dsh-config-manager 0.2.3 → 0.3.0

package/src/core/analyzer.ts

@@ -10,11 +10,10 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { sha256Hex } from '../utils/hashing.ts';
-import { parseJsonSafe } from '../utils/json.ts';
 import {
   SECTION_FILE_PREFIXES, SECTION_IDS, SECTION_JSON_PATHS, isFileSection, validateSectionData,
 } from '../schema/config.ts';
-import { CHECKSUMS_FILE, MANIFEST_FILE, parseManifest } from '../schema/manifest.ts';
+import { MANIFEST_FILE, parseManifest } from '../schema/manifest.ts';
 import {
   CURRENT_SCHEMA_VERSION, canImport, describeVersion, isSupported, isTooNew, needsMigration,
 } from '../schema/versions.ts';
@@ -23,6 +22,8 @@ import type { BootSafetyReport } from './boot-safety.ts';
 import type { FilesSection, Manifest, SectionId } from '../schema/types.ts';
 import { loadTombstones } from '../schema/tombstones.ts';
 import { DEFAULT_SENSITIVE_RELS, restoreVaultFiles } from '../security/vault.ts';
+import { applyUnverifiedFileBlocks, scanArchiveIntegrity, unverifiedNoticeText } from '../security/unverified-file-blocks.ts';
+import { UNVERIFIED_FILE_ENTRY_CODE } from '../security/integrity.ts';
 import { createSnapshot, fsForSection, planItemWritesTarget, resolveFileTarget, resolveFileTargetRel } from './backup.ts';
 import { isCredentialConfigured } from './credential-status.ts';
 import { rollback } from './rollback.ts';
@@ -107,12 +108,15 @@ export interface AnalyzerOptions {
    * 缺省 = 不做会话格式体检（旧调用方零改动）。
    */
   sessionFormatProbe?: (files: readonly { relativePath: string; data: Uint8Array }[]) => SessionFormatProbeResult;
+  /** SEC-05：按分区豁免「表外条目阻断」（缺省空 = 严格）；判据见 security/unverified-file-blocks.ts */
+  extraEntryExemptSections?: readonly SectionId[];
 }
 
 interface Bundle {
   archive: ZipArchive;
   manifest: Manifest;
   checksums: { ok: boolean; mismatches: string[]; missing: string[] };
+  unverifiedEntries: string[];
   zipWarnings: string[];
   /** G-06：schema 迁移链实际执行的步骤告警（`import.migrated`；CURRENT=MIN=1 时恒为空） */
   migrationWarnings: string[];
@@ -227,6 +231,7 @@ export class Analyzer {
   private readonly parseZipFn: (buf: Uint8Array, limits?: ZipSafetyLimits) => ZipArchive;
   private readonly msg: MsgFunc;
   private readonly sessionFormatProbe?: (files: readonly { relativePath: string; data: Uint8Array }[]) => SessionFormatProbeResult;
+  private readonly extraEntryExemptSections: readonly string[];
   /**
    * 会话内 bundle 缓存（zipPath → { 身份, 解析结果 }）。
    *
@@ -250,6 +255,7 @@ export class Analyzer {
     this.parseZipFn = opts.parseZipOverride ?? parseZip;
     this.msg = opts.msg ?? msgOf(opts.ctx);
     this.sessionFormatProbe = opts.sessionFormatProbe;
+    this.extraEntryExemptSections = opts.extraEntryExemptSections ?? [];
   }
 
   /* ---------------- 第 1-6 步：ZIP 读入 → 安全解析 → manifest → 完整性 → schema ---------------- */
@@ -297,55 +303,12 @@ export class Analyzer {
       throw new Error(this.msg('import.manifestParseFailed', { reason: err instanceof Error ? err.message : String(err) }));
     }
 
-    // 4. 完整性（integrity/checksums.json 逐一 SHA-256）
+    // 4. 完整性（checksums.json 逐一 SHA-256）+ 4b 反向覆盖（表外条目）：判据下沉在 security 侧。
     const zipWarnings: string[] = [];
-    let checksums = { ok: true, mismatches: [] as string[], missing: [] as string[] };
-    // 4a. H2：校验表**缺失**或**为空**时，全部条目都处于「未登记 ⇒ 未被校验」状态。
-    //     此前整段完整性逻辑（含下面的反向检查）都嵌在 `if (archive.has(CHECKSUMS_FILE))` 内，
-    //     于是「剥掉 checksums.json」或「把它置为 {}」= 一个条目都不校验，却 valid=true / 零告警。
-    //     两种形态对用户是同一件事（没有任何条目被校验），故共用同一条告警，不制造近重复文案。
-    const table = archive.has(CHECKSUMS_FILE)
-      ? (parseJsonSafe(archive.readEntryText(CHECKSUMS_FILE)) as Record<string, string>)
-      : null;
-    if (table === null || Object.keys(table).length === 0) {
-      zipWarnings.push(this.msg('import.checksumsMissing'));
-    }
-    if (table !== null && Object.keys(table).length > 0) {
-      const entries = new Map<string, Uint8Array>();
-      for (const name of archive.names()) {
-        if (name === MANIFEST_FILE || name === CHECKSUMS_FILE) continue;
-        try {
-          // 异步解压：这是全仓**唯一**逐条解压全部条目的地方，`inflateRawSync` 会整段阻塞
-          // 事件循环（实测 29 MiB 归档 108 ms，大备份就是几秒的界面冻结）。判据与同步版逐字相同。
-          entries.set(name, await archive.readEntryAsync(name));
-        } catch {
-          entries.delete(name); // 损坏条目在完整性阶段即失败
-          checksums.ok = false;
-          checksums.mismatches.push(name);
-        }
-      }
-      const result = await verifyAgainstTable(entries, table);
-      checksums = result;
-      if (!checksums.ok) {
-        throw new Error(this.msg('import.integrityFailed', {
-          entries: [...checksums.mismatches, ...checksums.missing].map((m) => `"${m}"`).join(', '),
-        }));
-      }
-      // 4b. G-04：反向完整性——ZIP 内**不在**校验表里的条目（未登记 ⇒ 未被校验）。
-      //     verifyAgainstTable 只遍历表里的键，所以 ZIP 里多出的条目此前既不校验也不告知；
-      //     这里把它变成显式 warning（不阻断：未知 ZIP 条目不参与校验是格式 v1 的既定语义）。
-      //     排除 manifest.json / checksums.json 自身与目录条目（以 "/" 结尾）。
-      const tableKeys = new Set(Object.keys(table));
-      const extraEntries = archive.names().filter(
-        (name) => name !== MANIFEST_FILE && name !== CHECKSUMS_FILE
-          && !name.endsWith('/') && !tableKeys.has(name),
-      );
-      if (extraEntries.length > 0) {
-        zipWarnings.push(this.msg('import.extraEntries', {
-          entries: extraEntries.map((e) => `"${e}"`).join(', '),
-        }));
-      }
-    }
+    const integrity = await scanArchiveIntegrity(archive, this.msg);
+    if (integrity.failure !== undefined) throw new Error(integrity.failure);
+    zipWarnings.push(...integrity.warnings);
+    const { checksums, unverified } = integrity;
 
     // 5. schema 版本判定（集中）：过新（isTooNew）或过旧（低于 MIN_SUPPORTED）→ 一律硬失败（行为不变）
     if (isTooNew(manifest.schemaVersion) || !isSupported(manifest.schemaVersion)) {
@@ -371,7 +334,7 @@ export class Analyzer {
       }
     }
 
-    const bundle: Bundle = { archive, manifest, checksums, zipWarnings, migrationWarnings };
+    const bundle: Bundle = { archive, manifest, checksums, unverifiedEntries: unverified, zipWarnings, migrationWarnings };
     // 身份读得到才入实例缓存（与跨请求缓存同一判据：不拿未知身份签结果）。
     if (identity !== null) this.bundleCache.set(zipPath, { stamp: identity.stamp, bundle });
     // 写入跨请求缓存：execute（refresh）也写 —— 它刚做过完整校验，这份结果对后续只读入口同样有效。
@@ -584,6 +547,12 @@ export class Analyzer {
     // 会话格式体检只跑一次：告警、计划项标记、ImportAnalysis 摘要共用（探针要解首帧，别重复跑）。
     const sessionFormats = this.resolveSessionFormats(sections);
 
+    // SEC-05：会落盘的文件分区条目必须在校验表内（表外条目此前照样被原样写进目标目录）。
+    // 阻断结果就在计划项自己身上（kind:'Error' + description），不另存一份名单（单一事实）。
+    applyUnverifiedFileBlocks(
+      bundle.unverifiedEntries, adapterItems, this.fileCollectionIds(), this.extraEntryExemptSections, this.msg,
+    );
+
     return {
       ...bundle,
       sections,
@@ -629,7 +598,13 @@ export class Analyzer {
     const analyzed = await this.analyzeBundle(bundle);
 
     const errors = [...analyzed.adapterIssues];
-    const warnings = [...zipWarnings, ...bundle.migrationWarnings, ...analyzed.sectionWarnings];
+    // SEC-05：未覆盖条目（表外 + 校验表缺失时的全部文件分区条目）≠ 被篡改 —— 逐条 Error 已保证零写入，
+    // 不再把整包判死。全仓只此一条 warning（RV1-F11：与 scanArchiveIntegrity 的 import.extraEntries 合并）；
+    // 名单取**全部**未覆盖条目而非「被阻断」子集：豁免分区（历史包兼容）不阻断但仍必须被说出来。
+    const blockedCount = analyzed.adapterItems.filter((i) => i.detail === UNVERIFIED_FILE_ENTRY_CODE).length;
+    const unverifiedNotice = analyzed.unverifiedEntries.length > 0
+      ? [unverifiedNoticeText(this.msg, analyzed.unverifiedEntries, blockedCount)] : [];
+    const warnings = [...zipWarnings, ...bundle.migrationWarnings, ...analyzed.sectionWarnings, ...unverifiedNotice];
     warnings.push(...this.secretsPayloadWarnings(manifest, opts.decryptedCredentials));
     if (!canImport(manifest.schemaVersion)) {
       errors.push(this.msg('import.versionUnsupported', { version: describeVersion(manifest.schemaVersion) }));
@@ -1074,11 +1049,17 @@ export class Analyzer {
             message: outcome.executed.message ?? null,
           });
         }
-        // 仅硬失败计入 anyFailed（warning 属非致命：目标不可达等，不触发回滚，§34.17）
-        if (outcome.executed.status === 'failed') anyFailed = true;
+        // 仅硬失败计入 anyFailed（warning 属非致命：目标不可达等，不触发回滚，§34.17）。
+        // 「硬失败」= 真的尝试过写、并且失败了（applyOne/adapter 抛错、applyItem 返回 failed、写一半的
+        // 目标不可达）。执行前就被策略拦下的项（kind 'Error'：安全白名单 / SEC-05 未覆盖条目）**根本没
+        // 碰目标** —— 它连一个字节都没写，把它算成失败只会让 rollbackOnError（IE-02 缺省 true）在
+        // 「本来能导入的部分」上做一次整笔回滚，等于用安全策略制造数据损失；它也没留下半套状态可回滚。
+        // 因此这类预判阻断只记账（executed 里 status 'failed'，用户可见），不触发回滚、不中断后续条目。
+        const hardFailed = outcome.executed.status === 'failed' && item.kind !== 'Error';
+        if (hardFailed) anyFailed = true;
         if (outcome.needsRestart) needsRestart = true;
         if (outcome.warning) warnings.push(outcome.warning);
-        if (opts.rollbackOnError && outcome.executed.status === 'failed') break;
+        if (opts.rollbackOnError && hardFailed) break;
       }
       // 分区收尾（issue #45 ④）：会话位置护栏等必须等本分区全部写完才做的动作。
       // 「终止 + 回滚」例外：整笔马上要被回滚，再跑收尾纯属浪费且可能中途失败。
@@ -1493,7 +1474,7 @@ export class Analyzer {
 import {
   applyMappingsToSections, applyTombstoneFilter, buildCredentialPlanItems, detectPathIssues,
   mergePathMappings, rebaseMapping, reportRollbackToJournal, runSchemaMigration, sessionUnitVersion,
-  usableSecretValue, verifyAgainstTable,
+  usableSecretValue,
 } from './import-planning.ts';
 
 // 对外导入面保持不变（core/index.ts 与既有测试按 './analyzer.ts' 取这三个名字）。

package/src/core/backup.test.ts

@@ -29,7 +29,12 @@ import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 
-import { FileSnapshotStore, createSnapshot, normalizeDshVersion, resolveFileTarget, verifySnapshot } from './backup.ts';
+import {
+  FileSnapshotStore, PRE_RESTORE_KEEP_ATTEMPTS, PRE_RESTORE_KEEP_DAYS,
+  createSnapshot, normalizeDshVersion, resolveFileTarget, verifySnapshot,
+} from './backup.ts';
+import type { PrunePlan } from './backup.ts';
+import { existsSync } from 'node:fs';
 import { rollback } from './rollback.ts';
 import { makeContext, MemSnapshotStore } from '../adapters/test-helpers.ts';
 import type { ImportPlan, Snapshot, SnapshotStore } from './types.ts';
@@ -461,3 +466,136 @@ test('mcp 连接器：storages/mcp_connector.json 进快照为整文件条目，
   assert.deepEqual(report.restored, ['mcp:' + rel], '回滚必须报告真正被还原的那一条');
   assert.equal(new TextDecoder().decode(await ctx.fs.readFile(abs)), original);
 });
+
+/* ---------------- BK-05：prune 不得销毁反悔副本（pre-restore） ----------------
+ *
+ * 反悔副本 = 恢复链路在覆盖/删除前落的原文副本：<snapshotsDir>/<snapshotId>/pre-restore/<attempt>/（restore.ts:888）。
+ * 此前 prune 用 fs.rm(<snapshotsDir>/<id>, { recursive: true }) 整目录删 ⇒ 快照一被淘汰，用户最后一次
+ * 「反悔」的原文就跟着消失，而那份字节是**唯一**的（不在 blobs 里、不进同步、不进导出）。
+ * 现在的口径：快照本体照常回收，pre-restore 子树留下；它有自己的保留策略（数量 + 天数），
+ * 且删除前先把「要删什么」回调出去（onPrunePlan），不先删后报。
+ */
+
+/** 与 restore.ts 的 preRestoreStamp 同格式（本地时间 yyyyMMdd-HHmmss-SSS）。 */
+function stamp(date: Date): string {
+  const p = (n: number, width = 2): string => String(n).padStart(width, '0');
+  return p(date.getFullYear(), 4) + p(date.getMonth() + 1) + p(date.getDate())
+    + '-' + p(date.getHours()) + p(date.getMinutes()) + p(date.getSeconds())
+    + '-' + p(date.getMilliseconds(), 3);
+}
+
+async function plantPreRestore(
+  dir: string,
+  snapshotId: string,
+  attempt: string,
+  files: Record<string, string>,
+): Promise<string> {
+  const pre = path.join(dir, snapshotId, 'pre-restore', attempt);
+  await fs.mkdir(pre, { recursive: true });
+  for (const [name, body] of Object.entries(files)) await fs.writeFile(path.join(pre, name), body, 'utf8');
+  return pre;
+}
+
+test('BK-05/①：prune 淘汰旧快照时保留 pre-restore 反悔副本（原文逐字节还在），删什么先落计划', async (t) => {
+  const dir = await tmpDir(t, 'prune-prerestore');
+  const { ctx } = countingCtx();
+  await seedHostFiles(ctx);
+  const plans: PrunePlan[] = [];
+  /** 计划回调里快照本体还在吗 —— 证明「先出清单，再删」而不是删完再编 */
+  let snapshotJsonAliveAtPlanTime: boolean | null = null;
+  const store = new FileSnapshotStore({
+    dir,
+    retentionPolicy: () => ({ keepLast: 1, keepMonthly: 0, keepYearly: 0 }),
+    onPrunePlan: (plan) => {
+      plans.push(plan);
+      if (plan.removeSnapshots.length > 0) {
+        snapshotJsonAliveAtPlanTime = existsSync(path.join(dir, plan.removeSnapshots[0]!, 'snapshot.json'));
+      }
+    },
+  });
+
+  const first = await createSnapshot({ ctx, plan: emptyPlan(), sourceZip: 'unit.zip', store, adapters: [] });
+  const attempt = stamp(new Date());
+  const pre = await plantPreRestore(dir, first.id, attempt, { '0001-settings.yaml': 'old-settings' });
+  const second = await createSnapshot({ ctx, plan: emptyPlan(), sourceZip: 'unit.zip', store, adapters: [] });
+
+  // 快照本体照常回收（否则保留清理等于失效）
+  await assert.rejects(fs.readFile(path.join(dir, first.id, 'snapshot.json'), 'utf8'), '旧快照的 snapshot.json 必须删掉');
+  await assert.rejects(fs.stat(path.join(dir, first.id, 'blobs')), '旧快照的 blobs 必须回收');
+  // 反悔副本一字不差
+  assert.equal(await fs.readFile(path.join(pre, '0001-settings.yaml'), 'utf8'), 'old-settings', '反悔副本必须原样保留');
+  assert.equal(existsSync(path.join(dir, second.id, 'snapshot.json')), true);
+
+  const plan = plans.at(-1)!;
+  assert.deepEqual(plan.removeSnapshots, [first.id], '计划里必须有「要删哪个快照」');
+  assert.ok(plan.keepPreRestoreFor.includes(first.id), '因反悔副本而不整目录删的快照要如实列出：' + JSON.stringify(plan));
+  assert.ok(plan.paths.includes(first.id + '/snapshot.json'), '计划要含具体路径（审计「到底删了什么」）：' + JSON.stringify(plan.paths));
+  assert.equal(snapshotJsonAliveAtPlanTime, true, '计划必须在真正删除**之前**给出');
+});
+
+test('BK-05/②：反悔副本自有保留策略 —— 每次恢复一个 attempt，只留最新 5 个', async (t) => {
+  const dir = await tmpDir(t, 'prune-prerestore-count');
+  const { ctx } = countingCtx();
+  await seedHostFiles(ctx);
+  const plans: PrunePlan[] = [];
+  const store = new FileSnapshotStore({ dir, onPrunePlan: (plan) => { plans.push(plan) } });
+  const snap = await createSnapshot({ ctx, plan: emptyPlan(), sourceZip: 'unit.zip', store, adapters: [] });
+
+  // 7 个 attempt（时间递增；每个 attempt 只装它那一次被覆盖的文件）
+  const base = Date.now() - 6 * 60 * 60 * 1000;
+  const names: string[] = [];
+  for (let i = 0; i < 7; i += 1) {
+    const name = stamp(new Date(base + i * 60 * 60 * 1000));
+    names.push(name);
+    await plantPreRestore(dir, snap.id, name, { '0001-settings.yaml': 'v' + i });
+  }
+  await store.pruneNow();
+
+  const left = (await fs.readdir(path.join(dir, snap.id, 'pre-restore'))).sort();
+  assert.deepEqual(left, names.slice(-PRE_RESTORE_KEEP_ATTEMPTS).sort(), '只留最新 ' + PRE_RESTORE_KEEP_ATTEMPTS + ' 个 attempt');
+  const plan = plans.at(-1)!;
+  const dropped = plan.dropPreRestore.map((d) => d.attempt).sort();
+  assert.deepEqual(dropped, names.slice(0, names.length - PRE_RESTORE_KEEP_ATTEMPTS).sort(), '被删的 attempt 必须逐条进计划');
+  assert.ok(plan.dropPreRestore.every((d) => d.reason === 'count'));
+  assert.ok(plan.dropPreRestore.every((d) => d.files === 1), '计划要带文件数（用户能看出删了多少）');
+  assert.equal(existsSync(path.join(dir, snap.id, 'snapshot.json')), true, '活着的快照本体绝不能被这轮清理碰到');
+});
+
+test('BK-05/③：反悔副本超过保留天数 → 删；近期的不动', async (t) => {
+  const dir = await tmpDir(t, 'prune-prerestore-age');
+  const { ctx } = countingCtx();
+  await seedHostFiles(ctx);
+  const plans: PrunePlan[] = [];
+  const store = new FileSnapshotStore({ dir, onPrunePlan: (plan) => { plans.push(plan) } });
+  const snap = await createSnapshot({ ctx, plan: emptyPlan(), sourceZip: 'unit.zip', store, adapters: [] });
+
+  const oldAttempt = stamp(new Date(Date.now() - (PRE_RESTORE_KEEP_DAYS + 5) * 24 * 60 * 60 * 1000));
+  const freshAttempt = stamp(new Date(Date.now() - 60 * 60 * 1000));
+  await plantPreRestore(dir, snap.id, oldAttempt, { '0001-settings.yaml': 'ancient' });
+  await plantPreRestore(dir, snap.id, freshAttempt, { '0001-settings.yaml': 'fresh' });
+  await store.pruneNow();
+
+  const left = (await fs.readdir(path.join(dir, snap.id, 'pre-restore'))).sort();
+  assert.deepEqual(left, [freshAttempt], '超过 ' + PRE_RESTORE_KEEP_DAYS + ' 天的反悔副本该按天数淘汰');
+  assert.deepEqual(
+    plans.at(-1)!.dropPreRestore.map((d) => ({ attempt: d.attempt, reason: d.reason })),
+    [{ attempt: oldAttempt, reason: 'over-age' }],
+  );
+});
+
+test('BK-05/④：反悔副本全部过期后不留空壳目录（快照已不在 ⇒ 目录一起收掉）', async (t) => {
+  const dir = await tmpDir(t, 'prune-prerestore-shell');
+  const { ctx } = countingCtx();
+  await seedHostFiles(ctx);
+  const store = new FileSnapshotStore({
+    dir,
+    retentionPolicy: () => ({ keepLast: 1, keepMonthly: 0, keepYearly: 0 }),
+  });
+  const first = await createSnapshot({ ctx, plan: emptyPlan(), sourceZip: 'unit.zip', store, adapters: [] });
+  const oldAttempt = stamp(new Date(Date.now() - (PRE_RESTORE_KEEP_DAYS + 1) * 24 * 60 * 60 * 1000));
+  await plantPreRestore(dir, first.id, oldAttempt, { '0001-settings.yaml': 'ancient' });
+  await createSnapshot({ ctx, plan: emptyPlan(), sourceZip: 'unit.zip', store, adapters: [] });
+
+  assert.equal(existsSync(path.join(dir, first.id)), false, '快照没了 + 反悔副本也过期 ⇒ 不留空壳');
+});
+

package/src/core/backup.ts

@@ -593,6 +593,53 @@ export type PruneSelector = (
 export const fallbackPruneSelector: PruneSelector = (metas, policy) =>
   selectPruneCandidates(metas, policy.keepLast);
 
+/* ---------------- BK-05：反悔副本（pre-restore）保留策略 ----------------
+ *
+ * 反悔副本 = 恢复链路在覆盖/删除前落的原文副本（restore.ts:888 起写 <snapshotDir>/pre-restore/<attempt>/）。
+ * 它与快照本体的生命周期**不是一回事**：本体可以按保留策略回收（历史回滚点），
+ * 反悔副本却是用户「把刚才这次恢复撤回去」的最后一份原文，整条链路上没有第二份
+ * （不在 blobs 里、不进同步、不进导出）。所以两套策略分开：
+ *  - 快照本体：既有 RetentionPolicyLike（宿主可注入 GFS）；
+ *  - 反悔副本：只按「份数 + 天数」淘汰，常量在 core 内固定（无宿主可调项 —— 少了它等于没有反悔能力）。
+ */
+export const PRE_RESTORE_KEEP_ATTEMPTS = 5;
+export const PRE_RESTORE_KEEP_DAYS = 30;
+/** 反悔副本目录名（restore.ts 写入侧同一常量值；这里是读侧，绝不与写侧分叉） */
+const PRE_RESTORE_DIR_NAME = 'pre-restore';
+
+/** 解析反悔副本 attempt 目录名里的时间戳（本地时间 yyyyMMdd-HHmmss-SSS，可选 -N 去重后缀）。 */
+function parsePreRestoreStamp(name: string): number | null {
+  const m = /^(\d{4})(\d{2})(\d{2})-(\d{2})(\d{2})(\d{2})-(\d{3})(?:-\d+)?$/.exec(name);
+  if (m === null) return null;
+  const at = new Date(
+    Number(m[1]), Number(m[2]) - 1, Number(m[3]),
+    Number(m[4]), Number(m[5]), Number(m[6]), Number(m[7]),
+  ).getTime();
+  return Number.isFinite(at) ? at : null;
+}
+
+/** 一条反悔副本 attempt 的淘汰计划（删除**前**就进 PrunePlan，供审计与界面展示）。 */
+export interface PrunePreRestoreDrop {
+  snapshotId: string;
+  attempt: string;
+  /** count = 超出份数上限；over-age = 超过保留天数 */
+  reason: 'count' | 'over-age';
+  /** 该 attempt 目录里的文件数（用户能看出「删了多少份原文」） */
+  files: number;
+}
+
+/** 一轮保留清理的**计划**（在真正 rm 之前回调出去；也是 pruneNow 的返回值）。 */
+export interface PrunePlan {
+  /** 将回收的快照 id（目录内的快照本体，不含 pre-restore 子树） */
+  removeSnapshots: string[];
+  /** 因存在反悔副本而**不**整目录删的快照 id（只删本体内容、留下 pre-restore/） */
+  keepPreRestoreFor: string[];
+  /** 反悔副本 attempt 级淘汰计划 */
+  dropPreRestore: PrunePreRestoreDrop[];
+  /** 计划删除的具体路径（相对快照根、'/' 分隔；审计「到底删了什么」） */
+  paths: string[];
+}
+
 export interface FileSnapshotStoreOptions {
   /** 快照根目录（宿主决定，如 ~/.dsh/dsh-config-manager/snapshots） */
   dir: string;
@@ -608,6 +655,8 @@ export interface FileSnapshotStoreOptions {
    * 缺省 = 不记录（不改变 prune 行为、不污染核心引擎）。
    */
   onPrune?: (removedIds: string[]) => void;
+  /** BK-05：保留清理的**计划**回调（在真正删除之前，best-effort；抛错不影响清理） */
+  onPrunePlan?: (plan: PrunePlan) => void;
   /**
    * m-retention：快照保留策略提供者（GFS 分层；可配置）。
    * 缺省 = `SNAPSHOT_RETENTION_LIMIT`（= 既有的「保留最近 10 个」，行为不变）。
@@ -722,7 +771,8 @@ export class FileSnapshotStore implements SnapshotStore {
  *  自动淘汰，只能手动删除（deleteSnapshot）。
  *  Phase 4 F3：被 active/quarantine 未收敛 journal 引用的 snapshot（recovery 回滚点）
  *  必须豁免——引用提供者（referencedSnapshotIds）返回的 id 绝不自动清理。 */
-  private async prune(): Promise<void> {
+  private async prune(): Promise<PrunePlan> {
+    const emptyPlan: PrunePlan = { removeSnapshots: [], keepPreRestoreFor: [], dropPreRestore: [], paths: [] };
     const dir = this.options.dir;
     const entries = await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
     // F3：被未收敛 journal 引用的快照**绝不自动清理**。判据是「读不到 ≠ 没有引用」——
@@ -734,7 +784,7 @@ export class FileSnapshotStore implements SnapshotStore {
         referenced = await this.options.referencedSnapshotIds();
       } catch (err) {
         this.options.onWarn?.(engineMsg('core.backup.pruneAbandoned', { reason: err instanceof Error ? err.message : String(err) }));
-        return;
+        return emptyPlan;
       }
     }
     // m-retention：策略读取失败 → 回退缺省（绝不因策略提供者异常而误删/崩溃）
@@ -762,17 +812,108 @@ export class FileSnapshotStore implements SnapshotStore {
         // 损坏 / 非快照目录：跳过（与 listSnapshots 语义一致）
       }
     }
-    const removedIds: string[] = [];
+    // --- BK-05：先出计划，再删 ---
+    // 快照本体与反悔副本是两套生命周期：本体按保留策略回收，pre-restore 按「份数 + 天数」淘汰。
+    // 计划必须在 rm **之前**成型并回调出去——删完再报等于审计拿不到原始状态。
+    const plan: PrunePlan = {
+      removeSnapshots: [],
+      keepPreRestoreFor: [],
+      dropPreRestore: await this.collectPreRestorePlan(),
+      paths: [],
+    };
+    /** 每个待回收快照：目录名 → 要删的子项（保持 pre-restore 不动） */
+    const removals: { id: string; children: string[]; hasPre: boolean }[] = [];
     for (const id of selector(metas, policy)) {
       const target = path.join(dir, id);
       if (!target.startsWith(dir)) continue; // 越界 id 跳过（不删、不抛，同 save/readBlob 包含性约定）
+      const children = await fs.readdir(target).catch(() => [] as string[]);
+      const hasPre = children.includes(PRE_RESTORE_DIR_NAME);
+      removals.push({ id, children, hasPre });
+      plan.removeSnapshots.push(id);
+      for (const child of children) {
+        if (child === PRE_RESTORE_DIR_NAME) continue;
+        plan.paths.push(id + '/' + child);
+      }
+    }
+    for (const drop of plan.dropPreRestore) plan.paths.push(drop.snapshotId + '/pre-restore/' + drop.attempt + '/');
+    this.options.onPrunePlan?.(plan);
+    if (plan.removeSnapshots.length === 0 && plan.dropPreRestore.length === 0) return plan;
+
+    // 1) 回收快照本体：有反悔副本的快照**不整目录删**（否则唯一那份原文跟着消失），逐项删其余内容
+    const removedIds: string[] = [];
+    for (const removal of removals) {
+      const target = path.join(dir, removal.id);
+      for (const child of removal.children) {
+        if (child === PRE_RESTORE_DIR_NAME) continue;
+        await fs.rm(path.join(target, child), { recursive: true, force: true });
+      }
+      if (removal.hasPre) plan.keepPreRestoreFor.push(removal.id);
+      else await fs.rm(target, { recursive: true, force: true });
+      removedIds.push(removal.id);
+    }
+    // 2) 反悔副本 attempt 级淘汰（份数超限 / 超过保留天数）
+    for (const drop of plan.dropPreRestore) {
+      await fs.rm(path.join(dir, drop.snapshotId, PRE_RESTORE_DIR_NAME, drop.attempt), { recursive: true, force: true });
+    }
+    // 3) 收尾：快照本体已回收（无 snapshot.json）且反悔副本也空了 ⇒ 不留空壳目录
+    const touched = new Set<string>([...plan.keepPreRestoreFor, ...plan.dropPreRestore.map((d) => d.snapshotId)]);
+    for (const id of touched) {
+      const target = path.join(dir, id);
+      const hasSnapshot = await fs.stat(path.join(target, 'snapshot.json')).catch(() => null) !== null;
+      if (hasSnapshot) continue;
+      const left = await fs.readdir(path.join(target, PRE_RESTORE_DIR_NAME)).catch(() => null);
+      if (left !== null && left.length > 0) continue;
       await fs.rm(target, { recursive: true, force: true });
-      removedIds.push(id);
     }
     // Phase 6：自动保留清理历史回调（best-effort；不改变 prune 行为）
     if (removedIds.length > 0) {
       try { this.options.onPrune?.(removedIds); } catch { /* 历史回调失败不阻断 */ }
     }
+    return plan;
+  }
+
+  /**
+   * BK-05：反悔副本（pre-restore）淘汰计划 —— 只看**份数与天数**，与快照本体的保留策略无关。
+   *
+   * 为什么单独一套：快照本体是「历史回滚点」，可被 GFS 策略批量回收；反悔副本是用户把
+   * 刚才那次恢复撤回去的**唯一**原文（不在 blobs、不进同步、不进导出），它只需要「别无限长」，
+   * 不需要也不该受 keepLast/keepMonthly 影响 —— 否则一次批量淘汰会把最近几次恢复的反悔点一起抹掉。
+   * attempt 名即恢复时间戳（restore.ts 的 preRestoreStamp，本地时间 yyyyMMdd-HHmmss-SSS[-序号]）；
+   * 解析不出来回落目录 mtime（手工改名的残留也能被淘汰，不会永久占位）。
+   */
+  private async collectPreRestorePlan(): Promise<PrunePreRestoreDrop[]> {
+    const dir = this.options.dir;
+    const drops: PrunePreRestoreDrop[] = [];
+    const now = Date.now();
+    const maxAgeMs = PRE_RESTORE_KEEP_DAYS * 24 * 60 * 60 * 1000;
+    for (const entry of await fs.readdir(dir, { withFileTypes: true }).catch(() => [])) {
+      if (!entry.isDirectory()) continue;
+      const preRoot = path.join(dir, entry.name, PRE_RESTORE_DIR_NAME);
+      const attempts = await fs.readdir(preRoot, { withFileTypes: true }).catch(() => null);
+      if (attempts === null) continue;
+      const rows: { attempt: string; at: number; files: number }[] = [];
+      for (const a of attempts) {
+        if (!a.isDirectory()) continue;
+        const at = parsePreRestoreStamp(a.name)
+          ?? (await fs.stat(path.join(preRoot, a.name)).then((s) => s.mtimeMs).catch(() => now));
+        const names = await fs.readdir(path.join(preRoot, a.name), { recursive: true }).catch(() => [] as string[]);
+        rows.push({ attempt: a.name, at, files: names.length });
+      }
+      rows.sort((x, y) => y.at - x.at); // 新 → 旧
+      rows.forEach((row, index) => {
+        if (index >= PRE_RESTORE_KEEP_ATTEMPTS) {
+          drops.push({ snapshotId: entry.name, attempt: row.attempt, reason: 'count', files: row.files });
+        } else if (now - row.at > maxAgeMs) {
+          drops.push({ snapshotId: entry.name, attempt: row.attempt, reason: 'over-age', files: row.files });
+        }
+      });
+    }
+    return drops;
+  }
+
+  /** BK-05：手动触发一轮保留清理（与 save 后的自动清理同一实现）。 */
+  async pruneNow(): Promise<PrunePlan> {
+    return this.prune();
   }
 
   async load(id: string): Promise<Snapshot> {

package/src/core/import-defaults.ts

@@ -0,0 +1,13 @@
+/**
+ * 导入执行策略的**唯一缺省**（IE-02）。
+ *
+ * 为什么单独一个零依赖模块：这个缺省必须被四处引用 —— 引擎 `src/core/importer.ts`、
+ * HTTP 路由 `src/routes/import.ts`、UI 向导 `src/ui/import-wizard.ts`、同步通道
+ * `src/sync/sync-engine.ts`。而 `src/ui/import-wizard.ts` 会被 `src/client/run-store.ts`
+ * 作为**值**导入并打进浏览器 bundle，所以它不能从 `src/core/importer.ts` 取这个值
+ * （那条路径经 Analyzer 拖进 node 内建与 ZIP 依赖）。本文件零依赖，两端都能安全引入。
+ *
+ * 语义：任一计划项失败立即整体回滚（安全侧，也就是 UI 文案「失败时整体回滚（推荐）」）。
+ * 要「单项失败如实记录并继续其余项」必须显式传 `false`，不再靠各入口各写一份缺省。
+ */
+export const DEFAULT_ROLLBACK_ON_ERROR = true;

package/src/core/importer.ts

@@ -11,6 +11,13 @@
 import type { ZipArchive, ZipSafetyLimits } from '../utils/zip.ts';
 import type { MsgFunc } from './messages.ts';
 import { Analyzer } from './analyzer.ts';
+import { DEFAULT_ROLLBACK_ON_ERROR } from './import-defaults.ts';
+
+/**
+ * 缺省值的规范定义在 `./import-defaults.ts`（零依赖，UI 向导与浏览器 bundle 也引入它）；
+ * 这里再导出一份，宿主侧调用方（路由、同步通道、CLI）可以从引擎门面拿，不必记两个路径。
+ */
+export { DEFAULT_ROLLBACK_ON_ERROR };
 import type { PlanItemProgress } from './analyzer.ts';
 import type { BootSafetyReport } from './boot-safety.ts';
 import type {
@@ -41,7 +48,10 @@ export interface ExecuteOptions {
   secretInputs?: Record<string, string>;
   /** 加密备份解密结果（仅内存；解密必须经 m4 encryption provider） */
   decryptedCredentials?: Map<string, string>;
-  /** 任一项失败立即整体回滚（默认 false：单项失败如实记录并继续其余项） */
+  /**
+   * 任一项失败立即整体回滚。缺省 = `DEFAULT_ROLLBACK_ON_ERROR`（`./import-defaults.ts`，全仓唯一一份）；
+   * 要「单项失败如实记录并继续其余项」必须显式传 `false`。
+   */
   rollbackOnError?: boolean;
   /** m1：每完成一个计划项的进度回调（透传给 Analyzer；不传则无埋点） */
   onItem?: (info: PlanItemProgress) => void;
@@ -97,7 +107,7 @@ export class Importer {
       confirm: opts.confirm,
       secretInputs: opts.secretInputs,
       decryptedCredentials: opts.decryptedCredentials,
-      rollbackOnError: opts.rollbackOnError,
+      rollbackOnError: opts.rollbackOnError ?? DEFAULT_ROLLBACK_ON_ERROR,
       onItem: opts.onItem,
       onItemStart: opts.onItemStart,
       onLog: opts.onLog,