thincoder 0.12.59 → 0.12.61

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

@@ -1,20 +1,37 @@
 /**
  * consult.mjs — multi-model consultation ("会诊", docs/design/CONSULTATION.md). CLI port.
  *
- * Three tools: consult_start (non-blocking spawn) / consult_check (read the next
- * reply as it arrives) / consult_stop (abort the rest). The mechanism does ZERO
- * judging — the main agent reads replies and verifies with its own tools.
+ * Two tools (AGENT-LOOP.md §25 D-R17a — R17, 2026-09-06): consult_start
+ * (non-blocking spawn) / consult_stop (cancel a running session). consult_check
+ * was RETIRED with the digest auto-injection: the mechanism does ZERO judging —
+ * when every model of a session settles (pending 0), the session moves to the
+ * pending single container (`_pendingAsyncResults` +role "consult"——
+ * ASYNC-RESULT-CONTAINER.md D2——升格完整 entry) and the NEXT run start (user turn
+ * or digest auto-turn) injects the full verdict text ("[System reminder:
+ * consultation #id finished — N replies …]" — per-model status annotations on
+ * partial/full failures) for the main agent to judge and act on in the digestion
+ * round. A cancelled session (consult_stop) never reaches the stream.
  *
  * CLI adaptation (vs the VS Code plugin): the child runner is CLI's runAgent
  * (runAgent(child, input, callbacks, opts) — an agent object, not provider+cwd);
  * children are built with createAgent({ role: "consult", readonly tools,
  * CONSULT_BASE overlay }); activity streams to the parent TUI via the relay
- * prefix `consult#<id>/` (same channel subagent uses), not onSubagent/onToolPanel.
+ * prefix `consult#<childRelayN>/` (one per consultant child — the shared subagent
+ * relay channel; the child relay number is NOT the session id — sessions key
+ * their own `_consultIdCounter`), not onSubagent/onToolPanel.
+ * Each child settles its own TUI block with a ⟦ev⟧done event at settle (R17 —
+ * the old in-turn check consumption is gone).
  */
 import { createAgent, runAgent, readonlyToolNames } from "../agent.mjs"
 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
@@ -112,13 +129,73 @@ export function makeMainHistoryTool(parentAgent) {
   }
 }
 
-/** Wake every parked consult_check waiter. */
-function wakeWaiters(session) {
-  const w = session.waiters.splice(0)
-  for (const resolve of w) { try { resolve(false) } catch { /* noop */ } }
+/**
+ * Full-session settle routing (R17 — AGENT-LOOP.md §25 D-R17a): a session whose
+ * pending count reached 0 has no more replies coming — the session leaves
+ * `_consultSessions` and, unless it was cancelled (consult_stop / turn-end
+ * abort), moves into the pending single container (`_pendingAsyncResults` +role
+ * "consult"——ASYNC-RESULT-CONTAINER.md D2——升格完整 entry：同 subagent/advisor/
+ * escalate 的 `{id, role, report, done, ...}` 形态）whose report carries the full
+ * per-model verdict text (composed here — all settle states are known,
+ * partial/full failures annotated per model). The entry is injected at the next
+ * run start (user turn or digest auto-turn — agent.mjs); the suspension driver
+ * is woken (settle-event parity with the async pools) so an idle settle still
+ * triggers the digestion round (T-R17j).
+ * D3：公共收尾统一走 settleAsyncEntry 共享 helper（四族同机制）——consult 族参数：
+ * 无池（会话池无条目——settle 即出池）、无 ctx（无 TUI 冻结事件——子块各自 settle 时
+ * 已冻结）、无 onAccounting；helper 按 role "consult" 恒停靠 pending（非挂起期也停靠）。
+ * Cancelled sessions produce no digest (T-R17c).
+ */
+function sessionSettled(agent, session) {
+  agent?._consultSessions?.delete(String(session.id))
+  if (session.stopped) return // cancelled — no digest (T-R17c)
+  const entry = {
+    id: String(session.id),
+    role: "consult",
+    report: composeConsultDigest(session),
+    error: null, done: true, status: "done", cancelled: false,
+    relayPrefix: null, startedAt: null, _settle: null, _settleSeq: 0,
+  }
+  settleAsyncEntry(agent, entry, { pool: null, ctx: null })
+}
+
+/** Digest body for a fully-settled session — title + one annotated line per
+ *  reply (failed replies marked per-model — round2 #7; full text is injected
+ *  verbatim and may be >64K → offloaded with a preview at injection). */
+export function composeConsultDigest(session) {
+  const replies = session.replies ?? []
+  const parts = replies.map((r) =>
+    r.failed
+      ? `- [${r.model}] (failed): ${r.reply}`
+      : `- [${r.model}]: ${r.reply}`)
+  const counts = `${replies.length} of ${session.total} models replied (${session.failed} failed)`
+  return `[System reminder: consultation #${session.id} finished — ${counts}]\n${parts.join("\n")}`
+}
+
+/**
+ * Inject one settled consult family entry into the parent history as a
+ * user-role reminder (run-start injection — agent.mjs; same shape rules as
+ * injectAsyncResult: XML-escaped, >64K offloaded with preview + path). Consumed
+ * = the caller splices the entry out of the pending single container
+ * (_pendingAsyncResults——ASYNC-RESULT-CONTAINER.md D2——role 分发注入）。
+ */
+export async function injectConsultResult(agent, entry) {
+  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),
+  })
 }
 
-function settleChild(session, id, label, ok, payload) {
+function settleChild(agent, session, id, label, ok, payload, emitDone) {
   if (ok) {
     session.received++
     session.replies.push({ model: label, reply: payload })
@@ -129,7 +206,8 @@ function settleChild(session, id, label, ok, payload) {
     session.replies.push({ model: label, reply: `(consultation failed: ${payload})`, failed: true })
   }
   session.pending--
-  wakeWaiters(session)
+  emitDone?.() // per-child TUI block freeze at settle (R17 — child's activity card is done)
+  if (session.pending === 0) sessionSettled(agent, session)
 }
 
 async function runConsultChild(ctx, session, id, m, problem, ctrl) {
@@ -139,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
@@ -161,6 +240,12 @@ async function runConsultChild(ctx, session, id, m, problem, ctrl) {
     if (kind === "ok" || kind === "partial") logEvent("child:done", { ...base, kind })
     else logEvent("child:error", { ...base, err: errText(payload, 200) })
   }
+  // R17: relay prefix assigned before the child runner arms — the per-child TUI
+  // block freeze emits only when a block actually exists (relay established).
+  let relayPrefix = null
+  const settle = (ok, payload) => settleChild(agent, session, id, label, ok, payload, relayPrefix
+    ? () => ctx.callbacks?.onToken?.(`${relayPrefix}⟦ev⟧done\x1e0\x1e0\x1edone\x1e`)
+    : null)
   try {
     // Provider resolution: consultModels entries are { provider, model, effort? } — resolve
     // via the subagent's provider resolver ("provider:model" handles cross-provider picks).
@@ -199,7 +284,7 @@ async function runConsultChild(ctx, session, id, m, problem, ctrl) {
     // Activity relay via the unified spawn-child pipeline (§7.2 D3): `consult#<subId>/`
     // prefix (same channel subagent uses — parallel consultants stay independent) +
     // onToolOutput passthrough so the consultant's tool output lands in its TUI block.
-    const relayPrefix = makeRelay(agent, "consult", ctx.callbacks?.onToken, provider.model ?? "")
+    relayPrefix = makeRelay(agent, "consult", ctx.callbacks?.onToken, provider.model ?? "")
     // LOGGING：arm（spawn 事件——relay 建立后；子内事件归属 _logId）
     childLogId = relayPrefix.slice(0, -1)
     child._logId = childLogId
@@ -238,7 +323,7 @@ async function runConsultChild(ctx, session, id, m, problem, ctrl) {
           },
           onDeclined: (e) => {
             declined = true
-            settleChild(session, id, label, false, `turn cap reached (${e.turn} turns) — stopped, diagnosis may be partial`)
+            settle(false, `turn cap reached (${e.turn} turns) — stopped, diagnosis may be partial`)
             logSettle("partial", null)
             return undefined
           },
@@ -246,44 +331,43 @@ async function runConsultChild(ctx, session, id, m, problem, ctrl) {
       )
       // Review #1 fix: onDeclined already settled this child as a failed reply —
       // settling again here would push a phantom empty success reply and decrement
-      // `pending` twice (negative pending → consult_check's two exits both
-      // unreachable → permanent block until user abort).
+      // `pending` twice (negative pending would re-enter the settle routing).
       if (!declined) {
-        settleChild(session, id, label, true, String(result ?? ""))
+        settle(true, String(result ?? ""))
         logSettle("ok", null)
       }
     } 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)
-      settleChild(session, id, label, false, note)
+      const note = timedOut ? `consultation timed out after ${Math.round(timeoutMs / 60000)}min (agent.consultTimeoutMs)` : deathLine(e, ctrl?.signal)
+      settle(false, note)
       logSettle("error", note)
     }
   } catch (e) {
     // Errors BEFORE the runner (provider resolution, createAgent) or a throwing
     // continue-prompt settle as failed replies — the runner's own errors are already
-    // handled inside the loop above.
-    settleChild(session, id, label, false, e?.message ?? String(e))
-    logSettle("error", e?.message ?? String(e))
+    // handled inside the loop above. relayPrefix is null on these paths — no TUI
+    // block was ever opened, so no freeze event is emitted.
+    const line = deathLine(e, ctrl?.signal)
+    settle(false, line)
+    logSettle("error", line)
   } finally {
     clearTimeout(watchdog)
   }
 }
 
-/** Turn-end cleanup (called from runAgent's finally): abort every leftover
- *  consultation controller, wake parked waiters, clear the session map. */
+/** Turn-end / session-end abort cleanup (R17 — call sites: the Ctrl+C abort
+ *  branches of finalizeAgentTurn and the suspension driver). Consultation
+ *  sessions are now cross-turn background work (like async subagents): a NORMAL
+ *  turn end keeps them alive — this runs only when the user stops everything:
+ *  every leftover session is marked stopped (its settles never reach the digest
+ *  stream — T-R17c) and its controllers aborted. */
 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 w of s.waiters?.splice(0) ?? []) { try { w() } catch { /* noop */ } }
+    for (const c of s.controllers ?? []) { try { c.abort({ abortTrigger: "stop", abortDetail: "consult-cleanup" }) } catch { /* already settled */ } }
   }
   agent._consultSessions?.clear()
-  // NOTE: deliberately void (consult P3, 2026-08-30). The { stopped: true } marker
-  // only reaches the TUI via the consult_stop TOOL return (onToolResult freezes
-  // blocks on tool calls) — cleanup runs from the turn finally, where the block
-  // freeze is owned by freezeAllSubTasks + sweepToolBlocks, so a return here is
-  // dead weight. Blocks still get frozen on interrupt via that sweep.
 }
 
 export const consultStartTool = {
@@ -294,8 +378,11 @@ export const consultStartTool = {
     "Start a parallel multi-model consultation (会诊) for a hard problem you are stuck on (repeated failures, no headway). " +
     "Call it directly when the user asks for 会诊 / consult — an explicit user request applies even if you are not 'stuck'. " +
     "Several configured models (agent.consultModels) analyze the same problem INDEPENDENTLY and in parallel. " +
-    "Non-blocking: returns immediately with a consult id. Then call consult_check(id) to read each reply as it " +
-    "arrives, judge/verify it yourself with your own tools, and call consult_stop(id) once a reply is good enough.\n" +
+    "Non-blocking: returns immediately with a consult id; the consultants keep running in the background across turns. " +
+    "When EVERY model has replied (or failed), the full verdict text is delivered to you automatically — as a system " +
+    "reminder at the next run start, or digested on its own while the session is idle — judge and adopt each opinion " +
+    "yourself with your own tools (opinions are suggestions, not gates). To stop a session early (user changed their " +
+    "mind / wants the tokens back), call consult_stop(id) — a stopped session delivers no digest.\n" +
     "Parameters:\n" +
     "- problem (required): a brief — the symptom, what you already tried (failure trail), and entry-point files. " +
     "Do NOT paste raw error logs; consultants pull the main session history themselves via their main_history tool.\n" +
@@ -325,7 +412,7 @@ export const consultStartTool = {
     agent._consultSessions ??= new Map()
     const id = String((agent._consultIdCounter = (agent._consultIdCounter ?? 0) + 1))
     const session = {
-      id, controllers: [], replies: [], pending: 0, waiters: [],
+      id, controllers: [], replies: [], pending: 0,
       failed: 0, terminated: 0, stopped: false, received: 0, total: run.length,
       models: run.map(consultLabel),
     }
@@ -335,102 +422,47 @@ export const consultStartTool = {
       session.pending++
       const ctrl = new AbortController()
       session.controllers.push(ctrl)
-      if (ctx.signal) {
-        if (ctx.signal.aborted) ctrl.abort()
-        else ctx.signal.addEventListener("abort", () => ctrl.abort(), { once: true })
+      // D6 buildChildSignal 单点（ASYNC-RESULT-CONTAINER.md D5——consult 补 _sessionSignal
+      // 兜底：挂起会话内的 consult children 持会话 signal，digest 自身 Ctrl+C 不误伤）。
+      const baseSignal = buildChildSignal(agent, ctx)
+      if (baseSignal) {
+        // §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 queue.
+      // Fire and forget — each child settles itself into the session; the session
+      // routes to the pending single container when every child has settled (R17).
       runConsultChild(ctx, session, id, m, problem, ctrl)
     }
     return JSON.stringify({ id, models: session.models })
   },
 }
 
-export const consultCheckTool = {
-  name: "consult_check",
-  readonly: true,
-  description:
-    "Read the NEXT consultation reply (whichever model answered first). Blocks until a reply arrives or all models " +
-    "have settled. The reply is raw and unjudged — verify/adopt it with your own tools. When done is true, no more " +
-    "replies are coming.\n" +
-    "Call it ALONE in a turn — do NOT batch it with calls that depend on its reply (readonly tools run in parallel).\n" +
-    "Replies arrive in arrival order: call it repeatedly (n = 1, 2, 3, …) until done is true.\n" +
-    "Returns JSON: {reply, model, failedReply, received, failed, terminated, total, done} for a reply — or {done: true, received, failed, total} when none are left.\n" +
-    "Parameters:\n" +
-    "- id (required): the consult id from consult_start\n" +
-    "- n (required): the 1-based read number for this consult — pass 1 on the first check, 2 on the next, and so on. It exists so consecutive checks are distinct tool calls (loop detectors) and the transcript reads as a sequence.",
-  parameters: {
-    type: "object",
-    properties: {
-      id: { type: "string", description: "Consult id" },
-      n: { type: "number", description: "1-based read number: 1 for the first check, incrementing with each subsequent check of the same consult" },
-    },
-    required: ["id", "n"],
-  },
-  async execute({ id, n: _n }, ctx) {
-    const s = ctx.agent?._consultSessions?.get(String(id))
-    if (!s) return JSON.stringify({ error: "unknown consult id" })
-    const abortAll = () => { for (const c of s.controllers) { try { c.abort() } catch { /* noop */ } } }
-    if (ctx.signal?.aborted) abortAll()
-
-    for (;;) {
-      if (s.replies.length > 0) {
-        const r = s.replies.shift()
-        return JSON.stringify({
-          reply: r.reply, model: r.model, failedReply: r.failed === true,
-          received: s.received,
-          failed: s.failed,
-          terminated: s.terminated ?? 0, total: s.total,
-          done: s.replies.length === 0 && s.pending === 0,
-        })
-      }
-      if (s.pending === 0) {
-        return JSON.stringify({ done: true, received: s.received, failed: s.failed, total: s.total })
-      }
-      const stopped = await new Promise((resolve) => {
-        function cleanup() {
-          const i = s.waiters.indexOf(w)
-          if (i >= 0) s.waiters.splice(i, 1)
-          ctx.signal?.removeEventListener("abort", onAbort)
-        }
-        function w() { cleanup(); resolve(false) }
-        function onAbort() { cleanup(); abortAll(); resolve(true) }
-        s.waiters.push(w)
-        if (ctx.signal) {
-          if (ctx.signal.aborted) { onAbort(); return }
-          ctx.signal.addEventListener("abort", onAbort, { once: true })
-        }
-      })
-      if (stopped) return JSON.stringify({ done: true, stopped: true, received: s.received, failed: s.failed, total: s.total })
-    }
-  },
-}
-
 export const consultStopTool = {
   name: "consult_stop",
   readonly: false,
   sideEffectExempt: true,
   description:
-    "Terminate the still-running consultations of a session once a reply is good enough — saves tokens and time. " +
-    "Already-answered replies stay available for consult_check. " +
-    "Returns JSON {stopped: <n>, abandoned: <pending count>} — or {error: \"unknown consult id\"}.\n" +
+    "Cancel a still-running consultation session (会诊) — the user changed their mind, the problem resolved, or you want the tokens back. " +
+    "Aborts every consultant that is still running; a stopped session delivers NO digest (R17 — its already-collected partial replies are dropped). " +
+    "Sessions that finished on their own are no longer cancellable — their verdict text is delivered automatically.\n" +
+    "Returns JSON {abandoned: <pending count>, cancelled: true} — or {error: \"unknown consult id\"} (already finished/cancelled).\n" +
     "Parameters:\n" +
-    "- id (required): the consult id from consult_start\n" +
-    "- n (required): incrementing call number for this consult (next value after the last consult_check/consult_stop) — keeps repeated calls distinct.",
+    "- id (required): the consult id from consult_start",
   parameters: {
     type: "object",
     properties: {
       id: { type: "string", description: "Consult id" },
-      n: { type: "number", description: "Incrementing call number for this consult (see consult_check)" },
     },
-    required: ["id", "n"],
+    required: ["id"],
   },
-  async execute({ id, n }, ctx) {
+  async execute({ id }, ctx) {
     const s = ctx.agent?._consultSessions?.get(String(id))
     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 */ } }
-    return JSON.stringify({ stopped: n, abandoned })
+    // §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 })
   },
 }