@unbrained/pm-cli 2026.8.28 → 2026.8.30

package/dist/core/diagnostics/remediation.js

@@ -19,7 +19,7 @@
  */
 /** Registry of every non-extension `pm health` / `pm validate` warning code and its remediation. Extension findings keep their richer, contextual `details.triage.remediation` produced by the extension health triage and are intentionally excluded here (see pm-0hnu: "all non-extension checks"). */
 
-!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]="c088607b-1be3-54c8-a38b-79c188924102")}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]="bb094b44-42b2-5a1c-9fc2-7a0eeaf9fbfd")}catch(e){}}();
 export const REMEDIATION_REGISTRY = Object.freeze([
     // --- pm health: directories ---
     {
@@ -195,8 +195,8 @@ export const REMEDIATION_REGISTRY = Object.freeze([
     },
     {
         code: "merge_receipts_pending",
-        command: "pm merge reconcile --dry-run",
-        summary: "A lossless merge receipt is still pending; preview and run pm merge reconcile so a green health gate certifies receipt settlement, not only intact data.",
+        command: "pm merge reconcile",
+        summary: "A lossless merge receipt is still pending; run pm merge reconcile to settle it (optionally preview first with --dry-run) so a green health gate certifies receipt settlement, not only intact data.",
     },
     {
         code: "merge_receipt_evidence_invalid",
@@ -231,10 +231,15 @@ export const REMEDIATION_REGISTRY = Object.freeze([
         command: "pm history-repair <id>",
         summary: "The item's history chain is broken; re-anchor the chain (pm history-repair --all repairs every drifted stream in one pass).",
     },
+    {
+        code: "history_drift_version_skew",
+        command: "npm install -g @unbrained/pm-cli@latest",
+        summary: "A history stream declares an item hash version this runtime does not support; upgrade pm to verify the chain instead of re-anchoring it.",
+    },
     {
         code: "history_drift_merge_receipt",
-        command: "pm merge reconcile --dry-run",
-        summary: "Canonical path, changed-field, and merged-value hash evidence attributes this drift to a pending receipt; preview reconciliation instead of repairing history directly.",
+        command: "pm merge reconcile",
+        summary: "Canonical path, changed-field, and merged-value hash evidence attributes this drift to a pending receipt; run reconciliation (optionally preview first with --dry-run) instead of repairing history directly.",
     },
     // --- pm health: storage (history compaction policy) ---
     {
@@ -426,6 +431,11 @@ export const REMEDIATION_REGISTRY = Object.freeze([
         command: "pm history-repair <id>",
         summary: "Re-anchor the history chains of the items with a broken history chain.",
     },
+    {
+        code: "validate_history_drift_version_skews",
+        command: "npm install -g @unbrained/pm-cli@latest",
+        summary: "One or more history streams declare an item hash version this runtime does not support; upgrade pm to verify the chains instead of re-anchoring them.",
+    },
     // --- pm validate: command_references ---
     {
         code: "validate_command_references_stale_pm_ids",
@@ -489,4 +499,4 @@ export function buildRemediationCommands(warnings) {
     return Object.values(buildRemediationMap(warnings));
 }
 //# sourceMappingURL=remediation.js.map
-//# debugId=c088607b-1be3-54c8-a38b-79c188924102
+//# debugId=bb094b44-42b2-5a1c-9fc2-7a0eeaf9fbfd

package/dist/core/history/drift-scan.d.ts

@@ -9,6 +9,8 @@ export interface DriftScanResult {
     hashMismatches: string[];
     /** Value that configures or reports chain mismatches for this contract. */
     chainMismatches: string[];
+    /** Streams written with a hash capability newer than this runtime understands. */
+    versionSkews: string[];
     /** Value that configures or reports drifted items for this contract. */
     driftedItems: string[];
     /** Governed singleton files whose JSON differs from workspace-history replay. */

package/dist/core/history/drift-scan.js

@@ -1,14 +1,14 @@
 
-!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]="32538934-2cbb-50fe-b721-ad9197cef7d8")}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]="65c0fed6-315a-5930-a23f-83996d3f5081")}catch(e){}}();
 import fs from "node:fs/promises";
 import { createHash } from "node:crypto";
 import path from "node:path";
 import { getHistoryPath } from "../store/paths.js";
 import { isFileMissingError, writeFileAtomic } from "../fs/fs-utils.js";
-import { CURRENT_HISTORY_ITEM_HASH_VERSION, hashDocumentForVersion, } from "./history.js";
+import { CURRENT_HISTORY_ITEM_HASH_VERSION, SUPPORTED_HISTORY_ITEM_HASH_VERSIONS, hashDocumentForVersion, } from "./history.js";
 import { verifyHistoryChainWithVersion } from "./replay.js";
 import { getWorkspaceHistoryPath, inspectWorkspaceHistoryState, WORKSPACE_HISTORY_ID, } from "./workspace-history.js";
-const DRIFT_CACHE_VERSION = 4;
+const DRIFT_CACHE_VERSION = 7;
 const DRIFT_CACHE_FILENAME = "history-drift-cache.json";
 function getDriftCachePath(pmRoot) {
     return path.join(pmRoot, "runtime", DRIFT_CACHE_FILENAME);
@@ -18,8 +18,17 @@ async function loadDriftCache(pmRoot) {
         const raw = await fs.readFile(getDriftCachePath(pmRoot), "utf8");
         const parsed = JSON.parse(raw);
         if (parsed.version !== DRIFT_CACHE_VERSION ||
+            parsed.history_item_hash_version !== CURRENT_HISTORY_ITEM_HASH_VERSION ||
             typeof parsed.entries !== "object" ||
-            parsed.entries === null) {
+            parsed.entries === null ||
+            Object.values(parsed.entries).some((entry) => typeof entry.chain_ok !== "boolean" ||
+                typeof entry.latest_hash_comparable !== "boolean" ||
+                (!SUPPORTED_HISTORY_ITEM_HASH_VERSIONS.includes(entry.item_hash_version) &&
+                    entry.version_skew !== true) ||
+                (entry.chain_ok &&
+                    entry.version_skew !== true &&
+                    SUPPORTED_HISTORY_ITEM_HASH_VERSIONS.includes(entry.item_hash_version) &&
+                    !entry.latest_hash_comparable))) {
             return null;
         }
         return parsed;
@@ -53,6 +62,9 @@ async function scanWorkspaceHistory(pmRoot, previousEntries, nextEntries, verify
         accumulator.missingStreams.splice(missingCount);
         return resolved.cacheDirty;
     }
+    if (resolved.verification.versionSkew) {
+        accumulator.versionSkews.push(WORKSPACE_HISTORY_ID);
+    }
     if (!resolved.verification.chainOk) {
         accumulator.chainMismatches.push(WORKSPACE_HISTORY_ID);
     }
@@ -63,6 +75,8 @@ async function scanWorkspaceHistory(pmRoot, previousEntries, nextEntries, verify
         content_hash: resolved.verification.contentHash,
         latest_after_hash: resolved.verification.latestAfterHash,
         chain_ok: resolved.verification.chainOk,
+        version_skew: resolved.verification.versionSkew,
+        latest_hash_comparable: resolved.verification.latestHashComparable,
         item_hash_version: resolved.verification.itemHashVersion,
     };
     return resolved.cacheDirty;
@@ -70,10 +84,6 @@ async function scanWorkspaceHistory(pmRoot, previousEntries, nextEntries, verify
 function hashContent(raw) {
     return createHash("sha256").update(raw).digest("hex");
 }
-async function readHistoryContentHash(historyPath) {
-    const raw = await fs.readFile(historyPath, "utf8");
-    return hashContent(raw);
-}
 /** Read and fully verify one history stream's hash chain. Returns null for an empty/missing stream (caller records it as a missing stream). */
 async function verifyHistoryStream(historyPath) {
     const raw = await fs.readFile(historyPath, "utf8");
@@ -102,11 +112,25 @@ async function verifyHistoryStream(historyPath) {
     }
     /* c8 ignore stop */
     const verification = verifyHistoryChainWithVersion(entries);
+    const versionSkew = entries.some((entry) => entry.item_hash_version !== undefined &&
+        !SUPPORTED_HISTORY_ITEM_HASH_VERSIONS.includes(entry.item_hash_version));
+    const latestEntry = entries[entries.length - 1];
+    const latestExplicitVersion = latestEntry.item_hash_version;
+    const latestExplicitVersionSupported = latestExplicitVersion !== undefined &&
+        SUPPORTED_HISTORY_ITEM_HASH_VERSIONS.includes(latestExplicitVersion);
+    const latestHashVersion = latestExplicitVersionSupported
+        ? latestExplicitVersion
+        : verification.item_hash_version;
     return {
         latestAfterHash,
         chainOk: verification.ok,
+        versionSkew,
+        latestHashComparable: latestHashVersion !== undefined &&
+            (!versionSkew ||
+                latestExplicitVersionSupported ||
+                latestExplicitVersion === undefined),
         contentHash,
-        itemHashVersion: verification.item_hash_version ?? CURRENT_HISTORY_ITEM_HASH_VERSION,
+        itemHashVersion: latestHashVersion ?? CURRENT_HISTORY_ITEM_HASH_VERSION,
     };
 }
 function cacheMetadataMatches(cached, stat) {
@@ -143,34 +167,31 @@ async function resolveStreamVerification(params) {
             cacheDirty: true,
         };
     }
-    let currentContentHash;
     if (params.verifyCacheHitByContent) {
-        try {
-            currentContentHash = await readHistoryContentHash(params.historyPath);
-        }
-        catch {
-            params.accumulator.unreadableStreams.push(params.itemId);
-            return { verification: null, cacheDirty: false };
-        }
-    }
-    else {
-        currentContentHash = cachedContentHash;
-    }
-    if (!params.verifyCacheHitByContent ||
-        currentContentHash === cachedContentHash) {
+        const verification = await loadFreshStreamVerification(params.itemId, params.historyPath, params.accumulator);
         return {
-            verification: {
-                latestAfterHash: params.cached.latest_after_hash,
-                chainOk: params.cached.chain_ok,
-                contentHash: currentContentHash,
-                itemHashVersion: params.cached.item_hash_version ?? CURRENT_HISTORY_ITEM_HASH_VERSION,
-            },
-            cacheDirty: false,
+            verification,
+            cacheDirty: verification === null ||
+                verification.contentHash !== cachedContentHash ||
+                verification.latestAfterHash !== params.cached.latest_after_hash ||
+                verification.chainOk !== params.cached.chain_ok ||
+                verification.versionSkew !== (params.cached.version_skew === true) ||
+                verification.latestHashComparable !==
+                    params.cached.latest_hash_comparable ||
+                verification.itemHashVersion !== params.cached.item_hash_version,
         };
     }
     return {
-        verification: await loadFreshStreamVerification(params.itemId, params.historyPath, params.accumulator),
-        cacheDirty: true,
+        verification: {
+            latestAfterHash: params.cached.latest_after_hash,
+            chainOk: params.cached.chain_ok,
+            versionSkew: params.cached.version_skew === true,
+            latestHashComparable: params.cached.latest_hash_comparable &&
+                SUPPORTED_HISTORY_ITEM_HASH_VERSIONS.includes(params.cached.item_hash_version),
+            contentHash: cachedContentHash,
+            itemHashVersion: params.cached.item_hash_version,
+        },
+        cacheDirty: false,
     };
 }
 /** Scan one item stream and return whether its cache entry needs persistence. */
@@ -196,8 +217,12 @@ async function scanItemHistory(pmRoot, item, cache, accumulator) {
     });
     if (!resolved.verification)
         return resolved.cacheDirty;
-    if (!resolved.verification.chainOk)
+    if (resolved.verification.versionSkew) {
+        accumulator.versionSkews.push(item.id);
+    }
+    if (!resolved.verification.chainOk) {
         accumulator.chainMismatches.push(item.id);
+    }
     cache.nextEntries[item.id] = {
         mtime_ms: stat.mtimeMs,
         ctime_ms: stat.ctimeMs,
@@ -205,9 +230,13 @@ async function scanItemHistory(pmRoot, item, cache, accumulator) {
         content_hash: resolved.verification.contentHash,
         latest_after_hash: resolved.verification.latestAfterHash,
         chain_ok: resolved.verification.chainOk,
+        version_skew: resolved.verification.versionSkew,
+        latest_hash_comparable: resolved.verification.latestHashComparable,
         item_hash_version: resolved.verification.itemHashVersion,
     };
     const { body, ...itemMetadata } = item;
+    if (!resolved.verification.latestHashComparable)
+        return resolved.cacheDirty;
     const currentHash = hashDocumentForVersion({ metadata: itemMetadata, body }, resolved.verification.itemHashVersion);
     if (currentHash !== resolved.verification.latestAfterHash)
         accumulator.hashMismatches.push(item.id);
@@ -216,7 +245,8 @@ async function scanItemHistory(pmRoot, item, cache, accumulator) {
 /** Compare the verified workspace stream with every governed singleton file. */
 async function scanWorkspaceStateAgreement(pmRoot, accumulator) {
     if (accumulator.unreadableStreams.includes(WORKSPACE_HISTORY_ID) ||
-        accumulator.chainMismatches.includes(WORKSPACE_HISTORY_ID))
+        accumulator.chainMismatches.includes(WORKSPACE_HISTORY_ID) ||
+        accumulator.versionSkews.includes(WORKSPACE_HISTORY_ID))
         return;
     try {
         const agreement = await inspectWorkspaceHistoryState(pmRoot);
@@ -244,6 +274,7 @@ export async function scanHistoryDrift(pmRoot, items, options = {}) {
         unreadableStreams: [],
         hashMismatches: [],
         chainMismatches: [],
+        versionSkews: [],
         workspaceStateMismatches: [],
         workspaceStateMissing: [],
         workspaceStateUnreadable: [],
@@ -272,7 +303,11 @@ export async function scanHistoryDrift(pmRoot, items, options = {}) {
         const cachePath = getDriftCachePath(pmRoot);
         try {
             await fs.mkdir(path.dirname(cachePath), { recursive: true });
-            await writeFileAtomic(cachePath, JSON.stringify({ version: DRIFT_CACHE_VERSION, entries: nextEntries }));
+            await writeFileAtomic(cachePath, JSON.stringify({
+                version: DRIFT_CACHE_VERSION,
+                history_item_hash_version: CURRENT_HISTORY_ITEM_HASH_VERSION,
+                entries: nextEntries,
+            }));
         }
         catch {
             // Best-effort cache write: a failed persist must never fail a health scan.
@@ -284,6 +319,7 @@ export async function scanHistoryDrift(pmRoot, items, options = {}) {
             ...accumulator.unreadableStreams,
             ...accumulator.hashMismatches,
             ...accumulator.chainMismatches,
+            ...accumulator.versionSkews,
             ...(accumulator.workspaceStateMismatches.length > 0 ||
                 accumulator.workspaceStateMissing.length > 0 ||
                 accumulator.workspaceStateUnreadable.length > 0
@@ -294,4 +330,4 @@ export async function scanHistoryDrift(pmRoot, items, options = {}) {
     return { ...accumulator, driftedItems };
 }
 //# sourceMappingURL=drift-scan.js.map
-//# debugId=32538934-2cbb-50fe-b721-ad9197cef7d8
+//# debugId=65c0fed6-315a-5930-a23f-83996d3f5081

package/dist/core/history/history.d.ts

@@ -1,9 +1,9 @@
 import { type AuthorSource } from "../shared/author.js";
 import type { HistoryEntry, ItemDocument } from "../../types/index.js";
-/** Hash epoch that preserves linked-test insertion order in immutable history. */
-export declare const CURRENT_HISTORY_ITEM_HASH_VERSION: 2;
+/** Hash epoch for the current canonical item surface written into immutable history. */
+export declare const CURRENT_HISTORY_ITEM_HASH_VERSION: 3;
 /** Hash epochs understood by this runtime. */
-export declare const SUPPORTED_HISTORY_ITEM_HASH_VERSIONS: readonly [1, 2];
+export declare const SUPPORTED_HISTORY_ITEM_HASH_VERSIONS: readonly [1, 2, 3];
 /** Restricts item hash versions accepted by history replay. */
 export type HistoryItemHashVersion = (typeof SUPPORTED_HISTORY_ITEM_HASH_VERSIONS)[number];
 declare function decodeJsonPointer(path: string): string[];

package/dist/core/history/history.js

@@ -4,7 +4,7 @@
  * Implements append-only history and replay behavior for 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]="f7cf18cb-0068-58ad-bd7f-759a5d91eb9f")}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]="8581413f-e74e-5db3-86bf-5e39290de741")}catch(e){}}();
 import jsonPatch from "fast-json-patch";
 import { ITEM_METADATA_KEY_ORDER } from "../shared/constants.js";
 import { runActiveServiceOverride } from "../extensions/index.js";
@@ -20,10 +20,10 @@ const EMPTY_LEGACY_HASH_DOCUMENT = {
     front_matter: {},
     body: "",
 };
-/** Hash epoch that preserves linked-test insertion order in immutable history. */
-export const CURRENT_HISTORY_ITEM_HASH_VERSION = 2;
+/** Hash epoch for the current canonical item surface written into immutable history. */
+export const CURRENT_HISTORY_ITEM_HASH_VERSION = 3;
 /** Hash epochs understood by this runtime. */
-export const SUPPORTED_HISTORY_ITEM_HASH_VERSIONS = [1, 2];
+export const SUPPORTED_HISTORY_ITEM_HASH_VERSIONS = [1, 2, 3];
 function compareOptionalStrings(left, right) {
     return (left ?? "").localeCompare(right ?? "");
 }
@@ -292,4 +292,4 @@ export const _testOnly = {
     isDefinedPointerPath,
 };
 //# sourceMappingURL=history.js.map
-//# debugId=f7cf18cb-0068-58ad-bd7f-759a5d91eb9f
+//# debugId=8581413f-e74e-5db3-86bf-5e39290de741

package/dist/core/history/replay.d.ts

@@ -108,6 +108,6 @@ export interface ReanchorResult {
  */
 export declare function resolveHistoryRepairItemHashVersion(entries: HistoryEntry[]): HistoryItemHashVersion;
 /** Re-anchor a drifted history chain: replay every entry from empty, recompute the before/after hashes, and only rewrite a patch when the original op set no longer strictly applies (legacy drift). Clean entries keep their patch verbatim so the on-disk diff stays minimal. The returned chain verifies via verifyHistoryChain. */
-export declare function reanchorHistoryEntries(entries: HistoryEntry[], itemHashVersion?: 1 | 2): ReanchorResult;
+export declare function reanchorHistoryEntries(entries: HistoryEntry[], itemHashVersion?: 1 | 2 | 3): ReanchorResult;
 /** Implements history entries to raw for the public runtime surface of this module. */
 export declare function historyEntriesToRaw(entries: HistoryEntry[]): string;

package/dist/core/history/replay.js

@@ -4,7 +4,7 @@
  * Implements append-only history and replay behavior for Replay.
  */
 
-!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]="bf8797ec-53d3-5d23-8a6e-8296a027ddf2")}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]="c823af51-0cfd-536b-8f85-1f3e72db1c86")}catch(e){}}();
 import jsonPatch from "fast-json-patch";
 import { ITEM_METADATA_KEY_ORDER } from "../shared/constants.js";
 import { canonicalDocument } from "../item/item-format.js";
@@ -132,13 +132,18 @@ function supportedExplicitHistoryItemHashVersions(entries) {
             SUPPORTED_HISTORY_ITEM_HASH_VERSIONS.includes(version))),
     ];
 }
+/** Return whether an explicit hash epoch cannot be replayed by this build. */
+function isUnsupportedExplicitHistoryItemHashVersion(version) {
+    return (version !== undefined &&
+        !SUPPORTED_HISTORY_ITEM_HASH_VERSIONS.includes(version));
+}
 /** Select the hash epochs allowed for one entry under an authoritative stream marker. */
 function historyEntryHashCandidates(explicitVersion, authoritativeVersion) {
     if (explicitVersion !== undefined) {
         return [explicitVersion];
     }
     return authoritativeVersion === undefined
-        ? [1, CURRENT_HISTORY_ITEM_HASH_VERSION]
+        ? [...SUPPORTED_HISTORY_ITEM_HASH_VERSIONS]
         : [authoritativeVersion];
 }
 /** Deterministically verify a history chain: each entry's before_hash must equal the prior replayed after_hash, the patch must strictly apply, and the recorded after_hash must equal the replayed result. */
@@ -147,23 +152,35 @@ export function verifyHistoryChainWithVersion(entries) {
     let replay = cloneEmptyReplayDocument();
     let detectedVersion;
     let authoritativeExplicitVersion;
+    const errors = [];
     for (let index = 0; index < entries.length; index += 1) {
         const entry = entries[index];
         const explicitVersion = entry.item_hash_version;
-        if (explicitVersion !== undefined &&
-            !SUPPORTED_HISTORY_ITEM_HASH_VERSIONS.includes(explicitVersion)) {
-            return {
-                ok: false,
-                errors: [
-                    `verify_failed:unsupported_item_hash_version:${String(explicitVersion)}:entry_${index + 1}`,
-                ],
-            };
+        if (isUnsupportedExplicitHistoryItemHashVersion(explicitVersion)) {
+            errors.push(`verify_failed:unsupported_item_hash_version:${String(explicitVersion)}:entry_${index + 1}`);
+            const applied = tryApplyReplayPatch(replay, entry.patch);
+            if (!applied.ok) {
+                return {
+                    ok: false,
+                    errors: [
+                        ...errors,
+                        `verify_failed:patch_apply_failed:entry_${index + 1}`,
+                    ],
+                };
+            }
+            replay = applied.document;
+            detectedVersion = undefined;
+            authoritativeExplicitVersion = undefined;
+            continue;
         }
         const applied = tryApplyReplayPatch(replay, entry.patch);
         if (!applied.ok) {
             return {
                 ok: false,
-                errors: [`verify_failed:patch_apply_failed:entry_${index + 1}`],
+                errors: [
+                    ...errors,
+                    `verify_failed:patch_apply_failed:entry_${index + 1}`,
+                ],
             };
         }
         // Prefer legacy epoch 1 when an unversioned entry is valid under both
@@ -174,21 +191,36 @@ export function verifyHistoryChainWithVersion(entries) {
         if (beforeMatches.length === 0) {
             return {
                 ok: false,
-                errors: [`verify_failed:before_hash_mismatch:entry_${index + 1}`],
+                errors: [
+                    ...errors,
+                    `verify_failed:before_hash_mismatch:entry_${index + 1}`,
+                ],
             };
         }
         const version = beforeMatches.find((candidate) => replayHash(applied.document, candidate) === entry.after_hash);
         if (version === undefined) {
             return {
                 ok: false,
-                errors: [`verify_failed:after_hash_mismatch:entry_${index + 1}`],
+                errors: [
+                    ...errors,
+                    `verify_failed:after_hash_mismatch:entry_${index + 1}`,
+                ],
             };
         }
         replay = applied.document;
         detectedVersion = version;
-        if (explicitVersion !== undefined) {
-            authoritativeExplicitVersion = version;
-        }
+        authoritativeExplicitVersion =
+            explicitVersion ??
+                authoritativeExplicitVersion;
+    }
+    if (errors.length > 0) {
+        return {
+            ok: false,
+            errors,
+            ...(detectedVersion === undefined
+                ? {}
+                : { item_hash_version: detectedVersion }),
+        };
     }
     return {
         ok: true,
@@ -266,8 +298,7 @@ export function resolveHistoryRepairItemHashVersion(entries) {
 }
 /** Re-anchor a drifted history chain: replay every entry from empty, recompute the before/after hashes, and only rewrite a patch when the original op set no longer strictly applies (legacy drift). Clean entries keep their patch verbatim so the on-disk diff stays minimal. The returned chain verifies via verifyHistoryChain. */
 export function reanchorHistoryEntries(entries, itemHashVersion = resolveHistoryRepairItemHashVersion(entries)) {
-    const unsupportedIndex = entries.findIndex((entry) => entry.item_hash_version !== undefined &&
-        !SUPPORTED_HISTORY_ITEM_HASH_VERSIONS.includes(entry.item_hash_version));
+    const unsupportedIndex = entries.findIndex((entry) => isUnsupportedExplicitHistoryItemHashVersion(entry.item_hash_version));
     if (unsupportedIndex >= 0) {
         throw new TypeError(`unsupported_item_hash_version:${String(entries[unsupportedIndex]?.item_hash_version)}:entry_${unsupportedIndex + 1}`);
     }
@@ -351,4 +382,4 @@ export function historyEntriesToRaw(entries) {
     return `${entries.map((entry) => JSON.stringify(entry)).join("\n")}\n`;
 }
 //# sourceMappingURL=replay.js.map
-//# debugId=bf8797ec-53d3-5d23-8a6e-8296a027ddf2
+//# debugId=c823af51-0cfd-536b-8f85-1f3e72db1c86

package/dist/core/item/actionability.d.ts

@@ -18,9 +18,15 @@ export interface ResolvedBlocker {
     status: ItemStatus | null;
     /** True when the blocker no longer gates work because the referenced item is terminal. */
     resolved: boolean;
+    /** Whether this blocker is a cross-system locator requiring an external resolver. */
+    external?: boolean;
+    /** Last holder mutation timestamp, used as a conservative external-block staleness marker. */
+    blocked_since?: string;
+    /** Resolver identity when an integration resolved this external blocker; null means unverifiable. */
+    resolver?: string | null;
 }
 /** Resolves an item's blockers against a corpus index with reverse `blocks` support. */
-export declare function resolveItemBlockers(item: Pick<ItemMetadata, "blocked_by" | "dependencies">, itemsById: Map<string, ItemMetadata>, statusRegistry: RuntimeStatusRegistry): ResolvedBlocker[];
+export declare function resolveItemBlockers(item: Pick<ItemMetadata, "blocked_by" | "dependencies"> & Partial<Pick<ItemMetadata, "id" | "updated_at">>, itemsById: Map<string, ItemMetadata>, statusRegistry: RuntimeStatusRegistry): ResolvedBlocker[];
 /**
  * Collects the normalized (trimmed, lowercased) ids of every corpus item that is
  * blocked under the single shared edge-aware definition: a non-terminal item

package/dist/core/item/actionability.js

@@ -10,8 +10,9 @@
  * `blocked_by` resolution a single source of truth.
  */
 
-!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]="de8a82e1-0b02-5d5a-9086-686529a1ccab")}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]="0605f770-d868-5fe9-a186-45f00d2e93b4")}catch(e){}}();
 import { isTerminalStatus, normalizeStatusForRegistry } from "./status.js";
+import { isExternalDependencyReference, isExternalDependencySourceKind, } from "./dependency-reference.js";
 /** Dependency kind that marks "this item is blocked by the referenced item". */
 const BLOCKED_BY_DEPENDENCY_KIND = "blocked_by";
 /** Reverse dependency kind that marks "this item blocks the referenced item". */
@@ -32,22 +33,32 @@ const NO_ACTIVE_BLOCKER_SENTINEL = "no-active-blocker";
 function normalizeItemId(id) {
     return id.trim().toLowerCase();
 }
+/** Build a collision-safe blocker key without normalizing external identity. */
+function blockerReferenceKey(id, external) {
+    return external ? `external:${id}` : `local:${normalizeItemId(id)}`;
+}
 /** Collects the blocker item ids declared by an item: the legacy scalar `blocked_by` field plus every `blocked_by` dependency edge. Ids are trimmed, de-duplicated, and returned in stable lexicographic order. This is the single source of truth for "what must close before this item can proceed", shared by `pm next` readiness classification and the close-time auto-unblock sweep. */
 export function collectBlockedByIds(item) {
-    const ids = new Set();
-    const scalar = typeof item.blocked_by === "string" ? normalizeItemId(item.blocked_by) : "";
-    if (scalar.length > 0 && scalar !== NO_ACTIVE_BLOCKER_SENTINEL) {
-        ids.add(scalar);
+    const ids = new Map();
+    const scalar = typeof item.blocked_by === "string" ? item.blocked_by.trim() : "";
+    if (scalar.length > 0 &&
+        normalizeItemId(scalar) !== NO_ACTIVE_BLOCKER_SENTINEL) {
+        const external = isExternalDependencyReference(scalar);
+        ids.set(blockerReferenceKey(scalar, external), external ? scalar : normalizeItemId(scalar));
     }
     for (const dependency of item.dependencies ?? []) {
-        const dependencyId = typeof dependency.id === "string" ? normalizeItemId(dependency.id) : "";
+        const dependencyId = typeof dependency.id === "string" ? dependency.id.trim() : "";
         if (dependency.kind === BLOCKED_BY_DEPENDENCY_KIND &&
             dependencyId.length > 0 &&
-            dependencyId !== NO_ACTIVE_BLOCKER_SENTINEL) {
-            ids.add(dependencyId);
+            normalizeItemId(dependencyId) !== NO_ACTIVE_BLOCKER_SENTINEL) {
+            const external = isExternalDependencyReference(dependencyId) ||
+                isExternalDependencySourceKind(dependency.source_kind);
+            ids.set(blockerReferenceKey(dependencyId, external), external
+                ? dependencyId
+                : normalizeItemId(dependencyId));
         }
     }
-    return [...ids].sort((left, right) => left.localeCompare(right));
+    return [...ids.values()].sort((left, right) => left.localeCompare(right));
 }
 /** Build every forward and reverse blocker set in one corpus pass. */
 export function indexBlockedByIds(corpus) {
@@ -92,9 +103,31 @@ function resolveItemBlockersWithIndex(item, itemsById, statusRegistry, blockerId
     const itemWithId = item;
     const blockerIds = typeof itemWithId.id === "string"
         ? (blockerIdsByItem?.get(normalizeItemId(itemWithId.id)) ??
-            collectBlockedByIdsFromCorpus(itemWithId, [...itemsById.values()]))
+            collectBlockedByIdsFromCorpus(itemWithId, [
+                ...itemsById.values(),
+            ]))
         : collectBlockedByIds(item);
+    const structuredExternalBlockerIds = new Set((item.dependencies ?? [])
+        .filter((dependency) => dependency.kind === BLOCKED_BY_DEPENDENCY_KIND &&
+        isExternalDependencySourceKind(dependency.source_kind) &&
+        typeof dependency.id === "string" &&
+        dependency.id.trim().length > 0)
+        .map((dependency) => blockerReferenceKey(dependency.id.trim(), true)));
     return blockerIds.map((id) => {
+        if (isExternalDependencyReference(id) ||
+            structuredExternalBlockerIds.has(blockerReferenceKey(id, true))) {
+            return {
+                id,
+                title: null,
+                status: null,
+                resolved: false,
+                external: true,
+                ...(typeof item.updated_at === "string"
+                    ? { blocked_since: item.updated_at }
+                    : {}),
+                resolver: null,
+            };
+        }
         const blocker = itemsById.get(normalizeItemId(id));
         if (!blocker) {
             return { id, title: null, status: null, resolved: false };
@@ -257,4 +290,4 @@ export function computeActionabilityReport(candidates, corpus, statusRegistry) {
     };
 }
 //# sourceMappingURL=actionability.js.map
-//# debugId=de8a82e1-0b02-5d5a-9086-686529a1ccab
+//# debugId=0605f770-d868-5fe9-a186-45f00d2e93b4

package/dist/core/item/dependency-reference.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @module core/item/dependency-reference
+ *
+ * Classifies dependency locators that intentionally resolve outside the local
+ * tracker so scheduling and graph governance do not confuse them with typos.
+ */
+/** Return whether a dependency target is an explicit cross-system locator rather than a local pm item id. */
+export declare function isExternalDependencyReference(target: string | undefined): boolean;
+/** Return whether dependency provenance explicitly places a target outside the local workspace. */
+export declare function isExternalDependencySourceKind(sourceKind: string | undefined): boolean;

package/dist/core/item/dependency-reference.js

@@ -0,0 +1,21 @@
+/**
+ * @module core/item/dependency-reference
+ *
+ * Classifies dependency locators that intentionally resolve outside the local
+ * tracker so scheduling and graph governance do not confuse them with typos.
+ */
+/** Return whether a dependency target is an explicit cross-system locator rather than a local pm item id. */
+
+!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]="971d929f-12be-5648-93c9-8a9878b40dde")}catch(e){}}();
+export function isExternalDependencyReference(target) {
+    const normalized = target?.trim() ?? "";
+    return (/^[A-Za-z][A-Za-z0-9+.-]*:\/\//u.test(normalized) ||
+        /^(?:github|gitlab|jira|linear):/iu.test(normalized));
+}
+/** Return whether dependency provenance explicitly places a target outside the local workspace. */
+export function isExternalDependencySourceKind(sourceKind) {
+    const normalized = sourceKind?.trim().toLowerCase();
+    return normalized === "global" || normalized === "external";
+}
+//# sourceMappingURL=dependency-reference.js.map
+//# debugId=971d929f-12be-5648-93c9-8a9878b40dde

package/dist/core/item/parse.d.ts

@@ -1,3 +1,5 @@
+/** Classify plaintext as structured key/value input using an explicit accepted-key vocabulary. */
+export declare function looksLikeStructuredKeyValueEntry(raw: string, keys: readonly string[]): boolean;
 /** Implements parse tags for the public runtime surface of this module. */
 export declare function parseTags(raw: string): string[];
 /** Merge repeated `--add-tags` / `--remove-tags` values into a single normalized tag list. Each entry can itself be CSV or a JSON array, mirroring the format accepted by `--tags`. Returns a deterministically sorted, deduped list. */
@@ -29,6 +31,8 @@ export declare function parseCsvKv(raw: string, optionName: string): Record<stri
  * never misread as a `C=…` key/value entry.
  */
 export declare function looksLikeGenericKeyValueEntry(raw: string): boolean;
+/** Refuse a comma-bearing bare value whose meaning depends on guessing whether the comma separates values or belongs to one value. */
+export declare function assertNoAmbiguousBareCommaEntry(raw: string, optionName: string, noun: string, structured: boolean): void;
 /**
  * Reject any key in a parsed CSV/markdown key/value map that is not part of the
  * caller's allowed-key contract, mirroring the strict `test --add` behavior