@thincoder/core 0.10.9 → 0.10.11

package/agent-tools/review-facts.mjs

@@ -6,10 +6,12 @@
  *  - 2026-10-04（工具路径基面根治批 · #921）：import 面扩为「node:* + manifest 发现/声明族
  *    （叶向——manifest 族零依赖 advisor 面，零新模块边；KD-2）」——`REVIEW_ROOT_KEYS` +
  *    `resolveReviewRootsFor` 判定本体自 `agent/write-gate.mjs` 迁入（write-gate 同名再出口保
- *    既有 import 面），新增 `resolveReviewDocPaths` 文档解析四分支单源。
+ *    既有 import 面）；`resolveReviewDocPaths` = 评审文档路径解析单源；
+ *  - 2026-10-25（评审文档路径收正批）：该解析器收为**单规则**——相对形按会话项目根 / 绝对形
+ *    照用 / 受理 = 项目内现存 `.md`；候选试探与歧义归一退场（判据正文 = `ADVISOR-GUARDS.md` §12）。
  */
 import { existsSync, statSync } from "node:fs"
-import { dirname, join, resolve } from "node:path"
+import { isAbsolute, join, relative, resolve, sep } from "node:path"
 import { DEFAULT_MANIFEST, docRootPaths, readManifest } from "../manifest.mjs"
 import { owningProject, projectRootView } from "../manifest-discovery.mjs"
 
@@ -27,12 +29,13 @@ export function docSetKey(documents, cwd) {
   return JSON.stringify(list.sort())
 }
 
-/** 评审目标解析读的 docRoot 键集（评审对象/被审文件可住的所有文档层——M6 分类据此判定）。
+/** **写门面**评审根的 docRoot 键集（`agent/write-gate.mjs` 的 `resolveReviewTargetPaths` 消费）——
+ *  设计评审**受理面不再消费**本键集（受理 = 项目内现存 `.md`，判据单源 = `ADVISOR-GUARDS.md` §12）。
  *  2026-10-04 自 `agent/write-gate.mjs` 迁入（键集本体零变；write-gate 同名再出口）。 */
 export const REVIEW_ROOT_KEYS = ["requirements", "specs", "design", "modules", "batches"]
 
 /**
- * 评审目标解析单点（按用点形——2026-09-21 收口 · 台账 #828；2026-10-04 自 `agent/write-gate.mjs`
+ * 写门评审根解析单点（按用点形——2026-09-21 收口 · 台账 #828；2026-10-04 自 `agent/write-gate.mjs`
  * 迁入，逐字零变；write-gate 同名再出口保既有 import 面）。
  */
 export function resolveReviewRootsFor(dir) {
@@ -50,78 +53,45 @@ function readableFile(abs) {
   try { return existsSync(abs) && statSync(abs).isFile() } catch { return false }
 }
 
-/** 会话根集（分支①判据集——既有 advisor 面 `resolveReviewTargetPaths(agent)` 目录形态的函数式封装；档内私有——零外部消费面）。 */
-function sessionReviewRoots(cwd) {
-  return resolveReviewRootsFor(cwd ?? process.cwd())
+/** 受理判据 = 现存普通文件 ∧ 扩展名 `.md`（大小写不敏感）——`scope-not-doc` 的指义 = 评审对象必须是文档。 */
+function isDocFile(abs) {
+  return /\.md$/i.test(abs) && readableFile(abs)
+}
+
+/** `p` 是否等于 `root` 或在其子树内（段边界判——`..` 逃逸 / 跨盘 ⇒ 否）。 */
+function isInside(p, root) {
+  const rel = relative(root, p)
+  return rel === "" || (rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel))
 }
 
 /**
- * **文档解析四分支单源**（2026-10-04 · 批档 §2.2 A 本体）：逐文档
- *   分支① 零变：normAbs(doc, cwd) 落会话根集 ⇒ 受理；分支② 零变：所属项目根集命中 ⇒ 受理；
- *   分支③ 根治面：相对形 ∧ 前两分支未中 ⇒ 候选底座逐个试探（底座 = projectRootView(cwd) 现行集 ＋
- *        cwd 祖先链全量目录——自父目录起至盘根、最近→远、去重、现行集在前）——resolve(c, doc)
- *        所属项目根集命中 = 结构命中；绝对形不进本分支（未中 = 真越界，无候选可试）；
- *   分支④ 歧义归一（KD-3）：结构命中 ≥2 ⇒ 可读文件存在性唯一化（batch-paths 读面「首个可读」
- *        同款判据）：恰一可读 ⇒ 胜；≥2 可读 ⇒ fail-closed 拒（scope-doc-ambiguous 列全部
- *        可读命中）；0 可读 ⇒ not-doc 拒（诊断列全部结构命中）。
- * @returns {{ resolved: Map<string,string>, invalid: Array<{doc, attempted:string[]}>,
- *   ambiguous: {doc, hits:string[]}|null, candidates: string[] }} ambiguous = 首个歧义文档
- *   （fail-closed 首拒——消费面拒发即止）；candidates = 分支③候选集（B 文案候选提示同源）。
- *   非字符串 / 空白串项**静默跳过**（同 docSetKey 既有过滤语义——不进 resolved/invalid）。
+ * **评审文档路径解析单规则**（判据正文 = `docs/core/design/ADVISOR-GUARDS.md` §12）——逐文档：
+ *   ① 相对形：基面 = **会话项目根** `projectRootView(cwd).root`——`p = resolve(根, doc)`；越根 ⇒ `outside-project`；
+ *   ② 相对形 ∧ 项目根解析不出（锚 = `workspace` / `none`）⇒ `no-project-root`；
+ *   ③ 绝对形：照用（零根试探、零拼接）；不住在任何项目里（`owningProject` 空）⇒ `outside-project`；
+ *   ④ 受理 = 现存普通文件 ∧ `.md`（大小写不敏感）；否则 `not-doc-file`。
+ *   **零试探**：无候选项目根、无祖先链、无歧义归一——路径要求写对（用户 2026-10-25 11:41
+ *   「为啥要试探？不能要求写对吗？」）。
+ *   非字符串 / 空白串项**静默跳过**（同 docSetKey 既有过滤语义——不进 resolved / invalid）。
+ * @returns {{ resolved: Map<string,string>, invalid: Array<{doc: string, resolved: string|null, reason: string}> }}
+ *   `reason` ∈ `no-project-root` / `outside-project` / `not-doc-file`（标识行恒 `criterion=scope-not-doc`，
+ *   三值只作 `reason=`）；`resolved` 项 = 解析后绝对路径（`no-project-root` 无基面 ⇒ `null`）。
  */
 export function resolveReviewDocPaths(documents, cwd) {
-  const fwd = (p) => p.replace(/[\\/]/g, "/")
-  const sessionRoots = sessionReviewRoots(cwd).map(fwd)
   const view = projectRootView(cwd ?? process.cwd())
-  const candidates = candidateRoots(view, cwd ?? process.cwd())
-  const ownRootsCache = new Map()
-  const ownRoots = (owner) => {
-    let r = ownRootsCache.get(owner)
-    if (!r) {
-      r = resolveReviewRootsFor(owner).map(fwd)
-      ownRootsCache.set(owner, r)
-    }
-    return r
-  }
-  // under = 段边界判（比较面用 `/` 归一形；**产出面保原生形态**——docAbs / resolved 与 normAbs
-  // 既有形态同族，冻结窗/陈旧谓词零改照比对——win32 反斜杠面不破）。
-  const under = (pNative, rootsFwd) => {
-    const p = fwd(pNative)
-    return rootsFwd.some((r) => p === r || p.startsWith(r + "/"))
-  }
-
   const resolved = new Map()
   const invalid = []
-  let ambiguous = null
   for (const doc of (documents ?? [])) {
     if (typeof doc !== "string" || !doc.trim()) continue
-    const isAbs = /^[a-zA-Z]:[\\/]/.test(doc) || doc.startsWith("/") || doc.startsWith("\\\\")
-    const n = normAbs(doc, cwd)
-    // 分支① 会话根集 / 分支② 所属项目根集（既有行为零变——判定序同 advisor.mjs 旧面）。
-    if (under(n, sessionRoots)) { resolved.set(doc, n); continue }
-    const owner = owningProject(n)
-    if (owner && under(n, ownRoots(owner))) { resolved.set(doc, n); continue }
-    // 分支③ 候选项目根试探（相对形 only——绝对形未中 = 真越界，无候选可试）。
-    let hits = []
-    if (!isAbs && candidates.length > 0) {
-      for (const c of candidates) {
-        const t = resolve(c, doc)
-        const cOwner = owningProject(t)
-        if (cOwner && under(t, ownRoots(cOwner))) hits.push(t)
-      }
-    }
-    // 分支④ 歧义归一：结构命中 ≥2 ⇒ 可读文件存在性唯一化；恰 1 命中 ⇒ 受理（存在性仅作
-    // 歧义唯一化判据——单命中无判别力，同分支①声明根集受理面一致不查存在）。
-    if (hits.length >= 2) {
-      const readable = hits.filter((h) => readableFile(h))
-      if (readable.length === 1) { resolved.set(doc, readable[0]); continue }
-      if (readable.length >= 2) { ambiguous = { doc, hits: readable }; break }
-    } else if (hits.length === 1) {
-      resolved.set(doc, hits[0]); continue
-    }
-    invalid.push({ doc, attempted: hits })
+    const abs = /^[a-zA-Z]:[\\/]/.test(doc) || doc.startsWith("/") || doc.startsWith("\\\\")
+    if (!abs && view.state !== "ok") { invalid.push({ doc, resolved: null, reason: "no-project-root" }); continue }
+    const p = abs ? doc : resolve(view.root, doc)
+    if (!abs && !isInside(p, view.root)) { invalid.push({ doc, resolved: p, reason: "outside-project" }); continue }
+    if (abs && !owningProject(p)) { invalid.push({ doc, resolved: p, reason: "outside-project" }); continue }
+    if (!isDocFile(p)) { invalid.push({ doc, resolved: p, reason: "not-doc-file" }); continue }
+    resolved.set(doc, p)
   }
-  return { resolved, invalid, ambiguous, candidates }
+  return { resolved, invalid }
 }
 
 /** #949（评审 history 串台面 ① 镜像键控）：评审实例镜像三值单点定域（round ∥ prior ∥
@@ -140,19 +110,3 @@ export function noteReviewDelivered(agent, run) {
   if (!run || typeof run !== "object") return
   run.historyAnchorIdx = Array.isArray(agent?.history) ? agent.history.length : 0
 }
-
-/** 分支③候选底座（`MANIFEST.md` §2.5「路径归一增量」族第四笔 · 2026-10-05 · #945）：现行
- *  `projectRootView(cwd)` 集（ok → [root]；workspace → candidates 按名序；none → 空集）＋
- *  cwd 祖先链全量目录（自父目录起至盘根、最近→远、去重、现行集在前）——容器相对形在子仓锚下
- *  可解析；受理判据（目标解析位最近 manifest 声明面）∥ 围栏 ∥ 可读唯一化 ∥ fail-closed 歧义零改。 */
-function candidateRoots(view, cwd) {
-  const current = view.state === "ok" ? [view.root] : view.state === "workspace" ? view.candidates : []
-  const ancestors = []
-  for (let d = dirname(resolve(cwd)); ; ) {
-    ancestors.push(d)
-    const p = dirname(d)
-    if (p === d) break
-    d = p
-  }
-  return [...new Set([...current, ...ancestors])]
-}

package/agent-tools/settings.mjs

@@ -12,7 +12,7 @@
  * 走显式形状表（_NULL_LEAF_SHAPES 相等面 / _SIBLING_SHAPES 存在性面——按各自真实消费形态
  * 校验，完备性机械锁 + 一次性警告；SETTINGS-TOOL.md §8）；set 侧效走审批门（dispatch 动作级分类）。
  */
-import { DEFAULTS, configPath, writeConfigAtomic } from "../config.mjs"
+import { DEFAULTS, configPath, promoteAgentViews, writeConfigAtomic } from "../config.mjs"
 import { DESC } from "../tools/shared.mjs" // #15 描述外置：文本单点 = tool-docs/settings.md
 
 /** 敏感键段判定（完整点分路径的段级匹配——两句取或：词表段 ∨ 开口键族段；SETTINGS-TOOL.md §2.4）。
@@ -136,14 +136,38 @@ function _checkShape(path, spec, value) {
   }
 }
 
+/* ─── advisor 写面（本批——D-ST18 ∥ promoted 视图同步；SETTINGS-TOOL.md §2.3 / §2.6） ─── */
+
+/** `agent.advisor.*` ⇄ promoted `advisor.*` 路径映射（写面三条腿的同步面——§2.3）；其它键 ⇒ null。 */
+function _promotedAdvisorPath(path) {
+  const key = String(path)
+  if (key === "agent.advisor") return "advisor"
+  if (key.startsWith("agent.advisor.")) return `advisor.${key.slice("agent.advisor.".length)}`
+  return null
+}
+
+/** D-ST18：advisor 超时的两个写面键只收 `null`（显式清除）∥ 有限正数（ms）。
+ *  读面的「非法一律回退默认」是手写 config.json 的兜底，不是写面的许可证——收下 `0` 再回显
+ *  「运行中已生效」= D-ST6 要防的静默面。拒绝句点名键与可消费形态。 */
+function _checkAdvisorTimeout(value) {
+  if (value === null) return
+  if (typeof value === "number" && Number.isFinite(value) && value > 0) return
+  throw new Error("advisor.timeoutMs must be a finite positive number (ms) or null")
+}
+
 /**
  * 已知键值校验（set 写盘前；违例抛错——磁盘/内存零变化）：
+ * ⓪ advisor 写面两键先判（D-ST18：只收 null ∥ 有限正数；整段赋值腿对对象内 timeoutMs 同规则）；
  * ① 形状表命中键（`_NULL_LEAF_SHAPES` / `_SIBLING_SHAPES` **两表都查**——表值 = 形状规格）→ 形状校验
  *    （`null` = 显式清除，放行）；② 非 null 叶子（派生表值 = `typeof` 串）→ 既有语义逐字保留
  *    （`want === "array"` 跳过 / `null` + `want ∈ _NULL_CLEARABLE` 放行——#645 扩 number/boolean）；
  *  ③ 未知键 → 原样通过（全量域）。
  */
 function _checkKnownKeyValue(path, value) {
+  if (path === "agent.advisor.timeoutMs" || path === "advisor.timeoutMs") return _checkAdvisorTimeout(value)
+  if ((path === "agent.advisor" || path === "advisor") && value !== null && typeof value === "object" && !Array.isArray(value) && "timeoutMs" in value) {
+    _checkAdvisorTimeout(value.timeoutMs) // 整段赋值腿（两个段名）：对象内该键同规则校验（§2.6）
+  }
   const spec = _NULL_LEAF_SHAPES[path] ?? _SIBLING_SHAPES[path]
   if (spec) {
     if (value === null) return // 显式清除 = 有效动作（消费面均有「未设置」态——D-S2.3）
@@ -206,10 +230,28 @@ function flatten(obj, prefix = "", out = []) {
   return out.sort((a, b) => (a.path < b.path ? -1 : 1))
 }
 
-/** 行格式化：`key = value (type)`——敏感键值遮罩 */
+/** 递归掩码：父对象不敏感、子键敏感时整棵子树替换为 MASKED（Gitee #21）。
+ *  只判查询路径本身会让 `get providers` 把 `providers[].apiKey` 明文吐出来——
+ *  而工具契约写着「敏感键永不明文回显」；父键不敏感不等于子树安全。 */
+function maskDeep(value, prefix) {
+  if (value === null || typeof value !== "object") return value
+  if (Array.isArray(value)) return value.map((v, i) => maskDeep(v, `${prefix}.${i}`))
+  const out = {}
+  for (const [k, v] of Object.entries(value)) {
+    const sub = `${prefix}.${k}`
+    out[k] = isSensitiveKey(sub) ? MASKED : maskDeep(v, sub)
+  }
+  return out
+}
+
+/** 行格式化：`key = value (type)`——敏感键值遮罩（含子树递归） */
 function formatLine({ path, value }) {
   // #58（hygiene-sweep 批）：对象值渲染收正（原 `[object Object]`——JSON 化；敏感键仍恒遮）
-  const shown = isSensitiveKey(path) ? MASKED : value !== null && typeof value === "object" ? JSON.stringify(value) : value
+  const shown = isSensitiveKey(path)
+    ? MASKED
+    : value !== null && typeof value === "object"
+      ? JSON.stringify(maskDeep(value, path))
+      : value
   return `${path} = ${shown} (${Array.isArray(value) ? "array" : typeof value})`
 }
 
@@ -275,11 +317,29 @@ export function settingsTool(opts = {}) {
         else setKeyPath(disk, args.key, value)
       })
       if (!r.ok) throw new Error("config changed on disk concurrently — retry (settings set not applied)")
+      const promotedPath = _promotedAdvisorPath(args.key) // `agent.advisor.*` 的 promoted 副本路径（其它键 ⇒ null）
+      const fresh = (v) => (v !== null && typeof v === "object" ? structuredClone(v) : v) // DEFAULTS 是共享常量——回填不别名
       if (value === null) {
         deleteKeyPath(config, args.key)
+        // `null` 删除腿：副本同子键同删，**不再 re-derive**——promote 会把 config.advisor 旧值带回（§2.3）
+        if (promotedPath) deleteKeyPath(config, promotedPath)
         const d = resolvePath(DEFAULTS, String(args.key))
-        if (d.ok) setKeyPath(config, args.key, d.value) // 回填默认（形状表键默认 null ⇒ 与今日同形）
-      } else setKeyPath(config, args.key, value)
+        if (d.ok) {
+          setKeyPath(config, args.key, fresh(d.value)) // 回填默认（形状表键默认 null ⇒ 与今日同形）
+          if (promotedPath) setKeyPath(config, promotedPath, fresh(d.value)) // 副本与 reload 等价（loadConfig 以 nested 为准）
+        }
+      } else {
+        setKeyPath(config, args.key, value)
+        // promoted 视图同步（§2.3）：整段赋值 = `promoteAgentViews` 合并语义；子键 set = **只同步被写的键**。
+        // 子键也整段 re-derive 会拿嵌套面上的同名默认值盖回运行面（`DEFAULTS.agent.advisor.guard = false`，
+        // 经 `loadConfig` 并进 `agent.advisor`）⇒ `/advisor` 打开的会话级 guard 会被静默关掉，
+        // 违反「运行面独有的会话级键在合并中保留」。
+        if (promotedPath === "advisor") {
+          promoteAgentViews(config) // 整段赋值 = 同一条 promote 规则（合并语义：只覆盖、不删除；非对象段不展开）
+        } else if (promotedPath !== null) {
+          setKeyPath(config, promotedPath, value) // 子键 set：键级同步（与 null 腿同一种「同一子键」口径）
+        }
+      }
       const sensitive = isSensitiveKey(String(args.key))
       const shown = sensitive ? MASKED : value
       const suffix = value === null

package/agent-tools/spawn-gates.mjs

@@ -1,7 +1,10 @@
 /**
  * spawn-gates.mjs — M5 委派与 spawn 门新门禁统一落点（ENGINEERING-MODE-V2-MODULE-DELEGATION §2.3）：
  * 全部新增门禁逻辑集中于此——装配点（buildSpawnChild / normalizeFileList）只加 import 调用。
- * 已实现：F2（round 枚举 + 任务书参数校验/拼装——四项核心 + 第五项按角色）· F6（files 声明面拦截谓词）。
+ * 已实现：F2（round 枚举 + 任务书参数门/拼装）· F6（files 声明面拦截谓词）。
+ * 2026-10-24（AGENT-LOOP-SUBAGENT.md §6.22）：任务书单通道 = 批次档 §2——工程角色
+ *   （eng-coder / eng-designer）零任务书文本参数，八个自由文本键（键在场即拒）命中即点名拒收；
+ *   非工程角色（explore / plan / coder）保持四项核心 + `scope`。
  * 裁撤（2026-09-17 主 agent 裁定——不落代码）：
  *   - F4 修复轮窄带：全量勘察散文 marker 不可机判（误拒风险不可接受）→ 由 F2 的 round 参数承载轮次语义；
  *   - F5 advisor 角色：advisor 不入 spawn 通道（评审走 advisor 工具）——enum 收正为
@@ -14,18 +17,15 @@
  */
 export const ROUND_VALUES = ["initial", "fix"]
 
-/** 任务书样例内容（供人照抄；不是门的判据——门只判存在 / 类型 / 非空）：核心四项一份，
- *  第五项按角色各一份（工程角色 = `designPoints` ∥ explore / plan / coder = `scope`）。 */
+/** 任务书样例内容（供人照抄；不是门的判据——门只判存在 / 类型 / 非空）：非工程角色
+ *  = 四项核心 + `scope`（工程角色无任务书文本参数——任务书 = 批次档 §2）。 */
 const TASK_BOOK_CORE_MIN = {
-  goal: "实现批准设计（样例任务书——四项核心 + 角色第五项齐备）。",
+  goal: "实现批准设计（样例任务书——四项核心 + `scope` 齐备）。",
   knownFacts: "设计已评审通过、token 已签发、批次档在册。",
   acceptance: "设计档的验收口径逐条可机验、项目验证链全绿。",
   reportFormat: "交付表 + 文件路径 + 验证命令与结果。",
 }
 
-/** 工程角色样例（核心四项 + `designPoints`）。 */
-export const ENG_TASK_BOOK_MIN = { ...TASK_BOOK_CORE_MIN, designPoints: "仅落设计档受影响文件清单；禁夹带新语义。" }
-
 /** 非工程角色样例（核心四项 + `scope`）——explore / plan / coder。 */
 export const PLAIN_TASK_BOOK_MIN = { ...TASK_BOOK_CORE_MIN, scope: "只读：相关源 / 设计档；不写任何文件、不碰 bench/。" }
 
@@ -46,61 +46,97 @@ export function validateRoundParam(args) {
   throw new Error(
     `Engineering spawn round gate: ${missing.join(" · ")}. ` +
     `The spawn contract requires the structured round parameter (initial|fix); ` +
-    `the five task-book parameters are enforced by a separate gate (validateTaskBookParams) — ` +
+    `task-book text parameters are refused for engineering roles by a separate gate (rejectEngFreeTextParams) — ` +
     `a missing or invalid round is a dispatch defect and the spawn is refused.`)
 }
 
+/** 工程角色名集（单一判据 = 是否有写权 ⇒ 只应有唯一任务来源——AGENT-LOOP-SUBAGENT.md §6.22）。 */
+const ENGINEERING_ROLES = new Set(["eng-coder", "eng-designer"])
+
+/** 角色 ∈ 工程角色（任务书 = 批次档 §2，零任务书文本参数）。 */
+export function isEngineeringRole(role) {
+  return ENGINEERING_ROLES.has(role)
+}
+
+/** 工程角色拒收的自由文本参数（八名单源）：全部进子代理 input 的自由文本 ⇒ 第二任务来源。
+ *  `designPoints` 已从 schema 退役；门取工具入参原对象（未声明键仍可达），故仍在名单内
+ *  ——拒收面不依赖 schema 声明。 */
+export const ENG_REFUSED_PARAMS = ["goal", "knownFacts", "acceptance", "reportFormat", "scope", "task", "context", "designPoints"]
+
+/** 工程角色必填集合（拒收文案的「还缺什么」面；判据本体 = batchDoc / round / token 各门）。 */
+const ENG_REQUIRED_NAMES = {
+  "eng-coder": "role · batchDoc (readable) · round · designToken (plus designId when several slots are held)",
+  "eng-designer": "role · batchDoc (readable) · round",
+}
+
 /**
- * F2 任务书名集（**所有 spawn 角色**）：core = 四项核心（全员必带）；fifth = 第五项两名
- * ——工程角色 = `designPoints` ∥ explore / plan / coder = `scope`。
+ * 工程角色任务书门（AGENT-LOOP-SUBAGENT.md §6.22.1）：**键在场即拒**——值全空白也拒
+ * （键在场说明派单方仍以为自己在写第二本任务书）。命中即抛，逐键点名并给出必填集合；
+ * `designPoints` 另附退役句。非工程角色不经本门（零改）。
+ */
+export function rejectEngFreeTextParams(args, role) {
+  const a = args ?? {}
+  const offending = ENG_REFUSED_PARAMS.filter((name) => a[name] !== undefined)
+  if (offending.length === 0) return
+  const names = offending
+    .map((name) => (name === "designPoints"
+      ? `${name} (designPoints is retired for every role — write §2, or scope for explore/plan/coder)`
+      : name))
+    .join(" / ")
+  const required = ENG_REQUIRED_NAMES[role] ?? "role · batchDoc (readable) · round"
+  throw new Error(
+    `Spawn task-channel gate (role='${role}'): ${names}. ` +
+    `An engineering spawn carries NO task-book text parameters — the task book is batch record §2 (batchDoc), read by the child itself. ` +
+    `Put everything the child needs into §2 before spawning; a thin §2 earns a bounce, not a supplement. ` +
+    `Required for role='${role}': ${required}.`)
+}
+
+/**
+ * F2 任务书名集（**非工程角色**：core = 四项核心 + fifth = `scope`）。工程角色 = 零任务书
+ * 文本参数（§6.22.1），不经本表。
  * 单源：本档为唯一名集处——校验 / 拼装 / 探针夹具校验一律经 `taskBookParamsFor(role)` 派生（D2）。
- * 样例对象 = `ENG_TASK_BOOK_MIN` / `PLAIN_TASK_BOOK_MIN`（供人照抄）。
+ * 样例对象 = `PLAIN_TASK_BOOK_MIN`（供人照抄）。
  */
 export const TASK_BOOK_PARAMS = {
   core: ["goal", "knownFacts", "acceptance", "reportFormat"],
-  fifth: { engineering: "designPoints", plain: "scope" },
-}
-
-/** 角色 → 第五项类别（唯一判据；**与模式无关**——工程模式里的 explore 也取 plain）。
- *  未知角色取 plain：spawn 路径上角色 enum 门先拒收（`agent-tools/subagent.mjs` 的 `ROLES`），到不了本门。 */
-function fifthClassOf(role) {
-  return role === "eng-coder" || role === "eng-designer" ? "engineering" : "plain"
+  fifth: "scope",
 }
 
-/** 角色 → 该角色的任务书名集（四项核心 + 第五项；序 = 拼装序：第五项插在 `knownFacts` 之后，
- *  与 C 之前 eng 角色的拼装序逐字相同——审计摘要 marker `/^Design points/i` 不受影响）。 */
+/** 角色 → 该角色的任务书名集（四项核心 + `scope`；序 = 拼装序：第五项插在 `knownFacts` 之后）。
+ *  工程角色返回空集——它们没有任务书文本参数（任务书 = 批次档 §2）。 */
 export function taskBookParamsFor(role) {
+  if (isEngineeringRole(role)) return []
   const core = TASK_BOOK_PARAMS.core
-  return [...core.slice(0, 2), TASK_BOOK_PARAMS.fifth[fifthClassOf(role)], ...core.slice(2)]
+  return [...core.slice(0, 2), TASK_BOOK_PARAMS.fifth, ...core.slice(2)]
 }
 
 /** 拼装标签（不导出；仅词面，不是判据——无任何匹配读它）。 */
 const TASK_BOOK_LABELS = {
   goal: "Goal & why",
   knownFacts: "Known facts",
-  designPoints: "Design points & forbidden scope",
   scope: "Scope (what to read / what not to touch)",
   acceptance: "Acceptance criteria",
   reportFormat: "Delivery report format",
 }
 
 /**
- * F2 任务书参数校验（ENGINEERING-MODE-V2-MODULE-DELEGATION §2.2）· **所有 spawn 角色**：
- * 名集按角色取（`taskBookParamsFor(role)`）。判据只有三条——参数存在 ∧ typeof string ∧
- * trim() 非空。不读内容：无正则、无标题匹配、无双语 marker。缺 / 空白 / 非字符串 → 合并抛，
- * 文案逐项点名该参数；第五项缺失而另一名在场时，文案附一句指路（只作文案，不加判据）。
+ * F2 任务书参数校验（ENGINEERING-MODE-V2-MODULE-DELEGATION §2.2）· **非工程角色**：
+ * 名集按角色取（`taskBookParamsFor(role)` = 四项核心 + `scope`）。判据只有三条——参数存在 ∧
+ * typeof string ∧ trim() 非空。不读内容：无正则、无标题匹配、无双语 marker。缺 / 空白 /
+ * 非字符串 → 合并抛，文案逐项点名该参数；`scope` 缺失而 `designPoints` 在场时，文案附一句
+ * 指路（只作文案，不加判据；工程角色不经本门——它们拒收全部自由文本键）。
  */
 export function validateTaskBookParams(args, role) {
   const a = args ?? {}
   const names = taskBookParamsFor(role)
-  const fifth = TASK_BOOK_PARAMS.fifth[fifthClassOf(role)]
-  const otherFifth = fifth === "designPoints" ? "scope" : "designPoints"
+  const fifth = TASK_BOOK_PARAMS.fifth
+  const otherFifth = "designPoints"
   const failed = []
   for (const name of names) {
     const v = a[name]
     if (v === undefined || v === null) {
       const hint = name === fifth && a[otherFifth] !== undefined && a[otherFifth] !== null
-        ? ` (got ${otherFifth} instead — that name belongs to the ${fifthClassOf(role) === "engineering" ? "explore/plan/coder" : "eng-coder/eng-designer"} spawns)`
+        ? ` (got ${otherFifth} instead — ${otherFifth} is retired for every role; the fifth parameter here is ${fifth})`
         : ""
       failed.push(`${name} — missing (the task book is four core parameters + the role's fifth)${hint}`)
     }
@@ -114,8 +150,9 @@ export function validateTaskBookParams(args, role) {
     `(the fifth parameter for role='${role}'); a missing, blank or non-string value is a dispatch defect and the spawn is refused.`)
 }
 
-/** 五参 → 子代理任务书文本（**非门禁**，纯拼装）：按 `taskBookParamsFor(role)` 固定序 + 标签，
- * 空值跳过，`\n\n` 分隔。拼装单源 = 本函数——子代理 input 与探针判官的「任务书全文」同源。 */
+/** 非工程角色任务书 → 子代理任务书文本（**非门禁**，纯拼装）：按 `taskBookParamsFor(role)` 固定序
+ * + 标签，空值跳过，`\n\n` 分隔。拼装单源 = 本函数——子代理 input、权限预览与探针判官同源。
+ * 工程角色名集为空 ⇒ 返回空串（任务书 = 批次档 §2，运行时不拼装——KD-SC5）。 */
 export function composeTaskBookBrief(args, role) {
   const a = args ?? {}
   const parts = []

package/agent-tools/subagent-async.mjs

@@ -21,7 +21,7 @@ import { runWithContinue, TURN_CAP_MARK } from "../agent/spawn-child.mjs"
 import { pushReal } from "../context.mjs"
 import { offloadToolResult } from "../agent/helpers.mjs"
 import { logEvent } from "../log.mjs"
-import { digestBudgetOver, persistOverflowReport } from "./digest-budget.mjs"
+import { digestBudgetOver, persistOverflowReport, _digestOffloadDirForTest } from "./digest-budget.mjs"
 // 群 B 批 B5（AGENT-LOOP.md §6.14 D-DG4）：预算单源迁出（digest-budget.mjs）——原处 re-export 保测试
 // 导入面零改（DIGEST_INJECT_BUDGET / _setDigestOffloadDirForTest）。
 export { DIGEST_INJECT_BUDGET, _setDigestOffloadDirForTest } from "./digest-budget.mjs"
@@ -380,10 +380,13 @@ export async function injectAsyncResult(agent, entry) {
   const body = entry.error ?? entry.report ?? "(no report)"
   // F-2（BATCH-3-STRUCTURE）+ AGENT-LOOP.md §6.14 D-DG2（群 B 批 B5）：注入前查轮累计（单源）——超限条目不
   // inline 全文，改清单行（全文经 persistOverflowReport 落盘——path 随行）。首条豁免
-  // （used===0 不判超）：单条大报告 >64K offload 预览照旧——轮预算只约束累计。
+  // （used===0 不判超）。
   const raw = String(body)
   const over = digestBudgetOver(agent, raw.length)
-  const preview = (over && await persistOverflowReport(raw, { tag: `async-subagent-${entry.id}` })) || await offloadToolResult(raw, `async-subagent-${entry.id}`)
+  // TIMEOUT-DIGEST.md §2.2：轮累计超预算 ⇒ 清单行（正文不进请求体）；否则无条件落盘——`force` 跳过
+  // 长度门（≤64K 的报告也上盘，父回合丢了还能按路径回读）；渲染二分全在 offloadToolResult。
+  const preview = (over && await persistOverflowReport(raw, { tag: `async-subagent-${entry.id}` }))
+    || await offloadToolResult(raw, `async-subagent-${entry.id}`, _digestOffloadDirForTest(), { force: true })
   // §6.10: advisor entries label themselves (role "advisor") — the digest
   // reminder says "async advisor review #N finished" (T-24b2 shape); subagent
   // entries keep the legacy wording verbatim.