@thincoder/core 0.10.10 → 0.10.12

package/session-lifecycle.mjs

@@ -39,7 +39,9 @@ import { mergeAdjacentAssistantEchoes } from "./context.mjs"
 // 打开态读数公式（§6.24 判据句 2——与 CLI 状态行 / VSC 同式；零新公式，只组合）。
 import { historyPercent } from "./token-window.mjs"
 import { scheduleSessionGC } from "./session-gc.mjs"
-import { restoreEngTokens } from "./token-ttl.mjs"
+import { restoreEngTokens, tokenExpired } from "./token-ttl.mjs"
+// 槽事件（docs/core/design/SESSION-OBSERVABILITY.md §3.1）：`slot:new` 走核日志单一通道。
+import { logEvent } from "./log.mjs"
 import { clearPlanMode } from "./agent-tools/plan.mjs"
 import { bindRecordStore, unbindRecordStore, RECORD_WINDOW_MESSAGES } from "./session-store.mjs"
 // 会话级档位（§6.21 判据句 4）判据单源：off 形族（`think-off.mjs`）+ 逐模型枚举
@@ -73,8 +75,9 @@ function stripTruncatedToolArgs(m) {
   return changed ? { ...m, tool_calls } : m
 }
 
-/** Apply loaded session data onto an agent object; returns true if the runtime composite
- *  was switched. 2026-08-31 会诊 F1：清空 _slot/_slotMtime 缓存——切换后下次保存重新认领。
+/** Apply loaded session data onto an agent object; returns `{ switched, droppedDesignTokens }`
+ *  （`switched` = 运行态渠道是否被切——原布尔值；`droppedDesignTokens` = 离开本会话的未过期
+ *  设计凭证数，设计档 §3.2）。2026-08-31 会诊 F1：清空 _slot/_slotMtime 缓存——切换后下次保存重新认领。
  *
  *  MODEL-MERGE-SESSION（F-4）applySession 重写为两支 + 删旧支（评审 #7/#9 措辞——防
  *  "三支"误读）：
@@ -121,8 +124,8 @@ export function applySession(agent, data, opts = {}) {
   agent.goal = data.goal ?? null
   agent._pendingReminders = data.pendingReminders ?? []
   agent._sessionStart = data.sessionStart ?? null
-  // R16 token 字段恢复（过期过滤——见 token-ttl.mjs restoreEngTokens）
-  restoreEngTokens(agent, data)
+  // R16 token 字段恢复（过期过滤——见 token-ttl.mjs restoreEngTokens）；返回值 = 离开集计数（§3.2）
+  const restored = restoreEngTokens(agent, data)
   // engineering is session-level (2026-08-29): the slot value is the CLI session's authority
   // — config.json is only the initial default / cross-end mirror. A legacy slot without the
   // field keeps whatever config.json seeded (unchanged behavior).
@@ -207,11 +210,11 @@ export function applySession(agent, data, opts = {}) {
         agent.provider.reasoningEffort = data.effort
       }
     }
-    return switched
+    return { switched, droppedDesignTokens: restored.droppedDesignTokens }
   }
   // ② 槽无 key ∥ 不在册 → D-S3 保留——静默保持现状（落 config 链：config 统一解析产物已是
   //    `agent.provider`；不报错不纠正——两方都无效由调用侧复验 validateProvider 弹重选）
-  return false
+  return { switched: false, droppedDesignTokens: restored.droppedDesignTokens }
 }
 
 /**
@@ -266,6 +269,7 @@ export async function newSession(cwd, opts = {}) {
   writeSessionFile(slotPath(cwd, slot), data)
   // 摘要 `ts` 地板入参（#503 同族随动——保存面写后取 mtime；`slotMtime` 读失败 ⇒ null ⇒ 裸墙钟）
   m.slots[slot] = slotDigest(data, slotMtime(cwd, slot))
+  const prevSlot = Number.isInteger(m.active) ? m.active : null // 覆盖前 active（无则 null）
   m.active = slot
   // 2026-08-31 advisor round1 🟡：与 ensureActive 认领模型一致——立即记录新 slot 所有权，
   // 否则 /new 后到首次保存之间并发方（VS Code/另一 CLI）会把新 active 槽当"空闲可恢复"
@@ -287,19 +291,29 @@ export async function newSession(cwd, opts = {}) {
   saveManifest(cwd, m, deletions, opts.releaseStale ? { setActive: true, release: [slot] } : { setActive: true })
   // 2026-09-05 §6.10 D-4：/new 落点写本端记录（显式切换跟随——T-M8）
   writeEndMarker(cwd, slot)
+  // 槽事件（设计档 §3.1）：落定后一行——字段闭集，不带标题 / 路径。
+  logEvent("slot:new", { slot, prevSlot, reason: "new-session" })
   return slot
 }
 
 /** 清空会话运行态（/new 用，2026-08-31 会诊 F3）：_fullHistory/title/_sessionStart 等
  *  全部会话级状态 + 一次性注入标志必须全清——否则新会话首次落盘把旧会话完整人类线 +
  *  旧标题写进新槽（实锤 .19/.3 双副本）；注入标志不清则 /new 后新会话永不注入
- *  OS/cwd reminder（2026-09-01 会诊 glm 🟡）。autoApprove 是用户偏好，跨会话保留（有意）。 */
+ *  OS/cwd reminder（2026-09-01 会诊 glm 🟡）。autoApprove 是用户偏好，跨会话保留（有意）。
+ *  返回 `{ droppedDesignTokens }`（设计档 §3.2）——重建 Map 前数一遍的未过期凭证数。 */
 export function resetSessionState(agent) {
   agent._fullHistory = []
   agent.history = []
   agent.title = ""
   agent.tasks = []
   agent._sessionStart = null
+  // 设计档 §3.2（R2）：重建 Map 前数一遍「未过期」条目——返回值 = 端壳报明口径（离开集）
+  let droppedDesignTokens = 0
+  if (agent._engDesignTokens instanceof Map) {
+    for (const t of agent._engDesignTokens.values()) {
+      if (!(typeof t === "string" && tokenExpired(t))) droppedDesignTokens++
+    }
+  }
   // DESIGN-TOKEN-SETTLEMENT D3（2026-09-08）：单值镜像 `_engDesignToken` 退役——不再维护
   agent._engDesignTokens = new Map() // multi-design slots die with the session (2026-09-01 fix #2)
   agent._compressFailures = 0
@@ -322,6 +336,7 @@ export function resetSessionState(agent) {
   agent._lastEngState = false
   // /new 或切换：记录存储解绑（新槽由 cmd-new / 首保存补绑重新挂载——§6.14 绑定与对账）
   unbindRecordStore(agent)
+  return { droppedDesignTokens }
 }
 
 /** Switch the manifest active pointer to a slot. Returns the slot's session data

package/session-segments.mjs

@@ -41,6 +41,7 @@ export function slimForDisplay(m) {
   if (m && m.role === "assistant" && Array.isArray(m.tool_calls)) {
     let changed = false
     const tool_calls = m.tool_calls.map((tc) => {
+      if (!tc || typeof tc !== "object") return tc // 空元素原样带走：读取侧不许崩（#31）
       const args = tc.function?.arguments
       if (typeof args === "string" && args.length > 300) {
         changed = true

package/session-slot-claims.mjs

@@ -22,6 +22,8 @@ import { probeOwnersSync, ownerState, filterDeadOwners } from "./process-probe.m
 import { getSessionId, manifestPath, slotPath } from "./session-slots.mjs"
 // 清单读写（落盘单源住原档——静态环见头注；反向 re-export 保 import 面）。
 import { loadManifest, saveManifest } from "./session-slots-manifest.mjs"
+// 槽事件（docs/core/design/SESSION-OBSERVABILITY.md §3.1）：分到全新号时落 `slot:allocate`。
+import { logEvent } from "./log.mjs"
 
 /** 本进程**残留认领集**（F-CR1 释放谓词 —— **判据单源** · SESSION.md §6.2 / §6.16）：
  *  「释放 A ⟺ `slotSessions[A]` 为本进程 ∧ `A ∉ 保留集`」。`keep` = 保留集 = 落点槽 ∪ 本进程
@@ -177,9 +179,11 @@ export function allocateFresh(cwd, m, deadParam = null, bundle = null) {
   }
   let newSlot = allSlots.length > 0 ? allSlots[allSlots.length - 1] + 1 : 1
   while (liveClaimed(newSlot) || existsSync(slotPath(cwd, newSlot))) newSlot++
+  const prevSlot = Number.isInteger(m.active) ? m.active : null // 分配前 active（无则 null）
   m.active = newSlot
   m.slotSessions[newSlot] = mySessionId
   saveManifest(cwd, m, deadParam?.() ?? null, { setActive: true })
+  logEvent("slot:allocate", { slot: newSlot, prevSlot, reason: "all-slots-live" })
   return newSlot
 }
 

package/session-slot-write.mjs

@@ -18,7 +18,9 @@
  *
  * token 台账字段（`engDesignTokens`）的**槽 I/O 面**不在本档——单源 = `token-ttl.mjs`
  * （settle 落盘 / 门禁回读 / 链终清理三面齐备）；本档只承载其**保存面合并规则**
- * （`mergeEngTokensForSave`——空态保留 + 并集 + 新铸者胜，纯函数）。槽标题写面同样不在
+ * （`mergeEngTokensForSave`——空态保留 + 并集 + 新铸者胜，纯函数）。批次归属旁列
+ * （`engDesignTokenBatches`）同款分层：槽 I/O 在 `token-ttl.mjs`，本档只持其保存面合并规则
+ * （`mergeEngTokenBatchesForSave`）。槽标题写面同样不在
  * 本档——单源 = `session-rename.mjs` 的 `renameSlot`（同 `{ok, reason}` 契约 + mtime 门控）。
  */
 
@@ -26,6 +28,8 @@ import { existsSync, readFileSync, renameSync, statSync } from "node:fs"
 
 import { getSessionId, loadManifest, saveManifest, slotDigest, slotPath, writeSessionFile, sessionEnd } from "./session-slots.mjs"
 import { loadSlotFile, isLegacyTransient } from "./session.mjs"
+// 槽事件（docs/core/design/SESSION-OBSERVABILITY.md §3.1）：走核日志单一通道 `logEvent`。
+import { logEvent } from "./log.mjs"
 // token 形态单源（格式校验 + 到期时刻）——本档的保存面合并规则复用同一判定。
 import { tokenExpiryMs } from "./token-ttl.mjs"
 // 会话级偏好写面（§6.21 判据句 3）的判据单源——档位值域（`specForModel(...).reasoningEffortEnum`）
@@ -77,9 +81,11 @@ function rotateIfForeign(p, slot, data) {
     const diskLonger = Array.isArray(disk?.history) && Array.isArray(data?.history) &&
       disk.history.filter((m) => !isLegacyTransient(m)).length > data.history.length
     if (!(diskIsNewer || diskForeign || (diskStart && diskStart !== myStart) || diskLonger)) return null
+    const reason = diskIsNewer ? "newer-version" : diskForeign ? "foreign-cwd" : diskLonger ? "longer-record" : "other-session"
     const bak = `${p}.bak-${Date.now()}`
     renameSync(p, bak)
     console.error(`[session] slot ${slot} holds ${diskIsNewer ? `a newer-version file (v${disk.version})` : diskForeign ? `a foreign-cwd file (${disk.cwd})` : diskLonger ? `a longer record (${disk.history.length} > ${data.history.length} messages — concurrent append)` : `another session (start ${diskStart}, ours ${myStart})`} — preserved as ${bak}`)
+    logEvent("slot:rotate", { slot, reason, bak: true, via: "write" })
     return bak
   } catch (e) {
     // 文件存在但不可读（损坏 / 半写）：改名保留现场，不覆盖
@@ -89,6 +95,8 @@ function rotateIfForeign(p, slot, data) {
     }
     // 排障面：区分「现场不可读」与「轮转失败」——静默会让半写/占用现场无从定位。
     console.error(`[session] slot ${slot}: pre-write rotation check failed (${e?.message ?? e}) —${preserved ? " preserved as .corrupted" : " the scene could NOT be preserved"}`)
+    // 判别式（设计档 §3.1）：已保全 ⇒ unreadable；未保全 ⇒ rotate-failed（同一个 catch 的两个现场）。
+    logEvent("slot:rotate", { slot, reason: preserved ? "unreadable" : "rotate-failed", bak: false, via: "write" })
     return null
   }
 }
@@ -187,6 +195,24 @@ export function mergeEngTokensForSave(incoming, existing) {
   return out
 }
 
+/**
+ * 保存面「批次归属旁列」合并规则（DESIGN-TOKEN-SETTLEMENT §10 / KD-BG7——纯函数）：
+ *  沿用 `mergeEngTokensForSave` 的「槽独有项保留」半边（忙时保存不得把内存快照的缺席当成删除），
+ *  同 key 冲突**以新写者胜**——旁列值是路径，无 mint 时刻可比，不比 `expiresAt`。
+ *  - `incoming === undefined`（调用方未携带该字段）⇒ 保留槽值；
+ *  - incoming 空值 ⇒ 槽有值则保留槽、槽也空 ⇒ null（写 null = 清字段）；
+ *  - 两端都有 ⇒ 并集：槽独有项保留、incoming 覆盖同 key。
+ *  理由：忙时保存把归属写丢 ⇒ 收口 no-op ⇒ 凭证留存，正是 §10 要消的窗口。
+ */
+export function mergeEngTokenBatchesForSave(incoming, existing) {
+  if (incoming === undefined) return existing ?? null
+  const hasNew = incoming && typeof incoming === "object" && !Array.isArray(incoming) && Object.keys(incoming).length > 0
+  const slotHas = existing && typeof existing === "object" && !Array.isArray(existing) && Object.keys(existing).length > 0
+  if (!hasNew) return slotHas ? existing : null
+  if (!slotHas) return incoming
+  return { ...existing, ...incoming }
+}
+
 /** 会话级偏好（§6.21）键闭集——表外键 = 整 patch 拒（写未发生）。 */
 const SLOT_PREF_KEYS = new Set(["provider", "model", "effort"])
 

package/session-slots-manifest.mjs

@@ -37,6 +37,8 @@ import { getSessionId, manifestPath, slotPath, writeSessionFile } from "./sessio
 // 认领面（2026-09-28 拆分外提——见头注）：本档 import `staleClaims` 供 dropStaleClaims 取用，
 // 并在下方 re-export 全族保既有 import 面。
 import { staleClaims } from "./session-slot-claims.mjs"
+// 槽事件（docs/core/design/SESSION-OBSERVABILITY.md §3.1）：拒写 / 读回失败两处写时点。
+import { logEvent } from "./log.mjs"
 
 /** Extract slot metadata from history (shared by slotDigest and loadSlotMeta) */
 export function extractSlotMeta(history, activeProvider, updatedAt, title = "") {
@@ -98,15 +100,32 @@ export function slotMtime(cwd, slot) {
   try { return statSync(slotPath(cwd, slot)).mtimeMs } catch { return null }
 }
 
-export function loadManifest(cwd) {
+/** 清单读（两形——DESIGN-TOKEN-SETTLEMENT §10「槽号解析层同判」· KD-BG8）：缺省宽容 ∥ `strict`。
+ *  判据 = 「没有」与「读不到」分清：文件不存在（`ENOENT`）⇒ 默认空账本（无槽号 = 合法缺省，**两形同**）；
+ *  在盘但读失败（`EACCES` ∥ `EISDIR`…）∥ 解析失败 ⇒ 宽容形照旧吞错回默认，**严格形抛**（携 manifest
+ *  路径 + 底层消息）。收口门面（`consumeBatchDesignTokens`）用严格形——manifest 损坏若被读成「无槽号」，
+ *  收口就落成「已收口而凭证仍在」，正是 F-D8 要消的窗口。
+ *  判别用 `err.code === "ENOENT"`——**不用 `existsSync`**：它把权限错也吞成「不存在」，而收口面要拒的正是那类。
+ *  **形状非法**（可读但解析成 `null` ∥ 非对象）按「读不到」处置（fail-closed；与 `saveManifest` 的 `shape-invalid`
+ *  同判）——严格形抛、拒文沿用「could NOT be read」：方向只更严，措辞不另立第三类。
+ *  与 `readEngTokenBatchesFromSlot`（token-ttl.mjs）同一两形先例：同一读函数、同一判据、缺省宽容；
+ *  展示 / 尽力面一律缺省（现行调用点零改），收口门面才传 `{ strict: true }`。 */
+export function loadManifest(cwd, { strict = false } = {}) {
+  let p = "(unresolved manifest path)"
   try {
-    const p = manifestPath(cwd)
-    if (!existsSync(p)) return { slots: {}, sessionId: null }
+    p = manifestPath(cwd)
     const m = JSON.parse(readFileSync(p, "utf8"))
     if (!m.slots) m.slots = {} // 2026-09-01 会诊 deepseek 🔵：损坏的 {} manifest 不再让调用方抛 TypeError
     if (!m.sessionId) m.sessionId = null
     return m
-  } catch { return { slots: {}, sessionId: null } }
+  } catch (e) {
+    // 「没有」：文件不存在 = 合法缺省（新会话 / 首建前）——两形一致，严格形也不抛
+    if (e?.code === "ENOENT") return { slots: {}, sessionId: null }
+    if (strict) {
+      throw new Error(`loadManifest: the session manifest could NOT be read (${p}: ${e?.message ?? e}) — the slot number cannot be resolved, so "no slot" cannot be told apart from "cannot read"; the engineering closeout is refused with the record untouched (fix the manifest file or its permissions and retry).`)
+    }
+    return { slots: {}, sessionId: null }
+  }
 }
 
 /** 可信合并基座判据（§6.23 判据句 1 · ②）：顶层非 null 非数组对象 ∧（`slots` / `slotSessions`
@@ -145,6 +164,7 @@ export function ledgerHealth(cwd) {
 function refuseManifestWrite(p, reason, preserved = null) {
   noteRefusal(reason, p)
   console.error(`[session] saveManifest: write refused (reason=${reason}) path=${p}${preserved ? ` preserved=${preserved}` : ""}`)
+  logEvent("slot:refuse", { reason })
   return false
 }
 
@@ -162,6 +182,7 @@ function writeManifestBase(p, m) {
   if (trusted) return true
   noteRefusal("readback-failed", p)
   console.error(`[session] saveManifest: readback-failed path=${p} preserved=${preserveScene(p)}`)
+  logEvent("slot:refuse", { reason: "readback-failed" })
   return false
 }
 

package/token-ttl.mjs

@@ -20,6 +20,9 @@
  * - **D3**：**单值镜像 `_engDesignToken` 退役**——AC3 零写 + 仅一次性迁移读。本模块
  *   不再写镜像（engTokenSlotFields 只产多槽表）；restoreEngTokens 是唯一迁移读点（旧
  *   slot 残留 engDesignToken → 迁入 Map，此后不写不读镜像）。
+ * - **§10（2026-10-26）**：批次归属旁列 `engDesignTokenBatches`（designId → 批档绝对路径）与
+ *   槽多槽表**同点序列化 / 同拍恢复 / 同处落盘**；轻读面 = `readEngTokenBatchesFromSlot`。
+ *   token 值形零改（仍 `<uuid>:<expiryMs>`）——旁列只承载归属，不承载授权。
  *
  * 依赖方向：本模块只 import 底层槽 I/O（session-slots.mjs 原语 + session-guard.mjs 轮转
  * 守卫）——session.mjs 同时 import 本模块（engTokenSlotFields/restoreEngTokens），形成
@@ -108,12 +111,17 @@ export function purgeExpiredDesignTokens(agent) {
  *  （JSON-safe）；空/缺 Map → undefined → JSON.stringify 丢 key——清过的会话写
  *  NO field，不从上次 save 复活槽。
  *  DESIGN-TOKEN-SETTLEMENT D3（2026-09-08）：单值镜像 `engDesignToken` 退役——
- *  saveSession 不再写镜像字段（AC3 零写）；只产多槽表 engDesignTokens。 */
+ *  saveSession 不再写镜像字段（AC3 零写）；只产多槽表 engDesignTokens。
+ *  批次归属旁列 `engDesignTokenBatches`（DESIGN-TOKEN-SETTLEMENT §10）同处序列化——
+ *  与槽表并列、同空态语义（空表 ⇒ undefined ⇒ 字段不落盘）；承载归属，不承载恢复。 */
 export function engTokenSlotFields(agent) {
   return {
     engDesignTokens: agent._engDesignTokens instanceof Map && agent._engDesignTokens.size > 0
       ? Object.fromEntries(agent._engDesignTokens)
       : undefined,
+    engDesignTokenBatches: agent._engDesignTokenBatches instanceof Map && agent._engDesignTokenBatches.size > 0
+      ? Object.fromEntries(agent._engDesignTokenBatches)
+      : undefined,
   }
 }
 
@@ -129,6 +137,13 @@ export function engTokenSlotFields(agent) {
  *  残留——一次性语义。镜像若已过期/畸形 → 不迁移（drop——与 Map 过期项同处理，
  *  清盘闭环）。永不写 agent._engDesignToken。 */
 export function restoreEngTokens(agent, data) {
+  // 设计档 §3.2（R2）：整体替换前快照旧 Map 的「未过期 id 集」，落定后求差 = 离开集（非集合大小差）。
+  const before = new Set()
+  if (agent._engDesignTokens instanceof Map) {
+    for (const [id, t] of agent._engDesignTokens) {
+      if (!(typeof t === "string" && tokenExpired(t))) before.add(id)
+    }
+  }
   const map = new Map()
   if (data.engDesignTokens && typeof data.engDesignTokens === "object" && !Array.isArray(data.engDesignTokens)) {
     for (const [id, t] of Object.entries(data.engDesignTokens)) {
@@ -144,16 +159,32 @@ export function restoreEngTokens(agent, data) {
   }
   if (map.size > 0) agent._engDesignTokens = map
   else delete agent._engDesignTokens
+  // 批次归属旁列同拍读入（§10）：值 = 批档绝对路径，无 TTL 可言（承载归属，不承载授权）。
+  // 槽因过期被丢而旁列行仍在 = 惰性残留：消费面按 id 反查时自然落成 no-op（不猜归属）。
+  const batches = new Map()
+  if (data.engDesignTokenBatches && typeof data.engDesignTokenBatches === "object" && !Array.isArray(data.engDesignTokenBatches)) {
+    for (const [id, b] of Object.entries(data.engDesignTokenBatches)) {
+      if (typeof b === "string" && b) batches.set(id, b)
+    }
+  }
+  if (batches.size > 0) agent._engDesignTokenBatches = batches
+  else delete agent._engDesignTokenBatches
+  let droppedDesignTokens = 0
+  for (const id of before) if (!map.has(id)) droppedDesignTokens++
+  return { droppedDesignTokens }
 }
 
 // ── 会话槽权威台账 I/O（DESIGN-TOKEN-SETTLEMENT D1/D2/D3——槽文件 = 权威结算台账） ──
 
 /** 当前会话槽号（读侧——无认领副作用）：粘性 _slot 优先；未钉槽时读 manifest active
- *  （loadManifest 只读——不在门禁路径触发认领写）。无槽 → null。 */
-function currentSlotNoReadOnly(agent) {
+ *  （loadManifest 只读——不在门禁路径触发认领写）。无槽 → null。
+ *  `strict` 透传 manifest 读形（§10「槽号解析层同判」）：缺省宽容（manifest 不可读 ⇒ 无槽号）；
+ *  收口面 `{strict:true}` ⇒ manifest 在盘但读失败 ∥ 解析失败即抛；manifest 不存在 ∥ `active` 缺席
+ *  仍是无槽号（合法缺省——「读到了，说没有」）。 */
+function currentSlotNoReadOnly(agent, { strict = false } = {}) {
   const slot = agent?._slot
   if (Number.isInteger(slot)) return slot
-  const active = loadManifest(agent?.cwd)?.active
+  const active = loadManifest(agent?.cwd, { strict })?.active
   return Number.isInteger(active) ? active : null
 }
 
@@ -175,6 +206,46 @@ export function readEngTokensFromSlot(agent) {
   } catch { return null }
 }
 
+/** 读当前会话槽文件的批次归属旁列（DESIGN-TOKEN-SETTLEMENT §10——不做 TTL 过滤、不改盘）。
+ *  与 `readEngTokensFromSlot` 同形同读法（JSON.parse 轻读、零 reconcile 副作用）；两者不能合成
+ *  一个函数——既有读者的字段名硬编码（只返回 `data.engDesignTokens`）⇒ 同形兄弟函数。
+ *  **两形（§10「读形（收口面严格 ∥ 清点面宽容）」）**：`strict:false`（缺省 · 清点面）读不到 ⇒ `null`，
+ *  批列照旧如实降级 `—`（F-SL1）；`strict:true`（收口面）读不到 ⇒ **抛**（close 被拒、档零字节变、可重试）。
+ *  判据 = **「没有」与「读不到」分清**：无槽号 ∥ 文件不存在（`ENOENT`）∥ 无该字段 ⇒ 空集（合法缺省，
+ *  两形同）；其余 I/O 错（`EACCES` ∥ `EISDIR` ∥ `EIO`…）∥ `JSON.parse` 失败 ⇒ 宽容形 `null` / 严格形抛。
+ *  **槽号解析层同判（manifest 层）**：槽号来自 `currentSlotNoReadOnly(agent, { strict })`——`_slot` 未钉时
+ *  读 manifest；strict 形把 manifest 的「读不到」原样抛出（拒因点名 manifest，不被本函数重包成旁列读失败）。
+ *  不用 `existsSync` 兜底——它把权限错也吞成「不存在」，正是收口面必须拒的那一类（「无法判定归属 =
+ *  无法证明清账」；§10「严格读的边界」）。
+ *  返回 {designId: <批档绝对路径>} 对象或 null（无槽/无文件/无该字段；宽容形的不可读亦 `null`）。 */
+export function readEngTokenBatchesFromSlot(agent, { strict = false } = {}) {
+  // 槽号解析在 try 之外：manifest 层的「读不到」自带 manifest 坐标（§10「槽号解析层同判」），
+  // 不在这里被重包成「旁列读不到」——两层拒因各自点名。宽容形此步不抛（不可读 ⇒ 无槽号 ⇒ null）。
+  const slot = currentSlotNoReadOnly(agent, { strict })
+  if (slot == null) return null
+  let p = "(unresolved slot path)"
+  try {
+    p = slotPath(agent.cwd, slot)
+    let raw
+    try {
+      raw = readFileSync(p, "utf8")
+    } catch (e) {
+      if (e?.code === "ENOENT") return null // 「没有」：文件不存在（新会话 / 尚无槽）——合法缺省
+      throw e // 「读不到」：其余 I/O 错交外层按读形处置
+    }
+    const data = JSON.parse(raw)
+    return (data && typeof data === "object" && !Array.isArray(data.engDesignTokenBatches)
+      && data.engDesignTokenBatches && typeof data.engDesignTokenBatches === "object")
+      ? data.engDesignTokenBatches
+      : null
+  } catch (e) {
+    if (strict) {
+      throw new Error(`readEngTokenBatchesFromSlot: the session slot file's batch-attribution side column could NOT be read (${p}: ${e?.message ?? e}) — the closeout consume cannot tell which slots belong to this batch, so the closeout is refused with the record untouched; fix the slot file or its permissions and retry.`)
+    }
+    return null
+  }
+}
+
 /** 内存 miss 时从权威槽 reconcile（D2 spawn 门 + D3 dispatch 写门同源）：把槽文件中
  *  **未过期**项并进内存 Map（TTL 过滤保留——expired 不并入，fail-closed；格式/畸形串
  *  与 restoreEngTokens 同语义读回——门禁格式拒）；槽无活项 → 内存原样。返回判定用 Map。
@@ -271,6 +342,9 @@ export function persistEngTokens(agent) {
   const fields = engTokenSlotFields(agent)
   if (fields.engDesignTokens !== undefined) data.engDesignTokens = fields.engDesignTokens
   else delete data.engDesignTokens
+  // 批次归属旁列逐字段复制同处（§10「保存 / 合并路径」第二处）：空表 ⇒ 字段删（不从上次落盘复活）。
+  if (fields.engDesignTokenBatches !== undefined) data.engDesignTokenBatches = fields.engDesignTokenBatches
+  else delete data.engDesignTokenBatches
   // 单值镜像字段永不复写（D3 零写）——残留 engDesignToken 随本次写一并清（更快退役，
   // 杜绝 stale 镜像 + 空 Map 组合在下次 restore 二次迁移复活死 token 的边角）。
   delete data.engDesignToken

package/tool-docs/advisor.md

@@ -1,9 +1,28 @@
-Run an independent review of your work. `type` is REQUIRED — one of exactly two values: 'design' reviews design / requirement documents BEFORE implementation (documents=[...] with the explicit doc paths — relative paths resolve against the session cwd first, then candidate project roots (project-root-relative e.g. <repo>/docs/…, or absolute; relative forms are also tried against the session cwd's ancestor directories); plus batchDoc when a batch record is in flight); 'code' reviews the code you changed AFTER implementation (paths=[...] to scope files/directories; documents=[...] adds acceptance-criteria context). A call without a type (or with a conflicting object.type) is refused — no default, no silent fallback.
+Run an independent review of your work. `type` is REQUIRED — one of exactly two values, no default and no silent fallback.
 
-The advisor is an independent read-only sub-agent (explores the codebase, reads files, traces callers via grep/lsp). Code review converges: round 1 full review → round 2 verifies the agent's fix claims → round 3+ re-checks only the fix claims. Design review is a single pass against methodology and requirements. Criteria come from .thincoder/advisor.md (if present) or sensible defaults. After the review you MUST produce a response table (format = discipline rules); on all-clear, call verify.
+- `type="design"` — design review: reviews design / requirement documents BEFORE implementation. Pass `documents=[...]` (the explicit list), plus `batchDoc` when a batch record is in flight.
+- `type="code"` — code review: reviews the code you changed AFTER implementation. Pass `paths=[...]` to scope files/directories; `documents=[...]` adds acceptance-criteria context.
 
-object={type,target,status,reason,exclude} optionally anchors the review target — mechanically injected at the start of the review message; absent = no injection.
+`documents` — one rule: a relative path resolves against the session project root (e.g. `docs/core/design/ADVISOR-GUARDS.md`); an absolute path is used as-is.
 
-ASYNC (depth 0 only): the review runs in the BACKGROUND by default — ack immediately, the report arrives automatically in a digest turn. One shared pool (agent.poolLimits.advisor, default 4 — configurable via /config 并发池 or config.json; pool-full and same-scope launches are refused stating the current limit) — launch reviews one at a time. Inside a child (depth>0) reviews are always synchronous (async:true rejected).
+The relative form needs the session anchor to be inside a project. When the anchor is a workspace root (several projects below it, no manifest of its own) there is no single project root to resolve against, and a relative path is refused with `no-project-root` — write the absolute path there.
 
-Returns the verdict: all-clear (call verify) or a findings list to fix.
+Accepted = an existing `.md` file anywhere inside a project — a doc sitting at the repo root counts. Anything else is refused with the resolved path, the reason and the two expected forms.
+
+A call without a type (or with a conflicting `object.type`) is refused.
+
+The advisor is an independent read-only sub-agent (explores the codebase, reads files, traces callers via grep/lsp).
+
+- Code review converges: round 1 full review → round 2 verifies the agent's fix claims → round 3+ re-checks only the fix claims.
+- Design review is a single pass against methodology and requirements.
+- Criteria come from `.thincoder/advisor.md` (if present) or sensible defaults.
+- After the review you MUST produce a response table (format = discipline rules); on all-clear, call `verify`.
+
+`object={type,target,status,reason,exclude}` optionally anchors the review target — mechanically injected at the start of the review message; absent = no injection.
+
+ASYNC (depth 0 only): the review runs in the BACKGROUND by default — ack immediately, the report arrives automatically in a digest turn.
+
+- One shared pool: `agent.poolLimits.advisor`, default 4 — configurable via `/config` 并发池 or config.json. Pool-full and same-scope launches are refused stating the current limit; launch reviews one at a time.
+- Inside a child (depth>0) reviews are always synchronous (`async:true` rejected).
+
+Returns the verdict: all-clear (call `verify`) or a findings list to fix.

package/tool-docs/doc_check.md

@@ -1,53 +1,59 @@
 Run a built-in documentation-discipline check on a project and report its findings.
 Read-only. In the default `report` mode it is non-gating: it reports, it never blocks, never sets an exit code, and its output is never a reason to refuse a task or a user instruction.
-When the engine files are newer than this session's start time (or unreadable), `report` prefixes its output with one
-`[doc_check note]` line naming the stale files — that reading came from an engine loaded at startup and is not usable as
-delivery evidence. Nothing else changes: `report` still produces no verdict and no existing line is altered (no stale files ⇒
-the report is byte-identical).
 
 What it checks — exactly two criteria, both built into the engine:
 - Anchors — every documentation pointer (a `*.md` token, optionally carrying directory segments, optionally followed by a section
   indicator `§N` / `§N.M` / `§N.M.K`) must resolve: the file must exist on disk (`档缺` when it does not), and when a section
   indicator is given the target file must carry a heading numbered with it (`节缺` when it does not). Line-number coordinates
+
   (`<doc>:12`) are not section references and are not judged as such. Files inside fenced code blocks and executable lines
   (command / pattern code spans) are skipped whole.
 
 ~~~text
-  **Operand names.** Six names count as operands rather than documents: the model writes them, or reads a file by that name. On
-  the prompt face (`thincoder-core/prompts/**`) they are stripped from a line before extraction. On other faces four of the six are
+  **Operand names.** Seven names count as operands rather than documents: the model writes them, or reads a file by that name. On
+  the prompt face (`thincoder-core/prompts/**`) they are stripped from a line before extraction. On other faces four of the seven are
+
   exempt as file-name classes — `AGENTS.md`, `SKILL.md`, `.thincoder/advisor.md`, `project_rules.md` — while `README.md` and
-  `MANIFEST.md` are still judged as pointers. The six:
+  `MANIFEST.md` are still judged as pointers. `RTM.md` is stripped on the prompt face; on other faces it is judged as a pointer — write it path-qualified (e.g. `test/RTM.md`) so it resolves. The seven:
 
   ```text
-  AGENTS.md  SKILL.md  README.md  MANIFEST.md  .thincoder/advisor.md  project_rules.md
+  AGENTS.md  SKILL.md  README.md  MANIFEST.md  .thincoder/advisor.md  project_rules.md  RTM.md
   ```
 ~~~
 
-- Line width — a line whose character count (CJK counts as 1) exceeds the built-in threshold, unless it is a table row, inside a
-  fenced code block, an executable line, a quote-block line, or inside an exempt zone.
+- Paragraph length — on a document face, adjacent non-blank body lines merge into one paragraph whose total character
+  count (CJK counts as 1) is judged against the built-in threshold; blank lines, table rows, headings, list items,
+  quote-block lines and fenced code blocks do not count into a paragraph and break it, and lines inside an exempt zone
+
+  are excluded. Breaking a paragraph into more lines changes nothing — only splitting it into more paragraphs or
+  writing it shorter passes.
+- Line length — a prompt-face file (`thincoder-core/prompts/**`) is judged line by line: the model reads raw text, so
+  one line is one block, and any single line over the threshold counts with no structural exemption.
 
 It cannot — in `report` mode — write anything, gate anything, or turn a finding into a refusal.
 
 Arguments — `target` (optional): the project root to check; defaults to the session anchor, relative paths resolve against it.
 A workspace target (several projects below it) is reported with the full candidate list — pass the project root you mean.
+
 `mode` (optional) — `report` (default: a non-gating report over the documents you list) or `gate` (the delivery gate below).
 `docs` (required) — the documents to judge, as paths relative to the project root or absolute; each is judged whole and nothing
+
 else is read except the targets those documents point at. Omitted in `gate` mode ⇒ the Markdown documents this session wrote.
 There is no default range in `report` mode: omitting `docs`, or passing an empty list, is refused rather than widened — nothing
+
 is scanned unless you name it. A path that is not on disk or is not a Markdown document is an error in `report` mode and nothing
 is judged; in `gate` mode such paths are listed as skipped instead. A pointer resolves against the project root (full path) or
+
 against the pointing document's own directory — bare names are not resolved across other directories.
 
 Delivery gate — `mode: "gate"`, for the end of a design or development round. Every listed doc is judged **whole**: a
-pre-existing dangling pointer or overlong line anywhere in it counts, not only this round's edited lines. The first line is the
+pre-existing dangling pointer or overlong paragraph / line anywhere in it counts, not only this round's edited lines. The first line is the
+
 machine-readable verdict — `DOC-CHECK GATE: PASS` / `DOC-CHECK GATE: REFUSED（命中 K 条）` / `DOC-CHECK GATE: ERROR（reason）` —
 and consumers judge by that prefix; the hits are fixed in the same round and are never booked to the ledger. The gate refuses
+
 **one delivery**, not a user instruction: an explicit user go-ahead is followed, with the hits written into the delivery.
-Before running the criteria the gate checks engine-version consistency: the six engine files (`doc-check/index.mjs` /
-`doc-check/anchors.mjs` / `doc-check/width.mjs` / `doc-check/version.mjs` / `agent-tools/doc-check.mjs` / this tool description) each have their mtime
-compared with this process's start time — newer, or unreadable, ⇒ `DOC-CHECK GATE: ERROR（引擎已更新…）` instead of a PASS,
-because a session keeps the engine modules it loaded at startup. `ERROR` is fail-closed (no PASS means not passed): restart the
-session and re-run; a multi-project workspace ⇒ name the project root, per the stated cause.
+`ERROR` is fail-closed (no PASS means not passed): a multi-project workspace ⇒ name the project root, per the stated cause.
 
 Do not wire it as a gate or CI step in `report` mode, and do not treat a finding as a reason to refuse an instruction — a
 machine check never outranks a user instruction.
@@ -59,6 +65,7 @@ Side effects and permissions — none. The tool is read-only: no writes, no appr
 
 Parameters and scope — both criteria run on built-in constants (`DOC_CHECK_BUILTINS`: threshold 300 characters, no exempt zones,
 no exemptions), and the judged set is the document list the caller passes — the judged set and the resolution set are the same
+
 documents, so there is no scan-dir / domain / root / exclude surface and no whole-repository scan. Changing a criterion or a
 threshold is a code change and goes through review; no project declaration changes these readings.
 

package/tool-docs/ledger.md

@@ -1,8 +1,8 @@
 台账统一入口——action = add / update / close / query / count。query / count 只读全角色；add / update / close 写仅主 agent。
 - add：新增条目入待讨论。kind = requirement（需求池）/ tech_todo（技术待办）；trigger = 归批 / 条件 / 认账不排期（可空）；resume_when = 复启条件句（可空；值非空——空串 / 全空白拒；句内可带锚 `@YYYY-MM-DD`（机判到期）或 `@事件件名`（机器不判））。task_book 写门（add ∥ update 同判，判本笔写入面）：结果行 在途 / 待核销 ∥ trigger = 归批 ⇒ task_book 必填（缺 / 空串 / 全空白拒）；本笔新写 task_book（非空值）∥ 本笔新写 trigger = 归批 ⇒ 该指针的文件部分（首个 `§` 前子串）须可解析且指出的档在盘，否则拒。本笔不动指针 ⇒ 零判零阻——旧指针所指档已被清理不阻 status / evidence / 其它字段更新（「档在不在盘」是读数 taskBookOnDisk，不是门）。
-- update：按六态允许表迁移：待讨论→待设计 / 待设计→在途 / 在途→待核销 / 待核销→已核销 / 任意态→已废弃；表外拒。id ∥ batch 恰携其一。status 缺省 = 仅更新字段；executor 缺省 = 进入待设计 / 在途自动写本会话，出在途 / 撤回清空；resume_when 同 update 可空字段（缺省 = 不变）。evidence 传入 = 追加（旧值非空 ⇒ 拼接 `旧｜新`——「｜」零空格；旧空直写）；`evidenceReplace: true` 与 evidence 同传 = 整段替换；旗独传（无新文）∥ 新值全空白 ⇒ 拒。
+- update：按六态允许表迁移：待讨论→待设计 / 待设计→在途 / 在途→待核销 / 待核销→已核销 / 任意态→已废弃；表外拒；迁移入 已核销 时结果行标题携「收尾链待跑」同拒（同笔携清标记 title 放行）。id ∥ batch 恰携其一。status 缺省 = 仅更新字段；executor 缺省 = 进入待设计 / 在途自动写本会话，出在途 / 撤回清空；resume_when 同 update 可空字段（缺省 = 不变）。evidence 传入 = 追加（旧值非空 ⇒ 拼接 `旧｜新`——「｜」零空格；旧空直写）；`evidenceReplace: true` 与 evidence 同传 = 整段替换；旗独传（无新文）∥ 新值全空白 ⇒ 拒。
 - update --batch：批级批量迁移（batch = 批档指针，与该档 task_book 同址的行一次处理）——携 status ⇒ 逐行按迁移表重判；不携 status ⇒ 纯字段补丁（status 零写）。回执 { batch, status, applied, skipped }；被跳过的行逐行点名 { id, from, why }（why = 逐行拒因原文），其余行照落；事务级失败整批回滚。batch 值须可解析且批档在盘，否则拒。
-- close：勾销（待核销 → 已核销）；追认核销（待讨论 / 待设计 → 已核销，须有 evidence——可随本调用传入（一跳核销），判结果值：缺 / 全空白拒）；在途 → 已核销 不可跳；撤回（任意态 → 已废弃）。软删除（写 closed_at，行保留）。id ∥ batch 恰携其一。evidence 传入 = 追加（旧值非空 ⇒ 拼接 `旧｜新`；旧空直写）；`evidenceReplace: true` 同传 = 整段替换；旗独传 / 新值全空白 ⇒ 拒；缺省 = 判行值。
+- close：勾销（待核销 → 已核销）；追认核销（待讨论 / 待设计 → 已核销，须有 evidence——可随本调用传入（一跳核销），判结果值：缺 / 全空白拒）；在途 → 已核销 不可跳；核销标记门：结果行标题携「收尾链待跑」⇒ 拒（收尾链未跑完，不许核销——先跑收尾全链，再由父侧清标记）；撤回（任意态 → 已废弃）不拦。软删除（写 closed_at，行保留）。id ∥ batch 恰携其一。evidence 传入 = 追加（旧值非空 ⇒ 拼接 `旧｜新`；旧空直写）；`evidenceReplace: true` 同传 = 整段替换；旗独传 / 新值全空白 ⇒ 拒；缺省 = 判行值。
 - close --batch：批级批量结算——只销已到 待核销 的行（勾销）；待讨论 / 待设计 逐行点名跳过（追认核销不入批量面，转单行 close），在途 逐行点名跳过（不可跳）；已核销 / 已废弃 行静默不计。status 可不给（缺省 = 已核销），给了只能是 已核销。
 - query：SQLite 行集，等值过滤（status / kind / board / trigger / task_book）缺省 = 全部行；行集逐行携 aged（未决四态 ∧ 行龄 > 30 天）/ evidenceOversize（evidence 超软上限 300 字——读数非拒写）/ taskBookOnDisk（task_book 文件部分解析成立 ∧ 该档在盘 ⇒ true；缺指针 / 不可解析 / 不在盘 ⇒ false——读数非门，不拦任何写入）/ overdue（出口态字串 ∥ null：resume_due / dangling / unlabeled / aged，首中优先）。六态 = 待讨论 / 待设计 / 在途 / 待核销 / 已核销 / 已废弃。
 - count：回报 { count, overdue, evidenceOversize }——count = 未决四态（待讨论 / 待设计 / 在途 / 待核销）行数；overdue = 其中命中出口态的行数；evidenceOversize = 其中 evidence 超限行数。task_book 等值过滤。