dsh-config-manager 0.1.78 → 0.1.79

package/lib/core/rollback-activity.js

@@ -0,0 +1,350 @@
+/**
+ * 会话**活跃时间窗**台账 —— 「某个时刻有哪些会话正在活着」。
+ *
+ * 为什么需要（2026-10-17 用户反馈 + 真机复盘）：写入归属（`rollback-attribution.ts`）只能从
+ * `tool/call` 的 arguments 里抽 `file_path`；`pwsh` / `run_code` / 脚本 / 外部编辑器写文件时
+ * **没有可解析的路径参数** ⇒ 这些写入完全没有归属，回退时识别不出「别的对话刚写过」，
+ * 于是把它一起抹掉（真机：B 对话给 README 加了一行，回退 A 时那一行也没了）。
+ *
+ * 这里补的是**时间维度**：文件 mtime 若落在某个会话的活跃窗口内，该会话就是候选写入者 ——
+ * 与工具参数完全无关，对 bash / 脚本 / 外部编辑器同样有效。
+ *
+ * ⚠️ 边界（不得越界解读）：时间窗只能证明「该会话在那时候有活动」，**不能单独证明「就是它写的」**。
+ * 它是旁证，不是判决；引擎必须把它与归属台账合起来用（见 rollback-point.ts 的判定）。
+ *
+ * 三条不变量（不得放宽）：
+ *  ① 采集**尽力而为**：只记「会话 id + 时间」，任何读写失败只 warn，绝不参与留点 / 回退的成败判定。
+ *  ② 窗口只增不减：同一会话的多次活动按 gapMs 合并；落盘前先读旧文件做**并集**，
+ *     两个 DSH 进程同写一个文件时绝不互相抹掉（落盘纪律照抄 `rollback-attribution.ts`）。
+ *  ③ 形状不符 = 空表：读不出来时宁可少一个窗口，也绝不猜字段含义（猜错会让回退误判归属）。
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+/** 台账文件名（与回滚点库同目录：dataDir/rollback-points/activity.json） */
+export const ROLLBACK_ACTIVITY_FILE_NAME = 'activity.json';
+/** 同一会话两条活动的间隔 <= 该值就并成一个窗口（缺省 10 分钟） */
+export const ROLLBACK_ACTIVITY_DEFAULT_GAP_MS = 10 * 60 * 1000;
+/** 窗口条目上限（超出按 to 淘汰最旧）—— 无界增长会把宿主拖垮（见 issue #89 的教训） */
+export const ROLLBACK_ACTIVITY_MAX_INTERVALS = 20000;
+/** 读一条窗口；形状不符返回 null（跳过，不猜） */
+function readInterval(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const record = value;
+    const sessionId = record.sessionId;
+    const from = record.from;
+    const to = record.to;
+    if (typeof sessionId !== 'string' || sessionId === '')
+        return null;
+    if (typeof from !== 'number' || !Number.isFinite(from) || from < 0)
+        return null;
+    if (typeof to !== 'number' || !Number.isFinite(to) || to < 0)
+        return null;
+    if (to < from)
+        return null;
+    return { sessionId, from, to };
+}
+/**
+ * 把一条窗口 [from, to] 并进窗口表（**纯函数**；落盘的「写前先读」也复用它）。
+ *
+ * 合并口径：与已有窗口的距离 <= gapMs 就并成一条（含重叠、相接）；
+ * 表内窗口按 from 升序且互不相接，所以「向后找不到可并的」即可停 —— 更早的窗口 to 只会更小。
+ */
+function mergeRangeInto(table, gapMs, sessionId, from, to) {
+    let list = table.get(sessionId);
+    if (list === undefined) {
+        list = [];
+        table.set(sessionId, list);
+    }
+    let hit = -1;
+    for (let i = list.length - 1; i >= 0; i -= 1) {
+        const iv = list[i];
+        if (iv === undefined)
+            continue;
+        if (from <= iv.to + gapMs && to >= iv.from - gapMs) {
+            hit = i;
+            break;
+        }
+        if (from > iv.to + gapMs)
+            break;
+    }
+    if (hit === -1) {
+        // 新开一条，按 from 升序插入（时钟回拨 / 乱序事件也不能让表失序）
+        let pos = list.length;
+        while (pos > 0) {
+            const prev = list[pos - 1];
+            if (prev === undefined || prev.from <= from)
+                break;
+            pos -= 1;
+        }
+        list.splice(pos, 0, { sessionId, from, to });
+        return;
+    }
+    const target = list[hit];
+    if (target === undefined)
+        return;
+    target.from = Math.min(target.from, from);
+    target.to = Math.max(target.to, to);
+    // 扩张后可能把左右邻居也拉进 gapMs 内 ⇒ 一并吸收，维持「互不相接」不变量
+    let index = hit;
+    while (index > 0) {
+        const left = list[index - 1];
+        const right = list[index];
+        if (left === undefined || right === undefined || right.from - left.to > gapMs)
+            break;
+        left.from = Math.min(left.from, right.from);
+        left.to = Math.max(left.to, right.to);
+        list.splice(index, 1);
+        index -= 1;
+    }
+    while (index + 1 < list.length) {
+        const left = list[index];
+        const right = list[index + 1];
+        if (left === undefined || right === undefined || right.from - left.to > gapMs)
+            break;
+        left.to = Math.max(left.to, right.to);
+        list.splice(index + 1, 1);
+    }
+}
+/** 窗口表 → 有稳定顺序的数组（先按会话 id，再按 from/to；落盘内容不随 Map 顺序抖动） */
+function flattenIntervals(table) {
+    const out = [];
+    for (const list of table.values()) {
+        for (const iv of list)
+            out.push({ sessionId: iv.sessionId, from: iv.from, to: iv.to });
+    }
+    out.sort((a, b) => (a.sessionId < b.sessionId ? -1 : a.sessionId > b.sessionId ? 1 : a.from - b.from || a.to - b.to));
+    return out;
+}
+/**
+ * 内存窗口表 + best-effort 落盘。
+ *
+ * 落盘的作用只有一个：**进程重启后**给旧会话回退时，活跃窗口还在（否则新进程只有本次启动后看到的窗口）。
+ * 因此写入是延迟合并的（一次会话事件一行，立即落盘会把 I/O 打成筛子）。
+ */
+export class RollbackSessionActivity {
+    table = new Map();
+    file;
+    now;
+    gapMs;
+    maxIntervals;
+    flushDelayMs;
+    warn;
+    loadPromise = null;
+    flushTimer = null;
+    writing = null;
+    /** 内存变更计数：与 lastFlushedRevision 相等 ⇒ 没有未落盘数据（flush 幂等靠它，不靠时间戳） */
+    revision = 0;
+    lastFlushedRevision = 0;
+    constructor(options) {
+        this.file = path.resolve(options.file);
+        this.now = options.now ?? (() => Date.now());
+        const gap = options.gapMs ?? ROLLBACK_ACTIVITY_DEFAULT_GAP_MS;
+        this.gapMs = Number.isFinite(gap) && gap >= 0 ? gap : ROLLBACK_ACTIVITY_DEFAULT_GAP_MS;
+        const max = options.maxIntervals ?? ROLLBACK_ACTIVITY_MAX_INTERVALS;
+        this.maxIntervals = Number.isFinite(max) && max >= 1 ? Math.floor(max) : ROLLBACK_ACTIVITY_MAX_INTERVALS;
+        const delay = options.flushDelayMs ?? 1000;
+        this.flushDelayMs = Number.isFinite(delay) ? delay : 1000;
+        this.warn = options.warn ?? (() => { });
+    }
+    /** 窗口总条数（诊断与测试用；上限见 maxIntervals。等价于「条目」，不是会话数） */
+    get size() {
+        let total = 0;
+        for (const list of this.table.values())
+            total += list.length;
+        return total;
+    }
+    /** 惰性读盘（幂等；读失败 = 空表，只 warn） */
+    async load() {
+        if (this.loadPromise === null)
+            this.loadPromise = this.read();
+        return this.loadPromise;
+    }
+    async read() {
+        try {
+            const text = await fs.readFile(this.file, 'utf8');
+            const parsed = JSON.parse(text);
+            if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed) || parsed.version !== 1 || !Array.isArray(parsed.intervals)) {
+                this.warn('rollback activity ignored (shape): ' + this.file);
+                return;
+            }
+            for (const raw of parsed.intervals) {
+                const iv = readInterval(raw);
+                if (iv === null)
+                    continue;
+                // 磁盘只是旧快照：**并集合并** ⇒ 读盘不得让本进程刚记的窗口消失（新记录优先）
+                mergeRangeInto(this.table, this.gapMs, iv.sessionId, iv.from, iv.to);
+            }
+            if (this.size > this.maxIntervals)
+                this.evictOldest();
+        }
+        catch (error) {
+            const code = error.code;
+            // ENOENT = 还没写过台账（正常）；其它错误如实留痕但不抛
+            if (code !== 'ENOENT')
+                this.warn('rollback activity unreadable: ' + this.file + ' ' + String(code ?? error));
+        }
+    }
+    /**
+     * 记一次活动。窗口只增不减：与上一条间隔 <= gapMs 就并入同一条窗口，否则新开一条。
+     *
+     * `at` 缺省取注入时钟（`options.now`）：引擎把**事件时间**显式传进来时以它为准
+     * （事件时间才是那次活动的真实时刻，取数时刻可能晚很多）。
+     * 空会话 id、非有限数字、负数一律**忽略**（fail-closed：宁可少一个窗口，绝不记错归属）。
+     */
+    noteActivity(sessionId, at = this.clockNow()) {
+        if (typeof sessionId !== 'string' || sessionId.trim() === '')
+            return;
+        if (typeof at !== 'number' || !Number.isFinite(at) || at < 0)
+            return;
+        mergeRangeInto(this.table, this.gapMs, sessionId, at, at);
+        this.revision += 1;
+        if (this.size > this.maxIntervals)
+            this.evictOldest();
+        this.scheduleFlush();
+    }
+    /** 缺省时钟：注入的 now 抛错或给出非有限值时 fail-closed（返回 NaN，由调用方校验丢弃） */
+    clockNow() {
+        try {
+            return this.now();
+        }
+        catch {
+            return Number.NaN;
+        }
+    }
+    /** 该会话最后一次活动时刻；没记过 = null（**不是 0**，0 会被误当成有效时间戳） */
+    lastActivityAt(sessionId) {
+        const list = this.table.get(sessionId);
+        if (list === undefined || list.length === 0)
+            return null;
+        const last = list[list.length - 1];
+        return last === undefined ? null : last.to;
+    }
+    /** 该会话是否有任何窗口（用于区分「确知没活动」与「根本没采到」） */
+    hasDataFor(sessionId) {
+        const list = this.table.get(sessionId);
+        return list !== undefined && list.length > 0;
+    }
+    /** 活跃窗口包含 at（可容忍 toleranceMs，缺省 0）的会话 id，按 id 升序、去重 */
+    sessionsActiveAt(at, toleranceMs = 0) {
+        const out = [];
+        if (typeof at !== 'number' || !Number.isFinite(at))
+            return out;
+        const tolerance = Number.isFinite(toleranceMs) && toleranceMs > 0 ? toleranceMs : 0;
+        for (const [sessionId, windows] of this.table) {
+            for (const iv of windows) {
+                if (at >= iv.from - tolerance && at <= iv.to + tolerance) {
+                    out.push(sessionId);
+                    break;
+                }
+            }
+        }
+        return out.sort();
+    }
+    /** 单个会话是否活跃（与 sessionsActiveAt 同口径，不另写一套判定） */
+    isActiveAt(sessionId, at, toleranceMs = 0) {
+        if (typeof sessionId !== 'string' || sessionId === '')
+            return false;
+        return this.sessionsActiveAt(at, toleranceMs).includes(sessionId);
+    }
+    /** 延迟落盘（多次调用只落一次） */
+    scheduleFlush() {
+        if (this.flushDelayMs <= 0 || this.flushTimer !== null)
+            return;
+        this.flushTimer = setTimeout(() => {
+            this.flushTimer = null;
+            void this.flush();
+        }, this.flushDelayMs);
+        this.flushTimer.unref?.();
+    }
+    /** 内存快照（深拷一层：落盘期间的新活动不得改写正在序列化的数据） */
+    snapshot() {
+        const clone = new Map();
+        for (const [sessionId, list] of this.table) {
+            clone.set(sessionId, list.map((iv) => ({ sessionId: iv.sessionId, from: iv.from, to: iv.to })));
+        }
+        return clone;
+    }
+    /** 淘汰最旧的窗口（按 to 升序删到上限内；条目 = 窗口，不是会话） */
+    evictOldest() {
+        const flat = [];
+        for (const list of this.table.values())
+            flat.push(...list);
+        const over = flat.length - this.maxIntervals;
+        if (over <= 0)
+            return;
+        flat.sort((a, b) => a.to - b.to || a.from - b.from);
+        const doomed = new Set(flat.slice(0, over));
+        for (const [sessionId, list] of [...this.table]) {
+            const kept = list.filter((iv) => !doomed.has(iv));
+            if (kept.length === 0)
+                this.table.delete(sessionId);
+            else
+                this.table.set(sessionId, kept);
+        }
+    }
+    /**
+     * 立刻落盘（原子：同目录临时文件 + rename；失败只 warn，绝不上抛）。
+     *
+     * 幂等：没有未落盘数据（revision == lastFlushedRevision）时**直接返回、不碰磁盘**；
+     * 并发调用共用同一个在飞写入。
+     */
+    async flush() {
+        if (this.writing !== null)
+            return this.writing;
+        if (this.revision === this.lastFlushedRevision)
+            return;
+        this.writing = (async () => {
+            const captured = this.revision;
+            try {
+                await fs.mkdir(path.dirname(this.file), { recursive: true });
+                const merged = this.snapshot();
+                // **写前合并**（2026-10-17 修）：本进程内存里只有自己见过的活动，而同一个工作区可能同时被
+                // 另一个 DSH 进程写台账 —— 各自「整体覆盖」会把对方的时间窗抹掉。窗口只增不减
+                // ⇒ 与磁盘做**并集合并**是唯一不丢信息的口径（同键取较新的那套在这里不适用：
+                // 时间窗不是「最后一次是谁」，而是「谁在这段时间活过」，两个进程的窗口都要留）。
+                try {
+                    const existing = JSON.parse(await fs.readFile(this.file, 'utf8'));
+                    if (existing !== null && typeof existing === 'object' && !Array.isArray(existing) && existing.version === 1 && Array.isArray(existing.intervals)) {
+                        for (const raw of existing.intervals) {
+                            const iv = readInterval(raw);
+                            if (iv === null)
+                                continue;
+                            mergeRangeInto(merged, this.gapMs, iv.sessionId, iv.from, iv.to);
+                        }
+                    }
+                }
+                catch {
+                    /* 读不到就当没有别人的记录：只写自己这份（绝不因为读失败而放弃落盘） */
+                }
+                const payload = { version: 1, intervals: flattenIntervals(merged) };
+                const tmp = this.file + '.tmp';
+                await fs.writeFile(tmp, JSON.stringify(payload), 'utf8');
+                await fs.rename(tmp, this.file);
+                this.lastFlushedRevision = captured;
+            }
+            catch (error) {
+                this.warn('rollback activity write failed: ' + this.file + ' ' + String(error.code ?? error));
+            }
+            finally {
+                this.writing = null;
+            }
+        })();
+        return this.writing;
+    }
+    /**
+     * 关闭：取消待落盘的定时器，并把还没落盘的活动写下去。
+     * 没有未落盘数据时不会重复写（flush 幂等）；写入失败只 warn，不透出（关停路径不得被台账拖垮）。
+     */
+    async dispose() {
+        if (this.flushTimer !== null) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = null;
+        }
+        await this.flush();
+        // 在飞写入期间又记了新活动 ⇒ 再落一次（最多两次，绝不循环重试）
+        if (this.revision !== this.lastFlushedRevision)
+            await this.flush();
+    }
+}
+//# sourceMappingURL=rollback-activity.js.map

package/lib/core/rollback-ledger.d.ts

@@ -122,15 +122,6 @@ export interface RollbackTempCleanupResult {
     /** 形似临时文件但**判据不足**（判不准就不删） */
     skipped: number;
 }
-/**
- * 删除 rollback-points/ 下**形状可自证**的崩溃残留原子写临时文件。
- *
- * 判据（三条全中才删，判不准一律不删）：
- *  1. 名字逐字符合 atomic-write.ts 的 tmpPath() 形态：.dshcm.<base>.<pid>.<16hex>.tmp；
- *  2. 该 pid **不是本进程**（本进程的 tmp 可能正在写）；
- *  3. 该 pid 进程已不存在（崩溃残留）—— 仍然活着的进程可能正在写，绝不抢。
- * 只扫根目录与它的一级子目录（records/ payloads/ objects/），不递归。
- */
 export declare function cleanupOrphanTempFiles(root: string): Promise<RollbackTempCleanupResult>;
 /** 清单条目校验：形状不对就**丢掉并计数**（与 v2 的 records.filter(isRollbackPointRecord) 同一条路） */
 export declare function normalizeManifestEntry(value: unknown): RollbackLedgerManifestEntry | null;

package/lib/core/rollback-ledger.js

@@ -38,6 +38,7 @@ import { StringDecoder } from 'node:string_decoder';
 import { atomicWriteFile } from '../utils/atomic-write.js';
 import { isRecord } from '../utils/guards.js';
 import { sha256Hex } from '../utils/hashing.js';
+import { UNDO_DONE_FILE_NAME, UNDO_JOURNAL_FILE_NAME } from './rollback-undo-journal.js';
 /* ------------------------------------------------------------------ 常量 */
 /** 清单格式版本（与**记录**的 schemaVersion 无关：后者是记录内容的版本，恒为 2） */
 export const ROLLBACK_LEDGER_SCHEMA_VERSION = 3;
@@ -300,6 +301,28 @@ function isProcessAlive(pid) {
  *  3. 该 pid 进程已不存在（崩溃残留）—— 仍然活着的进程可能正在写，绝不抢。
  * 只扫根目录与它的一级子目录（records/ payloads/ objects/），不递归。
  */
+/**
+ * 这个 undo 目录是不是「**回退写到一半就没了**」的现场（有 journal 索引、但没有 done 标记）。
+ *
+ * 判据必须与 journal 模块**同一份常量**（import 而不是抄字面量）：名字改了这里要跟着改，否则
+ * 要么把现场当垃圾删掉（灾难），要么永远不清残留（垃圾堆积）。
+ */
+async function hasUnfinishedJournal(dir) {
+    try {
+        await fs.access(path.join(dir, UNDO_DONE_FILE_NAME));
+        return false;
+    }
+    catch {
+        /* 没有 done：再看有没有 journal 索引 */
+    }
+    try {
+        await fs.access(path.join(dir, UNDO_JOURNAL_FILE_NAME));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 export async function cleanupOrphanTempFiles(root) {
     const out = { removed: 0, bytes: 0, skipped: 0 };
     let dirs;
@@ -372,6 +395,20 @@ export async function cleanupOrphanTempFiles(root) {
                 continue;
             }
             const target = path.join(undoRoot, name);
+            // **例外（2026-10-18）**：有 journal 却没有 done ⇒ 这不是垃圾，是「回退写到一半进程就没了」
+            // 的现场。必须留住：既能被 findInterruptedUndos 认出来，也能按 after 镜像安全重放
+            //（把工作区退回回退前）。删掉它 = 让半回退的工作区变成无人知晓的残留。
+            try {
+                if (await hasUnfinishedJournal(target)) {
+                    out.skipped += 1;
+                    continue;
+                }
+            }
+            catch {
+                // 判据自己读不出来 ⇒ **不碰**（宁可留垃圾，也不删可能还能救命的现场）
+                out.skipped += 1;
+                continue;
+            }
             try {
                 const bytes = await dirBytes(target);
                 await fs.rm(target, { recursive: true, force: true });

package/lib/core/rollback-merge.d.ts

@@ -1,5 +1,6 @@
+import { type TextShape } from './text-fidelity.ts';
 /** 合并结论（`ok:false` 时调用方必须**零写入**） */
-export type ThreeWayMergeReason = 'clean' | 'conflict' | 'degraded' | 'binary';
+export type ThreeWayMergeReason = 'clean' | 'conflict' | 'degraded' | 'binary' | 'non-utf8';
 export interface ThreeWayMergeResult {
     /** true = 结果可直接写入；false = 必须放弃写入并如实报告 */
     ok: boolean;
@@ -12,11 +13,30 @@ export interface ThreeWayMergeResult {
     revertedLines: number;
     /** 依赖风险提示（启发式；空数组 = 未发现明显风险，**不代表安全**） */
     risks: string[];
+    /**
+     * 输出的**字节形态**（判据 3/5）：落盘必须用 encodeTextBytes(result.text, result.shape) ——
+     * result.text 里**不含** BOM，BOM 由 shape.bom 承载。
+     */
+    shape: TextShape;
+    /** 输入里出现过**不止一种行尾风格**（单个文件内混合 / 各侧风格不同）⇒ 输出的行尾已被统一，不谎称「原样」 */
+    eolMixed: boolean;
+    /** 输出的行尾**不再逐字节等于输入**（含「显式 shape 与输入风格不同」）⇒ 行尾被改写，绝不静默 */
+    eolRewritten: boolean;
 }
 /**
  * 三方合并（纯函数、无 I/O）。
  *
+ * **文本保真（2026-10-18 缺陷：旧实现用 join('\n') 收尾 ⇒ 把整份 CRLF 文件转成 LF）**：
+ *  · 形态（EOL / BOM）显式给了 options.shape 就按它；没给就从 **theirs 探测**（磁盘上真实的那一侧），
+ *    绝不擅自把 CRLF 改成 LF。落在未变更区域的行取自 base，且只含**行内容**（不含行尾），输出统一按
+ *    shape.eol 收尾 —— 输入行尾若与输出不一致，用 eolMixed / eolRewritten 如实标注，不假装「原样」。
+ *  · 输入按契约是**已解码文本**（BOM 已由 decodeTextBytes 剥离）；残留的前导 U+FEFF 会被剥掉并记进
+ *    shape.bom，免得调用方 encode 时写出双 BOM。落盘必须用 encodeTextBytes(result.text, result.shape)。
+ *  · 输入若含孤立代理项或孤立 CR（TextShape 表达不了的形态）⇒ reason='non-utf8'，**零写入**。
+ *
  * 语义：结果是 `ours` 上再应用 `(theirs - base)` —— 撤销「我们从 base 改到 ours 的那部分」，
  * 同时保留「别人从 base 改到 theirs 的那部分」。
  */
-export declare function mergeThreeWay(ours: string, base: string, theirs: string): ThreeWayMergeResult;
+export declare function mergeThreeWay(ours: string, base: string, theirs: string, options?: {
+    shape?: TextShape;
+}): ThreeWayMergeResult;

package/lib/core/rollback-merge.js

@@ -22,6 +22,7 @@
  *     给出**启发式**风险提示（`risks`）—— 它不构成「删除不安全」的证明，也绝不因此声称合并正确。
  */
 import { diffLines, looksBinary } from '../utils/line-diff.js';
+import { isUtf8RoundTrippable, probeTextForm } from './text-fidelity.js';
 /** 标识符取样用的最小长度（太短的词（i、id）同名词满天飞，只会制造噪声） */
 const RISK_TOKEN_MIN = 4;
 /** 不参与依赖提示的通用词（语言关键字 / 极常见标识符） */
@@ -113,33 +114,77 @@ function riskTokens(lines) {
     }
     return [...seen];
 }
+/** 合并输入必须是「UTF-8 往返安全 + 行尾可无损表示」的文本（否则绝不合并、绝不写回） */
+function isMergableInput(text) {
+    return isUtf8RoundTrippable(text) && probeTextForm(text).loneCr === 0;
+}
+/** 剥掉**一个**前导 U+FEFF（BOM 由 shape.bom 承载，正文里不该再残留它） */
+function stripBomPrefix(text) {
+    return text.startsWith('\uFEFF') ? text.slice(1) : text;
+}
 /**
  * 三方合并（纯函数、无 I/O）。
  *
+ * **文本保真（2026-10-18 缺陷：旧实现用 join('\n') 收尾 ⇒ 把整份 CRLF 文件转成 LF）**：
+ *  · 形态（EOL / BOM）显式给了 options.shape 就按它；没给就从 **theirs 探测**（磁盘上真实的那一侧），
+ *    绝不擅自把 CRLF 改成 LF。落在未变更区域的行取自 base，且只含**行内容**（不含行尾），输出统一按
+ *    shape.eol 收尾 —— 输入行尾若与输出不一致，用 eolMixed / eolRewritten 如实标注，不假装「原样」。
+ *  · 输入按契约是**已解码文本**（BOM 已由 decodeTextBytes 剥离）；残留的前导 U+FEFF 会被剥掉并记进
+ *    shape.bom，免得调用方 encode 时写出双 BOM。落盘必须用 encodeTextBytes(result.text, result.shape)。
+ *  · 输入若含孤立代理项或孤立 CR（TextShape 表达不了的形态）⇒ reason='non-utf8'，**零写入**。
+ *
  * 语义：结果是 `ours` 上再应用 `(theirs - base)` —— 撤销「我们从 base 改到 ours 的那部分」，
  * 同时保留「别人从 base 改到 theirs 的那部分」。
  */
-export function mergeThreeWay(ours, base, theirs) {
+export function mergeThreeWay(ours, base, theirs, options) {
+    // 形态：显式优先；未显式给出时从 theirs 探测（主导 EOL + BOM 前缀）。
+    const oursForm = probeTextForm(ours);
+    const baseForm = probeTextForm(base);
+    const theirsForm = probeTextForm(theirs);
+    const hadBom = oursForm.bom || baseForm.bom || theirsForm.bom;
+    const eol = options?.shape?.eol ?? theirsForm.eol;
+    // 显式形态优先；但输入侧确实带过 BOM 时绝不静默丢弃（丢 BOM 属内容改动）
+    const shape = { eol, bom: options?.shape ? options.shape.bom || hadBom : hadBom };
+    const styles = new Set();
+    for (const form of [oursForm, baseForm, theirsForm]) {
+        for (const style of form.eols)
+            styles.add(style);
+    }
+    /** 输入里出现过不止一种行尾风格 */
+    const eolMixed = styles.size > 1;
+    /** 输出的行尾不再逐字节等于输入（已被统一） */
+    const eolRewritten = eolMixed || (styles.size === 1 && !styles.has(eol));
+    // ok:false 时 text 一律是**调用方给的 theirs 原文**（绝不落入半截合并结果）
     const empty = (reason, conflicts = 0, risks = []) => ({
-        ok: false, text: theirs, reason, conflicts, revertedLines: 0, risks,
+        ok: false, text: theirs, reason, conflicts, revertedLines: 0, risks, shape, eolMixed, eolRewritten,
     });
     // 没有基线就退化成「谁的改动都不认识」—— 调用方负责在无 base 时根本不调用本函数
     if (looksBinary(base) || looksBinary(ours) || looksBinary(theirs))
         return empty('binary');
-    if (ours === base) {
+    // 非法 / 无法无损表示的文本：孤立代理项（encode 时会被替换成 U+FFFD）、孤立 CR（行尾表示不了）
+    if (![ours, base, theirs].every(isMergableInput))
+        return empty('non-utf8');
+    // 前导 U+FEFF 归 shape.bom 管；正文里剥掉它，免得它被当成「行内容」混进 diff
+    const oursText = stripBomPrefix(ours);
+    const baseText = stripBomPrefix(base);
+    const theirsText = stripBomPrefix(theirs);
+    const clean = (text) => ({
+        ok: true, text, reason: 'clean', conflicts: 0, revertedLines: 0, risks: [], shape, eolMixed, eolRewritten,
+    });
+    if (oursText === baseText) {
         // 本会话没改过 ⇒ 结论就是「保持别人现在的内容」（不是失败）
-        return { ok: true, text: theirs, reason: 'clean', conflicts: 0, revertedLines: 0, risks: [] };
+        return clean(theirsText);
     }
-    if (theirs === base) {
+    if (theirsText === baseText) {
         // 别人没改过 ⇒ 直接回到 ours
-        return { ok: true, text: ours, reason: 'clean', conflicts: 0, revertedLines: 0, risks: [] };
+        return clean(oursText);
     }
-    if (ours === theirs) {
+    if (oursText === theirsText) {
         // 双方最终内容一致 ⇒ 谁都不用动
-        return { ok: true, text: theirs, reason: 'clean', conflicts: 0, revertedLines: 0, risks: [] };
+        return clean(theirsText);
     }
-    const oursBlocks = changeBlocks(base, ours);
-    const theirsBlocks = changeBlocks(base, theirs);
+    const oursBlocks = changeBlocks(baseText, oursText);
+    const theirsBlocks = changeBlocks(baseText, theirsText);
     if (oursBlocks === null || theirsBlocks === null)
         return empty('degraded');
     // 冲突扫描：任一 ours 块与任一 theirs 块触碰且内容不同 ⇒ 冲突
@@ -155,7 +200,7 @@ export function mergeThreeWay(ours, base, theirs) {
     }
     if (conflicts > 0)
         return empty('conflict', conflicts);
-    const baseLines = splitLinesOf(base);
+    const baseLines = splitLinesOf(baseText);
     const merged = [];
     const reverted = [];
     let cursor = 0;
@@ -183,12 +228,17 @@ export function mergeThreeWay(ours, base, theirs) {
     }
     for (let i = cursor; i < baseLines.length; i += 1)
         merged.push(baseLines[i]);
+    // 行尾统一按 shape.eol 收尾（混合 / 被改写的行尾已由 eolMixed / eolRewritten 如实标注）；
     // 尾换行以**当前磁盘**（theirs）为准：我们是在它的基础上撤销本会话的改动，不擅改它原本的收尾形态
-    const text = merged.join('\n') + (merged.length > 0 && theirs.endsWith('\n') ? '\n' : '');
+    const tail = merged.length > 0 && theirsText.endsWith('\n') ? eol : '';
+    const text = merged.join(eol) + tail;
     // 依赖风险（启发式）：被撤销的行里出现过、且合并结果里仍能读到的标识符
     const tokens = riskTokens(reverted);
     const risks = tokens.filter((token) => new RegExp('\\b' + token + '\\b').test(text)).slice(0, 8);
-    return { ok: true, text, reason: 'clean', conflicts: 0, revertedLines: reverted.length, risks };
+    return {
+        ok: true, text, reason: 'clean', conflicts: 0, revertedLines: reverted.length, risks,
+        shape, eolMixed, eolRewritten,
+    };
 }
 /** 与 `splitLines` 同口径的本地折行（避免为了一个函数再引一层依赖） */
 function splitLinesOf(text) {