@thincoder/core 0.10.10 → 0.10.12

package/tool-docs/subagent.md

@@ -1,36 +1,61 @@
 ONE tool, NINE actions — pick by what you need:
 
 - action:'spawn' (DEFAULT): run a sub-agent in its own isolated context — its reads, searches and tool calls never reach your history; only the final report comes back. Spawn MULTIPLE subagents in the SAME response for parallel work — they run concurrently.
-- action:'status': NON-BLOCKING progress query — returns immediately, consumes nothing, never fetches. Pass the spawn id for one child (role, state: running|queued|done, model, elapsed, turn, position, plus a touched-files summary — first 5 + a count) or omit it for a pool overview — see what a running child has changed BEFORE cancelling it. Background advisor reviews share this surface (pass the review id — role:'advisor', reviewType/round/elapsedSec, same shape).
-- action:'observe': SEE what a running async subagent is DOING right now (progress vs stuck) — pass the id; returns state, turn, the tool(s) executing right now (omitted when none), and the last N one-line turn summaries, newest first (default 5, via recent). Readonly; running/queued/done all answer — queued returns a placeholder, done gives the activity summary only, NOT the report (it rides the auto channel). Judge stuck vs progressing BEFORE cancelling or steering.
-- action:'send': STEER a running async subagent mid-flight — id + message (a direction, e.g. "check X, don't fixate on Y"). The child consumes it at its next turn boundary as an ORDINARY user instruction (non-interrupting; its discipline is unchanged — guidance, not a deviation waiver); returns {id, status:'delivered', queued}. Only RUNNING async children are targetable — sync/queued/settled/unknown error clearly; if the child settles first, its report carries an 'undelivered' note.
-- action:'escalate' (飞刀): hand an implementation task to a STRONGER model from your consult models; it gets WRITE access and does the work itself, then returns a post-op report (what changed, why, verification). Escalate EARLY, when the task calls for stronger hands (complex refactors, intractable bugs, intricate algorithms — or beyond your comfortable ability). Not available in engineering mode (implementation goes through eng-coder). Default-async at depth 0: ack {id, role:'escalate', status:'running'} returns immediately; the report arrives automatically with its mutations merged into your bookkeeping (pooled with the other role-domain spawns).
-- action:'cancel': STOP ONE background subagent — the id from the spawn return is REQUIRED (a blanket cancel is unsupported; Ctrl+C stops everything). Running aborts immediately ({id, status:'cancelled'}); queued is removed ({id, status:'cancelled', was:'queued'}; later positions shift). Other children and the session keep running. Cancel is a last resort: verify alarming signals with reliable checks (git/node — not guesses) first, and prefer scoped recovery — a running child's in-flight work dies with it, partial changes stay unmerged and unaudited. Background advisor reviews cancel the same way (pass the review id — no token is issued for a cancelled review).
-- action:'consume-design' (engineering mode, parent side): chain-terminal token consumption — after the delivery is verified and the chain closes out, consume this design's token slot. Selectors — pass exactly ONE: designId (a single slot; optional for a single-design session), designIds (an explicit non-empty list), expired:true (every expired slot), or olderThanDays:N (every slot older than N days). A consumed slot mechanically rejects further spawns for the same designId — new work (deviation fixes included) needs a fresh design review and token. Idempotent (unknown/already-consumed = a no-op notice); batch calls report per-slot lines + a `consumed N` count line. Do NOT call while the chain is still open — fix rounds reuse the same slot.
-- action:'design-slots' (engineering mode, parent side): READ-ONLY inventory of this session's approved design token slots — one line per slot (designId, live|expired, ageDays, expiresAt, batch, designToken), oldest first, ending with a total/live/expired count line. Nothing is written. Use it to see what still holds a slot before consuming; the expired / olderThanDays selectors act on the same set.
-  Every row carries its designToken value (expired ones included — status marks them; a malformed record shows designToken=—). Pass designId to filter to a single slot (trimmed exact match; unknown = refused with the held id list; empty string = no filter). Take designId + designToken verbatim onto the eng-coder spawn — the gate checks exact equality.
-- action:'panel': DIAGNOSE + fix the subagent panel (the collapsible blocks the user sees; headless/VS Code degrade to a 'no panel' pool view). view (default): the live blocks (key, role, status: running|done|awaitingDigest) exactly as the user sees them — digested-stuck entries carry digested:true. freeze: pass a digested-stuck block key (e.g. 'eng-coder#9' — {action:'panel', freeze:'role#N'}) to reclaim it into the conversation — passes ONLY for awaitingDigest blocks with no live pool entry and no pending report (a still-pending report would break the digestion order — refused).
+- action:'status': NON-BLOCKING progress query — returns immediately, consumes nothing, never fetches. Pass the spawn id for one child (role, state: running|queued|done, model, elapsed, turn, position, plus a touched-files summary — first 5 + a count) or omit it for a pool overview — see what a
+  running child has changed BEFORE cancelling it. Background advisor reviews share this surface (pass the review id — role:'advisor', reviewType/round/elapsedSec, same shape).
+- action:'observe': SEE what a running async subagent is DOING right now (progress vs stuck) — pass the id; returns state, turn, the tool(s) executing right now (omitted when none), and the last N one-line turn summaries, newest first (default 5, via recent). Readonly; running/queued/done all answer
+  — queued returns a placeholder, done gives the activity summary only, NOT the report (it rides the auto channel). Judge stuck vs progressing BEFORE cancelling or steering.
+- action:'send': STEER a running async subagent mid-flight — id + message (a direction, e.g. "check X, don't fixate on Y"). The child consumes it at its next turn boundary as an ORDINARY user instruction (non-interrupting; its discipline is unchanged — guidance, not a deviation waiver); returns {id,
+  status:'delivered', queued}. Only RUNNING async children are targetable — sync/queued/settled/unknown error clearly; if the child settles first, its report carries an 'undelivered' note.
+- action:'escalate' (飞刀): hand an implementation task to a STRONGER model from your consult models; it gets WRITE access and does the work itself, then returns a post-op report (what changed, why, verification). Escalate EARLY, when the task calls for stronger hands (complex refactors, intractable
+  bugs, intricate algorithms — or beyond your comfortable ability). Not available in engineering mode (implementation goes through eng-coder). Default-async at depth 0: ack {id, role:'escalate', status:'running'} returns immediately; the report arrives automatically with its mutations merged into
+  your bookkeeping (pooled with the other role-domain spawns).
+- action:'cancel': STOP ONE background subagent — the id from the spawn return is REQUIRED (a blanket cancel is unsupported; Ctrl+C stops everything). Running aborts immediately ({id, status:'cancelled'}); queued is removed ({id, status:'cancelled', was:'queued'}; later positions shift). Other
+  children and the session keep running. Cancel is a last resort: verify alarming signals with reliable checks (git/node — not guesses) first, and prefer scoped recovery — a running child's in-flight work dies with it, partial changes stay unmerged and unaudited. Background advisor reviews cancel
+  the same way (pass the review id — no token is issued for a cancelled review).
+- action:'consume-design' (engineering mode, parent side): chain-terminal token consumption — after the delivery is verified and the chain closes out, consume this design's token slot. Selectors — pass exactly ONE: designId (a single slot; optional for a single-design session), designIds (an
+  explicit non-empty list), expired:true (every expired slot), or olderThanDays:N (every slot older than N days). A consumed slot mechanically rejects further spawns for the same designId — new work (deviation fixes included) needs a fresh design review and token. Idempotent
+  (unknown/already-consumed = a no-op notice); batch calls report per-slot lines + a `consumed N` count line. Do NOT call while the chain is still open — fix rounds reuse the same slot.
+- action:'design-slots' (engineering mode, parent side): READ-ONLY inventory of this session's approved design token slots — one line per slot (designId, live|expired, ageDays, expiresAt, batch, designToken), oldest first, ending with a total/live/expired count line. Nothing is written. Use it to
+  see what still holds a slot before consuming; the expired / olderThanDays selectors act on the same set.
+  Every row carries its designToken value (expired ones included — status marks them; a malformed record shows designToken=—). Pass designId to filter to a single slot (trimmed exact match; unknown = refused with the held id list; empty string = no filter). Take designId + designToken verbatim onto
+  the eng-coder spawn — the gate checks exact equality.
+- action:'panel': DIAGNOSE + fix the subagent panel (the collapsible blocks the user sees; headless/VS Code degrade to a 'no panel' pool view). view (default): the live blocks (key, role, status: running|done|awaitingDigest) exactly as the user sees them — digested-stuck entries carry digested:true.
+  freeze: pass a digested-stuck block key (e.g. 'eng-coder#9' — {action:'panel', freeze:'role#N'}) to reclaim it into the conversation — passes ONLY for awaitingDigest blocks with no live pool entry and no pending report (a still-pending report would break the digestion order — refused).
 
 Why delegate? The child's noise never reaches your window — delegation keeps your context lean and the child focused; parallel children save wall-clock time, and coder/eng-coder children self-review (verify + advisor) before their reports arrive.
 
 Available roles (exposed per mode; the role is REQUIRED for action:'spawn' — a missing or misspelled role is refused):
 - explore — read-only search & analysis (read/search family); no git context — evidence comes from reads and the task book; its report must list what it searched and what it did NOT find. Say quick / medium / thorough (default medium).
 - plan — read-only planning; NEVER edits; returns a step-by-step plan.
-- coder — full implementation; the parent's complete read/write/execute toolset plus verify and advisor self-review. Its report carries a delivery table, one row per requirement (Done / Simplified / Not done — no deferred column). Normal mode: may optionally carry `batchDoc` — binds this spawn's §5 record-write channel (unbound ⇒ the main agent records §5 on its behalf); when provided the path must resolve to a readable file.
-- eng-coder — engineering mode only (replaces coder): same toolset plus the design-driven methodology overlay; its delivery protocol (implementation → audit → self-fix → advisor re-review → converged delivery) runs fully inside the child. REQUIRES a valid designToken from a passed advisor(type='design') review — pass the exact value from that review, or copy it verbatim from the action:'design-slots' row (the text after designToken=): missing or mismatched = the spawn is refused, and an expired token is refused with expired named (its reply also echoes a designId — pass it: required to pick between concurrent designs, optional for one; echo it back in the delivery report). REQUIRES a batchDoc — the batch record path, the task book this spawn implements (refused without it or when it does not resolve to a readable file).
-- eng-designer — engineering mode only: the SOLE author of the requirements/design documents and of the batch record's design section. Writes no implementation code, does not edit prompts, does not fire reviews, needs NO designToken. Surveys on its own; may only spawn read-only explore children (sync, ≤6 per batch). REQUIRES a batchDoc (same gate as eng-coder).
+- coder — full implementation; the parent's complete read/write/execute toolset plus verify and advisor self-review. Its report carries a delivery table, one row per requirement (Done / Simplified / Not done — no deferred column). Normal mode: may optionally carry `batchDoc` — binds this spawn's §5
+  record-write channel (unbound ⇒ the main agent records §5 on its behalf); when provided the path must resolve to a readable file.
+- eng-coder — engineering mode only (replaces coder): same toolset plus the design-driven methodology overlay; its delivery protocol (implementation → audit → self-fix → advisor re-review → converged delivery) runs fully inside the child. REQUIRES a valid designToken from a passed
+  advisor(type='design') review — pass the exact value from that review, or copy it verbatim from the action:'design-slots' row (the text after designToken=): missing or mismatched = the spawn is refused, and an expired token is refused with expired named (its reply also echoes a designId — pass it:
+  required to pick between concurrent designs, optional for one; echo it back in the delivery report). REQUIRES a batchDoc — the batch record path, the task book this spawn implements (refused without it or when it does not resolve to a readable file).
+- eng-designer — engineering mode only: the SOLE author of the design documents and of the batch record's design section (requirement docs stay with the main agent). Writes no implementation code, does not edit prompts, does not fire reviews, needs NO designToken. Surveys on its own; may only spawn
+  read-only explore children (sync, ≤6 per batch). REQUIRES a batchDoc (same gate as eng-coder).
 
-Task book (every spawn role): four core structured parameters — goal (goal & why), knownFacts (the facts you already verified), acceptance (machine-verifiable criteria), reportFormat (delivery-report format) — plus ONE fifth parameter named by role: designPoints (design points & forbidden scope) for eng-coder/eng-designer, scope (scope & forbidden scope — what to read / what not to touch) for explore/plan/coder. All five are required: a missing, blank or non-string value is refused with the parameter named, and one role's fifth name never substitutes for the other's. They are composed into the child's brief in that order. A free-text task is an optional supplement, never the whole brief; round (initial|fix) is mandatory for eng-coder/eng-designer. An eng-coder spawn also carries designToken — the write credential (the exact value from the review, or copied verbatim from the action:'design-slots' row, the text after designToken=): missing or mismatched = the spawn is refused.
+Task book (normal-mode roles: explore / plan / coder): four core structured parameters — goal (goal & why), knownFacts (the facts you already verified), acceptance (machine-verifiable criteria), reportFormat (delivery-report format)
+— plus scope (scope & forbidden scope — what to read / what not to touch).
+All five are required: a missing, blank or non-string value is refused with the parameter named.
+A free-text task is an optional supplement, never the whole brief.
+Engineering roles (eng-coder / eng-designer) take their task book from the batch record: batchDoc (the record path) and round (initial|fix), plus files / dependsOn for scheduling; the child reads §2 of that record itself — no other task text is passed.
+An eng-coder spawn also carries designToken — the write credential (the exact value from the review, or copied verbatim from the action:'design-slots' row, the text after designToken=), and designId when several designs are open: missing or mismatched = the spawn is refused.
 
 Pass one parameter per field — contents only (the runtime adds the labels):
-subagent(role="eng-coder", round="initial", goal="…", knownFacts="…", designPoints="…", acceptance="…", reportFormat="…", batchDoc="<batch record>", designToken="…")
+subagent(role="eng-coder", round="initial", batchDoc="<batch record>", designToken="…", files=[…])
 subagent(role="explore", goal="…", knownFacts="…", scope="…", acceptance="…", reportFormat="…")
 
 Mode filtering: normal mode exposes explore/plan/coder; engineering mode exposes explore/eng-designer/eng-coder — off-mode roles are refused mechanically (enums filtered at assembly; the spawn gate re-checks).
 
-Async spawn: top-level spawns are async by default — never pass async:false at depth 0 (the spawn returns {id, status:"running"} immediately; the report arrives automatically; if your next step needs it, end the turn and let the digest deliver it — do not poll; the explicit async:false is a mechanism parameter, not for model use). Inside subagents (depth>0) spawns are always synchronous. Async spawns are pooled per role domain — 4 concurrent eng-coders plus 4 concurrent other-role spawns by default (agent.poolLimits overrides both); a full domain queues further spawns with a position while the other keeps starting.
+Async spawn: top-level spawns are async by default — never pass async:false at depth 0 (the spawn returns {id, status:"running"} immediately; the report arrives automatically; if your next step needs it, end the turn and let the digest deliver it — do not poll; the explicit async:false is a
+mechanism parameter, not for model use). Inside subagents (depth>0) spawns are always synchronous. Async spawns are pooled per role domain — 4 concurrent eng-coders plus 4 concurrent other-role spawns by default (agent.poolLimits overrides both); a full domain queues further spawns with a position
+while the other keeps starting.
 
-Task scheduling: declare files (the file paths this task will modify) and dependsOn (ids from prior async returns whose outcome this task needs) to let the scheduler order your spawns. Overlapping-file tasks serialize and dependents start in order: a conflicting/dependent spawn queues (position/reason) and auto-starts when the conflict clears / the dependency settles (cancel to drop). A cancelled/failed dependency leaves it queued marked "dependency cancelled" until you decide (AUTO sessions auto-start). Unknown ids error; a consumed id counts as satisfied. Omit both for a plain immediate spawn (no scheduler involvement).
+Task scheduling: declare files (the file paths this task will modify) and dependsOn (ids from prior async returns whose outcome this task needs) to let the scheduler order your spawns. Overlapping-file tasks serialize and dependents start in order: a conflicting/dependent spawn queues
+(position/reason) and auto-starts when the conflict clears / the dependency settles (cancel to drop). A cancelled/failed dependency leaves it queued marked "dependency cancelled" until you decide (AUTO sessions auto-start). Unknown ids error; a consumed id counts as satisfied. Omit both for a plain
+immediate spawn (no scheduler involvement).
 
 Writing the prompt:
 - The child starts with zero context — brief it like a colleague who just walked in: goal, what you already know, the specifics.

package/tool-docs/wait_for.md

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

package/tools/web-deepseek.mjs

@@ -9,8 +9,9 @@
  *
  * The tools never fail because of this backend: every export returns a pure value
  * (`{ status: "ok" | "empty" | "failed" | "unavailable" }`) and never throws.
- * 401/402/403/404 trip a per-agent breaker (WeakSet); 408/429/5xx retry once (500 ms);
- * everything else falls back to the caller's existing chain.
+ * 401/402/403 trip a per-agent breaker for `BREAKER_TTL_MS` (10 min — auto-unseals, no restart);
+ * 404 does NOT trip (the target page is missing — not a credential failure, D-WB3); 408/429/5xx
+ * retry once (500 ms); everything else falls back to the caller's existing chain.
  */
 import { URL } from "node:url"
 import { truncate, isPrivateHost } from "./shared.mjs"
@@ -27,7 +28,8 @@ const DEEPSEEK_HOST = "api.deepseek.com"
 const TIMEOUT_MS = 15_000
 const RETRY_DELAY_MS = 500 // D-WB5: fixed single backoff (no Retry-After parsing)
 const COST_PER_CALL = 0.00075 // $0.75 / 1000 successful requests — `count` does not change the price
-const TRIP_STATUS = new Set([401, 402, 403, 404])
+const TRIP_STATUS = new Set([401, 402, 403]) // 404 = 目标页面的状态，不是凭据失效（D-WB3）
+const BREAKER_TTL_MS = 600_000 // 熔断限时 10 分钟——到期自动放行（改完 key 无需重启会话）
 const RETRY_STATUS = (() => {
   const codes = new Set([408, 429])
   for (let code = 500; code <= 599; code++) codes.add(code)
@@ -35,11 +37,16 @@ const RETRY_STATUS = (() => {
 })()
 
 let _transport = proxyFetch
-let _breaker = new WeakSet()
+let _now = Date.now
+let _breaker = new WeakMap() // agent → expiresAtMs（单域——search ∥ fetch 共享，D-WB3）
 
-/** Test seam (CONFIG.md §6.2 ③ — paired): swap the transport; reset also clears the breaker. */
+/** Test seam (CONFIG.md §6.2 ③ — paired): swap the transport ∥ the clock; reset also clears the breaker. */
 export function _setDeepseekTransportForTest(fn) { _transport = typeof fn === "function" ? fn : proxyFetch }
-export function _resetDeepseekTransportForTest() { _transport = proxyFetch; _breaker = new WeakSet() }
+export function _setDeepseekClockForTest(fn) { _now = typeof fn === "function" ? fn : Date.now }
+export function _resetDeepseekTransportForTest() { _transport = proxyFetch; _now = Date.now; _breaker = new WeakMap() }
+
+/** 熔断名单只读面（用例断言 404 零命中——D-WB3）。 */
+export const _TRIP_STATUS_FOR_TEST = Object.freeze([...TRIP_STATUS])
 
 /** `local` skips the DeepSeek backend; anything else (missing ∥ misspelled ∥ non-string) = `auto` (fail-open). */
 export function backendMode(cfg, key) {
@@ -66,11 +73,19 @@ function deepseekChannel(cfg) {
   return null
 }
 
-const tripped = (agent) => agent !== null && typeof agent === "object" && _breaker.has(agent)
+/** 熔断未到期？到期 ⇒ 删条目并放行（判活读时钟——改完 key 不必重启会话）。 */
+function tripped(agent) {
+  if (agent === null || typeof agent !== "object") return false
+  const expiresAt = _breaker.get(agent)
+  if (typeof expiresAt !== "number") return false
+  if (expiresAt > _now()) return true
+  _breaker.delete(agent)
+  return false
+}
 
-/** Break the backend for this agent identity (single domain — search ∥ fetch share it, D-WB3). */
+/** Break the backend for this agent identity for `BREAKER_TTL_MS` (single domain — search ∥ fetch share it, D-WB3). */
 function trip(agent) {
-  if (agent !== null && typeof agent === "object") _breaker.add(agent)
+  if (agent !== null && typeof agent === "object") _breaker.set(agent, _now() + BREAKER_TTL_MS)
 }
 
 /** One POST. Returns `{ kind: "ok", data }` | `{ kind: "http", status }` | `{ kind: "net", timeout }` | `{ kind: "json" }`. */
@@ -95,7 +110,7 @@ async function postOnce(url, body, apiKey, proxyUri) {
   } finally { clearTimeout(timer) }
 }
 
-/** One logical call: retry once (408/429/5xx), trip on 401/402/403/404, otherwise fall back. */
+/** One logical call: retry once (408/429/5xx), trip on 401/402/403, otherwise fall back. */
 async function request(url, body, apiKey, proxyUri, tool, agent) {
   const started = Date.now()
   let r = await postOnce(url, body, apiKey, proxyUri)
@@ -107,7 +122,7 @@ async function request(url, body, apiKey, proxyUri, tool, agent) {
   if (r.kind === "http" && TRIP_STATUS.has(r.status) && agent !== null && typeof agent === "object") {
     trip(agent)
     // Tripping line only (transient fallbacks stay quiet — ⑤).
-    logEvent("web:deepseek", { tool, status: r.status, tripped: true, ms: Date.now() - started })
+    logEvent("web:deepseek", { tool, status: r.status, tripped: true, ttlMs: BREAKER_TTL_MS, ms: Date.now() - started })
   }
   const reason = r.kind === "http" ? `http ${r.status}`
     : r.kind === "net" ? (r.timeout ? "timeout" : "network")

package/doc-check/version.mjs

@@ -1,84 +0,0 @@
-/**
- * doc-check/version.mjs — 引擎版本一致性的**单源**（纯函数 + 常量；两个消费面共用一个判据）。
- *
- * 权威规格 = `docs/core/design/DOC-DISCIPLINE.md` §3.20「引擎版本一致」（判据 / 比较 / 裁定 / 保守方向；
- * 本档只实现，不重述口径）。消费面两处：工具面 `agent-tools/doc-check.mjs` 的 gate 分支（转口导出、
- * 导出面不变）∥ 结构门 `agent-tools/batch-gate.mjs`（batch 两机械点）——两处不得各持一份清单。
- *
- * 问题形态：`thincoder-core/doc-check/**` 是 ESM，进程启动时加载即缓存；引擎档在启动后被改写 ⇒
- * 本会话仍跑旧模块 ⇒ 假阳（旧误报消不掉）/ 假绿（引擎变严时旧版放过）。故 gate 在跑判据前先判版本。
- *
- * `ENGINE_FILES` 六档 = 判据面：三判据档 + 本档（版本函数单源，自身入清单 = fail-closed）+ 工具面 +
- * 描述档。路径按本档 `import.meta.url` 解析到产品核根，**不随 target 变**。
- */
-import { statSync } from "node:fs"
-import { resolve } from "node:path"
-import { fileURLToPath } from "node:url"
-
-/** 产品核根（版本清单基线——本档住 `doc-check/`，上跳一级）。 */
-const CORE_ROOT = fileURLToPath(new URL("..", import.meta.url))
-
-/** 引擎六档 = 版本一致性的判据面（§3.20「引擎版本一致」· 判据）。 */
-export const ENGINE_FILES = [
-  "doc-check/index.mjs",
-  "doc-check/anchors.mjs",
-  "doc-check/width.mjs",
-  "doc-check/version.mjs",
-  "agent-tools/doc-check.mjs",
-  "tool-docs/doc_check.md",
-]
-
-/**
- * 引擎版本一致性（纯函数——时钟 ∥ stat 可注 ⇒ 可测，不碰产品档 mtime）：
- * 逐档 `mtimeMs` 与**本进程启动时刻**（`nowMs − uptimeSec × 1000`）比较——晚于启动 ⇒ 该档可能晚于模块加载 ⇒ stale。
- * 不可 `stat` 的档同样入 stale（fail-closed，不静默忽略）。`mtime ≤ 启动` 一定不比缓存新；
- * `mtime > 启动` 只是**可能**晚于加载 —— 取 fail-closed 方向（误判代价 = 一次会话重启）。
- * @param {{nowMs?:number, uptimeSec?:number, stat?:Function}} [o] 注入缝（缺省 = 真时钟 / 真 `statSync`）
- * @returns {{startMs:number, stale:{file:string, mtimeMs:number|null}[]}} `file` = 相对 `thincoder-core/` 的正斜杠路径
- */
-export function staleEngineFiles({ nowMs = Date.now(), uptimeSec = process.uptime(), stat = statSync } = {}) {
-  const startMs = nowMs - uptimeSec * 1000
-  const stale = []
-  for (const file of ENGINE_FILES) {
-    let mtimeMs = null
-    try { mtimeMs = stat(resolve(CORE_ROOT, file)).mtimeMs } catch { stale.push({ file, mtimeMs: null }); continue }
-    if (typeof mtimeMs !== "number" || !Number.isFinite(mtimeMs)) { stale.push({ file, mtimeMs: null }); continue }
-    if (mtimeMs > startMs) stale.push({ file, mtimeMs })
-  }
-  return { startMs, stale }
-}
-
-/** stale 列表形（`<文件> mtime <ISO 8601>`，`；` 连列）——gate ERROR 行 ∥ report 注记行共用一处格式。 */
-function staleParts(stale) {
-  const when = (t) => new Date(t).toISOString()
-  return stale.map((s) => `${s.file} mtime ${s.mtimeMs === null ? "不可读（stat 失败）" : when(s.mtimeMs)}`)
-}
-
-/** 引擎版本 ERROR 报面（固定句形）：多档 stale ⇒ 逐档 `<文件> mtime <时间>` 以 `；` 连列——**不产 PASS**。 */
-export function gateEngineError({ startMs, stale }) {
-  const when = (t) => new Date(t).toISOString()
-  return [
-    `DOC-CHECK GATE: ERROR（引擎已更新（${staleParts(stale).join("；")} > 进程启动 ${when(startMs)}），请重启会话后复跑）`,
-    "原因：本会话进程加载的引擎模块早于盘上引擎档——旧引擎读数不可信（假阳：旧误报消不掉 ∥ 假绿：引擎变严时旧版放过）",
-    "处置：重启会话后复跑 gate（`report` 不裁定、不产 verdict（陈旧时只在首行前加注记））",
-  ].join("\n")
-}
-
-/** 报告态引擎陈旧注记（纯函数）：stale 空 ⇒ `null`；非空 ⇒ 一行注记（逐字单源 = `DOC-DISCIPLINE.md`
- *  §3.20「gate 裁定 · report 注记」——多档以 `；` 连列，与 `gateEngineError` 同形）。 */
-export function reportEngineNote({ startMs, stale } = {}) {
-  if (!Array.isArray(stale) || stale.length === 0) return null
-  const when = (t) => new Date(t).toISOString()
-  return `[doc_check note] 引擎陈旧（${staleParts(stale).join("；")} > 进程启动 ${when(startMs)}）——本次读数由会话启动时加载的旧引擎产出，不可作为交付判据；重启会话后复跑。`
-}
-
-/** 报面 + 注记：有注记 ⇒ 注记行 + 原报面；无 ⇒ 原报面逐字返回（三不改：既有行 ∥ verdict ∥ PASS 语义）。 */
-export function withEngineNote(report, version) {
-  const note = reportEngineNote(version ?? {})
-  return note ? `${note}\n${report}` : report
-}
-
-/** 报面首行取形（唯一机判串 = 首行 `DOC-CHECK GATE:` 前缀——消费面共用一个取法，不各自 split）。 */
-export function firstVerdictLine(report) {
-  return String(report ?? "").split("\n")[0] ?? ""
-}

package/doc-check/width.mjs

@@ -1,87 +0,0 @@
-/**
- * doc-check/width.mjs — 文档纪律机检的产品档位（行宽谓词族 + 行宽判据——实现单源）。
- *
- * 口径单源 = `docs/core/design/DOC-DISCIPLINE.md` §3.18 条目 Q（度量 / 豁免类）；
- * 产品内建裁定 = 同档 §3.20 条目 S——谓词单源随迁：本仓 `scripts/doc-check-width.mjs` 改述为
- * **再出口缝**（薄档 · 零逻辑 · 逐名再出口），盘上不留第二份谓词实现。
- * 度量 = `[...line].length`（CJK 计 1——不引显示宽度 / 字体）；阈值 = 调用方的内置常量
- * （`DOC_CHECK_BUILTINS.lineWidth`）——不读声明面，也不扫目录：**判定集 = 调用方传入的文件清单**。
- * 豁免五类 = 表格行 ∥ fenced 块 ∥ 可执行行 ∥ 连续引文 ∥ 区带：**只认结构谓词**，
- * 无行级白名单（按行号 / 注释声明的豁免不入判）。
- * 边界：本档零门禁 / 零退出码 / 零阻断——报告态由 `agent-tools/doc-check.mjs` 呈现。
- */
-import { readFileSync } from "node:fs"
-
-/** 表格行谓词（markdown 表格行结构性不可折行——行宽豁免，与锚检查同源）。 */
-export const isTableRow = (l) => /^\s*\|.*\|\s*$/.test(String(l))
-
-/** 围栏标记（行首可选空白 + 三反引号 ∥ 三波浪号 ⇒ 标记字符；非围栏行 ⇒ null）——**单源**：
- *  `isFenceLine` 与两处块扫描（本节行宽 ∥ `./anchors.mjs` 锚抽取）同取此式，使「同形围栏行止」只此一解
- *  （同一模块内同符两义 = 单源可漂的结构口子）。 */
-export function fenceMark(l) {
-  const m = /^\s*(`{3,}|~{3,})/.exec(String(l))
-  return m ? m[1][0] : null
-}
-
-/** 围栏行谓词（单源 = `fenceMark`）——围栏行自身与块内整行均豁免。 */
-export const isFenceLine = (l) => fenceMark(l) !== null
-
-/** 引文块行谓词（行首可选空白 + `>`）——连续 `>` 行整块豁免（引证须逐字连续、不可折，同表行理据）。 */
-export const isQuoteLine = (l) => /^\s*>/.test(String(l))
-
-/** 区带头谓词（§3.15 谓词面）：标题文本去首部编号（`^\d+(?:\.\d+)*[.、]?\s*`）后——等于区带名 ∨ 以
- *  「区带名 + （∕(」起（容括注后缀，如 `变更记录（续）`）；闭集外一律不纳（fail-closed）。 */
-export function isZoneHead(headingText, zones = []) {
-  const text = String(headingText).replace(/^\d+(?:\.\d+)*[.、]?\s*/, "")
-  return zones.some((z) => typeof z === "string" && z !== "" && (text === z || text.startsWith(z + "（") || text.startsWith(z + "(")))
-}
-
-/** 行内可执行坐标（命令 / 搜索模式串码段）——整行豁免（证据与命令保字面，与锚判据同源）。 */
-export function isExecutableLine(line) {
-  const l = String(line)
-  if (/`[^`\n]*&&[^`\n]*`/.test(l)) return true // 命令链（cd … && …）
-  if (/`[^`\n]*\b(?:cd|node|npm|npx|grep|rg|git)\s[^`\n]*`/.test(l)) return true // 码段内命令词
-  if (/`[^`\n]*(?:\[\^|\\\.|\(\?<|\(\?:|\{\d)/.test(l)) return true // 码段内搜索模式串片段
-  return false
-}
-
-/** 行内位置是否在反引号码段内（引述面不判）。 */
-export function inCodeSpan(line, idx) {
-  return (String(line).slice(0, idx).match(/`/g) ?? []).length % 2 === 1
-}
-
-/** 行宽判据（阈值 = 调用方内置常量 `lineWidth`）：`[...line].length` > 阈值 ∧ 非表格行 ∧ 非 fenced 块内
- *  ∧ 非可执行行 ∧ 非连续引文 ∧ 非区带内 ⇔ 命中（口径逐字 = §3.18 条目 Q）。
- *  单遍扫描携标题栈（`^(#{1,6})\s` 行入栈——同级 ∥ 更高级出栈）：行所属标题链任一为区带头 ⇒ 豁免。
- *  围栏未闭合 ⇒ 至档尾整块免（fail-open 方向——§3.18 残余登记 ①）；`exemptZones` 缺省 ∥ 空集 ⇒ 零豁免。
- *  `files`（必填）= **判定集**（调用方传入的档清单——本档不遍历任何目录；空集 ⇒ 零命中）。 */
-export function checkDocWidths({ lineWidth, exemptZones = [], files = [] } = {}) {
-  const zones = (Array.isArray(exemptZones) ? exemptZones : []).filter((z) => typeof z === "string" && z !== "")
-  const hits = []
-  for (const f of files) {
-    let text = ""
-    try { text = readFileSync(f, "utf8") } catch { continue }
-    const stack = [] // 标题栈 —— { level, exempt }；exempt = 自身 ∥ 祖先命中区带
-    let fence = null // 围栏标记（` ∥ ~）；null = 不在块内
-    text.split("\n").forEach((l, i) => {
-      const mark = fenceMark(l)
-      if (mark !== null) {
-        if (fence === null) fence = mark
-        else if (mark === fence) fence = null
-        return // 围栏行自身免
-      }
-      if (fence !== null) return // 块内整块免（未闭合 ⇒ 至档尾免）
-      const hm = /^(#{1,6})\s+(.*)$/.exec(l)
-      if (hm) {
-        while (stack.length && stack[stack.length - 1].level >= hm[1].length) stack.pop()
-        const self = isZoneHead(hm[2].trim(), zones)
-        stack.push({ level: hm[1].length, exempt: self || (stack[stack.length - 1]?.exempt ?? false) })
-        return
-      }
-      const inZone = stack[stack.length - 1]?.exempt === true
-      const len = [...l].length
-      if (len > lineWidth && !isTableRow(l) && !isExecutableLine(l) && !isQuoteLine(l) && !inZone) hits.push({ file: f, line: i + 1, len })
-    })
-  }
-  return hits
-}