@thincoder/core 0.9.4 → 0.10.1

package/peer-claims.mjs

@@ -0,0 +1,263 @@
+/**
+ * peer-claims.mjs — R10 多实例协作 L3 **意图认领面**（claims · TTL 租约——MULTI-INSTANCE-COLLAB
+ * §4.4 / D-MI17–D-MI21）。
+ *
+ * 语义（§4.4.1–§4.4.3）：结构化写工具执行成功 ⇒ 本实例登记认领——同 `peers/{sessionId}.json`
+ * 加 `claims` / `claimsUpdatedAt` 两字段，与足迹面 `domains` / `updatedAt` **分字段分存**
+ * （落盘 = 字段级合并写，互不改写，未知字段逐字保留）；租约 `CLAIM_TTL_MS`，同域再写续约
+ * （`claimedAt` 保持首次；覆盖去冗 = 方向性 `covers` 三分支，集内无被覆盖项）；落盘 = 新目标
+ * 即刻 + 续约节流 `CLAIM_RENEW_FLUSH_MS`（届内零 IO）；原子写经 `writeSessionFile`
+ * （.tmp + rename——rename 翻 peers 目录 mtime ⇒ 对端聚合缓存失效，认领回合内可见）。
+ * 释放 = 租约到期 / 属主进程死亡 / 记录被死清理——**无显式释放面**（D-MI19）。
+ *
+ * 读面（§4.4.4）：按 `expiresAt > now` 过滤 + 本实例落盘时剪除（不 unlink——过期不是崩溃
+ * 残留）；属主死亡 ⇒ 整条记录不可见并随既有死清理删除。命中 = 目标 ∩ 他实例未过期认领
+ * （`claimHits`——调用面 = 既有写前预检同点、同一聚合扫描）；软提示文案 `claimNoteText`
+ * （双端逐字一致；`age` / `left` / `who` 规则同 §4.4.4）；去重集 `agent._peerNoted`
+ * （每（目标 × 认领属主）每 run 至多一行——`markClaimNoted` 在提示真正附加时落标记）。
+ *
+ * 本档另归口 peers 目录路径与路径谓词（`pathsOverlap` / `covers`——`peer-domains.mjs`
+ * re-export 保既有 import 面）。测试缝：`_setPeersDirForTest` / `_resetPeersDirForTest`
+ * （沙箱）+ `_setPeerClaimsTestImpl({ nowFn })`（时钟——续约 / 过期两侧零真实等待）。
+ */
+import { existsSync, readFileSync } from "node:fs"
+import { join } from "node:path"
+import { configDir } from "./config.mjs"
+import { normalizeCwd, getSessionId, sessionEnd, manifestPath, writeSessionFile } from "./session-slots.mjs"
+
+/** 认领租约（§4.4.2）：30 min——同目标再写 / 目标被已有认领覆盖 ⇒ `expiresAt = now + 本值`。 */
+export const CLAIM_TTL_MS = 30 * 60 * 1000
+
+/** 续约落盘节流（§4.4.3）：新目标即刻落盘；纯续约距上次落盘 ≥ 本窗才落盘，其余零 IO。 */
+export const CLAIM_RENEW_FLUSH_MS = 60 * 1000
+
+// ─── peers 目录（测试注入缝——形态先例 = 端侧同名缝）────────────────────────
+let peersDirOverride = null
+export function _setPeersDirForTest(dir) { peersDirOverride = dir }
+export function _resetPeersDirForTest() { peersDirOverride = null }
+
+export function peersDir() {
+  return peersDirOverride ?? join(configDir, "peers")
+}
+
+export function peerFilePath(sessionId) {
+  return join(peersDir(), `${sessionId}.json`)
+}
+
+// ─── 时钟缝（续约 / 过期两侧确定性断言——零真实等待）──────────────────────
+let _testNowFn = null
+
+export function _setPeerClaimsTestImpl({ nowFn = undefined } = {}) {
+  const prev = _testNowFn
+  _testNowFn = nowFn ?? null
+  return prev
+}
+
+export function _resetPeerClaimsTestImpl() {
+  _testNowFn = null
+}
+
+/** 认领面时钟（读面命中判据与落盘同一时钟——时钟缝注入时两侧确定一致；缺省 `Date.now`）。 */
+export function claimsNow() {
+  return _testNowFn ? _testNowFn() : Date.now()
+}
+
+// ─── 路径谓词（自 peer-domains.mjs 归口——单源）────────────────────────────
+
+function normPath(p) {
+  const n = process.platform === "win32" ? String(p).toLowerCase() : String(p)
+  return (process.platform === "win32" ? n.replace(/\//g, "\\") : n.replace(/\\/g, "/")).replace(/[\\/]+$/, "")
+}
+
+/** 路径重叠：a 与 b 相等或互为目录包含（file_ops 目录级操作 / delete 整目录语义——既有
+ *  语义原样：区分大小写按平台；分隔符归一）。本地规范式 = `normPath` 单源。 */
+export function pathsOverlap(a, b) {
+  const pa = normPath(a)
+  const pb = normPath(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)
+}
+
+/** 方向性包含（覆盖去冗判据 §4.4.1）：`coarse` 覆盖 `fine` = 相等或 coarse 为 fine 的目录
+ *  **前缀**（单方向——对称谓词 `pathsOverlap` 不作包含判据）。归一 / 大小写同款。 */
+export function covers(coarse, fine) {
+  const pc = normPath(coarse)
+  const pf = normPath(fine)
+  if (pc === pf) return true
+  return pf.startsWith(pc + (process.platform === "win32" ? "\\" : "/"))
+}
+
+// ─── 认领登记 / 落盘（写成功钩子——§4.4.3）────────────────────────────────
+
+/** 认领状态载体 = `agent._peerClaims`（Map<target, {target, claimedAt, expiresAt}>，与足迹面
+ *  `agent._peerWritten` 同型）；落盘账 = `agent._peerClaimsFlushed`（Set<target>）+
+ *  `agent._peerClaimsFlushedAt`（上次落盘时刻——续约节流锚）。 */
+
+function pendingClaims(agent) {
+  return agent._peerClaims ?? (agent._peerClaims = new Map())
+}
+
+/** 过期剪除（§4.4.2——读面过滤之外的落盘面剪除）：租约已结束的认领不参与覆盖判定，
+ *  也不占据续约对象；剪除同时清落盘账（该目标在盘上已失效 ⇒ 再认领视同新目标）。 */
+function pruneClaims(agent, now) {
+  const set = pendingClaims(agent)
+  const flushed = agent._peerClaimsFlushed
+  for (const [target, claim] of [...set]) {
+    if (claim.expiresAt > now) continue
+    set.delete(target)
+    flushed?.delete(target)
+  }
+}
+
+/**
+ * 认领登记 + 落盘决策（§4.4.3——写工具成功钩子调用；零新手工动作）。三分支（§4.4.1）：
+ * 已有认领 `covers` 新目标 ⇒ 只续约；新目标 `covers` 已有认领项 ⇒ 替换（被覆盖项出集）；
+ * 无包含关系 ⇒ 新目标入集。落盘：含未落盘目标 ⇒ 即刻整写；否则距上次落盘 ≥
+ * `CLAIM_RENEW_FLUSH_MS` ⇒ 续约落盘；其余零 IO。失败容忍（NF2——下次写重试）。
+ */
+export function recordPeerClaims(agent, targets) {
+  try {
+    const now = claimsNow()
+    pruneClaims(agent, now)
+    const set = pendingClaims(agent)
+    for (const target of targets) {
+      const covering = [...set.values()].find((c) => covers(c.target, target))
+      if (covering) {
+        covering.expiresAt = now + CLAIM_TTL_MS // 续约（claimedAt 保持首次）
+        continue
+      }
+      for (const [t, c] of [...set]) {
+        if (covers(target, c.target)) {
+          set.delete(t)
+          agent._peerClaimsFlushed?.delete(t)
+        }
+      }
+      set.set(target, { target, claimedAt: now, expiresAt: now + CLAIM_TTL_MS })
+    }
+    if (set.size === 0) return
+    const flushed = agent._peerClaimsFlushed ?? (agent._peerClaimsFlushed = new Set())
+    const hasUnflushed = [...set.keys()].some((t) => !flushed.has(t))
+    const due = now - (agent._peerClaimsFlushedAt ?? 0) >= CLAIM_RENEW_FLUSH_MS
+    if (hasUnflushed || due) flushPeerClaims(agent, now)
+  } catch {
+    /* 登记失败不影响工具结果（工具主流程永不受认领面影响） */
+  }
+}
+
+/** 读既有实例文件（字段级合并写基线）：缺失 / 损坏 / 结构非法 ⇒ `{}`（按缺失降级——
+ *  损坏件不删，本次落盘覆盖）。 */
+export function readPeerRecord(file) {
+  try {
+    const rec = JSON.parse(readFileSync(file, "utf8"))
+    return rec && typeof rec === "object" && !Array.isArray(rec) ? rec : {}
+  } catch {
+    return {}
+  }
+}
+
+/** 认领落盘（§4.4.1 字段级合并写）：只改 `claims` / `claimsUpdatedAt`——其余字段（含足迹面
+ *  `domains` / `updatedAt`、身份字段、未知字段）逐字保留；身份字段仅在缺失时补齐（本面
+ *  不写他面字段）。原子写 = `writeSessionFile`（.tmp + rename）。落盘门控 = 本 cwd 会话
+ *  manifest 在场（测试卫生——无头 / 未绑定会话不向真实 peers 目录写任何东西；端侧既有
+ *  L3 门同法）。过期条目在落盘时剪除。 */
+export function flushPeerClaims(agent, now = claimsNow()) {
+  try {
+    const cwd = agent?.cwd
+    if (!cwd || !existsSync(manifestPath(cwd))) return
+    const sessionId = getSessionId()
+    const base = readPeerRecord(peerFilePath(sessionId))
+    const claims = [...pendingClaims(agent).values()]
+      .filter((c) => c.expiresAt > now)
+      .map((c) => ({ target: c.target, claimedAt: c.claimedAt, expiresAt: c.expiresAt }))
+      .sort((a, b) => (a.target < b.target ? -1 : a.target > b.target ? 1 : 0))
+    const payload = { ...base }
+    if (payload.sessionId === undefined) payload.sessionId = sessionId
+    if (payload.pid === undefined) payload.pid = process.pid
+    if (payload.end === undefined) payload.end = sessionEnd()
+    if (payload.cwd === undefined) payload.cwd = normalizeCwd(cwd)
+    payload.claims = claims
+    payload.claimsUpdatedAt = now
+    writeSessionFile(peerFilePath(sessionId), payload)
+    agent._peerClaimsFlushed = new Set(claims.map((c) => c.target))
+    agent._peerClaimsFlushedAt = now
+  } catch {
+    /* NF2：失败容忍——下次写重试（落盘账不推进） */
+  }
+}
+
+// ─── 命中判据 / 文案 / 去重（§4.4.4）──────────────────────────────────────
+
+/** 聚合载荷中解析出的认领项形态（`scanPeersDir` 消费——结构非法按缺失）。 */
+export function parseClaims(raw) {
+  if (!Array.isArray(raw)) return []
+  const out = []
+  for (const c of raw) {
+    if (!c || typeof c !== "object") continue
+    if (typeof c.target !== "string" || c.target.length === 0) continue
+    const claimedAt = Number(c.claimedAt) || 0
+    const expiresAt = Number(c.expiresAt) || 0
+    if (expiresAt <= 0) continue
+    out.push({ target: c.target, claimedAt, expiresAt })
+  }
+  return out
+}
+
+/** 命中判据（§4.4.4）：`peers`（聚合载荷——同 cwd / self 已排除 / 属主已判活）中各实例的
+ *  **未过期**认领 ∩ `target` ⇒ `[{end, pid, sessionId, claimedAt, expiresAt}]`（同属主同
+ *  目标至多一条）。纯只读、不抛。 */
+export function claimHits(peers, target, now) {
+  const out = []
+  for (const p of peers ?? []) {
+    const hit = (p.claims ?? []).find((c) => c.expiresAt > now && pathsOverlap(target, c.target))
+    if (hit) out.push({ end: p.end, pid: p.pid, sessionId: p.sessionId, claimedAt: hit.claimedAt, expiresAt: hit.expiresAt })
+  }
+  return out
+}
+
+/** 认领时长（§4.4.4）：`just now`（< 1 min）/ `${n} min ago`。 */
+export function claimAge(claimedAt, now) {
+  const min = Math.floor((now - claimedAt) / 60000)
+  return min < 1 ? "just now" : `${min} min ago`
+}
+
+/** 剩余租约（§4.4.4）：`max(1, ceil((expiresAt − now) / 60000))`（分钟）。 */
+export function claimLeft(expiresAt, now) {
+  return Math.max(1, Math.ceil((expiresAt - now) / 60000))
+}
+
+/** `who` 串（§4.4.4 逐字规则）：认领属主 `${end} pid=${pid}`（无 end 则 `pid=${pid}`）；
+ *  仅足迹命中的属主追加 ` (recent write)`；以 ", " 连接。 */
+export function claimWho(owners) {
+  return owners
+    .map((o) => `${o.end ? `${o.end} ` : ""}pid=${o.pid}${o.recentWrite ? " (recent write)" : ""}`)
+    .join(", ")
+}
+
+/** 认领软提示文案（逐字契约 §4.4.4——双端一致；禁自行解释）。 */
+export function claimNoteText(target, who, age, left) {
+  return `[peer-collab] ${target} — another live instance (${who}) holds a live intent claim on it (claimed ${age}, lease ${left} min left); concurrent edits may overwrite each other. Write not blocked — coordinate before proceeding.`
+}
+
+/** 去重键（§4.4.4）：同一（目标 × 认领属主）每 run 至多一行——键 = `${target}\\u0000${sessionId}`。
+ *  `||`（非 `??`）兜底：缺 `sessionId` 的载荷不得与空串共键（端侧聚合允许空串）。 */
+export function claimNoteKey(target, owner) {
+  return `${target}\u0000${owner.sessionId || owner.pid}`
+}
+
+export function claimNoted(agent, key) {
+  return agent?._peerNoted instanceof Set && agent._peerNoted.has(key)
+}
+
+/** 落去重标记（调用方**在提示真正附加时**调用——写失败路径不消耗额度）。 */
+export function markClaimNoted(agent, keys) {
+  if (!agent || !Array.isArray(keys) || keys.length === 0) return
+  const set = agent._peerNoted instanceof Set ? agent._peerNoted : (agent._peerNoted = new Set())
+  for (const k of keys) set.add(k)
+}
+
+/** 去重集清空（§4.4.4——落点 = `flushPeerDomains` 首步：先于「无写入即返回」早退）。 */
+export function clearClaimNoted(agent) {
+  if (agent?._peerNoted instanceof Set) agent._peerNoted.clear()
+}

package/peer-domains.mjs

@@ -4,9 +4,13 @@
  *
  * 登记存储（D-L3a）：~/.thincoder/peers/{sessionId}.json——每实例单文件、单写者（本
  * 进程——end marker 同型模式）；内容 {sessionId, pid, end, cwd, domains[绝对路径],
- * updatedAt}。写点 = 回合级：写工具钩子累积"本回合实际写过的文件"（D-L3b 同一钩子——
- * 检测+记录一次完成）→ 回合结束 flush 整写一次（finalizeAgentTurn）；本回合无写入则
- * 不写（文件按自身 updatedAt 自然过期——hot 5 分钟窗口语义不被空回合提前清掉）。
+ * updatedAt} + 意图认领面 claims / claimsUpdatedAt（§4.4.1——两字段属 `peer-claims.mjs`，
+ * 本档只做字段级合并写）。写点 = 回合级：写工具钩子累积"本回合实际写过的文件"（D-L3b
+ * 同一钩子——检测+记录一次完成）→ 回合结束 flush 整写一次（finalizeAgentTurn）；本回合
+ * 无写入则不写（文件按自身 updatedAt 自然过期——hot 5 分钟窗口语义不被空回合提前清掉）。
+ *
+ * 意图认领面接线（§4.4 / D-MI17–D-MI21）：认领登记 / 落盘 / 命中判据 / 文案住 `peer-claims.mjs`
+ * ——本档接线 = `recordPeerWrites` 调认领登记 · `peerCollabNote` 组合认领行 · `flushPeerDomains` 首步清空去重集 + 字段级合并写 · 聚合载荷增 `claims`。
  *
  * 冲突检测（D-L3b）：结构化写工具（PEER_WRITE_TOOLS）执行前查 conflicts——命中他实例
  * hot 域 → 工具结果附软提示（决策⑥ A：不阻止）。缓存（评审修正 #2）：聚合结果按 peers
@@ -16,11 +20,18 @@
  */
 
 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 { join, resolve } from "node:path"
+import { normalizeCwd, getSessionId, sessionEnd, writeSessionFile } from "./session-slots.mjs"
 import { batchAlive } from "./peer-instances.mjs"
-import { FILE_MUTATORS } from "./agent/helpers.mjs"
+import { FILE_MUTATORS, toolTouchPaths } from "./agent/helpers.mjs"
+// 认领面（§4.4）归口 `peer-claims.mjs`；re-export 路径与谓词保既有 import 面（单源不复制）。
+import {
+  peersDir, peerFilePath, pathsOverlap, claimHits, claimNoteText, claimAge, claimLeft,
+  claimWho, claimNoteKey, claimNoted, markClaimNoted, clearClaimNoted, claimsNow,
+  recordPeerClaims, readPeerRecord, parseClaims,
+} from "./peer-claims.mjs"
+
+export { peersDir, peerFilePath, pathsOverlap, markClaimNoted }
 
 /** hot 窗口：登记（回合足迹 flush）后 5 分钟内视为 hot（决策⑤ A——"刚写过"语义） */
 export const HOT_WINDOW_MS = 5 * 60 * 1000
@@ -30,50 +41,43 @@ export const HOT_WINDOW_MS = 5 * 60 * 1000
  *  写工具（同一文件写入面），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
+let _testStatFn = null
 
-/** 注入聚合判活实现（批量判活计数/去真实 exec——T-L3b 死清理用例可用真死 pid 亦可注入）。 */
-export function _setPeerDomainsTestImpl({ aliveFn = undefined } = {}) {
+/** 注入聚合判活实现（批量判活计数/去真实 exec——T-L3b 死清理用例可用真死 pid 亦可注入）+
+ *  目录 stat 实现（N-MI7 成本断言——「目录 stat ≤ 1 / 缓存命中零扫描」，AC-IC10 计数面）。 */
+export function _setPeerDomainsTestImpl({ aliveFn = undefined, statFn = undefined } = {}) {
   const prev = _testAliveFn
   _testAliveFn = aliveFn ?? null
+  _testStatFn = statFn ?? null
   peersDirCache = null // 注入即环境变更——目录缓存失效（测试间不串）
   return prev
 }
 
 export function _resetPeerDomainsTestImpl() {
   _testAliveFn = null
+  _testStatFn = null
   peersDirCache = null
 }
 
-// peers 目录 mtime 惰性缓存（评审修正 #2）——单全局项（peers 目录全局唯一）
-let peersDirCache = null // { mtimeMs, peers: [...] }
+// peers 目录 mtime 惰性缓存（评审修正 #2）——单全局项（缓存键含目录路径：沙箱换目录即
+// 自然失效，`_setPeersDirForTest` 自足）
+let peersDirCache = null // { dir, mtimeMs, peers: [...] }
 
 function statDirMtimeMs(dir) {
   try {
-    return statSync(dir).mtimeMs
+    return (_testStatFn ?? statSync)(dir).mtimeMs
   } catch {
     return null // 目录缺失
   }
 }
 
-/** 目标路径解析（工具 touchedPaths 优先——apply_patch/edit-batch 多文件；file_ops 无
- *  touchedPaths——source/dest 双算；其余 path 单参兜底）。相对路径按 cwd 解析为绝对
- *  路径（resolve：绝对入参原样保留）。解析失败/畸形入参跳过（零目标 = 无检测无登记）。 */
+/** 目标路径解析（#327 单源谓词 `toolTouchPaths`——`docs/core/design/TOOLS.md` §6.17：钩子裁决 /
+ *  `file_ops` 无钩子 ⇒ 动作感知（`copy` ⇒ 只 `dest`；`move` / `rename` / 缺 `action` ⇒ source+dest）；
+ *  其余单参兜底）。相对路径按 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 raw = toolTouchPaths(tool, args) // 单源谓词（恒数组 · 恒零抛——原裸抛面收口）
   const out = []
   for (const p of raw) {
     if (typeof p !== "string" || p.length === 0) continue
@@ -86,25 +90,9 @@ export function peerWriteTargets(tool, args, cwd) {
   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 }]。目录缺失/不可读 → []。 */
+/** 扫描 peers 目录：解析每文件 + 一次批量判活全部 pid + 死登记惰性清理（unlink——崩溃残留）；
+ *  损坏文件按缺失降级（不删——属主下次 flush 覆盖）。返回活登记
+ *  [{ sessionId, pid, end, cwd, domains, updatedAt, claims, claimsUpdatedAt }]（认领面同载荷）。 */
 function scanPeersDir() {
   let files = []
   try {
@@ -120,7 +108,8 @@ function scanPeersDir() {
       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)) {
+        && typeof rec.cwd === "string"
+        && (Array.isArray(rec.domains) || Array.isArray(rec.claims))) { // 认领面先落盘的记录（尚无 domains）同样可解析
         parsed.push({ file, rec })
       }
       // 结构非法 = 损坏 → 按缺失降级（不删——NF2 同型）
@@ -148,8 +137,11 @@ function scanPeersDir() {
       pid: Number(rec.pid),
       end: typeof rec.end === "string" ? rec.end : undefined,
       cwd: rec.cwd,
-      domains: rec.domains.filter((d) => typeof d === "string"),
+      domains: (rec.domains ?? []).filter((d) => typeof d === "string"),
       updatedAt: Number(rec.updatedAt) || 0,
+      // 认领面（§4.4.4——同一聚合扫描供两面；旧记录无 claims ⇒ 按缺失降级）
+      claims: parseClaims(rec.claims),
+      claimsUpdatedAt: Number(rec.claimsUpdatedAt) || 0,
     })
   }
   return live
@@ -164,14 +156,14 @@ function cachedScan() {
     peersDirCache = null
     return []
   }
-  if (peersDirCache && peersDirCache.mtimeMs === mtime) return peersDirCache.peers
+  if (peersDirCache && peersDirCache.dir === dir && peersDirCache.mtimeMs === mtime) return peersDirCache.peers
   const peers = scanPeersDir()
   if (peers === null) {
     peersDirCache = null // 探测失败——不缓存空聚合（下轮调用重试探测——失败 ≠ 无登记）
     return []
   }
   // 死清理删文件会改目录 mtime——以清理后的 mtime 缓存（下次 stat 命中即不重扫）
-  peersDirCache = { mtimeMs: statDirMtimeMs(dir) ?? mtime, peers }
+  peersDirCache = { dir, mtimeMs: statDirMtimeMs(dir) ?? mtime, peers }
   return peers
 }
 
@@ -199,41 +191,73 @@ export function conflicts(cwd, targets, { now = Date.now() } = {}) {
   } 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)))
+    const by = footHitsFor(peers, target, now)
     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) {
+/** 足迹命中（D-L3b 判据单源——`conflicts` 与认领面同源同载荷，零二次扫描）。 */
+function footHitsFor(peers, target, now) {
+  return peers.filter((p) => p.domains.length > 0 && now - p.updatedAt <= HOT_WINDOW_MS
+    && p.domains.some((d) => pathsOverlap(target, d)))
+}
+
+/**
+ * dispatch 写工具钩子预检（§4.4.4——一次聚合扫描供两面）：认领命中（未过期）⇒ 出认领行并
+ * **抑制该目标足迹行**；仅足迹命中 ⇒ 既有足迹文案逐字零变；去重 = 同一（目标 × 认领属主）
+ * 每 run 至多一行。返回 `{ text, keys }`（`keys` = 本次新提示的去重键——调用方在**提示真正
+ * 附加**时落标记，写失败路径不消耗额度；无提示 / 降级 ⇒ null）。一次目录 stat。
+ */
+export function peerCollabNote(agent, tool, args) {
   try {
-    const targets = peerWriteTargets(tool, args, cwd)
+    const targets = peerWriteTargets(tool, args, agent.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")
+    const peers = peerDomains(agent.cwd)
+    if (peers.length === 0) return null
+    const now = Date.now() // 足迹面时钟（hot 窗口——D-MI5 语义零变）
+    const cnow = claimsNow() // 认领面时钟（与落盘同源——时钟缝注入侧确定一致）
+    const lines = []
+    const keys = []
+    for (const target of targets) {
+      const claims = claimHits(peers, target, cnow)
+      const foot = footHitsFor(peers, target, now)
+      const fresh = claims.filter((o) => !claimNoted(agent, claimNoteKey(target, o)))
+      if (fresh.length > 0) {
+        // 认领行：`who` = 新提示的认领属主 + 仅足迹命中的属主（` (recent write)` 后缀）
+        const footOnly = foot.filter((p) => !claims.some((c) => c.sessionId === p.sessionId))
+        const who = claimWho([
+          ...fresh.map((o) => ({ end: o.end, pid: o.pid })),
+          ...footOnly.map((p) => ({ end: p.end, pid: p.pid, recentWrite: true })),
+        ])
+        // 代表 = 集内最早认领（multi-owner 时 `age` / `left` 的确定性取样）
+        const rep = fresh.reduce((a, b) => (a.claimedAt <= b.claimedAt ? a : b))
+        lines.push(claimNoteText(target, who, claimAge(rep.claimedAt, cnow), claimLeft(rep.expiresAt, cnow)))
+        for (const o of fresh) keys.push(claimNoteKey(target, o))
+      } else if (claims.length === 0 && foot.length > 0) {
+        const who = foot.map((p) => (p.end ? `${p.end} pid=${p.pid}` : `pid=${p.pid}`)).join(", ")
+        lines.push(`[peer-collab] ${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.`)
+      }
+      // claims.length > 0 && fresh.length === 0 ⇒ 该目标本轮已提示：抑制足迹行、不出行
+    }
+    if (lines.length === 0) return null
+    return { text: lines.join("\n"), keys }
   } catch {
     return null // 感知失败绝不打扰工具执行
   }
 }
 
-/** 记录本回合写足迹（D-L3a 累积——D-L3b 同一钩子执行后调用；仅成功写计入"实际写过"）。
- *  agent._peerWritten: Set<绝对路径>（回合级——finalizeAgentTurn flush 时整写并清空）。 */
+/** 记录本回合写足迹（D-L3a 累积——D-L3b 同一钩子执行后调用；仅成功写计入"实际写过"）+
+ *  意图认领登记（§4.4.3——写成功即登记：新目标即刻落盘 / 续约节流；载体 agent._peerWritten）。 */
 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)
+    recordPeerClaims(agent, targets) // 认领面：登记 + 落盘决策（§4.4.3——零新手工动作）
   } catch {
     /* 记录失败不影响工具结果 */
   }
@@ -241,19 +265,24 @@ export function recordPeerWrites(agent, tool, args) {
 
 /**
  * 回合末登记 flush（D-L3a——finalizeAgentTurn 调用）：本回合足迹整写一次本实例文件
- * （单写者；.tmp+rename 原子——writeSessionFile）。本回合无写入 → 不写（文件按自身
- * updatedAt 自然过期——hot 窗口不被空回合提前清掉；低频 N3）。写失败容忍（NF2——end
- * marker 同型）；成功 flush 后清空回合集合。不抛（调用方回合收尾零风险）。
+ * （单写者；.tmp+rename 原子——writeSessionFile）。**字段级合并写**（§4.4.1）：只改足迹面
+ * `domains` / `updatedAt`——认领字段与未知字段逐字保留。首步清空认领去重集（§4.4.4——先于
+ * 「无写入即返回」早退：去重集不随无写回合泄漏）。本回合无写入 → 不写（hot 窗口不被空回合
+ * 提前清掉）；写失败容忍（NF2）；成功 flush 后清空回合集合。不抛（回合收尾零风险）。
  */
 export function flushPeerDomains(agent) {
+  clearClaimNoted(agent) // §4.4.4 去重集清空（不抛——纯内存操作）
   try {
     const set = agent._peerWritten
     if (!set || set.size === 0) return
     const sessionId = getSessionId()
-    writeSessionFile(peerFilePath(sessionId), {
+    const file = peerFilePath(sessionId)
+    const base = readPeerRecord(file) // 认领字段 / 未知字段逐字保留（字段级合并写）
+    writeSessionFile(file, {
+      ...base,
       sessionId,
       pid: process.pid,
-      end: END,
+      end: sessionEnd(),
       cwd: normalizeCwd(agent.cwd),
       domains: [...set],
       updatedAt: Date.now(),

package/peer-instances.mjs

@@ -26,8 +26,9 @@
  */
 
 import { statSync } from "node:fs"
-import { manifestPath, loadManifest, getSessionId, END } from "./session-slots.mjs"
+import { manifestPath, loadManifest, getSessionId, sessionEnd } from "./session-slots.mjs"
 import { batchAlive, batchAliveAsync, probeCmdlinesAsync, classifyEnd, isProductProc } from "./process-probe.mjs"
+import { DESC } from "./tools/shared.mjs" // #15 描述外置：文本单点 = tool-docs/peer_instances.md
 
 export { batchAlive } // 既有 import 面（peer-domains.mjs）零破——实现已外提 process-probe.mjs
 
@@ -78,10 +79,11 @@ function cachePut(cwd, entry) {
   peerInstanceCache.set(cwd, entry)
 }
 
-/** manifest slotSessions → 按 sessionId 去重分组 [{ sessionId, pid, slots }]。
+/** manifest slotSessions → 按 sessionId 去重分组 [{ sessionId, pid, slots }]（纯函数·零 IO）。
  *  sessionId 形如 "{pid}-{ts}-{rand}"（进程级——可去重分组，MULTI-INSTANCE-COLLAB §3.1）；pid 不可解析
- *  的条目跳过（存量清理归 saveManifest 的 cleanDeadOwners——本模块纯只读不写）。 */
-function groupSlotSessions(m) {
+ *  的条目跳过（存量清理归 saveManifest 的 cleanDeadOwners——本模块纯只读不写）。
+ *  **具名导出**（§3.1「聚合半段单源」）：VSC 端引本件分组半段（端侧零本地副本）。 */
+export function groupSlotSessions(m) {
   const byId = new Map()
   for (const [slot, sessionId] of Object.entries(m.slotSessions ?? {})) {
     if (typeof sessionId !== "string" || sessionId.length === 0) continue
@@ -145,7 +147,7 @@ export async function peerInstances(cwd) {
   const peers = []
   const selfGroup = groups.find((g) => g.sessionId === myId)
   if (selfGroup) {
-    peers.push({ pid: selfGroup.pid ?? process.pid, sessionId: myId, slots: selfGroup.slots, end: END, self: true })
+    peers.push({ pid: selfGroup.pid ?? process.pid, sessionId: myId, slots: selfGroup.slots, end: sessionEnd(), self: true })
   }
   for (const g of peerGroups) {
     const end = known ? classifyEnd(cmdlines.get(g.pid)) : undefined
@@ -159,14 +161,11 @@ export async function peerInstances(cwd) {
 /**
  * L2 只读查询工具（MULTI-INSTANCE-COLLAB §3.3）——挂本模块导出。schema
  * description 逐字锚（评审修正 #7——2026-09-06 定稿，双端照抄——禁止自行解释）：
- * "peer_instances — read-only: list other live ThinCoder instances sharing this
- * workspace cwd. Returns [{ pid, end, sessionId, slots }]; never includes self;
- * pure read — writes nothing."
+ * 文本本体 = `tool-docs/peer_instances.md`（DESC() 加载；#15 外置——文本逐字零改）。
  */
 export const peerInstancesTool = {
   name: "peer_instances",
-  description:
-    "peer_instances — read-only: list other live ThinCoder instances sharing this workspace cwd. Returns [{ pid, end, sessionId, slots }]; never includes self; pure read — writes nothing.",
+  description: DESC("peer_instances"), // #15 外置：文本单点 = tool-docs/peer_instances.md（逐字锚）
   parameters: { type: "object", properties: {} },
   readonly: true,
   async execute(args, ctx) {