dsh-config-manager 0.1.71 → 0.1.73

package/src/cli/index-guards.test.ts

@@ -0,0 +1,193 @@
+/**
+ * CLI 守卫单测（本轮修复的四条纪律，全部是「不能悄悄放过」的行为）：
+ *  ① 参数白名单：verify 不再悄悄接受 --dry-run / --profile / --settings；
+ *  ② snapshots / restore 的「快照目录读不出来」必须区别于「没有快照」（非 0 退出 + stderr）；
+ *  ③ restore 的第三道写入门：本机有 DSH 在跑 → 拒绝（且 dry-run 不受影响）；
+ *  ④ web 的四个目录从**同一个 root** 派生（--data-dir 尾段命中 snapshots/exports 时上溯一层）。
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import { parseCli, resolveWebPaths, runCli, type CliIo } from './index.ts';
+
+async function withTmp<T>(fn: (dir: string) => Promise<T>): Promise<T> {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-cm-cli-guards-'));
+  try {
+    return await fn(dir);
+  } finally {
+    await fs.rm(dir, { recursive: true, force: true });
+  }
+}
+
+function captureIo(): { io: CliIo; out: string[] } {
+  const out: string[] = [];
+  const io: CliIo = { log: (s) => out.push(s), error: (s) => out.push(s) };
+  return { io, out };
+}
+
+/* ---------------------------------------------------------------- ① 参数白名单 */
+
+test('G-01 verify 必须拒绝 --dry-run / --profile / --settings（不得悄悄接受并忽略）', () => {
+  for (const args of [
+    ['verify', '--dry-run'],
+    ['verify', '--profile', 'dev'],
+    ['verify', '--settings', '/s/settings.yaml'],
+  ]) {
+    assert.equal(parseCli(args).ok, false, '应拒绝: ' + args.join(' '));
+  }
+  // --id 是 verify 位置参数的等价写法（见 help 的 verify 段），必须继续可用。
+  const byId = parseCli(['verify', '--id', 'backup.zip']);
+  assert.ok(byId.ok);
+  assert.equal(byId.options.id, 'backup.zip');
+});
+
+test('G-02 其它命令也按「真正用到才放行」拒绝 restore 系参数', () => {
+  assert.equal(parseCli(['snapshots', '--profile', 'dev']).ok, false, 'snapshots 不用 --profile');
+  assert.equal(parseCli(['snapshots', '--settings', '/s']).ok, false, 'snapshots 不用 --settings');
+  assert.equal(parseCli(['snapshots', '--dry-run']).ok, false, 'snapshots 不用 --dry-run');
+  // 反向：真正用到这些参数的命令必须继续放行（不能为了「统一拒绝」把它们一起打死）。
+  assert.ok(parseCli(['reinstall', '--dry-run']).ok, 'reinstall 真的用 --dry-run');
+  assert.ok(parseCli(['backup', '--dry-run']).ok, 'backup 真的用 --dry-run');
+  assert.ok(parseCli(['import', '--from', 'claude-code', '--dry-run']).ok, 'import 真的用 --dry-run');
+  const web = parseCli(['web', '--profile', 'dev']);
+  assert.ok(web.ok, 'web 真的用 --profile（救急台「恢复」页的目标档案）');
+  assert.equal(web.options.profile, 'dev');
+  assert.ok(parseCli(['restore', '--id', 'x', '--dry-run', '--profile', 'dev', '--settings', '/s']).ok, 'restore 全都要');
+});
+
+/* ---------------------------------------------------------------- ② 读不到 ≠ 没有 */
+
+test('G-03 snapshots：快照目录读不出来 → stderr 说明 + 非 0 退出（绝不显示成「无快照」）', async () => {
+  await withTmp(async (tmp) => {
+    // 用一个**普通文件**占住快照目录路径：readdir 必失败（ENOTDIR），且不是「目录不存在」。
+    const dataDir = path.join(tmp, 'snapshots-as-file');
+    await fs.writeFile(dataDir, 'not a directory', 'utf8');
+    const { io, out } = captureIo();
+    const code = await runCli(['snapshots', '--data-dir', dataDir], io, { DSH_HOME: path.join(tmp, 'home') });
+    assert.equal(code, 1, '读不出来必须非 0 退出');
+    const text = out.join('\n');
+    assert.match(text, /快照目录读不出来/, '必须把事实打到 stderr');
+    assert.doesNotMatch(text, /无快照/, '不得显示成「没有快照」');
+  });
+});
+
+test('G-04 restore：默认挑快照时目录读不出来 → 如实打印 + 非 0 退出', async () => {
+  await withTmp(async (tmp) => {
+    const dataDir = path.join(tmp, 'snapshots-as-file');
+    await fs.writeFile(dataDir, 'not a directory', 'utf8');
+    const { io, out } = captureIo();
+    const code = await runCli(['restore', '--data-dir', dataDir], io, { DSH_HOME: path.join(tmp, 'home') });
+    assert.equal(code, 1);
+    assert.match(out.join('\n'), /快照目录读不出来/);
+  });
+});
+
+test('G-05 没有快照（目录不存在）仍照旧：snapshots 返回 0 并打印「无快照」', async () => {
+  await withTmp(async (tmp) => {
+    const { io, out } = captureIo();
+    const code = await runCli(['snapshots', '--data-dir', path.join(tmp, 'missing')], io, { DSH_HOME: path.join(tmp, 'home') });
+    assert.equal(code, 0, '目录不存在 ≠ 读不出来（core 的 listSnapshots 只有 ENOENT 才算没有）');
+    assert.match(out.join('\n'), /无快照/);
+  });
+});
+
+/* ---------------------------------------------------------------- ③ restore 的第三道门 */
+
+/** 造一个「可恢复」的最小快照 + 当前 home 文件。 */
+async function seedRestorableSnapshot(tmp: string): Promise<{ homeDir: string; dataDir: string; id: string }> {
+  const homeDir = path.join(tmp, 'home');
+  const dataDir = path.join(tmp, 'snapshots');
+  const id = 'snap-guard-1';
+  const dir = path.join(dataDir, id);
+  await fs.mkdir(path.join(dir, 'blobs', 'host'), { recursive: true });
+  await fs.writeFile(path.join(dir, 'blobs', 'host', 'settings'), 'SNAPSHOT settings\n', 'utf8');
+  await fs.writeFile(path.join(dir, 'snapshot.json'), JSON.stringify({
+    id, createdAt: '2026-08-14T12:00:00.000Z', sourceZip: 'backup.zip', status: 'done',
+    entries: [],
+    hostFileBackups: [{ relPath: 'settings.yaml', blobPath: 'blobs/host/settings', existed: true }],
+    beforePlugins: [],
+  }), 'utf8');
+  await fs.mkdir(homeDir, { recursive: true });
+  await fs.writeFile(path.join(homeDir, 'settings.yaml'), 'CURRENT settings\n', 'utf8');
+  // 心跳落在候选控制根之一（--data-dir 本身）下：pid 用本进程 → 判定为「正在跑」
+  await fs.mkdir(path.join(dataDir, 'running'), { recursive: true });
+  return { homeDir, dataDir, id };
+}
+
+test('G-06 restore：本机有 DSH 在跑 → 拒绝执行（与救急台 checkWriteGates 同源）', async () => {
+  await withTmp(async (tmp) => {
+    const { homeDir, dataDir, id } = await seedRestorableSnapshot(tmp);
+    await fs.writeFile(path.join(dataDir, 'running', 'web.json'), JSON.stringify({
+      schemaVersion: 1, name: 'web', pid: process.pid, port: 3099,
+      startedAt: new Date().toISOString(), updatedAt: Date.now(),
+    }), 'utf8');
+
+    const { io, out } = captureIo();
+    const code = await runCli(['restore', '--id', id, '--data-dir', dataDir], io, { DSH_HOME: homeDir });
+    assert.equal(code, 1, 'DSH 在跑时恢复必须被拒绝');
+    const text = out.join('\n');
+    assert.match(text, /检测到 DSH 正在运行/);
+    assert.match(text, /dcm web/, '必须给出「起不来时」的出口');
+    assert.equal(
+      await fs.readFile(path.join(homeDir, 'settings.yaml'), 'utf8'),
+      'CURRENT settings\n',
+      '被拒绝时一个字节都不许改',
+    );
+  });
+});
+
+test('G-07 restore --dry-run：DSH 在跑也照旧只打印计划（门只在真实执行前）', async () => {
+  await withTmp(async (tmp) => {
+    const { homeDir, dataDir, id } = await seedRestorableSnapshot(tmp);
+    await fs.writeFile(path.join(dataDir, 'running', 'web.json'), JSON.stringify({
+      schemaVersion: 1, name: 'web', pid: process.pid, port: 3099,
+      startedAt: new Date().toISOString(), updatedAt: Date.now(),
+    }), 'utf8');
+
+    const { io, out } = captureIo();
+    const code = await runCli(['restore', '--dry-run', '--id', id, '--data-dir', dataDir], io, { DSH_HOME: homeDir });
+    assert.equal(code, 0, 'dry-run 零写入，不受写入门影响');
+    assert.match(out.join('\n'), /动作计划/);
+    assert.equal(await fs.readFile(path.join(homeDir, 'settings.yaml'), 'utf8'), 'CURRENT settings\n');
+  });
+});
+
+/* ---------------------------------------------------------------- ④ web 目录派生 */
+
+test('G-08 resolveWebPaths：快照/导出/锁/数据根四处必须同源（--data-dir 只上溯一次）', () => {
+  // 统一先 resolve：Windows 下 '\\root' 是「当前盘符根」，函数内部也会 resolve，避免断言口径不一致。
+  const homeDsh = path.resolve(path.sep, 'home', 'dsh');
+  const root = path.resolve(path.sep, 'root');
+  const env = { DSH_HOME: homeDsh } as Record<string, string | undefined>;
+
+  // 尾段命中 snapshots：上溯一层当作 root，四个目录都挂在它下面。
+  const fromSnapshots = resolveWebPaths({ dataDir: path.join(root, 'snapshots') }, env);
+  assert.equal(fromSnapshots.root, root);
+  assert.equal(fromSnapshots.dataDir, root);
+  assert.equal(fromSnapshots.snapshotsDir, path.join(root, 'snapshots'));
+  assert.equal(fromSnapshots.exportsDir, path.join(root, 'exports'), '导出目录也必须上溯（不再挂到 leaf 下）');
+  assert.equal(fromSnapshots.locksDir, path.join(root, 'locks'));
+
+  // exports 同理
+  const fromExports = resolveWebPaths({ dataDir: path.join(root, 'exports') }, env);
+  assert.equal(fromExports.snapshotsDir, path.join(root, 'snapshots'));
+  assert.equal(fromExports.exportsDir, path.join(root, 'exports'));
+
+  // 直接给数据根
+  const fromRoot = resolveWebPaths({ dataDir: root }, env);
+  assert.equal(fromRoot.snapshotsDir, path.join(root, 'snapshots'));
+  assert.equal(fromRoot.exportsDir, path.join(root, 'exports'));
+
+  // --data-root 恒为准（即使同时给了 leaf 形态的 --data-dir）
+  const other = path.resolve(path.sep, 'other');
+  const explicitRoot = resolveWebPaths({ dataRoot: other, dataDir: path.join(root, 'snapshots') }, env);
+  assert.equal(explicitRoot.root, other);
+  assert.equal(explicitRoot.snapshotsDir, path.join(other, 'snapshots'));
+
+  // 都没给：缺省根 = $DSH_HOME/dsh-config-manager
+  const defaults = resolveWebPaths({}, env);
+  assert.equal(defaults.root, path.join(homeDsh, 'dsh-config-manager'));
+});

package/src/cli/index.ts

@@ -139,8 +139,23 @@ const BACKUP_ONLY_FLAGS = new Set(['--sections', '--out']);
 /** backup 明确不支持的 restore 系参数（--dry-run 对 backup 有效，故不在此表） */
 const BACKUP_REJECTED_FLAGS = new Set(['--id', '--profile', '--settings']);
 
-/** 仅 restore 子命令允许的参数 */
-const RESTORE_ONLY_FLAGS = new Set(['--id', '--dry-run', '--profile', '--settings']);
+/**
+ * 每个参数**真正被哪些子命令使用**（白名单，而不是「想起来才拒绝某一条」）。
+ *
+ * 为什么要有这张表：此前只有 `snapshots` 会拒绝 restore 系参数，于是
+ * `verify --dry-run / --profile / --settings` 被**悄悄接受并忽略** —— 用户会以为自检跑成了
+ * 「只读预演」。纪律是「本命令用不到的参数一律拒绝」，而不是「反正不影响结果就算了」。
+ */
+const FLAG_ALLOWED_COMMANDS = new Map<string, ReadonlySet<CliCommand>>([
+  // --id：restore 的目标快照；verify 把它当位置参数的等价写法（见 help 的 verify 段）。
+  ['--id', new Set<CliCommand>(['restore', 'verify'])],
+  // --dry-run：restore（只打印计划）/ reinstall（只打印重装步骤）/ backup（只打印打包清单）。
+  ['--dry-run', new Set<CliCommand>(['restore', 'reinstall', 'backup'])],
+  // --profile：restore 要恢复的档案；web 用它决定救急台操作哪个档案（两条都真的在用，故放行）。
+  ['--profile', new Set<CliCommand>(['restore', 'web'])],
+  // --settings：只有 restore 的「覆盖 settings 文件路径」用得到。
+  ['--settings', new Set<CliCommand>(['restore'])],
+]);
 
 /** 仅 reinstall 子命令允许的参数 */
 const REINSTALL_ONLY_FLAGS = new Set(['--yes', '--list', '--wipe-config', '--version']);
@@ -349,8 +364,10 @@ export function parseCli(argv: readonly string[]): ParseResult {  const command
       options.json = true;
       continue;
     }
-    if (command === 'snapshots' && RESTORE_ONLY_FLAGS.has(flag)) {
-      return { ok: false, error: `snapshots 子命令不支持参数 / flag not allowed here: ${flag}` };
+    // 本命令用不到的参数一律拒绝（绝不「悄悄接受并忽略」）：白名单见 FLAG_ALLOWED_COMMANDS。
+    const allowedCommands = FLAG_ALLOWED_COMMANDS.get(flag);
+    if (allowedCommands !== undefined && !allowedCommands.has(command)) {
+      return { ok: false, error: `${command} 子命令不支持参数 / flag not allowed here: ${flag}` };
     }
     if (command !== 'reinstall' && REINSTALL_ONLY_FLAGS.has(flag)) {
       return { ok: false, error: `${command} 子命令不支持参数 / flag not allowed here: ${flag}` };
@@ -1022,7 +1039,15 @@ export async function runCli(
   const dataDir = lockDataDir;
 
   if (options.command === 'snapshots') {
-    const metas = await listSnapshots(dataDir);
+    // 「读不到」≠「没有快照」（core/restore.ts 的 listSnapshots 只有 ENOENT 才算没有）：
+    // 目录存在却读不出来时必须把事实打到 stderr 并以非 0 退出，绝不显示成「无快照」。
+    const probe: { unreadable?: string } = {};
+    const metas = await listSnapshots(dataDir, probe);
+    if (probe.unreadable !== undefined) {
+      io.error(probe.unreadable);
+      io.error('读不到 ≠ 没有快照：请检查该目录的权限/形态，或用 --data-dir 指定正确位置。/ unreadable is not the same as no snapshots');
+      return 1;
+    }
     printSnapshots(metas, io);
     return 0;
   }
@@ -1030,7 +1055,14 @@ export async function runCli(
   // restore
   let id = options.id;
   if (id === undefined) {
-    const picked = pickDefaultSnapshotId(await listSnapshots(dataDir));
+    // 与 snapshots 同一口径：读不出来时如实打印（restore 的退出语义不变 —— 拿不到候选快照即拒绝执行）。
+    const probe: { unreadable?: string } = {};
+    const picked = pickDefaultSnapshotId(await listSnapshots(dataDir, probe));
+    if (probe.unreadable !== undefined) {
+      io.error(probe.unreadable);
+      io.error('读不到 ≠ 没有快照：恢复拒绝在「不知道有哪些快照」的状态下继续。/ unreadable is not the same as no snapshots; refusing to restore');
+      return 1;
+    }
     if (picked === null) {
       io.error('没有可用快照（无快照或全部已回滚）/ no usable snapshot (none or all rolled-back)');
       return 1;
@@ -1059,7 +1091,8 @@ export async function runCli(
   }
   // Phase 3 SAFE MODE：存在未恢复 transaction → 拒绝 destructive（CLI 不旁路 SAFE MODE）。
   // 候选根与真实 restore 的锁目录/journal 根同源（均为 <root> = dirname(快照目录) 的那一族）。
-  const safeMsg2 = checkSafeModeBlocked(resolveControlRoots({ dataRoot: options.dataRoot, dataDir: options.dataDir }, env));
+  const controlRoots = resolveControlRoots({ dataRoot: options.dataRoot, dataDir: options.dataDir }, env);
+  const safeMsg2 = checkSafeModeBlocked(controlRoots);
   if (safeMsg2 !== null) {
     io.error(`拒绝执行：${safeMsg2}`);
     return 1;
@@ -1076,12 +1109,25 @@ export async function runCli(
     // Phase 3 P0-A：CLI restore 也创建 durable journal（关闭 bypass）。
     const recovery = new Phase3Recovery({ dataDir: path.dirname(dataDir), packageVersion: '0.1.0', fingerprintDataDir: path.dirname(dataDir) });
     await recovery.initFingerprint().catch(() => undefined);
-    const report = await runWithMutationLock(lock, { op: 'cli-restore', target: id }, async (lockCtx) => {
-      if (lockCtx !== null) {
-        return (await recovery.runJournaled({ operationType: 'cli-restore', lockCtx, fn: () => restore(restoreOptions) })).result;
-      }
-      return restore(restoreOptions);
+    const outcome = await runWithMutationLock(lock, { op: 'cli-restore', target: id }, async (lockCtx) => {
+      // 第三道门（与救急台 actions.ts 的 checkWriteGates 同源、同序：SAFE MODE → 残留锁 → DSH 未运行）：
+      // 恢复会覆盖/删除 $DSH_HOME 下**正在被实例使用**的文件。放在持有环境锁之后，于是「残留锁」仍先于它报出。
+      const running = await readRunningInstances(controlRoots);
+      if (running.length > 0) return { kind: 'dsh-running' as const, running };
+      return {
+        kind: 'restore' as const,
+        report: lockCtx !== null
+          ? (await recovery.runJournaled({ operationType: 'cli-restore', lockCtx, fn: () => restore(restoreOptions) })).result
+          : await restore(restoreOptions),
+      };
     });
+    if (outcome.kind === 'dsh-running') {
+      io.error('检测到 DSH 正在运行（' + outcome.running.map((i) => i.name + ' pid=' + String(i.pid)).join('、')
+        + '）：请先关闭 DSH 再执行恢复 —— 恢复会覆盖/删除 $DSH_HOME 下正在使用的文件。');
+      io.error('如 DSH 已起不来（无法正常关闭），改用本机救急台：dcm web（「恢复」页与 CLI 同一实现，可先停实例/回收残留锁）。');
+      return 1;
+    }
+    const report = outcome.report;
     printReport(report, io);
     return report.failed.length > 0 ? 1 : 0;
   } catch (err) {
@@ -1095,15 +1141,54 @@ export async function runCli(
 
 /* ------------------------------------------------------------ web：离线只读救急台 */
 
+/** 救急台的目录事实（由 --data-dir / --data-root 统一派生；四处只认这一份）。 */
+export interface WebPaths {
+  /** 插件数据根（快照/导出/锁都挂在它下面） */
+  root: string
+  /** 与 root 同值（RescuePaths.dataDir 的语义） */
+  dataDir: string
+  snapshotsDir: string
+  exportsDir: string
+  locksDir: string
+  controlRoots: string[]
+}
+
+/**
+ * 派生救急台要用的四个目录 —— **root 只算一次**，再同时派生 snapshots / exports / locks / dataDir。
+ *
+ * 为什么必须统一：`--data-dir` 的历史语义是「快照目录 / 导出目录」，尾段命中 `snapshots`/`exports`
+ * 时要**上溯一层**才是数据根。此前只对「那一条」取原值、另一条仍 `path.join(dataDir, ...)`，
+ * 于是 `--data-dir <root>/snapshots` 会派生出 `<root>/snapshots/exports`（半上溯）——
+ * 命令行与网页看到的目录事实立刻分叉。`--data-root` 恒为准。
+ */
+export function resolveWebPaths(
+  opts: { dataRoot?: string; dataDir?: string } = {},
+  env: Record<string, string | undefined> = process.env,
+): WebPaths {
+  const explicitRoot = opts.dataRoot !== undefined && opts.dataRoot !== '' ? path.resolve(opts.dataRoot) : undefined;
+  const explicitDataDir = opts.dataDir !== undefined && opts.dataDir !== '' ? path.resolve(opts.dataDir) : undefined;
+  const root = explicitRoot
+    ?? (explicitDataDir === undefined
+      ? path.join(resolveDshHome(env), 'dsh-config-manager')
+      : ['snapshots', 'exports'].includes(path.basename(explicitDataDir))
+        ? path.dirname(explicitDataDir)
+        : explicitDataDir);
+  return {
+    root,
+    dataDir: root,
+    snapshotsDir: path.join(root, 'snapshots'),
+    exportsDir: path.join(root, 'exports'),
+    locksDir: path.join(root, 'locks'),
+    controlRoots: resolveControlRoots({ dataRoot: explicitRoot, dataDir: explicitDataDir }, env),
+  };
+}
+
 /**
  * 启动离线救急台（**只读**）。
  *
  * 为什么目录要在这一侧解析：`--data-dir / --data-root` 的既有语义只有本文件的 resolve* 系列说了算——
  * 网页与各子命令必须看到同一份目录事实，否则迟早出现「命令行说没有、网页说有一个」的分叉。
- * 这里统一按**控制面根**派生（`<root>/snapshots` 与 `<root>/exports`）。`--data-dir` 的历史语义是
- * 「快照目录 / 导出目录」，所以尾段命中 `snapshots` / `exports` 时会**上溯一层**再派生
- * （否则 <root>/snapshots 会变成 <root>/snapshots/snapshots，快照列表恒空 —— 验收 F6）；
- * `--data-root` 仍恒为准。
+ * 目录派生统一走 `resolveWebPaths()`（`--data-dir` 尾段命中 snapshots/exports 时上溯一层；`--data-root` 恒为准）。
  *
  * 服务端只绑 127.0.0.1，端口缺省 0（内核分配）；启动后打印带一次性 token 的 URL 并打开浏览器。
  */
@@ -1113,21 +1198,8 @@ async function runWeb(
   env: Record<string, string | undefined>,
 ): Promise<number> {
   const homeDir = options.home ?? resolveDshHome(env);
-  const controlRoots = resolveControlRoots({ dataRoot: options.dataRoot, dataDir: options.dataDir }, env);
-  const dataDir = controlRoots[0] ?? path.join(homeDir, 'dsh-config-manager');
-  // --data-dir 的历史语义是「快照目录 / 导出目录」：用户按该语义传 <root>/snapshots 时，
-  // 不能把它本身当作数据根（否则会派生出 <root>/snapshots/snapshots，真实快照必然看不见 —— 验收 F6）。
-  // 尾段命中 snapshots / exports 就上溯一层；显式 --data-root 仍以它为准。
-  const resolvedSnapshotsDir = options.dataRoot === undefined
-    && options.dataDir !== undefined
-    && ['snapshots', 'exports'].includes(path.basename(path.resolve(options.dataDir)))
-    ? path.resolve(options.dataDir)
-    : path.join(dataDir, 'snapshots');
-  const snapshotsDir = resolvedSnapshotsDir;
-  const exportsDir = options.dataDir !== undefined && path.basename(path.resolve(options.dataDir)) === 'exports'
-    ? path.resolve(options.dataDir)
-    : path.join(dataDir, 'exports');
-  const locksDir = resolveRecoverLocksDir({ dataRoot: options.dataRoot, dataDir: options.dataDir }, env);
+  const { dataDir, snapshotsDir, exportsDir, locksDir, controlRoots } =
+    resolveWebPaths({ dataRoot: options.dataRoot, dataDir: options.dataDir }, env);
   // 懒加载：http 服务端代码不进其他子命令（尤其 reinstall/restore 的救急路径）的启动链路
   const { startConsoleServer } = await import('./web/server.ts');
   const server = await startConsoleServer({
@@ -1139,6 +1211,9 @@ async function runWeb(
       locksDir,
       controlRoots,
       profile: options.profile,
+      // 离线导出的 manifest.exporter.version 用**真实 CLI 版本**（与 backup 同一口径），
+      // 不再写死 'rescue-console' —— 那会让产物声称一个不存在的导出器版本。
+      exporterVersion: CLI_EXPORTER_VERSION,
     },
     version: CLI_EXPORTER_VERSION,
     port: options.port ?? 0,

package/src/cli/sessions-inspect.test.ts

@@ -82,9 +82,23 @@ test('T6 CLI：--json 给机器可读结果（readOnly 声明 + summary + rows
     const { lines, io } = collect();
     const code = await runSessionsInspect({ home, action: 'list', json: true }, io);
     assert.equal(code, 0);
-    const parsed = JSON.parse(lines.join('\n')) as { readOnly: boolean; rows: unknown[]; summary: { total: number } };
+    const parsed = JSON.parse(lines.join('\n')) as { ok: boolean; readOnly: boolean; rows: unknown[]; summary: { total: number } };
     assert.equal(parsed.readOnly, true, '输出必须声明只读');
+    assert.equal(parsed.ok, true, '无阻断问题 → ok 与退出码（0）同源');
     assert.equal(parsed.summary.total, 1);
     assert.equal(parsed.rows.length, 1);
   });
 });
+
+test('T6 CLI：--json 的 ok 与退出码同源（有不可加载会话时为 false，不再恒 true）', { skip: !CAPABLE }, async () => {
+  await withTmp(async (home) => {
+    const dir = path.join(home, 'sessions', KEY, 'broken');
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(path.join(dir, 'session.jsonl.zstd'), Buffer.from('not zstd'));
+    const { lines, io } = collect();
+    const code = await runSessionsInspect({ home, action: 'doctor', json: true }, io);
+    assert.equal(code, 1, '存在不可加载会话 → 退出码 1');
+    const parsed = JSON.parse(lines.join('\n')) as { ok: boolean };
+    assert.equal(parsed.ok, false, 'ok 必须与退出码同源（此前恒 true，机器消费者只会信错一个）');
+  });
+});

package/src/cli/sessions-inspect.ts

@@ -67,7 +67,9 @@ export async function runSessionsInspect(options: SessionsInspectOptions, io: Se
   const blocking = result.summary.bySeverity.blocksStartup + result.summary.bySeverity.unloadable;
   if (options.json) {
     io.log(JSON.stringify({
-      ok: true,
+      // ok 与退出码**同源**（0 ⟺ 无阻断级问题）：此前恒 true，存在不可加载会话时
+      // CI 会看到 ok:true 而退出码 1 —— 两个字段互相矛盾，机器消费者只会信错一个。
+      ok: blocking === 0,
       readOnly: true,
       sessionsDir: result.sessionsDir,
       summary: { ...result.summary, untested: result.untested, unreadableEntries: result.unreadableEntries },

package/src/cli/sessions-repair.test.ts

@@ -0,0 +1,84 @@
+/**
+ * CLI 会话修复（`sessions repair`）的「读不到 ≠ 没有会话」回归。
+ *
+ * 修前：会话根**存在但读不出来**（ENOTDIR / EACCES…）时 scanSessions 只返回空列表，
+ * 于是打印「无需修复」+ exit 0 —— 把扫描失败说成了「没问题」，--json 还会回 ok:true。
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import { runSessionsRepair } from './sessions-repair.ts';
+
+interface Collected {
+  lines: string[];
+  errors: string[];
+  io: { log: (line: string) => void; error: (line: string) => void };
+}
+
+function collect(): Collected {
+  const lines: string[] = [];
+  const errors: string[] = [];
+  return { lines, errors, io: { log: (l) => lines.push(l), error: (l) => errors.push(l) } };
+}
+
+async function withTmp<T>(fn: (dir: string) => Promise<T>): Promise<T> {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'cm-cli-repair-'));
+  try {
+    return await fn(dir);
+  } finally {
+    await fs.rm(dir, { recursive: true, force: true });
+  }
+}
+
+const base = { fix: false, maps: [] as string[], json: false };
+
+test('RP-01 会话根存在但读不出来 → exit 1，明说「读不到 ≠ 没有会话」，绝不打印「无需修复」', async () => {
+  await withTmp(async (home) => {
+    // 用普通文件占住 <home>/sessions：exists() 为真，readdir 必失败（ENOTDIR）。
+    await fs.writeFile(path.join(home, 'sessions'), 'not a directory', 'utf8');
+    const { lines, errors, io } = collect();
+    const code = await runSessionsRepair({ home, ...base }, io);
+    assert.equal(code, 1, '读不出来必须非 0');
+    const text = lines.join('\n') + '\n' + errors.join('\n');
+    assert.match(text, /读不到/, '必须明说读不到');
+    assert.match(text, /读不到 ≠ 没有会话/);
+    assert.doesNotMatch(lines.join('\n'), /无需修复/, '不得把扫描失败说成「无需修复」');
+  });
+});
+
+test('RP-02 同一情形下 --json 不得回 ok:true', async () => {
+  await withTmp(async (home) => {
+    await fs.writeFile(path.join(home, 'sessions'), 'not a directory', 'utf8');
+    const { lines, io } = collect();
+    const code = await runSessionsRepair({ home, ...base, json: true }, io);
+    assert.equal(code, 1);
+    assert.equal(lines.length, 1, '--json 必须给出唯一一段机器可读输出');
+    const parsed = JSON.parse(lines[0]!) as { ok: boolean; rootReadable: boolean; error?: string };
+    assert.equal(parsed.ok, false, '读不出来时 ok 必须为 false');
+    assert.equal(parsed.rootReadable, false);
+    assert.equal(typeof parsed.error, 'string');
+    assert.doesNotMatch(lines[0]!, /"ok": true/);
+  });
+});
+
+test('RP-03 会话根存在且可读但为空 → 仍照旧「无需修复」+ exit 0（不误伤正常路径）', async () => {
+  await withTmp(async (home) => {
+    await fs.mkdir(path.join(home, 'sessions'), { recursive: true });
+    const { lines, io } = collect();
+    const code = await runSessionsRepair({ home, ...base }, io);
+    assert.equal(code, 0);
+    assert.match(lines.join('\n'), /无需修复/);
+  });
+});
+
+test('RP-04 会话根不存在 → exit 1 且提示用 --home 指对位置（既有语义不变）', async () => {
+  await withTmp(async (home) => {
+    const { errors, io } = collect();
+    const code = await runSessionsRepair({ home, ...base }, io);
+    assert.equal(code, 1);
+    assert.match(errors.join('\n'), /找不到会话根目录/);
+  });
+});

package/src/cli/sessions-repair.ts

@@ -67,19 +67,31 @@ export function parseRepairMaps(maps: readonly string[]): { mappings: PathMappin
   return { mappings, errors };
 }
 
-/** 扫描 <home>/sessions：projectKey 段 → 会话目录 → 首帧 cwd。任何读不出的都如实记为「无法判定」。 */
-async function scanSessions(sessionsRoot: string, io: SessionsRepairIo): Promise<ScannedSession[]> {
+/** 一次扫描的结果：会话清单 + **会话根本身是否读得出来**（后者与「没有会话」是两件事）。 */
+interface ScanResult {
+  sessions: ScannedSession[];
+  /** false = readdir 会话根失败（ENOTDIR / EACCES…）：此时 sessions 必为空，但**不等于没有会话** */
+  rootReadable: boolean;
+}
+
+/**
+ * 扫描 <home>/sessions：projectKey 段 → 会话目录 → 首帧 cwd。任何读不出的都如实记为「无法判定」。
+ *
+ * 返回值里必须带 rootReadable：会话根存在但读不出来时，空列表只能说明「扫描失败」，
+ * 调用方据此拒绝给出「无需修复」+ exit 0（读不到 ≠ 无会话 —— 验收 F2 同口径）。
+ */
+async function scanSessions(sessionsRoot: string, io: SessionsRepairIo): Promise<ScanResult> {
   const out: ScannedSession[] = [];
   let projectDirs: import('node:fs').Dirent[];
   try {
     projectDirs = await fs.readdir(sessionsRoot, { withFileTypes: true });
   } catch (error) {
     // 会话根不是目录 / 读不出来（ENOTDIR、EACCES…）：绝不能把裸异常抛给调用方
-    // （救急台会因此吐一段 Node 原始 JSON 500 —— 验收 F3）。如实报错并返回空扫描结果。
+    // （救急台会因此吐一段 Node 原始 JSON 500 —— 验收 F3）。如实报错并标记「根不可读」。
     const code = (error as { code?: string }).code;
     io.error('会话根读不出来 / sessions root not readable（' + String(code ?? 'unknown') + '）: ' + sessionsRoot);
     io.error(error instanceof Error ? error.message : String(error));
-    return out;
+    return { sessions: out, rootReadable: false };
   }
   for (const entry of projectDirs) {
     if (!entry.isDirectory()) continue;
@@ -112,7 +124,7 @@ async function scanSessions(sessionsRoot: string, io: SessionsRepairIo): Promise
       });
     }
   }
-  return out;
+  return { sessions: out, rootReadable: true };
 }
 
 /** 隔离目录：同一轮修复一个时间戳目录；**只搬不删**（用户可自行处理）。 */
@@ -137,8 +149,22 @@ export async function runSessionsRepair(options: SessionsRepairOptions, io: Sess
   for (const error of parsed.errors) io.error(error);
   if (parsed.errors.length > 0) return 1;
 
-  const scanned = await scanSessions(sessionsRoot, io);
-  const plan = planSessionRepair(scanned, {
+  const scan = await scanSessions(sessionsRoot, io);
+  if (!scan.rootReadable) {
+    // 「读不到」≠「没有会话」：根存在但读不出来时，空扫描结果只说明**扫描失败** ——
+    // 绝不能给出「无需修复」+ exit 0（那等于把「读不到」说成「没问题」），--json 也不得回 ok:true。
+    const message = '会话根存在但读不出来：读不到 ≠ 没有会话 / sessions root exists but is unreadable; '
+      + 'unreadable is not the same as no sessions: ' + sessionsRoot;
+    io.error(message);
+    if (options.json) {
+      io.log(JSON.stringify({
+        ok: false, rootReadable: false, dryRun: options.fix !== true,
+        home: options.home, root: sessionsRoot, error: message,
+      }, null, 2));
+    }
+    return 1;
+  }
+  const plan = planSessionRepair(scan.sessions, {
     mappings: parsed.mappings,
     ...(options.keep !== undefined ? { keep: options.keep } : {}),
   });