@unbrained/pm-cli 2026.8.26 → 2026.8.28

package/dist/sdk/cli-contracts.js

@@ -1,5 +1,5 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="c008aee5-ffe9-5da2-b1d9-6fb9fb6684c5")}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]="167b98d4-a5b5-581d-ac0a-17e8e3bfc490")}catch(e){}}();
 export { EXECUTABLE_COMMAND_ALIASES, PM_COMMAND_ALIAS_CONTRACTS, renderPmCommandAliasMigrationHint, resolvePmCommandAlias, } from "./cli-contracts/command-aliases.js";
 export { ACTIVITY_COMMANDER_STRING_OPTION_CONTRACTS, CALENDAR_COMMANDER_STRING_OPTION_CONTRACTS, CONTEXT_COMMANDER_STRING_OPTION_CONTRACTS, LIST_COMMANDER_STRING_OPTION_CONTRACTS, NEXT_COMMANDER_STRING_OPTION_CONTRACTS, SEARCH_COMMANDER_STRING_OPTION_CONTRACTS, readFirstValueFromCommanderOptions, readFirstStringFromCommanderOptions, readStringArrayFromCommanderOptions, } from "./cli-contracts/commander-types.js";
 export { CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, CREATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, CREATE_COMMANDER_STRING_OPTION_CONTRACTS, UPDATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, UPDATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, UPDATE_COMMANDER_STRING_OPTION_CONTRACTS, } from "./cli-contracts/commander-mutation-options.js";
@@ -7,7 +7,7 @@ export { CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, CREATE_COMMANDER_REPEAT
 // tables live in sibling modules and are re-exported here so existing import
 // sites (sdk/index.ts, mcp/server.ts, commands/contracts.ts, completion.ts, …)
 // keep importing everything from "./cli-contracts.js" unchanged.
-export { MERGE_SUBCOMMAND_VALUES, PM_EXTENSION_CAPABILITY_CONTRACTS, PM_EXTENSION_SERVICE_NAME_CONTRACTS, PM_EXTENSION_POLICY_MODE_CONTRACTS, PM_EXTENSION_TRUST_MODE_CONTRACTS, PM_EXTENSION_SANDBOX_PROFILE_CONTRACTS, PM_EXTENSION_POLICY_SURFACE_CONTRACTS, PM_CORE_COMMAND_NAMES, PM_CLI_ONLY_TOOL_ACTION_WAIVERS, PM_EXTENSION_PACKAGE_ACTION_SUBCOMMANDS, PM_ITEM_ACTION_SUBCOMMANDS, PM_DEPRECATED_TOOL_ACTIONS, PM_DISCOVERABLE_TOOL_ACTIONS, PM_TOOL_ACTIONS, analyzePmToolActionParity, isPmToolAction, isPmExtensionCapabilityContract, isPmExtensionServiceNameContract, isPmExtensionPolicyModeContract, isPmExtensionPolicySurfaceContract, } from "./cli-contracts/enum-contracts.js";
+export { MERGE_SUBCOMMAND_VALUES, PM_EXTENSION_CAPABILITY_CONTRACTS, PM_EXTENSION_SERVICE_NAME_CONTRACTS, PM_EXTENSION_POLICY_MODE_CONTRACTS, PM_EXTENSION_TRUST_MODE_CONTRACTS, PM_EXTENSION_SANDBOX_PROFILE_CONTRACTS, PM_EXTENSION_POLICY_SURFACE_CONTRACTS, PM_CORE_COMMAND_NAMES, PM_CLI_ONLY_TOOL_ACTION_WAIVERS, PM_EXTENSION_PACKAGE_ACTION_SUBCOMMANDS, PM_PACKAGE_ONLY_ACTION_SUBCOMMANDS, PM_ITEM_ACTION_SUBCOMMANDS, PM_DEPRECATED_TOOL_ACTIONS, PM_DISCOVERABLE_TOOL_ACTIONS, PM_TOOL_ACTIONS, analyzePmToolActionParity, isPmToolAction, isPmExtensionCapabilityContract, isPmExtensionServiceNameContract, isPmExtensionPolicyModeContract, isPmExtensionPolicySurfaceContract, } from "./cli-contracts/enum-contracts.js";
 export { TOOL_LIST_FILTER_OPTION_CONTRACTS, TOOL_AGGREGATE_OPTION_CONTRACTS, TOOL_SEARCH_FILTER_OPTION_CONTRACTS, TOOL_SHARED_CREATE_UPDATE_OPTION_CONTRACTS, TOOL_CREATE_OPTION_CONTRACTS, TOOL_UPDATE_OPTION_CONTRACTS, TOOL_UPDATE_MANY_FILTER_OPTION_CONTRACTS, TOOL_CLOSE_MANY_FILTER_OPTION_CONTRACTS, TOOL_CALENDAR_OPTION_CONTRACTS, TOOL_ACTIVITY_OPTION_CONTRACTS, TOOL_CONTEXT_OPTION_CONTRACTS, TOOL_DEPS_OPTION_CONTRACTS, TOOL_GRAPH_OPTION_CONTRACTS, TOOL_BULK_MUTATION_FILTER_OPTION_CONTRACT_SOURCE, TOOL_CREATE_OPTION_CONTRACT_SOURCE, TOOL_SHARED_CREATE_UPDATE_OPTION_CONTRACT_SOURCE, TOOL_UPDATE_OPTION_CONTRACT_SOURCE, verifyToolOptionCliParity, } from "./cli-contracts/tool-option-contracts.js";
 export { PM_COMMAND_POSITIONAL_CONTRACTS, PM_POSITIONAL_ACTION_CONTRACTS, } from "./cli-contracts/grammar-contracts.js";
 export { withFlagAliasMetadata, compactFlagAliasContracts, resolvePmPositionalActionFlagContracts, SUBCOMMAND_GLOBAL_FLAG_CONTRACTS, GLOBAL_FLAG_CONTRACTS, LIST_FILTER_FLAG_CONTRACTS, AGGREGATE_FLAG_CONTRACTS, COMMENTS_FLAG_CONTRACTS, NOTES_FLAG_CONTRACTS, LEARNINGS_FLAG_CONTRACTS, FILES_FLAG_CONTRACTS, DOCS_FLAG_CONTRACTS, HISTORY_FLAG_CONTRACTS, HISTORY_REDACT_FLAG_CONTRACTS, HISTORY_REPAIR_FLAG_CONTRACTS, HISTORY_AUTHOR_ACKNOWLEDGE_FLAG_CONTRACTS, HISTORY_COMPACT_FLAG_CONTRACTS, MERGE_FLAG_CONTRACTS, SCHEMA_FLAG_CONTRACTS, PROFILE_FLAG_CONTRACTS, PLAN_FLAG_CONTRACTS, INIT_FLAG_CONTRACTS, CONFIG_FLAG_CONTRACTS, EXTENSION_FLAG_CONTRACTS, EXTENSION_SCOPE_FLAG_CONTRACTS, EXTENSION_INIT_FLAG_CONTRACTS, EXTENSION_MIGRATE_FLAG_CONTRACTS, PACKAGE_FLAG_CONTRACTS, PACKAGE_INIT_FLAG_CONTRACTS, EXTENSION_INSTALL_FLAG_CONTRACTS, EXTENSION_UNINSTALL_FLAG_CONTRACTS, EXTENSION_EXPLORE_FLAG_CONTRACTS, EXTENSION_DESCRIBE_FLAG_CONTRACTS, EXTENSION_ADOPT_ALL_FLAG_CONTRACTS, EXTENSION_ACTIVATE_FLAG_CONTRACTS, EXTENSION_DEACTIVATE_FLAG_CONTRACTS, EXTENSION_MANAGE_FLAG_CONTRACTS, EXTENSION_RELOAD_FLAG_CONTRACTS, EXTENSION_DOCTOR_FLAG_CONTRACTS, EXTENSION_CATALOG_FLAG_CONTRACTS, EXTENSION_ADOPT_FLAG_CONTRACTS, INSTALL_FLAG_CONTRACTS, UPGRADE_FLAG_CONTRACTS, REINDEX_FLAG_CONTRACTS, CLOSE_FLAG_CONTRACTS, CLOSE_MANY_FLAG_CONTRACTS, APPEND_FLAG_CONTRACTS, CLAIM_FLAG_CONTRACTS, RESTORE_FLAG_CONTRACTS, DELETE_FLAG_CONTRACTS, RELEASE_FLAG_CONTRACTS, START_TASK_FLAG_CONTRACTS, PAUSE_TASK_FLAG_CONTRACTS, CLOSE_TASK_FLAG_CONTRACTS, MEET_FLAG_CONTRACTS, EVENT_FLAG_CONTRACTS, EVENTS_FLAG_CONTRACTS, REMIND_FLAG_CONTRACTS, TEST_FLAG_CONTRACTS, TEST_ALL_FLAG_CONTRACTS, TELEMETRY_FLAG_CONTRACTS, TEST_RUNS_FLAG_CONTRACTS, GC_FLAG_CONTRACTS, STATS_FLAG_CONTRACTS, DUPLICATES_FLAG_CONTRACTS, HEALTH_FLAG_CONTRACTS, VALIDATE_FLAG_CONTRACTS, ASSURANCE_FLAG_CONTRACTS, CREATE_FLAG_CONTRACTS, ITEM_COMPLETE_FLAG_CONTRACTS, ITEM_REOPEN_FLAG_CONTRACTS, ITEM_MUTATE_FLAG_CONTRACTS, COPY_FLAG_CONTRACTS, FOCUS_FLAG_CONTRACTS, UPDATE_FLAG_CONTRACTS, UPDATE_MANY_FLAG_CONTRACTS, CALENDAR_FLAG_CONTRACTS, ACTIVITY_FLAG_CONTRACTS, CONTEXT_FLAG_CONTRACTS, GET_FLAG_CONTRACTS, GUIDE_FLAG_CONTRACTS, DEPS_FLAG_CONTRACTS, GRAPH_FLAG_CONTRACTS, EVAL_FLAG_CONTRACTS, WORKSPACE_FLAG_CONTRACTS, NEXT_FLAG_CONTRACTS, SEARCH_FLAG_CONTRACTS, CONTRACTS_FLAG_CONTRACTS, COMPLETION_FLAG_CONTRACTS, hasSubcommandFlagContractsForCommand, resolveSubcommandFlagContractsForCommand, toCompletionFlagString, } from "./cli-contracts/flag-contracts.js";
@@ -15,4 +15,4 @@ export { buildPmActionToolInputSchema, PM_TOOL_RESERVED_CUSTOM_FIELD_PROPERTIES,
 export { analyzeSdkCliParameterCompleteness, } from "./cli-contracts/completeness.js";
 export { PM_COMMAND_OUTPUT_BUDGET_CONTRACTS, PM_DIAGNOSTIC_DEGRADATION_STEPS, PM_DIAGNOSTIC_OUTPUT_BUDGET_CONTRACTS, PM_DIAGNOSTIC_OUTPUT_CLASSES, PM_OUTPUT_BUDGET_CLASSES, PM_OUTPUT_DEGRADATION_STEPS, createPmCommandOutputBudget, definePmCommandOutputBudget, estimatePmOutputTokens, inferPmOutputBudgetClass, projectPmDiagnosticOutput, projectPmDiagnosticText, resolvePmDiagnosticOutputBudget, resolvePmCommandOutputBudget, } from "./cli-contracts/agent-output-contracts.js";
 //# sourceMappingURL=cli-contracts.js.map
-//# debugId=c008aee5-ffe9-5da2-b1d9-6fb9fb6684c5
+//# debugId=167b98d4-a5b5-581d-ac0a-17e8e3bfc490

package/dist/sdk/cli-program.js

@@ -4,7 +4,7 @@
  * Builds the reusable Commander root that embeds pm's universal global 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]="03d46cbf-73bc-50c9-b4e6-e7329ee53076")}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]="31e820a7-aa60-5e37-846d-c62b81b47587")}catch(e){}}();
 import { Command } from "commander";
 import { writeStdout } from "../core/output/output.js";
 /** Create a fresh pm root program suitable for one-shot CLI or embedded hosts. */
@@ -41,9 +41,10 @@ export function createPmCliProgram(version) {
         .option("--no-extensions", "Disable extension loading")
         .option("--no-pager", "Disable pager integration for help and long output")
         .option("--explain", "Render extended rationale and examples in help output")
+        .option("--all", "Reveal every public command and compatibility alias")
         .option("--profile", "Print deterministic timing diagnostics")
         .option("--author <id>", "Override mutation author for this invocation")
         .exitOverride();
 }
 //# sourceMappingURL=cli-program.js.map
-//# debugId=03d46cbf-73bc-50c9-b4e6-e7329ee53076
+//# debugId=31e820a7-aa60-5e37-846d-c62b81b47587

package/dist/sdk/comments.d.ts

@@ -19,6 +19,8 @@ export interface CommentsCommandOptions {
     includeMeta?: boolean;
     /** Return complete comment history after a mutation instead of a bounded receipt. */
     fullHistory?: boolean;
+    /** Append only when no comment has the same resolved author and text. */
+    ifAbsent?: boolean;
     /** Value that configures or reports author for this contract. */
     author?: string;
     /** Human-readable explanation suitable for logs and agent-facing output. */
@@ -46,6 +48,8 @@ export interface CommentsResult {
     mutation_receipt?: AnnotationMutationReceipt;
     /** Declares whether older comments were withheld from a mutation response. */
     omission_receipt?: AnnotationOmissionReceipt;
+    /** Whether a requested mutation changed persisted state. */
+    changed?: boolean;
 }
 /** Implements run comments for the public runtime surface of this module. */
 export declare function runComments(id: string, options: CommentsCommandOptions, global: GlobalOptions): Promise<CommentsResult>;

package/dist/sdk/comments.js

@@ -4,7 +4,7 @@
  * Implements the pm comments 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]="5167b367-26cf-52d5-8040-bb001ce3592a")}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]="f761d37b-28df-5176-9e25-762f57aa0abf")}catch(e){}}();
 import { isFileAbsentError } from "../core/fs/fs-utils.js";
 import { readFile } from "node:fs/promises";
 import { EXIT_CODE, PmCliError, createStdinTokenResolver, shouldResolveMutationStdinTokens, } from "./runtime-primitives.js";
@@ -131,4 +131,4 @@ export async function runComments(id, options, global) {
     });
 }
 //# sourceMappingURL=comments.js.map
-//# debugId=5167b367-26cf-52d5-8040-bb001ce3592a
+//# debugId=f761d37b-28df-5176-9e25-762f57aa0abf

package/dist/sdk/completion.js

@@ -4,11 +4,11 @@
  * Implements the pm completion 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]="48da3e98-ab96-54de-8993-7de0c4edf19b")}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]="4bf2b42b-91f3-5850-b1f1-d8a01525860c")}catch(e){}}();
 import { EXIT_CODE, PmCliError } from "./runtime-primitives.js";
 import { listPmCommandsForTier } from "./agent-capability-contracts.js";
 import { SCAFFOLD_CAPABILITIES } from "./extension/scaffold.js";
-import { AGGREGATE_FLAG_CONTRACTS, ACTIVITY_FLAG_CONTRACTS, APPEND_FLAG_CONTRACTS, CALENDAR_FLAG_CONTRACTS, CLOSE_MANY_FLAG_CONTRACTS, COMPLETION_FLAG_CONTRACTS, CONTRACTS_FLAG_CONTRACTS, CONTEXT_FLAG_CONTRACTS, COPY_FLAG_CONTRACTS, FOCUS_FLAG_CONTRACTS, MEET_FLAG_CONTRACTS, REMIND_FLAG_CONTRACTS, CREATE_FLAG_CONTRACTS, DEPS_FLAG_CONTRACTS, DUPLICATES_FLAG_CONTRACTS, EXTENSION_FLAG_CONTRACTS, GRAPH_FLAG_CONTRACTS, GET_FLAG_CONTRACTS, GUIDE_FLAG_CONTRACTS, GLOBAL_FLAG_CONTRACTS, HEALTH_FLAG_CONTRACTS, HISTORY_AUTHOR_ACKNOWLEDGE_FLAG_CONTRACTS, HISTORY_FLAG_CONTRACTS, INIT_FLAG_CONTRACTS, LIST_FILTER_FLAG_CONTRACTS, NEXT_FLAG_CONTRACTS, PM_COMMAND_ALIAS_CONTRACTS, PACKAGE_FLAG_CONTRACTS, PLAN_FLAG_CONTRACTS, SEARCH_FLAG_CONTRACTS, STATS_FLAG_CONTRACTS, EVENTS_FLAG_CONTRACTS, UPDATE_FLAG_CONTRACTS, UPDATE_MANY_FLAG_CONTRACTS, toCompletionFlagString, } from "./cli-contracts.js";
+import { AGGREGATE_FLAG_CONTRACTS, ACTIVITY_FLAG_CONTRACTS, APPEND_FLAG_CONTRACTS, CALENDAR_FLAG_CONTRACTS, CLOSE_MANY_FLAG_CONTRACTS, COMPLETION_FLAG_CONTRACTS, CONTRACTS_FLAG_CONTRACTS, CONTEXT_FLAG_CONTRACTS, COPY_FLAG_CONTRACTS, FOCUS_FLAG_CONTRACTS, MEET_FLAG_CONTRACTS, REMIND_FLAG_CONTRACTS, CREATE_FLAG_CONTRACTS, DEPS_FLAG_CONTRACTS, DUPLICATES_FLAG_CONTRACTS, EXTENSION_FLAG_CONTRACTS, GRAPH_FLAG_CONTRACTS, GET_FLAG_CONTRACTS, GUIDE_FLAG_CONTRACTS, GLOBAL_FLAG_CONTRACTS, HEALTH_FLAG_CONTRACTS, HISTORY_AUTHOR_ACKNOWLEDGE_FLAG_CONTRACTS, HISTORY_FLAG_CONTRACTS, INIT_FLAG_CONTRACTS, LIST_FILTER_FLAG_CONTRACTS, NEXT_FLAG_CONTRACTS, PM_COMMAND_ALIAS_CONTRACTS, PACKAGE_FLAG_CONTRACTS, PLAN_FLAG_CONTRACTS, SEARCH_FLAG_CONTRACTS, STATS_FLAG_CONTRACTS, EVENTS_FLAG_CONTRACTS, UPDATE_FLAG_CONTRACTS, UPDATE_MANY_FLAG_CONTRACTS, UPGRADE_FLAG_CONTRACTS, toCompletionFlagString, } from "./cli-contracts.js";
 import { BUILTIN_ITEM_TYPE_VALUES, STATUS_VALUES } from "../types/index.js";
 import { listGuideTopicIds } from "./guide-topics.js";
 const VALID_SHELLS = ["bash", "zsh", "fish"];
@@ -49,9 +49,11 @@ const PLAN_SUBCOMMANDS_LIST = "create show add-step update-step complete-step bl
 const COMPLETION_FLAGS = toCompletionFlagString(COMPLETION_FLAG_CONTRACTS);
 const COMPLETION_SHELL_CHOICES = `${COMPLETION_FLAGS} bash zsh fish`;
 const GUIDE_TOPIC_CHOICES = joinCompletionValues(listGuideTopicIds());
-const LIFECYCLE_ACTIONS = "init scaffold install uninstall explore manage describe reload doctor catalog adopt adopt-all activate deactivate";
+const EXTENSION_LIFECYCLE_ACTIONS = "init scaffold install uninstall explore manage describe reload doctor catalog adopt adopt-all activate deactivate migrate";
+const PACKAGE_LIFECYCLE_ACTIONS = `${EXTENSION_LIFECYCLE_ACTIONS} upgrade`;
 const EXTENSION_LIFECYCLE_FLAGS = toCompletionFlagString(EXTENSION_FLAG_CONTRACTS);
 const PACKAGE_LIFECYCLE_FLAGS = toCompletionFlagString(PACKAGE_FLAG_CONTRACTS);
+const UPGRADE_FLAGS = toCompletionFlagString(UPGRADE_FLAG_CONTRACTS);
 const MUTATION_FLAGS = "--author --message --force --json --quiet --no-changed-fields --id-only --pm-path --path --no-extensions --no-pager --profile --help";
 const DELETE_MUTATION_FLAGS = "--dry-run --author --message --force --json --quiet --no-changed-fields --id-only --pm-path --path --no-extensions --no-pager --profile --help";
 const CLOSE_MUTATION_FLAGS = "--author --message --validate-close --duplicate-of --force --json --quiet --no-changed-fields --id-only --pm-path --path --no-extensions --no-pager --profile --help";
@@ -59,7 +61,6 @@ const RELEASE_MUTATION_FLAGS = "--author --message --force --json --quiet --no-c
 const COMMAND_COMPLETION_DESCRIPTIONS = [
     ["init", "Initialize pm storage for the current workspace"],
     ["config", "Read or update pm settings"],
-    ["extension", "Manage extension lifecycle operations"],
     ["package", "Manage package lifecycle operations"],
     ["packages", "Alias for package"],
     ["create", "Create a new project management item"],
@@ -515,13 +516,13 @@ export function generateBashScript(itemTypes = [], tags = [], eagerTagExpansion
         "",
         ...(useEagerTagExpansion
             ? [
-                '  if [[ "$prev" == "--tag" || "$prev" == "--tags" ]]; then',
+                '  if [[ ( "$prev" == "--tag" || "$prev" == "--tags" ) && ! ( ( "${COMP_WORDS[1]}" == "package" || "${COMP_WORDS[1]}" == "packages" ) && "${COMP_WORDS[2]}" == "upgrade" ) ]]; then',
                 `    COMPREPLY=(${compgen(tagValues)})`,
                 "    return 0",
                 "  fi",
             ]
             : [
-                '  if [[ "$prev" == "--tag" || "$prev" == "--tags" ]]; then',
+                '  if [[ ( "$prev" == "--tag" || "$prev" == "--tags" ) && ! ( ( "${COMP_WORDS[1]}" == "package" || "${COMP_WORDS[1]}" == "packages" ) && "${COMP_WORDS[2]}" == "upgrade" ) ]]; then',
                 "    local now ttl cache_ts tag_values",
                 '    now="$(date +%s 2>/dev/null || echo 0)"',
                 '    ttl="${PM_COMPLETION_TAG_TTL:-120}"',
@@ -537,6 +538,11 @@ export function generateBashScript(itemTypes = [], tags = [], eagerTagExpansion
                 "  fi",
             ]),
         "",
+        '  if [[ "$prev" == "--tag" && ( ( "${COMP_WORDS[1]}" == "package" || "${COMP_WORDS[1]}" == "packages" ) && "${COMP_WORDS[2]}" == "upgrade" ) ]]; then',
+        "    COMPREPLY=()",
+        "    return 0",
+        "  fi",
+        "",
         '  local cmd="${COMP_WORDS[1]}"',
         "",
         '  case "$cmd" in',
@@ -589,19 +595,19 @@ export function generateBashScript(itemTypes = [], tags = [], eagerTagExpansion
         `      COMPREPLY=(${compgen("--criterion --clear-criteria --format --policy --json --quiet --no-changed-fields --pm-path --path --no-extensions --no-pager --profile --help")})`,
         "      ;;",
         "    extension)",
-        `      COMPREPLY=(${compgen(`${LIFECYCLE_ACTIONS} ${EXTENSION_LIFECYCLE_FLAGS}`)})`,
+        `      COMPREPLY=(${compgen(`${EXTENSION_LIFECYCLE_ACTIONS} ${EXTENSION_LIFECYCLE_FLAGS}`)})`,
         "      ;;",
         "    package|packages)",
-        `      COMPREPLY=(${compgen(`${LIFECYCLE_ACTIONS} ${PACKAGE_LIFECYCLE_FLAGS}`)})`,
+        `      COMPREPLY=(${compgen(`${PACKAGE_LIFECYCLE_ACTIONS} ${PACKAGE_LIFECYCLE_FLAGS} ${UPGRADE_FLAGS}`)})`,
         "      ;;",
         "    comments)",
-        `      COMPREPLY=(${compgen("--add --body --stdin --file --edit --delete --limit --full-history --author --message --force --json --quiet --no-changed-fields --pm-path --path --no-extensions --no-pager --profile --help")})`,
+        `      COMPREPLY=(${compgen("--add --body --stdin --file --edit --delete --limit --full-history --if-absent --author --message --force --json --quiet --no-changed-fields --pm-path --path --no-extensions --no-pager --profile --help")})`,
         "      ;;",
         "    notes)",
-        `      COMPREPLY=(${compgen("--add --add-json --stdin --file --edit --delete --limit --since --event-type --include-meta --full-history --author --message --force --json --quiet --no-changed-fields --pm-path --path --no-extensions --no-pager --profile --help")})`,
+        `      COMPREPLY=(${compgen("--add --add-json --stdin --file --edit --delete --limit --since --event-type --include-meta --full-history --if-absent --author --message --force --json --quiet --no-changed-fields --pm-path --path --no-extensions --no-pager --profile --help")})`,
         "      ;;",
         "    learnings)",
-        `      COMPREPLY=(${compgen("--add --stdin --file --edit --delete --limit --full-history --author --message --force --json --quiet --no-changed-fields --pm-path --path --no-extensions --no-pager --profile --help")})`,
+        `      COMPREPLY=(${compgen("--add --stdin --file --edit --delete --limit --full-history --if-absent --author --message --force --json --quiet --no-changed-fields --pm-path --path --no-extensions --no-pager --profile --help")})`,
         "      ;;",
         "    files)",
         `      COMPREPLY=(${compgen("discover lookup --add --add-glob --remove --migrate --list --apply --note --append-stable --validate-paths --scope --limit --offset --no-truncate --strict-read --explain --lines --decision-depth --author --message --force --json --quiet --no-changed-fields --pm-path --path --no-extensions --no-pager --profile --help")})`,
@@ -706,6 +712,9 @@ export function generateBashScript(itemTypes = [], tags = [], eagerTagExpansion
         `      COMPREPLY=(${compgen(GLOBAL_FLAGS)})`,
         "      ;;",
         "  esac",
+        '  if [[ "$cmd" == "comments" || "$cmd" == "notes" || "$cmd" == "learnings" ]]; then',
+        `    COMPREPLY+=(${compgen("--text")})`,
+        "  fi",
         "  return 0",
         "}",
         "",
@@ -778,6 +787,7 @@ _pm() {
   local context state line
   _arguments -C \\
     '--json[Output JSON instead of TOON]' \\
+    '--all[Reveal every public command and compatibility alias]' \\
     '--quiet[Suppress stdout output]' \\
     '--output-include[Retain comma-separated read fields or sections]:selectors' \\
     '--output-limit[Set the universal read row ceiling]:limit' \\
@@ -1353,12 +1363,14 @@ ${zshSearchRuntimeFieldFlags}            '--json[Output JSON]' \\
         comments)
           _arguments \\
             '--add[Add one entry (plain text, text=<value>, markdown pairs, or - for stdin)]:text' \\
+            '--text[Alias for --add]:text' \\
             '--stdin[Read comment text from stdin (supports multiline markdown)]' \\
             '--file[Read comment text from file (supports multiline markdown)]:path' \\
             '--edit[Replace the comment at 1-based index (text from positional/--add/--stdin/--file)]:index' \\
             '--delete[Delete the comment at 1-based index]:index' \\
             '--limit[Return only latest n entries]:number' \\
             '--full-history[Return complete post-mutation history]' \\
+            '--if-absent[Append only when the resolved author and text are absent]' \\
             '--author[Entry author (falls back to PM_AUTHOR/settings)]:author' \\
             '--message[History message]:message' \\
             '--force[Force override]' \\
@@ -1368,6 +1380,7 @@ ${zshSearchRuntimeFieldFlags}            '--json[Output JSON]' \\
         notes)
           _arguments \\
             '--add[Add one entry (plain text, text=<value>, markdown pairs, or - for stdin)]:text' \\
+            '--text[Alias for --add]:text' \\
             '--add-json[Append one validated JSON context event]:json' \\
             '--stdin[Read entry text from stdin]' \\
             '--file[Read entry text from file]:path' \\
@@ -1378,6 +1391,7 @@ ${zshSearchRuntimeFieldFlags}            '--json[Output JSON]' \\
             '--event-type[Return structured events with this top-level type]:event_type' \\
             '--include-meta[Include result counts and truncation metadata]' \\
             '--full-history[Return complete post-mutation history]' \\
+            '--if-absent[Append only when the resolved author and text are absent]' \\
             '--author[Entry author (falls back to PM_AUTHOR/settings)]:author' \\
             '--message[History message]:message' \\
             '--force[Force override]' \\
@@ -1387,12 +1401,14 @@ ${zshSearchRuntimeFieldFlags}            '--json[Output JSON]' \\
         learnings)
           _arguments \\
             '--add[Add one entry (plain text, text=<value>, markdown pairs, or - for stdin)]:text' \\
+            '--text[Alias for --add]:text' \\
             '--stdin[Read entry text from stdin]' \\
             '--file[Read entry text from file]:path' \\
             '--edit[Replace the entry at a 1-based index]:index' \\
             '--delete[Delete the entry at a 1-based index]:index' \\
             '--limit[Return only latest n entries]:number' \\
             '--full-history[Return complete post-mutation history]' \\
+            '--if-absent[Append only when the resolved author and text are absent]' \\
             '--author[Entry author (falls back to PM_AUTHOR/settings)]:author' \\
             '--message[History message]:message' \\
             '--force[Force override]' \\
@@ -1665,7 +1681,7 @@ ${zshSearchRuntimeFieldFlags}            '--json[Output JSON]' \\
           ;;
         extension)
           _arguments \\
-            '1:extension_action:(init scaffold install uninstall explore manage describe reload doctor catalog adopt adopt-all activate deactivate)' \\
+            '1:extension_action:(${EXTENSION_LIFECYCLE_ACTIONS})' \\
             '--init[Generate a starter extension scaffold at target path]' \\
             '--scaffold[Alias for --init]' \\
             '--capability[Capability the init scaffold targets]:capability:(${SCAFFOLD_CAPABILITIES.join(" ")})' \\
@@ -1704,7 +1720,7 @@ ${zshSearchRuntimeFieldFlags}            '--json[Output JSON]' \\
           ;;
         package|packages)
           _arguments \\
-            '1:package_action:(init scaffold install uninstall explore manage describe reload doctor catalog adopt adopt-all activate deactivate)' \\
+            '1:package_action:(${PACKAGE_LIFECYCLE_ACTIONS})' \\
             '--init[Generate a starter package scaffold at target path]' \\
             '--scaffold[Alias for --init]' \\
             '--capability[Capability the init scaffold targets]:capability:(${SCAFFOLD_CAPABILITIES.join(" ")})' \\
@@ -1738,6 +1754,12 @@ ${zshSearchRuntimeFieldFlags}            '--json[Output JSON]' \\
             '--ignore-global[Alias for --isolated]' \\
             '--strict-exit[Return non-zero exit when doctor warnings are present]' \\
             '--fail-on-warn[Alias for --strict-exit (doctor)]' \\
+            '--dry-run[Plan upgrades without mutating]' \\
+            '--cli-only[Upgrade only the pm CLI/SDK npm package]' \\
+            '--packages-only[Upgrade only managed pm packages]' \\
+            '--repair[Force npm global reinstall for the CLI/SDK]' \\
+            '--tag[npm version or dist-tag for upgrades]:tag' \\
+            '--package-name[Override the CLI package name]:package_name' \\
             '--json[Output JSON]' \\
             '--quiet[Suppress stdout]' \\
             '*:target_or_name:_files -/'
@@ -1818,6 +1840,7 @@ complete -c pm -f
 
 # Global flags (available for all subcommands)
 complete -c pm -l json -d 'Output JSON instead of TOON'
+complete -c pm -l all -d 'Reveal every public command and compatibility alias'
 complete -c pm -l quiet -d 'Suppress stdout output'
 complete -c pm -l output-include -d 'Retain comma-separated read fields or sections' -r
 complete -c pm -l output-limit -d 'Set the universal read row ceiling' -r
@@ -2423,6 +2446,7 @@ complete -c pm -n '__fish_seen_subcommand_from graph' -l summary -d 'Return coun
 
 # comments / notes / learnings flags
 complete -c pm -n '__fish_seen_subcommand_from comments notes learnings' -l add -d 'Add one entry (text=<value> or plain text)' -r
+complete -c pm -n '__fish_seen_subcommand_from comments notes learnings' -l text -d 'Alias for --add' -r
 complete -c pm -n '__fish_seen_subcommand_from notes' -l add-json -d 'Append one validated JSON context event' -r
 complete -c pm -n '__fish_seen_subcommand_from notes' -l since -d 'Return structured events at or after an ISO timestamp' -r
 complete -c pm -n '__fish_seen_subcommand_from notes' -l event-type -d 'Return structured events with this top-level type' -r
@@ -2431,6 +2455,7 @@ complete -c pm -n '__fish_seen_subcommand_from comments' -l stdin -d 'Read comme
 complete -c pm -n '__fish_seen_subcommand_from comments' -l file -d 'Read comment text from file (supports multiline markdown)' -r
 complete -c pm -n '__fish_seen_subcommand_from comments' -l edit -d 'Replace the comment at 1-based index (text from positional/--add/--stdin/--file)' -r
 complete -c pm -n '__fish_seen_subcommand_from comments' -l delete -d 'Delete the comment at 1-based index' -r
+complete -c pm -n '__fish_seen_subcommand_from comments notes learnings' -l if-absent -d 'Append only when the resolved author and text are absent'
 complete -c pm -n '__fish_seen_subcommand_from notes' -l stdin -d 'Read entry text from stdin'
 complete -c pm -n '__fish_seen_subcommand_from notes' -l file -d 'Read entry text from file' -r
 complete -c pm -n '__fish_seen_subcommand_from notes' -l edit -d 'Replace the entry at a 1-based index' -r
@@ -2666,7 +2691,7 @@ complete -c pm -n '__fish_seen_subcommand_from completion' -a 'bash zsh fish' -d
 complete -c pm -n '__fish_seen_subcommand_from templates' -a 'save list show' -d 'Templates command'
 
 # extension lifecycle flags
-complete -c pm -n '__fish_seen_subcommand_from extension' -a '${LIFECYCLE_ACTIONS}' -d 'Extension action subcommand'
+complete -c pm -n '__fish_seen_subcommand_from extension' -a '${EXTENSION_LIFECYCLE_ACTIONS}' -d 'Extension action subcommand'
 complete -c pm -n '__fish_seen_subcommand_from extension' -l init -d 'Generate starter extension scaffold'
 complete -c pm -n '__fish_seen_subcommand_from extension' -l scaffold -d 'Alias for --init'
 complete -c pm -n '__fish_seen_subcommand_from extension' -l capability -d 'Capability the init scaffold targets' -r -a '${SCAFFOLD_CAPABILITIES.join(" ")}'
@@ -2702,7 +2727,7 @@ complete -c pm -n '__fish_seen_subcommand_from extension' -l fail-on-warn -d 'Al
 
 # package lifecycle flags
 for package_cmd in package packages
-  complete -c pm -n "__fish_seen_subcommand_from $package_cmd" -a '${LIFECYCLE_ACTIONS}' -d 'Package action subcommand'
+  complete -c pm -n "__fish_seen_subcommand_from $package_cmd" -a '${PACKAGE_LIFECYCLE_ACTIONS}' -d 'Package action subcommand'
   complete -c pm -n "__fish_seen_subcommand_from $package_cmd" -l init -d 'Generate starter package scaffold'
   complete -c pm -n "__fish_seen_subcommand_from $package_cmd" -l scaffold -d 'Alias for --init'
   complete -c pm -n "__fish_seen_subcommand_from $package_cmd" -l capability -d 'Capability the init scaffold targets' -r -a '${SCAFFOLD_CAPABILITIES.join(" ")}'
@@ -2736,6 +2761,12 @@ for package_cmd in package packages
   complete -c pm -n "__fish_seen_subcommand_from $package_cmd" -l ignore-global -d 'Alias for --isolated'
   complete -c pm -n "__fish_seen_subcommand_from $package_cmd" -l strict-exit -d 'Return non-zero exit when doctor warnings are present'
   complete -c pm -n "__fish_seen_subcommand_from $package_cmd" -l fail-on-warn -d 'Alias for --strict-exit (doctor)'
+  complete -c pm -n "__fish_seen_subcommand_from $package_cmd" -l dry-run -d 'Plan upgrades without mutating'
+  complete -c pm -n "__fish_seen_subcommand_from $package_cmd" -l cli-only -d 'Upgrade only the pm CLI/SDK npm package'
+  complete -c pm -n "__fish_seen_subcommand_from $package_cmd" -l packages-only -d 'Upgrade only managed pm packages'
+  complete -c pm -n "__fish_seen_subcommand_from $package_cmd" -l repair -d 'Force npm global reinstall for the CLI/SDK'
+  complete -c pm -n "__fish_seen_subcommand_from $package_cmd" -l tag -d 'npm version or dist-tag for upgrades' -r
+  complete -c pm -n "__fish_seen_subcommand_from $package_cmd" -l package-name -d 'Override the CLI package name' -r
 end`;
 }
 const SETUP_HINTS = {
@@ -2767,4 +2798,4 @@ export function runCompletion(shell, itemTypes = [], tags = [], eagerTagExpansio
     };
 }
 //# sourceMappingURL=completion.js.map
-//# debugId=48da3e98-ab96-54de-8993-7de0c4edf19b
+//# debugId=4bf2b42b-91f3-5850-b1f1-d8a01525860c

package/dist/sdk/contracts.d.ts

@@ -13,6 +13,7 @@ export * from "./flag-invocation-contracts.js";
 export * from "./cli-contracts/flag-lexicon-contracts.js";
 export * from "./output-token-accounting.js";
 export * from "./output-contracts.js";
+export * from "./agent/task-transcript-contracts.js";
 export * from "./read-output-contracts.js";
 export * from "./agent/refusal-closure.js";
 export * from "./agent/closed-domain-contracts.js";

package/dist/sdk/contracts.js

@@ -4,7 +4,7 @@
  * Exposes command and action contract data without loading SDK runtime code.
  */
 
-!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]="8bdc03e5-c5cd-5842-b438-cf7bc79863f0")}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]="b47a3cc6-caba-5de8-8813-a4e6112dbe61")}catch(e){}}();
 export * from "./cli-contracts.js";
 export * from "./cli-contracts/grammar-contracts.js";
 export * from "./cli-contracts/command-exit-contracts.js";
@@ -15,9 +15,10 @@ export * from "./flag-invocation-contracts.js";
 export * from "./cli-contracts/flag-lexicon-contracts.js";
 export * from "./output-token-accounting.js";
 export * from "./output-contracts.js";
+export * from "./agent/task-transcript-contracts.js";
 export * from "./read-output-contracts.js";
 export * from "./agent/refusal-closure.js";
 export * from "./agent/closed-domain-contracts.js";
 export * from "./agent/tracker-preflight-contracts.js";
 //# sourceMappingURL=contracts.js.map
-//# debugId=8bdc03e5-c5cd-5842-b438-cf7bc79863f0
+//# debugId=b47a3cc6-caba-5de8-8813-a4e6112dbe61

package/dist/sdk/extension/install-sources.d.ts

@@ -107,6 +107,12 @@ export declare function wrapNpmPackResolutionError(spec: string, error: unknown)
 declare function resolveNpmPackSpec(spec: string): Promise<string>;
 /** Implements normalize npm local file alias spec for the public runtime surface of this module. */
 export declare function normalizeNpmLocalFileAliasSpec(spec: string, cwd?: string): string;
+/**
+ * Parse npm pack output and bind the reported artifact to its isolated target.
+ *
+ * Supports current JSON metadata and the legacy filename-only form while
+ * refusing absolute or traversing results before the filesystem is consulted.
+ */
 declare function parsePackedNpmPackage(stdout: string, packDirectory: string): {
     tarball: string;
     package?: string;
@@ -118,6 +124,13 @@ declare function resolveNpmSourceDirectory(source: NpmInstallSource): Promise<{
     version?: string;
     cleanup: () => Promise<void>;
 }>;
+/**
+ * Resolve an npm source with an injectable, argv-safe package-manager runner.
+ *
+ * Local package directories remain in place, while local and registry archives
+ * share the same bounded validation, dependency installation, and cleanup
+ * contract. Registry artifacts must also exist inside the requested pack root.
+ */
 declare function resolveNpmSourceDirectoryWithRunner(source: NpmInstallSource, npmRunner: typeof runNpmCommand): Promise<{
     directory: string;
     package?: string;

package/dist/sdk/extension/install-sources.js

@@ -4,7 +4,7 @@
  * Implements extension package-management support for Install Sources.
  */
 
-!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]="89b84412-aa15-5868-95b3-c8d898b1f480")}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]="404342eb-68ab-5b7d-9a5a-ade1c8e98546")}catch(e){}}();
 import { execFile } from "node:child_process";
 import fs from "node:fs/promises";
 import os from "node:os";
@@ -397,38 +397,63 @@ export function normalizeNpmLocalFileAliasSpec(spec, cwd = process.cwd()) {
         : decodedPath;
     return `${packageName}@${nativePath}`;
 }
+/**
+ * Parse npm pack output and bind the reported artifact to its isolated target.
+ *
+ * Supports current JSON metadata and the legacy filename-only form while
+ * refusing absolute or traversing results before the filesystem is consulted.
+ */
 function parsePackedNpmPackage(stdout, packDirectory) {
+    let parsed;
     try {
-        const parsed = JSON.parse(stdout);
-        const first = Array.isArray(parsed) ? parsed[0] : undefined;
-        if (first &&
-            typeof first.filename === "string" &&
-            first.filename.trim().length > 0) {
-            return {
-                tarball: path.resolve(packDirectory, first.filename),
-                package: typeof first.name === "string" ? first.name : undefined,
-                version: typeof first.version === "string" ? first.version : undefined,
-            };
-        }
+        parsed = JSON.parse(stdout);
     }
     catch {
         // Fall back to the last stdout line for older npm output.
     }
-    const lastLine = stdout
-        .split(/\r?\n/)
-        .map((line) => line.trim())
-        .filter((line) => line.length > 0)
-        .at(-1);
-    if (!lastLine) {
+    const first = Array.isArray(parsed)
+        ? parsed[0]
+        : undefined;
+    const filename = first &&
+        typeof first.filename === "string" &&
+        first.filename.trim().length > 0
+        ? first.filename
+        : stdout
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0)
+            .at(-1);
+    if (!filename) {
         throw new PmCliError("npm pack did not report a tarball filename.", EXIT_CODE.GENERIC_FAILURE);
     }
+    const tarball = path.resolve(packDirectory, filename);
+    const relativeTarball = path.relative(packDirectory, tarball);
+    if (relativeTarball.length === 0 ||
+        relativeTarball === ".." ||
+        relativeTarball.startsWith(`..${path.sep}`) ||
+        path.isAbsolute(relativeTarball)) {
+        throw new PmCliError("npm pack reported a package archive outside its isolated destination.", EXIT_CODE.GENERIC_FAILURE, {
+            code: "npm_package_archive_unsafe",
+            required: "Retry with a trusted npm client that writes its archive inside the requested pack destination.",
+            why: "pm will not read a package-manager artifact outside the isolated directory created for this install.",
+        });
+    }
     return {
-        tarball: path.resolve(packDirectory, lastLine),
+        tarball,
+        package: typeof first?.name === "string" ? first.name : undefined,
+        version: typeof first?.version === "string" ? first.version : undefined,
     };
 }
 async function resolveNpmSourceDirectory(source) {
     return resolveNpmSourceDirectoryWithRunner(source, runNpmCommand);
 }
+/**
+ * Resolve an npm source with an injectable, argv-safe package-manager runner.
+ *
+ * Local package directories remain in place, while local and registry archives
+ * share the same bounded validation, dependency installation, and cleanup
+ * contract. Registry artifacts must also exist inside the requested pack root.
+ */
 async function resolveNpmSourceDirectoryWithRunner(source, npmRunner) {
     const localPackageRoot = await resolveLocalNpmPackagePath(source.spec);
     if (localPackageRoot) {
@@ -451,9 +476,7 @@ async function resolveNpmSourceDirectoryWithRunner(source, npmRunner) {
     }
     const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "pm-npm-package-source-"));
     const packDirectory = path.join(tempRoot, "pack");
-    const extractDirectory = path.join(tempRoot, "extract");
     await fs.mkdir(packDirectory, { recursive: true });
-    await fs.mkdir(extractDirectory, { recursive: true });
     try {
         const packSpec = await resolveNpmPackSpec(source.spec);
         const packStdout = await npmRunner([
@@ -464,16 +487,25 @@ async function resolveNpmSourceDirectoryWithRunner(source, npmRunner) {
             packDirectory,
         ]);
         const packed = parsePackedNpmPackage(packStdout, packDirectory);
-        await execFileAsync("tar", ["-xzf", packed.tarball, "-C", extractDirectory], { encoding: "utf8" });
-        const packageRoot = path.join(extractDirectory, "package");
-        await installNpmPackageRuntimeDependencies(packageRoot);
-        const directory = await resolvePackageExtensionDirectory(packageRoot, source.input);
+        if (!(await pathExists(packed.tarball))) {
+            throw new PmCliError("npm pack did not create its reported package archive.", EXIT_CODE.GENERIC_FAILURE, {
+                code: "npm_package_archive_missing",
+                required: "Retry the npm package install with a healthy registry and writable temporary directory.",
+                why: "The package manager reported a tarball filename that was absent before validation, so pm cannot safely extract or install it.",
+            });
+        }
+        const extracted = await extractLocalPackageArchive(packed.tarball);
         return {
-            directory,
-            package: packed.package,
-            version: packed.version,
+            directory: extracted.directory,
+            package: packed.package ?? extracted.package,
+            version: packed.version ?? extracted.version,
             cleanup: async () => {
-                await fs.rm(tempRoot, { recursive: true, force: true });
+                try {
+                    await extracted.cleanup();
+                }
+                finally {
+                    await fs.rm(tempRoot, { recursive: true, force: true });
+                }
             },
         };
     }
@@ -962,4 +994,4 @@ export const _testOnlyInstallSources = {
     runNpmCommand,
 };
 //# sourceMappingURL=install-sources.js.map
-//# debugId=89b84412-aa15-5868-95b3-c8d898b1f480
+//# debugId=404342eb-68ab-5b7d-9a5a-ade1c8e98546

package/dist/sdk/generated/generated-error-code-catalog-part-1.js

@@ -1,6 +1,6 @@
 /** Generated partition 1 of the exhaustive error-code catalog. */
 
-!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]="c51fce27-5acd-513d-83c4-5fd75bd999f9")}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]="95253070-db43-5ddd-8468-7d001bc6657b")}catch(e){}}();
 export const PM_ERROR_CODE_CATALOG_PART_1 = [
     {
         code: "acceptance_criteria_mutation_conflict",
@@ -122,6 +122,18 @@ export const PM_ERROR_CODE_CATALOG_PART_1 = [
         canonical_code: "annotation_flag_like_value",
         aliases: [],
     },
+    {
+        code: "annotation_if_absent_without_append",
+        meaning: "Annotation if absent without append condition.",
+        stability: "provisional",
+        exit_code: 2,
+        class: "usage",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/annotations.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "annotation_if_absent_without_append",
+        aliases: [],
+    },
     {
         code: "annotation_message_without_text",
         meaning: "Annotation message without text condition.",
@@ -2088,6 +2100,18 @@ export const PM_ERROR_CODE_CATALOG_PART_1 = [
         canonical_code: "merge_root_not_found",
         aliases: [],
     },
+    {
+        code: "missing_allowed_values",
+        meaning: "Missing allowed values condition.",
+        stability: "provisional",
+        exit_code: 1,
+        class: "generic_failure",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/agent/refusal-closure.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "missing_allowed_values",
+        aliases: [],
+    },
 ];
 //# sourceMappingURL=generated-error-code-catalog-part-1.js.map
-//# debugId=c51fce27-5acd-513d-83c4-5fd75bd999f9
+//# debugId=95253070-db43-5ddd-8468-7d001bc6657b