dsh-config-manager 0.1.78 → 0.1.80

package/src/core/rollback-interrupted.test.ts

@@ -0,0 +1,137 @@
+/**
+ * 中断的回退（2026-10-18）：进程在「回退写到一半」时没了。
+ *
+ * 纪律：真实临时目录 + 真实读写；**不 mock 文件系统** —— 本组用例要证的正是「磁盘上留下了什么」。
+ *
+ * 现场形状：<dataDir>/rollback-points/undo/<pid>-<ts36>-<8hex>/ 里有 journal.jsonl（逐条前像 +
+ * after 镜像 + 路径），**没有 done**，且目录名里的 pid 已经死了。
+ *
+ * 三件事各自成文：
+ *  · I-1：这种目录**不得**被 cleanupOrphanTempFiles 当垃圾删掉（它还可能救命）；落 done 之后照旧清。
+ *  · I-2：恢复只在「当前内容仍等于 after 镜像」时写回 ⇒ 之后被改过的文件**跳过**、绝不覆盖。
+ *  · I-3：全部条目都自证成立 ⇒ 恢复成功、现场清掉。
+ */
+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 { RollbackPointEngine } from './rollback-point.ts'
+import { cleanupOrphanTempFiles } from './rollback-ledger.ts'
+import { UNDO_DONE_FILE_NAME, UndoJournalWriter } from './rollback-undo-journal.ts'
+import { sha256Hex } from '../utils/hashing.ts'
+
+/** 目录名里的 pid 必须「已死」：取一个超出常见 pid 上限的值（Windows/Linux 都会 ESRCH） */
+const DEAD_PID = 4294967
+
+interface Fixture { root: string; dataDir: string; homeDir: string; ws: string; cleanup: () => Promise<void>; undoDir: (name: string) => string }
+
+async function makeFixture(): Promise<Fixture> {
+  const root = await fs.realpath(await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-cm-interrupted-')))
+  const homeDir = path.join(root, 'home')
+  const dataDir = path.join(homeDir, 'dsh-config-manager')
+  const ws = path.join(root, 'ws')
+  await fs.mkdir(ws, { recursive: true })
+  const storeDir = path.join(dataDir, 'rollback-points')
+  return {
+    root, dataDir, homeDir, ws,
+    cleanup: async () => { await fs.rm(root, { recursive: true, force: true }) },
+    undoDir: (name: string) => path.join(storeDir, 'undo', name),
+  }
+}
+
+function makeEngine(fx: Fixture): RollbackPointEngine {
+  return new RollbackPointEngine({ dataDir: fx.dataDir, homeDir: fx.homeDir, sessionQuiescentMs: 0 })
+}
+
+/** 造一个「回退写到一半」的现场：逐条前像 + after 镜像，**不落 done** */
+async function makeInterrupted(
+  fx: Fixture,
+  name: string,
+  entries: { target: string; before: Uint8Array | null; after: { sha256: string } | { deleted: true } }[],
+): Promise<string> {
+  const dir = fx.undoDir(name)
+  await fs.mkdir(dir, { recursive: true })
+  const journal = await UndoJournalWriter.create(dir, { now: () => 5_000_000 })
+  for (const entry of entries) await journal.record(entry.target, entry.before, entry.after)
+  // **有意不调用 finish()** —— 这一行就是「崩在写入中途」
+  return dir
+}
+
+async function exists(target: string): Promise<boolean> {
+  try { await fs.access(target); return true } catch { return false }
+}
+
+test('I-1 中断的回退现场：不得被孤儿清理删掉；落 done 之后照旧清', async (t) => {
+  const fx = await makeFixture()
+  t.after(fx.cleanup)
+  const file = path.join(fx.ws, 'a.txt')
+  await fs.writeFile(file, 'AFTER')
+  const dir = await makeInterrupted(fx, DEAD_PID + '-abc1234-0123abcd', [
+    { target: file, before: Buffer.from('BEFORE'), after: { sha256: sha256Hex(Buffer.from('AFTER')) } },
+  ])
+
+  const cleaned = await cleanupOrphanTempFiles(path.join(fx.dataDir, 'rollback-points'))
+  assert.equal(await exists(dir), true,
+    '有 journal 但没有 done ⇒ 那是「回退写到一半」的现场，绝不能被当垃圾删掉（removed=' + String(cleaned.removed) + '）')
+
+  const engine = makeEngine(fx)
+  const list = await engine.interruptedRollbacks()
+  assert.equal(list.length, 1, '必须能被认出来：' + JSON.stringify(list.map((item) => item.dir)))
+  assert.equal(list[0]?.entries.length, 1)
+  assert.equal(list[0]?.entries[0]?.path, file)
+
+  // 落 done 之后它就不再是现场了 ⇒ 照旧按残留清掉（判据是 done，不是「永不删除」）
+  await fs.writeFile(path.join(dir, UNDO_DONE_FILE_NAME), JSON.stringify({ pid: DEAD_PID, finishedAt: 5_000_000 }))
+  const cleaned2 = await cleanupOrphanTempFiles(path.join(fx.dataDir, 'rollback-points'))
+  assert.equal(await exists(dir), false, 'done 已落 ⇒ 可以清（removed=' + String(cleaned2.removed) + '）')
+  assert.equal((await engine.interruptedRollbacks()).length, 0, '清掉之后不再有现场')
+})
+
+test('I-2 恢复只在「当前内容仍等于 after 镜像」时写回：后来被改过的文件一律跳过', async (t) => {
+  const fx = await makeFixture()
+  t.after(fx.cleanup)
+  const mine = path.join(fx.ws, 'mine.txt')
+  const touched = path.join(fx.ws, 'touched.txt')
+  await fs.writeFile(mine, 'AFTER')
+  await fs.writeFile(touched, 'AFTER')
+  const dir = await makeInterrupted(fx, DEAD_PID + '-def5678-fedcba98', [
+    { target: mine, before: Buffer.from('BEFORE'), after: { sha256: sha256Hex(Buffer.from('AFTER')) } },
+    { target: touched, before: Buffer.from('BEFORE'), after: { sha256: sha256Hex(Buffer.from('AFTER')) } },
+  ])
+  // 崩溃之后、恢复之前：这条被外部改过 ⇒ 它的当前内容不再等于 after 镜像
+  await fs.writeFile(touched, 'AFTER-BUT-EDITED-LATER')
+
+  const engine = makeEngine(fx)
+  const result = await engine.recoverInterruptedRollback(dir)
+  assert.equal(await fs.readFile(mine, 'utf8'), 'BEFORE', '自证成立的条目必须被写回（退回回退前）')
+  assert.equal(await fs.readFile(touched, 'utf8'), 'AFTER-BUT-EDITED-LATER',
+    '**绝不覆盖**比我们新的内容：observed=' + JSON.stringify(await fs.readFile(touched, 'utf8')))
+  assert.equal(result.restored, 1)
+  assert.equal(result.skipped.length, 1, '跳过的条目必须逐条报出来：' + JSON.stringify(result.skipped))
+  assert.equal(result.ok, false)
+  assert.equal(await exists(dir), true, '没全成功 ⇒ 现场留着（可以再看、再试）')
+})
+
+test('I-3 全部条目都自证成立 ⇒ 恢复成功并清掉现场', async (t) => {
+  const fx = await makeFixture()
+  t.after(fx.cleanup)
+  const file = path.join(fx.ws, 'a.txt')
+  await fs.writeFile(file, 'AFTER')
+  const gone = path.join(fx.ws, 'created-by-rewind.txt')
+  await fs.writeFile(gone, 'x')  // 回退动作当时**删除**了它 ⇒ after = deleted；恢复时它必须不存在
+  await fs.rm(gone)
+  const dir = await makeInterrupted(fx, DEAD_PID + '-aaa1111-1111aaaa', [
+    { target: file, before: Buffer.from('BEFORE'), after: { sha256: sha256Hex(Buffer.from('AFTER')) } },
+    { target: gone, before: Buffer.from('CAME-BACK'), after: { deleted: true } },
+  ])
+
+  const engine = makeEngine(fx)
+  const result = await engine.recoverInterruptedRollback(dir)
+  assert.equal(result.ok, true, JSON.stringify(result))
+  assert.equal(result.restored, 2)
+  assert.equal(await fs.readFile(file, 'utf8'), 'BEFORE')
+  assert.equal(await fs.readFile(gone, 'utf8'), 'CAME-BACK', '被回退删掉的路径必须被写回')
+  assert.equal(await exists(dir), false, '全部成功 ⇒ 现场清掉')
+})

package/src/core/rollback-ledger.ts

@@ -39,6 +39,7 @@ import { StringDecoder } from 'node:string_decoder'
 import { atomicWriteFile } from '../utils/atomic-write.ts'
 import { isRecord } from '../utils/guards.ts'
 import { sha256Hex } from '../utils/hashing.ts'
+import { UNDO_DONE_FILE_NAME, UNDO_JOURNAL_FILE_NAME } from './rollback-undo-journal.ts'
 import type {
   RollbackCode,
   RollbackPointKind,
@@ -413,6 +414,27 @@ function isProcessAlive(pid: number): boolean {
  *  3. 该 pid 进程已不存在（崩溃残留）—— 仍然活着的进程可能正在写，绝不抢。
  * 只扫根目录与它的一级子目录（records/ payloads/ objects/），不递归。
  */
+/**
+ * 这个 undo 目录是不是「**回退写到一半就没了**」的现场（有 journal 索引、但没有 done 标记）。
+ *
+ * 判据必须与 journal 模块**同一份常量**（import 而不是抄字面量）：名字改了这里要跟着改，否则
+ * 要么把现场当垃圾删掉（灾难），要么永远不清残留（垃圾堆积）。
+ */
+async function hasUnfinishedJournal(dir: string): Promise<boolean> {
+  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: string): Promise<RollbackTempCleanupResult> {
   const out: RollbackTempCleanupResult = { removed: 0, bytes: 0, skipped: 0 }
   let dirs: string[]
@@ -465,6 +487,16 @@ export async function cleanupOrphanTempFiles(root: string): Promise<RollbackTemp
       const pid = Number(m[1])
       if (pid === process.pid || isProcessAlive(pid)) { out.skipped += 1; 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/src/core/rollback-merge.test.ts

@@ -8,6 +8,7 @@ import test from 'node:test'
 import assert from 'node:assert/strict'
 
 import { mergeThreeWay } from './rollback-merge.ts'
+import { encodeTextBytes } from './text-fidelity.ts'
 
 test('M-1 不同区域：撤销 ours 的改动、保留 theirs 的改动', () => {
   const ours = ['function main() {', '  const a = 1', '  const b = 2', '  log(a + b)', '}'].join('\n') + '\n'
@@ -131,3 +132,132 @@ test('M-13 插入点落在被删区间**内部** ⇒ 仍然是冲突', () => {
   assert.equal(r.ok, false)
   assert.equal(r.reason, 'conflict')
 })
+
+/* ── 2026-10-18 文本保真缺陷（CRLF 被折断 / BOM / 非 UTF-8 写回）的回归 ── */
+
+test('M-14 CRLF 文件：撤销本会话改动后**行尾仍是 CRLF**（旧实现会把整份文件折成 LF）', () => {
+  const base = 'a\r\nKEEP\r\nDOOMED\r\nx\r\n'
+  const ours = 'a\r\nKEEP\r\nx\r\n' // 本会话删掉了 DOOMED
+  const theirs = 'a\r\nKEEP\r\nDOOMED\r\nX2\r\n' // 别人改了尾行
+  const r = mergeThreeWay(ours, base, theirs)
+  assert.equal(r.ok, true, r.reason)
+  assert.deepEqual(r.shape, { eol: '\r\n', bom: false })
+  assert.equal(r.text, 'a\r\nKEEP\r\nX2\r\n')
+  assert.equal(r.eolMixed, false)
+  assert.equal(r.eolRewritten, false)
+  // 旧实现产出 'a\nKEEP\nX2\n'：这里直接查「前面不是 CR 的 LF」——那正是被折过的证据
+  assert.equal(/[^\r]\n/.test(r.text), false, '不得出现被折成 LF 的行尾')
+  assert.equal(r.revertedLines, 1)
+})
+
+test('M-15 CRLF 且磁盘没有尾换行 ⇒ 输出同样不补尾换行（尾换行跟随 theirs）', () => {
+  const base = 'a\r\nb\r\nc\r\n'
+  const ours = 'a\r\nO1\r\nc\r\n'
+  const theirs = 'a\r\nb\r\nC2'
+  const r = mergeThreeWay(ours, base, theirs)
+  assert.equal(r.ok, true, r.reason)
+  assert.deepEqual(r.shape, { eol: '\r\n', bom: false })
+  assert.equal(r.text, 'a\r\nO1\r\nC2')
+  assert.equal(r.text.endsWith('\n'), false, '磁盘没有尾换行就不擅自补')
+})
+
+test('M-16 显式 shape 优先（判据 3）：CRLF 输入也能按 LF 输出，并如实标注行尾被改写', () => {
+  const base = 'a\r\nb\r\n'
+  const ours = 'a\r\nO\r\n'
+  const theirs = 'a\r\nb\r\nT\r\n'
+  const r = mergeThreeWay(ours, base, theirs, { shape: { eol: '\n', bom: false } })
+  assert.equal(r.ok, true, r.reason)
+  assert.equal(r.shape.eol, '\n')
+  assert.equal(r.eolRewritten, true, '与输入风格不同 ⇒ 必须如实标注')
+  assert.equal(r.text, 'a\nO\nT\n')
+})
+
+test('M-17 混合行尾：按 theirs 的主导 EOL 输出，并如实标注 eolMixed（判据 5）', () => {
+  const base = 'a\r\nb\r\nc\r\n'
+  const ours = 'a\r\nO\r\nc\r\n'
+  const theirs = 'a\r\nb\r\nT\r\nU\n'
+  const r = mergeThreeWay(ours, base, theirs)
+  assert.equal(r.ok, true, r.reason)
+  assert.equal(r.shape.eol, '\r\n', '2 个 CRLF 对 1 个 LF ⇒ 主导 CRLF')
+  assert.equal(r.eolMixed, true, '输入里出现两种行尾 ⇒ 必须标注')
+  assert.equal(r.eolRewritten, true)
+  assert.equal(r.text, 'a\r\nO\r\nT\r\nU\r\n')
+})
+
+test('M-18 BOM：前导 U+FEFF 归 shape 承载（正文不残留），encode 后逐字节复原', () => {
+  const base = '\uFEFFa\nb\n'
+  const ours = '\uFEFFa\nO\n'
+  const theirs = '\uFEFFa\nb\nT\n'
+  const r = mergeThreeWay(ours, base, theirs)
+  assert.equal(r.ok, true, r.reason)
+  assert.equal(r.shape.bom, true, '不得静默丢 BOM')
+  assert.equal(r.text.startsWith('\uFEFF'), false, '正文里不残留 BOM 字符（否则 encode 会写出双 BOM）')
+  assert.equal(r.text, 'a\nO\nT\n')
+  assert.deepEqual(
+    [...encodeTextBytes(r.text, r.shape)],
+    [...new TextEncoder().encode('\uFEFFa\nO\nT\n')],
+    '带 shape 落盘必须逐字节复原（含 BOM）',
+  )
+})
+
+test('M-19 孤立代理项（无法 UTF-8 无损编码）⇒ reason=non-utf8、ok=false、回落 theirs', () => {
+  const r = mergeThreeWay('a\n\uD83D\n', 'a\nb\n', 'a\nb\nT\n')
+  assert.equal(r.ok, false)
+  assert.equal(r.reason, 'non-utf8')
+  assert.equal(r.text, 'a\nb\nT\n', 'ok:false 时 text 一律是 theirs 原文（供比较，绝不写入）')
+})
+
+test('M-20 孤立 CR（TextShape 表示不了）⇒ reason=non-utf8，绝不悄悄改成 LF', () => {
+  const ours = 'a\rO\r'
+  const r = mergeThreeWay(ours, 'a\rb\r', 'a\rb\rT\r')
+  assert.equal(r.ok, false)
+  assert.equal(r.reason, 'non-utf8')
+  assert.equal(r.text, 'a\rb\rT\r')
+})
+
+test('M-21 每个分支都带 shape / eolMixed / eolRewritten（调用方无需猜）', () => {
+  const binary = mergeThreeWay('x\n', 'a\u0000b\n', 'y\n')
+  assert.equal(binary.reason, 'binary')
+  assert.deepEqual(binary.shape, { eol: '\n', bom: false })
+  const conflict = mergeThreeWay('a\nB-o\nc\n', 'a\nb\nc\n', 'a\nB-t\nc\n')
+  assert.equal(conflict.reason, 'conflict')
+  assert.deepEqual(conflict.shape, { eol: '\n', bom: false })
+  assert.equal(conflict.text, 'a\nB-t\nc\n')
+  const clean = mergeThreeWay('a\nb\n', 'a\nb\n', 'a\nb\nT\n')
+  assert.equal(clean.reason, 'clean')
+  assert.deepEqual(clean.shape, { eol: '\n', bom: false })
+  assert.equal(clean.eolMixed, false)
+  assert.equal(clean.eolRewritten, false)
+})
+
+test('M-22 未传 shape ⇒ 从 theirs 探测形态（不是拿 base / ours 猜）', () => {
+  const base = 'a\nb\n'
+  const ours = 'a\nO\n'
+  const theirs = 'a\r\nb\r\nT\r\n'
+  const r = mergeThreeWay(ours, base, theirs)
+  assert.equal(r.ok, true, r.reason)
+  assert.deepEqual(r.shape, { eol: '\r\n', bom: false })
+  assert.equal(r.eolMixed, true, 'base/ours 是 LF、theirs 是 CRLF ⇒ 如实标注风格不一致')
+  assert.equal(r.text, 'a\r\nO\r\nT\r\n')
+})
+
+test('M-23 空文件 / 空 theirs：不凭空行、不补尾换行、不失败', () => {
+  const both = mergeThreeWay('', 'a\n', '')
+  assert.equal(both.ok, true)
+  assert.equal(both.text, '')
+  assert.equal(mergeThreeWay('a\r\nb\r\n', 'a\r\nb\r\n', '').text, '', 'theirs 为空 ⇒ 结果也为空')
+  assert.equal(mergeThreeWay('a\nb', 'a\nb\n', 'a\nb\nT\n').ok, true)
+})
+
+test('M-24 BOM + CRLF + 中文 端到端：合并结果 encode 后逐字节符合原形态', () => {
+  const base = '\uFEFF第一行\r\n第二行\r\n尾行\r\n'
+  const ours = '\uFEFF第一行\r\n尾行\r\n'
+  const theirs = '\uFEFF第一行\r\n第二行\r\n尾行2\r\n'
+  const r = mergeThreeWay(ours, base, theirs)
+  assert.equal(r.ok, true, r.reason)
+  assert.deepEqual(r.shape, { eol: '\r\n', bom: true })
+  assert.deepEqual(
+    [...encodeTextBytes(r.text, r.shape)],
+    [...new TextEncoder().encode('\uFEFF第一行\r\n尾行2\r\n')],
+  )
+})

package/src/core/rollback-merge.ts

@@ -22,9 +22,10 @@
  *     给出**启发式**风险提示（`risks`）—— 它不构成「删除不安全」的证明，也绝不因此声称合并正确。
  */
 import { diffLines, looksBinary } from '../utils/line-diff.ts'
+import { isUtf8RoundTrippable, probeTextForm, type TextEol, 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 = 必须放弃写入并如实报告 */
@@ -38,6 +39,15 @@ 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
 }
 
 /** 一处变更块：base 的 `[start, end)` 行被替换成 `lines`（空区间 = 纯插入） */
@@ -131,32 +141,81 @@ function riskTokens(lines: readonly string[]): string[] {
   return [...seen]
 }
 
+/** 合并输入必须是「UTF-8 往返安全 + 行尾可无损表示」的文本（否则绝不合并、绝不写回） */
+function isMergableInput(text: string): boolean {
+  return isUtf8RoundTrippable(text) && probeTextForm(text).loneCr === 0
+}
+
+/** 剥掉**一个**前导 U+FEFF（BOM 由 shape.bom 承载，正文里不该再残留它） */
+function stripBomPrefix(text: string): string {
+  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: string, base: string, theirs: string): ThreeWayMergeResult {
+export function mergeThreeWay(
+  ours: string,
+  base: string,
+  theirs: string,
+  options?: { shape?: TextShape },
+): ThreeWayMergeResult {
+  // 形态：显式优先；未显式给出时从 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: TextEol = options?.shape?.eol ?? theirsForm.eol
+  // 显式形态优先；但输入侧确实带过 BOM 时绝不静默丢弃（丢 BOM 属内容改动）
+  const shape: TextShape = { eol, bom: options?.shape ? options.shape.bom || hadBom : hadBom }
+  const styles = new Set<TextEol>()
+  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: ThreeWayMergeReason, conflicts = 0, risks: string[] = []): ThreeWayMergeResult => ({
-    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: string): ThreeWayMergeResult => ({
+    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 块触碰且内容不同 ⇒ 冲突
@@ -170,7 +229,7 @@ export function mergeThreeWay(ours: string, base: string, theirs: string): Three
   }
   if (conflicts > 0) return empty('conflict', conflicts)
 
-  const baseLines = splitLinesOf(base)
+  const baseLines = splitLinesOf(baseText)
   const merged: string[] = []
   const reverted: string[] = []
   let cursor = 0
@@ -194,13 +253,18 @@ export function mergeThreeWay(ours: string, base: string, theirs: string): Three
     cursor = Math.max(cursor, block.end)
   }
   for (let i = cursor; i < baseLines.length; i += 1) merged.push(baseLines[i] as string)
+  // 行尾统一按 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` 同口径的本地折行（避免为了一个函数再引一层依赖） */