dsh-config-manager 0.1.78 → 0.1.79

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

@@ -9,7 +9,7 @@ import os from 'node:os';
 import path from 'node:path';
 
 import {
-  readSyncHistory, appendAutosyncEntry, SYNC_HISTORY_FILE,
+  readSyncHistory, appendAutosyncEntry, markAutosyncNotified, SYNC_HISTORY_FILE,
   AUTOSYNC_HISTORY_KEEP,
 } from './sync-history.ts';
 import type { AutosyncHistoryEntry } from './sync-history.ts';
@@ -114,3 +114,18 @@ test('appendAutosyncEntry：原子写（不残留 .tmp 文件）', async () => {
     assert.ok(!files.some((f) => f.includes('.tmp')), '不应残留 .tmp 临时文件');
   } finally { await fs.rm(dir, { recursive: true, force: true }); }
 });
+test('markAutosyncNotified：连续失败通知的 notifiedAt 真正落盘（issue #105）', async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-history-notified-'));
+  try {
+    const entry = makeEntry(1, 'failed');
+    await appendAutosyncEntry(dir, entry);
+    const notifiedAt = '2026-08-17T11:00:00.000Z';
+    assert.equal(await markAutosyncNotified(dir, entry.createdAt, notifiedAt), true);
+    const hist = await readSyncHistory(dir);
+    // 此前只改内存对象、从不落盘 —— 通知事实等于没留下
+    assert.equal(hist.autosyncEntries[0]!.notifiedAt, notifiedAt, '通知时间必须留在历史记录里');
+    // 未命中记录 → false，且不产生新条目、不改条目数
+    assert.equal(await markAutosyncNotified(dir, '2026-01-01T00:00:00.000Z', notifiedAt), false);
+    assert.equal((await readSyncHistory(dir)).autosyncEntries.length, 1);
+  } finally { await fs.rm(dir, { recursive: true, force: true }); }
+});

package/src/sync/sync-history.ts

@@ -118,3 +118,29 @@ export async function appendAutosyncEntry(
   const data = stringifyJsonSafe(current, { space: 2 });
   await atomicWriteFile(target, data, { mode: 0o600 });
 }
+
+/**
+ * 给指定 createdAt 的自动同步记录补 notifiedAt 并落盘（issue #105）。
+ *
+ * 为什么不再借道 autosync-config：此前「连续失败 ≥ 3」的通知文案被写进 lastRunMessage，
+ * 与「本轮错误原文」抢同一个字段 —— 界面据此渲染出与真实状态无关的通知文案。
+ * 通知的持久痕迹只留历史 entry 的 notifiedAt；未命中记录返回 false（不写文件）。
+ */
+export async function markAutosyncNotified(
+  dir: string,
+  createdAt: string,
+  notifiedAt: string,
+  opts: { now?: () => Date; readHistory?: (dir: string) => Promise<SyncHistoryFile> } = {},
+): Promise<boolean> {
+  const readHistory = opts.readHistory ?? readSyncHistory;
+  const current = await readHistory(dir);
+  const entry = current.autosyncEntries.find((e) => e.createdAt === createdAt);
+  if (entry === undefined) return false;
+  entry.notifiedAt = notifiedAt;
+  current.updatedAt = (opts.now ?? (() => new Date()))().toISOString();
+
+  await fs.mkdir(dir, { recursive: true });
+  const target = path.join(dir, SYNC_HISTORY_FILE);
+  await atomicWriteFile(target, stringifyJsonSafe(current, { space: 2 }), { mode: 0o600 });
+  return true;
+}

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

@@ -231,6 +231,70 @@ test('saveSyncState / loadSyncState: ancestorId 与 lastSnapshotId 相互独立
   }
 });
 
+/* ---------------- 基线纪律：pendingMerge（纯可选字段，不提升 schemaVersion） ---------------- */
+
+test('saveSyncState / loadSyncState: pendingMerge 往返（旧调用方缺省不写该字段）', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-sync-state-pending-'));
+  try {
+    const state: SyncState = {
+      schemaVersion: SYNC_STATE_SCHEMA_VERSION,
+      lastSyncAt: '2026-08-16T12:00:00.000Z',
+      sections: {},
+      lastSnapshotId: 'sync-base',
+      ancestorId: '',
+      pendingMerge: { remoteSnapshotId: 'sync-remote', sections: ['settings', 'skills'], since: '2026-08-16T12:00:00.000Z' },
+    };
+    await saveSyncState(tmp, state);
+    const raw = JSON.parse(await fs.readFile(path.join(tmp, SYNC_STATE_FILE), 'utf8'));
+    assert.equal(raw.schemaVersion, SYNC_STATE_SCHEMA_VERSION, '纯可选字段不提升 schemaVersion');
+    assert.deepEqual(raw.pendingMerge, state.pendingMerge, '逐字落盘');
+    const loaded = await loadSyncState(tmp);
+    assert.deepEqual(loaded.pendingMerge, state.pendingMerge, '读回形状一致');
+    assert.deepEqual(loaded, state);
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});
+
+test('loadSyncState: 缺 pendingMerge 的旧文件 → 读回形状逐键不变（字段缺席，不是 undefined 键）', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-sync-state-nopending-'));
+  try {
+    await fs.writeFile(
+      path.join(tmp, SYNC_STATE_FILE),
+      JSON.stringify({ schemaVersion: 3, lastSyncAt: '', sections: {}, lastSnapshotId: '', ancestorId: '' }),
+      'utf8',
+    );
+    const state = await loadSyncState(tmp);
+    assert.equal('pendingMerge' in state, false, '缺席 = 无待裁决冲突（不凭空造一个空记录）');
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});
+
+test('loadSyncState: 形状损坏/分区清单为空的 pendingMerge → 按「无待裁决冲突」处理，不抛错', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-sync-state-pending-bad-'));
+  try {
+    const cases: unknown[] = [
+      'not-an-object',
+      { remoteSnapshotId: 'x', since: 'y', sections: 'nope' },
+      { remoteSnapshotId: 42, since: 'y', sections: ['settings'] },
+      { remoteSnapshotId: 'x', sections: ['settings'] }, // 缺 since
+      { remoteSnapshotId: 'x', since: 'y', sections: [] }, // 空清单 = 没有内容可记录
+    ];
+    for (const bad of cases) {
+      await fs.writeFile(
+        path.join(tmp, SYNC_STATE_FILE),
+        JSON.stringify({ schemaVersion: 3, lastSyncAt: '', sections: {}, lastSnapshotId: '', ancestorId: '', pendingMerge: bad }),
+        'utf8',
+      );
+      const state = await loadSyncState(tmp);
+      assert.equal('pendingMerge' in state, false, '损坏形态不得让 loadSyncState 失败: ' + JSON.stringify(bad));
+    }
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});
+
 test('loadSyncState: 非字符串 ancestorId（损坏/被篡改）→ 按「无本地祖先副本」处理，不抛错', async () => {
   const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-sync-state-anc-bad-'));
   try {

package/src/sync/sync-state.ts

@@ -3,6 +3,7 @@
  * 记录上次同步时间与各分区内容 hash，供变更检测（与远端快照对比决定是否重传）。
  * 纯逻辑 + 可注入 fs；不触碰真实 ~/.dsh。
  */
+import { randomUUID } from 'node:crypto';
 import { sha256Hex } from '../utils/hashing.ts';
 import { parseJsonSafe, stringifyJsonSafe } from '../utils/json.ts';
 import { zhMsg } from '../core/messages.ts';
@@ -10,6 +11,8 @@ import type { MsgFunc } from '../core/messages.ts';
 import type { FilesSection, SectionData, SectionId } from '../schema/types.ts';
 import { createSnapshotFs, joinFs } from './fs.ts';
 import type { SnapshotFs } from './fs.ts';
+// 侧效应导入：注册同步域追加消息目录（sync.deviceNameFallback 等 ⑥ 新键必须能解析，绝不露裸键名）
+import './messages.ts';
 
 export const SYNC_STATE_SCHEMA_VERSION = 3;
 /**
@@ -28,6 +31,25 @@ export interface SyncSectionState {
   updatedAt: string; // ISO-8601 UTC
 }
 
+/**
+ * 待裁决的合并状态（基线纪律，2026-10）。
+ *
+ * 非空 = 上一次三方合并**仍有未裁决的冲突**，因此 lastSnapshotId 刻意**不推进**：
+ * 远端的最新快照下一轮仍会被当作「比基线新」而重新合并，冲突因此重新出现，直到用户裁决完。
+ * 若在冲突未裁决时就推进基线，冲突内容会在下一轮静默消失（远端那一版改动永远不再被讨论）。
+ *
+ * 纯可选字段：**不提升 SYNC_STATE_SCHEMA_VERSION**（旧文件缺该字段 → 读取形状逐键不变；
+ * 旧版本代码读到新文件也只是忽略它）。
+ */
+export interface PendingMerge {
+  /** 冲突所针对的**远端**快照 id（基线指针此刻仍停在更早的那一个）。 */
+  remoteSnapshotId: string;
+  /** 仍未裁决的分区 id（非空；空 = 没有待裁决内容，调用方应清除该字段）。 */
+  sections: SectionId[];
+  /** 该待裁决状态**首次**出现的时刻（ISO-8601 UTC；跨轮保留首次时间，便于界面讲「挂了多久」）。 */
+  since: string;
+}
+
 /** sync-state.json 结构 */
 export interface SyncState {
   schemaVersion: number;
@@ -57,6 +79,19 @@ export interface SyncState {
    * 本机若又出现该会话的实体，对应墓碑会被撤销（有实体 = 没删）。
    */
   deletedSessions?: string[];
+  /**
+   * cloud-sync 借鉴项 ⑥：本设备的**稳定**同步身份（首次推送时生成并持久化）。
+   *
+   * deviceId = 随机 UUID（换主机名/改机器名都不变，历史列表据此认出「同一台设备」）；
+   * deviceName = 人类可读名（缺省取主机名）。缺省 = 旧文件 / 从未推送（不猜）。
+   */
+  deviceId?: string;
+  deviceName?: string;
+  /**
+   * 基线纪律（2026-10）：未裁决冲突记录。非空 = 基线指针**刻意停在旧值**，
+   * 让冲突在下一轮重新出现（详见 PendingMerge）。
+   */
+  pendingMerge?: PendingMerge;
 }
 
 /** 文件类分区判定：{ version: 1, files: [...] }（duck-typing，与 JSON 分区区分） */
@@ -114,6 +149,22 @@ function readStringArray(raw: unknown): string[] {
   return out;
 }
 
+/**
+ * 读取可选 pendingMerge（基线纪律）。
+ *
+ * 形状不符（损坏/被篡改/分区清单为空）→ undefined = 按「无待裁决冲突」处理：
+ * 这里**绝不抛错**（一个诊断字段不该让 loadSyncState 整体失败），也绝不把空清单当成
+ * 「所有冲突都解决了」—— 空清单只是没有内容可记录。
+ */
+function readPendingMerge(raw: unknown): PendingMerge | undefined {
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return undefined;
+  const o = raw as Record<string, unknown>;
+  if (typeof o['remoteSnapshotId'] !== 'string' || typeof o['since'] !== 'string') return undefined;
+  const sections = readStringArray(o['sections']);
+  if (sections.length === 0) return undefined;
+  return { remoteSnapshotId: o['remoteSnapshotId'], sections: sections as SectionId[], since: o['since'] };
+}
+
 /** 读取同步状态；文件不存在 → 返回缺省空状态（从未同步）。
  * 旧版本文件（v1/v2）→ 在内存中迁移到当前版本（见 SYNC_STATE_SUPPORTED_VERSIONS），
  * 不在磁盘上就地升级（首次 saveSyncState 时才写回新版本）。 */
@@ -164,6 +215,11 @@ export async function loadSyncState(dir: string, fsx: SnapshotFs = createSnapsho
     // 绝不采用一个来路不明的目录名。
     ancestorId: rawAncestorId ?? (fileVersion < SYNC_STATE_SCHEMA_VERSION ? rawLastSnapshotId : ''),
     lastSnapshotId: rawLastSnapshotId,
+    // ⑥：只有文件里确实写过才回填（缺席 = 从未记录 → 下次推送才生成，绝不在这里凭空造一个 id）
+    ...(typeof obj['deviceId'] === 'string' && obj['deviceId'] !== '' ? { deviceId: obj['deviceId'] } : {}),
+    ...(typeof obj['deviceName'] === 'string' && obj['deviceName'] !== '' ? { deviceName: obj['deviceName'] } : {}),
+    // 基线纪律：同样「写过才回填」—— 缺席 = 无待裁决冲突（旧文件读回形状逐键不变）
+    ...(readPendingMerge(obj['pendingMerge']) !== undefined ? { pendingMerge: readPendingMerge(obj['pendingMerge'])! } : {}),
   };
   const t = obj['transport'];
   if (t !== undefined) {
@@ -175,6 +231,29 @@ export async function loadSyncState(dir: string, fsx: SnapshotFs = createSnapsho
   return state;
 }
 
+/**
+ * 解析（必要时生成并持久化）本设备的同步身份（cloud-sync 借鉴项 ⑥）。
+ *
+ * - deviceId 一旦生成就持久化在 sync-state.json → 历史列表能认出「同一台设备」；
+ * - deviceName 缺省取主机名，取不到（容器/无主机名）时用字典里的兜底文案，绝不写空串；
+ * - **只在首次生成时写盘**（已有 id → 纯读，不产生额外写）。
+ */
+export async function resolveDeviceIdentity(
+  dir: string,
+  hostName: string,
+  fsx: SnapshotFs = createSnapshotFs(),
+  msg: MsgFunc = zhMsg,
+): Promise<{ id: string; name: string }> {
+  const state = await loadSyncState(dir, fsx, msg);
+  const trimmedHost = typeof hostName === 'string' ? hostName.trim() : '';
+  const name = (typeof state.deviceName === 'string' && state.deviceName !== '' ? state.deviceName : '')
+    || (trimmedHost !== '' ? trimmedHost : msg('sync.deviceNameFallback'));
+  if (typeof state.deviceId === 'string' && state.deviceId !== '') return { id: state.deviceId, name };
+  const id = randomUUID();
+  await saveSyncState(dir, { ...state, deviceId: id, deviceName: name }, fsx);
+  return { id, name };
+}
+
 /** 保存同步状态（自动创建目录） */
 export async function saveSyncState(dir: string, state: SyncState, fsx: SnapshotFs = createSnapshotFs()): Promise<void> {
   await fsx.mkdir(dir);

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

@@ -0,0 +1,197 @@
+/**
+ * **本地改动监听器**单测（src/sync/sync-watcher.ts）。
+ *
+ * 盯四件事：
+ *  1. 文件目标监听父目录 + basename 过滤（原子写 rename 后句柄不失）；
+ *  2. 一次保存连写多个文件 → 去抖合并成一次 onFlush，且噪声路径被挡掉；
+ *  3. suspend/resume 的自写回声屏蔽（否则 push→apply→push 死循环）；
+ *  4. 监听失败绝不抛错（兜底是定时器），stop/setTargets 必须关掉旧句柄。
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import path from 'node:path';
+
+import { SyncWatcher } from './sync-watcher.ts';
+import { buildWatchTargets, type WatchTarget } from './watch-scope.ts';
+import type { Logger } from '../utils/logger.ts';
+
+const HOME = path.join(path.sep, 'home', 'u', '.dsh');
+
+interface FakeListener { absPath: string; recursive: boolean; fn: (event: string, filename: string | null) => void }
+
+function makeLogger(): { log: Logger; warns: string[]; debugs: string[] } {
+  const warns: string[] = [];
+  const debugs: string[] = [];
+  const log = {
+    debug: (m: string) => { debugs.push(m); },
+    info: () => undefined,
+    warn: (m: string) => { warns.push(m); },
+    error: () => undefined,
+  } as unknown as Logger;
+  return { log, warns, debugs };
+}
+
+function makeHarness(targets: readonly WatchTarget[], opts: { failOn?: string } = {}) {
+  const listeners: FakeListener[] = [];
+  const handles: Array<{ absPath: string; closed: boolean }> = [];
+  const flushes: string[][] = [];
+  const timers: Array<() => void> = [];
+  let nowMs = 10_000;
+  const { log, warns, debugs } = makeLogger();
+  const watcher = new SyncWatcher({
+    homeDir: HOME,
+    targets,
+    log,
+    onFlush: (changed) => { flushes.push([...changed]); },
+    watchFactory: (absPath, o, fn) => {
+      if (opts.failOn !== undefined && absPath === opts.failOn) throw new Error('ENOENT: 不存在');
+      const h = { absPath, closed: false };
+      handles.push(h);
+      listeners.push({ absPath, recursive: o.recursive, fn });
+      return { close: () => { h.closed = true; } };
+    },
+    now: () => nowMs,
+    setTimer: (fn) => { timers.push(fn); return timers.length as unknown as ReturnType<typeof setTimeout>; },
+    clearTimer: () => undefined,
+  });
+  /** 触发某目录上的原生事件（按绝对路径找监听句柄）。 */
+  const fire = (absPath: string, filename: string | null): void => {
+    const hit = listeners.filter((l) => l.absPath === absPath);
+    assert.ok(hit.length > 0, '没有监听 ' + absPath);
+    for (const l of hit) l.fn('change', filename);
+  };
+  const runTimers = (): void => {
+    const pending = [...timers];
+    timers.length = 0;
+    for (const t of pending) t();
+  };
+  return { watcher, listeners, handles, flushes, timers, fire, runTimers, warns, debugs, setNow: (v: number) => { nowMs = v; } };
+}
+
+const TARGETS = buildWatchTargets({ homeDir: HOME });
+const settingsAbs = path.join(HOME, 'settings.yaml');
+const skillsAbs = path.join(HOME, 'skills');
+
+test('start()：每个目标挂一个监听（文件目标监听父目录且非递归），重复调用幂等', () => {
+  const h = makeHarness(TARGETS);
+  h.watcher.start();
+  assert.equal(h.watcher.isStarted(), true);
+  assert.equal(h.watcher.attachmentCount(), TARGETS.length);
+  const fileListener = h.listeners.find((l) => l.absPath === path.dirname(settingsAbs));
+  assert.ok(fileListener !== undefined, 'settings.yaml 必须监听父目录（原子写 rename 后句柄不失）');
+  assert.equal(fileListener!.recursive, false, '文件目标不得递归');
+  const dirListener = h.listeners.find((l) => l.absPath === skillsAbs);
+  assert.equal(dirListener!.recursive, true, '目录目标递归');
+  h.watcher.start();
+  assert.equal(h.watcher.attachmentCount(), TARGETS.length, 'start() 幂等');
+  h.watcher.stop();
+  assert.equal(h.watcher.attachmentCount(), 0);
+  assert.ok(h.handles.every((x) => x.closed), 'stop() 必须关掉每个句柄');
+});
+
+test('文件目标：只认同名 basename；一次保存的连续事件去抖成一次 onFlush', () => {
+  const h = makeHarness(TARGETS);
+  h.watcher.start();
+  const dir = path.dirname(settingsAbs);
+  h.fire(dir, 'other.yaml');
+  assert.equal(h.timers.length, 0, '父目录里别的文件不得触发（否则整目录噪声）');
+  h.fire(dir, 'settings.yaml.tmp-1234-0');
+  assert.equal(h.timers.length, 0, '原子写临时文件是噪声');
+  h.fire(dir, 'settings.yaml');
+  h.fire(dir, 'settings.yaml');
+  assert.equal(h.timers.length, 1, '去抖：多次事件只排一个定时器');
+  h.runTimers();
+  assert.deepEqual(h.flushes, [['settings.yaml']], '去重后只报一次路径');
+});
+
+test('目录目标：递归事件的相对路径按 home 归一化；filename=null 忽略', () => {
+  const h = makeHarness(TARGETS);
+  h.watcher.start();
+  h.fire(skillsAbs, null);
+  assert.equal(h.timers.length, 0, '拿不到文件名的事件不能猜路径');
+  h.fire(skillsAbs, path.join('nodejs-testing', 'SKILL.md'));
+  h.runTimers();
+  assert.deepEqual(h.flushes, [['skills/nodejs-testing/SKILL.md']]);
+});
+
+test('suspend() 丢弃在途事件；resume() 后静默窗口内的事件被推迟到窗口结束（自写回声不触发、用户改动不丢）', () => {
+  const h = makeHarness(TARGETS);
+  h.watcher.start();
+  const dir = path.dirname(settingsAbs);
+  h.fire(dir, 'settings.yaml');
+  assert.equal(h.timers.length, 1);
+  h.watcher.suspend();
+  // suspend 清掉在途去抖：即便那枚已被 clearTimer 的定时器仍被触发，也不得回调
+  h.runTimers();
+  assert.deepEqual(h.flushes, [], 'suspend 必须丢弃在途变更（同步自家 apply/push 的写入不算用户改动）');
+  h.fire(dir, 'settings.yaml');
+  assert.equal(h.timers.length, 0, 'suspend 期间的事件一律屏蔽');
+  h.runTimers();
+  assert.deepEqual(h.flushes, [], '挂起期间不得回调');
+  h.watcher.resume();
+  h.setNow(10_000 + 1_999);
+  h.fire(dir, 'settings.yaml');
+  assert.deepEqual(h.flushes, [], '静默窗口内（<2000ms）不得立刻回调');
+  assert.equal(h.timers.length, 1, '但必须排一枚窗口结束后的补跑定时器（真机实测：直接丢弃会让用户改动等一整轮兜底间隔）');
+  // 平台抖动 / clearTimer 未生效导致定时器提前到期：仍不得在窗口内回调，而是继续推迟
+  h.runTimers();
+  assert.deepEqual(h.flushes, [], '窗口内即便定时器到期也不得回调');
+  assert.equal(h.timers.length, 1, '必须重新排期，绝不把这次改动丢掉');
+  h.setNow(10_000 + 2_001);
+  h.runTimers();
+  assert.deepEqual(h.flushes, [['settings.yaml']], '窗口结束后补跑一次：用户改动照常上行，自家回声由引擎 hash 比对判无变化');
+});
+
+test('stop() 后不再触发；onFlush 抛错只告警（监听不能拖垮宿主）', () => {
+  const { log } = makeLogger();
+  const warns: string[] = [];
+  const throwing = { ...log, warn: (m: string) => { warns.push(m); } } as unknown as Logger;
+  const h = makeHarness(TARGETS);
+  h.watcher.start();
+  const dir = path.dirname(settingsAbs);
+  const stale = h.listeners.filter((l) => l.absPath === dir);
+  assert.ok(stale.length > 0);
+  h.watcher.stop();
+  for (const l of stale) l.fn('change', 'settings.yaml');
+  assert.equal(h.timers.length, 0, 'stop 后事件不得再排期（挂起的句柄回声也要挡）');
+  // 单独构造一个回调抛错的实例
+  const timers: Array<() => void> = [];
+  const w2 = new SyncWatcher({
+    homeDir: HOME,
+    targets: TARGETS,
+    log: throwing,
+    onFlush: () => { throw new Error('上层炸了'); },
+    watchFactory: (absPath, _o, fn) => { fn('change', 'settings.yaml'); return { close: () => undefined }; },
+    setTimer: (fn) => { timers.push(fn); return timers.length as unknown as ReturnType<typeof setTimeout>; },
+    clearTimer: () => undefined,
+  });
+  w2.start();
+  for (const t of [...timers]) t();
+  assert.ok(warns.some((m) => m.includes('自动同步监听回调失败')), '回调抛错必须落 warn，不得冒泡');
+});
+
+test('监听挂载失败（路径不存在）不抛错、不计入附件数，只留 debug', () => {
+  // 用 skills/ 目录目标做失败点：它独占一个监听路径（settings.yaml 等三个文件目标共用 HOME，会一起失败）
+  const h = makeHarness(TARGETS, { failOn: skillsAbs });
+  h.watcher.start();
+  assert.equal(h.watcher.attachmentCount(), TARGETS.length - 1, '失败目标不挂载');
+  assert.ok(h.debugs.some((m) => m.includes('自动同步监听未挂载')), '失败原因写进 debug 日志');
+});
+
+test('setTargets()：原子重启，旧句柄关闭、新目标挂上', () => {
+  const h = makeHarness(TARGETS);
+  h.watcher.start();
+  const before = h.handles.length;
+  const narrowed = TARGETS.filter((t) => t.relPath === 'settings.yaml');
+  h.watcher.setTargets(narrowed);
+  assert.ok(h.handles.slice(0, before).every((x) => x.closed), '换目标必须关掉旧句柄');
+  assert.equal(h.watcher.attachmentCount(), 1);
+  h.watcher.stop();
+});
+
+test('未 start 时 setTargets 只记目标、不挂监听', () => {
+  const h = makeHarness(TARGETS);
+  h.watcher.setTargets(TARGETS);
+  assert.equal(h.watcher.attachmentCount(), 0);
+  assert.equal(h.watcher.isStarted(), false);
+});