@unbrained/pm-cli 2026.7.1 → 2026.7.3

package/dist/cli-bundle/main.js

@@ -5,10 +5,10 @@ import {
   emitTelemetryErrorEvent,
   finishTelemetryCommand,
   startTelemetryCommand
-} from "./chunks/chunk-GJ326ZKX.js";
+} from "./chunks/chunk-ER4ME5U2.js";
 import {
   migrateItemFilesToFormat
-} from "./chunks/chunk-NKZAN7BD.js";
+} from "./chunks/chunk-5IZUBZBR.js";
 import {
   applyDefaultOutputFormat,
   clearResolvedGlobalOptions,
@@ -18,13 +18,13 @@ import {
   getGlobalOptions,
   invalidateSearchCachesForMutation,
   setResolvedGlobalOptions
-} from "./chunks/chunk-3J6JRJ3I.js";
+} from "./chunks/chunk-HB4FAT3O.js";
 import {
   printError,
   printResult,
   writeStdout
-} from "./chunks/chunk-BDTISOSD.js";
-import "./chunks/chunk-4DSGXSBL.js";
+} from "./chunks/chunk-EQURFOMH.js";
+import "./chunks/chunk-XRYSCRZR.js";
 import {
   EXECUTABLE_COMMAND_ALIASES,
   applyBootstrapPagerPolicy,
@@ -35,14 +35,14 @@ import {
   parseBootstrapHelpRequest,
   parseBootstrapTypeValue,
   stripGlobalBootstrapTokens
-} from "./chunks/chunk-RH5ZBYFD.js";
+} from "./chunks/chunk-T6AXEBOP.js";
 import {
   PM_CORE_COMMAND_NAMES,
   resolveSubcommandFlagContractsForCommand
-} from "./chunks/chunk-MDPEOIGN.js";
-import "./chunks/chunk-3K2M5OYU.js";
-import "./chunks/chunk-BHO33VBQ.js";
-import "./chunks/chunk-WYDHYJPO.js";
+} from "./chunks/chunk-RAHINBVP.js";
+import "./chunks/chunk-6KRFL33E.js";
+import "./chunks/chunk-3W2HJKJX.js";
+import "./chunks/chunk-AJHYQCBJ.js";
 import {
   BUILTIN_ITEM_TYPE_VALUES,
   EXIT_CODE,
@@ -90,7 +90,7 @@ import {
   setActiveExtensionServices,
   toNonEmptyStringOrUndefined,
   writeSettings
-} from "./chunks/chunk-RVUALSJF.js";
+} from "./chunks/chunk-KHVGM5CS.js";
 
 // dist/cli/main.js
 import { Command } from "commander";
@@ -191,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) {
   }
 })();
@@ -356,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;
@@ -400,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) {
@@ -487,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) {
   }
 })();
@@ -501,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)
@@ -552,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;
@@ -1909,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] = "8fc55c5b-a16f-5087-814e-4c58f90d7f1a");
   } catch (e2) {
   }
 })();
@@ -1959,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);
@@ -2027,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) {
@@ -2201,13 +2198,16 @@ function buildFallbackTitleFromMessage(message) {
   }
   return `${firstLine.slice(0, 117)}...`;
 }
+function normalizeContextValue(value, fallback) {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : fallback;
+}
 function applyPmCliErrorContext(guidance, rawMessage, context) {
   if (!context) {
     return guidance;
   }
   const normalizedRawMessage = normalizeMessage(rawMessage);
-  const code = typeof context.code === "string" && context.code.trim().length > 0 ? context.code.trim() : guidance.code;
-  const type = typeof context.type === "string" && context.type.trim().length > 0 ? context.type.trim() : errorType(code);
+  const code = normalizeContextValue(context.code, guidance.code);
+  const type = normalizeContextValue(context.type, errorType(code));
   const examples = normalizeContextList(context.examples) ?? guidance.examples;
   const nextSteps = normalizeContextList(context.nextSteps) ?? guidance.nextSteps;
   const fallbackTitle = guidance.code === "command_failed" && context.code ? buildFallbackTitleFromMessage(normalizedRawMessage) : void 0;
@@ -2218,140 +2218,165 @@ function applyPmCliErrorContext(guidance, rawMessage, context) {
     type,
     title: fallbackTitle ?? guidance.title,
     happened: normalizedRawMessage.length > 0 ? normalizedRawMessage : guidance.happened,
-    required: typeof context.required === "string" && context.required.trim().length > 0 ? context.required.trim() : guidance.required,
-    why: typeof context.why === "string" && context.why.trim().length > 0 ? context.why.trim() : guidance.why,
+    required: normalizeContextValue(context.required, guidance.required),
+    why: normalizeContextValue(context.why, guidance.why),
     examples,
     nextSteps,
     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",
@@ -2471,147 +2496,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",
@@ -2695,7 +2746,7 @@ function createLazyModule(importer) {
 !(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] = "c2d84713-bde8-5ed0-9975-41d50fb0be76");
+    n && (e._sentryDebugIds = e._sentryDebugIds || {}, e._sentryDebugIds[n] = "f4bd09b9-2429-5af4-9f71-f2a7fe58f0d1");
   } catch (e2) {
   }
 })();
@@ -2814,7 +2865,7 @@ function normalizeExtensionCommandArguments(values) {
     return normalized;
   }).filter((entry) => entry !== null);
 }
-function collectExtensionCommandHelpDescriptors(commandHandlers, commandDefinitions, flagRegistrations) {
+function collectExtensionDefinitionsByCommand(commandDefinitions) {
   const definitionsByCommand = /* @__PURE__ */ new Map();
   for (const definition of commandDefinitions) {
     const commandPath = normalizeExtensionCommandPath(definition.command);
@@ -2839,6 +2890,9 @@ function collectExtensionCommandHelpDescriptors(commandHandlers, commandDefiniti
       }
     });
   }
+  return definitionsByCommand;
+}
+function collectExtensionFlagsByCommand(flagRegistrations) {
   const flagsByCommand = /* @__PURE__ */ new Map();
   for (const registration of flagRegistrations) {
     const commandPath = normalizeExtensionCommandPath(registration.target_command);
@@ -2849,6 +2903,9 @@ function collectExtensionCommandHelpDescriptors(commandHandlers, commandDefiniti
     existing.push(...registration.flags);
     flagsByCommand.set(commandPath, existing);
   }
+  return flagsByCommand;
+}
+function collectExtensionHelpCommandSet(commandHandlers, definitionsByCommand, flagsByCommand) {
   const commandSet = /* @__PURE__ */ new Set();
   for (const commandPath of commandHandlers) {
     const normalized = normalizeExtensionCommandPath(commandPath);
@@ -2862,6 +2919,12 @@ function collectExtensionCommandHelpDescriptors(commandHandlers, commandDefiniti
   for (const commandPath of flagsByCommand.keys()) {
     commandSet.add(commandPath);
   }
+  return commandSet;
+}
+function collectExtensionCommandHelpDescriptors(commandHandlers, commandDefinitions, flagRegistrations) {
+  const definitionsByCommand = collectExtensionDefinitionsByCommand(commandDefinitions);
+  const flagsByCommand = collectExtensionFlagsByCommand(flagRegistrations);
+  const commandSet = collectExtensionHelpCommandSet(commandHandlers, definitionsByCommand, flagsByCommand);
   const descriptors = /* @__PURE__ */ new Map();
   const sortedCommands = [...commandSet].sort((left, right) => left.localeCompare(right));
   for (const commandPath of sortedCommands) {
@@ -2897,7 +2960,7 @@ function applyDynamicExtensionArguments(command, descriptor) {
     command.argument(buildExtensionArgumentToken(argument), argument.description ?? "Extension argument.");
   }
 }
-function formatDynamicExtensionOptionFlags(definition) {
+function normalizeDynamicExtensionOptionNames(definition) {
   const visible = toOptionalBoolean(definition.visible);
   if (visible === false) {
     return null;
@@ -2906,31 +2969,27 @@ function formatDynamicExtensionOptionFlags(definition) {
   const shortName = toNonEmptyFlagString(definition.short);
   const normalizedShort = shortName && shortName.startsWith("-") && !shortName.startsWith("--") ? shortName : null;
   const normalizedLong = longName && longName.startsWith("--") && longName.length > 2 ? longName : null;
-  if (!normalizedLong && !normalizedShort) {
+  const optionNames = [normalizedShort, normalizedLong].filter((entry) => entry !== null);
+  return optionNames.length > 0 ? optionNames : null;
+}
+function formatDynamicExtensionOptionFlags(definition) {
+  const optionNames = normalizeDynamicExtensionOptionNames(definition);
+  if (!optionNames) {
     return null;
   }
   const optionValueName = toNonEmptyFlagString(definition.value_name);
   const optionValueSuffix = optionValueName ? ` <${optionValueName}>` : "";
-  const optionNames = [normalizedShort, normalizedLong].filter((entry) => entry !== null);
   return `${optionNames.join(", ")}${optionValueSuffix}`;
 }
 function formatDynamicExtensionParseOptionFlags(definition) {
-  const visible = toOptionalBoolean(definition.visible);
-  if (visible === false) {
-    return null;
-  }
-  const longName = toNonEmptyFlagString(definition.long);
-  const shortName = toNonEmptyFlagString(definition.short);
-  const normalizedShort = shortName && shortName.startsWith("-") && !shortName.startsWith("--") ? shortName : null;
-  const normalizedLong = longName && longName.startsWith("--") && longName.length > 2 ? longName : null;
-  if (!normalizedLong && !normalizedShort) {
+  const optionNames = normalizeDynamicExtensionOptionNames(definition);
+  if (!optionNames) {
     return null;
   }
   const valueType = toNonEmptyFlagString(definition.value_type) ?? toNonEmptyFlagString(definition.type);
   const valueName = toNonEmptyFlagString(definition.value_name);
   const requiresValue = valueType !== "boolean" && (valueName !== null || valueType !== null || toOptionalBoolean(definition.required) === true);
   const valueSuffix = requiresValue ? ` <${valueName ?? "value"}>` : "";
-  const optionNames = [normalizedShort, normalizedLong].filter((entry) => entry !== null);
   return `${optionNames.join(", ")}${valueSuffix}`;
 }
 function formatDynamicExtensionOptionDescription(definition) {
@@ -3114,7 +3173,7 @@ function ensureCommandPath(root, pathParts) {
 !(function() {
   try {
     var e = "undefined" != typeof window ? window : "undefined" != typeof global ? global : "undefined" != typeof globalThis ? globalThis : "undefined" != typeof self ? self : {}, n = new e.Error().stack;
-    n && (e._sentryDebugIds = e._sentryDebugIds || {}, e._sentryDebugIds[n] = "3f652b37-a8f5-5d02-9199-d2982382b7a8");
+    n && (e._sentryDebugIds = e._sentryDebugIds || {}, e._sentryDebugIds[n] = "e5659f1c-76e6-52e9-96f6-201091483918");
   } catch (e2) {
   }
 })();
@@ -3166,52 +3225,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) {
@@ -3256,7 +3292,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] = "7d27d900-2792-5dba-95dc-262d72ce028e");
   } catch (e2) {
   }
 })();
@@ -3539,22 +3575,9 @@ function rewriteUnknownOptionArgv(argv, unknownOption, replacementFlag) {
   }
   return void 0;
 }
-function buildUnknownCommandGuidanceFromRuntime(rawMessage, root, extensionDescriptors) {
-  const unknownCommandMatch = rawMessage.match(/unknown command '([^']+)'/i);
-  if (!unknownCommandMatch || typeof unknownCommandMatch[1] !== "string") {
-    return void 0;
-  }
-  const normalizedUnknown = normalizeHelpCommandPath(unknownCommandMatch[1]);
-  if (normalizedUnknown.length === 0) {
-    return void 0;
-  }
-  const commandPaths = collectRuntimeCommandPaths(root, extensionDescriptors);
-  if (commandPaths.length === 0) {
-    return void 0;
-  }
-  const primaryToken = normalizedUnknown.split(" ")[0];
-  const commandPathSet = new Set(commandPaths);
-  const scoreAgainstUnknown = (candidatePath) => Math.min(scoreCommandPathMatch(candidatePath, normalizedUnknown), primaryToken !== normalizedUnknown ? scoreCommandPathMatch(candidatePath, primaryToken) : Number.POSITIVE_INFINITY);
+function scoreRuntimeCommandCandidates(params) {
+  const commandPathSet = new Set(params.commandPaths);
+  const scoreAgainstUnknown = (candidatePath) => Math.min(scoreCommandPathMatch(candidatePath, params.normalizedUnknown), params.primaryToken !== params.normalizedUnknown ? scoreCommandPathMatch(candidatePath, params.primaryToken) : Number.POSITIVE_INFINITY);
   const scoresByCommandPath = /* @__PURE__ */ new Map();
   const recordCandidateScore = (commandPath, score) => {
     if (!Number.isFinite(score) || !commandPathSet.has(commandPath)) {
@@ -3565,22 +3588,55 @@ function buildUnknownCommandGuidanceFromRuntime(rawMessage, root, extensionDescr
       scoresByCommandPath.set(commandPath, score);
     }
   };
-  for (const commandPath of commandPaths) {
+  for (const commandPath of params.commandPaths) {
     recordCandidateScore(commandPath, scoreAgainstUnknown(commandPath));
   }
   for (const [aliasToken, canonicalPath] of Object.entries(EXECUTABLE_COMMAND_ALIASES)) {
     recordCandidateScore(canonicalPath, scoreAgainstUnknown(aliasToken));
   }
-  const rankedCandidates = [...scoresByCommandPath.entries()].sort(([leftPath, leftScore], [rightPath, rightScore]) => leftScore !== rightScore ? leftScore - rightScore : leftPath.localeCompare(rightPath)).map(([commandPath]) => commandPath);
-  const installedPackageCandidates = collectInstalledPackageCommandPathHints(primaryToken, extensionDescriptors).filter((commandPath) => commandPaths.includes(commandPath));
-  const combinedCandidates = dedupeStrings2([...rankedCandidates, ...installedPackageCandidates]);
-  const fallbackTopLevel = [...new Set(commandPaths.map((commandPath) => commandPath.split(" ")[0]).filter((segment) => segment.length > 0))];
-  fallbackTopLevel.sort((left, right) => left.localeCompare(right));
-  const suggestedPaths = (combinedCandidates.length > 0 ? combinedCandidates : fallbackTopLevel).slice(0, 3);
+  return [...scoresByCommandPath.entries()].sort(([leftPath, leftScore], [rightPath, rightScore]) => leftScore !== rightScore ? leftScore - rightScore : leftPath.localeCompare(rightPath)).map(([commandPath]) => commandPath);
+}
+function resolveUnknownCommandCandidates(params) {
+  const rankedCandidates = scoreRuntimeCommandCandidates(params);
+  const installedPackageCandidates = collectInstalledPackageCommandPathHints(params.primaryToken, params.extensionDescriptors).filter((commandPath) => params.commandPaths.includes(commandPath));
+  return dedupeStrings2([...rankedCandidates, ...installedPackageCandidates]);
+}
+function resolveUnknownCommandFallbacks(commandPaths) {
+  const topLevel = [...new Set(commandPaths.map((commandPath) => commandPath.split(" ")[0]).filter((segment) => segment.length > 0))];
+  return topLevel.sort((left, right) => left.localeCompare(right));
+}
+function buildUnknownCommandExamples(suggestedPaths, hasConcreteCandidates) {
   const suggestedExamples = suggestedPaths.map((path) => `pm ${path} --help`);
-  const examples = combinedCandidates.length > 0 ? [.../* @__PURE__ */ new Set([...suggestedExamples, "pm --help"])] : [.../* @__PURE__ */ new Set(["pm --help", ...suggestedExamples])];
+  if (hasConcreteCandidates) {
+    return [.../* @__PURE__ */ new Set([...suggestedExamples, "pm --help"])];
+  }
+  return [.../* @__PURE__ */ new Set(["pm --help", ...suggestedExamples])];
+}
+function buildUnknownCommandGuidanceFromRuntime(rawMessage, root, extensionDescriptors) {
+  const unknownCommandMatch = rawMessage.match(/unknown command '([^']+)'/i);
+  if (!unknownCommandMatch || typeof unknownCommandMatch[1] !== "string") {
+    return void 0;
+  }
+  const normalizedUnknown = normalizeHelpCommandPath(unknownCommandMatch[1]);
+  if (normalizedUnknown.length === 0) {
+    return void 0;
+  }
+  const commandPaths = collectRuntimeCommandPaths(root, extensionDescriptors);
+  if (commandPaths.length === 0) {
+    return void 0;
+  }
+  const primaryToken = normalizedUnknown.split(" ")[0];
+  const combinedCandidates = resolveUnknownCommandCandidates({
+    commandPaths,
+    normalizedUnknown,
+    primaryToken,
+    extensionDescriptors
+  });
+  const fallbackTopLevel = resolveUnknownCommandFallbacks(commandPaths);
+  const suggestedPaths = (combinedCandidates.length > 0 ? combinedCandidates : fallbackTopLevel).slice(0, 3);
+  const examples = buildUnknownCommandExamples(suggestedPaths, combinedCandidates.length > 0);
   const optionalPackageHint = resolveOptionalPackageInstallHint(normalizedUnknown);
-  const didYouMean = combinedCandidates.length > 0 ? `Did you mean: ${combinedCandidates.slice(0, 3).join(", ")}?` : null;
+  const didYouMean = combinedCandidates.length > 0 ? `Did you mean: ${suggestedPaths.join(", ")}?` : null;
   return {
     unknownCommandExamples: examples,
     unknownCommandNextSteps: [
@@ -3641,6 +3697,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";
@@ -3649,42 +3747,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,
@@ -3692,8 +3758,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
   };
@@ -3740,7 +3806,7 @@ async function formatCommanderUsageJson(error, rootProgram, extensionDescriptors
 !(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] = "913c0a00-924f-520e-adb6-4073fdb73413");
+    n && (e._sentryDebugIds = e._sentryDebugIds || {}, e._sentryDebugIds[n] = "4daddb64-a9f8-5131-92be-05d37fd24cf8");
   } catch (e2) {
   }
 })();
@@ -3873,20 +3939,26 @@ function buildHelpSubcommandSummaries(command) {
     description: entry.description().trim()
   })).sort((left, right) => left.name.localeCompare(right.name));
 }
+function buildJsonHelpNarrative(detailMode, fallbackNarrative, extensionDescriptor) {
+  if (!extensionDescriptor) {
+    return fallbackNarrative;
+  }
+  const extensionExamples = extensionDescriptor.examples ?? [];
+  const extensionFailureHints = extensionDescriptor.failure_hints ?? [];
+  return {
+    intent: extensionDescriptor.intent ?? extensionDescriptor.description ?? fallbackNarrative.intent,
+    examples: detailMode === "detailed" ? extensionExamples.length > 0 ? [...extensionExamples] : [...fallbackNarrative.examples] : extensionExamples.length > 0 ? [extensionExamples[0]] : [...fallbackNarrative.examples],
+    tips: detailMode === "detailed" ? extensionFailureHints.length > 0 ? [...extensionFailureHints] : [...fallbackNarrative.tips] : [],
+    detail_mode: detailMode
+  };
+}
 function buildJsonHelpPayload(rootProgram, targetCommand, argv, requestedPath, extensionDescriptors) {
   const detailMode = resolveHelpDetailMode(argv);
   const resolvedPath = normalizeHelpCommandPath(getCommandPath(targetCommand));
   const commandPath = resolvedPath.length > 0 ? resolvedPath : void 0;
   const fallbackNarrative = resolveHelpNarrative(commandPath, detailMode);
   const extensionDescriptor = commandPath ? extensionDescriptors.get(commandPath) : void 0;
-  const extensionExamples = extensionDescriptor?.examples ?? [];
-  const extensionFailureHints = extensionDescriptor?.failure_hints ?? [];
-  const narrative = extensionDescriptor ? {
-    intent: extensionDescriptor.intent ?? extensionDescriptor.description ?? fallbackNarrative.intent,
-    examples: detailMode === "detailed" ? extensionExamples.length > 0 ? [...extensionExamples] : [...fallbackNarrative.examples] : extensionExamples.length > 0 ? [extensionExamples[0]] : [...fallbackNarrative.examples],
-    tips: detailMode === "detailed" ? extensionFailureHints.length > 0 ? [...extensionFailureHints] : [...fallbackNarrative.tips] : [],
-    detail_mode: detailMode
-  } : fallbackNarrative;
+  const narrative = buildJsonHelpNarrative(detailMode, fallbackNarrative, extensionDescriptor);
   const optionSummaries = compactHelpOptionAliases(mergeHelpOptionSummaries(buildHelpOptionSummaries(targetCommand), buildDynamicExtensionHelpOptionSummaries(extensionDescriptor)));
   const subcommands = buildHelpSubcommandSummaries(targetCommand);
   return {
@@ -3939,20 +4011,39 @@ async function maybeRenderBootstrapJsonHelp(rootProgram, argv, extensionDescript
   process.exitCode = EXIT_CODE.SUCCESS;
   return true;
 }
+function buildCreateUpdatePolicyIntro(commandName, typeRegistry) {
+  const lines = [
+    "",
+    "Type-aware option policies:",
+    "  pass --type <value> with --help to render required/disabled/hidden option policy details for that type.",
+    `  active type values: ${typeRegistry.types.join("|")}`
+  ];
+  if (commandName === "create") {
+    lines.push("  scheduling shortcut: use --schedule-preset lightweight for Reminder/Meeting/Event minimal create flows.");
+  }
+  return lines.join("\n");
+}
+function appendTypeOptionHelpLines(lines, typeDefinition) {
+  if (typeDefinition.options.length === 0) {
+    lines.push("  type options: none");
+    return;
+  }
+  lines.push("  type options:");
+  for (const option of typeDefinition.options) {
+    const requiredLabel = option.required ? " (required)" : "";
+    const aliases = option.aliases ?? [];
+    lines.push(`    - ${option.key}${requiredLabel}`);
+    lines.push(`      values: ${option.values.length > 0 ? option.values.join("|") : "any non-empty string"}`);
+    lines.push(`      aliases: ${aliases.length > 0 ? aliases.join("|") : "none"}`);
+    if (option.description && option.description.trim().length > 0) {
+      lines.push(`      description: ${option.description.trim()}`);
+    }
+  }
+}
 function buildCreateUpdatePolicyHelpText(commandName, typeRegistry, argv) {
   const selectedTypeRaw = parseBootstrapTypeValue(argv);
   if (!selectedTypeRaw) {
-    const allowed = typeRegistry.types.join("|");
-    const lines2 = [
-      "",
-      "Type-aware option policies:",
-      "  pass --type <value> with --help to render required/disabled/hidden option policy details for that type.",
-      `  active type values: ${allowed}`
-    ];
-    if (commandName === "create") {
-      lines2.push("  scheduling shortcut: use --schedule-preset lightweight for Reminder/Meeting/Event minimal create flows.");
-    }
-    return lines2.join("\n");
+    return buildCreateUpdatePolicyIntro(commandName, typeRegistry);
   }
   const typeDefinition = resolveTypeDefinition(selectedTypeRaw, typeRegistry);
   if (!typeDefinition) {
@@ -3977,21 +4068,7 @@ function buildCreateUpdatePolicyHelpText(commandName, typeRegistry, argv) {
     lines.push("  schedule preset: --schedule-preset lightweight switches schedule artifacts to progressive required-option policy.");
     lines.push("  strict parity remains available via --create-mode strict.");
   }
-  if (typeDefinition.options.length === 0) {
-    lines.push("  type options: none");
-  } else {
-    lines.push("  type options:");
-    for (const option of typeDefinition.options) {
-      const requiredLabel = option.required ? " (required)" : "";
-      const aliases = option.aliases ?? [];
-      lines.push(`    - ${option.key}${requiredLabel}`);
-      lines.push(`      values: ${option.values.length > 0 ? option.values.join("|") : "any non-empty string"}`);
-      lines.push(`      aliases: ${aliases.length > 0 ? aliases.join("|") : "none"}`);
-      if (option.description && option.description.trim().length > 0) {
-        lines.push(`      description: ${option.description.trim()}`);
-      }
-    }
-  }
+  appendTypeOptionHelpLines(lines, typeDefinition);
   if (policyState.errors.length > 0) {
     lines.push(`  config errors: ${policyState.errors.join("; ")}`);
   }
@@ -4013,7 +4090,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] = "aa682568-77f6-5659-a6dd-3a69dd4e1fc0");
   } catch (e2) {
   }
 })();
@@ -4058,10 +4135,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-ZKJ53RS7.js"));
-var loadListQueryRegistrationModule = createLazyModule(() => import("./chunks/register-list-query-SNG5PGA4.js"));
-var loadMutationRegistrationModule = createLazyModule(() => import("./chunks/register-mutation-KK7PHYYU.js"));
-var loadOperationRegistrationModule = createLazyModule(() => import("./chunks/register-operations-HZ6XERQG.js"));
+var loadSetupRegistrationModule = createLazyModule(() => import("./chunks/register-setup-3QJY43CY.js"));
+var loadListQueryRegistrationModule = createLazyModule(() => import("./chunks/register-list-query-ELBHCCFI.js"));
+var loadMutationRegistrationModule = createLazyModule(() => import("./chunks/register-mutation-ROFE2YPC.js"));
+var loadOperationRegistrationModule = createLazyModule(() => import("./chunks/register-operations-IADFVH53.js"));
 function describeUnknownError(error) {
   if (error instanceof PmCliError) {
     return error.message;
@@ -4107,6 +4184,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;
@@ -4119,37 +4247,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
@@ -4480,8 +4587,11 @@ function collectExtensionFlagDefinitionsForInvocation(registrations, commandPath
   }
   return nestedMatch.length > 0 ? nestedMatch : exact;
 }
+function dynamicCommandArguments(descriptor) {
+  return descriptor.arguments ?? [];
+}
 function formatDynamicCommandUsage(descriptor) {
-  const argumentSuffix = descriptor.arguments.map((argument) => {
+  const argumentSuffix = dynamicCommandArguments(descriptor).map((argument) => {
     const label = argument.variadic ? `${argument.name}...` : argument.name;
     return argument.required ? `<${label}>` : `[${label}]`;
   }).join(" ");
@@ -4495,10 +4605,12 @@ function isImporterOrExporterCommandPath(registrations, commandPath) {
   return registrations.importers.some((entry) => normalizeExtensionCommandPath(`${entry.importer} import`) === normalized) || registrations.exporters.some((entry) => normalizeExtensionCommandPath(`${entry.exporter} export`) === normalized);
 }
 function validateDynamicExtensionCommandArgs(descriptor, args) {
-  const requiredCount = descriptor.arguments.filter((argument) => argument.required).length;
-  const variadic = descriptor.arguments.some((argument) => argument.variadic);
-  const maxCount = variadic ? Number.POSITIVE_INFINITY : descriptor.arguments.length;
-  const hintSuffix = descriptor.failure_hints.length > 0 ? ` ${descriptor.failure_hints.join(" ")}` : "";
+  const descriptorArguments = dynamicCommandArguments(descriptor);
+  const requiredCount = descriptorArguments.filter((argument) => argument.required).length;
+  const variadic = descriptorArguments.some((argument) => argument.variadic);
+  const maxCount = variadic ? Number.POSITIVE_INFINITY : descriptorArguments.length;
+  const failureHints = descriptor.failure_hints ?? [];
+  const hintSuffix = failureHints.length > 0 ? ` ${failureHints.join(" ")}` : "";
   if (args.length < requiredCount) {
     throw new PmCliError(`Missing required argument for extension command '${descriptor.command}'. Usage: ${formatDynamicCommandUsage(descriptor)}${hintSuffix}`, EXIT_CODE.USAGE);
   }
@@ -5079,14 +5191,39 @@ async function runRequiredExtensionCommand(command, options, globalOptions, exte
   return extensionCommandResult.result;
 }
 var WRAPPED_ACTION_HANDLER = /* @__PURE__ */ Symbol("pm.wrappedActionHandler");
+function resolveActionCommand(actionArgs, fallback) {
+  const possibleCommand = actionArgs[actionArgs.length - 1];
+  return possibleCommand instanceof Command ? possibleCommand : fallback;
+}
+function maybePrintExtensionProfileWarnings(enabled, label, warnings) {
+  if (enabled && warnings.length > 0) {
+    printError(`profile:extensions ${label}=${formatHookWarnings(warnings)}`);
+  }
+}
+function validateDynamicInvocationArgs(params) {
+  const dynamicDescriptor = activeRuntimeExtensionCommandDescriptors.get(normalizeExtensionCommandPath(params.commandPath));
+  if (!dynamicDescriptor || !isImporterOrExporterCommandPath(params.activeRegistrations, params.commandPath)) {
+    return;
+  }
+  const positionalArgs = dynamicCommandArguments(dynamicDescriptor).length === 0 ? collectLoosePositionalArgs(params.commandArgs) : stripLooseCommandOptionTokens(params.commandArgs, params.extensionFlagDefinitions);
+  validateDynamicExtensionCommandArgs(dynamicDescriptor, positionalArgs);
+}
+function syncCommanderActionArgs(actionCommand, actionArgs, commandArgs) {
+  actionCommand.args = [...commandArgs];
+  if ("_processArguments" in actionCommand && typeof actionCommand._processArguments === "function") {
+    actionCommand._processArguments();
+  }
+  if (actionArgs.length > 0 && Array.isArray(actionArgs[0])) {
+    actionArgs[0] = [...actionCommand.processedArgs];
+  }
+}
 function wrapProgramActionsForExtensionHandlers(rootProgram) {
   const visit = (entry) => {
     const actionEntry = entry;
     if (typeof actionEntry._actionHandler === "function" && actionEntry[WRAPPED_ACTION_HANDLER] !== true) {
       const originalAction = actionEntry._actionHandler;
       actionEntry._actionHandler = async function wrappedActionHandler(...actionArgs) {
-        const possibleCommand = actionArgs[actionArgs.length - 1];
-        const actionCommand = possibleCommand instanceof Command ? possibleCommand : entry;
+        const actionCommand = resolveActionCommand(actionArgs, entry);
         const startedAt = Date.now();
         clearResolvedGlobalOptions(actionCommand);
         let globalOptions = getGlobalOptions(actionCommand);
@@ -5107,26 +5244,14 @@ function wrapProgramActionsForExtensionHandlers(rootProgram) {
           global: globalOptions,
           pm_root: pmRoot
         });
-        if (globalOptions.profile && parserOverride.warnings.length > 0) {
-          printError(`profile:extensions parser_warnings=${formatHookWarnings(parserOverride.warnings)}`);
-        }
+        maybePrintExtensionProfileWarnings(globalOptions.profile, "parser_warnings", parserOverride.warnings);
         commandArgs = parserOverride.context.args;
         commandOptions = parserOverride.context.options;
         globalOptions = parserOverride.context.global;
-        const dynamicDescriptor = activeRuntimeExtensionCommandDescriptors.get(normalizeExtensionCommandPath(commandPath));
-        if (dynamicDescriptor && isImporterOrExporterCommandPath(activeRegistrations, commandPath)) {
-          const positionalArgs = dynamicDescriptor.arguments.length === 0 ? collectLoosePositionalArgs(commandArgs) : stripLooseCommandOptionTokens(commandArgs, extensionFlagDefinitions);
-          validateDynamicExtensionCommandArgs(dynamicDescriptor, positionalArgs);
-        }
+        validateDynamicInvocationArgs({ activeRegistrations, commandPath, commandArgs, extensionFlagDefinitions });
         globalOptions = await applyDefaultOutputFormat(globalOptions);
         setResolvedGlobalOptions(actionCommand, globalOptions);
-        actionCommand.args = [...commandArgs];
-        if ("_processArguments" in actionCommand && typeof actionCommand._processArguments === "function") {
-          actionCommand._processArguments();
-        }
-        if (actionArgs.length > 0 && Array.isArray(actionArgs[0])) {
-          actionArgs[0] = [...actionCommand.processedArgs];
-        }
+        syncCommanderActionArgs(actionCommand, actionArgs, commandArgs);
         for (const [key, value] of Object.entries(commandOptions)) {
           actionCommand.setOptionValueWithSource(key, value, "cli");
         }
@@ -5145,9 +5270,7 @@ function wrapProgramActionsForExtensionHandlers(rootProgram) {
           global: globalOptions,
           pm_root: pmRoot
         });
-        if (globalOptions.profile && extensionCommandResult.warnings.length > 0) {
-          printError(`profile:extensions command_handler_warnings=${formatHookWarnings(extensionCommandResult.warnings)}`);
-        }
+        maybePrintExtensionProfileWarnings(globalOptions.profile, "command_handler_warnings", extensionCommandResult.warnings);
         if (extensionCommandResult.handled) {
           setActiveCommandResult(extensionCommandResult.result);
           printResult(extensionCommandResult.result, {
@@ -5172,34 +5295,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);
@@ -5216,18 +5367,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);
@@ -5650,6 +5790,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;
@@ -5684,268 +6126,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 = {
@@ -5984,6 +6165,12 @@ var _testOnly = {
   extensionProvidesTemplatesRuntime,
   hasAnyCapability,
   handleGenericRunPmCliError,
+  handleRunPmCliCommanderError,
+  handleRunPmCliError,
+  handleRunPmCliHelpDisplayError,
+  handleRunPmCliKnownError,
+  handleRunPmCliCommanderUsageError,
+  handleUnknownHelpCommandError,
   inferMissingFieldsFromErrorMessage,
   inferPostActionErrorCode,
   inferPostActionFailureMessage,
@@ -6000,12 +6187,14 @@ var _testOnly = {
   normalizeTelemetryResolutionStage,
   normalizeThrownExitCode,
   probeUsesAnyFlag,
+  prepareExtensionServicesForRunPmCliError,
   readRecordBoolean,
   readRecordNumber,
   readRecordString,
   registerDynamicExtensionCommandPaths,
   registerRuntimeSchemaFieldFlags,
   resolveCoreCommandRegistrationSelection,
+  resolveUnknownHelpToken,
   readThrownExitCode,
   runAndClearAfterCommandHooks,
   runRequiredExtensionCommand,
@@ -6013,8 +6202,10 @@ var _testOnly = {
   shouldLogHandledErrorToSentry,
   shouldRegisterDynamicExtensionPaths,
   shouldRegisterRuntimeSchemaFlags,
+  shouldHandleRunPmCliCommanderError,
   setActiveExtensionHookContextForTest,
   setActiveRuntimeExtensionCommandDescriptorsForTest,
+  setRecoveredExtensionServices,
   toLooseFieldDefinitionType,
   isImporterOrExporterCommandPath,
   validateDynamicExtensionCommandInvocation,