@thincoder/core 0.10.3 → 0.10.4

package/agent-tools/batch-lifecycle.mjs

@@ -49,6 +49,18 @@ function segmentNumber(raw) {
   return m ? Number(m[1]) : null
 }
 
+/** 档头两可选参归一（`BATCH-RECORD.md` §4.11 契约——逐字文本面 = `TOOLS.md` §6.20）：trim ∥
+ *  单行（拒句逐字）∥ 空串 ≡ 未给（null）；`ledger` 前导 `#` 补齐（board 无补齐）。给参 ⇒ 建即填
+ *  台账行（batchSkeleton 实参面）；未给（任一）⇒ 占位留存 + 回执填法句。 */
+function normalizeHeaderParam(name, raw) {
+  const v = typeof raw === "string" ? raw.trim() : ""
+  if (!v) return null
+  if (/\r?\n/.test(v)) {
+    throw new Error("batch: create ledger / board must be single lines — a multi-line value would break the header's 台账 line. Nothing was written.")
+  }
+  return name === "ledger" && !v.startsWith("#") ? `#${v}` : v
+}
+
 /** main-agent-only 门（BR-19/BR-24）：create/close 仅 depth-0 放行（eng 子代理 / 评审皆拒）。 */
 function assertMainAgentOnly(ctx, action, review) {
   if (review || !isDepthZero(ctx)) {
@@ -108,6 +120,8 @@ export function findInFlightBatch(cwd, bases) {
  * 路径解析 = `resolveBatchCreatePath`（§4.15 单源：候选序首个落基底内者 / 锚定串只解析项目根形）。
  * F11-B：`source` **必填**（topic 同款空拒——骨架编制行实参化；不传 = 死占位残留必被 F11-C 拒
  * ⇒ create 即拒，不留死锁）；`prev` 传入值**幂等剥**「前情 = 」前缀（值规范化；默认值零变）。
+ * 2026-10-05（A-2）：`ledger` / `board` 可选参**建即填**台账行（归一契约 = §4.11；回执两态 =
+ * 两参皆给 ⇒ 标注已填 ∥ 未给（任一）⇒ 填法句）。
  * @returns {string} 成功消息（含落盘绝对路径）
  */
 export function createBatchRecord({ args, ctx, review, cwd, bases, onWritten }) {
@@ -138,15 +152,22 @@ export function createBatchRecord({ args, ctx, review, cwd, bases, onWritten })
   if (/\r?\n/.test(source)) {
     throw new Error("batch: create source must be a single line — a multi-line source would break the header's 编制 line. Nothing was written.")
   }
+  // 档头两可选参（§4.11 契约——给则建即填台账行；未给任一 ⇒ 占位留存 + 回执填法句）
+  const ledger = normalizeHeaderParam("ledger", args?.ledger)
+  const board = normalizeHeaderParam("board", args?.board)
   const date = typeof args?.date === "string" && args.date.trim() ? args.date.trim() : todayLocal()
   // F11-B：prev 幂等 strip——调用方自带「前情 = 」前缀（单或重复）一并剥净（`+` 量词；归一化目的
   // = 值规范化，无前缀值原样通过）。默认值形态「无（独立批）」零变。
   const prevRaw = typeof args?.prev === "string" ? args.prev.trim() : ""
   const prev = prevRaw ? (prevRaw.replace(/^(?:前情\s*[=：:]\s*)+/g, "").trim() || "无（独立批）") : "无（独立批）"
   mkdirSync(dirname(abs), { recursive: true })
-  writeFileSync(abs, batchSkeleton({ date, topic, source, prev }))
+  writeFileSync(abs, batchSkeleton({ date, topic, source, prev, ledger, board }))
   onWritten?.(ctx?.agent ?? {}, abs)
-  return `batch: created ${abs} — six-section skeleton written (§1 status line carries the gate-legal 「进行中」 placeholder; register the ledger entry yourself — create does not).`
+  // 回执两态（`TOOLS.md` §6.20 逐字）：两参皆给 ⇒ 标注已填；未给（任一）⇒ 填法句（填法 = 文件编辑）
+  const headerNote = ledger !== null && board !== null
+    ? `header 台账 line filled (${ledger} · ${board})`
+    : "header 台账 placeholder(s) remain — fill them by file edit before the record's first append/status opens"
+  return `batch: created ${abs} — six-section skeleton written (§1 status line carries the gate-legal 「进行中」 placeholder; register the ledger entry yourself — create does not). ${headerNote}`
 }
 
 /**
@@ -265,7 +286,7 @@ function assertStatusNote(note) {
  * 恰一词（**余核 = 关键词**——F11-A 谓词收紧），散文说明走独立 `note` 字段（落状态行括注）；
  * 冻结真值不变（gate 只读 §1）。path 参数 = 仅 depth-0（D-BR21）——子代理/评审传 path
  * ⇒ 拒（目标 = spawn/实例注入，语法上写不到别处）。F11-C 挂点 = 写盘前（assertStatusValue 后）：
- * 档头 / 目标段含骨架死占位 ⇒ 拒（close 不拦——收口是主 agent 终态动作）。
+ * 档头结构行含骨架死占位 ⇒ 拒（段体引用豁免；close 不拦——收口是主 agent 终态动作）。
  * @returns {string} 成功消息
  */
 export function statusBatchRecord({ args, ctx, review, pickTarget, onWritten }) {
@@ -298,8 +319,8 @@ export function statusBatchRecord({ args, ctx, review, pickTarget, onWritten })
   const abs = pickTarget(args?.path)
   const src = readFileSync(abs, "utf8")
   assertGateOpen(src)
-  // F11-C（写盘前）：档头 + 本段死占位残留 ⇒ 拒（他段占位不归本段作者管）
-  const residues = findPlaceholderResidue(src, seg)
+  // F11-C（写盘前）：档头结构行死占位残留 ⇒ 拒（段体引用豁免——判据可辨性收正，`TOOLS.md` §6.20）
+  const residues = findPlaceholderResidue(src)
   if (residues.length) throw new Error(placeholderResidueError(residues))
   const written = updateSectionStatusLine(src, seg, lineValue)
   writeFileSync(abs, written)

package/agent-tools/batch-paths.mjs

@@ -10,6 +10,7 @@
  * **歧义锚**（条 5 · 2026-10-02 · #828）= create 按目标所属项目落基底 ∥ 无所属显式拒；读面候选腿追加；
  * 在飞 ∥ 写门基底集 = 候选并集（`batchDocBases`）；**零变面** = 绝对路径照旧、三个错误文案逐字、
  * 「参数在 + 路径可读」判据句、`ok` / `none` 两态。
+ * **基底自有项目根腿 + 基底相对单段收窄**（条 6 · 2026-10-05 · #942）= 逐基底 `owningProject` 恰一落点收 ∥ 多落点显式拒（`ambiguousLandingError`）；基底相对腿限单段（多段串不二次拼接）。
  *
  * 依赖（KD-4 单向）：本档为**叶档**——只 import `node:*` 与 `../manifest.mjs`；主档 re-export 保既有面。
  */
@@ -98,6 +99,7 @@ const outsideBasesError = (raw) => new Error(`batch: create path resolves outsid
 const anchoredEscapeError = (raw) => new Error(`batch: create path is anchored at a batch base root but does not resolve under the declared docRoot.batches root(s) — refusing to nest it (fail-closed). Path: ${raw}`)
 /** 歧义锚 create 拒面（**文案逐字** = `BATCH-RECORD.md` §4.15 条 5——机检锚 `ambiguous session anchor`）。 */
 const ambiguousCreateError = (raw, candidates) => new Error(`batch: ambiguous session anchor — create target "${raw}" belongs to no candidate project; pass an explicit project path (e.g. "${candidates[0]}/docs/batches/<file>.md"). Candidates: ${candidates.join(", ")}`)
+const ambiguousLandingError = (raw, landings) => new Error(`batch: create path resolves under more than one declared batch-record base — refusing to pick one (fail-closed); pass an explicit path (absolute preferred). Path: ${raw}. Candidates: ${landings.join(", ")}`)
 
 /** 歧义锚读面候选腿（条 5）：逐候选项目——项目根形（`resolve(candidate, p)`）∥ 声明基底形
  *  （候选按名排序、并集保序——「首个可读」在此即为确定判读）。 */
@@ -149,7 +151,7 @@ export function resolveBatchDocPath(cwd, given) {
 }
 
 /**
- * **create 面**解析（§4.15 条 2/3）：绝对路径照旧取用（仍过越基底判据）；相对路径 = 候选序中首个**落基底
+ * **create 面**解析（§4.15 条 2/3/6）：绝对路径照旧取用（仍过越基底判据）；相对路径 = 候选序中首个**落基底
  * 根内**者（新档不存在——可读性无判别力）；锚定串只解析项目根形，不落基底内 ⇒ fail-closed 新文案。
  *  **歧义锚**（条 5）：目标所属项目（`owningProject`）∈ 锚候选集 ⇒ 基底 = 该项目声明面（落其基底内；
  *  越出 ⇒ 既有 fail-closed）；无所属 ⇒ **显式拒**（列候选 + 显式路径指引——不静默落锚）。
@@ -179,8 +181,26 @@ export function resolveBatchCreatePath(cwd, given, bases) {
     if (!insideBases(abs, roots)) throw anchoredEscapeError(raw)
     return abs
   }
-  for (const abs of [resolve(base, p), resolve(batchProjectRoot(base), p), ...roots.map((b) => resolve(b, p))]) {
+  for (const abs of [resolve(base, p), resolve(batchProjectRoot(base), p)]) {
     if (insideBases(abs, roots)) return abs
   }
+  // ③ 基底自有项目根形（#942 条 6）：owningProject 可判者逐基底取值；distinct 落点 ≥2 ⇒ 拒
+  const owned = []
+  for (const b of roots) {
+    const ownRoot = owningProject(b)
+    if (!ownRoot) continue
+    const abs = resolve(ownRoot, p)
+    if (insideBases(abs, roots) && !owned.some((x) => samePath(x, abs))) owned.push(abs)
+  }
+  if (owned.length > 1) throw ambiguousLandingError(raw, owned)
+  if (owned.length === 1) return owned[0]
+  // ④ 基底相对形收窄单段（归一后无 `/` 才走原基底腿——多段串不二次拼接）
+  const leafRel = roots.length ? relative(roots[0], resolve(roots[0], p)) : ""
+  if (leafRel && !leafRel.startsWith("..") && !leafRel.includes(sep)) {
+    for (const b of roots) {
+      const abs = resolve(b, p)
+      if (insideBases(abs, roots)) return abs
+    }
+  }
   throw outsideBasesError(raw)
 }

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）。
@@ -58,46 +58,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,16 +173,18 @@ 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>）` 后缀与 `来源 = <讨论来源>` 占位实参化。
  */
-export function batchSkeleton({ date, topic, source, prev }) {
+export function batchSkeleton({ date, topic, source, prev, ledger = null, board = null }) {
   return [
     `# ${date} · ${topic}`,
     "> 六段 append-only，一段一作者：§1 讨论（主 agent）· §2 批次任务与设计（eng-designer）· §3 设计评审（评审子代理）· §4 用户批准（主 agent）· §5 实施记录（eng-coder）· §6 验证与收口（父代理）。",
     `> 编制：主 agent · ${date} · 来源 = ${source}。`,
-    `> 台账 = #<编号>（<板块> · 归批）。前情 = ${prev}。`,
+    `> 台账 = ${ledger ?? "#<编号>"}（${board ?? "<板块>"} · 归批）。前情 = ${prev}。`,
     "## §1 讨论（主 agent）",
     `**状态行**：🔄 ${STATUS_WORDS[1].open}（…）`,
     "<§1 模板占位：本批条目 / 关键判据 / 授权口径>",

package/agent-tools/batch.mjs

@@ -211,9 +211,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)
@@ -268,6 +268,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/design-token.mjs

@@ -95,6 +95,19 @@ export function stripDesignTokenEcho(text, designToken) {
 const NO_VALID_ECHO_MARK = "未回显有效 token——未签发 (no valid token echo — no design token was issued)"
 const TRUNCATED_ECHO_MARK = "注：回显被截断（uuid 之后缺失或不符）——已按批准结算；全串 token 已签发 (note: truncated echo — the part after the uuid was missing or inexact; settled as approved; the full token was issued)"
 
+/** §5.2 verdict gate (#940): the echo alone is NOT the verdict — the receipt must
+ *  carry a `VERDICT: pass` line and no `VERDICT: changes-required` line (fail-closed). */
+const VERDICT_PASS_LINE    = /^[ \t]*[*_`]*[ \t]*VERDICT:[ \t]*pass[ \t]*[*_`]*[ \t]*$/m
+const VERDICT_CHANGES_LINE = /^[ \t]*[*_`]*[ \t]*VERDICT:[ \t]*changes-required[ \t]*[*_`]*[ \t]*$/m
+export function verdictGateFailure(rawResult) {
+  if (typeof rawResult !== "string") return "no-pass-line"
+  if (VERDICT_CHANGES_LINE.test(rawResult)) return "changes-required"
+  return VERDICT_PASS_LINE.test(rawResult) ? null : "no-pass-line"
+}
+
+/** §5.2 rejection mark (verbatim — machine-greppable; reason = no-pass-line | changes-required). */
+const VERDICT_GATE_MARK = (reason) => `裁定非通过——token 未签发 (review verdict is not pass — no design token was issued; reason: ${reason}; the echoed token was stripped)`
+
 /**
  * Shared design-review settlement (sync wrapper + async settle): the token echo
  * IS the verdict — the advisor echoes it only on approval. On echo (full string
@@ -134,6 +147,13 @@ export function settleDesignReview(agent, run, designToken, rawResult, opts = {}
     const stripped = stripDesignTokenEcho(rawResult, designToken).trim()
     return { passed: false, output: [stripped, NO_VALID_ECHO_MARK].filter(Boolean).join("\n\n") }
   }
+  // §5.2 裁定闸（#940）：签发 = 回显 ∧ 裁定行——缺 `VERDICT: pass` 行或含 `VERDICT: changes-required` 行
+  // ⇒ 拒签（与 M1 径同形：剥净回显 + 恒定标记；槽零写 ∥ 实例保持——修后重评）。
+  const gateFailure = verdictGateFailure(rawResult)
+  if (gateFailure !== null) {
+    const stripped = stripDesignTokenEcho(rawResult, designToken).trim()
+    return { passed: false, output: [stripped, VERDICT_GATE_MARK(gateFailure)].filter(Boolean).join("\n\n") }
+  }
   // Echoed the token → review passed. Issue it to the parent for eng-coder.
   agent._engDesignTokens ??= new Map()
   agent._engDesignTokens.set(run.designId, designToken)

package/agent-tools/escalate-async.mjs

@@ -107,8 +107,10 @@ function touchedFilesNote(child, cwd) {
 export function classifyEscalateSettle(parent, entry) {
   if (entry.cancelled) return { cancelled: true }
   // AGENT-LOOP.md §6.15（TUI-OOM-ROOTCAUSE）——childAgent 语义面：settle 分类（touched 摘要/partial
-  // merge）与 status/observe 摘要的读取源；**消化注入完成后由 `releaseSettledEntry`
-  // （async-settle.mjs）置 null**（池内未消化窗口不释放——表 2 候选 2 否决）。
+  // merge）与 status/observe 摘要的读取源；**消化注入完成后释放**（池内未消化窗口不释放——表 2 候选 2 否决）；
+  // fallback 面（无 `_daSession`）由 `releaseSettledEntry`（async-settle.mjs）置 null（逐字沿用）；会话态
+  // （`_daSession`）注入后改调 `releaseChildHold`（仅释放 `childAgent`——`report` 保留至销账 / 升级；
+  // §6.31.4 ∥ KD-DA7）。
   const child = entry.childAgent
   const touched = child?._touchedFiles ?? []
   const overlap = overlapPaths(parent, entry.launchSeq, touched)

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/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,6 +34,8 @@ 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"
 
@@ -394,10 +396,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-spawn.mjs

@@ -243,7 +243,7 @@ export function buildSpawnChild(parent, ctx, args, role, wantAsync, files, depen
   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)")

package/agent-tools/subagent.mjs

@@ -139,7 +139,7 @@ export const subagentTool = {
       model: { type: "string", description: "action:'spawn': provider/model override ('provider:model', a provider, or a model name on the parent's provider) — defaults config.agent.subagentModels[role] → config.agent.subagentModel → the parent's provider; \"default\" inherits. action:'escalate': a consult candidate (default = the first)." },
       designToken: { type: "string", description: "Required when role='eng-coder': the token from advisor(type='design') after the review passed — without it, eng-coder cannot modify files." },
       designId: { type: "string", description: "role='eng-coder': the designId echoed with the approved token — required to pick between concurrent designs (optional for one). action:'consume-design': the slot to close out (required to pick between several; the gate refuses to guess)." },
-      batchDoc: { type: "string", description: "REQUIRED for role='eng-coder'/'eng-designer': the batch record path (docs/batches/<batch>-<topic>.md) — the task book this spawn implements/writes. Refused when absent or when the path does not resolve to a readable file; the content is never validated." },
+      batchDoc: { type: "string", description: "REQUIRED for role='eng-coder'/'eng-designer': 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) — the task book this spawn implements/writes. Refused when absent or when the path does not resolve to a readable file; the content is never validated." },
       round: { type: "string", enum: ROUND_VALUES, description: "REQUIRED for role='eng-coder'/'eng-designer': initial (first round for this design) or fix (a correction round reusing the same designId+designToken; docs FIRST). No default — missing = refused." },
       async: { type: "boolean", description: "action:'spawn'/'escalate': default at depth 0 = true (async; the report arrives automatically); depth>0 always sync. async:false forces the blocking flight." },
       files: { type: "array", items: { type: "string" }, description: "action:'spawn' only: the file write-domain this task declares — file-level paths only (cwd-relative or absolute; directories rejected — they bypass the conflict detector). Overlapping-file tasks serialize automatically. Omit = no conflict detection." },