@thincoder/core 0.9.1

package/advisor/run.mjs

@@ -0,0 +1,190 @@
+/**
+ * advisor/run.mjs — advisor execution: provider resolution and the review entry
+ * point. Message building lives in advisor.mjs; the tool loop lives in loop.mjs
+ * and the context/limit/tail guards in compaction.mjs（第 11 批硬帽拆分——
+ * run.mjs 原 498/500；既有 import 面经 re-export 保持不变）。
+ */
+import { findProvider } from "../config.mjs"
+import { prepareAdvisorMessages } from "../advisor.mjs"
+import { buildObjectDeclarationBlock, buildDesignApprovalBlock } from "./messages.mjs"
+import { appendCitationReport } from "./citations.mjs"
+import { runAdvisorToolLoop } from "./loop.mjs"
+import { advisorIncompleteMarker, estimateTokens } from "./compaction.mjs"
+import { batchDocForReview } from "../agent-tools/batch-segment.mjs"
+
+// 拆分后 import 面（既有导出名逐一保面——re-export；谓词为本批新增）。
+export { ADVISOR_THINKING_PLACEHOLDER, MAX_RESULT_CHARS, renderTimeline as _renderTimeline } from "./compaction.mjs"
+export { advisorToolsFor, advisorToolsFor as _advisorToolsFor } from "./loop.mjs"
+export { runAdvisorToolLoop as _runAdvisorToolLoop } from "./loop.mjs"
+export { advisorIncompleteMarker } from "./compaction.mjs"
+
+/** B 启动拒绝前缀（§14.4 #2）——稳定契约单源（三消费点同串）：run.mjs 生成；同步工具面
+ *  据此登记 `_advisorRefusals`；异步结算面据此不置 `_calledAdvisorThisRun`。 */
+export const ADVISOR_LAUNCH_REFUSAL_PREFIX = "Advisor: design review launch refused"
+
+/** Resolve the advisor's provider: cfg.provider/model when set, otherwise the main agent's provider */
+export function resolveAdvisorProvider(agent) {
+  const cfg = agent.config?.advisor
+  if (cfg?.provider) {
+    try {
+      // F-1 (ISSUE-FIX-BATCH): children carry no agent.providers (spawn childConfig copies the
+      // parent config) — fall back to config.providersList (.length: [] must not skip the list).
+      const provider = findProvider(agent.providers?.length ? agent.providers : agent.config?.providersList ?? [agent.provider], cfg.provider)
+      // F-2a (MODEL-400-FIX)：无 cfg.model 时渠道克隆须重派生 model——渠道裸克隆会丢 model 键
+      // → 无 model 请求 → serde 400。
+      // MODEL-SELECTION v2（M3④）：无 cfg.model → 命中渠道自己的默认模型（`provider.model`
+      // 单值）；渠道无默认模型 → 父 provider 兜底（与 subagent F-2c 同构）——绝不产出静默
+      // undefined-model 请求（最极端两者皆无 → chat 前 assertProviderModel fail-fast）。
+      const result = cfg.model ? { ...provider, model: cfg.model } : { ...provider, model: provider.model ?? agent.provider?.model }
+      if (cfg.thinking === null || cfg.thinking === false) result.thinking = undefined  // explicitly off
+      else if (cfg.thinking !== undefined) result.thinking = cfg.thinking
+      if (cfg.reasoningEffort !== undefined) result.reasoningEffort = cfg.reasoningEffort
+      return result
+    } catch (e) {
+      // Provider not found or lookup failed — fall back to main provider, but surface the reason
+      console.warn(`[advisor] resolveAdvisorProvider: ${e.message}`)
+    }
+  }
+  const provider = { ...agent.provider }
+  if (cfg?.model) provider.model = cfg.model
+  // thinking off: null AND false both mean "explicitly off" — a raw `false`
+  // value is invalid for providers that expect undefined or an object.
+  if (cfg?.thinking === null || cfg?.thinking === false) provider.thinking = undefined
+  else if (cfg?.thinking !== undefined) provider.thinking = cfg.thinking
+  if (cfg?.reasoningEffort !== undefined) provider.reasoningEffort = cfg.reasoningEffort
+  return provider
+}
+
+/** Review-looking guard (async settle parity): a markdown table row or ≥200 chars of prose counts as a prior. */
+export function looksLikeReviewOutput(text) {
+  const trimmed = String(text ?? "").trim()
+  return /\|.*\|.*\|/.test(trimmed) || trimmed.length >= 200
+}
+
+/**
+ * 压缩定锚简报（F13/§14.4 #3）——**由评审参数构建**（非模型输出）：对象声明 / 文档清单 /
+ * Approval Signal 三锚；重内容（项目指南 / 方法论 / 文档地图）不入 pin（压缩的意义所在）。
+ * 形态逐字见设计 §14.4 #3（首行为机械化重挂说明）。
+ */
+function buildPinnedBrief(reviewType, documents, object, designToken, designId) {
+  const docList = Array.isArray(documents) ? documents.filter((d) => typeof d === "string" && d.trim()) : []
+  const parts = ["[review brief — re-attached after context compaction; the original review request is no longer in the context]"]
+  const declaration = buildObjectDeclarationBlock(object)
+  if (declaration) parts.push(declaration.trimEnd())
+  if (docList.length > 0) {
+    parts.push("## Documents to Review")
+    parts.push(docList.map((d) => `- ${d} — Read this file in full`).join("\n"))
+  }
+  if (reviewType === "design" && designToken) parts.push(buildDesignApprovalBlock(designToken, designId))
+  return parts.join("\n\n")
+}
+
+/**
+ * Run an advisor review. reviewType: "code" or "design" (the top-level type is validated at the tool gate — F30; this entry point consumes the already-decided value). Returns review text or null when skipped.
+ * @param {string|null} [designToken] — injected into the design-review prompt; the advisor echoes it only on approval.
+ * @param {string[]|null} [documents] — design review only: explicit list of doc paths to review; passed through to the message builder.
+ * @param {string[]|null} [paths] — code review only: explicit list of file/dir paths to review.
+ * @param {Object|null} [object] — review-object declaration (§18.8 D-OA1/D-OA3): { type, target, status, reason, exclude }; absent → legacy behavior (no injection).
+ * @param {string|null} [designId] — §29.1 F2a: injected next to the design token in
+ *   the Approval Signal (passed through to the message builders).
+ */
+export async function runAdvisorReview(agent, reviewType, callbacks, designToken = null, documents = null, paths = null, object = null, designId = null) {
+  const onOutput = callbacks?.onOutput
+  const signal = callbacks?.signal
+  const startTime = Date.now()
+
+  // Advisor reviews are ALWAYS available (2026-08-21 semantic refactor): the
+  // former advisor.enabled gate is removed — review capability has no off
+  // switch; only the guard (completion pushback) is opt-in via advisor.guard.
+
+  // 撤 cap / 撤计数据（2026-09-18 用户裁定——ADVISOR-CONVERGENCE.md §3.1）：本执行体**无任何按计数
+  // 拒发预检**（原 cap 内防线 + 同 doc-set 连败停止内防线整体退场；轮次仅作提示词衰减与显示）。
+  // 失败路径的出口 = 失败结论块（`advisor-settle.mjs` 结算出口，两轨共用——ADVISOR-GUARDS.md §7）。
+  const provider = resolveAdvisorProvider(agent)
+  // Advisor always works in the agent's cwd — scope is defined by paths/documents.
+  const advisorCwd = agent.cwd
+
+  const messages = prepareAdvisorMessages(agent, reviewType, designToken, documents, paths, null, object, designId)
+
+  // B 启动断言（fail-closed——§14.4 #2）：设计评审请求内**必须**携带与本次签发 token 精确
+  // 对应的 Approval Signal——构建面补不上就拒绝启动（不发"请回显一个不存在的 token"的请求）。
+  // 拒绝报告前缀 `Advisor: design review launch refused` = 稳定契约（同步工具面据此登记
+  // _advisorRefusals；异步结算面据此不置 _calledAdvisorThisRun）。工具路径恒签发 token ⇒
+  // 该拒绝为直接调用方兜底（防御纵深——正常链不可达，如实注）。
+  if (reviewType === "design") {
+    const missing = !designToken
+      ? "no design token was minted"
+      : (messages.some((m) => m.role === "user" && String(m.content ?? "").includes(`[DESIGN-TOKEN:${designToken}`))
+        ? null
+        : "the request does not carry the approval signal")
+    if (missing) {
+      return `${ADVISOR_LAUNCH_REFUSAL_PREFIX} — ${missing}. Nothing was sent: a request that asks the reviewer to echo a token it cannot see would break the credential chain. Re-run advisor(type='design') to mint a fresh token.`
+    }
+  }
+
+  // §2.20.3 批次档写通道的绑定（仅设计评审）：同步路径 = 调用方（advisor 工具）传入的
+  // callbacks.batchDoc（即 resolved.run 的实例绑定）；异步路径 = 本实例在跑池条目的
+  // run.batchDoc（同文档集实例键——各评审各取各档，不用单值会话态）。
+  const boundBatchDoc = reviewType === "design" ? batchDocForReview(agent, documents, callbacks) : null
+  // F13/§14.4 #3：压缩定锚简报（评审参数构建——压缩触发时由 compaction 重挂）。
+  const pinned = buildPinnedBrief(reviewType, documents, object, designToken, designId)
+
+  try {
+    const result = await runAdvisorToolLoop(provider, messages, onOutput, signal, agent, advisorCwd, null, reviewType, boundBatchDoc, pinned)
+
+    // Host-verified citations (decision d698434): mechanically check every
+    // `file:line: content` reference in the review against the CURRENT file
+    // state. LLMs cannot self-enforce the evidence rule — the model may quote
+    // the prior table instead of re-reading (three consecutive false reports
+    // cited pre-fix line content). Unverified citations must not support a
+    // push-back; the parent agent sees the verification report.
+    // F14/§14.5：解析候选 = cwd + 评审对象声明范围派生根（scope = documents + paths）。
+    let final = result
+    if (!result.trimStart().startsWith("Advisor:")) {
+      final = appendCitationReport(result, advisorCwd, { scope: [...(documents ?? []), ...(paths ?? [])] })
+      // Success path: keep the FULL review output for convergence rounds —
+      // round 2+ injects this verbatim and the model understands it (decision
+      // 2026-08-08: prior-table hard parsing removed; no phrase/header matching).
+      // Guard: only store outputs that actually carry a review — a markdown
+      // table row (`| a | b | c |`) or substantial prose (>200 chars). An
+      // empty or tool-progress-only reply must not become the "prior review"
+      // of round 2+.
+      const looksLikeReview = looksLikeReviewOutput(final)
+      if (looksLikeReview) {
+        agent._lastAdvisorOutput = final
+      }
+    }
+
+    // Log review statistics for observability
+    const elapsed = Math.round((Date.now() - startTime) / 1000)
+    const toolCallCount = messages.filter((m) => m.role === "tool").length
+    const tokensUsed = estimateTokens(messages)
+    onOutput?.({
+      kind: "text",
+      text: `\n[advisor] Review completed: ${elapsed}s, ${toolCallCount} tool calls, ~${Math.round(tokensUsed / 1000)}k tokens\n`,
+    })
+    return final
+  } catch (e) {
+    if (e.name === "AbortError" && signal?.reason?.interrupt) throw e
+    
+    // 细化错误类型
+    const errorType = e.message.includes("rate limit") || e.message.includes("429") ? "rate limit"
+      : e.message.includes("timeout") ? "timeout"
+      : e.message.includes("network") || e.message.includes("ECONNREFUSED") ? "network"
+      : e.message.includes("context length") ? "context_too_long"
+      : "unknown"
+    
+    const retryAdvice = errorType === "rate limit"
+      ? "Wait a moment and retry. Consider using a cheaper model for advisor."
+      : errorType === "timeout"
+        ? "The model took too long. Try with a narrower scope."
+        : errorType === "context_too_long"
+          ? "Reduce the scope (fewer files/paths) or use a model with larger context window."
+          : "You may retry or proceed to verify manually."
+    
+    return `Advisor: review failed (${errorType}) — ${e.message || "unknown error"}. ${retryAdvice}`
+  }
+}
+// Host-verified citations — moved to citations.mjs (kept re-exported here for
+// import compatibility: tests and callers import from run.mjs).
+export { extractCitations, verifyCitations, appendCitationReport } from "./citations.mjs"

package/advisor/truncate.mjs

@@ -0,0 +1,57 @@
+/**
+ * truncate.mjs — advisor 工具结果的行感知双端截断（DUAL-END-TRUNCATION F-2，
+ * thincoder-cli/docs/design/_archive/DUAL-END-TRUNCATION.md，2026-09-09）。
+ *
+ * 原 run.mjs 内联截断为纯头向（line-aware 从首行累加至 64K break）——评审尾部
+ * 结论/裁决被切。现改头尾双保：头行累加至预算 ~60% → 中段省略注 → 尾行累加至
+ * 剩余 ~40%（保尾结论——与 read 工具 C 方案 / offload 双端预览同构的
+ * "头+尾保留、中段截断"策略——共享设计语言、分别实现）。
+ *
+ * 纯函数无导入：maxChars 由调用方传入（run.mjs 传 MAX_RESULT_CHARS）。
+ */
+
+/** advisor 截断头占比——头行累加至此份额后切中段，尾自动取剩余预算（设计 §4 ≈0.6）。 */
+export const ADVISOR_HEAD_RATIO = 0.6
+
+/** 尾部预算预留（字符）：中段省略注 + offset 续读提示的保守预留——注的位数只减不增
+ *  （middle ≤ totalChars——超大结果位数可达 ~10 位——200 字符仍宽松覆盖注+提示 ≤ ~140；
+ *  差额留给尾行）。 */
+const NOTE_RESERVE_CHARS = 200
+
+/**
+ * 行感知双端截断：result > maxChars → 头 + `… (truncated: K more lines, TOTAL chars
+ * total)` + 尾 + offset 续读提示；≤ maxChars 原样返回（无假截断注）。K = 头尾之间
+ * 的中段行数——头(≤60%) + 尾(≤余预算) 均行级累加、绝不半行切开；中段存在时 K ≥ 1
+ * （防御：K ≤ 0 时静默返回头尾拼合——不谎报截断）。
+ */
+export function truncateAdvisorResult(result, maxChars) {
+  if (result.length <= maxChars) return result
+  const totalChars = result.length
+  const lines = result.split("\n")
+  const headBudget = Math.floor(maxChars * ADVISOR_HEAD_RATIO)
+  let head = ""
+  let headLines = 0
+  let chars = 0
+  while (headLines < lines.length && chars + lines[headLines].length + 1 <= headBudget) {
+    chars += lines[headLines].length + 1
+    head += lines[headLines] + "\n"
+    headLines++
+  }
+  const tailBudget = Math.max(0, maxChars - chars - NOTE_RESERVE_CHARS)
+  let tail = ""
+  let tailChars = 0
+  let tailStart = lines.length
+  while (tailStart > headLines && tailChars + lines[tailStart - 1].length + 1 <= tailBudget) {
+    tailChars += lines[tailStart - 1].length + 1
+    tailStart--
+    tail = lines[tailStart] + "\n" + tail
+  }
+  const middle = tailStart - headLines
+  if (middle <= 0) return head + tail // 头尾已覆盖全部行——绝不产生假截断注
+  return (
+    head +
+    `\n… (truncated: ${middle} more lines, ${totalChars} chars total)\n` +
+    tail +
+    `To see more content, use: read(path, offset=${headLines + 1}, limit=200)`
+  )
+}

package/advisor.mjs

@@ -0,0 +1,281 @@
+/**
+ * advisor.mjs — advisor system-prompt selection, follow-up building, session assembly.
+ * User-message building lives in advisor/messages.mjs; execution (tool loop, provider
+ * resolution, review entry) in advisor/run.mjs; history extraction in advisor/history.mjs.
+ * Path classification (code / doc / temp) and the project declaration surface live in
+ * ../conventions.mjs — the single authority every gate consumes (repos.mjs included).
+ *
+ * The advisor runs as a read-only exploration sub-agent with tools
+ * (read, glob, grep, ls, lsp, code_search) — ZERO git, every round. The change
+ * surface comes from the review scope (paths / _touchedFiles), never from git;
+ * verification is `read`-only with quoted-line evidence (7d49a52, d3be613).
+ *
+ * Config:
+ *   { advisor: { enabled: true, provider: "deepseek", model: "deepseek-chat" } }
+ *   provider + model are optional — defaults to the main agent's provider/model.
+ *
+ * Convergence protocol:
+ *   Round 1: full review → produces a numbered issue table.
+ *   Agent responds with a response table per issue (fix claims).
+ *   Round 2: semi-convergence — verifies the prior table + can flag obvious new issues.
+ *   Round 3+: strict convergence — only checks the prior issue table.
+ *   The prior issue table IS injected into rounds 2+ (decision 2026-08-05,
+ *   reversed) — it is the ONLY complete verification list: the agent response
+ *   table covers only issues the agent chose to answer, so skipped issues would
+ *   silently escape convergence without it. The fix-claim table travels as a
+ *   focus reference only. 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.
+ *   Each round replaces the system prompt (ROUND1 → ROUND2 → ROUND3) so the
+ *   round-1 full-scope mandate can't bleed into later rounds. Rounds have NO
+ *   mechanical cap (2026-09-18 ruling — ADVISOR-CONVERGENCE.md §3.1): the round
+ *   counter only drives prompt decay and display; failure paths end in a
+ *   settlement conclusion block, and repeated failures are reported to the user.
+ *   Rounds 2+ also declare all earlier diffs STALE and require read-verified
+ *   file:line evidence for any unfixed/new finding — see docs/design/ADVISOR-CONVERGENCE.md.
+ *
+ * Session memory (agent._advisorSession):
+ *   RETAINED for initialization compatibility but NEVER read (decision d698434):
+ *   every review round builds a fresh [system, user] session — round 2+ must not
+ *   reuse round 1's messages, because the old read outputs are the anchoring
+ *   source of re-review false reports and a token sink. Convergence data (prior
+ *   issue table + agent response table) travels via buildAdvisorFollowUp.
+ *   The field is reset by runAgent; the write sites are harmless leftovers.
+ *
+ * Project customisation: .thincoder/advisor.md in the project root.
+ */
+import { extractAgentResponseTable } from "./advisor/history.mjs"
+import { buildAdvisorUserMessage, resolveScopeFiles, buildObjectDeclarationBlock, buildDesignApprovalBlock } from "./advisor/messages.mjs"
+import { buildConvergenceBody } from "./advisor/convergence.mjs"
+import { escapeLiteralEscapes } from "./escape.mjs"
+import { applyPromptInjections, loadAdvisorPrompt } from "./prompt-files.mjs"
+// Re-export for run.mjs and tests (keeps their imports from "../advisor.mjs" stable)
+export { ADVISOR_MD_PATH, extractAgentResponseTable, extractConversationBackground } from "./advisor/history.mjs"
+export { buildAdvisorUserMessage } from "./advisor/messages.mjs"
+export { buildObjectDeclarationBlock, buildDesignApprovalBlock } from "./advisor/messages.mjs"
+
+// ────────────────────────────────────────
+// Prompt files — loaded at module init
+// ────────────────────────────────────────
+// U2 核内笔（CORE-UNIFICATION §2.6.3（六））：私持 `loadPrompt`/自持路径运算已删——四常量
+// 改经核内单一解析面 `loadAdvisorPrompt`（契约 8 / D-C13）；缺档语义不变 = 抛错（契约 9）。
+
+const ADVISOR_ROUND1 = loadAdvisorPrompt("advisor-round1.md")
+// ROUND2/3 are used whenever a convergence round (round 2+) is being built:
+// in-run session continuation replaces the system prompt with them, and a
+// rebuilt fresh session (e.g. after a failed review) also selects them via
+// buildAdvisorSystemPrompt when _advisorRound > 0.
+const ADVISOR_ROUND2 = loadAdvisorPrompt("advisor-round2.md")
+const ADVISOR_ROUND3 = loadAdvisorPrompt("advisor-round3.md")
+// Design-review prompt — hard-loaded like the round prompts (decision
+// 2026-08-21): a missing file means a broken installation, and silently
+// degrading to a lesser in-code prompt would quietly strip the approval-signal
+// and citation rules, disabling design approval entirely. loadAdvisorPrompt throws.
+const ADVISOR_DESIGN = loadAdvisorPrompt("advisor-design.md")
+
+// ────────────────────────────────────────
+// System prompt building
+// ────────────────────────────────────────
+
+/**
+/** Build the system prompt for an advisor review session.
+ * @param {Object} agent — the parent agent
+ * @param {Object|null} [prior] — prior review output (full text; decision 2026-08-08)
+ * @param {string} [reviewType] — "design" for design review, undefined/"code" for code review
+ * @returns {string} the system prompt
+ */
+
+// 锚替换缝（CORE-UNIFICATION §2.13.8——U0）：本函数**六个 return 逐条**经 `applyPromptInjections`
+// （未配置 = 恒等，现行行为零变）；读取径（模块级常量缓存）不动。结构机检
+// （`test/prompt-injections.test.mjs`）按 return 分支逐条守——新增分支未挂即红。
+export function buildAdvisorSystemPrompt(agent, prior, reviewType) {
+  // Round decision is DETERMINISTIC (decision 2026-08-08): _advisorRound > 0
+  // with a stored review output means convergence (round 2+); 0 means round 1.
+  // No prior-table parsing, no all-clear phrase matching — the round counter
+  // and the stored output are the only inputs. A restarted process has
+  // _advisorRound 0 → conservative full re-review.
+  const hasPrior = (agent._advisorRound || 0) > 0 && (prior ?? agent._lastAdvisorOutput)
+  // Design review: round 1 uses the dedicated design-review prompt (full scope +
+  // approval token); rounds 2+ converge like code reviews (verify agent fix claims).
+  if (reviewType === "design") {
+    if (!hasPrior) {
+      return applyPromptInjections(ADVISOR_DESIGN)
+    }
+    const round = (agent._advisorRound || 0) + 1
+    if (round === 2) return applyPromptInjections(ADVISOR_ROUND2)
+    return applyPromptInjections(ADVISOR_ROUND3)
+  }
+  if (!hasPrior) return applyPromptInjections(ADVISOR_ROUND1)
+  const round = (agent._advisorRound || 0) + 1
+  if (round === 2) return applyPromptInjections(ADVISOR_ROUND2)
+  return applyPromptInjections(ADVISOR_ROUND3)
+}
+
+// ────────────────────────────────────────
+// Follow-up building (round 2+)
+// ────────────────────────────────────────
+
+/**
+ * Build a follow-up user message for round 2+ — the agent's response table +
+ * round-aware instructions, without re-sending the full round-1 context.
+ * Deliberately NO git information injected (no diff snapshot, no git context):
+ * git output misled re-reviews — committed fixes never show in `git diff HEAD`,
+ * so the model read "no changes" as "no fixes". Verification is `read`-only.
+ * NOTE: the caller (prepareAdvisorMessages) applies escapeLiteralEscapes to
+ * the return value — direct callers must do the same (the prior table and
+ * agent response can quote literal "\x"/"\u" sequences).
+ * @param {Object} agent — the parent agent (history used for the response table)
+ * @param {Object|null} prior — prior issue table (extracted from history when null)
+ * @param {string[]|null} [scopeFiles] — review surface for the no-response fallback (cwd-relative)
+ * @param {Object|null} [object] — review-object declaration (§18.8): mechanically
+ *   prepended to the round-2+ follow-up so every round stays anchored (T-OA2).
+ * @returns {string} the follow-up user message — or a plain "System reminder: …"
+ *   fresh-review fallback (NO brackets — some OpenAI-compatible servers parse
+ *   '['-prefixed content as structured data / expand escapes) when no prior
+ *   review exists at all (caller misuse; the response-table extraction would
+ *   otherwise scan history from index 0 and could match an unrelated stale table)
+ */
+export function buildAdvisorFollowUp(agent, prior, scopeFiles = null, object = null) {
+  // Convergence follow-up REQUIRES a prior review record — the full output of
+  // the last review, injected VERBATIM (decision 2026-08-08: the model
+  // understands the review output; no table/header/phrase parsing). The caller
+  // usually passes it; fall back to the stored agent._lastAdvisorOutput.
+  const p = prior ?? agent._lastAdvisorOutput
+  if (!p) {
+    // Plain "System reminder:" prefix (no brackets) — same convention as the
+    // round-1 path (some OpenAI-compatible servers parse '['-prefixed content
+    // as structured data / expand escapes; see prepareAdvisorMessages).
+    return "System reminder: convergence follow-up requested without a prior review — perform a fresh full review."
+  }
+  // Convergence semantics require round >= 2 (round 1 is the full review, not
+  // verification). A direct caller with _advisorRound 0 would otherwise get a
+  // meaningless "Round 1 — Strict Verification".
+  if ((agent._advisorRound || 0) < 1) {
+    return "System reminder: convergence follow-up requested at round 1 — a full review is already in progress; no prior verification exists yet."
+  }
+  const noResponseFallback = scopeFiles?.length
+    ? "(Agent did not provide a response table — perform a fresh review of: " + scopeFiles.slice(0, 10).join(", ") + ")"
+    : "(Agent did not provide a response table — perform a fresh full review; the review surface is unknown, ask the user for the file list)"
+  const response = extractAgentResponseTable(agent.history) || noResponseFallback
+  const round = (agent._advisorRound || 0) + 1
+  // Review-object declaration FIRST (T-OA2 — round 2+ stays anchored, no re-archaeology).
+  const declaration = buildObjectDeclarationBlock(object)
+  return (declaration ? declaration + "\n" : "") + buildConvergenceBody(p, response, round, scopeFiles)
+}
+
+/**
+ * Resolve the review surface for the convergence fallback — moved to
+ * messages.mjs so the legacy path shares it (see there).
+ */
+
+// escapeLiteralEscapes 已抽到 ./escape.mjs（advisor 与主 agent 发送路径共用），
+// 这里 re-export 保持既有 import 稳定。
+export { escapeLiteralEscapes }
+
+
+/**
+ * Build the advisor conversation for this run.
+ * EVERY call builds a fresh [system, user] session (decision d698434) — no
+ * session reuse across rounds: round 1 = full scope (ROUND1 prompt), rounds
+ * 2+ = convergence (ROUND2/ROUND3 prompt + fix-claims follow-up).
+ * @param {Object} agent — the parent agent
+ * @param {string} [reviewType] — "design" or "code" (已由工具层类型门定轨——此处无缺省；F30)
+ * @param {string|null} [designToken] — design-review approval token (design only)
+ * @param {string[]|null} [documents] — design review only: explicit list of doc paths to review (passed through to buildAdvisorUserMessage)
+ * @param {string[]|null} [paths] — code review only: explicit list of file/dir paths to review
+ * @param {Object|null} [object] — review-object declaration (§18.8 D-OA1): passed through
+ *   to the user-message builders; mechanically injected at the start of every review
+ *   round (round 1 design/code + round 2+ follow-up). Absent → legacy behavior.
+ * @param {string|null} [designId] — §29.1 F2a: injected next to the design token in
+ *   the Approval Signal (round 1 + round 2+ — both values, verbatim anchor).
+ */
+export function prepareAdvisorMessages(agent, reviewType, designToken = null, documents = null, paths = null, priorParam = null, object = null, designId = null) {
+  // Deterministic convergence state (decision 2026-08-08): round 2+ requires
+  // _advisorRound > 0 AND a stored prior review output. No history parsing.
+  // priorParam (direct callers) wins over the stored output — same derivation
+  // as buildAdvisorSystemPrompt (single source of truth for round semantics).
+  const prior = (agent._advisorRound || 0) > 0 ? (priorParam ?? agent._lastAdvisorOutput) : null
+
+  // Design review round 1: the dedicated full-scope review with the approval
+  // token (an independent gate — it runs even when a prior review exists, e.g.
+  // after a failed design review). Fresh session.
+  if (reviewType === "design" && (agent._advisorRound || 0) === 0) {
+    return [
+      { role: "system", content: buildAdvisorSystemPrompt(agent, prior, reviewType) },
+      { role: "user", content: escapeLiteralEscapes(buildAdvisorUserMessage(agent, prior, reviewType, designToken, documents, paths, object, designId)) },
+    ]
+  }
+
+  // Every round is a FRESH session (decision d698434): round 2+ must NOT reuse
+  // round 1's messages — the old read outputs are the top anchoring source of
+  // re-review false reports (the model quoted pre-fix file content instead of
+  // re-reading) and a token sink. The agent response table (fix claims) is
+  // injected through buildAdvisorFollowUp instead; the system prompt carries
+  // the round (ROUND2/ROUND3) via buildAdvisorSystemPrompt.
+  // No prior review output: reset ONLY when this run made no code changes (user
+  // decision 2026-08-05: any loop that modified code must NOT reset — the
+  // advisor guard WILL push back, so the convergence round must keep advancing
+  // through retries (round = prompt decay + display only; no mechanical cap —
+  // ADVISOR-CONVERGENCE.md §3.1); a run with no mutations has no push-back risk
+  // and a reset is safe). Deterministic runtime state (`_mutatedThisRun`) decides — never
+  // model output (phrases/table headers drift; three rounds of false reports
+  // proved it). Either way the message is a fresh full review (no prior output
+  // exists without a completed review) — only the round counter differs.
+  if (!prior || (agent._advisorRound || 0) === 0) {
+    if (!(agent._mutatedThisRun ?? false)) {
+      // New review cycle (first review, all-clear, or no code changes): reset
+      // the round so the cycle starts from ROUND1 (round = prompt decay/display).
+      agent._advisorRound = 0
+    }
+    // Mutations exist → KEEP the round (attempts keep advancing through retries).
+    const user = buildAdvisorUserMessage(agent, prior, reviewType, designToken, documents, paths, object, designId)
+    return [
+      { role: "system", content: buildAdvisorSystemPrompt(agent, prior, reviewType) },
+      {
+        role: "user",
+        // NOTE (2026-08-06): the leading prefix is a PLAIN "System reminder:",
+        // NOT "[System reminder: ...]" — some OpenAI-compatible servers try to
+        // parse content that STARTS with '[' as structured content (or expand
+        // escape sequences in it). A literal "\x" inside the conversation
+        // background (e.g. the parent agent quoting escape sequences) then
+        // fails server-side as "unexpected end of hex escape" → 400. Plain
+        // prefix keeps the review message a plain string everywhere.
+        // The whole content also passes through escapeLiteralEscapes (below)
+        // so literal "\x"/"\u" quoted by the parent agent can never form an
+        // invalid escape when the server expands them.
+        content: escapeLiteralEscapes(`System reminder: no prior issue table is being carried into this review (first review, app restart, or session clear) — start with a fresh full review.\n\n${user}`),
+      },
+    ]
+  }
+
+  // Convergence rounds (2+): fresh [system(ROUND2/3), user(prior table + fix
+  // claims)]. buildAdvisorFollowUp carries BOTH the prior issue table (the
+  // only complete verification list — decision 2026-08-05, reversed) and the
+  // agent's fix-claim table (focus reference). buildAdvisorSystemPrompt
+  // selects ROUND2 for round 2, ROUND3 for rounds 3+ — a failed review retry
+  // keeps _advisorRound so the convergence prompt matches the attempt count.
+  // scopeFiles gives the fallback (agent gave no response table) a concrete
+  // review surface.
+  const scopeFiles = resolveScopeFiles(agent, paths)
+  const followUp = buildAdvisorFollowUp(agent, prior, scopeFiles, object)
+  // §11.2 D-24b (design round 2+ — async fix-round continuations must be able to
+  // re-approve): re-anchor the review scope (the convergence follow-up carries no
+  // document list) and inject the round's design token with the approval signal.
+  if (reviewType === "design") {
+    const docList = Array.isArray(documents)
+      ? documents.filter((d) => typeof d === "string" && d.trim())
+      : []
+    const scopeBlock = docList.length > 0
+      ? `\n\n## Documents to Review\nThe documents below are the review scope. Review ONLY these files — do not scan git diff or read any other files.\n${docList.map((d) => `- ${d} — Read this file in full`).join("\n")}`
+      : ""
+    const tokenBlock = designToken ? `\n\n${buildDesignApprovalBlock(designToken, designId)}` : ""
+    return [
+      { role: "system", content: buildAdvisorSystemPrompt(agent, prior, reviewType) },
+      { role: "user", content: escapeLiteralEscapes(followUp + scopeBlock + tokenBlock) },
+    ]
+  }
+  return [
+    { role: "system", content: buildAdvisorSystemPrompt(agent, prior, reviewType) },
+    { role: "user", content: escapeLiteralEscapes(followUp) },
+  ]
+}

package/agent/child-marks.mjs

@@ -0,0 +1,24 @@
+/**
+ * child-marks.mjs — 子代理报告文本锚点（机器检出子串——单一权威源）。
+ *
+ * 收编自 `spawn-child.mjs`（2026-09-20 端差·显示面消差批 §2.2 X6 实现轮）：端壳侧需**静态**
+ * 导入锚点做块头注记判定，而 `spawn-child.mjs` 静态链经核 agent 栈可达 `node:sqlite`
+ * ⇒ 端壳静态闭包禁达（W8 契约②；`thincoder-vscode/test/engine-floor-guard.test.mjs`
+ * fail-closed 红）⇒ 锚点下沉**零依赖叶**（先例 = `relay-prefix.mjs` 同因下沉）。`spawn-child.mjs`
+ * 原样再导出 ⇒ 既有 import 面（核 agent-tools 族 / CLI `tool-events.mjs`）零改。
+ *
+ * 语义：消费端用 `includes()` 检出锚点 ⇒ 合成块头注记（"work may be partial"）——两端各一处：
+ * CLI = `thincoder-cli/src/tui/tool-events.mjs:217`；端壳 = `thincoder-vscode/src/extension/
+ * panel-callbacks.mjs`（onToolResult）。文案演进只改这里（与检测判据单源——消除文案/判据漂移面）。
+ *
+ * 零 import——任意层可引、无环。
+ */
+
+/** turn-cap 降级文案的公共锚点：subagent/escalate 的 onDeclined 文案必含此子串
+ *  （`subagent-async.mjs` 折叠 partial / `escalate-async.mjs` 同族）。 */
+export const TURN_CAP_MARK = "stopped: turn cap reached"
+
+/** SYNC-CANCEL（L52）：sync spawn ⏹ 定向中止折叠报告的公共锚点（`buildSyncStoppedReport`）；
+ *  消费端用 `includes()` 检测"用户定向中止——工作可能不完整"语义（块冻结标 stopped 而非
+ *  done——R6）。与 TURN_CAP_MARK 同族单源纪律。 */
+export const STOPPED_MARK = "stopped by user"