@unbrained/pm-cli 2026.7.14 → 2026.7.16

package/dist/sdk/extension.js

@@ -0,0 +1,2174 @@
+/**
+ * @module sdk/extension
+ *
+ * Implements the pm extension command surface and its agent-facing runtime behavior.
+ */
+
+!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]="fe21d8bd-795f-5bed-b4fc-e6efe6ee6120")}catch(e){}}();
+import fs from "node:fs/promises";
+import path from "node:path";
+import { activateExtensions, createSerialQueue, loadExtensions, nextExtensionReloadToken, } from "../core/extensions/index.js";
+import { resolveExtensionRoots } from "../core/extensions/loader.js";
+import { pathExists } from "../core/fs/fs-utils.js";
+import { resolvePmPackageRootFromModule } from "../core/packages/root.js";
+import { EXIT_CODE } from "../core/shared/constants.js";
+import { PmCliError } from "../core/shared/errors.js";
+import { levenshteinDistanceWithinLimit } from "../core/shared/levenshtein.js";
+import { nowIso } from "../core/shared/time.js";
+import { resolveGlobalPmRoot, resolvePmRoot, } from "../core/store/paths.js";
+import { readSettings, writeSettings } from "../core/store/settings.js";
+import { quoteCommandArg, renderPmCommand } from "./command-line.js";
+import { ensureTypeFolderScaffold } from "./schema.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, } from "./extension/install-sources.js";
+import { resolveBundledExtensionAliasSource, resolveBundledPackageNpmName, isBundledPackageInstallAllTarget, listBundledPackageAliases, resolveBundledAliasManifestName, buildBundledPackageCatalog, } from "./extension/bundled-catalog.js";
+import { scaffoldExtensionProject } from "./extension/scaffold.js";
+import { buildExtensionDescribeResult } from "./extension/describe.js";
+import { applyDoctorRuntimeActivationState, classifyDoctorLoadFailureWarnings, classifyDoctorActivationFailureWarnings, classifyUnusedCapabilityWarnings, buildExtensionTriageSummary, parseDoctorDetailMode, collectUnknownCapabilityGuidance, buildCapabilityContractMetadata, buildDoctorConsistencySummary, } from "./extension/doctor.js";
+import { copyExtensionDirectoryForInstall, copyExtensionDirectoryWithoutSelfNesting, ensureExtensionModuleTypeMarker, isErrnoCode, isRetriableExtensionInstallCopyError, resolveCanonicalExtensionInstallDestination, withExtensionInstallLock, } from "./extension/install-runtime.js";
+import { mapWithFixedConcurrency } from "./extension/concurrency.js";
+import { checkGithubUpdate } from "./extension/update-check.js";
+import { captureExtensionInstallSnapshot, readOptionalMetadataFile, restoreExtensionInstallSnapshot, } from "./extension/install-snapshot.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, copyExtensionDirectoryForInstall, resolveCanonicalExtensionInstallDestination, };
+const GITHUB_UPDATE_CHECK_CONCURRENCY = 4;
+const LIFECYCLE_ACTION_TARGETS = [
+    ["install", "install", "--install"],
+    ["uninstall", "uninstall", "--uninstall"],
+    ["explore", "explore", "--explore"],
+    ["list", "explore", "--explore"],
+    ["manage", "manage", "--manage"],
+    ["describe", "describe", "--describe"],
+    ["reload", "reload", "--reload"],
+    ["doctor", "doctor", "--doctor"],
+    ["catalog", "catalog", "--catalog"],
+    ["init", "init", "--init"],
+    ["scaffold", "init", "--scaffold"],
+    ["adopt", "adopt", "--adopt"],
+    ["adopt-all", "adopt-all", "--adopt-all"],
+    ["activate", "activate", "--activate"],
+    ["deactivate", "deactivate", "--deactivate"],
+];
+const LIFECYCLE_ACTION_FLAG_HINT = LIFECYCLE_ACTION_TARGETS.map(([, , flag]) => flag)
+    .filter((flag, index, flags) => flags.indexOf(flag) === index)
+    .join(", ");
+const LIFECYCLE_ACTION_FLAGS = {
+    install: "--install",
+    uninstall: "--uninstall",
+    explore: "--explore",
+    manage: "--manage",
+    describe: "--describe",
+    reload: "--reload",
+    doctor: "--doctor",
+    catalog: "--catalog",
+    adopt: "--adopt",
+    "adopt-all": "--adopt-all",
+    activate: "--activate",
+    deactivate: "--deactivate",
+    init: "--init",
+};
+const NATIVE_OUTPUT_MARKER = "__pm_native_output";
+const EXTENSION_POLICY_ROOT_LIST_FIELDS = [
+    "trusted_extensions",
+    "allowed_extensions",
+    "blocked_extensions",
+    "allowed_capabilities",
+    "blocked_capabilities",
+    "allowed_surfaces",
+    "blocked_surfaces",
+    "allowed_commands",
+    "blocked_commands",
+    "allowed_actions",
+    "blocked_actions",
+    "allowed_services",
+    "blocked_services",
+];
+const EXTENSION_POLICY_OVERRIDE_LIST_FIELDS = [
+    "allowed_capabilities",
+    "blocked_capabilities",
+    "allowed_surfaces",
+    "blocked_surfaces",
+    "allowed_commands",
+    "blocked_commands",
+    "allowed_actions",
+    "blocked_actions",
+    "allowed_services",
+    "blocked_services",
+];
+const EXTENSION_POLICY_OVERRIDE_BOOLEAN_FIELDS = [
+    "disabled",
+    "require_trusted",
+    "require_provenance",
+];
+const DEFAULT_EXTENSION_POLICY_DETAILS = {
+    mode: "off",
+    trust_mode: "off",
+    require_provenance: false,
+    trusted_extensions: [],
+    default_sandbox_profile: "none",
+    allowed_extensions: [],
+    blocked_extensions: [],
+    allowed_capabilities: [],
+    blocked_capabilities: [],
+    allowed_surfaces: [],
+    blocked_surfaces: [],
+    allowed_commands: [],
+    blocked_commands: [],
+    allowed_actions: [],
+    blocked_actions: [],
+    allowed_services: [],
+    blocked_services: [],
+    extension_overrides: [],
+};
+/** Normalize every root-level extension policy list into a stable unique sequence. */
+const normalizePolicyRootLists = (policy) => {
+    const safePolicy = policy ?? DEFAULT_EXTENSION_POLICY_DETAILS;
+    const lists = {};
+    for (const field of EXTENSION_POLICY_ROOT_LIST_FIELDS) {
+        lists[field] = normalizeStringList(safePolicy[field] ?? []);
+    }
+    return lists;
+};
+/** Attach only populated override lists so diagnostics remain compact. */
+const appendNonEmptyPolicyLists = (target, lists) => {
+    for (const field of EXTENSION_POLICY_OVERRIDE_LIST_FIELDS) {
+        if (lists[field].length > 0) {
+            target[field] = lists[field];
+        }
+    }
+    return target;
+};
+/** Attach explicitly enabled scalar fields to one normalized extension override. */
+const appendEnabledPolicyScalars = (target, override) => {
+    for (const field of EXTENSION_POLICY_OVERRIDE_BOOLEAN_FIELDS) {
+        if (override[field] === true) {
+            target[field] = true;
+        }
+    }
+    if (override.sandbox_profile) {
+        target.sandbox_profile = override.sandbox_profile;
+    }
+    return target;
+};
+/** Normalize every list field from one extension policy override. */
+const normalizePolicyOverrideLists = (override) => {
+    const lists = {};
+    for (const field of EXTENSION_POLICY_OVERRIDE_LIST_FIELDS) {
+        lists[field] = normalizeStringList(override[field] ?? []);
+    }
+    return lists;
+};
+/** Build deterministic diagnostic details for one valid named extension override. */
+const buildExtensionPolicyOverrideDetails = (override) => {
+    const name = typeof override.name === "string" ? override.name.trim() : "";
+    if (name.length === 0) {
+        return null;
+    }
+    return appendNonEmptyPolicyLists(appendEnabledPolicyScalars({ name }, override), normalizePolicyOverrideLists(override));
+};
+/** Normalize and sort all named extension policy overrides. */
+const normalizeExtensionPolicyOverrides = (overrides) => (overrides ?? [])
+    .map((override) => buildExtensionPolicyOverrideDetails(override))
+    .filter((override) => override !== null)
+    .sort((left, right) => left.name.localeCompare(right.name));
+/** Build the normalized extension policy representation exposed by diagnostics. */
+const buildExtensionPolicyDetails = (policy) => {
+    const safePolicy = Object.assign({}, DEFAULT_EXTENSION_POLICY_DETAILS, policy ?? {});
+    const rootLists = normalizePolicyRootLists(policy);
+    const overrides = normalizeExtensionPolicyOverrides(safePolicy.extension_overrides);
+    return {
+        mode: safePolicy.mode,
+        trust_mode: safePolicy.trust_mode,
+        require_provenance: safePolicy.require_provenance === true,
+        trusted_extensions: rootLists.trusted_extensions,
+        default_sandbox_profile: safePolicy.default_sandbox_profile,
+        allowed_extensions: rootLists.allowed_extensions,
+        blocked_extensions: rootLists.blocked_extensions,
+        allowed_capabilities: rootLists.allowed_capabilities,
+        blocked_capabilities: rootLists.blocked_capabilities,
+        allowed_surfaces: rootLists.allowed_surfaces,
+        blocked_surfaces: rootLists.blocked_surfaces,
+        allowed_commands: rootLists.allowed_commands,
+        blocked_commands: rootLists.blocked_commands,
+        allowed_actions: rootLists.allowed_actions,
+        blocked_actions: rootLists.blocked_actions,
+        allowed_services: rootLists.allowed_services,
+        blocked_services: rootLists.blocked_services,
+        extension_overrides: overrides,
+    };
+};
+/** Resolve a lifecycle target against managed extension names, aliases, and directories. */
+const resolveInstalledExtensionCandidate = async (installed, extensionTarget) => {
+    const lookupValues = [extensionTarget];
+    const bundledAliasManifestName = await resolveBundledAliasManifestName(extensionTarget);
+    if (bundledAliasManifestName) {
+        lookupValues.push(bundledAliasManifestName);
+    }
+    const normalizedLookups = [
+        ...new Set(lookupValues
+            .map((value) => normalizeExtensionNameForMatch(value))
+            .filter((value) => value.length > 0)),
+    ];
+    for (const lookup of normalizedLookups) {
+        const byName = installed.find((entry) => normalizeExtensionNameForMatch(entry.name) === lookup);
+        if (byName) {
+            return byName;
+        }
+        const byDirectory = installed.find((entry) => normalizeExtensionNameForMatch(entry.directory) === lookup);
+        if (byDirectory) {
+            return byDirectory;
+        }
+    }
+    return undefined;
+};
+/** Return whether one extension is enabled after explicit enabled and disabled settings are applied. */
+const isExtensionEnabled = (settings, name) => {
+    const normalizedName = name.trim();
+    const enabled = new Set(normalizeStringList(settings.extensions.enabled));
+    const disabled = new Set(normalizeStringList(settings.extensions.disabled));
+    if (disabled.has(normalizedName)) {
+        return false;
+    }
+    if (enabled.size === 0) {
+        return true;
+    }
+    return enabled.has(normalizedName);
+};
+/** Mutate extension settings to activate one name and report whether persisted state changed. */
+const ensureActivated = (settings, name) => {
+    const normalizedName = name.trim();
+    const enabled = new Set(normalizeStringList(settings.extensions.enabled));
+    const disabled = new Set(normalizeStringList(settings.extensions.disabled));
+    const previousEnabled = [...enabled];
+    const previousDisabled = [...disabled];
+    disabled.delete(normalizedName);
+    if (enabled.size > 0) {
+        enabled.add(normalizedName);
+    }
+    settings.extensions.enabled = [...enabled].sort((left, right) => left.localeCompare(right));
+    settings.extensions.disabled = [...disabled].sort((left, right) => left.localeCompare(right));
+    return (settings.extensions.enabled.join("\u0000") !==
+        previousEnabled.join("\u0000") ||
+        settings.extensions.disabled.join("\u0000") !==
+            previousDisabled.join("\u0000"));
+};
+/** Mutate extension settings to deactivate one name and report whether persisted state changed. */
+const ensureDeactivated = (settings, name) => {
+    const normalizedName = name.trim();
+    const enabled = new Set(normalizeStringList(settings.extensions.enabled));
+    const disabled = new Set(normalizeStringList(settings.extensions.disabled));
+    const previousEnabled = [...enabled];
+    const previousDisabled = [...disabled];
+    enabled.delete(normalizedName);
+    disabled.add(normalizedName);
+    settings.extensions.enabled = [...enabled].sort((left, right) => left.localeCompare(right));
+    settings.extensions.disabled = [...disabled].sort((left, right) => left.localeCompare(right));
+    return (settings.extensions.enabled.join("\u0000") !==
+        previousEnabled.join("\u0000") ||
+        settings.extensions.disabled.join("\u0000") !==
+            previousDisabled.join("\u0000"));
+};
+/** Remove one extension from explicit enabled and disabled settings and report whether state changed. */
+const clearExtensionState = (settings, name) => {
+    const normalizedName = name.trim();
+    const enabled = new Set(normalizeStringList(settings.extensions.enabled));
+    const disabled = new Set(normalizeStringList(settings.extensions.disabled));
+    const previousEnabled = [...enabled];
+    const previousDisabled = [...disabled];
+    enabled.delete(normalizedName);
+    disabled.delete(normalizedName);
+    settings.extensions.enabled = [...enabled].sort((left, right) => left.localeCompare(right));
+    settings.extensions.disabled = [...disabled].sort((left, right) => left.localeCompare(right));
+    return (settings.extensions.enabled.join("\u0000") !==
+        previousEnabled.join("\u0000") ||
+        settings.extensions.disabled.join("\u0000") !==
+            previousDisabled.join("\u0000"));
+};
+/** Return the nearest valid lifecycle action and flag for one user-provided target. */
+const suggestLifecycleActionTarget = (target) => {
+    const normalizedTarget = target.trim().toLowerCase();
+    const maxDistance = Math.min(2, Math.max(1, Math.ceil(normalizedTarget.length / 4)));
+    const nearest = LIFECYCLE_ACTION_TARGETS.map(([candidate, action, flag]) => ({
+        action,
+        flag,
+        distance: levenshteinDistanceWithinLimit(normalizedTarget, candidate, maxDistance),
+    }))
+        .filter((entry) => entry.distance !== null)
+        .sort((left, right) => left.distance - right.distance)[0];
+    return nearest ? { action: nearest.action, flag: nearest.flag } : null;
+};
+/** Build structured recovery guidance for an unknown extension lifecycle action. */
+const buildUnknownLifecycleActionError = (target, options) => {
+    const noun = options.vocabulary === "package" ? "package" : "extension";
+    const suggestion = suggestLifecycleActionTarget(target);
+    if (!suggestion) {
+        return new PmCliError(`One action flag is required. Use one of: ${LIFECYCLE_ACTION_FLAG_HINT}. Bare \`pm package\` and \`pm extension\` default to --explore.`, EXIT_CODE.USAGE);
+    }
+    const command = `pm ${noun} ${suggestion.flag}`;
+    return new PmCliError(`Unknown ${noun} lifecycle action "${target}". Did you mean "${suggestion.flag}"?`, EXIT_CODE.USAGE, {
+        code: "unknown_lifecycle_action",
+        required: `Use one of: ${LIFECYCLE_ACTION_FLAG_HINT}.`,
+        examples: [command, `pm ${noun} --help`],
+        recovery: {
+            attempted_command: `pm ${noun} ${target}`,
+            suggested_retry: command,
+            fallback_candidates: [
+                {
+                    source: "lifecycle_action",
+                    command,
+                    reason: `nearest lifecycle action for "${target}"`,
+                },
+            ],
+        },
+    });
+};
+// Maps each boolean action flag to the lifecycle action it selects. `scaffold`
+// aliases `init` and `adoptAll` selects `adopt-all`; every other flag maps to its
+// like-named action. Dispatching through the table keeps `resolveAction` flat.
+const EXTENSION_ACTION_FLAG_SELECTORS = [
+    ["install", "install"],
+    ["uninstall", "uninstall"],
+    ["explore", "explore"],
+    ["manage", "manage"],
+    ["describe", "describe"],
+    ["reload", "reload"],
+    ["doctor", "doctor"],
+    ["catalog", "catalog"],
+    ["init", "init"],
+    ["scaffold", "init"],
+    ["adopt", "adopt"],
+    ["adoptAll", "adopt-all"],
+    ["activate", "activate"],
+    ["deactivate", "deactivate"],
+];
+/** Positional lifecycle shorthand mapped to the canonical extension action. */
+const IMPLICIT_EXTENSION_ACTIONS = {
+    doctor: "doctor",
+    reload: "reload",
+    catalog: "catalog",
+    init: "init",
+    scaffold: "init",
+    explore: "explore",
+    manage: "manage",
+    list: "explore",
+    "": "explore",
+};
+/** Map a bare positional token (already trimmed and lower-cased) to the lifecycle action it implies for `pm extension <token>` / `pm package <token>`: the `doctor`/`reload`/`catalog`/`init`/`scaffold`/`explore`/`manage` keywords, with `list` and the empty string both meaning `explore`. Returns `null` for anything else so the caller can raise a did-you-mean error. */
+const resolveImplicitActionFromTarget = (normalizedTarget) => IMPLICIT_EXTENSION_ACTIONS[normalizedTarget] ?? null;
+/** Resolve mutually exclusive lifecycle flags and positional shorthand into one extension action. */
+const resolveAction = (target, options) => {
+    const selected = [
+        ...new Set(EXTENSION_ACTION_FLAG_SELECTORS.filter(([flag]) => options[flag] === true).map(([, mappedAction]) => mappedAction)),
+    ];
+    if (selected.length === 0) {
+        if (target === undefined) {
+            return "explore";
+        }
+        const implicitAction = resolveImplicitActionFromTarget(target.trim().toLowerCase());
+        if (implicitAction) {
+            return implicitAction;
+        }
+        throw buildUnknownLifecycleActionError(target, options);
+    }
+    if (selected.length > 1) {
+        throw new PmCliError("Extension action flags are mutually exclusive.", EXIT_CODE.USAGE);
+    }
+    return selected[0];
+};
+/** Resolve project or global extension scope while rejecting conflicting scope flags. */
+const resolveScope = (options) => {
+    const projectLike = options.project === true || options.local === true;
+    const global = options.global === true;
+    if (projectLike && global) {
+        throw new PmCliError('Options "--project/--local" and "--global" are mutually exclusive.', EXIT_CODE.USAGE);
+    }
+    return global ? "global" : "project";
+};
+/** Ordered update-check policies from unmanaged and non-GitHub cases through recorded outcomes. */
+const EXTENSION_UPDATE_CHECK_RESOLVERS = [
+    (managedEntry) => managedEntry
+        ? null
+        : {
+            status: "skipped_unmanaged",
+            reason: "extension_not_managed",
+        },
+    (managedEntry) => managedEntry && managedEntry.source.kind !== "github"
+        ? {
+            status: "skipped_non_github",
+            reason: `managed_source_kind_${managedEntry.source.kind}`,
+        }
+        : null,
+    (managedEntry) => {
+        const updateError = typeof managedEntry?.update_error === "string"
+            ? managedEntry.update_error.trim()
+            : "";
+        return updateError.length > 0
+            ? { status: "failed", reason: updateError }
+            : null;
+    },
+    (managedEntry) => {
+        const entry = managedEntry;
+        const checkedAt = typeof entry.last_update_check_at === "string"
+            ? entry.last_update_check_at.trim()
+            : "";
+        if (checkedAt.length === 0) {
+            return null;
+        }
+        const reason = {
+            true: "update_available",
+            false: "up_to_date",
+        }[String(entry.update_available)] ?? "checked_without_commit_baseline";
+        return { status: "checked", reason };
+    },
+];
+/** Project managed-source update metadata into one deterministic update-check result. */
+const resolveUpdateCheckResolution = (managedEntry) => {
+    for (const resolve of EXTENSION_UPDATE_CHECK_RESOLVERS) {
+        const resolution = resolve(managedEntry);
+        if (resolution) {
+            return resolution;
+        }
+    }
+    return {
+        status: "not_checked",
+        reason: "no_update_check_recorded",
+    };
+};
+/**
+ * Assemble a {@link ManagedExtensionSummary} from a directory's resolved identity
+ * (name/version/entry/enabled state) and its managed-state record, projecting the
+ * managed-source provenance and the resolved update-check status. Runtime
+ * activation fields default to "not yet probed" (`runtime_active: null`,
+ * `activation_status: "unknown"`) so a later runtime probe can overlay live state.
+ */
+const buildInstalledExtensionSummary = (identity, scope, managedEntry, updateCheck) => {
+    const managed = managedEntry ?? {};
+    return {
+        name: identity.name,
+        directory: identity.directory,
+        version: identity.version,
+        entry: identity.entry,
+        scope,
+        active: identity.enabled,
+        enabled: identity.enabled,
+        runtime_active: null,
+        activation_status: "unknown",
+        managed: Boolean(managedEntry),
+        source: managed.source,
+        update_available: managed.update_available,
+        last_update_check_at: managed.last_update_check_at,
+        last_update_remote_commit: managed.last_update_remote_commit,
+        update_error: managed.update_error,
+        update_check_status: updateCheck.status,
+        update_check_reason: updateCheck.reason,
+    };
+};
+/** Project the degraded summary retained for a directory without a manifest. */
+const buildMissingManifestInspection = (directoryName, scope, settings, managedEntry) => {
+    const managed = Object.assign({
+        name: directoryName,
+        manifest_version: "unknown",
+        manifest_entry: "unknown",
+    }, managedEntry);
+    const enabled = managedEntry
+        ? isExtensionEnabled(settings, managedEntry.name)
+        : false;
+    return {
+        warning: `extension_manifest_missing:${scope}:${directoryName}`,
+        summary: buildInstalledExtensionSummary({
+            name: managed.name,
+            directory: directoryName,
+            version: managed.manifest_version,
+            entry: managed.manifest_entry,
+            enabled,
+        }, scope, managedEntry, resolveUpdateCheckResolution(managedEntry)),
+    };
+};
+/** Inspect one installed extension directory and project its manifest or warning. */
+const inspectInstalledExtensionDirectory = async (extensionsRoot, directoryName, scope, settings, managedByName, managedByDirectory) => {
+    const extensionDirectory = path.join(extensionsRoot, directoryName);
+    const manifestPath = path.join(extensionDirectory, "manifest.json");
+    const managedDirectoryEntry = managedByDirectory.get(normalizeExtensionNameForMatch(directoryName));
+    if (!(await pathExists(manifestPath))) {
+        return buildMissingManifestInspection(directoryName, scope, settings, managedDirectoryEntry);
+    }
+    const invalidJson = Symbol("invalid-extension-manifest-json");
+    const rawManifest = await fs
+        .readFile(manifestPath, "utf8")
+        .then((contents) => JSON.parse(contents))
+        .catch(() => invalidJson);
+    if (rawManifest === invalidJson) {
+        return {
+            warning: `extension_manifest_invalid_json:${scope}:${directoryName}`,
+        };
+    }
+    const manifest = parseExtensionManifest(rawManifest);
+    if (!manifest) {
+        return { warning: `extension_manifest_invalid:${scope}:${directoryName}` };
+    }
+    const managedEntry = managedByName.get(normalizeExtensionNameForMatch(manifest.name)) ??
+        managedByDirectory.get(normalizeExtensionNameForMatch(directoryName));
+    return {
+        summary: buildInstalledExtensionSummary({
+            name: manifest.name,
+            directory: directoryName,
+            version: manifest.version,
+            entry: manifest.entry,
+            enabled: isExtensionEnabled(settings, manifest.name),
+        }, scope, managedEntry, resolveUpdateCheckResolution(managedEntry)),
+    };
+};
+/** List managed and unmanaged extensions with activation, update, and command summaries. */
+const listInstalledExtensions = async (extensionsRoot, scope, settings, state) => {
+    if (!(await pathExists(extensionsRoot))) {
+        return {
+            extensions: [],
+            warnings: [],
+        };
+    }
+    const entries = await fs.readdir(extensionsRoot, { withFileTypes: true });
+    const directories = entries
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name)
+        .sort((left, right) => left.localeCompare(right));
+    const managedByName = new Map(state.entries.map((managedEntry) => [
+        normalizeExtensionNameForMatch(managedEntry.name),
+        managedEntry,
+    ]));
+    const managedByDirectory = new Map(state.entries.map((managedEntry) => [
+        normalizeExtensionNameForMatch(managedEntry.directory),
+        managedEntry,
+    ]));
+    const warnings = [];
+    const summaries = [];
+    for (const directoryName of directories) {
+        const inspected = await inspectInstalledExtensionDirectory(extensionsRoot, directoryName, scope, settings, managedByName, managedByDirectory);
+        if (inspected.warning) {
+            warnings.push(inspected.warning);
+        }
+        if (inspected.summary) {
+            summaries.push(inspected.summary);
+        }
+    }
+    return {
+        extensions: summaries.sort((left, right) => left.name.localeCompare(right.name)),
+        warnings: warnings.sort((left, right) => left.localeCompare(right)),
+    };
+};
+const extensionRuntimeProbeQueue = createSerialQueue();
+/** Return stable runtime command paths registered by one extension. */
+const 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)),
+    };
+};
+/** Resolve the package vocabulary name used in extension command discovery. */
+const resolveCommandDiscoveryPackageName = (extensionName, source) => [source.package, source.kind === "builtin" ? source.name : undefined]
+    .find((candidate) => candidate?.trim())
+    ?.trim() ?? extensionName;
+/** Build post-install command discovery and activation guidance for one extension. */
+const buildInstallCommandDiscovery = (extensionName, source, commandSummary, activationFailure) => {
+    const helpCommands = commandSummary.command_paths.map((commandPath) => `pm ${commandPath} --help`);
+    const sdkDependencyMissing = activationFailure?.error.toLowerCase().includes("@unbrained/pm-cli") ===
+        true;
+    const nextSteps = commandSummary.command_paths.length > 0
+        ? [...helpCommands]
+        : [
+            "Run pm package doctor --project --detail deep if expected package commands are missing.",
+        ];
+    if (sdkDependencyMissing) {
+        nextSteps.unshift("Install @unbrained/pm-cli in the target workspace so declarative package runtime imports resolve, then reinstall the package.");
+    }
+    return {
+        package_name: resolveCommandDiscoveryPackageName(extensionName, source),
+        extension_name: extensionName,
+        command_paths: commandSummary.command_paths,
+        action_paths: commandSummary.action_paths,
+        help_commands: helpCommands,
+        next_steps: nextSteps,
+        ...(sdkDependencyMissing ? { sdk_dependency_status: "missing" } : {}),
+    };
+};
+/** Project one activation failure into a bounded diagnostic summary. */
+const summarizeActivationFailureForDiagnostics = (failure) => {
+    const trace = failure.trace;
+    const summary = {
+        layer: failure.layer,
+        name: failure.name,
+        entry_path: failure.entry_path,
+        error: failure.error,
+    };
+    if (!trace)
+        return summary;
+    summary.trace = Object.fromEntries(Object.entries(trace).filter(([, value]) => value !== undefined));
+    if (trace.missing_capability) {
+        summary.missing_capability = trace.missing_capability;
+    }
+    if (trace.hint)
+        summary.hint = trace.hint;
+    return summary;
+};
+/** Collect activation failures that match one extension identity. */
+const collectActivationFailureDiagnostics = (failures) => {
+    return failures
+        .map((failure) => summarizeActivationFailureForDiagnostics(failure))
+        .sort((left, right) => `${left.layer}:${left.name}`.localeCompare(`${right.layer}:${right.name}`));
+};
+/** Find the first activation failure matching one normalized extension name. */
+const findActivationFailureByName = (extensionName, failures, layer) => {
+    const normalizedName = normalizeExtensionNameForMatch(extensionName);
+    return failures.find((failure) => (layer === undefined || failure.layer === layer) &&
+        normalizeExtensionNameForMatch(failure.name) === normalizedName);
+};
+/** Resolve post-install runtime activation status from load and activation evidence. */
+const resolveInstallRuntimeActivationStatus = (extensionName, scope, runtimeInstalled, installActivationFailure) => {
+    const runtimeInstalledExtension = runtimeInstalled.find((entry) => entry.scope === scope &&
+        normalizeExtensionNameForMatch(entry.name) ===
+            normalizeExtensionNameForMatch(extensionName));
+    return (runtimeInstalledExtension?.activation_status ??
+        (installActivationFailure ? "failed" : "unknown"));
+};
+/** Probe a temporary installed extension for runtime command registrations. */
+const probeRuntimeCommandPathsForInstall = (pmRoot, settings, refreshedInstalled, global) => {
+    return extensionRuntimeProbeQueue.enqueue(async () => {
+        const originalPackageRoot = process.env.PM_CLI_PACKAGE_ROOT;
+        process.env.PM_CLI_PACKAGE_ROOT = resolvePmPackageRootFromModule(import.meta.url, ["../.."]);
+        try {
+            const loadResult = await loadExtensions({
+                pmRoot,
+                settings,
+                cwd: process.cwd(),
+                noExtensions: global.noExtensions === true,
+                reload_token: nextExtensionReloadToken(),
+                cache_bust: true,
+            });
+            const activationResult = await activateExtensions({
+                ...loadResult,
+                loaded: loadResult.loaded,
+            });
+            const runtimeFailures = [
+                ...loadResult.failed.map((failure) => ({
+                    layer: failure.layer,
+                    name: failure.name,
+                    entry_path: failure.entry_path,
+                    error: failure.error,
+                })),
+                ...collectActivationFailureDiagnostics(activationResult.failed),
+            ];
+            return {
+                installed: applyDoctorRuntimeActivationState(refreshedInstalled, loadResult, activationResult),
+                warnings: [...loadResult.warnings, ...activationResult.warnings],
+                activation_failures: runtimeFailures,
+                extensions_disabled: loadResult.disabled_by_flag,
+                item_type_registrations: activationResult.registrations.item_types,
+            };
+        }
+        finally {
+            if (originalPackageRoot === undefined) {
+                delete process.env.PM_CLI_PACKAGE_ROOT;
+            }
+            else {
+                process.env.PM_CLI_PACKAGE_ROOT = originalPackageRoot;
+            }
+        }
+    });
+};
+/** Adopt unmanaged extension directories into deterministic managed state. */
+const adoptUnmanagedExtensions = async (extensionsRoot, scope, installedExtensions, state) => {
+    const unmanagedCandidates = installedExtensions.filter((entry) => !entry.managed);
+    const sortedCandidates = [...unmanagedCandidates].sort((left, right) => {
+        const byName = left.name.localeCompare(right.name);
+        if (byName !== 0) {
+            return byName;
+        }
+        return left.directory.localeCompare(right.directory);
+    });
+    let nextState = state;
+    const adoptedEntries = [];
+    for (const candidate of sortedCandidates) {
+        const extensionDirectory = path.join(extensionsRoot, candidate.directory);
+        const validated = await validateExtensionDirectory(extensionDirectory);
+        const now = nowIso();
+        const sourceRecord = {
+            kind: "local",
+            input: candidate.name,
+            location: extensionDirectory,
+        };
+        nextState = upsertManagedEntry(nextState, {
+            name: validated.manifest.name,
+            directory: candidate.directory,
+            scope,
+            manifest_version: validated.manifest.version,
+            manifest_entry: validated.manifest.entry,
+            capabilities: [...validated.manifest.capabilities],
+            installed_at: now,
+            updated_at: now,
+            source: sourceRecord,
+        });
+        adoptedEntries.push({
+            name: validated.manifest.name,
+            directory: candidate.directory,
+            version: validated.manifest.version,
+            entry: validated.manifest.entry,
+            source: sourceRecord,
+        });
+    }
+    if (adoptedEntries.length > 0) {
+        await writeManagedExtensionState(extensionsRoot, nextState);
+    }
+    return {
+        state: nextState,
+        adopted_entries: adoptedEntries,
+        unmanaged_candidates: sortedCandidates,
+        already_managed_count: installedExtensions.length - unmanagedCandidates.length,
+    };
+};
+/** Resolve project and global extension roots for one lifecycle scope. */
+const resolveExtensionRootsForScope = (scope, global) => {
+    const pmRoot = resolvePmRoot(process.cwd(), global.path);
+    const roots = resolveExtensionRoots(pmRoot, process.cwd());
+    const settingsRoot = scope === "global" ? resolveGlobalPmRoot(process.cwd()) : pmRoot;
+    const selectedRoot = scope === "global" ? roots.global : roots.project;
+    return {
+        pm_root: pmRoot,
+        scope,
+        settings_root: settingsRoot,
+        selected_root: selectedRoot,
+        roots,
+    };
+};
+/** Normalize the GitHub repository option accepted by extension lifecycle actions. */
+const resolveGithubOption = (options) => {
+    const values = [options.gh, options.github]
+        .filter((value) => typeof value === "string")
+        .map((value) => value.trim())
+        .filter(Boolean);
+    const uniqueValues = [...new Set(values)];
+    if (uniqueValues.length > 1) {
+        throw new PmCliError('Options "--gh" and "--github" must match when both are provided.', EXIT_CODE.USAGE);
+    }
+    return uniqueValues[0];
+};
+/** Return the canonical command-line flag for one extension lifecycle action. */
+const getLifecycleActionFlag = (action) => {
+    return LIFECYCLE_ACTION_FLAGS[action];
+};
+/** Throw structured recovery guidance for a missing lifecycle target. */
+const throwMissingLifecycleTarget = (action, options) => {
+    const noun = options.vocabulary === "package" ? "package" : "extension";
+    const targetName = action === "install" ? "source" : "name";
+    const targetLabel = `${noun} ${targetName}`;
+    const actionFlag = getLifecycleActionFlag(action);
+    const commandTarget = `<${targetName}>`;
+    const command = `pm ${noun} ${actionFlag} ${commandTarget}`;
+    throw new PmCliError(`Action "${action}" requires ${targetLabel} input.`, EXIT_CODE.USAGE, {
+        code: "missing_lifecycle_target",
+        required: `Provide a ${targetName} target for ${action}.`,
+        examples: [
+            `pm ${noun} ${action} ${commandTarget}`,
+            command,
+            `pm ${noun} --help`,
+        ],
+        recovery: {
+            attempted_command: `pm ${noun} ${action}`,
+            suggested_retry: command,
+            fallback_candidates: [
+                {
+                    source: "lifecycle_action",
+                    command,
+                    reason: `flag-form ${action} command with required ${targetName} target`,
+                },
+            ],
+        },
+    });
+};
+/** Return a required lifecycle target or throw structured usage guidance. */
+const requireTarget = (target, action, options = {}) => {
+    const normalized = target?.trim();
+    if (normalized)
+        return normalized;
+    if (action === "init") {
+        throw new PmCliError('Action "init" requires a scaffold target path (for example: pm package init ./my-package or pm extension init ./my-extension).', EXIT_CODE.USAGE);
+    }
+    return throwMissingLifecycleTarget(action, options);
+};
+/** Collect doctor warnings for unsafe global output override registrations. */
+const collectGlobalOutputOverrideDoctorWarnings = (activationResult) => {
+    const warnings = [];
+    for (const entry of activationResult.services.overrides) {
+        if (entry.service !== "output_format") {
+            continue;
+        }
+        warnings.push(`extension_output_service_override_global:${entry.service}:${entry.layer}:${entry.name}`);
+    }
+    for (const entry of activationResult.renderers.overrides) {
+        warnings.push(`extension_output_renderer_override_global:${entry.format}:${entry.layer}:${entry.name}`);
+    }
+    return [...new Set(warnings)].sort((left, right) => left.localeCompare(right));
+};
+/**
+ * Doctor advisory: flag loaded extensions that contribute GLOBAL schema (custom
+ * item types or fields) yet also declare narrow `activation.commands`.
+ *
+ * Custom item types and fields must be present for the built-in commands the
+ * extension does not own and cannot enumerate (`pm create <type>`,
+ * `pm list --type <type>`, `pm validate`). Declaring `activation.commands` gates
+ * lazy activation to only the listed command paths, so the package never
+ * activates for those built-ins and its custom type silently fails to register —
+ * a quiet footgun (decision pm-halx). The `schema` scaffold deliberately omits
+ * the field; this advisory catches hand-authored packages that do not. It is
+ * doctor-only and non-blocking — `pm health` does not surface it — so the author
+ * can either drop `activation.commands` or, when the schema is intentionally
+ * command-scoped, knowingly ignore the hint.
+ */
+const collectSchemaNarrowActivationDoctorWarnings = (loadResult, activationResult) => {
+    const schemaContributors = new Set([
+        ...activationResult.registrations.item_types.map((entry) => ({
+            entry,
+            count: entry.types.length,
+        })),
+        ...activationResult.registrations.item_fields.map((entry) => ({
+            entry,
+            count: entry.fields.length,
+        })),
+    ]
+        .filter(({ count }) => count > 0)
+        .map(({ entry }) => `${entry.layer}:${normalizeExtensionNameForMatch(entry.name)}`));
+    return loadResult.loaded
+        .filter((extension) => (extension.activation?.commands ?? []).length > 0)
+        .filter((extension) => schemaContributors.has(`${extension.layer}:${normalizeExtensionNameForMatch(extension.name)}`))
+        .map((extension) => `extension_schema_narrow_activation:${extension.layer}:${extension.name}`)
+        .filter((warning, index, warnings) => warnings.indexOf(warning) === index)
+        .sort((left, right) => left.localeCompare(right));
+};
+/** Reject option/action combinations that are only meaningful for a specific lifecycle action — `--trace`/`--strict-exit`/`--fail-on-warn` require `--doctor`, `--watch` requires `--reload`, `--runtime-probe` requires `--manage`, `--fix-managed-state` requires `--manage`/`--doctor`, and `--capability`/`--declarative` require `--init`/`--scaffold`. Each guard pairs a "flag is set" predicate with the action(s) that permit it and throws a USAGE error on the first mismatch. */
+const assertExtensionActionOptionScope = (action, options) => {
+    const guards = [
+        {
+            triggered: options.strictExit === true || options.failOnWarn === true,
+            allowed: action === "doctor",
+            message: "--strict-exit and --fail-on-warn are only valid with --doctor.",
+        },
+        {
+            triggered: options.trace === true,
+            allowed: action === "doctor",
+            message: "--trace is only valid with --doctor.",
+        },
+        {
+            triggered: options.watch === true,
+            allowed: action === "reload",
+            message: "--watch is only valid with --reload.",
+        },
+        {
+            triggered: options.runtimeProbe === true,
+            allowed: action === "manage",
+            message: "--runtime-probe is only valid with --manage.",
+        },
+        {
+            triggered: options.fixManagedState === true,
+            allowed: action === "manage" || action === "doctor",
+            message: "--fix-managed-state is only valid with --manage or --doctor.",
+        },
+        {
+            triggered: options.isolated === true || options.ignoreGlobal === true,
+            allowed: action === "doctor",
+            message: "--isolated and --ignore-global are only valid with --doctor.",
+        },
+        {
+            triggered: options.capability !== undefined,
+            allowed: action === "init",
+            message: "--capability is only valid with --init/--scaffold.",
+        },
+        {
+            triggered: options.declarative === true,
+            allowed: action === "init",
+            message: "--declarative is only valid with --init/--scaffold.",
+        },
+    ];
+    const invalidGuard = guards.find((guard) => guard.triggered && !guard.allowed);
+    if (invalidGuard) {
+        throw new PmCliError(invalidGuard.message, EXIT_CODE.USAGE);
+    }
+};
+/* c8 ignore start -- alias-normalization matrix is covered by resolveAction tests; this only rewrites positional aliases */
+/** Collapse a positional target that merely repeats the action keyword (`pm extension doctor`, `reload`, `catalog`, or `init`/`scaffold`) to `undefined` so the action handlers treat it as "no target" rather than an extension name; otherwise the original target is returned unchanged. */
+const resolveNormalizedExtensionTarget = (target, action, options) => {
+    const normalizedInput = String(target ?? "")
+        .trim()
+        .toLowerCase();
+    const explicitInitAction = [options.init, options.scaffold].includes(true);
+    const aliases = {
+        doctor: ["doctor"],
+        reload: ["reload"],
+        catalog: ["catalog"],
+        init: explicitInitAction ? [] : ["init", "scaffold"],
+    };
+    return (aliases[action] ?? []).includes(normalizedInput) ? undefined : target;
+};
+/* c8 ignore stop */
+/** Resolve stable roots for lifecycle results, including field-projected catalogs. */
+const resolveExtensionResultRoots = (ctx) => {
+    const projectedCatalog = [
+        ctx.action === "catalog",
+        typeof ctx.options.fields === "string",
+        String(ctx.options.fields).trim().length > 0,
+    ].every(Boolean);
+    return projectedCatalog
+        ? {
+            project: "project",
+            global: "global",
+            selected: ctx.scope,
+            settings_root: "project",
+        }
+        : {
+            project: ctx.resolvedRoots.roots.project,
+            global: ctx.resolvedRoots.roots.global,
+            selected: ctx.resolvedRoots.selected_root,
+            settings_root: ctx.resolvedRoots.settings_root,
+        };
+};
+/** Build and mark one canonical lifecycle result envelope. */
+const buildExtensionActionResult = (ctx, details, ok) => {
+    const result = {
+        ok,
+        action: ctx.action,
+        scope: ctx.scope,
+        roots: resolveExtensionResultRoots(ctx),
+        warnings: [...new Set(ctx.warnings)].sort((left, right) => left.localeCompare(right)),
+        details,
+    };
+    if (ctx.action === "doctor") {
+        Object.defineProperty(result, NATIVE_OUTPUT_MARKER, {
+            value: true,
+            enumerable: false,
+            configurable: false,
+        });
+    }
+    return result;
+};
+/**
+ * Entry point for the `pm extension` / `pm package` command surface. Resolves the
+ * requested lifecycle action and scope, rejects out-of-scope option usage,
+ * normalizes positional aliases, then dispatches to the matching action handler —
+ * each of which reads and writes managed-extension state, runtime-probes, and
+ * returns the canonical {@link ExtensionCommandResult}. `--doctor` results are
+ * flagged for native (non-JSON-wrapped) output.
+ */
+export const runExtension = async (target, options, global) => {
+    const action = resolveAction(target, options);
+    assertExtensionActionOptionScope(action, options);
+    const normalizedTarget = resolveNormalizedExtensionTarget(target, action, options);
+    const scope = resolveScope(options);
+    const resolvedRoots = resolveExtensionRootsForScope(scope, global);
+    const warnings = [];
+    const actionContext = {
+        action,
+        normalizedTarget,
+        scope,
+        resolvedRoots,
+        warnings,
+        options,
+        global,
+    };
+    /** Build the canonical lifecycle result envelope for this invocation. */
+    const withResult = (details, ok = true) => buildExtensionActionResult(actionContext, details, ok);
+    const ctx = {
+        ...actionContext,
+        withResult,
+    };
+    return await dispatchExtensionAction(ctx);
+};
+/** Build copy-pasteable setup and validation guidance for a fresh scaffold. */
+const buildExtensionScaffoldNextSteps = (scaffold, options) => {
+    const vocabulary = options.vocabulary ?? "extension";
+    const shellTargetPath = scaffold.target_path.replace(/\\/g, "/");
+    const quotedShellTargetPath = quoteCommandArg(shellTargetPath);
+    const dependencySteps = {
+        package: `Install dependencies: cd ${quotedShellTargetPath}, then run "npm install"`,
+        extension: `Install type-check dependencies: cd ${quotedShellTargetPath}, then run "npm install -D typescript @types/node @unbrained/pm-cli"`,
+    };
+    const validationSteps = {
+        package: `Validate the package: cd ${quotedShellTargetPath}, then run "npm run typecheck" and "npm test"`,
+        extension: `Type-check the source (optional): cd ${quotedShellTargetPath}, then run "npx tsc --noEmit"`,
+    };
+    const declarativeGuidance = [];
+    if ([vocabulary === "package", options.declarative === true].every(Boolean)) {
+        declarativeGuidance.push("Ensure the target workspace can resolve @unbrained/pm-cli before installing this declarative package.");
+    }
+    return [
+        dependencySteps[vocabulary],
+        ...declarativeGuidance,
+        `Install the scaffold: ${renderPmCommand(vocabulary === "package"
+            ? ["install", "--project", shellTargetPath]
+            : ["extension", "--install", "--project", shellTargetPath])}`,
+        `Smoke-test command path: pm ${scaffold.command_name}`,
+        validationSteps[vocabulary],
+        `Run diagnostics: ${vocabulary === "package" ? "pm package doctor" : "pm extension --doctor"} --project --detail summary`,
+    ];
+};
+/** Scaffold a new extension project from normalized lifecycle options. */
+const runExtensionInitAction = async (ctx) => {
+    const { action, normalizedTarget, options, withResult } = ctx;
+    const githubOption = resolveGithubOption(options);
+    const disallowedSourceOptions = [githubOption, options.ref]
+        .filter((value) => typeof value === "string")
+        .map((value) => value.trim())
+        .filter(Boolean);
+    if (disallowedSourceOptions.length > 0) {
+        throw new PmCliError('Action "init" does not accept --gh/--github/--ref options.', EXIT_CODE.USAGE);
+    }
+    const scaffoldTarget = requireTarget(normalizedTarget, action, options);
+    const scaffold = await scaffoldExtensionProject(scaffoldTarget, options.vocabulary ?? "extension", options.capability, options.declarative === true);
+    return withResult({
+        scaffolded: scaffold.created_directory ||
+            scaffold.files.some((entry) => entry.status === "created"),
+        extension: {
+            name: scaffold.extension_name,
+            command: scaffold.command_name,
+        },
+        capability: scaffold.capability,
+        style: scaffold.style,
+        target_path: scaffold.target_path,
+        created_directory: scaffold.created_directory,
+        files: scaffold.files,
+        next_steps: buildExtensionScaffoldNextSteps(scaffold, options),
+    });
+};
+/** Reload extension runtime state and report the new generation token. */
+const runExtensionReloadAction = async (ctx) => {
+    const { normalizedTarget, resolvedRoots, warnings, options, global, withResult, } = ctx;
+    if (normalizedTarget !== undefined) {
+        throw new PmCliError('Action "reload" does not accept a target argument.', EXIT_CODE.USAGE);
+    }
+    const settings = await readSettings(resolvedRoots.settings_root);
+    const reloadToken = nextExtensionReloadToken();
+    const reloaded = await loadExtensions({
+        pmRoot: resolvedRoots.settings_root,
+        settings,
+        cwd: process.cwd(),
+        noExtensions: global.noExtensions,
+        reload_token: reloadToken,
+        cache_bust: true,
+    });
+    warnings.push(...reloaded.warnings);
+    const activation = await activateExtensions(reloaded);
+    warnings.push(...activation.warnings);
+    const details = {
+        reload: {
+            token: reloadToken,
+            cache_bust: true,
+            watch: options.watch === true,
+        },
+        loaded_count: reloaded.loaded.length,
+        failed_count: reloaded.failed.length,
+        activated_count: Math.max(0, reloaded.loaded.length - activation.failed.length),
+        activation_failed_count: activation.failed.length,
+        loaded_extensions: reloaded.loaded.map((entry) => ({
+            name: entry.name,
+            layer: entry.layer,
+            version: entry.version,
+        })),
+        failed_extensions: reloaded.failed.map((entry) => ({
+            name: entry.name,
+            layer: entry.layer,
+            error: entry.error,
+        })),
+        activation_failures: activation.failed.map((entry) => ({
+            name: entry.name,
+            layer: entry.layer,
+            error: entry.error,
+        })),
+    };
+    if (options.watch === true) {
+        warnings.push("extension_reload_watch_hint:watch_mode_requested_non_interactive_single_pass_only");
+    }
+    return withResult(details);
+};
+/** List bundled and installed extension catalog entries. */
+const runExtensionCatalogAction = async (ctx) => {
+    const { normalizedTarget, scope, options, global, withResult } = ctx;
+    if (typeof normalizedTarget === "string" &&
+        normalizedTarget.length > 0 &&
+        normalizedTarget !== "catalog") {
+        throw new PmCliError('Action "catalog" does not accept a package target.', EXIT_CODE.USAGE);
+    }
+    return withResult(await buildBundledPackageCatalog(scope, global, options));
+};
+/* c8 ignore start -- source-shape branch combinations are exercised in install-source focused tests */
+/** Build managed provenance for a bundled first-party extension alias. */
+const buildBundledInstallManagedSource = (alias, packageName) => ({
+    kind: "builtin",
+    input: alias,
+    location: alias,
+    name: alias,
+    ...(packageName === null ? {} : { package: packageName }),
+});
+/** Build managed provenance for a local extension source. */
+const buildLocalInstallManagedSource = (source) => ({
+    kind: "local",
+    input: source.input,
+    location: source.absolute_path,
+});
+/** Build managed provenance for an npm extension source. */
+const buildNpmInstallManagedSource = (source, resolved) => ({
+    kind: "npm",
+    input: source.input,
+    location: resolved.resolved_subpath ?? ".",
+    package: resolved.npm_package,
+    version: resolved.npm_version,
+});
+/** Build managed provenance for a GitHub extension source. */
+const buildGithubInstallManagedSource = (source, resolved) => ({
+    kind: "github",
+    input: source.input,
+    location: resolved.resolved_subpath ?? source.subpath ?? ".",
+    repository: source.repository,
+    owner: source.owner,
+    repo: source.repo,
+    ref: source.ref,
+    subpath: resolved.resolved_subpath ?? source.subpath,
+    commit: resolved.commit,
+});
+/** Build the persisted managed-source record for an install from its resolved shape: a bundled builtin alias, a local path, an npm package, or (the default) a GitHub repository, capturing the location/commit/subpath provenance the manage and upgrade flows later read back. */
+const buildInstallManagedSource = (bundledAliasName, bundledPackageName, installSource, resolvedSource) => {
+    if (bundledAliasName) {
+        return buildBundledInstallManagedSource(bundledAliasName, bundledPackageName);
+    }
+    if (installSource.kind === "local") {
+        return buildLocalInstallManagedSource(installSource);
+    }
+    if (installSource.kind === "npm") {
+        return buildNpmInstallManagedSource(installSource, resolvedSource);
+    }
+    return buildGithubInstallManagedSource(installSource, resolvedSource);
+};
+/** Preserve original install time and only advance update time when source content changed. */
+const resolveManagedInstallTimestamps = (existing, manifestVersion, source, now) => {
+    if (!existing)
+        return { installed_at: now, updated_at: now };
+    if (existing.manifest_version !== manifestVersion) {
+        return { installed_at: existing.installed_at, updated_at: now };
+    }
+    if (!managedExtensionSourcesEquivalent(existing.source, source)) {
+        return { installed_at: existing.installed_at, updated_at: now };
+    }
+    return {
+        installed_at: existing.installed_at,
+        updated_at: existing.updated_at,
+    };
+};
+/** Copy and persist one validated extension before its runtime activation probe. */
+const persistExtensionInstall = async (ctx, input) => {
+    const { scope, resolvedRoots, warnings } = ctx;
+    const { validated, destinationDirectoryName } = input;
+    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 });
+    const backupRoot = await fs.mkdtemp(path.join(resolvedRoots.selected_root, ".pm-extension-install-backup-"));
+    const backupDirectory = path.join(backupRoot, "destination");
+    try {
+        const snapshot = await captureExtensionInstallSnapshot(resolvedRoots.selected_root, resolvedRoots.settings_root, destinationDirectory, destinationExists, backupDirectory);
+        const sourceRecord = buildInstallManagedSource(input.bundledAliasName, input.bundledPackageName, input.installSource, input.resolvedSource);
+        const existingManagedEntry = managedStateRead.state.entries.find((entry) => normalizeExtensionNameForMatch(entry.name) ===
+            normalizeExtensionNameForMatch(validated.manifest.name));
+        const timestamps = resolveManagedInstallTimestamps(existingManagedEntry, validated.manifest.version, sourceRecord, nowIso());
+        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],
+            ...timestamps,
+            source: sourceRecord,
+        });
+        const activationChanged = ensureActivated(settings, validated.manifest.name);
+        try {
+            if (!installInPlace) {
+                await copyExtensionDirectoryForInstall(validated.directory, destinationDirectory);
+            }
+            await ensureExtensionModuleTypeMarker(destinationDirectory);
+            await writeManagedExtensionState(resolvedRoots.selected_root, managedState);
+            if (activationChanged) {
+                await writeSettings(resolvedRoots.settings_root, settings, "settings:write");
+            }
+        }
+        catch (error) {
+            try {
+                await restoreExtensionInstallSnapshot(snapshot);
+            }
+            catch (rollbackError) {
+                throw new AggregateError([error, rollbackError], `Extension install failed: ${String(error)}; rollback failed: ${String(rollbackError)}`, { cause: rollbackError });
+            }
+            throw error;
+        }
+        return {
+            settings,
+            managedState,
+            sourceRecord,
+            destinationDirectory,
+            destinationExists,
+            installInPlace,
+            activationChanged,
+        };
+    }
+    finally {
+        await fs
+            .rm(backupRoot, { recursive: true, force: true })
+            .catch(() => undefined);
+    }
+};
+/** Scaffold project folders contributed by item types from the installed extension. */
+const scaffoldInstalledExtensionItemTypes = async (ctx, extensionName, registrations) => {
+    const definitions = registrations
+        .filter((entry) => normalizeExtensionNameForMatch(entry.name) ===
+        normalizeExtensionNameForMatch(extensionName))
+        .flatMap((entry) => entry.types.map((type) => ({ name: type.name, folder: type.folder })));
+    if (ctx.scope === "project" && definitions.length > 0) {
+        await ensureTypeFolderScaffold(ctx.resolvedRoots.pm_root, definitions, ctx.warnings, "install:type-folder");
+    }
+    return definitions;
+};
+/** Resolve post-install activation state, warnings, and health verification. */
+const buildInstalledExtensionActivation = (ctx, extensionName, runtimeProbe, commandSummary, installedItemTypes) => {
+    const failure = findActivationFailureByName(extensionName, runtimeProbe.activation_failures, ctx.scope);
+    const status = resolveInstallRuntimeActivationStatus(extensionName, ctx.scope, runtimeProbe.installed, failure);
+    const activated = [!runtimeProbe.extensions_disabled, status === "ok"].every(Boolean);
+    if (!activated) {
+        ctx.warnings.push(`extension_install_activation_failed:${ctx.scope}:${extensionName}:${status}`);
+    }
+    const healthByActivation = {
+        true: { status: "ok", blocking_failure_count: 0 },
+        false: { status: "degraded", blocking_failure_count: 1 },
+    };
+    return {
+        activated,
+        status,
+        failure,
+        verification: {
+            status: healthByActivation[String(activated)].status,
+            target_pm_root: ctx.resolvedRoots.pm_root,
+            activation_status: status,
+            activated,
+            registered_commands: commandSummary.command_paths,
+            registered_actions: commandSummary.action_paths,
+            registered_item_types: installedItemTypes,
+            health: healthByActivation[String(activated)],
+        },
+    };
+};
+/** Run the install body while holding the scope-wide install lock: read settings and managed state, copy the validated extension into the scope root unless it is already installed in place, upsert the managed entry and activation state, scaffold any contributed item-type folders, runtime-probe the freshly installed command paths, and return the install result envelope. */
+const performExtensionInstallUnderLock = async (ctx, input) => {
+    const { scope, resolvedRoots, warnings, global, withResult } = ctx;
+    const { validated, destinationDirectoryName } = input;
+    const persisted = await persistExtensionInstall(ctx, input);
+    const refreshedInstalled = await listInstalledExtensions(resolvedRoots.selected_root, scope, persisted.settings, persisted.managedState);
+    warnings.push(...refreshedInstalled.warnings);
+    const runtimeProbe = await probeRuntimeCommandPathsForInstall(resolvedRoots.pm_root, persisted.settings, refreshedInstalled.extensions, global);
+    warnings.push(...runtimeProbe.warnings);
+    // Scaffold the folders for any item types the installed package contributes
+    // so the tracker is immediately healthy — matching `pm schema add-type` and
+    // `pm profile apply`, the other paths that register a type. Without this a
+    // freshly-installed schema package leaves a `missing_directory` health
+    // warning until the first item of its type is created. Scoped to project
+    // installs, where `pm_root` is unambiguously the tracker the type folders
+    // belong to; a global install is not tied to one tracker, so its folders are
+    // created lazily on first use in each project.
+    const installedItemTypeDefinitions = await scaffoldInstalledExtensionItemTypes(ctx, validated.manifest.name, runtimeProbe.item_type_registrations);
+    const commandSummary = summarizeRuntimeCommandPathsForExtension(validated.manifest.name, runtimeProbe.installed);
+    const activation = buildInstalledExtensionActivation(ctx, validated.manifest.name, runtimeProbe, commandSummary, installedItemTypeDefinitions);
+    return withResult({
+        extension: {
+            name: validated.manifest.name,
+            version: validated.manifest.version,
+            entry: validated.manifest.entry,
+            capabilities: validated.manifest.capabilities,
+            directory: destinationDirectoryName,
+        },
+        source: persisted.sourceRecord,
+        destination_path: persisted.destinationDirectory,
+        overwritten: [
+            persisted.destinationExists,
+            !persisted.installInPlace,
+        ].every(Boolean),
+        installed_in_place: persisted.installInPlace,
+        activated: activation.activated,
+        settings_changed: persisted.activationChanged,
+        runtime_activation_status: activation.status,
+        command_paths: commandSummary.command_paths,
+        action_paths: commandSummary.action_paths,
+        command_discovery: buildInstallCommandDiscovery(validated.manifest.name, persisted.sourceRecord, commandSummary, activation.failure),
+        verification: activation.verification,
+        activation_diagnostics: {
+            failed_count: runtimeProbe.activation_failures.length,
+            failed: runtimeProbe.activation_failures,
+            installed_extension_failed: activation.failure ?? null,
+        },
+    }, activation.activated);
+};
+/** Install every bundled first-party package alias and aggregate verification. */
+const runBundledExtensionInstallAll = async (ctx) => {
+    const { options, global, warnings, withResult } = ctx;
+    if (typeof options.ref === "string" && options.ref.trim().length > 0) {
+        throw new PmCliError('Action "install all" does not accept --ref.', EXIT_CODE.USAGE);
+    }
+    const packages = [];
+    for (const alias of await listBundledPackageAliases()) {
+        packages.push({
+            alias,
+            result: await runExtension(alias, { ...options, install: true }, global),
+        });
+    }
+    warnings.push(...packages.flatMap((entry) => entry.result.warnings));
+    const installedAll = packages.every((entry) => entry.result.ok);
+    return withResult({
+        installed_all: installedAll,
+        installed_count: packages.filter((entry) => entry.result.ok).length,
+        failed_count: packages.filter((entry) => !entry.result.ok).length,
+        packages: packages.map((entry) => {
+            const details = entry.result.details;
+            return {
+                alias: entry.alias,
+                ok: entry.result.ok,
+                extension: details.extension,
+                source: details.source,
+                destination_path: details.destination_path,
+                activated: details.activated,
+                settings_changed: details.settings_changed,
+                command_paths: details.command_paths,
+                action_paths: details.action_paths,
+                command_discovery: details.command_discovery,
+                verification: details.verification,
+                runtime_activation_status: details.runtime_activation_status,
+                activation_diagnostics: details.activation_diagnostics,
+                warnings: entry.result.warnings,
+            };
+        }),
+    }, installedAll);
+};
+/** Resolve bundled-alias provenance before installing one extension source. */
+const resolveSingleExtensionInstallSource = async (explicitSourceInput, githubOption, ref) => {
+    /* c8 ignore start -- github/local alias-source split is exercised in install-action integration tests */
+    const bundledAliasSource = typeof githubOption === "string"
+        ? null
+        : await resolveBundledExtensionAliasSource(explicitSourceInput);
+    /* c8 ignore stop */
+    const bundledAliasName = bundledAliasSource === null
+        ? null
+        : explicitSourceInput.trim().toLowerCase();
+    const bundledPackageName = bundledAliasName === null
+        ? null
+        : await resolveBundledPackageNpmName(bundledAliasName);
+    const sourceInput = bundledAliasSource ?? explicitSourceInput;
+    /* c8 ignore start -- install-source branch combinations are covered in install-sources focused tests */
+    const installSource = parseExtensionInstallSource(sourceInput, {
+        forceGithub: typeof githubOption === "string",
+        ref,
+    });
+    /* c8 ignore stop */
+    return { bundledAliasName, bundledPackageName, installSource };
+};
+/** Install one resolved source and clean transient source material afterward. */
+const runSingleExtensionInstall = async (ctx, explicitSourceInput, githubOption) => {
+    const { resolvedRoots } = ctx;
+    const { bundledAliasName, bundledPackageName, installSource } = await resolveSingleExtensionInstallSource(explicitSourceInput, githubOption, ctx.options.ref);
+    const resolvedSource = await resolveInstallSource(installSource);
+    try {
+        const validated = await validateExtensionDirectory(resolvedSource.directory);
+        const destinationDirectoryName = normalizeManagedDirectoryName(validated.manifest.name);
+        return await withExtensionInstallLock(resolvedRoots.settings_root, destinationDirectoryName, () => performExtensionInstallUnderLock(ctx, {
+            validated,
+            destinationDirectoryName,
+            bundledAliasName,
+            bundledPackageName,
+            installSource,
+            resolvedSource,
+        }));
+    }
+    finally {
+        /* c8 ignore start -- cleanup hooks are only present for transient install sources */
+        if (resolvedSource.cleanup) {
+            await resolvedSource.cleanup();
+        }
+        /* c8 ignore stop */
+    }
+};
+/** Install one extension source under the owner-bound lifecycle lock. */
+const runExtensionInstallAction = async (ctx) => {
+    const githubOption = resolveGithubOption(ctx.options);
+    const explicitSourceInput = githubOption ??
+        requireTarget(ctx.normalizedTarget, ctx.action, ctx.options);
+    if ([
+        githubOption === undefined,
+        isBundledPackageInstallAllTarget(explicitSourceInput),
+    ].every(Boolean)) {
+        return runBundledExtensionInstallAll(ctx);
+    }
+    return runSingleExtensionInstall(ctx, explicitSourceInput, githubOption);
+};
+/** Adopt every eligible unmanaged extension in the selected scope. */
+const runExtensionAdoptAllAction = async (ctx) => {
+    const { normalizedTarget, scope, resolvedRoots, warnings, options, withResult, } = ctx;
+    if (normalizedTarget !== undefined) {
+        throw new PmCliError('Action "adopt-all" does not accept a target argument.', EXIT_CODE.USAGE);
+    }
+    const githubOption = resolveGithubOption(options);
+    if (githubOption !== undefined ||
+        (typeof options.ref === "string" && options.ref.trim().length > 0)) {
+        throw new PmCliError('Action "adopt-all" does not accept --gh/--github/--ref options.', EXIT_CODE.USAGE);
+    }
+    const settings = await readSettings(resolvedRoots.settings_root);
+    const managedStateRead = await readManagedExtensionState(resolvedRoots.selected_root);
+    warnings.push(...managedStateRead.warnings);
+    const installed = await listInstalledExtensions(resolvedRoots.selected_root, scope, settings, managedStateRead.state);
+    warnings.push(...installed.warnings);
+    const adoption = await adoptUnmanagedExtensions(resolvedRoots.selected_root, scope, installed.extensions, managedStateRead.state);
+    const refreshedInstalled = await listInstalledExtensions(resolvedRoots.selected_root, scope, settings, adoption.state);
+    warnings.push(...refreshedInstalled.warnings);
+    const triage = buildExtensionTriageSummary(scope, warnings, refreshedInstalled.extensions, options);
+    warnings.push(...triage.warnings);
+    /* c8 ignore start -- refresh-entry optional metadata is display-only and exercised indirectly */
+    const refreshedByIdentity = new Map(refreshedInstalled.extensions.map((entry) => [
+        `${normalizeExtensionNameForMatch(entry.name)}:${normalizeExtensionNameForMatch(entry.directory)}`,
+        entry,
+    ]));
+    const refreshedByDirectory = new Map(refreshedInstalled.extensions.map((entry) => [
+        normalizeExtensionNameForMatch(entry.directory),
+        entry,
+    ]));
+    const adoptedDetails = adoption.adopted_entries.map((entry) => {
+        const normalizedDirectory = normalizeExtensionNameForMatch(entry.directory);
+        const refreshedEntry = refreshedByIdentity.get(`${normalizeExtensionNameForMatch(entry.name)}:${normalizedDirectory}`) ?? refreshedByDirectory.get(normalizedDirectory);
+        return { ...entry, ...projectExtensionUpdateCheck(refreshedEntry) };
+    });
+    /* c8 ignore stop */
+    /* c8 ignore start -- adopt-all summary booleans are deterministic mirrors of adoptedDetails length */
+    return withResult({
+        adopted_all: adoptedDetails.length > 0,
+        adopted_count: adoptedDetails.length,
+        already_managed_count: adoption.already_managed_count,
+        extensions: adoptedDetails,
+        triage,
+        warning_codes: triage.warning_codes,
+        update_health_partial: triage.update_health_partial,
+        update_health_coverage: triage.update_health_coverage,
+    });
+    /* c8 ignore stop */
+};
+/** Project nullable update-check metadata for adopt result payloads. */
+const projectExtensionUpdateCheck = (entry) => {
+    return {
+        update_check_status: entry?.update_check_status ?? null,
+        update_check_reason: entry?.update_check_reason ?? null,
+    };
+};
+/** Resolve local or GitHub provenance for an adopted extension. */
+const buildAdoptedExtensionSource = (githubOption, extensionTarget, extensionDirectory, ref) => {
+    if (githubOption === undefined) {
+        return {
+            kind: "local",
+            input: extensionTarget,
+            location: extensionDirectory,
+        };
+    }
+    const parsed = parseExtensionInstallSource(githubOption, {
+        forceGithub: true,
+        ref,
+    });
+    /* c8 ignore start -- forceGithub guarantees a github-kind install source */
+    if (parsed.kind !== "github") {
+        throw new PmCliError(`Invalid GitHub shorthand "${githubOption}".`, EXIT_CODE.USAGE);
+    }
+    /* c8 ignore stop */
+    return {
+        kind: "github",
+        input: parsed.input,
+        location: parsed.subpath ?? ".",
+        repository: parsed.repository,
+        owner: parsed.owner,
+        repo: parsed.repo,
+        ref: parsed.ref,
+        subpath: parsed.subpath,
+    };
+};
+/** Adopt one unmanaged extension into managed lifecycle state. */
+const runExtensionAdoptAction = async (ctx) => {
+    const { action, normalizedTarget, scope, resolvedRoots, warnings, options, withResult, } = ctx;
+    const extensionTarget = requireTarget(normalizedTarget, action, options);
+    const githubOption = resolveGithubOption(options);
+    const settings = await readSettings(resolvedRoots.settings_root);
+    const managedStateRead = await readManagedExtensionState(resolvedRoots.selected_root);
+    warnings.push(...managedStateRead.warnings);
+    const installed = await listInstalledExtensions(resolvedRoots.selected_root, scope, settings, managedStateRead.state);
+    warnings.push(...installed.warnings);
+    const candidate = await resolveInstalledExtensionCandidate(installed.extensions, extensionTarget);
+    if (!candidate) {
+        throw new PmCliError(`Installed extension "${extensionTarget}" was not found in ${scope} scope.`, EXIT_CODE.NOT_FOUND);
+    }
+    if (candidate.managed) {
+        return withResult({
+            adopted: false,
+            already_managed: true,
+            extension: {
+                name: candidate.name,
+                directory: candidate.directory,
+            },
+        });
+    }
+    const extensionDirectory = path.join(resolvedRoots.selected_root, candidate.directory);
+    const validated = await validateExtensionDirectory(extensionDirectory);
+    const now = nowIso();
+    const sourceRecord = buildAdoptedExtensionSource(githubOption, extensionTarget, extensionDirectory, options.ref);
+    const managedState = upsertManagedEntry(managedStateRead.state, {
+        name: validated.manifest.name,
+        directory: candidate.directory,
+        scope,
+        manifest_version: validated.manifest.version,
+        manifest_entry: validated.manifest.entry,
+        capabilities: [...validated.manifest.capabilities],
+        installed_at: now,
+        updated_at: now,
+        source: sourceRecord,
+    });
+    await writeManagedExtensionState(resolvedRoots.selected_root, managedState);
+    const refreshedInstalled = await listInstalledExtensions(resolvedRoots.selected_root, scope, settings, managedState);
+    warnings.push(...refreshedInstalled.warnings);
+    /* c8 ignore start -- fallback only matters if a manifest renames between adopt and refresh */
+    const refreshedEntry = refreshedInstalled.extensions.find((entry) => normalizeExtensionNameForMatch(entry.name) ===
+        normalizeExtensionNameForMatch(validated.manifest.name)) ??
+        refreshedInstalled.extensions.find((entry) => normalizeExtensionNameForMatch(entry.directory) ===
+            normalizeExtensionNameForMatch(candidate.directory));
+    /* c8 ignore stop */
+    /* c8 ignore start -- adopt result mirrors refreshedEntry optionals for display only */
+    return withResult({
+        adopted: true,
+        extension: {
+            name: validated.manifest.name,
+            directory: candidate.directory,
+            version: validated.manifest.version,
+            entry: validated.manifest.entry,
+        },
+        source: sourceRecord,
+        ...projectExtensionUpdateCheck(refreshedEntry),
+    });
+    /* c8 ignore stop */
+};
+/** Resolve a required installed extension or throw structured not-found guidance. */
+const resolveRequiredInstalledExtension = async (ctx) => {
+    const { action, normalizedTarget, scope, resolvedRoots, warnings, options } = ctx;
+    const extensionTarget = requireTarget(normalizedTarget, action, options);
+    const settings = await readSettings(resolvedRoots.settings_root);
+    const managedStateRead = await readManagedExtensionState(resolvedRoots.selected_root);
+    warnings.push(...managedStateRead.warnings);
+    const installed = await listInstalledExtensions(resolvedRoots.selected_root, scope, settings, managedStateRead.state);
+    warnings.push(...installed.warnings);
+    const candidate = await resolveInstalledExtensionCandidate(installed.extensions, extensionTarget);
+    if (!candidate) {
+        throw new PmCliError(`Installed extension "${extensionTarget}" was not found in ${scope} scope.`, EXIT_CODE.NOT_FOUND);
+    }
+    return { settings, managedStateRead, candidate };
+};
+/** Uninstall one managed extension and update lifecycle state. */
+const runExtensionUninstallAction = async (ctx) => {
+    const { resolvedRoots, withResult } = ctx;
+    const { settings, managedStateRead, candidate } = await resolveRequiredInstalledExtension(ctx);
+    const destinationDirectory = path.join(resolvedRoots.selected_root, candidate.directory);
+    await fs.rm(destinationDirectory, { recursive: true, force: true });
+    const updatedState = {
+        ...managedStateRead.state,
+        updated_at: nowIso(),
+        /* c8 ignore start -- uninstall filter keeps both name+directory guards for legacy managed-state migrations */
+        entries: managedStateRead.state.entries.filter((entry) => normalizeExtensionNameForMatch(entry.name) !==
+            normalizeExtensionNameForMatch(candidate.name) &&
+            normalizeExtensionNameForMatch(entry.directory) !==
+                normalizeExtensionNameForMatch(candidate.directory)),
+        /* c8 ignore stop */
+    };
+    await writeManagedExtensionState(resolvedRoots.selected_root, updatedState);
+    const stateChanged = clearExtensionState(settings, candidate.name);
+    if (stateChanged) {
+        await writeSettings(resolvedRoots.settings_root, settings, "settings:write");
+    }
+    return withResult({
+        removed: true,
+        extension: {
+            name: candidate.name,
+            directory: candidate.directory,
+        },
+        destination_path: destinationDirectory,
+        settings_changed: stateChanged,
+    });
+};
+/** Activate or deactivate one installed extension and persist the resulting state. */
+const runExtensionActivateDeactivateAction = async (ctx) => {
+    const { action, resolvedRoots, withResult } = ctx;
+    const { settings, candidate } = await resolveRequiredInstalledExtension(ctx);
+    const settingsChanged = action === "activate"
+        ? ensureActivated(settings, candidate.name)
+        : ensureDeactivated(settings, candidate.name);
+    if (settingsChanged) {
+        await writeSettings(resolvedRoots.settings_root, settings, "settings:write");
+    }
+    return withResult({
+        extension: {
+            name: candidate.name,
+            directory: candidate.directory,
+        },
+        active: action === "activate",
+        settings_changed: settingsChanged,
+        settings: {
+            enabled: [...settings.extensions.enabled],
+            disabled: [...settings.extensions.disabled],
+        },
+    });
+};
+/** Assemble the doctor remediation hints: the triage remediations, vocabulary-aware advice to inspect load failures and activation failures, and a note when a managed-state fix adopted entries. Blank entries are trimmed and the list is de-duplicated. */
+const buildDoctorRemediation = (baseRemediation, loadFailureCount, activationFailureCount, vocabulary, managedStateFix, isolationHint) => {
+    const noun = vocabulary === "package" ? "package" : "extension";
+    const doctorAction = { package: "doctor", extension: "--doctor" }[noun];
+    const adoptedCount = managedStateFix?.adopted_entries.length ?? 0;
+    const conditionalEntries = [
+        [isolationHint !== null, isolationHint ?? ""],
+        [
+            loadFailureCount > 0,
+            `Run pm ${noun} explore --project and pm ${noun} explore --global to inspect load failures.`,
+        ],
+        [
+            activationFailureCount > 0,
+            `Review activation failures in pm ${noun} ${doctorAction} --detail deep output.`,
+        ],
+        [
+            adoptedCount > 0,
+            `Managed-state fix adopted ${adoptedCount} extension(s).`,
+        ],
+    ];
+    return [
+        ...new Set([
+            ...baseRemediation,
+            ...conditionalEntries
+                .filter(([include]) => include)
+                .map(([, entry]) => entry),
+        ]
+            .map((entry) => entry.trim())
+            .filter((entry) => entry.length > 0)),
+    ];
+};
+/** Return whether doctor details contain any global-layer diagnostics. */
+const hasGlobalLayerDiagnostics = (loadResult) => {
+    return (loadResult.loaded.some((entry) => entry.layer === "global") ||
+        loadResult.failed.some((entry) => entry.layer === "global") ||
+        loadResult.warnings.some((warning) => warning.includes(":global:")));
+};
+/** Build the project-isolation remediation hint for global extension conflicts. */
+const buildDoctorIsolationHint = (scope, isolated, vocabulary, loadResult) => {
+    if (scope !== "project" ||
+        isolated ||
+        !hasGlobalLayerDiagnostics(loadResult)) {
+        return null;
+    }
+    const noun = vocabulary === "package" ? "package" : "extension";
+    return (`Global ${noun} registrations are included in project diagnostics. ` +
+        `For hermetic ${noun} smoke tests, rerun pm ${noun} doctor --project --isolated --detail deep --trace, ` +
+        "or set PM_GLOBAL_PATH to a temporary directory for the whole test process.");
+};
+/** Validate doctor-only arguments and return normalized execution switches. */
+const resolveDoctorInvocationOptions = (target, scope, options) => {
+    if (String(target ?? "").trim().length > 0) {
+        throw new PmCliError('Action "doctor" does not accept a target argument.', EXIT_CODE.USAGE);
+    }
+    const isolated = [options.isolated, options.ignoreGlobal].includes(true);
+    if ([isolated, scope === "global"].every(Boolean)) {
+        throw new PmCliError("--isolated and --ignore-global are only valid with project-scope doctor diagnostics.", EXIT_CODE.USAGE);
+    }
+    const detailMode = parseDoctorDetailMode(options.detail);
+    const includeTrace = options.trace === true;
+    if ([includeTrace, detailMode !== "deep"].every(Boolean)) {
+        throw new PmCliError("--trace requires --detail deep with --doctor.", EXIT_CODE.USAGE);
+    }
+    return { isolated, detailMode, includeTrace };
+};
+/** Optionally adopt unmanaged entries requested by doctor and return effective state. */
+const applyDoctorManagedStateFix = async (ctx, installed, state) => {
+    if (ctx.options.fixManagedState !== true)
+        return { state, fix: null };
+    const fix = await adoptUnmanagedExtensions(ctx.resolvedRoots.selected_root, ctx.scope, installed, state);
+    return { state: fix.state, fix };
+};
+/** Build the doctor isolation block shared by summary and details output so the over-the-wire payload stays identical for extension and package vocabulary. */
+const buildDoctorIsolationMetadata = (scope, isolated, vocabulary, loadResult) => {
+    const noun = vocabulary === "package" ? "package" : "extension";
+    if (scope !== "project") {
+        return {
+            isolated,
+            global_extensions_included: false,
+            global_diagnostics_present: hasGlobalLayerDiagnostics(loadResult),
+            rerun_command: null,
+            pm_global_path_recipe: null,
+        };
+    }
+    const isolatedCommand = `pm ${noun} doctor --project --isolated --detail deep --trace`;
+    return {
+        isolated,
+        global_extensions_included: !isolated,
+        global_diagnostics_present: hasGlobalLayerDiagnostics(loadResult),
+        rerun_command: isolated ? null : isolatedCommand,
+        pm_global_path_recipe: `PM_GLOBAL_PATH=$(mktemp -d) pm ${noun} doctor --project --detail deep --trace`,
+    };
+};
+/** Run extension integrity, activation, policy, and isolation diagnostics. */
+const runExtensionDoctorAction = async (ctx) => {
+    const { normalizedTarget, scope, resolvedRoots, warnings, options, global, withResult, } = ctx;
+    const { isolated, detailMode, includeTrace } = resolveDoctorInvocationOptions(normalizedTarget, scope, options);
+    const settings = await readSettings(resolvedRoots.settings_root);
+    const managedStateRead = await readManagedExtensionState(resolvedRoots.selected_root);
+    warnings.push(...managedStateRead.warnings);
+    const installed = await listInstalledExtensions(resolvedRoots.selected_root, scope, settings, managedStateRead.state);
+    warnings.push(...installed.warnings);
+    const { state: managedState, fix: managedStateFix } = await applyDoctorManagedStateFix(ctx, installed.extensions, managedStateRead.state);
+    const refreshedInstalled = await listInstalledExtensions(resolvedRoots.selected_root, scope, settings, managedState);
+    warnings.push(...refreshedInstalled.warnings);
+    const loadResult = await loadExtensions({
+        pmRoot: resolvedRoots.pm_root,
+        settings,
+        cwd: process.cwd(),
+        noExtensions: global.noExtensions === true,
+        ignoreGlobalExtensions: isolated,
+    });
+    const activationResult = await activateExtensions({
+        ...loadResult,
+        loaded: loadResult.loaded,
+    });
+    warnings.push(...loadResult.warnings);
+    warnings.push(...classifyDoctorLoadFailureWarnings(loadResult.failed));
+    warnings.push(...activationResult.warnings);
+    warnings.push(...classifyDoctorActivationFailureWarnings(activationResult.failed));
+    warnings.push(...classifyUnusedCapabilityWarnings(loadResult, activationResult));
+    warnings.push(...collectGlobalOutputOverrideDoctorWarnings(activationResult));
+    warnings.push(...collectSchemaNarrowActivationDoctorWarnings(loadResult, activationResult));
+    const runtimeInstalledExtensions = applyDoctorRuntimeActivationState(refreshedInstalled.extensions, loadResult, activationResult);
+    const doctorConsistency = buildDoctorConsistencySummary(scope, runtimeInstalledExtensions, loadResult.loaded.map((entry) => ({
+        layer: entry.layer,
+        name: entry.name,
+    })), loadResult.failed.map((entry) => ({ name: entry.name })), loadResult.disabled_by_flag);
+    warnings.push(...doctorConsistency.warnings);
+    const updateCheckWarnings = runtimeInstalledExtensions
+        .filter((entry) => entry.update_check_status === "failed")
+        .map((entry) => `extension_update_check_failed:${entry.name}`);
+    warnings.push(...updateCheckWarnings);
+    const triage = buildExtensionTriageSummary(scope, warnings, runtimeInstalledExtensions, options);
+    warnings.push(...triage.warnings);
+    const normalizedWarnings = [...triage.warnings];
+    const policySummary = {
+        mode: loadResult.policy.mode,
+        trust_mode: loadResult.policy.trust_mode,
+        require_provenance: loadResult.policy.require_provenance,
+        default_sandbox_profile: loadResult.policy.default_sandbox_profile,
+        // Honest trust model (ADR pm-6ef3): keep this caveat to one concise line.
+        sandbox_enforcement: "advisory: sandbox_profile/permissions are declaration-based load gates, not runtime isolation (ADR pm-6ef3)",
+        trusted_extensions_count: loadResult.policy.trusted_extensions.length,
+        allowed_extensions_count: loadResult.policy.allowed_extensions.length,
+        blocked_extensions_count: loadResult.policy.blocked_extensions.length,
+        allowed_capabilities_count: loadResult.policy.allowed_capabilities.length,
+        blocked_capabilities_count: loadResult.policy.blocked_capabilities.length,
+        allowed_surfaces_count: loadResult.policy.allowed_surfaces.length,
+        blocked_surfaces_count: loadResult.policy.blocked_surfaces.length,
+        allowed_commands_count: loadResult.policy.allowed_commands.length,
+        blocked_commands_count: loadResult.policy.blocked_commands.length,
+        allowed_actions_count: loadResult.policy.allowed_actions.length,
+        blocked_actions_count: loadResult.policy.blocked_actions.length,
+        allowed_services_count: loadResult.policy.allowed_services.length,
+        blocked_services_count: loadResult.policy.blocked_services.length,
+        extension_override_count: loadResult.policy.extension_overrides.length,
+    };
+    const capabilityGuidance = collectUnknownCapabilityGuidance(normalizedWarnings);
+    const capabilityContract = buildCapabilityContractMetadata();
+    const warningCodes = triage.warning_codes;
+    const isolationHint = buildDoctorIsolationHint(scope, isolated, options.vocabulary, loadResult);
+    const remediation = buildDoctorRemediation(triage.remediation, loadResult.failed.length, activationResult.failed.length, options.vocabulary, managedStateFix, isolationHint);
+    const isolation = buildDoctorIsolationMetadata(scope, isolated, options.vocabulary, loadResult);
+    const summary = {
+        status: triage.status,
+        scope,
+        warning_count: triage.warning_count,
+        warning_codes: warningCodes,
+        total_extensions: runtimeInstalledExtensions.length,
+        managed_total: runtimeInstalledExtensions.filter((entry) => entry.managed)
+            .length,
+        enabled_total: runtimeInstalledExtensions.filter((entry) => entry.enabled)
+            .length,
+        active_total: runtimeInstalledExtensions.filter((entry) => entry.active)
+            .length,
+        unmanaged_loaded_extension_count: triage.unmanaged_loaded_extension_count,
+        unmanaged_action_required_extension_count: triage.unmanaged_action_required_extension_count,
+        unmanaged_expected_extension_count: triage.unmanaged_expected_extension_count,
+        runtime_active_total: runtimeInstalledExtensions.filter((entry) => entry.runtime_active === true).length,
+        activation_status_totals: {
+            ok: runtimeInstalledExtensions.filter((entry) => entry.activation_status === "ok").length,
+            failed: runtimeInstalledExtensions.filter((entry) => entry.activation_status === "failed").length,
+            not_loaded: runtimeInstalledExtensions.filter((entry) => entry.activation_status === "not_loaded").length,
+            unknown: runtimeInstalledExtensions.filter((entry) => entry.activation_status === "unknown").length,
+        },
+        unknown_capability_count: capabilityGuidance.length,
+        capability_contract_version: capabilityContract.version,
+        update_available_total: runtimeInstalledExtensions.filter((entry) => entry.update_available === true).length,
+        update_health_coverage: triage.update_health_coverage,
+        update_health_partial: triage.update_health_partial,
+        update_check_failed_total: runtimeInstalledExtensions.filter((entry) => entry.update_check_status === "failed").length,
+        load_failure_count: loadResult.failed.length,
+        activation_failure_count: activationResult.failed.length,
+        blocking_failure_count: loadResult.failed.length + activationResult.failed.length,
+        has_blocking_failures: loadResult.failed.length + activationResult.failed.length > 0,
+        consistency_warning_count: doctorConsistency.warnings.length,
+        trace_enabled: includeTrace,
+        isolation,
+        policy: policySummary,
+        remediation,
+    };
+    const managedStateFixSummary = managedStateFix
+        ? {
+            requested: true,
+            applied: managedStateFix.adopted_entries.length > 0,
+            adopted_count: managedStateFix.adopted_entries.length,
+            already_managed_count: managedStateFix.already_managed_count,
+            adopted_extensions: managedStateFix.adopted_entries.map((entry) => entry.name),
+        }
+        : {
+            requested: false,
+            applied: false,
+            adopted_count: 0,
+            already_managed_count: refreshedInstalled.extensions.filter((entry) => entry.managed).length,
+            adopted_extensions: [],
+        };
+    const details = {
+        mode: detailMode,
+        summary,
+        triage,
+        trace_enabled: includeTrace,
+        capability_contract: capabilityContract,
+        capability_guidance: capabilityGuidance,
+        managed_state_fix: managedStateFixSummary,
+        isolation,
+        policy: loadResult.policy,
+    };
+    if (detailMode === "deep") {
+        const activationFailedDetails = includeTrace
+            ? activationResult.failed
+            : activationResult.failed.map((entry) => {
+                const { trace: _trace, ...rest } = entry;
+                return rest;
+            });
+        details.deep = {
+            warnings: normalizedWarnings,
+            warning_codes: warningCodes,
+            capability_contract: capabilityContract,
+            capability_guidance: capabilityGuidance,
+            trace_enabled: includeTrace,
+            managed_state: {
+                path: managedStateRead.path,
+                count: managedState.entries.length,
+                entries: managedState.entries,
+            },
+            installed_extensions: runtimeInstalledExtensions,
+            load: {
+                roots: loadResult.roots,
+                policy: loadResult.policy,
+                warnings: loadResult.warnings,
+                failed: loadResult.failed,
+                loaded: loadResult.loaded.map((entry) => ({
+                    layer: entry.layer,
+                    directory: entry.directory,
+                    name: entry.name,
+                    version: entry.version,
+                    entry: entry.entry,
+                    priority: entry.priority,
+                })),
+            },
+            activation: {
+                failed: activationFailedDetails,
+                warnings: activationResult.warnings,
+                hook_counts: activationResult.hook_counts,
+                registration_counts: activationResult.registration_counts,
+                parser_override_count: activationResult.parser_override_count,
+                preflight_override_count: activationResult.preflight_override_count,
+                service_override_count: activationResult.service_override_count,
+                renderer_override_count: activationResult.renderer_override_count,
+            },
+            consistency: doctorConsistency.summary,
+        };
+        if (includeTrace) {
+            details.deep.trace = {
+                activation_failures: activationResult.failed
+                    .filter((entry) => entry.trace !== undefined)
+                    .map((entry) => ({
+                    layer: entry.layer,
+                    name: entry.name,
+                    entry_path: entry.entry_path,
+                    error: entry.error,
+                    method: entry.trace.method,
+                    command: entry.trace.command,
+                    capability: entry.trace.capability,
+                    missing_capability: entry.trace.missing_capability,
+                    registration_index: entry.trace.registration_index,
+                    expected_schema: entry.trace.expected_schema,
+                    hint: entry.trace.hint,
+                    received: entry.trace.received,
+                })),
+            };
+        }
+    }
+    return withResult(details);
+};
+/** Describe one installed extension and its runtime registrations. */
+const runExtensionDescribeAction = async (ctx) => {
+    const { normalizedTarget, scope, resolvedRoots, warnings, options, global, withResult, } = ctx;
+    const settings = await readSettings(resolvedRoots.settings_root);
+    const loadResult = await loadExtensions({
+        pmRoot: resolvedRoots.pm_root,
+        settings,
+        cwd: process.cwd(),
+        noExtensions: global.noExtensions === true,
+    });
+    const activationResult = await activateExtensions(loadResult);
+    warnings.push(...loadResult.warnings);
+    warnings.push(...activationResult.warnings);
+    const describeResult = buildExtensionDescribeResult(normalizedTarget, loadResult, activationResult);
+    if (normalizedTarget !== undefined &&
+        describeResult.extensions.length === 0) {
+        const noun = options.vocabulary === "package" ? "package" : "extension";
+        const loadedNames = [
+            ...new Set(loadResult.loaded.map((entry) => options.vocabulary === "package" &&
+                typeof entry.source_package === "string" &&
+                entry.source_package.trim().length > 0
+                ? entry.source_package.trim()
+                : entry.name)),
+        ].sort((left, right) => left.localeCompare(right));
+        const loadedHint = loadedNames.length > 0
+            ? ` Loaded ${noun} names: ${loadedNames.join(", ")}.`
+            : "";
+        throw new PmCliError(`No loaded ${noun} named "${normalizedTarget}" was found in ${scope} scope.${loadedHint} Run pm ${noun} explore to list discovered ${noun}s.`, EXIT_CODE.NOT_FOUND);
+    }
+    return withResult({
+        target: describeResult.target,
+        total: describeResult.total,
+        extensions: describeResult.extensions,
+        union: describeResult.union,
+    });
+};
+/* c8 ignore start -- explore/manage action split is validated by dedicated command-action tests */
+/** Apply manage-only adoption and remote update checks to managed extension state. */
+const prepareExploreManageState = async (ctx, installed, initialState) => {
+    let state = initialState;
+    let fix = null;
+    if ([ctx.action === "manage", ctx.options.fixManagedState === true].every(Boolean)) {
+        fix = await adoptUnmanagedExtensions(ctx.resolvedRoots.selected_root, ctx.scope, installed, initialState);
+        state = fix.state;
+    }
+    if (ctx.action === "manage") {
+        const entries = await mapWithFixedConcurrency(state.entries, GITHUB_UPDATE_CHECK_CONCURRENCY, async (entry) => {
+            if (entry.source.kind !== "github")
+                return entry;
+            const updateStatus = await checkGithubUpdate(entry.source);
+            return {
+                ...entry,
+                last_update_check_at: updateStatus.checked_at,
+                last_update_remote_commit: updateStatus.remote_commit,
+                update_available: updateStatus.available,
+                update_error: updateStatus.error,
+            };
+        });
+        state = {
+            ...state,
+            updated_at: nowIso(),
+            entries: sortManagedEntries(entries),
+        };
+        await writeManagedExtensionState(ctx.resolvedRoots.selected_root, state);
+    }
+    return { state, fix };
+};
+/** Runtime-probe explore by default and manage only when explicitly requested. */
+const probeExploreManageRuntime = async (ctx, settings, installed) => {
+    const requested = [
+        ctx.action === "explore",
+        ctx.options.runtimeProbe === true,
+    ].includes(true);
+    if (!requested) {
+        return {
+            installed,
+            failures: undefined,
+            summary: { requested: false, executed: false },
+        };
+    }
+    const loadResult = await loadExtensions({
+        pmRoot: ctx.resolvedRoots.pm_root,
+        settings,
+        cwd: process.cwd(),
+        noExtensions: ctx.global.noExtensions === true,
+    });
+    const activationResult = await activateExtensions({
+        ...loadResult,
+        loaded: loadResult.loaded,
+    });
+    ctx.warnings.push(...loadResult.warnings, ...activationResult.warnings);
+    return {
+        installed: applyDoctorRuntimeActivationState(installed, loadResult, activationResult),
+        failures: collectActivationFailureDiagnostics(activationResult.failed),
+        summary: {
+            requested: true,
+            executed: true,
+            reason: ctx.action === "explore"
+                ? "explore_defaults_to_runtime_probe"
+                : "runtime_probe_requested",
+            load_failure_count: loadResult.failed.length,
+            activation_failure_count: activationResult.failed.length,
+            warning_count: [
+                ...new Set([...loadResult.warnings, ...activationResult.warnings]),
+            ].length,
+            policy: loadResult.policy,
+        },
+    };
+};
+/** Project manage-only adoption details without coupling them to runtime probing. */
+const projectExploreManageFix = (fix, installed) => fix
+    ? {
+        requested: true,
+        applied: fix.adopted_entries.length > 0,
+        adopted_count: fix.adopted_entries.length,
+        adopted_extensions: fix.adopted_entries.map((entry) => entry.name),
+        already_managed_count: fix.already_managed_count,
+    }
+    : {
+        requested: false,
+        applied: false,
+        adopted_count: 0,
+        adopted_extensions: [],
+        already_managed_count: installed.filter((entry) => entry.managed)
+            .length,
+    };
+/** Explore installed extensions or mutate managed lifecycle state. */
+const runExtensionExploreManageAction = async (ctx) => {
+    const { action, scope, resolvedRoots, warnings, options, withResult } = ctx;
+    const settings = await readSettings(resolvedRoots.settings_root);
+    const configuredPolicy = buildExtensionPolicyDetails(settings.extensions.policy);
+    const managedStateRead = await readManagedExtensionState(resolvedRoots.selected_root);
+    warnings.push(...managedStateRead.warnings);
+    const installed = await listInstalledExtensions(resolvedRoots.selected_root, scope, settings, managedStateRead.state);
+    warnings.push(...installed.warnings);
+    const { state: managedState, fix: managedStateFix } = await prepareExploreManageState(ctx, installed.extensions, managedStateRead.state);
+    const refreshedInstalled = await listInstalledExtensions(resolvedRoots.selected_root, scope, settings, managedState);
+    warnings.push(...refreshedInstalled.warnings);
+    if (action === "manage") {
+        const updateWarnings = refreshedInstalled.extensions
+            .filter((entry) => entry.update_check_status === "failed")
+            .map((entry) => `extension_update_check_failed:${entry.name}`);
+        warnings.push(...updateWarnings);
+    }
+    const runtimeProbe = await probeExploreManageRuntime(ctx, settings, refreshedInstalled.extensions);
+    const runtimeInstalledExtensions = runtimeProbe.installed;
+    const triage = buildExtensionTriageSummary(scope, warnings, runtimeInstalledExtensions, options);
+    warnings.push(...triage.warnings);
+    const details = {
+        total: runtimeInstalledExtensions.length,
+        managed_total: runtimeInstalledExtensions.filter((entry) => entry.managed)
+            .length,
+        enabled_total: runtimeInstalledExtensions.filter((entry) => entry.enabled)
+            .length,
+        active_total: runtimeInstalledExtensions.filter((entry) => entry.active)
+            .length,
+        extensions: runtimeInstalledExtensions,
+        triage,
+        policy: configuredPolicy,
+    };
+    if (runtimeProbe.failures !== undefined) {
+        details.activation_diagnostics = {
+            failed_count: runtimeProbe.failures.length,
+            failed: runtimeProbe.failures,
+        };
+    }
+    if (action === "explore") {
+        details.runtime_probe = runtimeProbe.summary;
+    }
+    if (action === "manage") {
+        details.runtime_probe = runtimeProbe.summary;
+        details.managed_state_fix = projectExploreManageFix(managedStateFix, runtimeInstalledExtensions);
+    }
+    return withResult(details);
+};
+/* c8 ignore stop */
+// Dispatch table from lifecycle action to its handler. `explore`/`manage` and
+// `activate`/`deactivate` share a handler that branches on `ctx.action`; the
+// closed ExtensionCommandAction union guarantees every action has an entry, so
+// runExtension needs no unsupported-action fallthrough.
+const EXTENSION_ACTION_HANDLERS = {
+    init: runExtensionInitAction,
+    install: runExtensionInstallAction,
+    uninstall: runExtensionUninstallAction,
+    explore: runExtensionExploreManageAction,
+    manage: runExtensionExploreManageAction,
+    describe: runExtensionDescribeAction,
+    reload: runExtensionReloadAction,
+    doctor: runExtensionDoctorAction,
+    catalog: runExtensionCatalogAction,
+    adopt: runExtensionAdoptAction,
+    "adopt-all": runExtensionAdoptAllAction,
+    activate: runExtensionActivateDeactivateAction,
+    deactivate: runExtensionActivateDeactivateAction,
+};
+/** Identify lifecycle actions that mutate shared settings or managed-extension state. */
+const requiresExtensionStateLock = (ctx) => [
+    ctx.action === "uninstall",
+    ctx.action === "manage",
+    ctx.action === "adopt",
+    ctx.action === "adopt-all",
+    ctx.action === "activate",
+    ctx.action === "deactivate",
+    [ctx.action === "doctor", ctx.options.fixManagedState === true].every(Boolean),
+].some(Boolean);
+/** Dispatch one normalized lifecycle action through the complete handler table. */
+const dispatchExtensionAction = (ctx) => requiresExtensionStateLock(ctx)
+    ? withExtensionInstallLock(ctx.resolvedRoots.settings_root, `${ctx.action}-state`, () => EXTENSION_ACTION_HANDLERS[ctx.action](ctx))
+    : EXTENSION_ACTION_HANDLERS[ctx.action](ctx);
+/** Public contract for test only, shared by SDK and presentation-layer consumers. */
+export const _testOnly = {
+    adoptUnmanagedExtensions,
+    buildAdoptedExtensionSource,
+    buildExtensionPolicyDetails,
+    buildInstallCommandDiscovery,
+    checkGithubUpdate,
+    clearExtensionState,
+    collectActivationFailureDiagnostics,
+    findActivationFailureByName,
+    resolveInstallRuntimeActivationStatus,
+    collectGlobalOutputOverrideDoctorWarnings,
+    collectSchemaNarrowActivationDoctorWarnings,
+    copyExtensionDirectoryWithoutSelfNesting,
+    isErrnoCode,
+    isRetriableExtensionInstallCopyError,
+    listInstalledExtensions,
+    mapWithFixedConcurrency,
+    projectExtensionUpdateCheck,
+    readOptionalMetadataFile,
+    requireTarget,
+    resolveAction,
+    resolveCommandDiscoveryPackageName,
+    resolveGithubOption,
+    resolveInstalledExtensionCandidate,
+    resolveScope,
+    resolveUpdateCheckResolution,
+    withExtensionInstallLock,
+};
+//# sourceMappingURL=extension.js.map
+//# debugId=fe21d8bd-795f-5bed-b4fc-e6efe6ee6120