dsh-config-manager 0.1.72 → 0.1.76

package/lib/core/rollback-point.js

@@ -74,12 +74,26 @@ 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';
 /* ------------------------------------------------------------------ 常量 */
+/** 增量链的最大长度：到顶就落一个**全量锚点**（重建最多读 1 份全量 + 几份小增量） */
+const ROLLBACK_DELTA_CHAIN_LIMIT = 8;
+/** 增量视图只有在小于全量的这个比例时才采用（否则直接全量，简单可靠） */
+const ROLLBACK_DELTA_MAX_RATIO = 0.6;
 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 +171,55 @@ 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;
+/**
+ * 自适应预算区间（见 RollbackEngineOptions.captureBudgetMs）：上一次留点被截断 ⇒ 下次 ×2，
+ * 上一次只用掉不到 1/4 ⇒ 下次 ÷2。区间外不再调整（避免无限拉长 / 缩到不可用）。
+ */
+export const ROLLBACK_MIN_CAPTURE_BUDGET_MS = 10_000;
+export const ROLLBACK_MAX_CAPTURE_BUDGET_MS = 120_000;
+/**
+ * 捕获期「读内容 + 写对象仓」的并发上限。
+ *
+ * 为什么必须并发：真机实测（34k 文件 / 512 MiB）一次全量捕获 175 s，其中 **148 s 花在
+ * 31,702 次对象写**（一次 4.7 ms：temp + fsync + rename），而走查本身只要 0.66 s。
+ * 对象写入是纯 I/O，串行做等于把预算全花在等待上 ⇒ 覆盖永远只有一小半。
+ * 并发上限与**在飞字节闸门**共同限流（在飞内容上界 = `captureInFlightBytes`）。
+ */
+export const ROLLBACK_DEFAULT_CAPTURE_CONCURRENCY = 16;
+/**
+ * 捕获期**读入内存、尚未落对象仓**的内容字节上限（真正的内存闸门）。
+ *
+ * 为什么必须独立于 `maxFileBytes`（0.1.74 真机闪退事故，2026-10-16）：
+ *  `maxFileBytes` 的缺省是**总量预算** `maxBytes`（512 MiB）。并发捕获把闸门接到它上面，
+ *  于是「同时在飞的内容」可以到 ~512 MiB —— 串行实现的上界是「一份文件」，并发实现的
+ *  上界是「闸门限额」，两者差着两三个数量级。真机表现：发出消息后 1–2 s（= `turn/start`
+ *  开始留点）DSH Desktop 宿主被系统终止 ⇒ 桌面闪退（无 JS 栈、插件零错误、
+ *  退出码是「被外部终止」形状）。这里取一个小常量当闸门；要放宽只能显式传
+ *  `captureInFlightBytes`，且被 `maxBytes` 夹住。
+ */
+export const ROLLBACK_DEFAULT_CAPTURE_INFLIGHT_BYTES = 32 * 1024 * 1024;
+/** 对象写遇到这些码视为「瞬时占用」，有界退避重试（判据同 atomic-write 的 isRetryableLockCode） */
+const OBJECT_WRITE_RETRY_CODES = ['EPERM', 'EBUSY', 'EACCES', 'ENOTEMPTY'];
+/** 捕获阶段①的 stat 批大小：判定仍严格按顺序，只是 stat 并发取（真机 34k 次 stat 从 5 s → <1 s） */
+export const ROLLBACK_CAPTURE_STAT_BATCH = 128;
+/**
+ * 捕获期**候选名单**上限（不是入点上限）：必须显著大于 maxFiles，否则「缺口优先」排序作用不到
+ * 那些排在遍历顺序尾部、上一回合没覆盖到的文件（它们连候选都进不了 ⇒ 覆盖率永远不收敛）。
+ * 走查本来就会把每条路径记进 walked（路径索引的来源），这里多留的只是候选数组本身。
+ */
+export const ROLLBACK_CAPTURE_LIST_LIMIT = 200_000;
+/** 走查中断时逐条记下的「没进去的子树」上限；超出即放弃精确范围，退回全局 fail-closed */
+export const ROLLBACK_UNWALKED_DIRS_LIMIT = 200;
 /**
  * 「删除回退点之后新建的路径」的**整套上限**（用户 2026-10-11 定案 A）。
  * 超过就整套拒绝（fail-closed），绝不删一半 —— 半套删除既没有可解释的状态，也无法整体回滚。
@@ -188,6 +251,14 @@ export const ROLLBACK_PREVIEW_DIFF_TOTAL_WORK = 32_000_000;
 export const ROLLBACK_FILE_DIFF_LIMITS = {
     maxFileBytes: ROLLBACK_PREVIEW_DIFF_MAX_FILE_BYTES,
     context: 3,
+    /**
+     * Myers 编辑距离上限（2026-10-15 用户：不该动辄出现「已按整块替换展示」）。
+     * 实测（本仓 rollback-point.ts 的 4983 行 × 2492 行版本对）：D 在 3000~4000 就能拿到
+     * 最小编辑脚本 —— 耗时 ≤70 ms；代价是回溯的 V 快照 O(D²)，RSS 峰值 +~100 MB。
+     * 缺省那档 400 会让几千行里的普通改动一律退化成「整块替换」，那正是用户看到的那条提示；
+     * 单文件是**按需点开**的一屏，这点内存换「真差异」划算。再大就换算法，不加预算。
+     */
+    maxD: 4000,
 };
 /** 恢复顺序（工作区在前；工作区失败即中止后面的会话段） */
 export const ROLLBACK_REWIND_ORDER = ['workspace', 'session'];
@@ -211,6 +282,24 @@ export const ROLLBACK_PATH_CACHE_NAME = 'path-cache.json';
 function win32Fold(value) {
     return process.platform === 'win32' ? value.toLowerCase() : value;
 }
+/**
+ * 路径里是否存在以 `.asar` 结尾的段（**捕获 / 走查期一律不碰这类路径**）。
+ *
+ * 为什么（真机事故，0.1.76）：Electron 宿主对任何含 `.asar` 段的路径**启用了 asar 虚拟化** ——
+ * 即使那只是个普通文件，`fs.stat`/`readdir`/`read` 也会被接管去当容器解析。工作区里只要躺着一枚
+ * **畸形** `.asar`（测试夹具、被打断的打包残留），宿主进程就会被原生层带走：crashpad
+ * `not connected`、退出码 4294930435 ⇒ DSH Desktop 闪退（无 JS 栈、插件零错误）。
+ * 实测（本仓真机捕获、同一份输入）：`.tmp` 下 19 枚 `.asar` 夹具在场 → Electron 进程死；
+ * 全部改名后 → 同一趟捕获 9 s 跑完、退出码 0。
+ * `.asar.unpacked` 是**真目录**（段名不以 `.asar` 结尾）⇒ 不拦。
+ */
+export function hasAsarSegment(target) {
+    for (const segment of target.split(/[\\/]+/)) {
+        if (segment.length > '.asar'.length && win32Fold(segment).endsWith('.asar'))
+            return true;
+    }
+    return false;
+}
 /** child 是否等于 parent 或位于其下（win32 折叠大小写；段边界判定） */
 export function isInsidePath(child, parent) {
     const c = win32Fold(path.resolve(child));
@@ -221,6 +310,82 @@ export function isInsidePath(child, parent) {
 function pathKey(value) {
     return win32Fold(path.resolve(value));
 }
+/** 两个分块列表是否逐个相同（增量基准必须作用于同一批分块） */
+function sameChunks(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i += 1)
+        if (a[i] !== b[i])
+            return false;
+    return true;
+}
+/**
+ * **存盘视图**：条目里的 `object` 恒等于 `sha256`（内容寻址的名字就是内容哈希）⇒ 落盘时不写这个字段，
+ * 读取时按 `sha256` 补回（见 ledger 的 `withObjectRefs`）。每条约省 1/5 字节。
+ */
+function compactPayloadForStorage(payload) {
+    const strip = (list) => {
+        if (!Array.isArray(list))
+            return list;
+        return list.map((file) => {
+            const copy = { ...file };
+            delete copy['object'];
+            return copy;
+        });
+    };
+    const delta = payload.delta;
+    return {
+        ...payload,
+        files: strip(payload.files),
+        ...(delta === undefined
+            ? {}
+            : { delta: { ...delta, ...(delta.added === undefined ? {} : { added: strip(delta.added) }) } }),
+    };
+}
+/**
+ * 构造「相对基准的增量视图」；不划算（≥ 全量 × {@link ROLLBACK_DELTA_MAX_RATIO}）时返回 null。
+ *
+ * 条目**逐字比较**：路径、sha、字节数、mtimeMs、所属分块任一不同 ⇒ 进 `added`；基准里不再存在的路径进 `removed`。
+ * 重建 = 基准 − removed，再用 added 覆盖/追加，最后按路径排序（与全量捕获同序）。
+ */
+/** 基准摘要键：内容 + 字节数 + 所属分块（`mtimeMs` 不参与 —— 只被触摸、内容没变的文件不必进增量） */
+function digestKeyOf(file) {
+    return String(file.sha256) + ':' + String(file.bytes) + ':' + String(file.chunk);
+}
+/** 相对**内存基准摘要**的条目差异（新增/改写 / 不再存在）；路径逐字比较，不读任何文件 */
+function payloadDiffAgainstDigest(payload, baseEntries) {
+    const added = [];
+    const nextPaths = new Set();
+    for (const file of payload.files) {
+        nextPaths.add(file.path);
+        const prev = baseEntries.get(file.path);
+        if (prev === undefined || prev !== digestKeyOf(file))
+            added.push(file);
+    }
+    const removed = [];
+    for (const path of baseEntries.keys())
+        if (!nextPaths.has(path))
+            removed.push(path);
+    return { added, removed };
+}
+/**
+ * 构造「相对基准的增量视图」；不划算（≥ 全量 × {@link ROLLBACK_DELTA_MAX_RATIO}）时返回 null。
+ * 重建 = 基准 − removed，再用 added 覆盖/追加，最后按路径排序（与全量捕获同序）。
+ */
+function buildPayloadDelta(payload, baseHash, baseChain, diff) {
+    if (baseHash === '')
+        return null;
+    const delta = {
+        ...payload,
+        // **故意不是数组**：不认识 `delta` 的旧读取器会在形状校验这一步**拒绝这个点**（fail-closed），
+        // 而不是把「增量那几条」当成完整清单去规划删除 —— 那会把留点时存在的文件全判成新建、全部删掉。
+        files: null,
+        delta: { base: baseHash, baseChain: [...baseChain], removed: diff.removed, added: diff.added },
+    };
+    if (JSON.stringify(delta).length >= JSON.stringify(payload).length * ROLLBACK_DELTA_MAX_RATIO)
+        return null;
+    return delta;
+}
 function errorDetail(error) {
     if (error instanceof Error) {
         const code = error.code;
@@ -419,6 +584,17 @@ export function resolveTurnBoundary(events, turnSeq) {
     }
     return { ok: true, boundarySeq: boundary.boundarySeq, endSeq: boundary.endSeq };
 }
+/**
+ * 记录在案的文件条目数：优先用载荷自带的 `fileCount`（增量视图下 `files` 可能只是子集），
+ * 老载荷没有该字段才回落到 `files.length`。
+ */
+export function workspaceFileCount(payload) {
+    if (payload === null)
+        return 0;
+    if (typeof payload.fileCount === 'number' && Number.isFinite(payload.fileCount))
+        return payload.fileCount;
+    return payload.files.length;
+}
 export function summarizeRollbackPoint(record) {
     const workspace = record.workspace.payload;
     const session = record.session.payload;
@@ -449,7 +625,7 @@ export function summarizeRollbackPoint(record) {
         note: record.note,
         spreadMs: record.spreadMs,
         segments: [
-            segment('workspace', record.workspace, workspace?.files.length ?? 0, workspace?.bytes ?? 0, null, (workspace?.files.length ?? 0) > 0, workspace?.skippedCount ?? 0, workspace?.truncated ?? false),
+            segment('workspace', record.workspace, workspaceFileCount(workspace), workspace?.bytes ?? 0, null, workspaceFileCount(workspace) > 0, workspace?.skippedCount ?? 0, workspace?.truncated ?? false),
             segment('session', record.session, session === null ? 0 : 1, session?.bytes ?? 0, session?.cursorBytes ?? null, session !== null && session.sessionId !== null && session.boundarySeq !== null, 0, false),
         ],
     };
@@ -524,6 +700,105 @@ 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 */
+        }
+    }
+}
+/**
+ * 单文件字节闸门：保证「同时在飞（已读入、尚未落仓）的内容字节」≤ limit。
+ *
+ * 与 captureConcurrency 一起构成捕获期的内存上界：并发只放大**同时**驻留的量，而它被
+ * `captureInFlightBytes` 钉死（缺省 32 MiB）。**不能**用 maxFileBytes 当限额 —— 它缺省 =
+ * 总量预算 512 MiB，「一份文件」与「整个点的预算」不是同一个量级（0.1.74 闪退根因）。
+ */
+/**
+ * 路径身份键：dev:ino:size:mtimeNs:ctimeNs:mode（全 BigInt 字符串化）。必须 BigInt：ino / mtimeNs /
+ * ctimeNs 在 64 位 inode 文件系统上超出 Number 安全整数范围，用 Number 会静默丢精度（把两次不同的
+ * 写当成同一个身份）。单一来源：fileStatOf 与 pathIdentityOf 都用它。
+ */
+function fileIdentityOf(stat) {
+    return [
+        String(stat.dev),
+        String(stat.ino),
+        String(stat.size),
+        String(stat.mtimeNs),
+        String(stat.ctimeNs),
+        String(stat.mode & 511n),
+    ].join(':');
+}
+class ByteGate {
+    used = 0;
+    waiters = [];
+    limit;
+    constructor(limit) {
+        this.limit = limit;
+    }
+    async acquire(bytes) {
+        const need = Math.max(0, Math.min(bytes, this.limit));
+        while (this.used + need > this.limit && this.used > 0) {
+            await new Promise((resolve) => { this.waiters.push(resolve); });
+        }
+        this.used += need;
+    }
+    release(bytes) {
+        this.used = Math.max(0, this.used - Math.max(0, Math.min(bytes, this.limit)));
+        const next = this.waiters.shift();
+        if (next !== undefined)
+            next();
+    }
+}
 export class RollbackPointEngine {
     dataDir;
     homeDir;
@@ -535,6 +810,7 @@ export class RollbackPointEngine {
     maxFiles;
     maxBytes;
     maxFileBytes;
+    captureInFlightBytes;
     maxSkippedEntries;
     sessionMaxBytes;
     sessionQuiescentMs;
@@ -564,9 +840,49 @@ export class RollbackPointEngine {
     forkLinksAt = 0;
     forkLinksComplete = true;
     /** 会话日志头缓存（mtime + size 失效；只服务 fork 链扫描） */
+    /**
+     * **本进程**最近一次成功留点的工作区摘要（清单增量化的基准）。
+     *
+     * 为什么是内存而不是读盘：一次留点只准读清单（L-08 / issue #89）—— 读上一份 12 MB 载荷去算差异
+     * 正是那条被消灭的路。内存量 ≈ 每文件一个 `sha:bytes:chunk` 串（3.4 万文件约几 MB），
+     * 与已有的身份缓存（`pathCache`）同量级；进程重启后第一次留点落全量锚点，随后继续链。
+     */
+    deltaBase = null;
     forkHeaderCache = new Map();
-    /** 继承判据用的台账快照（TTL 缓存；避免每个 turn/start 都读整份台账） */
+    /** 继承判据用的台账快照（TTL 缓存；只缓存**清单条目**，绝不缓存完整记录） */
     ledgerSnapshotCache = null;
+    /** 台账存储层（v3：清单 + 单条记录 + 内容寻址载荷；issue #89） */
+    ledger;
+    ledgerBytesBudget;
+    /**
+     * 工作区捕获的挂钟时间预算（毫秒；见 ROLLBACK_DEFAULT_CAPTURE_BUDGET_MS）。**可变**：
+     * 每次留点后按「是否被截断 / 用掉多少」自适应（见 ROLLBACK_MIN/MAX_CAPTURE_BUDGET_MS）。
+     */
+    captureBudgetMs;
+    /** 自适应区间下界 / 上界（构造期定死，运行期只调 captureBudgetMs） */
+    captureBudgetMinMs;
+    captureBudgetMaxMs;
+    /** 回退期走查的时间预算（与捕获预算分开：自适应不该顺手拉长回退期的走查） */
+    rewindBudgetMs;
+    /** 捕获期读 + 写并发上限 */
+    captureConcurrency;
+    /** 对象仓目录已确认存在（省掉每个对象一次 mkdir） */
+    objectsDirReady = false;
+    /**
+     * 本回合对象名单快照（一次 readdir 顶掉「每个候选一次 fs.access」；真机 34k 次 access ≈ 3.7 s）。
+     * null = 读不到名单（首次还没建目录/异常）⇒ 回落逐条 objectExists。
+     * 只保证「写进去的立刻可见」：捕获期间被**并发删除**的对象可能仍被判为存在 —— 那一路由
+     * 读取侧（readObject + 哈希校验）响亮失败，不会静默给出错误的 before 内容。
+     */
+    captureObjectNames = null;
+    /**
+     * 启动期一次性初始化（流式迁移 v2 -> v3 + 孤儿 tmp 清理）的惰性单飞。
+     * 为什么惰取而不是构造时同步跑：构造发生在每个请求路径上，同步扫盘/迁移会把请求卡死；
+     * 而「每回合都扫一遍」正是要避免的浪费 —— 所以只跑一次并记住结果。
+     */
+    initPromise = null;
+    /** 启动期初始化失败的如实记录（读路径必须报出来，绝不假装台账是空的） */
+    initError;
     constructor(options) {
         this.dataDir = path.resolve(options.dataDir);
         this.homeDir = path.resolve(options.homeDir);
@@ -579,6 +895,10 @@ export class RollbackPointEngine {
         this.maxBytes = options.maxBytes ?? ROLLBACK_DEFAULT_MAX_BYTES;
         // 单文件上限缺省 = 总量预算（一个文件不可能比整个点的预算更大）
         this.maxFileBytes = options.maxFileBytes ?? this.maxBytes;
+        // **内存闸门与单文件上限分开**：拿 maxFileBytes 当闸门 = 允许把整个点的预算同时驻留
+        // （0.1.74 真机闪退的根因），见 ROLLBACK_DEFAULT_CAPTURE_INFLIGHT_BYTES。
+        const inFlight = options.captureInFlightBytes ?? ROLLBACK_DEFAULT_CAPTURE_INFLIGHT_BYTES;
+        this.captureInFlightBytes = Math.max(1, Math.min(this.maxBytes, Math.floor(inFlight)));
         this.maxSkippedEntries = options.maxSkippedEntries ?? ROLLBACK_SKIPPED_LIST_LIMIT;
         this.sessionMaxBytes = options.sessionMaxBytes ?? ROLLBACK_DEFAULT_SESSION_MAX_BYTES;
         this.sessionQuiescentMs = options.sessionQuiescentMs ?? ROLLBACK_DEFAULT_SESSION_QUIESCENT_MS;
@@ -596,6 +916,22 @@ 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.captureBudgetMinMs = options.captureBudgetMinMs ?? ROLLBACK_MIN_CAPTURE_BUDGET_MS;
+        this.captureBudgetMaxMs = options.captureBudgetMaxMs ?? ROLLBACK_MAX_CAPTURE_BUDGET_MS;
+        this.rewindBudgetMs = options.rewindBudgetMs ?? this.captureBudgetMs;
+        this.captureConcurrency = Math.max(1, Math.min(64, Math.floor(options.captureConcurrency ?? ROLLBACK_DEFAULT_CAPTURE_CONCURRENCY)));
+        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 +979,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 +1003,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,25 +1058,86 @@ 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;
+        }
     }
     /* -------------------------------------------------------------- 对象仓 */
+    /** 对象仓目录只 mkdir 一次（每个对象各 mkdir 一次是纯白花的 syscall） */
+    async ensureObjectsDir() {
+        if (this.objectsDirReady)
+            return;
+        await fs.mkdir(this.objectsDir, { recursive: true });
+        this.objectsDirReady = true;
+    }
+    /**
+     * 写内容寻址对象（对象文件名 = 内容 SHA-256）。
+     *
+     * **为什么这里不用 atomicWriteFile**：那是给「可写配置文件」用的强原子写（同目录 tmp → fsync →
+     * rename），真机实测一次约 4.7 ms —— 34k 文件的工作区一次全量捕获 148 s 全花在它上面（走查本身
+     * 只要 0.66 s）。对象仓的正确性要求不同：文件名即内容哈希 ⇒
+     *   · 用 'wx' **独占创建最终名**本身已是原子的（不覆盖已有对象；并发同写只有一方成功）；
+     *   · 半截 / 被篡改的内容在读取侧必然过不了哈希校验（readObject + sha256Hex）⇒ 按「读不出」
+     *     处理并 fail-closed，绝不会冒充有效前像；
+     *   · 不做 fsync：回滚点是尽力而为的本地快照，不为掉电持久性付出每文件一次 fsync 的代价。
+     */
     async writeObjectWithHash(bytes, sha) {
         if (!OBJECT_KEY_RE.test(sha))
             throw new Error('rollback object key invalid');
         const target = path.join(this.objectsDir, sha);
         if (!isInsidePath(target, this.objectsDir))
             throw new Error('rollback object path escapes store');
-        await fs.mkdir(this.objectsDir, { recursive: true });
-        try {
-            await fs.access(target);
-            return sha;
+        await this.ensureObjectsDir();
+        let delay = 10;
+        for (let attempt = 0;; attempt += 1) {
+            try {
+                await fs.writeFile(target, bytes, { flag: 'wx' });
+                this.captureObjectNames?.add(sha);
+                return sha;
+            }
+            catch (error) {
+                const code = error.code;
+                if (code === 'EEXIST')
+                    return sha; // 已有同内容对象（去重 / 并发竞写）
+                // 杀软 / 句柄瞬时占用：有界退避重试（与 atomic-write 的判据同族）
+                if (OBJECT_WRITE_RETRY_CODES.includes(code) && attempt < 3) {
+                    await new Promise((resolve) => setTimeout(resolve, delay));
+                    delay *= 2;
+                    continue;
+                }
+                throw error;
+            }
         }
-        catch { /* 不存在才写（内容寻址天然去重） */ }
-        await atomicWriteFile(target, bytes);
-        return sha;
     }
     /** 对象仓里是否真有这个 blob（缓存命中时校验；任何异常一律按「没有」处理） */
     async objectExists(sha) {
@@ -792,13 +1246,28 @@ export class RollbackPointEngine {
     /**
      * 列出一个显式分块内的候选文件（不跟随符号链接 / junction；跳过与读不到都留痕）。
      * 返回 null = 该分块本身不可用（不存在 / 是链接 / 非常规文件），细节已写进 sink。
+     *
+     * `truncated` 与 `walkAborted` 是**两件事**：前者只说「本次列表不完整」（文件数上限 / 提交上限），
+     * 后者说「走查被预算或取消打断，栈里还有没进去的子树」—— 只有后者才意味着那些路径
+     * **一条都没进任何名单**，调用方必须据此让删除集 fail-closed。
      */
     async listChunkFiles(chunk, sink, limit, 
     /**
      * 捕获期专用：把**走查过**的每条文件路径都记进来（含超出 limit、因而没进 `out` 的那些）——
      * 路径索引（{@link RollbackPathIndex}）的来源。回退期的走查不传它（那份名单只由记录决定）。
      */
-    collect, ignore) {
+    collect, ignore, 
+    /**
+     * 停止判据（捕获期传时间/取消预算；回退期的走查不传）—— 返回 true 立即停止遍历，
+     * 已走查的部分照常返回并置 truncated + walkAborted（栈里剩余的子树从未进门 ⇒ 由调用方据此 fail-closed；
+     * 回退期不传它，故 walkAborted 恒 false）。
+     */
+    shouldStop) {
+        // 分块根本身就是 `.asar` 段 ⇒ 一次 fs 调用都不发（见 hasAsarSegment）
+        if (hasAsarSegment(chunk)) {
+            this.recordSkip(sink, 'skipped', { path: chunk, reason: 'asar-container' });
+            return null;
+        }
         let stat;
         try {
             stat = await fs.lstat(chunk);
@@ -812,15 +1281,25 @@ export class RollbackPointEngine {
             return null;
         }
         if (stat.isFile())
-            return { files: [chunk], truncated: false };
+            return { files: [chunk], truncated: false, walkAborted: false, unwalkedDirs: [] };
         if (!stat.isDirectory()) {
             this.recordSkip(sink, 'skipped', { path: chunk, reason: 'not-a-file' });
             return null;
         }
         const out = [];
         let truncated = false;
+        // 走查**被预算 / 取消打断**：栈里还压着没进去的子树 —— 那些路径一条都没进任何名单
+        let walkAborted = false;
+        // 中断时把**还没进去的子树**如实带出去 ⇒ 调用方可以只对这几棵子树 fail-closed（精确范围）
+        let unwalkedDirs = [];
         const stack = [{ dir: chunk, depth: 0 }];
         while (stack.length > 0) {
+            if (shouldStop?.() === true) {
+                truncated = true;
+                walkAborted = true;
+                unwalkedDirs = stack.length > ROLLBACK_UNWALKED_DIRS_LIMIT ? [] : stack.map((item) => item.dir);
+                break;
+            }
             const item = stack.pop();
             if (item === undefined)
                 break;
@@ -838,14 +1317,27 @@ export class RollbackPointEngine {
             }
             for (const entry of entries) {
                 const full = path.join(item.dir, entry.name);
+                // **绝不把含 `.asar` 段的路径交给 fs**（见 hasAsarSegment：宿主里这一步是原生解析，
+                // 畸形夹具会让整个宿主进程消失）。留痕进 skipped —— 它是**证明名单**的一员，
+                // 因此该路径绝不会被当成「留点后新建」删掉。
+                if (hasAsarSegment(full)) {
+                    this.recordSkip(sink, 'skipped', { path: full, reason: 'asar-container' });
+                    continue;
+                }
                 if (entry.isSymbolicLink()) {
                     this.recordSkip(sink, 'skipped', { path: full, reason: 'link' });
                     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)) {
@@ -879,12 +1371,19 @@ export class RollbackPointEngine {
             }
         }
         out.sort();
-        return { files: out, truncated };
+        return { files: out, truncated, walkAborted, unwalkedDirs };
     }
-    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;
+        // 对象名单快照按回合重建（一次 readdir 换掉每个候选一次 fs.access）
+        this.captureObjectNames = null;
         const payload = {
             chunks: [...chunks],
             files: [],
@@ -904,104 +1403,65 @@ export class RollbackPointEngine {
         let sawChunk = false;
         // 走查过的**全部**文件路径（含被预算 / 单文件上限挡下的）—— 路径索引的来源（方向 B）
         const walked = [];
+        // 走查中断时**没进去的子树**（精确到目录）—— 供删除集做分子树 fail-closed
+        const unwalked = [];
         for (const chunk of chunks) {
+            if (outOfBudget()) {
+                // 分块之间就超预算：不再开新分块，并如实留痕（该分块的条目一条都没被走查）
+                // walkIncomplete 是**安全判据**（删除集 fail-closed）；这里能精确给出「没进去的是哪个分块」
+                // ⇒ 删除只拒这棵子树，不再把整个工作区的新建文件一起放弃。
+                payload.walkIncomplete = true;
+                payload.truncated = true;
+                unwalked.push(chunk);
+                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));
+            // 候选名单上限取 ROLLBACK_CAPTURE_LIST_LIMIT（而不是 maxFiles）：入点上限由阶段①的 slots
+            // 把关，这里若提前截断，缺口优先排序就够不到尾部文件 ⇒ 覆盖率不收敛
+            const listed = await this.listChunkFiles(resolved, payload, ROLLBACK_CAPTURE_LIST_LIMIT, walked, await loadIgnoreRules(resolved), outOfBudget);
             if (listed === null)
                 continue;
             sawChunk = true;
             if (listed.truncated)
                 payload.truncated = true;
-            for (const file of listed.files) {
-                if (read >= this.maxFiles) {
-                    // 文件数预算耗尽：其后每一条都如实留痕（不再 break 静默丢弃）
-                    payload.truncated = true;
-                    this.recordSkip(payload, 'skipped', { path: file, reason: 'budget-files' });
-                    continue;
-                }
-                if (isInsidePath(file, this.root)) {
-                    this.recordSkip(payload, 'skipped', { path: file, reason: 'self-store' });
-                    continue;
-                }
-                // **先 stat 判大小、再决定读不读**：单文件超限或加上它会超总量 → 跳过并如实留痕
-                // （旧实现的 `read > 0` 短路让**首个**文件完全不设上限，会被整份读进内存 —— t5-F1）
-                let stat;
-                try {
-                    stat = await fs.stat(file);
-                }
-                catch (error) {
-                    payload.unreadableFiles.push({ path: file, reason: errorDetail(error) });
-                    continue;
-                }
-                if (!stat.isFile()) {
-                    this.recordSkip(payload, 'skipped', { path: file, reason: 'not-a-file' });
-                    continue;
-                }
-                if (stat.size > this.maxFileBytes) {
-                    payload.truncated = true;
-                    this.recordSkip(payload, 'skipped', { path: file, reason: 'too-large' });
-                    continue;
-                }
-                if (payload.bytes + stat.size > this.maxBytes) {
-                    payload.truncated = true;
-                    this.recordSkip(payload, 'skipped', { path: file, reason: 'budget-bytes' });
-                    continue;
-                }
-                try {
-                    // 路径身份缓存：身份（dev:ino:size:mtimeNs:ctimeNs:mode）未变 ⇒ 复用已存 sha256，**不重读**
-                    const identity = await this.pathIdentityOf(file);
-                    const candidate = identity === null ? null : await this.lookupCachedFile(identity, file);
-                    // **F-2（t12 修复）**：缓存命中也要确认对象仓里真有那个 blob —— 对象被外部清掉后
-                    // 若直接复用 sha256，新点会「零对象却 canRestore=true」，预览骗人（执行才响亮失败）。
-                    // 对象不在 ⇒ 当作未命中：真读 + 重写对象（缓存因此自愈）。
-                    const cached = candidate === null || !(await this.objectExists(candidate.sha256)) ? null : candidate;
-                    const data = cached === null ? await this.readFileBytes(file) : null;
-                    const size = cached === null ? (data?.byteLength ?? 0) : cached.bytes;
-                    if (cached === null && data !== null && data.byteLength !== size) {
-                        payload.truncated = true;
-                        this.recordSkip(payload, 'skipped', { path: file, reason: 'budget-bytes' });
-                        continue;
-                    }
-                    if (cached !== null) {
-                        payload.files.push({ path: file, chunk: resolved, bytes: cached.bytes, sha256: cached.sha256, mtimeMs: stat.mtimeMs, object: cached.sha256 });
-                        payload.bytes += cached.bytes;
-                        read += 1;
-                        continue;
-                    }
-                    if (data === null) {
-                        payload.unreadableFiles.push({ path: file, reason: 'read-failed' });
-                        continue;
-                    }
-                    // stat 与 read 之间文件可能变化：真读到的字节数仍必须服从总量预算（不猜、不静默）
-                    if (payload.bytes + data.byteLength > this.maxBytes) {
-                        payload.truncated = true;
-                        this.recordSkip(payload, 'skipped', { path: file, reason: 'budget-bytes' });
-                        continue;
-                    }
-                    const sha = sha256Hex(data);
-                    await this.writeObjectWithHash(data, sha);
-                    if (identity !== null)
-                        this.rememberCachedFile(identity, file, sha, data.byteLength);
-                    payload.files.push({ path: file, chunk: resolved, bytes: data.byteLength, sha256: sha, mtimeMs: stat.mtimeMs, object: sha });
-                    payload.bytes += data.byteLength;
-                    read += 1;
-                }
-                catch (error) {
-                    payload.unreadableFiles.push({ path: file, reason: errorDetail(error) });
-                }
+            // 走查本身被打断 ⇒ 栈里还有没进去的子树（那些路径从未进任何名单）⇒ fail-closed。
+            // **区别于**下面「走查已结束、只是读到一半超时」：后者的路径全在 walked 里，
+            // 由文件末尾的覆盖自检补进证明名单（补不齐才拒删），不该整体拒删。
+            if (listed.walkAborted) {
+                payload.walkIncomplete = true;
+                for (const dir of listed.unwalkedDirs)
+                    unwalked.push(dir);
             }
+            read += await this.captureChunkCandidates(resolved, listed.files, Math.max(0, this.maxFiles - read), payload, outOfBudget);
         }
-        if (!sawChunk && payload.files.length === 0) {
+        // 精确的「没进去的子树」：有 ⇒ 删除集只在这些子树里 fail-closed；没有（老台账 / 栈被截断）
+        // ⇒ 退回全局拒删（见 planCreatedRemovals）
+        if (unwalked.length > 0)
+            payload.unwalkedDirs = [...new Set(unwalked)].sort();
+        // `truncated` 为真时**不能**判 chunk-not-found：那是「分块确实存在、只是没来得及走查完」
+        // （时间预算 / 取消信号）—— 报成「找不到分块」会让用户以为工作区配错了。
+        if (!sawChunk && payload.files.length === 0 && !payload.truncated) {
             return this.emptyTrack('workspace', capturedAt, 'chunk-not-found', chunks.join(' '));
         }
-        // **方向 B**：逐条跳过名单被记录上限截断（skippedTruncated）时，把走查过的全部路径另存成
-        // 路径索引对象 —— 「未记录」与「留点时就存在」只有在名单完整时才可区分。
-        // 只有这一种情形需要它：未截断时 files ∪ skipped 本身就是完整名单（零额外成本）。
-        // 写失败绝不改判留点成败：skippedTruncated 仍为 true ⇒ 回退侧 fail-closed 一条都不删（R-05f）。
-        if (payload.skippedTruncated) {
+        // **方向 B**：把走查过的全部路径另存成路径索引对象 —— 「未记录」与「留点时就存在」只有在
+        // 证明名单完整时才可区分。触发条件是**覆盖自检**（不是「跳过名单被截断」这一种特例）：
+        //  · 逐条跳过名单被记录上限截断（skippedTruncated）；或
+        //  · 读到一半被时间预算 / 取消打断 —— 本分块剩余文件进了 walked、却一条都没进任何名单。
+        // 覆盖完整时不必写（未截断时 files ∪ skipped 本身就是完整名单，零额外成本）。
+        // 写失败 ⇒ 证明名单补不齐 ⇒ 必须整体拒删（安全方向；R-05f）。
+        const proven = new Set();
+        for (const file of payload.files)
+            proven.add(pathKey(file.path));
+        for (const entry of payload.skipped)
+            proven.add(pathKey(entry.path));
+        for (const entry of payload.unreadableFiles)
+            proven.add(pathKey(entry.path));
+        const uncovered = walked.some((item) => !proven.has(pathKey(item)));
+        if (uncovered) {
             try {
                 const paths = [...new Set(walked)].sort();
                 const gz = gzipSync(Buffer.from(paths.join('\n'), 'utf8'));
@@ -1011,6 +1471,8 @@ export class RollbackPointEngine {
             }
             catch (error) {
                 this.warn('rollback path index failed: ' + errorDetail(error));
+                // 走查过、却没进名单的路径无法被证明 ⇒ 删除集整体拒绝（绝不「删一半」）
+                payload.walkIncomplete = true;
             }
         }
         // 用户忽略的整目录 ⇒ 证明名单不完整（删除集整体拒绝；见 planCreatedRemovals）。
@@ -1019,6 +1481,8 @@ export class RollbackPointEngine {
         payload.ignoreIncomplete = payload.ignoredDirCount > 0;
         // 路径身份缓存落盘（best-effort：写不进去只意味着下次全量读，绝不影响留点成败）
         await this.persistPathCache();
+        // 落点列表排序：并发读让入点顺序不定，契约必须是「按路径有序」（预览 / 对账 / 指纹都靠它）
+        payload.files.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
         // 留痕列表也排序：跨分块 / 依赖 readdir 顺序时输出仍确定（测试与对账都能逐条比）
         payload.skipped.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
         payload.excludedDirs.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
@@ -1026,9 +1490,25 @@ export class RollbackPointEngine {
         const canonical = [...payload.files]
             .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
             .map((f) => [f.path, f.bytes, f.sha256]);
+        payload.fileCount = payload.files.length;
         const fingerprint = sha256Hex(JSON.stringify({ chunks: [...payload.chunks].sort(), files: canonical }));
+        // 自适应预算（见 ROLLBACK_MIN/MAX_CAPTURE_BUDGET_MS）：被截断 ⇒ 下次翻倍（上限）；
+        // 用得很少 ⇒ 下次减半（下限）。大仓库第一次撞上限后自动拿到更大预算，小仓库自动回落，
+        // 不会每回合白等。回退期的走查预算（rewindBudgetMs）**不参与**这套调整。
+        if (payload.truncated || payload.walkIncomplete === true) {
+            this.captureBudgetMs = Math.min(this.captureBudgetMaxMs, this.captureBudgetMs * 2);
+        }
+        else if (this.stamp() - capturedAt < this.captureBudgetMs / 4) {
+            this.captureBudgetMs = Math.max(this.captureBudgetMinMs, Math.floor(this.captureBudgetMs / 2));
+        }
+        // 「降级（留得不完整）」只由**真的缺内容**触发：
+        //  ① truncated —— 文件数 / 总字节 / 单文件上限 / 时间预算挡下的内容；
+        //  ② unreadableDirs / unreadableFiles —— 读不出来或捕获竞态（内容不可信）。
+        // **不再用 skippedCount**：那里的条目大多是**设计内**的跳过（符号链接不跟随、文件级忽略、
+        // 自身数据区、读之前就消失），既不缺内容也无法回退 —— 旧口径让「工作区里有任何一个符号链接」
+        // 的仓库每个点都挂「回退可能不完整」，真出问题时反而被噪声淹没（真机 2026-10-15：10 个 link
+        // 跳过 ⇒ 每个点 degraded=true）。条目与计数仍逐条留痕（skippedCount / skipped 列表不变）。
         const degraded = payload.truncated
-            || payload.skippedCount > 0
             || payload.unreadableDirs.length > 0
             || payload.unreadableFiles.length > 0;
         return {
@@ -1044,6 +1524,213 @@ export class RollbackPointEngine {
     }
     /* ---------------------------------------------------------- 忽略规则 / 路径身份缓存 */
     /** 用户忽略规则是否命中该路径（只认「相对分块根」的斜杠路径） */
+    /**
+     * 处理一个分块的候选文件（**两阶段**）。
+     *
+     *  ① **顺序判定**（与旧的串行实现逐条一致，保证预算 / 计数 / 字节上限完全确定）：
+     *     文件数上限、时间预算、自身数据区、stat、单文件上限、总量上限、身份缓存 + 对象存在性
+     *     → 得出「当场入点（缓存命中）」还是「要真读」，该跳过的**当场**按原有 reason 逐条留痕。
+     *     stat 按**有序批**并发取（判定仍严格按顺序），并用「一次 readdir 的对象名单快照」代替
+     *     每个文件一次 fs.access —— 这两处是稳态成本的大头（真机实测各占 ~5 s / ~3.7 s）。
+     *  ② **并发读 + 哈希 + 落对象仓**：这是捕获耗时的**唯一大头**（真机 148 s / 31,702 个对象，
+     *     96% 的时间），用 captureConcurrency 个 worker 并发跑；并用**在飞字节闸门**保证
+     *     「同时在飞的内容字节 ≤ captureInFlightBytes」。**不是** maxFileBytes —— 它缺省 =
+     *     总量预算（512 MiB），拿它当闸门等于允许把整个点的预算同时驻留（0.1.74 闪退根因）。
+     *
+     * 返回本分块**真正入点**的文件数（调用方据此推进 maxFiles 预算）。
+     * 没判到 / 没读完的条目一律逐条进 skipped(budget-time)，绝不静默丢弃。
+     */
+    async captureChunkCandidates(chunk, candidates, slots, payload, outOfBudget) {
+        // 缺口优先：身份缓存里还没有的路径排前面 ⇒ 每个点都在补上次没覆盖的部分（见 orderByCoverage）
+        const ordered = await this.orderByCoverage(candidates);
+        const decided = new Array(ordered.length).fill(false);
+        const plans = [];
+        let captured = 0;
+        let newReads = 0;
+        // 字节预算必须在**准入那一刻**按 stat.size 预留：真正入点发生在并发的第二阶段，
+        // 若拿 payload.bytes 当判据，同一个分块里后面的文件会全部误判成「还有额度」
+        let accounted = payload.bytes;
+        // 对象名单快照：一次 readdir 顶掉「每个候选一次 fs.access」（读不到则回落逐条判断）
+        const names = await this.objectNamesSnapshot();
+        let cursor = 0;
+        while (cursor < ordered.length) {
+            if (outOfBudget())
+                break; // 剩余条目由收尾循环逐条记 budget-time（不预取 stat）
+            const window = ordered.slice(cursor, cursor + ROLLBACK_CAPTURE_STAT_BATCH);
+            const stats = await Promise.all(window.map((file) => this.fileStatOf(file)));
+            let broke = false;
+            for (let offset = 0; offset < window.length; offset += 1) {
+                const file = window[offset] ?? '';
+                const info = stats[offset] ?? { isFile: false, size: 0, mtimeMs: 0, identity: null, error: 'stat-missing' };
+                const index = cursor + offset;
+                if (outOfBudget()) {
+                    broke = true;
+                    break;
+                }
+                decided[index] = true;
+                if (isInsidePath(file, this.root)) {
+                    this.recordSkip(payload, 'skipped', { path: file, reason: 'self-store' });
+                    continue;
+                }
+                // **先 stat 判大小、再决定读不读**：单文件超限或加上它会超总量 → 跳过并如实留痕
+                // （旧实现的 read > 0 短路让**首个**文件完全不设上限，会被整份读进内存 —— t5-F1）
+                if (info.error !== undefined) {
+                    payload.unreadableFiles.push({ path: file, reason: info.error });
+                    continue;
+                }
+                if (!info.isFile) {
+                    this.recordSkip(payload, 'skipped', { path: file, reason: 'not-a-file' });
+                    continue;
+                }
+                if (info.size > this.maxFileBytes) {
+                    payload.truncated = true;
+                    this.recordSkip(payload, 'skipped', { path: file, reason: 'too-large' });
+                    continue;
+                }
+                // 路径身份缓存：身份（dev:ino:size:mtimeNs:ctimeNs:mode）未变 ⇒ 复用已存 sha256，**不重读**
+                const candidate = info.identity === null ? null : await this.lookupCachedFile(info.identity, file);
+                // **F-2（t12 修复）**：缓存命中也要确认对象仓里真有那个 blob —— 对象被外部清掉后
+                // 若直接复用 sha256，新点会「零对象却 canRestore=true」，预览骗人（执行才响亮失败）。
+                // 对象不在 ⇒ 当作未命中：真读 + 重写对象（缓存因此自愈）。
+                const objectPresent = candidate === null
+                    ? false
+                    : names !== null ? names.has(candidate.sha256) : await this.objectExists(candidate.sha256);
+                if (candidate !== null && objectPresent) {
+                    // 身份未变 ⇒ 内容必然与缓存一致：零 I/O 直接入点（稳态成本与仓库大小无关的来源）。
+                    // **不占读预算**：maxFiles / maxBytes 约束的是「这回合新读进来的内容」，不是「记录多少条」
+                    // —— 否则大仓库每个点都只能记下前 N 条，滚回某点时会漏掉其余文件（覆盖率永远不收敛）。
+                    payload.files.push({
+                        path: file, chunk, bytes: candidate.bytes, sha256: candidate.sha256, mtimeMs: info.mtimeMs, object: candidate.sha256,
+                    });
+                    payload.bytes += candidate.bytes;
+                    captured += 1;
+                    continue;
+                }
+                // 只有**要真读的新内容**才受每回合的规模预算约束（判定仍严格按顺序 ⇒ 结果确定）
+                if (newReads >= slots) {
+                    payload.truncated = true;
+                    this.recordSkip(payload, 'skipped', { path: file, reason: 'budget-files' });
+                    continue;
+                }
+                if (accounted + info.size > this.maxBytes) {
+                    payload.truncated = true;
+                    this.recordSkip(payload, 'skipped', { path: file, reason: 'budget-bytes' });
+                    continue;
+                }
+                accounted += info.size;
+                newReads += 1;
+                plans.push({ path: file, size: info.size, mtimeMs: info.mtimeMs, identity: info.identity });
+            }
+            cursor += window.length;
+            if (broke)
+                break;
+        }
+        if (plans.length > 0) {
+            // ② 并发读 + 落对象仓。outOfBudget 一命中就**不再开新条目**（在飞的照常收尾），
+            //    未开工的条目在循环外逐条记 budget-time —— 与串行版「中断处逐条留痕」同一诚实口径。
+            const gate = new ByteGate(this.captureInFlightBytes);
+            const done = new Array(plans.length).fill(false);
+            let planCursor = 0;
+            let stopped = false;
+            const workers = Array.from({ length: Math.min(this.captureConcurrency, plans.length) }, async () => {
+                for (;;) {
+                    if (stopped)
+                        return;
+                    const index = planCursor;
+                    planCursor += 1;
+                    if (index >= plans.length)
+                        return;
+                    const item = plans[index];
+                    if (outOfBudget()) {
+                        stopped = true;
+                        return;
+                    }
+                    await gate.acquire(item.size);
+                    try {
+                        if (outOfBudget()) {
+                            stopped = true;
+                            return;
+                        }
+                        const data = await this.readFileBytes(item.path);
+                        if (data.byteLength !== item.size) {
+                            // stat 与 read 之间文件变了（旧口径：budget-bytes）—— 绝不按旧字节数记账
+                            payload.truncated = true;
+                            this.recordSkip(payload, 'skipped', { path: item.path, reason: 'budget-bytes' });
+                            done[index] = true;
+                            continue;
+                        }
+                        // **捕获竞态**：读之前拿到的身份若在读完时已变，说明这次读到的内容未必是「留点时刻」
+                        // 的内容（回合与留点并发）⇒ 不当作前像，只如实进 unreadableFiles（它本身是**证明名单**
+                        // 的一员：证明「留点时存在」，因此绝不会被当成新建删掉）。
+                        const after = item.identity === null ? null : await this.pathIdentityOf(item.path);
+                        if (item.identity !== null && after !== item.identity) {
+                            payload.unreadableFiles.push({ path: item.path, reason: 'changed-during-read' });
+                            done[index] = true;
+                            continue;
+                        }
+                        const sha = sha256Hex(data);
+                        await this.writeObjectWithHash(data, sha);
+                        if (item.identity !== null)
+                            this.rememberCachedFile(item.identity, item.path, sha, data.byteLength);
+                        payload.files.push({
+                            path: item.path, chunk, bytes: data.byteLength, sha256: sha, mtimeMs: item.mtimeMs, object: sha,
+                        });
+                        payload.bytes += data.byteLength;
+                        captured += 1;
+                        done[index] = true;
+                    }
+                    catch (error) {
+                        payload.unreadableFiles.push({ path: item.path, reason: errorDetail(error) });
+                        done[index] = true;
+                    }
+                    finally {
+                        gate.release(item.size);
+                    }
+                }
+            });
+            await Promise.all(workers);
+            for (let index = 0; index < plans.length; index += 1) {
+                if (done[index] === true)
+                    continue;
+                payload.truncated = true;
+                this.recordSkip(payload, 'skipped', { path: plans[index].path, reason: 'budget-time' });
+            }
+        }
+        // 阶段 ① 里没判定到的（时间预算打断）同样逐条留痕 —— 覆盖自检因此仍认为名单完整
+        for (let index = 0; index < ordered.length; index += 1) {
+            if (decided[index] === true)
+                continue;
+            payload.truncated = true;
+            this.recordSkip(payload, 'skipped', { path: ordered[index] ?? '', reason: 'budget-time' });
+        }
+        // 返回值 = 本分块消耗掉的**读槽位**（缓存命中不占槽位；调用方据此推进 maxFiles）
+        return newReads;
+    }
+    /**
+     * 缺口优先排序：身份缓存里**没有**的路径排前面。
+     *
+     * 为什么：预算固定时按目录顺序走查，同一个「已覆盖且便宜」的前缀每回合都会吃掉全部预算，
+     * 尾部永远进不来（真机：34k 文件每次只覆盖 1/5，且五次都是同一批 outputs/ 前缀）。
+     * 未覆盖的排前面 ⇒ 每个点都在补上一次的缺口，覆盖率随回合**单调收敛**到 100%。
+     * 组内保持走查顺序（稳定），因此同一输入下的结果仍然确定。
+     */
+    async orderByCoverage(candidates) {
+        if (candidates.length <= 1)
+            return [...candidates];
+        const cache = await this.loadPathCache();
+        if (cache.size === 0)
+            return [...candidates];
+        const covered = new Set();
+        for (const entry of cache.values())
+            covered.add(pathKey(entry.path));
+        if (covered.size === 0)
+            return [...candidates];
+        const cold = [];
+        const hot = [];
+        for (const file of candidates)
+            (covered.has(pathKey(file)) ? hot : cold).push(file);
+        return cold.length === 0 ? hot : [...cold, ...hot];
+    }
     ignoredByRules(rules, target, isDir) {
         const rel = ignoreRelativePath(rules.root, target);
         return rel === null ? false : ignoreRuleMatches(rules, rel, isDir);
@@ -1060,19 +1747,43 @@ export class RollbackPointEngine {
      * 用毫秒换算同样不行：会把「同一毫秒内的两次写」当成同一个身份。
      * 读不到身份（文件消失 / 权限 / 平台不支持 bigint stat）→ null ⇒ 回落全量真读。
      */
+    /**
+     * 一次 bigint stat 拿到阶段①需要的**全部**东西（是否文件 / 大小 / mtime / 身份）。
+     * 旧实现「fs.stat + pathIdentityOf」每文件 stat 两次，真机 34k 文件白花约 5 s。
+     */
+    async fileStatOf(target) {
+        try {
+            const stat = await fs.stat(target, { bigint: true });
+            const isFile = stat.isFile();
+            return {
+                isFile,
+                size: Number(stat.size),
+                mtimeMs: Number(stat.mtimeMs),
+                identity: isFile ? fileIdentityOf(stat) : null,
+            };
+        }
+        catch (error) {
+            return { isFile: false, size: 0, mtimeMs: 0, identity: null, error: errorDetail(error) };
+        }
+    }
+    /** 对象名单快照（每个捕获回合一次 readdir）；读不到则返回 null ⇒ 调用方回落逐条判断 */
+    async objectNamesSnapshot() {
+        if (this.captureObjectNames !== null)
+            return this.captureObjectNames;
+        try {
+            this.captureObjectNames = new Set(await fs.readdir(this.objectsDir));
+        }
+        catch {
+            this.captureObjectNames = null;
+        }
+        return this.captureObjectNames;
+    }
     async pathIdentityOf(target) {
         try {
             const stat = await fs.stat(target, { bigint: true });
             if (!stat.isFile())
                 return null;
-            return [
-                String(stat.dev),
-                String(stat.ino),
-                String(stat.size),
-                String(stat.mtimeNs),
-                String(stat.ctimeNs),
-                String(stat.mode & 511n),
-            ].join(':');
+            return fileIdentityOf(stat);
         }
         catch {
             return null;
@@ -1117,6 +1828,25 @@ export class RollbackPointEngine {
         return map;
     }
     /** 缓存命中：身份键存在、且路径逐字相同（身份被复用也绝不认）。 */
+    /**
+     * 「这条记录的当前内容**仍然是它**吗」的身份快路径 —— **预览与执行共用同一条判据**
+     * （否则「预览说会改的 = 实际会改的」这条不变式会被打破）。
+     *
+     * 判据：路径身份（dev:ino:size:mtimeNs:ctimeNs:mode）命中**身份缓存**，且缓存里的 sha/bytes 与记录一致。
+     * 身份未变 ⇒ 内容未变：缓存里的 sha 就是**这份内容**在留点那一次真读出来的哈希（身份含 size/mtimeNs/
+     * ctimeNs/ino/dev/mode，改内容必动 mtime/ctime，Windows 上 user 代码改不了 ctime）。
+     * 任何一环拿不到（读不到身份 / 缓存没有该身份 / sha 或 bytes 不同）⇒ false，调用方回落「真读 + 哈希」。
+     *
+     * 为什么必须有它：大仓库一次预览/回退要判 3 万+ 条目，逐个真读等于把整个工作区读两遍
+     * （真机 34k 文件 / 609 MiB：预览 14.2 s 里 13 s 全在这，回退 60 s+ 同理）。**记录的指纹被篡改**
+     * 时本判据必然不成立（缓存的 sha 是真算出来的）⇒ 仍走真读 + 哈希的旧路径，护栏不退化。
+     */
+    async unchangedByIdentity(file, identity) {
+        if (identity === null)
+            return false;
+        const cached = await this.lookupCachedFile(identity, file.path);
+        return cached !== null && cached.sha256 === file.sha256 && cached.bytes === file.bytes;
+    }
     async lookupCachedFile(identity, target) {
         const cache = await this.loadPathCache();
         const hit = cache.get(identity);
@@ -1168,6 +1898,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 +1913,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 +1945,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 +1973,273 @@ 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;
+    /**
+     * 字节预算淘汰（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);
         }
-        for (const name of names) {
-            if (!OBJECT_KEY_RE.test(name) || referenced.has(name))
+        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 });
+            freed += entry.recordBytes;
+            const hash = entry.workspace.payload;
+            if (hash !== null && !keptPayloads.has(hash) && !freedPayloads.has(hash)) {
+                freedPayloads.add(hash);
+                freed += entry.workspace.payloadBytes;
             }
-            catch (error) {
-                this.warn('rollback gc failed: ' + name + ' ' + errorDetail(error));
+        }
+        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**，
+     * 绝不拿自己的快照覆盖别人的清单（宁可少一条点，也不丢别人的点）。
+     * 诚实的边界：检测与写入之间仍有极小窗口，无跨进程锁时无法彻底消除 —— 这里保证的是
+     * 「不静默覆盖 + 尽量合并」，不是原子性。
+     */
+    /**
+     * 把工作区载荷改写成**增量视图**（相对最近一个同分块的点）——清单增量化，省的是磁盘，不是语义。
+     *
+     * 判据与安全边界（逐条）：
+     *  · 基准 = 清单里最近一个 `workspace.payload` 非空、**分块完全相同**的点（只试最近几个，代价有界）；
+     *  · 增量 = 「相对基准新增 / 改写的条目」+「基准里不再存在的路径」，条目**逐字比较**（同形绝对路径）；
+     *  · 只有增量明显更小（< 全量的 60%）才用；否则原样全量落盘；
+     *  · 读路径由 ledger 物化（`resolvePayload`）⇒ 预览 / 回退 / 回收看到的永远是完整清单；
+     *  · 基准读不出来 / 分块对不上 / 任何异常 ⇒ 原样全量（绝不因为省字节而让点不可用）；
+     *  · 基准载荷的保活由 ledger 的 `payloadChain` 负责（淘汰时不会把基准删掉）。
+     */
+    async storagePlanFor(record, entries) {
+        const full = { record, reuse: null };
+        const payload = record.workspace.payload;
+        if (payload === null || record.workspace.ok !== true || payload.files.length === 0)
+            return full;
+        if (payload.delta !== undefined)
+            return full;
+        // 基准 = **本进程上一次成功留点**的内存摘要（绝不读别人的载荷/记录文件：L-08 / issue #89）。
+        // 没有摘要（进程刚起 / 分块变了）⇒ 这一次落**全量锚点**，随后由摘要继续链下去。
+        const base = this.deltaBase;
+        if (base !== null && sameChunks(base.chunks, payload.chunks)) {
+            const diff = payloadDiffAgainstDigest(payload, base.entries);
+            if (diff.added.length === 0 && diff.removed.length === 0) {
+                // 工作区与该点**逐条相同** ⇒ 直接复用它的载荷文件（零额外字节、链不增长）
+                const entry = entries.find((candidate) => candidate.workspace.payload === base.hash);
+                if (entry !== undefined && (await this.ledger.hasPayload(base.hash))) {
+                    return { record, reuse: { hash: base.hash, bytes: entry.workspace.payloadBytes, chain: [...base.chain] } };
+                }
+            }
+            else if (base.chain.length < ROLLBACK_DELTA_CHAIN_LIMIT) {
+                const delta = buildPayloadDelta(payload, base.hash, base.chain, diff);
+                if (delta !== null) {
+                    return {
+                        record: { ...record, workspace: { ...record.workspace, payload: compactPayloadForStorage(delta) } },
+                        reuse: null,
+                    };
+                }
+            }
+        }
+        // 没有可用基准 / 分块不同 / 增量不划算 ⇒ 全量落盘（仍省掉冗余的 object 字段）
+        return {
+            record: { ...record, workspace: { ...record.workspace, payload: compactPayloadForStorage(payload) } },
+            reuse: null,
+        };
+    }
+    /** 记下这份点作为下一次留点的增量基准（内存摘要，见 {@link deltaBase}） */
+    rememberDeltaBase(record, prepared) {
+        const payload = record.workspace.payload;
+        const hash = prepared.payloadHash;
+        if (payload === null || hash === null) {
+            this.deltaBase = null;
+            return;
+        }
+        const entries = new Map();
+        for (const file of payload.files)
+            entries.set(file.path, digestKeyOf(file));
+        this.deltaBase = {
+            hash,
+            chain: prepared.entry.workspace.payloadChain ?? [hash],
+            chunks: [...payload.chunks],
+            entries,
+        };
+    }
     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 };
+                }
+            }
+            // 清单增量化：能省就把这份载荷改写成「相对最近一个同分块载荷的增量」（读路径由 ledger 物化回来）。
+            // 失败 / 不划算 / 没有可用基准一律**原样返回** —— 增量只影响磁盘占用，绝不参与正确性判断。
+            const storage = await this.storagePlanFor(record, manifest.entries);
+            const prepared = this.ledger.prepareRecord(storage.record, storage.reuse ?? undefined);
+            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) };
+            }
+            // 记下「这次留点」作为下一次的增量基准（只在真正写成功后；失败不更新 ⇒ 链只跨成功落盘的点）
+            this.rememberDeltaBase(record, prepared);
+            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 +2264,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 +2325,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 +2347,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 +2376,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 +2447,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 +2463,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 +2500,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,19 +2525,50 @@ 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;
     }
     /* -------------------------------------------------------------- 预览 */
+    /**
+     * 预览的**单条只读判定**（阶段 A，可并发跑）：一次 bigint lstat + 身份快路径。
+     * `unchanged = true` 表示「已证明与记录一致」（身份命中身份缓存且 sha/bytes 相同）⇒ 调用方直接跳过。
+     */
+    async previewScan(file) {
+        try {
+            // **lstat，不是 stat**：写入侧用 `symlink:'reject'`（lstat 是链接即抛），预览若跟随链接就会
+            // 说「会创建 / 会覆盖」，执行却整段失败 —— 两侧必须是同一个口径。链接一律按「不可写」报。
+            const stat = await fs.lstat(file.path, { bigint: true });
+            if (stat.isSymbolicLink())
+                return { kind: 'unavailable' };
+            const size = Number(stat.size);
+            const regular = stat.isFile();
+            const unchanged = regular && size === file.bytes
+                && (await this.unchangedByIdentity(file, regular ? fileIdentityOf(stat) : null));
+            return { kind: 'ok', size, regular, unchanged };
+        }
+        catch (error) {
+            return classifyPreviewStatFailure(error) === 'missing' ? { kind: 'missing' } : { kind: 'unavailable' };
+        }
+    }
     trackWarnings(record) {
         const out = [];
         for (const track of [record.workspace, record.session]) {
@@ -1650,55 +2617,91 @@ export class RollbackPointEngine {
         for (const entry of payload.ignoredDirs ?? [])
             proof.add(pathKey(entry.path));
         let refused = null;
-        if (payload.skippedTruncated) {
-            // 逐条跳过名单被记录上限截断 ⇒ 必须有路径索引，否则「未记录」≠「留点之后新建」
-            const index = payload.pathIndex ?? null;
-            if (index === null)
+        // 路径索引**存在即并入**证明名单：写入条件已从「跳过名单被截断」推广为「覆盖自检不完整」
+        // （读到一半被预算打断也会写索引）—— 这里只看 skippedTruncated 会漏读索引 ⇒ 把老文件当新建删掉。
+        const index = payload.pathIndex ?? null;
+        if (index !== null) {
+            try {
+                for (const item of await this.readPathIndex(index))
+                    proof.add(pathKey(item));
+            }
+            catch (error) {
+                this.warn('rollback path index unreadable: ' + errorDetail(error));
                 refused = 'capture-incomplete';
-            else {
-                try {
-                    for (const item of await this.readPathIndex(index))
-                        proof.add(pathKey(item));
-                }
-                catch (error) {
-                    this.warn('rollback path index unreadable: ' + errorDetail(error));
-                    refused = 'capture-incomplete';
-                }
             }
         }
-        // 读不出的目录：目录内容在留点时刻**未知**（路径索引只含走查过的路径）⇒ 同样证明不了
-        if (refused === null && payload.unreadableDirs.length > 0)
+        else if (payload.skippedTruncated) {
+            // 逐条跳过名单被记录上限截断、又没有索引 ⇒ 「未记录」≠「留点之后新建」，证明不了
             refused = 'capture-incomplete';
-        // 用户忽略的整目录 ⇒ 其下内容在留点时刻未知 ⇒ 证明名单不完整（fail-closed）
-        if (refused === null && payload.ignoreIncomplete === true)
+        }
+        // —— 分子树拒删范围 ——
+        // 忽略目录 / 读不出的目录 / 走查没进去的子树：这三类的共同点是「其下内容在留点时刻未知」，
+        // 但它们**各自只影响自己那棵子树**。旧口径一律全局拒删，代价是「忽略一个 outputs/ 就让整个
+        // 工作区的新建文件一条都不删」；现在只拒这几棵子树，范围之外由证明名单照常判。
+        // 走查中断且拿不到精确子树列表（老台账 / 栈被截断）时才退回全局。
+        // 范围**说得清**才敢分子树拒删：忽略目录的逐条列表可能被记录上限截断（ignoredDirCount 是恒增
+        // 计数），走查中断也可能拿不到子树列表（老台账 / 栈太深）。任一「说不清」⇒ 退回全局拒删。
+        const ignoredKnown = (payload.ignoredDirs ?? []).length >= (payload.ignoredDirCount ?? 0);
+        const unwalkedKnown = (payload.unwalkedDirs ?? []).length > 0 || payload.walkIncomplete !== true;
+        const scopesKnown = ignoredKnown && unwalkedKnown;
+        const refusalScopes = scopesKnown
+            ? [
+                ...(payload.ignoredDirs ?? []).map((entry) => entry.path),
+                ...payload.unreadableDirs,
+                ...(payload.unwalkedDirs ?? []),
+            ]
+            : [];
+        if (refused === null && !scopesKnown) {
+            // 证明名单不完整、且**说不出**不完整的确切范围 ⇒ 整个工作区一条都不删（安全方向）
             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.rewindBudgetMs;
+        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);
             }
         }
-        const refusalWarnings = this.createdRefusalWarnings(payload);
+        // 警告只在**全局拒绝**时给：分子树拒绝由 createdSkipped 逐条说明（那句「本次不删除任何
+        // 『留点后新建』的路径」在分子树拒绝下是假话 —— 文案诚实要求按真实范围分派）。
+        const refusalWarnings = refused === null ? [] : this.createdRefusalWarnings(payload);
         const all = [];
         const paths = [];
         const skipped = [];
         for (const file of candidates) {
             all.push(file);
             // 拒删的也留在「未记录」清单里（如实报告），但绝不进删除集合
+            // 分子树拒删（忽略目录 / 读不出的目录 / 没走查到的子树）：只拒这几棵子树里的候选
+            if (refusalScopes.length > 0 && refusalScopes.some((dir) => isInsidePath(file, dir))) {
+                skipped.push(file);
+                continue;
+            }
             if (this.createdRemovalRefusal(file, chunks) !== null) {
                 skipped.push(file);
                 continue;
@@ -1793,7 +2796,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 +2820,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);
         // 工作区态
@@ -1838,15 +2850,27 @@ export class RollbackPointEngine {
             const changedFiles = [];
             // 单张预览共享的比对预算（字节 + 步数）；只有真的会被改动的条目才消耗它
             const diffBudget = { bytes: 0, work: 0 };
-            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() };
-                }
-                catch (error) {
-                    outcome = classifyPreviewStatFailure(error) === 'missing' ? { kind: 'missing' } : { kind: 'unavailable' };
+            // T10：stat 的三种结局分开表达 —— 「不存在（ENOENT）」与「存在性未知（其它 errno）」绝不混为一谈
+            const previewFiles = wsPayload.files;
+            // 阶段 A（**并发**）：逐条一次 bigint lstat + 身份快路径。大仓库这里是预览的大头：
+            // 真机 34k 条实测 —— 串行 lstat ≈ 6 s、串行真读 ≈ 13 s；并发后降到亚秒级 + 只读真正变了的那几条。
+            const scans = new Array(previewFiles.length);
+            let scanCursor = 0;
+            const scanWorkers = Array.from({ length: Math.min(this.captureConcurrency, Math.max(1, previewFiles.length)) }, async () => {
+                for (;;) {
+                    const index = scanCursor;
+                    scanCursor += 1;
+                    if (index >= previewFiles.length)
+                        return;
+                    scans[index] = await this.previewScan(previewFiles[index]);
                 }
+            });
+            await Promise.all(scanWorkers);
+            // 阶段 B（**顺序**）：只对「变了 / 没了 / 不可写」的条目按记录顺序装配 —— 列表顺序与行级 diff 的
+            // 共享预算因此仍**完全确定**（与并发前逐条一致，测试可逐字对账）。
+            for (let index = 0; index < previewFiles.length; index += 1) {
+                const file = previewFiles[index];
+                const outcome = scans[index] ?? { kind: 'unavailable' };
                 if (outcome.kind === 'missing') {
                     // **只有 ENOENT** 才算「当前确实不存在」⇒ 回退会重新创建它
                     missing += 1;
@@ -1864,6 +2888,9 @@ export class RollbackPointEngine {
                     changedFiles.push({ path: file.path, status: 'overwrite', ...previewCountsUnavailable() });
                     continue;
                 }
+                // 身份快路径已证明「与记录一致」⇒ 一个字段都不改（内容一致的文件不列进列表）
+                if (outcome.unchanged)
+                    continue;
                 const { size, regular } = outcome;
                 const sizeMatches = regular && size === file.bytes;
                 const withinCaps = file.bytes <= this.previewDiffMaxFileBytes && size <= this.previewDiffMaxFileBytes;
@@ -1872,7 +2899,7 @@ export class RollbackPointEngine {
                 // ② 大小不一致时也得读一次才能给行级统计（超限的大文件不白读）。
                 if (regular && (sizeMatches || withinCaps)) {
                     try {
-                        current = await fs.readFile(file.path);
+                        current = await this.readFileBytes(file.path);
                     }
                     catch {
                         current = null;
@@ -1988,10 +3015,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;
@@ -2067,7 +3100,7 @@ export class RollbackPointEngine {
             return { ...view, reason: 'too-large' };
         if (before.binary || after.binary)
             return { ...view, reason: 'binary' };
-        const result = diffLines(current === null ? '' : DIFF_TEXT_DECODER.decode(current), DIFF_TEXT_DECODER.decode(snapshot), { context: ROLLBACK_FILE_DIFF_LIMITS.context });
+        const result = diffLines(current === null ? '' : DIFF_TEXT_DECODER.decode(current), DIFF_TEXT_DECODER.decode(snapshot), { context: ROLLBACK_FILE_DIFF_LIMITS.context, maxD: ROLLBACK_FILE_DIFF_LIMITS.maxD });
         return {
             ...view,
             hunks: result.hunks, added: result.added, removed: result.removed,
@@ -2104,13 +3137,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 +3294,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'))
@@ -2273,6 +3316,8 @@ export class RollbackPointEngine {
         const detail = [];
         const writable = [];
         let failed = 0;
+        // 「已与记录一致」的条目数（身份快路径证明）—— 后面「0 变更」的文案与统计要用
+        let unchanged = 0;
         for (const file of payload.files) {
             // 门：记录里的路径必须落在记录里的分块内（记录不可成为写原语）
             const inChunk = payload.chunks.some((chunk) => path.isAbsolute(chunk) && isInsidePath(file.path, chunk));
@@ -2281,6 +3326,17 @@ export class RollbackPointEngine {
                 pushDetail(detail, 'invalid-path ' + file.path);
                 continue;
             }
+            // **身份快路径**：身份（dev:ino:size:mtimeNs:ctimeNs:mode）命中身份缓存、且缓存的 sha/bytes 与记录
+            // 一致 ⇒ 这个文件当前就是留点时刻的内容，**它根本不会被写** ⇒ 连对象都不必读。
+            // 大仓库实测：旧口径下阶段 1 会把 34k 个对象（609 MiB）全读一遍 + 哈希一遍（回退 60 s+ 全在这）。
+            // 语义变化（有意、且更准）：阶段 1 的对象校验只对**真要写**的条目做 —— 一个用不到的对象坏掉，
+            // 不该中止整次回退；真要用它时（该文件确实变了）照样会 `object-missing` / `object-hash-mismatch` 硬失败。
+            const info = await this.fileStatOf(file.path);
+            if (info.error === undefined && info.isFile && info.size === file.bytes
+                && (await this.unchangedByIdentity(file, info.identity))) {
+                unchanged += 1;
+                continue;
+            }
             try {
                 const bytes = await this.readObject(file.object);
                 if (sha256Hex(bytes) !== file.sha256) {
@@ -2332,7 +3388,6 @@ export class RollbackPointEngine {
         // E1：内容已与快照一致的条目**不再写** —— 「0 变更」就要是真的 0 次写入
         // （否则工作区已与该点一致时也会重写全部文件，白耗 I/O 并抖动 mtime）。
         const needed = [];
-        let unchanged = 0;
         for (const item of writable) {
             let identical = false;
             try {
@@ -2362,17 +3417,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);
+                bytes = await this.readFileBytes(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;
@@ -2392,7 +3486,7 @@ export class RollbackPointEngine {
         if (failed === 0) {
             for (const item of needed) {
                 try {
-                    const current = await fs.readFile(item.file.path);
+                    const current = await this.readFileBytes(item.file.path);
                     if (sha256Hex(current) !== item.file.sha256)
                         mismatched.push(item.file.path);
                 }
@@ -2402,23 +3496,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 +3517,8 @@ export class RollbackPointEngine {
         // 阶段 4（用户 2026-10-11 定案 A）：删除「回退点之后新建」的路径。
         // 顺序刻死：记录在案的路径**先写并复核通过**，再删新建的 —— 先删后写一旦写失败就回不去了。
         // 删除同样可回滚：先读前像（内存）→ 删；任一失败就把已写的还原、把已删的写回。
-        const destroyed = [];
+        // 待删文件的前像同样落盘（stage(path, bytes) 的语义就是「回滚时把它写回」）
+        let destroyedCount = 0;
         const removalFailures = [];
         // 逐条记录**真的删掉**的路径（全量，不再切 20 条）：它与预览的 workspace.removals 同源同序，
         // 界面把两份清单当作同一件事（「预览说会删的 = 实际删的」）。
@@ -2447,7 +3532,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 +3543,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 +3576,8 @@ export class RollbackPointEngine {
         // 捕获不完整 ⇒ 一条都没删：如实回报原因（界面据此说「因为捕获不完整，一条都没动」）
         if (removal.refused !== null)
             segment.createdRefusedReason = removal.refused;
+        // 前像字节用完即清（成功路径）：留在磁盘上只会变成无人认领的残留
+        await stager.dispose();
         return segment;
     }
     /**
@@ -2589,24 +3659,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 +3797,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 +3930,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 +3971,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 +4113,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 +4125,8 @@ export class RollbackAutoTracker {
             handle.unref();
     }
     stop() {
+        // 中断在途捕获：卸载之后不该再有任何一次「读工作区 + 写对象仓」跑完。
+        this.captureAbort.abort();
         if (this.timer === null)
             return;
         clearInterval(this.timer);