@unbrained/pm-cli 2026.6.30 → 2026.7.2

package/dist/cli-bundle/main.js

@@ -5,10 +5,10 @@ import {
   emitTelemetryErrorEvent,
   finishTelemetryCommand,
   startTelemetryCommand
-} from "./chunks/chunk-IDYCAK35.js";
+} from "./chunks/chunk-H4GRLYJS.js";
 import {
   migrateItemFilesToFormat
-} from "./chunks/chunk-OUQ5JEFM.js";
+} from "./chunks/chunk-S62UANU7.js";
 import {
   applyDefaultOutputFormat,
   clearResolvedGlobalOptions,
@@ -18,23 +18,31 @@ import {
   getGlobalOptions,
   invalidateSearchCachesForMutation,
   setResolvedGlobalOptions
-} from "./chunks/chunk-DORJSBGJ.js";
-import {
-  PM_CORE_COMMAND_NAMES,
-  resolveSubcommandFlagContractsForCommand
-} from "./chunks/chunk-6T5ZIWBS.js";
+} from "./chunks/chunk-SYNKD3ZG.js";
 import {
   printError,
   printResult,
   writeStdout
-} from "./chunks/chunk-CHRNYKNI.js";
-import "./chunks/chunk-KYDYQMNW.js";
+} from "./chunks/chunk-5PGBHRY3.js";
+import "./chunks/chunk-7TH5NMVB.js";
+import {
+  EXECUTABLE_COMMAND_ALIASES,
+  applyBootstrapPagerPolicy,
+  normalizeBootstrapInvocation,
+  normalizeExtensionNameForMatch,
+  parseBootstrapCommandName,
+  parseBootstrapGlobalOptions,
+  parseBootstrapHelpRequest,
+  parseBootstrapTypeValue,
+  stripGlobalBootstrapTokens
+} from "./chunks/chunk-BVZZN2LH.js";
 import {
-  normalizeExtensionNameForMatch
-} from "./chunks/chunk-F6VH3LFC.js";
-import "./chunks/chunk-LBH7UYKY.js";
-import "./chunks/chunk-ZFIEEDTJ.js";
-import "./chunks/chunk-MLHX6DN5.js";
+  PM_CORE_COMMAND_NAMES,
+  resolveSubcommandFlagContractsForCommand
+} from "./chunks/chunk-XWGEMNBR.js";
+import "./chunks/chunk-JXAUVO6X.js";
+import "./chunks/chunk-IEEJQCZ4.js";
+import "./chunks/chunk-AIAIXG7I.js";
 import {
   BUILTIN_ITEM_TYPE_VALUES,
   EXIT_CODE,
@@ -82,7 +90,7 @@ import {
   setActiveExtensionServices,
   toNonEmptyStringOrUndefined,
   writeSettings
-} from "./chunks/chunk-SNUK7H5J.js";
+} from "./chunks/chunk-7NSPKJUS.js";
 
 // dist/cli/main.js
 import { Command } from "commander";
@@ -183,7 +191,7 @@ async function maybeRunFirstUseTelemetryPrompt(commandPath, globalOptions) {
 !(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] = "1e5dec43-11a5-5a85-b2ab-e9a7d10fa478");
+    n && (e._sentryDebugIds = e._sentryDebugIds || {}, e._sentryDebugIds[n] = "acfdb01f-4105-58f5-98a1-8c28cefa6aae");
   } catch (e2) {
   }
 })();
@@ -348,6 +356,51 @@ function resolveTracesSampleRate() {
   }
   return parsed;
 }
+function scrubSentryExceptionValues(event) {
+  if (!event.exception?.values) {
+    return;
+  }
+  for (const exception of event.exception.values) {
+    if (exception.value) {
+      exception.value = scrubString(exception.value, "value");
+    }
+    if (exception.stacktrace?.frames) {
+      for (const frame of exception.stacktrace.frames) {
+        scrubStackFrame(frame);
+      }
+    }
+  }
+}
+function scrubSentryBreadcrumbs(event) {
+  if (!event.breadcrumbs) {
+    return;
+  }
+  for (const breadcrumb of event.breadcrumbs) {
+    if (breadcrumb.message) {
+      breadcrumb.message = scrubString(breadcrumb.message);
+    }
+    if (breadcrumb.data && typeof breadcrumb.data === "object") {
+      breadcrumb.data = scrubEventData(breadcrumb.data);
+    }
+  }
+}
+function scrubSentryContexts(event) {
+  if (!event.contexts) {
+    return;
+  }
+  for (const [ctxKey, ctx] of Object.entries(event.contexts)) {
+    if (ctx && typeof ctx === "object") {
+      event.contexts[ctxKey] = scrubEventData(ctx);
+    }
+  }
+}
+function scrubSentryRecordField(event, key) {
+  const target = event;
+  const value = target[key];
+  if (value && typeof value === "object") {
+    target[key] = scrubEventData(value);
+  }
+}
 async function ensureSentryInit() {
   if (_initDone)
     return _sentry;
@@ -392,47 +445,13 @@ async function ensureSentryInit() {
       if (event.transaction) {
         event.transaction = scrubString(event.transaction, "transaction");
       }
-      if (event.exception?.values) {
-        for (const exception of event.exception.values) {
-          if (exception.value) {
-            exception.value = scrubString(exception.value, "value");
-          }
-          if (exception.stacktrace?.frames) {
-            for (const frame of exception.stacktrace.frames) {
-              scrubStackFrame(frame);
-            }
-          }
-        }
-      }
-      if (event.breadcrumbs) {
-        for (const breadcrumb of event.breadcrumbs) {
-          if (breadcrumb.message) {
-            breadcrumb.message = scrubString(breadcrumb.message);
-          }
-          if (breadcrumb.data && typeof breadcrumb.data === "object") {
-            breadcrumb.data = scrubEventData(breadcrumb.data);
-          }
-        }
-      }
-      if (event.extra && typeof event.extra === "object") {
-        event.extra = scrubEventData(event.extra);
-      }
-      if (event.contexts) {
-        for (const [ctxKey, ctx] of Object.entries(event.contexts)) {
-          if (ctx && typeof ctx === "object") {
-            event.contexts[ctxKey] = scrubEventData(ctx);
-          }
-        }
-      }
-      if (event.request && typeof event.request === "object") {
-        event.request = scrubEventData(event.request);
-      }
-      if (event.user && typeof event.user === "object") {
-        event.user = scrubEventData(event.user);
-      }
-      if (event.tags && typeof event.tags === "object") {
-        event.tags = scrubEventData(event.tags);
-      }
+      scrubSentryExceptionValues(event);
+      scrubSentryBreadcrumbs(event);
+      scrubSentryRecordField(event, "extra");
+      scrubSentryContexts(event);
+      scrubSentryRecordField(event, "request");
+      scrubSentryRecordField(event, "user");
+      scrubSentryRecordField(event, "tags");
       return event;
     },
     beforeSendTransaction(event) {
@@ -479,7 +498,7 @@ function getSentry() {
 !(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] = "130c8e28-49f7-57d9-a522-1692a4f725c6");
+    n && (e._sentryDebugIds = e._sentryDebugIds || {}, e._sentryDebugIds[n] = "3ab66a74-037d-56a6-9113-59c1e6d09872");
   } catch (e2) {
   }
 })();
@@ -493,6 +512,33 @@ function setSpanAttribute(span, key, value) {
     attributeTarget.setAttribute(key, value);
   }
 }
+function setSentryTagIfPresent(Sentry, key, value) {
+  if (typeof value === "string" && value.trim().length > 0) {
+    Sentry.setTag(key, value);
+  }
+}
+function setSentryCommandFinishTags(Sentry, normalizedOk, metadata) {
+  Sentry.setTag("pm.ok", normalizedOk);
+  Sentry.setTag("pm.command_ok", normalizedOk);
+  if (typeof metadata?.exit_code === "number") {
+    Sentry.setTag("pm.exit_code", String(metadata.exit_code));
+    Sentry.setTag("pm.command_exit_code", String(metadata.exit_code));
+  }
+  setSentryTagIfPresent(Sentry, "pm.error_code", metadata?.error_code);
+  setSentryTagIfPresent(Sentry, "pm.error_category", metadata?.error_category);
+  setSentryTagIfPresent(Sentry, "pm.command_resolution", metadata?.command_resolution);
+  setSentryTagIfPresent(Sentry, "pm.resolution_stage", metadata?.resolution_stage);
+}
+function setCommandSpanFinishAttributes(span, normalizedOk, normalizedExitCode, metadata) {
+  setSpanAttribute(span, "pm.ok", normalizedOk);
+  setSpanAttribute(span, "pm.command_ok", normalizedOk);
+  setSpanAttribute(span, "pm.exit_code", normalizedExitCode);
+  setSpanAttribute(span, "pm.command_exit_code", normalizedExitCode);
+  setSpanAttribute(span, "pm.error_code", metadata?.error_code);
+  setSpanAttribute(span, "pm.error_category", metadata?.error_category);
+  setSpanAttribute(span, "pm.command_resolution", metadata?.command_resolution);
+  setSpanAttribute(span, "pm.resolution_stage", metadata?.resolution_stage);
+}
 function sentrySetCommandContext(command, args, options, metadata) {
   const Sentry = getSentry();
   if (!Sentry)
@@ -544,33 +590,9 @@ function sentryFinishCommandSpan(ok, error, metadata) {
   const normalizedExitCode = typeof metadata?.exit_code === "number" ? String(metadata.exit_code) : void 0;
   const Sentry = getSentry();
   if (Sentry) {
-    Sentry.setTag("pm.ok", normalizedOk);
-    Sentry.setTag("pm.command_ok", normalizedOk);
-    if (typeof metadata?.exit_code === "number") {
-      Sentry.setTag("pm.exit_code", String(metadata.exit_code));
-      Sentry.setTag("pm.command_exit_code", String(metadata.exit_code));
-    }
-    if (typeof metadata?.error_code === "string" && metadata.error_code.trim().length > 0) {
-      Sentry.setTag("pm.error_code", metadata.error_code);
-    }
-    if (typeof metadata?.error_category === "string" && metadata.error_category.trim().length > 0) {
-      Sentry.setTag("pm.error_category", metadata.error_category);
-    }
-    if (typeof metadata?.command_resolution === "string" && metadata.command_resolution.trim().length > 0) {
-      Sentry.setTag("pm.command_resolution", metadata.command_resolution);
-    }
-    if (typeof metadata?.resolution_stage === "string" && metadata.resolution_stage.trim().length > 0) {
-      Sentry.setTag("pm.resolution_stage", metadata.resolution_stage);
-    }
+    setSentryCommandFinishTags(Sentry, normalizedOk, metadata);
   }
-  setSpanAttribute(activeCommandSpan, "pm.ok", normalizedOk);
-  setSpanAttribute(activeCommandSpan, "pm.command_ok", normalizedOk);
-  setSpanAttribute(activeCommandSpan, "pm.exit_code", normalizedExitCode);
-  setSpanAttribute(activeCommandSpan, "pm.command_exit_code", normalizedExitCode);
-  setSpanAttribute(activeCommandSpan, "pm.error_code", metadata?.error_code);
-  setSpanAttribute(activeCommandSpan, "pm.error_category", metadata?.error_category);
-  setSpanAttribute(activeCommandSpan, "pm.command_resolution", metadata?.command_resolution);
-  setSpanAttribute(activeCommandSpan, "pm.resolution_stage", metadata?.resolution_stage);
+  setCommandSpanFinishAttributes(activeCommandSpan, normalizedOk, normalizedExitCode, metadata);
   activeCommandSpan.setStatus(ok ? { code: 1 } : { code: 2, message: error ?? "command_failed" });
   activeCommandSpan.end();
   activeCommandSpan = void 0;
@@ -663,7 +685,7 @@ async function sentryFlush(timeoutMs = 3e3) {
 !(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] = "006c671c-d2fc-5908-8431-08bc7e418184");
+    n && (e._sentryDebugIds = e._sentryDebugIds || {}, e._sentryDebugIds[n] = "23023585-f2dc-5ec7-a046-cc39355aaf59");
   } catch (e2) {
   }
 })();
@@ -841,29 +863,26 @@ function validateLooseCommandOptionsWithFlagDefinitions(options, definitions, co
     }
   }
 }
-function coerceLooseOptionValue(value, kind) {
-  if (Array.isArray(value)) {
-    return value.map((entry) => coerceLooseOptionValue(entry, kind));
+function coerceLooseStringOptionValue(value) {
+  if (typeof value === "string") {
+    return value;
   }
-  if (kind === "string") {
-    if (typeof value === "string") {
-      return value;
-    }
-    if (value === null || value === void 0) {
-      return value;
-    }
-    return String(value);
+  if (value === null || value === void 0) {
+    return value;
   }
-  if (kind === "number") {
-    if (typeof value === "number") {
-      return Number.isFinite(value) ? value : value;
-    }
-    if (typeof value === "string" && value.trim().length > 0) {
-      const parsed = Number(value);
-      return Number.isFinite(parsed) ? parsed : value;
-    }
+  return String(value);
+}
+function coerceLooseNumberOptionValue(value) {
+  if (typeof value === "number") {
     return value;
   }
+  if (typeof value === "string" && value.trim().length > 0) {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : value;
+  }
+  return value;
+}
+function coerceLooseBooleanOptionValue(value) {
   if (typeof value === "boolean") {
     return value;
   }
@@ -878,6 +897,17 @@ function coerceLooseOptionValue(value, kind) {
   }
   return value;
 }
+var LOOSE_OPTION_VALUE_COERCERS = {
+  string: coerceLooseStringOptionValue,
+  number: coerceLooseNumberOptionValue,
+  boolean: coerceLooseBooleanOptionValue
+};
+function coerceLooseOptionValue(value, kind) {
+  if (Array.isArray(value)) {
+    return value.map((entry) => coerceLooseOptionValue(entry, kind));
+  }
+  return LOOSE_OPTION_VALUE_COERCERS[kind](value);
+}
 function splitCommaListValue(value, kind) {
   const entries = flattenFlagListValue(value);
   return kind ? entries.map((entry) => coerceLooseOptionValue(entry, kind)) : entries;
@@ -1893,7 +1923,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] = "4fdf7d5d-e4c8-5f0c-a969-2ed905b3a5dc");
+    n && (e._sentryDebugIds = e._sentryDebugIds || {}, e._sentryDebugIds[n] = "594fd898-5ce1-5e77-8731-5bcd90c16f9a");
   } catch (e2) {
   }
 })();
@@ -1943,67 +1973,66 @@ function renderList(title, entries) {
   }
   return [title, ...entries.map((entry) => `  - ${entry}`)];
 }
+function normalizeStringArray(values) {
+  if (!Array.isArray(values)) {
+    return void 0;
+  }
+  const normalized = values.filter((entry) => typeof entry === "string").map((entry) => entry.trim()).filter((entry) => entry.length > 0);
+  return normalized.length > 0 ? normalized : void 0;
+}
+function normalizeRecoveryCandidates(candidates) {
+  if (!Array.isArray(candidates)) {
+    return void 0;
+  }
+  const normalized = candidates.map((entry) => ({
+    source: typeof entry?.source === "string" ? entry.source.trim() : "",
+    command: typeof entry?.command === "string" ? entry.command.trim() : "",
+    reason: typeof entry?.reason === "string" ? entry.reason.trim() : ""
+  })).filter((entry) => entry.source.length > 0 && entry.command.length > 0 && entry.reason.length > 0);
+  return normalized.length > 0 ? normalized : void 0;
+}
+function assignRecoveryString(normalized, key, value) {
+  if (typeof value === "string" && value.trim().length > 0) {
+    normalized[key] = value.trim();
+  }
+}
+function assignRecoveryStringArray(normalized, key, value) {
+  const values = normalizeStringArray(value);
+  if (values) {
+    normalized[key] = values;
+  }
+}
 function normalizeRecoveryPayload(payload) {
   if (!payload || typeof payload !== "object") {
     return void 0;
   }
-  const normalizeStringArray = (values) => {
-    if (!Array.isArray(values)) {
-      return void 0;
-    }
-    const normalized2 = values.filter((entry) => typeof entry === "string").map((entry) => entry.trim()).filter((entry) => entry.length > 0);
-    return normalized2.length > 0 ? normalized2 : void 0;
-  };
   const normalized = {};
   if (payload.recovery_mode === "compact") {
     normalized.recovery_mode = "compact";
   }
-  if (typeof payload.attempted_command === "string" && payload.attempted_command.trim().length > 0) {
-    normalized.attempted_command = payload.attempted_command.trim();
-  }
-  if (Array.isArray(payload.normalized_args)) {
-    const args = payload.normalized_args.map((entry) => entry.trim()).filter((entry) => entry.length > 0);
-    if (args.length > 0) {
-      normalized.normalized_args = args;
-    }
-  }
-  if (Array.isArray(payload.provided_fields)) {
-    const fields = payload.provided_fields.map((entry) => entry.trim()).filter((entry) => entry.length > 0);
-    if (fields.length > 0) {
-      normalized.provided_fields = fields;
-    }
-  }
-  if (Array.isArray(payload.missing)) {
-    const missing = payload.missing.map((entry) => entry.trim()).filter((entry) => entry.length > 0);
-    if (missing.length > 0) {
-      normalized.missing = missing;
-    }
-  }
-  const missingRequiredFields = normalizeStringArray(payload.missing_required_fields);
-  if (missingRequiredFields) {
-    normalized.missing_required_fields = missingRequiredFields;
-  }
-  const suggestedFlags = normalizeStringArray(payload.suggested_flags);
-  if (suggestedFlags) {
-    normalized.suggested_flags = suggestedFlags;
-  }
-  if (typeof payload.suggested_retry === "string" && payload.suggested_retry.trim().length > 0) {
-    normalized.suggested_retry = payload.suggested_retry.trim();
-  }
-  if (Array.isArray(payload.fallback_candidates)) {
-    const fallbackCandidates = payload.fallback_candidates.map((entry) => ({
-      source: typeof entry?.source === "string" ? entry.source.trim() : "",
-      command: typeof entry?.command === "string" ? entry.command.trim() : "",
-      reason: typeof entry?.reason === "string" ? entry.reason.trim() : ""
-    })).filter((entry) => entry.source.length > 0 && entry.command.length > 0 && entry.reason.length > 0);
-    if (fallbackCandidates.length > 0) {
-      normalized.fallback_candidates = fallbackCandidates;
-    }
+  assignRecoveryString(normalized, "attempted_command", payload.attempted_command);
+  assignRecoveryStringArray(normalized, "normalized_args", payload.normalized_args);
+  assignRecoveryStringArray(normalized, "provided_fields", payload.provided_fields);
+  assignRecoveryStringArray(normalized, "missing", payload.missing);
+  assignRecoveryStringArray(normalized, "missing_required_fields", payload.missing_required_fields);
+  assignRecoveryStringArray(normalized, "suggested_flags", payload.suggested_flags);
+  assignRecoveryString(normalized, "suggested_retry", payload.suggested_retry);
+  const fallbackCandidates = normalizeRecoveryCandidates(payload.fallback_candidates);
+  if (fallbackCandidates) {
+    normalized.fallback_candidates = fallbackCandidates;
+  }
+  assignRecoveryString(normalized, "next_best_command", payload.next_best_command);
+  return Object.keys(normalized).length > 0 ? normalized : void 0;
+}
+function appendRecoveryTextLine(lines, label, value) {
+  if (value) {
+    lines.push(`  ${label}: ${value}`);
   }
-  if (typeof payload.next_best_command === "string" && payload.next_best_command.trim().length > 0) {
-    normalized.next_best_command = payload.next_best_command.trim();
+}
+function appendRecoveryListLine(lines, label, values, separator) {
+  if (values && values.length > 0) {
+    lines.push(`  ${label}: ${values.join(separator)}`);
   }
-  return Object.keys(normalized).length > 0 ? normalized : void 0;
 }
 function renderRecoveryBundle(recovery) {
   const normalized = normalizeRecoveryPayload(recovery);
@@ -2011,30 +2040,14 @@ function renderRecoveryBundle(recovery) {
     return [];
   }
   const lines = ["Recovery bundle:"];
-  if (normalized.attempted_command) {
-    lines.push(`  attempted_command: ${normalized.attempted_command}`);
-  }
-  if (normalized.normalized_args && normalized.normalized_args.length > 0) {
-    lines.push(`  normalized_args: ${normalized.normalized_args.join(" ")}`);
-  }
-  if (normalized.provided_fields && normalized.provided_fields.length > 0) {
-    lines.push(`  provided_fields: ${normalized.provided_fields.join(", ")}`);
-  }
-  if (normalized.missing && normalized.missing.length > 0) {
-    lines.push(`  missing: ${normalized.missing.join(", ")}`);
-  }
-  if (normalized.missing_required_fields && normalized.missing_required_fields.length > 0) {
-    lines.push(`  missing_required_fields: ${normalized.missing_required_fields.join(", ")}`);
-  }
-  if (normalized.suggested_flags && normalized.suggested_flags.length > 0) {
-    lines.push(`  suggested_flags: ${normalized.suggested_flags.join(", ")}`);
-  }
-  if (normalized.suggested_retry) {
-    lines.push(`  suggested_retry: ${normalized.suggested_retry}`);
-  }
-  if (normalized.next_best_command) {
-    lines.push(`  next_best_command: ${normalized.next_best_command}`);
-  }
+  appendRecoveryTextLine(lines, "attempted_command", normalized.attempted_command);
+  appendRecoveryListLine(lines, "normalized_args", normalized.normalized_args, " ");
+  appendRecoveryListLine(lines, "provided_fields", normalized.provided_fields, ", ");
+  appendRecoveryListLine(lines, "missing", normalized.missing, ", ");
+  appendRecoveryListLine(lines, "missing_required_fields", normalized.missing_required_fields, ", ");
+  appendRecoveryListLine(lines, "suggested_flags", normalized.suggested_flags, ", ");
+  appendRecoveryTextLine(lines, "suggested_retry", normalized.suggested_retry);
+  appendRecoveryTextLine(lines, "next_best_command", normalized.next_best_command);
   if (normalized.fallback_candidates && normalized.fallback_candidates.length > 0) {
     lines.push("  fallback_candidates:");
     for (const candidate of normalized.fallback_candidates) {
@@ -2209,133 +2222,158 @@ function applyPmCliErrorContext(guidance, rawMessage, context) {
     recovery
   };
 }
-function buildPmCliErrorGuidance(rawMessage, context) {
-  const message = normalizeMessage(rawMessage);
+function buildTrackerNotInitializedGuidance(rawMessage, message, context) {
   const trackerNotInitialized = message.match(/^Tracker is not initialized at (.+)\. Run pm init first\.$/);
-  if (trackerNotInitialized) {
-    return applyPmCliErrorContext(makeGuidanceMessage({
-      code: "tracker_not_initialized",
-      title: "Tracker is not initialized",
-      happened: `pm data path does not contain initialized tracker metadata (${trackerNotInitialized[1]}).`,
-      required: "Initialize tracker storage before running this command.",
-      why: "Most commands require settings and tracker directories created by pm init.",
-      examples: ["pm init", "pm init acme"],
-      nextSteps: ['Run "pm init", then rerun your original command.']
-    }), rawMessage, context);
+  if (!trackerNotInitialized) {
+    return null;
   }
+  return applyPmCliErrorContext(makeGuidanceMessage({
+    code: "tracker_not_initialized",
+    title: "Tracker is not initialized",
+    happened: `pm data path does not contain initialized tracker metadata (${trackerNotInitialized[1]}).`,
+    required: "Initialize tracker storage before running this command.",
+    why: "Most commands require settings and tracker directories created by pm init.",
+    examples: ["pm init", "pm init acme"],
+    nextSteps: ['Run "pm init", then rerun your original command.']
+  }), rawMessage, context);
+}
+function buildItemNotFoundGuidance(rawMessage, message, context) {
   const itemNotFound = message.match(/^Item ([^ ]+) not found$/);
-  if (itemNotFound) {
-    const badId = itemNotFound[1];
-    const isPlaceholder = /^(undefined|null|<.*>|\[.*\]|{.*}|)$/.test(badId);
-    const happened = isPlaceholder ? `The item ID "${badId}" looks like a placeholder or unresolved variable. Ensure the ID argument is resolved before calling pm.` : `No item with id "${badId}" exists in the active tracker scope.`;
-    const nextSteps = isPlaceholder ? [
-      "Check that the variable holding the item ID is defined before passing it to pm.",
-      'Use "pm list-open --limit 20" to find valid IDs.'
-    ] : ["Confirm the active --path/PM_PATH scope, then retry with a valid id."];
-    return applyPmCliErrorContext(makeGuidanceMessage({
-      code: "item_not_found",
-      title: "Item ID not found",
-      happened,
-      required: "Use an existing item ID from current tracker data.",
-      why: "Mutation and read commands operate only on known IDs.",
-      examples: ["pm list-open --limit 20", 'pm search "<keyword>" --limit 10'],
-      nextSteps
-    }), rawMessage, context);
-  }
-  if (message.includes("is assigned to") && message.includes("Use --force to override")) {
-    return applyPmCliErrorContext(makeGuidanceMessage({
-      code: "ownership_conflict",
-      title: "Ownership conflict",
-      happened: message,
-      required: "Run as assigned owner, use audit flags for safe non-owner updates, or use --force only for approved override scenarios.",
-      why: "Ownership checks prevent accidental concurrent mutations on claimed items and protect against conflicting writes.",
-      examples: [
-        'pm update pm-a1b2 --allow-audit-update --description "..." --author "audit-agent"',
-        'pm update pm-a1b2 --allow-audit-dep-update --dep "..." --author "audit-agent"',
-        'pm comments pm-a1b2 "..." --allow-audit-comment --author "audit-agent"',
-        'pm claim pm-a1b2 --author "codex-agent"',
-        'pm release pm-a1b2 --allow-audit-release --author "reviewer"',
-        "pm update pm-a1b2 --status in_progress --force"
-      ],
-      nextSteps: [
-        "Use --allow-audit-update for metadata-only non-owner updates (excludes lifecycle/ownership fields).",
-        "Use --allow-audit-dep-update for dependency-only non-owner additions.",
-        "Use --allow-audit-comment on comments/notes/learnings for append-only audit entries.",
-        "Use --force for PM audits and systematic metadata updates performed by leads/maintainers.",
-        "Use --force when correcting known stale metadata after coordinating ownership changes.",
-        'For non-terminal reassignment, prefer "pm claim <ID> --author <you>" before running other mutations.',
-        'For assignee handoff release workflows, prefer "pm release <ID> --allow-audit-release --author <you>" before using --force.'
-      ]
-    }), rawMessage, context);
+  if (!itemNotFound) {
+    return null;
   }
-  if (message.includes("is locked")) {
-    return applyPmCliErrorContext(makeGuidanceMessage({
-      code: "lock_conflict",
-      title: "Lock conflict",
-      happened: message,
-      required: "Wait for lock release, or use --force where supported if lock is stale and safe to override.",
-      why: "Locking protects item files from concurrent write races.",
-      examples: ['pm update pm-a1b2 --status in_progress --force --author "codex-agent"']
-    }), rawMessage, context);
+  const badId = itemNotFound[1];
+  const isPlaceholder = /^(undefined|null|<.*>|\[.*\]|{.*}|)$/.test(badId);
+  const happened = isPlaceholder ? `The item ID "${badId}" looks like a placeholder or unresolved variable. Ensure the ID argument is resolved before calling pm.` : `No item with id "${badId}" exists in the active tracker scope.`;
+  const nextSteps = isPlaceholder ? [
+    "Check that the variable holding the item ID is defined before passing it to pm.",
+    'Use "pm list-open --limit 20" to find valid IDs.'
+  ] : ["Confirm the active --path/PM_PATH scope, then retry with a valid id."];
+  return applyPmCliErrorContext(makeGuidanceMessage({
+    code: "item_not_found",
+    title: "Item ID not found",
+    happened,
+    required: "Use an existing item ID from current tracker data.",
+    why: "Mutation and read commands operate only on known IDs.",
+    examples: ["pm list-open --limit 20", 'pm search "<keyword>" --limit 10'],
+    nextSteps
+  }), rawMessage, context);
+}
+function buildOwnershipConflictGuidance(rawMessage, message, context) {
+  if (!message.includes("is assigned to") || !message.includes("Use --force to override")) {
+    return null;
+  }
+  return applyPmCliErrorContext(makeGuidanceMessage({
+    code: "ownership_conflict",
+    title: "Ownership conflict",
+    happened: message,
+    required: "Run as assigned owner, use audit flags for safe non-owner updates, or use --force only for approved override scenarios.",
+    why: "Ownership checks prevent accidental concurrent mutations on claimed items and protect against conflicting writes.",
+    examples: [
+      'pm update pm-a1b2 --allow-audit-update --description "..." --author "audit-agent"',
+      'pm update pm-a1b2 --allow-audit-dep-update --dep "..." --author "audit-agent"',
+      'pm comments pm-a1b2 "..." --allow-audit-comment --author "audit-agent"',
+      'pm claim pm-a1b2 --author "codex-agent"',
+      'pm release pm-a1b2 --allow-audit-release --author "reviewer"',
+      "pm update pm-a1b2 --status in_progress --force"
+    ],
+    nextSteps: [
+      "Use --allow-audit-update for metadata-only non-owner updates (excludes lifecycle/ownership fields).",
+      "Use --allow-audit-dep-update for dependency-only non-owner additions.",
+      "Use --allow-audit-comment on comments/notes/learnings for append-only audit entries.",
+      "Use --force for PM audits and systematic metadata updates performed by leads/maintainers.",
+      "Use --force when correcting known stale metadata after coordinating ownership changes.",
+      'For non-terminal reassignment, prefer "pm claim <ID> --author <you>" before running other mutations.',
+      'For assignee handoff release workflows, prefer "pm release <ID> --allow-audit-release --author <you>" before using --force.'
+    ]
+  }), rawMessage, context);
+}
+function buildLockConflictGuidance(rawMessage, message, context) {
+  if (!message.includes("is locked")) {
+    return null;
   }
+  return applyPmCliErrorContext(makeGuidanceMessage({
+    code: "lock_conflict",
+    title: "Lock conflict",
+    happened: message,
+    required: "Wait for lock release, or use --force where supported if lock is stale and safe to override.",
+    why: "Locking protects item files from concurrent write races.",
+    examples: ['pm update pm-a1b2 --status in_progress --force --author "codex-agent"']
+  }), rawMessage, context);
+}
+function buildPmMissingRequiredOptionGuidance(rawMessage, message, context) {
   const missingRequiredOption = message.match(/^Missing required option /);
   const missingRequiredOptions = message.match(/^Missing required options /);
-  if (missingRequiredOption || missingRequiredOptions) {
-    const plural = Boolean(missingRequiredOptions);
-    const missingOptionFlag = !plural ? message.replace(/^Missing required option\s+/, "").trim() : null;
-    const missingOptionLabel = missingOptionFlag ?? "";
-    const missingOptionRequired = missingOptionFlag ? `Pass ${missingOptionFlag} with a valid value before running the command.` : "Provide the required option for this command invocation.";
-    return applyPmCliErrorContext(makeGuidanceMessage({
-      code: "missing_required_option",
-      title: plural ? "Missing required options" : `Missing required option ${missingOptionLabel}`,
-      happened: message,
-      required: plural ? "Provide every required option for this command invocation." : missingOptionRequired,
-      why: "Required options define command intent and enforce deterministic write contracts.",
-      examples: [
-        'pm create --title "Task title" --description "Task details" --type Task --create-mode progressive',
-        'pm create --title "Task title" --description "Task details" --type Task --status open --priority 1 --message "Create task" --dep "id=pm-epic01,kind=parent,author=codex-agent,created_at=now" --comment "author=codex-agent,created_at=now,text=Why this task exists." --note "author=codex-agent,created_at=now,text=Initial implementation note." --learning "author=codex-agent,created_at=now,text=Durable lesson placeholder." --file "path=src/example.ts,scope=project" --test "command=node scripts/run-tests.mjs test,scope=project,timeout_seconds=240" --doc "path=README.md,scope=project"'
-      ],
-      nextSteps: [
-        'Run "pm <command> --help" to view required and recommended flags.',
-        "For staged triage without placeholder linkage values, use --create-mode progressive."
-      ]
-    }), rawMessage, context);
-  }
-  if (message.startsWith("No update flags provided")) {
-    return applyPmCliErrorContext(makeGuidanceMessage({
-      code: "no_update_fields",
-      title: "No update fields supplied",
-      happened: "The update command was called without any field-changing flags.",
-      required: "Provide at least one field-changing flag such as --status, --priority, --title, --tags, --description, or --body. Use --message only to label a real mutation.",
-      why: "pm update mutates existing item fields; no-op invocations are rejected to avoid ambiguous history.",
-      examples: [
-        'pm update pm-a1b2 --status in_progress --message "Start implementation"',
-        'pm update pm-a1b2 --description "Clarified implementation scope" --message "Clarify task intent"',
-        'pm append pm-a1b2 --body "Detailed progress notes" --message "Append progress notes"'
-      ],
-      nextSteps: [
-        "Choose the item field you intend to change, then pair that change with --message for history context.",
-        "Use pm comments, pm notes, pm learnings, or pm append when you only need to add narrative context."
-      ]
-    }), rawMessage, context);
-  }
-  if (message.startsWith("Invalid ") || message.includes(" must be ") || message.includes(" requires ")) {
-    const recovery = normalizeRecoveryPayload(context?.recovery);
-    const commandName = inferCommandNameFromRecovery(recovery);
-    const helpExample = commandName ? `pm ${commandName} --help` : "pm <command> --help";
-    const allowedValues = inferAllowedValuesFromMessage(message);
-    const retryExample = buildAllowedValueRetryCommand(recovery, allowedValues);
-    const examples = retryExample ? [retryExample, helpExample] : [helpExample, "pm contracts --command <command> --flags-only --json"];
-    const nextSteps = allowedValues.length > 0 ? [`Allowed values: ${allowedValues.join("|")}`, `Run "${helpExample}" to confirm command-specific constraints.`] : ["Check allowed values in command help, then rerun with corrected input."];
-    return applyPmCliErrorContext(makeGuidanceMessage({
-      code: "invalid_argument_value",
-      title: "Invalid argument value",
-      happened: message,
-      required: "Use values that match documented command constraints.",
-      why: "Validation protects data consistency and deterministic behavior across commands.",
-      examples,
-      nextSteps
-    }), rawMessage, context);
+  if (!missingRequiredOption && !missingRequiredOptions) {
+    return null;
+  }
+  const plural = Boolean(missingRequiredOptions);
+  const missingOptionFlag = !plural ? message.replace(/^Missing required option\s+/, "").trim() : null;
+  const missingOptionLabel = missingOptionFlag ?? "";
+  const missingOptionRequired = missingOptionFlag ? `Pass ${missingOptionFlag} with a valid value before running the command.` : "Provide the required option for this command invocation.";
+  return applyPmCliErrorContext(makeGuidanceMessage({
+    code: "missing_required_option",
+    title: plural ? "Missing required options" : `Missing required option ${missingOptionLabel}`,
+    happened: message,
+    required: plural ? "Provide every required option for this command invocation." : missingOptionRequired,
+    why: "Required options define command intent and enforce deterministic write contracts.",
+    examples: [
+      'pm create --title "Task title" --description "Task details" --type Task --create-mode progressive',
+      'pm create --title "Task title" --description "Task details" --type Task --status open --priority 1 --message "Create task" --dep "id=pm-epic01,kind=parent,author=codex-agent,created_at=now" --comment "author=codex-agent,created_at=now,text=Why this task exists." --note "author=codex-agent,created_at=now,text=Initial implementation note." --learning "author=codex-agent,created_at=now,text=Durable lesson placeholder." --file "path=src/example.ts,scope=project" --test "command=node scripts/run-tests.mjs test,scope=project,timeout_seconds=240" --doc "path=README.md,scope=project"'
+    ],
+    nextSteps: [
+      'Run "pm <command> --help" to view required and recommended flags.',
+      "For staged triage without placeholder linkage values, use --create-mode progressive."
+    ]
+  }), rawMessage, context);
+}
+function buildNoUpdateFieldsGuidance(rawMessage, message, context) {
+  if (!message.startsWith("No update flags provided")) {
+    return null;
+  }
+  return applyPmCliErrorContext(makeGuidanceMessage({
+    code: "no_update_fields",
+    title: "No update fields supplied",
+    happened: "The update command was called without any field-changing flags.",
+    required: "Provide at least one field-changing flag such as --status, --priority, --title, --tags, --description, or --body. Use --message only to label a real mutation.",
+    why: "pm update mutates existing item fields; no-op invocations are rejected to avoid ambiguous history.",
+    examples: [
+      'pm update pm-a1b2 --status in_progress --message "Start implementation"',
+      'pm update pm-a1b2 --description "Clarified implementation scope" --message "Clarify task intent"',
+      'pm append pm-a1b2 --body "Detailed progress notes" --message "Append progress notes"'
+    ],
+    nextSteps: [
+      "Choose the item field you intend to change, then pair that change with --message for history context.",
+      "Use pm comments, pm notes, pm learnings, or pm append when you only need to add narrative context."
+    ]
+  }), rawMessage, context);
+}
+function buildInvalidArgumentGuidance(rawMessage, message, context) {
+  if (!message.startsWith("Invalid ") && !message.includes(" must be ") && !message.includes(" requires ")) {
+    return null;
+  }
+  const recovery = normalizeRecoveryPayload(context?.recovery);
+  const commandName = inferCommandNameFromRecovery(recovery);
+  const helpExample = commandName ? `pm ${commandName} --help` : "pm <command> --help";
+  const allowedValues = inferAllowedValuesFromMessage(message);
+  const retryExample = buildAllowedValueRetryCommand(recovery, allowedValues);
+  const examples = retryExample ? [retryExample, helpExample] : [helpExample, "pm contracts --command <command> --flags-only --json"];
+  const nextSteps = allowedValues.length > 0 ? [`Allowed values: ${allowedValues.join("|")}`, `Run "${helpExample}" to confirm command-specific constraints.`] : ["Check allowed values in command help, then rerun with corrected input."];
+  return applyPmCliErrorContext(makeGuidanceMessage({
+    code: "invalid_argument_value",
+    title: "Invalid argument value",
+    happened: message,
+    required: "Use values that match documented command constraints.",
+    why: "Validation protects data consistency and deterministic behavior across commands.",
+    examples,
+    nextSteps
+  }), rawMessage, context);
+}
+function buildPmCliErrorGuidance(rawMessage, context) {
+  const message = normalizeMessage(rawMessage);
+  const guidance = buildTrackerNotInitializedGuidance(rawMessage, message, context) ?? buildItemNotFoundGuidance(rawMessage, message, context) ?? buildOwnershipConflictGuidance(rawMessage, message, context) ?? buildLockConflictGuidance(rawMessage, message, context) ?? buildPmMissingRequiredOptionGuidance(rawMessage, message, context) ?? buildNoUpdateFieldsGuidance(rawMessage, message, context) ?? buildInvalidArgumentGuidance(rawMessage, message, context);
+  if (guidance) {
+    return guidance;
   }
   return applyPmCliErrorContext(makeGuidanceMessage({
     code: "command_failed",
@@ -2455,147 +2493,173 @@ function buildLinkedTestQuotedRetryCommand(argv) {
   }
   return void 0;
 }
-function buildCommanderErrorGuidance(rawMessage, commandName, allowedTypes, context) {
-  const message = normalizeMessage(rawMessage);
+function buildMissingRequiredOptionGuidance(message, commandName, allowedTypes, context) {
   const requiredOption = message.match(/required option '([^']+)' not specified/);
-  if (requiredOption) {
-    const optionFlag = normalizeRequiredOptionLabel(requiredOption[1]);
-    const isType = optionFlag.startsWith("--type");
-    const retryCommand = context?.suggestedRetryCommand;
-    const providedFlags = normalizeOptionFlags(context?.providedOptionFlags);
-    const missing = [optionFlag];
-    const examples = commandExampleForRequiredOption(commandName, optionFlag, allowedTypes);
-    const examplesWithRetry = retryCommand ? appendIfMissing(examples, retryCommand) : examples;
-    const nextStepsBase = isType ? [`Allowed type values: ${allowedTypes}`, `Run "pm ${commandName ?? "create"} --help --type <value>" for type-aware policy details.`] : [`Run "pm ${commandName ?? "<command>"} --help" for required option guidance.`];
-    const nextStepsWithRetry = retryCommand ? appendIfMissing(nextStepsBase, `Replay with preserved arguments: ${retryCommand}`) : nextStepsBase;
-    const nextSteps = providedFlags && providedFlags.length > 0 ? appendIfMissing(nextStepsWithRetry, `Already provided options: ${providedFlags.join(", ")}`) : nextStepsWithRetry;
-    return makeGuidanceMessage({
-      code: "missing_required_option",
-      title: `Missing required option ${optionFlag}`,
-      happened: `Commander rejected the command because ${optionFlag} was not provided.`,
-      required: `Pass ${optionFlag} with a valid value before running the command.`,
-      why: isType ? "--type selects item contract and policy routing, including required/disabled option rules." : "Required flags define mandatory command intent and prevent ambiguous execution.",
-      examples: examplesWithRetry,
-      nextSteps,
-      recovery: buildCommanderRecoveryPayload(context, { missing })
-    });
+  if (!requiredOption) {
+    return null;
   }
+  const optionFlag = normalizeRequiredOptionLabel(requiredOption[1]);
+  const isType = optionFlag.startsWith("--type");
+  const retryCommand = context?.suggestedRetryCommand;
+  const providedFlags = normalizeOptionFlags(context?.providedOptionFlags);
+  const missing = [optionFlag];
+  const examples = commandExampleForRequiredOption(commandName, optionFlag, allowedTypes);
+  const examplesWithRetry = retryCommand ? appendIfMissing(examples, retryCommand) : examples;
+  const nextStepsBase = isType ? [`Allowed type values: ${allowedTypes}`, `Run "pm ${commandName ?? "create"} --help --type <value>" for type-aware policy details.`] : [`Run "pm ${commandName ?? "<command>"} --help" for required option guidance.`];
+  const nextStepsWithRetry = retryCommand ? appendIfMissing(nextStepsBase, `Replay with preserved arguments: ${retryCommand}`) : nextStepsBase;
+  const nextSteps = providedFlags && providedFlags.length > 0 ? appendIfMissing(nextStepsWithRetry, `Already provided options: ${providedFlags.join(", ")}`) : nextStepsWithRetry;
+  return makeGuidanceMessage({
+    code: "missing_required_option",
+    title: `Missing required option ${optionFlag}`,
+    happened: `Commander rejected the command because ${optionFlag} was not provided.`,
+    required: `Pass ${optionFlag} with a valid value before running the command.`,
+    why: isType ? "--type selects item contract and policy routing, including required/disabled option rules." : "Required flags define mandatory command intent and prevent ambiguous execution.",
+    examples: examplesWithRetry,
+    nextSteps,
+    recovery: buildCommanderRecoveryPayload(context, { missing })
+  });
+}
+function buildMissingRequiredArgumentGuidance(message, commandName, context) {
   const missingArgument = message.match(/missing required argument '([^']+)'/);
-  if (missingArgument) {
-    const argumentName = missingArgument[1];
-    return makeGuidanceMessage({
-      code: "missing_required_argument",
-      title: `Missing required argument ${argumentName}`,
-      happened: `Command invocation omitted positional argument ${argumentName}.`,
-      required: `Provide ${argumentName} in the expected command position.`,
-      why: "Positional arguments identify the target entity or action context for the command.",
-      examples: [`pm ${commandName ?? "<command>"} --help`],
-      recovery: buildCommanderRecoveryPayload(context, { missing: [argumentName] })
-    });
+  if (!missingArgument) {
+    return null;
   }
+  const argumentName = missingArgument[1];
+  return makeGuidanceMessage({
+    code: "missing_required_argument",
+    title: `Missing required argument ${argumentName}`,
+    happened: `Command invocation omitted positional argument ${argumentName}.`,
+    required: `Provide ${argumentName} in the expected command position.`,
+    why: "Positional arguments identify the target entity or action context for the command.",
+    examples: [`pm ${commandName ?? "<command>"} --help`],
+    recovery: buildCommanderRecoveryPayload(context, { missing: [argumentName] })
+  });
+}
+function buildUnsupportedUpdateOptionGuidance(optionName, context, suggestions) {
+  return makeGuidanceMessage({
+    code: "unsupported_update_option",
+    title: `Unsupported option ${optionName} for update`,
+    happened: `pm update does not accept ${optionName} for linked artifact mutations.`,
+    required: "Use dedicated linked-artifact commands instead of pm update for files/docs changes.",
+    why: "pm update manages scalar item metadata, while linked files/docs are managed by pm files and pm docs.",
+    examples: [
+      'pm files pm-a1b2 --add "path=src/cli/main.ts,scope=project,note=implementation surface"',
+      'pm docs pm-a1b2 --add "path=README.md,scope=project,note=user-facing contract"'
+    ],
+    nextSteps: ['Run "pm files --help" and "pm docs --help" for add/remove payload formats.'],
+    recovery: buildCommanderRecoveryPayload(context, {
+      suggested_flags: suggestions
+    })
+  });
+}
+function buildUnknownOptionGuidance(message, commandName, context) {
   const unknownOption = message.match(/unknown option '([^']+)'/);
-  if (unknownOption) {
-    const optionName = unknownOption[1];
-    const suggestions = normalizeOptionFlags(context?.unknownOptionSuggestions);
-    const retryCommand = context?.suggestedRetryCommand;
-    if (commandName === "update" && (optionName === "--file" || optionName === "--doc")) {
-      return makeGuidanceMessage({
-        code: "unsupported_update_option",
-        title: `Unsupported option ${optionName} for update`,
-        happened: `pm update does not accept ${optionName} for linked artifact mutations.`,
-        required: "Use dedicated linked-artifact commands instead of pm update for files/docs changes.",
-        why: "pm update manages scalar item metadata, while linked files/docs are managed by pm files and pm docs.",
-        examples: [
-          'pm files pm-a1b2 --add "path=src/cli/main.ts,scope=project,note=implementation surface"',
-          'pm docs pm-a1b2 --add "path=README.md,scope=project,note=user-facing contract"'
-        ],
-        nextSteps: ['Run "pm files --help" and "pm docs --help" for add/remove payload formats.'],
-        recovery: buildCommanderRecoveryPayload(context, {
-          missing: suggestions
-        })
-      });
-    }
-    const otherCommands = normalizeContextList(context?.unknownOptionOtherCommands);
-    const nextSteps = [
-      "Run command help to confirm the exact option contracts for this command path.",
-      ...suggestions && suggestions.length > 0 ? [`Nearest supported options: ${suggestions.join(", ")}`] : [],
-      ...otherCommands && otherCommands.length > 0 ? [`${optionName} is a valid option on: ${otherCommands.join(", ")}. If you meant one of those, run that command instead.`] : [],
-      ...retryCommand ? [`Replay with suggested correction: ${retryCommand}`] : []
-    ];
-    const examples = [
-      ...retryCommand ? [retryCommand] : [],
-      `pm ${commandName ?? "<command>"} --help`
-    ];
-    return makeGuidanceMessage({
-      code: "unknown_option",
-      title: `Unknown option ${optionName}`,
-      happened: `Commander does not recognize option ${optionName} for this command path.`,
-      required: "Use supported options only, or move option to the correct subcommand.",
-      why: "Option contracts are command-specific and intentionally validated.",
-      examples,
-      nextSteps,
-      recovery: buildCommanderRecoveryPayload(context, {
-        missing: suggestions
-      })
-    });
+  if (!unknownOption) {
+    return null;
   }
+  const optionName = unknownOption[1];
+  const suggestions = normalizeOptionFlags(context?.unknownOptionSuggestions);
+  const retryCommand = context?.suggestedRetryCommand;
+  if (commandName === "update" && (optionName === "--file" || optionName === "--doc")) {
+    return buildUnsupportedUpdateOptionGuidance(optionName, context, suggestions);
+  }
+  const otherCommands = normalizeContextList(context?.unknownOptionOtherCommands);
+  const nextSteps = [
+    "Run command help to confirm the exact option contracts for this command path.",
+    ...suggestions && suggestions.length > 0 ? [`Nearest supported options: ${suggestions.join(", ")}`] : [],
+    ...otherCommands && otherCommands.length > 0 ? [`${optionName} is a valid option on: ${otherCommands.join(", ")}. If you meant one of those, run that command instead.`] : [],
+    ...retryCommand ? [`Replay with suggested correction: ${retryCommand}`] : []
+  ];
+  const examples = [
+    ...retryCommand ? [retryCommand] : [],
+    `pm ${commandName ?? "<command>"} --help`
+  ];
+  return makeGuidanceMessage({
+    code: "unknown_option",
+    title: `Unknown option ${optionName}`,
+    happened: `Commander does not recognize option ${optionName} for this command path.`,
+    required: "Use supported options only, or move option to the correct subcommand.",
+    why: "Option contracts are command-specific and intentionally validated.",
+    examples,
+    nextSteps,
+    recovery: buildCommanderRecoveryPayload(context, {
+      suggested_flags: suggestions
+    })
+  });
+}
+function buildKnownPackageCommandGuidance(commandToken, packageHint, baseExamples, baseNextSteps, context) {
+  const installStep = `"${commandToken}" is provided by the ${packageHint.packageName} package. Install it with: ${packageHint.installCommand}`;
+  return makeGuidanceMessage({
+    code: "unknown_command",
+    title: `Unknown command ${commandToken}`,
+    happened: `pm does not expose command path "${commandToken}" in current runtime configuration. It is shipped by the optional ${packageHint.packageName} package.`,
+    required: `Install the ${packageHint.packageName} package, or use a valid command name or subcommand path.`,
+    why: "Command registry includes core commands plus active extension command handlers; package-provided commands appear only after the package is installed.",
+    examples: dedupeStrings([packageHint.installCommand, ...baseExamples]),
+    nextSteps: dedupeStrings([installStep, ...baseNextSteps]),
+    recovery: buildCommanderRecoveryPayload(context)
+  });
+}
+function buildUnknownCommandGuidance(message, context) {
   const unknownCommand = message.match(/unknown command '([^']+)'/);
-  if (unknownCommand) {
-    const commandToken = unknownCommand[1];
-    const runtimeExamples = normalizeContextList(context?.unknownCommandExamples);
-    const runtimeNextSteps = normalizeContextList(context?.unknownCommandNextSteps);
-    const packageHint = resolveKnownPackageCommandHint(commandToken);
-    const baseExamples = runtimeExamples ?? ["pm --help"];
-    const baseNextSteps = runtimeNextSteps ?? ["Verify spelling and active extensions, then rerun."];
-    if (packageHint) {
-      const installStep = `"${commandToken}" is provided by the ${packageHint.packageName} package. Install it with: ${packageHint.installCommand}`;
-      return makeGuidanceMessage({
-        code: "unknown_command",
-        title: `Unknown command ${commandToken}`,
-        happened: `pm does not expose command path "${commandToken}" in current runtime configuration. It is shipped by the optional ${packageHint.packageName} package.`,
-        required: `Install the ${packageHint.packageName} package, or use a valid command name or subcommand path.`,
-        why: "Command registry includes core commands plus active extension command handlers; package-provided commands appear only after the package is installed.",
-        examples: dedupeStrings([packageHint.installCommand, ...baseExamples]),
-        nextSteps: dedupeStrings([installStep, ...baseNextSteps]),
-        recovery: buildCommanderRecoveryPayload(context)
-      });
-    }
-    return makeGuidanceMessage({
-      code: "unknown_command",
-      title: `Unknown command ${commandToken}`,
-      happened: `pm does not expose command path "${commandToken}" in current runtime configuration.`,
-      required: "Use a valid command name or subcommand path.",
-      why: "Command registry includes core commands plus active extension command handlers.",
-      examples: baseExamples,
-      nextSteps: baseNextSteps,
-      recovery: buildCommanderRecoveryPayload(context)
-    });
+  if (!unknownCommand) {
+    return null;
   }
-  if (/too many arguments/i.test(message) && commandName === "test") {
-    const argv = context?.normalizedInvocationArgs;
-    const mutationFlag = findLinkedTestMutationFlag(argv);
-    if (mutationFlag) {
-      const retryCommand = buildLinkedTestQuotedRetryCommand(argv);
-      return makeGuidanceMessage({
-        code: "linked_test_value_not_quoted",
-        title: `Linked-test ${mutationFlag} value must be one argument`,
-        happened: `Commander saw extra positional tokens after the item id \u2014 usually a ${mutationFlag} value containing spaces (for example a command with " -- ") that the shell split into multiple tokens.`,
-        required: `Quote the whole ${mutationFlag} value as a single argument. Accepted forms: --add "command=npm test -- parser", --add command "npm test -- parser" (two-token form with the value quoted), or --add-json for complex commands.`,
-        why: "The shell splits unquoted values before pm can see them, so pm cannot reassemble the intended command unambiguously.",
-        examples: [
-          ...retryCommand ? [retryCommand] : [],
-          'pm test pm-a1b2 --add "command=npm test -- parser"',
-          'pm test pm-a1b2 --add command "npm test -- parser"',
-          `pm test pm-a1b2 --add-json '{"command":"npm test -- parser"}'`
-        ],
-        nextSteps: [
-          ...retryCommand ? [`Replay with the value re-joined into one argument: ${retryCommand}`] : [],
-          "Prefer --add-json for commands containing commas, equals signs, or quotes.",
-          'Run "pm test --help" for linked-test entry contracts.'
-        ],
-        recovery: buildCommanderRecoveryPayload(context, retryCommand ? { suggested_retry: retryCommand } : {})
-      });
-    }
+  const commandToken = unknownCommand[1];
+  const runtimeExamples = normalizeContextList(context?.unknownCommandExamples);
+  const runtimeNextSteps = normalizeContextList(context?.unknownCommandNextSteps);
+  const packageHint = resolveKnownPackageCommandHint(commandToken);
+  const baseExamples = runtimeExamples ?? ["pm --help"];
+  const baseNextSteps = runtimeNextSteps ?? ["Verify spelling and active extensions, then rerun."];
+  if (packageHint) {
+    return buildKnownPackageCommandGuidance(commandToken, packageHint, baseExamples, baseNextSteps, context);
+  }
+  return makeGuidanceMessage({
+    code: "unknown_command",
+    title: `Unknown command ${commandToken}`,
+    happened: `pm does not expose command path "${commandToken}" in current runtime configuration.`,
+    required: "Use a valid command name or subcommand path.",
+    why: "Command registry includes core commands plus active extension command handlers.",
+    examples: baseExamples,
+    nextSteps: baseNextSteps,
+    recovery: buildCommanderRecoveryPayload(context)
+  });
+}
+function buildLinkedTestValueNotQuotedGuidance(message, commandName, allowedTypes, context) {
+  if (!/too many arguments/i.test(message) || commandName !== "test") {
+    return null;
+  }
+  const argv = context?.normalizedInvocationArgs;
+  const mutationFlag = findLinkedTestMutationFlag(argv);
+  if (!mutationFlag) {
+    return null;
+  }
+  const retryCommand = buildLinkedTestQuotedRetryCommand(argv);
+  return makeGuidanceMessage({
+    code: "linked_test_value_not_quoted",
+    title: `Linked-test ${mutationFlag} value must be one argument`,
+    happened: `Commander saw extra positional tokens after the item id \u2014 usually a ${mutationFlag} value containing spaces (for example a command with " -- ") that the shell split into multiple tokens.`,
+    required: `Quote the whole ${mutationFlag} value as a single argument. Accepted forms: --add "command=npm test -- parser", --add command "npm test -- parser" (two-token form with the value quoted), or --add-json for complex commands.`,
+    why: "The shell splits unquoted values before pm can see them, so pm cannot reassemble the intended command unambiguously.",
+    examples: [
+      ...retryCommand ? [retryCommand] : [],
+      'pm test pm-a1b2 --add "command=npm test -- parser"',
+      'pm test pm-a1b2 --add command "npm test -- parser"',
+      `pm test pm-a1b2 --add-json '{"command":"npm test -- parser"}'`
+    ],
+    nextSteps: [
+      ...retryCommand ? [`Replay with the value re-joined into one argument: ${retryCommand}`] : [],
+      "Prefer --add-json for commands containing commas, equals signs, or quotes.",
+      'Run "pm test --help" for linked-test entry contracts.'
+    ],
+    recovery: buildCommanderRecoveryPayload(context, retryCommand ? { suggested_retry: retryCommand } : {})
+  });
+}
+function buildCommanderErrorGuidance(rawMessage, commandName, allowedTypes, context) {
+  const message = normalizeMessage(rawMessage);
+  const guidance = buildMissingRequiredOptionGuidance(message, commandName, allowedTypes, context) ?? buildMissingRequiredArgumentGuidance(message, commandName, context) ?? buildUnknownOptionGuidance(message, commandName, context) ?? buildUnknownCommandGuidance(message, context) ?? buildLinkedTestValueNotQuotedGuidance(message, commandName, allowedTypes, context);
+  if (guidance) {
+    return guidance;
   }
   return makeGuidanceMessage({
     code: "invalid_command_usage",
@@ -3094,674 +3158,11 @@ function ensureCommandPath(root, pathParts) {
   return current;
 }
 
-// dist/cli/bootstrap-args.js
+// dist/cli/migration-gates.js
 !(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] = "df81f91f-ed92-5511-b34c-ea7c1b81230b");
-  } catch (e2) {
-  }
-})();
-function parseBootstrapPathToken(token, next) {
-  if (token === "--path" || token === "--pm-path") {
-    if (typeof next === "string" && next.length > 0) {
-      return {
-        consumed: 2,
-        pathValue: next,
-        preferred: token === "--pm-path"
-      };
-    }
-    return {
-      consumed: 1,
-      preferred: token === "--pm-path"
-    };
-  }
-  const inlinePrefix = token.startsWith("--path=") ? "--path=" : token.startsWith("--pm-path=") ? "--pm-path=" : void 0;
-  if (!inlinePrefix) {
-    return null;
-  }
-  const value = token.slice(inlinePrefix.length);
-  if (value.length > 0) {
-    return {
-      consumed: 1,
-      pathValue: value,
-      preferred: inlinePrefix === "--pm-path="
-    };
-  }
-  return {
-    consumed: 1,
-    preferred: inlinePrefix === "--pm-path="
-  };
-}
-function parseBootstrapGlobalOptions(argv) {
-  let legacyPathValue;
-  let pmPathValue;
-  let noExtensions = false;
-  let noPager = false;
-  let json = false;
-  let quiet = false;
-  let index = 0;
-  while (index < argv.length) {
-    const token = argv[index];
-    if (token === "--") {
-      break;
-    }
-    if (token === "--no-extensions") {
-      noExtensions = true;
-      index += 1;
-      continue;
-    }
-    if (token === "--no-pager") {
-      noPager = true;
-      index += 1;
-      continue;
-    }
-    if (token === "--json") {
-      json = true;
-      index += 1;
-      continue;
-    }
-    if (token === "--quiet") {
-      quiet = true;
-      index += 1;
-      continue;
-    }
-    const parsedPath = parseBootstrapPathToken(token, argv[index + 1]);
-    if (parsedPath) {
-      if (parsedPath.pathValue !== void 0) {
-        if (parsedPath.preferred) {
-          pmPathValue = parsedPath.pathValue;
-        } else {
-          legacyPathValue = parsedPath.pathValue;
-        }
-      }
-      index += parsedPath.consumed;
-      continue;
-    }
-    index += 1;
-  }
-  return {
-    path: pmPathValue ?? legacyPathValue,
-    noExtensions,
-    noPager,
-    json,
-    quiet
-  };
-}
-function stripGlobalBootstrapTokens(argv) {
-  const remaining = [];
-  let index = 0;
-  while (index < argv.length) {
-    const token = argv[index];
-    if (token === "--") {
-      break;
-    }
-    if (token === "--json" || token === "--quiet" || token === "--no-extensions" || token === "--no-pager" || token === "--profile" || token === "--id-only" || token === "--explain") {
-      index += 1;
-      continue;
-    }
-    if (token === "--path" || token === "--pm-path") {
-      index += 2;
-      continue;
-    }
-    if (token.startsWith("--path=") || token.startsWith("--pm-path=")) {
-      index += 1;
-      continue;
-    }
-    remaining.push(token);
-    index += 1;
-  }
-  return remaining;
-}
-function parseBootstrapHelpRequest(argv) {
-  const stripped = stripGlobalBootstrapTokens(argv);
-  const first = stripped[0]?.trim().toLowerCase();
-  if (first === "help") {
-    const commandPathTokens2 = [];
-    for (let index = 1; index < stripped.length; index += 1) {
-      const token = stripped[index];
-      if (token.startsWith("-")) {
-        break;
-      }
-      commandPathTokens2.push(token.trim().toLowerCase());
-    }
-    return {
-      requested: true,
-      commandPathTokens: commandPathTokens2
-    };
-  }
-  const helpFlagIndex = stripped.findIndex((token) => token === "--help" || token === "-h");
-  if (helpFlagIndex < 0) {
-    return {
-      requested: false,
-      commandPathTokens: []
-    };
-  }
-  const commandPathTokens = [];
-  for (const token of stripped) {
-    if (token.startsWith("-")) {
-      break;
-    }
-    commandPathTokens.push(token.trim().toLowerCase());
-  }
-  return {
-    requested: true,
-    commandPathTokens
-  };
-}
-function findCommandTokenIndex(argv) {
-  for (let index = 0; index < argv.length; index += 1) {
-    const token = argv[index];
-    if (token === "--") {
-      return void 0;
-    }
-    if (token === "--path" || token === "--pm-path") {
-      index += 1;
-      continue;
-    }
-    if (token.startsWith("--path=") || token.startsWith("--pm-path=") || token === "--json" || token === "--quiet" || token === "--no-extensions" || token === "--no-pager" || token === "--profile" || token === "--id-only" || token === "--explain") {
-      continue;
-    }
-    if (token.startsWith("-")) {
-      continue;
-    }
-    return index;
-  }
-  return void 0;
-}
-function parseBootstrapCommandName(argv) {
-  const index = findCommandTokenIndex(argv);
-  return index === void 0 ? void 0 : argv[index].trim().toLowerCase();
-}
-function shouldDisablePagerForInvocation(argv, bootstrapGlobal) {
-  if (bootstrapGlobal.noPager) {
-    return true;
-  }
-  if (process.stdout.isTTY === true) {
-    return false;
-  }
-  const helpRequest = parseBootstrapHelpRequest(argv);
-  return helpRequest.requested;
-}
-function applyBootstrapPagerPolicy(argv) {
-  const bootstrapGlobal = parseBootstrapGlobalOptions(argv);
-  if (!shouldDisablePagerForInvocation(argv, bootstrapGlobal)) {
-    return;
-  }
-  process.env.PAGER = "cat";
-  process.env.MANPAGER = "cat";
-  process.env.GIT_PAGER = "cat";
-  if (typeof process.env.LESS !== "string" || process.env.LESS.trim().length === 0) {
-    process.env.LESS = "FRX";
-  }
-}
-var EXTENSION_ACTION_SYNTAX_TOKENS = /* @__PURE__ */ new Set([
-  "install",
-  "uninstall",
-  "explore",
-  "manage",
-  "doctor",
-  "adopt",
-  "adopt-all",
-  "activate",
-  "deactivate"
-]);
-function normalizeLegacyExtensionActionSyntax(argv) {
-  const extensionIndex = argv.findIndex((token) => token === "extension");
-  if (extensionIndex < 0) {
-    return [...argv];
-  }
-  const actionToken = argv[extensionIndex + 1];
-  if (!actionToken || actionToken.startsWith("-")) {
-    return [...argv];
-  }
-  if (!EXTENSION_ACTION_SYNTAX_TOKENS.has(actionToken)) {
-    return [...argv];
-  }
-  if (argv.includes("--help") || argv.includes("-h")) {
-    return [...argv];
-  }
-  const forcedActionFlag = `--${actionToken}`;
-  if (argv.includes(forcedActionFlag)) {
-    return [...argv];
-  }
-  return [...argv.slice(0, extensionIndex + 1), forcedActionFlag, ...argv.slice(extensionIndex + 2)];
-}
-var EXECUTABLE_COMMAND_ALIASES = {
-  show: "get",
-  view: "get",
-  comment: "comments",
-  note: "notes",
-  learning: "learnings"
-};
-function rewriteCommandAlias(argv, trace) {
-  const index = findCommandTokenIndex(argv);
-  if (index === void 0) {
-    return argv;
-  }
-  const token = argv[index];
-  const canonical = EXECUTABLE_COMMAND_ALIASES[token.trim().toLowerCase()];
-  if (!canonical) {
-    return argv;
-  }
-  const rewritten = [...argv];
-  rewritten[index] = canonical;
-  trace.push({ from: token, to: [canonical], reason: "command_alias", confidence: "high" });
-  return rewritten;
-}
-function normalizeFlagKeyToken(raw) {
-  const withoutPrefix = raw.replace(/^--?/, "");
-  return withoutPrefix.replace(/_/g, "-").replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
-}
-function toComparableFlagKey(raw) {
-  return normalizeFlagKeyToken(raw).replace(/-/g, "");
-}
-function markUnambiguousFlag(map, key, canonicalFlag) {
-  const existing = map.get(key);
-  if (existing === void 0) {
-    map.set(key, canonicalFlag);
-    return;
-  }
-  if (existing !== canonicalFlag) {
-    map.set(key, null);
-  }
-}
-function collectLongFlagCandidates(contract) {
-  const candidates = [];
-  const pushLongFlag = (value) => {
-    if (typeof value !== "string") {
-      return;
-    }
-    if (!value.startsWith("--")) {
-      return;
-    }
-    candidates.push(value);
-  };
-  pushLongFlag(contract.flag);
-  for (const alias of contract.aliases ?? []) {
-    pushLongFlag(alias);
-  }
-  return candidates;
-}
-function buildFlagLookup(commandName, contractsOverride) {
-  const contracts = contractsOverride ?? resolveSubcommandFlagContractsForCommand(commandName);
-  const canonicalByNormalized = /* @__PURE__ */ new Map();
-  const canonicalByCompact = /* @__PURE__ */ new Map();
-  const canonicalComparablesMap = /* @__PURE__ */ new Map();
-  const listCanonicalFlags = /* @__PURE__ */ new Set();
-  for (const contract of contracts) {
-    const longCandidates = collectLongFlagCandidates(contract);
-    if (longCandidates.length === 0) {
-      continue;
-    }
-    const canonicalFlag = `--${normalizeFlagKeyToken(longCandidates[0])}`;
-    for (const candidate of longCandidates) {
-      markUnambiguousFlag(canonicalByNormalized, normalizeFlagKeyToken(candidate), canonicalFlag);
-      markUnambiguousFlag(canonicalByCompact, toComparableFlagKey(candidate), canonicalFlag);
-    }
-    const comparable = toComparableFlagKey(canonicalFlag);
-    if (!canonicalComparablesMap.has(canonicalFlag)) {
-      canonicalComparablesMap.set(canonicalFlag, comparable);
-    }
-    if (contract.list === true) {
-      listCanonicalFlags.add(canonicalFlag);
-    }
-  }
-  return {
-    canonicalByNormalized,
-    canonicalByCompact,
-    canonicalComparables: [...canonicalComparablesMap.entries()].map(([canonicalFlag, comparable]) => ({
-      canonicalFlag,
-      comparable
-    })),
-    listCanonicalFlags
-  };
-}
-function resolveCanonicalFlag(rawKey, lookup) {
-  const normalizedKey = normalizeFlagKeyToken(rawKey);
-  const direct = lookup.canonicalByNormalized.get(normalizedKey);
-  if (typeof direct === "string") {
-    return {
-      flag: direct,
-      reason: "flag_alias",
-      confidence: "high"
-    };
-  }
-  const comparableKey = normalizedKey.replace(/-/g, "");
-  const compactMatch = lookup.canonicalByCompact.get(comparableKey);
-  if (typeof compactMatch === "string") {
-    return {
-      flag: compactMatch,
-      reason: "flag_alias",
-      confidence: "high"
-    };
-  }
-  const maxDistance = comparableKey.length >= 8 ? 2 : 1;
-  let bestDistance = Number.POSITIVE_INFINITY;
-  let bestFlag;
-  let tied = false;
-  for (const candidate of lookup.canonicalComparables) {
-    const distance = levenshteinDistanceWithinLimit(comparableKey, candidate.comparable, maxDistance);
-    if (distance === null) {
-      continue;
-    }
-    if (distance < bestDistance) {
-      bestDistance = distance;
-      bestFlag = candidate.canonicalFlag;
-      tied = false;
-      continue;
-    }
-    if (distance === bestDistance && bestFlag !== candidate.canonicalFlag) {
-      tied = true;
-    }
-  }
-  if (!bestFlag || tied || !Number.isFinite(bestDistance) || bestDistance <= 0) {
-    return null;
-  }
-  return {
-    flag: bestFlag,
-    reason: "flag_typo",
-    confidence: bestDistance >= 2 ? "medium" : "high"
-  };
-}
-function parseBareKeyValueToken(token) {
-  if (token.includes("://")) {
-    return null;
-  }
-  const match = token.match(/^([A-Za-z][A-Za-z0-9_-]{1,63})([:=])(.*)$/);
-  if (!match) {
-    return null;
-  }
-  const key = match[1];
-  const value = match[3];
-  if (value.length === 0) {
-    return null;
-  }
-  return {
-    key,
-    value
-  };
-}
-function normalizeLongOptionToken(token, lookup) {
-  if (!token.startsWith("--")) {
-    return { tokens: [token] };
-  }
-  const equalsIndex = token.indexOf("=");
-  const key = equalsIndex >= 0 ? token.slice(0, equalsIndex) : token;
-  const inlineValue = equalsIndex >= 0 ? token.slice(equalsIndex + 1) : void 0;
-  const resolution = resolveCanonicalFlag(key, lookup);
-  if (!resolution) {
-    return { tokens: [token] };
-  }
-  const normalizedToken = inlineValue === void 0 ? resolution.flag : `${resolution.flag}=${inlineValue}`;
-  if (normalizedToken === token) {
-    return { tokens: [token] };
-  }
-  return {
-    tokens: [normalizedToken],
-    event: {
-      from: token,
-      to: [normalizedToken],
-      reason: resolution.reason,
-      confidence: resolution.confidence
-    }
-  };
-}
-var GLOBAL_VALUE_CONSUMING_FLAGS = /* @__PURE__ */ new Set(["--pm-path", "--path"]);
-function splitCanonicalListToken(token) {
-  if (!token.startsWith("--")) {
-    return null;
-  }
-  const equalsIndex = token.indexOf("=");
-  if (equalsIndex < 0) {
-    return { flag: token };
-  }
-  return {
-    flag: token.slice(0, equalsIndex),
-    inlineValue: token.slice(equalsIndex + 1)
-  };
-}
-function coalesceRepeatedListFlags(argv, listFlags, valueConsumingFlags = /* @__PURE__ */ new Set(), multiValueListFlags = /* @__PURE__ */ new Set()) {
-  if (listFlags.size === 0) {
-    return { argv: [...argv], events: [] };
-  }
-  const result = [];
-  const slots = /* @__PURE__ */ new Map();
-  let index = 0;
-  while (index < argv.length) {
-    const token = argv[index];
-    if (token === "--") {
-      result.push(...argv.slice(index));
-      break;
-    }
-    if (valueConsumingFlags.has(token)) {
-      result.push(token);
-      const next = argv[index + 1];
-      if (typeof next === "string" && next !== "--") {
-        result.push(next);
-        index += 2;
-      } else {
-        index += 1;
-      }
-      continue;
-    }
-    const parsed = splitCanonicalListToken(token);
-    if (!parsed || !listFlags.has(parsed.flag)) {
-      result.push(token);
-      index += 1;
-      continue;
-    }
-    let value;
-    let consumed = 1;
-    if (parsed.inlineValue !== void 0) {
-      value = parsed.inlineValue;
-    } else {
-      const next = argv[index + 1];
-      if (typeof next === "string" && next !== "--" && !next.startsWith("-")) {
-        const values = [next];
-        if (multiValueListFlags.has(parsed.flag)) {
-          let valueIndex = index + 2;
-          while (valueIndex < argv.length && argv[valueIndex] !== "--" && !argv[valueIndex].startsWith("-")) {
-            values.push(argv[valueIndex]);
-            valueIndex += 1;
-          }
-        }
-        value = values.join(",");
-        consumed = 1 + values.length;
-      }
-    }
-    if (value === void 0) {
-      result.push(token);
-      index += consumed;
-      continue;
-    }
-    const originalTokens = argv.slice(index, index + consumed);
-    const existing = slots.get(parsed.flag);
-    if (existing) {
-      existing.values.push(value);
-      existing.occurrences += 1;
-    } else {
-      const slot = {
-        outputIndex: result.length,
-        originalTokens,
-        values: [value],
-        occurrences: 1
-      };
-      slots.set(parsed.flag, slot);
-      result.push(null);
-    }
-    index += consumed;
-  }
-  const events = [];
-  const splices = [];
-  for (const [flag, slot] of slots) {
-    const shouldMerge = slot.occurrences >= 2 || multiValueListFlags.has(flag) && slot.originalTokens.length > 2;
-    if (shouldMerge) {
-      const mergedToken = `${flag}=${slot.values.join(",")}`;
-      splices.push({ outputIndex: slot.outputIndex, tokens: [mergedToken] });
-      events.push({
-        from: `${flag} (x${slot.occurrences})`,
-        to: [mergedToken],
-        reason: "list_merge",
-        confidence: "high"
-      });
-    } else {
-      splices.push({ outputIndex: slot.outputIndex, tokens: slot.originalTokens });
-    }
-  }
-  splices.sort((a, b) => b.outputIndex - a.outputIndex);
-  for (const splice of splices) {
-    result.splice(splice.outputIndex, 1, ...splice.tokens);
-  }
-  return { argv: result, events };
-}
-var LINKED_TEST_TWO_TOKEN_KEYS_BY_FLAG = /* @__PURE__ */ new Map([
-  ["--add", /* @__PURE__ */ new Set(["command", "cmd", "path"])],
-  ["--remove", /* @__PURE__ */ new Set(["command", "path"])]
-]);
-function isLinkedTestTwoTokenValuePosition(commandName, emittedTokens) {
-  if (commandName !== "test" || emittedTokens.length < 2) {
-    return false;
-  }
-  const key = emittedTokens[emittedTokens.length - 1];
-  const flag = emittedTokens[emittedTokens.length - 2];
-  const keys = LINKED_TEST_TWO_TOKEN_KEYS_BY_FLAG.get(flag);
-  return keys !== void 0 && keys.has(key);
-}
-function mergeLinkedTestTwoTokenEntries(argv, commandName, trace) {
-  if (commandName !== "test") {
-    return argv;
-  }
-  const result = [];
-  let index = 0;
-  while (index < argv.length) {
-    const token = argv[index];
-    if (token === "--") {
-      result.push(...argv.slice(index));
-      return result;
-    }
-    const keys = LINKED_TEST_TWO_TOKEN_KEYS_BY_FLAG.get(token);
-    const key = keys ? argv[index + 1] : void 0;
-    if (!keys || typeof key !== "string" || !keys.has(key)) {
-      result.push(token);
-      index += 1;
-      continue;
-    }
-    let runEnd = index + 2;
-    while (runEnd < argv.length && !argv[runEnd].startsWith("-")) {
-      runEnd += 1;
-    }
-    if (runEnd - (index + 2) !== 1) {
-      result.push(token);
-      index += 1;
-      continue;
-    }
-    const value = argv[index + 2];
-    const mergedValue = `${key}=${value}`;
-    result.push(token, mergedValue);
-    trace.push({
-      from: `${token} ${key} ${value}`,
-      to: [token, mergedValue],
-      reason: "bare_key_value",
-      confidence: "high"
-    });
-    index += 3;
-  }
-  return result;
-}
-function normalizeBootstrapInvocation(argv) {
-  const trace = [];
-  const legacyNormalized = normalizeLegacyExtensionActionSyntax(argv);
-  if (legacyNormalized.length !== argv.length || legacyNormalized.some((token, index) => token !== argv[index])) {
-    trace.push({
-      from: argv.join(" "),
-      to: [...legacyNormalized],
-      reason: "legacy_extension_action",
-      confidence: "high"
-    });
-  }
-  const aliasNormalized = rewriteCommandAlias(legacyNormalized, trace);
-  const commandName = parseBootstrapCommandName(aliasNormalized);
-  const commandPathName = parseBootstrapCommandPathName(aliasNormalized);
-  const lookup = buildFlagLookup(commandPathName ?? commandName);
-  const normalizedArgv = [];
-  for (let index = 0; index < aliasNormalized.length; index += 1) {
-    const token = aliasNormalized[index];
-    if (token === "--") {
-      normalizedArgv.push(...aliasNormalized.slice(index));
-      break;
-    }
-    const previous = normalizedArgv[normalizedArgv.length - 1];
-    if (token.startsWith("--")) {
-      const normalizedToken = normalizeLongOptionToken(token, lookup);
-      normalizedArgv.push(...normalizedToken.tokens);
-      if (normalizedToken.event) {
-        trace.push(normalizedToken.event);
-      }
-      continue;
-    }
-    const bareKeyValue = parseBareKeyValueToken(token);
-    if (bareKeyValue && !(typeof previous === "string" && previous.startsWith("-")) && !isLinkedTestTwoTokenValuePosition(commandName, normalizedArgv)) {
-      const resolution = resolveCanonicalFlag(bareKeyValue.key, lookup);
-      if (resolution) {
-        const replacement = [resolution.flag, bareKeyValue.value];
-        normalizedArgv.push(...replacement);
-        trace.push({
-          from: token,
-          to: replacement,
-          reason: "bare_key_value",
-          confidence: resolution.confidence
-        });
-        continue;
-      }
-    }
-    normalizedArgv.push(token);
-  }
-  const linkedTestNormalized = mergeLinkedTestTwoTokenEntries(normalizedArgv, commandName, trace);
-  const coalesced = coalesceRepeatedListFlags(linkedTestNormalized, lookup.listCanonicalFlags, GLOBAL_VALUE_CONSUMING_FLAGS, commandName === "create" ? /* @__PURE__ */ new Set(["--tags"]) : /* @__PURE__ */ new Set());
-  for (const event of coalesced.events) {
-    trace.push(event);
-  }
-  return {
-    argv: coalesced.argv,
-    commandName,
-    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];
-    if (token === "--type") {
-      const candidate = argv[index + 1];
-      if (typeof candidate === "string" && candidate.trim().length > 0) {
-        return candidate.trim();
-      }
-      continue;
-    }
-    if (token.startsWith("--type=")) {
-      const candidate = token.slice("--type=".length).trim();
-      if (candidate.length > 0) {
-        return candidate;
-      }
-    }
-  }
-  return void 0;
-}
-
-// dist/cli/migration-gates.js
-!(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] = "3f652b37-a8f5-5d02-9199-d2982382b7a8");
+    n && (e._sentryDebugIds = e._sentryDebugIds || {}, e._sentryDebugIds[n] = "e5659f1c-76e6-52e9-96f6-201091483918");
   } catch (e2) {
   }
 })();
@@ -3813,52 +3214,29 @@ function collectMandatoryMigrationBlockers(migrations) {
 function hasMutatingListValues(value) {
   return Array.isArray(value) && value.length > 0;
 }
+var ALWAYS_MUTATING_COMMANDS = /* @__PURE__ */ new Set(["create", "beads import", "todos import"]);
+var FORCEABLE_MUTATING_COMMANDS = /* @__PURE__ */ new Set(["restore", "update", "close", "delete", "append", "claim", "release"]);
+var TEXT_APPEND_COMMANDS = /* @__PURE__ */ new Set(["comments", "notes", "learnings"]);
+var LIST_MUTATION_COMMANDS = /* @__PURE__ */ new Set(["files", "docs", "test"]);
 function decideWriteGate(commandPath, options) {
   const forceRequested = options.force === true;
-  switch (commandPath) {
-    case "create":
-    case "beads import":
-    case "todos import":
-      return {
-        isMutation: true,
-        forceCapable: false,
-        forceRequested: false
-      };
-    case "restore":
-    case "update":
-    case "close":
-    case "delete":
-    case "append":
-    case "claim":
-    case "release":
-      return {
-        isMutation: true,
-        forceCapable: true,
-        forceRequested
-      };
-    case "comments":
-    case "notes":
-    case "learnings":
-      return {
-        isMutation: typeof options.add === "string",
-        forceCapable: true,
-        forceRequested
-      };
-    case "files":
-    case "docs":
-    case "test":
-      return {
-        isMutation: hasMutatingListValues(options.add) || hasMutatingListValues(options.remove),
-        forceCapable: true,
-        forceRequested
-      };
-    default:
-      return {
-        isMutation: false,
-        forceCapable: false,
-        forceRequested: false
-      };
+  if (ALWAYS_MUTATING_COMMANDS.has(commandPath)) {
+    return { isMutation: true, forceCapable: false, forceRequested: false };
+  }
+  if (FORCEABLE_MUTATING_COMMANDS.has(commandPath)) {
+    return { isMutation: true, forceCapable: true, forceRequested };
+  }
+  if (TEXT_APPEND_COMMANDS.has(commandPath)) {
+    return { isMutation: typeof options.add === "string", forceCapable: true, forceRequested };
   }
+  if (LIST_MUTATION_COMMANDS.has(commandPath)) {
+    return {
+      isMutation: hasMutatingListValues(options.add) || hasMutatingListValues(options.remove),
+      forceCapable: true,
+      forceRequested
+    };
+  }
+  return { isMutation: false, forceCapable: false, forceRequested: false };
 }
 function enforceMandatoryMigrationWriteGate(commandPath, options, blockers) {
   if (blockers.length === 0) {
@@ -3903,7 +3281,7 @@ async function enforceItemFormatWriteGateAndPreflightMigration(commandPath, opti
 !(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] = "c0b38b44-fdea-5d80-b2d4-361f2b07c8f1");
+    n && (e._sentryDebugIds = e._sentryDebugIds || {}, e._sentryDebugIds[n] = "66620fd2-4f5f-5930-a9e1-0497672abda9");
   } catch (e2) {
   }
 })();
@@ -4288,6 +3666,48 @@ function isKnownHelpCommandPath(root, commandPathTokens) {
   }
   return matchedAny;
 }
+async function resolveAllowedTypesForUsage(bootstrapGlobal) {
+  try {
+    const pmRoot = resolvePmRoot(process.cwd(), bootstrapGlobal.path);
+    if (!await pathExists(getSettingsPath(pmRoot))) {
+      return BUILTIN_TYPE_HELP_VALUES;
+    }
+    const settings = await readSettings(pmRoot);
+    const extensionRegistrations = bootstrapGlobal.noExtensions ? void 0 : getActiveExtensionRegistrations();
+    const typeRegistry = resolveItemTypeRegistry(settings, extensionRegistrations);
+    return typeRegistry.types.length > 0 ? typeRegistry.types.join("|") : BUILTIN_TYPE_HELP_VALUES;
+  } catch {
+    return BUILTIN_TYPE_HELP_VALUES;
+  }
+}
+function resolveUnknownOptionSuggestions(message, commandName) {
+  const match = message.match(/unknown option '([^']+)'/i);
+  const suggestions = match && commandName ? dedupeStrings2([
+    ...getSemanticUnknownOptionSuggestions(commandName, match[1]),
+    ...suggestNearestLongFlags(match[1], collectKnownLongFlags(commandName))
+  ]) : void 0;
+  return {
+    match,
+    suggestions,
+    otherCommands: match ? findOtherCommandsForFlag(match[1], commandName) : []
+  };
+}
+function resolveSuggestedRetryForUnknownOption(invocationArgv, unknownOptionMatch, unknownOptionSuggestions) {
+  if (!unknownOptionMatch || !unknownOptionSuggestions || unknownOptionSuggestions.length === 0) {
+    return void 0;
+  }
+  const rewritten = rewriteUnknownOptionArgv(invocationArgv, unknownOptionMatch[1], unknownOptionSuggestions[0]);
+  return rewritten ? renderAttemptedCommand(rewritten) : void 0;
+}
+function resolveSuggestedRetryForMissingOption(message, invocationArgv) {
+  const missingRequiredOption = message.match(/required option '([^']+)' not specified/i);
+  const requiredOptionToken = missingRequiredOption?.[1] ? trimTrailingPunctuationToken(firstWhitespaceSeparatedToken(missingRequiredOption[1].trim())) : void 0;
+  if (!requiredOptionToken?.startsWith("--")) {
+    return void 0;
+  }
+  const hasFlag = invocationArgv.some((token) => token === requiredOptionToken || token.startsWith(`${requiredOptionToken}=`));
+  return hasFlag ? void 0 : renderAttemptedCommand([...invocationArgv, requiredOptionToken, "<value>"]);
+}
 async function resolveCommanderUsageContext(error, rootProgram, extensionDescriptors) {
   const rawMessage = typeof error === "object" && error !== null ? error.message : void 0;
   const message = rawMessage ?? "Invalid command usage";
@@ -4296,42 +3716,10 @@ async function resolveCommanderUsageContext(error, rootProgram, extensionDescrip
   const commandName = parseBootstrapCommandName(invocationArgv);
   const attemptedCommand = renderAttemptedCommand(invocationArgv);
   const providedOptionFlags = extractProvidedOptionFlags(invocationArgv);
-  let allowedTypes = BUILTIN_TYPE_HELP_VALUES;
-  try {
-    const pmRoot = resolvePmRoot(process.cwd(), bootstrapGlobal.path);
-    if (await pathExists(getSettingsPath(pmRoot))) {
-      const settings = await readSettings(pmRoot);
-      const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());
-      if (typeRegistry.types.length > 0) {
-        allowedTypes = typeRegistry.types.join("|");
-      }
-    }
-  } catch {
-  }
+  const allowedTypes = await resolveAllowedTypesForUsage(bootstrapGlobal);
   const unknownCommandGuidance = buildUnknownCommandGuidanceFromRuntime(message, rootProgram, extensionDescriptors);
-  const unknownOptionMatch = message.match(/unknown option '([^']+)'/i);
-  const unknownOptionSuggestions = unknownOptionMatch && commandName ? dedupeStrings2([
-    ...getSemanticUnknownOptionSuggestions(commandName, unknownOptionMatch[1]),
-    ...suggestNearestLongFlags(unknownOptionMatch[1], collectKnownLongFlags(commandName))
-  ]) : void 0;
-  const unknownOptionOtherCommands = unknownOptionMatch ? findOtherCommandsForFlag(unknownOptionMatch[1], commandName) : [];
-  let suggestedRetryCommand;
-  if (unknownOptionMatch && unknownOptionSuggestions && unknownOptionSuggestions.length > 0) {
-    const rewritten = rewriteUnknownOptionArgv(invocationArgv, unknownOptionMatch[1], unknownOptionSuggestions[0]);
-    if (rewritten) {
-      suggestedRetryCommand = renderAttemptedCommand(rewritten);
-    }
-  }
-  if (!suggestedRetryCommand) {
-    const missingRequiredOption = message.match(/required option '([^']+)' not specified/i);
-    const requiredOptionToken = missingRequiredOption?.[1] ? trimTrailingPunctuationToken(firstWhitespaceSeparatedToken(missingRequiredOption[1].trim())) : void 0;
-    if (requiredOptionToken?.startsWith("--")) {
-      const hasFlag = invocationArgv.some((token) => token.startsWith(requiredOptionToken));
-      if (!hasFlag) {
-        suggestedRetryCommand = renderAttemptedCommand([...invocationArgv, requiredOptionToken, "<value>"]);
-      }
-    }
-  }
+  const unknownOption = resolveUnknownOptionSuggestions(message, commandName);
+  const suggestedRetryCommand = resolveSuggestedRetryForUnknownOption(invocationArgv, unknownOption.match, unknownOption.suggestions) ?? resolveSuggestedRetryForMissingOption(message, invocationArgv);
   return {
     message,
     commandName,
@@ -4339,8 +3727,8 @@ async function resolveCommanderUsageContext(error, rootProgram, extensionDescrip
     attemptedCommand,
     normalizedInvocationArgs: [...invocationArgv],
     providedOptionFlags,
-    unknownOptionSuggestions,
-    unknownOptionOtherCommands: unknownOptionOtherCommands.length > 0 ? unknownOptionOtherCommands : void 0,
+    unknownOptionSuggestions: unknownOption.suggestions,
+    unknownOptionOtherCommands: unknownOption.otherCommands.length > 0 ? unknownOption.otherCommands : void 0,
     suggestedRetryCommand,
     ...unknownCommandGuidance
   };
@@ -4660,7 +4048,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] = "9f13a662-73c4-5ffa-99bc-4edee2b7a7fb");
+    n && (e._sentryDebugIds = e._sentryDebugIds || {}, e._sentryDebugIds[n] = "a367900b-1ec4-5110-9997-7f0a02e315c0");
   } catch (e2) {
   }
 })();
@@ -4705,10 +4093,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-MPANILQF.js"));
-var loadListQueryRegistrationModule = createLazyModule(() => import("./chunks/register-list-query-KY6Z6WV7.js"));
-var loadMutationRegistrationModule = createLazyModule(() => import("./chunks/register-mutation-N6AYSKPM.js"));
-var loadOperationRegistrationModule = createLazyModule(() => import("./chunks/register-operations-L6CYTOIH.js"));
+var loadSetupRegistrationModule = createLazyModule(() => import("./chunks/register-setup-ZCGKHDKL.js"));
+var loadListQueryRegistrationModule = createLazyModule(() => import("./chunks/register-list-query-XN4ZRHSV.js"));
+var loadMutationRegistrationModule = createLazyModule(() => import("./chunks/register-mutation-KRLAHEL2.js"));
+var loadOperationRegistrationModule = createLazyModule(() => import("./chunks/register-operations-4PASGJDB.js"));
 function describeUnknownError(error) {
   if (error instanceof PmCliError) {
     return error.message;
@@ -4754,6 +4142,57 @@ function inferMissingFieldsFromErrorMessage(message) {
   const normalized = [...new Set(matches.map((entry) => normalizeLongOptionFlag(entry) ?? entry))];
   return normalized.length > 0 ? normalized : void 0;
 }
+function inferMissingFieldsForRecovery(rawMessage, invocationArgv, existingRecovery) {
+  if (existingRecovery?.suggested_retry) {
+    return void 0;
+  }
+  const providedFields = extractProvidedOptionFlags(invocationArgv);
+  const providedSet = new Set(providedFields.map((flag) => normalizeLongOptionFlag(flag) ?? flag));
+  const rawInferred = inferMissingFieldsFromErrorMessage(rawMessage);
+  const trulyMissing = rawInferred?.filter((flag) => !providedSet.has(normalizeLongOptionFlag(flag) ?? flag));
+  return trulyMissing && trulyMissing.length > 0 ? trulyMissing : void 0;
+}
+function resolveRecoverySuggestedRetry(invocationArgv, attemptedCommand, inferredMissing, existingRecovery) {
+  if (existingRecovery?.suggested_retry) {
+    return existingRecovery.suggested_retry;
+  }
+  const missingFlag = inferredMissing?.[0];
+  const normalizedMissing = missingFlag ? normalizeLongOptionFlag(missingFlag) : void 0;
+  const suggestedRetry = normalizedMissing ? renderAttemptedCommand3([...invocationArgv, normalizedMissing, "<value>"]) : attemptedCommand;
+  return suggestedRetry === attemptedCommand ? void 0 : suggestedRetry;
+}
+function projectExistingRecoveryOptionalFields(existingRecovery) {
+  if (!existingRecovery) {
+    return {};
+  }
+  const optionalFields = [
+    "recovery_mode",
+    "missing_required_fields",
+    "suggested_flags",
+    "fallback_candidates",
+    "next_best_command"
+  ];
+  const projected = {};
+  for (const field of optionalFields) {
+    const value = existingRecovery[field];
+    if (value !== void 0 && value !== null) {
+      projected[field] = value;
+    }
+  }
+  return projected;
+}
+function buildRecoveryPayload(params) {
+  const existingRecovery = params.existingRecovery;
+  return {
+    attempted_command: existingRecovery?.attempted_command ?? params.attemptedCommand,
+    normalized_args: existingRecovery?.normalized_args ?? [...params.invocationArgv],
+    /* c8 ignore next */
+    provided_fields: existingRecovery?.provided_fields ?? (params.providedFields.length > 0 ? params.providedFields : void 0),
+    missing: existingRecovery?.missing ?? params.inferredMissing,
+    ...projectExistingRecoveryOptionalFields(existingRecovery),
+    ...params.suggestedRetry ? { suggested_retry: params.suggestedRetry } : {}
+  };
+}
 function buildPmCliRecoveryContext(context, invocationArgv, rawMessage) {
   const explainRequested = invocationArgv.includes("--explain");
   const existingRecovery = context?.recovery;
@@ -4766,37 +4205,16 @@ function buildPmCliRecoveryContext(context, invocationArgv, rawMessage) {
   }
   const attemptedCommand = renderAttemptedCommand3(invocationArgv);
   const providedFields = extractProvidedOptionFlags(invocationArgv);
-  const providedSet = new Set(providedFields.map((flag) => normalizeLongOptionFlag(flag) ?? flag));
-  const rawInferred = existingRecovery?.suggested_retry ? void 0 : inferMissingFieldsFromErrorMessage(rawMessage);
-  const trulyMissing = rawInferred?.filter((flag) => !providedSet.has(normalizeLongOptionFlag(flag) ?? flag));
-  const inferredMissing = trulyMissing && trulyMissing.length > 0 ? trulyMissing : void 0;
-  let suggestedRetry = existingRecovery?.suggested_retry;
-  if (!suggestedRetry && inferredMissing && inferredMissing.length > 0) {
-    const missingFlag = inferredMissing[0];
-    const normalizedMissing = normalizeLongOptionFlag(missingFlag);
-    if (normalizedMissing) {
-      suggestedRetry = renderAttemptedCommand3([...invocationArgv, normalizedMissing, "<value>"]);
-    }
-  }
-  if (!suggestedRetry) {
-    suggestedRetry = attemptedCommand;
-  }
-  if (!existingRecovery?.suggested_retry && suggestedRetry === attemptedCommand) {
-    suggestedRetry = void 0;
-  }
-  const recovery = {
-    attempted_command: existingRecovery?.attempted_command ?? attemptedCommand,
-    normalized_args: existingRecovery?.normalized_args ?? [...invocationArgv],
-    /* c8 ignore next */
-    provided_fields: existingRecovery?.provided_fields ?? (providedFields.length > 0 ? providedFields : void 0),
-    missing: existingRecovery?.missing ?? inferredMissing,
-    ...existingRecovery?.recovery_mode ? { recovery_mode: existingRecovery.recovery_mode } : {},
-    ...existingRecovery?.missing_required_fields ? { missing_required_fields: existingRecovery.missing_required_fields } : {},
-    ...existingRecovery?.suggested_flags ? { suggested_flags: existingRecovery.suggested_flags } : {},
-    ...suggestedRetry ? { suggested_retry: suggestedRetry } : {},
-    ...existingRecovery?.fallback_candidates ? { fallback_candidates: existingRecovery.fallback_candidates } : {},
-    ...existingRecovery?.next_best_command ? { next_best_command: existingRecovery.next_best_command } : {}
-  };
+  const inferredMissing = inferMissingFieldsForRecovery(rawMessage, invocationArgv, existingRecovery);
+  const suggestedRetry = resolveRecoverySuggestedRetry(invocationArgv, attemptedCommand, inferredMissing, existingRecovery);
+  const recovery = buildRecoveryPayload({
+    invocationArgv,
+    attemptedCommand,
+    providedFields,
+    inferredMissing,
+    suggestedRetry,
+    existingRecovery
+  });
   return {
     ...context,
     recovery
@@ -5819,34 +5237,62 @@ function wrapProgramActionsForExtensionHandlers(rootProgram) {
   };
   visit(rootProgram);
 }
+async function clearDynamicExtensionCommandState(params) {
+  activeRuntimeExtensionCommandDescriptors = /* @__PURE__ */ new Map();
+  setActiveExtensionServices({ overrides: [] });
+  if (params) {
+    await maybeAttachCreateUpdatePolicyHelpText(params.rootProgram, params.pmRoot, params.invocationArgv, createEmptyExtensionRegistrationRegistry(), params.settings);
+  }
+}
+function attachDynamicExtensionHelp(command, descriptor, flagHelp, metadataHelp) {
+  if (descriptor?.flags && descriptor.flags.length > 0) {
+    applyDynamicExtensionFlagOptions(command, descriptor.flags);
+    const residualFlagHelp = buildResidualDynamicExtensionFlagHelp(command, descriptor.flags);
+    if (residualFlagHelp) {
+      command.addHelpText("after", residualFlagHelp);
+    }
+  } else if (flagHelp) {
+    command.addHelpText("after", flagHelp);
+  }
+  if (metadataHelp) {
+    command.addHelpText("after", metadataHelp);
+  }
+}
 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());
+    await clearDynamicExtensionCommandState({
+      rootProgram,
+      pmRoot,
+      invocationArgv
+    });
     return;
   }
   const discoverySnapshot = await loadRuntimeExtensionDiscoverySnapshot(pmRoot);
   const probe = buildBootstrapActivationProbe(invocationArgv);
   if (!discoverySnapshot) {
-    activeRuntimeExtensionCommandDescriptors = /* @__PURE__ */ new Map();
-    setActiveExtensionServices({ overrides: [] });
+    await clearDynamicExtensionCommandState();
     return;
   }
   if (!discoveryNeedsActivationForProbe(discoverySnapshot.discovery, probe)) {
-    activeRuntimeExtensionCommandDescriptors = /* @__PURE__ */ new Map();
-    setActiveExtensionServices({ overrides: [] });
-    await maybeAttachCreateUpdatePolicyHelpText(rootProgram, pmRoot, invocationArgv, createEmptyExtensionRegistrationRegistry(), discoverySnapshot.settings);
+    await clearDynamicExtensionCommandState({
+      rootProgram,
+      pmRoot,
+      invocationArgv,
+      settings: discoverySnapshot.settings
+    });
     emitExtensionSkippedProfile(bootstrapProfileEnabled(invocationArgv), discoverySnapshot, probe);
     return;
   }
   const snapshot = await loadRuntimeExtensionSnapshot(pmRoot);
   if (!snapshot) {
-    activeRuntimeExtensionCommandDescriptors = /* @__PURE__ */ new Map();
-    setActiveExtensionServices({ overrides: [] });
-    await maybeAttachCreateUpdatePolicyHelpText(rootProgram, pmRoot, invocationArgv, createEmptyExtensionRegistrationRegistry(), discoverySnapshot.settings);
+    await clearDynamicExtensionCommandState({
+      rootProgram,
+      pmRoot,
+      invocationArgv,
+      settings: discoverySnapshot.settings
+    });
     return;
   }
   setActiveExtensionServices(snapshot.services);
@@ -5863,18 +5309,7 @@ async function registerDynamicExtensionCommandPaths(rootProgram, invocationArgv)
     const flagHelp = snapshot.commandFlagHelp.get(commandPath);
     const metadataHelp = descriptor ? buildDynamicExtensionCommandMetadataHelp(descriptor) : null;
     if (existingCommand) {
-      if (descriptor?.flags && descriptor.flags.length > 0) {
-        applyDynamicExtensionFlagOptions(existingCommand, descriptor.flags);
-        const residualFlagHelp = buildResidualDynamicExtensionFlagHelp(existingCommand, descriptor.flags);
-        if (residualFlagHelp) {
-          existingCommand.addHelpText("after", residualFlagHelp);
-        }
-      } else if (flagHelp) {
-        existingCommand.addHelpText("after", flagHelp);
-      }
-      if (metadataHelp) {
-        existingCommand.addHelpText("after", metadataHelp);
-      }
+      attachDynamicExtensionHelp(existingCommand, descriptor, flagHelp, metadataHelp);
       continue;
     }
     const dynamicCommand = ensureCommandPath(rootProgram, pathParts);
@@ -6297,6 +5732,308 @@ function enforceExplicitRetryForFlagTypos(bootstrapInvocation) {
     }
   });
 }
+function createTelemetryCommandErrorEmitter(params) {
+  return async (event) => {
+    const errorCategory = resolveTelemetryErrorCategory(event.errorCode);
+    const commandResolution = deriveTelemetryCommandResolution({
+      ok: false,
+      errorCode: event.errorCode,
+      errorCategory
+    });
+    await emitTelemetryErrorEvent({
+      command: event.command,
+      args: params.invocationArgv,
+      options: event.options,
+      global: params.bootstrapGlobal,
+      pm_version: CLI_VERSION,
+      pm_root: params.bootstrapPmRoot,
+      error_code: event.errorCode,
+      error_message: event.errorMessage,
+      exit_code: event.exitCode,
+      error_category: errorCategory,
+      command_resolution: commandResolution,
+      resolution_stage: event.resolutionStage
+    });
+    return {
+      errorCategory,
+      commandResolution
+    };
+  };
+}
+async function prepareExtensionServicesForRunPmCliError(params) {
+  if (params.bootstrapGlobal.noExtensions) {
+    return;
+  }
+  const bootstrapProbe = buildBootstrapActivationProbe(params.invocationArgv);
+  const discoverySnapshot = await loadRuntimeExtensionDiscoverySnapshot(params.bootstrapPmRoot);
+  if (discoverySnapshot && discoveryNeedsActivationForProbe(discoverySnapshot.discovery, bootstrapProbe)) {
+    const bootstrapSnapshot = await loadRuntimeExtensionSnapshot(params.bootstrapPmRoot);
+    setRecoveredExtensionServices(bootstrapSnapshot);
+    return;
+  }
+  if (discoverySnapshot) {
+    emitExtensionSkippedProfile(bootstrapProfileEnabled(params.invocationArgv), discoverySnapshot, bootstrapProbe);
+  }
+  setActiveExtensionServices({ overrides: [] });
+}
+function setRecoveredExtensionServices(bootstrapSnapshot) {
+  if (!bootstrapSnapshot) {
+    setActiveExtensionServices({ overrides: [] });
+    return;
+  }
+  setActiveExtensionServices(bootstrapSnapshot.services);
+}
+async function finishRunPmCliFailure(params) {
+  sentryFinishCommandSpan(false, params.errorMessage, {
+    error_code: params.classificationCode,
+    error_category: params.errorCategory,
+    exit_code: params.exitCode,
+    command_resolution: params.commandResolution,
+    resolution_stage: params.resolutionStage
+  });
+  await runAndClearAfterCommandHooks({
+    ok: false,
+    error: params.errorMessage,
+    exit_code: params.exitCode,
+    error_code: params.classificationCode,
+    error_category: params.errorCategory,
+    command_resolution: params.commandResolution,
+    resolution_stage: params.resolutionStage
+  });
+}
+async function finishRunPmCliSuccessParse() {
+  sentryFinishCommandSpan(true, void 0, {
+    exit_code: EXIT_CODE.SUCCESS,
+    command_resolution: "success",
+    resolution_stage: "parse"
+  });
+  await runAndClearAfterCommandHooks({
+    ok: true,
+    exit_code: EXIT_CODE.SUCCESS,
+    command_resolution: "success",
+    resolution_stage: "parse"
+  });
+  process.exitCode = EXIT_CODE.SUCCESS;
+}
+async function handleRunPmCliKnownError(context, numericExitCode) {
+  const hasExplicitExitCode = typeof numericExitCode === "number" && Number.isFinite(numericExitCode);
+  if (!(context.error instanceof PmCliError) && (isCommanderError(context.error) || !hasExplicitExitCode)) {
+    return false;
+  }
+  const errorMessage = describeUnknownError(context.error);
+  const exitCode = context.error instanceof PmCliError ? context.error.exitCode : normalizeThrownExitCode(numericExitCode);
+  const rawContext = context.error instanceof PmCliError ? context.error.context : void 0;
+  const enrichedContext = buildPmCliRecoveryContext(rawContext, context.invocationArgv, errorMessage);
+  const classification = classifyPmCliError(errorMessage, enrichedContext);
+  const renderedError = context.jsonErrors ? JSON.stringify(formatPmCliErrorForJson(errorMessage, exitCode, enrichedContext), null, 2) : formatPmCliErrorForDisplay(errorMessage, enrichedContext);
+  printError(renderedError);
+  const { errorCategory, commandResolution } = await context.emitTelemetryCommandError({
+    command: context.attemptedCommand,
+    errorCode: classification.code,
+    errorMessage: classification.detail,
+    exitCode,
+    options: {
+      bootstrap_global_options: context.bootstrapGlobal
+    },
+    resolutionStage: "execute"
+  });
+  const loggedHandledErrorToSentry = await maybeLogHandledCliErrorToSentry({
+    command: context.attemptedCommand,
+    error_code: classification.code,
+    error_category: errorCategory,
+    exit_code: exitCode,
+    error_message: classification.detail,
+    command_resolution: commandResolution,
+    resolution_stage: "execute",
+    source_context: activeTelemetryCommandContext?.source_context
+  });
+  await finishRunPmCliFailure({
+    errorMessage,
+    exitCode,
+    classificationCode: classification.code,
+    errorCategory,
+    commandResolution,
+    resolutionStage: "execute"
+  });
+  if (loggedHandledErrorToSentry) {
+    sentryCaptureCliError(wrapThrownErrorForSentry(context.error, errorMessage));
+    await sentryFlush(HANDLED_ERROR_SENTRY_FLUSH_TIMEOUT_MS);
+  }
+  process.exitCode = exitCode;
+  return true;
+}
+function resolveUnknownHelpToken(invocationArgv) {
+  const helpRequest = parseBootstrapHelpRequest(invocationArgv);
+  return helpRequest.commandPathTokens[0] ?? parseBootstrapCommandName(invocationArgv) ?? "<command>";
+}
+async function handleUnknownHelpCommandError(context, code) {
+  const unknownToken = resolveUnknownHelpToken(context.invocationArgv);
+  const unknownMessage = `unknown command '${unknownToken}'`;
+  const recoveryCommandDescriptors = await loadRuntimeExtensionCommandDescriptorsForRecovery(resolvePmRoot(process.cwd(), context.bootstrapGlobal.path));
+  const usageContext = await resolveCommanderUsageContext({ message: unknownMessage }, program, recoveryCommandDescriptors);
+  const classification = classifyCommanderError(usageContext.message, usageContext.commandName, usageContext.allowedTypes, {
+    unknownCommandExamples: usageContext.unknownCommandExamples,
+    unknownCommandNextSteps: usageContext.unknownCommandNextSteps,
+    attemptedCommand: usageContext.attemptedCommand,
+    normalizedInvocationArgs: usageContext.normalizedInvocationArgs,
+    providedOptionFlags: usageContext.providedOptionFlags,
+    unknownOptionSuggestions: usageContext.unknownOptionSuggestions,
+    suggestedRetryCommand: usageContext.suggestedRetryCommand
+  });
+  const { errorCategory, commandResolution } = await context.emitTelemetryCommandError({
+    command: unknownToken,
+    errorCode: classification.code,
+    errorMessage: classification.detail,
+    exitCode: EXIT_CODE.USAGE,
+    options: {
+      bootstrap_global_options: context.bootstrapGlobal,
+      commander_code: code ?? "commander.helpDisplayed"
+    },
+    resolutionStage: "parse"
+  });
+  const loggedHandledErrorToSentry = await maybeLogHandledCliErrorToSentry({
+    command: unknownToken,
+    error_code: classification.code,
+    error_category: errorCategory,
+    exit_code: EXIT_CODE.USAGE,
+    error_message: classification.detail,
+    command_resolution: commandResolution,
+    resolution_stage: "parse",
+    source_context: activeTelemetryCommandContext?.source_context
+  });
+  const renderedUsage = context.jsonErrors ? await formatCommanderUsageJson({ message: unknownMessage }, program, recoveryCommandDescriptors) : await formatCommanderUsageMessage({ message: unknownMessage }, program, recoveryCommandDescriptors);
+  await finishRunPmCliFailure({
+    errorMessage: unknownMessage,
+    exitCode: EXIT_CODE.USAGE,
+    classificationCode: classification.code,
+    errorCategory,
+    commandResolution,
+    resolutionStage: "parse"
+  });
+  printError(renderedUsage);
+  if (loggedHandledErrorToSentry) {
+    await sentryFlush(HANDLED_ERROR_SENTRY_FLUSH_TIMEOUT_MS);
+  }
+  process.exitCode = EXIT_CODE.USAGE;
+}
+async function handleRunPmCliHelpDisplayError(context, code, rawMessage) {
+  const isHelpDisplayCode = code === "commander.helpDisplayed" || code === "commander.help" || code === "commander.helpCommand";
+  if (!isHelpDisplayCode && !rawMessage.includes("(outputHelp)")) {
+    return false;
+  }
+  const helpRequest = parseBootstrapHelpRequest(context.invocationArgv);
+  if (helpRequest.requested && !isKnownHelpCommandPath(program, helpRequest.commandPathTokens)) {
+    await handleUnknownHelpCommandError(context, code);
+    return true;
+  }
+  await finishRunPmCliSuccessParse();
+  return true;
+}
+async function handleRunPmCliCommanderUsageError(context, code) {
+  const usageContext = await resolveCommanderUsageContext(context.error, program, activeRuntimeExtensionCommandDescriptors);
+  const classification = classifyCommanderError(usageContext.message, usageContext.commandName, usageContext.allowedTypes, {
+    unknownCommandExamples: usageContext.unknownCommandExamples,
+    unknownCommandNextSteps: usageContext.unknownCommandNextSteps,
+    attemptedCommand: usageContext.attemptedCommand,
+    normalizedInvocationArgs: usageContext.normalizedInvocationArgs,
+    providedOptionFlags: usageContext.providedOptionFlags,
+    unknownOptionSuggestions: usageContext.unknownOptionSuggestions,
+    suggestedRetryCommand: usageContext.suggestedRetryCommand
+  });
+  const { errorCategory, commandResolution } = await context.emitTelemetryCommandError({
+    command: context.attemptedCommand,
+    errorCode: classification.code,
+    errorMessage: classification.detail,
+    exitCode: EXIT_CODE.USAGE,
+    options: {
+      bootstrap_global_options: context.bootstrapGlobal,
+      commander_code: code
+    },
+    resolutionStage: "parse"
+  });
+  const loggedHandledErrorToSentry = await maybeLogHandledCliErrorToSentry({
+    command: context.attemptedCommand,
+    error_code: classification.code,
+    error_category: errorCategory,
+    exit_code: EXIT_CODE.USAGE,
+    error_message: classification.detail,
+    command_resolution: commandResolution,
+    resolution_stage: "parse",
+    source_context: activeTelemetryCommandContext?.source_context
+  });
+  const renderedUsage = context.jsonErrors ? await formatCommanderUsageJson(context.error, program, activeRuntimeExtensionCommandDescriptors) : await formatCommanderUsageMessage(context.error, program, activeRuntimeExtensionCommandDescriptors);
+  await finishRunPmCliFailure({
+    errorMessage: usageContext.message,
+    exitCode: EXIT_CODE.USAGE,
+    classificationCode: classification.code,
+    errorCategory,
+    commandResolution,
+    resolutionStage: "parse"
+  });
+  printError(renderedUsage);
+  if (loggedHandledErrorToSentry) {
+    await sentryFlush(HANDLED_ERROR_SENTRY_FLUSH_TIMEOUT_MS);
+  }
+  process.exitCode = EXIT_CODE.USAGE;
+}
+function shouldHandleRunPmCliCommanderError(error) {
+  if (typeof error !== "object" || error === null || !("code" in error)) {
+    return false;
+  }
+  const code = error.code;
+  if (typeof code === "string" && (code === "commander.version" || code.startsWith("commander."))) {
+    return true;
+  }
+  const rawMessage = String(error.message ?? "");
+  return rawMessage.includes("(outputHelp)");
+}
+async function handleRunPmCliCommanderError(context) {
+  const code = context.error.code;
+  const rawMessage = String(context.error.message ?? "");
+  if (await handleRunPmCliHelpDisplayError(context, code, rawMessage)) {
+    return;
+  }
+  if (code === "commander.version") {
+    await finishRunPmCliSuccessParse();
+    return;
+  }
+  await handleRunPmCliCommanderUsageError(context, code);
+}
+async function handleRunPmCliError(params) {
+  const bootstrapGlobal = parseBootstrapGlobalOptions(params.invocationArgv);
+  const bootstrapPmRoot = resolvePmRoot(process.cwd(), bootstrapGlobal.path);
+  const context = {
+    error: params.error,
+    invocationArgv: params.invocationArgv,
+    bootstrapGlobal,
+    jsonErrors: bootstrapGlobal.json,
+    bootstrapPmRoot,
+    attemptedCommand: parseBootstrapCommandName(params.invocationArgv) ?? "<unknown>",
+    emitTelemetryCommandError: createTelemetryCommandErrorEmitter({
+      invocationArgv: params.invocationArgv,
+      bootstrapGlobal,
+      bootstrapPmRoot
+    })
+  };
+  await prepareExtensionServicesForRunPmCliError({
+    invocationArgv: params.invocationArgv,
+    bootstrapGlobal,
+    bootstrapPmRoot
+  });
+  if (await handleRunPmCliKnownError(context, readThrownExitCode(params.error))) {
+    return;
+  }
+  if (shouldHandleRunPmCliCommanderError(params.error)) {
+    await handleRunPmCliCommanderError(context);
+    return;
+  }
+  await handleGenericRunPmCliError({
+    error: params.error,
+    attemptedCommand: context.attemptedCommand,
+    bootstrapGlobal,
+    emitTelemetryCommandError: context.emitTelemetryCommandError
+  });
+}
 async function runPmCli(rawArgv = process.argv.slice(2)) {
   const bootstrapInvocation = normalizeBootstrapInvocation(rawArgv);
   const invocationArgv = bootstrapInvocation.argv;
@@ -6331,268 +6068,7 @@ async function runPmCli(rawArgv = process.argv.slice(2)) {
     }
     await program.parseAsync(invocationProcessArgv);
   } catch (error) {
-    const bootstrapGlobal = parseBootstrapGlobalOptions(invocationArgv);
-    const jsonErrors = bootstrapGlobal.json;
-    const bootstrapPmRoot = resolvePmRoot(process.cwd(), bootstrapGlobal.path);
-    const attemptedCommand = parseBootstrapCommandName(invocationArgv) ?? "<unknown>";
-    const emitTelemetryCommandError = async (params) => {
-      const errorCategory = resolveTelemetryErrorCategory(params.errorCode);
-      const commandResolution = deriveTelemetryCommandResolution({
-        ok: false,
-        errorCode: params.errorCode,
-        errorCategory
-      });
-      await emitTelemetryErrorEvent({
-        command: params.command,
-        args: invocationArgv,
-        options: params.options,
-        global: bootstrapGlobal,
-        pm_version: CLI_VERSION,
-        pm_root: bootstrapPmRoot,
-        error_code: params.errorCode,
-        error_message: params.errorMessage,
-        exit_code: params.exitCode,
-        error_category: errorCategory,
-        command_resolution: commandResolution,
-        resolution_stage: params.resolutionStage
-      });
-      return {
-        errorCategory,
-        commandResolution
-      };
-    };
-    if (!bootstrapGlobal.noExtensions) {
-      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)) {
-      const errorMessage = describeUnknownError(error);
-      const exitCode = error instanceof PmCliError ? error.exitCode : normalizeThrownExitCode(numericExitCode);
-      const context = error instanceof PmCliError ? error.context : void 0;
-      const enrichedContext = buildPmCliRecoveryContext(context, invocationArgv, errorMessage);
-      const classification = classifyPmCliError(errorMessage, enrichedContext);
-      const renderedError = jsonErrors ? JSON.stringify(formatPmCliErrorForJson(errorMessage, exitCode, enrichedContext), null, 2) : formatPmCliErrorForDisplay(errorMessage, enrichedContext);
-      printError(renderedError);
-      const { errorCategory, commandResolution } = await emitTelemetryCommandError({
-        command: attemptedCommand,
-        errorCode: classification.code,
-        errorMessage: classification.detail,
-        exitCode,
-        options: {
-          bootstrap_global_options: bootstrapGlobal
-        },
-        resolutionStage: "execute"
-      });
-      const loggedHandledErrorToSentry = await maybeLogHandledCliErrorToSentry({
-        command: attemptedCommand,
-        error_code: classification.code,
-        error_category: errorCategory,
-        exit_code: exitCode,
-        error_message: classification.detail,
-        command_resolution: commandResolution,
-        resolution_stage: "execute",
-        source_context: activeTelemetryCommandContext?.source_context
-      });
-      sentryFinishCommandSpan(false, errorMessage, {
-        error_code: classification.code,
-        error_category: errorCategory,
-        exit_code: exitCode,
-        command_resolution: commandResolution,
-        resolution_stage: "execute"
-      });
-      await runAndClearAfterCommandHooks({
-        ok: false,
-        error: errorMessage,
-        exit_code: exitCode,
-        error_code: classification.code,
-        error_category: errorCategory,
-        command_resolution: commandResolution,
-        resolution_stage: "execute"
-      });
-      if (loggedHandledErrorToSentry) {
-        sentryCaptureCliError(wrapThrownErrorForSentry(error, errorMessage));
-      }
-      if (loggedHandledErrorToSentry) {
-        await sentryFlush(HANDLED_ERROR_SENTRY_FLUSH_TIMEOUT_MS);
-      }
-      process.exitCode = exitCode;
-      return;
-    }
-    if (typeof error === "object" && error !== null && "code" in error) {
-      const code = error.code;
-      const rawMessage = typeof error.message === "string" ? error.message ?? "" : "";
-      const isHelpDisplayCode = code === "commander.helpDisplayed" || code === "commander.help" || code === "commander.helpCommand";
-      if (isHelpDisplayCode || rawMessage.includes("(outputHelp)")) {
-        const helpRequest = parseBootstrapHelpRequest(invocationArgv);
-        if (helpRequest.requested && !isKnownHelpCommandPath(program, helpRequest.commandPathTokens)) {
-          const unknownToken = helpRequest.commandPathTokens[0] ?? parseBootstrapCommandName(invocationArgv) ?? "<command>";
-          const unknownMessage = `unknown command '${unknownToken}'`;
-          const recoveryCommandDescriptors = await loadRuntimeExtensionCommandDescriptorsForRecovery(resolvePmRoot(process.cwd(), bootstrapGlobal.path));
-          const usageContext = await resolveCommanderUsageContext({ message: unknownMessage }, program, recoveryCommandDescriptors);
-          const classification = classifyCommanderError(usageContext.message, usageContext.commandName, usageContext.allowedTypes, {
-            unknownCommandExamples: usageContext.unknownCommandExamples,
-            unknownCommandNextSteps: usageContext.unknownCommandNextSteps,
-            attemptedCommand: usageContext.attemptedCommand,
-            normalizedInvocationArgs: usageContext.normalizedInvocationArgs,
-            providedOptionFlags: usageContext.providedOptionFlags,
-            unknownOptionSuggestions: usageContext.unknownOptionSuggestions,
-            suggestedRetryCommand: usageContext.suggestedRetryCommand
-          });
-          const { errorCategory, commandResolution } = await emitTelemetryCommandError({
-            command: unknownToken,
-            errorCode: classification.code,
-            errorMessage: classification.detail,
-            exitCode: EXIT_CODE.USAGE,
-            options: {
-              bootstrap_global_options: bootstrapGlobal,
-              commander_code: code ?? "commander.helpDisplayed"
-            },
-            resolutionStage: "parse"
-          });
-          const loggedHandledErrorToSentry = await maybeLogHandledCliErrorToSentry({
-            command: unknownToken,
-            error_code: classification.code,
-            error_category: errorCategory,
-            exit_code: EXIT_CODE.USAGE,
-            error_message: classification.detail,
-            command_resolution: commandResolution,
-            resolution_stage: "parse",
-            source_context: activeTelemetryCommandContext?.source_context
-          });
-          const renderedUsage = jsonErrors ? await formatCommanderUsageJson({ message: unknownMessage }, program, recoveryCommandDescriptors) : await formatCommanderUsageMessage({ message: unknownMessage }, program, recoveryCommandDescriptors);
-          sentryFinishCommandSpan(false, unknownMessage, {
-            error_code: classification.code,
-            error_category: errorCategory,
-            exit_code: EXIT_CODE.USAGE,
-            command_resolution: commandResolution,
-            resolution_stage: "parse"
-          });
-          await runAndClearAfterCommandHooks({
-            ok: false,
-            error: unknownMessage,
-            exit_code: EXIT_CODE.USAGE,
-            error_code: classification.code,
-            error_category: errorCategory,
-            command_resolution: commandResolution,
-            resolution_stage: "parse"
-          });
-          if (jsonErrors) {
-            printError(renderedUsage);
-          } else {
-            printError(renderedUsage);
-          }
-          if (loggedHandledErrorToSentry) {
-            await sentryFlush(HANDLED_ERROR_SENTRY_FLUSH_TIMEOUT_MS);
-          }
-          process.exitCode = EXIT_CODE.USAGE;
-          return;
-        }
-        sentryFinishCommandSpan(true, void 0, {
-          exit_code: EXIT_CODE.SUCCESS,
-          command_resolution: "success",
-          resolution_stage: "parse"
-        });
-        await runAndClearAfterCommandHooks({
-          ok: true,
-          exit_code: EXIT_CODE.SUCCESS,
-          command_resolution: "success",
-          resolution_stage: "parse"
-        });
-        process.exitCode = EXIT_CODE.SUCCESS;
-        return;
-      }
-      if (code === "commander.version") {
-        sentryFinishCommandSpan(true, void 0, {
-          exit_code: EXIT_CODE.SUCCESS,
-          command_resolution: "success",
-          resolution_stage: "parse"
-        });
-        await runAndClearAfterCommandHooks({
-          ok: true,
-          exit_code: EXIT_CODE.SUCCESS,
-          command_resolution: "success",
-          resolution_stage: "parse"
-        });
-        process.exitCode = EXIT_CODE.SUCCESS;
-        return;
-      }
-      if (code?.startsWith("commander.")) {
-        const usageContext = await resolveCommanderUsageContext(error, program, activeRuntimeExtensionCommandDescriptors);
-        const classification = classifyCommanderError(usageContext.message, usageContext.commandName, usageContext.allowedTypes, {
-          unknownCommandExamples: usageContext.unknownCommandExamples,
-          unknownCommandNextSteps: usageContext.unknownCommandNextSteps,
-          attemptedCommand: usageContext.attemptedCommand,
-          normalizedInvocationArgs: usageContext.normalizedInvocationArgs,
-          providedOptionFlags: usageContext.providedOptionFlags,
-          unknownOptionSuggestions: usageContext.unknownOptionSuggestions,
-          suggestedRetryCommand: usageContext.suggestedRetryCommand
-        });
-        const { errorCategory, commandResolution } = await emitTelemetryCommandError({
-          command: attemptedCommand,
-          errorCode: classification.code,
-          errorMessage: classification.detail,
-          exitCode: EXIT_CODE.USAGE,
-          options: {
-            bootstrap_global_options: bootstrapGlobal,
-            commander_code: code
-          },
-          resolutionStage: "parse"
-        });
-        const loggedHandledErrorToSentry = await maybeLogHandledCliErrorToSentry({
-          command: attemptedCommand,
-          error_code: classification.code,
-          error_category: errorCategory,
-          exit_code: EXIT_CODE.USAGE,
-          error_message: classification.detail,
-          command_resolution: commandResolution,
-          resolution_stage: "parse",
-          source_context: activeTelemetryCommandContext?.source_context
-        });
-        const renderedUsage = jsonErrors ? await formatCommanderUsageJson(error, program, activeRuntimeExtensionCommandDescriptors) : await formatCommanderUsageMessage(error, program, activeRuntimeExtensionCommandDescriptors);
-        sentryFinishCommandSpan(false, usageContext.message, {
-          error_code: classification.code,
-          error_category: errorCategory,
-          exit_code: EXIT_CODE.USAGE,
-          command_resolution: commandResolution,
-          resolution_stage: "parse"
-        });
-        await runAndClearAfterCommandHooks({
-          ok: false,
-          error: usageContext.message,
-          exit_code: EXIT_CODE.USAGE,
-          error_code: classification.code,
-          error_category: errorCategory,
-          command_resolution: commandResolution,
-          resolution_stage: "parse"
-        });
-        if (jsonErrors) {
-          printError(renderedUsage);
-        } else {
-          printError(renderedUsage);
-        }
-        if (loggedHandledErrorToSentry) {
-          await sentryFlush(HANDLED_ERROR_SENTRY_FLUSH_TIMEOUT_MS);
-        }
-        process.exitCode = EXIT_CODE.USAGE;
-        return;
-      }
-    }
-    await handleGenericRunPmCliError({
-      error,
-      attemptedCommand,
-      bootstrapGlobal,
-      emitTelemetryCommandError
-    });
+    await handleRunPmCliError({ error, invocationArgv });
   }
 }
 var _testOnly = {
@@ -6631,6 +6107,12 @@ var _testOnly = {
   extensionProvidesTemplatesRuntime,
   hasAnyCapability,
   handleGenericRunPmCliError,
+  handleRunPmCliCommanderError,
+  handleRunPmCliError,
+  handleRunPmCliHelpDisplayError,
+  handleRunPmCliKnownError,
+  handleRunPmCliCommanderUsageError,
+  handleUnknownHelpCommandError,
   inferMissingFieldsFromErrorMessage,
   inferPostActionErrorCode,
   inferPostActionFailureMessage,
@@ -6647,12 +6129,14 @@ var _testOnly = {
   normalizeTelemetryResolutionStage,
   normalizeThrownExitCode,
   probeUsesAnyFlag,
+  prepareExtensionServicesForRunPmCliError,
   readRecordBoolean,
   readRecordNumber,
   readRecordString,
   registerDynamicExtensionCommandPaths,
   registerRuntimeSchemaFieldFlags,
   resolveCoreCommandRegistrationSelection,
+  resolveUnknownHelpToken,
   readThrownExitCode,
   runAndClearAfterCommandHooks,
   runRequiredExtensionCommand,
@@ -6660,8 +6144,10 @@ var _testOnly = {
   shouldLogHandledErrorToSentry,
   shouldRegisterDynamicExtensionPaths,
   shouldRegisterRuntimeSchemaFlags,
+  shouldHandleRunPmCliCommanderError,
   setActiveExtensionHookContextForTest,
   setActiveRuntimeExtensionCommandDescriptorsForTest,
+  setRecoveredExtensionServices,
   toLooseFieldDefinitionType,
   isImporterOrExporterCommandPath,
   validateDynamicExtensionCommandInvocation,