dsh-config-manager 0.1.19 → 0.1.21

package/src/sync/ancestor.ts

@@ -0,0 +1,81 @@
+/**
+ * m-sync-flow：共同祖先快照存储助手。
+ * 与 push 落盘的 localSnapshotsDir 共用目录布局；按 snapshotId 读写、按 createdAt 保留最近 N 个。
+ * 纯逻辑 + 可注入 fs；不触碰真实 ~/.dsh。
+ */
+import { createSnapshotFs, joinFs } from './fs.ts';
+import type { SnapshotFs } from './fs.ts';
+import { readSnapshotFromDir, writeSnapshotToDir } from './layout.ts';
+import { SNAPSHOT_MANIFEST_FILE } from './layout.ts';
+import type { SyncSnapshot } from './transport.ts';
+
+/** 默认保留的祖先快照数量（最旧超出则被裁剪）。 */
+export const DEFAULT_ANCESTOR_KEEP = 10;
+
+/** 按 snapshotId 读取祖先快照目录；不存在抛错，不静默降级。 */
+export async function loadAncestor(
+  localSnapshotsDir: string,
+  snapshotId: string,
+  fsx: SnapshotFs = createSnapshotFs(),
+): Promise<SyncSnapshot> {
+  if (typeof snapshotId !== 'string' || snapshotId === '') {
+    throw new Error('loadAncestor: snapshotId 不能为空');
+  }
+  const dir = joinFs(localSnapshotsDir, snapshotId);
+  return await readSnapshotFromDir(dir, fsx);
+}
+
+/** 把合并后的快照写入本地祖先副本目录（覆盖同名 id）。 */
+export async function writeAncestor(
+  localSnapshotsDir: string,
+  snapshot: SyncSnapshot,
+  fsx: SnapshotFs = createSnapshotFs(),
+): Promise<void> {
+  const dir = joinFs(localSnapshotsDir, snapshot.id);
+  await writeSnapshotToDir(snapshot, dir, fsx);
+}
+
+/** 列出 localSnapshotsDir 下全部祖先快照目录的 (id, createdAt) 对，按 createdAt 升序。 */
+export async function listAncestors(
+  localSnapshotsDir: string,
+  fsx: SnapshotFs = createSnapshotFs(),
+): Promise<Array<{ id: string; createdAt: string }>> {
+  if (!(await fsx.exists(localSnapshotsDir))) return [];
+  const names = await fsx.readdir(localSnapshotsDir);
+  const out: Array<{ id: string; createdAt: string }> = [];
+  for (const name of names) {
+    const dir = joinFs(localSnapshotsDir, name);
+    const manifestPath = joinFs(dir, SNAPSHOT_MANIFEST_FILE);
+    if (!(await fsx.exists(manifestPath))) continue;
+    try {
+      const raw = Buffer.from(await fsx.readFile(manifestPath)).toString('utf8');
+      const parsed = JSON.parse(raw) as { id?: unknown; createdAt?: unknown };
+      if (typeof parsed.id === 'string' && typeof parsed.createdAt === 'string') {
+        out.push({ id: parsed.id, createdAt: parsed.createdAt });
+      }
+    } catch {
+      // 单个快照目录损坏不影响整体列表
+    }
+  }
+  out.sort((a, b) => (a.createdAt < b.createdAt ? -1 : a.createdAt > b.createdAt ? 1 : 0));
+  return out;
+}
+
+/** 保留最近 keep 个祖先（按 createdAt 升序的最末 keep 个）；其余删除。
+ * keep <= 0 视为保留全部（不做任何删除）。
+ * 返回被删除的祖先 id 列表（按 createdAt 升序，即先删最旧）。 */
+export async function pruneAncestors(
+  localSnapshotsDir: string,
+  keep: number = DEFAULT_ANCESTOR_KEEP,
+  fsx: SnapshotFs = createSnapshotFs(),
+): Promise<string[]> {
+  const all = await listAncestors(localSnapshotsDir, fsx);
+  if (keep <= 0 || all.length <= keep) return [];
+  const toRemove = all.slice(0, all.length - keep);
+  const removed: string[] = [];
+  for (const a of toRemove) {
+    await fsx.remove(joinFs(localSnapshotsDir, a.id));
+    removed.push(a.id);
+  }
+  return removed;
+}

package/src/sync/autosync-config.test.ts

@@ -0,0 +1,93 @@
+/**
+ * autosync-config 测试：sync-autosync.json 读写往返、缺省值、损坏 JSON 回退缺省、原子写。
+ */
+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 {
+  readAutosyncConfig, writeAutosyncConfig, AUTOSYNC_CONFIG_FILE,
+  AUTOSYNC_CONFIG_SCHEMA_VERSION, DEFAULT_AUTOSYNC_INTERVAL,
+  DEFAULT_STARTUP_MIN_INTERVAL_MS,
+} from './autosync-config.ts';
+
+test('writeAutosyncConfig + readAutosyncConfig：写入 → 读回字段一致', async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-autosync-rt-'));
+  try {
+    await writeAutosyncConfig(dir, {
+      enabled: true,
+      interval: '15m',
+      startupMinIntervalMs: 300000,
+      consecutiveFailures: 2,
+      lastRunAt: '2026-08-16T12:00:00.000Z',
+      lastRunStatus: 'skipped',
+      lastRunMessage: '有冲突项，跳过',
+      lastRunHistoryId: 'hist-1',
+    });
+    const cfg = await readAutosyncConfig(dir);
+    assert.equal(cfg.enabled, true);
+    assert.equal(cfg.interval, '15m');
+    assert.equal(cfg.startupMinIntervalMs, 300000);
+    assert.equal(cfg.consecutiveFailures, 2);
+    assert.equal(cfg.lastRunAt, '2026-08-16T12:00:00.000Z');
+    assert.equal(cfg.lastRunStatus, 'skipped');
+    assert.equal(cfg.lastRunMessage, '有冲突项，跳过');
+    assert.equal(cfg.lastRunHistoryId, 'hist-1');
+    // 原始文件校验
+    const raw = JSON.parse(await fs.readFile(path.join(dir, AUTOSYNC_CONFIG_FILE), 'utf8'));
+    assert.equal(raw.schemaVersion, AUTOSYNC_CONFIG_SCHEMA_VERSION);
+    assert.equal(raw.enabled, true);
+    assert.equal(raw.interval, '15m');
+  } finally { await fs.rm(dir, { recursive: true, force: true }); }
+});
+
+test('readAutosyncConfig：文件不存在 → 返回缺省值', async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-autosync-default-'));
+  try {
+    const cfg = await readAutosyncConfig(dir);
+    assert.equal(cfg.enabled, false);
+    assert.equal(cfg.interval, DEFAULT_AUTOSYNC_INTERVAL);
+    assert.equal(cfg.startupMinIntervalMs, DEFAULT_STARTUP_MIN_INTERVAL_MS);
+    assert.equal(cfg.consecutiveFailures, 0);
+    assert.equal(cfg.lastRunAt, undefined);
+    assert.equal(cfg.lastRunStatus, undefined);
+  } finally { await fs.rm(dir, { recursive: true, force: true }); }
+});
+
+test('readAutosyncConfig：损坏 JSON → 回退缺省', async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-autosync-corrupt-'));
+  try {
+    await fs.writeFile(path.join(dir, AUTOSYNC_CONFIG_FILE), '{not-json', 'utf8');
+    const cfg = await readAutosyncConfig(dir);
+    assert.equal(cfg.enabled, false);
+    assert.equal(cfg.interval, DEFAULT_AUTOSYNC_INTERVAL);
+    assert.equal(cfg.startupMinIntervalMs, DEFAULT_STARTUP_MIN_INTERVAL_MS);
+  } finally { await fs.rm(dir, { recursive: true, force: true }); }
+});
+
+test('readAutosyncConfig：不支持的 schemaVersion → 回退缺省', async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-autosync-badver-'));
+  try {
+    await fs.writeFile(path.join(dir, AUTOSYNC_CONFIG_FILE),
+      JSON.stringify({ schemaVersion: 99, enabled: true }), 'utf8');
+    const cfg = await readAutosyncConfig(dir);
+    assert.equal(cfg.enabled, false);
+  } finally { await fs.rm(dir, { recursive: true, force: true }); }
+});
+
+test('writeAutosyncConfig：原子写（自动创建目录）', async () => {
+  const base = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-autosync-mkdir-'));
+  try {
+    const dir = path.join(base, 'nested', 'sync');
+    await writeAutosyncConfig(dir, { enabled: true, interval: '30m', startupMinIntervalMs: 300000, consecutiveFailures: 0 });
+    const cfg = await readAutosyncConfig(dir);
+    assert.ok(cfg);
+    assert.equal(cfg.enabled, true);
+    // 确认没有残留临时文件
+    const files = await fs.readdir(dir);
+    assert.ok(files.length >= 1, '应有配置文件');
+    assert.ok(!files.some((f) => f.includes('.tmp')), '不应残留 .tmp 临时文件');
+  } finally { await fs.rm(base, { recursive: true, force: true }); }
+});

package/src/sync/autosync-config.ts

@@ -0,0 +1,137 @@
+/**
+ * m-autosync：自动同步配置持久化（sync-autosync.json）。
+ *
+ * 与 sync-config.json 并列独立文件：语义清楚、schema 演进独立。
+ * schemaVersion:1，字段 { enabled, interval, startupMinIntervalMs, consecutiveFailures,
+ * lastRunAt, lastRunStatus, lastRunMessage, lastRunHistoryId }。
+ *
+ * 原子写（临时文件 + rename），损坏/不支持 schema 回退缺省（enabled=false,
+ * interval='30m', startupMinIntervalMs=5*60*1000）。
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+import { parseJsonSafe, stringifyJsonSafe } from '../utils/json.ts';
+
+export const AUTOSYNC_CONFIG_FILE = 'sync-autosync.json';
+export const AUTOSYNC_CONFIG_SCHEMA_VERSION = 1;
+
+/** 统一间隔类型 */
+export type AutosyncInterval = '5m' | '15m' | '30m' | '60m' | '6h' | '12h' | '24h';
+
+/** 缺省间隔 */
+export const DEFAULT_AUTOSYNC_INTERVAL: AutosyncInterval = '30m';
+
+/** 缺省启动触发最小间隔阈值（5 分钟，防频繁重启反复同步） */
+export const DEFAULT_STARTUP_MIN_INTERVAL_MS = 5 * 60 * 1000;
+
+/** 最近一次自动同步执行状态 */
+export type AutosyncRunStatus = 'success' | 'skipped' | 'failed' | 'partial';
+
+/** 自动同步配置（持久化面） */
+export interface AutosyncConfig {
+  /** 总开关（同时控制上传 + 下载） */
+  enabled: boolean;
+  /** 统一间隔 */
+  interval: AutosyncInterval;
+  /** 重启触发的「自动下载合并」最小间隔阈值（ms） */
+  startupMinIntervalMs: number;
+  /** 连续失败计数（用于通知判定） */
+  consecutiveFailures: number;
+  /** 最近一次自动同步执行时间（ISO-8601 UTC）；''/undefined = 从未执行 */
+  lastRunAt?: string;
+  /** 最近一次自动同步执行状态 */
+  lastRunStatus?: AutosyncRunStatus;
+  lastRunMessage?: string;
+  /** 最近一次自动同步触发的同步历史条目 id */
+  lastRunHistoryId?: string;
+}
+
+/** 缺省配置（首次无文件 / 损坏 / 不支持 schema 时回退） */
+export function defaultAutosyncConfig(): AutosyncConfig {
+  return {
+    enabled: false,
+    interval: DEFAULT_AUTOSYNC_INTERVAL,
+    startupMinIntervalMs: DEFAULT_STARTUP_MIN_INTERVAL_MS,
+    consecutiveFailures: 0,
+  };
+}
+
+/** 读取自动同步配置；文件不存在 / 损坏 / 不支持 schema → 缺省值（不抛错）。 */
+export async function readAutosyncConfig(dir: string): Promise<AutosyncConfig> {
+  const file = path.join(dir, AUTOSYNC_CONFIG_FILE);
+  let raw: string;
+  try {
+    raw = await fs.readFile(file, 'utf8');
+  } catch {
+    return defaultAutosyncConfig();
+  }
+  let parsed: unknown;
+  try {
+    parsed = parseJsonSafe(raw);
+  } catch {
+    return defaultAutosyncConfig();
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return defaultAutosyncConfig();
+  }
+  const obj = parsed as Record<string, unknown>;
+  // schemaVersion 必须为 1（不支持其他版本）
+  if (obj['schemaVersion'] !== undefined && obj['schemaVersion'] !== AUTOSYNC_CONFIG_SCHEMA_VERSION) {
+    return defaultAutosyncConfig();
+  }
+  if (obj['schemaVersion'] === undefined) {
+    return defaultAutosyncConfig();
+  }
+  const cfg = defaultAutosyncConfig();
+  if (typeof obj['enabled'] === 'boolean') cfg.enabled = obj['enabled'];
+  if (isAutosyncInterval(obj['interval'])) cfg.interval = obj['interval'];
+  if (typeof obj['startupMinIntervalMs'] === 'number' && Number.isFinite(obj['startupMinIntervalMs']) && obj['startupMinIntervalMs'] > 0) {
+    cfg.startupMinIntervalMs = obj['startupMinIntervalMs'];
+  }
+  if (typeof obj['consecutiveFailures'] === 'number' && Number.isFinite(obj['consecutiveFailures']) && obj['consecutiveFailures'] >= 0) {
+    cfg.consecutiveFailures = obj['consecutiveFailures'];
+  }
+  if (typeof obj['lastRunAt'] === 'string' && obj['lastRunAt'] !== '') cfg.lastRunAt = obj['lastRunAt'];
+  if (typeof obj['lastRunStatus'] === 'string' && (obj['lastRunStatus'] === 'success' || obj['lastRunStatus'] === 'skipped' || obj['lastRunStatus'] === 'failed' || obj['lastRunStatus'] === 'partial')) {
+    cfg.lastRunStatus = obj['lastRunStatus'];
+  }
+  if (typeof obj['lastRunMessage'] === 'string') cfg.lastRunMessage = obj['lastRunMessage'];
+  if (typeof obj['lastRunHistoryId'] === 'string') cfg.lastRunHistoryId = obj['lastRunHistoryId'];
+  return cfg;
+}
+
+/** 写入自动同步配置（原子写：临时文件 + rename；自动创建目录）。 */
+export async function writeAutosyncConfig(dir: string, cfg: AutosyncConfig): Promise<void> {
+  await fs.mkdir(dir, { recursive: true });
+  const payload: Record<string, unknown> = {
+    schemaVersion: AUTOSYNC_CONFIG_SCHEMA_VERSION,
+    enabled: cfg.enabled,
+    interval: cfg.interval,
+    startupMinIntervalMs: cfg.startupMinIntervalMs,
+    consecutiveFailures: cfg.consecutiveFailures,
+  };
+  if (cfg.lastRunAt !== undefined && cfg.lastRunAt !== '') payload['lastRunAt'] = cfg.lastRunAt;
+  if (cfg.lastRunStatus !== undefined) payload['lastRunStatus'] = cfg.lastRunStatus;
+  if (cfg.lastRunMessage !== undefined && cfg.lastRunMessage !== '') payload['lastRunMessage'] = cfg.lastRunMessage;
+  if (cfg.lastRunHistoryId !== undefined && cfg.lastRunHistoryId !== '') payload['lastRunHistoryId'] = cfg.lastRunHistoryId;
+
+  const target = path.join(dir, AUTOSYNC_CONFIG_FILE);
+  const tmp = path.join(
+    dir,
+    `.${AUTOSYNC_CONFIG_FILE}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`,
+  );
+  const data = stringifyJsonSafe(payload, { space: 2 });
+  try {
+    await fs.writeFile(tmp, data, 'utf8');
+    await fs.rename(tmp, target);
+  } catch (err) {
+    try { await fs.rm(tmp, { force: true }); } catch { /* ignore */ }
+    throw err;
+  }
+}
+
+function isAutosyncInterval(v: unknown): v is AutosyncInterval {
+  return v === '5m' || v === '15m' || v === '30m' || v === '60m' || v === '6h' || v === '12h' || v === '24h';
+}

package/src/sync/autosync-scheduler.test.ts

@@ -0,0 +1,191 @@
+/**
+ * AutoSyncScheduler 测试：interval 换算、shouldTriggerStartupRun 阈值、
+ * enabled=false 不执行、连续失败通知、冲突跳过。
+ *
+ * 采用真实 RunRegistry + 注入 readConfig/writeConfig/readSyncConfigFn/readHistoryFn/
+ * appendHistoryFn/makeSyncEngine/now，全程不触碰真实网络与真实定时器。
+ */
+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 {
+  AutoSyncScheduler, intervalToMs, shouldTriggerStartupRun, buildAutoApplyPlan,
+} from './autosync-scheduler.ts';
+import { RunRegistry } from '../core/run-registry.ts';
+import { nullLogger } from '../utils/logger.ts';
+import type { AutosyncConfig } from './autosync-config.ts';
+import type { AutosyncHistoryEntry } from './sync-history.ts';
+import type { MergePlan, MergeSectionResult } from './merge.ts';
+import type { SyncEngine } from './sync-engine.ts';
+
+test('intervalToMs: 间隔换算正确', () => {
+  assert.equal(intervalToMs('5m'), 5 * 60 * 1000);
+  assert.equal(intervalToMs('15m'), 15 * 60 * 1000);
+  assert.equal(intervalToMs('30m'), 30 * 60 * 1000);
+  assert.equal(intervalToMs('60m'), 60 * 60 * 1000);
+  assert.equal(intervalToMs('6h'), 6 * 60 * 60 * 1000);
+  assert.equal(intervalToMs('12h'), 12 * 60 * 60 * 1000);
+  assert.equal(intervalToMs('24h'), 24 * 60 * 60 * 1000);
+});
+
+test('shouldTriggerStartupRun: 阈值判断', () => {
+  const threshold = 5 * 60 * 1000;
+  const now = 1_000_000_000_000;
+  assert.equal(shouldTriggerStartupRun(new Date(now - 60 * 1000).toISOString(), threshold, now), false);
+  assert.equal(shouldTriggerStartupRun(new Date(now - 6 * 60 * 1000).toISOString(), threshold, now), true);
+  assert.equal(shouldTriggerStartupRun(undefined, threshold, now), true);
+  assert.equal(shouldTriggerStartupRun(new Date(now - threshold).toISOString(), threshold, now), true);
+  assert.equal(shouldTriggerStartupRun(new Date(now - threshold - 1).toISOString(), threshold, now), true);
+  assert.equal(shouldTriggerStartupRun(new Date(now - threshold + 1).toISOString(), threshold, now), false);
+});
+
+/** 构造一个可控 scheduler：注入全部 fs/engine 依赖，验证 runOnce 行为。 */
+function makeScheduler(opts: {
+  cfg: AutosyncConfig;
+  engine: Partial<SyncEngine>;
+  history: AutosyncHistoryEntry[];
+}) {
+  const runs = new RunRegistry();
+  const entries: AutosyncHistoryEntry[] = [...opts.history];
+  let config = opts.cfg;
+  const scheduler = new AutoSyncScheduler({
+    syncDir: '/tmp',
+    host: { log: nullLogger() },
+    makeSyncEngine: () => opts.engine as SyncEngine,
+    msg: (k: string) => k,
+    runs,
+    now: () => new Date(1_000_000_000_000),
+    readConfig: async () => config,
+    writeConfig: async (c) => { config = c; },
+    readSyncConfigFn: async () => ({ repoUrl: 'git@github.com:foo/bar.git' }),
+    readHistoryFn: async () => ({ schemaVersion: 1, autosyncEntries: entries, updatedAt: '' }),
+    appendHistoryFn: async (e) => { entries.push(e); },
+    // 测试不用真实定时器：不调 start()
+  });
+  return { scheduler, runs, getConfig: () => config, getEntries: () => entries };
+}
+
+function mergeResult(id: string, decision: MergeSectionResult['decision']): MergeSectionResult {
+  return { id: id as never, decision, conflicts: [], merged: {} as never };
+}
+
+function makeMergePlan(ids: Array<[string, MergeSectionResult['decision']]>): MergePlan {
+  return { sections: ids.map(([id, decision]) => mergeResult(id, decision)) };
+}
+
+test('runOnce: enabled=false → skipped(disabled)，不写历史', async () => {
+  const cfg: AutosyncConfig = { enabled: false, interval: '30m', startupMinIntervalMs: 300000, consecutiveFailures: 0 };
+  const { scheduler, getConfig, getEntries } = makeScheduler({ cfg, engine: {}, history: [] });
+  const result = await scheduler.runOnce();
+  assert.equal(result.status, 'skipped');
+  assert.equal(result.skipReason, 'disabled');
+  assert.equal(getEntries().length, 0, 'disabled 不写历史');
+  assert.equal(getConfig().consecutiveFailures, 0);
+});
+
+test('runOnce: 未配置仓库 → skipped(unconfigured)，写历史但不计失败', async () => {
+  const cfg: AutosyncConfig = { enabled: true, interval: '30m', startupMinIntervalMs: 300000, consecutiveFailures: 0 };
+  const scheduler = new AutoSyncScheduler({
+    syncDir: '/tmp',
+    host: { log: nullLogger() },
+    makeSyncEngine: () => ({} as SyncEngine),
+    msg: (k: string) => k,
+    runs: new RunRegistry(),
+    now: () => new Date(1_000_000_000_000),
+    readConfig: async () => cfg,
+    writeConfig: async () => {},
+    readSyncConfigFn: async () => null,
+    readHistoryFn: async () => ({ schemaVersion: 1, autosyncEntries: [], updatedAt: '' }),
+    appendHistoryFn: async () => {},
+  });
+  const result = await scheduler.runOnce();
+  assert.equal(result.status, 'skipped');
+  assert.equal(result.skipReason, 'unconfigured');
+  assert.equal(result.consecutiveFailures, 0, '未配置不累计失败');
+});
+
+test('runOnce: merge 抛错 → failed，连续失败计数 +1', async () => {
+  const cfg: AutosyncConfig = { enabled: true, interval: '30m', startupMinIntervalMs: 300000, consecutiveFailures: 2 };
+  const engine = { merge: async () => { throw new Error('network down'); } };
+  const { scheduler, getConfig, getEntries } = makeScheduler({ cfg, engine, history: [] });
+  const result = await scheduler.runOnce();
+  assert.equal(result.status, 'failed');
+  assert.equal(result.consecutiveFailures, 3, '连续失败 2→3');
+  assert.equal(getConfig().consecutiveFailures, 3);
+  assert.ok(getEntries().some((e) => e.status === 'failed'), '写入失败历史');
+});
+
+test('runOnce: 有冲突 → skipped(conflict)，不写本地，不计失败', async () => {
+  const cfg: AutosyncConfig = { enabled: true, interval: '30m', startupMinIntervalMs: 300000, consecutiveFailures: 1 };
+  const engine = {
+    merge: async (): Promise<MergePlan> => makeMergePlan([['settings', 'conflict']]),
+  };
+  const { scheduler, getConfig, getEntries } = makeScheduler({ cfg, engine, history: [] });
+  const result = await scheduler.runOnce();
+  assert.equal(result.status, 'skipped');
+  assert.equal(result.skipReason, 'conflict');
+  assert.deepEqual(result.conflictedSections, ['settings']);
+  assert.equal(result.consecutiveFailures, 1, '冲突跳过不计失败');
+  assert.equal(getConfig().consecutiveFailures, 1);
+  assert.ok(getEntries().some((e) => e.skipReason === 'conflict'), '写入冲突跳过历史');
+});
+
+test('runOnce: 无冲突且无变化 → success(pull,unchanged)', async () => {
+  const cfg: AutosyncConfig = { enabled: true, interval: '30m', startupMinIntervalMs: 300000, consecutiveFailures: 0 };
+  const engine = {
+    merge: async (): Promise<MergePlan> => makeMergePlan([['settings', 'skip']]),
+  };
+  const { scheduler } = makeScheduler({ cfg, engine, history: [] });
+  const result = await scheduler.runOnce();
+  assert.equal(result.status, 'success');
+  assert.equal(result.direction, 'pull');
+  assert.equal(result.skipReason, 'unchanged');
+});
+
+test('runOnce: 完整双向 → 无冲突合并写本地 + push', async () => {
+  const cfg: AutosyncConfig = { enabled: true, interval: '30m', startupMinIntervalMs: 300000, consecutiveFailures: 0 };
+  const applyCalls: string[] = [];
+  const engine = {
+    merge: async (): Promise<MergePlan> => makeMergePlan([['settings', 'useRemote']]),
+    applyMergePlan: async () => { applyCalls.push('apply'); return { ok: true, applied: ['settings'], restoreId: 'r1', rolledBack: false, review: [], warnings: [] }; },
+    push: async () => ({ ok: true, snapshotId: 'snap-push', sections: ['settings'] as never, warnings: [] }),
+  };
+  const { scheduler, getEntries } = makeScheduler({ cfg, engine, history: [] });
+  const result = await scheduler.runOnce();
+  assert.equal(result.status, 'success');
+  assert.equal(result.direction, 'both');
+  assert.deepEqual(result.appliedSections, ['settings']);
+  assert.equal(result.pushedSnapshotId, 'snap-push');
+  assert.equal(applyCalls.length, 1);
+  assert.ok(getEntries().some((e) => e.status === 'success' && e.direction === 'both'), '写入双向成功历史');
+});
+
+test('runOnce: startup 变体 → 只做 pull 合并，不上传', async () => {
+  const cfg: AutosyncConfig = { enabled: true, interval: '30m', startupMinIntervalMs: 300000, consecutiveFailures: 0 };
+  const pushCalls: string[] = [];
+  const engine = {
+    merge: async (): Promise<MergePlan> => makeMergePlan([['settings', 'useRemote']]),
+    applyMergePlan: async () => ({ ok: true, applied: ['settings'], restoreId: 'r1', rolledBack: false, review: [], warnings: [] }),
+    push: async () => { pushCalls.push('push'); return { ok: true, snapshotId: 'x', sections: [] as never, warnings: [] }; },
+  };
+  const { scheduler } = makeScheduler({ cfg, engine, history: [] });
+  const result = await scheduler.runOnce({ startup: true });
+  assert.equal(result.direction, 'pull', 'startup 不上传');
+  assert.equal(pushCalls.length, 0, 'startup 变体不调用 push');
+});
+
+test('buildAutoApplyPlan: 把非 skip 非 conflict 项归入 autoApply', () => {
+  const plan = makeMergePlan([
+    ['settings', 'useRemote'],
+    ['providers', 'keepLocal'],
+    ['plugins', 'skip'],
+    ['mcp', 'conflict'],
+  ]);
+  const apply = buildAutoApplyPlan(plan);
+  assert.deepEqual(apply.autoApply.map((s) => s.id), ['settings', 'providers']);
+  assert.deepEqual(apply.review.map((s) => s.id), ['mcp']);
+  assert.deepEqual(apply.skipped.map((s) => s.id), ['plugins']);
+});