@thincoder/core 0.9.4 → 0.10.1

package/agent/turn-loop.mjs

@@ -0,0 +1,244 @@
+/**
+ * agent/turn-loop.mjs — runAgent 回合环（2026-09-29 P2 三拆：agent.mjs runAgent 段 2 ∕ 3 ∕ 5 ∕ 6
+ * verbatim 迁入——循环局部 ∕ `_ctxBasis` ∕ drainChildUpstream ∕ for 循环本体 ∕ 零落盘结账 +
+ * ContinueError；模型调用段经 callModelTurn 外提 agent/chat-call.mjs）。
+ * 接口 = runTurnLoop(agent, ctx)；控制流零转换（`continue` ∕ `return cr.content` ∕ `throw` 全留环内）。
+ */
+import { resolve } from "node:path"
+import { pushReal, summarizeRunExplorations } from "../context.mjs"
+import { abortError, annotateAbort } from "../abort-provenance.mjs"
+import { specForModel, assistantToolCallMessage } from "../config.mjs"
+import { executeToolCalls } from "./dispatch.mjs"
+import { recordToolResults } from "./record-results.mjs"
+import { injectPostTurn } from "./post-turn.mjs"
+import { handleCompletion } from "./completion.mjs"
+import { runCompactionCheck, injectTurnReminders, injectResponseReminders } from "./run-stages.mjs"
+import { callModelTurn } from "./chat-call.mjs"
+import {
+  turnFrame, // 第 19 批（TURN-ACROSS-SEGMENTS）：跨段累计编号帧（设计 TURN-CAP-CONTINUE.md §4）
+  ContinueError,
+  FILE_MUTATORS, toolTouchPaths,
+} from "./helpers.mjs"
+
+export async function runTurnLoop(agent, {
+  maxTurns, threshold, toolSchemas, toolByName, systemPrompt,
+  depth, signal, autoTurn, streamOutput,
+  consumeInjected, consumeQueuedInput, callbacks, distillSignal,
+}) {
+  let guardPushbacks = 0
+  let advisorPushbacks = 0
+  let honestReminderInjected = false
+  const recentCallSigs = []
+  // "once" stream rules fire at most once per runAgent call; the set survives across
+  // chat() calls (rule abort-retry, tool loop) within the turn.
+  const streamRuleFired = new Set()
+
+  // Compaction overhead for the pure-estimation path: system prompt + tools schema are
+  // in every request but not in history — without them the first-turn/just-compacted
+  // estimate under-counts and may never trigger. Measured path already includes both.
+  const compactionOverhead = {
+    systemPrompt,
+    tools: toolSchemas,
+    // TRACES.md §6.1 D-TR4：compress 轨迹 depth 元数据（runAgent 的 depth 在此作用域——
+    // context.mjs compressIfNeeded 经 extras 透出到 logCtx）
+    traceDepth: depth,
+  }
+  // F-CC1（§6.16.4 阈值单源接线）：本回合压缩判定所用的阈值 + 固定开销面暂存——
+  // `context` 工具的 stats 报**同一口径**（不自行重算第二口径；VSC checkAndCompact 同款暂存）。
+  agent._ctxBasis = { threshold, overhead: compactionOverhead }
+
+  // SUBAGENT-UPSTREAM-CHANNEL（AGENT-LOOP-UPSTREAM.md §6.27.4 消费点）：子 → 父在飞消息的
+  // 回合边界注入单点取用一次（模块缓存 ⇒ 每 run 一次代价）；动态 import = 零新增静态边
+  // （先例 = 上方 injectAsyncResult :113-117）。
+  const { drainChildUpstream } = await import("../agent-tools/parent-channel.mjs")
+
+  // #417（撞帽载荷「本段零落盘轮数」——只报数：零阈值 / 零自动动作）：计数基线——回合环逐轮
+  // 比对 `_touchedFiles` 增量（轮顶对上一轮结账；撞帽收尾轮在环外单结）。
+  agent._turnFilesMark = agent._touchedFiles.length
+
+  for (let turn = 0; turn < maxTurns; turn++) {
+    // 第 19 批（TURN-ACROSS-SEGMENTS——设计 TURN-CAP-CONTINUE.md §4）：编号帧——
+    // `_turnSeq` 每轮 +1（跨段累计，仅 `!resume` 链起点复位）；面向消费面的两字段
+    // （状态行 + ⟦ev⟧turn / ⟦ev⟧approval 事件共用）在此同点赋值（编号唯一权威；帧
+    // 公式 = helpers.mjs turnFrame）。段内帽判定不读帧（下行循环条件只读段内
+    // turn / maxTurns——N6）。
+    const frame = turnFrame(++agent._turnSeq, turn, maxTurns)
+    agent._currentTurn = frame.turn
+    agent._maxTurns = frame.maxTurns
+    // #417（撞帽载荷「本段零落盘轮数」——采集点与 `_turnSeq` 同源面）：上一轮至今 `_touchedFiles`
+    // 零增 ⇒ 上一轮零落盘，计数 +1；mark 前移（收尾轮在环外结账——见下方 ContinueError 前）。
+    if (turn > 0 && agent._touchedFiles.length === agent._turnFilesMark) agent._zeroWriteTurns += 1
+    agent._turnFilesMark = agent._touchedFiles.length
+    // D2 (AGENT-LOOP-SUBAGENT.md §6.7.2): depth>0 children emit a ⟦ev⟧turn progress token each turn —
+    // single emit point covering all three spawn tools; phase=llm (tool/done progress rides
+    // the onToolCall/onToolResult relay — no token for those). 第 19 批：载荷取上方帧值
+    // （agent._currentTurn / _maxTurns——字段形态 / 字段数 / phase 零变化，N5）。
+    if (depth > 0 && callbacks.onToken) {
+      callbacks.onToken(`⟦ev⟧turn\x1e${agent._currentTurn}\x1e${agent._maxTurns}\x1ellm\x1e`)
+    }
+    // §2.5 #78 并入（VSC 帧回调）：每轮帧另经结构化回调发出（池条目 entry.turn 的
+    // VSC 等价通道——⟦ev⟧turn token 解析的宿主面随时可用；签名扩展向后兼容）。
+    callbacks.onAgentTurn?.(frame.turn, frame.maxTurns)
+
+    // SUBAGENT-OBSERVE-SEND D2: 子代理回合边界消费点——每轮开头把父侧经 subagent
+    // action:'send' 注入队列（entry._injected）的消息按普通 user 回合推入子历史
+    // （pushReal → 下一轮 chat 即含该指令）。由 executeAsyncSpawn 经 childRunOpts 贯通的
+    // consumeInjected 回调承载（异步子代理专属——缺省 null：主会话/阻塞子代理零开销）。
+    consumeInjected?.(agent)
+    // 子代理在飞消息（子 → 父；§6.27）：空队列 no-op；非空 ⇒ 恰一条合并 user 消息注入。
+    drainChildUpstream(agent)
+    // ③ 用户 → 主会话投递（步边界 pickup——queue-visible 批 fix 轮 2026-09-24 · F16）：循环头
+    // 回合边界缝（核只给缝、不给策略——取批 / pushReal / 呈现归端侧闭包）；缺省 null，系统轮不传
+    // （`AGENT-LOOP-ASYNC-POOL.md` §6.8「步边界 pickup」· 适用面 = 用户回合）。
+    consumeQueuedInput?.(agent)
+
+    const lastRole = agent.history.at(-1)?.role
+    if (lastRole === "user" || lastRole === "tool") {
+      // 2026-09-05 实践轮：压缩检查/降级计数提为 runCompactionCheck（agent/run-stages.mjs——
+      // CLI 对位 VS run-stages）——循环骨架此处只剩检查调用（recentCallSigs 对象引用回流）。
+      await runCompactionCheck(agent, { threshold, callbacks, compactionOverhead, signal, recentCallSigs })
+    }
+
+    // 2026-09-05 实践轮：plan cadence + eng 状态注入提为 injectTurnReminders（run-stages）
+    await injectTurnReminders(agent, { depth })
+
+    const response = await callModelTurn(agent, {
+      systemPrompt, toolSchemas, streamOutput, callbacks, signal, streamRuleFired, autoTurn, depth, turn,
+    })
+
+    // 内置工具（Responses web_search）结果本地化：服务端已执行——入历史为 tool 消息；
+    // 服务端 item id 是 msg_xxx 非 web_search_call_ 前缀——必须合成前缀（toItems 识别锚点），
+    // 原始 id 存入 content（真机冒烟 2026-08-31 验证）。
+    for (const btr of response.builtinToolResults ?? []) {
+      if (!btr?.id) continue
+      pushReal(agent, {
+        role: "tool",
+        tool_call_id: `web_search_call_${btr.id}`,
+        content: JSON.stringify({ id: btr.id, query: btr.query ?? "", sources: btr.sources ?? [], status: btr.status ?? "completed" }),
+      })
+    }
+
+    // Stream rule triggered mid-generation (action: "abort"): halt, inject the rule's
+    // message as a reminder, retry from the same context.
+    if (response.ruleTriggered) {
+      if (response.content) {
+        pushReal(agent, { role: "assistant", content: response.content })
+      }
+      const label = response.ruleName ? ` — stream rule "${response.ruleName}"` : ""
+      agent.history.push({
+        role: "user",
+        content: `[System reminder${label}: ${response.ruleMessage}]`,
+      })
+      continue
+    }
+
+    // Stream rule warnings / finish-reason 警告（2026-09-05 实践轮——提为
+    // injectResponseReminders，agent/run-stages.mjs——verbatim，语义零变）
+    injectResponseReminders(agent, response)
+
+    // User interrupted mid-generation (Ctrl+I): commit partial output + inject the
+    // message, then signal the outer loop to recreate the controller and resume.
+    if (response.interrupted) {
+      if (response.content) {
+        pushReal(agent, { role: "assistant", content: response.content })
+      }
+      agent.history.push({
+        role: "user",
+        content: `[User interrupt: ${response.interruptMessage}]`,
+      })
+      // AGENT-LOOP-SUBAGENT.md §6.12 站点 #8（第 24 批）：错误对象已自带 name/message——只补来源标注（缺 abortInfo 才补）
+      throw annotateAbort(Object.assign(new Error("User interrupted"), { name: "AbortError" }), signal, "agent", "interrupted-response")
+    }
+
+    if (response.usage) {
+      callbacks.onUsage?.(response.usage)
+      if (response.usage.prompt_tokens != null) {
+        agent._lastPromptTokens = response.usage.prompt_tokens
+        agent._usageAtLen = agent.history.length
+      }
+    }
+
+    // Warn on abnormal finish reasons — the response may be incomplete/truncated.
+    // 2026-09-05 实践轮：finish-reason 注入随流规则警告提为 injectResponseReminders。
+
+    if (response.toolCalls.length === 0) {
+      const cr = handleCompletion(agent, response, depth, turn, guardPushbacks, honestReminderInjected, advisorPushbacks, callbacks)
+      guardPushbacks = cr.guardPushbacks
+      honestReminderInjected = cr.honestReminderInjected
+      advisorPushbacks = cr.advisorPushbacks
+      if (cr.action === "continue") continue
+      if (depth === 0) {
+        // End-of-run exploration distillation (CONTEXT-COMPACTION §5 + SEND-STALL-DISTILL
+        // §2.1): async — the promise hangs on _pendingDistill, settling at the next run's
+        // start or the TUI exit flush. Silent (N3): failure never blocks return/history.
+        // TRACES.md §6.1 D-TR4：depth 透传（distill 轨迹元数据——与 compress 同通道）；extras = 会话续写前缀面（§6.15）
+        // §2.5-B（P4-I）：端壳经 `opts.distillSignal` 供蒸馏专用中止信号（与运行 signal 分离——
+        // 运行 controller 重建不杀蒸馏）；缺省（null）⇒ `signal` 逐字零变。
+        const distill = summarizeRunExplorations(agent, callbacks, distillSignal ?? signal, depth,
+          { systemPrompt, tools: toolSchemas }).catch(() => {}) // 与回合请求同源（无第二构造点）
+        agent._pendingDistill = distill
+      }
+      return cr.content
+    }
+
+    // abort after chat completes, before committing history: don't commit a half-finished turn
+    if (signal?.aborted) throw abortError(signal, "agent", "post-chat")
+
+    pushReal(agent, assistantToolCallMessage(response, specForModel(agent.provider.model)))
+
+    const results = await executeToolCalls(agent, toolByName, response.toolCalls, callbacks, depth, signal)
+
+    // Ctrl+I interrupt during tool execution: skip committing partial results — inject
+    // the interrupt and retry (placeholder results keep strict providers pairable).
+    if (signal?.reason?.interrupt) {
+      // 中断变更记账（2026-08-31 评审 #4）：此分支的工具已全部执行完成（磁盘已变，execute 已完成），
+      // 真实结果按语义不进历史（placeholder 替代）——但变更必须记账：否则 guard 看到
+      // "本轮未改代码" 放行，评审/verify 门禁被绕过（文件改了却没评审）。
+      // §29 fix A（2026-09-07）：mutation-seq 记账已收敛到 dispatch runOne 执行成功即刻
+      // （唯一记账点——本分支不再 noteMutations——不双计——中断+同批 launch seq 单计
+      // 回归断言见 §29 T-A1i）；此处仅剩 guard 标志 + touchedFiles 记账。
+      for (const { toolCall, ok } of results) {
+        const tool = toolByName.get(toolCall.name)
+        if (!ok || !tool || !FILE_MUTATORS.has(toolCall.name)) continue
+        agent._mutatedThisRun = true
+        agent._calledAdvisorThisRun = false
+        agent._verifiedThisRun = false
+        agent._verifyPassed = undefined
+        try {
+          const args = JSON.parse(toolCall.arguments)
+          const paths = toolTouchPaths(tool, args)
+          for (const p of paths) {
+            const abs = resolve(agent.cwd, p)
+            if (!agent._touchedFiles.includes(abs)) agent._touchedFiles.push(abs)
+          }
+        } catch { /* 畸形 args 不影响记账（touchedFiles 尽力而为） */ }
+      }
+      // The assistant tool_calls were committed above — synthesize placeholder tool
+      // results BEFORE the interrupt message (strict providers 400 on dangling
+      // tool_calls; consult P1, 2026-08-30).
+      for (const tc of response.toolCalls) {
+        agent.history.push({ role: "tool", tool_call_id: tc.id, content: "[Tool execution interrupted — results discarded]" })
+      }
+      agent.history.push({
+        role: "user",
+        content: `[User interrupt: ${signal.reason.message}]`,
+      })
+      callbacks.onTurnEnd?.(agent, turn)
+      continue
+    }
+
+    // Model is executing tools → real work: reset guard pushback counters
+    guardPushbacks = 0
+    advisorPushbacks = 0
+
+    // Commit tool results (pairing, multimodal deferral, mutation accounting, reindex)
+    await recordToolResults(agent, toolByName, results)
+
+    injectPostTurn(agent, results, recentCallSigs, callbacks, turn)
+  }
+
+  // #417（撞帽载荷「本段零落盘轮数」）：收尾轮（撞帽轮）若零落盘同样计入——轮顶计数只
+  // 覆盖到倒数第二轮（maxTurns ≤ 0 时环未跑，不虚计）。
+  if (maxTurns > 0 && agent._touchedFiles.length === agent._turnFilesMark) agent._zeroWriteTurns += 1
+  throw new ContinueError(maxTurns)
+}

package/agent/write-gate.mjs

@@ -3,7 +3,7 @@
  *
  * v2 唯一增量（模块设计 §2.1）：评审对象 / 被审文件路径来源改读 manifest `docRoot`
  * （去硬编码 `docs/`），token 门（`anyLiveDesignSlot`）与冻结窗口谓词本体继承 v1 零改
- * （KD-M4-3）——本档只承载两个单点：
+ * （KD-M4-3）——本档承载三个单点：
  *
  * 1. `resolveReviewTargetPaths(agent)` —— 评审目标解析单点：读 manifest `docRoot`
  *    产出评审对象 / 被审文件的绝对路径集合（目录级；子键值形态 = 串 | 多根数组，
@@ -15,19 +15,28 @@
  *    KD-M1-12）：CLI make-agent.mjs / VSC setup.mjs 同判）；读错（权限等）→ 上抛不伪装成缺失（manifest.mjs 契约）。
  *    M6 的 `advisor.mjs` design-review 分类分支消费本导出
  *    （KD-M6-1——同源不重复实现；落 dispatch.mjs 会让 advisor 反向 import 门禁簇成环）。
+ *    **按用点形（2026-10-02 收口 · 台账 #828）**：`resolveReviewRootsFor(dir)`——同单点
+ *    非第二实现（按目标目录 ∥ 所属项目根解析；多档锚下各文档按各自项目判定）。
  * 2. `freezeWindowConflict(agent, absPaths)` —— D5 冻结窗口判据组装：被审文件集 =
  *    声明文档集（`inflightDesignReviewConflict` 同源 docAbs 腿）+ 批次档（`run.batchDoc`
- *    腿——评审绑定批档在途时，写批档同样致 stale）。dispatch.mjs / VSC tool-gates.mjs
+ *    腿——评审绑定批档在途时，写批档同样致 stale）。dispatch.mjs
  *    只 import 消费，不再各自直连 `advisor-settle.mjs`。
+ * 3. `batchRecordWriteConflict(agent, depth, absPaths)` —— 批次档写门判据组装（#309 ·
+ *    `AGENT-LOOP-SUBAGENT.md` §6.29.1）：判据与拒绝文案同址（文案字面只出本档）。
+ *    2026-09-29 收窄（台账 #545）：自身批次伴随件（非 `.md` · 同目录 · 词干族 = 三合取）放行——
+ *    批次档本体 ∕ 他批伴随件 ∕ 异目录伴随件照拒；两端取用 = 核 `agent/dispatch.mjs` Phase 1（两端同径）。
  *
  * 继承零改面（本档不碰）：token 门资格判据（anyLiveDesignSlot / validateDesignToken）、
  * 代码路径判定（conventions.mjs 单一权威分类——KD-M4-1 保留为代码路径判定用）。
  */
+import { basename, dirname, resolve } from "node:path"
 import { DEFAULT_MANIFEST, docRootPaths, readManifest } from "../manifest.mjs"
 // advisor-settle 无上游依赖本簇（dispatch → write-gate → advisor-settle 单向）。normAbs
 // 权威本体 = review-facts.mjs（第 33 批迁入），advisor-settle re-export；本档再 re-export
 // （指针链非副本），M6 经本档一行 import 取齐。
 import { inflightDesignReviewConflict, normAbs } from "../agent-tools/advisor-settle.mjs"
+// 批次档路径单源（叶档——`BATCH-RECORD.md` §4.15）：批次档写门基底集取 `batchDocBases`。
+import { batchDocBases } from "../agent-tools/batch-paths.mjs"
 export { normAbs }
 
 /** 评审目标解析读的 docRoot 键集（评审对象/被审文件可住的所有文档层——M6 分类据此判定）。 */
@@ -44,14 +53,21 @@ const REVIEW_ROOT_KEYS = ["requirements", "specs", "design", "modules", "batches
  * @returns {string[]} 评审目标目录的绝对路径（去重）
  */
 export function resolveReviewTargetPaths(agent) {
-  const cwd = agent?.cwd ?? process.cwd()
-  // 读错上抛（manifest.mjs:readManifest 契约——不伪装成缺失）；整档缺失/非法 → {ok:false}。
-  const man = readManifest(cwd)
+  return resolveReviewRootsFor(agent?.cwd ?? process.cwd())
+}
+
+/** 同单点之**按用点解析**增量（2026-09-21「参数按用点解析」之裁收口 · 台账 #828）：按**目标目录**
+ *  （其所属项目根——最近带档祖先）解析评审目标根集——多档锚下各文档按各自项目判定。
+ *  @param {string} dir 目标目录（项目根——最近带档祖先）
+ *  @returns {string[]} 评审目标目录绝对路径（去重）
+ */
+export function resolveReviewRootsFor(dir) {
+  const man = readManifest(dir)
   const root = man.ok && man.manifest?.docRoot && typeof man.manifest.docRoot === "object"
     ? man.manifest.docRoot
     : DEFAULT_MANIFEST.docRoot
   const out = []
-  for (const key of REVIEW_ROOT_KEYS) out.push(...docRootPaths(root?.[key], cwd))
+  for (const key of REVIEW_ROOT_KEYS) out.push(...docRootPaths(root?.[key], dir))
   return [...new Set(out)]
 }
 
@@ -85,3 +101,84 @@ export function freezeWindowConflict(agent, absPaths) {
   }
   return null
 }
+
+/** 批次档写门基底集**按 run 记忆化**（每 run 一次 manifest 读——§6.29.1；键 = agent 对象）。
+ *  载体 = WeakMap（agent 回收即随 GC——无跨 run 残留）；cwd 变更即失效重读。
+ *  **歧义锚**（多项目并存 · #828）⇒ 基底 = 候选项目基底**并集**（`batchDocBases` 解析单点——覆盖随之对齐）。 */
+const batchGateBasesMemo = new WeakMap()
+
+/** 比较键（绝对形态归一：`.` 段归位 + 分隔符归一 `/` + win32 大小写归一——§6.29.1 判据）。 */
+const gateKey = (p) => {
+  const s = resolve(String(p)).replace(/\\/g, "/")
+  return process.platform === "win32" ? s.toLowerCase() : s
+}
+
+function memoizedBatchBases(agent, cwd) {
+  const memo = agent && typeof agent === "object" ? batchGateBasesMemo.get(agent) : null
+  if (memo && memo.cwd === cwd) return memo.bases
+  const bases = batchDocBases(cwd)
+  if (agent && typeof agent === "object") batchGateBasesMemo.set(agent, { cwd, bases })
+  return bases
+}
+
+/** 目标是否落基底根内（按路径段——win32 大小写归一；同 `batch-paths.mjs` 越基底判据口径）。 */
+function underBase(targetKey, baseAbs, cwd) {
+  const root = gateKey(normAbs(baseAbs, cwd))
+  return targetKey === root || targetKey.startsWith(root.endsWith("/") ? root : root + "/")
+}
+
+/** 自身批次伴随件判据（三合取——`AGENT-LOOP-SUBAGENT.md` §6.29.1 · 2026-09-29 收窄 · 台账 #545）：
+ *  ① 目标非 `.md`（批次档本体永在门内——含近词干 `<词干>-v2.md`；`.md` 判定大小写不敏感 = fail-closed 侧）；
+ *  ② 目标与绑定档同目录；③ 目标基名以 `<词干>.` 或 `<词干>-` 打头（词干 = 绑定档基名剥 `.md`）。
+ *  入参 = 比较键（gateKey 归一后——win32 大小写归一同覆盖 ②③ 的字面比较）。
+ *  @returns {boolean} 三合取全中 = true（放行面）；余者 false（照拒） */
+function isOwnBatchCompanion(targetKey, boundKey) {
+  const targetBase = basename(targetKey)
+  if (targetBase.toLowerCase().endsWith(".md")) return false // ① 批次档本体（任何 `.md`）永在门内
+  if (dirname(targetKey) !== dirname(boundKey)) return false // ② 同目录（按比较键）
+  const boundBase = basename(boundKey)
+  const stem = boundBase.toLowerCase().endsWith(".md") ? boundBase.slice(0, -3) : boundBase
+  return targetBase.startsWith(stem + ".") || targetBase.startsWith(stem + "-") // ③ 词干族（`.` ∕ `-` 前缀）
+}
+
+/**
+ * 批次档写门判据（#309 · `docs/core/design/AGENT-LOOP-SUBAGENT.md` §6.29.1——containment；
+ * 2026-09-29 收窄 · 台账 #545）：
+ * 工程角色子代理（`depth > 0` ∧ `agent._batchDoc` 在场）对**批次档文件**的写 ⇒ 目标 ≠ 绑定档
+ * **且非绑定批次的伴随件**（见 `isOwnBatchCompanion`）⇒ 冲突（fail-closed；写自己绑定的档 ∥
+ * 自身批次伴随件 = 正常面放行）。比较键 = 绝对路径 + win32 大小写归一。
+ * 界面：depth 0（主 agent——跨档处置是父侧职责）· 无 `_batchDoc`（非工程绑定族）· 主基底外的
+ * 普通文件写 —— 三种形态均不进本门（返回 null，行为零变）。判据集由调用方限定 = `FILE_MUTATORS`
+ * （`file_ops` / 读类不在门内——§6.29.1 边界）。
+ * 拒绝文案**单源 = 本档**（两端直取 `message`——零字面副本）。
+ * 恒零抛（形照 `freezeWindowConflict` 先例——全判据带形态守卫）。
+ * @param {Object} agent — 子代理 agent（读 `_batchDoc` / `cwd`）
+ * @param {number} depth — 执行深度（> 0 = 子代理）
+ * @param {string[]} absPaths — 本次写将触碰的绝对路径集（调用方已 resolve）
+ * @returns {{bound: string, target: string, message: string}|null} 命中 = 冲突信息 / 否则 null
+ */
+export function batchRecordWriteConflict(agent, depth, absPaths) {
+  if (!(depth > 0)) return null
+  const bound = agent?._batchDoc
+  if (typeof bound !== "string" || bound.length === 0) return null
+  const wanted = (absPaths ?? []).filter((p) => typeof p === "string" && p.length > 0)
+  if (wanted.length === 0) return null
+  const cwd = typeof agent?.cwd === "string" && agent.cwd.length > 0 ? agent.cwd : process.cwd()
+  const bases = memoizedBatchBases(agent, cwd)
+  const boundAbs = normAbs(bound, cwd)
+  const boundKey = gateKey(boundAbs)
+  for (const p of wanted) {
+    const target = normAbs(p, cwd)
+    const targetKey = gateKey(target)
+    if (targetKey === boundKey) continue // 写自己绑定的档 = 正常面
+    if (!bases.some((b) => underBase(targetKey, b, cwd))) continue // 非批次档文件（含缺 manifest 的基底外盘面）
+    if (isOwnBatchCompanion(targetKey, boundKey)) continue // 自身批次伴随件 = 放行面（三合取——见判据）
+    return {
+      bound: boundAbs,
+      target,
+      message: `write refused — cross-batch batch-record write: this child is bound to ${basename(boundAbs)}; ${basename(target)} belongs to a different batch. Write only your own bound record and its companion files (the batch tool targets your bound record); the parent agent handles other batch records.`,
+    }
+  }
+  return null
+}
+

package/agent-tools/advisor-async.mjs

@@ -4,7 +4,7 @@
  * The advisor tool runs reviews in a background pool at depth 0 (default async —
  * ruling ②-3 A): the launch returns an ack, the turn ends naturally, the session
  * suspends, the review settles into _pendingAsyncResults and a digest turn
- * delivers the report (§17 consumption machinery — role-agnostic; entries carry
+ * delivers the report (AGENT-LOOP-ASYNC-POOL.md §6.8 consumption machinery — role-agnostic; entries carry
  * role "advisor" and ride the subagent panel as a pseudo-role, ruling ②-4 A).
  *
  * This module owns:
@@ -51,7 +51,7 @@ import { normAbs, mutationSeqOf, settleAdvisorRun } from "./advisor-settle.mjs"
 export {
   mutationSeqOf, noteMutations, reviewIsStale, settleAdvisorRun, inflightDesignReviewConflict,
 } from "./advisor-settle.mjs"
-// 第 33 批（§17.5）：doc-set 键迁事实面档（实例续跑与陈旧判定同锚单源；原为私有——零 import 面）。
+// 第 33 批（评审失败护栏）：doc-set 键迁事实面档（实例续跑与陈旧判定同锚单源；原为私有——零 import 面）。
 // 本文件继续在实例解析 / 池 entries 上消费它。
 import { docSetKey } from "./review-facts.mjs"
 // F31（2026-09-18 顾问面治理批）：拒回文案对象标识行单源。
@@ -110,7 +110,7 @@ function openDesignRun(agent, key) {
 }
 
 /**
- * Resolve the review instance a launch continues (§11.2 ③ — per-review
+ * Resolve the review instance a launch continues (AGENT-LOOP-ASYNC-POOL.md §6.10 ③ — per-review
  * rounds/prior; reviewId = designId for design reviews, a random id for code).
  *  - design: continue the OPEN instance of the same document set (fix rounds of
  *    a review thread keep its designId and its round/prior); none → new instance.
@@ -172,7 +172,7 @@ export function effectiveAdvisorRound(agent) {
 
 export const ADVISOR_POOL_LIMIT = 4
 
-/** §11.2 advisor 池生效上限（纯——读 agent.poolLimits.advisor——合法 ≥1 整数生效——
+/** AGENT-LOOP-ASYNC-POOL.md §6.10 advisor 池生效上限（纯——读 agent.poolLimits.advisor——合法 ≥1 整数生效——
  *  非法/缺省回退 ADVISOR_POOL_LIMIT——与 subagent 域 resolvePoolLimits 独立不共享
  *  （subagent 两键表不含本键——键表语义不同——POOL-CONFIG-UNIFIED F-2））。 */
 export function resolveAdvisorPoolLimit(raw) {
@@ -185,7 +185,7 @@ export function resolveAdvisorPoolLimit(raw) {
 export function advisorPoolLimitFor(agent) {
   return resolveAdvisorPoolLimit(agent?.config?.agent?.poolLimits)
 }
-/** §11.2 同 scope 守卫（F-5——用户裁①）：同 reviewType+scope 有 running 评审 → true
+/** §6.10 同 scope 守卫（F-5——用户裁①）：同 reviewType+scope 有 running 评审 → true
  *  （拒——running 并行多实例歧义放大——settled 续跑语义不变）。design scope = 文档集键
  *  （docSetKey）；code = 单 code 线程（记录不记路径键——与 openCodeRun 语义一致）。
  *  与池容量守卫独立：容量 = 全局 ≤N——scope = 同 scope ≤1——两关都过才启动。 */
@@ -257,7 +257,7 @@ export function cancelAsyncAdvisor(agent, id, onToken) {
     return { id: key, status: "cancelled", was: "queued" }
   }
   entry.cancelled = true
-  // §20.3 站点 #11（第 24 批）：定向中止 = cancel（reason 载荷）
+  // AGENT-LOOP-SUBAGENT.md §6.12 站点 #11（第 24 批）：定向中止 = cancel（reason 载荷）
   entry.controller?.abort?.({ abortTrigger: "cancel", abortDetail: "advisor-cancel" })
   return { id: key, status: "cancelled" }
 }
@@ -352,13 +352,13 @@ export function refillAdvisorQueue(parent, onToken) {
  * digest/panel/freeze consumers route it like any other settled block.
  * @returns {{ok: true, id: string}} — ack; or {{ok: true, id: string, queued: true,
  *   position: number}} — ED-4 排队 ack（池满 + 异 scope——slot 释放自动起跑）; or
- *   {{error: string}} — scope guard (same reviewType+scope running — §11.2 F-5)
+ *   {{error: string}} — scope guard (same reviewType+scope running — §6.10 F-5)
  *   or invalid ctx.
  */
 export function launchAsyncAdvisor(parent, ctx, launch) {
   const { reviewType, documents, paths, object, designToken, designId, run } = launch
   const limit = advisorPoolLimitFor(parent)
-  // §11.2 same-scope guard（F-5——用户裁①）：同 type+scope 有 running → 拒——与池容量
+  // §6.10 same-scope guard（F-5——用户裁①）：同 type+scope 有 running → 拒——与池容量
   // 守卫独立两关都过才启动——同 scope 不等不排（settled 续跑不变；排队仅异 scope 面）。
   if (runningAdvisorOfScope(parent, reviewType, run?.docSetKey ?? null)) {
     const scopeNote = reviewType === "design"
@@ -398,7 +398,7 @@ export function launchAsyncAdvisor(parent, ctx, launch) {
   // D6 buildChildSignal 单点（ASYNC-RESULT-CONTAINER.md）。
   const ctrl = new AbortController()
   entry.controller = ctrl
-  // §20.3 站点 #10（第 24 批）：hop 逐跳保 reason；#98 链结单点（interrupt 豁免面——
+  // §6.12 站点 #10（第 24 批）：hop 逐跳保 reason；#98 链结单点（interrupt 豁免面——
   // Ctrl+I 不逐链中止飞行评审）。
   bindChildController(ctrl, buildChildSignal(parent, ctx))
   entry.promise = new Promise((res) => { entry._settle = res })
@@ -416,7 +416,7 @@ export function launchAsyncAdvisor(parent, ctx, launch) {
       signal: entry.controller.signal,
     }, designToken, documents, paths, object, designId)
       .then((report) => { entry.report = report })
-      // §20.3 第 3 条合成器（第 24 批）：原 message 前缀逐字保留 + 来源后缀
+      // §6.12 第 3 条合成器（第 24 批）：原 message 前缀逐字保留 + 来源后缀
       .catch((err) => { entry.error = deathLine(err, entry.controller?.signal) })
       .finally(() => {
         // settle 公共收尾单点（ASYNC-RESULT-CONTAINER.md D3——settleAsyncEntry）：日志三连
@@ -430,7 +430,7 @@ export function launchAsyncAdvisor(parent, ctx, launch) {
           ctx,
           onAccounting: () => {
             const settled = settleAdvisorRun(parent, entry)
-            // §29 fix B：settle 分支输出（清洗/未签发提示）写回 entry.report——digest 原样进。
+            // fix B：settle 分支输出（清洗/未签发提示）写回 entry.report——digest 原样进。
             if (settled.report != null) entry.report = settled.report
           },
         })

package/agent-tools/advisor-settle.mjs

@@ -6,15 +6,15 @@
  *
  * 内容 = 迁入（逐字搬移含注释）+ 本批两处接线：
  *  - `settleAdvisorRun` —— 记账本体零改（轮次 / 陈旧 / token D1 落盘 / prior）；A 族
- *    未完成判定改用单谓词 `advisorIncompleteMarker`（§14.3 消费点 1/2）：design 结算经
+ *    未完成判定改用单谓词 `advisorIncompleteMarker`（ADVISOR-GUARDS.md §1 消费点 1/2）：design 结算经
  *    `settleDesignReview(…, { incomplete })` 未完成即不签发；code 完成守卫同谓词
  *    （旧 `^` 锚首行失败正则退役——六形态语义零丢，含 review_failed 字符串
  *    resolve 形态）；
- *  - `inflightDesignReviewConflict` —— E 族（F17/§14.14）D5 冻结窗口冲突检测：与
+ *  - `inflightDesignReviewConflict` —— E 族（F17/ADVISOR-GUARDS.md §5）D5 冻结窗口冲突检测：与
  *    `reviewIsStale` 同族（同 docAbs / 同 normAbs）、仅扫 running 且未取消的设计条目
  *    （dispatch Phase-1 预闸消费）。
  *
- * 第 33 批（2026-09-11——评审失败护栏 §17.5）：`normAbs` 本体迁 `review-facts.mjs`
+ * 第 33 批（2026-09-11——评审失败护栏）：`normAbs` 本体迁 `review-facts.mjs`
  * （原处 re-export 保面）；**2026-09-18 顾问面治理批**：计数落账（`designReviewOutcome` →
  * `noteDesignReviewOutcome`）随会话级计数器整体退场——改治**失败结论**：结算出口按
  * `settlementCriterion`（纯函数单源，`advisor/notice.mjs`）追加结论块（**两轨共用**——
@@ -23,9 +23,9 @@
 import { persistEngTokens } from "../token-ttl.mjs"
 import { settleDesignReview, makeDesignTokenRegex, stripApprovedSuffix } from "./design-token.mjs"
 import { looksLikeReviewOutput, advisorIncompleteMarker, ADVISOR_LAUNCH_REFUSAL_PREFIX } from "../advisor/run.mjs"
-import { isCodePath, loadConventions } from "../conventions.mjs"
+import { isCodePath, loadProjectDeclaration } from "../conventions.mjs"
 import { logEvent } from "../log.mjs"
-// 第 33 批（§17.5）：`normAbs` 迁 `review-facts.mjs`（中立模块——陈旧判定与事实面共用同一归一）；
+// 第 33 批（评审失败护栏）：`normAbs` 迁 `review-facts.mjs`（中立模块——陈旧判定与事实面共用同一归一）；
 // 2026-09-18：结算分类 / 结论文案单源迁 `advisor/notice.mjs`（纯函数、零状态、零计数载体）。
 import { normAbs } from "./review-facts.mjs"
 import { settlementCriterion, buildSettlementConclusion, scopeSummary } from "../advisor/notice.mjs"
@@ -40,7 +40,7 @@ export function mutationSeqOf(agent) {
 }
 
 /** Record a file-mutation commit — bounded ring feeding the stale scan. paths = ABSOLUTE.
- *  唯一记账点（§29 fix A）：dispatch runOne 写执行成功即刻调用（取代批后段 + 中断分支——
+ *  唯一记账点（fix A）：dispatch runOne 写执行成功即刻调用（取代批后段 + 中断分支——
  *  不双计）；mergeChildMutations（子代理合入）是独立事件面。 */
 export function noteMutations(agent, paths) {
   const list = (paths ?? []).filter((p) => typeof p === "string" && p.length > 0)
@@ -51,7 +51,7 @@ export function noteMutations(agent, paths) {
   if (log.length > 200) log.splice(0, log.length - 200)
 }
 
-// 第 33 批（§17.5）：`normAbs` 本体迁 `review-facts.mjs`；原处 re-export 保既有 import 面
+// 第 33 批（评审失败护栏）：`normAbs` 本体迁 `review-facts.mjs`；原处 re-export 保既有 import 面
 // （advisor-async / 测试）零变。
 export { normAbs } from "./review-facts.mjs"
 
@@ -68,14 +68,14 @@ export function reviewIsStale(agent, entry) {
     const set = new Set(scope)
     return since.some((m) => (m.paths ?? []).some((p) => set.has(normAbs(p, agent?.cwd))))
   }
-  // Code face = the shared classifier (src/conventions.mjs) — one authority with
+  // Code face = the shared classifier (thincoder-core/conventions.mjs) — one authority with
   // the design gate and the mutation guard (PORTABILITY FR12 / PO-10).
-  const conv = loadConventions(agent?.cwd)
+  const conv = loadProjectDeclaration(agent?.cwd)
   return since.some((m) => (m.paths ?? []).some((p) => isCodePath(normAbs(p, agent?.cwd), conv)))
 }
 
 /**
- * E 族（F17/§14.14 E-3d）——D5 冻结窗口写前拦截的冲突检测：设计评审**在途**（点火 → 结算）
+ * E 族（F17/ADVISOR-GUARDS.md §5 E-3d）——D5 冻结窗口写前拦截的冲突检测：设计评审**在途**（点火 → 结算）
  * 期间，父侧对被审文件集（`docAbs` = 声明文档集，含批次档）的写入会被 dispatch 预闸拒绝。
  * 判据与 `reviewIsStale` **同源**（同一 docAbs / 同一 normAbs）；仅扫 **running 且未取消**
  * 的设计条目（已结算 / 已取消条目不拦——结算后写不再致 stale、取消的结算早退不判）。
@@ -112,7 +112,7 @@ export function inflightDesignReviewConflict(agent, absPaths) {
  *     mirror retired per DESIGN-TOKEN-SETTLEMENT D3) + D1 settle-time slot persist
  *     (persistEngTokens — write failure = settle failure: no registration, no
  *     Approved echo, re-review — 评审 #1);
- *  4. §29 fix B — branch-shaped report output (the caller writes it back to
+ *  4. fix B — branch-shaped report output (the caller writes it back to
  *     entry.report; digest injects the CLEANED form): pass → stripped +
  *     Approved/designId suffix (sync 参照形态); persist-failed → stripped +
  *     "D1: …token could NOT be durably written…" re-review notice (no Approved
@@ -121,7 +121,7 @@ export function inflightDesignReviewConflict(agent, absPaths) {
  * 第 11 批增补（A/F11）：`incomplete` = 宿主尾族判定（单谓词）——design 结算未完成即不
  * 签发（`settleDesignReview` 的 `opts.incomplete`）；code 完成守卫的失败判定改用同谓词
  * （六形态语义零丢——旧 `^` 锚正则退役）。
- * 第 33 批增补（§17.5）：design 结算按分类单源落账到会话级护栏——**2026-09-18 撤**（零载体）。
+ * 第 33 批增补（评审失败护栏）：design 结算按分类单源落账到会话级护栏——**2026-09-18 撤**（零载体）。
  * 现行：结算出口按判据名单源（`settlementCriterion`）追加失败结论块（两轨共用；F28/F29）——
  * 判据名非空 ⇒ 块在位（块首行 = 对象标识行）；可用判决 / 中断 / 拒发 ⇒ 零噪声（无块）。
  * Cancelled / parent-aborted reviews consume nothing (the user dropped the
@@ -140,10 +140,10 @@ export function settleAdvisorRun(agent, entry) {
   let report = result
   let passed = false
   let persistFailed = false
-  // 宿主尾族判定（单谓词——design 结算与 code 守卫共用；§14.3 消费点 1/2）。
+  // 宿主尾族判定（单谓词——design 结算与 code 守卫共用；ADVISOR-GUARDS.md §1 消费点 1/2）。
   const incomplete = result != null ? advisorIncompleteMarker(String(result)) : null
   // 启动拒绝报告（未发起请求——无评审产出）：第 33 批上移为本结算段**单点**——消费 = ① design
-  // 失败分类（neutral——无尝试发生，§17.3 #1）② code 守卫 failureVerdict（既有语义零变）。
+  // 失败分类（neutral——无尝试发生；`ADVISOR-GUARDS.md` §7 失败结算表行 1）② code 守卫 failureVerdict（既有语义零变）。
   const launchRefused = result != null && String(result).startsWith(ADVISOR_LAUNCH_REFUSAL_PREFIX)
   if (!stale) {
     if (run.reviewType === "design" && entry.designToken && result) {
@@ -199,7 +199,7 @@ export function settleAdvisorRun(agent, entry) {
     // 第 11 批（F16/A3）：失败判定 = 单谓词六 kind（含 review_failed 字符串 resolve 形态）
     // ——旧 `^` 锚正则只认首行形态，漏「时间线 + 尾」；语义零丢（六形态全覆盖）。
     // 另：设计评审的**启动拒绝报告**（未发起请求——无评审产出）同样不得计为评审覆盖
-    // （§14.4 异步结算面判据；与同步工具面 _advisorRefusals 同源前缀；正常链不可达＝防御纵深）
+    // （异步结算面判据；与同步工具面 _advisorRefusals 同源前缀；正常链不可达＝防御纵深）
     // ——判定已上移为本结算段单点（launchRefused，上方）。
     const failureVerdict = (run.reviewType !== "design" && (
       incomplete !== null ||
@@ -209,7 +209,7 @@ export function settleAdvisorRun(agent, entry) {
       agent._calledAdvisorThisRun = true
     }
   } else if (run.reviewType === "design" && entry.designToken && result != null) {
-    // §29 fix B（stale 分支）：陈旧评审不签发——digest 不得展示未注册 token——先剥
+    // fix B（stale 分支）：陈旧评审不签发——digest 不得展示未注册 token——先剥
     // 方括号回显 + 前置 "评审目标已变更——token 未签发"（不变式——两分支都清洗）。
     const stripped = String(result)
       .replace(makeDesignTokenRegex(entry.designToken, "g"), "")
@@ -217,7 +217,7 @@ export function settleAdvisorRun(agent, entry) {
     report = `评审目标已变更——token 未签发 (review target changed after launch — this review judged a stale state; no design token was issued — re-run the review on the current state)\n\n${stripped}`.trim()
   }
   // Prior of round 2+ = the last REVIEW-LOOKING output (mirror of run.mjs's guard).
-  // F2e (§29.1): strip the engine-approved suffix FIRST — the prior must never
+  // F2e: strip the engine-approved suffix FIRST — the prior must never
   // carry the raw token / designId (exact truncation — zero collateral).
   // 结论块（下方）刻意晚于 prior 归一：prior 只承载评审正文，不携带机制文案。
   if (report && looksLikeReviewOutput(report)) {