@unbrained/pm-cli 2026.8.27 → 2026.8.29

package/dist/sdk/merge/reconcile.js

@@ -1,11 +1,11 @@
 
-!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]="c3ec7d9d-f276-5e97-8e97-507925e5d33a")}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]="8d85d220-dad2-5234-8819-65632275eb47")}catch(e){}}();
 import { EXIT_CODE } from "../../core/shared/constants.js";
 import { PmCliError } from "../../core/shared/errors.js";
 import { resolvePmRoot } from "../../core/store/paths.js";
 import { runHistoryRepair, runHistoryRepairAll, } from "../history-repair.js";
 import { runValidate } from "../governance/validate.js";
-import { inspectMergeReceiptEvidence, markMergeReceiptReconciled, partitionMergeReceipts, summarizeMergeReceipt, } from "./receipts.js";
+import { inspectMergeReceiptEvidence, markMergeReceiptReconciled, summarizeMergeReceipt, } from "./receipts.js";
 import { findGitWorkspaceRoot } from "./install.js";
 import { mapWithFixedConcurrency } from "../extension/concurrency.js";
 const RECEIPT_ONLY_REPAIR_CONCURRENCY = 4;
@@ -95,19 +95,6 @@ export async function runMergeReconcile(options, global) {
         });
     }
     const pendingReceipts = receiptEvidence.receipts;
-    const { pendingDecisions: discardedReceipts } = partitionMergeReceipts(pendingReceipts);
-    if (!dryRun && options.force !== true && discardedReceipts.length > 0) {
-        throw new PmCliError(`Merge reconciliation would accept ${discardedReceipts.length} receipt(s) containing discarded scalar values. Review pm merge report and rerun with --force only after deciding which values to retain or re-apply.`, EXIT_CODE.CONFLICT, {
-            code: "merge_reconcile_discards_require_acceptance",
-            required: "Explicitly review every discarded field before accepting reconciliation.",
-            nextSteps: discardedReceipts.map((receipt) => `Review receipt ${receipt.id} for ${receipt.item_id}: ${receipt.decisions
-                .map((decision) => decision.field)
-                .join(", ")}.`),
-            recovery: {
-                suggested_retry: "pm merge reconcile --dry-run",
-            },
-        });
-    }
     const receiptsByItem = new Map();
     for (const receipt of pendingReceipts) {
         const receipts = receiptsByItem.get(receipt.item_id) ?? [];
@@ -193,4 +180,4 @@ export async function runMergeReconcile(options, global) {
     };
 }
 //# sourceMappingURL=reconcile.js.map
-//# debugId=c3ec7d9d-f276-5e97-8e97-507925e5d33a
+//# debugId=8d85d220-dad2-5234-8819-65632275eb47

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/query/next.d.ts

@@ -60,6 +60,12 @@ export interface NextBlockerRef {
     title: string | null;
     /** Lifecycle state reported for status. */
     status: ItemStatus | null;
+    /** Whether this reference must be checked outside the local tracker. */
+    external?: boolean;
+    /** Conservative timestamp from which the unresolved external block may be stale. */
+    blocked_since?: string;
+    /** External resolver identity, or null when no integration verified the reference. */
+    resolver?: string | null;
 }
 /**
  * A classified actionable item on the `pm next` output: a {@link ContextFocusItem}

package/dist/sdk/query/next.js

@@ -9,7 +9,7 @@
  * re-deriving readiness from a full `pm context` snapshot every turn.
  */
 
-!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]="3431d4d4-e053-5416-b3d1-6dbfbed0142d")}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]="9b788e0a-f4ac-5c6e-bf52-0ef0519d6925")}catch(e){}}();
 import { collectBlockedByIds, computeActionabilityReport, } from "../actionability.js";
 import { resolveRuntimeStatusRegistry, EXIT_CODE, PmCliError, nowIso, normalizeStatusInput, normalizeStatusForRegistry, resolvePmRoot, readSettings, resolveAuthor, } from "../runtime-primitives.js";
 import { parseIntegerLimit } from "./parsers.js";
@@ -60,6 +60,11 @@ function toNextActionableItem(entry, statusRegistry, childrenByParent, rank) {
             id: blocker.id,
             title: blocker.title,
             status: blocker.status,
+            ...(blocker.external ? { external: true } : {}),
+            ...(blocker.blocked_since
+                ? { blocked_since: blocker.blocked_since }
+                : {}),
+            ...(blocker.external ? { resolver: blocker.resolver ?? null } : {}),
         })),
         unblocks: entry.unblocks,
         rank,
@@ -474,4 +479,4 @@ function formatNextLine(item) {
     return `${rankToken}${item.id} p${item.priority} ${item.status} ${item.type} deadline:${deadlineToken}${parentToken}${unblocksToken} ${item.title}`;
 }
 //# sourceMappingURL=next.js.map
-//# debugId=3431d4d4-e053-5416-b3d1-6dbfbed0142d
+//# debugId=9b788e0a-f4ac-5c6e-bf52-0ef0519d6925

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/dist/sdk/test/entry.d.ts

@@ -1,6 +1,6 @@
 /** Public contract for structured linked test keys, shared by SDK and presentation-layer consumers. */
 export declare const STRUCTURED_LINKED_TEST_KEYS: readonly ["command", "cmd", "path", "scope", "timeout", "timeout_seconds", "pm_context_mode", "workspace_context_mode", "env_set", "env_clear", "shared_host_safe", "assert_stdout_contains", "assert_stdout_regex", "assert_stderr_contains", "assert_stderr_regex", "assert_stdout_min_lines", "assert_json_field_equals", "assert_json_field_gte", "note"];
-/** Implements looks like structured linked test entry for the public runtime surface of this module. */
+/** Classify linked-test plaintext through the shared structured-entry grammar. */
 export declare function looksLikeStructuredLinkedTestEntry(raw: string): boolean;
 /** Implements normalize structured linked test entry for the public runtime surface of this module. */
 export declare function normalizeStructuredLinkedTestEntry(kv: Record<string, string>, optionName: "--add" | "--test"): Record<string, string>;

package/dist/sdk/test/entry.js

@@ -4,9 +4,10 @@
  * Implements the pm linked test entry 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]="44e6a87d-0ca5-53af-b199-b66bb2b98fb5")}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]="b29e4416-82ab-585c-9456-718e4699566d")}catch(e){}}();
 import { EXIT_CODE } from "../../core/shared/constants.js";
 import { PmCliError } from "../../core/shared/errors.js";
+import { looksLikeStructuredKeyValueEntry } from "../../core/item/parse.js";
 // Keys accepted inside a structured linked-test entry. `cmd` is an alias for
 // `command`; everything else maps 1:1 to a LinkedTest field.
 /** Public contract for structured linked test keys, shared by SDK and presentation-layer consumers. */
@@ -32,14 +33,9 @@ export const STRUCTURED_LINKED_TEST_KEYS = [
     "note",
 ];
 const STRUCTURED_LINKED_TEST_KEY_SET = new Set(STRUCTURED_LINKED_TEST_KEYS);
-const STRUCTURED_LINKED_TEST_KEY_PATTERN = STRUCTURED_LINKED_TEST_KEYS.map((key) => key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|");
-const STRUCTURED_LINKED_TEST_ENTRY_PATTERN = new RegExp(`^(?:[-*+]\\s+)?(?:${STRUCTURED_LINKED_TEST_KEY_PATTERN})\\s*[:=]`, "i");
-/** Implements looks like structured linked test entry for the public runtime surface of this module. */
+/** Classify linked-test plaintext through the shared structured-entry grammar. */
 export function looksLikeStructuredLinkedTestEntry(raw) {
-    if (raw.startsWith("```") || raw.includes("\n")) {
-        return true;
-    }
-    return STRUCTURED_LINKED_TEST_ENTRY_PATTERN.test(raw);
+    return looksLikeStructuredKeyValueEntry(raw, STRUCTURED_LINKED_TEST_KEYS);
 }
 /** Implements normalize structured linked test entry for the public runtime surface of this module. */
 export function normalizeStructuredLinkedTestEntry(kv, optionName) {
@@ -72,4 +68,4 @@ export function normalizeStructuredLinkedTestEntry(kv, optionName) {
     return normalizedKv;
 }
 //# sourceMappingURL=entry.js.map
-//# debugId=44e6a87d-0ca5-53af-b199-b66bb2b98fb5
+//# debugId=b29e4416-82ab-585c-9456-718e4699566d

package/dist/sdk/test/execution.d.ts

@@ -234,6 +234,8 @@ declare function readJsonPathValue(root: unknown, fieldPath: string): {
     value: unknown;
 };
 declare function evaluateLinkedTestAssertions(linkedTest: LinkedTest, stdout: string, stderr: string): string[];
+/** Return whether a linked command applies a runner-level test-name filter that must match at least one test. */
+declare function commandUsesTestNameFilter(command: string): boolean;
 interface RunLinkedTestsOptions {
     progress?: boolean;
     sourceRoots?: LinkedTestSandboxSourceRoots;
@@ -303,6 +305,7 @@ export declare const _testOnlyTestCommand: {
     buildPmContextMismatchHint: typeof buildPmContextMismatchHint;
     commandInvokesPmCli: typeof commandInvokesPmCli;
     commandInvokesPmTrackerReadCommand: typeof commandInvokesPmTrackerReadCommand;
+    commandUsesTestNameFilter: typeof commandUsesTestNameFilter;
     copyIntoSandboxIfPresent: typeof copyIntoSandboxIfPresent;
     countLinkedTestItemFiles: typeof countLinkedTestItemFiles;
     ensureScope: typeof ensureScope;

package/dist/sdk/test/execution.js

@@ -4,7 +4,7 @@
  * Implements the pm test 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]="99ce92bb-ed45-5327-b148-b5bb26a0bf05")}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]="de5bc6bf-fe31-5643-a809-ee9ca52aac48")}catch(e){}}();
 import { assertInitializedTracker } from "../environment/tracker-preflight.js";
 import { spawn } from "node:child_process";
 import { cp, mkdir, mkdtemp, open, readdir, rm, symlink, } from "node:fs/promises";
@@ -817,9 +817,17 @@ async function runLinkedTestCommand(command, timeoutMs, env, progressContext, pr
         try {
             child = createLinkedTestChild(command, env, stdoutHandle.fd, stderrHandle.fd, cwd);
         }
-        finally {
+        catch (error) {
             await Promise.all([stdoutHandle.close(), stderrHandle.close()]);
+            throw error;
         }
+        const childClose = waitForLinkedTestChildClose(child);
+        let spawnError;
+        /* c8 ignore next 5 -- shell spawn error callbacks are non-deterministic across platforms. */
+        child.on("error", (error) => {
+            spawnError = error.message;
+        });
+        await Promise.all([stdoutHandle.close(), stderrHandle.close()]);
         closeLinkedTestStdin(child);
         const timers = {
             heartbeat: beginLinkedTestProgress(progressContext, progressMode),
@@ -828,18 +836,13 @@ async function runLinkedTestCommand(command, timeoutMs, env, progressContext, pr
         };
         const requestTermination = createLinkedTestTerminationRequester(child, timers);
         let timedOut = false;
-        let spawnError;
-        /* c8 ignore next 5 -- shell spawn error callbacks are non-deterministic across platforms. */
-        child.on("error", (error) => {
-            spawnError = error.message;
-        });
         /* c8 ignore next 4 -- callback scheduling timing is non-deterministic under coverage instrumentation. */
         timers.timedOutTimer = setTimeout(() => {
             timedOut = true;
             void requestTermination();
         }, timeoutMs);
         timers.timedOutTimer.unref?.();
-        const { code, signal } = await waitForLinkedTestChildClose(child);
+        const { code, signal } = await childClose;
         clearLinkedTestTimers(timers);
         const [stdout, stderr] = await Promise.all([
             readLinkedTestCapture(stdoutPath),
@@ -1285,16 +1288,45 @@ const EMPTY_LINKED_TEST_RUN_PATTERNS = [
     { code: "no_tests_found", regex: /\bNo tests found\b/i },
     { code: "no_matching_tests", regex: /\bNo matching tests?\b/i },
     { code: "collected_zero_items", regex: /\bcollected 0 items?\b/i },
+    {
+        code: "reported_zero_passes",
+        regex: /(?:^\s*(?:#|ℹ)?\s*tests\s+0\s*$[\s\S]*^\s*(?:#|ℹ)?\s*pass\s+0\s*$|^\s*(?:#|ℹ)?\s*pass\s+0\s*$[\s\S]*^\s*(?:#|ℹ)?\s*tests\s+0\s*$)/imu,
+    },
+    {
+        code: "reported_zero_tests",
+        regex: /^\s*(?:#|ℹ)?\s*tests\s+0\s*$/imu,
+    },
+];
+const POSITIVE_LINKED_TEST_RUN_PATTERNS = [
+    /^\s*(?:#|ℹ)?\s*tests\s+[1-9]\d*\s*$/imu,
+    /^\s*(?:#|ℹ)?\s*pass\s+[1-9]\d*\s*$/imu,
+    /\bTests?\s+[1-9]\d*\s+passed\b/iu,
+    /\b[1-9]\d*\s+passed\b/iu,
+    /\bTests:\s+(?:.*\b)?[1-9]\d*\s+passed\b/iu,
 ];
 function detectEmptyLinkedTestRun(stdout, stderr) {
     const combined = `${stdout}\n${stderr}`;
     for (const pattern of EMPTY_LINKED_TEST_RUN_PATTERNS) {
         if (pattern.regex.test(combined)) {
-            return pattern.code;
+            return { code: pattern.code };
         }
     }
     return null;
 }
+/** Return whether runner output contains a recognized positive executed-test receipt. */
+function hasPositiveLinkedTestRunReceipt(stdout, stderr) {
+    const combined = `${stdout}\n${stderr}`;
+    return POSITIVE_LINKED_TEST_RUN_PATTERNS.some((pattern) => pattern.test(combined));
+}
+/** Return whether a linked command applies a runner-level test-name filter that must match at least one test. */
+function commandUsesTestNameFilter(command) {
+    const normalized = normalizeCommandForValidation(command);
+    if (/(?:^|\s)(?:--test-name-pattern|--testnamepattern)(?:=|\s)/u.test(normalized)) {
+        return true;
+    }
+    return splitNormalizedCommandSegments(normalized).some((segment) => /(?:^|\s)-t(?:=|\s)/u.test(segment) &&
+        segmentInvokesUnsafeDirectTestRunner(segment));
+}
 function createLinkedTestSandboxLayout(sandboxRoot) {
     return {
         root: sandboxRoot,
@@ -1625,8 +1657,8 @@ function buildLinkedTestEmptyRunResult(params) {
         execution_context: params.executionContext,
         stdout: params.execution.stdout,
         stderr: params.execution.stderr,
-        error: `Linked test reported an empty test run (${params.emptyRunSignal}) while --fail-on-empty-test-run is enabled. ` +
-            "Update test selection or disable --fail-on-empty-test-run for this run.",
+        error: `Linked test reported an empty test run (${params.emptyRunSignal.code}). ` +
+            "Update the test selection so at least one test executes; unfiltered commands may opt out by omitting --fail-on-empty-test-run.",
     };
 }
 function buildLinkedTestCommandFailureResult(params) {
@@ -1643,11 +1675,19 @@ function buildLinkedTestCommandFailureResult(params) {
     };
 }
 function buildLinkedTestPassedExecutionResult(params) {
-    if (params.options?.failOnEmptyTestRun === true) {
+    if (params.options?.failOnEmptyTestRun === true ||
+        commandUsesTestNameFilter(params.linkedTest.command ?? "")) {
         const emptyRunSignal = detectEmptyLinkedTestRun(params.execution.stdout, params.execution.stderr);
         if (emptyRunSignal) {
             return buildLinkedTestEmptyRunResult({ ...params, emptyRunSignal });
         }
+        if (commandUsesTestNameFilter(params.linkedTest.command ?? "") &&
+            !hasPositiveLinkedTestRunReceipt(params.execution.stdout, params.execution.stderr)) {
+            return buildLinkedTestEmptyRunResult({
+                ...params,
+                emptyRunSignal: { code: "missing_positive_execution_receipt" },
+            });
+        }
     }
     const assertionFailures = evaluateLinkedTestAssertions(params.linkedTest, params.execution.stdout, params.execution.stderr);
     if (assertionFailures.length > 0) {
@@ -2129,6 +2169,7 @@ export const _testOnlyTestCommand = {
     buildPmContextMismatchHint,
     commandInvokesPmCli,
     commandInvokesPmTrackerReadCommand,
+    commandUsesTestNameFilter,
     copyIntoSandboxIfPresent,
     countLinkedTestItemFiles,
     ensureScope,
@@ -2160,4 +2201,4 @@ export const _testOnlyTestCommand = {
     summarizeRunResultStatuses,
 };
 //# sourceMappingURL=execution.js.map
-//# debugId=99ce92bb-ed45-5327-b148-b5bb26a0bf05
+//# debugId=de5bc6bf-fe31-5643-a809-ee9ca52aac48

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/CONTEXT_RECOVERY_PRIMITIVES.md

@@ -0,0 +1,67 @@
+# Context Integrity and Recovery Primitives
+
+Tracker: [pm-hu92i3](../.agents/pm/issues/pm-hu92i3.toon), [pm-nc94mk](../.agents/pm/issues/pm-nc94mk.toon), [pm-xrjy8o](../.agents/pm/issues/pm-xrjy8o.toon), [pm-f60039](../.agents/pm/issues/pm-f60039.toon), [pm-2qahia](../.agents/pm/issues/pm-2qahia.toon), [pm-z1z96w](../.agents/pm/issues/pm-z1z96w.toon), [pm-yhle2e](../.agents/pm/issues/pm-yhle2e.toon), [pm-t7wl00](../.agents/pm/issues/pm-t7wl00.toon), [pm-hiqlkh](../.agents/pm/issues/pm-hiqlkh.toon), [pm-ntnv4k](../.agents/pm/issues/pm-ntnv4k.toon), [pm-sxg7wl](../.agents/pm/issues/pm-sxg7wl.toon), [pm-xspd](../.agents/pm/chores/pm-xspd.toon)
+
+`project management = context management`: a successful command is useful only when the context it records and later returns is truthful, lossless, and actionable. These SDK-owned primitives are shared by the CLI and package integrations.
+
+## Lossless structured values
+
+CSV-style structured metadata preserves whitespace following literal commas. An escaped comma (`\,`) is consumed as one literal comma. Prefer quoted or structured forms when a value itself contains delimiters:
+
+```bash
+pm files pm-123 --add 'path="docs/name,with-comma.md",scope=project'
+pm update pm-123 --annotation 'key=summary,value=Alpha\, beta'
+```
+
+Bare comma-separated file and documentation paths are refused because the CLI cannot know whether the comma separates two paths or belongs to one filename. Repeat the option for multiple values. A linked-test command followed by a structured tuple, such as `command,scope=project`, is refused for the same reason; use `command=<value>,scope=project`.
+
+## Linked path write receipts
+
+`pm files --add`, `pm docs --add`, and path migrations validate the resulting paths when the mutation changes stored metadata. The result includes `validation.missing_paths`, `validation.non_file_paths`, and `validation.remote_references`. Missing local paths remain permitted as deliberate forward references, but they are visible in the write receipt instead of becoming silent durable context.
+
+## Executed-test evidence
+
+A linked runner command carrying a name filter must execute at least one test. An explicit zero-test runner summary is classified as `failure_category: empty_run`, even when the process exits zero. A zero-pass count alone is not an empty-run receipt when the runner reports a positive test count. Filtered commands without either positive execution evidence or an explicit zero-test signal fail closed as `missing_positive_execution_receipt`; unfiltered commands retain the explicit `--fail-on-empty-test-run` policy.
+
+## External blockers
+
+URL and named external locators are not dangling local item identifiers. Validation excludes them from local dangling-reference remediation, and graph assembly materializes them as external predecessor nodes. Until an integration resolves the remote state, `pm next` retains the blocker and reports:
+
+- `external: true`
+- `blocked_since`: the holder's conservative last-mutation timestamp
+- `resolver: null`
+
+This makes an unverifiable or stale dependency visible without suggesting destructive removal.
+
+Packages can add provider-specific resolution without coupling core to GitHub, Jira, Linear, or another service. Register an `ExternalDependencyResolver` through the public SDK and dispose it when the package deactivates. The SDK normalizes lifecycle state to `open`, `closed`, or `unknown`; caps remote titles at 240 characters and evidence locators at 2,048 characters; records `checked_at` plus the registered resolver name; and treats only trusted `closed` evidence as resolved. Provider errors and unsupported locators fail closed so another registered resolver can handle the reference or the blocker remains explicitly unverifiable.
+
+## Package-manager receipt compatibility
+
+The npm package source accepts both documented receipt families:
+
+- npm 11: an array of package receipt objects
+- npm 12: an object keyed by package name
+
+When multiple entries exist, the SDK selects the requested package by key or `name`. A well-formed but unsupported or ambiguous JSON value fails with `npm_pack_json_shape_unsupported`; filename-only fallback is used only for genuinely non-JSON legacy output.
+
+## History and merge recovery
+
+History hash capability 3 distinguishes the current canonical writer surface from older epoch-2 writers while retaining readers for epochs 1 and 2. An unsupported epoch is version skew, not permission to reinterpret or silently normalize history.
+
+Health keeps the metadata-only cache path for clean history streams. A cached hash mismatch, chain mismatch, or writer-version skew is only a candidate: health rereads canonical item sources and verifies stream content hashes before reporting corruption. The `history_drift` details expose `cache_confirmation` candidate, confirmed, and resolved-false-positive item sets, while `cache_hit_verification: metadata_then_content_hash` identifies the authoritative fallback. Drift-cache envelopes also carry the current item-hash capability, so a runtime with incompatible hash semantics rebuilds the cache instead of trusting it.
+
+Merge reconciliation may consume a durable hash-only receipt without `--force` only when its canonical item path, complete declared-field set, and every merged-value hash exactly match the current item snapshot. Raw discarded values remain clone-local. Any incomplete or mismatched proof fails closed.
+
+## Strict-create recovery
+
+When strict governance requires a collection, the recovery bundle lists the truthful empty declaration before an example that adds metadata:
+
+```text
+--clear-deps, --dep, --create-mode progressive
+```
+
+The same contract covers comments, docs, events, files, learnings, notes, reminders, tests, and type options. Agents should never invent an edge or evidence row merely to satisfy a required-field gate.
+
+## Duplication gates
+
+`pnpm lint:duplicates` runs both the repository-wide clone gate and a lower-line production-source profile. The source profile covers `src`, `packages`, and `plugins` so a compact clone reported by hosted analysis cannot hide below the broader repository threshold.

package/docs/MERGE_SAFETY.md

@@ -3,7 +3,9 @@
 Tracked by [pm-wc1r](../.agents/pm/features/pm-wc1r.toon), with the integrity and concurrency fixes [pm-9q2t](../.agents/pm/issues/pm-9q2t.toon), [pm-cxyv](../.agents/pm/issues/pm-cxyv.toon), [pm-gpo7](../.agents/pm/issues/pm-gpo7.toon), [pm-m3nl](../.agents/pm/issues/pm-m3nl.toon), [pm-wwfd](../.agents/pm/issues/pm-wwfd.toon), and [pm-xdn6](../.agents/pm/issues/pm-xdn6.toon). Fresh-init fence ownership is tracked by [pm-1w3ljt](../.agents/pm/issues/pm-1w3ljt.toon); runtime-cache index governance by [pm-hous](../.agents/pm/issues/pm-hous.toon); local allocation safety by [pm-khdq](../.agents/pm/issues/pm-khdq.toon); fence-coverage completeness and drift detection by [pm-i4fx](../.agents/pm/issues/pm-i4fx.toon); package-defined item coverage by [pm-5rexki](../.agents/pm/issues/pm-5rexki.toon); non-item JSON coverage by [pm-gjicmx](../.agents/pm/issues/pm-gjicmx.toon); portable driver identity by [pm-w91mvg](../.agents/pm/issues/pm-w91mvg.toon); pending receipt validation by [pm-ysqb6n](../.agents/pm/issues/pm-ysqb6n.toon); receipt classification by [pm-jtwsct](../.agents/pm/issues/pm-jtwsct.toon); direction-independent item conflict selection by [pm-dlx7v7](../.agents/pm/issues/pm-dlx7v7.toon); corrected reconciliation guidance by [pm-lwmstb](../.agents/pm/issues/pm-lwmstb.toon); cross-branch id collision safety by [pm-pibw](../.agents/pm/issues/pm-pibw.toon); auditable merge history by [pm-9j2r3b](../.agents/pm/tasks/pm-9j2r3b.toon); durable conflict decisions by [pm-rh98vo](../.agents/pm/issues/pm-rh98vo.toon); continuous conformance by [pm-76dnfg](../.agents/pm/tasks/pm-76dnfg.toon); workspace-wide CI enforcement by [pm-pdr8t1](../.agents/pm/tasks/pm-pdr8t1.toon); post-merge reconciliation by [pm-mfkv92](../.agents/pm/issues/pm-mfkv92.toon); linked-command execution trust by [pm-ed28wi](../.agents/pm/issues/pm-ed28wi.toon); this repository's own adoption by [pm-iwsj](../.agents/pm/chores/pm-iwsj.toon).
 
 Lossless receipt health gating is tracked by
-[pm-baksix](../.agents/pm/issues/pm-baksix.toon).
+[pm-baksix](../.agents/pm/issues/pm-baksix.toon), and executable remediation
+that performs settlement is tracked by
+[pm-r0p3at](../.agents/pm/issues/pm-r0p3at.toon).
 
 pm stores project context as reviewable repository files. Concurrent agents can therefore use ordinary branches and worktrees, but tracker artifacts need semantic merge behavior: raw line merging cannot preserve TOON collection counts, JSON object structure, or append-only history hash chains.
 
@@ -116,7 +118,7 @@ After every branch merge that touches `.agents/pm`, run:
 ```bash
 pm merge reconcile --dry-run --json
 pm merge reconcile --message "Reconcile merged tracker histories" --json
-# Required only after every discarded field has been reviewed or re-applied:
+# Required only to accept a receipt that lacks qualifying exact hash proof:
 pm merge reconcile --force --message "Accept reviewed merge decisions" --json
 ```
 
@@ -125,10 +127,10 @@ Lossless receipts do not become discarded-value decisions and reconcile without
 `--force`, but `pm health` reports `merge_receipts_pending:<n>` and remains
 non-green until the apply pass settles them. `pm history-repair` cannot clear
 that receipt finding. When a drifted item also has a pending receipt, the
-`history_drift` remediation map prioritizes `pm merge reconcile --dry-run` only
+`history_drift` remediation map prioritizes `pm merge reconcile` only
 when canonical item path, changed-field, and merged-value hash evidence all
 attribute that finding to one or more receipts loaded from the clone-local Git
-evidence store. Every field declared by each receipt must match its current merged-value
+evidence store or the authoritative durable receipt store. Every field declared by each receipt must match its current merged-value
 hash, even when only a subset appears in the history reconciliation diff.
 Disjoint valid receipts may collectively cover a multi-field reconciliation;
 the audit and settlement then retain every individually proven receipt id.
@@ -136,22 +138,33 @@ Serialized source claims are ignored. Receipt readers validate the complete
 bounded schema, safe identifiers, filename and item-path identity, timestamps,
 and bounded decision structure before a sidecar enters health or
 reconciliation. Reads use size-preflighted, no-follow regular-file descriptors;
-durable decisions must retain hash-only values. Legacy or durable-only receipts,
+durable decisions must retain hash-only values. Qualifying durable-only receipts
+are reloaded from the authoritative store and accepted only after exact canonical
+item path, declared-field, and merged-value hash verification. Legacy receipts,
 receipts whose declared fields disagree with their hashes, same-item tampering,
 and drift on unrelated items fail closed to the normal `pm history-repair`
-guidance. Health indexes clone-local evidence once by item and reconciliation
+guidance. Health indexes authoritative evidence once by item and reconciliation
 uses the same per-item groups with a fixed receipt-only worker pool, so committed
 sidecars cannot amplify drift scans into unbounded parallel repair work.
+The machine-executable remediation names the apply command because `--dry-run`
+returns a successful preview without changing the red health state. Operators
+may still run the documented dry-run first; agents that execute the remediation
+field verbatim perform the settlement instead of entering a successful no-op
+loop.
 Apply-mode reconciliation repeats the same proof against the exact
 item snapshot used by the audited history rewrite. The audit event and
 settlement include only the individually proven receipt id, so one valid receipt
 cannot authorize an untrusted same-item sibling. Failed or unproven receipts
 remain pending unless the coordinator explicitly reviews and supplies `--force`.
 Receipts with discarded scalar values retain the distinct
-`merge_decisions_unreviewed:<n>` finding, and the apply pass refuses them unless
-the coordinator explicitly supplies `--force` after review. This prevents a
-routine history repair from hiding unfinished reconciliation or silently
-accepting data loss.
+`merge_decisions_unreviewed:<n>` finding. Matching authoritative hash proof
+allows those receipts to settle without `--force`; without qualifying proof,
+the apply pass refuses them until the coordinator explicitly supplies `--force`
+after review. The `history_drift_merge_receipt` remediation may therefore emit
+an unforced apply command that clears `merge_decisions_unreviewed` when the
+receipt proves the exact current merged values. This prevents routine repair
+from hiding unfinished reconciliation while avoiding redundant force for an
+already-proven canonical snapshot.
 It exits nonzero while either merge-critical validation check is non-green, so
 CI and explicit post-merge hooks cannot approve unresolved receipts or drift.
 The apply pass uses the audited history rewrite boundary to append a