dsh-config-manager 0.1.73 → 0.1.77

package/lib/core/messages.d.ts

@@ -177,6 +177,7 @@ export declare const zh: {
     readonly 'host.sessionStoreShapeUnknown': '宿主会话存储列举（sessionPersistence.list()）的元素形状无法解析（探测形状 {shape}，{count} 个元素全部认不出）：父子关系判定放弃，绝不当作「本机没有父子关系」（请升级 DSH，或把该形状反馈给插件）';
     readonly 'host.sessionStorePurposeReindex': '会话 header 重新索引';
     readonly 'host.sessionStorePurposeParentRelations': '父子关系判定';
+    readonly 'host.sessionStorePurposeRewindAttach': '回退子会话归位';
     readonly 'host.sessionStoreListFailed': '会话存储列举失败（{purpose}）：{reason}';
     readonly 'host.sessionStoreListNotArray': '会话存储列举返回非数组（{purpose}）：形状未知，按不可用处理';
     readonly 'host.sessionStorePartialUnresolved': '会话存储列举中有 {count}/{total} 个元素形状无法解析（{purpose}）：已解析的照常使用';

package/lib/core/messages.js

@@ -166,6 +166,7 @@ export const zh = {
     'host.sessionStoreShapeUnknown': '宿主会话存储列举（sessionPersistence.list()）的元素形状无法解析（探测形状 {shape}，{count} 个元素全部认不出）：父子关系判定放弃，绝不当作「本机没有父子关系」（请升级 DSH，或把该形状反馈给插件）',
     'host.sessionStorePurposeReindex': '会话 header 重新索引',
     'host.sessionStorePurposeParentRelations': '父子关系判定',
+    'host.sessionStorePurposeRewindAttach': '回退子会话归位',
     'host.sessionStoreListFailed': '会话存储列举失败（{purpose}）：{reason}',
     'host.sessionStoreListNotArray': '会话存储列举返回非数组（{purpose}）：形状未知，按不可用处理',
     'host.sessionStorePartialUnresolved': '会话存储列举中有 {count}/{total} 个元素形状无法解析（{purpose}）：已解析的照常使用',
@@ -603,6 +604,7 @@ export const en = {
     'host.sessionStoreShapeUnknown': 'Cannot parse the elements returned by the host session store (sessionPersistence.list(); probed shape {shape}, none of the {count} elements is recognizable): parent/child detection is abandoned rather than treated as "no parent relations on this machine" (please upgrade DSH or report this shape to the plugin)',
     'host.sessionStorePurposeReindex': 'session header re-index',
     'host.sessionStorePurposeParentRelations': 'parent/child detection',
+    'host.sessionStorePurposeRewindAttach': 'rewind child session placement',
     'host.sessionStoreListFailed': 'Session store listing failed ({purpose}): {reason}',
     'host.sessionStoreListNotArray': 'Session store listing returned a non-array ({purpose}): unknown shape, treated as unavailable',
     'host.sessionStorePartialUnresolved': 'Session store listing: {count}/{total} elements have an unrecognized shape ({purpose}); the parsed ones are still used',

package/lib/core/rollback-attribution.d.ts

@@ -0,0 +1,81 @@
+/** 台账文件名（与回滚点库同目录：dataDir/rollback-points/attribution.json） */
+export declare const ROLLBACK_ATTRIBUTION_FILE_NAME = "attribution.json";
+/** 条目上限（超出按 at 淘汰最旧）—— 台账无界增长会把宿主拖垮（见 issue #89 的教训） */
+export declare const ROLLBACK_ATTRIBUTION_MAX_ENTRIES = 20000;
+/**
+ * 认得的**写类**工具名。
+ *
+ * 为什么用白名单而不是「参数里有 path 就算写」：`read` / `grep` / `ops_inspect_local_file`
+ * 的参数里也有 path —— 把它们当写入者会让**读**污染归属，进而让回退误跳过本该恢复的文件。
+ */
+export declare const ROLLBACK_WRITE_TOOL_NAMES: readonly string[];
+/** 一条写入归属：谁（会话）在什么时候用哪个工具写了这个路径 */
+export interface RollbackWriteFact {
+    sessionId: string;
+    tool: string;
+    callId: string;
+    /** 毫秒时间戳（本进程时钟） */
+    at: number;
+    turn: number | null;
+}
+/** 引擎只读这一面 */
+export interface RollbackWriteAttributionPort {
+    /** 该路径最后一次的写入归属；undefined = **未判定**（不是「没人写过」） */
+    writerOf(target: string): RollbackWriteFact | undefined;
+}
+/** 采集面（只有留点器的 noteEvent 用得上） */
+export interface RollbackWriteRecorder {
+    /**
+     * 记一次 `tool/call` 事件载荷。返回**记录到的路径条数**：
+     * 0 = 不是写类工具 / 解析不出路径 = **未判定**（绝不代表「没写过」）。
+     */
+    noteToolCall(sessionId: string, data: unknown): number;
+}
+/**
+ * 从一次 `tool/call` 事件载荷里抽出**会被写的路径**。
+ *
+ * `arguments` 在 DSH 的事件里是 **JSON 字符串**（不是对象）——两种形态都收，
+ * 解不出来就返回空数组（= 未判定），绝不抛错。
+ */
+export declare function toolCallWritePaths(name: unknown, argumentsValue: unknown): string[];
+export interface RollbackWriteAttributionOptions {
+    /** 台账文件绝对路径 */
+    file: string;
+    now?: () => number;
+    maxEntries?: number;
+    /** 落盘延迟（毫秒）；<= 0 表示不自动落盘（测试用） */
+    flushDelayMs?: number;
+    warn?: (line: string) => void;
+}
+/**
+ * 内存台账 + best-effort 落盘。
+ *
+ * 落盘的作用只有一个：**进程重启后**打开旧会话回退时，归属还在。
+ * 因此写入是延迟合并的（一次 tool/call 一行，立即落盘会把 I/O 打成筛子）。
+ */
+export declare class RollbackWriteAttribution implements RollbackWriteAttributionPort, RollbackWriteRecorder {
+    private readonly entries;
+    private readonly file;
+    private readonly now;
+    private readonly maxEntries;
+    private readonly flushDelayMs;
+    private readonly warn;
+    private loadPromise;
+    private flushTimer;
+    private writing;
+    constructor(options: RollbackWriteAttributionOptions);
+    /** 台账条目数（测试与诊断用） */
+    get size(): number;
+    /** 惰性读盘（幂等；读失败 = 空表，只 warn） */
+    load(): Promise<void>;
+    private read;
+    /** 记一次 tool/call（返回记录到的路径条数；0 = 不是写类工具或解析不出路径 = 未判定） */
+    noteToolCall(sessionId: string, data: unknown): number;
+    /** 淘汰最旧条目（按 at 升序删到上限内） */
+    private evictOldest;
+    writerOf(target: string): RollbackWriteFact | undefined;
+    /** 延迟落盘（多次调用只落一次） */
+    scheduleFlush(): void;
+    /** 立刻落盘（原子：同目录临时文件 + rename；失败只 warn，绝不上抛） */
+    flush(): Promise<void>;
+}

package/lib/core/rollback-attribution.js

@@ -0,0 +1,236 @@
+/**
+ * 工具调用的**写入归属台账** —— 「这个路径最后一次是哪个会话的哪次工具调用写的」。
+ *
+ * 为什么需要（2026-10-17 用户反馈）：回滚点的「工作区态」是**整个工作区**的快照，
+ * 回退也按整棵树执行 ⇒ 同一工作区里对话 A 改了文件，对话 B 回退时会把 A 的改动一起撤销。
+ * 有了归属，引擎才能在预览里标出「这个文件在留点之后是**别的**会话写的」，
+ * 让界面把它默认排除（用户仍可手动勾回来）。
+ *
+ * 三条不变量（不得放宽）：
+ *  ① 采集**尽力而为**：只有能解析出路径的写类工具（write/edit/ops_replace…）才记。
+ *     `pwsh` / `run_code` / 外部编辑器写的文件**没有归属** ⇒ 查不到 = **未判定**。
+ *  ② **未判定 ≠ 别的会话写的**：只有确知最后写入者是别的会话时才敢标 foreign。
+ *     拿不准就按老口径（照常恢复）—— 少标一次，比误判一次安全。
+ *  ③ 落盘失败只 warn：台账丢了只让归属退化成「未判定」，绝不参与留点 / 回退的成败判定。
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+/** 台账文件名（与回滚点库同目录：dataDir/rollback-points/attribution.json） */
+export const ROLLBACK_ATTRIBUTION_FILE_NAME = 'attribution.json';
+/** 条目上限（超出按 at 淘汰最旧）—— 台账无界增长会把宿主拖垮（见 issue #89 的教训） */
+export const ROLLBACK_ATTRIBUTION_MAX_ENTRIES = 20000;
+/**
+ * 认得的**写类**工具名。
+ *
+ * 为什么用白名单而不是「参数里有 path 就算写」：`read` / `grep` / `ops_inspect_local_file`
+ * 的参数里也有 path —— 把它们当写入者会让**读**污染归属，进而让回退误跳过本该恢复的文件。
+ */
+export const ROLLBACK_WRITE_TOOL_NAMES = [
+    'write',
+    'edit',
+    'ops_replace',
+    'ops_edit',
+    'write_file',
+    'str_replace',
+    'multi_edit',
+    'apply_patch',
+];
+/** 写类工具里代表「目标路径」的参数名（DSH 官方 write/edit 用 file_path；本插件工具用 path） */
+const WRITE_PATH_ARG_KEYS = ['file_path', 'path', 'filePath'];
+/** 路径比较键（与 `rollback-point.ts` 的 pathKey 同一口径：resolve + win32 折叠大小写） */
+function attributionPathKey(value) {
+    const resolved = path.resolve(value);
+    return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+}
+/**
+ * 从一次 `tool/call` 事件载荷里抽出**会被写的路径**。
+ *
+ * `arguments` 在 DSH 的事件里是 **JSON 字符串**（不是对象）——两种形态都收，
+ * 解不出来就返回空数组（= 未判定），绝不抛错。
+ */
+export function toolCallWritePaths(name, argumentsValue) {
+    if (typeof name !== 'string' || !ROLLBACK_WRITE_TOOL_NAMES.includes(name))
+        return [];
+    let parsed = argumentsValue;
+    if (typeof argumentsValue === 'string') {
+        try {
+            parsed = JSON.parse(argumentsValue);
+        }
+        catch {
+            return [];
+        }
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+        return [];
+    const record = parsed;
+    const out = [];
+    for (const key of WRITE_PATH_ARG_KEYS) {
+        const value = record[key];
+        if (typeof value === 'string' && value.trim() !== '')
+            out.push(value);
+    }
+    // 同一个调用里两个键指向同一路径是常见的（别名）⇒ 去重，避免同一路径记两次
+    return [...new Set(out)];
+}
+function readFact(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const record = value;
+    const sessionId = record.sessionId;
+    const at = record.at;
+    if (typeof sessionId !== 'string' || sessionId === '')
+        return null;
+    if (typeof at !== 'number' || !Number.isFinite(at))
+        return null;
+    return {
+        sessionId,
+        at,
+        tool: typeof record.tool === 'string' ? record.tool : '',
+        callId: typeof record.callId === 'string' ? record.callId : '',
+        turn: typeof record.turn === 'number' && Number.isFinite(record.turn) ? record.turn : null,
+    };
+}
+/**
+ * 内存台账 + best-effort 落盘。
+ *
+ * 落盘的作用只有一个：**进程重启后**打开旧会话回退时，归属还在。
+ * 因此写入是延迟合并的（一次 tool/call 一行，立即落盘会把 I/O 打成筛子）。
+ */
+export class RollbackWriteAttribution {
+    entries = new Map();
+    file;
+    now;
+    maxEntries;
+    flushDelayMs;
+    warn;
+    loadPromise = null;
+    flushTimer = null;
+    writing = null;
+    constructor(options) {
+        this.file = path.resolve(options.file);
+        this.now = options.now ?? (() => Date.now());
+        this.maxEntries = Math.max(1, options.maxEntries ?? ROLLBACK_ATTRIBUTION_MAX_ENTRIES);
+        this.flushDelayMs = options.flushDelayMs ?? 1000;
+        this.warn = options.warn ?? (() => { });
+    }
+    /** 台账条目数（测试与诊断用） */
+    get size() {
+        return this.entries.size;
+    }
+    /** 惰性读盘（幂等；读失败 = 空表，只 warn） */
+    async load() {
+        if (this.loadPromise === null)
+            this.loadPromise = this.read();
+        return this.loadPromise;
+    }
+    async read() {
+        try {
+            const text = await fs.readFile(this.file, 'utf8');
+            const parsed = JSON.parse(text);
+            if (parsed.version !== 1 || parsed.entries === null || typeof parsed.entries !== 'object' || Array.isArray(parsed.entries)) {
+                this.warn('rollback attribution ignored (shape): ' + this.file);
+                return;
+            }
+            for (const [key, value] of Object.entries(parsed.entries)) {
+                const fact = readFact(value);
+                // 读盘期间可能已经有本进程新记的条目 ⇒ **新记录优先**（磁盘只是旧快照）
+                if (fact !== null && !this.entries.has(key))
+                    this.entries.set(key, fact);
+            }
+        }
+        catch (error) {
+            const code = error.code;
+            // ENOENT = 还没写过台账（正常）；其它错误如实留痕但不抛
+            if (code !== 'ENOENT')
+                this.warn('rollback attribution unreadable: ' + this.file + ' ' + String(code ?? error));
+        }
+    }
+    /** 记一次 tool/call（返回记录到的路径条数；0 = 不是写类工具或解析不出路径 = 未判定） */
+    noteToolCall(sessionId, data) {
+        if (typeof sessionId !== 'string' || sessionId === '')
+            return 0;
+        if (data === null || typeof data !== 'object')
+            return 0;
+        const record = data;
+        const paths = toolCallWritePaths(record.name, record.arguments);
+        if (paths.length === 0)
+            return 0;
+        const fact = {
+            sessionId,
+            tool: typeof record.name === 'string' ? record.name : '',
+            callId: typeof record.callId === 'string' ? record.callId : '',
+            at: this.now(),
+            turn: typeof record.turn === 'number' && Number.isFinite(record.turn) ? record.turn : null,
+        };
+        for (const target of paths)
+            this.entries.set(attributionPathKey(target), fact);
+        if (this.entries.size > this.maxEntries)
+            this.evictOldest();
+        this.scheduleFlush();
+        return paths.length;
+    }
+    /** 淘汰最旧条目（按 at 升序删到上限内） */
+    evictOldest() {
+        const sorted = [...this.entries.entries()].sort((a, b) => a[1].at - b[1].at);
+        const over = this.entries.size - this.maxEntries;
+        for (let i = 0; i < over; i += 1) {
+            const item = sorted[i];
+            if (item !== undefined)
+                this.entries.delete(item[0]);
+        }
+    }
+    writerOf(target) {
+        return this.entries.get(attributionPathKey(target));
+    }
+    /** 延迟落盘（多次调用只落一次） */
+    scheduleFlush() {
+        if (this.flushDelayMs <= 0 || this.flushTimer !== null)
+            return;
+        this.flushTimer = setTimeout(() => {
+            this.flushTimer = null;
+            void this.flush();
+        }, this.flushDelayMs);
+        this.flushTimer.unref?.();
+    }
+    /** 立刻落盘（原子：同目录临时文件 + rename；失败只 warn，绝不上抛） */
+    async flush() {
+        if (this.writing !== null)
+            return this.writing;
+        this.writing = (async () => {
+            try {
+                await fs.mkdir(path.dirname(this.file), { recursive: true });
+                const entriesSnapshot = Object.fromEntries(this.entries);
+                // **写前合并**（2026-10-17 修）：本进程内存里只有自己见过的写入，而同一个工作区可能同时被
+                // 另一个 DSH 进程写归属 —— 各自「整体覆盖」会把对方的记录抹掉。真机实测：归属里缺了对方
+                // 那次编辑，导致回退时识别不到「别人改过这个文件」，进而把对方的改动静默覆盖掉。
+                // 同键取 `at` 较新者：时间戳是这里唯一可信的先后判据。
+                try {
+                    const existing = JSON.parse(await fs.readFile(this.file, 'utf8'));
+                    if (existing.version === 1 && existing.entries !== null && typeof existing.entries === 'object' && !Array.isArray(existing.entries)) {
+                        for (const [key, value] of Object.entries(existing.entries)) {
+                            const fact = readFact(value);
+                            if (fact === null)
+                                continue;
+                            const mine = entriesSnapshot[key];
+                            if (mine === undefined || fact.at > mine.at)
+                                entriesSnapshot[key] = fact;
+                        }
+                    }
+                }
+                catch { /* 读不到就当没有别人的记录：只写自己这份（绝不因为读失败而放弃落盘） */ }
+                const payload = { version: 1, entries: entriesSnapshot };
+                const tmp = this.file + '.tmp';
+                await fs.writeFile(tmp, JSON.stringify(payload), 'utf8');
+                await fs.rename(tmp, this.file);
+            }
+            catch (error) {
+                this.warn('rollback attribution write failed: ' + this.file + ' ' + String(error.code ?? error));
+            }
+            finally {
+                this.writing = null;
+            }
+        })();
+        return this.writing;
+    }
+}
+//# sourceMappingURL=rollback-attribution.js.map

package/lib/core/rollback-ledger.d.ts

@@ -1,4 +1,4 @@
-import type { RollbackPointKind, RollbackPointRecord, RollbackPointSummary, RollbackSegmentSummary, RollbackStateKind } from './rollback-point.ts';
+import type { RollbackPointKind, RollbackPointRecord, RollbackPointSummary, RollbackSegmentSummary, RollbackStateKind, RollbackWorkspacePayload } from './rollback-point.ts';
 /** 清单格式版本（与**记录**的 schemaVersion 无关：后者是记录内容的版本，恒为 2） */
 export declare const ROLLBACK_LEDGER_SCHEMA_VERSION = 3;
 /** 单条记录目录名 */
@@ -54,6 +54,12 @@ export interface RollbackLedgerManifestEntry {
         payload: string | null;
         /** 载荷文件字节数（**同一哈希只算一次**，预算与统计用） */
         payloadBytes: number;
+        /**
+         * 这份点**解析所需的全部载荷哈希**（自身在前、基准依次在后）。
+         * 增量载荷依赖基准 ⇒ 回收（prunePayloads）必须按链保活，否则链一断这个点就读不出来了。
+         * 老清单没有该字段 ⇒ 视为 `[payload]`（老载荷都是全量、无依赖）。
+         */
+        payloadChain?: string[];
     };
     session: RollbackLedgerTrackHeader & {
         /** 会话字节副本的对象仓键；null = 没有副本（回收对象时用，不必读记录文件） */
@@ -176,14 +182,34 @@ export declare class RollbackLedger {
     /** 原子写清单（小文件；条目由调用方决定） */
     writeManifest(entries: readonly RollbackLedgerManifestEntry[]): Promise<void>;
     /** 把完整记录拆成「清单条目 + 记录文件内容 + 载荷文件内容」（**不做 IO**，纯函数） */
-    prepareRecord(record: RollbackPointRecord): RollbackLedgerPrepared;
+    prepareRecord(record: RollbackPointRecord, reuse?: {
+        hash: string;
+        bytes: number;
+        chain?: string[];
+    }): RollbackLedgerPrepared;
     /**
      * 落盘：载荷（内容寻址；同一哈希已存在则**零写入**）+ 记录文件。
      * 先载荷后记录：中途失败只留一份没人引用的载荷（垃圾，不是坏数据），下次 prune 回收。
      */
     writePrepared(prepared: RollbackLedgerPrepared): Promise<void>;
     /** 读校验过的载荷（哈希不符 / 形状不符 -> error，绝不返回半个） */
-    private readVerifiedPayload;
+    /**
+     * **原始**读取一份载荷（形状校验 + 内容寻址自证）。
+     * `files` 可能只是「相对基准的增量子集」（`payload.delta` 非空）—— **只给解析器用**，
+     * 消费者一律走 {@link resolvePayload} 拿物化后的完整清单。
+     */
+    private readStoredPayload;
+    /**
+     * 解析一份载荷：增量视图**物化**成完整 `files`（含 `object` 字段补回），全量视图原样返回。
+     *
+     * 任何一环不成立（基准缺失 / 哈希不符 / 形状不符 / 链成环）⇒ **如实失败**：绝不返回半个清单 ——
+     * 半份清单会让「留点后新建」的判据把绝大多数文件当成新建的，回退就会删掉它们。
+     */
+    resolvePayload(hash: string): Promise<{
+        payload?: RollbackWorkspacePayload;
+        error?: string;
+    }>;
+    private materializePayload;
     /** 读一条**完整**记录（引用解析对调用方透明）；任何一步不成立就如实失败 */
     readRecord(id: string): Promise<{
         record?: RollbackPointRecord;

package/lib/core/rollback-ledger.js

@@ -490,6 +490,7 @@ export function normalizeManifestEntry(value) {
         return null;
     const rawRecordBytes = value['recordBytes'];
     const rawPayloadBytes = isRecord(workspaceRaw) ? workspaceRaw['payloadBytes'] : 0;
+    const rawPayloadChain = isRecord(workspaceRaw) ? workspaceRaw['payloadChain'] : null;
     return {
         id,
         kind,
@@ -507,6 +508,10 @@ export function normalizeManifestEntry(value) {
             ...workspace,
             payload: typeof wsPayload === 'string' ? wsPayload : null,
             payloadBytes: typeof rawPayloadBytes === 'number' && Number.isFinite(rawPayloadBytes) && rawPayloadBytes >= 0 ? rawPayloadBytes : 0,
+            // 只保留形状合法的哈希；读不回来的链由解析器如实失败（绝不猜）
+            ...(Array.isArray(rawPayloadChain)
+                ? { payloadChain: rawPayloadChain.filter((h) => typeof h === 'string' && OBJECT_KEY_RE.test(h)) }
+                : {}),
         },
         session: { ...session, object: typeof sessionObject === 'string' ? sessionObject : null },
         segments: [first, second],
@@ -532,6 +537,26 @@ function normalizeWorkspacePayload(value) {
         return null;
     return value;
 }
+/**
+ * **存盘**形状校验：完整清单（`files` 是数组）或增量视图（`delta` 是对象、`files` 故意留 null）。
+ * 与 {@link normalizeWorkspacePayload}（消费侧，要求物化后的完整形状）分开：增量载荷**绝不会**被当成完整清单读出去。
+ */
+function normalizeStoredPayload(value) {
+    const base = normalizeWorkspacePayload(value);
+    if (base !== null)
+        return base;
+    if (!isRecord(value))
+        return null;
+    const delta = value['delta'];
+    if (!isRecord(delta))
+        return null;
+    if (typeof delta['base'] !== 'string')
+        return null;
+    if (!Array.isArray(delta['added']) || !Array.isArray(delta['removed']))
+        return null;
+    const clone = { ...value, files: [] };
+    return normalizeWorkspacePayload(clone);
+}
 function normalizeSessionPayload(value) {
     if (!isRecord(value))
         return null;
@@ -743,7 +768,7 @@ export class RollbackLedger {
     }
     /* -------------------------------------------------------- 单条记录 */
     /** 把完整记录拆成「清单条目 + 记录文件内容 + 载荷文件内容」（**不做 IO**，纯函数） */
-    prepareRecord(record) {
+    prepareRecord(record, reuse) {
         const summary = this.summarize(record);
         const workspaceTrack = record.workspace;
         const sessionTrack = record.session;
@@ -751,7 +776,12 @@ export class RollbackLedger {
         let payloadJson = null;
         let payloadHash = null;
         let payloadBytes = 0;
-        if (payload !== null) {
+        if (payload !== null && reuse !== undefined) {
+            // **复用**：这份工作区态与基准点逐条相同 ⇒ 直接引用它已经落盘的载荷（零额外字节，链不增长）
+            payloadHash = reuse.hash;
+            payloadBytes = reuse.bytes;
+        }
+        else if (payload !== null) {
             payloadJson = JSON.stringify(payload);
             payloadHash = sha256Hex(payloadJson);
             payloadBytes = byteLength(payloadJson);
@@ -773,6 +803,14 @@ export class RollbackLedger {
             workspace: { ...trackHeader(workspaceTrack), payload: payloadHash },
             session: { ...trackHeader(sessionTrack), payload: sessionTrack.payload },
         });
+        // 增量视图 ⇒ 清单条目带上「解析所需的全部载荷哈希」（自身 + 基准链），回收按链保活
+        const payloadChain = payloadHash === null
+            ? undefined
+            : reuse !== undefined
+                ? (reuse.chain !== undefined && reuse.chain.length > 0 ? [...reuse.chain] : [payloadHash])
+                : payload?.delta === undefined
+                    ? [payloadHash]
+                    : [payloadHash, ...payload.delta.baseChain];
         const entry = {
             id: record.id,
             kind: record.kind,
@@ -786,7 +824,7 @@ export class RollbackLedger {
             turnSeq: record.turnSeq,
             boundarySeq: record.boundarySeq,
             recordBytes: byteLength(recordJson),
-            workspace: { ...trackHeader(workspaceTrack), payload: payloadHash, payloadBytes },
+            workspace: { ...trackHeader(workspaceTrack), payload: payloadHash, payloadBytes, ...(payloadChain === undefined ? {} : { payloadChain }) },
             session: { ...trackHeader(sessionTrack), object: sessionTrack.payload?.object ?? null },
             segments: summary.segments,
         };
@@ -813,7 +851,12 @@ export class RollbackLedger {
         await this.write(recordFile, Buffer.from(prepared.recordJson, 'utf8'));
     }
     /** 读校验过的载荷（哈希不符 / 形状不符 -> error，绝不返回半个） */
-    async readVerifiedPayload(hash) {
+    /**
+     * **原始**读取一份载荷（形状校验 + 内容寻址自证）。
+     * `files` 可能只是「相对基准的增量子集」（`payload.delta` 非空）—— **只给解析器用**，
+     * 消费者一律走 {@link resolvePayload} 拿物化后的完整清单。
+     */
+    async readStoredPayload(hash) {
         const target = this.payloadPath(hash);
         if (target === null)
             return { error: 'record-incomplete: payload ref invalid' };
@@ -834,11 +877,64 @@ export class RollbackLedger {
         catch (error) {
             return { error: 'record-incomplete: payload unreadable (' + errorDetail(error) + ')' };
         }
-        const payload = normalizeWorkspacePayload(parsed);
+        const payload = normalizeStoredPayload(parsed);
         if (payload === null)
             return { error: 'record-incomplete: payload shape invalid' };
         return { payload };
     }
+    /**
+     * 解析一份载荷：增量视图**物化**成完整 `files`（含 `object` 字段补回），全量视图原样返回。
+     *
+     * 任何一环不成立（基准缺失 / 哈希不符 / 形状不符 / 链成环）⇒ **如实失败**：绝不返回半个清单 ——
+     * 半份清单会让「留点后新建」的判据把绝大多数文件当成新建的，回退就会删掉它们。
+     */
+    async resolvePayload(hash) {
+        // **不缓存**：载荷被删/被改必须立刻看得见（缓存会把「存储已经坏了」蒙过去），
+        // 也守住「一次只驻留一份载荷」的内存护栏（issue #89 的 OOM 现场）。
+        return this.materializePayload(hash, new Set([hash]));
+    }
+    async materializePayload(hash, seen) {
+        const stored = await this.readStoredPayload(hash);
+        if (stored.payload === undefined)
+            return { error: stored.error ?? 'record-incomplete: payload unreadable' };
+        const payload = stored.payload;
+        const delta = payload.delta;
+        if (delta === undefined)
+            return { payload: withObjectRefs(payload) };
+        if (typeof delta.base !== 'string' || !OBJECT_KEY_RE.test(delta.base)) {
+            return { error: 'record-incomplete: delta base ref invalid' };
+        }
+        if (seen.has(delta.base))
+            return { error: 'record-incomplete: delta chain cycle' };
+        const next = new Set(seen);
+        next.add(delta.base);
+        const base = await this.materializePayload(delta.base, next);
+        if (base.payload === undefined) {
+            return { error: 'record-incomplete: delta base unresolved (' + String(base.error ?? '') + ')' };
+        }
+        const removed = new Set();
+        for (const p of Array.isArray(delta.removed) ? delta.removed : [])
+            if (typeof p === 'string')
+                removed.add(p);
+        const added = withObjectRefs({ ...payload, files: delta.added ?? [], delta: undefined }).files;
+        const addedPaths = new Set();
+        for (const file of added)
+            if (typeof file?.path === 'string')
+                addedPaths.add(file.path);
+        const files = [];
+        for (const file of base.payload.files) {
+            if (typeof file?.path !== 'string')
+                continue;
+            if (removed.has(file.path) || addedPaths.has(file.path))
+                continue;
+            files.push(file);
+        }
+        for (const file of added)
+            files.push(file);
+        // 与全量捕获同序（`payload.files.sort` 用的就是这个比较器）
+        files.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+        return { payload: { ...payload, files, delta: undefined } };
+    }
     /** 读一条**完整**记录（引用解析对调用方透明）；任何一步不成立就如实失败 */
     async readRecord(id) {
         const target = this.recordPath(id);
@@ -870,7 +966,7 @@ export class RollbackLedger {
             if (typeof payloadRef !== 'string' || !OBJECT_KEY_RE.test(payloadRef)) {
                 return { error: 'record-incomplete: payload ref invalid' };
             }
-            const resolved = await this.readVerifiedPayload(payloadRef);
+            const resolved = await this.resolvePayload(payloadRef);
             if (resolved.payload === undefined)
                 return { error: resolved.error ?? 'record-incomplete: payload unreadable' };
             payload = resolved.payload;
@@ -935,6 +1031,13 @@ export class RollbackLedger {
     async prunePayloads(entries) {
         const referenced = new Set();
         for (const entry of entries) {
+            // 增量载荷依赖基准 ⇒ **按链保活**（否则淘汰/删点会把基准删掉，那个点就永远读不回来了）
+            const chain = entry.workspace.payloadChain;
+            if (Array.isArray(chain) && chain.length > 0) {
+                for (const hash of chain)
+                    referenced.add(hash);
+                continue;
+            }
             if (entry.workspace.payload !== null)
                 referenced.add(entry.workspace.payload);
         }
@@ -986,7 +1089,7 @@ export class RollbackLedger {
         for (const entry of entries) {
             const hash = entry.workspace.payload;
             if (hash !== null) {
-                const resolved = await this.readVerifiedPayload(hash);
+                const resolved = await this.resolvePayload(hash);
                 if (resolved.payload === undefined) {
                     return { removed: 0, bytes: 0, referencedPaths, aborted: resolved.error ?? 'payload unreadable' };
                 }
@@ -1272,6 +1375,21 @@ function trackHeader(track) {
         reasonDetail: track.reasonDetail,
     };
 }
+/**
+ * 补回**落盘时省掉的** `object` 字段：内容寻址的名字就是内容哈希 ⇒ `object ≡ sha256`。
+ * 缺 `sha256` 的畸形条目保持原样（消费侧的防御判据照旧生效）。
+ */
+function withObjectRefs(payload) {
+    for (const file of payload.files) {
+        if (file === null || typeof file !== 'object')
+            continue;
+        if (typeof file.object === 'string')
+            continue;
+        if (typeof file.sha256 === 'string')
+            file.object = file.sha256;
+    }
+    return payload;
+}
 function errorDetail(error) {
     if (error instanceof Error) {
         const code = error.code;

package/lib/core/rollback-merge.d.ts

@@ -0,0 +1,22 @@
+/** 合并结论（`ok:false` 时调用方必须**零写入**） */
+export type ThreeWayMergeReason = 'clean' | 'conflict' | 'degraded' | 'binary';
+export interface ThreeWayMergeResult {
+    /** true = 结果可直接写入；false = 必须放弃写入并如实报告 */
+    ok: boolean;
+    /** 合并结果（`ok:false` 时是 theirs 原文 —— 方便调用方做「保持现状」的比较，绝不写入） */
+    text: string;
+    reason: ThreeWayMergeReason;
+    /** 冲突块数（>0 ⇒ ok=false） */
+    conflicts: number;
+    /** 本次合并**撤销**的行数（base 有、ours 没有）与**保留**的对方新增行数（诊断用） */
+    revertedLines: number;
+    /** 依赖风险提示（启发式；空数组 = 未发现明显风险，**不代表安全**） */
+    risks: string[];
+}
+/**
+ * 三方合并（纯函数、无 I/O）。
+ *
+ * 语义：结果是 `ours` 上再应用 `(theirs - base)` —— 撤销「我们从 base 改到 ours 的那部分」，
+ * 同时保留「别人从 base 改到 theirs 的那部分」。
+ */
+export declare function mergeThreeWay(ours: string, base: string, theirs: string): ThreeWayMergeResult;