@unbrained/pm-cli 2026.8.27 → 2026.8.28

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

@@ -1,19 +1,7 @@
 /** Generated partition 2 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]="b5722b34-7560-5460-8280-8666a27e5490")}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]="5d5ca5e6-4286-59d6-a669-29fbce3fa19f")}catch(e){}}();
 export const PM_ERROR_CODE_CATALOG_PART_2 = [
-    {
-        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: [],
-    },
     {
         code: "missing_budget",
         meaning: "Missing budget condition.",
@@ -331,6 +319,30 @@ export const PM_ERROR_CODE_CATALOG_PART_2 = [
         canonical_code: "non_refusal_exit",
         aliases: [],
     },
+    {
+        code: "npm_package_archive_missing",
+        meaning: "Npm package archive missing condition.",
+        stability: "provisional",
+        exit_code: 1,
+        class: "generic_failure",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/extension/install-sources.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "npm_package_archive_missing",
+        aliases: [],
+    },
+    {
+        code: "npm_package_archive_unsafe",
+        meaning: "Npm package archive unsafe condition.",
+        stability: "provisional",
+        exit_code: 1,
+        class: "generic_failure",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/extension/install-sources.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "npm_package_archive_unsafe",
+        aliases: [],
+    },
     {
         code: "npm_package_not_found",
         meaning: "Npm package not found condition.",
@@ -2114,4 +2126,4 @@ export const PM_ERROR_CODE_CATALOG_PART_2 = [
     },
 ];
 //# sourceMappingURL=generated-error-code-catalog-part-2.js.map
-//# debugId=b5722b34-7560-5460-8280-8666a27e5490
+//# debugId=5d5ca5e6-4286-59d6-a669-29fbce3fa19f

package/dist/sdk/index.d.ts

@@ -118,6 +118,7 @@ export * from "./query/item-filter-options.js";
 export * from "./query/parsers.js";
 export * from "./output.js";
 export * from "./output-contracts.js";
+export * from "./agent/task-transcript-contracts.js";
 export * from "./relationship-analytics.js";
 export * from "./relationship-context.js";
 export * from "./relationship-history.js";

package/dist/sdk/index.js

@@ -4,7 +4,7 @@
  * Defines public SDK APIs and package-author helpers for Index.
  */
 
-!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]="ae931d1f-b7c6-5f15-aa9a-cda07f375b74")}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]="ea1845ab-34f5-5a1c-ad49-ac81495c1840")}catch(e){}}();
 export { PM_COMMAND_CAPABILITY_CONTRACTS, PM_COMMAND_VISIBILITY_CONTRACTS, PM_MCP_PROMPT_CONTRACTS, PM_MCP_RESOURCE_CONTRACTS, PM_MCP_TOOL_COMMAND_CONTRACTS, listPmCommandsForFamily, listPmCommandsForTier, listPmMcpToolsForProfile, renderPmCommandVisibilityMarkdown, resolvePmCommandCapabilityFamily, resolvePmCommandVisibilityTier, } from "./agent-capability-contracts.js";
 export * from "./mcp/protocol.js";
 export * from "./mcp/interactions.js";
@@ -115,6 +115,7 @@ export * from "./query/item-filter-options.js";
 export * from "./query/parsers.js";
 export * from "./output.js";
 export * from "./output-contracts.js";
+export * from "./agent/task-transcript-contracts.js";
 export * from "./relationship-analytics.js";
 export * from "./relationship-context.js";
 export * from "./relationship-history.js";
@@ -175,4 +176,4 @@ export * from "./governance.js";
 export * from "./query.js";
 export * from "./testing.js";
 //# sourceMappingURL=index.js.map
-//# debugId=ae931d1f-b7c6-5f15-aa9a-cda07f375b74
+//# debugId=ea1845ab-34f5-5a1c-ad49-ac81495c1840

package/dist/sdk/learnings.d.ts

@@ -22,6 +22,8 @@ export interface LearningsCommandOptions {
     limit?: string;
     /** Return complete learning history after a mutation instead of a bounded receipt. */
     fullHistory?: boolean;
+    /** Append only when no learning 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. */
@@ -49,6 +51,8 @@ export interface LearningsResult {
     mutation_receipt?: AnnotationMutationReceipt;
     /** Declares whether older learnings were withheld from a mutation response. */
     omission_receipt?: AnnotationOmissionReceipt;
+    /** Whether a requested mutation changed persisted state. */
+    changed?: boolean;
 }
 /** Implements run learnings for the public runtime surface of this module. */
 export declare function runLearnings(id: string, options: LearningsCommandOptions, global: GlobalOptions): Promise<LearningsResult>;

package/dist/sdk/learnings.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]="93184f29-f215-5413-9628-fb5b34523995")}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]="972816c9-b407-5b89-a744-249c9771451f")}catch(e){}}();
 import { parseAnnotationTextInput, resolveAnnotationInput, runAnnotationCommand, } from "./annotations.js";
 /** Implements run learnings for the public runtime surface of this module. */
 export async function runLearnings(id, options, global) {
@@ -11,11 +11,14 @@ export async function runLearnings(id, options, global) {
         deleteOp: "learning_delete",
         parseText: (raw) => parseAnnotationTextInput(raw),
         createEntry: (entry) => entry,
-        bypassOwnershipConflict: Boolean(options.edit === undefined && options.delete === undefined &&
+        bypassOwnershipConflict: Boolean(options.edit === undefined &&
+            options.delete === undefined &&
             options.ownershipAppendBypass),
         conflictGuidance: {
             required: "For an approved append-only handoff on another owner's item, use the package-provided ownership bypass before considering --force.",
-            examples: ['pm learnings pm-a1b2 --add "review learning" --author "reviewer" --force'],
+            examples: [
+                'pm learnings pm-a1b2 --add "review learning" --author "reviewer" --force',
+            ],
             nextSteps: [
                 "Use an installed package's narrow append-only ownership bypass when available.",
                 "Use --force only when an ownership override is explicitly approved.",
@@ -24,4 +27,4 @@ export async function runLearnings(id, options, global) {
     });
 }
 //# sourceMappingURL=learnings.js.map
-//# debugId=93184f29-f215-5413-9628-fb5b34523995
+//# debugId=972816c9-b407-5b89-a744-249c9771451f

package/dist/sdk/lifecycle/close.js

@@ -4,11 +4,12 @@
  * Implements the pm close 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]="781b5118-7b07-53c7-802f-c889cb797a96")}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]="9f28f7d8-993b-5201-b606-d1eab0c3ff5c")}catch(e){}}();
 import { assertInitializedTracker } from "../environment/tracker-preflight.js";
 import { toItemRecord, isTerminalStatus, resolveItemTypeRegistry, resolveRuntimeStatusRegistry, EXIT_CODE, PmCliError, buildItemNotFoundError, listAllItemMetadataLight, locateItem, mutateItem, readLocatedItem, resolvePmRoot, readSettings, resolveAuthor, resolveIsoOrRelative, shouldCompletePlanOnClose, getActiveExtensionRegistrations, } from "../runtime-primitives.js";
 import { collectBlockedByIds, indexBlockedByIds } from "../actionability.js";
 import { applyTerminalOrderingPolicy, requireTerminalReason, } from "../lifecycle-policy.js";
+import { nowIso } from "../../core/shared/time.js";
 import { renderPmCommand } from "../command-line.js";
 const CLOSE_VALIDATION_FIELDS = [
     { key: "resolution", label: "resolution (--resolution)" },
@@ -415,7 +416,7 @@ export async function closeItem(id, closeReasonText, options, global) {
     // informational note instead of the warn/strict validation warning.
     const trackerItems = await listAllItemMetadataLight(pmRoot, settings.item_format, typeToFolder, undefined, settings.schema);
     const activeChildIds = findActiveChildIds(trackerItems, located.id, statusRegistry);
-    const closedAt = new Date().toISOString();
+    const closedAt = nowIso();
     const completedAt = options.completedAt === undefined
         ? closedAt
         : resolveIsoOrRelative(options.completedAt, new Date(closedAt), "completed-at");
@@ -457,4 +458,4 @@ export function runClose(id, closeReasonText, options, global) {
     return closeItem(id, closeReasonText, options, global);
 }
 //# sourceMappingURL=close.js.map
-//# debugId=781b5118-7b07-53c7-802f-c889cb797a96
+//# debugId=9f28f7d8-993b-5201-b606-d1eab0c3ff5c

package/dist/sdk/notes.d.ts

@@ -30,6 +30,8 @@ export interface NotesCommandOptions {
     includeMeta?: boolean;
     /** Return complete note history after a mutation instead of a bounded receipt. */
     fullHistory?: boolean;
+    /** Append only when no note 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. */
@@ -59,6 +61,8 @@ export interface NotesResult {
     mutation_receipt?: AnnotationMutationReceipt;
     /** Declares whether older notes were withheld from a mutation response. */
     omission_receipt?: AnnotationOmissionReceipt;
+    /** Whether a requested mutation changed persisted state. */
+    changed?: boolean;
 }
 /** Implements run notes for the public runtime surface of this module. */
 export declare function runNotes(id: string, options: NotesCommandOptions, global: GlobalOptions): Promise<NotesResult>;

package/dist/sdk/notes.js

@@ -4,7 +4,7 @@
  * Implements the pm notes 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]="ebd9f151-593f-5081-97da-d78f83de4914")}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]="216389a2-fb85-56a0-8ef2-9f41f1321c16")}catch(e){}}();
 import { EXIT_CODE, PmCliError, parseLimit, stableStringify, } from "./runtime-primitives.js";
 import { limitAnnotationEntries, parseAnnotationTextInput, resolveAnnotationInput, runAnnotationCommand, } from "./annotations.js";
 function parseStructuredEventPayload(raw) {
@@ -137,4 +137,4 @@ export async function runNotes(id, options, global) {
     };
 }
 //# sourceMappingURL=notes.js.map
-//# debugId=ebd9f151-593f-5081-97da-d78f83de4914
+//# debugId=216389a2-fb85-56a0-8ef2-9f41f1321c16

package/dist/sdk/runtime-input.js

@@ -5,7 +5,7 @@
  * primitives are shared by native action dispatchers and MCP-specific adapters.
  */
 
-!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]="7949205a-ab1b-5457-961c-593498aff88b")}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]="fde4fea5-94d6-53e2-bfbc-bff71d828c01")}catch(e){}}();
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
 import { asRecordClone } from "../core/shared/primitives.js";
@@ -202,6 +202,9 @@ const HOISTED_ACTION_OPTION_KEYS = {
     update: ["parent", "allowMissingParent", "completedAt"],
     copy: ["allowDuplicate"],
     close: ["duplicateOf", "completedAt"],
+    comments: ["ifAbsent"],
+    notes: ["ifAbsent"],
+    learnings: ["ifAbsent"],
     upgrade: [
         "scope",
         "dryRun",
@@ -586,4 +589,4 @@ export function updateManyOptionsFromFlat(options) {
     };
 }
 //# sourceMappingURL=runtime-input.js.map
-//# debugId=7949205a-ab1b-5457-961c-593498aff88b
+//# debugId=fde4fea5-94d6-53e2-bfbc-bff71d828c01

package/dist/sdk/runtime.d.ts

@@ -157,11 +157,11 @@ export declare class PmClient {
     stats<Options extends ReadOptions<StatsCommandOptions> = StatsCommandOptions>(options?: Options): ReadPromise<StatsResult, Options>;
     /** Discover existing duplicate clusters without mutating tracker state. */
     duplicates<Options extends ReadOptions<DuplicatesCommandOptions> = DuplicatesCommandOptions>(options?: Options): ReadPromise<DuplicatesResult, Options>;
-    /** List, add, edit, or delete item comments. */
+    /** List or mutate comments, including lock-scoped idempotent appends. */
     comments<Options extends ReadOptions<CommentsCommandOptions> = CommentsCommandOptions>(id: string, options?: Options): ReadPromise<CommentsResult, Options>;
-    /** List or append private item notes. */
+    /** List or mutate private notes, including lock-scoped idempotent appends. */
     notes<Options extends ReadOptions<NotesCommandOptions> = NotesCommandOptions>(id: string, options?: Options): ReadPromise<NotesResult, Options>;
-    /** List or append durable item learnings. */
+    /** List or mutate durable learnings, including lock-scoped idempotent appends. */
     learnings(id: string, options?: LearningsCommandOptions): Promise<LearningsResult>;
     /** Add, remove, clear, or list linked project files for an item. */
     files<Options extends ReadOptions<FilesCommandOptions> = FilesCommandOptions>(id: string, options?: Options): ReadPromise<FilesResult, Options>;
@@ -373,11 +373,11 @@ export declare function aggregate<Options extends ReadOptions<AggregateOptions>
 export declare function stats<Options extends ReadOptions<StatsCommandOptions> = StatsCommandOptions>(options?: Options, clientOptions?: PmClientOptions): ReadPromise<StatsResult, Options>;
 /** Discover duplicate clusters without constructing a reusable client. */
 export declare function duplicates<Options extends ReadOptions<DuplicatesCommandOptions> = DuplicatesCommandOptions>(options?: Options, clientOptions?: PmClientOptions): ReadPromise<DuplicatesResult, Options>;
-/** List, add, edit, or delete item comments without constructing a reusable client. */
+/** List or mutate comments with optional idempotency without constructing a client. */
 export declare function comments<Options extends ReadOptions<CommentsCommandOptions> = CommentsCommandOptions>(id: string, options?: Options, clientOptions?: PmClientOptions): ReadPromise<CommentsResult, Options>;
-/** List or append private item notes without constructing a reusable client. */
+/** List or mutate private notes with optional idempotency without constructing a client. */
 export declare function notes<Options extends ReadOptions<NotesCommandOptions> = NotesCommandOptions>(id: string, options?: Options, clientOptions?: PmClientOptions): ReadPromise<NotesResult, Options>;
-/** List or append durable item learnings without constructing a reusable client. */
+/** List or mutate durable learnings with optional idempotency without constructing a client. */
 export declare function learnings(id: string, options?: LearningsCommandOptions, clientOptions?: PmClientOptions): Promise<LearningsResult>;
 /** Manage linked item files without constructing a reusable client. */
 export declare function files<Options extends ReadOptions<FilesCommandOptions> = FilesCommandOptions>(id: string, options?: Options, clientOptions?: PmClientOptions): ReadPromise<FilesResult, Options>;

package/dist/sdk/runtime.js

@@ -4,7 +4,7 @@
  * Defines public SDK APIs and package-author helpers for Runtime.
  */
 
-!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]="72111aa2-52b2-53da-a1c8-07ba53a74944")}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]="b67ba0fe-bbca-57ab-b3be-a4a028f21de4")}catch(e){}}();
 export { PM_GITIGNORE_END, PM_GITIGNORE_START, ensurePmGitignore, getPmGitignoreBlock, } from "./workspace.js";
 export { SEARCH_EXTENSION_FLAG_DEFINITIONS } from "./extension-contracts.js";
 export * from "./cli-contracts/agent-output-contracts.js";
@@ -212,15 +212,15 @@ export class PmClient {
     duplicates(options = {}) {
         return this.runTyped("duplicates", { options });
     }
-    /** List, add, edit, or delete item comments. */
+    /** List or mutate comments, including lock-scoped idempotent appends. */
     comments(id, options = {}) {
         return this.runTyped("comments", { id, options });
     }
-    /** List or append private item notes. */
+    /** List or mutate private notes, including lock-scoped idempotent appends. */
     notes(id, options = {}) {
         return this.runTyped("notes", { id, options });
     }
-    /** List or append durable item learnings. */
+    /** List or mutate durable learnings, including lock-scoped idempotent appends. */
     learnings(id, options = {}) {
         return this.runTyped("learnings", { id, options });
     }
@@ -744,15 +744,15 @@ export function stats(options = {}, clientOptions = {}) {
 export function duplicates(options = {}, clientOptions = {}) {
     return new PmClient(clientOptions).duplicates(options);
 }
-/** List, add, edit, or delete item comments without constructing a reusable client. */
+/** List or mutate comments with optional idempotency without constructing a client. */
 export function comments(id, options = {}, clientOptions = {}) {
     return new PmClient(clientOptions).comments(id, options);
 }
-/** List or append private item notes without constructing a reusable client. */
+/** List or mutate private notes with optional idempotency without constructing a client. */
 export function notes(id, options = {}, clientOptions = {}) {
     return new PmClient(clientOptions).notes(id, options);
 }
-/** List or append durable item learnings without constructing a reusable client. */
+/** List or mutate durable learnings with optional idempotency without constructing a client. */
 export function learnings(id, options = {}, clientOptions = {}) {
     return new PmClient(clientOptions).learnings(id, options);
 }
@@ -1933,4 +1933,4 @@ async function loadWorkspaceExtensionRegistrations(pmRoot, settings, cwd) {
     }
 }
 //# sourceMappingURL=runtime.js.map
-//# debugId=72111aa2-52b2-53da-a1c8-07ba53a74944
+//# debugId=b67ba0fe-bbca-57ab-b3be-a4a028f21de4

package/docs/COMMANDS.md

@@ -735,15 +735,16 @@ explicitly overriding terminal-state or lock conflicts.
 
 ```bash
 pm comments <id> "Implemented command parsing fix."
+pm comments <id> "Implemented command parsing fix." --author agent-a --if-absent
 printf '%s\n' '## Verification summary' '- Linux pass' '- macOS pass' | pm comments <id> --stdin
 pm comments <id> --file docs/release-evidence.md
 pm comments <id> --edit 2 "Corrected: the regression was in the parser, not the renderer."
 pm comments <id> --delete 3
-pm notes <id> --add "Keep renderer changes isolated to TOON output."
-pm learnings <id> --add "Use runtime contracts instead of duplicating flag lists."
+pm notes <id> --add "Keep renderer changes isolated to TOON output." --if-absent
+pm learnings <id> --add "Use runtime contracts instead of duplicating flag lists." --if-absent
 ```
 
-Use comments for progress and evidence, notes for implementation context, and learnings for durable future guidance. All three accept `--text` as a hidden compatibility alias for canonical `--add`; comments also retain `--body`/`--comment`, and notes retain `--note`. Choose exactly one input source (`[text]`, an add alias, `--stdin`, or `--file`) per invocation. Conflicting alias values fail before mutation. To clean up obsolete orchestration notes, `--edit <index>` rewrites the comment at a 1-based index and `--delete <index>` removes it; both record history and honor ownership rules.
+Use comments for progress and evidence, notes for implementation context, and learnings for durable future guidance. All three accept `--text` as a hidden compatibility alias for canonical `--add`; comments also retain `--body`/`--comment`, and notes retain `--note`. Choose exactly one input source (`[text]`, an add alias, `--stdin`, or `--file`) per invocation. Conflicting alias values fail before mutation. For retrying agents, `--if-absent` makes any annotation append idempotent by the resolved author plus exact normalized stored text: the first call returns `changed: true` and `mutation_receipt.changed_count: 1`; an exact retry returns `changed: false`, the existing entry position, and `changed_count: 0` without writing item or history state. Different authors remain distinct, and omitting `--if-absent` deliberately preserves duplicate-appending compatibility. The flag is append-only and is rejected for list, edit, and delete operations. To clean up obsolete orchestration notes, `--edit <index>` rewrites the comment at a 1-based index and `--delete <index>` removes it; both record history and honor ownership rules.
 
 ## Linked Artifacts
 

package/docs/OUTPUT_TOKEN_ACCOUNTING.md

@@ -1,6 +1,6 @@
 # Output Token Accounting
 
-Tracker references: [pm-t5dt4z](../.agents/pm/tasks/pm-t5dt4z.toon) and [pm-g3n00m](../.agents/pm/stories/pm-g3n00m.toon).
+Tracker references: [pm-t5dt4z](../.agents/pm/tasks/pm-t5dt4z.toon), [pm-g3n00m](../.agents/pm/stories/pm-g3n00m.toon), [pm-8pnj](../.agents/pm/features/pm-8pnj.toon), [pm-f05lsg](../.agents/pm/features/pm-f05lsg.toon), and [pm-srns](../.agents/pm/issues/pm-srns.toon).
 
 ## Agent Quick Context
 
@@ -39,20 +39,33 @@ The command still exits with its normal non-zero status; the receipt is additive
 
 ## Release-Level Task Entitlement
 
-[`agent-task-token-baseline.json`](agent-task-token-baseline.json) is the externally shipped release baseline. The gate executes the built CLI in an isolated workspace and covers:
+[`agent-task-transcripts.json`](agent-task-transcripts.json) is the SDK-validated, versioned golden corpus. [`agent-task-token-baseline.json`](agent-task-token-baseline.json) is its externally shipped release ratchet. The gate executes the built CLI against independent, identically seeded accounting-on and accounting-off workspaces. Its five complete workflows cover:
 
-- a small-workspace read;
-- a scaled-workspace context read;
-- a returning-agent item read with a required-field completeness assertion;
-- a failing command with bounded recovery output.
+- bounded triage, scaled-workspace orientation, and returning-agent inspection;
+- a closed-domain refusal followed by the exact advertised shell-free retry;
+- an unknown option after valid flags followed by a corrected command;
+- create, inspect, close, and final-state confirmation through mutation receipts;
+- successful bulk partial-effect and no-effect exits without collapsing them into exit zero.
 
-Each invocation is independently byte-counted, its section sum is checked, and its consumed field is retained. A seeded million-token regression proves the ratchet fails. Run it with:
+Every step verifies its public SDK output family, canonical successful or refusal exit status, required own-property paths, declared `expected_field_values`, and refusal identity where applicable. Recovery steps must declare a successful output family instead of chaining one refusal to another, every refusal in a completed task must have a later successful `recovery_for` step, and every completed task must terminate with successful output. Successful steps cannot carry refusal-only metadata. Dot-separated `required_fields` and `expected_field_values` paths are traversed structurally from the output root, so incidental prose or nested key names cannot satisfy completeness or terminal-state assertions. The report publishes bytes and estimated tokens for each step and completed task, retry counts, corpus digest, and composite cost. Accounting-on application payloads must be byte-equivalent to their independently captured accounting-off payloads after removing only the receipt. Receipt byte and token fields are independently measured rather than trusted. Runtime refusals verify that their self-reported `total_bytes` matches the independent transport and that `total_estimated_tokens` equals `ceil(total_bytes / 4)`; Commander usage refusals that happen before accounting attachment are measured directly from the captured transport and labeled `independent_transport`.
+
+The baseline fails closed on corpus digest, task identity, step identity, missing or non-finite per-step and per-task ceilings, and missing or non-finite composite cost ceilings. A seeded million-token completed-task regression proves the ratchet fails. Run it with:
 
 ```bash
 pnpm quality:agent-task-token
 node scripts/release/agent-task-token-gate.mjs --negative-control
 ```
 
+Package authors can validate their own corpus with the same public contract before replay:
+
+```ts
+import { parsePmAgentTaskTranscriptCorpus } from "@unbrained/pm-cli/sdk/contracts";
+
+const corpus = parsePmAgentTaskTranscriptCorpus(JSON.parse(source));
+```
+
+The parser rejects unknown versions, empty tasks or steps, duplicate identities, output families that disagree with the command contract, refusal-only metadata on successful steps, terminal or otherwise unrecovered refusals, and recovery edges that do not point from a successful step to an earlier refusal.
+
 Refresh the committed ceiling only after an intentional reviewed output change:
 
 ```bash

package/docs/RELEASING.md

@@ -29,6 +29,8 @@ provenance is tracked by [pm-u1baah](../.agents/pm/issues/pm-u1baah.toon), and
 authoritative blocker-recovery run selection by
 [pm-db8onn](../.agents/pm/issues/pm-db8onn.toon), and queued automatic
 same-day recovery by [pm-dm2vfz](../.agents/pm/issues/pm-dm2vfz.toon).
+Bounded Sentry request latency is tracked by
+[pm-b9g2cs](../.agents/pm/issues/pm-b9g2cs.toon).
 
 ## Version Policy
 
@@ -210,6 +212,12 @@ events, and every `generic_failure` or `dependency_failed` remain blocking.
 This keeps rewording independent from release policy and makes stale or broad
 message allowlists impossible.
 
+Sentry API requests use a 120-second deadline by default. Operators can set
+`--sentry-request-timeout-ms` between `1` and `300000` when reproducing
+provider latency, while the emitted gate receipt records the effective value.
+The release workflow pins `120000`; query timeouts remain fail-closed and must
+not be treated as an empty issue set.
+
 If private reliability checks identify repeated user friction, either confirm the current release already contains the remediation with regression coverage or fix it before continuing.
 
 The build writes `dist/cli-bundle/bundle-manifest.json` atomically with SHA-256 digests for every emitted bundle file. At startup, `pm` reports `bundle_integrity_torn_install` only when a module-loader failure is accompanied by manifest proof that an upgrade or rebuild changed, removed, or corrupted the active bundle. Reinstall `@unbrained/pm-cli` and retry after that diagnostic. Ordinary `ERR_MODULE_NOT_FOUND` and export failures with an intact manifest remain unexpected failures and must continue to block reliability gates.
@@ -358,7 +366,7 @@ git push origin v<version>
   tracked source path (apart from managed-extension install metadata).
 - static quality gate (shared complexity, duplication, dead/orphan module, file/folder hygiene, source/exported docstring coverage profile)
 - temporary-project compatibility gate against latest published tracker data
-- reliability threshold gate (Sentry severity threshold, bounded to a recent-activity window via `--sentry-window-days` (default `14`, `0` = unbounded) so a stale benign unresolved issue cannot block every scheduled release; `--telemetry-mode` gate policy: `off` | `best-effort` | `required`). Scheduled `auto-release.yml` failures open/update an `Auto Release blocked` GitHub issue so blocked daily releases are never silently skipped.
+- reliability threshold gate (Sentry severity threshold, bounded to a recent-activity window via `--sentry-window-days` (default `14`, `0` = unbounded) so a stale benign unresolved issue cannot block every scheduled release; Sentry requests use the fail-closed bounded `--sentry-request-timeout-ms` contract (default `120000`, maximum `300000`); `--telemetry-mode` gate policy: `off` | `best-effort` | `required`). Scheduled `auto-release.yml` failures open/update an `Auto Release blocked` GitHub issue so blocked daily releases are never silently skipped.
 - sandboxed `pm` coverage
 - optional Sentry release metadata and sourcemap upload when `SENTRY_AUTH_TOKEN` is configured
 - npm pack dry run and npx tarball smoke test

package/docs/SDK.md

@@ -1512,6 +1512,18 @@ edit/delete semantics, ownership guidance, history mutation metadata, and stable
 list pagination. MCP tool actions intentionally omit file input to prevent host
 filesystem access. Package authors can build custom annotation presentation
 layers without importing CLI modules.
+`CommentsCommandOptions.ifAbsent`, `NotesCommandOptions.ifAbsent`, and
+`LearningsCommandOptions.ifAbsent` give retrying agents one explicit idempotent
+annotation append contract. Equality is evaluated under the item writer lock
+after author resolution and text normalization, using the resolved author plus
+exact stored text. The first append returns `changed: true` and
+`mutation_receipt.changed_count: 1`; an exact retry returns the existing entry,
+`changed: false`, and `changed_count: 0` without changing the item, history, or
+derived search state. Different authors remain distinct, and the default
+without `ifAbsent` continues to append intentional duplicates. The option is
+valid only for append input and fails closed for list, edit, or delete modes.
+CLI `comments|notes|learnings --if-absent` and the corresponding MCP actions
+with `options.ifAbsent: true` are thin transports over this SDK behavior.
 `PmClient.notes` also accepts `addJson` for a validated structured context event. The persisted entry remains backward-readable through canonical `text` while exposing typed `format: "json"`, `data`, and `event_type` fields. `since`, `eventType`, `limit`, and `includeMeta` form the bounded query contract; the collection continues to use field-aware union merge semantics for concurrent branches.
 
 Customization convenience methods are the SDK baseline for project-specific pm

package/docs/SDK_CONTEXT_INTEGRITY.md

@@ -1,6 +1,6 @@
 # SDK Context Integrity
 
-Tracker: [pm-0k19l7](../.agents/pm/issues/pm-0k19l7.toon), [pm-9stazf](../.agents/pm/issues/pm-9stazf.toon), [pm-tu71](../.agents/pm/issues/pm-tu71.toon), [pm-0xmajx](../.agents/pm/issues/pm-0xmajx.toon), [pm-7rrqsk](../.agents/pm/issues/pm-7rrqsk.toon), [pm-ety1qc](../.agents/pm/issues/pm-ety1qc.toon), [pm-lu6sca](../.agents/pm/features/pm-lu6sca.toon), [pm-5y05kq](../.agents/pm/issues/pm-5y05kq.toon), [pm-gjjurs](../.agents/pm/issues/pm-gjjurs.toon), [pm-h97qxd](../.agents/pm/issues/pm-h97qxd.toon), [pm-h06944](../.agents/pm/issues/pm-h06944.toon), [pm-5t33or](../.agents/pm/features/pm-5t33or.toon), [pm-in23qu](../.agents/pm/issues/pm-in23qu.toon), [pm-h8tpeh](../.agents/pm/features/pm-h8tpeh.toon), [pm-okgxwa](../.agents/pm/issues/pm-okgxwa.toon), [pm-22rzjp](../.agents/pm/issues/pm-22rzjp.toon), [pm-76fkpp](../.agents/pm/issues/pm-76fkpp.toon), [pm-igdvfq](../.agents/pm/issues/pm-igdvfq.toon), [pm-643e0k](../.agents/pm/issues/pm-643e0k.toon), [pm-larv4r](../.agents/pm/issues/pm-larv4r.toon), [pm-mcxk8v](../.agents/pm/issues/pm-mcxk8v.toon), and [pm-2zkvxm](../.agents/pm/issues/pm-2zkvxm.toon).
+Tracker: [pm-0k19l7](../.agents/pm/issues/pm-0k19l7.toon), [pm-9stazf](../.agents/pm/issues/pm-9stazf.toon), [pm-tu71](../.agents/pm/issues/pm-tu71.toon), [pm-0xmajx](../.agents/pm/issues/pm-0xmajx.toon), [pm-7rrqsk](../.agents/pm/issues/pm-7rrqsk.toon), [pm-ety1qc](../.agents/pm/issues/pm-ety1qc.toon), [pm-lu6sca](../.agents/pm/features/pm-lu6sca.toon), [pm-5y05kq](../.agents/pm/issues/pm-5y05kq.toon), [pm-gjjurs](../.agents/pm/issues/pm-gjjurs.toon), [pm-h97qxd](../.agents/pm/issues/pm-h97qxd.toon), [pm-h06944](../.agents/pm/issues/pm-h06944.toon), [pm-5t33or](../.agents/pm/features/pm-5t33or.toon), [pm-in23qu](../.agents/pm/issues/pm-in23qu.toon), [pm-h8tpeh](../.agents/pm/features/pm-h8tpeh.toon), [pm-okgxwa](../.agents/pm/issues/pm-okgxwa.toon), [pm-22rzjp](../.agents/pm/issues/pm-22rzjp.toon), [pm-76fkpp](../.agents/pm/issues/pm-76fkpp.toon), [pm-igdvfq](../.agents/pm/issues/pm-igdvfq.toon), [pm-643e0k](../.agents/pm/issues/pm-643e0k.toon), [pm-larv4r](../.agents/pm/issues/pm-larv4r.toon), [pm-mcxk8v](../.agents/pm/issues/pm-mcxk8v.toon), [pm-2zkvxm](../.agents/pm/issues/pm-2zkvxm.toon), and [pm-ea1yh2](../.agents/pm/issues/pm-ea1yh2.toon).
 
 Current closure tranche: [pm-fs8q9x](../.agents/pm/tasks/pm-fs8q9x.toon), [pm-gy885b](../.agents/pm/issues/pm-gy885b.toon), and [pm-f05lsg](../.agents/pm/features/pm-f05lsg.toon).
 
@@ -82,6 +82,17 @@ The structured `option_scope` is `declared_on_path`, `declared_elsewhere`, or
 case, while the third names the nearest current-path spellings and explicitly
 terminates the otherwise-unbounded command search.
 
+## Retry-safe annotation mutations
+
+Comments, notes, and learnings expose one SDK-owned `ifAbsent` append contract.
+The item writer lock compares the resolved author and exact normalized stored
+text, so concurrent retries create one entry and one history event. The winning
+append reports `changed: true` and `mutation_receipt.changed_count: 1`; later
+exact retries return the existing entry with `changed: false` and
+`changed_count: 0`. Default appends remain duplicate-preserving. CLI
+`--if-absent` and MCP `ifAbsent` are thin transports, and `--full-history`
+remains the explicit escape hatch from bounded mutation receipts.
+
 ## Semantic flag and spelling contracts
 
 `listPmFlagLexicon()` classifies flags by meaning rather than spelling alone.

package/docs/SDK_RUNTIME_BOUNDARIES.md

@@ -61,6 +61,16 @@ published error vocabulary while still sharing classification, path redaction,
 and recovery guidance. Workspace snapshots use this compatibility path for
 their stable storage, resource, and permission fault codes.
 
+Package archives use one bounded validation and extraction boundary whether
+they come from a local path or `npm pack`. The SDK rejects links, escaping
+paths, unsupported entry types, oversized archives, and decompression growth
+before extraction. If npm reports an archive it did not create, callers receive
+the path-redacted `npm_package_archive_missing` refusal instead of a raw system
+`tar` exception; an archive reported outside the isolated pack destination is
+rejected as `npm_package_archive_unsafe`. This keeps package install behavior
+portable and prevents an untrusted registry artifact or package-manager result
+from bypassing the local-archive policy.
+
 ## CLI refusal ownership
 
 CLI adapters preserve SDK error codes, exit semantics, and actionable recovery

package/docs/TESTING.md

@@ -2,7 +2,7 @@
 
 This page describes safe local tests, linked tests, coverage, and release-readiness checks.
 
-Tracked implementation updates: [pm-52eh](../.agents/pm/features/pm-52eh.toon), [pm-mcxr](../.agents/pm/issues/pm-mcxr.toon), [pm-u42x](../.agents/pm/issues/pm-u42x.toon), [pm-atfm](../.agents/pm/features/pm-atfm.toon), [pm-xmp5](../.agents/pm/tasks/pm-xmp5.toon), [pm-39cqqx](../.agents/pm/tasks/pm-39cqqx.toon), [pm-5cgm2z](../.agents/pm/chores/pm-5cgm2z.toon), [pm-avv3wx](../.agents/pm/issues/pm-avv3wx.toon), [pm-rizqb6](../.agents/pm/issues/pm-rizqb6.toon), [pm-95h7pg](../.agents/pm/issues/pm-95h7pg.toon), [pm-giks4s](../.agents/pm/issues/pm-giks4s.toon), [pm-xa3t0o](../.agents/pm/issues/pm-xa3t0o.toon), [pm-e97jyf](../.agents/pm/issues/pm-e97jyf.toon), [pm-efkvdy](../.agents/pm/issues/pm-efkvdy.toon), and [pm-ed28wi](../.agents/pm/issues/pm-ed28wi.toon).
+Tracked implementation updates: [pm-52eh](../.agents/pm/features/pm-52eh.toon), [pm-mcxr](../.agents/pm/issues/pm-mcxr.toon), [pm-u42x](../.agents/pm/issues/pm-u42x.toon), [pm-atfm](../.agents/pm/features/pm-atfm.toon), [pm-xmp5](../.agents/pm/tasks/pm-xmp5.toon), [pm-39cqqx](../.agents/pm/tasks/pm-39cqqx.toon), [pm-5cgm2z](../.agents/pm/chores/pm-5cgm2z.toon), [pm-avv3wx](../.agents/pm/issues/pm-avv3wx.toon), [pm-rizqb6](../.agents/pm/issues/pm-rizqb6.toon), [pm-95h7pg](../.agents/pm/issues/pm-95h7pg.toon), [pm-giks4s](../.agents/pm/issues/pm-giks4s.toon), [pm-xa3t0o](../.agents/pm/issues/pm-xa3t0o.toon), [pm-e97jyf](../.agents/pm/issues/pm-e97jyf.toon), [pm-efkvdy](../.agents/pm/issues/pm-efkvdy.toon), [pm-ed28wi](../.agents/pm/issues/pm-ed28wi.toon), and [pm-5ug5xq](../.agents/pm/issues/pm-5ug5xq.toon).
 
 ## Agent Quick Context
 
@@ -43,7 +43,11 @@ claims to the same canonical gate IDs. Hosted-only environment isolation and
 tracker-integrity steps remain explicit entries with reasons rather than
 silently disappearing from local parity.
 
-`node scripts/run-tests.mjs` wraps Vitest in temporary tracker roots, then cleans them up.
+`node scripts/run-tests.mjs` wraps Vitest in temporary tracker roots, disables
+external Sentry delivery for the build, test workers, and their nested CLI
+children, then cleans the roots up. Instrumentation tests can still exercise
+Sentry initialization through their mocked module boundary; ordinary negative
+fixtures must never create production incidents from a developer host.
 
 Public SDK changes additionally run semantic surface and import-cost contracts: