@thincoder/core 0.10.3 → 0.10.5

package/agent-tools/batch-skeleton.mjs

@@ -13,8 +13,8 @@
  * 段标题定位（sectionHeaderRe）同住本档：append 段尾定位与 status/close 段内状态行定位
  * 消费**同一个段头正则**——`## §N` 形态单源（`## §20` 不误命中 §2）。
  *
- * F11-C（本批）：**骨架死占位枚举**（TEMPLATE_PLACEHOLDERS）与残留扫描纯函数
- * （findPlaceholderResidue）同住本档——与骨架模板共址即判据不会与模板脱节。
+ * F11-C：**骨架死占位枚举**（TEMPLATE_PLACEHOLDERS）与残留扫描纯函数（findPlaceholderResidue——
+ * 判定域 = 档头结构行，2026-10-05 判据收正）同住本档——与骨架模板共址即判据不会与模板脱节。
  */
 /**
  * 段标题定位（`## §N` 独立标题——`## §20` 不误命中 §2）。
@@ -29,7 +29,7 @@ export const sectionHeaderRe = (seg) => new RegExp(`^## §${seg}(?=\\s|$)`, "m")
  * 内嵌另一冻结词的值（含「进行中…已收口」双词 ⇒ 已收口优先误冻结——2026-09-20 词面纪律）。
  * emoji / 括注 / 日期后缀容忍（**读侧** gate 判定 = 子串包含，同 gate——写入面 value 谓词
  * 自本批起收紧为「剥装饰白名单后余核 = 关键词」，见 batch-lifecycle.mjs）；
- * 全词表并集 = 各段项去重集合（note 字段零命中的判据面——括注永不误触 gate）。
+ * 全词表并集 = 各段项去重集合（note 字段零命中的判据——括注永不误触 gate）。
  */
 export const STATUS_WORDS = Object.freeze({
   1: Object.freeze({ open: "进行中", closed: "已收口" }),
@@ -39,16 +39,29 @@ export const STATUS_WORDS = Object.freeze({
 })
 
 /** 身份 → 可写段号（append 段白名单的**子代理面**——原 batch-segment.mjs 逐字迁移；主 agent
- *  的 depth-0 白名单（append = §1/§4/§6 · status = §1——轮 2 #3 裁定②）由身份判据在
- *  batch.mjs / batch-lifecycle.mjs 分支，不经本表。旧 batch-segment.mjs 导出面等价保持——
- *  本符号经 batch.mjs re-export（过渡 shim 面零触）。 */
+ *  的 depth-0 白名单（模式感知——工程 §1/§4/§6 · §1 ∥ 普通 §1/§2/§4/§5/§6 · §1/§2/§5，§4.16）
+ *  由身份判据在 batch.mjs / batch-lifecycle.mjs 分支，不经本表。旧 batch-segment.mjs 导出面等价
+ *  保持——本符号经 batch.mjs re-export（过渡 shim 面零触）。**表零字面改**——普通模式另立增表
+ *  `SEGMENT_BY_ROLE_NORMAL`（合并查只在普通模式分支）；工程面「逐字不变」判据据此成立。 */
 export const SEGMENT_BY_ROLE = { "eng-designer": 2, "eng-coder": 5 }
 
+/** 普通模式增表（§4.16——**合并查只在普通模式分支**，工程模式分支不消费本表）：coder 承办 ⇒ §5
+ *  实施记录（可选绑定自写——未绑定由主 agent 代记、行内注明来源）。 */
+export const SEGMENT_BY_ROLE_NORMAL = { "coder": 5 }
+
+/** depth-0 段白名单（§4.16——**模式键两集**；工程面判定字面逐字保持、普通面新增）：
+ *  append：工程 = §1/§4/§6 ∥ 普通 = §1/§2/§4/§5/§6（§2 = 设计师席并入主 agent；§5 = 直做实施记录）；
+ *  status：工程 = §1 ∥ 普通 = §1/§2/§5（写域仍「调用者自己段」；`segment` 缺省 = §1）。 */
+export const DEPTH0_SEGMENTS = Object.freeze({
+  append: Object.freeze({ engineering: Object.freeze([1, 4, 6]), normal: Object.freeze([1, 2, 4, 5, 6]) }),
+  status: Object.freeze({ engineering: Object.freeze([1]), normal: Object.freeze([1, 2, 5]) }),
+})
+
 /** §1 状态行前缀形态（`**状态行**：` 独立行——表格行 / 块引用行不命中；判定只认关键字）。 */
 export const STATUS_LINE_RE = /^\s*\*\*状态行\*\*[：:]\s*(.*)$/
 
 /**
- * 骨架死占位**枚举单源**（F11-C 判据面——create 骨架产出过的全部死占位字面）：
+ * 骨架死占位**枚举单源**（F11-C 判据——create 骨架产出过的全部死占位字面）：
  *  - `#<编号>` / `<板块>` = 现行骨架仍在产出的两处（台账行——填充人 = 主 agent，时点 =
  *    建档后、本档首个 append/status 之前）；
  *  - `<BATCH-ID>` / `<讨论来源>` = 改形**删除**的两处旧占位（create 不再产出；旧档残留同判）。
@@ -58,46 +71,42 @@ export const STATUS_LINE_RE = /^\s*\*\*状态行\*\*[：:]\s*(.*)$/
  */
 export const TEMPLATE_PLACEHOLDERS = ["<BATCH-ID>", "<讨论来源>", "#<编号>", "<板块>"]
 
+/** 档头结构行值形（骨架三类——标题行 `# …` / 编制行 `> 编制` / 台账行 `> 台账`）：判据可辨性收正
+ *  （`TOOLS.md` §6.20）后只有这三类行参与死占位判定；骨架↔结构行不变量 = `batchSkeleton` 产出中
+ *  枚举字面 ⊆ 本三类行（骨架改形与判据同拍——结构行外新增占位 = 静默漏检）。 */
+const HEADER_STRUCTURAL_RE = [/^#\s/, /^>\s*编制/, /^>\s*台账/]
+
 /**
  * 死占位残留扫描（F11-C——append/status 落笔前的机检；**纯函数 · 零 fs**）。
- * 判定域 = **档头**（档首行起至首个 `## §N` 段头前）+ **本次目标段**段内——他段模板占位不归
- * 本段作者管（一段一作者：§2 作者扫 §5 的占位 = 越权）。
+ * 判定域 = **档头结构行**（区域 = 档首至首个 `## §N` 段头前；值形 = 骨架三类结构行：标题行
+ * `# …` / 编制行 `> 编制` / 台账行 `> 台账`）——行内出现枚举字面 ⇒ 残留；段体（首段头起）
+ * 任意位置出现字面 = 正文引用 ⇒ **豁免**（引用非未填——2026-10-05 判据可辨性收正，`TOOLS.md`
+ * §6.20；原「档头 + 目标段」全域子串扫描分不清「未填占位」与「正文引用」——本批 §1 首投实害）。
  * @param {string} src — 档全文
- * @param {number|string} seg — 本次目标段号（`2` / `"2"`——同 sectionHeaderRe 消费形）
- * @returns {Array<{line: number, text: string, where: "header"|"section"}>} 残留列表（空 = 无残留）；
- *   `line` = 所在判定域内 1-based 行号（档头域自档首行起 · 段域自 `## §N` 标题行起——便于定位），
- *   `text` = 命中行 trim 原文，`where` = 命中域（档头 / 目标段——错误句标注位置用）
+ * @returns {Array<{line: number, text: string}>} 残留列表（空 = 无残留）；
+ *   `line` = 档头域内 1-based 行号（档头域自档首行起——便于定位），`text` = 命中行 trim 原文
  */
-export function findPlaceholderResidue(src, seg) {
-  const out = []
-  const scan = (text, where) => {
-    text.split("\n").forEach((line, i) => {
-      if (TEMPLATE_PLACEHOLDERS.some((ph) => line.includes(ph))) out.push({ line: i + 1, text: line.trim(), where })
-    })
-  }
+export function findPlaceholderResidue(src) {
   const firstSection = /^## §\d/m.exec(src)
-  scan(src.slice(0, firstSection ? firstSection.index : 0), "header")
-  const hdr = sectionHeaderRe(seg).exec(src)
-  if (hdr) {
-    const nextRe = /^## §\d/gm
-    nextRe.lastIndex = hdr.index + hdr[0].length
-    const next = nextRe.exec(src)
-    scan(src.slice(hdr.index, next ? next.index : src.length), "section")
-  }
+  const out = []
+  src.slice(0, firstSection ? firstSection.index : 0).split("\n").forEach((line, i) => {
+    if (!HEADER_STRUCTURAL_RE.some((re) => re.test(line))) return
+    if (TEMPLATE_PLACEHOLDERS.some((ph) => line.includes(ph))) out.push({ line: i + 1, text: line.trim() })
+  })
   return out
 }
 
 /**
- * 占位残留拒绝句（F11-C——append / status 两个挂点共用单源文案；逐行列残留：位置标注 + 行号 + 原文）。
+ * 占位残留拒绝句（F11-C——append / status 两个挂点共用单源文案；逐行列残留：行号 + 原文）。
  * 错误句前缀 = `batch:`（本批新增错误面——与 append 迁移面的 `batch_segment:` 旧面不混）。
- * @param {Array<{line:number,text:string,where:string}>} residues — findPlaceholderResidue 的返回值（非空）
+ * 逐字 = `TOOLS.md` §6.20 拒句表（「or your target section」半句随判定域收正退场）。
+ * @param {Array<{line:number,text:string}>} residues — findPlaceholderResidue 的返回值（非空）
  * @returns {string} 完整拒绝句（调用方 throw new Error(...)）
  */
 export function placeholderResidueError(residues) {
-  const where = (r) => (r.where === "header" ? "档头" : "目标段")
-  const list = residues.map((r) => `  ${where(r)} line ${r.line}: ${r.text}`).join("\n")
-  return "batch: 骨架死占位残留 — the batch record still carries skeleton placeholders (档头 or your target section). " +
-    "Fill them before writing: create ⇒ the main agent fills the header's 台账编号 / 板块 placeholders ⇒ the record's first append/status opens. " +
+  const list = residues.map((r) => `  档头 line ${r.line}: ${r.text}`).join("\n")
+  return "batch: 骨架死占位残留 — the batch record's header still carries skeleton placeholders. " +
+    "Fill them before writing: create with ledger / board fills the 台账 line at creation; otherwise the main agent fills the header by file edit ⇒ the record's first append/status opens. " +
     `Nothing was written. Residue:\n${list}`
 }
 
@@ -177,25 +186,32 @@ export function sectionHasStatusLine(src, seg) {
  * 编制行 + 台账/前情指针行）+ §1 段内**占位状态行**（含 gate 合法关键字「进行中」——建档即过
  * gate；整行不含「已收口」——gate 已收口优先，占位行不得携带冻结词）+ 各段模板子标题占位。
  * 已知实参替换：date / topic / **source** / prev（§4.11 参数面 + F11-B——source 必填、prev 传
- * 入值过幂等剥前缀，归一化在 lifecycle 面）；档头 `#<编号>` / `<板块>` 仍保持占位字面（台账
- * 登记 = 主 agent 既有义务，create 不代建——填充时点 = 建档后、本档首个 append/status 之前）。
+ * 入值过幂等剥前缀，归一化在 lifecycle 面）；`ledger` / `board` = 可选参（2026-10-05 建即填——
+ * 给则台账行实参化、未给保持占位字面；4 参旧调用形输出零变）。档头 `#<编号>` / `<板块>` 占位
+ * 留存时（未给参）由主 agent 文件编辑填（台账登记 = 主 agent 既有义务，create 不代建——填充
+ * 时点 = 建档后、本档首个 append/status 之前）。
  * 本批改形删除（F11-B）：旧 `# …（<BATCH-ID>）` 后缀与 `来源 = <讨论来源>` 占位实参化。
+ * 模式取形（§4.16——普通模式变体**四处替换**、余行逐字同；`mode` 缺省 = "engineering" ⇒
+ * 工程产出逐字不变）：① 汇总行 §2/§5 标签；② `## §2` 段头；③ §2 状态占位句；④ `## §5` 段头。
  */
-export function batchSkeleton({ date, topic, source, prev }) {
+export function batchSkeleton({ date, topic, source, prev, ledger = null, board = null, mode = "engineering" }) {
+  const normal = mode === "normal"
+  const designerSeat = normal ? "主 agent" : "eng-designer" // ① 汇总行 §2 标签 ∥ ② §2 段头
+  const implementerSeat = normal ? "实施者：主 agent ∥ coder" : "eng-coder" // ① 汇总行 §5 标签 ∥ ④ §5 段头
   return [
     `# ${date} · ${topic}`,
-    "> 六段 append-only，一段一作者：§1 讨论（主 agent）· §2 批次任务与设计（eng-designer）· §3 设计评审（评审子代理）· §4 用户批准（主 agent）· §5 实施记录（eng-coder）· §6 验证与收口（父代理）。",
+    `> 六段 append-only，一段一作者：§1 讨论（主 agent）· §2 批次任务与设计（${designerSeat}）· §3 设计评审（评审子代理）· §4 用户批准（主 agent）· §5 实施记录（${implementerSeat}）· §6 验证与收口（父代理）。`,
     `> 编制：主 agent · ${date} · 来源 = ${source}。`,
-    `> 台账 = #<编号>（<板块> · 归批）。前情 = ${prev}。`,
+    `> 台账 = ${ledger ?? "#<编号>"}（${board ?? "<板块>"} · 归批）。前情 = ${prev}。`,
     "## §1 讨论（主 agent）",
     `**状态行**：🔄 ${STATUS_WORDS[1].open}（…）`,
     "<§1 模板占位：本批条目 / 关键判据 / 授权口径>",
-    "## §2 批次任务与设计（eng-designer）",
-    "**状态行**：（eng-designer 写入时更新）",
-    "<§2 模板占位：本批条目（覆盖） / 设计档落点 / 机制设计 / 受影响文件与测试面 / 验收对照 / 关键决策 / 上抛项>",
+    `## §2 批次任务与设计（${designerSeat}）`,
+    `**状态行**：（${normal ? "主 agent" : "eng-designer"} 写入时更新）`, // ③ §2 状态占位句
+    "<§2 模板占位：本批条目（覆盖） / 设计档落点 / 机制设计 / 受影响文件与测试覆盖 / 验收对照 / 关键决策 / 上抛项>",
     "## §3 设计评审（评审子代理）",
     "## §4 用户批准（主 agent）",
-    "## §5 实施记录（eng-coder）",
+    `## §5 实施记录（${implementerSeat}）`,
     "## §6 验证与收口（父代理）",
     "",
   ].join("\n")

package/agent-tools/batch.mjs

@@ -12,9 +12,10 @@
  * eng 子代理 `depth > 0`（`agent._role` 定段）；评审实例 ctx 无 depth 但工具以 `review: true`
  * 绑定。create/close 仅 depth-0 放行；depth-0 的 append/status/close 可选 `path`（D-BR21：
  * 缺省 = findInFlightBatch 取唯一在飞批，0/复数 ⇒ throw）；子代理/评审传 path ⇒ 拒（目标 =
- * spawn/实例注入，语法上写不到别处——运行期门拒）。append 段白名单：depth-0 → §1/§4/§6 ·
- * eng-designer → §2 · 评审 → §3 · eng-coder → §5；status 写域 = 调用者自己段（主 agent 仅 §1
- * ——轮 2 #3 裁定②）。append 迁移面错误串**逐字保持 "batch_segment:" 前缀**（§4.1 全表锚断言）；
+ * spawn/实例注入，语法上写不到别处——运行期门拒）。append 段白名单（**模式感知**——§4.16）：
+ * depth-0 → 工程 §1/§4/§6 ∥ 普通 §1/§2/§4/§5/§6 · eng-designer → §2 · 评审 → §3 · eng-coder → §5 ·
+ * coder（普通模式分支增表——SEGMENT_BY_ROLE_NORMAL）→ §5；status 写域 = 调用者自己段（模式感知
+ * ——见 batch-lifecycle.mjs）。append 迁移面错误串**逐字保持 "batch_segment:" 前缀**（§4.1 全表锚断言）；
  * "batch:" 前缀 = 本批新增错误面（create/close/status/findInFlight/path 门/dispatch）。
  *
  * 导出面：`batchTool`（主名）· `resolveBatchDocPath` · `batchDocBases` · `batchDocForReview` ·
@@ -29,7 +30,7 @@ import { readFileSync, writeFileSync } from "node:fs"
 
 // 描述面 = `tool-docs/batch.md`（#15 描述外置统一——工厂形描述经 DESC 单一解析面，工厂调用期取值）
 import { DESC } from "../tools/shared.mjs"
-import { SEGMENT_BY_ROLE, readBatchStatusLine, sectionHeaderRe, findPlaceholderResidue, placeholderResidueError } from "./batch-skeleton.mjs"
+import { SEGMENT_BY_ROLE, SEGMENT_BY_ROLE_NORMAL, DEPTH0_SEGMENTS, readBatchStatusLine, sectionHeaderRe, findPlaceholderResidue, placeholderResidueError } from "./batch-skeleton.mjs"
 import { batchDocBases, resolveBatchDocPath } from "./batch-paths.mjs"
 import { closeBatchRecord, createBatchRecord, findInFlightBatch, statusBatchRecord } from "./batch-lifecycle.mjs"
 
@@ -93,10 +94,12 @@ function segmentNumber(raw) {
 }
 
 /** 身份 → 可写段号；无写权身份 → null。评审实例绑定优先（评审者的身份即"设计评审"。）
- *  depth-0 的段白名单（append = §1/§4/§6）由 appendBatchRecord 分支，不经本表。 */
-function allowedSegment(agent, review) {
+ *  depth-0 的段白名单（append——模式感知，§4.16）由 appendBatchRecord 分支，不经本表；
+ *  普通模式分支额外合并 coder 增表（`SEGMENT_BY_ROLE_NORMAL`——**合并查只在普通模式分支**）。 */
+function allowedSegment(agent, review, engineering) {
   if (review) return 3
-  return SEGMENT_BY_ROLE[agent?._role] ?? null
+  const role = agent?._role
+  return SEGMENT_BY_ROLE[role] ?? (engineering ? null : SEGMENT_BY_ROLE_NORMAL[role]) ?? null
 }
 
 /**
@@ -146,8 +149,9 @@ function insertIntoSection(src, seg, text) {
 
 /**
  * append 执行体（action=append——原 batch_segment execute 迁移 + depth-0 分支）：
- *  - 段白名单：depth-0 → §1/§4/§6（新错误面，"batch:" 前缀）；eng-designer → §2 · 评审 → §3 ·
- *    eng-coder → §5（迁移错误面，"batch_segment:" 前缀**逐字保持**）；
+ *  - 段白名单（**模式感知**——§4.16）：depth-0 工程 → §1/§4/§6（新错误面，"batch:" 前缀）∥
+ *    depth-0 普通 → §1/§2/§4/§5/§6（模式化新串）；eng-designer → §2 · 评审 → §3 ·
+ *    eng-coder → §5 · coder（普通模式分支增表）→ §5（迁移错误面，"batch_segment:" 前缀**逐字保持**）；
  *  - 目标定位（D-BR21）：depth-0 path 可选（缺省 = findInFlightBatch 唯一在飞批）；子代理/评审
  *    传 path ⇒ 拒，目标 = spawn/实例绑定；
  *  - 其余（gate / text 校验 / 剥凭证 / 骨架保护 / **死占位机检（F11-C）** / 插入 / 记账 / 回执）逐字保持原语义。
@@ -156,20 +160,29 @@ function appendBatchRecord({ args, ctx, review, batchDoc, onWritten }) {
   const agent = ctx?.agent ?? {}
   const cwd = agent.cwd ?? process.cwd()
   const depth0 = ctx?.depth === 0
-  const seg = allowedSegment(agent, review)
+  // 模式位执行期实读（§4.16——同款先例 = task.mjs execute 门；翻转即时生效——D-BR26）
+  const engineering = !!agent?.config?.agent?.engineering
+  const seg = allowedSegment(agent, review, engineering)
   if (!depth0 && 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.")
+    throw new Error(engineering
+      ? "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."
+      : "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); in normal mode the parent agent writes §1/§2/§4/§5/§6 through ordinary document writes.")
   }
   const n = segmentNumber(args?.segment)
   if (n === null) {
     if (depth0) {
-      throw new Error(`batch: unknown segment ${JSON.stringify(args?.segment ?? null)} — depth-0 append writes §1/§4/§6 of the in-flight record (pass the section number you write, e.g. "§4").`)
+      throw new Error(engineering
+        ? `batch: unknown segment ${JSON.stringify(args?.segment ?? null)} — depth-0 append writes §1/§4/§6 of the in-flight record (pass the section number you write, e.g. "§4").`
+        : `batch: unknown segment ${JSON.stringify(args?.segment ?? null)} — in normal mode depth-0 append writes §1/§2/§4/§5/§6 of the in-flight record (pass the section number you write, e.g. "§4").`)
     }
     throw new Error(`batch_segment: unknown segment ${JSON.stringify(args?.segment ?? null)} — pass the section number you write (e.g. "§${seg}").`)
   }
   if (depth0) {
-    if (n !== 1 && n !== 4 && n !== 6) {
-      throw new Error(`batch: §${n} is not yours to write — depth-0 append writes §1/§4/§6 only (一段一作者: §2 = eng-designer, §3 = design review, §5 = eng-coder).`)
+    const domain = engineering ? DEPTH0_SEGMENTS.append.engineering : DEPTH0_SEGMENTS.append.normal
+    if (!domain.includes(n)) {
+      throw new Error(engineering
+        ? `batch: §${n} is not yours to write — depth-0 append writes §1/§4/§6 only (一段一作者: §2 = eng-designer, §3 = design review, §5 = eng-coder).`
+        : `batch: §${n} is not yours to write — in normal mode depth-0 append writes §1/§2/§4/§5/§6 (一段一作者: §3 = design review only). Nothing was written.`)
     }
   } else 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).`)
@@ -211,9 +224,9 @@ function appendBatchRecord({ args, ctx, review, batchDoc, onWritten }) {
   if (!body.trim()) {
     throw new Error("batch_segment: nothing to append — the text is empty after credential stripping (credential values never reach the record).")
   }
-  // F11-C（挂点：gate / text 校验后 · insertIntoSection 前）：档头 + 目标段死占位残留 ⇒ 拒
-  // （他段占位不拦——一段一作者；骨架枚举单源 = skeleton 档 TEMPLATE_PLACEHOLDERS）。
-  const residues = findPlaceholderResidue(src, n)
+  // F11-C（挂点：gate / text 校验后 · insertIntoSection 前）：档头结构行死占位残留 ⇒ 拒
+  // （段体引用豁免——判据可辨性收正，`TOOLS.md` §6.20；骨架枚举单源 = skeleton 档 TEMPLATE_PLACEHOLDERS）。
+  const residues = findPlaceholderResidue(src)
   if (residues.length) throw new Error(placeholderResidueError(residues))
   const { written, roundN } = insertIntoSection(src, n, body)
   writeFileSync(abs, written)
@@ -246,7 +259,7 @@ export function batchTool(batchDoc = null, { review = false } = {}) {
         },
         segment: {
           type: "string",
-          description: "append/status only — the batch-record section you are writing (e.g. \"§4\"). Declares the section number only; your identity decides what is actually writable (main agent: append §1/§4/§6 · status §1; eng-designer §2; design review §3; eng-coder §5).",
+          description: "append/status only — the batch-record section you are writing (e.g. \"§4\"). Declares the section number only; your identity decides what is actually writable (main agent: append §1/§4/§6 · status §1 (engineering) / append §1/§2/§4/§5/§6 · status §1/§2/§5 (normal); eng-designer §2; eng-coder §5; normal-mode coder with a batchDoc binding §5; design review §3).",
         },
         text: {
           type: "string",
@@ -268,6 +281,14 @@ export function batchTool(batchDoc = null, { review = false } = {}) {
           type: "string",
           description: "create only — REQUIRED: the record's origin line (来源 = …; single line). It fills the header's 编制 line; without it the skeleton's placeholder would block the record's first append/status (topic-style fail-closed). Nothing is written when it is missing.",
         },
+        ledger: {
+          type: "string",
+          description: "create only — optional: the ledger entry number for the header's 台账 line (e.g. \"#938\"; a leading # is added if missing). Passed together with board, it fills the header at creation; when omitted, the placeholder stays and must be filled by file edit before the record's first append/status.",
+        },
+        board: {
+          type: "string",
+          description: "create only — optional: the owning board for the header's 台账 line (e.g. \"core\"). See ledger — both fill the header at creation.",
+        },
         date: {
           type: "string",
           description: "create only — the record date (YYYY-MM-DD); defaults to today.",

package/agent-tools/browser-async.mjs

@@ -0,0 +1,198 @@
+/**
+ * browser-async.mjs — browser 后台动作任务桥（池 ∥ 起跑 ∥ 结算 ∥ 注入 ∥ 杀单点——复用 bg 族单点，D2）。
+ * 设计权威 = `docs/core/design/BROWSER-TOOL.md` §2.11（异步通道——F-BT18）∥ §2.9（后台动作仍受动作
+ * 预算——timeoutMs 可覆写）∥ §2.10（外部关闭在飞 ⇒ 同因由结算）；批档 = `docs/batches/2026-10-07-browser-async-fix.md` §2。
+ *
+ * - 形态：`async:true`（depth-0 专项——schema 删参 + 运行期第二道）⇒ ack
+ *   `browser#<N> started (running) — <action> <subject>` 即返 ⇒ 后台同队执行（同一串行队列——单页
+ *   不引入并发）⇒ 结算**恒停靠** `_pendingAsyncResults` + 唤醒挂起驱动（bg 同式——消化轮注入）。
+ * - 池：`_browserTasks`（角色 "browser"；帽 `BROWSER_TASK_MAX = 4` 对齐单域 4，第 5 条显式拒——零静默丢）。
+ * - 取消：`process action=kill id:N`（id 路由先 bg 后 browser）⇒ queued 丢队（从未运行）∥ running
+ *   abort（动作展开）⇒ 结算 cancelled（墓碑 + 无摘要；重复幂等）；**不杀浏览器**（重置经 `close`）。
+ *   取消柄 = 条目控制器信号（`browser/session.mjs` `runAction` 的 `{signal}` 缝——一条机制两个因由）。
+ * - 收尾：Stop ∥ 会话中止 ⇒ `async-discard.mjs` `BROWSER_SPEC`（dispose = 条目控制器 abort）+ 墓碑
+ *   `discarded` 出池 + 整批一次提醒（模型可见凭据）；回合中断（Ctrl+I）经 `bindChildController` 豁免
+ *   （池保留——bg 同款）。竞态窗（条目先自行结算、收尾面未及见）⇒ 按 bg 族兜底：正常两态照常停靠
+ *   （摘要必达——零静默丢失），**不**自落「仅墓碑」降级支（墓碑不是模型可见凭据）。
+ * - 注入：`injectBrowserResult`（digest 单点族成员——`injectAsyncResult` 按 role="browser" 分发）；
+ *   回执正文受动作面既有上限（≤20,000 字符）⇒ 无需 offload 径。
+ * - 等待：`wait_for "browser id:N done"`（`browserTaskDone`——池内 done ∥ 出池即 done）。
+ * 入径 = `tools/browser.mjs` ∥ `tools/ops.mjs` **动态 import**（W8 契约②）；模块图：→ browser/session.mjs
+ * （入队面）· agent-tools/async-settle.mjs · subagent-scheduler.mjs（取号 / 令牌 / 键守卫）·
+ * agent/helpers.mjs（escapeXml）· context.mjs（pushReal）——叶子向、无环。
+ */
+import { escapeXml } from "../agent/helpers.mjs"
+import { pushReal } from "../context.mjs"
+import { runAction } from "../browser/session.mjs"
+import {
+  bindChildController, buildChildSignal, carrierField, getAsyncPool, parkAsyncPending,
+  tombstoneOf, wakeAsyncWaiters, writeTombstone,
+} from "./async-settle.mjs"
+import { assertPoolKeyFree, consumeSubagentToken, nextSubagentId } from "./subagent-scheduler.mjs"
+
+/** 后台动作帽（对齐 `ASYNC_POOL_LIMITS` 单域 4——KD-22）。超限显式拒。 */
+export const BROWSER_TASK_MAX = 4
+
+/** 池写侧（绑定不变式：主容器落父字段；缺省借用 / 别名 `history` 侧——同 `bash-async.mjs` 同式）。 */
+function ensureBrowserPool(parent) {
+  if (parent._browserTasks instanceof Map) return parent._browserTasks
+  const borrowed = carrierField(parent, "_browserTasks")
+  if (borrowed instanceof Map) { parent._browserTasks = borrowed; return borrowed }
+  parent._browserTasks = new Map()
+  if (parent?.history && typeof parent.history === "object") parent.history._browserTasks = parent._browserTasks
+  return parent._browserTasks
+}
+
+/** 条目读取（键形单源：写侧 `set(String(id))` ⇒ 读一律 String 归一；双形键兜底照 bg 族）。 */
+export function browserTaskEntry(parent, id) {
+  const pool = getAsyncPool(parent, "browser")
+  if (!(pool instanceof Map)) return null
+  const key = String(id)
+  return pool.get(key) ?? pool.get(Number(key)) ?? null
+}
+
+/** `wait_for` 条件 `browser id:N done` 判据（同式 bg）：池内 done ∥ **出池即 done**（结算恒出池——
+ *  pending 停靠 / 杀 / 丢弃皆已结束）；未知 id 亦按 done-by-vacuity。 */
+export function browserTaskDone(parent, id) {
+  const entry = browserTaskEntry(parent, id)
+  if (!entry) return true
+  return entry.done === true || entry.status === "done"
+}
+
+/** 条目中止（同一机制两处调用：kill 径 `killBrowserTask` ∥ discard 收尾面 `BROWSER_SPEC.dispose`）：
+ *  条目控制器 abort ⇒ `runAction` 信号径传导（queued 丢队 ∥ running 动作展开）；重复幂等
+ *  （`AbortController.abort` 幂等）。 */
+function abortBrowserEntry(entry) {
+  try { entry?.controller?.abort?.({ abortTrigger: "browser-kill" }) } catch { /* 已中止 */ }
+}
+
+/** subject 标签（ack ∥ 摘要共用）：动作对象头——navigate = url ∥ ref / selector / url / key / op /
+ *  from / networkIdle ∥ 坐标 ∥ expression 头 ∥ text 头；全空 ⇒ 空串。 */
+export function browserSubject(action, args = {}) {
+  const pick = action === "navigate" ? (args.url ?? null)
+    : (args.ref ?? args.selector ?? args.url ?? args.key ?? args.op ?? args.from
+      ?? (args.networkIdle === true ? "networkIdle" : null))
+  if (pick != null && String(pick) !== "") return String(pick)
+  if (String(args.x ?? "") !== "" && String(args.y ?? "") !== "" && Number.isFinite(Number(args.x)) && Number.isFinite(Number(args.y))) {
+    return `${args.x},${args.y}`
+  }
+  if (typeof args.expression === "string" && args.expression) return args.expression.slice(0, 60)
+  if (typeof args.text === "string" && args.text) return args.text.slice(0, 40)
+  return ""
+}
+
+/**
+ * 起跑（ack 即返——调用方不被动作阻塞）。失败面 = 显式 `{ error }`（帽 / 深度 / 上下文——零静默丢）。
+ * @returns {{ id: number, ack: string, entry: object } | { error: string }}
+ */
+export async function launchBrowserTask(parent, ctx, args = {}) {
+  if (!parent) return { error: "no agent context — background browser tasks run in a depth-0 session only" }
+  if ((ctx?.depth ?? 0) > 0) {
+    return { error: "browser async is depth-0 only — a child agent has no background task pool (run the action synchronously)" }
+  }
+  const action = String(args.action ?? "")
+  const pool = ensureBrowserPool(parent)
+  const running = [...pool.values()].filter((e) => e.done !== true)
+  if (running.length >= BROWSER_TASK_MAX) {
+    return {
+      error: `browser task cap reached (${running.length}/${BROWSER_TASK_MAX} running: ${running.map((e) => `browser#${e.id}`).join(", ")})` +
+        ` — wait for one to settle (wait_for "browser id:N done") or kill one (process action='kill' id:N)`,
+    }
+  }
+  // ED-5：取号 → 消费同步配对（无 await 间隙）+ 入池键守卫（同 bash-async 同式——守卫前置于起跑，命中即抛零副作用）。
+  const id = nextSubagentId(parent)
+  consumeSubagentToken(parent, id, "browser async launch", "browser")
+  assertPoolKeyFree(pool, id, "browser")
+  const { async: _asyncFlag, ...actionArgs } = args // `async` 不入动作参数面（零语义泄漏）
+  const subject = browserSubject(action, actionArgs)
+  const ctrl = new AbortController()
+  const entry = {
+    id, role: "browser", action, args: actionArgs, subject,
+    status: "running", done: false, cancelled: false, discarded: false,
+    controller: ctrl, startedAt: Date.now(), endedAt: null,
+    receipt: null, error: null, failed: null, _settle: null, promise: null,
+  }
+  entry.promise = new Promise((res) => { entry._settle = res })
+  // 会话 / 回合信号链（同 bg）：非 interrupt 中止 ⇒ 控制器中止 ⇒ 动作展开 + discard 收尾面；
+  // 回合中断（Ctrl+I）⇒ 不动（池保留）。
+  bindChildController(ctrl, buildChildSignal(parent, ctx))
+  entry.promiseRun = Promise.resolve()
+    .then(() => runAction(action, actionArgs, ctx, { signal: ctrl.signal }))
+    .then(
+      (receipt) => { entry.receipt = String(receipt) },
+      (e) => { entry.error = e?.message ?? String(e) },
+    )
+    .finally(() => finalizeBrowserEntry(parent, entry))
+  pool.set(String(id), entry)
+  return { id, ack: `browser#${id} started (running) — ${action}${subject ? ` ${subject}` : ""}`, entry }
+}
+
+/**
+ * 结算单点（回执 / 拒绝两径合流；幂等：entry.done 即返）。取消 / 丢弃两态 ⇒ 只落终态与唤醒（无摘要——
+ * 凭据 = 杀点确认 ∥ 收尾整批提醒）；其余（含会话中止竞态窗——收尾面未及见）⇒ 恒停靠 pending + 唤醒
+ * 挂起驱动（消化轮注入——零静默丢失；同 `bash-async.mjs` finalize 同式，**不**自落「仅墓碑」支）。
+ */
+function finalizeBrowserEntry(parent, entry) {
+  if (entry.done) return
+  entry.done = true
+  entry.status = "done"
+  entry.endedAt = Date.now()
+  getAsyncPool(parent, "browser")?.delete(String(entry.id))
+  if (entry.cancelled === true || entry.discarded === true) {
+    entry._settle?.() // 定向杀 ∥ 会话中止收尾——不注入（墓碑已由杀点 / 收尾面落定）
+    return
+  }
+  const receipt = entry.receipt ?? ""
+  if (entry.error == null && receipt.startsWith("Error:")) {
+    entry.failed = receipt.split("\n")[0].replace(/^Error:\s*/, "")
+  }
+  parkAsyncPending(parent, entry)
+  entry._settleSeq = (parent._asyncSettleSeq = (parent._asyncSettleSeq ?? 0) + 1)
+  entry._settle?.()
+  wakeAsyncWaiters(parent)
+}
+
+/** 状态词截断（摘要首行单行可读——超长因由截 200 字符）。 */
+function clip(text, max = 200) {
+  const s = String(text)
+  return s.length > max ? `${s.slice(0, max)}…` : s
+}
+
+/** 注入器（digest 单点族成员——`injectAsyncResult` 按 role="browser" 分发；消费即墓碑）。 */
+export async function injectBrowserResult(parent, entry) {
+  const seconds = (Math.max(0, (entry.endedAt ?? Date.now()) - entry.startedAt) / 1000).toFixed(1)
+  const label = `${entry.action}${entry.subject ? ` ${entry.subject}` : ""}`
+  const status = entry.error != null ? `failed: ${clip(entry.error)}`
+    : entry.failed != null ? `failed: ${clip(entry.failed)}`
+    : "ok"
+  const head = `[System reminder: background browser#${entry.id} finished — ${label} (${status}, ${seconds}s)]`
+  const body = escapeXml(String(entry.receipt ?? entry.error ?? "(no result)"))
+  pushReal(parent, { role: "user", content: `${head}\n${body}` })
+  writeTombstone(parent, entry.id, entry.error != null || entry.failed != null ? "failed" : "consumed", "browser")
+}
+
+/**
+ * 杀单点（id 靶——`process` action='kill'）：queued ⇒ 丢队（从未运行）∥ running ⇒ abort（动作展开）
+ * ⇒ 结算 cancelled（墓碑 + 无摘要）；**不杀浏览器**；重复 = 幂等（经终态墓碑返回同一确认——bg 同式）。
+ * @returns {{ id: string, status: "cancelled" | "error", error?: string }}
+ */
+export function killBrowserTask(parent, id) {
+  const key = String(id)
+  if (!key || key === "undefined" || key === "null") {
+    return { id: key, status: "error", error: "process kill id: requires a background browser task id (browser#N from the async ack)" }
+  }
+  const pool = getAsyncPool(parent, "browser")
+  const entry = browserTaskEntry(parent, key)
+  if (!entry) {
+    const tomb = tombstoneOf(parent, key)
+    if (tomb?.status === "cancelled" && tomb.role === "browser") return { id: key, status: "cancelled" } // 幂等确认
+    return { id: key, status: "error", error: `unknown background browser task id: ${key} — it has finished, was killed, or was never started` }
+  }
+  if (entry.done) return { id: key, status: "error", error: `browser#${key} has already finished — nothing to kill` }
+  if (entry.cancelled) return { id: key, status: "cancelled" } // 杀已在途——幂等
+  entry.cancelled = true
+  abortBrowserEntry(entry)
+  pool?.delete(key)
+  writeTombstone(parent, key, "cancelled", "browser")
+  return { id: key, status: "cancelled" }
+}

package/agent-tools/checkpoint.mjs

@@ -59,7 +59,7 @@ export function registerTurnCapCheckpoint(child, carrier, { turn = 0, signal } =
   if (signal?.aborted) return Promise.resolve(false) // ② 已中止 ⇒ 立即降级（不进挂起）
   const key = String(carrier.id ?? "")
   const rec = { child, carrier, turn }
-  // 先臂后报请（顺序即防御）：`rec.resolve` 与中止监听在入队**前**就位——否则
+  // 先布防、后报请（顺序即防御）：`rec.resolve` 与中止监听在入队**前**就位——否则
   // `pushChildUpstream` 同步唤醒等待栓的窗口里「登记已写、resolve 未挂」，兑现假成功而挂起不收敛。
   let abortedNow = signal?.aborted === true
   const promise = new Promise((resolve) => {