@unbrained/pm-cli 2026.8.27 → 2026.8.29

package/dist/sdk/annotations.js

@@ -4,7 +4,7 @@
  * Implements the pm annotation command 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]="39acab93-f9ad-5b95-871e-625d912f1322")}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]="6d20a21c-ac67-5712-9f63-b10ffc0e2c64")}catch(e){}}();
 import { assertInitializedTracker } from "./environment/tracker-preflight.js";
 import { readFile } from "node:fs/promises";
 import { isFileAbsentError } from "../core/fs/fs-utils.js";
@@ -217,6 +217,13 @@ function assertAnnotationAddValueIsNotFlagLike(raw, config) {
  * with the same structured recovery bundle.
  */
 function assertAnnotationMessageHasTextSource(config, options) {
+    if (options.ifAbsent === true &&
+        !["add", "stdin", "file"].includes(config.input.mode)) {
+        throw new PmCliError(`--if-absent requires a ${config.collectionKey.replace(/s$/, "")} append`, EXIT_CODE.USAGE, {
+            code: "annotation_if_absent_without_append",
+            required: "Combine --if-absent with one append text source; omit it for list, edit, and delete operations.",
+        });
+    }
     if (config.input.mode !== "list" || options.message === undefined) {
         return;
     }
@@ -230,6 +237,19 @@ function assertAnnotationMessageHasTextSource(config, options) {
         ],
     });
 }
+/** Append one annotation entry or return the matching entry for an idempotent retry. */
+function appendAnnotationEntry(document, collectionKey, author, text, ifAbsent, createEntry) {
+    const entries = readAnnotationEntries(document.metadata, collectionKey);
+    const existingIndex = ifAbsent
+        ? entries.findIndex((entry) => entry.author === author && entry.text === text)
+        : -1;
+    if (existingIndex >= 0) {
+        return { changedFields: [], entryIndex: existingIndex + 1 };
+    }
+    entries.push(createEntry({ created_at: nowIso(), author, text }));
+    document.metadata[collectionKey] = entries;
+    return { changedFields: [collectionKey], entryIndex: entries.length };
+}
 /** Implements run annotation command for the public runtime surface of this module. */
 export async function runAnnotationCommand(id, options, global, config) {
     assertAnnotationMessageHasTextSource(config, options);
@@ -325,6 +345,7 @@ export async function runAnnotationCommand(id, options, global, config) {
         }, options.fullHistory === true);
     }
     let result;
+    let entryIndex = 0;
     try {
         result = await mutateItem({
             pmRoot,
@@ -335,12 +356,11 @@ export async function runAnnotationCommand(id, options, global, config) {
             message: options.message,
             force: options.force,
             bypassAssigneeConflict: config.bypassOwnershipConflict,
+            skipNoop: options.ifAbsent === true,
             mutate(document) {
-                const entries = readAnnotationEntries(document.metadata, config.collectionKey);
-                const entryInput = { created_at: nowIso(), author, text };
-                entries.push(config.createEntry(entryInput));
-                document.metadata[config.collectionKey] = entries;
-                return { changedFields: [config.collectionKey] };
+                const appended = appendAnnotationEntry(document, config.collectionKey, author, text, options.ifAbsent === true, config.createEntry);
+                entryIndex = appended.entryIndex;
+                return { changedFields: appended.changedFields };
             },
         });
     }
@@ -350,8 +370,11 @@ export async function runAnnotationCommand(id, options, global, config) {
     const allEntries = readAnnotationEntries(result.item, config.collectionKey);
     return renderAnnotationResult(result.item.id, config.collectionKey, allEntries, limit, options.includeMeta === true, {
         action: "add",
-        entryIndex: allEntries.length,
-        entry: allEntries.at(-1),
+        entryIndex,
+        entry: allEntries[entryIndex - 1],
+        changedCount: options.ifAbsent === true
+            ? Math.min(result.changedFields.length, 1)
+            : undefined,
     }, options.fullHistory === true);
 }
 /** Implements resolve annotation index for the public runtime surface of this module. */
@@ -367,6 +390,36 @@ export function resolveAnnotationIndex(oneBasedIndex, count, collectionKey) {
     }
     return oneBasedIndex - 1;
 }
+/** Build the mutation and omission receipts attached to bounded annotation results. */
+function renderAnnotationMutationReceipts(collectionKey, mutation, historyOmitted) {
+    if (mutation === undefined)
+        return {};
+    return {
+        mutation_receipt: {
+            action: mutation.action,
+            entry_index: mutation.entryIndex,
+            changed_count: mutation.changedCount ?? 1,
+            full_history_included: !historyOmitted,
+        },
+        omission_receipt: {
+            has_omissions: historyOmitted,
+            omitted_field_group_count: historyOmitted ? 1 : 0,
+            omitted_field_groups: historyOmitted
+                ? [
+                    {
+                        name: `${collectionKey}_history`,
+                        restore_with: {
+                            selector: "full_history",
+                            cli_flag: "--full-history",
+                            sdk_option: "fullHistory",
+                            mcp_option: "full",
+                        },
+                    },
+                ]
+                : [],
+        },
+    };
+}
 function renderAnnotationResult(id, collectionKey, allEntries, limit, includeMeta, mutation, fullHistory = false) {
     const entries = mutation === undefined || fullHistory
         ? limitAnnotationEntries(allEntries, mutation !== undefined && fullHistory ? undefined : limit)
@@ -378,6 +431,9 @@ function renderAnnotationResult(id, collectionKey, allEntries, limit, includeMet
         id,
         [collectionKey]: entries,
         count: entries.length,
+        ...(mutation?.changedCount === undefined
+            ? {}
+            : { changed: mutation.changedCount === 1 }),
         ...([includeMeta, mutation !== undefined].includes(true)
             ? {
                 total_count: allEntries.length,
@@ -386,34 +442,8 @@ function renderAnnotationResult(id, collectionKey, allEntries, limit, includeMet
                 ...(limit !== undefined ? { limit } : {}),
             }
             : {}),
-        ...(mutation === undefined
-            ? {}
-            : {
-                mutation_receipt: {
-                    action: mutation.action,
-                    entry_index: mutation.entryIndex,
-                    changed_count: 1,
-                    full_history_included: !historyOmitted,
-                },
-                omission_receipt: {
-                    has_omissions: historyOmitted,
-                    omitted_field_group_count: historyOmitted ? 1 : 0,
-                    omitted_field_groups: historyOmitted
-                        ? [
-                            {
-                                name: `${collectionKey}_history`,
-                                restore_with: {
-                                    selector: "full_history",
-                                    cli_flag: "--full-history",
-                                    sdk_option: "fullHistory",
-                                    mcp_option: "full",
-                                },
-                            },
-                        ]
-                        : [],
-                },
-            }),
+        ...renderAnnotationMutationReceipts(collectionKey, mutation, historyOmitted),
     };
 }
 //# sourceMappingURL=annotations.js.map
-//# debugId=39acab93-f9ad-5b95-871e-625d912f1322
+//# debugId=6d20a21c-ac67-5712-9f63-b10ffc0e2c64

package/dist/sdk/cli-bootstrap.d.ts

@@ -53,15 +53,9 @@ export interface BootstrapHelpRequest {
 }
 /** Implements parse bootstrap help request for the public runtime surface of this module. */
 export declare function parseBootstrapHelpRequest(argv: string[]): BootstrapHelpRequest;
-/**
- * Index of the command token in argv — the first non-flag token, skipping the
- * value-consuming/global bootstrap flags. Returns undefined when there is none
- * (bare invocation, only global flags, or a leading `--`). Single source of truth
- * for command-position scanning shared by {@link parseBootstrapCommandName} and the
- * command-alias rewrite so their precedence rules can never drift apart.
- */
+/** Locate the command token after global bootstrap flags and their values. */
 export declare function findBootstrapCommandTokenIndex(argv: string[]): number | undefined;
-/** Implements parse bootstrap command name for the public runtime surface of this module. */
+/** Resolve the normalized command name from bootstrap invocation arguments. */
 export declare function parseBootstrapCommandName(argv: string[]): string | undefined;
 /** Implements apply bootstrap pager policy for the public runtime surface of this module. */
 export declare function applyBootstrapPagerPolicy(argv: string[]): () => void;

package/dist/sdk/cli-bootstrap.js

@@ -4,24 +4,14 @@
  * 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]="90f1f3ba-b3a9-5730-9cf7-8947e782a027")}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]="3d35c0f5-e1b8-5fd8-8fd7-c754a21784a1")}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";
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
 import { normalizeItemAddressInvocation } from "./agent/item-addressing.js";
-const GLOBAL_VALUE_CONSUMING_FLAGS = new Set([
-    "--pm-path",
-    "--path",
-    "--author",
-    "--output-include",
-    "--output-limit",
-    "--output-budget",
-    "--output-format",
-    "--output-session",
-    "--output-cursor",
-]);
+import { BOOTSTRAP_BOOLEAN_FLAGS, GLOBAL_VALUE_CONSUMING_FLAGS, consumesBootstrapValue, findBootstrapCommandTokenIndex as findContractBootstrapCommandTokenIndex, isInlineGlobalValueToken, parseBootstrapCommandName as parseContractBootstrapCommandName, } from "./cli-contracts/bootstrap-command-scanner.js";
 const OUTPUT_VALUE_FLAGS = new Set([
     "--output-include",
     "--output-limit",
@@ -30,28 +20,6 @@ const OUTPUT_VALUE_FLAGS = new Set([
     "--output-session",
     "--output-cursor",
 ]);
-/** Whether a global value-consuming flag uses its inline `--flag=value` form. */
-const 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. */
-const consumesBootstrapValue = (flag, next) => {
-    if (typeof next !== "string")
-        return false;
-    return flag === "--path" || flag === "--pm-path" || !next.startsWith("-");
-};
-const BOOTSTRAP_BOOLEAN_FLAGS = new Set([
-    "--no-extensions",
-    "--no-pager",
-    "--json",
-    "--quiet",
-    "--lean",
-    "--token-accounting",
-    "--output-row-contract",
-    "--all",
-]);
 /** Consume one bootstrap-global token and update the accumulated parse state. */
 function consumeBootstrapGlobalToken(argv, index, state) {
     const token = argv[index];
@@ -197,41 +165,13 @@ export function parseBootstrapHelpRequest(argv) {
         commandPathTokens,
     };
 }
-/**
- * Index of the command token in argv — the first non-flag token, skipping the
- * value-consuming/global bootstrap flags. Returns undefined when there is none
- * (bare invocation, only global flags, or a leading `--`). Single source of truth
- * for command-position scanning shared by {@link parseBootstrapCommandName} and the
- * command-alias rewrite so their precedence rules can never drift apart.
- */
+/** Locate the command token after global bootstrap flags and their values. */
 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;
+    return findContractBootstrapCommandTokenIndex(argv);
 }
-/** Implements parse bootstrap command name for the public runtime surface of this module. */
+/** Resolve the normalized command name from bootstrap invocation arguments. */
 export function parseBootstrapCommandName(argv) {
-    const index = findBootstrapCommandTokenIndex(argv);
-    return index === undefined ? undefined : argv[index].trim().toLowerCase();
+    return parseContractBootstrapCommandName(argv);
 }
 function shouldDisablePagerForInvocation(argv, bootstrapGlobal) {
     if (bootstrapGlobal.noPager) {
@@ -896,4 +836,4 @@ export const _testOnly = {
     resolveCanonicalFlag,
 };
 //# sourceMappingURL=cli-bootstrap.js.map
-//# debugId=90f1f3ba-b3a9-5730-9cf7-8947e782a027
+//# debugId=3d35c0f5-e1b8-5fd8-8fd7-c754a21784a1

package/dist/sdk/cli-contracts/bootstrap-command-scanner.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @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. */
+export declare const GLOBAL_VALUE_CONSUMING_FLAGS: Set<string>;
+/** Boolean global options ignored while locating the command token. */
+export declare const BOOTSTRAP_BOOLEAN_FLAGS: Set<string>;
+/** Whether a global value-consuming flag uses its inline `--flag=value` form. */
+export declare function isInlineGlobalValueToken(token: string): boolean;
+/** Whether a bootstrap value flag consumes its following token. */
+export declare function consumesBootstrapValue(flag: string, next: string | undefined): boolean;
+/**
+ * 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 declare function findBootstrapCommandTokenIndex(argv: readonly string[]): number | undefined;
+/** Resolve the normalized command name from shell-free invocation arguments. */
+export declare function parseBootstrapCommandName(argv: readonly string[]): string | undefined;

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