@unbrained/pm-cli 2026.8.6 → 2026.8.8

package/dist/sdk/lifecycle/close-many.js

@@ -4,12 +4,13 @@
  * Implements the pm close many 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]="1be4d7c4-3ede-59cc-8d70-df966a66e67e")}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]="4da07a98-855e-59cf-a6a4-2f59a8b3c0bd")}catch(e){}}();
 import { pathExists, createCheckpointId, loadMutationCheckpoint, restoreCheckpointItems, writeMutationCheckpoint, getActiveExtensionRegistrations, isTerminalStatus, resolveItemTypeRegistry, resolveRuntimeStatusRegistry, EXIT_CODE, PmCliError, toErrorMessage, resolveAuthor, nowIso, listAllItemMetadataLight, getSettingsPath, resolvePmRoot, readSettings, } from "../runtime-primitives.js";
 import { runClose } from "./close.js";
 import { hasListFilters } from "../query/list-filter-shared.js";
 import { runList } from "../query/list.js";
 import { runRestore } from "./restore.js";
+import { derivePmBulkMutationEffect, } from "../cli-contracts/command-exit-contracts.js";
 const CLOSE_MANY_CHECKPOINT_SCHEMA_VERSION = 1;
 const CLOSE_MANY_CHECKPOINT_SUBDIR = "close-many";
 const CLOSE_MANY_FILTER_GUIDANCE = [
@@ -139,6 +140,12 @@ async function runCloseManyRollback(params) {
     const restoreMessage = params.options.message ?? `Rollback close-many checkpoint ${checkpoint.id}`;
     const rollback = await restoreCheckpointItems(checkpoint.items, (id, targetUpdatedAt) => runRestore(id, targetUpdatedAt, { author: params.options.author, message: restoreMessage, force: true }, params.global));
     return {
+        ...derivePmBulkMutationEffect({
+            applied: rollback.restored_ids.length,
+            skipped: 0,
+            failed: rollback.failed_count,
+            unmatched: 0,
+        }),
         mode: "rollback",
         matched_count: checkpoint.items.length,
         dry_run: false,
@@ -266,6 +273,13 @@ async function buildCloseManyPlanContext(params) {
     const listed = await runList(params.options.status, activeListOptions(params.options.list), params.global);
     const { childrenByParent, parentByChild } = await buildActiveChildrenByParent(params.pmRoot, params.settings);
     const matched = sortCloseManyMatchedItems(listed.items, parentByChild);
+    const requestedIds = [
+        ...new Set(String(params.options.list?.ids ?? "")
+            .split(",")
+            .map((entry) => entry.trim())
+            .filter((entry) => entry.length > 0)),
+    ];
+    const matchedIds = new Set(matched.map((item) => item.id));
     const closePlannedIds = resolveCloseManyPlannedIds(matched, statusRegistry, force);
     return {
         pmRoot: params.pmRoot,
@@ -276,11 +290,14 @@ async function buildCloseManyPlanContext(params) {
         force,
         listed,
         matched,
+        unmatchedIds: requestedIds.filter((id) => !matchedIds.has(id)),
         planRows: planCloseManyRows(matched, childrenByParent, closePlannedIds, statusRegistry, force),
     };
 }
 function buildCloseManyDryRunResult(context) {
     return {
+        outcome: "effect",
+        exit_code: EXIT_CODE.SUCCESS,
         mode: "dry_run",
         matched_count: context.matched.length,
         dry_run: true,
@@ -291,6 +308,12 @@ function buildCloseManyDryRunResult(context) {
             : {}),
         item_plans: context.planRows,
         ids: [],
+        ...(context.unmatchedIds.length > 0
+            ? {
+                unmatched_ids: context.unmatchedIds,
+                unmatched_count: context.unmatchedIds.length,
+            }
+            : {}),
     };
 }
 async function resolveCloseManyCheckpointInfo(params) {
@@ -362,7 +385,16 @@ export async function runCloseMany(options, global) {
         closeOptions,
         global,
     });
+    const closedCount = rows.filter((row) => row.status === "closed").length;
+    const skippedCount = rows.filter((row) => row.status === "skipped").length;
+    const failedCount = rows.filter((row) => row.status === "failed").length;
     return {
+        ...derivePmBulkMutationEffect({
+            applied: closedCount,
+            skipped: skippedCount,
+            failed: failedCount,
+            unmatched: context.unmatchedIds.length,
+        }),
         mode: "apply",
         matched_count: context.matched.length,
         dry_run: false,
@@ -372,11 +404,17 @@ export async function runCloseMany(options, global) {
             ? { validate_close: context.validateCloseMode }
             : {}),
         ...(checkpointInfo ? { checkpoint: checkpointInfo } : {}),
-        closed_count: rows.filter((row) => row.status === "closed").length,
-        skipped_count: rows.filter((row) => row.status === "skipped").length,
-        failed_count: rows.filter((row) => row.status === "failed").length,
+        closed_count: closedCount,
+        skipped_count: skippedCount,
+        failed_count: failedCount,
         rows,
         ids: closedIds,
+        ...(context.unmatchedIds.length > 0
+            ? {
+                unmatched_ids: context.unmatchedIds,
+                unmatched_count: context.unmatchedIds.length,
+            }
+            : {}),
     };
 }
 /** Public contract for test only, shared by SDK and presentation-layer consumers. */
@@ -390,4 +428,4 @@ export const _testOnly = {
     resolveReason,
 };
 //# sourceMappingURL=close-many.js.map
-//# debugId=1be4d7c4-3ede-59cc-8d70-df966a66e67e
+//# debugId=4da07a98-855e-59cf-a6a4-2f59a8b3c0bd

package/dist/sdk/lifecycle/plan.js

@@ -4,7 +4,7 @@
  * Implements the pm plan 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]="d4b9caa3-59eb-5747-ba76-49f786c5010e")}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]="5d3c68a6-0b40-56b5-ae9e-776e1830ed3e")}catch(e){}}();
 import { pathExists, getActiveExtensionRegistrations, isTerminalStatus, resolveItemTypeRegistry, resolveRuntimeStatusRegistry, resolveTypeName, EXIT_CODE, PmCliError, splitCommaList, nowIso, locateItem, mutateItem, readLocatedItem, getSettingsPath, resolvePmRoot, readSettings, resolveAuthor, isTerminalPlanMode, } from "../runtime-primitives.js";
 import { PLAN_HARNESS_VALUES, PLAN_MODE_VALUES, PLAN_STEP_LINK_KIND_VALUES, PLAN_STEP_STATUS_VALUES, } from "../../types/index.js";
 import { runCreate, } from "./create.js";
@@ -726,7 +726,10 @@ async function planCreate(options, global, ctx) {
         test: toSpecArray(options.test),
         doc: toSpecArray(options.doc),
         field: toSpecArray(options.field),
-        assignee: requestedAssignee,
+        // Ownership is assigned by the atomic Plan metadata mutation below. The
+        // base create must remain author-owned so strict ownership governance does
+        // not reject the metadata seed as a cross-owner follow-up mutation.
+        assignee: resolveAuthor(options.author, ctx.settings.author_default),
         blockedBy: undefined,
         dep: buildPlanCreateDependencies(options),
         message: options.message ??
@@ -1576,4 +1579,4 @@ export const _testOnlyPlanCommand = {
     changedPlanMetadataFields,
 };
 //# sourceMappingURL=plan.js.map
-//# debugId=d4b9caa3-59eb-5747-ba76-49f786c5010e
+//# debugId=5d3c68a6-0b40-56b5-ae9e-776e1830ed3e

package/dist/sdk/lifecycle/update-many.d.ts

@@ -8,6 +8,7 @@ import type { ItemStatus, PmSettings } from "../../types/index.js";
 import { hasListFilters } from "../query/list-filter-shared.js";
 import { type ListOptions, type ListedItem } from "../query/list.js";
 import { type UpdateCommandOptions } from "./update.js";
+import { type PmCommandEffectReceipt } from "../cli-contracts/command-exit-contracts.js";
 /** Documents the update many command options payload exchanged by command, SDK, and package integrations. */
 export interface UpdateManyCommandOptions {
     /** Lifecycle state reported for status. */
@@ -50,7 +51,7 @@ interface UpdateManyRollbackResultRow {
     error?: string;
 }
 /** Documents the update many result payload exchanged by command, SDK, and package integrations. */
-export interface UpdateManyResult {
+export interface UpdateManyResult extends PmCommandEffectReceipt {
     /** Value that configures or reports mode for this contract. */
     mode: "dry_run" | "apply" | "rollback";
     /** Number of matched entries represented by this result. */

package/dist/sdk/lifecycle/update-many.js

@@ -4,13 +4,14 @@
  * Implements the pm update many 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]="61fe3a97-39e6-53de-8663-8e70d931a2d4")}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]="67f8958d-60d5-5657-93ce-9803859acd9e")}catch(e){}}();
 import { pathExists, createCheckpointId, loadMutationCheckpoint, restoreCheckpointItems, writeMutationCheckpoint, toItemRecord, applyAcceptanceCriteriaMutations, applyTagRemovals, mergeAdditiveTags, parseOptionalNonNegativeInteger, parseTags, splitAcceptanceCriteria, resolvePriority, normalizeStatusInput, resolveItemTypeRegistry, resolveTypeName, collectRuntimeUpdateFieldValues, buildInvalidTypeError, resolveItemTypesFilePath, resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, EXIT_CODE, PmCliError, toErrorMessage, stableValueEquals, nowIso, resolveIsoOrRelative, getActiveExtensionRegistrations, getSettingsPath, resolvePmRoot, readSettings, resolveAuthor, } from "../runtime-primitives.js";
 import { parseStatusFilterCsv } from "../../core/item/status-filter.js";
 import { hasListFilters } from "../query/list-filter-shared.js";
 import { runList, } from "../query/list.js";
 import { runRestore } from "./restore.js";
 import { runUpdate } from "./update.js";
+import { derivePmBulkMutationEffect, } from "../cli-contracts/command-exit-contracts.js";
 const UPDATE_MANY_CHECKPOINT_SCHEMA_VERSION = 1;
 const UPDATE_MANY_CHECKPOINT_SUBDIR = "update-many";
 const NON_MUTATION_UPDATE_OPTION_KEYS = new Set([
@@ -519,6 +520,12 @@ const runUpdateManyRollback = async (params) => {
         force: params.options.update?.force ?? true,
     }, params.global));
     return {
+        ...derivePmBulkMutationEffect({
+            applied: rollback.restored_ids.length,
+            skipped: 0,
+            failed: rollback.failed_count,
+            unmatched: 0,
+        }),
         mode: "rollback",
         matched_count: checkpoint.items.length,
         dry_run: false,
@@ -642,6 +649,8 @@ const buildUpdateManyPlan = async (params) => {
 };
 /** Builds the non-mutating preview response for a prepared update-many plan. */
 const buildUpdateManyDryRunResult = (plan) => ({
+    outcome: "effect",
+    exit_code: EXIT_CODE.SUCCESS,
     mode: "dry_run",
     matched_count: plan.listed.items.length,
     dry_run: true,
@@ -653,6 +662,12 @@ const buildUpdateManyDryRunResult = (plan) => ({
 });
 /** Builds the apply response for a plan whose rows are all already current. */
 const buildUpdateManyNoopResult = (plan) => ({
+    ...derivePmBulkMutationEffect({
+        applied: 0,
+        skipped: plan.listed.items.length,
+        failed: 0,
+        unmatched: plan.unmatchedIds?.length ?? 0,
+    }),
     mode: "apply",
     matched_count: plan.listed.items.length,
     dry_run: false,
@@ -742,16 +757,25 @@ const applyUpdateManyPlan = async (params) => {
     });
     /** Counts apply rows with one terminal status. */
     const countStatus = (status) => applied.rows.filter((row) => row.status === status).length;
+    const updatedCount = countStatus("updated");
+    const skippedCount = countStatus("skipped");
+    const failedCount = countStatus("failed");
     return {
+        ...derivePmBulkMutationEffect({
+            applied: updatedCount,
+            skipped: skippedCount,
+            failed: failedCount,
+            unmatched: params.plan.unmatchedIds?.length ?? 0,
+        }),
         mode: "apply",
         matched_count: params.plan.listed.items.length,
         dry_run: false,
         filters: params.plan.listed.filters,
         planned_update_options: params.plan.updateSummary,
         ...(checkpointInfo ? { checkpoint: checkpointInfo } : {}),
-        updated_count: countStatus("updated"),
-        skipped_count: countStatus("skipped"),
-        failed_count: countStatus("failed"),
+        updated_count: updatedCount,
+        skipped_count: skippedCount,
+        failed_count: failedCount,
         rows: applied.rows,
         ids: applied.updatedIds,
         ...buildUnmatchedIdFields(params.plan),
@@ -804,4 +828,4 @@ export const _testOnlyUpdateManyCommand = {
     toComparablePreviewValue,
 };
 //# sourceMappingURL=update-many.js.map
-//# debugId=61fe3a97-39e6-53de-8663-8e70d931a2d4
+//# debugId=67f8958d-60d5-5657-93ce-9803859acd9e

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

@@ -9,5 +9,5 @@
 export { ITEM_LATEST_TIMESTAMP_FIELDS, ITEM_UNION_COLLECTION_FIELDS, mergeHistoryStreams, mergeItemDocuments, mergeJsonDocuments, mergeRelationshipEventStreams, type HistoryMergeResult, type HistoryMergeStrategy, type ItemDocumentMergeResult, type JsonDocumentMergeResult, type ItemMergeConflictDecision, type MergePreferredSide, type RelationshipStreamMergeResult, } from "./three-way.js";
 export { listMergeReceipts, markMergeReceiptReconciled, runMergeReceiptReport, summarizeMergeReceipt, type MergeDecisionReceipt, type MergeDecisionReceiptSummary, type MergeReceiptReport, } from "./receipts.js";
 export { MERGE_DRIVER_ARTIFACT_VALUES, runMergeDriver, type MergeDriverArtifact, type MergeDriverOptions, type MergeDriverResult, } from "./driver.js";
-export { auditMergeAttributeFence, auditMergeDriverConfiguration, buildMergeAttributePatterns, findGitWorkspaceRoot, PM_GITATTRIBUTES_END, PM_GITATTRIBUTES_START, refreshMergeAttributeFenceIfInstalled, runMergeInstall, type MergeFenceAuditResult, type MergeDriverConfigurationAuditResult, type MergeFenceRefreshOutcome, type MergeInstallOptions, type MergeInstallResult, } from "./install.js";
+export { auditMergeAttributeFence, auditMergeDriverConfiguration, buildMergeAttributePatterns, findGitWorkspaceRoot, PM_GITATTRIBUTES_END, PM_GITATTRIBUTES_START, refreshMergeAttributeFenceIfInstalled, resolveMergeInstallContext, runMergeInstall, type MergeFenceAuditResult, type MergeDriverConfigurationAuditResult, type MergeFenceRefreshOutcome, type MergeInstallOptions, type MergeInstallContextResolution, type MergeInstallResult, } from "./install.js";
 export { runMergeReconcile, type MergeReconcileOptions, type MergeReconcileResult, } from "./reconcile.js";

package/dist/sdk/merge/index.js

@@ -7,11 +7,11 @@
  * this module so packages and hosts can reuse the same merge 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]="27725b9d-2a1d-54ae-8191-12ebace6ef6a")}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]="a8072065-092c-564b-a84f-cf687f795a92")}catch(e){}}();
 export { ITEM_LATEST_TIMESTAMP_FIELDS, ITEM_UNION_COLLECTION_FIELDS, mergeHistoryStreams, mergeItemDocuments, mergeJsonDocuments, mergeRelationshipEventStreams, } from "./three-way.js";
 export { listMergeReceipts, markMergeReceiptReconciled, runMergeReceiptReport, summarizeMergeReceipt, } from "./receipts.js";
 export { MERGE_DRIVER_ARTIFACT_VALUES, runMergeDriver, } from "./driver.js";
-export { auditMergeAttributeFence, auditMergeDriverConfiguration, buildMergeAttributePatterns, findGitWorkspaceRoot, PM_GITATTRIBUTES_END, PM_GITATTRIBUTES_START, refreshMergeAttributeFenceIfInstalled, runMergeInstall, } from "./install.js";
+export { auditMergeAttributeFence, auditMergeDriverConfiguration, buildMergeAttributePatterns, findGitWorkspaceRoot, PM_GITATTRIBUTES_END, PM_GITATTRIBUTES_START, refreshMergeAttributeFenceIfInstalled, resolveMergeInstallContext, runMergeInstall, } from "./install.js";
 export { runMergeReconcile, } from "./reconcile.js";
 //# sourceMappingURL=index.js.map
-//# debugId=27725b9d-2a1d-54ae-8191-12ebace6ef6a
+//# debugId=a8072065-092c-564b-a84f-cf687f795a92

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]="1729579e-ef08-55c3-914f-c025ba3033e4")}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]="fce8fc1d-b9ca-55bc-9c5a-f4f9728a7158")}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 {
@@ -185,6 +225,14 @@ export function buildMergeAttributePatterns(trackerRelativeRoot, typeFolders) {
     patterns.push(`${quoteGitAttributePattern(`${prefix}history/*.jsonl`)} merge=pm-history`);
     patterns.push(`${quoteGitAttributePattern(`${prefix}settings.json`)} merge=pm-json`);
     patterns.push(`${quoteGitAttributePattern(`${prefix}**/*.json`)} merge=pm-json`);
+    // Extensions are package assets, not tracker item streams. The broad
+    // fallback patterns above intentionally protect unknown contributed item
+    // folders, so this last-match escape hatch must explicitly unset merge for
+    // every file beneath the reserved extension package root.
+    patterns.push(`${quoteGitAttributePattern(`${prefix}extensions/**`)} -merge`);
+    // The managed extension inventory is tracker state rather than package
+    // content, so restore its structured JSON driver after the asset exclusion.
+    patterns.push(`${quoteGitAttributePattern(`${prefix}extensions/.managed-extensions.json`)} merge=pm-json`);
     return patterns;
 }
 async function reconcileGitattributesBlock(workspaceRoot, patterns, dryRun) {
@@ -385,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,
@@ -510,4 +548,4 @@ export async function installMergeFence(options) {
     };
 }
 //# sourceMappingURL=install.js.map
-//# debugId=1729579e-ef08-55c3-914f-c025ba3033e4
+//# debugId=fce8fc1d-b9ca-55bc-9c5a-f4f9728a7158

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/read-output-budget.js

@@ -1,21 +1,12 @@
 
-!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]="64c4e6e1-d7c4-50e0-a444-fb2fa3c65443")}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]="1726fdce-dc71-5707-ae75-b588691e813d")}catch(e){}}();
+import { countReadOutputRows, readOutputRowCollections, } from "./read-output-rows.js";
 const MAX_ESTIMATE_ITERATIONS = 8;
 const MAX_COMPACTION_ITERATIONS = 64;
 /** Return whether a value is a non-array object record. */
 function isRecord(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
-/** Resolve declared row keys, falling back to top-level array properties. */
-function rowKeys(result) {
-    const contract = result.row_contract;
-    if (isRecord(contract) && Array.isArray(contract.row_keys)) {
-        return contract.row_keys.filter((entry) => typeof entry === "string");
-    }
-    return Object.entries(result)
-        .filter(([, value]) => Array.isArray(value))
-        .map(([key]) => key);
-}
 /** Recursively shorten explanatory strings and record whether content changed. */
 function compactStrings(value, state) {
     if (typeof value === "string") {
@@ -48,27 +39,38 @@ export function updateReadOutputReceiptEstimate(result, receipt) {
 }
 /** Reduce the largest row collection until the budget fits or no rows can move. */
 function compactRowsToBudget(result, receipt, budget) {
-    const keys = rowKeys(result);
     for (let iteration = 0; iteration < MAX_COMPACTION_ITERATIONS; iteration += 1) {
         updateReadOutputReceiptEstimate(result, receipt);
         if (receipt.estimated_tokens <= budget)
             return;
-        const candidate = keys
-            .map((key) => ({
-            key,
-            rows: Array.isArray(result[key]) ? result[key] : [],
+        const candidate = readOutputRowCollections(result)
+            .filter((collection) => (Array.isArray(collection.value)
+            ? collection.value.length
+            : Object.keys(collection.value).length) > 1)
+            .map((collection) => ({
+            collection,
+            length: Array.isArray(collection.value)
+                ? collection.value.length
+                : Object.keys(collection.value).length,
         }))
-            .filter(({ rows }) => rows.length > 1)
-            .sort((left, right) => right.rows.length - left.rows.length ||
-            left.key.localeCompare(right.key))[0];
+            .sort((left, right) => right.length - left.length ||
+            left.collection.path.localeCompare(right.collection.path))[0]?.collection;
         if (!candidate)
             return;
-        candidate.rows.splice(-Math.max(1, Math.ceil(candidate.rows.length / 2)));
+        if (Array.isArray(candidate.value)) {
+            candidate.value.splice(-Math.max(1, Math.ceil(candidate.value.length / 2)));
+        }
+        else {
+            const keys = Object.keys(candidate.value);
+            for (const key of keys.slice(-Math.max(1, Math.ceil(keys.length / 2)))) {
+                delete candidate.value[key];
+            }
+        }
         receipt.rows_compacted = true;
         result.has_more = true;
         result.truncated = true;
         if (typeof result.count === "number") {
-            result.count = keys.reduce((total, key) => total + (Array.isArray(result[key]) ? result[key].length : 0), 0);
+            result.count = countReadOutputRows(result);
         }
     }
 }
@@ -83,4 +85,4 @@ export function compactReadOutputToBudget(result, receipt, budget) {
     return compacted;
 }
 //# sourceMappingURL=read-output-budget.js.map
-//# debugId=64c4e6e1-d7c4-50e0-a444-fb2fa3c65443
+//# debugId=1726fdce-dc71-5707-ae75-b588691e813d

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

@@ -1,3 +1,4 @@
+import { type PmReadOutputSessionReceipt, type PmReadOutputSessionState } from "./read-output-session.js";
 /** Stable output dimensions shared by every read surface. */
 export declare const PM_READ_OUTPUT_DIMENSIONS: readonly ["include", "amount", "cost", "encoding"];
 /** One member of the universal read-output dimension set. */
@@ -16,6 +17,8 @@ export interface PmReadOutputOptions {
     outputBudget?: string | number;
     /** Requested static renderer encoding; streaming remains a command behavior. */
     outputFormat?: "json" | "toon";
+    /** Caller-carried cross-call budget and served-fact state. */
+    outputSession?: string | PmReadOutputSessionState;
 }
 /** Compatibility spelling retained for a command-specific output control. */
 export interface PmReadOutputLegacyAlias {
@@ -118,11 +121,16 @@ export interface PmReadOutputBudgetExceeded {
 /** Read result with an optional shaping receipt or a discriminated omission. */
 export type PmReadOutputResult<Result> = (Result & {
     read_output?: PmReadOutputReceipt;
-}) | PmReadOutputBudgetExceeded;
+    read_session?: PmReadOutputSessionReceipt;
+}) | (PmReadOutputBudgetExceeded & {
+    read_session?: PmReadOutputSessionReceipt;
+});
 /** Select the omission-aware result type when an option shape can request a budget. */
-export type PmReadOutputResultFor<Result, Options> = "outputBudget" extends keyof Options ? PmReadOutputResult<Result> : Result;
+export type PmReadOutputResultFor<Result, Options> = "outputBudget" extends keyof Options ? PmReadOutputResult<Result> : "outputSession" extends keyof Options ? PmReadOutputResult<Result> : Result;
 /** Canonical CLI flags that opt a read invocation into universal output shaping. */
 export declare const PM_READ_OUTPUT_OPTION_FLAGS: readonly string[];
+/** Canonical control that composes the four per-call dimensions across reads. */
+export declare const PM_READ_OUTPUT_COMPOSITION_OPTION_FLAGS: readonly ["--output-session"];
 /** Universal output contract for every built-in read surface. */
 export declare const PM_READ_OUTPUT_SURFACE_CONTRACTS: readonly PmReadOutputSurfaceContract[];
 /** Resolve a command or list/context alias to its canonical read-output surface. */