@unbrained/pm-cli 2026.8.5 → 2026.8.6

package/dist/sdk/extension.js

@@ -4,7 +4,7 @@
  * 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]="f4f1a871-b632-5263-aec0-cb00bcdbe1b3")}catch(e){}}();
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
@@ -30,7 +30,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 +40,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 +63,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 +81,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 +357,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 +368,7 @@ const IMPLICIT_EXTENSION_ACTIONS = {
     scaffold: "init",
     explore: "explore",
     manage: "manage",
+    migrate: "migrate",
     list: "explore",
     "": "explore",
 };
@@ -889,6 +895,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) {
@@ -1302,6 +1313,7 @@ const performExtensionInstallUnderLock = async (ctx, input) => {
             directory: destinationDirectoryName,
         },
         source: persisted.sourceRecord,
+        source_resolution: input.sourceResolution,
         destination_path: persisted.destinationDirectory,
         overwritten: [
             persisted.destinationExists,
@@ -1357,6 +1369,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 +1384,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 +1405,7 @@ const runSingleExtensionInstall = async (ctx, explicitSourceInput, githubOption)
             destinationDirectoryName,
             bundledAliasName,
             bundledPackageName,
+            sourceResolution,
             installSource,
             resolvedSource,
         }));
@@ -2147,6 +2143,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 +2153,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 +2192,4 @@ export const _testOnly = {
     withExtensionInstallLock,
 };
 //# sourceMappingURL=extension.js.map
-//# debugId=4fb93ad8-845c-5b71-93eb-c95481f101b7
+//# debugId=f4f1a871-b632-5263-aec0-cb00bcdbe1b3

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

package/dist/sdk/index.d.ts

@@ -20,7 +20,10 @@ export { quoteCommandArg, quoteWindowsCommandArg, renderPmCommand, } from "./com
 export { runGc, type GcCheckpointsSummary, type GcLocksSummary, } from "./governance/gc.js";
 export { _testOnlyHealthCommand, runHealth, type HealthCheck, } from "./governance/health.js";
 export { _testOnlyValidateCommand, projectValidateCounts, runValidate, type ValidateCheck, type ValidateCountsFixesSummary, type ValidateCountsResult, type ValidateFixesSummary, type ValidateMutationServices, } from "./governance/validate.js";
-export { runExtension } from "./extension.js";
+export { runExtension, type ExtensionCommandAction, } from "./extension.js";
+export { resolveExtensionInstallSourceIdentity, type ExtensionInstallSourceCandidate, type ExtensionInstallSourceResolution, type ExtensionInstallSourceSelection, type ResolvedExtensionInstallSource, } from "./extension/source-resolution.js";
+export { applyStoredExtensionMigrationState, readExtensionMigrationState, resolveExtensionMigrationStatePath, runExtensionMigrateAction, runExtensionMigrations, type ExtensionMigrationActionContext, type ExtensionMigrationOutcomeStatus, type ExtensionMigrationReceipt, type ExtensionMigrationRunResult, type ExtensionMigrationState, type ExtensionMigrationStateEntry, type RunExtensionMigrationsOptions, } from "./extension/migrations.js";
+export { findInstalledNpmPackageCandidate, type GithubInstallSource, type InstalledNpmPackageCandidate, type InstallSource, type LocalInstallSource, type NpmInstallSource, type ResolvedInstallSource, } from "./extension/install-sources.js";
 export { buildExtensionDescribeResult, renderExtensionDescribeMarkdown, type ExtensionCommandClaimant, type ExtensionCommandOwnership, type ExtensionDescribeActivationStatus, type ExtensionDescribeResult, type ExtensionSurfaceDescription, } from "./extension/describe.js";
 export { runEvent, runMeet, runRemind, type MeetingEventShortcutOptions, type ReminderShortcutOptions, type SchedulingShortcutCommonOptions, } from "./scheduling-shortcuts.js";
 export { createExtensionCommandSdk } from "./extension-command-context.js";
@@ -45,7 +48,7 @@ export { RESERVED_ITEM_FIELD_NAMES } from "../core/extensions/item-fields.js";
 export type { LocatedItem } from "../core/store/item-store.js";
 export { PM_PACKAGE_CONVENTIONAL_RESOURCE_ROOTS, PM_PACKAGE_RESOURCE_KINDS, collectPackageExtensionDirectories, readPmPackageManifest, type PmPackageCatalogLinkMap, type PmPackageCatalogMediaMap, type PmPackageCatalogMetadata, type PmPackageManifest, type PmPackageResourceKind, type PmPackageResourceMap, } from "../core/packages/manifest.js";
 export type { CommanderOptionAliasContract, CommanderOptionRegistrationContract, } from "./cli-contracts.js";
-export { ACTIVITY_FLAG_CONTRACTS, ACTIVITY_COMMANDER_STRING_OPTION_CONTRACTS, AGGREGATE_FLAG_CONTRACTS, APPEND_FLAG_CONTRACTS, CALENDAR_COMMANDER_STRING_OPTION_CONTRACTS, CALENDAR_FLAG_CONTRACTS, CLAIM_FLAG_CONTRACTS, CLOSE_ACTION_OPTION_KEYS, CLOSE_FLAG_CONTRACTS, CLOSE_MANY_FLAG_CONTRACTS, CLOSE_TASK_FLAG_CONTRACTS, COMMENTS_FLAG_CONTRACTS, COMPLETION_FLAG_CONTRACTS, CONFIG_FLAG_CONTRACTS, CONTEXT_COMMANDER_STRING_OPTION_CONTRACTS, CONTEXT_FLAG_CONTRACTS, CONTRACTS_FLAG_CONTRACTS, COPY_FLAG_CONTRACTS, CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, CREATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, CREATE_COMMANDER_STRING_OPTION_CONTRACTS, CREATE_FLAG_CONTRACTS, DELETE_FLAG_CONTRACTS, DEPS_FLAG_CONTRACTS, DOCS_FLAG_CONTRACTS, EVAL_FLAG_CONTRACTS, EVENT_FLAG_CONTRACTS, EVENTS_FLAG_CONTRACTS, EXTENSION_ACTIVATE_FLAG_CONTRACTS, EXTENSION_ADOPT_ALL_FLAG_CONTRACTS, EXTENSION_ADOPT_FLAG_CONTRACTS, EXTENSION_CATALOG_FLAG_CONTRACTS, EXTENSION_DEACTIVATE_FLAG_CONTRACTS, EXTENSION_DESCRIBE_FLAG_CONTRACTS, EXTENSION_DOCTOR_FLAG_CONTRACTS, EXTENSION_EXPLORE_FLAG_CONTRACTS, EXTENSION_FLAG_CONTRACTS, EXTENSION_INIT_FLAG_CONTRACTS, EXTENSION_INSTALL_FLAG_CONTRACTS, EXTENSION_MANAGE_FLAG_CONTRACTS, EXTENSION_RELOAD_FLAG_CONTRACTS, EXTENSION_SCOPE_FLAG_CONTRACTS, EXTENSION_UNINSTALL_FLAG_CONTRACTS, FILES_FLAG_CONTRACTS, FOCUS_FLAG_CONTRACTS, GC_FLAG_CONTRACTS, GET_FLAG_CONTRACTS, GRAPH_FLAG_CONTRACTS, GLOBAL_FLAG_CONTRACTS, GUIDE_FLAG_CONTRACTS, HEALTH_FLAG_CONTRACTS, HISTORY_COMPACT_FLAG_CONTRACTS, HISTORY_FLAG_CONTRACTS, HISTORY_REDACT_FLAG_CONTRACTS, HISTORY_REPAIR_FLAG_CONTRACTS, HISTORY_AUTHOR_ACKNOWLEDGE_FLAG_CONTRACTS, INIT_FLAG_CONTRACTS, INSTALL_FLAG_CONTRACTS, ITEM_MUTATE_FLAG_CONTRACTS, ITEM_COMPLETE_FLAG_CONTRACTS, LEARNINGS_FLAG_CONTRACTS, LIST_COMMANDER_STRING_OPTION_CONTRACTS, LIST_FILTER_FLAG_CONTRACTS, MEET_FLAG_CONTRACTS, MERGE_FLAG_CONTRACTS, NEXT_COMMANDER_STRING_OPTION_CONTRACTS, NEXT_FLAG_CONTRACTS, NOTES_FLAG_CONTRACTS, PACKAGE_FLAG_CONTRACTS, PACKAGE_INIT_FLAG_CONTRACTS, PAUSE_TASK_FLAG_CONTRACTS, PLAN_CREATE_METADATA_PARAMETER_KEYS, PLAN_FLAG_CONTRACTS, PM_COMMAND_OUTPUT_BUDGET_CONTRACTS, PM_CLI_ONLY_TOOL_ACTION_WAIVERS, PM_CORE_COMMAND_NAMES, PM_EXTENSION_PACKAGE_ACTION_SUBCOMMANDS, PM_EXTENSION_CAPABILITY_CONTRACTS, PM_EXTENSION_POLICY_MODE_CONTRACTS, PM_EXTENSION_POLICY_SURFACE_CONTRACTS, PM_EXTENSION_SANDBOX_PROFILE_CONTRACTS, PM_EXTENSION_SERVICE_NAME_CONTRACTS, PM_EXTENSION_TRUST_MODE_CONTRACTS, PM_PROVIDER_TOOL_PARAMETERS_SCHEMA, PM_PROVIDER_TOOL_PARAMETERS_SCHEMA_VERSION, PM_TOOL_ACTIONS, analyzePmToolActionParity, PM_TOOL_ACTION_PARAMETER_CONTRACTS, PM_TOOL_PARAMETERS_SCHEMA, PM_TOOL_PARAMETERS_SCHEMA_MAJOR, PM_TOOL_PARAMETERS_SCHEMA_VERSION, PM_OUTPUT_BUDGET_CLASSES, PM_OUTPUT_DEGRADATION_STEPS, PROFILE_FLAG_CONTRACTS, REINDEX_FLAG_CONTRACTS, RELEASE_FLAG_CONTRACTS, REMIND_FLAG_CONTRACTS, RESTORE_FLAG_CONTRACTS, SCHEMA_FLAG_CONTRACTS, SEARCH_COMMANDER_STRING_OPTION_CONTRACTS, SEARCH_FLAG_CONTRACTS, START_TASK_FLAG_CONTRACTS, STATS_FLAG_CONTRACTS, DUPLICATES_FLAG_CONTRACTS, SUBCOMMAND_GLOBAL_FLAG_CONTRACTS, TELEMETRY_FLAG_CONTRACTS, TEST_ALL_FLAG_CONTRACTS, TEST_FLAG_CONTRACTS, TEST_RUNS_FLAG_CONTRACTS, TOOL_ACTIVITY_OPTION_CONTRACTS, TOOL_AGGREGATE_OPTION_CONTRACTS, TOOL_BULK_MUTATION_FILTER_OPTION_CONTRACT_SOURCE, TOOL_CALENDAR_OPTION_CONTRACTS, TOOL_CLOSE_MANY_FILTER_OPTION_CONTRACTS, TOOL_CONTEXT_OPTION_CONTRACTS, TOOL_CREATE_OPTION_CONTRACTS, TOOL_CREATE_OPTION_CONTRACT_SOURCE, TOOL_DEPS_OPTION_CONTRACTS, TOOL_GRAPH_OPTION_CONTRACTS, TOOL_LIST_FILTER_OPTION_CONTRACTS, TOOL_SEARCH_FILTER_OPTION_CONTRACTS, TOOL_SHARED_CREATE_UPDATE_OPTION_CONTRACTS, TOOL_SHARED_CREATE_UPDATE_OPTION_CONTRACT_SOURCE, TOOL_UPDATE_MANY_FILTER_OPTION_CONTRACTS, TOOL_UPDATE_OPTION_CONTRACTS, TOOL_UPDATE_OPTION_CONTRACT_SOURCE, UPDATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, UPDATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, UPDATE_COMMANDER_STRING_OPTION_CONTRACTS, UPDATE_FLAG_CONTRACTS, UPDATE_MANY_FLAG_CONTRACTS, UPGRADE_FLAG_CONTRACTS, VALIDATE_FLAG_CONTRACTS, WORKSPACE_FLAG_CONTRACTS, buildPmActionToolInputSchema, PM_TOOL_RESERVED_CUSTOM_FIELD_PROPERTIES, compactFlagAliasContracts, createPmCommandOutputBudget, definePmCommandOutputBudget, estimatePmOutputTokens, inferPmOutputBudgetClass, analyzeSdkCliParameterCompleteness, isPmExtensionCapabilityContract, isPmExtensionPolicyModeContract, isPmExtensionPolicySurfaceContract, isPmExtensionServiceNameContract, isPmToolAction, hasSubcommandFlagContractsForCommand, readFirstStringFromCommanderOptions, readFirstValueFromCommanderOptions, readStringArrayFromCommanderOptions, resolveSubcommandFlagContractsForCommand, resolvePmCommandOutputBudget, resolvePmToolCustomFieldCollision, toCompletionFlagString, withFlagAliasMetadata, } from "./cli-contracts.js";
+export { ACTIVITY_FLAG_CONTRACTS, ACTIVITY_COMMANDER_STRING_OPTION_CONTRACTS, AGGREGATE_FLAG_CONTRACTS, APPEND_FLAG_CONTRACTS, CALENDAR_COMMANDER_STRING_OPTION_CONTRACTS, CALENDAR_FLAG_CONTRACTS, CLAIM_FLAG_CONTRACTS, CLOSE_ACTION_OPTION_KEYS, CLOSE_FLAG_CONTRACTS, CLOSE_MANY_FLAG_CONTRACTS, CLOSE_TASK_FLAG_CONTRACTS, COMMENTS_FLAG_CONTRACTS, COMPLETION_FLAG_CONTRACTS, CONFIG_FLAG_CONTRACTS, CONTEXT_COMMANDER_STRING_OPTION_CONTRACTS, CONTEXT_FLAG_CONTRACTS, CONTRACTS_FLAG_CONTRACTS, COPY_FLAG_CONTRACTS, CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, CREATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, CREATE_COMMANDER_STRING_OPTION_CONTRACTS, CREATE_FLAG_CONTRACTS, DELETE_FLAG_CONTRACTS, DEPS_FLAG_CONTRACTS, DOCS_FLAG_CONTRACTS, EVAL_FLAG_CONTRACTS, EVENT_FLAG_CONTRACTS, EVENTS_FLAG_CONTRACTS, EXTENSION_ACTIVATE_FLAG_CONTRACTS, EXTENSION_ADOPT_ALL_FLAG_CONTRACTS, EXTENSION_ADOPT_FLAG_CONTRACTS, EXTENSION_CATALOG_FLAG_CONTRACTS, EXTENSION_DEACTIVATE_FLAG_CONTRACTS, EXTENSION_DESCRIBE_FLAG_CONTRACTS, EXTENSION_DOCTOR_FLAG_CONTRACTS, EXTENSION_EXPLORE_FLAG_CONTRACTS, EXTENSION_FLAG_CONTRACTS, EXTENSION_INIT_FLAG_CONTRACTS, EXTENSION_INSTALL_FLAG_CONTRACTS, EXTENSION_MANAGE_FLAG_CONTRACTS, EXTENSION_MIGRATE_FLAG_CONTRACTS, EXTENSION_RELOAD_FLAG_CONTRACTS, EXTENSION_SCOPE_FLAG_CONTRACTS, EXTENSION_UNINSTALL_FLAG_CONTRACTS, FILES_FLAG_CONTRACTS, FOCUS_FLAG_CONTRACTS, GC_FLAG_CONTRACTS, GET_FLAG_CONTRACTS, GRAPH_FLAG_CONTRACTS, GLOBAL_FLAG_CONTRACTS, GUIDE_FLAG_CONTRACTS, HEALTH_FLAG_CONTRACTS, HISTORY_COMPACT_FLAG_CONTRACTS, HISTORY_FLAG_CONTRACTS, HISTORY_REDACT_FLAG_CONTRACTS, HISTORY_REPAIR_FLAG_CONTRACTS, HISTORY_AUTHOR_ACKNOWLEDGE_FLAG_CONTRACTS, INIT_FLAG_CONTRACTS, INSTALL_FLAG_CONTRACTS, ITEM_MUTATE_FLAG_CONTRACTS, ITEM_COMPLETE_FLAG_CONTRACTS, LEARNINGS_FLAG_CONTRACTS, LIST_COMMANDER_STRING_OPTION_CONTRACTS, LIST_FILTER_FLAG_CONTRACTS, MEET_FLAG_CONTRACTS, MERGE_FLAG_CONTRACTS, NEXT_COMMANDER_STRING_OPTION_CONTRACTS, NEXT_FLAG_CONTRACTS, NOTES_FLAG_CONTRACTS, PACKAGE_FLAG_CONTRACTS, PACKAGE_INIT_FLAG_CONTRACTS, PAUSE_TASK_FLAG_CONTRACTS, PLAN_CREATE_METADATA_PARAMETER_KEYS, PLAN_FLAG_CONTRACTS, PM_COMMAND_OUTPUT_BUDGET_CONTRACTS, PM_CLI_ONLY_TOOL_ACTION_WAIVERS, PM_CORE_COMMAND_NAMES, PM_EXTENSION_PACKAGE_ACTION_SUBCOMMANDS, PM_EXTENSION_CAPABILITY_CONTRACTS, PM_EXTENSION_POLICY_MODE_CONTRACTS, PM_EXTENSION_POLICY_SURFACE_CONTRACTS, PM_EXTENSION_SANDBOX_PROFILE_CONTRACTS, PM_EXTENSION_SERVICE_NAME_CONTRACTS, PM_EXTENSION_TRUST_MODE_CONTRACTS, PM_PROVIDER_TOOL_PARAMETERS_SCHEMA, PM_PROVIDER_TOOL_PARAMETERS_SCHEMA_VERSION, PM_TOOL_ACTIONS, analyzePmToolActionParity, PM_TOOL_ACTION_PARAMETER_CONTRACTS, PM_TOOL_PARAMETERS_SCHEMA, PM_TOOL_PARAMETERS_SCHEMA_MAJOR, PM_TOOL_PARAMETERS_SCHEMA_VERSION, PM_OUTPUT_BUDGET_CLASSES, PM_OUTPUT_DEGRADATION_STEPS, PROFILE_FLAG_CONTRACTS, REINDEX_FLAG_CONTRACTS, RELEASE_FLAG_CONTRACTS, REMIND_FLAG_CONTRACTS, RESTORE_FLAG_CONTRACTS, SCHEMA_FLAG_CONTRACTS, SEARCH_COMMANDER_STRING_OPTION_CONTRACTS, SEARCH_FLAG_CONTRACTS, START_TASK_FLAG_CONTRACTS, STATS_FLAG_CONTRACTS, DUPLICATES_FLAG_CONTRACTS, SUBCOMMAND_GLOBAL_FLAG_CONTRACTS, TELEMETRY_FLAG_CONTRACTS, TEST_ALL_FLAG_CONTRACTS, TEST_FLAG_CONTRACTS, TEST_RUNS_FLAG_CONTRACTS, TOOL_ACTIVITY_OPTION_CONTRACTS, TOOL_AGGREGATE_OPTION_CONTRACTS, TOOL_BULK_MUTATION_FILTER_OPTION_CONTRACT_SOURCE, TOOL_CALENDAR_OPTION_CONTRACTS, TOOL_CLOSE_MANY_FILTER_OPTION_CONTRACTS, TOOL_CONTEXT_OPTION_CONTRACTS, TOOL_CREATE_OPTION_CONTRACTS, TOOL_CREATE_OPTION_CONTRACT_SOURCE, TOOL_DEPS_OPTION_CONTRACTS, TOOL_GRAPH_OPTION_CONTRACTS, TOOL_LIST_FILTER_OPTION_CONTRACTS, TOOL_SEARCH_FILTER_OPTION_CONTRACTS, TOOL_SHARED_CREATE_UPDATE_OPTION_CONTRACTS, TOOL_SHARED_CREATE_UPDATE_OPTION_CONTRACT_SOURCE, TOOL_UPDATE_MANY_FILTER_OPTION_CONTRACTS, TOOL_UPDATE_OPTION_CONTRACTS, TOOL_UPDATE_OPTION_CONTRACT_SOURCE, UPDATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, UPDATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, UPDATE_COMMANDER_STRING_OPTION_CONTRACTS, UPDATE_FLAG_CONTRACTS, UPDATE_MANY_FLAG_CONTRACTS, UPGRADE_FLAG_CONTRACTS, VALIDATE_FLAG_CONTRACTS, WORKSPACE_FLAG_CONTRACTS, buildPmActionToolInputSchema, PM_TOOL_RESERVED_CUSTOM_FIELD_PROPERTIES, compactFlagAliasContracts, createPmCommandOutputBudget, definePmCommandOutputBudget, estimatePmOutputTokens, inferPmOutputBudgetClass, analyzeSdkCliParameterCompleteness, isPmExtensionCapabilityContract, isPmExtensionPolicyModeContract, isPmExtensionPolicySurfaceContract, isPmExtensionServiceNameContract, isPmToolAction, hasSubcommandFlagContractsForCommand, readFirstStringFromCommanderOptions, readFirstValueFromCommanderOptions, readStringArrayFromCommanderOptions, resolveSubcommandFlagContractsForCommand, resolvePmCommandOutputBudget, resolvePmToolCustomFieldCollision, toCompletionFlagString, withFlagAliasMetadata, } from "./cli-contracts.js";
 export type { CliFlagContract, OptionsFromContracts, PmActionSchemaContract, PmActionToolInputSchemaOptions, PmToolCustomFieldCollision, PmBulkMutationControlOptions, PmBulkMutationFilterOptions, PmCloseActionOptions, PmCloseManyActionOptions, PmCreateActionOptions, PmMutationAttributionOptions, PmOptionScalar, PmCommandOutputBudgetContract, PmOutputBudgetClass, PmOutputDegradationStep, PmUpdateActionOptions, PmUpdateManyActionOptions, PmExtensionCapabilityContract, PmExtensionPolicyModeContract, PmExtensionPolicySurfaceContract, PmExtensionSandboxProfileContract, PmExtensionServiceNameContract, PmExtensionTrustModeContract, PmToolAction, SdkCliActionParameterCoverage, SdkCliCompletenessContractSource, SdkCliParameterCoverageEntry, SdkCliParameterDisposition, ToolOptionFlagContract, } from "./cli-contracts.js";
 export * from "./compose.js";
 export * from "./compile-cache.js";
@@ -119,6 +122,7 @@ export { runUpgrade } from "./governance/upgrade.js";
 export { PLAN_SHOW_DEPTH_VALUES, PLAN_SUBCOMMANDS, PLAN_TEMPLATE_NAMES, } from "./lifecycle/plan.js";
 export * from "./define.js";
 export { BASELINE_ITEM_FORMAT_VERSION, BUILTIN_ITEM_TYPE_VALUES, CONFIDENCE_TEXT_VALUES, CURRENT_ITEM_FORMAT_VERSION, DEPENDENCY_KIND_VALUES, EXIT_CODE, ISSUE_SEVERITY_VALUES, ITEM_TYPE_VALUES, PM_CLI_EXPECTED_ERROR_NAME, PmCliError, PmClient, RISK_VALUES, STATUS_VALUES, acquireLock, appendHistoryEntry, canonicalDocument, classifyItemFormatVersion, clearWorkspaceContractsCache, commitImportedItem, createHistoryEntry, createPmCliExpectedError, effectiveItemFormatVersion, emptyImportedDocument, ensureTrackerInitialized, generateItemId, getActiveExtensionRegistrations, getContracts, getHistoryPath, getItemPath, getSettingsPath, getWorkspaceContracts, isPmCliExpectedError, isTimestampLiteral, listAllItemMetadata, loadCreateTemplateOptions, locateItem, normalizeItemMetadata, normalizeItemFormatVersion, normalizeItemId, normalizeRawItemId, normalizeStatusInput, nowIso, parseTags, pathExists, readBooleanOption, readCsvListOption, readFileIfExists, readLocatedItem, readRequiredString, readSettings, readStringOption, removeFileIfExists, renderCalendarMarkdown, renderCalendarToon, renderGuideMarkdown, resolveCalendarOutputFormat, resolveGuideOutputFormat, resolveItemTypeRegistry, resolveImplicitPmRoot, resolvePmRoot, resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, runAction, runActiveOnReadHooks, runActiveOnWriteHooks, runCalendar, runCompletion, runGuide, runList, runReindex, runSearch, runTemplatesList, runTemplatesSave, runTemplatesShow, runTestRunsList, runTestRunsLogs, runTestRunsResume, runTestRunsStatus, runTestRunsStop, scanItemFormatVersions, selectImportAuthor, serializeItemDocument, splitFrontMatter, toEstimatedMinutesValue, toImportBoolean, toImportConfidence, toImportInteger, toImportLinkedDocs, toImportLinkedFiles, toImportLinkedTests, toImportLogEntries, toImportNormalizedEnum, toImportNumberMap, toImportPriority, toImportStatus, toImportStringList, toImportStringMap, toImportTags, toNonEmptyImportString, writeFileAtomic, aggregate, append, claim, claimNext, close, closeTask, comments, config, context, copy, create, deleteItem, deps, docs, duplicates, extension, extensionActivate, extensionDeactivate, extensionList, files, filesDiscover, filesLookup, focus, gc, get, graph, health, historyCompact, historyCompactBulk, historyRedact, historyRepair, historyRepairAll, init, learnings, list, next, notes, packageActivate, packageCatalog, packageDeactivate, packageDescribe, packageDoctor, packageInstall, packageLifecycle, packageList, packageManage, packageReload, packageUninstall, pauseTask, profile, profileApply, profileLint, profileList, profileShow, release, restore, schema, schemaAddField, schemaAddStatus, schemaAddType, schemaApplyPreset, schemaInferTypes, schemaList, schemaListFields, schemaRemapStatus, schemaRemoveField, schemaRemoveStatus, schemaRemoveType, schemaShow, schemaShowField, schemaShowStatus, schemaRenameField, schemaRenameType, search, startTask, stats, update, upgrade, validate, type AggregateOptions, type AggregateResult, type AggregateRow, type AppendCommandOptions, type AppendResult, type BlockerEntry, type CalendarOptions, type CalendarResult, type ClaimResult, type CloseResult, type CloseTaskResult, type CommitImportedItemParams, type CommitImportedItemResult, type CommentsCommandOptions, type CommentsResult, type ConfigCommandOptions, type ConfigResult, type CompletionResult, type CompletionShell, type ContractsCommandOptions, type ContractsResult, type ContextFocusItem, type ContextOptions, type ContextOutputFormat, type ContextResult, type CopyResult, type CreatePmCliExpectedErrorOptions, type CreateResult, type CreateTemplateOptions, type Dependency, type DeleteResult, type DepsCommandOptions, type DepsResult, type DocsCommandOptions, type DocsResult, type ExtensionCommandOptions, type ExtensionCommandResult, type FilesCommandOptions, type FilesDiscoverOptions, type FilesDiscoverResult, type FilesLookupOptions, type FilesLookupResult, type FilesResult, type FocusResult, type GcCommandOptions, type GcResult, type GetContractsOptions, type GetOptions, type GetResult, type GuideDepth, type GuideOptions, type GuideOutputFormat, type GuideResult, type HealthResult, type ImportLinkedScope, type InitCommandOptions, type InitResult, type ItemFormatVersionScanEntry, type ItemFormatVersionScanResult, type ItemFormatVersionStatus, type LearningsCommandOptions, type LearningsResult, type LinkedDoc, type LinkedFile, type LinkedTest, type ListedItem, type ListCompactResult, type ListFullResult, type ListOptions, type ListProjectedItem, type ListProjectedItemCore, type ListResult, type ListResultItem, type ListSortField, type ListSortOrder, type ListTreeItem, type ListTreeMetadata, type ListVerboseResult, type LogNote, type NextActionableItem, type NextBlockerRef, type NextOptions, type NextOutputFormat, type NextRecommendation, type NextResult, type NotesCommandOptions, type NotesResult, type PackageCommandOptions, type PackageCommandResult, type PauseTaskResult, type PmActionInput, type PmActionName, type PmActionOptions, type PmClientCloseActionOptions, type PmClientFullMutationOptions, type PmClientMutationOptions, type PmClientOptions, type PmClientRunArgs, type PmCliExpectedError, type ProfileApplyCommandOptions, type ProfileApplyResult, type ProfileLintResult, type ProfileListResult, type ProfileResult, type ProfileShowResult, type ProfileSubcommand, type ReindexOptions, type ReindexResult, type ReleaseResult, type RestoreResult, type RunHealthOptions, type SchemaAddFieldCommandOptions, type SchemaAddFieldResult, type SchemaAddStatusCommandOptions, type SchemaAddStatusResult, type SchemaAddTypeCommandOptions, type SchemaAddTypeInferCommandOptions, type SchemaAddTypeInferResult, type SchemaAddTypeResult, type SchemaApplyPresetCommandOptions, type SchemaApplyPresetResult, type SchemaInspectResult, type SchemaListFieldsResult, type SchemaListResult, type SchemaRemoveFieldCommandOptions, type SchemaRemoveFieldResult, type SchemaRemoveStatusCommandOptions, type SchemaRemoveStatusResult, type SchemaRemoveTypeCommandOptions, type SchemaRemoveTypeResult, type SchemaShowFieldResult, type SchemaShowResult, type SchemaShowStatusResult, type SchemaResult, type RunSchemaEvolutionMigrationOptions, type SchemaEvolutionMigrationRequest, type SchemaEvolutionMigrationResult, type SchemaSubcommand, type SearchCompactResult, type SearchHit, type SearchHitHighlight, type SearchMatchMode, type SearchOptions, type ClaimNextOptions, type SearchResult, type SearchResultItem, type SearchVerboseResult, type StartTaskResult, type StatsCommandOptions, type StatsResult, type TemplatesListResult, type TemplatesSaveResult, type TemplatesShowResult, type TestRunsListCommandOptions, type TestRunsLogsCommandOptions, type TestRunsResumeCommandOptions, type TestRunsStopCommandOptions, type ToImportLinkedArtifactsOptions, type ToImportLinkedTestsOptions, type ToImportLogEntriesOptions, type UpdateResult, type UpgradeCommandOptions, type UpgradeResult, type ValidateCommandOptions, type ValidateResult, type WorkspaceContracts, type WorkspaceContractsOptions, type WorkspaceExtensionCommandContract, type WorkspaceFieldContract, } from "./runtime.js";
+export { extensionMigrate, packageMigrate } from "./package-migrations.js";
 export { CONTEXT_OUTPUT_VALUES, NEXT_OUTPUT_VALUES, PM_GITIGNORE_END, PM_GITIGNORE_START, analyzeSdkActionCoverage, ensurePmGitignore, getPmGitignoreBlock, closeItem, runAggregate, runClose, runCopy, runContext, runDelete, runFocus, runGet, runNext, runRestore, runUpdate, type CloseCommandOptions, type CopyOptions, type DeleteCommandOptions, type EnsurePmGitignoreResult, type HierarchyChild, type HierarchyNode, type HotFile, type FocusOptions, type ImportPriorityValue, type ProgressEntry, type RecentContextItem, type RestoreCommandOptions, type SdkActionCoverageRow, type StaleEntry, type TestHealthSummary, type UpdateCommandOptions, type WorkloadEntry, } from "./runtime.js";
 export { runStats } from "./stats.js";
 export { DEFAULT_EVAL_QUERIES_RELATIVE_PATH, EVAL_QUERY_SET_CONTRACT, EVAL_QUERY_SET_EXAMPLE, EVAL_QUERY_SET_SCHEMA_ID, parseEvalQuerySet, runEval, type EvalOptions, type EvalQueryReport, type EvalResult, } from "./eval.js";

package/dist/sdk/index.js

@@ -4,7 +4,7 @@
  * Defines public SDK APIs and package-author helpers for Index.
  */
 
-!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]="ee9b3579-e9c4-505d-9b38-3d3616757e64")}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]="4e336574-f00e-5296-a55f-7f27a264188c")}catch(e){}}();
 export { PM_COMMAND_VISIBILITY_CONTRACTS, PM_MCP_PROMPT_CONTRACTS, PM_MCP_RESOURCE_CONTRACTS, PM_MCP_TOOL_COMMAND_CONTRACTS, listPmCommandsForTier, listPmMcpToolsForProfile, renderPmCommandVisibilityMarkdown, resolvePmCommandVisibilityTier, } from "./agent-capability-contracts.js";
 export * from "./agent-session-context.js";
 export { isErrnoError, limitAnnotationEntries, parseAnnotationTextInput, readAnnotationEntries, resolveAnnotationInput, resolveAnnotationIndex, runAnnotationCommand, wrapOwnershipConflict, } from "./annotations.js";
@@ -21,7 +21,10 @@ export { quoteCommandArg, quoteWindowsCommandArg, renderPmCommand, } from "./com
 export { runGc, } from "./governance/gc.js";
 export { _testOnlyHealthCommand, runHealth, } from "./governance/health.js";
 export { _testOnlyValidateCommand, projectValidateCounts, runValidate, } from "./governance/validate.js";
-export { runExtension } from "./extension.js";
+export { runExtension, } from "./extension.js";
+export { resolveExtensionInstallSourceIdentity, } from "./extension/source-resolution.js";
+export { applyStoredExtensionMigrationState, readExtensionMigrationState, resolveExtensionMigrationStatePath, runExtensionMigrateAction, runExtensionMigrations, } from "./extension/migrations.js";
+export { findInstalledNpmPackageCandidate, } from "./extension/install-sources.js";
 export { buildExtensionDescribeResult, renderExtensionDescribeMarkdown, } from "./extension/describe.js";
 export { runEvent, runMeet, runRemind, } from "./scheduling-shortcuts.js";
 export { createExtensionCommandSdk } from "./extension-command-context.js";
@@ -44,7 +47,7 @@ export { PROFILE_SUBCOMMANDS, formatProfileApplyHuman, formatProfileLintHuman, f
 export * from "./extension-contracts.js";
 export { RESERVED_ITEM_FIELD_NAMES } from "../core/extensions/item-fields.js";
 export { PM_PACKAGE_CONVENTIONAL_RESOURCE_ROOTS, PM_PACKAGE_RESOURCE_KINDS, collectPackageExtensionDirectories, readPmPackageManifest, } from "../core/packages/manifest.js";
-export { ACTIVITY_FLAG_CONTRACTS, ACTIVITY_COMMANDER_STRING_OPTION_CONTRACTS, AGGREGATE_FLAG_CONTRACTS, APPEND_FLAG_CONTRACTS, CALENDAR_COMMANDER_STRING_OPTION_CONTRACTS, CALENDAR_FLAG_CONTRACTS, CLAIM_FLAG_CONTRACTS, CLOSE_ACTION_OPTION_KEYS, CLOSE_FLAG_CONTRACTS, CLOSE_MANY_FLAG_CONTRACTS, CLOSE_TASK_FLAG_CONTRACTS, COMMENTS_FLAG_CONTRACTS, COMPLETION_FLAG_CONTRACTS, CONFIG_FLAG_CONTRACTS, CONTEXT_COMMANDER_STRING_OPTION_CONTRACTS, CONTEXT_FLAG_CONTRACTS, CONTRACTS_FLAG_CONTRACTS, COPY_FLAG_CONTRACTS, CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, CREATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, CREATE_COMMANDER_STRING_OPTION_CONTRACTS, CREATE_FLAG_CONTRACTS, DELETE_FLAG_CONTRACTS, DEPS_FLAG_CONTRACTS, DOCS_FLAG_CONTRACTS, EVAL_FLAG_CONTRACTS, EVENT_FLAG_CONTRACTS, EVENTS_FLAG_CONTRACTS, EXTENSION_ACTIVATE_FLAG_CONTRACTS, EXTENSION_ADOPT_ALL_FLAG_CONTRACTS, EXTENSION_ADOPT_FLAG_CONTRACTS, EXTENSION_CATALOG_FLAG_CONTRACTS, EXTENSION_DEACTIVATE_FLAG_CONTRACTS, EXTENSION_DESCRIBE_FLAG_CONTRACTS, EXTENSION_DOCTOR_FLAG_CONTRACTS, EXTENSION_EXPLORE_FLAG_CONTRACTS, EXTENSION_FLAG_CONTRACTS, EXTENSION_INIT_FLAG_CONTRACTS, EXTENSION_INSTALL_FLAG_CONTRACTS, EXTENSION_MANAGE_FLAG_CONTRACTS, EXTENSION_RELOAD_FLAG_CONTRACTS, EXTENSION_SCOPE_FLAG_CONTRACTS, EXTENSION_UNINSTALL_FLAG_CONTRACTS, FILES_FLAG_CONTRACTS, FOCUS_FLAG_CONTRACTS, GC_FLAG_CONTRACTS, GET_FLAG_CONTRACTS, GRAPH_FLAG_CONTRACTS, GLOBAL_FLAG_CONTRACTS, GUIDE_FLAG_CONTRACTS, HEALTH_FLAG_CONTRACTS, HISTORY_COMPACT_FLAG_CONTRACTS, HISTORY_FLAG_CONTRACTS, HISTORY_REDACT_FLAG_CONTRACTS, HISTORY_REPAIR_FLAG_CONTRACTS, HISTORY_AUTHOR_ACKNOWLEDGE_FLAG_CONTRACTS, INIT_FLAG_CONTRACTS, INSTALL_FLAG_CONTRACTS, ITEM_MUTATE_FLAG_CONTRACTS, ITEM_COMPLETE_FLAG_CONTRACTS, LEARNINGS_FLAG_CONTRACTS, LIST_COMMANDER_STRING_OPTION_CONTRACTS, LIST_FILTER_FLAG_CONTRACTS, MEET_FLAG_CONTRACTS, MERGE_FLAG_CONTRACTS, NEXT_COMMANDER_STRING_OPTION_CONTRACTS, NEXT_FLAG_CONTRACTS, NOTES_FLAG_CONTRACTS, PACKAGE_FLAG_CONTRACTS, PACKAGE_INIT_FLAG_CONTRACTS, PAUSE_TASK_FLAG_CONTRACTS, PLAN_CREATE_METADATA_PARAMETER_KEYS, PLAN_FLAG_CONTRACTS, PM_COMMAND_OUTPUT_BUDGET_CONTRACTS, PM_CLI_ONLY_TOOL_ACTION_WAIVERS, PM_CORE_COMMAND_NAMES, PM_EXTENSION_PACKAGE_ACTION_SUBCOMMANDS, PM_EXTENSION_CAPABILITY_CONTRACTS, PM_EXTENSION_POLICY_MODE_CONTRACTS, PM_EXTENSION_POLICY_SURFACE_CONTRACTS, PM_EXTENSION_SANDBOX_PROFILE_CONTRACTS, PM_EXTENSION_SERVICE_NAME_CONTRACTS, PM_EXTENSION_TRUST_MODE_CONTRACTS, PM_PROVIDER_TOOL_PARAMETERS_SCHEMA, PM_PROVIDER_TOOL_PARAMETERS_SCHEMA_VERSION, PM_TOOL_ACTIONS, analyzePmToolActionParity, PM_TOOL_ACTION_PARAMETER_CONTRACTS, PM_TOOL_PARAMETERS_SCHEMA, PM_TOOL_PARAMETERS_SCHEMA_MAJOR, PM_TOOL_PARAMETERS_SCHEMA_VERSION, PM_OUTPUT_BUDGET_CLASSES, PM_OUTPUT_DEGRADATION_STEPS, PROFILE_FLAG_CONTRACTS, REINDEX_FLAG_CONTRACTS, RELEASE_FLAG_CONTRACTS, REMIND_FLAG_CONTRACTS, RESTORE_FLAG_CONTRACTS, SCHEMA_FLAG_CONTRACTS, SEARCH_COMMANDER_STRING_OPTION_CONTRACTS, SEARCH_FLAG_CONTRACTS, START_TASK_FLAG_CONTRACTS, STATS_FLAG_CONTRACTS, DUPLICATES_FLAG_CONTRACTS, SUBCOMMAND_GLOBAL_FLAG_CONTRACTS, TELEMETRY_FLAG_CONTRACTS, TEST_ALL_FLAG_CONTRACTS, TEST_FLAG_CONTRACTS, TEST_RUNS_FLAG_CONTRACTS, TOOL_ACTIVITY_OPTION_CONTRACTS, TOOL_AGGREGATE_OPTION_CONTRACTS, TOOL_BULK_MUTATION_FILTER_OPTION_CONTRACT_SOURCE, TOOL_CALENDAR_OPTION_CONTRACTS, TOOL_CLOSE_MANY_FILTER_OPTION_CONTRACTS, TOOL_CONTEXT_OPTION_CONTRACTS, TOOL_CREATE_OPTION_CONTRACTS, TOOL_CREATE_OPTION_CONTRACT_SOURCE, TOOL_DEPS_OPTION_CONTRACTS, TOOL_GRAPH_OPTION_CONTRACTS, TOOL_LIST_FILTER_OPTION_CONTRACTS, TOOL_SEARCH_FILTER_OPTION_CONTRACTS, TOOL_SHARED_CREATE_UPDATE_OPTION_CONTRACTS, TOOL_SHARED_CREATE_UPDATE_OPTION_CONTRACT_SOURCE, TOOL_UPDATE_MANY_FILTER_OPTION_CONTRACTS, TOOL_UPDATE_OPTION_CONTRACTS, TOOL_UPDATE_OPTION_CONTRACT_SOURCE, UPDATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, UPDATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, UPDATE_COMMANDER_STRING_OPTION_CONTRACTS, UPDATE_FLAG_CONTRACTS, UPDATE_MANY_FLAG_CONTRACTS, UPGRADE_FLAG_CONTRACTS, VALIDATE_FLAG_CONTRACTS, WORKSPACE_FLAG_CONTRACTS, buildPmActionToolInputSchema, PM_TOOL_RESERVED_CUSTOM_FIELD_PROPERTIES, compactFlagAliasContracts, createPmCommandOutputBudget, definePmCommandOutputBudget, estimatePmOutputTokens, inferPmOutputBudgetClass, analyzeSdkCliParameterCompleteness, isPmExtensionCapabilityContract, isPmExtensionPolicyModeContract, isPmExtensionPolicySurfaceContract, isPmExtensionServiceNameContract, isPmToolAction, hasSubcommandFlagContractsForCommand, readFirstStringFromCommanderOptions, readFirstValueFromCommanderOptions, readStringArrayFromCommanderOptions, resolveSubcommandFlagContractsForCommand, resolvePmCommandOutputBudget, resolvePmToolCustomFieldCollision, toCompletionFlagString, withFlagAliasMetadata, } from "./cli-contracts.js";
+export { ACTIVITY_FLAG_CONTRACTS, ACTIVITY_COMMANDER_STRING_OPTION_CONTRACTS, AGGREGATE_FLAG_CONTRACTS, APPEND_FLAG_CONTRACTS, CALENDAR_COMMANDER_STRING_OPTION_CONTRACTS, CALENDAR_FLAG_CONTRACTS, CLAIM_FLAG_CONTRACTS, CLOSE_ACTION_OPTION_KEYS, CLOSE_FLAG_CONTRACTS, CLOSE_MANY_FLAG_CONTRACTS, CLOSE_TASK_FLAG_CONTRACTS, COMMENTS_FLAG_CONTRACTS, COMPLETION_FLAG_CONTRACTS, CONFIG_FLAG_CONTRACTS, CONTEXT_COMMANDER_STRING_OPTION_CONTRACTS, CONTEXT_FLAG_CONTRACTS, CONTRACTS_FLAG_CONTRACTS, COPY_FLAG_CONTRACTS, CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, CREATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, CREATE_COMMANDER_STRING_OPTION_CONTRACTS, CREATE_FLAG_CONTRACTS, DELETE_FLAG_CONTRACTS, DEPS_FLAG_CONTRACTS, DOCS_FLAG_CONTRACTS, EVAL_FLAG_CONTRACTS, EVENT_FLAG_CONTRACTS, EVENTS_FLAG_CONTRACTS, EXTENSION_ACTIVATE_FLAG_CONTRACTS, EXTENSION_ADOPT_ALL_FLAG_CONTRACTS, EXTENSION_ADOPT_FLAG_CONTRACTS, EXTENSION_CATALOG_FLAG_CONTRACTS, EXTENSION_DEACTIVATE_FLAG_CONTRACTS, EXTENSION_DESCRIBE_FLAG_CONTRACTS, EXTENSION_DOCTOR_FLAG_CONTRACTS, EXTENSION_EXPLORE_FLAG_CONTRACTS, EXTENSION_FLAG_CONTRACTS, EXTENSION_INIT_FLAG_CONTRACTS, EXTENSION_INSTALL_FLAG_CONTRACTS, EXTENSION_MANAGE_FLAG_CONTRACTS, EXTENSION_MIGRATE_FLAG_CONTRACTS, EXTENSION_RELOAD_FLAG_CONTRACTS, EXTENSION_SCOPE_FLAG_CONTRACTS, EXTENSION_UNINSTALL_FLAG_CONTRACTS, FILES_FLAG_CONTRACTS, FOCUS_FLAG_CONTRACTS, GC_FLAG_CONTRACTS, GET_FLAG_CONTRACTS, GRAPH_FLAG_CONTRACTS, GLOBAL_FLAG_CONTRACTS, GUIDE_FLAG_CONTRACTS, HEALTH_FLAG_CONTRACTS, HISTORY_COMPACT_FLAG_CONTRACTS, HISTORY_FLAG_CONTRACTS, HISTORY_REDACT_FLAG_CONTRACTS, HISTORY_REPAIR_FLAG_CONTRACTS, HISTORY_AUTHOR_ACKNOWLEDGE_FLAG_CONTRACTS, INIT_FLAG_CONTRACTS, INSTALL_FLAG_CONTRACTS, ITEM_MUTATE_FLAG_CONTRACTS, ITEM_COMPLETE_FLAG_CONTRACTS, LEARNINGS_FLAG_CONTRACTS, LIST_COMMANDER_STRING_OPTION_CONTRACTS, LIST_FILTER_FLAG_CONTRACTS, MEET_FLAG_CONTRACTS, MERGE_FLAG_CONTRACTS, NEXT_COMMANDER_STRING_OPTION_CONTRACTS, NEXT_FLAG_CONTRACTS, NOTES_FLAG_CONTRACTS, PACKAGE_FLAG_CONTRACTS, PACKAGE_INIT_FLAG_CONTRACTS, PAUSE_TASK_FLAG_CONTRACTS, PLAN_CREATE_METADATA_PARAMETER_KEYS, PLAN_FLAG_CONTRACTS, PM_COMMAND_OUTPUT_BUDGET_CONTRACTS, PM_CLI_ONLY_TOOL_ACTION_WAIVERS, PM_CORE_COMMAND_NAMES, PM_EXTENSION_PACKAGE_ACTION_SUBCOMMANDS, PM_EXTENSION_CAPABILITY_CONTRACTS, PM_EXTENSION_POLICY_MODE_CONTRACTS, PM_EXTENSION_POLICY_SURFACE_CONTRACTS, PM_EXTENSION_SANDBOX_PROFILE_CONTRACTS, PM_EXTENSION_SERVICE_NAME_CONTRACTS, PM_EXTENSION_TRUST_MODE_CONTRACTS, PM_PROVIDER_TOOL_PARAMETERS_SCHEMA, PM_PROVIDER_TOOL_PARAMETERS_SCHEMA_VERSION, PM_TOOL_ACTIONS, analyzePmToolActionParity, PM_TOOL_ACTION_PARAMETER_CONTRACTS, PM_TOOL_PARAMETERS_SCHEMA, PM_TOOL_PARAMETERS_SCHEMA_MAJOR, PM_TOOL_PARAMETERS_SCHEMA_VERSION, PM_OUTPUT_BUDGET_CLASSES, PM_OUTPUT_DEGRADATION_STEPS, PROFILE_FLAG_CONTRACTS, REINDEX_FLAG_CONTRACTS, RELEASE_FLAG_CONTRACTS, REMIND_FLAG_CONTRACTS, RESTORE_FLAG_CONTRACTS, SCHEMA_FLAG_CONTRACTS, SEARCH_COMMANDER_STRING_OPTION_CONTRACTS, SEARCH_FLAG_CONTRACTS, START_TASK_FLAG_CONTRACTS, STATS_FLAG_CONTRACTS, DUPLICATES_FLAG_CONTRACTS, SUBCOMMAND_GLOBAL_FLAG_CONTRACTS, TELEMETRY_FLAG_CONTRACTS, TEST_ALL_FLAG_CONTRACTS, TEST_FLAG_CONTRACTS, TEST_RUNS_FLAG_CONTRACTS, TOOL_ACTIVITY_OPTION_CONTRACTS, TOOL_AGGREGATE_OPTION_CONTRACTS, TOOL_BULK_MUTATION_FILTER_OPTION_CONTRACT_SOURCE, TOOL_CALENDAR_OPTION_CONTRACTS, TOOL_CLOSE_MANY_FILTER_OPTION_CONTRACTS, TOOL_CONTEXT_OPTION_CONTRACTS, TOOL_CREATE_OPTION_CONTRACTS, TOOL_CREATE_OPTION_CONTRACT_SOURCE, TOOL_DEPS_OPTION_CONTRACTS, TOOL_GRAPH_OPTION_CONTRACTS, TOOL_LIST_FILTER_OPTION_CONTRACTS, TOOL_SEARCH_FILTER_OPTION_CONTRACTS, TOOL_SHARED_CREATE_UPDATE_OPTION_CONTRACTS, TOOL_SHARED_CREATE_UPDATE_OPTION_CONTRACT_SOURCE, TOOL_UPDATE_MANY_FILTER_OPTION_CONTRACTS, TOOL_UPDATE_OPTION_CONTRACTS, TOOL_UPDATE_OPTION_CONTRACT_SOURCE, UPDATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, UPDATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, UPDATE_COMMANDER_STRING_OPTION_CONTRACTS, UPDATE_FLAG_CONTRACTS, UPDATE_MANY_FLAG_CONTRACTS, UPGRADE_FLAG_CONTRACTS, VALIDATE_FLAG_CONTRACTS, WORKSPACE_FLAG_CONTRACTS, buildPmActionToolInputSchema, PM_TOOL_RESERVED_CUSTOM_FIELD_PROPERTIES, compactFlagAliasContracts, createPmCommandOutputBudget, definePmCommandOutputBudget, estimatePmOutputTokens, inferPmOutputBudgetClass, analyzeSdkCliParameterCompleteness, isPmExtensionCapabilityContract, isPmExtensionPolicyModeContract, isPmExtensionPolicySurfaceContract, isPmExtensionServiceNameContract, isPmToolAction, hasSubcommandFlagContractsForCommand, readFirstStringFromCommanderOptions, readFirstValueFromCommanderOptions, readStringArrayFromCommanderOptions, resolveSubcommandFlagContractsForCommand, resolvePmCommandOutputBudget, resolvePmToolCustomFieldCollision, toCompletionFlagString, withFlagAliasMetadata, } from "./cli-contracts.js";
 export * from "./compose.js";
 export * from "./compile-cache.js";
 export * from "./context-relevance.js";
@@ -111,6 +114,7 @@ export { runUpgrade } from "./governance/upgrade.js";
 export { PLAN_SHOW_DEPTH_VALUES, PLAN_SUBCOMMANDS, PLAN_TEMPLATE_NAMES, } from "./lifecycle/plan.js";
 export * from "./define.js";
 export { BASELINE_ITEM_FORMAT_VERSION, BUILTIN_ITEM_TYPE_VALUES, CONFIDENCE_TEXT_VALUES, CURRENT_ITEM_FORMAT_VERSION, DEPENDENCY_KIND_VALUES, EXIT_CODE, ISSUE_SEVERITY_VALUES, ITEM_TYPE_VALUES, PM_CLI_EXPECTED_ERROR_NAME, PmCliError, PmClient, RISK_VALUES, STATUS_VALUES, acquireLock, appendHistoryEntry, canonicalDocument, classifyItemFormatVersion, clearWorkspaceContractsCache, commitImportedItem, createHistoryEntry, createPmCliExpectedError, effectiveItemFormatVersion, emptyImportedDocument, ensureTrackerInitialized, generateItemId, getActiveExtensionRegistrations, getContracts, getHistoryPath, getItemPath, getSettingsPath, getWorkspaceContracts, isPmCliExpectedError, isTimestampLiteral, listAllItemMetadata, loadCreateTemplateOptions, locateItem, normalizeItemMetadata, normalizeItemFormatVersion, normalizeItemId, normalizeRawItemId, normalizeStatusInput, nowIso, parseTags, pathExists, readBooleanOption, readCsvListOption, readFileIfExists, readLocatedItem, readRequiredString, readSettings, readStringOption, removeFileIfExists, renderCalendarMarkdown, renderCalendarToon, renderGuideMarkdown, resolveCalendarOutputFormat, resolveGuideOutputFormat, resolveItemTypeRegistry, resolveImplicitPmRoot, resolvePmRoot, resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, runAction, runActiveOnReadHooks, runActiveOnWriteHooks, runCalendar, runCompletion, runGuide, runList, runReindex, runSearch, runTemplatesList, runTemplatesSave, runTemplatesShow, runTestRunsList, runTestRunsLogs, runTestRunsResume, runTestRunsStatus, runTestRunsStop, scanItemFormatVersions, selectImportAuthor, serializeItemDocument, splitFrontMatter, toEstimatedMinutesValue, toImportBoolean, toImportConfidence, toImportInteger, toImportLinkedDocs, toImportLinkedFiles, toImportLinkedTests, toImportLogEntries, toImportNormalizedEnum, toImportNumberMap, toImportPriority, toImportStatus, toImportStringList, toImportStringMap, toImportTags, toNonEmptyImportString, writeFileAtomic, aggregate, append, claim, claimNext, close, closeTask, comments, config, context, copy, create, deleteItem, deps, docs, duplicates, extension, extensionActivate, extensionDeactivate, extensionList, files, filesDiscover, filesLookup, focus, gc, get, graph, health, historyCompact, historyCompactBulk, historyRedact, historyRepair, historyRepairAll, init, learnings, list, next, notes, packageActivate, packageCatalog, packageDeactivate, packageDescribe, packageDoctor, packageInstall, packageLifecycle, packageList, packageManage, packageReload, packageUninstall, pauseTask, profile, profileApply, profileLint, profileList, profileShow, release, restore, schema, schemaAddField, schemaAddStatus, schemaAddType, schemaApplyPreset, schemaInferTypes, schemaList, schemaListFields, schemaRemapStatus, schemaRemoveField, schemaRemoveStatus, schemaRemoveType, schemaShow, schemaShowField, schemaShowStatus, schemaRenameField, schemaRenameType, search, startTask, stats, update, upgrade, validate, } from "./runtime.js";
+export { extensionMigrate, packageMigrate } from "./package-migrations.js";
 export { CONTEXT_OUTPUT_VALUES, NEXT_OUTPUT_VALUES, PM_GITIGNORE_END, PM_GITIGNORE_START, analyzeSdkActionCoverage, ensurePmGitignore, getPmGitignoreBlock, closeItem, runAggregate, runClose, runCopy, runContext, runDelete, runFocus, runGet, runNext, runRestore, runUpdate, } from "./runtime.js";
 export { runStats } from "./stats.js";
 export { DEFAULT_EVAL_QUERIES_RELATIVE_PATH, EVAL_QUERY_SET_CONTRACT, EVAL_QUERY_SET_EXAMPLE, EVAL_QUERY_SET_SCHEMA_ID, parseEvalQuerySet, runEval, } from "./eval.js";
@@ -129,4 +133,4 @@ export * from "./governance.js";
 export * from "./query.js";
 export * from "./testing.js";
 //# sourceMappingURL=index.js.map
-//# debugId=ee9b3579-e9c4-505d-9b38-3d3616757e64
+//# debugId=4e336574-f00e-5296-a55f-7f27a264188c

package/dist/sdk/package-migrations.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @module sdk/package-migrations
+ *
+ * Provides one-shot SDK helpers for extension and package migration lifecycle.
+ */
+import { type ExtensionCommandOptions, type ExtensionCommandResult, type PackageCommandOptions, type PackageCommandResult, type PmClientOptions } from "./runtime.js";
+/** Plan or apply active extension migrations without constructing a reusable client. */
+export declare function extensionMigrate(options?: ExtensionCommandOptions, clientOptions?: PmClientOptions): Promise<ExtensionCommandResult>;
+/** Plan or apply active package migrations without constructing a reusable client. */
+export declare function packageMigrate(options?: PackageCommandOptions, clientOptions?: PmClientOptions): Promise<PackageCommandResult>;

package/dist/sdk/package-migrations.js

@@ -0,0 +1,21 @@
+/**
+ * @module sdk/package-migrations
+ *
+ * Provides one-shot SDK helpers for extension and package migration lifecycle.
+ */
+
+!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]="5bbfab95-010d-5507-ab01-f8f43943d295")}catch(e){}}();
+import { PmClient, } from "./runtime.js";
+/** Plan or apply active extension migrations without constructing a reusable client. */
+export function extensionMigrate(options = {}, clientOptions = {}) {
+    return new PmClient(clientOptions).extension(undefined, {
+        ...options,
+        migrate: true,
+    });
+}
+/** Plan or apply active package migrations without constructing a reusable client. */
+export function packageMigrate(options = {}, clientOptions = {}) {
+    return new PmClient(clientOptions).packageMigrate(options);
+}
+//# sourceMappingURL=package-migrations.js.map
+//# debugId=5bbfab95-010d-5507-ab01-f8f43943d295

package/dist/sdk/runtime.d.ts

@@ -336,6 +336,8 @@ export declare class PmClient {
     packageActivate(target: string, options?: PackageCommandOptions): Promise<PackageCommandResult>;
     /** Disable an installed package using the same action as `pm package deactivate`. */
     packageDeactivate(target: string, options?: PackageCommandOptions): Promise<PackageCommandResult>;
+    /** Plan or apply active package migrations with durable workspace receipts. */
+    packageMigrate(options?: PackageCommandOptions): Promise<PackageCommandResult>;
     /** Upgrade the pm CLI and/or managed packages through the public SDK dispatcher. */
     upgrade(target?: string, options?: UpgradeCommandOptions): Promise<UpgradeResult>;
 }

package/dist/sdk/runtime.js

@@ -4,7 +4,7 @@
  * Defines public SDK APIs and package-author helpers for Runtime.
  */
 
-!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]="196ad1a3-c78f-5eef-90fd-ea5de108b9fa")}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]="57628397-0652-5a7b-8521-2f0fb2abb787")}catch(e){}}();
 export { PM_GITIGNORE_END, PM_GITIGNORE_START, ensurePmGitignore, getPmGitignoreBlock, } from "./workspace.js";
 export { SEARCH_EXTENSION_FLAG_DEFINITIONS } from "./extension-contracts.js";
 import { AsyncLocalStorage } from "node:async_hooks";
@@ -669,6 +669,10 @@ export class PmClient {
     packageDeactivate(target, options = {}) {
         return this.runTyped("package-deactivate", { target, options });
     }
+    /** Plan or apply active package migrations with durable workspace receipts. */
+    packageMigrate(options = {}) {
+        return this.package(undefined, { ...options, migrate: true });
+    }
     /** Upgrade the pm CLI and/or managed packages through the public SDK dispatcher. */
     upgrade(target, options = {}) {
         return this.runTyped("upgrade", {
@@ -1958,4 +1962,4 @@ async function loadWorkspaceExtensionRegistrations(pmRoot, settings, cwd) {
     }
 }
 //# sourceMappingURL=runtime.js.map
-//# debugId=196ad1a3-c78f-5eef-90fd-ea5de108b9fa
+//# debugId=57628397-0652-5a7b-8521-2f0fb2abb787

package/docs/COMMANDS.md

@@ -82,6 +82,8 @@ pm install npm:@scope/pm-package --project
 pm package describe --project   # by-name surface map of every loaded package
 pm package describe my-package --markdown --output docs/my-package-reference.md
 pm package doctor --project --detail summary
+pm package migrate --project --dry-run --json
+pm package migrate --project --json
 pm upgrade --dry-run
 pm upgrade --packages-only
 pm upgrade --cli-only --repair
@@ -89,6 +91,13 @@ pm upgrade --cli-only --repair
 
 `pm install` and `pm package` are the preferred package-first workflow. `pm package` and `pm extension` bare invocations default to `--explore` so agents can list installed packages without remembering an action flag. `pm install '*'`, shell-expanded `pm install *`, and `pm install all` install bundled first-party packages. `pm extension` remains as a compatibility command for direct extension lifecycle operations.
 Install output includes a light `verification` summary with target tracker root, activation state, registered commands/actions/item types, and an `ok|degraded` health verdict. Runtime activation failure sets the command result and process exit status to failure; inspect `activation_diagnostics` and `command_discovery.next_steps` for the exact recovery path.
+Bare install names use bundled aliases before installed npm packages. Every
+install result reports `source_resolution`; when both candidates exist it marks
+the choice ambiguous and provides explicit bare and `npm:` retry commands.
+`package migrate` plans or applies active migration registrations and writes
+durable workspace-history receipts; a successful migration is skipped on later
+processes, while a failed migration remains retryable. `extension migrate` is
+the compatibility spelling.
 When package-owned commands are unavailable, usage guidance includes an install-ready retry (for example `pm install calendar`, `pm install search-advanced`, `pm install governance-audit`, or `pm install guide-shell`).
 
 ## Triage

package/docs/EXTENSIONS.md

@@ -1,6 +1,6 @@
 # Packages and Extensions
 
-Extension flags declared with `list: true` accumulate repeated long/short alias occurrences and comma-separated values into one array. Dynamic commands preserve flag-like variadic content after `--`, and package handlers can use the public `suppressHostOutput()` protocol when they already emitted streaming, binary, or pre-rendered output. Declarative blueprints are also checked for reserved item-field collisions during SDK lint/preflight and harness activation, so a package cannot pass author-time validation and then fail only when users create or update items. Local archive installation, command ownership, and MCP custom-field diagnostics are tracked by [pm-lw6acw](../.agents/pm/issues/pm-lw6acw.toon), [pm-6z0wzf](../.agents/pm/issues/pm-6z0wzf.toon), and [pm-yfdav2](../.agents/pm/issues/pm-yfdav2.toon). Transactional mutation guards, host-bound command test SDKs, and installed custom-type lifecycle parity are tracked by [pm-hx23u5](../.agents/pm/issues/pm-hx23u5.toon), [pm-wx2lr5](../.agents/pm/issues/pm-wx2lr5.toon), and [pm-scga6k](../.agents/pm/issues/pm-scga6k.toon).
+Extension flags declared with `list: true` accumulate repeated long/short alias occurrences and comma-separated values into one array. Dynamic commands preserve flag-like variadic content after `--`, and package handlers can use the public `suppressHostOutput()` protocol when they already emitted streaming, binary, or pre-rendered output. Declarative blueprints are also checked for reserved item-field collisions during SDK lint/preflight and harness activation, so a package cannot pass author-time validation and then fail only when users create or update items. Local archive installation, command ownership, and MCP custom-field diagnostics are tracked by [pm-lw6acw](../.agents/pm/issues/pm-lw6acw.toon), [pm-6z0wzf](../.agents/pm/issues/pm-6z0wzf.toon), and [pm-yfdav2](../.agents/pm/issues/pm-yfdav2.toon). Transactional mutation guards, host-bound command test SDKs, and installed custom-type lifecycle parity are tracked by [pm-hx23u5](../.agents/pm/issues/pm-hx23u5.toon), [pm-wx2lr5](../.agents/pm/issues/pm-wx2lr5.toon), and [pm-scga6k](../.agents/pm/issues/pm-scga6k.toon). Durable migration application, explicit source resolution, and composable preflight ownership are covered in [Extension Lifecycle Contracts](EXTENSION_LIFECYCLE.md).
 
 Packages add optional `pm` workflows without changing the core CLI. A package can ship one or more runtime extensions plus metadata such as docs and examples. Prefer the package-first commands in new docs and automation:
 
@@ -38,7 +38,7 @@ pm install calendar --project
 pm install search-advanced --project
 pm install kanban --project
 ```
-`pm install '*'`, `pm install all`, and shell-expanded `pm install *` are normalized to the same bundled install-all request. First-party package aliases come from each package manifest, with a fallback derived from the `packages/pm-*` directory name.
+`pm install '*'`, `pm install all`, and shell-expanded `pm install *` are normalized to the same bundled install-all request. First-party package aliases come from each package manifest, with a fallback derived from the `packages/pm-*` directory name. A bare bundled alias that also names an installed npm package reports both explicit choices in `source_resolution`; see [Extension Lifecycle Contracts](EXTENSION_LIFECYCLE.md).
 
 External registry packages are installed by exact package name. If `npm:<name>` returns a registry 404, JSON error output includes `fallback_candidates` and `next_best_command`; unpublished first-party packages fall back to `pm install --project github.com/unbraind/<name>`. Install results include package-owned `command_paths`, `action_paths`, `contributions`, `command_discovery`, and a light `verification` block covering the target tracker, activation status, registered commands/actions/item types, and health verdict. Agents should consume those fields instead of guessing from the package name or immediately spending another invocation on doctor. A successful activation persists the versioned contribution inventory in `.managed-extensions.json`; subsequent discovery can enumerate command handlers, hooks, parser/renderer targets, schema names, and the other registered surfaces without importing the package module. A failed runtime activation returns `ok: false`, `activated: false`, a non-zero CLI exit, and actionable diagnostics; missing SDK resolution adds an explicit dependency recovery step. Local installs are containment-safe when the extension destination is nested inside the source checkout: pm stages the package outside the source and prunes the destination, `.agents`, `node_modules`, and install-backup directories before copying, so reinstalling cannot recursively copy tracker history, host dependencies, or prior backups.
 Local `.tgz` and `.tar.gz` npm archives are inspected and extracted in an isolated temporary directory without invoking a shell. Archives must contain one `package/package.json` root, regular files/directories only, and bounded entry and expanded-byte totals. Absolute paths, traversal, alternate roots, links, device entries, oversized entries, and decompression-ratio abuse fail before installation. The managed source remains the original archive path, so reload and upgrade provenance do not point at a temporary extraction directory.

package/docs/EXTENSION_LIFECYCLE.md

@@ -0,0 +1,46 @@
+# Extension Lifecycle Contracts
+
+Tracked by [pm-ig5cfe](../.agents/pm/issues/pm-ig5cfe.toon),
+[pm-495lkc](../.agents/pm/issues/pm-495lkc.toon), and
+[pm-miy5k6](../.agents/pm/issues/pm-miy5k6.toon).
+
+## Explicit Install-Source Identity
+
+A bare target may name both a bundled alias and an already-installed npm
+package. pm preserves the bundled-first compatibility rule but never hides the
+choice. Install results include `source_resolution` with the selected source,
+an `ambiguous` indicator, every matching candidate, and an explicit command for
+each. Use `pm install npm:<package>` to force npm identity or the reported bare
+alias command to force the bundled package. Install-all results carry the same
+receipt on every package row.
+
+## Durable Extension Migrations
+
+Active packages register schema migrations through `api.registerMigration`.
+Runtime preflight applies runnable migrations, and operators can plan or apply
+the same registrations explicitly:
+
+```bash
+pm package migrate --project --dry-run --json
+pm package migrate --project --json
+pm health --check-only --json
+```
+
+`pm extension migrate` is the compatibility spelling. The SDK exposes
+`runExtensionMigrations`, `PmClient.packageMigrate`, and the one-shot
+`packageMigrate`/`extensionMigrate` helpers. Dry-run never invokes package code
+or writes state. Apply records deterministic per-migration receipts in
+`.agents/pm/extension-migrations.json` through workspace history. Successful
+migrations become idempotent `skipped` rows in later processes. Failures retain
+their error for health diagnostics and are retried on the next apply. Project
+scope includes active project and global packages because both affect that
+workspace; `--global` restricts execution to global registrations.
+
+## Scoped Preflight Ownership
+
+`definePreflightOverride` and `api.registerPreflight` accept
+`{ commands, run }`. Command paths are normalized, disjoint registrations
+compose without warnings, and runtime invokes only the matching owner. Empty or
+omitted command ownership retains the legacy global behavior and collides with
+every other override. Activation summaries and persisted contribution
+inventories expose `preflight_ownership` for static doctor and tooling output.

package/docs/README.md

@@ -59,6 +59,7 @@ pm guide release --json
 - [Portable Corpus Shapes](CORPUS_SHAPES.md) - versioned SDK populations for realistic benchmarks, evaluations, and package tests.
 - [Agent UX Contracts](AGENT_UX_CONTRACTS.md) - ordering-cycle advisories, graph count units, collision safety, compact context, ownership wording, and recovery behavior.
 - [Packages and Extensions](EXTENSIONS.md) - package install workflows, runtime extension lifecycle, and API reference.
+- [Extension Lifecycle Contracts](EXTENSION_LIFECYCLE.md) - source identity, durable migrations, and scoped preflight ownership.
 - [Extension Author Contracts](EXTENSION_AUTHOR_CONTRACTS.md) - the stability guarantees and contract surface package authors build against.
 - [SDK](SDK.md) - public import surfaces and typed authoring examples.
 - [Multi-Branch Merge Safety](MERGE_SAFETY.md) - semantic tracker merge drivers, post-merge integrity gates, delete/modify policy, and recovery-receipt retention.

package/docs/RELEASING.md

@@ -20,7 +20,8 @@ Tracked documentation work: [pm-u9d0](../.agents/pm/epics/pm-u9d0.toon),
 [pm-4s24d2](../.agents/pm/issues/pm-4s24d2.toon),
 [pm-39cqqx](../.agents/pm/tasks/pm-39cqqx.toon), stable peer compatibility
 [pm-csuce0](../.agents/pm/issues/pm-csuce0.toon), and artifact budgets
-[pm-998juj](../.agents/pm/tasks/pm-998juj.toon).
+[pm-998juj](../.agents/pm/tasks/pm-998juj.toon), plus exact-tag recovery
+[pm-lwnifd](../.agents/pm/issues/pm-lwnifd.toon).
 
 ## Version Policy
 
@@ -232,11 +233,14 @@ git push origin v<version>
 `.github/workflows/release.yml` runs on `v*.*.*` tags and handles:
 
 - full-history checkout
-- manual `workflow_dispatch` by tag for recovery when an immutable npm version already exists; the reviewed current `main` source runs the gates so a historical tag cannot be blocked by an expired external fixture
+- manual `workflow_dispatch` by tag for recovery. An authenticated exact-version probe keeps already-published access recovery on the reviewed dispatch-time `main` source; when the immutable tag exists but npm publication never completed, recovery checks out that exact tagged source and retains the original version guard
 - pnpm install with frozen lockfile
 - version policy and tag guard
 - secret scan
-- build, typecheck, test, and coverage
+- build, clone-local merge-driver installation, typecheck, test, and coverage
+- generated changelog verification and `pm-changelog` installation before the
+  tracker-bearing static gate, so a clean checkout does not misclassify the
+  managed extension's linked files as missing
 - static quality gate (shared complexity, duplication, dead/orphan module, file/folder hygiene, source/exported docstring coverage profile)
 - temporary-project compatibility gate against latest published tracker data
 - reliability threshold gate (Sentry severity threshold, bounded to a recent-activity window via `--sentry-window-days` (default `14`, `0` = unbounded) so a stale benign unresolved issue cannot block every scheduled release; `--telemetry-mode` gate policy: `off` | `best-effort` | `required`). Scheduled `auto-release.yml` failures open/update an `Auto Release blocked` GitHub issue so blocked daily releases are never silently skipped.
@@ -248,7 +252,10 @@ git push origin v<version>
 - `npm publish --access public --provenance --tag latest`, skipped on retry
   only when the exact version is anonymously visible from a fresh npm cache.
   If the package is public but the target version is absent, the workflow
-  publishes immediately without attempting a package-access mutation. Only
+  publishes immediately without attempting a package-access mutation. A
+  dispatch may do so only when its source-selection preflight pinned the
+  checkout to the requested immutable tag; reviewed-main recovery continues
+  to refuse publication of a missing target. Only
   when neither the target nor package metadata is anonymously visible does the
   same-tag recovery path attempt to restore public package access, because a
   hidden version can also return 404 to authenticated metadata reads. After a
@@ -272,7 +279,7 @@ git push origin v<version>
   `scripts/release/verify-installed-agent-session.mjs`. Separate npm and Bun
   install roots must contain the resolved executable, then each drives the
   cold-start `init -> context -> create -> claim -> annotate -> files -> close
-  -> validate -> get -> context` loop. The structured report identifies the
+-> validate -> get -> context` loop. The structured report identifies the
   failing step and records per-step output ceilings and estimated token cost.
 - GitHub Release creation
 - GitHub Release metadata verification through the same local verification script
@@ -312,25 +319,31 @@ Use the npm registry package for maintainer global updates. Do not use `npm inst
   ordinal recovery version. Rerun `.github/workflows/release.yml` with
   `workflow_dispatch` and `tag=v<version>` (or close the current bot-created
   blocker once to trigger the guarded exact-run recovery). The workflow skips
-  duplicate npm publication for an anonymously visible version and attempts
-  protected access recovery before anonymous probes. A dispatch refuses to
-  publish when that immutable version is absent; first publication remains owned
-  by the original tag-push run.
-  Authenticated metadata is not used as the existence oracle because a hidden
-  immutable version can return 404 there as well.
+  duplicate npm publication for an anonymously visible version. Before
+  installing or running gates, dispatch performs an authenticated exact-version
+  probe. An
+  existing version keeps the reviewed dispatch-time `main` source and cannot
+  be republished. A definitive missing-version response pins the checkout to
+  the existing immutable tag, reapplies the version guard, installs the managed
+  changelog extension before tracker measurement, and permits first publication
+  only from that exact tagged source. Other registry failures stop before
+  source selection or publication.
 - If an immutable published package contains a defect that cannot be repaired
   by rerunning the same tag workflow, document the incident and ship the code
   fix in the next UTC day's release.
-- A manual exact-tag `workflow_dispatch` recovery reasserts public npm package
-  access before consulting anonymous registry metadata. This prevents a stale
-  public cache hit from bypassing access repair; an already-visible immutable
-  version is still verified and never republished. Recovery checks out the
+- A manual exact-tag `workflow_dispatch` recovery uses isolated anonymous
+  registry probes before any account-level access mutation. A visible package
+  with a missing target version proceeds directly to exact-tag publication, so
+  a publish-capable automation token is not required to change package access.
+  Access recovery is reserved for the ambiguous case where neither the package
+  nor target version is anonymously visible. An already-visible immutable
+  version is still verified and never republished. Recovery starts from the
   dispatch-time commit SHA and fails unless the dispatch ref is the repository
-  default branch (`main`), while `RELEASE_TAG` keeps the requested immutable
-  version as the verification target. Historical recovery validates
-  the tag shape but intentionally does not require current `package.json` to
-  equal that older version; dispatch cannot publish, so this does not weaken the
-  original tag-push version guard.
+  default branch (`main`). It remains on that reviewed source when the exact
+  npm version exists. When the version is definitively absent, it switches to
+  the resolved commit behind `RELEASE_TAG`, requires `package.json` to match the
+  tag, installs the clone-local merge driver and managed changelog extension,
+  and may publish that exact source after every gate passes.
 - Record failure evidence and remediation in the release `pm` item.
 
 ### Silent skip debugging