@thincoder/core 0.10.2 → 0.10.4

package/agent/turn-loop.mjs

@@ -49,14 +49,22 @@ export async function runTurnLoop(agent, {
 
   // SUBAGENT-UPSTREAM-CHANNEL（AGENT-LOOP-UPSTREAM.md §6.27.4 消费点）：子 → 父在飞消息的
   // 回合边界注入单点取用一次（模块缓存 ⇒ 每 run 一次代价）；动态 import = 零新增静态边
-  // （先例 = 上方 injectAsyncResult :113-117）。
+  // （同款先例 = run-start.mjs:43 ∥ :66——injectAsyncResult 动态 import）。
   const { drainChildUpstream } = await import("../agent-tools/parent-channel.mjs")
+  // #934（零落笔看门狗——AGENT-LOOP-UPSTREAM.md §6.32）：连续零写越阈 ⇒ 自动上行提醒（只推——
+  // 不杀 / 不转向）；单源叶 = zero-write-watch.mjs，动态 import 沿上条同款（零新增静态边）。
+  const { maybeZeroWriteAlert } = await import("../agent-tools/zero-write-watch.mjs")
+  // §6.31.5 落痕写点门（#939）：载体吸收经 `carrierField` 单点（§6.31.4 同式）；动态 import = 零新增静态边（沿上方两条同款）。
+  const { carrierField } = await import("../agent-tools/async-settle.mjs")
 
   // #417（撞帽载荷「本段零落盘轮数」——只报数：零阈值 / 零自动动作）：计数基线——回合环逐轮
   // 比对 `_touchedFiles` 增量（轮顶对上一轮结账；撞帽收尾轮在环外单结）。
   agent._turnFilesMark = agent._touchedFiles.length
 
   for (let turn = 0; turn < maxTurns; turn++) {
+    // #793（核面小修批——AGENT-LOOP.md §6.2 环边界中止前置 ∥ 需求 F5）：环头检查点——中止恒以
+    // AbortError 收束、不开启新轮（环头注入族 / 压缩 / 模型调用零触）。
+    if (signal?.aborted) throw abortError(signal, "agent", "turn-head")
     // 第 19 批（TURN-ACROSS-SEGMENTS——设计 TURN-CAP-CONTINUE.md §4）：编号帧——
     // `_turnSeq` 每轮 +1（跨段累计，仅 `!resume` 链起点复位）；面向消费面的两字段
     // （状态行 + ⟦ev⟧turn / ⟦ev⟧approval 事件共用）在此同点赋值（编号唯一权威；帧
@@ -67,7 +75,18 @@ export async function runTurnLoop(agent, {
     agent._maxTurns = frame.maxTurns
     // #417（撞帽载荷「本段零落盘轮数」——采集点与 `_turnSeq` 同源面）：上一轮至今 `_touchedFiles`
     // 零增 ⇒ 上一轮零落盘，计数 +1；mark 前移（收尾轮在环外结账——见下方 ContinueError 前）。
-    if (turn > 0 && agent._touchedFiles.length === agent._turnFilesMark) agent._zeroWriteTurns += 1
+    // #934（零落笔看门狗——§6.32.2 ① 单点采集）：streak 与越阈判定同点——上轮零写 ⇒ +1 并判越阈；
+    // 有写 ⇒ streak 归零 + 清闩（写后重臂——每连续零写段恰一条）。#417 计数语义逐字保持。
+    if (turn > 0) {
+      if (agent._touchedFiles.length === agent._turnFilesMark) {
+        agent._zeroWriteTurns += 1
+        agent._zeroWriteStreak += 1
+        maybeZeroWriteAlert(agent) // #934：连续零写越阈 ⇒ 自动上行提醒（只推——§6.32）
+      } else {
+        agent._zeroWriteStreak = 0
+        agent._zeroWriteAlerted = false // 写后重臂
+      }
+    }
     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
@@ -106,6 +125,13 @@ export async function runTurnLoop(agent, {
       systemPrompt, toolSchemas, streamOutput, callbacks, signal, streamRuleFired, autoTurn, depth, turn,
     })
 
+    // §6.31.5 落痕（消化账务批 · 2026-10-05 · 台账 #930 ∥ #939 收正）：本 run 内**逐轮追加**——
+    // 每模型轮返回即写（会话态）；首轮签收不为收口轮覆盖（见账取件读累积痕）。
+    // 落父字段（抗 `history` 整体替换——`context.mjs` `applyCompression`）；非会话零动作。
+    if (carrierField(agent, "_daSession") === true && response.content) {
+      agent._lastRunOutput = `${agent._lastRunOutput ?? ""}${response.content}\n`
+    }
+
     // 内置工具（Responses web_search）结果本地化：服务端已执行——入历史为 tool 消息；
     // 服务端 item id 是 msg_xxx 非 web_search_call_ 前缀——必须合成前缀（toItems 识别锚点），
     // 原始 id 存入 content（真机冒烟 2026-08-31 验证）。
@@ -240,5 +266,8 @@ export async function runTurnLoop(agent, {
   // #417（撞帽载荷「本段零落盘轮数」）：收尾轮（撞帽轮）若零落盘同样计入——轮顶计数只
   // 覆盖到倒数第二轮（maxTurns ≤ 0 时环未跑，不虚计）。
   if (maxTurns > 0 && agent._touchedFiles.length === agent._turnFilesMark) agent._zeroWriteTurns += 1
+  // #793（核面小修批——AGENT-LOOP.md §6.2 环边界中止前置 ∥ 需求 F5）：环尾检查点——中止恒以
+  // AbortError 收束（不落 ContinueError——用户 Stop 优先于继续提示；消费契约 = 外层按 reason 判定）。
+  if (signal?.aborted) throw abortError(signal, "agent", "turn-tail")
   throw new ContinueError(maxTurns)
 }

package/agent/write-gate.mjs

@@ -6,8 +6,10 @@
  * （KD-M4-3）——本档承载三个单点：
  *
  * 1. `resolveReviewTargetPaths(agent)` —— 评审目标解析单点：读 manifest `docRoot`
- *    产出评审对象 / 被审文件的绝对路径集合（目录级；子键值形态 = 串 | 多根数组，
- *    展开走 `docRootPaths`）。缺 `docRoot` 键 → `readManifest`
+ *    产出评审对象 / 被审文件的绝对路径集合（目录级；子键值形态 = 串 | 多根数组）。
+ *    判定本体（`REVIEW_ROOT_KEYS` 键集 + `resolveReviewRootsFor(dir)`——2026-10-02 收口 ·
+ *    台账 #828 按用点形）自本档迁 `review-facts.mjs`（2026-10-04 · #921 · KD-2——本档同名
+ *    再出口保既有 import 面）；缺 `docRoot` 键 → `readManifest`
  *    的 fillDefaults 已补默认（架构 §2.3 E2 便利 fallback 落点）；整档缺失 / 非法 JSON →
  *    `{ok:false}` → 回退 DEFAULT_MANIFEST.docRoot（本函数是壳门之下的便利层——E2 的
  *    「整档缺失」由壳面 requireManifest 按用点处置（判 + 报明 / 建档，**不抛**——
@@ -15,8 +17,6 @@
  *    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
@@ -30,7 +30,6 @@
  * 代码路径判定（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 取齐。
@@ -38,13 +37,17 @@ import { inflightDesignReviewConflict, normAbs } from "../agent-tools/advisor-se
 // 批次档路径单源（叶档——`BATCH-RECORD.md` §4.15）：批次档写门基底集取 `batchDocBases`。
 import { batchDocBases } from "../agent-tools/batch-paths.mjs"
 export { normAbs }
-
-/** 评审目标解析读的 docRoot 键集（评审对象/被审文件可住的所有文档层——M6 分类据此判定）。 */
-const REVIEW_ROOT_KEYS = ["requirements", "specs", "design", "modules", "batches"]
+// 2026-10-04（工具路径基面根治批 · #921 · KD-2 同名再出口）：REVIEW_ROOT_KEYS +
+// resolveReviewRootsFor 判定本体迁 `review-facts.mjs`（评审事实面——advisor-async 既有
+// import 面零新模块边）；本档同名再出口（指针非副本——normAbs 同款先例）——既有 import 面
+// （advisor.mjs / 测试）零改；本档消费点 `resolveReviewTargetPaths` 薄委托同名函数。
+export { REVIEW_ROOT_KEYS, resolveReviewRootsFor } from "../agent-tools/review-facts.mjs"
+import { resolveReviewRootsFor } from "../agent-tools/review-facts.mjs"
 
 /**
- * 评审目标解析单点（M4 §2.1#1）：读 manifest `docRoot` → 评审对象 / 被审文件的绝对路径
- * 集合（目录级，反斜杠归一；子键值形态 = 串 | 多根数组，逐键经 `docRootPaths` 展开）。
+ * 评审目标解析单点（M4 §2.1#1）：评审对象 / 被审文件的绝对路径集合（目录级）——
+ * 判定本体（manifest `docRoot` 读面 / 缺档回退 / 读错上抛语义）2026-10-04 迁
+ * `review-facts.mjs` 单源（KD-2——本档薄委托；详述见该档 resolveReviewRootsFor JSDoc）。
  * 缺 `docRoot` 键 → readManifest 已补默认；整档缺失 / 非法 →
  * `{ok:false}` → 回退 DEFAULT_MANIFEST.docRoot（便利层——E2 的「整档缺失」由壳面
  * requireManifest 按用点处置（判 + 报明 / 建档，**不抛**——启动侧恒不拒，KD-M1-25；**工程模式会话**口径——KD-M1-12），本函数不重复拦）；
@@ -56,21 +59,6 @@ export function resolveReviewTargetPaths(agent) {
   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], dir))
-  return [...new Set(out)]
-}
-
 /**
  * D5 冻结窗口判据组装（M4 §2.1#2）：评审在途（点火 → 结算）期间父侧对被审文件集
  * （声明文档集 + 批次档）的写入 → 返回冲突 { id, path }；无冲突 → null。

package/agent-tools/advisor-async.mjs

@@ -47,13 +47,13 @@ export {
 // 第 11 批拆分（2026-09-11）：settle 记账 + 变更日志（noteMutations）+ 陈旧判定
 // （reviewIsStale）+ 冻结冲突（inflightDesignReviewConflict）迁 advisor-settle.mjs——
 // 既有 import 面（dispatch / subagent-async / escalate-async / 测试）经此 re-export 不变。
-import { normAbs, mutationSeqOf, settleAdvisorRun } from "./advisor-settle.mjs"
+import { mutationSeqOf, settleAdvisorRun } from "./advisor-settle.mjs"
 export {
   mutationSeqOf, noteMutations, reviewIsStale, settleAdvisorRun, inflightDesignReviewConflict,
 } from "./advisor-settle.mjs"
 // 第 33 批（评审失败护栏）：doc-set 键迁事实面档（实例续跑与陈旧判定同锚单源；原为私有——零 import 面）。
 // 本文件继续在实例解析 / 池 entries 上消费它。
-import { docSetKey } from "./review-facts.mjs"
+import { docSetKey, resolveReviewDocPaths, scopeAdvisorMirror } from "./review-facts.mjs"
 // F31（2026-09-18 顾问面治理批）：拒回文案对象标识行单源。
 import { withIdentityLine, scopeSummary } from "../advisor/notice.mjs"
 import { runAdvisorReview, resolveAdvisorProvider, ADVISOR_THINKING_PLACEHOLDER } from "../advisor/run.mjs"
@@ -65,6 +65,8 @@ import { deathLine } from "../abort-provenance.mjs"
 // ASYNC-RESULT-CONTAINER.md D3/D6：settle 公共收尾单点 + child signal 构建单点
 import { bindChildController, buildChildSignal, carrierField, getAsyncPool, settleAsyncEntry, tombstoneOf, writeTombstone } from "./async-settle.mjs"
 import { nextSubagentId, consumeSubagentToken, assertPoolKeyFree, entryTerminal } from "./subagent-scheduler.mjs"
+// #934（零落笔看门狗——AGENT-LOOP-UPSTREAM.md §6.32.6 触发接线②）：评审族推送单源（叶档——恒零抛）。
+import { pushAdvisorAlert } from "./zero-write-watch.mjs"
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Review-instance registry (_advisorRuns — per-review rounds/prior/cap)
@@ -135,6 +137,11 @@ export function resolveAdvisorLaunch(agent, reviewType, { documents = null } = {
       // the same id (no slot residue — T14: the old token is then rejected at
       // the gate); old slots die at TTL only, kept as the fail-safe fallback.
       const prior = [...runs.values()].reverse().find((r) => r.reviewType === "design" && r.docSetKey === key)
+      // #863 实例回收（§6.10）：同 docSetKey 保最新一条 closed（= prior——F2h 只取 newest，语义零变）；
+      // 余者去重回收（实例随删释放——closed 零消费面）。
+      for (const r of [...runs.values()]) {
+        if (r !== prior && r.reviewType === "design" && !r.open && r.docSetKey === key) runs.delete(r.reviewId)
+      }
       run = {
         reviewId, reviewType, designId: prior?.designId ?? reviewId,
         round: 0, priorOutput: null, stale: false, open: true, docSetKey: key,
@@ -144,6 +151,10 @@ export function resolveAdvisorLaunch(agent, reviewType, { documents = null } = {
   } else {
     run = openCodeRun(agent)
     if (!run) {
+      // #863 实例回收（§6.10）：新 code 实例创建 ⇒ closed 实例清除（openCodeRun 仅取 open——零消费）。
+      for (const r of [...runs.values()]) {
+        if (r.reviewType === "code" && !r.open) runs.delete(r.reviewId)
+      }
       const reviewId = randomUUID()
       run = {
         reviewId, reviewType, designId: null,
@@ -152,9 +163,9 @@ export function resolveAdvisorLaunch(agent, reviewType, { documents = null } = {
       runs.set(reviewId, run)
     }
   }
-  // Scope the legacy mirror fields (message builder + run.mjs cap + displays).
-  agent._advisorRound = run.priorOutput ? run.round : 0
-  agent._lastAdvisorOutput = run.priorOutput
+  // Scope the mirror fields to THIS instance (message builder + run.mjs cap +
+  // displays; #949 ① — the queued-launch window is re-secured at entry.start).
+  scopeAdvisorMirror(agent, run)
   return { run, isNew: run.round === 0 && !run.priorOutput, reviewId: run.reviewId, designId: run.designId }
 }
 
@@ -381,8 +392,11 @@ export function launchAsyncAdvisor(parent, ctx, launch) {
     id, role: "advisor", reviewType, run,
     reviewId: run.reviewId, designId, designToken, documents, paths, object,
     launchSeq: mutationSeqOf(parent),
+    // docAbs 产出面同源归一（2026-10-04 · #921 · A 随件）：四腿单源 resolved（裸形/前缀形
+    // 命中候选项目根即归一为绝对路径）——冻结窗/陈旧判定对**裸形受理档**照护成立（否则 A
+    // 开冻结窗保护洞）；绝对形与旧 normAbs 面逐字等价。
     docAbs: reviewType === "design" && Array.isArray(documents)
-      ? documents.filter((d) => typeof d === "string").map((d) => normAbs(d, parent.cwd))
+      ? [...resolveReviewDocPaths(documents, parent.cwd).resolved.values()]
       : [],
     relayPrefix: `advisor#${id}/`,
     status: queued ? "queued" : "running", position: undefined,
@@ -411,9 +425,12 @@ export function launchAsyncAdvisor(parent, ctx, launch) {
     // Async mark + [model] — the TUI block opens at ACTUAL start (⏹ gating reads it).
     ctx?.callbacks?.onToken?.(entry.relayPrefix + "⟦ev⟧async\x1e")
     ctx?.callbacks?.onToken?.(entry.relayPrefix + "[model]" + (entry.model ?? ""))
+    // #949 ①：排队 / 延迟窗口封死——构建前按本评审实例复核镜像（消费点定域；幂等）。
+    scopeAdvisorMirror(parent, run)
     runAdvisorReview(parent, reviewType, {
       onOutput: (chunk) => relayAdvisorOutput(ctx?.callbacks, entry.relayPrefix, chunk),
       signal: entry.controller.signal,
+      onStall: (rounds) => pushAdvisorAlert(parent, `advisor#${id}`, rounds), // #934：连续无产出越阈 ⇒ 自动上行提醒（只推——§6.32）
     }, designToken, documents, paths, object, designId)
       .then((report) => { entry.report = report })
       // §6.12 第 3 条合成器（第 24 批）：原 message 前缀逐字保留 + 来源后缀
@@ -474,7 +491,8 @@ export function closeOpenCodeAdvisorRuns(agent) {
   const runs = advisorRunsRead(agent)
   if (runs instanceof Map) {
     for (const r of runs.values()) {
-      if (r.reviewType === "code" && r.open) { r.open = false; closed = true }
+      // #863 关闭点轻量化：闭合同拍释放 priorOutput（closed 实例零消费面——续跑仅取 open）。
+      if (r.reviewType === "code" && r.open) { r.open = false; r.priorOutput = null; closed = true }
     }
   }
   return closed

package/agent-tools/advisor-settle.mjs

@@ -21,7 +21,7 @@
  * ADVISOR-GUARDS.md §7）。记账本体 / 陈旧判定 / 轮次 / token 落盘零改。
  */
 import { persistEngTokens } from "../token-ttl.mjs"
-import { settleDesignReview, makeDesignTokenRegex, stripApprovedSuffix } from "./design-token.mjs"
+import { settleDesignReview, stripDesignTokenEcho, stripApprovedSuffix } from "./design-token.mjs"
 import { looksLikeReviewOutput, advisorIncompleteMarker, ADVISOR_LAUNCH_REFUSAL_PREFIX } from "../advisor/run.mjs"
 import { isCodePath, loadProjectDeclaration } from "../conventions.mjs"
 import { logEvent } from "../log.mjs"
@@ -176,9 +176,7 @@ export function settleAdvisorRun(agent, entry) {
           run.approvedSuffix = null
           persistFailed = true
           logEvent("advisor:error", { id: `advisor#${entry.id}`, err: "engDesignTokens slot persist failed — settle failed (re-review)" })
-          const stripped = String(result)
-            .replace(makeDesignTokenRegex(entry.designToken, "g"), "")
-            .trim()
+          const stripped = stripDesignTokenEcho(String(result), entry.designToken).trim()
           report = `${stripped}\n\nD1: the design review passed but the token could NOT be durably written to the session ledger (slot persist failed) — re-run advisor(type='design') to re-issue; no eng-coder spawn is authorized for this review (评审通过但 token 未能持久化——需重评).`.trim()
         }
       } else {
@@ -210,17 +208,17 @@ export function settleAdvisorRun(agent, entry) {
     }
   } else if (run.reviewType === "design" && entry.designToken && result != null) {
     // fix B（stale 分支）：陈旧评审不签发——digest 不得展示未注册 token——先剥
-    // 方括号回显 + 前置 "评审目标已变更——token 未签发"（不变式——两分支都清洗）。
-    const stripped = String(result)
-      .replace(makeDesignTokenRegex(entry.designToken, "g"), "")
-      .trim()
+    // token 回显（单源三形）+ 前置 "评审目标已变更——token 未签发"（不变式——两分支都清洗）。
+    const stripped = stripDesignTokenEcho(String(result), entry.designToken).trim()
     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: 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)) {
+  // #863 关闭点轻量化（父侧批·五裁定——§2.3 表外追加）：closed 实例零消费面（续跑仅取 open）——
+  // 关闭后不再写回 priorOutput（否则 settleDesignReview 关闭点的释放被覆盖）。
+  if (run.open && report && looksLikeReviewOutput(report)) {
     run.priorOutput = stripApprovedSuffix(report, run.approvedSuffix)
   }
   // F28/F29 失败结论（2026-09-18 顾问面治理批——**两轨共用**，ADVISOR-GUARDS.md §7 契约二）：

package/agent-tools/advisor.mjs

@@ -9,12 +9,11 @@
  */
 import { runAdvisorReview, advisorIncompleteMarker, ADVISOR_LAUNCH_REFUSAL_PREFIX } from "../advisor/run.mjs"
 import { resolveBatchDocPath } from "./batch.mjs"
-// M6（模块设计 §2.1 F3）：评审对象来源读 manifest docRoot（声明面）——复用 M4 的
-// write-gate.mjs 单一权威源（KD-M6-1），替代 v1 的逐档分类面（isDocPath）；
-// normAbs 同源 re-export（指针非副本）。不 import dispatch.mjs（簇间回边，环风险）。
-import { resolveReviewTargetPaths, resolveReviewRootsFor, normAbs } from "../agent/write-gate.mjs"
-import { owningProject } from "../manifest-discovery.mjs"
-import { sep } from "node:path"
+// M6（模块设计 §2.1 F3）：评审对象来源读 manifest docRoot（声明面）——单一权威源 =
+// review-facts.mjs 的 resolveReviewDocPaths（2026-10-04 · #921 · KD-2——分类四腿 + B 文案
+// 诊断数据单源；write-gate 同名再出口保 normAbs 面）。不 import dispatch.mjs（簇间回边，环风险）。
+import { normAbs } from "../agent/write-gate.mjs"
+import { resolveReviewDocPaths } from "./review-facts.mjs"
 import {
   generateDesignToken,
   settleDesignReview,
@@ -63,11 +62,11 @@ export const advisorTool = {
       documents: {
         type: "array",
         items: { type: "string" },
-        description: "Doc paths to review (design / requirements / referenced docs). The advisor reviews ONLY these — no git diff scan. Use for both review types to pass the task's docs list.",
+        description: "Doc paths to review (design / requirements / referenced docs). Relative paths resolve against the session cwd first, then candidate project roots (project-root-relative e.g. <repo>/docs/…, or absolute). The advisor reviews ONLY these — no git diff scan. Use for both review types to pass the task's docs list.",
       },
       batchDoc: {
         type: "string",
-        description: "Design review only: the in-flight batch record path — validated whenever passed (unreadable ⇒ refused, not ignored); the reviewer then also gets the `batch` write channel to record its findings + verdict. Omit when no batch record is in flight (no write channel — zero regression).",
+        description: "Design review only: the in-flight batch record path — validated whenever passed (unreadable ⇒ refused, not ignored); the reviewer then also gets the `batch` write channel to record its findings + verdict. Relative paths resolve against the session cwd first, then candidate project roots (project-root-relative e.g. <repo>/docs/batches/…, or absolute). Omit when no batch record is in flight (no write channel — zero regression).",
       },
     },
     required: ["type"],
@@ -112,34 +111,36 @@ export const advisorTool = {
       )
     }
 
-    // Design review: the review scope must be documentation files. Classification
-    // comes from the manifest-declared review-target roots (M4 write-gate.mjs single
-    // authority — FR12: no directory-name hardcoding; a project whose docs live
-    // elsewhere declares them in PROJECT-MANIFEST.json docRoot).
+    // Design review: the review scope must be documentation files. Classification =
+    // resolveReviewDocPaths (2026-10-04 · #921 · the four-leg single authority in
+    // review-facts.mjs): legs ① session-root set / ② owning-project root set keep the
+    // legacy behavior verbatim; leg ③ probes candidate project roots for bare
+    // project-root-relative forms; leg ④ disambiguates by readable-file uniqueness
+    // (fail-closed — criterion=scope-doc-ambiguous when ≥2 candidates are readable).
     if (reviewType === "design" && documents) {
-      const roots = resolveReviewTargetPaths(agent).map((r) => r.replace(/[\\/]/g, sep))
-      // 按用点解析（2026-09-21 之裁收口 · 台账 #828）：逐文档按**其所属项目**（最近带档祖先）
-      // 的 docRoot 判定；无主档文档回退会话根集判定（原行为零变）。
-      const ownerRootsCache = new Map()
-      const ownRoots = (abs) => {
-        const owner = owningProject(abs)
-        if (!owner) return []
-        let r = ownerRootsCache.get(owner)
-        if (!r) {
-          r = resolveReviewRootsFor(owner).map((x) => x.replace(/[\\/]/g, sep))
-          ownerRootsCache.set(owner, r)
-        }
-        return r
-      }
-      const invalidDocs = documents.filter((doc) => {
-        const n = normAbs(doc, agent.cwd).replace(/[\\/]/g, sep)
-        const under = (r) => n === r || n.startsWith(r + sep)
-        return !roots.some(under) && !ownRoots(n).some(under)
-      })
-      if (invalidDocs.length > 0) {
+      const { resolved, invalid, ambiguous, candidates } = resolveReviewDocPaths(documents, agent.cwd)
+      if (invalid.length > 0 || ambiguous) {
         if (ctx._toolCallId !== undefined) (agent._advisorRefusals ??= new Set()).add(ctx._toolCallId)
+        if (ambiguous) {
+          // 歧义拒（KD-4 独立判据——不混入 not-doc；列全部可读命中——fail-closed 不静默挑一）。
+          return withIdentityLine(
+            `Advisor: design review document is ambiguous — "${ambiguous.doc}" matches several candidate projects: ${ambiguous.hits.join(", ")}. Pass a project-root-relative or absolute path.`,
+            { type: reviewType, scope: scopeSummary(documents), round: "—", criterion: "scope-doc-ambiguous" },
+          )
+        }
+        // not-doc 拒：既有稳定前缀逐字（行首）+ 解析诊断尾（B 面根治——逐文档「解析后绝对
+        // 路径 ← 基面 = 会话 cwd」+ 候选项目根提示 cap 5 + 重试指引——纠正「误报因」缺陷）。
+        const invalidList = invalid.map((v) => v.doc).join(", ")
+        const attemptedList = invalid
+          .map((v) => `${v.doc} → ${v.attempted.length > 0 ? v.attempted.join(" | ") : normAbs(v.doc, agent.cwd)}`)
+          .join("; ")
+        const shown = candidates.slice(0, 5)
+        const more = candidates.length - shown.length
+        const candidateNote = shown.length > 0
+          ? `(candidates: ${shown.join(", ")}${more > 0 ? ` +${more} more` : ""}) — pass project-root-relative (e.g. ${shown[0]}/docs/…) or absolute paths`
+          : "— pass project-root-relative or absolute paths"
         return withIdentityLine(
-          `Advisor: design review documents must be documentation files (per the project's conventions). Invalid: ${invalidDocs.join(", ")}`,
+          `Advisor: design review documents must be documentation files (per the project's conventions). Invalid: ${invalidList}\nDiagnosis: resolved against session cwd ${agent.cwd} → ${attemptedList}; no candidate project docRoot contains it ${candidateNote}.`,
           { type: reviewType, scope: scopeSummary(documents), round: "—", criterion: "scope-not-doc" },
         )
       }

package/agent-tools/async-settle.mjs

@@ -134,6 +134,17 @@ export function parkAsyncPending(parent, entry) {
   pend.push(entry)
 }
 
+/**
+ * §6.31.5 升级账本写助手（消化账务批）：`_unsettledDigests` 追加一行
+ * （`{ id, role, failures, report, at }`）。载体吸收（父字段优先 / history 借用——形态同
+ * `parkAsyncPending`）；行序 = 升级序（读面 = `digest-account.mjs` `unsettledRows`）。
+ */
+export function appendUnsettledDigest(parent, row) {
+  const existing = carrierField(parent, "_unsettledDigests")
+  const list = (parent._unsettledDigests ??= Array.isArray(existing) ? existing : [])
+  list.push(row)
+}
+
 // ─── D4 守卫统一（严格版）+ D6 信号兜底单点 ──────────────────────────────────
 
 /** D4 settle 守卫统一（escalate 严格版）：父侧中止 = 回合 signal aborted（#98 VSC 侧
@@ -161,7 +172,9 @@ export function buildChildSignal(parent, ctx) {
  * 对子代理对象的引用（`childAgent`/`report`——条目前此从不显式释放，挂起期 = 分钟级驻留）。
  * 幂等（重入不抛）；池内/挂起未消化窗口语义零变（settle 时刻不释放——表 2 候选 2 否决：
  * status/observe 在窗口内仍读 child 摘要）。三消费点（回合尾收集 / run 起始 pending 注入 /
- * 挂起残差注入）在注入完成后调本 helper。
+ * 挂起残差注入）——fallback 面（无 `_daSession`）注入完成后调本 helper（逐字沿用）；会话态
+ * （`_daSession`）注入后改调 `releaseChildHold`（仅释放 `childAgent`——`report` 保留至销账 /
+ * 升级；§6.31.4 ∥ KD-DA7）。
  */
 export function releaseSettledEntry(entry) {
   if (!entry || typeof entry !== "object") return
@@ -169,6 +182,16 @@ export function releaseSettledEntry(entry) {
   entry.report = null
 }
 
+/**
+ * §6.31.4 投递面（消化账务批 · 2026-10-05 · 台账 #930）：会话态注入后**仅**释放 `childAgent`——
+ * `report` 保留至销账 / 升级（重投需原文；驻留增量以报告量级 ∥ 重投上限封顶）。fallback 面零调用
+ * （既有 `releaseSettledEntry` 逐字沿用——注入即释放）。
+ */
+export function releaseChildHold(entry) {
+  if (!entry || typeof entry !== "object") return
+  entry.childAgent = null
+}
+
 /**
  * D3 settle 共享 helper——四族 settle 回调公共收尾单点（ASYNC-RESULT-CONTAINER.md
  * AC1：settle 记账单点，无逐字重复）。流程：
@@ -273,10 +296,11 @@ export function settleAsyncEntry(parent, entry, opts = {}) {
       parkAsyncPending(parent, entry)
       pool?.delete(String(entry.id))
     }
-    // 发射单点（块到达时点归位批 · #746｜§6.8「settle 延迟冻结（两态统一）」）：settle 一律 ⟦ev⟧settled
-    // （区块头恒中间态「done · awaiting digestion」驻留面板）；⟦ev⟧done = 消费面补发（消费窗清单单源
-    // = §6.8）⇒ 冻结 ∥ 归档恒落消费时点——回合运行中零归档触发器（「S 不夹运行中回合」结构不变式）。
-    ctx?.callbacks?.onToken?.(`${entry.relayPrefix}⟦ev⟧settled\x1e0\x1e0\x1esettled\x1e`)
+  // 发射单点（块到达时点归位批 · #746｜§6.8「settle 延迟冻结（两态统一）」）：settle 一律 ⟦ev⟧settled
+  // （区块头恒中间态「done · awaiting digestion」驻留面板）；⟦ev⟧done = 消费面补发（消费窗清单单源
+  // = §6.8）⇒ 冻结 ∥ 归档恒落投递时点（消化账务批 · 2026-10-05——归档 ≠ 销账；销账后移见账 = §6.31）；
+  // 回合运行中零归档触发器（「S 不夹运行中回合」结构不变式）。
+  ctx?.callbacks?.onToken?.(`${entry.relayPrefix}⟦ev⟧settled\x1e0\x1e0\x1esettled\x1e`)
   }
   // ④ 公共尾部：settleSeq 递增 + _settle 唤醒（never rejects）+ 唤醒挂起驱动 waiter
   entry._settleSeq = (parent._asyncSettleSeq = (parent._asyncSettleSeq ?? 0) + 1)

package/agent-tools/batch-lifecycle.mjs

@@ -49,6 +49,18 @@ function segmentNumber(raw) {
   return m ? Number(m[1]) : null
 }
 
+/** 档头两可选参归一（`BATCH-RECORD.md` §4.11 契约——逐字文本面 = `TOOLS.md` §6.20）：trim ∥
+ *  单行（拒句逐字）∥ 空串 ≡ 未给（null）；`ledger` 前导 `#` 补齐（board 无补齐）。给参 ⇒ 建即填
+ *  台账行（batchSkeleton 实参面）；未给（任一）⇒ 占位留存 + 回执填法句。 */
+function normalizeHeaderParam(name, raw) {
+  const v = typeof raw === "string" ? raw.trim() : ""
+  if (!v) return null
+  if (/\r?\n/.test(v)) {
+    throw new Error("batch: create ledger / board must be single lines — a multi-line value would break the header's 台账 line. Nothing was written.")
+  }
+  return name === "ledger" && !v.startsWith("#") ? `#${v}` : v
+}
+
 /** main-agent-only 门（BR-19/BR-24）：create/close 仅 depth-0 放行（eng 子代理 / 评审皆拒）。 */
 function assertMainAgentOnly(ctx, action, review) {
   if (review || !isDepthZero(ctx)) {
@@ -58,8 +70,9 @@ function assertMainAgentOnly(ctx, action, review) {
 
 /** 递归收集目录下全部 `*.md`（#369 · KD-4：显式嵌套路径为合法 create 面 ⇒ 顶层平扫会欠计
  *  ⇒ 复数情形漏判、默认定位可落非预期档）。只认真目录（`dirent.isDirectory()`——symlink 不入，
- *  防环）；单目录读错按无候选处理（尽力面，同旧平扫）。 */
-function collectMarkdownFiles(dir, out = []) {
+ *  防环）；单目录读错按无候选处理（尽力面，同旧平扫）。**转导出**（read-data-interface 批——
+ *  `batch/list` 读面文件集同源复用；零行为变）。 */
+export function collectMarkdownFiles(dir, out = []) {
   let entries = []
   try { entries = readdirSync(dir, { withFileTypes: true }) } catch { return out }
   for (const e of entries) {
@@ -107,6 +120,8 @@ export function findInFlightBatch(cwd, bases) {
  * 路径解析 = `resolveBatchCreatePath`（§4.15 单源：候选序首个落基底内者 / 锚定串只解析项目根形）。
  * F11-B：`source` **必填**（topic 同款空拒——骨架编制行实参化；不传 = 死占位残留必被 F11-C 拒
  * ⇒ create 即拒，不留死锁）；`prev` 传入值**幂等剥**「前情 = 」前缀（值规范化；默认值零变）。
+ * 2026-10-05（A-2）：`ledger` / `board` 可选参**建即填**台账行（归一契约 = §4.11；回执两态 =
+ * 两参皆给 ⇒ 标注已填 ∥ 未给（任一）⇒ 填法句）。
  * @returns {string} 成功消息（含落盘绝对路径）
  */
 export function createBatchRecord({ args, ctx, review, cwd, bases, onWritten }) {
@@ -137,15 +152,22 @@ export function createBatchRecord({ args, ctx, review, cwd, bases, onWritten })
   if (/\r?\n/.test(source)) {
     throw new Error("batch: create source must be a single line — a multi-line source would break the header's 编制 line. Nothing was written.")
   }
+  // 档头两可选参（§4.11 契约——给则建即填台账行；未给任一 ⇒ 占位留存 + 回执填法句）
+  const ledger = normalizeHeaderParam("ledger", args?.ledger)
+  const board = normalizeHeaderParam("board", args?.board)
   const date = typeof args?.date === "string" && args.date.trim() ? args.date.trim() : todayLocal()
   // F11-B：prev 幂等 strip——调用方自带「前情 = 」前缀（单或重复）一并剥净（`+` 量词；归一化目的
   // = 值规范化，无前缀值原样通过）。默认值形态「无（独立批）」零变。
   const prevRaw = typeof args?.prev === "string" ? args.prev.trim() : ""
   const prev = prevRaw ? (prevRaw.replace(/^(?:前情\s*[=：:]\s*)+/g, "").trim() || "无（独立批）") : "无（独立批）"
   mkdirSync(dirname(abs), { recursive: true })
-  writeFileSync(abs, batchSkeleton({ date, topic, source, prev }))
+  writeFileSync(abs, batchSkeleton({ date, topic, source, prev, ledger, board }))
   onWritten?.(ctx?.agent ?? {}, abs)
-  return `batch: created ${abs} — six-section skeleton written (§1 status line carries the gate-legal 「进行中」 placeholder; register the ledger entry yourself — create does not).`
+  // 回执两态（`TOOLS.md` §6.20 逐字）：两参皆给 ⇒ 标注已填；未给（任一）⇒ 填法句（填法 = 文件编辑）
+  const headerNote = ledger !== null && board !== null
+    ? `header 台账 line filled (${ledger} · ${board})`
+    : "header 台账 placeholder(s) remain — fill them by file edit before the record's first append/status opens"
+  return `batch: created ${abs} — six-section skeleton written (§1 status line carries the gate-legal 「进行中」 placeholder; register the ledger entry yourself — create does not). ${headerNote}`
 }
 
 /**
@@ -264,7 +286,7 @@ function assertStatusNote(note) {
  * 恰一词（**余核 = 关键词**——F11-A 谓词收紧），散文说明走独立 `note` 字段（落状态行括注）；
  * 冻结真值不变（gate 只读 §1）。path 参数 = 仅 depth-0（D-BR21）——子代理/评审传 path
  * ⇒ 拒（目标 = spawn/实例注入，语法上写不到别处）。F11-C 挂点 = 写盘前（assertStatusValue 后）：
- * 档头 / 目标段含骨架死占位 ⇒ 拒（close 不拦——收口是主 agent 终态动作）。
+ * 档头结构行含骨架死占位 ⇒ 拒（段体引用豁免；close 不拦——收口是主 agent 终态动作）。
  * @returns {string} 成功消息
  */
 export function statusBatchRecord({ args, ctx, review, pickTarget, onWritten }) {
@@ -297,8 +319,8 @@ export function statusBatchRecord({ args, ctx, review, pickTarget, onWritten })
   const abs = pickTarget(args?.path)
   const src = readFileSync(abs, "utf8")
   assertGateOpen(src)
-  // F11-C（写盘前）：档头 + 本段死占位残留 ⇒ 拒（他段占位不归本段作者管）
-  const residues = findPlaceholderResidue(src, seg)
+  // F11-C（写盘前）：档头结构行死占位残留 ⇒ 拒（段体引用豁免——判据可辨性收正，`TOOLS.md` §6.20）
+  const residues = findPlaceholderResidue(src)
   if (residues.length) throw new Error(placeholderResidueError(residues))
   const written = updateSectionStatusLine(src, seg, lineValue)
   writeFileSync(abs, written)

package/agent-tools/batch-paths.mjs

@@ -10,6 +10,7 @@
  * **歧义锚**（条 5 · 2026-10-02 · #828）= create 按目标所属项目落基底 ∥ 无所属显式拒；读面候选腿追加；
  * 在飞 ∥ 写门基底集 = 候选并集（`batchDocBases`）；**零变面** = 绝对路径照旧、三个错误文案逐字、
  * 「参数在 + 路径可读」判据句、`ok` / `none` 两态。
+ * **基底自有项目根腿 + 基底相对单段收窄**（条 6 · 2026-10-05 · #942）= 逐基底 `owningProject` 恰一落点收 ∥ 多落点显式拒（`ambiguousLandingError`）；基底相对腿限单段（多段串不二次拼接）。
  *
  * 依赖（KD-4 单向）：本档为**叶档**——只 import `node:*` 与 `../manifest.mjs`；主档 re-export 保既有面。
  */
@@ -98,6 +99,7 @@ const outsideBasesError = (raw) => new Error(`batch: create path resolves outsid
 const anchoredEscapeError = (raw) => new Error(`batch: create path is anchored at a batch base root but does not resolve under the declared docRoot.batches root(s) — refusing to nest it (fail-closed). Path: ${raw}`)
 /** 歧义锚 create 拒面（**文案逐字** = `BATCH-RECORD.md` §4.15 条 5——机检锚 `ambiguous session anchor`）。 */
 const ambiguousCreateError = (raw, candidates) => new Error(`batch: ambiguous session anchor — create target "${raw}" belongs to no candidate project; pass an explicit project path (e.g. "${candidates[0]}/docs/batches/<file>.md"). Candidates: ${candidates.join(", ")}`)
+const ambiguousLandingError = (raw, landings) => new Error(`batch: create path resolves under more than one declared batch-record base — refusing to pick one (fail-closed); pass an explicit path (absolute preferred). Path: ${raw}. Candidates: ${landings.join(", ")}`)
 
 /** 歧义锚读面候选腿（条 5）：逐候选项目——项目根形（`resolve(candidate, p)`）∥ 声明基底形
  *  （候选按名排序、并集保序——「首个可读」在此即为确定判读）。 */
@@ -149,7 +151,7 @@ export function resolveBatchDocPath(cwd, given) {
 }
 
 /**
- * **create 面**解析（§4.15 条 2/3）：绝对路径照旧取用（仍过越基底判据）；相对路径 = 候选序中首个**落基底
+ * **create 面**解析（§4.15 条 2/3/6）：绝对路径照旧取用（仍过越基底判据）；相对路径 = 候选序中首个**落基底
  * 根内**者（新档不存在——可读性无判别力）；锚定串只解析项目根形，不落基底内 ⇒ fail-closed 新文案。
  *  **歧义锚**（条 5）：目标所属项目（`owningProject`）∈ 锚候选集 ⇒ 基底 = 该项目声明面（落其基底内；
  *  越出 ⇒ 既有 fail-closed）；无所属 ⇒ **显式拒**（列候选 + 显式路径指引——不静默落锚）。
@@ -179,8 +181,26 @@ export function resolveBatchCreatePath(cwd, given, bases) {
     if (!insideBases(abs, roots)) throw anchoredEscapeError(raw)
     return abs
   }
-  for (const abs of [resolve(base, p), resolve(batchProjectRoot(base), p), ...roots.map((b) => resolve(b, p))]) {
+  for (const abs of [resolve(base, p), resolve(batchProjectRoot(base), p)]) {
     if (insideBases(abs, roots)) return abs
   }
+  // ③ 基底自有项目根形（#942 条 6）：owningProject 可判者逐基底取值；distinct 落点 ≥2 ⇒ 拒
+  const owned = []
+  for (const b of roots) {
+    const ownRoot = owningProject(b)
+    if (!ownRoot) continue
+    const abs = resolve(ownRoot, p)
+    if (insideBases(abs, roots) && !owned.some((x) => samePath(x, abs))) owned.push(abs)
+  }
+  if (owned.length > 1) throw ambiguousLandingError(raw, owned)
+  if (owned.length === 1) return owned[0]
+  // ④ 基底相对形收窄单段（归一后无 `/` 才走原基底腿——多段串不二次拼接）
+  const leafRel = roots.length ? relative(roots[0], resolve(roots[0], p)) : ""
+  if (leafRel && !leafRel.startsWith("..") && !leafRel.includes(sep)) {
+    for (const b of roots) {
+      const abs = resolve(b, p)
+      if (insideBases(abs, roots)) return abs
+    }
+  }
   throw outsideBasesError(raw)
 }

package/agent-tools/batch-read.mjs

@@ -0,0 +1,36 @@
+/**
+ * agent-tools/batch-read.mjs — 批次档只读读面（read-data-interface 批 · 设计档
+ * `docs/cli/design/READ-DATA-INTERFACE.md` §2.5 / §3.3 · 台账 #887）。
+ *
+ * `listBatchRecords({ cwd, bases })` —— ACP `batch/list` 与变更观察器共用的**文件集 + 段状态单源**：
+ * 文件集 = 基底根（`batchDocBases`——声明面单源）下全部 `*.md`（递归；收集器 `collectMarkdownFiles`
+ * 转导出复用）；路径升序稳定；单档读错跳过（尽力面）。各段状态 = `readSectionStatusWord`（段头 /
+ * 状态行正则 / 词表全消费 batch-skeleton 单源——与冻结门字面零漂移；`§4` / `§6` = 字面「无状态词」）。
+ */
+import { readFileSync } from "node:fs"
+import { basename } from "node:path"
+
+import { collectMarkdownFiles } from "./batch-lifecycle.mjs"
+import { batchDocBases } from "./batch-paths.mjs"
+import { readSectionStatusWord } from "./batch-skeleton.mjs"
+
+/** 段号表（1–6——输出映射键序固定；`readSectionStatusWord` 消费数形段号）。 */
+const SEGMENTS = [1, 2, 3, 4, 5, 6]
+
+/** 批次档列举（只读）：`{ batches: [{ file, path, sections }] }`——`path` = 绝对路径（`/` 归一）、
+ *  `file` = basename、`batches` 按路径升序；单档读错跳过（尽力面）。`bases` 缺省 = `batchDocBases(cwd)`。 */
+export function listBatchRecords({ cwd, bases } = {}) {
+  const base = cwd ?? process.cwd()
+  const roots = bases ?? batchDocBases(base)
+  const files = new Set()
+  for (const root of roots) for (const abs of collectMarkdownFiles(root)) files.add(abs.replace(/\\/g, "/"))
+  const batches = []
+  for (const p of [...files].sort()) {
+    let src
+    try { src = readFileSync(p, "utf8") } catch { continue } // 单档读错跳过（尽力面）
+    const sections = {}
+    for (const seg of SEGMENTS) sections[`§${seg}`] = readSectionStatusWord(src, seg)
+    batches.push({ file: basename(p), path: p, sections })
+  }
+  return { batches }
+}