@unbrained/pm-cli 2026.8.12 → 2026.8.14

package/dist/core/fs/fs-utils.js

@@ -4,7 +4,7 @@
  * Provides filesystem helpers for Fs Utils.
  */
 
-!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]="5aef9dc6-948a-5c82-9e3c-2f85fef46beb")}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]="23fc5fcb-5c80-57ab-8d91-8d15ee35ab53")}catch(e){}}();
 import * as fs from "node:fs/promises";
 import path from "node:path";
 import crypto from "node:crypto";
@@ -33,7 +33,11 @@ export async function pathExists(targetPath) {
  * runtime fault instead of reaching the caller's own root validation.
  */
 export function isFileAbsentError(error) {
-    return isErrno(error, "ENOENT") || isErrno(error, "ENOTDIR");
+    return isFileMissingError(error) || isErrno(error, "ENOTDIR");
+}
+/** Report an exact missing-entry race while preserving ENOTDIR as structural corruption. */
+export function isFileMissingError(error) {
+    return isErrno(error, "ENOENT");
 }
 /** Implements read file if exists for the public runtime surface of this module. */
 export async function readFileIfExists(targetPath) {
@@ -152,4 +156,4 @@ function isErrno(error, code) {
         error.code === code);
 }
 //# sourceMappingURL=fs-utils.js.map
-//# debugId=5aef9dc6-948a-5c82-9e3c-2f85fef46beb
+//# debugId=23fc5fcb-5c80-57ab-8d91-8d15ee35ab53

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

@@ -4,7 +4,8 @@
  * Invalidates derived history-chain verification state after committed writes.
  */
 
-!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]="4db09d54-90c6-548b-baa8-c7ce419f70a2")}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]="5121b339-6594-58ec-b479-11cbf7dafd27")}catch(e){}}();
+import { isFileMissingError } from "../fs/fs-utils.js";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { writeStderr } from "../output/output.js";
@@ -49,7 +50,7 @@ export async function invalidateHistoryDriftCache(pmRoot) {
     }
     catch (error) {
         const errorCode = getFilesystemErrorCode(error);
-        if (errorCode === "ENOENT") {
+        if (isFileMissingError(error)) {
             return;
         }
         const code = errorCode === undefined
@@ -69,4 +70,4 @@ export async function invalidateHistoryDriftCacheForPath(historyPath) {
     await invalidateHistoryDriftCache(path.dirname(historyDirectory));
 }
 //# sourceMappingURL=drift-cache.js.map
-//# debugId=4db09d54-90c6-548b-baa8-c7ce419f70a2
+//# debugId=5121b339-6594-58ec-b479-11cbf7dafd27

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

@@ -11,6 +11,12 @@ export interface DriftScanResult {
     chainMismatches: string[];
     /** Value that configures or reports drifted items for this contract. */
     driftedItems: string[];
+    /** Governed singleton files whose JSON differs from workspace-history replay. */
+    workspaceStateMismatches: string[];
+    /** Governed singleton files absent from disk. */
+    workspaceStateMissing: string[];
+    /** Governed singleton files unreadable as safe workspace-local JSON. */
+    workspaceStateUnreadable: string[];
 }
 /** Controls how cached history stream verification is trusted when the file stat tuple still matches a previous scan. */
 export type DriftCacheHitVerification = "content_hash" | "metadata";

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

@@ -1,13 +1,13 @@
 
-!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]="1bffe32d-543d-588a-a1e9-d72553cab06c")}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]="32538934-2cbb-50fe-b721-ad9197cef7d8")}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 { writeFileAtomic } from "../fs/fs-utils.js";
+import { isFileMissingError, writeFileAtomic } from "../fs/fs-utils.js";
 import { CURRENT_HISTORY_ITEM_HASH_VERSION, hashDocumentForVersion, } from "./history.js";
 import { verifyHistoryChainWithVersion } from "./replay.js";
-import { getWorkspaceHistoryPath, WORKSPACE_HISTORY_ID, } from "./workspace-history.js";
+import { getWorkspaceHistoryPath, inspectWorkspaceHistoryState, WORKSPACE_HISTORY_ID, } from "./workspace-history.js";
 const DRIFT_CACHE_VERSION = 4;
 const DRIFT_CACHE_FILENAME = "history-drift-cache.json";
 function getDriftCachePath(pmRoot) {
@@ -28,12 +28,6 @@ async function loadDriftCache(pmRoot) {
         return null;
     }
 }
-function isErrno(error, code) {
-    return (typeof error === "object" &&
-        error !== null &&
-        "code" in error &&
-        error.code === code);
-}
 async function scanWorkspaceHistory(pmRoot, previousEntries, nextEntries, verifyCacheHitByContent, accumulator) {
     const historyPath = getWorkspaceHistoryPath(pmRoot);
     let stat;
@@ -41,7 +35,7 @@ async function scanWorkspaceHistory(pmRoot, previousEntries, nextEntries, verify
         stat = await fs.stat(historyPath);
     }
     catch (error) {
-        if (isErrno(error, "ENOENT"))
+        if (isFileMissingError(error))
             return false;
         accumulator.unreadableStreams.push(WORKSPACE_HISTORY_ID);
         return false;
@@ -179,6 +173,61 @@ async function resolveStreamVerification(params) {
         cacheDirty: true,
     };
 }
+/** Scan one item stream and return whether its cache entry needs persistence. */
+async function scanItemHistory(pmRoot, item, cache, accumulator) {
+    const historyPath = getHistoryPath(pmRoot, item.id);
+    let stat;
+    try {
+        stat = await fs.stat(historyPath);
+    }
+    catch (error) {
+        (isFileMissingError(error)
+            ? accumulator.missingStreams
+            : accumulator.unreadableStreams).push(item.id);
+        return false;
+    }
+    const resolved = await resolveStreamVerification({
+        itemId: item.id,
+        historyPath,
+        stat,
+        cached: cache.previousEntries[item.id],
+        verifyCacheHitByContent: cache.verifyCacheHitByContent,
+        accumulator,
+    });
+    if (!resolved.verification)
+        return resolved.cacheDirty;
+    if (!resolved.verification.chainOk)
+        accumulator.chainMismatches.push(item.id);
+    cache.nextEntries[item.id] = {
+        mtime_ms: stat.mtimeMs,
+        ctime_ms: stat.ctimeMs,
+        size: stat.size,
+        content_hash: resolved.verification.contentHash,
+        latest_after_hash: resolved.verification.latestAfterHash,
+        chain_ok: resolved.verification.chainOk,
+        item_hash_version: resolved.verification.itemHashVersion,
+    };
+    const { body, ...itemMetadata } = item;
+    const currentHash = hashDocumentForVersion({ metadata: itemMetadata, body }, resolved.verification.itemHashVersion);
+    if (currentHash !== resolved.verification.latestAfterHash)
+        accumulator.hashMismatches.push(item.id);
+    return resolved.cacheDirty;
+}
+/** 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))
+        return;
+    try {
+        const agreement = await inspectWorkspaceHistoryState(pmRoot);
+        accumulator.workspaceStateMismatches.push(...agreement.mismatched_documents);
+        accumulator.workspaceStateMissing.push(...agreement.missing_documents);
+        accumulator.workspaceStateUnreadable.push(...agreement.unreadable_documents);
+    }
+    catch {
+        accumulator.unreadableStreams.push(WORKSPACE_HISTORY_ID);
+    }
+}
 /**
  * Scan every item's history stream for drift (missing/unreadable streams, broken
  * hash chains, and item/history hash mismatches).
@@ -195,6 +244,9 @@ export async function scanHistoryDrift(pmRoot, items, options = {}) {
         unreadableStreams: [],
         hashMismatches: [],
         chainMismatches: [],
+        workspaceStateMismatches: [],
+        workspaceStateMissing: [],
+        workspaceStateUnreadable: [],
     };
     const cache = await loadDriftCache(pmRoot);
     const previousEntries = cache?.entries ?? {};
@@ -203,57 +255,18 @@ export async function scanHistoryDrift(pmRoot, items, options = {}) {
     // Metadata mode does not open a stat-matched stream, so unreadable-after-stat
     // failures are intentionally deferred to strict validate/history-repair scans.
     const verifyCacheHitByContent = options.cacheHitVerification !== "metadata";
+    const cacheState = {
+        previousEntries,
+        nextEntries,
+        verifyCacheHitByContent,
+    };
     for (const item of items) {
-        const historyPath = getHistoryPath(pmRoot, item.id);
-        let stat;
-        try {
-            stat = await fs.stat(historyPath);
-        }
-        catch (error) {
-            if (isErrno(error, "ENOENT")) {
-                accumulator.missingStreams.push(item.id);
-            }
-            else {
-                accumulator.unreadableStreams.push(item.id);
-            }
-            continue;
-        }
-        const cached = previousEntries[item.id];
-        const resolved = await resolveStreamVerification({
-            itemId: item.id,
-            historyPath,
-            stat,
-            cached,
-            verifyCacheHitByContent,
-            accumulator,
-        });
-        cacheDirty ||= resolved.cacheDirty;
-        if (!resolved.verification) {
-            continue;
-        }
-        if (!resolved.verification.chainOk) {
-            accumulator.chainMismatches.push(item.id);
-        }
-        nextEntries[item.id] = {
-            mtime_ms: stat.mtimeMs,
-            ctime_ms: stat.ctimeMs,
-            size: stat.size,
-            content_hash: resolved.verification.contentHash,
-            latest_after_hash: resolved.verification.latestAfterHash,
-            chain_ok: resolved.verification.chainOk,
-            item_hash_version: resolved.verification.itemHashVersion,
-        };
-        const { body, ...itemMetadata } = item;
-        const currentHash = hashDocumentForVersion({
-            metadata: itemMetadata,
-            body,
-        }, resolved.verification.itemHashVersion);
-        if (currentHash !== resolved.verification.latestAfterHash) {
-            accumulator.hashMismatches.push(item.id);
-        }
+        if (await scanItemHistory(pmRoot, item, cacheState, accumulator))
+            cacheDirty = true;
     }
     const workspaceCacheDirty = await scanWorkspaceHistory(pmRoot, previousEntries, nextEntries, verifyCacheHitByContent, accumulator);
     cacheDirty ||= workspaceCacheDirty;
+    await scanWorkspaceStateAgreement(pmRoot, accumulator);
     if (cacheDirty ||
         Object.keys(previousEntries).length !== Object.keys(nextEntries).length) {
         const cachePath = getDriftCachePath(pmRoot);
@@ -271,9 +284,14 @@ export async function scanHistoryDrift(pmRoot, items, options = {}) {
             ...accumulator.unreadableStreams,
             ...accumulator.hashMismatches,
             ...accumulator.chainMismatches,
+            ...(accumulator.workspaceStateMismatches.length > 0 ||
+                accumulator.workspaceStateMissing.length > 0 ||
+                accumulator.workspaceStateUnreadable.length > 0
+                ? [WORKSPACE_HISTORY_ID]
+                : []),
         ]),
     ].sort((a, b) => a.localeCompare(b));
     return { ...accumulator, driftedItems };
 }
 //# sourceMappingURL=drift-scan.js.map
-//# debugId=1bffe32d-543d-588a-a1e9-d72553cab06c
+//# debugId=32538934-2cbb-50fe-b721-ad9197cef7d8

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

@@ -76,6 +76,47 @@ export interface WorkspaceAuditEventOptions {
     /** Maximum lock wait in milliseconds. */
     lockWaitMs: number;
 }
+/** Agreement between the replayed workspace stream and governed singleton files. */
+export interface WorkspaceHistoryStateAgreement {
+    /** Whether every governed singleton is readable and equals its replayed value. */
+    ok: boolean;
+    /** Number of singleton documents represented by the latest replayed state. */
+    document_count: number;
+    /** Governed documents whose on-disk JSON equals the replayed value. */
+    matching_documents: string[];
+    /** Governed documents whose on-disk JSON differs from the replayed value. */
+    mismatched_documents: string[];
+    /** Governed documents absent from disk. */
+    missing_documents: string[];
+    /** Governed documents that cannot be read as safe workspace-local JSON. */
+    unreadable_documents: string[];
+}
+/** Authorized append-only reconciliation of one out-of-band singleton state. */
+export interface WorkspaceJsonReconciliationOptions extends Omit<WorkspaceJsonWriteOptions, "raw" | "recordCreation"> {
+    /** Closed Decision item authorizing acceptance of the on-disk state. */
+    authorizationDecision: string;
+}
+/** Restore one governed singleton from a recorded workspace history version. */
+export interface WorkspaceJsonRestoreOptions extends Omit<WorkspaceJsonWriteOptions, "raw" | "recordCreation"> {
+    /** One-based workspace history version whose document value is restored. */
+    targetVersion: number;
+}
+/** Receipt returned after a singleton is restored from workspace history. */
+export interface WorkspaceJsonRestoreResult {
+    /** Tracker-relative singleton identity. */
+    document_path: string;
+    /** One-based workspace history version used as the restore source. */
+    restored_from_version: number;
+    /** Whether the on-disk singleton and latest history state changed. */
+    changed: boolean;
+}
+/**
+ * Compare every singleton represented by the verified workspace stream with
+ * its current on-disk JSON. Hash-chain verification proves recorded ordering;
+ * this state-agreement check separately proves that every current singleton
+ * mutation is represented by that chain.
+ */
+export declare function inspectWorkspaceHistoryState(pmRoot: string): Promise<WorkspaceHistoryStateAgreement>;
 /**
  * Append one workspace document mutation under the dedicated workspace-history
  * lock. Existing history is verified and replayed before the new entry is
@@ -103,3 +144,21 @@ export declare function mutateWorkspaceJsonWithHistory<Result>(params: Workspace
  * under the workspace-history lock, with compensation if history append fails.
  */
 export declare function writeWorkspaceJsonWithHistory(params: WorkspaceJsonWriteOptions): Promise<boolean>;
+/**
+ * Append an authorized reconciliation event that adopts a reviewed on-disk
+ * singleton after an out-of-band change. The existing stream is never edited:
+ * its latest replayed state becomes the event before-state and the reviewed
+ * singleton becomes the after-state, with the authorizing Decision recorded in
+ * structured context.
+ */
+export declare function reconcileWorkspaceJsonHistory(options: WorkspaceJsonReconciliationOptions): Promise<{
+    changed: boolean;
+    entry?: HistoryEntry;
+    historyPath: string;
+}>;
+/**
+ * Restore one governed JSON singleton to the value recorded at a one-based
+ * workspace history version, then append the restore as a new history state so
+ * replay remains forward-only and independently verifiable.
+ */
+export declare function restoreWorkspaceJsonFromHistory(options: WorkspaceJsonRestoreOptions): Promise<WorkspaceJsonRestoreResult>;

package/dist/core/history/workspace-history.js

@@ -5,7 +5,7 @@
  * HistoryEntry format used by item mutations.
  */
 
-!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]="86b45d6b-2192-5d31-8f73-94d6e6b17dfc")}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]="0f666995-78f8-5741-ae0c-0d792feea599")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { readFileIfExists, writeFileAtomic } from "../fs/fs-utils.js";
@@ -37,14 +37,83 @@ function workspaceDocument(documents, timestamp) {
     };
     return { metadata, body: "" };
 }
-function replayWorkspaceEntries(entries) {
+function replayWorkspaceEntries(entries, count = entries.length) {
     let replay = cloneEmptyReplayDocument();
-    for (const entry of entries) {
+    for (const entry of entries.slice(0, count)) {
         const applied = tryApplyReplayPatch(replay, entry.patch);
         replay = applied.document;
     }
     return replayToItemDocument(replay);
 }
+/** Read the governed document map from one replayed workspace document. */
+function workspaceDocuments(document) {
+    return "documents" in document.metadata &&
+        typeof document.metadata.documents === "object" &&
+        document.metadata.documents !== null &&
+        !Array.isArray(document.metadata.documents)
+        ? document.metadata.documents
+        : {};
+}
+/** Resolve a governed singleton path and reject paths outside the tracker root. */
+function resolveGovernedDocumentPath(pmRoot, filePath) {
+    const absolutePath = path.resolve(filePath);
+    const documentPath = path.relative(pmRoot, absolutePath).replaceAll("\\", "/");
+    if (documentPath.length === 0 ||
+        documentPath === ".." ||
+        documentPath.startsWith("../") ||
+        path.isAbsolute(documentPath)) {
+        throw new TypeError("Workspace history document path must stay inside the tracker root");
+    }
+    return { documentPath, absolutePath };
+}
+/**
+ * Compare every singleton represented by the verified workspace stream with
+ * its current on-disk JSON. Hash-chain verification proves recorded ordering;
+ * this state-agreement check separately proves that every current singleton
+ * mutation is represented by that chain.
+ */
+export async function inspectWorkspaceHistoryState(pmRoot) {
+    const entries = await readHistoryEntries(getWorkspaceHistoryPath(pmRoot), WORKSPACE_HISTORY_ID);
+    const verification = verifyHistoryChain(entries);
+    if (!verification.ok) {
+        throw new TypeError(`Workspace history verification failed: ${verification.errors.join(", ")}`);
+    }
+    const documents = workspaceDocuments(entries.length === 0
+        ? EMPTY_CANONICAL_DOCUMENT
+        : replayWorkspaceEntries(entries));
+    const matching = [];
+    const mismatched = [];
+    const missing = [];
+    const unreadable = [];
+    for (const documentPath of Object.keys(documents).sort()) {
+        let raw;
+        try {
+            const resolved = resolveGovernedDocumentPath(pmRoot, path.resolve(pmRoot, documentPath));
+            raw = await readFileIfExists(resolved.absolutePath);
+            if (raw === null) {
+                missing.push(documentPath);
+                continue;
+            }
+            const current = JSON.parse(raw);
+            (stableStringify(current) === stableStringify(documents[documentPath])
+                ? matching
+                : mismatched).push(documentPath);
+        }
+        catch {
+            unreadable.push(documentPath);
+        }
+    }
+    return {
+        ok: mismatched.length === 0 &&
+            missing.length === 0 &&
+            unreadable.length === 0,
+        document_count: Object.keys(documents).length,
+        matching_documents: matching,
+        mismatched_documents: mismatched,
+        missing_documents: missing,
+        unreadable_documents: unreadable,
+    };
+}
 /**
  * Append one workspace document mutation while the caller holds the dedicated
  * workspace-history lock.
@@ -66,12 +135,7 @@ async function appendWorkspaceHistoryChangeLocked(change) {
     const beforeDocument = entries.length === 0
         ? EMPTY_CANONICAL_DOCUMENT
         : replayWorkspaceEntries(entries);
-    const priorDocuments = "documents" in beforeDocument.metadata &&
-        typeof beforeDocument.metadata.documents === "object" &&
-        beforeDocument.metadata.documents !== null &&
-        !Array.isArray(beforeDocument.metadata.documents)
-        ? beforeDocument.metadata.documents
-        : {};
+    const priorDocuments = workspaceDocuments(beforeDocument);
     const recordedBefore = priorDocuments[change.documentPath];
     if (recordedBefore !== undefined &&
         stableStringify(recordedBefore) !== stableStringify(change.before)) {
@@ -220,5 +284,128 @@ export async function writeWorkspaceJsonWithHistory(params) {
         await release();
     }
 }
+/**
+ * Append an authorized reconciliation event that adopts a reviewed on-disk
+ * singleton after an out-of-band change. The existing stream is never edited:
+ * its latest replayed state becomes the event before-state and the reviewed
+ * singleton becomes the after-state, with the authorizing Decision recorded in
+ * structured context.
+ */
+export async function reconcileWorkspaceJsonHistory(options) {
+    const authorizationDecision = options.authorizationDecision.trim();
+    if (!authorizationDecision) {
+        throw new TypeError("Workspace history reconciliation requires an authorization decision");
+    }
+    const release = await acquireLock(options.pmRoot, "workspace-history", options.lockTtlSeconds, options.author, false, false, options.lockWaitMs);
+    try {
+        const { documentPath, absolutePath } = resolveGovernedDocumentPath(options.pmRoot, options.filePath);
+        const historyPath = getWorkspaceHistoryPath(options.pmRoot);
+        const entries = await readHistoryEntries(historyPath, WORKSPACE_HISTORY_ID);
+        const verification = verifyHistoryChain(entries);
+        if (!verification.ok) {
+            throw new TypeError(`Workspace history verification failed: ${verification.errors.join(", ")}`);
+        }
+        const beforeDocument = replayWorkspaceEntries(entries);
+        const priorDocuments = workspaceDocuments(beforeDocument);
+        if (!Object.hasOwn(priorDocuments, documentPath)) {
+            throw new TypeError(`Workspace history does not govern document ${documentPath}`);
+        }
+        const raw = await readFileIfExists(absolutePath);
+        if (raw === null) {
+            throw new TypeError(`Workspace history document is missing: ${documentPath}`);
+        }
+        const current = JSON.parse(raw);
+        if (stableStringify(priorDocuments[documentPath]) === stableStringify(current)) {
+            return { changed: false, historyPath };
+        }
+        const timestamp = new Date().toISOString();
+        const entry = createHistoryEntry({
+            nowIso: timestamp,
+            author: options.author,
+            op: options.op,
+            before: beforeDocument,
+            after: workspaceDocument({ ...priorDocuments, [documentPath]: current }, beforeDocument.metadata.created_at),
+            message: options.message,
+            context: {
+                reason: "out_of_band_workspace_state_reconciliation",
+                document_path: documentPath,
+                authorization_decision: authorizationDecision,
+            },
+        });
+        await appendHistoryEntry(historyPath, entry);
+        return { changed: true, entry, historyPath };
+    }
+    finally {
+        await release();
+    }
+}
+/**
+ * Restore one governed JSON singleton to the value recorded at a one-based
+ * workspace history version, then append the restore as a new history state so
+ * replay remains forward-only and independently verifiable.
+ */
+export async function restoreWorkspaceJsonFromHistory(options) {
+    const release = await acquireLock(options.pmRoot, "workspace-history", options.lockTtlSeconds, options.author, false, false, options.lockWaitMs);
+    try {
+        const { documentPath, absolutePath } = resolveGovernedDocumentPath(options.pmRoot, options.filePath);
+        const entries = await readHistoryEntries(getWorkspaceHistoryPath(options.pmRoot), WORKSPACE_HISTORY_ID);
+        if (!Number.isInteger(options.targetVersion) ||
+            options.targetVersion < 1 ||
+            options.targetVersion > entries.length) {
+            throw new TypeError(`Invalid workspace history target version: ${String(options.targetVersion)}`);
+        }
+        const verification = verifyHistoryChain(entries);
+        if (!verification.ok) {
+            throw new TypeError(`Workspace history verification failed: ${verification.errors.join(", ")}`);
+        }
+        const target = workspaceDocuments(replayWorkspaceEntries(entries, options.targetVersion))[documentPath];
+        if (target === undefined) {
+            throw new TypeError(`Workspace history version ${options.targetVersion} does not contain ${documentPath}`);
+        }
+        const beforeRaw = await readFileIfExists(absolutePath);
+        const targetRaw = `${JSON.stringify(target, null, 2)}\n`;
+        if (beforeRaw === targetRaw)
+            return {
+                document_path: documentPath,
+                restored_from_version: options.targetVersion,
+                changed: false,
+            };
+        const beforeDocument = replayWorkspaceEntries(entries);
+        const timestamp = new Date().toISOString();
+        const entry = createHistoryEntry({
+            nowIso: timestamp,
+            author: options.author,
+            op: options.op,
+            before: beforeDocument,
+            after: workspaceDocument({ ...workspaceDocuments(beforeDocument), [documentPath]: target }, beforeDocument.metadata.created_at),
+            message: options.message,
+            context: {
+                reason: "workspace_state_restore",
+                document_path: documentPath,
+                restored_from_version: options.targetVersion,
+                replaced_out_of_band_state: true,
+            },
+        });
+        await writeFileAtomic(absolutePath, targetRaw);
+        try {
+            await appendHistoryEntry(getWorkspaceHistoryPath(options.pmRoot), entry);
+        }
+        catch (error) {
+            if (beforeRaw === null)
+                await fs.rm(absolutePath, { force: true });
+            else
+                await writeFileAtomic(absolutePath, beforeRaw);
+            throw error;
+        }
+        return {
+            document_path: documentPath,
+            restored_from_version: options.targetVersion,
+            changed: true,
+        };
+    }
+    finally {
+        await release();
+    }
+}
 //# sourceMappingURL=workspace-history.js.map
-//# debugId=86b45d6b-2192-5d31-8f73-94d6e6b17dfc
+//# debugId=0f666995-78f8-5741-ae0c-0d792feea599

package/dist/core/lock/lock-gc.js

@@ -9,7 +9,8 @@
  * Zero ttl means any lock older than 0 ms is stale. Negative ttl means always stale.
  */
 
-!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]="a026943f-1a46-526b-bfaa-435025c65c2a")}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]="79f9ccbd-48d1-5eb3-82ae-3dd62427041c")}catch(e){}}();
+import { isFileMissingError } from "../fs/fs-utils.js";
 import fs from "node:fs/promises";
 import path from "node:path";
 function parseLock(raw) {
@@ -34,12 +35,6 @@ function parseLock(raw) {
     }
     return { id, owner, created_at, ttl_seconds };
 }
-function isErrno(error, code) {
-    return (typeof error === "object" &&
-        error !== null &&
-        "code" in error &&
-        error.code === code);
-}
 /** Pure classification of one lock file's raw content against `nowMs`. This is the single staleness/parse policy shared by `pm gc --scope locks` (which acts on it) and the `pm health` locks check (which only reports it). */
 export function classifyLockContent(file, raw, nowMs) {
     const lock = parseLock(raw);
@@ -108,7 +103,7 @@ export async function scanLockHealth(pmRoot, now) {
         dirEntries = rawDir.filter((f) => f.endsWith(".lock")).sort();
     }
     catch (error) {
-        if (isErrno(error, "ENOENT")) {
+        if (isFileMissingError(error)) {
             return scan;
         }
         throw error;
@@ -119,7 +114,7 @@ export async function scanLockHealth(pmRoot, now) {
             raw = await fs.readFile(path.join(locksDir, file), "utf8");
         }
         catch (readError) {
-            if (isErrno(readError, "ENOENT")) {
+            if (isFileMissingError(readError)) {
                 // Disappeared between readdir and readFile — treat as a ghost; skip quietly.
                 continue;
             }
@@ -159,7 +154,7 @@ export async function runLockGc(pmRoot, options) {
         dirEntries = raw.filter((f) => f.endsWith(".lock")).sort();
     }
     catch (error) {
-        if (isErrno(error, "ENOENT")) {
+        if (isFileMissingError(error)) {
             return result;
         }
         throw error;
@@ -179,7 +174,7 @@ export async function runLockGc(pmRoot, options) {
             raw = await fs.readFile(absPath, "utf8");
         }
         catch (readError) {
-            if (isErrno(readError, "ENOENT")) {
+            if (isFileMissingError(readError)) {
                 // Disappeared between readdir and readFile — treat as a ghost; skip quietly.
                 result.scanned -= 1;
                 continue;
@@ -223,7 +218,7 @@ export async function runLockGc(pmRoot, options) {
                 await fs.unlink(absPath);
             }
             catch (unlinkError) {
-                if (!isErrno(unlinkError, "ENOENT")) {
+                if (!isFileMissingError(unlinkError)) {
                     result.warnings.push(`lock_remove_failed:${file}`);
                     result.retained.push(relPath);
                     result.entries.push(classified.entry);
@@ -243,4 +238,4 @@ export async function runLockGc(pmRoot, options) {
     return result;
 }
 //# sourceMappingURL=lock-gc.js.map
-//# debugId=a026943f-1a46-526b-bfaa-435025c65c2a
+//# debugId=79f9ccbd-48d1-5eb3-82ae-3dd62427041c