@thincoder/core 0.10.12 → 0.11.1

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
@@ -138,11 +139,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 = tokenRatioOf(agent) // 取比单源（同下 `historyReading` 的第三参来源）
   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,12 +156,106 @@ 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 带回，与净判同一个值）。
+ * `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 = 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 会把全部估算支缩小、重开「该压没压」原始故障，
+  // 保守方向不取（仅一侧校准，零新魔数）。
+  agent._tokRatio = Math.max(1, agent._tok.num / agent._tok.den)
+}
+
+/**
+ * 样本写出面（§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, …)` 兜底。
+ */
+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% 的单源关系」）——与 CLI 状态行（`render-frame.mjs` 式）与 VSC `ctxPercentForHistory` **同式**；
- * stats 报出的就是用户看到的那个百分比（不新增第三口径）；空历史 ⇒ 0（状态行的 `ctxPct > 0` 显示门在端侧）。
+ * 核读数（§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 historyPercent(history, provider) {
-  return Math.round((estimateTokens(history ?? []) / providerSpec(provider).context) * 100)
+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.

package/tool-docs/doc_check.md

@@ -2,12 +2,20 @@ Run a built-in documentation-discipline check on a project and report its findin
 Read-only. In the default `report` mode it is non-gating: it reports, it never blocks, never sets an exit code, and its output is never a reason to refuse a task or a user instruction.
 
 What it checks — exactly two criteria, both built into the engine:
-- Anchors — every documentation pointer (a `*.md` token, optionally carrying directory segments, optionally followed by a section
+- Anchors — a documentation pointer (a `*.md` token, optionally carrying directory segments, optionally followed by a section
   indicator `§N` / `§N.M` / `§N.M.K`) must resolve: the file must exist on disk (`档缺` when it does not), and when a section
   indicator is given the target file must carry a heading numbered with it (`节缺` when it does not). Line-number coordinates
 
   (`<doc>:12`) are not section references and are not judged as such. Files inside fenced code blocks and executable lines
   (command / pattern code spans) are skipped whole.
+- **The reach is what survives extraction, not every `.md` token.** Three name families are never extracted, so they are never
+  judged: **conventional file names** used to say which files get read (`AGENTS.md`, `SKILL.md`, `project_rules.md`, `todo.md`
+  and the rest of that closed set),
+
+  **placeholder stems** (single letters plus the usual sample words — `x.md`, `file.md`, `foo.md`, `example.md`), and — on the
+  prompt face only — the seven operand names the `Operand names` block below lists.
+
+  A `.md` token outside those families is judged even when misspelled: a wrong name reports `档缺`, never a pass.
 
 ~~~text
   **Operand names.** Seven names count as operands rather than documents: the model writes them, or reads a file by that name. On
@@ -21,15 +29,41 @@ What it checks — exactly two criteria, both built into the engine:
   ```
 ~~~
 
-- Paragraph length — on a document face, adjacent non-blank body lines merge into one paragraph whose total character
+- Citation check — the same criterion, one more hit class `引缺` (a line that claims its own basis).
+
+  A claim line writes `依据 <document path>「<verbatim quotation>」`, and the quoted text must appear as a contiguous substring
+  of the file that path resolves to; when it does not, the hit is `引缺` and the report names the path plus the first 40 characters.
+
+  The path is judged for existence first: a path that does not resolve reports `档缺`, never `引缺` — the fix differs
+  (check the path ∥ check the words). Both classes count into the one `锚` total: no third criterion, no new verdict word.
+
+  Between the path token and `「` only the optional separator (`:` ∥ `：` ∥ `=`) and an optional backtick may sit. Anything else
+  (a space, a prose word, a punctuation mark) means the line is not a basis marker and nothing is judged; an empty `「」` is not a marker either.
+
+  A path whose name falls in the exempt families above is not a marker path either — the same exemption decides both faces.
+
+  Existence only: no whitespace folding, no case or width folding. A verbatim quotation taken from the wrong place still passes —
+  whether it is the *right* basis (a contract rather than a comment) belongs to review, and this tool does not claim to judge it.
+
+
+- Paragraph length — on every non-prompt face, adjacent non-blank body lines merge into one paragraph whose total character
   count (CJK counts as 1) is judged against the built-in threshold; blank lines, table rows, headings, list items,
   quote-block lines and fenced code blocks do not count into a paragraph and break it, and lines inside an exempt zone
 
-  are excluded. Breaking a paragraph into more lines changes nothing — only splitting it into more paragraphs or
-  writing it shorter passes.
+  are excluded. No face is exempt: a tool-description file (`thincoder-core/tool-docs/**`, this file included) is judged on
+  this criterion too — a long paragraph hides its later points from every reader, the model included.
+
+  Breaking a paragraph into more lines changes nothing, and clearing the length check is not the same as fixing it: splitting a
+  paragraph into more paragraphs, or writing it shorter, clears the count while the reader still faces the same packed paragraph.
+
+  What fixes it is fewer and shorter sentences, a list of named items where the paragraph holds parallel assertions, or a table
+  where it holds enumerated readings.
 - Line length — a prompt-face file (`thincoder-core/prompts/**`) is judged line by line: the model reads raw text, so
   one line is one block, and any single line over the threshold counts with no structural exemption.
 
+`report` mode also prints one extra block: an inventory of the line-number coordinates found in the documents you pass
+(`<doc>:12` shape). That block is a reading, not a criterion — `gate` never produces it, and it cannot change a verdict or a hit count.
+
 It cannot — in `report` mode — write anything, gate anything, or turn a finding into a refusal.
 
 Arguments — `target` (optional): the project root to check; defaults to the session anchor, relative paths resolve against it.
@@ -46,10 +80,11 @@ is judged; in `gate` mode such paths are listed as skipped instead. A pointer re
 
 against the pointing document's own directory — bare names are not resolved across other directories.
 
-Delivery gate — `mode: "gate"`, for the end of a design or development round. Every listed doc is judged **whole**: a
-pre-existing dangling pointer or overlong paragraph / line anywhere in it counts, not only this round's edited lines. The first line is the
+Delivery gate — `mode: "gate"`, for the end of a design or development round. Every listed doc is judged **whole**:
+a pre-existing dangling pointer or overlong paragraph / line anywhere in it counts, not only this round's edited lines.
+
+The first line is the machine-readable verdict — `DOC-CHECK GATE: PASS` / `DOC-CHECK GATE: REFUSED（命中 K 条）` / `DOC-CHECK GATE: ERROR（reason）` —
 
-machine-readable verdict — `DOC-CHECK GATE: PASS` / `DOC-CHECK GATE: REFUSED（命中 K 条）` / `DOC-CHECK GATE: ERROR（reason）` —
 and consumers judge by that prefix; the hits are fixed in the same round and are never booked to the ledger. The gate refuses
 
 **one delivery**, not a user instruction: an explicit user go-ahead is followed, with the hits written into the delivery.
@@ -64,7 +99,7 @@ a reader: use `doc_search` / `read` to read documents and `grep` to search them;
 Side effects and permissions — none. The tool is read-only: no writes, no approval prompt, safe to run in parallel with other calls.
 
 Parameters and scope — both criteria run on built-in constants (`DOC_CHECK_BUILTINS`: threshold 300 characters, no exempt zones,
-no exemptions), and the judged set is the document list the caller passes — the judged set and the resolution set are the same
+no registration-based exemption list), and the judged set is the document list the caller passes — the judged set and the resolution set are the same
 
 documents, so there is no scan-dir / domain / root / exclude surface and no whole-repository scan. Changing a criterion or a
 threshold is a code change and goes through review; no project declaration changes these readings.

package/tool-docs/doc_search.md

@@ -1 +1,5 @@
-Search the project's documentation (README, design docs, guides, markdown files) for relevant information. Use this to find design decisions, coding conventions, architecture docs, or project rules. Prefer this over code_search when you need to understand the project's intended design rather than existing implementation. Returns matching doc chunks: path, heading, line range, relevance score, content excerpt. For what was said in sessions (conversation/chat history — decisions, rulings), use read_history.
+Search the project's documentation (README, design docs, guides, markdown files) for relevant information. Use this to find design decisions, coding conventions, architecture docs, or project rules.
+
+Prefer this over code_search when you need to understand the project's intended design rather than existing implementation. Returns matching doc chunks: path, heading, line range, relevance score, content excerpt.
+
+For what was said in sessions (conversation/chat history — decisions, rulings), use read_history.

package/tool-docs/edit.md

@@ -1,4 +1,20 @@
-Edit a file as a patch — targeted by content or by line number. Two targeting forms (mutually exclusive — use one): ① line-based: `line: N` replaces that single line, `startLine: N, endLine: M` replaces the inclusive 1-based line range — no old_string needed when you know the line number; give new_string to replace, or OMIT new_string to delete the line/range; ② content-based: old_string is the current content of the region to change (must match exactly once); new_string is the desired result of that region. old_string matching is tolerant: exact match first, then a unique whitespace-only variant, then fuzzy match (unique window with ≥90% of lines identical after trimming, tab→space indent and quote normalization — ASCII single, curly single/double and backtick quotes all unify to straight double quotes). Lines shared by old/new are kept; lines only in new_string take their position relative to the shared lines (LCS order); lines only in old_string are deleted — a replacement never leaves old lines behind (zero overlap → old lines are replaced by new_string, not kept). A unique single-line old_string paired with a single-line new_string replaces that exact line in place (line count unchanged). To add a new line without removing anything use insert_after. replace_all applies to content-based edits only: literal replacement of every occurrence — the diff rules do not apply.
+Edit a file as a patch — targeted by content or by line number.
+
+Two targeting forms (mutually exclusive — use one):
+
+① line-based: `line: N` replaces that single line, `startLine: N, endLine: M` replaces the inclusive 1-based line range — no old_string needed when you know the line number; give new_string to replace, or OMIT new_string to delete the line/range;
+
+② content-based: old_string is the current content of the region to change (must match exactly once); new_string is the desired result of that region.
+
+old_string matching is tolerant: exact match first, then a unique whitespace-only variant, then fuzzy match (unique window with ≥90% of lines identical after trimming,
+
+tab→space indent and quote normalization — ASCII single, curly single/double and backtick quotes all unify to straight double quotes).
+
+Lines shared by old/new are kept; lines only in new_string take their position relative to the shared lines (LCS order); lines only in old_string are deleted — a replacement never leaves old lines behind (zero overlap → old lines are replaced by new_string, not kept).
+
+A unique single-line old_string paired with a single-line new_string replaces that exact line in place (line count unchanged). To add a new line without removing anything use insert_after.
+
+replace_all applies to content-based edits only: literal replacement of every occurrence — the diff rules do not apply.
 
 **Routing — pick the right edit tool:**
 - Delete a line/range by number → omit new_string: edit with `line: N` / `startLine: N, endLine: M`
@@ -11,9 +27,14 @@ Edit a file as a patch — targeted by content or by line number. Two targeting
 
 **Batch multiple changes into ONE call via the `edits` array** (preferred over N single edit calls) — same file or across files; atomic: any failure writes nothing. One permission ask, one undo unit, and one turn instead of N. Per-entry shape and targeting are in the schema.
 
+Line-number entries in one `edits` array apply first, in descending `startLine` order, so each is anchored on the numbers you read; their ranges must not overlap (overlap ⇒ the whole batch is refused, nothing written). Content entries then apply in array order. The receipt stays in call order.
+
 Notes:
 - Prefer this over write for targeted edits — it's safer and keeps changes targeted
 - If old_string matches zero times (even fuzzy): error. If it matches multiple times without replace_all: error — add more surrounding context to make it unique
 - Returns `Edited <path>: replaced N occurrence(s)` (delete-mode: `Deleted line N of <path>` / `Deleted lines N-M of <path>`) + git diff + syntax-check note + context block (L..-L..).
 - Never fabricate the old_string — copy it verbatim from the actual file using read first
+- **Line-number anchoring**: `line` / `startLine`+`endLine` are judged against the last write to that file: inside or below that write's affected range, or when the file was written after it without updating that anchor, the call is refused — naming the path, the drift (`L<startLine>`, `±shift`) and two ways on (re-read, or address the region without line numbers).
 - use the most recent read of the file as the source of old_string / line numbers / hashes — re-read after the file changed
+
+**`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/execute.md

@@ -1,4 +1,6 @@
-Execute JavaScript — either inline `code` or a `scriptFile`. Runs in a real child `node` process — a pure node ESM environment: top-level `await` and dynamic `import()` are available, no globals are injected. File reads/writes/searches belong to the dedicated read/ls/glob/grep/write/edit tools — not to execute. If a script genuinely needs fs/path, `import` the `node:` module inside the code (one explicit import line).
+Execute JavaScript — either inline `code` or a `scriptFile`. Runs in a real child `node` process — a pure node ESM environment: top-level `await` and dynamic `import()` are available, no globals are injected.
+
+File reads/writes/searches belong to the dedicated read/ls/glob/grep/write/edit tools — not to execute. If a script genuinely needs fs/path, `import` the `node:` module inside the code (one explicit import line).
 
 **Route to execute instead of bash:**
 - `node -e "…"` → execute (inline code; top-level await + import() + console all work)
@@ -11,3 +13,7 @@ Notes:
 - Output is capped at ~50KB; when a script overruns it, an explicit `[output truncated]` marker is appended — print large results in chunks, or have the script write them to a file (node:fs) and read that file back with the `read` tool.
 - Use `write`/`edit`/`apply_patch` for source edits. Still use `bash` for package-manager/CLI subprocesses (`npm test`/`npm publish`/`vsce`), servers, and interactive/TTY programs — execute covers in-process JS and `node <script>`/`node --test`/`node --check`, not arbitrary CLI or long-running programs.
 - Irreversibility: it runs with full filesystem access and no automatic undo — script side effects are permanent; checkpoint (git) before risky bulk operations.
+
+**`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 scripts are judged the same way (no command-line classification).
+
+**`project`** — the project this call belongs to (absolute path of the project root). Read only when `workdir` is absent — `workdir` wins when both are given. Pure declaration: it does not change the execution directory (`workdir` does).

package/tool-docs/fetch.md

@@ -1,4 +1,6 @@
-Fetch a URL and return its content. With a DeepSeek provider configured the URL is fetched through DeepSeek's servers and returned as Markdown ([deepseek] title + content); otherwise it is fetched locally and HTML is stripped to readable text. Private/metadata URLs are never sent. Use after websearch to read full documents.
+Fetch a URL and return its content. With a DeepSeek provider configured the URL is fetched through DeepSeek's servers and returned as Markdown ([deepseek] title + content); otherwise it is fetched locally and HTML is stripped to readable text.
+
+Private/metadata URLs are never sent. Use after websearch to read full documents.
 
 Parameters:
 - url (required): http/https URL

package/tool-docs/file_ops.md

@@ -14,4 +14,6 @@ Notes:
 - Paths resolve relative to cwd — no directory restriction (same boundary as bash; the approval gate is the guard).
 - `dest` is overwritten if it already exists. `copy` is recursive for directories.
 - To create a directory, use `write` (creates parent dirs) or `bash mkdir`.
-- Returns `Moved|Copied|Renamed <source> -> <dest>` or `Error: ...` (same-path and missing-path errors).
+- Returns `Moved|Copied|Renamed <source> -> <dest>` or `Error: ...` (same-path and missing-path errors).
+
+**`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/git.md

@@ -1,6 +1,8 @@
 Run a git command. Only works inside a git repository.
 
-**Route to git instead of bash** — every sub-command maps to the same-named action: status / log / diff / show / add / rm / commit / push / tag / branch / checkout / restore / stash / fetch / pull / reset / revert / merge / cherry-pick / ls-remote / clone / init / rebase / remote / clean / switch / apply / worktree / archive / blame / mv.
+**Route to git instead of bash** — every sub-command maps to the same-named action:
+
+status / log / diff / show / add / rm / commit / push / tag / branch / checkout / restore / stash / fetch / pull / reset / revert / merge / cherry-pick / ls-remote / clone / init / rebase / remote / clean / switch / apply / worktree / archive / blame / mv.
 
 - diff: unified diff since last commit (`staged` — staged only; `ref` — compare a commit/branch; `path` — scope).
 - status: working tree state — staged / unstaged / untracked / conflicts.
@@ -26,3 +28,9 @@ Run a git command. Only works inside a git repository.
 - Destructive ops (checkout -- path / restore / reset --hard / stash pop / branch|tag delete / clean / rebase) auto-snapshot first; restore a snapshot via `checkpointAction=rewind`.
 - Failures come back as errors — `git <action> failed: <reason>` — nothing is silently swallowed.
 - `filter` narrows any read-only action's output (case-insensitive regex); `config` (git -c overrides, e.g. a proxy) applies to the network actions (push / fetch / pull / ls-remote / clone). Other parameter defaults and applicability live in the schema.
+
+**`ledger`** — the in-flight ledger row this call serves: `"#N"` or `"N"`. In engineering mode the parent agent must pass it for a write action; omitted = refused.
+
+**`project`** — the project this call belongs to (absolute path of the project root). Read only when neither `path` nor `workdir` is given — those win when present. Pure declaration: it does not change where git runs (`workdir` does).
+
+Read-only actions do not need it: `diff` / `status` / `log` / `show` / `ls-remote` / `blame`, and each `*Action: "list"` (`checkpoint` `list` / `cat` included).

package/tool-docs/goal.md

@@ -1,6 +1,8 @@
 Manage a long-running autonomous goal.
 action='set': create or replace the goal — must have a verifiable completion criterion (a machine-checkable proof, not vague effort).
+
 action='complete': mark achieved — only after the criterion's check has actually passed.
 action='blocked': report an impasse (requires 'reason') — only after 3 genuine attempts.
 action='cancel': abandon the goal.
+
 Returns a status line — the goal set/updated/completed/blocked/cancelled confirmation, or Error: ... with the reason.

package/tool-docs/grep.md

@@ -1,4 +1,4 @@
-Search file contents with a regex. Returns matching lines as path:line: content.
+Search file contents with a regex. Returns matching lines, each preceded by its file path and line number.
 
 **Route to grep instead of bash:** `findstr /c:"pat" file` / `grep -rn pat .` → grep. Searching file contents is a read — never shell out for it.
 

package/tool-docs/hashline_edit.md

@@ -12,3 +12,5 @@ Notes:
 - Prefer this over edit when: 1) the file may have mixed whitespace/encoding, 2) you want to edit a block of lines with a single call
 - Replacement text replaces the lines identified by the hashes — content not present in new_content is deleted. For a new line after a known line, use insert_after. For a single simple string swap, use edit.
 - use the most recent read of the file as the source of old_string / line numbers / hashes — re-read after the file changed
+
+**`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/insert_after.md

@@ -11,5 +11,7 @@ Notes:
 - Use this instead of edit when you're adding a new line — a checklist item, a doc heading, a line of prose, a function, an import, or a block — no need to fabricate surrounding context for exact matching.
 - The inserted content becomes its own line; it's equivalent to `lines.splice(targetLine, 0, content)`.
 - Returns a diff of the change.
-- **Read-before-insert guard**: if the file was modified by any write tool (write/edit/insert_after/hashline_edit/apply_patch/delete) since your last `read`, this tool REFUSES with an error — line numbers may be stale. Read the file again, then retry. This prevents after_line from silently landing at a drifted position.
+- **Read-before-insert guard**: `after_line` is judged against the last write to that file — a line at or above that write's write point is allowed; inside or below it, or when the file was written after it without updating that anchor, the call is refused with the path, the drift and two ways on (re-read, or address the region without line numbers).
 - use the most recent read of the file as the source of old_string / line numbers / hashes — re-read after the file changed
+
+**`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.