thincoder 0.12.59 → 0.12.60

package/src/memory/docs.mjs

@@ -7,7 +7,8 @@ import { join } from "node:path"
 import { embed, cosine, toBlob, fromBlob } from "../embedding.mjs"
 import { commitAndPush } from "../git/gitmem.mjs"
 import { DOC_EXTS, SKIP_DIRS, MAX_DOC_FILE_BYTES } from "./schema.mjs"
-import { buildFtsQuery, put, search, putMarkdown, deleteByUid, matchMemoryRows, deleteWhere, clearPersonal, EMBED_TEXT_MAX_LEN } from "./core.mjs"
+import { buildFtsQuery, put, search, putMarkdown, clearPersonal, EMBED_TEXT_MAX_LEN } from "./core.mjs"
+import { deleteByUid, matchMemoryRows, deleteWhere } from "./delete.mjs"
 import { _upsertDocFile, yieldTick } from "./code-index.mjs"
 import { markIndexedCommit, listProjectFiles } from "./code-sync.mjs"
 
@@ -165,7 +166,8 @@ export function docSearchTool(memory) {
     name: "doc_search",
     description:
       "Search the project's documentation (README, design docs, guides, markdown files) for relevant information. Use this to find design decisions, coding conventions, architecture docs, or project rules. Prefer this over code_search when you need to understand the project's intended design rather than existing implementation. " +
-      "Returns matching doc chunks: path, heading, line range, relevance score, content excerpt.",
+      "Returns matching doc chunks: path, heading, line range, relevance score, content excerpt. " +
+      "For what was said in sessions (conversation/chat history — decisions, rulings), use read_history.",
     parameters: {
       type: "object",
       properties: {
@@ -188,19 +190,21 @@ export function docSearchTool(memory) {
 // ---------------------------------------------------------------- agent tools
 
 /** §6 shared tool surface — action enum / parameter shapes / descriptions byte-identical
- *  with thincoder-vscode/src/memory.mjs (MEMORY.md §6 D-M1/F-M6); scope VALUES per end
+ *  with thincoder-vscode/src/memory.mjs (MEMORY.md §6 D-M1/F-M6); layer VALUES per end
  *  (VS Code has no team layer and rejects it with CLI guidance). */
 const MEMORY_ACTIONS = ["search", "put", "list", "delete", "clear"]
-const MEMORY_SCOPES = ["personal", "project", "team"]
+const MEMORY_LAYERS = ["personal", "project", "team"]
 const MEMORY_TOOL_DESCRIPTION =
   "Manage long-term memory in ONE tool — the action parameter picks the operation:\n" +
-  "- search — find knowledge saved in previous sessions (query, optional scope/limit); results include every entry's id\n" +
-  "- put — save a piece of knowledge for future sessions (type: rule = coding standards, knowledge = project facts, decision = architecture decisions, pattern = debugging/workflow patterns; title/content/tags/scope)\n" +
-  "- list — inventory what memory holds: optional scope/type/keyword filters, limit default 50; one row per entry: id [type] title (date); a truncated list notes the full count\n" +
-  "- delete — SINGLE: {id, scope} deletes one entry by the id shown in put/search/list output. BATCH: {scope + type and/or keyword} deletes every matching entry in that scope — a call without confirm:true is refused and returns the count plus a preview (re-send with confirm:true to execute); scope-wide wipes without filters are refused on every layer\n" +
-  "- clear — {scope: \"personal\", confirm: true} wipes ALL personal memory entries. clear is personal-only: a missing scope or a project/team scope is refused (use delete batch filters on shared layers)\n" +
+  "- search — find knowledge saved in previous sessions (query, optional layer/limit); result rows start with a [layer] tag and carry the entry id (id prefix = the layer)\n" +
+  "- put — save a piece of knowledge for future sessions (type: rule = coding standards, knowledge = project facts, decision = architecture decisions, pattern = debugging/workflow patterns; title/content/tags; layer defaults to personal)\n" +
+  "- list — inventory what memory holds (optional layer/type/keyword filters, limit default 50); one row per entry: [layer] id [type] title (date); a truncated list notes the full count\n" +
+  "- delete — SINGLE: {id, layer} removes the entry shown in put/search/list output — layer is optional: when passed it is validated against the id prefix (a mismatch is refused — guards against deleting the wrong entry); when omitted the id prefix routes the delete, so any id search/list returned is directly deletable. BATCH (no id): {layer, type and/or keyword} removes every matching entry in that layer — layer and at least one of type/keyword are required, plus confirm:true (without confirm it returns the count plus a preview); layer-wide wipes without filters are refused on every layer\n" +
+  "- clear — {layer: \"personal\", confirm: true} wipes ALL personal memory entries. clear is personal-only: a missing layer or a project/team layer is refused (use delete batch filters on shared layers)\n" +
+  "Layer is the memory tier: personal (private), project (shared via this repo's .thincoder/memory/), team (CLI only, git-synced). The [layer] tag on search/list result rows, the row's id prefix, and the layer parameter are the same concept — pass a result row's [layer] as layer, or omit it on a single delete to auto-route by the id prefix.\n" +
   "Deleting project/team (CLI) entries removes the local markdown file and its index row — team deletion is local only and a later team sync may resurrect the file while the remote still has it.\n" +
-  "Save bugs, conventions, and preferences here — they persist across sessions."
+  "Save bugs, conventions, and preferences here — they persist across sessions.\n" +
+  "Session message history (what was said in this or past sessions) is NOT in memory — search session messages with read_history."
 
 function validateTypeFilter(type) {
   if (type === undefined || type === null || type === "") return null
@@ -218,13 +222,13 @@ function fmtDate(ts) {
   return ts ? new Date(ts).toISOString().slice(0, 10) : "?"
 }
 
-const listRowLine = (r) => `${r.id} [${r.type}] ${r.title}（${fmtDate(r.ts)}）`
+const listRowLine = (r) => `[${r.layer}] ${r.id} [${r.type}] ${r.title}（${fmtDate(r.ts)}）`
 
 /**
  * Generate the memory agent tool — ONE `memory` tool with five actions (MEMORY.md §6 D-M1).
  * search/list are read-only actions (planMode pass / no permission ask — dispatch classifies
  * them action-level, same as subagent check/status); put keeps its side-effect permission
- * gate; batch delete/clear gate on confirm:true + scope inside the tool (direct-delete
+ * gate; batch delete/clear gate on confirm:true + layer inside the tool (direct-delete
  * ruling — the confirm parameter IS the gate) and stay non-readonly like the retired tools.
  * opts: { cwd, projectDir, author, team: { dir, name } | null }
  */
@@ -239,7 +243,7 @@ export function memoryTools(memory, opts = {}) {
         type: "object",
         properties: {
           action: { type: "string", enum: MEMORY_ACTIONS, description: "Operation to run (required)" },
-          scope: { type: "string", enum: MEMORY_SCOPES, description: "Where the memory lives: personal (private), project (shared via this repo's .thincoder/memory/), team (CLI only). put defaults to personal; search/list search every layer when omitted; delete/clear require it" },
+          layer: { type: "string", enum: MEMORY_LAYERS, description: "The memory layer: personal (private), project (shared via this repo's .thincoder/memory/), team (CLI only). Same concept as the [layer] tag and the id prefix on search/list result rows. put/search/list: optional (put defaults to personal; search/list omit = all layers). single delete: optional (omit = route by id prefix). batch delete/clear: required" },
           type: { type: "string", enum: ["rule", "knowledge", "decision", "pattern"], description: "Entry type: put = what to save; list/delete batch = filter by type" },
           title: { type: "string", description: "put: short title" },
           content: { type: "string", description: "put: full content to remember" },
@@ -272,21 +276,21 @@ export function memoryTools(memory, opts = {}) {
 
 /** action search — the retired search tool surface (read-only, same output contract). */
 async function execSearch(memory, args) {
-  const scope = args.scope
-  if (scope !== undefined && scope !== null && !MEMORY_SCOPES.includes(String(scope))) {
-    throw new Error(`memory search: invalid scope "${scope}"`)
+  const layer = args.layer
+  if (layer !== undefined && layer !== null && !MEMORY_LAYERS.includes(String(layer))) {
+    throw new Error(`memory search: invalid layer "${layer}"`)
   }
   const query = String(args.query ?? "").trim()
   if (!query) return "(no matching memories)" // 空 query 短路——两端同语义（评审 code review #4）
   const limit = normalizeLimit(args.limit, 5)
   let results
-  if (!scope) {
+  if (!layer) {
     results = await search(memory, query, { limit })
   } else {
-    // scope filter: oversample then slice the requested layer (results keep global rank order).
+    // layer filter: oversample then slice the requested layer (results keep global rank order).
     // 窗口 = max(limit*4, 20) 是召回上限——大库 + 高 limit 时该层结果可能不足 limit（接受的取舍——评审 code review #3）
     const wide = await search(memory, query, { limit: Math.max(limit * 4, 20) })
-    results = wide.filter((r) => r.layer === String(scope)).slice(0, limit)
+    results = wide.filter((r) => r.layer === String(layer)).slice(0, limit)
   }
   if (results.length === 0) return "(no matching memories)"
   return results.map((r) => `[${r.layer}][${r.type}] ${r.title} (id=${r.id})\n${r.content}`).join("\n\n")
@@ -294,14 +298,14 @@ async function execSearch(memory, args) {
 
 /** action put — the retired put tool surface (side-effect gate, unchanged semantics). */
 async function execPut(memory, args, opts, dirs) {
-  const scope = String(args.scope ?? "personal")
-  if (!MEMORY_SCOPES.includes(scope)) throw new Error(`memory put: invalid scope "${scope}"`)
-  if (scope === "personal") {
+  const layer = String(args.layer ?? "personal")
+  if (!MEMORY_LAYERS.includes(layer)) throw new Error(`memory put: invalid layer "${layer}"`)
+  if (layer === "personal") {
     const id = await put(memory, { type: args.type, title: args.title, content: args.content, tags: args.tags ?? "" })
     return `Saved to personal memory (id=personal:${id}): [${args.type}] ${args.title}`
   }
-  if (scope === "project") {
-    if (!dirs.project) throw new Error("project scope unavailable: no project directory configured")
+  if (layer === "project") {
+    if (!dirs.project) throw new Error("project layer unavailable: no project directory configured")
     const filename = await putMarkdown(memory, {
       layer: "project",
       dir: dirs.project,
@@ -314,7 +318,7 @@ async function execPut(memory, args, opts, dirs) {
     return `Saved to project memory (id=project:${dirs.project}:${filename}): [${args.type}] ${args.title}`
   }
   if (!dirs.team) {
-    throw new Error("team scope not configured: set memory.team in ~/.thincoder/config.json")
+    throw new Error("team layer not configured: set memory.team in ~/.thincoder/config.json")
   }
   const filename = await putMarkdown(memory, {
     layer: "team",
@@ -329,12 +333,12 @@ async function execPut(memory, args, opts, dirs) {
   return `Saved to team memory and pushed (id=team:${dirs.team}:${filename}): [${args.type}] ${args.title}`
 }
 
-/** action list — new inventory action (read-only): scope/type/keyword filters + limit truncation note. */
+/** action list — new inventory action (read-only): layer/type/keyword filters + limit truncation note. */
 async function execList(memory, args, dirs) {
-  const scope = args.scope ?? null
-  if (scope && !MEMORY_SCOPES.includes(String(scope))) throw new Error(`memory list: invalid scope "${scope}"`)
+  const layer = args.layer ?? null
+  if (layer && !MEMORY_LAYERS.includes(String(layer))) throw new Error(`memory list: invalid layer "${layer}"`)
   const rows = await matchMemoryRows(memory, {
-    scope: scope ? String(scope) : null,
+    layer: layer ? String(layer) : null,
     type: validateTypeFilter(args.type),
     keyword: args.keyword ? String(args.keyword).trim() : null,
     projectDir: dirs.project,
@@ -348,22 +352,23 @@ async function execList(memory, args, dirs) {
   return lines.join("\n")
 }
 
-/** action delete — single ({ id, scope } — §0.1-era single-delete semantics) + batch (scope + type/keyword + confirm). */
+/** action delete — single ({ id, layer? } — MEMORY.md §6.2: layer OPTIONAL, validated when
+ *  passed, else the id prefix routes the delete) + batch (layer + type/keyword + confirm). */
 async function execDelete(memory, args, dirs) {
   const hasId = args.id !== undefined && args.id !== null && String(args.id) !== ""
   if (hasId) return execDeleteSingle(memory, args, dirs)
   // batch form
-  const scope = args.scope
-  if (!scope) throw new Error("batch delete requires scope plus type and/or keyword filter")
-  if (!MEMORY_SCOPES.includes(String(scope))) throw new Error(`memory delete: invalid scope "${scope}"`)
+  const layer = args.layer
+  if (!layer) throw new Error("batch delete requires layer plus type and/or keyword filter")
+  if (!MEMORY_LAYERS.includes(String(layer))) throw new Error(`memory delete: invalid layer "${layer}"`)
   const type = validateTypeFilter(args.type)
   const keyword = args.keyword ? String(args.keyword).trim() : null
   if (!type && !keyword) {
-    throw new Error("batch delete requires type and/or keyword filter — a scope-wide wipe without filters is refused (personal full wipe is the clear action)")
+    throw new Error("batch delete requires type and/or keyword filter — a layer-wide wipe without filters is refused (personal full wipe is the clear action)")
   }
-  if (scope === "project" && !dirs.project) throw new Error("project scope unavailable: no project directory configured")
-  if (scope === "team" && !dirs.team) throw new Error("team scope not configured: set memory.team in ~/.thincoder/config.json")
-  const filters = { scope: String(scope), type, keyword }
+  if (layer === "project" && !dirs.project) throw new Error("project layer unavailable: no project directory configured")
+  if (layer === "team" && !dirs.team) throw new Error("team layer not configured: set memory.team in ~/.thincoder/config.json")
+  const filters = { layer: String(layer), type, keyword }
   const rows = await matchMemoryRows(memory, { ...filters, projectDir: dirs.project, teamDir: dirs.team })
   if (rows.length === 0) return "0 条匹配"
   if (args.confirm !== true) {
@@ -374,27 +379,32 @@ async function execDelete(memory, args, dirs) {
     return lines.join("\n")
   }
   const n = await deleteWhere(memory, filters, { dirs })
-  return `Deleted ${n} entries in scope ${scope}`
+  return `Deleted ${n} entries in layer ${layer}`
 }
 
-/** Single-entry delete — §0.1-era delete semantics (id + scope, NF2/NF3, direct-delete ruling). */
+/** Single-entry delete — MEMORY.md §6.2: layer is OPTIONAL. When passed it is validated
+ *  against the id prefix (mismatch refused — guards against deleting the wrong entry); when
+ *  omitted the delete routes by the id prefix alone, so any id search/list returned is
+ *  directly deletable (deleteByUid already resolves the layer from the uid prefix). */
 async function execDeleteSingle(memory, args, dirs) {
-  if (!args.scope) throw new Error("delete requires id + scope")
   const uid = String(args.id)
   const prefix = uid.split(":")[0]
-  const uidScope = prefix === "personal" || prefix === "project" || prefix === "team" ? prefix : /^\d+$/.test(prefix) ? "personal" : null
-  if (!uidScope) throw new Error(`invalid memory id: ${uid}`)
-  if (uidScope !== args.scope) throw new Error(`id prefix ${prefix}: 与 scope ${args.scope} 不匹配`)
+  const uidLayer = prefix === "personal" || prefix === "project" || prefix === "team" ? prefix : /^\d+$/.test(prefix) ? "personal" : null
+  if (!uidLayer) throw new Error(`invalid memory id: ${uid}`)
+  const layer = args.layer
+  if (layer !== undefined && layer !== null && String(layer) !== uidLayer) {
+    throw new Error(`id prefix ${prefix}: 与 layer ${layer} 不匹配`)
+  }
   const entry = await deleteByUid(memory, uid, { dirs })
   return `Deleted ${entry.id}: ${entry.title}\n${(entry.content ?? "").slice(0, 500)}`
 }
 
-/** action clear — personal-only full wipe (scope + confirm:true gates; project/team refused). */
+/** action clear — personal-only full wipe (layer + confirm:true gates; project/team refused). */
 function execClear(memory, args) {
-  const scope = args.scope
-  if (!scope) throw new Error('clear requires scope "personal" — pass scope: "personal" plus confirm: true')
-  if (String(scope) !== "personal") {
-    if (!MEMORY_SCOPES.includes(String(scope))) throw new Error(`memory clear: invalid scope "${scope}"`)
+  const layer = args.layer
+  if (!layer) throw new Error('clear requires layer "personal" — pass layer: "personal" plus confirm: true')
+  if (String(layer) !== "personal") {
+    if (!MEMORY_LAYERS.includes(String(layer))) throw new Error(`memory clear: invalid layer "${layer}"`)
     throw new Error("shared layers don't support clear — use delete with type/keyword batch filters instead")
   }
   if (args.confirm !== true) throw new Error("clear requires confirm:true — this wipes ALL personal memory")

package/src/memory.mjs

@@ -7,7 +7,9 @@
 export { createMemory, migrate, segmentCJK, VALID_TYPES, SCHEMA_VERSION, CODE_EXTS, DOC_EXTS, SKIP_DIRS, BIG_FILE_LINES } from "./memory/schema.mjs"
 
 // CRUD + search + ensureEmbeddings
-export { put, search, ftsSearch, fetchEntry, ensureEmbeddings, putMarkdown, syncDir, indexMarkdownFile, list, remove, deleteByUid, matchMemoryRows, deleteWhere, clearPersonal, buildFtsQuery } from "./memory/core.mjs"
+// (delete.mjs owns the disk-truth row match + deletion family — see its header)
+export { put, search, ftsSearch, fetchEntry, ensureEmbeddings, putMarkdown, syncDir, indexMarkdownFile, list, clearPersonal, buildFtsQuery } from "./memory/core.mjs"
+export { matchMemoryRows, deleteWhere, deleteByUid, remove } from "./memory/delete.mjs"
 
 // code chunking + markdown chunking
 export { detectLanguage, extractSymbols, extractPySymbols, chunkCode, extractLeadingDoc, yieldTick, _upsertCodeFile, chunkMarkdown, _upsertDocFile } from "./memory/code-index.mjs"

package/src/peer-domains.mjs

@@ -0,0 +1,265 @@
+/**
+ * peer-domains.mjs — R10 多实例协作 L3 文件写域登记 + 冲突检测（MULTI-INSTANCE-COLLAB
+ * §2a.5——评审修正 #8：独立文件，防 300 行超限）。
+ *
+ * 登记存储（D-L3a）：~/.thincoder/peers/{sessionId}.json——每实例单文件、单写者（本
+ * 进程——end marker 同型模式）；内容 {sessionId, pid, end, cwd, domains[绝对路径],
+ * updatedAt}。写点 = 回合级：写工具钩子累积"本回合实际写过的文件"（D-L3b 同一钩子——
+ * 检测+记录一次完成）→ 回合结束 flush 整写一次（finalizeAgentTurn）；本回合无写入则
+ * 不写（文件按自身 updatedAt 自然过期——hot 5 分钟窗口语义不被空回合提前清掉）。
+ *
+ * 冲突检测（D-L3b）：结构化写工具（PEER_WRITE_TOOLS）执行前查 conflicts——命中他实例
+ * hot 域 → 工具结果附软提示（决策⑥ A：不阻止）。缓存（评审修正 #2）：聚合结果按 peers
+ * 目录 mtime 惰性缓存——目录未变零扫描；单次写工具调用新增开销上限 = 目录 stat 一次
+ * （N3 度量）。崩溃残留：聚合时惰性清理（死 pid 文件删除——batchAlive 一次批量）；
+ * 损坏文件按缺失降级（end marker NF2 同型——不删不炸，属主下次 flush 覆盖）。
+ */
+
+import { statSync, readdirSync, readFileSync, unlinkSync } from "node:fs"
+import { join, resolve, sep } from "node:path"
+import { configDir } from "./config.mjs"
+import { normalizeCwd, getSessionId, END, writeSessionFile } from "./session-slots.mjs"
+import { batchAlive } from "./peer-instances.mjs"
+import { FILE_MUTATORS } from "./agent/helpers.mjs"
+
+/** hot 窗口：登记（回合足迹 flush）后 5 分钟内视为 hot（决策⑤ A——"刚写过"语义） */
+export const HOT_WINDOW_MS = 5 * 60 * 1000
+
+/** L3 覆盖的结构化写工具（D-L3b 清单）——既有 FILE_MUTATORS（write/edit/insert_after/
+ *  hashline_edit/apply_patch/delete）∪ file_ops。insert_after/hashline_edit 亦为结构化
+ *  写工具（同一文件写入面），file_ops 在 FILE_MUTATORS 之外故显式并入。 */
+export const PEER_WRITE_TOOLS = new Set([...FILE_MUTATORS, "file_ops"])
+
+export function peersDir() {
+  return join(configDir, "peers")
+}
+
+export function peerFilePath(sessionId) {
+  return join(peersDir(), `${sessionId}.json`)
+}
+
+// 模块级测试注入缝（default null = 生产实现；测试注入 + finally 恢复）
+let _testAliveFn = null
+
+/** 注入聚合判活实现（批量判活计数/去真实 exec——T-L3b 死清理用例可用真死 pid 亦可注入）。 */
+export function _setPeerDomainsTestImpl({ aliveFn = undefined } = {}) {
+  const prev = _testAliveFn
+  _testAliveFn = aliveFn ?? null
+  peersDirCache = null // 注入即环境变更——目录缓存失效（测试间不串）
+  return prev
+}
+
+export function _resetPeerDomainsTestImpl() {
+  _testAliveFn = null
+  peersDirCache = null
+}
+
+// peers 目录 mtime 惰性缓存（评审修正 #2）——单全局项（peers 目录全局唯一）
+let peersDirCache = null // { mtimeMs, peers: [...] }
+
+function statDirMtimeMs(dir) {
+  try {
+    return statSync(dir).mtimeMs
+  } catch {
+    return null // 目录缺失
+  }
+}
+
+/** 目标路径解析（工具 touchedPaths 优先——apply_patch/edit-batch 多文件；file_ops 无
+ *  touchedPaths——source/dest 双算；其余 path 单参兜底）。相对路径按 cwd 解析为绝对
+ *  路径（resolve：绝对入参原样保留）。解析失败/畸形入参跳过（零目标 = 无检测无登记）。 */
+export function peerWriteTargets(tool, args, cwd) {
+  const raw = tool?.touchedPaths
+    ? tool.touchedPaths(args ?? {})
+    : tool?.name === "file_ops"
+      ? [args?.source, args?.dest]
+      : [args?.path]
+  const out = []
+  for (const p of raw) {
+    if (typeof p !== "string" || p.length === 0) continue
+    try {
+      out.push(resolve(cwd, p))
+    } catch {
+      /* 畸形路径跳过——检测/登记尽力而为 */
+    }
+  }
+  return out
+}
+
+/** 路径重叠：a 与 b 相等或互为目录包含（file_ops 目录级操作/delete 整目录语义——
+ *  区分大小写按平台（Windows 文件系统不区分）；分隔符归一（resolve 产物为原生分隔符，
+ *  入参可能混用 / 与 \）。 */
+export function pathsOverlap(a, b) {
+  const norm = (p) => {
+    const n = process.platform === "win32" ? p.toLowerCase() : p
+    return (process.platform === "win32" ? n.replace(/\//g, "\\") : n.replace(/\\/g, "/")).replace(/[\\/]+$/, "")
+  }
+  const pa = norm(a)
+  const pb = norm(b)
+  if (pa === pb) return true
+  const sepN = process.platform === "win32" ? "\\" : "/"
+  const prefix = (p, q) => p === q || p.startsWith(q + sepN)
+  return prefix(pa, pb) || prefix(pb, pa)
+}
+
+/** 扫描 peers 目录：解析每文件 + 一次批量判活全部 pid + 死登记惰性清理（unlink——
+ *  崩溃残留）；损坏文件按缺失降级（不删——属主下次 flush 覆盖）。返回活登记
+ *  [{ sessionId, pid, end, cwd, domains, updatedAt }]。目录缺失/不可读 → []。 */
+function scanPeersDir() {
+  let files = []
+  try {
+    files = readdirSync(peersDir(), { withFileTypes: true })
+      .filter((e) => e.isFile() && e.name.endsWith(".json"))
+      .map((e) => join(peersDir(), e.name))
+  } catch {
+    return [] // 目录缺失（从未 flush）→ 无登记
+  }
+  const parsed = []
+  for (const file of files) {
+    try {
+      const rec = JSON.parse(readFileSync(file, "utf8"))
+      if (rec && typeof rec === "object" && typeof rec.sessionId === "string" && rec.sessionId.length > 0
+        && Number.isInteger(Number(rec.pid)) && Number(rec.pid) > 0
+        && typeof rec.cwd === "string" && Array.isArray(rec.domains)) {
+        parsed.push({ file, rec })
+      }
+      // 结构非法 = 损坏 → 按缺失降级（不删——NF2 同型）
+    } catch {
+      /* 解析失败同损坏 */
+    }
+  }
+  if (parsed.length === 0) return []
+  const aliveFn = _testAliveFn ?? batchAlive
+  const alive = aliveFn([...new Set(parsed.map((p) => Number(p.rec.pid)))])
+  // 判活探测失败（batchAlive → null）≠ 死：不得据此执行死清理（unlink 是破坏性副作用）
+  // ——返回 null 信号：调用方不缓存空聚合（下轮调用重试探测）
+  if (!(alive instanceof Set)) return null
+  const live = []
+  for (const { file, rec } of parsed) {
+    if (!alive.has(Number(rec.pid))) {
+      try {
+        // 死登记惰性清理（崩溃残留——聚合时一次批量判活顺带删除）
+        unlinkSync(file)
+      } catch { /* unlink 失败不影响聚合（下次再试） */ }
+      continue
+    }
+    live.push({
+      sessionId: rec.sessionId,
+      pid: Number(rec.pid),
+      end: typeof rec.end === "string" ? rec.end : undefined,
+      cwd: rec.cwd,
+      domains: rec.domains.filter((d) => typeof d === "string"),
+      updatedAt: Number(rec.updatedAt) || 0,
+    })
+  }
+  return live
+}
+
+/** peers 目录 mtime 惰性缓存聚合（评审修正 #2——目录未变不重扫）。返回当前目录下全部
+ *  活登记（含他 cwd 实例——死清理跨 cwd 一次批量；cwd 过滤在 peerDomains）。 */
+function cachedScan() {
+  const dir = peersDir()
+  const mtime = statDirMtimeMs(dir)
+  if (mtime == null) {
+    peersDirCache = null
+    return []
+  }
+  if (peersDirCache && peersDirCache.mtimeMs === mtime) return peersDirCache.peers
+  const peers = scanPeersDir()
+  if (peers === null) {
+    peersDirCache = null // 探测失败——不缓存空聚合（下轮调用重试探测——失败 ≠ 无登记）
+    return []
+  }
+  // 死清理删文件会改目录 mtime——以清理后的 mtime 缓存（下次 stat 命中即不重扫）
+  peersDirCache = { mtimeMs: statDirMtimeMs(dir) ?? mtime, peers }
+  return peers
+}
+
+/**
+ * 聚合（D-L3a）：本 cwd（normalizeCwd 同构比较）的其他活实例登记（self 排除——
+ *  sessionId === getSessionId()）。返回 [{ sessionId, pid, end, cwd, domains, updatedAt }]。
+ * 纯只读；缓存命中 = 目录 stat 一次（N3）。
+ */
+export function peerDomains(cwd) {
+  const normCwd = normalizeCwd(cwd)
+  const myId = getSessionId()
+  return cachedScan().filter((p) => p.sessionId !== myId && normalizeCwd(p.cwd) === normCwd)
+}
+
+/**
+ * 冲突检测（D-L3b——写前查询）：targets（绝对路径）命中他实例 hot 域（updatedAt 在
+ * HOT_WINDOW_MS 内且域含 target/互为包含）→ 返回 [{ target, by: [{end, pid, sessionId}] }]。
+ * 无冲突/无目标 → []。纯只读、不抛（内部全降级——失败按零冲突）。
+ */
+export function conflicts(cwd, targets, { now = Date.now() } = {}) {
+  if (!Array.isArray(targets) || targets.length === 0) return []
+  let peers = []
+  try {
+    peers = peerDomains(cwd)
+  } catch {
+    return []
+  }
+  const hot = peers.filter((p) => p.domains.length > 0 && now - p.updatedAt <= HOT_WINDOW_MS)
+  if (hot.length === 0) return []
+  const hits = []
+  for (const target of targets) {
+    const by = hot.filter((p) => p.domains.some((d) => pathsOverlap(target, d)))
+    if (by.length > 0) hits.push({ target, by: by.map((p) => ({ end: p.end, pid: p.pid, sessionId: p.sessionId })) })
+  }
+  return hits
+}
+
+/** dispatch 写工具钩子预检：命中他实例 hot 域 → 软提示文案（null = 无冲突/无目标/
+ *  降级——调用方零附加）。一次目录 stat（缓存命中零扫描——N3 度量）。 */
+export function peerCollabNote(cwd, tool, args) {
+  try {
+    const targets = peerWriteTargets(tool, args, cwd)
+    if (targets.length === 0) return null
+    const hits = conflicts(cwd, targets)
+    if (hits.length === 0) return null
+    return hits.map((h) => {
+      const who = h.by.map((p) => (p.end ? `${p.end} pid=${p.pid}` : `pid=${p.pid}`)).join(", ")
+      return `[peer-collab] ${h.target} — another live instance (${who}) registered writing it within the last 5 minutes; concurrent edits may overwrite each other. Write not blocked — coordinate before proceeding.`
+    }).join("\n")
+  } catch {
+    return null // 感知失败绝不打扰工具执行
+  }
+}
+
+/** 记录本回合写足迹（D-L3a 累积——D-L3b 同一钩子执行后调用；仅成功写计入"实际写过"）。
+ *  agent._peerWritten: Set<绝对路径>（回合级——finalizeAgentTurn flush 时整写并清空）。 */
+export function recordPeerWrites(agent, tool, args) {
+  try {
+    const targets = peerWriteTargets(tool, args, agent.cwd)
+    if (targets.length === 0) return
+    agent._peerWritten ??= new Set()
+    for (const t of targets) agent._peerWritten.add(t)
+  } catch {
+    /* 记录失败不影响工具结果 */
+  }
+}
+
+/**
+ * 回合末登记 flush（D-L3a——finalizeAgentTurn 调用）：本回合足迹整写一次本实例文件
+ * （单写者；.tmp+rename 原子——writeSessionFile）。本回合无写入 → 不写（文件按自身
+ * updatedAt 自然过期——hot 窗口不被空回合提前清掉；低频 N3）。写失败容忍（NF2——end
+ * marker 同型）；成功 flush 后清空回合集合。不抛（调用方回合收尾零风险）。
+ */
+export function flushPeerDomains(agent) {
+  try {
+    const set = agent._peerWritten
+    if (!set || set.size === 0) return
+    const sessionId = getSessionId()
+    writeSessionFile(peerFilePath(sessionId), {
+      sessionId,
+      pid: process.pid,
+      end: END,
+      cwd: normalizeCwd(agent.cwd),
+      domains: [...set],
+      updatedAt: Date.now(),
+    })
+    set.clear()
+  } catch {
+    /* NF2：失败容忍——下次 flush 重写 */
+  }
+}