@unbrained/pm-cli 2026.5.12 → 2026.5.18

package/dist/cli/commands/contracts.js

@@ -1,12 +1,14 @@
+
+!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]="dc0f1970-8a30-56c5-827f-573784a38d54")}catch(e){}}();
 import { EXIT_CODE, SETTINGS_DEFAULTS } from "../../core/shared/constants.js";
 import { PmCliError } from "../../core/shared/errors.js";
-import { activateExtensions, getActiveExtensionRegistrations, loadExtensions } from "../../core/extensions/index.js";
+import { activateExtensions, getActiveExtensionRegistrations, loadExtensions, } from "../../core/extensions/index.js";
 import { pathExists } from "../../core/fs/fs-utils.js";
-import { commandOptionFlagLabel, resolveCommandOptionPolicyState, resolveItemTypeRegistry } from "../../core/item/type-registry.js";
+import { commandOptionFlagLabel, resolveCommandOptionPolicyState, resolveItemTypeRegistry, } from "../../core/item/type-registry.js";
 import { resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, } from "../../core/schema/runtime-schema.js";
 import { getSettingsPath, resolvePmRoot } from "../../core/store/paths.js";
 import { readSettings } from "../../core/store/settings.js";
-import { ACTIVITY_COMMANDER_STRING_OPTION_CONTRACTS, ACTIVITY_FLAG_CONTRACTS, AGGREGATE_FLAG_CONTRACTS, APPEND_FLAG_CONTRACTS, CALENDAR_COMMANDER_STRING_OPTION_CONTRACTS, CALENDAR_FLAG_CONTRACTS, CLAIM_FLAG_CONTRACTS, CLOSE_TASK_FLAG_CONTRACTS, COMMENTS_FLAG_CONTRACTS, COMMENTS_AUDIT_FLAG_CONTRACTS, CLOSE_FLAG_CONTRACTS, COMPLETION_FLAG_CONTRACTS, CONFIG_FLAG_CONTRACTS, CONTRACTS_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, DEDUPE_AUDIT_FLAG_CONTRACTS, DOCS_FLAG_CONTRACTS, EXTENSION_FLAG_CONTRACTS, FILES_FLAG_CONTRACTS, GC_FLAG_CONTRACTS, GUIDE_FLAG_CONTRACTS, GLOBAL_FLAG_CONTRACTS, HEALTH_FLAG_CONTRACTS, HISTORY_FLAG_CONTRACTS, LEARNINGS_FLAG_CONTRACTS, LIST_COMMANDER_STRING_OPTION_CONTRACTS, LIST_FILTER_FLAG_CONTRACTS, NORMALIZE_FLAG_CONTRACTS, NOTES_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_CORE_COMMAND_NAMES, PM_TOOL_ACTIONS, PM_TOOL_PARAMETERS_SCHEMA, REINDEX_FLAG_CONTRACTS, RELEASE_FLAG_CONTRACTS, RESTORE_FLAG_CONTRACTS, SEARCH_COMMANDER_STRING_OPTION_CONTRACTS, SEARCH_FLAG_CONTRACTS, START_TASK_FLAG_CONTRACTS, PAUSE_TASK_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, withFlagAliasMetadata, } from "../../sdk/cli-contracts.js";
+import { ACTIVITY_COMMANDER_STRING_OPTION_CONTRACTS, ACTIVITY_FLAG_CONTRACTS, AGGREGATE_FLAG_CONTRACTS, APPEND_FLAG_CONTRACTS, CALENDAR_COMMANDER_STRING_OPTION_CONTRACTS, CALENDAR_FLAG_CONTRACTS, CLAIM_FLAG_CONTRACTS, CLOSE_TASK_FLAG_CONTRACTS, COMMENTS_FLAG_CONTRACTS, COMMENTS_AUDIT_FLAG_CONTRACTS, CLOSE_FLAG_CONTRACTS, COMPLETION_FLAG_CONTRACTS, CONFIG_FLAG_CONTRACTS, CONTRACTS_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, DEDUPE_AUDIT_FLAG_CONTRACTS, DOCS_FLAG_CONTRACTS, EXTENSION_FLAG_CONTRACTS, FILES_FLAG_CONTRACTS, GC_FLAG_CONTRACTS, GET_FLAG_CONTRACTS, GUIDE_FLAG_CONTRACTS, GLOBAL_FLAG_CONTRACTS, HEALTH_FLAG_CONTRACTS, HISTORY_FLAG_CONTRACTS, HISTORY_REDACT_FLAG_CONTRACTS, INSTALL_FLAG_CONTRACTS, INIT_FLAG_CONTRACTS, LEARNINGS_FLAG_CONTRACTS, LIST_COMMANDER_STRING_OPTION_CONTRACTS, LIST_FILTER_FLAG_CONTRACTS, NORMALIZE_FLAG_CONTRACTS, NOTES_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, PLAN_FLAG_CONTRACTS, PM_CORE_COMMAND_NAMES, PM_TOOL_ACTIONS, PM_TOOL_PARAMETERS_SCHEMA, REINDEX_FLAG_CONTRACTS, RELEASE_FLAG_CONTRACTS, RESTORE_FLAG_CONTRACTS, SEARCH_COMMANDER_STRING_OPTION_CONTRACTS, SEARCH_FLAG_CONTRACTS, START_TASK_FLAG_CONTRACTS, PAUSE_TASK_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, } from "../../sdk/cli-contracts.js";
 const LIST_COMMAND_NAMES = new Set([
     "list",
     "list-all",
@@ -17,16 +19,56 @@ const LIST_COMMAND_NAMES = new Set([
     "list-closed",
     "list-canceled",
 ]);
-const EXTENSION_ACTION_COMMAND_PATHS = {
-    "beads-import": "beads import",
-    "todos-import": "todos import",
-    "todos-export": "todos export",
-};
+const PACKAGE_OWNED_ACTIONS = new Set([
+    "calendar",
+    "dedupe-audit",
+    "guide",
+    "reindex",
+    "normalize",
+    "comments-audit",
+    "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",
+    "comments-audit",
+    "completion",
+    "completion-tags",
+    "dedupe-audit",
+    "guide",
+    "normalize",
+    "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 CANONICAL_COMMAND_ALIASES = [
+    {
+        canonical: "context",
+        aliases: ["ctx"],
+    },
+    {
+        canonical: "package",
+        aliases: ["extension", "packages", "install"],
+    },
+];
+const COMMAND_ALIAS_TO_CANONICAL = new Map(CANONICAL_COMMAND_ALIASES.flatMap((entry) => entry.aliases.map((alias) => [alias, entry.canonical])));
 function resolveActionCommandPath(action) {
-    const extensionCommandPath = EXTENSION_ACTION_COMMAND_PATHS[action];
-    if (extensionCommandPath) {
-        return normalizeCommandPath(extensionCommandPath);
-    }
     if (PM_CORE_COMMAND_NAMES.includes(action)) {
         return normalizeCommandPath(action);
     }
@@ -168,8 +210,12 @@ function normalizeStringList(values) {
 function toExtensionFlagContract(definition) {
     const longName = toOptionalTrimmedString(definition.long);
     const shortName = toOptionalTrimmedString(definition.short);
-    const normalizedLong = longName && longName.startsWith("--") && longName.length > 2 ? longName : null;
-    const normalizedShort = shortName && shortName.startsWith("-") && !shortName.startsWith("--") ? shortName : null;
+    const normalizedLong = longName && longName.startsWith("--") && longName.length > 2
+        ? longName
+        : null;
+    const normalizedShort = shortName && shortName.startsWith("-") && !shortName.startsWith("--")
+        ? shortName
+        : null;
     const flag = normalizedLong ?? normalizedShort;
     if (!flag) {
         return null;
@@ -224,7 +270,7 @@ function collectExtensionFlagContractsByCommand(registrations) {
                 if (layerOrder !== 0) {
                     return layerOrder;
                 }
-                return left.name.localeCompare(right.name);
+                return (left.name ?? "").localeCompare(right.name ?? "");
             }),
         });
     }
@@ -238,7 +284,8 @@ function collectExtensionCommandContracts(runtimeProbe) {
         if (command.length === 0) {
             continue;
         }
-        const action = toOptionalTrimmedString(definition.action) ?? normalizeActionNameFromCommand(command);
+        const action = toOptionalTrimmedString(definition.action) ??
+            normalizeActionNameFromCommand(command);
         const args = Array.isArray(definition.arguments)
             ? definition.arguments
                 .map((argument) => {
@@ -286,7 +333,9 @@ function collectExtensionCommandContracts(runtimeProbe) {
         if (definition) {
             contracts.push({
                 ...definition,
-                flags: definition.flags.length > 0 ? definition.flags : flagsByCommand.get(command)?.flags ?? [],
+                flags: definition.flags.length > 0
+                    ? definition.flags
+                    : (flagsByCommand.get(command)?.flags ?? []),
             });
             continue;
         }
@@ -318,7 +367,9 @@ function buildExtensionActionSchemaBranch(contract) {
         action: {
             type: "string",
             const: contract.action,
-            description: contract.intent ?? contract.description ?? `Invoke extension command '${contract.command}'.`,
+            description: contract.intent ??
+                contract.description ??
+                `Invoke extension command '${contract.command}'.`,
         },
     };
     const required = ["action"];
@@ -327,13 +378,15 @@ function buildExtensionActionSchemaBranch(contract) {
             properties[argument.name] = {
                 type: "array",
                 items: { type: "string" },
-                description: argument.description ?? `Variadic argument '${argument.name}' for extension action '${contract.action}'.`,
+                description: argument.description ??
+                    `Variadic argument '${argument.name}' for extension action '${contract.action}'.`,
             };
         }
         else {
             properties[argument.name] = {
                 type: "string",
-                description: argument.description ?? `Argument '${argument.name}' for extension action '${contract.action}'.`,
+                description: argument.description ??
+                    `Argument '${argument.name}' for extension action '${contract.action}'.`,
             };
         }
         if (argument.required) {
@@ -423,12 +476,14 @@ async function resolveRuntimeExtensionActionProbe(global) {
 function collectActionContractDescriptors(extensionContracts) {
     const descriptors = new Map();
     for (const action of PM_TOOL_ACTIONS) {
-        const extensionCommandPath = EXTENSION_ACTION_COMMAND_PATHS[action];
+        if (PACKAGE_OWNED_ACTIONS.has(action)) {
+            continue;
+        }
         const commandPath = resolveActionCommandPath(action);
         descriptors.set(action, {
             action,
-            provider: extensionCommandPath ? "extension" : "core",
-            requires_extension: extensionCommandPath !== undefined,
+            provider: "core",
+            requires_extension: false,
             command_path: commandPath,
         });
     }
@@ -443,7 +498,7 @@ function collectActionContractDescriptors(extensionContracts) {
             command_path: normalizeCommandPath(contract.command),
         });
     }
-    return [...descriptors.values()].sort((left, right) => left.action.localeCompare(right.action));
+    return [...descriptors.values()].sort((left, right) => (left.action ?? "").localeCompare(right.action ?? ""));
 }
 function resolveActionAvailability(descriptor, runtimeProbe) {
     if (descriptor.provider === "core" && !descriptor.requires_extension) {
@@ -458,7 +513,9 @@ function resolveActionAvailability(descriptor, runtimeProbe) {
             cli_exposed: descriptor.command_path !== null,
         };
     }
-    const commandPath = descriptor.command_path ? normalizeCommandPath(descriptor.command_path) : "";
+    const commandPath = descriptor.command_path
+        ? normalizeCommandPath(descriptor.command_path)
+        : "";
     const extensionCommandAvailable = commandPath.length > 0 && runtimeProbe.handlers.has(commandPath);
     const invocable = runtimeProbe.disabledReason === null && extensionCommandAvailable;
     return {
@@ -467,7 +524,9 @@ function resolveActionAvailability(descriptor, runtimeProbe) {
         available: invocable,
         requires_extension: true,
         provider: "extension",
-        disabled_reason: invocable ? null : runtimeProbe.disabledReason ?? "extension_command_not_registered",
+        disabled_reason: invocable
+            ? null
+            : (runtimeProbe.disabledReason ?? "extension_command_not_registered"),
         command_path: descriptor.command_path,
         cli_exposed: extensionCommandAvailable,
         policy_state: {
@@ -478,12 +537,20 @@ function resolveActionAvailability(descriptor, runtimeProbe) {
     };
 }
 function resolveCoreCommandFlags(command) {
+    if (command === "init") {
+        return INIT_FLAG_CONTRACTS;
+    }
     if (command === "config") {
         return CONFIG_FLAG_CONTRACTS;
     }
-    if (command === "extension" || command === "package" || command === "packages" || command === "install") {
+    if (command === "extension" ||
+        command === "package" ||
+        command === "packages") {
         return EXTENSION_FLAG_CONTRACTS;
     }
+    if (command === "install") {
+        return INSTALL_FLAG_CONTRACTS;
+    }
     if (command === "create") {
         return CREATE_FLAG_CONTRACTS;
     }
@@ -505,6 +572,9 @@ function resolveCoreCommandFlags(command) {
     if (command === "context" || command === "ctx") {
         return CONTEXT_FLAG_CONTRACTS;
     }
+    if (command === "get") {
+        return GET_FLAG_CONTRACTS;
+    }
     if (command === "search") {
         return SEARCH_FLAG_CONTRACTS;
     }
@@ -526,6 +596,12 @@ function resolveCoreCommandFlags(command) {
     if (command === "history") {
         return HISTORY_FLAG_CONTRACTS;
     }
+    if (command === "history-redact") {
+        return HISTORY_REDACT_FLAG_CONTRACTS;
+    }
+    if (command === "plan") {
+        return PLAN_FLAG_CONTRACTS;
+    }
     if (command === "restore") {
         return RESTORE_FLAG_CONTRACTS;
     }
@@ -651,13 +727,20 @@ function buildRuntimeFieldFlagContracts(fieldRegistry) {
         if (!primaryFlag) {
             continue;
         }
-        const shortAlias = definition.cli_aliases.map((alias) => toRuntimeShortFlagToken(alias)).find((alias) => alias !== null);
+        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 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);
@@ -676,7 +759,7 @@ function buildRuntimeFieldFlagContracts(fieldRegistry) {
     }
     const result = new Map();
     for (const [command, bucket] of buckets.entries()) {
-        result.set(command, withFlagAliasMetadata(bucket.flags));
+        result.set(command, compactFlagAliasContracts(bucket.flags));
     }
     return result;
 }
@@ -691,12 +774,12 @@ function mergeFlagContracts(primary, secondary) {
         seen.add(key);
         merged.push(contract);
     }
-    return withFlagAliasMetadata(merged);
+    return compactFlagAliasContracts(merged);
 }
 function buildCommandFlagSurface(commands, extensionFlagMap, runtimeFieldFlagMap) {
     return commands
         .map((command) => {
-        const isCoreCommand = PM_CORE_COMMAND_NAMES.includes(command);
+        const isCoreCommand = PM_CORE_COMMAND_NAMES.includes(command) && !PACKAGE_OWNED_COMMANDS.has(command);
         const coreFlags = isCoreCommand ? resolveCoreCommandFlags(command) : [];
         const runtimeFlags = runtimeFieldFlagMap.get(normalizeCommandForRuntimeFieldFlags(command)) ?? [];
         const extensionFlags = extensionFlagMap.get(command);
@@ -716,6 +799,25 @@ function buildCommandFlagSurface(commands, extensionFlagMap, runtimeFieldFlagMap
     })
         .sort((left, right) => left.command.localeCompare(right.command));
 }
+function compactCommandAliasSurface(commands) {
+    const commandSet = new Set(commands);
+    const result = [];
+    for (const command of commands) {
+        const canonical = COMMAND_ALIAS_TO_CANONICAL.get(command);
+        if (canonical && commandSet.has(canonical)) {
+            continue;
+        }
+        result.push(command);
+    }
+    return result;
+}
+function buildCommandAliasSurface(commands) {
+    const commandSet = new Set(commands);
+    return CANONICAL_COMMAND_ALIASES.map((entry) => ({
+        canonical: entry.canonical,
+        aliases: entry.aliases.filter((alias) => commandSet.has(alias)),
+    })).filter((entry) => commandSet.has(entry.canonical) && entry.aliases.length > 0);
+}
 function buildCommanderAliasSurface() {
     return {
         create_string_options: CREATE_COMMANDER_STRING_OPTION_CONTRACTS,
@@ -730,7 +832,7 @@ function buildCommanderAliasSurface() {
     };
 }
 function resolveCreateRequiredOptionContract(typeDefinition, createMode) {
-    const baseRequiredOptions = new Set(["title", "description", "type"]);
+    const baseRequiredOptions = new Set(["title", "type"]);
     if (createMode === "strict") {
         for (const field of typeDefinition.required_create_fields) {
             baseRequiredOptions.add(field);
@@ -741,8 +843,14 @@ function resolveCreateRequiredOptionContract(typeDefinition, createMode) {
     }
     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));
+    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,
@@ -809,7 +917,19 @@ export async function runContracts(options, global) {
     const flagsOnly = options.flagsOnly === true;
     const availabilityOnly = options.availabilityOnly === true;
     const runtimeOnly = options.runtimeOnly === true;
-    const projectionFlagsEnabled = [schemaOnly, flagsOnly, availabilityOnly].filter((value) => value).length;
+    const fullOutput = options.full === true;
+    const unfilteredDefaultBriefMode = !fullOutput && !schemaOnly && !flagsOnly && !availabilityOnly && !selectedAction && !selectedCommand;
+    // Agent token-cost guard: when no filter and no projection flag and not --full,
+    // skip the giant schema oneOf union (the 200KB+ chunk). Restore via --full
+    // or by scoping to a specific --command/--action.
+    const omitUnfilteredSchema = unfilteredDefaultBriefMode;
+    const omitUnfilteredCommandFlags = unfilteredDefaultBriefMode;
+    const omitUnfilteredCommanderAliases = unfilteredDefaultBriefMode;
+    const projectionFlagsEnabled = [
+        schemaOnly,
+        flagsOnly,
+        availabilityOnly,
+    ].filter((value) => value).length;
     if (projectionFlagsEnabled > 1) {
         throw new PmCliError("Choose only one projection flag: --schema-only, --flags-only, or --availability-only.", EXIT_CODE.USAGE);
     }
@@ -834,7 +954,12 @@ export async function runContracts(options, global) {
     if (selectedAction && !actionNames.has(selectedAction)) {
         throw new PmCliError(`Unknown action: "${options.action}".`, EXIT_CODE.USAGE);
     }
-    const commandCatalog = [...new Set([...PM_CORE_COMMAND_NAMES, ...extensionContracts.map((entry) => entry.command)])]
+    const commandCatalog = [
+        ...new Set([
+            ...PM_CORE_COMMAND_NAMES.filter((entry) => !PACKAGE_OWNED_COMMANDS.has(entry)),
+            ...extensionContracts.map((entry) => entry.command),
+        ]),
+    ]
         .map((entry) => normalizeCommandPath(entry))
         .filter((entry) => entry.length > 0)
         .sort((left, right) => left.localeCompare(right));
@@ -879,13 +1004,16 @@ export async function runContracts(options, global) {
         ? commandScopedDescriptors.filter((descriptor) => descriptor.action === selectedAction)
         : commandScopedDescriptors;
     const allActionAvailability = scopedActionDescriptors.map((descriptor) => resolveActionAvailability(descriptor, runtimeProbe));
-    const actionAvailability = runtimeOnly && !selectedAction ? allActionAvailability.filter((entry) => entry.invocable) : allActionAvailability;
+    const actionAvailability = runtimeOnly && !selectedAction
+        ? allActionAvailability.filter((entry) => entry.invocable)
+        : allActionAvailability;
     const actions = actionAvailability.map((entry) => entry.action);
+    const descriptorActionSet = new Set(actionDescriptors.map((descriptor) => descriptor.action));
     let filteredSchema = selectedAction
         ? filterSchemaByAction(mergedSchema, selectedAction)
         : selectedCommand
             ? filterSchemaByActions(mergedSchema, new Set(scopedActionDescriptors.map((descriptor) => descriptor.action)))
-            : mergedSchema;
+            : filterSchemaByActions(mergedSchema, descriptorActionSet);
     if (runtimeOnly && !selectedAction) {
         filteredSchema = filterSchemaByActions(filteredSchema, new Set(actions));
     }
@@ -898,14 +1026,22 @@ export async function runContracts(options, global) {
         : selectedAction
             ? resolveScopedCommandsFromActionDescriptors(scopedActionDescriptors, commandCatalog)
             : commandCatalog;
+    const outputCommands = flagsOnly && selectedCommand === undefined && selectedAction === undefined
+        ? compactCommandAliasSurface(commands)
+        : commands;
+    const commandAliases = buildCommandAliasSurface(commands);
     const extensionCommandContracts = selectedCommand
         ? extensionContracts.filter((entry) => entry.command === selectedCommand)
         : selectedAction
-            ? extensionContracts.filter((entry) => commands.includes(normalizeCommandPath(entry.command)))
+            ? extensionContracts.filter((entry) => outputCommands.includes(normalizeCommandPath(entry.command)))
             : extensionContracts;
     const result = {
-        schema_version: typeof mergedSchema["x-schema-version"] === "string" ? mergedSchema["x-schema-version"] : null,
-        schema_id: typeof mergedSchema.$id === "string" ? mergedSchema.$id : null,
+        schema_version: typeof mergedSchema["x-schema-version"] === "string"
+            ? mergedSchema["x-schema-version"]
+            : null,
+        schema_id: typeof mergedSchema.$id === "string"
+            ? mergedSchema.$id
+            : null,
         selected: {
             action: selectedAction ?? null,
             command: selectedCommand ?? null,
@@ -915,7 +1051,7 @@ export async function runContracts(options, global) {
             runtime_only: runtimeOnly,
             command_scoped: selectedCommand !== undefined,
         },
-        commands,
+        commands: outputCommands,
         runtime_schema: {
             statuses: statusRegistry.definitions.map((definition) => definition.id),
             open_status: statusRegistry.open_status,
@@ -924,7 +1060,9 @@ export async function runContracts(options, global) {
             types: [...typeRegistry.types],
             fields_by_command: Object.fromEntries([...runtimeFieldRegistry.command_to_fields.entries()].map(([command, definitions]) => [
                 command,
-                [...new Set(definitions.map((definition) => `--${definition.cli_flag}`))].sort((left, right) => left.localeCompare(right)),
+                [
+                    ...new Set(definitions.map((definition) => `--${definition.cli_flag}`)),
+                ].sort((left, right) => left.localeCompare(right)),
             ])),
         },
         extension_contracts: {
@@ -946,16 +1084,34 @@ export async function runContracts(options, global) {
         result.actions = actions;
         result.action_availability = actionAvailability;
     }
-    if (includeSchemaSurface) {
+    if (includeSchemaSurface && !omitUnfilteredSchema) {
         result.schema = filteredSchema;
         result.extension_commands = extensionCommandContracts;
     }
+    else if (includeSchemaSurface && omitUnfilteredSchema) {
+        result.schema_omitted_reason = "unfiltered_default_brief";
+        result.extension_commands = extensionCommandContracts;
+    }
     if (!schemaOnly && !availabilityOnly) {
-        result.command_flags = buildCommandFlagSurface(commands, extensionFlagMap, runtimeFieldFlagMap);
+        if (!omitUnfilteredCommandFlags) {
+            result.command_flags = buildCommandFlagSurface(outputCommands, extensionFlagMap, runtimeFieldFlagMap);
+        }
+        else {
+            result.command_flags_omitted_reason = "unfiltered_default_brief";
+        }
+        if (commandAliases.length > 0) {
+            result.command_aliases = commandAliases;
+        }
     }
     if (!schemaOnly && !flagsOnly && !availabilityOnly) {
-        result.commander_aliases = buildCommanderAliasSurface();
+        if (!omitUnfilteredCommanderAliases) {
+            result.commander_aliases = buildCommanderAliasSurface();
+        }
+        else {
+            result.commander_aliases_omitted_reason = "unfiltered_default_brief";
+        }
     }
     return result;
 }
-//# sourceMappingURL=contracts.js.map
+//# sourceMappingURL=contracts.js.map
+//# debugId=dc0f1970-8a30-56c5-827f-573784a38d54