dsh-config-manager 0.1.78 → 0.1.79

package/src/sync/sync-device-identity.test.ts

@@ -0,0 +1,267 @@
+/**
+ * ⑥ 设备身份（sync-state.resolveDeviceIdentity + push manifest 携带）+ ② 引擎探针的单测。
+ *
+ *  - resolveDeviceIdentity：首次调用生成并落盘 deviceId/deviceName（读回一致）；
+ *    第二次调用**不再写盘**（写计数 fs 断言）；空主机名 → 字典兜底文案；
+ *    已有 id 而无 name 的旧文件 → 纯读（磁盘逐字节不变）；
+ *  - engine.push：快照 manifest 带 deviceId/deviceName，且与 sync-state 落盘值一致、第二次 push 稳定；
+ *  - engine.probe：通道无 probe → 抛 sync.probeUnsupported（绝不谎报连接正常）；有 probe → 原样透出。
+ */
+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 { SyncEngine } from './sync-engine.ts';
+import { createSnapshotFs } from './fs.ts';
+import type { SnapshotFs } from './fs.ts';
+import {
+  loadSyncState, resolveDeviceIdentity, saveSyncState, SYNC_STATE_FILE, SYNC_STATE_SCHEMA_VERSION,
+} from './sync-state.ts';
+import { computeSnapshotMeta, SyncTransportError } from './transport.ts';
+import type { SyncSnapshot, SyncSnapshotMeta, SyncTransport } from './transport.ts';
+import { createAdapters } from '../adapters/index.ts';
+import { makeContext, MemSnapshotStore } from '../adapters/test-helpers.ts';
+import { Importer } from '../core/importer.ts';
+import { zhMsg } from '../core/messages.ts';
+
+/* ---------------- 写计数 fs（断言「第二次不再写盘」） ---------------- */
+
+function countingFs(): { fsx: SnapshotFs; stats: { writes: number; mkdirs: number } } {
+  const inner = createSnapshotFs();
+  const stats = { writes: 0, mkdirs: 0 };
+  const fsx: SnapshotFs = {
+    async readFile(p) { return inner.readFile(p); },
+    async writeFile(p, data) { stats.writes += 1; await inner.writeFile(p, data); },
+    async mkdir(p) { stats.mkdirs += 1; await inner.mkdir(p); },
+    async readdir(p) { return inner.readdir(p); },
+    async isDir(p) { return inner.isDir(p); },
+    async exists(p) { return inner.exists(p); },
+    async remove(p) { await inner.remove(p); },
+  };
+  return { fsx, stats };
+}
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+/* ---------------- ⑥ resolveDeviceIdentity ---------------- */
+
+test('⑥ 设备身份：首次调用生成 UUID + 主机名并落盘；第二次调用零写入', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-device-id-'));
+  try {
+    const { fsx, stats } = countingFs();
+
+    const first = await resolveDeviceIdentity(tmp, '  workstation-a  ', fsx);
+    assert.match(first.id, UUID_RE, 'deviceId 必须是随机 UUID');
+    assert.equal(first.name, 'workstation-a', 'deviceName 取主机名（两端空白去掉）');
+    assert.ok(stats.writes >= 1, '首次必须落盘');
+
+    // 读回一致（走真实 fs + loadSyncState）
+    const onDisk = JSON.parse(await fs.readFile(path.join(tmp, SYNC_STATE_FILE), 'utf8')) as Record<string, unknown>;
+    assert.equal(onDisk['deviceId'], first.id);
+    assert.equal(onDisk['deviceName'], 'workstation-a');
+    const loaded = await loadSyncState(tmp);
+    assert.equal(loaded.deviceId, first.id);
+    assert.equal(loaded.deviceName, first.name);
+
+    // 第二次：已有 id/name → 纯读
+    stats.writes = 0;
+    stats.mkdirs = 0;
+    const second = await resolveDeviceIdentity(tmp, 'workstation-a', fsx);
+    assert.equal(second.id, first.id, '同一台设备必须复用 deviceId');
+    assert.equal(second.name, 'workstation-a');
+    assert.equal(stats.writes, 0, '第二次调用绝不写盘');
+    assert.equal(stats.mkdirs, 0, '第二次调用连目录都不建');
+
+    // 换主机名也不变（deviceId 是稳定标识）
+    const renamed = await resolveDeviceIdentity(tmp, 'renamed-host', fsx);
+    assert.equal(renamed.id, first.id);
+    assert.equal(renamed.name, 'workstation-a', '已记录的 deviceName 不被改写');
+    assert.equal(stats.writes, 0);
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});
+
+test('⑥ 设备身份：主机名为空串 → deviceName 落到字典兜底文案（绝不写空串）', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-device-fallback-'));
+  try {
+    const { fsx } = countingFs();
+    const r = await resolveDeviceIdentity(tmp, '   ', fsx);
+
+    assert.equal(r.name, zhMsg('sync.deviceNameFallback'));
+    assert.equal(r.name, '未命名设备', 'zh 字典兜底文案');
+    assert.ok(r.name.trim() !== '', 'deviceName 不得为空/纯空白');
+
+    const persisted = await loadSyncState(tmp);
+    assert.equal(persisted.deviceId, r.id);
+    assert.equal(persisted.deviceName, r.name, '兜底文案必须一并落盘（否则下次仍要重算）');
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});
+
+test('⑥ 设备身份：文件里已有 deviceId 但缺 deviceName → 纯读，磁盘逐字节不变', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-device-legacy-'));
+  try {
+    await saveSyncState(tmp, {
+      schemaVersion: SYNC_STATE_SCHEMA_VERSION,
+      lastSyncAt: '',
+      sections: {},
+      lastSnapshotId: '',
+      ancestorId: '',
+      deviceId: 'existing-device-id-123',
+    });
+    const before = await fs.readFile(path.join(tmp, SYNC_STATE_FILE), 'utf8');
+
+    const { fsx, stats } = countingFs();
+    const r = await resolveDeviceIdentity(tmp, 'host-x', fsx);
+
+    assert.equal(r.id, 'existing-device-id-123', '已有 id 必须原样复用');
+    assert.equal(r.name, 'host-x', '缺 name 时按主机名解析');
+    assert.equal(stats.writes, 0, '已有 id ⇒ 绝不补写');
+    assert.equal(await fs.readFile(path.join(tmp, SYNC_STATE_FILE), 'utf8'), before, '磁盘逐字节不变');
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});
+
+/* ---------------- 引擎：manifest 设备身份 + probe ---------------- */
+
+class MemTransport implements SyncTransport {
+  readonly type = 'memory';
+  snapshots = new Map<string, SyncSnapshot>();
+  metas: SyncSnapshotMeta[] = [];
+  calls: string[] = [];
+
+  async list(): Promise<SyncSnapshotMeta[]> {
+    this.calls.push('list');
+    return [...this.metas].sort((a, b) => (a.createdAt < b.createdAt ? -1 : 1));
+  }
+
+  async upload(snapshot: SyncSnapshot): Promise<SyncSnapshotMeta> {
+    this.calls.push('upload');
+    this.snapshots.set(snapshot.id, snapshot);
+    this.metas = this.metas.filter((m) => m.id !== snapshot.id);
+    this.metas.push(computeSnapshotMeta(snapshot));
+    return computeSnapshotMeta(snapshot);
+  }
+
+  async download(id: string): Promise<SyncSnapshot> {
+    this.calls.push('download');
+    const snap = this.snapshots.get(id);
+    if (snap === undefined) throw new Error('missing snapshot: ' + id);
+    return snap;
+  }
+
+  async delete(id: string): Promise<void> {
+    this.calls.push('delete');
+    this.snapshots.delete(id);
+    this.metas = this.metas.filter((m) => m.id !== id);
+  }
+}
+
+function seedSettings(ctx: ReturnType<typeof makeContext>): void {
+  ctx.settings.ns.set('general', { value: { theme: 'dark', language: 'zh-CN' }, revision: 1, secrets: [] });
+}
+
+function makeEngine(opts: {
+  ctx: ReturnType<typeof makeContext>;
+  transport: SyncTransport;
+  stateDir: string;
+}): SyncEngine {
+  const adapters = createAdapters({ namespaces: ['general', 'theme'] });
+  const importer = new Importer({ ctx: opts.ctx, adapters, snapshotStore: new MemSnapshotStore() });
+  return new SyncEngine({
+    ctx: opts.ctx,
+    transport: opts.transport,
+    stateDir: opts.stateDir,
+    adapters,
+    importer,
+    now: () => new Date('2026-10-18T12:00:00.000Z'),
+  } as ConstructorParameters<typeof SyncEngine>[0]);
+}
+
+test('⑥ push：快照 manifest 带 deviceId/deviceName，与 sync-state 落盘值一致且跨 push 稳定', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-engine-device-'));
+  try {
+    const ctx = makeContext('win32', 'C:\\Users\\alice');
+    seedSettings(ctx);
+    const transport = new MemTransport();
+    const engine = makeEngine({ ctx, transport, stateDir: tmp });
+
+    const report = await engine.push({ snapshotId: 'sync-dev-1' });
+    assert.equal(report.ok, true, 'push 必须成功：' + JSON.stringify(report.warnings));
+
+    const uploaded = transport.snapshots.get('sync-dev-1');
+    assert.ok(uploaded !== undefined, '快照已上传');
+    const deviceId = uploaded.manifest.deviceId;
+    const deviceName = uploaded.manifest.deviceName;
+    assert.ok(typeof deviceId === 'string' && UUID_RE.test(deviceId), 'manifest.deviceId 必须是 UUID，实际=' + String(deviceId));
+    assert.ok(typeof deviceName === 'string' && deviceName.trim() !== '', 'manifest.deviceName 必须非空');
+
+    const expectedName = os.hostname().trim() !== '' ? os.hostname().trim() : zhMsg('sync.deviceNameFallback');
+    assert.equal(deviceName, expectedName, 'deviceName = 本机主机名（取不到才是兜底文案）');
+
+    const state = await loadSyncState(tmp);
+    assert.equal(state.deviceId, deviceId, 'manifest 的 deviceId 必须就是同步身份落盘值');
+    assert.equal(state.deviceName, deviceName);
+
+    await engine.push({ snapshotId: 'sync-dev-2' });
+    const second = transport.snapshots.get('sync-dev-2');
+    assert.ok(second !== undefined);
+    assert.equal(second.manifest.deviceId, deviceId, '同一台设备连续 push 的 deviceId 必须稳定');
+    assert.equal(second.manifest.deviceName, deviceName);
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});
+
+test('② engine.probe()：通道没实现 probe → 抛 sync.probeUnsupported，绝不谎报连接正常', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-engine-probe-'));
+  try {
+    const ctx = makeContext('win32', 'C:\\Users\\alice');
+    seedSettings(ctx);
+    const transport = new MemTransport();
+    assert.equal(typeof (transport as { probe?: unknown }).probe, 'undefined', '本用例前提：该通道没有 probe');
+    const engine = makeEngine({ ctx, transport, stateDir: tmp });
+
+    await assert.rejects(
+      () => engine.probe(),
+      (err: unknown) => {
+        assert.ok(err instanceof SyncTransportError);
+        assert.equal(err.kind, 'client');
+        assert.equal(err.retryable, false);
+        assert.equal(err.message, zhMsg('sync.probeUnsupported'));
+        assert.equal(err.message, '当前同步通道不支持连通性自检');
+        return true;
+      },
+    );
+    assert.deepEqual(transport.calls, [], '不支持 probe 时不得退化成任何通道调用');
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});
+
+test('② engine.probe()：通道实现了 probe → 原样透出（this 绑定在通道实例上）', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-engine-probe-ok-'));
+  try {
+    const ctx = makeContext('win32', 'C:\\Users\\alice');
+    seedSettings(ctx);
+    const transport = new (class extends MemTransport {
+      probeCalls = 0;
+      async probe() {
+        this.probeCalls += 1;
+        return { message: 'ok:' + this.type, snapshotCount: 7 };
+      }
+    })();
+    const engine = makeEngine({ ctx, transport, stateDir: tmp });
+
+    const result = await engine.probe();
+    assert.deepEqual(result, { message: 'ok:memory', snapshotCount: 7 });
+    assert.equal(transport.probeCalls, 1);
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});

package/src/sync/sync-engine.test.ts

@@ -1373,6 +1373,33 @@ test('hasNewRemoteSnapshot: 空远端→false；从未同步且远端非空→tr
   }
 });
 
+test('hasNewRemoteSnapshot(listed)：传入本轮列表 → 不再 list（自动同步一轮至多一次网络往返）', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-sync-engine-hasnew-reuse-'));
+  try {
+    const ctx = makeContext('win32', 'C:\\Users\\alice');
+    seedSource(ctx);
+    const transport = new MemSyncTransport();
+    const engine = makeEngine({ ctx, transport, stateDir: tmp });
+    await engine.push({ snapshotId: 'sync-001' });
+
+    const before = transport.calls.filter((c) => c === 'list').length;
+    const listed = await engine.listSnapshots();
+    assert.equal(transport.calls.filter((c) => c === 'list').length, before + 1);
+
+    assert.equal(await engine.hasNewRemoteSnapshot(listed), false, '复用传入列表判定「远端最新=祖先」');
+    assert.equal(
+      transport.calls.filter((c) => c === 'list').length, before + 1,
+      '传了列表就绝不能再 list 一次（否则每个回合白跑一次远端往返）',
+    );
+
+    // 对照组：不传 → 自己 list（保持旧行为）
+    assert.equal(await engine.hasNewRemoteSnapshot(), false);
+    assert.equal(transport.calls.filter((c) => c === 'list').length, before + 2, '不传时必须自己 list');
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});
+
 test('hasLocalChanges: 从未同步→true；推后无改动→false；本地改动→true', async () => {
   const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-sync-engine-haslocal-'));
   try {
@@ -2309,3 +2336,355 @@ test('issue #78: 拉取侧 —— 只放行 mcp 时，远端快照里的 session
     await fs.rm(tmp, { recursive: true, force: true });
   }
 });
+
+
+/* ---------------- 远程合并：push 远端推进检测 + 基线纪律（2026-10） ---------------- */
+
+/** 造一份「另一台设备推的」远端快照（仅 settings 分区），与 e2e 同款夹具。 */
+function remoteSettingsSnapshot(id: string, theme: string, revision: number): SyncSnapshot {
+  return {
+    id,
+    createdAt: '2026-08-16T12:00:00.000Z',
+    manifest: { schemaVersion: 1, dshVersion: '1.2.3', platform: 'win32', sectionIds: ['settings'], containsSecrets: false },
+    sections: {
+      settings: { version: 1, namespaces: { general: { value: { theme }, revision, secrets: [] } } },
+    },
+  };
+}
+
+/** 把「别人的快照」塞进内存通道（模拟另一台设备推送）。 */
+function seedRemoteSnapshot(transport: MemSyncTransport, snapshot: SyncSnapshot): void {
+  transport.snapshots.set(snapshot.id, snapshot);
+  transport.metas.push(computeSnapshotMeta(snapshot));
+}
+
+/** 递归收集目录下全部文件（相对路径 → 文本内容）：用于断言「零写入」。 */
+async function snapshotTree(dir: string): Promise<Record<string, string>> {
+  const out: Record<string, string> = {};
+  const walk = async (rel: string): Promise<void> => {
+    const entries = await fs.readdir(path.join(dir, rel), { withFileTypes: true }).catch(() => [] as import('node:fs').Dirent[]);
+    for (const e of entries) {
+      const child = rel === '' ? e.name : rel + '/' + e.name;
+      if (e.isDirectory()) await walk(child);
+      else out[child] = await fs.readFile(path.join(dir, child), 'utf8');
+    }
+  };
+  await walk('');
+  return out;
+}
+
+/** list() 可注入失败的通道（覆盖「读不到远端列表」这条分支）。 */
+class FlakyListTransport extends MemSyncTransport {
+  failList = false;
+  override async list(): Promise<SyncSnapshotMeta[]> {
+    if (this.failList) throw new Error('list-boom');
+    return await super.list();
+  }
+}
+
+test('push: 远端已被别的设备推进 → 拒绝写入（不 upload、sync-state 逐字节不变），force 才放行', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-push-advance-'));
+  try {
+    const ctx = makeContext('win32', 'C:\\Users\\alice');
+    seedSource(ctx);
+    const transport = new MemSyncTransport();
+    const engine = makeEngine({ ctx, transport, stateDir: tmp, localSnapshotsDir: path.join(tmp, 'anc') });
+    // 首次同步：远端为空 → 不拦（本机没有基线可丢）
+    assert.equal((await engine.push({ snapshotId: 'sync-base' })).ok, true);
+    const stateBefore = await fs.readFile(path.join(tmp, SYNC_STATE_FILE), 'utf8');
+
+    // 另一台设备推了 sync-other（本机基线仍是 sync-base）
+    seedRemoteSnapshot(transport, remoteSettingsSnapshot('sync-other', 'light', 5));
+    transport.calls.length = 0;
+    const refused = await engine.push({ snapshotId: 'sync-mine' });
+
+    assert.equal(refused.ok, false, '远端已推进 → 拒绝');
+    assert.equal(refused.conflict, true, '这是「需要先合并远端」的冲突态，不是通道故障');
+    assert.equal(refused.snapshotId, '');
+    assert.deepEqual(refused.sections, []);
+    assert.equal(refused.warnings.length, 0, '拒绝路径本身不产生额外告警');
+    assert.ok((refused.message ?? '').includes('sync-other'), '说明里点出远端快照 id: ' + refused.message);
+    assert.ok((refused.message ?? '').includes('sync-base'), '说明里点出本地基线 id: ' + refused.message);
+    assert.equal(transport.snapshots.has('sync-mine'), false, '绝不 upload');
+    assert.ok(!transport.calls.includes('upload'), 'transport 未收到 upload: ' + transport.calls.join(','));
+    assert.equal(await fs.readFile(path.join(tmp, SYNC_STATE_FILE), 'utf8'), stateBefore, 'sync-state 逐字节不变');
+
+    // 用户显式强制才写
+    const forced = await engine.push({ snapshotId: 'sync-mine', force: true });
+    assert.equal(forced.ok, true, 'force=true 放行');
+    assert.equal(transport.snapshots.has('sync-mine'), true);
+    assert.equal((await loadSyncState(tmp)).lastSnapshotId, 'sync-mine');
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});
+
+test('push: 首次同步（lastSnapshotId=""）即使远端已有别人的快照也不拦', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-push-first-'));
+  try {
+    const ctx = makeContext('win32', 'C:\\Users\\alice');
+    seedSource(ctx);
+    const transport = new MemSyncTransport();
+    seedRemoteSnapshot(transport, remoteSettingsSnapshot('sync-other', 'light', 5));
+    const engine = makeEngine({ ctx, transport, stateDir: tmp });
+    const report = await engine.push({ snapshotId: 'sync-first' });
+    assert.equal(report.ok, true, '没有基线就没有可丢的东西 → 不拦');
+    assert.equal((await loadSyncState(tmp)).lastSnapshotId, 'sync-first');
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});
+
+test('push: 远端列表读不出来 → 无法判定，按原样继续但如实告警（不静默、不拦）', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-push-listfail-'));
+  try {
+    const ctx = makeContext('win32', 'C:\\Users\\alice');
+    seedSource(ctx);
+    const transport = new FlakyListTransport();
+    const engine = makeEngine({ ctx, transport, stateDir: tmp });
+    await engine.push({ snapshotId: 'sync-base' });
+    transport.failList = true;
+    const report = await engine.push({ snapshotId: 'sync-mine' });
+    assert.equal(report.ok, true, '读不到远端列表不拦推送（上传本身会暴露通道问题）');
+    assert.ok(report.warnings.some((w) => w.includes('list-boom')), '必须如实说明无法判定: ' + report.warnings.join(' | '));
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});
+
+test('previewMerge: 只读零写入 + 决策/计数/三侧预览（敏感值必须已脱敏）', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-preview-merge-'));
+  try {
+    const ctx = makeContext('win32', 'C:\\Users\\alice');
+    seedSource(ctx);
+    const transport = new MemSyncTransport();
+    const ancestors = path.join(tmp, 'anc');
+    const engine = makeEngine({ ctx, transport, stateDir: tmp, localSnapshotsDir: ancestors });
+    // 先建基线（祖先 = dark + 一个值形态敏感内容：字段名不敏感，只能靠 redact 的值形状模式兜底）
+    // 注意：载荷必须是「像密钥」的形状（含大写/数字）——纯小写词的 sk- 形态被值形状守卫刻意放行（防过剥）
+    ctx.settings.ns.set('general', { value: { theme: 'dark', webhook: 'sk-anc-0000000000000000' }, revision: 3, secrets: [] });
+    await engine.push({ snapshotId: 'sync-base' });
+    // 本地改 blue / 远端改 red，且两侧的敏感值不同 → 该键必然留冲突，预览里必须有值可脱敏
+    ctx.settings.ns.set('general', { value: { theme: 'blue', webhook: 'sk-live-AB12cd34EF56gh78' }, revision: 4, secrets: [] });
+    seedRemoteSnapshot(transport, {
+      id: 'sync-remote',
+      createdAt: '2026-08-16T12:00:00.000Z',
+      manifest: { schemaVersion: 1, dshVersion: '1.2.3', platform: 'win32', sectionIds: ['settings'], containsSecrets: false },
+      sections: {
+        settings: {
+          version: 1,
+          namespaces: { general: { value: { theme: 'red', webhook: 'sk-live-Zx98wv76ut54sr32' }, revision: 9, secrets: [] } },
+        },
+      },
+    });
+
+    const before = { state: await snapshotTree(tmp), anc: await snapshotTree(ancestors) };
+    const preview = await engine.previewMerge();
+    const after = { state: await snapshotTree(tmp), anc: await snapshotTree(ancestors) };
+    assert.deepEqual(after, before, 'previewMerge 必须零写入（状态目录 + 祖先目录逐字节不变）');
+
+    assert.equal(preview.ok, true);
+    assert.equal(preview.snapshotId, 'sync-remote');
+    assert.equal(preview.hasAncestor, true, '有祖先副本 → 三方合并');
+    const settings = preview.sections.find((s) => s.id === 'settings');
+    assert.ok(settings !== undefined, 'plan 应含 settings');
+    assert.equal(settings!.decision, 'conflict');
+    assert.ok(settings!.conflictCount >= 1);
+    const conflict = settings!.conflicts[0]!;
+    assert.ok(conflict.localPreview.includes('blue'), '本机侧预览: ' + conflict.localPreview);
+    assert.ok(conflict.remotePreview.includes('red'), '远端侧预览: ' + conflict.remotePreview);
+    const serialized = JSON.stringify(preview);
+    assert.ok(!serialized.includes('sk-live-AB12cd34EF56gh78'), '本机侧敏感值绝不回传浏览器');
+    assert.ok(!serialized.includes('sk-live-Zx98wv76ut54sr32'), '远端侧敏感值绝不回传浏览器');
+    assert.ok(!serialized.includes('sk-anc-0000000000000000'), '祖先侧敏感值绝不回传浏览器');
+    assert.ok(serialized.includes('REDACTED'), '预览文本必须过 redact: ' + serialized.slice(0, 400));
+    // 预览必须是**字符串**（原始值对象绝不直接上抛给浏览器）
+    assert.ok(preview.sections.every((s) => s.conflicts.every((c) =>
+      typeof c.localPreview === 'string' && typeof c.remotePreview === 'string' && typeof c.ancestorPreview === 'string')));
+    assert.equal(preview.summary.conflicts, 1);
+    assert.ok(preview.summary.review >= 1, '冲突项必须计入需人工');
+    assert.equal(preview.summary.skipped >= 0, true);
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});
+
+test('previewMerge: 无祖先副本 → hasAncestor=false 且两侧差异一律呈现为 conflict', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-preview-noanc-'));
+  try {
+    const ctx = makeContext('win32', 'C:\\Users\\alice');
+    seedSource(ctx);
+    const transport = new MemSyncTransport();
+    // 不给 localSnapshotsDir → 没有本地祖先副本
+    const engine = makeEngine({ ctx, transport, stateDir: tmp });
+    seedRemoteSnapshot(transport, remoteSettingsSnapshot('sync-remote', 'light', 5));
+    const preview = await engine.previewMerge();
+    assert.equal(preview.ok, true);
+    assert.equal(preview.hasAncestor, false);
+    const settings = preview.sections.find((s) => s.id === 'settings');
+    assert.equal(settings?.decision, 'conflict', '无祖先 → 不猜，两侧差异按冲突呈现');
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});
+
+test('applyMergeResolutions: skip 的裁决 → 基线不推进 + pendingMerge 记录 + 本机不被写', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-merge-pending-'));
+  try {
+    const ctx = makeContext('win32', 'C:\\Users\\alice');
+    seedSource(ctx);
+    ctx.settings.ns.set('general', { value: { theme: 'dark' }, revision: 3, secrets: [] });
+    const transport = new MemSyncTransport();
+    const engine = makeEngine({ ctx, transport, stateDir: tmp, localSnapshotsDir: path.join(tmp, 'anc') });
+    await engine.push({ snapshotId: 'sync-base' });
+    ctx.settings.ns.set('general', { value: { theme: 'blue' }, revision: 4, secrets: [] });
+    seedRemoteSnapshot(transport, remoteSettingsSnapshot('sync-remote', 'red', 9));
+
+    const report = await engine.applyMergeResolutions([{ id: 'settings', action: 'skip' }]);
+    assert.equal(report.ok, true);
+    assert.deepEqual(report.applied, []);
+    assert.deepEqual(report.pendingConflicts, ['settings']);
+    assert.ok(report.warnings.some((w) => w.includes('settings')), '待裁决必须可见: ' + report.warnings.join(' | '));
+
+    const state = await loadSyncState(tmp);
+    assert.equal(state.lastSnapshotId, 'sync-base', '冲突未裁决 → 远端指针保持原值');
+    assert.deepEqual(state.pendingMerge?.sections, ['settings']);
+    assert.equal(state.pendingMerge?.remoteSnapshotId, 'sync-remote');
+    assert.notEqual(state.pendingMerge?.since, '');
+    assert.equal((ctx.settings.ns.get('general')!.value as { theme: string }).theme, 'blue', '本机未被覆盖');
+    // 磁盘原文断言（不经 loadSyncState 的归一化）：lastSnapshotId 必须逐字不变，pendingMerge 必须落盘
+    const raw = JSON.parse(await fs.readFile(path.join(tmp, SYNC_STATE_FILE), 'utf8'));
+    assert.equal(raw.lastSnapshotId, 'sync-base', 'sync-state.json 里的基线指针原文不变');
+    assert.equal(raw.schemaVersion, SYNC_STATE_SCHEMA_VERSION, '不提升 schemaVersion');
+    assert.deepEqual(raw.pendingMerge.sections, ['settings']);
+    assert.equal(raw.pendingMerge.remoteSnapshotId, 'sync-remote');
+
+    // 冲突下一轮重新出现（基线没推进 → 远端那版仍被当作新快照）
+    const again = await engine.previewMerge();
+    assert.equal(again.sections.find((s) => s.id === 'settings')?.decision, 'conflict');
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});
+
+test('applyMergeResolutions: 全部裁决 → 基线推进到远端快照 + pendingMerge 清空 + 本机被写', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-merge-resolved-'));
+  try {
+    const ctx = makeContext('win32', 'C:\\Users\\alice');
+    seedSource(ctx);
+    ctx.settings.ns.set('general', { value: { theme: 'dark' }, revision: 3, secrets: [] });
+    const transport = new MemSyncTransport();
+    const engine = makeEngine({ ctx, transport, stateDir: tmp, localSnapshotsDir: path.join(tmp, 'anc') });
+    await engine.push({ snapshotId: 'sync-base' });
+    ctx.settings.ns.set('general', { value: { theme: 'blue' }, revision: 4, secrets: [] });
+    seedRemoteSnapshot(transport, remoteSettingsSnapshot('sync-remote', 'red', 9));
+
+    // 先留一个待裁决状态，再全部裁决 → 字段必须被清掉
+    const pending = await engine.applyMergeResolutions([{ id: 'settings', action: 'skip' }]);
+    assert.deepEqual(pending.pendingConflicts, ['settings']);
+    assert.equal((await loadSyncState(tmp)).lastSnapshotId, 'sync-base');
+
+    const report = await engine.applyMergeResolutions([{ id: 'settings', action: 'useRemote' }]);
+    assert.equal(report.ok, true);
+    assert.deepEqual(report.applied, ['settings']);
+    assert.deepEqual(report.pendingConflicts, [], '没有待裁决分区了');
+    assert.equal((ctx.settings.ns.get('general')!.value as { theme: string }).theme, 'red', '远端整分区胜出');
+    const state = await loadSyncState(tmp);
+    assert.equal(state.lastSnapshotId, 'sync-remote', '全部裁决完 → 基线推进');
+    assert.equal(state.pendingMerge, undefined, 'pendingMerge 必须清空');
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});
+
+test('applyMergeResolutions: useMerged 对 conflict 分区（无 merged）→ 计入待裁决，不写本机', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-merge-usemerged-'));
+  try {
+    const ctx = makeContext('win32', 'C:\\Users\\alice');
+    seedSource(ctx);
+    ctx.settings.ns.set('general', { value: { theme: 'dark' }, revision: 3, secrets: [] });
+    const transport = new MemSyncTransport();
+    const engine = makeEngine({ ctx, transport, stateDir: tmp, localSnapshotsDir: path.join(tmp, 'anc') });
+    await engine.push({ snapshotId: 'sync-base' });
+    ctx.settings.ns.set('general', { value: { theme: 'blue' }, revision: 4, secrets: [] });
+    seedRemoteSnapshot(transport, remoteSettingsSnapshot('sync-remote', 'red', 9));
+
+    const report = await engine.applyMergeResolutions([{ id: 'settings', action: 'useMerged' }]);
+    assert.deepEqual(report.pendingConflicts, ['settings']);
+    assert.deepEqual(report.applied, []);
+    assert.equal((ctx.settings.ns.get('general')!.value as { theme: string }).theme, 'blue');
+    assert.equal((await loadSyncState(tmp)).lastSnapshotId, 'sync-base');
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});
+
+test('applyMergeResolutions: keepLocal 全部裁决 → 本机不变且基线推进（决策不被下一轮推翻）', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-merge-keeplocal-'));
+  try {
+    const ctx = makeContext('win32', 'C:\\Users\\alice');
+    seedSource(ctx);
+    ctx.settings.ns.set('general', { value: { theme: 'dark' }, revision: 3, secrets: [] });
+    const transport = new MemSyncTransport();
+    const engine = makeEngine({ ctx, transport, stateDir: tmp, localSnapshotsDir: path.join(tmp, 'anc') });
+    await engine.push({ snapshotId: 'sync-base' });
+    ctx.settings.ns.set('general', { value: { theme: 'blue' }, revision: 4, secrets: [] });
+    seedRemoteSnapshot(transport, remoteSettingsSnapshot('sync-remote', 'red', 9));
+
+    const report = await engine.applyMergeResolutions([{ id: 'settings', action: 'keepLocal' }]);
+    assert.equal(report.ok, true);
+    assert.deepEqual(report.pendingConflicts, []);
+    assert.equal((ctx.settings.ns.get('general')!.value as { theme: string }).theme, 'blue', '本机裁决胜出');
+    assert.equal((await loadSyncState(tmp)).lastSnapshotId, 'sync-remote');
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});
+
+test('applyMergeResolutions: 写回失败 → 整体回滚 + 基线不变 + 不写 pendingMerge', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-merge-applyfail-'));
+  try {
+    const ctx = makeContext('win32', 'C:\\Users\\alice');
+    seedSource(ctx);
+    ctx.settings.ns.set('general', { value: { theme: 'dark' }, revision: 3, secrets: [] });
+    const transport = new MemSyncTransport();
+    const mock = new MockImporter();
+    mock.ok = false;
+    const engine = makeEngineWithMockImporter({
+      ctx, transport, stateDir: tmp, localSnapshotsDir: path.join(tmp, 'anc'), mockImporter: mock,
+    });
+    await engine.push({ snapshotId: 'sync-base' });
+    ctx.settings.ns.set('general', { value: { theme: 'blue' }, revision: 4, secrets: [] });
+    seedRemoteSnapshot(transport, remoteSettingsSnapshot('sync-remote', 'red', 9));
+
+    const report = await engine.applyMergeResolutions([{ id: 'settings', action: 'useRemote' }]);
+    assert.equal(report.ok, false, '失败 → ok:false');
+    assert.equal(report.rolledBack, true, '失败 → 整体回滚');
+    assert.deepEqual(report.applied, []);
+    const state = await loadSyncState(tmp);
+    assert.equal(state.lastSnapshotId, 'sync-base', '失败绝不推进基线');
+    assert.equal(state.pendingMerge, undefined, '失败路径不写待裁决记录');
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});
+
+test('applyMergeResolutions: 远端无快照 → 空报告（ok:true，不构造计划、不抛错）', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-merge-empty-'));
+  try {
+    const ctx = makeContext('win32', 'C:\\Users\\alice');
+    seedSource(ctx);
+    const transport = new MemSyncTransport();
+    const engine = makeEngine({ ctx, transport, stateDir: tmp });
+    const report = await engine.applyMergeResolutions([{ id: 'settings', action: 'useRemote' }]);
+    assert.equal(report.ok, true);
+    assert.deepEqual(report.pendingConflicts, []);
+    assert.deepEqual(report.applied, []);
+    const preview = await engine.previewMerge();
+    assert.equal(preview.ok, false);
+    assert.equal(preview.snapshotId, '');
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});
+