@unbrained/pm-cli 2026.5.24 → 2026.5.27

package/dist/cli/commands/extension.js

@@ -1,156 +1,36 @@
 
-!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]="69ff4814-0641-5d85-962e-a798cfd1a78e")}catch(e){}}();
+!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]="bec21924-aaa9-50f0-83ba-af92671813ea")}catch(e){}}();
 import { execFile } from "node:child_process";
 import fs from "node:fs/promises";
-import os from "node:os";
 import path from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
 import { promisify } from "node:util";
 import { activateExtensions, loadExtensions, nextExtensionReloadToken } from "../../core/extensions/index.js";
-import { EXTENSION_CAPABILITY_CONTRACT, KNOWN_EXTENSION_CAPABILITIES, parseLegacyExtensionCapabilityAliasWarning, parseUnknownExtensionCapabilityWarning, resolveExtensionRoots, } from "../../core/extensions/loader.js";
+import { resolveExtensionRoots } from "../../core/extensions/loader.js";
 import { pathExists } from "../../core/fs/fs-utils.js";
-import { isPathWithinDirectory } from "../../core/fs/path-utils.js";
-import { PM_PACKAGE_RESOURCE_KINDS, collectPackageExtensionDirectories, readPmPackageManifest, } from "../../core/packages/manifest.js";
-import { resolvePmPackageRootFromModule } from "../../core/packages/root.js";
 import { EXIT_CODE } from "../../core/shared/constants.js";
 import { PmCliError } from "../../core/shared/errors.js";
 import { nowIso } from "../../core/shared/time.js";
 import { resolveGlobalPmRoot, resolvePmRoot } from "../../core/store/paths.js";
 import { readSettings, writeSettings } from "../../core/store/settings.js";
+// Cohesive helper groups now live in ./extension/* sibling modules. They are
+// imported for the command wiring that stays here and re-exported below so
+// existing import sites (sdk barrels, upgrade.ts, tests) keep importing the
+// public surface (runExtension, managed-state read/write, install-source
+// parsing, …) from "./extension.js" unchanged.
+import { normalizeStringList, normalizeExtensionNameForMatch, normalizeManagedDirectoryName, parseExtensionManifest, validateExtensionDirectory, } from "./extension/shared.js";
+import { sortManagedEntries, managedExtensionSourcesEquivalent, readManagedExtensionState, writeManagedExtensionState, upsertManagedEntry, resolveManagedExtensionStatePath, } from "./extension/managed-state.js";
+import { parseExtensionInstallSource, resolveInstallSource, areDirectoriesEquivalent, runGitCommand, } from "./extension/install-sources.js";
+import { resolveBundledExtensionAliasSource, isBundledPackageInstallAllTarget, listBundledPackageAliases, resolveBundledAliasManifestName, buildBundledPackageCatalog, } from "./extension/bundled-catalog.js";
+import { scaffoldExtensionProject } from "./extension/scaffold.js";
+import { applyDoctorRuntimeActivationState, classifyDoctorLoadFailureWarnings, buildExtensionTriageSummary, parseDoctorDetailMode, collectUnknownCapabilityGuidance, buildCapabilityContractMetadata, buildDoctorConsistencySummary, } from "./extension/doctor.js";
+// Re-export the public surface that lives in sibling modules but was previously
+// exported from this file (used by sdk barrels, upgrade.ts, and tests).
+export { parseExtensionManifest, validateExtensionDirectory, readManagedExtensionState, writeManagedExtensionState, resolveManagedExtensionStatePath, parseExtensionInstallSource, };
 const execFileAsync = promisify(execFile);
-const DEFAULT_EXTENSION_PRIORITY = 100;
-const MANAGED_EXTENSION_STATE_FILENAME = ".managed-extensions.json";
-const MANAGED_EXTENSION_STATE_VERSION = 1;
-const PM_PACKAGE_ROOT_ENV = "PM_CLI_PACKAGE_ROOT";
-const LEGACY_BUNDLED_PACKAGE_ALIASES = {
-    beads: {
-        package_directory: "pm-beads",
-        legacy_extension_directory: "beads",
-    },
-    todos: {
-        package_directory: "pm-todos",
-        legacy_extension_directory: "todos",
-    },
-};
-const BUNDLED_PACKAGE_INSTALL_ALL_TARGETS = new Set(["*", "all"]);
-function resolvePackageRootCandidates() {
-    const candidates = [];
-    const envRoot = process.env[PM_PACKAGE_ROOT_ENV];
-    if (typeof envRoot === "string" && envRoot.trim().length > 0) {
-        candidates.push(path.resolve(envRoot.trim()));
-    }
-    candidates.push(resolvePmPackageRootFromModule(import.meta.url, ["../../.."]));
-    return [...new Set(candidates)];
-}
-async function resolveBundledExtensionAliasSource(input) {
-    const normalized = input.trim().toLowerCase();
-    const packageRoot = await resolveBundledPackageRoot(normalized);
-    if (packageRoot) {
-        return packageRoot;
-    }
-    const alias = LEGACY_BUNDLED_PACKAGE_ALIASES[normalized];
-    if (!alias) {
-        return null;
-    }
-    for (const packageRoot of resolvePackageRootCandidates()) {
-        const legacyExtensionPath = path.join(packageRoot, ".agents", "pm", "extensions", alias.legacy_extension_directory);
-        if (await pathExists(path.join(legacyExtensionPath, "manifest.json"))) {
-            return legacyExtensionPath;
-        }
-    }
-    return null;
-}
-function isBundledPackageInstallAllTarget(input) {
-    return BUNDLED_PACKAGE_INSTALL_ALL_TARGETS.has(input.trim().toLowerCase());
-}
-function derivePackageAlias(packageDirectory) {
-    return packageDirectory.replace(/^pm-/i, "").trim().toLowerCase();
-}
-async function collectBundledPackageEntries() {
-    const entriesByAlias = new Map();
-    for (const packageRoot of resolvePackageRootCandidates()) {
-        const packagesRoot = path.join(packageRoot, "packages");
-        if (!(await pathExists(packagesRoot))) {
-            continue;
-        }
-        const entries = await fs.readdir(packagesRoot, { withFileTypes: true });
-        for (const entry of entries) {
-            if (!entry.isDirectory() || !entry.name.startsWith("pm-")) {
-                continue;
-            }
-            const candidateRoot = path.join(packagesRoot, entry.name);
-            if (!(await pathExists(path.join(candidateRoot, "package.json")))) {
-                continue;
-            }
-            const manifest = await readPmPackageManifest(candidateRoot);
-            const aliases = manifest.aliases && manifest.aliases.length > 0
-                ? manifest.aliases
-                : [derivePackageAlias(entry.name)];
-            for (const alias of aliases) {
-                const normalizedAlias = alias.trim().toLowerCase();
-                if (normalizedAlias.length === 0 || entriesByAlias.has(normalizedAlias)) {
-                    continue;
-                }
-                entriesByAlias.set(normalizedAlias, {
-                    alias: normalizedAlias,
-                    package_directory: entry.name,
-                    package_root: candidateRoot,
-                });
-            }
-        }
-    }
-    for (const [alias, legacy] of Object.entries(LEGACY_BUNDLED_PACKAGE_ALIASES)) {
-        if (entriesByAlias.has(alias)) {
-            continue;
-        }
-        for (const packageRoot of resolvePackageRootCandidates()) {
-            const packagePath = path.join(packageRoot, "packages", legacy.package_directory);
-            if (await pathExists(path.join(packagePath, "package.json"))) {
-                entriesByAlias.set(alias, {
-                    alias,
-                    package_directory: legacy.package_directory,
-                    package_root: packagePath,
-                });
-                break;
-            }
-        }
-    }
-    return [...entriesByAlias.values()].sort((left, right) => left.alias.localeCompare(right.alias));
-}
-async function listBundledPackageAliases() {
-    return (await collectBundledPackageEntries()).map((entry) => entry.alias);
-}
-async function resolveBundledPackageRoot(alias) {
-    const normalized = alias.trim().toLowerCase();
-    const entry = (await collectBundledPackageEntries()).find((candidate) => candidate.alias === normalized);
-    return entry?.package_root ?? null;
-}
-function normalizeStringList(values) {
-    return [...new Set(values.map((value) => value.trim()).filter((value) => value.length > 0))].sort((left, right) => left.localeCompare(right));
-}
-function summarizePolicyWarnings(warnings) {
-    let warningCount = 0;
-    let violationCount = 0;
-    let blockedCount = 0;
-    for (const warning of warnings) {
-        if (!warning.startsWith("extension_policy_")) {
-            continue;
-        }
-        warningCount += 1;
-        if (warning.startsWith("extension_policy_violation_")) {
-            violationCount += 1;
-            continue;
-        }
-        if (warning.startsWith("extension_policy_blocked_")) {
-            blockedCount += 1;
-        }
-    }
-    return {
-        warning_count: warningCount,
-        violation_count: violationCount,
-        blocked_count: blockedCount,
-    };
-}
+const EXTENSION_INSTALL_COPY_ATTEMPTS = 3;
+const EXTENSION_INSTALL_LOCK_ATTEMPTS = 120;
+const EXTENSION_INSTALL_LOCK_DELAY_MS = 250;
+const EXTENSION_INSTALL_LOCK_STALE_MS = 120_000;
 function buildExtensionPolicyDetails(policy) {
     const overrides = (policy.extension_overrides ?? [])
         .map((override) => ({
@@ -209,263 +89,71 @@ function buildExtensionPolicyDetails(policy) {
         })),
     };
 }
-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);
-    }
-    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 !== undefined && candidate.priority !== null) {
-        if (typeof candidate.priority !== "number" || !Number.isInteger(candidate.priority)) {
-            return null;
-        }
-        priority = candidate.priority;
-    }
-    let capabilities = [];
-    if (candidate.capabilities !== undefined && 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);
+function isRetriableExtensionInstallCopyError(error) {
+    if (typeof error !== "object" || error === null || !("code" in error)) {
+        return false;
     }
-    return {
-        directory,
-        manifest_path: manifestPath,
-        entry_path: entryPath,
-        manifest,
-    };
+    const code = error.code;
+    return code === "EEXIST" || code === "ENOTEMPTY" || code === "ENOENT";
 }
-export function resolveManagedExtensionStatePath(extensionsRoot) {
-    return path.join(extensionsRoot, MANAGED_EXTENSION_STATE_FILENAME);
+function isErrnoCode(error, code) {
+    return typeof error === "object" && error !== null && "code" in error && error.code === code;
 }
-function createEmptyManagedExtensionState() {
-    return {
-        version: MANAGED_EXTENSION_STATE_VERSION,
-        updated_at: nowIso(),
-        entries: [],
-    };
-}
-function sortManagedEntries(entries) {
-    return [...entries].sort((left, right) => {
-        const byScope = left.scope.localeCompare(right.scope);
-        if (byScope !== 0) {
-            return byScope;
-        }
-        const byName = left.name.localeCompare(right.name);
-        if (byName !== 0) {
-            return byName;
-        }
-        return left.directory.localeCompare(right.directory);
+function sleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
     });
 }
-function managedExtensionSourcesEquivalent(left, right) {
-    if (left.kind !== right.kind || left.input !== right.input || left.location !== right.location) {
-        return false;
-    }
-    if (left.kind === "npm" && right.kind === "npm") {
-        return left.package === right.package && left.version === right.version;
-    }
-    if (left.kind === "github" && right.kind === "github") {
-        return left.repository === right.repository && left.ref === right.ref && left.subpath === right.subpath && left.commit === right.commit;
-    }
-    if (left.kind === "builtin" && right.kind === "builtin") {
-        return left.name === right.name;
-    }
-    return true;
-}
-function normalizeManagedState(raw) {
-    if (typeof raw !== "object" || raw === null) {
-        return null;
-    }
-    const candidate = raw;
-    if (candidate.version !== MANAGED_EXTENSION_STATE_VERSION || !Array.isArray(candidate.entries)) {
-        return null;
-    }
-    const entries = [];
-    for (const rawEntry of candidate.entries) {
-        if (typeof rawEntry !== "object" || rawEntry === null) {
-            continue;
-        }
-        const entry = rawEntry;
-        if (typeof entry.name !== "string" ||
-            entry.name.trim().length === 0 ||
-            typeof entry.directory !== "string" ||
-            entry.directory.trim().length === 0 ||
-            (entry.scope !== "project" && entry.scope !== "global") ||
-            typeof entry.manifest_version !== "string" ||
-            typeof entry.manifest_entry !== "string" ||
-            !Array.isArray(entry.capabilities) ||
-            entry.capabilities.some((value) => typeof value !== "string") ||
-            typeof entry.installed_at !== "string" ||
-            typeof entry.updated_at !== "string" ||
-            typeof entry.source !== "object" ||
-            entry.source === null) {
-            continue;
+export async function copyExtensionDirectoryForInstall(sourceDirectory, destinationDirectory, copyDirectory = fs.cp) {
+    let lastError = null;
+    for (let attempt = 1; attempt <= EXTENSION_INSTALL_COPY_ATTEMPTS; attempt += 1) {
+        try {
+            if (await pathExists(destinationDirectory)) {
+                await fs.rm(destinationDirectory, { recursive: true, force: true });
+            }
+            await copyDirectory(sourceDirectory, destinationDirectory, { recursive: true, force: true });
+            return;
         }
-        const source = entry.source;
-        if ((source.kind !== "local" && source.kind !== "github" && source.kind !== "npm" && source.kind !== "builtin") ||
-            typeof source.input !== "string" ||
-            typeof source.location !== "string") {
-            continue;
+        catch (error) {
+            if (!isRetriableExtensionInstallCopyError(error) || attempt === EXTENSION_INSTALL_COPY_ATTEMPTS) {
+                throw error;
+            }
+            lastError = error;
         }
-        entries.push({
-            name: entry.name.trim(),
-            directory: entry.directory.trim(),
-            scope: entry.scope,
-            manifest_version: entry.manifest_version,
-            manifest_entry: entry.manifest_entry,
-            capabilities: normalizeStringList(entry.capabilities),
-            installed_at: entry.installed_at,
-            updated_at: entry.updated_at,
-            source: {
-                kind: source.kind,
-                input: source.input,
-                location: source.location,
-                name: typeof source.name === "string" ? source.name : undefined,
-                package: typeof source.package === "string" ? source.package : undefined,
-                version: typeof source.version === "string" ? source.version : undefined,
-                repository: typeof source.repository === "string" ? source.repository : undefined,
-                owner: typeof source.owner === "string" ? source.owner : undefined,
-                repo: typeof source.repo === "string" ? source.repo : undefined,
-                ref: typeof source.ref === "string" ? source.ref : undefined,
-                subpath: typeof source.subpath === "string" ? source.subpath : undefined,
-                commit: typeof source.commit === "string" ? source.commit : undefined,
-            },
-            last_update_check_at: typeof entry.last_update_check_at === "string" ? entry.last_update_check_at : undefined,
-            last_update_remote_commit: typeof entry.last_update_remote_commit === "string" ? entry.last_update_remote_commit : undefined,
-            update_available: typeof entry.update_available === "boolean" || entry.update_available === null
-                ? entry.update_available
-                : undefined,
-            update_error: typeof entry.update_error === "string" ? entry.update_error : undefined,
-        });
     }
-    return {
-        version: MANAGED_EXTENSION_STATE_VERSION,
-        updated_at: typeof candidate.updated_at === "string" ? candidate.updated_at : nowIso(),
-        entries: sortManagedEntries(entries),
-    };
 }
-export async function readManagedExtensionState(extensionsRoot) {
-    const statePath = resolveManagedExtensionStatePath(extensionsRoot);
-    const fallback = createEmptyManagedExtensionState();
-    try {
-        const raw = await fs.readFile(statePath, "utf8");
-        const parsed = JSON.parse(raw);
-        const normalized = normalizeManagedState(parsed);
-        if (!normalized) {
-            return {
-                path: statePath,
-                state: fallback,
-                warnings: [`extension_manager_state_invalid_schema:${statePath}`],
-            };
-        }
-        return {
-            path: statePath,
-            state: normalized,
-            warnings: [],
-        };
-    }
-    catch (error) {
-        if (typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT") {
-            return {
-                path: statePath,
-                state: fallback,
-                warnings: [],
-            };
+async function withExtensionInstallLock(settingsRoot, destinationDirectoryName, run) {
+    const lockRoot = path.join(settingsRoot, "runtime", "extension-install-locks");
+    const lockPath = path.join(lockRoot, `${destinationDirectoryName}.lock`);
+    await fs.mkdir(lockRoot, { recursive: true });
+    let acquired = false;
+    for (let attempt = 1; attempt <= EXTENSION_INSTALL_LOCK_ATTEMPTS; attempt += 1) {
+        try {
+            await fs.mkdir(lockPath);
+            acquired = true;
+            await fs.writeFile(path.join(lockPath, "owner.json"), `${JSON.stringify({ pid: process.pid, created_at: nowIso(), destination: destinationDirectoryName }, null, 2)}\n`, "utf8");
+            break;
+        }
+        catch (error) {
+            if (!isErrnoCode(error, "EEXIST")) {
+                throw error;
+            }
+            const stat = await fs.stat(lockPath).catch(() => null);
+            if (stat && Date.now() - stat.mtimeMs > EXTENSION_INSTALL_LOCK_STALE_MS) {
+                await fs.rm(lockPath, { recursive: true, force: true });
+                continue;
+            }
+            await sleep(EXTENSION_INSTALL_LOCK_DELAY_MS);
         }
-        return {
-            path: statePath,
-            state: fallback,
-            warnings: [`extension_manager_state_read_failed:${statePath}`],
-        };
     }
-}
-export async function writeManagedExtensionState(extensionsRoot, state) {
-    const statePath = resolveManagedExtensionStatePath(extensionsRoot);
-    const normalized = {
-        version: MANAGED_EXTENSION_STATE_VERSION,
-        updated_at: nowIso(),
-        entries: sortManagedEntries(state.entries),
-    };
-    await fs.mkdir(extensionsRoot, { recursive: true });
-    await fs.writeFile(statePath, `${JSON.stringify(normalized, null, 2)}\n`, "utf8");
-}
-function normalizeExtensionNameForMatch(value) {
-    return value.trim().toLowerCase();
-}
-async function resolveBundledAliasManifestName(input) {
-    const bundledAliasSource = await resolveBundledExtensionAliasSource(input);
-    if (!bundledAliasSource) {
-        return null;
+    if (!acquired) {
+        throw new PmCliError(`Timed out waiting for extension install lock for "${destinationDirectoryName}".`, EXIT_CODE.CONFLICT);
     }
     try {
-        const extensionDirectories = await collectPackageExtensionDirectories(bundledAliasSource);
-        if (extensionDirectories.length !== 1) {
-            return null;
-        }
-        const validated = await validateExtensionDirectory(extensionDirectories[0]);
-        return validated.manifest.name;
+        return await run();
     }
-    catch {
-        return null;
+    finally {
+        await fs.rm(lockPath, { recursive: true, force: true }).catch(() => undefined);
     }
 }
 async function resolveInstalledExtensionCandidate(installed, extensionTarget) {
@@ -596,505 +284,6 @@ function resolveScope(options) {
     }
     return global ? "global" : "project";
 }
-async function buildBundledPackageCatalog(scope, global, options = {}) {
-    const roots = resolveExtensionRoots(resolvePmRoot(process.cwd(), global.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) => path.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()) {
-        const packageRoot = await resolveBundledPackageRoot(alias);
-        const installScopeFlag = scope === "global" ? "--global" : "--project";
-        if (!packageRoot) {
-            packages.push({
-                alias,
-                bundled: true,
-                available: false,
-                installed: false,
-                install_target: alias,
-                install_command: `pm install ${alias} ${installScopeFlag}`,
-            });
-            continue;
-        }
-        const manifest = await readPmPackageManifest(packageRoot);
-        const repository = manifest.catalog?.links?.repository ?? manifest.package_repository_url;
-        const report = manifest.catalog?.links?.report ?? manifest.package_bugs_url;
-        const docs = manifest.catalog?.links?.docs ?? manifest.package_homepage;
-        const npm = manifest.catalog?.links?.npm ??
-            (manifest.package_name && manifest.package_private !== true
-                ? `https://www.npmjs.com/package/${encodeURIComponent(manifest.package_name)}`
-                : undefined);
-        const metadataOnlyResources = Object.fromEntries(PM_PACKAGE_RESOURCE_KINDS
-            .filter((resourceKind) => resourceKind !== "extensions")
-            .map((resourceKind) => [resourceKind, manifest.resources[resourceKind] ?? []])
-            .filter(([, entries]) => Array.isArray(entries) && entries.length > 0));
-        packages.push({
-            alias,
-            bundled: true,
-            available: true,
-            installed: installedBuiltinAliases.has(alias) || installedLocations.has(path.resolve(packageRoot)),
-            install_target: alias,
-            install_command: `pm install ${alias} ${installScopeFlag}`,
-            package_name: manifest.package_name,
-            package_version: manifest.package_version,
-            description: manifest.catalog?.summary ?? manifest.package_description,
-            keywords: manifest.package_keywords ?? [],
-            resources: manifest.resources,
-            installable_resources: {
-                extensions: manifest.resources.extensions ?? [],
-            },
-            metadata_only_resources: metadataOnlyResources,
-            catalog: {
-                display_name: manifest.catalog?.display_name,
-                category: manifest.catalog?.category,
-                tags: manifest.catalog?.tags ?? manifest.package_keywords ?? [],
-                links: {
-                    docs,
-                    npm,
-                    repository,
-                    report,
-                },
-                media: manifest.catalog?.media,
-            },
-        });
-    }
-    const fields = parsePackageCatalogFields(options.fields);
-    const outputPackages = fields ? packages.map((entry) => projectPackageCatalogEntry(entry, fields)) : packages;
-    return {
-        total: outputPackages.length,
-        scope,
-        installable_resource_kinds: ["extensions"],
-        metadata_only_resource_kinds: PM_PACKAGE_RESOURCE_KINDS.filter((resourceKind) => resourceKind !== "extensions"),
-        packages: outputPackages,
-    };
-}
-const PACKAGE_CATALOG_FIELD_KEYS = new Set([
-    "alias",
-    "bundled",
-    "available",
-    "installed",
-    "install_target",
-    "install_command",
-    "package_name",
-    "package_version",
-    "description",
-    "keywords",
-    "resources",
-    "installable_resources",
-    "metadata_only_resources",
-    "catalog",
-    "category",
-    "display_name",
-]);
-function parsePackageCatalogFields(raw) {
-    if (raw === undefined) {
-        return undefined;
-    }
-    const fields = [...new Set(raw.split(",").map((entry) => entry.trim()).filter((entry) => entry.length > 0))];
-    if (fields.length === 0) {
-        throw new PmCliError("Package catalog --fields requires a comma-separated list of field names", EXIT_CODE.USAGE);
-    }
-    const unknown = fields.filter((field) => !PACKAGE_CATALOG_FIELD_KEYS.has(field));
-    if (unknown.length > 0) {
-        throw new PmCliError(`Unknown package catalog --fields value(s): ${unknown.join(", ")}`, EXIT_CODE.USAGE, {
-            examples: [
-                "pm package list --project --fields alias,installed,install_command",
-                "pm package catalog --project --fields alias,package_name,category",
-            ],
-        });
-    }
-    return fields;
-}
-function projectPackageCatalogEntry(entry, fields) {
-    const projected = {};
-    for (const field of fields) {
-        if (field === "category") {
-            projected[field] = entry.catalog?.category ?? null;
-        }
-        else if (field === "display_name") {
-            projected[field] = entry.catalog?.display_name ?? null;
-        }
-        else {
-            projected[field] = entry[field] ?? null;
-        }
-    }
-    return projected;
-}
-function parseGithubPathSpec(pathSpec, input, refOverride) {
-    const segments = pathSpec
-        .split("/")
-        .map((segment) => segment.trim())
-        .filter((segment) => segment.length > 0);
-    if (segments.length < 2) {
-        return null;
-    }
-    const owner = segments[0];
-    const repo = segments[1].replace(/\.git$/i, "");
-    if (owner.length === 0 || repo.length === 0) {
-        return null;
-    }
-    const tail = segments.slice(2);
-    let ref;
-    let subpath;
-    if (tail[0] === "tree" && tail.length >= 2) {
-        ref = tail[1];
-        subpath = tail.slice(2).join("/");
-    }
-    else if (tail.length > 0) {
-        subpath = tail.join("/");
-    }
-    if (typeof refOverride === "string" && refOverride.trim().length > 0) {
-        ref = refOverride.trim();
-    }
-    return {
-        kind: "github",
-        input,
-        owner,
-        repo,
-        repository: `https://github.com/${owner}/${repo}.git`,
-        ref,
-        subpath: subpath && subpath.length > 0 ? subpath : undefined,
-    };
-}
-export function parseExtensionInstallSource(input, options = {}) {
-    const normalizedInput = input.trim();
-    if (normalizedInput.length === 0) {
-        throw new PmCliError("Extension source is required for --install.", EXIT_CODE.USAGE);
-    }
-    const refOverride = typeof options.ref === "string" && options.ref.trim().length > 0 ? options.ref.trim() : undefined;
-    if (normalizedInput.startsWith("npm:")) {
-        const spec = normalizedInput.slice("npm:".length).trim();
-        if (spec.length === 0) {
-            throw new PmCliError('npm package source must include a package spec after "npm:".', EXIT_CODE.USAGE);
-        }
-        if (options.forceGithub) {
-            throw new PmCliError('Options "--gh/--github" cannot be combined with npm: package sources.', EXIT_CODE.USAGE);
-        }
-        if (refOverride) {
-            throw new PmCliError('Option "--ref" cannot be combined with npm: package sources.', EXIT_CODE.USAGE);
-        }
-        return {
-            kind: "npm",
-            input: normalizedInput,
-            spec,
-        };
-    }
-    const maybeGithubByUrl = (() => {
-        try {
-            const parsed = new URL(normalizedInput);
-            if (parsed.hostname !== "github.com") {
-                return null;
-            }
-            const pathSpec = parsed.pathname.replace(/^\/+/, "");
-            return parseGithubPathSpec(pathSpec, normalizedInput, refOverride);
-        }
-        catch {
-            return null;
-        }
-    })();
-    if (maybeGithubByUrl) {
-        return maybeGithubByUrl;
-    }
-    const strippedDomainInput = normalizedInput.startsWith("github.com/") ? normalizedInput.slice("github.com/".length) : null;
-    if (strippedDomainInput) {
-        const parsed = parseGithubPathSpec(strippedDomainInput, normalizedInput, refOverride);
-        if (!parsed) {
-            throw new PmCliError(`Invalid GitHub source "${normalizedInput}".`, EXIT_CODE.USAGE);
-        }
-        return parsed;
-    }
-    if (options.forceGithub) {
-        const parsed = parseGithubPathSpec(normalizedInput, normalizedInput, refOverride);
-        if (!parsed) {
-            throw new PmCliError(`Invalid GitHub shorthand "${normalizedInput}".`, EXIT_CODE.USAGE);
-        }
-        return parsed;
-    }
-    if (/^https?:\/\//i.test(normalizedInput)) {
-        throw new PmCliError(`Unsupported extension source URL "${normalizedInput}". Supported remote source host: github.com.`, EXIT_CODE.USAGE);
-    }
-    return {
-        kind: "local",
-        input: normalizedInput,
-        absolute_path: path.resolve(process.cwd(), normalizedInput),
-    };
-}
-async function runGitCommand(args) {
-    try {
-        const result = await execFileAsync("git", args, { encoding: "utf8" });
-        return (result.stdout ?? "").trim();
-    }
-    catch (error) {
-        const stderr = typeof error === "object" && error !== null && "stderr" in error ? String(error.stderr) : "";
-        const message = stderr.trim().length > 0 ? stderr.trim() : error instanceof Error ? error.message : String(error);
-        throw new PmCliError(`Git command failed: git ${args.join(" ")}\n${message}`, EXIT_CODE.GENERIC_FAILURE);
-    }
-}
-async function runNpmCommand(args, cwd) {
-    try {
-        const result = await execFileAsync("npm", args, { cwd, encoding: "utf8" });
-        return (result.stdout ?? "").trim();
-    }
-    catch (error) {
-        const stderr = typeof error === "object" && error !== null && "stderr" in error ? String(error.stderr) : "";
-        const message = stderr.trim().length > 0 ? stderr.trim() : error instanceof Error ? error.message : String(error);
-        throw new PmCliError(`npm command failed: npm ${args.join(" ")}\n${message}`, EXIT_CODE.GENERIC_FAILURE);
-    }
-}
-async function resolveLocalNpmPackagePath(spec) {
-    if (path.isAbsolute(spec) || spec.startsWith(".") || spec.startsWith("..")) {
-        const absolutePath = path.resolve(process.cwd(), spec);
-        return (await pathExists(absolutePath)) ? absolutePath : null;
-    }
-    try {
-        const parsed = new URL(spec);
-        if (parsed.protocol === "file:") {
-            const absolutePath = fileURLToPath(parsed);
-            return (await pathExists(absolutePath)) ? absolutePath : null;
-        }
-    }
-    catch {
-        // Registry package specs are not URLs.
-    }
-    return null;
-}
-async function resolveNpmPackSpec(spec) {
-    const localPath = await resolveLocalNpmPackagePath(spec);
-    if (localPath) {
-        return pathToFileURL(localPath).href;
-    }
-    if (/^[a-z][a-z0-9+.-]*:/i.test(spec)) {
-        return spec;
-    }
-    return spec;
-}
-function parsePackedNpmPackage(stdout, packDirectory) {
-    try {
-        const parsed = JSON.parse(stdout);
-        const first = Array.isArray(parsed) ? parsed[0] : undefined;
-        if (first && typeof first.filename === "string" && first.filename.trim().length > 0) {
-            return {
-                tarball: path.resolve(packDirectory, first.filename),
-                package: typeof first.name === "string" ? first.name : undefined,
-                version: typeof first.version === "string" ? first.version : undefined,
-            };
-        }
-    }
-    catch {
-        // Fall back to the last stdout line for older npm output.
-    }
-    const lastLine = stdout
-        .split(/\r?\n/)
-        .map((line) => line.trim())
-        .filter((line) => line.length > 0)
-        .at(-1);
-    if (!lastLine) {
-        throw new PmCliError("npm pack did not report a tarball filename.", EXIT_CODE.GENERIC_FAILURE);
-    }
-    return {
-        tarball: path.resolve(packDirectory, lastLine),
-    };
-}
-async function resolveNpmSourceDirectory(source) {
-    const localPackageRoot = await resolveLocalNpmPackagePath(source.spec);
-    if (localPackageRoot) {
-        const packageJsonPath = path.join(localPackageRoot, "package.json");
-        const packageJson = (await pathExists(packageJsonPath))
-            ? JSON.parse(await fs.readFile(packageJsonPath, "utf8"))
-            : {};
-        return {
-            directory: await resolvePackageExtensionDirectory(localPackageRoot, source.input),
-            package: typeof packageJson.name === "string" ? packageJson.name : undefined,
-            version: typeof packageJson.version === "string" ? packageJson.version : undefined,
-            cleanup: async () => { },
-        };
-    }
-    const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "pm-npm-package-source-"));
-    const packDirectory = path.join(tempRoot, "pack");
-    const extractDirectory = path.join(tempRoot, "extract");
-    await fs.mkdir(packDirectory, { recursive: true });
-    await fs.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 = path.join(extractDirectory, "package");
-        await installNpmPackageRuntimeDependencies(packageRoot);
-        const directory = await resolvePackageExtensionDirectory(packageRoot, source.input);
-        return {
-            directory,
-            package: packed.package,
-            version: packed.version,
-            cleanup: async () => {
-                await fs.rm(tempRoot, { recursive: true, force: true });
-            },
-        };
-    }
-    catch (error) {
-        await fs.rm(tempRoot, { recursive: true, force: true });
-        throw error;
-    }
-}
-async function installNpmPackageRuntimeDependencies(packageRoot) {
-    const packageJsonPath = path.join(packageRoot, "package.json");
-    if (!(await pathExists(packageJsonPath))) {
-        return;
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(await fs.readFile(packageJsonPath, "utf8"));
-    }
-    catch {
-        return;
-    }
-    if (typeof parsed !== "object" || parsed === null) {
-        return;
-    }
-    const manifest = parsed;
-    const dependencySpecs = runtimeDependencyInstallSpecs(manifest);
-    if (dependencySpecs.length === 0) {
-        return;
-    }
-    const runtimeOnlyManifest = { ...parsed };
-    delete runtimeOnlyManifest.devDependencies;
-    await fs.writeFile(packageJsonPath, `${JSON.stringify(runtimeOnlyManifest, null, 2)}\n`, "utf8");
-    await Promise.all([
-        fs.rm(path.join(packageRoot, "package-lock.json"), { force: true }),
-        fs.rm(path.join(packageRoot, "npm-shrinkwrap.json"), { force: true }),
-    ]);
-    await runNpmCommand(["install", "--ignore-scripts", "--no-audit", "--fund=false", "--package-lock=false", "--no-save", ...dependencySpecs], packageRoot);
-}
-function runtimeDependencyInstallSpecs(manifest) {
-    const specs = new Map();
-    for (const dependencyMap of [manifest.dependencies, manifest.optionalDependencies, manifest.peerDependencies]) {
-        if (typeof dependencyMap !== "object" || dependencyMap === null) {
-            continue;
-        }
-        for (const [name, version] of Object.entries(dependencyMap)) {
-            if (typeof version !== "string" || version.trim().length === 0 || specs.has(name)) {
-                continue;
-            }
-            specs.set(name, `${name}@${version.trim()}`);
-        }
-    }
-    return [...specs.values()];
-}
-async function resolvePackageExtensionDirectory(packageRoot, sourceLabel) {
-    const discovered = await collectPackageExtensionDirectories(packageRoot);
-    if (discovered.length === 1) {
-        return discovered[0];
-    }
-    if (discovered.length > 1) {
-        const choices = discovered
-            .map((entry) => path.relative(packageRoot, entry).replaceAll(path.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);
-}
-async function resolveGithubSourceDirectory(cloneDirectory, source) {
-    const candidatePaths = [];
-    if (source.subpath) {
-        candidatePaths.push(source.subpath);
-        candidatePaths.push(path.posix.join(".agents/pm/extensions", source.subpath));
-        candidatePaths.push(path.posix.join(".custom/pm-extensions", source.subpath));
-        candidatePaths.push(path.posix.join(".custom/pm-extension", source.subpath));
-    }
-    for (const candidate of candidatePaths) {
-        const absolute = path.resolve(cloneDirectory, candidate);
-        if (await pathExists(path.join(absolute, "manifest.json"))) {
-            return { directory: absolute, resolved_subpath: candidate };
-        }
-    }
-    if (await pathExists(path.join(cloneDirectory, "manifest.json"))) {
-        return { directory: cloneDirectory, resolved_subpath: "." };
-    }
-    const discoveredDirectory = await resolvePackageExtensionDirectory(cloneDirectory, source.input);
-    return {
-        directory: discoveredDirectory,
-        resolved_subpath: path.relative(cloneDirectory, discoveredDirectory).replaceAll(path.sep, "/"),
-    };
-}
-async function resolveInstallSource(source) {
-    if (source.kind === "local") {
-        let localStats;
-        try {
-            localStats = await fs.stat(source.absolute_path);
-        }
-        catch {
-            throw new PmCliError(`Local extension source does not exist: "${source.absolute_path}".`, EXIT_CODE.NOT_FOUND);
-        }
-        if (!localStats.isDirectory()) {
-            throw new PmCliError(`Local extension source must be a directory: "${source.absolute_path}".`, EXIT_CODE.USAGE);
-        }
-        const directory = await resolvePackageExtensionDirectory(source.absolute_path, source.input);
-        return {
-            source,
-            directory,
-        };
-    }
-    if (source.kind === "npm") {
-        const resolved = await resolveNpmSourceDirectory(source);
-        return {
-            source,
-            directory: resolved.directory,
-            cleanup: resolved.cleanup,
-            resolved_subpath: path.relative(path.dirname(resolved.directory), resolved.directory).replaceAll(path.sep, "/"),
-            npm_package: resolved.package,
-            npm_version: resolved.version,
-        };
-    }
-    const cloneDirectory = await fs.mkdtemp(path.join(os.tmpdir(), "pm-extension-source-"));
-    const cloneArgs = ["clone", "--depth", "1"];
-    if (source.ref) {
-        cloneArgs.push("--branch", source.ref);
-    }
-    cloneArgs.push(source.repository, cloneDirectory);
-    try {
-        await runGitCommand(cloneArgs);
-        const commit = await runGitCommand(["-C", cloneDirectory, "rev-parse", "HEAD"]);
-        const resolved = await resolveGithubSourceDirectory(cloneDirectory, source);
-        return {
-            source,
-            directory: resolved.directory,
-            resolved_subpath: resolved.resolved_subpath,
-            commit,
-            cleanup: async () => {
-                await fs.rm(cloneDirectory, { recursive: true, force: true });
-            },
-        };
-    }
-    catch (error) {
-        await fs.rm(cloneDirectory, { recursive: true, force: true });
-        throw error;
-    }
-}
-async function areDirectoriesEquivalent(left, right) {
-    if (!(await pathExists(left)) || !(await pathExists(right))) {
-        return false;
-    }
-    const [leftRealPath, rightRealPath] = await Promise.all([fs.realpath(left), fs.realpath(right)]);
-    return leftRealPath === rightRealPath;
-}
-function upsertManagedEntry(state, entry) {
-    const updatedEntries = state.entries.filter((candidate) => normalizeExtensionNameForMatch(candidate.name) !== normalizeExtensionNameForMatch(entry.name) &&
-        normalizeExtensionNameForMatch(candidate.directory) !== normalizeExtensionNameForMatch(entry.directory));
-    updatedEntries.push(entry);
-    return {
-        ...state,
-        updated_at: nowIso(),
-        entries: sortManagedEntries(updatedEntries),
-    };
-}
 function resolveUpdateCheckResolution(managedEntry) {
     if (!managedEntry) {
         return {
@@ -1229,88 +418,6 @@ async function listInstalledExtensions(extensionsRoot, scope, settings, state) {
         warnings: warnings.sort((left, right) => left.localeCompare(right)),
     };
 }
-function applyDoctorRuntimeActivationState(extensions, loadResult, activationResult) {
-    const loadedNames = new Set(loadResult.loaded.map((entry) => normalizeExtensionNameForMatch(entry.name)));
-    const loadFailedNames = new Set(loadResult.failed.map((entry) => normalizeExtensionNameForMatch(entry.name)));
-    const activationFailedNames = new Set(activationResult.failed.map((entry) => normalizeExtensionNameForMatch(entry.name)));
-    const commandPathsByExtension = new Map();
-    const actionPathsByExtension = new Map();
-    const addCommandPath = (extensionName, commandPath) => {
-        const normalizedName = normalizeExtensionNameForMatch(extensionName);
-        const normalizedCommandPath = commandPath.trim();
-        if (normalizedName.length === 0 || normalizedCommandPath.length === 0) {
-            return;
-        }
-        const existing = commandPathsByExtension.get(normalizedName) ?? new Set();
-        existing.add(normalizedCommandPath);
-        commandPathsByExtension.set(normalizedName, existing);
-    };
-    const addActionPath = (extensionName, actionPath) => {
-        const normalizedName = normalizeExtensionNameForMatch(extensionName);
-        const normalizedActionPath = actionPath.trim();
-        if (normalizedName.length === 0 || normalizedActionPath.length === 0) {
-            return;
-        }
-        const existing = actionPathsByExtension.get(normalizedName) ?? new Set();
-        existing.add(normalizedActionPath);
-        actionPathsByExtension.set(normalizedName, existing);
-    };
-    for (const registration of activationResult.registrations.commands) {
-        addCommandPath(registration.name, registration.command);
-        addActionPath(registration.name, registration.action);
-    }
-    for (const handler of activationResult.commands.handlers) {
-        addCommandPath(handler.name, handler.command);
-    }
-    for (const override of activationResult.commands.overrides) {
-        addCommandPath(override.name, override.command);
-    }
-    const sortedPaths = (values) => {
-        if (!values || values.size === 0) {
-            return undefined;
-        }
-        return [...values].sort((left, right) => left.localeCompare(right));
-    };
-    return extensions.map((entry) => {
-        const normalizedName = normalizeExtensionNameForMatch(entry.name);
-        const commandPaths = sortedPaths(commandPathsByExtension.get(normalizedName));
-        const actionPaths = sortedPaths(actionPathsByExtension.get(normalizedName));
-        const runtimeMetadata = {
-            ...(commandPaths ? { command_paths: commandPaths } : {}),
-            ...(actionPaths ? { action_paths: actionPaths } : {}),
-        };
-        if (!entry.enabled) {
-            return {
-                ...entry,
-                runtime_active: false,
-                activation_status: "not_loaded",
-                ...runtimeMetadata,
-            };
-        }
-        if (loadFailedNames.has(normalizedName) || activationFailedNames.has(normalizedName)) {
-            return {
-                ...entry,
-                runtime_active: false,
-                activation_status: "failed",
-                ...runtimeMetadata,
-            };
-        }
-        if (loadedNames.has(normalizedName)) {
-            return {
-                ...entry,
-                runtime_active: true,
-                activation_status: "ok",
-                ...runtimeMetadata,
-            };
-        }
-        return {
-            ...entry,
-            runtime_active: false,
-            activation_status: "not_loaded",
-            ...runtimeMetadata,
-        };
-    });
-}
 async function checkGithubUpdate(source) {
     const checkedAt = nowIso();
     if (source.kind !== "github" || !source.repository) {
@@ -1448,391 +555,6 @@ function requireTarget(target, action) {
     }
     return normalized;
 }
-function lifecycleFlagCommand(options, action) {
-    return options.vocabulary === "package" ? `pm package ${action}` : `pm extension --${action}`;
-}
-function buildStarterExtensionScaffoldFiles(extensionName, commandName, vocabulary) {
-    const packageName = `pm-${extensionName}`;
-    const manifest = `${JSON.stringify({
-        name: extensionName,
-        version: "0.1.0",
-        entry: "./index.js",
-        capabilities: ["commands"],
-    }, null, 2)}\n`;
-    const entrypoint = [
-        "export function activate(api) {",
-        "  api.registerCommand({",
-        `    name: ${JSON.stringify(commandName)},`,
-        '    description: "Starter scaffold command. Replace with your own behavior.",',
-        "    run: async (context) => ({",
-        "      ok: true,",
-        `      source: ${JSON.stringify(extensionName)},`,
-        "      command: context.command,",
-        '      message: "Starter extension scaffold is active.",',
-        "    }),",
-        "  });",
-        "}",
-        "",
-        "export default {",
-        "  activate,",
-        "};",
-        "",
-    ].join("\n");
-    if (vocabulary === "package") {
-        const packageJson = `${JSON.stringify({
-            name: packageName,
-            version: "0.1.0",
-            private: true,
-            type: "module",
-            keywords: ["pm-package"],
-            peerDependencies: {
-                "@unbrained/pm-cli": "*",
-            },
-            pm: {
-                aliases: [extensionName],
-                extensions: [`extensions/${extensionName}`],
-                docs: ["README.md"],
-                examples: ["README.md"],
-                catalog: {
-                    display_name: extensionName,
-                    category: "workflow",
-                    summary: "Starter pm package scaffold.",
-                    tags: ["starter"],
-                },
-            },
-        }, null, 2)}\n`;
-        const packageReadme = [
-            `# ${packageName}`,
-            "",
-            "Generated by `pm package init`.",
-            "",
-            "## Included Files",
-            "- `package.json`: package metadata and `pm` resource manifest.",
-            `- \`extensions/${extensionName}/manifest.json\`: extension metadata and capabilities.`,
-            `- \`extensions/${extensionName}/index.js\`: starter command registration using the \`commands\` capability.`,
-            "",
-            "## Quick Start",
-            "```bash",
-            "pm install --project <package-path>",
-            `pm ${commandName}`,
-            "pm package doctor --project --detail summary",
-            "```",
-            "",
-            "## Notes",
-            "- Keep package metadata in `package.json` and runtime behavior under `extensions/`.",
-            "- Add capabilities to the extension manifest only when the entrypoint uses the matching SDK API.",
-            "- Use `@unbrained/pm-cli/sdk` as the public SDK import for richer package runtimes.",
-            "",
-        ].join("\n");
-        return {
-            "package.json": packageJson,
-            [`extensions/${extensionName}/manifest.json`]: manifest,
-            [`extensions/${extensionName}/index.js`]: entrypoint,
-            "README.md": packageReadme,
-        };
-    }
-    const readme = [
-        `# ${extensionName}`,
-        "",
-        "Generated by `pm extension init`.",
-        "",
-        "## Included Files",
-        "- `manifest.json`: extension metadata and capabilities.",
-        "- `index.js`: starter command registration using the `commands` capability.",
-        "",
-        "## Quick Start",
-        "```bash",
-        "pm extension --install --project <scaffold-path>",
-        `pm ${commandName}`,
-        "pm extension --doctor --project --detail summary",
-        "```",
-        "",
-        "## Notes",
-        "- This scaffold uses ESM exports so it works in package scopes with `type: module`.",
-        "- Update `manifest.json` capabilities and `index.js` command behavior as your extension evolves.",
-        "",
-    ].join("\n");
-    return {
-        "manifest.json": manifest,
-        "index.js": entrypoint,
-        "README.md": readme,
-    };
-}
-async function scaffoldExtensionProject(target, vocabulary = "extension") {
-    const normalizedTarget = target.trim();
-    const targetPath = path.resolve(process.cwd(), normalizedTarget);
-    const extensionName = normalizeManagedDirectoryName(path.basename(targetPath));
-    const commandName = `${extensionName} ping`;
-    const scaffoldFiles = buildStarterExtensionScaffoldFiles(extensionName, commandName, vocabulary);
-    let createdDirectory = false;
-    if (await pathExists(targetPath)) {
-        const existingTargetStats = await fs.stat(targetPath);
-        if (!existingTargetStats.isDirectory()) {
-            throw new PmCliError(`Scaffold target "${targetPath}" exists and is not a directory.`, EXIT_CODE.CONFLICT);
-        }
-    }
-    else {
-        await fs.mkdir(targetPath, { recursive: true });
-        createdDirectory = true;
-    }
-    const files = [];
-    for (const [relativePath, content] of Object.entries(scaffoldFiles)) {
-        const absolutePath = path.join(targetPath, relativePath);
-        await fs.mkdir(path.dirname(absolutePath), { recursive: true });
-        if (await pathExists(absolutePath)) {
-            const existingContent = await fs.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);
-            }
-            files.push({
-                path: relativePath,
-                status: "unchanged",
-            });
-            continue;
-        }
-        await fs.writeFile(absolutePath, content, "utf8");
-        files.push({
-            path: relativePath,
-            status: "created",
-        });
-    }
-    return {
-        extension_name: extensionName,
-        command_name: commandName,
-        target_path: targetPath,
-        created_directory: createdDirectory,
-        files,
-    };
-}
-function classifyDoctorLoadFailureWarnings(loadFailures) {
-    const warnings = [];
-    for (const failure of loadFailures) {
-        const normalizedError = failure.error.toLowerCase();
-        if (normalizedError.includes("cannot find package '@unbrained/pm-cli'") ||
-            normalizedError.includes('cannot find module "@unbrained/pm-cli"') ||
-            normalizedError.includes("cannot find module '@unbrained/pm-cli'")) {
-            warnings.push(`extension_load_failed_sdk_dependency_missing:${failure.name}`);
-        }
-        if (normalizedError.includes("cannot use import statement outside a module") ||
-            normalizedError.includes("to load an es module") ||
-            normalizedError.includes("must use import to load es module")) {
-            warnings.push(`extension_load_failed_module_mode_mismatch:${failure.name}`);
-        }
-    }
-    return [...new Set(warnings)].sort((left, right) => left.localeCompare(right));
-}
-function buildExtensionTriageSummary(scope, warnings, extensions, options = {}) {
-    const normalizedWarnings = [...new Set(warnings)].sort((left, right) => left.localeCompare(right));
-    const managedTotal = extensions.filter((entry) => entry.managed).length;
-    const enabledTotal = extensions.filter((entry) => entry.enabled).length;
-    const activeTotal = extensions.filter((entry) => entry.active).length;
-    const updateAvailableTotal = extensions.filter((entry) => entry.update_available === true).length;
-    const unmanagedExtensions = extensions.filter((entry) => entry.managed === false);
-    const unmanagedExpectedExtensions = unmanagedExtensions
-        .filter((entry) => isExpectedUnmanagedExtension(entry))
-        .map((entry) => entry.name)
-        .sort((left, right) => left.localeCompare(right));
-    const unmanagedActionRequiredExtensions = unmanagedExtensions
-        .filter((entry) => !isExpectedUnmanagedExtension(entry))
-        .map((entry) => entry.name)
-        .sort((left, right) => left.localeCompare(right));
-    const updateCheckStatusTotals = {
-        checked: 0,
-        skipped_unmanaged: 0,
-        skipped_non_github: 0,
-        failed: 0,
-        not_checked: 0,
-    };
-    for (const entry of extensions) {
-        updateCheckStatusTotals[entry.update_check_status] += 1;
-    }
-    const updateCheckFailedTotal = updateCheckStatusTotals.failed;
-    const skippedUnmanagedTotal = updateCheckStatusTotals.skipped_unmanaged;
-    const skippedNonGithubTotal = updateCheckStatusTotals.skipped_non_github;
-    const updateHealthPartial = unmanagedActionRequiredExtensions.length > 0;
-    const updateHealthCoverage = updateHealthPartial ? "partial" : "full";
-    const partialCoverageWarnings = updateHealthPartial
-        ? [`extension_update_health_partial_coverage:skipped_unmanaged:${unmanagedActionRequiredExtensions.length}`]
-        : [];
-    const effectiveWarnings = [...new Set([...normalizedWarnings, ...partialCoverageWarnings])].sort((left, right) => left.localeCompare(right));
-    const warningCodes = [...new Set(effectiveWarnings.map((value) => warningCode(value)))].sort((left, right) => left.localeCompare(right));
-    const policyWarnings = summarizePolicyWarnings(effectiveWarnings);
-    const scopeFlag = scope === "global" ? "--global" : "--project";
-    const remediation = [];
-    if (normalizedWarnings.length > 0) {
-        if (normalizedWarnings.some((warning) => warning.startsWith("extension_manifest_"))) {
-            remediation.push(`Run ${lifecycleFlagCommand(options, "explore")} ${scopeFlag} to inspect discovered manifests and directories.`);
-        }
-        if (normalizedWarnings.some((warning) => warning.startsWith("extension_capability_unknown:"))) {
-            remediation.push(`Unknown extension capabilities detected. Allowed capabilities: ${KNOWN_EXTENSION_CAPABILITIES.join(", ")}. ` +
-                "Review extension_capability_unknown warning details for suggested replacements.");
-        }
-        if (normalizedWarnings.some((warning) => warning.startsWith("extension_capability_legacy_alias:"))) {
-            remediation.push("Legacy extension capability aliases were auto-remapped to canonical capabilities. " +
-                "Update manifests to canonical names (migration/validation -> schema).");
-        }
-        if (normalizedWarnings.some((warning) => warning.startsWith("extension_command_definition_legacy_handler_alias:"))) {
-            remediation.push("Extension command definitions using legacy handler were auto-remapped. " +
-                "Update command definitions to use run: (context) => ... for forward compatibility.");
-        }
-        if (normalizedWarnings.some((warning) => warning.startsWith("extension_load_failed_sdk_dependency_missing:"))) {
-            remediation.push(`Detected extension load failures caused by missing SDK dependency resolution. ` +
-                `Ensure extension package dependencies include "@unbrained/pm-cli" and reinstall dependencies before running ${lifecycleFlagCommand(options, "doctor")} ${scopeFlag}.`);
-        }
-        if (normalizedWarnings.some((warning) => warning.startsWith("extension_load_failed_module_mode_mismatch:"))) {
-            remediation.push(`Detected extension module-mode mismatches. For ESM-based extension entries/imports, set package.json "type": "module" ` +
-                `or use an explicit .mjs entry and rerun ${lifecycleFlagCommand(options, "doctor")} ${scopeFlag}.`);
-        }
-        if (updateCheckFailedTotal > 0) {
-            remediation.push(`Run ${lifecycleFlagCommand(options, "manage")} ${scopeFlag} after validating network and repository access.`);
-        }
-        if (normalizedWarnings.some((warning) => warning.startsWith("extension_manager_state_"))) {
-            remediation.push(`Review and repair ${scope} managed extension state file if schema/read warnings persist.`);
-        }
-        if (policyWarnings.warning_count > 0) {
-            remediation.push("Extension governance policy warnings detected. Review settings.extensions.policy mode and allow/block lists to confirm intended capabilities and registration surfaces.");
-        }
-    }
-    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) {
-        remediation.push(`Loaded unmanaged extensions are currently treated as informational. Use ${lifecycleFlagCommand(options, "manage")} ${scopeFlag} --fix-managed-state to adopt them for update checks.`);
-    }
-    if (skippedNonGithubTotal > 0) {
-        remediation.push(`Non-GitHub managed extensions are skipped by update checks. Use doctor output for non-update diagnostics.`);
-    }
-    if (updateAvailableTotal > 0) {
-        remediation.push(`Update available managed extensions via ${lifecycleFlagCommand(options, "install")} ${scopeFlag} <source>.`);
-    }
-    if (remediation.length === 0) {
-        remediation.push(`No immediate action required. Re-run ${lifecycleFlagCommand(options, "manage")} ${scopeFlag} after extension changes.`);
-    }
-    return {
-        status: effectiveWarnings.length === 0 ? "ok" : "warn",
-        warning_count: effectiveWarnings.length,
-        warning_codes: warningCodes,
-        warnings: effectiveWarnings,
-        policy_warning_count: policyWarnings.warning_count,
-        policy_violation_count: policyWarnings.violation_count,
-        policy_blocked_count: policyWarnings.blocked_count,
-        total_extensions: extensions.length,
-        managed_total: managedTotal,
-        enabled_total: enabledTotal,
-        active_total: activeTotal,
-        update_available_total: updateAvailableTotal,
-        update_health_coverage: updateHealthCoverage,
-        update_health_partial: updateHealthPartial,
-        unmanaged_loaded_extension_count: unmanagedExtensions.length,
-        unmanaged_loaded_extensions: unmanagedExtensions
-            .map((entry) => entry.name)
-            .sort((left, right) => left.localeCompare(right)),
-        unmanaged_expected_extension_count: unmanagedExpectedExtensions.length,
-        unmanaged_expected_extensions: unmanagedExpectedExtensions,
-        unmanaged_action_required_extension_count: unmanagedActionRequiredExtensions.length,
-        unmanaged_action_required_extensions: unmanagedActionRequiredExtensions,
-        update_check_status_totals: updateCheckStatusTotals,
-        update_check_failed_total: updateCheckFailedTotal,
-        top_warnings: effectiveWarnings.slice(0, 8),
-        remediation,
-    };
-}
-function parseDoctorDetailMode(raw) {
-    if (!raw || raw.trim().length === 0) {
-        return "summary";
-    }
-    const normalized = raw.trim().toLowerCase();
-    if (normalized === "summary" || normalized === "deep") {
-        return normalized;
-    }
-    throw new PmCliError(`Invalid --detail value "${raw}". Expected summary or deep.`, EXIT_CODE.USAGE);
-}
-function warningCode(value) {
-    const normalized = value.trim();
-    const separator = normalized.indexOf(":");
-    if (separator === -1) {
-        return normalized;
-    }
-    return normalized.slice(0, separator);
-}
-function collectUnknownCapabilityGuidance(warnings) {
-    const seen = new Set();
-    const guidance = [];
-    for (const warning of warnings) {
-        const parsedDetails = (() => {
-            const unknownWarning = parseUnknownExtensionCapabilityWarning(warning);
-            if (unknownWarning) {
-                return [unknownWarning];
-            }
-            return parseLegacyExtensionCapabilityAliasWarning(warning);
-        })();
-        for (const parsed of parsedDetails) {
-            const key = `${parsed.layer}:${parsed.name}:${parsed.capability}`;
-            if (seen.has(key)) {
-                continue;
-            }
-            seen.add(key);
-            guidance.push(parsed);
-        }
-    }
-    return guidance;
-}
-function buildCapabilityContractMetadata() {
-    return {
-        version: EXTENSION_CAPABILITY_CONTRACT.version,
-        capabilities: [...EXTENSION_CAPABILITY_CONTRACT.capabilities],
-        legacy_aliases: { ...EXTENSION_CAPABILITY_CONTRACT.legacy_aliases },
-    };
-}
-function isExpectedUnmanagedExtension(entry) {
-    const normalizedName = normalizeExtensionNameForMatch(entry.name);
-    const normalizedDirectory = normalizeExtensionNameForMatch(entry.directory);
-    if (normalizedName.startsWith("builtin-")) {
-        return true;
-    }
-    return normalizedDirectory === "beads" || normalizedDirectory === "todos";
-}
-function buildDoctorConsistencySummary(scope, installedExtensions, loadedExtensions, failedLoads, disabledByFlag) {
-    if (scope !== "project" || disabledByFlag) {
-        return {
-            warnings: [],
-            summary: {
-                active_project_count: 0,
-                loaded_project_count: 0,
-                active_project_names: [],
-                loaded_project_names: [],
-                missing_active_project_names: [],
-            },
-        };
-    }
-    const activeProjectNames = [
-        ...new Set(installedExtensions
-            .filter((entry) => entry.active)
-            .map((entry) => normalizeExtensionNameForMatch(entry.name))),
-    ].sort((left, right) => left.localeCompare(right));
-    const loadedProjectNames = [
-        ...new Set(loadedExtensions
-            .filter((entry) => entry.layer === "project")
-            .map((entry) => normalizeExtensionNameForMatch(entry.name))),
-    ].sort((left, right) => left.localeCompare(right));
-    const failedLoadNames = new Set(failedLoads.map((entry) => normalizeExtensionNameForMatch(entry.name)));
-    const missingActiveProjectNames = activeProjectNames
-        .filter((name) => !loadedProjectNames.includes(name) && !failedLoadNames.has(name))
-        .sort((left, right) => left.localeCompare(right));
-    const warnings = missingActiveProjectNames.length > 0
-        ? [`extension_doctor_consistency_active_not_loaded:${missingActiveProjectNames.join(",")}`]
-        : [];
-    return {
-        warnings,
-        summary: {
-            active_project_count: activeProjectNames.length,
-            loaded_project_count: loadedProjectNames.length,
-            active_project_names: activeProjectNames,
-            loaded_project_names: loadedProjectNames,
-            missing_active_project_names: missingActiveProjectNames,
-        },
-    };
-}
 export async function runExtension(target, options, global) {
     const action = resolveAction(target, options);
     if ((options.strictExit === true || options.failOnWarn === true) && action !== "doctor") {
@@ -2012,89 +734,88 @@ export async function runExtension(target, options, global) {
             ref: options.ref,
         });
         const resolvedSource = await resolveInstallSource(installSource);
-        const settings = await readSettings(resolvedRoots.settings_root);
-        const managedStateRead = await readManagedExtensionState(resolvedRoots.selected_root);
-        warnings.push(...managedStateRead.warnings);
         try {
             const validated = await validateExtensionDirectory(resolvedSource.directory);
             const destinationDirectoryName = normalizeManagedDirectoryName(validated.manifest.name);
-            const destinationDirectory = path.join(resolvedRoots.selected_root, destinationDirectoryName);
-            const destinationExists = await pathExists(destinationDirectory);
-            const installInPlace = await areDirectoriesEquivalent(validated.directory, destinationDirectory);
-            await fs.mkdir(resolvedRoots.selected_root, { recursive: true });
-            if (!installInPlace) {
-                if (destinationExists) {
-                    await fs.rm(destinationDirectory, { recursive: true, force: true });
-                }
-                await fs.cp(validated.directory, destinationDirectory, { recursive: true, force: true });
-            }
-            const sourceRecord = bundledAliasName
-                ? {
-                    kind: "builtin",
-                    input: bundledAliasName,
-                    location: bundledAliasName,
-                    name: bundledAliasName,
+            return await withExtensionInstallLock(resolvedRoots.settings_root, destinationDirectoryName, async () => {
+                const settings = await readSettings(resolvedRoots.settings_root);
+                const managedStateRead = await readManagedExtensionState(resolvedRoots.selected_root);
+                warnings.push(...managedStateRead.warnings);
+                const destinationDirectory = path.join(resolvedRoots.selected_root, destinationDirectoryName);
+                const destinationExists = await pathExists(destinationDirectory);
+                const installInPlace = await areDirectoriesEquivalent(validated.directory, destinationDirectory);
+                await fs.mkdir(resolvedRoots.selected_root, { recursive: true });
+                if (!installInPlace) {
+                    await copyExtensionDirectoryForInstall(validated.directory, destinationDirectory);
                 }
-                : installSource.kind === "local"
+                const sourceRecord = bundledAliasName
                     ? {
-                        kind: "local",
-                        input: installSource.input,
-                        location: installSource.absolute_path,
+                        kind: "builtin",
+                        input: bundledAliasName,
+                        location: bundledAliasName,
+                        name: bundledAliasName,
                     }
-                    : installSource.kind === "npm"
+                    : installSource.kind === "local"
                         ? {
-                            kind: "npm",
+                            kind: "local",
                             input: installSource.input,
-                            location: resolvedSource.resolved_subpath ?? ".",
-                            package: resolvedSource.npm_package,
-                            version: resolvedSource.npm_version,
+                            location: installSource.absolute_path,
                         }
-                        : {
-                            kind: "github",
-                            input: installSource.input,
-                            location: resolvedSource.resolved_subpath ?? installSource.subpath ?? ".",
-                            repository: installSource.repository,
-                            owner: installSource.owner,
-                            repo: installSource.repo,
-                            ref: installSource.ref,
-                            subpath: resolvedSource.resolved_subpath ?? installSource.subpath,
-                            commit: resolvedSource.commit,
-                        };
-            const now = nowIso();
-            const existingManagedEntry = managedStateRead.state.entries.find((entry) => normalizeExtensionNameForMatch(entry.name) === normalizeExtensionNameForMatch(validated.manifest.name));
-            const sourceUnchanged = existingManagedEntry !== undefined &&
-                existingManagedEntry.manifest_version === validated.manifest.version &&
-                managedExtensionSourcesEquivalent(existingManagedEntry.source, sourceRecord);
-            const managedState = upsertManagedEntry(managedStateRead.state, {
-                name: validated.manifest.name,
-                directory: destinationDirectoryName,
-                scope,
-                manifest_version: validated.manifest.version,
-                manifest_entry: validated.manifest.entry,
-                capabilities: [...validated.manifest.capabilities],
-                installed_at: existingManagedEntry?.installed_at ?? now,
-                updated_at: sourceUnchanged ? existingManagedEntry.updated_at : now,
-                source: sourceRecord,
-            });
-            await writeManagedExtensionState(resolvedRoots.selected_root, managedState);
-            const activationChanged = ensureActivated(settings, validated.manifest.name);
-            if (activationChanged) {
-                await writeSettings(resolvedRoots.settings_root, settings, "settings:write");
-            }
-            return withResult({
-                extension: {
+                        : installSource.kind === "npm"
+                            ? {
+                                kind: "npm",
+                                input: installSource.input,
+                                location: resolvedSource.resolved_subpath ?? ".",
+                                package: resolvedSource.npm_package,
+                                version: resolvedSource.npm_version,
+                            }
+                            : {
+                                kind: "github",
+                                input: installSource.input,
+                                location: resolvedSource.resolved_subpath ?? installSource.subpath ?? ".",
+                                repository: installSource.repository,
+                                owner: installSource.owner,
+                                repo: installSource.repo,
+                                ref: installSource.ref,
+                                subpath: resolvedSource.resolved_subpath ?? installSource.subpath,
+                                commit: resolvedSource.commit,
+                            };
+                const now = nowIso();
+                const existingManagedEntry = managedStateRead.state.entries.find((entry) => normalizeExtensionNameForMatch(entry.name) === normalizeExtensionNameForMatch(validated.manifest.name));
+                const sourceUnchanged = existingManagedEntry !== undefined &&
+                    existingManagedEntry.manifest_version === validated.manifest.version &&
+                    managedExtensionSourcesEquivalent(existingManagedEntry.source, sourceRecord);
+                const managedState = upsertManagedEntry(managedStateRead.state, {
                     name: validated.manifest.name,
-                    version: validated.manifest.version,
-                    entry: validated.manifest.entry,
-                    capabilities: validated.manifest.capabilities,
                     directory: destinationDirectoryName,
-                },
-                source: sourceRecord,
-                destination_path: destinationDirectory,
-                overwritten: destinationExists && !installInPlace,
-                installed_in_place: installInPlace,
-                activated: true,
-                settings_changed: activationChanged,
+                    scope,
+                    manifest_version: validated.manifest.version,
+                    manifest_entry: validated.manifest.entry,
+                    capabilities: [...validated.manifest.capabilities],
+                    installed_at: existingManagedEntry?.installed_at ?? now,
+                    updated_at: sourceUnchanged ? existingManagedEntry.updated_at : now,
+                    source: sourceRecord,
+                });
+                await writeManagedExtensionState(resolvedRoots.selected_root, managedState);
+                const activationChanged = ensureActivated(settings, validated.manifest.name);
+                if (activationChanged) {
+                    await writeSettings(resolvedRoots.settings_root, settings, "settings:write");
+                }
+                return withResult({
+                    extension: {
+                        name: validated.manifest.name,
+                        version: validated.manifest.version,
+                        entry: validated.manifest.entry,
+                        capabilities: validated.manifest.capabilities,
+                        directory: destinationDirectoryName,
+                    },
+                    source: sourceRecord,
+                    destination_path: destinationDirectory,
+                    overwritten: destinationExists && !installInPlace,
+                    installed_in_place: installInPlace,
+                    activated: true,
+                    settings_changed: activationChanged,
+                });
             });
         }
         finally {
@@ -2612,4 +1333,4 @@ export async function runExtension(target, options, global) {
     throw new PmCliError(`Unsupported extension action "${action}".`, EXIT_CODE.USAGE);
 }
 //# sourceMappingURL=extension.js.map
-//# debugId=69ff4814-0641-5d85-962e-a798cfd1a78e
+//# debugId=bec21924-aaa9-50f0-83ba-af92671813ea