dsh-config-manager 0.1.71 → 0.1.72

package/src/adapters/sessions.ts

@@ -10,6 +10,8 @@
 import { FileCollectionAdapter } from './file-collection.ts';
 import { listFilesDetailed } from './link-report.ts';
 import { msgOf } from '../core/messages.ts';
+// t6：注册 adapters 域追加目录（本模块只消费注入的 msg，故只引它的注册副作用）。
+import './messages.ts';
 import { groupSessionUnits, isSessionLogFileName, normalizeSessionLimit, pickLatestSessionUnits, sessionIdKey } from '../core/session-select.ts';
 import { projectKeyOf } from '../core/session-meta.ts';
 import { applyPathMapping } from '../core/path-mapping.ts';
@@ -367,7 +369,7 @@ export class SessionsAdapter extends FileCollectionAdapter {
       if (present.has(sessionIdKey(next.sessionId))) continue;
       const dirRel = await this.findSessionDir(ctx, next.sessionId, next.key, allKeys);
       if (dirRel === null) {
-        uncoupled.push(next.sessionId + '（' + msg('export.sessionRelationNotFound') + '）');
+        uncoupled.push(msg('adapter.sessionUncoupledNote', { id: next.sessionId, reason: msg('export.sessionRelationNotFound') }));
         continue;
       }
       const listing = await listFilesDetailed(ctx.fs, dirRel);
@@ -381,7 +383,7 @@ export class SessionsAdapter extends FileCollectionAdapter {
         loaded.push({ relativePath: this.relPathOf(rel), data, contentHash: sha256Hex(data) });
       }
       if (tooLarge || loaded.length === 0) {
-        uncoupled.push(next.sessionId + '（' + msg('export.sessionParentTooLarge') + '）');
+        uncoupled.push(msg('adapter.sessionUncoupledNote', { id: next.sessionId, reason: msg('export.sessionParentTooLarge') }));
         continue;
       }
       usedBytes += unitBytes;

package/src/adapters/settings.test.ts

@@ -6,7 +6,8 @@ import test from 'node:test';
 import assert from 'node:assert/strict';
 import { SettingsAdapter } from './settings.ts';
 import { makeContext, makeImportContext } from './test-helpers.ts';
-import type { PlanItem } from '../core/types.ts';
+import type { PlanItem, SensitiveHit } from '../core/types.ts';
+import { createSecretScanner } from '../security/secret-scanner.ts';
 
 const NS = ['general', 'theme', 'llm-deepseek'];
 
@@ -176,3 +177,39 @@ test('settings: describeAll 抛错时退回逐名路径（快路径失败不得
   assert.deepEqual(out.warnings, []);
 });
 
+test('settings: value/base 共享同一嵌套对象不得触发强化 scanner 的循环误报（用户上报 2026-10-09）', async () => {
+  const ctx = makeContext('win32', 'C:\\Users\\alice');
+  // 真实 DSH 的 describe() 同时回传 value（生效值）与 base（组合层）：未被用户覆盖的嵌套分组在两处是
+  // 同一个对象 → 导出结构里出现 DAG 共享引用。旧版全局 visited 判环会把它读成
+  // 「检测到循环引用，无法扫描（路径 namespaces.<ns>.value.<key>）」，整次备份失败。
+  const dream = { enabled: true, idleMinutes: 180, apiKey: 'sk-live-abcdefgh12345' };
+  ctx.settings.ns.set('meow-memory', {
+    value: { promptLang: 'zh', dream },
+    base: { promptLang: 'zh', dream },
+    revision: 3,
+    secrets: [],
+  });
+  const adapter = new SettingsAdapter(['meow-memory']);
+  const exported = await adapter.export(ctx, { includeSecrets: false });
+  const rec = exported.data.namespaces['meow-memory'];
+  // 前置条件：导出的 value/base 确实共享同一个对象（否则这条测试没覆盖到目标形态）
+  assert.strictEqual(
+    (rec?.value as { dream?: unknown } | undefined)?.dream,
+    (rec?.base as { dream?: unknown } | undefined)?.dream,
+    'value/base 必须共享同一 dream 对象',
+  );
+
+  const scanner = createSecretScanner();
+  let scanned: { sanitized: unknown; hits: SensitiveHit[] } | undefined;
+  assert.doesNotThrow(() => { scanned = scanner.scanAndRedact(exported.data); }, '共享引用不得被误判为循环');
+  const outRec = (scanned!.sanitized as {
+    namespaces: Record<string, { value: { dream: Record<string, unknown> }; base: { dream: Record<string, unknown> } }>;
+  }).namespaces['meow-memory']!;
+  // 两个分支都要在，且各自完成脱敏（不能因为共享就丢分支或漏剥）
+  assert.equal(outRec.value.dream['apiKey'], '', 'value 分支脱敏');
+  assert.equal(outRec.base.dream['apiKey'], '', 'base 分支脱敏');
+  assert.equal(outRec.value.dream['idleMinutes'], 180, '非敏感字段保留');
+  assert.ok(scanned!.hits.some((h) => h.path === 'namespaces.meow-memory.value.dream.apiKey'));
+  assert.ok(scanned!.hits.some((h) => h.path === 'namespaces.meow-memory.base.dream.apiKey'));
+});
+

package/src/adapters/ui.test.ts

@@ -3,7 +3,7 @@
  */
 import test from 'node:test';
 import assert from 'node:assert/strict';
-import { UiAdapter, isUiNamespace, UI_MIGRATION_NOTES } from './ui.ts';
+import { UiAdapter, isUiNamespace, uiMigrationNotes } from './ui.ts';
 import { makeContext, makeImportContext } from './test-helpers.ts';
 
 const NS = ['general', 'theme', 'pet', 'dsh-better-sidebar', 'llm-deepseek'];
@@ -32,7 +32,7 @@ test('ui: 导出只含 UI namespace + uiMigrationNotes（纯说明）', async ()
   assert.equal(out.counts.namespaces, 2);
   assert.ok(out.data.uiMigrationNotes.length >= 1);
   assert.equal(out.data.uiMigrationNotes[0]?.migratable, false);
-  assert.equal(UI_MIGRATION_NOTES.length, out.data.uiMigrationNotes.length);
+  assert.equal(uiMigrationNotes().length, out.data.uiMigrationNotes.length);
 
   const v = await adapter.validate(out.data);
   assert.equal(v.valid, true);

package/src/adapters/ui.ts

@@ -3,9 +3,10 @@
  * 数据源 = settings.yaml 中「UI 类」namespace（pet / dsh-better-sidebar / remote-web-ui / ui-onboarding / skin 等）。
  * localStorage 等 Host 不可迁移的 UI 状态以 uiMigrationNotes 纯说明形式导出（不含任何值）。
  */
-import type { NamespaceRecord, UiSection } from '../schema/types.ts';
+import type { NamespaceRecord, UiMigrationNote, UiSection } from '../schema/types.ts';
 import { zhMsg } from '../core/messages.ts';
 import type { MsgFunc } from '../core/messages.ts';
+import { engineMsg } from './messages.ts';
 import type {
   ApplyResult, ConfigAdapter, ExportOptions, ExportSection, HostContext,
   ImportContext, PlanItem, ValidationResult,
@@ -34,31 +35,30 @@ export function isUiNamespace(name: string): boolean {
   return KNOWN_UI_NAMESPACE_PREFIXES.some((p) => lower.startsWith(p.toLowerCase()));
 }
 
-/** localStorage 等 Host 无通道的 UI 状态说明（纯说明，不含值；研究报告 §2.2/§4.4） */
-export const UI_MIGRATION_NOTES: UiSection['uiMigrationNotes'] = [
-  {
-    plugin: 'dsh-task-board',
-    storage: 'localStorage',
-    key: 'dsh.taskBoard.v1',
-    migratable: false,
-    reason: '任务看板数据存于浏览器 localStorage，Host 侧无访问通道，需在目标机器重新配置',
-  },
-  {
-    plugin: 'dsh-aionui-panel',
-    storage: 'localStorage',
-    key: 'aionui-panel.*',
-    migratable: false,
-    reason: '面板宽度/折叠状态存于浏览器 localStorage，Host 侧无访问通道，需在目标机器重新配置',
-  },
-  {
-    plugin: 'dsh-client-ui-*',
-    storage: 'localStorage',
-    key: '*',
-    migratable: false,
-    reason: '浏览器端 UI 状态无法经 Host API 迁移',
-  },
+/**
+ * localStorage 等 Host 无通道的 UI 状态说明（纯说明，不含值；研究报告 §2.2/§4.4）。
+ *
+ * t6（英文界面零中文）：说明行的 `reason` 是用户可见文案 ⇒ 表里只放**目录键**，取文案在导出期现取
+ * （`uiMigrationNotes(msg)`）—— 这样导出的说明行跟随界面语言，而不是冻结在装配期语言。
+ * （表本身是数据；中文只存在于 adapters 域的追加目录 `src/adapters/messages.ts`。）
+ */
+const UI_MIGRATION_NOTE_ROWS: ReadonlyArray<Omit<UiMigrationNote, 'reason'> & { reasonKey: string }> = [
+  { plugin: 'dsh-task-board', storage: 'localStorage', key: 'dsh.taskBoard.v1', migratable: false, reasonKey: 'adapter.uiLocalStorageTaskBoard' },
+  { plugin: 'dsh-aionui-panel', storage: 'localStorage', key: 'aionui-panel.*', migratable: false, reasonKey: 'adapter.uiLocalStoragePanel' },
+  { plugin: 'dsh-client-ui-*', storage: 'localStorage', key: '*', migratable: false, reasonKey: 'adapter.uiLocalStorageGeneric' },
 ];
 
+/** UI 迁移说明行（取文案在调用期现取；缺省 = 当前引擎语言的 engineMsg）。 */
+export function uiMigrationNotes(msg: MsgFunc = engineMsg): UiSection['uiMigrationNotes'] {
+  return UI_MIGRATION_NOTE_ROWS.map((row) => ({
+    plugin: row.plugin,
+    storage: row.storage,
+    key: row.key,
+    migratable: row.migratable,
+    reason: msg(row.reasonKey),
+  }));
+}
+
 export class UiAdapter implements ConfigAdapter<UiSection> {
   readonly id = 'ui' as const;
   // 元数据唯一来源 = 注册表（t31）：不再与 ui/export-flow.ts 的导出目录各写一份
@@ -76,10 +76,11 @@ export class UiAdapter implements ConfigAdapter<UiSection> {
     const all = await resolveNamespaces(this.namespaces, ctx);
     const uiNames = all.filter((n) => isUiNamespace(n));
     const namespaces: Record<string, NamespaceRecord> = await collectNamespaceRecords(ctx, uiNames, warnings);
+    const notes = uiMigrationNotes(ctx.msg);
     return {
       sectionId: 'ui',
-      data: { version: 1, namespaces, uiMigrationNotes: UI_MIGRATION_NOTES },
-      counts: { namespaces: Object.keys(namespaces).length, notes: UI_MIGRATION_NOTES.length },
+      data: { version: 1, namespaces, uiMigrationNotes: notes },
+      counts: { namespaces: Object.keys(namespaces).length, notes: notes.length },
       warnings,
     };
   }

package/src/adapters/workspaces.ts

@@ -8,6 +8,8 @@ import { isDeepStrictEqual } from 'node:util';
 import { normalizePath } from '../utils/paths.ts';
 import { zhMsg } from '../core/messages.ts';
 import type { MsgFunc } from '../core/messages.ts';
+// t6：注册 adapters 域追加目录（本模块只消费注入的 msg，故只引它的注册副作用）。
+import './messages.ts';
 import type { WorkspaceRecord, WorkspacesSection } from '../schema/types.ts';
 import type {
   ApplyResult, ConfigAdapter, ExportOptions, ExportSection, ExportUnit, HostContext,
@@ -214,14 +216,16 @@ export class WorkspacesAdapter implements ConfigAdapter<WorkspacesSection> {
       // 目标端无法写入（如路径 realpath 失败/目录不存在）→ 非致命警告（§34.17），
       // 不触发整体回滚——否则一个失效路径会拖垮已成功导入的其余配置。
       const reason = err instanceof Error ? err.message : String(err);
-      const detail = notes.length > 0 ? '（' + notes.join('；') + '）' : '';
+      const detail = notes.length > 0
+        ? ctx.msg('adapter.workspaceNotesParen', { notes: notes.join(ctx.msg('adapter.listSeparator')) })
+        : '';
       return {
         ok: false,
         warning: true,
         message: ctx.msg('adapter.workspaceWriteFailed', { ref, msg: reason }) + detail,
       };
     }
-    return { ok: true, ...(notes.length > 0 ? { message: notes.join('；') } : {}) };
+    return { ok: true, ...(notes.length > 0 ? { message: notes.join(ctx.msg('adapter.listSeparator')) } : {}) };
   }
 
   /**
@@ -431,7 +435,7 @@ async function registerImportedSessions(
   const outsideNote = outsideFailed > 0
     ? ctx.msg('adapter.workspaceSessionsOutsideBundle', { count: String(outsideFailed) })
     : '';
-  const compose = (head: string): string => (outsideNote === '' || head === '' ? head + outsideNote : head + '；' + outsideNote);
+  const compose = (head: string): string => (outsideNote === '' || head === '' ? head + outsideNote : head + ctx.msg('adapter.listSeparator') + outsideNote);
   if (bundledFailed > 0) {
     return {
       message: compose(ctx.msg('adapter.workspaceSessionsPending', {

package/src/cli/actions.test.ts

@@ -20,6 +20,8 @@ import {
   sessionRepairRowMessage, sessionVerifyNoteOf, stopProfile, unlockEncryptedBackup, type SessionLogRepairRow,
 } from './actions.ts'
 import type { SessionVerifyResult } from '../utils/session-verify.ts'
+import { parseZip } from '../utils/zip.ts'
+import { MANIFEST_FILE } from '../schema/manifest.ts'
 
 async function withTmp<T>(fn: (dir: string) => Promise<T>): Promise<T> {
   const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'dcm-actions-'))
@@ -400,6 +402,32 @@ test('V4-01 离线导出：真的产出 ZIP 并自检通过；不可收集的分
   })
 })
 
+test('V4-01b 离线导出的 manifest.exporter.version 用真实版本（不再写死 rescue-console）', async () => {
+  await withTmp(async (tmp) => {
+    const home = path.join(tmp, 'home')
+    await fs.mkdir(path.join(home, 'skills', 'demo'), { recursive: true })
+    await fs.writeFile(path.join(home, 'skills', 'demo', 'SKILL.md'), '# demo\n')
+    const dataDir = path.join(home, 'dsh-config-manager')
+    const paths = {
+      homeDir: home, dataDir,
+      snapshotsDir: path.join(dataDir, 'snapshots'),
+      exportsDir: path.join(dataDir, 'exports'),
+      locksDir: path.join(dataDir, 'locks'),
+      controlRoots: [dataDir],
+      profile: 'web',
+      exporterVersion: '9.9.9-test',
+    }
+    const result = await exportOfflineBackup(paths, ['skills'])
+    assert.equal(result.ok, true, result.message)
+    const buf = await fs.readFile(result.outPath!)
+    const manifest = JSON.parse(
+      Buffer.from(parseZip(buf).readEntry(MANIFEST_FILE)).toString('utf8'),
+    ) as { exporter?: { name?: string; version?: string } }
+    assert.equal(manifest.exporter?.version, '9.9.9-test', 'manifest 必须写调用方注入的真实版本')
+    assert.notEqual(manifest.exporter?.version, 'rescue-console', '不得再写死假的导出器版本')
+  })
+})
+
 test('V4-02 解锁：非加密文件如实报 not-encrypted（绝不谎报解锁成功）', async () => {
   await withTmp(async (tmp) => {
     const exportsDir = path.join(tmp, 'exports')

package/src/cli/actions.ts

@@ -306,6 +306,12 @@ export interface RescuePaths {
   locksDir: string
   controlRoots: readonly string[]
   profile: string
+  /**
+   * 离线导出的 manifest.exporter.version（CLI 传真实版本；缺省 = 中性占位）。
+   * 为什么不在这里再算一次版本：actions.ts 不得 import ./index.ts（会成环），
+   * 而版本号只有 CLI 侧从 package.json 读得到 —— 由 runWeb 经本结构注入。
+   */
+  exporterVersion?: string
 }
 
 export interface RescueStatus {
@@ -419,7 +425,9 @@ export type WriteGateOutcome = { ok: true } | WriteGateRefusal
 /**
  * 写动作的前置门（与 CLI `sessions repair --fix` 同一判据）。
  *
- * `needsDshStopped`：只有**改写会话字节**的动作才需要「DSH 已停」这一条（清理缓存不需要）。
+ * `needsDshStopped`：**改写/搬动会话字节**的动作（会话布局归位 repairSessions、字节级就地修复
+ * repairSessionLogInline）与**快照恢复**（runSnapshotRestore 会覆盖/删除 `$DSH_HOME` 下正在使用的文件）
+ * 都要「DSH 已停」这一条；磁盘清理不需要（只碰可重建缓存）。
  */
 export async function checkWriteGates(
   controlRoots: readonly string[],
@@ -1356,7 +1364,8 @@ export async function exportOfflineBackup(
     }
     const checksums = buildChecksums(collection.entries)
     const manifest = buildManifest({
-      exporterVersion: 'rescue-console',
+      // 真实版本（runWeb 经 RescuePaths 注入）；拿不到时给中性占位，绝不谎报某个具体版本。
+      exporterVersion: paths.exporterVersion ?? '0.0.0-unknown',
       // 离线探测不到真实 DSH 版本：如实标注，不谎报
       dshVersion: 'cli-offline',
       platform: process.platform as never,

package/src/cli/help.ts

@@ -155,7 +155,7 @@ export const COMMAND_HELP: readonly CommandHelp[] = [
     title: '离线救急台（本机网页）',
     usage: 'web',
     summary: '离线救急台：只读诊断 + 逐项确认的修复',
-    usageLines: ['web [--port <n>] [--no-open] [--home <dir>] [--data-root <dir>] [--idle-timeout <min>]'],
+    usageLines: ['web [--port <n>] [--no-open] [--home <dir>] [--data-dir <dir>] [--data-root <dir>] [--profile <name>] [--idle-timeout <min>]'],
     description: [
       '启动一个只绑 127.0.0.1 的本机网页，把诊断与修复动作摆成能点的界面：',
       '实例心跳 / SAFE MODE / 残留锁 / 快照 / 备份自检 / 磁盘占用 / 会话体检 / 档案实例。',
@@ -171,7 +171,9 @@ export const COMMAND_HELP: readonly CommandHelp[] = [
           { flag: '--no-open', desc: '启动后不打开浏览器（SSH / 无桌面场景）' },
           { flag: '--idle-timeout <min>', desc: '空闲多少分钟自动退出（0 = 不自动退出；缺省 30）' },
           { flag: '--home <dir>', desc: '要查看的 DSH home（缺省 $DSH_HOME，即 ~/.dsh）' },
-          { flag: '--data-root <dir>', desc: '插件数据根 dataDir（自定义时必须显式传）' },
+          { flag: '--data-dir <dir>', desc: '快照 / 导出目录（历史语义）：尾段是 snapshots / exports 时按它的父目录当数据根，再派生 快照/导出/锁 三个目录；否则整条按数据根处理（缺省 $DSH_HOME/dsh-config-manager）' },
+          { flag: '--data-root <dir>', desc: '插件数据根 dataDir（自定义时必须显式传；给了就以它为准）' },
+          { flag: '--profile <name>', desc: '救急台操作的 DSH profile（缺省 web；影响「恢复」页的目标档案）' },
           { flag: '-h, --help', desc: '显示本页' },
         ],
       },
@@ -195,6 +197,7 @@ export const COMMAND_HELP: readonly CommandHelp[] = [
       '快照是每次导入前自动留下的整机配置副本；本命令只读，按新→旧列出：',
       'ID / 创建时间 / 来源 ZIP / 状态 / 条目数 / 宿主文件数 / 插件数。',
       '没有任何快照时打印「无快照」并照常返回 0。',
+      '目录存在却读不出来（权限 / 路径被文件占住）时，把事实打到 stderr 并以非 0 退出 —— 读不到 ≠ 没有快照。',
     ],
     sections: [
       {
@@ -204,7 +207,13 @@ export const COMMAND_HELP: readonly CommandHelp[] = [
           { flag: '-h, --help', desc: '显示本页' },
         ],
       },
-      { title: '退出码', entries: [{ flag: '0', desc: '列出成功（没有快照也是 0）' }] },
+      {
+        title: '退出码',
+        entries: [
+          { flag: '0', desc: '列出成功（目录不存在、没有快照也是 0）' },
+          { flag: '1', desc: '快照目录存在但读不出来（≠ 没有快照；原因打到 stderr）' },
+        ],
+      },
     ],
     examples: ['dcm snapshots', 'dcm snapshots --data-dir D:/rescue/snapshots'],
   },
@@ -213,7 +222,7 @@ export const COMMAND_HELP: readonly CommandHelp[] = [
     title: '只读自检备份 ZIP',
     usage: 'verify [<file|path>]',
     summary: '只读自检备份 ZIP（无参 = 导出目录全部）',
-    usageLines: ['verify [<file|path>] [--json] [--data-dir <dir>]'],
+    usageLines: ['verify [<file|path> | --id <file|path>] [--json] [--data-dir <dir>]'],
     description: [
       '重新读取备份 ZIP，核对结构与 integrity/checksums.json 的逐条 SHA-256；全程零写入。',
       '无参数时校验导出目录下全部 *.zip；也可以给一个文件名或完整路径。',
@@ -234,6 +243,7 @@ export const COMMAND_HELP: readonly CommandHelp[] = [
         title: '选项',
         entries: [
           { flag: '--json', desc: '机器可读输出（退出码仍为 0/1；出错的 JSON 也走 stdout）' },
+          { flag: '--id <file|path>', desc: '待校验目标（文件名或路径）；与位置参数同义，同时给出时以 --id 为准' },
           { flag: '--data-dir <dir>', desc: '导出目录（缺省 $DSH_HOME/dsh-config-manager/exports）' },
           { flag: '-h, --help', desc: '显示本页' },
         ],
@@ -330,8 +340,9 @@ export const COMMAND_HELP: readonly CommandHelp[] = [
     description: [
       '把配置恢复到该快照的状态：每个被覆盖或被删除的文件先拷到 <快照目录>/pre-restore/，以便反悔。',
       '不带 --id 时挑最近一个非 rolled-back 的快照；--dry-run 只打印计划，零写入。',
-      '真正执行前有两道门，任一不过就拒绝（没有 --force）：',
-      '  ① SAFE MODE 存在未恢复的 transaction；② 环境锁被别的任务持有。',
+      '真正执行前有三道门，任一不过就拒绝（没有 --force）：',
+      '  ① SAFE MODE 存在未恢复的 transaction；② 环境锁被别的任务持有；',
+      '  ③ 本机有 DSH 实例在跑（恢复会覆盖/删除它正在使用的文件）——关掉 DSH，或改用 dcm web 救急台。',
     ],
     sections: [
       {
@@ -350,7 +361,7 @@ export const COMMAND_HELP: readonly CommandHelp[] = [
         title: '退出码',
         entries: [
           { flag: '0', desc: '全部动作成功（--dry-run 恒 0）' },
-          { flag: '1', desc: '有失败步骤 / 没有可用快照 / id 非法 / SAFE MODE 或环境锁拒绝' },
+          { flag: '1', desc: '有失败步骤 / 没有可用快照 / 快照目录读不出来 / id 非法 / SAFE MODE、环境锁或「DSH 在跑」拒绝' },
         ],
       },
     ],
@@ -374,6 +385,8 @@ export const COMMAND_HELP: readonly CommandHelp[] = [
       '--map old=new 用于跨机恢复：命中前缀会先改写首帧 cwd，其余帧逐字节保留。',
       '--keep <dir> 处理重复 id：点名保留哪一份，其余移进 sessions/.cm-repair-quarantine-<时间戳>/（只搬不删）。',
       '写盘前会检查 DSH 是否在跑；在跑则拒绝，避免边读边改。',
+      '--json 的 ok 与退出码同源：0（无阻断级问题）时为 true，否则 false —— 两者不会互相矛盾。',
+      '会话根不存在或存在却读不出来时，repair 都如实报错并非 0 退出（读不到 ≠ 没有会话）。',
     ],
     sections: [
       {
@@ -398,9 +411,9 @@ export const COMMAND_HELP: readonly CommandHelp[] = [
       {
         title: '退出码',
         entries: [
-          { flag: '0', desc: '无阻断问题；repair 的 dry-run 恒 0' },
-          { flag: '1', desc: '有阻断问题；repair 的 --fix 有失败/冲突/回滚；参数错误' },
-          { flag: '2', desc: 'list / doctor 找不到会话根目录' },
+          { flag: '0', desc: '无阻断问题；repair 的 dry-run 恒 0（--json 的 ok 同时为 true）' },
+          { flag: '1', desc: '有阻断问题（--json 的 ok 为 false）；repair 的 --fix 有失败/冲突/回滚；repair 的会话根不存在或读不出来；参数错误' },
+          { flag: '2', desc: 'list / doctor 找不到会话根目录（repair 的同一情形是 1）' },
         ],
       },
     ],

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'));
+});