dsh-config-manager 0.1.19 → 0.1.21

package/src/index.ts

@@ -58,6 +58,7 @@ import * as yaml from 'js-yaml'
 
 import { Exporter, FileSnapshotStore, Importer } from './core/index.ts'
 import { listSnapshots, planRestore, type RestorePlan, type RestoreReport } from './core/restore.ts'
+import { rollback as performRollback } from './core/rollback.ts'
 import { RunRegistry, type RunState } from './core/run-registry.ts'
 import { makeMsg, msgOf, zhMsg } from './core/messages.ts'
 import type { MsgFunc } from './core/messages.ts'
@@ -67,7 +68,7 @@ import {
 } from './core/plugin-cli.ts'
 import type {
   ConfigAdapter, CredentialsFacade, FileSystemFacade, HostContext, ImportDecisions,
-  ImportPlan, NamespaceInfo, PatchFileFacade, PluginInfo, PluginsFacade,
+  ImportPlan, NamespaceInfo, PatchFileFacade, PlanItemKind, PluginInfo, PluginsFacade,
   SettingsFacade, WorkspaceFacade,
 } from './core/types.ts'
 import { createAdapters, USER_PATCH_FILE } from './adapters/index.ts'
@@ -76,7 +77,12 @@ import { createHardenedZipParser } from './security/zip-security.ts'
 import { GitTransport } from './sync/git/git-transport.ts'
 import { DeviceFlowStore, GitHubAuthClient } from './sync/github-auth.ts'
 import { SyncEngine } from './sync/sync-engine.ts'
-import { loadSyncState } from './sync/sync-state.ts'
+import { SyncSessionStore } from './sync/sync-session.ts'
+import { AutoSyncScheduler } from './sync/autosync-scheduler.ts'
+import { defaultAutosyncConfig, readAutosyncConfig, writeAutosyncConfig } from './sync/autosync-config.ts'
+import type { AutosyncInterval, AutosyncRunStatus } from './sync/autosync-config.ts'
+import { appendAutosyncEntry, readSyncHistory } from './sync/sync-history.ts'
+import { loadSyncState, saveSyncState } from './sync/sync-state.ts'
 import { readSyncConfig, writeSyncConfig, validateRepoUrl } from './sync/sync-config.ts'
 import { MANIFEST_FILE, parseManifest } from './schema/manifest.ts'
 import { SECTION_IDS } from './schema/config.ts'
@@ -94,7 +100,7 @@ export const name = 'config-manager'
 export const inject = ['settings', 'credentials']
 
 /** Plugin version, kept in sync with package.json ("version"). */
-const PLUGIN_VERSION = '0.1.19'
+const PLUGIN_VERSION = '0.1.20'
 
 /**
  * 内置 GitHub OAuth App 的 client_id（「使用 GitHub 登录」device flow 缺省值）。
@@ -148,6 +154,15 @@ const API = {
   syncGithubStart: '/api/dsh-config-manager/sync/github/start',
   syncGithubPoll: '/api/dsh-config-manager/sync/github/poll',
   syncGithubCancel: '/api/dsh-config-manager/sync/github/cancel',
+  // P2：同步历史 / 自动应用 / 一键回滚
+  syncHistory: '/api/dsh-config-manager/sync/history',
+  syncRollback: '/api/dsh-config-manager/sync/rollback',
+  // m-sync-v2：一键同步（差异确认会话）+ 自动同步 + 历史快照
+  syncSnapshotsList: '/api/dsh-config-manager/sync/snapshots-list',
+  syncSync: '/api/dsh-config-manager/sync/sync',
+  syncApplyItems: '/api/dsh-config-manager/sync/apply-items',
+  syncCancel: '/api/dsh-config-manager/sync/cancel',
+  syncAutosync: '/api/dsh-config-manager/sync/autosync',
 } as const
 
 /**
@@ -822,6 +837,88 @@ export function writeSyncRouteError(res: ServerResponse, error: unknown): void {
   writeJson(res, 500, { error: message })
 }
 
+/** 需要人工决策的 PlanItemKind（一键同步 needsReview 判定 + 逐项确认标记） */
+const REVIEW_KINDS: ReadonlySet<PlanItemKind> = new Set([
+  'Conflict', 'MissingSecret', 'MissingDependency', 'Install', 'Error', 'PathMapping',
+])
+
+/** 一键同步差异项（client 逐项确认的最小契约；与 sync-api.ts SyncConfirmItem 对齐） */
+interface SyncConfirmItem {
+  itemId: string
+  adapter: SectionId
+  kind: PlanItemKind
+  description: string
+  severity: 'info' | 'warning' | 'error'
+  defaultAdopt: boolean
+  adopt: boolean
+  conflict?: { path: string; kind: 'key' | 'file' | 'section'; local?: unknown; remote?: unknown; ancestor?: unknown; diff?: string }
+  target?: { adapter: SectionId; ref: string }
+}
+
+/** 把 ImportPlan 投影为逐项可确认的差异项（默认采用 Create/Update/Install；人工项默认不采用）。 */
+function planToConfirmItems(plan: ImportPlan): SyncConfirmItem[] {
+  return plan.items.map((item) => {
+    const manual = REVIEW_KINDS.has(item.kind)
+    let conflict: SyncConfirmItem['conflict']
+    if (item.kind === 'Conflict') {
+      const c = (item as { conflict?: { path?: string; kind?: string; local?: unknown; remote?: unknown; ancestor?: unknown } }).conflict
+      conflict = {
+        path: c?.path ?? '$',
+        kind: c?.kind === 'file' ? 'file' : c?.kind === 'section' ? 'section' : 'key',
+        ...(c?.local !== undefined ? { local: c.local } : {}),
+        ...(c?.remote !== undefined ? { remote: c.remote } : {}),
+        ...(c?.ancestor !== undefined ? { ancestor: c.ancestor } : {}),
+      }
+    }
+    return {
+      itemId: item.id,
+      adapter: item.adapter,
+      kind: item.kind,
+      description: item.description,
+      severity: item.severity,
+      defaultAdopt: !manual,
+      adopt: !manual,
+      ...(conflict !== undefined ? { conflict } : {}),
+      ...(item.target !== undefined ? { target: item.target } : {}),
+    }
+  })
+}
+
+/** autosync interval 类型守卫 */
+function isAutosyncInterval(v: unknown): v is AutosyncInterval {
+  return v === '5m' || v === '15m' || v === '30m' || v === '60m' || v === '6h' || v === '12h' || v === '24h'
+}
+
+/** 自动同步状态响应（GET /sync/autosync 与 POST 回填；读盘计算 elapsedMs）。 */
+async function buildAutosyncStatus(dir: string): Promise<AutosyncStatusResponse> {
+  const cfg = await readAutosyncConfig(dir)
+  const elapsedMs = cfg.lastRunAt === undefined || cfg.lastRunAt === ''
+    ? -1
+    : Math.max(0, Date.now() - Date.parse(cfg.lastRunAt))
+  return {
+    enabled: cfg.enabled,
+    interval: cfg.interval,
+    ...(cfg.lastRunAt !== undefined ? { lastRunAt: cfg.lastRunAt } : {}),
+    ...(cfg.lastRunStatus !== undefined ? { lastRunStatus: cfg.lastRunStatus } : {}),
+    ...(cfg.lastRunMessage !== undefined ? { lastRunMessage: cfg.lastRunMessage } : {}),
+    consecutiveFailures: cfg.consecutiveFailures,
+    elapsedMs,
+    ...(cfg.lastRunHistoryId !== undefined ? { lastRunHistoryId: cfg.lastRunHistoryId } : {}),
+  }
+}
+
+/** GET /sync/autosync 响应类型（与 sync-api.ts AutosyncStatusResponse 对齐） */
+interface AutosyncStatusResponse {
+  enabled: boolean
+  interval: AutosyncInterval
+  lastRunAt?: string
+  lastRunStatus?: AutosyncRunStatus
+  lastRunMessage?: string
+  consecutiveFailures: number
+  elapsedMs: number
+  lastRunHistoryId?: string
+}
+
 /* -------------------------------------------------- restore 路由（M4） */
 
 /** POST /restore 请求体校验（纯函数；snapshotId 拒绝路径分隔符防 join 越界）。 */
@@ -1043,6 +1140,21 @@ function makeRoutes(deps: RoutesDeps): WebRoute[] {
     });
   }
 
+  /** 一键同步差异确认会话存储（进程内存；/sync/sync 预览 → /sync/apply-items 逐项执行解耦） */
+  const syncSessions = new SyncSessionStore()
+
+  /** 自动同步后台调度器（宿主进程生命周期，不依赖浏览器） */
+  let scheduler: AutoSyncScheduler | undefined
+  scheduler = new AutoSyncScheduler({
+    syncDir,
+    host,
+    makeSyncEngine,
+    msg,
+    runs,
+  })
+  // 启动：读 autosync-config；若 enabled 启动定时器；无条件执行一次「启动触发下载合并」（受阈值约束）
+  scheduler.start()
+
   return [
     // ------------------------------------------------------------- status
     {
@@ -1401,6 +1513,7 @@ function makeRoutes(deps: RoutesDeps): WebRoute[] {
             lastSyncAt: state.lastSyncAt === '' ? undefined : state.lastSyncAt,
             sectionCount: Object.keys(state.sections).length,
             transport: state.transport,
+            autosync: await buildAutosyncStatus(syncDir),
           })
         } catch (error) {
           writeJson(res, 500, { error: error instanceof Error ? error.message : String(error) })
@@ -1574,6 +1687,310 @@ function makeRoutes(deps: RoutesDeps): WebRoute[] {
         writeJson(res, 200, { ok: true })
       },
     },
+    // ------------------------------------------------------ sync/history
+    // P2：列出本地祖先快照目录的 manifest.json（id/createdAt/sectionHashes），
+    // 同时统计 review-queue 中关联到该 snapshotId 的项数。
+    {
+      kind: 'exact',
+      path: API.syncHistory,
+      handler: async (req, res) => {
+        if (!guard(req, res, 'GET')) return
+        try {
+          const localDir = join(syncDir, 'snapshots')
+          const entries = await fs.readdir(localDir).catch(() => [])
+          const rows: Array<{ id: string; createdAt: string; sectionCount: number; reviewCount: number }> = []
+          for (const name of entries) {
+            const dir = join(localDir, name)
+            const stat = await fs.stat(dir).catch(() => null)
+            if (!stat?.isDirectory()) continue
+            const manifestPath = join(dir, 'manifest.json')
+            const raw = await fs.readFile(manifestPath, 'utf8').catch(() => null)
+            if (raw === null) continue
+            try {
+              const m = JSON.parse(raw) as { id?: unknown; createdAt?: unknown; sectionHashes?: unknown }
+              if (typeof m.id !== 'string' || typeof m.createdAt !== 'string') continue
+              const sectionCount = m.sectionHashes && typeof m.sectionHashes === 'object'
+                ? Object.keys(m.sectionHashes as Record<string, unknown>).length
+                : 0
+              rows.push({ id: m.id, createdAt: m.createdAt, sectionCount, reviewCount: 0 })
+            } catch { /* skip malformed */ }
+          }
+          // 关联 review-queue 计数
+          const rqPath = join(syncDir, 'sync-review-queue.json')
+          const rqRaw = await fs.readFile(rqPath, 'utf8').catch(() => null)
+          if (rqRaw !== null) {
+            try {
+              const rq = JSON.parse(rqRaw) as { items?: Array<{ snapshotId?: string }> }
+              const byId = new Map<string, number>()
+              for (const it of rq.items ?? []) {
+                if (typeof it.snapshotId === 'string') {
+                  byId.set(it.snapshotId, (byId.get(it.snapshotId) ?? 0) + 1)
+                }
+              }
+              for (const r of rows) {
+                const c = byId.get(r.id)
+                if (c !== undefined) r.reviewCount = c
+              }
+            } catch { /* skip */ }
+          }
+          rows.sort((a, b) => (a.createdAt < b.createdAt ? 1 : a.createdAt > b.createdAt ? -1 : 0))
+          // 合并自动同步执行记录（sync-history.json）
+          const hist = await readSyncHistory(syncDir)
+          const merged = [
+            ...rows.map((r) => ({ ...r, kind: 'apply' as const })),
+            ...hist.autosyncEntries.map((e) => ({
+              id: e.createdAt,
+              createdAt: e.createdAt,
+              kind: 'autosync' as const,
+              autosync: e,
+            })),
+          ].sort((a, b) => (a.createdAt < b.createdAt ? 1 : a.createdAt > b.createdAt ? -1 : 0))
+          writeJson(res, 200, { entries: merged })
+        } catch (error) {
+          writeJson(res, 500, { error: error instanceof Error ? error.message : String(error) })
+        }
+      },
+    },
+    // ------------------------------------------------------ sync/snapshots-list
+    // m-sync-v2：远端历史快照列表（供「选择历史快照」下拉）。
+    {
+      kind: 'exact',
+      path: API.syncSnapshotsList,
+      handler: async (req, res) => {
+        if (!guard(req, res, 'POST')) return
+        const body = await readJsonBody(req)
+        if (body === undefined) {
+          writeJson(res, 400, { error: 'invalid JSON body' })
+          return
+        }
+        try {
+          const { repoUrl, gitBin } = await prepareSync(body)
+          const engine = makeSyncEngine(repoUrl, gitBin)
+          const metas = await withTimeout(
+            engine.listSnapshots(),
+            ROUTE_TIMEOUT_MS,
+            msg('host.syncPullTimeout'),
+          )
+          const snapshots = [...metas]
+            .sort((a, b) => (a.createdAt < b.createdAt ? 1 : a.createdAt > b.createdAt ? -1 : 0))
+            .map((m) => ({
+              id: m.id,
+              createdAt: m.createdAt,
+              sectionCount: m.manifest.sectionIds.length,
+              platform: m.manifest.platform,
+              dshVersion: m.manifest.dshVersion,
+            }))
+          const state = await loadSyncState(syncDir)
+          writeJson(res, 200, { ok: true, snapshots, currentSnapshotId: state.lastSnapshotId === '' ? undefined : state.lastSnapshotId })
+        } catch (error) {
+          writeSyncRouteError(res, error)
+        }
+      },
+    },
+    // ------------------------------------------------------ sync/sync
+    // m-sync-v2：一键同步第一步 —— 拉取 → 差异确认会话（内存登记临时 ZIP + ImportPlan）。
+    {
+      kind: 'exact',
+      path: API.syncSync,
+      handler: async (req, res) => {
+        if (!guard(req, res, 'POST')) return
+        const body = await readJsonBody(req)
+        if (body === undefined) {
+          writeJson(res, 400, { error: 'invalid JSON body' })
+          return
+        }
+        try {
+          const { repoUrl, gitBin } = await prepareSync(body)
+          const engine = makeSyncEngine(repoUrl, gitBin)
+          const snapshotId = typeof body['snapshotId'] === 'string' && body['snapshotId'] !== '' ? body['snapshotId'] : undefined
+          const preview = await withTimeout(
+            engine.preview(snapshotId === undefined ? {} : { snapshotId }),
+            ROUTE_TIMEOUT_MS,
+            msg('host.syncPullTimeout'),
+          )
+          if (!preview.ok || preview.plan === null || preview.analysis === null) {
+            writeJson(res, 200, { ok: false, syncSessionId: '', snapshotId: preview.snapshotId, items: [], needsReview: false, compatibility: 'unsupported', message: preview.message ?? '同步预览失败' })
+            return
+          }
+          const syncSessionId = syncSessions.set({
+            zipPath: preview.zipPath,
+            plan: preview.plan,
+            analysis: preview.analysis,
+            snapshotId: preview.snapshotId,
+            repoUrl,
+            gitBin,
+          })
+          const items = planToConfirmItems(preview.plan)
+          const needsReview = items.some((i) => REVIEW_KINDS.has(i.kind)) || preview.analysis.pathIssues.length > 0
+          writeJson(res, 200, {
+            ok: true,
+            syncSessionId,
+            snapshotId: preview.snapshotId,
+            items,
+            needsReview,
+            compatibility: preview.analysis.compatibility,
+          })
+        } catch (error) {
+          writeSyncRouteError(res, error)
+        }
+      },
+    },
+    // ------------------------------------------------------ sync/apply-items
+    // m-sync-v2：一键同步第二步 —— 按用户对差异项的逐项决策执行导入。
+    {
+      kind: 'exact',
+      path: API.syncApplyItems,
+      handler: async (req, res) => {
+        if (!guard(req, res, 'POST')) return
+        const body = await readJsonBody(req)
+        if (body === undefined) {
+          writeJson(res, 400, { error: 'invalid JSON body' })
+          return
+        }
+        try {
+          const syncSessionId = typeof body['syncSessionId'] === 'string' ? body['syncSessionId'] : ''
+          const session = syncSessions.get(syncSessionId)
+          if (session === undefined) {
+            writeJson(res, 400, { error: '同步会话不存在或已过期，请重新拉取预览' })
+            return
+          }
+          const adoptions = Array.isArray(body['adoptions']) ? body['adoptions'] : []
+          // 构造子计划（仅含采纳项）
+          const byId = new Map<string, { adopt: boolean; resolution?: string }>()
+          for (const a of adoptions as Array<Record<string, unknown>>) {
+            if (typeof a?.['itemId'] !== 'string') continue
+            byId.set(a['itemId'], { adopt: a['adopt'] === true, resolution: typeof a['resolution'] === 'string' ? a['resolution'] : undefined })
+          }
+          const subItems = session.plan.items.filter((item) => {
+            const d = byId.get(item.id)
+            if (d === undefined || !d.adopt) return false
+            // Conflict 项必须有 resolution，且 keepLocal/skip 从子计划剔除
+            if (item.kind === 'Conflict') {
+              if (d.resolution === undefined) throw new SyncRouteError(`冲突项 ${item.id} 必须提供 resolution（useRemote/keepLocal/skip）`)
+              if (d.resolution === 'keepLocal' || d.resolution === 'skip') return false
+            }
+            return true
+          })
+          const subPlan: ImportPlan = {
+            ...session.plan,
+            items: subItems,
+          }
+          // 消费会话（同一 session 只允许一次 apply-items）
+          syncSessions.delete(syncSessionId)
+          await fs.rm(dirname(session.zipPath), { recursive: true, force: true }).catch(() => { /* 尽力清理临时 ZIP */ })
+          const engine = makeSyncEngine(session.repoUrl, session.gitBin)
+          const report = await engine.applyItems(session.zipPath, subPlan, {
+            onItem: (info) => { /* 进度可选：runs 已由 applyItems 内部处理 */ },
+          })
+          writeJson(res, 200, {
+            ok: report.ok,
+            applied: report.applied,
+            skipped: subItems.map((i) => i.id),
+            needsRestart: report.needsRestart === true,
+            warnings: report.warnings,
+            restoreId: report.restoreId,
+            rolledBack: report.rolledBack,
+            failed: report.failed,
+            result: report.result,
+          })
+        } catch (error) {
+          writeSyncRouteError(res, error)
+        }
+      },
+    },
+    // ------------------------------------------------------ sync/cancel
+    // m-sync-v2：取消 / 清理差异确认会话（丢弃临时 ZIP，零副作用）。
+    {
+      kind: 'exact',
+      path: API.syncCancel,
+      handler: async (req, res) => {
+        if (!guard(req, res, 'POST')) return
+        const body = await readJsonBody(req)
+        if (body === undefined) {
+          writeJson(res, 400, { error: 'invalid JSON body' })
+          return
+        }
+        try {
+          const syncSessionId = typeof body['syncSessionId'] === 'string' ? body['syncSessionId'] : ''
+          if (syncSessionId !== '') {
+            const session = syncSessions.get(syncSessionId)
+            if (session !== undefined) {
+              await fs.rm(dirname(session.zipPath), { recursive: true, force: true }).catch(() => { /* 尽力清理临时 ZIP */ })
+            }
+            syncSessions.delete(syncSessionId)
+          }
+          writeJson(res, 200, { ok: true })
+        } catch (error) {
+          writeSyncRouteError(res, error)
+        }
+      },
+    },
+    // ------------------------------------------------------ sync/autosync
+    // m-sync-v2：自动同步配置读写（总开关 + 间隔 + 启动阈值 + 状态）。
+    {
+      kind: 'exact',
+      path: API.syncAutosync,
+      handler: async (req, res) => {
+        if (!guard(req, res, 'GET')) return
+        try {
+          writeJson(res, 200, await buildAutosyncStatus(syncDir))
+        } catch (error) {
+          writeSyncRouteError(res, error)
+        }
+      },
+    },
+    {
+      kind: 'exact',
+      path: API.syncAutosync,
+      handler: async (req, res) => {
+        if (!guard(req, res, 'POST')) return
+        const body = await readJsonBody(req)
+        if (body === undefined) {
+          writeJson(res, 400, { error: 'invalid JSON body' })
+          return
+        }
+        try {
+          const cfg = await readAutosyncConfig(syncDir)
+          if (typeof body['enabled'] === 'boolean') cfg.enabled = body['enabled']
+          if (typeof body['interval'] === 'string' && isAutosyncInterval(body['interval'])) cfg.interval = body['interval']
+          if (typeof body['startupMinIntervalMs'] === 'number' && Number.isFinite(body['startupMinIntervalMs']) && body['startupMinIntervalMs'] > 0) {
+            cfg.startupMinIntervalMs = body['startupMinIntervalMs']
+          }
+          await writeAutosyncConfig(syncDir, cfg)
+          if (scheduler) scheduler.reload().catch(() => { /* 尽力而为 */ })
+          writeJson(res, 200, await buildAutosyncStatus(syncDir))
+        } catch (error) {
+          writeSyncRouteError(res, error)
+        }
+      },
+    },
+    // ------------------------------------------------------ sync/rollback
+    // P2：UI 一键回滚入口（按 apply 返回的 restoreId 调用 backup→rollback）。
+    {
+      kind: 'exact',
+      path: API.syncRollback,
+      handler: async (req, res) => {
+        if (!guard(req, res, 'POST')) return
+        const body = await readJsonBody(req)
+        if (body === undefined) {
+          writeJson(res, 400, { error: 'invalid JSON body' })
+          return
+        }
+        try {
+          const restoreId = typeof body['restoreId'] === 'string' ? body['restoreId'] : ''
+          if (restoreId === '') {
+            writeJson(res, 400, { error: 'restoreId required' })
+            return
+          }
+          const store = new FileSnapshotStore({ dir: join(syncDir, 'snapshots') })
+          const snap = await store.load(restoreId)
+          const report = await performRollback({ ctx: host, snapshot: snap, store, adapters })
+          writeJson(res, 200, { ok: true, full: report.full })
+        } catch (error) {
+          writeJson(res, 500, { error: error instanceof Error ? error.message : String(error) })
+        }
+      },
+    },
   ]
 }
 

package/src/sync/ancestor.test.ts

@@ -0,0 +1,152 @@
+/**
+ * m-sync-flow：ancestor 存储助手测试。
+ * - loadAncestor: 存在返回 SyncSnapshot；不存在抛错
+ * - writeAncestor: 写出目录能被 readSnapshotFromDir 完整读回，分区 hash 一致
+ * - pruneAncestors: 仅删超出 keep 的最旧副本；保留集合完整无损
+ */
+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 { loadAncestor, pruneAncestors, writeAncestor, DEFAULT_ANCESTOR_KEEP } from './ancestor.ts';
+import { hashSection, loadSyncState, saveSyncState } from './sync-state.ts';
+import type { SectionData, FilesSection } from '../schema/types.ts';
+import type { SyncSnapshot } from './transport.ts';
+
+function mkSnapshot(id: string, createdAt: string, sections: SyncSnapshot['sections']): SyncSnapshot {
+  return {
+    id,
+    createdAt,
+    manifest: {
+      schemaVersion: 1,
+      dshVersion: 'test',
+      platform: 'linux',
+      sectionIds: Object.keys(sections) as SyncSnapshot['manifest']['sectionIds'],
+      containsSecrets: false,
+    },
+    sections,
+  };
+}
+
+test('loadAncestor: 存在 → 返回 SyncSnapshot（与 writeAncestor 写入一致）', async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-ancestor-load-'));
+  try {
+    const snap = mkSnapshot('sync-1', '2026-08-16T10:00:00.000Z', {
+      settings: { version: 1, namespaces: { general: { value: { theme: 'dark' }, revision: 1, secrets: [] } } } as SectionData,
+    });
+    await writeAncestor(dir, snap);
+    const loaded = await loadAncestor(dir, 'sync-1');
+    assert.equal(loaded.id, 'sync-1');
+    assert.equal(loaded.createdAt, '2026-08-16T10:00:00.000Z');
+    assert.equal(loaded.sections.settings && hashSection(loaded.sections.settings as SectionData), hashSection(snap.sections.settings as SectionData));
+  } finally {
+    await fs.rm(dir, { recursive: true, force: true });
+  }
+});
+
+test('loadAncestor: 不存在 → 抛错（不静默降级）', async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-ancestor-missing-'));
+  try {
+    await assert.rejects(() => loadAncestor(dir, 'sync-nonexistent'));
+    await assert.rejects(() => loadAncestor(dir, ''), /snapshotId/);
+  } finally {
+    await fs.rm(dir, { recursive: true, force: true });
+  }
+});
+
+test('writeAncestor: 写出目录可被 readSnapshotFromDir 读回，分区 hash 一致', async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-ancestor-write-'));
+  try {
+    const files: FilesSection = {
+      version: 1,
+      files: [
+        { relativePath: 'a.md', data: new TextEncoder().encode('# A\n'), contentHash: '' },
+        { relativePath: 'b/skill.md', data: new TextEncoder().encode('# B\n'), contentHash: '' },
+      ],
+    };
+    const snap = mkSnapshot('sync-2', '2026-08-16T11:00:00.000Z', { skills: files as unknown as SectionData });
+    await writeAncestor(dir, snap);
+    const loaded = await loadAncestor(dir, 'sync-2');
+    assert.equal(hashSection(loaded.sections.skills as SectionData), hashSection(files as unknown as SectionData));
+    assert.equal((loaded.sections.skills as FilesSection).files.length, 2);
+  } finally {
+    await fs.rm(dir, { recursive: true, force: true });
+  }
+});
+
+test('pruneAncestors: 仅删超出 keep 的最旧副本；保留集合完整无损', async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-ancestor-prune-'));
+  try {
+    for (let i = 0; i < 12; i++) {
+      const t = `2026-08-16T10:0${i % 10}:00.000Z`.replace('10:00', `10:${String(i).padStart(2, '0')}`);
+      const iso = i < 10
+        ? `2026-08-16T10:0${i}:00.000Z`
+        : `2026-08-16T10:${i}:00.000Z`;
+      const snap = mkSnapshot(`sync-${String(i).padStart(2, '0')}`, iso, {
+        settings: { version: 1, namespaces: {} } as SectionData,
+      });
+      await writeAncestor(dir, snap);
+    }
+    const removed = await pruneAncestors(dir, 10);
+    assert.equal(removed.length, 2, '12 - 10 = 2 个最旧被删');
+    assert.equal(removed[0], 'sync-00');
+    assert.equal(removed[1], 'sync-01');
+    // 剩余 10 个仍在
+    for (let i = 2; i < 12; i++) {
+      const loaded = await loadAncestor(dir, `sync-${String(i).padStart(2, '0')}`);
+      assert.equal(loaded.id, `sync-${String(i).padStart(2, '0')}`);
+    }
+    await assert.rejects(() => loadAncestor(dir, 'sync-00'));
+    await assert.rejects(() => loadAncestor(dir, 'sync-01'));
+  } finally {
+    await fs.rm(dir, { recursive: true, force: true });
+  }
+});
+
+test('pruneAncestors: keep<=0 视为保留全部', async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-ancestor-prune0-'));
+  try {
+    for (let i = 0; i < 3; i++) {
+      const snap = mkSnapshot(`s-${i}`, `2026-08-16T10:0${i}:00.000Z`, {
+        settings: { version: 1, namespaces: {} } as SectionData,
+      });
+      await writeAncestor(dir, snap);
+    }
+    const removed = await pruneAncestors(dir, 0);
+    assert.equal(removed.length, 0);
+    for (let i = 0; i < 3; i++) {
+      const loaded = await loadAncestor(dir, `s-${i}`);
+      assert.equal(loaded.id, `s-${i}`);
+    }
+  } finally {
+    await fs.rm(dir, { recursive: true, force: true });
+  }
+});
+
+test('DEFAULT_ANCESTOR_KEEP 默认值符合规划（10）', () => {
+  assert.equal(DEFAULT_ANCESTOR_KEEP, 10);
+});
+
+// 同时验证 sync-state 在 v2 下 lastSnapshotId 可被 save/load 完整往返（与 M1 互补）
+test('saveSyncState + loadSyncState: 写入 v2 含 lastSnapshotId 往返完整（与 M1 互补验证）', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-sync-state-ancestor-rt-'));
+  try {
+    await saveSyncState(tmp, {
+      schemaVersion: 2,
+      lastSyncAt: '2026-08-16T12:00:00.000Z',
+      sections: {},
+      lastSnapshotId: 'sync-1',
+    });
+    const s = await loadSyncState(tmp);
+    assert.equal(s.lastSnapshotId, 'sync-1');
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});
+
+// 抑制 unused import 警告（hashSection/saveSyncState 通过 M1 测试已用到，此处仅 import 即可）
+void hashSection;
+void saveSyncState;
+void path;