@unbrained/pm-cli 2026.8.7 → 2026.8.9

package/dist/sdk/merge/install.d.ts

@@ -1,5 +1,6 @@
 import type { GlobalOptions } from "../../core/shared/command-types.js";
 import { readSettings } from "../../core/store/settings.js";
+import { resolveSourceContextWritePolicy } from "../environment/source-context.js";
 /** Opening marker for the pm-owned merge-driver `.gitattributes` block. */
 export declare const PM_GITATTRIBUTES_START = "# pm-cli:merge-drivers:start";
 /** Closing marker for the pm-owned merge-driver `.gitattributes` block. */
@@ -37,6 +38,26 @@ export interface MergeInstallResult {
     /** ISO 8601 timestamp recording when generated occurred. */
     generated_at: string;
 }
+/** Resolved tracker and workspace selection for one merge-install invocation. */
+export interface MergeInstallContextResolution {
+    /** Tracker root selected without performing filesystem writes. */
+    pm_root: string;
+    /** Starting path used to discover the enclosing Git workspace. */
+    workspace_start: string;
+    /** Whether complete inherited source coordinates were present. */
+    source_coordinates_available: boolean;
+    /** Whether inherited source coordinates were selected. */
+    source_context_selected: boolean;
+    /** Source-coordinate write policy active for the invocation. */
+    source_policy: ReturnType<typeof resolveSourceContextWritePolicy>;
+}
+/** Resolve explicit, inherited-source, and current-workspace precedence without I/O. */
+export declare function resolveMergeInstallContext(options: {
+    cwd: string;
+    explicitPath?: string;
+    dryRun: boolean;
+    environment: Readonly<Record<string, string | undefined>>;
+}): MergeInstallContextResolution;
 /** Result of auditing clone-local driver definitions behind a committed fence. */
 export interface MergeDriverConfigurationAuditResult {
     /** Whether every required driver definition exactly matches this installation. */

package/dist/sdk/merge/install.js

@@ -8,7 +8,7 @@
  * mutations refresh the fenced block automatically once it is installed.
  */
 
-!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]="a250384a-0279-5d01-ade4-f64be3119ed9")}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]="cb6dc38e-b317-5739-83ff-cf459b8bb31e")}catch(e){}}();
 import { readFile, realpath, writeFile } from "node:fs/promises";
 import { execFile } from "node:child_process";
 import path from "node:path";
@@ -24,6 +24,7 @@ import { nowIso } from "../../core/shared/time.js";
 import { getSettingsPath, resolvePmRoot } from "../../core/store/paths.js";
 import { readSettings, resolveGovernanceKnobs, } from "../../core/store/settings.js";
 import { isPathOutsideRoot } from "../workspace.js";
+import { resolveSourceContextWritePolicy } from "../environment/source-context.js";
 const execFileAsync = promisify(execFile);
 /** Opening marker for the pm-owned merge-driver `.gitattributes` block. */
 export const PM_GITATTRIBUTES_START = "# pm-cli:merge-drivers:start";
@@ -80,6 +81,45 @@ const MERGE_DRIVER_DEFINITIONS = [
         itemPath: undefined,
     },
 ];
+/** Resolve explicit, inherited-source, and current-workspace precedence without I/O. */
+export function resolveMergeInstallContext(options) {
+    const explicitPath = options.explicitPath?.trim();
+    const sourceWorkspaceRoot = options.environment.PM_SOURCE_WORKSPACE_ROOT?.trim();
+    const sourcePmRoot = options.environment.PM_SOURCE_PM_PATH?.trim();
+    const sourcePolicy = resolveSourceContextWritePolicy(options.environment);
+    const sourceCoordinatesAvailable = Boolean(sourceWorkspaceRoot && sourcePmRoot);
+    const sourceContextSelected = explicitPath === undefined &&
+        sourceCoordinatesAvailable &&
+        (options.dryRun || sourcePolicy.source_writes_allowed);
+    if (explicitPath !== undefined) {
+        const pmRoot = resolvePmRoot(options.cwd, explicitPath);
+        return {
+            pm_root: pmRoot,
+            workspace_start: pmRoot,
+            source_coordinates_available: sourceCoordinatesAvailable,
+            source_context_selected: false,
+            source_policy: sourcePolicy,
+        };
+    }
+    if (sourceContextSelected) {
+        return {
+            pm_root: path.resolve(sourcePmRoot),
+            workspace_start: path.resolve(sourceWorkspaceRoot),
+            source_coordinates_available: true,
+            source_context_selected: true,
+            source_policy: sourcePolicy,
+        };
+    }
+    return {
+        pm_root: sourceCoordinatesAvailable
+            ? resolvePmRoot(options.cwd, ".agents/pm")
+            : resolvePmRoot(options.cwd),
+        workspace_start: options.cwd,
+        source_coordinates_available: sourceCoordinatesAvailable,
+        source_context_selected: false,
+        source_policy: sourcePolicy,
+    };
+}
 /** Resolve the enclosing Git worktree root or return null outside Git. */
 export async function findGitWorkspaceRoot(cwd) {
     try {
@@ -393,27 +433,17 @@ export async function refreshMergeAttributeFenceIfInstalled(pmRoot) {
  * per checkout). Requires an initialized tracker and a git repository.
  */
 export async function runMergeInstall(options, global) {
-    const explicitPath = global.path?.trim();
-    const sourceWorkspaceRoot = process.env.PM_SOURCE_WORKSPACE_ROOT?.trim();
-    const sourcePmRoot = process.env.PM_SOURCE_PM_PATH?.trim();
-    const usesLinkedTestSourceContext = explicitPath === undefined &&
-        sourceWorkspaceRoot !== undefined &&
-        sourceWorkspaceRoot.length > 0 &&
-        sourcePmRoot !== undefined &&
-        sourcePmRoot.length > 0;
-    const pmRoot = explicitPath !== undefined
-        ? resolvePmRoot(process.cwd(), explicitPath)
-        : usesLinkedTestSourceContext
-            ? path.resolve(sourcePmRoot)
-            : resolvePmRoot(process.cwd());
+    const context = resolveMergeInstallContext({
+        cwd: process.cwd(),
+        explicitPath: global.path,
+        dryRun: options.dryRun === true,
+        environment: process.env,
+    });
+    const pmRoot = context.pm_root;
     if (!(await pathExists(getSettingsPath(pmRoot)))) {
         throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
     }
-    const workspaceRoot = await resolveGitWorkspaceRoot(explicitPath !== undefined
-        ? pmRoot
-        : usesLinkedTestSourceContext
-            ? path.resolve(sourceWorkspaceRoot)
-            : process.cwd());
+    const workspaceRoot = await resolveGitWorkspaceRoot(context.workspace_start);
     return installMergeFence({
         pmRoot,
         workspaceRoot,
@@ -511,11 +541,11 @@ export async function installMergeFence(options) {
         guidance: [
             "Commit .gitattributes so every branch and collaborator shares the merge mapping.",
             'git config is per-clone: each collaborator (and each fresh worktree/clone) runs "pm merge install" once.',
-            'After merging branches, run "pm validate" and, if history drift is reported, "pm history-repair --all" to reconcile item state with merged history.',
+            'After merging branches, run "pm merge reconcile --dry-run" to inspect the complete receipt and history repair, then apply "pm merge reconcile"; use --force only after explicitly accepting any discarded values.',
             "Custom item types registered later refresh this fence automatically (pm schema add-type/remove-type); rerun pm merge install only after out-of-band type-folder edits.",
         ],
         generated_at: nowIso(),
     };
 }
 //# sourceMappingURL=install.js.map
-//# debugId=a250384a-0279-5d01-ade4-f64be3119ed9
+//# debugId=cb6dc38e-b317-5739-83ff-cf459b8bb31e

package/dist/sdk/merge/receipts.d.ts

@@ -11,6 +11,8 @@ export interface MergeDecisionReceipt {
     item_id: string;
     /** Preferred side used for scalar conflicts. */
     preferred: MergePreferredSide;
+    /** Scalar-conflict selection contract used by the item driver. */
+    conflict_resolution: "preferred_side" | "stable_value_order";
     /** Fields selected cleanly from the other branch. */
     fields_from_theirs: string[];
     /** Collections combined from both branches. */
@@ -40,6 +42,8 @@ export interface MergeDecisionReceiptSummary {
     union_fields: string[];
     /** Preferred side used for scalar conflicts. */
     preferred: MergePreferredSide;
+    /** Scalar-conflict selection contract used by the item driver. */
+    conflict_resolution: "preferred_side" | "stable_value_order";
     /** Hashes proving the retained and discarded values without publishing them. */
     decisions: Array<{
         field: string;
@@ -65,14 +69,23 @@ export declare function writeMergeReceipt(params: {
     cwd: string;
     itemPath: string;
     preferred: MergePreferredSide;
+    conflictResolution?: "preferred_side" | "stable_value_order";
     fieldsFromTheirs: string[];
     unionFields: string[];
     decisions: ItemMergeConflictDecision[];
 }): Promise<MergeDecisionReceipt | null>;
-/** Read all clone-local receipts, optionally including reconciled history. */
+/** Read clone-local receipts with explicit reconciled/lossless classification controls. */
 export declare function listMergeReceipts(cwd: string, options?: {
     includeReconciled?: boolean;
+    includeLossless?: boolean;
 }): Promise<MergeDecisionReceipt[]>;
+/** Split merge provenance into receipts with discarded values and receipts whose composition was lossless. */
+export declare function partitionMergeReceipts(receipts: MergeDecisionReceipt[]): {
+    /** Receipts that require an explicit decision because at least one competing scalar value was discarded. */
+    pendingDecisions: MergeDecisionReceipt[];
+    /** Receipts that record provenance without a discarded competing scalar value. */
+    lossless: MergeDecisionReceipt[];
+};
 /** Mark a receipt as represented by a committed merge history event. */
 export declare function markMergeReceiptReconciled(cwd: string, receipt: MergeDecisionReceipt): Promise<void>;
 /** Report pending or historical clone-local merge decisions. */

package/dist/sdk/merge/receipts.js

@@ -7,7 +7,7 @@
  * value for the coordinator that performed the merge.
  */
 
-!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]="c4721ede-e557-5720-a9c2-4b2b344cc6cc")}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]="3ccde5c2-f743-52ac-a3fd-9590f720e1b3")}catch(e){}}();
 import { execFile } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { readdir, readFile } from "node:fs/promises";
@@ -19,7 +19,12 @@ import { nowIso } from "../../core/shared/time.js";
 const execFileAsync = promisify(execFile);
 async function resolveReceiptDirectory(cwd) {
     try {
-        const { stdout } = await execFileAsync("git", ["rev-parse", "--path-format=absolute", "--git-path", "pm-merge-receipts"], { cwd, encoding: "utf8", windowsHide: true, timeout: 10_000 });
+        const { stdout } = await execFileAsync("git", [
+            "rev-parse",
+            "--path-format=absolute",
+            "--git-path",
+            "pm-merge-receipts",
+        ], { cwd, encoding: "utf8", windowsHide: true, timeout: 10_000 });
         return stdout.trim();
     }
     catch {
@@ -39,6 +44,7 @@ export function summarizeMergeReceipt(receipt) {
         fields_from_theirs: receipt.fields_from_theirs,
         union_fields: receipt.union_fields,
         preferred: receipt.preferred,
+        conflict_resolution: receipt.conflict_resolution,
         decisions: receipt.decisions.map((decision) => ({
             field: decision.field,
             retained_hash: sha256Hex(stableStringify(decision.retained)),
@@ -65,6 +71,7 @@ export async function writeMergeReceipt(params) {
         item_path: itemPath.replaceAll("\\", "/"),
         item_id: itemId,
         preferred: params.preferred,
+        conflict_resolution: params.conflictResolution ?? "preferred_side",
         fields_from_theirs: [...params.fieldsFromTheirs],
         union_fields: [...params.unionFields],
         decisions: structuredClone(params.decisions),
@@ -75,7 +82,7 @@ export async function writeMergeReceipt(params) {
     await writeFileAtomic(path.join(directory, receiptFileName(receipt.id)), `${JSON.stringify(receipt, null, 2)}\n`);
     return receipt;
 }
-/** Read all clone-local receipts, optionally including reconciled history. */
+/** Read clone-local receipts with explicit reconciled/lossless classification controls. */
 export async function listMergeReceipts(cwd, options = {}) {
     const directory = await resolveReceiptDirectory(cwd);
     if (directory === null || !(await pathExists(directory))) {
@@ -95,9 +102,16 @@ export async function listMergeReceipts(cwd, options = {}) {
         }
         try {
             const parsed = JSON.parse(await readFile(path.join(directory, name), "utf8"));
-            if (parsed.version === 1 &&
-                (options.includeReconciled || parsed.state === "pending")) {
-                receipts.push(parsed);
+            const normalizedReceipt = {
+                ...parsed,
+                conflict_resolution: parsed.conflict_resolution ?? "preferred_side",
+            };
+            if (normalizedReceipt.version === 1 &&
+                (options.includeReconciled || normalizedReceipt.state === "pending") &&
+                (options.includeLossless !== false ||
+                    (Array.isArray(normalizedReceipt.decisions) &&
+                        normalizedReceipt.decisions.length > 0))) {
+                receipts.push(normalizedReceipt);
             }
         }
         catch {
@@ -107,6 +121,17 @@ export async function listMergeReceipts(cwd, options = {}) {
     }
     return receipts.sort((left, right) => left.created_at.localeCompare(right.created_at));
 }
+/** Split merge provenance into receipts with discarded values and receipts whose composition was lossless. */
+export function partitionMergeReceipts(receipts) {
+    const pendingDecisions = [];
+    const lossless = [];
+    for (const receipt of receipts) {
+        (Array.isArray(receipt.decisions) && receipt.decisions.length > 0
+            ? pendingDecisions
+            : lossless).push(receipt);
+    }
+    return { pendingDecisions, lossless };
+}
 /** Mark a receipt as represented by a committed merge history event. */
 export async function markMergeReceiptReconciled(cwd, receipt) {
     const directory = await resolveReceiptDirectory(cwd);
@@ -117,7 +142,10 @@ export async function markMergeReceiptReconciled(cwd, receipt) {
 }
 /** Report pending or historical clone-local merge decisions. */
 export async function runMergeReceiptReport(options) {
-    const receipts = await listMergeReceipts(options.cwd ?? process.cwd(), options);
+    const receipts = await listMergeReceipts(options.cwd ?? process.cwd(), {
+        ...options,
+        includeLossless: true,
+    });
     return {
         ok: true,
         count: receipts.length,
@@ -126,4 +154,4 @@ export async function runMergeReceiptReport(options) {
     };
 }
 //# sourceMappingURL=receipts.js.map
-//# debugId=c4721ede-e557-5720-a9c2-4b2b344cc6cc
+//# debugId=3ccde5c2-f743-52ac-a3fd-9590f720e1b3

package/dist/sdk/merge/reconcile.js

@@ -1,8 +1,10 @@
 
-!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]="b2f34565-7664-5612-815d-949b8b1d4f90")}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]="c5620467-6c8c-5702-b742-57fba9e302c5")}catch(e){}}();
+import { EXIT_CODE } from "../../core/shared/constants.js";
+import { PmCliError } from "../../core/shared/errors.js";
 import { runHistoryRepair, runHistoryRepairAll, } from "../history-repair.js";
 import { runValidate } from "../governance/validate.js";
-import { listMergeReceipts, markMergeReceiptReconciled, summarizeMergeReceipt, } from "./receipts.js";
+import { listMergeReceipts, markMergeReceiptReconciled, partitionMergeReceipts, summarizeMergeReceipt, } from "./receipts.js";
 /**
  * Preview or apply post-merge history reconciliation and immediately validate
  * the two merge-critical invariants. The default remains explicit and safe:
@@ -11,7 +13,22 @@ import { listMergeReceipts, markMergeReceiptReconciled, summarizeMergeReceipt, }
  */
 export async function runMergeReconcile(options, global) {
     const dryRun = options.dryRun === true;
-    const pendingReceipts = await listMergeReceipts(process.cwd());
+    const pendingReceipts = await listMergeReceipts(process.cwd(), {
+        includeLossless: true,
+    });
+    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 = pendingReceipts.reduce((groups, receipt) => {
         (groups[receipt.item_id] ??= []).push(receipt);
         return groups;
@@ -106,4 +123,4 @@ export async function runMergeReconcile(options, global) {
     };
 }
 //# sourceMappingURL=reconcile.js.map
-//# debugId=b2f34565-7664-5612-815d-949b8b1d4f90
+//# debugId=c5620467-6c8c-5702-b742-57fba9e302c5

package/dist/sdk/merge/three-way.d.ts

@@ -100,6 +100,8 @@ export interface ItemDocumentMergeResult {
     conflict_decisions: ItemMergeConflictDecision[];
     /** Which side unresolvable conflicts were resolved toward. */
     preferred: MergePreferredSide;
+    /** Scalar-conflict selection contract used for this merge. */
+    conflict_resolution: "preferred_side" | "stable_value_order";
 }
 /**
  * Field-aware three-way merge of one tracker item document. Commutative
@@ -107,8 +109,8 @@ export interface ItemDocumentMergeResult {
  * concurrent appends never conflict; `updated_at` resolves to the latest
  * timestamp so disjoint-field edits never collide on the shared freshness
  * scalar; every other metadata field and the body use classic three-way
- * resolution. Unresolvable both-sides-changed conflicts are resolved toward
- * the preferred side but reported in `conflict_fields`, and the merged output
+ * resolution. Unresolvable both-sides-changed conflicts use the configured
+ * scalar policy but remain reported in `conflict_fields`, and the merged output
  * is always canonically serialized — count-prefixed TOON array headers are
  * recomputed, so the hand-resolution corruption class (stale `notes[N]`
  * headers) cannot be produced by this merge.
@@ -116,6 +118,8 @@ export interface ItemDocumentMergeResult {
 export declare function mergeItemDocuments(baseRaw: string, oursRaw: string, theirsRaw: string, options?: ItemDocumentFormatOptions & {
     /** Side that wins unresolvable conflicts (default "ours"). */
     preferred?: MergePreferredSide;
+    /** Direction-independent scalar selection used by the Git driver. */
+    conflictResolution?: "preferred_side" | "stable_value_order";
 }): ItemDocumentMergeResult;
 /** Documents the JSON document merge result payload exchanged by command, SDK, and package integrations. */
 export interface JsonDocumentMergeResult {

package/dist/sdk/merge/three-way.js

@@ -9,7 +9,7 @@
  * definition for multi-branch agent workflows.
  */
 
-!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]="582576df-8dbe-5f93-890b-5d872669dfe8")}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]="f6f04eec-0698-5e5b-a40e-de3a4be89f95")}catch(e){}}();
 import { historyEntriesToRaw, reanchorHistoryEntries, } from "../../core/history/replay.js";
 import { canonicalDocument, parseItemDocument, serializeItemDocument, } from "../../core/item/item-format.js";
 import { EXIT_CODE } from "../../core/shared/constants.js";
@@ -339,6 +339,18 @@ function mergeScalarThreeWay(base, ours, theirs, preferred) {
         conflict: true,
     };
 }
+function mergeItemScalarThreeWay(base, ours, theirs, preferred, conflictResolution) {
+    const outcome = mergeScalarThreeWay(base, ours, theirs, preferred);
+    if (!outcome.conflict || conflictResolution === "preferred_side") {
+        return outcome;
+    }
+    const retainTheirs = stableStringify(theirs).localeCompare(stableStringify(ours)) < 0;
+    return {
+        value: retainTheirs ? theirs : ours,
+        from_theirs: retainTheirs,
+        conflict: true,
+    };
+}
 function toMetadataRecord(document) {
     return { ...document.metadata };
 }
@@ -350,7 +362,7 @@ function parseItemMergeSide(raw, label, options) {
         throw new PmCliError(`Item merge input (${label}) is not a readable item document: ${String(error)}`, EXIT_CODE.GENERIC_FAILURE);
     }
 }
-function mergeItemMetadataRecords(baseRecord, oursRecord, theirsRecord, preferred) {
+function mergeItemMetadataRecords(baseRecord, oursRecord, theirsRecord, preferred, conflictResolution) {
     const unionFieldSet = new Set(ITEM_UNION_COLLECTION_FIELDS);
     const latestFieldSet = new Set(ITEM_LATEST_TIMESTAMP_FIELDS);
     const fieldNames = [
@@ -382,7 +394,7 @@ function mergeItemMetadataRecords(baseRecord, oursRecord, theirsRecord, preferre
             accumulator.merged[field] = latestTimestamp(oursValue, theirsValue);
             continue;
         }
-        const outcome = mergeScalarThreeWay(baseValue, oursValue, theirsValue, preferred);
+        const outcome = mergeItemScalarThreeWay(baseValue, oursValue, theirsValue, preferred, conflictResolution);
         if (outcome.value !== undefined) {
             accumulator.merged[field] = outcome.value;
         }
@@ -394,7 +406,7 @@ function mergeItemMetadataRecords(baseRecord, oursRecord, theirsRecord, preferre
                 ours: oursValue,
                 theirs: theirsValue,
                 retained: outcome.value,
-                discarded: preferred === "theirs" ? oursValue : theirsValue,
+                discarded: outcome.from_theirs ? oursValue : theirsValue,
             });
         }
         else if (outcome.from_theirs) {
@@ -409,14 +421,15 @@ function mergeItemMetadataRecords(baseRecord, oursRecord, theirsRecord, preferre
  * concurrent appends never conflict; `updated_at` resolves to the latest
  * timestamp so disjoint-field edits never collide on the shared freshness
  * scalar; every other metadata field and the body use classic three-way
- * resolution. Unresolvable both-sides-changed conflicts are resolved toward
- * the preferred side but reported in `conflict_fields`, and the merged output
+ * resolution. Unresolvable both-sides-changed conflicts use the configured
+ * scalar policy but remain reported in `conflict_fields`, and the merged output
  * is always canonically serialized — count-prefixed TOON array headers are
  * recomputed, so the hand-resolution corruption class (stale `notes[N]`
  * headers) cannot be produced by this merge.
  */
 export function mergeItemDocuments(baseRaw, oursRaw, theirsRaw, options = {}) {
     const preferred = options.preferred ?? "ours";
+    const conflictResolution = options.conflictResolution ?? "preferred_side";
     // An empty base means both branches created the file independently
     // (add/add); three-way falls back to treating every differing field as an
     // ours/theirs decision, which the scalar resolver already models.
@@ -429,8 +442,8 @@ export function mergeItemDocuments(baseRaw, oursRaw, theirsRaw, options = {}) {
         : {};
     const oursRecord = toMetadataRecord(ours);
     const theirsRecord = toMetadataRecord(theirs);
-    const { merged, conflictFields, fieldsFromTheirs, unionFields, conflictDecisions, } = mergeItemMetadataRecords(baseRecord, oursRecord, theirsRecord, preferred);
-    const bodyOutcome = mergeScalarThreeWay(hasBase ? base.body : "", ours.body, theirs.body, preferred);
+    const { merged, conflictFields, fieldsFromTheirs, unionFields, conflictDecisions, } = mergeItemMetadataRecords(baseRecord, oursRecord, theirsRecord, preferred, conflictResolution);
+    const bodyOutcome = mergeItemScalarThreeWay(hasBase ? base.body : "", ours.body, theirs.body, preferred, conflictResolution);
     if (bodyOutcome.conflict) {
         conflictFields.push("body");
         conflictDecisions.push({
@@ -439,7 +452,7 @@ export function mergeItemDocuments(baseRaw, oursRaw, theirsRaw, options = {}) {
             ours: ours.body,
             theirs: theirs.body,
             retained: bodyOutcome.value,
-            discarded: preferred === "theirs" ? ours.body : theirs.body,
+            discarded: bodyOutcome.from_theirs ? ours.body : theirs.body,
         });
     }
     else if (bodyOutcome.from_theirs) {
@@ -456,6 +469,7 @@ export function mergeItemDocuments(baseRaw, oursRaw, theirsRaw, options = {}) {
         union_fields: unionFields,
         conflict_decisions: conflictDecisions,
         preferred,
+        conflict_resolution: conflictResolution,
     };
 }
 function isPlainObject(value) {
@@ -611,4 +625,4 @@ export function mergeJsonDocuments(baseRaw, oursRaw, theirsRaw, options = {}) {
     };
 }
 //# sourceMappingURL=three-way.js.map
-//# debugId=582576df-8dbe-5f93-890b-5d872669dfe8
+//# debugId=f6f04eec-0698-5e5b-a40e-de3a4be89f95

package/dist/sdk/notes.d.ts

@@ -5,6 +5,7 @@
  */
 import { type GlobalOptions } from "./runtime-primitives.js";
 import type { LogNote } from "../types/index.js";
+import { type AnnotationMutationReceipt, type AnnotationOmissionReceipt } from "./annotations.js";
 /** Documents the notes command options payload exchanged by command, SDK, and package integrations. */
 export interface NotesCommandOptions {
     /** Value that configures or reports add for this contract. */
@@ -27,6 +28,8 @@ export interface NotesCommandOptions {
     eventType?: string;
     /** Include total, returned, and truncation metadata. */
     includeMeta?: boolean;
+    /** Return complete note history after a mutation instead of a bounded receipt. */
+    fullHistory?: boolean;
     /** Value that configures or reports author for this contract. */
     author?: string;
     /** Human-readable explanation suitable for logs and agent-facing output. */
@@ -52,6 +55,10 @@ export interface NotesResult {
     limit?: number;
     /** Number of structured context events in the returned projection. */
     structured_event_count?: number;
+    /** Mutation identity when this result changed the collection. */
+    mutation_receipt?: AnnotationMutationReceipt;
+    /** Declares whether older notes were withheld from a mutation response. */
+    omission_receipt?: AnnotationOmissionReceipt;
 }
 /** 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]="973fe868-d08e-5a45-83c5-b7ecb959f680")}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]="ebd9f151-593f-5081-97da-d78f83de4914")}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=973fe868-d08e-5a45-83c5-b7ecb959f680
+//# debugId=ebd9f151-593f-5081-97da-d78f83de4914

package/dist/sdk/query/get.d.ts

@@ -24,6 +24,17 @@ type GetItemProjection = Partial<ItemMetadata> & {
     notes_count?: number;
     /** Number of linked tests omitted by a token-bounded projection. */
     tests_count?: number;
+    /** Stable cardinalities for every collection mutation surface. */
+    collection_counts?: Readonly<{
+        comments: number;
+        notes: number;
+        learnings: number;
+        files: number;
+        tests: number;
+        docs: number;
+        reminders: number;
+        events: number;
+    }>;
 };
 /** Documents the get result payload exchanged by command, SDK, and package integrations. */
 export interface GetResult {

package/dist/sdk/query/get.js

@@ -4,7 +4,7 @@
  * Implements the SDK-owned item query shared by every surface.
  */
 
-!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]="5536c6eb-5d51-5b67-879d-c1d0bfa5b692")}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]="f68f4074-51ba-5065-8cca-fe16acd48927")}catch(e){}}();
 import { pathExists, getActiveExtensionRegistrations, toItemRecord, resolveItemTypeRegistry, resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, EXIT_CODE, ITEM_METADATA_KEY_ORDER, TYPE_TO_FOLDER, PmCliError, buildItemNotFoundError, listAllItemMetadataLight, locateItem, readLocatedItem, getHistoryPath, getSettingsPath, resolvePmRoot, readSettings, resolveAuthor, } from "../runtime-primitives.js";
 import { readHistoryEntries } from "../history-read.js";
 import { recordContextUsageTouches } from "../context-usage.js";
@@ -21,6 +21,23 @@ const AUTOMATIC_CHILD_ROLLUP_TYPES = new Set([
     "plan",
 ]);
 const BUILTIN_ITEM_TYPES = new Set(Object.keys(TYPE_TO_FOLDER).map((type) => type.toLowerCase()));
+function itemCollectionCounts(item) {
+    const lengths = Object.fromEntries([
+        "comments",
+        "notes",
+        "learnings",
+        "files",
+        "tests",
+        "docs",
+        "reminders",
+        "events",
+    ].map((key) => [
+        key,
+        item[key]
+            ?.length ?? 0,
+    ]));
+    return lengths;
+}
 /** Decide whether a normal read should pay for a workspace-wide child projection. */
 function shouldAutoIncludeGetChildren(itemType) {
     const normalizedType = itemType.trim().toLowerCase();
@@ -65,14 +82,29 @@ function parseGetDepth(raw) {
     throw new PmCliError("Get --depth must be one of brief|standard|deep|full", EXIT_CODE.USAGE);
 }
 function projectItemForDepth(item, depth) {
+    const collectionCounts = itemCollectionCounts(item);
     if (depth === "deep") {
-        return item;
+        return {
+            ...item,
+            comments: item.comments ?? [],
+            notes: item.notes ?? [],
+            learnings: item.learnings ?? [],
+            files: item.files ?? [],
+            tests: item.tests ?? [],
+            docs: item.docs ?? [],
+            reminders: item.reminders ?? [],
+            events: item.events ?? [],
+            notes_count: collectionCounts.notes,
+            tests_count: collectionCounts.tests,
+            collection_counts: collectionCounts,
+        };
     }
     const { comments: _comments, notes: _notes, learnings: _learnings, files: _files, tests: _tests, docs: _docs, reminders: _reminders, events: _events, ...projected } = item;
     return {
         ...projected,
         notes_count: item.notes?.length ?? 0,
         tests_count: item.tests?.length ?? 0,
+        collection_counts: collectionCounts,
     };
 }
 function parseGetFields(raw) {
@@ -100,6 +132,7 @@ function validateGetFields(fields, runtimeMetadataKeys) {
         ...runtimeMetadataKeys,
         "notes_count",
         "tests_count",
+        "collection_counts",
     ]);
     const allowedRootFields = new Set([
         "body",
@@ -151,6 +184,7 @@ function projectItemForFields(item, fields) {
     const omittedCounts = {
         notes_count: item.notes?.length ?? 0,
         tests_count: item.tests?.length ?? 0,
+        collection_counts: itemCollectionCounts(item),
     };
     const projected = {};
     for (const field of fields) {
@@ -387,4 +421,4 @@ export const _testOnlyGetCommand = {
     shouldAutoIncludeGetChildren,
 };
 //# sourceMappingURL=get.js.map
-//# debugId=5536c6eb-5d51-5b67-879d-c1d0bfa5b692
+//# debugId=f68f4074-51ba-5065-8cca-fe16acd48927

package/dist/sdk/read-output-contracts.d.ts

@@ -4,7 +4,7 @@ export declare const PM_READ_OUTPUT_DIMENSIONS: readonly ["include", "amount", "
 /** One member of the universal read-output dimension set. */
 export type PmReadOutputDimension = (typeof PM_READ_OUTPUT_DIMENSIONS)[number];
 /** Built-in command roots whose primary operation is a read. */
-export declare const PM_READ_OUTPUT_SURFACES: readonly ["list", "context", "search", "get", "next", "health", "deps", "graph", "history", "activity", "validate", "events", "contracts", "comments", "notes", "files", "docs", "stats", "aggregate"];
+export declare const PM_READ_OUTPUT_SURFACES: readonly ["list", "context", "search", "get", "next", "health", "deps", "graph", "history", "activity", "validate", "events", "contracts", "comments", "notes", "files", "docs", "stats", "aggregate", "package-manage"];
 /** Built-in read command supported by the universal output contract. */
 export type PmReadOutputSurface = (typeof PM_READ_OUTPUT_SURFACES)[number];
 /** Canonical output controls accepted by every built-in read action. */