@unbrained/pm-cli 2026.8.13 → 2026.8.15

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

@@ -1,5 +1,5 @@
 
-!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]="a6714da6-6e2b-5647-bfde-607a54d7e4cd")}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";
@@ -7,7 +7,7 @@ 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 { 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) {
@@ -173,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).
@@ -189,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 ?? {};
@@ -197,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 (isFileMissingError(error)) {
-                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);
@@ -265,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=a6714da6-6e2b-5647-bfde-607a54d7e4cd
+//# debugId=32538934-2cbb-50fe-b721-ad9197cef7d8

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

@@ -93,8 +93,21 @@ export interface ReanchorResult {
     skippedOps: number;
     /** Value that configures or reports details for this contract. */
     details: ReanchorEntryDetail[];
+    /** Hash epoch retained while rebuilding the stream. */
+    itemHashVersion: HistoryItemHashVersion;
+    /** Whether rewritten entries explicitly carry the hash epoch field. */
+    explicitItemHashVersion: boolean;
 }
+/**
+ * Resolve the hash epoch a repair must retain.
+ *
+ * A valid stream is authoritative even when legacy entries omit the version
+ * field. For a broken stream, one consistent explicit epoch remains
+ * authoritative; fully implicit legacy streams stay on epoch 1. Only an
+ * irreconcilably mixed stream falls forward to the current epoch.
+ */
+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[]): ReanchorResult;
+export declare function reanchorHistoryEntries(entries: HistoryEntry[], itemHashVersion?: 1 | 2): 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]="a1283470-00c7-5e91-8676-e1c1a667537f")}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]="0c37a722-fda7-523e-991c-f8abfb7a1495")}catch(e){}}();
 import jsonPatch from "fast-json-patch";
 import { ITEM_METADATA_KEY_ORDER } from "../shared/constants.js";
 import { canonicalDocument } from "../item/item-format.js";
@@ -219,8 +219,35 @@ export function lenientApplyReplayPatch(current, patch) {
     };
     return { document, convertedReplaceToAdd, skippedOps };
 }
+/**
+ * Resolve the hash epoch a repair must retain.
+ *
+ * A valid stream is authoritative even when legacy entries omit the version
+ * field. For a broken stream, one consistent explicit epoch remains
+ * authoritative; fully implicit legacy streams stay on epoch 1. Only an
+ * irreconcilably mixed stream falls forward to the current epoch.
+ */
+export function resolveHistoryRepairItemHashVersion(entries) {
+    const verified = verifyHistoryChainWithVersion(entries);
+    if (verified.ok && verified.item_hash_version !== undefined) {
+        return verified.item_hash_version;
+    }
+    const explicitVersions = [
+        ...new Set(entries
+            .map((entry) => entry.item_hash_version)
+            .filter((version) => version !== undefined &&
+            SUPPORTED_HISTORY_ITEM_HASH_VERSIONS.includes(version))),
+    ];
+    if (explicitVersions.length === 1) {
+        return explicitVersions[0];
+    }
+    if (explicitVersions.length === 0) {
+        return 1;
+    }
+    return CURRENT_HISTORY_ITEM_HASH_VERSION;
+}
 /** 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) {
+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));
     if (unsupportedIndex >= 0) {
@@ -233,9 +260,11 @@ export function reanchorHistoryEntries(entries) {
     let entriesPatchRepaired = 0;
     let convertedReplaceToAdd = 0;
     let skippedOps = 0;
+    const explicitItemHashVersion = itemHashVersion !== 1 ||
+        entries.some((entry) => entry.item_hash_version !== undefined);
     for (let index = 0; index < entries.length; index += 1) {
         const entry = entries[index];
-        const beforeHash = replayHash(replay, CURRENT_HISTORY_ITEM_HASH_VERSION);
+        const beforeHash = replayHash(replay, itemHashVersion);
         const strict = tryApplyReplayPatch(replay, entry.patch);
         let next;
         let outPatch;
@@ -257,18 +286,24 @@ export function reanchorHistoryEntries(entries) {
             skippedOps += entrySkipped;
             entriesPatchRepaired += 1;
         }
-        const afterHash = replayHash(next, CURRENT_HISTORY_ITEM_HASH_VERSION);
+        const afterHash = replayHash(next, itemHashVersion);
         const rehashed = beforeHash !== entry.before_hash || afterHash !== entry.after_hash;
         if (rehashed) {
             entriesRehashed += 1;
         }
-        rewritten.push({
+        const rewrittenEntry = {
             ...entry,
             patch: outPatch,
             before_hash: beforeHash,
             after_hash: afterHash,
-            item_hash_version: CURRENT_HISTORY_ITEM_HASH_VERSION,
-        });
+        };
+        if (explicitItemHashVersion) {
+            rewrittenEntry.item_hash_version = itemHashVersion;
+        }
+        else {
+            delete rewrittenEntry.item_hash_version;
+        }
+        rewritten.push(rewrittenEntry);
         details.push({
             index: index + 1,
             rehashed,
@@ -286,6 +321,8 @@ export function reanchorHistoryEntries(entries) {
         convertedReplaceToAdd,
         skippedOps,
         details,
+        itemHashVersion,
+        explicitItemHashVersion,
     };
 }
 /** Implements history entries to raw for the public runtime surface of this module. */
@@ -296,4 +333,4 @@ export function historyEntriesToRaw(entries) {
     return `${entries.map((entry) => JSON.stringify(entry)).join("\n")}\n`;
 }
 //# sourceMappingURL=replay.js.map
-//# debugId=a1283470-00c7-5e91-8676-e1c1a667537f
+//# debugId=0c37a722-fda7-523e-991c-f8abfb7a1495

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/output/output.d.ts

@@ -24,6 +24,8 @@ export interface OutputOptions {
     outputFormat?: "toon" | "json";
     /** Caller-carried cross-call budget and served-item state. */
     outputSession?: string;
+    /** Opaque budget-compaction continuation cursor. */
+    outputCursor?: string;
     /** Include machine-readable row location and row-encoding metadata. */
     outputRowContract?: boolean;
     /** Fallback output format used when callers do not provide an override. */

package/dist/core/output/output.js

@@ -4,7 +4,7 @@
  * Formats compact human and machine output for Output.
  */
 
-!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]="5aaf8b90-5b95-5102-9ea4-b877c696d593")}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]="bccd5918-1a51-5258-8d66-1960c51523cf")}catch(e){}}();
 import { getActiveCommandContext, runActiveCommandOverride, runActiveRendererOverride, runActiveServiceOverrideSync, setActiveCommandResult, } from "../extensions/index.js";
 import { EXIT_CODE } from "../shared/constants.js";
 import { isHostOutputSuppressed } from "./output-control.js";
@@ -366,12 +366,21 @@ function formatEffectiveOutput(effectiveResult, nativeOutput, options) {
             ["outputBudget", options.outputBudget],
             ["outputFormat", options.outputFormat],
             ["outputSession", options.outputSession],
+            ["outputCursor", options.outputCursor],
             ["outputRowContract", options.outputRowContract],
         ].filter((entry) => entry[1] !== undefined)),
     };
     const format = resolveReadOutputEncoding(command ?? "", commandOptions) ??
         resolveOutputFormat(options);
-    const effectiveOptions = { ...options, command, commandOptions };
+    const resolvedCommandOptions = {
+        ...commandOptions,
+        resolvedOutputFormat: format,
+    };
+    const effectiveOptions = {
+        ...options,
+        command,
+        commandOptions: resolvedCommandOptions,
+    };
     const service = resolveOutputService(effectiveResult, nativeOutput, effectiveOptions, format);
     if (service.rendered !== null)
         return service.rendered;
@@ -379,7 +388,7 @@ function formatEffectiveOutput(effectiveResult, nativeOutput, options) {
     const projectedOutputResult = command === "test"
         ? projectLinkedTestEvidence(outputResult, options.lean === true)
         : outputResult;
-    const intentOutputResult = attachReadOutputContracts(command, commandOptions, projectedOutputResult);
+    const intentOutputResult = attachReadOutputContracts(command, resolvedCommandOptions, projectedOutputResult);
     const renderResolvedOutput = (value) => {
         if (format === "toon") {
             const markdownDefault = renderDefaultMarkdownResult(value);
@@ -456,4 +465,4 @@ export const outputTestOnly = {
     renderToonValue,
 };
 //# sourceMappingURL=output.js.map
-//# debugId=5aaf8b90-5b95-5102-9ea4-b877c696d593
+//# debugId=bccd5918-1a51-5258-8d66-1960c51523cf

package/dist/core/shared/command-types.d.ts

@@ -29,6 +29,8 @@ export interface GlobalOptions {
     outputFormat?: "toon" | "json";
     /** Caller-carried cross-call budget and served-item state. */
     outputSession?: string;
+    /** Opaque budget-compaction continuation cursor. */
+    outputCursor?: string;
     /** Include the machine-readable row selector and TOON encoding contract. */
     outputRowContract?: boolean;
     /** Filesystem path used for path resolution. */