@unbrained/pm-cli 2026.10.30 → 2026.11.1

package/.agents/skills/pm-user/references/ECOSYSTEM_PLANNING.md

@@ -10,7 +10,7 @@ implementation starts with bounded context and expands only its active lineage.
 ## Establish the Population
 
 ```bash
-pm context --limit 10 --for orient
+pm context --for orient
 pm search "<request keywords>" --limit 10   # hybrid when semantic search is configured, keyword otherwise
 pm list --status open --limit 20
 pm list --status in_progress --limit 20

package/.claude-plugin/marketplace.json

@@ -1 +1 @@
-{"name":"pm","owner":{"name":"unbrained","url":"https://github.com/unbraind/pm-cli"},"description":"Official marketplace for pm CLI — native git-based project management for Claude Code and AI coding agents.","version":"2026.10.30","plugins":[{"name":"pm-claude","source":"./plugins/pm-claude","description":"Native pm CLI integration for Claude Code — 32 MCP tools, 14 workflow skills with slash invocations, 4 subagents, hybrid TUI task tracking, session context injection, and coordination subagents for git-based project management without leaving Claude Code.","version":"2026.10.30","author":{"name":"unbrained","url":"https://github.com/unbraind/pm-cli"},"homepage":"https://github.com/unbraind/pm-cli","repository":"https://github.com/unbraind/pm-cli","license":"MIT","keywords":["pm-cli","project-management","mcp","tasks","agents","workflows","git-native","task-tracker","ai"],"category":"productivity"}]}
+{"name":"pm","owner":{"name":"unbrained","url":"https://github.com/unbraind/pm-cli"},"description":"Official marketplace for pm CLI — native git-based project management for Claude Code and AI coding agents.","version":"2026.11.1","plugins":[{"name":"pm-claude","source":"./plugins/pm-claude","description":"Native pm CLI integration for Claude Code — 32 MCP tools, 14 workflow skills with slash invocations, 4 subagents, hybrid TUI task tracking, session context injection, and coordination subagents for git-based project management without leaving Claude Code.","version":"2026.11.1","author":{"name":"unbrained","url":"https://github.com/unbraind/pm-cli"},"homepage":"https://github.com/unbraind/pm-cli","repository":"https://github.com/unbraind/pm-cli","license":"MIT","keywords":["pm-cli","project-management","mcp","tasks","agents","workflows","git-native","task-tracker","ai"],"category":"productivity"}]}

package/AGENTS.md

@@ -60,8 +60,8 @@ For real repository tracking, do not override `PM_PATH`. If a script must target
 <!-- pm-cli:agent-guidance:start:v1 -->
 ## pm Workflow (Agent Quickstart)
 
-- Cold start with the measured canonical orientation: `pm context --limit 10 --for orient`; before item mutation, also run `pm search "<keywords>" --limit 10`, `pm list --status open --limit 20`, and `pm list --status in_progress --limit 20`.
-- Claim and start atomically: `pm claim <id> --start`.
+- Cold start with the measured canonical orientation: `pm context --for orient`; before item mutation, also run `pm search "<keywords>" --limit 10`, `pm list --status open --limit 20`, and `pm list --status in_progress --limit 20`.
+- Claim and start: `pm claim <id> --start`, or `pm claim --next --start` to take the next available item in one write.
 - Link evidence while coding: `pm files <id> --add ...`, `pm docs <id> --add ...`, `pm test <id> --add command="node scripts/run-tests.mjs test"`.
 - Verify and close: `pm test <id> --run --progress`, then atomically record closure evidence with `pm close <id> "<reason>" --resolution "<what changed>" --expected "<expected outcome>" --actual "<observed outcome>" --validate-close warn`, then `pm release <id>`.
 - Author identity is automatic for supported agent harnesses; use `--author` only for an explicit override.
@@ -70,7 +70,7 @@ For real repository tracking, do not override `PM_PATH`. If a script must target
 
 ## Working Rules
 
-- **Orient:** start with the measured canonical cold-start, `pm context --limit 10 --for orient`. Before `pm create`, also run request-specific `pm search`, `pm list --status open`, and `pm list --status in_progress` so duplicate and ownership checks use live state. If net-new work is required, create or reuse the parent lineage first and record duplicate-check evidence in a create-time comment.
+- **Orient:** start with the measured canonical cold-start, `pm context --for orient`. Before `pm create`, also run request-specific `pm search`, `pm list --status open`, and `pm list --status in_progress` so duplicate and ownership checks use live state. If net-new work is required, create or reuse the parent lineage first and record duplicate-check evidence in a create-time comment.
 - **Verify before you claim:** the verification recipe for the Non-Negotiable above. A `closed` item whose `resolution`/`close_reason` describes the fix represents completed, shipped work — never describe it as outstanding. Confirm release/CI/infra status against the live system, e.g. `pm get pm-9gxi`, `npm view @unbrained/pm-cli version`, `gh release list`, `gh run list --workflow=auto-release.yml`.
 - **Implement:** keep edits scoped to the claimed item. Link changed files with `pm files`, docs with `pm docs`, and runnable verification with `pm test`.
 - **Record:** use `pm comments`, `pm notes`, and `pm learnings` for progress, rationale, and durable lessons. Prefer append-style updates over rewriting item content.

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## 2026.11.1 - 2026-11-01
+
+### Fixed
+
+- MCP read tools read every declared flat parameter, pm_search honours its keywords alias, and filtered pm context keeps dependency edges ([pm-hke9z7](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-hke9z7.toon))
+- GH-1642: compact brief pm list and pm search TOON envelopes while keeping the effective default sort visible ([pm-gh1642](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1642.toon))
+- GH-1644: disclose when a --for intent reduces an explicit --limit and recommend the measured canonical pm context --for orient ([pm-gh1644](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1644.toon))
+- GH-1643: make pm claim --next --start one atomic select-claim-start write and type the claim-target refusals ([pm-gh1643](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1643.toon))
+
+## 2026.10.31 - 2026-10-31
+
+### Changed
+
+- Update Sentry CLI to 3.8.2 after seven-day cooldown ([pm-sentry-cli-382](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-sentry-cli-382.toon))
+
+### Fixed
+
+- Successful linked-test receipts carry non-actionable execution_context and all-zero failure_categories, even under --lean ([pm-covpax](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-covpax.toon))
+- Unknown-option recovery drops a dash-leading prose value: the advertised replay closes, comments or creates without the user's text ([pm-stq61b](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-stq61b.toon))
+- GH-1633: accept comma-separated --unset field lists with per-field validation ([pm-gh1633](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1633.toon))
+- GH-1630: bound selective linked-test receipts to the selected collection ([pm-gh1630](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1630.toon))
+- GH-1626: offer same-command replay corrections for brief completeness spellings ([pm-gh1626](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1626.toon))
+- GH-1609: recover killed commit owners and bound lock waits with a monotonic clock ([pm-gh1609](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1609.toon))
+- GH-1624: define typed Unicode handling for extension output across JSON and TOON ([pm-gh1624](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1624.toon))
+- GH-1625: align extension-refusal Sentry capture with declared contracts and telemetry source context ([pm-gh1625](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1625.toon))
+- GH-1602: keep preflight warnings inside JSON error envelopes ([pm-gh1602](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1602.toon))
+- Bound independent native receipt regression cases ([pm-native-index-proof](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-native-index-proof.toon))
+- GH-1558: Settle Windows generation-fixture rename rejections without weakening lock assertions ([pm-gh1558](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1558.toon))
+- pm close clears the assignee but leaves claim_principal, so closed claimed items keep an active owner ([pm-8xgg7i](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-8xgg7i.toon))
+- GH-1618: prevent automated comment churn from misleading next-work priority ([pm-gh1618](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1618.toon))
+- GH-1610: compact lean refusals and expose structured claim context ([pm-gh1610](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1610.toon))
+- GH-1627: bound the entire next response and compact optional TOON sections losslessly ([pm-gh1627](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1627.toon))
+- GH-1628: preserve terminal timestamps for identical forced SDK updates ([pm-gh1628](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1628.toon))
+- Pull-request CI requests 33 hosted-runner jobs per push against the account's 20-job concurrency cap, so required checks wait hours before they start ([pm-m6ig79](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-m6ig79.toon))
+- Text refusals drop the specific What happened detail when an echoed argv overflows the diagnostic ceiling ([pm-4oc353](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-4oc353.toon))
+- GH-1622: investigate pm-presets SDK-loading fault blocking daily release ([pm-gh1622](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1622.toon))
+
+### Security
+
+- Registry advisories GHSA-mrwp-f3q8-3g9p (follow-redirects 1.16.1, high) and GHSA-g3hv-75wg-m249 (minimatch 10.2.6, moderate) block the static gate on main and every PR ([pm-irviv0](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-irviv0.toon))
+
 ## 2026.10.30 - 2026-10-30
 
 ### Added

package/README.md

@@ -102,7 +102,7 @@ pm release <item-id>
 Use the measured one-call context intent for cold-start orientation. Use `pm next` as an alternative when you only need the single highest-priority ready item, then search all statuses before creating anything. Measurement methodology and ratcheted evidence live in the [Agent Guide](docs/AGENT_GUIDE.md#agent-quick-context).
 
 ```bash
-pm context --limit 10 --for orient              # canonical cold start: state, ownership, actionable work
+pm context --for orient                         # canonical cold start: state, ownership, actionable work
 # Alternative: pm next                          # one actionable item + rationale, ready/blocked queues
 pm search "keywords for the requested work" --limit 10
 pm list --status open --limit 20

package/dist/cli/commander-usage.js

@@ -1,4 +1,4 @@
-(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="f07b9b70-b22d-5a5b-aec4-e1011286fb77")}catch{}})();import{pathExists,resolveItemTypeRegistry,EXIT_CODE,getSettingsPath,resolvePmRoot,readSettings,getActiveExtensionRegistrations,locateItem,runActiveServiceOverride,levenshteinDistanceWithinLimit}from"../sdk/runtime-primitives.js";import{BUILTIN_ITEM_TYPE_VALUES}from"../types/index.js";import{PM_CORE_COMMAND_NAMES,resolveSubcommandFlagContractsForCommand}from"../sdk/cli-contracts.js";import{formatCommanderErrorForDisplay,formatCommanderErrorForJson,projectLeanErrorEnvelope}from"./error-guidance.js";import{normalizeHelpCommandPath}from"./help-content.js";import{getCommandPath}from"./registration-helpers.js";import{EXECUTABLE_COMMAND_ALIASES,findBootstrapCommandTokenIndex,normalizeBootstrapInvocation,parseBootstrapHelpRequest,parseBootstrapGlobalOptions,parseBootstrapCommandName}from"./bootstrap-args.js";import{extractProvidedOptionFlags,normalizeLongFlag,renderPmCommand}from"./argv-utils.js";import{normalizeExtensionNameForMatch}from"./commands/extension/shared.js";import{canonicalizeCommandSuggestions,rankCommandPaths,resolveMisnestedCommandPath}from"../sdk/agent/command-suggestions.js";import{isCompatibleRecoveryFlag,renderMissingOptionRetry,resolveLifecycleVerbRecovery}from"../sdk/agent/command-recovery.js";import{resolvePmCommandScopeArgs}from"../sdk/command-line.js";import{attachOutputTokenAccounting}from"../sdk/output-token-accounting.js";import{findPmNamespacedCommand,resolvePmCommandAlias}from"../sdk/cli-contracts/command-aliases.js";const BUILTIN_TYPE_HELP_VALUES=BUILTIN_ITEM_TYPE_VALUES.join("|"),OPTIONAL_PACKAGE_INSTALL_HINTS={calendar:"calendar",cal:"calendar",reindex:"search-advanced","search-advanced":"search-advanced",guide:"guide-shell",completion:"guide-shell",templates:"templates","test-runs":"linked-test-adapters",beads:"beads",todos:"todos"},SEMANTIC_UNKNOWN_OPTION_SUGGESTIONS={comments:{"--body":["--add"],"--text":["--add"],"--comment":["--add"]},notes:{"--body":["--add"],"--text":["--add"],"--note":["--add"]},learnings:{"--body":["--add"],"--text":["--add"],"--learning":["--add"]},update:{"--add-tag":["--add-tags"],"--remove-tag":["--remove-tags"],"--tag":["--tags"]},create:{"--add-tag":["--add-tags"],"--tag":["--tags"]}},SCHEMA_SUBCOMMAND_VALUES=["add-field","add-status","add-type","apply-preset","list","list-fields","remap-status","remove-field","remove-status","remove-type","rename-field","rename-type","show","show-field","show-status"];function getSemanticUnknownOptionSuggestions(commandName,unknownOption){const commandSuggestions=SEMANTIC_UNKNOWN_OPTION_SUGGESTIONS[commandName];if(!commandSuggestions)return[];const normalizedUnknown=normalizeLongFlag(unknownOption);for(const[flag,suggestions]of Object.entries(commandSuggestions))if(normalizeLongFlag(flag)===normalizedUnknown)return suggestions;return[]}function appendCommanderExtensionFailures(renderedUsage,json,failures){if(failures.length===0)return renderedUsage;if(json){const primaryFailure2=failures.find(entry=>entry.declared_command_match===!0),{token_accounting:priorAccounting,...usage}=JSON.parse(renderedUsage),enriched={...usage,...primaryFailure2?{extension_command_failure:{code:"extension_command_activation_failed",extension:primaryFailure2.name,layer:primaryFailure2.layer,error:primaryFailure2.error,recovery_commands:primaryFailure2.recovery_commands??[]}}:{},failed_extensions:failures};return JSON.stringify(priorAccounting===void 0?enriched:attachOutputTokenAccounting(enriched,value=>`${JSON.stringify(value,null,2)}
+(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="e860a827-39e1-5d6c-b76e-0d77365ba202")}catch{}})();import{pathExists,resolveItemTypeRegistry,EXIT_CODE,getSettingsPath,resolvePmRoot,readSettings,getActiveExtensionRegistrations,locateItem,runActiveServiceOverride,levenshteinDistanceWithinLimit}from"../sdk/runtime-primitives.js";import{BUILTIN_ITEM_TYPE_VALUES}from"../types/index.js";import{PM_CORE_COMMAND_NAMES,resolveSubcommandFlagContractsForCommand}from"../sdk/cli-contracts.js";import{formatCommanderErrorForDisplay,formatCommanderErrorForJson,projectLeanErrorEnvelope}from"./error-guidance.js";import{normalizeHelpCommandPath}from"./help-content.js";import{getCommandPath}from"./registration-helpers.js";import{EXECUTABLE_COMMAND_ALIASES,findBootstrapCommandTokenIndex,normalizeBootstrapInvocation,parseBootstrapHelpRequest,parseBootstrapGlobalOptions,parseBootstrapCommandName}from"./bootstrap-args.js";import{extractProvidedOptionFlags,normalizeLongFlag,renderPmCommand}from"./argv-utils.js";import{normalizeExtensionNameForMatch}from"./commands/extension/shared.js";import{canonicalizeCommandSuggestions,rankCommandPaths,resolveMisnestedCommandPath}from"../sdk/agent/command-suggestions.js";import{isCompatibleRecoveryFlag,renderMissingOptionRetry,resolveLifecycleVerbRecovery}from"../sdk/agent/command-recovery.js";import{resolvePmCommandScopeArgs}from"../sdk/command-line.js";import{attachOutputTokenAccounting}from"../sdk/output-token-accounting.js";import{findPmNamespacedCommand,resolvePmCommandAlias}from"../sdk/cli-contracts/command-aliases.js";const BUILTIN_TYPE_HELP_VALUES=BUILTIN_ITEM_TYPE_VALUES.join("|"),OPTIONAL_PACKAGE_INSTALL_HINTS={calendar:"calendar",cal:"calendar",reindex:"search-advanced","search-advanced":"search-advanced",guide:"guide-shell",completion:"guide-shell",templates:"templates","test-runs":"linked-test-adapters",beads:"beads",todos:"todos"},SEMANTIC_UNKNOWN_OPTION_SUGGESTIONS={comments:{"--body":["--add"],"--text":["--add"],"--comment":["--add"]},notes:{"--body":["--add"],"--text":["--add"],"--note":["--add"]},learnings:{"--body":["--add"],"--text":["--add"],"--learning":["--add"]},update:{"--add-tag":["--add-tags"],"--remove-tag":["--remove-tags"],"--tag":["--tags"]},create:{"--add-tag":["--add-tags"],"--tag":["--tags"]}},SCHEMA_SUBCOMMAND_VALUES=["add-field","add-status","add-type","apply-preset","list","list-fields","remap-status","remove-field","remove-status","remove-type","rename-field","rename-type","show","show-field","show-status"];function getSemanticUnknownOptionSuggestions(commandName,unknownOption){const commandSuggestions=SEMANTIC_UNKNOWN_OPTION_SUGGESTIONS[commandName];if(!commandSuggestions)return[];const normalizedUnknown=normalizeLongFlag(unknownOption);for(const[flag,suggestions]of Object.entries(commandSuggestions))if(normalizeLongFlag(flag)===normalizedUnknown)return suggestions;return[]}function appendCommanderExtensionFailures(renderedUsage,json,failures){if(failures.length===0)return renderedUsage;if(json){const primaryFailure2=failures.find(entry=>entry.declared_command_match===!0),{token_accounting:priorAccounting,...usage}=JSON.parse(renderedUsage),enriched={...usage,...primaryFailure2?{extension_command_failure:{code:"extension_command_activation_failed",extension:primaryFailure2.name,layer:primaryFailure2.layer,error:primaryFailure2.error,recovery_commands:primaryFailure2.recovery_commands??[]}}:{},failed_extensions:failures};return JSON.stringify(priorAccounting===void 0?enriched:attachOutputTokenAccounting(enriched,value=>`${JSON.stringify(value,null,2)}
 `),null,2)}const details=failures.map(entry=>`- ${entry.layer}:${entry.name}: ${entry.error}`).join(`
 `),primaryFailure=failures.find(entry=>entry.declared_command_match===!0);if(!primaryFailure)return`${renderedUsage}
 Extension activation failures:
@@ -11,6 +11,6 @@ ${recovery}`:""}
 ${renderedUsage}
 Extension activation failures:
 ${details}`}function resolveUnknownCommanderToken(invocationArgv){return parseBootstrapHelpRequest(invocationArgv).commandPathTokens[0]??parseBootstrapCommandName(invocationArgv)??"<command>"}function collectRuntimeCommandPaths(root,extensionDescriptors){const commandPaths=new Set,queue=[...root.commands];for(;queue.length>0;){const current=queue.shift();if(!current)continue;const normalizedPath=normalizeHelpCommandPath(getCommandPath(current)),hasInternalSegment=normalizedPath.split(" ").some(segment=>segment.startsWith("_"));normalizedPath.length>0&&!hasInternalSegment&&commandPaths.add(normalizedPath),queue.push(...current.commands)}for(const descriptorPath of extensionDescriptors.keys()){const normalizedPath=normalizeHelpCommandPath(descriptorPath),hasInternalSegment=normalizedPath.split(" ").some(segment=>segment.startsWith("_"));normalizedPath.length>0&&!hasInternalSegment&&commandPaths.add(normalizedPath)}return[...commandPaths].sort((left,right)=>left.localeCompare(right))}function scoreCommandPathMatch(commandPath,queryToken){const normalizedPath=commandPath.trim().toLowerCase(),normalizedToken=queryToken.trim().toLowerCase();if(normalizedToken.length===0)return Number.POSITIVE_INFINITY;const pathSegments=normalizedPath.split(" ");if(normalizedPath===normalizedToken)return 0;if(pathSegments.includes(normalizedToken))return 1;if(pathSegments.some(segment=>segment.startsWith(normalizedToken)))return 2;if(normalizedPath.includes(normalizedToken))return 3;const maxDistance=normalizedToken.length>=5?2:1;let bestDistance=Number.POSITIVE_INFINITY;for(const segment of pathSegments){const distance=levenshteinDistanceWithinLimit(segment,normalizedToken,maxDistance);distance!==null&&(bestDistance=Math.min(bestDistance,distance))}return Number.isFinite(bestDistance)?4+bestDistance:Number.POSITIVE_INFINITY}function toComparableFlag(flag){return normalizeLongFlag(flag).slice(2).replace(/-/g,"")}function renderAttemptedCommand(argv){return renderPmCommand(argv)}function resolveOptionalPackageInstallHint(commandPath){const canonicalPath=resolvePmCommandAlias(commandPath)?.canonical??EXECUTABLE_COMMAND_ALIASES[commandPath]??commandPath,topLevel=canonicalPath.split(" ")[0]?.trim().toLowerCase();if(!topLevel)return null;const packageAlias=OPTIONAL_PACKAGE_INSTALL_HINTS[topLevel];return packageAlias?{packageAlias,canonicalPath,installCommand:`pm package install ${packageAlias} --project`}:null}function normalizePackageCommandAliasToken(value){let normalized=normalizeExtensionNameForMatch(value);for(const prefix of["@unbrained/","builtin-","pm-"])normalized.startsWith(prefix)&&(normalized=normalized.slice(prefix.length));return normalized}function collectInstalledPackageCommandPathHints(unknownToken,extensionDescriptors){const normalizedUnknown=normalizePackageCommandAliasToken(unknownToken);if(normalizedUnknown.length===0)return[];const hints=[];for(const descriptor of extensionDescriptors.values()){const identifiers=new Set,source=descriptor.source;if(source)for(const identifier of[source.name,source.package]){const normalizedIdentifier=normalizePackageCommandAliasToken(identifier??"");normalizedIdentifier.length>0&&identifiers.add(normalizedIdentifier)}identifiers.size!==0&&[...identifiers].some(identifier=>identifier===normalizedUnknown||identifier.includes(normalizedUnknown)||normalizedUnknown.includes(identifier))&&hints.push(descriptor.command)}return[...new Set(hints)].sort((left,right)=>left.localeCompare(right))}function collectKnownLongFlags(commandName,contractsOverride){const flags=new Set,contracts=contractsOverride??resolveSubcommandFlagContractsForCommand(commandName);for(const contract of contracts){contract.flag.startsWith("--")&&flags.add(normalizeLongFlag(contract.flag));for(const alias of contract.aliases??[])alias.startsWith("--")&&flags.add(normalizeLongFlag(alias))}return[...flags].sort((left,right)=>left.localeCompare(right))}function suggestNearestLongFlags(unknownOption,knownFlags){if(!unknownOption.startsWith("--"))return[];const unknownComparable=toComparableFlag(unknownOption);if(unknownComparable.length===0)return[];const maxDistance=unknownComparable.length>=8?2:1,candidates=[];for(const flag of knownFlags){const flagComparable=toComparableFlag(flag);if(flagComparable===unknownComparable)continue;if(unknownComparable.length>=3&&flagComparable.startsWith(unknownComparable)){candidates.push({flag,rank:0,distance:flagComparable.length-unknownComparable.length});continue}const distance=levenshteinDistanceWithinLimit(unknownComparable,flagComparable,maxDistance);distance===null||distance<=0||candidates.push({flag,rank:1,distance})}return candidates.sort((left,right)=>left.rank!==right.rank?left.rank-right.rank:left.distance!==right.distance?left.distance-right.distance:left.flag.localeCompare(right.flag)).map(entry=>entry.flag).slice(0,3)}let crossCommandFlagIndexCache;const CROSS_COMMAND_FLAG_EXCLUSIONS=new Set(["ctx","packages","list-draft","list-open","list-in-progress","list-blocked","list-closed","list-canceled","start-task","pause-task","close-task","help"]);function getCrossCommandFlagIndex(){if(crossCommandFlagIndexCache)return crossCommandFlagIndexCache;const index=new Map;for(const command of PM_CORE_COMMAND_NAMES)if(!CROSS_COMMAND_FLAG_EXCLUSIONS.has(command))for(const flag of collectKnownLongFlags(command)){const commands=index.get(flag)??[];commands.push(command),index.set(flag,commands)}return crossCommandFlagIndexCache=index,crossCommandFlagIndexCache}function findOtherCommandsForFlag(unknownOption,currentCommand){if(!unknownOption.startsWith("--"))return[];const commands=getCrossCommandFlagIndex().get(normalizeLongFlag(unknownOption));if(!commands)return[];const normalizedCurrent=currentCommand?.trim().toLowerCase(),currentFlags=new Set(collectKnownLongFlags(normalizedCurrent));return[...new Set(commands.filter(command=>command!==normalizedCurrent).map(command=>({command,sharedFlagCount:collectKnownLongFlags(command).filter(flag=>currentFlags.has(flag)).length})).sort((left,right)=>left.sharedFlagCount!==right.sharedFlagCount?right.sharedFlagCount-left.sharedFlagCount:left.command.localeCompare(right.command)).map(({command})=>resolvePmCommandAlias(command)?.canonical??command))]}function rewriteUnknownOptionArgv(argv,unknownOption,replacementFlag){for(let index=0;index<argv.length;index+=1){const token=argv[index];if(!token.startsWith("--"))continue;const equalsIndex=token.indexOf("="),key=equalsIndex>=0?token.slice(0,equalsIndex):token;if(normalizeLongFlag(key)!==normalizeLongFlag(unknownOption))continue;const next=[...argv];return next[index]=equalsIndex>=0?`${replacementFlag}${token.slice(equalsIndex)}`:replacementFlag,next}}function scoreRuntimeCommandCandidates(params){const commandPathSet=new Set(params.commandPaths),scoreAgainstUnknown=candidatePath=>Math.min(scoreCommandPathMatch(candidatePath,params.normalizedUnknown),params.primaryToken!==params.normalizedUnknown?scoreCommandPathMatch(candidatePath,params.primaryToken):Number.POSITIVE_INFINITY),scoresByCommandPath=new Map,recordCandidateScore=(commandPath,score)=>{if(!Number.isFinite(score)||!commandPathSet.has(commandPath))return;const existing=scoresByCommandPath.get(commandPath);(existing===void 0||score<existing)&&scoresByCommandPath.set(commandPath,score)};for(const commandPath of params.commandPaths)recordCandidateScore(commandPath,scoreAgainstUnknown(commandPath));for(const[aliasToken,canonicalPath]of Object.entries(EXECUTABLE_COMMAND_ALIASES))aliasToken!=="read"&&recordCandidateScore(canonicalPath,scoreAgainstUnknown(aliasToken));return[...scoresByCommandPath.entries()].sort(([leftPath,leftScore],[rightPath,rightScore])=>leftScore!==rightScore?leftScore-rightScore:leftPath.localeCompare(rightPath)).map(([commandPath])=>commandPath)}function resolveUnknownCommandCandidates(params){const exactAlias=resolvePmCommandAlias(params.normalizedUnknown),semanticCandidates=rankCommandPaths(params.commandPaths,params.primaryToken),rankedCandidates=scoreRuntimeCommandCandidates(params),installedPackageCandidates=collectInstalledPackageCommandPathHints(params.primaryToken,params.extensionDescriptors).filter(commandPath=>params.commandPaths.includes(commandPath));return canonicalizeCommandSuggestions([...exactAlias&&params.commandPaths.includes(exactAlias.canonical)?[exactAlias.canonical_argv.join(" ")]:[],...semanticCandidates,...rankedCandidates,...installedPackageCandidates],params.commandPaths,params.primaryToken).filter(path=>!params.normalizedUnknown.includes(" ")||path!==params.normalizedUnknown)}function resolveUnknownCommandFallbacks(commandPaths){return[...new Set(commandPaths.map(commandPath=>commandPath.split(" ")[0]).filter(segment=>segment.length>0))].sort((left,right)=>left.localeCompare(right))}function buildUnknownCommandExamples(suggestedPaths,hasConcreteCandidates){const suggestedExamples=suggestedPaths.map(path=>`pm ${path} --help`);return hasConcreteCandidates?[...new Set([...suggestedExamples,"pm --help --all"])]:[...new Set(["pm --help --all",...suggestedExamples])]}function resolveUnknownCommandPath(token,invocationArgv,commandPaths){let commandIndex=findBootstrapCommandTokenIndex([...invocationArgv]);const path=[];for(;commandIndex!==void 0;){if(path.push(invocationArgv[commandIndex]),invocationArgv[commandIndex]===token)return path.join(" ");if(!commandPaths.includes(path.join(" ")))return token;const offset=findBootstrapCommandTokenIndex(invocationArgv.slice(commandIndex+1));commandIndex=offset===void 0?void 0:commandIndex+1+offset}return token}function buildCanonicalHelpRetryArgs(canonicalPath,invocationArgv){if(!canonicalPath)return;const bootstrapGlobal=parseBootstrapGlobalOptions([...invocationArgv]);return[...resolvePmCommandScopeArgs(bootstrapGlobal),...canonicalPath.split(" "),"--help"]}function buildUnknownCommandGuidanceFromRuntime(rawMessage,root,extensionDescriptors,invocationArgv=[]){const unknownCommandMatch=rawMessage.match(/unknown command '([^']+)'/i);if(!unknownCommandMatch||typeof unknownCommandMatch[1]!="string")return;const commandPaths=collectRuntimeCommandPaths(root,extensionDescriptors),unknownPath=resolveUnknownCommandPath(unknownCommandMatch[1],invocationArgv,commandPaths),normalizedUnknown=normalizeHelpCommandPath(unknownPath);if(normalizedUnknown.length===0||commandPaths.length===0)return;const lifecycleRecovery=resolveLifecycleVerbRecovery(normalizedUnknown,commandPaths);if(lifecycleRecovery){const retryArgs2=buildCanonicalHelpRetryArgs("update",invocationArgv),bootstrapArgs=retryArgs2.slice(0,-2);return{suggestedRetryCommand:renderPmCommand(retryArgs2),suggestedRetryArgs:retryArgs2,unknownCommandExamples:[renderPmCommand(retryArgs2),...lifecycleRecovery.examples.map(args=>renderPmCommand([...bootstrapArgs,...args]))],unknownCommandNextSteps:lifecycleRecovery.nextSteps}}const optionalPackageHint=resolveOptionalPackageInstallHint(normalizedUnknown);if(optionalPackageHint&&!commandPaths.includes(optionalPackageHint.canonicalPath.split(" ")[0]))return{unknownCommandExamples:[optionalPackageHint.installCommand,`pm ${optionalPackageHint.canonicalPath} --help`,"pm --help --all"],unknownCommandNextSteps:[`"${normalizedUnknown}" is provided by the "${optionalPackageHint.packageAlias}" package. Install it with: ${optionalPackageHint.installCommand}. Command after installation: pm ${optionalPackageHint.canonicalPath}.`],suggestedRetryCommand:optionalPackageHint.installCommand};const primaryToken=normalizedUnknown.split(" ")[0],combinedCandidates=resolveUnknownCommandCandidates({commandPaths,normalizedUnknown,primaryToken,extensionDescriptors}),fallbackTopLevel=resolveUnknownCommandFallbacks(commandPaths),misnestedPath=resolveMisnestedCommandPath(normalizedUnknown,commandPaths),retryArgs=buildCanonicalHelpRetryArgs(misnestedPath,invocationArgv),suggestedPaths=[...new Set([...misnestedPath?[misnestedPath]:[],...combinedCandidates.length>0?combinedCandidates:canonicalizeCommandSuggestions(fallbackTopLevel,commandPaths)])].slice(0,3),examples=buildUnknownCommandExamples(suggestedPaths,combinedCandidates.length>0),didYouMean=combinedCandidates.length>0?`Did you mean: ${suggestedPaths.join(", ")}?`:null;return{...retryArgs?{suggestedRetryCommand:renderPmCommand(retryArgs),suggestedRetryArgs:retryArgs}:{},unknownCommandExamples:retryArgs?[renderPmCommand(retryArgs),...examples.slice(1)]:examples,unknownCommandNextSteps:[...didYouMean?[didYouMean]:[],'Run "pm --help --all" to list every command available in this runtime, including active extensions.',...didYouMean?["Use one of the suggested command paths above with --help to inspect valid flags and usage."]:[]]}}function dedupeStrings(values){return Array.from(new Set(values))}function firstWhitespaceSeparatedToken(input){let token="";for(const character of input){if(character===" "||character==="	"||character===`
-`||character==="\r"||character==="\f"||character==="\v")break;token+=character}return token}function trimTrailingPunctuationToken(token){let end=token.length;for(;end>0;){const character=token[end-1];if(character!==","&&character!==":"&&character!==";")break;end-=1}return token.slice(0,end)}function resolveChildCommandByToken(parent,token){const normalizedToken=token.trim().toLowerCase();return parent.commands.find(candidate=>candidate.name().trim().toLowerCase()===normalizedToken?!0:(typeof candidate.aliases=="function"?candidate.aliases():[]).some(alias=>alias.trim().toLowerCase()===normalizedToken))}function isKnownHelpCommandPath(root,commandPathTokens){if(commandPathTokens.length===0)return!0;let current=root;for(const[tokenIndex,token]of commandPathTokens.entries()){const next=resolveChildCommandByToken(current,token);if(!next){const declaredArguments=current.registeredArguments;return declaredArguments.length>0&&(current.commands.length===0||declaredArguments[0]?.required===!0)&&(declaredArguments.at(-1)?.variadic===!0||commandPathTokens.length-tokenIndex<=declaredArguments.length)}current=next}return!0}async function resolveWorkspaceUsageContext(bootstrapGlobal,message,invocationArgv,commandName){try{const pmRoot=resolvePmRoot(process.cwd(),bootstrapGlobal.path);if(!await pathExists(getSettingsPath(pmRoot)))return{allowedTypes:BUILTIN_TYPE_HELP_VALUES};const settings=await readSettings(pmRoot),extensionRegistrations=bootstrapGlobal.noExtensions?void 0:getActiveExtensionRegistrations(),typeRegistry=resolveItemTypeRegistry(settings,extensionRegistrations);let verifiedCollectionItemId;if(/too many arguments/i.test(message)&&["comments","docs","files","learnings","notes","test"].includes(commandName??"")){const commandIndex=invocationArgv.findIndex(token=>token===commandName),candidate=invocationArgv[commandIndex+2];if(invocationArgv[commandIndex+1]?.toLowerCase()==="add"&&candidate!==void 0&&!candidate.startsWith("-"))try{verifiedCollectionItemId=(await locateItem(pmRoot,candidate,settings.id_prefix,settings.item_format,typeRegistry.type_to_folder))?.id}catch{}}return{allowedTypes:typeRegistry.types.length>0?typeRegistry.types.join("|"):BUILTIN_TYPE_HELP_VALUES,pmRoot,settings,typeToFolder:typeRegistry.type_to_folder,verifiedCollectionItemId}}catch{return{allowedTypes:BUILTIN_TYPE_HELP_VALUES}}}function resolveUnknownOptionSuggestions(message,commandName){const match=message.match(/unknown option '([^']+)'/i),suggestions=match&&commandName?dedupeStrings([...getSemanticUnknownOptionSuggestions(commandName,match[1]),...suggestNearestLongFlags(match[1],collectKnownLongFlags(commandName))]).filter(candidate=>isCompatibleRecoveryFlag(match[1],candidate)):void 0,otherCommands=match?findOtherCommandsForFlag(match[1],commandName):[],declaredOnPath=match!==null&&collectKnownLongFlags(commandName).includes(normalizeLongFlag(match[1]));return{match,suggestions,otherCommands,scope:declaredOnPath?"declared_on_path":otherCommands.length>0?"declared_elsewhere":"declared_nowhere"}}function resolveSuggestedRetryForUnknownOption(invocationArgv,unknownOptionMatch,unknownOptionSuggestions){if(!unknownOptionMatch||!unknownOptionSuggestions||unknownOptionSuggestions.length===0)return;const rewritten=rewriteUnknownOptionArgv(invocationArgv,unknownOptionMatch[1],unknownOptionSuggestions[0]);return rewritten?renderAttemptedCommand(rewritten):void 0}function resolveSuggestedRetryForMissingOption(message,invocationArgv){const missingRequiredOption=message.match(/required option '([^']+)' not specified/i),requiredOptionToken=missingRequiredOption?.[1]?trimTrailingPunctuationToken(firstWhitespaceSeparatedToken(missingRequiredOption[1].trim())):void 0;if(!requiredOptionToken?.startsWith("--"))return;const commandName=parseBootstrapCommandName(invocationArgv);if(commandName)return renderMissingOptionRetry(invocationArgv,commandName,[requiredOptionToken])}function resolveSplitSchemaSubcommand(message,invocationArgv){if(!/too many arguments/i.test(message))return;const commandIndex=findBootstrapCommandTokenIndex(invocationArgv),namespaced=findPmNamespacedCommand(invocationArgv.slice(commandIndex));if(namespaced?.alias!=="schema")return;const schemaIndex=commandIndex+namespaced.canonical_argv.length-1,verb=invocationArgv[schemaIndex+1]?.trim().toLowerCase(),noun=invocationArgv[schemaIndex+2]?.trim().toLowerCase();if(!verb||!noun)return;const joined=`${verb}-${noun}`;if(!SCHEMA_SUBCOMMAND_VALUES.includes(joined))return;const rewritten=[...invocationArgv.slice(0,schemaIndex+1),joined,...invocationArgv.slice(schemaIndex+3)];return{unknownSubcommandPath:"schema",unknownSubcommandToken:`${verb} ${noun}`,unknownSubcommandAllowedValues:[...SCHEMA_SUBCOMMAND_VALUES],suggestedRetryCommand:renderAttemptedCommand(rewritten)}}function resolveRecoveryCommandName(message,invocationArgv,rootProgram,extensionDescriptors){const commandIndex=findBootstrapCommandTokenIndex(invocationArgv),inferred=findPmNamespacedCommand(invocationArgv.slice(commandIndex))?.alias??parseBootstrapCommandName(invocationArgv);if(!/unknown option /i.test(message)||inferred===void 0)return inferred;const canonical=resolvePmCommandAlias(inferred)?.canonical??inferred;return PM_CORE_COMMAND_NAMES.some(name=>name===inferred)||collectRuntimeCommandPaths(rootProgram,extensionDescriptors).includes(canonical)?inferred:void 0}async function resolveCommanderUsageContext(error,rootProgram,extensionDescriptors,guidanceOverrides={},invocationArgs=process.argv.slice(2)){const message=(typeof error=="object"&&error!==null?error.message:void 0)??"Invalid command usage",invocationArgv=normalizeBootstrapInvocation([...invocationArgs]).argv,bootstrapGlobal=parseBootstrapGlobalOptions(invocationArgv),commandName=resolveRecoveryCommandName(message,invocationArgv,rootProgram,extensionDescriptors),attemptedCommand=renderAttemptedCommand(invocationArgv),providedOptionFlags=extractProvidedOptionFlags(invocationArgv),workspaceUsage=await resolveWorkspaceUsageContext(bootstrapGlobal,message,invocationArgv,commandName),allowedTypes=workspaceUsage.allowedTypes,unknownCommandGuidance=buildUnknownCommandGuidanceFromRuntime(message,rootProgram,extensionDescriptors,invocationArgv),unknownOption=resolveUnknownOptionSuggestions(message,commandName),splitSchemaSubcommand=resolveSplitSchemaSubcommand(message,invocationArgv),suggestedRetryCommand=splitSchemaSubcommand?.suggestedRetryCommand??resolveSuggestedRetryForUnknownOption(invocationArgv,unknownOption.match,unknownOption.suggestions)??resolveSuggestedRetryForMissingOption(message,invocationArgv);return{message,commandName,allowedTypes,attemptedCommand,normalizedInvocationArgs:[...invocationArgv],providedOptionFlags,unknownOptionSuggestions:unknownOption.suggestions,unknownOptionOtherCommands:unknownOption.otherCommands.length>0?unknownOption.otherCommands.slice(0,12):void 0,unknownOptionOtherCommandsTotal:unknownOption.otherCommands.length>0?unknownOption.otherCommands.length:void 0,unknownOptionOtherCommandsTruncated:unknownOption.otherCommands.length>12||void 0,unknownOptionScope:unknownOption.scope,suggestedRetryCommand,verifiedCollectionItemId:workspaceUsage.verifiedCollectionItemId,...splitSchemaSubcommand,...unknownCommandGuidance,...guidanceOverrides}}async function formatCommanderUsageMessage(error,rootProgram,extensionDescriptors,guidanceOverrides={},invocationArgs=process.argv.slice(2)){const usageContext=await resolveCommanderUsageContext(error,rootProgram,extensionDescriptors,guidanceOverrides,invocationArgs),{message,commandName,allowedTypes,...guidance}=usageContext,formatted=formatCommanderErrorForDisplay(message,commandName,allowedTypes,guidance),serviceOverride=await runActiveServiceOverride("help_format",{message:formatted,command:commandName,allowed_types:allowedTypes});return serviceOverride.handled&&typeof serviceOverride.result=="string"?serviceOverride.result:formatted}async function formatCommanderUsageJson(error,rootProgram,extensionDescriptors,lean=!1,guidanceOverrides={},invocationArgs=process.argv.slice(2)){const usageContext=await resolveCommanderUsageContext(error,rootProgram,extensionDescriptors,guidanceOverrides,invocationArgs),envelope=formatCommanderErrorForJson(usageContext.message,usageContext.commandName,usageContext.allowedTypes,EXIT_CODE.USAGE,usageContext),projected=lean?projectLeanErrorEnvelope(envelope):envelope,accountingRequested=parseBootstrapGlobalOptions(usageContext.normalizedInvocationArgs).tokenAccounting===!0;return JSON.stringify(accountingRequested?attachOutputTokenAccounting(projected,value=>`${JSON.stringify(value,null,2)}
+`||character==="\r"||character==="\f"||character==="\v")break;token+=character}return token}function trimTrailingPunctuationToken(token){let end=token.length;for(;end>0;){const character=token[end-1];if(character!==","&&character!==":"&&character!==";")break;end-=1}return token.slice(0,end)}function resolveChildCommandByToken(parent,token){const normalizedToken=token.trim().toLowerCase();return parent.commands.find(candidate=>candidate.name().trim().toLowerCase()===normalizedToken?!0:(typeof candidate.aliases=="function"?candidate.aliases():[]).some(alias=>alias.trim().toLowerCase()===normalizedToken))}function isKnownHelpCommandPath(root,commandPathTokens){if(commandPathTokens.length===0)return!0;let current=root;for(const[tokenIndex,token]of commandPathTokens.entries()){const next=resolveChildCommandByToken(current,token);if(!next){const declaredArguments=current.registeredArguments;return declaredArguments.length>0&&(current.commands.length===0||declaredArguments[0]?.required===!0)&&(declaredArguments.at(-1)?.variadic===!0||commandPathTokens.length-tokenIndex<=declaredArguments.length)}current=next}return!0}async function resolveWorkspaceUsageContext(bootstrapGlobal,message,invocationArgv,commandName){try{const pmRoot=resolvePmRoot(process.cwd(),bootstrapGlobal.path);if(!await pathExists(getSettingsPath(pmRoot)))return{allowedTypes:BUILTIN_TYPE_HELP_VALUES};const settings=await readSettings(pmRoot),extensionRegistrations=bootstrapGlobal.noExtensions?void 0:getActiveExtensionRegistrations(),typeRegistry=resolveItemTypeRegistry(settings,extensionRegistrations);let verifiedCollectionItemId;if(/too many arguments/i.test(message)&&["comments","docs","files","learnings","notes","test"].includes(commandName??"")){const commandIndex=invocationArgv.findIndex(token=>token===commandName),candidate=invocationArgv[commandIndex+2];if(invocationArgv[commandIndex+1]?.toLowerCase()==="add"&&candidate!==void 0&&!candidate.startsWith("-"))try{verifiedCollectionItemId=(await locateItem(pmRoot,candidate,settings.id_prefix,settings.item_format,typeRegistry.type_to_folder))?.id}catch{}}return{allowedTypes:typeRegistry.types.length>0?typeRegistry.types.join("|"):BUILTIN_TYPE_HELP_VALUES,pmRoot,settings,typeToFolder:typeRegistry.type_to_folder,verifiedCollectionItemId}}catch{return{allowedTypes:BUILTIN_TYPE_HELP_VALUES}}}function resolveUnknownOptionSuggestions(message,commandName){const match=message.match(/unknown option '([^']+)'/i),suggestions=match&&commandName?dedupeStrings([...getSemanticUnknownOptionSuggestions(commandName,match[1]),...suggestNearestLongFlags(match[1],collectKnownLongFlags(commandName))]).filter(candidate=>isCompatibleRecoveryFlag(match[1],candidate)):void 0,otherCommands=match?findOtherCommandsForFlag(match[1],commandName):[],declaredOnPath=match!==null&&collectKnownLongFlags(commandName).includes(normalizeLongFlag(match[1]));return{match,suggestions,otherCommands,scope:declaredOnPath?"declared_on_path":otherCommands.length>0?"declared_elsewhere":"declared_nowhere"}}function resolveSuggestedRetryForUnknownOption(invocationArgv,unknownOptionMatch,unknownOptionSuggestions){if(!unknownOptionMatch||!unknownOptionSuggestions||unknownOptionSuggestions.length===0)return;const rewritten=rewriteUnknownOptionArgv(invocationArgv,unknownOptionMatch[1],unknownOptionSuggestions[0]);return rewritten?renderAttemptedCommand(rewritten):void 0}function resolveSuggestedRetryForMissingOption(message,invocationArgv){const missingRequiredOption=message.match(/required option '([^']+)' not specified/i),requiredOptionToken=missingRequiredOption?.[1]?trimTrailingPunctuationToken(firstWhitespaceSeparatedToken(missingRequiredOption[1].trim())):void 0;if(!requiredOptionToken?.startsWith("--"))return;const commandName=parseBootstrapCommandName(invocationArgv);if(commandName)return renderMissingOptionRetry(invocationArgv,commandName,[requiredOptionToken])}function resolveSplitSchemaSubcommand(message,invocationArgv){if(!/too many arguments/i.test(message))return;const commandIndex=findBootstrapCommandTokenIndex(invocationArgv),namespaced=findPmNamespacedCommand(invocationArgv.slice(commandIndex));if(namespaced?.alias!=="schema")return;const schemaIndex=commandIndex+namespaced.canonical_argv.length-1,verb=invocationArgv[schemaIndex+1]?.trim().toLowerCase(),noun=invocationArgv[schemaIndex+2]?.trim().toLowerCase();if(!verb||!noun)return;const joined=`${verb}-${noun}`;if(!SCHEMA_SUBCOMMAND_VALUES.includes(joined))return;const rewritten=[...invocationArgv.slice(0,schemaIndex+1),joined,...invocationArgv.slice(schemaIndex+3)];return{unknownSubcommandPath:"schema",unknownSubcommandToken:`${verb} ${noun}`,unknownSubcommandAllowedValues:[...SCHEMA_SUBCOMMAND_VALUES],suggestedRetryCommand:renderAttemptedCommand(rewritten)}}function resolveRecoveryCommandName(message,invocationArgv,rootProgram,extensionDescriptors){const commandIndex=findBootstrapCommandTokenIndex(invocationArgv),inferred=findPmNamespacedCommand(invocationArgv.slice(commandIndex))?.alias??parseBootstrapCommandName(invocationArgv);if(!/unknown option /i.test(message)||inferred===void 0)return inferred;const canonical=resolvePmCommandAlias(inferred)?.canonical??inferred;return PM_CORE_COMMAND_NAMES.some(name=>name===inferred)||collectRuntimeCommandPaths(rootProgram,extensionDescriptors).includes(canonical)?inferred:void 0}async function resolveCommanderUsageContext(error,rootProgram,extensionDescriptors,guidanceOverrides={},invocationArgs=process.argv.slice(2)){const message=(typeof error=="object"&&error!==null?error.message:void 0)??"Invalid command usage",invocationArgv=normalizeBootstrapInvocation([...invocationArgs]).argv,bootstrapGlobal=parseBootstrapGlobalOptions(invocationArgv),commandName=resolveRecoveryCommandName(message,invocationArgv,rootProgram,extensionDescriptors),attemptedCommand=renderAttemptedCommand(invocationArgv),providedOptionFlags=extractProvidedOptionFlags(invocationArgv),workspaceUsage=await resolveWorkspaceUsageContext(bootstrapGlobal,message,invocationArgv,commandName),allowedTypes=workspaceUsage.allowedTypes,unknownCommandGuidance=buildUnknownCommandGuidanceFromRuntime(message,rootProgram,extensionDescriptors,invocationArgv),unknownOption=resolveUnknownOptionSuggestions(message,commandName),splitSchemaSubcommand=resolveSplitSchemaSubcommand(message,invocationArgv),suggestedRetryCommand=splitSchemaSubcommand?.suggestedRetryCommand??resolveSuggestedRetryForUnknownOption(invocationArgv,unknownOption.match,unknownOption.suggestions)??resolveSuggestedRetryForMissingOption(message,invocationArgv);return{message,commandName,allowedTypes,attemptedCommand,normalizedInvocationArgs:[...invocationArgv],providedOptionFlags,unknownOptionSuggestions:unknownOption.suggestions,unknownOptionOtherCommands:unknownOption.otherCommands.length>0?unknownOption.otherCommands.slice(0,12):void 0,unknownOptionOtherCommandsTotal:unknownOption.otherCommands.length>0?unknownOption.otherCommands.length:void 0,unknownOptionOtherCommandsTruncated:unknownOption.otherCommands.length>12||void 0,unknownOptionScope:unknownOption.scope,suggestedRetryCommand,verifiedCollectionItemId:workspaceUsage.verifiedCollectionItemId,...splitSchemaSubcommand,...unknownCommandGuidance,...guidanceOverrides}}async function formatCommanderUsageMessage(error,rootProgram,extensionDescriptors,guidanceOverrides={},invocationArgs=process.argv.slice(2)){const usageContext=await resolveCommanderUsageContext(error,rootProgram,extensionDescriptors,guidanceOverrides,invocationArgs),{message,commandName,allowedTypes,...guidance}=usageContext,lean=parseBootstrapGlobalOptions(usageContext.normalizedInvocationArgs).lean,formatted=formatCommanderErrorForDisplay(message,commandName,allowedTypes,guidance,{lean}),serviceOverride=await runActiveServiceOverride("help_format",{message:formatted,command:commandName,allowed_types:allowedTypes});return serviceOverride.handled&&typeof serviceOverride.result=="string"?serviceOverride.result:formatted}async function formatCommanderUsageJson(error,rootProgram,extensionDescriptors,lean=!1,guidanceOverrides={},invocationArgs=process.argv.slice(2)){const usageContext=await resolveCommanderUsageContext(error,rootProgram,extensionDescriptors,guidanceOverrides,invocationArgs),envelope=formatCommanderErrorForJson(usageContext.message,usageContext.commandName,usageContext.allowedTypes,EXIT_CODE.USAGE,usageContext),projected=lean?projectLeanErrorEnvelope(envelope):envelope,accountingRequested=parseBootstrapGlobalOptions(usageContext.normalizedInvocationArgs).tokenAccounting===!0;return JSON.stringify(accountingRequested?attachOutputTokenAccounting(projected,value=>`${JSON.stringify(value,null,2)}
 `):projected,null,2)}const _testOnly={collectKnownLongFlags,collectInstalledPackageCommandPathHints,resolveOptionalPackageInstallHint,resolveSuggestedRetryForMissingOption,suggestNearestLongFlags};export{BUILTIN_TYPE_HELP_VALUES,_testOnly,appendCommanderExtensionFailures,buildUnknownCommandGuidanceFromRuntime,collectRuntimeCommandPaths,formatCommanderUsageJson,formatCommanderUsageMessage,isKnownHelpCommandPath,resolveChildCommandByToken,resolveCommanderUsageContext,resolveUnknownCommanderToken,scoreCommandPathMatch};
 //# sourceMappingURL=commander-usage.js.map

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

@@ -14,6 +14,12 @@ tombstone?:PmCliErrorContext["tombstone"];
 lease?:PmCliErrorContext["lease"];
 /** Lock generation observed at a refused lock_lost commit. */
 currentOwner?:PmCliErrorContext["current_owner"];
+/** Principal holding the item behind an already_claimed_by refusal. */
+claimedBy?:string;
+/** When that holder took the item; null when history was silent. */
+claimedAt?:string | null;
+/** Whether the holder arrived through a claim or an assignment. */
+claimSource?:PmCliErrorContext["claim_source"];
 code:string;
 type:string;
 title:string;
@@ -46,8 +52,20 @@ policy_violation_count?:number;
 /** Process exit code paired with the refusal. */
 exit_code:number;
 }
+/** Structured preflight advisories retained alongside a machine-readable outcome. */
+export interface PreflightWarningDiagnostics {
+/** Stable advisory codes emitted before command execution. */
+warnings?:string[];
+/** Additional actionable guidance that accompanies an advisory code. */
+warning_details?:Array<{
+/** Stable code identifying the advisory. */
+code:string;
+/** Human-readable remediation retained for this code. */
+message:string;
+}>;
+}
 /** Documents the json error envelope payload exchanged by command, SDK, and package integrations. */
-export interface JsonErrorEnvelope {
+export interface JsonErrorEnvelope extends PreflightWarningDiagnostics {
 /** Completed durable writes, with paths relative to the selected tracker. */
 side_effects?:PmCliErrorContext["side_effects"];
 /** Verified admission refusal before any mutation. */
@@ -64,6 +82,12 @@ tombstone?:PmCliErrorContext["tombstone"];
 lease?:PmCliErrorContext["lease"];
 /** Lock generation observed at a refused lock_lost commit, or null when none exists. */
 current_owner?:PmCliErrorContext["current_owner"];
+/** Principal holding the item behind an already_claimed_by refusal. */
+claimed_by?:string;
+/** When that holder took the item, or null when history was silent. */
+claimed_at?:string | null;
+/** Whether the holder arrived through an explicit claim or a metadata assignment. */
+claim_source?:PmCliErrorContext["claim_source"];
 /** Schema type that determines the shape and validation rules for this value. */
 type:string;
 /** Value that configures or reports code for this contract. */
@@ -101,7 +125,12 @@ diagnostic_output?:PmDiagnosticOutputReceipt;
 }
 /** Error envelope after deterministic budget projection. */
 export type ProjectedJsonErrorEnvelope = PmProjectedDiagnostic<JsonErrorEnvelope>;
-/** Compact an error envelope to fields that change the caller's next action. */
+/**
+ * Compact an error envelope to fields that change the caller's next action:
+ * the duplicated title, generic `required`/`why`/examples and the invocation
+ * echo go; code-specific rationale, examples, recovery and typed holder
+ * evidence stay (GH-1610).
+ */
 export declare function projectLeanErrorEnvelope(envelope:ProjectedJsonErrorEnvelope):ProjectedJsonErrorEnvelope;
 /** Documents the error classification payload exchanged by command, SDK, and package integrations. */
 export interface ErrorClassification {
@@ -121,6 +150,12 @@ tombstone?:PmCliErrorContext["tombstone"];
 lease?:PmCliErrorContext["lease"];
 /** Lock generation observed at a refused lock_lost commit, or null when none exists. */
 current_owner?:PmCliErrorContext["current_owner"];
+/** Principal holding the item behind an already_claimed_by refusal. */
+claimed_by?:string;
+/** When that holder took the item, or null when history was silent. */
+claimed_at?:string | null;
+/** Whether the holder arrived through an explicit claim or a metadata assignment. */
+claim_source?:PmCliErrorContext["claim_source"];
 /** Schema type that determines the shape and validation rules for this value. */
 type:string;
 /** Value that configures or reports code for this contract. */
@@ -199,8 +234,13 @@ declare function resolveKnownPackageCommandHint(commandToken:string):PackageComm
 declare function renderList(title:string,entries:string[]):string[];
 /** Whitelist valid recovery fields before exposing them in public CLI diagnostics. */
 declare function normalizeRecoveryPayload(payload:PmCliErrorRecoveryPayload | undefined):PmCliErrorRecoveryPayload | undefined;
+/** Presentation controls for text refusals. */
+export interface RenderGuidanceOptions {
+/** Omit constant boilerplate and the invocation echo; keep code-specific recovery (GH-1610). */
+lean?:boolean;
+}
 /** Implements render guidance message for the public runtime surface of this module. */
-export declare function renderGuidanceMessage(message:GuidanceMessage):string;
+export declare function renderGuidanceMessage(message:GuidanceMessage,options?:RenderGuidanceOptions):string;
 /** Project guidance into JSON, preserving no-write evidence only when explicitly verified. */
 declare function guidanceToJsonEnvelope(message:GuidanceMessage,exitCode:number):JsonErrorEnvelope;
 /** Classify guidance with the same optional refusal evidence as the JSON envelope. */
@@ -216,13 +256,13 @@ declare function appendIfMissing(entries:string[],value:string | undefined):stri
 /** Synthesize a copy-pasteable retry for the unquoted linked-test value shape `pm test <id> --add command npm test -- parser` by re-joining the shell-split value tokens into the documented quoted `key=value` form. Only fires when the item id already precedes the flag (so trailing tokens unambiguously belong to the value) and the token after `--add`/`--remove` is an entry-identity key. */
 export declare function buildLinkedTestQuotedRetryCommand(argv:string[] | undefined):string | undefined;
 /** Render concise initialization recovery or the bounded diagnostic for other failures. */
-export declare function formatPmCliErrorForDisplay(rawMessage:string,context?:PmCliErrorContext):string;
+export declare function formatPmCliErrorForDisplay(rawMessage:string,context?:PmCliErrorContext,options?:RenderGuidanceOptions):string;
 /** Implements classify pm cli error for the public runtime surface of this module. */
 export declare function classifyPmCliError(rawMessage:string,context?:PmCliErrorContext):ErrorClassification;
 /** Implements format pm cli error for json for the public runtime surface of this module. */
 export declare function formatPmCliErrorForJson(rawMessage:string,exitCode:number,context?:PmCliErrorContext):ProjectedJsonErrorEnvelope;
 /** Implements format commander error for display for the public runtime surface of this module. */
-export declare function formatCommanderErrorForDisplay(rawMessage:string,commandName:string | undefined,allowedTypes:string,context?:CommanderGuidanceContext):string;
+export declare function formatCommanderErrorForDisplay(rawMessage:string,commandName:string | undefined,allowedTypes:string,context?:CommanderGuidanceContext,options?:RenderGuidanceOptions):string;
 /** Implements classify commander error for the public runtime surface of this module. */
 export declare function classifyCommanderError(rawMessage:string,commandName:string | undefined,allowedTypes:string,context?:CommanderGuidanceContext):ErrorClassification;
 /** Implements format commander error for json for the public runtime surface of this module. */