@thincoder/core 0.9.3 → 0.9.5

package/CHANGELOG.md

@@ -3,6 +3,46 @@
 All notable changes to the core package are documented here.
 Format: Keep a Changelog · 中文 · 号在发布时定（CalVer——见 `docs/RELEASE.md` §4）。
 
+## [0.9.5] — 2026-09-25
+
+> 0.9.4 → 0.9.5（月内序号——发布时定号）
+
+### Added
+
+- **规格表覆盖扩面（新名专行）**：`qwen-flash` / `qwen-vl-max`（实测输出上限 32_768——服务端直报 `[1, 32768]`；前者思考默认可开、后者不支持）、`claude-fable-5.1`（1_000_000 / 128_000）、`gemini-3.1-pro`（1_048_576 / 65_536）、`stepfun/step-3.7-flash`（262_144）；kimi-code 平台三行（`kimi-for-coding` / `kimi-for-coding-highspeed` / `k3-256k`——含 effort 枚举与默认档）——掉兜底名不再退默认。
+- **bench 受测 10 档规格行**：此前经泛前缀/兜底解析的受测模型补独立行 + 视觉声明分态登记。
+- **跨实例意图认领层（P1）**：`peers/{sessionId}.json` 增 claims 意图域（TTL 30 分钟租约 · 进程死亡即失效）；写前命中他实例活认领 ⇒ 软提示（不阻写；与写后足迹登记分开存）。
+
+### Changed
+
+- **提示词面**：`question` 工具从子代理工具表排除（子代理无提问通道——可见但不可用，不再注入）；子代理**在途提问通道**（问询即上抛，不等收尾）与「矛盾要求 ⇒ 立即 ask、不得自行解套」自止边界落档（common + 各人格面）。
+- **`glm-5.3-flash` 行 `maxOutput` 128_000 → 131_072**（校验级实测；本体 `glm-5.3` 128_000 冻结零改）。
+
+### Removed
+
+- **`cacheMode` 字段整体删除**：全仓零判据消费的死字段（假能力位——看着像能力声明、实际零行为）；表键 / 行注 / `DEFAULT_SPEC` / 注释提及字面清零。
+
+### Fixed
+
+- **deepseek 预设 `maxTokens` 393_216 → 384_000**（对齐规格行——消 K×1024 vs 十进制口径差；预置 ≤ 规格不变式 + 历史超限白名单锁定）。
+- **edit 工具非数组 `edits` 入参** ⇒ 成形错误（原裸 `TypeError` 外泄；core 与 ACP 桥同收）。
+- **台账库键跨端归一**（盘符大小写 ⇒ 同项目双库）+ `ledger-migrate` 迁移引擎（备份两道 → dry-run → confirm → 记存根审计；源库进回收不删）。
+- **batch 工具相对路径基底统一**（create / append / 评审门 / spawn 门四调用点单源解析 + 防嵌套 fail-closed）。
+- **会话 GC 加固**：无主会话清扫（无活属主 + cwd 不可达/空 + 7 天窗收口）· 多处指针/文句收正。
+
+## [0.9.4] — 2026-09-22
+
+> 0.9.3 → 0.9.4（月内序号——发布时定号）
+
+### Added
+
+- **MiMo V2.6 三款规格行**（`mimo-v2.6-pro` / `mimo-v2.6-flash` / `mimo-v2.6-pro-ultraspeed`——同日上架）：此前缺行落兜底（128K / 32K / 无视觉），现按真机实测登记——1M 上下文 · 131_072 输出 · 思考默认开（`thinking.type`）· 全模态 · 自动缓存。
+
+### Changed
+
+- **MiMo v2.5 两行存量对齐**（同日实测）：`maxOutput` 128_000 → 131_072 + 补自动缓存登记；族头注与 `assistantToolCallMessage` 文书句按 2026-09-22 复测改写（原「缺字段 → 400」句已不可复现——回显策略保持保守不变）。
+- **MiMo 预设改指**：`mimo` / `mimoplan` 默认模型 → `mimo-v2.6-pro`（v2.5 官网标注即将下线；Token Plan 端点同平台推断）。
+
 ## [0.9.3] — 2026-09-22
 
 > 0.9.2 → 0.9.3（月内序号——发布时定号）

package/advisor/loop.mjs

@@ -40,8 +40,8 @@ function advisorCodeSearchTool(agent) {
 
 function advisorToolsFor(agent, reviewType = "code", batchDoc = null) {
   const tools = [readTool, globTool, grepTool, lsTool, lspTool, advisorCodeSearchTool(agent)]
-  // §2.20.3（第 4 批）：**只有绑定了批次档的设计评审**额外拿到写通道——代码评审工具集
-  // 逐字节不变（零 git + 只读不变量，§2.20.8 #1）；未绑定 → 不挂载（fail-closed）。
+  // BATCH-RECORD.md §4.3（第 4 批）：**只有绑定了批次档的设计评审**额外拿到写通道——代码评审工具集
+  // 逐字节不变（零 git + 只读不变量，BATCH-RECORD.md §4.7 #1）；未绑定 → 不挂载（fail-closed）。
   if (reviewType === "design" && batchDoc) tools.push(batchTool(batchDoc, { review: true }))
   return { schemas: tools.map(toOpenAISchema), byName: new Map(tools.map((t) => [t.name, t])) }
 }

package/advisor/run.mjs

@@ -122,7 +122,7 @@ export async function runAdvisorReview(agent, reviewType, callbacks, designToken
     }
   }
 
-  // §2.20.3 批次档写通道的绑定（仅设计评审）：同步路径 = 调用方（advisor 工具）传入的
+  // BATCH-RECORD.md §4.3 批次档写通道的绑定（仅设计评审）：同步路径 = 调用方（advisor 工具）传入的
   // callbacks.batchDoc（即 resolved.run 的实例绑定）；异步路径 = 本实例在跑池条目的
   // run.batchDoc（同文档集实例键——各评审各取各档，不用单值会话态）。
   const boundBatchDoc = reviewType === "design" ? batchDocForReview(agent, documents, callbacks) : null

package/agent/dispatch.mjs

@@ -6,9 +6,9 @@ import { offloadToolResult, FILE_MUTATORS } from "./helpers.mjs"
 import { runHooks } from "../hooks.mjs"
 import { snapshotForUndo } from "../undo-stack.mjs"
 import { isCodePath, loadConventions } from "../conventions.mjs"
-// R10 L3 (MULTI-INSTANCE-COLLAB §2a.5 D-L3b)：写工具钩子——peerCollabNote（执行前冲突
-// 检测——软提示不阻止）+ recordPeerWrites（成功后累积本回合写足迹——回合末 flush）。
-import { PEER_WRITE_TOOLS, peerCollabNote, recordPeerWrites } from "../peer-domains.mjs"
+// R10 L3 (MULTI-INSTANCE-COLLAB §2a.5 D-L3b / §4.4 D-MI17–D-MI21)：写工具钩子——peerCollabNote
+// （执行前冲突与认领命中检测——软提示不阻止）+ recordPeerWrites（成功后足迹与认领登记）。
+import { PEER_WRITE_TOOLS, peerCollabNote, recordPeerWrites, markClaimNoted } from "../peer-domains.mjs"
 import { writeFileSync, mkdirSync, existsSync } from "node:fs"
 import { join, resolve, relative } from "node:path"
 import { homedir } from "node:os"
@@ -51,18 +51,18 @@ function logToolError(toolName, args, error) {
 }
 
 /**
- * §19 action-level classification (AGENT-LOOP.md §19 D-M1): the merged subagent
+ * action-level classification (AGENT-LOOP-SUBAGENT.md §6.7 D-M1): the merged subagent
  * tool expresses spawn (side effect) and status (read-only query) through
  * its `action` parameter — the tool-level readonly flag can no longer express both.
  * dispatch Phase-1/Phase-2 classifies per action: status behaves as readonly
  * (planMode pass / no permission ask / batchable), spawn keeps its non-readonly
  * gates, escalate runs non-readonly AND serially (the retired escalate tool had no
  * parallel flag — zero behavior change under the merged surface).
- * §19.5 cancel (19.5.2b round2 #4): CONTROL-class exemption — cancel only
+ * AGENT-LOOP-SUBAGENT.md §6.7.2 cancel (19.5.2b round2 #4): CONTROL-class exemption — cancel only
  * stops, never starts. isSubagentControlAction feeds the SAME two gate sites as
  * readonly (planMode pass / no permission ask — never joins a batch approval
  * group / no handler → not denied — digest 内 cancel 放行).
- * §19.6 panel (round1 #5): view 面归只读类（同 status——planMode 放行、免
+ * AGENT-LOOP-SUBAGENT.md §6.7.2 panel (round1 #5): view 面归只读类（同 status——planMode 放行、免
  * 审批、可批并行）；freeze 面归控制类（同 cancel——planMode 放行、免权限审批、
  * 批审批不入组、digest 内放行）。freeze 存在（非空 key）即控制类——否则只读类。
  */
@@ -83,11 +83,11 @@ function isSubagentReadonlyAction(toolName, args) {
   }
   if (toolName !== "subagent" || !args || typeof args !== "object") return false
   const action = args.action
-  // §19.8: check 动作已删除——只读面仅剩 status（planMode 放行/免权限审批/可批并行）
+  // AGENT-LOOP-SUBAGENT.md §6.7.5: check 动作已删除——只读面仅剩 status（planMode 放行/免权限审批/可批并行）
   if (action === "status") return true
   // SUBAGENT-OBSERVE-SEND：observe = readonly 查询（同 status——digest/planMode 放行）
   if (action === "observe") return true
-  // §19.6 panel view 面（freeze 缺省/空 = 视图请求——readonly；非空 freeze 归控制类）
+  // AGENT-LOOP-SUBAGENT.md §6.7.2 panel view 面（freeze 缺省/空 = 视图请求——readonly；非空 freeze 归控制类）
   if (action === "panel" && (args.freeze === undefined || args.freeze === null || String(args.freeze) === "")) return true
   return false
 }
@@ -97,7 +97,7 @@ function isSubagentControlAction(toolName, args) {
   // SUBAGENT-OBSERVE-SEND：send = 控制类豁免（同 cancel——父回合内显式调用即授权——
   // 写子输入队列属父对子轻量引导，非产品代码写——免审批、planMode 放行、digest 内放行）
   if (args?.action === "send") return true
-  // §19.6 panel freeze 面（D-P3 门控在 executor——只读/控制分类在此）
+  // AGENT-LOOP-SUBAGENT.md §6.7.2 panel freeze 面（D-P3 门控在 executor——只读/控制分类在此）
   if (args?.action === "panel" && args.freeze !== undefined && args.freeze !== null && String(args.freeze) !== "") return true
   return false
 }
@@ -352,11 +352,11 @@ export async function executeToolCalls(agent, toolByName, toolCalls, callbacks,
     const toolName = item.toolCall.name
     logEvent("tool:call", { tool: toolName, child: agent?._logId })
     try {
-      // R10 L3 (MULTI-INSTANCE-COLLAB §2a.5 D-L3b)：结构化写工具执行前查 conflicts
-      // （命中他实例 hot 域 → 结果附软提示——决策⑥ A 不阻止；一次目录 stat——N3 度量）；
-      // 足迹累积（D-L3a——"检测+记录一次完成"）延后到执行成功（实际写过的文件）。
+      // R10 L3 (MULTI-INSTANCE-COLLAB §2a.5 D-L3b / §4.4.4)：结构化写工具执行前查冲突与认领
+      // 命中（软提示——决策⑥ A 不阻止；一次目录 stat——N3 度量）；足迹累积（D-L3a——"检测+
+      // 记录一次完成"）与认领登记延后到执行成功（实际写过的文件）。
       const isPeerWriteTool = PEER_WRITE_TOOLS.has(toolName)
-      const peerNote = isPeerWriteTool ? peerCollabNote(agent.cwd, item.tool, item.args) : null
+      const peerNote = isPeerWriteTool ? peerCollabNote(agent, item.tool, item.args) : null
       // Snapshot for undo before side-effect tools (setupOutputPanel already fired in Phase 1)
       if (!item.tool?.readonly && item.args) {
         snapshotForUndo(agent, item.toolCall.name, item.args, agent.cwd)
@@ -367,7 +367,8 @@ export async function executeToolCalls(agent, toolByName, toolCalls, callbacks,
         const routed = await callbacks.toolRouter(item.toolCall.name, item.args)
         if (routed?.handled) {
           const routedOk = !String(routed.result).startsWith("Error:")
-          const routedResult = peerNote && routedOk ? `${routed.result}\n${peerNote}` : routed.result
+          const routedResult = peerNote && routedOk ? `${routed.result}\n${peerNote.text}` : routed.result
+          if (peerNote && routedOk) markClaimNoted(agent, peerNote.keys) // 提示已附加 ⇒ 落去重标记
           if (isPeerWriteTool && routedOk) recordPeerWrites(agent, item.tool, item.args)
           // §29 fix A：routed 写成功（客户端执行）同样执行期即刻记账（唯一记账点）
           if (routedOk && FILE_MUTATORS.has(toolName)) noteExecutedMutation(agent, item.tool, item.args)
@@ -434,9 +435,11 @@ export async function executeToolCalls(agent, toolByName, toolCalls, callbacks,
       const resultWithConsole = capturedConsole.length > 0
         ? `${result}\n[console during ${item.toolCall.name}]\n${capturedConsole.join("\n")}`
         : result
-      // R10 L3：冲突软提示附在工具结果末尾（模型可见——不阻止写）
-      const resultForModel = peerNote && !raw.startsWith("Error:")
-        ? `${resultWithConsole}\n${peerNote}`
+      // R10 L3：冲突 / 认领软提示附在工具结果末尾（模型可见——不阻止写；提示附加成功才落去重标记）
+      const notedOk = Boolean(peerNote) && !raw.startsWith("Error:")
+      if (notedOk) markClaimNoted(agent, peerNote.keys)
+      const resultForModel = notedOk
+        ? `${resultWithConsole}\n${peerNote.text}`
         : resultWithConsole
       callbacks.onToolResult?.(item.toolCall.name, resultForModel, item.toolCall.id, toolCtx._subagentKey)
       // PostToolUse hooks: fire-and-forget (result not awaited on hook failure)
@@ -478,7 +481,7 @@ export async function executeToolCalls(agent, toolByName, toolCalls, callbacks,
   }
   for (const item of prepared) {
     // escalate action keeps the retired escalate tool's serial placement (no
-    // parallel flag): it flushes the batch and runs alone in call order (§19 —
+    // parallel flag): it flushes the batch and runs alone in call order (AGENT-LOOP-SUBAGENT.md §6.7 —
     // spawn stays parallel; status classifies as readonly and batch freely).
     if (item.tool && !item.tool.readonly
         && (!item.tool.parallel || isSubagentEscalateAction(item.tool.name, item.args))) {

package/agent/family-tools.mjs

@@ -63,7 +63,7 @@ export async function assembleFamilyTools({
       properties: {
         ...subagentTool.parameters.properties,
         role: { ...subagentTool.parameters.properties.role, ...subagentRoles },
-        // §19: escalate 动作的候选池 = consultModels（缺省池首 / 指定 provider:model）。
+        // AGENT-LOOP-SUBAGENT.md §6.7: escalate 动作的候选池 = consultModels（缺省池首 / 指定 provider:model）。
         // 池装饰挂在 action 属性描述（原 escalate 工具注册时 withPool 同款意图——模型
         // 需要知道可选候选人）。escalate 在工程模式禁用——装饰只对正常模式有意义。
         action: (consultModels.length && !engineering)
@@ -80,15 +80,15 @@ export async function assembleFamilyTools({
   // §18 D-E3 + ENGINEERING-MODE.md §2.15 D（第 2 批——参数化复用，不并列第二个 IIFE）：
   // 工程子代理（depth>0；eng-coder = 偏差审计 / eng-designer = 自己勘察）get a restricted
   // spawn channel — role enum limited to explore, NO async parameter (sync only) and action
-  // pinned to spawn（§19 D-M3 restricted-variant action gate——escalate/check/status are
+  // pinned to spawn（AGENT-LOOP-SUBAGENT.md §6.7 D-M3 restricted-variant action gate——escalate/check/status are
   // refused here at the schema level too；the mechanical re-check lives in subagent.mjs
-  // execute → the §19 action gate + gateEngCoderSpawn (spawn-child.mjs) — schema enums are
+  // execute → the AGENT-LOOP-SUBAGENT.md §6.7 action gate + gateEngCoderSpawn (spawn-child.mjs) — schema enums are
   // advisory, providers don't enforce them）。描述文案按父角色分流（审计 vs 勘察）。
   const engChildRole = depth > 0 && (role === "eng-coder" || role === "eng-designer") ? role : null
   const engChildSubagent = engChildRole
     ? (() => {
         const props = { ...subagentTool.parameters.properties }
-        // §19 review hygiene: the child channel is spawn-only sync explore — drop
+        // AGENT-LOOP-SUBAGENT.md §6.7 review hygiene: the child channel is spawn-only sync explore — drop
         // async, the check/status params (id/n), the eng-coder token params
         // (designToken/designId are meaningless for a read-only spawn; the parent
         // spawn already carried the token) and batchDoc (an audit child derives no
@@ -130,7 +130,7 @@ export async function assembleFamilyTools({
     : null
 
   // consult 工具仅在配置时注册（consultModels 空池时注册会让模型调用后吃一个错误回合）——
-  // §19: escalate 已并入常驻 subagent 的 action:"escalate"（无空池注册问题——动作在
+  // AGENT-LOOP-SUBAGENT.md §6.7: escalate 已并入常驻 subagent 的 action:"escalate"（无空池注册问题——动作在
   // 池空时返回既有错误语义，工程模式 fail-closed 在 execute 内拒绝）。
   // §25 D-R17a: consult_check 已退役（digest 自动注入是唯一消费通道）——consult 家族
   // 只剩 2 工具（consult_start/consult_stop——setup 注册点与描述面同步清零）。
@@ -159,7 +159,7 @@ export async function assembleFamilyTools({
     // eng-designer (§2.15 D): the survey-only subagent channel alone — no advisor
     // (it does not fire reviews) and no verify (its deliverable is documents, not code).
     // BATCH-RECORD §4.3 挂载表（批次档生命周期工具化批）：eng 两分支各挂主名 `batch`
-    // （绑定段 append/status；目标 = spawn 绑定 `child._batchDoc`）——§2.20.3 的 batch_segment
+    // （绑定段 append/status；目标 = spawn 绑定 `child._batchDoc`）——BATCH-RECORD.md §4.2 的 batch_segment
     // 挂载形态已随单名化收口退役（过渡别名 §4.14 不入生产挂载面）；depth-0 主 agent 同表挂载
     // `batch`（D-BR18 扩权——create/close + append §1/§4/§6 + status §1（轮 2 裁定②：§4/§6
     // 状态面走普通文档写），目标走可选 path / 在飞扫描）。

package/agent/helpers.mjs

@@ -210,7 +210,7 @@ export class ContinueError extends Error {
   }
 }
 
-/** §17 D-S6 auto-turn guard 标记集（核内单源）：快照/回填两 helper 共用本清单——
+/** AGENT-LOOP-ASYNC-POOL.md §6.8 D-S6 auto-turn guard 标记集（核内单源）：快照/回填两 helper 共用本清单——
  *  端侧宿主载体（`panel._guardCarry`）与核载体（`agent._inheritedGuard`）同清单。 */
 export const INHERITED_GUARD_KEYS = [
   "_mutatedThisRun", "_verifiedThisRun", "_verifyPassed", "_calledAdvisorThisRun",
@@ -231,7 +231,7 @@ export function restoreGuard(target, snap) {
   for (const k of INHERITED_GUARD_KEYS) if (k in snap) target[k] = snap[k]
 }
 
-/** 跨段累计编号帧（TURN-CAP-CONTINUE.md §19.3——第 19 批 TURN-ACROSS-SEGMENTS）：
+/** 跨段累计编号帧（TURN-CAP-CONTINUE.md §4——第 19 批 TURN-ACROSS-SEGMENTS）：
  *  唯一计算点（纯函数）——把链内累计序数换算成面向消费面的编号载荷。
  *  - seq      = 该轮链内累计序数（1 起——`agent._turnSeq` 每轮 +1，续跑不重置）
  *  - turn     = 段内轮号（0 起——段内帽判定的循环变量）
@@ -337,6 +337,16 @@ export function readonlyToolNames(tools) {
   return new Set(tools.filter((t) => t.readonly).map((t) => t.name))
 }
 
+/** Depth>0 tool exclusions — subagents never get the interactive main-session tools (`question`:
+ *  no user to ask; the routing guidance already lives in every persona file). Single source for
+ *  the repo: the shell-side depth>0 filter consumes this set (design = TOOLS.md §6.16 / D-TO11). */
+export const SUBAGENT_TOOL_EXCLUSIONS = new Set(["question"])
+
+/** Apply the depth>0 exclusion set — always returns a NEW array (parent table untouched). */
+export function excludeSubagentTools(tools) {
+  return tools.filter((t) => !SUBAGENT_TOOL_EXCLUSIONS.has(t.name))
+}
+
 const MAX_INSTRUCTION_CHARS = 32_000
 
 /** Load AGENTS.md / project_rules.md from user home and project root.

package/agent/run-stages.mjs

@@ -171,7 +171,7 @@ export async function finalizeAgentTurn(agent, ctx) {
   // resumes); the Ctrl+C abort branch below is the only path that aborts them
   // (cleanupConsultSessions — marked stopped → no digest), and the suspension
   // driver aborts them on its own abort unwind.
-  // Async subagent turn-end handling (AGENT-LOOP.md §15 D-A3 + §17 D-S1). Lifecycle:
+  // Async subagent turn-end handling (AGENT-LOOP.md §15 D-A3 + AGENT-LOOP-ASYNC-POOL.md §6.8 D-S1). Lifecycle:
   // - Ctrl+C (plain abort): children were aborted with the parent signal — discard dead
   //   entries (tombstone/out-of-pool/notice — AGENT-LOOP-ASYNC-POOL.md §6.20; no stale
   //   errors injected — user explicitly stopped); consultation sessions are cross-turn
@@ -217,7 +217,7 @@ export async function finalizeAgentTurn(agent, ctx) {
     }
   }
   agent._inAutoTurn = false
-  // §17 D-S6: auto-turn guard marks survive into the next USER run (restored at its
+  // AGENT-LOOP-ASYNC-POOL.md §6.8 D-S6: auto-turn guard marks survive into the next USER run (restored at its
   // !resume reset above). Normal ends only — abort discards; ContinueError lets the
   // auto-resumed run snapshot at its own end.
   if (autoTurn && !(signal?.aborted && !signal?.reason?.interrupt) && !(thrownError instanceof ContinueError)) {
@@ -236,8 +236,8 @@ export async function finalizeAgentTurn(agent, ctx) {
  *   queued STAY — no allSettled wait. Results never lost without a session.
  * - suspDriven=true (the interaction layer runs suspensionSession after this
  *   run): NO direct inject — settled entries STAY pooled (settled not consumed)
- *   for the session's first sweepSettledToPending → digest turn (§17.5 — done
- *   条目留池等消化轮注入；status 在 sweep 前仍从池读——17.5.2 不变面（§19.8：check 已删——自动通道为唯一消费方）)。
+ *   for the session's first sweepSettledToPending → digest turn (AGENT-LOOP-ASYNC-POOL.md §6.8 — done
+ *   条目留池等消化轮注入；status 在 sweep 前仍从池读——17.5.2 不变面（AGENT-LOOP-SUBAGENT.md §6.7.5：check 已删——自动通道为唯一消费方）)。
  * maybeRefillAsync runs in both modes (starts queued heads whose slot freed).
  * Single ownership: entries settled inside a suspension session were moved to
  * _pendingAsyncResults by the settle callback, so this only sees user-turn
@@ -250,7 +250,7 @@ async function collectSettledAsync(agent, { suspDriven = false } = {}) {
   if (maps.length === 0) return false
   const { maybeRefillAsync, injectAsyncResult } = await import("../agent-tools/subagent.mjs")
   maybeRefillAsync(agent) // start queued heads now that slots may have freed — no waiting
-  if (suspDriven) return false // §17.5: settled stays pooled — the suspension session digests it
+  if (suspDriven) return false // AGENT-LOOP-ASYNC-POOL.md §6.8: settled stays pooled — the suspension session digests it
   let injectedAdvisor = false
   for (const map of maps) {
     for (const e of [...map.values()]) {

package/agent/suspension.mjs

@@ -1,5 +1,5 @@
 /**
- * agent/suspension.mjs — §17 挂起 / 唤醒驱动（核内形态——AGENT-LOOP.md §2.3 #184 定案）。
+ * agent/suspension.mjs — 挂起 / 唤醒驱动（核内形态——AGENT-LOOP.md §2.3 #184 定案；机制面 = AGENT-LOOP-ASYNC-POOL.md §6.8）。
  *
  * 语义（两端同源，逐字承两端现行挂起驱动——CLI 侧 tui 面 / VSC 侧 extension 面，同语义移植）：
  * 回合尾后台池仍 live → 挂起会话——池项 settle → 入 pending；pending 非空 **或存在未 drain 的

package/agent-tools/advisor-async.mjs

@@ -4,7 +4,7 @@
  * The advisor tool runs reviews in a background pool at depth 0 (default async —
  * ruling ②-3 A): the launch returns an ack, the turn ends naturally, the session
  * suspends, the review settles into _pendingAsyncResults and a digest turn
- * delivers the report (§17 consumption machinery — role-agnostic; entries carry
+ * delivers the report (AGENT-LOOP-ASYNC-POOL.md §6.8 consumption machinery — role-agnostic; entries carry
  * role "advisor" and ride the subagent panel as a pseudo-role, ruling ②-4 A).
  *
  * This module owns:
@@ -51,7 +51,7 @@ import { normAbs, mutationSeqOf, settleAdvisorRun } from "./advisor-settle.mjs"
 export {
   mutationSeqOf, noteMutations, reviewIsStale, settleAdvisorRun, inflightDesignReviewConflict,
 } from "./advisor-settle.mjs"
-// 第 33 批（§17.5）：doc-set 键迁事实面档（实例续跑与陈旧判定同锚单源；原为私有——零 import 面）。
+// 第 33 批（评审失败护栏）：doc-set 键迁事实面档（实例续跑与陈旧判定同锚单源；原为私有——零 import 面）。
 // 本文件继续在实例解析 / 池 entries 上消费它。
 import { docSetKey } from "./review-facts.mjs"
 // F31（2026-09-18 顾问面治理批）：拒回文案对象标识行单源。

package/agent-tools/advisor-settle.mjs

@@ -14,7 +14,7 @@
  *    `reviewIsStale` 同族（同 docAbs / 同 normAbs）、仅扫 running 且未取消的设计条目
  *    （dispatch Phase-1 预闸消费）。
  *
- * 第 33 批（2026-09-11——评审失败护栏 §17.5）：`normAbs` 本体迁 `review-facts.mjs`
+ * 第 33 批（2026-09-11——评审失败护栏）：`normAbs` 本体迁 `review-facts.mjs`
  * （原处 re-export 保面）；**2026-09-18 顾问面治理批**：计数落账（`designReviewOutcome` →
  * `noteDesignReviewOutcome`）随会话级计数器整体退场——改治**失败结论**：结算出口按
  * `settlementCriterion`（纯函数单源，`advisor/notice.mjs`）追加结论块（**两轨共用**——
@@ -25,7 +25,7 @@ import { settleDesignReview, makeDesignTokenRegex, stripApprovedSuffix } from ".
 import { looksLikeReviewOutput, advisorIncompleteMarker, ADVISOR_LAUNCH_REFUSAL_PREFIX } from "../advisor/run.mjs"
 import { isCodePath, loadConventions } from "../conventions.mjs"
 import { logEvent } from "../log.mjs"
-// 第 33 批（§17.5）：`normAbs` 迁 `review-facts.mjs`（中立模块——陈旧判定与事实面共用同一归一）；
+// 第 33 批（评审失败护栏）：`normAbs` 迁 `review-facts.mjs`（中立模块——陈旧判定与事实面共用同一归一）；
 // 2026-09-18：结算分类 / 结论文案单源迁 `advisor/notice.mjs`（纯函数、零状态、零计数载体）。
 import { normAbs } from "./review-facts.mjs"
 import { settlementCriterion, buildSettlementConclusion, scopeSummary } from "../advisor/notice.mjs"
@@ -51,7 +51,7 @@ export function noteMutations(agent, paths) {
   if (log.length > 200) log.splice(0, log.length - 200)
 }
 
-// 第 33 批（§17.5）：`normAbs` 本体迁 `review-facts.mjs`；原处 re-export 保既有 import 面
+// 第 33 批（评审失败护栏）：`normAbs` 本体迁 `review-facts.mjs`；原处 re-export 保既有 import 面
 // （advisor-async / 测试）零变。
 export { normAbs } from "./review-facts.mjs"
 
@@ -121,7 +121,7 @@ export function inflightDesignReviewConflict(agent, absPaths) {
  * 第 11 批增补（A/F11）：`incomplete` = 宿主尾族判定（单谓词）——design 结算未完成即不
  * 签发（`settleDesignReview` 的 `opts.incomplete`）；code 完成守卫的失败判定改用同谓词
  * （六形态语义零丢——旧 `^` 锚正则退役）。
- * 第 33 批增补（§17.5）：design 结算按分类单源落账到会话级护栏——**2026-09-18 撤**（零载体）。
+ * 第 33 批增补（评审失败护栏）：design 结算按分类单源落账到会话级护栏——**2026-09-18 撤**（零载体）。
  * 现行：结算出口按判据名单源（`settlementCriterion`）追加失败结论块（两轨共用；F28/F29）——
  * 判据名非空 ⇒ 块在位（块首行 = 对象标识行）；可用判决 / 中断 / 拒发 ⇒ 零噪声（无块）。
  * Cancelled / parent-aborted reviews consume nothing (the user dropped the
@@ -143,7 +143,7 @@ export function settleAdvisorRun(agent, entry) {
   // 宿主尾族判定（单谓词——design 结算与 code 守卫共用；§14.3 消费点 1/2）。
   const incomplete = result != null ? advisorIncompleteMarker(String(result)) : null
   // 启动拒绝报告（未发起请求——无评审产出）：第 33 批上移为本结算段**单点**——消费 = ① design
-  // 失败分类（neutral——无尝试发生，§17.3 #1）② code 守卫 failureVerdict（既有语义零变）。
+  // 失败分类（neutral——无尝试发生；`ADVISOR-GUARDS.md` §7 失败结算表行 1）② code 守卫 failureVerdict（既有语义零变）。
   const launchRefused = result != null && String(result).startsWith(ADVISOR_LAUNCH_REFUSAL_PREFIX)
   if (!stale) {
     if (run.reviewType === "design" && entry.designToken && result) {

package/agent-tools/advisor.mjs

@@ -174,10 +174,10 @@ export const advisorTool = {
     // scopes agent._advisorRound/_lastAdvisorOutput so the message builder and
     // the run.mjs cap read THIS instance's round/prior (multi-review isolation).
     const resolved = resolveAdvisorLaunch(agent, reviewType, { documents })
-    // §2.20.2 评审侧批次档门禁 + 实例键绑定（batch_segment 的唯一路径来源）：
+    // BATCH-RECORD.md §4.2 评审侧批次档门禁 + 实例键绑定（batch_segment 的唯一路径来源）：
     // 口径 = **「若传则须可读」**（空/不可读 → throw；不强制必传——无批次档的在途设计评审
     // 零回归，N5）；绑定落在 resolved.run（评审实例键，与 reviewType/round/designId 同族）——
-    // 并发设计评审各绑各档，不用单值会话态（§2.20.8 #6）。
+    // 并发设计评审各绑各档，不用单值会话态（BATCH-RECORD.md §4.7 #6）。
     if (args.batchDoc !== undefined && args.batchDoc !== null) {
       resolved.run.batchDoc = resolveBatchDocPath(agent.cwd, args.batchDoc)
     }
@@ -246,7 +246,7 @@ export const advisorTool = {
 
     // B 启动拒绝（§14.4 #2——稳定前缀）：拒发登记（同池满 / cap 款——不置 called、不耗轮次），
     // 可见报错照常返回（record-results 的 REFUSED 契约）。第 33 批：判定单点——同时供设计
-    // 失败分类复用（launchRefused ⇒ neutral——无尝试发生，§17.3 #1）。
+    // 失败分类复用（launchRefused ⇒ neutral——无尝试发生；`ADVISOR-GUARDS.md` §7 失败结算表行 1）。
     const launchRefused = String(result).startsWith(ADVISOR_LAUNCH_REFUSAL_PREFIX)
     if (launchRefused && ctx._toolCallId !== undefined) {
       (agent._advisorRefusals ??= new Set()).add(ctx._toolCallId)

package/agent-tools/async-settle.mjs

@@ -232,7 +232,7 @@ export function settleAsyncEntry(parent, entry, opts = {}) {
   }
   // ③ 分流
   if (entry.cancelled) {
-    // §19.5 cancelled settle 分支（D-M6）：不入 pending、不参与回合尾直注入——清池 +
+    // AGENT-LOOP-SUBAGENT.md §6.7.2 cancelled settle 分支（D-M6）：不入 pending、不参与回合尾直注入——清池 +
     // 终态墓碑（dependsOn 取消语义）+ ⟦ev⟧stopped 冻结 + 族提醒（半成品警示对模型可见）。
     pool?.delete(String(entry.id))
     writeTombstone(parent, entry.id, "cancelled", role) // §20 D-SD5：单点写入（#94 载体吸收）
@@ -263,7 +263,7 @@ export function settleAsyncEntry(parent, entry, opts = {}) {
     // 族记账 hook（advisor 陈旧判定/token D1 落盘；escalate 三分类 merge 决策；subagent/
     // escalate 腾槽补位）——可改写 entry.report（settle 分支输出——digest 原样进）。
     onAccounting?.(parent, entry)
-    // 挂起分流（§17 D-S8 + D-S3 记账——以读取时刻为准）：挂起期 settle → 移交 pending
+    // 挂起分流（AGENT-LOOP-ASYNC-POOL.md §6.8 D-S8 + D-S3 记账——以读取时刻为准）：挂起期 settle → 移交 pending
     // 单容器（digest 注入）+ 出池 + ⟦ev⟧settled 驻留；回合内 → ⟦ev⟧done 立即冻结
     // （条目留池——done-in-pool 统一表示——回合尾 collectSettledAsync 注入）。
     // consult 族恒停靠（settle 即出会话池入 pending——无 TUI 冻结事件——子块各自冻结）。

package/agent-tools/batch-lifecycle.mjs

@@ -5,9 +5,9 @@
  * depth-0 在飞批定位（findInFlightBatch——D-BR21）。判定字面全部单源自 batch-skeleton.mjs
  * （SEGMENT_BY_ROLE / STATUS_WORDS / STATUS_LINE_RE / readBatchStatusLine / sectionHeaderRe /
  * batchSkeleton / TEMPLATE_PLACEHOLDERS / findPlaceholderResidue / placeholderResidueError）；
- * 路径解析单源（resolveBatchDocPath / batchDocBases）与 #84 记账缝住 batch.mjs
- * 主档——**依赖单向（KD-4）：skeleton ← lifecycle ← 主档**，主档把解析后的 cwd/bases/目标闭包
- * 传进来，本档不回 import 主档（防环）。
+ * 路径解析单源（`resolveBatchDocPath` / `batchDocBases` / `resolveBatchCreatePath`——住 `batch-paths.mjs`，
+ * 本档 import 取用）与 #84 记账缝住 batch.mjs 主档——**依赖单向（KD-4）：paths ← skeleton ← lifecycle
+ * ← 主档**，主档把解析后的 cwd/bases/目标闭包传进来，本档不回 import 主档（防环）。
  *
  * 身份判据（D-BR17/D-BR18/D-BR21）：主 agent 的工具调用 ctx 带 `depth === 0`（dispatch 装配）；
  * eng 子代理 `ctx.depth > 0`；评审实例 ctx 无 depth 但工具以 `review: true` 绑定。create/close
@@ -16,12 +16,13 @@
  * 状态面走普通文档写）；depth-0 的 status/path 面按 D-BR21（可选 path，缺省 = 在飞批唯一时取）。
  */
 import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs"
-import { dirname, isAbsolute, resolve, sep } from "node:path"
+import { dirname, resolve } from "node:path"
 
 import {
   SEGMENT_BY_ROLE, STATUS_WORDS, STATUS_LINE_RE, readBatchStatusLine, sectionHeaderRe, batchSkeleton,
   TEMPLATE_PLACEHOLDERS, findPlaceholderResidue, placeholderResidueError,
 } from "./batch-skeleton.mjs"
+import { resolveBatchCreatePath } from "./batch-paths.mjs"
 
 /** 可读文件判据（存在且为文件——目录/缺失同判不可读；与主档同名 helper 同型——KD-4 单向
  *  依赖下各自持有，三行谓词不构成第二权威源）。 */
@@ -87,21 +88,13 @@ export function findInFlightBatch(cwd, bases) {
   return candidates[0]
 }
 
-/** create 路径越界判据（fix 轮 #12）：解析后须落在某一基底根之内；win32 大小写不敏感比较。 */
-function assertInsideBases(abs, bases, raw) {
-  const norm = (p) => (process.platform === "win32" ? p.toLowerCase() : p)
-  const target = norm(abs)
-  for (const b of bases) {
-    const root = norm(b)
-    if (target === root || target.startsWith(root.endsWith(sep) ? root : root + sep)) return
-  }
-  throw new Error(`batch: create path resolves outside the batch-record base roots — a batch record must live under the declared docRoot.batches base (fail-closed). Path: ${raw}`)
-}
+/** create 路径越界判据已迁 `batch-paths.mjs`（`resolveBatchCreatePath` 内含——§4.15 单源）。 */
 
 /**
  * create——建档（§4.11，仅 depth-0）。六段骨架一次预齐（骨架模板单源 = batchSkeleton），
  * 建档即过 gate（§1 占位状态行含「进行中」）；fail-closed：非 .md / 越基底 / 目标已存在 ⇒ throw
  * （不覆盖既有批档，BR-20）；目录缺失 ⇒ mkdir -p 后落位（BR-25）。不代建台账条目。
+ * 路径解析 = `resolveBatchCreatePath`（§4.15 单源：候选序首个落基底内者 / 锚定串只解析项目根形）。
  * F11-B：`source` **必填**（topic 同款空拒——骨架编制行实参化；不传 = 死占位残留必被 F11-C 拒
  * ⇒ create 即拒，不留死锁）；`prev` 传入值**幂等剥**「前情 = 」前缀（值规范化；默认值零变）。
  * @returns {string} 成功消息（含落盘绝对路径）
@@ -119,8 +112,7 @@ export function createBatchRecord({ args, ctx, review, cwd, bases, onWritten })
   if (!primary) {
     throw new Error("batch: no batch-record base root is available — fix PROJECT-MANIFEST.json docRoot.batches (or its default) before creating a record. Nothing was written.")
   }
-  const abs = isAbsolute(raw) ? resolve(raw) : resolve(primary, raw.replace(/\\/g, "/"))
-  assertInsideBases(abs, bases, raw)
+  const abs = resolveBatchCreatePath(cwd, raw, bases)
   if (readableFile(abs)) {
     throw new Error(`batch: create target already exists — refusing to overwrite an existing batch record (fail-closed, BR-20): ${raw}`)
   }

package/agent-tools/batch-paths.mjs

@@ -0,0 +1,142 @@
+/**
+ * agent-tools/batch-paths.mjs — 批次档相对路径解析**单源**（`BATCH-RECORD.md` §4.15 · 台账 #287 · 2026-09-25 批）。
+ *
+ * 四处调用点全部经本档：create（`resolveBatchCreatePath`）· append / status / close 与评审门
+ * （`resolveBatchDocPath`——读面抛错形）· spawn 门（`resolveBatchReadPath`——读面非抛形）。
+ *
+ * 契约（§4.15 逐字）：**候选序** = cwd → 项目根 → 逐基底（基底 = `batchDocBases` 声明面单源）；
+ * **判据分野** = 读面取首个**可读**文件 / create 取首个**落基底根内**者；**锚定防嵌套** = 串以任一基底的
+ * 「项目根相对前缀」打头且前缀后为**路径段边界** ⇒ 只解析项目根形（不二次拼接；不落基底内 ⇒ fail-closed）；
+ * **零变面** = 绝对路径照旧、三个错误文案逐字、「参数在 + 路径可读」判据句。
+ *
+ * 依赖（KD-4 单向）：本档为**叶档**——只 import `node:*` 与 `../manifest.mjs`；主档 re-export 保既有面。
+ */
+import { existsSync, statSync } from "node:fs"
+import { isAbsolute, relative, resolve, sep } from "node:path"
+
+import { docRootBase, docRootPaths, readManifest, resolveProjectRoot } from "../manifest.mjs"
+
+/** 可读文件判据（存在且为文件——目录 / 缺失同判不可读）。 */
+function readableFile(abs) {
+  try { return existsSync(abs) && statSync(abs).isFile() } catch { return false }
+}
+
+/** 「项目根」取根单源（§4.15 条 1——归属 ∨ 发现，无 manifest ⇒ `resolve(cwd ?? ".")` 兜底且**单值**）：
+ *  同式 = 台账库键 / 写门指针基准的同一子表达式（`design/LEDGER.md` §6.1 口径 2）。 */
+export function batchProjectRoot(cwd) {
+  return resolveProjectRoot(cwd) ?? resolve(cwd ?? ".")
+}
+
+/** manifest **声明基底**（声明面；manifest 缺失 / 非法 / 读错 ⇒ 空集——v1 单基底语义零变）。 */
+function declaredBases(cwd) {
+  const base = cwd ?? process.cwd()
+  let man = { ok: false }
+  try { man = readManifest(base) } catch { /* 读错 → 按无 manifest 处理（回退默认基底） */ }
+  return man.ok ? docRootPaths(man.manifest?.docRoot?.batches, base) : []
+}
+
+/** 批次档基底根数组（**声明面单源**——create / 在飞扫描 / 锚定判据共用）：manifest `docRoot.batches`
+ *  （串 | 多根数组）→ 声明基底；缺失 / 非法 ⇒ 回退默认基底 `"docs/batches"`（恒返回非空数组）。
+ *  @param {string} cwd
+ *  @returns {string[]} */
+export function batchDocBases(cwd) {
+  const roots = declaredBases(cwd)
+  return roots.length ? roots : [resolve(docRootBase(cwd), "docs/batches")]
+}
+
+/** 基底的项目根相对前缀（归一 `/`；基底不落项目根下 / 与前缀重合 ⇒ 不产前缀——前缀不匹配者不做启发式改写）。 */
+function basePrefixes(cwd, bases) {
+  const root = batchProjectRoot(cwd)
+  const out = []
+  for (const b of bases) {
+    const rel = relative(root, resolve(b)).replace(/\\/g, "/")
+    if (!rel || rel === ".." || rel.startsWith("../") || isAbsolute(rel)) continue
+    out.push(rel)
+  }
+  return out
+}
+
+/** 锚定判据（**按路径段**——前缀后须为 `/` 或串尾；`docs/batches-old/<x>.md` 不锚定，BR-35）。 */
+function anchoredPrefix(p, prefixes) {
+  for (const pre of prefixes) if (p === pre || p.startsWith(pre + "/")) return pre
+  return null
+}
+
+/** 越基底判据（create 面）：解析后须落在某一基底根之内；win32 大小写不敏感比较。 */
+function insideBases(abs, bases) {
+  const norm = (p) => (process.platform === "win32" ? p.toLowerCase() : p)
+  const target = norm(abs)
+  return bases.some((b) => {
+    const root = norm(b)
+    return target === root || target.startsWith(root.endsWith(sep) ? root : root + sep)
+  })
+}
+
+/** create 越基底（原文案逐字——零变面）。 */
+const outsideBasesError = (raw) => new Error(`batch: create path resolves outside the batch-record base roots — a batch record must live under the declared docRoot.batches base (fail-closed). Path: ${raw}`)
+/** create 锚定但落基底外（§4.15 新文案逐字——不二次拼接）。 */
+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}`)
+
+/**
+ * **读面**解析（append / status / close 与评审门 / spawn 门共用）：首个**可读**候选胜；无 ⇒ null
+ * （调用方各自抛既有文案）。锚定串只解析项目根形（跳过 ①③——已含基底相对前缀者不再二次拼接）。
+ * @param {string} cwd 会话锚（缺省 → 进程 cwd）
+ * @param {string} given 参数原值（相对 / 绝对、`\` 与 `/` 混写均可）
+ * @returns {string|null} 可读文件的绝对路径 / null
+ */
+export function resolveBatchReadPath(cwd, given) {
+  const base = cwd ?? process.cwd()
+  const raw = typeof given === "string" ? given.trim() : ""
+  if (!raw) return null
+  const p = raw.replace(/\\/g, "/")
+  if (anchoredPrefix(p, basePrefixes(base, batchDocBases(base)))) {
+    const abs = resolve(batchProjectRoot(base), p)
+    return readableFile(abs) ? abs : null
+  }
+  const candidates = [resolve(base, p), resolve(batchProjectRoot(base), p), ...declaredBases(base).map((b) => resolve(b, p))]
+  for (const abs of candidates) if (readableFile(abs)) return abs
+  return null
+}
+
+/**
+ * 批次档路径门禁（评审侧 `BATCH-RECORD.md` §4.2 口径 = **「若传则须可读」**）：空 / 非字符串 / 不可读 → throw。
+ * 非空且可读 → 返回绝对路径（`\` 归一——照 `files` / `batchDoc` spawn 门先例）。错误文案逐字零变（零回归硬约束）。
+ */
+export function resolveBatchDocPath(cwd, given) {
+  const base = cwd ?? process.cwd()
+  const raw = typeof given === "string" ? given.trim() : ""
+  if (!raw) {
+    throw new Error("batchDoc must be a non-empty path to the batch record — pass the batch record currently in flight, or omit the parameter entirely when no batch record is in flight.")
+  }
+  const abs = resolveBatchReadPath(base, raw)
+  if (abs) return abs
+  throw new Error(`batchDoc is not a readable file: ${raw} — pass the path of the batch record currently in flight (a path that resolves to an existing file), or omit the parameter when no batch record is in flight.`)
+}
+
+/**
+ * **create 面**解析（§4.15 条 2/3）：绝对路径照旧取用（仍过越基底判据）；相对路径 = 候选序中首个**落基底
+ * 根内**者（新档不存在——可读性无判别力）；锚定串只解析项目根形，不落基底内 ⇒ fail-closed 新文案。
+ * @param {string} cwd 会话锚
+ * @param {string} given create `path` 原值
+ * @param {string[]} bases 已解析的基底根数组（`batchDocBases` 单源；调用方传入以免重复读档）
+ * @returns {string} 落位绝对路径
+ */
+export function resolveBatchCreatePath(cwd, given, bases) {
+  const base = cwd ?? process.cwd()
+  const raw = String(given ?? "").trim()
+  const p = raw.replace(/\\/g, "/")
+  if (isAbsolute(raw)) {
+    const abs = resolve(raw)
+    if (!insideBases(abs, bases)) throw outsideBasesError(raw)
+    return abs
+  }
+  if (anchoredPrefix(p, basePrefixes(base, bases))) {
+    const abs = resolve(batchProjectRoot(base), p)
+    if (!insideBases(abs, bases)) throw anchoredEscapeError(raw)
+    return abs
+  }
+  for (const abs of [resolve(base, p), resolve(batchProjectRoot(base), p), ...bases.map((b) => resolve(b, p))]) {
+    if (insideBases(abs, bases)) return abs
+  }
+  throw outsideBasesError(raw)
+}