@thincoder/core 0.10.8 → 0.10.9

package/CHANGELOG.md

@@ -5,6 +5,12 @@ Format: Keep a Changelog · 中文 · 号在发布时定（CalVer——见 `docs
 
 ## [Unreleased]
 
+## [0.10.9] — 2026-10-19
+
+### Removed
+
+- **`design-slots` 的 `reveal` 开关与掩蔽（token-visibility-simplify 批 2026-10-17）**：清点面改**直读**——逐槽行恒携 `designToken`（过期照列、`status` 自标态；记录畸形 ⇒ `—`）；删净 `reveal` 开关 / 掩蔽 / 一次一槽限制（用户裁定「没必要把 token 藏起来，agent 要就告诉他」）；签发链（mint / settle / TTL / persist）零改。
+
 ## [0.10.8] — 2026-10-16
 
 > 0.10.7 → 0.10.8（月内 +1——发布时定号）

package/agent/family-tools.mjs

@@ -125,8 +125,8 @@ export async function assembleFamilyTools({
           ...subagentTool,
           name: "subagent",
           description: designer
-            ? "Spawn a read-only `explore` sub-agent to SURVEY the current state for the design: it reads code / docs / existing designs and reports evidence with file:line. BLOCKING ONLY (no async) and action:'spawn' ONLY — the survey channel is read-only; escalate/status/cancel/panel/consume-design/observe/send are not available. Survey budget: ≤6 explore spawns per batch — the main agent's survey result is reference only; do your own."
-            : "Spawn a read-only `explore` sub-agent to AUDIT your delivery against the design: it compares the delivered code with the design for divergence — partially implemented acceptance criteria, silent simplifications, doc drift, changes outside the approved file list. BLOCKING ONLY (no async — the audit report decides your next protocol step). action:'spawn' ONLY — the audit channel is a read-only spawn; escalate/status/cancel/panel/consume-design/observe/send are not available. The audit task book is appended MECHANICALLY — your own spawn task (docs involved / acceptance criteria / file list) plus the files you actually touched; never hand the audit a self-written file list (a self-report could omit exactly the out-of-scope file it must catch).",
+            ? "Spawn a read-only `explore` sub-agent to SURVEY the current state for the design: it reads code / docs / existing designs and reports evidence with file:line. BLOCKING ONLY (no async) and action:'spawn' ONLY — the survey channel is read-only; escalate/status/cancel/panel/consume-design/observe/send are not available. Survey budget: ≤6 explore spawns per batch — the main agent's survey result is reference only; do your own. The spawn carries the five task-book parameters (four core: goal / knownFacts / acceptance / reportFormat + `scope`); a task-only spawn is refused."
+            : "Spawn a read-only `explore` sub-agent to AUDIT your delivery against the design: it compares the delivered code with the design for divergence — partially implemented acceptance criteria, silent simplifications, doc drift, changes outside the approved file list. BLOCKING ONLY (no async — the audit report decides your next protocol step). action:'spawn' ONLY — the audit channel is a read-only spawn; escalate/status/cancel/panel/consume-design/observe/send are not available. The audit task book is appended MECHANICALLY — your own spawn task (docs involved / acceptance criteria / file list) plus the files you actually touched; never hand the audit a self-written file list (a self-report could omit exactly the out-of-scope file it must catch). The spawn carries the five task-book parameters (four core: goal / knownFacts / acceptance / reportFormat + `scope`); a task-only spawn is refused.",
           parameters: { ...subagentTool.parameters, properties: props },
         }
       })()

package/agent/helpers.mjs

@@ -451,14 +451,14 @@ export const AUTO_TURN_DIGEST_DOMAIN =
 /** Engineering-mode auto-turn digest domain variant (mode = `agent.config.agent.engineering`;
  *  clause 2 drops the task-tool pointer — F10: the task tool is disabled in engineering mode,
  *  the batch record + ledger are the tracking authority). Single line, verbatim from the
- *  design doc (TOOLS.md §6.15.3); mechanism = AGENT-LOOP-ASYNC-POOL.md §6.8. Content authority = parent side. */
+ *  design doc (TOOLS.md §6.15.3); mechanism = AGENT-LOOP-ASYNC-POOL.md §6.8. Content basis = the mechanism doc; landing = eng-coder. */
 export const AUTO_TURN_DIGEST_DOMAIN_ENG =
   "[System reminder: auto-turn — background async subagents finished while there was no user message, and this turn runs automatically to digest their reports (the finished-report reminders above). No one is waiting for this reply, so organize only: 1) summarize each finished report's key points into this conversation for the user to read later; 2) (engineering mode: the task tool is disabled — no task-list update is expected this turn; the batch record + ledger are the tracking authority and are updated in real user turns); 3) write decision points with a suggested next step as text — do not execute it. FORBIDDEN this turn (mechanically enforced): modifying files, bash/execute/verify, spawning subagents, asking questions — those need a real user message. End the turn once the summaries are written.]"
 
 /** Up-stream wake-turn domain (AGENT-LOOP-UPSTREAM.md §6.27.12.8): a running subagent sent
  *  an in-flight message and is waiting for the reply — the digest domain's "No one is waiting
  *  for this reply" is the opposite of the truth, so the wake turn gets its own text.
- *  Verbatim from the design doc (single line — no newlines). Content authority = parent side. */
+ *  Verbatim from the design doc (single line — no newlines). Content basis = the mechanism doc; landing = eng-coder. */
 export const UPSTREAM_TURN_DOMAIN =
   "[System reminder: auto-turn — a running subagent sent you an in-flight message (shown below). No user message is waiting. Decide it now and reply with subagent action:'send' (id + message) — the child consumes the reply at its next turn boundary and keeps working on the unaffected parts; if the message needs no answer, say so in one line and move on. If finished subagent reports are also present above, summarize them as usual in the same turn. Do not start new work: FORBIDDEN this turn (mechanically enforced): modifying files, bash/execute/verify, spawning subagents, asking questions — those need a real user message. End the turn once the reply is sent.]"
 
@@ -466,16 +466,16 @@ export const UPSTREAM_TURN_DOMAIN =
  *  expired while the session was idle and the end's latch opened this turn automatically —
  *  neither the digest domain ("no one is waiting", organize-only) nor the up-stream domain
  *  (a subagent waiting for a reply) fits: the timer's own semantics is "act on what the
- *  timer was for". Verbatim from the parent-side final text (single line — no newlines).
- *  Content authority = parent side. */
+ *  timer was for". Verbatim from the mechanism doc (single line — no newlines).
+ *  Content basis = the mechanism doc; landing = eng-coder. */
 export const TIMER_TURN_DOMAIN =
   "[System reminder: auto-turn — a timer you set earlier has expired (reminder above). No user message is waiting. Act on what the timer was for now: pull the data or run the check rather than continuing to reason in the abstract. Stay within the work that was in flight when the timer was set; do not open unrelated new work. Wrap up as soon as the action is done or blocked.]"
 
 /** Digest-accounting requirement line (AGENT-LOOP-ASYNC-POOL.md §6.31.3 · batch digest-accounting ·
  *  2026-10-05)：消化轮账目要求——两档同发（手动 / AUTO）；manual 域文本只覆盖手动档 ⇒ 要求行
  *  独立常量承载，避免 AUTO 轮无要求。`<ids>` = 未销账 id 清单占位（动态拼 = digest-account.mjs
- *  `digestAccountRequirement`）；注入面 = transient（机器线独有）。Verbatim from the parent-side
- *  final text (single line — no newlines); content authority = parent side. */
+ *  `digestAccountRequirement`）；注入面 = transient（机器线独有）。Verbatim from the mechanism doc
+ *  (single line — no newlines). Content basis = the mechanism doc; landing = eng-coder. */
 export const DIGEST_ACCOUNT_DOMAIN =
   "[System reminder: digest accounting — for every report listed below as not yet accounted, emit exactly one line: \"[digest-ack #<id>] digested — <key points>\" (handled) or \"[digest-ack #<id>] deferred — <reason>\" (not handled). Not yet accounted: <ids>. Do not omit any.]"
 

package/agent/post-turn.mjs

@@ -10,6 +10,31 @@ export const STALL_WINDOW_SIZE = 5
 export const STALL_THRESHOLD = 3
 export const GOAL_BUDGET_WARN_RATIO = 0.75
 
+// 设计轮轮数注入阈值（AGENT-LOOP.md §6.6「设计轮轮数注入」· 台账 #1661）：
+// 5 = 在 persona 判定点（过 7 轮未落盘 ⇒ 降级）之前 3 轮给出计数；8 = 与 persona 同一判定点；
+// 15 = persona 的首版预算（注入串里的 15 一律由它插值——改常量即改注入文本，不另留字面）。
+export const DESIGN_TURN_NOTICE_AT = 5
+export const DESIGN_TURN_SKELETON_AT = 8
+export const DESIGN_FIRST_VERSION_TURNS = 15
+
+/**
+ * 设计轮轮数提醒（纯函数——注入串 | `null`；判据源 = 链内累计轮号 + 本设计轮是否落过盘）。
+ * 逐字注入形 = `AGENT-LOOP.md` §6.6「注入形逐字」；角色表当前一行（`eng-designer`），
+ * `eng-coder` 零注入（其零落笔面另由零落笔看门狗兜）。
+ * @param {{role?:string|null, turn?:number, wrote?:boolean}} o `turn` = 链内累计轮号（1 起）
+ * @returns {string|null}
+ */
+export function designTurnReminder({ role, turn, wrote } = {}) {
+  if (role !== "eng-designer") return null
+  const used = Number(turn ?? 0)
+  if (!Number.isFinite(used) || used < DESIGN_TURN_NOTICE_AT) return null
+  const budget = DESIGN_FIRST_VERSION_TURNS
+  if (used >= DESIGN_TURN_SKELETON_AT && !wrote) {
+    return `[System reminder: design round turn ${used}/${budget} — nothing has been written to disk yet. The 7-turn mark has passed with nothing landed: degrade the delivery NOW — write the skeleton (design doc + batch record §2) plus an unresolved list, then refine in place.]`
+  }
+  return `[System reminder: design round turn ${used}/${budget} — ${wrote ? "something has been written to disk" : "nothing has been written to disk yet"}. First version budget is ${budget} turns; past 7 turns with nothing landed the rule is a skeleton + unresolved list.]`
+}
+
 /**
  * Inject all post-turn events into agent history.
  * Must be called after every tool-execution turn within runAgent's loop.
@@ -66,5 +91,14 @@ export function injectPostTurn(agent, results, recentCallSigs, callbacks, turn,
     })
   }
 
+  // 设计轮轮数注入（AGENT-LOOP.md §6.6 · 台账 #1661）：轮号取 `_currentTurn`（链内累计、续跑不重置），
+  // 写入痕迹取 `_touchedFiles`（在 resume 保留集内 ⇒ 续跑段沿用前段痕迹）；段内 `turn` 形参不参与判据。
+  const designReminder = designTurnReminder({
+    role: agent._role,
+    turn: agent._currentTurn ?? 0,
+    wrote: (agent._touchedFiles ?? []).length > 0,
+  })
+  if (designReminder) agent.history.push({ role: "user", content: designReminder })
+
   callbacks.onTurnEnd?.(agent, turn)
 }

package/agent/run-stages.mjs

@@ -8,6 +8,9 @@
  */
 
 import { compressIfNeeded, compressFallback, COMPRESS_FAILURE_LIMIT } from "../context.mjs"
+// §6.17/D-CC32 溢出守卫（兜底，非主修）：预算面单源 requestBudget ∥ 再估面 contextUsage（与压缩判定同一函数）
+import { requestBudget } from "../config.mjs"
+import { contextUsage } from "../token-window.mjs"
 import { ensureAutoReminder, injectEngineeringReminder, ContinueError, snapshotGuard } from "./helpers.mjs"
 import { pushManifestStateReminder } from "./setup-reminders.mjs"
 import { cleanupConsultSessions } from "../agent-tools/consult.mjs"
@@ -84,6 +87,16 @@ export async function runCompactionCheck(agent, ctx) {
   // 其余全同（同 splitHistory / 同尾部预算 / 同摘要链 / 同回注 / 同基线失效）。
   const pending = agent._pendingCompact
   agent._pendingCompact = null
+  // 成功记账（§6.17：成功记账段抽局部——阈值面与守卫面共用同一段，零复制）
+  const bookkeepCompaction = () => {
+    agent._compressFailures = 0
+    agent._planReminderAtLen = 0 // After compression history shrinks, reset cadence so reminders resume
+    recentCallSigs.length = 0 // After compression history is rebuilt, reset stall detection counter
+    // Completion info (CONTEXT-COMPACTION §7 D-C2): { mode, tokensFreed, elapsedMs } —
+    // the TUI panel renders it; callers that ignore the arg keep prior onCompress semantics.
+    callbacks.onCompress?.(agent._lastCompressInfo ?? {})
+    ensureAutoReminder(agent)
+  }
   try {
     let compacted = await compressIfNeeded(
       agent, threshold, callbacks,
@@ -96,15 +109,7 @@ export async function runCompactionCheck(agent, ctx) {
       agent.history.push({ role: "user", content: compactNoopNote(), transient: true })
       compacted = await compressIfNeeded(agent, threshold, callbacks, compactionOverhead, signal)
     }
-    if (compacted) {
-      agent._compressFailures = 0
-      agent._planReminderAtLen = 0 // After compression history shrinks, reset cadence so reminders resume
-      recentCallSigs.length = 0 // After compression history is rebuilt, reset stall detection counter
-      // Completion info (CONTEXT-COMPACTION §7 D-C2): { mode, tokensFreed, elapsedMs } —
-      // the TUI panel renders it; callers that ignore the arg keep prior onCompress semantics.
-      callbacks.onCompress?.(agent._lastCompressInfo ?? {})
-      ensureAutoReminder(agent)
-    }
+    if (compacted) bookkeepCompaction()
   } catch (compressError) {
     // AbortError must not be swallowed: user cancellation must propagate
     if (compressError?.name === "AbortError" || signal?.aborted) throw compressError
@@ -122,6 +127,35 @@ export async function runCompactionCheck(agent, ctx) {
       if (compressFallback(agent)) callbacks.onCompress?.(agent._lastCompressInfo ?? {})
     }
   }
+
+  // 溢出守卫（CONTEXT-COMPACTION.md §6.17 / D-CC32——兜底，非主修；本缝 = catch 闭合后、返回前）。
+  // 判据 = maxTokensSource !== "absent" ∧ prompt 估算 > limit（limit = window − reserve，恒为数）。
+  // **判据不用 maxTokens**：未发时为 undefined ⇒ NaN ⇒ 守卫静默失效（§6.17）；absent 档客户端未预留
+  // ⇒ 守卫不覆盖（服务端 400 兜——把规格 maxOutput 当实发判会让 doubao 三行永久发不出去）。
+  // 真 ⇒ 以 force 强制压缩一次（先压再判）；再估仍超 ⇒ 抛三实数、回合请求零发。不截断、不静默削输出。
+  const budget = requestBudget(agent.provider)
+  if (budget.maxTokensSource !== "absent") {
+    let usage = contextUsage(agent, compactionOverhead)
+    if (usage.total > budget.limit) {
+      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
+      }
+    }
+  }
 }
 
 /**

package/agent/setup.mjs

@@ -22,8 +22,8 @@ import { assembleFamilyTools } from "./family-tools.mjs"
 import { normalizeOrigin } from "../memory/origin.mjs"
 import { searchOrigins } from "../memory/code-search.mjs"
 import { INDEX_ORIGIN_ROW_WARN } from "../memory/schema.mjs"
+import { resolveCompactThreshold } from "../config.mjs"
 
-const DEFAULT_COMPACT_THRESHOLD = 100_000
 const DOC_SEARCH_LIMIT = 5
 const DOC_CHUNK_PREVIEW_LEN = 300
 /** UTF-16 安全截断（2026-09-02 deepseek 400 根因）：slice(0, N) 按码元切会把 emoji 代理对切成孤立
@@ -51,7 +51,9 @@ export async function prepareRun(agent, input, callbacks, {
   injections = null, toolDecorate = undefined,
 } = {}) {
   const maxTurns = overrideTurns ?? agent.config?.agent?.maxTurns ?? DEFAULT_MAX_TURNS
-  const threshold = agent.config?.agent?.compactThreshold ?? DEFAULT_COMPACT_THRESHOLD
+  // §6.17 每 run 现算：数值在场 = 显式原样；不在场 = auto 现算（按在用 provider——切模型后下一 run 跟手）。
+  // 派生值不落 agent.compactThreshold（显式键永不被改写）。
+  const threshold = resolveCompactThreshold(agent.config?.agent?.compactThreshold, agent.provider).value
   // 注入开关（PROMPT-SYSTEM.md §6.24 · 台账 #1420）：判据 `!== false`（缺省 = 现行为零变）——
   // 逐 run 现读 `agent.config` ⇒ `settings` 工具 ∕ `/config` 写入后本会话下一次组装即生效。
   const injectDocs = agent.config?.agent?.injectDocs !== false
@@ -62,6 +64,12 @@ export async function prepareRun(agent, input, callbacks, {
 
   agent._lastPromptTokens = null
   agent._usageAtLen = null
+  // 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.
+  agent._cacheHitTokens = 0
+  agent._cacheMissTokens = 0
+  agent._usageTurns = 0
   agent.history = repairHistory(agent.history)
 
   if (!resume) {

package/agent/turn-loop.mjs

@@ -180,6 +180,12 @@ export async function runTurnLoop(agent, {
 
     if (response.usage) {
       callbacks.onUsage?.(response.usage)
+      // Core-side cumulative cache tally (batch 2026-10-18-context-cache-visibility):
+      // every agent (parent or child) keeps its own hit/miss so `context` can report
+      // cache efficiency instead of the terminal faces being the only tally holders.
+      agent._cacheHitTokens = (agent._cacheHitTokens ?? 0) + (response.usage.prompt_cache_hit_tokens ?? 0)
+      agent._cacheMissTokens = (agent._cacheMissTokens ?? 0) + (response.usage.prompt_cache_miss_tokens ?? 0)
+      agent._usageTurns = (agent._usageTurns ?? 0) + 1
       if (response.usage.prompt_tokens != null) {
         agent._lastPromptTokens = response.usage.prompt_tokens
         agent._usageAtLen = agent.history.length

package/agent-tools/audit-block.mjs

@@ -23,9 +23,11 @@
  */
 export function summarizeEngTaskBook(taskInput) {
   if (!taskInput) return "(unavailable)"
+  // 五项拼装形下，`designPoints` 一段同时承载「设计档落点」与「受影响文件清单」——
+  // 前两段同取该块是有意的（语义都在其中）；代价 = 摘要里该块出现两次，不是抽取失败。
   const SECTIONS = [
-    { name: "Design docs involved", markers: [/Docs? involved/i, /涉及文档/] },
-    { name: "Affected-file list", markers: [/Files? (?:list|to (?:modify|change)|modified)/i, /受影响文件/, /文件清单/, /涉及文件/] },
+    { name: "Design docs involved", markers: [/Docs? involved/i, /涉及文档/, /^Design points/i] },
+    { name: "Affected-file list", markers: [/Files? (?:list|to (?:modify|change)|modified)/i, /受影响文件/, /文件清单/, /涉及文件/, /^Design points/i] },
     { name: "Acceptance criteria", markers: [/Acceptance(?: criteria)?/i, /验收标准/] },
   ]
   const lines = taskInput.split("\n")

package/agent-tools/batch-gate.mjs

@@ -0,0 +1,198 @@
+/**
+ * agent-tools/batch-gate.mjs — 文档机检门（`batch` 工具两机械点的**单源门**）。
+ *
+ * 权威规格 = `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）；命中 ⊆ 他批在途集 ⇒ 不阻收口 + 固定行逐档列出。
+ *
+ * 判据零变：本档不新增判据——只决定「判谁」与「何时强制」；判据与裁定串由产品引擎
+ * `doc-check/index.mjs` 产出（判据源唯一）。引擎版本前置同源 = `doc-check/version.mjs`。
+ *
+ * 两条边界（设计与实测同口径）：① **批档自身不入范围**（载体不是判据对象；声明域已排除 `batches`，
+ * 传入只产「跳过域外」行 = 假检查）；② **本轮提交面不在工具面**——`<批起 sha>` 只有父侧掌握，
+ * ② 的写入集只认触达账 + 回执明示「基 sha 未定」，提交面由父侧协议清单兜（不静默）。
+ */
+import { execFileSync } from "node:child_process"
+import { relative, resolve } from "node:path"
+
+import { owningProject, readManifest } from "../manifest.mjs"
+import { runDocCheck } from "../doc-check/index.mjs"
+import { firstVerdictLine, gateEngineError, staleEngineFiles } from "../doc-check/version.mjs"
+import { batchProjectRoot } from "./batch-paths.mjs"
+
+/** 平台路径键（win32 大小写不敏感——只作集比对，非判据面）。 */
+const pathKey = (p) => (process.platform === "win32" ? p.toLowerCase() : p)
+
+/** 文档档谓词 + 绝对化（触达账 / git 面同形；非 `.md` 不进范围）。 */
+const isDocPath = (p) => typeof p === "string" && p.trim() !== "" && p.toLowerCase().endsWith(".md")
+function docPaths(list, base) {
+  const out = []
+  for (const p of Array.isArray(list) ? list : []) if (isDocPath(p)) out.push(resolve(base, p))
+  return out
+}
+
+/**
+ * git 面（他批在途集候选——只取清单，域求交归引擎）：`git diff --name-only HEAD` ∪ 未跟踪档。
+ * 路径以**仓根**（`rev-parse --show-toplevel`）为基还原——项目根住大仓子目录时条目不丢（清单相对仓根）。
+ * 不可得（非仓 / 无 git）⇒ `ok: false` + 空集（调用面回执明示「git 面不可得」，不静默）。
+ */
+function gitSurface(root) {
+  const run = (cwd, argv) => execFileSync("git", ["-C", cwd, ...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) }
+  } catch {
+    return { ok: false, base: root, files: [] }
+  }
+}
+
+/** 命中 → `{ aligned, entries }`：`file` = 判定用（引擎给绝对路径）；显示行取引擎已产出的 `✗` 行
+ *   （报面单源不重写）；行数与命中数不等（引擎报面行序变动）⇒ `aligned: false` + 自造行，由调用面回执明示。 */
+function hitEntries(res, root) {
+  const lines = res.report.split("\n").filter((l) => l.startsWith("✗ "))
+  const hits = [...res.anchorHits, ...res.widthHits]
+  const aligned = lines.length === hits.length
+  const entries = hits.map((h, i) => ({
+    file: h.file,
+    line: aligned ? lines[i] : `✗ ${relative(root, h.file).replace(/\\/g, "/")}:${h.line}`,
+  }))
+  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("处置：")))
+  lines[0] = first
+  if (notes.length) {
+    const at = lines.findIndex((l) => l.startsWith("处置："))
+    if (at >= 0) lines.splice(at, 0, ...notes)
+    else lines.push(...notes)
+  }
+  return lines.join("\n")
+}
+
+/** 空范围返回形（`range` 恒在场——回执要读 `范围 N 档`）。 */
+const emptyRange = (basis) => ({ count: 0, k: 0, foreign: 0, basis })
+const errorState = (first, range = emptyRange("none")) => ({ state: "error", first, report: first, hitLines: [], noteLines: [], range })
+
+/**
+ * 跑一次门（**非抛错**：三因之外的门自身异常收为 `error` 态，由调用面按 `scope` 消费）。
+ * @param {{abs:string, cwd?:string, agent?:object, scope?:'writer'|'close', clock?:object}} o
+ *   `abs` = 目标批次档绝对路径（根解析用）；`agent._touchedFiles` = 触达记账；`clock` = 版本判定的测试注入缝。
+ * @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}}}
+ *   `first` = 唯一机判串（首行 `DOC-CHECK GATE:`）；`not-applicable` ⇒ `first = null` + 固定回执行。
+ */
+export function runBatchGate({ abs, cwd, agent = {}, scope = "writer", clock } = {}) {
+  // `scope` 两取值、无第三值（设计「`scope` 语义」）——未知值不静默降级（降级即 ② 变 fail-open）
+  if (scope !== "writer" && scope !== "close") {
+    return errorState(`DOC-CHECK GATE: ERROR（未知 scope：${JSON.stringify(scope)}——取值只有 "writer" ∥ "close"）`)
+  }
+  try {
+    return evaluate({ abs, cwd, agent, scope, clock })
+  } catch (e) {
+    const first = `DOC-CHECK GATE: ERROR（门自身异常：${e?.message ?? String(e)}）`
+    return errorState(first)
+  }
+}
+
+/** 门体（正常路径——异常由上抛给 `runBatchGate` 收口）。 */
+function evaluate({ abs, cwd, agent, scope, clock }) {
+  const base = resolve(cwd ?? process.cwd())
+  const root = owningProject(resolve(abs)) ?? batchProjectRoot(base)
+  const close = scope === "close"
+
+  let read
+  try { read = readManifest(root) } catch (e) {
+    return errorState(`DOC-CHECK GATE: ERROR（manifest 不可读 —— ${e?.message ?? String(e)}）`)
+  }
+  // 适用面（声明面驱动）：无 manifest ⇒ 不适用 + 回执明示；**不是豁免清单**——判据参数来自 checkConfig。
+  if (!read.ok && read.reason === "missing") {
+    return { state: "not-applicable", first: null, report: "[doc-check gate] 未跑（本项目无声明面）", hitLines: [], noteLines: [], range: emptyRange("none") }
+  }
+  // 引擎版本前置（fail-closed）：stale ⇒ 直接 ERROR 串，不进引擎（不产 PASS）。
+  const version = staleEngineFiles(clock ?? {})
+  if (version.stale.length) {
+    const report = gateEngineError(version)
+    return { state: "error", first: firstVerdictLine(report), report, hitLines: [], noteLines: [], range: emptyRange("none") }
+  }
+
+  // 范围（判谁）：writer = 写者触达账；close = 本批笔域集（触达账）∪ git 面。
+  // 批档自身不入范围（载体不是判据对象；声明域已排除 batches ⇒ 传入只产「跳过域外」行 = 假检查）。
+  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 res = runDocCheck(root, { mode: "gate", docs, docsSource: close ? "explicit" : "session" })
+  if (res.error) return { state: "error", first: firstVerdictLine(res.report), report: res.report, hitLines: [], noteLines: [], range: { count: res.checkFiles.length, k: 0, foreign: 0, basis } }
+
+  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 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 提交面由父侧协议清单兜）")
+  }
+
+  return {
+    state: k >= 1 ? "refused" : "pass",
+    first,
+    report: composeReport(res, first, notes, k === 0 && foreign.length > 0),
+    hitLines: entries.map((e) => e.line),
+    noteLines: notes,
+    range: { count: res.checkFiles.length, k, foreign: foreign.length, basis },
+  }
+}
+
+/** 成功回执行（append / close / status 三面同形；`null` 门 ⇒ 零改——非挂门路径回执逐字旧形）。
+ *  附注行（他批在途逐档列出 ∥ 取基 / git 面明示）紧随其后**逐字**列出——不静默吞掉可见性。 */
+export function gateReceiptLine(gate) {
+  if (!gate) return ""
+  if (gate.state === "not-applicable") return "\n[doc-check gate] 未跑（本项目无声明面）"
+  const head = `\n[doc-check gate] ${gate.first} · 范围 ${gate.range?.count ?? 0} 档`
+  return [head, ...(gate.noteLines ?? []).map((l) => `\n${l}`)].join("")
+}
+
+/**
+ * 拒绝串（throw 载荷；两机械点同源措辞）：`batch:` 前缀 + verdict 首行 + 逐条 `✗` 行 + 处置句；
+ * ① 追加同路既有句「失败 ⇒ 勿 close」（字面同 append 既有拒因，不新造措辞）。
+ */
+export function gateRefusalMessage(gate, action = "append") {
+  const lead = action === "append"
+    ? "batch: 文档机检门拒写（doc-check gate · 结构兜底 ①）—— 本次段写入未落盘，档字节不变。"
+    : `batch: 文档机检门拒收口（doc-check gate · 结构兜底 ②）—— ${action === "close" ? "close" : "status → 已收口"} 被拒绝，§1 状态行字节不变。`
+  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."
+  return [lead, gate.first, ...(detail ?? []), ...(gate.noteLines ?? []), tail].join("\n")
+}