@thincoder/core 0.10.11 → 0.10.13

package/provider/errors.mjs

@@ -8,6 +8,7 @@
  */
 
 import { RETRYABLE_STATUS, RATE_LIMIT_BACKOFF_MS } from "./rate.mjs"
+import { requestBudget } from "../config.mjs"
 
 /** Parse Retry-After: 秒数 or HTTP-date；上限 300s（会诊 #11）— 异常头不得让 CLI 睡数小时。
  *  header 缺失/非法时退回指数退避表（rateLimitHits 计数取档）。 */
@@ -132,3 +133,43 @@ export function classifyResponsesErrorCode(code) {
       return null
   }
 }
+
+/** 越窗报文特征（§6.17 HTTP 400 分类——三个渠道的逐字形态；词表就这一处）。 */
+const CONTEXT_OVERFLOW_PHRASES = ["maximum context length", "context_length_exceeded", "prompt is too long"]
+
+/** 越窗 typed 错误（§6.17）：三实数逐字带出（prompt / max_tokens / 窗口，另附 limit）；kind / retryable
+ *  复用同族既有词表（`classifyResponsesErrorCode("context_length_exceeded")`），零新词。 */
+export function contextOverflowError(provider, prompt, budget, remedy) {
+  const cls = classifyResponsesErrorCode("context_length_exceeded")
+  const err = new Error(
+    `context overflow: prompt ~${prompt} tokens · max_tokens ${budget.maxTokens ?? "not sent"}` +
+    ` · window ${budget.window} (limit ${budget.limit}) — ${remedy} [model ${provider?.model ?? "unknown"}]`,
+  )
+  err.kind = cls.kind
+  err.retryable = cls.retryable
+  return err
+}
+
+/** 发送面净判（§6.17 第二道，四个装配面同形一次调用）：`estPrompt` = 输入侧估算
+ *  （= `estimateRequestTokens(X) − (body.max_tokens ?? 0)`，四面同一定义——不减会把输出预算白扣一份）。
+ *  内部阶段豁免：`compress` / `distill` / 续写本身就是越线后用来把上下文降下来的那次调用，
+ *  判它 = 判掉止血动作本身（标签已存在，零新增机制）。 */
+export function assertPromptFits(provider, estPrompt, logCtx) {
+  const stage = logCtx?.stage
+  if (stage === "compress" || stage === "distill" || logCtx?.isContinuation === true) return
+  const budget = requestBudget(provider)
+  if (!(estPrompt > budget.limit)) return
+  throw contextOverflowError(provider, estPrompt, budget, "the request was not sent; reduce the conversation (/compact or prune) before retrying")
+}
+
+/** HTTP 400 越窗报文 ⇒ typed 错误（§6.17）；未命中 ⇒ 原样返回入参错误（不发明分类）。 */
+export function markContextOverflow(error, status, text) {
+  if (status !== 400) return error
+  const lower = String(text ?? "").toLowerCase()
+  if (!CONTEXT_OVERFLOW_PHRASES.some((p) => lower.includes(p))) return error
+  const cls = classifyResponsesErrorCode("context_length_exceeded")
+  error.kind = cls.kind
+  error.retryable = cls.retryable
+  if (cls.hint) error.message += `（${cls.hint}）`
+  return error
+}

package/provider/google.mjs

@@ -5,12 +5,14 @@
  */
 
 import { proxyFetch } from "../proxy.mjs"
+import { withUserAgent } from "../client-identity.mjs"
 import { requestWithRetry } from "./retry.mjs"
 import { effectiveFetchTimeoutMs, effectiveBodyIdleMs } from "./core.mjs"
 import { abortError, timeoutError } from "../abort-provenance.mjs"
 import { terminateBody } from "../stream-destroy.mjs"
 import { requestBudget } from "../config.mjs"
 import { DEFAULT_BODY_IDLE_MS } from "../config-defaults.mjs"
+import { assertPromptFits } from "./errors.mjs"
 
 /** OpenAI 语义 tool_choice → Gemini FunctionCallingConfig（2026-08-31 能力层）。 */
 function mapFunctionCallingConfig(choice) {
@@ -77,7 +79,7 @@ export function convertMessages(messages) {
 
 /** Build and send a Gemini chat request. Returns the same shape as core.mjs chat.
  *  2026-08-31 会诊 #6：接入 rateGate/recordRate（原实现完全绕过 TPM/RPM 闸门）。 */
-export async function chat(provider, { messages, tools, onToken, onReasoning, onWait, signal, toolChoice }) {
+export async function chat(provider, { messages, tools, onToken, onReasoning, onWait, signal, toolChoice, logCtx }) {
   const systemMessages = messages.filter((m) => m.role === "system")
   const contents = convertMessages(messages)
 
@@ -118,7 +120,10 @@ export async function chat(provider, { messages, tools, onToken, onReasoning, on
 
   // 会诊 #6：TPM/RPM 闸门 + 记账
   const { rateGate, recordRate, estimateRequestTokens } = await import("./rate.mjs")
-  const estimated = estimateRequestTokens({ messages })
+  // §6.17 发送面净判：估准面补 `tools`（原只投影 messages）；body 用 `maxOutputTokens`、无 `max_tokens` 键 ⇒ 减项恒 0
+  const estimated = estimateRequestTokens({ messages, tools })
+  const estPrompt = estimated - (body.max_tokens ?? 0)
+  assertPromptFits(provider, estPrompt, logCtx)
   await rateGate(provider, estimated, onWait, signal)
 
   // 2026-08-31：5xx/网络与 OpenAI 格式统一退避重试链（原完全无重试——Gemini 高峰
@@ -126,7 +131,7 @@ export async function chat(provider, { messages, tools, onToken, onReasoning, on
   const response = await requestWithRetry(
     () => proxyFetch(url, {
       method: "POST",
-      headers: { ...(provider.headers ?? {}), "Content-Type": "application/json" }, // 定制头展开（PROVIDER.md §21）——定制头在前、内置头在后：内置头胜出
+      headers: { ...withUserAgent(provider.headers), "Content-Type": "application/json" }, // 定制头 + 产品标识头（UA 不可被渠道覆盖——PROVIDER.md §6.17）；内置头在后故同名胜出
       body: JSON.stringify(body),
       // 2026-09-01：同 core.mjs——绝对墙钟废除；响应头阶段 fetchTimeoutMs（600s 默认），body 阶段读侧 idle 管
       signal,
@@ -145,6 +150,7 @@ export async function chat(provider, { messages, tools, onToken, onReasoning, on
       content: result.content,
       reasoning: result.reasoning,
       finishReason: result.finishReason ?? null, // §6.31.7 F-DA5（原三 transport 恒 null——字段值收正）
+      estimated: estPrompt, // §6.17 自校准采样（den 与净判同口径）
       usage: {
         prompt_tokens: usage.prompt_tokens ?? 0,
         completion_tokens: usage.completion_tokens ?? 0,
@@ -154,7 +160,7 @@ export async function chat(provider, { messages, tools, onToken, onReasoning, on
     }
   }
 
-  return { content: result.content, reasoning: result.reasoning, finishReason: result.finishReason ?? null, toolCalls: result.toolCalls }
+  return { content: result.content, reasoning: result.reasoning, finishReason: result.finishReason ?? null, estimated: estPrompt, toolCalls: result.toolCalls }
 }
 
 /** Gemini `finishReason` ⇒ 核统一 `finishReason`（§6.31.7 F-DA5——归一只喂既有分类；

package/provider/list-models.mjs

@@ -14,6 +14,7 @@
  * 解析保持防御性（字段缺失即跳过该项）。候选不过滤非对话模型（embedding 等——§16.6 #14）。
  */
 import { proxyFetch } from "../proxy.mjs"
+import { withUserAgent } from "../client-identity.mjs"
 import { resolveProviderSecrets } from "../env-ref.mjs"
 import { positiveInt, recordListedContext } from "../model-context.mjs"
 
@@ -74,7 +75,7 @@ function listedWindowOf(row) {
 
 async function listOpenai(provider, signal) {
   const url = `${provider.baseURL}/models`
-  const data = await fetchJson(provider, url, { ...(provider.headers ?? {}), Authorization: `Bearer ${provider.apiKey ?? ""}` }, signal)
+  const data = await fetchJson(provider, url, { ...withUserAgent(provider.headers), Authorization: `Bearer ${provider.apiKey ?? ""}` }, signal)
   // L3 写面的收集段（PROVIDER.md §6.15）：解析 `data[]` 时顺带收 `id → 窗口`——三字段按序取
   // 第一个**合法**值（R25 ∥ R26），非法相当于该字段缺席；三字段都不可得 = 该模型列表未报（不进表）。
   const ids = []
@@ -92,7 +93,7 @@ async function listOpenai(provider, signal) {
 }
 
 async function listAnthropic(provider, signal) {
-  const headers = { ...(provider.headers ?? {}), "x-api-key": provider.apiKey ?? "", "anthropic-version": ANTHROPIC_VERSION }
+  const headers = { ...withUserAgent(provider.headers), "x-api-key": provider.apiKey ?? "", "anthropic-version": ANTHROPIC_VERSION }
   const base = `${provider.baseURL}/models?limit=1000`
   const out = []
   let afterId = null
@@ -108,7 +109,7 @@ async function listAnthropic(provider, signal) {
 }
 
 async function listGoogle(provider, signal) {
-  const headers = { ...(provider.headers ?? {}) }
+  const headers = { ...withUserAgent(provider.headers) }
   const base = `${provider.baseURL}/models?key=${encodeURIComponent(provider.apiKey ?? "")}&pageSize=1000`
   const out = []
   let pageToken = null

package/provider/responses.mjs

@@ -13,10 +13,11 @@
  */
 import { effectiveFetchTimeoutMs, effectiveBodyIdleMs } from "./core.mjs"
 import { proxyFetch } from "../proxy.mjs"
+import { withUserAgent } from "../client-identity.mjs"
 import { requestWithRetry } from "./retry.mjs"
 import { rateGate, recordRate, estimateRequestTokens } from "./rate.mjs"
 import { buildBody, normalizeUsage } from "./responses-request.mjs"
-import { classifyResponsesErrorCode } from "./errors.mjs"
+import { classifyResponsesErrorCode, assertPromptFits } from "./errors.mjs"
 // 同名 re-export（2026-09-29 structure-split-2 · 台账 #620——缝 = 同名再出口）：请求构造面出档 `provider/responses-request.mjs`；
 // `buildBody` / `isStoreRequiredHost` / `builtinToolsFor` 三名既有导出经本档转口——消费者 import 面零改。
 export { buildBody, isStoreRequiredHost, builtinToolsFor } from "./responses-request.mjs"
@@ -223,15 +224,18 @@ function handleEvent(ev, h) {
 }
 
 /** 主入口：请求 + 链状态推进（与 core.mjs 的 chat 同形返回）。 */
-export async function chat(provider, { messages, tools, onToken, onReasoning, onWait, signal, toolChoice, stateful }) {
+export async function chat(provider, { messages, tools, onToken, onReasoning, onWait, signal, toolChoice, stateful, logCtx }) {
   const { body: reqBody, previousResponseId, warnings, newChain } = buildBody(provider, messages, tools, { toolChoice, stateful })
   const body = { ...reqBody, ...(previousResponseId ? { previous_response_id: previousResponseId } : {}) }
 
   // rateGate/recordRate 对齐 core（responses body 无 messages 键——按本地全量 messages 估算）
-  const estimated = estimateRequestTokens({ messages })
+  // §6.17 发送面净判：估准面补 `tools`（原只投影 messages）；body 用 `max_output_tokens`、无 `max_tokens` 键 ⇒ 减项恒 0
+  const estimated = estimateRequestTokens({ messages, tools })
+  const estPrompt = estimated - (body.max_tokens ?? 0)
+  assertPromptFits(provider, estPrompt, logCtx)
   await rateGate(provider, estimated, onWait, signal)
-  // 定制头展开（PROVIDER.md §21）：provider.headers 在前、内置头在后——同名内置头胜出（三处 fetch 共用）
-  const headers = { ...(provider.headers ?? {}), "Content-Type": "application/json", Authorization: `Bearer ${provider.apiKey}` }
+  // 定制头 + 产品标识头（UA 不可被渠道覆盖——PROVIDER.md §6.17）：定制头在前、内置头在后——同名内置头胜出（三处 fetch 共用）
+  const headers = { ...withUserAgent(provider.headers), "Content-Type": "application/json", Authorization: `Bearer ${provider.apiKey}` }
 
   // round2 复验 #1（2026-08-31）：retry 层对 4xx 非可重试是 throw 而非返回——
   // requestWithRetry 从不返回 400/404 响应 → 下方 isChainInvalidError 分支原来不可达（D6 死代码）。
@@ -287,11 +291,17 @@ export async function chat(provider, { messages, tools, onToken, onReasoning, on
       { signal, onWait, buildMessage: (status, text) => `Responses API error ${status}: ${text}` },
     )
   }
-  return finish(provider, response, { onToken, onReasoning, signal, newChain, warnings, estimated })
+  return finish(provider, response, {
+    onToken, onReasoning, signal, newChain, warnings, estimated,
+    // §6.17 自校准口径：链式（`previous_response_id`）请求的 body 只带增量（`responses-request.mjs`
+    // `body.input = newOutputs`），而分母是本地全量估算 ⇒ 两者口径不同，本轮不采样。
+    estPrompt: previousResponseId ? undefined : estPrompt,
+  })
 }
 
-async function finish(provider, response, { onToken, onReasoning, signal, newChain, warnings, estimated }) {
+async function finish(provider, response, { onToken, onReasoning, signal, newChain, warnings, estimated, estPrompt }) {
   const result = await parseStream(response, { onToken, onReasoning, signal })
+  result.estimated = estPrompt // §6.17 自校准采样（den 与净判同口径）
   recordRate(provider, estimated, result.usage)
   // 链状态推进：completed 事件里 response.id 供同一 turn 后续增量；
   // 截断/失败/无 id（部分端点不回传）→ 链作废（后续全量，正确性优先）。

package/session-lifecycle.mjs

@@ -322,6 +322,9 @@ export function resetSessionState(agent) {
   agent._runStartHistoryLen = 0
   agent._lastPromptTokens = null
   agent._usageAtLen = null
+  // §6.17 估算自校准：新会话无样本（比 = 1）——跨会话不继承旧模型的估算偏差
+  agent._tok = null
+  agent._tokRatio = 1
   agent.planMode = false
   agent.goal = null
   agent._pendingReminders = []

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 门控）。
  */
 
@@ -193,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

@@ -100,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`

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,
   }
 }
 
@@ -151,6 +159,16 @@ 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 }
@@ -159,11 +177,14 @@ export function restoreEngTokens(agent, data) {
 // ── 会话槽权威台账 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
 }
 
@@ -185,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。
@@ -281,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/token-window.mjs

@@ -138,11 +138,13 @@ export function contextUsage(agent, extras = {}) {
   const overhead = system + tools
   const historyTokens = estimateTokens(history)
   const measured = agent?._lastPromptTokens != null
+  // §6.3 / §6.17 估算自校准：估算值乘 `_tokRatio`；`_lastPromptTokens` 是服务端真值，不乘。
+  const ratio = agent?._tokRatio ?? 1
   return {
     basis: measured ? "measured" : "estimated",
     total: measured
-      ? agent._lastPromptTokens + estimateTokens(history.slice(agent._usageAtLen ?? history.length))
-      : historyTokens + overhead,
+      ? agent._lastPromptTokens + Math.round(estimateTokens(history.slice(agent._usageAtLen ?? history.length)) * ratio)
+      : Math.round((historyTokens + overhead) * ratio),
     history: historyTokens,
     system,
     tools,
@@ -153,6 +155,25 @@ export function contextUsage(agent, extras = {}) {
   }
 }
 
+/**
+ * 估算自校准采样（§6.17「估算自校准」）——池化比：`num += usage.prompt_tokens`、`den += estPrompt`
+ * （分子分母同取输入侧口径；`estPrompt` 由发送面随 result 带回，与净判同一个值）。
+ * `key = format:model` 变 ⇒ 归零重采（切模型自清，不接四个刷新点）；`_tok` / `_tokRatio` 只由本函数写，
+ * `/new` 与 run 装配复位。无样本 ⇒ 比 = 1（估算维持原口径）。
+ * 作用面 = `contextUsage` 两支承（§6.3）；实测基线 `_lastPromptTokens` 不乘。
+ */
+export function recordTokenSample(agent, provider, estPrompt, usage) {
+  const prompt = Number(usage?.prompt_tokens)
+  if (!agent || !(prompt > 0) || !(estPrompt > 0)) return
+  const key = `${provider?.format ?? "openai"}:${provider?.model ?? ""}`
+  if (agent._tok?.key !== key) agent._tok = { key, num: 0, den: 0 }
+  agent._tok.num += prompt
+  agent._tok.den += estPrompt
+  // 下界 = 1：已知偏差方向是估算偏低；比 < 1 会把全部估算支缩小、重开「该压没压」原始故障，
+  // 保守方向不取（仅一侧校准，零新魔数）。
+  agent._tokRatio = Math.max(1, agent._tok.num / agent._tok.den)
+}
+
 /**
  * 状态行百分比（§6.16.4「与状态行 ctx% 的单源关系」）——与 CLI 状态行（`render-frame.mjs` 式）与 VSC `ctxPercentForHistory` **同式**；
  * stats 报出的就是用户看到的那个百分比（不新增第三口径）；空历史 ⇒ 0（状态行的 `ctxPct > 0` 显示门在端侧）。

package/tool-docs/wait_for.md

@@ -1,15 +1,24 @@
-Wait until a condition becomes true — polls the condition every interval_ms and returns as soon as it holds or the timeout_ms ceiling passes. Use it ONLY for genuinely asynchronous waits: an async subagent/consult still settling, a file appearing, a port opening. Synchronous tools (advisor, blocking subagent spawn) return when done — waiting after them is NOT needed and wastes time.
+Wait until a condition becomes true — polls every interval_ms and returns as soon as it holds or timeout_ms passes.
+
+**Use it only for states that cannot announce themselves**: a file appearing, a port opening, a background bash or browser task finishing. Nothing delivers those into the session, so a blocking wait is the only way to learn about them.
+
+**Never use it to wait for a subagent or a review report.** Those arrive on their own when the session is idle — the act of waiting for one is simply ending the turn.
+
+`wait_for "subagent id:N done"` and `wait_for "advisor settled"` park the session for the whole budget, poll hundreds of times, and learn nothing you would not have been handed anyway.
+
+Measured in practice: two such waits in one session burned ~4.5 minutes and 210 polls on reports that were already on their way. The conditions stay supported (a background task genuinely may need joining), but reaching for them on a child is the classic misuse.
 
 Parameters:
 - condition (required): a semantic condition expression:
-  - `advisor settled` — an in-flight advisor review session has finished (async advisor-role children settled)
-  - `subagent id:N done` — async subagent N (the id your async spawn ack returned) has settled
-  - `consult done` — every consult_start session has drained
+  - `advisor settled` — an in-flight advisor review session has finished — **discouraged**: the report is delivered automatically; end the turn instead
+  - `subagent id:N done` — async subagent N (the id your async spawn ack returned) has settled — **discouraged**, same reason
+  - `consult done` — every consult_start session has drained — the verdict text is delivered automatically; wait only when a synchronous caller cannot proceed without it
   - `bash id:N done` — background bash task N (the id from the bash async ack, `bash#N`) has finished — settled, or already left the pool (nothing left to wait on)
   - `browser id:N done` — a background browser task N (the id from the ack, `browser#N`) has settled — finished, or already left the pool (nothing left to wait on)
   - `file exists:path` — the file at path exists (path relative to cwd)
   - `port open:N` — something is listening on 127.0.0.1 port N
-  - The agent-internal conditions (advisor / subagent / consult / bash) apply to ASYNC sessions only — a synchronous call already completed before it returned and has nothing to wait for. An unknown condition is an explicit error (`wait_for: unsupported condition "..."` — the supported forms are listed above), never a silent wait.
+  - The agent-internal conditions (advisor / subagent / consult / bash) apply to ASYNC sessions only — a synchronous call already completed before it returned and has nothing to wait for.
+  - An unknown condition is an explicit error (`wait_for: unsupported condition "..."` — the supported forms are listed above), never a silent wait.
 - interval_ms: poll interval (default 1000, floor 100 — polling never busy-spins)
 - timeout_ms: overall ceiling (default 30000; config.json `agent.waitForTimeoutMs` overrides the default; hard cap 600000 like the execute tool)
 
@@ -21,4 +30,4 @@ Returns:
 Notes:
 - Read-only and non-destructive — it only observes (agent pools, the filesystem, a local port probe).
 - Blocking by design — call it ALONE in a turn, not batched with calls that depend on its result.
-- Do not use it to wait after synchronous tools (advisor / blocking subagent spawn / verify return only when done).
+- This is the one blocking call an agent usually should not reach for. Before calling it, ask: **will this state announce itself to me anyway?** If yes (a subagent report, a review digest, a timer), end the turn and let it arrive.