thincoder 0.12.11 → 0.12.12

package/src/advisor.mjs

@@ -1,14 +1,13 @@
 /**
  * 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; git discovery/collection in
- * advisor/repos.mjs (design-review diffs only — code-review follow-ups deliberately
- * inject NO git information); history extraction in advisor/history.mjs.
+ * 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.
  *
  * The advisor runs as a read-only exploration sub-agent with tools
- * (read, glob, grep, ls, git, lsp, code_search). Round 1 discovers changes
- * via git diff and reads files for context; convergence rounds (2+) verify
- * fix status with `read` only — no git output is injected or trusted.
+ * (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" } }
@@ -16,9 +15,16 @@
  *
  * Convergence protocol:
  *   Round 1: full review → produces a numbered issue table.
- *   Agent responds with a response table per issue.
- *   Round 2: semi-convergence — verifies table + can flag obvious new issues.
+ *   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, plus a mechanical
  *   cap (MAX_ADVISOR_ROUNDS in run.mjs) refuses a 6th review call outright.
@@ -26,13 +32,12 @@
  *   file:line evidence for any unfixed/new finding — see docs/design/ADVISOR-CONVERGENCE.md.
  *
  * Session memory (agent._advisorSession):
- *   All advisor calls within one run share a single conversation — round 2+
- *   just appends a follow-up (agent response + refreshed diff + round rules),
- *   so the advisor keeps its exploration context instead of re-discovering
- *   everything. The session is discarded when the run ends (runAgent resets it);
- *   the next task starts a fresh advisor session. After an app restart the
- *   in-memory session is gone — falls back to a fresh session seeded from the
- *   issue/response tables in the main history.
+ *   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.
  */
@@ -40,7 +45,7 @@ import { readFileSync } from "node:fs"
 import { join, dirname } from "node:path"
 import { fileURLToPath } from "node:url"
 import { extractPriorIssueTable, extractAgentResponseTable } from "./advisor/history.mjs"
-import { buildAdvisorUserMessage } from "./advisor/messages.mjs"
+import { buildAdvisorUserMessage, buildConvergenceInstructions, resolveScopeFiles } from "./advisor/messages.mjs"
 // Re-export for run.mjs and tests (keeps their imports from "../advisor.mjs" stable)
 export { ADVISOR_MD_PATH, extractPriorIssueTable, extractAgentResponseTable, extractConversationBackground } from "./advisor/history.mjs"
 export { buildAdvisorUserMessage } from "./advisor/messages.mjs"
@@ -51,15 +56,30 @@ const __dirname = dirname(fileURLToPath(import.meta.url))
 // Prompt files — loaded at module init
 // ────────────────────────────────────────
 
-const ADVISOR_ROUND1 = readFileSync(join(__dirname, "prompts", "advisor-round1.md"), "utf8")
+function loadPrompt(file, name) {
+  try {
+    return readFileSync(join(__dirname, "prompts", file), "utf8")
+  } catch {
+    throw new Error(`${name} missing from the installation (prompts/${file}) — reinstall thincoder or restore the file`)
+  }
+}
+
+const ADVISOR_ROUND1 = loadPrompt("advisor-round1.md", "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 = readFileSync(join(__dirname, "prompts", "advisor-round2.md"), "utf8")
-const ADVISOR_ROUND3 = readFileSync(join(__dirname, "prompts", "advisor-round3.md"), "utf8")
+const ADVISOR_ROUND2 = loadPrompt("advisor-round2.md", "advisor-round2.md")
+const ADVISOR_ROUND3 = loadPrompt("advisor-round3.md", "advisor-round3.md")
+// Fallback when advisor-design.md is missing — keep in sync with the real
+// file (table format + workflow steps; a drifted fallback would also break
+// extractPriorIssueTable's DESIGN_TABLE_HEADER matching).
+const ADVISOR_DESIGN_FALLBACK = `You are an independent design reviewer for an engineering-mode project. Review the design document in the changes below. Evaluate: completeness, feasibility, clarity, scope, acceptance criteria. Read METHODOLOGY.md if provided. Produce a review table with | # | Category | Severity | Issue | Suggestion | format.`
 let ADVISOR_DESIGN = ""
-try { ADVISOR_DESIGN = readFileSync(join(__dirname, "prompts", "advisor-design.md"), "utf8") } catch { /* design review unavailable */ }
+// Design review is OPTIONAL (engineering mode only) — silent fallback to the
+// in-code constant is intentional, unlike the mandatory round prompts which
+// must exist for every review (loadPrompt throws a descriptive error there).
+try { ADVISOR_DESIGN = readFileSync(join(__dirname, "prompts", "advisor-design.md"), "utf8") } catch { /* fallback below */ }
 
 // ────────────────────────────────────────
 // System prompt building
@@ -68,15 +88,24 @@ try { ADVISOR_DESIGN = readFileSync(join(__dirname, "prompts", "advisor-design.m
 /**
  * Build the system prompt for an advisor review session.
  * @param {Object} agent — the parent agent
- * @param {Object|null} [_prior] — prior issue table (from extractPriorIssueTable)
+ * @param {Object|null} [prior] — prior issue table (from extractPriorIssueTable)
  * @param {string} [reviewType] — "design" for design review, undefined/"code" for code review
  * @returns {string} the system prompt
  */
-export function buildAdvisorSystemPrompt(agent, _prior, reviewType) {
-  // Design review: dedicated prompt, no convergence rounds
-  if (reviewType === "design") return ADVISOR_DESIGN || `You are an independent design reviewer for an engineering-mode project. Review the design document in the changes below. Evaluate: completeness, feasibility, clarity, scope, acceptance criteria. Read METHODOLOGY.md if provided. Produce a review table with | # | Category | Severity | Issue | Suggestion | format.`
-  const prior = _prior ?? extractPriorIssueTable(agent.history)
-  if (!prior || (agent._advisorRound || 0) === 0) return ADVISOR_ROUND1
+export function buildAdvisorSystemPrompt(agent, prior, reviewType) {
+  // 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") {
+    const p = prior ?? extractPriorIssueTable(agent.history)
+    if (!p || (agent._advisorRound || 0) === 0) {
+      return ADVISOR_DESIGN || ADVISOR_DESIGN_FALLBACK
+    }
+    const round = (agent._advisorRound || 0) + 1
+    if (round === 2) return ADVISOR_ROUND2
+    return ADVISOR_ROUND3
+  }
+  const p = prior ?? extractPriorIssueTable(agent.history)
+  if (!p || (agent._advisorRound || 0) === 0) return ADVISOR_ROUND1
   const round = (agent._advisorRound || 0) + 1
   if (round === 2) return ADVISOR_ROUND2
   return ADVISOR_ROUND3
@@ -92,93 +121,186 @@ export function buildAdvisorSystemPrompt(agent, _prior, reviewType) {
  * 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)
+ * @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) {
-  const prior = _prior ?? extractPriorIssueTable(agent.history)
-  const response = extractAgentResponseTable(agent.history, prior?.sinceIdx ?? 0)
-    || "(Agent did not provide a response table — re-evaluate each issue)"
+export function buildAdvisorFollowUp(agent, prior, scopeFiles = null) {
+  // Convergence follow-up REQUIRES a prior review record. The caller usually
+  // passes it; fall back to extracting it from history (compat for direct
+  // callers/tests). If there is genuinely no prior review, a nullish table
+  // would make the response-table extraction scan from index 0 and possibly
+  // match an unrelated stale table — return a round-1-style message instead.
+  const p = prior ?? extractPriorIssueTable(agent.history)
+  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, p.sinceIdx) || noResponseFallback
   const round = (agent._advisorRound || 0) + 1
   const label = round === 2 ? "Verify Prior Table + Flag New Issues" : "Strict Verification"
 
+  const reminder = round === 2
+    ? "verify every item in the prior issue table and flag only obvious new issues introduced by the fixes"
+    : "strictly verify only the prior issue table — do NOT look for new issues"
   const parts = [
     `## Round ${round} — ${label}`,
     "",
-    `[System reminder: this is round ${round} of the convergence protocol. The system prompt for this round has already narrowed the review scope — follow it: ${round === 2 ? "verify the prior table and flag only obvious new issues introduced by the fixes" : "strictly verify only the prior table — do NOT look for new issues"}.]`,
+    `[System reminder: this is round ${round} of the convergence protocol. ` +
+      `The system prompt for this round has already narrowed the review scope — follow it: ${reminder}.]`,
     "",
-    "## Prior Issue Table",
-    prior?.text ?? "(no prior table — review from scratch)",
+    // Prior issue table IS in the context (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 issues the agent
+    // skipped would silently escape convergence. Restatement risk is handled
+    // mechanically: host-verified citations reject references that do not
+    // match the CURRENT disk state, and fresh sessions exclude old read data.
+    // The agent response table stays as a focus aid ("I fixed X"), not as the
+    // to-verify list.
+    "## Prior Issue Table (verify every item)",
+    p.text,
     "",
-    "## Agent Response",
+    "## Agent Response (fix claims — reference only)",
     response,
     "",
     "## Instructions",
-    round === 2
-      ? "Verify each item in the prior table. Flag any obvious NEW issues introduced by the fixes (crashes, data loss, logic errors — not style). Produce a verification table."
-      : "Strictly verify ONLY the items in the prior table against the CURRENT FILE STATE (use `read` — an empty diff does not mean the fixes are absent). Do NOT look for new issues.",
-    "",
-    "IMPORTANT: the prior issue table is HISTORY — always verify current file state with `read` before judging an item as fixed or unfixed.",
-    // Round-aware evidence rule: "New" entries only exist in round 2 (round 3+ forbids them).
-    `STALE-CONTEXT WARNING: only fresh \`read\` results describe the current state — never judge from earlier snapshots or from \`git diff\` (committed fixes never show in \`git diff HEAD\`). Read the files to verify. Any "Unfixed" entry${round === 2 ? ' (and any "New" entry)' : ""} 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). Uncited findings are unverified and will be ignored.`,
-    "",
-    "Do NOT re-read AGENTS.md / design docs. Verify fix status with `read` only — do not rely on git output: a clean working tree does not mean fixes are absent (they may be committed).",
+    ...buildConvergenceInstructions(round, scopeFiles),
     "",
   ]
   return parts.join("\n")
 }
 
 /**
- * Build or continue the advisor conversation for this run.
- * First call in a run: fresh [system, user] session. Later calls: append a
- * follow-up to the existing session so the advisor keeps its context.
- * After an app restart (session lost), starts a fresh round-1 full review —
- * exploration context is gone, so prior tables from history are not injected.
- * @param {string[]|null} [paths] — code review only: explicit list of file/dir paths to review
+ * Resolve the review surface for the convergence fallback — moved to
+ * messages.mjs so the legacy path shares it (see there).
+ */
+
+/**
+ * Neutralize literal backslash escape sequences ("\x", "\u") that some
+ * OpenAI-compatible servers interpret inside message content ("unexpected end
+ * of hex escape" → 400 — observed 2026-08-06 when the conversation background
+ * quoted "\x" literals). Only sequences that would be INVALID when expanded
+ * are doubled ("\\x" → literal "\x" after server expansion); well-formed
+ * "\xNN" / "\uNNNN" pass through untouched (they expand to a byte/codepoint).
+ */
+export function escapeLiteralEscapes(text) {
+  // (?<!\\) — only a SINGLE backslash counts ("\\x" already doubles the
+  // escape and must pass through untouched); lookbehind is fine on Node 24.
+  // Known limitation (documented, accepted): an ODD backslash run of 3+ (e.g.
+  // "\\\x") leaves the trailing "\x" un-doubled — vanishingly rare in real
+  // conversation text, and the sequence is still valid JSON either way.
+  // The lookahead treats "\x" followed by AT LEAST 2 hex as valid (servers
+  // expand only the first two: "\x1b3" → ESC + "3"); only truncated runs
+  // ("\x" + <2 hex) are doubled.
+  text = String(text ?? "")
+  return text
+    .replace(/(?<!\\)\\(x)(?![0-9a-fA-F]{2})/g, "\\\\$1")
+    .replace(/(?<!\\)\\(u)(?![0-9a-fA-F]{4})/g, "\\\\$1")
+}
+
+
+/**
+ * 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" (default)
  * @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
  */
 export function prepareAdvisorMessages(agent, reviewType, designToken = null, documents = null, paths = null) {
   const prior = extractPriorIssueTable(agent.history)
-  // Design review: always fresh session, no convergence
-  if (reviewType === "design") {
+
+  // Design review round 1: the dedicated full-scope review with the approval
+  // token (an independent gate — it runs even when a prior table 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: buildAdvisorUserMessage(agent, prior, reviewType, designToken, documents, paths) },
+      { role: "user", content: escapeLiteralEscapes(buildAdvisorUserMessage(agent, prior, reviewType, designToken, documents, paths)) },
     ]
   }
-  let session = agent._advisorSession
-  if (session) {
-    // Session exists but no prior table (last review was all-clear or none) —
-    // a follow-up "Verify Prior Table" would be meaningless; start a fresh full review
-    if (!prior) {
-      agent._advisorSession = null
-      // Only reset the round counter on a truly fresh start (no prior reviews at all).
-      // If _advisorRound > 0, there WAS a prior review — it just passed (all-clear).
-      if (!agent._advisorRound) agent._advisorRound = 0
-    } else {
-      // Convergence rounds (2+): replace the system prompt so the round-1
-      // "full-scope review" mandate cannot override the follow-up's narrowed scope.
-      // Without this the model re-runs a full review every round, finds new issues
-      // each time, and the protocol never converges. buildAdvisorSystemPrompt
-      // returns ROUND2 for round 2 and ROUND3 for round 3+.
-      session[0] = { role: "system", content: buildAdvisorSystemPrompt(agent, prior, reviewType) }
-      session.push({ role: "user", content: buildAdvisorFollowUp(agent, prior) })
-      return session
+
+  // 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.
+  // Guard matches buildAdvisorSystemPrompt's ROUND1 condition
+  // (`!prior || _advisorRound === 0`): a stale prior table with _advisorRound 0
+  // (history persists across runAgent calls) must yield a fresh round-1 review —
+  // ROUND1 system prompt + full-scope user message, never the convergence
+  // follow-up (which would contradict the ROUND1 system prompt). The
+  // _advisorRound===0 half was lost in the _mutatedThisRun refactor and is
+  // restored here (regression 67ac851 → 6e15a6b window).
+  // No prior table: 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
+  // toward the cap; 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 issue list
+  // exists without a prior table) — 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 gets its own 5-round budget.
+      agent._advisorRound = 0
     }
+    // Mutations exist → KEEP the round (cap keeps advancing through retries).
+    const user = buildAdvisorUserMessage(agent, prior, reviewType, designToken, documents, paths)
+    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}`),
+      },
+    ]
   }
-  session = [
+
+  // 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)
+  return [
     { role: "system", content: buildAdvisorSystemPrompt(agent, prior, reviewType) },
-    { role: "user", content: buildAdvisorUserMessage(agent, prior, reviewType, designToken, documents, paths) },
+    { role: "user", content: escapeLiteralEscapes(buildAdvisorFollowUp(agent, prior, scopeFiles)) },
   ]
-  // Fresh session. Only reset round if this is truly the first review.
-  // If _advisorRound > 0, there was a prior review that passed (all-clear).
-  if (!agent._advisorRound) agent._advisorRound = 0
-  if (!prior) {
-    // Tell the advisor why no prior issue table is present
-    session[1] = {
-      role: "user",
-      content: `[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${session[1].content}`,
-    }
-  }
-  return session
 }

package/src/agent/completion.mjs

@@ -6,6 +6,7 @@
  */
 import { isDocFile } from "../advisor/repos.mjs"
 import { pushReal } from "../context.mjs"
+import { MAX_ADVISOR_ROUNDS } from "../advisor/run.mjs"
 
 /** True when this run mutated at least one CODE file. Mirrors agent.mjs:hasCodeMutations. */
 function hasCodeMutations(agent) {
@@ -117,12 +118,18 @@ export function handleCompletion(agent, response, depth, turn, guardPushbacks, h
   }
 
   // --- advisor guard: review of mutated files before completion ---
-  // OPT-IN via advisor.enabled + guard!==false, and NEVER in engineering mode.
+  // Active by default when advisor.enabled is set (opt-out via guard: false),
+  // and NEVER in engineering mode.
   const cfg = agent.config?.advisor
   const advisorReview = cfg?.enabled && cfg?.guard !== false
   if (depth === 0 && advisorReview && !agent.config?.agent?.engineering) {
+    // Cap sync: beyond MAX_ADVISOR_ROUNDS the advisor tool refuses to review
+    // (run.mjs convergence cap) — pushing back further would loop forever
+    // (fix → pushback → cap-refused call → fix …). The cap message from the
+    // last accepted review stands; the user decides manually.
     if (agent._mutatedThisRun && !agent._calledAdvisorThisRun && hasCodeMutations(agent)
-        && advisorPushbacks < MAX_ADVISOR_PUSHBACKS) {
+        && advisorPushbacks < MAX_ADVISOR_PUSHBACKS
+        && (agent._advisorRound || 0) < MAX_ADVISOR_ROUNDS) {
       advisorPushbacks++
       pushReal(agent, { role: "assistant", content: response.content })
       agent.history.push({

package/src/agent/dispatch.mjs

@@ -152,6 +152,15 @@ export async function executeToolCalls(agent, toolByName, toolCalls, callbacks,
       if (!item.tool?.readonly && item.args) {
         snapshotForUndo(agent, item.toolCall.name, item.args, agent.cwd)
       }
+      // M2 ACP: route fs tools through the client (IDE buffer / diff review).
+      // toolRouter returns { handled: true, result } to short-circuit execution.
+      if (callbacks.toolRouter) {
+        const routed = await callbacks.toolRouter(item.toolCall.name, item.args)
+        if (routed?.handled) {
+          callbacks.onToolResult?.(item.toolCall.name, routed.result)
+          return { ...item, result: routed.result, ok: true }
+        }
+      }
       const rawResult = await item.tool.execute(item.args, {
         cwd: agent.cwd,
         agent,
@@ -172,6 +181,11 @@ export async function executeToolCalls(agent, toolByName, toolCalls, callbacks,
     } catch (error) {
       // Persist to ~/.thincoder/tool-errors/ for post-mortem; only pass message to the model (stack traces confuse LLMs and may leak paths)
       logToolError(item.toolCall.name, item.args, error)
+      // User interrupt (Ctrl+C / Ctrl+I) must propagate, not become a tool error:
+      // swallowing it here would make the parent keep looping while the user
+      // asked to stop — worst case with subagents, where the child runs its
+      // whole turn budget and the interrupt appears to do nothing.
+      if (signal?.aborted) throw error
       runHooks("PostToolUseFailure", { agent, toolName: item.toolCall.name, toolArgs: item.args, error }).catch(() => {})
       // Build contextual error: tool name + key args so the model can reason about what went wrong
       const ctxParts = []

package/src/agent-tools/advisor.mjs

@@ -81,8 +81,8 @@ export const advisorTool = {
     "Use type='code' (default) to review code changes after implementation — pass paths=[...] to specify which files or directories to review, or documents=[...] for acceptance criteria context. " +
     "The advisor is an independent read-only sub-agent that explores the codebase, " +
     "reads files, and traces callers via grep/lsp. " +
-    "For code review: round 1 does a full review, round 2 verifies the prior table, " +
-    "round 3+ strictly checks only the prior table — convergence, not divergence. " +
+    "For code review: round 1 does a full review, round 2 verifies the agent's fix claims, " +
+    "round 3+ strictly checks only the fix claims — convergence, not divergence. " +
     "For design review: single-pass review against methodology and requirements. " +
     "Review criteria come from .thincoder/advisor.md (if present) or sensible defaults. " +
     "After the review, you MUST produce a response table (see discipline rules for format). " +
@@ -94,7 +94,7 @@ export const advisorTool = {
       paths: {
         type: "array",
         items: { type: "string" },
-        description: "Code files or directories to review (for code review). Required unless documents is provided. The advisor reviews git diff filtered to these paths.",
+        description: "Code files or directories to review (for code review). Required unless documents is provided. The advisor reads the files/directories listed here — it has no git tool and never inspects diffs.",
       },
       documents: {
         type: "array",
@@ -110,11 +110,13 @@ export const advisorTool = {
     const agent = ctx.agent
     const reviewType = args.type || "code"
     const documents = args.documents || null
-    const paths = args.paths || null
+    // Scope fallback: the runtime mutation record (zero git) covers guard-triggered
+    // reviews where the model did not pass explicit paths.
+    const paths = args.paths || (agent._touchedFiles?.length ? [...agent._touchedFiles] : null)
 
     // Code review must have a scope — no implicit fallback.
     if (reviewType !== "design" && !paths && !documents) {
-      return "Advisor: no review scope specified. Provide paths (files/directories to review) or documents (acceptance criteria — code diff is still used)."
+      return "Advisor: no review scope specified. Provide paths (files/directories to review) or documents (acceptance criteria context)."
     }
 
     // Design review: validate that documents are in docs/ or are recognized doc files
@@ -129,11 +131,10 @@ export const advisorTool = {
       }
     }
 
-    // Design review: always starts from round 1 (no convergence)
-    if (reviewType === "design") {
-      agent._advisorRound = 0
-      agent._advisorSession = null
-    }
+    // Design review: NO round reset — design reviews share the 5-round convergence
+    // budget with code reviews (round advances in agent.mjs; cap in run.mjs).
+    // Session reset also removed: design rounds 2+ continue the advisor session
+    // like code reviews (fix claims + round-aware prompts).
 
     // Generate the design token BEFORE the review and inject it into the advisor's prompt.
     // The advisor (LLM) decides pass/fail itself and echoes the token only on approval —

package/src/agent-tools/subagent.mjs

@@ -180,7 +180,7 @@ export const subagentTool = {
         ? (name, args) => ctx.callbacks.onToolCall(`${relayPrefix}${name}`, args)
         : null,
     }
-    const childRunOpts = { depth: (ctx.depth ?? 0) + 1, maxTurns: ctx.agent?.config?.agent?.subagentTurns ?? DEFAULT_SUBAGENT_TURNS }
+    const childRunOpts = buildChildRunOpts(ctx)
     let report = await runAgent(child, input, childOpts, childRunOpts)
 
     // Report too short = incomplete handoff: send back for expansion once (inspired by kimi-code's summaryPolicy: min 200 chars, retry 1 time).
@@ -203,6 +203,20 @@ export const subagentTool = {
   },
 }
 
+/**
+ * Child agent run options — the parent's abort signal MUST propagate to the
+ * child: without it, Ctrl+C aborts the parent's controller but the child keeps
+ * running its full turn budget (up to subagentTurns) while the parent awaits —
+ * the interrupt appears to do nothing.
+ */
+export function buildChildRunOpts(ctx) {
+  return {
+    depth: (ctx.depth ?? 0) + 1,
+    maxTurns: ctx.agent?.config?.agent?.subagentTurns ?? DEFAULT_SUBAGENT_TURNS,
+    signal: ctx.signal ?? null,
+  }
+}
+
 /**
  * Merge an eng-coder child's mutations into the parent agent's bookkeeping.
  * The parent must stay aware of delegated file changes: `_touchedFiles` enables
@@ -210,13 +224,20 @@ export const subagentTool = {
  * pushback for review. Prior verify/advisor state is invalidated because it
  * judged an older state.
  *
- * `_advisorRound` is reset to 0: merged code is new code that deserves a fresh
- * convergence budget. Mirrors the design-review reset semantics.
+ * `_advisorRound` is NOT reset: merged code enters the CURRENT convergence
+ * cycle. Resetting here would break the review→fix→re-review loop (the parent
+ * reviews, spawns an eng-coder to fix, merges, reviews again — every merge
+ * would restart at round 1 and the 5-round cap could never be reached).
+ * `_calledAdvisorThisRun` IS cleared so the merged code triggers a fresh
+ * advisor call (the guard demands review of new mutations).
  *
  * Returns true when mutations were merged (kept for future caller checks).
  */
 export function mergeChildMutations(parent, child) {
-  if (!child._mutatedThisRun) return false
+  // A child claiming mutations without any touched file is a misbehaving
+  // child (or a bookkeeping bug) — do not propagate an empty mutation claim
+  // to the parent's guard state.
+  if (!child._mutatedThisRun || !(child._touchedFiles?.length)) return false
   parent._mutatedThisRun = true
   for (const abs of child._touchedFiles ?? []) {
     if (!parent._touchedFiles.includes(abs)) parent._touchedFiles.push(abs)
@@ -226,10 +247,7 @@ export function mergeChildMutations(parent, child) {
     parent._verifiedThisRun = false
     parent._verifyPassed = undefined
   }
-  // Fresh code → fresh convergence budget + stale session cleanup.
-  // _advisorRound reset ensures new code gets a full round-1 review;
-  // _advisorSession prevents cross-contamination between reviews.
-  parent._advisorRound = 0
+  // Stale session cleanup only — the round counter survives (see above).
   parent._advisorSession = null
   return true
 }

package/src/agent.mjs

@@ -404,18 +404,18 @@ export async function runAgent(agent, input, callbacks = {}, { depth = 0, signal
         if (toolCall.name === "verify") agent._verifiedThisRun = true
         if (toolCall.name === "advisor") {
           agent._calledAdvisorThisRun = true
-          // Design reviews are a separate gate with no convergence protocol —
-          // they must not consume code-review rounds (MAX_ADVISOR_ROUNDS budget).
+          // All advisor calls (code and design) share the 5-round convergence
+          // budget — each advances _advisorRound toward MAX_ADVISOR_ROUNDS.
           // Always advance the round — the convergence protocol cares about
           // how many reviews have run (round 1→2→3→4→5), not how many succeeded.
           // A failed/interrupted review is still a review attempt and should use
           // the next round's prompt on retry.
           try {
-            const advArgs = JSON.parse(toolCall.arguments || "{}")
-            if (advArgs.type !== "design") agent._advisorRound++
+            JSON.parse(toolCall.arguments || "{}")
           } catch {
-            agent._advisorRound++
+            /* arguments unparseable — still counts as a review attempt */
           }
+          agent._advisorRound++
         }
         if (FILE_MUTATORS.has(toolCall.name)) {
           const args = JSON.parse(toolCall.arguments)

package/src/prompts/advisor-round1.md

@@ -17,15 +17,21 @@ Budget rules:
 - **Batch everything**: multiple `read` calls in one reply, multiple `grep` calls in one reply. Serializing tool calls wastes your round budget.
 
 Rules:
-- First judge the task from the conversation background: if the changes are clearly non-code (documentation, comments, version bumps, config metadata) and cannot affect runtime behavior, reply immediately with the all-clear phrase — do NOT spend tool calls exploring.
+- First judge the task from the conversation background: if the changes are clearly non-code and cannot affect runtime behavior, reply immediately with the all-clear phrase — `"All clear — no code changes to review."` (the host recognizes it via the "all clear" / "no 🔴" / "review passed" / "no issues found" markers, matched case-insensitively) — do NOT spend tool calls exploring. This applies to static docs, README, and CHANGELOG files. Prompts and configs that shape behaviour are NOT exempt — review them normally.
+- **Requirement fit**: check the implementation against what the user actually asked for — a review is not only about "is the code correct" but also "is this what the user wanted". Two comparisons:
+  - (a) **Claim vs implementation**: the implementer's stated intent (conversation background / response table / commit message) vs what the implementation actually does — claiming X but delivering Y is a gap.
+  - (b) **Expectation vs shape**: explicit user expectations in the background vs the delivered shape — "asked for A, got B" (e.g. "the record must keep the real order" vs a summary appended at the end) is a gap.
+  - **Known limit**: the conversation background only includes the last 3 user–assistant exchanges — older user expectations may not be visible. (a) is the primary check (needs only recent context); (b) is best-effort — check what the background shows, do NOT treat an invisible expectation as a gap.
+  - **Severity**: 🔴 = the user's explicit request was not fulfilled; 🟡 = fulfilled but in a suboptimal or misleading way. Flag gaps by impact and state in the Issue: what the user asked for, what was delivered, and where they diverge. Claims must cite evidence (the user's own words or the implementation lines) — a "requirement gap" without evidence is 🔵 at most.
 - Reply in the same language as the conversation background.
 - Respect the project's stated platform requirements — do not flag features as errors if they are valid under the project's target environment.
 - Output a Markdown table. This table becomes the sole basis for convergence in later rounds — be thorough.
 | # | File | Severity | Issue | Suggestion |
 |---|------|----------|-------|------------|
-| 1 | src/x.mjs | 🔴 | ... | ... |
+| 1 | src/example.mjs | 🔴 | ... | ... |
 - Order by severity: 🔴 Critical · 🟡 Advisory · 🔵 Style.
 - For each issue state: which file, what the problem is, why it is a problem, how to fix it.
 - Cover everything now. Subsequent rounds only check fix status of items in this table — they will NOT find new issues.
 - Stop calling tools once you are ready to produce the review table.
+- **Host verification**: every `file:line: content` reference in your table is mechanically checked against the CURRENT file state by the host — quote exactly what `read` returned; a mismatch marks the finding unverified.
 - **Pass/fail**: if there are NO 🔴 (Critical) issues, the review passes. 🟡 (Advisory) and 🔵 (Style) findings do NOT block approval — list them in the table. If there is ANY 🔴 issue, list it and do not claim the review passed.