@unbrained/pm-cli 2026.7.14 → 2026.7.16

package/dist/cli/commands/extension.js

@@ -1,2189 +1,10 @@
 /**
  * @module cli/commands/extension
  *
- * Implements the pm extension command surface and its agent-facing runtime behavior.
+ * Compatibility exports for the SDK-owned extension and package engine.
  */
 
-!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]="17d000c7-b19f-540c-9600-65416d2ca11b")}catch(e){}}();
-import { execFile } from "node:child_process";
-import fs from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import { promisify } from "node:util";
-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 { isPathWithinDirectory } from "../../core/fs/path-utils.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 { 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, runGitCommand, } 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";
-// Re-export the public surface that lives in sibling modules but was previously
-// exported from this file (used by sdk barrels, upgrade.ts, and tests).
-export { parseExtensionManifest, validateExtensionDirectory, readManagedExtensionState, writeManagedExtensionState, resolveManagedExtensionStatePath, parseExtensionInstallSource, };
-const execFileAsync = promisify(execFile);
-const EXTENSION_INSTALL_COPY_ATTEMPTS = 3;
-const EXTENSION_INSTALL_LOCK_ATTEMPTS = 120;
-const EXTENSION_INSTALL_LOCK_DELAY_MS = 250;
-const EXTENSION_INSTALL_LOCK_STALE_MS = 120_000;
-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 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: [],
-};
-function 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;
-}
-function appendNonEmptyPolicyLists(target, lists) {
-    for (const field of EXTENSION_POLICY_OVERRIDE_LIST_FIELDS) {
-        if (lists[field].length > 0) {
-            target[field] = lists[field];
-        }
-    }
-    return target;
-}
-function buildExtensionPolicyOverrideDetails(override) {
-    const name = typeof override.name === "string" ? override.name.trim() : "";
-    if (name.length === 0) {
-        return null;
-    }
-    const details = { name };
-    if (override.disabled === true) {
-        details.disabled = true;
-    }
-    if (override.require_trusted === true) {
-        details.require_trusted = true;
-    }
-    if (override.require_provenance === true) {
-        details.require_provenance = true;
-    }
-    if (override.sandbox_profile) {
-        details.sandbox_profile = override.sandbox_profile;
-    }
-    const lists = {};
-    for (const field of EXTENSION_POLICY_OVERRIDE_LIST_FIELDS) {
-        lists[field] = normalizeStringList(override[field] ?? []);
-    }
-    return appendNonEmptyPolicyLists(details, lists);
-}
-function buildExtensionPolicyDetails(policy) {
-    const safePolicy = policy ?? DEFAULT_EXTENSION_POLICY_DETAILS;
-    const rootLists = normalizePolicyRootLists(policy);
-    const overrides = (safePolicy.extension_overrides ?? [])
-        .map((override) => buildExtensionPolicyOverrideDetails(override))
-        .filter((override) => override !== null)
-        .sort((left, right) => left.name.localeCompare(right.name));
-    return {
-        mode: safePolicy.mode ?? DEFAULT_EXTENSION_POLICY_DETAILS.mode,
-        trust_mode: safePolicy.trust_mode ?? DEFAULT_EXTENSION_POLICY_DETAILS.trust_mode,
-        require_provenance: safePolicy.require_provenance === true,
-        trusted_extensions: rootLists.trusted_extensions,
-        default_sandbox_profile: safePolicy.default_sandbox_profile ?? "none",
-        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,
-    };
-}
-function isRetriableExtensionInstallCopyError(error) {
-    if (typeof error !== "object" || error === null || !("code" in error)) {
-        return false;
-    }
-    const code = error.code;
-    return code === "EEXIST" || code === "ENOTEMPTY" || code === "ENOENT";
-}
-function isErrnoCode(error, code) {
-    return (typeof error === "object" &&
-        error !== null &&
-        "code" in error &&
-        error.code === code);
-}
-function sleep(ms) {
-    return new Promise((resolve) => {
-        setTimeout(resolve, ms);
-    });
-}
-/** Ensure the installed extension directory carries a `package.json` with `"type": "module"`. Extension entrypoints are ESM TypeScript; without a nearby package.json Node resolves the module type from the HOST project's package.json, so installs into `"type": "commonjs"` projects fail activation with `extension_load_failed` (pm-r0m4). Extensions that ship their own package.json are left untouched. */
-async function ensureExtensionModuleTypeMarker(destinationDirectory) {
-    const markerPath = path.join(destinationDirectory, "package.json");
-    if (await pathExists(markerPath)) {
-        return;
-    }
-    await fs.writeFile(markerPath, `${JSON.stringify({ type: "module" }, null, 2)}\n`, "utf8");
-}
-/** Implements copy extension directory for install for the public runtime surface of this module. */
-export async function copyExtensionDirectoryForInstall(sourceDirectory, destinationDirectory, copyDirectory = fs.cp) {
-    for (let attempt = 1; attempt <= EXTENSION_INSTALL_COPY_ATTEMPTS; attempt += 1) {
-        try {
-            if (await pathExists(destinationDirectory)) {
-                await fs.rm(destinationDirectory, { recursive: true, force: true });
-            }
-            await copyExtensionDirectoryWithoutSelfNesting(sourceDirectory, destinationDirectory, copyDirectory);
-            return;
-        }
-        catch (error) {
-            if (!isRetriableExtensionInstallCopyError(error) ||
-                attempt === EXTENSION_INSTALL_COPY_ATTEMPTS) {
-                throw error;
-            }
-            await sleep(EXTENSION_INSTALL_LOCK_DELAY_MS);
-        }
-    }
-}
-async function copyExtensionDirectoryWithoutSelfNesting(sourceDirectory, destinationDirectory, copyDirectory) {
-    const resolvedSource = path.resolve(sourceDirectory);
-    const resolvedDestination = path.resolve(destinationDirectory);
-    if (resolvedSource === resolvedDestination) {
-        return;
-    }
-    if (!isPathWithinDirectory(resolvedSource, resolvedDestination)) {
-        await copyDirectory(sourceDirectory, destinationDirectory, {
-            recursive: true,
-            force: true,
-        });
-        return;
-    }
-    const stagingRoot = await fs.mkdtemp(path.join(os.tmpdir(), "pm-extension-copy-"));
-    const stagedDirectory = path.join(stagingRoot, "extension");
-    try {
-        await copyDirectory(sourceDirectory, stagedDirectory, {
-            recursive: true,
-            force: true,
-        });
-        await copyDirectory(stagedDirectory, destinationDirectory, {
-            recursive: true,
-            force: true,
-        });
-    }
-    finally {
-        await fs.rm(stagingRoot, { recursive: true, force: true });
-    }
-}
-async function withExtensionInstallLock(settingsRoot, destinationDirectoryName, run, options) {
-    const lockRoot = path.join(settingsRoot, "runtime", "extension-install-locks");
-    const lockPath = path.join(lockRoot, `${destinationDirectoryName}.lock`);
-    await fs.mkdir(lockRoot, { recursive: true });
-    const attempts = Math.max(1, Math.floor(options?.attempts ?? EXTENSION_INSTALL_LOCK_ATTEMPTS));
-    const delayMs = Math.max(0, Math.floor(options?.delay_ms ?? EXTENSION_INSTALL_LOCK_DELAY_MS));
-    const staleMs = Math.max(0, Math.floor(options?.stale_ms ?? EXTENSION_INSTALL_LOCK_STALE_MS));
-    let acquired = false;
-    for (let attempt = 1; attempt <= attempts; attempt += 1) {
-        try {
-            await fs.mkdir(lockPath);
-            acquired = true;
-            await fs.writeFile(path.join(lockPath, "owner.json"), `${JSON.stringify({ pid: process.pid, created_at: nowIso(), destination: destinationDirectoryName }, null, 2)}\n`, "utf8");
-            break;
-        }
-        catch (error) {
-            if (!isErrnoCode(error, "EEXIST")) {
-                throw error;
-            }
-            let stat = null;
-            try {
-                stat = await fs.stat(lockPath);
-            }
-            catch {
-                stat = null;
-            }
-            if (stat && Date.now() - stat.mtimeMs > staleMs) {
-                await fs.rm(lockPath, { recursive: true, force: true });
-                continue;
-            }
-            await sleep(delayMs);
-        }
-    }
-    if (!acquired) {
-        throw new PmCliError(`Timed out waiting for extension install lock for "${destinationDirectoryName}".`, EXIT_CODE.CONFLICT);
-    }
-    try {
-        return await run();
-    }
-    finally {
-        await fs
-            .rm(lockPath, { recursive: true, force: true })
-            .catch(() => undefined);
-    }
-}
-async function resolveInstalledExtensionCandidate(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;
-}
-function 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);
-}
-function 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"));
-}
-function 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"));
-}
-function 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"));
-}
-function suggestLifecycleActionTarget(target) {
-    const normalizedTarget = target.trim().toLowerCase();
-    const exactMatch = LIFECYCLE_ACTION_TARGETS.find(([candidate]) => candidate === normalizedTarget);
-    if (exactMatch) {
-        return { action: exactMatch[1], flag: exactMatch[2] };
-    }
-    const maxDistance = normalizedTarget.length <= 4 ? 1 : 2;
-    let nearest = null;
-    for (const [candidate, action, flag] of LIFECYCLE_ACTION_TARGETS) {
-        const distance = levenshteinDistanceWithinLimit(normalizedTarget, candidate, maxDistance);
-        if (distance === null) {
-            continue;
-        }
-        if (nearest === null) {
-            nearest = { action, flag, distance };
-            continue;
-        }
-        if (distance < nearest.distance) {
-            nearest = { action, flag, distance };
-        }
-    }
-    return nearest === null
-        ? null
-        : { action: nearest.action, flag: nearest.flag };
-}
-function 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"],
-];
-/** 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. */
-function resolveImplicitActionFromTarget(normalizedTarget) {
-    if (normalizedTarget === "doctor") {
-        return "doctor";
-    }
-    if (normalizedTarget === "reload") {
-        return "reload";
-    }
-    if (normalizedTarget === "catalog") {
-        return "catalog";
-    }
-    if (normalizedTarget === "init" || normalizedTarget === "scaffold") {
-        return "init";
-    }
-    if (normalizedTarget === "explore") {
-        return "explore";
-    }
-    if (normalizedTarget === "manage") {
-        return "manage";
-    }
-    if (normalizedTarget === "list" || normalizedTarget === "") {
-        return "explore";
-    }
-    return null;
-}
-function 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];
-}
-function 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";
-}
-function resolveUpdateCheckResolution(managedEntry) {
-    if (!managedEntry) {
-        return {
-            status: "skipped_unmanaged",
-            reason: "extension_not_managed",
-        };
-    }
-    if (managedEntry.source.kind !== "github") {
-        return {
-            status: "skipped_non_github",
-            reason: `managed_source_kind_${managedEntry.source.kind}`,
-        };
-    }
-    const updateError = typeof managedEntry.update_error === "string"
-        ? managedEntry.update_error.trim()
-        : "";
-    if (updateError.length > 0) {
-        return {
-            status: "failed",
-            reason: updateError,
-        };
-    }
-    if (typeof managedEntry.last_update_check_at === "string" &&
-        managedEntry.last_update_check_at.trim().length > 0) {
-        if (managedEntry.update_available === true) {
-            return {
-                status: "checked",
-                reason: "update_available",
-            };
-        }
-        if (managedEntry.update_available === false) {
-            return {
-                status: "checked",
-                reason: "up_to_date",
-            };
-        }
-        return {
-            status: "checked",
-            reason: "checked_without_commit_baseline",
-        };
-    }
-    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.
- */
-function buildInstalledExtensionSummary(identity, scope, managedEntry, updateCheck) {
-    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: managedEntry?.source,
-        update_available: managedEntry?.update_available,
-        last_update_check_at: managedEntry?.last_update_check_at,
-        last_update_remote_commit: managedEntry?.last_update_remote_commit,
-        update_error: managedEntry?.update_error,
-        update_check_status: updateCheck.status,
-        update_check_reason: updateCheck.reason,
-    };
-}
-async function listInstalledExtensions(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();
-    const managedByDirectory = new Map();
-    for (const managedEntry of state.entries) {
-        managedByName.set(normalizeExtensionNameForMatch(managedEntry.name), managedEntry);
-        managedByDirectory.set(normalizeExtensionNameForMatch(managedEntry.directory), managedEntry);
-    }
-    const warnings = [];
-    const summaries = [];
-    for (const directoryName of directories) {
-        const extensionDirectory = path.join(extensionsRoot, directoryName);
-        const manifestPath = path.join(extensionDirectory, "manifest.json");
-        if (!(await pathExists(manifestPath))) {
-            warnings.push(`extension_manifest_missing:${scope}:${directoryName}`);
-            const managedEntry = managedByDirectory.get(normalizeExtensionNameForMatch(directoryName));
-            summaries.push(buildInstalledExtensionSummary({
-                name: managedEntry?.name ?? directoryName,
-                directory: directoryName,
-                version: managedEntry?.manifest_version ?? "unknown",
-                entry: managedEntry?.manifest_entry ?? "unknown",
-                enabled: managedEntry
-                    ? isExtensionEnabled(settings, managedEntry.name)
-                    : false,
-            }, scope, managedEntry, resolveUpdateCheckResolution(managedEntry)));
-            continue;
-        }
-        let rawManifest;
-        try {
-            rawManifest = JSON.parse(await fs.readFile(manifestPath, "utf8"));
-        }
-        catch {
-            warnings.push(`extension_manifest_invalid_json:${scope}:${directoryName}`);
-            continue;
-        }
-        const manifest = parseExtensionManifest(rawManifest);
-        if (!manifest) {
-            warnings.push(`extension_manifest_invalid:${scope}:${directoryName}`);
-            continue;
-        }
-        const managedEntry = managedByName.get(normalizeExtensionNameForMatch(manifest.name)) ??
-            managedByDirectory.get(normalizeExtensionNameForMatch(directoryName));
-        summaries.push(buildInstalledExtensionSummary({
-            name: manifest.name,
-            directory: directoryName,
-            version: manifest.version,
-            entry: manifest.entry,
-            enabled: isExtensionEnabled(settings, manifest.name),
-        }, scope, managedEntry, resolveUpdateCheckResolution(managedEntry)));
-    }
-    return {
-        extensions: summaries.sort((left, right) => left.name.localeCompare(right.name)),
-        warnings: warnings.sort((left, right) => left.localeCompare(right)),
-    };
-}
-const extensionRuntimeProbeQueue = createSerialQueue();
-function summarizeRuntimeCommandPathsForExtension(extensionName, installed) {
-    const normalizedName = normalizeExtensionNameForMatch(extensionName);
-    const entry = installed.find((candidate) => normalizeExtensionNameForMatch(candidate.name) === normalizedName);
-    return {
-        command_paths: [...(entry?.command_paths ?? [])].sort((left, right) => left.localeCompare(right)),
-        action_paths: [...(entry?.action_paths ?? [])].sort((left, right) => left.localeCompare(right)),
-    };
-}
-function resolveCommandDiscoveryPackageName(extensionName, source) {
-    if (typeof source.package === "string" && source.package.trim().length > 0) {
-        return source.package.trim();
-    }
-    if (source.kind === "builtin" &&
-        typeof source.name === "string" &&
-        source.name.trim().length > 0) {
-        return source.name.trim();
-    }
-    return extensionName;
-}
-function buildInstallCommandDiscovery(extensionName, source, commandSummary, 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" } : {}),
-    };
-}
-function summarizeActivationFailureForDiagnostics(failure) {
-    const trace = failure.trace
-        ? {
-            method: failure.trace.method,
-            registration_index: failure.trace.registration_index,
-            expected_schema: failure.trace.expected_schema,
-            ...(failure.trace.command ? { command: failure.trace.command } : {}),
-            ...(failure.trace.capability
-                ? { capability: failure.trace.capability }
-                : {}),
-            ...(failure.trace.missing_capability
-                ? { missing_capability: failure.trace.missing_capability }
-                : {}),
-            ...(failure.trace.hint ? { hint: failure.trace.hint } : {}),
-        }
-        : undefined;
-    return {
-        layer: failure.layer,
-        name: failure.name,
-        entry_path: failure.entry_path,
-        error: failure.error,
-        ...(failure.trace?.missing_capability
-            ? { missing_capability: failure.trace.missing_capability }
-            : {}),
-        ...(failure.trace?.hint ? { hint: failure.trace.hint } : {}),
-        ...(trace ? { trace } : {}),
-    };
-}
-function collectActivationFailureDiagnostics(failures) {
-    return failures
-        .map((failure) => summarizeActivationFailureForDiagnostics(failure))
-        .sort((left, right) => `${left.layer}:${left.name}`.localeCompare(`${right.layer}:${right.name}`));
-}
-function findActivationFailureByName(extensionName, failures, layer) {
-    const normalizedName = normalizeExtensionNameForMatch(extensionName);
-    return failures.find((failure) => (layer === undefined || failure.layer === layer) &&
-        normalizeExtensionNameForMatch(failure.name) === normalizedName);
-}
-function 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"));
-}
-async function probeRuntimeCommandPathsForInstall(pmRoot, settings, refreshedInstalled, global) {
-    return extensionRuntimeProbeQueue.enqueue(async () => {
-        const originalPackageRoot = process.env.PM_CLI_PACKAGE_ROOT;
-        process.env.PM_CLI_PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(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;
-            }
-        }
-    });
-}
-async function checkGithubUpdate(source, gitCommandRunner = runGitCommand) {
-    const checkedAt = nowIso();
-    if (source.kind !== "github" || !source.repository) {
-        return {
-            checked_at: checkedAt,
-            available: null,
-            error: "not_a_github_managed_source",
-        };
-    }
-    try {
-        const ref = source.ref && source.ref.trim().length > 0 ? source.ref.trim() : "HEAD";
-        const output = await gitCommandRunner([
-            "ls-remote",
-            source.repository,
-            ref,
-        ]);
-        const firstLine = output
-            .split(/\r?\n/)
-            .map((line) => line.trim())
-            .find((line) => line.length > 0);
-        if (!firstLine) {
-            return {
-                checked_at: checkedAt,
-                available: null,
-                error: "no_remote_reference_found",
-            };
-        }
-        const [remoteCommit] = firstLine.split(/\s+/);
-        /* c8 ignore start -- firstLine is trimmed non-empty, so split always yields a non-empty first token */
-        if (typeof remoteCommit !== "string" || remoteCommit.length === 0) {
-            return {
-                checked_at: checkedAt,
-                available: null,
-                error: "invalid_remote_reference",
-            };
-        }
-        /* c8 ignore stop */
-        if (typeof source.commit === "string" && source.commit.trim().length > 0) {
-            return {
-                checked_at: checkedAt,
-                remote_commit: remoteCommit,
-                available: remoteCommit !== source.commit.trim(),
-            };
-        }
-        return {
-            checked_at: checkedAt,
-            remote_commit: remoteCommit,
-            available: null,
-            error: "missing_installed_commit",
-        };
-    }
-    catch (error) {
-        return {
-            checked_at: checkedAt,
-            available: null,
-            error: error instanceof Error ? error.message : String(error),
-        };
-    }
-}
-async function adoptUnmanagedExtensions(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,
-    };
-}
-function 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,
-    };
-}
-function resolveGithubOption(options) {
-    if (typeof options.gh === "string" &&
-        typeof options.github === "string" &&
-        options.gh.trim() !== options.github.trim()) {
-        throw new PmCliError('Options "--gh" and "--github" must match when both are provided.', EXIT_CODE.USAGE);
-    }
-    if (typeof options.gh === "string" && options.gh.trim().length > 0) {
-        return options.gh.trim();
-    }
-    if (typeof options.github === "string" && options.github.trim().length > 0) {
-        return options.github.trim();
-    }
-    return undefined;
-}
-function getLifecycleActionFlag(action) {
-    return LIFECYCLE_ACTION_FLAGS[action];
-}
-function requireTarget(target, action, options = {}) {
-    const normalized = target?.trim();
-    if (!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);
-        }
-        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 normalized;
-}
-function 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.
- */
-function collectSchemaNarrowActivationDoctorWarnings(loadResult, activationResult) {
-    const schemaContributors = new Set();
-    for (const entry of activationResult.registrations.item_types) {
-        if (entry.types.length > 0) {
-            schemaContributors.add(`${entry.layer}:${normalizeExtensionNameForMatch(entry.name)}`);
-        }
-    }
-    for (const entry of activationResult.registrations.item_fields) {
-        if (entry.fields.length > 0) {
-            schemaContributors.add(`${entry.layer}:${normalizeExtensionNameForMatch(entry.name)}`);
-        }
-    }
-    const warnings = [];
-    for (const extension of loadResult.loaded) {
-        if ((extension.activation?.commands ?? []).length === 0) {
-            continue;
-        }
-        if (schemaContributors.has(`${extension.layer}:${normalizeExtensionNameForMatch(extension.name)}`)) {
-            warnings.push(`extension_schema_narrow_activation:${extension.layer}:${extension.name}`);
-        }
-    }
-    return [...new Set(warnings)].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. */
-function 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.",
-        },
-    ];
-    for (const guard of guards) {
-        if (guard.triggered && !guard.allowed) {
-            throw new PmCliError(guard.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. */
-function resolveNormalizedExtensionTarget(target, action, options) {
-    const normalizedInput = target?.trim().toLowerCase();
-    if (action === "doctor" && normalizedInput === "doctor") {
-        return undefined;
-    }
-    if (action === "reload" && normalizedInput === "reload") {
-        return undefined;
-    }
-    if (action === "catalog" && normalizedInput === "catalog") {
-        return undefined;
-    }
-    const inferredInitAlias = action === "init" &&
-        options.init !== true &&
-        options.scaffold !== true &&
-        (normalizedInput === "init" || normalizedInput === "scaffold");
-    if (inferredInitAlias) {
-        return undefined;
-    }
-    return target;
-}
-/* c8 ignore stop */
-/**
- * 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 async function runExtension(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 withResult = (details, ok = true) => {
-        const result = {
-            ok,
-            action,
-            scope,
-            roots: action === "catalog" &&
-                typeof options.fields === "string" &&
-                options.fields.trim().length > 0
-                ? {
-                    project: "project",
-                    global: "global",
-                    selected: scope,
-                    settings_root: "project",
-                }
-                : {
-                    project: resolvedRoots.roots.project,
-                    global: resolvedRoots.roots.global,
-                    selected: resolvedRoots.selected_root,
-                    settings_root: resolvedRoots.settings_root,
-                },
-            warnings: [...new Set(warnings)].sort((left, right) => left.localeCompare(right)),
-            details,
-        };
-        if (action === "doctor") {
-            Object.defineProperty(result, NATIVE_OUTPUT_MARKER, {
-                value: true,
-                enumerable: false,
-                configurable: false,
-            });
-        }
-        return result;
-    };
-    const ctx = {
-        action,
-        normalizedTarget,
-        scope,
-        resolvedRoots,
-        warnings,
-        options,
-        global,
-        withResult,
-    };
-    return EXTENSION_ACTION_HANDLERS[action](ctx);
-}
-async function runExtensionInitAction(ctx) {
-    const { action, normalizedTarget, options, withResult } = ctx;
-    const githubOption = resolveGithubOption(options);
-    if (githubOption !== undefined ||
-        (typeof options.ref === "string" && options.ref.trim().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);
-    const quotedTargetPath = JSON.stringify(scaffold.target_path);
-    // Forward-slash the path for the copy-pasteable `cd` hint: Windows cmd.exe /
-    // PowerShell reject the doubled backslashes JSON.stringify emits, while both
-    // shells (and POSIX) accept forward slashes.
-    const quotedShellTargetPath = JSON.stringify(scaffold.target_path.replace(/\\/g, "/"));
-    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: [
-            // Extensions are authored AND loaded as TypeScript (ADR pm-2c28 / pm-m1uz):
-            // the manifest entry is ./index.ts and pm strips types on load (Node
-            // >=22.18), so there is no compile/build step — install dependencies, then
-            // install the scaffold directly.
-            ...(options.vocabulary === "package"
-                ? [
-                    `Install dependencies: cd ${quotedShellTargetPath}, then run "npm install"`,
-                ]
-                : [
-                    `Install type-check dependencies: cd ${quotedShellTargetPath}, then run "npm install -D typescript @types/node @unbrained/pm-cli"`,
-                ]),
-            ...(options.vocabulary === "package" && options.declarative === true
-                ? [
-                    "Ensure the target workspace can resolve @unbrained/pm-cli before installing this declarative package.",
-                ]
-                : []),
-            `Install the scaffold: ${options.vocabulary === "package" ? "pm install --project" : "pm extension --install --project"} ${quotedTargetPath}`,
-            `Smoke-test command path: pm ${scaffold.command_name}`,
-            ...(options.vocabulary === "package"
-                ? [
-                    `Validate the package: cd ${quotedShellTargetPath}, then run "npm run typecheck" and "npm test"`,
-                ]
-                : [
-                    `Type-check the source (optional): cd ${quotedShellTargetPath}, then run "npx tsc --noEmit"`,
-                ]),
-            `Run diagnostics: ${options.vocabulary === "package" ? "pm package doctor" : "pm extension --doctor"} --project --detail summary`,
-        ],
-    });
-}
-async function runExtensionReloadAction(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);
-}
-async function runExtensionCatalogAction(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 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. */
-function buildInstallManagedSource(bundledAliasName, bundledPackageName, installSource, resolvedSource) {
-    if (bundledAliasName) {
-        return {
-            kind: "builtin",
-            input: bundledAliasName,
-            location: bundledAliasName,
-            name: bundledAliasName,
-            ...(bundledPackageName === null ? {} : { package: bundledPackageName }),
-        };
-    }
-    if (installSource.kind === "local") {
-        return {
-            kind: "local",
-            input: installSource.input,
-            location: installSource.absolute_path,
-        };
-    }
-    if (installSource.kind === "npm") {
-        return {
-            kind: "npm",
-            input: installSource.input,
-            location: resolvedSource.resolved_subpath ?? ".",
-            package: resolvedSource.npm_package,
-            version: resolvedSource.npm_version,
-        };
-    }
-    return {
-        kind: "github",
-        input: installSource.input,
-        location: resolvedSource.resolved_subpath ?? installSource.subpath ?? ".",
-        repository: installSource.repository,
-        owner: installSource.owner,
-        repo: installSource.repo,
-        ref: installSource.ref,
-        subpath: resolvedSource.resolved_subpath ?? installSource.subpath,
-        commit: resolvedSource.commit,
-    };
-}
-/* c8 ignore stop */
-/** Run the install body while holding the per-destination 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. */
-async function performExtensionInstallUnderLock(ctx, input) {
-    const { scope, resolvedRoots, warnings, global, withResult } = ctx;
-    const { validated, destinationDirectoryName, bundledAliasName, bundledPackageName, installSource, resolvedSource, } = 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 });
-    if (!installInPlace) {
-        await copyExtensionDirectoryForInstall(validated.directory, destinationDirectory);
-    }
-    await ensureExtensionModuleTypeMarker(destinationDirectory);
-    const sourceRecord = buildInstallManagedSource(bundledAliasName, bundledPackageName, installSource, resolvedSource);
-    const now = nowIso();
-    const existingManagedEntry = managedStateRead.state.entries.find((entry) => normalizeExtensionNameForMatch(entry.name) ===
-        normalizeExtensionNameForMatch(validated.manifest.name));
-    const sourceUnchanged = existingManagedEntry !== undefined &&
-        existingManagedEntry.manifest_version === validated.manifest.version &&
-        managedExtensionSourcesEquivalent(existingManagedEntry.source, sourceRecord);
-    const managedState = upsertManagedEntry(managedStateRead.state, {
-        name: validated.manifest.name,
-        directory: destinationDirectoryName,
-        scope,
-        manifest_version: validated.manifest.version,
-        manifest_entry: validated.manifest.entry,
-        capabilities: [...validated.manifest.capabilities],
-        installed_at: existingManagedEntry?.installed_at ?? now,
-        updated_at: sourceUnchanged ? existingManagedEntry.updated_at : now,
-        source: sourceRecord,
-    });
-    await writeManagedExtensionState(resolvedRoots.selected_root, managedState);
-    const activationChanged = ensureActivated(settings, validated.manifest.name);
-    if (activationChanged) {
-        await writeSettings(resolvedRoots.settings_root, settings, "settings:write");
-    }
-    const refreshedInstalled = await listInstalledExtensions(resolvedRoots.selected_root, scope, settings, managedState);
-    warnings.push(...refreshedInstalled.warnings);
-    const runtimeProbe = await probeRuntimeCommandPathsForInstall(resolvedRoots.pm_root, 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 = runtimeProbe.item_type_registrations
-        .filter((entry) => normalizeExtensionNameForMatch(entry.name) ===
-        normalizeExtensionNameForMatch(validated.manifest.name))
-        .flatMap((entry) => entry.types.map((type) => ({ name: type.name, folder: type.folder })));
-    if (scope === "project" && installedItemTypeDefinitions.length > 0) {
-        await ensureTypeFolderScaffold(resolvedRoots.pm_root, installedItemTypeDefinitions, warnings, "install:type-folder");
-    }
-    const commandSummary = summarizeRuntimeCommandPathsForExtension(validated.manifest.name, runtimeProbe.installed);
-    const installActivationFailure = findActivationFailureByName(validated.manifest.name, runtimeProbe.activation_failures, scope);
-    const runtimeActivationStatus = resolveInstallRuntimeActivationStatus(validated.manifest.name, scope, runtimeProbe.installed, installActivationFailure);
-    const activated = !runtimeProbe.extensions_disabled && runtimeActivationStatus !== "failed";
-    if (!activated) {
-        warnings.push(`extension_install_activation_failed:${scope}:${validated.manifest.name}:${runtimeActivationStatus}`);
-    }
-    const verification = {
-        status: activated ? "ok" : "degraded",
-        target_pm_root: resolvedRoots.pm_root,
-        activation_status: runtimeActivationStatus,
-        activated,
-        registered_commands: commandSummary.command_paths,
-        registered_actions: commandSummary.action_paths,
-        registered_item_types: installedItemTypeDefinitions,
-        health: {
-            status: activated ? "ok" : "degraded",
-            blocking_failure_count: activated ? 0 : 1,
-        },
-    };
-    return withResult({
-        extension: {
-            name: validated.manifest.name,
-            version: validated.manifest.version,
-            entry: validated.manifest.entry,
-            capabilities: validated.manifest.capabilities,
-            directory: destinationDirectoryName,
-        },
-        source: sourceRecord,
-        destination_path: destinationDirectory,
-        overwritten: destinationExists && !installInPlace,
-        installed_in_place: installInPlace,
-        activated,
-        settings_changed: activationChanged,
-        runtime_activation_status: runtimeActivationStatus,
-        command_paths: commandSummary.command_paths,
-        action_paths: commandSummary.action_paths,
-        command_discovery: buildInstallCommandDiscovery(validated.manifest.name, sourceRecord, commandSummary, installActivationFailure),
-        verification,
-        activation_diagnostics: {
-            failed_count: runtimeProbe.activation_failures.length,
-            failed: runtimeProbe.activation_failures,
-            installed_extension_failed: installActivationFailure ?? null,
-        },
-    }, activated);
-}
-async function runExtensionInstallAction(ctx) {
-    const { action, normalizedTarget, resolvedRoots, warnings, options, global, withResult, } = ctx;
-    const githubOption = resolveGithubOption(options);
-    const explicitSourceInput = githubOption ?? requireTarget(normalizedTarget, action, options);
-    if (typeof githubOption !== "string" &&
-        isBundledPackageInstallAllTarget(explicitSourceInput)) {
-        if (typeof options.ref === "string" && options.ref.trim().length > 0) {
-            throw new PmCliError('Action "install all" does not accept --ref.', EXIT_CODE.USAGE);
-        }
-        const aliases = await listBundledPackageAliases();
-        const packages = [];
-        for (const alias of aliases) {
-            packages.push({
-                alias,
-                result: await runExtension(alias, { ...options, install: true }, global),
-            });
-        }
-        for (const entry of packages) {
-            warnings.push(...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) => ({
-                alias: entry.alias,
-                ok: entry.result.ok,
-                extension: entry.result.details
-                    .extension,
-                source: entry.result.details.source,
-                destination_path: entry.result.details.destination_path,
-                activated: entry.result.details
-                    .activated,
-                settings_changed: entry.result.details.settings_changed,
-                command_paths: entry.result.details
-                    .command_paths,
-                action_paths: entry.result.details
-                    .action_paths,
-                command_discovery: entry.result.details.command_discovery,
-                verification: entry.result.details
-                    .verification,
-                runtime_activation_status: entry.result.details.runtime_activation_status,
-                activation_diagnostics: entry.result.details.activation_diagnostics,
-                warnings: entry.result.warnings,
-            })),
-        }, installedAll);
-    }
-    /* 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: options.ref,
-    });
-    /* c8 ignore stop */
-    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 */
-    }
-}
-async function runExtensionAdoptAllAction(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 adoptedDetails = adoption.adopted_entries.map((entry) => {
-        const refreshedEntry = refreshedInstalled.extensions.find((candidate) => normalizeExtensionNameForMatch(candidate.name) ===
-            normalizeExtensionNameForMatch(entry.name) &&
-            normalizeExtensionNameForMatch(candidate.directory) ===
-                normalizeExtensionNameForMatch(entry.directory)) ??
-            /* c8 ignore next 3 -- fallback only matters if a manifest renames between adopt and refresh */
-            refreshedInstalled.extensions.find((candidate) => normalizeExtensionNameForMatch(candidate.directory) ===
-                normalizeExtensionNameForMatch(entry.directory));
-        return {
-            ...entry,
-            update_check_status: refreshedEntry?.update_check_status ?? null,
-            update_check_reason: refreshedEntry?.update_check_reason ?? null,
-        };
-    });
-    /* 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 */
-}
-async function runExtensionAdoptAction(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 = githubOption === undefined
-        ? {
-            kind: "local",
-            input: extensionTarget,
-            location: extensionDirectory,
-        }
-        : (() => {
-            const parsed = parseExtensionInstallSource(githubOption, {
-                forceGithub: true,
-                ref: options.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 */
-            /* c8 ignore start -- github subpath defaults are validated in install-source parser tests */
-            return {
-                kind: "github",
-                input: parsed.input,
-                location: parsed.subpath ?? ".",
-                repository: parsed.repository,
-                owner: parsed.owner,
-                repo: parsed.repo,
-                ref: parsed.ref,
-                subpath: parsed.subpath,
-            };
-            /* c8 ignore stop */
-        })();
-    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,
-        update_check_status: refreshedEntry?.update_check_status ?? null,
-        update_check_reason: refreshedEntry?.update_check_reason ?? null,
-    });
-    /* c8 ignore stop */
-}
-async function resolveRequiredInstalledExtension(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 };
-}
-async function runExtensionUninstallAction(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,
-    });
-}
-async function runExtensionActivateDeactivateAction(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. */
-function buildDoctorRemediation(baseRemediation, loadFailureCount, activationFailureCount, vocabulary, managedStateFix, isolationHint) {
-    return [
-        ...new Set([
-            ...baseRemediation,
-            ...(isolationHint === null ? [] : [isolationHint]),
-            /* c8 ignore start -- vocabulary-specific remediation branches are copy-only variants */
-            ...(loadFailureCount > 0
-                ? [
-                    vocabulary === "package"
-                        ? "Run pm package explore --project and pm package explore --global to inspect load failures."
-                        : "Run pm extension --explore --project and pm extension --explore --global to inspect load failures.",
-                ]
-                : []),
-            ...(activationFailureCount > 0
-                ? [
-                    vocabulary === "package"
-                        ? "Review activation failures in pm package doctor --detail deep output."
-                        : "Review activation failures in pm extension --doctor --detail deep output.",
-                ]
-                : []),
-            /* c8 ignore stop */
-            ...(managedStateFix && managedStateFix.adopted_entries.length > 0
-                ? [
-                    `Managed-state fix adopted ${managedStateFix.adopted_entries.length} extension(s).`,
-                ]
-                : []),
-        ]
-            .map((entry) => entry.trim())
-            .filter((entry) => entry.length > 0)),
-    ];
-}
-function hasGlobalLayerDiagnostics(loadResult) {
-    return (loadResult.loaded.some((entry) => entry.layer === "global") ||
-        loadResult.failed.some((entry) => entry.layer === "global") ||
-        loadResult.warnings.some((warning) => warning.includes(":global:")));
-}
-function 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.");
-}
-/** Build the doctor isolation block shared by summary and details output so the over-the-wire payload stays identical for extension and package vocabulary. */
-function 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`,
-    };
-}
-async function runExtensionDoctorAction(ctx) {
-    const { normalizedTarget, scope, resolvedRoots, warnings, options, global, withResult, } = ctx;
-    if (normalizedTarget && normalizedTarget.trim().length > 0) {
-        throw new PmCliError('Action "doctor" does not accept a target argument.', EXIT_CODE.USAGE);
-    }
-    const isolated = options.isolated === true || options.ignoreGlobal === true;
-    if (isolated && scope === "global") {
-        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") {
-        throw new PmCliError("--trace requires --detail deep with --doctor.", 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);
-    let managedState = managedStateRead.state;
-    const managedStateFix = options.fixManagedState === true
-        ? await adoptUnmanagedExtensions(resolvedRoots.selected_root, scope, installed.extensions, managedStateRead.state)
-        : null;
-    if (managedStateFix) {
-        managedState = managedStateFix.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);
-}
-async function runExtensionDescribeAction(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 */
-async function runExtensionExploreManageAction(ctx) {
-    const { action, scope, resolvedRoots, warnings, options, global, 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);
-    let managedState = managedStateRead.state;
-    const managedStateFix = action === "manage" && options.fixManagedState === true
-        ? await adoptUnmanagedExtensions(resolvedRoots.selected_root, scope, installed.extensions, managedStateRead.state)
-        : null;
-    if (managedStateFix) {
-        managedState = managedStateFix.state;
-    }
-    if (action === "manage") {
-        const updates = await Promise.all(managedState.entries.map(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,
-            };
-        }));
-        managedState = {
-            ...managedState,
-            updated_at: nowIso(),
-            entries: sortManagedEntries(updates),
-        };
-        await writeManagedExtensionState(resolvedRoots.selected_root, managedState);
-    }
-    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);
-    }
-    let runtimeProbeSummary;
-    let runtimeInstalledExtensions = refreshedInstalled.extensions;
-    let runtimeActivationFailures;
-    if (action === "explore" || options.runtimeProbe === true) {
-        const loadResult = await loadExtensions({
-            pmRoot: resolvedRoots.pm_root,
-            settings,
-            cwd: process.cwd(),
-            noExtensions: global.noExtensions === true,
-        });
-        const activationResult = await activateExtensions({
-            ...loadResult,
-            loaded: loadResult.loaded,
-        });
-        warnings.push(...loadResult.warnings);
-        warnings.push(...activationResult.warnings);
-        runtimeInstalledExtensions = applyDoctorRuntimeActivationState(refreshedInstalled.extensions, loadResult, activationResult);
-        runtimeActivationFailures = collectActivationFailureDiagnostics(activationResult.failed);
-        runtimeProbeSummary = {
-            requested: true,
-            executed: true,
-            reason: 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,
-        };
-    }
-    else if (action === "manage") {
-        runtimeProbeSummary = {
-            requested: false,
-            executed: false,
-        };
-    }
-    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 (runtimeActivationFailures !== undefined) {
-        details.activation_diagnostics = {
-            failed_count: runtimeActivationFailures.length,
-            failed: runtimeActivationFailures,
-        };
-    }
-    if (action === "explore") {
-        details.runtime_probe = runtimeProbeSummary;
-    }
-    if (action === "manage") {
-        details.runtime_probe = runtimeProbeSummary;
-        details.managed_state_fix =
-            managedStateFix !== null
-                ? {
-                    requested: true,
-                    applied: managedStateFix.adopted_entries.length > 0,
-                    adopted_count: managedStateFix.adopted_entries.length,
-                    adopted_extensions: managedStateFix.adopted_entries.map((entry) => entry.name),
-                    already_managed_count: managedStateFix.already_managed_count,
-                }
-                : {
-                    requested: false,
-                    applied: false,
-                    adopted_count: 0,
-                    adopted_extensions: [],
-                    already_managed_count: runtimeInstalledExtensions.filter((entry) => entry.managed).length,
-                };
-    }
-    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,
-};
-/** Public contract for test only, shared by SDK and presentation-layer consumers. */
-export const _testOnly = {
-    adoptUnmanagedExtensions,
-    buildExtensionPolicyDetails,
-    buildInstallCommandDiscovery,
-    checkGithubUpdate,
-    clearExtensionState,
-    collectActivationFailureDiagnostics,
-    findActivationFailureByName,
-    resolveInstallRuntimeActivationStatus,
-    collectGlobalOutputOverrideDoctorWarnings,
-    collectSchemaNarrowActivationDoctorWarnings,
-    copyExtensionDirectoryWithoutSelfNesting,
-    isErrnoCode,
-    isRetriableExtensionInstallCopyError,
-    listInstalledExtensions,
-    requireTarget,
-    resolveAction,
-    resolveCommandDiscoveryPackageName,
-    resolveGithubOption,
-    resolveInstalledExtensionCandidate,
-    resolveScope,
-    resolveUpdateCheckResolution,
-    withExtensionInstallLock,
-};
+!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]="3594d81d-d502-5f4e-bdf0-ef81a6a3cf91")}catch(e){}}();
+export * from "../../sdk/extension.js";
 //# sourceMappingURL=extension.js.map
-//# debugId=17d000c7-b19f-540c-9600-65416d2ca11b
+//# debugId=3594d81d-d502-5f4e-bdf0-ef81a6a3cf91