thincoder 0.12.59 → 0.12.61

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

package/src/peer-instances.mjs

@@ -0,0 +1,231 @@
+/**
+ * peer-instances.mjs — R10 多实例协作感知面 L1/L2（MULTI-INSTANCE-COLLAB §2a.4）。
+ *
+ * 目标：让同 cwd 的多个 thincoder 副本在 agent 层互相感知。数据源 = 既有 SESSION.md
+ * §10 基建（manifest slotSessions / getSessionId——不新建平行存储，N1），纯只读（N3
+ * ——不认领、不写 manifest——本模块结构化上没有任何 fs 写调用）。
+ *
+ * - peerInstances(cwd)：读 manifest slotSessions → 按 sessionId 去重分组 → slots；
+ *   一次批量判活（batchAlive——修复 isProcessAlive 每 pid 一次 execSync 的成本）；
+ *   端字段（决策③ A：批量 cmdline 探测）区分 Code.exe/扩展宿主（vscode）vs
+ *   node/thincoder（cli）；self = sessionId === getSessionId()。
+ * - 惰性：manifest mtime 缓存（变了才重查——活实例变化必伴随 manifest 写——仿
+ *   agent._slotMtime 先例）。manifest 缺失 → 空清单（不缓存——stat 一次成本）。
+ * - 测试注入缝：_setPeerInstancesTestImpl({ aliveFn, cmdlineFn })——default null
+ *   生产行为不变；测试 restore in finally。
+ * - peerInstancesTool：L2 只读查询工具（schema description 逐字锚——评审修正 #7，
+ *   双端照抄）；无参、去 self、字段白名单 {pid, end, sessionId, slots}（N4）。
+ */
+
+import { execFileSync } from "node:child_process"
+import { statSync } from "node:fs"
+import { manifestPath, loadManifest, getSessionId, END } from "./session-slots.mjs"
+
+const ALIVE_EXEC_TIMEOUT_MS = 10_000
+const CMDLINE_EXEC_TIMEOUT_MS = 15_000
+const CACHE_MAX = 64
+
+/** VS Code 扩展宿主判别标记（决策③ A——cmdline 探测）：扩展宿主进程 argv 必带其一
+ *  （Windows：Code.exe --type=extensionHost / --extensionDevelopmentPath；Unix 同）。 */
+const VSC_END_RE = /--extensionDevelopmentPath|--type=extensionHost|extensionHostProcess/i
+
+// 模块级测试注入缝（default null = 生产实现；测试注入 + finally 恢复——见测试文件）
+let _testImpl = null
+
+/** 注入测试实现。aliveFn(pids) → Set<pid>；cmdlineFn(pids) → Map<pid,cmdline>|null。
+ *  返回前值便于测试保存恢复；传 {} 只清空对应槽。 */
+export function _setPeerInstancesTestImpl({ aliveFn = undefined, cmdlineFn = undefined } = {}) {
+  const prev = _testImpl
+  _testImpl = { aliveFn: aliveFn ?? null, cmdlineFn: cmdlineFn ?? null }
+  peerInstanceCache.clear() // 注入即环境变更——缓存必须失效（测试间不串）
+  return prev
+}
+
+export function _resetPeerInstancesTestImpl() {
+  _testImpl = null
+  peerInstanceCache.clear()
+}
+
+/** manifest mtime 惰性缓存：cwd → { mtimeMs, peers }。缓存有上限（CACHE_MAX——旧条目
+ *  先出）；条目是纯函数结果快照，无锁无句柄——陈旧只影响新鲜度不影响正确性。 */
+const peerInstanceCache = new Map()
+
+function statMtimeMs(p) {
+  try {
+    const st = statSync(p)
+    return st.mtimeMs
+  } catch {
+    return null // 文件缺失/不可读
+  }
+}
+
+function cachePut(cwd, entry) {
+  if (peerInstanceCache.size >= CACHE_MAX) {
+    const oldest = peerInstanceCache.keys().next().value
+    if (oldest !== undefined) peerInstanceCache.delete(oldest)
+  }
+  peerInstanceCache.set(cwd, entry)
+}
+
+/**
+ * 批量判活：单次 tasklist（Windows 全量 CSV）/ ps（Unix）拿全量 PID 集合 → 一次 exec
+ * 比对（修复 isProcessAlive 每 pid 一次 execSync 的成本——每回合 N 次 = 贵，探索 §4）。
+ * 返回存活 pid 的 Set；exec/解析失败 → null（调用方区分"探测失败"与"全死"——只读面按
+ * 无活伴降级；域面（peer-domains 死清理）在 null 时不得执行删除——探测失败 ≠ 死）。
+ */
+export function batchAlive(pids) {
+  const uniq = [...new Set(pids.map(Number).filter((n) => Number.isInteger(n) && n > 0))]
+  if (uniq.length === 0) return new Set()
+  try {
+    if (process.platform === "win32") {
+      const output = execFileSync("tasklist", ["/FO", "CSV", "/NH"], {
+        encoding: "utf8", timeout: ALIVE_EXEC_TIMEOUT_MS, stdio: ["ignore", "pipe", "ignore"],
+      })
+      const alive = new Set()
+      for (const line of output.split(/\r?\n/)) {
+        const m = line.match(/^"([^"]*)","(\d+)"/)
+        if (m) alive.add(Number(m[2]))
+      }
+      return new Set(uniq.filter((pid) => alive.has(pid)))
+    }
+    const output = execFileSync("ps", ["-eo", "pid="], {
+      encoding: "utf8", timeout: ALIVE_EXEC_TIMEOUT_MS, stdio: ["ignore", "pipe", "ignore"],
+    })
+    const alive = new Set(output.split(/\r?\n/).map((l) => Number(l.trim())).filter((n) => Number.isInteger(n)))
+    return new Set(uniq.filter((pid) => alive.has(pid)))
+  } catch {
+    return null // 探测失败（区别于全死）——调用方不得据此执行删除/判死副作用
+  }
+}
+
+/**
+ * 批量 cmdline 探测（决策③ A——一次 exec 拿全部 pid+cmdline）：返回 Map<pid, cmdline>
+ * 或 null（exec 失败/解析失败）。Windows = 一次 Get-CimInstance（PowerShell）；Unix =
+ * 一次 ps。仅在 manifest mtime 变化后跑一次（~百 ms 级——设计已接受）。
+ */
+export function probeCmdlines(pids) {
+  const uniq = [...new Set(pids.map(Number).filter((n) => Number.isInteger(n) && n > 0))]
+  if (uniq.length === 0) return new Map()
+  try {
+    let out
+    if (process.platform === "win32") {
+      // 一次 Get-CimInstance 拿全表 → node 侧过滤目标 pid（避免 shell 引号注入面）
+      out = execFileSync("powershell.exe",
+        ["-NoProfile", "-NonInteractive", "-Command",
+          "Get-CimInstance Win32_Process | Select-Object ProcessId,CommandLine | ConvertTo-Json -Compress"],
+        { encoding: "utf8", timeout: CMDLINE_EXEC_TIMEOUT_MS, stdio: ["ignore", "pipe", "ignore"] })
+      const rows = JSON.parse(out.trim())
+      const map = new Map()
+      for (const r of Array.isArray(rows) ? rows : [rows]) {
+        if (r && Number.isInteger(r.ProcessId) && typeof r.CommandLine === "string") {
+          map.set(Number(r.ProcessId), r.CommandLine)
+        }
+      }
+      return map
+    }
+    out = execFileSync("ps", ["-eo", "pid=,args="], {
+      encoding: "utf8", timeout: CMDLINE_EXEC_TIMEOUT_MS, stdio: ["ignore", "pipe", "ignore"],
+    })
+    const map = new Map()
+    for (const line of out.split(/\r?\n/)) {
+      const m = line.match(/^\s*(\d+)\s+(.*)$/)
+      if (m) map.set(Number(m[1]), m[2])
+    }
+    return map
+  } catch {
+    return null // 探测失败 → 端字段缺省（调用方降级）
+  }
+}
+
+/** cmdline → 端标签：扩展宿主标记 → vscode；其余（node/thincoder CLI）→ cli。 */
+function classifyEnd(cmdline) {
+  if (typeof cmdline !== "string" || cmdline.length === 0) return undefined
+  return VSC_END_RE.test(cmdline) ? "vscode" : "cli"
+}
+
+/** manifest slotSessions → 按 sessionId 去重分组 [{ sessionId, pid, slots }]。
+ *  sessionId 形如 "{pid}-{ts}-{rand}"（进程级——可去重分组，探索 §4）；pid 不可解析
+ *  的条目跳过（存量清理归 saveManifest 的 cleanDeadOwners——本模块纯只读不写）。 */
+function groupSlotSessions(m) {
+  const byId = new Map()
+  for (const [slot, sessionId] of Object.entries(m.slotSessions ?? {})) {
+    if (typeof sessionId !== "string" || sessionId.length === 0) continue
+    let g = byId.get(sessionId)
+    if (!g) {
+      const pid = Number.parseInt(sessionId.split("-")[0], 10)
+      g = { sessionId, pid: Number.isInteger(pid) ? pid : null, slots: [] }
+      byId.set(sessionId, g)
+    }
+    if (/^\d+$/.test(slot)) g.slots.push(Number(slot))
+  }
+  const groups = [...byId.values()]
+  for (const g of groups) g.slots.sort((a, b) => a - b)
+  return groups
+}
+
+/**
+ * 汇总当前 cwd 的活 thincoder 实例（含 self——由调用方过滤；self = 本进程 sessionId）。
+ * 返回 [{ pid, sessionId, slots, self, end? }]——end 仅在批量 cmdline 探测成功时给出
+ * （N4 白名单键之外零附加字段）。纯只读（N3）；manifest 缺失/损坏 → []（按缺失降级）。
+ */
+export function peerInstances(cwd) {
+  // 惰性：manifest mtime 未变 → 直接返回缓存快照（零 exec/零读——T-L1c）
+  const mp = manifestPath(cwd)
+  const mtime = statMtimeMs(mp)
+  if (mtime == null) {
+    peerInstanceCache.delete(cwd) // manifest 尚未诞生/被删——不缓存空结果（stat 一次成本）
+    return []
+  }
+  const hit = peerInstanceCache.get(cwd)
+  if (hit && hit.mtimeMs === mtime) return hit.peers
+
+  const m = loadManifest(cwd) // 损坏 → {slots:{}, sessionId:null}——按缺失降级
+  const groups = groupSlotSessions(m)
+  const myId = getSessionId()
+  const others = groups.filter((g) => g.sessionId !== myId && g.pid != null)
+  // 活判定：其余实例的 pid 去重后一次批量（self 恒活不查；无同伴 → 零 exec）
+  // 探测失败（batchAlive → null）→ 按"无活伴"降级——只读面不显示幽灵同伴
+  const aliveFn = _testImpl?.aliveFn ?? batchAlive
+  const othersAlive = others.length > 0 ? aliveFn([...new Set(others.map((g) => g.pid))]) : new Set()
+  const aliveSet = othersAlive instanceof Set ? othersAlive : new Set()
+  const liveOthers = others.filter((g) => aliveSet.has(g.pid))
+  // 端字段：一次批量 cmdline 探测（仅活同伴——决策③ A；探测失败 → end 缺省）
+  let cmdlines = null
+  if (liveOthers.length > 0) {
+    const probe = _testImpl?.cmdlineFn ?? probeCmdlines
+    cmdlines = probe([...new Set(liveOthers.map((g) => g.pid))])
+  }
+  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 })
+  }
+  for (const g of liveOthers) {
+    const end = cmdlines instanceof Map ? classifyEnd(cmdlines.get(g.pid)) : undefined
+    peers.push({ pid: g.pid, sessionId: g.sessionId, slots: g.slots, self: false, end })
+  }
+  peers.sort((a, b) => a.pid - b.pid || (a.self === b.self ? 0 : a.self ? -1 : 1))
+  cachePut(cwd, { mtimeMs: mtime, peers })
+  return peers
+}
+
+/**
+ * L2 只读查询工具（MULTI-INSTANCE-COLLAB §2a.4 D-L2b）——挂本模块导出。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."
+ */
+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.",
+  parameters: { type: "object", properties: {} },
+  readonly: true,
+  async execute(args, ctx) {
+    const list = peerInstances(ctx.cwd)
+      .filter((p) => !p.self)
+      .map((p) => ({ pid: p.pid, end: p.end, sessionId: p.sessionId, slots: p.slots }))
+    return JSON.stringify(list, null, 2)
+  },
+}

package/src/prompt-overlays.mjs

@@ -0,0 +1,82 @@
+/**
+ * prompt-overlays.mjs — prompt slot constants + the scenario→slot assembly (PROMPT-SYSTEM
+ * 施工② G1+G2, 2026-09-10). Slot constants are loaded ONCE (byte-stable, module scope);
+ * assemblePrompt composes them per PROMPT-SYSTEM.md §3.2 装配矩阵 (D1 内联表——设计锚).
+ *
+ * Slot model (PROMPT-SYSTEM.md §1/§2): persona → common → discipline → [4] other
+ * (AGENTS/skills ride the existing tail logic). explore/coder/plan reuse PERSONA_NORMAL
+ * as their persona slot (蓝图 §3.1 同槽位复用——变体差异归人格层覆写; design D1 G1 note).
+ */
+
+import { readFileSync } from "node:fs"
+import { join, dirname } from "node:path"
+import { fileURLToPath } from "node:url"
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+function loadSlot(name) {
+  try { return readFileSync(join(__dirname, "prompts", name), "utf8") } catch { return "" }
+}
+
+// ── G1 槽位内容表（文件名 → 内容常量）──
+const SLOT_CONTENTS = {
+  "persona-engineering.md": loadSlot("persona-engineering.md"),
+  "persona-normal.md": loadSlot("persona-normal.md"),
+  "persona-eng-coder.md": loadSlot("persona-eng-coder.md"),
+  "persona-eng-designer.md": loadSlot("persona-eng-designer.md"),
+  "persona-explore.md": loadSlot("persona-explore.md"),
+  "persona-coder.md": loadSlot("persona-coder.md"),
+  "persona-plan.md": loadSlot("persona-plan.md"),
+  "common.md": loadSlot("common.md"),
+  "discipline-engineering.md": loadSlot("discipline-engineering.md"),
+  "discipline-normal.md": loadSlot("discipline-normal.md"),
+}
+
+// ── G1 六件导出（评审 #1 计数口径：人格 2 + 公共 1 + 纪律 2 + consult 自含基底；
+//    persona-{role} 三件由 SLOT_CONTENTS 承载、不设独立常量导出——装配表唯一消费面）──
+export const PERSONA_ENGINEERING = SLOT_CONTENTS["persona-engineering.md"]
+export const PERSONA_NORMAL = SLOT_CONTENTS["persona-normal.md"]
+export const COMMON = SLOT_CONTENTS["common.md"]
+export const DISCIPLINE_ENGINEERING = SLOT_CONTENTS["discipline-engineering.md"]
+export const DISCIPLINE_NORMAL = SLOT_CONTENTS["discipline-normal.md"]
+export const CONSULT_BASE = loadSlot("consult-base.md")
+
+// ── D1 场景→槽位文件表（PROMPT-SYSTEM.md §3.2 装配矩阵内联——①②并行契约锚：
+//    槽文件路径字符串以本表为唯一权威——设计 §1.1 红线。explore/coder/plan 行 =
+//    persona-{role}（蓝图 §3.2 1:1——施工①已落地三份角色人格文件；advisor round1
+//    修正：此前误按 G1 括注映射 persona-normal 使三文件永不被消费）。──
+export const SCENARIO_SLOT_FILES = {
+  engineering: ["persona-engineering.md", "common.md", "discipline-engineering.md"],
+  normal: ["persona-normal.md", "common.md", "discipline-normal.md"],
+  "eng-coder": ["persona-eng-coder.md", "common.md", "discipline-engineering.md"],
+  "eng-designer": ["persona-eng-designer.md", "common.md", "discipline-engineering.md"],
+  explore: ["persona-explore.md", "common.md", "discipline-normal.md"],
+  coder: ["persona-coder.md", "common.md", "discipline-normal.md"],
+  plan: ["persona-plan.md", "common.md", "discipline-normal.md"],
+  consult: null, // §3.3 特殊模块——consult-base.md 自含基底，不入主装配链（CONSULT_BASE 直出）
+}
+
+// ── D2 警告文案（走既有 setup 警告通道 = history 注入——不新增机制；common 同款）──
+export function slotWarning(fileName) {
+  return `[System reminder: prompt slot file ${fileName} missing — this slot is SKIPPED, no fallback from another slot (层间隔离). Prompt content may be degraded; check the prompts directory.]`
+}
+
+/**
+ * G2: the single prompt-assembly function — table-driven (D1), fixed order
+ * persona → common → discipline (§3.1 四槽位固定序；[4] AGENTS/skills 由既有尾部
+ * 逻辑承担). A missing slot file is SKIPPED with a prominent warning (蓝图 §3.4 降级链);
+ * AGENTS.md missing = silent skip in the caller's existing tail logic. Byte-stable
+ * per scenario (D3): fixed slot contents + fixed order — no timestamps here.
+ */
+export function assemblePrompt(scenario) {
+  const files = SCENARIO_SLOT_FILES[scenario]
+  if (!files) return { prompt: CONSULT_BASE, warnings: [] }
+  const parts = []
+  const warnings = []
+  for (const file of files) {
+    const content = SLOT_CONTENTS[file]
+    if (content) parts.push(content)
+    else warnings.push(slotWarning(file))
+  }
+  return { prompt: parts.join("\n\n"), warnings }
+}