@thincoder/core 0.10.4 → 0.10.6

package/agent-tools/manifest.mjs

@@ -0,0 +1,193 @@
+/**
+ * agent-tools/manifest.mjs — `manifest` 工具：M1 项目状态档（`PROJECT-MANIFEST.json`）的
+ * agent 侧读写出口（2026-10-08 · 台账 #1098；权威设计 = `docs/core/design/MANIFEST.md` §2.10）。
+ *
+ * 三动作（KD-M1-38）：
+ *  - `read`  ⇒ `projectView(target)` 五态报明（稳定锚 `state=ok|missing|invalid|ambiguous|no-project`）；
+ *              `ok` 态再 `readManifest(view.root)` 取细节面（`projectView` 面不含 `missingKeys` /
+ *              `unknownKeys`）——**不抛**（缺档报明，非拒）。
+ *  - `init`  ⇒ 缺档建默认档（`initManifest`——内容 = `DEFAULT_MANIFEST`）；**已带档 ⇒ 拒**
+ *              （不覆盖——`initManifest` 本体无覆盖保护，工具面补此闸）。
+ *  - `write` ⇒ **点改**：读现档 → 设节点 → 落盘（`writeManifest` 内先 `validateManifest`——
+ *              编辑结果非法 ⇒ 拒 + 盘零变）；**缺档 ⇒ 拒** + 引导 `init`（写不建档）。
+ *
+ * 写面白名单（判据单源 = `MANIFEST_SCHEMA`——钉死谓词）：`keys` 中**非** `nestedKeys` 父键者
+ * （`version` / `phase` / `promptsLanding` / `codePaths` 整键）+ `nestedKeys` 子键
+ * （`docRoot.*` / `checkConfig.*` / `index.*`（含 `publicRepos`）/ `advisor.*`）；**四族整键写
+ * （传整个对象）⇒ 拒**；白名单外 ⇒ 拒（拼写保护——未知键写盘 = 静默死键，KD-M1-36 问题本体）。
+ * `value` 解析 = 同款口径 `settings.mjs:216-228`（先 `JSON.parse`，失败取字面串；`"null"` ⇒ `null`
+ * ——`docRoot.*` 的「本面无」，KD-M1-37）。
+ *
+ * 目标面（KD-M1-39——判据复用零新解析器）：`read` = `projectView`；`init` / `write` =
+ * `projectRootView`（歧义 ⇒ 拒 + 候选全列——不猜）；`resolveProjectRoot` 对歧义塌缩 `null` 再回落 cwd
+ * ⇒ 写 / 建两动作**不得**直用。
+ *
+ * 写路径复用（零新写路径）：落盘恒经 `writeManifest` / `initManifest`——`writer` 恒显式 `'main'`
+ * （缺省 `'subagent'` = 写门 fail-closed 缺省，KD-M1-3 / AC-M1-5 零改）。
+ *
+ * 报告面随动（KD-M1-40）：本工具**不写** `agent.manifest`（第二值源否——工具目标可为非锚项目）——
+ * 写盘 = 盘面变化，情境行经既有 ③b mtime 门控于下回合采纳（`agent/setup-reminders.mjs`）。
+ */
+import { existsSync } from "node:fs"
+import { join, resolve } from "node:path"
+import { MANIFEST_REL, MANIFEST_SCHEMA, initManifest, projectRootView, projectView, readManifest, writeManifest } from "../manifest.mjs"
+import { DESC } from "../tools/shared.mjs"
+
+/** 拒面统一前缀（设计 §2.10：`manifest <action>: refused — …`）——盘零变类拒绝一律经此抛错。 */
+function refuse(action, reason) {
+  return new Error(`manifest ${action}: refused — ${reason}`)
+}
+
+/** `target` 解析（先例 `eng.mjs:81` 缺省会话锚 ∥ `git.mjs:32-35` 相对形归一）：缺省 = 会话锚
+ *  （`ctx.agent.cwd ?? ctx.cwd ?? process.cwd()`）；显式相对形按会话锚归一（绝对形原样）。 */
+function resolveTarget(args, ctx) {
+  const base = ctx?.agent?.cwd ?? ctx?.cwd ?? process.cwd()
+  return args?.target ? resolve(base, String(args.target)) : resolve(base)
+}
+
+/** 写面白名单谓词（**钉死**——设计 §2.10）：点分路径恰两形——
+ *  ① 单段：`keys` ∩ ∉ `nestedKeys`（= `version` / `phase` / `promptsLanding` / `codePaths` 整键）；
+ *  ② 双段：`nestedKeys[父]` 含子键（四族子键）；其余（四族整键写 / 未知键 / 更深路径）⇒ 拒。
+ *  `Array.isArray` 守卫：原型链名（`__proto__` / `constructor` / `toString` 类）取到非数组 ⇒ 落拒面
+ *  （不得 TypeError 直出——白名单外一律 `refused` 统一前缀）。 */
+function isWritableKey(key) {
+  const segs = String(key).split(".")
+  if (segs.length === 1) return MANIFEST_SCHEMA.keys.includes(segs[0]) && !Object.hasOwn(MANIFEST_SCHEMA.nestedKeys, segs[0])
+  if (segs.length === 2) {
+    const subs = MANIFEST_SCHEMA.nestedKeys[segs[0]]
+    return Array.isArray(subs) && subs.includes(segs[1])
+  }
+  return false
+}
+
+/** `value` 解析（同款口径 = `settings.mjs:216-228`）：先 `JSON.parse`（`"null"` ⇒ `null`；数值 /
+ *  布尔 / 数组皆 JSON 形），失败取字面串（裸串如 `docs/design`）。 */
+function parseValue(raw) {
+  const s = String(raw)
+  try { return JSON.parse(s) } catch { return s }
+}
+
+/** 点分路径设值（自动建中间对象——settings `setKeyPath` 同款；白名单谓词已保父段为已知族）。 */
+function setKeyPath(obj, path, value) {
+  const segs = String(path).split(".")
+  let cur = obj
+  for (let i = 0; i < segs.length - 1; i++) {
+    if (cur[segs[i]] === null || typeof cur[segs[i]] !== "object") cur[segs[i]] = {}
+    cur = cur[segs[i]]
+  }
+  cur[segs[segs.length - 1]] = value
+}
+
+/** 歧义拒文案（候选全列——不猜；init / write 共用）：多候选 = 显式指定 target，机制不代选。 */
+function ambiguousReason(target, candidates) {
+  return `ambiguous target ${target} — ${candidates.length} candidate projects (the mechanism never picks one); pass target explicitly:\n` +
+    candidates.map((c) => `- ${c}`).join("\n")
+}
+
+/** read 动作（五态报明——**不抛**）：`state=` 稳定锚 + 各态附行（ok 细节面 / missing 引导 /
+ *  ambiguous 候选全列 / invalid 错误行）。 */
+function readAction(target) {
+  const view = projectView(target)
+  const lines = [`state=${view.state}`]
+  if (view.path) lines.push(`path=${view.path}`)
+  if (view.state === "ok") {
+    const m = readManifest(view.root) // 细节面：missingKeys / unknownKeys / errors（非空才出）
+    lines.push(`manifest=${JSON.stringify(m.manifest)}`)
+    if (m.missingKeys?.length) lines.push(`missingKeys=${m.missingKeys.join(", ")}`)
+    if (m.unknownKeys?.length) lines.push(`unknownKeys=${m.unknownKeys.join(", ")}`)
+    if (m.errors?.length) lines.push(`errors=${m.errors.join("；")}`)
+  } else if (view.state === "missing") {
+    lines.push(`hint: run manifest action=init to create the default manifest here`)
+  } else if (view.state === "no-project") {
+    lines.push(`hint: no project on the ancestor chain and none below — manifest action=init can create one at the target`)
+  } else if (view.state === "ambiguous") {
+    lines.push(`candidates (${(view.candidates ?? []).length}):`)
+    for (const c of view.candidates ?? []) lines.push(`- ${c}`)
+    lines.push(`hint: pass target explicitly — the mechanism never picks one`)
+  } else if (view.state === "invalid") {
+    if (view.errors?.length) lines.push(`errors=${view.errors.join("；")}`)
+  }
+  return lines.join("\n")
+}
+
+export const manifestTool = {
+  name: "manifest",
+  description: DESC("manifest"),
+  parameters: {
+    type: "object",
+    properties: {
+      action: { type: "string", enum: ["read", "init", "write"], description: "read — current manifest + validation state (five-state anchor, never throws); init — create the default manifest when missing (refused when one already exists); write — point-edit one node (key + value) of an existing manifest" },
+      target: { type: "string", description: "Explicit target directory — defaults to the session anchor; relative paths resolve against it. Ambiguous targets are refused with the full candidate list (never picks one)." },
+      key: { type: "string", description: "(write) Dot path of the node to set — version / phase / promptsLanding / codePaths, or a sub-key of docRoot / checkConfig / index / advisor (e.g. docRoot.design / index.publicRepos / advisor.docMap); whole-object writes of those four families are refused", },
+      value: { type: "string", description: "(write) New value — parsed as JSON first (null / true / 5 / [\"a\"]), otherwise kept as a literal string; \"null\" is the explicit no-such-face for docRoot.<key>" },
+    },
+    required: ["action"],
+  },
+  readonly: false, // 动作级分类（dispatch-gates `isSubagentReadonlyAction`）：read = 只读类；init / write 保持侧效门
+  async execute(args, ctx) {
+    const action = args?.action
+    if (!["read", "init", "write"].includes(action)) {
+      throw new Error(`manifest: action must be one of read/init/write — got ${JSON.stringify(action)}`)
+    }
+    const target = resolveTarget(args, ctx)
+
+    if (action === "read") return readAction(target)
+
+    // init / write：目标面 = `projectRootView`（歧义直读形——不猜；KD-M1-39）
+    const rootView = projectRootView(target)
+    if (rootView.state === "ambiguous") {
+      throw refuse(action, ambiguousReason(target, rootView.candidates))
+    }
+
+    if (action === "init") {
+      const root = rootView.state === "ok" ? rootView.root : target // 梯⑤（无项目）⇒ 落点 = target 自身
+      const file = join(root, MANIFEST_REL)
+      if (existsSync(file)) {
+        throw refuse("init", `${file} already carries a manifest — init never overwrites (use action=write to edit it)`)
+      }
+      try {
+        initManifest(root, { writer: "main" }) // 落盘恒经写门（writer 闸 + 校验前闸——零新写路径）
+      } catch (e) {
+        throw refuse("init", `could not write the default manifest at ${file} — ${e?.message ?? String(e)}`)
+      }
+      return `manifest init: created default manifest (DEFAULT_MANIFEST)\npath=${file}`
+    }
+
+    // write：缺档 ⇒ 拒 + 引导 init（写不建档——多写权面唯一的建档动作 = init）
+    if (rootView.state === "none") {
+      throw refuse("write", `no project at ${target} — write requires an existing ${MANIFEST_REL}; run manifest action=init first (write never creates one)`)
+    }
+    const root = rootView.root
+    const file = join(root, MANIFEST_REL)
+    const key = args?.key
+    if (!key) throw new Error("manifest write: key is required (dot path, e.g. docRoot.design)")
+    if (args?.value === undefined) throw new Error("manifest write: value is required (JSON-parsed first, otherwise a literal string)")
+    if (!isWritableKey(key)) {
+      throw refuse("write", `key "${key}" is not writable — writable nodes: version / phase / promptsLanding / codePaths + sub-keys of docRoot / checkConfig / index / advisor (whole-object writes of the four families are refused)`)
+    }
+    let current
+    try {
+      current = readManifest(root)
+    } catch (e) {
+      throw refuse("write", `could not read ${file} — ${e?.message ?? String(e)}`)
+    }
+    if (!current.ok) {
+      if (current.reason === "missing") {
+        throw refuse("write", `${file} does not exist — run manifest action=init first (write never creates one)`)
+      }
+      if (!current.manifest) {
+        throw refuse("write", `${file} is not editable (fail-closed): ${(current.errors ?? []).join("；")}`)
+      }
+      // 现档可解析但校验非法：照常点改——编辑结果仍经落盘前 `validateManifest`（非法 ⇒ 拒 + 盘零变）
+    }
+    const value = parseValue(args.value)
+    const manifest = current.manifest
+    setKeyPath(manifest, String(key), value)
+    try {
+      writeManifest(root, manifest, { writer: "main" }) // 落盘前 validateManifest（编辑结果非法 ⇒ 拒 + 盘零变）
+    } catch (e) {
+      throw refuse("write", `the edited manifest fails the pre-write validation (disk unchanged) — ${e?.message ?? String(e)}`)
+    }
+    return `manifest write: set ${key} = ${JSON.stringify(value)}\npath=${file}`
+  },
+}

package/agent-tools/parent-channel.mjs

@@ -20,7 +20,7 @@
  *   生命周期与子代理生命周期**解耦**（settle / cancel 不迁移、不清队列——F3）。
  * - 父侧唤醒 = ask 入队尾调 `wakeAsyncWaiters(parent)`（**同步**，零 await；`note` 不唤醒）——
  *   零新字段 / 零新容器 / 零新注册：等待栓数组由挂起驱动注册，非挂起期数组空 ⇒ no-op。
- * - 父侧消费 = `drainChildUpstream(agent)`（`thincoder-core/agent.mjs` 循环头单点，紧邻
+ * - 父侧消费 = `drainChildUpstream(agent)`（`thincoder-core/agent/turn-loop.mjs` 循环头单点，紧邻
  *   `consumeInjected?.(agent)`——同址反向）：全部 pending **合并一条** user 消息（`pushReal`
  *   非 transient——事务性事件落盘，D-UC5），每条附结束注脚（已 settle / 已 cancel 两形态；
  *   其余态不附——不臆断）。
@@ -151,10 +151,13 @@ function endNote(agent, entry) {
   return ""
 }
 
+/** kind → 投递标识（单点渲染——机读面 / 日志留原 kind；用户 2026-10-06 裁定逐字）。 */
+const KIND_MARK = { ask: "[上抛·待裁]", note: "[上抛·知会]" }
+
 /**
- * 父侧消费点（回合边界单点——`agent.mjs` 循环头；空队列 no-op = 零历史变更、零开销）：
+ * 父侧消费点（回合边界单点——`agent/turn-loop.mjs` 循环头；空队列 no-op = 零历史变更、零开销）：
  * 全部 pending 消息**合并为一条** user 消息注入（`pushReal`——不带 `transient`，事件落盘），
- * 按入队序逐条列示（来源 `role#id` + `kind` + message（`escapeXml`）+ 结束注脚）。
+ * 按入队序逐条列示（来源 `role#id` + **kind 标识**（`ask` ⇒ `[上抛·待裁]` ∥ `note` ⇒ `[上抛·知会]`）+ message（`escapeXml`）+ 结束注脚）。
  * @param {object} agent 父（消费方）agent 形态。
  * @returns {number} 本次消费条目数（0 = 空队列 no-op）。
  */
@@ -168,7 +171,7 @@ export function drainChildUpstream(agent) {
       + "Answer with subagent action:'send' (id + message) if the decision is yours; an unanswered ask means that child skips the part and reports it as not done.]"
     : `[System reminder: in-flight message from your subagent ${entries[0].from} — it keeps working on the unaffected parts. `
       + "Answer with subagent action:'send' (id + message) if the decision is yours; an unanswered ask means the child skips that part and reports it as not done.]"
-  const rows = entries.map((e) => `${many ? "- " : ""}${e.kind} · ${e.from}: ${escapeXml(e.message)}${endNote(agent, e)}`)
+  const rows = entries.map((e) => `${many ? "- " : ""}${KIND_MARK[e.kind] ?? e.kind} · ${e.from}: ${escapeXml(e.message)}${endNote(agent, e)}`)
   pushReal(agent, { role: "user", content: [header, ...rows].join("\n") })
   return entries.length
 }

package/agent-tools/review-facts.mjs

@@ -6,7 +6,7 @@
  *  - 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` 文档解析四分支单源。
  */
 import { existsSync, statSync } from "node:fs"
 import { dirname, join, resolve } from "node:path"
@@ -50,23 +50,23 @@ function readableFile(abs) {
   try { return existsSync(abs) && statSync(abs).isFile() } catch { return false }
 }
 
-/** 会话根集（腿①判据集——既有 advisor 面 `resolveReviewTargetPaths(agent)` 目录形态的函数式封装；档内私有——零外部消费面）。 */
+/** 会话根集（分支①判据集——既有 advisor 面 `resolveReviewTargetPaths(agent)` 目录形态的函数式封装；档内私有——零外部消费面）。 */
 function sessionReviewRoots(cwd) {
   return resolveReviewRootsFor(cwd ?? process.cwd())
 }
 
 /**
- * **文档解析四腿单源**（2026-10-04 · 批档 §2.2 A 本体）：逐文档
- *   腿① 零变：normAbs(doc, cwd) 落会话根集 ⇒ 受理；腿② 零变：所属项目根集命中 ⇒ 受理；
- *   腿③ 根治面：相对形 ∧ 前两腿未中 ⇒ 候选底座逐个试探（底座 = projectRootView(cwd) 现行集 ＋
+ * **文档解析四分支单源**（2026-10-04 · 批档 §2.2 A 本体）：逐文档
+ *   分支① 零变：normAbs(doc, cwd) 落会话根集 ⇒ 受理；分支② 零变：所属项目根集命中 ⇒ 受理；
+ *   分支③ 根治面：相对形 ∧ 前两分支未中 ⇒ 候选底座逐个试探（底座 = projectRootView(cwd) 现行集 ＋
  *        cwd 祖先链全量目录——自父目录起至盘根、最近→远、去重、现行集在前）——resolve(c, doc)
- *        所属项目根集命中 = 结构命中；绝对形不进本腿（未中 = 真越界，无候选可试）；
- *   腿④ 歧义归一（KD-3）：结构命中 ≥2 ⇒ 可读文件存在性唯一化（batch-paths 读面「首个可读」
+ *        所属项目根集命中 = 结构命中；绝对形不进本分支（未中 = 真越界，无候选可试）；
+ *   分支④ 歧义归一（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 文案候选提示同源）。
+ *   （fail-closed 首拒——消费面拒发即止）；candidates = 分支③候选集（B 文案候选提示同源）。
  *   非字符串 / 空白串项**静默跳过**（同 docSetKey 既有过滤语义——不进 resolved/invalid）。
  */
 export function resolveReviewDocPaths(documents, cwd) {
@@ -97,11 +97,11 @@ export function resolveReviewDocPaths(documents, cwd) {
     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 旧面）。
+    // 分支① 会话根集 / 分支② 所属项目根集（既有行为零变——判定序同 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——绝对形未中 = 真越界，无候选可试）。
+    // 分支③ 候选项目根试探（相对形 only——绝对形未中 = 真越界，无候选可试）。
     let hits = []
     if (!isAbs && candidates.length > 0) {
       for (const c of candidates) {
@@ -110,8 +110,8 @@ export function resolveReviewDocPaths(documents, cwd) {
         if (cOwner && under(t, ownRoots(cOwner))) hits.push(t)
       }
     }
-    // 腿④ 歧义归一：结构命中 ≥2 ⇒ 可读文件存在性唯一化；恰 1 命中 ⇒ 受理（存在性仅作
-    // 歧义唯一化判据——单命中无判别力，同腿①声明根集受理面一致不查存在）。
+    // 分支④ 歧义归一：结构命中 ≥2 ⇒ 可读文件存在性唯一化；恰 1 命中 ⇒ 受理（存在性仅作
+    // 歧义唯一化判据——单命中无判别力，同分支①声明根集受理面一致不查存在）。
     if (hits.length >= 2) {
       const readable = hits.filter((h) => readableFile(h))
       if (readable.length === 1) { resolved.set(doc, readable[0]); continue }
@@ -141,7 +141,7 @@ export function noteReviewDelivered(agent, run) {
   run.historyAnchorIdx = Array.isArray(agent?.history) ? agent.history.length : 0
 }
 
-/** 腿③候选底座（`MANIFEST.md` §2.5「路径归一增量」族第四笔 · 2026-10-05 · #945）：现行
+/** 分支③候选底座（`MANIFEST.md` §2.5「路径归一增量」族第四笔 · 2026-10-05 · #945）：现行
  *  `projectRootView(cwd)` 集（ok → [root]；ambiguous → candidates 按名序；none → 空集）＋
  *  cwd 祖先链全量目录（自父目录起至盘根、最近→远、去重、现行集在前）——容器相对形在子仓锚下
  *  可解析；受理判据（目标解析位最近 manifest 声明面）∥ 围栏 ∥ 可读唯一化 ∥ fail-closed 歧义零改。 */

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-async.mjs

@@ -38,6 +38,8 @@ import { getAsyncPool, tombstoneOf, writeTombstone } from "./async-settle.mjs"
 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 续接）。
@@ -131,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) {
@@ -145,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 }
 }
 
@@ -368,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 随行）。首条豁免

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,6 +199,9 @@ 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() : ""
@@ -249,6 +212,14 @@ export function buildSpawnChild(parent, ctx, args, role, wantAsync, files, depen
     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 /