@thincoder/core 0.10.13 → 0.11.1

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 }
 }
 
@@ -401,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 } = {}) {
@@ -417,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 ?? "")

package/token-window.mjs

@@ -4,11 +4,12 @@
  * 迁出三族（语义零改——原档越限在即，本批按 §6.16.8 拆出）：① 计量面（IMAGE_TOKEN_ESTIMATE + `estimateTokens`）；
  * ② 尾族（KEEP_HEAD 头注 + TAIL_BUDGET_FRACTION / SUMMARY_TOKEN_ESTIMATE / TAIL_FLOOR_MESSAGES + `keepTailSize` + `tailBudgetTokens`）；
  * ③ 切分与配对修复族（`splitHistory` + `repairedTailStart` + `tightenTailByBudget`）。
- * 新增族：`contextUsage`（与 `compressIfNeeded` 的 token 判定**同一函数**）· `historyPercent`（与两端状态行**同式**）·
+ * 新增族：`contextUsage`（与 `compressIfNeeded` 的 token 判定**同一函数**）· `historyReading` / `historyPercent`（状态行
+ * 百分比——与 CLI ∥ VSC **同源**：一个实现点，端侧零自算式，消费面全是本档的投影）·
  * `collectStaleToolOutputs`（陈旧工具输出合格集）+ 门槛常量 `PRUNE_MIN_TOKENS`（**与合格集同住本档** ⇒ 消费方单向取用、零回指）。
- * 依赖面 = `provider/rate.mjs`（`estimateText`）+ `config.mjs`（`providerSpec` / `resolveCompactThreshold`）——**零 import 环**。
+ * 依赖面 = `provider/rate.mjs`（`estimateText` / `ESTIMATOR_VERSION`）+ `config.mjs`（`providerSpec` / `resolveCompactThreshold`）——**零 import 环**。
  */
-import { estimateText } from "./provider/rate.mjs"
+import { estimateText, ESTIMATOR_VERSION } from "./provider/rate.mjs"
 import { providerSpec, resolveCompactThreshold } from "./config.mjs"
 
 const IMAGE_TOKEN_ESTIMATE = 2000 // rough estimate for image content tokens (CLI legacy 256 underestimated real image costs, delaying compaction)
@@ -40,7 +41,7 @@ const KEEP_HEAD = 0 // No dedicated head: earliest messages may be a COMPLETED e
 // × window − SUMMARY_TOKEN_ESTIMATE ≈1K, §6.9) tightens it over pair-safe boundaries when compaction runs,
 // never below TAIL_FLOOR_MESSAGES; ordinary sessions never reach it (D-T4: the trigger ratio lives in `config.mjs` — untouched here).
 const TAIL_BUDGET_FRACTION = 0.15
-const SUMMARY_TOKEN_ESTIMATE = 1000 // §6.9: summary output target ~1K tokens — reserved from the 15%
+export const SUMMARY_TOKEN_ESTIMATE = 1000 // §6.9: summary output target ~1K tokens — reserved from the 15%；§6.17 可达性门的 `note` 项同取本常量
 const TAIL_FLOOR_MESSAGES = 10 // §6.4④ D-T2: the tail keeps ≥10 verbatim messages — floor beats budget
 export function keepTailSize(provider, historyLen) {
   // provider is guaranteed at every call site (runAgent always builds one); providerSpec
@@ -139,7 +140,7 @@ export function contextUsage(agent, extras = {}) {
   const historyTokens = estimateTokens(history)
   const measured = agent?._lastPromptTokens != null
   // §6.3 / §6.17 估算自校准：估算值乘 `_tokRatio`；`_lastPromptTokens` 是服务端真值，不乘。
-  const ratio = agent?._tokRatio ?? 1
+  const ratio = tokenRatioOf(agent) // 取比单源（同下 `historyReading` 的第三参来源）
   return {
     basis: measured ? "measured" : "estimated",
     total: measured
@@ -155,18 +156,25 @@ export function contextUsage(agent, extras = {}) {
   }
 }
 
+/** 估算样本键（§6.17.1 链二校验③单源）：`format:model`——采样面与恢复面同一判据（切模型自清）。 */
+export function tokenKey(provider) {
+  return `${provider?.format ?? "openai"}:${provider?.model ?? ""}`
+}
+
 /**
  * 估算自校准采样（§6.17「估算自校准」）——池化比：`num += usage.prompt_tokens`、`den += estPrompt`
  * （分子分母同取输入侧口径；`estPrompt` 由发送面随 result 带回，与净判同一个值）。
- * `key = format:model` 变 ⇒ 归零重采（切模型自清，不接四个刷新点）；`_tok` / `_tokRatio` 只由本函数写，
- * `/new` 与 run 装配复位。无样本 ⇒ 比 = 1（估算维持原口径）。
- * 作用面 = `contextUsage` 两支承（§6.3）；实测基线 `_lastPromptTokens` 不乘。
+ * `tokenKey()` 变 ⇒ 归零重采（切模型自清，不接四个刷新点）；`_tok` / `_tokRatio` 的**采样侧**只由本函数写
+ * （恢复侧 = `restoreTokenSample`，清空 = `/new`——`session-lifecycle.mjs`）；run 装配**不复位**
+ * （池化比要跨消息累计，见 `agent/setup.mjs`）。
+ * 无样本 ⇒ 比 = 1（估算维持原口径）。作用面 = `contextUsage` 两支承（§6.3）；实测基线 `_lastPromptTokens` 不乘。
+ * 落槽形见 §6.17.1 链二：`est` = 估算口径版本位，跨进程恢复时与本值不符的样本不复用。
  */
 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 }
+  const key = tokenKey(provider)
+  if (agent._tok?.key !== key) agent._tok = { key, num: 0, den: 0, est: ESTIMATOR_VERSION }
   agent._tok.num += prompt
   agent._tok.den += estPrompt
   // 下界 = 1：已知偏差方向是估算偏低；比 < 1 会把全部估算支缩小、重开「该压没压」原始故障，
@@ -175,11 +183,79 @@ export function recordTokenSample(agent, provider, estPrompt, usage) {
 }
 
 /**
- * 状态行百分比（§6.16.4「与状态行 ctx% 的单源关系」）——与 CLI 状态行（`render-frame.mjs` 式）与 VSC `ctxPercentForHistory` **同式**；
- * stats 报出的就是用户看到的那个百分比（不新增第三口径）；空历史 ⇒ 0（状态行的 `ctxPct > 0` 显示门在端侧）。
+ * 样本写出面（§6.17.1 链二写面）：会话槽 `estimateSample` 的值——`agent._tok` 为空 ⇒ `null`
+ * （落 null，不造空对象）；`est` 缺省补当前口径版本（老进程内的样本对象无该位）。
+ */
+export function tokenSampleOf(agent) {
+  const tok = agent?._tok
+  if (!tok || typeof tok.key !== "string") return null
+  return { key: tok.key, num: tok.num, den: tok.den, est: tok.est ?? ESTIMATOR_VERSION }
+}
+
+/**
+ * 样本读回面（§6.17.1 链二）：槽里是盘上用户数据 ⇒ 判定走 `validSample`（同一份校验，不在此复述），
+ * 不过则回到未校准档（`_tok = null` / `_tokRatio = 1`，不抛——坏样本不得拦住会话恢复）。
+ * 返回是否复用了样本。
+ */
+export function restoreTokenSample(agent, sample, provider) {
+  const ok = validSample(sample, provider)
+  agent._tok = ok
+  agent._tokRatio = ok ? Math.max(1, ok.num / ok.den) : 1
+  return ok !== null
+}
+
+/**
+ * 样本判定（§6.17.1 链二四条校验——**唯一实现面**）：形状与数值域（`num` / `den` / `est` 有限、`den > 0`）·
+ * 口径版本（`est === ESTIMATOR_VERSION`——口径变了，旧样本的 `den` 与新估算不同量纲）· 键匹配
+ * （`key === tokenKey(provider)`——恢复后模型已换 ⇒ 不复用）。全过 ⇒ `{ key, num, den, est }`；任一不过 ⇒ `null`
+ * （回到未校准档，不抛——坏样本不得拦住会话恢复 / 读数）。恢复面 `restoreTokenSample` 与读数面 `sampleRatio`
+ * 同取本函数：同一判定，不写第二份。④ 比 < 1 不必单独判——由 `max(1, …)` 兜底。
  */
-export function historyPercent(history, provider) {
-  return Math.round((estimateTokens(history ?? []) / providerSpec(provider).context) * 100)
+function validSample(sample, provider) {
+  if (!sample || typeof sample !== "object" || Array.isArray(sample)) return null
+  const { key, num, den, est } = sample
+  if (typeof key !== "string" || !Number.isFinite(num) || !Number.isFinite(den) || !Number.isFinite(est) || !(den > 0)) return null
+  if (est !== ESTIMATOR_VERSION) return null
+  if (key !== tokenKey(provider)) return null
+  return { key, num, den, est }
+}
+
+/**
+ * 核读数（§6.16.4「与状态行 ctx% 的单源关系」）——这个量**只有本函数一个实现点**，五处消费面全是它的投影：
+ * stats 第 6 行 · 打开态读数 · 桌面 `ev:usage` · VSC `specs.mjs` · CLI 状态行（经 `ctxCacheOf` 缓存）。
+ * 一点出两值：`tokens` = 校准后的历史估算 `round(estimateTokens(history) × ratio)`、`pct` = 它 ÷ 窗口、
+ * `window` = `providerSpec(provider).context`——同屏「context X% Yk」必须同尺，两值各自算一次就是两把尺；
+ * `window` 随读带出，消费面不再二次派生同一个量。
+ * `ratio` **无缺省**：忘传 ⇒ `estimateTokens × undefined` = `NaN` ⇒ `tokens` / `pct` 皆 `NaN`。三面显示门
+ * 都把非正值读作「不显示」（CLI `ctxPct > 0` · VSC 分子为假回 `null` · 桌面 `usageFrameWanted` 不发帧）
+ * ⇒ 读数**缺席**（不会是错数）；给缺省 1 则相反——忘传处静默显示未校准读数，看着完全正常而差一整个校准比。
+ * 两种形状里只有后者会被当作事实读走，所以宁可缺席。
+ * 空历史 ⇒ 0（状态行的 `ctxPct > 0` 显示门在端侧，不入本函数面）。
+ */
+export function historyReading(history, provider, ratio) {
+  const window = providerSpec(provider).context
+  const tokens = Math.round(estimateTokens(history ?? []) * ratio)
+  return { tokens, pct: Math.round((tokens / window) * 100), window }
+}
+
+/** 状态行百分比薄转口（名面与 export 不变）：`historyReading` 的 `pct`——与 stats ∥ CLI ∥ VSC **同源**
+ * （各处全是这一实现点的投影，端侧零自算式）。第三参 `ratio` 同 `historyReading`：无缺省。 */
+export function historyPercent(history, provider, ratio) {
+  return historyReading(history, provider, ratio).pct
+}
+
+/** 估算校准比（§6.17）——`agent._tokRatio` 的**唯一**读出点（中性值 1 的唯一出处）：
+ * 无样本 ⇒ 1。合法的 1 只有两种：新会话无样本（`_tok` 为 `null`）· 打开态槽无 `estimateSample`；
+ * agent 不在场（`undefined` / `null`）也回 1，该档 = 未校准读数，由消费面显式断言，不靠默认值蒙过。 */
+export function tokenRatioOf(agent) {
+  return agent?._tokRatio ?? 1
+}
+
+/** 槽样本 ⇒ 校准比（§6.17.1 链二读数面）：判定与 `restoreTokenSample`（恢复面）同一份 `validSample`，
+ * 好样本 ⇒ `max(1, num / den)`，坏样本 ⇒ `1`（下界 1 与 `recordTokenSample` 同——偏差方向已知是估算偏低）。 */
+export function sampleRatio(sample, provider) {
+  const s = validSample(sample, provider)
+  return s ? Math.max(1, s.num / s.den) : 1
 }
 
 /** 陈旧工具输出门槛（§6.16.3 判据③）：低于门槛的替换是净增 token（stub 本身有长度）——常量与合格集同住本档。 */

package/tool-docs/advisor.md

@@ -1,9 +1,9 @@
 Run an independent review of your work. `type` is REQUIRED — one of exactly two values, no default and no silent fallback.
 
-- `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="design"` — design review: reviews design / requirement documents BEFORE implementation. Pass `documents=[...]` and `batchDoc` — the batch record this review belongs to. **`batchDoc` is required**: a design review without it is refused before launch, because the token it would mint has no batch to close it.
 - `type="code"` — code review: reviews the code you changed AFTER implementation. Pass `paths=[...]` to scope files/directories; `documents=[...]` adds acceptance-criteria context.
 
-`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.
+`documents` — one rule: a relative path resolves against the session project root (e.g. `docs/<area>/<name>.md`); an absolute path is used as-is.
 
 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.
 

package/tool-docs/apply_patch.md

@@ -13,3 +13,5 @@ Notes:
 - If a hunk's context matches multiple locations it is rejected — add more surrounding context lines
 - Deleting files is not supported — use the delete tool
 - For single-file edits, edit is simpler; for full rewrites, write is simpler
+
+**`ledger`** — the in-flight ledger row this call serves: `"#N"` or `"N"`. In engineering mode the parent agent must pass it — a call that does not say which row it serves is refused.

package/tool-docs/bash.md

@@ -37,3 +37,7 @@ Notes:
 - After commands that change files (git checkout, npm install, etc.), repo_outline and code_search may be stale — re-run them to get current results.
 - Prefer read/glob/grep/ls for file operations inside the project — file tools and bash reach the same paths (no directory restriction).
 - NEVER use bash to write or modify files (echo/sed/printf > file, cat << EOF, etc.). Use write/edit/insert_after/apply_patch instead — they handle encoding, escaping, and EOL conventions correctly.
+
+**`ledger`** — the in-flight ledger row this call serves: `"#N"` or `"N"`. In engineering mode the parent agent must pass it — a call that does not say which row it serves is refused, and read-only commands are judged the same way (no command-line classification).
+
+**`project`** — the project this call belongs to: the absolute path of the project root (the directory carrying PROJECT-MANIFEST.json). Engineering mode: pass it together with `ledger`. Pure declaration: it does not change the execution directory.

package/tool-docs/batch.md

@@ -1 +1,85 @@
-Batch-record lifecycle tool (一段一作者 — six append-only sections, one author each). actions: create (depth-0 only — write a new six-section skeleton record; pass path + topic + source, plus optional ledger / board that fill the record's 台账 header line at creation) · append (add text to the END of YOUR section — existing lines are never rewritten or deleted) · status (update YOUR section's `**状态行**：` line — the value must carry exactly ONE legal keyword of your section's STATUS_WORDS entry, decorated only by surrounding symbols / a trailing ISO date / whitespace; prose goes to the separate `note` field, which lands as a parenthetical). Writing §1 已收口 closes the record and runs the closeout-chain gate: §2 / §3 / §4 / §6 must each carry content, or §1 declares it inapplicable with `> 不适用：§N —— <reason>` (§2 / §3 / §4 only; §5 is exempt; §6 never). Reopening a frozen record = §1 → 进行中 with `note` = the reason: the tool rewrites the §1 status line and appends a 「重开记录」 line — no other existing line is touched. · close (depth-0 only — freeze the record: §1 → 「已收口 <date>」, every further write is refused except the reopen conjunction; runs the same closeout-chain gate as status — an incomplete chain is refused, naming the missing sections). Closing a record — the close action, or status writing §1 已收口 — also writes the ledger: this record's unsettled rows (task_book → this record, status 待讨论 / 待设计 / 在途, trigger ≠ 认账不排期 — a policy call leaves its row untouched, and a row already 条件 is skipped with zero writes) get trigger → 条件, with the resume sentence 「原批 <record> 已收口，须另起批次接手」 landing in resume_when (a non-empty resume_when keeps its value — the sentence is appended to evidence instead); each changed / skipped row is named in a `[ledger reanchor]` receipt block (a ledger write failure — busy store / no derivable project root — is named there too and never blocks the freeze). Identity fixes what you may write (段白名单): main agent (depth 0) — create/close; append/status domains are mode-dependent: engineering — append §1/§4/§6, status §1; normal — append §1/§2/§4/§5/§6, status §1/§2/§5 (the main agent holds the designer seat and records direct implementation); eng-designer — §2; eng-coder — §5; a normal-mode coder bound via batchDoc — §5; design review (review binding) — §3. A write outside your own section is refused. Skeleton placeholders (dead literals — `#<编号>` / `<板块>` and the older `<BATCH-ID>` / `<讨论来源>`) in the record header's structural lines block append/status until filled: create with ledger / board fills them at creation; if omitted, the main agent fills the header by file edit right after create (citing these literals in a section's prose is fine — only the header is checked); `<§N 模板占位：…>` template lines are legal and never blocked. Target record: sub-agents and design reviews have NO path parameter in practice — the record arrives via the spawn binding / the review instance key (passing path is refused); depth-0 MAY pass path (若传则须可读), omitting it picks the unique in-flight record (0 or ≥2 in flight ⇒ refuse — pass path). A design review's append is stamped by the tool with a `### 轮次 N（评审子代理）` heading — N is tool-counted; do not write your own heading (it would be dropped). Credential values are stripped mechanically before writing (never write a token or designId value). Document-check gate: appending §2 / §5 as a sub-agent and closing a record (or setting §1 to 已收口) run the doc-check gate before the write — REFUSED ⇒ the write is refused and the record's bytes stay unchanged (do not close a record after a refused append); ERROR ⇒ a closeout is refused while an append still lands with an ERROR receipt line; no PROJECT-MANIFEST.json ⇒ the gate does not run and the receipt says so. Failures are hard and visible (no silent fallback): if a write is refused or fails, say so in your report — “§× 未写入”.
+Batch-record lifecycle tool (一段一作者 — six sections, one author each; the author has two actions on that one section: append adds text at its end, edit rewrites its lines in place; the section's status line has a single writer, `status`).
+
+actions: create (depth-0 only — write a new six-section skeleton record; pass path + topic + source, plus optional ledger / board that fill the record's 台账 header line at creation;
+
+ledger:"#N" takes over an existing row, and omitting ledger opens a new row only when no unsettled row exists on the same board — otherwise create is refused with the candidate list and you pass newDebt:"<why this is a new debt>" or ledger:"#<id>")
+
+· append (add text to the END of YOUR section — the lines already there are left byte-for-byte as they stand)
+
+A §3 append must carry exactly one verdict on its own line — `VERDICT: pass` or `VERDICT: changes-required`; the localized whole-line forms count too (`结论：通过` / `结论：不通过`, and their 需修改 variants), and the Chinese forms take an optional trailing 。.
+
+A §3 write that reads as no verdict line, or as both lines at once, is refused with nothing written — no round number is consumed, so resend the same text with the verdict line added.
+
+
+· edit — replace one anchored range inside YOUR OWN section (any section you may append to; your identity decides which)
+
+oldText must match exactly once, byte for byte (line endings included), inside the section body; newText replaces that range, and an empty newText deletes it.
+
+Refused with nothing written: a blank oldText, zero hits, two or more hits (the matching lines are named), an anchor crossing the section boundary, and any anchor or replacement that touches or introduces a `**状态行**：` line (the status line has one writer: `status`).
+
+On §3 an incoming `### 轮次 N（评审子代理）` line is dropped from newText — the round stamp is tool-generated only.
+
+Two gates hang on `append` alone and do not apply to `edit`: the §5 ordering gate (an edit needs an existing anchor, so it cannot write what does not exist yet) and the §3 verdict line (that gate reads the block you append; rewriting words inside an existing block changes no machine criterion).
+
+
+· status (update YOUR section's `**状态行**：` line — the value must carry exactly ONE legal keyword of your section's STATUS_WORDS entry, decorated only by surrounding symbols / a trailing ISO date / whitespace).
+
+Prose goes to the separate `note` field, which lands as a parenthetical.
+
+A §3 pass round sets that section's status line in the same write — `status` on §3 is an optional rewrite, never a required step.
+
+Writing §1 已收口 closes the record and runs the closeout-chain gate: every section must carry content (§5 exempt) — the `不适用` declaration is retired, so any `> 不适用：§N` line in §1 is refused outright.
+
+Reopening a frozen record = §1 → 进行中 with `note` = the reason: the tool rewrites the §1 status line and appends a 「重开记录」 line — no other existing line is touched.
+
+· close (depth-0 only — freeze the record: §1 → 「已收口 <date>」, every further write is refused except the reopen conjunction; runs the same closeout-chain gate as status — an incomplete chain is refused, naming the missing sections).
+
+Closing a record — the close action, or status writing §1 已收口 — also writes the ledger: this record's unsettled rows (task_book → this record, status 待讨论 / 待设计 / 在途, trigger ≠ 认账不排期 — a policy call leaves its row untouched, and a row already 条件 is skipped with zero writes) get trigger → 条件,
+
+with the resume sentence 「原批 <record> 已收口，须另起批次接手」 landing in resume_when (a non-empty resume_when keeps its value — the sentence is appended to evidence instead);
+
+each changed / skipped row is named in a `[ledger reanchor]` receipt block (a ledger write failure — busy store / no derivable project root — is named there too and never blocks the freeze).
+
+Identity fixes what you may write (段白名单): main agent (depth 0) — create/close;
+
+append/status domains are mode-dependent: engineering — append §1/§4/§6, status §1; normal — append §1/§2/§4/§5/§6, status §1/§2/§5 (the main agent holds the designer seat and records direct implementation);
+
+edit reads the same whitelist as append — one table, two actions: the section you may append to is the section you may rewrite in place. Depth-0 gains §2 and §5 on edit in normal mode for the reason it gains them on append (the main agent holds the designer and implementer seats).
+
+eng-designer — §2; eng-coder — §5; a normal-mode coder bound via batchDoc — §5; design review (review binding) — §3.
+
+A write outside your own section is refused.
+
+Skeleton placeholders (dead literals — `#<编号>` / `<板块>` and the older `<BATCH-ID>` / `<讨论来源>`) in the record header's structural lines block append/status until filled:
+
+create with ledger / board fills them at creation; if omitted, the main agent fills the header by file edit right after create (citing these literals in a section's prose is fine — only the header is checked);
+
+`<§N 模板占位：…>` template lines are legal and never blocked.
+
+Target record: sub-agents and design reviews have NO path parameter in practice — the record arrives via the spawn binding / the review instance key (passing path is refused); depth-0 MAY pass path (若传则须可读), omitting it picks the unique in-flight record (0 or ≥2 in flight ⇒ refuse — pass path).
+
+A design review's append is stamped by the tool with a `### 轮次 N（评审子代理）` heading — N is tool-counted; do not write your own heading (it would be dropped).
+
+Credential values are stripped mechanically before writing (never write a token or designId value).
+
+Document-check gate: every append and every edit runs it before the write — any section (§1–§6), depth-0 and sub-agent and design review alike — and so does closing a record (or setting §1 to 已收口).
+
+On `edit` the judged set splits by hit class: paragraph / line length is judged on the newText you pass; the anchor classes (档缺 / 节缺 / 引缺) are judged on the whole record as it will stand after your edit.
+
+A dead citation anywhere in the record therefore refuses an unrelated edit — and replacing that very line is the way through, which is why the record is judged as it will stand, not as it sits.
+
+On append it judges three things: the text you are appending now, the markdown files already touched in this run, and the record itself — but only the first two can refuse the write.
+
+A hit in the text you are appending or in a touched file ⇒ REFUSED: nothing lands, the record's bytes stay unchanged (do not close a record after a refused append).
+
+A hit in a section that has already landed is named in the receipt with its section number and author and never blocks the write — another author's landed lines cannot be rewritten here; the close face is where it is enforced.
+
+On close (and on status writing §1 已收口) every hit in the range refuses, each one named as `§N（作者：…）` when it sits inside the record.
+
+An append receipt reads `[doc-check gate] DOC-CHECK GATE: PASS · 范围 N 档` — N = the documents actually judged, the record itself always one of them.
+
+ERROR ⇒ a closeout is refused while an append still lands with an ERROR receipt line;
+
+no PROJECT-MANIFEST.json ⇒ the gate does not run and the receipt says so.
+
+Failures are hard and visible (no silent fallback): if a write is refused or fails, say so in your report — “§× 未写入”.

package/tool-docs/browser.md

@@ -1,4 +1,6 @@
-Drive a real browser the tool starts itself: a headless (default) or visible system Edge/Chrome in an isolated profile under `~/.thincoder/browser/profile`. Multi-step and stateful: `navigate`, `snapshot`, then act on the element references the snapshot returns. Not a takeover — it never attaches to a browser you already have open and needs no extension.
+Drive a real browser the tool starts itself: a headless (default) or visible system Edge/Chrome in an isolated profile under `~/.thincoder/browser/profile`.
+
+Multi-step and stateful: `navigate`, `snapshot`, then act on the element references the snapshot returns. Not a takeover — it never attaches to a browser you already have open and needs no extension.
 
 **Route to browser instead of fetch:**
 - content that only exists after JS runs, or behind interaction (login, click, form, scroll) → browser

package/tool-docs/code_search.md

@@ -1 +1,3 @@
-Search the project's source code for relevant code. Use this to find functions, classes, or code patterns across the codebase. Returns matching code chunks with file paths and line numbers. Prefer doc_search for the intended design (design docs, conventions); code_search for the implementation as written. For what was said in a session (conversation/chat history), use read_history.
+Search the project's source code for relevant code. Use this to find functions, classes, or code patterns across the codebase. Returns matching code chunks with file paths and line numbers.
+
+Prefer doc_search for the intended design (design docs, conventions); code_search for the implementation as written. For what was said in a session (conversation/chat history), use read_history.

package/tool-docs/consult_start.md

@@ -1,5 +1,9 @@
 Start a parallel multi-model consultation (会诊) for a hard problem you are stuck on (repeated failures, no headway). Call it directly when the user asks for 会诊 / consult — an explicit user request applies even if you are not 'stuck'.
 
-Several configured models (agent.consultModels — at most 5; an unconfigured pool is an explicit error) analyze the same problem INDEPENDENTLY and in parallel. Non-blocking: returns immediately with a consult id; the consultants keep running in the background across turns. When EVERY model has replied (or failed), the full verdict text is delivered to you automatically — as a system reminder at the next run start, or digested on its own while the session is idle — judge and adopt each opinion yourself with your own tools (opinions are suggestions, not gates). To stop a session early (user changed their mind / wants the tokens back), call consult_stop(id) — a stopped session delivers no digest.
+Several configured models (agent.consultModels — at most 5; an unconfigured pool is an explicit error) analyze the same problem INDEPENDENTLY and in parallel. Non-blocking: returns immediately with a consult id; the consultants keep running in the background across turns.
 
-The brief should carry the symptom, what you already tried (the failure trail), and entry-point files; do NOT paste raw error logs — consultants pull the main session history themselves via their main_history tool.
+When EVERY model has replied (or failed), the full verdict text is delivered to you automatically — as a system reminder at the next run start, or digested on its own while the session is idle — judge and adopt each opinion yourself with your own tools (opinions are suggestions, not gates).
+
+To stop a session early (user changed their mind / wants the tokens back), call consult_stop(id) — a stopped session delivers no digest.
+
+The brief should carry the symptom, what you already tried (the failure trail), and entry-point files; do NOT paste raw error logs — consultants pull the main session history themselves via their main_history tool.

package/tool-docs/consult_stop.md

@@ -1,3 +1,5 @@
-Cancel a still-running consultation session (会诊) — the user changed their mind, the problem resolved, or you want the tokens back. Aborts every consultant that is still running; a stopped session delivers NO digest (its already-collected partial replies are dropped). Sessions that finished on their own are no longer cancellable — their verdict text is delivered automatically.
+Cancel a still-running consultation session (会诊) — the user changed their mind, the problem resolved, or you want the tokens back. Aborts every consultant that is still running; a stopped session delivers NO digest (its already-collected partial replies are dropped).
+
+Sessions that finished on their own are no longer cancellable — their verdict text is delivered automatically.
 
 Returns JSON {abandoned: <pending count>, cancelled: true} — or {error: "unknown consult id"} (already finished/cancelled).

package/tool-docs/delete.md

@@ -1,4 +1,5 @@
 Delete a file, or an empty directory. Use when the agent created a temporary or junk file or empty directory that should be cleaned up, or when the user explicitly asks to delete something.
+
 Refuses to delete git-tracked files as a safety measure — tracked files should be edited or removed via bash with explicit user confirmation.
 
 **Route to delete instead of bash:** `del file` / `rm file` → delete (single files); an empty directory → delete (empty directories only). Non-empty directories have no delete path — stop and report to the user instead of hand-rolling a recursive shell delete.
@@ -13,3 +14,5 @@ Notes:
 - Directories: empty ones only — a non-empty directory is refused (a natural fuse; nothing recursive is ever removed); delete nested empty trees bottom-up
 - Symbolic links are removed as links — the link itself is deleted, never followed (its target is untouched)
 - Returns `Deleted <path>` (or `Error: ...` on failure / tracked / non-empty refusal).
+
+**`ledger`** — the in-flight ledger row this call serves: `"#N"` or `"N"`. In engineering mode the parent agent must pass it — a call that does not say which row it serves is refused.