dsh-config-manager 0.1.71 → 0.1.73

package/src/core/recovery-orchestrator.ts

@@ -29,6 +29,7 @@ import {
 import { RunRegistry, type RunState } from './run-registry.ts';
 import type { HostContext, Snapshot } from './types.ts';
 import type { MsgFunc } from './messages.ts';
+import { engineMsg } from './messages-core.ts';
 
 /** 路由注入的恢复执行器（restore / rollback 引擎；测试注入 mock）。 */
 export interface RecoveryExecutorFns {
@@ -195,8 +196,8 @@ export function createRecoveryOrchestrator(deps: RecoveryOrchestratorDeps): Reco
         performRestore: executors.performRestore, performRollback: executors.performRollback,
       }, true);
       if (result === 'failed') {
-        runs.fail(runId, 'recovery 执行失败');
-        return { status: 400, body: { error: 'recovery 执行失败', runId } };
+        runs.fail(runId, engineMsg('core.recovery.executeFailed'));
+        return { status: 400, body: { error: engineMsg('core.recovery.executeFailed'), runId } };
       }
       runs.finish(runId, { decision: decisionKind, state: 'RECOVERING' });
       return { status: 200, body: { ok: true, operationId, decision: decisionKind, state: 'RECOVERING', runId } };
@@ -290,10 +291,10 @@ export function createRecoveryOrchestrator(deps: RecoveryOrchestratorDeps): Reco
       if (userConfirmed !== true) return { status: 400, body: { error: 'userConfirmed required' } };
       const j = await store.loadActive(operationId);
       if (j === null) return { status: 404, body: { error: 'operation not found' } };
-      if (j.state !== 'NEEDS_ATTENTION') return { status: 409, body: { error: `journal state ${j.state} 不允许 confirm` } };
-      if (j.snapshotId === null || j.snapshotId === '') return { status: 400, body: { error: 'journal 无 trusted snapshot，无法恢复' } };
+      if (j.state !== 'NEEDS_ATTENTION') return { status: 409, body: { error: engineMsg('core.recovery.stateNotAllowed', { state: j.state, action: 'confirm' }) } };
+      if (j.snapshotId === null || j.snapshotId === '') return { status: 400, body: { error: engineMsg('core.recovery.noTrustedSnapshot') } };
       const verdict = await validateSnapshotVerdict(j.snapshotId);
-      if (verdict !== 'TRUSTED_OPERATION_SNAPSHOT') return { status: 400, body: { error: `snapshot 不可信: ${verdict}` } };
+      if (verdict !== 'TRUSTED_OPERATION_SNAPSHOT') return { status: 400, body: { error: engineMsg('core.recovery.snapshotUntrusted', { verdict }) } };
       // journal 保持 NEEDS_ATTENTION（confirm 不转 RECOVERING）
       return { status: 200, body: { ok: true, operationId, snapshotId: j.snapshotId, verdict } };
     },
@@ -303,12 +304,12 @@ export function createRecoveryOrchestrator(deps: RecoveryOrchestratorDeps): Reco
       if (userConfirmed !== true) return { status: 400, body: { error: 'userConfirmed required' } };
       const j = await store.loadActive(operationId);
       if (j === null) return { status: 404, body: { error: 'operation not found' } };
-      if (j.state !== 'NEEDS_ATTENTION' && j.state !== 'RECOVERING') return { status: 409, body: { error: `journal state ${j.state} 不允许 execute` } };
-      if (j.snapshotId === null || j.snapshotId === '') return { status: 400, body: { error: 'journal 无 trusted snapshot，无法恢复' } };
+      if (j.state !== 'NEEDS_ATTENTION' && j.state !== 'RECOVERING') return { status: 409, body: { error: engineMsg('core.recovery.stateNotAllowed', { state: j.state, action: 'execute' }) } };
+      if (j.snapshotId === null || j.snapshotId === '') return { status: 400, body: { error: engineMsg('core.recovery.noTrustedSnapshot') } };
       const d = await decision(j);
-      if (d === 'needs-attention') return { status: 400, body: { error: 'recovery decision 为 needs-attention，无法自动执行' } };
+      if (d === 'needs-attention') return { status: 400, body: { error: engineMsg('core.recovery.needsAttentionNoAuto') } };
       const verdict = await validateSnapshotVerdict(j.snapshotId);
-      if (verdict !== 'TRUSTED_OPERATION_SNAPSHOT') return { status: 400, body: { error: `snapshot 不可信: ${verdict}` } };
+      if (verdict !== 'TRUSTED_OPERATION_SNAPSHOT') return { status: 400, body: { error: engineMsg('core.recovery.snapshotUntrusted', { verdict }) } };
       return runExecution(operationId, j, d, makeExecutors);
     },
 
@@ -316,13 +317,13 @@ export function createRecoveryOrchestrator(deps: RecoveryOrchestratorDeps): Reco
       if (!isValidOperationId(operationId)) return { status: 400, body: { error: 'invalid operationId' } };
       const j = await store.loadActive(operationId);
       if (j === null) return { status: 404, body: { error: 'operation not found' } };
-      if (j.state !== 'RECOVERING') return { status: 409, body: { error: `journal state ${j.state} 不允许 verify` } };
-      if (j.snapshotId === null || j.snapshotId === '') return { status: 400, body: { error: 'journal 无 trusted snapshot' } };
+      if (j.state !== 'RECOVERING') return { status: 409, body: { error: engineMsg('core.recovery.stateNotAllowed', { state: j.state, action: 'verify' }) } };
+      if (j.snapshotId === null || j.snapshotId === '') return { status: 400, body: { error: engineMsg('core.recovery.noTrustedSnapshotShort') } };
       let snap: Snapshot;
       try {
         snap = await new FileSnapshotStore({ dir: snapshotsDir }).load(j.snapshotId);
       } catch {
-        return { status: 400, body: { error: 'snapshot 无法加载' } };
+        return { status: 400, body: { error: engineMsg('core.recovery.snapshotLoadFailed') } };
       }
       const verification = await verifyRecovery(snap, host, { snapshotsRoot: snapshotsDir, environmentFingerprint: getEnvironmentFingerprint(), expectedOperationId: j.operationId });
       const terminal = recoveryTerminalState(verification.verdict);
@@ -351,12 +352,12 @@ export function createRecoveryOrchestrator(deps: RecoveryOrchestratorDeps): Reco
       if (userConfirmed !== true) return { status: 400, body: { error: 'userConfirmed required' } };
       const j = await store.loadActive(operationId);
       if (j === null) return { status: 404, body: { error: 'operation not found' } };
-      if (j.state !== 'NEEDS_ATTENTION') return { status: 409, body: { error: `journal state ${j.state} 不允许 retry` } };
-      if (j.snapshotId === null || j.snapshotId === '') return { status: 400, body: { error: 'journal 无 trusted snapshot' } };
+      if (j.state !== 'NEEDS_ATTENTION') return { status: 409, body: { error: engineMsg('core.recovery.stateNotAllowed', { state: j.state, action: 'retry' }) } };
+      if (j.snapshotId === null || j.snapshotId === '') return { status: 400, body: { error: engineMsg('core.recovery.noTrustedSnapshotShort') } };
       const d = await decision(j);
-      if (d === 'needs-attention') return { status: 400, body: { error: 'recovery decision 为 needs-attention，无法 retry' } };
+      if (d === 'needs-attention') return { status: 400, body: { error: engineMsg('core.recovery.needsAttentionNoRetry') } };
       const verdict = await validateSnapshotVerdict(j.snapshotId);
-      if (verdict !== 'TRUSTED_OPERATION_SNAPSHOT') return { status: 400, body: { error: `snapshot 不可信: ${verdict}` } };
+      if (verdict !== 'TRUSTED_OPERATION_SNAPSHOT') return { status: 400, body: { error: engineMsg('core.recovery.snapshotUntrusted', { verdict }) } };
       return runExecution(operationId, j, d, makeExecutors);
     },
 
@@ -367,7 +368,7 @@ export function createRecoveryOrchestrator(deps: RecoveryOrchestratorDeps): Reco
       if (j === null) return { status: 404, body: { error: 'operation not found' } };
       // dismiss → quarantine（用户放弃；不删除 snapshot/journal evidence，不强行 RECOVERED）
       const result = await executeRecovery(store, { operationId, action: 'dismiss', snapshotId: j.snapshotId }, true);
-      if (result === 'failed') return { status: 400, body: { error: 'dismiss 失败' } };
+      if (result === 'failed') return { status: 400, body: { error: engineMsg('core.recovery.dismissFailed') } };
       // issue #56：放弃恢复 = 该 incident 结案 —— 若没有别的未解决 incident，必须同时解除保护。
       // 此前这里只 quarantine 不清 SAFE MODE，而唯一的清除点挂在 verify(ROLLED_BACK) 上，
       // 事务已被移出 active/ ⇒ 那条分支永远走不到：界面显示「暂无待处理」，写操作却持续 423，
@@ -429,7 +430,7 @@ export function createRecoveryOrchestrator(deps: RecoveryOrchestratorDeps): Reco
         }
         if (!res.ok) {
           // 拒绝是正常结果（活锁/无法证明 stale/二次验证失败），不是 500
-          return { status: 200, body: { ok: false, removed: false, state: res.state, reason: res.detail ?? '未判定为 stale，已拒绝回收' } };
+          return { status: 200, body: { ok: false, removed: false, state: res.state, reason: res.detail ?? engineMsg('core.recovery.lockNotStale') } };
         }
         // 回收成功后 stale 分类已消失；锁态交由客户端重新拉取 status 刷新
         return { status: 200, body: { ok: true, removed: res.removed, state: res.state } };

package/src/core/reinstall.ts

@@ -21,6 +21,7 @@
  *    显式亮出独立开关删除。
  */
 
+import { engineMsg } from './messages-core.ts';
 import os from 'node:os'
 import path from 'node:path'
 
@@ -40,39 +41,43 @@ export interface ReinstallItemDef {
   defaultOn: boolean
 }
 
+/**
+ * 类别清单。label/desc 写成 **getter**（访问时才解析语言）：本常量在模块加载期求值，
+ * 若直接调用 engineMsg 会把文案冻结成加载时的语言 —— 正是本次 i18n 改造要修的根因。
+ */
 export const REINSTALL_ITEMS: readonly ReinstallItemDef[] = [
   {
     id: 'program',
-    label: 'DSH 程序本体',
-    desc: '卸载并重装 @deepseek-ai/dsh 全局启动器（核心动作）',
+    get label() { return engineMsg('core.reinstall.programLabel') },
+    get desc() { return engineMsg('core.reinstall.programDesc') },
     destructive: false,
     defaultOn: true,
   },
   {
     id: 'cache',
-    label: '全局残留缓存',
-    desc: '清 pnpm store 与 npm cache（可选）',
+    get label() { return engineMsg('core.reinstall.cacheLabel') },
+    get desc() { return engineMsg('core.reinstall.cacheDesc') },
     destructive: false,
     defaultOn: true,
   },
   {
     id: 'settings',
-    label: '~/.dsh 设置',
-    desc: '清空 settings.yaml 等配置（不可逆）',
+    get label() { return engineMsg('core.reinstall.settingsLabel') },
+    get desc() { return engineMsg('core.reinstall.settingsDesc') },
     destructive: true,
     defaultOn: false,
   },
   {
     id: 'plugins',
-    label: '~/.dsh 已装插件',
-    desc: '清空 profiles 下已装插件依赖（不可逆）',
+    get label() { return engineMsg('core.reinstall.pluginsLabel') },
+    get desc() { return engineMsg('core.reinstall.pluginsDesc') },
     destructive: true,
     defaultOn: false,
   },
   {
     id: 'data',
-    label: '会话记录与凭据',
-    desc: '清空 sessions 会话与 .credentials.yaml 凭据（最高风险，强制二次确认）',
+    get label() { return engineMsg('core.reinstall.dataLabel') },
+    get desc() { return engineMsg('core.reinstall.dataDesc') },
     destructive: true,
     defaultOn: false,
   },
@@ -216,22 +221,22 @@ export async function buildReinstallPlan(
     const globalRoot = await resolveNpmGlobalRoot(exec)
     const dshGlobalDir = path.join(globalRoot, '@deepseek-ai', 'dsh')
     steps.push({
-      label: '卸载全局 @deepseek-ai/dsh',
+      label: engineMsg('core.reinstall.stepUninstallGlobal'),
       command: 'npm uninstall -g @deepseek-ai/dsh',
       dangerous: false,
     })
     steps.push({
-      label: '清理全局残留 @deepseek-ai/dsh',
+      label: engineMsg('core.reinstall.stepCleanGlobal'),
       command: rmCommand(dshGlobalDir, platform),
       dangerous: false,
     })
     steps.push({
-      label: `安装全局 @deepseek-ai/dsh@${versionSpec}`,
+      label: engineMsg('core.reinstall.stepInstallGlobal', { version: versionSpec }),
       command: `npm install -g @deepseek-ai/dsh@${versionSpec}`,
       dangerous: false,
     })
     steps.push({
-      label: '验证版本（dsh --version）',
+      label: engineMsg('core.reinstall.stepVerifyVersion'),
       command: 'dsh --version',
       dangerous: false,
     })
@@ -241,13 +246,13 @@ export async function buildReinstallPlan(
     const pnpmStore = resolvePnpmStoreDir(env, platform)
     if (pnpmStore !== null) {
       steps.push({
-        label: '清理 pnpm store',
+        label: engineMsg('core.reinstall.stepCleanPnpmStore'),
         command: rmCommand(pnpmStore, platform),
         dangerous: false,
       })
     }
     steps.push({
-      label: '清理 npm cache',
+      label: engineMsg('core.reinstall.stepCleanNpmCache'),
       command: 'npm cache clean --force',
       dangerous: false,
     })
@@ -259,33 +264,33 @@ export async function buildReinstallPlan(
   // 但历史会话/凭据在此备份，作为抢救兜底）。
   if (wipeConfig) {
     steps.push({
-      label: '备份 ~/.dsh 到同级 .reinstall-backup（抢救兜底）',
+      label: engineMsg('core.reinstall.stepBackupHome'),
       command: copyDirCommand(dshHome, `${dshHome}.reinstall-backup`, platform),
       dangerous: true,
     })
   }
   if (selection.has('settings')) {
     steps.push({
-      label: '清空 ~/.dsh 设置（settings.yaml 等）',
+      label: engineMsg('core.reinstall.stepWipeSettings'),
       command: rmCommand(path.join(dshHome, 'settings.yaml'), platform),
       dangerous: true,
     })
   }
   if (selection.has('plugins')) {
     steps.push({
-      label: '清空 ~/.dsh 已装插件（profiles/*/node_modules）',
+      label: engineMsg('core.reinstall.stepWipePlugins'),
       command: rmCommand(path.join(dshHome, 'profiles'), platform),
       dangerous: true,
     })
   }
   if (selection.has('data')) {
     steps.push({
-      label: '清空会话记录（sessions/）',
+      label: engineMsg('core.reinstall.stepWipeSessions'),
       command: rmCommand(path.join(dshHome, 'sessions'), platform),
       dangerous: true,
     })
     steps.push({
-      label: '清空凭据（.credentials.yaml，仅删除文件）',
+      label: engineMsg('core.reinstall.stepWipeCredentials'),
       command: rmCommand(path.join(dshHome, '.credentials.yaml'), platform),
       dangerous: true,
     })

package/src/core/restore.ts

@@ -20,6 +20,7 @@
  * cordis.patch.yml）；workspaceRecord 离线无法经 DSH storages 恢复 → 如实提示。
  * 旧快照（无 beforePlugins / hostFileBackups）兼容：缺基线的部分只提示不动作。
  */
+import { engineMsg } from './messages-core.ts';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 
@@ -281,10 +282,10 @@ export interface RestoreSnapshotValidation {
 /** 递归检查快照目录内关键文件非 symlink（F25：拒绝 symlink 化 metadata/blob 写穿）。 */
 async function assertNoSnapshotSymlink(dir: string, rel: string): Promise<string | null> {
   const p = path.join(dir, rel);
-  if (!isWithinHome(dir, p)) return `路径越界: ${rel}`;
+  if (!isWithinHome(dir, p)) return engineMsg('core.restore.pathEscaped', { rel });
   try {
     const st = await fs.lstat(p);
-    if (st.isSymbolicLink()) return `symlink 化关键文件: ${rel}`;
+    if (st.isSymbolicLink()) return engineMsg('core.restore.symlinkCriticalFile', { rel });
     return null;
   } catch {
     // 缺失由 verify/logic 处理（此处不判缺失）
@@ -310,12 +311,12 @@ export async function validateSnapshotForRestore(
   env?: { environmentFingerprint?: string },
 ): Promise<RestoreSnapshotValidation> {
   const id = path.basename(snapshotDir);
-  if (!isValidSnapshotId(id)) return { verdict: 'INVALID', reason: 'snapshotId 非法' };
+  if (!isValidSnapshotId(id)) return { verdict: 'INVALID', reason: engineMsg('core.restore.invalidSnapshotId') };
 
   // 目录边界：snapshotDir 必须紧邻 snapshotsRoot 下的一层
   const rel = path.relative(snapshotsRoot, snapshotDir).split(path.sep).join('/');
   if (rel === '' || rel.includes('/') || !isWithinHome(snapshotsRoot, snapshotDir)) {
-    return { verdict: 'INVALID', reason: '快照目录越界或非直接子目录' };
+    return { verdict: 'INVALID', reason: engineMsg('core.restore.snapshotDirOutOfBounds') };
   }
 
   // 关键文件 symlink 检查（F25）
@@ -339,7 +340,7 @@ export async function validateSnapshotForRestore(
   const blobEntries = await fs.readdir(blobsDir, { withFileTypes: true }).catch(() => [] as Array<{ name: string; isSymbolicLink(): boolean }>);
   for (const be of blobEntries) {
     if (be.isSymbolicLink()) {
-      return { verdict: 'UNSAFE_PATH', reason: `blob 是 symlink: ${be.name}` };
+      return { verdict: 'UNSAFE_PATH', reason: engineMsg('core.restore.blobSymlink', { name: be.name }) };
     }
   }
 
@@ -352,9 +353,9 @@ export async function validateSnapshotForRestore(
   } catch {
     /* verifySnapshot 已报缺失 */
   }
-  if (snapshot === null || typeof snapshot !== 'object') return { verdict: 'CORRUPT', reason: 'snapshot.json 无法解析' };
+  if (snapshot === null || typeof snapshot !== 'object') return { verdict: 'CORRUPT', reason: engineMsg('core.restore.snapshotJsonUnparsable') };
   if (!manifestExists && snapshot.readiness === undefined) {
-    return { verdict: 'LEGACY_REQUIRES_CONFIRMATION', reason: '旧快照（无 manifest/READY），需显式确认后恢复' };
+    return { verdict: 'LEGACY_REQUIRES_CONFIRMATION', reason: engineMsg('core.restore.legacyNeedsConfirm') };
   }
 
   // 结构 + 完整性（磁盘重读，不信任内存）
@@ -364,18 +365,18 @@ export async function validateSnapshotForRestore(
   // 环境绑定（WRONG_ENVIRONMENT）
   if (env?.environmentFingerprint && snapshot.readiness === 'READY' && snapshot.environmentFingerprint
     && snapshot.environmentFingerprint !== env.environmentFingerprint) {
-    return { verdict: 'WRONG_ENVIRONMENT', reason: 'environmentFingerprint 不匹配（可能来自其他机器/安装）' };
+    return { verdict: 'WRONG_ENVIRONMENT', reason: engineMsg('core.restore.envFingerprintMismatch') };
   }
 
   // provenance 分类
   const hasBinding = snapshot.operationId !== undefined || snapshot.environmentFingerprint !== undefined || snapshot.ownerInstanceId !== undefined;
   if (snapshot.readiness === undefined) {
-    return { verdict: 'LEGACY_REQUIRES_CONFIRMATION', reason: '旧快照（无 readiness），需显式确认后恢复' };
+    return { verdict: 'LEGACY_REQUIRES_CONFIRMATION', reason: engineMsg('core.restore.legacyNoReadiness') };
   }
   if (!hasBinding) {
-    return { verdict: 'TRUSTED_MANUAL_LOCAL', reason: '完整性通过，但非 operation-bound（手动/本地快照）' };
+    return { verdict: 'TRUSTED_MANUAL_LOCAL', reason: engineMsg('core.restore.trustedManualLocal') };
   }
-  return { verdict: 'TRUSTED_OPERATION_SNAPSHOT', reason: 'READY + manifest 完整 + op/env/owner binding 匹配' };
+  return { verdict: 'TRUSTED_OPERATION_SNAPSHOT', reason: engineMsg('core.restore.trustedOperationSnapshot') };
 }
 
 
@@ -434,9 +435,11 @@ export async function planRestore(opts: RestoreOptions): Promise<RestorePlan> {
     const currentExists = await fileExists(abs);
     if (backup.existed) {
       if (backup.blobPath === '') {
+        // unreadable = 拍快照时文件存在但读不出来：本次**只跳过并如实说明**，绝不因为
+        // 「快照里没有字节」就把它当成「当时不存在」（那会在恢复时删掉用户真实的文件）。
         actions.push({
           kind: 'skip',
-          description: msg('restore.hostNoBlobInfo', { path: backup.relPath }),
+          description: msg(backup.unreadable === true ? 'restore.hostUnreadable' : 'restore.hostNoBlobInfo', { path: backup.relPath }),
           target: backup.relPath,
         });
         continue;
@@ -850,7 +853,7 @@ export async function listSnapshots(
     // 其余（EACCES / EPERM / ENOTDIR…）经 out.unreadable 回传，由调用方如实展示。
     const code = (error as { code?: string }).code;
     if (code !== 'ENOENT' && out !== undefined) {
-      out.unreadable = '快照目录读不出来（' + String(code ?? 'unknown') + '）：' + dir;
+      out.unreadable = engineMsg('core.restore.snapshotDirUnreadable', { code: String(code ?? 'unknown'), dir });
     }
     return [];
   }
@@ -891,11 +894,11 @@ export function isValidSnapshotId(id: unknown): id is string {
  *  不存在视为成功（幂等）。返回是否实际删除。 */
 export async function deleteSnapshot(snapshotsDir: string, id: string): Promise<boolean> {
   if (!isValidSnapshotId(id)) {
-    throw new Error(`非法快照 id: ${JSON.stringify(id)}`);
+    throw new Error(engineMsg('core.restore.illegalSnapshotId', { id: JSON.stringify(id) }));
   }
   const target = path.join(snapshotsDir, id);
   if (!target.startsWith(path.resolve(snapshotsDir) + path.sep)) {
-    throw new Error(`快照路径越界: ${id}`);
+    throw new Error(engineMsg('core.restore.snapshotPathEscaped', { id }));
   }
   try {
     await fs.stat(target);
@@ -910,12 +913,12 @@ export async function deleteSnapshot(snapshotsDir: string, id: string): Promise<
  *  只接受合法 id；快照不存在抛错。 */
 export async function setSnapshotPinned(snapshotsDir: string, id: string, pinned: boolean): Promise<boolean> {
   if (!isValidSnapshotId(id)) {
-    throw new Error(`非法快照 id: ${JSON.stringify(id)}`);
+    throw new Error(engineMsg('core.restore.illegalSnapshotId', { id: JSON.stringify(id) }));
   }
   const file = path.join(snapshotsDir, id, 'snapshot.json');
   const resolvedRoot = path.resolve(snapshotsDir) + path.sep;
   if (!file.startsWith(resolvedRoot)) {
-    throw new Error(`快照路径越界: ${id}`);
+    throw new Error(engineMsg('core.restore.snapshotPathEscaped', { id }));
   }
   const snapshot = parseJsonSafe(await fs.readFile(file, 'utf8')) as Snapshot;
   snapshot.pinned = pinned;

package/src/core/rollback-file-diff.test.ts

@@ -0,0 +1,159 @@
+/**
+ * 回滚点「单文件前后对照」（`RollbackPointEngine.fileDiff`）单测。
+ *
+ * 纪律与本仓既有 core 测试同款：真实临时目录 + 真实读写，不 mock 文件系统。
+ *
+ * 覆盖的是这个端点的**收窄与诚实性**（它是新的只读读取面，用户 2026-10-12 的「查看」数据源）：
+ *  · 方向必须是 before = **当前磁盘** / after = **回退点快照**（读反了整屏差异都是反的）；
+ *  · 只认**记录在案**的路径（未记录 ⇒ file-not-recorded，绝不变成任意路径读取器）；
+ *  · 二进制 / 超限 / 读不出一律结构化 reason + 空 hunks（「不知道」不得显示成「没有差异」）；
+ *  · 全程**零写入**（工作区字节不变、对象仓不新增）。
+ */
+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 { RollbackPointEngine } from './rollback-point.ts'
+
+interface Fixture {
+  root: string
+  homeDir: string
+  dataDir: string
+  workspaceDir: string
+  cleanup: () => Promise<void>
+}
+
+async function makeFixture(): Promise<Fixture> {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-cm-rollback-file-diff-'))
+  const homeDir = path.join(root, 'home')
+  const dataDir = path.join(homeDir, 'dsh-config-manager')
+  const workspaceDir = path.join(root, 'ws')
+  await fs.mkdir(workspaceDir, { recursive: true })
+  await fs.writeFile(path.join(workspaceDir, 'a.txt'), 'A1\nA2\n')
+  return { root, homeDir, dataDir, workspaceDir, cleanup: async () => { await fs.rm(root, { recursive: true, force: true }) } }
+}
+
+function makeEngine(fx: Fixture): RollbackPointEngine {
+  return new RollbackPointEngine({ dataDir: fx.dataDir, homeDir: fx.homeDir, sessionQuiescentMs: 0 })
+}
+
+/** 留一个点（只带工作区态），返回点 id。 */
+async function capture(engine: RollbackPointEngine, fx: Fixture): Promise<string> {
+  const captured = await engine.capturePoint({ chunks: [fx.workspaceDir], sessionId: 'session-1111', turnSeq: 1 })
+  const id = captured.point?.id
+  assert.ok(typeof id === 'string' && id !== '', 'fixture 必须先真的留下一个点：' + JSON.stringify(captured))
+  return id as string
+}
+
+test('fileDiff：before = 当前磁盘、after = 回退点快照（方向不许读反）', async () => {
+  const fx = await makeFixture()
+  try {
+    const engine = makeEngine(fx)
+    const id = await capture(engine, fx)
+    const file = path.join(fx.workspaceDir, 'a.txt')
+    // 留点**之后**改文件：回退会把 A2 删掉、把 A3 加回来
+    await fs.writeFile(file, 'A1\nA3\n')
+    const diff = await engine.fileDiff(id, file)
+    assert.equal(diff.ok, true, JSON.stringify(diff))
+    assert.equal(diff.status, 'overwrite')
+    assert.equal(diff.before.exists, true)
+    assert.equal(diff.after.exists, true)
+    assert.equal(diff.identical, false)
+    // 方向证据：删掉的是当前独有的 A3，新增的是快照里的 A2
+    assert.equal(diff.removed, 1)
+    assert.equal(diff.added, 1)
+    const texts = diff.hunks.flatMap((hunk) => hunk.lines.map((line) => line.kind + ':' + line.text))
+    assert.ok(texts.includes('del:A3'), '当前独有的行必须是删除：' + JSON.stringify(texts))
+    assert.ok(texts.includes('add:A2'), '快照独有的行必须是新增：' + JSON.stringify(texts))
+  } finally {
+    await fx.cleanup()
+  }
+})
+
+test('fileDiff：当前文件不存在（ENOENT）→ status=create，新增 = 快照全部行', async () => {
+  const fx = await makeFixture()
+  try {
+    const engine = makeEngine(fx)
+    const id = await capture(engine, fx)
+    const file = path.join(fx.workspaceDir, 'a.txt')
+    await fs.rm(file)
+    const diff = await engine.fileDiff(id, file)
+    assert.equal(diff.ok, true)
+    assert.equal(diff.status, 'create')
+    assert.equal(diff.before.exists, false)
+    assert.equal(diff.after.exists, true)
+    assert.equal(diff.removed, 0)
+    assert.equal(diff.added, diff.after.lines)
+  } finally {
+    await fx.cleanup()
+  }
+})
+
+test('fileDiff：未记录在案的路径 → file-not-recorded（这条端点不是任意路径读取器）', async () => {
+  const fx = await makeFixture()
+  try {
+    const engine = makeEngine(fx)
+    const id = await capture(engine, fx)
+    const outside = path.join(fx.root, 'outside.txt')
+    await fs.writeFile(outside, 'secret\n')
+    const diff = await engine.fileDiff(id, outside)
+    assert.equal(diff.ok, false)
+    assert.equal(diff.code, 'file-not-recorded')
+    assert.deepEqual(diff.hunks, [], '未记录的路径不得给出任何差异内容')
+  } finally {
+    await fx.cleanup()
+  }
+})
+
+test('fileDiff：二进制 → reason=binary 且 hunks 空（不把「不知道」说成「没有差异」）', async () => {
+  const fx = await makeFixture()
+  try {
+    const engine = makeEngine(fx)
+    const binary = path.join(fx.workspaceDir, 'blob.bin')
+    await fs.writeFile(binary, Buffer.from([0, 1, 2, 3, 0, 9]))
+    const id = await capture(engine, fx)
+    await fs.writeFile(binary, Buffer.from([0, 5, 6, 7, 0, 9]))
+    const diff = await engine.fileDiff(id, binary)
+    assert.equal(diff.ok, true)
+    assert.equal(diff.reason, 'binary')
+    assert.deepEqual(diff.hunks, [])
+    assert.equal(diff.identical, false, '无法逐行对比不得被说成「一致」')
+  } finally {
+    await fx.cleanup()
+  }
+})
+
+test('fileDiff：未知 id → record-not-found（结构化码，不抛）', async () => {
+  const fx = await makeFixture()
+  try {
+    const engine = makeEngine(fx)
+    await capture(engine, fx)
+    const diff = await engine.fileDiff('nope', path.join(fx.workspaceDir, 'a.txt'))
+    assert.equal(diff.ok, false)
+    assert.equal(diff.code, 'record-not-found')
+  } finally {
+    await fx.cleanup()
+  }
+})
+
+test('fileDiff：零写入 —— 对照前后工作区字节与对象仓条目都不变', async () => {
+  const fx = await makeFixture()
+  try {
+    const engine = makeEngine(fx)
+    const id = await capture(engine, fx)
+    const file = path.join(fx.workspaceDir, 'a.txt')
+    await fs.writeFile(file, 'A1\nCHANGED\n')
+    const before = await fs.readFile(file)
+    const objectsDir = path.join(engine.storeDir, 'objects')
+    const objectsBefore = await fs.readdir(objectsDir)
+    const ledgerBefore = await fs.readFile(path.join(engine.storeDir, 'index.json'), 'utf8')
+    await engine.fileDiff(id, file)
+    assert.deepEqual(await fs.readFile(file), before, '只读对照不得改动工作区文件')
+    assert.deepEqual(await fs.readdir(objectsDir), objectsBefore, '只读对照不得写对象仓')
+    assert.equal(await fs.readFile(path.join(engine.storeDir, 'index.json'), 'utf8'), ledgerBefore, '只读对照不得写台账')
+  } finally {
+    await fx.cleanup()
+  }
+})

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

@@ -0,0 +1,66 @@
+/**
+ * 回合自动留点开关的**进程内**语义（issue #88 / #89，src/core/rollback-gate.ts）。
+ *
+ * 钉住四条：① 缺省关闭；② 变化才通知（同值不通知，避免写偏好时抖动 attach/detach）；
+ * ③ 监听器抛错不影响开关本身与其它监听器；④ 解绑幂等。
+ *
+ * 为什么值得单测：宿主那条 `session/event` 订阅链的 attach/detach 完全由这里驱动 ——
+ * 一旦「关了还通知」或「通知丢了」，就是「界面说关了、宿主还在每回合写台账」这类静默故障。
+ */
+import test from 'node:test'
+import assert from 'node:assert/strict'
+
+import {
+  isRollbackEnabled,
+  onRollbackEnabledChange,
+  resetRollbackGateForTest,
+  setRollbackEnabled,
+} from './rollback-gate.ts'
+
+test('G-01 缺省关闭 + 置真置假都生效', () => {
+  resetRollbackGateForTest()
+  assert.equal(isRollbackEnabled(), false, '缺省必须是关闭（fail-closed）')
+  setRollbackEnabled(true)
+  assert.equal(isRollbackEnabled(), true)
+  setRollbackEnabled(false)
+  assert.equal(isRollbackEnabled(), false)
+  resetRollbackGateForTest()
+})
+
+test('G-02 同值不通知；变化按顺序通知一次', () => {
+  resetRollbackGateForTest()
+  const seen: boolean[] = []
+  const off = onRollbackEnabledChange((value) => { seen.push(value) })
+  setRollbackEnabled(false) // 与缺省同值 → 不通知
+  assert.deepEqual(seen, [], '同值不得通知')
+  setRollbackEnabled(true)
+  setRollbackEnabled(true) // 重复同值
+  setRollbackEnabled(false)
+  assert.deepEqual(seen, [true, false], '只在真实变化时通知一次')
+  off()
+  resetRollbackGateForTest()
+})
+
+test('G-03 监听器抛错不影响开关与其它监听器', () => {
+  resetRollbackGateForTest()
+  const seen: boolean[] = []
+  const offBad = onRollbackEnabledChange(() => { throw new Error('boom') })
+  const offGood = onRollbackEnabledChange((value) => { seen.push(value) })
+  setRollbackEnabled(true)
+  assert.equal(isRollbackEnabled(), true, '坏监听器不得拦住状态切换')
+  assert.deepEqual(seen, [true], '坏监听器不得吃掉后面监听器的通知')
+  offBad()
+  offGood()
+  resetRollbackGateForTest()
+})
+
+test('G-04 解绑幂等：解绑后再改状态不通知已解绑者', () => {
+  resetRollbackGateForTest()
+  const seen: boolean[] = []
+  const off = onRollbackEnabledChange((value) => { seen.push(value) })
+  off()
+  off() // 幂等
+  setRollbackEnabled(true)
+  assert.deepEqual(seen, [])
+  resetRollbackGateForTest()
+})