@thincoder/core 0.10.3 → 0.10.5

package/agent-tools/review-facts.mjs

@@ -1,17 +1,17 @@
-/**
- * review-facts.mjs — design-review 事实面（纯事实：路径归一 + 评审范围键）。
- *
- * 本档前身 = 第 33 批（2026-09-11）的失败计数护栏档；其计数载体 / 停止谓词 / 两级检查点随
- * 「撤除全部会话级轮次计数器」**整体退场**（2026-09-18 用户裁定；设计权威 =
- * `docs/core/design/ADVISOR-CONVERGENCE.md` §3.1/§3.4 + `ADVISOR-GUARDS.md` §7）。
- * 结算分类迁出为纯函数（输出判据名、零状态）= `thincoder-core/advisor/notice.mjs`。
+/** 本档前身 = 第 33 批失败计数护栏档（载体随 2026-09-18 计数器整体退场；结算分类 = `advisor/notice.mjs`）。
  *
- * 本档 = 中立模块（**不 import 任何 src/ 模块**——打断潜在环）：
- *  - `normAbs` 自 advisor-settle.mjs 迁入（原处 re-export——既有 import 面零变；陈旧判定 /
- *    冻结拦截 / 评审范围键同源）；
- *  - `docSetKey` 自 advisor-async.mjs 迁入（原为私有——零 import 面）。
+ * 本档 = 中立模块（**不 import 任何 src/ 模块**——打断潜在环；2026-10-04 边界收窄）：
+ *  - `normAbs` 自 advisor-settle.mjs 迁入（原处 re-export——既有 import 面零变）；
+ *  - `docSetKey` 自 advisor-async.mjs 迁入（原为私有——零 import 面）；
+ *  - 2026-10-04（工具路径基面根治批 · #921）：import 面扩为「node:* + manifest 发现/声明族
+ *    （叶向——manifest 族零依赖 advisor 面，零新模块边；KD-2）」——`REVIEW_ROOT_KEYS` +
+ *    `resolveReviewRootsFor` 判定本体自 `agent/write-gate.mjs` 迁入（write-gate 同名再出口保
+ *    既有 import 面），新增 `resolveReviewDocPaths` 文档解析四分支单源。
  */
-import { join } from "node:path"
+import { existsSync, statSync } from "node:fs"
+import { dirname, join, resolve } from "node:path"
+import { DEFAULT_MANIFEST, docRootPaths, readManifest } from "../manifest.mjs"
+import { owningProject, projectRootView } from "../manifest-discovery.mjs"
 
 /** ABS 归一（cwd 相对 → cwd 拼接）——陈旧判定 / 冻结拦截 / 评审范围键同源（ADVISOR-GUARDS.md §5 E-4）。 */
 export function normAbs(p, cwd) {
@@ -19,13 +19,140 @@ export function normAbs(p, cwd) {
   return /^[a-zA-Z]:[\\/]/.test(s) || s.startsWith("/") || s.startsWith("\\\\") ? s : join(cwd, s)
 }
 
-/** Canonical scope key for design reviews — the document multi-set
- *  (order-insensitive, ABS-path normalized — launch 与 continuation 的写法差异
- *  ("./docs/x.md" vs "docs/x.md"、反斜杠) 不误建新实例).
- *  第 33 批自 advisor-async.mjs 逐字迁入（实例续跑与事实面同锚单源）。 */
+/** Canonical scope key for design reviews（写法差异不误建新实例；第 33 批自 advisor-async.mjs 迁入）。 */
 export function docSetKey(documents, cwd) {
   const list = [...new Set((documents ?? [])
     .filter((d) => typeof d === "string" && d.trim())
     .map((d) => normAbs(d, cwd)))]
   return JSON.stringify(list.sort())
 }
+
+/** 评审目标解析读的 docRoot 键集（评审对象/被审文件可住的所有文档层——M6 分类据此判定）。
+ *  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`
+ * 迁入，逐字零变；write-gate 同名再出口保既有 import 面）。
+ */
+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)]
+}
+
+/** 可读文件判据（存在且为文件——目录 / 缺失同判不可读；同 batch-paths.mjs 读面先例）。 */
+function readableFile(abs) {
+  try { return existsSync(abs) && statSync(abs).isFile() } catch { return false }
+}
+
+/** 会话根集（分支①判据集——既有 advisor 面 `resolveReviewTargetPaths(agent)` 目录形态的函数式封装；档内私有——零外部消费面）。 */
+function sessionReviewRoots(cwd) {
+  return resolveReviewRootsFor(cwd ?? process.cwd())
+}
+
+/**
+ * **文档解析四分支单源**（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）。
+ */
+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 })
+  }
+  return { resolved, invalid, ambiguous, candidates }
+}
+
+/** #949（评审 history 串台面 ① 镜像键控）：评审实例镜像三值单点定域（round ∥ prior ∥
+ *  响应表取件下界 `_advisorResponseAnchor`）——`resolveAdvisorLaunch` 发起定域 +
+ *  `entry.start` 排队 / 延迟窗口消费点复核（构建前幂等重落）；非排队 / 同步语义零变。 */
+export function scopeAdvisorMirror(agent, run) {
+  agent._advisorRound = run.priorOutput ? run.round : 0
+  agent._lastAdvisorOutput = run.priorOutput
+  agent._advisorResponseAnchor = run.historyAnchorIdx ?? null
+}
+
+/** #949（② 投递水印）：响应表取件下界 = 投递刻 history 下标（消费面前向取首表）。
+ *  调用点：async `injectAsyncResult`（pushReal 后）∥ sync record-results 记账块；
+ *  run 缺省 / 非对象（legacy 直调）⇒ 零写（回落全文倒扫）。 */
+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]；ambiguous → candidates 按名序；none → 空集）＋
+ *  cwd 祖先链全量目录（自父目录起至盘根、最近→远、去重、现行集在前）——容器相对形在子仓锚下
+ *  可解析；受理判据（目标解析位最近 manifest 声明面）∥ 围栏 ∥ 可读唯一化 ∥ fail-closed 歧义零改。 */
+function candidateRoots(view, cwd) {
+  const current = view.state === "ok" ? [view.root] : view.state === "ambiguous" ? 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

@@ -44,7 +44,7 @@ const _NULL_LEAF_SHAPES = {
   "memory.team": { kind: "team", expects: "object { repo: string, name?, dir? }" },
 }
 
-/** 同族/跨端形状表（**存在性断言面**——不参与完备性锁的集合相等）。W3 同族：`agent.subagentModels`
+/** 同族/跨端形状表（**存在性断言**——不参与完备性锁的集合相等）。W3 同族：`agent.subagentModels`
  *  默认 `{}` ⇒ 派生表零条目 ⇒ 零约束（字符串被静默忽略——回落 subagentModel）。 */
 const _SIBLING_SHAPES = {
   "agent.subagentModels": { kind: "roleMap", expects: "object of role→non-empty string" },

package/agent-tools/skill.mjs

@@ -2,7 +2,7 @@ import { loadSkills, readSkill } from "../skills.mjs"
 import { escapeXml } from "../agent.mjs"
 import { DESC } from "../tools/shared.mjs"
 
-// ─── skill loader 注入缝（#88——「同步 loader 面按核内结构归一」的端侧覆盖面）──────────
+// ─── skill loader 注入缝（#88——「同步 loader 面按核内结构归一」的端侧覆盖范围）──────────
 /**
  * skill loader 注入位（**缺省不覆盖** = 核内异步 loader——CLI 语义，零行为变；端装配层
  * 可覆盖为端形态（如核内同步面 `loadSkillsSync` / `readSkillSync` 的绑定）。核内零端名分支

package/agent-tools/subagent-actions-query.mjs

@@ -13,6 +13,8 @@ import { describeBlockers, detectStall, STALL_NOTE } from "./subagent-scheduler.
 // ASYNC-RESULT-CONTAINER.md D1：池 accessor（absorb 双池——advisor 独立池无队列）
 import { getAsyncPool } from "./async-settle.mjs"
 import { turnCapTrace } from "./checkpoint.mjs"
+// §6.31.6 未清算可见面（批 digest-accounting · 2026-10-05 · 台账 #930）：unsettled 段 + 单查续查
+import { unsettledRow, unsettledRows } from "../agent/digest-account.mjs"
 
 /**
  * subagent action:"status" (AGENT-LOOP-SUBAGENT.md §6.7 D-M2, new): NON-BLOCKING async-pool query —
@@ -22,11 +24,13 @@ import { turnCapTrace } from "./checkpoint.mjs"
  * (AGENT-LOOP-ASYNC-POOL.md §6.8 D-S3 ② — injected at the next run start) are no longer in the pool and
  * are NOT counted as done-waiting.
  * - id given → { id, role, status, model?, elapsedSec?, turn?, maxTurns?,
- *   touchedFiles?/touchedMore?/touched? ... } for that entry; unknown id → error
- *   (T12 semantics — unknown async-subagent id error, same wording as the pool).
- * - id omitted → { overview: { running: [{id, role, model, elapsedSec, turn,
- *   maxTurns, touchedFiles?/touched?}], queued: [{id, role, position, touched?}],
- *   done: [{id, role}] } } — live queue positions (index in _asyncQueue + 1).
+ *   touchedFiles?/touchedMore?/touched? ... } for that entry; when the id matches neither pool it
+ *   falls through to `_pendingAsyncResults` / `_unsettledDigests` (§6.31.6 — same row shape);
+ *   unknown everywhere → error (T12 semantics — unknown async-subagent id error, same wording as the pool).
+ * - id omitted → { overview: { running: [...], queued: [...], done: [...],
+ *   unsettled: [{id, role, state, attempts, preview?}] } } — live queue positions (index in
+ *   _asyncQueue + 1); the unsettled section lists every entry still awaiting settlement
+ *   (awaiting-digest / retrying) plus the upgraded ledger (§6.31.6).
  * AGENT-LOOP-SUBAGENT.md §6.7.2: running 条目带 touched files 摘要（touchedFiles 前 5 + touchedMore 超出
  * 计数——相对查询方 cwd；0 改动 → touched 占位）；queued 条目带 touched 占位
  * "—（未启动）"；done/error/取消条目无 touched 字段（round3 #9）。
@@ -113,6 +117,9 @@ export function executeStatusAction(args, ctx) {
     // ids are unique across both pools; role identifies the kind).
     const entry = map.get(key) ?? advisors.get(key)
     if (!entry) {
+      // §6.31.6（消化账务批）：续查 pending / 升级账本同解析——三处皆无 ⇒ 原错误文案不变。
+      const row = unsettledRow(agent, key)
+      if (row) return JSON.stringify(row)
       // Wording kept exact — locked by subagent-async/tool tests (unknown-id error
       // semantics); an unknown id simply names neither pool (the pools share the
       // id counter, so the message stays unambiguous).
@@ -146,7 +153,7 @@ export function executeStatusAction(args, ctx) {
     target.note = "settled, not yet consumed — delivered by the auto channel (turn-end collection or the suspension digest injects it)"
     return JSON.stringify(target)
   }
-  const overview = { running: [], queued: [], done: [] }
+  const overview = { running: [], queued: [], done: [], unsettled: unsettledRows(agent) }
   const mapEntries = [...map.values(), ...advisors.values()]
   for (const entry of mapEntries) {
     if (entry.status === "running") overview.running.push(statusFields(entry, agent.cwd))

package/agent-tools/subagent-async.mjs

@@ -34,8 +34,12 @@ import {
 import { cancelAsyncAdvisor, noteMutations, refreshAdvisorQueuedTokens } from "./advisor-async.mjs"
 // #94（VSC 侧并入——异步机械族）：池读取载体吸收 + 墓碑写入单点（原 inline 写收口）。
 import { getAsyncPool, tombstoneOf, writeTombstone } from "./async-settle.mjs"
+// #949（评审 history 串台面）：评审实例投递水印单点（叶档——零环）。
+import { noteReviewDelivered } from "./review-facts.mjs"
 // #9（TOOLS.md §6.19）：后台 bash 任务注入器（digest 单点族按 role="bg" 分发到本档）。
 import { injectBgResult } from "./bash-async.mjs"
+// 批 browser-async-fix：后台浏览器动作注入器（同族——role="browser" 分发到 browser-async.mjs）。
+import { injectBrowserResult } from "./browser-async.mjs"
 
 // agent-tools 共享：并行子代理的审批/继续弹窗经 owner 上命名 promise 链串行——
 // 永不叠弹窗（返回链供调用方 .then 续接）。
@@ -129,13 +133,15 @@ export function runningPoolCount(parent, pool) {
 /**
  * Resolve the sub-agent's provider from a model override string (shared with the
  * VS Code port). Forms accepted:
- *   "provider:model"  → the named provider with the named model
- *   "provider"        → the named provider's configured model
+ *   "provider:model"  → the named provider with the named model (first-colon split —
+ *                       "a:b:c" keeps model "b:c"; multi-colon model names intact)
  *   "model"           → same provider as the parent, different model
  *   "default"         → same as null: the parent's provider unchanged (explicit
  *                       "use the default model" — 2026-09-05 user ruling; matched
  *                       case-insensitively — parser-layer alias guard)
  * null → parent's provider unchanged.
+ * Rejected: bare provider names (2026-10-09 清除批——渠道无默认模型，无渠道级 model 可派生；
+ * 可读错误「渠道无默认模型，请用 provider:model」) ∥ "provider:" 空模型段。
  * API keys come from config.json only (env vars are not a key source).
  */
 export function resolveChildProvider(parent, modelArg) {
@@ -143,29 +149,32 @@ export function resolveChildProvider(parent, modelArg) {
   // #861（AGENT-LOOP-SUBAGENT.md §6.7.1 ②）运行期防御——四消费链汇点（config ∥ tool model 参数 ∥
   // consult ∥ vision-reader）：其余非字符串（对象 ∕ 数组 ∕ 数字 ∕ 布尔）明确报错（不裸 TypeError——可自纠）。
   if (typeof modelArg !== "string") {
-    throw new Error(`subagent model override must be a string ("provider:model" | provider | model); got ${Array.isArray(modelArg) ? "array" : typeof modelArg}`)
+    throw new Error(`subagent model override must be a string ("provider:model" | model); got ${Array.isArray(modelArg) ? "array" : typeof modelArg}`)
   }
   // "default" alias (2026-09-05 user ruling — ARCHITECTURE.md 子 agent 模型指定):
   // the literal "default", matched case-insensitively, declares "no override →
   // inherit the default model" — equivalent to null/omission (parent provider
   // unchanged). Checked BEFORE the provider-name lookup so the alias is reserved
   // (≡ omission — providers are not consulted) and never falls through to the
-  // model-name swap branch. Any other single-segment value keeps the legacy
-  // semantics below.
+  // resolution branches below. Any other value runs the resolution below.
   if (String(modelArg).toLowerCase() === "default") return { ...parent.provider }
   const providers = parent.config?.providersList ?? []
   const withKey = (p) => (p.apiKey?.trim() ? { ...p, apiKey: p.apiKey.trim() } : { ...p })
-  if (modelArg.includes(":")) {
-    const [pname, mname] = modelArg.split(":")
+  // 首冒号分割（2026-10-09 清除批）：多冒号模型名不截断——`a:b:c` ⇒ provider `a` ∥ model `b:c`。
+  const sep = modelArg.indexOf(":")
+  if (sep >= 0) {
+    const pname = modelArg.slice(0, sep)
+    const mname = modelArg.slice(sep + 1)
     const p = providers.find((x) => x.name === pname)
     if (!p) throw new Error(`subagent model: unknown provider "${pname}" (available: ${providers.map((x) => x.name).join(", ") || "none"})`)
-    return { ...withKey(p), model: mname || p.model }
+    // 空 mname 一律拒（2026-10-09 清除批）：渠道不携模型，无渠道级 model 可回落。
+    if (!mname) throw new Error(`subagent model: "${modelArg}" — model part is empty (expected provider:model)`)
+    return { ...withKey(p), model: mname }
   }
   const byName = providers.find((x) => x.name === modelArg)
-  // F-2c (MODEL-400-FIX)：裸渠道名克隆须重派生 model——渠道裸克隆会丢 model 键 → 无 model 请求
-  // → serde 400。MODEL-SELECTION v2（M3④）：取渠道默认模型（`provider.model` 单值——2026-09-10
-  // 起；老 models[] 首候选形态已退场）；无默认模型 → 主 provider 的 model 兜底（T28）。
-  if (byName) return { ...withKey(byName), model: byName.model ?? parent.provider?.model }
+  // 2026-10-09 清除批（PROVIDER.md §6.16 M3）：渠道单值模型退场——裸渠名无从派生 model，
+  // 一律拒（不回落任何渠道级 model）。
+  if (byName) throw new Error("渠道无默认模型，请用 provider:model")
   return { ...parent.provider, model: modelArg }
 }
 
@@ -366,6 +375,8 @@ export async function injectAsyncResult(agent, entry) {
   // #9：后台 bash 任务族（role="bg"）单列——专用注入器（状态行 + 尾截 + 全量在 log）；
   // 本函为 digest 注入单点族成员，消费面（run-start pending / 端壳残余注入）零改。
   if (entry.role === "bg") return injectBgResult(agent, entry)
+  // 批 browser-async-fix：后台浏览器动作族（role="browser"）同式单列（摘要文法 = ack 族同源）。
+  if (entry.role === "browser") return injectBrowserResult(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 随行）。首条豁免
@@ -394,10 +405,15 @@ export async function injectAsyncResult(agent, entry) {
     role: "user",
     content: label,
   })
+  // #949：评审族投递水印落点（响应表取件下界 = 投递刻下标；非评审族零写）。
+  if (entry.role === "advisor") noteReviewDelivered(agent, entry.run)
   // §6.9 D-SD5 终态墓碑：本函数是全部自动注入路径的共享形态（回合尾 collect + 挂起
-  // digest 首行注入）——注入即消费（调用方随即从容器移除）——dependsOn 引用该 id 的
-  // 后续 spawn 视为已满足（T-SD14 消费终态语义——AGENT-LOOP-SUBAGENT.md §6.7.5 后 check 消费路径删除，本自动
-  // 通道为唯一消费方；error 条目记 failed——依赖取消/失败分支照旧，不误标成功）。
+  // digest 首行注入）——注入即消费（墓碑落注入时点——依赖满足判据不随销账后移）——容器侧：
+  // 会话态（`_daDelivered`）注入后**不随即从容器移除**（留容器至销账 / 升级；移除 =
+  // `accountDigestRound` 的 splice，§6.31），fallback 面照旧（缺省条取尽离容器——先离容后注入；
+  // `_daDelivered` 条同判据跳过且留容器）——
+  // dependsOn 引用该 id 的后续 spawn 视为已满足（T-SD14 消费终态语义——AGENT-LOOP-SUBAGENT.md §6.7.5 后 check
+  // 消费路径删除，本自动通道为唯一消费方；error 条目记 failed——依赖取消/失败分支照旧，不误标成功）。
   writeTombstone(agent, entry.id, entry.error != null ? "failed" : "consumed", entry.role)
 }
 

package/agent-tools/subagent-panel.mjs

@@ -257,7 +257,8 @@ export function executePanelAction(args, ctx) {
     if (b.status === "running") {
       out.elapsedSec = b.startedAt ? Math.max(0, Math.floor((Date.now() - b.startedAt) / 1000)) : 0
     } else if (b.status === "awaitingDigest") {
-      // 读时交叉（round1 #3）：pending/池均无对应 = 报告已消化（注入即从两者移除）——
+      // 读时交叉（round1 #3）：pending/池均无对应 = 报告已消化（fallback 面注入即从两者移除；
+      // 会话面注入后不随即移除——留容器至销账 / 升级，移除 = `accountDigestRound` 的 splice；§6.31）——
       // 块驻留 = 状态滞后——digested:true（freeze 候选——模型可定位异常块）。
       // ASYNC-RESULT-CONTAINER.md D2：pending 单容器参与比对（四族统一）。
       // #748：consult 子块按消费判据（会话在跑 ∥ 会话条目在 pending ⇒ 未消化）——与门控同源。

package/agent-tools/subagent-scheduler.mjs

@@ -397,14 +397,15 @@ export function maybeRefillAsync(parent) {
  * 域 = 进程内（不做槽持久化——reload 后池清块消失，新进程从 1 无冲突——设计范围边界）。
  * spawn（subagent-spawn.mjs async 分支）、escalate（escalate-async.mjs）、async-advisor
  * 池（advisor-async.mjs——§6.10 跨池共号）、**后台 bash 任务池**（bash-async.mjs——#9：
- * `_bgTasks` 同入扫描域——VSC 形计数器不随 run 存活，缺此扫描会与在途 bg 条目撞号）共用；
+ * `_bgTasks` 同入扫描域——VSC 形计数器不随 run 存活，缺此扫描会与在途 bg 条目撞号）、
+ * **后台浏览器动作池**（browser-async.mjs——批 browser-async-fix：`_browserTasks` 同入）共用；
  * executeAsyncSpawn 直读 counter（分配与
  * 消费同步——无 await 间隙）。CLI 两池键均为字符串（set(String(id))——解析分支防御保留）。
  * @returns {number} 全池唯一的下一 id（单调——进程内）
  */
 export function nextSubagentId(parent) {
   let poolMax = 0
-  for (const pool of [carrierField(parent, "_asyncSubagents"), carrierField(parent, "_asyncAdvisors"), carrierField(parent, "_bgTasks")]) {
+  for (const pool of [carrierField(parent, "_asyncSubagents"), carrierField(parent, "_asyncAdvisors"), carrierField(parent, "_bgTasks"), carrierField(parent, "_browserTasks")]) {
     if (!pool || pool.size === 0) continue
     for (const k of pool.keys()) {
       const n = typeof k === "number" ? k : Number.parseInt(k, 10)
@@ -426,7 +427,8 @@ export function nextSubagentId(parent) {
  * nextSubagentId ⇒ 令牌缺位/错号 ⇒ 抛错——防直读陈旧 counter 的静默覆写），断言
  * 通过即置 `undefined`（一次性——同一令牌跨站点复用第二消费必抛）。
  * 调用点：executeAsyncSpawn（subagent-run.mjs）· launchEscalateAsync（escalate-async.mjs）·
- * launchAsyncAdvisor（advisor-async.mjs）——site = 站点名（错误文案定位面）。
+ * launchAsyncAdvisor（advisor-async.mjs）· launchBrowserTask（browser-async.mjs——批 browser-async-fix
+ * 第四站点）——site = 站点名（错误文案定位面）。
  */
 export function consumeSubagentToken(parent, id, site, role) {
   if (parent?._lastSubagentId !== id) {
@@ -436,9 +438,10 @@ export function consumeSubagentToken(parent, id, site, role) {
 }
 
 /**
- * ED-5（§6.21）入池键守卫——三入池点同族：`set(String(id))` 前断言键不存在；命中 =
+ * ED-5（§6.21）入池键守卫——四入池点同族：`set(String(id))` 前断言键不存在；命中 =
  * 覆写（静默丢报告 + status/cancel 错址）⇒ 抛错。调用点：子代理池（subagent-run.mjs）·
- * escalate（escalate-async.mjs）· advisor 池（advisor-async.mjs）。
+ * escalate（escalate-async.mjs）· advisor 池（advisor-async.mjs）· browser 池（browser-async.mjs——
+ * 批 browser-async-fix 同族实例）。
  */
 export function assertPoolKeyFree(pool, id, role) {
   if (pool.has(String(id))) {

package/agent-tools/subagent-spawn.mjs

@@ -20,7 +20,7 @@ import { allocRelay, wrapChildCallbacks, relayPrefixOf } from "../agent/spawn-ch
 // TUI-OOM-ROOTCAUSE（AGENT-LOOP.md §6.15）：子代理人读线窗口常量单源（store 零依赖）。
 import { RECORD_WINDOW_MESSAGES } from "../session-store.mjs"
 import { validateDesignToken } from "./advisor.mjs"
-import { tokenExpired, removeDesignTokenSlot, reconcileEngTokensFromSlot, persistEngTokens } from "../token-ttl.mjs"
+import { tokenExpired, removeDesignTokenSlot, reconcileEngTokensFromSlot } from "../token-ttl.mjs"
 import { resolveChildProvider, buildChildRunOpts, enqueueAsk } from "./subagent-async.mjs"
 import { nextSubagentId } from "./subagent-scheduler.mjs"
 import {
@@ -50,7 +50,7 @@ function logBatchDocRefs(parent, role, task, boundAbs) {
   const cwd = parent?.cwd ?? process.cwd()
   const text = typeof task === "string" ? task : ""
   const key = (p) => (process.platform === "win32" ? p.toLowerCase() : p)
-  const bases = batchDocBases(cwd) // 歧义锚 ⇒ 候选项目基底并集（#828——入基底判据覆盖面随之对齐）
+  const bases = batchDocBases(cwd) // 歧义锚 ⇒ 候选项目基底并集（#828——入基底判据覆盖范围随之对齐）
   const seen = new Set()
   for (const m of text.matchAll(MD_PATH_TOKEN)) {
     const token = m[0]
@@ -125,54 +125,14 @@ export function resolveDesignSlot(parent, designIdArg) {
 
 /**
  * consume-design 动作执行器（2026-09-07 token 链终消费制——ENGINEERING-MODE.md §2.6 F1）：
- * 父侧验收核销时显式调用——读槽值 → removeDesignTokenSlot（token-ttl.mjs——移除该
- * designId 槽）→ 消费后同 designId 再 spawn = resolveDesignSlot not found 机械拒。调用
- * 形态定死（评审 #3）：参数 designId（单设计会话可省略——FR3 spawn 同款语义）；未知
- * designId 与重复消费同款 no-op 提示（幂等——不报错）。DESIGN-TOKEN-SETTLEMENT D3
- * （2026-09-08）：单值镜像 `_engDesignToken` 已退役——无镜像兼容值清/兜底读（AC3）。
- * consume 落盘对称（2026-09-08 D1 段 + AC7）：删内存槽后当场 persistEngTokens 同步
- * 落盘删除（旧台账不留盘——防 D2 门禁 miss 回读复活已消费 token）；落盘失败回滚
- * 内存槽 + 抛错（不留半消费态，可重试——D1 评审 #1 同款失败语义）。
- * dispatch 分类（评审 #7d）：非只读控制动作——depth-0 + 工程模式
- * 限定（受限变体门在 subagent.mjs 分流处；本器自持工程模式门）——planMode 拒绝
- * （dispatch 不豁免）——不入批审批分组（dispatch 免审直行——无文件写）。
+ * 父侧验收核销时显式调用——读槽值 → removeDesignTokenSlot（移除该 designId 槽）→ 消费后同
+ * designId 再 spawn = resolveDesignSlot not found 机械拒；落盘失败回滚内存槽 + 抛错
+ * （不留半消费态，可重试——D1 评审 #1 同款失败语义）。
+ * 2026-10-07 批 ledger-tool（#927 并入）：选择器扩展（designIds / expired / olderThanDays——
+ * 恰一，fail-closed）+ 清点面 `design-slots` 落 `./design-slots.mjs`（清点 / 批量选择 / 消费核
+ * 单源迁入——单枚形态拒文 / 回执逐字不变）；本处仅保本档 import 面（subagent.mjs / 既有消费点零改）。
  */
-export function executeConsumeDesignAction(args, ctx) {
-  const parent = ctx.agent
-  if (!parent?.config?.agent?.engineering) {
-    throw new Error("Engineering mode is not active — consume-design applies only to engineering-mode design tokens (spawn 同门).")
-  }
-  const designId = args?.designId ? String(args.designId) : undefined
-  const slots = parent?._engDesignTokens
-  const hasSlots = slots instanceof Map && slots.size > 0
-  // 多槽缺 designId → 拒（spawn 同款语义——不误消费任一槽）
-  if (!designId && hasSlots && slots.size > 1) {
-    throw new Error(`consume-design: Multiple approved designs in this session (${slots.size}) — pass the designId parameter (echoed with each token) to choose which design to close out.`)
-  }
-  // 读槽值：给定 designId → 精确槽（未知/已消费 → undefined）；缺省 → 唯一槽
-  let token = null
-  if (designId && hasSlots) token = slots.get(designId) ?? null
-  else if (!designId && hasSlots) token = [...slots.values()][0]
-  // 未知 designId / 已消费 / 无任何槽 → 幂等 no-op 提示（不报错——评审 #3 定死）
-  if (!token) {
-    return `consume-design: no live slot${designId ? ` for designId ${designId}` : ""} (already consumed or never issued) — idempotent no-op, nothing changed.`
-  }
-  // consume 落盘对称（DESIGN-TOKEN-SETTLEMENT D1 段 + AC7——交付 🔴 复活洞修复）：
-  // 删内存槽后当场同步落盘删除（D1 同款 persistEngTokens——空 Map → 槽文件
-  // engDesignTokens 字段删除，旧台账不留盘）。否则消费→回合尾 saveSession 窗口内
-  // spawn 门禁 miss 回读（D2）会从盘上复活已消费 token。
-  const slotId = designId ?? [...slots.keys()][0]
-  removeDesignTokenSlot(parent, designId, token)
-  try {
-    persistEngTokens(parent)
-  } catch (e) {
-    // 落盘失败 → 回滚内存槽 + 抛错（不留半消费态——盘上仍有旧台账时消费不得报
-    // 成功；可重试——D1 评审 #1 settle 同款失败语义）
-    if (slotId) parent._engDesignTokens.set(slotId, token)
-    throw new Error(`consume-design: the slot was removed in memory but could NOT be durably deleted from the slot file (${e.message}) — the slot is restored in memory; retry consume-design.`)
-  }
-  return `design slot consumed — designId ${designId ?? "(single-design session)"} is closed out; a further eng-coder spawn for this design is mechanically rejected, and any new work (including deviation fixes) requires a fresh advisor(type='design') review and token.`
-}
+export { executeConsumeDesignAction } from "./design-slots.mjs"
 
 // ── spawn 调度参数准入（AGENT-LOOP-SUBAGENT.md §6.9 D-SD1/D-SD3）────────────
 // files/dependsOn 声明即契约（v1：不做任务书文本自动解析——不可靠）。缺省（两者皆
@@ -239,16 +199,27 @@ export function buildSpawnChild(parent, ctx, args, role, wantAsync, files, depen
   // 路径语义照 `files` 先例：cwd 相对或绝对均可，`\` 归一为 `/`；解析序单源 = §4.15（cwd → 项目根 →
   // 逐基底，读面取首个可读）——cwd 非项目根时根相对串不再必拒（BR-29/BR-33）。错误文案带
   // **实际角色名**（§2.15 越界文案参数化——designer 撞门时不误导）与逐字不可读后缀。
+  // §4.16（2026-10-09）：coder（普通模式）**可选**携 `batchDoc`——非强制（「spawn 强制 batchDoc」=
+  // 工程专属、不移植）；传则须可读（同评审面判据）⇒ `child._batchDoc` 绑定 §5 记录通道；
+  // 未携 ⇒ 不绑定、照常 spawn。
   let batchDocAbs = null
   if (role === "eng-coder" || role === "eng-designer") {
     const given = typeof args.batchDoc === "string" ? args.batchDoc.trim() : ""
     const refusal = (suffix = "") => new Error(
-      `batchDoc is required for role='${role}' — pass the batch record path (docs/batches/<batch>-<topic>.md); spawn refused without it.` + suffix)
+      `batchDoc is required for role='${role}' — pass the batch record path (e.g. <repo>/docs/batches/<batch>-<topic>.md; relative paths resolve against the session cwd first, then candidate project roots — or absolute); spawn refused without it.` + suffix)
     if (!given) throw refusal()
     batchDocAbs = resolveBatchReadPath(parent.cwd ?? process.cwd(), given)
     if (!batchDocAbs) throw refusal(" (given path is not a readable file)")
     // #309 形三：任务书中的他批批次档引用观测留痕（不阻断——放行不受影响）。
     logBatchDocRefs(parent, role, args.task, batchDocAbs)
+  } else if (role === "coder") {
+    const given = typeof args.batchDoc === "string" ? args.batchDoc.trim() : ""
+    if (given) {
+      batchDocAbs = resolveBatchReadPath(parent.cwd ?? process.cwd(), given)
+      if (!batchDocAbs) {
+        throw new Error("batchDoc for role='coder' — pass the batch record path (e.g. <repo>/docs/batches/<batch>-<topic>.md; relative paths resolve against the session cwd first, then candidate project roots — or absolute); when provided it must resolve to a readable file (omit batchDoc to spawn without the §5 record-write binding).")
+      }
+    }
   }
 
   // M5 F2（ENGINEERING-MODE-V2-MODULE-DELEGATION §2.2）：任务书六强制字段门——
@@ -344,10 +315,12 @@ export function buildSpawnChild(parent, ctx, args, role, wantAsync, files, depen
   // 每个 child 原先各自一份永不压缩的 _fullHistory（勘察 C2 乘数面）。
   child._historyWindow = RECORD_WINDOW_MESSAGES
 
-  // BATCH-RECORD.md §2 批次档段写入通道绑定（第 4 批）：工程角色（eng-coder/eng-designer）把批次档
-  // 绝对路径记在 child 上——setup 挂载 `batch` 时读它。无路径参数的工具靠这条
-  // 绑定决定目标档（spawn 门已保证「参数在 + 路径可读」）。
-  if (engineeringRole) child._batchDoc = batchDocAbs
+  // BATCH-RECORD.md §2 批次档段写入通道绑定（第 4 批；§4.16 扩 coder 可选分支）：工程角色
+  // （eng-coder/eng-designer）把批次档绝对路径记在 child 上——setup 挂载 `batch` 时读它；
+  // 携绑定的 coder（普通模式，可选）同点绑定。无路径参数的工具靠这条绑定决定目标档
+  // （spawn 门已保证「参数在 + 路径可读」）。
+  const batchBound = engineeringRole || (role === "coder" && !!batchDocAbs)
+  if (batchBound) child._batchDoc = batchDocAbs
 
   // Token-verified design review → child is authorized to modify files without re-reviewing
   if (role === "eng-coder") child._engDesignReviewed = true
@@ -383,8 +356,9 @@ export function buildSpawnChild(parent, ctx, args, role, wantAsync, files, depen
   // §2.11 第 1 点（FR16 载体 + FR17 铁律 #5 的机械面）：批次档**绝对路径**下发给工程角色
   // （eng-coder 实现 / eng-designer 写稿）——任务文本本身不动（批次档 §2 才是任务书本体；
   // 本行让子代理"拿到本档路径"）。行文不含 summarizeEngTaskBook 的三组段 marker
-  // （Docs involved / Files list / Acceptance criteria）——段匹配不受影响。仅工程角色注入。
-  if (engineeringRole) spawnBlocks.push(`Batch record (batchDoc): ${batchDocAbs}`)
+  // （Docs involved / Files list / Acceptance criteria）——段匹配不受影响。工程角色恒注入；
+  // 携绑定 coder（§4.16）随绑定注入（绑定 coder 要能读到本档）。
+  if (batchBound) spawnBlocks.push(`Batch record (batchDoc): ${batchDocAbs}`)
   // AGENT-LOOP-SUBAGENT.md §6.7.6 D-E2 ③ (round4 #4, T-E13/T-E15): an eng-coder audit spawn's task book is
   // the eng-coder's OWN spawn task — mechanically kept as _engTaskInput by the
   // parent spawn and injected as the D-TS5 A2 mechanical summary (design docs /