dsh-config-manager 0.1.72 → 0.1.73

package/lib/core/rollback-point.js

@@ -74,12 +74,22 @@ import { projectKeyOf } from './session-select.js';
 import { ignoreRelativePath, ignoreRuleMatches, loadIgnoreRules } from './rollback-ignore-rules.js';
 import { isSessionLogName } from '../utils/session-log.js';
 import { decodeZstdFrame, scanZstdFrames, zstdAvailable, ZSTD_MAGIC } from '../utils/zstd-frame.js';
+import { cleanupOrphanTempFiles, entrySummaryOf, ROLLBACK_DEFAULT_LEDGER_BYTES, ROLLBACK_UNDO_DIR_NAME, RollbackLedger, } from './rollback-ledger.js';
 /* ------------------------------------------------------------------ 常量 */
 export const ROLLBACK_SCHEMA_VERSION = 2;
 /** 回滚点库目录名（dataDir/rollback-points）——路由族 /recovery/rollback-points/* 同源 */
 export const ROLLBACK_POINTS_DIR_NAME = 'rollback-points';
+/**
+ * 台账**清单**文件名（v3，issue #89）：它只是一份小清单（元数据 + 段摘要），
+ * 完整记录在 records/<id>.json、工作区载荷在 payloads/<sha256>.json —— 清单里绝不含大数组。
+ */
 export const ROLLBACK_LEDGER_NAME = 'index.json';
 export const ROLLBACK_OBJECTS_DIR_NAME = 'objects';
+/**
+ * 台账字节预算（records/ + payloads/）的缺省值，可由 RollbackEngineOptions.ledgerBytesBudget 覆盖。
+ * 为什么需要它：ROLLBACK_MAX_RECORDS（50）只限**条数**；本机实测 50 条 = 473 MB 直接把宿主撑爆。
+ */
+export { ROLLBACK_DEFAULT_LEDGER_BYTES };
 /** 全局自动点上限（S6）；protected / guard 点不占预算、只进不出 */
 export const ROLLBACK_MAX_RECORDS = 50;
 /** 每会话自动点上限（S6） */
@@ -157,6 +167,16 @@ export const ROLLBACK_DEFAULT_SESSION_QUIESCENT_MS = 30_000;
 /** 轮询回退的间隔上界（S1：会话日志 mtime ≤5 s 轮询） */
 export const ROLLBACK_DEFAULT_POLL_INTERVAL_MS = 5_000;
 export const ROLLBACK_LEFTOVER_LIST_LIMIT = 20;
+/**
+ * 工作区捕获的**挂钟时间预算**（缺省 30 s）。
+ *
+ * 为什么需要（对标 dsh-turn-rewind 的 `deadline.ts`、dsh-checkpoint-rewind 至今未合并的 PR #25）：
+ * 捕获路径此前只有「文件数 / 总字节 / 单文件字节」三个**规模**上限，没有**时间**上限 ——
+ * 一个「文件数很多但总量不大」的工作区能让 walk + stat + sha256 跑很久。
+ * 超预算**不是失败**：已收条目照常成点（ok=true），未走查的部分按 `budget-time` 逐条留痕、
+ * `truncated` 置真 ⇒ 删除集自动 fail-closed（证明名单不完整就一条都不删）。
+ */
+export const ROLLBACK_DEFAULT_CAPTURE_BUDGET_MS = 30_000;
 /**
  * 「删除回退点之后新建的路径」的**整套上限**（用户 2026-10-11 定案 A）。
  * 超过就整套拒绝（fail-closed），绝不删一半 —— 半套删除既没有可解释的状态，也无法整体回滚。
@@ -524,6 +544,62 @@ function withLedgerWriteLock(ledgerPath, task) {
     });
     return run;
 }
+/**
+ * 回退前像暂存器：**字节落盘、索引随栈**。
+ *
+ * 为什么不是内存数组（旧实现）：大工作区整体回退时前像峰值 = 待写总字节（可达数百 MB），
+ * 与 issue #89 的 OOM 同族。落盘后内存只随**文件条数**增长。
+ *
+ * 生命周期：`stage()` 逐条写前像 → 成功则 `dispose()`；中途失败则 `rollback()` 写回再 `dispose()`。
+ * 目录名带 pid，崩溃残留由 rollback-ledger 的 `cleanupOrphanTempFiles` 在下次启动回收。
+ */
+class UndoStager {
+    entries = [];
+    dir;
+    seq = 0;
+    constructor(dir) {
+        this.dir = dir;
+    }
+    /** 记一条前像：`bytes === null` = 该路径当时**不存在**（回滚时删掉它）。 */
+    async stage(target, bytes) {
+        if (bytes === null) {
+            this.entries.push({ path: target, file: null });
+            return;
+        }
+        const file = path.join(this.dir, String(this.seq) + '.bin');
+        this.seq += 1;
+        await fs.writeFile(file, bytes);
+        this.entries.push({ path: target, file });
+    }
+    /**
+     * 逐条写回（**逆序**：同一路径被 stage 两次时，最后一次 stage 记的是最早状态，必须最后写）。
+     * 返回失败清单 —— 回滚失败绝不静默。
+     */
+    async rollback(writer) {
+        const failed = [];
+        for (const entry of [...this.entries].reverse()) {
+            try {
+                if (entry.file === null)
+                    await fs.rm(entry.path, { force: true });
+                else
+                    await writer(entry.path, await fs.readFile(entry.file));
+            }
+            catch (error) {
+                failed.push(entry.path + ' ' + errorDetail(error));
+            }
+        }
+        return failed;
+    }
+    /** 前像目录用完即清（best-effort：清理失败不该把回退报成失败）。 */
+    async dispose() {
+        try {
+            await fs.rm(this.dir, { recursive: true, force: true });
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+}
 export class RollbackPointEngine {
     dataDir;
     homeDir;
@@ -565,8 +641,21 @@ export class RollbackPointEngine {
     forkLinksComplete = true;
     /** 会话日志头缓存（mtime + size 失效；只服务 fork 链扫描） */
     forkHeaderCache = new Map();
-    /** 继承判据用的台账快照（TTL 缓存；避免每个 turn/start 都读整份台账） */
+    /** 继承判据用的台账快照（TTL 缓存；只缓存**清单条目**，绝不缓存完整记录） */
     ledgerSnapshotCache = null;
+    /** 台账存储层（v3：清单 + 单条记录 + 内容寻址载荷；issue #89） */
+    ledger;
+    ledgerBytesBudget;
+    /** 工作区捕获的挂钟时间预算（毫秒；见 ROLLBACK_DEFAULT_CAPTURE_BUDGET_MS） */
+    captureBudgetMs;
+    /**
+     * 启动期一次性初始化（流式迁移 v2 -> v3 + 孤儿 tmp 清理）的惰性单飞。
+     * 为什么惰取而不是构造时同步跑：构造发生在每个请求路径上，同步扫盘/迁移会把请求卡死；
+     * 而「每回合都扫一遍」正是要避免的浪费 —— 所以只跑一次并记住结果。
+     */
+    initPromise = null;
+    /** 启动期初始化失败的如实记录（读路径必须报出来，绝不假装台账是空的） */
+    initError;
     constructor(options) {
         this.dataDir = path.resolve(options.dataDir);
         this.homeDir = path.resolve(options.homeDir);
@@ -596,6 +685,18 @@ export class RollbackPointEngine {
         this.previewDiffMaxWork = options.previewDiffMaxWork ?? ROLLBACK_PREVIEW_DIFF_MAX_WORK;
         this.previewDiffTotalWork = options.previewDiffTotalWork ?? ROLLBACK_PREVIEW_DIFF_TOTAL_WORK;
         this.log = options.log;
+        this.ledgerBytesBudget = options.ledgerBytesBudget ?? ROLLBACK_DEFAULT_LEDGER_BYTES;
+        this.captureBudgetMs = options.captureBudgetMs ?? ROLLBACK_DEFAULT_CAPTURE_BUDGET_MS;
+        this.ledger = new RollbackLedger({
+            root: this.root,
+            bytesBudget: this.ledgerBytesBudget,
+            // 摘要与记录校验的单一事实源都在本模块：注入而不是反向 import，避免运行期循环依赖
+            summarize: summarizeRollbackPoint,
+            isLedgerRecord: isRollbackPointRecord,
+            now: () => this.stamp(),
+            log: (line) => this.warn(line),
+            onFileRead: options.ledgerReadFile,
+        });
     }
     /** 回滚点库根目录（只读侦察用；写路径全部经本类的门） */
     get storeDir() {
@@ -643,6 +744,22 @@ export class RollbackPointEngine {
         else
             sink.skippedTruncated = true;
     }
+    /**
+     * 打开一次回退的前像暂存目录（`<root>/undo/<pid>-<ts36>-<8hex>/`）。
+     * 返回 null = 建不出来（权限 / 磁盘满）⇒ 调用方必须**零写入失败**。
+     */
+    async openUndoStager() {
+        const name = String(process.pid) + '-' + this.stamp().toString(36) + '-' + crypto.randomBytes(4).toString('hex');
+        const dir = path.join(this.root, ROLLBACK_UNDO_DIR_NAME, name);
+        try {
+            await fs.mkdir(dir, { recursive: true });
+        }
+        catch (error) {
+            this.warn('rollback undo staging unavailable: ' + errorDetail(error));
+            return null;
+        }
+        return new UndoStager(dir);
+    }
     async writeFile(target, bytes) {
         if (this.writeSeam !== undefined) {
             await this.writeSeam(target, bytes);
@@ -651,8 +768,49 @@ export class RollbackPointEngine {
         await atomicWriteFile(target, bytes, { symlink: 'reject' });
     }
     /* ---------------------------------------------------------- 存储栈探针 */
+    /**
+     * 启动期一次性初始化（惰性单飞）：先**流式**迁移 v2 单文件 -> v3，再清理崩溃残留的原子写 tmp。
+     *
+     * 为什么惰取而不是在构造里同步跑：引擎在每个请求路径上都会被新建（路由层不缓存引擎），
+     * 构造里同步扫盘/迁移会把请求卡死；而「每回合扫一遍」又是纯浪费 —— 所以只跑一次并记住结果。
+     * 迁移失败**不抛**：如实记进 initError，由读路径报出来，并**拒写**（绝不覆盖还没迁完的 v2 文件）。
+     */
+    async ensureReady() {
+        if (this.initPromise === null)
+            this.initPromise = this.runInit();
+        await this.initPromise;
+    }
+    async runInit() {
+        let migration;
+        try {
+            migration = await this.ledger.migrateIfNeeded();
+        }
+        catch (error) {
+            this.initError = 'ledger unreadable: ' + errorDetail(error);
+            return;
+        }
+        if (migration.error !== undefined) {
+            this.initError = migration.error;
+            this.warn('rollback ledger migration failed: ' + migration.error);
+            return;
+        }
+        if (migration.migrated) {
+            this.warn('rollback ledger migrated: records=' + String(migration.records) + ' skipped=' + String(migration.skipped));
+        }
+        // 迁移**之后**再清残留：连本次迁移自己的 tmp 一并收掉（只放行可自证形状的崩溃残留）
+        try {
+            const cleaned = await cleanupOrphanTempFiles(this.root);
+            if (cleaned.removed > 0) {
+                this.warn('rollback temp cleanup: removed=' + String(cleaned.removed) + ' bytes=' + String(cleaned.bytes) + ' skipped=' + String(cleaned.skipped));
+            }
+        }
+        catch (error) {
+            this.warn('rollback temp cleanup failed: ' + errorDetail(error));
+        }
+    }
     async storageStatus() {
         const base = { root: this.root, requirements: ROLLBACK_STORAGE_REQUIREMENTS };
+        await this.ensureReady();
         let result;
         if (this.probe !== undefined) {
             try {
@@ -665,9 +823,39 @@ export class RollbackPointEngine {
         else {
             result = await defaultStorageProbe(this.root);
         }
-        if (result.ok)
-            return { ...base, available: true, guidance: [] };
-        return { ...base, available: false, detail: result.detail, guidance: storageGuidance(this.root, result.detail) };
+        if (!result.ok) {
+            return { ...base, available: false, detail: result.detail, guidance: storageGuidance(this.root, result.detail) };
+        }
+        const out = { ...base, available: true, guidance: [] };
+        const ledger = await this.ledgerStatus();
+        if (ledger !== undefined)
+            out.ledger = ledger;
+        if (this.initError !== undefined) {
+            // 磁盘本身没问题，但台账读不出来（迁移失败 / 迁到一半被别人占着）：如实上屏，不谎报可用
+            out.detail = this.initError;
+            out.guidance = storageGuidance(this.root, this.initError);
+        }
+        return out;
+    }
+    /** 台账可观测快照（清单条数 + 磁盘字节 + 预算 + 本进程淘汰计数） */
+    async ledgerStatus() {
+        try {
+            const manifest = await this.ledger.readManifest();
+            const stats = await this.ledger.stats();
+            return {
+                records: manifest.entries.length,
+                bytes: stats.bytes,
+                budgetBytes: this.ledgerBytesBudget,
+                evicted: this.ledger.evictedCount,
+                // 每次 append 都会尽力淘汰到预算内 ⇒「bytes > budget」本身就等于「淘汰到极限了」
+                // （单条点大于预算时恒为 true）。这里不额外读盘，只用已有 stats。
+                overBudget: stats.bytes > this.ledgerBytesBudget,
+            };
+        }
+        catch (error) {
+            this.warn('rollback ledger status failed: ' + errorDetail(error));
+            return undefined;
+        }
     }
     /* -------------------------------------------------------------- 对象仓 */
     async writeObjectWithHash(bytes, sha) {
@@ -798,7 +986,12 @@ export class RollbackPointEngine {
      * 捕获期专用：把**走查过**的每条文件路径都记进来（含超出 limit、因而没进 `out` 的那些）——
      * 路径索引（{@link RollbackPathIndex}）的来源。回退期的走查不传它（那份名单只由记录决定）。
      */
-    collect, ignore) {
+    collect, ignore, 
+    /**
+     * 停止判据（捕获期传时间/取消预算；回退期的走查不传）—— 返回 true 立即停止遍历，
+     * 已走查的部分照常返回并置 truncated（证明名单因此不完整 ⇒ 删除集 fail-closed）。
+     */
+    shouldStop) {
         let stat;
         try {
             stat = await fs.lstat(chunk);
@@ -821,6 +1014,10 @@ export class RollbackPointEngine {
         let truncated = false;
         const stack = [{ dir: chunk, depth: 0 }];
         while (stack.length > 0) {
+            if (shouldStop?.() === true) {
+                truncated = true;
+                break;
+            }
             const item = stack.pop();
             if (item === undefined)
                 break;
@@ -843,9 +1040,15 @@ export class RollbackPointEngine {
                     continue;
                 }
                 if (entry.isDirectory()) {
-                    if (EXCLUDED_DEP_DIR_NAMES.includes(entry.name)) {
+                    // `.git` 与运行时依赖目录**同档**：整棵不进快照。两条理由 ——
+                    //  ① 回退写回 .git（index/refs/logs）会让 git 状态错乱（提交看似消失、可能留 index.lock），
+                    //     而删除侧本来就把 .git 当拒删目录 ⇒ 排除它才让两侧口径一致；
+                    //  ② .git 常常几百 MB，会**挤掉 maxBytes 预算里的源码文件**。
+                    // 大小写折半比较：Windows 上 .GIT/.Git 是同一个目录。
+                    const dirName = win32Fold(entry.name);
+                    if (EXCLUDED_DEP_DIR_NAMES.includes(entry.name) || dirName === '.git') {
                         // 内置忽略规则（S4「沿用现有 IGNORE 规则」）：整棵不进快照，但留痕（不静默）
-                        this.recordSkip(sink, 'excluded', { path: full, reason: 'dep-dir' });
+                        this.recordSkip(sink, 'excluded', { path: full, reason: dirName === '.git' ? 'git-dir' : 'dep-dir' });
                         continue;
                     }
                     if (ignore !== undefined && this.ignoredByRules(ignore, full, true)) {
@@ -881,10 +1084,15 @@ export class RollbackPointEngine {
         out.sort();
         return { files: out, truncated };
     }
-    async captureWorkspace(chunks) {
+    async captureWorkspace(chunks, signal) {
         const capturedAt = this.stamp();
         if (chunks.length === 0)
             return this.emptyTrack('workspace', capturedAt, 'no-chunks', 'chunks empty');
+        // 时间预算（见 ROLLBACK_DEFAULT_CAPTURE_BUDGET_MS）：用 stamp()（单调）比较，
+        // 系统时钟回拨也不会让预算永不触发。超时置 payload.truncated ⇒ 结尾的 reasonCode
+        // 自动落成 capture-truncated，UI 走既有的 degraded 提示路径（零新增文案）。
+        const deadline = capturedAt + this.captureBudgetMs;
+        const outOfBudget = () => signal?.aborted === true || this.stamp() >= deadline;
         const payload = {
             chunks: [...chunks],
             files: [],
@@ -905,17 +1113,32 @@ export class RollbackPointEngine {
         // 走查过的**全部**文件路径（含被预算 / 单文件上限挡下的）—— 路径索引的来源（方向 B）
         const walked = [];
         for (const chunk of chunks) {
+            if (outOfBudget()) {
+                // 分块之间就超预算：不再开新分块，并如实留痕（该分块的条目一条都没被走查）
+                // walkIncomplete 是**安全判据**（删除集 fail-closed），漏了它会删掉未走查子树里的文件
+                payload.walkIncomplete = true;
+                payload.truncated = true;
+                this.recordSkip(payload, 'skipped', { path: chunk, reason: 'budget-time' });
+                break;
+            }
             if (!path.isAbsolute(chunk))
                 return this.emptyTrack('workspace', capturedAt, 'chunk-not-absolute', chunk);
             const resolved = path.resolve(chunk);
             // 文件数预算还剩多少就收多少；+1 只用于让遍历器发现「还有溢出」——溢出条目逐条记 skipped
-            const listed = await this.listChunkFiles(resolved, payload, Math.max(0, this.maxFiles - read) + 1, walked, await loadIgnoreRules(resolved));
+            const listed = await this.listChunkFiles(resolved, payload, Math.max(0, this.maxFiles - read) + 1, walked, await loadIgnoreRules(resolved), outOfBudget);
             if (listed === null)
                 continue;
             sawChunk = true;
             if (listed.truncated)
                 payload.truncated = true;
             for (const file of listed.files) {
+                if (outOfBudget()) {
+                    // 同上：中断 = 剩余路径从未进任何名单 ⇒ 必须让删除集 fail-closed
+                    payload.walkIncomplete = true;
+                    payload.truncated = true;
+                    this.recordSkip(payload, 'skipped', { path: file, reason: 'budget-time' });
+                    break;
+                }
                 if (read >= this.maxFiles) {
                     // 文件数预算耗尽：其后每一条都如实留痕（不再 break 静默丢弃）
                     payload.truncated = true;
@@ -994,7 +1217,9 @@ export class RollbackPointEngine {
                 }
             }
         }
-        if (!sawChunk && payload.files.length === 0) {
+        // `truncated` 为真时**不能**判 chunk-not-found：那是「分块确实存在、只是没来得及走查完」
+        // （时间预算 / 取消信号）—— 报成「找不到分块」会让用户以为工作区配错了。
+        if (!sawChunk && payload.files.length === 0 && !payload.truncated) {
             return this.emptyTrack('workspace', capturedAt, 'chunk-not-found', chunks.join(' '));
         }
         // **方向 B**：逐条跳过名单被记录上限截断（skippedTruncated）时，把走查过的全部路径另存成
@@ -1168,6 +1393,10 @@ export class RollbackPointEngine {
             out.push({ code: 'rollback.warn.createdRefused', detail: 'ignore-dirs' });
             return out;
         }
+        if (payload.walkIncomplete === true) {
+            out.push({ code: 'rollback.warn.createdRefused', detail: 'walk-incomplete' });
+            return out;
+        }
         if (payload.skippedTruncated && (payload.pathIndex === null || payload.pathIndex === undefined)) {
             out.push({ code: 'rollback.warn.createdRefused', detail: 'path-index-missing' });
             return out;
@@ -1179,32 +1408,28 @@ export class RollbackPointEngine {
         return out;
     }
     /* -------------------------------------------------------------- 台账 */
-    async readLedger() {
-        let raw;
-        try {
-            raw = await fs.readFile(this.ledgerPath, 'utf8');
-        }
-        catch (error) {
-            // 不存在 = 首次使用（不是错误）；其它读失败如实回报
-            const code = error.code;
-            if (code === 'ENOENT')
-                return { records: [] };
-            return { records: [], error: errorDetail(error) };
-        }
-        try {
-            const parsed = JSON.parse(raw);
-            if (!isRecord(parsed))
-                return { records: [], error: 'ledger shape invalid' };
-            const list = parsed['records'];
-            if (!Array.isArray(list))
-                return { records: [], error: 'ledger.records invalid' };
-            const records = list.filter(isRollbackPointRecord);
-            const skipped = list.length - records.length;
-            return skipped > 0 ? { records, error: 'ledger dropped ' + String(skipped) + ' invalid record(s)' } : { records };
-        }
-        catch (error) {
-            return { records: [], error: 'ledger unreadable: ' + errorDetail(error) };
-        }
+    /**
+     * 读台账**清单**（只读元数据 + 段摘要；代价与工作区文件数**无关**）。
+     *
+     * 与 v2 的差别只在实现：v2 每回合把整份 index.json 读进内存并 parse（473 MB 那条路），
+     * v3 读的是一份小清单。**外部语义一个字没变**：返回 entries + 同一套 error 文案。
+     * 启动期初始化失败时如实回报（不读 v2 文件、不假装台账为空）。
+     */
+    async readManifest() {
+        await this.ensureReady();
+        if (this.initError !== undefined)
+            return { entries: [], error: this.initError };
+        return await this.ledger.readManifest();
+    }
+    /**
+     * 读**完整**记录（引用解析对调用方透明）。失败一律如实回报，**绝不返回半个记录**：
+     * 载荷缺失 / 哈希不符 / 形状不符 ⇒ error（调用方走 record-incomplete 路径）。
+     */
+    async readFullRecord(id) {
+        await this.ensureReady();
+        if (this.initError !== undefined)
+            return { error: this.initError };
+        return await this.ledger.readRecord(id);
     }
     /**
      * S6 淘汰（t14 冻结 + 2026-10-12 guard 全局上限）：三类点各按各的预算裁，**只删最旧的**。
@@ -1215,17 +1440,26 @@ export class RollbackPointEngine {
      * | guard 救援点 | 每会话 `maxGuardsPerSession`（20）→ 全局 `maxGuards`（`ROLLBACK_MAX_GUARDS`，50） | **不占**自动点预算、**不受**自动点的 20/50 影响；用户删不掉 ⇒ 必须有自己的两道预算（单会话挡住不够，跨会话也要收敛） |
      * | protected 点 | 无上限（只进不出） | 生产路径**造不出来**（capture 端点已下线、tracker 从不设 protect），只有测试能造 |
      */
-    selectPrune(records) {
+    /**
+     * 条数淘汰（口径与 v2 逐字相同，只是从「记录」换成「清单条目」）：三类点各按各的预算裁，**只删最旧的**。
+     *
+     * | 类别 | 预算 | 说明 |
+     * |---|---|---|
+     * | auto 自动点 | 每会话 maxRecordsPerSession（20）→ 全局 maxRecords（50） | 两次裁剪都只删最旧 |
+     * | guard 救援点 | 每会话 maxGuardsPerSession（20）→ 全局 maxGuards（ROLLBACK_MAX_GUARDS，50） | **不占**自动点预算、**不受**自动点的 20/50 影响；用户删不掉 ⇒ 必须有自己的两道预算（单会话挡住不够，跨会话也要收敛） |
+     * | protected 点 | 无上限（只进不出） | 生产路径**造不出来**（capture 端点已下线、tracker 从不设 protect），只有测试能造 |
+     */
+    selectPruneEntries(entries) {
         const kept = [];
         const guards = [];
         const prunable = [];
-        for (const record of records) {
-            if (record.protected)
-                kept.push(record);
-            else if (record.kind === 'guard')
-                guards.push(record);
+        for (const entry of entries) {
+            if (entry.protected)
+                kept.push(entry);
+            else if (entry.kind === 'guard')
+                guards.push(entry);
             else
-                prunable.push(record);
+                prunable.push(entry);
         }
         // 最新在前（下面三类裁剪共用同一排序口径）
         const newestFirst = (a, b) => a.createdAt > b.createdAt ? -1 : a.createdAt < b.createdAt ? 1 : 0;
@@ -1234,85 +1468,204 @@ export class RollbackPointEngine {
         guards.sort(newestFirst);
         const guardsPerSession = new Map();
         const withinGuardSession = [];
-        for (const record of guards) {
-            const key = record.sessionId ?? '';
+        for (const entry of guards) {
+            const key = entry.sessionId ?? '';
             const used = guardsPerSession.get(key) ?? 0;
             if (used >= this.maxGuardsPerSession)
                 continue;
             guardsPerSession.set(key, used + 1);
-            withinGuardSession.push(record);
+            withinGuardSession.push(entry);
         }
         kept.push(...withinGuardSession.slice(0, Math.max(0, this.maxGuards)));
         // 自动点：先每会话上限，再全局上限
         prunable.sort(newestFirst);
         const perSession = new Map();
         const withinSession = [];
-        for (const record of prunable) {
-            const key = record.sessionId ?? '';
+        for (const entry of prunable) {
+            const key = entry.sessionId ?? '';
             const used = perSession.get(key) ?? 0;
             if (used >= this.maxRecordsPerSession)
                 continue;
             perSession.set(key, used + 1);
-            withinSession.push(record);
+            withinSession.push(entry);
         }
         kept.push(...withinSession.slice(0, Math.max(0, this.maxRecords)));
         const keptIds = new Set(kept.map((r) => r.id));
-        const removed = records.filter((r) => !keptIds.has(r.id)).map((r) => r.id);
+        const removed = entries.filter((r) => !keptIds.has(r.id)).map((r) => r.id);
         return { kept, removed };
     }
-    async gcObjects(records) {
-        const referenced = new Set();
-        const referencedPaths = new Set();
-        for (const record of records) {
-            for (const file of record.workspace.payload?.files ?? []) {
-                referenced.add(file.object);
-                referencedPaths.add(pathKey(file.path));
-            }
-            const pathIndex = record.workspace.payload?.pathIndex;
-            if (pathIndex !== null && pathIndex !== undefined)
-                referenced.add(pathIndex.object);
-            const sessionObject = record.session.payload?.object;
-            if (sessionObject !== null && sessionObject !== undefined)
-                referenced.add(sessionObject);
-        }
-        let names;
-        try {
-            names = await fs.readdir(this.objectsDir);
-        }
-        catch {
-            return;
-        }
-        for (const name of names) {
-            if (!OBJECT_KEY_RE.test(name) || referenced.has(name))
+    /**
+     * 字节预算淘汰（issue #89 的**根因修复**）：条数没超、字节超了照样会 OOM。
+     *
+     * 判据与条数淘汰共用同一类别口径：**只淘汰最旧的 auto 点**（guard / protected 永不淘汰）。
+     * 释放量按「记录文件字节 + 载荷**最后一个引用**消失时的载荷字节」估算（引用计数靠清单，不读载荷）。
+     * 返回淘汰后的清单（调用方负责落盘与删文件）。
+     */
+    async applyByteBudget(all, keptInput, extraBytes, protectedNewId) {
+        const kept = [...keptInput];
+        // 基线口径（**精确**，不用估算）：当前磁盘字节 - 本次已定要删的条目所占字节 + 本次新增字节。
+        // 「已定要删」= 条数淘汰掉的（它们的文件马上会被删），所以不能拿 stats.bytes 当基线。
+        const keptIds = new Set(kept.map((entry) => entry.id));
+        const keptPayloads = new Set();
+        for (const entry of kept) {
+            if (entry.workspace.payload !== null)
+                keptPayloads.add(entry.workspace.payload);
+        }
+        let freed = 0;
+        const freedPayloads = new Set();
+        for (const entry of all) {
+            if (keptIds.has(entry.id))
                 continue;
-            try {
-                await fs.rm(path.join(this.objectsDir, name), { force: true });
-            }
-            catch (error) {
-                this.warn('rollback gc failed: ' + name + ' ' + errorDetail(error));
-            }
+            freed += entry.recordBytes;
+            const hash = entry.workspace.payload;
+            if (hash !== null && !keptPayloads.has(hash) && !freedPayloads.has(hash)) {
+                freedPayloads.add(hash);
+                freed += entry.workspace.payloadBytes;
+            }
+        }
+        const stats = await this.ledger.stats();
+        let bytes = stats.bytes - freed + extraBytes;
+        if (bytes <= this.ledgerBytesBudget)
+            return kept;
+        const refs = new Map();
+        for (const entry of kept) {
+            const hash = entry.workspace.payload;
+            if (hash !== null)
+                refs.set(hash, (refs.get(hash) ?? 0) + 1);
+        }
+        const candidates = kept
+            .filter((entry) => !entry.protected && entry.kind === 'auto' && entry.id !== protectedNewId)
+            .sort((a, b) => (a.createdAt < b.createdAt ? -1 : a.createdAt > b.createdAt ? 1 : 0));
+        const victims = new Set();
+        for (const entry of candidates) {
+            if (bytes <= this.ledgerBytesBudget)
+                break;
+            victims.add(entry.id);
+            const index = kept.findIndex((item) => item.id === entry.id);
+            if (index >= 0)
+                kept.splice(index, 1);
+            bytes -= entry.recordBytes;
+            const hash = entry.workspace.payload;
+            if (hash !== null) {
+                const left = (refs.get(hash) ?? 1) - 1;
+                refs.set(hash, left);
+                if (left <= 0)
+                    bytes -= entry.workspace.payloadBytes;
+            }
+        }
+        if (victims.size === 0) {
+            // 一条都淘汰不了却仍然超预算（典型：单条点自身的体积就大于预算）—— **如实留痕**。
+            // 不写这一条，「预算生效」就是假象（竞品 dsh-checkpoint-rewind #35 正是「软配额 bound
+            // 不住单条」的口子）；界面侧由 RollbackLedgerStatus.overBudget 如实上屏。
+            if (bytes > this.ledgerBytesBudget) {
+                this.warn('rollback ledger over budget: nothing prunable bytes=' + String(bytes) + ' budget=' + String(this.ledgerBytesBudget));
+            }
+            return kept;
+        }
+        this.ledger.markEvicted(victims.size);
+        this.warn('rollback ledger over budget: evicted=' + String(victims.size) + ' bytes=' + String(bytes) + ' budget=' + String(this.ledgerBytesBudget));
+        return kept;
+    }
+    /**
+     * 对象仓回收（**重写版**，issue #89）：账本字节数不再进内存。
+     *
+     * 旧实现要从「内存里所有记录的全部 files 数组」累计引用 ⇒ 回收一次 = 把整份台账读进内存。
+     * 现在：扫**清单** -> 逐个读引用到的**载荷文件**（一次只驻留一份）-> 累计 referenced 对象键 -> 扫 objects/。
+     * 峰值内存 ∝ 单份载荷 + 对象键集合，**不 ∝ 台账总字节**。
+     * 任何一份被引用的载荷读不出来 ⇒ 整体放弃回收（fail-closed：读不到的载荷里有什么对象谁也不知道）。
+     */
+    async gcObjects(entries) {
+        const result = await this.ledger.collectObjects(entries);
+        if (result.aborted !== null) {
+            this.warn('rollback gc skipped: ' + result.aborted);
+            return;
         }
         // 路径身份缓存随引用回收：没有任何回滚点引用的路径不留条目（不无界增长）
-        await this.gcPathCache(referencedPaths);
+        await this.gcPathCache(new Set([...result.referencedPaths].map(pathKey)));
     }
     /**
      * 把记录写进台账（**留点侧唯一写入口**）：整段「读全文 → 合并 → S6 淘汰 → 原子写 → 回收对象」
      * 都在 {@link withLedgerWriteLock} 的进程内串行队列里 —— 绝不与 tracker / 路由的另一次写交错。
      */
+    /**
+     * 写一条记录（**最多三次尝试**）—— 跨进程乐观并发（①B）。
+     *
+     * dataDir 由 `$DSH_HOME` 决定、**不随 profile 分家**（与本插件自带的实例锁同一套多实例假设），
+     * 所以「另一个 DSH 实例正在写同一份清单」是设计内的场景，而 `withLedgerWriteLock` 只串行本进程。
+     * 策略：读清单前后各取一次**代际戳**，被改过就重读重试；三次都变 ⇒ **放弃本次留点并 warn**，
+     * 绝不拿自己的快照覆盖别人的清单（宁可少一条点，也不丢别人的点）。
+     * 诚实的边界：检测与写入之间仍有极小窗口，无跨进程锁时无法彻底消除 —— 这里保证的是
+     * 「不静默覆盖 + 尽量合并」，不是原子性。
+     */
     async appendRecord(record) {
+        for (let attempt = 0; attempt < 3; attempt += 1) {
+            const result = await this.appendRecordOnce(record);
+            if (result.conflict !== true) {
+                return result.detail !== undefined ? { ok: result.ok, detail: result.detail } : { ok: result.ok };
+            }
+        }
+        this.warn('rollback ledger busy: another instance kept changing the manifest (auto point skipped)');
+        return { ok: false, detail: 'ledger-busy: manifest changed by another instance' };
+    }
+    /** `appendRecord` 的单次尝试；`conflict: true` = 这期间清单被别的实例改过，调用方应当重试。 */
+    async appendRecordOnce(record) {
         return await withLedgerWriteLock(this.ledgerPath, async () => {
-            const ledger = await this.readLedger();
-            const merged = [record, ...ledger.records.filter((r) => r.id !== record.id)];
-            const { kept } = this.selectPrune(merged);
+            // 读之前先取一次代际戳（不参与锁：它天生是跨进程的探针）
+            const stampBefore = await this.ledger.manifestStamp();
+            let manifest = await this.readManifest();
+            if (this.initError !== undefined) {
+                // 台账还有 v2 没迁完（或迁移失败）：**拒写**，绝不覆盖原文件（下次启动重试）
+                return { ok: false, detail: this.initError };
+            }
+            if (manifest.error !== undefined) {
+                // 清单**读不出来**：先**从 records/ 重建**（旧点的最终真相在记录文件里），
+                // 而不是拿一个空 entries 覆盖 —— 后者会把旧点整批从清单抹掉，紧接着 prunePayloads
+                // 还会删掉它们的载荷 ⇒ 永久不可恢复。重建后**仍**读不出来才拒写（fail-closed）。
+                manifest = await this.ledger.recoverManifest();
+                if (manifest.error !== undefined) {
+                    return { ok: false, detail: 'ledger unreadable: ' + manifest.error };
+                }
+            }
+            const prepared = this.ledger.prepareRecord(record);
+            const merged = [prepared.entry, ...manifest.entries.filter((r) => r.id !== record.id)];
+            const pruned = this.selectPruneEntries(merged);
+            // 本次新增字节：记录文件 + **首次落盘**的载荷（同一工作区态已存在 ⇒ 零额外字节）
+            const payloadIsNew = prepared.payloadHash !== null && !(await this.ledger.hasPayload(prepared.payloadHash));
+            const extraBytes = prepared.entry.recordBytes + (payloadIsNew ? prepared.entry.workspace.payloadBytes : 0);
+            // 刚写入的这一条不参与本轮字节淘汰（否则 capturePoint 会回一个台账里查不到的幽灵点）
+            const kept = await this.applyByteBudget(merged, pruned.kept, extraBytes, prepared.entry.id);
             kept.sort((a, b) => (a.createdAt > b.createdAt ? -1 : a.createdAt < b.createdAt ? 1 : 0));
+            // 写之前复核：这份清单在这期间有没有被别的实例改过？改过就**不写**，交给调用方重读重试。
+            // 读不出代际戳（任一时刻为 null）⇒ 不参与判定、照常写 —— 绝不因为一个可选探针失败就拒绝留点。
+            const stampAfter = await this.ledger.manifestStamp();
+            if (stampBefore !== null && stampAfter !== null && stampBefore !== stampAfter) {
+                return { ok: false, conflict: true, detail: 'manifest changed by another instance' };
+            }
             try {
                 await fs.mkdir(this.root, { recursive: true });
-                await atomicWriteFile(this.ledgerPath, JSON.stringify({ schemaVersion: ROLLBACK_SCHEMA_VERSION, records: kept }, null, 2));
+                await this.ledger.writePrepared(prepared);
             }
             catch (error) {
                 return { ok: false, detail: errorDetail(error) };
             }
-            await this.gcObjects(kept);
+            try {
+                await this.ledger.writeManifest(kept);
+            }
+            catch (error) {
+                // 清单没写成 ⇒ 这一条**不算落进台账**：撤掉刚落的记录文件与无人引用的载荷（不留半截）
+                await this.ledger.deleteRecords([prepared.entry.id]);
+                await this.ledger.prunePayloads(manifest.entries);
+                return { ok: false, detail: errorDetail(error) };
+            }
+            const keptIds = new Set(kept.map((entry) => entry.id));
+            const dropped = merged.filter((entry) => !keptIds.has(entry.id)).map((entry) => entry.id);
+            await this.ledger.deleteRecords(dropped);
+            await this.ledger.prunePayloads(kept);
+            // **只在真的淘汰了记录时**才扫对象仓：对象回收需要逐份读被引用的载荷（代价 ∝ 载荷总量），
+            // 而没有淘汰时不可能产生无人引用的对象 —— 每回合都扫一遍等于把「读全账本」搬进了留点热路径
+            // （issue #89 正是要消灭这条路）。删除点 / 预算淘汰 / 清理入口都会走到这里。
+            if (dropped.length > 0)
+                await this.gcObjects(kept);
             return { ok: true };
         });
     }
@@ -1337,7 +1690,7 @@ export class RollbackPointEngine {
             boundarySeq: typeof input.boundarySeq === 'number' && Number.isFinite(input.boundarySeq) ? input.boundarySeq : null,
             boundaryEndSeq: typeof input.boundaryEndSeq === 'number' && Number.isFinite(input.boundaryEndSeq) ? input.boundaryEndSeq : null,
         });
-        const workspace = await this.captureWorkspace(chunks);
+        const workspace = await this.captureWorkspace(chunks, input.signal);
         const spreadMs = Math.abs(session.capturedAt - workspace.capturedAt);
         const record = {
             schemaVersion: ROLLBACK_SCHEMA_VERSION,
@@ -1398,11 +1751,11 @@ export class RollbackPointEngine {
     async ledgerSnapshot() {
         const now = this.stamp();
         if (this.ledgerSnapshotCache !== null && now - this.ledgerSnapshotCache.at < ROLLBACK_INHERITED_LEDGER_TTL_MS) {
-            return this.ledgerSnapshotCache.records;
+            return this.ledgerSnapshotCache.entries;
         }
-        const ledger = await this.readLedger();
-        this.ledgerSnapshotCache = { at: now, records: ledger.records };
-        return ledger.records;
+        const ledger = await this.readManifest();
+        this.ledgerSnapshotCache = { at: now, entries: ledger.entries };
+        return ledger.entries;
     }
     /**
      * 本会话/本回合**没有自己的点**时，沿继承链找祖先的同回合点（t9 的判据层）。
@@ -1420,7 +1773,7 @@ export class RollbackPointEngine {
         for (const ancestor of ancestors) {
             const hit = records.find((r) => r.sessionId === ancestor && r.turnSeq === turn);
             if (hit !== undefined)
-                return summarizeRollbackPoint(hit);
+                return entrySummaryOf(hit);
         }
         return null;
     }
@@ -1449,14 +1802,14 @@ export class RollbackPointEngine {
      * 任何东西），而 fork 子会话与父会话在**同一个项目键**下（fork 不改 cwd）⇒ 覆盖这点就够了。
      * 台账空 ⇒ 直接返回（零扫描，热路径零代价）；结果按 {@link ROLLBACK_FORK_LINKS_TTL_MS} 缓存。
      */
-    async refreshForkLinks(records) {
+    async refreshForkLinks(entries) {
         const now = this.stamp();
         if (this.forkLinksAt !== 0 && now - this.forkLinksAt < ROLLBACK_FORK_LINKS_TTL_MS)
             return;
         this.forkLinksAt = now;
         const projectKeys = new Set();
-        for (const record of records) {
-            const key = unitProjectKeyOf(record.unitId);
+        for (const entry of entries) {
+            const key = unitProjectKeyOf(entry.unitId);
             if (key !== null)
                 projectKeys.add(key);
         }
@@ -1520,14 +1873,14 @@ export class RollbackPointEngine {
      *  · `inheritedFrom` / `inheritedSessionId` 如实标出它的来处。
      * 有界（{@link ROLLBACK_INHERITED_VIEW_MAX}），超出如实标记。
      */
-    inheritedViews(records) {
+    inheritedViews(manifest) {
         const entries = [];
         let truncated = false;
         const ownTurnsOf = (sessionId) => {
             const out = new Set();
-            for (const record of records) {
-                if (record.sessionId === sessionId && record.turnSeq !== null)
-                    out.add(record.turnSeq);
+            for (const entry of manifest) {
+                if (entry.sessionId === sessionId && entry.turnSeq !== null)
+                    out.add(entry.turnSeq);
             }
             return out;
         };
@@ -1536,22 +1889,30 @@ export class RollbackPointEngine {
             if (chain.length === 0)
                 continue;
             const own = ownTurnsOf(child);
+            // 多代链（A→B→D）里同一个回合可能同时存在于多个祖先：**只取最近的那个**。
+            // 没有这份集合时，D 会拿到两条 (sessionId=D, turn=N) 却指向**不同状态**的记录，
+            // 客户端取第一条时结果随祖先顺序漂移。chain 由近到远 ⇒ 先到先得。
+            const pickedTurns = new Set();
             for (const ancestor of chain) {
-                for (const record of records) {
-                    if (record.sessionId !== ancestor || record.turnSeq === null)
+                for (const entry of manifest) {
+                    if (entry.sessionId !== ancestor || entry.turnSeq === null)
                         continue;
-                    if (own.has(record.turnSeq))
+                    if (own.has(entry.turnSeq))
                         continue; // 本会话自己有这一回合的点 ⇒ 用自己那个
+                    if (pickedTurns.has(entry.turnSeq))
+                        continue; // 更近的祖先已经提供过这一回合
                     if (entries.length >= ROLLBACK_INHERITED_VIEW_MAX) {
                         truncated = true;
                         break;
                     }
+                    pickedTurns.add(entry.turnSeq);
                     entries.push({
-                        ...summarizeRollbackPoint(record),
+                        // 段摘要来自清单里**写入时算好**的那份（口径仍是 summarizeRollbackPoint）
+                        ...entrySummaryOf(entry),
                         sessionId: child,
-                        unitId: childUnitIdOf(record.unitId, child),
-                        inheritedFrom: record.id,
-                        inheritedSessionId: record.sessionId,
+                        unitId: childUnitIdOf(entry.unitId, child),
+                        inheritedFrom: entry.id,
+                        inheritedSessionId: entry.sessionId,
                     });
                 }
                 if (truncated)
@@ -1565,12 +1926,13 @@ export class RollbackPointEngine {
     /* -------------------------------------------------------------- 列 / 读 */
     async list() {
         const storage = await this.storageStatus();
-        const ledger = await this.readLedger();
-        await this.refreshForkLinks(ledger.records);
-        const points = [...ledger.records]
+        const ledger = await this.readManifest();
+        await this.refreshForkLinks(ledger.entries);
+        // v3：列表**只读清单**（元数据 + 写入时算好的段摘要）—— 一个记录文件都不读（issue #89 的内存护栏）
+        const points = [...ledger.entries]
             .sort((a, b) => (a.createdAt > b.createdAt ? -1 : a.createdAt < b.createdAt ? 1 : 0))
-            .map(summarizeRollbackPoint);
-        const inherited = this.inheritedViews(ledger.records);
+            .map(entrySummaryOf);
+        const inherited = this.inheritedViews(ledger.entries);
         const out = {
             ok: storage.available,
             storage,
@@ -1589,16 +1951,26 @@ export class RollbackPointEngine {
     }
     async read(id) {
         const storage = await this.storageStatus();
-        const ledger = await this.readLedger();
-        const point = ledger.records.find((r) => r.id === id);
+        const ledger = await this.readManifest();
+        const entry = ledger.entries.find((r) => r.id === id);
+        // v3：records 只回传命中的那一条 —— 调用方只用 point；逐条读全部记录文件是不可接受的代价
         const out = {
-            records: ledger.records,
+            records: [],
             storage,
         };
-        if (point !== undefined)
-            out.point = point;
-        if (ledger.error !== undefined)
-            out.error = ledger.error;
+        let error = ledger.error;
+        if (entry !== undefined) {
+            const resolved = await this.readFullRecord(entry.id);
+            if (resolved.record !== undefined) {
+                out.point = resolved.record;
+                out.records = [resolved.record];
+            }
+            else if (resolved.error !== undefined) {
+                error = error === undefined ? resolved.error : error + '; ' + resolved.error;
+            }
+        }
+        if (error !== undefined)
+            out.error = error;
         return out;
     }
     /* -------------------------------------------------------------- 预览 */
@@ -1672,21 +2044,38 @@ export class RollbackPointEngine {
         // 用户忽略的整目录 ⇒ 其下内容在留点时刻未知 ⇒ 证明名单不完整（fail-closed）
         if (refused === null && payload.ignoreIncomplete === true)
             refused = 'capture-incomplete';
+        // 走查被时间预算 / 取消信号中断 ⇒ 剩余子树**一条都没进任何名单** ⇒ 同样证明不了
+        // （这是 `truncated` 之外的第四种「名单不完整」：其余三种截断都会逐条留痕）
+        if (refused === null && payload.walkIncomplete === true)
+            refused = 'capture-incomplete';
         const chunks = payload.chunks;
         // 走查上限 = 全树：候选的**准入**由证明名单负责，条数上限不再是安全阀
         //（旧上限 maxFiles*4 会在巨型工作区里静默漏掉真正的新建文件 —— 那是「删一半」，不是 fail-closed）
         const limit = Number.MAX_SAFE_INTEGER;
+        // **时间预算**：回退期的走查同样不能无限跑（分块 = 会话 cwd，家目录 / 大仓库会走很久，
+        // 而捕获侧早就有 30 s 预算 —— 只修一侧等于把 OOM 形态从留点搬到了回退）。
+        // 中断只会让候选**变少**（安全方向），但必须如实置 truncated（绝不静默漏删、也不谎报完整）。
+        const deadline = this.stamp() + this.captureBudgetMs;
+        const outOfBudget = () => this.stamp() >= deadline;
         const candidates = [];
         let truncated = false;
         for (const chunk of chunks) {
             if (!path.isAbsolute(chunk))
                 continue;
-            const listed = await this.listChunkFiles(path.resolve(chunk), sink, limit, undefined, await loadIgnoreRules(path.resolve(chunk)));
+            if (outOfBudget()) {
+                truncated = true;
+                break;
+            }
+            const listed = await this.listChunkFiles(path.resolve(chunk), sink, limit, undefined, await loadIgnoreRules(path.resolve(chunk)), outOfBudget);
             if (listed === null)
                 continue;
             if (listed.truncated)
                 truncated = true;
             for (const file of listed.files) {
+                if (outOfBudget()) {
+                    truncated = true;
+                    break;
+                }
                 if (proof.has(pathKey(file)))
                     continue;
                 candidates.push(file);
@@ -1793,7 +2182,7 @@ export class RollbackPointEngine {
     /** 只读预览：零写入（不过确认门、不拍 guard、不写任何字节）。 */
     async preview(id) {
         const storage = await this.storageStatus();
-        const ledger = await this.readLedger();
+        const ledger = await this.readManifest();
         const warnings = [];
         if (ledger.error !== undefined)
             warnings.push({ code: 'rollback.warn.ledgerUnreadable', detail: ledger.error });
@@ -1817,9 +2206,18 @@ export class RollbackPointEngine {
         if (!storage.available) {
             return { ...base, code: 'storage-unavailable', detail: storage.detail, guidance: storage.guidance };
         }
-        const record = ledger.records.find((r) => r.id === id);
-        if (record === undefined)
+        const entry = ledger.entries.find((r) => r.id === id);
+        if (entry === undefined)
             return { ...base, code: 'record-not-found' };
+        const resolved = await this.readFullRecord(entry.id);
+        if (resolved.record === undefined) {
+            // 引用解析失败（载荷文件缺失 / 哈希不符 / 形状不符）：**如实失败** —— 绝不拿半个记录去预览
+            // （半个记录会让「可回退」看起来成立，然后回退真的写错文件）
+            const detail = resolved.error ?? 'record-incomplete';
+            warnings.push({ code: 'rollback.warn.ledgerUnreadable', detail });
+            return { ...base, code: 'record-incomplete', detail };
+        }
+        const record = resolved.record;
         for (const guidance of this.trackWarnings(record))
             warnings.push(guidance);
         // 工作区态
@@ -1841,8 +2239,12 @@ export class RollbackPointEngine {
             for (const file of wsPayload.files) {
                 let outcome;
                 try {
-                    const stat = await fs.stat(file.path);
-                    outcome = { kind: 'ok', size: stat.size, regular: stat.isFile() };
+                    // **lstat，不是 stat**：写入侧用 `symlink:'reject'`（lstat 是链接即抛），预览若跟随链接就会
+                    // 说「会创建 / 会覆盖」，执行却整段失败 —— 两侧必须是同一个口径。链接一律按「不可写」报。
+                    const stat = await fs.lstat(file.path);
+                    outcome = stat.isSymbolicLink()
+                        ? { kind: 'unavailable' }
+                        : { kind: 'ok', size: stat.size, regular: stat.isFile() };
                 }
                 catch (error) {
                     outcome = classifyPreviewStatFailure(error) === 'missing' ? { kind: 'missing' } : { kind: 'unavailable' };
@@ -1988,10 +2390,16 @@ export class RollbackPointEngine {
             return { ...base, code: 'storage-unavailable', detail: storage.detail };
         if (filePath === '')
             return { ...base, detail: 'empty-path' };
-        const ledger = await this.readLedger();
-        const record = ledger.records.find((r) => r.id === id);
-        if (record === undefined)
+        const ledger = await this.readManifest();
+        const entry = ledger.entries.find((r) => r.id === id);
+        if (entry === undefined)
             return { ...base, code: 'record-not-found' };
+        const resolved = await this.readFullRecord(entry.id);
+        if (resolved.record === undefined) {
+            // 引用解析失败：**如实失败**（RollbackFileDiffResult 没有 warnings 槽位，用 detail 说清楚）
+            return { ...base, code: 'record-incomplete', detail: resolved.error ?? 'record-incomplete' };
+        }
+        const record = resolved.record;
         const payload = record.workspace.payload;
         if (!record.workspace.ok || payload === null) {
             const detail = record.workspace.reasonDetail;
@@ -2104,13 +2512,21 @@ export class RollbackPointEngine {
         if (!storage.available) {
             return this.result({ outcome: 'failed', code: 'storage-unavailable', detail: storage.detail, id: input.id, storage, guidance: storage.guidance });
         }
-        const ledger = await this.readLedger();
+        const ledger = await this.readManifest();
         if (ledger.error !== undefined)
             warnings.push({ code: 'rollback.warn.ledgerUnreadable', detail: ledger.error });
-        const record = ledger.records.find((r) => r.id === input.id);
-        if (record === undefined) {
+        const entry = ledger.entries.find((r) => r.id === input.id);
+        if (entry === undefined) {
             return this.result({ outcome: 'failed', code: 'record-not-found', id: input.id, storage, warnings });
         }
+        const resolved = await this.readFullRecord(entry.id);
+        if (resolved.record === undefined) {
+            // 记录读不完整（载荷缺失 / 哈希不符 / 形状不符）：**零写入**失败，绝不拿半个记录去回退
+            const detail = resolved.error ?? 'record-incomplete';
+            warnings.push({ code: 'rollback.warn.ledgerUnreadable', detail });
+            return this.result({ outcome: 'failed', code: 'record-incomplete', detail, id: input.id, storage, warnings });
+        }
+        const record = resolved.record;
         // 门 1（fail-closed 确认门）：必须恰好 true
         if (input.userConfirmed !== true) {
             return this.result({ outcome: 'denied', code: 'confirmation-required', detail: 'userConfirmed!==true', id: input.id, storage, warnings });
@@ -2253,7 +2669,9 @@ export class RollbackPointEngine {
             return 'outside-chunk';
         if (isInsidePath(file, this.root))
             return 'inside-data-dir';
-        const segments = path.resolve(file).split(path.sep);
+        // Windows 文件系统**不分大小写**：`.GIT` / `.Git` / `NODE_MODULES` 是同一个目录，必须折大小写后
+        // 再比 —— 不折会让它们的子树失去保护（本文件其它路径判据都走 win32Fold，这里此前漏了）。
+        const segments = win32Fold(path.resolve(file)).split(/[\\/]+/);
         if (segments.includes('.git'))
             return 'excluded-dir';
         if (segments.includes('node_modules'))
@@ -2362,17 +2780,56 @@ export class RollbackPointEngine {
                 noop.createdRefusedReason = removal.refused;
             return noop;
         }
-        // 前像（内存）：失败时要能整体回到恢复前状态 —— 只覆盖**真会被写**的文件
-        const pre = [];
+        // 前像（**字节落盘、索引随栈**）：失败时要能整体回到恢复前状态 —— 只覆盖**真会被写**的文件。
+        // 字节之所以不留在内存：大工作区整体回退时前像峰值 = 待写总字节（可达数百 MB），
+        // 与 issue #89 的 OOM 同族；落盘后内存只随**文件条数**增长。
+        // 暂存目录建不出来 ⇒ **零写入失败**（fail-closed）：回退没有安全网就不该开始。
+        const stager = await this.openUndoStager();
+        if (stager === null) {
+            pushDetail(detail, 'undo-staging-unavailable root=' + this.root + ' zeroWrites=true');
+            return {
+                state: 'workspace', status: 'failed', reasonCode: 'restore-failed', detail,
+                restored: 0, failed: needed.length + removal.paths.length,
+                leftovers: leftovers.leftovers, leftoversTruncated: leftovers.truncated,
+            };
+        }
+        const preCount = needed.length;
         for (const item of needed) {
             let bytes = null;
+            let unreadable = null;
             try {
                 bytes = await fs.readFile(item.file.path);
             }
-            catch {
-                bytes = null;
+            catch (error) {
+                // **只认 ENOENT = 当时确实不存在**。其它 errno（EACCES / EMFILE / EBUSY…）是
+                // 「读不出来」而不是「没有」—— 折成 null 会让回滚阶段把这个**存在**的文件删掉
+                // （UndoStager.stage(null) 的语义正是「回滚时删掉它」）。
+                if (error.code !== 'ENOENT')
+                    unreadable = errorDetail(error);
+            }
+            if (unreadable !== null) {
+                await stager.dispose();
+                pushDetail(detail, 'preimage-unreadable ' + item.file.path + ' ' + unreadable + ' zeroWrites=true');
+                return {
+                    state: 'workspace', status: 'failed', reasonCode: 'restore-failed', detail,
+                    restored: 0, failed: needed.length + removal.paths.length,
+                    leftovers: leftovers.leftovers, leftoversTruncated: leftovers.truncated,
+                };
+            }
+            try {
+                await stager.stage(item.file.path, bytes);
+            }
+            catch (error) {
+                // 暂存写不下去（ENOSPC / EACCES）：**零写入失败** —— 绝不带着不完整的前像开工，
+                // 也绝不让异常穿出引擎（那会被路由兜成没有机器码的裸 500，且暂存目录无人清理）。
+                await stager.dispose();
+                pushDetail(detail, 'preimage-stage-failed ' + item.file.path + ' ' + errorDetail(error) + ' zeroWrites=true');
+                return {
+                    state: 'workspace', status: 'failed', reasonCode: 'restore-failed', detail,
+                    restored: 0, failed: needed.length + removal.paths.length,
+                    leftovers: leftovers.leftovers, leftoversTruncated: leftovers.truncated,
+                };
             }
-            pre.push({ path: item.file.path, existed: bytes !== null, bytes });
         }
         let restored = 0;
         let writtenBytes = 0;
@@ -2402,23 +2859,13 @@ export class RollbackPointEngine {
             }
         }
         if (failed > 0 || mismatched.length > 0) {
-            const rollbackFailed = [];
-            for (const item of pre) {
-                try {
-                    if (item.existed && item.bytes !== null)
-                        await this.writeFile(item.path, item.bytes);
-                    else
-                        await fs.rm(item.path, { force: true });
-                }
-                catch (error) {
-                    rollbackFailed.push(item.path + ' ' + errorDetail(error));
-                }
-            }
+            const rollbackFailed = await stager.rollback((target, bytes) => this.writeFile(target, bytes));
+            await stager.dispose();
             for (const target of mismatched)
                 pushDetail(detail, 'verify-mismatch ' + target);
             for (const line of rollbackFailed)
                 pushDetail(detail, 'rolled-back-failed ' + line);
-            detail.push('restored=0 failed=' + String(failed + mismatched.length) + ' rolledBack=' + String(pre.length - rollbackFailed.length) + ' unchanged=' + String(unchanged));
+            detail.push('restored=0 failed=' + String(failed + mismatched.length) + ' rolledBack=' + String(preCount - rollbackFailed.length) + ' unchanged=' + String(unchanged));
             return {
                 state: 'workspace', status: 'failed',
                 reasonCode: mismatched.length > 0 ? 'verify-failed' : 'restore-failed',
@@ -2433,7 +2880,8 @@ export class RollbackPointEngine {
         // 阶段 4（用户 2026-10-11 定案 A）：删除「回退点之后新建」的路径。
         // 顺序刻死：记录在案的路径**先写并复核通过**，再删新建的 —— 先删后写一旦写失败就回不去了。
         // 删除同样可回滚：先读前像（内存）→ 删；任一失败就把已写的还原、把已删的写回。
-        const destroyed = [];
+        // 待删文件的前像同样落盘（stage(path, bytes) 的语义就是「回滚时把它写回」）
+        let destroyedCount = 0;
         const removalFailures = [];
         // 逐条记录**真的删掉**的路径（全量，不再切 20 条）：它与预览的 workspace.removals 同源同序，
         // 界面把两份清单当作同一件事（「预览说会删的 = 实际删的」）。
@@ -2447,7 +2895,8 @@ export class RollbackPointEngine {
                     removal.skipped.push(target);
                     continue;
                 }
-                destroyed.push({ path: target, bytes });
+                await stager.stage(target, bytes);
+                destroyedCount += 1;
                 await fs.rm(target, { force: true });
                 removed += 1;
                 removedPaths.push(target);
@@ -2457,32 +2906,14 @@ export class RollbackPointEngine {
             }
         }
         if (removalFailures.length > 0) {
-            const rollbackFailed = [];
-            for (const item of pre) {
-                try {
-                    if (item.existed && item.bytes !== null)
-                        await this.writeFile(item.path, item.bytes);
-                    else
-                        await fs.rm(item.path, { force: true });
-                }
-                catch (error) {
-                    rollbackFailed.push(item.path + ' ' + errorDetail(error));
-                }
-            }
-            for (const item of destroyed) {
-                try {
-                    await this.writeFile(item.path, item.bytes);
-                }
-                catch (error) {
-                    rollbackFailed.push(item.path + ' ' + errorDetail(error));
-                }
-            }
+            const rollbackFailed = await stager.rollback((target, bytes) => this.writeFile(target, bytes));
+            await stager.dispose();
             for (const line of removalFailures)
                 pushDetail(detail, 'created-remove-failed ' + line);
             for (const line of rollbackFailed)
                 pushDetail(detail, 'rolled-back-failed ' + line);
             detail.push('restored=0 removed=0 failed=' + String(removalFailures.length) +
-                ' rolledBack=' + String(pre.length + destroyed.length - rollbackFailed.length) +
+                ' rolledBack=' + String(preCount + destroyedCount - rollbackFailed.length) +
                 ' unchanged=' + String(unchanged));
             return {
                 state: 'workspace', status: 'failed', reasonCode: 'restore-failed', detail,
@@ -2508,6 +2939,8 @@ export class RollbackPointEngine {
         // 捕获不完整 ⇒ 一条都没删：如实回报原因（界面据此说「因为捕获不完整，一条都没动」）
         if (removal.refused !== null)
             segment.createdRefusedReason = removal.refused;
+        // 前像字节用完即清（成功路径）：留在磁盘上只会变成无人认领的残留
+        await stager.dispose();
         return segment;
     }
     /**
@@ -2589,24 +3022,86 @@ export class RollbackPointEngine {
         if (!storage.available)
             return { ok: false, code: 'storage-unavailable', detail: storage.detail, id };
         return await withLedgerWriteLock(this.ledgerPath, async () => {
-            const ledger = await this.readLedger();
-            const record = ledger.records.find((r) => r.id === id);
-            if (record === undefined)
+            const ledger = await this.readManifest();
+            if (this.initError !== undefined) {
+                return { ok: false, code: 'ledger-write-failed', detail: this.initError, id };
+            }
+            // 删除只看**清单元数据**（protected / kind 都在清单里）—— 一个记录文件都不读、一个载荷都不读
+            const entry = ledger.entries.find((r) => r.id === id);
+            if (entry === undefined)
                 return { ok: false, code: 'record-not-found', id };
-            if (record.protected || record.kind === 'guard') {
-                return { ok: false, code: 'protected-point', detail: record.kind, id };
+            if (entry.protected || entry.kind === 'guard') {
+                return { ok: false, code: 'protected-point', detail: entry.kind, id };
             }
-            const kept = ledger.records.filter((r) => r.id !== id);
+            const kept = ledger.entries.filter((r) => r.id !== id);
             try {
-                await atomicWriteFile(this.ledgerPath, JSON.stringify({ schemaVersion: ROLLBACK_SCHEMA_VERSION, records: kept }, null, 2));
+                await this.ledger.writeManifest(kept);
             }
             catch (error) {
                 return { ok: false, code: 'ledger-write-failed', detail: errorDetail(error), id };
             }
+            await this.ledger.deleteRecords([id]);
+            await this.ledger.prunePayloads(kept);
             await this.gcObjects(kept);
             return { ok: true, code: 'deleted', id };
         });
     }
+    /**
+     * 磁盘清理入口（引擎侧）：删**全部**自动点（includeGuards=true 时连 guard 也删），
+     * protected 点**永不删**（生产路径造不出来，只有测试能造）。随后回收无人引用的载荷与对象。
+     *
+     * 零写入拒绝路径照旧：存储不可用 / 清单读不出来（形状不符、迁移失败、迁移中）⇒ **抛带 code 的错误**，
+     * 一个字节都不动、也绝不静默返回全 0（「什么都没删」与「读不出来所以没删」是两件事）。
+     * 返回的 bytes = 本次真正删掉的字节（记录文件 + 载荷文件 + 对象文件）。
+     */
+    async purgeLedger(options = {}) {
+        const storage = await this.storageStatus();
+        if (!storage.available) {
+            throw new RollbackLedgerRefusedError('storage-unavailable', storage.detail ?? 'rollback storage unavailable');
+        }
+        return await withLedgerWriteLock(this.ledgerPath, async () => {
+            const ledger = await this.readManifest();
+            if (this.initError !== undefined)
+                throw new RollbackLedgerRefusedError('ledger-unreadable', this.initError);
+            if (ledger.error !== undefined)
+                throw new RollbackLedgerRefusedError('ledger-unreadable', ledger.error);
+            const includeGuards = options.includeGuards === true;
+            const victims = ledger.entries.filter((entry) => !entry.protected && (includeGuards || entry.kind === 'auto'));
+            if (victims.length === 0)
+                return { removedRecords: 0, removedPayloads: 0, removedObjects: 0, bytes: 0 };
+            const victimIds = new Set(victims.map((entry) => entry.id));
+            const kept = ledger.entries.filter((entry) => !victimIds.has(entry.id));
+            // 先落清单、再删文件：崩在中途也只会留下「清单已删、文件还在」的垃圾，不会留下指向空文件的清单
+            await this.ledger.writeManifest(kept);
+            const records = await this.ledger.deleteRecords([...victimIds]);
+            const payloads = await this.ledger.prunePayloads(kept);
+            const objects = await this.ledger.collectObjects(kept);
+            if (objects.aborted === null) {
+                await this.gcPathCache(new Set([...objects.referencedPaths].map(pathKey)));
+            }
+            else {
+                this.warn('rollback purge: object gc skipped: ' + objects.aborted);
+            }
+            return {
+                removedRecords: records.removed,
+                removedPayloads: payloads.removed,
+                removedObjects: objects.removed,
+                bytes: records.bytes + payloads.bytes + objects.bytes,
+            };
+        });
+    }
+}
+/**
+ * 台账清理的**显式拒绝**（形状不符 / 存储不可用）：带机器可读 code，绝不静默返回全 0。
+ * 路由层按 code 映射 HTTP（与既有 RollbackCode 冻结集同源）。
+ */
+export class RollbackLedgerRefusedError extends Error {
+    code;
+    constructor(code, detail) {
+        super(detail);
+        this.name = 'RollbackLedgerRefusedError';
+        this.code = code;
+    }
 }
 function uniqueStates(states) {
     const out = [];
@@ -2665,6 +3160,12 @@ export function rollbackSessionBindingOf(session) {
     }
     const header = session.header;
     const headerRecord = header !== null && typeof header === 'object' ? header : null;
+    // 子代理会话**不自动留点**（见 RollbackCode 的 'subagent-session'）：它的工作区与父会话相同、
+    // 回合号是自己的，留点只挤占用户自己会话的预算。**只在字段逐字等于 'subagent' 时判定** ——
+    // 读不到 origin（老宿主 / 形状不符）就不判，绝不因为读不到而少留点。
+    if (headerRecord?.['origin'] === 'subagent') {
+        return { ok: false, code: 'subagent-session', detail: 'origin=subagent session=' + id };
+    }
     const cwd = headerRecord?.['cwd'];
     // t9：父链与「是否播种而来」只从**活会话头**读；读不到就不带字段（＝不是继承子会话），绝不猜
     const fork = {};
@@ -2792,6 +3293,8 @@ export class RollbackAutoTracker {
     lastStat = new Map();
     timer = null;
     mechanism = 'event';
+    /** 在途捕获的取消信号（stop() 时 abort；重新 start() 时换一个新的） */
+    captureAbort = new AbortController();
     constructor(options) {
         this.engine = options.engine;
         this.nowFn = options.now ?? (() => Date.now());
@@ -2831,6 +3334,8 @@ export class RollbackAutoTracker {
             boundaryEndSeq: info.endSeq,
             chunks: binding.chunks ?? [],
             note: this.mechanism === 'poll' ? 'auto:poll' : 'auto:turn',
+            // 卸载 / 停止 ⇒ 立刻中断在途捕获（下一个文件边界停下；已收条目照常成点）
+            signal: this.captureAbort.signal,
         });
         // T10：写台账失败（ok=false）绝不算留点成功 —— 否则 tracker 会记住一个台账里不存在的 pointId，
         // 后续 rewind/详情都查不到它。（capturePoint 失败时也不再回传 point，这条判据是第二道保险。）
@@ -2971,6 +3476,9 @@ export class RollbackAutoTracker {
     start() {
         if (this.timer !== null)
             return;
+        // 上一轮 stop() 已经把信号 abort 掉：重新 start 必须换一个新的，否则捕获一动就停。
+        if (this.captureAbort.signal.aborted)
+            this.captureAbort = new AbortController();
         this.mechanism = 'poll';
         this.timer = setInterval(() => {
             void this.pollOnce().catch((error) => { this.warn('rollback tracker poll failed: ' + errorDetail(error)); });
@@ -2980,6 +3488,8 @@ export class RollbackAutoTracker {
             handle.unref();
     }
     stop() {
+        // 中断在途捕获：卸载之后不该再有任何一次「读工作区 + 写对象仓」跑完。
+        this.captureAbort.abort();
         if (this.timer === null)
             return;
         clearInterval(this.timer);