dsh-config-manager 0.1.72 → 0.1.76

package/src/core/rollback-point.test.ts

@@ -30,6 +30,7 @@ import path from 'node:path'
 
 import {
   ROLLBACK_ANCESTOR_MAX_DEPTH,
+  ROLLBACK_DEFAULT_CAPTURE_INFLIGHT_BYTES,
   ROLLBACK_DEFAULT_MAX_BYTES,
   ROLLBACK_DEFAULT_MAX_FILES,
   ROLLBACK_LEFTOVER_LIST_LIMIT,
@@ -50,6 +51,8 @@ import {
   type RollbackEngineOptions,
   type RollbackForkInput,
   type RollbackPointRecord,
+  type RollbackTrack,
+  type RollbackWorkspacePayload,
 } from './rollback-point.ts'
 import { projectKeyOf } from './session-select.ts'
 import { atomicWriteFile } from '../utils/atomic-write.ts'
@@ -70,7 +73,10 @@ interface Fixture {
 }
 
 async function makeFixture(): Promise<Fixture> {
-  const root = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-cm-rollback-point-'))
+  // issue #69 口径（与 tests/route/recovery-rollback.test.ts 同款）：os.tmpdir() 在 Windows / macOS 上
+  // 可能给**未规范化**的拼写（Windows 的 8.3 短名 RUNNER~1 / macOS 的 /var → /private/var 软链），
+  // 而引擎内部一律 realpath ⇒ 断言会变成比「同一个目录的两种写法」（CI 的 windows/macos 必红，本机不复现）。
+  const root = await fs.realpath(await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-cm-rollback-point-')))
   const homeDir = path.join(root, 'home')
   const dataDir = path.join(homeDir, 'dsh-config-manager')
   const sessionsDir = path.join(homeDir, 'sessions')
@@ -129,6 +135,43 @@ async function ledgerOf(engine: RollbackPointEngine): Promise<{ records: Rollbac
   return JSON.parse(await readText(path.join(engine.storeDir, 'index.json'))) as { records: RollbackPointRecord[] }
 }
 
+/** v3 记录文件（records/<id>.json）里工作区载荷只剩一个内容寻址哈希引用 */
+interface StoredRecordFile {
+  workspace: Omit<RollbackTrack<RollbackWorkspacePayload>, 'payload'> & { payload: string | null }
+}
+
+/**
+ * v3 台账的**完整记录**读写助手（只给「记录被篡改」这类白盒用例用）。
+ *
+ * 为什么必须成对改写：v3 起完整记录在 records/<id>.json，工作区大数组在**内容寻址**的
+ * payloads/<sha256>.json（清单 index.json 里只剩元数据）。篡改必须同时改载荷与记录里的哈希引用，
+ * 否则读路径会先按「哈希不符」如实失败，就测不到下游那条判据了。
+ */
+async function readFullRecord(engine: RollbackPointEngine, id: string): Promise<RollbackPointRecord> {
+  const file = path.join(engine.storeDir, 'records', id + '.json')
+  const stored = JSON.parse(await readText(file)) as StoredRecordFile & Omit<RollbackPointRecord, 'workspace'>
+  const hash = stored.workspace.payload
+  const payload = hash === null
+    ? null
+    : JSON.parse(await readText(path.join(engine.storeDir, 'payloads', hash + '.json'))) as RollbackWorkspacePayload
+  return { ...stored, workspace: { ...stored.workspace, payload } }
+}
+
+async function writeFullRecord(engine: RollbackPointEngine, record: RollbackPointRecord): Promise<void> {
+  const file = path.join(engine.storeDir, 'records', record.id + '.json')
+  const stored = JSON.parse(await readText(file)) as Record<string, unknown>
+  const payload = record.workspace.payload
+  let hash: string | null = null
+  if (payload !== null) {
+    const text = JSON.stringify(payload)
+    hash = sha256Hex(text)
+    await fs.writeFile(path.join(engine.storeDir, 'payloads', hash + '.json'), text)
+  }
+  const workspaceRaw = stored['workspace'] as Record<string, unknown>
+  workspaceRaw['payload'] = hash
+  await fs.writeFile(file, JSON.stringify(stored))
+}
+
 /* =================================================== R-01 两态捕获 / 无 config */
 
 test('R-01 两态捕获：workspace + session 都有载荷与指纹，且**没有 config 段**', async (t) => {
@@ -656,12 +699,13 @@ test('R-05d 非相邻回退：预览的「会被删除路径集合」必须与
   }
   assert.equal(ws?.removed, 25, 'removed 必须等于真实删除数（detail=' + JSON.stringify(ws?.detail) + '）')
   const refused = ws?.createdSkipped ?? []
-  assert.equal(refused.length, 3, '3 条 .git 路径必须如实进 createdSkipped')
-  for (const file of refused) {
-    assert.ok(file.split(path.sep).includes('.git'), '拒删的必须只可能是 .git 段内的：' + file)
-    assert.equal(await readText(file), 'GIT', '.git 内的文件绝不能被删')
+  // 2026-10-14 起 `.git` 在**捕获与回退两侧**都不进走查 ⇒ 它连候选都不是，不再是「候选后被拒删」。
+  // 断言的是更强的事实：.git 子树**一个字节都没被动过**（拒删判据仍在，只是更早的一道门就挡住了）。
+  assert.equal(refused.length, 0, '.git 子树不进候选（比「候选后拒删」更早一道门）')
+  for (const turn of [3, 4, 5]) {
+    assert.equal(await readText(path.join(fx.workspaceDir, '.git', 'mid' + String(turn))), 'GIT', '.git 内的文件绝不能被删')
   }
-  assert.equal(ws?.createdSkippedCount, 3)
+  assert.equal(ws?.createdSkippedCount, 0)
   assert.equal(ws?.createdRefusedReason, undefined, '捕获完整 ⇒ 不是「捕获不完整」拒删')
 
   // ② 目标点记录在案的路径写回并通过 SHA-256 复核
@@ -673,7 +717,7 @@ test('R-05d 非相邻回退：预览的「会被删除路径集合」必须与
   assert.deepEqual(previewWs.removals, ws?.removedPaths, '预览说会删的 = 实际删的（逐条、同序）')
   assert.equal(previewWs.removalsCount, ws?.removed, '预览的删除总数 = 实际删除数')
   assert.equal(previewWs.removals.some((file) => file.split(path.sep).includes('.git')), false, '预览的删除清单里绝不能混进永不删除的 .git 路径')
-  assert.equal(previewWs.createdSkippedCount, 3, '预览必须同样列出 3 条拒删项')
+  assert.equal(previewWs.createdSkippedCount, 0, '预览与执行同口径：.git 不进候选（所以没有拒删项）')
 
   // ④ 清单**全量**（不再切 20 条）：界面直接把这份清单渲染成「删除」行，不需要任何说明句
   assert.equal(previewWs.removals.length, 25, '25 条会删的必须**全部**列出来（旧实现只列前 20 条，用户看到的正是「预览只列几个」）')
@@ -989,19 +1033,17 @@ test('R-11 记录被篡改不能变成写原语：路径越界 / 指纹不符一
   const captured = await capturePoint(engine, fx)
   const record = captured.point
   assert.ok(record !== undefined)
-  const ledgerPath = path.join(engine.storeDir, 'index.json')
 
   const outside = path.join(fx.root, 'outside.txt')
   await fs.writeFile(outside, 'SAFE')
   await fs.writeFile(path.join(fx.workspaceDir, 'a.txt'), 'A2')
 
-  // 篡改 1：把记录里的路径改成分块之外的文件
-  const tampered = await ledgerOf(engine) as unknown as { records: RollbackPointRecord[] }
-  const wsFiles = tampered.records[0]?.workspace.payload?.files ?? []
-  const hit = wsFiles.find((f) => f.path.endsWith('a.txt'))
+  // 篡改 1：把记录里的路径改成分块之外的文件（同时改载荷与其哈希引用，见 writeFullRecord）
+  const tampered = await readFullRecord(engine, record.id)
+  const hit = (tampered.workspace.payload?.files ?? []).find((f) => f.path.endsWith('a.txt'))
   assert.ok(hit !== undefined)
   hit.path = outside
-  await fs.writeFile(ledgerPath, JSON.stringify(tampered, null, 2))
+  await writeFullRecord(engine, tampered)
   const rewound1 = await engine.rewind({ id: record.id, userConfirmed: true, guardPolicy: 'off' })
   assert.equal(rewound1.outcome, 'failed')
   assert.ok((rewound1.segments[0]?.detail ?? []).some((line) => line.startsWith('invalid-path')))
@@ -1009,15 +1051,35 @@ test('R-11 记录被篡改不能变成写原语：路径越界 / 指纹不符一
   assert.equal(await readText(path.join(fx.workspaceDir, 'a.txt')), 'A2', '一条不合格 → 零写入')
 
   // 篡改 2：路径合法但声明的内容指纹不符
-  const tampered2 = await ledgerOf(engine) as unknown as { records: RollbackPointRecord[] }
-  const hit2 = (tampered2.records[0]?.workspace.payload?.files ?? []).find((f) => f.sha256 === sha256Hex('A1'))
+  // 注：载荷**不再存** `object`（object ≡ sha256，落盘时省掉、读取时按 sha256 补回）⇒ 改 sha256
+  // 等于同时改掉对象名 ⇒ 那个对象根本不存在 ⇒ 如实报 `object-missing`（仍是 fail-closed、零写入）。
+  const tampered2 = await readFullRecord(engine, record.id)
+  const hit2 = (tampered2.workspace.payload?.files ?? []).find((f) => f.sha256 === sha256Hex('A1'))
   assert.ok(hit2 !== undefined)
   hit2.path = path.join(fx.workspaceDir, 'a.txt')   // 路径合法（分块内），只有指纹不符
   hit2.sha256 = sha256Hex('NOT-THE-CAPTURED-CONTENT')
-  await fs.writeFile(ledgerPath, JSON.stringify(tampered2, null, 2))
+  await writeFullRecord(engine, tampered2)
   const rewound2 = await engine.rewind({ id: record.id, userConfirmed: true, guardPolicy: 'off' })
   assert.equal(rewound2.outcome, 'failed')
-  assert.ok((rewound2.segments[0]?.detail ?? []).some((line) => line.includes('object-hash-mismatch')))
+  assert.ok((rewound2.segments[0]?.detail ?? []).some((line) => line.includes('object-missing')),
+    '改 sha256 ⇒ 对象名随之改 ⇒ 读不到：' + JSON.stringify(rewound2.segments[0]?.detail))
+  assert.equal(await readText(path.join(fx.workspaceDir, 'a.txt')), 'A2')
+
+  // 篡改 2b：指纹合法、但把**对象键**指向另一份真实存在的内容 ⇒ 该走 object-hash-mismatch
+  const tampered3 = await readFullRecord(engine, record.id)
+  const files3 = tampered3.workspace.payload?.files ?? []
+  const aTxt = path.join(fx.workspaceDir, 'a.txt')
+  const hit3 = files3.find((f) => f.path === aTxt)
+  assert.ok(hit3 !== undefined)
+  hit3.sha256 = sha256Hex('A1')   // 指纹还原成**真的**（上一轮篡改改过它）
+  const otherObject = files3.find((f) => f.path !== aTxt && f.sha256 !== hit3.sha256)?.sha256
+  assert.ok(otherObject !== undefined)
+  hit3.object = otherObject   // 对象存在、但它的内容哈希 ≠ 记录里的 sha256
+  await writeFullRecord(engine, tampered3)
+  const rewound3 = await engine.rewind({ id: record.id, userConfirmed: true, guardPolicy: 'off' })
+  assert.equal(rewound3.outcome, 'failed')
+  assert.ok((rewound3.segments[0]?.detail ?? []).some((line) => line.includes('object-hash-mismatch')),
+    '对象键被换 ⇒ 内容哈希对不上：' + JSON.stringify(rewound3.segments[0]?.detail))
   assert.equal(await readText(path.join(fx.workspaceDir, 'a.txt')), 'A2')
 })
 
@@ -1337,7 +1399,10 @@ test('R-19 分块不可用 / 非绝对路径 / 会话越界：该态结构化失
   const linked = await capturePoint(engine, fx)
   const track = linked.point?.workspace
   assert.equal(track?.ok, true)
-  assert.equal(track?.degraded, true)
+  // 链接是**设计内**跳过（不跟随、也不该回退它）⇒ 逐条留痕但不算「留得不完整」（R-50 口径）：
+  // 否则任何含符号链接的仓库每个点都挂「回退可能不完整」，真出问题时被噪声淹没
+  assert.equal(track?.degraded, false)
+  assert.equal(track?.reasonCode, null)
   assert.ok((track?.payload?.skipped ?? []).some((s) => s.reason === 'link' && s.path === junction))
   assert.equal((track?.payload?.files ?? []).some((f) => isInsidePath(f.path, junction)), false)
 })
@@ -2150,15 +2215,13 @@ test('R-33 T10：preview 的 stat 失败语义 —— 只有 ENOENT 才算「当
   const engine = makeEngine(fx)
   const captured = await capturePoint(engine, fx)
   const id = captured.point?.id ?? ''
-  const ledgerPath = path.join(engine.storeDir, 'index.json')
-  interface TamperableRecord { id: string; workspace: { payload: { files: { path: string }[] } | null } }
-  const ledger = JSON.parse(await readText(ledgerPath)) as { records: TamperableRecord[] }
-  const record = ledger.records.find((r) => r.id === id)
-  assert.ok(record !== undefined && record.workspace.payload !== null)
-  const victim = record.workspace.payload?.files.find((f) => f.path.endsWith('a.txt'))
+  // v3：完整记录在 records/<id>.json + 内容寻址载荷；篡改必须成对改写（见 writeFullRecord）
+  const tampered = await readFullRecord(engine, id)
+  assert.ok(tampered.workspace.payload !== null)
+  const victim = tampered.workspace.payload.files.find((f) => f.path.endsWith('a.txt'))
   assert.ok(victim !== undefined)
   victim.path = path.join(fx.workspaceDir, 'a' + String.fromCharCode(0) + '.txt')
-  await fs.writeFile(ledgerPath, JSON.stringify(ledger))
+  await writeFullRecord(engine, tampered)
 
   const preview = await engine.preview(id)
   assert.equal(preview.workspace.missing, 0, '非 ENOENT 的 stat 失败**不是**「当前不存在」')
@@ -2346,7 +2409,8 @@ test('T2-B 缓存命中与未命中两条路径下，删除候选判定（预览
   const hit = await engine.preview(id)
   assert.equal(hit.ok, true)
   assert.deepEqual(hit.workspace.removals, created, '两条新建路径都必须被列为会删')
-  assert.equal(hit.workspace.createdSkippedCount, 1, '.git 内的拒删项如实计入')
+  // `.git` 从两侧走查排除 ⇒ 它不进候选（口径与执行侧、与 R-05d 一致）
+  assert.equal(hit.workspace.createdSkippedCount, 0, '.git 不进候选 ⇒ 无拒删项')
 
   // ② 未命中路径：删掉缓存文件 + 用新实例（只能全量真读）
   await fs.rm(path.join(engine.storeDir, 'path-cache.json'), { force: true })
@@ -2364,7 +2428,7 @@ test('T2-B 缓存命中与未命中两条路径下，删除候选判定（预览
   for (const file of created) await assert.rejects(fs.readFile(file), { code: 'ENOENT' })
 })
 
-test('T2-C 忽略规则：整个目录被忽略 ⇒ 证明名单不完整 ⇒ 删除整体拒绝（fail-closed，预览如实说明）', async (t) => {
+test('T2-C 忽略规则：整个目录被忽略 ⇒ **只拒那棵子树**的删除（分子树 fail-closed），范围外照常删', async (t) => {
   const fx = await makeFixture()
   t.after(fx.cleanup)
   const dir = await makeSizeDir(fx, 'cap-ignore-dir', { 'keep.txt': 3, 'note.md': 3 })
@@ -2390,23 +2454,29 @@ test('T2-C 忽略规则：整个目录被忽略 ⇒ 证明名单不完整 ⇒
   await fs.writeFile(createdRoot, 'NEW')
   await fs.writeFile(createdInBuild, 'NEW-IN-BUILD')
 
-  // 预览如实说明：删除被整体拒绝、原因 = 忽略目录
+  // 分子树 fail-closed：拒删只说 build/ 那棵子树，不再把整个工作区的删除一起关掉
   const preview = await engine.preview(captured.point?.id ?? '')
-  assert.equal(preview.workspace.createdRefusedReason, 'capture-incomplete')
-  assert.deepEqual(preview.workspace.removals, [], '证明名单不完整 ⇒ 预览的删除清单必须是空的')
-  const warn = preview.warnings.find((w) => w.code === 'rollback.warn.createdRefused')
-  assert.equal(warn?.detail, 'ignore-dirs', '成因必须如实回传（忽略目录）')
+  assert.equal(preview.workspace.createdRefusedReason, null, '范围说得清 ⇒ 不是全局拒删')
+  assert.deepEqual(preview.workspace.removals, [createdRoot], '范围外的候选照常删')
+  // 被忽略的子树在**回退期也走查不到**（同一条忽略规则）⇒ 它里面的路径根本不进候选，
+  // 既不在删除集、也不必进拒删清单；它的安全由「两端一致地看不见」保证。
+  assert.deepEqual(preview.workspace.createdSkipped, [], '被忽略子树整棵不进候选')
+  assert.equal(
+    preview.warnings.some((w) => w.code === 'rollback.warn.createdRefused'),
+    false,
+    '不再「一条都不删」⇒ 不得给那句全局警告（文案诚实性）',
+  )
 
-  // 执行：一条都不删
+  // 执行：范围内删 1 条、子树里的一条都不删
   const rewound = await engine.rewind({
     id: captured.point?.id ?? '', userConfirmed: true, guardPolicy: 'off', mode: 'files', removeCreated: true,
   })
   const ws = rewound.segments.find((s) => s.state === 'workspace')
-  assert.equal(ws?.createdRefusedReason, 'capture-incomplete')
-  assert.equal(ws?.removed ?? 0, 0, '证明名单不完整 ⇒ 一条都不删')
-  assert.equal(await readText(createdRoot), 'NEW')
-  assert.equal(await readText(createdInBuild), 'NEW-IN-BUILD')
-  assert.ok((ws?.createdSkippedCount ?? 0) > 0, '候选必须如实进拒删清单')
+  assert.equal(ws?.createdRefusedReason, undefined, '分子树拒绝不是全局拒绝')
+  assert.equal(ws?.removed, 1, '范围外的候选照常删')
+  await assert.rejects(fs.readFile(createdRoot), { code: 'ENOENT' })
+  assert.equal(await readText(createdInBuild), 'NEW-IN-BUILD', '被忽略子树里的新建路径绝不删')
+  assert.equal(ws?.createdSkippedCount ?? 0, 0, '被忽略子树不进候选 ⇒ 拒删清单为空（不是「拒删了几条」）')
 })
 
 test('T2-D 忽略规则：文件级忽略仍保持证明名单完整 ⇒ 删除照常；内置 node_modules 规则不可反向取消', async (t) => {
@@ -2458,7 +2528,7 @@ test('T2-E 内存硬约束：同时驻留的文件内容 ≤ maxFileBytes（绝
   sizes['huge.txt'] = 4096
   const dir = await makeSizeDir(fx, 'cap-mem', sizes)
   const reader = countingReader()
-  const engine = makeEngine(fx, { maxFileBytes: 64, maxBytes: 1024 * 1024, readFile: reader.seam })
+  const engine = makeEngine(fx, { maxFileBytes: 64, captureInFlightBytes: 64, maxBytes: 1024 * 1024, readFile: reader.seam })
   const captured = await engine.capturePoint({ chunks: [dir], sessionId: 's-mem' })
   const payload = captured.point?.workspace.payload
   assert.ok(payload !== null && payload !== undefined)
@@ -2466,11 +2536,12 @@ test('T2-E 内存硬约束：同时驻留的文件内容 ≤ maxFileBytes（绝
   assert.equal(reader.reads.includes(path.join(dir, 'huge.txt')), false, '超限文件绝不整份读进内存')
   assert.ok(payload.skipped.some((e) => e.path.endsWith('huge.txt') && e.reason === 'too-large'))
   assert.equal(payload.files.length, 10)
-  // 同时驻留：单份 ≤ maxFileBytes，且从不并发驻留两份（走查是逐条串行的）
+  // 两个上限是两件事：maxFileBytes = 单文件「要不要读」的判据；captureInFlightBytes = 并发内存闸门。
+  // 2026-10-16 之前闸门错接到 maxFileBytes（缺省 = 总量预算 512 MiB）⇒ 桌面闪退。
   assert.ok(reader.peakSingle <= 64, '单份驻留 = ' + String(reader.peakSingle) + ' > maxFileBytes=64')
   assert.ok(
     reader.peakLive <= 64,
-    '同时驻留内容 = ' + String(reader.peakLive) + ' 字节，必须 ≤ maxFileBytes(64) + 常量(0)',
+    '同时驻留内容 = ' + String(reader.peakLive) + ' 字节，必须 ≤ captureInFlightBytes(64)',
   )
 })
 
@@ -2601,3 +2672,757 @@ test('T2-G 路径身份缓存随 gc 回收：删除回滚点后，缓存里不
   assert.equal((await engine.remove(second.point?.id ?? '')).ok, true)
   assert.equal(Object.keys((await cacheFileOf(engine)).entries).length, 0, '没有引用者 ⇒ 缓存条目必须被回收')
 })
+
+/* ========================== R-30..R-35（2026-10-14 三款竞品对照后的修复） */
+
+test('R-30 子代理会话不参与自动留点：origin=subagent 给显式机器码；读不到 origin 照常', () => {
+  const sub = rollbackSessionBindingOf({ id: 'session-9', header: { cwd: '/ws', origin: 'subagent' } })
+  assert.equal(sub.ok, false)
+  assert.equal(sub.ok === false ? sub.code : 'ok', 'subagent-session')
+  // 老宿主 / 形状不符：**不加判定** —— 绝不因为读不到 origin 就少留点
+  assert.equal(rollbackSessionBindingOf({ id: 'session-9', header: { cwd: '/ws' } }).ok, true)
+  // origin 存在但不是 subagent（父会话 / 用户会话）：照常
+  assert.equal(rollbackSessionBindingOf({ id: 'session-9', header: { cwd: '/ws', origin: 'user' } }).ok, true)
+})
+
+test('R-31 采集时间预算：超预算留**部分点**并如实标 truncated（不是失败、不静默）', async (t) => {
+  const fx = await makeFixture()
+  t.after(fx.cleanup)
+  // 时钟每次读 +1ms、预算 1ms ⇒ 第一个判定点就超时（确定性的，不依赖真机速度）
+  const engine = makeEngine(fx, { captureBudgetMs: 1, now: steppingClock(1_000, 1) })
+  const captured = await capturePoint(engine, fx)
+  assert.equal(captured.ok, true, '超预算不是失败：已收条目照常成点')
+  const track = captured.point?.workspace
+  assert.equal(track?.degraded, true)
+  assert.equal(track?.reasonCode, 'capture-truncated')
+  assert.equal(track?.payload?.truncated, true)
+  assert.ok(
+    (track?.payload?.skipped ?? []).some((s) => s.reason === 'budget-time'),
+    '超时必须逐条留痕 budget-time（不是静默截断）',
+  )
+  assert.equal(track?.payload?.walkIncomplete, true, '走查中断必须标记 ⇒ 删除集随之 fail-closed')
+})
+
+/**
+ * 测试专用的时序注入：把「预算**何时**越界」钉成确定性的（不靠真机速度）。
+ *
+ * `now` 恒定返回同一个基线时刻，直到 state 被置位才推过 deadline：
+ *  · `walkDone` 由 {@link timeOutAfterWalk} 在 listChunkFiles 返回后置位 ⇒ 越界发生在**读文件阶段**；
+ *  · `armed` 由 {@link timeOutAtStop} 在第 N 次停止判据内置位 ⇒ 越界发生在**走查之中**。
+ */
+function makeArmedClock(budgetMs: number): { now: () => number; state: { armed: boolean } } {
+  const base = 1_000_000
+  const state = { armed: false }
+  // 未 armed ⇒ 恒定基线时刻（永不越界）；armed ⇒ 直接推过 deadline
+  const now = (): number => (state.armed ? base + budgetMs + 60_000 : base)
+  return { now, state }
+}
+
+/** 包一层私有的 listChunkFiles：把第 `at` 次停止判据变成「越界」（栈里还剩没进去的子树）。 */
+function timeOutAtStop(engine: RollbackPointEngine, state: { armed: boolean }, at: number): void {
+  const self = engine as unknown as { listChunkFiles: (...args: unknown[]) => Promise<unknown> }
+  const original = self.listChunkFiles.bind(engine)
+  // 计数跨分块累计（每个分块各调一次 listChunkFiles，停止判据是按次判定的）
+  let calls = 0
+  self.listChunkFiles = async (...args: unknown[]) => {
+    const stop = args[5]
+    if (typeof stop === 'function') {
+      const stopFn = stop as () => boolean
+      args[5] = () => {
+        calls += 1
+        if (calls >= at) state.armed = true
+        return stopFn()
+      }
+    }
+    return await original(...args)
+  }
+}
+
+test('R-43 预算落在**走查之后**：不误报 walk-incomplete，被中断的条目逐条留痕（删除照常）', async (t) => {
+  const fx = await makeFixture()
+  t.after(fx.cleanup)
+  const dir = await makeSizeDir(fx, 'cap-after-walk', { 'k1.txt': 3, 'k2.txt': 3, 'k3.txt': 3 })
+  const clock = makeArmedClock(50)
+  const engine = makeEngine(fx, {
+    captureBudgetMs: 50,
+    now: clock.now,
+    captureConcurrency: 1,
+    // 确定性地把「超时」钉在**第一个文件读完之后**（不靠真机速度）：并发为 1 ⇒ 只此一份入点
+    readFile: async (file: string) => {
+      const bytes = await fs.readFile(file)
+      clock.state.armed = true
+      return bytes
+    },
+  })
+  const captured = await engine.capturePoint({ chunks: [dir], sessionId: 's-after-walk' })
+  const payload = captured.point?.workspace.payload
+  assert.ok(payload !== null && payload !== undefined)
+  // 读文件阶段被打断 ⇒ 截断仍如实标注（诚实不降级）
+  assert.equal(payload.truncated, true, '读到一半停下必须如实标截断')
+  assert.equal(captured.point?.workspace.reasonCode, 'capture-truncated')
+  assert.deepEqual(payload.files.map((f) => path.basename(f.path)), ['k1.txt'], JSON.stringify(payload.files))
+  // 被中断的两条**逐条留痕**（不静默）—— 名单因此保持完整，不需要路径索引兜底
+  assert.deepEqual(
+    payload.skipped.filter((s) => s.reason === 'budget-time').map((s) => path.basename(s.path)),
+    ['k2.txt', 'k3.txt'],
+    JSON.stringify(payload.skipped),
+  )
+  // 核心：走查已走完 ⇒ **不得**标记「走查不完整」（旧实现在这里误报，删除集整片失效）
+  assert.equal(payload.walkIncomplete ?? false, false, '走查已完成 ⇒ 不许标记 walkIncomplete（误报回归）')
+  assert.equal(payload.pathIndex ?? null, null, '每条都逐条留痕 ⇒ 覆盖自检认为名单完整，无需索引')
+
+  // 点之后新建一条：证明名单完整 ⇒ 预览与执行都照常删
+  const created = path.join(dir, 'created-after.txt')
+  await fs.writeFile(created, 'NEW')
+  const preview = await engine.preview(captured.point?.id ?? '')
+  assert.equal(preview.workspace.createdRefusedReason, null, '证明名单完整 ⇒ 不拒删')
+  assert.deepEqual(preview.workspace.removals, [created])
+  assert.equal(preview.warnings.some((w) => w.code === 'rollback.warn.createdRefused'), false, JSON.stringify(preview.warnings))
+
+  const rewound = await engine.rewind({
+    id: captured.point?.id ?? '', userConfirmed: true, guardPolicy: 'off', mode: 'files', removeCreated: true,
+  })
+  const ws = rewound.segments.find((s) => s.state === 'workspace')
+  assert.equal(ws?.removed, 1, '证明名单完整 ⇒ 新建文件照常删')
+  await assert.rejects(fs.readFile(created), { code: 'ENOENT' })
+  assert.equal(await readText(path.join(dir, 'k3.txt')), 'xxx', '没读到的老文件绝不能被当成「新建」删掉')
+})
+
+test('R-44 走查被打断：只拒「没走查到的那棵子树」（分子树 fail-closed），范围外照常删', async (t) => {
+  const fx = await makeFixture()
+  t.after(fx.cleanup)
+  // 分块 1 整棵走完（其中的文件照常入点）；分块 2 的走查在弹出 sub/ **之前**被预算打断 ⇒ sub/ 从未进门
+  const dir1 = await makeSizeDir(fx, 'cap-walk-ok', { 'n1.txt': 3 })
+  const dir2 = await makeSizeDir(fx, 'cap-walk-abort', { 'm1.txt': 3 })
+  const sub = path.join(dir2, 'sub')
+  await fs.mkdir(sub, { recursive: true })
+  await fs.writeFile(path.join(sub, 'm2.txt'), 'OLD-IN-SUB')
+  const clock = makeArmedClock(50)
+  const engine = makeEngine(fx, { captureBudgetMs: 50, now: clock.now, captureConcurrency: 1 })
+  // 停止判据调用序：dir1 排空(#1) → dir2 弹出(#2，仍在预算内) → dir2/sub 弹出(#3，越界 ⇒ sub/ 从未进门)
+  timeOutAtStop(engine, clock.state, 3)
+
+  const captured = await engine.capturePoint({ chunks: [dir1, dir2], sessionId: 's-walk-abort' })
+  const payload = captured.point?.workspace.payload
+  assert.ok(payload !== null && payload !== undefined)
+  assert.equal(payload.truncated, true)
+  assert.equal(payload.walkIncomplete, true, '子树从未进门 ⇒ 安全判据必须生效')
+  assert.deepEqual(payload.unwalkedDirs, [sub], '精确范围必须带出来（分子树 fail-closed 的依据）')
+  assert.deepEqual(payload.files.map((f) => path.basename(f.path)), ['n1.txt'], '打断前读完的分块照常入点')
+  assert.equal(payload.files.some((f) => f.path.startsWith(sub)), false, 'sub/ 从未被走查')
+  assert.ok(
+    payload.skipped.some((s) => s.path.endsWith('m1.txt') && s.reason === 'budget-time'),
+    JSON.stringify(payload.skipped),
+  )
+
+  const createdElsewhere = path.join(dir1, 'created-in-walked-chunk.txt')
+  const createdRoot = path.join(dir2, 'created-root.txt')
+  const createdInSub = path.join(sub, 'created-in-sub.txt')
+  await fs.writeFile(createdElsewhere, 'NEW')
+  await fs.writeFile(createdRoot, 'NEW')
+  await fs.writeFile(createdInSub, 'NEW-IN-SUB')
+  const preview = await engine.preview(captured.point?.id ?? '')
+  assert.equal(preview.workspace.createdRefusedReason, null, '范围说得清 ⇒ 不是全局拒删')
+  assert.deepEqual(
+    [...preview.workspace.removals].sort(),
+    [createdElsewhere, createdRoot].sort(),
+    '没走查到的子树之外，候选照常删',
+  )
+  // 没走查到的子树里，**所有**当前存在且无记录的路径都进拒删清单（新建的 + 本来就在的 m2.txt）
+  assert.deepEqual(
+    [...preview.workspace.createdSkipped].sort(),
+    [createdInSub, path.join(sub, 'm2.txt')].sort(),
+    '子树里的候选如实进拒删清单',
+  )
+  assert.equal(
+    preview.warnings.some((w) => w.code === 'rollback.warn.createdRefused'),
+    false,
+    '分子树拒绝不得套用那句「一条都不删」的全局警告',
+  )
+
+  const rewound = await engine.rewind({
+    id: captured.point?.id ?? '', userConfirmed: true, guardPolicy: 'off', mode: 'files', removeCreated: true,
+  })
+  const ws = rewound.segments.find((s) => s.state === 'workspace')
+  assert.equal(ws?.createdRefusedReason, undefined, '分子树拒绝不是全局拒绝')
+  assert.equal(ws?.removed, 2, '没走查到的子树之外照常删')
+  await assert.rejects(fs.readFile(createdElsewhere), { code: 'ENOENT' })
+  await assert.rejects(fs.readFile(createdRoot), { code: 'ENOENT' })
+  assert.equal(await readText(createdInSub), 'NEW-IN-SUB')
+  assert.equal(await readText(path.join(sub, 'm2.txt')), 'OLD-IN-SUB', '从未走查的文件绝不能被删')
+  assert.equal(await readText(path.join(dir1, 'n1.txt')), 'xxx')
+  assert.ok((ws?.createdSkippedCount ?? 0) > 0, '候选必须如实进拒删清单')
+})
+
+test('R-45 捕获并发：读 + 写并发跑（真机大头），但在飞内容字节 ≤ captureInFlightBytes', async (t) => {
+  const fx = await makeFixture()
+  t.after(fx.cleanup)
+  const sizes: Record<string, number> = {}
+  for (let i = 0; i < 24; i += 1) sizes['p-' + String(i).padStart(2, '0') + '.txt'] = 64
+  const dir = await makeSizeDir(fx, 'cap-parallel', sizes)
+  let live = 0
+  let peak = 0
+  let inFlight = 0
+  let maxInFlight = 0
+  const engine = makeEngine(fx, {
+    // 闸门 = captureInFlightBytes（并发内存上界），与 maxFileBytes（单文件判据）分开：
+    // 同时最多 4 份 64 B 的内容在飞。
+    captureInFlightBytes: 256,
+    readFile: async (file: string) => {
+      inFlight += 1
+      maxInFlight = Math.max(maxInFlight, inFlight)
+      const bytes = await fs.readFile(file)
+      live += bytes.byteLength
+      peak = Math.max(peak, live)
+      await new Promise((resolve) => setTimeout(resolve, 2)) // 让并发真的重叠
+      live -= bytes.byteLength
+      inFlight -= 1
+      return bytes
+    },
+  })
+  const captured = await engine.capturePoint({ chunks: [dir], sessionId: 's-par' })
+  const payload = captured.point?.workspace.payload
+  assert.equal(payload?.files.length, 24, JSON.stringify(payload?.skipped))
+  assert.ok(maxInFlight > 1, '必须真的并发（否则 34k 文件永远扫不完）：实测 ' + String(maxInFlight))
+  assert.ok(peak <= 256, '在飞内容字节必须 ≤ captureInFlightBytes，实测 ' + String(peak))
+})
+
+test('R-45b 缺省闸门：maxFileBytes 缺省 = 总量预算，绝不能当成在飞内容上限（0.1.74 闪退根因）', async (t) => {
+  const fx = await makeFixture()
+  t.after(fx.cleanup)
+  const sizes: Record<string, number> = {}
+  for (let i = 0; i < 24; i += 1) sizes['g-' + String(i).padStart(2, '0') + '.txt'] = 64
+  const dir = await makeSizeDir(fx, 'cap-inflight-default', sizes)
+  let live = 0
+  let peak = 0
+  // maxFileBytes 给一个**远大于闸门**的值：旧实现（闸门 = maxFileBytes）会放行 24×64 = 1536 B 在飞。
+  const engine = makeEngine(fx, {
+    maxFileBytes: 4096,
+    captureInFlightBytes: 128,
+    readFile: async (file: string) => {
+      const bytes = await fs.readFile(file)
+      live += bytes.byteLength
+      peak = Math.max(peak, live)
+      await new Promise((resolve) => setTimeout(resolve, 2))
+      live -= bytes.byteLength
+      return bytes
+    },
+  })
+  const captured = await engine.capturePoint({ chunks: [dir], sessionId: 's-inflight' })
+  assert.equal(captured.point?.workspace.payload?.files.length, 24)
+  assert.ok(peak <= 128, '在飞内容必须被 captureInFlightBytes 钉死（不是 maxFileBytes），实测 ' + String(peak))
+  // 缺省闸门本身必须远小于总量预算 —— 它才是并发的内存上界
+  assert.equal(ROLLBACK_DEFAULT_CAPTURE_INFLIGHT_BYTES, 32 * 1024 * 1024)
+  assert.ok(
+    ROLLBACK_DEFAULT_CAPTURE_INFLIGHT_BYTES < ROLLBACK_DEFAULT_MAX_BYTES / 8,
+    '缺省在飞闸门必须比总量预算小一个数量级以上',
+  )
+})
+
+test('T2-H .asar 路径绝不交给 fs：宿主里那是原生容器解析，畸形夹具能带走整个宿主', async (t) => {
+  const fx = await makeFixture()
+  t.after(fx.cleanup)
+  const dir = await makeSizeDir(fx, 'cap-asar', {})
+  await fs.writeFile(path.join(dir, 'normal.txt'), 'N')
+  await fs.writeFile(path.join(dir, 'broken.asar'), Buffer.alloc(64, 0xff))
+  await fs.mkdir(path.join(dir, 'bundle.asar'), { recursive: true })
+  await fs.writeFile(path.join(dir, 'bundle.asar', 'inner.txt'), 'I')
+  const reads: string[] = []
+  const engine = makeEngine(fx, {
+    readFile: async (file: string) => {
+      reads.push(file)
+      return await fs.readFile(file)
+    },
+  })
+  const captured = await engine.capturePoint({ chunks: [dir], sessionId: 's-asar' })
+  const payload = captured.point?.workspace.payload
+  assert.ok(payload !== null && payload !== undefined)
+  assert.equal(reads.some((f) => f.endsWith('.asar')), false, '任何 .asar 路径都不得被读')
+  assert.equal(reads.some((f) => f.includes('.asar' + path.sep)), false, '含 .asar 段的路径一律不碰')
+  assert.ok(
+    payload.skipped.some((e) => e.path.endsWith('broken.asar') && e.reason === 'asar-container'),
+    '畸形 .asar 必须留痕为 asar-container: ' + JSON.stringify(payload.skipped.map((e) => [e.path, e.reason])),
+  )
+  assert.ok(
+    payload.skipped.some((e) => e.path.endsWith('bundle.asar') && e.reason === 'asar-container'),
+    '名字含 .asar 段的目录同样不碰',
+  )
+  assert.ok(payload.files.some((f) => f.path.endsWith('normal.txt')), '普通文件照常入点')
+})
+
+test('R-46 缺口优先：预算被限死时覆盖率随回合**单调收敛**到 100%', async (t) => {
+  const fx = await makeFixture()
+  t.after(fx.cleanup)
+  const dir = await makeSizeDir(fx, 'cap-converge', {})
+  const names = Array.from({ length: 60 }, (_, i) => 'c-' + String(i).padStart(3, '0') + '.txt')
+  for (const name of names) await fs.writeFile(path.join(dir, name), 'x')
+  // 每回合只放行 3 次读：等价于「预算只够扫一小部分」的确定性版本
+  let allowance = 3
+  const engine = makeEngine(fx, {
+    captureConcurrency: 1,
+    now: () => (allowance <= 0 ? 2_000_000 + 60_000 : 2_000_000),
+    readFile: async (file: string) => {
+      const bytes = await fs.readFile(file)
+      allowance -= 1
+      return bytes
+    },
+  })
+  const seen = new Set<string>()
+  const covered: number[] = []
+  for (let round = 0; round < 25; round += 1) {
+    allowance = 3
+    const captured = await engine.capturePoint({ chunks: [dir], sessionId: 's-converge' })
+    for (const file of captured.point?.workspace.payload?.files ?? []) seen.add(file.path)
+    covered.push(seen.size)
+  }
+  for (let i = 1; i < covered.length; i += 1) {
+    assert.ok(covered[i]! >= covered[i - 1]!, '覆盖率不得回退：' + covered.join(','))
+  }
+  assert.equal(covered[covered.length - 1], 60, '足够多回合后必须覆盖 100%：' + covered.join(','))
+})
+
+test('R-47 自适应预算：被截断 ⇒ 下次翻倍；提前收工 ⇒ 下次减半（区间内）', async (t) => {
+  const fx = await makeFixture()
+  t.after(fx.cleanup)
+  const dir = await makeSizeDir(fx, 'cap-adapt', { 'a.txt': 3, 'b.txt': 3 })
+  let stepped = true
+  let tick = 0
+  const engine = makeEngine(fx, {
+    captureBudgetMs: 1_000,
+    captureBudgetMinMs: 500,
+    captureBudgetMaxMs: 4_000,
+    now: () => (stepped ? (tick += 1_000) : Date.now()),
+  })
+  const budgetOf = (): number => (engine as unknown as { captureBudgetMs: number }).captureBudgetMs
+  assert.equal(budgetOf(), 1_000, '初值 = 选项值')
+  // ① 步进时钟 ⇒ 一次次判定就撞满预算 ⇒ 截断 ⇒ 下次翻倍
+  const truncated = await engine.capturePoint({ chunks: [dir], sessionId: 's-adapt' })
+  assert.equal(truncated.point?.workspace.payload?.truncated, true)
+  assert.equal(budgetOf(), 2_000, '被截断 ⇒ 翻倍')
+  // ② 真实时钟 ⇒ 两个小文件毫秒级跑完（用不到 1/4）⇒ 下次减半；继续跑到下界为止
+  stepped = false
+  await engine.capturePoint({ chunks: [dir], sessionId: 's-adapt' })
+  assert.equal(budgetOf(), 1_000, '提前收工 ⇒ 减半')
+  await engine.capturePoint({ chunks: [dir], sessionId: 's-adapt' })
+  await engine.capturePoint({ chunks: [dir], sessionId: 's-adapt' })
+  assert.equal(budgetOf(), 500, '减到下界即停（回到 captureBudgetMinMs 下界）')
+})
+
+test('R-48 捕获竞态：读到一半被改写的文件不当前像，但进证明名单（绝不被当成新建删掉）', async (t) => {
+  const fx = await makeFixture()
+  t.after(fx.cleanup)
+  const dir = await makeSizeDir(fx, 'cap-race', { 'r1.txt': 3, 'r2.txt': 3 })
+  const target = path.join(dir, 'r1.txt')
+  let mutated = false
+  const engine = makeEngine(fx, {
+    captureConcurrency: 1,
+    readFile: async (file: string) => {
+      const bytes = await fs.readFile(file)
+      if (file === target && !mutated) {
+        mutated = true
+        await fs.writeFile(file, 'XYZ') // 同长度原地改写：身份（mtimeNs/ctimeNs）必变
+      }
+      return bytes
+    },
+  })
+  const captured = await engine.capturePoint({ chunks: [dir], sessionId: 's-race' })
+  const payload = captured.point?.workspace.payload
+  assert.ok(payload !== null && payload !== undefined)
+  assert.equal(mutated, true)
+  assert.equal(payload.files.some((f) => f.path === target), false, '竞态中的文件不得当作前像')
+  assert.ok(
+    payload.unreadableFiles.some((f) => f.path === target && f.reason === 'changed-during-read'),
+    JSON.stringify(payload.unreadableFiles),
+  )
+  const created = path.join(dir, 'created.txt')
+  await fs.writeFile(created, 'NEW')
+  const preview = await engine.preview(captured.point?.id ?? '')
+  assert.equal(preview.workspace.createdRefusedReason, null, '证明名单仍完整（unreadableFiles 也是证明）')
+  assert.deepEqual(preview.workspace.removals, [created])
+  const rewound = await engine.rewind({
+    id: captured.point?.id ?? '', userConfirmed: true, guardPolicy: 'off', mode: 'files', removeCreated: true,
+  })
+  assert.equal(rewound.ok, true)
+  assert.equal(await readText(target), 'XYZ', '竞态文件绝不能被当成新建删掉')
+  assert.equal(await readText(path.join(dir, 'r2.txt')), 'xxx')
+})
+
+test('R-49 记录与读预算解耦：已知内容不占读槽位 ⇒ 大仓库从第二个点起记录全量', async (t) => {
+  const fx = await makeFixture()
+  t.after(fx.cleanup)
+  const dir = await makeSizeDir(fx, 'cap-entries', {})
+  const names = Array.from({ length: 12 }, (_, i) => 'e-' + String(i).padStart(2, '0') + '.txt')
+  for (const name of names) await fs.writeFile(path.join(dir, name), 'x')
+  // 每回合只允许读 5 条**新内容**（maxFiles 约束的是读，不是「记录多少条」）
+  const engine = makeEngine(fx, { maxFiles: 5 })
+  const first = await engine.capturePoint({ chunks: [dir], sessionId: 's-entries' })
+  const p1 = first.point?.workspace.payload
+  assert.equal(p1?.files.length, 5, '第一点：只有 5 条新内容被读进来')
+  assert.equal(p1?.truncated, true, '还有新内容没读 ⇒ 如实标截断')
+  const second = await engine.capturePoint({ chunks: [dir], sessionId: 's-entries' })
+  const p2 = second.point?.workspace.payload
+  assert.equal(p2?.files.length, 10, '已知的 5 条不占槽位、一律进记录：' + JSON.stringify(p2?.files.map((f) => path.basename(f.path))))
+  const third = await engine.capturePoint({ chunks: [dir], sessionId: 's-entries' })
+  const p3 = third.point?.workspace.payload
+  assert.equal(p3?.files.length, 12, '全部已知 ⇒ 记录必须是全量（这是「任何大小都收敛」的判据）')
+  assert.equal(p3?.truncated, false, '没有新内容要读 ⇒ 不该再标截断')
+  assert.deepEqual(p3?.files.map((f) => path.basename(f.path)), names, '记录顺序仍按路径有序')
+})
+
+test('R-50 降级口径：设计内跳过（符号链接 / 文件级忽略）不构成「留得不完整」；缺内容才算', async (t) => {
+  const fx = await makeFixture()
+  t.after(fx.cleanup)
+  // 分块根：一个正常文件 + 一个被文件级忽略规则跳过的文件（等价于「符号链接被跳过」那类设计内跳过）
+  const dir = await makeSizeDir(fx, 'cap-degraded', { 'keep.txt': 3 })
+  await fs.writeFile(path.join(dir, 'old.log'), 'OLD')
+  await fs.writeFile(path.join(dir, '.dsh-rollback-ignore'), '*.log' + '\n')
+  const engine = makeEngine(fx)
+  const first = await engine.capturePoint({ chunks: [dir], sessionId: 's-degraded' })
+  const p1 = first.point?.workspace.payload
+  assert.ok(p1 !== null && p1 !== undefined)
+  assert.ok(p1.skippedCount > 0, '文件级忽略必须逐条留痕：' + JSON.stringify(p1.skipped))
+  assert.equal(p1.skipped.some((e) => e.reason === 'ignored'), true)
+  assert.equal(p1.truncated, false)
+  assert.equal(first.point?.workspace.degraded, false, '设计内跳过 ⇒ 不得报「留得不完整」')
+  assert.equal(first.point?.workspace.reasonCode, null)
+  const seg = (await engine.list()).points[0]?.segments.find((s) => s.state === 'workspace')
+  assert.equal(seg?.degraded, false, '列表摘要同样不得降级')
+  assert.equal(seg?.reasonCode, null)
+
+  // 对照：真的缺内容（超单文件上限被跳过）⇒ 必须降级且如实给码
+  const dir2 = await makeSizeDir(fx, 'cap-degraded-real', { 'big.bin': 200 })
+  const engine2 = makeEngine(fx, { maxFileBytes: 64 })
+  const second = await engine2.capturePoint({ chunks: [dir2], sessionId: 's-degraded2' })
+  assert.equal(second.point?.workspace.degraded, true)
+  assert.equal(second.point?.workspace.reasonCode, 'capture-truncated')
+  assert.ok(second.point?.workspace.payload?.skipped.some((e) => e.reason === 'too-large'))
+})
+
+test('R-51 预览快路径：身份命中时不再真读工作区文件（大仓库预览的 13 s 就在这一步）', async (t) => {
+  const fx = await makeFixture()
+  t.after(fx.cleanup)
+  const dir = await makeSizeDir(fx, 'cap-preview', { 'a.txt': 5, 'b.txt': 5, 'c.txt': 5 })
+  const reader = countingReader()
+  const engine = makeEngine(fx, { readFile: reader.seam })
+  const captured = await engine.capturePoint({ chunks: [dir], sessionId: 's-preview' })
+  const id = captured.point?.id ?? ''
+  reader.reset()
+  const first = await engine.preview(id)
+  assert.equal(first.workspace.different, 0, '三条全都一致')
+  assert.equal(reader.reads.length, 0, '身份命中 ⇒ 预览一次都不读内容：' + JSON.stringify(reader.reads))
+  // 改一条：**只有它**需要被真读（其余仍走快路径）
+  await fs.writeFile(path.join(dir, 'b.txt'), 'ZZZZZ')
+  reader.reset()
+  const second = await engine.preview(id)
+  assert.equal(second.workspace.different, 1)
+  assert.deepEqual(reader.reads, [path.join(dir, 'b.txt')], '只真读被改的那一条：' + JSON.stringify(reader.reads))
+})
+
+test('R-52 回退快路径：已一致的条目不读对象、不写盘；用不到的对象坏掉不再中止整次回退', async (t) => {
+  const fx = await makeFixture()
+  t.after(fx.cleanup)
+  const dir = await makeSizeDir(fx, 'cap-rewind-fast', { 'k1.txt': 5, 'k2.txt': 5 })
+  const reader = countingReader()
+  const engine = makeEngine(fx, {
+    readFile: reader.seam,
+    writeFile: async () => { throw new Error('不该写任何文件') },
+  })
+  const captured = await engine.capturePoint({ chunks: [dir], sessionId: 's-rewind-fast' })
+  const id = captured.point?.id ?? ''
+  reader.reset()
+  const rewound = await engine.rewind({ id, userConfirmed: true, guardPolicy: 'off', mode: 'files', removeCreated: true })
+  const ws = rewound.segments.find((s) => s.state === 'workspace')
+  assert.equal(rewound.outcome, 'restored', JSON.stringify(ws))
+  assert.equal(ws?.reasonCode, 'nothing-to-restore', '全部已一致 ⇒ 0 变更')
+  assert.equal(reader.reads.length, 0, '身份命中 ⇒ 阶段 2/3 一次都不读：' + JSON.stringify(reader.reads))
+
+  // 新语义：**用不到的对象**坏掉不该中止整次回退（真要用它时仍会 object-missing 硬失败）
+  const payload = (await engine.read(id)).point?.workspace.payload
+  assert.ok(payload !== null && payload !== undefined)
+  await fs.rm(path.join(engine.storeDir, 'objects', payload.files[0]?.object ?? ''))
+  const second = await engine.rewind({ id, userConfirmed: true, guardPolicy: 'off', mode: 'files', removeCreated: true })
+  const ws2 = second.segments.find((s) => s.state === 'workspace')
+  assert.equal(second.outcome, 'restored', '用不到的对象坏掉仍应成功：' + JSON.stringify(ws2?.detail))
+  assert.equal(ws2?.reasonCode, 'nothing-to-restore')
+})
+
+test('R-53 清单增量化：第二点只落「相对第一点的增量」，读回来是同一份完整清单', async (t) => {
+  const fx = await makeFixture()
+  t.after(fx.cleanup)
+  const dir = path.join(fx.workspaceDir, 'cap-delta')
+  await fs.mkdir(dir, { recursive: true })
+  for (let i = 0; i < 40; i += 1) {
+    await fs.writeFile(path.join(dir, 'f' + String(i).padStart(2, '0') + '.txt'), 'V' + String(i))
+  }
+  const engine = makeEngine(fx)
+  const first = await engine.capturePoint({ chunks: [dir], sessionId: 's-delta' })
+  const firstFull = first.point?.workspace.payload
+  assert.ok(firstFull !== null && firstFull !== undefined)
+  assert.equal(firstFull.fileCount, 40)
+  const manifest = JSON.parse(await fs.readFile(path.join(engine.storeDir, 'index.json'), 'utf8')) as {
+    records: { id: string; workspace: { payload: string | null; payloadChain?: string[] } }[]
+  }
+  void manifest
+  // 每次现读清单（第二点会再写一次清单）
+  const hashOf = async (id: string): Promise<string> => {
+    const fresh = JSON.parse(await fs.readFile(path.join(engine.storeDir, 'index.json'), 'utf8')) as {
+      records: { id: string; workspace: { payload: string | null; payloadChain?: string[] } }[]
+    }
+    return fresh.records.find((r) => r.id === id)?.workspace.payload ?? ''
+  }
+  const payloadPath = (hash: string): string => path.join(engine.storeDir, 'payloads', hash + '.json')
+  const firstHash = await hashOf(first.point?.id ?? '')
+  const firstBytes = (await fs.stat(payloadPath(firstHash))).size
+  t.diagnostic('首点载荷 ' + String(firstBytes) + ' 字节')
+  // 第二点：改 1 个文件 + 新增 1 个 ⇒ 增量应远小于全量
+  await fs.writeFile(path.join(dir, 'f00.txt'), 'CHANGED')
+  await fs.writeFile(path.join(dir, 'new.txt'), 'NEW')
+  const second = await engine.capturePoint({ chunks: [dir], sessionId: 's-delta' })
+  const secondFull = second.point?.workspace.payload
+  assert.ok(secondFull !== null && secondFull !== undefined)
+  assert.equal(secondFull.fileCount, 41, '摘要里的条数必须是全量条数，不是增量条数')
+  const payloadsDir = path.join(engine.storeDir, 'payloads')
+  const names = await fs.readdir(payloadsDir)
+  assert.equal(names.length, 2, '首点全量 + 第二点增量（内容不同 ⇒ 两份载荷）')
+  const secondHash = await hashOf(second.point?.id ?? '')
+  assert.notEqual(secondHash, firstHash)
+  const secondBytes = (await fs.stat(payloadPath(secondHash))).size
+  const secondStored = JSON.parse(await fs.readFile(payloadPath(secondHash), 'utf8')) as { delta?: { base?: string } }
+  assert.equal(secondStored.delta?.base, firstHash, '第二点必须是相对首点的增量视图（而不是又一份全量）')
+  assert.ok(secondBytes < firstBytes / 2, '增量载荷必须明显更小：' + String(secondBytes) + ' vs ' + String(firstBytes))
+  // 读回来必须与「全量捕获」逐条一致（路径序 / sha / bytes / 对象键）
+  const back = await engine.read(second.point?.id ?? '')
+  const rebuilt = back.point?.workspace.payload
+  assert.ok(rebuilt !== null && rebuilt !== undefined)
+  assert.equal(rebuilt.delta, undefined, '读回来必须是物化后的完整清单')
+  const sorted = [...(secondFull.files ?? [])].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
+  assert.deepEqual(
+    rebuilt.files.map((f) => [f.path, f.sha256, f.bytes, f.object]),
+    sorted.map((f) => [f.path, f.sha256, f.bytes, f.object]),
+    '增量重建的清单必须与全量逐条一致（含补回的 object）',
+  )
+  assert.equal(rebuilt.pathIndex?.object ?? null, secondFull.pathIndex?.object ?? null)
+  // 预览与全量点同一口径：内容一致 ⇒ 零改动
+  const preview = await engine.preview(second.point?.id ?? '')
+  assert.equal(preview.workspace.different, 0)
+  assert.equal(preview.workspace.overwrite, 41, '全量条数（不是增量条数）')
+})
+
+test('R-54 增量链：基准载荷缺失 ⇒ 该点如实失败（绝不返回半份清单）；prune 不删被链引用的载荷', async (t) => {
+  const fx = await makeFixture()
+  t.after(fx.cleanup)
+  const dir = path.join(fx.workspaceDir, 'cap-delta-chain')
+  await fs.mkdir(dir, { recursive: true })
+  for (let i = 0; i < 20; i += 1) await fs.writeFile(path.join(dir, 'g' + String(i) + '.txt'), 'C' + String(i))
+  const engine = makeEngine(fx)
+  const a = await engine.capturePoint({ chunks: [dir], sessionId: 's-chain' })
+  await fs.writeFile(path.join(dir, 'g0.txt'), 'CHANGED')
+  const b = await engine.capturePoint({ chunks: [dir], sessionId: 's-chain' })
+  assert.ok(a.point !== undefined && b.point !== undefined)
+  // 第二点必须是增量（载荷哈希 ≠ 第一点；且它的载荷里有 delta 标记）
+  const payloadsDir = path.join(engine.storeDir, 'payloads')
+  const names = await fs.readdir(payloadsDir)
+  assert.equal(names.length, 2)
+  const manifest = JSON.parse(await fs.readFile(path.join(engine.storeDir, 'index.json'), 'utf8')) as {
+    records: { id: string; workspace: { payload: string | null; payloadChain?: string[] } }[]
+  }
+  const entryOf = (id: string) => manifest.records.find((r) => r.id === id)
+  const payloadPath = (hash: string): string => path.join(payloadsDir, hash + '.json')
+  const bHash = entryOf(b.point.id)?.workspace.payload ?? ''
+  assert.ok(Array.isArray(entryOf(b.point.id)?.workspace.payloadChain), '清单条目必须带上解析所需的链')
+  const bFile = JSON.parse(await fs.readFile(payloadPath(bHash), 'utf8')) as {
+    files?: unknown
+    delta?: { base?: string; added?: unknown; removed?: unknown }
+  }
+  assert.ok(bFile.delta !== undefined && bFile.delta.base !== undefined, '第二点必须落成增量视图')
+  const delta0 = bFile.delta as { base: string; added?: unknown }
+  // 增量视图**故意**让 files 不是数组：不认识 delta 的旧读取器会因形状不符拒绝这个点（fail-closed），
+  // 而不是把「增量那几条」当完整清单去规划删除
+  assert.equal(bFile.files, null, '增量视图的 files 必须为 null')
+  assert.ok(Array.isArray(delta0.added))
+  // 删掉基准载荷：**读第二点必须如实失败**（半份清单会被拿去规划删除，等于删掉其它全部文件）
+  await fs.rm(payloadPath(delta0.base))
+  const broken = await engine.read(b.point.id)
+  assert.equal(broken.point, undefined)
+  assert.ok((broken.error ?? '').includes('record-incomplete'), '如实失败：' + String(broken.error))
+})
+
+test('R-32 取消信号：已中止 ⇒ 在文件边界停下（部分点 + budget-time 留痕，绝不整份跑完）', async (t) => {
+  const fx = await makeFixture()
+  t.after(fx.cleanup)
+  const engine = makeEngine(fx)
+  const controller = new AbortController()
+  controller.abort()
+  const captured = await capturePoint(engine, fx, { signal: controller.signal })
+  assert.equal(captured.ok, true, '取消 = 部分点，不是失败')
+  const track = captured.point?.workspace
+  assert.equal(track?.payload?.truncated, true)
+  assert.ok((track?.payload?.skipped ?? []).some((s) => s.reason === 'budget-time'))
+})
+
+test('R-33 预算兜不住单条点：如实标 overBudget（记录仍保留，绝不悄悄丢用户刚留的点）', async (t) => {
+  const fx = await makeFixture()
+  t.after(fx.cleanup)
+  // 预算 1 字节：任何一条记录都超，且候选里没有可淘汰的旧点
+  const engine = makeEngine(fx, { ledgerBytesBudget: 1 })
+  assert.equal((await capturePoint(engine, fx)).ok, true)
+  const status = await engine.storageStatus()
+  assert.equal(status.ledger?.records, 1, '超预算不删刚留的点')
+  assert.equal(status.ledger?.overBudget, true, '预算兜不住时必须如实上报，不能显示成「一切正常」')
+})
+
+test('R-34 回退前像落盘：成功后 undo 目录零残留', async (t) => {
+  const fx = await makeFixture()
+  t.after(fx.cleanup)
+  const engine = makeEngine(fx, { fork: async () => ({ ok: true, childSessionId: 'child-1' }) })
+  const captured = await capturePoint(engine, fx)
+  const id = captured.point?.id ?? ''
+  await fs.writeFile(path.join(fx.workspaceDir, 'a.txt'), 'A2')
+  const rewind = await engine.rewind({ id, userConfirmed: true, guardPolicy: 'off' })
+  assert.equal(rewind.ok, true)
+  assert.equal(await readText(path.join(fx.workspaceDir, 'a.txt')), 'A1', '前像落盘不影响「写回原内容」')
+  const undoRoot = path.join(engine.storeDir, 'undo')
+  assert.deepEqual(await fs.readdir(undoRoot).catch(() => []), [], '前像目录用完即清（不留无人认领的字节）')
+})
+
+test('R-34b 前像暂存建不出来 ⇒ 零写入失败（回退没有安全网就不该开始）', async (t) => {
+  const fx = await makeFixture()
+  t.after(fx.cleanup)
+  const engine = makeEngine(fx, { fork: async () => ({ ok: true, childSessionId: 'child-1' }) })
+  const captured = await capturePoint(engine, fx)
+  const id = captured.point?.id ?? ''
+  await fs.writeFile(path.join(fx.workspaceDir, 'a.txt'), 'A2')
+  // 用一个**文件**占住 undo 路径 ⇒ mkdir 必然失败（ENOTDIR/EEXIST）
+  await fs.writeFile(path.join(engine.storeDir, 'undo'), 'block')
+  const rewind = await engine.rewind({ id, userConfirmed: true, guardPolicy: 'off' })
+  assert.equal(rewind.ok, false)
+  assert.equal(rewind.outcome, 'failed')
+  assert.equal(await readText(path.join(fx.workspaceDir, 'a.txt')), 'A2', '零写入：文件保持回退前的内容')
+})
+
+test('R-35 崩溃残留的回退前像目录：死 pid 整目录清掉、活 pid 一律不碰', async (t) => {
+  const fx = await makeFixture()
+  t.after(fx.cleanup)
+  const engine = makeEngine(fx)
+  await engine.storageStatus()
+  const undoRoot = path.join(engine.storeDir, 'undo')
+  const dead = path.join(undoRoot, '999999-abc-01234567')
+  const live = path.join(undoRoot, String(process.pid) + '-abc-01234567')
+  await fs.mkdir(dead, { recursive: true })
+  await fs.writeFile(path.join(dead, '0.bin'), 'x'.repeat(64))
+  await fs.mkdir(live, { recursive: true })
+  const { cleanupOrphanTempFiles } = await import('./rollback-ledger.ts')
+  const result = await cleanupOrphanTempFiles(engine.storeDir)
+  assert.equal(result.removed, 1)
+  assert.ok(result.bytes >= 64)
+  await assert.rejects(fs.access(dead), '死 pid 的残留目录必须被清掉')
+  await fs.access(live)
+})
+
+test('R-36 走查被中断的点：删除集整体拒绝（未走查的子树不得被当成「留点后新建」删掉）', async (t) => {
+  const fx = await makeFixture()
+  t.after(fx.cleanup)
+  const engine = makeEngine(fx, { fork: async () => ({ ok: true, childSessionId: 'child-1' }) })
+  const captured = await capturePoint(engine, fx)
+  const id = captured.point?.id ?? ''
+  // 白盒：造出 R-31 现场的那个状态（时间预算中断 ⇒ 剩余子树一条都没进任何名单）
+  const record = await readFullRecord(engine, id)
+  assert.notEqual(record.workspace.payload, null)
+  if (record.workspace.payload !== null) record.workspace.payload.walkIncomplete = true
+  await writeFullRecord(engine, record)
+
+  // 留点之后新建的文件：它在留点时刻**是否存在**已无从证明
+  const created = path.join(fx.workspaceDir, 'created-after.txt')
+  await fs.writeFile(created, 'NEW')
+
+  const preview = await engine.preview(id)
+  assert.equal(preview.workspace.createdRefusedReason, 'capture-incomplete', '预览必须拒绝删除并说明原因')
+  assert.deepEqual(preview.workspace.removals, [], '预览不得列出任何待删路径')
+
+  const rewind = await engine.rewind({ id, userConfirmed: true, guardPolicy: 'off', removeCreated: true })
+  assert.equal(rewind.ok, true)
+  assert.equal(await readText(created), 'NEW', '证明名单不完整 ⇒ 一条都不删（绝不误删未走查子树里的文件）')
+})
+
+
+test('R-42 .git 不进捕获面：整棵进 excludedDirs 留痕，且不进 files', async (t) => {
+  const fx = await makeFixture()
+  t.after(fx.cleanup)
+  await fs.mkdir(path.join(fx.workspaceDir, '.git'), { recursive: true })
+  await fs.writeFile(path.join(fx.workspaceDir, '.git', 'index'), 'GIT')
+  const engine = makeEngine(fx)
+  const captured = await capturePoint(engine, fx)
+  const payload = captured.point?.workspace.payload
+  assert.ok(payload)
+  assert.equal(
+    (payload?.files ?? []).some((f) => f.path.split(path.sep).includes('.git')),
+    false,
+    '.git 下的文件不得进快照（回退写回 .git 会让 git 状态错乱，且 .git 会挤掉 maxBytes 预算）',
+  )
+  assert.ok(
+    (payload?.excludedDirs ?? []).some((e) => e.path.endsWith('.git') && e.reason === 'git-dir'),
+    '.git 必须如实进 excludedDirs（留痕，不静默）',
+  )
+  assert.equal(payload?.files.length, 2, '工作区里的两个正常文件照常进快照')
+})
+
+test('R-37 清单损坏时**从 records/ 重建**：旧点不丢（而不是拿空清单覆盖掉它们）', async (t) => {
+  const fx = await makeFixture()
+  t.after(fx.cleanup)
+  const engine = makeEngine(fx)
+  const first = await capturePoint(engine, fx)
+  assert.equal(first.ok, true)
+  const firstId = first.point?.id ?? ''
+  const manifestPath = path.join(engine.storeDir, 'index.json')
+  // 把清单弄成**读不出来**：readManifest 返回 { entries: [], error }
+  await fs.writeFile(manifestPath, '{"schemaVersion": 3, "records": "not-an-array"}')
+  const second = await capturePoint(engine, fx, { sessionId: 's-other' })
+  assert.equal(second.ok, true, '清单损坏不该阻塞留点（R-16 的既有口径）')
+  const after = await engine.list()
+  assert.equal(after.error, undefined)
+  assert.equal(after.points.length, 2, '旧点必须从 records/ 重建回来，绝不能被空清单覆盖丢掉')
+  assert.ok(after.points.some((pt) => pt.id === firstId), '而且就是原来那一条（同 id）')
+})
+
+// 折大小写只在 Windows 生效（win32Fold）：Linux 上 `.GIT` 与 `.git` 是两个不同目录，
+// 本用例断言的是「不区分大小写的文件系统」下的保护行为，故非 Windows 一律跳过。
+test(
+  'R-40 拒删判据折大小写：.GIT 子树同样受保护（Windows 文件系统不区分大小写）',
+  { skip: process.platform === 'win32' ? false : '折大小写只在 Windows 生效（win32Fold）；Linux 上 .GIT 与 .git 是不同目录' },
+  async (t) => {
+  const fx = await makeFixture()
+  t.after(fx.cleanup)
+  const engine = makeEngine(fx, { fork: async () => ({ ok: true, childSessionId: 'child-1' }) })
+  const captured = await capturePoint(engine, fx)
+  const id = captured.point?.id ?? ''
+  const dir = path.join(fx.workspaceDir, '.GIT')
+  await fs.mkdir(dir, { recursive: true })
+  const inner = path.join(dir, 'x.txt')
+  await fs.writeFile(inner, 'PROTECTED')
+  const rewind = await engine.rewind({ id, userConfirmed: true, guardPolicy: 'off', removeCreated: true })
+  assert.equal(rewind.ok, true)
+  assert.equal(await readText(inner), 'PROTECTED', '.GIT 子树不得被当成「留点后新建」删除')
+})
+
+test('R-41 回退期走查也有时间预算：中断只让候选变少（安全方向）并如实标 truncated', async (t) => {
+  const fx = await makeFixture()
+  t.after(fx.cleanup)
+  const engine = makeEngine(fx, { fork: async () => ({ ok: true, childSessionId: 'child-1' }) })
+  const captured = await capturePoint(engine, fx)
+  const id = captured.point?.id ?? ''
+  const created = path.join(fx.workspaceDir, 'created-after.txt')
+  await fs.writeFile(created, 'NEW')
+  // 同一个台账、另一套预算：回退阶段第一个判定点就超时（步进时钟 + 1ms 预算，确定性）
+  const fast = makeEngine(fx, {
+    captureBudgetMs: 1,
+    now: steppingClock(5_000_000, 1),
+    fork: async () => ({ ok: true, childSessionId: 'child-1' }),
+  })
+  const rewind = await fast.rewind({ id, userConfirmed: true, guardPolicy: 'off', removeCreated: true })
+  assert.equal(rewind.ok, true, '走查中断不是失败')
+  assert.equal(await readText(created), 'NEW', '中断时宁可少删（绝不因为没走完就当成「可以删」）')
+  const ws = rewind.segments.find((s) => s.state === 'workspace')
+  assert.equal(ws?.createdSkippedTruncated, true, '中断必须如实标 truncated，不谎报「已完整走查」')
+})
+
+