thincoder 0.12.58 → 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, 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"
 
@@ -164,7 +165,9 @@ export function docSearchTool(memory) {
   return {
     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.",
+      "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. " +
+      "For what was said in sessions (conversation/chat history — decisions, rulings), use read_history.",
     parameters: {
       type: "object",
       properties: {
@@ -186,9 +189,47 @@ 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); 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_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 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.\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
+  const t = String(type)
+  if (!["rule", "knowledge", "decision", "pattern"].includes(t)) throw new Error(`Invalid memory type "${t}"; expected one of: rule, knowledge, decision, pattern`)
+  return t
+}
+
+function normalizeLimit(limit, dflt) {
+  const n = Number(limit)
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : dflt
+}
+
+function fmtDate(ts) {
+  return ts ? new Date(ts).toISOString().slice(0, 10) : "?"
+}
+
+const listRowLine = (r) => `[${r.layer}] ${r.id} [${r.type}] ${r.title}（${fmtDate(r.ts)}）`
+
 /**
- * Generate the three memory-related agent tools (following the tools.mjs tool shape).
- * memory_put and memory_delete are side-effecting (need permission confirmation), memory_search is read-only.
+ * 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 + 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 }
  */
 export function memoryTools(memory, opts = {}) {
@@ -196,99 +237,177 @@ export function memoryTools(memory, opts = {}) {
   const dirs = { project: projectDir, team: opts.team?.dir ?? null }
   return [
     {
-      name: "memory_put",
-      description:
-        "Save a piece of knowledge to long-term memory. Use when you learn something worth remembering across sessions: a project convention, a debugging insight, an architecture decision. Types: rule (coding standards), knowledge (project facts), decision (architecture decisions), pattern (debugging/workflow patterns). Scopes: personal (default, private to you), project (shared via this repo's .thincoder/memory/), team (org-wide team repo, if configured).",
+      name: "memory",
+      description: MEMORY_TOOL_DESCRIPTION,
       parameters: {
         type: "object",
         properties: {
-          type: { type: "string", enum: ["rule", "knowledge", "decision", "pattern"] },
-          title: { type: "string", description: "Short title" },
-          content: { type: "string", description: "Full content to remember" },
-          tags: { type: "string", description: "Space-separated tags" },
-          scope: { type: "string", enum: ["personal", "project", "team"], description: "Where to save (default personal)" },
+          action: { type: "string", enum: MEMORY_ACTIONS, description: "Operation to run (required)" },
+          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" },
+          tags: { type: "string", description: "put: space-separated tags" },
+          query: { type: "string", description: "search: natural-language query" },
+          keyword: { type: "string", description: "list/delete batch: filter matching title/content" },
+          id: { type: "string", description: "delete single: the entry id from put/search/list output" },
+          limit: { type: "number", description: "Max rows: list 50 by default, search 5 by default" },
+          confirm: { type: "boolean", description: "delete batch/clear: must be true — without it the tool refuses" },
         },
-        required: ["type", "title", "content"],
+        required: ["action"],
       },
       readonly: false,
       async execute(args) {
-        const scope = args.scope ?? "personal"
-        if (scope === "personal") {
-          const id = await put(memory, args)
-          return `Saved to personal memory (id=personal:${id}): [${args.type}] ${args.title}`
-        }
-        if (scope === "project") {
-          if (!projectDir) throw new Error("project scope unavailable: no project directory configured")
-          const filename = await putMarkdown(memory, {
-            layer: "project",
-            dir: projectDir,
-            type: args.type,
-            title: args.title,
-            content: args.content,
-            tags: (args.tags ?? "").split(/\s+/).filter(Boolean),
-            author: opts.author ?? "unknown",
-          })
-          return `Saved to project memory (id=project:${projectDir}:${filename}): [${args.type}] ${args.title}`
+        const action = String(args?.action ?? "")
+        if (!MEMORY_ACTIONS.includes(action)) {
+          throw new Error(`memory: unknown action "${action}" — expected one of: ${MEMORY_ACTIONS.join("/")}`)
         }
-        if (!opts.team?.dir) {
-          throw new Error("team scope not configured: set memory.team in ~/.thincoder/config.json")
+        switch (action) {
+          case "search": return execSearch(memory, args)
+          case "put": return execPut(memory, args, opts, dirs)
+          case "list": return execList(memory, args, dirs)
+          case "delete": return execDelete(memory, args, dirs)
+          case "clear": return execClear(memory, args)
         }
-        const filename = await putMarkdown(memory, {
-          layer: "team",
-          dir: opts.team.dir,
-          type: args.type,
-          title: args.title,
-          content: args.content,
-          tags: (args.tags ?? "").split(/\s+/).filter(Boolean),
-          author: opts.author ?? "unknown",
-        })
-        await commitAndPush(opts.team.dir, filename, `memory: [${args.type}] ${args.title}`)
-        return `Saved to team memory and pushed (id=team:${opts.team.dir}:${filename}): [${args.type}] ${args.title}`
-      },
-    },
-    {
-      name: "memory_search",
-      description:
-        "Search long-term memory across all layers (personal/project/team) for relevant knowledge saved in previous sessions. Use the same language as the memories being searched.",
-      parameters: {
-        type: "object",
-        properties: {
-          query: { type: "string", description: "Natural language search query" },
-          limit: { type: "number", description: "Max results (default 5)" },
-        },
-        required: ["query"],
-      },
-      readonly: true,
-      async execute(args) {
-        const results = await search(memory, args.query, { limit: args.limit ?? 5 })
-        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")
-      },
-    },
-    {
-      name: "memory_delete",
-      description:
-        "Delete a memory entry by its id (as returned by memory_put / memory_search) and scope. " +
-        "Scope is required and must match the id prefix — this prevents accidental deletion in another scope. " +
-        "Returns the deleted entry's title and content so the deletion is auditable and recoverable.",
-      parameters: {
-        type: "object",
-        properties: {
-          id: { type: "string", description: "Entry id: personal:<n> / project:<origin>:<path> / team:<origin>:<path>" },
-          scope: { type: "string", enum: ["personal", "project", "team"], description: "Scope of the entry to delete (required)" },
-        },
-        required: ["id", "scope"],
-      },
-      readonly: false,
-      async execute(args) {
-        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 entry = await deleteByUid(memory, uid, { dirs })
-        return `Deleted ${entry.id}: ${entry.title}\n${(entry.content ?? "").slice(0, 500)}`
       },
     },
   ]
 }
+
+/** action search — the retired search tool surface (read-only, same output contract). */
+async function execSearch(memory, args) {
+  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 (!layer) {
+    results = await search(memory, query, { limit })
+  } else {
+    // 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(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")
+}
+
+/** action put — the retired put tool surface (side-effect gate, unchanged semantics). */
+async function execPut(memory, args, opts, dirs) {
+  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 (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,
+      type: args.type,
+      title: args.title,
+      content: args.content,
+      tags: (args.tags ?? "").split(/\s+/).filter(Boolean),
+      author: opts.author ?? "unknown",
+    })
+    return `Saved to project memory (id=project:${dirs.project}:${filename}): [${args.type}] ${args.title}`
+  }
+  if (!dirs.team) {
+    throw new Error("team layer not configured: set memory.team in ~/.thincoder/config.json")
+  }
+  const filename = await putMarkdown(memory, {
+    layer: "team",
+    dir: dirs.team,
+    type: args.type,
+    title: args.title,
+    content: args.content,
+    tags: (args.tags ?? "").split(/\s+/).filter(Boolean),
+    author: opts.author ?? "unknown",
+  })
+  await commitAndPush(dirs.team, filename, `memory: [${args.type}] ${args.title}`)
+  return `Saved to team memory and pushed (id=team:${dirs.team}:${filename}): [${args.type}] ${args.title}`
+}
+
+/** action list — new inventory action (read-only): layer/type/keyword filters + limit truncation note. */
+async function execList(memory, args, dirs) {
+  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, {
+    layer: layer ? String(layer) : null,
+    type: validateTypeFilter(args.type),
+    keyword: args.keyword ? String(args.keyword).trim() : null,
+    projectDir: dirs.project,
+    teamDir: dirs.team,
+  })
+  if (rows.length === 0) return "0 条匹配"
+  const limit = normalizeLimit(args.limit, 50)
+  const shown = rows.slice(0, limit)
+  const lines = shown.map(listRowLine)
+  if (rows.length > shown.length) lines.unshift(`${shown.length} 条——截断前 ${rows.length}`)
+  return lines.join("\n")
+}
+
+/** 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 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 layer-wide wipe without filters is refused (personal full wipe is the clear action)")
+  }
+  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) {
+    const lines = [rows.length > 5 ? `将删 ${rows.length} 条：前 5 条预览` : `将删 ${rows.length} 条`]
+    lines.push(...rows.slice(0, 5).map(listRowLine))
+    if (rows.length > 5) lines.push(`5 条——截断前 ${rows.length}`)
+    lines.push("confirm:true required — re-send with it to execute the deletion")
+    return lines.join("\n")
+  }
+  const n = await deleteWhere(memory, filters, { dirs })
+  return `Deleted ${n} entries in layer ${layer}`
+}
+
+/** 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) {
+  const uid = String(args.id)
+  const prefix = uid.split(":")[0]
+  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 (layer + confirm:true gates; project/team refused). */
+function execClear(memory, args) {
+  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")
+  const n = clearPersonal(memory)
+  return `Cleared personal memory (${n} entries deleted)`
+}

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, 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/model-specs.mjs

@@ -88,7 +88,13 @@ const MODEL_SPECS = [
 ]
 const DEFAULT_SPEC = { context: 128_000, maxOutput: 32_000, cacheMode: "none" }
 
-/** Look up spec by model name prefix (case-insensitive), conservative default for unknown models */
+/** Look up spec by model name prefix (case-insensitive), conservative default for unknown models.
+ *
+ * Vendor-namespace prefix stripping (2026-09-04)：第三方 token 市场（roapi/new-api/one-api/
+ * aiproxy 聚合网关）惯例在模型名前加厂商前缀（zhipu/glm-5.3、openai/gpt-4o）。完整名未命中
+ * 且含 "/" 时，剥掉第一个 "/" 前的 namespace 再按前缀匹配一次——ZHIPU/GLM-5.3 → glm-5.3 命中
+ * 真实规格，不再降级 128K 默认。kimi/kimi-k3 的显式 alias 行保留为文档锚（发送路径
+ * provider.core isRouter 依赖含 "/" 判定），通用机制已覆盖同类。 */
 const warnedModels = new Set() // warn once per model name — specForModel is a hot path (every request)
 // Pre-sorted once at module scope — specForModel runs on every request (agent, provider core,
 // context, auto-think, TUI rendering); re-sorting per call was wasteful.
@@ -98,6 +104,14 @@ export function specForModel(model) {
   for (const [prefix, spec] of SORTED_SPECS) {
     if (m.startsWith(prefix.toLowerCase())) return spec
   }
+  // Vendor-namespace strip: vendor/model — retry the prefix match on the bare model part.
+  const slash = m.indexOf("/")
+  if (slash > 0) {
+    const bare = m.slice(slash + 1)
+    for (const [prefix, spec] of SORTED_SPECS) {
+      if (bare.startsWith(prefix.toLowerCase())) return spec
+    }
+  }
   // Unknown model: warn ONCE (not per request) so a typo'd ID or a missing alias surfaces
   // instead of silently degrading to the 128K default (IK5VGJ).
   if (m && !warnedModels.has(m)) {

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 重写 */
+  }
+}