@unbrained/pm-cli 2026.8.25 → 2026.8.27

package/dist/mcp/tool-definitions.d.ts

@@ -14,6 +14,8 @@ export interface ToolDefinition {
     description: string;
     /** Value that configures or reports input schema for this contract. */
     inputSchema: Record<string, unknown>;
+    /** Optional negotiated extension metadata projected during tools/list. */
+    _meta?: Record<string, unknown>;
 }
 /** MCP transport parameters layered over every canonical action schema. */
 export declare const TOOL_SCHEMA_BASE: {

package/dist/mcp/tool-definitions.js

@@ -4,7 +4,7 @@
  * Defines the Tool Definitions module for pm CLI source.
  */
 
-!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]="90896fb6-ee3e-575d-b103-bbc1a83c6672")}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]="b69edba8-884f-521c-9bc3-451c7df755a9")}catch(e){}}();
 import { GRAPH_SUBCOMMAND_VALUES, PM_DISCOVERABLE_TOOL_ACTIONS, } from "../sdk/cli-contracts/enum-contracts.js";
 import { buildPmActionToolInputSchema } from "../sdk/cli-contracts/tool-schema.js";
 import { RUNTIME_STATUS_ROLE_VALUES } from "../types.js";
@@ -748,4 +748,4 @@ export function buildMcpToolContracts() {
     }).sort((left, right) => left.name.localeCompare(right.name));
 }
 //# sourceMappingURL=tool-definitions.js.map
-//# debugId=90896fb6-ee3e-575d-b103-bbc1a83c6672
+//# debugId=b69edba8-884f-521c-9bc3-451c7df755a9

package/dist/sdk/agent/closed-domain-contracts.d.ts

@@ -15,7 +15,7 @@ export interface PmClosedDomainContract {
     /** Exact argv expected in the refusal's executable recovery. */
     suggested_retry_args: readonly string[];
     /** Stable machine-readable error code that owns the refusal. */
-    error_code: "projection_options_mutually_exclusive" | "unknown_context_intent" | "unknown_field_projection";
+    error_code: "package_upgrade_modes_mutually_exclusive" | "projection_options_mutually_exclusive" | "unknown_context_intent" | "unknown_field_projection";
     /** Whether a complete accepted-value domain is required in the refusal. */
     allowed_values_required?: boolean;
 }

package/dist/sdk/agent/closed-domain-contracts.js

@@ -6,7 +6,7 @@
  * without changing the stable core corpus.
  */
 
-!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]="35d4f3d7-7ec2-5a8b-bd96-f7e73c658737")}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]="95833d58-d6b9-5ab4-b447-5ce003643fd5")}catch(e){}}();
 import { PM_CONTEXT_INTENT_CONTRACTS } from "../context-intent-contracts.js";
 import { LIST_COMMAND_DEFAULT_PROJECTIONS, listGetProjectionFields, listListProjectionFields, listSearchProjectionFields, } from "../query/projection-contracts.js";
 const REJECTED_INTENT = "not-a-declared-intent";
@@ -107,6 +107,28 @@ export function listCoreClosedDomainContracts() {
             error_code: "projection_options_mutually_exclusive",
             allowed_values_required: false,
         },
+        {
+            probe_id: "package-upgrade-mutually-exclusive-modes",
+            command: "package upgrade",
+            flag: "--cli-only/--packages-only",
+            rejected_value: "--cli-only+--packages-only",
+            refusal_args: [
+                "package",
+                "upgrade",
+                "--cli-only",
+                "--packages-only",
+                "--dry-run",
+            ],
+            allowed_values: [],
+            suggested_retry_args: [
+                "package",
+                "upgrade",
+                "--packages-only",
+                "--dry-run",
+            ],
+            error_code: "package_upgrade_modes_mutually_exclusive",
+            allowed_values_required: false,
+        },
         {
             probe_id: "search-invalid-field",
             command: "search",
@@ -137,4 +159,4 @@ export function renderPmClosedDomainHelp(command, flag) {
     return `Allowed core values: ${canonicalValues.join("|")}.${runtimeSuffix}`;
 }
 //# sourceMappingURL=closed-domain-contracts.js.map
-//# debugId=35d4f3d7-7ec2-5a8b-bd96-f7e73c658737
+//# debugId=95833d58-d6b9-5ab4-b447-5ce003643fd5

package/dist/sdk/agent/refusal-closure-census.d.ts

@@ -44,10 +44,14 @@ export interface PmRefusalClosureCensusReport {
     /** Exactly one row for every catalog code. */
     rows: PmRefusalClosureCensusRow[];
 }
-/** Reviewed floor of 16 catalog rows; includes one alias across 15 canonical groups. */
+/** @deprecated Historical v1 floor retained for SDK compatibility. */
 export declare const PM_REFUSAL_CLOSURE_EXECUTABLE_CODE_BASELINE = 16;
-/** Fifteen canonical compatibility groups that must retain executable evidence. */
+/** @deprecated Historical v1 identities retained for SDK compatibility. */
 export declare const PM_REFUSAL_CLOSURE_EXECUTABLE_CANONICAL_CODE_BASELINE: readonly ["bulk_ids_input_empty", "bulk_ids_input_missing_path", "bulk_ids_input_unreadable", "invalid_argument_value", "missing_lifecycle_target", "missing_required_argument", "projection_options_mutually_exclusive", "tracker_not_initialized", "tracker_root_missing", "tracker_root_not_directory", "tracker_root_unreadable", "unknown_context_intent", "unknown_field_projection", "unknown_option", "unknown_subcommand"];
+/** Reviewed v2 floor of 18 catalog rows across 17 canonical groups. */
+export declare const PM_REFUSAL_CLOSURE_EXECUTABLE_CODE_BASELINE_V2 = 18;
+/** V2 canonical identities that must retain executable evidence. */
+export declare const PM_REFUSAL_CLOSURE_EXECUTABLE_CANONICAL_CODE_BASELINE_V2: readonly string[];
 /** Ratchet receipt that prevents catalog growth from erasing proven closure. */
 export declare function verifyPmRefusalClosureRatchet(report: PmRefusalClosureCensusReport, baseline?: number): {
     ok: boolean;

package/dist/sdk/agent/refusal-closure-census.js

@@ -1,8 +1,8 @@
-/** Reviewed floor of 16 catalog rows; includes one alias across 15 canonical groups. */
+/** @deprecated Historical v1 floor retained for SDK compatibility. */
 
-!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]="5560aa3a-036e-509c-955c-a09e9bf9df18")}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]="a1efaf49-c6ca-53dd-8fad-eb2540c20cc8")}catch(e){}}();
 export const PM_REFUSAL_CLOSURE_EXECUTABLE_CODE_BASELINE = 16;
-/** Fifteen canonical compatibility groups that must retain executable evidence. */
+/** @deprecated Historical v1 identities retained for SDK compatibility. */
 export const PM_REFUSAL_CLOSURE_EXECUTABLE_CANONICAL_CODE_BASELINE = Object.freeze([
     "bulk_ids_input_empty",
     "bulk_ids_input_missing_path",
@@ -20,8 +20,16 @@ export const PM_REFUSAL_CLOSURE_EXECUTABLE_CANONICAL_CODE_BASELINE = Object.free
     "unknown_option",
     "unknown_subcommand",
 ]);
+/** Reviewed v2 floor of 18 catalog rows across 17 canonical groups. */
+export const PM_REFUSAL_CLOSURE_EXECUTABLE_CODE_BASELINE_V2 = 18;
+/** V2 canonical identities that must retain executable evidence. */
+export const PM_REFUSAL_CLOSURE_EXECUTABLE_CANONICAL_CODE_BASELINE_V2 = Object.freeze([
+    ...PM_REFUSAL_CLOSURE_EXECUTABLE_CANONICAL_CODE_BASELINE,
+    "manifest_unknown_key",
+    "no_version_bounds_declared",
+].sort((left, right) => left.localeCompare(right)));
 /** Ratchet receipt that prevents catalog growth from erasing proven closure. */
-export function verifyPmRefusalClosureRatchet(report, baseline = PM_REFUSAL_CLOSURE_EXECUTABLE_CODE_BASELINE) {
+export function verifyPmRefusalClosureRatchet(report, baseline = PM_REFUSAL_CLOSURE_EXECUTABLE_CODE_BASELINE_V2) {
     return {
         ok: report.executable_error_code_count >= baseline,
         baseline,
@@ -29,7 +37,7 @@ export function verifyPmRefusalClosureRatchet(report, baseline = PM_REFUSAL_CLOS
     };
 }
 /** Ratchet canonical compatibility-group identities independently from counts. */
-export function verifyPmRefusalClosureIdentityRatchet(report, requiredCanonicalCodes = PM_REFUSAL_CLOSURE_EXECUTABLE_CANONICAL_CODE_BASELINE) {
+export function verifyPmRefusalClosureIdentityRatchet(report, requiredCanonicalCodes = PM_REFUSAL_CLOSURE_EXECUTABLE_CANONICAL_CODE_BASELINE_V2) {
     const executableCanonicalCodes = new Set(report.rows
         .filter(({ disposition }) => disposition === "executable")
         .map(({ canonical_code: canonicalCode }) => canonicalCode));
@@ -127,8 +135,8 @@ export function renderPmRefusalClosureCensusMarkdown(report) {
         "",
         `- Catalog error codes: ${report.catalog_error_code_count}`,
         `- Executable error codes: ${report.executable_error_code_count}`,
-        `- Executable-code ratchet floor: ${PM_REFUSAL_CLOSURE_EXECUTABLE_CODE_BASELINE}`,
-        `- Required executable canonical codes: ${PM_REFUSAL_CLOSURE_EXECUTABLE_CANONICAL_CODE_BASELINE.map((code) => `\`${code}\``).join(", ")}`,
+        `- Executable-code ratchet floor: ${PM_REFUSAL_CLOSURE_EXECUTABLE_CODE_BASELINE_V2}`,
+        `- Required executable canonical codes: ${PM_REFUSAL_CLOSURE_EXECUTABLE_CANONICAL_CODE_BASELINE_V2.map((code) => `\`${code}\``).join(", ")}`,
         `- Uncovered error codes: ${report.uncovered_error_code_count}`,
         `- Coverage fraction: ${report.coverage_fraction.toFixed(6)}`,
         `- Closed-domain probes: ${report.closed_domain_probe_count}`,
@@ -141,4 +149,4 @@ export function renderPmRefusalClosureCensusMarkdown(report) {
     ].join("\n");
 }
 //# sourceMappingURL=refusal-closure-census.js.map
-//# debugId=5560aa3a-036e-509c-955c-a09e9bf9df18
+//# debugId=a1efaf49-c6ca-53dd-8fad-eb2540c20cc8

package/dist/sdk/agent-capability-contracts.js

@@ -5,7 +5,7 @@
  * surfaces from one public SDK contract.
  */
 
-!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]="51e187c6-d48f-59e8-ad23-c72670ade3cc")}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]="d8f3f734-9adf-56f3-a5ba-c8b6407c4a89")}catch(e){}}();
 import { PM_CORE_COMMAND_NAMES } from "./cli-contracts/enum-contracts.js";
 const CORE_COMMANDS = new Set([
     "claim",
@@ -244,6 +244,8 @@ const CAPABILITY_FAMILY_ORDER = [
 ];
 const CAPABILITY_ROUTING_EXCLUDED_ALIASES = new Set([
     "ctx",
+    "extension",
+    "install",
     "item-reopen",
     "list-all",
     "list-blocked",
@@ -252,6 +254,8 @@ const CAPABILITY_ROUTING_EXCLUDED_ALIASES = new Set([
     "list-draft",
     "list-in-progress",
     "list-open",
+    "packages",
+    "upgrade",
 ]);
 /** Group the command registry for progressive-disclosure routing surfaces. */
 export function listPmCommandCapabilityGroups(contracts = PM_COMMAND_CAPABILITY_CONTRACTS) {
@@ -420,4 +424,4 @@ export function renderPmCapabilityRoutingMarkdown(contracts = PM_COMMAND_CAPABIL
     ].join("\n");
 }
 //# sourceMappingURL=agent-capability-contracts.js.map
-//# debugId=51e187c6-d48f-59e8-ad23-c72670ade3cc
+//# debugId=d8f3f734-9adf-56f3-a5ba-c8b6407c4a89

package/dist/sdk/cli-bootstrap.js

@@ -4,7 +4,7 @@
  * Provides public bootstrap argument normalization for embedded CLI hosts.
  */
 
-!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]="d45455ca-9496-5b8c-906c-d33d3d890e68")}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]="90f1f3ba-b3a9-5730-9cf7-8947e782a027")}catch(e){}}();
 import { EXECUTABLE_COMMAND_ALIASES, PM_COMMAND_ALIAS_CONTRACTS, renderPmCommandAliasMigrationHint, resolvePmCommandAlias, resolveSubcommandFlagContractsForCommand, } from "./cli-contracts.js";
 export { EXECUTABLE_COMMAND_ALIASES, PM_COMMAND_ALIAS_CONTRACTS, renderPmCommandAliasMigrationHint, resolvePmCommandAlias, };
 import { levenshteinDistanceWithinLimit } from "../core/shared/levenshtein.js";
@@ -50,6 +50,7 @@ const BOOTSTRAP_BOOLEAN_FLAGS = new Set([
     "--lean",
     "--token-accounting",
     "--output-row-contract",
+    "--all",
 ]);
 /** Consume one bootstrap-global token and update the accumulated parse state. */
 function consumeBootstrapGlobalToken(argv, index, state) {
@@ -895,4 +896,4 @@ export const _testOnly = {
     resolveCanonicalFlag,
 };
 //# sourceMappingURL=cli-bootstrap.js.map
-//# debugId=d45455ca-9496-5b8c-906c-d33d3d890e68
+//# debugId=90f1f3ba-b3a9-5730-9cf7-8947e782a027

package/dist/sdk/cli-contracts/command-aliases.js

@@ -10,7 +10,7 @@
  * are intentionally absent from default help and completion discovery.
  */
 
-!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]="9afc5057-afcd-5d6c-a4c1-c2883640fc50")}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]="3c9694bd-3635-5298-abeb-6899c94317ab")}catch(e){}}();
 export const PM_COMMAND_ALIAS_CONTRACTS = [
     ...[
         ["fetch", "get"],
@@ -70,6 +70,19 @@ export const PM_COMMAND_ALIAS_CONTRACTS = [
         registration: "commander",
         owner: "pm-pfqi",
     })),
+    ...[
+        ["extension", "package"],
+        ["install", "package install"],
+        ["upgrade", "package upgrade"],
+    ].map(([alias, canonical]) => ({
+        alias,
+        canonical,
+        canonical_argv: canonical.split(" "),
+        lifecycle: "deprecated",
+        hidden: true,
+        registration: "commander",
+        owner: "pm-tnud",
+    })),
 ];
 /** High-frequency executable aliases whose targets accept identical arguments. */
 export const EXECUTABLE_COMMAND_ALIASES = Object.fromEntries(PM_COMMAND_ALIAS_CONTRACTS.filter((contract) => contract.registration === "bootstrap").map((contract) => [contract.alias, contract.canonical]));
@@ -83,4 +96,4 @@ export function renderPmCommandAliasMigrationHint(contract) {
     return `Deprecated command \`${contract.alias}\`; use \`pm ${contract.canonical_argv.join(" ")}\`.`;
 }
 //# sourceMappingURL=command-aliases.js.map
-//# debugId=9afc5057-afcd-5d6c-a4c1-c2883640fc50
+//# debugId=3c9694bd-3635-5298-abeb-6899c94317ab

package/dist/sdk/cli-contracts/enum-contracts.d.ts

@@ -34,6 +34,8 @@ export declare const MERGE_SUBCOMMAND_VALUES: readonly ["install", "reconcile",
 export type MergeSubcommand = (typeof MERGE_SUBCOMMAND_VALUES)[number];
 /** Nested lifecycle verbs flattened by SDK and MCP package actions. */
 export declare const PM_EXTENSION_PACKAGE_ACTION_SUBCOMMANDS: readonly ["init", "install", "uninstall", "explore", "manage", "describe", "reload", "doctor", "catalog", "adopt", "adopt-all", "activate", "deactivate"];
+/** Package-only lifecycle verbs flattened by SDK and MCP package actions. */
+export declare const PM_PACKAGE_ONLY_ACTION_SUBCOMMANDS: readonly ["upgrade"];
 /** Noun-first item lifecycle verbs flattened for SDK and MCP dispatch. */
 export declare const PM_ITEM_ACTION_SUBCOMMANDS: readonly ["reopen"];
 /** CLI-only presentation commands intentionally omitted from programmatic actions. */
@@ -44,9 +46,10 @@ export declare const PM_CLI_ONLY_TOOL_ACTION_WAIVERS: {
 type PmCoreCommandName = (typeof PM_CORE_COMMAND_NAMES)[number];
 type PmCliOnlyToolAction = keyof typeof PM_CLI_ONLY_TOOL_ACTION_WAIVERS;
 type PmExtensionPackageAction = `${"extension" | "package"}-${(typeof PM_EXTENSION_PACKAGE_ACTION_SUBCOMMANDS)[number]}`;
+type PmPackageOnlyAction = `package-${(typeof PM_PACKAGE_ONLY_ACTION_SUBCOMMANDS)[number]}`;
 type PmItemAction = `item-${(typeof PM_ITEM_ACTION_SUBCOMMANDS)[number]}`;
 /** Restricts pm tool action values accepted by command, SDK, and storage contracts. */
-export type PmToolAction = Exclude<PmCoreCommandName, PmCliOnlyToolAction | "item"> | PmExtensionPackageAction | PmItemAction;
+export type PmToolAction = Exclude<PmCoreCommandName, PmCliOnlyToolAction | "item"> | PmExtensionPackageAction | PmPackageOnlyAction | PmItemAction;
 /**
  * Public pm tool actions derived from the CLI vocabulary. Nested extension and
  * package verbs are flattened for transports that expose one action string.

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

@@ -4,7 +4,7 @@
  * Defines SDK command-contract metadata for Enum Contracts.
  */
 
-!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]="3935bae8-0a40-59ea-aca6-64e238d1f318")}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]="6315a62f-6f55-5200-a5ea-ec892ff39f58")}catch(e){}}();
 import { KNOWN_EXTENSION_CAPABILITIES, KNOWN_EXTENSION_POLICY_MODES, KNOWN_EXTENSION_POLICY_SURFACES, KNOWN_EXTENSION_SANDBOX_PROFILES, KNOWN_EXTENSION_SERVICE_NAMES, KNOWN_EXTENSION_TRUST_MODES, } from "../../core/extensions/extension-types.js";
 import { PM_COMMAND_ALIAS_CONTRACTS } from "./command-aliases.js";
 /** Public contract for pm extension capability contracts, shared by SDK and presentation-layer consumers. */
@@ -147,6 +147,8 @@ export const PM_EXTENSION_PACKAGE_ACTION_SUBCOMMANDS = [
     "activate",
     "deactivate",
 ];
+/** Package-only lifecycle verbs flattened by SDK and MCP package actions. */
+export const PM_PACKAGE_ONLY_ACTION_SUBCOMMANDS = ["upgrade"];
 /** Noun-first item lifecycle verbs flattened for SDK and MCP dispatch. */
 export const PM_ITEM_ACTION_SUBCOMMANDS = ["reopen"];
 /** CLI-only presentation commands intentionally omitted from programmatic actions. */
@@ -164,6 +166,9 @@ export const PM_TOOL_ACTIONS = Object.freeze(PM_CORE_COMMAND_NAMES.flatMap((comm
     if (command === "extension" || command === "package") {
         return [
             ...PM_EXTENSION_PACKAGE_ACTION_SUBCOMMANDS.map((subcommand) => `${command}-${subcommand}`),
+            ...(command === "package"
+                ? PM_PACKAGE_ONLY_ACTION_SUBCOMMANDS.map((subcommand) => `package-${subcommand}`)
+                : []),
             command,
         ];
     }
@@ -215,4 +220,4 @@ export function isPmExtensionPolicySurfaceContract(value) {
     return PM_EXTENSION_POLICY_SURFACE_CONTRACTS.includes(value);
 }
 //# sourceMappingURL=enum-contracts.js.map
-//# debugId=3935bae8-0a40-59ea-aca6-64e238d1f318
+//# debugId=6315a62f-6f55-5200-a5ea-ec892ff39f58

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

@@ -7,7 +7,7 @@
  * flag surface stays single-sourced across the CLI, SDK, and MCP boundaries.
  */
 
-!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]="6664bc8f-e5da-5593-a2df-ac45f1cef09e")}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]="76fe6260-2386-52c5-8f94-aad48dec33f9")}catch(e){}}();
 import { normalizeUniqueStringList } from "./string-lists.js";
 import { RESERVED_EXTENSION_HOST_FLAGS } from "../../core/extensions/reserved-host-flags.js";
 import { PM_POSITIONAL_ACTION_CONTRACTS, } from "./grammar-contracts.js";
@@ -219,7 +219,7 @@ export const AGGREGATE_FLAG_CONTRACTS = [
 /** Public contract for comments flag contracts, shared by SDK and presentation-layer consumers. */
 export const COMMENTS_FLAG_CONTRACTS = [
     { flag: "--id", value_name: "item-id" },
-    { flag: "--add", aliases: ["--comment", "--body"] },
+    { flag: "--add", aliases: ["--comment", "--body", "--text"] },
     { flag: "--stdin" },
     { flag: "--file" },
     { flag: "--edit" },
@@ -238,7 +238,7 @@ function withCursorSemantics(contracts, presentationFlags) {
 /** Public contract for notes flag contracts, shared by SDK and presentation-layer consumers. */
 export const NOTES_FLAG_CONTRACTS = [
     { flag: "--id", value_name: "item-id" },
-    { flag: "--add", aliases: ["--note"] },
+    { flag: "--add", aliases: ["--note", "--text"] },
     { flag: "--add-json" },
     { flag: "--stdin" },
     { flag: "--file" },
@@ -256,7 +256,7 @@ export const NOTES_FLAG_CONTRACTS = [
 /** Public contract for learnings flag contracts, shared by SDK and presentation-layer consumers. */
 export const LEARNINGS_FLAG_CONTRACTS = [
     { flag: "--id", value_name: "item-id" },
-    { flag: "--add", aliases: ["--learning"] },
+    { flag: "--add", aliases: ["--learning", "--text"] },
     { flag: "--limit" },
     { flag: "--full-history" },
     { flag: "--author" },
@@ -1884,6 +1884,10 @@ export function resolveSubcommandFlagContractsForCommand(commandName) {
         rootCommand === "packages") &&
         lifecycleSubcommand !== undefined &&
         extraParts.length === 0) {
+        if ((rootCommand === "package" || rootCommand === "packages") &&
+            lifecycleSubcommand === "upgrade") {
+            return withSubcommandGlobalFlags(UPGRADE_FLAG_CONTRACTS);
+        }
         return withSubcommandGlobalFlags(resolveExtensionLifecycleFlagContracts(rootCommand, lifecycleSubcommand));
     }
     const contracts = SUBCOMMAND_FLAG_CONTRACTS_BY_COMMAND.get(normalized) ?? [];
@@ -1908,4 +1912,4 @@ export function toCompletionFlagString(flagContracts, includeGlobal = true) {
     return normalizeUniqueStringList(all).join(" ");
 }
 //# sourceMappingURL=flag-contracts.js.map
-//# debugId=6664bc8f-e5da-5593-a2df-ac45f1cef09e
+//# debugId=76fe6260-2386-52c5-8f94-aad48dec33f9

package/dist/sdk/cli-contracts/grammar-contracts.d.ts

@@ -6,11 +6,11 @@
  * this checked-in table in both directions so adding or removing a command
  * cannot silently bypass the architecture decision.
  */
-import type { PmCommandAliasContract } from "./command-aliases.js";
+import { type PmCommandAliasContract } from "./command-aliases.js";
 /** Canonical top-level domains an agent must retain to route pm operations. */
 export declare const PM_CLI_GRAMMAR_NOUNS: readonly ["item", "list", "context", "search", "graph", "history", "workspace", "package", "ops", "plan", "contracts", "help"];
 /** Shared verbs whose meaning transfers across domain nouns. */
-export declare const PM_CLI_SHARED_VERBS: readonly ["activate", "add", "adopt", "adopt-all", "catalog", "compact", "complete", "create", "deactivate", "delete", "describe", "doctor", "edit", "explore", "import", "init", "inspect", "install", "list", "manage", "migrate", "mutate", "read", "redact", "reload", "remove", "reopen", "repair", "restore", "run", "show", "uninstall", "verify"];
+export declare const PM_CLI_SHARED_VERBS: readonly ["activate", "add", "adopt", "adopt-all", "catalog", "compact", "complete", "create", "deactivate", "delete", "describe", "doctor", "edit", "explore", "import", "init", "inspect", "install", "list", "manage", "migrate", "mutate", "read", "redact", "reload", "remove", "reopen", "repair", "restore", "run", "show", "uninstall", "upgrade", "verify"];
 /** Why a current command is permitted while the grammar migration proceeds. */
 export type PmCommandDestinationDisposition = "target_noun" | "consolidation" | "package_owned" | "keep_as_is";
 /** Exact destination decision for one command emitted by runtime contracts. */
@@ -78,7 +78,7 @@ export declare const PM_COMMAND_POSITIONAL_CONTRACTS: readonly PmCommandPosition
 /** Immutable grammar policy used by contracts and the CI gate. */
 export declare const PM_CLI_GRAMMAR_CONTRACT: {
     readonly nouns: readonly ["item", "list", "context", "search", "graph", "history", "workspace", "package", "ops", "plan", "contracts", "help"];
-    readonly shared_verbs: readonly ["activate", "add", "adopt", "adopt-all", "catalog", "compact", "complete", "create", "deactivate", "delete", "describe", "doctor", "edit", "explore", "import", "init", "inspect", "install", "list", "manage", "migrate", "mutate", "read", "redact", "reload", "remove", "reopen", "repair", "restore", "run", "show", "uninstall", "verify"];
+    readonly shared_verbs: readonly ["activate", "add", "adopt", "adopt-all", "catalog", "compact", "complete", "create", "deactivate", "delete", "describe", "doctor", "edit", "explore", "import", "init", "inspect", "install", "list", "manage", "migrate", "mutate", "read", "redact", "reload", "remove", "reopen", "repair", "restore", "run", "show", "uninstall", "upgrade", "verify"];
     readonly scope_before_verb: true;
     readonly visible_top_level_ceiling: 69;
     readonly ceiling_raise_requires_pm_item: true;

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

@@ -1,6 +1,15 @@
-/** Canonical top-level domains an agent must retain to route pm operations. */
+/**
+ * @module sdk/cli-contracts/grammar-contracts
+ *
+ * Declares and verifies the agent-facing noun–verb grammar. The destination
+ * census is intentionally exact: live command contracts are compared with
+ * this checked-in table in both directions so adding or removing a command
+ * cannot silently bypass the architecture decision.
+ */
 
-!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]="21495fd2-6abb-5a4f-965c-e7b9c8f87dff")}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]="d0f4c030-0028-5acb-a438-210666118074")}catch(e){}}();
+import { resolvePmCommandAlias, } from "./command-aliases.js";
+/** Canonical top-level domains an agent must retain to route pm operations. */
 export const PM_CLI_GRAMMAR_NOUNS = [
     "item",
     "list",
@@ -49,6 +58,7 @@ export const PM_CLI_SHARED_VERBS = [
     "run",
     "show",
     "uninstall",
+    "upgrade",
     "verify",
 ];
 function positionalSlot(name, valueKind, required, options = {}) {
@@ -391,12 +401,6 @@ const EXPLICIT_POSITIONAL_SLOTS = new Map([
     ["deps", [ITEM_ID]],
     ["docs", [ITEM_ID]],
     ["event", [positionalSlot("title", "string", true)]],
-    [
-        "extension",
-        [positionalSlot("target", "string", false, { polymorphic: true })],
-    ],
-    ["extension list", []],
-    ["extension scaffold", [positionalSlot("target", "string", true)]],
     ["files", [ITEM_ID]],
     ["files discover", [ITEM_ID]],
     [
@@ -422,7 +426,6 @@ const EXPLICIT_POSITIONAL_SLOTS = new Map([
         "init",
         [positionalSlot("prefix-or-path", "string", false, { polymorphic: true })],
     ],
-    ["install", [positionalSlot("targets", "string", false, { variadic: true })]],
     ["item complete", [ITEM_ID, positionalSlot("reason", "string", false)]],
     ["item reopen", [ITEM_ID, positionalSlot("reason", "string", true)]],
     ["learnings", [ITEM_ID, OPTIONAL_TEXT]],
@@ -444,12 +447,14 @@ const EXPLICIT_POSITIONAL_SLOTS = new Map([
     ],
     ["package list", []],
     ["package scaffold", [positionalSlot("target", "string", true)]],
+    ["package upgrade", [positionalSlot("target", "string", false)]],
     [
         "packages",
         [positionalSlot("target", "string", false, { polymorphic: true })],
     ],
     ["packages list", []],
     ["packages scaffold", [positionalSlot("target", "string", true)]],
+    ["packages upgrade", [positionalSlot("target", "string", false)]],
     ["pause-task", [ITEM_ID]],
     [
         "plan",
@@ -494,7 +499,6 @@ const EXPLICIT_POSITIONAL_SLOTS = new Map([
     ],
     ["test", [ITEM_ID]],
     ["update", [ITEM_ID]],
-    ["upgrade", [positionalSlot("target", "string", false)]],
     [
         "workspace snapshot",
         [
@@ -528,7 +532,13 @@ function normalizePositionalCommandPath(command) {
 /** Resolve one declared signature without treating arbitrary object keys as commands. */
 export function resolvePmCommandPositionalContract(command) {
     const normalized = normalizePositionalCommandPath(command);
-    return PM_COMMAND_POSITIONAL_CONTRACTS.find((contract) => contract.command === normalized);
+    const direct = PM_COMMAND_POSITIONAL_CONTRACTS.find((contract) => contract.command === normalized);
+    if (direct)
+        return direct;
+    const canonical = resolvePmCommandAlias(normalized)?.canonical;
+    if (!canonical)
+        return undefined;
+    return PM_COMMAND_POSITIONAL_CONTRACTS.find((contract) => contract.command === canonical);
 }
 /** Resolve one action-specific help/contract view. */
 export function resolvePmPositionalActionContract(command) {
@@ -654,9 +664,9 @@ export const PM_COMMAND_DESTINATION_CONTRACTS = [
         "package reload",
         "package scaffold",
         "package uninstall",
+        "package upgrade",
     ]),
     ...destinationRows("package", "package", "consolidation", "pm-tnud", [
-        "extension",
         "extension activate",
         "extension adopt",
         "extension adopt-all",
@@ -667,13 +677,10 @@ export const PM_COMMAND_DESTINATION_CONTRACTS = [
         "extension explore",
         "extension init",
         "extension install",
-        "extension list",
         "extension manage",
         "extension migrate",
         "extension reload",
-        "extension scaffold",
         "extension uninstall",
-        "install",
         "packages",
         "packages activate",
         "packages adopt",
@@ -691,7 +698,7 @@ export const PM_COMMAND_DESTINATION_CONTRACTS = [
         "packages reload",
         "packages scaffold",
         "packages uninstall",
-        "upgrade",
+        "packages upgrade",
     ]),
     ...destinationRows("package", "package", "package_owned", "package:beads", [
         "beads import",
@@ -958,4 +965,4 @@ export function verifyPmCliGrammar(commands, aliases = [], destinations = PM_COM
     };
 }
 //# sourceMappingURL=grammar-contracts.js.map
-//# debugId=21495fd2-6abb-5a4f-965c-e7b9c8f87dff
+//# debugId=d0f4c030-0028-5acb-a438-210666118074

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

@@ -4,7 +4,7 @@
  * Implements the pm contracts command surface and its agent-facing runtime behavior.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="428a19d2-be42-548a-a328-aa0e476b8a71")}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]="a4c43fa6-9f2e-515c-ab47-d21ef5d7878e")}catch(e){}}();
 import { EXIT_CODE, SETTINGS_DEFAULTS, PmCliError, activateExtensions, getActiveExtensionRegistrations, loadExtensions, pathExists, commandOptionFlagLabel, resolveCommandOptionPolicyState, resolveItemTypeRegistry, resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, getSettingsPath, resolvePmRoot, readSettings, } from "../runtime-primitives.js";
 import { buildMcpToolContracts, } from "../../mcp/tool-definitions.js";
 import { ACTIVITY_COMMANDER_STRING_OPTION_CONTRACTS, ACTIVITY_FLAG_CONTRACTS, AGGREGATE_FLAG_CONTRACTS, ASSURANCE_FLAG_CONTRACTS, APPEND_FLAG_CONTRACTS, CALENDAR_COMMANDER_STRING_OPTION_CONTRACTS, CALENDAR_FLAG_CONTRACTS, CLAIM_FLAG_CONTRACTS, CLOSE_TASK_FLAG_CONTRACTS, COMMENTS_FLAG_CONTRACTS, CLOSE_FLAG_CONTRACTS, CLOSE_MANY_FLAG_CONTRACTS, COMPLETION_FLAG_CONTRACTS, CONFIG_FLAG_CONTRACTS, CONTRACTS_FLAG_CONTRACTS, COPY_FLAG_CONTRACTS, CONTEXT_COMMANDER_STRING_OPTION_CONTRACTS, CONTEXT_FLAG_CONTRACTS, CREATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, CREATE_COMMANDER_STRING_OPTION_CONTRACTS, CREATE_FLAG_CONTRACTS, DELETE_FLAG_CONTRACTS, DEPS_FLAG_CONTRACTS, GRAPH_FLAG_CONTRACTS, DOCS_FLAG_CONTRACTS, EXTENSION_ACTIVATE_FLAG_CONTRACTS, EXTENSION_ADOPT_ALL_FLAG_CONTRACTS, EXTENSION_ADOPT_FLAG_CONTRACTS, EXTENSION_CATALOG_FLAG_CONTRACTS, EXTENSION_DEACTIVATE_FLAG_CONTRACTS, EXTENSION_DESCRIBE_FLAG_CONTRACTS, EXTENSION_DOCTOR_FLAG_CONTRACTS, EXTENSION_EXPLORE_FLAG_CONTRACTS, EXTENSION_FLAG_CONTRACTS, EXTENSION_INIT_FLAG_CONTRACTS, EXTENSION_INSTALL_FLAG_CONTRACTS, EXTENSION_MANAGE_FLAG_CONTRACTS, EXTENSION_MIGRATE_FLAG_CONTRACTS, EXTENSION_RELOAD_FLAG_CONTRACTS, EXTENSION_UNINSTALL_FLAG_CONTRACTS, FILES_FLAG_CONTRACTS, FOCUS_FLAG_CONTRACTS, GC_FLAG_CONTRACTS, GET_FLAG_CONTRACTS, GUIDE_FLAG_CONTRACTS, GLOBAL_FLAG_CONTRACTS, HEALTH_FLAG_CONTRACTS, HISTORY_FLAG_CONTRACTS, HISTORY_COMPACT_FLAG_CONTRACTS, HISTORY_REDACT_FLAG_CONTRACTS, HISTORY_REPAIR_FLAG_CONTRACTS, HISTORY_AUTHOR_ACKNOWLEDGE_FLAG_CONTRACTS, INSTALL_FLAG_CONTRACTS, INIT_FLAG_CONTRACTS, ITEM_COMPLETE_FLAG_CONTRACTS, ITEM_MUTATE_FLAG_CONTRACTS, ITEM_REOPEN_FLAG_CONTRACTS, LEARNINGS_FLAG_CONTRACTS, LIST_COMMANDER_STRING_OPTION_CONTRACTS, LIST_FILTER_FLAG_CONTRACTS, MERGE_FLAG_CONTRACTS, NOTES_FLAG_CONTRACTS, PACKAGE_FLAG_CONTRACTS, PACKAGE_INIT_FLAG_CONTRACTS, PM_EXTENSION_CAPABILITY_CONTRACTS, PM_EXTENSION_POLICY_MODE_CONTRACTS, PM_EXTENSION_POLICY_SURFACE_CONTRACTS, PM_EXTENSION_SANDBOX_PROFILE_CONTRACTS, PM_EXTENSION_SERVICE_NAME_CONTRACTS, PM_EXTENSION_TRUST_MODE_CONTRACTS, PM_OUTPUT_DEGRADATION_STEPS, PLAN_FLAG_CONTRACTS, PM_CORE_COMMAND_NAMES, PM_DEPRECATED_TOOL_ACTIONS, PM_TOOL_ACTIONS, PM_TOOL_PARAMETERS_SCHEMA, REINDEX_FLAG_CONTRACTS, RELEASE_FLAG_CONTRACTS, RESTORE_FLAG_CONTRACTS, SCHEMA_FLAG_CONTRACTS, PROFILE_FLAG_CONTRACTS, SEARCH_COMMANDER_STRING_OPTION_CONTRACTS, EVAL_FLAG_CONTRACTS, WORKSPACE_FLAG_CONTRACTS, NEXT_FLAG_CONTRACTS, SEARCH_FLAG_CONTRACTS, STATS_FLAG_CONTRACTS, DUPLICATES_FLAG_CONTRACTS, START_TASK_FLAG_CONTRACTS, PAUSE_TASK_FLAG_CONTRACTS, TELEMETRY_FLAG_CONTRACTS, TEST_ALL_FLAG_CONTRACTS, TEST_FLAG_CONTRACTS, TEST_RUNS_FLAG_CONTRACTS, UPDATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, UPDATE_COMMANDER_STRING_OPTION_CONTRACTS, UPDATE_FLAG_CONTRACTS, UPDATE_MANY_FLAG_CONTRACTS, UPGRADE_FLAG_CONTRACTS, VALIDATE_FLAG_CONTRACTS, compactFlagAliasContracts, PM_COMMAND_ALIAS_CONTRACTS, PM_DIAGNOSTIC_OUTPUT_BUDGET_CONTRACTS, resolvePmCommandOutputBudget, } from "../cli-contracts.js";
@@ -217,7 +217,7 @@ const CANONICAL_COMMAND_ALIASES = [
     },
     {
         canonical: "package",
-        aliases: ["extension", "packages", "install"],
+        aliases: ["extension", "packages"],
     },
 ];
 const COMMAND_ALIAS_TO_CANONICAL = new Map(CANONICAL_COMMAND_ALIASES.flatMap((entry) => entry.aliases.map((alias) => [alias, entry.canonical])));
@@ -313,11 +313,9 @@ const COMMAND_INTENTS = new Map([
     ["history-redact", "Redact sensitive history values."],
     ["history-repair", "Repair history integrity."],
 ]);
-// Lifecycle subcommand flag contracts for `pm extension`. Only `init` differs
-// between extension and package: `pm package init` / `pm packages init`
-// additionally accept the package-only `--declarative` flag, so the package
-// variant swaps in PACKAGE_INIT_FLAG_CONTRACTS while every other subcommand is
-// shared verbatim.
+// Lifecycle subcommand flag contracts for `pm extension`. Package lifecycle
+// swaps in the declarative init contract and adds the package-only upgrade
+// command; every shared extension/package subcommand remains byte-identical.
 const EXTENSION_LIFECYCLE_FLAG_CONTRACTS = [
     ["init", EXTENSION_INIT_FLAG_CONTRACTS],
     ["install", EXTENSION_INSTALL_FLAG_CONTRACTS],
@@ -334,9 +332,12 @@ const EXTENSION_LIFECYCLE_FLAG_CONTRACTS = [
     ["deactivate", EXTENSION_DEACTIVATE_FLAG_CONTRACTS],
     ["migrate", EXTENSION_MIGRATE_FLAG_CONTRACTS],
 ];
-const PACKAGE_LIFECYCLE_FLAG_CONTRACTS = EXTENSION_LIFECYCLE_FLAG_CONTRACTS.map(([subcommand, flags]) => subcommand === "init"
-    ? [subcommand, PACKAGE_INIT_FLAG_CONTRACTS]
-    : [subcommand, flags]);
+const PACKAGE_LIFECYCLE_FLAG_CONTRACTS = [
+    ...EXTENSION_LIFECYCLE_FLAG_CONTRACTS.map(([subcommand, flags]) => subcommand === "init"
+        ? [subcommand, PACKAGE_INIT_FLAG_CONTRACTS]
+        : [subcommand, flags]),
+    ["upgrade", UPGRADE_FLAG_CONTRACTS],
+];
 const CORE_COMMAND_FLAG_CONTRACT_ENTRIES = [
     ...EXTENSION_LIFECYCLE_FLAG_CONTRACTS.map(([subcommand, flags]) => [`extension ${subcommand}`, flags]),
     ...PACKAGE_LIFECYCLE_FLAG_CONTRACTS.flatMap(([subcommand, flags]) => [
@@ -1686,6 +1687,7 @@ const COMMAND_OPERATION_INTENTS = new Map([
     ["run", "Run"],
     ["snapshot", "Manage snapshots for"],
     ["uninstall", "Uninstall"],
+    ["upgrade", "Upgrade"],
 ]);
 const COMMAND_INTENT_SUBJECT_OVERRIDES = new Map([
     ["extension adopt-all", "extensions"],
@@ -2082,4 +2084,4 @@ export const _testOnlyContractsCommand = {
     toRuntimeShortFlagToken,
 };
 //# sourceMappingURL=runtime-contracts.js.map
-//# debugId=428a19d2-be42-548a-a328-aa0e476b8a71
+//# debugId=a4c43fa6-9f2e-515c-ab47-d21ef5d7878e