@unbrained/pm-cli 2026.9.4 → 2026.9.6

package/dist/sdk/history-repair.d.ts

@@ -1,3 +1,4 @@
+import { type HistorySalvageReceipt } from "./history/salvage.js";
 import { type ReplayDocument } from "../core/history/replay.js";
 import type { GlobalOptions } from "../core/shared/command-types.js";
 import type { HistoryEntry } from "../types/index.js";
@@ -5,6 +6,8 @@ import { type MergeDecisionReceipt } from "./merge/receipts.js";
 import { type ProvenanceNormalizationReceipt } from "./governance/provenance-health.js";
 /** Documents the history repair command options payload exchanged by command, SDK, and package integrations. */
 export interface HistoryRepairCommandOptions {
+    /** Remove only an invalid trailing suffix after a verified prefix; never re-anchor or reconcile. */
+    salvageTail?: boolean;
     /** Value that configures or reports dry run for this contract. */
     dryRun?: boolean;
     /** Value that configures or reports author for this contract. */
@@ -33,9 +36,18 @@ export interface HistoryRepairCommandOptions {
         gitWorkspaceRoot: string | null;
         receipts: MergeDecisionReceipt[];
     }>;
+    /** Restored-origin evidence checked against the same item snapshot protected by the rewrite transaction. */
+    mergeAbandonmentProof?: {
+        /** Git workspace containing the tracked item. */
+        gitWorkspaceRoot: string;
+        /** Authoritative receipt whose original rebase state must match. */
+        receipt: MergeDecisionReceipt;
+    };
 }
 /** Documents the history repair result payload exchanged by command, SDK, and package integrations. */
 export interface HistoryRepairResult {
+    /** Present when invalid trailing bytes were selected for explicit salvage. */
+    salvage?: HistorySalvageReceipt;
     /** Stable identifier used to reference this record across commands and storage. */
     id: string;
     /** Value that configures or reports dry run for this contract. */

package/dist/sdk/history-repair.js

@@ -4,8 +4,9 @@
  * Implements the pm history repair 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]="cb0b0e36-3135-5fc4-a0ae-f4e5b974e57f")}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]="9f91f2ee-cebe-592c-92ee-717301fa96ca")}catch(e){}}();
 import { assertInitializedTracker } from "./environment/tracker-preflight.js";
+import { salvageHistoryTail } from "./history/salvage.js";
 import { realpath } from "node:fs/promises";
 import path from "node:path";
 import jsonPatch from "fast-json-patch";
@@ -29,6 +30,7 @@ import { listAllItemMetadataWithBody, readLocatedItem, } from "../core/store/ite
 import { resolvePmRoot } from "../core/store/paths.js";
 import { readSettings } from "../core/store/settings.js";
 import { resolveHistorySubject } from "./history-redact.js";
+import { isOriginalGitStateRestored } from "./merge/receipt-operation.js";
 import { inspectMergeReceiptEvidence, summarizeMergeReceipt, } from "./merge/receipts.js";
 import { encodeItemScalarDecisionValue, hashItemScalarDecisionValue, } from "./merge/three-way.js";
 import { listInvalidProvenanceHistoryStreamIds, normalizeInvalidHistoryProvenance, } from "./governance/provenance-health.js";
@@ -228,6 +230,24 @@ async function verifyMergeReceiptProof(params) {
         receipt_ids: [],
     };
 }
+/** Refuse a restored-origin audit when its exact item snapshot or clean history has changed. */
+async function assertHistoryRepairAbandonmentProof(proof, context, chainOk, reanchor) {
+    if (proof === undefined)
+        return;
+    const { receipt, gitWorkspaceRoot } = proof;
+    const canonicalPath = context.currentItemPath === null ? null
+        : path.relative(gitWorkspaceRoot, context.currentItemPath).split(path.sep).join("/");
+    if (!chainOk || reanchor.entriesRehashed !== 0 || reanchor.entriesPatchRepaired !== 0 || context.matchedChainBefore !== true ||
+        context.currentItemRawBeforeLock === null || canonicalPath !== receipt.item_path ||
+        receipt.operation === undefined ||
+        !await isOriginalGitStateRestored(gitWorkspaceRoot, receipt.item_path, receipt.operation, context.currentItemRawBeforeLock)) {
+        throw new PmCliError("Restored-origin receipt evidence no longer proves the exact clean item snapshot.", EXIT_CODE.CONFLICT, {
+            code: "merge_reconcile_receipt_evidence_untrusted",
+            recovery: { suggested_retry: "pm merge reconcile --dry-run" },
+        });
+    }
+}
+/** Resolve and verify receipt candidates against loaded item evidence, refusing untrusted preview and apply requests alike. */
 async function resolveHistoryRepairMergeEvidence(params) {
     const requestedReceiptIds = new Set(params.options.mergeReceiptProof?.receipts
         .filter((receipt) => receipt.item_id === params.subjectId)
@@ -255,7 +275,6 @@ async function resolveHistoryRepairMergeEvidence(params) {
         : undefined;
     if (mergeReceiptProof &&
         !mergeReceiptProof.trusted &&
-        params.options.dryRun !== true &&
         params.options.force !== true) {
         throw new PmCliError(`Merge receipt evidence for ${params.subjectId} does not prove the exact item snapshot (${mergeReceiptProof.reason}).`, EXIT_CODE.CONFLICT, {
             code: "merge_reconcile_receipt_evidence_untrusted",
@@ -358,6 +377,7 @@ function collectHistoryRepairWarnings(changed, skippedOps, reconciliation) {
     }
     return warnings;
 }
+/** Revalidate item/history bytes and restored-origin Git proof under the rewrite lock before persisting. */
 async function applyHistoryRepairRewrite(params) {
     return executeHistoryRewrite({
         pmRoot: params.pmRoot,
@@ -365,16 +385,19 @@ async function applyHistoryRepairRewrite(params) {
         settings: params.settings,
         typeRegistry: params.typeRegistry,
         historyRawBeforeLock: params.historyRawBeforeLock,
-        currentItemRawBeforeLock: params.currentItemRawBeforeLock,
+        currentItemRawBeforeLock: params.itemReplayContext.currentItemRawBeforeLock,
         operation: "history-repair",
         author: params.author,
         force: params.force,
-        itemDocument: params.loadedItem?.document ?? null,
-        applyRewrite: async ({ historyRawUnderLock }) => writeHistoryRawWithRollback({
-            historyPath: params.historyPath,
-            nextHistoryRaw: historyEntriesToRaw(params.rewrittenEntries),
-            historyRawUnderLock,
-        }),
+        itemDocument: params.itemReplayContext.loadedItem?.document ?? null,
+        applyRewrite: async ({ historyRawUnderLock }) => {
+            await assertHistoryRepairAbandonmentProof(params.mergeAbandonmentProof, params.itemReplayContext, params.chainOk, params.reanchor);
+            await writeHistoryRawWithRollback({
+                historyPath: params.historyPath,
+                nextHistoryRaw: historyEntriesToRaw(params.rewrittenEntries),
+                historyRawUnderLock,
+            });
+        },
         applyPostRewrite: async () => runActiveOnWriteHooks({
             path: params.historyPath,
             scope: "project",
@@ -389,6 +412,24 @@ export async function runHistoryRepair(id, options, global) {
     const settings = await readSettings(pmRoot);
     const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());
     const subject = await resolveHistorySubject(pmRoot, id, settings, typeRegistry.type_to_folder);
+    if (options.salvageTail === true) {
+        return salvageHistoryTail({ pmRoot, subject, settings, typeRegistry, options, author: resolveAuthor(options.author, settings.author_default) });
+    }
+    return repairHistorySubject({ pmRoot, subject, settings, typeRegistry, options });
+}
+/** Preserve explicit audit requests while reusing exact restored-origin dispositions in verified history. */
+function shouldAppendForcedHistoryAudit(options, historyEntries) {
+    // Receipt persistence can fail after the audited history transaction commits.
+    // Only an identical disposition satisfies a retry; unrelated audits do not.
+    const alreadyRecorded = options.mergeAbandonmentProof !== undefined &&
+        options.auditContext !== undefined &&
+        historyEntries.some((entry) => entry.op === "merge_reconcile" &&
+            stableStringify(entry.context) === stableStringify(options.auditContext));
+    return options.forceAuditEntry === true && !alreadyRecorded;
+}
+/** Reanchor or reconcile one resolved subject, separately from byte-preserving salvage. */
+async function repairHistorySubject(params) {
+    const { pmRoot, subject, settings, typeRegistry, options } = params;
     if (!(await pathExists(subject.historyPath))) {
         throw new PmCliError(`No history stream exists for ${subject.id}.`, EXIT_CODE.NOT_FOUND);
     }
@@ -416,6 +457,7 @@ export async function runHistoryRepair(id, options, global) {
         .filter((version) => version !== undefined));
     const reanchor = reanchorHistoryEntries(provenanceNormalization.entries, itemHashVersion);
     const itemReplayContext = await loadHistoryRepairItemReplay(subject, settings, historyEntries, itemHashVersion);
+    await assertHistoryRepairAbandonmentProof(options.mergeAbandonmentProof, itemReplayContext, chainBefore.ok, reanchor);
     const finalReplay = reanchor.finalDocument;
     const finalReplayHashes = replayHashVerificationCandidates(finalReplay, itemHashVersion);
     let reconcileNeeded = false;
@@ -440,7 +482,7 @@ export async function runHistoryRepair(id, options, global) {
         reanchor.entriesRehashed > 0,
         reanchor.entriesPatchRepaired > 0,
         reconcileNeeded,
-        options.forceAuditEntry === true,
+        shouldAppendForcedHistoryAudit(options, historyEntries),
         provenanceNormalization.receipt.changed,
     ].some(Boolean);
     const author = resolveAuthor(options.author, settings.author_default);
@@ -481,10 +523,12 @@ export async function runHistoryRepair(id, options, global) {
             settings,
             typeRegistry,
             historyRawBeforeLock,
-            currentItemRawBeforeLock: itemReplayContext.currentItemRawBeforeLock,
+            itemReplayContext,
+            mergeAbandonmentProof: options.mergeAbandonmentProof,
+            chainOk: chainBefore.ok,
+            reanchor,
             author,
             force: options.force,
-            loadedItem: itemReplayContext.loadedItem,
             historyPath: subject.historyPath,
             rewrittenEntries,
         })));
@@ -537,6 +581,9 @@ export function assertHistoryRepairTarget(id, all) {
 }
 /** Bulk drift repair: scan every item's history stream with the same drift scan `pm health` uses, then run the audited single-stream repair (ownership check, lock, no-drift verification, audit marker) for each drifted stream. One failing stream never aborts the rest; failures are collected per row and the caller decides the exit code from `totals.failed`. */
 export async function runHistoryRepairAll(options, global) {
+    if (options.salvageTail === true) {
+        throw new PmCliError("Tail salvage requires one explicit item ID; --all is not supported.", EXIT_CODE.USAGE);
+    }
     const pmRoot = resolvePmRoot(process.cwd(), global.path);
     await assertInitializedTracker(pmRoot);
     const settings = await readSettings(pmRoot);
@@ -608,4 +655,4 @@ export async function runHistoryRepairAll(options, global) {
     };
 }
 //# sourceMappingURL=history-repair.js.map
-//# debugId=cb0b0e36-3135-5fc4-a0ae-f4e5b974e57f
+//# debugId=9f91f2ee-cebe-592c-92ee-717301fa96ca

package/dist/sdk/lifecycle/claim.d.ts

@@ -62,6 +62,10 @@ export interface ReleaseResult {
     previous_assignee: string | null;
     /** Value that configures or reports forced for this contract. */
     forced: boolean;
+    /** Stable handoff diagnostics shared by CLI and MCP consumers. */
+    warnings?: string[];
+    /** Concrete recovery commands when releasing ownership leaves work in progress. */
+    suggestions?: string[];
 }
 /** Documents the claim mutation options payload exchanged by command, SDK, and package integrations. */
 export interface ClaimMutationOptions {

package/dist/sdk/lifecycle/claim.js

@@ -4,9 +4,9 @@
  * Implements the pm claim 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]="1a61bf25-e320-5adc-8f5a-a427bc89af1a")}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]="a4d95016-05b9-5272-8044-2649da644e98")}catch(e){}}();
 import { assertInitializedTracker } from "../environment/tracker-preflight.js";
-import { resolveRuntimeStatusRegistry, statusIsTerminal, EXIT_CODE, PmCliError, toItemRecord, mutateItem, resolvePmRoot, readSettings, resolveAuthor, resolveClaimPrincipal, } from "../runtime-primitives.js";
+import { resolveRuntimeStatusRegistry, statusIsTerminal, EXIT_CODE, PmCliError, toItemRecord, mutateItem, resolvePmRoot, readSettings, resolveAuthor, resolveClaimPrincipal, normalizeStatusForRegistry, } from "../runtime-primitives.js";
 import { wrapOwnershipConflict } from "../annotations.js";
 import { describeItemOwnershipConflict } from "../ownership-source.js";
 import { runNext, } from "../query/next.js";
@@ -226,12 +226,18 @@ export async function runRelease(id, force, global, options = {}) {
         principal: claimPrincipal,
         itemId: result.item.id,
     });
+    const statusRegistry = resolveRuntimeStatusRegistry(settings.schema);
+    const stillInProgress = normalizeStatusForRegistry(result.item.status, statusRegistry) === normalizeStatusForRegistry(statusRegistry.in_progress_status, statusRegistry);
     return {
         item: toItemRecord(result.item),
         released_by: author,
         previous_assignee: previousAssignee,
         forced: force,
+        ...(stillInProgress ? {
+            warnings: ["released_unclaimed_in_progress"],
+            suggestions: [`${result.item.id} remains ${result.item.status} and unclaimed. If work is paused, run pm pause-task ${result.item.id} to move it to ${statusRegistry.open_status}.`],
+        } : {}),
     };
 }
 //# sourceMappingURL=claim.js.map
-//# debugId=1a61bf25-e320-5adc-8f5a-a427bc89af1a
+//# debugId=a4d95016-05b9-5272-8044-2649da644e98

package/dist/sdk/lifecycle/close.d.ts

@@ -1,3 +1,9 @@
+/**
+ * @module sdk/lifecycle/close
+ *
+ * Implements the pm close command surface and its agent-facing runtime behavior.
+ */
+import type { PmCliErrorRecoveryPayload } from "../../core/shared/errors.js";
 import { type GlobalOptions } from "../runtime-primitives.js";
 import { collectBlockedByIds } from "../actionability.js";
 import { type CloseOperationOptions, type CloseOperationResult } from "../lifecycle-policy.js";
@@ -28,6 +34,8 @@ export interface CloseResult {
     item: Record<string, unknown>;
     /** Changed metadata fields. */
     changed_fields: string[];
+    /** Evidence-only update guidance when acceptance fields are missing. */
+    recovery?: PmCliErrorRecoveryPayload;
     /** Validation and lifecycle receipts. */
     warnings: string[];
 }

package/dist/sdk/lifecycle/close.js

@@ -1,10 +1,5 @@
-/**
- * @module sdk/lifecycle/close
- *
- * Implements the pm close command surface and its agent-facing runtime behavior.
- */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="9f28f7d8-993b-5201-b606-d1eab0c3ff5c")}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]="0e166cbb-ef9c-5016-89a6-07f287e00a2e")}catch(e){}}();
 import { assertInitializedTracker } from "../environment/tracker-preflight.js";
 import { toItemRecord, isTerminalStatus, resolveItemTypeRegistry, resolveRuntimeStatusRegistry, EXIT_CODE, PmCliError, buildItemNotFoundError, listAllItemMetadataLight, locateItem, mutateItem, readLocatedItem, resolvePmRoot, readSettings, resolveAuthor, resolveIsoOrRelative, shouldCompletePlanOnClose, getActiveExtensionRegistrations, } from "../runtime-primitives.js";
 import { collectBlockedByIds, indexBlockedByIds } from "../actionability.js";
@@ -47,6 +42,16 @@ function findMissingCloseValidationFields(itemMetadata) {
     }
     return missing;
 }
+/** Build an argv-safe update that appends acceptance evidence without repeating a terminal transition. */
+function closeEvidenceRecovery(metadata, pmRoot, options = {}) {
+    const missing = findMissingCloseValidationFields(metadata);
+    if (missing.length === 0)
+        return undefined;
+    const values = { resolution: options.resolution, expected_result: options.expectedResult, actual_result: options.actualResult };
+    const missingFlags = missing.map((field) => `--${field.key.replaceAll("_", "-")}`);
+    const args = ["--pm-path", pmRoot, "update", metadata.id, ...missing.flatMap((field, index) => [missingFlags[index], values[field.key]?.trim() || "<value>"])];
+    return { missing: missingFlags, suggested_retry: renderPmCommand(args), suggested_retry_args: args };
+}
 async function duplicateChainReferencesClosingItem(loadItemById, initialDuplicateOf, closingId) {
     const visited = new Set();
     let current = initialDuplicateOf;
@@ -317,10 +322,11 @@ function clearCloseAssignee(metadata) {
     delete metadata.assignee;
     return ["assignee"];
 }
+/** Enforce terminal and closure policies before applying acceptance fields and the atomic lifecycle transition. */
 function mutateCloseMetadata(metadata, context) {
     if (isTerminalStatus(metadata.status, context.statusRegistry) &&
         !context.force) {
-        throw new PmCliError(`Item ${metadata.id} is already terminal; use --force to close again.`, EXIT_CODE.CONFLICT);
+        throw new PmCliError(`Item ${metadata.id} is already terminal; use pm update to append acceptance evidence, or --force only for an intentional repeat closure.`, EXIT_CODE.CONFLICT, { recovery: closeEvidenceRecovery(metadata, context.pmRoot, context.options) });
     }
     const inlineChangedFields = applyInlineCloseFields(metadata, context.options);
     const duplicateFallbackFields = applyDuplicateCloseMetadata(metadata, context.duplicateOf);
@@ -444,9 +450,11 @@ export async function closeItem(id, closeReasonText, options, global) {
             });
         },
     });
+    const recovery = validateCloseMode === "warn" ? closeEvidenceRecovery(result.item, pmRoot) : undefined;
     return {
         item: toItemRecord(result.item),
         changed_fields: result.changedFields,
+        ...(recovery ? { recovery } : {}),
         warnings: [
             ...result.warnings,
             ...(await autoUnblockResolvedDependents(pmRoot, settings, trackerItems, located.id, author, statusRegistry)),
@@ -458,4 +466,4 @@ export function runClose(id, closeReasonText, options, global) {
     return closeItem(id, closeReasonText, options, global);
 }
 //# sourceMappingURL=close.js.map
-//# debugId=9f28f7d8-993b-5201-b606-d1eab0c3ff5c
+//# debugId=0e166cbb-ef9c-5016-89a6-07f287e00a2e

package/dist/sdk/lifecycle/create.js

@@ -4,7 +4,7 @@
  * Implements the pm create 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]="c9bfbfd4-3d34-5fa7-b264-6bf9ed5f7f81")}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]="44240cea-9996-5f86-acc5-ac0cfa71c586")}catch(e){}}();
 import { assertInitializedTracker } from "../environment/tracker-preflight.js";
 import { assertNoAmbiguousBareCommaEntry, looksLikeStructuredKeyValueEntry, resolveMutationStdinTokenFields, } from "../../core/item/parse.js";
 import { removeFileIfExists, writeFileAtomic, appendHistoryEntry, createHistoryEntry, generateItemId, normalizeItemId, canonicalDocument, normalizeItemMetadata, serializeItemDocument, assertParentReferenceIsNotSelf, isPlaceholderReferenceToken, normalizeParentReferenceValue, validateMissingParentReference, validateSprintOrReleaseValue, assertNoUnknownCsvKeys, looksLikeGenericKeyValueEntry, mergeAdditiveTags, parseCsvKv, parseOptionalNonNegativeInteger, parseOptionalNumber, parseTags, shouldResolveMutationStdinTokens, transferMutationStdinTokenPolicy, resolvePriority, getFocusedItem, normalizeStatusInput, isTerminalStatus, canonicalizeCommandOptionKey, commandOptionFlagLabel, resolveItemTypeRegistry, resolveCommandOptionPolicyState, resolveTypeDefinition, resolveTypeName, validateTypeOptions, acquireLock, printError, buildInvalidTypeError, resolveTypeSynonym, collectRuntimeCreateFieldValues, resolveItemTypesFilePath, resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, EXIT_CODE, ITEM_METADATA_KEY_ORDER, PmCliError, nowIso, resolveIsoOrRelative, getActiveExtensionRegistrations, projectAfterCommandItemSnapshot, recordAfterCommandAffectedItem, runActiveCommandHandler, runActiveBeforeMutationHooks, runActiveOnWriteHooks, collectRegisteredItemFieldNames, applyRegisteredItemFieldDefaultsAndValidation, parseRegisteredItemFieldAssignments, listAllItemMetadataLight, locateItem, createMutationGuardSdk, getHistoryPath, getItemPath, resolvePmRoot, readSettings, resolveAuthor, } from "../runtime-primitives.js";
@@ -24,7 +24,7 @@ import { attachLinkedTestMutationProvenance } from "../test/trust.js";
 import { COMMON_UNSET_FIELD_DEFINITIONS_AFTER_AUTHOR, COMMON_UNSET_FIELD_DEFINITIONS_BEFORE_AUTHOR, parseCommandUnsetTargets, resolveRuntimeUnsetFieldDefinition, } from "./shared-unset-fields.js";
 import { ensureEnumValue } from "./recurrence-parsers.js";
 import { assertDependencyEdgesAllowed, assertDependencyTargetsResolvable, assertValidBareDependencyFlagValue, } from "../dependency-flag-validation.js";
-import { normalizeDependencySeedId, normalizeDependencySourceKind, } from "../dependency-provenance.js";
+import { normalizeDependencySeedId, normalizeItemReference, isExternalDependencyReference, normalizeDependencySourceKind, } from "../dependency-provenance.js";
 import { resolveCanonicalRelationshipKind } from "../relationships.js";
 import { supportsCreateExplicitEmpty } from "../agent/create-option-policy.js";
 import { parseEventEntries, parseReminderEntries, parseTypeOptionEntries, } from "./repeatable-metadata-parsers.js";
@@ -767,9 +767,6 @@ export function requireStringOption(value, flag) {
     }
     return normalized;
 }
-function ensurePriority(rawPriority) {
-    return resolvePriority(rawPriority);
-}
 function mergeCreateOptionsWithTemplate(templateOptions, explicitOptions) {
     const merged = {};
     for (const [key, value] of Object.entries(templateOptions)) {
@@ -847,9 +844,6 @@ async function loadCreateTemplateOptionsFromRuntime(templateName, global, pmRoot
     /* c8 ignore next -- template runtime success path is covered by package-level integration tests. */
     return readTemplateOptionsFromRuntimeResult(handlerResult.result, templateName);
 }
-function ensureInitHasRun(pmRoot) {
-    return assertInitializedTracker(pmRoot);
-}
 /**
  * Resolve an optional string item-metadata field for {@link runCreate}: yields
  * `undefined` when the field is being cleared via `--unset <key>` or was never
@@ -913,7 +907,10 @@ async function inheritFocusedParent(parent, resolvedOptions, unsetKeys, pmRoot)
 }
 /** Normalize and locate a new item's parent reference, returning the normalized value plus any never-blocking missing-parent warnings the configured `parent_reference` policy produces when the target does not resolve. */
 async function validateCreateParentReference(pmRoot, settings, typeRegistry, itemId, parent, policy) {
-    const normalized = normalizeParentReferenceValue(parent);
+    const normalized = normalizeItemReference(normalizeParentReferenceValue(parent), settings.id_prefix);
+    if (isExternalDependencyReference(normalized)) {
+        return { parent: normalized, warnings: [] };
+    }
     assertParentReferenceIsNotSelf(itemId, normalized, settings.id_prefix);
     const parentLocated = await locateItem(pmRoot, normalized, settings.id_prefix, settings.item_format, typeRegistry.type_to_folder);
     if (parentLocated) {
@@ -1618,7 +1615,7 @@ async function writeCreatedItem(params) {
 export async function runCreate(options, global) {
     let resolvedOptions = normalizeLegacyNoneCreateOptions(await resolveCreateTransportInputs(options));
     const pmRoot = resolvePmRoot(process.cwd(), global.path);
-    await ensureInitHasRun(pmRoot);
+    await assertInitializedTracker(pmRoot);
     const settings = await readSettings(pmRoot);
     const statusRegistry = resolveRuntimeStatusRegistry(settings.schema);
     const runtimeFieldRegistry = resolveRuntimeFieldRegistry(settings.schema);
@@ -1683,7 +1680,7 @@ export async function runCreate(options, global) {
         ? parseStatusValue(resolvedOptions.status, statusRegistry)
         : resolveCreateDefaultStatus(typeDefinition, statusRegistry);
     const priority = resolvedOptions.priority !== undefined
-        ? ensurePriority(resolvedOptions.priority)
+        ? resolvePriority(resolvedOptions.priority)
         : 2;
     const unsetKeys = unsetTargets.metadataKeys;
     const tags = resolveCreateTags(unsetKeys, resolvedOptions);
@@ -1950,4 +1947,4 @@ export const _testOnlyCreateCommand = {
     typeOptionExampleValue,
 };
 //# sourceMappingURL=create.js.map
-//# debugId=c9bfbfd4-3d34-5fa7-b264-6bf9ed5f7f81
+//# debugId=44240cea-9996-5f86-acc5-ac0cfa71c586

package/dist/sdk/lifecycle/restore.d.ts

@@ -25,6 +25,7 @@ export interface RestoreResult {
         kind: "version" | "timestamp";
         target: string;
         history_index: number;
+        version: number | null;
         entry_ts: string;
         entry_op: string;
     };

package/dist/sdk/lifecycle/restore.js

@@ -4,13 +4,22 @@
  * Implements the SDK-owned restore lifecycle operation 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]="db5f3a6d-9ae5-5f9b-bedf-766b2b79324c")}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]="7a3effef-6ba8-51ba-ae99-436d4ef69813")}catch(e){}}();
 import { assertInitializedTracker } from "../environment/tracker-preflight.js";
 import jsonPatch from "fast-json-patch";
 import fs from "node:fs/promises";
-import { pathExists, readFileIfExists, writeFileAtomic, appendHistoryEntry, createHistoryEntry, replayToCanonicalItemDocument, replayToItemDocument, toReplayDocument, enforceHistoryStreamPolicyForItem, normalizeItemId, normalizeRawItemId, canonicalDocument, serializeItemDocument, resolveItemTypeRegistry, acquireLock, EXIT_CODE, PmCliError, nowIso, getActiveExtensionRegistrations, projectAfterCommandItemSnapshot, recordAfterCommandAffectedItem, runActiveOnWriteHooks, runActiveBeforeMutationHooks, locateItem, createMutationGuardSdk, readLocatedItem, getHistoryPath, getItemPath, resolvePmRoot, readSettings, resolveAuthor, } from "../runtime-primitives.js";
+import { readLocatedItemSnapshot } from "../../core/store/item-store.js";
+import { historyVersionOffset } from "../../core/history/version-address.js";
+import { pathExists, readFileIfExists, writeFileAtomic, appendHistoryEntry, createHistoryEntry, replayToCanonicalItemDocument, replayToItemDocument, toReplayDocument, enforceHistoryStreamPolicyForItem, normalizeItemId, normalizeRawItemId, canonicalDocument, serializeItemDocument, resolveItemTypeRegistry, acquireLock, EXIT_CODE, PmCliError, nowIso, getActiveExtensionRegistrations, projectAfterCommandItemSnapshot, recordAfterCommandAffectedItem, runActiveOnWriteHooks, runActiveBeforeMutationHooks, locateItem, createMutationGuardSdk, getHistoryPath, getItemPath, resolvePmRoot, readSettings, resolveAuthor, } from "../runtime-primitives.js";
 import { applyHistoryPatch, ensureMaterializedHistoryTarget as ensureMaterializedRestoreTarget, extractPatchFailureContext, readHistoryEntries, replayHistoryToTarget as replayToTarget, resolveHistoryTarget, } from "../history-read.js";
 import { acquireItemMetadataDerivedIndexLock, refreshItemMetadataDerivedIndex, } from "../item-metadata-index.js";
+/** Read a restore input without discarding unreadable bytes needed for rollback. */
+async function readRestoreItem(located, settings, history) {
+    const snapshot = await readLocatedItemSnapshot(located, { schema: settings.schema });
+    return snapshot.error === null
+        ? { raw: snapshot.raw, document: snapshot.document }
+        : { raw: snapshot.raw, document: replayCurrentDocument(history), recovered: true };
+}
 /** Resolve restore targets with the command's established wording and at-or-before timestamp semantics. */
 function ensureReplayTarget(target, history) {
     return resolveHistoryTarget(target, history, {
@@ -82,6 +91,7 @@ function changedFields(beforeDocument, afterDocument) {
     }
     return Array.from(fields).sort((a, b) => a.localeCompare(b));
 }
+/** Reload item and history under the caller's lock, refusing changes since the recovery snapshot. */
 async function loadRestoreStateUnderLock(params) {
     const historyRawUnderLock = await readFileIfExists(params.subject.historyPath);
     if (historyRawUnderLock !== params.historyRawBeforeLock) {
@@ -89,9 +99,7 @@ async function loadRestoreStateUnderLock(params) {
     }
     const locatedUnderLock = await locateItem(params.pmRoot, params.resolvedId, params.settings.id_prefix, params.settings.item_format, params.typeToFolder);
     const loadedItemUnderLock = locatedUnderLock
-        ? await readLocatedItem(locatedUnderLock, {
-            schema: params.settings.schema,
-        })
+        ? await readRestoreItem(locatedUnderLock, params.settings, params.history)
         : null;
     if ((loadedItemUnderLock?.raw ?? null) !== params.currentItemRawBeforeLock) {
         throw new PmCliError(`Item ${params.resolvedId} changed while waiting for lock; retry restore.`, EXIT_CODE.CONFLICT);
@@ -183,7 +191,7 @@ export async function runRestore(id, target, options, global) {
         throw new PmCliError(`Restore target resolved to item ${restoredDocument.metadata.id}, expected ${resolvedId}.`, EXIT_CODE.GENERIC_FAILURE);
     }
     const loadedItemBeforeLock = subject.located
-        ? await readLocatedItem(subject.located, { schema: settings.schema })
+        ? await readRestoreItem(subject.located, settings, history)
         : null;
     const currentItemRawBeforeLock = loadedItemBeforeLock?.raw ?? null;
     const author = resolveAuthor(options.author, settings.author_default);
@@ -197,6 +205,7 @@ export async function runRestore(id, target, options, global) {
             typeToFolder: typeRegistry.type_to_folder,
             historyRawBeforeLock,
             currentItemRawBeforeLock,
+            history,
         });
         const itemFormat = "toon";
         const currentState = resolveRestoreCurrentState(loadedItemUnderLock, history);
@@ -282,17 +291,20 @@ export async function runRestore(id, target, options, global) {
             changed_fields: restoreChangedFields,
         });
         const targetEntry = history[resolvedTarget.historyIndex];
+        const offset = historyVersionOffset(history, true);
         return {
             item: restoredDocument.metadata,
             restored_from: {
                 kind: resolvedTarget.kind,
                 target: resolvedTarget.raw,
                 history_index: resolvedTarget.historyIndex + 1,
+                version: offset === null ? null : offset + resolvedTarget.historyIndex + 1,
                 entry_ts: targetEntry.ts,
                 entry_op: targetEntry.op,
             },
             changed_fields: restoreChangedFields,
             warnings: [
+                ...(loadedItemUnderLock?.recovered ? ["restore_unreadable_item_recovered"] : []),
                 ...subject.historyPolicyWarnings,
                 ...ownershipWarnings,
                 ...derivedIndexWarnings,
@@ -316,4 +328,4 @@ export const _testOnlyRestoreCommand = {
     resolveRestoreSubject,
 };
 //# sourceMappingURL=restore.js.map
-//# debugId=db5f3a6d-9ae5-5f9b-bedf-766b2b79324c
+//# debugId=7a3effef-6ba8-51ba-ae99-436d4ef69813

package/dist/sdk/lifecycle/update.js

@@ -4,7 +4,7 @@
  * Implements the pm update 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]="78f8b369-1802-555d-a8cc-0147c0d8fb08")}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]="5a6614ac-62fd-5680-9eed-447bfb7a167f")}catch(e){}}();
 import { assertInitializedTracker } from "../environment/tracker-preflight.js";
 import { resolveMutationStdinTokenFields } from "../../core/item/parse.js";
 import { COMMON_MUTATION_COMMAND_OPTION_KEYS, canonicalizeCommandOptionKey, commandOptionFlagLabel, resolveItemTypeRegistry, resolveCommandOptionPolicyState, resolveTypeDefinition, resolveTypeName, validateTypeOptions, normalizeItemId, toItemRecord, buildInvalidTypeError, assertParentReferenceIsNotSelf, normalizeParentReferenceValue, validateMissingParentReference, validateSprintOrReleaseValue, applyAcceptanceCriteriaMutations, applyTagRemovals, assertNoUnknownCsvKeys, looksLikeGenericKeyValueEntry, mergeAdditiveTags, parseCsvKv, parseOptionalNonNegativeInteger, parseOptionalNumber, parseTags, shouldResolveMutationStdinTokens, transferMutationStdinTokenPolicy, splitAcceptanceCriteria, resolvePriority, normalizeStatusInput, isTerminalStatus, collectRuntimeUpdateFieldValues, resolveItemTypesFilePath, resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, describeAllowedTransitions, evaluateTransition, resolveTypeWorkflows, EXIT_CODE, PmCliError, stableValueEquals, resolveIsoOrRelative, getActiveExtensionRegistrations, collectRegisteredItemFieldNames, applyRegisteredItemFieldDefaultsAndValidation, parseRegisteredItemFieldAssignments, buildItemNotFoundError, listAllItemMetadataLight, locateItem, readLocatedItem, resolvePmRoot, readSettings, resolveAuthor, } from "../runtime-primitives.js";
@@ -15,7 +15,7 @@ import { applyLegacyNoneCollectionNormalizers, createLegacyNoneCollectionNormali
 import { ensureEnumValue as ensureEnum } from "./recurrence-parsers.js";
 import { parseEventEntries, parseReminderEntries, parseTypeOptionEntries, } from "./repeatable-metadata-parsers.js";
 import { assertDependencyEdgesAllowed, assertDependencyTargetsResolvable, assertValidBareDependencyFlagValue, } from "../dependency-flag-validation.js";
-import { normalizeDependencySeedId, normalizeDependencySourceKind, } from "../dependency-provenance.js";
+import { normalizeDependencySeedId, normalizeItemReference, isExternalDependencyReference, normalizeDependencySourceKind, } from "../dependency-provenance.js";
 import { resolveCanonicalRelationshipKind } from "../relationships.js";
 import { collectNewOrderingCycleWarnings } from "../graph/mutation-advisory.js";
 import { assertHierarchyMutationAllowed } from "../graph/hierarchy-integrity.js";
@@ -619,9 +619,6 @@ function matchesDependencySelector(value, selector) {
     }
     return true;
 }
-function ensurePriority(raw) {
-    return resolvePriority(raw);
-}
 function normalizeUpdatePolicyOptionKey(raw, typeName) {
     const canonical = canonicalizeCommandOptionKey("update", raw);
     if (!canonical) {
@@ -1152,9 +1149,6 @@ function assertUpdateHierarchyIntegrity(params) {
         return;
     assertHierarchyMutationAllowed(params.before, params.before.map((item) => item.id === params.document.metadata.id ? params.document.metadata : item), params.document.metadata.id, (status) => isTerminalStatus(status, params.statusRegistry), resolveWorkspaceRelationshipKindRegistry());
 }
-async function assertUpdateTrackerInitialized(pmRoot) {
-    await assertInitializedTracker(pmRoot);
-}
 function assertMatchingOrderRank(options) {
     if (options.order !== undefined &&
         options.rank !== undefined &&
@@ -1162,12 +1156,16 @@ function assertMatchingOrderRank(options) {
         throw new PmCliError("--order and --rank must match when both are provided", EXIT_CODE.USAGE);
     }
 }
+/** Canonicalize local parent input before self/existence checks; preserve explicit remote locators and explicit unsets. */
 async function resolveParentReferenceForUpdate(params) {
     if (params.options.parent === undefined ||
         params.unsetTargets.metadataKeys.has("parent")) {
         return { resolvedParentValue: undefined, warnings: [] };
     }
-    const resolvedParentValue = normalizeParentReferenceValue(params.options.parent);
+    const resolvedParentValue = normalizeItemReference(normalizeParentReferenceValue(params.options.parent), params.settings.id_prefix);
+    if (isExternalDependencyReference(resolvedParentValue)) {
+        return { resolvedParentValue, warnings: [] };
+    }
     assertParentReferenceIsNotSelf(params.id, resolvedParentValue, params.settings.id_prefix);
     const parentLocated = await locateItem(params.pmRoot, resolvedParentValue, params.settings.id_prefix, params.settings.item_format, params.typeRegistry.type_to_folder);
     if (parentLocated) {
@@ -1212,6 +1210,7 @@ async function collectWorkflowTransitionWarnings(params) {
     });
     return warning ? [warning] : [];
 }
+/** Delegate the configured close transition to the closure writer, applying other requested fields first and retaining its evidence. */
 async function routeCloseStatusUpdate(context) {
     if (!context.fieldFlags.status) {
         return undefined;
@@ -1349,11 +1348,12 @@ function applyStatusAndCloseReasonMutations(document, context, previousStatusNor
     applyStatusAndCompletionMutations(document, context, previousStatusNormalized, changedFields);
     applyCloseReasonMutations(document, context, previousStatusNormalized, changedFields);
 }
+/** Resolve priority and type changes against runtime registries before enforcing type-specific options and recording changed fields. */
 function applyPriorityTypeAndOptions(document, context, changedFields) {
     let activeTypeName = resolveTypeName(document.metadata.type, context.typeRegistry) ??
         document.metadata.type;
     if (context.options.priority !== undefined) {
-        document.metadata.priority = ensurePriority(context.options.priority);
+        document.metadata.priority = resolvePriority(context.options.priority);
         changedFields.push("priority");
     }
     if (context.options.type !== undefined) {
@@ -1829,7 +1829,7 @@ function mutateUpdateDocument(document, context) {
 async function runUpdateWithContext(id, options, global, execution = {}) {
     options = await resolveUpdateTransportOptions(options);
     const pmRoot = resolvePmRoot(process.cwd(), global.path);
-    await assertUpdateTrackerInitialized(pmRoot);
+    await assertInitializedTracker(pmRoot);
     const settings = await readSettings(pmRoot);
     const statusRegistry = resolveRuntimeStatusRegistry(settings.schema);
     const runtimeFieldRegistry = resolveRuntimeFieldRegistry(settings.schema);
@@ -2134,4 +2134,4 @@ export const _testOnlyUpdateCommand = {
     resolveRuntimeUnsetDefinition: (token, registry) => resolveRuntimeUnsetFieldDefinition(token, "update", registry),
 };
 //# sourceMappingURL=update.js.map
-//# debugId=78f8b369-1802-555d-a8cc-0147c0d8fb08
+//# debugId=5a6614ac-62fd-5680-9eed-447bfb7a167f

package/dist/sdk/lifecycle-policy.d.ts

@@ -1,3 +1,4 @@
+import { type PmCliErrorRecoveryPayload } from "../core/shared/errors.js";
 import type { ItemMetadata } from "../types/index.js";
 /** The author-controlled field from which a terminal reason was derived. */
 export type TerminalReasonSource = "explicit" | "duplicate" | "resolution" | "message" | "none";
@@ -37,6 +38,8 @@ export interface CloseOperationResult {
     item: Record<string, unknown>;
     /** Metadata fields changed by the transition. */
     changed_fields: string[];
+    /** Evidence-only update guidance when a successful warning close leaves acceptance fields missing. */
+    recovery?: PmCliErrorRecoveryPayload;
     /** Validation and lifecycle policy receipts. */
     warnings: string[];
 }

package/dist/sdk/lifecycle-policy.js

@@ -5,7 +5,7 @@
  * item enters a terminal lifecycle state.
  */
 
-!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]="a7ae3c89-b50b-5e4f-8273-8318bc976d84")}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]="89e3f65e-8455-5921-bcc1-45cf572d8585")}catch(e){}}();
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
 /** Default terminal policy shared by CLI, SDK, and MCP operations. */
@@ -118,4 +118,4 @@ export function applyTerminalOrderingPolicy(metadata, policy) {
     };
 }
 //# sourceMappingURL=lifecycle-policy.js.map
-//# debugId=a7ae3c89-b50b-5e4f-8273-8318bc976d84
+//# debugId=89e3f65e-8455-5921-bcc1-45cf572d8585

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

@@ -0,0 +1,15 @@
+/**
+ * @module sdk/merge/abandoned-receipts
+ * Settles verified restored-origin receipts through an explicit history event.
+ */
+import type { GlobalOptions } from "../../core/shared/command-types.js";
+import { type MergeDecisionReceipt } from "./receipts.js";
+/** Preview or record restored-origin dispositions without treating them as applied merges. */
+export declare function settleAbandonedMergeReceipts(params: {
+    cwd: string | null;
+    receipts: readonly MergeDecisionReceipt[];
+    dryRun: boolean;
+    author?: string;
+    message?: string;
+    global: GlobalOptions;
+}): Promise<string[]>;