@thincoder/core 0.10.11 → 0.10.13

package/CHANGELOG.md

@@ -3,6 +3,27 @@
 All notable changes to the core package are documented here.
 Format: Keep a Changelog · 中文 · 号在发布时定（CalVer——见 `docs/RELEASE.md` §4）。
 
+## [0.10.13] — 2026-10-26
+
+### Added
+
+- **`client-identity.mjs`：模型请求带产品身份头**——新增 `setClientIdentity({ surface, version })` ∥ `clientIdentity()` ∥ `userAgent()` ∥ `withUserAgent(headers)`；字形 `ThinCoder/<surface>/<version>`，surface 小写枚举 `cli` ∥ `vscode` ∥ `desktop` ∥ `server`（内部缺省 `core`）。
+- **不可被渠道配置覆盖**：`withUserAgent` 先删任何大小写变体的 `user-agent` 键再写本产品值——fetch `Headers` 对变体是合并语义，只靠后写会得双值。
+- **七处消费点全部装配**：provider/{core,anthropic,google,responses,list-models} · `generate-title.mjs` · `embedding.mjs`。
+- **缺省哨兵** `ThinCoder/core/0.0.0`：任何真实端版本都不等于 `0.0.0`，四端进程内出现即声明漏接。
+
+### Note
+
+- **核须先于端发版**：四端都载本件，旧核 + 新端 = 启动即 `ERR_MODULE_NOT_FOUND`。
+
+## [0.10.12] — 2026-10-26
+
+### Changed
+
+- **台账在无根目录从「静默空集」改为「抛明」**：项目根推导不出来时，`query` / `count` / `add` / `update` / `close` 一律抛错并说明「自哪个路径、向上找到哪里为止」，不再返回空集。空集与「记到别的项目」在回执上分不开，静默空集等于让人以为没有台账。
+- **多根工作区下建批档：报明项目并给路径，不再落锚目录**：工作目录本身没有项目、直接子目录里有项目（1 个同判、多个同判），此时建批档会列全下辖项目并给显式路径指引；目标属于某个项目时照常落该项目的声明基底。
+- **项目根解析：多根工作区一律「≥1 同判」**：取消此前「恰一个子项目」与「多个」的区别——工作目录下直接子目录带项目清单，不论 1 个还是多个，都是多根工作区，逻辑一致。
+
 ## [0.10.11] — 2026-10-25
 
 ### Added

package/advisor/messages.mjs

@@ -12,7 +12,7 @@ import { loadAdvisorMd, extractConversationBackground, extractAgentResponseTable
 import { injectProjectGuide, injectDocumentMap, injectProjectStandards, NO_GIT_NOTICE } from "./project-context.mjs"
 
 // Structural split (not an authority migration): the moved helpers stay reachable here.
-export { findProjectRoot, injectProjectGuide } from "./project-context.mjs"
+export { findGuideRoot, injectProjectGuide } from "./project-context.mjs"
 
 /**
  * Build the mechanical review-object declaration block (AGENT-LOOP-ASYNC-POOL.md §6.18

package/advisor/project-context.mjs

@@ -51,7 +51,7 @@ export const NO_GIT_NOTICE = "(No git repository detected — change-set context
  * @param {string[]} scopeFiles — cwd-relative review-scope paths (may be empty)
  * @returns {string|null} absolute project root with an AGENTS.md, or null
  */
-export function findProjectRoot(cwd, scopeFiles) {
+export function findGuideRoot(cwd, scopeFiles) {
   // Normalize separators before comparing: input paths may use either
   // convention (join() → "\\" on Windows; tool args / tests → "/"). Mixed
   // styles made isInside(cwd + sep) miss legitimately nested paths.
@@ -88,7 +88,7 @@ export function findProjectRoot(cwd, scopeFiles) {
  */
 export function injectProjectGuide(agent, parts, scopeFiles = []) {
   parts.push("## Project Guide (AGENTS.md)")
-  const root = findProjectRoot(agent.cwd, scopeFiles)
+  const root = findGuideRoot(agent.cwd, scopeFiles)
   const path = root ? join(root, "AGENTS.md") : null
   let text
   if (!path) {

package/agent/run-stages.mjs

@@ -11,6 +11,7 @@ import { compressIfNeeded, compressFallback, COMPRESS_FAILURE_LIMIT } from "../c
 // §6.17/D-CC32 溢出守卫（兜底，非主修）：预算面单源 requestBudget ∥ 再估面 contextUsage（与压缩判定同一函数）
 import { requestBudget } from "../config.mjs"
 import { contextUsage } from "../token-window.mjs"
+import { contextOverflowError } from "../provider/errors.mjs"
 import { ensureAutoReminder, injectEngineeringReminder, ContinueError, snapshotGuard } from "./helpers.mjs"
 import { pushManifestStateReminder } from "./setup-reminders.mjs"
 import { cleanupConsultSessions } from "../agent-tools/consult.mjs"
@@ -97,6 +98,19 @@ export async function runCompactionCheck(agent, ctx) {
     callbacks.onCompress?.(agent._lastCompressInfo ?? {})
     ensureAutoReminder(agent)
   }
+  // 压缩失败记账（两处共用：下面的阈值面 catch ∥ 下面的守卫面强制压缩）——AbortError 必须透传。
+  const noteCompressFailure = (compressError) => {
+    if (compressError?.name === "AbortError" || signal?.aborted) throw compressError
+    agent._compressFailures = (agent._compressFailures ?? 0) + 1
+    // Q3 (CONTEXT-COMPACTION §7 D-C1): a failed compression is surfaced to the panel;
+    // COMPRESS_FAILURE_LIMIT consecutive failures still degrade to compressFallback.
+    callbacks?.onCompressFail?.(compressError)
+  }
+  const degradeIfCompressExhausted = () => {
+    if (agent._compressFailures < COMPRESS_FAILURE_LIMIT) return
+    agent._compressFailures = 0
+    if (compressFallback(agent)) callbacks.onCompress?.(agent._lastCompressInfo ?? {})
+  }
   try {
     let compacted = await compressIfNeeded(
       agent, threshold, callbacks,
@@ -111,49 +125,39 @@ export async function runCompactionCheck(agent, ctx) {
     }
     if (compacted) bookkeepCompaction()
   } catch (compressError) {
-    // AbortError must not be swallowed: user cancellation must propagate
-    if (compressError?.name === "AbortError" || signal?.aborted) throw compressError
-    agent._compressFailures = (agent._compressFailures ?? 0) + 1
-    // Q3 (CONTEXT-COMPACTION §7 D-C1): a failed compression is surfaced to the panel;
-    // COMPRESS_FAILURE_LIMIT consecutive failures still degrade to compressFallback.
-    callbacks?.onCompressFail?.(compressError)
+    noteCompressFailure(compressError)
     if (pending) {
       // 失败注记（§6.16.2 回执面②）：模型面告知缺口——既有失败链 / 面板面零改，仅补一行机器注记
       const { compactFailureNote } = await import("../agent-tools/context.mjs")
       agent.history.push({ role: "user", content: compactFailureNote(errText(compressError), agent._compressFailures), transient: true })
     }
-    if (agent._compressFailures >= COMPRESS_FAILURE_LIMIT) {
-      agent._compressFailures = 0
-      if (compressFallback(agent)) callbacks.onCompress?.(agent._lastCompressInfo ?? {})
-    }
+    degradeIfCompressExhausted()
   }
 
   // 溢出守卫（CONTEXT-COMPACTION.md §6.17 / D-CC32——兜底，非主修；本缝 = catch 闭合后、返回前）。
-  // 判据 = maxTokensSource !== "absent" ∧ prompt 估算 > limit（limit = window − reserve，恒为数）。
-  // **判据不用 maxTokens**：未发时为 undefined ⇒ NaN ⇒ 守卫静默失效（§6.17）；absent 档客户端未预留
-  // ⇒ 守卫不覆盖（服务端 400 兜——把规格 maxOutput 当实发判会让 doubao 三行永久发不出去）。
+  // 判据 = prompt 估算 > `budget.limit`（**无档次门**——absent 档 limit 取地板 max(window − reserve, threshold)，
+  // 恒为正数、恒可判）。**判据不用 maxTokens**：未发时为 undefined ⇒ NaN ⇒ 守卫静默失效（§6.17）。
   // 真 ⇒ 以 force 强制压缩一次（先压再判）；再估仍超 ⇒ 抛三实数、回合请求零发。不截断、不静默削输出。
   const budget = requestBudget(agent.provider)
-  if (budget.maxTokensSource !== "absent") {
-    let usage = contextUsage(agent, compactionOverhead)
-    if (usage.total > budget.limit) {
+  let usage = contextUsage(agent, compactionOverhead)
+  if (usage.total > budget.limit) {
+    // 强压一次：失败走与阈值面同一条记账 / 降级链（不把摘要错误当回合错误直抛——
+    // 记账后仍按「压后仍超」判：降级截断可能已把上下文压到线下）。
+    try {
       const compacted = await compressIfNeeded(
         agent, threshold, callbacks, { ...compactionOverhead, force: true }, signal,
       )
       if (compacted) bookkeepCompaction()
-      usage = contextUsage(agent, compactionOverhead)
-      if (usage.total > budget.limit) {
-        const remedy = budget.limit < 0
-          ? `max_tokens ${budget.maxTokens} alone exceeds the window — lower provider.maxTokens or switch to a larger-window model`
-          : "reduce the conversation (/compact or prune) before retrying"
-        const overflow = new Error(
-          `context overflow: prompt ~${usage.total} tokens + max_tokens ${budget.maxTokens} > window ${budget.window}` +
-          ` (limit ${budget.limit}) — forced compaction ran but the prompt still exceeds the window; ${remedy}`,
-        )
-        overflow.kind = "context_overflow"
-        overflow.retryable = false
-        throw overflow
-      }
+    } catch (compressError) {
+      noteCompressFailure(compressError)
+      degradeIfCompressExhausted()
+    }
+    usage = contextUsage(agent, compactionOverhead)
+    if (usage.total > budget.limit) {
+      const remedy = budget.limit < 0
+        ? `max_tokens ${budget.maxTokens} alone exceeds the window — lower provider.maxTokens or switch to a larger-window model`
+        : "forced compaction ran but the prompt still exceeds the window; reduce the conversation (/compact or prune) before retrying"
+      throw contextOverflowError(agent.provider, usage.total, budget, remedy)
     }
   }
 }

package/agent/setup.mjs

@@ -64,6 +64,9 @@ export async function prepareRun(agent, input, callbacks, {
 
   agent._lastPromptTokens = null
   agent._usageAtLen = null
+  // §6.17 估算自校准比（`_tok` / `_tokRatio`）**不在本处清**：本函数是每 run 的 pre-flight，
+  // 而在每轮用户消息上归零会让池化比退化成单样本（R2 失效）。初值在 `agent.mjs` 构造字面量，
+  // 清空点 = `/new`（`session-lifecycle.mjs`）∥ `key` 变自清（`token-window.mjs` `recordTokenSample`）。
   // Cumulative provider cache accounting (batch 2026-10-18-context-cache-visibility):
   // the service reports prompt_cache_hit/miss per response; the terminal faces each kept
   // their own tally, so the CORE had none and `context` could not report cache efficiency.

package/agent/turn-loop.mjs

@@ -13,6 +13,7 @@ import { recordToolResults } from "./record-results.mjs"
 import { injectPostTurn } from "./post-turn.mjs"
 import { handleCompletion } from "./completion.mjs"
 import { runCompactionCheck, injectTurnReminders, injectResponseReminders } from "./run-stages.mjs"
+import { recordTokenSample } from "../token-window.mjs"
 import { callModelTurn } from "./chat-call.mjs"
 import {
   turnFrame, // 第 19 批（TURN-ACROSS-SEGMENTS）：跨段累计编号帧（设计 TURN-CAP-CONTINUE.md §4）
@@ -194,6 +195,8 @@ export async function runTurnLoop(agent, {
         agent._lastPromptTokens = response.usage.prompt_tokens
         agent._usageAtLen = agent.history.length
       }
+      // §6.17 估算自校准：服务端真值 ÷ 输入侧估算（`estimated` = 发送面净判同一个 estPrompt）
+      recordTokenSample(agent, agent.provider, response.estimated, response.usage)
     }
 
     // Warn on abnormal finish reasons — the response may be incomplete/truncated.

package/agent-tools/batch-gate.mjs

@@ -1,36 +1,39 @@
 /**
  * agent-tools/batch-gate.mjs — 文档机检门（`batch` 工具两机械点的**单源门**）。
  *
- * 权威规格 = `docs/core/design/DOC-DISCIPLINE.md` §3.20「结构兜底」（判据 / 范围 / 范围分域 / 适用面 /
+ * 权威规格 = `docs/core/design/DOC-DISCIPLINE.md` §3.20「结构兜底」（判据 / 范围 / 适用面 /
  * ERROR 消费分野 / 门自身异常 / 不检面）——本档只实现，**不重述口径**（D2）。需求 = `DOC-CHECK.md` F9 / AC-7。
  *
  * 调用面两处、各一取值（`scope` 语义 = 规范「调用面开关，无第三值」）：
  *   ① `batch.mjs` append 写 §2 / §5（`!depth0 && !review`）⇒ `scope: "writer"`——范围 = 写者触达记账
  *      （与工具面 gate 同源 `docsSource="session"`）；`REFUSED` ⇒ 调用面 throw；`ERROR` / 门自身异常 ⇒ 放行 +
  *      回执明示（子代理无法重启会话，卡死写账 = 无账之笔；② 会拒收口 ⇒ 轮次不会被当成已通过）。
- *   ② `batch-lifecycle.mjs` close ∥ status 值余核「已收口」⇒ `scope: "close"`——范围 = 本批笔域集（触达账；
- *      `git diff --name-only <批起 sha> HEAD` 的基 sha 只有父侧掌握 ⇒ 取不到基时只认触达账 + 回执明示）
- *      ∪ git 面（`git diff --name-only HEAD` ∪ `git ls-files --others --exclude-standard`，域求交归引擎）；
- *      `REFUSED`（K ≥ 1）∥ `ERROR` ⇒ 调用面 throw（fail-closed）；命中 ⊆ 他批在途集 ⇒ 不阻收口 + 固定行逐档列出。
+ *   ② `batch-lifecycle.mjs` close ∥ status 值余核「已收口」⇒ `scope: "close"`——范围 = 本批笔域集
+ *      （父侧触达账 ∪ 本批提交 diff = `git diff --name-only <批起 sha> HEAD` 内的 `.md`）；
+ *      `REFUSED`（K ≥ 1）∥ `ERROR` ⇒ 调用面 throw（fail-closed）。
+ *      **单集**：范围内不设第二集——工作树里范围外的档不入判、不入报面（用户 2026-10-25 裁定「只判指定文件」）。
  *
  * 判据零变：本档不新增判据——只决定「判谁」与「何时强制」；判据与裁定串由产品引擎
  * `doc-check/index.mjs` 产出（判据源唯一）。
  *
- * 两条边界（设计与实测同口径）：① **批档自身不入范围**（载体不是判据对象——判它只会把载体的超段记成本批欠账）；
- * ② **本轮提交面不在工具面**——`<批起 sha>` 只有父侧掌握，
- * ② 的写入集只认触达账 + 回执明示「基 sha 未定」，提交面由父侧协议清单兜（不静默）。
+ * 两条边界（设计与实测同口径）：
+ * ① **批档自身不入范围**（载体不是判据对象——判它只会把载体的超段记成本批欠账）；
+ * ② **提交 diff 腿的基 sha 只读批档 §1 的记入行**（`批起 sha = <sha>`——取行内首个 40 位十六进制串）；
+ *    取不到（无该行 ∥ 形态不合 ∥ git 跑不出该 diff）⇒ 只认触达账 + 回执明示「基 sha 未定」（不静默）。
  */
 import { execFileSync } from "node:child_process"
+import { readFileSync } from "node:fs"
 import { relative, resolve } from "node:path"
 
 import { owningProject, readManifest } from "../manifest.mjs"
 import { runDocCheck } from "../doc-check/index.mjs"
+import { sectionHeaderRe } from "./batch-skeleton.mjs"
 import { batchProjectRoot } from "./batch-paths.mjs"
 
 /** 平台路径键（win32 大小写不敏感——只作集比对，非判据面）。 */
 const pathKey = (p) => (process.platform === "win32" ? p.toLowerCase() : p)
 
-/** 文档档谓词 + 绝对化（触达账 / git 面同形；非 `.md` 不进范围）。 */
+/** 文档档谓词 + 绝对化（触达账 / 提交 diff 同形；非 `.md` 不进范围）。 */
 const isDocPath = (p) => typeof p === "string" && p.trim() !== "" && p.toLowerCase().endsWith(".md")
 function docPaths(list, base) {
   const out = []
@@ -39,18 +42,41 @@ function docPaths(list, base) {
 }
 
 /**
- * git 面（他批在途集候选——只取清单，域求交归引擎）：`git diff --name-only HEAD` ∪ 未跟踪档。
- * 路径以**仓根**（`rev-parse --show-toplevel`）为基还原——项目根住大仓子目录时条目不丢（清单相对仓根）。
- * 不可得（非仓 / 无 git）⇒ `ok: false` + 空集（调用面回执明示「git 面不可得」，不静默）。
+ * `<批起 sha>` 的取法（唯一）= 批档 §1 的记入行 `批起 sha = <sha>`：段界消费 `sectionHeaderRe(1)`
+ * （段头形态单源——`## §10` 不误命中 `§1`），取段内该行行内首个 40 位十六进制串。
+ * 无该行 ∥ 形态不合 ∥ 读不到 ⇒ `null`——调用面按「基 sha 未定」明示，不静默；段界外提到该行形不算数
+ * （记入行只认 §1：取法与写入义务单源 = 规范「② 的范围」）。
  */
-function gitSurface(root) {
-  const run = (cwd, argv) => execFileSync("git", ["-C", cwd, ...argv], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 8000 })
+function baseShaOf(abs) {
+  let src
+  try { src = readFileSync(abs, "utf8") } catch { return null }
+  const hdr = sectionHeaderRe(1).exec(src)
+  if (!hdr) return null
+  const nextRe = /^## §\d/gm
+  nextRe.lastIndex = hdr.index + hdr[0].length
+  const next = nextRe.exec(src)
+  const body = src.slice(hdr.index + hdr[0].length, next ? next.index : src.length)
+  for (const line of body.split(/\r?\n/)) {
+    if (!line.includes("批起 sha")) continue
+    const sha = /[0-9a-f]{40}/i.exec(line)?.[0]
+    if (sha) return sha
+  }
+  return null
+}
+
+/**
+ * 本批提交 diff 腿（`git diff --name-only <sha> HEAD`——只取清单，判定归引擎）：路径以**仓根**
+ * （`rev-parse --show-toplevel`）为基还原——项目根住大仓子目录时条目不丢（清单相对仓根）。
+ * `-c core.quotepath=false`：不关此开关时 git 把含非 ASCII 字节的路径整串加引号转义，
+ * 下流 `endsWith(".md")` 判据会判假 ⇒ 非 ASCII 档名的档静默掉出范围（正是本批要关的「范围跑偏」）。
+ * 跑不出（非仓 / sha 不可解析）⇒ `ok: false` + 空集（调用面按「基 sha 未定」明示，不静默）。
+ */
+function committedDocs(root, sha) {
+  const run = (cwd, argv) => execFileSync("git", ["-C", cwd, "-c", "core.quotepath=false", ...argv], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 8000 })
   try {
-    const top = run(root, ["rev-parse", "--show-toplevel"]).trim()
-    const base = top || root
-    const changed = run(base, ["diff", "--name-only", "HEAD"]).split(/\r?\n/)
-    const untracked = run(base, ["ls-files", "--others", "--exclude-standard"]).split(/\r?\n/)
-    return { ok: true, base, files: [...changed, ...untracked].filter(Boolean) }
+    const top = run(root, ["rev-parse", "--show-toplevel"]).trim() || root
+    const files = run(top, ["diff", "--name-only", sha, "HEAD"]).split(/\r?\n/).filter(Boolean)
+    return { ok: true, base: top, files }
   } catch {
     return { ok: false, base: root, files: [] }
   }
@@ -69,15 +95,9 @@ function hitEntries(res, root) {
   return { aligned, entries }
 }
 
-/** 固定行里的定位片（`档:行`——取自命中行；取不到则退回相对路径）。 */
-function locationOf(entry, root) {
-  return /(\S+?\.md:\d+)/.exec(entry.line)?.[1] ?? relative(root, entry.file).replace(/\\/g, "/")
-}
-
-/** 报面组装：只换首行 + 插入本条附加行（其余行 = 引擎原样，不重写格式）；`dropDisposal` ⇒ 剔除引擎的
- *  「处置：同轮修正后复跑…」行（close 面 PASS 且命中全属他批在途时——该行会把读者引去改别人的档）。 */
-function composeReport(res, first, notes, dropDisposal) {
-  const lines = String(res.report).split("\n").filter((l) => !(dropDisposal && l.startsWith("处置：")))
+/** 报面组装：只换首行 + 插入本条附加行（其余行 = 引擎原样，不重写格式）。 */
+function composeReport(res, first, notes) {
+  const lines = String(res.report).split("\n")
   lines[0] = first
   if (notes.length) {
     const at = lines.findIndex((l) => l.startsWith("处置："))
@@ -88,7 +108,7 @@ function composeReport(res, first, notes, dropDisposal) {
 }
 
 /** 空范围返回形（`range` 恒在场——回执要读 `范围 N 档`）。 */
-const emptyRange = (basis) => ({ count: 0, k: 0, foreign: 0, basis })
+const emptyRange = (basis) => ({ count: 0, k: 0, basis })
 const errorState = (first, range = emptyRange("none")) => ({ state: "error", first, report: first, hitLines: [], noteLines: [], range })
 
 /**
@@ -96,7 +116,7 @@ const errorState = (first, range = emptyRange("none")) => ({ state: "error", fir
  * @param {{abs:string, cwd?:string, agent?:object, scope?:'writer'|'close'}} o
  *   `abs` = 目标批次档绝对路径（根解析用）；`agent._touchedFiles` = 触达记账。
  * @returns {{state:'pass'|'refused'|'error'|'not-applicable', first:string|null, report:string,
- *   hitLines:string[], noteLines:string[], range:{count:number, k:number, foreign:number, basis:string}}}
+ *   hitLines:string[], noteLines:string[], range:{count:number, k:number, basis:string}}}
  *   `first` = 唯一机判串（首行 `DOC-CHECK GATE:`）；`not-applicable` ⇒ `first = null` + 固定回执行。
  */
 export function runBatchGate({ abs, cwd, agent = {}, scope = "writer" } = {}) {
@@ -126,46 +146,42 @@ function evaluate({ abs, cwd, agent, scope }) {
   if (!read.ok && read.reason === "missing") {
     return { state: "not-applicable", first: null, report: "[doc-check gate] 未跑（本项目无声明面）", hitLines: [], noteLines: [], range: emptyRange("none") }
   }
-  // 范围（判谁）：writer = 写者触达账；close = 本批笔域集（触达账）∪ git 面。
+  // 范围（判谁）：writer = 写者触达账；close = 本批笔域集 = 触达账 ∪ 本批提交 diff（**单集**——
+  // 范围内不设第二集：工作树里范围外的档不入判、不入报面）。
   // 批档自身不入范围（载体不是判据对象——判它只会把载体的超段记成本批欠账）。
   const selfKey = pathKey(resolve(abs))
   const touched = docPaths(agent?._touchedFiles, base).filter((p) => pathKey(p) !== selfKey)
-  const git = close ? gitSurface(root) : { ok: false, base: root, files: [] }
-  const gitDocs = docPaths(git.ok ? git.files : [], git.base).filter((p) => pathKey(p) !== selfKey)
-  const docs = close ? [...new Set([...touched, ...gitDocs])] : touched
-  const basis = close ? (git.ok ? "touched+git" : "touched（git 面不可得）") : "touched"
+  const baseSha = close ? baseShaOf(abs) : null
+  const diff = baseSha ? committedDocs(root, baseSha) : { ok: false, base: root, files: [] }
+  const diffDocs = docPaths(diff.ok ? diff.files : [], diff.base).filter((p) => pathKey(p) !== selfKey)
+  const docs = close ? [...new Set([...touched, ...diffDocs])] : touched
+  const basis = !close ? "touched" : diff.ok ? "touched+diff" : "touched（基 sha 未定）"
   const res = runDocCheck(root, { mode: "gate", docs, docsSource: close ? "explicit" : "session" })
 
   const { aligned, entries } = hitEntries(res, root)
-  const ownKeys = new Set(touched.map(pathKey))
-  const own = close ? entries.filter((e) => ownKeys.has(pathKey(e.file))) : entries
-  const foreign = close ? entries.filter((e) => !ownKeys.has(pathKey(e.file))) : []
-  const k = own.length
+  const k = entries.length // 单集：命中数即 K（没有第二集可排除）
   const first = k >= 1
     ? `DOC-CHECK GATE: REFUSED（命中 ${k} 条）`
     : (res.checkFiles.length ? "DOC-CHECK GATE: PASS" : "DOC-CHECK GATE: PASS（0 档）")
 
-  // 附加行（只挂 close 面）：他批在途（逐档列出、不计入 K）+ 两条取基明示（不静默）。
+  // 附加行（不静默面）：命中行不可对齐（判定面自述）+ 收口面取不到基（只认触达账）。
   const notes = []
   if (!aligned) notes.push("命中行不可对齐（引擎报面 ✗ 行数与命中数不等）——显示行按自造形，判定按命中对象")
-  if (close) {
-    if (foreign.length) notes.push(`他批在途 ${foreign.length} 档（非本批笔域 · 未计入 K · 请其作者在其批修复）：${foreign.map((e) => locationOf(e, root)).join(" ∥ ")}`)
-    if (!git.ok) notes.push("git 面不可得——他批在途集只按触达账判（不静默）")
-    notes.push("基 sha 未定——本批笔域集只认触达账（git 提交面由父侧协议清单兜）")
-  }
+  if (close && !diff.ok) notes.push("基 sha 未定——本批笔域集只认触达账")
 
   return {
     state: k >= 1 ? "refused" : "pass",
     first,
-    report: composeReport(res, first, notes, k === 0 && foreign.length > 0),
+    report: composeReport(res, first, notes),
     hitLines: entries.map((e) => e.line),
     noteLines: notes,
-    range: { count: res.checkFiles.length, k, foreign: foreign.length, basis },
+    range: { count: res.checkFiles.length, k, basis },
   }
 }
 
 /** 成功回执行（append / close / status 三面同形；`null` 门 ⇒ 零改——非挂门路径回执逐字旧形）。
- *  附注行（他批在途逐档列出 ∥ 取基 / git 面明示）紧随其后**逐字**列出——不静默吞掉可见性。 */
+ *  两件 = verdict + `范围 N 档` 事实行；附注行（「基 sha 未定」∥ 命中行不可对齐）紧随其后**逐字**列出——
+ *  不静默吞掉可见性。 */
 export function gateReceiptLine(gate) {
   if (!gate) return ""
   if (gate.state === "not-applicable") return "\n[doc-check gate] 未跑（本项目无声明面）"
@@ -184,6 +200,6 @@ export function gateRefusalMessage(gate, action = "append") {
   const detail = gate.state === "error" ? String(gate.report ?? "").split("\n").slice(1) : gate.hitLines
   const tail = action === "append"
     ? "处置：同轮修正后复跑（改文档 ∥ 修引擎）；不转台账；拿不准 ⇒ 上抛主 agent 裁决（主 agent 拿不准 ⇒ 转呈用户）。Nothing was written. Do NOT close the record after a refused append — nothing landed, and closing freezes the missing section for good (失败 ⇒ 勿 close)."
-    : "处置：同轮修正后复跑（改文档 ∥ 修引擎）；不转台账；命中他批笔域 ⇒ 报告父侧转派作者；拿不准 ⇒ 上抛主 agent 裁决（主 agent 拿不准 ⇒ 转呈用户）。Nothing was written."
+    : "处置：同轮修正后复跑（改文档 ∥ 修引擎）；不转台账；拿不准 ⇒ 上抛主 agent 裁决（主 agent 拿不准 ⇒ 转呈用户）。Nothing was written."
   return [lead, gate.first, ...(detail ?? []), ...(gate.noteLines ?? []), tail].join("\n")
 }

package/agent-tools/batch-lifecycle.mjs

@@ -22,12 +22,22 @@
  *
  * 链完整性门（§4.18-A）：`close` ∥ `status` 写「已收口」两路在写盘前同过 `assertCloseoutChainComplete`
  * ——§2/§3/§4/§6 各段有内容 ∥ §1 声明不适用（仅 §2/§3/§4 可声明；§6 不可声明 · §5 段号豁免）；
- * 缺段 ⇒ 点名拒（门位 = 冻结拒写之后、文档机检门之前）。重开径（§4.18-B）：已收口档
+ * 缺段 ⇒ 点名拒（门位 = 冻结拒写之后、文档机检门之前）。
+ *
+ * 本批批内单测档门（`TESTING.md` §3.5 零留存的收口门）：同一两路在链门之后、文档机检门之前同过
+ * `assertUnitTestFilesCleared`——本批自己的单元测试档仍在盘 ⇒ 点名拒（单源叶档 =
+ * `batch-unit-test-gate.mjs`；判据 = 同目录最长批档名前缀归属）。门只拒、不代删。
+ *
+ * 重开径（§4.18-B）：已收口档
  * `status` §1 → 进行中 + `note` 非空 ⇒ 状态行改写 + §1 段尾追记行（只追加，其余行字节不变）。
  *
  * 收口重锚（§6.2 · C · AC-M2-30）：收口有两条通路——`close` ∥ `status` 写 §1「已收口」——两路都冻结档、
  * 都让批「收口了」，故**两路同调**单源 `reanchorOnClose`（本档下方），调点均在状态行写盘之后。
  * 一次收口只出一份 `[ledger reanchor]` 回执段（判据 = 前态未冻结：已冻结档在两路都被冻结门早拒）。
+ *
+ * 收口自动消费本批设计凭证（DESIGN-TOKEN-SETTLEMENT §10 · 2026-10-26）：同一两路在**写状态行之前**
+ * 调 `consumeBatchDesignTokens`（判据 = 槽的批次归属旁列；口径单源见该档 §10）。消费失败 ⇒ 原样上抛、
+ * close 被拒、档零字节变——位次与重锚（写盘之后）相反，这是机制本体（KD-BG3）。
  */
 import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs"
 import { dirname, relative, resolve } from "node:path"
@@ -39,6 +49,8 @@ import {
 } from "./batch-skeleton.mjs"
 import { resolveBatchCreatePath } from "./batch-paths.mjs"
 import { gateReceiptLine, gateRefusalMessage, runBatchGate } from "./batch-gate.mjs"
+import { assertUnitTestFilesCleared } from "./batch-unit-test-gate.mjs"
+import { batchPathKey, executeConsumeDesignAction, unionBatches, unionSlots } from "./design-slots.mjs"
 
 /** 可读文件判据（存在且为文件——目录/缺失同判不可读；与主档同名 helper 同型——KD-4 单向
  *  依赖下各自持有，三行谓词不构成第二权威源）。 */
@@ -397,7 +409,7 @@ function assertStatusNote(note) {
  * path 参数 = 仅 depth-0（D-BR21）——子代理/评审传 path ⇒ 拒（目标 = spawn/实例注入，语法上
  * 写不到别处）。F11-C 挂点 = 写盘前（assertStatusValue 后）：档头结构行含骨架死占位 ⇒ 拒
  * （段体引用豁免；close 不拦——收口是主 agent 终态动作）。
- * **收口第二通路**：值余核 = §1「已收口」时本 action 同样收口（链门 + 机检门 + 冻结与 close 同序）⇒
+ * **收口第二通路**：值余核 = §1「已收口」时本 action 同样收口（链门 + 批内单测档门 + 机检门 + 冻结与 close 同序）⇒
  * 状态行写盘后同调 `reanchorOnClose`（单源——不复制 close 径逻辑），回执携同一 `[ledger reanchor]` 段。
  * @returns {Promise<string>} 成功消息
  */
@@ -470,10 +482,15 @@ export async function statusBatchRecord({ args, ctx, review, pickTarget, onWritt
   // （`STATUS_WORDS[1].closed` 只属 §1 项，`assertStatusValue` 亦拒他段该值；显式 `seg === 1` 让不变量不靠巧合）。
   const closingValue = seg === 1 && stripDecorations(value) === STATUS_WORDS[1].closed
   if (closingValue) assertCloseoutChainComplete(src)
+  // 本批批内单测档门（`TESTING.md` §3.5——门位 = 链门之后、文档机检门之前）：本批自己的单元测试档
+  // 仍在盘 ⇒ 拒（零留存的结构兜底；两路同判——close 与 status 写「已收口」各过一次；放行零回执）。
+  if (closingValue) assertUnitTestFilesCleared(abs, "status")
   // ④ 文档机检门（§3.20「结构兜底」②——门位 = 链门之后、状态行改写之前）：值余核 =「已收口」时同门；
   // REFUSED（K ≥ 1）∥ ERROR ⇒ throw（§1 状态行字节不变）；其余值零挂（回执逐字旧形）。
   const gate = closingValue ? runBatchGate({ abs, cwd: ctx?.agent?.cwd ?? process.cwd(), agent: ctx?.agent ?? {}, scope: "close" }) : null
   if (gate && (gate.state === "refused" || gate.state === "error")) throw new Error(gateRefusalMessage(gate, "status"))
+  // 收口自动消费（§10——第二通路与 close 同效：位次 = 上两道门之后、状态行写盘之前）
+  const designTokens = closingValue ? consumeBatchDesignTokens(ctx?.agent ?? {}, abs) : null
   const written = updateSectionStatusLine(src, seg, lineValue)
   writeFileSync(abs, written)
   onWritten?.(ctx?.agent ?? {}, abs)
@@ -483,15 +500,15 @@ export async function statusBatchRecord({ args, ctx, review, pickTarget, onWritt
   // **一次收口只出一份清单**：触发 = `closingValue` ∧ 前态未冻结；`batch` 一次调用只分派一个 action
   // （close ∥ status 不会同拍）⇒ 同一拍至多一次重锚、至多一份 `[ledger reanchor]`。前一合取项 =
   // **defensive-only**：前态 closed 已被冻结门（`assertGateOpen`，本函数上方）早拒，正常路径跑不到这里。
-  const reanchor = closingValue && readBatchStatusLine(src) !== "closed" ? await reanchorOnClose(abs) : null
-  return `batch: §${seg} status line updated to ${JSON.stringify(lineValue)} — the freeze gate (§1) is a read-only domain for non-§1 writes (frozen truth stays = the §1 line).${gateReceiptLine(gate)}${reanchorReceiptLine(reanchor)}`
+  const reanchor = closingValue && readBatchStatusLine(src) !== "closed" ? await reanchorOnClose(abs, ctx?.agent?.cwd ?? process.cwd()) : null
+  return `batch: §${seg} status line updated to ${JSON.stringify(lineValue)} — the freeze gate (§1) is a read-only domain for non-§1 writes (frozen truth stays = the §1 line).${gateReceiptLine(gate)}${designTokensReceiptLine(designTokens)}${reanchorReceiptLine(reanchor)}`
 }
 
 /**
  * close——收口冻结（§4.13，仅 depth-0）。§1 状态行 →「已收口 <YYYY-MM-DD>」；此后该档
  * append/status 全拒（冻结判据唯一真值 = §1 行——§4.9 零语义变；唯一例外 = 重开合取 §4.18-B）。
  * 对已收口档再 close ⇒ 拒（close 本身是对冻结档的写）。不代写 §6 内容、不替代台账核销事务。
- * 前提规则（#422 + 本批 A 链门 §4.18-A）：① 链完整性门（收口前置——§2/§3/§4/§6 各段有内容 ∥ 声明
+ * 前提规则（#422 + A 链门 §4.18-A + 本批单测档门 §3.5）：① 链完整性门（收口前置——§2/§3/§4/§6 各段有内容 ∥ 声明
  * 不适用；§6 唯一缺段时拒串 = 旧 §6 串逐字零回归）；② 拒句含「失败 ⇒ 勿 close」（append/status 面
  * ——见 batch.mjs 与上方 assertGateOpen）；③ 无状态行档 ⇒ 自建机读位（updateSectionStatusLine
  * 缺失即插——同路收口；「有行但不可解析」仍 fail-closed）。
@@ -507,33 +524,86 @@ export async function closeBatchRecord({ args, ctx, review, pickTarget, onWritte
   // 链完整性门（§4.18-A——门位 = 既有拒因之后、文档机检门之前）：§2/§3/§4/§6 各段有内容 ∥ 声明
   // 不适用；缺段 ⇒ 拒并点名（§6 唯一缺段 = J2 旧串逐字）。含声明形不合判（J3——不静默当作无声明）。
   assertCloseoutChainComplete(src)
+  // 本批批内单测档门（`TESTING.md` §3.5——门位 = 链门之后、文档机检门之前）：本批自己的单元测试档
+  // 仍在盘 ⇒ 拒（零留存的结构兜底；`close` 与 `status` 写「已收口」两路同判；放行零回执）。
+  assertUnitTestFilesCleared(abs, "close")
   // 文档机检门（§3.20「结构兜底」②——门位 = 链门之后、状态行改写之前）：REFUSED（K ≥ 1）∥ ERROR
   // ⇒ throw（fail-closed，不落「已收口」）；PASS / 未跑（无声明面）⇒ 落盘 + 回执明示。
   const gate = runBatchGate({ abs, cwd: ctx?.agent?.cwd ?? process.cwd(), agent: ctx?.agent ?? {}, scope: "close" })
   if (gate.state === "refused" || gate.state === "error") throw new Error(gateRefusalMessage(gate, "close"))
+  // 收口自动消费本批设计凭证（§10——位次 = 全部拒因之后、写盘之前；失败 ⇒ 原样上抛、本函数拒）
+  const designTokens = consumeBatchDesignTokens(ctx?.agent ?? {}, abs)
   const date = todayLocal()
   const written = updateSectionStatusLine(src, 1, `已收口 ${date}`)
   writeFileSync(abs, written)
   onWritten?.(ctx?.agent ?? {}, abs)
   // 收口重锚（§6.2 · C · AC-M2-30）：顺序位 = 全部拒因通过、§1 状态行写盘**之后**（上两行）——close 被拒
   //（身份 ∥ 冻结 ∥ 链完整性门 ∥ 文档机检门）⇒ 台账零写（被拒的 close 没有收口，「原批已收口」那时是假事实）。
-  const reanchor = await reanchorOnClose(abs)
-  return `batch: §1 status line → 「已收口 ${date}」 — the record is frozen: append is refused from now on, and status is refused except the reopen conjunction (§1 → 进行中 with a note) (整档冻结；改 = 新批新档; §6 内容与台账核销仍走既有通道).${gateReceiptLine(gate)}${reanchorReceiptLine(reanchor)}`
+  const reanchor = await reanchorOnClose(abs, ctx?.agent?.cwd ?? process.cwd())
+  return `batch: §1 status line → 「已收口 ${date}」 — the record is frozen: append is refused from now on, and status is refused except the reopen conjunction (§1 → 进行中 with a note) (整档冻结；改 = 新批新档; §6 内容与台账核销仍走既有通道).${gateReceiptLine(gate)}${designTokensReceiptLine(designTokens)}${reanchorReceiptLine(reanchor)}`
+}
+
+// ─── 收口自动消费本批设计凭证（DESIGN-TOKEN-SETTLEMENT §10——单源，close ∥ status 两通路同调）──
+
+/** 「留槽无归属」枚数（§10 观测量）：并集视图里在旁列**无归属行**的槽数——含过期项（清点面
+ *  照列；过期槽同样撑开写门，正是敞口本身）。只认旁列：注册表反查是显示面兜底、不是消费判据
+ *  （旧槽不猜归属——KD-BG4）。 */
+function unattributedSlotCount(agent, batches) {
+  let n = 0
+  for (const id of unionSlots(agent).keys()) if (!batches.has(id)) n++
+  return n
+}
+
+/**
+ * 收口自动消费（DESIGN-TOKEN-SETTLEMENT §10——两通路共调本函数，不复制逻辑）。四步：
+ * ①非工程模式 ⇒ no-op（普通模式批无设计槽——槽只在工程模式评审 settle 时铸，`executeConsumeDesignAction` 同门）；
+ * ②反查 = 内存 Map ∪ 槽文件旁列（`unionBatches`，**严格读** `{strict:true}`——旁列读不到即抛 ⇒ close 被拒，
+ * §10「读形」；「没有」= 空集，不抛）取该 `abs` 名下的 designId 集；
+ * ③空集 ⇒ no-op（重开后再 close 走这条——该批槽已被上一轮消费）；
+ * ④调既有 `executeConsumeDesignAction({ designIds })`——单次落盘 + 内存整体回滚 + 逐枚回执全复用
+ * （KD-BG6：不新写落盘 / 回滚逻辑，否则同一份语义写第二遍、两处必漂）。
+ * **失败语义**：④抛 ⇒ **原样上抛**（消费核已把内存槽整体回滚）⇒ 调用方被拒、档零字节变、可重试——
+ * 「已收口而凭证仍在」正是本节要消掉的窗口，不把它降级成一句回执。
+ * @param {object} agent — 含 `config.agent.engineering` 与槽状态图
+ * @param {string} abs — 本批批档绝对路径（收口目标，`pickTarget` 解析所得）
+ * @returns {{consumed: number, unattributed: number}|null} 消费枚数 ∥ 留槽无归属枚数；`null` = no-op（非工程模式）
+ */
+export function consumeBatchDesignTokens(agent, abs) {
+  if (!agent?.config?.agent?.engineering) return null
+  const target = batchPathKey(abs)
+  const batches = unionBatches(agent, { strict: true })
+  const ids = [...batches]
+    .filter(([, b]) => typeof b === "string" && batchPathKey(b) === target)
+    .map(([id]) => id)
+  if (ids.length === 0) return { consumed: 0, unattributed: unattributedSlotCount(agent, batches) }
+  const held = unionSlots(agent) // 消费前态：与消费核同一并集视图（消费枚数 = 交集大小）
+  const consumed = ids.filter((id) => held.has(id)).length
+  executeConsumeDesignAction({ designIds: ids }, { agent })
+  return { consumed, unattributed: unattributedSlotCount(agent, batches) }
+}
+
+/** 收口回执的凭证段（§10 回执形：单列 `[design tokens]` 一行——消费枚数 ∥ 留槽无归属枚数）；
+ *  标签形与 `[ledger reanchor]` ∥ `[doc-check gate]` 一致（换行 + 方括号前缀）。`null`（普通模式
+ *  no-op）⇒ 无该段——回执逐字旧形。 */
+function designTokensReceiptLine(result) {
+  if (!result) return ""
+  return `\n[design tokens] 消费 ${result.consumed} 枚 · 留槽无归属 ${result.unattributed} 枚`
 }
 
 /** 收口重锚（设计档 §6.2 · C）——收口两条通路（`close` ∥ `status` 写 §1「已收口」）共调本函数（同一单源，
  *  不复制逻辑）；写入单源 = `ledgerReanchorBatch`（本档只供 `cwd` 基准与回执形；工具层零 SQL）。
- *  `cwd` = **批档所属项目根** = `resolveLedgerRoot(dirname(<batchDoc>))?.root`（§6.1 口径 2 同一子表达式）——
- *  **不用会话锚**：会话锚为工作区 ∥ 容器时可能收到别的项目根 ⇒ 选行零命中 ⇒ 唯一的机器写静默失效。
+ *  `cwd` = **批档所属项目根** = `resolveLedgerRoot(dirname(<batchDoc>), boundary)?.root`（§6.1 口径 2 同一子表达式）——
+ *  **不用会话锚**：会话锚为多根工作区时可能收到别的项目根 ⇒ 选行零命中 ⇒ 唯一的机器写静默失效。
+ *  `boundary` = 上溯上界 = **会话锚**（设计档 §3.8「界（单源）」——台账面同一枚界；缺则落进程 cwd）。
  *  无根 ⇒ 传 `null`（核心不取行、不重锚，`failed` 点名——不落兜底基准）。
  *  `batch` = 项目根相对路径（复启句的 `<批名>` 即其文件部分；绝对路径同样可解析，但句内会带整条绝对路径）。
  *  失败**不抛**（台账忙 ∥ 无根均不否决收口——档面写与台账库分属两存储，不做分布式事务）。 */
-async function reanchorOnClose(abs) {
+async function reanchorOnClose(abs, boundary) {
   try {
     const { ledgerReanchorBatch, resolveLedgerRoot } = await import("../ledger.mjs") // 动态 import：ledger-db 静态引 node:sqlite（W8 契约②）
-    const root = resolveLedgerRoot(dirname(abs))?.root ?? null
+    const root = resolveLedgerRoot(dirname(abs), boundary)?.root ?? null
     // 句内路径统一正斜杠（与 `task_book` 列值同形——`<批名>` 是给人读的事实句，不是平台路径）
-    return ledgerReanchorBatch({ cwd: root, batch: root ? relative(root, abs).replace(/\\/g, "/") : abs })
+    return ledgerReanchorBatch({ cwd: root, batch: root ? relative(root, abs).replace(/\\/g, "/") : abs, boundary })
   } catch (e) {
     // 非预期异常（模块加载失败 ∥ 根推导内读声明抛）同样不得否决收口——降为同一返回形（台账零写）
     return { batch: abs, reanchored: [], alreadyAnchored: [], failed: String(e?.message ?? e) }