thincoder 0.12.60 → 0.12.61

package/src/agent-tools/advisor.mjs

@@ -2,12 +2,13 @@
  * agent-tools/advisor.mjs — advisor tool wrapper.
  * The agent calls this explicitly to get an independent review.
  * type="design" for design doc review, type="code" for code review (default).
- * §24 D-24b (R13 — async advisor): at depth 0 the review launches into the
+ * §11.2 (R13 — async advisor): at depth 0 the review launches into the
  * background pool by DEFAULT (async:true / omitted; async:false forces the
  * blocking review); depth>0 (eng-coder self-review) stays synchronous always.
  */
-import { runAdvisorReview, MAX_ADVISOR_ROUNDS, buildCapMessage } from "../advisor/run.mjs"
-import { isDocFile } from "../advisor/repos.mjs"
+import { runAdvisorReview, MAX_ADVISOR_ROUNDS, buildCapMessage, advisorIncompleteMarker, ADVISOR_LAUNCH_REFUSAL_PREFIX, buildDesignReviewGuardMessage } from "../advisor/run.mjs"
+import { resolveBatchDocPath } from "./batch-segment.mjs"
+import { isDocPath, loadConventions } from "../conventions.mjs"
 import {
   generateDesignToken,
   settleDesignReview,
@@ -15,6 +16,10 @@ import {
   launchAsyncAdvisor,
   stripApprovedSuffix,
 } from "./advisor-async.mjs"
+// 第 33 批（§17.5）：护栏消费面——工具层预检（检查点 1）+ 同步面计数（计数点 2）。
+import {
+  designReviewOutcome, designReviewStreakRecord, designReviewStreakStopped, noteDesignReviewOutcome,
+} from "./review-streak.mjs"
 
 // Design-token utilities moved to advisor-async.mjs (the async settle shares
 // them — no wrapper↔runner module cycle); validateDesignToken stays exported
@@ -38,11 +43,12 @@ export const advisorTool = {
     "Optionally pass object={type,target,status,reason,exclude} to anchor the review target " +
     "(AGENT-LOOP.md §18.8 — the review-object declaration is mechanically injected into the review message); " +
     "absent → legacy behavior (no injection). " +
-    "ASYNC (AGENT-LOOP.md §24 D-24b): at depth 0 the review runs in the BACKGROUND by default " +
+    "ASYNC (AGENT-LOOP.md §11.2): at depth 0 the review runs in the BACKGROUND by default " +
     "(async:true or omitted) — the call returns an ack immediately, the turn ends, and the report " +
-    "arrives automatically in a digest turn when the review finishes; at most 2 reviews run in " +
-    "parallel (excess launches are refused — launch one at a time). Pass async:false to force the " +
-    "blocking review (result returned inline). Inside a child (depth>0 — eng-coder self-review) " +
+    "arrives automatically in a digest turn when the review finishes; background reviews share one pool — " +
+    "at most agent.poolLimits.advisor concurrent reviews (default 4 — configurable via /config 并发池 or " +
+    "config.json; pool-full and same-scope refusals state the current limit) — launch reviews one at a time. " +
+    "Inside a child (depth>0 — eng-coder self-review) " +
     "reviews are always synchronous; async:true is rejected there. " +
     "Returns the review report — the advisor's findings verdict: all-clear (call verify) or a findings list to fix.",
   parameters: {
@@ -51,7 +57,7 @@ export const advisorTool = {
       type: { type: "string", enum: ["code", "design"], description: "Review type: 'design' for design doc review, 'code' for code review (default)" },
       async: {
         type: "boolean",
-        description: "Background review: default at depth 0 = true (async — ack now, report via digest); async:false forces the blocking review. depth>0 → always sync (async:true rejected).",
+        description: "Background review: default at depth 0 = true (async — ack now, report via digest); async:false forces the blocking review (mechanism parameter — top-level launches are async by default). depth>0 → always sync (async:true rejected).",
       },
       object: {
         type: "object",
@@ -74,6 +80,10 @@ export const advisorTool = {
         items: { type: "string" },
         description: "Explicit list of doc paths to review (design docs, requirements docs, referenced docs). The advisor reviews ONLY these — it does NOT scan git diff. Use for both design review and code review to pass the task's Docs involved list.",
       },
+      batchDoc: {
+        type: "string",
+        description: "Design review only: path to the batch record currently in flight. Validated WHENEVER passed (any review type) — a value that is not a readable file is refused with an error rather than ignored; for design reviews the reviewer then ALSO gets the batch_segment write channel to record its findings table + VERDICT + counts into §3 (ENGINEERING-MODE.md §2.20). Omit when no batch record is in flight — the review then runs unchanged with no write channel (zero regression).",
+      },
     },
   },
   readonly: true,
@@ -100,20 +110,20 @@ export const advisorTool = {
       return "Advisor: no review scope specified. Provide paths (files/directories to review) or documents (acceptance criteria context)."
     }
 
-    // Design review: validate that documents are in docs/ or are recognized doc files
+    // Design review: the review scope must be documentation files. Classification
+    // comes from the single authority (src/conventions.mjs) — the old `docs/`
+    // prefix test is retired with it (FR12: no directory-name hardcoding in the
+    // gate; a project whose docs live elsewhere just declares its code paths).
     if (reviewType === "design" && documents) {
-      const invalidDocs = documents.filter((doc) => {
-        // Allow docs/ directory and recognized doc files (METHODOLOGY.md, README.md, etc.)
-        if (doc.startsWith("docs/") || doc.startsWith("docs\\")) return false
-        return !isDocFile(doc)
-      })
+      const conv = loadConventions(agent.cwd)
+      const invalidDocs = documents.filter((doc) => !isDocPath(doc, conv))
       if (invalidDocs.length > 0) {
         if (ctx._toolCallId !== undefined) (agent._advisorRefusals ??= new Set()).add(ctx._toolCallId)
-        return `Advisor: design review documents must be in docs/ directory or be recognized doc files. Invalid: ${invalidDocs.join(", ")}`
+        return `Advisor: design review documents must be documentation files (per the project's conventions). Invalid: ${invalidDocs.join(", ")}`
       }
     }
 
-    // §24 D-24b (R13 — ruling ②-3 A): async gate. Depth-0 defaults to the
+    // §11.2 (R13 — ruling ②-3 A): async gate. Depth-0 defaults to the
     // background pool; depth>0 (eng-coder internal self-review) is ALWAYS sync —
     // an explicit async:true there is rejected, the default never flips.
     const depth = ctx?.depth
@@ -121,18 +131,25 @@ export const advisorTool = {
       // 拒发登记（与 cap/池满拒同款）：评审未跑——不置 called/不耗轮次（record-results
       // 的 REFUSED 契约——advisor 评审发现 #1：拒发不得静默满足 guard）。
       if (ctx._toolCallId !== undefined) (agent._advisorRefusals ??= new Set()).add(ctx._toolCallId)
-      return "Advisor: async reviews are only available at depth 0 — the top-level session owns the background pool (AGENT-LOOP.md §24 D-24b); inside a child (eng-coder self-review) reviews run synchronously. Call advisor again without async:true (or with async:false)."
+      return "Advisor: async reviews are only available at depth 0 — the top-level session owns the background pool (AGENT-LOOP.md §11.2); inside a child (eng-coder self-review) reviews run synchronously. Call advisor again without async:true (or with async:false)."
     }
     const isAsync = args.async === true || (depth === 0 && args.async !== false)
     // (ctx.depth undefined = direct callers/tests without a dispatch context —
     // legacy sync semantics.)
 
-    // Per-review instance resolution (§24 D-24b ③ — ruling ②-5 A): fix rounds
+    // Per-review instance resolution (§11.2 ③ — ruling ②-5 A): fix rounds
     // continue the same reviewId (design = the doc-set instance's designId —
     // slot/spawn continuity; code = the newest OPEN instance). The resolution
     // scopes agent._advisorRound/_lastAdvisorOutput so the message builder and
     // the run.mjs cap read THIS instance's round/prior (multi-review isolation).
     const resolved = resolveAdvisorLaunch(agent, reviewType, { documents })
+    // §2.20.2 评审侧批次档门禁 + 实例键绑定（batch_segment 的唯一路径来源）：
+    // 口径 = **「若传则须可读」**（空/不可读 → throw；不强制必传——无批次档的在途设计评审
+    // 零回归，N5）；绑定落在 resolved.run（评审实例键，与 reviewType/round/designId 同族）——
+    // 并发设计评审各绑各档，不用单值会话态（§2.20.8 #6）。
+    if (args.batchDoc !== undefined && args.batchDoc !== null) {
+      resolved.run.batchDoc = resolveBatchDocPath(agent.cwd, args.batchDoc)
+    }
     // Design token minted for EVERY design round — the reviewer echoes it only on
     // a clean pass; on pass it is slotted under the instance's designId at settle
     // (sync: right here; async: the settle callback — fix #2). A NEW instance
@@ -154,6 +171,14 @@ export const advisorTool = {
       return buildCapMessage(agent)
     }
 
+    // 第 33 批（§17.5 检查点 1——工具层预检；cap 预检邻位 / sync / async 分叉前）：同一 doc-set
+    // 连续 `MAX_DESIGN_REVIEW_STREAK` 次未产出可用结算 ⇒ 拒发（登记 `_advisorRefusals` 同 cap /
+    // 池满款——不置 called / 不耗轮次 / **零 LLM**），返回结论串。
+    if (reviewType === "design" && designReviewStreakStopped(agent, resolved.run.docSetKey)) {
+      if (ctx._toolCallId !== undefined) (agent._advisorRefusals ??= new Set()).add(ctx._toolCallId)
+      return buildDesignReviewGuardMessage(designReviewStreakRecord(agent, resolved.run.docSetKey), documents ?? [])
+    }
+
     if (isAsync) {
       const ack = launchAsyncAdvisor(agent, ctx, {
         reviewType, documents, paths, object: reviewObject,
@@ -170,10 +195,15 @@ export const advisorTool = {
       if (ctx._toolCallId !== undefined) {
         (agent._advisorAsyncAcks ??= new Set()).add(ctx._toolCallId)
       }
+      // E（F17/§14.14 E-3c）：设计评审点火回执追加冻结句（代码评审 ack 零改）——窗口下界以
+      // 可观察信号表达：报告送达 / 取消前，被审文档（含批次档）零写入。
+      const freezeNote = reviewType === "design"
+        ? "；D5 冻结窗口：被审文档（含批次档）在报告送达前零写入——在途写入会被拒绝，写入将使本轮结算为陈旧 (pass 不发 token)"
+        : ""
       return JSON.stringify({
         id: ack.id, kind: "advisor", status: "running",
         reviewId: resolved.reviewId,
-        note: "评审已后台启动——完成自动回来 (review started in the background — the report arrives in a digest turn automatically; pass this id to cancel if needed)",
+        note: "评审已后台启动——完成自动回来 (review started in the background — the report arrives in a digest turn automatically; pass this id to cancel if needed)" + freezeNote,
       })
     }
 
@@ -187,8 +217,18 @@ export const advisorTool = {
     const result = await runAdvisorReview(agent, reviewType, {
       onOutput: ctx.onOutput,
       signal: ctx.signal,
+      // 同步路径的实例绑定传递（异步路径由池条目 run.batchDoc 取——run.mjs 自行解析）。
+      batchDoc: resolved.run.batchDoc ?? null,
     }, designToken, documents, paths, reviewObject, designId)
 
+    // B 启动拒绝（§14.4 #2——稳定前缀）：拒发登记（同池满 / cap 款——不置 called、不耗轮次），
+    // 可见报错照常返回（record-results 的 REFUSED 契约）。第 33 批：判定单点——同时供设计
+    // 失败分类复用（launchRefused ⇒ neutral——无尝试发生，§17.3 #1）。
+    const launchRefused = String(result).startsWith(ADVISOR_LAUNCH_REFUSAL_PREFIX)
+    if (launchRefused && ctx._toolCallId !== undefined) {
+      (agent._advisorRefusals ??= new Set()).add(ctx._toolCallId)
+    }
+
     if (reviewType === "design") {
       // Design pass/fail settlement — token echo IS the verdict (prompt-enforced);
       // no findings-table heuristics: a design with issues never carries the token.
@@ -198,11 +238,20 @@ export const advisorTool = {
       // retired — no mirror write here; the dispatch/spawn gates read the authoritative
       // multi-slot Map (+ slot-file re-read). Slotting moved into settleDesignReview
       // (shared with the async settle — fix #2).
-      const settled = settleDesignReview(agent, resolved.run, designToken, result)
+      const incomplete = advisorIncompleteMarker(result)
+      const settled = settleDesignReview(agent, resolved.run, designToken, result, { incomplete })
+      // 第 33 批（§17.5 计数点 2——同步面）：同分类单源落账（同步面无 stale / 无落盘步骤
+      // ⇒ persistFailed 恒 false）。
+      noteDesignReviewOutcome(agent, resolved.run.docSetKey, designReviewOutcome({
+        launchRefused, stale: false, hasResult: result != null, incomplete, persistFailed: false,
+      }))
       // F2e (§29.1): the sync prior mirror must not carry the raw echo the runner
       // stored — overwrite with the clean settled form (exact-suffix truncation).
       if (settled.passed) {
         agent._lastAdvisorOutput = stripApprovedSuffix(settled.output, resolved.run.approvedSuffix)
+      } else if (incomplete) {
+        // 未完成 ⇒ 同步 prior 镜像覆写为清洗后输出（防未注册 token 进 prior——§14.3）。
+        agent._lastAdvisorOutput = settled.output
       }
       return settled.output
     }

package/src/agent-tools/batch-segment.mjs

@@ -0,0 +1,195 @@
+/**
+ * agent-tools/batch-segment.mjs — 批次档段写入工具（ENGINEERING-MODE.md §2.20 · FR22 F1-F7）。
+ *
+ * 规则、守卫与 fail-closed 清单的**权威正文在 §2.20.1**（本文件不重述——D2 单一权威源）；
+ * 实现要点（正文未定死、由代码承载）：
+ *  - 身份判据 = 评审实例绑定（`review` 形态）/ `agent._role`；
+ *  - append-only：在段尾（下一条 `## §N` 或 EOF）插入，既有行字节不变；
+ *  - 来源戳 `### 轮次 N（评审子代理）`（仅 §3）——N = §3 内该形态行计数 + 1，**调用方自带**
+ *    的同名标题行被丢弃（否则伪造戳会污染 N 计数——§2.20.8 #5）；
+ *  - 凭证剥除：含凭证形态的行剥掉该子串，剥后为空则整行丢弃（「零命中」+「其余逐字保留」）；
+ *  - 路径门禁：`resolveBatchDocPath`（评审侧「若传则须可读」）；工具内再查一次可读性。
+ *
+ * 导出面：`batchSegmentTool` · `resolveBatchDocPath` · `batchDocForReview`（异步评审实例键取绑定）。
+ */
+import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs"
+import { resolve } from "node:path"
+
+/** text 单次上限（§2.20.1——超出引导分段追加，不承诺"不新盖戳"）。 */
+export const MAX_TEXT_CHARS = 20000
+/** 身份 → 可写段号（§2.20.1 段白名单）。 */
+export const SEGMENT_BY_ROLE = { "eng-designer": 2, "eng-coder": 5 }
+/** 工具写入的轮次节标题形态（N 计数口径 = 该形态行；`### 轮次与发现（…）` 骨架行不匹配）。 */
+const ROUND_HEADING_RE = /^### 轮次 \d+（评审子代理）/
+/** 段标题定位（`## §N` 独立标题——`## §20` 不误命中 §2）。 */
+const sectionHeaderRe = (seg) => new RegExp(`^## §${seg}(?=\\s|$)`, "m")
+/** 凭证形态（§2.7 冒号态）：`[DESIGN-TOKEN:…]` 与 `designId: …`——本节自有正则。 */
+const CRED_RE = /\[DESIGN-TOKEN:[^\]]*\]|designId\s*:\s*\S+/g
+const CRED_TEST_RE = /\[DESIGN-TOKEN:[^\]]*\]|designId\s*:\s*\S+/
+
+/** 可读文件判据（存在且为文件——目录/缺失同判不可读）。 */
+function readableFile(abs) {
+  try { return existsSync(abs) && statSync(abs).isFile() } catch { return false }
+}
+
+/**
+ * 批次档路径门禁（评审侧 §2.20.2 口径 = **「若传则须可读」**）：空/非字符串/不可读 → throw。
+ * 非空且可读 → 返回绝对路径（`\` 归一——照 `files`/`batchDoc` spawn 门先例）。
+ */
+export function resolveBatchDocPath(cwd, given) {
+  const raw = typeof given === "string" ? given.trim() : ""
+  if (!raw) {
+    throw new Error("batchDoc must be a non-empty path to the batch record (ENGINEERING-MODE.md §2.20.2) — pass the batch record currently in flight, or omit the parameter entirely when no batch record is in flight.")
+  }
+  const abs = resolve(cwd ?? process.cwd(), raw.replace(/\\/g, "/"))
+  if (!readableFile(abs)) {
+    throw new Error(`batchDoc is not a readable file: ${raw} — pass the path of the batch record currently in flight (a path that resolves to an existing file), or omit the parameter when no batch record is in flight.`)
+  }
+  return abs
+}
+
+/**
+ * 设计评审的实例绑定解析（§2.20.2/§2.20.3——batch_segment 的唯一路径来源）：
+ *  - 同步路径：调用方（advisor 工具）把实例绑定显式放进 callbacks（**带 batchDoc 键**，
+ *    未绑定即 null）——以此为准，不再回看池条目（防同步/异步混跑时串档）；
+ *  - 异步路径：本评审所在**池条目**的 `run.batchDoc`（文档集 = 实例键，各评审各取各条）。
+ */
+export function batchDocForReview(agent, documents, callbacks = null) {
+  if (callbacks && "batchDoc" in callbacks) return callbacks.batchDoc ?? null
+  const key = JSON.stringify([...(documents ?? [])].sort())
+  for (const e of agent?._asyncAdvisors?.values?.() ?? []) {
+    if (e.status === "running" && e.reviewType === "design" && JSON.stringify([...(e.documents ?? [])].sort()) === key) {
+      return e.run?.batchDoc ?? null
+    }
+  }
+  return null
+}
+
+/** 段号解析：`§2` / `2` / `§2 批次任务` 均可；无法解析 → null。 */
+function segmentNumber(raw) {
+  const m = /^§?\s*(\d+)/.exec(String(raw ?? "").trim())
+  return m ? Number(m[1]) : null
+}
+
+/** 身份 → 可写段号；无写权身份 → null。评审实例绑定优先（评审者的身份即"设计评审"。） */
+function allowedSegment(agent, review) {
+  if (review) return 3
+  return SEGMENT_BY_ROLE[agent?._role] ?? null
+}
+
+/**
+ * 凭证剥除 + 伪造轮次标题丢弃（§2.20.1 F6/AC30/AC34）。
+ * 逐行处理：含凭证形态的行 → 剥除该子串，剥后为空则整行丢弃（其余内容逐字保留）。
+ * `dropStamp`（仅 §3 目标段）：调用方自带的 `### 轮次 N（评审子代理）` 行被丢弃——
+ * 工具生成才是唯一来源戳（否则伪造戳会污染 N 计数）。
+ */
+function sanitizeText(text, dropStamp) {
+  const kept = []
+  for (const line of text.replace(/\r\n?/g, "\n").split("\n")) {
+    if (dropStamp && ROUND_HEADING_RE.test(line)) continue
+    if (!CRED_TEST_RE.test(line)) { kept.push(line); continue }
+    const cleaned = line.replace(CRED_RE, "").replace(/[ \t]+$/, "")
+    if (cleaned.trim()) kept.push(cleaned)
+  }
+  return kept.join("\n")
+}
+
+/** §3 内工具写入的轮次行计数（N = 计数 + 1；收窄口径——只数工具戳形态）。 */
+function roundCount(src, headerMatch, endIdx) {
+  const body = src.slice(headerMatch.index + headerMatch[0].length, endIdx)
+  return body.split("\n").filter((l) => ROUND_HEADING_RE.test(l)).length
+}
+
+/** 段尾定位 + 插入（append-only：只在段尾插入，既有字节不变；返回新全文 + 本轮 N）。 */
+function insertIntoSection(src, seg, text) {
+  const hdr = sectionHeaderRe(seg).exec(src)
+  if (!hdr) {
+    throw new Error(`batch_segment: the bound batch record has no "## §${seg}" section header — the six-section skeleton is written by the record's creator before any segment write (§1.12). Fix: ask the parent/creator to add the "## §${seg} …" heading (with the template's sub-headings) first, then call batch_segment again. Nothing was written.`)
+  }
+  const nextRe = /^## §\d/gm
+  nextRe.lastIndex = hdr.index + hdr[0].length
+  const next = nextRe.exec(src)
+  const endIdx = next ? next.index : src.length
+  // 来源戳（仅 §3）：工具生成标题 + N——调用方写不进自己的标题（sanitize 已丢弃同名行）。
+  const roundN = seg === 3 ? roundCount(src, hdr, endIdx) + 1 : 0
+  const payload = (seg === 3 ? `### 轮次 ${roundN}（评审子代理）\n\n` : "") + text
+  const before = src.slice(0, endIdx)
+  const after = src.slice(endIdx)
+  const eol = src.includes("\r\n") ? "\r\n" : "\n"
+  const lead = before === "" ? "" : before.endsWith(eol + eol) ? "" : before.endsWith(eol) ? eol : eol + eol
+  // 尾随 eol 恒加（块自成行）；后面还有段标题时再补一个空行（保持模板的空行分隔）。
+  const written = before + lead + payload.replaceAll("\n", eol) + eol + (after === "" ? "" : eol) + after
+  return { written, roundN }
+}
+
+/**
+ * 批次档段写入工具工厂。
+ * @param {string|null} batchDoc — 绑定的目标档（spawn：`child._batchDoc`；评审：实例键）
+ * @param {{review?: boolean}} [opts] — review=true 表示"设计评审实例"形态（写 §3 + 工具盖戳）
+ */
+export function batchSegmentTool(batchDoc = null, { review = false } = {}) {
+  const own = review ? "§3" : null
+  return {
+    name: "batch_segment",
+    description:
+      "Append your own section of the batch record (ENGINEERING-MODE.md §2.20 — 一段一作者). " +
+      "There is NO path parameter: the target record is bound to you (at spawn for eng-designer/eng-coder, per review instance for a design review) and your identity fixes the section you may write " +
+      "(eng-designer → §2, design review → §3, eng-coder → §5) — a write outside your own section is refused. " +
+      "Append-only: the text lands at the end of your section; existing lines are never rewritten or deleted. " +
+      "Credential values are stripped mechanically before writing (never write a token or designId value — §2.7). " +
+      "A design review's append is stamped by the tool with a `### 轮次 N（评审子代理）` heading — N is tool-counted; do not write your own heading (it would be dropped). " +
+      "Failures are hard and visible (no silent fallback): if the write is refused or fails, say so in your report — “§× 未写入”.",
+    parameters: {
+      type: "object",
+      properties: {
+        segment: {
+          type: "string",
+          description: `The batch-record section you are writing${own ? ` — yours is ${own}` : ""}. Declares the section number only; your identity decides what is actually writable (§2.20.1).`,
+        },
+        text: {
+          type: "string",
+          description: "The markdown to append (verbatim — findings table + VERDICT + counts for a design review §3). Limit 20000 characters per call; longer content is refused — split it into multiple calls (each call becomes its own section, N continues).",
+        },
+      },
+      required: ["segment", "text"],
+    },
+    async execute(args, ctx) {
+      const agent = ctx?.agent ?? {}
+      const seg = allowedSegment(agent, review)
+      if (seg === null) {
+        throw new Error("batch_segment: no segment is writable by this caller — the channel exists for eng-designer (§2), eng-coder (§5) and design reviews bound to a batch record (§3); the parent agent writes §1/§4/§6 through ordinary document writes (ENGINEERING-MODE.md §2.20.1/§2.20.3).")
+      }
+      const n = segmentNumber(args?.segment)
+      if (n === null) {
+        throw new Error(`batch_segment: unknown segment ${JSON.stringify(args?.segment ?? null)} — pass the section number you write (e.g. "§${seg}").`)
+      }
+      if (n !== seg) {
+        throw new Error(`batch_segment: §${n} is not yours to write — this caller writes §${seg} only (一段一作者: eng-designer → §2, design review → §3, eng-coder → §5; ENGINEERING-MODE.md §2.20.1).`)
+      }
+      if (!batchDoc) {
+        throw new Error("batch_segment: no batch record is bound to this caller — there is no path parameter by design (the target arrives via the spawn binding / the review instance key, ENGINEERING-MODE.md §2.20.2). Report the section as not written.")
+      }
+      const abs = resolve(agent.cwd ?? process.cwd(), String(batchDoc).replace(/\\/g, "/"))
+      if (!readableFile(abs)) {
+        throw new Error(`batch_segment: the bound batch record is not a readable file: ${abs} — nothing was written (§2.20.1 fail-closed). Check the record still exists, then report the section as not written.`)
+      }
+      if (typeof args?.text !== "string") {
+        throw new Error("batch_segment: text must be a string (the markdown to append).")
+      }
+      if (args.text.length > MAX_TEXT_CHARS) {
+        throw new Error(`batch_segment: text is ${args.text.length} characters — the limit is ${MAX_TEXT_CHARS} per call. Split it into multiple calls: each call becomes its own section and the round number N continues (分段追加——每次调用各成节、N 顺延; ENGINEERING-MODE.md §2.20.1).`)
+      }
+      if (/^## §\d/m.test(args.text)) {
+        throw new Error("batch_segment: the text contains a section header line matching `^## §N` — that would break section location and the append-only guarantee. Rewrite it (escape the heading, or drop the leading `## §N`), then call again (§2.20.1 骨架保护). Nothing was written.")
+      }
+      const body = sanitizeText(args.text, seg === 3).replace(/^\n+/, "").replace(/\s+$/, "")
+      if (!body.trim()) {
+        throw new Error("batch_segment: nothing to append — the text is empty after credential stripping (credential values never reach the record; ENGINEERING-MODE.md §2.7/§2.20.1).")
+      }
+      const src = readFileSync(abs, "utf8")
+      const { written, roundN } = insertIntoSection(src, seg, body)
+      writeFileSync(abs, written)
+      return `batch_segment: appended ${body.length} characters to §${seg} of the batch record${roundN ? ` (### 轮次 ${roundN}（评审子代理）)` : ""}.`
+    },
+  }
+}

package/src/agent-tools/consult.mjs

@@ -27,9 +27,11 @@ import { resolveChildProvider } from "./subagent.mjs"
 import { pushReal } from "../context.mjs"
 import { offloadToolResult, escapeXml } from "../agent/helpers.mjs"
 import { logEvent, errText } from "../log.mjs"
+import { deathLine } from "../abort-provenance.mjs"
 import { makeRelay, wrapChildCallbacks, runWithContinue, ensureChildApiKey, clampEffort } from "../agent/spawn-child.mjs"
 // ASYNC-RESULT-CONTAINER.md D2/D3/D6：pending 单容器停靠 + settle 公共收尾 + child signal 单点
 import { buildChildSignal, settleAsyncEntry } from "./async-settle.mjs"
+import { digestBudgetOver, persistOverflowReport } from "./digest-budget.mjs" // B5（群 B 批 §22 D-DG2）：digest 注入预算单源
 
 // Named consult defaults (consult P2, 2026-08-30).
 const CONSULT_TIMEOUT_MS = 600_000 // default consult lifecycle timeout
@@ -178,8 +180,15 @@ export function composeConsultDigest(session) {
  * (_pendingAsyncResults——ASYNC-RESULT-CONTAINER.md D2——role 分发注入）。
  */
 export async function injectConsultResult(agent, entry) {
-  const body = entry?.report ?? "(no consultation result)"
-  const preview = await offloadToolResult(String(body), `consult-${entry.id ?? "session"}`)
+  const full = String(entry?.report ?? "(no consultation result)")
+  // §22 D-DG3（群 B 批 B5）：计入预算的 raw = 报告正文（标签行不计）——首行标签拆出；超限
+  // 路径保留族标签行（与 VSC 镜像同形）；落盘内容 = raw（与其余三族同口径）。
+  const at = full.indexOf("\n")
+  const label = at === -1 ? "" : full.slice(0, at + 1)
+  const raw = at === -1 ? full : full.slice(at + 1)
+  const over = digestBudgetOver(agent, raw.length)
+  const saved = over ? await persistOverflowReport(raw, { tag: `consult-${entry?.id ?? "session"}` }) : null
+  const preview = saved ? `${label}${saved}` : await offloadToolResult(full, `consult-${entry?.id ?? "session"}`)
   pushReal(agent, {
     role: "user",
     content: escapeXml(preview),
@@ -208,7 +217,8 @@ async function runConsultChild(ctx, session, id, m, problem, ctrl) {
   const armWatchdog = () => {
     const t = setTimeout(() => {
       timedOut = true
-      try { ctrl.abort() } catch { /* already settled */ }
+      // §20.3 站点 #12 信号面（第 24 批）：watchdog 中止带 timeout reason
+      try { ctrl.abort({ abortTrigger: "timeout", abortDetail: "consult-watchdog" }) } catch { /* already settled */ }
     }, timeoutMs)
     t.unref?.()
     return t
@@ -329,7 +339,7 @@ async function runConsultChild(ctx, session, id, m, problem, ctrl) {
     } catch (e) {
       // Runner errors (incl. the watchdog's abort) settle as a failed reply — the
       // continue/declined paths are already handled inside runWithContinue.
-      const note = timedOut ? `consultation timed out after ${Math.round(timeoutMs / 60000)}min (agent.consultTimeoutMs)` : e?.message ?? String(e)
+      const note = timedOut ? `consultation timed out after ${Math.round(timeoutMs / 60000)}min (agent.consultTimeoutMs)` : deathLine(e, ctrl?.signal)
       settle(false, note)
       logSettle("error", note)
     }
@@ -338,8 +348,9 @@ async function runConsultChild(ctx, session, id, m, problem, ctrl) {
     // continue-prompt settle as failed replies — the runner's own errors are already
     // handled inside the loop above. relayPrefix is null on these paths — no TUI
     // block was ever opened, so no freeze event is emitted.
-    settle(false, e?.message ?? String(e))
-    logSettle("error", e?.message ?? String(e))
+    const line = deathLine(e, ctrl?.signal)
+    settle(false, line)
+    logSettle("error", line)
   } finally {
     clearTimeout(watchdog)
   }
@@ -354,7 +365,7 @@ async function runConsultChild(ctx, session, id, m, problem, ctrl) {
 export function cleanupConsultSessions(agent) {
   for (const s of agent._consultSessions?.values() ?? []) {
     s.stopped = true
-    for (const c of s.controllers ?? []) { try { c.abort() } catch { /* already settled */ } }
+    for (const c of s.controllers ?? []) { try { c.abort({ abortTrigger: "stop", abortDetail: "consult-cleanup" }) } catch { /* already settled */ } }
   }
   agent._consultSessions?.clear()
 }
@@ -415,8 +426,9 @@ export const consultStartTool = {
       // 兜底：挂起会话内的 consult children 持会话 signal，digest 自身 Ctrl+C 不误伤）。
       const baseSignal = buildChildSignal(agent, ctx)
       if (baseSignal) {
-        if (baseSignal.aborted) ctrl.abort()
-        else baseSignal.addEventListener("abort", () => ctrl.abort(), { once: true })
+        // §20.3 站点 #10（第 24 批）：hop 逐跳保 reason
+        if (baseSignal.aborted) ctrl.abort(baseSignal.reason)
+        else baseSignal.addEventListener("abort", () => ctrl.abort(baseSignal.reason), { once: true })
       }
       // Fire and forget — each child settles itself into the session; the session
       // routes to the pending single container when every child has settled (R17).
@@ -449,7 +461,8 @@ export const consultStopTool = {
     if (!s) return JSON.stringify({ error: "unknown consult id" })
     const abandoned = s.pending
     s.stopped = true
-    for (const c of s.controllers) { try { c.abort() } catch { /* already settled */ } }
+    // §20.3 站点 #11（第 24 批）：会话级停 = stop
+    for (const c of s.controllers) { try { c.abort({ abortTrigger: "stop", abortDetail: "consult-stop" }) } catch { /* already settled */ } }
     return JSON.stringify({ abandoned, cancelled: true })
   },
 }

package/src/agent-tools/design-token.mjs

@@ -73,12 +73,25 @@ export function makeDesignTokenRegex(token, flags = "") {
  * later review of the same doc-set starts a fresh full review). On non-echo:
  * strip every dead token occurrence and return the findings text — slots stay
  * untouched (方案 ②: a failed re-review revokes nothing).
+ * @param {Object} [opts] — 第 11 批（A/F11）：`opts.incomplete` = 宿主尾族判定 kind
+ *   （单谓词 `advisorIncompleteMarker`——结算方透传）。非空 ⇒ **一律不签发**（无论评审文本
+ *   是否回显 token）：剥除全部 token 回显 + 追加未签发提示（原因 + 恢复指引），不写槽、
+ *   不关实例（可重评）。
  * @returns {{passed: boolean, output: string}}
  */
-export function settleDesignReview(agent, run, designToken, rawResult) {
+export function settleDesignReview(agent, run, designToken, rawResult, opts = {}) {
   if (!designToken || typeof rawResult !== "string") {
     return { passed: false, output: rawResult ?? "" }
   }
+  // A（F11/§14.3 消费点 1）：未完成即不签发——判据与 code 完成守卫同源（单谓词）。
+  const incomplete = opts?.incomplete ?? null
+  if (incomplete) {
+    const stripped = rawResult.replace(makeDesignTokenRegex(designToken, "g"), "").trim()
+    return {
+      passed: false,
+      output: `${stripped}\n\n评审未完成——token 未签发 (review incomplete — no design token issued; reason: ${incomplete})\n以更小范围重跑设计评审（逐档 / 逐节拆分，或拆到两次评审），或调大 agent.advisor.timeoutMs 后重试；补充检查未完成的部分不得按已核处理。`.trim(),
+    }
+  }
   const tokenPattern = makeDesignTokenRegex(designToken)
   if (!tokenPattern.test(rawResult)) {
     const stripped = rawResult.replace(makeDesignTokenRegex(designToken, "g"), "").trim()

package/src/agent-tools/digest-budget.mjs

@@ -0,0 +1,76 @@
+/**
+ * digest-budget.mjs — digest 注入批量预算单源（群 B 批 B5——AGENT-LOOP.md §22 语义源）。
+ * 原预算块居 subagent-async.mjs（只覆盖经 injectAsyncResult 的三族：subagent / advisor /
+ * escalate），consult 族注入器（injectConsultResult）绕过 ⇒ 多族条目同轮合并注入时可累计
+ * 超限（BATCH-3-STRUCTURE F-2 原始事故面 1.3MB 请求体）。本档把常量 / 判超 / 记账 / 落盘
+ * 四处合一（D2 单源）+ 四族全接线（D-DG2）。
+ *
+ * 契约（D-DG1 三导出——CLI 面）：
+ * - `DIGEST_INJECT_BUDGET`（64×1024——与 offload 单条预览同量级）；
+ * - `digestBudgetOver(agent, size)`——判超 + 记账：`used > 0 && used + size > BUDGET`
+ *   首条豁免保留（单条大报告 >64K 走 offload 预览照旧——预算只约束轮累计）；轮界定
+ *   `agent.history.length !== r.len + 1` 语义逐字迁入（相邻注入间 history 无其他落史 = 同轮；
+ *   每次注入 pushReal 恰 +1——他人落史 = 新请求窗口 → 预算复位）；键 = agent（会话级复用
+ *   ——Map 常驻一两项）。
+ * - `persistOverflowReport(raw, { tag })`——超限条目全量落盘（`configDir/tool-results` +
+ *   `cleanupOldToolResults` 轮转；落盘名 `<ts>-<tag>.log`（tag = 溯源标签：写入族 + 条目 id
+ *   ——非法字符归一 `_`））。返回清单行文本（inline = 仅此——不 inline 全文）；落盘失败 →
+ *   null（调用方回退常规 inline 路径——offload 同款「失败不吞报告」语义）。
+ *
+ * 计数口径（D-DG3）：计入预算的 raw = 报告 / 错误正文（不含 `[System reminder: …]` 标签行
+ * ——与既有口径一致）；错误条目同计同落盘。
+ *
+ * 兼容面（D-DG4）：subagent-async.mjs 保留 `DIGEST_INJECT_BUDGET` +
+ * `_setDigestOffloadDirForTest` re-export（测试导入面零改）；单条 offload 预览路径零改。
+ *
+ * 模块图：import node:fs/promises + node:path + ../agent/helpers.mjs（cleanupOldToolResults）+
+ * ../config.mjs（configDir）——叶子级；subagent-async / consult 单向 import 本档（无环）。
+ */
+import { mkdir, writeFile } from "node:fs/promises"
+import { join } from "node:path"
+import { cleanupOldToolResults } from "../agent/helpers.mjs"
+import { configDir } from "../config.mjs"
+
+export const DIGEST_INJECT_BUDGET = 64 * 1024 // 64K——与 offload 单条预览同量级
+
+// 轮记账：agent → { len, used }（逐字自 subagent-async.mjs 迁入——语义零变）。
+const digestRounds = new Map()
+function digestRoundFor(agent) {
+  const h = agent.history
+  const r = digestRounds.get(agent)
+  if (!r || h.length !== r.len + 1) {
+    const fresh = { len: h.length, used: 0 }
+    digestRounds.set(agent, fresh)
+    return fresh
+  }
+  r.len = h.length
+  return r
+}
+
+/** 判超 + 记账（size = 原始正文字符数——标签行不计；先判后记：首条恒豁免）。 */
+export function digestBudgetOver(agent, size) {
+  const round = digestRoundFor(agent)
+  const over = round.used > 0 && round.used + size > DIGEST_INJECT_BUDGET
+  round.used += size
+  return over
+}
+
+/** Test seam: 落盘目录重定向（单测沙箱——生产从不调用）。 */
+let _digestOffloadDirOverride = null
+export function _setDigestOffloadDirForTest(dir) { _digestOffloadDirOverride = dir }
+
+/** 超限条目全量落盘（返回清单行文本；失败 null——调用方回退 inline——结果零丢失）。
+ *  tag 入文件名（溯源：写入族 + 条目 id）。 */
+export async function persistOverflowReport(raw, { tag }) {
+  try {
+    const dir = _digestOffloadDirOverride ?? join(configDir, "tool-results")
+    await cleanupOldToolResults(dir)
+    await mkdir(dir, { recursive: true })
+    const file = join(dir, `${Date.now()}-${String(tag).replace(/[^a-zA-Z0-9_-]/g, "_")}.log`)
+    await writeFile(file, raw, "utf8")
+    return `Report saved to disk (digest inject budget exceeded — full text not inlined): ${file}\nRead it with the read tool (offset/limit).`
+  } catch (e) {
+    console.warn(`[digest] report persist failed — falling back to inline (report not lost): ${e.message}`)
+    return null
+  }
+}

package/src/agent-tools/eng.mjs

@@ -34,7 +34,7 @@ export const engTool = {
       // R16 (F-R16a): OFF 不清 token——有效 token 跨模式存活（设计评审过的产物不因
       // 开关重复烧）。过期清理跑在另外三处（恢复过滤 / 开模式 / spawn 门禁拒）。
       ctx.agent._advisorRound = 0          // reset convergence budget
-      ctx.agent._advisorRuns = new Map()   // §24 D-24b: per-review instances die with the mode (fresh cycles)
+      ctx.agent._advisorRuns = new Map()   // §11.2 D-24b: per-review instances die with the mode (fresh cycles)
       ctx.agent._touchedFiles = []         // clear mutation tracking
       ctx.agent._lastEngState = false
       ctx.agent._pendingReminders = ctx.agent._pendingReminders ?? []
@@ -52,11 +52,11 @@ export const engTool = {
       // R16 (F-R16b ②): off→on 不重评——只清过期 token（用户裁定"打开工程模式时
       // 应该清理"），有效 token 原样保留——遍历 Map 删过期，返回文案含清理个数。
       const cleared = purgeExpiredDesignTokens(ctx.agent)
-      ctx.agent._advisorRuns = new Map() // §24 D-24b: per-review instances die with the mode (fresh cycles)
+      ctx.agent._advisorRuns = new Map() // §11.2 D-24b: per-review instances die with the mode (fresh cycles)
       ctx.agent._lastEngState = true
       ctx.agent._pendingReminders = ctx.agent._pendingReminders ?? []
       ctx.agent._pendingReminders.push(ENG_ON_REMINDER)
-      let msg = "Engineering mode activated. Design-before-code enforced: write a design document in docs/, run advisor with type='design', get user approval, then implement via eng-coder subagents."
+      let msg = "Engineering mode activated. Design-before-code enforced: write a design document first (location per your project's document conventions), run advisor with type='design', get user approval, then implement via eng-coder subagents."
       if (cleared > 0) {
         msg += ` Cleared ${cleared} expired design token${cleared === 1 ? "" : "s"} — 清 ${cleared} 个过期 token，有效 token 保留（TTL 内不重评）。`
       }