@thincoder/core 0.10.12 → 0.11.1

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,
@@ -136,7 +141,7 @@ export async function chat(provider, { messages, tools, onToken, onReasoning, on
     { signal, onWait, buildMessage: (status, text) => `Gemini API error ${status}: ${text}` },
   )
 
-  const result = await parseGeminiStream(response, { onToken, onReasoning, signal, idleMs: effectiveBodyIdleMs(provider) })
+  const result = await parseGeminiStream(response, { onToken, onReasoning, signal, idleMs: effectiveBodyIdleMs(provider), firstChunkMs: effectiveFetchTimeoutMs(provider) })
   recordRate(provider, estimated, result.usage)
 
   const usage = result.usage
@@ -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——归一只喂既有分类；
@@ -169,7 +175,7 @@ function mapGeminiFinishReason(reason) {
  * Parse Gemini SSE stream.
  * Format: data: {...}\n\n (each line is a complete JSON object)
  */
-async function parseGeminiStream(response, { onToken, onReasoning, signal, idleMs = DEFAULT_BODY_IDLE_MS }) {
+export async function parseGeminiStream(response, { onToken, onReasoning, signal, idleMs = DEFAULT_BODY_IDLE_MS, firstChunkMs }) {
   const result = { content: "", reasoning: "", toolCalls: [], usage: null, finishReason: null }
   const decoder = new TextDecoder()
   let buffer = ""
@@ -216,21 +222,31 @@ async function parseGeminiStream(response, { onToken, onReasoning, signal, idleM
 
   if (!response.body) throw new Error("No stream response body")
   // 2026-09-01 读侧 idle 超时（同 sse.mjs）：body 有数据流动即不超时；连续 `idleMs` 无新 chunk 判死
+  // （首 chunk 之前改用首 chunk 窗，见下）
+  // 首 chunk 两态臂（TIMEOUT-DIGEST.md §2.4）：首个 body 字节前用 `firstChunkMs`，之后每次重挂用 `idleMs`
   let idleTimer = null
   let idleError = null
+  let gotFirstChunk = false
   const armIdle = () => {
     if (idleTimer) clearTimeout(idleTimer)
+    // 同 sse.mjs：首挂窗缺省取 `idleMs`，相位文案按态取（未传者仍报既有 `google-sse-idle`）
+    const firstArm = !gotFirstChunk
+    const ms = firstArm ? (firstChunkMs ?? idleMs) : idleMs
+    const firstChunkPhase = firstArm && firstChunkMs != null
     idleTimer = setTimeout(() => {
       // #878：断流单点分流——直连 fetch（web 流）走 `IDLE_ABORT` 内部 abort 通道；
-      // proxy 形回落 destroyBody（原契约）。相位串 = 本分支专属 google-sse-idle。
-      idleError = timeoutError(`SSE idle timeout: no data for ${idleMs / 1000}s`, "provider", "google-sse-idle")
+      // proxy 形回落 destroyBody（原契约）。
+      idleError = firstChunkPhase
+        ? timeoutError(`SSE first-chunk timeout: no data for ${ms / 1000}s`, "provider", "google-sse-first-chunk")
+        : timeoutError(`SSE idle timeout: no data for ${ms / 1000}s`, "provider", "google-sse-idle")
       try { terminateBody(response, idleError) } catch { /* already gone */ }
-    }, idleMs)
+    }, ms)
     idleTimer.unref?.()
   }
   armIdle()
   try {
     for await (const chunk of response.body) {
+      gotFirstChunk = true
       armIdle()
       if (signal?.aborted) {
         throw abortError(signal, "provider", "transport-google")

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/rate.mjs

@@ -1,4 +1,4 @@
-/**
+/**
  * provider/rate.mjs — TPM/RPM proactive throttling gate
  * Sliding-window accounting; pre-check budget before sending requests; sleep until window frees space when over budget.
  */
@@ -42,8 +42,16 @@ function rateKey(provider) {
   return `${base}|${provider.apiKey ?? ""}`
 }
 
+/** 估算口径（CONTEXT-COMPACTION.md §6.17.1 链一，**单源**）：ASCII `ASCII_CHARS_PER_TOKEN` 字符/token；
+ *  非 ASCII（CJK/emoji）1 字/token（保守方向，不动）。取 3 的依据 = 失败现场服务端报 723,272 in messages
+ *  ÷ 同刻状态栏 491k ≈ 2.7 字符/token ⇒ 旧值 `/4` 低报约 1.47 倍（余下由链二按模型自校准吸收）。 */
+export const ASCII_CHARS_PER_TOKEN = 3
+/** 估算口径版本位（§6.17.1 链二）：落槽的校准样本只在同版本内复用——改公式即自动弃旧样本。 */
+export const ESTIMATOR_VERSION = 1
+
 /** Rough estimate of text token count.
- *  ASCII ~4 chars/token; non-ASCII (CJK/emoji) ~1 char/token (conservative; measured BPE is 1.5-2.5 chars/token).
+ *  ASCII ~3 chars/token (`ASCII_CHARS_PER_TOKEN`); non-ASCII (CJK/emoji) ~1 char/token
+ *  (conservative; measured BPE is 1.5-2.5 chars/token).
  *  §2.5 #114 并入（token 估算取并集）：数组内容按 part 分派——text 走单串估算，
  *  image_url part 计 85 tokens（VSC 侧口径）。 */
 export function estimateText(s) {
@@ -62,7 +70,7 @@ export function estimateText(s) {
 function _estimateSingle(s) {
   let nonAscii = 0
   for (let i = 0; i < s.length; i++) if (s.charCodeAt(i) > 0x7f) nonAscii++
-  return Math.ceil((s.length - nonAscii) / 4) + nonAscii
+  return Math.ceil((s.length - nonAscii) / ASCII_CHARS_PER_TOKEN) + nonAscii
 }
 
 /** Estimated prompt tokens for this request */

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/provider/sse.mjs

@@ -90,7 +90,7 @@ function finalizeToolCalls(result) {
   }
 }
 
-export async function readSSE(response, { onToken, onReasoning, rules, signal, firedPatterns: sharedFired, idleMs = DEFAULT_BODY_IDLE_MS }) {
+export async function readSSE(response, { onToken, onReasoning, rules, signal, firedPatterns: sharedFired, idleMs = DEFAULT_BODY_IDLE_MS, firstChunkMs }) {
   // Early intercept: non-SSE responses — either error bodies (HTTP >= 400) or
   // valid single-chunk JSON completions (some APIs return JSON despite stream:true).
   const contentType = response.headers.get("content-type") || ""
@@ -198,23 +198,34 @@ export async function readSSE(response, { onToken, onReasoning, rules, signal, f
   // 2026-09-01 读侧 idle 超时（根因修复）：原实现靠 fetch 层的 600s 绝对墙钟兜底——长上下文子代理
   // 单次生成（或上游排队）超 10 分钟即被腰斩（"The operation was aborted due to timeout" 直透）。
   // 现改为：读侧空闲超时——body 只要有数据流动就永不超时，连续 `idleMs` 无新 chunk 才判死
-  // （`idleMs` 由 provider/core.mjs 的 effectiveBodyIdleMs 算好传入，缺省 DEFAULT_BODY_IDLE_MS）。
+  // （首 chunk 之前改用首 chunk 窗，见下；`idleMs` 由 provider/core.mjs 的 effectiveBodyIdleMs 算好传入）。
   // 直连 fetch 与 proxyFetch 统一走这里（proxy 的 _bodyIdleMs 语义与之等价，双保险）。
   let idleTimer = null
   let idleError = null
+  // 首 chunk 两态臂（TIMEOUT-DIGEST.md §2.4）：首次挂用 `firstChunkMs`，收到第一个 body 字节后
+  // 每次重挂改用 `idleMs`——翻转不可逆（流中途不会退回「等首 chunk」态）。
+  let gotFirstChunk = false
   const armIdle = () => {
     if (idleTimer) clearTimeout(idleTimer)
+    // 窗与文案同源（`N` = 该相位实际生效的窗值）：首挂窗缺省取 `idleMs`（入参缺省 = 老行为），
+    // 相位文案按态取——真传了首 chunk 窗才是分窗使用者（未传者仍报既有 `sse-idle`，逐字零变）。
+    const firstArm = !gotFirstChunk
+    const ms = firstArm ? (firstChunkMs ?? idleMs) : idleMs
+    const firstChunkPhase = firstArm && firstChunkMs != null
     idleTimer = setTimeout(() => {
       // #878：断流单点分流——直连 fetch（web 流）走 `IDLE_ABORT` 内部 abort 通道，
       // proxy 形回落 destroyBody（原契约）。
-      idleError = timeoutError(`SSE idle timeout: no data for ${idleMs / 1000}s`, "provider", "sse-idle")
+      idleError = firstChunkPhase
+        ? timeoutError(`SSE first-chunk timeout: no data for ${ms / 1000}s`, "provider", "sse-first-chunk")
+        : timeoutError(`SSE idle timeout: no data for ${ms / 1000}s`, "provider", "sse-idle")
       try { terminateBody(response, idleError) } catch { /* already gone */ }
-    }, idleMs)
+    }, ms)
     idleTimer.unref?.()
   }
   armIdle()
   try {
     for await (const chunk of response.body) {
+      gotFirstChunk = true
       armIdle()
       if (signal?.aborted) {
         throw abortError(signal, "provider", "stream-read")

package/session-identity.mjs

@@ -0,0 +1,21 @@
+/**
+ * session-identity.mjs — 进程会话 id 单源（零 import 叶档）——PROVIDER.md §6.17「会话标识头」。
+ *
+ * 为什么单立一叶：请求装配面 `client-identity.mjs` 是零依赖叶子，而每个 transport 都 import 它；
+ * 会话 id 又要「每次请求现取」。若从 `session-slots.mjs` 取，会把它的依赖链（config 读盘 ∥ 会话
+ * 存储 ∥ 进程探测共 8 档）连带拉进每个 transport 的 import 图。故本体住本档，`session-slots.mjs`
+ * 反向 re-export——既有 import 面零改。
+ *
+ * 语义：进程级惰性生成、零 IO、进程内稳定；形 `{pid}-{ts}-{rand6}`。它区分的是「哪一次进程会话」，
+ * 不是「槽位里的哪一份对话」（按对话槽分桶属另批穿参改造）。
+ */
+
+let currentSessionId = null
+
+/** Generate unique session ID for this process */
+export function getSessionId() {
+  if (!currentSessionId) {
+    currentSessionId = `${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
+  }
+  return currentSessionId
+}

package/session-lifecycle.mjs

@@ -36,8 +36,8 @@ import { loadSlotFile } from "./session.mjs"
 // 与 VSC `newSlot` / `loadSlotForWrite` 全新分支同一构造器；环 import 同上，函数体内运行时使用）。
 import { newSlotData } from "./session-slot-write.mjs"
 import { mergeAdjacentAssistantEchoes } from "./context.mjs"
-// 打开态读数公式（§6.24 判据句 2——与 CLI 状态行 / VSC 同式；零新公式，只组合）。
-import { historyPercent } from "./token-window.mjs"
+// 打开态读数公式（§6.24 判据句 2——与 CLI 状态行 / VSC 同一实现点的投影；零新公式，只组合）。
+import { historyPercent, restoreTokenSample, sampleRatio } from "./token-window.mjs"
 import { scheduleSessionGC } from "./session-gc.mjs"
 import { restoreEngTokens, tokenExpired } from "./token-ttl.mjs"
 // 槽事件（docs/core/design/SESSION-OBSERVABILITY.md §3.1）：`slot:new` 走核日志单一通道。
@@ -210,10 +210,15 @@ export function applySession(agent, data, opts = {}) {
         agent.provider.reasoningEffort = data.effort
       }
     }
+    // §6.17.1 链二读面：估算校准样本随槽恢复——上行刚把 `provider` 按槽值落定，key 同源校验才有意义
+    // （四条校验在 `restoreTokenSample`：形状 / est 版本 / key 同源 / 下界 1；不合格 ⇒ 未校准档）。
+    restoreTokenSample(agent, data.estimateSample, agent.provider)
     return { switched, droppedDesignTokens: restored.droppedDesignTokens }
   }
   // ② 槽无 key ∥ 不在册 → D-S3 保留——静默保持现状（落 config 链：config 统一解析产物已是
   //    `agent.provider`；不报错不纠正——两方都无效由调用侧复验 validateProvider 弹重选）
+  // §6.17.1 链二读面（B 支出口同 A 支）：样本照旧随槽恢复（provider = config 链产物，key 同源校验照做）
+  restoreTokenSample(agent, data.estimateSample, agent.provider)
   return { switched: false, droppedDesignTokens: restored.droppedDesignTokens }
 }
 
@@ -322,6 +327,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 = []
@@ -398,7 +406,7 @@ export function slotOccupancy(cwd, slot) {
  *     ⇒ 落链）∥ 无槽模型 ⇒ 现行模型链回落（`defaultModel` 属本渠道 ⇒ 其模型段；两档皆无 ⇒ `null`——
  *     `resolveChannelModel`，2026-10-09 清除批：渠道单值模型退场，零静默回落）；未命中 ⇒ `fallback`
  *     （支 ②「静默保持现状」的装配口径 = `loadConfig().provider`）；
- *  ④ 公式 = `historyPercent`（`thincoder-core/token-window.mjs`——与 CLI 状态行 / VSC 同式）。
+ *  ④ 公式 = 核 `historyReading`（与 CLI ∥ VSC 同一实现点的投影）；第三参 = 槽样本经 `sampleRatio` 取的校准比。
  *  **零副作用**：`data` / `providers` / `fallback` / `defaultModel` 皆入参（不读盘、不写盘、不改任何进程态）；
  *  `data` 非对象 ⇒ `0`（与空历史同值——「非正 ⇒ 零节点」显示门归端侧，沿 `historyPercent` 空历史口径）。 */
 export function sessionReading(data, { providers, fallback, defaultModel } = {}) {
@@ -414,5 +422,5 @@ export function sessionReading(data, { providers, fallback, defaultModel } = {})
   const provider = entry
     ? { ...entry, model: slotModel ?? resolveChannelModel(entry, defaultModel ?? null) }
     : fallback
-  return historyPercent(line, provider)
+  return historyPercent(line, provider, sampleRatio(data.estimateSample, provider))
 }

package/session-slots.mjs

@@ -6,10 +6,10 @@
  * init-block 批 · F-MI7 二次拆分：探测束接线后本档实读 517 行（破 490 判定线并越 500 硬限）
  * ⇒ 按 `CORE-UNIFICATION.md` §2.8.1 子表原行 3（已随 2026-10-08 批清账）**随批**外提清单 / 认领 / 属主面至
  * `session-slots-manifest.mjs`（语义原样迁移；本档 re-export 该档导出保既有 import 面——
- * 消费档 import 路径与名面不动）。本档保留 = 存储原语（cwd 哈希 / 路径 / 原子写 / 进程
- * sessionId）· 端记录（end marker）· 列表面（listSlots——条目集 = 盘面实读；扫描面住
- * `session-slot-scan.mjs`）· 删槽 · 恢复决策面
- * （usableSlot / loadLegacyFile / resumeSlot）。
+ * 消费档 import 路径与名面不动）。本档保留 = 存储原语（cwd 哈希 / 路径 / 原子写）· 端记录
+ * （end marker）· 列表面（listSlots——条目集 = 盘面实读；扫描面住 `session-slot-scan.mjs`）·
+ * 删槽 · 恢复决策面（usableSlot / loadLegacyFile / resumeSlot）。进程 sessionId 的本体已迁
+ * 零 import 叶 `session-identity.mjs`（PROVIDER.md §6.17），本档 re-export 保名面。
  *
  * 端名缝（SESSION.md §6.20 D-SE50 · 2026-09-25 SLOT-END-PARAM 批）：端名 = **进程内的单值
  * 声明**（`setSessionEnd` / `sessionEnd`；`END` 仅模块级初值——CLI 零声明即得「cli」）。
@@ -53,20 +53,15 @@ import {
 import { scanSlotMetas } from "./session-slot-scan.mjs"
 // 读面懒核实面（§6.25 判据句 3 落点 B——不可信清单调度：纯内存登记 + 启动窗外延迟拍）；静态环同形。
 import { scheduleVerify } from "./session-slot-verify.mjs"
+// 进程会话 id（PROVIDER.md §6.17 会话标识头）：本体住零 import 叶 `session-identity.mjs`——本档的
+// 依赖链会经请求装配面被拉进每个 transport 的 import 图，故迁出。本档 import 取用（usableSlot ∥
+// resumeSlot 的属主判据）+ 下行 re-export 保既有 import 面零改（消费档路径与名面不动）。
+import { getSessionId } from "./session-identity.mjs"
 export {
   slotDigest, loadManifest, saveManifest, ownerPid, ownerPids,
   allocateFresh, claimSlot, activeSlot, ledgerHealth,
 } from "./session-slots-manifest.mjs"
-
-let currentSessionId = null
-
-/** Generate unique session ID for this process */
-export function getSessionId() {
-  if (!currentSessionId) {
-    currentSessionId = `${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
-  }
-  return currentSessionId
-}
+export { getSessionId }
 
 /** Normalize cwd for hashing: uppercase Windows drive letter so both ends
  *  (CLI's process.cwd() vs VS Code's uri.fsPath, which lowercases it) agree. */

package/session.mjs

@@ -27,6 +27,8 @@ import { digestTs } from "./session-slots-manifest.mjs"
 // F2 轮转守卫自 2026-09-08 迁至 session-guard.mjs（session-slots 再越 500 行硬限拆分）
 import { guardForeignSlotFile } from "./session-guard.mjs"
 import { engTokenSlotFields } from "./token-ttl.mjs"
+// §6.17.1 链二写面（估算校准样本随会话槽走）：本档只取写出值，读面在 `session-lifecycle.mjs`（applySession）。
+import { tokenSampleOf } from "./token-window.mjs"
 // TUI-OOM-ROOTCAUSE 批（SESSION.md §6.14）：人读线记录存储（磁盘为准 + 内存窗口）。
 // slimForDisplay/isLegacyTransient 迁入 store 模块（§6.14 记录存储）——本文件 re-export 保持
 // 既有 import 面（session-slots.mjs 引 isLegacyTransient）。依赖方向单向：store 零项目内依赖。
@@ -143,6 +145,9 @@ export function saveSession(agent, opts = {}) {
     advisor: agent.config?.advisor ?? null,
     pendingReminders: agent._pendingReminders ?? [],
     sessionStart: agent._sessionStart ?? null,
+    // §6.17.1 链二写面：估算校准样本 `{key,num,den,est}`——空样本落 null（不造空对象）；
+    // 只随回合尾保存走，不新增写路径、不逐样本落盘。
+    estimateSample: tokenSampleOf(agent),
   }
   // 2026-09-05 §6.10 D-4：首认领（_slot 为 null——如 /session 切换后首保存、“查看对方活槽 →
   // 保存 fork 新槽”的落盘槽跟随）写本端记录——marker = 端内最后认领者；粘性 _slot 期间

package/skip-dirs.mjs

@@ -0,0 +1,48 @@
+/**
+ * skip-dirs.mjs — 目录排除名单**零依赖叶档**（本批 E12：四份名单合一份）。
+ *
+ * 四份并存曾是漂移源：`index-discover.mjs:28`（8 项）· `tools/shared.mjs:27`（6 项，名 `IGNORED_DIRS`）·
+ * `tools/tree.mjs:13`（13 项）· `memory/schema.mjs:48-69`（39 项 + 折叠集 + 前缀族）。同一个问题
+ * （「哪些目录不是人要读的东西」）四个答案；索引面与检索面各剪各的，同一批文件在两个面上一进一出。
+ * 单源 = 本档，四个消费面只 import 名单，不各自持有副本。
+ *
+ * **名单只此一份**：`SKIP_DIRS`（42 项）答「索引 / 遍历 / 搜索时跳过什么」——剪掉的是噪音。
+ * 面判不读任何排除名单：面只有两值（文档面放行 ∥ 其余产品面拦），「什么算产物」不参与面判定。
+ *
+ * 三条处置（理由写在项旁，防后人「顺手补回去」）：
+ * - `bin` **不列**：`thincoder-cli/bin/` 有 2 个 `.mjs` 是 CLI 入口、产品代码；列进名单会把入口
+ *   漏出索引与检索面。
+ * - `turbo` 并入 `.turbo`：`tools/tree.mjs` 旧名单里的 `turbo`（无点）是笔误，另三份都是 `.turbo`，
+ *   工作区递归查 `*turbo*` 零命中该目录。
+ * - `.thincoder` / `.vs` / `.idea` 本批补入：工具临时目录与 IDE 配置——进索引是噪音。
+ *
+ * 零依赖：本档只出常量，无 import——四处引它不成环、不加重量（`memory/schema.mjs` 引 `node:sqlite`、
+ * `conventions.mjs` 的依赖链被 `declaration.mjs` → `manifest.mjs` 拖着走，两条都不适合当单源落点）。
+ */
+
+/** 索引 / 遍历 / 搜索的剪枝全集（42 项）。精确段匹配（`memory/file-walk.mjs` 另叠折叠与前缀口径）。 */
+export const SKIP_DIRS = new Set([
+  // 产物 / 依赖（19）
+  "node_modules", ".git", "dist", "build", ".turbo", "coverage",
+  "__pycache__", ".venv", "venv", "target", ".next", ".nuxt", ".svelte-kit",
+  "vendor", "Pods", "bower_components", "third_party", "obj", "out",
+  // Windows 用户目录（14——永不含项目代码）
+  "AppData", "Application Data", "Desktop", "Documents", "Downloads",
+  "Music", "Pictures", "Videos", "OneDrive", "Contacts", "Favorites",
+  "Links", "Saved Games", "Searches",
+  // 其他非代码目录（6——Library = macOS 用户目录；go = Go workspace；三项 Windows 系统目录）
+  "Library", "go", "Program Files", "Program Files (x86)", "Windows", "$Recycle.Bin",
+  // 本批补（3——工具临时目录 / IDE 配置；见头注）
+  ".thincoder", ".vs", ".idea",
+])
+
+/** win32 大小写折叠子集（18 项——那台文件系统不区分大小写，`Node_Modules` 仍要剪）。
+ *  `.git` 不在：它由 `memory/file-walk.mjs` 的点段规则覆盖，不属本族。 */
+export const SKIP_DIRS_FOLD = new Set([
+  "node_modules", "dist", "build", ".turbo", "coverage",
+  "__pycache__", ".venv", "venv", "target", ".next", ".nuxt", ".svelte-kit",
+  "vendor", "Pods", "bower_components", "third_party", "obj", "out",
+])
+
+/** 目录名前缀族（`bazel-<workspace>` 无法枚举——workspace 名任意）。 */
+export const SKIP_DIR_PREFIXES = ["bazel-"]

package/team-ledger.mjs

@@ -26,8 +26,8 @@ const READ_ACTIONS = ["query", "count"]
 /** 六态（服务端 CHECK 同集——ledger/LEDGER.md §3）。 */
 const STATUSES = ["待讨论", "待设计", "在途", "待核销", "已核销", "已废弃"]
 
-/** 工具 cwd 供值面（缺省 → 当前项目根）。 */
-const cwdOf = (ctx) => ctx?.agent?.cwd ?? ctx?.cwd ?? process.cwd()
+/** 工具 cwd 供值面（零进程缺省：`ctx.agent.cwd` > `ctx.cwd`；两者皆无 ⇒ 当场失败，不落 `process.cwd()`）。 */
+const cwdOf = (ctx) => ctx?.agent?.cwd ?? ctx?.cwd
 
 // ── 仓标记派生（§2.2） ───────────────────────────────────────────────────────
 
@@ -174,7 +174,7 @@ const ACTION_SPECS = {
     properties: {
       id: { type: "number", description: "条目编号（全局）" },
       title: { type: "string", description: "标题（缺省 = 不变）" },
-      detail: { type: "string", description: "正文（缺省 = 不变；追认核销前须非空）" },
+      detail: { type: "string", description: "正文（缺省 = 不变）" },
       owner: { type: "string", description: "负责人（交接 = 换负责人；缺省 = 不变）" },
       status: { type: "string", enum: STATUSES, description: "目标状态（迁移表合法后继——非法由服务端 400）" },
     },
@@ -201,7 +201,7 @@ const UNION_PARAMETERS = {
     status: { type: "string", enum: STATUSES, description: "状态（query ∥ count 过滤——六态之一；update 目标态——迁移表合法后继；close ∈ {已核销, 已废弃}）" },
     owner: { type: "string", description: "负责人（query ∥ count 过滤——用户名精确匹配；add ∥ update 设值）" },
     title: { type: "string", description: "标题（add 必填 ∥ update 可改——trim 非空 ∥ ≤200）" },
-    detail: { type: "string", description: "正文（add ∥ update——可空 ∥ ≤4000；追认核销须非空）" },
+    detail: { type: "string", description: "正文（add ∥ update——可空 ∥ ≤4000）" },
     id: { type: "number", description: "条目编号（update ∥ close 必填——全局编号）" },
   },
   additionalProperties: false,

package/text-budget.mjs

@@ -51,6 +51,10 @@ export function appendCappedText(prev, add, { hard, head = 0, tail = 0, marker =
  * straddling the boundary leaves a LONE high surrogate (U+D800-DBFF) that strict UTF-16
  * decoders reject. When the cut point lands on a high surrogate, step back one code unit
  * (the pair is dropped whole).
+ *
+ * 核内唯一定义（D2）：`thincoder-core/agent/offload.mjs`（双端 preview 头切片）与
+ * `thincoder-core/agent/setup.mjs`（doc_search 预览）经 import 复用本函数——核内不再有私有复本。
+ * 入参先归一（`String(text ?? "")`）：非字符串入参归一后按同一规则切片，不抛（既有导出契约）。
  */
 export function safeSliceUTF16(text, max) {
   const t = String(text ?? "")