thincoder 0.12.60 → 0.12.61

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")
+}

package/src/advisor/loop.mjs

@@ -0,0 +1,293 @@
+/**
+ * advisor/loop.mjs — advisor tool loop: chat → execute tools → repeat, plus the
+ * review timeline (split out of advisor/run.mjs, 第 11 批 — run.mjs was 498/500
+ * 硬帽；拆分保持既有 import 面：run.mjs 继续 re-export 本文件导出）。
+ *
+ * 第 11 批（F15/§14.6）：每次 chat 调用携带硬墙信号（`AbortSignal.any([signal,
+ * AbortSignal.timeout(remaining)])`；墙判定绑信号状态——抛错 / partial 两形态同判），
+ * 并按 0.75 一次性预算提示 + 结构化超时尾收尾；守卫与限额函数在 compaction.mjs。
+ */
+import { chat } from "../provider/core.mjs"
+import { providerSpec } from "../config.mjs"
+import { toOpenAISchema } from "../tools/index.mjs"
+import { describeToolArgs } from "../tui/tool-args.mjs"
+import { truncateAdvisorResult } from "./truncate.mjs"
+import { batchSegmentTool } from "../agent-tools/batch-segment.mjs"
+import {
+  estimateTokens, compactMessages, shouldBudgetNudge, budgetNudgeText, timeoutTail, renderTimeline,
+  MAX_ADVISOR_TURNS, advisorContextBudget, TOOL_TIMEOUT_MS, REVIEW_TIMEOUT_MS, MAX_RESULT_CHARS,
+  ADVISOR_THINKING_PLACEHOLDER,
+} from "./compaction.mjs"
+
+const { readTool, globTool, grepTool, lsTool } = await import("../tools/index.mjs")
+const { lspTool } = await import("../tools/lsp.mjs")
+const { codeSearchTool } = await import("../memory/code-sync.mjs")
+
+/**
+ * Advisor tool set — ZERO git, read-only ONLY, every round. The change surface
+ * comes from the review scope (paths / _touchedFiles injected by the caller),
+ * never from git: git output misled reviews (committed fixes never show in
+ * `git diff HEAD`, so "no changes" was read as "not fixed") and the user
+ * mandate is full decoupling (7d49a52 + d3be613). The reviewer reads files
+ * and searches code; it never touches git and never writes.
+ * No round parameter — the set is constant across all rounds.
+ * @param {Object} agent — only used for the code index (agent.memory); the
+ *   semantic code_search tool needs it. Without a memory, the set is 5 tools.
+ */
+function advisorToolsFor(agent, reviewType = "code", batchDoc = null) {
+  const search = agent?.memory ? codeSearchTool(agent.memory) : null
+  const tools = search
+    ? [readTool, globTool, grepTool, lsTool, lspTool, search]
+    : [readTool, globTool, grepTool, lsTool, lspTool]
+  // §2.20.3（第 4 批）：**只有绑定了批次档的设计评审**额外拿到写通道——代码评审工具集
+  // 逐字节不变（零 git + 只读不变量，§2.20.8 #1）；未绑定 → 不挂载（fail-closed）。
+  if (reviewType === "design" && batchDoc) tools.push(batchSegmentTool(batchDoc, { review: true }))
+  return { schemas: tools.map(toOpenAISchema), byName: new Map(tools.map((t) => [t.name, t])) }
+}
+// Test seam: the tool set is pure (agent.memory → code_search inclusion).
+export { advisorToolsFor, advisorToolsFor as _advisorToolsFor }
+
+/**
+ * Run the advisor's tool loop: chat → execute tools → repeat.
+ * Stops when the model produces text without tool calls.
+ *
+ * Progress lines (→ tool args) are emitted via onOutput between model bursts so
+ * the panel keeps moving while the advisor explores — otherwise the panel sits
+ * frozen through every tool-call phase and the review appears to have stalled.
+ *
+ * @param {string|null} [pinned] — 第 11 批：压缩定锚简报（评审参数构建——F13/§14.4 #3）。
+ * @param {{now?: Function, chat?: Function}} [seams] — 测试缝（默认 Date.now / chat——
+ *   生产调用不传，默认回退零行为变）。
+ */
+async function runAdvisorToolLoop(provider, messages, onOutput, signal, agent, cwd, toolsOverride = null, reviewType = "code", batchDoc = null, pinned = null, seams = {}) {
+  const now = seams.now ?? Date.now
+  const chatCall = seams.chat ?? chat
+  // 第 11 批硬墙 / 预算 / 尾：实现注解见下方各点；守卫函数与 renderTimeline 在 compaction.mjs。
+  // Kind-tagged wrappers: the TUI panel colors reasoning / answer / tool progress differently.
+  // Every chunk is ALSO recorded into an ordered timeline — the persisted record
+  // must show the review process (thinking ↔ tool progress ↔ final text) at its
+  // real positions, not a summary appended at the end. Same-kind consecutive
+  // chunks merge (token streams); kind flips start a new entry.
+  const timeline = []
+  const record = (kind, text) => {
+    const last = timeline.at(-1)
+    if (last && last.kind === kind) last.text += text
+    else timeline.push({ kind, text })
+  }
+  const emit = (kind) => (text) => { record(kind, text); onOutput?.({ kind, text }) }
+  const onThink = emit("think")
+  const onText = emit("text")
+  const onTool = emit("tool")
+  // toolsOverride = test seam (T-TS8/9): the real advisor tool set, or a mock
+  // set with controllable timing/errors.
+  const { schemas: toolSchemas, byName: toolByName } = toolsOverride ?? advisorToolsFor(agent, reviewType, batchDoc)
+  let turns = 0
+  let toolCallCount = 0
+  let reviewTextProduced = false
+  let budgetNudged = false
+  const startTime = now()
+  // 第 25 批（§16.3）：上下文预算跟随评审模型窗口——`providerSpec`（模型规格表 × provider 级
+  // context 覆盖）派生；函数体内、while 轮次外一次性（provider 全场不变），两档消费见下守卫。
+  const budget = advisorContextBudget(provider)
+
+  while (true) {
+    // Interrupted (Ctrl+I) — stop immediately instead of spinning a fresh uncancellable signal
+    if (signal?.aborted) return renderTimeline(timeline, "Advisor: interrupted.")
+    
+    // Check review timeout (10 minutes by default; agent.advisor.timeoutMs overrides)
+    // 运行时校验（设计评审 #1，2026-08-24）：手写 config.json 的非法值（0/负数/字符串）
+    // 不得静默禁用或立即触发超时——非法一律回退默认。
+    const cfg = agent.config?.advisor?.timeoutMs
+    const timeoutMs = (Number.isFinite(cfg) && cfg > 0) ? cfg : REVIEW_TIMEOUT_MS
+    const elapsed = now() - startTime
+    const remaining = timeoutMs - elapsed
+    // 硬墙（§14.6 #1）：预算用尽 → 结构化超时尾（首行 = 判定族 timeout 前缀）。
+    if (remaining <= 0) {
+      return renderTimeline(timeline, timeoutTail(timeoutMs, turns, toolCallCount, reviewTextProduced))
+    }
+    // 0.75 一次性预算提示（§14.6 #2——同一检查点、每场评审至多一次）：注入一条 user 消息
+    // 促模型在墙前收敛产出（不改语义判据、不碰提示词面）。
+    if (shouldBudgetNudge(elapsed, timeoutMs, budgetNudged)) {
+      budgetNudged = true
+      messages.push({ role: "user", content: budgetNudgeText(elapsed, timeoutMs) })
+    }
+    
+    if (++turns > MAX_ADVISOR_TURNS) {
+      return renderTimeline(timeline, "Advisor: stopped after " + MAX_ADVISOR_TURNS + " tool rounds — the review appears to be looping. You may retry with a narrower scope.")
+    }
+    
+    // Check context window and compact if needed
+    const currentTokens = estimateTokens(messages)
+    if (currentTokens > budget.compactAt) {
+      onText(`\n[Context compacted: ${currentTokens} tokens → reducing to fit window]\n`)
+      compactMessages(messages, pinned)
+      if (estimateTokens(messages) > budget.limit) {
+        // Report the POST-compaction count — the pre-compaction currentTokens
+        // is stale by the time compaction has run.
+        return renderTimeline(timeline, `Advisor: context window limit reached (${estimateTokens(messages)} tokens). Review incomplete — too many tool calls. Try a narrower scope.`)
+      }
+    }
+    
+    // LLM generation silence: the reasoning phase produces no SSE bytes for
+    // seconds to tens of seconds (server-side prefill on large contexts, per
+    // tool-round LLM return). A placeholder keeps the panel visibly working.
+    // kind "think" (NOT "text"): the placeholder must land in the SAME buffer
+    // and position as the upcoming reasoning — a "text"-kind placeholder
+    // rendered BELOW the think block, and the reasoning stream appeared ABOVE
+    // it ("the stream runs back to the front"). Same buffer = same spot; the
+    // reasoning continues right where the placeholder sits.
+    onOutput?.({ kind: "think", text: ADVISOR_THINKING_PLACEHOLDER })
+
+    // 硬墙（§14.6 #1）：单次请求信号 = 用户信号 × 本调用 deadline（remaining）。复合信号
+    // 无条件传入（上层检查与本调用之间的中止仍必须取消请求——已 aborted 的 composite 使请求
+    // 立即失败）；此处改正了原指向 provider/core.mjs 组合 AbortSignal 的陈旧注释（§14.10 #3）。
+    const callSignal = signal
+      ? AbortSignal.any([signal, AbortSignal.timeout(remaining)])
+      : AbortSignal.timeout(remaining)
+    let response
+    try {
+      response = await chatCall(provider, {
+        messages,
+        tools: toolSchemas,
+        signal: callSignal,
+        onToken: (t) => { if (String(t ?? "").trim()) reviewTextProduced = true; onText(t) },
+        onReasoning: onThink,
+        // LOGGING（vscode advisor/run.mjs parity——按 stage 可 grep）
+        // §18.6 D-TR4：轨迹元数据增补——kind=advisor（评审独立于子代理——T-TR2）；role
+        // 透出调用方角色（eng-coder 内嵌评审时为 "eng-coder"）；session/cwd 供轨迹对回；
+        // traces 开关沿 agent.config（D-TR6）。
+        logCtx: {
+          stage: "advisor",
+          role: agent?._role ?? null,
+          kind: "advisor",
+          session: agent?._sessionStart ?? null,
+          cwd,
+          traces: agent?.config?.traces?.enabled !== false,
+        },
+      })
+    } catch (e) {
+      // 墙判定绑信号状态（§14.6 #1——非异常名）：① 用户信号已中止 ⇒ 原样上抛（中断语义
+      // 零变）；② 复合信号已中止（墙触发）而用户信号未中止 ⇒ 结构化超时尾（形态①：抛错；
+      // AbortError / TimeoutError 两名兜底——AbortSignal.timeout 的 reason 是 TimeoutError
+      // DOMException）；③ 其余错误原样上抛（runAdvisorReview 的失败分类不变）。
+      if (signal?.aborted) throw e
+      if (callSignal.aborted || e?.name === "AbortError" || e?.name === "TimeoutError") {
+        return renderTimeline(timeline, timeoutTail(timeoutMs, turns, toolCallCount, reviewTextProduced))
+      }
+      throw e
+    }
+    if (signal?.aborted) return renderTimeline(timeline, "Advisor: interrupted.")
+    // 形态②（§14.6 #1）：不抛错而返回 partial（流已有内容时中断以 partial:true 透传）——
+    // 不得按普通结果收尾：墙触发（复合信号已中止）同判。
+    if (callSignal.aborted && response?.partial) {
+      return renderTimeline(timeline, timeoutTail(timeoutMs, turns, toolCallCount, reviewTextProduced))
+    }
+
+    // No tool calls — this is the final review text. The final answer was
+    // already streamed into the timeline via onText; fall back to
+    // response.content only if nothing was recorded.
+    if (!response.toolCalls?.length) {
+      if (!response.content?.trim()) return renderTimeline(timeline) || "Advisor: empty response — review was inconclusive"
+      return renderTimeline(timeline) || response.content.trim()
+    }
+
+    // Push assistant message with tool calls. reasoning_content ECHO is
+    // mandatory for reasoningEcho:"required" providers (deepseek/kimi): the
+    // server stops returning reasoning_content on later rounds when the
+    // tool-call assistant history lacks it — the observed "reasoning stops
+    // after the first tool call, returns only at the final answer" symptom.
+    // Mirrors the main agent's push (agent.mjs).
+    messages.push({
+      role: "assistant",
+      content: response.content || null,
+      tool_calls: response.toolCalls.map((tc) => ({
+        id: tc.id, type: "function",
+        function: { name: tc.name, arguments: tc.arguments },
+      })),
+      ...(response.reasoning && providerSpec(provider).reasoningEcho === "required"
+        ? { reasoning_content: response.reasoning }
+        : {}),
+    })
+
+    // B1 (AGENT-LOOP.md §18.7 D-TS7): the SAME LLM reply's multiple read-only
+    // tool calls run in PARALLEL (Promise.all) — results are backfilled in
+    // toolCalls order (Promise.all preserves the input order → tool_call_id
+    // never mismatches); each tool's timeout/error is captured independently
+    // (the existing TOOL_TIMEOUT stays — one failing tool does not block the
+    // others); progress lines are emitted in toolCalls order. The read-only
+    // tool set has no side effects — no sequencing/serialization needed.
+    // Scope note (round1 review #10): B1 is ONLY in-loop tool parallelism — it
+    // does NOT solve the TODO "platform execution: advisor parallel calls are
+    // actually serial" mystery (docs/TODO.md — LOGGING evidence item), which
+    // concerns multiple advisor CALLS observed as serial, not one reply's
+    // tool calls.
+    const parsed = response.toolCalls.map((tc) => {
+      const tool = toolByName.get(tc.name)
+      let args = {}
+      let parseError = null
+      try {
+        args = JSON.parse(tc.arguments || "{}")
+      } catch (e) {
+        parseError = `Error: invalid JSON in tool arguments: ${e.message}\nRaw arguments: ${(tc.arguments || "").slice(0, 200)}`
+      }
+      return { tc, tool, args, parseError }
+    })
+    toolCallCount += parsed.length
+    // Progress lines first, in toolCalls order (emitted before the parallel
+    // run — display order is independent of completion order).
+    for (const p of parsed) {
+      if (p.parseError) continue // parse-error tools get no progress line (legacy behavior)
+      const argsLine = describeToolArgs(p.tc.name, p.args)
+      onTool(`\n→ ${p.tc.name}${argsLine ? " " + argsLine : ""}\n`)
+    }
+    // Every tool runs CONCURRENTLY; each result/error lands in its own slot —
+    // Promise.all preserves input order, so index i always matches parsed[i].
+    const executed = await Promise.all(parsed.map(async (p) => {
+      // Parse failure → error to model immediately (no execution)
+      if (p.parseError) return p.parseError
+      if (!p.tool) return `Error: unknown tool "${p.tc.name}". Available: ${[...toolByName.keys()].join(", ")}`
+      // Execute with timeout (clear the timer when the tool wins the race —
+      // otherwise up to MAX_ADVISOR_TURNS dangling timers accumulate)
+      try {
+        let timeoutId
+        const timeoutPromise = new Promise((_, reject) => {
+          timeoutId = setTimeout(() => reject(new Error(`tool timeout after ${TOOL_TIMEOUT_MS}ms`)), TOOL_TIMEOUT_MS)
+        })
+        let toolPromise
+        try {
+          toolPromise = p.tool.execute(p.args, { cwd, agent, onOutput, signal })
+          return await Promise.race([toolPromise, timeoutPromise])
+        } finally {
+          clearTimeout(timeoutId)
+          // Timeout won → toolPromise is still pending; a later rejection
+          // would surface as an unhandled rejection. The race already
+          // consumed the result/error in the normal path, so this no-op
+          // catch only fires for the abandoned-tool case.
+          toolPromise?.catch(() => {})
+        }
+      } catch (e) {
+        const errorType = e.message.includes("timeout") ? "timeout"
+          : e.message.includes("ENOENT") ? "file_not_found"
+          : e.message.includes("permission") ? "permission_denied"
+          : "execution_error"
+        return `Error (${errorType}): ${e.message}`
+      }
+    }))
+
+    // Backfill in toolCalls order (executed[i] ↔ parsed[i]); per-result
+    // non-string serialization + dual-end line-aware truncation stay per-tool
+    // (DUAL-END-TRUNCATION F-2 — truncate.mjs: head ≈60% + tail ≈40% — keep the
+    // tail verdicts; ≤ MAX_RESULT_CHARS results pass through untouched).
+    for (let i = 0; i < parsed.length; i++) {
+      let result = executed[i]
+      if (typeof result !== "string") result = JSON.stringify(result)
+
+      result = truncateAdvisorResult(result, MAX_RESULT_CHARS)
+
+      messages.push({ role: "tool", tool_call_id: parsed[i].tc.id, content: result })
+    }
+  }
+}
+// Test seam (T-TS8/9): the tool loop itself — toolsOverride injects a mock tool
+// set with controllable timing/errors (the real set comes from advisorToolsFor).
+export { runAdvisorToolLoop, runAdvisorToolLoop as _runAdvisorToolLoop }