dsh-gokifu-compact 1.11.7 → 1.11.9

package/CHANGELOG.md

@@ -1,5 +1,95 @@
 # 更新记录
 
+## 1.11.9 — 2026-10-31
+
+### 发布脚本新增门禁：CHANGELOG 写的「N 个测试文件」必须等于事实
+
+**这条门禁上线当天就抓到了真实漂移**：CHANGELOG 从 1.11.5 起一直写着同一个旧数字（**37**），
+实际早就是 **42** —— 连续几个版本没人对过账（它不影响构建，所以从来不会自己叫）。
+
+**新增（`scripts/release-lib.mjs`，纯逻辑、可单测）**
+
+| 导出 | 行为 |
+|---|---|
+| `declaredTestFiles(section)` | 读「N 个测试文件」；**没写返回 `null`**；容错 `**42** 个测试文件` / `（42 个测试文件；493 + 7）` / `42个测试文件` |
+| `checkTestFileCount(section, actual)` | **三态**：一致放行 / 不一致给出 `{declared, actual, reason}` / 无声明放行 |
+
+**`scripts/release.mjs` 体检 ②b**：当前版本那一节的数字 ≠ `test/*.test.mjs` 实际数 ⇒ **红，`--yes` 也不动手**；
+**没写这句不报错**（允许不声明）。红文案同时给出两个数与「怎么数」（含历史版本数法）：
+
+```
+· CHANGELOG 写的「N 个测试文件」与实际 42 个不符 —— 改了测试文件就必须同步这句（或删掉它，脚本不会因此报错）。
+  实际值怎么数：ls test/*.test.mjs | wc -l（看历史版本：git ls-tree -r --name-only <tag>^{commit} test/ | grep -c '\.test\.mjs$'）
+```
+
+### 顺带修掉两个「只在预演期才撞到」的发布脚本缺陷
+
+写这条门禁时跑 dry-run，脚本**直接崩了**，顺藤摸出两个真缺陷（都不影响发版那一刻，但会让「已发版本上再跑一次预演」变成堆栈）：
+
+1. **tag 已存在时 dry-run 崩**：`git rev-parse -q --verify refs/tags/x^{commit}` —— Windows 上 `execSync` 走 **cmd.exe**，
+   `^` 是转义字符 ⇒ 被吃成 `{commit}`，命令失败抛异常（手动在 Git Bash 里跑同一命令是好的，极难从表面看出）。
+   改用 `git rev-list -n1 refs/tags/<tag>`（无 shell 元字符，annotated / lightweight 都剥到 commit）+ try/catch。
+2. **「tag 指向别的 commit」误报**：给 `ls-remote` 传**精确 pattern** 时**不会**输出 `^{}` 剥皮行 ⇒ 拿到的是 tag 对象 sha（≠ commit）；
+   而且判据原本是「≠ HEAD」，但「发过之后 main 又往前走了」是**正常态**。改为列全部 tag 再在 JS 里过滤剥皮行，
+   判据改成「**既不是 HEAD 也不是 HEAD 的祖先**」（`git merge-base --is-ancestor`）才报。
+
+### 验证
+
+- 全量：**498 passed / 0 skipped / 0 failed**（**42 个测试文件**；493 + 5 条 `release-hardening`）
+- `release-hardening` **15/0** · `verify-install` **16/16**
+- `npm pack --dry-run --json`：**71 文件**（`test/` 不进包，数量不变）
+- 三态端到端（临时克隆、版本 9.9.9）：声明 37 / 实际 42 ⇒ **exit 1**；**无声明** ⇒ **exit 0**（附跳过说明）；声明 42 ⇒ **exit 0**
+- 仓库记录更正：1.11.8 节的「37」已改为「42」并在原处注明「发布时误写；npm 上已发内容无法改」
+
+**未验证**
+
+- 门禁只校验**当前 `package.json` 版本那一节**；历史各节不追溯。
+- 没把「仓库自洽」做成单测：若在测试套件里断言「当前版本的数字 == 实际数」，每加一个测试文件都会红到下一版
+  （已发布那一节是冻结的）⇒ 这条只在**发布时**才对得起来。
+
+## 1.11.8 — 2026-10-31
+
+### sidecar 现在能**回灌**：归档掉的悬空边可以放回图里
+
+1.11.1 起 `migrate-dangling --apply` 把 settled residue 归档到 `graph.dangling.json`（sidecar），
+**但一直没有回灌工具** —— 报告里写「字段齐全、可回灌」，实际只能靠人手写 JSON。这一版把这条路补完。
+
+**新增（R14 `src/rooms/migrate.mjs`）**
+
+| 导出 | 作用 |
+|---|---|
+| `readSidecar(file)` | 读 + 校验：`format` / `version` / **非空 `edges`** / 每条边必须有 `id` / 会话匹配；**坏文件一律拒绝且不动图** |
+| `mergeSidecar(graph, sidecar, opts)` | 按 `edge.id` 合并；**同 id 跳过、不覆盖**；保留 sidecar 原字段；**原子写 `graph.json` + 重建 `index.md`** |
+| `mergeMany(target, opts)` | 目标可以是**文件或目录**；批量 |
+| `mergeBackupDir(opts)` | 回灌前先备份 `graph.json` / `index.md` 并落 `MERGE.json` |
+
+- **默认 dry-run**：只有 `--apply` 才写盘；**幂等** —— 二次 merge 0 条命中且**不写盘**。
+- CLI：`--merge-sidecar=<file|dir> [--apply] [--backup-dir=] [--json]`；有错误 **exit 1**。
+
+**CLI 摘要（`scripts/migrate-dangling.mjs`）**
+
+- 修掉 `main()` 里 merge 分支的**重复执行链**（只留 `mergeMany`，错误 exit 1），人类摘要移到输出链。
+- 无 `--json` 时打印：标题 / target / `sessions|merged|skipped` / 逐会话行 / backup 目录 / errors / dry-run 或已回灌提示；
+  **`--json` 仍是纯 JSON**（可 `JSON.parse`）。
+- `mergeMany`：目标不存在时**直接报「目标不存在」**（不再默默去读 `./graph.json`）。
+
+**测试 +7**（486 → 493）
+
+- M1 回灌与备份 · M2 幂等 · M3 **五类拒绝**（format/version/空 edges/边无 id/会话不匹配）· M4 同 id 不覆盖 · M5 `mergeMany` 批量
+- C1 **真跑 CLI 六态**（人类摘要 / `--json` / apply 备份 / 幂等 / 坏 version / 目标不存在）· C2 结构回归（merge 分支恰好 2 处）
+- 变异自检：覆盖已存在边 / dry-run 写盘 / 不校验 version / 执行链重复分支 / `--json` 走人类摘要 / 删人类摘要分支 —— 逐条红
+
+### 验证
+
+- 全量：**493 passed / 0 skipped / 0 failed**（**42** 个测试文件 —— 发布时误写 37，此处已按实际更正；npm 上 1.11.8 的 CHANGELOG 仍是 37，无法改）
+- `migrate` **21/0** · `rooms` 15/0 · `verify-install` **16/16**
+- `npm pack --dry-run --json`：**71 文件**（数量不变；只改 `src/` `scripts/` `test/`）
+
+**未验证**
+
+- 回灌**没有对真实库跑过** —— 全部证据来自夹具；真实 `sessions/**` 的 apply 仍需主人授权 + 停插件窗口。
+- 回灌只按 `edge.id` 去重：**同一个「边」若在 sidecar 里 id 不同（历史重复归档），会被当成两条各插一次**。
+
 ## 1.11.7 — 2026-10-31
 
 ### 真实测试与门禁都不再「靠输出猜」

package/README.md

@@ -1,6 +1,6 @@
 # dsh-GOkifu-compact
 
-> 当前版本：**`1.11.7`** · npm [`dsh-gokifu-compact`](https://www.npmjs.com/package/dsh-gokifu-compact) · [GitHub Releases](https://github.com/MYCF711/dsh-GOkifu-compact/releases) · 更新记录见 [CHANGELOG.md](CHANGELOG.md)
+> 当前版本：**`1.11.9`** · npm [`dsh-gokifu-compact`](https://www.npmjs.com/package/dsh-gokifu-compact) · [GitHub Releases](https://github.com/MYCF711/dsh-GOkifu-compact/releases) · 更新记录见 [CHANGELOG.md](CHANGELOG.md)
 
 **DSH 的棋谱式上下文压缩后端 —— 把「历史 → 一段摘要」换成「历史 → 可复盘的棋谱 DAG + 每步只有 351 tokens 的热清单」。**
 
@@ -8,7 +8,7 @@
 热清单     351 tokens       （2000 边合成夹具 · L5 降级档 · 2026-10-30/10-31 两次实测同值；旧版全量 28,800）
 失败保留   8 / 8            （历史口径 †；官方 8 段模板 4.67 / 8）
 清单开销   未复现/待测       （原载 0.2% = 历史单会话 v1.3.1 后实测；无复跑命令、无对照组；源 evidence/真实计费核对.md）
-验证       486 项单测（0 skipped） · 真实包 8/8 † · 真实进程 fold 3~6/6 †
+验证       498 项单测（0 skipped） · 真实包 8/8 † · 真实进程 fold 3~6/6 †
 ```
 
 GO = 围棋，kifu = 棋谱，compact = 压缩。一局棋下完，棋谱上不只有落子顺序，还有每一手的评语。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-gokifu-compact",
-  "version": "1.11.7",
+  "version": "1.11.9",
   "description": "DSH context-compression backend with a go game record (kifu) DAG: node = position, edge = attempted move + result. Incremental fold (each span summarized once), failure memory that survives compaction, transposition detection (chess-engine style), and a tiny hot ledger rebuilt every step.",
   "repository": {
     "type": "git",

package/scripts/migrate-dangling.mjs

@@ -11,6 +11,8 @@
  *   node scripts/migrate-dangling.mjs --apply                # 真执行（先整目录备份；120s 新鲜度守卫）
  *   node scripts/migrate-dangling.mjs --verify --backup=<dir>  # 只读校验
  *   node scripts/migrate-dangling.mjs --rollback=<dir>       # 从备份逐字恢复
+ *   node scripts/migrate-dangling.mjs --merge-sidecar=<file|dir>          # 回灌 sidecar（默认 dry-run）
+ *   node scripts/migrate-dangling.mjs --merge-sidecar=<file|dir> --apply  # 真回灌（备份到 --backup-dir）
  *   --root=<sessionsRoot>  --backup-dir=<dir>  --now=<epochMs>
  *
  * 退出码：0 正常；1 校验失败/执行失败；2 参数错误。
@@ -18,13 +20,13 @@
 
 import nodeFs from "node:fs";
 import nodePath from "node:path";
-import { dryRun, apply, verify, rollback, sessionsRoot, backupsRoot } from "../src/rooms/migrate.mjs";
+import { dryRun, apply, verify, rollback, mergeMany, sessionsRoot, backupsRoot } from "../src/rooms/migrate.mjs";
 
 function parseArgs(argv) {
-  const opts = { mode: "dry-run", json: false, force: false, only: null, root: sessionsRoot(), backupRoot: backupsRoot(), backupDir: "", now: Date.now() };
+  const opts = { mode: "dry-run", json: false, force: false, only: null, root: sessionsRoot(), backupRoot: backupsRoot(), backupDir: "", mergeTarget: "", now: Date.now() };
   for (const arg of argv) {
     if (arg === "--dry-run") opts.mode = "dry-run";
-    else if (arg === "--apply") opts.mode = "apply";
+    else if (arg === "--apply") { opts.applyMerge = true; if (!opts.mergeTarget) opts.mode = "apply"; }
     else if (arg === "--force") opts.force = true;
     else if (arg === "--verify") opts.mode = "verify";
     else if (arg === "--json") opts.json = true;
@@ -34,6 +36,13 @@ function parseArgs(argv) {
     else if (arg.startsWith("--rollback=")) {
       opts.mode = "rollback";
       opts.backupDir = arg.slice("--rollback=".length);
+    } else if (arg.startsWith("--merge-sidecar=")) {
+      opts.mode = "merge";
+      opts.mergeTarget = arg.slice("--merge-sidecar=".length);
+      if (opts.mergeTarget.length === 0) {
+        console.error("--merge-sidecar= 需要一个 sidecar 文件或会话目录");
+        process.exit(2);
+      }
     } else if (arg.startsWith("--sessions=")) {
       opts.only = arg.slice("--sessions=".length).split(",").map((x) => x.trim()).filter(Boolean);
     } else if (arg.startsWith("--now=")) opts.now = Number(arg.slice("--now=".length));
@@ -55,6 +64,8 @@ function printHelp() {
   node scripts/migrate-dangling.mjs --apply [--force]                   # 执行（整目录备份 + 120s 新鲜度守卫）
   node scripts/migrate-dangling.mjs --verify --backup=<backupDir>       # 只读校验
   node scripts/migrate-dangling.mjs --rollback=<backupDir>              # 从备份恢复
+  node scripts/migrate-dangling.mjs --merge-sidecar=<file|dir> [--apply] [--backup-dir=<dir>]
+        # 回灌 sidecar：默认 dry-run（只报告将合并几条）；--apply 才写（先备份 graph.json/index.md）
 
 默认路径：<DSH_HOME>/chess-context/sessions ；备份：<DSH_HOME>/chess-context/migrate-backups`);
 }
@@ -68,6 +79,9 @@ function main() {
       result = dryRun(opts.root, { now: opts.now, only: opts.only });
     } else if (opts.mode === "apply") {
       result = apply(opts.root, { now: opts.now, backupRoot: opts.backupRoot, only: opts.only, maxAgeMs: opts.force ? 0 : undefined });
+    } else if (opts.mode === "merge") {
+      result = mergeMany(opts.mergeTarget, { apply: opts.applyMerge, backupRoot: opts.backupRoot, now: opts.now });
+      if (!result.ok) code = 1;
     } else if (opts.mode === "verify") {
       result = verify(opts.root, { now: opts.now, backupDir: opts.backupDir, only: opts.only });
       if (!result.ok) code = 1;
@@ -81,6 +95,24 @@ function main() {
   }
   if (opts.json) {
     console.log(JSON.stringify(result, null, 1));
+  } else if (opts.mode === "merge") {
+    // ★ task-157：merge 的人类摘要（--json 时走上一条分支给 JSON）。
+    //   旧版这里的 merge 分支被误插进**执行链**里（与同条件的 dispatch 分支重复），
+    //   结果永远不执行 ⇒ 不带 --json 时只能看到兜底的 JSON。
+    console.log(`== migrate-dangling ${result.mode} ==`);
+    console.log(`target: ${result.target}`);
+    console.log(`sessions: ${result.sessions}｜merged ${result.merged}｜skipped ${result.skipped}`);
+    for (const one of result.perSession ?? []) {
+      const bad = one.errors.length ? ` errors ${one.errors.length}` : "";
+      console.log(`  · ${one.session}: merged ${one.merged} / skipped ${one.skipped}${bad}`);
+      for (const err of one.errors) console.log(`      ✗ ${err}`);
+    }
+    if (result.backupDirs.length) console.log(`backup: ${result.backupDirs.join(", ")}`);
+    if (result.errors.length) {
+      console.log("errors:");
+      for (const err of result.errors) console.log(`- ${err}`);
+    }
+    console.log(opts.applyMerge ? "（已回灌并重建 index.md）" : "（dry-run：什么都没写；加 --apply 才回灌）");
   } else if (opts.mode === "dry-run") {
     console.log("== migrate-dangling dry-run ==");
     console.log(`root: ${result.root}`);

package/scripts/release-lib.mjs

@@ -101,3 +101,68 @@ export function runTransaction(steps, opts = {}) {
   }
   return { ok: true, done, failed: null, error: null, aborted: [] }
 }
+
+/**
+ * 从 CHANGELOG 某节里读出**所有**「N 个测试文件」的声明。
+ * 支持这些写法（本仓历史都用过）：
+ *   `（37 个测试文件）` · `（37 个测试文件；481 + 5）` · `37 个测试文件` · `**42** 个测试文件`
+ * @returns {number[]} 没写就是空数组（不是错误）
+ */
+export function declaredTestFilesAll(section) {
+  const text = String(section ?? "")
+  const re = /(\d+)\s*\*{0,2}\s*个测试文件/g
+  const out = []
+  let m
+  while ((m = re.exec(text)) !== null) out.push(Number(m[1]))
+  return out
+}
+
+/**
+ * 从 CHANGELOG 某节里读出「N 个测试文件」的**声明**（第一个）。
+ * @returns {number|null} 没写就返回 null（不是错误）
+ */
+export function declaredTestFiles(section) {
+  const all = declaredTestFilesAll(section)
+  return all.length > 0 ? all[0] : null
+}
+
+/**
+ * 校验「N 个测试文件」的声明与实际发现的 `test/*.test.mjs` 数量是否一致。
+ *
+ * **三态**（task-160 的契约）：
+ *   · 一致     ⇒ `{ ok: true,  declared: N }`
+ *   · 不一致   ⇒ `{ ok: false, declared: N, reason }` —— 发布必须被拦住
+ *   · 没有声明 ⇒ `{ ok: true,  declared: null }` —— 不报错（允许不写这个数）
+ *
+ * ⚠ 一节里可能出现**多个**数字（例如正文引用了旧版报错原文）。那种情况按「**全部都要等**」判：
+ * 只要出现一个不等于实际的数字就红，并把所有值列出来 —— 否则这段文档自己就是一锅粥，
+ * 门禁被自己的举例骗过（1.11.9 起草时真实发生过）。
+ *
+ * 为什么要有这条：本仓 CHANGELOG 长期写「N 个测试文件」，而 N 从 1.11.5 起就停在 37、
+ * 实际已经 42 —— 数字漂了 5 个版本没人发现。用户会拿这个数判断覆盖面。
+ *
+ * @param {string} section 当前版本那一节的正文
+ * @param {number} actual 实际 `test/*.test.mjs` 文件数
+ */
+export function checkTestFileCount(section, actual) {
+  const all = declaredTestFilesAll(section)
+  if (all.length === 0) return { ok: true, declared: null, actual, declaredAll: [] }
+  const declared = all[0]
+  const bad = all.filter((n) => n !== actual)
+  if (bad.length === 0) return { ok: true, declared, actual, declaredAll: all }
+  const distinct = [...new Set(all)]
+  return {
+    ok: false,
+    declared,
+    actual,
+    declaredAll: all,
+    reason:
+      distinct.length > 1
+        ? `CHANGELOG 这一节里出现了多个不一致的「N 个测试文件」：${distinct.join(" / ")}（实际 ${actual} 个）—— ` +
+          `一处写对、另一处写错同样会误导；引用旧数字时请用占位符（如「N 个测试文件」），别写真实旧值`
+        : `CHANGELOG 写的「${declared} 个测试文件」与实际 ${actual} 个不符 —— ` +
+          `改了测试文件就必须同步这句（或删掉它，脚本不会因此报错）。` +
+          `实际值怎么数：ls test/*.test.mjs | wc -l（看历史版本：` +
+          `git ls-tree -r --name-only <tag>^{commit} test/ | grep -c '\\.test\\.mjs$'）`,
+  }
+}

package/scripts/release.mjs

@@ -12,6 +12,7 @@
 //
 // 体检项（任一不过就退出码 1，且 --yes 也不动手）：
 //   ① package.json 有 version               ② CHANGELOG 有这一版那一段
+//   ②b 「N 个测试文件」的声明 == test/*.test.mjs 实际数（**没写这句不报错**）
 //   ③ 工作区干净                            ④ 当前在默认分支
 //   ⑤ remote 是合法 GitHub URL（拒 git+https 之类）  ⑥ 远端可达（ls-remote 必须成功）
 //   ⑦ 不落后远端（fetch 必须成功，失败=红，不再吞成 note）  ⑧ tag 还没被占
@@ -24,9 +25,9 @@
 //   GITHUB_TOKEN / GH_TOKEN 环境变量。没有也能跑 —— 它会打印手工建 Release 的命令。
 
 import { execSync, execFileSync } from "node:child_process"
-import { readFileSync, existsSync } from "node:fs"
+import { readFileSync, readdirSync, existsSync } from "node:fs"
 import { join } from "node:path"
-import { classifyRemote, runTransaction } from "./release-lib.mjs"
+import { classifyRemote, runTransaction, checkTestFileCount } from "./release-lib.mjs"
 
 const ROOT = process.cwd()
 const argv = new Set(process.argv.slice(2))
@@ -94,6 +95,20 @@ function changelogSection(v) {
 const section = version ? changelogSection(version) : ""
 if (version && !section) bad(`CHANGELOG.md 里没有「## ${version}」那一段 —— 先写更新内容再发版`)
 
+// ── 「N 个测试文件」的声明必须等于事实 ────────────────────────────────
+// 这条是 task-160 加的：本仓 CHANGELOG 连续 5 个版本写「37 个测试文件」，实际早就是 42
+// —— 数字漂了没人发现，而用户会拿它判断覆盖面。**没写这句不报错**（允许不写）。
+const testDir = join(ROOT, "test")
+const actualTestFiles = existsSync(testDir)
+  ? readdirSync(testDir).filter((f) => f.endsWith(".test.mjs")).length
+  : 0
+const testFileCheck = checkTestFileCount(section, actualTestFiles)
+if (testFileCheck.declared === null) {
+  note(`CHANGELOG 没写「N 个测试文件」⇒ 跳过该数字校验（实际 ${actualTestFiles} 个）`)
+} else if (!testFileCheck.ok) {
+  bad(testFileCheck.reason)
+}
+
 /**
  * 去掉 `> 起因：…` 那段 —— 它写给维护者，不进 Release 正文。
  * （UPDATING 四：一条一行说的是改了什么，`> 起因` 说的是为什么。用户感知不到后者。）
@@ -183,22 +198,45 @@ let tagCommitLocal = ""
 let tagCommitRemote = ""
 if (gh) {
   tagExistsLocal = shOk(`git rev-parse -q --verify refs/tags/${tag}`)
-  if (tagExistsLocal) tagCommitLocal = sh(`git rev-parse -q --verify refs/tags/${tag}^{commit}`)
+  // ⚠ 不能用 `refs/tags/x^{commit}`：Windows 上 execSync 走 cmd.exe，`^` 是转义字符 ⇒
+  // 会被吃成 `refs/tags/x{commit}`，命令失败、脚本崩（2026-10-31 实测：tag 已存在时跑预演直接抛异常）。
+  // `rev-list -n1` 对 annotated / lightweight tag 都会剥到 commit，且没有 shell 元字符。
+  if (tagExistsLocal) {
+    try {
+      tagCommitLocal = sh(`git rev-list -n1 refs/tags/${tag}`)
+    } catch {
+      tagCommitLocal = ""
+    }
+  }
   try {
-    const out = sh(`git ls-remote --tags origin refs/tags/${tag}`)
-    tagExistsRemote = out.length > 0
-    // ls-remote 对 annotated tag 会同时给 `<tagobj>\trefs/tags/x` 和 `<commit>\trefs/tags/x^{}`；
-    // 取 deref 行（`^{}`）的 sha 才是它指向的 commit。
-    const deref = out.split("\n").find((l) => l.includes(`refs/tags/${tag}^{}`))
-    const plain = out.split("\n").find((l) => l.endsWith(`refs/tags/${tag}`))
-    tagCommitRemote = (deref ?? plain ?? "").split(/\s+/)[0] ?? ""
+    // ⚠ 不能给 ls-remote 传 `refs/tags/x` 这种精确 pattern：那样**不会**输出 `^{}` 剥皮行，
+    // 拿到的只是 tag 对象 sha（annotated tag 时 ≠ commit）。列全部 tag 再由 JS 过滤。
+    const out = sh(`git ls-remote --tags origin`)
+    const lines = out.split("\n").filter(Boolean)
+    const deref = lines.find((l) => l.endsWith(`refs/tags/${tag}^{}`))
+    const plain = lines.find((l) => l.endsWith(`refs/tags/${tag}`))
+    tagExistsRemote = Boolean(plain || deref)
+    // annotated tag：deref 行的 sha 才是 commit；lightweight tag：只有 plain 行且它本身就是 commit。
+    tagCommitRemote = ((deref ?? plain ?? "").split(/\s+/)[0] ?? "").trim()
   } catch {}
   const headSha = shOk("git rev-parse HEAD") ? sh("git rev-parse HEAD") : ""
-  const pointsAtHead = (sha) => !!sha && !!headSha && (sha === headSha || headSha.startsWith(sha))
+  /** tag 指向的 commit 是不是 HEAD 本身或 HEAD 的祖先（= 正常「发过了，之后又提交了几次」） */
+  const tagIsBehindHead = (sha) => {
+    if (!sha) return false
+    if (!headSha) return false
+    if (sha === headSha || headSha.startsWith(sha)) return true
+    try {
+      sh(`git merge-base --is-ancestor ${sha} HEAD`)
+      return true
+    } catch {
+      return false
+    }
+  }
   if (tagExistsLocal || tagExistsRemote) {
-    if (tagExistsRemote && tagCommitRemote && !pointsAtHead(tagCommitRemote)) {
+    const remoteSha = tagCommitRemote || tagCommitLocal
+    if (tagExistsRemote && remoteSha && !tagIsBehindHead(remoteSha)) {
       bad(
-        `远端 tag ${tag} 已存在，但指向 ${tagCommitRemote.slice(0, 12)}（不是 HEAD ${headSha.slice(0, 12)}）—— ` +
+        `远端 tag ${tag} 已存在，但指向 ${remoteSha.slice(0, 12)}，既不是 HEAD 也不是 HEAD 的祖先 —— ` +
           `可能是上次发布中断时由 Release API 自动建的轻量 tag。脚本**不会自动 force**。` +
           `确认这个 tag 发错之后，手工修：git push --force origin refs/tags/${tag}:refs/tags/${tag}`,
       )

package/src/rooms/migrate.mjs

@@ -410,6 +410,210 @@ export function apply(root, { now = Date.now(), backupRoot = backupsRoot(), stam
   return summary;
 }
 
+/* ───────────────────────────── merge（sidecar 回灌） ───────────────────────────── */
+
+/**
+ * merge 的备份目录：`<backupRoot>/merge-<iso>`（apply 且真的写了才创建）。
+ * 与 apply 的整目录备份同根（`<DSH_HOME>/chess-context/migrate-backups`），便于排障时一处找齐。
+ */
+export function mergeBackupDir({ backupRoot = backupsRoot(), stamp = new Date() } = {}) {
+  const dir = nodePath.join(backupRoot, `merge-${stamp.toISOString().replace(/[:.]/g, "-")}`);
+  nodeFs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+/**
+ * 校验 sidecar 并读出边（纯只读，不碰图）。
+ * @returns {{ok:boolean, errors:string[], sidecar:any, edges:any[]}}
+ */
+export function readSidecar(file, { sessionId = "" } = {}) {
+  const errors = [];
+  let sidecar = null;
+  if (!nodeFs.existsSync(file)) return { ok: false, errors: [`sidecar 不存在：${file}`], sidecar: null, edges: [] };
+  try {
+    sidecar = JSON.parse(nodeFs.readFileSync(file, "utf8"));
+  } catch (error) {
+    return { ok: false, errors: [`sidecar 不是合法 JSON（${String(error?.message ?? error)}）`], sidecar: null, edges: [] };
+  }
+  if (sidecar === null || typeof sidecar !== "object") errors.push("sidecar 顶层不是对象");
+  if (sidecar?.format !== SIDECAR_FORMAT) errors.push(`sidecar format 不对：${String(sidecar?.format)}（应为 ${SIDECAR_FORMAT}）`);
+  if (sidecar?.version !== SIDECAR_VERSION) errors.push(`sidecar version 不支持：${String(sidecar?.version)}（应为 ${SIDECAR_VERSION}）`);
+  if (sessionId && typeof sidecar?.sessionId === "string" && sidecar.sessionId.length > 0 && sidecar.sessionId !== sessionId) {
+    errors.push(`sidecar 属于别的会话：${sidecar.sessionId}（当前 ${sessionId}）`);
+  }
+  const edges = Array.isArray(sidecar?.edges) ? sidecar.edges : null;
+  if (edges === null) errors.push("sidecar.edges 不是数组");
+  else if (edges.length === 0) errors.push("sidecar 里没有边（空边）");
+  if (Array.isArray(edges)) {
+    edges.forEach((edge, i) => {
+      if (edge === null || typeof edge !== "object") errors.push(`edges[${i}] 不是对象`);
+      else if (typeof edge.id !== "string" || edge.id.length === 0) errors.push(`edges[${i}] 缺 id`);
+    });
+  }
+  return { ok: errors.length === 0, errors, sidecar, edges: errors.length === 0 ? edges : [] };
+}
+
+/**
+ * 把一个 sidecar 回灌进会话图（R14）。
+ *
+ * 语义（与 apply 对称）：
+ *   · 按 **edge.id** 合并；图里已有同 id ⇒ **跳过**（绝不覆盖当前边）；
+ *   · 保留 sidecar 里的原字段（JSON 深拷贝，不重算/不改写）；
+ *   · 有改动才 `updatedAt = now`、原子写 graph.json、**重建 index.md**；
+ *   · **默认 dry-run**（不写任何文件）；`apply:true` 才写，写之前把 graph.json / index.md
+ *     备份到 `<backupRoot>/merge-<iso>/`，并落一份 `MERGE.json` 审计；
+ *   · 幂等：同一 sidecar 回灌第二次 ⇒ `merged:0`、`skipped:N`、不写盘、不建备份。
+ *
+ * @param {string} dir 会话目录（含 graph.json）
+ * @param {{sidecarFile?:string, apply?:boolean, backupRoot?:string, stamp?:Date, now?:number}} [options]
+ * @returns {{mode:string, session:string, sidecar:string, ok:boolean, dryRun:boolean, total:number, merged:number, skipped:number, duplicates:number, mergedIds:string[], errors:string[], backupDir:string, graphBytesBefore:number, graphBytesAfter:number, indexRebuilt:boolean}}
+ */
+export function mergeSidecar(dir, { sidecarFile = "", apply = false, backupRoot = backupsRoot(), stamp = new Date(), now = Date.now() } = {}) {
+  const session = nodePath.basename(dir);
+  const file = sidecarFile || nodePath.join(dir, SIDECAR_NAME);
+  const result = {
+    mode: apply ? "merge-apply" : "merge-dry-run",
+    session,
+    sidecar: file,
+    ok: false,
+    dryRun: !apply,
+    total: 0,
+    merged: 0,
+    skipped: 0,
+    duplicates: 0,
+    mergedIds: [],
+    errors: [],
+    backupDir: "",
+    graphBytesBefore: 0,
+    graphBytesAfter: 0,
+    indexRebuilt: false,
+  };
+
+  const graphFile = nodePath.join(dir, "graph.json");
+  if (!nodeFs.existsSync(graphFile)) {
+    result.errors.push(`会话目录里没有 graph.json：${graphFile}`);
+    return result;
+  }
+  const read = readSidecar(file, { sessionId: session });
+  if (!read.ok) {
+    result.errors.push(...read.errors);
+    return result;
+  }
+  result.total = read.edges.length;
+
+  let text;
+  let g;
+  try {
+    text = nodeFs.readFileSync(graphFile, "utf8");
+    g = fromJSON(text);
+  } catch (error) {
+    result.errors.push(`graph.json 读不出（${String(error?.message ?? error)}）`);
+    return result;
+  }
+  result.graphBytesBefore = Buffer.byteLength(text);
+
+  const seen = new Set();
+  for (const edge of read.edges) {
+    if (seen.has(edge.id)) {
+      result.duplicates += 1;
+      continue;
+    }
+    seen.add(edge.id);
+    if (g.edges && g.edges[edge.id]) {
+      result.skipped += 1;
+      continue;
+    }
+    g.edges[edge.id] = JSON.parse(JSON.stringify(edge));
+    result.mergedIds.push(edge.id);
+    result.merged += 1;
+  }
+
+  if (result.merged === 0) {
+    // 幂等：没有新边 ⇒ 一个字节都不写（不建备份、不碰 index.md）
+    result.graphBytesAfter = result.graphBytesBefore;
+    result.ok = true;
+    return result;
+  }
+
+  g.updatedAt = now;
+  const next = toJSON(g);
+  result.graphBytesAfter = Buffer.byteLength(next);
+
+  if (!apply) {
+    result.ok = true;
+    return result;
+  }
+
+  // ① 显式备份（graph.json + index.md）；② 原子写 graph.json；③ 重建 index.md；④ MERGE.json 审计
+  const backupDir = mergeBackupDir({ backupRoot, stamp });
+  result.backupDir = backupDir;
+  nodeFs.copyFileSync(graphFile, nodePath.join(backupDir, "graph.json"));
+  const indexFile = nodePath.join(dir, "index.md");
+  if (nodeFs.existsSync(indexFile)) nodeFs.copyFileSync(indexFile, nodePath.join(backupDir, "index.md"));
+  writeFileAtomic(graphFile, next);
+  writeFileAtomic(indexFile, renderIndexMd(g));
+  result.indexRebuilt = true;
+  writeFileAtomic(
+    nodePath.join(backupDir, "MERGE.json"),
+    JSON.stringify({ ...result, appliedAt: new Date(now).toISOString(), root: dir }, null, 1),
+  );
+  result.ok = true;
+  return result;
+}
+
+/**
+ * 回灌一批会话（CLI 用）：`target` 可以是单个 sidecar 文件、单个会话目录、或会话根目录。
+ * 返回汇总 + 每会话结果。任何一条出错 ⇒ `ok:false`（但已成功的仍然写完了，逐条可查）。
+ */
+export function mergeMany(target, { apply = false, backupRoot = backupsRoot(), stamp = new Date(), now = Date.now() } = {}) {
+  const dirs = [];
+  const sidecars = [];
+  if (!nodeFs.existsSync(target)) {
+    return {
+      mode: apply ? "merge-apply" : "merge-dry-run",
+      target,
+      sessions: 0,
+      merged: 0,
+      skipped: 0,
+      ok: false,
+      errors: [`目标不存在：${target}`],
+      backupDirs: [],
+      perSession: [],
+    };
+  }
+  if (nodeFs.statSync(target).isDirectory()) {
+    const direct = nodePath.join(target, SIDECAR_NAME);
+    if (nodeFs.existsSync(direct) && nodeFs.existsSync(nodePath.join(target, "graph.json"))) {
+      dirs.push(target);
+    } else {
+      for (const dir of listSessions(target)) {
+        if (nodeFs.existsSync(nodePath.join(dir, SIDECAR_NAME))) dirs.push(dir);
+      }
+    }
+  } else {
+    sidecars.push(target);
+  }
+  const perSession = dirs.map((dir) => mergeSidecar(dir, { apply, backupRoot, stamp, now }));
+  for (const file of sidecars) {
+    // sidecar 文件 → 会话目录 = 它的父目录
+    perSession.push(mergeSidecar(nodePath.dirname(file), { sidecarFile: file, apply, backupRoot, stamp, now }));
+  }
+  const merged = perSession.reduce((n, r) => n + r.merged, 0);
+  const skipped = perSession.reduce((n, r) => n + r.skipped, 0);
+  const errors = perSession.flatMap((r) => r.errors.map((e) => `${r.session}: ${e}`));
+  return {
+    mode: apply ? "merge-apply" : "merge-dry-run",
+    target,
+    sessions: perSession.length,
+    merged,
+    skipped,
+    ok: perSession.length > 0 && errors.length === 0,
+    errors,
+    backupDirs: perSession.map((r) => r.backupDir).filter(Boolean),
+    perSession,
+  };
+}
+
 /* ───────────────────────────── verify ───────────────────────────── */
 
 /**