@xiaoyuyu6420/dsh-backup 0.13.1 → 0.13.3

package/lib/index.js

@@ -47,6 +47,7 @@ import { mkdir, open, copyFile, chmod, readdir, readFile, rename, rm, stat as fs
 import { createRequire } from 'node:module';
 import { hostname } from 'node:os';
 import { basename, dirname, join } from 'node:path';
+import { StringDecoder } from 'node:string_decoder';
 import { fileURLToPath } from 'node:url';
 import * as zlib from 'node:zlib';
 import { defineTool } from '@deepseek-ai/dsh-tools';
@@ -59,8 +60,18 @@ export const inject = ['subprocess', 'commands', 'timer', 'tools'];
 
 /** Windows 无 POSIX chmod 语义（用户目录 ACL 默认私有）。 */
 const IS_WIN = process.platform === 'win32';
-/** sha256 回退路径（node:fs 读取 + node:crypto）的内存上限。 */
+/** 深度校验（会话日志整读入内存）的体积上限；sha256 流式回退不适用此限。 */
 const HASH_MAX_BYTES = 256 * 1024 * 1024;
+/** 流式 sha256 的分块大小（4MB ≈ 每块几毫秒 CPU，块间让出事件循环）。 */
+const HASH_CHUNK_BYTES = 4 * 1024 * 1024;
+/**
+ * 启动宽限期：插件装配后头 45 秒不启动任何重活（全量 tar/gzip + 哈希要几分钟）。
+ * 宿主自己的 boot 预算按 30s 计（#103：DSH Desktop 的 HostRpc 30s 超时），
+ * 启动期补跑全量备份会抢 CPU/IO 把宿主 boot 拖超时，进而被判失败强杀。
+ */
+const AUTO_BOOT_GRACE_MS = 45_000;
+/** 自动备份失败后同会话内的重试间隔（只重试一次，避免失败热循环烧 CPU）。 */
+const AUTO_RETRY_MS = 30 * 60_000;
 /** GitHub 单个文件 100MB 上限，留 10MB 余量。 */
 const MAX_GITHUB_BYTES = 90 * 1024 * 1024;
 /** 同步工作树目录名（位于备份目录下）。 */
@@ -77,6 +88,8 @@ const DOWNLOAD_PREFIX = '/backup-download';
 const SENSITIVE_DEFAULTS = ['.credentials.yaml', '.env', 'qq-bridge/config.json'];
 /** 备份目录下保存明文敏感文件的子目录（随备份刷新为最新一份的副本）。 */
 const VAULT_DIR = 'vault';
+/** vault 下存放「凭据旧布局存底」的子目录：跨升级的长效安全网，备份刷新时不得删除。 */
+const PRESERVED_DIR = 'preserved';
 
 /**
  * 分类型备份的内容类型表（相对 ~/.dsh 根的 POSIX 路径）。
@@ -94,7 +107,6 @@ const BACKUP_TYPES = Object.freeze({
   settings: { label: '设置', paths: ['settings.yaml'] },
   profiles: { label: '插件 profiles', paths: ['profiles'] },
 });
-const BACKUP_TYPE_KEYS = Object.freeze(Object.keys(BACKUP_TYPES));
 /** 分类型归档前缀（与全量 dsh- 区分：独立轮换、不进全量列表、旧版插件不可见不误删）。 */
 const TYPED_PREFIX = 'dsh-t-';
 
@@ -297,17 +309,36 @@ const DEFAULTS = Object.freeze({
 /**
  * 解析 settings 命名空间的 schema，同时定义默认值。
  * Base 层：pluginConfig（cordis.patch.yml，插件级或 profile 级）。
- * User 层：Settings 面板运行时编辑，持久化到 settings.yaml。
+ * User 层：Settings 面板运行时编辑（0.1.6 及更早持久化到 settings.yaml；
+ * 0.1.7 起由宿主写入 profile 覆盖层）。
+ *
+ * **两代模型共用这一份**：
+ *  - ≤0.1.6-alpha.1：`ctx.settings.register(NS, SCHEMA)` 自注册命名空间；
+ *  - ≥0.1.7（含 0.2.0）：`register` 被移除，宿主改从「条目的 Config schema」
+ *    派生表单，且只认**标了 volatile 的字段**（宿主 dsh-settings 的
+ *    `volatileForm` 仅当 `meta.volatile` 存在才纳入表单）。故此处导出 Config
+ *    并逐字段标注 volatile。
+ *
+ * `volatileField` 做运行时探测：老载体（@deepseek-ai/schemastery < 3.18.4）
+ * 没有 `.volatile()`，探测失败就原样返回——老宿主走 register 路径，不需要它。
+ * 这样同一份代码在 0.1.1 → 0.2.0 全列车都能装配，不会因新 API 缺失而崩在装载期。
  */
+const volatileField = (schema) => (typeof schema.volatile === 'function' ? schema.volatile() : schema);
+
 const SCHEMA = z.object({
-  destination: z.string().default(DEFAULTS.destination),
-  keep: z.number().min(0).default(0),
-  exclude: z.array(z.string()).default(DEFAULTS.exclude),
-  redact: z.union([z.array(z.string()), 'off']).default(DEFAULTS.redact),
-  githubRepo: z.string().default(DEFAULTS.githubRepo),
-  updateCheck: z.boolean().default(DEFAULTS.updateCheck),
+  destination: volatileField(z.string().default(DEFAULTS.destination)),
+  keep: volatileField(z.number().min(0).default(0)),
+  exclude: volatileField(z.array(z.string()).default(DEFAULTS.exclude)),
+  // 'none' 是 v0.6 时代写法（代码里映射为 'off'）：schema 收下它，别让老配置
+  // 在新宿主的条目校验里被拒。
+  redact: volatileField(z.union([z.array(z.string()), 'off', 'none']).default(DEFAULTS.redact)),
+  githubRepo: volatileField(z.string().default(DEFAULTS.githubRepo)),
+  updateCheck: volatileField(z.boolean().default(DEFAULTS.updateCheck)),
 });
 
+/** 宿主装载条目时读取的 Config schema（0.1.7+ 的设置表单来源）。 */
+export const Config = SCHEMA;
+
 const SETTINGS_FIELDS = ['destination', 'keep', 'exclude', 'redact', 'githubRepo', 'updateCheck'];
 
 /** 校验并归一化单个字段到 `out`；非法值忽略。 */
@@ -488,7 +519,7 @@ class BackupPanelService extends TypertRemoteService {
     return this.ops.doctorRepair(selector, signal);
   }
 
-  /** 迁移预检：只读扫描全部会话日志（含 v1/v2/v3 各代），预测升级后哪些会话打不开。 */
+  /** 迁移预检：只读扫描全部会话日志（v0 起各代，按文件名代判定），预测升级后哪些会话打不开。 */
   migrateCheck(signal) {
     return this.ops.migrateCheck(signal);
   }
@@ -515,7 +546,13 @@ export function apply(ctx, pluginConfig) {
   let settingsService;
   ctx.inject(['settings'], (sctx) => {
     settingsService = sctx.settings;
-    settingsService.register(NS, SCHEMA, { base: resolveBase(pluginConfig) });
+    // 0.1.7 起宿主移除了 settings.register（新模型改由「profile 条目自带的
+    // Config schema」派生表单）；旧宿主（≤0.1.6-alpha.1）仍走自注册命名空间。
+    // 两级都留：有 register 就注册，没有就跳过——请求侧按「命名空间缺失」显式
+    // 降级，而不是在装配期抛错（旧实现在新宿主上是静默 TypeError）。
+    if (typeof settingsService.register === 'function') {
+      settingsService.register(NS, SCHEMA, { base: resolveBase(pluginConfig) });
+    }
     // detach 清理：服务中途 dispose 时置空，resolvedConfig() 自动降级到 pluginConfig
     return () => { settingsService = undefined; };
   });
@@ -574,10 +611,16 @@ export function apply(ctx, pluginConfig) {
 
   // ---------- 工具函数 ----------
   /**
-   * 读取 subprocess 收集的输出流。dsh-subprocess 的收集契约：输出超过
-   * maxBytes（8192）时内存窗口只保留尾部（readFrom 返回 lossy: true），
-   * 完整输出 spill 到 spillPath——restore 的 `tar -tvzf` 校验清单必须看
-   * 全量，否则大归档的校验可被清单前段的恶意条目绕过（8KB 尾窗看不到）。
+   * 读取 subprocess 收集的输出流（诊断/小输出用）。dsh-subprocess 的收集契约：
+   * 输出超过 maxBytes（8192）时内存窗口只保留尾部（readFrom 返回 lossy: true），
+   * 完整输出 spill 到 spillPath。
+   *
+   * ⚠️ **不要用它读体积不可控、且结果参与安全判定的输出**（#119）：spill 自身还有
+   * 上限，宿主对超过上限的流会**丢弃 spill 文件**（`discardSpill()`），此时
+   * `readFrom` 只给内存尾窗、`lossy: true` 且**没有 spillPath**——旧实现把这段
+   * 截断文本原样返回，`tar -tvzf` 校验清单因此把"断在文件名中间的碎片"当成不安全
+   * 条目，整包被拒绝恢复（备份成功、verify 报完整、面板正常列出，只在恢复时炸）。
+   * 这类输出请走 {@link streamListingLines}（原始流逐行消费，无上限）。
    */
   async function collectOutput(col) {
     const read = col?.readFrom(0);
@@ -592,6 +635,65 @@ export function apply(ctx, pluginConfig) {
     return read.text ?? '';
   }
 
+  /**
+   * 逐行消费一条命令的 stdout（`stdio: 'pipe'` 原始流形态），把每一行交给
+   * `onLine`；`onLine` 返回 false 时立即终止子进程并提前返回（"发现违规就不必读完"）。
+   *
+   * 为什么不用有界收集（#119）：见 {@link collectOutput} 的 ⚠️。这里内存只保留
+   * "尚未收尾的一行"，清单多大都不截断，也不会把碎片当成一行；stderr 仍走有界
+   * 收集（只作诊断，几 KB 足够）。
+   */
+  async function streamListingLines(argv, cwd, signal, onLine) {
+    const proc = ctx.subprocess.spawn({
+      argv,
+      cwd,
+      graceMs: 5000,
+      signal,
+      stdio: { stdin: 'ignore', stdout: 'pipe', stderr: { maxBytes: 8192, spill: { maxBytes: 1 << 20 } } },
+    });
+    const stream = proc.stdout;
+    if (!stream) throw new Error('宿主未提供原始输出流（subprocess stdout:"pipe" 不可用）——请升级宿主后重试');
+    // 单行长度的护栏：tar -tv 的一行正常不过几百字节；给足余量后仍设上限，
+    // 避免被构造出的超长名字把 carry 撑成内存炸弹。
+    const MAX_LINE_BYTES = 16 * 1024 * 1024;
+    const decoder = new StringDecoder('utf8');
+    let bytes = 0;
+    let lines = 0;
+    let carry = '';
+    let stopped = false;
+    for await (const chunk of stream) {
+      bytes += chunk.length;
+      carry += decoder.write(chunk);
+      let idx;
+      while ((idx = carry.indexOf('\n')) >= 0) {
+        const line = carry.slice(0, idx);
+        carry = carry.slice(idx + 1);
+        lines += 1;
+        if (onLine(line) === false) { stopped = true; break; }
+      }
+      if (stopped) break;
+      if (carry.length > MAX_LINE_BYTES) throw new Error(`输出单行超过 ${MAX_LINE_BYTES} 字节上限——拒绝继续解析`);
+    }
+    if (stopped) {
+      proc.terminate();
+    } else {
+      carry += decoder.end();
+      if (carry.length) { lines += 1; onLine(carry); }
+    }
+    let err = '';
+    try {
+      err = await collectOutput(proc.collected?.stderr);
+    } catch { /* 诊断文本尽力而为 */ }
+    const outcome = await proc.done;
+    // 取消优先于一切结果分类（与 spawnRun 同款取舍）
+    if (signal?.aborted) throw new Error('操作已取消');
+    if (!stopped) {
+      if (outcome.signal != null) throw new Error(`命令被终止（signal=${outcome.signal}）`);
+      if (outcome.exitCode !== 0) throw new Error(`命令失败 exit=${outcome.exitCode}: ${err}`);
+    }
+    return { bytes, lines, stopped };
+  }
+
   async function spawnRun(argv, cwd, signal) {
     const proc = ctx.subprocess.spawn({
       argv,
@@ -678,6 +780,9 @@ export function apply(ctx, pluginConfig) {
   // （'D:' + '/' + name 仍是合法路径，renameBeside 等不受影响）。
   const parentTar = (p) => (p.endsWith('/') ? p : `${p}/`);
 
+  /** 仓库地址：CLI 首次备份的 star 提示用（面板侧另有常驻入口，见 src/client.js）。 */
+  const STAR_URL = 'https://github.com/xiaoyuyu6420/dsh-backup';
+
   /** semver 比较（常见形态，含 prerelease）：a > b 才返回 true；解析失败保守降为 false。 */
   function semverGt(a, b) {
     const parse = (s) => {
@@ -723,17 +828,33 @@ export function apply(ctx, pluginConfig) {
     }
   }
 
+  /** 读回 profile 内实际解析到的本插件版本（pnpm 把直接依赖链接在 profile 的
+   *  node_modules 下）；路径异常或读不到时返回 null，调用方按「无法核对」处理。 */
+  async function installedVersion(profile) {
+    try {
+      const meta = JSON.parse(await readFile(join(paths().dshHome, 'profiles', profile, 'node_modules', SELF_META.name, 'package.json'), 'utf8'));
+      return typeof meta?.version === 'string' && meta.version ? meta.version : null;
+    } catch {
+      return null;
+    }
+  }
+
   /**
    * 一键更新（B）：先拍升级前快照（未过期的退路），再走官方 `dsh plugin
-   * --profile <p> update <pkg>`（pnpm 语义——profile 是 pnpm 项目，插件绝不
-   * 自己覆写依赖文件，否则 lockfile 失配）。完成后提示重启生效：宿主在启动
-   * 时结算 Loader 树，Node 半不可在运行中热替换。
+   * --profile <p> update --latest <pkg>`（pnpm 语义——profile 是 pnpm 项目，
+   * 插件绝不自己覆写依赖文件，否则 lockfile 失配）。完成后提示重启生效：宿主
+   * 在启动时结算 Loader 树，Node 半不可在运行中热替换。
+   *
+   * `--latest` 不可省：pnpm update <pkg> 只在 profile 声明的版本范围内升级
+   * （安装时写入的是 ^x.y.z），跨 minor 会停在旧 minor 上——而升级按钮承诺的
+   * 目标通常正是新 minor，少了它就是「点了更新、版本没动」。命令跑完再读回
+   * profile 内的真实版本核对，不拿 registry 的 latest 冒充结果。
    */
   async function runUpdate(signal, profileArg) {
     const profile = profileArg || 'web';
     const chk = await checkUpdate(signal);
     if (chk.error) {
-      return { ok: false, updated: false, summary: `检查更新失败：${chk.error}\n可手动执行: dsh plugin --profile ${profile} update ${SELF_META.name}` };
+      return { ok: false, updated: false, summary: `检查更新失败：${chk.error}\n可手动执行: dsh plugin --profile ${profile} update --latest ${SELF_META.name}` };
     }
     if (!chk.update) {
       return { ok: true, updated: false, current: chk.current, latest: chk.latest, summary: `已是最新版本 ${chk.current}` };
@@ -749,12 +870,12 @@ export function apply(ctx, pluginConfig) {
     // detectHostTrain 同款定位——`node <入口> plugin ...` 与运行中的宿主同源）
     let argv = null;
     try {
-      argv = [await ctx.subprocess.resolveExecutable('dsh'), 'plugin', '--profile', profile, 'update', SELF_META.name];
+      argv = [await ctx.subprocess.resolveExecutable('dsh'), 'plugin', '--profile', profile, 'update', '--latest', SELF_META.name];
     } catch {
       try {
-        argv = [process.execPath, realpathSync(process.argv[1]), 'plugin', '--profile', profile, 'update', SELF_META.name];
+        argv = [process.execPath, realpathSync(process.argv[1]), 'plugin', '--profile', profile, 'update', '--latest', SELF_META.name];
       } catch {
-        return { ok: false, updated: false, summary: `找不到 dsh 命令，请手动执行: dsh plugin --profile ${profile} update ${SELF_META.name}${snap ? `\n更新前快照已留: ${snap}` : ''}` };
+        return { ok: false, updated: false, summary: `找不到 dsh 命令，请手动执行: dsh plugin --profile ${profile} update --latest ${SELF_META.name}${snap ? `\n更新前快照已留: ${snap}` : ''}` };
       }
     }
     try {
@@ -763,12 +884,26 @@ export function apply(ctx, pluginConfig) {
     } catch (err) {
       return { ok: false, updated: false, summary: `更新失败：${friendlyReason(err)}${snap ? `\n已有升级前快照 ${snap}，可 /backup restore ${snap} 回滚。` : ''}` };
     }
+    // 命令跑完 ≠ 版本已变：profile 里锁着精确版本、pnpm 配置忽略 --latest 等情况
+    // 都会让结果停在旧版，读回真实版本再回执（否则用户重启后仍是旧版，无从解释）。
+    const after = await installedVersion(profile);
+    if (after && after !== chk.latest) {
+      return {
+        ok: false,
+        updated: false,
+        current: after,
+        latest: chk.latest,
+        summary: `更新命令已执行，但 profile 内解析到的仍是 ${after}（目标 ${chk.latest}）。`
+          + `\n请手动执行: dsh plugin --profile ${profile} update --latest ${SELF_META.name}`
+          + (snap ? `\n更新前已留升级前快照 ${snap}。` : ''),
+      };
+    }
     return {
       ok: true,
       updated: true,
-      current: chk.latest,
+      current: after || chk.latest,
       latest: chk.latest,
-      summary: `已更新到 ${chk.latest}。${snap ? `\n更新前已留升级前快照 ${snap}（想回退：/backup restore ${snap}）。` : '\n更新前快照未生成（不影响本次更新）。'}\n请重启 dsh web 使新版本生效。`,
+      summary: `已更新到 ${after || chk.latest}。${snap ? `\n更新前已留升级前快照 ${snap}（想回退：/backup restore ${snap}）。` : '\n更新前快照未生成（不影响本次更新）。'}\n请重启 dsh web 使新版本生效。`,
     };
   }
 
@@ -816,6 +951,18 @@ export function apply(ctx, pluginConfig) {
     return out;
   }
 
+  /**
+   * vault 串行锁：同一进程内「备份刷新镜像」与「凭据存底」（启动钩子 / migrate
+   * 预检）都写同一个 vault 目录。旧实现是"整目录 rm -rf 再重写"，两路并发时
+   * 互相踩——Linux 上实测 ENOTEMPTY 直接让整个备份失败（CI 稳定复现）。
+   */
+  let vaultChain = Promise.resolve();
+  function withVaultLock(task) {
+    const next = vaultChain.then(task, task);
+    vaultChain = next.then(() => {}, () => {});
+    return next;
+  }
+
   /**
    * 刷新本机 vault：把 ~/.dsh 中现存的敏感文件按相对路径镜像到
    * `<备份目录>/vault/`（先清空旧镜像，vault 永远对应最新一次备份）。
@@ -827,29 +974,41 @@ export function apply(ctx, pluginConfig) {
     const vaultDir = `${root}/${VAULT_DIR}`;
     if (!rels.length) return [];
     if (signal?.aborted) throw new Error('操作已取消');
-    await rm(vaultDir, { recursive: true, force: true });
-    const stored = [];
-    for (const rel of rels) {
-      const src = `${dshHome}/${rel}`;
-      const ok = await fsStat(src).then(() => true, (err) => {
-        if (err && err.code === 'ENOENT') return false;
-        throw err;
-      });
-      if (!ok) continue;
-      const dst = `${vaultDir}/${rel}`;
-      await mkdir(dirname(dst), { recursive: true });
-      await copyFile(src, dst);
-      stored.push(rel);
-    }
-    if (stored.length && !IS_WIN) {
-      const chmod = await ctx.subprocess.resolveExecutable('chmod');
+    return withVaultLock(async () => {
+      // 只清 vault 里的**镜像条目**：`preserved/`（凭据存底）绝不能被下一次备份
+      // 抹掉——它正是为"升级后想回退"留的后路。镜像文件随后会被 copyFile 覆盖成
+      // 最新内容，所以清理失败（另一实例正在写）一律容忍，不值得让备份失败。
+      let names = [];
       try {
-        await spawnRun([chmod, '-R', 'go-rwx', vaultDir], home, signal);
-      } catch {
-        // chmod 失败不阻断备份：vault 已在用户私有目录下，权限收紧是纵深防御
+        names = await readdir(vaultDir);
+      } catch { /* vault 尚不存在：下面逐文件 mkdir 会建 */ }
+      for (const n of names) {
+        if (n === PRESERVED_DIR) continue;
+        await rm(`${vaultDir}/${n}`, { recursive: true, force: true }).catch(() => {});
       }
-    }
-    return stored;
+      const stored = [];
+      for (const rel of rels) {
+        const src = `${dshHome}/${rel}`;
+        const ok = await fsStat(src).then(() => true, (err) => {
+          if (err && err.code === 'ENOENT') return false;
+          throw err;
+        });
+        if (!ok) continue;
+        const dst = `${vaultDir}/${rel}`;
+        await mkdir(dirname(dst), { recursive: true });
+        await copyFile(src, dst);
+        stored.push(rel);
+      }
+      if (stored.length && !IS_WIN) {
+        const chmod = await ctx.subprocess.resolveExecutable('chmod');
+        try {
+          await spawnRun([chmod, '-R', 'go-rwx', vaultDir], home, signal);
+        } catch {
+          // chmod 失败不阻断备份：vault 已在用户私有目录下，权限收紧是纵深防御
+        }
+      }
+      return stored;
+    });
   }
 
   function stampNow() {
@@ -997,7 +1156,11 @@ export function apply(ctx, pluginConfig) {
   }
 
   // 校验和：POSIX 优先 sha256sum（macOS 回退 shasum）流式计算；
-  // 都不可用时（Windows）回退 node:fs 读取 + node:crypto 内存哈希。
+  // 都不可用时（Windows 典型）回退 node:crypto 流式哈希。
+  // #103：旧实现是 readFile 整包进内存 + 同步 update，且 >256MB 直接抛错——
+  // Windows 上 3GB 级归档因此**必然失败**，备份写完 tar 却永远收不了尾，
+  // 锚点不前进 → 每次启动重跑一次全量 tar → 宿主 boot 窗口被拖死。
+  // 改为 createReadStream 分块喂哈希：不整包入内存、每块之间让出事件循环、无体积上限。
   async function sha256File(absPath, home, signal) {
     for (const candidate of [['sha256sum', []], ['shasum', ['-a', '256']]]) {
       try {
@@ -1010,12 +1173,18 @@ export function apply(ctx, pluginConfig) {
         // 尝试下一个
       }
     }
-    const info = await fsStat(absPath);
-    if (info.size > HASH_MAX_BYTES) {
-      throw new Error(`计算 sha256 失败：文件 ${Math.floor(info.size / 1048576)}MB 超过 ${Math.floor(HASH_MAX_BYTES / 1048576)}MB 回退上限`);
+    const hash = createHash('sha256');
+    const stream = createReadStream(absPath, { highWaterMark: HASH_CHUNK_BYTES });
+    try {
+      for await (const chunk of stream) {
+        if (signal?.aborted) throw new Error('操作已取消');
+        hash.update(chunk);
+      }
+    } catch (err) {
+      stream.destroy();
+      throw err;
     }
-    const bytes = await readFile(absPath);
-    return createHash('sha256').update(bytes).digest('hex');
+    return hash.digest('hex');
   }
 
   async function existsStat(p) {
@@ -1638,7 +1807,29 @@ export function apply(ctx, pluginConfig) {
       }
     }
     if (nameIdx < 0 || nameIdx >= f.length) return null;
-    return { type: f[0][0], name: f.slice(nameIdx).join(' ').replace(/\/$/, '') };
+    const rest = f.slice(nameIdx).join(' ');
+    // tar -tv 的链接形态：硬链接 `<名> link to <目标>`、符号链接 `<名> -> <目标>`。
+    // 必须把目标摘出来单独校验：旧实现把它并进 name，于是硬链接条目的"名字"
+    // 天然含空格与目标路径，必然被判非法而整体拒绝（#112），错误信息里也把
+    // 目标一起印出来。
+    let name = rest;
+    let link = null;
+    const hardAt = rest.indexOf(' link to ');
+    if (hardAt >= 0) {
+      name = rest.slice(0, hardAt);
+      link = rest.slice(hardAt + ' link to '.length);
+    } else {
+      const symAt = rest.lastIndexOf(' -> ');
+      if (symAt >= 0) {
+        name = rest.slice(0, symAt);
+        link = rest.slice(symAt + 4);
+      }
+    }
+    return {
+      type: f[0][0],
+      name: name.replace(/\/$/, ''),
+      link: link === null ? null : link.replace(/\/$/, ''),
+    };
   }
 
   /**
@@ -1699,33 +1890,40 @@ export function apply(ctx, pluginConfig) {
     const { root, dshHome } = paths();
     const base = dshHome.split('/').pop();
     const tar = await ctx.subprocess.resolveExecutable('tar');
-    const listed = await spawnRun([tar, '-tvzf', pickedName], root, signal);
-    // tar 路径穿越防护：逐行解析 -tvzf 输出（双布局，见 parseTarEntry），
-    // 条目必须是普通文件/目录、相对路径且位于备份根目录之下；任一违规
-    // 即整体拒绝，恢复绝不触碰备份根之外的文件。
+    // 清单流式读取（#119）：不用有界收集——大归档的清单超过 spill 上限时会被截断，
+    // 碎片会被误判成"不安全条目"而拒绝整包（详见 streamListingLines 注释）。
     const entries = [];
     const bad = [];
-    for (const line of listed.out.split('\n')) {
+    // 路径检查（反斜杠归一化后再判）：`.dsh/..\..\escape.txt` 与 `/` 分隔的
+    // `..` 段同样拒绝（Windows 风格路径变体）。
+    const insideBase = (p) => Boolean(p)
+      && !p.startsWith('/') && !/^[A-Za-z]:/.test(p)
+      && !p.split('/').includes('..')
+      && (p === base || p.startsWith(`${base}/`));
+    const onLine = (line) => {
       const s = line.trim();
-      if (!s) continue;
+      if (!s) return true;
       const parsed = parseTarEntry(s);
-      // 反斜杠归一化后再做全部路径检查：`.dsh/..\..\escape.txt` 与
-      // `/` 分隔的 `..` 段同样拒绝（Windows 风格路径变体）
       const name = parsed ? parsed.name.replace(/\\/g, '/').replace(/\/$/, '') : null;
-      if (
-        !parsed || !name
-        || (parsed.type !== '-' && parsed.type !== 'd')
-        || name.startsWith('/') || /^[A-Za-z]:/.test(name)
-        || name.split('/').includes('..')
-        || (name !== base && !name.startsWith(`${base}/`))
-      ) {
+      const link = parsed && parsed.link ? parsed.link.replace(/\\/g, '/').replace(/\/$/, '') : null;
+      // 允许的类型：普通文件 '-'、目录 'd'，以及**目标也在备份根内**的硬链接 'h'。
+      // 硬链接是 DSH 附件库（attachments/v1：files/ 与 file-objects/ 同一 inode）的
+      // 正常形态，tar 会把第二个路径写成 'h' 条目——旧实现只放行 -/d，于是**带附件的
+      // 归档一律被判"不安全条目"整体拒绝**，完整恢复/dry-run/分类型合并/doctor 修复/
+      // 救援台全链路失效（#112）。硬链接不能跨文件系统、也不能指向目录，目标同为
+      // 归档内相对路径时解压不会逃出备份根；符号链接（l）、设备等仍一律拒绝。
+      const plainOk = Boolean(parsed) && Boolean(name) && (parsed.type === '-' || parsed.type === 'd') && insideBase(name);
+      const hardOk = Boolean(parsed) && parsed.type === 'h' && insideBase(name) && insideBase(link);
+      if (!plainOk && !hardOk) {
         bad.push(parsed ? name : s);
       } else {
         entries.push(name);
       }
-    }
+      return bad.length === 0; // 发现违规立即停读并终止 tar，不必读完
+    };
+    const listed = await streamListingLines([tar, '-tvzf', pickedName], root, signal, onLine);
     if (bad.length) {
-      throw new Error(`归档包含不安全条目（拒绝恢复）：${bad.slice(0, 3).join(', ')}，恢复已中止`);
+      throw new Error(`归档包含不安全条目（拒绝恢复）：${bad.slice(0, 3).join(', ')}（已读清单 ${listed.lines} 行 / ${listed.bytes} 字节），恢复已中止`);
     }
     return entries;
   }
@@ -1843,17 +2041,23 @@ export function apply(ctx, pluginConfig) {
         if (mergedProfiles.length) {
           try {
             const pnpm = await ctx.subprocess.resolveExecutable('pnpm');
+            // 单个 profile 装失败记入 failed 并继续（与全量恢复路径同语义）；
+            // pnpm 本身缺失才落到外层 note。
             for (const p of mergedProfiles) {
               try {
                 await spawnRun([pnpm, 'install', '--frozen-lockfile'], `${dshHome}/profiles/${p}`, signal);
                 deps.installed.push(p);
               } catch {
-                await spawnRun([pnpm, 'install'], `${dshHome}/profiles/${p}`, signal);
-                deps.installed.push(p);
+                try {
+                  await spawnRun([pnpm, 'install'], `${dshHome}/profiles/${p}`, signal);
+                  deps.installed.push(p);
+                } catch {
+                  deps.failed.push(p);
+                }
               }
             }
           } catch {
-            deps.note = 'pnpm 不可用，跳过依赖重装（配置已恢复）';
+            deps.note = '未找到 pnpm，请在各 profile 目录手动执行 pnpm install';
           }
         }
       }
@@ -2049,7 +2253,17 @@ export function apply(ctx, pluginConfig) {
   // （魔数/帧头/块序列/校验和），再逐帧解出逻辑行。检测目标正是社区高频的
   // "corrupt session log"灾难：并发写 seq 撞号、坏帧、尾部截断、单帧重写。
   const ZSTD_MAGIC = 0xfd2fb528;
-  const SESSION_LOG_NAMES = new Set(['session.jsonl.zstd', 'session.jsonl']);
+  // 会话日志文件名 = 宿主 sessionFormatLogFilename 的形态：session[.v<N>].jsonl[.zstd]
+  // （N≥1 可多位；无 .vN 后缀即第 0 代）。**代数是文件名的一部分、会随格式换代前进**，
+  // 写死具体名字会在换代当天整体失明（#117：v4 机器上 doctor/migrate 一份都看不见），
+  // 故按形态匹配，让新代文件至少进入校验/预检流程（代的判定另见迁移预检）。
+  const SESSION_LOG_RE = /^session(?:\.v([1-9][0-9]*))?\.jsonl(?:\.zstd)?$/;
+  const isSessionLogName = (name) => SESSION_LOG_RE.test(name);
+  /** 从会话日志文件名取格式代；非会话日志名返回 null（无 .vN 后缀即 v0）。 */
+  function sessionLogVersion(name) {
+    const m = SESSION_LOG_RE.exec(name);
+    return m ? Number(m[1] ?? 0) : null;
+  }
   const SCAN_SKIP_DIRS = new Set(['node_modules', '.system', '.git', 'vault']);
   const SCAN_MAX_FILES = 4000;
   const SCAN_MAX_DEPTH = 8;
@@ -2194,7 +2408,7 @@ export function apply(ctx, pluginConfig) {
   }
 
   /** 有界递归收集会话日志文件（相对 ~/.dsh 路径）；跳过依赖/系统目录。 */
-  async function collectSessionLogs(dir, relPrefix, depth, out, names = SESSION_LOG_NAMES) {
+  async function collectSessionLogs(dir, relPrefix, depth, out, isLogName = isSessionLogName) {
     if (depth > SCAN_MAX_DEPTH || out.length >= SCAN_MAX_FILES) return;
     let dirents;
     try {
@@ -2207,8 +2421,8 @@ export function apply(ctx, pluginConfig) {
       const rel = relPrefix ? `${relPrefix}/${d.name}` : d.name;
       if (d.isDirectory()) {
         if (SCAN_SKIP_DIRS.has(d.name)) continue;
-        await collectSessionLogs(`${dir}/${d.name}`, rel, depth + 1, out, names);
-      } else if (names.has(d.name)) {
+        await collectSessionLogs(`${dir}/${d.name}`, rel, depth + 1, out, isLogName);
+      } else if (isLogName(d.name)) {
         out.push({ abs: `${dir}/${d.name}`, rel });
       }
     }
@@ -2292,16 +2506,13 @@ export function apply(ctx, pluginConfig) {
   // （0.1.5-rc.2 校准，与 0.11.2 对齐 isHeaderLine 同一套路），覆盖"解析即判"
   // 的规则；需要重放迁移过程的规则（chunk 折叠溯源、引用重映射、worker 复核）
   // 不在覆盖范围，结果里如实标注。三层判定：fail=会话将打不开；migratable=
-  // 旧代但静态规则全过（首次写开会发布 v3 新代）；ok=已是当前代。
-  const MIGRATE_CURRENT_VERSION = 3;
-  /** 物理代文件名 ↔ 格式代（宿主 sessionFormatLogFilename；文件名与 header 不一致宿主拒载）。 */
-  const MIGRATE_LOG_NAMES = [
-    { name: 'session.jsonl', version: 0 },
-    { name: 'session.v1.jsonl', version: 1 },
-    { name: 'session.v2.jsonl', version: 2 },
-    { name: 'session.v3.jsonl', version: 3 },
-  ];
-  const MIGRATE_LOG_SET = new Set(MIGRATE_LOG_NAMES.flatMap((g) => [g.name, `${g.name}.zstd`]));
+  // 旧代但静态规则全过（首次写开会发布当前代新文件）；ok=已是当前代。
+  //
+  // **校准代（#117）**：宿主会随格式换代推进文件名与 header 的 version（0.1.7 起
+  // 为 v4——迁移包只到 `v3-to-v4`、无 `v4-to-v5`）。此常数是本插件**规则**覆盖到的
+  // 最高代，换代时须同步更新；比它更新的日志只提示、不判"打不开"（见
+  // newer-generation）——"宿主读不读得了"取决于宿主版本，不是我们这张注定滞后的表。
+  const MIGRATE_CALIBRATED_VERSION = 4;
   // 冻结事件清单（RELEASED_V0_EVENT_TYPES / RELEASED_V2_EVENT_TYPES，宿主
   // 按契约不增长旧代清单）；migration 对清单外类型连 ignorable 也拒（#6355）。
   const MIGRATE_V0_EVENT_TYPES = new Set(['agent-preset/selected', 'agent/inbox/spliced', 'approval/asked', 'approval/decided', 'approval/policy', 'assistant/chunk', 'assistant/message', 'command/done', 'command/run', 'compaction/end', 'compaction/prune', 'compaction/start', 'compaction/summary', 'feedback/record', 'goal/change', 'hook/invoked', 'hook/result', 'llm/retry', 'llm/retry-started', 'model/selection', 'permission/preset', 'plan/mode', 'request/context', 'request/header', 'sandbox/mode', 'schedule/change', 'session-log-deepseek/delivery-accepted', 'session/end-seed', 'session/title', 'session/title-llm-request', 'step/end', 'step/start', 'subagent/descriptor', 'subagent/model-selection-policy', 'team/member', 'team/message/delivered', 'team/message/queued', 'team/task', 'todo/write', 'tool-workflow/agent-end', 'tool-workflow/agent-start', 'tool-workflow/run-end', 'tool-workflow/run-start', 'tool/call', 'tool/code-dispatch', 'tool/code-dispatch-start', 'tool/result', 'turn/end', 'turn/start', 'user/message', 'web/deepseek-search-llm-request']);
@@ -2309,14 +2520,26 @@ export function apply(ctx, pluginConfig) {
   /** v0 侧退役类型（pre-react-loop 预发布形态；宿主点名拒绝）。 */
   const MIGRATE_V0_RETIRED_TYPES = new Set(['request/header-delta', 'mode/set']);
   /** 消息来源 kind 白名单（v3 侧 15 类；未知 kind 在 v2→v3 边被拒——#6355 主症状）。 */
-  const MIGRATE_SOURCE_KINDS = new Set(['user', 'plugin', 'model', 'tool', 'agent-instructions', 'session-reference', 'team-message', 'goal', 'skill-invocation', 'skill-catalog', 'coordinator', 'subagent-report', 'subagent-settled', 'webhook', 'agent-message']);
+  /**
+   * 「消息来源 kind」的**已知**集合（#113）。注意语义：宿主的 `source.kind` 是
+   * **可合并扩展的联合类型**——每个生产者在自己的模块里声明自己的 kind，没有
+   * 统一的兜底值，所以任何硬编码清单都**不可能完整**。这里的集合因此只当"已知
+   * 名单"用：命中的静默通过，没命中的记一条**提示**（不再判为"打不开"，见
+   * 下方 unknown-source-kind）——真正会拒载的是旧代**事件类型**的冻结清单。
+   *
+   * 内容来自宿主 `@deepseek-ai/dsh-session-format-v3-to-v4` 自带的
+   * `RENAMED_PRODUCERS` 取值与 `RELEASED_SAME_NAME_PRODUCERS` 名单
+   * （2026-09-29 从 0.2.0-rc.1 实装包逐行核对），外加 `producerKind()` 的兜底
+   * 形态 `plugin:<插件名>`（用前缀匹配，见 MIGRATE_KIND_KNOWN）。
+   */
+  const MIGRATE_SOURCE_KINDS = new Set(['user', 'plugin', 'model', 'tool', 'agent-instructions', 'session-reference', 'team-message', 'goal', 'skill-invocation', 'skill-catalog', 'coordinator', 'subagent-report', 'subagent-settled', 'webhook', 'agent-message', 'compact-checkpoint', 'ptc-mode', 'compact-basic', 'runtime-context', 'system-prompt', 'model-selection', 'plan-mode', 'time-context', 'tmux-context', 'user-approval', 'repeat-tool-reminder', 'tool-cordis', 'cordis-host-runner', 'tool-goal', 'tool-jobs', 'hooks-codex', 'hooks-claude-code', 'schedule', 'dsh-session-title-llm', 'fallback', 'provider']);
   const MIGRATE_MAX_FINDINGS = 3;
+  /** kind 是否在已知名单内：精确命中，或宿主兜底形态 `plugin:<插件名>`（可任意长尾，故用前缀判定）。 */
+  const MIGRATE_KIND_KNOWN = (kind) => MIGRATE_SOURCE_KINDS.has(kind) || kind.startsWith('plugin:');
 
-  /** 从物理文件名推格式代；非代文件名（未来扩展）返回 null。 */
+  /** 非代文件名（未来扩展）返回 null；代的判定与 doctor 共用 SESSION_LOG_RE。 */
   function migrateFilenameVersion(fileName) {
-    const base = fileName.replace(/\.zstd$/, '');
-    const g = MIGRATE_LOG_NAMES.find((x) => x.name === base);
-    return g ? g.version : null;
+    return sessionLogVersion(fileName);
   }
 
   /**
@@ -2334,18 +2557,26 @@ export function apply(ctx, pluginConfig) {
     if (!header || typeof header !== 'object' || typeof header.version !== 'number') return null;
     const sourceVersion = header.version;
     const findings = [];
+    const warnings = [];
     let total = 0;
     const fail = (rule, detail) => {
       total += 1;
       if (findings.length < MIGRATE_MAX_FINDINGS) findings.push({ rule, detail });
     };
-    if (sourceVersion > MIGRATE_CURRENT_VERSION) {
-      fail('newer-than-host', `header version=${sourceVersion} 高于本宿主可读的 v${MIGRATE_CURRENT_VERSION}——日志由更新版本的宿主写出，读/写都会被拒（提示语会要求升级宿主）`);
-      return { sourceVersion, findings, total };
+    // 提示（不判"打不开"）：用于**开放集合**上的命中失败——最典型的是
+    // source.kind（可合并扩展的联合类型，硬编码清单天生补不全，#113）。
+    const warn = (rule, detail) => {
+      if (warnings.length < MIGRATE_MAX_FINDINGS) warnings.push({ rule, detail });
+    };
+    if (sourceVersion > MIGRATE_CALIBRATED_VERSION) {
+      // 更新的格式代：本插件的规则表对它是盲区，但"能不能读"由宿主决定（同代/更新可读、
+      // 降级运行被拒）——按开放集合纪律只提示、不替宿主下"打不开"的判决（#117/#113）。
+      warn('newer-generation', `header version=${sourceVersion} 高于本插件校准到的 v${MIGRATE_CALIBRATED_VERSION}——日志由更新的格式代写出。能否打开取决于宿主：宿主同代或更新即可读，**降级运行会被拒**；若你的宿主已是这一代，说明本插件校准滞后，欢迎反馈。仅提示，不判为打不开`);
+      return { sourceVersion, findings, warnings, total };
     }
     if (fileVersion !== null && fileVersion !== sourceVersion) {
       fail('name-version-mismatch', `文件名标 v${fileVersion}，header 标 v${sourceVersion}——宿主按不一致直接拒载`);
-      return { sourceVersion, findings, total };
+      return { sourceVersion, findings, warnings, total };
     }
     // 事件行静态规则。seq 游标语义与 validateSessionLines 一致：v0 有 packed 行
     //（一条行多个 chunk），v1 起一行一事件。
@@ -2383,14 +2614,22 @@ export function apply(ctx, pluginConfig) {
       if (sourceVersion === 2 && (type === 'tool/code-dispatch' || type === 'tool/code-dispatch-start')) fail('ptc-reserved-v2', `第 ${i + 1} 行 ${type} 是 v3 保留 PTC 标签，v2→v3 拒绝（ignorable 也拒）`);
       if ((sourceVersion === 2 || sourceVersion === 3) && type === 'request/header' && rec.data?.header?.system !== undefined) fail('retired-header-system', `第 ${i + 1} 行 request/header 携带退役的 header.system——v2→v3 无法保留时序地提升它${sourceVersion === 3 ? '，当前代读取同样拒绝' : ''}`);
       const kind = rec?.data?.source?.kind;
-      if (typeof kind === 'string' && !MIGRATE_SOURCE_KINDS.has(kind)) fail('unknown-source-kind', `第 ${i + 1} 行消息来源 kind="${kind}" 不在白名单——v2→v3 边拒绝（社区插件自定义 kind，#6355）`);
+      // kind 只作提示，不作判据（#113）：宿主把它设计成可合并扩展的联合类型，
+      // 每个生产者（含任意社区插件）都能加自己的 kind，且生产端对未知 kind 照读
+      // ——旧实现把"不在白名单"直接判成"打不开"，在一台真实机器上把 81/82 份
+      // 完全健康的日志报成不可打开。
+      if (typeof kind === 'string' && !MIGRATE_KIND_KNOWN(kind)) {
+        warn('unknown-source-kind', `第 ${i + 1} 行消息来源 kind="${kind}" 不在已知名单（宿主为可合并扩展的联合类型，官方/社区插件都能新增）——仅提示，不判为打不开；真正会拒载的是旧代事件类型不在冻结清单内`);
+      }
     }
-    return { sourceVersion, findings, total };
+    return { sourceVersion, findings, warnings, total };
   }
 
   /**
    * 单文件迁移预检：解码（复用 doctor 的帧走查）→ 判代 → 静态规则。
-   * 返回 { verdict: 'fail'|'migratable'|'ok'|'skipped', version, findings, total, reason }。
+   * 返回 { verdict: 'fail'|'migratable'|'ok'|'skipped', version, findings, warnings, total, reason }——
+   * findings 是"判为打不开"的硬伤，warnings 是开放集合上的命中失败（如未知
+   * source.kind），只提示不改变 verdict（#113）。
    */
   async function migrateAnalyzeFile(f) {
     const fileVersion = migrateFilenameVersion(f.abs.split('/').pop());
@@ -2405,8 +2644,8 @@ export function apply(ctx, pluginConfig) {
       if (!lines.length) return { verdict: 'fail', version: fileVersion, findings: [{ rule: 'empty', detail: '解出的逻辑行为空' }], total: 1 };
       const r = migrateAnalyzeLines(lines, fileVersion);
       if (!r) return { verdict: 'skipped', version: fileVersion, findings: [], total: 0, reason: 'header 行不可解析——按损坏处理（doctor 体检覆盖），迁移预检跳过' };
-      if (r.total > 0) return { verdict: 'fail', version: r.sourceVersion, findings: r.findings, total: r.total };
-      return { verdict: r.sourceVersion < MIGRATE_CURRENT_VERSION ? 'migratable' : 'ok', version: r.sourceVersion, findings: [], total: 0 };
+      if (r.total > 0) return { verdict: 'fail', version: r.sourceVersion, findings: r.findings, warnings: r.warnings, total: r.total };
+      return { verdict: r.sourceVersion < MIGRATE_CALIBRATED_VERSION ? 'migratable' : 'ok', version: r.sourceVersion, findings: [], warnings: r.warnings, total: 0 };
     } catch (err) {
       return { verdict: 'skipped', version: fileVersion, findings: [], total: 0, reason: `解码失败（${String(err && err.message ? err.message : err)}）——doctor 体检会按损坏处理` };
     }
@@ -2428,14 +2667,17 @@ export function apply(ctx, pluginConfig) {
   async function preserveFlatCredentials() {
     const { dshHome, root } = paths();
     if (!(await credentialsIsFlatLayout(dshHome))) return null;
-    const dir = `${root}/${VAULT_DIR}/preserved`;
-    await mkdir(dir, { recursive: true });
-    const dest = `${dir}/credentials-flat-${new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19)}.yaml`;
-    await copyFile(`${dshHome}/.credentials.yaml`, dest);
-    // 轮换：只留最近 3 份（按文件名时间戳排序即时间序）
-    const old = (await readdir(dir)).filter((n) => n.startsWith('credentials-flat-')).sort();
-    for (const n of old.slice(0, Math.max(old.length - 3, 0))) await rm(`${dir}/${n}`, { force: true });
-    return dest;
+    // 与备份侧的 vault 刷新共用串行锁：并发写入同一 vault 目录互相踩（ENOTEMPTY）
+    return withVaultLock(async () => {
+      const dir = `${root}/${VAULT_DIR}/${PRESERVED_DIR}`;
+      await mkdir(dir, { recursive: true });
+      const dest = `${dir}/credentials-flat-${new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19)}.yaml`;
+      await copyFile(`${dshHome}/.credentials.yaml`, dest);
+      // 轮换：只留最近 3 份（按文件名时间戳排序即时间序）
+      const old = (await readdir(dir)).filter((n) => n.startsWith('credentials-flat-')).sort();
+      for (const n of old.slice(0, Math.max(old.length - 3, 0))) await rm(`${dir}/${n}`, { force: true });
+      return dest;
+    });
   }
 
   /** 环境级探测：硬链接支持（v3 发布用 fs.link，exFAT 等会 ENOTSUP）+ 凭据布局。 */
@@ -2469,7 +2711,7 @@ export function apply(ctx, pluginConfig) {
     const { dshHome, root } = paths();
     if (signal?.aborted) throw new Error('操作已取消');
     const found = [];
-    await collectSessionLogs(dshHome, '', 0, found, MIGRATE_LOG_SET);
+    await collectSessionLogs(dshHome, '', 0, found);
     const sessions = [];
     for (const f of found) {
       if (signal?.aborted) throw new Error('操作已取消');
@@ -2479,8 +2721,9 @@ export function apply(ctx, pluginConfig) {
     const fails = sessions.filter((s) => s.verdict === 'fail');
     const migratable = sessions.filter((s) => s.verdict === 'migratable');
     const skipped = sessions.filter((s) => s.verdict === 'skipped');
+    const warned = sessions.filter((s) => (s.warnings?.length ?? 0) > 0);
     const lines = [];
-    lines.push(`扫描 ${sessions.length} 个会话日志（含 v1/v2/v3 代）：${fails.length} 个升级后将打不开、${migratable.length} 个旧代待迁移（静态规则全过）、${skipped.length} 个未能判定`);
+    lines.push(`扫描 ${sessions.length} 个会话日志（v0 起各代，按文件名代判定）：${fails.length} 个升级后将打不开、${migratable.length} 个旧代待迁移（静态规则全过）、${skipped.length} 个未能判定${warned.length ? `、${warned.length} 个带提示（不影响打开）` : ''}`);
     if (fails.length) {
       lines.push('');
       for (const s of fails.slice(0, 15)) {
@@ -2492,24 +2735,33 @@ export function apply(ctx, pluginConfig) {
       lines.push('');
       lines.push('升级前建议：先拍一份升级前快照（/backup），坏的会话可从更早归档定点修复（/backup doctor --repair）。');
     }
+    if (warned.length) {
+      lines.push('');
+      lines.push(`ℹ️ ${warned.length} 个日志带提示（**不计入"打不开"**，逐条看原因）：`);
+      for (const s of warned.slice(0, 5)) {
+        for (const w of s.warnings) lines.push(`  · ${s.rel}：${w.detail}`);
+      }
+      if (warned.length > 5) lines.push(`  …另有 ${warned.length - 5} 个文件`);
+    }
     if (!env.hardlink) {
       lines.push('');
-      lines.push(`⚠️ 文件系统不支持硬链接（${env.hardlinkNote}）——宿主发布 v3 新代文件会失败（官方 #6358 场景）：旧会话读得了、写开就报错，且升级无法继续。建议把 ~/.dsh 挪回 APFS/ext4 等本地文件系统。`);
+      lines.push(`⚠️ 文件系统不支持硬链接（${env.hardlinkNote}）——宿主发布新代文件会失败（官方 #6358 场景）：旧会话读得了、写开就报错，且升级无法继续。建议把 ~/.dsh 挪回 APFS/ext4 等本地文件系统。`);
     }
     if (env.credentialsFlat) {
       lines.push('');
       lines.push(`⚠️ .credentials.yaml 还是旧扁平布局——宿主下次读档会把它原子替换成 version:1（不可逆，旧宿主将读不回）。${env.credentialsPreserved ? `已自动存底：${env.credentialsPreserved.replace(`${root}/`, '')}` : '自动存底失败（vault 不可写？），建议立即手动 /backup 一次。'}`);
     }
     lines.push('');
-    lines.push(`覆盖说明：以上为静态规则判定（宿主 ${detectHostTrain() || '未知列车'} 校准）。需要重放迁移过程的检查（chunk 折叠溯源、引用重映射、发布前 worker 复核）不在本版覆盖内——静态全过仍可能在新代发布时被宿主拒载。`);
+    lines.push(`覆盖说明：以上为静态规则判定（宿主 ${detectHostTrain() || '未知列车'} 校准；格式代校准到 v${MIGRATE_CALIBRATED_VERSION}）。需要重放迁移过程的检查（chunk 折叠溯源、引用重映射、发布前 worker 复核）不在本版覆盖内——静态全过仍可能在新代发布时被宿主拒载。`);
     const head = fails.length || !env.hardlink || env.credentialsFlat ? '⚠️' : '✅';
     return {
       scanned: sessions.length,
-      sessions: sessions.map((s) => ({ rel: s.rel, verdict: s.verdict, version: s.version, total: s.total, findings: s.findings, ...(s.reason ? { reason: s.reason } : {}) })),
+      sessions: sessions.map((s) => ({ rel: s.rel, verdict: s.verdict, version: s.version, total: s.total, findings: s.findings, ...(s.warnings?.length ? { warnings: s.warnings } : {}), ...(s.reason ? { reason: s.reason } : {}) })),
       env,
       failCount: fails.length,
       migratableCount: migratable.length,
       skippedCount: skipped.length,
+      warningCount: warned.length,
       summary: `${head} ${lines.join('\n')}`,
     };
   }
@@ -2598,6 +2850,30 @@ export function apply(ctx, pluginConfig) {
   // 上次见到的宿主列车（detectHostTrain 代理值）：null=尚未记录（首启动只记
   // 录不拍快照），非 null 且变化 → 升/降级 → 自动拍 dsh-pre-upgrade- 快照。
   let lastTrain = null;
+  // 增长：CLI 回执的 star 提示只出现一次（持久化在 auto.json；旧版读未知字段安全忽略）
+  let starHinted = false;
+  // #103 循环防护三件套：
+  //  - lastAutoAttemptAt：每次自动备份**起跑即记**（不等到成功）。写盘后即使进程
+  //    被强杀（重活干到一半被杀正是本 issue 的形态），下次启动也知道"刚试过"，
+  //    不会以 delay≤0 立刻重跑；旧版读未知字段安全忽略。
+  //  - newestArchiveAt：备份目录里最新归档的 mtime，调度锚点的最终兜底——磁盘上
+  //    躺着新归档就说明不必马上再打一份，避免锚点丢失导致的重跑。
+  //  - lastAutoError：上次失败原因（成功即清），让"备份一直在失败"这件事在
+  //    /backup 与面板上可见，而不是只躺在没人看的宿主日志里。
+  let lastAutoAttemptAt = null;
+  let newestArchiveAt = 0;
+  let lastAutoError = null;
+  // 连续失败次数（内存态）：失败重试按 30min × 2^(n-1) 退避、封顶一个周期，
+  // 避免确定性失败（磁盘满/权限）变成每 30 分钟烧一次 CPU 的热循环。
+  let autoFailStreak = 0;
+  // 无人值守的重活串行队列：开机补跑与列车快照可能同时到点，两份 GB 级 tar
+  // 并行会把机器彻底压死。手动备份/恢复快照是用户在等结果的显式操作，不入队。
+  let heavyChain = Promise.resolve();
+  function enqueueHeavy(task) {
+    const next = heavyChain.then(task, task);
+    heavyChain = next.then(() => {}, () => {});
+    return next;
+  }
 
   /**
    * 等待 settings 用户层加载完成（describe 出现 revision）。启动钩子若在
@@ -2640,7 +2916,7 @@ export function apply(ctx, pluginConfig) {
     // （先到者 rename 走，后到者 ENOENT），UUID 跨实例唯一
     const tmp = `${target}.${randomUUID()}.tmp`;
     try {
-      await writeOwned(tmp, `${JSON.stringify({ hours: autoHours, lastAutoAt, github: githubState, lastTrain })}\n`);
+      await writeOwned(tmp, `${JSON.stringify({ hours: autoHours, lastAutoAt, github: githubState, lastTrain, starHinted, lastAutoAttemptAt, lastAutoError })}\n`);
       await rename(tmp, target);
     } catch (err) {
       await rm(tmp, { force: true }).catch(() => {});
@@ -2648,6 +2924,32 @@ export function apply(ctx, pluginConfig) {
     }
   }
 
+  /**
+   * 磁盘上最新全量归档的 mtime（#103 兜底锚点）：锚点丢失/不前进时，只要备份
+   * 目录里躺着新归档就不该马上再打一份——这是"失败→重跑→再失败"死循环的
+   * 第二道断路（第一道是 lastAutoAttemptAt）。口径与 listBackups 一致：
+   * 只看用户可见的全量归档，不含内部快照与分类型归档。
+   */
+  async function refreshNewestArchiveAt() {
+    const { root } = paths();
+    let dirents;
+    try {
+      dirents = await readdir(root, { withFileTypes: true });
+    } catch {
+      return; // 备份目录还没有/不可读：锚点保持 0
+    }
+    let newest = 0;
+    for (const d of dirents) {
+      if (!d.name.startsWith('dsh-') || !d.name.endsWith('.tar.gz')) continue;
+      if (SNAPSHOT_PREFIXES.some((p) => d.name.startsWith(p)) || d.name.startsWith(TYPED_PREFIX)) continue;
+      try {
+        const st = await fsStat(`${root}/${d.name}`);
+        if (st.mtimeMs > newest) newest = st.mtimeMs;
+      } catch { /* 与轮换/删除竞态：忽略 */ }
+    }
+    newestArchiveAt = newest;
+  }
+
   async function loadAutoState() {
     try {
       const { root } = paths();
@@ -2665,7 +2967,16 @@ export function apply(ctx, pluginConfig) {
       // 故一律视为非法 → null，从当前时间起算 catch-up。
       const lastTs = typeof parsed?.lastAutoAt === 'string' ? Date.parse(parsed.lastAutoAt) : NaN;
       lastAutoAt = Number.isNaN(lastTs) || lastTs > Date.now() ? null : parsed.lastAutoAt;
+      const attTs = typeof parsed?.lastAutoAttemptAt === 'string' ? Date.parse(parsed.lastAutoAttemptAt) : NaN;
+      lastAutoAttemptAt = Number.isNaN(attTs) || attTs > Date.now() ? null : parsed.lastAutoAttemptAt;
       lastTrain = typeof parsed?.lastTrain === 'string' && parsed.lastTrain ? parsed.lastTrain : null;
+      starHinted = parsed?.starHinted === true;
+      const e = parsed?.lastAutoError;
+      lastAutoError = e && typeof e === 'object' && typeof e.message === 'string'
+        ? { at: typeof e.at === 'string' ? e.at : '', message: e.message }
+        : null;
+      // 旧版写的 auto.json 没有这些字段 → 全部按缺失处理，行为与旧版一致
+      await refreshNewestArchiveAt();
       return Number.isFinite(h) && h >= 1 && h <= 720 ? Math.floor(h) : 0;
     } catch (err) {
       // ENOENT = 首次使用还没有 auto.json，是正常初始状态，静默按未配置处理；
@@ -2673,16 +2984,20 @@ export function apply(ctx, pluginConfig) {
       if (err && err.code !== 'ENOENT') {
         console.warn(`[dsh-backup] 自动备份计划文件读取失败，定时备份已暂停（不影响已有备份）：执行 /backup auto <小时数> 可重新开启（${String(err && err.message ? err.message : err)}）`);
       }
+      await refreshNewestArchiveAt();
       return 0;
     }
   }
 
-  /** 下次自动备份触发时间（毫秒）：上次执行 + 周期；无锚点从当前时间起算。 */
+  /** 调度锚点（毫秒）：上次成功 / 磁盘最新归档，取最晚者；皆无则 0。 */
+  function autoAnchorAt() {
+    return Math.max(Number(new Date(lastAutoAt)) || 0, newestArchiveAt || 0);
+  }
+
+  /** 下次自动备份触发时间（毫秒）：锚点 + 周期；无锚点从当前时间起算。 */
   function nextAutoAt() {
     const cycle = autoHours * 3600 * 1000;
-    // 非法/缺失 lastAutoAt 按 0 处理：从当前时间起算，避免 NaN 传染延迟计算
-    const anchor = (Number(new Date(lastAutoAt)) || 0) + cycle;
-    return Math.max(anchor, Date.now());
+    return Math.max(autoAnchorAt() + cycle, Date.now());
   }
 
   /** 本地时间显示：YYYY-MM-DD HH:mm——不依赖运行时 locale（裸跑环境会落 en-US）。 */
@@ -2692,43 +3007,82 @@ export function apply(ctx, pluginConfig) {
     return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}`;
   }
 
+  /** 失败提示（若有）：让"备份一直在失败"在 /backup 与面板上可见，而不是只躺在宿主日志里。 */
+  function autoErrorNote() {
+    if (!lastAutoError) return '';
+    const when = lastAutoError.at ? formatWhen(Date.parse(lastAutoError.at)) : '';
+    const msg = lastAutoError.message.length > 200 ? `${lastAutoError.message.slice(0, 200)}…` : lastAutoError.message;
+    return `\n⚠️ 上次自动备份未完成${when ? `（${when}）` : ''}：${msg}`;
+  }
+
   function autoSummary() {
-    if (!autoDispose) return '自动备份未开启（/backup auto <N小时> 开启）';
-    // 绝对节奏：下次 = 上次执行 + 周期；错过（重启间隔超周期）则按现在显示，调度会立即补跑。
-    return `自动备份已开启：每 ${autoHours} 小时一次（已持久化，重启续跑），下次 ${formatWhen(nextAutoAt())}${lastAuto ? `；上次自动备份: ${lastAuto}` : ''}`;
+    if (!autoDispose) return `自动备份未开启（/backup auto <N小时> 开启）${autoErrorNote()}`;
+    // 绝对节奏：下次 = 锚点 + 周期；错过（重启间隔超周期）则按现在显示，调度会在启动宽限后补跑。
+    return `自动备份已开启：每 ${autoHours} 小时一次（已持久化，重启续跑），下次 ${formatWhen(nextAutoAt())}${lastAuto ? `；上次自动备份: ${lastAuto}` : ''}${autoErrorNote()}`;
   }
 
-  /** 链式 timeout 调度：每次触发后按上次执行时间推算下一次，重启后节奏不重置。 */
-  function scheduleAuto() {
+  /**
+   * 链式 timeout 调度：每次触发后按锚点推算下一次，重启后节奏不重置。
+   * #103 两条断路，缺一不可：
+   *  1. boot 宽限——启动路径的首次触发绝不落在宿主 boot 窗口内（delay≤0 的补跑
+   *     正是把 GB 级 tar 塞进 boot 窗口、拖垮 HostRpc 的元凶）；
+   *  2. 尝试冷却——上次**起跑**（不要求成功）之后 30 分钟（失败按 2^n 退避）内
+   *     不再起跑。锚点落盘，所以"干到一半被强杀 → 下次启动又立刻重跑"的循环断开。
+   */
+  function scheduleAuto(opts = {}) {
     // 关闭竞态保护：auto off 时 in-flight 备份完成后的续链会以 autoHours=0
     // 算出 delay=0，形成无限备份循环——关闭后绝不续链。
     if (autoHours <= 0) return;
-    const delay = nextAutoAt() - Date.now();
+    const cycle = autoHours * 3600 * 1000;
+    let delay = nextAutoAt() - Date.now();
+    const attemptAt = Number(new Date(lastAutoAttemptAt)) || 0;
+    const cooldown = autoFailStreak > 0
+      ? Math.min(AUTO_RETRY_MS * 2 ** (autoFailStreak - 1), cycle)
+      : AUTO_RETRY_MS;
+    if (attemptAt) delay = Math.max(delay, attemptAt + cooldown - Date.now());
+    if (opts.boot) delay = Math.max(delay, AUTO_BOOT_GRACE_MS);
     autoDispose = ctx.timeout(async () => {
-      await runAutoBackup();
+      // 无人值守重活串行：与列车快照等其它无人值守任务排队，不并行抢机器
+      await enqueueHeavy(runAutoBackup);
       scheduleAuto();
     }, delay);
   }
 
   async function runAutoBackup() {
+    // 起跑留痕（先写盘再干活）：进程被强杀也不丢"刚试过"这个事实，
+    // 下次启动据此冷却，不会在 boot 窗口里重跑（#103）。
+    lastAutoAttemptAt = new Date().toISOString();
+    await saveAutoState().catch(() => { /* 记录失败不阻断备份本身 */ });
     try {
       const r = await doBackup(autoKeep());
       lastAuto = r.path.split('/').pop();
       lastAutoAt = new Date().toISOString();
+      lastAutoError = null;
+      autoFailStreak = 0;
+      newestArchiveAt = Date.now();
       await saveAutoState();
       console.log(`[dsh-backup] 自动备份完成: ${r.path} (sha ${r.sha.slice(0, 12)}…)`);
     } catch (err) {
-      // 失败也推进内存锚点：否则下次 delay=0 立即重试形成热循环。不落盘
-      // （失败路径 auto.json 大概率也写失败），下次成功备份会持久化。
-      lastAutoAt = new Date().toISOString();
-      console.error(`[dsh-backup] 自动备份失败: ${String(err && err.message ? err.message : err)}`);
+      // 失败不再"只推进内存锚点"（旧实现不落盘 → 每次启动 delay≤0 重跑，
+      // 3GB 归档必然失败时就是无限重跑；#103）。改记失败原因 + 退避重试，
+      // 由 lastAutoAttemptAt（已落盘）负责跨重启冷却。
+      autoFailStreak += 1;
+      const message = String(err && err.message ? err.message : err);
+      lastAutoError = { at: new Date().toISOString(), message };
+      await saveAutoState().catch(() => { /* 失败路径写盘也可能失败，不影响内存退避 */ });
+      console.error(`[dsh-backup] 自动备份失败（第 ${autoFailStreak} 次，${Math.round(Math.min(AUTO_RETRY_MS * 2 ** (autoFailStreak - 1), autoHours * 3600 * 1000) / 60000)} 分钟后重试）: ${message}`);
     }
   }
 
   async function setAuto(h) {
     if (autoDispose) { autoDispose(); autoDispose = null; }
     autoHours = h;
+    // 开启/重设 = 用户要一次基线备份：清掉旧锚点与失败退避，让下次触发落在"现在"
     lastAutoAt = null;
+    lastAutoAttemptAt = null;
+    newestArchiveAt = 0;
+    autoFailStreak = 0;
+    lastAutoError = null;
     if (h > 0) scheduleAuto();
     await saveAutoState();
   }
@@ -2918,9 +3272,17 @@ export function apply(ctx, pluginConfig) {
         const typesMatch = input.match(/--(?:types|only)\s+([\w,]+)/);
         const types = typesMatch ? [...new Set(typesMatch[1].split(',').map((s) => s.trim()).filter(Boolean))] : undefined;
         const r = await doBackup(keep, invocation.signal, types ? { types } : {});
+        // 增长（每周增长仪表盘配套）：首次手动备份成功后给一次 star 提示，此后永不再现；
+        // 自动备份的日志不加（噪音），面板有常驻入口。
+        let starNote = '';
+        if (!starHinted) {
+          starNote = `\n\n💡 觉得好用的话，给个 Star 是对我们最大的支持: ${STAR_URL}`;
+          starHinted = true;
+          await saveAutoState().catch(() => { /* 记录失败不影响回执内容 */ });
+        }
         return {
           kind: 'success',
-          text: `✅ 备份完成${types ? `（类型: ${types.join(', ')}${r.hasCredentials ? '，含明文凭据·不进 GitHub 同步' : ''}）` : ''}\n  文件: ${r.path}\n  校验和: ${r.sha.slice(0, 16)}…\n  轮换: 删除 ${r.stale} 份旧备份（保留 ${r.keep} 份）${quarantineNote(r)}\n  ${autoSummary()}`,
+          text: `✅ 备份完成${types ? `（类型: ${types.join(', ')}${r.hasCredentials ? '，含明文凭据·不进 GitHub 同步' : ''}）` : ''}\n  文件: ${r.path}\n  校验和: ${r.sha.slice(0, 16)}…\n  轮换: 删除 ${r.stale} 份旧备份（保留 ${r.keep} 份）${quarantineNote(r)}\n  ${autoSummary()}${starNote}`,
         };
       } catch (err) {
         return { kind: 'error', text: `备份失败: ${friendlyReason(err)}` };
@@ -2931,7 +3293,7 @@ export function apply(ctx, pluginConfig) {
   // ---------- backup_dsh 模型工具 ----------
   ctx.tools.register(defineTool({
     name: 'backup_dsh',
-    description: '备份、校验、恢复或体检 DSH 用户数据（~/.dsh 的会话、配置、技能）。凭据文件默认脱敏：不进归档、不进 GitHub 同步，明文只存本机 vault，恢复时自动还原。mode=backup 立即备份（keep 指定保留份数）；mode=list 列出备份；mode=verify 校验完整性（selector=前缀或 all，缺省最新一份）；mode=restore 恢复（selector=前缀或 latest，syncDeps 恢复后重装 profile 依赖；恢复前自动校验并快照当前数据，解压失败自动还原；真实恢复前必须先 dryRun=true 预览并向用户展示确认）；mode=auto 设置定时备份（hours 间隔小时数，0=关闭，缺省查询）；mode=doctor 会话日志体检——检测损坏的会话历史（seq 撞号/坏帧/截断），repair=true 时从 selector 归档定点修复；mode=migrate 迁移预检——静态扫描全部代会话日志（含 v1/v2/v3 代），预测宿主升级后哪些会话会打不开、挂在哪条规则，并探测文件系统硬链接支持与凭据文件旧布局',
+    description: '备份、校验、恢复或体检 DSH 用户数据（~/.dsh 的会话、配置、技能）。凭据文件默认脱敏：不进归档、不进 GitHub 同步，明文只存本机 vault，恢复时自动还原。mode=backup 立即备份（keep 指定保留份数）；mode=list 列出备份；mode=verify 校验完整性（selector=前缀或 all，缺省最新一份）；mode=restore 恢复（selector=前缀或 latest，syncDeps 恢复后重装 profile 依赖；恢复前自动校验并快照当前数据，解压失败自动还原；真实恢复前必须先 dryRun=true 预览并向用户展示确认）；mode=auto 设置定时备份（hours 间隔小时数，0=关闭，缺省查询）；mode=doctor 会话日志体检——检测损坏的会话历史（seq 撞号/坏帧/截断），repair=true 时从 selector 归档定点修复；mode=migrate 迁移预检——静态扫描全部代会话日志（v0 起各代），预测宿主升级后哪些会话会打不开、挂在哪条规则，并探测文件系统硬链接支持与凭据文件旧布局',
     parameters: {
       mode: { type: 'string', required: true, enum: ['backup', 'list', 'verify', 'restore', 'auto', 'doctor', 'migrate'], description: 'backup=执行备份，list=列出备份，verify=校验完整性，restore=恢复，auto=定时备份，doctor=会话日志体检，migrate=升级迁移预检' },
       keep: { type: 'number', description: '保留的备份份数（mode=backup，默认 7）' },
@@ -2996,8 +3358,11 @@ export function apply(ctx, pluginConfig) {
             failCount: r.failCount,
             migratableCount: r.migratableCount,
             skippedCount: r.skippedCount,
+            warningCount: r.warningCount ?? 0,
             summary: r.summary,
-            sessions: r.sessions.filter((s) => s.verdict === 'fail').map((s) => ({ path: s.rel, version: s.version, findings: s.findings })),
+            // fail 项照旧全带；带提示（不判打不开）的条目也带上 warnings——否则
+            // UI 只能看到"没问题"，用户无从知道有哪些开放集合上的命中失败（#113）。
+            sessions: r.sessions.filter((s) => s.verdict === 'fail' || s.warnings?.length).map((s) => ({ path: s.rel, version: s.version, findings: s.findings, ...(s.warnings?.length ? { warnings: s.warnings } : {}) })),
             env: r.env,
           };
         }
@@ -3306,8 +3671,22 @@ export function apply(ctx, pluginConfig) {
             sendJson(res, 503, { error: 'settings-unavailable' });
             return;
           }
+          // 0.1.7 起宿主换了 settings 模型：插件的 register(ns, schema) 被移除，
+          // 描述符改由「profile 条目自带的 Config schema」派生——我们自注册的
+          // 命名空间因此不在 describe() 里（0.1.6-alpha.1 及更早仍是旧模型）。
+          // 旧实现在这里直接抛 TypeError（读 undefined.value），面板只看到一句
+          // 原始报错、编辑还静默失败。改为显式降级：如实说明并指向配置出路。
+          const desc = describeOwn(settingsService, NS);
+          if (!desc) {
+            sendJson(res, 200, {
+              unavailable: true,
+              reason: 'settings-namespace-missing',
+              note: '此宿主版本的设置面板由宿主自带的配置表单接管（0.1.7 起插件自注册的设置命名空间不再生效）；本插件的选项请写在 profile 的 cordis.yml / cordis.patch.yml 的插件条目 config 下。',
+            });
+            return;
+          }
           if (req.method === 'GET' || req.method === 'HEAD') {
-            sendJson(res, 200, describeResponse(describeOwn(settingsService, NS)));
+            sendJson(res, 200, describeResponse(desc));
             return;
           }
           if (req.method !== 'POST') {
@@ -3340,7 +3719,7 @@ export function apply(ctx, pluginConfig) {
             }
             throw err;
           }
-          sendJson(res, 200, describeResponse(describeOwn(settingsService, NS)));
+          sendJson(res, 200, describeResponse(describeOwn(settingsService, NS) ?? desc));
         } catch (err) {
           sendJson(res, 400, { error: String(err && err.message ? err.message : err) });
         }
@@ -3348,7 +3727,8 @@ export function apply(ctx, pluginConfig) {
     }), 'dsh-backup: settings route');
   });
 
-  // 启动时恢复持久化的定时备份计划（不阻塞插件装配）；错过则 delay=0 立即补跑。
+  // 启动时恢复持久化的定时备份计划（不阻塞插件装配）；错过则在**启动宽限期之后**
+  // 补跑——绝不在宿主 boot 窗口内启动 GB 级 tar（#103）。
   // 同处做升级前快照：宿主列车变化（升/降级）先拍一份 dsh-pre-upgrade- 安全网
   // 再继续——命中社区"想试新版怕搞坏"的最大恐惧。首见列车只记录不拍。
   void (async () => {
@@ -3357,7 +3737,7 @@ export function apply(ctx, pluginConfig) {
     const h = await loadAutoState();
     if (h > 0 && !autoDispose) {
       autoHours = h;
-      scheduleAuto();
+      scheduleAuto({ boot: true });
     }
     // 凭据哨兵：宿主首次读档会把扁平布局的 .credentials.yaml 原子替换成
     // version:1（不可逆——旧宿主读不回 versioned，官方 #6358）。启动即检测，
@@ -3379,14 +3759,21 @@ export function apply(ctx, pluginConfig) {
     }
     if (lastTrain === train) return;
     const oldTrain = lastTrain;
-    try {
-      const snap = await doBackup(undefined, undefined, { namePrefix: 'dsh-pre-upgrade-' });
-      await prunePrefixedSnapshots('dsh-pre-upgrade-', 2, snap.name);
-      lastTrain = train;
-      await saveAutoState();
-      console.log(`[dsh-backup] 宿主列车变化（${oldTrain} → ${train}），已自动拍升级前快照: ${snap.name}${snap.quarantined?.length ? `（${snap.quarantined.length} 个损坏会话文件未入档）` : ''}`);
-    } catch (err) {
-      console.warn(`[dsh-backup] 升级前快照失败（不影响运行，下次启动会重试）: ${String(err && err.message ? err.message : err)}`);
-    }
+    // 列车快照同样是 GB 级重活：与自动补跑一样推迟到 boot 窗口之外，并走同一条
+    // 无人值守队列（两者同时到点时串行而非并行）。失败时不更新 lastTrain，
+    // 下次启动重试——语义与旧版一致。
+    ctx.timeout(() => {
+      void enqueueHeavy(async () => {
+        try {
+          const snap = await doBackup(undefined, undefined, { namePrefix: 'dsh-pre-upgrade-' });
+          await prunePrefixedSnapshots('dsh-pre-upgrade-', 2, snap.name);
+          lastTrain = train;
+          await saveAutoState();
+          console.log(`[dsh-backup] 宿主列车变化（${oldTrain} → ${train}），已自动拍升级前快照: ${snap.name}${snap.quarantined?.length ? `（${snap.quarantined.length} 个损坏会话文件未入档）` : ''}`);
+        } catch (err) {
+          console.warn(`[dsh-backup] 升级前快照失败（不影响运行，下次启动会重试）: ${String(err && err.message ? err.message : err)}`);
+        }
+      });
+    }, AUTO_BOOT_GRACE_MS);
   })();
 }