thincoder 0.12.59 → 0.12.61

package/src/abort-provenance.mjs

@@ -0,0 +1,116 @@
+/**
+ * abort-provenance.mjs — abort 来源标注词汇表（单一权威源——AGENT-LOOP.md §20.3 第 1/2 条）
+ *
+ * 子代理 / 评审 / 会诊死亡的可诊断性：产生点标注结构化来源（`err.abortInfo`）→
+ * controller 链 hop 逐跳保 reason（§20.3 第 4 条 #10）→ 结算 / 报告面用 `deathLine`
+ * 合成死亡行（原 message 前缀逐字保留 + 来源后缀）。
+ *
+ * 纯函数、零 import——任意层可引、无环（provider / proxy / agent / settle 族共用）。
+ * 词汇表：
+ * - trigger（5 值）：`user`（reason.interrupt）· `timeout`（TimeoutError / 定时器面）·
+ *   `cancel`（定向中止）· `stop`（整批 / 会话 / 回合级停）· `unknown`（残留 / 未标注——告警态）。
+ * - layer（3 值）：`provider` / `agent` / `settle`；未标注错误回落 `unrecorded`（合成器 token）。
+ */
+
+/** trigger 枚举权威（测试锁计数 5——AGENT-LOOP.md §20.3 第 1 条表）。 */
+export const TRIGGERS = ["user", "timeout", "cancel", "stop", "unknown"]
+
+/**
+ * trigger 判定（判据序 = §20.3 第 1 条表；signal.reason 四形态：
+ * ① `{interrupt:true(,message)}`（既有 user 面）② `TimeoutError`（原生——timeout 面）
+ * ③ `{abortTrigger:"cancel"|"stop"|"timeout"(,abortDetail)}`（新增——程序性中止）
+ * ④ 缺失 / 无已知键（→ unknown——诊断告警态，不得静默）。
+ */
+export function triggerOf(signal) {
+  const reason = signal?.reason
+  if (reason == null) return "unknown"
+  if (reason.interrupt === true) return "user"
+  if (reason.name === "TimeoutError" || reason.abortTrigger === "timeout") return "timeout"
+  if (reason.abortTrigger === "cancel") return "cancel"
+  if (reason.abortTrigger === "stop") return "stop"
+  return "unknown"
+}
+
+/**
+ * 产生点错误（abort 面）：AbortError + `reason` 透传 + `abortInfo` 标注。
+ * message 取既有通用文案（既有前缀断言零回归——死亡行前缀逐字保留）。
+ */
+export function abortError(signal, layer, detail) {
+  const e = new DOMException("The operation was aborted", "AbortError")
+  e.reason = signal?.reason
+  e.abortInfo = { trigger: triggerOf(signal), layer, detail }
+  return e
+}
+
+/**
+ * 产生点错误（定时器面）：自有 message + `abortInfo{trigger:"timeout"}`。
+ * name 保持 "Error"（既有分类谓词——`AbortError` 分支——零变化）。
+ */
+export function timeoutError(message, layer, detail) {
+  const e = new Error(message)
+  e.abortInfo = { trigger: "timeout", layer, detail }
+  return e
+}
+
+/**
+ * 外部错误补标（undici / fetch 拒否等）：缺 `abortInfo` 才补（不覆盖产生点标注）；
+ * 不改 `name` / `message`（消费面零回归）。
+ * 第 4 参 detail 为站点名（站点表逐站点传——自由短串）。
+ */
+export function annotateAbort(err, signal, layer, detail) {
+  if (err?.abortInfo) return err
+  try {
+    err.abortInfo = { trigger: triggerOf(signal), layer, detail: detail ?? "unrecorded" }
+  } catch { /* frozen error——保持未标注（合成器 unknown 告警兜底） */ }
+  return err
+}
+
+/** 死亡行长度上限（AGENT-LOOP.md §20.3 第 3 条——超长优先截 detail）。 */
+const MAX_LEN = 300
+/** unknown 形态 detail token（§20.3 第 3 条逐字）。 */
+const NO_REASON = "no reason on signal"
+/** 未标注回落 token（layer / detail 两面兜底）。 */
+const UNRECORDED = "unrecorded"
+
+/** 信号域 detail 回落（§20.3 第 1 条形态③——`abortDetail` 载站点名；错误未标注时仍可辨发起动作）。 */
+const detailOf = (signal) => (typeof signal?.reason?.abortDetail === "string" ? signal.reason.abortDetail : null)
+
+/** 求值链（§20.3 第 1 条：err.abortInfo → triggerOf(signal) → err.name 兜底）。 */
+function resolveAbort(err, signal) {
+  const info = err?.abortInfo
+  if (info?.trigger) return { trigger: info.trigger, layer: info.layer ?? UNRECORDED, detail: info.detail || null }
+  const fromSignal = triggerOf(signal)
+  if (fromSignal !== "unknown") return { trigger: fromSignal, layer: UNRECORDED, detail: detailOf(signal) }
+  if (err?.name === "TimeoutError") return { trigger: "timeout", layer: UNRECORDED, detail: detailOf(signal) }
+  // AbortError / 无名——告警态（unknown 显式，空后缀即违规）
+  return { trigger: "unknown", layer: UNRECORDED, detail: NO_REASON }
+}
+
+/** detail 裁剪：优先截 detail（budget = 上限内剩余字符）。 */
+function clipDetail(detail, budget) {
+  if (budget <= 0) return ""
+  return detail.length <= budget ? detail : detail.slice(0, Math.max(1, budget - 1)) + "…"
+}
+
+/**
+ * 死亡行合成器（§20.3 第 3 条——报告面单点）：
+ * `<原 message>[ ← cause: <cause.message>][ · abort(<trigger>@<layer>:<detail>)]`
+ * - 原 message 前缀逐字保留（既有前缀 / 包含断言零回归）；
+ * - 后缀出现条件 = `err.abortInfo` 存在 ∨ `signal?.aborted` ∨ `err.name ∈ {AbortError, TimeoutError}`；
+ * - cause 段（P1）独立于后缀（"fetch failed" 类网络死亡真因同判）；
+ * - 总长 ≤300 字符（超长先截 detail，仍超再截尾）。
+ */
+export function deathLine(err, signal) {
+  let line = err?.message ?? String(err ?? "")
+  if (err?.cause?.message) line += ` ← cause: ${err.cause.message}`
+  const abortish = Boolean(err?.abortInfo) || Boolean(signal?.aborted) ||
+    err?.name === "AbortError" || err?.name === "TimeoutError"
+  if (abortish) {
+    const { trigger, layer, detail } = resolveAbort(err, signal)
+    const head = `${line} · abort(${trigger}@${layer}:`
+    // unknown 形态逐字用告警 token（§20.3 第 3 条——站点 detail 不进告警行）；非串 detail 归一化
+    const text = trigger === "unknown" ? NO_REASON : (detail == null ? UNRECORDED : String(detail))
+    line = `${head}${clipDetail(text, MAX_LEN - head.length - 1)})`
+  }
+  return line.length > MAX_LEN ? line.slice(0, MAX_LEN - 1) + "…" : line
+}

package/src/acp/bridge.mjs

@@ -20,7 +20,9 @@
  * `{ stopReason: "end_turn" }` (kimi session.ts parity).
  */
 import { detectDanger, normalizeEOL, joinWithEol } from "../tools/shared.mjs"
-import { computeEditEntry, validateEditEntry, assertEditArgsExclusive } from "../tools/edit-diff.mjs"
+import { computeEditEntry, validateEditEntry, assertEditArgsExclusive, hasLineParams } from "../tools/edit-diff.mjs"
+// 第 27 批 §12.3①/③：relay 前缀文法单一权威（模块直连——不自持正则副本）。
+import { parseRelayPath } from "../agent/relay-prefix.mjs"
 
 /** ACP ToolKind inference (schema v1 enum) — best-effort, clients render by kind. */
 function inferToolKind(name) {
@@ -92,7 +94,7 @@ export function buildAcpCallbacks({ sessionId, notify, request, log = () => {} }
   }
 
   // §15.1（TOOLS.md）D15.7 委派：edit 判定/应用单一权威 = 本地 computeEditEntry
-  // （edit-diff.mjs——校验→判定序→应用：行级 LCS、零重叠→插入、replace_all 字面替换全部）。
+  // （edit-diff.mjs——校验→判定序→应用：行级 LCS、零重叠→替换即删、replace_all 字面替换全部）。
   // 桥只留「读 IDE 缓冲 → computeEditEntry → 写回 IDE 缓冲」——错误文本经抛错原样透传
   // ——与本地通道逐字一致（NF15.6b / AC15.10：not found / occurrences / 空 old / 空 new）。
   const EDIT_ABORT_PREFIX = "edit aborted (atomic — no files written): "
@@ -130,7 +132,7 @@ export function buildAcpCallbacks({ sessionId, notify, request, log = () => {} }
   const editBatch = async (args) => {
     const edits = args.edits
     if (!Array.isArray(edits) || edits.length === 0) {
-      throw new Error("edits must be a non-empty array of {path, old_string, new_string}")
+      throw new Error("edits must be a non-empty array of {path, old_string | line/startLine+endLine, new_string}")
     }
     assertEditArgsExclusive(args)
     const groups = new Map() // path → { path, raw, content, edits }
@@ -167,26 +169,38 @@ export function buildAcpCallbacks({ sessionId, notify, request, log = () => {} }
 
   const callbacks = {
     onToken: (text) => {
-      // Strip the subagent `[model]` metadata token (role#id/[model]<name>) — it's a
+      // 第 27 批 §12.3③ 行 1（R-A2.1）：relay 前缀（role#id/——任意嵌套深度）零进显示面——
+      // 先剥前缀取 payload，信号判定与正文发送都作用在 payload 上。
+      const path = parseRelayPath(text)
+      const payload = path ? path.rest : text
+      // Strip the subagent `[model]` metadata token ([model]<name>) — it's a
       // TUI/webview display signal, not conversation content, and must not reach ACP clients.
-      // §19.5 D-M8 (round2 #6): nested prefixes recurse — eng-coder#2/explore#1/[model]…
-      if (/^(?:[\w-]+#\d+\/)*\[model\]/.test(text)) return
-      // D7 (AGENT-LOOP.md §7.2 + §19.5 round2 #6 + D-M7b): strip ⟦ev⟧ event tokens (bare or
-      // any-depth prefixed variants — turn/approval/done/settled/stopped/async — async
-      // = §19.5 D-M7b zero-field spawn marker) — they
-      // carry RS control characters and are a TUI display signal; structured ACP
+      if (/^\[model\]/.test(payload)) return
+      // D7 (AGENT-LOOP.md §7.2 + §19.5 round2 #6 + D-M7b): strip ⟦ev⟧ event tokens (turn/
+      // approval/done/settled/stopped/async — async = §19.5 D-M7b zero-field spawn marker)
+      // — they carry RS control characters and are a TUI display signal; structured ACP
       // mapping (tool_call_update) is tracked separately in docs/TODO.md.
       // 有意为之：控制字符协议/转义序列剥离正则（ANSI/⟦ev⟧/SGR/history 双线分隔）
-      if (/^(?:[\w-]+#\d+\/)*⟦ev⟧(?:turn|approval|done|settled|stopped|async)\x1e/.test(text)) return
-      update("agent_message_chunk", { content: { type: "text", text } })
+      if (/^⟦ev⟧(?:turn|approval|done|settled|stopped|async)\x1e/.test(payload)) return
+      if (!payload) return // D6：剥后空载荷不发通知（防噪声空 chunk）
+      update("agent_message_chunk", { content: { type: "text", text: payload } })
+    },
+    onReasoning: (text) => {
+      // 第 27 批 §12.3③ 行 2：同 onToken 取 payload；空载荷不发（D6）。
+      const path = parseRelayPath(text)
+      const payload = path ? path.rest : text
+      if (!payload) return
+      update("agent_thought_chunk", { content: { type: "text", text: payload } })
     },
-    onReasoning: (text) => update("agent_thought_chunk", { content: { type: "text", text } }),
     onUsage: (usage) => update("usage_update", { usage }),
     onWait: ({ phase, seconds }) => log(`[rate-limit] ${phase} waiting ~${seconds}s`),
     onCompress: () => log("[context] auto-compacted"),
 
     onToolCall: (name, args, toolId) => {
       const id = toolCallId()
+      // 第 27 批 §12.3③ 行 3：显示面剥前缀（title / kind）；配对键 toolQueue 存原样 name（D3）。
+      const path = parseRelayPath(name)
+      const shown = path ? path.rest : name
       // D15.8（advisor 🔴#1 修复）：模型级 id 每轮重置（sse.mjs finalizeToolCalls 内
       // seq=0——call_0 call_1… 跨轮/跨消息可重复——设计自注「跨 turn 不保证唯一」）。
       // 因此 push 前若队列已有同名同 toolId 条目，它必是结果永不回调的陈旧孤儿
@@ -200,8 +214,8 @@ export function buildAcpCallbacks({ sessionId, notify, request, log = () => {} }
       toolQueue.push({ name, id, toolId: toolId ?? null })
       update("tool_call", {
         toolCallId: id,
-        title: name,
-        kind: inferToolKind(name),
+        title: shown,
+        kind: inferToolKind(shown),
         status: "in_progress",
         rawInput: args ?? {},
         content: [contentBlock(JSON.stringify(args ?? {}))],
@@ -222,15 +236,19 @@ export function buildAcpCallbacks({ sessionId, notify, request, log = () => {} }
      * client. Any transport failure → reject (safety-first, kimi parity).
      */
     onPermissionRequest: async (name, args) => {
+      // 第 27 批 §12.3③ 行 4：显示面（请求文本 + toolCall.title）剥前缀；
+      // 危险基名判定与 peekToolId 照旧（配对键 = 原样名——D3）。
+      const path = parseRelayPath(name)
+      const shown = path ? path.rest : name
       // 危险命令标注(只提示不拦截):kimi 同款模式,帮助编辑器端用户审批
-      const base = name.includes("/") ? name.split("/").pop() : name
+      const base = shown.includes("/") ? shown.split("/").pop() : shown
       const danger = base === "bash" ? detectDanger(args?.command ?? "") : undefined
-      const content = [contentBlock(`Requesting approval to run ${name}`)]
+      const content = [contentBlock(`Requesting approval to run ${shown}`)]
       if (danger) content.push(contentBlock(`⚠️ Dangerous: ${danger}`))
       content.push(contentBlock(JSON.stringify(args ?? {})))
       const toolCall = {
-        toolCallId: peekToolId(name) ?? toolCallId(), // D15.8：peek 不消费——result 仍要与自己的条目配对
-        title: name,
+        toolCallId: peekToolId(name) ?? toolCallId(), // D15.8：peek 不消费（原样名键）——result 仍要与自己的条目配对
+        title: shown,
         content,
       }
       try {
@@ -269,7 +287,10 @@ export function buildAcpCallbacks({ sessionId, notify, request, log = () => {} }
           return { handled: true, result: `Error: fs/write_text_file failed: ${e.message}` }
         }
       }
-      if (base === "edit" && (Array.isArray(args?.edits) || (path && typeof args?.old_string === "string" && typeof args?.new_string === "string"))) {
+      // 2026-09-08 D1：单形态按行号改（path + line/startLine/endLine + new_string——无
+      // old_string）同样走 IDE 缓冲通道（hasLineParams 判定）——否则回落本地写盘会与
+      // IDE 缓冲脱敏；editSingle → computeEditEntry 行号语义自动继承。
+      if (base === "edit" && (Array.isArray(args?.edits) || (path && typeof args?.new_string === "string" && (typeof args?.old_string === "string" || hasLineParams(args))))) {
         try {
           const text = Array.isArray(args?.edits) ? await editBatch(args) : await editSingle(path, args)
           return { handled: true, result: text }
@@ -325,7 +346,10 @@ export function replayHistory({ sessionId, notify, history, log = () => {} }) {
         // later tool_call_updates by toolCallId; an orphan update would be ignored.
         pendingToolCalls = calls.map((tc, i) => {
           const id = `t${++toolSeq}`
-          const title = tc?.name ?? "tool"
+          // 第 27 批 §12.3③ 行 5（防御面——T18）：历史工具名带前缀 → 剥；无前缀 → 零变化。
+          const raw = tc?.name ?? "tool"
+          const path = parseRelayPath(raw)
+          const title = path ? path.rest : raw
           update("tool_call", {
             toolCallId: id,
             title,

package/src/acp.mjs

@@ -71,12 +71,17 @@ export function defaultIsConfigured() {
   }
 }
 
+/** 第 27 批 §12.3⑤（R-A1.1）：ACP 会话装配期剔除的工具。ACP 是 headless 通道——
+ *  question 工具需要交互 UI（`src/tools/question.mjs` 无 `ctx.onQuestion` 即 throw），
+ *  模型可见即会调用、调用必错 → 装配期剔除（schema 直接少一条）。 */
+export const ACP_EXCLUDED_TOOLS = ["question"]
+
 /** M1/M2 session factory: one agent per session, built from the process cwd (single-cwd model).
  *  `id` is the ACP session id — it is baked into the callbacks at construction time
  *  (buildAcpCallbacks closure), so it must be known BEFORE createAcpSession runs.
  *  `request` is the transport's reverse-RPC channel (permissions + fs routing). */
 export async function defaultCreateSession({ id, notify, request, log }) {
-  const agent = await assembleAgent()
+  const agent = await assembleAgent({ excludeTools: ACP_EXCLUDED_TOOLS })
   return createAcpSession({ id, agent, notify, request, log })
 }
 

package/src/advisor/citations.mjs

@@ -4,9 +4,14 @@
  * a host fact: every `file:line: content` reference in a review is mechanically
  * checked against the CURRENT disk state; mismatches mark the finding
  * unverified and cannot support a push-back.
+ *
+ * 第 11 批（C / F14 / §14.5）：解析候选 = cwd + **评审对象声明范围派生根**（声明仓根 /
+ * 声明文件目录 / 声明目录——纯路径派生，零扫描、零 git）；命中判据三条件全中（围栏内 ∧
+ * 可读 ∧ 目标行含引文内容）⇒ 零新增假命中。失败原因三分（file unreadable /
+ * content mismatch @ path / path traversal）——父侧不再人肉复核。
  */
 import { readFileSync, realpathSync } from "node:fs"
-import { resolve, sep } from "node:path"
+import { resolve, relative, dirname, extname, sep, isAbsolute, join } from "node:path"
 
 // `file:line: content` citations — the file group is narrowed to source/config
 // extensions so URLs (`example.com:8080: …`) don't become false-positive
@@ -25,48 +30,105 @@ export function extractCitations(text) {
   return out
 }
 
+/** 候选解析根（§14.5——纯路径派生，候选顺序 = cwd → 各声明路径的派生根）：
+ *  声明仓根（`cwd/<segs[0]>`）与 声明文件目录 / 声明目录本身。声明在 cwd 之外 → 不派生
+ *  （relative 越出 cwd 或跨盘符——候选与声明脱节即假命中面）。 */
+function citationRoots(cwd, scope) {
+  const base = resolve(cwd)
+  const roots = [base]
+  for (const s of Array.isArray(scope) ? scope : []) {
+    if (typeof s !== "string" || !s.trim()) continue
+    const abs = resolve(base, s)
+    const rel = relative(base, abs)
+    if (!rel || rel.startsWith("..") || isAbsolute(rel)) continue
+    const segs = rel.split(/[\\/]/).filter(Boolean)
+    if (segs.length === 0) continue
+    const repoRoot = join(base, segs[0])
+    const declaredDir = extname(abs) ? dirname(abs) : abs
+    for (const r of [repoRoot, declaredDir]) if (!roots.includes(r)) roots.push(r)
+  }
+  return roots
+}
+
+/** 单引文解析（§14.5）：按候选顺序试 `resolve(root, file)`；三条件全中才算命中。
+ *  @returns {{matched: true, root: string, resolved: string}|{matched: false, reason: string}} */
+function resolveCitation(citation, roots, base) {
+  const fence = base + sep
+  let mismatch = null
+  let traversal = false
+  for (const root of roots) {
+    let real
+    try {
+      // Path confinement: citation paths are LLM-generated — never trust them.
+      // A hallucinated "../config.json" would otherwise read (and leak via the
+      // report) files outside the project, including API-key configs.
+      // realpathSync resolves symlinks too — a link inside the project that
+      // points outside must not pass the prefix check.
+      real = realpathSync(resolve(root, citation.file))
+    } catch {
+      continue // 该候选无此文件（或不可解析）——试下一候选
+    }
+    if (!real.startsWith(fence)) { traversal = true; continue }
+    let line = ""
+    try {
+      line = readFileSync(real, "utf8").split("\n")[citation.line - 1] ?? ""
+    } catch {
+      continue // 存在但读不了（目录等）——按未命中处理，试下一候选
+    }
+    if (line.includes(citation.content)) {
+      return { matched: true, root, resolved: relative(base, real).split(sep).join("/") }
+    }
+    mismatch ??= real
+  }
+  if (mismatch) return { matched: false, reason: `content mismatch @ ${relative(base, mismatch).split(sep).join("/")}` }
+  if (traversal) return { matched: false, reason: "path traversal" }
+  return { matched: false, reason: "file unreadable" }
+}
+
 /**
  * Mechanically verify citations against the CURRENT file state: read the file,
  * take the exact line, check it CONTAINS the quoted content. Reports
  * N/M matched + the mismatches. Unverified citations cannot support a
  * push-back — the evidence rule becomes a host fact, not a prompt wish.
+ * @param {string} text — the review text
+ * @param {string} cwd — the agent's working directory (workspace root)
+ * @param {{scope?: string[]}} [opts] — scope = 评审对象声明路径（documents + paths）；
+ *   省略 ⇒ 旧行为（仅 cwd 候选——签名向后兼容）。
  */
-export function verifyCitations(text, cwd) {
+export function verifyCitations(text, cwd, opts = {}) {
   const citations = extractCitations(text)
   const matched = []
   const failed = []
-  const root = resolve(cwd) + sep
+  const base = resolve(cwd)
+  const roots = citationRoots(cwd, opts?.scope)
   for (const c of citations) {
-    try {
-      // Path confinement: citation paths are LLM-generated — never trust them.
-      // A hallucinated "../config.json" would otherwise read (and leak via the
-      // report) files outside the project, including API-key configs.
-      // realpathSync resolves symlinks too — a link inside the project that
-      // points outside must not pass the prefix check.
-      const resolved = realpathSync(resolve(cwd, c.file))
-      if (!resolved.startsWith(root)) {
-        failed.push({ ...c, reason: "path traversal" })
-        continue
-      }
-      const line = readFileSync(resolved, "utf8").split("\n")[c.line - 1] ?? ""
-      if (line.includes(c.content)) matched.push(c)
-      else failed.push(c)
-    } catch {
-      failed.push({ ...c, reason: "file unreadable" })
+    const r = resolveCitation(c, roots, base)
+    if (r.matched) {
+      // 命中根记录（§14.5）：经派生根解析（非 cwd 直解）的命中在报告中注明解析路径。
+      matched.push(r.root === base ? c : { ...c, root: r.root, resolved: r.resolved })
+    } else {
+      failed.push({ ...c, reason: r.reason })
     }
   }
   return { total: citations.length, matched, failed }
 }
 
 /** Append the verification report to the review text (visible to the parent agent). */
-export function appendCitationReport(text, cwd) {
-  const { total, matched, failed } = verifyCitations(text, cwd)
+export function appendCitationReport(text, cwd, opts = {}) {
+  const { total, matched, failed } = verifyCitations(text, cwd, opts)
   if (total === 0) return text // no citations — nothing to verify
   const lines = [
     "",
     "---",
     `[host-verified] ${matched.length}/${total} citations match current file state.`,
   ]
+  // 命中根透明（F14/§14.5）：经声明范围派生根解析的命中逐条注明解析路径（cwd 直解的不列
+  // ——零噪音；列的正是修复前会被误报为 unreadable 的裸路径引用）。
+  const derived = matched.filter((c) => c.resolved)
+  if (derived.length > 0) {
+    lines.push("Citations resolved via the declared review scope (bare path — resolved root noted):")
+    for (const c of derived.slice(0, 10)) lines.push(`- ${c.file}:${c.line} → ${c.resolved}`)
+  }
   if (failed.length > 0) {
     lines.push("Citations that do NOT match the current file state (treat their claims as unverified):")
     for (const f of failed.slice(0, 10)) {

package/src/advisor/compaction.mjs

@@ -0,0 +1,174 @@
+/**
+ * advisor/compaction.mjs — advisor review support (split out of advisor/run.mjs,
+ * 第 11 批 — run.mjs was 498/500 硬帽): context trimming + the review's resource
+ * limits + the terminal-state guards + the review-text assembler.
+ *
+ * estimateTokens / compactMessages moved VERBATIM (the only edit is the `pinned`
+ * re-attach — F13/§14.4 #3); renderTimeline moved verbatim too, so the tail
+ * GENERATOR and the tail CLASSIFIER stay in one file with the assembler they
+ * feed (§14.3 谓词 ↔ §14.6 结构化尾——同族单源)。拆分线 = 行数硬帽实测（见批次档 §5）。
+ */
+
+import { providerSpec } from "../config.mjs" // 第 25 批：预算派生（与 loop.mjs:11 同源导入）
+// B4（群 B 批，CLI §18.3——F32）：CJK 加权单源（provider/rate.mjs 叶子向无环）
+import { estimateText } from "../provider/rate.mjs"
+
+export const MAX_ADVISOR_TURNS = 100
+// NOTE: prompts/advisor-round{1,2,3}.md encourage the model to finish within
+// ~30 tool turns — a prompt-level efficiency target, DISTINCT from the
+// 100-turn mechanical hard cap (MAX_ADVISOR_TURNS above; pure runaway-loop
+// guard). They serve different purposes; do NOT synchronize them.
+
+// Context window limits
+// 上下文预算（第 25 批——120K 硬编码退场）：预算跟随评审模型窗口（providerSpec：
+// 模型规格表 × provider 级 context 覆盖）。头寸用途 = chars/4 估算误差 + 响应/协议开销
+// （内存不构成约束——设计 §16.4）；判死线仍是宿主机自限线，服务端窗口约束不变。
+export const CONTEXT_LIMIT_RATIO = 0.8  // 判死线 = 窗口 × 0.8
+const COMPACT_TRIGGER_RATIO = 0.8       // 压缩触发 = 判死线 × 0.8（既有关系零改）
+
+/** 评审上下文预算（纯函数——两档阈值可机测；provider 为 null 时退化默认规格）。 */
+export function advisorContextBudget(provider) {
+  const limit = Math.floor(providerSpec(provider).context * CONTEXT_LIMIT_RATIO)
+  return { limit, compactAt: Math.floor(limit * COMPACT_TRIGGER_RATIO) }
+}
+
+export const TOOL_TIMEOUT_MS = 30_000 // single tool timeout
+export const REVIEW_TIMEOUT_MS = 600_000 // whole review timeout (10 minutes)
+export const MAX_RESULT_CHARS = 64 * 1024 // tool result truncation (line-aware; 64K, aligned with main offload limit)
+const MAX_KEY_FILES_IN_COMPACTION = 5 // files named in the compaction summary
+
+/** Estimate token count from messages（B4——群 B 批 CLI §18.3：扁平 chars/4 改 `estimateText`
+ *  加权式——ASCII/4 + 非 ASCII/1；纯 ASCII 与旧式逐值相等；CJK 低估 ~3-4× 修正；
+ *  walker（content / tool_calls 两源）与计数口径零改）。 */
+export function estimateTokens(messages) {
+  return messages.reduce((sum, msg) => {
+    const content = typeof msg.content === "string" ? msg.content : JSON.stringify(msg.content || "")
+    const toolCalls = msg.tool_calls ? JSON.stringify(msg.tool_calls) : ""
+    return sum + estimateText(content + toolCalls)
+  }, 0)
+}
+
+/** Compact early messages when context grows too large — LOCAL trimming only
+ *  (no LLM summarization). MUTATES in place (splice) so the caller's array
+ *  reference stays valid — a reassignment would leave the caller's logging
+ *  (tool-call count, token estimate) reading a stale array. */
+export function compactMessages(messages, pinned = null) {
+  // Keep: system prompt, last 20 messages (≈ 10 assistant+tool exchanges),
+  // user message — the rest is summarized.
+  if (messages.length <= 20) return
+
+  const system = messages[0]
+  const recent = messages.slice(-20)
+  const old = messages.slice(1, -20)
+
+  // Count actual tool messages (old.length counts user/assistant rows too)
+  const toolCount = old.filter((m) => m.role === "tool").length
+  const keyFiles = old
+    .filter((m) => m.role === "tool")
+    .map((m) => m.content?.split("\n")[0]?.slice(0, 50)) // first line of tool results typically names the file that was read/grepped
+    .filter(Boolean)
+    .slice(0, MAX_KEY_FILES_IN_COMPACTION)
+  const filesPart = keyFiles.length > 0 ? ` Key files examined: ${keyFiles.join(", ")}` : ""
+  const summary = `Earlier exploration: ${toolCount} tool calls completed.${filesPart}`
+
+  // F13（第 11 批 §14.4 #3）：压缩丢掉的正是**首条 user 消息**（评审简报，含 token）——
+  // pinned 由评审参数构建（非模型输出），在本次压缩动作内作为一条 user 消息重挂（幂等可读：
+  // 重复压缩允许重复挂回，不做存在性判定）。
+  const pin = pinned ? [{ role: "user", content: pinned }] : []
+  messages.splice(0, messages.length,
+    system,
+    { role: "user", content: `[Context compacted] ${summary}` },
+    ...pin,
+    ...recent)
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 不完整判定族（A / F16 共用单谓词——§14.3；六 kind = 宿主尾族）
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** 宿主尾族六 kind 的块首行逐字前缀（§14.3 表）。变量段（token 数 / 秒数 / 工具轮数）
+ *  不入前缀——取各尾的固定字面部分；`review_failed` = run.mjs catch 的字符串 resolve
+ *  形态（不 throw），其余五条 = renderTimeline 尾（loop.mjs）。 */
+const ADVISOR_INCOMPLETE_PREFIXES = [
+  ["context_limit", "Advisor: context window limit"],
+  ["turn_cap", "Advisor: stopped after"],
+  ["timeout", "Advisor: review timeout"],
+  ["empty", "Advisor: empty response"],
+  ["interrupted", "Advisor: interrupted."],
+  ["review_failed", "Advisor: review failed"],
+]
+
+/** 单谓词（三消费点同源：design 结算 / code 完成守卫 / 报告提示）——**块首行扫描**（按空行
+ *  分块，逐块取首行 trim 后测前缀；时间线与尾以空行相接，六条尾均以块首行形态落地）。
+ *  负向精度（§14.3 修正轮）：引文中同串的**非块首形态**（围栏内行 / 表格行 / 引用行）不判
+ *  incomplete；块首裸行引用同串的残余误报方向安全（fail-closed——多付一轮重跑，如实登记）。
+ *  @returns {string|null} kind 或 null */
+export function advisorIncompleteMarker(text) {
+  for (const block of String(text ?? "").split(/\n\s*\n/)) {
+    const first = block.split("\n").find((l) => l.trim() !== "")
+    if (!first) continue
+    const line = first.trim()
+    for (const [kind, prefix] of ADVISOR_INCOMPLETE_PREFIXES) {
+      if (line.startsWith(prefix)) return kind
+    }
+  }
+  return null
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 预算提示 + 结构化超时尾（D / F15——§14.6 #2/#3）
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** 0.75 一次性预算提示判定（纯函数——阈值两侧可机测；每场评审至多一次）。 */
+export function shouldBudgetNudge(elapsedMs, budgetMs, nudged) {
+  return !nudged && Number.isFinite(budgetMs) && budgetMs > 0 && elapsedMs >= budgetMs * 0.75
+}
+
+/** 预算提示文案（逐字——§14.6 #2；由循环注入一条 user 消息）。 */
+export function budgetNudgeText(elapsedMs, budgetMs) {
+  const secs = (ms) => Math.round(ms / 100) / 10
+  const pct = Math.round((elapsedMs / budgetMs) * 100)
+  return `⏳ review budget: ~${pct}% consumed (${secs(elapsedMs)}s of ${secs(budgetMs)}s). Converge now: emit your findings table for the evidence you have verified, mark anything you could not verify explicitly as \`unverified\` (unverified evidence must not support a pass), and emit your verdict line.`
+}
+
+/** 结构化超时尾（§14.6 #3）：族前缀 `Advisor: review timeout after {S}s.` 逐字保持
+ *  （判定族字面依赖）；其后 = 机读统计（rounds / tool calls / review text produced）
+ *  + 可执行恢复指引（narrower scope / 调预算）。 */
+export function timeoutTail(timeoutMs, rounds, toolCalls, producedText) {
+  const s = Math.round(timeoutMs / 1000)
+  return [
+    `Advisor: review timeout after ${s}s. Review incomplete — the wall-clock budget was exhausted; partial findings (if any) are above.`,
+    `- rounds: ${rounds} · tool calls: ${toolCalls} · review text produced: ${producedText ? "yes" : "no"}`,
+    `- budget: ${s}s (agent.advisor.timeoutMs) — re-run with a narrower scope (split the review across fewer documents) or raise the budget.`,
+  ].join("\n")
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 评审文本装配（loop 的尾经此与时间线合流——与尾族同文件：生成 / 判定 / 装配单源）
+// ─────────────────────────────────────────────────────────────────────────────
+
+// The live "[thinking…]" wait indicator shares its exact text with the TUI
+// cleanup regex (agent-turn.mjs strips it before flushing to history) — keep
+// them in lockstep.
+export const ADVISOR_THINKING_PLACEHOLDER = "\n[thinking…]\n"
+
+/**
+ * Tool-call progress line summary delegates to the single source describeToolArgs
+ * (../tui/tool-args.mjs) — the same function main-agent tool blocks and subagent
+ * blocks use. 2026-08-31: replaced the local picker (action/path/pattern/command-only)
+ * so advisor progress lines show the quoted-path forms everywhere else.
+ */
+/**
+ * Render the ordered review timeline — thinking / tool progress / final text
+ * interleaved EXACTLY as emitted, so the persisted record shows the review
+ * process at its real positions. A summary appended at the end would lose the
+ * order (the user-visible "no tool calls in the advisor record" gap). The
+ * live "[thinking…]" placeholder is stripped (wait indicator, not content).
+ */
+export function renderTimeline(timeline, tail = "") {
+  const body = timeline
+    .map((b) => b.text.replaceAll(ADVISOR_THINKING_PLACEHOLDER, "").trim())
+    .filter(Boolean)
+    .join("\n\n")
+  return [body, tail].filter(Boolean).join("\n\n")
+}