thincoder 0.12.11 → 0.12.12

package/src/acp.mjs

@@ -0,0 +1,335 @@
+/**
+ * acp.mjs — `thincoder acp` entry: expose the thincoder agent over the
+ * Agent Client Protocol (schema v1) on stdio, so ACP clients (Zed, JetBrains
+ * AI Chat, Paseo) can drive sessions directly.
+ *
+ * M1 scope (see docs/design/ACP-CLIENT.md §9):
+ *   initialize / authenticate / session/new / session/prompt / session/cancel / session/close
+ * M2: tools + request_permission + fs reverse-RPC. M3: session load/resume/list/delete + config options.
+ *
+ * Auth: reuse the terminal config (~/.thincoder/config.json) — a resolvable
+ * provider API key means "configured". No account system; `logout` is absent.
+ *
+ * `isConfigured` / `createSession` are injectable for tests.
+ */
+import { readFileSync } from "node:fs"
+import { resolve } from "node:path"
+import { loadConfig } from "./config.mjs"
+import { assembleAgent } from "./cli/make-agent.mjs"
+import { createAcpServer, ACP_ERRORS } from "./acp/transport.mjs"
+import { createAcpSession } from "./acp/session.mjs"
+import { replayHistory } from "./acp/bridge.mjs"
+import { listSlots, applySession, deleteSlot, sessionPath, normalizeCwd, isLegacyTransient } from "./session.mjs"
+
+const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version
+
+/** Load a specific slot file (not the active one) — session/load by id.
+ *  Same validation as loadSession: version 1/2, cwd match, legacy-transient
+ *  filtering (pre-filtering slot files must not leak machine lines into replay). */
+function loadSlotFile(cwd, slot) {
+  const path = `${sessionPath(cwd)}.${slot}`
+  try {
+    const data = JSON.parse(readFileSync(path, "utf8"))
+    if (data?.version !== 1 && data?.version !== 2) return null
+    if (!Array.isArray(data.history)) return null
+    if (data.cwd && normalizeCwd(data.cwd).toLowerCase() !== normalizeCwd(cwd).toLowerCase()) return null
+    data.history = data.history.filter((m) => !isLegacyTransient(m))
+    return data
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Apply a session-level config option to the agent instance (memory only —
+ * the session's own runtime state, last-write-wins; not persisted to config.json).
+ * Returns true when the configId is known.
+ */
+function applyConfigOption(agent, configId, value) {
+  switch (configId) {
+    case "model": {
+      if (typeof value !== "string" || !value.trim()) return false
+      if (!agent.provider) return false // nothing to configure
+      // Split on the FIRST colon only — model names may contain colons.
+      const ci = value.indexOf(":")
+      const provider = ci >= 0 ? value.slice(0, ci) : null
+      const model = (ci >= 0 ? value.slice(ci + 1) : value).trim()
+      if (provider && provider !== agent.provider.name) agent.provider.name = provider
+      agent.provider.model = model
+      return true
+    }
+    case "thinking": {
+      if (typeof value !== "boolean" || !agent.provider) return false
+      agent.provider.thinking = value ? { type: "enabled" } : { type: "disabled" }
+      return true
+    }
+    case "mode": {
+      if (value !== "plan" && value !== "normal") return false
+      agent.planMode = value === "plan"
+      return true
+    }
+    default:
+      return false
+  }
+}
+
+/** Config is "configured" when the active provider has a resolvable API key (env fallback included). */
+export function defaultIsConfigured() {
+  try {
+    return !!loadConfig().provider?.apiKey?.trim()
+  } catch {
+    return false
+  }
+}
+
+/** M1/M2 session factory: one agent per session, built from the process cwd (single-cwd model).
+ *  `id` is the ACP session id — it is baked into the callbacks at construction time
+ *  (buildAcpCallbacks closure), so it must be known BEFORE createAcpSession runs.
+ *  `request` is the transport's reverse-RPC channel (permissions + fs routing). */
+export async function defaultCreateSession({ id, notify, request, log }) {
+  const agent = await assembleAgent()
+  return createAcpSession({ id, agent, notify, request, log })
+}
+
+/**
+ * Build the ACP method handlers. Returns { handlers, sessions, notifyRef } —
+ * notifyRef.current is set by runAcpServer once the transport exists; sessions
+ * are created lazily (session/new), by which time the reference is live.
+ * @param {{ version?: string, notify?: (method, params) => void, log?: (s: string) => void,
+ *           isConfigured?: () => boolean, createSession?: (ctx) => Promise<object> }} deps
+ */
+export function buildAcpHandlers({
+  version = VERSION,
+  notify = () => {},
+  log = () => {},
+  isConfigured = defaultIsConfigured,
+  createSession = defaultCreateSession,
+  cwd = () => process.cwd(),
+}) {
+  const getCwd = cwd
+  const notifyRef = { current: notify }
+  const requestRef = { current: async () => { throw new Error("no request channel") } }
+  const sessions = new Map()
+  let nextId = 1
+  let authenticated = false
+  const findSession = (params) => {
+    const s = sessions.get(String(params?.sessionId))
+    if (!s) return { error: { ...ACP_ERRORS.INVALID_PARAMS, message: `unknown session ${params?.sessionId}` } }
+    return { session: s }
+  }
+
+  return {
+    handlers: {
+      initialize: () => ({
+        protocolVersion: 1,
+        agentInfo: { name: "thincoder", version },
+        authMethods: ["terminal"],
+        capabilities: { fs: { read: true, write: true }, terminal: false },
+      }),
+
+      authenticate: () => {
+        if (!isConfigured()) return { error: ACP_ERRORS.AUTH_REQUIRED }
+        authenticated = true
+        return { authenticated: true }
+      },
+
+      "session/new": async (params) => {
+        if (!authenticated) return { error: ACP_ERRORS.AUTH_REQUIRED }
+        if (params.cwd !== undefined && typeof params.cwd !== "string") {
+          return { error: { ...ACP_ERRORS.INVALID_PARAMS, message: "cwd must be a string" } }
+        }
+        // Normalized comparison: resolve() collapses trailing slashes, and
+        // normalizeCwd().toLowerCase() makes the check case-insensitive on
+        // Windows (drive letter + path — a client sending "c:\users\…" vs
+        // process.cwd() "C:\Users\…" must match). The ternary guards against
+        // resolve(undefined) — it would coerce undefined to the literal
+        // "undefined" and resolve a nonsense path. Note: `requested` never
+        // feeds any path operation — the agent always runs in getCwd() — so
+        // a case-insensitive match on case-sensitive platforms is harmless.
+        const norm = (p) => normalizeCwd(p).toLowerCase()
+        const requested = params.cwd ? resolve(params.cwd) : getCwd()
+        if (norm(requested) !== norm(getCwd())) {
+          return { error: { ...ACP_ERRORS.INVALID_PARAMS, message: `v1: cwd must equal the process working directory (${getCwd()})` } }
+        }
+        if (params.mcpServers?.length) {
+          log(`[acp] MCP forwarding is M2 scope — ignoring ${params.mcpServers.length} server(s)`)
+        }
+        try {
+          const id = String(nextId++)
+          const session = await createSession({ id, notify: notifyRef.current, request: requestRef.current, log })
+          // `id` is immutable after construction (baked into the callbacks) — never reassign.
+          sessions.set(id, session)
+          return { id, configOptions: [{ configId: "model" }, { configId: "thinking" }, { configId: "mode" }] }
+        } catch (e) {
+          return { error: { code: ACP_ERRORS.INTERNAL.code, message: `failed to create session: ${e.message}` } }
+        }
+      },
+
+      "session/prompt": async (params) => {
+        if (!authenticated) return { error: ACP_ERRORS.AUTH_REQUIRED }
+        const found = findSession(params)
+        if (found.error) return found
+        const blocks = Array.isArray(params?.content) ? params.content : []
+        const text = blocks.find((b) => b?.type === "text")?.text ?? ""
+        if (!text) return { error: { ...ACP_ERRORS.INVALID_PARAMS, message: "prompt requires a text content block" } }
+        try {
+          await found.session.run(text)
+          return { stopReason: "end_turn" }
+        } catch (e) {
+          // Cancelled/interrupted turns are not errors on the wire.
+          if (e?.name === "AbortError" || e?.code === "ABORT_ERR") return { stopReason: "cancelled" }
+          return { error: { code: ACP_ERRORS.INTERNAL.code, message: e?.message ?? String(e) } }
+        }
+      },
+
+      "session/cancel": (params) => {
+        const found = findSession(params)
+        if (found.error) return found
+        found.session.cancel()
+        return {}
+      },
+
+      "session/close": (params) => {
+        const found = findSession(params)
+        if (!found.error) {
+          // Abort any in-flight turn first — the client is gone, the agent must
+          // stop consuming LLM tokens and emitting notifications.
+          found.session.cancel()
+          sessions.delete(String(params.sessionId))
+          log(`session ${params.sessionId} closed by client`)
+        }
+        return {}
+      },
+
+      // ─── M3: persisted slots (thincoder session archive) + config options ───
+
+      "session/list": () => {
+        if (!authenticated) return { error: ACP_ERRORS.AUTH_REQUIRED }
+        const slots = listSlots(getCwd())
+        return {
+          sessions: slots.map((s) => ({
+            id: String(s.slot),
+            cwd: getCwd(), // single-cwd model (design §4.5)
+            updatedAt: s.updatedAt ?? 0,
+            title: s.title ?? "",
+            messageCount: s.messageCount ?? 0,
+          })),
+        }
+      },
+
+      "session/load": async (params) => {
+        if (!authenticated) return { error: ACP_ERRORS.AUTH_REQUIRED }
+        const slot = Number(params.sessionId)
+        if (!Number.isInteger(slot) || slot < 1) {
+          return { error: { ...ACP_ERRORS.INVALID_PARAMS, message: `invalid session id: ${params.sessionId}` } }
+        }
+        const data = loadSlotFile(getCwd(), slot)
+        if (!data) {
+          return { error: { ...ACP_ERRORS.INVALID_PARAMS, message: `session ${slot} not found (corrupt or deleted)` } }
+        }
+        try {
+          const id = String(nextId++)
+          const session = await createSession({ id, notify: notifyRef.current, request: requestRef.current, log })
+          applySession(session.agent, data)
+          sessions.set(id, session)
+          // Replay the human line (role → chunk mapping, design §4.5) so the
+          // client renders the restored conversation.
+          replayHistory({ sessionId: id, notify: notifyRef.current, history: data.history, log })
+          log(`session ${slot} loaded as session ${id} (${data.history?.length ?? 0} messages replayed)`)
+          return { id, cwd: getCwd(), configOptions: [{ configId: "model" }, { configId: "thinking" }, { configId: "mode" }] }
+        } catch (e) {
+          return { error: { code: ACP_ERRORS.INTERNAL.code, message: `failed to load session ${slot}: ${e.message}` } }
+        }
+      },
+
+      "session/resume": async (params) => {
+        if (!authenticated) return { error: ACP_ERRORS.AUTH_REQUIRED }
+        const slot = Number(params.sessionId)
+        if (!Number.isInteger(slot) || slot < 1) {
+          return { error: { ...ACP_ERRORS.INVALID_PARAMS, message: `invalid session id: ${params.sessionId}` } }
+        }
+        const data = loadSlotFile(getCwd(), slot)
+        if (!data) {
+          return { error: { ...ACP_ERRORS.INVALID_PARAMS, message: `session ${slot} not found (corrupt or deleted)` } }
+        }
+        try {
+          const id = String(nextId++)
+          const session = await createSession({ id, notify: notifyRef.current, request: requestRef.current, log })
+          applySession(session.agent, data)
+          sessions.set(id, session)
+          // resume: no history replay — the client keeps its own rendering.
+          log(`session ${slot} resumed as session ${id} (no replay)`)
+          return { id, cwd: getCwd(), configOptions: [{ configId: "model" }, { configId: "thinking" }, { configId: "mode" }] }
+        } catch (e) {
+          return { error: { code: ACP_ERRORS.INTERNAL.code, message: `failed to resume session ${slot}: ${e.message}` } }
+        }
+      },
+
+      "session/delete": (params) => {
+        if (!authenticated) return { error: ACP_ERRORS.AUTH_REQUIRED }
+        const slot = Number(params.sessionId)
+        if (!Number.isInteger(slot) || slot < 1) {
+          return { error: { ...ACP_ERRORS.INVALID_PARAMS, message: `invalid session id: ${params.sessionId}` } }
+        }
+        // Only the persisted archive is removed; an active in-memory session
+        // with the same id keeps running (design §4.5).
+        if (!deleteSlot(getCwd(), slot)) {
+          return { error: { ...ACP_ERRORS.INVALID_PARAMS, message: `session ${slot} not found` } }
+        }
+        log(`session ${slot} archive deleted`)
+        return {}
+      },
+
+      "session/set_config_option": (params) => {
+        if (!authenticated) return { error: ACP_ERRORS.AUTH_REQUIRED }
+        const found = findSession(params)
+        if (found.error) return found
+        const { configId, value } = params
+        if (!configId || value === undefined) {
+          return { error: { ...ACP_ERRORS.INVALID_PARAMS, message: "set_config_option requires configId and value" } }
+        }
+        const applied = applyConfigOption(found.session.agent, configId, value)
+        if (!applied) {
+          return { error: { ...ACP_ERRORS.INVALID_PARAMS, message: `unknown configId: ${configId}` } }
+        }
+        // Last-write-wins on the internal state; notify the client of the change.
+        notifyRef.current("session/update", {
+          sessionId: String(params.sessionId),
+          update: { sessionUpdate: "config_option_update", configId, value },
+        })
+        return {}
+      },
+
+      "session/set_mode": (params) => {
+        if (!authenticated) return { error: ACP_ERRORS.AUTH_REQUIRED }
+        const found = findSession(params)
+        if (found.error) return found
+        if (params.mode !== "plan" && params.mode !== "normal") {
+          return { error: { ...ACP_ERRORS.INVALID_PARAMS, message: "mode must be plan or normal" } }
+        }
+        found.session.agent.planMode = params.mode === "plan"
+        notifyRef.current("session/update", {
+          sessionId: String(params.sessionId),
+          update: { sessionUpdate: "current_mode_update", mode: params.mode },
+        })
+        return {}
+      },
+    },
+    sessions,
+    notifyRef,
+    requestRef,
+  }
+}
+
+/** `thincoder acp` — start the server and block until the client closes the pipe. */
+export async function runAcpServer() {
+  const log = (...a) => process.stderr.write(a.join(" ") + "\n")
+  // Build handlers first, then wire the transport — no window where requests
+  // hit an empty handler map. notifyRef/requestRef become live with the server.
+  const built = buildAcpHandlers({ log })
+  const server = createAcpServer(built.handlers, { log })
+  built.notifyRef.current = server.notify
+  built.requestRef.current = server.request
+  log(`[acp] thincoder ${VERSION} — ACP v1 over stdio, waiting for initialize`)
+  server.start()
+}

package/src/advisor/citations.mjs

@@ -0,0 +1,77 @@
+/**
+ * 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.
+ */
+import { readFileSync, realpathSync } from "node:fs"
+import { resolve, sep } 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
+}
+
+/**
+ * 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.
+ */
+export function verifyCitations(text, cwd) {
+  const citations = extractCitations(text)
+  const matched = []
+  const failed = []
+  const root = resolve(cwd) + sep
+  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" })
+    }
+  }
+  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)
+  if (total === 0) return text // no citations — nothing to verify
+  const lines = [
+    "",
+    "---",
+    `[host-verified] ${matched.length}/${total} citations match current file state.`,
+  ]
+  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/src/advisor/history.mjs

@@ -6,6 +6,8 @@ import { join } from "node:path"
 
 export const ADVISOR_MD_PATH = ".thincoder/advisor.md"
 export const ADVISOR_TABLE_HEADER = "| # | File | Severity | Issue | Suggestion |"
+// Design-review table header (advisor-design.md round 1): | # | Category | Severity | Issue | Suggestion |
+const DESIGN_TABLE_HEADER = "| # | Category | Severity | Issue | Suggestion |"
 const CONVERGENCE_TABLE_HEADER = "| # | Orig# | File | Severity | Status | Notes |"
 const AGENT_RESPONSE_HEADER = "| # | Action | Detail |"
 export const LEGACY_ADVISOR_HEADER = "| # | 文件 | 严重程度 | 问题描述 | 建议修复 |"
@@ -25,11 +27,19 @@ const DEFAULT_CRITERIA = `Review the code changes, focusing on:
  * Returns null when: no advisor call, empty output, or the last review is
  * all-clear (nothing to follow up on).
  */
+// All-clear phrases the prompts instruct the advisor to use on a clean review.
+// Used ONLY by extractPriorIssueTable (issue-table verdict — a phrase-free
+// issue table with rows is never all-clear). The round-reset guard no longer
+// depends on model output at all: prepareAdvisorMessages decides by the
+// deterministic _mutatedThisRun flag (user decision 2026-08-05). "no new
+// issues" is DELIBERATELY absent — verification-table outputs (round 2+)
+// commonly conclude with it (round 3+ instructions even SAY "do not look for
+// new issues"); treating it as all-clear would reset the convergence budget
+// after every round-2 review (the observed "always round 2" bug: prior → null
+// → _advisorRound reset → 1→2→1…).
+const ALL_CLEAR_PHRASES = ["no 🔴", "all clear", "全部通过", "review passed", "no issues found", "everything is fine"]
+
 export function extractPriorIssueTable(history) {
-  // allClear: exact phrases the prompts instruct the advisor to use on a clean review.
-  // NOTE: "已修复" (Fixed) is NOT here — it's a per-row Status value in convergence tables,
-  // and a mixed table must continue convergence even if some rows are Fixed.
-  const allClear = ["no 🔴", "all clear", "全部通过", "review passed", "no issues found", "no new issues"]
   // Negative signals: a table listing SOME items as unfixed is NOT all-clear.
   // Applied when the message carries a Status column (English or Chinese convergence
   // format) — "failed"/"❌" in a round-1 Issue description must NOT trigger it.
@@ -44,6 +54,7 @@ export function extractPriorIssueTable(history) {
     // header constants' own source code (e.g. history.mjs), producing a phantom
     // "prior issue table" and re-opening convergence rounds against stale data.
     if (!lineHasHeader(m.content, ADVISOR_TABLE_HEADER)
+      && !lineHasHeader(m.content, DESIGN_TABLE_HEADER)
       && !lineHasHeader(m.content, CONVERGENCE_TABLE_HEADER)
       && !lineHasHeader(m.content, LEGACY_ADVISOR_HEADER)) continue
     const text = m.content
@@ -52,8 +63,16 @@ export function extractPriorIssueTable(history) {
     // column) — Chinese legacy tables lack it, but they are issue tables, not convergence.
     const hasStatusColumn = lineHasHeader(text, CONVERGENCE_TABLE_HEADER)
       || /Status|状态/.test(text.slice(0, text.indexOf("\n") + 1))
-    if (hasStatusColumn && partiallyFixedRe.test(lower)) return { text, sinceIdx: i }
-    if (allClear.some((s) => lower.includes(s))) return null
+    if (hasStatusColumn) {
+      // Convergence/verification table: pass/fail is row-level — free-text
+      // phrases like "no new issues found" / "review passed" are partial or
+      // boilerplate statements in verification outputs. Some row unfixed →
+      // convergence continues; every row fixed → all clear (fresh cycle).
+      if (partiallyFixedRe.test(lower)) return { text, sinceIdx: i }
+      return null
+    }
+    // Issue table (round 1 / design): phrase-based all-clear detection.
+    if (ALL_CLEAR_PHRASES.some((s) => lower.includes(s))) return null
     // sinceIdx = the advisor call's own index; extractAgentResponseTable skips it (role !== assistant)
     return { text, sinceIdx: i }
   }

package/src/advisor/messages.mjs

@@ -4,30 +4,31 @@
  * (.thincoder/advisor.md). System prompts live in advisor.mjs / prompts/.
  */
 import { readFileSync } from "node:fs"
-import { resolve } from "node:path"
+import { resolve, join, relative } from "node:path"
 import { findReviewRepos, collectRepoSnapshots, collectChangedFiles } from "./repos.mjs"
 import { loadAdvisorMd, extractConversationBackground, extractAgentResponseTable, extractPriorIssueTable } from "./history.mjs"
 
 /**
  * Build the user message for an advisor review session.
  * @param {Object} agent — the parent agent
- * @param {Object|null} [_prior] — prior issue table
+ * @param {Object|null} [prior] — prior issue table
  * @param {string} [reviewType] — "design" or "code" (default)
  * @param {string|null} [designToken] — token 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 (requirements + design + referenced docs).
  *   When set, the review input is built from this list ONLY — no git-diff change-set collection.
  *   When absent, the legacy git-diff-based scope is kept (backward compatible).
+ * @param {string[]|null} [paths] — code review only: explicit list of file/dir paths to review (deduped; shown under Review Scope)
  * @returns {string} the user message
  */
-export function buildAdvisorUserMessage(agent, _prior, reviewType, designToken = null, documents = null, paths = null) {
-  const prior = _prior ?? extractPriorIssueTable(agent.history)
+export function buildAdvisorUserMessage(agent, prior, reviewType, designToken = null, documents = null, paths = null) {
+  const p = prior ?? extractPriorIssueTable(agent.history)
 
   const parts = []
   const docList = Array.isArray(documents) ? documents.filter((d) => typeof d === "string" && d.trim()) : []
-  const pathList = Array.isArray(paths) ? paths.filter((p) => typeof p === "string" && p.trim()) : []
+  const pathList = Array.isArray(paths) ? [...new Set(paths.filter((p) => typeof p === "string" && p.trim()))] : []
 
   // Design review: simplified message — focus on the design doc, not code
-  if (reviewType === "design") {
+  if (reviewType === "design" && (agent._advisorRound || 0) === 0) {
     const repos = findReviewRepos(agent)
     parts.push("## Design Review")
     if (docList.length > 0) {
@@ -95,25 +96,35 @@ export function buildAdvisorUserMessage(agent, _prior, reviewType, designToken =
     return parts.join("\n")
   }
 
-  // Convergence data (round 2+). Design reviews returned above — only code reviews reach here.
-  if (prior && (agent._advisorRound || 0) > 0) {
-    const response = extractAgentResponseTable(agent.history, prior.sinceIdx)
-      || "(Agent did not provide a response table — re-evaluate each issue)"
+  // Convergence data (round 2+). LEGACY COMPATIBILITY PATH: the normal advisor
+  // flow routes convergence rounds through buildAdvisorFollowUp (fresh session,
+  // decision d698434); this block only fires for direct external callers of
+  // buildAdvisorUserMessage with a prior table. Kept to avoid breaking those.
+  // Same rule as buildAdvisorFollowUp: prior table IS injected (decision
+  // 2026-08-05, reversed) — it is the only complete verification list.
+  if (p && (agent._advisorRound || 0) > 0) {
+    const scopeFiles = resolveScopeFiles(agent, paths)
+    const response = extractAgentResponseTable(agent.history, p.sinceIdx)
+      || (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 review of the files named in the system prompt context)")
     const round = (agent._advisorRound || 0) + 1
     const label = round === 2 ? "Verify Prior Table + Flag New Issues" : "Strict Verification"
     parts.push(`## Round ${round} — ${label}`)
     parts.push("")
-    parts.push("## Prior Issue Table")
-    parts.push(prior.text)
+    parts.push("## Prior Issue Table (verify every item)")
+    parts.push(p.text)
     parts.push("")
-    parts.push("## Agent Response")
+    parts.push("## Agent Response (fix claims — reference only)")
     parts.push(response)
     parts.push("")
     parts.push("---")
     parts.push("")
   }
 
-  parts.push("## Review Scope")
+  if (pathList.length > 0 || docList.length > 0) {
+    parts.push("## Review Scope")
+  }
   if (pathList.length > 0) {
     parts.push("Review these code files/directories — read them in full for context:")
     parts.push("")
@@ -159,18 +170,15 @@ export function buildAdvisorUserMessage(agent, _prior, reviewType, designToken =
   }
 
   // Instructions — round-aware: re-reviews skip convention discovery entirely
-  const isReReview = prior && (agent._advisorRound || 0) > 0
+  const isReReview = p && (agent._advisorRound || 0) > 0
   parts.push("## Instructions")
-  parts.push("1. IMPORTANT: in the diff, `-` lines are REMOVED content (no longer in the file), `+` lines are ADDED. The prior issue table (if any) is HISTORY — always verify current file state with `read` before judging an item.")
+  parts.push("1. IMPORTANT: the review scope lists the files under review — always verify current file state with `read` before judging. Never decide based on earlier snapshots alone.")
   if (isReReview) {
-    parts.push("2. STALE-CONTEXT WARNING: any diff or file content embedded in earlier messages is a historical snapshot — treat it as expired. Only fresh `read` results describe the current state. Never quote a `-` line from an earlier diff as if it were live code.")
-    parts.push("3. Verify the prior issue table against the CURRENT FILE STATE — use `read`, never `git diff` alone. Fixes may already be committed: an empty `git diff` does NOT mean nothing changed. `git log -3` shows recent commits.")
-    parts.push("4. `read` the files in the Review Scope in full — ALWAYS, regardless of what `git diff` shows. Batch reads/greps in a single reply.")
-    parts.push("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 come from the stale prior table. Findings without a fresh quoted line are treated as unverified and will not be accepted.")
-    parts.push("6. Produce your verification table. Do not re-read content you already have.")
+    const round = (agent._advisorRound || 0) + 1
+    parts.push(...buildConvergenceInstructions(round, pathList))
   } else {
     parts.push("2. Read `AGENTS.md` / design docs only if they exist (check once; do not re-probe with multiple patterns).")
-    parts.push("3. `read` changed files for full context beyond the diff. Batch independent reads/greps in a single reply instead of one call per round-trip.")
+    parts.push("3. `read` the files in the Review Scope in full — they define exactly what to inspect. Batch independent reads/greps in a single reply instead of one call per round-trip.")
     parts.push("4. Use `grep` or `lsp` to trace callers, imports, and dependencies — only where the diff leaves genuine doubt.")
     parts.push("5. Produce your review table based on the review criteria above. Do not re-read content you already have.")
     parts.push("6. You may also flag other issues: crashes, data loss, logic errors — anything obvious. This is the convergence protocol: round 1 is the full review, later rounds only re-verify.")
@@ -180,3 +188,49 @@ export function buildAdvisorUserMessage(agent, _prior, reviewType, designToken =
 
   return parts.join("\n")
 }
+
+/**
+ * Resolve the review surface for the convergence fallback: explicit `paths`
+ * win; otherwise the runtime mutation record (_touchedFiles, ABSOLUTE) is
+ * normalized to cwd-relative so the fallback list matches the relative-path
+ * norm the reviewer sees everywhere else. Paths outside cwd are relativized
+ * with path.relative — never a mixed absolute/relative list.
+ */
+export function resolveScopeFiles(agent, paths) {
+  const normalize = (p) => {
+    const abs = p.startsWith(agent.cwd) ? p : join(agent.cwd, p)
+    return relative(agent.cwd, abs)
+  }
+  if (Array.isArray(paths)) return [...new Set(paths.map(normalize))]
+  if (agent._touchedFiles?.length) {
+    return [...new Set(agent._touchedFiles.map(normalize))]
+  }
+  return null
+}
+
+/**
+ * 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 issue table 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 table (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.",
+  ]
+}
+