@unbrained/pm-cli 2026.9.4 → 2026.9.5

package/dist/sdk/history/salvage.js

@@ -0,0 +1,248 @@
+/**
+ * @module sdk/history/salvage
+ * Recover an invalid JSONL suffix while preserving every verified prefix byte.
+ */
+
+!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]="49af8ec4-dd6b-56ef-8833-9c776fa35c85")}catch(e){}}();
+import { isUtf8 } from "node:buffer";
+import { readFile } from "node:fs/promises";
+import { isFileMissingError, readFileIfExists, } from "../../core/fs/fs-utils.js";
+import { acquireLock } from "../../core/lock/lock.js";
+import { createHistoryEntry, sealHistoryRecord, } from "../../core/history/history.js";
+import { checkHistoryRewriteOwnership, writeHistoryRawWithRollback, } from "../../core/history/history-rewrite.js";
+import { replayHistoryToTarget } from "../../core/history/projection.js";
+import { replayToItemDocument, verifyHistoryChainWithVersion, } from "../../core/history/replay.js";
+import { findFirstMergeConflictMarker } from "../../core/shared/conflict-markers.js";
+import { EXIT_CODE } from "../../core/shared/constants.js";
+import { PmCliError } from "../../core/shared/errors.js";
+import { sha256Hex } from "../../core/shared/serialization.js";
+import { nowIso } from "../../core/shared/time.js";
+import { runActiveOnReadHooks, runActiveOnWriteHooks, } from "../../core/extensions/index.js";
+import { locateItem, readLocatedItemSnapshot, } from "../../core/store/item-store.js";
+/** Decode a whole record or identify an invalid suffix without hiding a valid record. */
+function decodeSalvageLine(line) {
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch {
+        // A complete record followed by crash padding is not a disposable line.
+        // Refuse instead of silently dropping that record along with the padding.
+        if (line.trimStart().startsWith("{") && line.includes("}")) {
+            throw new PmCliError("History salvage cannot discard a potentially complete record with trailing corruption.", EXIT_CODE.CONFLICT, { code: "history_salvage_refused" });
+        }
+        return null;
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new PmCliError("History salvage would conceal interior corruption or a malformed record.", EXIT_CODE.CONFLICT, { code: "history_salvage_refused" });
+    }
+    const entry = parsed;
+    if (!Array.isArray(entry.patch) ||
+        ![
+            entry.ts,
+            entry.author,
+            entry.op,
+            entry.before_hash,
+            entry.after_hash,
+        ].every((field) => typeof field === "string")) {
+        throw new PmCliError("History salvage requires complete history records before the invalid tail.", EXIT_CODE.CONFLICT, { code: "history_salvage_refused" });
+    }
+    return entry;
+}
+/**
+ * Select a hash-verified prefix. Any parseable JSON after the first invalid
+ * line makes the corruption interior and therefore unsalvageable by truncation.
+ */
+export function inspectHistoryTail(raw) {
+    if (findFirstMergeConflictMarker(raw)) {
+        throw new PmCliError("Resolve history merge conflicts before salvage.", EXIT_CODE.CONFLICT, { code: "history_salvage_refused" });
+    }
+    const entries = [];
+    let offset = 0;
+    let invalidOffset;
+    let invalidLine = 0;
+    for (const [index, line] of raw.split("\n").entries()) {
+        if (!line.trim()) {
+            offset += line.length + 1;
+            continue;
+        }
+        const parsed = decodeSalvageLine(line);
+        if (parsed === null) {
+            if (invalidOffset === undefined) {
+                invalidOffset = offset;
+                invalidLine = index + 1;
+            }
+            offset += line.length + 1;
+            continue;
+        }
+        if (invalidOffset !== undefined) {
+            throw new PmCliError("History salvage would discard a record or conceal interior corruption.", EXIT_CODE.CONFLICT, {
+                code: "history_salvage_refused",
+                required: "Recover the damaged record from version control or a backup; no bytes were changed.",
+            });
+        }
+        entries.push(parsed);
+        offset += line.length + 1;
+    }
+    const verification = verifyHistoryChainWithVersion(entries);
+    if (!verification.ok || verification.item_hash_version === undefined) {
+        throw new PmCliError("History salvage requires a nonempty verified prefix.", EXIT_CODE.CONFLICT, {
+            code: "history_salvage_refused",
+            verification_errors: verification.errors,
+            required: "Recover an intact history prefix from version control or a backup.",
+        });
+    }
+    return {
+        entries,
+        itemHashVersion: verification.item_hash_version,
+        prefix: invalidOffset === undefined ? raw : raw.slice(0, invalidOffset),
+        receipt: invalidOffset === undefined
+            ? null
+            : {
+                first_invalid_line: invalidLine,
+                discarded_bytes: Buffer.byteLength(raw.slice(invalidOffset)),
+                discarded_sha256: sha256Hex(raw.slice(invalidOffset)),
+                retained_entries: entries.length,
+            },
+    };
+}
+/** Prefer the live item's owner; history supplies ownership only when its file is unreadable. */
+async function readSalvageOwnership(subject, settings, fallback) {
+    if (!subject.located)
+        return { itemRaw: null, document: fallback };
+    const snapshot = await readLocatedItemSnapshot(subject.located, {
+        schema: settings.schema,
+    });
+    return { itemRaw: snapshot.raw, document: snapshot.document ?? fallback };
+}
+/** Refuse lossy decoding so suffix receipts and rollback always describe original bytes. */
+async function readSalvageStream(historyPath) {
+    let bytes;
+    try {
+        bytes = await readFile(historyPath);
+    }
+    catch (error) {
+        if (isFileMissingError(error))
+            return null;
+        throw error;
+    }
+    if (!isUtf8(bytes)) {
+        throw new PmCliError("History salvage requires UTF-8 input; recover binary corruption from a byte-preserving backup.", EXIT_CODE.CONFLICT, { code: "history_salvage_refused" });
+    }
+    return bytes.toString("utf8");
+}
+/** Salvage one explicitly selected stream under its normal ownership and lock policy. */
+export async function salvageHistoryTail(params) {
+    const { subject, settings, options, author } = params;
+    if ([
+        options.normalizeProvenance,
+        options.auditOperation,
+        options.auditContext,
+        options.auditContextById,
+        options.forceAuditEntry,
+        options.mergeReceiptProof,
+        options.mergeReceiptProofById,
+    ].some(Boolean)) {
+        throw new PmCliError("Tail salvage cannot be combined with other repair modes.", EXIT_CODE.USAGE);
+    }
+    const raw = await readSalvageStream(subject.historyPath);
+    if (raw === null)
+        throw new PmCliError(`No history stream exists for ${subject.id}.`, EXIT_CODE.NOT_FOUND);
+    await runActiveOnReadHooks({ path: subject.historyPath, scope: "project" });
+    const selected = inspectHistoryTail(raw);
+    const replay = replayHistoryToTarget(selected.entries, selected.entries.length - 1);
+    const document = replayToItemDocument(replay);
+    if (typeof replay.metadata.id === "string" &&
+        replay.metadata.id !== subject.id) {
+        throw new PmCliError("History belongs to another item; salvage refused.", EXIT_CODE.CONFLICT, { code: "history_salvage_refused" });
+    }
+    const ownership = await readSalvageOwnership(subject, settings, document);
+    const warnings = checkHistoryRewriteOwnership({
+        itemDocument: ownership.document,
+        subjectId: subject.id,
+        author,
+        force: options.force,
+        settings,
+    });
+    const version = selected.itemHashVersion;
+    const dryRun = options.dryRun === true;
+    const changed = selected.receipt !== null;
+    if (changed && !dryRun) {
+        const release = await acquireLock(params.pmRoot, subject.id, settings.locks.ttl_seconds, author, Boolean(options.force), settings.governance.force_required_for_stale_lock, settings.locks.wait_ms);
+        try {
+            const currentRaw = await readSalvageStream(subject.historyPath);
+            const located = await locateItem(params.pmRoot, subject.id, settings.id_prefix, settings.item_format, params.typeRegistry.type_to_folder);
+            const currentItem = located
+                ? await readFileIfExists(located.itemPath)
+                : null;
+            if (currentRaw !== raw || currentItem !== ownership.itemRaw) {
+                throw new PmCliError("History or item changed while waiting for salvage lock; retry.", EXIT_CODE.CONFLICT);
+            }
+            const audit = sealHistoryRecord({
+                ...createHistoryEntry({
+                    nowIso: nowIso(),
+                    author,
+                    op: "history_salvage",
+                    before: document,
+                    after: document,
+                    message: options.message,
+                    context: { history_salvage: selected.receipt },
+                }),
+                before_hash: selected.entries.at(-1).after_hash,
+                after_hash: selected.entries.at(-1).after_hash,
+                item_hash_version: version,
+            });
+            await writeHistoryRawWithRollback({
+                historyPath: subject.historyPath,
+                historyRawUnderLock: raw,
+                nextHistoryRaw: `${selected.prefix}${JSON.stringify(audit)}\n`,
+            });
+            warnings.push(...(await runActiveOnWriteHooks({
+                path: subject.historyPath,
+                scope: "project",
+                op: "history_salvage:history",
+            })));
+        }
+        finally {
+            await release();
+        }
+    }
+    return {
+        id: subject.id,
+        dry_run: dryRun,
+        changed,
+        history: {
+            path: subject.historyPath,
+            entries_scanned: selected.entries.length,
+            chain_drift_before: false,
+            entries_rehashed: 0,
+            entries_patch_repaired: 0,
+            converted_replace_to_add: 0,
+            skipped_ops: 0,
+            reconciled_with_item: false,
+            audit_entry_added: changed && !dryRun,
+            verify_ok: true,
+            verify_errors: [],
+            item_hash_version_before: version,
+            item_hash_version_after: version,
+            version_disposition: "preserved",
+        },
+        item: {
+            exists: subject.located !== null,
+            path: subject.located?.itemPath ?? null,
+            matched_chain_before: null,
+        },
+        provenance_normalization: {
+            requested: false,
+            changed: false,
+            events_changed: 0,
+            observations_removed: 0,
+            invalid_values: [],
+        },
+        ...(selected.receipt ? { salvage: selected.receipt } : {}),
+        warnings,
+        generated_at: nowIso(),
+    };
+}
+//# sourceMappingURL=salvage.js.map
+//# debugId=49af8ec4-dd6b-56ef-8833-9c776fa35c85

package/dist/sdk/history-compact.js

@@ -4,16 +4,17 @@
  * Implements the pm history compact 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]="7570ecac-7f15-5a1b-9b2d-2f1744a00720")}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]="26c39ecd-5d72-5cc9-b22b-6abc33fbf4ac")}catch(e){}}();
 import { assertInitializedTracker } from "./environment/tracker-preflight.js";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { createHistoryEntry, hashHistoryStream, resealHistoryRewrite, } from "../core/history/history.js";
+import { createHistoryEntry, hashHistoryStream, sealHistoryRecord, SUPPORTED_HISTORY_ITEM_HASH_VERSIONS, } from "../core/history/history.js";
 import { selectHistoryCompactBulkTargets, } from "../core/history/history-compact-bulk.js";
 import { executeHistoryRewrite, writeHistoryRawWithRollback, } from "../core/history/history-rewrite.js";
-import { cloneEmptyReplayDocument, historyEntriesToRaw, replayHash, replayToItemDocument, toReplayDocument, verifyHistoryChain, } from "../core/history/replay.js";
+import { cloneEmptyReplayDocument, historyEntriesToRaw, replayHashVerificationCandidates, replayToItemDocument, toReplayDocument, verifyHistoryChain, } from "../core/history/replay.js";
 import { applyHistoryPatch } from "../core/history/projection.js";
 import { readHistoryEntries } from "../core/history/read.js";
+import { historyVersionOffset } from "../core/history/version-address.js";
 import { resolveItemTypeRegistry } from "../core/item/type-registry.js";
 import { lifecycleClassifierFromStatusRegistry } from "../core/governance/metadata-coverage.js";
 import { resolveRuntimeStatusRegistry } from "../core/schema/runtime-schema.js";
@@ -29,6 +30,7 @@ import { resolvePmRoot } from "../core/store/paths.js";
 import { readSettings } from "../core/store/settings.js";
 import { resolveAuthor } from "../core/shared/author.js";
 import { resolveHistorySubject } from "./history-redact.js";
+/** Translate a durable version or timestamp boundary into physical compacted and retained counts. */
 function parseBeforeBoundary(before, entries) {
     if (before === undefined) {
         return {
@@ -44,12 +46,13 @@ function parseBeforeBoundary(before, entries) {
     }
     if (/^\d+$/.test(raw)) {
         const version = Number.parseInt(raw, 10);
+        const offset = historyVersionOffset(entries);
         if (!Number.isSafeInteger(version) ||
-            version < 1 ||
-            version > entries.length + 1) {
-            throw new PmCliError(`history-compact --before version must be between 1 and ${entries.length + 1}.`, EXIT_CODE.USAGE);
+            version < offset + 1 ||
+            version > offset + entries.length + 1) {
+            throw new PmCliError(`history-compact --before version must be between ${offset + 1} and ${offset + entries.length + 1}.`, EXIT_CODE.USAGE);
         }
-        const compactCount = Math.max(0, Math.min(entries.length, version - 1));
+        const compactCount = version - offset - 1;
         return {
             kind: "version",
             raw,
@@ -79,18 +82,13 @@ function parseBeforeBoundary(before, entries) {
         retainedCount: entries.length - compactCount,
     };
 }
+/** Fold the already verified stream once, capturing its compaction checkpoint. */
 function replayHistoryAndResolveCheckpoint(entries, compactCount) {
     let replay = cloneEmptyReplayDocument();
     let checkpoint = cloneEmptyReplayDocument();
     for (let index = 0; index < entries.length; index += 1) {
         const entry = entries[index];
-        if (replayHash(replay) !== entry.before_hash) {
-            throw new PmCliError(`history-compact detected before-hash drift at entry ${index + 1}; run pm history-repair first.`, EXIT_CODE.CONFLICT);
-        }
         replay = applyHistoryPatch(replay, entry.patch, index + 1, entry.op);
-        if (replayHash(replay) !== entry.after_hash) {
-            throw new PmCliError(`history-compact detected after-hash drift at entry ${index + 1}; run pm history-repair first.`, EXIT_CODE.CONFLICT);
-        }
         if (index + 1 === compactCount) {
             checkpoint = structuredClone(replay);
         }
@@ -100,23 +98,7 @@ function replayHistoryAndResolveCheckpoint(entries, compactCount) {
         finalReplay: replay,
     };
 }
-function reanchorRetainedEntries(retainedEntries, seed, retainedEntryOffset) {
-    let replay = structuredClone(seed);
-    const rewritten = [];
-    for (const [index, entry] of retainedEntries.entries()) {
-        const beforeHash = replayHash(replay);
-        replay = applyHistoryPatch(replay, entry.patch, retainedEntryOffset + index + 1, entry.op);
-        rewritten.push(resealHistoryRewrite(entry, {
-            ...entry,
-            before_hash: beforeHash,
-            after_hash: replayHash(replay),
-        }));
-    }
-    return {
-        entries: rewritten,
-        finalReplay: replay,
-    };
-}
+/** Snapshot the live item and compare it with the stream's supported historical hash surfaces. */
 async function loadHistoryCompactCurrentItem(subject, settings, historyEntries) {
     const loadedItem = subject.located
         ? await readLocatedItem(subject.located, { schema: settings.schema })
@@ -128,11 +110,12 @@ async function loadHistoryCompactCurrentItem(subject, settings, historyEntries)
             matchedChainBefore: null,
         };
     }
+    const lastEntry = historyEntries[historyEntries.length - 1];
     return {
         loadedItem,
         currentItemRawBeforeLock: loadedItem.raw,
-        matchedChainBefore: replayHash(toReplayDocument(loadedItem.document)) ===
-            historyEntries[historyEntries.length - 1]?.after_hash,
+        matchedChainBefore: SUPPORTED_HISTORY_ITEM_HASH_VERSIONS.some((version) => (lastEntry.item_hash_version === undefined || lastEntry.item_hash_version === version) &&
+            replayHashVerificationCandidates(toReplayDocument(loadedItem.document), version).includes(lastEntry.after_hash)),
     };
 }
 function buildHistoryCompactMessage(options, boundary) {
@@ -151,6 +134,7 @@ function buildHistoryCompactBaselineMessage(boundary) {
     }
     return `history-compact baseline snapshot before ${boundary.raw}.`;
 }
+/** Replace the pruned prefix with a durable-addressed checkpoint while retaining original records and hash semantics. */
 function buildHistoryCompactEntries(params) {
     if (!params.changed) {
         return {
@@ -161,9 +145,9 @@ function buildHistoryCompactEntries(params) {
     }
     const { checkpoint, finalReplay } = replayHistoryAndResolveCheckpoint(params.historyEntries, params.boundary.compactCount);
     const retained = params.historyEntries.slice(params.boundary.compactCount);
-    const reanchored = reanchorRetainedEntries(retained, checkpoint, params.boundary.compactCount);
+    const offset = historyVersionOffset(params.historyEntries, true);
     const baselineEntry = createHistoryEntry({
-        nowIso: nowIso(),
+        nowIso: params.historyEntries[params.boundary.compactCount - 1].ts,
         author: params.author,
         op: "history_compact_baseline",
         before: replayToItemDocument(cloneEmptyReplayDocument()),
@@ -172,6 +156,8 @@ function buildHistoryCompactEntries(params) {
         context: {
             history_compaction: {
                 contract_version: 1,
+                version_offset: offset === null ? null : offset + params.boundary.compactCount - 1,
+                checkpoint_timestamp_semantics: "last_compacted_entry",
                 pruned_entry_count: params.boundary.compactCount,
                 pruned_stream_digest: hashHistoryStream(params.historyEntries.slice(0, params.boundary.compactCount)),
                 retained_proof: "stream_digest_and_checkpoint",
@@ -179,7 +165,15 @@ function buildHistoryCompactEntries(params) {
             },
         },
     });
-    const rewrittenEntries = [baselineEntry, ...reanchored.entries];
+    const checkpointEntry = params.historyEntries[params.boundary.compactCount - 1];
+    // Preserve the checkpoint's epoch and semantic hash variant. Do not introduce
+    // an explicit epoch into an unversioned stream: it would pin later legacy reads.
+    const rewrittenEntries = [sealHistoryRecord({
+            ...baselineEntry,
+            before_hash: params.historyEntries[0].before_hash,
+            after_hash: checkpointEntry.after_hash,
+            item_hash_version: checkpointEntry.item_hash_version,
+        }), ...retained];
     if (!params.dryRun) {
         rewrittenEntries.push(createHistoryEntry({
             nowIso: nowIso(),
@@ -279,7 +273,8 @@ export async function runHistoryCompact(id, options, global) {
             rewrittenEntries,
         })));
     }
-    const firstRetainedEntry = boundary.retainedCount > 0 ? boundary.compactCount + 1 : null;
+    const offset = historyVersionOffset(historyEntries, true);
+    const firstRetainedEntry = boundary.retainedCount > 0 && offset !== null ? offset + boundary.compactCount + 1 : null;
     return {
         id: subject.id,
         dry_run: dryRun,
@@ -530,4 +525,4 @@ export async function runHistoryCompactBulk(options, global) {
     };
 }
 //# sourceMappingURL=history-compact.js.map
-//# debugId=7570ecac-7f15-5a1b-9b2d-2f1744a00720
+//# debugId=26c39ecd-5d72-5cc9-b22b-6abc33fbf4ac

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

@@ -1,6 +1,7 @@
 import { applyHistoryPatch, ensureMaterializedHistoryTarget, extractPatchFailureContext, replayHistoryToTarget, resolveHistoryTarget, type ResolvedHistoryTarget } from "../core/history/projection.js";
 import { readHistoryEntries } from "../core/history/read.js";
 import type { HistoryEntry, ItemDocument } from "../types/index.js";
+export { findHistoryIdentityDiscontinuities, type HistoryIdentityDiscontinuity, } from "../core/history/identity.js";
 /** Workspace resolution controls accepted by {@link getItemAt}. */
 export interface GetItemAtOptions {
     /** Explicit tracker root, equivalent to the CLI global `--pm-path`. */
@@ -14,8 +15,8 @@ export interface GetItemAtResult {
     document: ItemDocument;
     /** Always true, preventing consumers from confusing this with current state. */
     reconstructed: true;
-    /** One-based version included in the projection. */
-    as_of_version: number;
+    /** Durable one-based version; null when a legacy checkpoint lost its mapping. */
+    as_of_version: number | null;
     /** Timestamp of the final included history entry. */
     as_of_timestamp: string;
     /** Normalized target resolution metadata shared with restore. */

package/dist/sdk/history-read.js

@@ -7,11 +7,12 @@
  * systems without acquiring locks or appending history.
  */
 
-!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]="f1ea4209-59d4-53f0-a8ea-2e060e385d14")}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]="6fe766e2-93e8-5653-beb5-16bd92efae51")}catch(e){}}();
 import { assertInitializedTracker } from "./environment/tracker-preflight.js";
 import { getActiveExtensionRegistrations } from "../core/extensions/index.js";
 import { applyHistoryPatch, ensureMaterializedHistoryTarget, extractPatchFailureContext, replayHistoryToTarget, resolveHistoryTarget, } from "../core/history/projection.js";
 import { readHistoryEntries } from "../core/history/read.js";
+import { historyVersionOffset } from "../core/history/version-address.js";
 import { hashDocument, hashDocumentVerificationCandidates, hashEmptyDocument, } from "../core/history/history.js";
 import { replayToCanonicalItemDocument, verifyHistoryChainWithVersion, } from "../core/history/replay.js";
 import { resolveItemTypeRegistry } from "../core/item/type-registry.js";
@@ -20,6 +21,7 @@ import { PmCliError } from "../core/shared/errors.js";
 import { resolvePmRoot } from "../core/store/paths.js";
 import { readSettings } from "../core/store/settings.js";
 import { resolveHistorySubject } from "./history-redact.js";
+export { findHistoryIdentityDiscontinuities, } from "../core/history/identity.js";
 /**
  * Verify a history chain and optionally compare it with a current document.
  *
@@ -80,10 +82,11 @@ export async function getItemAt(id, target, options = {}) {
         throw new PmCliError(`History target resolved to item ${document.metadata.id}, expected ${subject.id}.`, EXIT_CODE.GENERIC_FAILURE);
     }
     const targetEntry = history[resolvedTarget.historyIndex];
+    const offset = historyVersionOffset(history, true);
     return {
         document,
         reconstructed: true,
-        as_of_version: resolvedTarget.historyIndex + 1,
+        as_of_version: offset === null ? null : offset + resolvedTarget.historyIndex + 1,
         as_of_timestamp: targetEntry.ts,
         target: resolvedTarget,
         history_length: history.length,
@@ -91,4 +94,4 @@ export async function getItemAt(id, target, options = {}) {
 }
 export { applyHistoryPatch, ensureMaterializedHistoryTarget, extractPatchFailureContext, readHistoryEntries, replayHistoryToTarget, resolveHistoryTarget, };
 //# sourceMappingURL=history-read.js.map
-//# debugId=f1ea4209-59d4-53f0-a8ea-2e060e385d14
+//# debugId=6fe766e2-93e8-5653-beb5-16bd92efae51

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. */
@@ -36,6 +39,8 @@ export interface HistoryRepairCommandOptions {
 }
 /** 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]="d397bc22-d0ae-5c3d-a1bf-7f4c38ca31be")}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";
@@ -389,6 +390,14 @@ 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 });
+}
+/** 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);
     }
@@ -537,6 +546,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 +620,4 @@ export async function runHistoryRepairAll(options, global) {
     };
 }
 //# sourceMappingURL=history-repair.js.map
-//# debugId=cb0b0e36-3135-5fc4-a0ae-f4e5b974e57f
+//# debugId=d397bc22-d0ae-5c3d-a1bf-7f4c38ca31be

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/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;
     };