@unbrained/pm-cli 2026.8.22 → 2026.8.24

package/.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Official marketplace for pm CLI — native git-based project management for Claude Code and AI coding agents.",
-    "version": "2026.8.22"
+    "version": "2026.8.24"
   },
   "plugins": [
     {
       "name": "pm-claude",
       "source": "./plugins/pm-claude",
       "description": "Native pm CLI integration for Claude Code — 28 MCP tools, 5 workflow skills, 14 slash commands, 4 subagents, hybrid TUI task tracking, session context injection, and coordination subagents for git-based project management without leaving Claude Code.",
-      "version": "2026.8.22",
+      "version": "2026.8.24",
       "author": {
         "name": "unbrained",
         "url": "https://github.com/unbraind/pm-cli"

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## 2026.8.24 - 2026-08-24
+
+### Fixed
+
+- Structured release-failure causes are preserved in blocked-release alerts ([pm-x63izf](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-x63izf.toon))
+- Bulk writes accept newline/comma IDs from argv, stdin, and @path with effect-aware exits ([pm-3oq022](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-3oq022.toon))
+- update-many --dry-run allows filter-only preview for review and bulk-selection workflows ([pm-kexu](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-kexu.toon))
+- Releases from the default branch are supported with analyzer evidence ([pm-u1baah](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-u1baah.toon))
+
+### Other
+
+- Uniform stdin convention: body-file and annotation --file flags accept '-' for stdin ([pm-iktj](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-iktj.toon))
+- Single source of surface tiering: one contract-declared tier per command drives CLI help, MCP tool profiles, completions, and docs together ([pm-kxci8x](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-kxci8x.toon))
+
+## 2026.8.23 - 2026-08-23
+
+### Added
+
+- Every instruction the product emits about its own next command is an unexecuted claim: the recovery vocabulary is generated, asserted as text, and run by nothing ([pm-h8tpeh](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-h8tpeh.toon))
+
+### Changed
+
+- Update ESLint to compatible 10.9.0 release ([pm-940mcx](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-940mcx.toon))
+
+### Fixed
+
+- Allow linked tests to opt out of source-workspace injection for self-sandboxing repo-wide gates ([pm-efkvdy](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-efkvdy.toon))
+- Linked-test schema context changes non-PM repository checks, so commands that pass directly fail when recorded and run through pm test ([pm-e97jyf](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-e97jyf.toon))
+- GH-1089: expose reproducible execution through supported CLI and MCP process configuration ([pm-gh1089](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1089.toon))
+- Budget recovery can recommend a smaller ceiling than the request that already truncated ([pm-xam9bt](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-xam9bt.toon))
+
+### Security
+
+- Linked-test commands are merge-unioned workspace data executed with shell:true — no provenance, allowlist, or confirmation boundary ([pm-ed28wi](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-ed28wi.toon))
+- Cross-harness provenance adapters: automatically resolve native model, version, and effort signals beyond Claude without identity flags ([pm-c0lrdm](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-c0lrdm.toon))
+
+### Other
+
+- Cross-process reproducibility gate: prove CLI and MCP deterministic runs are byte-identical and fail on ambient time leaks ([pm-vklr99](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-vklr99.toon))
+- Expose agent probe controls and versioned legacy-author vocabulary through pm config and SDK mutation APIs ([pm-yds9dt](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-yds9dt.toon))
+- Diagnostic output budget: errors, warnings, and recovery bundles are the output an agent reads most and the only output with no declared ceiling ([pm-cha95z](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-cha95z.toon))
+
 ## 2026.8.22 - 2026-08-22
 
 ### Fixed
@@ -81,7 +123,6 @@
 
 ### Fixed
 
-- A commit pushed directly to the default branch can never be released: both analyzer-evidence fallbacks presuppose a pull request, and nothing declares that precondition ([pm-u1baah](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-u1baah.toon))
 - GH-1052: typed fail-closed whole-list SDK primitive ([pm-y4aaol](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-y4aaol.toon))
 - Packed Bun SDK import fails on node:module stripTypeScriptTypes ([pm-ikj8ve](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-ikj8ve.toon))
 - GH-1051: package catalog rejects universal output-budget controls ([pm-2firut](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-2firut.toon))

package/dist/cli/description-stdin.js

@@ -4,14 +4,15 @@
  * Resolves the shared create/update description stdin sentinel.
  */
 
-!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]="e6b32b75-4618-5270-a79a-8564e97c7f3b")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="c55461f3-15d7-51f4-9e41-f71ce693b7b8")}catch(e){}}();
 import { createStdinTokenResolver } from "../sdk/runtime-primitives.js";
 /** Replace a description stdin sentinel with the complete standard-input payload. */
 export async function resolveDescriptionStdin(options) {
-    if (options.description === "-") {
+    if (typeof options.description === "string" &&
+        options.description.trim() === "-") {
         options.description =
-            (await createStdinTokenResolver().resolveValue("-", "--description")) ?? "";
+            (await createStdinTokenResolver().resolveValue(options.description, "--description")) ?? "";
     }
 }
 //# sourceMappingURL=description-stdin.js.map
-//# debugId=e6b32b75-4618-5270-a79a-8564e97c7f3b
+//# debugId=c55461f3-15d7-51f4-9e41-f71ce693b7b8

package/dist/cli/error-guidance.d.ts

@@ -21,6 +21,17 @@ interface GuidanceMessage {
     availableDependencies?: NonNullable<PmCliErrorContext["available_dependencies"]>;
     recovery?: PmCliErrorRecoveryPayload;
 }
+/** Compact refusal identity embedded in every structured error envelope. */
+export interface PmRefusalEnvelope {
+    /** Command, flag, or missing operand that rejected the invocation. */
+    surface: string;
+    /** Supplied scalar rejected by a closed domain, when available. */
+    rejected_value?: string;
+    /** Complete legal domain advertised by the refusal, when applicable. */
+    legal_domain?: string[];
+    /** Process exit code paired with the refusal. */
+    exit_code: number;
+}
 /** Documents the json error envelope payload exchanged by command, SDK, and package integrations. */
 export interface JsonErrorEnvelope {
     /** Schema type that determines the shape and validation rules for this value. */
@@ -53,6 +64,8 @@ export interface JsonErrorEnvelope {
     available_dependencies?: NonNullable<PmCliErrorContext["available_dependencies"]>;
     /** Value that configures or reports recovery for this contract. */
     recovery?: PmCliErrorRecoveryPayload;
+    /** Stable compact identity of the failing surface and legal recovery domain. */
+    refusal: PmRefusalEnvelope;
     /** Binding output-budget receipt for this diagnostic. */
     diagnostic_output?: PmDiagnosticOutputReceipt;
 }

package/dist/cli/error-guidance.js

@@ -1,5 +1,5 @@
 
-!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]="72da6986-67d5-5adf-8e63-4f654d9ec7dd")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="4bdb7fcf-dd74-57bc-8a0e-07539095462e")}catch(e){}}();
 import { resolveRecoveryCommandName } from "../sdk/agent/command-recovery.js";
 import { projectPmDiagnosticOutput, projectPmDiagnosticText, } from "../sdk/cli-contracts/agent-output-contracts.js";
 import { renderPmCommand } from "./argv-utils.js";
@@ -304,6 +304,42 @@ function attachStructuredGuidanceDetails(payload, message) {
     }
     return payload;
 }
+function resolveRefusalCandidateFlag(message, normalizedArgs) {
+    if (message.flag)
+        return message.flag;
+    return message.recovery?.provided_fields?.find((field) => field !== "--json" &&
+        field !== "--quiet" &&
+        normalizedArgs.includes(field));
+}
+function resolveRefusalRejectedValue(message, normalizedArgs, candidateFlag) {
+    if (message.value !== undefined)
+        return message.value;
+    if (candidateFlag) {
+        return normalizedArgs[normalizedArgs.indexOf(candidateFlag) + 1];
+    }
+    const allowedValues = message.recovery?.allowed_values;
+    if (!allowedValues?.length)
+        return undefined;
+    return normalizedArgs.find((argument, index) => index > 0 &&
+        !argument.startsWith("-") &&
+        !allowedValues.includes(argument));
+}
+function buildRefusalEnvelope(message, exitCode) {
+    const normalizedArgs = message.recovery?.normalized_args ?? [];
+    const candidateFlag = resolveRefusalCandidateFlag(message, normalizedArgs);
+    const rejectedValue = resolveRefusalRejectedValue(message, normalizedArgs, candidateFlag);
+    return {
+        surface: candidateFlag ??
+            message.recovery?.missing?.[0] ??
+            inferCommandNameFromRecovery(message.recovery) ??
+            "command",
+        ...(rejectedValue !== undefined ? { rejected_value: rejectedValue } : {}),
+        ...(message.recovery?.allowed_values?.length
+            ? { legal_domain: message.recovery.allowed_values }
+            : {}),
+        exit_code: exitCode,
+    };
+}
 function guidanceToJsonEnvelope(message, exitCode) {
     return attachStructuredGuidanceDetails({
         type: message.type,
@@ -312,8 +348,20 @@ function guidanceToJsonEnvelope(message, exitCode) {
         detail: message.happened,
         required: message.required,
         exit_code: exitCode,
+        refusal: buildRefusalEnvelope(message, exitCode),
     }, message);
 }
+function projectJsonErrorGuidance(guidance, exitCode) {
+    const recovery = guidance.recovery;
+    const hasActionableRecovery = Boolean(recovery?.suggested_retry) ||
+        Boolean(recovery?.suggested_retry_args?.length) ||
+        Boolean(recovery?.allowed_values?.length) ||
+        Boolean(recovery?.candidate_commands?.length) ||
+        Boolean(guidance.nextSteps?.length);
+    return projectPmDiagnosticOutput(guidanceToJsonEnvelope(guidance, exitCode), {
+        diagnosticClass: hasActionableRecovery ? "recovery_bundle" : "error",
+    });
+}
 function guidanceToClassification(message) {
     return attachStructuredGuidanceDetails({
         type: message.type,
@@ -415,7 +463,10 @@ function applyPmCliErrorContext(guidance, rawMessage, context) {
     const fallbackTitle = guidance.code === "command_failed" && context.code
         ? buildFallbackTitleFromMessage(normalizedRawMessage)
         : undefined;
-    const recovery = normalizeRecoveryPayload(context.recovery) ?? guidance.recovery;
+    const contextRecovery = normalizeRecoveryPayload(context.recovery);
+    const recovery = contextRecovery && guidance.recovery
+        ? normalizeRecoveryPayload({ ...guidance.recovery, ...contextRecovery })
+        : (contextRecovery ?? guidance.recovery);
     return {
         ...guidance,
         code,
@@ -600,6 +651,10 @@ function buildInvalidArgumentGuidance(rawMessage, message, context) {
         ? `pm ${commandName} --help`
         : "pm <command> --help";
     const allowedValues = inferAllowedValuesFromMessage(message);
+    const enrichedRecovery = normalizeRecoveryPayload({
+        ...recovery,
+        allowed_values: recovery?.allowed_values ?? allowedValues,
+    });
     const retryExample = buildAllowedValueRetryCommand(recovery, allowedValues);
     const examples = retryExample
         ? [retryExample, helpExample]
@@ -620,6 +675,7 @@ function buildInvalidArgumentGuidance(rawMessage, message, context) {
         why: "Validation protects data consistency and deterministic behavior across commands.",
         examples,
         nextSteps,
+        recovery: enrichedRecovery,
     }), rawMessage, context);
 }
 function buildPmCliErrorGuidance(rawMessage, context) {
@@ -1172,7 +1228,7 @@ export function classifyPmCliError(rawMessage, context) {
 }
 /** Implements format pm cli error for json for the public runtime surface of this module. */
 export function formatPmCliErrorForJson(rawMessage, exitCode, context) {
-    return projectPmDiagnosticOutput(guidanceToJsonEnvelope(buildPmCliErrorGuidance(rawMessage, context), exitCode));
+    return projectJsonErrorGuidance(buildPmCliErrorGuidance(rawMessage, context), exitCode);
 }
 /** Implements format commander error for display for the public runtime surface of this module. */
 export function formatCommanderErrorForDisplay(rawMessage, commandName, allowedTypes, context) {
@@ -1185,12 +1241,12 @@ export function classifyCommanderError(rawMessage, commandName, allowedTypes, co
 }
 /** Implements format commander error for json for the public runtime surface of this module. */
 export function formatCommanderErrorForJson(rawMessage, commandName, allowedTypes, exitCode, context) {
-    return projectPmDiagnosticOutput(guidanceToJsonEnvelope(buildCommanderErrorGuidance(rawMessage, commandName, allowedTypes, context), exitCode));
+    return projectJsonErrorGuidance(buildCommanderErrorGuidance(rawMessage, commandName, allowedTypes, context), exitCode);
 }
 /** Implements format unknown error for json for the public runtime surface of this module. */
 export function formatUnknownErrorForJson(rawMessage, exitCode) {
     const guidance = buildUnknownErrorGuidance(rawMessage);
-    return projectPmDiagnosticOutput(guidanceToJsonEnvelope(guidance, exitCode));
+    return projectJsonErrorGuidance(guidance, exitCode);
 }
 function buildUnknownErrorGuidance(rawMessage) {
     const message = normalizeMessage(rawMessage);
@@ -1241,4 +1297,4 @@ export const _testOnly = {
     resolveKnownPackageCommandHint,
 };
 //# sourceMappingURL=error-guidance.js.map
-//# debugId=72da6986-67d5-5adf-8e63-4f654d9ec7dd
+//# debugId=4bdb7fcf-dd74-57bc-8a0e-07539095462e

package/dist/cli/extension-command-help.d.ts

@@ -5,6 +5,7 @@
  */
 import { Command } from "commander";
 import { type FlagDefinition, type RegisteredExtensionCommandDefinition, type RegisteredExtensionFlagDefinitions } from "../sdk/runtime-primitives.js";
+import type { PmCommandCapabilityFamily, PmCommandVisibilityTier } from "../sdk/agent-capability-contracts.js";
 /** Documents the extension command argument help descriptor payload exchanged by command, SDK, and package integrations. */
 export interface ExtensionCommandArgumentHelpDescriptor {
     /** Value that configures or reports name for this contract. */
@@ -34,6 +35,10 @@ export interface ExtensionCommandHelpDescriptor {
     arguments: ExtensionCommandArgumentHelpDescriptor[];
     /** Value that configures or reports flags for this contract. */
     flags: FlagDefinition[];
+    /** Minimum agent surface tier declared by the package. */
+    tier: PmCommandVisibilityTier;
+    /** Capability family declared by the package. */
+    family: PmCommandCapabilityFamily;
     /** Value that configures or reports source for this contract. */
     source?: {
         layer: "global" | "project";

package/dist/cli/extension-command-help.js

@@ -4,7 +4,7 @@
  * Provides CLI runtime support for Extension Command Help.
  */
 
-!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]="45f3bebb-c075-5573-97bc-b573ae4d2d76")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="99d39b7c-ec26-5c95-85c0-ac28112a6fe6")}catch(e){}}();
 import { Option } from "commander";
 /** Implements normalize extension command path for the public runtime surface of this module. */
 export function normalizeExtensionCommandPath(commandPath) {
@@ -227,6 +227,8 @@ function collectExtensionDefinitionsByCommand(commandDefinitions) {
             failure_hints: normalizeExtensionCommandStringList(definition.failure_hints),
             arguments: normalizeExtensionCommandArguments(definition.arguments),
             flags: [],
+            tier: definition.tier ?? "standard",
+            family: definition.family ?? "extensions",
             source: {
                 layer: definition.layer,
                 name: definition.name,
@@ -300,6 +302,8 @@ export function collectExtensionCommandHelpDescriptors(commandHandlers, commandD
             failure_hints: [],
             arguments: [],
             flags,
+            tier: "standard",
+            family: "extensions",
         });
     }
     return descriptors;
@@ -630,4 +634,4 @@ export function reportExtensionCommandCollision(activationWarnings, report, warn
     report(`[pm] warning: ${warning}; core command preserved. Rename or namespace the extension command alias.`);
 }
 //# sourceMappingURL=extension-command-help.js.map
-//# debugId=45f3bebb-c075-5573-97bc-b573ae4d2d76
+//# debugId=99d39b7c-ec26-5c95-85c0-ac28112a6fe6

package/dist/cli/help-content.d.ts

@@ -4,6 +4,11 @@
  * Provides CLI runtime support for Help Content.
  */
 import { Command } from "commander";
+import { type PmCommandVisibilityTier } from "../sdk/agent-capability-contracts.js";
+/** Attach a package command's declared tier to its Commander presentation node. */
+export declare function setPmCommandHelpVisibilityTier(command: Command, tier: PmCommandVisibilityTier): void;
+/** Read presentation metadata attached to a package-created Commander node. */
+export declare function getPmCommandHelpVisibilityTier(command: Command): PmCommandVisibilityTier | undefined;
 /** Documents the help bundle payload exchanged by command, SDK, and package integrations. */
 export interface HelpBundle {
     /** Value that configures or reports why for this contract. */

package/dist/cli/help-content.js

@@ -1,7 +1,17 @@
 
-!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]="9cf83881-9464-5c18-b196-ee669057a873")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="5ea35d21-cfe6-5138-9fdb-413083719924")}catch(e){}}();
 import { parseBootstrapHelpRequest } from "./bootstrap-args.js";
 import { formatPmPositionalActionFlagTip, PM_POSITIONAL_ACTION_CONTRACTS, resolvePmPositionalActionContract, } from "../sdk/cli-contracts/grammar-contracts.js";
+import { listPmCommandsForTier, measurePmCoreHelp, PM_CORE_HELP_OPTION_FLAGS, } from "../sdk/agent-capability-contracts.js";
+const COMMAND_HELP_VISIBILITY_TIERS = new WeakMap();
+/** Attach a package command's declared tier to its Commander presentation node. */
+export function setPmCommandHelpVisibilityTier(command, tier) {
+    COMMAND_HELP_VISIBILITY_TIERS.set(command, tier);
+}
+/** Read presentation metadata attached to a package-created Commander node. */
+export function getPmCommandHelpVisibilityTier(command) {
+    return COMMAND_HELP_VISIBILITY_TIERS.get(command);
+}
 // Compact help/narrative surfaces show at most the first example. Centralizing this
 // keeps the empty-examples guard in one place for renderCompactHelpBundle and
 // resolveHelpNarrative (both must degrade to an empty list rather than [undefined]).
@@ -875,8 +885,51 @@ export function resolveHelpNarrative(commandPath, detailMode) {
 }
 /** Implements attach rich help text for the public runtime surface of this module. */
 export function attachRichHelpText(program, argv = process.argv.slice(2)) {
+    const baselineHelp = program.createHelp();
+    const coreCommands = new Set(listPmCommandsForTier("core"));
+    const coreOptions = new Set(PM_CORE_HELP_OPTION_FLAGS);
+    const selectedRootCommands = new Set();
+    program.configureHelp({
+        visibleCommands(command) {
+            const visible = baselineHelp.visibleCommands(command);
+            if (command !== program) {
+                return visible;
+            }
+            return visible.filter((candidate) => selectedRootCommands.has(candidate));
+        },
+        visibleOptions(command) {
+            const visible = baselineHelp.visibleOptions(command);
+            return command === program
+                ? visible.filter((option) => coreOptions.has(option.flags))
+                : visible;
+        },
+    });
     const detailMode = resolveHelpDetailMode(argv);
-    program.addHelpText("after", renderHelpBundle(ROOT_HELP_BUNDLE, detailMode));
+    const rootHelpText = renderHelpBundle(ROOT_HELP_BUNDLE, detailMode);
+    program.addHelpText("after", rootHelpText);
+    const budgetHelp = program.createHelp();
+    budgetHelp.prepareContext({
+        error: false,
+        helpWidth: 80,
+        outputHasColors: false,
+    });
+    const renderBudgetHelp = () => `${budgetHelp.formatHelp(program, budgetHelp)}${rootHelpText}\n`;
+    const rootCandidates = baselineHelp.visibleCommands(program);
+    for (const candidate of rootCandidates) {
+        const declaredTier = getPmCommandHelpVisibilityTier(candidate);
+        if (declaredTier === undefined &&
+            (candidate.name() === "help" || coreCommands.has(candidate.name()))) {
+            selectedRootCommands.add(candidate);
+        }
+    }
+    for (const candidate of rootCandidates) {
+        if (getPmCommandHelpVisibilityTier(candidate) !== "core")
+            continue;
+        selectedRootCommands.add(candidate);
+        if (!measurePmCoreHelp(renderBudgetHelp()).within_budget) {
+            selectedRootCommands.delete(candidate);
+        }
+    }
     for (const [commandPath, bundle] of Object.entries(HELP_BY_COMMAND_PATH)) {
         attachBundleByPath(program, commandPath, bundle, detailMode);
     }
@@ -910,4 +963,4 @@ export const _testOnly = {
     renderDetailedHelpBundle,
 };
 //# sourceMappingURL=help-content.js.map
-//# debugId=9cf83881-9464-5c18-b196-ee669057a873
+//# debugId=5ea35d21-cfe6-5138-9fdb-413083719924

package/dist/cli/help-json-payload.d.ts

@@ -32,13 +32,15 @@ export interface HelpSubcommandSummary {
     /** Shared command capability family. */
     family: PmCommandCapabilityFamily;
 }
+type ExtensionCommandSurface = Pick<ExtensionCommandHelpDescriptor, "tier" | "family">;
+declare function resolveExtensionCommandSurface(commandPath: string, descriptors: ReadonlyMap<string, ExtensionCommandHelpDescriptor>, allowDescendants?: boolean): ExtensionCommandSurface | undefined;
 declare function resolveCommandFromPathTokens(root: Command, pathTokens: string[]): Command | null;
 declare function readOptionAttributeName(option: unknown): string | null;
 declare function buildOptionAliasMap(options: unknown[]): Map<string, string[]>;
 declare function buildHelpOptionSummaries(command: Command): HelpOptionSummary[];
 declare function compactHelpOptionAliases(options: HelpOptionSummary[]): HelpOptionSummary[];
 declare function buildHelpArgumentSummaries(command: Command): HelpArgumentSummary[];
-declare function buildHelpSubcommandSummaries(command: Command): HelpSubcommandSummary[];
+declare function buildHelpSubcommandSummaries(command: Command, extensionDescriptors?: ReadonlyMap<string, ExtensionCommandHelpDescriptor>): HelpSubcommandSummary[];
 interface PositionalActionHelpProjection {
     arguments: HelpArgumentSummary[];
     options: HelpOptionSummary[];
@@ -46,7 +48,7 @@ interface PositionalActionHelpProjection {
     usage: string;
 }
 /** Build the command/action structural view shared by every JSON help field. */
-declare function buildPositionalActionHelpProjection(action: PmPositionalActionContract | undefined, targetCommand: Command, resolvedPath: string, allOptions: HelpOptionSummary[]): PositionalActionHelpProjection;
+declare function buildPositionalActionHelpProjection(action: PmPositionalActionContract | undefined, targetCommand: Command, resolvedPath: string, allOptions: HelpOptionSummary[], extensionDescriptors?: ReadonlyMap<string, ExtensionCommandHelpDescriptor>): PositionalActionHelpProjection;
 declare function buildJsonHelpPayload(rootProgram: Command, targetCommand: Command, argv: string[], requestedPath: string[], extensionDescriptors: ReadonlyMap<string, ExtensionCommandHelpDescriptor>): Record<string, unknown>;
 /** Implements maybe render bootstrap json help for the public runtime surface of this module. */
 export declare function maybeRenderBootstrapJsonHelp(rootProgram: Command, argv: string[], extensionDescriptors: ReadonlyMap<string, ExtensionCommandHelpDescriptor>): Promise<boolean>;
@@ -66,5 +68,6 @@ export declare const _testOnly: {
     compactHelpOptionAliases: typeof compactHelpOptionAliases;
     readOptionAttributeName: typeof readOptionAttributeName;
     resolveCommandFromPathTokens: typeof resolveCommandFromPathTokens;
+    resolveExtensionCommandSurface: typeof resolveExtensionCommandSurface;
 };
 export {};

package/dist/cli/help-json-payload.js

@@ -1,9 +1,9 @@
 
-!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]="abdb8d3e-8c1b-511e-b25b-220d5a40ae3f")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="26c3efa6-b820-5370-b0ab-65b08bc007ec")}catch(e){}}();
 import { hasSubcommandFlagContractsForCommand, PM_CORE_COMMAND_NAMES, } from "../sdk/cli-contracts.js";
 import { commandOptionFlagLabel, resolveCommandOptionPolicyState, resolveTypeDefinition, EXIT_CODE, printError, writeStdout, } from "../sdk/runtime-primitives.js";
 import { buildDynamicExtensionHelpOptionSummaries, mergeHelpOptionSummaries, findCommandByPath, findDirectChildCommand, commandAliases, } from "./extension-command-help.js";
-import { normalizeHelpCommandPath, resolveHelpDetailMode, resolveHelpNarrative, } from "./help-content.js";
+import { getPmCommandHelpVisibilityTier, normalizeHelpCommandPath, resolveHelpDetailMode, resolveHelpNarrative, } from "./help-content.js";
 import { getCommandPath } from "./registration-helpers.js";
 import { parseBootstrapGlobalOptions, parseBootstrapHelpRequest, parseBootstrapCommandName, parseBootstrapTypeValue, } from "./bootstrap-args.js";
 import { extractProvidedOptionFlags, renderPmCommand } from "./argv-utils.js";
@@ -12,6 +12,32 @@ import { BUILTIN_TYPE_HELP_VALUES, buildUnknownCommandGuidanceFromRuntime, } fro
 import { resolveCreateExplicitEmptyFlag } from "../sdk/agent/create-option-policy.js";
 import { formatPmPositionalActionFlagTip, PM_POSITIONAL_ACTION_CONTRACTS, resolvePmPositionalActionContract, } from "../sdk/cli-contracts/grammar-contracts.js";
 import { resolvePmCommandCapabilityFamily, resolvePmCommandVisibilityTier, } from "../sdk/agent-capability-contracts.js";
+const EXTENSION_TIER_ORDER = {
+    core: 0,
+    standard: 1,
+    full: 2,
+    internal: 3,
+};
+function resolveExtensionCommandSurface(commandPath, descriptors, allowDescendants = true) {
+    const exact = descriptors.get(commandPath);
+    if (exact)
+        return exact;
+    if (!allowDescendants)
+        return undefined;
+    const descendants = [...descriptors.entries()]
+        .filter(([path]) => path.startsWith(`${commandPath} `))
+        .map(([, descriptor]) => descriptor);
+    if (descendants.length === 0)
+        return undefined;
+    const tier = descendants.reduce((selected, descriptor) => EXTENSION_TIER_ORDER[descriptor.tier] < EXTENSION_TIER_ORDER[selected]
+        ? descriptor.tier
+        : selected, "internal");
+    const families = new Set(descendants.map(({ family }) => family));
+    return {
+        tier,
+        family: families.size === 1 ? descendants[0].family : "extensions",
+    };
+}
 function resolveCommandFromPathTokens(root, pathTokens) {
     if (pathTokens.length === 0) {
         return root;
@@ -180,20 +206,23 @@ function buildHelpArgumentSummaries(command) {
         };
     });
 }
-function buildHelpSubcommandSummaries(command) {
+function buildHelpSubcommandSummaries(command, extensionDescriptors = new Map()) {
     return command
         .createHelp()
         .visibleCommands(command)
         .filter((entry) => entry.name() !== "help" || command.parent === null)
         .map((entry) => {
-        const rootCommand = normalizeHelpCommandPath(getCommandPath(entry))
-            .split(" ")[0];
+        const commandPath = normalizeHelpCommandPath(getCommandPath(entry));
+        const rootCommand = commandPath.split(" ")[0];
+        const extensionDescriptor = resolveExtensionCommandSurface(commandPath, extensionDescriptors, getPmCommandHelpVisibilityTier(entry) !== undefined);
         return {
             name: entry.name().trim(),
             aliases: commandAliases(entry),
             description: entry.description().trim(),
-            tier: resolvePmCommandVisibilityTier(rootCommand),
-            family: resolvePmCommandCapabilityFamily(rootCommand),
+            tier: extensionDescriptor?.tier ??
+                resolvePmCommandVisibilityTier(rootCommand),
+            family: extensionDescriptor?.family ??
+                resolvePmCommandCapabilityFamily(rootCommand),
         };
     })
         .sort((left, right) => left.name.localeCompare(right.name));
@@ -223,11 +252,22 @@ function buildJsonHelpNarrative(detailMode, fallbackNarrative, extensionDescript
         detail_mode: detailMode,
     };
 }
+function resolveJsonHelpVisibilityTier(rootCommandPath, extensionDescriptor) {
+    if (rootCommandPath === undefined)
+        return null;
+    return (extensionDescriptor?.tier ?? resolvePmCommandVisibilityTier(rootCommandPath));
+}
+function resolveJsonHelpCapabilityFamily(rootCommandPath, extensionDescriptor) {
+    if (rootCommandPath === undefined)
+        return null;
+    return (extensionDescriptor?.family ??
+        resolvePmCommandCapabilityFamily(rootCommandPath));
+}
 /** Build the command/action structural view shared by every JSON help field. */
-function buildPositionalActionHelpProjection(action, targetCommand, resolvedPath, allOptions) {
+function buildPositionalActionHelpProjection(action, targetCommand, resolvedPath, allOptions, extensionDescriptors = new Map()) {
     if (!action) {
         const argumentsList = buildHelpArgumentSummaries(targetCommand);
-        const registeredSubcommands = buildHelpSubcommandSummaries(targetCommand);
+        const registeredSubcommands = buildHelpSubcommandSummaries(targetCommand, extensionDescriptors);
         const registeredSubcommandNames = new Set(registeredSubcommands.map(({ name }) => name));
         return {
             arguments: argumentsList,
@@ -289,21 +329,20 @@ function buildJsonHelpPayload(rootProgram, targetCommand, argv, requestedPath, e
     const extensionDescriptor = commandPath
         ? extensionDescriptors.get(commandPath)
         : undefined;
+    const extensionSurface = commandPath
+        ? resolveExtensionCommandSurface(commandPath, extensionDescriptors, getPmCommandHelpVisibilityTier(targetCommand) !== undefined)
+        : undefined;
     const narrative = buildJsonHelpNarrative(detailMode, fallbackNarrative, extensionDescriptor);
     const allOptionSummaries = compactHelpOptionAliases(mergeHelpOptionSummaries(buildHelpOptionSummaries(targetCommand), buildDynamicExtensionHelpOptionSummaries(extensionDescriptor)));
-    const projection = buildPositionalActionHelpProjection(positionalAction, targetCommand, projectedPath, allOptionSummaries);
+    const projection = buildPositionalActionHelpProjection(positionalAction, targetCommand, projectedPath, allOptionSummaries, extensionDescriptors);
     return {
         format: "pm_help_v1",
         detail_mode: detailMode,
         root_command: rootProgram.name(),
         requested_path: requestedPath,
         resolved_path: projectedPath.length > 0 ? projectedPath : rootProgram.name(),
-        visibility_tier: rootCommandPath === undefined
-            ? null
-            : resolvePmCommandVisibilityTier(rootCommandPath),
-        capability_family: rootCommandPath === undefined
-            ? null
-            : resolvePmCommandCapabilityFamily(rootCommandPath),
+        visibility_tier: resolveJsonHelpVisibilityTier(rootCommandPath, extensionSurface),
+        capability_family: resolveJsonHelpCapabilityFamily(rootCommandPath, extensionSurface),
         description: positionalAction?.description ?? targetCommand.description(),
         usage: projection.usage,
         intent: positionalAction?.description ?? narrative.intent,
@@ -487,6 +526,7 @@ export const _testOnly = {
     compactHelpOptionAliases,
     readOptionAttributeName,
     resolveCommandFromPathTokens,
+    resolveExtensionCommandSurface,
 };
 //# sourceMappingURL=help-json-payload.js.map
-//# debugId=abdb8d3e-8c1b-511e-b25b-220d5a40ae3f
+//# debugId=26c3efa6-b820-5370-b0ab-65b08bc007ec

package/dist/cli/main.d.ts

@@ -157,6 +157,8 @@ declare function loadRuntimeExtensionCommandDescriptorsForRecovery(pmRoot: strin
 declare function executeRegisteredRuntimeMigrations(migrations: RegisteredExtensionSchemaMigrationDefinition[], pmRoot: string): Promise<string[]>;
 declare function runRequiredExtensionCommand(command: Command, options: Record<string, unknown>, globalOptions: GlobalOptions, extensionFlagDefinitions?: LooseCommandFlagDefinition[]): Promise<unknown>;
 declare function wrapProgramActionsForExtensionHandlers(rootProgram: Command): void;
+/** Apply descendant-derived visibility to every generated extension namespace. */
+declare function applyDynamicExtensionRootHelpVisibility(rootProgram: Command, preexistingTopLevelCommands: ReadonlySet<string>, descriptors: ReadonlyMap<string, ExtensionCommandHelpDescriptor>): void;
 declare function registerDynamicExtensionCommandPaths(rootProgram: Command, invocationArgv: string[]): Promise<void>;
 interface CoreCommandRegistrationSelection {
     setup: boolean;
@@ -230,6 +232,7 @@ export declare function runPmCli(rawArgv?: string[]): Promise<void>;
 /** Public contract for test only, shared by SDK and presentation-layer consumers. */
 export declare const _testOnly: {
     activationCommandMatchesProbe: typeof activationCommandMatchesProbe;
+    applyDynamicExtensionRootHelpVisibility: typeof applyDynamicExtensionRootHelpVisibility;
     bootstrapProfileEnabled: typeof bootstrapProfileEnabled;
     buildBootstrapActivationProbe: typeof buildBootstrapActivationProbe;
     buildPostActionTelemetryOutcome: typeof buildPostActionTelemetryOutcome;