thincoder 0.12.59 → 0.12.61

package/src/tools/{system.mjs → bash.mjs}

@@ -4,23 +4,12 @@ import {
   truncate,
   makeDecoder,
   BASH_TIMEOUT_MS,
-  IGNORED_DIRS,
-  resolveInCwd,
-  globToRegex,
-  normalizeEOL,
 } from "./shared.mjs";
 import { spawn, execFileSync } from "node:child_process";
-import { readFile, readdir, stat, lstat } from "node:fs/promises";
-import { join } from "node:path";
 
 /** Maximum buffer size per stream (stdout / stderr) before truncation */
 const MAX_STREAM_BUF = 2_000_000
 
-/** Escape a string for literal regex matching (grep literal=true). */
-function escapeRegExp(s) {
-  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
-}
-
 /** Keep only output lines matching a regex (bash filter, case-insensitive). */
 function applyLineFilter(output, filter) {
   let re
@@ -83,13 +72,6 @@ function killProcessTree(child) {
   }
 }
 
-/**
- * Run a bash command: spawn, stream stdout/stderr with buffering and decoding,
- * enforce timeout and signal abort, return formatted result.
- *
- * Returns a promise that resolves to the formatted output string (stdout + stderr + status + truncation note).
- */
-
 /**
  * Detect destructive git commands and auto-snapshot BEFORE execution.
  * The scenario: the model writes uncommitted code, then (after breaking things)
@@ -127,6 +109,12 @@ async function gitGuardSnapshot(command, cwd) {
   }
 }
 
+/**
+ * Run a bash command: spawn, stream stdout/stderr with buffering and decoding,
+ * enforce timeout and signal abort, return formatted result.
+ *
+ * Returns a promise that resolves to the formatted output string (stdout + stderr + status + truncation note).
+ */
 function runBash(command, cwd, { timeout, signal, onOutput, shell }) {
   return new Promise((resolve) => {
     // Windows + default cmd: force UTF-8 code page for this child process (each spawn
@@ -145,6 +133,11 @@ function runBash(command, cwd, { timeout, signal, onOutput, shell }) {
       detached: process.platform !== "win32",
       stdio: ["ignore", "pipe", "pipe"],
       env: buildBashEnv(),
+      // 双保险（2026-09-05——裸 spawn 无 signal 教训：abort 只靠 killTree 手动杀——taskkill
+      // best-effort 可能失败/竞态）——Node signal option = 第一道（abort 时自动杀**直接**子
+      // 进程——cmd——语义保证）；killTree 仍是必需兜底（孙进程握管道使 close 不触发——见
+      // L191 注释——spawn 级 kill 不达孙进程）
+      ...(signal ? { signal } : {}),
     })
 
     const killTree = () => killProcessTree(child)
@@ -181,10 +174,18 @@ function runBash(command, cwd, { timeout, signal, onOutput, shell }) {
       settled = true
       clearTimeout(timer)
       clearTimeout(graceTimer)
+      // 2026-09-05（advisor 🟡#2）：收尾移除 abort 监听器——ctx.signal 为长生命周期对象，
+      // 残留 once 监听器每次 bash 调用累积（闭包持有 child/输出缓冲直到 abort 才释放）
+      if (signal) signal.removeEventListener("abort", killTree)
       resolve(result)
     }
 
     child.on("error", (error) => {
+      // signal 双保险（2026-09-05）：abort 时 Node signal option 杀直接子进程 → 本事件
+      // 以 AbortError 先触发——**跳过 finish**（不 settled）——exit 事件随后必到（实证
+      // 2ms 内）走 L195 分支带已收集输出收尾（user interrupted——不丢 partial）；
+      // 非 abort 的真 spawn 错误（command not found 等）保持原分支
+      if (error.name === "AbortError") return
       finish(truncate(`Command failed: ${error.message}\n[stdout]:\n${outBuf || "(empty)"}`))
     })
 
@@ -265,206 +266,3 @@ export const bashTool = {
     return hint ? `${hint}\n${body}` : body
   },
 }
-
-// ---------------------------------------------------------------- glob
-
-export const globTool = {
-  name: "glob",
-  description: DESC("glob"),
-  parameters: {
-    type: "object",
-    properties: {
-      pattern: { type: "string", description: "Glob pattern" },
-      path: { type: "string", description: "Directory to search in (default cwd)" },
-    },
-    required: ["pattern"],
-  },
-  readonly: true,
-  async execute(args, ctx) {
-    const base = resolveInCwd(ctx, args.path ?? ".")
-    const regex = globToRegex(args.pattern)
-    const results = []
-    for await (const relPath of walkFiles(base)) {
-      if (regex.test(relPath)) {
-        results.push(relPath)
-        if (results.length >= 1000) break
-      }
-    }
-    if (results.length === 0) return "(no matches)"
-    return truncate(results.sort().join("\n"))
-  },
-}
-
-/** Recursively traverse files, yield relative paths (skip IGNORED_DIRS) */
-async function* walkFiles(dir, rel = "") {
-  let entries
-  try {
-    entries = await readdir(dir, { withFileTypes: true })
-  } catch {
-    return
-  }
-  for (const e of entries) {
-    // Skip ignored dirs AND symbolic links (symlinks to directories would cause infinite loops)
-    if (e.isSymbolicLink()) continue
-    if (e.isDirectory() && IGNORED_DIRS.has(e.name)) continue
-    const relPath = rel ? `${rel}/${e.name}` : e.name
-    if (e.isDirectory()) {
-      yield* walkFiles(join(dir, e.name), relPath)
-    } else {
-      yield relPath
-    }
-  }
-}
-
-/** Glob to regex: **\/ matches zero or more directory levels, ** crosses directories, * within segment, ? single char within segment */
-
-// ---------------------------------------------------------------- grep
-
-export const grepTool = {
-  name: "grep",
-  description: DESC("grep"),
-  parameters: {
-    type: "object",
-    properties: {
-      pattern: { type: "string", description: "Regular expression, or a literal string when literal=true" },
-      path: { type: "string", description: "Directory or file to search (default cwd)" },
-      glob: { type: "string", description: "Only search files matching this glob (e.g. '*.mjs')" },
-      ignoreCase: { type: "boolean", description: "Case-insensitive match (default false)" },
-      literal: { type: "boolean", description: "Literal string match — no regex interpretation (default false)" },
-      before: { type: "integer", description: "Lines of context to show before each match (grep -B). Default 0" },
-      after: { type: "integer", description: "Lines of context to show after each match (grep -A). Default 0" },
-    },
-    required: ["pattern"],
-  },
-  readonly: true,
-  async execute(args, ctx) {
-    const base = resolveInCwd(ctx, args.path ?? ".")
-    let regex
-    try {
-      const pat = args.literal ? escapeRegExp(String(args.pattern)) : args.pattern
-      regex = new RegExp(pat, args.ignoreCase ? "i" : "")
-    } catch (e) {
-      throw new Error(`grep pattern /${args.pattern}/ is not a valid regex: ${e.message}`, { cause: e })
-    }
-    const fileFilter = args.glob ? globToRegex(args.glob) : null
-    const before = Math.max(0, Math.floor(args.before ?? 0))
-    const after = Math.max(0, Math.floor(args.after ?? 0))
-    const wantCtx = before > 0 || after > 0
-    const hits = [] // { file, line(1-based), text }
-    const fileLines = new Map() // file -> string[] (cached only when context lines requested)
-
-    async function search(file) {
-      let content
-      try {
-        // Large file guard: skip files over 10MB to prevent OOM
-        const fst = await stat(file)
-        if (fst.size > 10_000_000) return
-        content = normalizeEOL(await readFile(file, "utf8"))
-      } catch {
-        return // Skip unreadable files; binary files will be read as UTF-8 and searched (may produce garbled matches)
-      }
-      const lines = content.split("\n")
-      if (wantCtx) fileLines.set(file, lines)
-      for (let i = 0; i < lines.length; i++) {
-        if (regex.test(lines[i])) {
-          hits.push({ file, line: i + 1, text: lines[i] })
-          if (hits.length >= 200) return
-        }
-      }
-    }
-
-    async function walk(target) {
-      if (hits.length >= 200) return
-      // Use lstat to avoid following symlinks — prevents ./evil → /etc from making grep scan the entire system
-      let s
-      try { s = await lstat(target) } catch { return }
-      if (!s.isDirectory()) {
-        if (!fileFilter || fileFilter.test(target.split(/[\\/]/).pop())) await search(target)
-        return
-      }
-      let entries
-      try {
-        entries = await readdir(target, { withFileTypes: true })
-      } catch {
-        return
-      }
-      for (const e of entries) {
-        if (e.isDirectory() && IGNORED_DIRS.has(e.name)) continue
-        await walk(join(target, e.name))
-      }
-    }
-
-    await walk(base)
-    if (hits.length === 0) return "(no matches)"
-
-    // No context: keep original path:line: content format
-    if (!wantCtx) {
-      return truncate(hits.map((h) => `${h.file}:${h.line}: ${h.text}`).join("\n"))
-    }
-
-    // With context: matching lines use ':', context lines use '-' (like ripgrep); overlapping ranges in same file are merged and de-duplicated
-    const fileMatched = new Map() // file -> Set<line>
-    for (const h of hits) {
-      if (!fileMatched.has(h.file)) fileMatched.set(h.file, new Set())
-      fileMatched.get(h.file).add(h.line)
-    }
-    const out = []
-    for (const [file, matchedLines] of fileMatched) {
-      const lines = fileLines.get(file) ?? []
-      const lineSet = new Set()
-      for (const ml of matchedLines) {
-        for (let l = Math.max(1, ml - before); l <= Math.min(lines.length, ml + after); l++) lineSet.add(l)
-      }
-      for (const l of [...lineSet].sort((a, b) => a - b)) {
-        const sep = matchedLines.has(l) ? ":" : "-"
-        out.push(`${file}${sep}${l}${sep} ${lines[l - 1]}`)
-      }
-    }
-    return truncate(out.join("\n"))
-  },
-}
-
-// ---------------------------------------------------------------- websearch
-
-export const lsTool = {
-  name: "ls",
-  description: DESC("ls"),
-  parameters: {
-    type: "object",
-    properties: {
-      path: { type: "string", description: "Directory path (default cwd)" },
-      filter: { type: "string", description: "Only list entries matching this glob (e.g. '*.mjs', '*test*')" },
-    },
-  },
-  readonly: true,
-  async execute(args, ctx) {
-    const abs = resolveInCwd(ctx, args.path ?? ".")
-    const filterRe = args.filter ? globToRegex(args.filter) : null
-    let entries
-    try {
-      entries = await readdir(abs, { withFileTypes: true })
-    } catch (e) {
-      if (e.code === "ENOENT" || e.code === "ENOTDIR") throw new Error(`ls: ${args.path ?? "."} — ${e.code === "ENOTDIR" ? "not a directory" : "not found"}`, { cause: e })
-      throw e
-    }
-    const rows = await Promise.all(
-      entries
-        .filter((e) => !filterRe || filterRe.test(e.name))
-        .slice(0, 500)
-        .map(async (e) => {
-        const s = await stat(join(abs, e.name)).catch(() => null)
-        const isDir = e.isDirectory()
-        return {
-          dir: isDir,
-          name: e.name + (isDir ? "/" : ""),
-          size: s?.size ?? 0,
-          mtime: s ? s.mtime.toISOString().slice(0, 16).replace("T", " ") : "?",
-        }
-      }),
-    )
-    rows.sort((a, b) => (a.dir === b.dir ? a.name.localeCompare(b.name) : a.dir ? -1 : 1))
-    if (rows.length === 0) return "(no entries)"
-    const out = rows.map((r) => `${r.dir ? "d" : "-"}  ${r.name.padEnd(40)} ${String(r.size).padStart(10)}  ${r.mtime}`)
-    return truncate(out.join("\n"))
-  },
-}

package/src/tools/checklist-sync.mjs

@@ -0,0 +1,181 @@
+/**
+ * checklist-sync.mjs — checklist 并发写同步机（R10 F4，MULTI-INSTANCE-COLLAB.md §2a.3
+ * ——2026-09-06，自 checklist.mjs 拆出：门控 + 合并 + 序列化——防 checklist.mjs 超 300
+ * 行 advisory 线；本模块为纯同步机制，不持 checklist 业务状态）。
+ *
+ * 双端 checklist 同路径 {cwd}/.thincoder/checklist.md——多实例并发写原为裸整文件覆盖
+ * （丢项）。写前 mtime 门控 + ID 键合并（评审修正 #6 基线规则：基线 = 本读-改-写链内
+ * 最近一次 stat 的 mtime；本进程自写后刷新——parse 规范化写回不误触发 merged/重分配）。
+ * .bak 不做（决策点② A：cwd 在 git 仓库内——git 兜底现场）。
+ *
+ * 冲突语义（flushWrite 内收口）：写前 stat ≠ 基线（对端并发写过）→ 重读磁盘 → 双方
+ * union by ID（本端新增 + 盘上他端新增都保留；同 ID 不同文本 → 盘上保留、本端重分配
+ * max+1 续分配；同 ID 仅状态不同 → in_progress 胜过 pending——标记不丢）；checklist
+ * 文件合并时按 done 文件归档 ID 排除（含子任务点号 ID——并发 mark-done 的"盘上有旧
+ * pending 副本"不复活已归档项——done 集合 union 的另一半）。checklist-done.md 自身
+ * 合并 = 纯 union（无归档排除）。
+ *
+ * 调用方（checklist.mjs）通过 flushWrite 的 opts 注入：reread（磁盘无写回重读）、
+ * doneFile 路径、isDone（目标文件是否为 done 文件）——避免本模块反向依赖 checklist
+ * 的 parse/树结构。
+ */
+import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs"
+
+const baselines = new Map() // filePath → 最近一次读的 stat mtime（null = 读时文件缺失）
+
+/** F4 测试缝（伪属主范式——T-F4a..d）：在每次写前门控处注入"对端写盘"钩子——模拟本链
+ *  parse 后、write 前对端实例的真实并发写。生产不设置（null → 零行为影响）。 */
+let writeGateHook = null
+export function _setWriteGateHookForTest(fn) { writeGateHook = fn }
+
+/** 文件缺失 → null（门控 t0 基线形态）。 */
+export function statMtime(p) {
+  try { return statSync(p).mtimeMs } catch { return null }
+}
+
+/** 调用方（parse 读链）登记基线——读后写链以它为门控比对基准。 */
+export function noteReadBaseline(filePath, mtime) {
+  baselines.set(filePath, mtime)
+}
+
+/** Done 文件归档根 ID 清单（含子任务点号 ID：T1 与 T1.2 都进——归档排除用；编号预留
+ *  nextRootId 的 /^T(\d+)$/ 过滤不受影响）。 */
+export function readDoneRoots(doneFile) {
+  if (!existsSync(doneFile)) return []
+  const roots = []
+  for (const line of readFileSync(doneFile, "utf-8").split("\n")) {
+    const m = line.match(/^- \[.\] ((?:T\d+)(?:\.\d+)*): /)
+    if (m) roots.push({ id: m[1] })
+  }
+  return roots
+}
+
+/** Serialize items to markdown lines (2-space indent per depth) — tree structure preserved. */
+function renderItems(nodes, depth, out) {
+  const indent = "  ".repeat(depth)
+  for (const item of nodes) {
+    const mark = item.status === "done" ? "x" : item.status === "in_progress" ? "~" : " "
+    const label = item.id ? `${item.id}: ${item.text}` : item.text
+    out.push(`${indent}- [${mark}] ${label}`)
+    if (item.children?.length) renderItems(item.children, depth + 1, out)
+  }
+}
+
+/**
+ * 门控 + 合并 + 写（F4 收口——parse 规范化写回 / add / mark 双写都经它）。
+ * @param filePath 目标文件（checklist.md 或 checklist-done.md）
+ * @param items 本端（读-改-写链产物）的顶层 items
+ * @param opts.reread 磁盘无写回重读函数（返回盘上顶层 items——合并触发时调用）
+ * @param opts.doneFile done 文件路径（checklist 合并的归档排除源）
+ * @param opts.isDone 目标文件是否为 done 文件（true = 纯 union，无归档排除）
+ * @returns { merged, items }——merged=true 时 items 为落盘真相（本端节点原地重分配——
+ *   调用方持有的引用/消息读到的即最终 ID）；merged=false 时 items 为原输入。
+ */
+export function flushWrite(filePath, items, { reread, doneFile, isDone }) {
+  if (writeGateHook) writeGateHook(filePath) // 测试缝：模拟对端此刻写盘
+  const base = baselines.get(filePath) // undefined = 本链无读（防御——无基线无从门控）
+  const now = statMtime(filePath)
+  let finalItems = items
+  let merged = false
+  if (base !== undefined && now !== base) {
+    // 磁盘被对端并发改过（本链读后）→ 重读磁盘 + 合并（ID union）
+    const diskItems = reread()
+    finalItems = mergeItems(diskItems, items, doneFile, isDone)
+    merged = true
+  }
+  const out = []
+  renderItems(finalItems, 0, out)
+  writeFileSync(filePath, out.join("\n") + "\n")
+  baselines.set(filePath, statMtime(filePath)) // 自写后刷新基线（防自写误判并发）
+  return { merged, items: finalItems }
+}
+
+// ── F4 合并（ID 键 union）─────────────────────────────────────────────────────
+
+function flattenTree(nodes, out = []) {
+  for (const n of nodes) {
+    out.push(n)
+    if (n.children?.length) flattenTree(n.children, out)
+  }
+  return out
+}
+
+/** 层内递归合并（磁盘序在前；本端独有/重分配项追加尾部）——规则见文件头注释。 */
+function mergeLevel(diskNodes, ourNodes, env) {
+  const diskById = new Map(diskNodes.filter((n) => n.id != null).map((n) => [n.id, n]))
+  const ourById = new Map(ourNodes.filter((n) => n.id != null).map((n) => [n.id, n]))
+  const result = []
+  const pending = [] // 本端独有 + 同 ID 异文本（待重分配）——追加在磁盘序之后
+  for (const d of diskNodes) {
+    if (d.id != null && !env.isDone && env.doneIds.has(d.id)) continue // 已归档（对端 mark-done）→ 不复活
+    const o = d.id != null ? ourById.get(d.id) : null
+    if (!o) { result.push(d); continue } // 盘上独有 → 整棵保留
+    const childEnv = { ...env, prefix: `${d.id}.` } // 子层重分配域 = 父 ID 前缀（"T1" → "T1."）
+    if (o.text === d.text && o.status === d.status) {
+      // 双端同一节点（parse 规范化幂等场景）→ 去重；子树仍逐层合并（防丢任一端子新增）
+      d.children = mergeLevel(d.children ?? [], o.children ?? [], childEnv)
+      result.push(d)
+      continue
+    }
+    if (o.text === d.text) {
+      // 仅状态不同 → in_progress 胜过 pending（标记意图不丢；同文本不可能 pending×pending）
+      const carry = d.status === "in_progress" ? d : o
+      carry.children = mergeLevel(d.children ?? [], o.children ?? [], childEnv)
+      result.push(carry)
+      continue
+    }
+    // 同 ID 不同文本（并发 add 各自从同基线分到同号）→ 盘上保留；本端项排队重分配
+    result.push(d)
+    pending.push(o)
+  }
+  for (const o of ourNodes) {
+    if (o.id == null) { pending.push(o); continue } // 无 ID 行（理论极少——parse 已归一）→ 原样追加
+    if (!env.isDone && env.doneIds.has(o.id)) continue // 本端项已被归档 → 丢弃（不复活）
+    if (!diskById.has(o.id)) pending.push(o) // 本端独有 → 保留（含子树）
+    // 共享 ID 已在磁盘循环处理（去重/状态/文本冲突排队）
+  }
+  for (const o of pending) {
+    if (o.id != null && diskById.has(o.id)) reassignNode(o, env) // 文本冲突项 → 重分配 max+1 续分配
+    result.push(o)
+  }
+  return result
+}
+
+/** 重分配：层前缀（根 "T" / 子树 `${parentId}.`）下 max+1；子树 ID 前缀同步换新
+ *  （"T4.1" → "T5.1"——ID 层级与父节点保持一致）。原地改——调用方引用即最终 ID。 */
+function reassignNode(node, env) {
+  let max = 0
+  for (const id of env.allIds) {
+    if (!id?.startsWith(env.prefix)) continue
+    const suffix = id.slice(env.prefix.length)
+    if (/^\d+$/.test(suffix)) max = Math.max(max, parseInt(suffix))
+  }
+  const oldId = node.id
+  const newId = `${env.prefix}${max + 1}`
+  node.id = newId
+  env.allIds.add(newId)
+  if (oldId) renameSubtreePrefixes(node, oldId, newId)
+}
+
+function renameSubtreePrefixes(node, oldId, newId) {
+  for (const c of node.children ?? []) {
+    if (c.id?.startsWith(`${oldId}.`)) {
+      c.id = newId + c.id.slice(oldId.length)
+      renameSubtreePrefixes(c, oldId, newId)
+    }
+  }
+}
+
+/** 合并入口：isDone = checklist-done 文件（纯 union——无归档排除）；否则按 done 文件
+ *  当前归档 ID 排除（含点号子 ID——对端 mark-done 归档的项不因本端旧 parse 复活）。 */
+function mergeItems(diskItems, ourItems, doneFile, isDone) {
+  const doneRoots = isDone ? [] : readDoneRoots(doneFile)
+  const doneIds = new Set(doneRoots.map((r) => r.id))
+  const allIds = new Set() // 重分配 max 计算域：双端全树 + 归档根（根层防撞）
+  for (const n of flattenTree(diskItems).concat(flattenTree(ourItems))) {
+    if (n.id != null) allIds.add(n.id)
+  }
+  for (const id of doneIds) allIds.add(id)
+  const env = { isDone, doneIds, allIds, prefix: "T" } // 根层前缀 "T"；子层在 mergeLevel 递归时推导
+  return mergeLevel(diskItems, ourItems, env)
+}

package/src/tools/checklist.mjs

@@ -1,6 +1,9 @@
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs"
+import { readFileSync, existsSync, mkdirSync } from "node:fs"
 import { join, dirname } from "node:path"
 import { DESC } from "./shared.mjs"
+// F4 并发写同步机（门控 + ID union 合并 + 序列化）在 checklist-sync.mjs——本文件只留
+// parse/树操作与工具执行；设计见 MULTI-INSTANCE-COLLAB.md §2a.3（D-F4a/b）。
+import { statMtime, noteReadBaseline, readDoneRoots, flushWrite } from "./checklist-sync.mjs"
 
 const CHECKLIST = "checklist.md"
 const DONE = "checklist-done.md"
@@ -15,8 +18,21 @@ function donePath(cwd) { return join(cwd, ".thincoder", DONE) }
  * "index" is the 1-based position in the flat markdown list.
  */
 function parse(filePath) {
-  if (!existsSync(filePath)) return []
-  const lines = readFileSync(filePath, "utf-8").split("\n")
+  return readItems(filePath, { writeback: true })
+}
+
+/** 读盘 → 建树 → 无 ID 行一次性分配（assignIds）；writeback=true 时（公开 parse 语义）
+ *  分配后立即经 write() 落盘（同走 F4 门控——并发写合并/放弃重分配）。基线在**读前**
+ *  stat（stat→read 序：对端在读与 stat 微窗口写入只造成假合并，绝不漏检静默覆盖）。 */
+function readItems(filePath, { writeback }) {
+  const base = statMtime(filePath) // 基线 = 本链最近 stat（评审修正 #6）
+  let text = null
+  try {
+    if (existsSync(filePath)) text = readFileSync(filePath, "utf-8")
+  } catch { text = null } // 读失败（对端删/半写）→ 按缺失降级
+  noteReadBaseline(filePath, text === null ? null : base)
+  if (text === null) return []
+  const lines = text.split("\n")
   const items = []
   let flatIdx = 0
   const stack = [{ children: items, depth: -1 }] // virtual root
@@ -29,12 +45,12 @@ function parse(filePath) {
     const depth = Math.floor(indent.length / 2) // 2 spaces = 1 level
     const raw = m[2]
     const status = raw === "x" ? "done" : raw === "~" ? "in_progress" : "pending"
-    const text = m[3].trim()
+    const text2 = m[3].trim()
 
     // Strip ALL leading "T[\d.]+:" tokens (historical dirty data can accumulate
     // "T15: T15: T15:"); keep the first token as the ID and the rest as text.
     let id = null
-    let bareText = text
+    let bareText = text2
     let idTok
     while ((idTok = bareText.match(/^(T[\d.]+):\s*/))) {
       if (id == null) id = idTok[1]
@@ -56,7 +72,7 @@ function parse(filePath) {
   function assignIds(nodes, parentId) {
     for (const n of nodes) {
       if (!n.id) {
-        n.id = parentId ? nextChildId(parentId, nodes) : nextRootId(nodes, doneRoots)
+        n.id = parentId ? nextChildId(parentId, nodes, doneIds) : nextRootId(nodes, doneRoots)
         assigned = true
       }
       if (n.children?.length) assignIds(n.children, n.id)
@@ -65,20 +81,15 @@ function parse(filePath) {
   // Root IDs archived to the done file also reserve numbers (mirrors the `add`
   // path's double-file scan), so auto-assigned IDs never collide with them.
   const doneRoots = readDoneRoots(join(dirname(filePath), DONE))
+  const doneIds = doneRoots.map((r) => r.id) // 含点号子 ID——子层分配同样预留
   assignIds(items, null)
-  if (assigned) write(filePath, items)
-
-  return items
-}
-
-function readDoneRoots(doneFile) {
-  if (!existsSync(doneFile)) return []
-  const roots = []
-  for (const line of readFileSync(doneFile, "utf-8").split("\n")) {
-    const m = line.match(/^- \[.\] (T\d+): /)
-    if (m) roots.push({ id: m[1] })
+  if (writeback && assigned) {
+    // 规范化写回（同走门控——F4）：合并发生时返回落盘真相——调用方（add/mark/list）在
+    // 磁盘真值上继续，避免基于过期 parse 再触发一轮合并
+    const r = write(filePath, items)
+    if (r.merged) return r.items
   }
-  return roots
+  return items
 }
 
 function nextRootId(items, doneItems) {
@@ -92,7 +103,7 @@ function nextRootId(items, doneItems) {
   return `T${max + 1}`
 }
 
-function nextChildId(parentId, children) {
+function nextChildId(parentId, children, archivedIds) {
   let max = 0
   const prefix = `${parentId}.`
   for (const c of children) {
@@ -101,27 +112,24 @@ function nextChildId(parentId, children) {
       if (/^\d+$/.test(suffix)) max = Math.max(max, parseInt(suffix))
     }
   }
+  // 归档预留（F4 补正）：已归档同前缀点号 ID 不复用——重加子项撞归档 ID 会被门控合并误删
+  for (const id of archivedIds ?? []) {
+    if (typeof id !== "string" || !id.startsWith(prefix)) continue
+    const suffix = id.slice(prefix.length)
+    if (/^\d+$/.test(suffix)) max = Math.max(max, parseInt(suffix))
+  }
   return `${prefix}${max + 1}`
 }
 
-/** Write items back to file, preserving tree structure */
-function write(filePath, items, _depth = 0) {
-  if (_depth === 0) mkdirSync(dirname(filePath), { recursive: true })
-  const lines = []
-  const indent = "  ".repeat(_depth)
-  for (const item of items) {
-    const mark = item.status === "done" ? "x" : item.status === "in_progress" ? "~" : " "
-    const label = item.id ? `${item.id}: ${item.text}` : item.text
-    lines.push(`${indent}- [${mark}] ${label}`)
-    if (item.children?.length) {
-      lines.push(...write(filePath, item.children, _depth + 1).split("\n").filter(Boolean))
-    }
-  }
-  if (_depth === 0) {
-    writeFileSync(filePath, lines.join("\n") + "\n")
-    return ""
-  }
-  return lines.join("\n")
+/** Write items back to file, preserving tree structure — F4 收口点（门控 + 合并见
+ *  checklist-sync.mjs flushWrite）。返回 { merged, items }（同 flushWrite 契约）。 */
+function write(filePath, items) {
+  mkdirSync(dirname(filePath), { recursive: true })
+  return flushWrite(filePath, items, {
+    reread: () => readItems(filePath, { writeback: false }), // 合并用磁盘重读（无写回）
+    doneFile: join(dirname(filePath), DONE), // checklist 合并的归档排除源
+    isDone: filePath.endsWith(DONE), // done 文件自身 = 纯 union
+  })
 }
 
 /** Find a node by ID in the tree */
@@ -222,11 +230,16 @@ export const checklistTool = {
           parentId = found.item.id
         }
 
-        const id = parentId ? nextChildId(parentId, target) : nextRootId(items, parse(donePath(ctx.cwd)))
+        // 归档预留（根 + 点号子 ID——add 父/子都扫 done 文件；防撞号 + 防合并误删）
+        const doneItems = parse(donePath(ctx.cwd))
+        const id = parentId
+          ? nextChildId(parentId, target, doneItems.map((i) => i.id))
+          : nextRootId(items, doneItems)
         const node = { id, index: 0, depth: parentId ? 1 : 0, status: "pending", text: args.item, children: [] }
         target.push(node)
         write(checklistPath(ctx.cwd), items)
-        return `Added: [ ] ${id}: ${args.item}${parentId ? ` (under ${parentId})` : ""}`
+        // F4：合并可能原地重分配本端新项（并发同号）——以 node.id（落盘真相）报回
+        return `Added: [ ] ${node.id}: ${args.item}${parentId ? ` (under ${parentId})` : ""}`
       }
       case "mark": {
         if (args.id == null && args.index == null) return "Error: 'id' or 'index' is required for mark"