@unbrained/pm-cli 2026.8.5 → 2026.8.7

package/dist/sdk/extension/scaffold.js

@@ -4,7 +4,7 @@
  * Implements extension package-management support for Scaffold.
  */
 
-!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]="50f2e5c4-c7fe-5e29-ae2a-60b1b1957756")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="30dfc6e4-27c5-56c0-981b-94e85b780f1f")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { pathExists } from "../../core/fs/fs-utils.js";
@@ -276,8 +276,9 @@ const PACKAGE_CAPABILITY_README_SECTIONS = {
         "",
         "## Preflight Override",
         "`index.ts` registers a preflight override through `api.registerPreflight`. pm",
-        "calls it before every command to compute the migration/format gate decision —",
-        "the last registered override wins. Return only the decision keys you want to",
+        "calls it only for its declared command ownership to compute the migration/format",
+        "gate decision. Overlapping or legacy global ownership is diagnosed. Return only",
+        "the decision keys you want to",
         "change; this starter echoes the current decision unchanged (a safe no-op) so",
         "installing the package does not alter gate behavior. The `preflight`",
         "capability in `manifest.json` grants the registration.",
@@ -765,15 +766,19 @@ function buildActivateBodyLines(extensionName, commandName, capability) {
             ...commandLines,
             "",
             "  // Preflight overrides adjust pm's pre-run gate decision (extension",
-            "  // migrations + item-format checks) before EVERY command — the last",
-            "  // registered override wins. Return a delta of the keys you want to change",
+            "  // migrations + item-format checks) for the commands it owns. Disjoint",
+            "  // packages compose; overlapping or legacy global ownership is diagnosed.",
+            "  // Return a delta of the keys you want to change",
             "  // (enforce_item_format_gate, run_preflight_item_format_sync,",
             "  // run_extension_migrations, enforce_mandatory_migration_gate); returning",
             "  // context.decision unchanged is a safe no-op so installing the package does",
             "  // not alter gate behavior — replace it with your policy, e.g.",
             "  // `{ run_extension_migrations: false }`. The `preflight` capability in",
             "  // manifest.json grants the registration.",
-            "  api.registerPreflight((context) => context.decision);",
+            "  api.registerPreflight({",
+            `    commands: [${JSON.stringify(commandName)}],`,
+            "    run: (context) => context.decision,",
+            "  });",
         ];
     }
     if (capability === "services") {
@@ -1339,7 +1344,7 @@ function buildDeclarativeBlueprintSurface(extensionName, commandName, capability
             break;
         case "preflight":
             builderImports.push("definePreflightOverride");
-            definitions.push("", "// Preflight overrides adjust pm's pre-run gate decision (extension migrations +", "// item-format checks) before EVERY command - the last registered override wins.", "// Return a delta of the keys you want to change (enforce_item_format_gate,", "// run_preflight_item_format_sync, run_extension_migrations,", "// enforce_mandatory_migration_gate); returning context.decision unchanged is a", "// safe no-op - replace it with your policy, e.g. { run_extension_migrations: false }.", "export const preflightOverride = definePreflightOverride((context) => context.decision);");
+            definitions.push("", "// Preflight overrides adjust pm's pre-run gate decision (extension migrations +", "// item-format checks) for the commands it owns. Scoped ownership composes with", "// other packages; overlapping or legacy global ownership is diagnosed.", "// Return a delta of the keys you want to change (enforce_item_format_gate,", "// run_preflight_item_format_sync, run_extension_migrations,", "// enforce_mandatory_migration_gate); returning context.decision unchanged is a", "// safe no-op - replace it with your policy, e.g. { run_extension_migrations: false }.", "export const preflightOverride = definePreflightOverride({", `  commands: [${JSON.stringify(commandName)}],`, "  run: (context) => context.decision,", "});");
             blueprintFields.push("  preflights: [preflightOverride],");
             break;
         case "services":
@@ -1963,7 +1968,7 @@ function buildDefineBuilderExports(extensionName, commandName, capability, names
         lines.push("", "export const pingParser = defineParserOverride((context) => {", "  const options = { ...context.options };", "  if (options.shout === true) options.upper = true;", "  delete options.shout;", "  return { options };", "});");
     }
     if (capability === "preflight") {
-        lines.push("", "// Return a delta of the gate-decision keys you want to change; returning", "// context.decision unchanged is a safe no-op (e.g. { run_extension_migrations: false }).", "export const preflightOverride = definePreflightOverride((context) => context.decision);");
+        lines.push("", "// Return a delta of the gate-decision keys you want to change; returning", "// context.decision unchanged is a safe no-op (e.g. { run_extension_migrations: false }).", "export const preflightOverride = definePreflightOverride({", `  commands: [${JSON.stringify(commandName)}],`, "  run: (context) => context.decision,", "});");
     }
     if (capability === "services") {
         lines.push("", "export const outputService = defineServiceOverride((context) => {", `  if (context.command !== ${JSON.stringify(commandName)}) return { handled: false };`, `  return { rendered_by: ${JSON.stringify(extensionName)}, payload: context.payload };`, "});");
@@ -2295,4 +2300,4 @@ export async function scaffoldExtensionProject(target, vocabulary = "extension",
     };
 }
 //# sourceMappingURL=scaffold.js.map
-//# debugId=50f2e5c4-c7fe-5e29-ae2a-60b1b1957756
+//# debugId=30dfc6e4-27c5-56c0-981b-94e85b780f1f

package/dist/sdk/extension/source-resolution.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @module sdk/extension/source-resolution
+ *
+ * Resolves install-source identity without executing package code.
+ */
+import { type InstallSource } from "./install-sources.js";
+/** Selected install-source identity. */
+export interface ExtensionInstallSourceSelection {
+    /** Selected source family. */
+    kind: "builtin" | "local" | "github" | "npm";
+    /** Canonical source input used for resolution. */
+    input: string;
+    /** Canonical package name when known. */
+    package?: string;
+}
+/** One source candidate and the explicit command that selects it. */
+export interface ExtensionInstallSourceCandidate extends ExtensionInstallSourceSelection {
+    /** Installed candidate version when known. */
+    version?: string;
+    /** Installed candidate directory when relevant. */
+    directory?: string;
+    /** Unambiguous CLI command that selects this candidate. */
+    command: string;
+}
+/** Machine-readable explanation of how one install target resolved. */
+export interface ExtensionInstallSourceResolution {
+    /** Exact target supplied by the caller. */
+    requested: string;
+    /** Source selected by the deterministic resolver. */
+    selected: ExtensionInstallSourceSelection;
+    /** Whether another locally available source could satisfy the same bare name. */
+    ambiguous: boolean;
+    /** Stable precedence rule used for the selection. */
+    precedence: "bundled_alias_before_installed_npm";
+    /** Every matching candidate and its explicit install command. */
+    candidates: ExtensionInstallSourceCandidate[];
+}
+/** Complete result of resolving one extension install target. */
+export interface ResolvedExtensionInstallSource {
+    /** Normalized bundled alias, or null for non-bundled sources. */
+    bundledAliasName: string | null;
+    /** Bundled package name, or null when unavailable. */
+    bundledPackageName: string | null;
+    /** Parsed source passed to the install resolver. */
+    installSource: InstallSource;
+    /** Observable source-selection decision. */
+    sourceResolution: ExtensionInstallSourceResolution;
+}
+/** Resolve bundled-alias provenance and competing installed npm identity. */
+export declare function resolveExtensionInstallSourceIdentity(explicitSourceInput: string, githubOption: string | undefined, ref: string | undefined): Promise<ResolvedExtensionInstallSource>;

package/dist/sdk/extension/source-resolution.js

@@ -0,0 +1,66 @@
+/**
+ * @module sdk/extension/source-resolution
+ *
+ * Resolves install-source identity without executing package code.
+ */
+
+!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]="39bc7f14-2d32-5b58-97ab-647f9f238273")}catch(e){}}();
+import { findInstalledNpmPackageCandidate, parseExtensionInstallSource, } from "./install-sources.js";
+import { resolveBundledExtensionAliasSource, resolveBundledPackageNpmName, } from "./bundled-catalog.js";
+/** Resolve bundled-alias provenance and competing installed npm identity. */
+export async function resolveExtensionInstallSourceIdentity(explicitSourceInput, githubOption, ref) {
+    const bundledAliasSource = typeof githubOption === "string"
+        ? null
+        : await resolveBundledExtensionAliasSource(explicitSourceInput);
+    const bundledAliasName = bundledAliasSource === null
+        ? null
+        : explicitSourceInput.trim().toLowerCase();
+    const bundledPackageName = bundledAliasName === null
+        ? null
+        : await resolveBundledPackageNpmName(bundledAliasName);
+    const installSource = parseExtensionInstallSource(bundledAliasSource ?? explicitSourceInput, { forceGithub: typeof githubOption === "string", ref });
+    const installedNpmCandidate = bundledAliasName === null
+        ? null
+        : await findInstalledNpmPackageCandidate(explicitSourceInput);
+    return {
+        bundledAliasName,
+        bundledPackageName,
+        installSource,
+        sourceResolution: {
+            requested: explicitSourceInput,
+            selected: {
+                kind: bundledAliasName === null ? installSource.kind : "builtin",
+                input: bundledAliasName ?? installSource.input,
+                ...(bundledPackageName === null ? {} : { package: bundledPackageName }),
+            },
+            ambiguous: installedNpmCandidate !== null,
+            precedence: "bundled_alias_before_installed_npm",
+            candidates: [
+                ...(bundledAliasName === null
+                    ? []
+                    : [{
+                            kind: "builtin",
+                            input: bundledAliasName,
+                            ...(bundledPackageName === null
+                                ? {}
+                                : { package: bundledPackageName }),
+                            command: `pm install ${bundledAliasName}`,
+                        }]),
+                ...(installedNpmCandidate === null
+                    ? []
+                    : [{
+                            kind: "npm",
+                            input: `npm:${installedNpmCandidate.package}`,
+                            package: installedNpmCandidate.package,
+                            ...(installedNpmCandidate.version === undefined
+                                ? {}
+                                : { version: installedNpmCandidate.version }),
+                            directory: installedNpmCandidate.directory,
+                            command: `pm install npm:${installedNpmCandidate.package}`,
+                        }]),
+            ],
+        },
+    };
+}
+//# sourceMappingURL=source-resolution.js.map
+//# debugId=39bc7f14-2d32-5b58-97ab-647f9f238273

package/dist/sdk/extension.d.ts

@@ -16,7 +16,7 @@ export { parseExtensionManifest, validateExtensionDirectory, readManagedExtensio
 export type { ManagedExtensionSource, ManagedExtensionRecord, ManagedExtensionState, };
 export type { ManagedExtensionStateReadResult } from "./extension/managed-state.js";
 /** Restricts extension command action values accepted by command, SDK, and storage contracts. */
-export type ExtensionCommandAction = "install" | "uninstall" | "explore" | "manage" | "describe" | "reload" | "doctor" | "catalog" | "adopt" | "adopt-all" | "activate" | "deactivate" | "init";
+export type ExtensionCommandAction = "install" | "uninstall" | "explore" | "manage" | "describe" | "reload" | "doctor" | "catalog" | "adopt" | "adopt-all" | "activate" | "deactivate" | "migrate" | "init";
 /** Restricts extension scope values accepted by command, SDK, and storage contracts. */
 export type ExtensionScope = "project" | "global";
 /** Restricts extension activation status values accepted by command, SDK, and storage contracts. */
@@ -59,6 +59,8 @@ export interface ExtensionCommandOptions {
     activate?: boolean;
     /** Value that configures or reports deactivate for this contract. */
     deactivate?: boolean;
+    /** Plan or apply active extension migrations. */
+    migrate?: boolean;
     /** Value that configures or reports project for this contract. */
     project?: boolean;
     /** Value that configures or reports local for this contract. */
@@ -93,6 +95,8 @@ export interface ExtensionCommandOptions {
     declarative?: boolean;
     /** Value that configures or reports vocabulary for this contract. */
     vocabulary?: "extension" | "package";
+    /** Plan migration work without invoking extension code. */
+    dryRun?: boolean;
 }
 /** Documents the managed extension summary payload exchanged by command, SDK, and package integrations. */
 export interface ManagedExtensionSummary {

package/dist/sdk/extension.js

@@ -4,9 +4,8 @@
  * Implements the pm extension command surface and its agent-facing runtime behavior.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="4fb93ad8-845c-5b71-93eb-c95481f101b7")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="f4b47053-cc05-51f2-b5cb-cc6dba3365c2")}catch(e){}}();
 import fs from "node:fs/promises";
-import os from "node:os";
 import path from "node:path";
 import { activateExtensions, createSerialQueue, loadExtensions, nextExtensionReloadToken, } from "../core/extensions/index.js";
 import { describeExtensionActivation } from "../core/extensions/activation-summary.js";
@@ -30,7 +29,7 @@ import { ensureTypeFolderScaffold } from "./schema.js";
 import { normalizeStringList, normalizeExtensionNameForMatch, normalizeManagedDirectoryName, parseExtensionManifest, validateExtensionDirectory, } from "./extension/shared.js";
 import { sortManagedEntries, managedExtensionSourcesEquivalent, readManagedExtensionState, writeManagedExtensionState, upsertManagedEntry, persistManagedContributionInventory, resolveManagedExtensionStatePath, } from "./extension/managed-state.js";
 import { parseExtensionInstallSource, resolveInstallSource, areDirectoriesEquivalent, } from "./extension/install-sources.js";
-import { resolveBundledExtensionAliasSource, resolveBundledPackageNpmName, isBundledPackageInstallAllTarget, listBundledPackageAliases, resolveBundledAliasManifestName, buildBundledPackageCatalog, } from "./extension/bundled-catalog.js";
+import { resolveBundledExtensionAliasSource, 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, summarizeExtensionFailures, } from "./extension/doctor.js";
@@ -40,6 +39,8 @@ import { summarizeRuntimeCommandPathsForExtension } from "./extension/runtime-su
 import { collectGlobalOutputOverrideDoctorWarnings } from "./extension/output-ownership.js";
 import { collectMcpCustomFieldCollisionDoctorWarnings } from "./extension/custom-field-collisions.js";
 import { checkGithubUpdate } from "./extension/update-check.js";
+import { runExtensionMigrateAction } from "./extension/migrations.js";
+import { resolveExtensionInstallSourceIdentity, } from "./extension/source-resolution.js";
 import { captureExtensionInstallSnapshot, readOptionalMetadataFile, restoreExtensionInstallSnapshot, } from "./extension/install-snapshot.js";
 // Re-export the public surface that lives in sibling modules but was previously
 // exported from this file (used by sdk barrels, upgrade.ts, and tests).
@@ -61,6 +62,7 @@ const LIFECYCLE_ACTION_TARGETS = [
     ["adopt-all", "adopt-all", "--adopt-all"],
     ["activate", "activate", "--activate"],
     ["deactivate", "deactivate", "--deactivate"],
+    ["migrate", "migrate", "--migrate"],
 ];
 const LIFECYCLE_ACTION_FLAG_HINT = LIFECYCLE_ACTION_TARGETS.map(([, , flag]) => flag)
     .filter((flag, index, flags) => flags.indexOf(flag) === index)
@@ -78,6 +80,7 @@ const LIFECYCLE_ACTION_FLAGS = {
     "adopt-all": "--adopt-all",
     activate: "--activate",
     deactivate: "--deactivate",
+    migrate: "--migrate",
     init: "--init",
 };
 const NATIVE_OUTPUT_MARKER = "__pm_native_output";
@@ -353,6 +356,7 @@ const EXTENSION_ACTION_FLAG_SELECTORS = [
     ["adoptAll", "adopt-all"],
     ["activate", "activate"],
     ["deactivate", "deactivate"],
+    ["migrate", "migrate"],
 ];
 /** Positional lifecycle shorthand mapped to the canonical extension action. */
 const IMPLICIT_EXTENSION_ACTIONS = {
@@ -363,6 +367,7 @@ const IMPLICIT_EXTENSION_ACTIONS = {
     scaffold: "init",
     explore: "explore",
     manage: "manage",
+    migrate: "migrate",
     list: "explore",
     "": "explore",
 };
@@ -637,10 +642,10 @@ const resolveInstallRuntimeActivationStatus = (extensionName, scope, runtimeInst
         (installActivationFailure ? "failed" : "unknown"));
 };
 /** Probe a temporary installed extension for runtime command registrations. */
-const probeRuntimeCommandPathsForInstall = (pmRoot, settings, refreshedInstalled, global) => {
+const probeRuntimeCommandPathsForInstall = (pmRoot, parent, settings, refreshedInstalled, global) => {
     return extensionRuntimeProbeQueue.enqueue(async () => {
         const originalPackageRoot = process.env.PM_CLI_PACKAGE_ROOT;
-        const moduleGraphSnapshotRoot = await fs.mkdtemp(path.join(os.tmpdir(), "pm-extension-module-graph-"));
+        const snapshotRoot = await fs.mkdtemp(path.join(parent, ".pm-module-graph-"));
         process.env.PM_CLI_PACKAGE_ROOT = resolvePmPackageRootFromModule(import.meta.url, ["../.."]);
         try {
             const loadResult = await loadExtensions({
@@ -650,11 +655,10 @@ const probeRuntimeCommandPathsForInstall = (pmRoot, settings, refreshedInstalled
                 noExtensions: global.noExtensions === true,
                 reload_token: nextExtensionReloadToken(),
                 cache_bust: true,
-                module_graph_snapshot_root: moduleGraphSnapshotRoot,
+                module_graph_snapshot_root: snapshotRoot,
             });
             const activationResult = await activateExtensions({
                 ...loadResult,
-                loaded: loadResult.loaded,
             });
             const runtimeFailures = [
                 ...loadResult.failed.map((failure) => ({
@@ -681,7 +685,7 @@ const probeRuntimeCommandPathsForInstall = (pmRoot, settings, refreshedInstalled
             };
         }
         finally {
-            await fs.rm(moduleGraphSnapshotRoot, { recursive: true, force: true });
+            await fs.rm(snapshotRoot, { recursive: true, force: true });
             if (originalPackageRoot === undefined) {
                 delete process.env.PM_CLI_PACKAGE_ROOT;
             }
@@ -889,6 +893,11 @@ const assertExtensionActionOptionScope = (action, options) => {
             allowed: action === "init",
             message: "--declarative is only valid with --init/--scaffold.",
         },
+        {
+            triggered: options.dryRun === true,
+            allowed: action === "migrate",
+            message: "--dry-run is only valid with --migrate.",
+        },
     ];
     const invalidGuard = guards.find((guard) => guard.triggered && !guard.allowed);
     if (invalidGuard) {
@@ -1264,7 +1273,7 @@ const buildInstalledExtensionActivation = (ctx, extensionName, runtimeProbe, com
             registered_commands: commandSummary.command_paths,
             registered_actions: commandSummary.action_paths,
             registered_item_types: installedItemTypes,
-            module_graph_verification: "fresh_snapshot",
+            module_graph_verification: "fresh_in_topology_snapshot",
             health: healthByActivation[String(activated)],
         },
     };
@@ -1276,7 +1285,7 @@ const performExtensionInstallUnderLock = async (ctx, input) => {
     const persisted = await persistExtensionInstall(ctx, input);
     const refreshedInstalled = await listInstalledExtensions(resolvedRoots.selected_root, scope, persisted.settings, persisted.managedState);
     warnings.push(...refreshedInstalled.warnings);
-    const runtimeProbe = await probeRuntimeCommandPathsForInstall(resolvedRoots.pm_root, persisted.settings, refreshedInstalled.extensions, global);
+    const runtimeProbe = await probeRuntimeCommandPathsForInstall(resolvedRoots.pm_root, path.dirname(resolvedRoots.selected_root), persisted.settings, refreshedInstalled.extensions, global);
     warnings.push(...runtimeProbe.warnings);
     // Scaffold the folders for any item types the installed package contributes
     // so the tracker is immediately healthy — matching `pm schema add-type` and
@@ -1302,6 +1311,7 @@ const performExtensionInstallUnderLock = async (ctx, input) => {
             directory: destinationDirectoryName,
         },
         source: persisted.sourceRecord,
+        source_resolution: input.sourceResolution,
         destination_path: persisted.destinationDirectory,
         overwritten: [
             persisted.destinationExists,
@@ -1357,6 +1367,7 @@ const runBundledExtensionInstallAll = async (ctx) => {
                 ok: entry.result.ok,
                 extension: details.extension,
                 source: details.source,
+                source_resolution: details.source_resolution,
                 destination_path: details.destination_path,
                 activated: details.activated,
                 settings_changed: details.settings_changed,
@@ -1371,32 +1382,14 @@ const runBundledExtensionInstallAll = async (ctx) => {
         }),
     }, installedAll);
 };
-/** Resolve bundled-alias provenance before installing one extension source. */
-const resolveSingleExtensionInstallSource = async (explicitSourceInput, githubOption, ref) => {
-    /* c8 ignore start -- github/local alias-source split is exercised in install-action integration tests */
-    const bundledAliasSource = typeof githubOption === "string"
-        ? null
-        : await resolveBundledExtensionAliasSource(explicitSourceInput);
-    /* c8 ignore stop */
-    const bundledAliasName = bundledAliasSource === null
-        ? null
-        : explicitSourceInput.trim().toLowerCase();
-    const bundledPackageName = bundledAliasName === null
-        ? null
-        : await resolveBundledPackageNpmName(bundledAliasName);
-    const sourceInput = bundledAliasSource ?? explicitSourceInput;
-    /* c8 ignore start -- install-source branch combinations are covered in install-sources focused tests */
-    const installSource = parseExtensionInstallSource(sourceInput, {
-        forceGithub: typeof githubOption === "string",
-        ref,
-    });
-    /* c8 ignore stop */
-    return { bundledAliasName, bundledPackageName, installSource };
-};
 /** Install one resolved source and clean transient source material afterward. */
 const runSingleExtensionInstall = async (ctx, explicitSourceInput, githubOption) => {
     const { resolvedRoots } = ctx;
-    const { bundledAliasName, bundledPackageName, installSource } = await resolveSingleExtensionInstallSource(explicitSourceInput, githubOption, ctx.options.ref);
+    const { bundledAliasName, bundledPackageName, installSource, sourceResolution, } = await resolveExtensionInstallSourceIdentity(explicitSourceInput, githubOption, ctx.options.ref);
+    if (sourceResolution.ambiguous) {
+        const npmCandidate = sourceResolution.candidates.find((candidate) => candidate.kind === "npm");
+        ctx.warnings.push(`extension_install_source_ambiguous:${explicitSourceInput}:builtin:${bundledAliasName}:npm:${npmCandidate.package}`);
+    }
     const resolvedSource = await resolveInstallSource(installSource);
     try {
         const validated = await validateExtensionDirectory(resolvedSource.directory, {
@@ -1410,6 +1403,7 @@ const runSingleExtensionInstall = async (ctx, explicitSourceInput, githubOption)
             destinationDirectoryName,
             bundledAliasName,
             bundledPackageName,
+            sourceResolution,
             installSource,
             resolvedSource,
         }));
@@ -1640,7 +1634,7 @@ const runExtensionActivateDeactivateAction = async (ctx) => {
         await writeSettings(resolvedRoots.settings_root, settings, "settings:write");
     }
     const activationFailure = action === "activate"
-        ? await probeRuntimeCommandPathsForInstall(resolvedRoots.pm_root, settings, [candidate], global).then((probe) => {
+        ? await probeRuntimeCommandPathsForInstall(resolvedRoots.pm_root, path.dirname(resolvedRoots.selected_root), settings, [candidate], global).then((probe) => {
             warnings.push(...probe.warnings);
             return findActivationFailureByName(candidate.name, probe.activation_failures, ctx.scope);
         })
@@ -2147,6 +2141,7 @@ const EXTENSION_ACTION_HANDLERS = {
     "adopt-all": runExtensionAdoptAllAction,
     activate: runExtensionActivateDeactivateAction,
     deactivate: runExtensionActivateDeactivateAction,
+    migrate: runExtensionMigrateAction,
 };
 /** Identify lifecycle actions that mutate shared settings or managed-extension state. */
 const requiresExtensionStateLock = (ctx) => [
@@ -2156,6 +2151,7 @@ const requiresExtensionStateLock = (ctx) => [
     ctx.action === "adopt-all",
     ctx.action === "activate",
     ctx.action === "deactivate",
+    ctx.action === "migrate",
     [ctx.action === "doctor", ctx.options.fixManagedState === true].every(Boolean),
 ].some(Boolean);
 /** Dispatch one normalized lifecycle action through the complete handler table. */
@@ -2194,4 +2190,4 @@ export const _testOnly = {
     withExtensionInstallLock,
 };
 //# sourceMappingURL=extension.js.map
-//# debugId=4fb93ad8-845c-5b71-93eb-c95481f101b7
+//# debugId=f4b47053-cc05-51f2-b5cb-cc6dba3365c2

package/dist/sdk/generated-error-code-catalog.js

@@ -4,7 +4,7 @@
  * Generated by scripts/generate-error-code-catalog.mjs. Do not edit manually.
  */
 
-!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]="7a568064-a103-5b19-969d-6e58fc0cc5b7")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="93c784d2-8f0f-5bf4-875e-3d83a675c9eb")}catch(e){}}();
 import { definePmErrorCodeCatalog } from "./error-code-catalog.js";
 /** Exhaustive catalog generated from literal error guidance declarations. */
 export const PM_ERROR_CODE_CATALOG = definePmErrorCodeCatalog([
@@ -668,6 +668,26 @@ export const PM_ERROR_CODE_CATALOG = definePmErrorCodeCatalog([
         sources: ["core/diagnostics/remediation.ts"],
         emitting_commands: ["*"],
     },
+    {
+        code: "improvement_metric_contract_conflict",
+        meaning: "Improvement metric contract conflict condition.",
+        stability: "provisional",
+        exit_code: 4,
+        class: "conflict",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/improvement-ledger.ts"],
+        emitting_commands: ["*"],
+    },
+    {
+        code: "improvement_observation_conflict",
+        meaning: "Improvement observation conflict condition.",
+        stability: "provisional",
+        exit_code: 4,
+        class: "conflict",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/improvement-ledger.ts"],
+        emitting_commands: ["*"],
+    },
     {
         code: "init_existing_settings_requires_force",
         meaning: "Init existing settings requires force condition.",
@@ -853,6 +873,86 @@ export const PM_ERROR_CODE_CATALOG = definePmErrorCodeCatalog([
         sources: ["sdk/mutation-events.ts"],
         emitting_commands: ["*"],
     },
+    {
+        code: "invalid_history_analytics_limit",
+        meaning: "Invalid history analytics limit condition.",
+        stability: "provisional",
+        exit_code: 2,
+        class: "usage",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/history-analytics.ts"],
+        emitting_commands: ["*"],
+    },
+    {
+        code: "invalid_history_analytics_minimum_sample",
+        meaning: "Invalid history analytics minimum sample condition.",
+        stability: "provisional",
+        exit_code: 2,
+        class: "usage",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/history-analytics.ts"],
+        emitting_commands: ["*"],
+    },
+    {
+        code: "invalid_history_analytics_since",
+        meaning: "Invalid history analytics since condition.",
+        stability: "provisional",
+        exit_code: 2,
+        class: "usage",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/history-analytics.ts"],
+        emitting_commands: ["*"],
+    },
+    {
+        code: "invalid_improvement_ledger",
+        meaning: "Invalid improvement ledger condition.",
+        stability: "provisional",
+        exit_code: 1,
+        class: "generic_failure",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/improvement-ledger-validation.ts"],
+        emitting_commands: ["*"],
+    },
+    {
+        code: "invalid_improvement_metric",
+        meaning: "Invalid improvement metric condition.",
+        stability: "provisional",
+        exit_code: 2,
+        class: "usage",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/improvement-ledger.ts"],
+        emitting_commands: ["*"],
+    },
+    {
+        code: "invalid_improvement_observation",
+        meaning: "Invalid improvement observation condition.",
+        stability: "provisional",
+        exit_code: 2,
+        class: "usage",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/improvement-ledger.ts"],
+        emitting_commands: ["*"],
+    },
+    {
+        code: "invalid_improvement_observation_limit",
+        meaning: "Invalid improvement observation limit condition.",
+        stability: "provisional",
+        exit_code: 2,
+        class: "usage",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/improvement-ledger.ts"],
+        emitting_commands: ["*"],
+    },
+    {
+        code: "invalid_improvement_observation_timestamp",
+        meaning: "Invalid improvement observation timestamp condition.",
+        stability: "provisional",
+        exit_code: 2,
+        class: "usage",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/improvement-ledger.ts"],
+        emitting_commands: ["*"],
+    },
     {
         code: "invalid_provenance_predicate",
         meaning: "Invalid provenance predicate condition.",
@@ -873,6 +973,16 @@ export const PM_ERROR_CODE_CATALOG = definePmErrorCodeCatalog([
         sources: ["sdk/pagination.ts"],
         emitting_commands: ["*"],
     },
+    {
+        code: "invalid_read_output_session",
+        meaning: "Invalid read output session condition.",
+        stability: "provisional",
+        exit_code: 2,
+        class: "usage",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/read-output-session.ts"],
+        emitting_commands: ["*"],
+    },
     {
         code: "invalid_workspace_snapshot_target",
         meaning: "Invalid workspace snapshot target condition.",
@@ -2285,4 +2395,4 @@ export const PM_ERROR_CODE_CATALOG = definePmErrorCodeCatalog([
     },
 ]);
 //# sourceMappingURL=generated-error-code-catalog.js.map
-//# debugId=7a568064-a103-5b19-969d-6e58fc0cc5b7
+//# debugId=93c784d2-8f0f-5bf4-875e-3d83a675c9eb

package/dist/sdk/governance/health.js

@@ -4,7 +4,7 @@
  * Implements the pm health command surface and its agent-facing runtime behavior.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="6d814d40-522c-5bcc-b404-7e6511cf999a")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="34fc99f6-45e5-53f2-96eb-767d50ed449c")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { resolveItemTypeRegistry } from "../../core/item/type-registry.js";
@@ -35,6 +35,7 @@ import { readSettingsWithMetadata } from "../../core/store/settings.js";
 import { buildRemediationMap } from "../../core/diagnostics/remediation.js";
 import { scanHistoryAuthorAttribution, } from "../author-attribution.js";
 import { readManagedExtensionState } from "../extension.js";
+import { applyStoredExtensionMigrationState } from "../extension/migrations.js";
 import { buildCapabilityContractMetadata, buildRegistrationCollisionRemediation, collectUnknownCapabilityGuidance, } from "../extension/doctor.js";
 import { scanStaleInProgressItems, } from "./stale-work.js";
 import { scanTrackedRuntimeCache } from "./tracked-runtime-cache.js";
@@ -605,6 +606,7 @@ async function buildExtensionCheck(pmRoot, settings, noExtensionsFlag) {
         readManagedExtensionState(loadResult.roots.project),
         readManagedExtensionState(loadResult.roots.global),
     ]);
+    await applyStoredExtensionMigrationState(pmRoot, activationResult.registrations.migrations);
     const migrationStatus = summarizeMigrationStatuses(activationResult.registrations.migrations);
     const activationDetails = {
         failed: activationResult.failed,
@@ -695,6 +697,13 @@ async function buildExtensionCheck(pmRoot, settings, noExtensionsFlag) {
                 warnings: extensionWarnings,
                 activation: activationDetails,
                 triage: extensionTriage,
+                ...(migrationStatus.summary.pending_count > 0
+                    ? {
+                        remediation_map: {
+                            extension_migration_pending: "pm extension migrate --project",
+                        },
+                    }
+                    : {}),
                 capability_contract: capabilityContract,
                 capability_guidance: capabilityGuidance,
             },
@@ -1955,4 +1964,4 @@ export const _testOnlyHealthCommand = {
     warningCode,
 };
 //# sourceMappingURL=health.js.map
-//# debugId=6d814d40-522c-5bcc-b404-7e6511cf999a
+//# debugId=34fc99f6-45e5-53f2-96eb-767d50ed449c