@unbrained/pm-cli 2026.9.7 → 2026.9.8

package/dist/sdk/cli-contracts/runtime-contracts.js

@@ -1,2091 +1,2 @@
-/**
- * @module cli/commands/contracts
- *
- * Implements the pm contracts command surface and its agent-facing runtime behavior.
- */
-
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="188569e7-c809-5f28-a714-d531f57be1d9")}catch(e){}}();
-import { EXIT_CODE, SETTINGS_DEFAULTS, PmCliError, activateExtensions, getActiveExtensionRegistrations, loadExtensions, pathExists, commandOptionFlagLabel, resolveCommandOptionPolicyState, resolveItemTypeRegistry, resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, getSettingsPath, resolvePmRoot, readSettings, } from "../runtime-primitives.js";
-import { buildMcpToolContracts, } from "../../mcp/tool-definitions.js";
-import { ACTIVITY_COMMANDER_STRING_OPTION_CONTRACTS, ACTIVITY_FLAG_CONTRACTS, AGGREGATE_FLAG_CONTRACTS, ASSURANCE_FLAG_CONTRACTS, APPEND_FLAG_CONTRACTS, CALENDAR_COMMANDER_STRING_OPTION_CONTRACTS, CALENDAR_FLAG_CONTRACTS, CLAIM_FLAG_CONTRACTS, CLOSE_TASK_FLAG_CONTRACTS, COMMENTS_FLAG_CONTRACTS, CLOSE_FLAG_CONTRACTS, CLOSE_MANY_FLAG_CONTRACTS, COMPLETION_FLAG_CONTRACTS, CONFIG_FLAG_CONTRACTS, CONTRACTS_FLAG_CONTRACTS, COPY_FLAG_CONTRACTS, CONTEXT_COMMANDER_STRING_OPTION_CONTRACTS, CONTEXT_FLAG_CONTRACTS, CREATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, CREATE_COMMANDER_STRING_OPTION_CONTRACTS, CREATE_FLAG_CONTRACTS, DELETE_FLAG_CONTRACTS, DEPS_FLAG_CONTRACTS, GRAPH_FLAG_CONTRACTS, DOCS_FLAG_CONTRACTS, EXTENSION_ACTIVATE_FLAG_CONTRACTS, EXTENSION_ADOPT_ALL_FLAG_CONTRACTS, EXTENSION_ADOPT_FLAG_CONTRACTS, EXTENSION_CATALOG_FLAG_CONTRACTS, EXTENSION_DEACTIVATE_FLAG_CONTRACTS, EXTENSION_DESCRIBE_FLAG_CONTRACTS, EXTENSION_DOCTOR_FLAG_CONTRACTS, EXTENSION_EXPLORE_FLAG_CONTRACTS, EXTENSION_FLAG_CONTRACTS, EXTENSION_INIT_FLAG_CONTRACTS, EXTENSION_INSTALL_FLAG_CONTRACTS, EXTENSION_MANAGE_FLAG_CONTRACTS, EXTENSION_MIGRATE_FLAG_CONTRACTS, EXTENSION_RELOAD_FLAG_CONTRACTS, EXTENSION_UNINSTALL_FLAG_CONTRACTS, FILES_FLAG_CONTRACTS, FOCUS_FLAG_CONTRACTS, GC_FLAG_CONTRACTS, GET_FLAG_CONTRACTS, GUIDE_FLAG_CONTRACTS, GLOBAL_FLAG_CONTRACTS, HEALTH_FLAG_CONTRACTS, HISTORY_FLAG_CONTRACTS, HISTORY_COMPACT_FLAG_CONTRACTS, HISTORY_REDACT_FLAG_CONTRACTS, HISTORY_REPAIR_FLAG_CONTRACTS, HISTORY_AUTHOR_ACKNOWLEDGE_FLAG_CONTRACTS, INSTALL_FLAG_CONTRACTS, INIT_FLAG_CONTRACTS, ITEM_COMPLETE_FLAG_CONTRACTS, ITEM_MUTATE_FLAG_CONTRACTS, ITEM_REOPEN_FLAG_CONTRACTS, LEARNINGS_FLAG_CONTRACTS, LIST_COMMANDER_STRING_OPTION_CONTRACTS, LIST_FILTER_FLAG_CONTRACTS, MERGE_FLAG_CONTRACTS, NOTES_FLAG_CONTRACTS, PACKAGE_FLAG_CONTRACTS, PACKAGE_INIT_FLAG_CONTRACTS, PM_EXTENSION_CAPABILITY_CONTRACTS, PM_EXTENSION_POLICY_MODE_CONTRACTS, PM_EXTENSION_POLICY_SURFACE_CONTRACTS, PM_EXTENSION_SANDBOX_PROFILE_CONTRACTS, PM_EXTENSION_SERVICE_NAME_CONTRACTS, PM_EXTENSION_TRUST_MODE_CONTRACTS, PM_OUTPUT_DEGRADATION_STEPS, PLAN_FLAG_CONTRACTS, PM_CORE_COMMAND_NAMES, PM_DEPRECATED_TOOL_ACTIONS, PM_TOOL_ACTIONS, PM_TOOL_PARAMETERS_SCHEMA, REINDEX_FLAG_CONTRACTS, RELEASE_FLAG_CONTRACTS, RESTORE_FLAG_CONTRACTS, SCHEMA_FLAG_CONTRACTS, PROFILE_FLAG_CONTRACTS, SEARCH_COMMANDER_STRING_OPTION_CONTRACTS, EVAL_FLAG_CONTRACTS, WORKSPACE_FLAG_CONTRACTS, NEXT_FLAG_CONTRACTS, SEARCH_FLAG_CONTRACTS, STATS_FLAG_CONTRACTS, DUPLICATES_FLAG_CONTRACTS, START_TASK_FLAG_CONTRACTS, PAUSE_TASK_FLAG_CONTRACTS, TELEMETRY_FLAG_CONTRACTS, TEST_ALL_FLAG_CONTRACTS, TEST_FLAG_CONTRACTS, TEST_RUNS_FLAG_CONTRACTS, UPDATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, UPDATE_COMMANDER_STRING_OPTION_CONTRACTS, UPDATE_FLAG_CONTRACTS, UPDATE_MANY_FLAG_CONTRACTS, UPGRADE_FLAG_CONTRACTS, VALIDATE_FLAG_CONTRACTS, compactFlagAliasContracts, PM_COMMAND_ALIAS_CONTRACTS, PM_DIAGNOSTIC_OUTPUT_BUDGET_CONTRACTS, resolvePmCommandOutputBudget, } from "../cli-contracts.js";
-import { PM_POSITIONAL_ACTION_FLAG_CONTRACTS } from "./flag-contracts.js";
-import { GOVERNANCE_CLOSE_VALIDATION_DEFAULT_VALUES, GOVERNANCE_CREATE_MODE_DEFAULT_VALUES, GOVERNANCE_OWNERSHIP_ENFORCEMENT_VALUES, GOVERNANCE_WORKFLOW_ENFORCEMENT_VALUES, } from "../../types.js";
-import { BRIEF_LIST_FIELDS, DEFAULT_COMPACT_LIST_FIELDS, LIST_COMMAND_DEFAULT_PROJECTIONS, } from "../query/list.js";
-import { getActiveContextIntentContracts, } from "../context-intent-contracts.js";
-import { readOutputIncludeModeOptions, resolveReadOutputSurface, PM_READ_OUTPUT_SURFACE_CONTRACTS, } from "../read-output-contracts.js";
-import { enrichCliFlagInvocationContracts, } from "../flag-invocation-contracts.js";
-import { resolvePmCommandVisibilityTier, } from "../agent-capability-contracts.js";
-import { PM_ERROR_CODE_CATALOG } from "../generated-error-code-catalog.js";
-import { resolvePmCommandOutputEnvelope, } from "../output-contracts.js";
-import { PM_COMMAND_EXIT_OUTCOME_CONTRACTS, resolvePmCommandExitContract, } from "./command-exit-contracts.js";
-import { BUILTIN_RELATIONSHIP_KINDS } from "../relationship-kinds/contract.js";
-import { ASSURANCE_GATE_TRIGGERS, ASSURANCE_MEASUREMENT_SOURCE_KINDS, } from "../governance/assurance.js";
-import { PM_CLI_GRAMMAR_CONTRACT, PM_COMMAND_DESTINATION_CONTRACTS, PM_COMMAND_POSITIONAL_CONTRACTS, PM_POSITIONAL_ACTION_CONTRACTS, positionalShapeKey, resolvePmCommandPositionalContract, } from "./grammar-contracts.js";
-const AGENT_BOOTSTRAP_FLAGS = new Map([
-    [
-        "claim",
-        [
-            "--if-available",
-            "--next",
-            "--type",
-            "--priority",
-            "--token-budget",
-            "--explain-ranking",
-        ],
-    ],
-    [
-        "close",
-        [
-            "--reason",
-            "--validate-close",
-            "--resolution",
-            "--expected-result",
-            "--actual-result",
-            "--message",
-        ],
-    ],
-    [
-        "context",
-        [
-            "--limit",
-            "--after",
-            "--depth",
-            "--section",
-            "--token-budget",
-            "--explain-ranking",
-        ],
-    ],
-    [
-        "contracts",
-        [
-            "--command",
-            "--flags-only",
-            "--summary",
-            "--runtime-only",
-            "--availability-only",
-            "--full",
-        ],
-    ],
-    [
-        "create",
-        ["--title", "--type", "--status", "--priority", "--dep", "--comment"],
-    ],
-    [
-        "get",
-        ["--full", "--depth", "--fields", "--tree", "--tree-depth", "--format"],
-    ],
-    [
-        "health",
-        [
-            "--check-only",
-            "--summary",
-            "--brief",
-            "--check-telemetry",
-            "--strict-exit",
-            "--full",
-        ],
-    ],
-    ["list", ["--status", "--type", "--limit", "--after", "--brief", "--fields"]],
-    [
-        "next",
-        [
-            "--limit",
-            "--blocked-limit",
-            "--ready-only",
-            "--token-budget",
-            "--explain-ranking",
-            "--format",
-        ],
-    ],
-    [
-        "search",
-        ["--mode", "--status", "--type", "--limit", "--after", "--fields"],
-    ],
-    [
-        "update",
-        ["--status", "--message", "--dep", "--comment", "--file", "--test"],
-    ],
-    [
-        "validate",
-        [
-            "--check-resolution",
-            "--check-history-drift",
-            "--check-storage-integrity",
-            "--counts",
-            "--strict-exit",
-            "--fix-hints",
-        ],
-    ],
-]);
-const AGENT_BOUNDED_FLAG_PRIORITY = [
-    "--limit",
-    "--after",
-    "--offset",
-    "--token-budget",
-    "--brief",
-    "--summary",
-    "--compact",
-    "--fields",
-    "--full",
-    "--format",
-    "--since",
-    "--until",
-];
-const LIST_COMMAND_NAMES = new Set([
-    "list",
-    "list-all",
-    "list-draft",
-    "list-open",
-    "list-in-progress",
-    "list-blocked",
-    "list-closed",
-    "list-canceled",
-]);
-const PACKAGE_OWNED_ACTIONS = new Set([
-    "calendar",
-    "guide",
-    "reindex",
-    "completion",
-    "test-runs-list",
-    "test-runs-status",
-    "test-runs-logs",
-    "test-runs-stop",
-    "test-runs-resume",
-    "templates-list",
-    "templates-save",
-    "templates-show",
-]);
-const PACKAGE_OWNED_COMMANDS = new Set([
-    "cal",
-    "calendar",
-    "completion",
-    "completion-statuses",
-    "completion-tags",
-    "completion-types",
-    "guide",
-    "reindex",
-    "templates",
-    "templates list",
-    "templates save",
-    "templates show",
-    "test-runs",
-    "test-runs list",
-    "test-runs status",
-    "test-runs logs",
-    "test-runs stop",
-    "test-runs resume",
-]);
-const PACKAGE_OWNED_COMMAND_INSTALL_HINTS = new Map([
-    ["cal", "calendar"],
-    ["calendar", "calendar"],
-    ["completion", "guide-shell"],
-    ["completion-statuses", "guide-shell"],
-    ["completion-tags", "guide-shell"],
-    ["completion-types", "guide-shell"],
-    ["guide", "guide-shell"],
-    ["reindex", "search-advanced"],
-    ["templates", "templates"],
-    ["templates list", "templates"],
-    ["templates save", "templates"],
-    ["templates show", "templates"],
-    ["test-runs", "linked-test-adapters"],
-    ["test-runs list", "linked-test-adapters"],
-    ["test-runs status", "linked-test-adapters"],
-    ["test-runs logs", "linked-test-adapters"],
-    ["test-runs stop", "linked-test-adapters"],
-    ["test-runs resume", "linked-test-adapters"],
-]);
-const PACKAGE_OWNED_ACTION_COMMAND_PATHS = new Map([
-    ["calendar", "calendar|cal"],
-    ["guide", "guide"],
-    ["reindex", "reindex"],
-    ["completion", "completion"],
-    ["test-runs-list", "test-runs|test-runs list"],
-    ["test-runs-status", "test-runs status"],
-    ["test-runs-logs", "test-runs logs"],
-    ["test-runs-stop", "test-runs stop"],
-    ["test-runs-resume", "test-runs resume"],
-    ["templates-list", "templates|templates list"],
-    ["templates-save", "templates save"],
-    ["templates-show", "templates show"],
-]);
-const PACKAGE_OWNED_COMMAND_ACTIONS = new Map([...PACKAGE_OWNED_ACTION_COMMAND_PATHS.entries()].flatMap(([action, commandPaths]) => splitCommandPathAliases(commandPaths).map((commandPath) => [commandPath, action])));
-const CANONICAL_COMMAND_ALIASES = [
-    {
-        canonical: "context",
-        aliases: ["ctx"],
-    },
-    {
-        canonical: "package",
-        aliases: ["extension", "packages"],
-    },
-];
-const COMMAND_ALIAS_TO_CANONICAL = new Map(CANONICAL_COMMAND_ALIASES.flatMap((entry) => entry.aliases.map((alias) => [alias, entry.canonical])));
-const COMMAND_NAMESPACE_DISPLAY_LIMIT = 10;
-const COMMAND_NAMESPACE_FALLBACK_LIMIT = 20;
-const COMMAND_INTENTS = new Map([
-    ["activity", "Read activity."],
-    ["aggregate", "Group counts."],
-    ["append", "Append body."],
-    ["assurance", "Evaluate assurance."],
-    ["assurance derive", "Derive checks from evidence."],
-    ["assurance risk", "Select checks for changes."],
-    ["assurance lineages", "Measure recurrence coverage."],
-    ["beads", "Manage Beads interoperability."],
-    ["cal", "Manage calendar integration."],
-    ["calendar", "Manage calendar integration."],
-    ["changelog", "Generate changelog output."],
-    ["claim", "Claim work."],
-    ["close", "Close work."],
-    ["close-many", "Close matching work."],
-    ["close-task", "Close task work."],
-    ["command-kit", "Inspect command authoring primitives."],
-    ["comments", "Manage comments."],
-    ["comments-audit", "Audit comment governance."],
-    ["completion", "Generate shell completions."],
-    ["config", "Manage settings."],
-    ["context", "Build context."],
-    ["contracts", "Inspect contracts."],
-    ["copy", "Copy work."],
-    ["create", "Create work."],
-    ["dedupe-audit", "Audit duplicate work."],
-    ["dedupe-merge", "Merge duplicate work."],
-    ["delete", "Delete work."],
-    ["deps", "Manage deps."],
-    ["duplicates", "Find duplicate clusters."],
-    ["docs", "Link docs."],
-    ["eval", "Run evaluations."],
-    ["event", "Manage events."],
-    ["events", "Read events."],
-    ["files", "Link files."],
-    ["focus", "Manage focus."],
-    ["gc", "Clean caches."],
-    ["get", "Read item."],
-    ["graph", "Query graph."],
-    ["guide", "Show user guides."],
-    ["health", "Check health."],
-    ["help", "Show help."],
-    ["history", "Inspect history."],
-    ["init", "Initialize workspace."],
-    ["install", "Install packages."],
-    ["item", "Mutate work through typed operations."],
-    ["learnings", "Manage learnings."],
-    ["list", "List work."],
-    ["list-all", "List work across every status."],
-    ["list-blocked", "List blocked work."],
-    ["list-canceled", "List canceled work."],
-    ["list-closed", "List closed work."],
-    ["list-draft", "List draft work."],
-    ["list-in-progress", "List in-progress work."],
-    ["list-open", "List open work."],
-    ["meet", "Record meeting context."],
-    ["merge", "Manage tracker merges."],
-    ["next", "Pick next work."],
-    ["notes", "Manage notes."],
-    ["normalize", "Normalize tracker data."],
-    ["ops", "Run operations."],
-    ["package", "Manage packages."],
-    ["packages", "Manage packages."],
-    ["pause-task", "Pause task work."],
-    ["plan", "Manage plans."],
-    ["profile", "Manage profiles."],
-    ["reindex", "Refresh search index."],
-    ["release", "Release claim."],
-    ["remind", "Manage reminders."],
-    ["restore", "Restore history."],
-    ["schema", "Customize schema."],
-    ["search", "Search work."],
-    ["search-advanced", "Run advanced search."],
-    ["start-task", "Start task work."],
-    ["stats", "Show stats."],
-    ["telemetry", "Manage telemetry."],
-    ["templates", "Manage work templates."],
-    ["test", "Run linked tests."],
-    ["test-all", "Run all linked tests."],
-    ["test-runs", "Inspect background test runs."],
-    ["todos", "Manage source-code todos."],
-    ["twin", "Manage repository twins."],
-    ["update", "Update work."],
-    ["update-many", "Update matching work."],
-    ["upgrade", "Upgrade packages."],
-    ["validate", "Validate data."],
-    ["vcs", "Inspect version-control context."],
-    ["workspace", "Manage portable workspace primitives."],
-    ["history-author-acknowledge", "Acknowledge reviewed history authors."],
-    ["history-compact", "Compact history."],
-    ["history-redact", "Redact sensitive history values."],
-    ["history-repair", "Repair history integrity."],
-]);
-// Lifecycle subcommand flag contracts for `pm extension`. Package lifecycle
-// swaps in the declarative init contract and adds the package-only upgrade
-// command; every shared extension/package subcommand remains byte-identical.
-const EXTENSION_LIFECYCLE_FLAG_CONTRACTS = [
-    ["init", EXTENSION_INIT_FLAG_CONTRACTS],
-    ["install", EXTENSION_INSTALL_FLAG_CONTRACTS],
-    ["uninstall", EXTENSION_UNINSTALL_FLAG_CONTRACTS],
-    ["explore", EXTENSION_EXPLORE_FLAG_CONTRACTS],
-    ["manage", EXTENSION_MANAGE_FLAG_CONTRACTS],
-    ["describe", EXTENSION_DESCRIBE_FLAG_CONTRACTS],
-    ["reload", EXTENSION_RELOAD_FLAG_CONTRACTS],
-    ["doctor", EXTENSION_DOCTOR_FLAG_CONTRACTS],
-    ["catalog", EXTENSION_CATALOG_FLAG_CONTRACTS],
-    ["adopt", EXTENSION_ADOPT_FLAG_CONTRACTS],
-    ["adopt-all", EXTENSION_ADOPT_ALL_FLAG_CONTRACTS],
-    ["activate", EXTENSION_ACTIVATE_FLAG_CONTRACTS],
-    ["deactivate", EXTENSION_DEACTIVATE_FLAG_CONTRACTS],
-    ["migrate", EXTENSION_MIGRATE_FLAG_CONTRACTS],
-];
-const PACKAGE_LIFECYCLE_FLAG_CONTRACTS = [
-    ...EXTENSION_LIFECYCLE_FLAG_CONTRACTS.map(([subcommand, flags]) => subcommand === "init"
-        ? [subcommand, PACKAGE_INIT_FLAG_CONTRACTS]
-        : [subcommand, flags]),
-    ["upgrade", UPGRADE_FLAG_CONTRACTS],
-];
-const CORE_COMMAND_FLAG_CONTRACT_ENTRIES = [
-    ...EXTENSION_LIFECYCLE_FLAG_CONTRACTS.map(([subcommand, flags]) => [`extension ${subcommand}`, flags]),
-    ...PACKAGE_LIFECYCLE_FLAG_CONTRACTS.flatMap(([subcommand, flags]) => [
-        [`package ${subcommand}`, flags],
-        [`packages ${subcommand}`, flags],
-    ]),
-    ["init", INIT_FLAG_CONTRACTS],
-    ["config", CONFIG_FLAG_CONTRACTS],
-    ["extension", EXTENSION_FLAG_CONTRACTS],
-    ["package", PACKAGE_FLAG_CONTRACTS],
-    ["packages", PACKAGE_FLAG_CONTRACTS],
-    ["install", INSTALL_FLAG_CONTRACTS],
-    ["create", CREATE_FLAG_CONTRACTS],
-    ["item mutate", ITEM_MUTATE_FLAG_CONTRACTS],
-    ["item complete", ITEM_COMPLETE_FLAG_CONTRACTS],
-    ["item reopen", ITEM_REOPEN_FLAG_CONTRACTS],
-    ["copy", COPY_FLAG_CONTRACTS],
-    ["focus", FOCUS_FLAG_CONTRACTS],
-    ["update", UPDATE_FLAG_CONTRACTS],
-    ["update-many", UPDATE_MANY_FLAG_CONTRACTS],
-    ["upgrade", UPGRADE_FLAG_CONTRACTS],
-    ["calendar", CALENDAR_FLAG_CONTRACTS],
-    ["cal", CALENDAR_FLAG_CONTRACTS],
-    ["context", CONTEXT_FLAG_CONTRACTS],
-    ["ctx", CONTEXT_FLAG_CONTRACTS],
-    ["get", GET_FLAG_CONTRACTS],
-    ["search", SEARCH_FLAG_CONTRACTS],
-    ["eval", EVAL_FLAG_CONTRACTS],
-    ["workspace", WORKSPACE_FLAG_CONTRACTS],
-    ["workspace position", []],
-    ["workspace snapshot", WORKSPACE_FLAG_CONTRACTS],
-    ["workspace snapshot create", WORKSPACE_FLAG_CONTRACTS],
-    ["workspace snapshot list", WORKSPACE_FLAG_CONTRACTS],
-    ["workspace snapshot inspect", WORKSPACE_FLAG_CONTRACTS],
-    ["workspace snapshot restore", WORKSPACE_FLAG_CONTRACTS],
-    ["workspace snapshot delete", WORKSPACE_FLAG_CONTRACTS],
-    ["next", NEXT_FLAG_CONTRACTS],
-    ["aggregate", AGGREGATE_FLAG_CONTRACTS],
-    ["deps", DEPS_FLAG_CONTRACTS],
-    ["graph", GRAPH_FLAG_CONTRACTS],
-    ["guide", GUIDE_FLAG_CONTRACTS],
-    ["reindex", REINDEX_FLAG_CONTRACTS],
-    ["history", HISTORY_FLAG_CONTRACTS],
-    ["history-compact", HISTORY_COMPACT_FLAG_CONTRACTS],
-    ["history-redact", HISTORY_REDACT_FLAG_CONTRACTS],
-    ["history-repair", HISTORY_REPAIR_FLAG_CONTRACTS],
-    ["history-author-acknowledge", HISTORY_AUTHOR_ACKNOWLEDGE_FLAG_CONTRACTS],
-    ["merge", MERGE_FLAG_CONTRACTS],
-    ["schema", SCHEMA_FLAG_CONTRACTS],
-    ["profile", PROFILE_FLAG_CONTRACTS],
-    ["plan", PLAN_FLAG_CONTRACTS],
-    ["restore", RESTORE_FLAG_CONTRACTS],
-    ["delete", DELETE_FLAG_CONTRACTS],
-    ["close", CLOSE_FLAG_CONTRACTS],
-    ["close-many", CLOSE_MANY_FLAG_CONTRACTS],
-    ["append", APPEND_FLAG_CONTRACTS],
-    ["claim", CLAIM_FLAG_CONTRACTS],
-    ["release", RELEASE_FLAG_CONTRACTS],
-    ["start-task", START_TASK_FLAG_CONTRACTS],
-    ["pause-task", PAUSE_TASK_FLAG_CONTRACTS],
-    ["close-task", CLOSE_TASK_FLAG_CONTRACTS],
-    ["comments", COMMENTS_FLAG_CONTRACTS],
-    ["notes", NOTES_FLAG_CONTRACTS],
-    ["learnings", LEARNINGS_FLAG_CONTRACTS],
-    ["files", FILES_FLAG_CONTRACTS],
-    ["docs", DOCS_FLAG_CONTRACTS],
-    ["test", TEST_FLAG_CONTRACTS],
-    ["test-all", TEST_ALL_FLAG_CONTRACTS],
-    ["telemetry", TELEMETRY_FLAG_CONTRACTS],
-    ["test-runs", TEST_RUNS_FLAG_CONTRACTS],
-    ["gc", GC_FLAG_CONTRACTS],
-    ["stats", STATS_FLAG_CONTRACTS],
-    ["duplicates", DUPLICATES_FLAG_CONTRACTS],
-    ["validate", VALIDATE_FLAG_CONTRACTS],
-    ["health", HEALTH_FLAG_CONTRACTS],
-    ["assurance", ASSURANCE_FLAG_CONTRACTS],
-    ...PM_POSITIONAL_ACTION_FLAG_CONTRACTS,
-    ["contracts", CONTRACTS_FLAG_CONTRACTS],
-    ["completion", COMPLETION_FLAG_CONTRACTS],
-    ["activity", ACTIVITY_FLAG_CONTRACTS],
-    ...[...LIST_COMMAND_NAMES].map((command) => [command, LIST_FILTER_FLAG_CONTRACTS]),
-];
-const CORE_COMMAND_FLAG_CONTRACTS_BY_COMMAND = new Map(CORE_COMMAND_FLAG_CONTRACT_ENTRIES);
-/* c8 ignore start -- extension contract shaping utilities are exercised by dedicated extension/runtime integration suites. */
-function packageOwnedActionForCommand(command) {
-    const exactAction = PACKAGE_OWNED_COMMAND_ACTIONS.get(command);
-    if (exactAction) {
-        return exactAction;
-    }
-    if (command.startsWith("test-runs ")) {
-        return `test-runs-${command.slice("test-runs ".length)}`;
-    }
-    if (command.startsWith("templates ")) {
-        return `templates-${command.slice("templates ".length)}`;
-    }
-    return command;
-}
-function resolveActionCommandPath(action) {
-    if (PM_CORE_COMMAND_NAMES.includes(action)) {
-        return normalizeCommandPath(action);
-    }
-    if (action.startsWith("extension-")) {
-        return normalizeCommandPath(`extension ${action.slice("extension-".length)}`);
-    }
-    if (action.startsWith("package-")) {
-        return normalizeCommandPath(`package ${action.slice("package-".length)}`);
-    }
-    if (action.startsWith("item-")) {
-        return normalizeCommandPath(`item ${action.slice("item-".length)}`);
-    }
-    if (action.startsWith("test-runs-")) {
-        return normalizeCommandPath(`test-runs ${action.slice("test-runs-".length)}`);
-    }
-    if (action.startsWith("templates-")) {
-        return normalizeCommandPath(`templates ${action.slice("templates-".length)}`);
-    }
-    if (PACKAGE_OWNED_ACTIONS.has(action)) {
-        return (PACKAGE_OWNED_ACTION_COMMAND_PATHS.get(action) ??
-            normalizeCommandPath(action));
-    }
-    return null;
-}
-function actionDescriptorMatchesSelectedCommand(descriptor, selectedCommand) {
-    if (descriptor.command_path === null) {
-        return false;
-    }
-    return splitCommandPathAliases(descriptor.command_path).some((commandPath) => {
-        if (commandPath === selectedCommand) {
-            return true;
-        }
-        return (commandPath.startsWith(`${selectedCommand} `) ||
-            selectedCommand.startsWith(`${commandPath} `));
-    });
-}
-function splitCommandPathAliases(commandPath) {
-    return commandPath
-        .split("|")
-        .map((entry) => normalizeCommandPath(entry))
-        .filter((entry) => entry.length > 0);
-}
-function resolveScopedCommandsFromActionDescriptors(descriptors, commandCatalog) {
-    const commandSet = new Set(commandCatalog);
-    const scoped = new Set();
-    for (const descriptor of descriptors) {
-        if (!descriptor.command_path) {
-            continue;
-        }
-        for (const commandPath of splitCommandPathAliases(descriptor.command_path)) {
-            const tokens = commandPath.split(" ").filter((entry) => entry.length > 0);
-            if (tokens.length === 0) {
-                continue;
-            }
-            for (let end = tokens.length; end > 0; end -= 1) {
-                const candidate = tokens.slice(0, end).join(" ");
-                if (!commandSet.has(candidate)) {
-                    continue;
-                }
-                scoped.add(candidate);
-                break;
-            }
-        }
-    }
-    return [...scoped].sort((left, right) => left.localeCompare(right));
-}
-function normalizeToken(value) {
-    if (typeof value !== "string") {
-        return undefined;
-    }
-    const trimmed = value.trim().toLowerCase();
-    return trimmed.length > 0 ? trimmed : undefined;
-}
-function extractActionBranches(schema) {
-    const oneOf = schema.oneOf;
-    if (!Array.isArray(oneOf)) {
-        return [];
-    }
-    return oneOf.filter((entry) => typeof entry === "object" && entry !== null);
-}
-function filterSchemaByAction(schema, action) {
-    if (!action) {
-        return { ...schema };
-    }
-    const branches = extractActionBranches(schema);
-    const filtered = branches.filter((entry) => {
-        const properties = entry.properties;
-        if (typeof properties !== "object" || properties === null) {
-            return false;
-        }
-        const actionProperty = properties.action;
-        if (typeof actionProperty !== "object" || actionProperty === null) {
-            return false;
-        }
-        return actionProperty.const === action;
-    });
-    return {
-        ...schema,
-        oneOf: filtered,
-    };
-}
-function filterSchemaByActions(schema, actions) {
-    const branches = extractActionBranches(schema);
-    const filtered = branches.filter((entry) => {
-        const properties = entry.properties;
-        if (typeof properties !== "object" || properties === null) {
-            return false;
-        }
-        const actionProperty = properties.action;
-        if (typeof actionProperty !== "object" || actionProperty === null) {
-            return false;
-        }
-        const actionConst = actionProperty.const;
-        return typeof actionConst === "string" && actions.has(actionConst);
-    });
-    return {
-        ...schema,
-        oneOf: filtered,
-    };
-}
-function normalizeCommandPath(value) {
-    return value
-        .trim()
-        .toLowerCase()
-        .split(/\s+/)
-        .filter((entry) => entry.length > 0)
-        .join(" ");
-}
-function normalizeActionNameFromCommand(commandPath) {
-    return commandPath.replace(/\s+/g, "-");
-}
-function toOptionalTrimmedString(value) {
-    if (typeof value !== "string") {
-        return null;
-    }
-    const trimmed = value.trim();
-    return trimmed.length > 0 ? trimmed : null;
-}
-function normalizeStringList(values) {
-    if (!Array.isArray(values)) {
-        return [];
-    }
-    const normalized = [];
-    const seen = new Set();
-    for (const value of values) {
-        const trimmed = toOptionalTrimmedString(value);
-        if (!trimmed || seen.has(trimmed)) {
-            continue;
-        }
-        seen.add(trimmed);
-        normalized.push(trimmed);
-    }
-    return normalized;
-}
-function assignExtensionFlagBoolean(contract, key, enabled) {
-    if (enabled) {
-        contract[key] = true;
-    }
-}
-function normalizeExtensionFlagName(value, kind) {
-    if (value == null) {
-        return null;
-    }
-    if (typeof value !== "string") {
-        throw new TypeError("Expected string for extension flag name.");
-    }
-    const trimmed = value.trim();
-    if (trimmed.length === 0) {
-        return null;
-    }
-    if (kind === "long") {
-        return trimmed.startsWith("--") && trimmed.length > 2 ? trimmed : null;
-    }
-    return trimmed.startsWith("-") &&
-        !trimmed.startsWith("--") &&
-        trimmed.length > 1
-        ? trimmed
-        : null;
-}
-function toExtensionFlagContract(definition) {
-    const normalizedLong = normalizeExtensionFlagName(definition.long, "long");
-    const normalizedShort = normalizeExtensionFlagName(definition.short, "short");
-    const flag = normalizedLong ?? normalizedShort;
-    if (!flag) {
-        return null;
-    }
-    const contract = { flag };
-    if (normalizedShort && normalizedLong) {
-        contract.short = normalizedShort;
-    }
-    assignExtensionFlagBoolean(contract, "required", definition.required === true);
-    assignExtensionFlagBoolean(contract, "repeatable", definition.repeatable === true);
-    assignExtensionFlagBoolean(contract, "list", definition.list === true);
-    const description = toOptionalTrimmedString(definition.description);
-    if (description) {
-        contract.description = description;
-    }
-    const valueName = toOptionalTrimmedString(definition.value_name);
-    if (valueName) {
-        contract.value_name = valueName;
-    }
-    const rawValueType = [
-        toOptionalTrimmedString(definition.value_type),
-        toOptionalTrimmedString(definition.type),
-        valueName ? "string" : null,
-    ].find((candidate) => candidate === "string" ||
-        candidate === "number" ||
-        candidate === "boolean");
-    if (rawValueType) {
-        contract.value_type = rawValueType;
-    }
-    return contract;
-}
-function collectExtensionFlagContractsByCommand(registrations) {
-    const grouped = new Map();
-    for (const registration of registrations) {
-        const commandPath = normalizeCommandPath(registration.target_command);
-        if (commandPath.length === 0) {
-            continue;
-        }
-        const bucket = grouped.get(commandPath) ?? {
-            flags: [],
-            sources: [],
-            dedupe: new Set(),
-            sourceDedupe: new Set(),
-        };
-        const sourceKey = `${registration.layer}:${registration.name}`;
-        if (!bucket.sourceDedupe.has(sourceKey)) {
-            bucket.sourceDedupe.add(sourceKey);
-            bucket.sources.push({
-                layer: registration.layer,
-                name: registration.name,
-            });
-        }
-        for (const definition of registration.flags) {
-            const contract = toExtensionFlagContract(definition);
-            if (!contract) {
-                continue;
-            }
-            const key = `${contract.flag}|${contract.short ?? ""}`;
-            if (bucket.dedupe.has(key)) {
-                continue;
-            }
-            bucket.dedupe.add(key);
-            bucket.flags.push(contract);
-        }
-        grouped.set(commandPath, bucket);
-    }
-    const normalized = new Map();
-    for (const [commandPath, bucket] of grouped.entries()) {
-        normalized.set(commandPath, {
-            flags: bucket.flags,
-            sources: bucket.sources.sort((left, right) => {
-                const layerOrder = left.layer.localeCompare(right.layer);
-                if (layerOrder !== 0) {
-                    return layerOrder;
-                }
-                return (left.name ?? "").localeCompare(right.name ?? "");
-            }),
-        });
-    }
-    return normalized;
-}
-function collectExtensionCommandContracts(runtimeProbe) {
-    const flagsByCommand = collectExtensionFlagContractsByCommand(runtimeProbe.flagRegistrations);
-    const definitionsByCommand = new Map();
-    for (const definition of runtimeProbe.commandDefinitions) {
-        const command = normalizeCommandPath(definition.command);
-        if (command.length === 0) {
-            continue;
-        }
-        const action = toOptionalTrimmedString(definition.action) ??
-            normalizeActionNameFromCommand(command);
-        const args = Array.isArray(definition.arguments)
-            ? definition.arguments
-                .map((argument) => {
-                const name = toOptionalTrimmedString(argument.name);
-                if (!name) {
-                    return null;
-                }
-                return {
-                    name,
-                    required: argument.required === true,
-                    variadic: argument.variadic === true,
-                    description: toOptionalTrimmedString(argument.description),
-                };
-            })
-                .filter((argument) => argument !== null)
-            : [];
-        definitionsByCommand.set(command, {
-            command,
-            action,
-            source: {
-                layer: definition.layer,
-                name: definition.name,
-            },
-            description: toOptionalTrimmedString(definition.description),
-            intent: toOptionalTrimmedString(definition.intent),
-            arguments: args,
-            flags: flagsByCommand.get(command)?.flags ?? [],
-            examples: normalizeStringList(definition.examples),
-            failure_hints: normalizeStringList(definition.failure_hints),
-        });
-    }
-    const extensionCommands = new Set();
-    for (const command of runtimeProbe.handlers) {
-        extensionCommands.add(normalizeCommandPath(command));
-    }
-    for (const command of definitionsByCommand.keys()) {
-        extensionCommands.add(command);
-    }
-    for (const command of flagsByCommand.keys()) {
-        extensionCommands.add(command);
-    }
-    const contracts = [];
-    for (const command of [...extensionCommands].sort((left, right) => left.localeCompare(right))) {
-        const definition = definitionsByCommand.get(command);
-        contracts.push(buildCollectedExtensionCommandContract(command, definition, flagsByCommand.get(command)?.flags ?? []));
-    }
-    return contracts;
-}
-function buildCollectedExtensionCommandContract(command, definition, registeredFlags) {
-    if (definition) {
-        return {
-            ...definition,
-            flags: definition.flags.length > 0 ? definition.flags : registeredFlags,
-        };
-    }
-    return {
-        command,
-        action: normalizeActionNameFromCommand(command),
-        source: null,
-        description: null,
-        intent: null,
-        arguments: [],
-        flags: registeredFlags,
-        examples: [],
-        failure_hints: [],
-    };
-}
-function extensionSchemaPropertyNameFromFlag(flag) {
-    const normalized = flag.flag.replace(/^-+/, "").trim();
-    if (normalized.length === 0) {
-        return null;
-    }
-    const camelCased = normalized.replace(/-([a-z0-9])/g, (_match, char) => char.toUpperCase());
-    const cleaned = camelCased.replace(/[^a-zA-Z0-9]/g, "");
-    return cleaned.length > 0 ? cleaned : null;
-}
-function buildExtensionArgumentSchema(argument, action) {
-    if (argument.variadic) {
-        return {
-            type: "array",
-            items: { type: "string" },
-            description: argument.description ??
-                `Variadic argument '${argument.name}' for extension action '${action}'.`,
-        };
-    }
-    return {
-        type: "string",
-        description: argument.description ??
-            `Argument '${argument.name}' for extension action '${action}'.`,
-    };
-}
-function buildExtensionFlagSchema(flag, action) {
-    const valueType = flag.value_type ?? "boolean";
-    const schemaType = valueType === "boolean"
-        ? "boolean"
-        : valueType === "number"
-            ? ["number", "string"]
-            : "string";
-    const acceptsMultipleValues = flag.repeatable === true || flag.list === true;
-    return {
-        type: acceptsMultipleValues ? "array" : schemaType,
-        ...(acceptsMultipleValues ? { items: { type: schemaType } } : {}),
-        description: flag.description ??
-            `Extension option '${flag.flag}' for action '${action}'.`,
-    };
-}
-function buildExtensionActionSchemaBranch(contract) {
-    const commands = contract.command
-        .split("|")
-        .map((command) => command.trim())
-        .filter((command) => command.length > 0);
-    const properties = {
-        action: {
-            type: "string",
-            const: contract.action,
-            description: contract.intent ??
-                contract.description ??
-                `Invoke extension command '${contract.command}'.`,
-        },
-    };
-    const required = ["action"];
-    for (const argument of contract.arguments) {
-        properties[argument.name] = buildExtensionArgumentSchema(argument, contract.action);
-        if (argument.required) {
-            required.push(argument.name);
-        }
-    }
-    for (const flag of contract.flags) {
-        const propertyName = extensionSchemaPropertyNameFromFlag(flag);
-        if (!propertyName || properties[propertyName] !== undefined) {
-            continue;
-        }
-        properties[propertyName] = buildExtensionFlagSchema(flag, contract.action);
-        if (flag.required === true) {
-            required.push(propertyName);
-        }
-    }
-    return {
-        type: "object",
-        properties,
-        required,
-        additionalProperties: true,
-        "x-extension-source": contract.source,
-        "x-extension-command": commands[0] ?? contract.command,
-        "x-extension-commands": commands,
-    };
-}
-function mergeExtensionFlagContract(existing, incoming) {
-    existing.description ??= incoming.description;
-    existing.value_name ??= incoming.value_name;
-    existing.value_type ??= incoming.value_type;
-    if (incoming.required === true) {
-        existing.required = true;
-    }
-    if (incoming.repeatable === true) {
-        existing.repeatable = true;
-    }
-}
-function mergeExtensionContractsByAction(contracts) {
-    const byAction = new Map();
-    for (const contract of contracts) {
-        const existing = byAction.get(contract.action);
-        if (!existing) {
-            byAction.set(contract.action, {
-                ...contract,
-                flags: [...contract.flags],
-                examples: [...contract.examples],
-                failure_hints: [...contract.failure_hints],
-            });
-            continue;
-        }
-        existing.command = [...new Set([existing.command, contract.command])]
-            .sort((left, right) => left.localeCompare(right))
-            .join("|");
-        existing.arguments =
-            existing.arguments.length >= contract.arguments.length
-                ? existing.arguments
-                : contract.arguments;
-        const flagKeys = new Set(existing.flags.map((flag) => `${flag.flag}|${flag.short ?? ""}`));
-        for (const flag of contract.flags) {
-            const key = `${flag.flag}|${flag.short ?? ""}`;
-            if (!flagKeys.has(key)) {
-                flagKeys.add(key);
-                existing.flags.push(flag);
-            }
-            else {
-                const existingFlag = existing.flags.find((candidate) => `${candidate.flag}|${candidate.short ?? ""}` === key);
-                if (existingFlag) {
-                    mergeExtensionFlagContract(existingFlag, flag);
-                }
-            }
-        }
-        existing.examples = [
-            ...new Set([...existing.examples, ...contract.examples]),
-        ];
-        existing.failure_hints = [
-            ...new Set([...existing.failure_hints, ...contract.failure_hints]),
-        ];
-    }
-    return [...byAction.values()].sort((left, right) => left.action.localeCompare(right.action));
-}
-/* c8 ignore stop */
-async function resolveRuntimeExtensionActionProbe(global, readSettingsFn = readSettings) {
-    const defaultPolicyState = {
-        mode: SETTINGS_DEFAULTS.extensions.policy.mode,
-        trust_mode: SETTINGS_DEFAULTS.extensions.policy.trust_mode,
-        default_sandbox_profile: SETTINGS_DEFAULTS.extensions.policy.default_sandbox_profile,
-    };
-    if (global.noExtensions) {
-        return {
-            handlers: new Set(),
-            disabledReason: "extensions_disabled",
-            commandDefinitions: [],
-            flagRegistrations: [],
-            registrations: null,
-            policyState: defaultPolicyState,
-        };
-    }
-    const pmRoot = resolvePmRoot(process.cwd(), global.path);
-    if (!(await pathExists(getSettingsPath(pmRoot)))) {
-        return {
-            handlers: new Set(),
-            disabledReason: null,
-            commandDefinitions: [],
-            flagRegistrations: [],
-            registrations: null,
-            policyState: defaultPolicyState,
-        };
-    }
-    try {
-        const settings = await readSettingsFn(pmRoot);
-        const loadResult = await loadExtensions({
-            pmRoot,
-            settings,
-            cwd: process.cwd(),
-            noExtensions: false,
-        });
-        const activationResult = await activateExtensions({
-            ...loadResult,
-            loaded: loadResult.loaded,
-        });
-        const handlers = new Set(activationResult.commands.handlers.map((entry) => normalizeCommandPath(entry.command)));
-        return {
-            handlers,
-            disabledReason: null,
-            commandDefinitions: activationResult.registrations.commands,
-            flagRegistrations: activationResult.registrations.flags,
-            registrations: activationResult.registrations,
-            policyState: {
-                mode: loadResult.policy.mode,
-                trust_mode: loadResult.policy.trust_mode,
-                default_sandbox_profile: loadResult.policy.default_sandbox_profile,
-            },
-        };
-    }
-    catch {
-        return {
-            handlers: new Set(),
-            disabledReason: "extension_runtime_probe_failed",
-            commandDefinitions: [],
-            flagRegistrations: [],
-            registrations: null,
-            policyState: defaultPolicyState,
-        };
-    }
-}
-function collectActionContractDescriptors(extensionContracts, options = {}) {
-    /* c8 ignore start -- package-owned action descriptor permutations are covered in package-install integration suites. */
-    const descriptors = new Map();
-    for (const action of PM_TOOL_ACTIONS) {
-        const packageOwned = PACKAGE_OWNED_ACTIONS.has(action);
-        if (packageOwned && !options.includePackageOwnedActions) {
-            continue;
-        }
-        const commandPath = resolveActionCommandPath(action);
-        descriptors.set(action, {
-            action,
-            provider: packageOwned ? "extension" : "core",
-            requires_extension: packageOwned,
-            command_path: commandPath,
-        });
-    }
-    if (options.includePackageOwnedActions) {
-        for (const action of PACKAGE_OWNED_ACTIONS) {
-            if (descriptors.has(action)) {
-                continue;
-            }
-            descriptors.set(action, {
-                action,
-                provider: "extension",
-                requires_extension: true,
-                command_path: resolveActionCommandPath(action),
-            });
-        }
-    }
-    for (const contract of extensionContracts) {
-        if (descriptors.has(contract.action)) {
-            continue;
-        }
-        descriptors.set(contract.action, {
-            action: contract.action,
-            provider: "extension",
-            requires_extension: true,
-            command_path: normalizeCommandPath(contract.command),
-        });
-    }
-    return [...descriptors.values()].sort((left, right) => (left.action ?? "").localeCompare(right.action ?? ""));
-    /* c8 ignore stop */
-}
-function resolveActionAvailability(descriptor, runtimeProbe) {
-    /* c8 ignore start -- runtime extension availability branches are exercised in extension policy integration tests. */
-    if (descriptor.provider === "core" && !descriptor.requires_extension) {
-        return {
-            action: descriptor.action,
-            invocable: true,
-            available: true,
-            requires_extension: false,
-            provider: "core",
-            disabled_reason: null,
-            command_path: descriptor.command_path,
-            cli_exposed: descriptor.command_path !== null,
-        };
-    }
-    const commandPaths = descriptor.command_path
-        ? splitCommandPathAliases(descriptor.command_path)
-        : [];
-    const extensionCommandAvailable = commandPaths.some((commandPath) => runtimeProbe.handlers.has(commandPath));
-    const optionalPackageHint = commandPaths
-        .map((commandPath) => PACKAGE_OWNED_COMMAND_INSTALL_HINTS.get(commandPath))
-        .find((hint) => typeof hint === "string");
-    const invocable = runtimeProbe.disabledReason === null && extensionCommandAvailable;
-    return {
-        action: descriptor.action,
-        invocable,
-        available: invocable,
-        requires_extension: true,
-        provider: "extension",
-        disabled_reason: invocable
-            ? null
-            : (runtimeProbe.disabledReason ??
-                (optionalPackageHint
-                    ? `optional_package_not_installed:${optionalPackageHint}`
-                    : "extension_command_not_registered")),
-        command_path: descriptor.command_path,
-        cli_exposed: extensionCommandAvailable,
-        policy_state: {
-            mode: runtimeProbe.policyState.mode,
-            trust_mode: runtimeProbe.policyState.trust_mode,
-            default_sandbox_profile: runtimeProbe.policyState.default_sandbox_profile,
-        },
-    };
-    /* c8 ignore stop */
-}
-function resolveCoreCommandFlags(command) {
-    return (CORE_COMMAND_FLAG_CONTRACTS_BY_COMMAND.get(command) ?? GLOBAL_FLAG_CONTRACTS);
-}
-function isCoreCommandPath(command) {
-    if (PACKAGE_OWNED_COMMANDS.has(command)) {
-        return false;
-    }
-    return CORE_COMMAND_FLAG_CONTRACTS_BY_COMMAND.has(command);
-}
-function normalizeCommandForRuntimeFieldFlags(command) {
-    if (LIST_COMMAND_NAMES.has(command)) {
-        return "list";
-    }
-    if (command === "cal") {
-        return "calendar";
-    }
-    if (command === "ctx") {
-        return "context";
-    }
-    if (command === "update-many") {
-        return "update_many";
-    }
-    return command;
-}
-function toRuntimeLongFlagToken(token) {
-    const trimmed = token.trim();
-    if (!trimmed) {
-        return null;
-    }
-    if (trimmed.startsWith("--")) {
-        return trimmed;
-    }
-    if (trimmed.startsWith("-")) {
-        return null;
-    }
-    return `--${trimmed}`;
-}
-function toRuntimeShortFlagToken(token) {
-    const trimmed = token.trim();
-    if (!trimmed) {
-        return null;
-    }
-    if (trimmed.startsWith("--")) {
-        return null;
-    }
-    if (trimmed.startsWith("-")) {
-        return trimmed;
-    }
-    return null;
-}
-function buildRuntimeFieldFlagContracts(fieldRegistry) {
-    /* c8 ignore start -- runtime-field alias collision branches are validated in schema/runtime flag integration tests. */
-    const buckets = new Map();
-    for (const definition of fieldRegistry.definitions) {
-        const primaryFlag = toRuntimeLongFlagToken(definition.cli_flag);
-        if (!primaryFlag) {
-            continue;
-        }
-        const shortAlias = definition.cli_aliases
-            .map((alias) => toRuntimeShortFlagToken(alias))
-            .find((alias) => alias !== null);
-        const longAliases = definition.cli_aliases
-            .map((alias) => toRuntimeLongFlagToken(alias))
-            .filter((alias) => alias !== null && alias !== primaryFlag);
-        for (const command of definition.commands) {
-            const bucket = buckets.get(command) ?? {
-                flags: [],
-                seen: new Set(),
-            };
-            const primaryContract = shortAlias
-                ? { flag: primaryFlag, short: shortAlias }
-                : { flag: primaryFlag };
-            const primaryKey = `${primaryContract.flag}|${primaryContract.short ?? ""}`;
-            if (!bucket.seen.has(primaryKey)) {
-                bucket.seen.add(primaryKey);
-                bucket.flags.push(primaryContract);
-            }
-            for (const alias of longAliases) {
-                const key = `${alias}|`;
-                if (bucket.seen.has(key)) {
-                    continue;
-                }
-                bucket.seen.add(key);
-                bucket.flags.push({ flag: alias });
-            }
-            buckets.set(command, bucket);
-        }
-    }
-    const result = new Map();
-    for (const [command, bucket] of buckets.entries()) {
-        result.set(command, compactFlagAliasContracts(bucket.flags));
-    }
-    return result;
-    /* c8 ignore stop */
-}
-function mergeFlagContracts(primary, secondary) {
-    /* c8 ignore start -- flag merge dedupe permutations are covered via command-surface integration fixtures. */
-    const merged = [];
-    const seen = new Set();
-    for (const contract of [...primary, ...secondary]) {
-        const key = `${contract.flag}|${contract.short ?? ""}`;
-        if (seen.has(key)) {
-            continue;
-        }
-        seen.add(key);
-        merged.push(contract);
-    }
-    return compactFlagAliasContracts(merged);
-    /* c8 ignore stop */
-}
-function buildCommandFlagSurface(commands, extensionFlagMap, runtimeFieldFlagMap, includeSemanticMetadata) {
-    return commands
-        .map((command) => {
-        const isCoreCommand = isCoreCommandPath(command);
-        const coreFlags = isCoreCommand ? resolveCoreCommandFlags(command) : [];
-        const runtimeFlags = runtimeFieldFlagMap.get(normalizeCommandForRuntimeFieldFlags(command)) ?? [];
-        const extensionFlags = extensionFlagMap.get(command);
-        const coreWithRuntime = mergeFlagContracts(coreFlags, runtimeFlags);
-        const flags = mergeFlagContracts(coreWithRuntime, extensionFlags?.flags ?? []);
-        const provider = coreFlags.length > 0 && (extensionFlags?.flags.length ?? 0) > 0
-            ? "mixed"
-            : isCoreCommand
-                ? "core"
-                : "extension";
-        return {
-            command,
-            flags,
-            ...(includeSemanticMetadata
-                ? {
-                    canonical_command: canonicalSummaryCommand(command),
-                    visibility: resolvePmCommandVisibilityTier(canonicalSummaryCommand(command)),
-                    positionals: resolvePmCommandPositionalContract(command)?.slots ?? [],
-                    flag_invocations: enrichCliFlagInvocationContracts(command, flags),
-                }
-                : {}),
-            provider,
-            extension_sources: extensionFlags?.sources,
-        };
-    })
-        .sort((left, right) => left.command.localeCompare(right.command));
-}
-/** Build the executable alias projection from a command catalog and alias table. */
-export function buildCommandAliasSurface(commands, aliasContracts = PM_COMMAND_ALIAS_CONTRACTS) {
-    const commandSet = new Set(commands);
-    const grouped = new Map();
-    for (const entry of CANONICAL_COMMAND_ALIASES) {
-        const aliases = entry.aliases.filter((alias) => commandSet.has(alias));
-        grouped.set(entry.canonical, {
-            canonical: entry.canonical,
-            aliases,
-            contracts: [],
-        });
-    }
-    for (const contract of aliasContracts) {
-        if (!commandSet.has(contract.canonical)) {
-            continue;
-        }
-        if (contract.registration === "commander" &&
-            !commandSet.has(contract.alias)) {
-            continue;
-        }
-        const entry = grouped.get(contract.canonical) ?? {
-            canonical: contract.canonical,
-            aliases: [],
-            contracts: [],
-        };
-        if (!entry.aliases.includes(contract.alias)) {
-            entry.aliases.push(contract.alias);
-        }
-        entry.contracts.push(contract);
-        grouped.set(contract.canonical, entry);
-    }
-    return [...grouped.values()]
-        .map(({ contracts, ...entry }) => contracts.length === 0 ? entry : { ...entry, contracts })
-        .sort((left, right) => left.canonical.localeCompare(right.canonical));
-}
-function buildCommanderAliasSurface() {
-    return {
-        create_string_options: CREATE_COMMANDER_STRING_OPTION_CONTRACTS,
-        create_repeatable_options: CREATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS,
-        update_string_options: UPDATE_COMMANDER_STRING_OPTION_CONTRACTS,
-        update_repeatable_options: UPDATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS,
-        list_string_options: LIST_COMMANDER_STRING_OPTION_CONTRACTS,
-        search_string_options: SEARCH_COMMANDER_STRING_OPTION_CONTRACTS,
-        calendar_string_options: CALENDAR_COMMANDER_STRING_OPTION_CONTRACTS,
-        context_string_options: CONTEXT_COMMANDER_STRING_OPTION_CONTRACTS,
-        activity_string_options: ACTIVITY_COMMANDER_STRING_OPTION_CONTRACTS,
-    };
-}
-function resolveCreateRequiredOptionContract(typeDefinition, createMode) {
-    /* c8 ignore start -- create-option policy shaping is validated by dedicated create command contract fixtures. */
-    const baseRequiredOptions = new Set(["title", "type"]);
-    if (createMode === "strict") {
-        for (const field of typeDefinition.required_create_fields) {
-            baseRequiredOptions.add(field);
-        }
-        for (const field of typeDefinition.required_create_repeatables) {
-            baseRequiredOptions.add(field);
-        }
-    }
-    const policyState = resolveCommandOptionPolicyState(typeDefinition, "create", baseRequiredOptions);
-    const requiredOptionKeys = [...new Set(policyState.required)].sort((left, right) => left.localeCompare(right));
-    const requiredFlags = [
-        ...new Set(requiredOptionKeys.map((option) => commandOptionFlagLabel("create", option))),
-    ].sort((left, right) => left.localeCompare(right));
-    const requiredTypeOptions = [
-        ...new Set(typeDefinition.options
-            .filter((option) => option.required === true)
-            .map((option) => option.key)),
-    ].sort((left, right) => left.localeCompare(right));
-    return {
-        required_option_keys: requiredOptionKeys,
-        required_flags: requiredFlags,
-        required_type_options: requiredTypeOptions,
-        policy_errors: [...new Set(policyState.errors)].sort((left, right) => left.localeCompare(right)),
-    };
-    /* c8 ignore stop */
-}
-function buildCreateRequiredOptionContracts(typeRegistry) {
-    const byTypeStrict = {};
-    const byTypeProgressive = {};
-    for (const typeName of [...typeRegistry.types].sort((left, right) => left.localeCompare(right))) {
-        const typeDefinition = typeRegistry.by_type[typeName];
-        byTypeStrict[typeName] = resolveCreateRequiredOptionContract(typeDefinition, "strict");
-        byTypeProgressive[typeName] = resolveCreateRequiredOptionContract(typeDefinition, "progressive");
-    }
-    return {
-        default_create_mode: "strict",
-        by_create_mode: {
-            strict: {
-                by_type: byTypeStrict,
-            },
-            progressive: {
-                by_type: byTypeProgressive,
-            },
-        },
-    };
-}
-function attachCreateRequiredOptionContracts(schema, metadata) {
-    const branches = extractActionBranches(schema);
-    if (branches.length === 0) {
-        return schema;
-    }
-    let touched = false;
-    const enrichedBranches = branches.map((branch) => {
-        const properties = branch.properties;
-        if (typeof properties !== "object" || properties === null) {
-            return branch;
-        }
-        const actionProperty = properties.action;
-        if (typeof actionProperty !== "object" || actionProperty === null) {
-            return branch;
-        }
-        if (actionProperty.const !== "create") {
-            return branch;
-        }
-        touched = true;
-        return {
-            ...branch,
-            "x-create-required-options": metadata,
-        };
-    });
-    if (!touched) {
-        return schema;
-    }
-    return {
-        ...schema,
-        oneOf: enrichedBranches,
-    };
-}
-function resolveContractsSelection(options) {
-    const explicitlyScoped = normalizeToken(options.action) !== undefined ||
-        normalizeToken(options.command) !== undefined;
-    const projectionSelected = options.schemaOnly === true ||
-        options.flagsOnly === true ||
-        options.availabilityOnly === true;
-    const summary = options.summary === true ||
-        (options.full !== true &&
-            options.runtimeOnly !== true &&
-            !explicitlyScoped &&
-            !projectionSelected);
-    const schemaOnly = options.schemaOnly === true;
-    const flagsOnly = options.flagsOnly === true;
-    const availabilityOnly = options.availabilityOnly === true;
-    const runtimeOnly = options.runtimeOnly === true;
-    const fullOutput = options.full === true;
-    const selectedAction = normalizeToken(options.action);
-    const selectedCommand = normalizeToken(options.command);
-    const unfilteredDefaultBriefMode = !summary &&
-        !fullOutput &&
-        !schemaOnly &&
-        !flagsOnly &&
-        !availabilityOnly &&
-        !selectedAction &&
-        !selectedCommand;
-    return {
-        selectedAction,
-        selectedCommand,
-        summary,
-        schemaOnly,
-        flagsOnly,
-        availabilityOnly,
-        runtimeOnly,
-        fullOutput,
-        omitUnfilteredSchema: unfilteredDefaultBriefMode,
-        omitUnfilteredCommandFlags: unfilteredDefaultBriefMode,
-        omitUnfilteredCommanderAliases: unfilteredDefaultBriefMode ||
-            (selectedCommand !== undefined && !fullOutput),
-    };
-}
-function assertSingleContractsProjection(selection) {
-    const projectionFlagsEnabled = [
-        selection.summary,
-        selection.schemaOnly,
-        selection.flagsOnly,
-        selection.availabilityOnly,
-    ].filter((value) => value).length;
-    if (projectionFlagsEnabled > 1) {
-        throw new PmCliError("Choose only one projection flag: --summary, --schema-only, --flags-only, or --availability-only.", EXIT_CODE.USAGE);
-    }
-}
-async function readContractsSettings(pmRoot, readSettingsFn = readSettings) {
-    try {
-        return await readSettingsFn(pmRoot);
-    }
-    catch {
-        return structuredClone(SETTINGS_DEFAULTS);
-    }
-}
-async function resolveContractsRuntimeContext(global, pmRoot) {
-    const settings = await readContractsSettings(pmRoot);
-    const runtimeProbe = await resolveRuntimeExtensionActionProbe(global);
-    const typeRegistry = resolveItemTypeRegistry(settings, runtimeProbe.registrations ?? getActiveExtensionRegistrations());
-    const runtimeFieldRegistry = resolveRuntimeFieldRegistry(settings.schema);
-    const extensionContracts = collectExtensionCommandContracts(runtimeProbe);
-    return {
-        settings,
-        runtimeProbe,
-        typeRegistry,
-        statusRegistry: resolveRuntimeStatusRegistry(settings.schema),
-        runtimeFieldRegistry,
-        runtimeFieldFlagMap: buildRuntimeFieldFlagContracts(runtimeFieldRegistry),
-        createRequiredOptionContracts: buildCreateRequiredOptionContracts(typeRegistry),
-        extensionContracts,
-        mergedExtensionContracts: mergeExtensionContractsByAction(extensionContracts),
-        extensionFlagMap: collectExtensionFlagContractsByCommand(runtimeProbe.flagRegistrations),
-    };
-}
-function shouldIncludePackageOwnedActions(selection) {
-    return (selection.availabilityOnly &&
-        ((selection.selectedAction !== undefined &&
-            PACKAGE_OWNED_ACTIONS.has(selection.selectedAction)) ||
-            (selection.selectedCommand !== undefined &&
-                PACKAGE_OWNED_COMMANDS.has(selection.selectedCommand))));
-}
-function collectContractsActionDescriptors(selection, mergedExtensionContracts) {
-    const actionDescriptors = collectActionContractDescriptors(mergedExtensionContracts, {
-        includePackageOwnedActions: shouldIncludePackageOwnedActions(selection),
-    });
-    if (selection.selectedAction === undefined &&
-        selection.selectedCommand === undefined) {
-        const deprecatedActions = new Set(PM_DEPRECATED_TOOL_ACTIONS);
-        return actionDescriptors.filter((descriptor) => !deprecatedActions.has(descriptor.action));
-    }
-    if (shouldIncludePackageOwnedActions(selection) &&
-        selection.selectedCommand !== undefined &&
-        PACKAGE_OWNED_COMMANDS.has(selection.selectedCommand) &&
-        !actionDescriptors.some((entry) => entry.command_path === selection.selectedCommand)) {
-        actionDescriptors.push({
-            action: packageOwnedActionForCommand(selection.selectedCommand),
-            provider: "extension",
-            requires_extension: true,
-            command_path: selection.selectedCommand,
-        });
-    }
-    return actionDescriptors;
-}
-function assertKnownContractsAction(selection, actionDescriptors) {
-    const actionNames = new Set(actionDescriptors.map((entry) => entry.action));
-    if (selection.selectedAction && !actionNames.has(selection.selectedAction)) {
-        throw new PmCliError(`Unknown action: "${selection.selectedAction}".`, EXIT_CODE.USAGE);
-    }
-}
-function buildContractsCommandCatalog(actionDescriptors, mergedExtensionContracts) {
-    return [
-        ...new Set([
-            ...PM_CORE_COMMAND_NAMES.filter((entry) => !PACKAGE_OWNED_COMMANDS.has(entry)),
-            ...[...CORE_COMMAND_FLAG_CONTRACTS_BY_COMMAND.keys()].filter((entry) => !PACKAGE_OWNED_COMMANDS.has(entry)),
-            /* c8 ignore next -- action descriptors always include concrete command paths in command-scoped test fixtures. */
-            ...actionDescriptors.flatMap((entry) => entry.command_path ? splitCommandPathAliases(entry.command_path) : []),
-            ...mergedExtensionContracts.flatMap((entry) => entry.command.split("|")),
-        ]),
-    ]
-        .map((entry) => normalizeCommandPath(entry))
-        .filter((entry) => entry.length > 0)
-        .sort((left, right) => left.localeCompare(right));
-}
-function buildCommandNamespaceError(command, namespaceChildren) {
-    const displayedNamespaceChildren = namespaceChildren.slice(0, COMMAND_NAMESPACE_DISPLAY_LIMIT);
-    const hiddenNamespaceChildCount = namespaceChildren.length - displayedNamespaceChildren.length;
-    const displayedChildCommandList = hiddenNamespaceChildCount > 0
-        ? `${displayedNamespaceChildren.join(", ")}, and ${hiddenNamespaceChildCount} more`
-        : displayedNamespaceChildren.join(", ");
-    const fallbackCandidates = namespaceChildren.slice(0, COMMAND_NAMESPACE_FALLBACK_LIMIT);
-    const childCommandExamples = namespaceChildren
-        .slice(0, 5)
-        .map((childCommand) => `pm contracts --command "${childCommand}" --flags-only --json`);
-    const suggestedChildCommand = namespaceChildren[0];
-    return new PmCliError(`Command "${command}" is a command namespace. Choose a concrete child command: ${displayedChildCommandList}.`, EXIT_CODE.USAGE, {
-        code: "command_namespace",
-        required: "Use a concrete child command path listed under this namespace.",
-        why: "Command groups expose help at the namespace root, but command flag contracts belong to executable child commands.",
-        examples: childCommandExamples,
-        nextSteps: [
-            `Retry with a child command, for example: ${childCommandExamples[0]}`,
-        ],
-        recovery: {
-            suggested_retry: `pm contracts --command "${suggestedChildCommand}" --flags-only --json`,
-            fallback_candidates: fallbackCandidates.map((childCommand) => ({
-                source: "command_namespace",
-                command: `pm contracts --command "${childCommand}" --flags-only --json`,
-                reason: `Child command under ${command}`,
-            })),
-        },
-    });
-}
-function buildPackageOwnedCommandError(command, packageHint) {
-    return new PmCliError(`Unknown command: "${command}". Command "${command}" is provided by the optional "${packageHint}" package. Run "pm install ${packageHint} --project" and retry.`, EXIT_CODE.USAGE, {
-        code: "unknown_command",
-        required: `Install the optional "${packageHint}" package, or choose a command from pm contracts --flags-only --json.`,
-        why: "Command contracts include core commands plus commands registered by active packages and extensions.",
-        examples: [
-            `pm install ${packageHint} --project`,
-            `pm contracts --command ${command} --flags-only --json`,
-        ],
-        nextSteps: [
-            `Install the optional package first: pm install ${packageHint} --project`,
-        ],
-        recovery: {
-            suggested_retry: `pm install ${packageHint} --project`,
-        },
-    });
-}
-function buildUnknownCommandError(command) {
-    return new PmCliError(`Unknown command: "${command}".`, EXIT_CODE.USAGE, {
-        code: "unknown_command",
-        required: "Use a command path listed by pm contracts --flags-only --json.",
-        why: "Command contracts are generated from the active core, package, and extension command registry.",
-        examples: ["pm contracts --flags-only --json", "pm --help"],
-        nextSteps: [
-            "Verify spelling and active packages/extensions, then rerun with a known command path.",
-        ],
-        recovery: {
-            suggested_retry: "pm contracts --flags-only --json",
-        },
-    });
-}
-function assertKnownContractsCommand(selection, commandCatalog) {
-    if (!selection.selectedCommand) {
-        return;
-    }
-    const commandNames = new Set(commandCatalog);
-    if (commandNames.has(selection.selectedCommand)) {
-        return;
-    }
-    const namespaceChildren = commandCatalog.filter((command) => command.startsWith(`${selection.selectedCommand} `));
-    if (namespaceChildren.length > 0) {
-        throw buildCommandNamespaceError(selection.selectedCommand, namespaceChildren);
-    }
-    const packageHint = PACKAGE_OWNED_COMMAND_INSTALL_HINTS.get(selection.selectedCommand);
-    if (packageHint) {
-        throw buildPackageOwnedCommandError(selection.selectedCommand, packageHint);
-    }
-    throw buildUnknownCommandError(selection.selectedCommand);
-}
-function resolveContractsActionContext(selection, runtime) {
-    const actionDescriptors = collectContractsActionDescriptors(selection, runtime.mergedExtensionContracts);
-    assertKnownContractsAction(selection, actionDescriptors);
-    const commandCatalog = buildContractsCommandCatalog(actionDescriptors, runtime.mergedExtensionContracts);
-    assertKnownContractsCommand(selection, commandCatalog);
-    const selectedPackageOwnedAction = selection.selectedCommand
-        ? PACKAGE_OWNED_COMMAND_ACTIONS.get(selection.selectedCommand)
-        : undefined;
-    const commandScopedDescriptors = selection.selectedCommand
-        ? actionDescriptors.filter((descriptor) => selectedPackageOwnedAction
-            ? descriptor.action === selectedPackageOwnedAction
-            : actionDescriptorMatchesSelectedCommand(descriptor, selection.selectedCommand))
-        : actionDescriptors;
-    if (selection.selectedCommand &&
-        selection.selectedAction &&
-        !commandScopedDescriptors.some((descriptor) => descriptor.action === selection.selectedAction)) {
-        throw new PmCliError(`Action "${selection.selectedAction}" is not mapped to command "${selection.selectedCommand}" in contracts output.`, EXIT_CODE.USAGE);
-    }
-    const scopedActionDescriptors = selection.selectedAction
-        ? commandScopedDescriptors.filter((descriptor) => descriptor.action === selection.selectedAction)
-        : commandScopedDescriptors;
-    const allActionAvailability = [
-        ...new Map(scopedActionDescriptors
-            .map((descriptor) => resolveActionAvailability(descriptor, runtime.runtimeProbe))
-            .map((entry) => [
-            /* c8 ignore next -- keyed dedupe by action|path is covered by runtime policy integration tests. */
-            selectedPackageOwnedAction
-                ? entry.action
-                : `${entry.action}|${entry.command_path ?? ""}`,
-            entry,
-        ])).values(),
-    ];
-    const actionAvailability = selection.runtimeOnly &&
-        !selection.selectedAction &&
-        !selection.availabilityOnly
-        ? allActionAvailability.filter((entry) => entry.invocable)
-        : allActionAvailability;
-    return {
-        actionDescriptors,
-        commandCatalog,
-        commandScopedDescriptors,
-        scopedActionDescriptors,
-        selectedPackageOwnedAction,
-        actionAvailability,
-        actions: [...new Set(actionAvailability.map((entry) => entry.action))],
-    };
-}
-function buildSchemaActionSet(schema) {
-    return new Set(extractActionBranches(schema)
-        .map((entry) => {
-        const properties = entry.properties;
-        /* c8 ignore start -- PM_TOOL_PARAMETERS_SCHEMA action branches always carry a properties object; the property-less fallback is validated in schema-level contract tests. */
-        if (typeof properties !== "object" || properties === null) {
-            return null;
-        }
-        /* c8 ignore stop */
-        const actionProperty = properties.action;
-        /* c8 ignore start -- PM_TOOL_PARAMETERS_SCHEMA action branches always carry an action object; the missing-action fallback is validated in schema-level contract tests. */
-        if (typeof actionProperty !== "object" || actionProperty === null) {
-            return null;
-        }
-        /* c8 ignore stop */
-        const actionConst = actionProperty.const;
-        /* c8 ignore start -- the action.const is always a string in PM_TOOL_PARAMETERS_SCHEMA; the non-string fallback is validated in schema-level contract tests. */
-        return typeof actionConst === "string" ? actionConst : null;
-        /* c8 ignore stop */
-    })
-        .filter((entry) => entry !== null));
-}
-function buildMergedContractsSchema(mergedExtensionContracts) {
-    const schema = PM_TOOL_PARAMETERS_SCHEMA;
-    const schemaBranches = extractActionBranches(schema);
-    const schemaActionSet = buildSchemaActionSet(schema);
-    const extensionBranches = mergedExtensionContracts
-        .filter((contract) => !schemaActionSet.has(contract.action))
-        .map((contract) => buildExtensionActionSchemaBranch(contract));
-    return extensionBranches.length > 0
-        ? {
-            ...schema,
-            oneOf: [...schemaBranches, ...extensionBranches],
-        }
-        : schema;
-}
-function filterContractsSchema(selection, actionContext, mergedSchema) {
-    const descriptorActionSet = new Set(actionContext.actionDescriptors.map((descriptor) => descriptor.action));
-    const filteredSchema = selection.selectedAction
-        ? filterSchemaByAction(mergedSchema, selection.selectedAction)
-        : selection.selectedCommand
-            ? filterSchemaByActions(mergedSchema, new Set(actionContext.scopedActionDescriptors.map((descriptor) => descriptor.action)))
-            : filterSchemaByActions(mergedSchema, descriptorActionSet);
-    return selection.runtimeOnly && !selection.selectedAction
-        ? filterSchemaByActions(filteredSchema, new Set(actionContext.actions))
-        : filteredSchema;
-}
-function resolveContractsSchemaContext(selection, runtime, actionContext) {
-    const mergedSchema = buildMergedContractsSchema(runtime.mergedExtensionContracts);
-    const includeSchemaSurface = !selection.flagsOnly && !selection.availabilityOnly;
-    const filteredSchema = includeSchemaSurface
-        ? attachCreateRequiredOptionContracts(filterContractsSchema(selection, actionContext, mergedSchema), runtime.createRequiredOptionContracts)
-        : filterContractsSchema(selection, actionContext, mergedSchema);
-    return { mergedSchema, filteredSchema };
-}
-function resolveContractsCommands(selection, actionContext) {
-    if (selection.selectedCommand !== undefined) {
-        return [selection.selectedCommand];
-    }
-    if (selection.selectedAction) {
-        return resolveScopedCommandsFromActionDescriptors(actionContext.scopedActionDescriptors, actionContext.commandCatalog);
-    }
-    return actionContext.commandCatalog;
-}
-function resolveOutputCommands(selection, commands) {
-    if (selection.selectedCommand !== undefined ||
-        selection.selectedAction !== undefined) {
-        return commands;
-    }
-    const hiddenAliases = new Set(PM_COMMAND_ALIAS_CONTRACTS.filter((contract) => contract.hidden && contract.lifecycle === "deprecated").map((contract) => contract.alias));
-    return commands.filter((command) => !hiddenAliases.has(command));
-}
-function canonicalSummaryCommand(command) {
-    const rootCommand = command.split(" ")[0];
-    if (rootCommand.startsWith("list-"))
-        return "list";
-    if (rootCommand.startsWith("history-"))
-        return "history";
-    return COMMAND_ALIAS_TO_CANONICAL.get(rootCommand) ?? rootCommand;
-}
-const COMMAND_OPERATION_INTENTS = new Map([
-    ["activate", "Activate"],
-    ["adopt", "Adopt"],
-    ["adopt-all", "Adopt all"],
-    ["catalog", "Catalog"],
-    ["complete", "Complete"],
-    ["create", "Create"],
-    ["deactivate", "Deactivate"],
-    ["delete", "Delete"],
-    ["describe", "Describe"],
-    ["doctor", "Diagnose"],
-    ["explore", "Explore"],
-    ["init", "Initialize"],
-    ["inspect", "Inspect"],
-    ["install", "Install"],
-    ["list", "List"],
-    ["manage", "Manage"],
-    ["migrate", "Migrate"],
-    ["mutate", "Mutate"],
-    ["reload", "Reload"],
-    ["restore", "Restore"],
-    ["run", "Run"],
-    ["snapshot", "Manage snapshots for"],
-    ["uninstall", "Uninstall"],
-    ["upgrade", "Upgrade"],
-]);
-const COMMAND_INTENT_SUBJECT_OVERRIDES = new Map([
-    ["extension adopt-all", "extensions"],
-    ["package adopt-all", "packages"],
-    ["workspace snapshot list", "workspace snapshots"],
-]);
-function summarizeCommandIntent(command, extensionContracts) {
-    const declared = COMMAND_INTENTS.get(command) ??
-        (command.includes(" ")
-            ? undefined
-            : COMMAND_INTENTS.get(canonicalSummaryCommand(command)));
-    if (declared !== undefined) {
-        return { intent: declared, intent_source: "command" };
-    }
-    const extensionContract = extensionContracts.find((contract) => splitCommandPathAliases(contract.command).includes(command));
-    if (extensionContract?.intent !== null &&
-        extensionContract?.intent !== undefined) {
-        return { intent: extensionContract.intent, intent_source: "command" };
-    }
-    if (extensionContract?.description !== null &&
-        extensionContract?.description !== undefined) {
-        return {
-            intent: extensionContract.description,
-            intent_source: "description",
-        };
-    }
-    const tokens = command.split(" ");
-    const operation = tokens.at(-1);
-    const subject = tokens.slice(0, -1).join(" ");
-    const verb = COMMAND_OPERATION_INTENTS.get(operation);
-    const intentSubject = COMMAND_INTENT_SUBJECT_OVERRIDES.get(command) ?? subject;
-    return {
-        intent: verb === undefined || subject.length === 0
-            ? `Run ${command}.`
-            : `${verb} ${intentSubject}.`,
-        intent_source: "generated",
-    };
-}
-function buildCommandSummarySurface(commands, extensionContracts = [], options = {}) {
-    const includeFormatBudgets = options.includeFormatBudgets ?? true;
-    const includeIntentProvenance = options.includeIntentProvenance ?? true;
-    return [...new Set(commands.map(normalizeCommandPath))]
-        .filter((command) => command.length > 0)
-        .sort((left, right) => left.localeCompare(right))
-        .map((command) => {
-        const budget = resolvePmCommandOutputBudget(command, {
-            generateFallback: true,
-        });
-        const rootCommand = command.split(" ")[0];
-        const canonicalRoot = COMMAND_ALIAS_TO_CANONICAL.get(rootCommand) ??
-            (rootCommand.startsWith("list-")
-                ? "list"
-                : rootCommand.startsWith("history-")
-                    ? "history"
-                    : rootCommand);
-        const availableFlags = new Set([
-            ...resolveCoreCommandFlags(command).map((contract) => contract.flag),
-            ...extensionContracts
-                .filter((contract) => splitCommandPathAliases(contract.command).includes(command))
-                .flatMap((contract) => contract.flags.map((flag) => flag.flag)),
-        ]);
-        const flags = (AGENT_BOOTSTRAP_FLAGS.get(command) ??
-            AGENT_BOOTSTRAP_FLAGS.get(canonicalRoot) ??
-            AGENT_BOUNDED_FLAG_PRIORITY).filter((flag) => availableFlags.has(flag));
-        const intent = summarizeCommandIntent(command, extensionContracts);
-        return {
-            command,
-            intent: intent.intent,
-            ...(includeIntentProvenance || intent.intent_source !== "command"
-                ? { intent_source: intent.intent_source }
-                : {}),
-            ...(flags.length > 0 ? { flags } : {}),
-            default_max_estimated_tokens: budget.default_max_estimated_tokens,
-            ...(includeFormatBudgets
-                ? {
-                    default_max_estimated_tokens_by_format: {
-                        ...budget.default_max_estimated_tokens_by_format,
-                    },
-                }
-                : {}),
-        };
-    });
-}
-function buildCommandOutputContracts(commands) {
-    return commands.map((command) => ({
-        budget: resolvePmCommandOutputBudget(command, {
-            generateFallback: true,
-        }),
-        envelope: resolvePmCommandOutputEnvelope(command),
-    }));
-}
-function buildCommandExitContractGroups(commands) {
-    const groups = new Map();
-    for (const command of commands) {
-        const contract = resolvePmCommandExitContract(command);
-        const exitCodes = contract === undefined
-            ? [
-                EXIT_CODE.SUCCESS,
-                EXIT_CODE.GENERIC_FAILURE,
-                EXIT_CODE.USAGE,
-                EXIT_CODE.NOT_FOUND,
-                EXIT_CODE.CONFLICT,
-                EXIT_CODE.DEPENDENCY_FAILED,
-            ]
-            : contract.exit_codes;
-        const key = exitCodes.join(",");
-        const group = groups.get(key) ?? { commands: [], exit_codes: exitCodes };
-        group.commands.push(command);
-        groups.set(key, group);
-    }
-    return [...groups.values()];
-}
-function resolveExtensionCommandContracts(selection, runtime, outputCommands) {
-    if (selection.selectedCommand) {
-        return runtime.extensionContracts.filter((entry) => splitCommandPathAliases(entry.command).includes(selection.selectedCommand));
-    }
-    if (selection.selectedAction) {
-        const outputCommandSet = new Set(outputCommands);
-        return runtime.extensionContracts.filter((entry) => splitCommandPathAliases(entry.command).some((command) => outputCommandSet.has(command)));
-    }
-    return runtime.extensionContracts;
-}
-function createContractsResult(selection, schemaContext, actionContext, outputCommands) {
-    return {
-        schema_version: 
-        /* c8 ignore next -- schema version/id fallbacks are exercised by schema snapshot tests. */
-        typeof schemaContext.mergedSchema["x-schema-version"] === "string"
-            ? schemaContext.mergedSchema["x-schema-version"]
-            : null,
-        schema_id: 
-        /* c8 ignore next -- schema version/id fallbacks are exercised by schema snapshot tests. */
-        typeof schemaContext.mergedSchema.$id === "string"
-            ? schemaContext.mergedSchema.$id
-            : null,
-        selected: {
-            action: selection.selectedAction ?? null,
-            command: selection.selectedCommand ?? null,
-            summary: selection.summary,
-            schema_only: selection.schemaOnly,
-            flags_only: selection.flagsOnly,
-            availability_only: selection.availabilityOnly,
-            runtime_only: selection.runtimeOnly,
-            command_scoped: selection.selectedCommand !== undefined,
-        },
-        commands: selection.summary ? [] : outputCommands,
-        ...(!selection.summary && !selection.flagsOnly
-            ? {
-                actions: actionContext.actions,
-                action_availability: actionContext.actionAvailability,
-            }
-            : {}),
-    };
-}
-function attachRuntimeContractsResult(result, runtime, selection) {
-    const selectedCommand = selection.selectedCommand;
-    result.runtime_schema = {
-        statuses: runtime.statusRegistry.definitions.map((definition) => definition.id),
-        open_status: runtime.statusRegistry.open_status,
-        close_status: runtime.statusRegistry.close_status,
-        canceled_status: runtime.statusRegistry.canceled_status,
-        types: [...runtime.typeRegistry.types],
-        fields_by_command: Object.fromEntries([...runtime.runtimeFieldRegistry.command_to_fields.entries()]
-            .filter(([command]) => selectedCommand === undefined || command === selectedCommand)
-            .map(([command, definitions]) => [
-            command,
-            [
-                ...new Set(definitions.map((definition) => `--${definition.cli_flag}`)),
-            ].sort((left, right) => left.localeCompare(right)),
-        ])),
-    };
-    if (selectedCommand !== undefined && !selection.fullOutput) {
-        return;
-    }
-    result.extension_contracts = {
-        capabilities: [...PM_EXTENSION_CAPABILITY_CONTRACTS],
-        services: [...PM_EXTENSION_SERVICE_NAME_CONTRACTS],
-        policy_modes: [...PM_EXTENSION_POLICY_MODE_CONTRACTS],
-        policy_mode_scope: "extensions.policy.mode",
-        policy_surfaces: [...PM_EXTENSION_POLICY_SURFACE_CONTRACTS],
-        trust_modes: [...PM_EXTENSION_TRUST_MODE_CONTRACTS],
-        trust_mode_scope: "extensions.policy.trust_mode",
-        sandbox_profiles: [...PM_EXTENSION_SANDBOX_PROFILE_CONTRACTS],
-        manifest_versions: [1, 2],
-        compatibility: {
-            current: "v2",
-            previous: ["v1"],
-            breaking_strategy: "versioned_breaking",
-        },
-    };
-    result.governance_contracts = {
-        ownership_enforcement_modes: [...GOVERNANCE_OWNERSHIP_ENFORCEMENT_VALUES],
-        create_modes: [...GOVERNANCE_CREATE_MODE_DEFAULT_VALUES],
-        close_validation_modes: [...GOVERNANCE_CLOSE_VALIDATION_DEFAULT_VALUES],
-        workflow_enforcement_modes: [...GOVERNANCE_WORKFLOW_ENFORCEMENT_VALUES],
-    };
-    result.relationship_kind_contracts = [
-        ...BUILTIN_RELATIONSHIP_KINDS,
-        ...(runtime.runtimeProbe.registrations?.relationship_kinds ?? []).flatMap((registration) => registration.definitions),
-    ]
-        .sort((left, right) => left.kind.localeCompare(right.kind))
-        .map((definition) => ({
-        canonical: definition.kind,
-        aliases: [...(definition.aliases ?? [])],
-        ...(definition.inverse === undefined
-            ? {}
-            : { inverse: definition.inverse }),
-        ordering: definition.ordering,
-        hierarchy: definition.hierarchy,
-    }));
-}
-function attachSchemaContractsResult(result, selection, schemaContext, extensionCommandContracts) {
-    if (selection.flagsOnly || selection.availabilityOnly) {
-        return;
-    }
-    if (!selection.omitUnfilteredSchema) {
-        result.schema = schemaContext.filteredSchema;
-        result.extension_commands = extensionCommandContracts;
-        return;
-    }
-    result.schema_omitted_reason = "unfiltered_default_brief";
-    result.extension_commands = extensionCommandContracts;
-}
-function attachFlagContractsResult(result, selection, runtime, outputCommands, commandAliases) {
-    if (selection.schemaOnly || selection.availabilityOnly) {
-        return;
-    }
-    if (!selection.omitUnfilteredCommandFlags) {
-        result.command_flags = buildCommandFlagSurface(outputCommands, runtime.extensionFlagMap, runtime.runtimeFieldFlagMap, selection.selectedCommand !== undefined);
-        const commandSet = new Set(outputCommands);
-        result.list_projections = Object.entries(LIST_COMMAND_DEFAULT_PROJECTIONS)
-            .filter(([command]) => commandSet.has(command))
-            .map(([command, defaultProjection]) => ({
-            command,
-            default: defaultProjection,
-            brief_fields: [...BRIEF_LIST_FIELDS],
-            compact_fields: [...DEFAULT_COMPACT_LIST_FIELDS],
-        }));
-    }
-    else {
-        result.command_flags_omitted_reason = "unfiltered_default_brief";
-    }
-    result.command_aliases = commandAliases;
-}
-function attachCommanderAliasContractsResult(result, selection) {
-    if (selection.schemaOnly ||
-        selection.flagsOnly ||
-        selection.availabilityOnly) {
-        return;
-    }
-    if (!selection.omitUnfilteredCommanderAliases) {
-        result.commander_aliases = buildCommanderAliasSurface();
-        return;
-    }
-    result.commander_aliases_omitted_reason = selection.selectedCommand
-        ? "command_scoped"
-        : "unfiltered_default_brief";
-}
-/** Attach the compact agent-facing command semantics shared by summary and full projections. */
-function attachAgentCommandContractsResult(result, outputCommands, extensionCommandContracts, options) {
-    result.command_summaries = buildCommandSummarySurface(outputCommands, extensionCommandContracts, {
-        includeFormatBudgets: options.includeFormatBudgets,
-        includeIntentProvenance: options.includeIntentProvenance,
-    });
-    result.output_policy = {
-        token_estimate: "ceil(utf8_bytes / 4)",
-        degradation_ladder: [...PM_OUTPUT_DEGRADATION_STEPS],
-        allows_unbounded_opt_out: true,
-    };
-    result.output_projection_contracts = {
-        global_ladder_field: "output_policy.degradation_ladder",
-        global_ladder_scope: "union_not_per_command",
-        discovery: "pm contracts --command <command> --summary",
-        ...(options.includeProjectionModeMatrix
-            ? {
-                commands: [...new Set(outputCommands.map(normalizeCommandPath))]
-                    .filter((command) => resolveReadOutputSurface(command) !== undefined)
-                    .sort((left, right) => left.localeCompare(right))
-                    .map((command) => ({
-                    command,
-                    modes: [...readOutputIncludeModeOptions(command).keys()],
-                })),
-            }
-            : {}),
-    };
-    result.grammar_contracts = {
-        nouns: PM_CLI_GRAMMAR_CONTRACT.nouns,
-        shared_verbs: PM_CLI_GRAMMAR_CONTRACT.shared_verbs,
-        scope_before_verb: PM_CLI_GRAMMAR_CONTRACT.scope_before_verb,
-        visible_top_level_ceiling: PM_CLI_GRAMMAR_CONTRACT.visible_top_level_ceiling,
-        ceiling_raise_requires_pm_item: PM_CLI_GRAMMAR_CONTRACT.ceiling_raise_requires_pm_item,
-        positional_shape_budget: PM_CLI_GRAMMAR_CONTRACT.positional_shape_budget,
-        positional_shape_count: new Set(PM_COMMAND_POSITIONAL_CONTRACTS.map(({ slots }) => positionalShapeKey(slots))).size,
-        positional_action_count: PM_POSITIONAL_ACTION_CONTRACTS.length,
-        positional_action_parents: [
-            ...new Set(PM_POSITIONAL_ACTION_CONTRACTS.map(({ parent }) => parent)),
-        ].sort((left, right) => left.localeCompare(right)),
-        ...(options.includePositionalSignatures
-            ? { positional_signatures: PM_COMMAND_POSITIONAL_CONTRACTS }
-            : {}),
-    };
-}
-/** Implements run contracts for the public runtime surface of this module. */
-export async function runContracts(options, global) {
-    const selection = resolveContractsSelection(options);
-    assertSingleContractsProjection(selection);
-    const pmRoot = resolvePmRoot(process.cwd(), global.path);
-    const runtime = await resolveContractsRuntimeContext(global, pmRoot);
-    const actionContext = resolveContractsActionContext(selection, runtime);
-    const schemaContext = resolveContractsSchemaContext(selection, runtime, actionContext);
-    const commands = resolveContractsCommands(selection, actionContext);
-    const outputCommands = resolveOutputCommands(selection, commands);
-    const result = createContractsResult(selection, schemaContext, actionContext, outputCommands);
-    const extensionCommandContracts = resolveExtensionCommandContracts(selection, runtime, outputCommands);
-    const includeCommandDetails = selection.fullOutput || selection.selectedCommand !== undefined;
-    if (selection.summary || selection.fullOutput) {
-        attachAgentCommandContractsResult(result, outputCommands, extensionCommandContracts, {
-            includeFormatBudgets: includeCommandDetails,
-            includeIntentProvenance: includeCommandDetails,
-            includePositionalSignatures: includeCommandDetails,
-            includeProjectionModeMatrix: includeCommandDetails,
-        });
-    }
-    if (selection.summary) {
-        return result;
-    }
-    const commandAliases = buildCommandAliasSurface(actionContext.commandCatalog);
-    if (!(selection.flagsOnly && !selection.fullOutput)) {
-        attachRuntimeContractsResult(result, runtime, selection);
-    }
-    attachSchemaContractsResult(result, selection, schemaContext, extensionCommandContracts);
-    attachFlagContractsResult(result, selection, runtime, outputCommands, commandAliases);
-    attachCommanderAliasContractsResult(result, selection);
-    if (selection.selectedCommand === "assurance" || selection.fullOutput) {
-        result.assurance_contracts = {
-            measurement_source_kinds: [...ASSURANCE_MEASUREMENT_SOURCE_KINDS],
-            gate_triggers: [...ASSURANCE_GATE_TRIGGERS],
-        };
-    }
-    if (selection.fullOutput && result.grammar_contracts) {
-        result.grammar_contracts.destinations = PM_COMMAND_DESTINATION_CONTRACTS;
-    }
-    // pm-4os2: snapshot the static MCP tool surface in the full projection so
-    // `pnpm contracts:check` (CI static gate) fails on unintended inputSchema
-    // drift in src/mcp/tool-definitions.ts.
-    if (selection.fullOutput &&
-        !selection.schemaOnly &&
-        !selection.flagsOnly &&
-        !selection.availabilityOnly) {
-        result.mcp_tools = buildMcpToolContracts();
-        result.context_intents = getActiveContextIntentContracts();
-        result.read_output_dimensions = PM_READ_OUTPUT_SURFACE_CONTRACTS;
-        result.error_codes = PM_ERROR_CODE_CATALOG;
-        result.command_output_contracts =
-            buildCommandOutputContracts(outputCommands);
-        result.diagnostic_output_contracts = PM_DIAGNOSTIC_OUTPUT_BUDGET_CONTRACTS;
-        result.command_exit_contracts = {
-            vocabulary: PM_COMMAND_EXIT_OUTCOME_CONTRACTS,
-            command_sets: buildCommandExitContractGroups(outputCommands),
-        };
-    }
-    return result;
-}
-/** Public contract for test only contracts command, shared by SDK and presentation-layer consumers. */
-export const _testOnlyContractsCommand = {
-    actionDescriptorMatchesSelectedCommand,
-    attachCreateRequiredOptionContracts,
-    buildExtensionActionSchemaBranch,
-    buildCommandSummarySurface,
-    buildCommandOutputContracts,
-    buildCommandExitContractGroups,
-    buildRuntimeFieldFlagContracts,
-    collectActionContractDescriptors,
-    collectExtensionCommandContracts,
-    collectExtensionFlagContractsByCommand,
-    extractActionBranches,
-    extensionSchemaPropertyNameFromFlag,
-    filterSchemaByAction,
-    filterSchemaByActions,
-    isCoreCommandPath,
-    mergeExtensionContractsByAction,
-    normalizeExtensionFlagName,
-    normalizeActionNameFromCommand,
-    normalizeCommandForRuntimeFieldFlags,
-    normalizeCommandPath,
-    packageOwnedActionForCommand,
-    readContractsSettings,
-    resolveActionCommandPath,
-    resolveActionAvailability,
-    resolveCoreCommandFlags,
-    resolveRuntimeExtensionActionProbe,
-    resolveScopedCommandsFromActionDescriptors,
-    splitCommandPathAliases,
-    toRuntimeLongFlagToken,
-    toRuntimeShortFlagToken,
-};
+!(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]="5fbd5bc2-6f35-5f7e-b357-7c16e6991787")}catch(e2){}})();import{EXIT_CODE,SETTINGS_DEFAULTS,PmCliError,activateExtensions,getActiveExtensionRegistrations,loadExtensions,pathExists,commandOptionFlagLabel,resolveCommandOptionPolicyState,resolveItemTypeRegistry,resolveRuntimeFieldRegistry,resolveRuntimeStatusRegistry,getSettingsPath,resolvePmRoot,readSettings}from"../runtime-primitives.js";import{buildMcpToolContracts}from"../../mcp/tool-definitions.js";import{ACTIVITY_COMMANDER_STRING_OPTION_CONTRACTS,ACTIVITY_FLAG_CONTRACTS,AGGREGATE_FLAG_CONTRACTS,ASSURANCE_FLAG_CONTRACTS,APPEND_FLAG_CONTRACTS,CALENDAR_COMMANDER_STRING_OPTION_CONTRACTS,CALENDAR_FLAG_CONTRACTS,CLAIM_FLAG_CONTRACTS,CLOSE_TASK_FLAG_CONTRACTS,COMMENTS_FLAG_CONTRACTS,CLOSE_FLAG_CONTRACTS,CLOSE_MANY_FLAG_CONTRACTS,COMPLETION_FLAG_CONTRACTS,CONFIG_FLAG_CONTRACTS,CONTRACTS_FLAG_CONTRACTS,COPY_FLAG_CONTRACTS,CONTEXT_COMMANDER_STRING_OPTION_CONTRACTS,CONTEXT_FLAG_CONTRACTS,CREATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS,CREATE_COMMANDER_STRING_OPTION_CONTRACTS,CREATE_FLAG_CONTRACTS,DELETE_FLAG_CONTRACTS,DEPS_FLAG_CONTRACTS,GRAPH_FLAG_CONTRACTS,DOCS_FLAG_CONTRACTS,EXTENSION_ACTIVATE_FLAG_CONTRACTS,EXTENSION_ADOPT_ALL_FLAG_CONTRACTS,EXTENSION_ADOPT_FLAG_CONTRACTS,EXTENSION_CATALOG_FLAG_CONTRACTS,EXTENSION_DEACTIVATE_FLAG_CONTRACTS,EXTENSION_DESCRIBE_FLAG_CONTRACTS,EXTENSION_DOCTOR_FLAG_CONTRACTS,EXTENSION_EXPLORE_FLAG_CONTRACTS,EXTENSION_FLAG_CONTRACTS,EXTENSION_INIT_FLAG_CONTRACTS,EXTENSION_INSTALL_FLAG_CONTRACTS,EXTENSION_MANAGE_FLAG_CONTRACTS,EXTENSION_MIGRATE_FLAG_CONTRACTS,EXTENSION_RELOAD_FLAG_CONTRACTS,EXTENSION_UNINSTALL_FLAG_CONTRACTS,FILES_FLAG_CONTRACTS,FOCUS_FLAG_CONTRACTS,GC_FLAG_CONTRACTS,GET_FLAG_CONTRACTS,GUIDE_FLAG_CONTRACTS,GLOBAL_FLAG_CONTRACTS,HEALTH_FLAG_CONTRACTS,HISTORY_FLAG_CONTRACTS,HISTORY_COMPACT_FLAG_CONTRACTS,HISTORY_REDACT_FLAG_CONTRACTS,HISTORY_REPAIR_FLAG_CONTRACTS,HISTORY_AUTHOR_ACKNOWLEDGE_FLAG_CONTRACTS,INSTALL_FLAG_CONTRACTS,INIT_FLAG_CONTRACTS,ITEM_COMPLETE_FLAG_CONTRACTS,ITEM_MUTATE_FLAG_CONTRACTS,ITEM_REOPEN_FLAG_CONTRACTS,LEARNINGS_FLAG_CONTRACTS,LIST_COMMANDER_STRING_OPTION_CONTRACTS,LIST_FILTER_FLAG_CONTRACTS,MERGE_FLAG_CONTRACTS,NOTES_FLAG_CONTRACTS,PACKAGE_FLAG_CONTRACTS,PACKAGE_INIT_FLAG_CONTRACTS,PM_EXTENSION_CAPABILITY_CONTRACTS,PM_EXTENSION_POLICY_MODE_CONTRACTS,PM_EXTENSION_POLICY_SURFACE_CONTRACTS,PM_EXTENSION_SANDBOX_PROFILE_CONTRACTS,PM_EXTENSION_SERVICE_NAME_CONTRACTS,PM_EXTENSION_TRUST_MODE_CONTRACTS,PM_OUTPUT_DEGRADATION_STEPS,PLAN_FLAG_CONTRACTS,PM_CORE_COMMAND_NAMES,PM_DEPRECATED_TOOL_ACTIONS,PM_TOOL_ACTIONS,PM_TOOL_PARAMETERS_SCHEMA,REINDEX_FLAG_CONTRACTS,RELEASE_FLAG_CONTRACTS,RESTORE_FLAG_CONTRACTS,SCHEMA_FLAG_CONTRACTS,PROFILE_FLAG_CONTRACTS,SEARCH_COMMANDER_STRING_OPTION_CONTRACTS,EVAL_FLAG_CONTRACTS,WORKSPACE_FLAG_CONTRACTS,NEXT_FLAG_CONTRACTS,SEARCH_FLAG_CONTRACTS,STATS_FLAG_CONTRACTS,DUPLICATES_FLAG_CONTRACTS,START_TASK_FLAG_CONTRACTS,PAUSE_TASK_FLAG_CONTRACTS,TELEMETRY_FLAG_CONTRACTS,TEST_ALL_FLAG_CONTRACTS,TEST_FLAG_CONTRACTS,TEST_RUNS_FLAG_CONTRACTS,UPDATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS,UPDATE_COMMANDER_STRING_OPTION_CONTRACTS,UPDATE_FLAG_CONTRACTS,UPDATE_MANY_FLAG_CONTRACTS,UPGRADE_FLAG_CONTRACTS,VALIDATE_FLAG_CONTRACTS,compactFlagAliasContracts,PM_COMMAND_ALIAS_CONTRACTS,PM_DIAGNOSTIC_OUTPUT_BUDGET_CONTRACTS,resolvePmCommandOutputBudget}from"../cli-contracts.js";import{PM_HISTORY_COMMAND_ALIASES,resolvePmHistoryOperation}from"./command-aliases.js";import{PM_POSITIONAL_ACTION_FLAG_CONTRACTS}from"./flag-contracts.js";import{GOVERNANCE_CLOSE_VALIDATION_DEFAULT_VALUES,GOVERNANCE_CREATE_MODE_DEFAULT_VALUES,GOVERNANCE_OWNERSHIP_ENFORCEMENT_VALUES,GOVERNANCE_WORKFLOW_ENFORCEMENT_VALUES}from"../../types.js";import{BRIEF_LIST_FIELDS,DEFAULT_COMPACT_LIST_FIELDS,LIST_COMMAND_DEFAULT_PROJECTIONS}from"../query/list.js";import{getActiveContextIntentContracts}from"../context-intent-contracts.js";import{readOutputIncludeModeOptions,resolveReadOutputSurface,PM_READ_OUTPUT_SURFACE_CONTRACTS}from"../read-output-contracts.js";import{enrichCliFlagInvocationContracts}from"../flag-invocation-contracts.js";import{resolvePmCommandVisibilityTier}from"../agent-capability-contracts.js";import{PM_ERROR_CODE_CATALOG}from"../generated-error-code-catalog.js";import{resolvePmCommandOutputEnvelope}from"../output-contracts.js";import{PM_COMMAND_EXIT_OUTCOME_CONTRACTS,resolvePmCommandExitContract}from"./command-exit-contracts.js";import{BUILTIN_RELATIONSHIP_KINDS}from"../relationship-kinds/contract.js";import{ASSURANCE_GATE_TRIGGERS,ASSURANCE_MEASUREMENT_SOURCE_KINDS}from"../governance/assurance.js";import{PM_CLI_GRAMMAR_CONTRACT,PM_COMMAND_DESTINATION_CONTRACTS,PM_COMMAND_POSITIONAL_CONTRACTS,PM_POSITIONAL_ACTION_CONTRACTS,positionalShapeKey,resolvePmCommandPositionalContract}from"./grammar-contracts.js";const AGENT_BOOTSTRAP_FLAGS=new Map([["claim",["--if-available","--next","--type","--priority","--token-budget","--explain-ranking"]],["close",["--reason","--validate-close","--resolution","--expected-result","--actual-result","--message"]],["context",["--limit","--after","--depth","--section","--token-budget","--explain-ranking"]],["contracts",["--command","--flags-only","--summary","--runtime-only","--availability-only","--full"]],["create",["--title","--type","--status","--priority","--dep","--comment"]],["get",["--full","--depth","--fields","--tree","--tree-depth","--format"]],["health",["--check-only","--summary","--brief","--check-telemetry","--strict-exit","--full"]],["list",["--status","--type","--limit","--after","--brief","--fields"]],["next",["--limit","--blocked-limit","--ready-only","--token-budget","--explain-ranking","--format"]],["search",["--mode","--status","--type","--limit","--after","--fields"]],["update",["--status","--message","--dep","--comment","--file","--test"]],["validate",["--check-resolution","--check-history-drift","--check-storage-integrity","--counts","--strict-exit","--fix-hints"]]]);const AGENT_BOUNDED_FLAG_PRIORITY=["--limit","--after","--offset","--token-budget","--brief","--summary","--compact","--fields","--full","--format","--since","--until"];const LIST_COMMAND_NAMES=new Set(["list","list-all","list-draft","list-open","list-in-progress","list-blocked","list-closed","list-canceled"]);const PACKAGE_OWNED_ACTIONS=new Set(["calendar","guide","reindex","completion","test-runs-list","test-runs-status","test-runs-logs","test-runs-stop","test-runs-resume","templates-list","templates-save","templates-show"]);const PACKAGE_OWNED_COMMANDS=new Set(["cal","calendar","completion","completion-statuses","completion-tags","completion-types","guide","reindex","templates","templates list","templates save","templates show","test-runs","test-runs list","test-runs status","test-runs logs","test-runs stop","test-runs resume"]);const PACKAGE_OWNED_COMMAND_INSTALL_HINTS=new Map([["cal","calendar"],["calendar","calendar"],["completion","guide-shell"],["completion-statuses","guide-shell"],["completion-tags","guide-shell"],["completion-types","guide-shell"],["guide","guide-shell"],["reindex","search-advanced"],["templates","templates"],["templates list","templates"],["templates save","templates"],["templates show","templates"],["test-runs","linked-test-adapters"],["test-runs list","linked-test-adapters"],["test-runs status","linked-test-adapters"],["test-runs logs","linked-test-adapters"],["test-runs stop","linked-test-adapters"],["test-runs resume","linked-test-adapters"]]);const PACKAGE_OWNED_ACTION_COMMAND_PATHS=new Map([["calendar","calendar|cal"],["guide","guide"],["reindex","reindex"],["completion","completion"],["test-runs-list","test-runs|test-runs list"],["test-runs-status","test-runs status"],["test-runs-logs","test-runs logs"],["test-runs-stop","test-runs stop"],["test-runs-resume","test-runs resume"],["templates-list","templates|templates list"],["templates-save","templates save"],["templates-show","templates show"]]);const PACKAGE_OWNED_COMMAND_ACTIONS=new Map([...PACKAGE_OWNED_ACTION_COMMAND_PATHS.entries()].flatMap(([action,commandPaths])=>splitCommandPathAliases(commandPaths).map(commandPath=>[commandPath,action])));const CANONICAL_COMMAND_ALIASES=[{canonical:"context",aliases:["ctx"]},{canonical:"package",aliases:["extension","packages"]}];const COMMAND_ALIAS_TO_CANONICAL=new Map(CANONICAL_COMMAND_ALIASES.flatMap(entry=>entry.aliases.map(alias=>[alias,entry.canonical])));const COMMAND_NAMESPACE_DISPLAY_LIMIT=10;const COMMAND_NAMESPACE_FALLBACK_LIMIT=20;const COMMAND_INTENTS=new Map([["activity","Read activity."],["aggregate","Group counts."],["append","Append body."],["assurance","Evaluate assurance."],["assurance derive","Derive checks."],["assurance risk","Select checks for changes."],["assurance lineages","Measure recurrence coverage."],["beads","Manage Beads interoperability."],["cal","Manage calendar integration."],["calendar","Manage calendar integration."],["changelog","Generate changelog output."],["claim","Claim work."],["close","Close work."],["close-many","Close matching work."],["close-task","Close task work."],["command-kit","Inspect command authoring primitives."],["comments","Manage comments."],["comments-audit","Audit comment governance."],["completion","Generate shell completions."],["config","Manage settings."],["context","Build context."],["contracts","Inspect contracts."],["copy","Copy work."],["create","Create work."],["dedupe-audit","Audit duplicate work."],["dedupe-merge","Merge duplicate work."],["delete","Delete work."],["deps","Manage deps."],["duplicates","Find duplicate clusters."],["docs","Link docs."],["eval","Run evaluations."],["event","Manage events."],["events","Read events."],["files","Link files."],["focus","Manage focus."],["gc","Clean caches."],["get","Read item."],["graph","Query graph."],["guide","Show user guides."],["health","Check health."],["help","Show help."],["history","Inspect history."],["init","Initialize workspace."],["install","Install packages."],["item","Mutate items."],["learnings","Manage learnings."],["list","List work."],["list-all","List work across every status."],["list-blocked","List blocked work."],["list-canceled","List canceled work."],["list-closed","List closed work."],["list-draft","List draft work."],["list-in-progress","List in-progress work."],["list-open","List open work."],["meet","Record meeting context."],["merge","Manage tracker merges."],["next","Pick next work."],["notes","Manage notes."],["normalize","Normalize tracker data."],["ops","Run operations."],["package","Manage packages."],["packages","Manage packages."],["pause-task","Pause task work."],["plan","Manage plans."],["profile","Manage profiles."],["reindex","Refresh search index."],["release","Release claim."],["remind","Manage reminders."],["restore","Restore history."],["schema","Customize schema."],["search","Search work."],["search-advanced","Run advanced search."],["start-task","Start task work."],["stats","Show stats."],["telemetry","Manage telemetry."],["templates","Manage work templates."],["test","Run linked tests."],["test-all","Run all linked tests."],["test-runs","Inspect background test runs."],["todos","Manage source-code todos."],["twin","Manage repository twins."],["update","Update work."],["update-many","Update matching work."],["upgrade","Upgrade packages."],["validate","Validate data."],["vcs","Inspect version-control context."],["workspace","Manage workspaces."],["history-author-acknowledge","Acknowledge reviewed history authors."],["history-compact","Compact history."],["history-redact","Redact sensitive history values."],["history-repair","Repair history integrity."]]);const EXTENSION_LIFECYCLE_FLAG_CONTRACTS=[["init",EXTENSION_INIT_FLAG_CONTRACTS],["install",EXTENSION_INSTALL_FLAG_CONTRACTS],["uninstall",EXTENSION_UNINSTALL_FLAG_CONTRACTS],["explore",EXTENSION_EXPLORE_FLAG_CONTRACTS],["manage",EXTENSION_MANAGE_FLAG_CONTRACTS],["describe",EXTENSION_DESCRIBE_FLAG_CONTRACTS],["reload",EXTENSION_RELOAD_FLAG_CONTRACTS],["doctor",EXTENSION_DOCTOR_FLAG_CONTRACTS],["catalog",EXTENSION_CATALOG_FLAG_CONTRACTS],["adopt",EXTENSION_ADOPT_FLAG_CONTRACTS],["adopt-all",EXTENSION_ADOPT_ALL_FLAG_CONTRACTS],["activate",EXTENSION_ACTIVATE_FLAG_CONTRACTS],["deactivate",EXTENSION_DEACTIVATE_FLAG_CONTRACTS],["migrate",EXTENSION_MIGRATE_FLAG_CONTRACTS]];const PACKAGE_LIFECYCLE_FLAG_CONTRACTS=[...EXTENSION_LIFECYCLE_FLAG_CONTRACTS.map(([subcommand,flags])=>subcommand==="init"?[subcommand,PACKAGE_INIT_FLAG_CONTRACTS]:[subcommand,flags]),["upgrade",UPGRADE_FLAG_CONTRACTS]];const CORE_COMMAND_FLAG_CONTRACT_ENTRIES=[...EXTENSION_LIFECYCLE_FLAG_CONTRACTS.map(([subcommand,flags])=>[`extension ${subcommand}`,flags]),...PACKAGE_LIFECYCLE_FLAG_CONTRACTS.flatMap(([subcommand,flags])=>[[`package ${subcommand}`,flags],[`packages ${subcommand}`,flags]]),["init",INIT_FLAG_CONTRACTS],["config",CONFIG_FLAG_CONTRACTS],["extension",EXTENSION_FLAG_CONTRACTS],["package",PACKAGE_FLAG_CONTRACTS],["packages",PACKAGE_FLAG_CONTRACTS],["install",INSTALL_FLAG_CONTRACTS],["create",CREATE_FLAG_CONTRACTS],["item mutate",ITEM_MUTATE_FLAG_CONTRACTS],["item complete",ITEM_COMPLETE_FLAG_CONTRACTS],["item reopen",ITEM_REOPEN_FLAG_CONTRACTS],["copy",COPY_FLAG_CONTRACTS],["focus",FOCUS_FLAG_CONTRACTS],["update",UPDATE_FLAG_CONTRACTS],["update-many",UPDATE_MANY_FLAG_CONTRACTS],["upgrade",UPGRADE_FLAG_CONTRACTS],["calendar",CALENDAR_FLAG_CONTRACTS],["cal",CALENDAR_FLAG_CONTRACTS],["context",CONTEXT_FLAG_CONTRACTS],["ctx",CONTEXT_FLAG_CONTRACTS],["get",GET_FLAG_CONTRACTS],["search",SEARCH_FLAG_CONTRACTS],["eval",EVAL_FLAG_CONTRACTS],["workspace",WORKSPACE_FLAG_CONTRACTS],["workspace position",[]],["workspace snapshot",WORKSPACE_FLAG_CONTRACTS],["workspace snapshot create",WORKSPACE_FLAG_CONTRACTS],["workspace snapshot list",WORKSPACE_FLAG_CONTRACTS],["workspace snapshot inspect",WORKSPACE_FLAG_CONTRACTS],["workspace snapshot restore",WORKSPACE_FLAG_CONTRACTS],["workspace snapshot delete",WORKSPACE_FLAG_CONTRACTS],["next",NEXT_FLAG_CONTRACTS],["aggregate",AGGREGATE_FLAG_CONTRACTS],["deps",DEPS_FLAG_CONTRACTS],["graph",GRAPH_FLAG_CONTRACTS],["guide",GUIDE_FLAG_CONTRACTS],["reindex",REINDEX_FLAG_CONTRACTS],["history",HISTORY_FLAG_CONTRACTS],["history-compact",HISTORY_COMPACT_FLAG_CONTRACTS],["history-redact",HISTORY_REDACT_FLAG_CONTRACTS],["history-repair",HISTORY_REPAIR_FLAG_CONTRACTS],["history-author-acknowledge",HISTORY_AUTHOR_ACKNOWLEDGE_FLAG_CONTRACTS],["merge",MERGE_FLAG_CONTRACTS],["schema",SCHEMA_FLAG_CONTRACTS],["profile",PROFILE_FLAG_CONTRACTS],["plan",PLAN_FLAG_CONTRACTS],["restore",RESTORE_FLAG_CONTRACTS],["delete",DELETE_FLAG_CONTRACTS],["close",CLOSE_FLAG_CONTRACTS],["close-many",CLOSE_MANY_FLAG_CONTRACTS],["append",APPEND_FLAG_CONTRACTS],["claim",CLAIM_FLAG_CONTRACTS],["release",RELEASE_FLAG_CONTRACTS],["start-task",START_TASK_FLAG_CONTRACTS],["pause-task",PAUSE_TASK_FLAG_CONTRACTS],["close-task",CLOSE_TASK_FLAG_CONTRACTS],["comments",COMMENTS_FLAG_CONTRACTS],["notes",NOTES_FLAG_CONTRACTS],["learnings",LEARNINGS_FLAG_CONTRACTS],["files",FILES_FLAG_CONTRACTS],["docs",DOCS_FLAG_CONTRACTS],["test",TEST_FLAG_CONTRACTS],["test-all",TEST_ALL_FLAG_CONTRACTS],["telemetry",TELEMETRY_FLAG_CONTRACTS],["test-runs",TEST_RUNS_FLAG_CONTRACTS],["gc",GC_FLAG_CONTRACTS],["stats",STATS_FLAG_CONTRACTS],["duplicates",DUPLICATES_FLAG_CONTRACTS],["validate",VALIDATE_FLAG_CONTRACTS],["health",HEALTH_FLAG_CONTRACTS],["assurance",ASSURANCE_FLAG_CONTRACTS],...PM_POSITIONAL_ACTION_FLAG_CONTRACTS,["contracts",CONTRACTS_FLAG_CONTRACTS],["completion",COMPLETION_FLAG_CONTRACTS],["activity",ACTIVITY_FLAG_CONTRACTS],...[...LIST_COMMAND_NAMES].map(command=>[command,LIST_FILTER_FLAG_CONTRACTS])];const CORE_COMMAND_FLAG_CONTRACTS_BY_COMMAND=new Map(CORE_COMMAND_FLAG_CONTRACT_ENTRIES);for(const{alias,canonical}of PM_HISTORY_COMMAND_ALIASES){CORE_COMMAND_FLAG_CONTRACTS_BY_COMMAND.set(canonical,CORE_COMMAND_FLAG_CONTRACTS_BY_COMMAND.get(alias))}function packageOwnedActionForCommand(command){const exactAction=PACKAGE_OWNED_COMMAND_ACTIONS.get(command);if(exactAction){return exactAction}if(command.startsWith("test-runs ")){return`test-runs-${command.slice("test-runs ".length)}`}if(command.startsWith("templates ")){return`templates-${command.slice("templates ".length)}`}return command}function resolveActionCommandPath(action){const historyAlias=PM_HISTORY_COMMAND_ALIASES.find(contract=>contract.alias===action);if(historyAlias)return`${historyAlias.canonical}|${historyAlias.alias}`;if(PM_CORE_COMMAND_NAMES.includes(action)){return normalizeCommandPath(action)}if(action.startsWith("extension-")){return normalizeCommandPath(`extension ${action.slice("extension-".length)}`)}if(action.startsWith("package-")){return normalizeCommandPath(`package ${action.slice("package-".length)}`)}if(action.startsWith("item-")){return normalizeCommandPath(`item ${action.slice("item-".length)}`)}if(action.startsWith("test-runs-")){return normalizeCommandPath(`test-runs ${action.slice("test-runs-".length)}`)}if(action.startsWith("templates-")){return normalizeCommandPath(`templates ${action.slice("templates-".length)}`)}if(PACKAGE_OWNED_ACTIONS.has(action)){return PACKAGE_OWNED_ACTION_COMMAND_PATHS.get(action)??normalizeCommandPath(action)}return null}function actionDescriptorMatchesSelectedCommand(descriptor,selectedCommand){const historyOperation=resolvePmHistoryOperation(selectedCommand);if(historyOperation!==selectedCommand)return descriptor.action===historyOperation;if(descriptor.command_path===null){return false}return splitCommandPathAliases(descriptor.command_path).some(commandPath=>{if(commandPath===selectedCommand){return true}return commandPath.startsWith(`${selectedCommand} `)||selectedCommand.startsWith(`${commandPath} `)})}function splitCommandPathAliases(commandPath){return commandPath.split("|").map(entry=>normalizeCommandPath(entry)).filter(entry=>entry.length>0)}function resolveScopedCommandsFromActionDescriptors(descriptors,commandCatalog){const commandSet=new Set(commandCatalog);const scoped=new Set;for(const descriptor of descriptors){if(!descriptor.command_path){continue}for(const commandPath of splitCommandPathAliases(descriptor.command_path)){const tokens=commandPath.split(" ").filter(entry=>entry.length>0);if(tokens.length===0){continue}for(let end=tokens.length;end>0;end-=1){const candidate=tokens.slice(0,end).join(" ");if(!commandSet.has(candidate)){continue}scoped.add(candidate);break}}}return[...scoped].sort((left,right)=>left.localeCompare(right))}function normalizeToken(value){if(typeof value!=="string"){return void 0}const trimmed=value.trim().toLowerCase();return trimmed.length>0?trimmed:void 0}function extractActionBranches(schema){const oneOf=schema.oneOf;if(!Array.isArray(oneOf)){return[]}return oneOf.filter(entry=>typeof entry==="object"&&entry!==null)}function filterSchemaByAction(schema,action){if(!action){return{...schema}}const branches=extractActionBranches(schema);const filtered=branches.filter(entry=>{const properties=entry.properties;if(typeof properties!=="object"||properties===null){return false}const actionProperty=properties.action;if(typeof actionProperty!=="object"||actionProperty===null){return false}return actionProperty.const===action});return{...schema,oneOf:filtered}}function filterSchemaByActions(schema,actions){const branches=extractActionBranches(schema);const filtered=branches.filter(entry=>{const properties=entry.properties;if(typeof properties!=="object"||properties===null){return false}const actionProperty=properties.action;if(typeof actionProperty!=="object"||actionProperty===null){return false}const actionConst=actionProperty.const;return typeof actionConst==="string"&&actions.has(actionConst)});return{...schema,oneOf:filtered}}function normalizeCommandPath(value){return value.trim().toLowerCase().split(/\s+/).filter(entry=>entry.length>0).join(" ")}function normalizeActionNameFromCommand(commandPath){return commandPath.replace(/\s+/g,"-")}function toOptionalTrimmedString(value){if(typeof value!=="string"){return null}const trimmed=value.trim();return trimmed.length>0?trimmed:null}function normalizeStringList(values){if(!Array.isArray(values)){return[]}const normalized=[];const seen=new Set;for(const value of values){const trimmed=toOptionalTrimmedString(value);if(!trimmed||seen.has(trimmed)){continue}seen.add(trimmed);normalized.push(trimmed)}return normalized}function assignExtensionFlagBoolean(contract,key,enabled){if(enabled){contract[key]=true}}function normalizeExtensionFlagName(value,kind){if(value==null){return null}if(typeof value!=="string"){throw new TypeError("Expected string for extension flag name.")}const trimmed=value.trim();if(trimmed.length===0){return null}if(kind==="long"){return trimmed.startsWith("--")&&trimmed.length>2?trimmed:null}return trimmed.startsWith("-")&&!trimmed.startsWith("--")&&trimmed.length>1?trimmed:null}function toExtensionFlagContract(definition){const normalizedLong=normalizeExtensionFlagName(definition.long,"long");const normalizedShort=normalizeExtensionFlagName(definition.short,"short");const flag=normalizedLong??normalizedShort;if(!flag){return null}const contract={flag};if(normalizedShort&&normalizedLong){contract.short=normalizedShort}assignExtensionFlagBoolean(contract,"required",definition.required===true);assignExtensionFlagBoolean(contract,"repeatable",definition.repeatable===true);assignExtensionFlagBoolean(contract,"list",definition.list===true);const description=toOptionalTrimmedString(definition.description);if(description){contract.description=description}const valueName=toOptionalTrimmedString(definition.value_name);if(valueName){contract.value_name=valueName}const rawValueType=[toOptionalTrimmedString(definition.value_type),toOptionalTrimmedString(definition.type),valueName?"string":null].find(candidate=>candidate==="string"||candidate==="number"||candidate==="boolean");if(rawValueType){contract.value_type=rawValueType}return contract}function collectExtensionFlagContractsByCommand(registrations){const grouped=new Map;for(const registration of registrations){const commandPath=normalizeCommandPath(registration.target_command);if(commandPath.length===0){continue}const bucket=grouped.get(commandPath)??{flags:[],sources:[],dedupe:new Set,sourceDedupe:new Set};const sourceKey=`${registration.layer}:${registration.name}`;if(!bucket.sourceDedupe.has(sourceKey)){bucket.sourceDedupe.add(sourceKey);bucket.sources.push({layer:registration.layer,name:registration.name})}for(const definition of registration.flags){const contract=toExtensionFlagContract(definition);if(!contract){continue}const key=`${contract.flag}|${contract.short??""}`;if(bucket.dedupe.has(key)){continue}bucket.dedupe.add(key);bucket.flags.push(contract)}grouped.set(commandPath,bucket)}const normalized=new Map;for(const[commandPath,bucket]of grouped.entries()){normalized.set(commandPath,{flags:bucket.flags,sources:bucket.sources.sort((left,right)=>{const layerOrder=left.layer.localeCompare(right.layer);if(layerOrder!==0){return layerOrder}return(left.name??"").localeCompare(right.name??"")})})}return normalized}function collectExtensionCommandContracts(runtimeProbe){const flagsByCommand=collectExtensionFlagContractsByCommand(runtimeProbe.flagRegistrations);const definitionsByCommand=new Map;for(const definition of runtimeProbe.commandDefinitions){const command=normalizeCommandPath(definition.command);if(command.length===0){continue}const action=toOptionalTrimmedString(definition.action)??normalizeActionNameFromCommand(command);const args=Array.isArray(definition.arguments)?definition.arguments.map(argument=>{const name=toOptionalTrimmedString(argument.name);if(!name){return null}return{name,required:argument.required===true,variadic:argument.variadic===true,description:toOptionalTrimmedString(argument.description)}}).filter(argument=>argument!==null):[];definitionsByCommand.set(command,{command,action,source:{layer:definition.layer,name:definition.name},description:toOptionalTrimmedString(definition.description),intent:toOptionalTrimmedString(definition.intent),arguments:args,flags:flagsByCommand.get(command)?.flags??[],examples:normalizeStringList(definition.examples),failure_hints:normalizeStringList(definition.failure_hints)})}const extensionCommands=new Set;for(const command of runtimeProbe.handlers){extensionCommands.add(normalizeCommandPath(command))}for(const command of definitionsByCommand.keys()){extensionCommands.add(command)}for(const command of flagsByCommand.keys()){extensionCommands.add(command)}const contracts=[];for(const command of[...extensionCommands].sort((left,right)=>left.localeCompare(right))){const definition=definitionsByCommand.get(command);contracts.push(buildCollectedExtensionCommandContract(command,definition,flagsByCommand.get(command)?.flags??[]))}return contracts}function buildCollectedExtensionCommandContract(command,definition,registeredFlags){if(definition){return{...definition,flags:definition.flags.length>0?definition.flags:registeredFlags}}return{command,action:normalizeActionNameFromCommand(command),source:null,description:null,intent:null,arguments:[],flags:registeredFlags,examples:[],failure_hints:[]}}function extensionSchemaPropertyNameFromFlag(flag){const normalized=flag.flag.replace(/^-+/,"").trim();if(normalized.length===0){return null}const camelCased=normalized.replace(/-([a-z0-9])/g,(_match,char)=>char.toUpperCase());const cleaned=camelCased.replace(/[^a-zA-Z0-9]/g,"");return cleaned.length>0?cleaned:null}function buildExtensionArgumentSchema(argument,action){if(argument.variadic){return{type:"array",items:{type:"string"},description:argument.description??`Variadic argument '${argument.name}' for extension action '${action}'.`}}return{type:"string",description:argument.description??`Argument '${argument.name}' for extension action '${action}'.`}}function buildExtensionFlagSchema(flag,action){const valueType=flag.value_type??"boolean";const schemaType=valueType==="boolean"?"boolean":valueType==="number"?["number","string"]:"string";const acceptsMultipleValues=flag.repeatable===true||flag.list===true;return{type:acceptsMultipleValues?"array":schemaType,...acceptsMultipleValues?{items:{type:schemaType}}:{},description:flag.description??`Extension option '${flag.flag}' for action '${action}'.`}}function buildExtensionActionSchemaBranch(contract){const commands=contract.command.split("|").map(command=>command.trim()).filter(command=>command.length>0);const properties={action:{type:"string",const:contract.action,description:contract.intent??contract.description??`Invoke extension command '${contract.command}'.`}};const required=["action"];for(const argument of contract.arguments){properties[argument.name]=buildExtensionArgumentSchema(argument,contract.action);if(argument.required){required.push(argument.name)}}for(const flag of contract.flags){const propertyName=extensionSchemaPropertyNameFromFlag(flag);if(!propertyName||properties[propertyName]!==void 0){continue}properties[propertyName]=buildExtensionFlagSchema(flag,contract.action);if(flag.required===true){required.push(propertyName)}}return{type:"object",properties,required,additionalProperties:true,"x-extension-source":contract.source,"x-extension-command":commands[0]??contract.command,"x-extension-commands":commands}}function mergeExtensionFlagContract(existing,incoming){existing.description??=incoming.description;existing.value_name??=incoming.value_name;existing.value_type??=incoming.value_type;if(incoming.required===true){existing.required=true}if(incoming.repeatable===true){existing.repeatable=true}}function mergeExtensionContractsByAction(contracts){const byAction=new Map;for(const contract of contracts){const existing=byAction.get(contract.action);if(!existing){byAction.set(contract.action,{...contract,flags:[...contract.flags],examples:[...contract.examples],failure_hints:[...contract.failure_hints]});continue}existing.command=[...new Set([existing.command,contract.command])].sort((left,right)=>left.localeCompare(right)).join("|");existing.arguments=existing.arguments.length>=contract.arguments.length?existing.arguments:contract.arguments;const flagKeys=new Set(existing.flags.map(flag=>`${flag.flag}|${flag.short??""}`));for(const flag of contract.flags){const key=`${flag.flag}|${flag.short??""}`;if(!flagKeys.has(key)){flagKeys.add(key);existing.flags.push(flag)}else{const existingFlag=existing.flags.find(candidate=>`${candidate.flag}|${candidate.short??""}`===key);if(existingFlag){mergeExtensionFlagContract(existingFlag,flag)}}}existing.examples=[...new Set([...existing.examples,...contract.examples])];existing.failure_hints=[...new Set([...existing.failure_hints,...contract.failure_hints])]}return[...byAction.values()].sort((left,right)=>left.action.localeCompare(right.action))}async function resolveRuntimeExtensionActionProbe(global2,readSettingsFn=readSettings){const defaultPolicyState={mode:SETTINGS_DEFAULTS.extensions.policy.mode,trust_mode:SETTINGS_DEFAULTS.extensions.policy.trust_mode,default_sandbox_profile:SETTINGS_DEFAULTS.extensions.policy.default_sandbox_profile};if(global2.noExtensions){return{handlers:new Set,disabledReason:"extensions_disabled",commandDefinitions:[],flagRegistrations:[],registrations:null,policyState:defaultPolicyState}}const pmRoot=resolvePmRoot(process.cwd(),global2.path);if(!await pathExists(getSettingsPath(pmRoot))){return{handlers:new Set,disabledReason:null,commandDefinitions:[],flagRegistrations:[],registrations:null,policyState:defaultPolicyState}}try{const settings=await readSettingsFn(pmRoot);const loadResult=await loadExtensions({pmRoot,settings,cwd:process.cwd(),noExtensions:false});const activationResult=await activateExtensions({...loadResult,loaded:loadResult.loaded});const handlers=new Set(activationResult.commands.handlers.map(entry=>normalizeCommandPath(entry.command)));return{handlers,disabledReason:null,commandDefinitions:activationResult.registrations.commands,flagRegistrations:activationResult.registrations.flags,registrations:activationResult.registrations,policyState:{mode:loadResult.policy.mode,trust_mode:loadResult.policy.trust_mode,default_sandbox_profile:loadResult.policy.default_sandbox_profile}}}catch{return{handlers:new Set,disabledReason:"extension_runtime_probe_failed",commandDefinitions:[],flagRegistrations:[],registrations:null,policyState:defaultPolicyState}}}function collectActionContractDescriptors(extensionContracts,options={}){const descriptors=new Map;for(const action of PM_TOOL_ACTIONS){const packageOwned=PACKAGE_OWNED_ACTIONS.has(action);if(packageOwned&&!options.includePackageOwnedActions){continue}const commandPath=resolveActionCommandPath(action);descriptors.set(action,{action,provider:packageOwned?"extension":"core",requires_extension:packageOwned,command_path:commandPath})}if(options.includePackageOwnedActions){for(const action of PACKAGE_OWNED_ACTIONS){if(descriptors.has(action)){continue}descriptors.set(action,{action,provider:"extension",requires_extension:true,command_path:resolveActionCommandPath(action)})}}for(const contract of extensionContracts){if(descriptors.has(contract.action)){continue}descriptors.set(contract.action,{action:contract.action,provider:"extension",requires_extension:true,command_path:normalizeCommandPath(contract.command)})}return[...descriptors.values()].sort((left,right)=>(left.action??"").localeCompare(right.action??""))}function resolveActionAvailability(descriptor,runtimeProbe){if(descriptor.provider==="core"&&!descriptor.requires_extension){return{action:descriptor.action,invocable:true,available:true,requires_extension:false,provider:"core",disabled_reason:null,command_path:descriptor.command_path,cli_exposed:descriptor.command_path!==null}}const commandPaths=descriptor.command_path?splitCommandPathAliases(descriptor.command_path):[];const extensionCommandAvailable=commandPaths.some(commandPath=>runtimeProbe.handlers.has(commandPath));const optionalPackageHint=commandPaths.map(commandPath=>PACKAGE_OWNED_COMMAND_INSTALL_HINTS.get(commandPath)).find(hint=>typeof hint==="string");const invocable=runtimeProbe.disabledReason===null&&extensionCommandAvailable;return{action:descriptor.action,invocable,available:invocable,requires_extension:true,provider:"extension",disabled_reason:invocable?null:runtimeProbe.disabledReason??(optionalPackageHint?`optional_package_not_installed:${optionalPackageHint}`:"extension_command_not_registered"),command_path:descriptor.command_path,cli_exposed:extensionCommandAvailable,policy_state:{mode:runtimeProbe.policyState.mode,trust_mode:runtimeProbe.policyState.trust_mode,default_sandbox_profile:runtimeProbe.policyState.default_sandbox_profile}}}function resolveCoreCommandFlags(command){return CORE_COMMAND_FLAG_CONTRACTS_BY_COMMAND.get(command)??GLOBAL_FLAG_CONTRACTS}function isCoreCommandPath(command){if(PACKAGE_OWNED_COMMANDS.has(command)){return false}return CORE_COMMAND_FLAG_CONTRACTS_BY_COMMAND.has(command)}function normalizeCommandForRuntimeFieldFlags(command){if(LIST_COMMAND_NAMES.has(command)){return"list"}if(command==="cal"){return"calendar"}if(command==="ctx"){return"context"}if(command==="update-many"){return"update_many"}return command}function toRuntimeLongFlagToken(token){const trimmed=token.trim();if(!trimmed){return null}if(trimmed.startsWith("--")){return trimmed}if(trimmed.startsWith("-")){return null}return`--${trimmed}`}function toRuntimeShortFlagToken(token){const trimmed=token.trim();if(!trimmed){return null}if(trimmed.startsWith("--")){return null}if(trimmed.startsWith("-")){return trimmed}return null}function buildRuntimeFieldFlagContracts(fieldRegistry){const buckets=new Map;for(const definition of fieldRegistry.definitions){const primaryFlag=toRuntimeLongFlagToken(definition.cli_flag);if(!primaryFlag){continue}const shortAlias=definition.cli_aliases.map(alias=>toRuntimeShortFlagToken(alias)).find(alias=>alias!==null);const longAliases=definition.cli_aliases.map(alias=>toRuntimeLongFlagToken(alias)).filter(alias=>alias!==null&&alias!==primaryFlag);for(const command of definition.commands){const bucket=buckets.get(command)??{flags:[],seen:new Set};const primaryContract=shortAlias?{flag:primaryFlag,short:shortAlias}:{flag:primaryFlag};const primaryKey=`${primaryContract.flag}|${primaryContract.short??""}`;if(!bucket.seen.has(primaryKey)){bucket.seen.add(primaryKey);bucket.flags.push(primaryContract)}for(const alias of longAliases){const key=`${alias}|`;if(bucket.seen.has(key)){continue}bucket.seen.add(key);bucket.flags.push({flag:alias})}buckets.set(command,bucket)}}const result=new Map;for(const[command,bucket]of buckets.entries()){result.set(command,compactFlagAliasContracts(bucket.flags))}return result}function mergeFlagContracts(primary,secondary){const merged=[];const seen=new Set;for(const contract of[...primary,...secondary]){const key=`${contract.flag}|${contract.short??""}`;if(seen.has(key)){continue}seen.add(key);merged.push(contract)}return compactFlagAliasContracts(merged)}function buildCommandFlagSurface(commands,extensionFlagMap,runtimeFieldFlagMap,includeSemanticMetadata){return commands.map(command=>{const isCoreCommand=isCoreCommandPath(command);const coreFlags=isCoreCommand?resolveCoreCommandFlags(command):[];const runtimeFlags=runtimeFieldFlagMap.get(normalizeCommandForRuntimeFieldFlags(command))??[];const extensionFlags=extensionFlagMap.get(command);const coreWithRuntime=mergeFlagContracts(coreFlags,runtimeFlags);const flags=mergeFlagContracts(coreWithRuntime,extensionFlags?.flags??[]);const provider=coreFlags.length>0&&(extensionFlags?.flags.length??0)>0?"mixed":isCoreCommand?"core":"extension";return{command,flags,...includeSemanticMetadata?{canonical_command:canonicalSummaryCommand(command),visibility:resolvePmCommandVisibilityTier(canonicalSummaryCommand(command)),positionals:resolvePmCommandPositionalContract(command)?.slots??[],flag_invocations:enrichCliFlagInvocationContracts(command,flags)}:{},provider,extension_sources:extensionFlags?.sources}}).sort((left,right)=>left.command.localeCompare(right.command))}function buildCommandAliasSurface(commands,aliasContracts=PM_COMMAND_ALIAS_CONTRACTS){const commandSet=new Set(commands);const grouped=new Map;for(const entry of CANONICAL_COMMAND_ALIASES){const aliases=entry.aliases.filter(alias=>commandSet.has(alias));grouped.set(entry.canonical,{canonical:entry.canonical,aliases,contracts:[]})}for(const contract of aliasContracts){if(!commandSet.has(contract.canonical)){continue}if(contract.registration==="commander"&&!commandSet.has(contract.alias)){continue}const entry=grouped.get(contract.canonical)??{canonical:contract.canonical,aliases:[],contracts:[]};if(!entry.aliases.includes(contract.alias)){entry.aliases.push(contract.alias)}entry.contracts.push(contract);grouped.set(contract.canonical,entry)}return[...grouped.values()].map(({contracts,...entry})=>contracts.length===0?entry:{...entry,contracts}).sort((left,right)=>left.canonical.localeCompare(right.canonical))}function buildCommanderAliasSurface(){return{create_string_options:CREATE_COMMANDER_STRING_OPTION_CONTRACTS,create_repeatable_options:CREATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS,update_string_options:UPDATE_COMMANDER_STRING_OPTION_CONTRACTS,update_repeatable_options:UPDATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS,list_string_options:LIST_COMMANDER_STRING_OPTION_CONTRACTS,search_string_options:SEARCH_COMMANDER_STRING_OPTION_CONTRACTS,calendar_string_options:CALENDAR_COMMANDER_STRING_OPTION_CONTRACTS,context_string_options:CONTEXT_COMMANDER_STRING_OPTION_CONTRACTS,activity_string_options:ACTIVITY_COMMANDER_STRING_OPTION_CONTRACTS}}function resolveCreateRequiredOptionContract(typeDefinition,createMode){const baseRequiredOptions=new Set(["title","type"]);if(createMode==="strict"){for(const field of typeDefinition.required_create_fields){baseRequiredOptions.add(field)}for(const field of typeDefinition.required_create_repeatables){baseRequiredOptions.add(field)}}const policyState=resolveCommandOptionPolicyState(typeDefinition,"create",baseRequiredOptions);const requiredOptionKeys=[...new Set(policyState.required)].sort((left,right)=>left.localeCompare(right));const requiredFlags=[...new Set(requiredOptionKeys.map(option=>commandOptionFlagLabel("create",option)))].sort((left,right)=>left.localeCompare(right));const requiredTypeOptions=[...new Set(typeDefinition.options.filter(option=>option.required===true).map(option=>option.key))].sort((left,right)=>left.localeCompare(right));return{required_option_keys:requiredOptionKeys,required_flags:requiredFlags,required_type_options:requiredTypeOptions,policy_errors:[...new Set(policyState.errors)].sort((left,right)=>left.localeCompare(right))}}function buildCreateRequiredOptionContracts(typeRegistry){const byTypeStrict={};const byTypeProgressive={};for(const typeName of[...typeRegistry.types].sort((left,right)=>left.localeCompare(right))){const typeDefinition=typeRegistry.by_type[typeName];byTypeStrict[typeName]=resolveCreateRequiredOptionContract(typeDefinition,"strict");byTypeProgressive[typeName]=resolveCreateRequiredOptionContract(typeDefinition,"progressive")}return{default_create_mode:"strict",by_create_mode:{strict:{by_type:byTypeStrict},progressive:{by_type:byTypeProgressive}}}}function attachCreateRequiredOptionContracts(schema,metadata){const branches=extractActionBranches(schema);if(branches.length===0){return schema}let touched=false;const enrichedBranches=branches.map(branch=>{const properties=branch.properties;if(typeof properties!=="object"||properties===null){return branch}const actionProperty=properties.action;if(typeof actionProperty!=="object"||actionProperty===null){return branch}if(actionProperty.const!=="create"){return branch}touched=true;return{...branch,"x-create-required-options":metadata}});if(!touched){return schema}return{...schema,oneOf:enrichedBranches}}function resolveContractsSelection(options){const explicitlyScoped=normalizeToken(options.action)!==void 0||normalizeToken(options.command)!==void 0;const projectionSelected=options.schemaOnly===true||options.flagsOnly===true||options.availabilityOnly===true;const summary=options.summary===true||options.full!==true&&options.runtimeOnly!==true&&!explicitlyScoped&&!projectionSelected;const schemaOnly=options.schemaOnly===true;const flagsOnly=options.flagsOnly===true;const availabilityOnly=options.availabilityOnly===true;const runtimeOnly=options.runtimeOnly===true;const fullOutput=options.full===true;const selectedAction=normalizeToken(options.action);const selectedCommand=normalizeToken(options.command);const unfilteredDefaultBriefMode=!summary&&!fullOutput&&!schemaOnly&&!flagsOnly&&!availabilityOnly&&!selectedAction&&!selectedCommand;return{selectedAction,selectedCommand,summary,schemaOnly,flagsOnly,availabilityOnly,runtimeOnly,fullOutput,omitUnfilteredSchema:unfilteredDefaultBriefMode,omitUnfilteredCommandFlags:unfilteredDefaultBriefMode,omitUnfilteredCommanderAliases:unfilteredDefaultBriefMode||selectedCommand!==void 0&&!fullOutput}}function assertSingleContractsProjection(selection){const projectionFlagsEnabled=[selection.summary,selection.schemaOnly,selection.flagsOnly,selection.availabilityOnly].filter(value=>value).length;if(projectionFlagsEnabled>1){throw new PmCliError("Choose only one projection flag: --summary, --schema-only, --flags-only, or --availability-only.",EXIT_CODE.USAGE)}}async function readContractsSettings(pmRoot,readSettingsFn=readSettings){try{return await readSettingsFn(pmRoot)}catch{return structuredClone(SETTINGS_DEFAULTS)}}async function resolveContractsRuntimeContext(global2,pmRoot){const settings=await readContractsSettings(pmRoot);const runtimeProbe=await resolveRuntimeExtensionActionProbe(global2);const typeRegistry=resolveItemTypeRegistry(settings,runtimeProbe.registrations??getActiveExtensionRegistrations());const runtimeFieldRegistry=resolveRuntimeFieldRegistry(settings.schema);const extensionContracts=collectExtensionCommandContracts(runtimeProbe);return{settings,runtimeProbe,typeRegistry,statusRegistry:resolveRuntimeStatusRegistry(settings.schema),runtimeFieldRegistry,runtimeFieldFlagMap:buildRuntimeFieldFlagContracts(runtimeFieldRegistry),createRequiredOptionContracts:buildCreateRequiredOptionContracts(typeRegistry),extensionContracts,mergedExtensionContracts:mergeExtensionContractsByAction(extensionContracts),extensionFlagMap:collectExtensionFlagContractsByCommand(runtimeProbe.flagRegistrations)}}function shouldIncludePackageOwnedActions(selection){return selection.availabilityOnly&&(selection.selectedAction!==void 0&&PACKAGE_OWNED_ACTIONS.has(selection.selectedAction)||selection.selectedCommand!==void 0&&PACKAGE_OWNED_COMMANDS.has(selection.selectedCommand))}function collectContractsActionDescriptors(selection,mergedExtensionContracts){const actionDescriptors=collectActionContractDescriptors(mergedExtensionContracts,{includePackageOwnedActions:shouldIncludePackageOwnedActions(selection)});if(selection.selectedAction===void 0&&selection.selectedCommand===void 0){const deprecatedActions=new Set(PM_DEPRECATED_TOOL_ACTIONS);return actionDescriptors.filter(descriptor=>!deprecatedActions.has(descriptor.action))}if(shouldIncludePackageOwnedActions(selection)&&selection.selectedCommand!==void 0&&PACKAGE_OWNED_COMMANDS.has(selection.selectedCommand)&&!actionDescriptors.some(entry=>entry.command_path===selection.selectedCommand)){actionDescriptors.push({action:packageOwnedActionForCommand(selection.selectedCommand),provider:"extension",requires_extension:true,command_path:selection.selectedCommand})}return actionDescriptors}function assertKnownContractsAction(selection,actionDescriptors){const actionNames=new Set(actionDescriptors.map(entry=>entry.action));if(selection.selectedAction&&!actionNames.has(selection.selectedAction)){throw new PmCliError(`Unknown action: "${selection.selectedAction}".`,EXIT_CODE.USAGE)}}function buildContractsCommandCatalog(actionDescriptors,mergedExtensionContracts){return[...new Set([...PM_CORE_COMMAND_NAMES.filter(entry=>!PACKAGE_OWNED_COMMANDS.has(entry)),...[...CORE_COMMAND_FLAG_CONTRACTS_BY_COMMAND.keys()].filter(entry=>!PACKAGE_OWNED_COMMANDS.has(entry)),...actionDescriptors.flatMap(entry=>entry.command_path?splitCommandPathAliases(entry.command_path):[]),...mergedExtensionContracts.flatMap(entry=>entry.command.split("|"))])].map(entry=>normalizeCommandPath(entry)).filter(entry=>entry.length>0).sort((left,right)=>left.localeCompare(right))}function buildCommandNamespaceError(command,namespaceChildren){const displayedNamespaceChildren=namespaceChildren.slice(0,COMMAND_NAMESPACE_DISPLAY_LIMIT);const hiddenNamespaceChildCount=namespaceChildren.length-displayedNamespaceChildren.length;const displayedChildCommandList=hiddenNamespaceChildCount>0?`${displayedNamespaceChildren.join(", ")}, and ${hiddenNamespaceChildCount} more`:displayedNamespaceChildren.join(", ");const fallbackCandidates=namespaceChildren.slice(0,COMMAND_NAMESPACE_FALLBACK_LIMIT);const childCommandExamples=namespaceChildren.slice(0,5).map(childCommand=>`pm contracts --command "${childCommand}" --flags-only --json`);const suggestedChildCommand=namespaceChildren[0];return new PmCliError(`Command "${command}" is a command namespace. Choose a concrete child command: ${displayedChildCommandList}.`,EXIT_CODE.USAGE,{code:"command_namespace",required:"Use a concrete child command path listed under this namespace.",why:"Command groups expose help at the namespace root, but command flag contracts belong to executable child commands.",examples:childCommandExamples,nextSteps:[`Retry with a child command, for example: ${childCommandExamples[0]}`],recovery:{suggested_retry:`pm contracts --command "${suggestedChildCommand}" --flags-only --json`,fallback_candidates:fallbackCandidates.map(childCommand=>({source:"command_namespace",command:`pm contracts --command "${childCommand}" --flags-only --json`,reason:`Child command under ${command}`}))}})}function buildPackageOwnedCommandError(command,packageHint){return new PmCliError(`Unknown command: "${command}". Command "${command}" is provided by the optional "${packageHint}" package. Run "pm install ${packageHint} --project" and retry.`,EXIT_CODE.USAGE,{code:"unknown_command",required:`Install the optional "${packageHint}" package, or choose a command from pm contracts --flags-only --json.`,why:"Command contracts include core commands plus commands registered by active packages and extensions.",examples:[`pm install ${packageHint} --project`,`pm contracts --command ${command} --flags-only --json`],nextSteps:[`Install the optional package first: pm install ${packageHint} --project`],recovery:{suggested_retry:`pm install ${packageHint} --project`}})}function buildUnknownCommandError(command){return new PmCliError(`Unknown command: "${command}".`,EXIT_CODE.USAGE,{code:"unknown_command",required:"Use a command path listed by pm contracts --flags-only --json.",why:"Command contracts are generated from the active core, package, and extension command registry.",examples:["pm contracts --flags-only --json","pm --help"],nextSteps:["Verify spelling and active packages/extensions, then rerun with a known command path."],recovery:{suggested_retry:"pm contracts --flags-only --json"}})}function assertKnownContractsCommand(selection,commandCatalog){if(!selection.selectedCommand){return}const commandNames=new Set(commandCatalog);if(commandNames.has(selection.selectedCommand)){return}const namespaceChildren=commandCatalog.filter(command=>command.startsWith(`${selection.selectedCommand} `));if(namespaceChildren.length>0){throw buildCommandNamespaceError(selection.selectedCommand,namespaceChildren)}const packageHint=PACKAGE_OWNED_COMMAND_INSTALL_HINTS.get(selection.selectedCommand);if(packageHint){throw buildPackageOwnedCommandError(selection.selectedCommand,packageHint)}throw buildUnknownCommandError(selection.selectedCommand)}function resolveContractsActionContext(selection,runtime){const actionDescriptors=collectContractsActionDescriptors(selection,runtime.mergedExtensionContracts);assertKnownContractsAction(selection,actionDescriptors);const commandCatalog=buildContractsCommandCatalog(actionDescriptors,runtime.mergedExtensionContracts);assertKnownContractsCommand(selection,commandCatalog);const selectedPackageOwnedAction=selection.selectedCommand?PACKAGE_OWNED_COMMAND_ACTIONS.get(selection.selectedCommand):void 0;const commandScopedDescriptors=selection.selectedCommand?actionDescriptors.filter(descriptor=>selectedPackageOwnedAction?descriptor.action===selectedPackageOwnedAction:actionDescriptorMatchesSelectedCommand(descriptor,selection.selectedCommand)):actionDescriptors;if(selection.selectedCommand&&selection.selectedAction&&!commandScopedDescriptors.some(descriptor=>descriptor.action===selection.selectedAction)){throw new PmCliError(`Action "${selection.selectedAction}" is not mapped to command "${selection.selectedCommand}" in contracts output.`,EXIT_CODE.USAGE)}const scopedActionDescriptors=selection.selectedAction?commandScopedDescriptors.filter(descriptor=>descriptor.action===selection.selectedAction):commandScopedDescriptors;const allActionAvailability=[...new Map(scopedActionDescriptors.map(descriptor=>resolveActionAvailability(descriptor,runtime.runtimeProbe)).map(entry=>[selectedPackageOwnedAction?entry.action:`${entry.action}|${entry.command_path??""}`,entry])).values()];const actionAvailability=selection.runtimeOnly&&!selection.selectedAction&&!selection.availabilityOnly?allActionAvailability.filter(entry=>entry.invocable):allActionAvailability;return{actionDescriptors,commandCatalog,commandScopedDescriptors,scopedActionDescriptors,selectedPackageOwnedAction,actionAvailability,actions:[...new Set(actionAvailability.map(entry=>entry.action))]}}function buildSchemaActionSet(schema){return new Set(extractActionBranches(schema).map(entry=>{const properties=entry.properties;if(typeof properties!=="object"||properties===null){return null}const actionProperty=properties.action;if(typeof actionProperty!=="object"||actionProperty===null){return null}const actionConst=actionProperty.const;return typeof actionConst==="string"?actionConst:null}).filter(entry=>entry!==null))}function buildMergedContractsSchema(mergedExtensionContracts){const schema=PM_TOOL_PARAMETERS_SCHEMA;const schemaBranches=extractActionBranches(schema);const schemaActionSet=buildSchemaActionSet(schema);const extensionBranches=mergedExtensionContracts.filter(contract=>!schemaActionSet.has(contract.action)).map(contract=>buildExtensionActionSchemaBranch(contract));return extensionBranches.length>0?{...schema,oneOf:[...schemaBranches,...extensionBranches]}:schema}function filterContractsSchema(selection,actionContext,mergedSchema){const descriptorActionSet=new Set(actionContext.actionDescriptors.map(descriptor=>descriptor.action));const filteredSchema=selection.selectedAction?filterSchemaByAction(mergedSchema,selection.selectedAction):selection.selectedCommand?filterSchemaByActions(mergedSchema,new Set(actionContext.scopedActionDescriptors.map(descriptor=>descriptor.action))):filterSchemaByActions(mergedSchema,descriptorActionSet);return selection.runtimeOnly&&!selection.selectedAction?filterSchemaByActions(filteredSchema,new Set(actionContext.actions)):filteredSchema}function resolveContractsSchemaContext(selection,runtime,actionContext){const mergedSchema=buildMergedContractsSchema(runtime.mergedExtensionContracts);const includeSchemaSurface=!selection.flagsOnly&&!selection.availabilityOnly;const filteredSchema=includeSchemaSurface?attachCreateRequiredOptionContracts(filterContractsSchema(selection,actionContext,mergedSchema),runtime.createRequiredOptionContracts):filterContractsSchema(selection,actionContext,mergedSchema);return{mergedSchema,filteredSchema}}function resolveContractsCommands(selection,actionContext){if(selection.selectedCommand!==void 0){return[selection.selectedCommand]}if(selection.selectedAction){return resolveScopedCommandsFromActionDescriptors(actionContext.scopedActionDescriptors,actionContext.commandCatalog)}return actionContext.commandCatalog}function resolveOutputCommands(selection,commands){if(selection.selectedCommand!==void 0||selection.selectedAction!==void 0){return commands}const hiddenAliases=new Set(PM_COMMAND_ALIAS_CONTRACTS.filter(contract=>contract.hidden&&(contract.lifecycle==="deprecated"||!selection.fullOutput&&!selection.availabilityOnly)).map(contract=>contract.alias));return commands.filter(command=>!hiddenAliases.has(command))}function canonicalSummaryCommand(command){const historyAlias=PM_HISTORY_COMMAND_ALIASES.find(contract=>contract.alias===command||contract.canonical===command);if(historyAlias)return historyAlias.canonical;const rootCommand=command.split(" ")[0];if(rootCommand.startsWith("list-"))return"list";return COMMAND_ALIAS_TO_CANONICAL.get(rootCommand)??rootCommand}const COMMAND_OPERATION_INTENTS=new Map([["activate","Activate"],["adopt","Adopt"],["adopt-all","Adopt all"],["catalog","Catalog"],["complete","Complete"],["create","Create"],["deactivate","Deactivate"],["delete","Delete"],["describe","Describe"],["doctor","Diagnose"],["explore","Explore"],["init","Initialize"],["inspect","Inspect"],["install","Install"],["list","List"],["manage","Manage"],["migrate","Migrate"],["mutate","Mutate"],["reload","Reload"],["restore","Restore"],["run","Run"],["snapshot","Manage snapshots for"],["uninstall","Uninstall"],["upgrade","Upgrade"]]);const COMMAND_INTENT_SUBJECT_OVERRIDES=new Map([["extension adopt-all","extensions"],["package adopt-all","packages"],["workspace snapshot list","workspace snapshots"]]);function summarizeCommandIntent(command,extensionContracts){const declared=COMMAND_INTENTS.get(resolvePmHistoryOperation(command))??(command.includes(" ")?void 0:COMMAND_INTENTS.get(canonicalSummaryCommand(command)));if(declared!==void 0){return{intent:declared,intent_source:"command"}}const extensionContract=extensionContracts.find(contract=>splitCommandPathAliases(contract.command).includes(command));if(extensionContract?.intent!==null&&extensionContract?.intent!==void 0){return{intent:extensionContract.intent,intent_source:"command"}}if(extensionContract?.description!==null&&extensionContract?.description!==void 0){return{intent:extensionContract.description,intent_source:"description"}}const tokens=command.split(" ");const operation=tokens.at(-1);const subject=tokens.slice(0,-1).join(" ");const verb=COMMAND_OPERATION_INTENTS.get(operation);const intentSubject=COMMAND_INTENT_SUBJECT_OVERRIDES.get(command)??subject;return{intent:verb===void 0||subject.length===0?`Run ${command}.`:`${verb} ${intentSubject}.`,intent_source:"generated"}}function buildCommandSummarySurface(commands,extensionContracts=[],options={}){const includeFormatBudgets=options.includeFormatBudgets??true;const includeIntentProvenance=options.includeIntentProvenance??true;return[...new Set(commands.map(normalizeCommandPath))].filter(command=>command.length>0).sort((left,right)=>left.localeCompare(right)).map(command=>{const budget=resolvePmCommandOutputBudget(command,{generateFallback:true});const rootCommand=command.split(" ")[0];const canonicalRoot=COMMAND_ALIAS_TO_CANONICAL.get(rootCommand)??(rootCommand.startsWith("list-")?"list":rootCommand.startsWith("history-")?"history":rootCommand);const availableFlags=new Set([...resolveCoreCommandFlags(command).map(contract=>contract.flag),...extensionContracts.filter(contract=>splitCommandPathAliases(contract.command).includes(command)).flatMap(contract=>contract.flags.map(flag=>flag.flag))]);const flags=(AGENT_BOOTSTRAP_FLAGS.get(resolvePmHistoryOperation(command))??AGENT_BOOTSTRAP_FLAGS.get(canonicalRoot)??AGENT_BOUNDED_FLAG_PRIORITY).filter(flag=>availableFlags.has(flag));const intent=summarizeCommandIntent(command,extensionContracts);return{command,intent:intent.intent,...includeIntentProvenance||intent.intent_source!=="command"?{intent_source:intent.intent_source}:{},...flags.length>0?{flags}:{},default_max_estimated_tokens:budget.default_max_estimated_tokens,...includeFormatBudgets?{default_max_estimated_tokens_by_format:{...budget.default_max_estimated_tokens_by_format}}:{}}})}function buildCommandOutputContracts(commands){return commands.map(command=>({budget:resolvePmCommandOutputBudget(command,{generateFallback:true}),envelope:resolvePmCommandOutputEnvelope(command)}))}function buildCommandExitContractGroups(commands){const groups=new Map;for(const command of commands){const contract=resolvePmCommandExitContract(command);const exitCodes=contract===void 0?[EXIT_CODE.SUCCESS,EXIT_CODE.GENERIC_FAILURE,EXIT_CODE.USAGE,EXIT_CODE.NOT_FOUND,EXIT_CODE.CONFLICT,EXIT_CODE.DEPENDENCY_FAILED]:contract.exit_codes;const key=exitCodes.join(",");const group=groups.get(key)??{commands:[],exit_codes:exitCodes};group.commands.push(command);groups.set(key,group)}return[...groups.values()]}function resolveExtensionCommandContracts(selection,runtime,outputCommands){if(selection.selectedCommand){return runtime.extensionContracts.filter(entry=>splitCommandPathAliases(entry.command).includes(selection.selectedCommand))}if(selection.selectedAction){const outputCommandSet=new Set(outputCommands);return runtime.extensionContracts.filter(entry=>splitCommandPathAliases(entry.command).some(command=>outputCommandSet.has(command)))}return runtime.extensionContracts}function createContractsResult(selection,schemaContext,actionContext,outputCommands){return{schema_version:typeof schemaContext.mergedSchema["x-schema-version"]==="string"?schemaContext.mergedSchema["x-schema-version"]:null,schema_id:typeof schemaContext.mergedSchema.$id==="string"?schemaContext.mergedSchema.$id:null,selected:{action:selection.selectedAction??null,command:selection.selectedCommand??null,summary:selection.summary,schema_only:selection.schemaOnly,flags_only:selection.flagsOnly,availability_only:selection.availabilityOnly,runtime_only:selection.runtimeOnly,command_scoped:selection.selectedCommand!==void 0},commands:selection.summary?[]:outputCommands,...!selection.summary&&!selection.flagsOnly?{actions:actionContext.actions,action_availability:actionContext.actionAvailability}:{}}}function attachRuntimeContractsResult(result,runtime,selection){const selectedCommand=selection.selectedCommand;result.runtime_schema={statuses:runtime.statusRegistry.definitions.map(definition=>definition.id),open_status:runtime.statusRegistry.open_status,close_status:runtime.statusRegistry.close_status,canceled_status:runtime.statusRegistry.canceled_status,types:[...runtime.typeRegistry.types],fields_by_command:Object.fromEntries([...runtime.runtimeFieldRegistry.command_to_fields.entries()].filter(([command])=>selectedCommand===void 0||command===selectedCommand).map(([command,definitions])=>[command,[...new Set(definitions.map(definition=>`--${definition.cli_flag}`))].sort((left,right)=>left.localeCompare(right))]))};if(selectedCommand!==void 0&&!selection.fullOutput){return}result.extension_contracts={capabilities:[...PM_EXTENSION_CAPABILITY_CONTRACTS],services:[...PM_EXTENSION_SERVICE_NAME_CONTRACTS],policy_modes:[...PM_EXTENSION_POLICY_MODE_CONTRACTS],policy_mode_scope:"extensions.policy.mode",policy_surfaces:[...PM_EXTENSION_POLICY_SURFACE_CONTRACTS],trust_modes:[...PM_EXTENSION_TRUST_MODE_CONTRACTS],trust_mode_scope:"extensions.policy.trust_mode",sandbox_profiles:[...PM_EXTENSION_SANDBOX_PROFILE_CONTRACTS],manifest_versions:[1,2],compatibility:{current:"v2",previous:["v1"],breaking_strategy:"versioned_breaking"}};result.governance_contracts={ownership_enforcement_modes:[...GOVERNANCE_OWNERSHIP_ENFORCEMENT_VALUES],create_modes:[...GOVERNANCE_CREATE_MODE_DEFAULT_VALUES],close_validation_modes:[...GOVERNANCE_CLOSE_VALIDATION_DEFAULT_VALUES],workflow_enforcement_modes:[...GOVERNANCE_WORKFLOW_ENFORCEMENT_VALUES]};result.relationship_kind_contracts=[...BUILTIN_RELATIONSHIP_KINDS,...(runtime.runtimeProbe.registrations?.relationship_kinds??[]).flatMap(registration=>registration.definitions)].sort((left,right)=>left.kind.localeCompare(right.kind)).map(definition=>({canonical:definition.kind,aliases:[...definition.aliases??[]],...definition.inverse===void 0?{}:{inverse:definition.inverse},ordering:definition.ordering,hierarchy:definition.hierarchy}))}function attachSchemaContractsResult(result,selection,schemaContext,extensionCommandContracts){if(selection.flagsOnly||selection.availabilityOnly){return}if(!selection.omitUnfilteredSchema){result.schema=schemaContext.filteredSchema;result.extension_commands=extensionCommandContracts;return}result.schema_omitted_reason="unfiltered_default_brief";result.extension_commands=extensionCommandContracts}function attachFlagContractsResult(result,selection,runtime,outputCommands,commandAliases){if(selection.schemaOnly||selection.availabilityOnly){return}if(!selection.omitUnfilteredCommandFlags){result.command_flags=buildCommandFlagSurface(outputCommands,runtime.extensionFlagMap,runtime.runtimeFieldFlagMap,selection.selectedCommand!==void 0);const commandSet=new Set(outputCommands);result.list_projections=Object.entries(LIST_COMMAND_DEFAULT_PROJECTIONS).filter(([command])=>commandSet.has(command)).map(([command,defaultProjection])=>({command,default:defaultProjection,brief_fields:[...BRIEF_LIST_FIELDS],compact_fields:[...DEFAULT_COMPACT_LIST_FIELDS]}))}else{result.command_flags_omitted_reason="unfiltered_default_brief"}result.command_aliases=selection.fullOutput?commandAliases:commandAliases.map(({canonical,aliases})=>({canonical,aliases}));if(!selection.fullOutput){result.command_alias_contracts_omitted_reason="compact_projection; restore with --full"}}function attachCommanderAliasContractsResult(result,selection){if(selection.schemaOnly||selection.flagsOnly||selection.availabilityOnly){return}if(!selection.omitUnfilteredCommanderAliases){result.commander_aliases=buildCommanderAliasSurface();return}result.commander_aliases_omitted_reason=selection.selectedCommand?"command_scoped":"unfiltered_default_brief"}function attachAgentCommandContractsResult(result,outputCommands,extensionCommandContracts,options){result.command_summaries=buildCommandSummarySurface(outputCommands,extensionCommandContracts,{includeFormatBudgets:options.includeFormatBudgets,includeIntentProvenance:options.includeIntentProvenance});result.output_policy={token_estimate:"ceil(utf8_bytes / 4)",degradation_ladder:[...PM_OUTPUT_DEGRADATION_STEPS],allows_unbounded_opt_out:true};result.output_projection_contracts={global_ladder_field:"output_policy.degradation_ladder",global_ladder_scope:"union_not_per_command",discovery:"pm contracts --command <command> --summary",...options.includeProjectionModeMatrix?{commands:[...new Set(outputCommands.map(normalizeCommandPath))].filter(command=>resolveReadOutputSurface(command)!==void 0).sort((left,right)=>left.localeCompare(right)).map(command=>({command,modes:[...readOutputIncludeModeOptions(command).keys()]}))}:{}};result.grammar_contracts={nouns:PM_CLI_GRAMMAR_CONTRACT.nouns,shared_verbs:PM_CLI_GRAMMAR_CONTRACT.shared_verbs,scope_before_verb:PM_CLI_GRAMMAR_CONTRACT.scope_before_verb,visible_top_level_ceiling:PM_CLI_GRAMMAR_CONTRACT.visible_top_level_ceiling,ceiling_raise_requires_pm_item:PM_CLI_GRAMMAR_CONTRACT.ceiling_raise_requires_pm_item,positional_shape_budget:PM_CLI_GRAMMAR_CONTRACT.positional_shape_budget,positional_shape_count:new Set(PM_COMMAND_POSITIONAL_CONTRACTS.map(({slots})=>positionalShapeKey(slots))).size,positional_action_count:PM_POSITIONAL_ACTION_CONTRACTS.length,positional_action_parents:[...new Set(PM_POSITIONAL_ACTION_CONTRACTS.map(({parent})=>parent))].sort((left,right)=>left.localeCompare(right)),...options.includePositionalSignatures?{positional_signatures:PM_COMMAND_POSITIONAL_CONTRACTS}:{}}}async function runContracts(options,global2){const selection=resolveContractsSelection(options);assertSingleContractsProjection(selection);const pmRoot=resolvePmRoot(process.cwd(),global2.path);const runtime=await resolveContractsRuntimeContext(global2,pmRoot);const actionContext=resolveContractsActionContext(selection,runtime);const schemaContext=resolveContractsSchemaContext(selection,runtime,actionContext);const commands=resolveContractsCommands(selection,actionContext);const outputCommands=resolveOutputCommands(selection,commands);const result=createContractsResult(selection,schemaContext,actionContext,outputCommands);const extensionCommandContracts=resolveExtensionCommandContracts(selection,runtime,outputCommands);const includeCommandDetails=selection.fullOutput||selection.selectedCommand!==void 0;if(selection.summary||selection.fullOutput){attachAgentCommandContractsResult(result,outputCommands,extensionCommandContracts,{includeFormatBudgets:includeCommandDetails,includeIntentProvenance:includeCommandDetails,includePositionalSignatures:includeCommandDetails,includeProjectionModeMatrix:includeCommandDetails})}if(selection.summary){return result}const commandAliases=buildCommandAliasSurface(actionContext.commandCatalog);if(!(selection.flagsOnly&&!selection.fullOutput)){attachRuntimeContractsResult(result,runtime,selection)}attachSchemaContractsResult(result,selection,schemaContext,extensionCommandContracts);attachFlagContractsResult(result,selection,runtime,outputCommands,commandAliases);attachCommanderAliasContractsResult(result,selection);if(selection.selectedCommand==="assurance"||selection.fullOutput){result.assurance_contracts={measurement_source_kinds:[...ASSURANCE_MEASUREMENT_SOURCE_KINDS],gate_triggers:[...ASSURANCE_GATE_TRIGGERS]}}if(selection.fullOutput&&result.grammar_contracts){result.grammar_contracts.destinations=PM_COMMAND_DESTINATION_CONTRACTS}if(selection.fullOutput&&!selection.schemaOnly&&!selection.flagsOnly&&!selection.availabilityOnly){result.mcp_tools=buildMcpToolContracts();result.context_intents=getActiveContextIntentContracts();result.read_output_dimensions=PM_READ_OUTPUT_SURFACE_CONTRACTS;result.error_codes=PM_ERROR_CODE_CATALOG;result.command_output_contracts=buildCommandOutputContracts(outputCommands);result.diagnostic_output_contracts=PM_DIAGNOSTIC_OUTPUT_BUDGET_CONTRACTS;result.command_exit_contracts={vocabulary:PM_COMMAND_EXIT_OUTCOME_CONTRACTS,command_sets:buildCommandExitContractGroups(outputCommands)}}return result}const _testOnlyContractsCommand={actionDescriptorMatchesSelectedCommand,attachCreateRequiredOptionContracts,buildExtensionActionSchemaBranch,buildCommandSummarySurface,buildCommandOutputContracts,buildCommandExitContractGroups,buildRuntimeFieldFlagContracts,collectActionContractDescriptors,collectExtensionCommandContracts,collectExtensionFlagContractsByCommand,extractActionBranches,extensionSchemaPropertyNameFromFlag,filterSchemaByAction,filterSchemaByActions,isCoreCommandPath,mergeExtensionContractsByAction,normalizeExtensionFlagName,normalizeActionNameFromCommand,normalizeCommandForRuntimeFieldFlags,normalizeCommandPath,packageOwnedActionForCommand,readContractsSettings,resolveActionCommandPath,resolveActionAvailability,resolveCoreCommandFlags,resolveRuntimeExtensionActionProbe,resolveScopedCommandsFromActionDescriptors,splitCommandPathAliases,toRuntimeLongFlagToken,toRuntimeShortFlagToken};export{_testOnlyContractsCommand,buildCommandAliasSurface,runContracts};
 //# sourceMappingURL=runtime-contracts.js.map
-//# debugId=188569e7-c809-5f28-a714-d531f57be1d9