dsh-config-manager 0.1.78 → 0.1.80

package/lib/sync/git/git-transport.d.ts

@@ -1,5 +1,5 @@
 import { SyncTransportError } from '../transport.ts';
-import type { SyncRetryOptions, SyncSnapshot, SyncSnapshotMeta, SyncTransport, SyncTransportErrorOptions } from '../transport.ts';
+import type { SyncProbeResult, SyncRetryOptions, SyncSnapshot, SyncSnapshotMeta, SyncTransport, SyncTransportErrorOptions } from '../transport.ts';
 import type { MsgFunc } from '../../core/messages.ts';
 /** git 命令执行结果（code ≠ 0 = git 命令失败/退出非零） */
 export interface GitExecResult {
@@ -28,6 +28,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 只从这里读取，绝不在任何地方持久化 */
 export interface GitCredentialProvider {
@@ -105,6 +113,16 @@ export declare class GitTransport implements SyncTransport {
      * UI 层可用 isPrivateHint 提示「私有仓库推荐」；公开仓库也可用（内容需自行评估）。
      */
     checkIsPrivate(): Promise<boolean>;
+    /**
+     * 连通性探针（cloud-sync 借鉴项 ②）：只读自检「远端可达 + 凭据可用」。
+     *
+     * 为什么复用 ls-remote：它不需要工作副本、不写任何本地状态，而且正是 clone/fetch 之前的那一步 ——
+     * 远端不可达 / 令牌失效 / SSH 主机密钥不信任都会在这里显式失败（checkIsPrivate 抛可操作文案），
+     * 因此结论与随后真正同步时的成败**同源**。
+     * 刻意**不**统计远端快照数：那要先 fetch 工作副本（对本地有写入），超出「只读自检」的范围 ——
+     * 宁可不报，也不报一个会误导的 0。
+     */
+    probe(): Promise<SyncProbeResult>;
     private ensureRepo;
     /**
      * 让工作副本的 origin 与配置的 repoUrl 保持一致（issue #79）。
@@ -131,14 +149,35 @@ export declare class GitTransport implements SyncTransport {
         detail?: boolean;
     }): Promise<GitWorkDirFacts>;
     /**
-     * 重建工作副本（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）—— 绝不删来路不明的目录。
      */
-    rebuildWorkDir(mode: 'relink' | 'reclone'): Promise<void>;
+    rebuildWorkDir(mode: 'relink' | 'adopt' | 'reclone'): Promise<void>;
+    /**
+     * 采纳远端历史（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 adoptRemoteHistory;
     /**
      * pull --ff-only 同步远端；无本地提交（全新仓库）或无 upstream 时静默跳过。
      * opts.retryable=true（仅 list / download 等**幂等读**路径传）：瞬时网络故障走有限指数退避重试。

package/lib/sync/git/git-transport.js

@@ -55,6 +55,11 @@ const SNAPSHOTS_ENCRYPTED_REL = 'snapshots-encrypted';
  * 内容没变 = 文件路径已存在 = 一个字都不写、也不进本次 diff。
  */
 const BLOBS_REL = 'blobs';
+/**
+ * 同步仓库（git 通道）顶层**只可能出现**这三个条目。issue #104 的 `adopt` 模式拿它当安全判据：
+ * 远端分支的顶层出现别的名字 = 这不是本插件的同步仓库，合并它等于把别人的仓库内容搬进工作副本。
+ */
+const ADOPT_ROOT_ALLOW = new Set([SNAPSHOTS_REL, SNAPSHOTS_ENCRYPTED_REL, BLOBS_REL]);
 const DEFAULT_AUTHOR = { name: 'DSH Config Sync', email: 'sync@dsh.local' };
 const DEFAULT_CREDENTIAL_USERNAME = 'oauth2';
 /** 快照 id 安全字符集：字母数字开头，仅 . _ -；防路径穿越与 commit message 注入 */
@@ -330,6 +335,19 @@ export class GitTransport {
         }
         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() {
+        await this.checkIsPrivate();
+        return { message: this.msg('sync.git.probeOk') };
+    }
     /* ---------------- 内部实现 ---------------- */
     async ensureRepo() {
         if (this.repoReady)
@@ -419,7 +437,7 @@ export class GitTransport {
     async inspectWorkDir(opts = {}) {
         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() : '';
@@ -427,6 +445,7 @@ export class GitTransport {
         const pushRaw = pushRes.code === 0 ? pushRes.stdout.trim() : '';
         let ahead = null;
         let dirty = null;
+        let remoteSnapshots = null;
         if (opts.detail === true) {
             // 未上行的本地提交：HEAD 可达、但任何远端跟踪引用都不可达的提交数（无 upstream 也能算）
             const aheadRes = await this.runGit(['rev-list', '--count', 'HEAD', '--not', '--remotes'], { allowNonZero: true });
@@ -434,6 +453,28 @@ export class GitTransport {
             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) => {
+                    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,
@@ -444,11 +485,14 @@ export class GitTransport {
             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
@@ -470,9 +514,98 @@ export class GitTransport {
             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 会自己建分支）；有分支但名字对不上则拒绝猜，把远端分支名列出来。
+     */
+    async adoptRemoteHistory() {
+        // ① 未提交改动：不替用户丢改动
+        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 等**幂等读**路径传）：瞬时网络故障走有限指数退避重试。
@@ -579,7 +712,17 @@ export class GitTransport {
         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/lib/sync/merge.d.ts

@@ -2,37 +2,70 @@
  * m-sync-flow：三方合并引擎（纯函数）。
  *
  * 输入：local / remote / ancestor 各分区的 SectionData + 分区 hash。
- * 行为（每分区）：
- *   - localHash == remoteHash        → skip（无变化）
- *   - localHash != remoteHash：
- *     - localHash == ancestorHash    → useRemote（远端独有改动）
- *     - remoteHash == ancestorHash   → keepLocal（本地独有改动）
- *     - 其余                          → 进入精细合并：JSON 分区按 top-level key 合并、FilesSection 按 relativePath 合并；
- *                                       仅双侧均改且值不同的键/文件留为 conflict，其余非重叠变更自动合入。
+ * 输出：MergePlan（纯数据，不含副作用），由上层（SyncEngine.merge / previewMerge）交给 UI 决策。
  *
- * 输出：MergePlan（纯数据，不含副作用），由上层（SyncEngine.merge）返回给 UI 决策。
+ * 每分区的决策链（顺序即优先级，与 git 的三方合并口径一致）：
+ *   1. localHash == remoteHash    → skip（无变化，绝不产生多余写入）
+ *   2. 仅一侧存在该分区           → 单边存在：不构成删除语义（见 §边界），按变化与否取舍
+ *   3. ancestor 缺失              → conflict(reason='no-ancestor')：拒绝猜测共同祖先
+ *   4. localHash == ancestorHash  → useRemote（仅远端改）
+ *   5. remoteHash == ancestorHash → keepLocal（仅本地改）
+ *   6. 双侧相对祖先都改           → 精细合并：
+ *        - JSON 分区：递归对象合并（mergeJsonValues），冲突路径精确到叶子（'namespaces.general.value.theme'）
+ *        - FilesSection：逐 relativePath 合并，两侧都改的文本文件再走行级三方合并（mergeBytesThreeWay）
+ *        - 无残留冲突 → decision='merge'（merged + autoMerged 计数）
+ *        - 有残留冲突 → decision='conflict'（merged 为 undefined：绝不把半成品当结果）
  *
- * 安全约束：ancestor 为 undefined 时退化为两方合并：local != remote 视为整分区 conflict（拒绝猜测共同祖先）。
+ * 安全约束（改这里前先读）：
+ *  - 数组**绝不**按索引合并：双侧都改且不逐字相等 → 冲突（reason='array'）。语义不明的合并比冲突更危险。
+ *  - 二进制 / 超大文件不做文本合并（mergeBytesThreeWay 会如实拒绝）→ 保留冲突交用户裁决。
+ *  - 绝不静默丢弃任一侧的未知字段 / 插件配置 / 用户数据：递归合并只对「双侧都改同一处」报冲突，
+ *    单侧新增/修改的键一律保留。
+ *  - ancestor 缺失时退化为两方：差异一律整分区 conflict（拒绝猜测共同祖先）。
+ *
+ * 边界（有意如此，勿“修复”）：分区在某侧**缺失**不等于「该侧删了这个分区」—— 同步只搬本轮
+ * 勾选的分区，可选分区（sessions/mcp）未勾选时为缺失。因此分区级缺失不判删除冲突；
+ * 文件级（FilesSection 内的 relativePath）才是真正的删除语义，那里按 modify/delete 判冲突。
  */
 import type { SectionData, SectionId } from '../schema/types.ts';
-export type MergeDecision = 'useRemote' | 'keepLocal' | 'skip';
-/** 分区内精细合并产生的单条冲突（JSON key 或 FilesSection 单文件）。 */
+/**
+ * 分区级决胜结果（三方合并，2026-10 收口）：
+ *  - 'skip'      ：双侧相对祖先都未改（或本就无变化）—— 不产生任何写入；
+ *  - 'useRemote' ：仅远端相对祖先改了（本地未改）→ 远端整分区原值胜出；
+ *  - 'keepLocal' ：仅本地相对祖先改了（远端未改）→ 本地整分区原值胜出；
+ *  - 'merge'     ：双侧都改，但**精细合并成功**（无残留冲突）→ merged 为合并结果。
+ *    'merge' 绝不等于 'useRemote'：把自动合并读成「用了远端」会让 UI/日志谎报数据来源。
+ *  - 'conflict'  ：双侧都改且无法安全自动合并 → merged 为 undefined，仅 conflicts 有值。
+ */
+export type MergeDecision = 'useRemote' | 'keepLocal' | 'merge' | 'skip';
+/** 冲突成因（可选字段：旧调用方/旧数据没有它，UI 缺省按 'both-modified' 措辞）。 */
+export type MergeConflictReason = 'both-modified' | 'modify-delete' | 'delete-modify' | 'no-ancestor' | 'binary' | 'too-large' | 'overlap' | 'array' | 'format' | 'section';
+/** 分区内精细合并产生的单条冲突（JSON 叶子 / FilesSection 单文件）。 */
 export interface MergeConflict {
-    /** 冲突位置：JSON 分区是 top-level key；FilesSection 是 relativePath。 */
+    /** 冲突位置：JSON 分区是**点号路径**（'a.b.c'，整分区为 '$'）；FilesSection 是 relativePath。 */
     path: string;
     kind: 'key' | 'file';
+    /** 冲突成因（可选：旧数据没有该字段；UI 缺省按 'both-modified' 措辞） */
+    reason?: MergeConflictReason;
+    /** 是否已尝试自动合并（true + reason='binary'/'too-large'/'array' = 试过但不安全，故留冲突） */
+    autoMergeAttempted?: boolean;
     local?: unknown;
     remote?: unknown;
     ancestor?: unknown;
 }
 export interface MergeSectionResult {
     id: SectionId;
-    /** 分区级决策；'skip' 时无 merged/conflicts；'conflict' 时 merged 为 null（仅 conflicts）。 */
+    /** 分区级决策；'skip' 时无 merged/conflicts；'conflict' 时 merged 为 undefined（仅 conflicts）。 */
     decision: MergeDecision | 'conflict';
-    /** 当 decision 为 'useRemote' / 'keepLocal' 时：合并后的整分区数据（= 胜出方原值）。 */
+    /** decision 为 'useRemote' / 'keepLocal' / 'merge' 时为整分区数据（原值或合并结果）。 */
     merged?: SectionData;
     /** 仅 decision === 'conflict' 时非空：分区级冲突或精细合并后剩余冲突。 */
     conflicts: MergeConflict[];
+    /**
+     * 自动合并并入的变更点数量（仅 decision === 'merge' 时有意义；缺省 undefined = 未统计）。
+     * UI 用它区分「远端整分区覆盖」与「双方改动都保住了」。
+     */
+    autoMerged?: number;
 }
 export interface MergePlan {
     /** 每分区的合并结果；仅含 local/remote/ancestor 三者任一出现的分区。 */