@thincoder/core 0.9.1

package/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/advisor/citations.mjs

@@ -0,0 +1,139 @@
+/**
+ * citations.mjs — host-verified citation checking (decision d698434).
+ * Extracted from advisor/run.mjs (file-size split). The evidence rule becomes
+ * 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, 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
+// citations that fail as "file unreadable" in the verification report.
+// Single-letter extensions (c/h) are kept — false positives (e.g. "a.c:1: x")
+// are rare and only add a failed-citation line to the report; the report is
+// advisory for the parent agent, never a crash path.
+const CITATION_RE = /([\w./\\-]+\.(?:mjs|cjs|js|ts|jsx|tsx|mts|cts|py|rs|go|c|h|cpp|hpp|java|rb|php|sh|bash|json|md|markdown|mdx|yaml|yml|toml|css|html)):(\d+):\s*([^`\n]{4,})/g
+
+/** Extract `file:line: content` citations from a review text. */
+export function extractCitations(text) {
+  const out = []
+  for (const m of text.matchAll(CITATION_RE)) {
+    out.push({ file: m[1], line: Number(m[2]), content: m[3].trim() })
+  }
+  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, opts = {}) {
+  const citations = extractCitations(text)
+  const matched = []
+  const failed = []
+  const base = resolve(cwd)
+  const roots = citationRoots(cwd, opts?.scope)
+  for (const c of citations) {
+    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, 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)) {
+      lines.push(`- ${f.file}:${f.line}: ${f.content.slice(0, 80)}${f.reason ? ` (${f.reason})` : ""}`)
+    }
+  }
+  return text + lines.join("\n")
+}

package/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/advisor/convergence.mjs

@@ -0,0 +1,80 @@
+/**
+ * advisor/convergence.mjs — shared convergence-round message building (round 2+).
+ * SINGLE source for the round-2+ sections used by BOTH the normal advisor flow
+ * (buildAdvisorFollowUp) and the legacy path (buildAdvisorUserMessage) — fixes must
+ * not be replicated in two places. Lives in its own module to avoid the advisor-entry
+ * ↔ message-building import cycle.
+ */
+
+/**
+ * Shared convergence-round instructions — single source for BOTH paths
+ * (buildAdvisorUserMessage's legacy convergence block and
+ * buildAdvisorFollowUp), so the wording cannot diverge.
+ * Round 2 may flag obvious new issues; round 3+ is strict verification.
+ * @param {number} round — convergence round number (2+)
+ * @param {string[]|null} scopeFiles — optional file list for the no-response fallback
+ * @returns {string[]} the numbered instruction lines (callers spread them)
+ */
+export function buildConvergenceInstructions(round, scopeFiles = null) {
+  const fileList = scopeFiles?.length
+    ? ` The review surface is: ${scopeFiles.slice(0, 10).join(", ")}.`
+    : ""
+  return [
+    `1. IMPORTANT: verify EVERY item of the prior review output against the CURRENT FILE STATE with \`read\` — never decide based on earlier snapshots alone.${fileList}`,
+    "2. STALE-CONTEXT WARNING: any diff or file content from earlier messages is a historical snapshot — treat it as expired. Only fresh `read` results describe the current state.",
+    "3. You have no git tool; git output in earlier messages is historical and untrustworthy (committed fixes never show in a diff).",
+    "4. `read` the files named in the prior review output (or the review surface above) in full — ALWAYS. Batch reads/greps in a single reply.",
+    "5. Evidence rule: every 'Unfixed'/'New' finding MUST quote the exact line content from THIS round's `read` output (e.g. `run.mjs:180: timeoutId = setTimeout(...)`). Line numbers alone are NOT evidence — they may be stale or fabricated. Findings without a fresh quoted line are treated as unverified and will not be accepted.",
+    "6. Produce your verification table. Do not re-read content you already have.",
+    round === 2
+      ? "7. You may flag obvious NEW issues introduced by the fixes (crashes, data loss, logic errors — not style)."
+      : "7. Do NOT look for new issues.",
+  ]
+}
+
+/**
+ * Shared convergence body — SINGLE source for the round-2+ message sections
+ * (decision 2026-08-08): the FULL verbatim prior review output is the only
+ * complete verification list; the agent response table is a focus aid only.
+ * Used by buildAdvisorFollowUp (the normal flow) and the legacy path in
+ * messages.mjs (direct external callers of buildAdvisorUserMessage) — fixes
+ * must not be replicated in two places.
+ * @param {string} p — full prior review output (verbatim)
+ * @param {string} response — agent fix-claims table (or fallback text)
+ * @param {number} round — next round number (>= 2)
+ * @param {string[]|null} [scopeFiles] — review surface for instructions
+ * @returns {string} the convergence message
+ */
+export function buildConvergenceBody(p, response, round, scopeFiles) {
+  const label = round === 2 ? "Verify Prior Table + Flag New Issues" : "Strict Verification"
+  const reminder = round === 2
+    ? "verify every item in the prior review output and flag only obvious new issues introduced by the fixes"
+    : "strictly verify only the prior review output — do NOT look for new issues"
+  const parts = [
+    `## Round ${round} — ${label}`,
+    "",
+    `[System reminder: this is round ${round} of the convergence protocol. ` +
+      `The system prompt for this round has already narrowed the review scope — follow it: ${reminder}.]`,
+    "",
+    // Prior review output IS in the context (decision 2026-08-08): the FULL
+    // verbatim output of the last review — the only complete verification list.
+    // The agent response table covers only issues the agent chose to answer,
+    // so issues the agent skipped would silently escape convergence without
+    // the prior output. The model understands the review output directly —
+    // no table/header/phrase parsing. Restatement risk is handled
+    // mechanically: host-verified citations reject references that do not
+    // match the CURRENT disk state, and fresh sessions exclude old read data.
+    // The agent response table stays as a focus aid ("I fixed X"), not as the
+    // to-verify list.
+    "## Prior Review Output (verify every item it raises)",
+    p,
+    "",
+    "## Agent Response (fix claims — reference only)",
+    response,
+    "",
+    "## Instructions",
+    ...buildConvergenceInstructions(round, scopeFiles),
+    "",
+  ]
+  return parts.join("\n")
+}

package/advisor/history.mjs

@@ -0,0 +1,77 @@
+/**
+ * advisor/history.mjs — advisor history extraction: agent response table and conversation background.
+ */
+import { readFileSync } from "node:fs"
+import { join } from "node:path"
+
+export const ADVISOR_MD_PATH = ".thincoder/advisor.md"
+const AGENT_RESPONSE_HEADER = "| # | Action | Detail |"
+
+const DEFAULT_CRITERIA = `Review the code changes, focusing on:
+1. Correctness: logic errors, edge cases, off-by-one, incomplete modifications
+2. Security: unhandled exceptions, null references, resource leaks, race conditions
+3. Consistency: alignment with existing project patterns and conventions
+4. Completeness: missing callers, imports, or follow-up changes
+5. Maintainability: vague naming, missing comments, overly complex logic`
+
+/**
+ * Extract the agent's response table (| # | Action | Detail |) — the fix-claims
+ * reference for convergence rounds.
+ * Semantics (decision 2026-08-08): without sinceIdx, scan BACKWARD for the
+ * MOST RECENT response table (no prior-table index is carried anymore — the
+ * agent response is a focus aid only; format drift falls back to the
+ * no-response text and never drives control flow). With sinceIdx, scan
+ * FORWARD from it (legacy callers/tests).
+ * @param {Array} history — message history
+ * @param {number} [sinceIdx] — legacy: start scanning forward from this index
+ * @returns {string|null} the response table content, or null
+ */
+export function extractAgentResponseTable(history, sinceIdx) {
+  const entries = Array.isArray(history) ? history : []
+  if (sinceIdx !== undefined) {
+    for (let i = sinceIdx; i < entries.length; i++) {
+      const m = entries[i]
+      if (m.role !== "assistant" || typeof m.content !== "string") continue
+      if (m.content.includes(AGENT_RESPONSE_HEADER)) return m.content
+    }
+    return null
+  }
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const m = entries[i]
+    if (m.role !== "assistant" || typeof m.content !== "string") continue
+    if (m.content.includes(AGENT_RESPONSE_HEADER)) return m.content
+  }
+  return null
+}
+
+/**
+ * Load review criteria: project .thincoder/advisor.md if present,
+ * otherwise the built-in defaults.
+ */
+export function loadAdvisorMd(cwd) {
+  try {
+    return readFileSync(join(cwd, ADVISOR_MD_PATH), "utf8")
+  } catch {
+    return DEFAULT_CRITERIA
+  }
+}
+
+/** Extract recent user↔assistant exchanges (up to maxTurns) for intent context. */
+export function extractConversationBackground(history, maxTurns = 3) {
+  const entries = Array.isArray(history) ? history : []
+  const lines = []
+  let turns = 0
+  for (let i = entries.length - 1; i >= 0 && turns < maxTurns; i--) {
+    const m = entries[i]
+    if (m.role === "tool" || m.role === "system") continue
+    if (typeof m.content !== "string") continue
+    if (m.content.startsWith("[System reminder:") || m.content.startsWith("[System mode:") || m.content.startsWith("[Relevant memories")) continue
+    // ^ [System mode:] is not currently generated anywhere — kept as forward-looking
+    // defensive filtering in case convergence messages ever adopt a different prefix.
+    if (m.role === "user" || m.role === "assistant") {
+      lines.unshift(`${m.role === "user" ? "User" : "Assistant"}: ${m.content.slice(0, 400)}`)
+      if (m.role === "user") turns++
+    }
+  }
+  return lines.length > 0 ? lines.join("\n\n") : null
+}