thincoder 0.12.60 → 0.12.61

package/src/advisor/run.mjs

@@ -1,351 +1,95 @@
 /**
- * advisor/run.mjs — advisor execution: tool loop, provider resolution, and the review entry point.
- * Message building lives in advisor.mjs.
+ * 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 { chat } from "../provider/core.mjs"
-import { findProvider, providerSpec } from "../config.mjs"
-import { toOpenAISchema } from "../tools/index.mjs"
+import { findProvider } from "../config.mjs"
 import { prepareAdvisorMessages } from "../advisor.mjs"
+import { buildObjectDeclarationBlock, buildDesignApprovalBlock } from "./messages.mjs"
 import { appendCitationReport } from "./citations.mjs"
-import { describeToolArgs } from "../tui/tool-args.mjs"
+import { runAdvisorToolLoop } from "./loop.mjs"
+import { advisorIncompleteMarker, estimateTokens } from "./compaction.mjs"
+import { batchDocForReview } from "../agent-tools/batch-segment.mjs"
+// 第 33 批（§17.5 模块图）：护栏常量 / doc-set 键 / 记录读取——单向导入（review-streak 无回指）。
+import {
+  MAX_DESIGN_REVIEW_STREAK, docSetKey, designReviewStreakRecord, designReviewStreakStopped,
+} from "../agent-tools/review-streak.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"
 
-const MAX_ADVISOR_TURNS = 100
 // Mechanical convergence cap: up to 5 rounds suffice; a 6th call means the model
-// is looping — refuse it instead of burning tokens. §24 D-24b (2026-09-06): PER
+// is looping — refuse it instead of burning tokens. §11.2 D-24b (2026-09-06): PER
 // REVIEW INSTANCE (agent._advisorRuns); CODE REVIEWS ONLY (2026-09-07 §8 ruling)
 // — design reviews are EXEMPT: their rounds keep advancing, the cap never refuses.
 export const MAX_ADVISOR_ROUNDS = 5
 
-// 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.
-
-// 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"
-
-// Context window limits
-const MAX_CONTEXT_TOKENS = 120_000 // Reserve headroom to avoid OOM
-const TOOL_TIMEOUT_MS = 30_000 // single tool timeout
-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_UNFIXED_DISPLAY = 10 // unfixed issues shown in the cap message
-const MAX_KEY_FILES_IN_COMPACTION = 5 // files named in the compaction summary
-
-/** Estimate token count from messages (rough: 1 token ≈ 4 chars) */
-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 + Math.ceil((content.length + toolCalls.length) / 4)
-  }, 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. */
-function compactMessages(messages) {
-  // 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}`
-
-  messages.splice(0, messages.length,
-    system,
-    { role: "user", content: `[Context compacted] ${summary}` },
-    ...recent)
-}
-
-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) {
-  const search = agent?.memory ? codeSearchTool(agent.memory) : null
-  const tools = search
-    ? [readTool, globTool, grepTool, lsTool, lspTool, search]
-    : [readTool, globTool, grepTool, lsTool, lspTool]
-  return { schemas: tools.map(toOpenAISchema), byName: new Map(tools.map((t) => [t.name, t])) }
+/** B 启动拒绝前缀（§14.4 #2）——稳定契约单源（三消费点同串）：run.mjs 生成；同步工具面
+ *  据此登记 `_advisorRefusals`；异步结算面据此不置 `_calledAdvisorThisRun`。 */
+export const ADVISOR_LAUNCH_REFUSAL_PREFIX = "Advisor: design review launch refused"
+
+/** 评审失败护栏稳定前缀（第 33 批 §17.4——与 `ADVISOR_LAUNCH_REFUSAL_PREFIX` 同族；
+ *  实现 grep / 用例断言锚）。凭证卫生：串内零 token / designId 值。 */
+export const ADVISOR_DESIGN_STREAK_STOP_PREFIX = "Advisor: design review stopped"
+
+/** kind → 人读说明（第 33 批 §17.4 逐字——结论表第三列；八类 = 五 kind + stale +
+ *  no_credential + no_report，与 review-streak.mjs 分类输出同集）。 */
+const DESIGN_REVIEW_OUTCOME_MEANINGS = {
+  timeout: "review exceeded the wall-clock budget (agent.advisor.timeoutMs)",
+  context_limit: "review exceeded the model context budget",
+  turn_cap: "review exceeded the tool-round limit",
+  empty: "the provider returned an empty response",
+  review_failed: "provider / transport error",
+  stale: "the reviewed documents changed while the review was in flight",
+  no_credential: "the token could not be written to the session ledger",
+  no_report: "the review settled without a report",
 }
-// Test seam: the tool set is pure (agent.memory → code_search inclusion).
-export { advisorToolsFor as _advisorToolsFor }
 
 /**
- * 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).
+ * 停止结论串（第 33 批 §17.4 逐字；F29）：稳定前缀 + 停止的 doc-set 清单 + 失败尝试表
+ * （记录逐条——kind + 人读说明）+ 三选项（接受现状 / 改变或缩小范围后重跑 / /new 重置）。
+ * 全文零凭证值；不自动执行任何恢复动作（发起权在父代理 / 用户）。
+ * @param {{count: number, log: string[]}|null} record — 护栏记录（`designReviewStreakRecord`）
+ * @param {string[]|null} documents — 被停的文档集（结论清单数据源）
  */
-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")
+export function buildDesignReviewGuardMessage(record, documents) {
+  const log = Array.isArray(record?.log) ? record.log : []
+  const docList = Array.isArray(documents) ? documents.filter((d) => typeof d === "string" && d.trim()) : []
+  return [
+    `${ADVISOR_DESIGN_STREAK_STOP_PREFIX} — ${MAX_DESIGN_REVIEW_STREAK} consecutive attempts on this document set produced no design token (repeated failed settlements; no further reviews will start for this set in this session).`,
+    "Document set (1 design instance — no token issued):",
+    ...docList.map((d) => `- ${d}`),
+    "Attempts (most recent last):",
+    "| # | outcome | meaning |",
+    "|---|---|---|",
+    ...log.map((kind, i) => `| ${i + 1} | ${kind} | ${DESIGN_REVIEW_OUTCOME_MEANINGS[kind] ?? kind} |`),
+    "Options:",
+    "1. Accept the current state and proceed — implementation for this document set stays gated (no design token).",
+    "2. Narrow or change the scope: a different document set starts a fresh budget — fix the cause first (agent.advisor.timeoutMs / advisor model / provider).",
+    "3. Start a new session (/new) to reset the guard.",
+  ].join("\n")
 }
-// Test seam (mirrors _advisorToolsFor).
-export { renderTimeline as _renderTimeline }
-// 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 as _runAdvisorToolLoop }
-
-/**
- * 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.
- */
-async function runAdvisorToolLoop(provider, messages, onOutput, signal, agent, cwd, toolsOverride = null) {
-  // 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)
-  let turns = 0
-  const startTime = Date.now()
-  
-  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
-    if (Date.now() - startTime > timeoutMs) {
-      return renderTimeline(timeline, `Advisor: review timeout after ${Math.round(timeoutMs / 1000)}s. Partial results may be available. Try again with a narrower scope.`)
-    }
-    
-    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 > MAX_CONTEXT_TOKENS * 0.8) {
-      onText(`\n[Context compacted: ${currentTokens} tokens → reducing to fit window]\n`)
-      compactMessages(messages)
-      if (estimateTokens(messages) > MAX_CONTEXT_TOKENS) {
-        // 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 })
 
-    const response = await chat(provider, {
-      messages,
-      tools: toolSchemas,
-      // Pass the signal UNCONDITIONALLY: a signal aborted between the check
-      // above and here must still cancel the fetch. core.mjs composes
-      // AbortSignal.any([signal, timeout]) — an already-aborted signal makes
-      // the request fail immediately instead of ignoring the interrupt.
-      signal: signal ?? null,
-      onToken: onText,
-      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,
-      },
-    })
-
-    // 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 }
-    })
-    // 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 + line-aware truncation stay per-tool.
-    for (let i = 0; i < parsed.length; i++) {
-      let result = executed[i]
-      if (typeof result !== "string") result = JSON.stringify(result)
-
-      if (result.length > MAX_RESULT_CHARS) {
-        const lines = result.split("\n")
-        let truncated = ""
-        let charCount = 0
-        let keptLines = 0
-
-        for (let j = 0; j < lines.length; j++) {
-          const line = lines[j]
-          if (charCount + line.length + 1 > MAX_RESULT_CHARS) break
-          truncated += line + "\n"
-          charCount += line.length + 1
-          keptLines++
-        }
-
-        const remainingLines = lines.length - keptLines
-        result = (
-          truncated +
-          `\n… (truncated: ${remainingLines} more lines, ${result.length} chars total)\n` +
-          `To see more content, use: read(path, offset=${keptLines + 1}, limit=200)`
-        )
-      }
-
-      messages.push({ role: "tool", tool_call_id: parsed[i].tc.id, content: result })
-    }
-  }
-}
+const MAX_UNFIXED_DISPLAY = 10 // unfixed issues shown in the cap message
 
 /** 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 {
-      const provider = findProvider(agent.providers ?? [agent.provider], cfg.provider)
-      const result = cfg.model ? { ...provider, model: cfg.model } : { ...provider }
+      // 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
@@ -406,6 +150,24 @@ export function buildCapMessage(agent) {
   return message
 }
 
+/**
+ * 压缩定锚简报（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" (default) or "design". Returns review text or null when skipped.
  * @param {string|null} [designToken] — injected into the design-review prompt; the advisor echoes it only on approval.
@@ -426,20 +188,52 @@ export async function runAdvisorReview(agent, reviewType, callbacks, designToken
 
   // Mechanical convergence cap — CODE REVIEWS ONLY (2026-09-07 §8 ruling: design
   // reviews are exempt). _advisorRound is scoped to the current review instance
-  // (§24 D-24b ③), so >= MAX_ADVISOR_ROUNDS blocks the next call of THIS instance.
+  // (§11.2 D-24b ③), so >= MAX_ADVISOR_ROUNDS blocks the next call of THIS instance.
   // 5 rounds max; after that the review is never pushed back.
   if (reviewType !== "design" && (agent._advisorRound || 0) >= MAX_ADVISOR_ROUNDS) {
     return buildCapMessage(agent)
   }
 
+  // 第 33 批（§17.5 检查点 2——内防线）：同一 doc-set 连续未产出可用结算达阈值 ⇒ 直接拒绝
+  // （不建消息、不发起、零 LLM）——防直接调用方绕过工具层预检（正常工具链在预检已拒）。
+  if (reviewType === "design" && Array.isArray(documents) && documents.length > 0) {
+    const streakKey = docSetKey(documents, agent.cwd)
+    if (designReviewStreakStopped(agent, streakKey)) {
+      return buildDesignReviewGuardMessage(designReviewStreakRecord(agent, streakKey), documents)
+    }
+  }
+
   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)
+    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
@@ -447,9 +241,10 @@ export async function runAdvisorReview(agent, reviewType, callbacks, designToken
     // 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)
+      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).

package/src/advisor/truncate.mjs

@@ -0,0 +1,57 @@
+/**
+ * truncate.mjs — advisor 工具结果的行感知双端截断（DUAL-END-TRUNCATION F-2，
+ * DUAL-END-TRUNCATION.md，2026-09-09——CLI/VSC 双端逐字同构镜像）。
+ *
+ * 原 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/src/advisor.mjs

@@ -2,7 +2,8 @@
  * 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.
- * repos.mjs still hosts the doc-file classifier (isDocFile) used by mutation tracking.
+ * 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
@@ -266,7 +267,7 @@ export function prepareAdvisorMessages(agent, reviewType, designToken = null, do
   // review surface.
   const scopeFiles = resolveScopeFiles(agent, paths)
   const followUp = buildAdvisorFollowUp(agent, prior, scopeFiles, object)
-  // §24 D-24b (design round 2+ — async fix-round continuations must be able to
+  // §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") {

package/src/agent/completion.mjs

@@ -120,7 +120,7 @@ export function handleCompletion(agent, response, depth, turn, guardPushbacks, h
   const cfg = agent.config?.advisor
   const advisorReview = cfg?.guard === true
   if (depth === 0 && advisorReview && !agent.config?.agent?.engineering) {
-    // §24 D-24b (T-24b4 — guard timing): an async review that is still in flight
+    // §11.2 D-24b (T-24b4 — guard timing): an async review that is still in flight
     // (or queued in the advisor pool) means the review was launched — the guard
     // does NOT push back while it is pending (未决不算未评审); once it settles
     // non-stale it marks _calledAdvisorThisRun, and a STALE settle leaves the