@unbrained/pm-cli 2026.5.30 → 2026.6.5

package/dist/cli/main.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="fb080e3e-ad71-5608-a944-ce887395e3e9")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="85d31f87-d392-5da2-9d53-1525fb938ff2")}catch(e){}}();
 import fs from "node:fs";
 import path from "node:path";
 import { Command } from "commander";
-import { activateExtensions, clearActiveExtensionHooks, getActiveCommandResult, getActiveExtensionRegistrations, loadExtensions, runActiveCommandHandler, runActiveParserOverride, runActivePreflightOverride, runAfterCommandHooks, runBeforeCommandHooks, setActiveCommandResult, setActiveCommandContext, setActiveExtensionCommands, setActiveExtensionHooks, setActiveExtensionParsers, setActiveExtensionPreflight, setActiveExtensionRegistrations, setActiveExtensionRenderers, setActiveExtensionServices, } from "../core/extensions/index.js";
+import { activateExtensions, clearActiveExtensionHooks, createEmptyExtensionRegistrationRegistry, discoverExtensions, getActiveCommandResult, getActiveExtensionRegistrations, loadExtensions, consumeAfterCommandAffectedItems, runActiveCommandHandler, runActiveParserOverride, runActivePreflightOverride, runAfterCommandHooks, runBeforeCommandHooks, setActiveCommandResult, setActiveCommandContext, setActiveExtensionCommands, setActiveExtensionHooks, setActiveExtensionParsers, setActiveExtensionPreflight, setActiveExtensionRegistrations, setActiveExtensionRenderers, setActiveExtensionServices, } from "../core/extensions/index.js";
 import { pathExists } from "../core/fs/fs-utils.js";
 import { resolvePmPackageRootFromModule } from "../core/packages/root.js";
 import { resolveItemTypeRegistry, } from "../core/item/type-registry.js";
@@ -19,7 +19,7 @@ import { deriveTelemetryCommandResolution, } from "../core/telemetry/observabili
 import { sentryCaptureCliError, sentryFinishCommandSpan, sentryFlush, sentryLogCliUsageError, sentrySetCommandContext, sentryStartCommandSpan, } from "../core/sentry/helpers.js";
 import { ensureSentryInit } from "../core/sentry/instrument.js";
 import { getSettingsPath, resolvePmRoot } from "../core/store/paths.js";
-import { readSettings } from "../core/store/settings.js";
+import { readSettings, readSettingsWithMetadata } from "../core/store/settings.js";
 import { coerceLooseCommandOptionsWithFlagDefinitions, parseLooseCommandOptions, validateLooseCommandOptionsWithFlagDefinitions, } from "./extension-command-options.js";
 import { attachRichHelpText } from "./help-content.js";
 import { extractProvidedOptionFlags, normalizeLongOptionFlag, renderPmCommand, } from "./argv-utils.js";
@@ -27,7 +27,7 @@ import { classifyCommanderError, classifyPmCliError, classifyUnknownError, forma
 import { applyDefaultOutputFormat, clearResolvedGlobalOptions, collect, formatHookWarnings, getCommandPath, getGlobalOptions, invalidateSearchCachesForMutation, setResolvedGlobalOptions, } from "./registration-helpers.js";
 import { createLazyModule } from "../core/shared/lazy-module.js";
 import { normalizeExtensionCommandPath, collectDynamicExtensionFlagHelpByCommand, collectExtensionCommandHelpDescriptors, applyDynamicExtensionArguments, buildDynamicExtensionCommandMetadataHelp, findCommandByPath, ensureCommandPath, } from "./extension-command-help.js";
-import { parseBootstrapGlobalOptions, applyBootstrapPagerPolicy, parseBootstrapHelpRequest, parseBootstrapCommandName, normalizeBootstrapInvocation, } from "./bootstrap-args.js";
+import { parseBootstrapGlobalOptions, applyBootstrapPagerPolicy, parseBootstrapHelpRequest, parseBootstrapCommandName, normalizeBootstrapInvocation, stripGlobalBootstrapTokens, } from "./bootstrap-args.js";
 import { collectMandatoryMigrationBlockers, enforceMandatoryMigrationWriteGate, enforceItemFormatWriteGateAndPreflightMigration, resolveMigrationId, resolveNormalizedMigrationStatus, } from "./migration-gates.js";
 import { isKnownHelpCommandPath, formatCommanderUsageMessage, formatCommanderUsageJson, resolveCommanderUsageContext, } from "./commander-usage.js";
 import { maybeRenderBootstrapJsonHelp, attachCreateUpdatePolicyHelpText, } from "./help-json-payload.js";
@@ -57,6 +57,7 @@ const TELEMETRY_COMMAND_RESOLUTION_SET = new Set([
 const TELEMETRY_RESOLUTION_STAGE_SET = new Set(["parse", "preflight", "execute", "unknown"]);
 const TELEMETRY_ERROR_CATEGORY_SET = new Set(["usage", "validation", "conflict", "runtime", "unknown"]);
 let runtimeExtensionSnapshotCache = null;
+let runtimeExtensionDiscoverySnapshotCache = null;
 let activeRuntimeExtensionCommandDescriptors = new Map();
 const HANDLED_ERROR_SENTRY_FLUSH_TIMEOUT_MS = 250;
 const EXPECTED_HANDLED_ERROR_EXIT_CODES = new Set([
@@ -137,7 +138,7 @@ function buildPmCliRecoveryContext(context, invocationArgv, rawMessage) {
     if (!suggestedRetry) {
         suggestedRetry = attemptedCommand;
     }
-    if (suggestedRetry === attemptedCommand) {
+    if (!existingRecovery?.suggested_retry && suggestedRetry === attemptedCommand) {
         suggestedRetry = undefined;
     }
     const recovery = {
@@ -321,17 +322,30 @@ async function runAndClearAfterCommandHooks(outcome) {
         clearActiveExtensionHooks();
         return;
     }
-    const hookWarnings = await runAfterCommandHooks(runtime.hooks, {
-        command: runtime.commandName,
-        args: runtime.commandArgs,
-        options: { ...runtime.commandOptions },
-        global: { ...runtime.globalOptions },
-        pm_root: runtime.pmRoot,
-        ok: outcome.ok,
-        error: outcome.error,
-        result: getActiveCommandResult(),
-    });
-    clearActiveExtensionHooks();
+    let hookWarnings = [];
+    try {
+        hookWarnings = await runAfterCommandHooks(runtime.hooks, {
+            command: runtime.commandName,
+            args: runtime.commandArgs,
+            options: { ...runtime.commandOptions },
+            global: { ...runtime.globalOptions },
+            pm_root: runtime.pmRoot,
+            ok: outcome.ok,
+            error: outcome.error,
+            result: getActiveCommandResult(),
+            affected: consumeAfterCommandAffectedItems(),
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        hookWarnings = [`afterCommand hooks failed: ${message}`];
+    }
+    finally {
+        clearActiveExtensionHooks();
+    }
+    if (!runtime.globalOptions.json && hookWarnings.length > 0) {
+        printError(`[pm] warning: afterCommand hook_warnings=${formatHookWarnings(hookWarnings)}`);
+    }
     if (runtime.profileEnabled && hookWarnings.length > 0) {
         printError(`profile:extensions hook_warnings=${formatHookWarnings(hookWarnings)}`);
     }
@@ -534,6 +548,20 @@ async function registerRuntimeSchemaFieldFlags(rootProgram, invocationArgv) {
         }
     }
 }
+async function maybeAttachCreateUpdatePolicyHelpText(rootProgram, pmRoot, invocationArgv, registrations, settings) {
+    const bootstrapCommand = parseBootstrapCommandName(invocationArgv);
+    if (bootstrapCommand !== "create" && bootstrapCommand !== "update") {
+        return;
+    }
+    try {
+        const resolvedSettings = settings ?? (await readSettings(pmRoot));
+        const typeRegistry = resolveItemTypeRegistry(resolvedSettings, registrations);
+        attachCreateUpdatePolicyHelpText(rootProgram, typeRegistry, invocationArgv);
+    }
+    catch {
+        // Help should remain available even when settings cannot be read.
+    }
+}
 function defaultPreflightDecision() {
     return {
         enforce_item_format_gate: true,
@@ -545,6 +573,194 @@ function defaultPreflightDecision() {
 function buildRuntimeExtensionSnapshotCacheKey(pmRoot) {
     return `pm-root:${pmRoot}`;
 }
+function bootstrapProfileEnabled(invocationArgv) {
+    return invocationArgv.some((token) => token === "--profile");
+}
+function buildRuntimeExtensionDiscoverySnapshotCacheKey(pmRoot) {
+    return `pm-root:${pmRoot}`;
+}
+function collectLeadingCommandArgs(commandArgs) {
+    const leading = [];
+    for (const arg of commandArgs ?? []) {
+        if (arg.startsWith("-")) {
+            break;
+        }
+        const normalized = normalizeExtensionCommandPath(arg);
+        if (normalized.length === 0) {
+            continue;
+        }
+        leading.push(normalized);
+    }
+    return leading;
+}
+function collectActivationCommandCandidates(probe) {
+    const commandPath = normalizeExtensionCommandPath(probe.commandPath ?? "");
+    if (commandPath.length === 0) {
+        return [];
+    }
+    const candidates = [commandPath];
+    const parts = commandPath.split(" ").filter((part) => part.length > 0);
+    for (const arg of collectLeadingCommandArgs(probe.commandArgs)) {
+        parts.push(...arg.split(" ").filter((part) => part.length > 0));
+        candidates.push(parts.join(" "));
+    }
+    return [...new Set(candidates)];
+}
+function activationCommandMatchesProbe(command, probe) {
+    const normalized = normalizeExtensionCommandPath(command);
+    if (normalized.length === 0) {
+        return false;
+    }
+    const candidates = collectActivationCommandCandidates(probe);
+    for (const candidate of candidates) {
+        if (candidate === normalized || candidate.startsWith(`${normalized} `)) {
+            return true;
+        }
+    }
+    if (probe.allowCommandPrefixMatch === true) {
+        return candidates.some((candidate) => normalized.startsWith(`${candidate} `));
+    }
+    return false;
+}
+function extensionActivationCommands(extension) {
+    return extension.activation?.commands ?? [];
+}
+function extensionCapabilities(extension) {
+    return new Set((extension.capabilities ?? []).map((capability) => capability.trim().toLowerCase()));
+}
+const GLOBAL_EXTENSION_ACTIVATION_CAPABILITIES = new Set(["hooks", "parser", "preflight", "renderers"]);
+const CONSERVATIVE_EXTENSION_ACTIVATION_CAPABILITIES = new Set(["commands", "schema", "services"]);
+const SEARCH_EXTENSION_ACTIVATION_COMMANDS = new Set(["reindex", "search", "search-advanced"]);
+const CREATE_TEMPLATE_FLAGS = new Set(["--template"]);
+function hasAnyCapability(capabilities, expected) {
+    for (const capability of expected) {
+        if (capabilities.has(capability)) {
+            return true;
+        }
+    }
+    return false;
+}
+function commandPathNeedsSearchExtensions(commandPath) {
+    const normalized = normalizeExtensionCommandPath(commandPath ?? "");
+    if (normalized.length === 0) {
+        return false;
+    }
+    const [topLevel] = normalized.split(" ");
+    return SEARCH_EXTENSION_ACTIVATION_COMMANDS.has(topLevel ?? normalized);
+}
+function probeUsesAnyFlag(probe, flags) {
+    for (const arg of probe.commandArgs ?? []) {
+        if (!arg.startsWith("--")) {
+            continue;
+        }
+        const [flagName] = arg.split("=", 1);
+        if (flags.has(flagName)) {
+            return true;
+        }
+    }
+    return false;
+}
+function commandPathNeedsTemplateExtensions(probe) {
+    return normalizeExtensionCommandPath(probe.commandPath ?? "") === "create" && probeUsesAnyFlag(probe, CREATE_TEMPLATE_FLAGS);
+}
+function extensionProvidesTemplatesRuntime(commands) {
+    return commands.some((command) => {
+        const normalized = normalizeExtensionCommandPath(command);
+        return normalized === "templates" || normalized.startsWith("templates ");
+    });
+}
+function extensionNeedsActivationForProbe(extension, probe) {
+    const capabilities = extensionCapabilities(extension);
+    const commands = extensionActivationCommands(extension);
+    if (commands.length > 0 && commands.some((command) => activationCommandMatchesProbe(command, probe))) {
+        return true;
+    }
+    if (hasAnyCapability(capabilities, GLOBAL_EXTENSION_ACTIVATION_CAPABILITIES)) {
+        return true;
+    }
+    if (commandPathNeedsTemplateExtensions(probe) && extensionProvidesTemplatesRuntime(commands)) {
+        return true;
+    }
+    if (capabilities.has("search")) {
+        return commandPathNeedsSearchExtensions(probe.commandPath);
+    }
+    if (commands.length > 0) {
+        return false;
+    }
+    if (hasAnyCapability(capabilities, CONSERVATIVE_EXTENSION_ACTIVATION_CAPABILITIES)) {
+        return true;
+    }
+    if (capabilities.has("importers")) {
+        return probe.allowCommandPrefixMatch === true;
+    }
+    return false;
+}
+function discoveryNeedsActivationForProbe(discovery, probe) {
+    if (discovery.effective.length === 0) {
+        return false;
+    }
+    const hasCommandProbe = normalizeExtensionCommandPath(probe.commandPath ?? "").length > 0;
+    if (!hasCommandProbe) {
+        return discovery.effective.some((extension) => {
+            const capabilities = extensionCapabilities(extension);
+            return (extensionActivationCommands(extension).length > 0 ||
+                hasAnyCapability(capabilities, GLOBAL_EXTENSION_ACTIVATION_CAPABILITIES) ||
+                hasAnyCapability(capabilities, CONSERVATIVE_EXTENSION_ACTIVATION_CAPABILITIES) ||
+                capabilities.has("importers") ||
+                capabilities.has("search"));
+        });
+    }
+    return discovery.effective.some((extension) => extensionNeedsActivationForProbe(extension, probe));
+}
+function buildBootstrapActivationProbe(invocationArgv) {
+    const helpRequest = parseBootstrapHelpRequest(invocationArgv);
+    if (helpRequest.requested && helpRequest.commandPathTokens.length > 0) {
+        const [commandPath, ...commandArgs] = helpRequest.commandPathTokens;
+        return {
+            commandPath,
+            commandArgs,
+            allowCommandPrefixMatch: true,
+        };
+    }
+    const stripped = stripGlobalBootstrapTokens(invocationArgv);
+    const commandIndex = stripped.findIndex((token) => token.trim().length > 0 && !token.startsWith("-"));
+    if (commandIndex < 0) {
+        return {};
+    }
+    return {
+        commandPath: stripped[commandIndex],
+        commandArgs: stripped.slice(commandIndex + 1),
+        allowCommandPrefixMatch: helpRequest.requested,
+    };
+}
+function collectParsedActivationCommandArgs(command) {
+    const commandArgs = command.args.map(String);
+    const commandPath = normalizeExtensionCommandPath(getCommandPath(command));
+    if (commandPath === "create") {
+        const options = command.optsWithGlobals();
+        if (typeof options.template === "string" && options.template.trim().length > 0) {
+            commandArgs.push("--template");
+        }
+    }
+    return commandArgs;
+}
+/**
+ * Surface settings-read warnings once per command on stderr. readSettings()
+ * silently falls back to defaults when settings.json is invalid, so most
+ * commands (create/list/search/...) generate the warning but never show it — a
+ * typo would change behavior with no explanation. Only the `settings_read_*`
+ * codes are surfaced (the corrupt-settings fallbacks: invalid_json /
+ * invalid_schema / merge_failed); other informational settings warnings (schema
+ * bootstrap, legacy-format coercion) stay quiet. Mirrors the same finding in
+ * `pm health`, which also carries a remediation_map for it.
+ */
+function emitSettingsReadWarnings(warnings) {
+    for (const warning of warnings) {
+        if (warning.startsWith("settings_read_")) {
+            printError(`[pm] warning: ${warning} — settings.json could not be loaded and pm fell back to defaults; run pm health for remediation.`);
+        }
+    }
+}
 function emitExtensionProfile(globalOptions, snapshot) {
     if (!globalOptions.profile) {
         return;
@@ -554,6 +770,56 @@ function emitExtensionProfile(globalOptions, snapshot) {
         printError(`profile:extensions activation_warnings=${formatHookWarnings(snapshot.activationWarnings)}`);
     }
 }
+function emitExtensionSkippedProfile(profileEnabled, snapshot, probe) {
+    if (!profileEnabled) {
+        return;
+    }
+    const command = normalizeExtensionCommandPath(probe.commandPath ?? "") || "<none>";
+    printError(`profile:extensions activation=skipped command=${command} effective=${snapshot.discovery.effective.length} warnings=${snapshot.discovery.warnings.length} discovery_ms=${snapshot.discoveryMs}`);
+}
+async function loadRuntimeExtensionDiscoverySnapshot(pmRoot) {
+    const cacheKey = buildRuntimeExtensionDiscoverySnapshotCacheKey(pmRoot);
+    if (runtimeExtensionDiscoverySnapshotCache?.key === cacheKey) {
+        return runtimeExtensionDiscoverySnapshotCache.snapshot;
+    }
+    const settingsPath = getSettingsPath(pmRoot);
+    if (!(await pathExists(settingsPath))) {
+        runtimeExtensionDiscoverySnapshotCache = {
+            key: cacheKey,
+            snapshot: null,
+        };
+        return null;
+    }
+    try {
+        const startedAt = Date.now();
+        const { settings, warnings: settingsReadWarnings } = await readSettingsWithMetadata(pmRoot);
+        const discovery = await discoverExtensions({
+            pmRoot,
+            settings,
+            cwd: process.cwd(),
+            noExtensions: false,
+        });
+        const snapshot = {
+            pmRoot,
+            settings,
+            discovery,
+            discoveryMs: Date.now() - startedAt,
+            settingsReadWarnings: [...settingsReadWarnings],
+        };
+        runtimeExtensionDiscoverySnapshotCache = {
+            key: cacheKey,
+            snapshot,
+        };
+        return snapshot;
+    }
+    catch {
+        runtimeExtensionDiscoverySnapshotCache = {
+            key: cacheKey,
+            snapshot: null,
+        };
+        return null;
+    }
+}
 async function loadRuntimeExtensionSnapshot(pmRoot) {
     const cacheKey = buildRuntimeExtensionSnapshotCacheKey(pmRoot);
     if (runtimeExtensionSnapshotCache?.key === cacheKey) {
@@ -620,9 +886,34 @@ async function loadRuntimeExtensionSnapshot(pmRoot) {
 async function maybeLoadRuntimeExtensions(command) {
     const globalOptions = getGlobalOptions(command);
     if (globalOptions.noExtensions) {
+        // Extensions are disabled, so the discovery snapshot that normally carries
+        // the settings-read warnings is skipped. Surface them directly here (a single
+        // read on this uncommon path) so `pm --no-extensions <cmd>` — the common safe
+        // mode — still reports a corrupt settings.json instead of silently running on
+        // defaults.
+        const noExtPmRoot = resolvePmRoot(process.cwd(), globalOptions.path);
+        if (await pathExists(getSettingsPath(noExtPmRoot))) {
+            emitSettingsReadWarnings((await readSettingsWithMetadata(noExtPmRoot)).warnings);
+        }
         return null;
     }
     const pmRoot = resolvePmRoot(process.cwd(), globalOptions.path);
+    const discoverySnapshot = await loadRuntimeExtensionDiscoverySnapshot(pmRoot);
+    if (!discoverySnapshot) {
+        return null;
+    }
+    // Surface actionable settings-read warnings once per command, before the
+    // activation-skipped fast path returns, so create/list/search/... all report a
+    // corrupt settings.json instead of silently running on defaults.
+    emitSettingsReadWarnings(discoverySnapshot.settingsReadWarnings);
+    const probe = {
+        commandPath: getCommandPath(command),
+        commandArgs: collectParsedActivationCommandArgs(command),
+    };
+    if (!discoveryNeedsActivationForProbe(discoverySnapshot.discovery, probe)) {
+        emitExtensionSkippedProfile(globalOptions.profile, discoverySnapshot, probe);
+        return null;
+    }
     const snapshot = await loadRuntimeExtensionSnapshot(pmRoot);
     if (!snapshot) {
         return null;
@@ -817,24 +1108,39 @@ function wrapProgramActionsForExtensionHandlers(rootProgram) {
 }
 async function registerDynamicExtensionCommandPaths(rootProgram, invocationArgv) {
     const bootstrapGlobalOptions = parseBootstrapGlobalOptions(invocationArgv);
+    const pmRoot = resolvePmRoot(process.cwd(), bootstrapGlobalOptions.path);
     if (bootstrapGlobalOptions.noExtensions) {
         activeRuntimeExtensionCommandDescriptors = new Map();
         setActiveExtensionServices({ overrides: [] });
+        await maybeAttachCreateUpdatePolicyHelpText(rootProgram, pmRoot, invocationArgv, createEmptyExtensionRegistrationRegistry());
+        return;
+    }
+    const discoverySnapshot = await loadRuntimeExtensionDiscoverySnapshot(pmRoot);
+    const probe = buildBootstrapActivationProbe(invocationArgv);
+    if (!discoverySnapshot) {
+        activeRuntimeExtensionCommandDescriptors = new Map();
+        setActiveExtensionServices({ overrides: [] });
+        return;
+    }
+    if (!discoveryNeedsActivationForProbe(discoverySnapshot.discovery, probe)) {
+        activeRuntimeExtensionCommandDescriptors = new Map();
+        setActiveExtensionServices({ overrides: [] });
+        await maybeAttachCreateUpdatePolicyHelpText(rootProgram, pmRoot, invocationArgv, createEmptyExtensionRegistrationRegistry(), discoverySnapshot.settings);
+        emitExtensionSkippedProfile(bootstrapProfileEnabled(invocationArgv), discoverySnapshot, probe);
         return;
     }
-    const pmRoot = resolvePmRoot(process.cwd(), bootstrapGlobalOptions.path);
     const snapshot = await loadRuntimeExtensionSnapshot(pmRoot);
     if (!snapshot) {
         activeRuntimeExtensionCommandDescriptors = new Map();
         setActiveExtensionServices({ overrides: [] });
+        await maybeAttachCreateUpdatePolicyHelpText(rootProgram, pmRoot, invocationArgv, createEmptyExtensionRegistrationRegistry(), discoverySnapshot.settings);
         return;
     }
     // Ensure usage/help/error formatting overrides are available even when parse
     // errors occur before preAction hooks initialize full runtime extension state.
     setActiveExtensionServices(snapshot.services);
     activeRuntimeExtensionCommandDescriptors = new Map(snapshot.commandDescriptors);
-    const typeRegistry = resolveItemTypeRegistry(snapshot.settings, snapshot.registrations);
-    attachCreateUpdatePolicyHelpText(rootProgram, typeRegistry, invocationArgv);
+    await maybeAttachCreateUpdatePolicyHelpText(rootProgram, pmRoot, invocationArgv, snapshot.registrations, snapshot.settings);
     const commandPaths = [...new Set([...snapshot.commandHandlers, ...snapshot.commandDescriptors.keys()])].sort((left, right) => left.localeCompare(right));
     for (const commandPath of commandPaths) {
         const pathParts = commandPath.split(" ").filter((part) => part.length > 0);
@@ -1093,6 +1399,7 @@ const LIST_QUERY_COMMAND_NAMES = new Set([
 const MUTATION_COMMAND_NAMES = new Set([
     "append",
     "close",
+    "close-many",
     "comments",
     "delete",
     "deps",
@@ -1123,6 +1430,14 @@ const OPERATION_COMMAND_NAMES = new Set([
     "test-runs-worker",
     "validate",
 ]);
+const MUTATING_OPERATION_COMMAND_NAMES = new Set([
+    "claim",
+    "close-task",
+    "pause-task",
+    "release",
+    "start-task",
+    "test",
+]);
 const REGISTER_ALL_CORE_COMMAND_FAMILIES = {
     setup: true,
     listQuery: true,
@@ -1267,12 +1582,39 @@ function shouldRegisterRuntimeSchemaFlags(invocationArgv) {
     }
     return RUNTIME_SCHEMA_FLAG_BOOTSTRAP_COMMANDS.has(commandName);
 }
+function enforceExplicitRetryForFlagTypos(bootstrapInvocation) {
+    const commandName = bootstrapInvocation.commandName;
+    if (!commandName) {
+        return;
+    }
+    const typoEvent = bootstrapInvocation.trace.find((entry) => entry.reason === "flag_typo");
+    if (!typoEvent) {
+        return;
+    }
+    const normalizedTokens = Array.isArray(typoEvent.to)
+        ? typoEvent.to
+        : [String(typoEvent.to ?? "")].filter((entry) => entry.length > 0);
+    const normalizedDisplay = normalizedTokens.length > 0 ? normalizedTokens.join(" ") : "the canonical flag";
+    const mutatingCommand = MUTATION_COMMAND_NAMES.has(commandName) || MUTATING_OPERATION_COMMAND_NAMES.has(commandName);
+    const code = mutatingCommand ? "mutating_flag_typo_requires_retry" : "flag_typo_requires_retry";
+    const commandScope = mutatingCommand ? "mutating option" : "option";
+    throw new PmCliError(`Refusing to auto-correct ${commandScope} ${typoEvent.from} to ${normalizedDisplay}. Retry with the canonical flag so the command is explicit.`, EXIT_CODE.USAGE, {
+        code,
+        examples: [renderPmCommand(bootstrapInvocation.argv)],
+        nextSteps: ["Retry the command with the canonical flag shown in examples."],
+        recovery: {
+            normalized_args: [...bootstrapInvocation.argv],
+            suggested_retry: renderPmCommand(bootstrapInvocation.argv),
+        },
+    });
+}
 export async function runPmCli(rawArgv = process.argv.slice(2)) {
     const bootstrapInvocation = normalizeBootstrapInvocation(rawArgv);
     const invocationArgv = bootstrapInvocation.argv;
     const invocationProcessArgv = [process.argv[0], process.argv[1], ...invocationArgv];
     const isBareInvocation = invocationArgv.length === 0;
     try {
+        enforceExplicitRetryForFlagTypos(bootstrapInvocation);
         applyBootstrapPagerPolicy(invocationArgv);
         const registrationSelection = resolveCoreCommandRegistrationSelection(invocationArgv);
         await registerCoreCommandFamilies(program, registrationSelection);
@@ -1333,8 +1675,18 @@ export async function runPmCli(rawArgv = process.argv.slice(2)) {
             };
         };
         if (!bootstrapGlobal.noExtensions) {
-            const bootstrapSnapshot = await loadRuntimeExtensionSnapshot(bootstrapPmRoot);
-            setActiveExtensionServices(bootstrapSnapshot?.services ?? { overrides: [] });
+            const bootstrapProbe = buildBootstrapActivationProbe(invocationArgv);
+            const discoverySnapshot = await loadRuntimeExtensionDiscoverySnapshot(bootstrapPmRoot);
+            if (discoverySnapshot && discoveryNeedsActivationForProbe(discoverySnapshot.discovery, bootstrapProbe)) {
+                const bootstrapSnapshot = await loadRuntimeExtensionSnapshot(bootstrapPmRoot);
+                setActiveExtensionServices(bootstrapSnapshot?.services ?? { overrides: [] });
+            }
+            else {
+                if (discoverySnapshot) {
+                    emitExtensionSkippedProfile(bootstrapProfileEnabled(invocationArgv), discoverySnapshot, bootstrapProbe);
+                }
+                setActiveExtensionServices({ overrides: [] });
+            }
         }
         const numericExitCode = readThrownExitCode(error);
         if (error instanceof PmCliError ||
@@ -1380,7 +1732,9 @@ export async function runPmCli(rawArgv = process.argv.slice(2)) {
                 command_resolution: commandResolution,
                 resolution_stage: "execute",
             });
-            sentryCaptureCliError(wrapThrownErrorForSentry(error, errorMessage));
+            if (loggedHandledErrorToSentry) {
+                sentryCaptureCliError(wrapThrownErrorForSentry(error, errorMessage));
+            }
             if (jsonErrors) {
                 printError(JSON.stringify(formatPmCliErrorForJson(errorMessage, exitCode, enrichedContext), null, 2));
             }
@@ -1605,4 +1959,4 @@ export const _testOnly = {
     wrapThrownErrorForSentry,
 };
 //# sourceMappingURL=main.js.map
-//# debugId=fb080e3e-ad71-5608-a944-ce887395e3e9
+//# debugId=85d31f87-d392-5da2-9d53-1525fb938ff2