@thincoder/core 0.9.1

package/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/peer-instances.mjs

@@ -0,0 +1,178 @@
+/**
+ * peer-instances.mjs — R10 多实例协作感知面 L1/L2（MULTI-INSTANCE-COLLAB §3）。
+ *
+ * 目标：让同 cwd 的多个 thincoder 副本在 agent 层互相感知。数据源 = 既有 SESSION.md
+ * §6.10 基建（manifest slotSessions / getSessionId——不新建平行存储，N1），纯只读（N3
+ * ——不认领、不写 manifest——本模块结构化上没有任何 fs 写调用）。
+ *
+ * - 探测族（`batchAlive` / `probeCmdlines` / `classifyEnd`）住 `process-probe.mjs`
+ *   （批 1 CORE-DEFECT-FIXES 外提——探测与身份判据单源，判据面 = §3.1 F-MI6 / V3）；
+ *   `batchAlive` 本档 **re-export**（既有 import 面零破——`peer-domains.mjs` 零改，
+ *   其域残留清理保持**纯存在性**语义）。
+ * - peerInstances(cwd)：读 manifest slotSessions → 按 sessionId 去重分组 → 一次批量判活
+ *   （batchAlive）→ **命令行身份复核**（`isProductProc`——pid 复用不再误报「另有活动实例」；
+ *   命令探测失败 / 该 pid 缺行 ⇒ **保守保留**，D-MI10）→ 端字段（决策③ A）；
+ *   self = sessionId === getSessionId()。
+ * - 惰性：manifest mtime **∨ 快照 TTL**缓存（命中即返——零 exec 零读；TUI 假死批 2026-09-18 收正：
+ *   `saveSession` 每回合重写 manifest ⇒ 纯 mtime 判据**每回合自击穿**，探测面改 TTL 下限）。
+ *   manifest 缺失 → 空清单（不缓存——stat 一次成本）。
+ * - 探测**异步化**（同批）：读面用 `batchAliveAsync` / `probeCmdlinesAsync`（`execFile` promise——
+ *   不得用同步 exec 占住事件循环）；清理面（`cleanDeadOwners`）继续同步版（非每回合面，D-MI14）。
+ * - 测试注入缝：_setPeerInstancesTestImpl({ aliveFn, cmdlineFn, nowFn })（前两缝均**批量**语义；
+ *   `nowFn` = 时钟缝——TTL 两侧可**确定性**断言，免真实 ≥ 5 s 等待）。
+ *   default null 生产行为不变；测试 restore in finally。
+ * - peerInstancesTool：L2 只读查询工具（schema description 逐字锚——评审修正 #7，
+ *   双端照抄）；无参、去 self、字段白名单 {pid, end, sessionId, slots}（N4）。
+ */
+
+import { statSync } from "node:fs"
+import { manifestPath, loadManifest, getSessionId, END } from "./session-slots.mjs"
+import { batchAlive, batchAliveAsync, probeCmdlinesAsync, classifyEnd, isProductProc } from "./process-probe.mjs"
+
+export { batchAlive } // 既有 import 面（peer-domains.mjs）零破——实现已外提 process-probe.mjs
+
+const CACHE_MAX = 64
+
+/** 快照最大存活（毫秒）——mtime 变了但距上次实探不足此值 ⇒ 仍命中缓存（§3.1）。
+ *  修因 = `saveSession` 每回合重写 manifest（`session.mjs`）⇒ 纯 mtime 判据每回合自击穿，
+ *  每回合重跑 `tasklist` + `Get-CimInstance`（1–3 s **同步 exec**）。TTL 只影响新鲜度
+ *  （同伴来去在人类时标），不影响正确性。 */
+export const PEER_PROBE_TTL_MS = 5000
+
+// 模块级测试注入缝（default null = 生产实现；测试注入 + finally 恢复——见测试文件）
+let _testImpl = null
+
+/** 注入测试实现。aliveFn(pids) → Set<pid>；cmdlineFn(pids) → Map<pid,cmdline>|null；
+ *  nowFn() → 毫秒时钟（缺省 `Date.now`——TTL 两侧可确定性断言）。三缝均**批量**语义。
+ *  返回前值便于测试保存恢复；**未传的槽置 null**（传 `{}` = 全槽同清，等价 reset）。 */
+export function _setPeerInstancesTestImpl({ aliveFn = undefined, cmdlineFn = undefined, nowFn = undefined } = {}) {
+  const prev = _testImpl
+  _testImpl = { aliveFn: aliveFn ?? null, cmdlineFn: cmdlineFn ?? null, nowFn: nowFn ?? null }
+  peerInstanceCache.clear() // 注入即环境变更——缓存必须失效（测试间不串）
+  return prev
+}
+
+export function _resetPeerInstancesTestImpl() {
+  _testImpl = null
+  peerInstanceCache.clear()
+}
+
+/** manifest mtime ∨ 快照 TTL 惰性缓存：cwd → { mtimeMs, probedAt, 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)
+}
+
+/** manifest slotSessions → 按 sessionId 去重分组 [{ sessionId, pid, slots }]。
+ *  sessionId 形如 "{pid}-{ts}-{rand}"（进程级——可去重分组，MULTI-INSTANCE-COLLAB §3.1）；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 缺失/损坏 → []（按缺失降级）。
+ *
+ * 身份复核（批 1 F-MI6）：pid 存在性 × 命令行命中本产品标记族才算活同伴。命令**明确可得
+ * 且不命中** ⇒ 不列为同伴（pid 被他进程复用 ⇒ 消假阳性）；探测失败（null）/ 缺行 ⇒
+ * 保守保留（D-MI10——探测失败 ≠ 死；只读面宁留噪音不隐藏真同伴）。
+ *
+ * **async**（TUI 假死批）：内部经异步对偶探测（`execFile` promise）——每回合调用面不得同步 exec。
+ */
+export async function peerInstances(cwd) {
+  // 惰性：manifest mtime 未变 **∨ 快照年龄 < TTL** → 直接返回缓存快照（零 exec/零读——T-L1c）
+  const nowFn = _testImpl?.nowFn ?? Date.now
+  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 || nowFn() - hit.probedAt < PEER_PROBE_TTL_MS)) 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）
+  // 探测失败（batchAliveAsync → null）→ 按"无活伴"降级——只读面不显示幽灵同伴
+  const aliveFn = _testImpl?.aliveFn ?? batchAliveAsync
+  const othersAlive = others.length > 0 ? await 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 ?? probeCmdlinesAsync
+    cmdlines = await probe([...new Set(liveOthers.map((g) => g.pid))])
+  }
+  const known = cmdlines instanceof Map
+  const peerGroups = liveOthers.filter((g) => {
+    const cmd = known ? cmdlines.get(g.pid) : undefined
+    return cmd == null || cmd === "" || isProductProc(cmd) // 缺行/探测失败 ⇒ 保守保留
+  })
+  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 peerGroups) {
+    const end = known ? 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, probedAt: nowFn(), peers })
+  return peers
+}
+
+/**
+ * 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."
+ */
+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 = (await 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/permission.mjs

@@ -0,0 +1,79 @@
+/**
+ * permission.mjs — 权限闸（核内结构归位；CORE-UNIFICATION §2.5 #165「融合：权限闸按核内结构
+ * 归位 + 展示面按端注入」）。
+ *
+ * 来源：
+ *  - `summarize` / `formatPermission` / `askPermission` 的**闸语义** = CLI
+ *    `thincoder-cli/src/cli/permission.mjs`（逐字随迁；每工具定制化请示文案 + 非交互默认拒绝
+ *    的 safety-first 口径）。
+ *  - **展示面（④ 端差）** = 按端注入：CLI 用本档默认的 TTY 文本问答；VSC 的面板卡片在装配层
+ *    传入自己的 `io.ask`（`askPermission` 的第三参），核内不出现端名分支（契约 5 / 10）。
+ *
+ * 闸语义（两端同，前提校验成立）：`autoApprove` 每回合快照 + 中途 live 标志的判定在上层
+ * dispatch 内；本档只管「问一次 + 拿到布尔」。
+ */
+import { createInterface } from "node:readline"
+
+/** CLI tool arg summary (truncated long JSON) */
+export function summarize(toolArgs) {
+  const s = JSON.stringify(toolArgs)
+  return s.length > 120 ? s.slice(0, 120) + "..." : s
+}
+
+/** Permission request key info (per-tool customized). name may include a sub-agent prefix
+ *  ("coder/bash") — extract the basename for matching. */
+export function formatPermission(name, args) {
+  const cap = (s, n = 1000) => (s.length > n ? `${s.slice(0, n)}…(共 ${s.length} 字符)` : s)
+  const base = name.includes("/") ? name.split("/").pop() : name
+  if (base === "bash") return cap(args.command ?? "")
+  if (base === "write") return `${args.path}（写入 ${(args.content ?? "").length} 字符）\n${cap(args.content ?? "", 1000)}`
+  if (base === "edit") {
+    const oldLines = cap(args.old_string ?? "", 500).split("\n").map((l) => `- ${l}`).join("\n")
+    const newLines = cap(args.new_string ?? "", 500).split("\n").map((l) => `+ ${l}`).join("\n")
+    return `${args.path}\n${oldLines}\n  ↓\n${newLines}`
+  }
+  if (base === "delete") return `${args.path}${args.force ? "（force：跟踪文件也删）" : ""}`
+  if (base === "subagent") return cap(args.task ?? "", 500)
+  if (base === "memory") {
+    // §6 action-routed preview: put shows content, batch delete/clear show the gate args
+    const action = String(args.action ?? "")
+    if (action === "put") return `[${args.type ?? ""}] ${args.title ?? ""}\n${cap(args.content ?? "", 500)}`
+    if (action === "delete") return args.id ? `id=${args.id}${args.layer ? ` layer=${args.layer}` : ""}` : `batch delete layer=${args.layer ?? ""} type=${args.type ?? ""} keyword=${args.keyword ?? ""} confirm=${args.confirm}`
+    if (action === "clear") return `clear layer=${args.layer ?? ""} confirm=${args.confirm}`
+    return cap(summarize(args), 300)
+  }
+  return cap(summarize(args), 300)
+}
+
+/**
+ * Permission confirmation. Default channel = interactive y/n on the TTY; non-interactive
+ * defaults to deny (safety-first) — the CLI semantics, preserved verbatim.
+ *
+ * ④ 端差注入点：`io.ask({ name, toolArgs, text })` 返回 `Promise<boolean>`（或不返回 =
+ * 未处理 ⇒ 回退默认通道）。VSC 面板卡片在自己的装配层传入；核内零端名分支。
+ *
+ * @param {string} name
+ * @param {object} toolArgs
+ * @param {{ask?: Function}} [io]
+ * @returns {Promise<boolean>}
+ */
+export async function askPermission(name, toolArgs, io = {}) {
+  const text = formatPermission(name, toolArgs)
+  if (typeof io.ask === "function") {
+    const answer = await io.ask({ name, toolArgs, text })
+    if (answer !== undefined) return Boolean(answer)
+  }
+  if (!process.stdin.isTTY) {
+    console.error(`\n[deny] ${name} (non-interactive, side-effect tools require a TTY)`)
+    return false
+  }
+  const rl = createInterface({ input: process.stdin, output: process.stderr })
+  try {
+    const answer = await new Promise((resolve) => {
+      rl.question(`\n[allow?] ${name}\n${text}\n(y/N) `, resolve)
+    })
+    return answer.trim().toLowerCase() === "y"
+  } finally {
+    rl.close()
+  }
+}