dsh-config-manager 0.1.78 → 0.1.80

package/src/sync/git/git-transport.ts

@@ -35,7 +35,7 @@ import {
   SyncTransportError, withSyncRetry,
 } from '../transport.ts';
 import type {
-  SyncRetryOptions, SyncSnapshot, SyncSnapshotMeta, SyncTransport, SyncTransportErrorOptions,
+  SyncProbeResult, SyncRetryOptions, SyncSnapshot, SyncSnapshotMeta, SyncTransport, SyncTransportErrorOptions,
 } from '../transport.ts';
 import { parseJsonSafe } from '../../utils/json.ts';
 import { atomicWriteFile } from '../../utils/atomic-write.ts';
@@ -77,6 +77,14 @@ export interface GitWorkDirFacts {
   ahead: number | null;
   /** 工作树是否有未提交改动（读不出 → null） */
   dirty: boolean | null;
+  /**
+   * 远端跟踪分支上的快照数（issue #104 建议 3）：`snapshots/` 与 `snapshots-encrypted/`
+   * 下的直接子项数（目录，或加密通道的 <id>.json 文件）。它和 `ahead` 一起回答
+   * 「本地领先 N 个提交、可远端从来没收到过快照吗」—— 那正是 issue #104 里
+   * 远端两周一个字节都没收到、用户却以为在正常备份的现场。
+   * 只有 detail 自检时给出；无远端跟踪分支 / 读不出 → null。
+   */
+  remoteSnapshots: number | null;
 }
 
 /** 凭据提供者：token 只从这里读取，绝不在任何地方持久化 */
@@ -130,6 +138,11 @@ const SNAPSHOTS_ENCRYPTED_REL = 'snapshots-encrypted';
  * 内容没变 = 文件路径已存在 = 一个字都不写、也不进本次 diff。
  */
 const BLOBS_REL = 'blobs';
+/**
+ * 同步仓库（git 通道）顶层**只可能出现**这三个条目。issue #104 的 `adopt` 模式拿它当安全判据：
+ * 远端分支的顶层出现别的名字 = 这不是本插件的同步仓库，合并它等于把别人的仓库内容搬进工作副本。
+ */
+const ADOPT_ROOT_ALLOW = new Set<string>([SNAPSHOTS_REL, SNAPSHOTS_ENCRYPTED_REL, BLOBS_REL]);
 const DEFAULT_AUTHOR: GitAuthor = { name: 'DSH Config Sync', email: 'sync@dsh.local' };
 const DEFAULT_CREDENTIAL_USERNAME = 'oauth2';
 /** 快照 id 安全字符集：字母数字开头，仅 . _ -；防路径穿越与 commit message 注入 */
@@ -410,6 +423,20 @@ export class GitTransport implements SyncTransport {
     throw new GitTransportError(this.msg('sync.git.repoUnreachable', { url: this.mask(this.o.repoUrl, null) }));
   }
 
+  /**
+   * 连通性探针（cloud-sync 借鉴项 ②）：只读自检「远端可达 + 凭据可用」。
+   *
+   * 为什么复用 ls-remote：它不需要工作副本、不写任何本地状态，而且正是 clone/fetch 之前的那一步 ——
+   * 远端不可达 / 令牌失效 / SSH 主机密钥不信任都会在这里显式失败（checkIsPrivate 抛可操作文案），
+   * 因此结论与随后真正同步时的成败**同源**。
+   * 刻意**不**统计远端快照数：那要先 fetch 工作副本（对本地有写入），超出「只读自检」的范围 ——
+   * 宁可不报，也不报一个会误导的 0。
+   */
+  async probe(): Promise<SyncProbeResult> {
+    await this.checkIsPrivate();
+    return { message: this.msg('sync.git.probeOk') };
+  }
+
   /* ---------------- 内部实现 ---------------- */
 
   private async ensureRepo(): Promise<void> {
@@ -501,7 +528,7 @@ export class GitTransport implements SyncTransport {
   async inspectWorkDir(opts: { detail?: boolean } = {}): Promise<GitWorkDirFacts> {
     const fsx = createSnapshotFs();
     if (!(await fsx.exists(path.join(this.o.workDir, '.git')))) {
-      return { path: this.o.workDir, exists: false, origin: null, pushUrl: null, match: false, ahead: null, dirty: null };
+      return { path: this.o.workDir, exists: false, origin: null, pushUrl: null, match: false, ahead: null, dirty: null, remoteSnapshots: null };
     }
     const originRes = await this.runGit(['remote', 'get-url', 'origin'], { allowNonZero: true });
     const origin = originRes.code === 0 ? originRes.stdout.trim() : '';
@@ -509,6 +536,7 @@ export class GitTransport implements SyncTransport {
     const pushRaw = pushRes.code === 0 ? pushRes.stdout.trim() : '';
     let ahead: number | null = null;
     let dirty: boolean | null = null;
+    let remoteSnapshots: number | null = null;
     if (opts.detail === true) {
       // 未上行的本地提交：HEAD 可达、但任何远端跟踪引用都不可达的提交数（无 upstream 也能算）
       const aheadRes = await this.runGit(['rev-list', '--count', 'HEAD', '--not', '--remotes'], { allowNonZero: true });
@@ -516,6 +544,27 @@ export class GitTransport implements SyncTransport {
       ahead = Number.isFinite(parsed) ? parsed : null;
       const statusRes = await this.runGit(['status', '--porcelain'], { allowNonZero: true });
       dirty = statusRes.code === 0 ? statusRes.stdout.trim() !== '' : null;
+      // issue #104 建议 3：远端分支上到底有几个快照。只读 refs/remotes/origin/<branch>
+      // （上次 fetch / push 的结果），不发网络请求 —— 两条本地只读命令。
+      // 注意不能写 `ls-tree origin/<branch> -- snapshots`：带 pathspec 时它只回显目录条目
+      // 本身（`snapshots`），数出来永远是 1。必须用 `<ref>:<dir>` 取该树的直接子项。
+      const branchRes = await this.runGit(['rev-parse', '--abbrev-ref', 'HEAD'], { allowNonZero: true });
+      const branch = branchRes.code === 0 ? branchRes.stdout.trim() : '';
+      if (branch !== '' && branch !== 'HEAD') {
+        const countTree = async (treeish: string): Promise<number | null> => {
+          const treeRes = await this.runGit(['ls-tree', '--name-only', treeish], { allowNonZero: true });
+          if (treeRes.code !== 0) return null;
+          return treeRes.stdout
+            .split('\n')
+            .map((line) => line.trim())
+            // 每个快照是一级子项；`.gitkeep` 只是占位，不是快照
+            .filter((line) => line !== '' && !line.endsWith(SNAPSHOT_KEEP_FILE)).length;
+        };
+        const plain = await countTree(`origin/${branch}:${SNAPSHOTS_REL}`);
+        const encrypted = await countTree(`origin/${branch}:${SNAPSHOTS_ENCRYPTED_REL}`);
+        // 两个目录都不存在 = 远端分支根本没有快照布局（0）；分支/引用读不出 = null（不猜）
+        remoteSnapshots = plain === null && encrypted === null ? 0 : (plain ?? 0) + (encrypted ?? 0);
+      }
     }
     return {
       path: this.o.workDir,
@@ -526,18 +575,21 @@ export class GitTransport implements SyncTransport {
       match: origin === this.o.repoUrl && (pushRaw === '' || pushRaw === this.o.repoUrl),
       ahead,
       dirty,
+      remoteSnapshots,
     };
   }
 
   /**
-   * 重建工作副本（issue #79 的自救入口）：
+   * 重建工作副本（issue #79 / #104 的自救入口）：
    *  - `relink`：只把 origin / push URL 重新指向 repoUrl（**非破坏性**：不碰工作树与本地提交）；
+   *  - `adopt`：把远端分支**合并进**现有工作副本（issue #104：换成另一个仓库、或远端历史被重写后，
+   *    两条历史不相交，`pull --ff-only` 永远失败；这里合并后本地提交一条都不丢，可 revert）；
    *  - `reclone`：删除工作副本目录后重新 clone（**丢弃未上行的本地提交**；调用方必须先让用户确认）。
    *
    * 安全边界：`reclone` 只在目录**确实是 git 工作副本**（有 .git）时才删；目录非空且无 .git
    * 一律拒绝（与 ensureRepo 同一句 workDirNotRepo）—— 绝不删来路不明的目录。
    */
-  async rebuildWorkDir(mode: 'relink' | 'reclone'): Promise<void> {
+  async rebuildWorkDir(mode: 'relink' | 'adopt' | 'reclone'): Promise<void> {
     this.repoReady = false;
     if (mode === 'relink') {
       await this.ensureRepo(); // .git 存在 → reconcileOrigin
@@ -556,10 +608,121 @@ export class GitTransport implements SyncTransport {
       await this.ensureRepo(); // 空目录 → 直接 clone
       return;
     }
+    if (mode === 'adopt') {
+      // 已有工作副本但历史与远端不相交：合并远端历史，不删任何本地提交
+      await this.adoptRemoteHistory();
+      return;
+    }
     await fs.rm(this.o.workDir, { recursive: true, force: true });
     await this.ensureRepo();
   }
 
+  /**
+   * 采纳远端历史（issue #104）：把远端分支合并进现有工作副本，解开「换了仓库 / 远端历史被重写」
+   * 之后 `pull --ff-only` 的死结（真机形态：`+ 8e87c0c...dc69fc7 main (forced update)` 后
+   * `fatal: Not possible to fast-forward, aborting.`）。
+   *
+   * 为什么 merge 而不是 issue 里建议的 `rebase --root --onto`：
+   *  - rebase 会**改写本地提交**（sha 全变），出问题时无法 revert，中途失败还留下 detached HEAD
+   *    与 .git/rebase-merge 目录，状态比失败前更难收拾；
+   *  - merge 只多一个 merge commit，`git revert -m 1` 可原路退回，冲突时 `merge --abort`
+   *    能干净回到起点（真机裸仓验证：冲突 abort 后无 MERGE_HEAD、工作树零改动）。
+   *
+   * 三条安全边界（宁可不做，也不把别人的仓库合进来）：
+   *  ① 工作树必须干净 —— 有未提交改动时合并会把用户改动卡在冲突里；
+   *  ② 远端分支顶层只允许快照布局（snapshots / snapshots-encrypted / blobs）—— 否则这是个
+   *     「另有用途的仓库」，合并等于把它整个搬进工作副本；
+   *  ③ 远端必须存在同名分支 —— 远端是空仓库（没有任何分支）时视为没什么可采纳，正常返回
+   *     （后续 push 会自己建分支）；有分支但名字对不上则拒绝猜，把远端分支名列出来。
+   */
+  private async adoptRemoteHistory(): Promise<void> {
+    // ① 未提交改动：不替用户丢改动
+    const statusRes = await this.runGit(['status', '--porcelain'], { allowNonZero: true });
+    if (statusRes.code !== 0) {
+      throw new GitTransportError(
+        this.msg('sync.git.cmdFailed', {
+          args: 'status --porcelain',
+          code: String(statusRes.code),
+          err: this.mask(statusRes.stderr, await this.readTokenOnce()),
+        }),
+        { kind: 'unknown', retryable: true },
+      );
+    }
+    if (statusRes.stdout.trim() !== '') {
+      throw new GitTransportError(
+        this.msg('sync.git.adoptDirty', { dir: this.o.workDir }),
+        { kind: 'protocol', retryable: false },
+      );
+    }
+    await this.reconcileOrigin();
+    const branchRes = await this.runGit(['rev-parse', '--abbrev-ref', 'HEAD'], { allowNonZero: true });
+    const branch = branchRes.code === 0 ? branchRes.stdout.trim() : '';
+    if (branch === '' || branch === 'HEAD') {
+      // detached HEAD：没有分支可挂比 upstream，合并也不会被 push 走 → 拒绝并说明
+      throw new GitTransportError(
+        this.msg('sync.git.adoptDetached', { dir: this.o.workDir }),
+        { kind: 'protocol', retryable: false },
+      );
+    }
+    // fetch 是网络操作（幂等读）→ 允许有限指数退避重试
+    await withSyncRetry(async () => {
+      await this.runGit(['fetch', 'origin'], { withCredential: true });
+    }, this.o.retry);
+    const remoteRef = `refs/remotes/origin/${branch}`;
+    const refRes = await this.runGit(['rev-parse', '--verify', '--quiet', remoteRef], { allowNonZero: true });
+    if (refRes.code !== 0) {
+      // 远端没有同名分支：用 ls-remote 区分「远端是空仓库」与「分支名不同」
+      const headsRes = await this.runGit(['ls-remote', '--heads', 'origin'], { withCredential: true, allowNonZero: true });
+      const heads = (headsRes.code === 0 ? headsRes.stdout : '')
+        .split('\n')
+        .map((line) => line.trim().split('\t')[1] ?? '')
+        .filter((ref) => ref.startsWith('refs/heads/'))
+        .map((ref) => ref.slice('refs/heads/'.length));
+      if (heads.length === 0) {
+        this.repoReady = true; // 空仓库：没有可采纳的历史，后续 push 会建分支
+        return;
+      }
+      throw new GitTransportError(
+        this.msg('sync.git.adoptNoRemoteBranch', { branch, heads: heads.slice(0, 3).join(', ') }),
+        { kind: 'protocol', retryable: false },
+      );
+    }
+    // ② 远端顶层只能是快照布局
+    const treeRes = await this.runGit(['ls-tree', '--name-only', `origin/${branch}`], { allowNonZero: true });
+    if (treeRes.code !== 0) {
+      throw new GitTransportError(
+        this.msg('sync.git.cmdFailed', {
+          args: `ls-tree --name-only origin/${branch}`,
+          code: String(treeRes.code),
+          err: this.mask(treeRes.stderr, await this.readTokenOnce()),
+        }),
+        { kind: 'unknown', retryable: true },
+      );
+    }
+    const unknownEntries = treeRes.stdout
+      .split('\n')
+      .map((name) => name.trim().replace(/\/$/, ''))
+      .filter((name) => name !== '' && !ADOPT_ROOT_ALLOW.has(name));
+    if (unknownEntries.length > 0) {
+      throw new GitTransportError(
+        this.msg('sync.git.adoptNotSyncRepo', { entries: unknownEntries.slice(0, 3).join(', ') }),
+        { kind: 'protocol', retryable: false },
+      );
+    }
+    // ③ 合并（不改写任何本地提交）；冲突则 abort 回起点再报错
+    const mergeRes = await this.runGit(['merge', '--allow-unrelated-histories', '--no-edit', `origin/${branch}`], { allowNonZero: true });
+    if (mergeRes.code !== 0) {
+      await this.runGit(['merge', '--abort'], { allowNonZero: true });
+      throw new GitTransportError(
+        this.msg('sync.git.adoptMergeConflict', { branch }),
+        { kind: 'conflict', retryable: false },
+      );
+    }
+    // 让后续 pull --ff-only 有 upstream 可用（忽略失败：分支可能已被删/重命名）
+    await this.runGit(['branch', '--set-upstream-to', `origin/${branch}`, branch], { allowNonZero: true });
+    this.repoReady = true;
+  }
+
   /**
    * pull --ff-only 同步远端；无本地提交（全新仓库）或无 upstream 时静默跳过。
    * opts.retryable=true（仅 list / download 等**幂等读**路径传）：瞬时网络故障走有限指数退避重试。
@@ -666,7 +829,17 @@ export class GitTransport implements SyncTransport {
     const fileArg = quoteGitValue(credFile.replace(/\\/g, '/'));
     await atomicWriteFile(credFile, `https://${this.o.credentialUsername}:${token}@${host}\n`, { mode: 0o600, symlink: 'reject' });
     return {
-      extraArgs: ['-c', 'credential.helper=', '-c', `credential.helper=store --file=${fileArg}`],
+      // issue #103：**必须**把用户名也钉进 git 参数。git credential store 用 URL 里的 username
+      // 作为查找键；store 文件写的是本插件自己的用户名（默认 oauth2），但 git 会先读全局
+      // `.gitconfig` 里的 `credential.<url>.username`（Git Credential Manager / gh CLI 都会写这一行），
+      // 用那个用户名去查 store —— 键对不上就查不到口令，无 tty 时退化成
+      // `fatal: could not read Password for 'https://<全局用户名>@host'`。
+      // 钉住 username 后查找键与 store 文件里的值同源（都来自 credentialUsername）。
+      extraArgs: [
+        '-c', 'credential.helper=',
+        '-c', `credential.helper=store --file=${fileArg}`,
+        '-c', `credential.username=${this.o.credentialUsername}`,
+      ],
       token,
       cleanup: async () => { await fs.rm(tmpDir, { recursive: true, force: true }); },
     };

package/src/sync/merge.test.ts

@@ -1,10 +1,10 @@
 /**
  * m-sync-flow：三方合并引擎测试。
  * 覆盖：
- *  - 分区级四象限（useRemote / keepLocal / skip / conflict）
- *  - JSON 分区键级精细合并（非重叠键自动合、双侧均改且不同留冲突）
- *  - FilesSection 文件级精细合并
- *  - MergePlan 输出形状
+ *  - 分区级四象限（useRemote / keepLocal / skip / conflict）+ 精细合并成功的 'merge' 决策
+ *  - JSON 分区递归合并（嵌套对象/未知字段保留/数组保守冲突/冲突路径到叶子）
+ *  - FilesSection 逐文件合并（文本行级三方合并 / 二进制保留冲突 / 删除-修改冲突）
+ *  - MergePlan 输出形状与 MergeConflict.reason
  *  - 无祖先退化为整分区冲突
  */
 import test from 'node:test';
@@ -22,13 +22,22 @@ const settings = (ns: Record<string, { value: unknown; revision: number }>): Set
 
 const files = (entries: Array<[string, string]>): FilesSection => ({
   version: 1,
-  files: entries.map(([p, c]) => ({ relativePath: p, data: new TextEncoder().encode(c), contentHash: '' })),
+  files: entries.map(([pth, c]) => ({ relativePath: pth, data: new TextEncoder().encode(c), contentHash: '' })),
 });
 
+const binFiles = (entries: Array<[string, Uint8Array]>): FilesSection => ({
+  version: 1,
+  files: entries.map(([pth, data]) => ({ relativePath: pth, data, contentHash: '' })),
+});
+
+const decode = (s: FilesSection, path: string): string | undefined => {
+  const f = s.files.find((x) => x.relativePath === path);
+  return f === undefined ? undefined : new TextDecoder().decode(f.data);
+};
+
 test('merge: 本地==远端 → skip', () => {
   const s = settings({ general: { value: { theme: 'dark' }, revision: 1 } });
-  const a = s;
-  const plan = merge({ settings: s as SectionData }, { settings: s as SectionData }, { settings: a as SectionData });
+  const plan = merge({ settings: s as SectionData }, { settings: s as SectionData }, { settings: s as SectionData });
   assert.equal(plan.sections.length, 1);
   assert.equal(plan.sections[0]!.decision, 'skip');
   assert.equal(plan.sections[0]!.conflicts.length, 0);
@@ -36,10 +45,9 @@ test('merge: 本地==远端 → skip', () => {
 
 test('merge: 本地==祖先 & 远端!=祖先 → useRemote', () => {
   const anc = settings({ general: { value: { theme: 'dark' }, revision: 1 } });
-  const loc = anc;
   const rem = settings({ general: { value: { theme: 'light' }, revision: 2 } });
   const plan = merge(
-    { settings: loc as SectionData },
+    { settings: anc as SectionData },
     { settings: rem as SectionData },
     { settings: anc as SectionData },
   );
@@ -50,17 +58,16 @@ test('merge: 本地==祖先 & 远端!=祖先 → useRemote', () => {
 test('merge: 本地!=祖先 & 远端==祖先 → keepLocal', () => {
   const anc = settings({ general: { value: { theme: 'dark' }, revision: 1 } });
   const loc = settings({ general: { value: { theme: 'custom' }, revision: 2 } });
-  const rem = anc;
   const plan = merge(
     { settings: loc as SectionData },
-    { settings: rem as SectionData },
+    { settings: anc as SectionData },
     { settings: anc as SectionData },
   );
   assert.equal(plan.sections[0]!.decision, 'keepLocal');
   assert.deepEqual((plan.sections[0]!.merged as SettingsSection).namespaces.general!.value, { theme: 'custom' });
 });
 
-test('merge: 双侧相对祖先都改且分区 hash 不同 → conflict', () => {
+test('merge: 双侧相对祖先都改且同处不同值 → conflict（路径精确到叶子）', () => {
   const anc = settings({ general: { value: { theme: 'dark' }, revision: 1 } });
   const loc = settings({ general: { value: { theme: 'blue' }, revision: 2 } });
   const rem = settings({ general: { value: { theme: 'red' }, revision: 2 } });
@@ -70,7 +77,11 @@ test('merge: 双侧相对祖先都改且分区 hash 不同 → conflict', () =>
     { settings: anc as SectionData },
   );
   assert.equal(plan.sections[0]!.decision, 'conflict');
-  assert.ok(plan.sections[0]!.conflicts.length >= 1);
+  assert.equal(plan.sections[0]!.merged, undefined, '冲突时绝不回传半成品 merged');
+  assert.equal(plan.sections[0]!.conflicts.length, 1);
+  assert.equal(plan.sections[0]!.conflicts[0]!.path, 'namespaces.general.value.theme');
+  assert.equal(plan.sections[0]!.conflicts[0]!.kind, 'key');
+  assert.equal(plan.sections[0]!.conflicts[0]!.reason, 'both-modified');
 });
 
 test('merge: 无 ancestor → 整分区 conflict（不猜测）', () => {
@@ -78,20 +89,18 @@ test('merge: 无 ancestor → 整分区 conflict（不猜测）', () => {
   const rem = settings({ general: { value: { theme: 'light' }, revision: 2 } });
   const plan = merge({ settings: loc as SectionData }, { settings: rem as SectionData });
   assert.equal(plan.sections[0]!.decision, 'conflict');
+  assert.equal(plan.sections[0]!.conflicts[0]!.reason, 'no-ancestor');
 });
 
-test('merge: JSON 分区键级精细合并 —— 非重叠键各自变更自动合', () => {
-  // 祖先：{ general: {theme:'dark'}, editor: {fontSize:12} }
+test('merge: JSON 非重叠键各自变更 → decision=merge + autoMerged 计数（不再谎报 useRemote）', () => {
   const anc = settings({
     general: { value: { theme: 'dark' }, revision: 1 },
     editor: { value: { fontSize: 12 }, revision: 1 },
   });
-  // 本地：改 editor
   const loc = settings({
     general: { value: { theme: 'dark' }, revision: 1 },
     editor: { value: { fontSize: 14 }, revision: 2 },
   });
-  // 远端：改 general
   const rem = settings({
     general: { value: { theme: 'light' }, revision: 2 },
     editor: { value: { fontSize: 12 }, revision: 1 },
@@ -101,29 +110,60 @@ test('merge: JSON 分区键级精细合并 —— 非重叠键各自变更自动
     { settings: rem as SectionData },
     { settings: anc as SectionData },
   );
-  assert.equal(plan.sections[0]!.decision, 'useRemote', '精细合并后无非冲突 → useRemote（承载合并结果）');
-  const merged = plan.sections[0]!.merged as SettingsSection;
+  const r = plan.sections[0]!;
+  assert.equal(r.decision, 'merge');
+  assert.equal(r.conflicts.length, 0);
+  assert.ok((r.autoMerged ?? 0) > 0, 'autoMerged 必须如实统计并入的变更点');
+  const merged = r.merged as SettingsSection;
   assert.deepEqual(merged.namespaces.general!.value, { theme: 'light' });
   assert.deepEqual(merged.namespaces.editor!.value, { fontSize: 14 });
-  assert.equal(plan.sections[0]!.conflicts.length, 0);
 });
 
-test('merge: JSON 分区键级精细合并 —— 双侧均改同一 key 且值不同 → 冲突', () => {
-  const anc = settings({ general: { value: { theme: 'dark' }, revision: 1 } });
-  const loc = settings({ general: { value: { theme: 'blue' }, revision: 2 } });
-  const rem = settings({ general: { value: { theme: 'red' }, revision: 2 } });
-  const plan = merge(
-    { settings: loc as SectionData },
-    { settings: rem as SectionData },
-    { settings: anc as SectionData },
-  );
-  assert.equal(plan.sections[0]!.decision, 'conflict');
-  assert.equal(plan.sections[0]!.conflicts.length, 1);
-  assert.equal(plan.sections[0]!.conflicts[0]!.path, 'general');
-  assert.equal(plan.sections[0]!.conflicts[0]!.kind, 'key');
+test('merge: 深层嵌套 JSON 合并（不同叶子自动合，未知字段两侧都保留）', () => {
+  const anc: SectionData = { version: 1, ui: { theme: { color: 'dark', size: 12 }, extra: { a: 1 } } } as unknown as SectionData;
+  const loc: SectionData = { version: 1, ui: { theme: { color: 'blue', size: 12 }, extra: { a: 1 }, localOnly: true } } as unknown as SectionData;
+  const rem: SectionData = { version: 1, ui: { theme: { color: 'dark', size: 16 }, extra: { a: 1 }, remoteOnly: true } } as unknown as SectionData;
+  const plan = merge({ settings: loc }, { settings: rem }, { settings: anc });
+  const r = plan.sections[0]!;
+  assert.equal(r.decision, 'merge');
+  const merged = r.merged as unknown as { ui: Record<string, unknown> };
+  assert.deepEqual(merged.ui['theme'], { color: 'blue', size: 16 });
+  assert.equal(merged.ui['localOnly'], true, '本地新增的未知字段不得被静默丢弃');
+  assert.equal(merged.ui['remoteOnly'], true, '远端新增的未知字段不得被静默丢弃');
 });
 
-test('merge: FilesSection 文件级精细合并 —— 非重叠文件自动合', () => {
+test('merge: 数组双侧都改且不同 → conflict(reason=array)，不按索引猜', () => {
+  const anc: SectionData = { version: 1, plugins: [{ spec: 'a' }] } as unknown as SectionData;
+  const loc: SectionData = { version: 1, plugins: [{ spec: 'a' }, { spec: 'b' }] } as unknown as SectionData;
+  const rem: SectionData = { version: 1, plugins: [{ spec: 'c' }] } as unknown as SectionData;
+  const plan = merge({ plugins: loc }, { plugins: rem }, { plugins: anc });
+  const r = plan.sections[0]!;
+  assert.equal(r.decision, 'conflict');
+  assert.equal(r.conflicts[0]!.path, 'plugins');
+  assert.equal(r.conflicts[0]!.reason, 'array');
+});
+
+test('merge: 数组仅一侧改 → 采纳该侧（另一侧键的改动同时保住）', () => {
+  const anc: SectionData = { version: 1, plugins: [{ spec: 'a' }], note: 'x' } as unknown as SectionData;
+  const loc: SectionData = { version: 1, plugins: [{ spec: 'a' }, { spec: 'b' }], note: 'x' } as unknown as SectionData;
+  const rem: SectionData = { version: 1, plugins: [{ spec: 'a' }], note: 'y' } as unknown as SectionData;
+  const plan = merge({ plugins: loc }, { plugins: rem }, { plugins: anc });
+  const r = plan.sections[0]!;
+  assert.equal(r.decision, 'merge');
+  const merged = r.merged as unknown as { plugins: unknown[]; note: string };
+  assert.equal(merged.plugins.length, 2);
+  assert.equal(merged.note, 'y');
+});
+
+test('merge: 数组双侧改成相同结果 → 收敛为一份（不算冲突）', () => {
+  const anc: SectionData = { version: 1, plugins: [{ spec: 'a' }] } as unknown as SectionData;
+  const loc: SectionData = { version: 1, plugins: [{ spec: 'a' }, { spec: 'b' }] } as unknown as SectionData;
+  const rem: SectionData = { version: 1, plugins: [{ spec: 'a' }, { spec: 'b' }] } as unknown as SectionData;
+  const plan = merge({ plugins: loc }, { plugins: rem }, { plugins: anc });
+  assert.equal(plan.sections[0]!.decision, 'skip');
+});
+
+test('merge: FilesSection 非重叠文件自动合 → decision=merge', () => {
   const anc = files([['a.md', '# A old\n'], ['b.md', '# B\n']]);
   const loc = files([['a.md', '# A new local\n'], ['b.md', '# B\n']]);
   const rem = files([['a.md', '# A old\n'], ['b.md', '# B remote\n']]);
@@ -132,44 +172,126 @@ test('merge: FilesSection 文件级精细合并 —— 非重叠文件自动合'
     { skills: rem as SectionData },
     { skills: anc as SectionData },
   );
-  assert.equal(plan.sections[0]!.decision, 'useRemote');
-  const merged = plan.sections[0]!.merged as FilesSection;
-  const byPath = new Map(merged.files.map((f) => [f.relativePath, new TextDecoder().decode(f.data)]));
-  assert.equal(byPath.get('a.md'), '# A new local\n');
-  assert.equal(byPath.get('b.md'), '# B remote\n');
+  const r = plan.sections[0]!;
+  assert.equal(r.decision, 'merge');
+  const merged = r.merged as FilesSection;
+  assert.equal(decode(merged, 'a.md'), '# A new local\n');
+  assert.equal(decode(merged, 'b.md'), '# B remote\n');
 });
 
-test('merge: FilesSection 文件级精细合并 —— 双侧均改同一文件 → 冲突', () => {
-  const anc = files([['a.md', '# A old\n']]);
-  const loc = files([['a.md', '# A local\n']]);
-  const rem = files([['a.md', '# A remote\n']]);
+test('merge: 同一文本文件两侧改不同行 → 行级三方合并成功', () => {
+  const anc = files([['a.md', 'line1\nline2\nline3\n']]);
+  const loc = files([['a.md', 'LINE1\nline2\nline3\n']]);
+  const rem = files([['a.md', 'line1\nline2\nLINE3\n']]);
   const plan = merge(
     { skills: loc as SectionData },
     { skills: rem as SectionData },
     { skills: anc as SectionData },
   );
-  assert.equal(plan.sections[0]!.decision, 'conflict');
-  assert.equal(plan.sections[0]!.conflicts[0]!.kind, 'file');
-  assert.equal(plan.sections[0]!.conflicts[0]!.path, 'a.md');
+  const r = plan.sections[0]!;
+  assert.equal(r.decision, 'merge', '不同行的改动必须能自动合并');
+  assert.equal(decode(r.merged as FilesSection, 'a.md'), 'LINE1\nline2\nLINE3\n');
 });
 
-test('merge: 远端缺 + 本地等于祖先 → skip', () => {
-  const anc = settings({ general: { value: { theme: 'dark' }, revision: 1 } });
+test('merge: 同一文本文件两侧改同一行 → 冲突（不静默覆盖任何一侧）', () => {
+  const anc = files([['a.md', 'line1\nline2\n']]);
+  const loc = files([['a.md', 'line1\nLOCAL\n']]);
+  const rem = files([['a.md', 'line1\nREMOTE\n']]);
   const plan = merge(
-    { settings: anc as SectionData },
-    {}, // 远端无此分区
-    { settings: anc as SectionData },
+    { skills: loc as SectionData },
+    { skills: rem as SectionData },
+    { skills: anc as SectionData },
   );
+  const r = plan.sections[0]!;
+  assert.equal(r.decision, 'conflict');
+  assert.equal(r.conflicts[0]!.kind, 'file');
+  assert.equal(r.conflicts[0]!.path, 'a.md');
+  assert.equal(r.conflicts[0]!.reason, 'both-modified');
+});
+
+test('merge: 二进制文件两侧都改 → 冲突 reason=binary（不做文本合并）', () => {
+  const anc = binFiles([['blob.bin', new Uint8Array([0, 1, 2])]]);
+  const loc = binFiles([['blob.bin', new Uint8Array([0, 9, 2])]]);
+  const rem = binFiles([['blob.bin', new Uint8Array([0, 7, 2])]]);
+  const plan = merge(
+    { skills: loc as SectionData },
+    { skills: rem as SectionData },
+    { skills: anc as SectionData },
+  );
+  const r = plan.sections[0]!;
+  assert.equal(r.decision, 'conflict');
+  assert.equal(r.conflicts[0]!.reason, 'binary');
+  assert.equal(r.conflicts[0]!.autoMergeAttempted, true);
+});
+
+test('merge: 文件级 本地改 / 远端删 → modify-delete 冲突（不直接删数据）', () => {
+  const anc = files([['a.md', '# A\n'], ['b.md', '# B\n']]);
+  const loc = files([['a.md', '# A local edit\n'], ['b.md', '# B\n']]);
+  const rem = files([['b.md', '# B\n']]);
+  const plan = merge(
+    { skills: loc as SectionData },
+    { skills: rem as SectionData },
+    { skills: anc as SectionData },
+  );
+  const r = plan.sections[0]!;
+  assert.equal(r.decision, 'conflict');
+  assert.equal(r.conflicts[0]!.path, 'a.md');
+  assert.equal(r.conflicts[0]!.reason, 'modify-delete');
+});
+
+test('merge: 文件级 本地删 / 远端改 → delete-modify 冲突', () => {
+  const anc = files([['a.md', '# A\n'], ['b.md', '# B\n']]);
+  const loc = files([['b.md', '# B\n']]);
+  const rem = files([['a.md', '# A remote edit\n'], ['b.md', '# B\n']]);
+  const plan = merge(
+    { skills: loc as SectionData },
+    { skills: rem as SectionData },
+    { skills: anc as SectionData },
+  );
+  const r = plan.sections[0]!;
+  assert.equal(r.decision, 'conflict');
+  assert.equal(r.conflicts[0]!.path, 'a.md');
+  assert.equal(r.conflicts[0]!.reason, 'delete-modify');
+});
+
+test('merge: 文件级 本地删 / 远端未改 → 跟随删除（无冲突）', () => {
+  const anc = files([['a.md', '# A\n'], ['b.md', '# B\n']]);
+  const loc = files([['b.md', '# B\n']]);
+  const rem = files([['a.md', '# A\n'], ['b.md', '# B changed\n']]);
+  const plan = merge(
+    { skills: loc as SectionData },
+    { skills: rem as SectionData },
+    { skills: anc as SectionData },
+  );
+  const r = plan.sections[0]!;
+  assert.equal(r.decision, 'merge');
+  const merged = r.merged as FilesSection;
+  assert.equal(decode(merged, 'a.md'), undefined, '本地已删且远端未改 → 跟随删除');
+  assert.equal(decode(merged, 'b.md'), '# B changed\n');
+});
+
+test('merge: 远端缺 + 本地等于祖先 → skip', () => {
+  const anc = settings({ general: { value: { theme: 'dark' }, revision: 1 } });
+  const plan = merge({ settings: anc as SectionData }, {}, { settings: anc as SectionData });
   assert.equal(plan.sections[0]!.decision, 'skip');
 });
 
+test('merge: 远端缺 + 本地改了 → 冲突且不得丢弃本地改动', () => {
+  const anc = settings({ general: { value: { theme: 'dark' }, revision: 1 } });
+  const loc = settings({ general: { value: { theme: 'blue' }, revision: 2 } });
+  const plan = merge({ settings: loc as SectionData }, {}, { settings: anc as SectionData });
+  assert.equal(plan.sections[0]!.decision, 'conflict');
+  assert.equal(plan.sections[0]!.conflicts[0]!.reason, 'modify-delete');
+  assert.ok(plan.sections[0]!.conflicts[0]!.local !== undefined);
+});
+
 test('merge: MergePlan 输出形状符合 contract', () => {
   const anc = settings({ general: { value: { theme: 'dark' }, revision: 1 } });
   const plan = merge({ settings: anc as SectionData }, { settings: anc as SectionData }, { settings: anc as SectionData });
   assert.ok(Array.isArray(plan.sections));
   const r = plan.sections[0]!;
   assert.equal(typeof r.id, 'string');
-  assert.ok(['useRemote', 'keepLocal', 'skip', 'conflict'].includes(r.decision));
+  assert.ok(['useRemote', 'keepLocal', 'merge', 'skip', 'conflict'].includes(r.decision));
   assert.ok(Array.isArray(r.conflicts));
 });
 
@@ -177,7 +299,6 @@ test('merge: 多分区混合场景（settings skip / providers keepLocal / skill
   const sA = settings({ general: { value: { theme: 'dark' }, revision: 1 } });
   const pA: SectionData = { version: 1, providers: { openai: { route: 'https://api.openai.com/v1' } } };
   const fA = files([['a.md', '# A\n']]);
-
   const plan = merge(
     {
       settings: sA as SectionData,
@@ -197,8 +318,20 @@ test('merge: 多分区混合场景（settings skip / providers keepLocal / skill
   );
   const byId = new Map(plan.sections.map((s) => [s.id, s]));
   assert.equal(byId.get('settings')!.decision, 'skip');
-  // providers：本地改了 route、远端 == 祖先 → keepLocal
   assert.equal(byId.get('providers')!.decision, 'keepLocal');
-  // skills：本地 == 祖先、远端新增 b.md → useRemote
   assert.equal(byId.get('skills')!.decision, 'useRemote');
 });
+
+test('merge: 类型不一致（一侧文件类 / 一侧 JSON）→ 整分区冲突 reason=section', () => {
+  const anc = settings({ general: { value: { theme: 'dark' }, revision: 1 } });
+  const loc = files([['a.md', '# A\n']]);
+  const rem = settings({ general: { value: { theme: 'light' }, revision: 2 } });
+  const plan = merge(
+    { skills: loc as SectionData },
+    { skills: rem as SectionData },
+    { skills: anc as SectionData },
+  );
+  const r = plan.sections[0]!;
+  assert.equal(r.decision, 'conflict');
+  assert.equal(r.conflicts[0]!.reason, 'section');
+});