@unbrained/pm-cli 2026.5.31 → 2026.6.5

package/dist/cli-bundle/main.js

@@ -1,10 +1,7 @@
 #!/usr/bin/env node
-import {
-  levenshteinDistanceWithinLimit
-} from "./chunks/chunk-EAOG77HM.js";
 import {
   migrateItemFilesToFormat
-} from "./chunks/chunk-KBQY3YG5.js";
+} from "./chunks/chunk-BNL6S7QH.js";
 import {
   applyDefaultOutputFormat,
   clearResolvedGlobalOptions,
@@ -14,33 +11,32 @@ import {
   getGlobalOptions,
   invalidateSearchCachesForMutation,
   setResolvedGlobalOptions
-} from "./chunks/chunk-P53TN6IA.js";
+} from "./chunks/chunk-TK633IVD.js";
 import {
   PM_CORE_COMMAND_NAMES,
   resolveSubcommandFlagContractsForCommand
-} from "./chunks/chunk-GN7IJPCD.js";
-import "./chunks/chunk-6HT2F4TK.js";
+} from "./chunks/chunk-ZQ4F6EC4.js";
+import "./chunks/chunk-5IRA6IYD.js";
 import {
   printError,
   printResult,
   writeStdout
-} from "./chunks/chunk-5HSEP75M.js";
+} from "./chunks/chunk-HZOS2UG5.js";
 import {
-  resolvePmPackageRootFromModule
-} from "./chunks/chunk-EGUGFSNX.js";
-import "./chunks/chunk-BUPWJ3IJ.js";
-import "./chunks/chunk-4AEZR5EJ.js";
-import "./chunks/chunk-CEFIVZPG.js";
-import "./chunks/chunk-MD7K4JYF.js";
+  levenshteinDistanceWithinLimit
+} from "./chunks/chunk-EAOG77HM.js";
+import "./chunks/chunk-XG7RJYHV.js";
+import "./chunks/chunk-KA24HME7.js";
+import "./chunks/chunk-HPH6X4ZZ.js";
 import {
   commandOptionFlagLabel,
   resolveCommandOptionPolicyState,
   resolveItemTypeRegistry,
   resolveTypeDefinition
-} from "./chunks/chunk-WDPXDQFG.js";
+} from "./chunks/chunk-4PJQSECJ.js";
 import {
   nowIso
-} from "./chunks/chunk-PVNQLCIS.js";
+} from "./chunks/chunk-RANZIID5.js";
 import {
   BUILTIN_ITEM_TYPE_VALUES,
   EXIT_CODE,
@@ -49,6 +45,9 @@ import {
   appendLineAtomic,
   asRecordOrNull,
   clearActiveExtensionHooks,
+  consumeAfterCommandAffectedItems,
+  createEmptyExtensionRegistrationRegistry,
+  discoverExtensions,
   getActiveCommandResult,
   getActiveExtensionRegistrations,
   getSettingsPath,
@@ -58,6 +57,7 @@ import {
   readSettings,
   readSettingsWithMetadata,
   resolveGlobalPmRoot,
+  resolvePmPackageRootFromModule,
   resolvePmRoot,
   resolveRuntimeFieldRegistry,
   resolveTelemetryErrorCategory,
@@ -79,7 +79,7 @@ import {
   toNonEmptyStringOrUndefined,
   writeFileAtomic,
   writeSettings
-} from "./chunks/chunk-LSXGH6NE.js";
+} from "./chunks/chunk-SRVKTWPR.js";
 
 // dist/cli/main.js
 import fs2 from "node:fs";
@@ -92,13 +92,13 @@ import { stdin as input, stdout as output } from "node:process";
 !(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] = "6fcbb185-889c-5474-9f02-321a53177803");
+    n && (e._sentryDebugIds = e._sentryDebugIds || {}, e._sentryDebugIds[n] = "c965da5d-6609-5258-ba49-a57475f7f2ef");
   } catch (e2) {
   }
 })();
 var TELEMETRY_PROMPT_DISABLE_ENV = "PM_TELEMETRY_PROMPT";
 var TELEMETRY_PROMPT_DISABLE_VALUES = /* @__PURE__ */ new Set(["0", "false", "no", "off"]);
-var TELEMETRY_PROMPT_SKIPPED_COMMANDS = /* @__PURE__ */ new Set(["init", "completion", "completion-tags"]);
+var TELEMETRY_PROMPT_SKIPPED_COMMANDS = /* @__PURE__ */ new Set(["init", "completion", "completion-statuses", "completion-tags", "completion-types"]);
 function parseBooleanLike(value) {
   if (typeof value !== "string") {
     return false;
@@ -180,11 +180,11 @@ import path from "node:path";
 !(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] = "05b6b4cc-d37d-593c-b34c-b491c722d181");
+    n && (e._sentryDebugIds = e._sentryDebugIds || {}, e._sentryDebugIds[n] = "ad10a6ab-5a76-55e1-9750-1613c8210700");
   } catch (e2) {
   }
 })();
-var SETUP_ROOT_COMMANDS = /* @__PURE__ */ new Set(["init", "config", "completion", "completion-tags"]);
+var SETUP_ROOT_COMMANDS = /* @__PURE__ */ new Set(["init", "config", "completion", "completion-statuses", "completion-tags", "completion-types"]);
 var QUERY_ROOT_COMMANDS = /* @__PURE__ */ new Set([
   "list",
   "list-all",
@@ -210,6 +210,7 @@ var MUTATION_ROOT_COMMANDS = /* @__PURE__ */ new Set([
   "create",
   "update",
   "update-many",
+  "close-many",
   "append",
   "close",
   "delete",
@@ -2344,7 +2345,7 @@ function parseLooseCommandOptions(args) {
 !(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] = "87ab8982-4eaf-5b48-88af-96ff4450ab0f");
+    n && (e._sentryDebugIds = e._sentryDebugIds || {}, e._sentryDebugIds[n] = "ed65d7db-f9b0-5c53-ba96-b13eb4d6cd35");
   } catch (e2) {
   }
 })();
@@ -2488,6 +2489,70 @@ var HELP_BY_COMMAND_PATH = {
       "Use --dry-run before upgrade when automation needs a deterministic plan."
     ]
   },
+  "package init": {
+    why: "Generates an installable starter pm package with package metadata and a root extension entrypoint.",
+    examples: [
+      "pm package init ./my-package",
+      "pm install ./my-package --project",
+      "pm package doctor --project --detail summary"
+    ],
+    tips: [
+      "The generated package is local-install safe; add SDK runtime imports only after declaring dependencies and validating with package doctor.",
+      "Use package doctor after changes to verify activation, policy, and collision diagnostics."
+    ]
+  },
+  "package install": {
+    why: "Installs pm packages from local paths, npm sources, GitHub sources, bundled aliases, or wildcard/all aliases.",
+    examples: [
+      "pm package install ./my-package --project",
+      "pm install npm:pm-changelog --project",
+      "pm package install --github org/repo/packages/my-pm-package --ref main"
+    ],
+    tips: [
+      "Prefer the top-level pm install alias in scripts when only installation is needed.",
+      "Run pm package manage or pm package doctor after installing external packages."
+    ]
+  },
+  "package catalog": {
+    why: "Lists bundled first-party package catalog metadata and compact field projections.",
+    examples: [
+      "pm package catalog --project",
+      "pm package catalog --project --fields alias,installed,install_command",
+      "pm package list --project --fields alias,package_name,category"
+    ],
+    tips: [
+      "Use --fields for low-token package discovery in agent loops.",
+      "External npm package discovery still belongs to npm search."
+    ]
+  },
+  "extension init": {
+    why: "Generates an installable starter runtime extension with manifest and entrypoint files.",
+    examples: [
+      "pm extension init ./my-extension",
+      "pm extension --install --project ./my-extension",
+      "pm extension --doctor --project --detail summary"
+    ],
+    tips: [
+      "Use package init for new distributable package workflows; extension init is the compatibility-level runtime scaffold."
+    ]
+  },
+  "extension install": {
+    why: "Installs a compatibility runtime extension from local, npm, GitHub, bundled alias, or wildcard sources.",
+    examples: [
+      "pm extension install ./my-extension --project",
+      "pm extension --install --project ./my-extension",
+      "pm extension doctor --project --detail summary"
+    ],
+    tips: ["Prefer pm install or pm package install for new package-first automation."]
+  },
+  "extension catalog": {
+    why: "Compatibility view of bundled package catalog metadata.",
+    examples: [
+      "pm extension catalog --project",
+      "pm extension catalog --project --fields alias,installed,install_command"
+    ],
+    tips: ["Prefer pm package catalog in new user-facing workflows."]
+  },
   install: {
     why: "Installs a pm package into project scope by default, using local, npm, GitHub, or bundled alias sources.",
     examples: [
@@ -2553,6 +2618,21 @@ var HELP_BY_COMMAND_PATH = {
       "Checkpoints are enabled by default for apply mode and can be restored with --rollback."
     ]
   },
+  "close-many": {
+    why: "Bulk-closes matched items with a shared reason routed through full pm close semantics (close validation, active-child orphan checks, blocked-edge cleanup) plus dry-run previews and rollback checkpoints \u2014 unlike update-many --status closed, which bypasses close validation.",
+    examples: [
+      'pm close-many --filter-sprint S-12 --reason "Sprint S-12 acceptance criteria met" --dry-run',
+      'pm close-many --filter-tag wave:7 --reason "Superseded by redesign" --validate-close warn',
+      'pm close-many --ids pm-a,pm-b,pm-c --reason "Closed in batch" --resolution "Verified by integration suite"',
+      "pm close-many --rollback close-many-20260604-abc123"
+    ],
+    tips: [
+      "At least one filter (--filter-* or --ids) is required so close-many never matches every item.",
+      "Already-terminal matches are skipped by default; pass --force to re-close them.",
+      "Use --dry-run to preview matches plus per-item skip reasons and active-child orphan warnings before applying.",
+      "Checkpoints are enabled by default for apply mode; restore with --rollback <checkpoint-id>."
+    ]
+  },
   normalize: {
     why: "Scans items for low-signal lifecycle metadata drift, emits deterministic per-item plans, and optionally applies normalized metadata updates with update-style safety checks.",
     examples: [
@@ -2715,7 +2795,7 @@ var HELP_BY_COMMAND_PATH = {
       "pm get pm-a1b2 --fields id,title,status,parent,type --json"
     ],
     tips: [
-      "Default depth is deep for backward compatibility; use brief for metadata-only checks and standard for body plus linked artifacts without append-only logs.",
+      "Default depth is standard for body plus linked artifacts without append-only logs; use brief for metadata-only checks or --full for complete history-heavy metadata.",
       "Use --fields for the smallest deterministic item metadata payload when an agent only needs specific fields.",
       "JSON output shape is { item, body, linked, claim_state }; body is top-level (not item.body)."
     ]
@@ -2980,7 +3060,7 @@ function attachRichHelpText(program2, argv = process.argv.slice(2)) {
 !(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] = "92cba1f2-f9c5-5748-90ce-ab2049ada502");
+    n && (e._sentryDebugIds = e._sentryDebugIds || {}, e._sentryDebugIds[n] = "7f17a5b9-5783-523d-b9cd-61968ddd9ed2");
   } catch (e2) {
   }
 })();
@@ -2996,13 +3076,17 @@ function normalizeLongOptionFlag(token) {
 }
 function extractProvidedOptionFlags(argv) {
   const provided = /* @__PURE__ */ new Set();
+  const ordered = [];
   for (const token of argv) {
     const normalized = normalizeLongOptionFlag(token);
     if (normalized) {
+      if (!provided.has(normalized)) {
+        ordered.push(normalized);
+      }
       provided.add(normalized);
     }
   }
-  return [...provided].sort((left, right) => left.localeCompare(right));
+  return ordered;
 }
 function quoteCommandArg(arg) {
   if (/^[A-Za-z0-9._:/@=-]+$/.test(arg)) {
@@ -3018,7 +3102,7 @@ function renderPmCommand(argv) {
 !(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] = "98367a9e-b72b-56c3-a337-fcc10e562f6e");
+    n && (e._sentryDebugIds = e._sentryDebugIds || {}, e._sentryDebugIds[n] = "883618a4-a53f-5506-ab97-d734647806e7");
   } catch (e2) {
   }
 })();
@@ -3181,6 +3265,10 @@ function guidanceToClassification(message) {
 function normalizeMessage(message) {
   return message.replace(/\(outputHelp\)/g, "").trim();
 }
+function isModuleResolutionErrorMessage(message) {
+  const normalized = message.toLowerCase();
+  return normalized.includes("cannot find module") || normalized.includes("cannot find package") || normalized.includes("err_module_not_found") || normalized.includes("module_not_found");
+}
 function normalizeContextList(values) {
   if (!Array.isArray(values)) {
     return void 0;
@@ -3600,10 +3688,26 @@ function formatUnknownErrorForJson(rawMessage, exitCode) {
   return guidanceToJsonEnvelope(guidance, exitCode);
 }
 function buildUnknownErrorGuidance(rawMessage) {
+  const message = normalizeMessage(rawMessage);
+  if (isModuleResolutionErrorMessage(message)) {
+    return makeGuidanceMessage({
+      code: "module_import_failed",
+      title: "Module import failed",
+      happened: message,
+      required: "Ensure the active checkout is built and any package or extension entry file exists before retrying.",
+      why: "Node could not resolve an imported module. In pm this usually means an extension/package entrypoint, build artifact, or dependency is missing from the active runtime.",
+      examples: ["pnpm build", "pm package manage --doctor --project", "pm health --check-only --json"],
+      nextSteps: [
+        "Rebuild the checkout or package that provides the missing module.",
+        "Run package doctor for installed extensions when the failure follows package installation or activation.",
+        "Rerun the original pm command after the runtime files are present."
+      ]
+    });
+  }
   return makeGuidanceMessage({
     code: "unknown_error",
     title: "Unhandled error",
-    happened: normalizeMessage(rawMessage),
+    happened: message,
     required: "Inspect command input and runtime state, then retry.",
     why: "Unexpected runtime failures can occur from environment or extension-level issues.",
     examples: ["pm --help", "pm health --json"]
@@ -4009,7 +4113,7 @@ function ensureCommandPath(root, pathParts) {
 !(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] = "09a59142-b988-5127-9105-7bdfc1f9c832");
+    n && (e._sentryDebugIds = e._sentryDebugIds || {}, e._sentryDebugIds[n] = "abcf109c-c846-5b61-b510-f1ad6ff4f3aa");
   } catch (e2) {
   }
 })();
@@ -4520,7 +4624,8 @@ function normalizeBootstrapInvocation(argv) {
   }
   const aliasNormalized = rewriteCommandAlias(legacyNormalized, trace);
   const commandName = parseBootstrapCommandName(aliasNormalized);
-  const lookup = buildFlagLookup(commandName);
+  const commandPathName = parseBootstrapCommandPathName(aliasNormalized);
+  const lookup = buildFlagLookup(commandPathName ?? commandName);
   const normalizedArgv = [];
   for (let index = 0; index < aliasNormalized.length; index += 1) {
     const token = aliasNormalized[index];
@@ -4564,6 +4669,15 @@ function normalizeBootstrapInvocation(argv) {
     trace
   };
 }
+function parseBootstrapCommandPathName(argv) {
+  const stripped = stripGlobalBootstrapTokens(argv);
+  const first = stripped[0]?.trim().toLowerCase();
+  const second = stripped[1]?.trim().toLowerCase();
+  if ((first === "extension" || first === "package" || first === "packages") && typeof second === "string" && second.length > 0 && !second.startsWith("-")) {
+    return `${first} ${second}`;
+  }
+  return first;
+}
 function parseBootstrapTypeValue(argv) {
   for (let index = 0; index < argv.length; index += 1) {
     const token = argv[index];
@@ -5427,7 +5541,7 @@ function attachCreateUpdatePolicyHelpText(rootProgram, typeRegistry, argv) {
 !(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] = "fb080e3e-ad71-5608-a944-ce887395e3e9");
+    n && (e._sentryDebugIds = e._sentryDebugIds || {}, e._sentryDebugIds[n] = "85d31f87-d392-5da2-9d53-1525fb938ff2");
   } catch (e2) {
   }
 })();
@@ -5457,6 +5571,7 @@ var TELEMETRY_COMMAND_RESOLUTION_SET = /* @__PURE__ */ new Set([
 var TELEMETRY_RESOLUTION_STAGE_SET = /* @__PURE__ */ new Set(["parse", "preflight", "execute", "unknown"]);
 var TELEMETRY_ERROR_CATEGORY_SET = /* @__PURE__ */ new Set(["usage", "validation", "conflict", "runtime", "unknown"]);
 var runtimeExtensionSnapshotCache = null;
+var runtimeExtensionDiscoverySnapshotCache = null;
 var activeRuntimeExtensionCommandDescriptors = /* @__PURE__ */ new Map();
 var HANDLED_ERROR_SENTRY_FLUSH_TIMEOUT_MS = 250;
 var EXPECTED_HANDLED_ERROR_EXIT_CODES = /* @__PURE__ */ new Set([
@@ -5465,10 +5580,10 @@ var EXPECTED_HANDLED_ERROR_EXIT_CODES = /* @__PURE__ */ new Set([
   EXIT_CODE.CONFLICT
 ]);
 var TRUE_LIKE_ENV_VALUES = /* @__PURE__ */ new Set(["1", "true", "yes", "on"]);
-var loadSetupRegistrationModule = createLazyModule(() => import("./chunks/register-setup-V56GDRUS.js"));
-var loadListQueryRegistrationModule = createLazyModule(() => import("./chunks/register-list-query-UP3VRUFS.js"));
-var loadMutationRegistrationModule = createLazyModule(() => import("./chunks/register-mutation-YWSBF545.js"));
-var loadOperationRegistrationModule = createLazyModule(() => import("./chunks/register-operations-3BDTGSDH.js"));
+var loadSetupRegistrationModule = createLazyModule(() => import("./chunks/register-setup-YJKIQRKA.js"));
+var loadListQueryRegistrationModule = createLazyModule(() => import("./chunks/register-list-query-AG3XKXWL.js"));
+var loadMutationRegistrationModule = createLazyModule(() => import("./chunks/register-mutation-RSMT6DPK.js"));
+var loadOperationRegistrationModule = createLazyModule(() => import("./chunks/register-operations-Q54JQZUN.js"));
 function describeUnknownError(error) {
   if (error instanceof PmCliError) {
     return error.message;
@@ -5533,7 +5648,7 @@ function buildPmCliRecoveryContext(context, invocationArgv, rawMessage) {
   if (!suggestedRetry) {
     suggestedRetry = attemptedCommand;
   }
-  if (suggestedRetry === attemptedCommand) {
+  if (!existingRecovery?.suggested_retry && suggestedRetry === attemptedCommand) {
     suggestedRetry = void 0;
   }
   const recovery = {
@@ -5711,17 +5826,28 @@ async function runAndClearAfterCommandHooks(outcome) {
     clearActiveExtensionHooks();
     return;
   }
-  const hookWarnings = await runAfterCommandHooks(runtime.hooks, {
-    command: runtime.commandName,
-    args: runtime.commandArgs,
-    options: { ...runtime.commandOptions },
-    global: { ...runtime.globalOptions },
-    pm_root: runtime.pmRoot,
-    ok: outcome.ok,
-    error: outcome.error,
-    result: getActiveCommandResult()
-  });
-  clearActiveExtensionHooks();
+  let hookWarnings = [];
+  try {
+    hookWarnings = await runAfterCommandHooks(runtime.hooks, {
+      command: runtime.commandName,
+      args: runtime.commandArgs,
+      options: { ...runtime.commandOptions },
+      global: { ...runtime.globalOptions },
+      pm_root: runtime.pmRoot,
+      ok: outcome.ok,
+      error: outcome.error,
+      result: getActiveCommandResult(),
+      affected: consumeAfterCommandAffectedItems()
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    hookWarnings = [`afterCommand hooks failed: ${message}`];
+  } finally {
+    clearActiveExtensionHooks();
+  }
+  if (!runtime.globalOptions.json && hookWarnings.length > 0) {
+    printError(`[pm] warning: afterCommand hook_warnings=${formatHookWarnings(hookWarnings)}`);
+  }
   if (runtime.profileEnabled && hookWarnings.length > 0) {
     printError(`profile:extensions hook_warnings=${formatHookWarnings(hookWarnings)}`);
   }
@@ -5920,6 +6046,18 @@ async function registerRuntimeSchemaFieldFlags(rootProgram, invocationArgv) {
     }
   }
 }
+async function maybeAttachCreateUpdatePolicyHelpText(rootProgram, pmRoot, invocationArgv, registrations, settings) {
+  const bootstrapCommand = parseBootstrapCommandName(invocationArgv);
+  if (bootstrapCommand !== "create" && bootstrapCommand !== "update") {
+    return;
+  }
+  try {
+    const resolvedSettings = settings ?? await readSettings(pmRoot);
+    const typeRegistry = resolveItemTypeRegistry(resolvedSettings, registrations);
+    attachCreateUpdatePolicyHelpText(rootProgram, typeRegistry, invocationArgv);
+  } catch {
+  }
+}
 function defaultPreflightDecision() {
   return {
     enforce_item_format_gate: true,
@@ -5931,6 +6069,180 @@ function defaultPreflightDecision() {
 function buildRuntimeExtensionSnapshotCacheKey(pmRoot) {
   return `pm-root:${pmRoot}`;
 }
+function bootstrapProfileEnabled(invocationArgv) {
+  return invocationArgv.some((token) => token === "--profile");
+}
+function buildRuntimeExtensionDiscoverySnapshotCacheKey(pmRoot) {
+  return `pm-root:${pmRoot}`;
+}
+function collectLeadingCommandArgs(commandArgs) {
+  const leading = [];
+  for (const arg of commandArgs ?? []) {
+    if (arg.startsWith("-")) {
+      break;
+    }
+    const normalized = normalizeExtensionCommandPath(arg);
+    if (normalized.length === 0) {
+      continue;
+    }
+    leading.push(normalized);
+  }
+  return leading;
+}
+function collectActivationCommandCandidates(probe) {
+  const commandPath = normalizeExtensionCommandPath(probe.commandPath ?? "");
+  if (commandPath.length === 0) {
+    return [];
+  }
+  const candidates = [commandPath];
+  const parts = commandPath.split(" ").filter((part) => part.length > 0);
+  for (const arg of collectLeadingCommandArgs(probe.commandArgs)) {
+    parts.push(...arg.split(" ").filter((part) => part.length > 0));
+    candidates.push(parts.join(" "));
+  }
+  return [...new Set(candidates)];
+}
+function activationCommandMatchesProbe(command, probe) {
+  const normalized = normalizeExtensionCommandPath(command);
+  if (normalized.length === 0) {
+    return false;
+  }
+  const candidates = collectActivationCommandCandidates(probe);
+  for (const candidate of candidates) {
+    if (candidate === normalized || candidate.startsWith(`${normalized} `)) {
+      return true;
+    }
+  }
+  if (probe.allowCommandPrefixMatch === true) {
+    return candidates.some((candidate) => normalized.startsWith(`${candidate} `));
+  }
+  return false;
+}
+function extensionActivationCommands(extension) {
+  return extension.activation?.commands ?? [];
+}
+function extensionCapabilities(extension) {
+  return new Set((extension.capabilities ?? []).map((capability) => capability.trim().toLowerCase()));
+}
+var GLOBAL_EXTENSION_ACTIVATION_CAPABILITIES = /* @__PURE__ */ new Set(["hooks", "parser", "preflight", "renderers"]);
+var CONSERVATIVE_EXTENSION_ACTIVATION_CAPABILITIES = /* @__PURE__ */ new Set(["commands", "schema", "services"]);
+var SEARCH_EXTENSION_ACTIVATION_COMMANDS = /* @__PURE__ */ new Set(["reindex", "search", "search-advanced"]);
+var CREATE_TEMPLATE_FLAGS = /* @__PURE__ */ new Set(["--template"]);
+function hasAnyCapability(capabilities, expected) {
+  for (const capability of expected) {
+    if (capabilities.has(capability)) {
+      return true;
+    }
+  }
+  return false;
+}
+function commandPathNeedsSearchExtensions(commandPath) {
+  const normalized = normalizeExtensionCommandPath(commandPath ?? "");
+  if (normalized.length === 0) {
+    return false;
+  }
+  const [topLevel] = normalized.split(" ");
+  return SEARCH_EXTENSION_ACTIVATION_COMMANDS.has(topLevel ?? normalized);
+}
+function probeUsesAnyFlag(probe, flags) {
+  for (const arg of probe.commandArgs ?? []) {
+    if (!arg.startsWith("--")) {
+      continue;
+    }
+    const [flagName] = arg.split("=", 1);
+    if (flags.has(flagName)) {
+      return true;
+    }
+  }
+  return false;
+}
+function commandPathNeedsTemplateExtensions(probe) {
+  return normalizeExtensionCommandPath(probe.commandPath ?? "") === "create" && probeUsesAnyFlag(probe, CREATE_TEMPLATE_FLAGS);
+}
+function extensionProvidesTemplatesRuntime(commands) {
+  return commands.some((command) => {
+    const normalized = normalizeExtensionCommandPath(command);
+    return normalized === "templates" || normalized.startsWith("templates ");
+  });
+}
+function extensionNeedsActivationForProbe(extension, probe) {
+  const capabilities = extensionCapabilities(extension);
+  const commands = extensionActivationCommands(extension);
+  if (commands.length > 0 && commands.some((command) => activationCommandMatchesProbe(command, probe))) {
+    return true;
+  }
+  if (hasAnyCapability(capabilities, GLOBAL_EXTENSION_ACTIVATION_CAPABILITIES)) {
+    return true;
+  }
+  if (commandPathNeedsTemplateExtensions(probe) && extensionProvidesTemplatesRuntime(commands)) {
+    return true;
+  }
+  if (capabilities.has("search")) {
+    return commandPathNeedsSearchExtensions(probe.commandPath);
+  }
+  if (commands.length > 0) {
+    return false;
+  }
+  if (hasAnyCapability(capabilities, CONSERVATIVE_EXTENSION_ACTIVATION_CAPABILITIES)) {
+    return true;
+  }
+  if (capabilities.has("importers")) {
+    return probe.allowCommandPrefixMatch === true;
+  }
+  return false;
+}
+function discoveryNeedsActivationForProbe(discovery, probe) {
+  if (discovery.effective.length === 0) {
+    return false;
+  }
+  const hasCommandProbe = normalizeExtensionCommandPath(probe.commandPath ?? "").length > 0;
+  if (!hasCommandProbe) {
+    return discovery.effective.some((extension) => {
+      const capabilities = extensionCapabilities(extension);
+      return extensionActivationCommands(extension).length > 0 || hasAnyCapability(capabilities, GLOBAL_EXTENSION_ACTIVATION_CAPABILITIES) || hasAnyCapability(capabilities, CONSERVATIVE_EXTENSION_ACTIVATION_CAPABILITIES) || capabilities.has("importers") || capabilities.has("search");
+    });
+  }
+  return discovery.effective.some((extension) => extensionNeedsActivationForProbe(extension, probe));
+}
+function buildBootstrapActivationProbe(invocationArgv) {
+  const helpRequest = parseBootstrapHelpRequest(invocationArgv);
+  if (helpRequest.requested && helpRequest.commandPathTokens.length > 0) {
+    const [commandPath, ...commandArgs] = helpRequest.commandPathTokens;
+    return {
+      commandPath,
+      commandArgs,
+      allowCommandPrefixMatch: true
+    };
+  }
+  const stripped = stripGlobalBootstrapTokens(invocationArgv);
+  const commandIndex = stripped.findIndex((token) => token.trim().length > 0 && !token.startsWith("-"));
+  if (commandIndex < 0) {
+    return {};
+  }
+  return {
+    commandPath: stripped[commandIndex],
+    commandArgs: stripped.slice(commandIndex + 1),
+    allowCommandPrefixMatch: helpRequest.requested
+  };
+}
+function collectParsedActivationCommandArgs(command) {
+  const commandArgs = command.args.map(String);
+  const commandPath = normalizeExtensionCommandPath(getCommandPath(command));
+  if (commandPath === "create") {
+    const options = command.optsWithGlobals();
+    if (typeof options.template === "string" && options.template.trim().length > 0) {
+      commandArgs.push("--template");
+    }
+  }
+  return commandArgs;
+}
+function emitSettingsReadWarnings(warnings) {
+  for (const warning of warnings) {
+    if (warning.startsWith("settings_read_")) {
+      printError(`[pm] warning: ${warning} \u2014 settings.json could not be loaded and pm fell back to defaults; run pm health for remediation.`);
+    }
+  }
+}
 function emitExtensionProfile(globalOptions, snapshot) {
   if (!globalOptions.profile) {
     return;
@@ -5940,6 +6252,55 @@ function emitExtensionProfile(globalOptions, snapshot) {
     printError(`profile:extensions activation_warnings=${formatHookWarnings(snapshot.activationWarnings)}`);
   }
 }
+function emitExtensionSkippedProfile(profileEnabled, snapshot, probe) {
+  if (!profileEnabled) {
+    return;
+  }
+  const command = normalizeExtensionCommandPath(probe.commandPath ?? "") || "<none>";
+  printError(`profile:extensions activation=skipped command=${command} effective=${snapshot.discovery.effective.length} warnings=${snapshot.discovery.warnings.length} discovery_ms=${snapshot.discoveryMs}`);
+}
+async function loadRuntimeExtensionDiscoverySnapshot(pmRoot) {
+  const cacheKey = buildRuntimeExtensionDiscoverySnapshotCacheKey(pmRoot);
+  if (runtimeExtensionDiscoverySnapshotCache?.key === cacheKey) {
+    return runtimeExtensionDiscoverySnapshotCache.snapshot;
+  }
+  const settingsPath = getSettingsPath(pmRoot);
+  if (!await pathExists(settingsPath)) {
+    runtimeExtensionDiscoverySnapshotCache = {
+      key: cacheKey,
+      snapshot: null
+    };
+    return null;
+  }
+  try {
+    const startedAt = Date.now();
+    const { settings, warnings: settingsReadWarnings } = await readSettingsWithMetadata(pmRoot);
+    const discovery = await discoverExtensions({
+      pmRoot,
+      settings,
+      cwd: process.cwd(),
+      noExtensions: false
+    });
+    const snapshot = {
+      pmRoot,
+      settings,
+      discovery,
+      discoveryMs: Date.now() - startedAt,
+      settingsReadWarnings: [...settingsReadWarnings]
+    };
+    runtimeExtensionDiscoverySnapshotCache = {
+      key: cacheKey,
+      snapshot
+    };
+    return snapshot;
+  } catch {
+    runtimeExtensionDiscoverySnapshotCache = {
+      key: cacheKey,
+      snapshot: null
+    };
+    return null;
+  }
+}
 async function loadRuntimeExtensionSnapshot(pmRoot) {
   const cacheKey = buildRuntimeExtensionSnapshotCacheKey(pmRoot);
   if (runtimeExtensionSnapshotCache?.key === cacheKey) {
@@ -6003,9 +6364,26 @@ async function loadRuntimeExtensionSnapshot(pmRoot) {
 async function maybeLoadRuntimeExtensions(command) {
   const globalOptions = getGlobalOptions(command);
   if (globalOptions.noExtensions) {
+    const noExtPmRoot = resolvePmRoot(process.cwd(), globalOptions.path);
+    if (await pathExists(getSettingsPath(noExtPmRoot))) {
+      emitSettingsReadWarnings((await readSettingsWithMetadata(noExtPmRoot)).warnings);
+    }
     return null;
   }
   const pmRoot = resolvePmRoot(process.cwd(), globalOptions.path);
+  const discoverySnapshot = await loadRuntimeExtensionDiscoverySnapshot(pmRoot);
+  if (!discoverySnapshot) {
+    return null;
+  }
+  emitSettingsReadWarnings(discoverySnapshot.settingsReadWarnings);
+  const probe = {
+    commandPath: getCommandPath(command),
+    commandArgs: collectParsedActivationCommandArgs(command)
+  };
+  if (!discoveryNeedsActivationForProbe(discoverySnapshot.discovery, probe)) {
+    emitExtensionSkippedProfile(globalOptions.profile, discoverySnapshot, probe);
+    return null;
+  }
   const snapshot = await loadRuntimeExtensionSnapshot(pmRoot);
   if (!snapshot) {
     return null;
@@ -6197,22 +6575,37 @@ function wrapProgramActionsForExtensionHandlers(rootProgram) {
 }
 async function registerDynamicExtensionCommandPaths(rootProgram, invocationArgv) {
   const bootstrapGlobalOptions = parseBootstrapGlobalOptions(invocationArgv);
+  const pmRoot = resolvePmRoot(process.cwd(), bootstrapGlobalOptions.path);
   if (bootstrapGlobalOptions.noExtensions) {
     activeRuntimeExtensionCommandDescriptors = /* @__PURE__ */ new Map();
     setActiveExtensionServices({ overrides: [] });
+    await maybeAttachCreateUpdatePolicyHelpText(rootProgram, pmRoot, invocationArgv, createEmptyExtensionRegistrationRegistry());
+    return;
+  }
+  const discoverySnapshot = await loadRuntimeExtensionDiscoverySnapshot(pmRoot);
+  const probe = buildBootstrapActivationProbe(invocationArgv);
+  if (!discoverySnapshot) {
+    activeRuntimeExtensionCommandDescriptors = /* @__PURE__ */ new Map();
+    setActiveExtensionServices({ overrides: [] });
+    return;
+  }
+  if (!discoveryNeedsActivationForProbe(discoverySnapshot.discovery, probe)) {
+    activeRuntimeExtensionCommandDescriptors = /* @__PURE__ */ new Map();
+    setActiveExtensionServices({ overrides: [] });
+    await maybeAttachCreateUpdatePolicyHelpText(rootProgram, pmRoot, invocationArgv, createEmptyExtensionRegistrationRegistry(), discoverySnapshot.settings);
+    emitExtensionSkippedProfile(bootstrapProfileEnabled(invocationArgv), discoverySnapshot, probe);
     return;
   }
-  const pmRoot = resolvePmRoot(process.cwd(), bootstrapGlobalOptions.path);
   const snapshot = await loadRuntimeExtensionSnapshot(pmRoot);
   if (!snapshot) {
     activeRuntimeExtensionCommandDescriptors = /* @__PURE__ */ new Map();
     setActiveExtensionServices({ overrides: [] });
+    await maybeAttachCreateUpdatePolicyHelpText(rootProgram, pmRoot, invocationArgv, createEmptyExtensionRegistrationRegistry(), discoverySnapshot.settings);
     return;
   }
   setActiveExtensionServices(snapshot.services);
   activeRuntimeExtensionCommandDescriptors = new Map(snapshot.commandDescriptors);
-  const typeRegistry = resolveItemTypeRegistry(snapshot.settings, snapshot.registrations);
-  attachCreateUpdatePolicyHelpText(rootProgram, typeRegistry, invocationArgv);
+  await maybeAttachCreateUpdatePolicyHelpText(rootProgram, pmRoot, invocationArgv, snapshot.registrations, snapshot.settings);
   const commandPaths = [.../* @__PURE__ */ new Set([...snapshot.commandHandlers, ...snapshot.commandDescriptors.keys()])].sort((left, right) => left.localeCompare(right));
   for (const commandPath of commandPaths) {
     const pathParts = commandPath.split(" ").filter((part) => part.length > 0);
@@ -6450,6 +6843,7 @@ var LIST_QUERY_COMMAND_NAMES = /* @__PURE__ */ new Set([
 var MUTATION_COMMAND_NAMES = /* @__PURE__ */ new Set([
   "append",
   "close",
+  "close-many",
   "comments",
   "delete",
   "deps",
@@ -6480,6 +6874,14 @@ var OPERATION_COMMAND_NAMES = /* @__PURE__ */ new Set([
   "test-runs-worker",
   "validate"
 ]);
+var MUTATING_OPERATION_COMMAND_NAMES = /* @__PURE__ */ new Set([
+  "claim",
+  "close-task",
+  "pause-task",
+  "release",
+  "start-task",
+  "test"
+]);
 var REGISTER_ALL_CORE_COMMAND_FAMILIES = {
   setup: true,
   listQuery: true,
@@ -6619,12 +7021,37 @@ function shouldRegisterRuntimeSchemaFlags(invocationArgv) {
   }
   return RUNTIME_SCHEMA_FLAG_BOOTSTRAP_COMMANDS.has(commandName);
 }
+function enforceExplicitRetryForFlagTypos(bootstrapInvocation) {
+  const commandName = bootstrapInvocation.commandName;
+  if (!commandName) {
+    return;
+  }
+  const typoEvent = bootstrapInvocation.trace.find((entry) => entry.reason === "flag_typo");
+  if (!typoEvent) {
+    return;
+  }
+  const normalizedTokens = Array.isArray(typoEvent.to) ? typoEvent.to : [String(typoEvent.to ?? "")].filter((entry) => entry.length > 0);
+  const normalizedDisplay = normalizedTokens.length > 0 ? normalizedTokens.join(" ") : "the canonical flag";
+  const mutatingCommand = MUTATION_COMMAND_NAMES.has(commandName) || MUTATING_OPERATION_COMMAND_NAMES.has(commandName);
+  const code = mutatingCommand ? "mutating_flag_typo_requires_retry" : "flag_typo_requires_retry";
+  const commandScope = mutatingCommand ? "mutating option" : "option";
+  throw new PmCliError(`Refusing to auto-correct ${commandScope} ${typoEvent.from} to ${normalizedDisplay}. Retry with the canonical flag so the command is explicit.`, EXIT_CODE.USAGE, {
+    code,
+    examples: [renderPmCommand(bootstrapInvocation.argv)],
+    nextSteps: ["Retry the command with the canonical flag shown in examples."],
+    recovery: {
+      normalized_args: [...bootstrapInvocation.argv],
+      suggested_retry: renderPmCommand(bootstrapInvocation.argv)
+    }
+  });
+}
 async function runPmCli(rawArgv = process.argv.slice(2)) {
   const bootstrapInvocation = normalizeBootstrapInvocation(rawArgv);
   const invocationArgv = bootstrapInvocation.argv;
   const invocationProcessArgv = [process.argv[0], process.argv[1], ...invocationArgv];
   const isBareInvocation = invocationArgv.length === 0;
   try {
+    enforceExplicitRetryForFlagTypos(bootstrapInvocation);
     applyBootstrapPagerPolicy(invocationArgv);
     const registrationSelection = resolveCoreCommandRegistrationSelection(invocationArgv);
     await registerCoreCommandFamilies(program, registrationSelection);
@@ -6683,8 +7110,17 @@ async function runPmCli(rawArgv = process.argv.slice(2)) {
       };
     };
     if (!bootstrapGlobal.noExtensions) {
-      const bootstrapSnapshot = await loadRuntimeExtensionSnapshot(bootstrapPmRoot);
-      setActiveExtensionServices(bootstrapSnapshot?.services ?? { overrides: [] });
+      const bootstrapProbe = buildBootstrapActivationProbe(invocationArgv);
+      const discoverySnapshot = await loadRuntimeExtensionDiscoverySnapshot(bootstrapPmRoot);
+      if (discoverySnapshot && discoveryNeedsActivationForProbe(discoverySnapshot.discovery, bootstrapProbe)) {
+        const bootstrapSnapshot = await loadRuntimeExtensionSnapshot(bootstrapPmRoot);
+        setActiveExtensionServices(bootstrapSnapshot?.services ?? { overrides: [] });
+      } else {
+        if (discoverySnapshot) {
+          emitExtensionSkippedProfile(bootstrapProfileEnabled(invocationArgv), discoverySnapshot, bootstrapProbe);
+        }
+        setActiveExtensionServices({ overrides: [] });
+      }
     }
     const numericExitCode = readThrownExitCode(error);
     if (error instanceof PmCliError || !isCommanderError(error) && typeof numericExitCode === "number" && Number.isFinite(numericExitCode)) {
@@ -6729,7 +7165,9 @@ async function runPmCli(rawArgv = process.argv.slice(2)) {
         command_resolution: commandResolution2,
         resolution_stage: "execute"
       });
-      sentryCaptureCliError(wrapThrownErrorForSentry(error, errorMessage));
+      if (loggedHandledErrorToSentry) {
+        sentryCaptureCliError(wrapThrownErrorForSentry(error, errorMessage));
+      }
       if (jsonErrors) {
         printError(JSON.stringify(formatPmCliErrorForJson(errorMessage, exitCode, enrichedContext), null, 2));
       } else {