@unbrained/pm-cli 2026.6.5 → 2026.6.7

package/dist/cli-bundle/chunks/{chunk-OIQIXTNB.js → chunk-KR6R465K.js}

@@ -1,9 +1,16 @@
+import {
+  normalizeExtensionNameForMatch,
+  normalizeManagedDirectoryName,
+  normalizeStringList,
+  parseExtensionManifest,
+  validateExtensionDirectory
+} from "./chunk-THDEID2Z.js";
 import {
   splitCommaList
 } from "./chunk-3HUE7XOF.js";
 import {
   nowIso
-} from "./chunk-RANZIID5.js";
+} from "./chunk-FHHBD7PN.js";
 import {
   EXIT_CODE,
   EXTENSION_CAPABILITY_CONTRACT,
@@ -22,118 +29,18 @@ import {
   resolvePmPackageRootFromModule,
   resolvePmRoot,
   writeSettings
-} from "./chunk-SRVKTWPR.js";
+} from "./chunk-UJUT6AHZ.js";
 
 // dist/cli/commands/extension.js
 import { execFile as execFile2 } from "node:child_process";
-import fs7 from "node:fs/promises";
+import fs6 from "node:fs/promises";
 import os2 from "node:os";
-import path7 from "node:path";
+import path6 from "node:path";
 import { promisify as promisify2 } from "node:util";
 
-// dist/cli/commands/extension/shared.js
+// dist/cli/commands/extension/managed-state.js
 import fs from "node:fs/promises";
 import path from "node:path";
-!(function() {
-  try {
-    var e = "undefined" != typeof window ? window : "undefined" != typeof global ? global : "undefined" != typeof globalThis ? globalThis : "undefined" != typeof self ? self : {}, n = new e.Error().stack;
-    n && (e._sentryDebugIds = e._sentryDebugIds || {}, e._sentryDebugIds[n] = "cb831def-7a8a-55f8-85e2-7749a5591bfe");
-  } catch (e2) {
-  }
-})();
-var DEFAULT_EXTENSION_PRIORITY = 100;
-function normalizeStringList(values) {
-  return [...new Set(values.map((value) => value.trim()).filter((value) => value.length > 0))].sort((left, right) => left.localeCompare(right));
-}
-function normalizeExtensionNameForMatch(value) {
-  return value.trim().toLowerCase();
-}
-function normalizeManagedDirectoryName(name) {
-  const normalized = name.trim().toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
-  if (normalized.length === 0) {
-    throw new PmCliError("Extension manifest name must resolve to a non-empty directory name.", EXIT_CODE.USAGE);
-  }
-  if (normalized === "." || normalized === "..") {
-    throw new PmCliError('Extension manifest name must not resolve to "." or "..".', EXIT_CODE.USAGE);
-  }
-  return normalized;
-}
-function parseExtensionManifest(raw) {
-  if (typeof raw !== "object" || raw === null) {
-    return null;
-  }
-  const candidate = raw;
-  if (typeof candidate.name !== "string" || candidate.name.trim().length === 0) {
-    return null;
-  }
-  if (typeof candidate.version !== "string" || candidate.version.trim().length === 0) {
-    return null;
-  }
-  if (typeof candidate.entry !== "string" || candidate.entry.trim().length === 0) {
-    return null;
-  }
-  let priority = DEFAULT_EXTENSION_PRIORITY;
-  if (candidate.priority !== void 0 && candidate.priority !== null) {
-    if (typeof candidate.priority !== "number" || !Number.isInteger(candidate.priority)) {
-      return null;
-    }
-    priority = candidate.priority;
-  }
-  let capabilities = [];
-  if (candidate.capabilities !== void 0 && candidate.capabilities !== null) {
-    if (!Array.isArray(candidate.capabilities) || candidate.capabilities.some((value) => typeof value !== "string")) {
-      return null;
-    }
-    capabilities = normalizeStringList(candidate.capabilities.map((value) => String(value).toLowerCase()));
-  }
-  return {
-    name: candidate.name.trim(),
-    version: candidate.version.trim(),
-    entry: candidate.entry.trim(),
-    priority,
-    capabilities
-  };
-}
-async function isCanonicalPathWithinDirectory(directory, targetPath) {
-  const [resolvedDirectory, resolvedTargetPath] = await Promise.all([fs.realpath(directory), fs.realpath(targetPath)]);
-  return isPathWithinDirectory(resolvedDirectory, resolvedTargetPath);
-}
-async function validateExtensionDirectory(directory) {
-  const manifestPath = path.join(directory, "manifest.json");
-  if (!await pathExists(manifestPath)) {
-    throw new PmCliError(`Extension manifest is missing at "${manifestPath}".`, EXIT_CODE.USAGE);
-  }
-  let parsedManifest;
-  try {
-    parsedManifest = JSON.parse(await fs.readFile(manifestPath, "utf8"));
-  } catch (error) {
-    throw new PmCliError(`Failed to parse extension manifest at "${manifestPath}": ${error instanceof Error ? error.message : String(error)}`, EXIT_CODE.USAGE);
-  }
-  const manifest = parseExtensionManifest(parsedManifest);
-  if (!manifest) {
-    throw new PmCliError(`Extension manifest at "${manifestPath}" is invalid.`, EXIT_CODE.USAGE);
-  }
-  const entryPath = path.resolve(directory, manifest.entry);
-  if (!isPathWithinDirectory(directory, entryPath)) {
-    throw new PmCliError(`Extension entry "${manifest.entry}" resolves outside extension directory "${directory}".`, EXIT_CODE.USAGE);
-  }
-  if (!await pathExists(entryPath)) {
-    throw new PmCliError(`Extension entry file is missing at "${entryPath}".`, EXIT_CODE.USAGE);
-  }
-  if (!await isCanonicalPathWithinDirectory(directory, entryPath)) {
-    throw new PmCliError(`Extension entry "${manifest.entry}" resolves outside extension directory after symlink resolution.`, EXIT_CODE.USAGE);
-  }
-  return {
-    directory,
-    manifest_path: manifestPath,
-    entry_path: entryPath,
-    manifest
-  };
-}
-
-// dist/cli/commands/extension/managed-state.js
-import fs2 from "node:fs/promises";
-import path2 from "node:path";
 !(function() {
   try {
     var e = "undefined" != typeof window ? window : "undefined" != typeof global ? global : "undefined" != typeof globalThis ? globalThis : "undefined" != typeof self ? self : {}, n = new e.Error().stack;
@@ -144,7 +51,7 @@ import path2 from "node:path";
 var MANAGED_EXTENSION_STATE_FILENAME = ".managed-extensions.json";
 var MANAGED_EXTENSION_STATE_VERSION = 1;
 function resolveManagedExtensionStatePath(extensionsRoot) {
-  return path2.join(extensionsRoot, MANAGED_EXTENSION_STATE_FILENAME);
+  return path.join(extensionsRoot, MANAGED_EXTENSION_STATE_FILENAME);
 }
 function createEmptyManagedExtensionState() {
   return {
@@ -241,7 +148,7 @@ async function readManagedExtensionState(extensionsRoot) {
   const statePath = resolveManagedExtensionStatePath(extensionsRoot);
   const fallback = createEmptyManagedExtensionState();
   try {
-    const raw = await fs2.readFile(statePath, "utf8");
+    const raw = await fs.readFile(statePath, "utf8");
     const parsed = JSON.parse(raw);
     const normalized = normalizeManagedState(parsed);
     if (!normalized) {
@@ -273,8 +180,8 @@ async function writeManagedExtensionState(extensionsRoot, state) {
     updated_at: nowIso(),
     entries: sortManagedEntries(state.entries)
   };
-  await fs2.mkdir(extensionsRoot, { recursive: true });
-  await fs2.writeFile(statePath, `${JSON.stringify(normalized, null, 2)}
+  await fs.mkdir(extensionsRoot, { recursive: true });
+  await fs.writeFile(statePath, `${JSON.stringify(normalized, null, 2)}
 `, "utf8");
 }
 function upsertManagedEntry(state, entry) {
@@ -289,15 +196,15 @@ function upsertManagedEntry(state, entry) {
 
 // dist/cli/commands/extension/install-sources.js
 import { execFile } from "node:child_process";
-import fs4 from "node:fs/promises";
+import fs3 from "node:fs/promises";
 import os from "node:os";
-import path4 from "node:path";
+import path3 from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { promisify } from "node:util";
 
 // dist/core/packages/manifest.js
-import fs3 from "node:fs/promises";
-import path3 from "node:path";
+import fs2 from "node:fs/promises";
+import path2 from "node:path";
 !(function() {
   try {
     var e = "undefined" != typeof window ? window : "undefined" != typeof global ? global : "undefined" != typeof globalThis ? globalThis : "undefined" != typeof self ? self : {}, n = new e.Error().stack;
@@ -424,7 +331,7 @@ function normalizePackageCatalogMetadata(raw) {
   return Object.values(catalog).some((value) => value !== void 0) ? catalog : void 0;
 }
 async function readPmPackageManifest(packageRoot) {
-  const packageJsonPath = path3.join(packageRoot, "package.json");
+  const packageJsonPath = path2.join(packageRoot, "package.json");
   if (!await pathExists(packageJsonPath)) {
     return {
       source: "convention",
@@ -433,7 +340,7 @@ async function readPmPackageManifest(packageRoot) {
   }
   let parsed;
   try {
-    parsed = JSON.parse(await fs3.readFile(packageJsonPath, "utf8"));
+    parsed = JSON.parse(await fs2.readFile(packageJsonPath, "utf8"));
   } catch (error) {
     throw new PmCliError(`Failed to parse package manifest at "${packageJsonPath}": ${String(error)}`, EXIT_CODE.USAGE);
   }
@@ -464,21 +371,21 @@ async function listExtensionManifestDirectories(parentDirectory) {
   if (!await pathExists(parentDirectory)) {
     return [];
   }
-  const entries = await fs3.readdir(parentDirectory, { withFileTypes: true });
+  const entries = await fs2.readdir(parentDirectory, { withFileTypes: true });
   const candidates = [];
   for (const entry of entries) {
     if (!entry.isDirectory()) {
       continue;
     }
-    const directory = path3.join(parentDirectory, entry.name);
-    if (await pathExists(path3.join(directory, "manifest.json"))) {
+    const directory = path2.join(parentDirectory, entry.name);
+    if (await pathExists(path2.join(directory, "manifest.json"))) {
       candidates.push(directory);
     }
   }
   return candidates.sort((left, right) => left.localeCompare(right));
 }
 async function collectPackageExtensionDirectories(packageRoot) {
-  if (await pathExists(path3.join(packageRoot, "manifest.json"))) {
+  if (await pathExists(path2.join(packageRoot, "manifest.json"))) {
     return [packageRoot];
   }
   const manifest = await readPmPackageManifest(packageRoot);
@@ -488,11 +395,11 @@ async function collectPackageExtensionDirectories(packageRoot) {
     if (entry.includes("*") || entry.startsWith("!")) {
       throw new PmCliError(`Package extension entry "${entry}" uses a glob/exclusion pattern. pm package installs currently require concrete extension paths or directories.`, EXIT_CODE.USAGE);
     }
-    const absolute = path3.resolve(packageRoot, entry);
+    const absolute = path2.resolve(packageRoot, entry);
     if (!isPathWithinDirectory(packageRoot, absolute)) {
       throw new PmCliError(`Package extension entry "${entry}" resolves outside package root.`, EXIT_CODE.USAGE);
     }
-    if (await pathExists(path3.join(absolute, "manifest.json"))) {
+    if (await pathExists(path2.join(absolute, "manifest.json"))) {
       discovered.add(absolute);
       continue;
     }
@@ -502,7 +409,7 @@ async function collectPackageExtensionDirectories(packageRoot) {
   }
   if (manifestEntries.length === 0) {
     for (const root of PM_PACKAGE_CONVENTIONAL_RESOURCE_ROOTS.extensions) {
-      for (const child of await listExtensionManifestDirectories(path3.join(packageRoot, root))) {
+      for (const child of await listExtensionManifestDirectories(path2.join(packageRoot, root))) {
         discovered.add(child);
       }
     }
@@ -514,7 +421,7 @@ async function collectPackageExtensionDirectories(packageRoot) {
 !(function() {
   try {
     var e = "undefined" != typeof window ? window : "undefined" != typeof global ? global : "undefined" != typeof globalThis ? globalThis : "undefined" != typeof self ? self : {}, n = new e.Error().stack;
-    n && (e._sentryDebugIds = e._sentryDebugIds || {}, e._sentryDebugIds[n] = "eaa543ef-b644-5b26-9eb4-dcb40aaa8a53");
+    n && (e._sentryDebugIds = e._sentryDebugIds || {}, e._sentryDebugIds[n] = "2ced78c7-c9de-52cc-ad20-81a4028eb89d");
   } catch (e2) {
   }
 })();
@@ -610,7 +517,7 @@ function parseExtensionInstallSource(input, options = {}) {
   return {
     kind: "local",
     input: normalizedInput,
-    absolute_path: path4.resolve(process.cwd(), normalizedInput)
+    absolute_path: path3.resolve(process.cwd(), normalizedInput)
   };
 }
 async function runGitCommand(args) {
@@ -642,9 +549,77 @@ async function runNpmCommand(args, cwd) {
 ${message}`, EXIT_CODE.GENERIC_FAILURE);
   }
 }
+function npmPackageNameFromSpec(spec) {
+  const trimmed = spec.trim();
+  const withoutAlias = trimmed.includes("@file:") ? trimmed.slice(0, trimmed.lastIndexOf("@file:")) : trimmed;
+  if (withoutAlias.startsWith("@")) {
+    const scoped = withoutAlias.match(/^(@[^/@\s]+\/[^/@\s]+)/);
+    return scoped?.[1] ?? withoutAlias;
+  }
+  const unscoped = withoutAlias.match(/^([^/@\s]+)/);
+  return unscoped?.[1] ?? withoutAlias;
+}
+function isNpmNotFoundError(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  const normalized = message.toLowerCase();
+  return normalized.includes("npm err! code e404") || normalized.includes("404 not found") || normalized.includes("is not in this registry");
+}
+function isNpmPackNotFoundError(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  const normalized = message.toLowerCase();
+  return isNpmNotFoundError(error) || normalized.includes("not found");
+}
+function isFirstPartyPmPackageName(packageName) {
+  const normalized = packageName.trim().toLowerCase();
+  return normalized.startsWith("@unbrained/pm-") || normalized.startsWith("pm-");
+}
+function buildNpmNotFoundRecovery(spec) {
+  const packageName = npmPackageNameFromSpec(spec);
+  const isFirstPartyPackage = isFirstPartyPmPackageName(packageName);
+  const repoName = packageName.split("/").at(-1) ?? packageName;
+  const githubSource = isFirstPartyPackage ? `github.com/unbraind/${repoName}` : void 0;
+  const nextBestCommand = githubSource ? `pm install --project ${githubSource}` : void 0;
+  return {
+    message: isFirstPartyPackage ? `npm package "${spec}" was not found in the registry. If this is an unpublished first-party pm package, install its GitHub repository instead.` : `npm package "${spec}" was not found in the registry.`,
+    context: {
+      code: "npm_package_not_found",
+      required: "Use an install source that exists, or publish the npm package before installing it with npm:<name>.",
+      why: "Classifying npm 404s avoids repeated registry retries and gives agents a deterministic fallback path.",
+      examples: nextBestCommand ? [nextBestCommand, `pm package catalog --project --json`] : [`npm view ${packageName}`, `pm package catalog --project --json`],
+      nextSteps: nextBestCommand ? [
+        `Try ${nextBestCommand} if the repository exists.`,
+        "Use pm package catalog --project --json to inspect bundled package aliases before installing."
+      ] : [
+        `Verify ${packageName} exists in the npm registry and that you have access to it.`,
+        "Use pm package catalog --project --json to inspect bundled package aliases before installing."
+      ],
+      recovery: {
+        attempted_command: `pm install --project npm:${spec}`,
+        normalized_args: ["install", "--project", `npm:${spec}`],
+        ...githubSource && nextBestCommand ? {
+          fallback_candidates: [
+            {
+              source: githubSource,
+              command: nextBestCommand,
+              reason: "canonical first-party GitHub repository fallback for unpublished pm packages"
+            }
+          ],
+          next_best_command: nextBestCommand
+        } : {}
+      }
+    }
+  };
+}
+function wrapNpmPackResolutionError(spec, error) {
+  if (!isNpmPackNotFoundError(error)) {
+    return null;
+  }
+  const recovery = buildNpmNotFoundRecovery(spec);
+  return new PmCliError(recovery.message, EXIT_CODE.NOT_FOUND, recovery.context);
+}
 async function resolveLocalNpmPackagePath(spec) {
-  if (path4.isAbsolute(spec) || spec.startsWith(".") || spec.startsWith("..")) {
-    const absolutePath = path4.resolve(process.cwd(), spec);
+  if (path3.isAbsolute(spec) || spec.startsWith(".") || spec.startsWith("..")) {
+    const absolutePath = path3.resolve(process.cwd(), spec);
     return await pathExists(absolutePath) ? absolutePath : null;
   }
   try {
@@ -656,7 +631,7 @@ async function resolveLocalNpmPackagePath(spec) {
   } catch {
   }
   if (!/^[a-z][a-z0-9+.-]*:/i.test(spec)) {
-    const absolutePath = path4.resolve(process.cwd(), spec);
+    const absolutePath = path3.resolve(process.cwd(), spec);
     if (await pathExists(absolutePath)) {
       return absolutePath;
     }
@@ -688,7 +663,7 @@ function normalizeNpmLocalFileAliasSpec(spec, cwd = process.cwd()) {
   if (packageName.trim().length === 0 || target.trim().length === 0 || target.startsWith("//")) {
     return spec;
   }
-  const absolutePath = path4.isAbsolute(target) || path4.win32.isAbsolute(target) ? target : path4.resolve(cwd, target);
+  const absolutePath = path3.isAbsolute(target) || path3.win32.isAbsolute(target) ? target : path3.resolve(cwd, target);
   return `${packageName}@${pathToFileURL(absolutePath).href}`;
 }
 function parsePackedNpmPackage(stdout, packDirectory) {
@@ -697,7 +672,7 @@ function parsePackedNpmPackage(stdout, packDirectory) {
     const first = Array.isArray(parsed) ? parsed[0] : void 0;
     if (first && typeof first.filename === "string" && first.filename.trim().length > 0) {
       return {
-        tarball: path4.resolve(packDirectory, first.filename),
+        tarball: path3.resolve(packDirectory, first.filename),
         package: typeof first.name === "string" ? first.name : void 0,
         version: typeof first.version === "string" ? first.version : void 0
       };
@@ -709,14 +684,14 @@ function parsePackedNpmPackage(stdout, packDirectory) {
     throw new PmCliError("npm pack did not report a tarball filename.", EXIT_CODE.GENERIC_FAILURE);
   }
   return {
-    tarball: path4.resolve(packDirectory, lastLine)
+    tarball: path3.resolve(packDirectory, lastLine)
   };
 }
 async function resolveNpmSourceDirectory(source) {
   const localPackageRoot = await resolveLocalNpmPackagePath(source.spec);
   if (localPackageRoot) {
-    const packageJsonPath = path4.join(localPackageRoot, "package.json");
-    const packageJson = await pathExists(packageJsonPath) ? JSON.parse(await fs4.readFile(packageJsonPath, "utf8")) : {};
+    const packageJsonPath = path3.join(localPackageRoot, "package.json");
+    const packageJson = await pathExists(packageJsonPath) ? JSON.parse(await fs3.readFile(packageJsonPath, "utf8")) : {};
     return {
       directory: await resolvePackageExtensionDirectory(localPackageRoot, source.input),
       package: typeof packageJson.name === "string" ? packageJson.name : void 0,
@@ -725,17 +700,17 @@ async function resolveNpmSourceDirectory(source) {
       }
     };
   }
-  const tempRoot = await fs4.mkdtemp(path4.join(os.tmpdir(), "pm-npm-package-source-"));
-  const packDirectory = path4.join(tempRoot, "pack");
-  const extractDirectory = path4.join(tempRoot, "extract");
-  await fs4.mkdir(packDirectory, { recursive: true });
-  await fs4.mkdir(extractDirectory, { recursive: true });
+  const tempRoot = await fs3.mkdtemp(path3.join(os.tmpdir(), "pm-npm-package-source-"));
+  const packDirectory = path3.join(tempRoot, "pack");
+  const extractDirectory = path3.join(tempRoot, "extract");
+  await fs3.mkdir(packDirectory, { recursive: true });
+  await fs3.mkdir(extractDirectory, { recursive: true });
   try {
     const packSpec = await resolveNpmPackSpec(source.spec);
     const packStdout = await runNpmCommand(["pack", packSpec, "--json", "--pack-destination", packDirectory]);
     const packed = parsePackedNpmPackage(packStdout, packDirectory);
     await execFileAsync("tar", ["-xzf", packed.tarball, "-C", extractDirectory], { encoding: "utf8" });
-    const packageRoot = path4.join(extractDirectory, "package");
+    const packageRoot = path3.join(extractDirectory, "package");
     await installNpmPackageRuntimeDependencies(packageRoot);
     const directory = await resolvePackageExtensionDirectory(packageRoot, source.input);
     return {
@@ -743,22 +718,26 @@ async function resolveNpmSourceDirectory(source) {
       package: packed.package,
       version: packed.version,
       cleanup: async () => {
-        await fs4.rm(tempRoot, { recursive: true, force: true });
+        await fs3.rm(tempRoot, { recursive: true, force: true });
       }
     };
   } catch (error) {
-    await fs4.rm(tempRoot, { recursive: true, force: true });
+    await fs3.rm(tempRoot, { recursive: true, force: true });
+    const wrappedError = wrapNpmPackResolutionError(source.spec, error);
+    if (wrappedError) {
+      throw wrappedError;
+    }
     throw error;
   }
 }
 async function installNpmPackageRuntimeDependencies(packageRoot) {
-  const packageJsonPath = path4.join(packageRoot, "package.json");
+  const packageJsonPath = path3.join(packageRoot, "package.json");
   if (!await pathExists(packageJsonPath)) {
     return;
   }
   let parsed;
   try {
-    parsed = JSON.parse(await fs4.readFile(packageJsonPath, "utf8"));
+    parsed = JSON.parse(await fs3.readFile(packageJsonPath, "utf8"));
   } catch {
     return;
   }
@@ -772,11 +751,11 @@ async function installNpmPackageRuntimeDependencies(packageRoot) {
   }
   const runtimeOnlyManifest = { ...parsed };
   delete runtimeOnlyManifest.devDependencies;
-  await fs4.writeFile(packageJsonPath, `${JSON.stringify(runtimeOnlyManifest, null, 2)}
+  await fs3.writeFile(packageJsonPath, `${JSON.stringify(runtimeOnlyManifest, null, 2)}
 `, "utf8");
   await Promise.all([
-    fs4.rm(path4.join(packageRoot, "package-lock.json"), { force: true }),
-    fs4.rm(path4.join(packageRoot, "npm-shrinkwrap.json"), { force: true })
+    fs3.rm(path3.join(packageRoot, "package-lock.json"), { force: true }),
+    fs3.rm(path3.join(packageRoot, "npm-shrinkwrap.json"), { force: true })
   ]);
   await runNpmCommand(["install", "--ignore-scripts", "--no-audit", "--fund=false", "--package-lock=false", "--no-save", ...dependencySpecs], packageRoot);
 }
@@ -801,7 +780,7 @@ async function resolvePackageExtensionDirectory(packageRoot, sourceLabel) {
     return discovered[0];
   }
   if (discovered.length > 1) {
-    const choices = discovered.map((entry) => path4.relative(packageRoot, entry).replaceAll(path4.sep, "/")).sort((left, right) => left.localeCompare(right));
+    const choices = discovered.map((entry) => path3.relative(packageRoot, entry).replaceAll(path3.sep, "/")).sort((left, right) => left.localeCompare(right));
     throw new PmCliError(`Package source "${sourceLabel}" contains multiple extension manifests. Provide an explicit extension path. Candidates: ${choices.join(", ")}`, EXIT_CODE.USAGE);
   }
   throw new PmCliError(`Unable to locate a pm extension manifest in package source "${sourceLabel}". Package installs currently activate only extension resources, so add package.json pm.extensions or an extensions/ directory. Metadata-only resources like pm.docs/pm.examples are catalog metadata and do not activate commands.`, EXIT_CODE.USAGE);
@@ -810,33 +789,33 @@ async function resolveGithubSourceDirectory(cloneDirectory, source) {
   const candidatePaths = [];
   if (source.subpath) {
     candidatePaths.push(source.subpath);
-    candidatePaths.push(path4.posix.join(".agents/pm/extensions", source.subpath));
-    candidatePaths.push(path4.posix.join(".custom/pm-extensions", source.subpath));
-    candidatePaths.push(path4.posix.join(".custom/pm-extension", source.subpath));
+    candidatePaths.push(path3.posix.join(".agents/pm/extensions", source.subpath));
+    candidatePaths.push(path3.posix.join(".custom/pm-extensions", source.subpath));
+    candidatePaths.push(path3.posix.join(".custom/pm-extension", source.subpath));
   }
   for (const candidate of candidatePaths) {
-    const absolute = path4.resolve(cloneDirectory, candidate);
+    const absolute = path3.resolve(cloneDirectory, candidate);
     if (!isPathWithinDirectory(cloneDirectory, absolute)) {
       continue;
     }
-    if (await pathExists(path4.join(absolute, "manifest.json"))) {
+    if (await pathExists(path3.join(absolute, "manifest.json"))) {
       return { directory: absolute, resolved_subpath: candidate };
     }
   }
-  if (await pathExists(path4.join(cloneDirectory, "manifest.json"))) {
+  if (await pathExists(path3.join(cloneDirectory, "manifest.json"))) {
     return { directory: cloneDirectory, resolved_subpath: "." };
   }
   const discoveredDirectory = await resolvePackageExtensionDirectory(cloneDirectory, source.input);
   return {
     directory: discoveredDirectory,
-    resolved_subpath: path4.relative(cloneDirectory, discoveredDirectory).replaceAll(path4.sep, "/")
+    resolved_subpath: path3.relative(cloneDirectory, discoveredDirectory).replaceAll(path3.sep, "/")
   };
 }
 async function resolveInstallSource(source) {
   if (source.kind === "local") {
     let localStats;
     try {
-      localStats = await fs4.stat(source.absolute_path);
+      localStats = await fs3.stat(source.absolute_path);
     } catch {
       throw new PmCliError(`Local extension source does not exist: "${source.absolute_path}".`, EXIT_CODE.NOT_FOUND);
     }
@@ -855,12 +834,12 @@ async function resolveInstallSource(source) {
       source,
       directory: resolved.directory,
       cleanup: resolved.cleanup,
-      resolved_subpath: path4.relative(path4.dirname(resolved.directory), resolved.directory).replaceAll(path4.sep, "/"),
+      resolved_subpath: path3.relative(path3.dirname(resolved.directory), resolved.directory).replaceAll(path3.sep, "/"),
       npm_package: resolved.package,
       npm_version: resolved.version
     };
   }
-  const cloneDirectory = await fs4.mkdtemp(path4.join(os.tmpdir(), "pm-extension-source-"));
+  const cloneDirectory = await fs3.mkdtemp(path3.join(os.tmpdir(), "pm-extension-source-"));
   const cloneArgs = ["clone", "--depth", "1"];
   if (source.ref) {
     cloneArgs.push("--branch", source.ref);
@@ -876,11 +855,11 @@ async function resolveInstallSource(source) {
       resolved_subpath: resolved.resolved_subpath,
       commit,
       cleanup: async () => {
-        await fs4.rm(cloneDirectory, { recursive: true, force: true });
+        await fs3.rm(cloneDirectory, { recursive: true, force: true });
       }
     };
   } catch (error) {
-    await fs4.rm(cloneDirectory, { recursive: true, force: true });
+    await fs3.rm(cloneDirectory, { recursive: true, force: true });
     throw error;
   }
 }
@@ -888,13 +867,13 @@ async function areDirectoriesEquivalent(left, right) {
   if (!await pathExists(left) || !await pathExists(right)) {
     return false;
   }
-  const [leftRealPath, rightRealPath] = await Promise.all([fs4.realpath(left), fs4.realpath(right)]);
+  const [leftRealPath, rightRealPath] = await Promise.all([fs3.realpath(left), fs3.realpath(right)]);
   return leftRealPath === rightRealPath;
 }
 
 // dist/cli/commands/extension/bundled-catalog.js
-import fs5 from "node:fs/promises";
-import path5 from "node:path";
+import fs4 from "node:fs/promises";
+import path4 from "node:path";
 !(function() {
   try {
     var e = "undefined" != typeof window ? window : "undefined" != typeof global ? global : "undefined" != typeof globalThis ? globalThis : "undefined" != typeof self ? self : {}, n = new e.Error().stack;
@@ -918,7 +897,7 @@ function resolvePackageRootCandidates() {
   const candidates = [];
   const envRoot = process.env[PM_PACKAGE_ROOT_ENV];
   if (typeof envRoot === "string" && envRoot.trim().length > 0) {
-    candidates.push(path5.resolve(envRoot.trim()));
+    candidates.push(path4.resolve(envRoot.trim()));
   }
   candidates.push(resolvePmPackageRootFromModule(import.meta.url, ["../../../.."]));
   return [...new Set(candidates)];
@@ -934,8 +913,8 @@ async function resolveBundledExtensionAliasSource(input) {
     return null;
   }
   for (const packageRoot2 of resolvePackageRootCandidates()) {
-    const legacyExtensionPath = path5.join(packageRoot2, ".agents", "pm", "extensions", alias.legacy_extension_directory);
-    if (await pathExists(path5.join(legacyExtensionPath, "manifest.json"))) {
+    const legacyExtensionPath = path4.join(packageRoot2, ".agents", "pm", "extensions", alias.legacy_extension_directory);
+    if (await pathExists(path4.join(legacyExtensionPath, "manifest.json"))) {
       return legacyExtensionPath;
     }
   }
@@ -950,17 +929,17 @@ function derivePackageAlias(packageDirectory) {
 async function collectBundledPackageEntries() {
   const entriesByAlias = /* @__PURE__ */ new Map();
   for (const packageRoot of resolvePackageRootCandidates()) {
-    const packagesRoot = path5.join(packageRoot, "packages");
+    const packagesRoot = path4.join(packageRoot, "packages");
     if (!await pathExists(packagesRoot)) {
       continue;
     }
-    const entries = await fs5.readdir(packagesRoot, { withFileTypes: true });
+    const entries = await fs4.readdir(packagesRoot, { withFileTypes: true });
     for (const entry of entries) {
       if (!entry.isDirectory() || !entry.name.startsWith("pm-")) {
         continue;
       }
-      const candidateRoot = path5.join(packagesRoot, entry.name);
-      if (!await pathExists(path5.join(candidateRoot, "package.json"))) {
+      const candidateRoot = path4.join(packagesRoot, entry.name);
+      if (!await pathExists(path4.join(candidateRoot, "package.json"))) {
         continue;
       }
       const manifest = await readPmPackageManifest(candidateRoot);
@@ -983,8 +962,8 @@ async function collectBundledPackageEntries() {
       continue;
     }
     for (const packageRoot of resolvePackageRootCandidates()) {
-      const packagePath = path5.join(packageRoot, "packages", legacy.package_directory);
-      if (await pathExists(path5.join(packagePath, "package.json"))) {
+      const packagePath = path4.join(packageRoot, "packages", legacy.package_directory);
+      if (await pathExists(path4.join(packagePath, "package.json"))) {
         entriesByAlias.set(alias, {
           alias,
           package_directory: legacy.package_directory,
@@ -1024,7 +1003,7 @@ async function buildBundledPackageCatalog(scope, global2, options = {}) {
   const roots = resolveExtensionRoots(resolvePmRoot(process.cwd(), global2.path), process.cwd());
   const selectedRoot = scope === "global" ? roots.global : roots.project;
   const managedStateRead = await readManagedExtensionState(selectedRoot);
-  const installedLocations = new Set(managedStateRead.state.entries.filter((entry) => entry.scope === scope).filter((entry) => entry.source.kind !== "builtin").map((entry) => path5.resolve(entry.source.location)));
+  const installedLocations = new Set(managedStateRead.state.entries.filter((entry) => entry.scope === scope).filter((entry) => entry.source.kind !== "builtin").map((entry) => path4.resolve(entry.source.location)));
   const installedBuiltinAliases = new Set(managedStateRead.state.entries.filter((entry) => entry.scope === scope && entry.source.kind === "builtin").flatMap((entry) => [entry.source.name, entry.source.input, entry.source.location]).filter((value) => typeof value === "string" && value.trim().length > 0).map((value) => value.trim().toLowerCase()));
   const packages = [];
   for (const alias of await listBundledPackageAliases()) {
@@ -1051,7 +1030,7 @@ async function buildBundledPackageCatalog(scope, global2, options = {}) {
       alias,
       bundled: true,
       available: true,
-      installed: installedBuiltinAliases.has(alias) || installedLocations.has(path5.resolve(packageRoot)),
+      installed: installedBuiltinAliases.has(alias) || installedLocations.has(path4.resolve(packageRoot)),
       install_target: alias,
       install_command: `pm install ${alias} ${installScopeFlag}`,
       package_name: manifest.package_name,
@@ -1139,8 +1118,8 @@ function projectPackageCatalogEntry(entry, fields) {
 }
 
 // dist/cli/commands/extension/scaffold.js
-import fs6 from "node:fs/promises";
-import path6 from "node:path";
+import fs5 from "node:fs/promises";
+import path5 from "node:path";
 !(function() {
   try {
     var e = "undefined" != typeof window ? window : "undefined" != typeof global ? global : "undefined" != typeof globalThis ? globalThis : "undefined" != typeof self ? self : {}, n = new e.Error().stack;
@@ -1277,33 +1256,33 @@ function buildStarterExtensionScaffoldFiles(extensionName, commandName, vocabula
 }
 async function scaffoldExtensionProject(target, vocabulary = "extension") {
   const normalizedTarget = target.trim();
-  const targetPath = path6.resolve(process.cwd(), normalizedTarget);
-  const extensionName = normalizeManagedDirectoryName(path6.basename(targetPath));
+  const targetPath = path5.resolve(process.cwd(), normalizedTarget);
+  const extensionName = normalizeManagedDirectoryName(path5.basename(targetPath));
   const commandName = `${extensionName} ping`;
   const scaffoldFiles = buildStarterExtensionScaffoldFiles(extensionName, commandName, vocabulary);
   let createdDirectory = false;
   if (await pathExists(targetPath)) {
-    const existingTargetStats = await fs6.stat(targetPath);
+    const existingTargetStats = await fs5.stat(targetPath);
     if (!existingTargetStats.isDirectory()) {
       throw new PmCliError(`Scaffold target "${targetPath}" exists and is not a directory.`, EXIT_CODE.CONFLICT);
     }
   } else {
-    await fs6.mkdir(targetPath, { recursive: true });
+    await fs5.mkdir(targetPath, { recursive: true });
     createdDirectory = true;
   }
   for (const [relativePath, content] of Object.entries(scaffoldFiles)) {
-    const absolutePath = path6.join(targetPath, relativePath);
+    const absolutePath = path5.join(targetPath, relativePath);
     if (!await pathExists(absolutePath)) {
       continue;
     }
-    const existingContent = await fs6.readFile(absolutePath, "utf8");
+    const existingContent = await fs5.readFile(absolutePath, "utf8");
     if (existingContent !== content) {
       throw new PmCliError(`Scaffold file "${relativePath}" already exists with different content in "${targetPath}". Choose a new target path or remove conflicting files.`, EXIT_CODE.CONFLICT);
     }
   }
   const files = [];
   for (const [relativePath, content] of Object.entries(scaffoldFiles)) {
-    const absolutePath = path6.join(targetPath, relativePath);
+    const absolutePath = path5.join(targetPath, relativePath);
     if (await pathExists(absolutePath)) {
       files.push({
         path: relativePath,
@@ -1311,8 +1290,8 @@ async function scaffoldExtensionProject(target, vocabulary = "extension") {
       });
       continue;
     }
-    await fs6.mkdir(path6.dirname(absolutePath), { recursive: true });
-    await fs6.writeFile(absolutePath, content, "utf8");
+    await fs5.mkdir(path5.dirname(absolutePath), { recursive: true });
+    await fs5.writeFile(absolutePath, content, "utf8");
     files.push({
       path: relativePath,
       status: "created"
@@ -1331,7 +1310,7 @@ async function scaffoldExtensionProject(target, vocabulary = "extension") {
 !(function() {
   try {
     var e = "undefined" != typeof window ? window : "undefined" != typeof global ? global : "undefined" != typeof globalThis ? globalThis : "undefined" != typeof self ? self : {}, n = new e.Error().stack;
-    n && (e._sentryDebugIds = e._sentryDebugIds || {}, e._sentryDebugIds[n] = "2c378b79-515a-5ad7-a807-9ab870e2d33d");
+    n && (e._sentryDebugIds = e._sentryDebugIds || {}, e._sentryDebugIds[n] = "bda44a9b-2e9f-5654-851d-eac3d5c6c094");
   } catch (e2) {
   }
 })();
@@ -1473,6 +1452,7 @@ function parseRegistrationCollisionWarning(warning) {
   }
   return {
     code,
+    surface: parts.slice(1, -4).join(":") || "global",
     winner: { layer: winnerLayer, name: winnerName },
     displaced: { layer: displacedLayer, name: displacedName }
   };
@@ -1498,6 +1478,58 @@ function buildRegistrationCollisionRemediation(warnings, commands) {
   const collisionNameText = collisionNames.length > 0 ? ` Conflicting extensions: ${collisionNames.join(", ")}.` : "";
   return `Extension registration collisions or handler/override overlaps detected.${collisionNameText} Single-winner surfaces can hide earlier package behavior. Deactivate one conflicting package with ${commands.deactivate}, or scope registration surfaces in extensions.policy.extension_overrides, then rerun ${commands.doctor}.`;
 }
+function buildRegistrationCollisionPlan(scope, warnings, extensions, options) {
+  const collisions = warnings.map((warning) => parseRegistrationCollisionWarning(warning)).filter((entry) => entry !== null).sort((left, right) => `${left.code}:${left.surface}:${left.winner.name}:${left.displaced.name}`.localeCompare(`${right.code}:${right.surface}:${right.winner.name}:${right.displaced.name}`));
+  if (collisions.length === 0) {
+    return void 0;
+  }
+  const scopeFlag = scope === "global" ? "--global" : "--project";
+  const deactivatePrefix = lifecycleFlagCommand(options, "deactivate");
+  const doctorCommand = `${lifecycleFlagCommand(options, "doctor")} ${scopeFlag} --detail deep --trace`;
+  const extensionByName = new Map(extensions.map((entry) => [normalizeExtensionNameForMatch(entry.name), entry]));
+  const affectedByName = /* @__PURE__ */ new Map();
+  for (const collision of collisions) {
+    for (const name of [collision.winner.name, collision.displaced.name]) {
+      const normalizedName = normalizeExtensionNameForMatch(name);
+      affectedByName.set(normalizedName, (affectedByName.get(normalizedName) ?? 0) + 1);
+    }
+  }
+  const remediationCandidates = [...affectedByName.entries()].map(([normalizedName, affectedCollisions]) => {
+    const extension = extensionByName.get(normalizedName);
+    const extensionName = extension?.name ?? normalizedName;
+    const commandPaths = extension?.command_paths ?? [];
+    const actionPaths = extension?.action_paths ?? [];
+    return {
+      action: "deactivate",
+      extension: extensionName,
+      command: `${deactivatePrefix} ${extensionName} ${scopeFlag}`,
+      affected_collisions: affectedCollisions,
+      feature_loss: {
+        command_paths: [...commandPaths].sort((left, right) => left.localeCompare(right)),
+        action_paths: [...actionPaths].sort((left, right) => left.localeCompare(right))
+      }
+    };
+  }).sort((left, right) => {
+    const affectedDelta = right.affected_collisions - left.affected_collisions;
+    if (affectedDelta !== 0) {
+      return affectedDelta;
+    }
+    const leftSurfaceCount = left.feature_loss.command_paths.length + left.feature_loss.action_paths.length;
+    const rightSurfaceCount = right.feature_loss.command_paths.length + right.feature_loss.action_paths.length;
+    if (leftSurfaceCount !== rightSurfaceCount) {
+      return leftSurfaceCount - rightSurfaceCount;
+    }
+    return left.extension.localeCompare(right.extension);
+  });
+  return {
+    status: "conflicts_detected",
+    collision_count: collisions.length,
+    extension_count: affectedByName.size,
+    next_best_command: doctorCommand,
+    collisions,
+    remediation_candidates: remediationCandidates
+  };
+}
 function classifyDoctorLoadFailureWarnings(loadFailures) {
   const warnings = [];
   for (const failure of loadFailures) {
@@ -1600,6 +1632,7 @@ function buildExtensionTriageSummary(scope, warnings, extensions, options = {})
       remediation.push("Extension governance policy warnings detected. Review settings.extensions.policy mode and allow/block lists to confirm intended capabilities and registration surfaces.");
     }
   }
+  const collisionPlan = buildRegistrationCollisionPlan(scope, normalizedWarnings, extensions, options);
   if (updateHealthPartial) {
     remediation.push(`Update-check coverage is partial because unmanaged extensions need adoption. Adopt existing installs via ${lifecycleFlagCommand(options, "manage")} ${scopeFlag} --fix-managed-state (or ${lifecycleFlagCommand(options, "adopt-all")} ${scopeFlag}, ${lifecycleFlagCommand(options, "adopt")} <name> ${scopeFlag}, or reinstall via ${lifecycleFlagCommand(options, "install")} ${scopeFlag} <source>).`);
   } else if (skippedUnmanagedTotal > 0) {
@@ -1638,7 +1671,8 @@ function buildExtensionTriageSummary(scope, warnings, extensions, options = {})
     update_check_status_totals: updateCheckStatusTotals,
     update_check_failed_total: updateCheckFailedTotal,
     top_warnings: effectiveWarnings.slice(0, 8),
-    remediation
+    remediation,
+    ...collisionPlan ? { collision_plan: collisionPlan } : {}
   };
 }
 function parseDoctorDetailMode(raw) {
@@ -1734,7 +1768,7 @@ function buildDoctorConsistencySummary(scope, installedExtensions, loadedExtensi
 !(function() {
   try {
     var e = "undefined" != typeof window ? window : "undefined" != typeof global ? global : "undefined" != typeof globalThis ? globalThis : "undefined" != typeof self ? self : {}, n = new e.Error().stack;
-    n && (e._sentryDebugIds = e._sentryDebugIds || {}, e._sentryDebugIds[n] = "120f378d-34a8-5b2f-ab24-f056fb646d43");
+    n && (e._sentryDebugIds = e._sentryDebugIds || {}, e._sentryDebugIds[n] = "efb7ee07-3564-5722-a520-fcc45e7dbc3c");
   } catch (e2) {
   }
 })();
@@ -1814,11 +1848,11 @@ function sleep(ms) {
     setTimeout(resolve, ms);
   });
 }
-async function copyExtensionDirectoryForInstall(sourceDirectory, destinationDirectory, copyDirectory = fs7.cp) {
+async function copyExtensionDirectoryForInstall(sourceDirectory, destinationDirectory, copyDirectory = fs6.cp) {
   for (let attempt = 1; attempt <= EXTENSION_INSTALL_COPY_ATTEMPTS; attempt += 1) {
     try {
       if (await pathExists(destinationDirectory)) {
-        await fs7.rm(destinationDirectory, { recursive: true, force: true });
+        await fs6.rm(destinationDirectory, { recursive: true, force: true });
       }
       await copyExtensionDirectoryWithoutSelfNesting(sourceDirectory, destinationDirectory, copyDirectory);
       return;
@@ -1831,8 +1865,8 @@ async function copyExtensionDirectoryForInstall(sourceDirectory, destinationDire
   }
 }
 async function copyExtensionDirectoryWithoutSelfNesting(sourceDirectory, destinationDirectory, copyDirectory) {
-  const resolvedSource = path7.resolve(sourceDirectory);
-  const resolvedDestination = path7.resolve(destinationDirectory);
+  const resolvedSource = path6.resolve(sourceDirectory);
+  const resolvedDestination = path6.resolve(destinationDirectory);
   if (resolvedSource === resolvedDestination) {
     return;
   }
@@ -1840,34 +1874,34 @@ async function copyExtensionDirectoryWithoutSelfNesting(sourceDirectory, destina
     await copyDirectory(sourceDirectory, destinationDirectory, { recursive: true, force: true });
     return;
   }
-  const stagingRoot = await fs7.mkdtemp(path7.join(os2.tmpdir(), "pm-extension-copy-"));
-  const stagedDirectory = path7.join(stagingRoot, "extension");
+  const stagingRoot = await fs6.mkdtemp(path6.join(os2.tmpdir(), "pm-extension-copy-"));
+  const stagedDirectory = path6.join(stagingRoot, "extension");
   try {
     await copyDirectory(sourceDirectory, stagedDirectory, { recursive: true, force: true });
     await copyDirectory(stagedDirectory, destinationDirectory, { recursive: true, force: true });
   } finally {
-    await fs7.rm(stagingRoot, { recursive: true, force: true });
+    await fs6.rm(stagingRoot, { recursive: true, force: true });
   }
 }
 async function withExtensionInstallLock(settingsRoot, destinationDirectoryName, run) {
-  const lockRoot = path7.join(settingsRoot, "runtime", "extension-install-locks");
-  const lockPath = path7.join(lockRoot, `${destinationDirectoryName}.lock`);
-  await fs7.mkdir(lockRoot, { recursive: true });
+  const lockRoot = path6.join(settingsRoot, "runtime", "extension-install-locks");
+  const lockPath = path6.join(lockRoot, `${destinationDirectoryName}.lock`);
+  await fs6.mkdir(lockRoot, { recursive: true });
   let acquired = false;
   for (let attempt = 1; attempt <= EXTENSION_INSTALL_LOCK_ATTEMPTS; attempt += 1) {
     try {
-      await fs7.mkdir(lockPath);
+      await fs6.mkdir(lockPath);
       acquired = true;
-      await fs7.writeFile(path7.join(lockPath, "owner.json"), `${JSON.stringify({ pid: process.pid, created_at: nowIso(), destination: destinationDirectoryName }, null, 2)}
+      await fs6.writeFile(path6.join(lockPath, "owner.json"), `${JSON.stringify({ pid: process.pid, created_at: nowIso(), destination: destinationDirectoryName }, null, 2)}
 `, "utf8");
       break;
     } catch (error) {
       if (!isErrnoCode(error, "EEXIST")) {
         throw error;
       }
-      const stat = await fs7.stat(lockPath).catch(() => null);
+      const stat = await fs6.stat(lockPath).catch(() => null);
       if (stat && Date.now() - stat.mtimeMs > EXTENSION_INSTALL_LOCK_STALE_MS) {
-        await fs7.rm(lockPath, { recursive: true, force: true });
+        await fs6.rm(lockPath, { recursive: true, force: true });
         continue;
       }
       await sleep(EXTENSION_INSTALL_LOCK_DELAY_MS);
@@ -1879,7 +1913,7 @@ async function withExtensionInstallLock(settingsRoot, destinationDirectoryName,
   try {
     return await run();
   } finally {
-    await fs7.rm(lockPath, { recursive: true, force: true }).catch(() => void 0);
+    await fs6.rm(lockPath, { recursive: true, force: true }).catch(() => void 0);
   }
 }
 async function resolveInstalledExtensionCandidate(installed, extensionTarget) {
@@ -2057,7 +2091,7 @@ async function listInstalledExtensions(extensionsRoot, scope, settings, state) {
       warnings: []
     };
   }
-  const entries = await fs7.readdir(extensionsRoot, { withFileTypes: true });
+  const entries = await fs6.readdir(extensionsRoot, { withFileTypes: true });
   const directories = entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort((left, right) => left.localeCompare(right));
   const managedByName = /* @__PURE__ */ new Map();
   const managedByDirectory = /* @__PURE__ */ new Map();
@@ -2068,8 +2102,8 @@ async function listInstalledExtensions(extensionsRoot, scope, settings, state) {
   const warnings = [];
   const summaries = [];
   for (const directoryName of directories) {
-    const extensionDirectory = path7.join(extensionsRoot, directoryName);
-    const manifestPath = path7.join(extensionDirectory, "manifest.json");
+    const extensionDirectory = path6.join(extensionsRoot, directoryName);
+    const manifestPath = path6.join(extensionDirectory, "manifest.json");
     if (!await pathExists(manifestPath)) {
       warnings.push(`extension_manifest_missing:${scope}:${directoryName}`);
       const managedEntry2 = managedByDirectory.get(normalizeExtensionNameForMatch(directoryName));
@@ -2098,7 +2132,7 @@ async function listInstalledExtensions(extensionsRoot, scope, settings, state) {
     }
     let rawManifest;
     try {
-      rawManifest = JSON.parse(await fs7.readFile(manifestPath, "utf8"));
+      rawManifest = JSON.parse(await fs6.readFile(manifestPath, "utf8"));
     } catch {
       warnings.push(`extension_manifest_invalid_json:${scope}:${directoryName}`);
       continue;
@@ -2136,6 +2170,52 @@ async function listInstalledExtensions(extensionsRoot, scope, settings, state) {
     warnings: warnings.sort((left, right) => left.localeCompare(right))
   };
 }
+function summarizeRuntimeCommandPathsForExtension(extensionName, installed) {
+  const normalizedName = normalizeExtensionNameForMatch(extensionName);
+  const entry = installed.find((candidate) => normalizeExtensionNameForMatch(candidate.name) === normalizedName);
+  return {
+    command_paths: [...entry?.command_paths ?? []].sort((left, right) => left.localeCompare(right)),
+    action_paths: [...entry?.action_paths ?? []].sort((left, right) => left.localeCompare(right))
+  };
+}
+function resolveCommandDiscoveryPackageName(extensionName, source) {
+  if (source.kind === "npm" && typeof source.package === "string" && source.package.trim().length > 0) {
+    return source.package.trim();
+  }
+  if (source.kind === "builtin" && typeof source.name === "string" && source.name.trim().length > 0) {
+    return source.name.trim();
+  }
+  return extensionName;
+}
+function buildInstallCommandDiscovery(extensionName, source, commandSummary) {
+  const helpCommands = commandSummary.command_paths.map((commandPath) => `pm ${commandPath} --help`);
+  return {
+    package_name: resolveCommandDiscoveryPackageName(extensionName, source),
+    extension_name: extensionName,
+    command_paths: commandSummary.command_paths,
+    action_paths: commandSummary.action_paths,
+    help_commands: helpCommands,
+    next_steps: commandSummary.command_paths.length > 0 ? helpCommands : ["Run pm package doctor --project --detail deep if expected package commands are missing."]
+  };
+}
+async function probeRuntimeCommandPathsForInstall(pmRoot, settings, refreshedInstalled, global2) {
+  const loadResult = await loadExtensions({
+    pmRoot,
+    settings,
+    cwd: process.cwd(),
+    noExtensions: global2.noExtensions === true,
+    reload_token: nextExtensionReloadToken(),
+    cache_bust: true
+  });
+  const activationResult = await activateExtensions({
+    ...loadResult,
+    loaded: loadResult.loaded
+  });
+  return {
+    installed: applyDoctorRuntimeActivationState(refreshedInstalled, loadResult, activationResult),
+    warnings: [...loadResult.warnings, ...activationResult.warnings]
+  };
+}
 async function checkGithubUpdate(source) {
   const checkedAt = nowIso();
   if (source.kind !== "github" || !source.repository) {
@@ -2197,7 +2277,7 @@ async function adoptUnmanagedExtensions(extensionsRoot, scope, installedExtensio
   let nextState = state;
   const adoptedEntries = [];
   for (const candidate of sortedCandidates) {
-    const extensionDirectory = path7.join(extensionsRoot, candidate.directory);
+    const extensionDirectory = path6.join(extensionsRoot, candidate.directory);
     const validated = await validateExtensionDirectory(extensionDirectory);
     const now = nowIso();
     const sourceRecord = {
@@ -2454,6 +2534,9 @@ async function runExtension(target, options, global2) {
           destination_path: entry.result.details.destination_path,
           activated: entry.result.details.activated,
           settings_changed: entry.result.details.settings_changed,
+          command_paths: entry.result.details.command_paths,
+          action_paths: entry.result.details.action_paths,
+          command_discovery: entry.result.details.command_discovery,
           warnings: entry.result.warnings
         }))
       });
@@ -2473,10 +2556,10 @@ async function runExtension(target, options, global2) {
         const settings = await readSettings(resolvedRoots.settings_root);
         const managedStateRead = await readManagedExtensionState(resolvedRoots.selected_root);
         warnings.push(...managedStateRead.warnings);
-        const destinationDirectory = path7.join(resolvedRoots.selected_root, destinationDirectoryName);
+        const destinationDirectory = path6.join(resolvedRoots.selected_root, destinationDirectoryName);
         const destinationExists = await pathExists(destinationDirectory);
         const installInPlace = await areDirectoriesEquivalent(validated.directory, destinationDirectory);
-        await fs7.mkdir(resolvedRoots.selected_root, { recursive: true });
+        await fs6.mkdir(resolvedRoots.selected_root, { recursive: true });
         if (!installInPlace) {
           await copyExtensionDirectoryForInstall(validated.directory, destinationDirectory);
         }
@@ -2525,6 +2608,11 @@ async function runExtension(target, options, global2) {
         if (activationChanged) {
           await writeSettings(resolvedRoots.settings_root, settings, "settings:write");
         }
+        const refreshedInstalled = await listInstalledExtensions(resolvedRoots.selected_root, scope, settings, managedState);
+        warnings.push(...refreshedInstalled.warnings);
+        const runtimeProbe = await probeRuntimeCommandPathsForInstall(resolvedRoots.pm_root, settings, refreshedInstalled.extensions, global2);
+        warnings.push(...runtimeProbe.warnings);
+        const commandSummary = summarizeRuntimeCommandPathsForExtension(validated.manifest.name, runtimeProbe.installed);
         return withResult({
           extension: {
             name: validated.manifest.name,
@@ -2538,7 +2626,10 @@ async function runExtension(target, options, global2) {
           overwritten: destinationExists && !installInPlace,
           installed_in_place: installInPlace,
           activated: true,
-          settings_changed: activationChanged
+          settings_changed: activationChanged,
+          command_paths: commandSummary.command_paths,
+          action_paths: commandSummary.action_paths,
+          command_discovery: buildInstallCommandDiscovery(validated.manifest.name, sourceRecord, commandSummary)
         });
       });
     } finally {
@@ -2606,7 +2697,7 @@ async function runExtension(target, options, global2) {
         }
       });
     }
-    const extensionDirectory = path7.join(resolvedRoots.selected_root, candidate.directory);
+    const extensionDirectory = path6.join(resolvedRoots.selected_root, candidate.directory);
     const validated = await validateExtensionDirectory(extensionDirectory);
     const now = nowIso();
     const sourceRecord = githubOption === void 0 ? {
@@ -2671,8 +2762,8 @@ async function runExtension(target, options, global2) {
     if (!candidate) {
       throw new PmCliError(`Installed extension "${extensionTarget}" was not found in ${scope} scope.`, EXIT_CODE.NOT_FOUND);
     }
-    const destinationDirectory = path7.join(resolvedRoots.selected_root, candidate.directory);
-    await fs7.rm(destinationDirectory, { recursive: true, force: true });
+    const destinationDirectory = path6.join(resolvedRoots.selected_root, candidate.directory);
+    await fs6.rm(destinationDirectory, { recursive: true, force: true });
     const updatedState = {
       ...managedStateRead.state,
       updated_at: nowIso(),
@@ -3027,8 +3118,6 @@ async function runExtension(target, options, global2) {
 }
 
 export {
-  parseExtensionManifest,
-  validateExtensionDirectory,
   resolveManagedExtensionStatePath,
   readManagedExtensionState,
   writeManagedExtensionState,
@@ -3037,4 +3126,4 @@ export {
   copyExtensionDirectoryForInstall,
   runExtension
 };
-//# sourceMappingURL=chunk-OIQIXTNB.js.map
+//# sourceMappingURL=chunk-KR6R465K.js.map