@unbrained/pm-cli 2026.8.27 → 2026.8.28

package/dist/sdk/cli-contracts/bootstrap-command-scanner.js

@@ -0,0 +1,80 @@
+/**
+ * @module sdk/cli-contracts/bootstrap-command-scanner
+ *
+ * Resolves command position from shell-free argv without loading CLI runtime
+ * normalization, error, filesystem, or item-addressing dependencies.
+ */
+/** Global options that consume a following value when one is present. */
+
+!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]="9d04e30a-caf5-59b4-8853-9df39c1728aa")}catch(e){}}();
+export const GLOBAL_VALUE_CONSUMING_FLAGS = new Set([
+    "--pm-path",
+    "--path",
+    "--author",
+    "--output-include",
+    "--output-limit",
+    "--output-budget",
+    "--output-format",
+    "--output-session",
+    "--output-cursor",
+]);
+/** Boolean global options ignored while locating the command token. */
+export const BOOTSTRAP_BOOLEAN_FLAGS = new Set([
+    "--no-extensions",
+    "--no-pager",
+    "--json",
+    "--quiet",
+    "--lean",
+    "--token-accounting",
+    "--output-row-contract",
+    "--all",
+]);
+/** Whether a global value-consuming flag uses its inline `--flag=value` form. */
+export function isInlineGlobalValueToken(token) {
+    const equalsIndex = token.indexOf("=");
+    return (equalsIndex > 0 &&
+        GLOBAL_VALUE_CONSUMING_FLAGS.has(token.slice(0, equalsIndex)));
+}
+/** Whether a bootstrap value flag consumes its following token. */
+export function consumesBootstrapValue(flag, next) {
+    if (typeof next !== "string")
+        return false;
+    return flag === "--path" || flag === "--pm-path" || !next.startsWith("-");
+}
+/**
+ * Locate the first command token after global flags and their values.
+ *
+ * A leading `--` terminates command discovery. Unknown flags are ignored so
+ * later command-specific validation can return the canonical diagnostic.
+ */
+export function findBootstrapCommandTokenIndex(argv) {
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (token === "--") {
+            return undefined;
+        }
+        if (GLOBAL_VALUE_CONSUMING_FLAGS.has(token)) {
+            index += consumesBootstrapValue(token, argv[index + 1]) ? 1 : 0;
+            continue;
+        }
+        if (isInlineGlobalValueToken(token) ||
+            BOOTSTRAP_BOOLEAN_FLAGS.has(token) ||
+            token === "--profile" ||
+            token === "--id-only" ||
+            token === "--explain") {
+            continue;
+        }
+        if (token.startsWith("-")) {
+            continue;
+        }
+        return index;
+    }
+    return undefined;
+}
+/** Resolve the normalized command name from shell-free invocation arguments. */
+export function parseBootstrapCommandName(argv) {
+    const index = findBootstrapCommandTokenIndex(argv);
+    return index === undefined ? undefined : argv[index].trim().toLowerCase();
+}
+//# sourceMappingURL=bootstrap-command-scanner.js.map
+//# debugId=9d04e30a-caf5-59b4-8853-9df39c1728aa

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]="76fe6260-2386-52c5-8f94-aad48dec33f9")}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]="bd6c497f-9fb0-5c47-a677-9dd6636dba02")}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";
@@ -226,6 +226,7 @@ export const COMMENTS_FLAG_CONTRACTS = [
     { flag: "--delete" },
     { flag: "--limit" },
     { flag: "--full-history" },
+    { flag: "--if-absent", value_type: "boolean" },
     { flag: "--author" },
     { flag: "--message" },
     { flag: "--force" },
@@ -249,6 +250,7 @@ export const NOTES_FLAG_CONTRACTS = [
     { flag: "--event-type" },
     { flag: "--include-meta" },
     { flag: "--full-history" },
+    { flag: "--if-absent", value_type: "boolean" },
     { flag: "--author" },
     { flag: "--message" },
     { flag: "--force" },
@@ -259,6 +261,7 @@ export const LEARNINGS_FLAG_CONTRACTS = [
     { flag: "--add", aliases: ["--learning", "--text"] },
     { flag: "--limit" },
     { flag: "--full-history" },
+    { flag: "--if-absent", value_type: "boolean" },
     { flag: "--author" },
     { flag: "--message" },
     { flag: "--force" },
@@ -1912,4 +1915,4 @@ export function toCompletionFlagString(flagContracts, includeGlobal = true) {
     return normalizeUniqueStringList(all).join(" ");
 }
 //# sourceMappingURL=flag-contracts.js.map
-//# debugId=76fe6260-2386-52c5-8f94-aad48dec33f9
+//# debugId=bd6c497f-9fb0-5c47-a677-9dd6636dba02

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

@@ -5,7 +5,7 @@
  * per-command growth budgets.
  */
 
-!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]="8320177c-e95d-5d14-a914-4ac37230c0b9")}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]="3466866d-8869-5ab6-b981-d084e7330aa5")}catch(e){}}();
 import { hasSubcommandFlagContractsForCommand, resolveSubcommandFlagContractsForCommand, } from "./flag-contracts.js";
 import { PM_COMMAND_CAPABILITY_CONTRACTS, } from "../agent-capability-contracts.js";
 import { enrichCliFlagInvocationContracts } from "../flag-invocation-contracts.js";
@@ -146,9 +146,9 @@ const PM_COMMAND_FLAG_BUDGET_MAXIMUMS = Object.freeze({
     "close-many": 72,
     delete: 24,
     append: 24,
-    comments: 30,
-    notes: 34,
-    learnings: 26,
+    comments: 31,
+    notes: 35,
+    learnings: 27,
     files: 39,
     docs: 30,
     deps: 32,
@@ -337,4 +337,4 @@ export function renderPmFlagLexiconMarkdown() {
     ].join("\n");
 }
 //# sourceMappingURL=flag-lexicon-contracts.js.map
-//# debugId=8320177c-e95d-5d14-a914-4ac37230c0b9
+//# debugId=3466866d-8869-5ab6-b981-d084e7330aa5

package/dist/sdk/cli-contracts/tool-parameter-tables.js

@@ -4,7 +4,7 @@
  * Defines SDK command-contract metadata for Tool Parameter Tables.
  */
 
-!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]="2d43e788-cb8d-59b8-a447-4d24033bb55b")}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]="6968f481-8384-5e3b-8ac0-b0972d08eeb1")}catch(e){}}();
 import { PLAN_HARNESS_VALUES, PLAN_MODE_VALUES, PLAN_STEP_LINK_KIND_VALUES, PLAN_STEP_STATUS_VALUES, } from "../../types/index.js";
 import { PM_READ_OUTPUT_SESSION_MAX_SEEN_ITEM_IDS } from "../read-output-session.js";
 import { ASSURANCE_DEFINITION_SCHEMA } from "./schemas/assurance-definition.js";
@@ -499,6 +499,7 @@ export const PM_TOOL_PARAMETER_PROPERTIES = {
     noCheckpoint: { type: "boolean" },
     force: { type: "boolean" },
     ifAvailable: { type: "boolean" },
+    ifAbsent: { type: "boolean" },
     next: { type: "boolean" },
     maxAttempts: {
         anyOf: [
@@ -1266,6 +1267,9 @@ export const PM_TOOL_PARAMETER_METADATA = {
     message: {
         description: "History message for mutation audit trail.",
     },
+    ifAbsent: {
+        description: "For annotations, append only when no existing entry has the same resolved author and exact stored text; retries return changed false without a history event.",
+    },
     assignee: {
         description: "Assignee identity.",
     },
@@ -2029,11 +2033,17 @@ export const PM_TOOL_ACTION_SCOPED_PARAMETER_METADATA = {
         full: {
             description: "Return the complete post-mutation comment history instead of the bounded mutation receipt projection.",
         },
+        ifAbsent: {
+            description: "Append a comment only when the resolved author and exact stored text are absent; a duplicate retry returns changed false without writing history.",
+        },
     },
     notes: {
         full: {
             description: "Return the complete post-mutation note history instead of the bounded mutation receipt projection.",
         },
+        ifAbsent: {
+            description: "Append a note only when the resolved author and exact stored text are absent; a duplicate retry returns changed false without writing history.",
+        },
         since: {
             description: "Inclusive ISO 8601 creation timestamp lower bound for structured note event filtering.",
             examples: ["2026-01-01T00:00:00.000Z"],
@@ -2043,6 +2053,9 @@ export const PM_TOOL_ACTION_SCOPED_PARAMETER_METADATA = {
         full: {
             description: "Return the complete post-mutation learning history instead of the bounded mutation receipt projection.",
         },
+        ifAbsent: {
+            description: "Append a learning only when the resolved author and exact stored text are absent; a duplicate retry returns changed false without writing history.",
+        },
     },
     next: {
         tag: {
@@ -2128,4 +2141,4 @@ export const PM_TOOL_ACTION_SCOPED_PARAMETER_METADATA = {
     },
 };
 //# sourceMappingURL=tool-parameter-tables.js.map
-//# debugId=2d43e788-cb8d-59b8-a447-4d24033bb55b
+//# debugId=6968f481-8384-5e3b-8ac0-b0972d08eeb1

package/dist/sdk/cli-contracts/tool-schema.d.ts

@@ -91,7 +91,7 @@ export interface PmActionToolInputSchemaOptions {
  */
 export declare function buildPmActionToolInputSchema(action: PmToolAction, options?: PmActionToolInputSchemaOptions): Record<string, unknown>;
 /** Canonical version of the action-scoped strict MCP tool-parameters schema (`PM_TOOL_PARAMETERS_SCHEMA`). Exported as the single source of truth so the MCP server, the `pm contracts` command, SDK consumers, and contract tests bind to one version constant. Bump the patch/minor for additive, backward-compatible schema changes; bump the MAJOR for breaking changes — the major also drives the `$id` `tool-parameters-v{major}` slug, so the two never drift. */
-export declare const PM_TOOL_PARAMETERS_SCHEMA_VERSION: "4.9.0";
+export declare const PM_TOOL_PARAMETERS_SCHEMA_VERSION: "4.10.1";
 /**
  * Major component of {@link PM_TOOL_PARAMETERS_SCHEMA_VERSION}, used to build the
  * schema `$id` slug so a breaking version bump renames the document in lockstep.

package/dist/sdk/cli-contracts/tool-schema.js

@@ -7,7 +7,7 @@
  * consumers from a single source of truth.
  */
 
-!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]="0b302ca6-1333-532f-a55e-e8e984636456")}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]="91de08b8-ad0b-5c61-a272-3c18cd3f083b")}catch(e){}}();
 import { normalizeUniqueStringList } from "./string-lists.js";
 import { PM_TOOL_ACTIONS } from "./enum-contracts.js";
 import { TOOL_CREATE_OPTION_CONTRACTS, TOOL_SHARED_CREATE_UPDATE_OPTION_CONTRACTS, TOOL_UPDATE_OPTION_CONTRACTS, TOOL_UPDATE_MANY_FILTER_OPTION_CONTRACTS, TOOL_CONTEXT_OPTION_CONTRACTS, TOOL_ACTIVITY_OPTION_CONTRACTS, TOOL_LIST_FILTER_OPTION_CONTRACTS, TOOL_AGGREGATE_OPTION_CONTRACTS, TOOL_SEARCH_FILTER_OPTION_CONTRACTS, TOOL_CLOSE_MANY_FILTER_OPTION_CONTRACTS, } from "./tool-option-contracts.js";
@@ -850,8 +850,13 @@ const PM_TOOL_ACTION_SCHEMA_CONTRACTS = {
             "delete",
             "limit",
             "full",
+            "ifAbsent",
             ...AUTHOR_MESSAGE_FORCE_PARAMETER_KEYS,
         ],
+        mutuallyExclusive: [
+            ["edit", "ifAbsent"],
+            ["delete", "ifAbsent"],
+        ],
     },
     notes: {
         required: ["id"],
@@ -867,6 +872,7 @@ const PM_TOOL_ACTION_SCHEMA_CONTRACTS = {
             "eventType",
             "includeMeta",
             "full",
+            "ifAbsent",
             ...AUTHOR_MESSAGE_FORCE_PARAMETER_KEYS,
         ],
         mutuallyExclusive: [
@@ -875,6 +881,8 @@ const PM_TOOL_ACTION_SCHEMA_CONTRACTS = {
             ["addJson", "file"],
             ["addJson", "edit"],
             ["addJson", "delete"],
+            ["edit", "ifAbsent"],
+            ["delete", "ifAbsent"],
         ],
     },
     learnings: {
@@ -887,8 +895,13 @@ const PM_TOOL_ACTION_SCHEMA_CONTRACTS = {
             "delete",
             "limit",
             "full",
+            "ifAbsent",
             ...AUTHOR_MESSAGE_FORCE_PARAMETER_KEYS,
         ],
+        mutuallyExclusive: [
+            ["edit", "ifAbsent"],
+            ["delete", "ifAbsent"],
+        ],
     },
     files: {
         required: [],
@@ -1534,7 +1547,7 @@ function createLazyContractSchema(build) {
     });
 }
 /** Canonical version of the action-scoped strict MCP tool-parameters schema (`PM_TOOL_PARAMETERS_SCHEMA`). Exported as the single source of truth so the MCP server, the `pm contracts` command, SDK consumers, and contract tests bind to one version constant. Bump the patch/minor for additive, backward-compatible schema changes; bump the MAJOR for breaking changes — the major also drives the `$id` `tool-parameters-v{major}` slug, so the two never drift. */
-export const PM_TOOL_PARAMETERS_SCHEMA_VERSION = "4.9.0";
+export const PM_TOOL_PARAMETERS_SCHEMA_VERSION = "4.10.1";
 /**
  * Major component of {@link PM_TOOL_PARAMETERS_SCHEMA_VERSION}, used to build the
  * schema `$id` slug so a breaking version bump renames the document in lockstep.
@@ -1616,4 +1629,4 @@ export const _testOnlyCliContracts = {
     withFlagAliasMetadata,
 };
 //# sourceMappingURL=tool-schema.js.map
-//# debugId=0b302ca6-1333-532f-a55e-e8e984636456
+//# debugId=91de08b8-ad0b-5c61-a272-3c18cd3f083b

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,7 +4,7 @@
  * 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]="c8446891-4e65-54c3-9826-eb40f4922f3b")}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";
@@ -601,13 +601,13 @@ export function generateBashScript(itemTypes = [], tags = [], eagerTagExpansion
         `      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")})`,
@@ -1370,6 +1370,7 @@ ${zshSearchRuntimeFieldFlags}            '--json[Output JSON]' \\
             '--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]' \\
@@ -1390,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]' \\
@@ -1406,6 +1408,7 @@ ${zshSearchRuntimeFieldFlags}            '--json[Output JSON]' \\
             '--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]' \\
@@ -2452,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
@@ -2794,4 +2798,4 @@ export function runCompletion(shell, itemTypes = [], tags = [], eagerTagExpansio
     };
 }
 //# sourceMappingURL=completion.js.map
-//# debugId=c8446891-4e65-54c3-9826-eb40f4922f3b
+//# 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