thincoder 0.12.12 → 0.12.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thincoder",
-  "version": "0.12.12",
+  "version": "0.12.13",
   "description": "Thin coding agent - zero dependencies, no build step, Node.js native. Sharp code, zero bloat.",
   "keywords": [
     "ai",

package/src/advisor/convergence.mjs

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

package/src/advisor/history.mjs

@@ -1,16 +1,11 @@
 /**
- * advisor/history.mjs — advisor history extraction: issue/response tables and conversation background.
+ * advisor/history.mjs — advisor history extraction: agent response table and conversation background.
  */
 import { readFileSync } from "node:fs"
 import { join } from "node:path"
 
 export const ADVISOR_MD_PATH = ".thincoder/advisor.md"
-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 = "| # | 文件 | 严重程度 | 问题描述 | 建议修复 |"
 
 const DEFAULT_CRITERIA = `Review the code changes, focusing on:
 1. Correctness: logic errors, edge cases, off-by-one, incomplete modifications
@@ -20,77 +15,28 @@ const DEFAULT_CRITERIA = `Review the code changes, focusing on:
 5. Maintainability: vague naming, missing comments, overly complex logic`
 
 /**
- * Extract the most recent advisor review table from history.
- * Returns { text, sinceIdx } where sinceIdx is the index of the advisor call's
- * own history entry — extractAgentResponseTable skips it (role is "tool", not
- * "assistant") and scans forward for the agent's response table.
- * Returns null when: no advisor call, empty output, or the last review is
- * all-clear (nothing to follow up on).
+ * Extract the agent's response table (| # | Action | Detail |) — the fix-claims
+ * reference for convergence rounds.
+ * Semantics (decision 2026-08-08): without sinceIdx, scan BACKWARD for the
+ * MOST RECENT response table (no prior-table index is carried anymore — the
+ * agent response is a focus aid only; format drift falls back to the
+ * no-response text and never drives control flow). With sinceIdx, scan
+ * FORWARD from it (legacy callers/tests).
+ * @param {Array} history — message history
+ * @param {number} [sinceIdx] — legacy: start scanning forward from this index
+ * @returns {string|null} the response table content, or null
  */
-// 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) {
-  // 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.
-  const partiallyFixedRe = /\bunfixed\b|未修复|❌|\bfailed\b/i
+export function extractAgentResponseTable(history, sinceIdx) {
   const entries = Array.isArray(history) ? history : []
-
-  for (let i = entries.length - 1; i >= 0; i--) {
-    const m = entries[i]
-    if (m.role !== "tool" || typeof m.content !== "string") continue
-    // Only review outputs carry one of these table headers. Matched at LINE START:
-    // an `includes()` match would also fire on advisor output that quotes the
-    // 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
-    const lower = text.toLowerCase()
-    // Has a Status column? (English convergence format or any table with a Status-like
-    // 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) {
-      // 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
+  if (sinceIdx !== undefined) {
+    for (let i = sinceIdx; i < entries.length; i++) {
+      const m = entries[i]
+      if (m.role !== "assistant" || typeof m.content !== "string") continue
+      if (m.content.includes(AGENT_RESPONSE_HEADER)) return m.content
     }
-    // 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 }
+    return null
   }
-  return null
-}
-
-/** True when some line of `text` starts with `header` — table headers always sit at line start. */
-function lineHasHeader(text, header) {
-  return text.split("\n").some((l) => l.trimStart().startsWith(header))
-}
-
-/**
- * Extract the agent's response table (| # | Action | Detail |) that follows
- * the advisor review. Returns null when missing or no advisor review precedes.
- */
-export function extractAgentResponseTable(history, sinceIdx) {
-  const entries = Array.isArray(history) ? history : []
-  for (let i = sinceIdx ?? 0; i < entries.length; i++) {
+  for (let i = entries.length - 1; i >= 0; i--) {
     const m = entries[i]
     if (m.role !== "assistant" || typeof m.content !== "string") continue
     if (m.content.includes(AGENT_RESPONSE_HEADER)) return m.content

package/src/advisor/messages.mjs

@@ -3,10 +3,105 @@
  * Split out of advisor.mjs to keep it under the 300-line advisory threshold
  * (.thincoder/advisor.md). System prompts live in advisor.mjs / prompts/.
  */
-import { readFileSync } from "node:fs"
-import { resolve, join, relative } from "node:path"
+import { readFileSync, existsSync } from "node:fs"
+import { resolve, join, relative, dirname, sep } from "node:path"
+import { specForModel } from "../config.mjs"
 import { findReviewRepos, collectRepoSnapshots, collectChangedFiles } from "./repos.mjs"
-import { loadAdvisorMd, extractConversationBackground, extractAgentResponseTable, extractPriorIssueTable } from "./history.mjs"
+import { buildConvergenceBody, buildConvergenceInstructions } from "./convergence.mjs"
+import { loadAdvisorMd, extractConversationBackground, extractAgentResponseTable } from "./history.mjs"
+
+/** Project guide (AGENTS.md) injection budget — decision 2026-08-08:
+ *  NO fixed truncation; long-context models (1M+) get up to 5% of their context
+ *  window for the doc map, small windows still get a floor so the map is always
+ *  visible. The map is what tells the reviewer WHERE the requirements docs live
+ *  (requirement-fit is judged against those docs, not the conversation only). */
+const PROJECT_GUIDE_MIN = 8192 // chars — floor for small-window models
+const PROJECT_GUIDE_FRACTION = 0.05 // 5% of the reviewer model's context window
+
+/**
+ * Discover the project root for the review — user decision 2026-08-08:
+ * the project root is a SUBDIRECTORY of the working directory, never an
+ * ancestor above it. Priority:
+ *   1. Walk UP from each review-scope file's directory, bounded by cwd —
+ *      the NEAREST AGENTS.md inside the workspace wins. In a monorepo this is
+ *      the subproject's own doc map even when cwd itself has an AGENTS.md
+ *      (a workspace-level meta map must not shadow the subproject guide).
+ *   2. No scope files / nothing found → cwd (single project; the walk's
+ *      last step naturally lands on cwd's own AGENTS.md when it exists).
+ * @param {string} cwd — the agent's working directory (workspace root)
+ * @param {string[]} scopeFiles — cwd-relative review-scope paths (may be empty)
+ * @returns {string|null} absolute project root with an AGENTS.md, or null
+ */
+function findProjectRoot(cwd, scopeFiles) {
+  // Normalize separators before comparing: input paths may use either
+  // convention (join() → "\\" on Windows; tool args / tests → "/"). Mixed
+  // styles made isInside(cwd + sep) miss legitimately nested paths.
+  const norm = (p) => p.replaceAll("\\", "/")
+  const isInside = (dir) => {
+    const d = norm(dir)
+    const c = norm(cwd)
+    return d === c || d.startsWith(c + "/")
+  }
+  for (const f of scopeFiles) {
+    let dir = dirname(resolve(cwd, f))
+    while (isInside(dir) && dir !== dirname(dir)) {
+      if (existsSync(join(dir, "AGENTS.md"))) return dir
+      dir = dirname(dir)
+    }
+  }
+  // No scope files, or none found in the walk — cwd itself (its AGENTS.md is
+  // checked as the walk's final step for scope files; for empty scopes, check
+  // it explicitly so a bare cwd project still gets its guide).
+  if (existsSync(join(cwd, "AGENTS.md"))) return cwd
+  return null
+}
+
+/**
+ * Inject the project guide (AGENTS.md) into the review message. AGENTS.md is the
+ * project's doc map — it defines the structure and where requirements/design
+ * documents live. The reviewer must see it FIRST: requirement-fit is judged
+ * against the documents it points to, with the conversation background as a
+ * supplement. Absent AGENTS.md degrades honestly (no pretending there is a map).
+ * @param {Object} agent — the parent agent
+ * @param {string[]} parts — message parts (mutated)
+ * @param {string[]} [scopeFiles] — cwd-relative review-scope paths for project-root discovery
+ * @returns {string|null} the discovered project root (abs), or null when no guide
+ */
+function injectProjectGuide(agent, parts, scopeFiles = []) {
+  parts.push("## Project Guide (AGENTS.md)")
+  const root = findProjectRoot(agent.cwd, scopeFiles)
+  const path = root ? join(root, "AGENTS.md") : null
+  let text
+  if (!path) {
+    parts.push("(No AGENTS.md found — neither at the working directory root nor in any review-scope subdirectory. Judge the user's requirements from the conversation background, and say so explicitly if the requirements are unclear.)")
+    parts.push("")
+    return null // no guide — requirement-fit falls back to the conversation
+  }
+  try {
+    text = readFileSync(path, "utf8")
+  } catch (e) {
+    if (e.code !== "ENOENT") {
+      // File exists but is unreadable (EACCES etc.) — log, don't masquerade as "not found".
+      console.warn(`[advisor] AGENTS.md unreadable at ${path}: ${e.message}`)
+    }
+    parts.push("(No AGENTS.md found — neither at the working directory root nor in any review-scope subdirectory. Judge the user's requirements from the conversation background, and say so explicitly if the requirements are unclear.)")
+    parts.push("")
+    return null // no guide — requirement-fit falls back to the conversation
+  }
+  // readFileSync succeeded — compute the budget OUTSIDE the try so a spec
+  // lookup failure can never masquerade as "no AGENTS.md".
+  const ctx = specForModel(agent.provider?.model ?? "").context
+  const cap = Math.max(PROJECT_GUIDE_MIN, Math.floor(ctx * PROJECT_GUIDE_FRACTION))
+  const shown = text.length <= cap
+    ? text
+    : [...text].slice(0, cap).join("") + `\n\n…(truncated at ${cap} chars — read the full file if you need more)` // codepoint-safe slice: no broken surrogate pairs at the boundary
+  parts.push(`<!-- Project root: ${relative(agent.cwd, path).split(sep).join("/")} (inferred from the review scope under ${agent.cwd}) -->`)
+  parts.push("This file defines the project's structure and where its requirements/design documents live. Read the documents it points to — the user's requirements live THERE, not only in the conversation background.")
+  parts.push("")
+  parts.push(shown)
+  parts.push("")
+  return root // guide injected — requirement-fit criteria apply (truthy root)
+}
 
 /**
  * Build the user message for an advisor review session.
@@ -21,12 +116,23 @@ import { loadAdvisorMd, extractConversationBackground, extractAgentResponseTable
  * @returns {string} the user message
  */
 export function buildAdvisorUserMessage(agent, prior, reviewType, designToken = null, documents = null, paths = null) {
-  const p = prior ?? extractPriorIssueTable(agent.history)
+  // prior = the full prior review output (string) when a convergence round is
+  // being built (decision 2026-08-08 — verbatim injection, model understands it).
+  // Deterministic: only _advisorRound > 0 with stored output counts.
+  const p = prior ?? ((agent._advisorRound || 0) > 0 ? agent._lastAdvisorOutput : null)
 
   const parts = []
   const docList = Array.isArray(documents) ? documents.filter((d) => typeof d === "string" && d.trim()) : []
   const pathList = Array.isArray(paths) ? [...new Set(paths.filter((p) => typeof p === "string" && p.trim()))] : []
 
+  // Project guide FIRST in EVERY review path (code AND design round 0): the map
+  // to the requirements docs is needed for design reviews too (design must fit
+  // the requirements, not just the methodology). Design round 0 early-returns
+  // below — the guide must be injected before that return. Project root is
+  // discovered from the review scope (code paths AND design-doc paths, so a
+  // documents-only design review still finds the subproject guide).
+  const guideRoot = injectProjectGuide(agent, parts, [...pathList, ...docList])
+
   // Design review: simplified message — focus on the design doc, not code
   if (reviewType === "design" && (agent._advisorRound || 0) === 0) {
     const repos = findReviewRepos(agent)
@@ -66,10 +172,11 @@ export function buildAdvisorUserMessage(agent, prior, reviewType, designToken =
       }
     }
 
-    // Engineering mode: inject project methodology
+    // Engineering mode: inject project methodology (resolved from the
+    // DISCOVERED project root — in a monorepo that is the subproject, not cwd)
     if (agent.config?.agent?.engineering) {
       try {
-        const mpath = resolve(agent.cwd, "METHODOLOGY.md")
+        const mpath = resolve(guideRoot ?? agent.cwd, "METHODOLOGY.md")
         const methodology = readFileSync(mpath, "utf8")
         parts.push("## Project Methodology")
         parts.push("Evaluate the design against this methodology:")
@@ -85,8 +192,9 @@ export function buildAdvisorUserMessage(agent, prior, reviewType, designToken =
       parts.push("1. Read the design document fully. Read METHODOLOGY.md to understand the project's standards.")
     }
     parts.push("2. Review against: completeness (all requirements covered?), feasibility (can this be built?), clarity (specific enough?), acceptance criteria (verifiable?), scope (appropriate?).")
-    parts.push("3. Do NOT run git diff or look for code changes — there are none at this stage.")
-    parts.push("4. If you find issues, produce your review table with the format: | # | Category | Severity | Issue | Suggestion |. If the design passes, no table is needed.")
+    parts.push("3. If the ## Project Guide (AGENTS.md) section above is present, also check requirement fit: does the design match what the requirements documents it points to actually ask for?")
+    parts.push("4. Do NOT run git diff or look for code changes — there are none at this stage.")
+    parts.push("5. If you find issues, produce your review table with the format: | # | Category | Severity | Issue | Suggestion |. If the design passes, no table is needed.")
     if (designToken) {
       parts.push("")
       parts.push("## Approval Signal")
@@ -99,24 +207,22 @@ export function buildAdvisorUserMessage(agent, prior, reviewType, designToken =
   // 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.
+  // buildAdvisorUserMessage with a stored prior review output. Kept to avoid
+  // breaking those. Same rule as buildAdvisorFollowUp: the FULL prior review
+  // output is injected verbatim (decision 2026-08-08 — the model understands it;
+  // no table/header/phrase parsing).
+  // NOTE: this legacy path does NOT apply escapeLiteralEscapes (that lives in
+  // advisor.mjs and importing it here would create a top-level module cycle).
+  // Direct callers must escape the injected output themselves if the parent
+  // conversation can quote literal "\x"/"\u" sequences (server 400 risk).
   if (p && (agent._advisorRound || 0) > 0) {
     const scopeFiles = resolveScopeFiles(agent, paths)
-    const response = extractAgentResponseTable(agent.history, p.sinceIdx)
+    const response = extractAgentResponseTable(agent.history)
       || (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 (verify every item)")
-    parts.push(p.text)
-    parts.push("")
-    parts.push("## Agent Response (fix claims — reference only)")
-    parts.push(response)
+    parts.push(buildConvergenceBody(p, response, round, scopeFiles))
     parts.push("")
     parts.push("---")
     parts.push("")
@@ -155,12 +261,19 @@ export function buildAdvisorUserMessage(agent, prior, reviewType, designToken =
   const criteria = loadAdvisorMd(agent.cwd)
   parts.push("## Review Criteria")
   parts.push(criteria)
+  if (guideRoot) {
+    // Requirement-fit is a first-class dimension when the project guide was
+    // found — the criteria file (advisor.md) may not mention it (legacy).
+    parts.push("")
+    parts.push("Additional criterion: **requirement fit** — does the implementation match what the requirements documents (referenced by the Project Guide above) actually ask for?")
+  }
   parts.push("")
 
   // Engineering mode: inject project methodology so advisor knows the rules
+  // (resolved from the DISCOVERED project root — subproject in a monorepo)
   if (agent.config?.agent?.engineering) {
     try {
-      const mpath = resolve(agent.cwd, "METHODOLOGY.md")
+      const mpath = resolve(guideRoot ?? agent.cwd, "METHODOLOGY.md")
       const methodology = readFileSync(mpath, "utf8")
       parts.push("## Project Methodology (Engineering Mode)")
       parts.push("The project follows this methodology. Evaluate the changes against it:")
@@ -169,7 +282,9 @@ export function buildAdvisorUserMessage(agent, prior, reviewType, designToken =
     } catch { /* file doesn't exist — skip */ }
   }
 
-  // Instructions — round-aware: re-reviews skip convention discovery entirely
+  // Instructions — round-aware: re-reviews skip convention discovery entirely.
+  // These are SUPPLEMENTARY reminders to the system prompt's numbered workflow —
+  // deliberately not renumbered as a competing sequence.
   const isReReview = p && (agent._advisorRound || 0) > 0
   parts.push("## Instructions")
   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.")
@@ -177,7 +292,9 @@ export function buildAdvisorUserMessage(agent, prior, reviewType, designToken =
     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("2. " + (guideRoot
+      ? "The `## Project Guide (AGENTS.md)` section above maps the project — read the requirements/design documents it points to (they are the primary reference for requirement-fit). Use `read` to load those documents."
+      : "No AGENTS.md was found at the project root — rely on the conversation background for the user's requirements. If the requirements are unclear, state so explicitly."))
     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.")
@@ -198,7 +315,8 @@ export function buildAdvisorUserMessage(agent, prior, reviewType, designToken =
  */
 export function resolveScopeFiles(agent, paths) {
   const normalize = (p) => {
-    const abs = p.startsWith(agent.cwd) ? p : join(agent.cwd, p)
+    // sep-guarded prefix check — /proj vs /project-other must not collide
+    const abs = p === agent.cwd || p.startsWith(agent.cwd + sep) ? p : join(agent.cwd, p)
     return relative(agent.cwd, abs)
   }
   if (Array.isArray(paths)) return [...new Set(paths.map(normalize))]
@@ -208,29 +326,3 @@ export function resolveScopeFiles(agent, paths) {
   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.",
-  ]
-}
-

package/src/advisor/repos.mjs

@@ -99,6 +99,15 @@ export function collectChangedFiles(repos, cwd) {
 
 const DOC_FILE = /(?:^|[/\\])(?:LICENSE|NOTICE|CHANGELOG|AUTHORS)(?:\.\w+)?$|\.(?:md|markdown|mdx|txt|rst|adoc)$/i
 
+/** Temporary/scratch files that must NOT count as code mutations: tmp-* named
+ *  scratch scripts (tmp-c1.mjs, tmp-check.mjs…) and .tmp/.temp extensions.
+ *  The advisor/verify guards skip these — a throwaway diagnostic script is not
+ *  a code change, and writing one must not push the agent into a review loop.
+ *  NOTE: matches the tmp-* basename at ANY directory depth, not just root —
+ *  intentional: _touchedFiles stores absolute paths, so the pattern must work
+ *  for "D:/proj/tmp-check.mjs" as well as a bare "tmp-check.mjs". */
+const TEMP_FILE = /(?:^|[/\\])tmp-[^/\\]+$|\.(?:tmp|temp)$/i
+
 /** True when a path matches the doc/license pattern by extension or name.
  *  NOTE: this is extension-based only — it does NOT exclude src/ paths.
  *  Callers must separately check the src/ prefix for product-code semantics
@@ -108,6 +117,35 @@ export function isDocFile(p) {
   return DOC_FILE.test(p ?? "")
 }
 
+/** True when a path is a throwaway temp file (tmp-* name or .tmp/.temp ext).
+ *  Excluded from code-mutation detection so scratch scripts don't trigger
+ *  advisor/verify guards. */
+export function isTempFile(p) {
+  return TEMP_FILE.test(p ?? "")
+}
+
+/**
+ * True when this run mutated at least one CODE file. Shared single source of
+ * truth for the advisor/verify guards (agent.mjs + agent/completion.mjs).
+ * Doc-only changes (docs/, *.md, LICENSE…) must NOT trigger the guards — the
+ * design phase edits docs/ and must not be pushed to a code review. Temp/scratch
+ * files (tmp-*, .tmp, .temp) are excluded too — a throwaway diagnostic script
+ * is not a code change. Mutations without a known path (tools outside
+ * FILE_MUTATORS) are treated as code — cannot tell, so guard conservatively.
+ * Product-code semantics: anything under src/ (incl. src/prompts/*.md) is code;
+ * anything else that isn't a doc or temp file is code.
+ * NOTE: _touchedFiles stores ABSOLUTE paths (join(cwd, p)), so the src/ check
+ * matches a path component (works for "src/..." and "D:\...\src\..." alike),
+ * not a bare ^src prefix — the literal ^src[\\/] form would be dead code here.
+ */
+export function hasCodeMutations({ _touchedFiles, _mutatedThisRun }) {
+  const files = _touchedFiles ?? []
+  if (files.length === 0) return _mutatedThisRun
+  // src/ is unconditional — anything under src/ is code regardless of its name
+  // (incl. src/tmp-*.mjs). Temp/doc exclusions apply only outside src/.
+  return files.some((p) => /(?:^|[\\/])src[\\/]/.test(p) || (!isTempFile(p) && !isDocFile(p)))
+}
+
 /** True when all changed files across repos are documentation (md/txt/LICENSE etc.).
  *  Anything under src/ (incl. src/prompts/*.md) counts as product code —
  *  isProductCode semantics, consistent with the design gate. */
@@ -126,7 +164,9 @@ export function isDocOnlyChange(repos, cwd) {
     for (const line of status.split("\n")) {
       // porcelain: "XY path" or "XY old -> new" (rename)
       const filePath = line.slice(3).split(" -> ").pop().replace(/^"|"$/g, "")
+      // src/ is unconditional product code (even src/tmp-*.mjs) — check before the temp skip
       if (/^src[\\/]/.test(filePath) || !DOC_FILE.test(filePath)) return false
+      if (isTempFile(filePath)) continue
     }
   }
   return sawChanges

package/src/advisor/run.mjs

@@ -6,7 +6,6 @@ import { chat } from "../provider/core.mjs"
 import { findProvider, specForModel } from "../config.mjs"
 import { toOpenAISchema } from "../tools/index.mjs"
 import { prepareAdvisorMessages } from "../advisor.mjs"
-import { extractPriorIssueTable } from "../advisor/history.mjs"
 import { appendCitationReport } from "./citations.mjs"
 
 const MAX_ADVISOR_TURNS = 100
@@ -376,9 +375,10 @@ export async function runAdvisorReview(agent, reviewType, callbacks, designToken
   // blocks the next call. 5 rounds max; after that the review is never pushed back
   // (the caller decides: accept, manual re-check, or /new to reset).
   if ((agent._advisorRound || 0) >= MAX_ADVISOR_ROUNDS) {
-    // 提取未解决的问题，给出更具体的指导
-    const prior = extractPriorIssueTable(agent.history)
-    const unfixed = prior ? extractUnfixedIssues(prior.text) : []
+    // Summarize unresolved items from the last review output for guidance
+    // (line-level status-word scan — no table-header parsing, decision 2026-08-08).
+    const prior = agent._lastAdvisorOutput
+    const unfixed = prior ? extractUnfixedIssues(prior) : []
     
     let message = `Advisor: convergence cap reached after ${MAX_ADVISOR_ROUNDS} rounds.\n`
     if (unfixed.length > 0) {
@@ -409,6 +409,18 @@ export async function runAdvisorReview(agent, reviewType, callbacks, designToken
     let final = result
     if (!result.trimStart().startsWith("Advisor:")) {
       final = appendCitationReport(result, advisorCwd)
+      // Success path: keep the FULL review output for convergence rounds —
+      // round 2+ injects this verbatim and the model understands it (decision
+      // 2026-08-08: prior-table hard parsing removed; no phrase/header matching).
+      // Guard: only store outputs that actually carry a review — a markdown
+      // table row (`| a | b | c |`) or substantial prose (>200 chars). An
+      // empty or tool-progress-only reply must not become the "prior review"
+      // of round 2+.
+      const trimmed = final.trim()
+      const looksLikeReview = /\|.*\|.*\|/.test(trimmed) || trimmed.length >= 200
+      if (looksLikeReview) {
+        agent._lastAdvisorOutput = final
+      }
     }
 
     // Log review statistics for observability

package/src/advisor.mjs

@@ -44,10 +44,11 @@
 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, buildConvergenceInstructions, resolveScopeFiles } from "./advisor/messages.mjs"
+import { extractAgentResponseTable } from "./advisor/history.mjs"
+import { buildAdvisorUserMessage, resolveScopeFiles } from "./advisor/messages.mjs"
+import { buildConvergenceBody } from "./advisor/convergence.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 { ADVISOR_MD_PATH, extractAgentResponseTable, extractConversationBackground } from "./advisor/history.mjs"
 export { buildAdvisorUserMessage } from "./advisor/messages.mjs"
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
@@ -72,8 +73,7 @@ const ADVISOR_ROUND1 = loadPrompt("advisor-round1.md", "advisor-round1.md")
 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).
+// file (table format + workflow steps).
 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 = ""
 // Design review is OPTIONAL (engineering mode only) — silent fallback to the
@@ -88,24 +88,28 @@ 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 review output (full text; decision 2026-08-08)
  * @param {string} [reviewType] — "design" for design review, undefined/"code" for code review
  * @returns {string} the system prompt
  */
 export function buildAdvisorSystemPrompt(agent, prior, reviewType) {
+  // Round decision is DETERMINISTIC (decision 2026-08-08): _advisorRound > 0
+  // with a stored review output means convergence (round 2+); 0 means round 1.
+  // No prior-table parsing, no all-clear phrase matching — the round counter
+  // and the stored output are the only inputs. A restarted process has
+  // _advisorRound 0 → conservative full re-review.
+  const hasPrior = (agent._advisorRound || 0) > 0 && (prior ?? agent._lastAdvisorOutput)
   // Design review: round 1 uses the dedicated design-review prompt (full scope +
   // approval token); rounds 2+ converge like code reviews (verify agent fix claims).
   if (reviewType === "design") {
-    const p = prior ?? extractPriorIssueTable(agent.history)
-    if (!p || (agent._advisorRound || 0) === 0) {
+    if (!hasPrior) {
       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
+  if (!hasPrior) return ADVISOR_ROUND1
   const round = (agent._advisorRound || 0) + 1
   if (round === 2) return ADVISOR_ROUND2
   return ADVISOR_ROUND3
@@ -134,12 +138,11 @@ export function buildAdvisorSystemPrompt(agent, prior, reviewType) {
  *   otherwise scan history from index 0 and could match an unrelated stale table)
  */
 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)
+  // Convergence follow-up REQUIRES a prior review record — the full output of
+  // the last review, injected VERBATIM (decision 2026-08-08: the model
+  // understands the review output; no table/header/phrase parsing). The caller
+  // usually passes it; fall back to the stored agent._lastAdvisorOutput.
+  const p = prior ?? agent._lastAdvisorOutput
   if (!p) {
     // Plain "System reminder:" prefix (no brackets) — same convention as the
     // round-1 path (some OpenAI-compatible servers parse '['-prefixed content
@@ -155,38 +158,9 @@ export function buildAdvisorFollowUp(agent, prior, scopeFiles = null) {
   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 response = extractAgentResponseTable(agent.history) || 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: ${reminder}.]`,
-    "",
-    // 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 (fix claims — reference only)",
-    response,
-    "",
-    "## Instructions",
-    ...buildConvergenceInstructions(round, scopeFiles),
-    "",
-  ]
-  return parts.join("\n")
+  return buildConvergenceBody(p, response, round, scopeFiles)
 }
 
 /**
@@ -229,11 +203,15 @@ export function escapeLiteralEscapes(text) {
  * @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)
+export function prepareAdvisorMessages(agent, reviewType, designToken = null, documents = null, paths = null, priorParam = null) {
+  // Deterministic convergence state (decision 2026-08-08): round 2+ requires
+  // _advisorRound > 0 AND a stored prior review output. No history parsing.
+  // priorParam (direct callers) wins over the stored output — same derivation
+  // as buildAdvisorSystemPrompt (single source of truth for round semantics).
+  const prior = (agent._advisorRound || 0) > 0 ? (priorParam ?? agent._lastAdvisorOutput) : null
 
   // Design review round 1: the dedicated full-scope review with the approval
-  // token (an independent gate — it runs even when a prior table exists, e.g.
+  // token (an independent gate — it runs even when a prior review exists, e.g.
   // after a failed design review). Fresh session.
   if (reviewType === "design" && (agent._advisorRound || 0) === 0) {
     return [
@@ -248,21 +226,14 @@ export function prepareAdvisorMessages(agent, reviewType, designToken = null, do
   // 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
+  // No prior review output: reset ONLY when this run made no code changes (user
   // decision 2026-08-05: any loop that modified code must NOT reset — the
   // advisor guard WILL push back, so the convergence round must keep advancing
   // 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.
+  // proved it). Either way the message is a fresh full review (no prior output
+  // exists without a completed review) — only the round counter differs.
   if (!prior || (agent._advisorRound || 0) === 0) {
     if (!(agent._mutatedThisRun ?? false)) {
       // New review cycle (first review, all-clear, or no code changes): reset

package/src/agent/completion.mjs

@@ -4,17 +4,10 @@
  * Checks: pending tasks, verify guard, advisor guard.
  * Returns { action: 'continue' | 'done', content?, guardPushbacks, honestReminderInjected, advisorPushbacks }
  */
-import { isDocFile } from "../advisor/repos.mjs"
+import { hasCodeMutations } 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) {
-  const files = agent._touchedFiles ?? []
-  if (files.length === 0) return agent._mutatedThisRun
-  return files.some((p) => /(?:^|[\\/])src[\\/]/.test(p) || !isDocFile(p))
-}
-
 const MAX_VERIFY_PUSHBACKS = 2
 const MAX_VERIFY_RETRIES = 3
 const MAX_ADVISOR_PUSHBACKS = 3

package/src/agent.mjs

@@ -13,7 +13,6 @@ import { executeToolCalls } from "./agent/dispatch.mjs"
 import { prepareRun } from "./agent/setup.mjs"
 import { injectPostTurn, STALL_WINDOW_SIZE, STALL_THRESHOLD, GOAL_BUDGET_WARN_RATIO } from "./agent/post-turn.mjs"
 import { handleCompletion } from "./agent/completion.mjs"
-import { isDocFile } from "./advisor/repos.mjs"
 import {
   escapeXml, tryCanonicalize, repairHistory, listWorkDir,
   readonlyToolNames, collectGitContext, loadProjectInstructions,
@@ -56,23 +55,8 @@ export const ENG_ON_REMINDER =
   "subagents only. Advisor calls are NOT per-turn-mandatory — call only at " +
   "flow nodes or when the user asks.]"
 
-/**
- * True when this run mutated at least one CODE file. Doc-only changes
- * (docs/, *.md, LICENSE…) must NOT trigger the advisor/verify guards — the
- * design phase edits docs/ and must not be pushed to a code review.
- * Mutations without a known path (tools outside FILE_MUTATORS) are treated as
- * code — cannot tell, so guard conservatively.
- * Product-code semantics match isProductCode: anything under src/ (incl.
- * src/prompts/*.md) is code; anything else that isn't a doc file is code.
- * NOTE: _touchedFiles stores ABSOLUTE paths (join(cwd, p)), so the src/ check
- * matches a path component (works for "src/..." and "D:\...\src\..." alike),
- * not a bare ^src prefix — the literal ^src[\\/] form would be dead code here.
- */
-export function hasCodeMutations(agent) {
-  const files = agent._touchedFiles ?? []
-  if (files.length === 0) return agent._mutatedThisRun
-  return files.some((p) => /(?:^|[\\/])src[\\/]/.test(p) || !isDocFile(p))
-}
+// Re-exported for API compatibility (single source of truth: advisor/repos.mjs)
+export { hasCodeMutations } from "./advisor/repos.mjs"
 
 /** Engineering-mode status injection — one reminder when engineering mode is ON. */
 function injectEngineeringReminder(agent) {
@@ -101,6 +85,7 @@ export function createAgent({
     _engDesignReviewed: false, // eng-coder: design review gate passed (hard gate in dispatch.mjs)
     _engDesignToken: null, // issued by advisor(type="design"); required to spawn eng-coder
     _touchedFiles: [], _verifyRetries: 0, _advisorRound: 0, _advisorSession: null,
+    _lastAdvisorOutput: null, // full review output from the most recent advisor call (convergence rounds inject it verbatim)
     _lastEngState: false,
     _pendingReminders: [],
     _pendingTimers: [],
@@ -165,7 +150,7 @@ export async function runAgent(agent, input, callbacks = {}, { depth = 0, signal
     const lastRole = agent.history.at(-1)?.role
     if (lastRole === "user" || lastRole === "tool") {
       try {
-        if (await compressIfNeeded(agent, threshold, callbacks, compactionOverhead)) {
+        if (await compressIfNeeded(agent, threshold, callbacks, compactionOverhead, signal)) {
           agent._compressFailures = 0
           agent._planReminderAtLen = 0 // After compression history shrinks, reset cadence so reminders resume
           recentCallSigs.length = 0 // After compression history is rebuilt, reset stall detection counter
@@ -220,8 +205,8 @@ export async function runAgent(agent, input, callbacks = {}, { depth = 0, signal
       await classifyAndApply(agent, turn).catch(() => {})
     }
 
-    try {
-      response = await chat(agent.provider, {
+    if (process.env.ADVISOR_DEBUG) console.error("[chat-call]", JSON.stringify({ turn, histLen: agent.history.length, lastRole: agent.history.at(-1)?.role }))
+    try {      response = await chat(agent.provider, {
         messages, tools: toolSchemas,
         onToken: callbacks.onToken,
         onReasoning: callbacks.onReasoning,
@@ -389,13 +374,21 @@ export async function runAgent(agent, input, callbacks = {}, { depth = 0, signal
       pushReal(agent, { role: "tool", tool_call_id: toolCall.id, content: result })
       if (tool && ok) {
         if (FILE_MUTATORS.has(toolCall.name)) {
-          // Direct file edit — code was changed.
+          // Direct file edit — code was changed. The prior advisor review and
+          // verify are stale: a review that ran before the edit no longer
+          // covers the current file state.
           agent._mutatedThisRun = true
-        }
-        if (!tool.readonly && !tool.sideEffectExempt) {
-          // Any side-effect tool (bash, git, etc.) invalidates prior review/verify.
-          // Code may not have changed, but the environment did.
-          if (agent._calledAdvisorThisRun) agent._calledAdvisorThisRun = false
+          agent._calledAdvisorThisRun = false
+          agent._verifiedThisRun = false
+          agent._verifyPassed = undefined
+        } else if (!tool.readonly && !tool.sideEffectExempt) {
+          // Non-mutating side-effect tools (bash, git): do NOT invalidate the
+          // advisor review — a review is triggered by CODE MUTATIONS only
+          // (user decision 2026-08-08: the guard rule is "review after code
+          // changes", not "review after any environment change"; bash is
+          // barred from writing files, so it cannot change the reviewed code).
+          // Verify IS invalidated: its state snapshot (git diff, file list)
+          // may be stale after git/shell operations.
           if (agent._verifiedThisRun) {
             agent._verifiedThisRun = false
             agent._verifyPassed = undefined

package/src/config.mjs

@@ -139,9 +139,12 @@ const COMPACT_RATIO = 0.6
 
 /** Look up spec by model name prefix (case-insensitive), conservative default for unknown models */
 const warnedModels = new Set() // warn once per model name — specForModel is a hot path (every request)
+// Pre-sorted once at module scope — specForModel runs on every request (agent, provider core,
+// context, auto-think, TUI rendering); re-sorting per call was wasteful.
+const SORTED_SPECS = [...MODEL_SPECS].sort((a, b) => b[0].length - a[0].length)
 export function specForModel(model) {
   const m = (model ?? "").toLowerCase()
-  for (const [prefix, spec] of [...MODEL_SPECS].sort((a,b) => b[0].length - a[0].length)) {
+  for (const [prefix, spec] of SORTED_SPECS) {
     if (m.startsWith(prefix.toLowerCase())) return spec
   }
   // Unknown model: warn ONCE (not per request) so a typo'd ID or a missing alias surfaces
@@ -189,6 +192,8 @@ export function normalizeProxy(proxy) {
  * Load configuration.
  * Env var priority: THINCODER_ACTIVE_PROVIDER > config file activeProvider
  * THINCODER_API_KEY / THINCODER_BASE_URL / THINCODER_MODEL override the current active provider's corresponding fields
+ * THINCODER_ACTIVE_MODEL overrides the active model (wins over THINCODER_MODEL — see loadConfig)
+ * Provider-specific key fallbacks (when providers[] lacks a key): DEEPSEEK_API_KEY / OPENAI_API_KEY
  */
 export function loadConfig() {
   let config = {}
@@ -203,7 +208,7 @@ export function loadConfig() {
   const merged = {
     ...DEFAULTS,
     ...config,
-    providers: config.providers?.length ? config.providers : DEFAULTS.providers,
+    providers: Array.isArray(config.providers) && config.providers.length ? config.providers.map((p) => ({ ...p })) : DEFAULTS.providers.map((p) => ({ ...p })),
     activeProvider: config.activeProvider ?? DEFAULTS.activeProvider,
     agent: { ...DEFAULTS.agent, ...config.agent },
     memory: { ...DEFAULTS.memory, ...config.memory },
@@ -247,6 +252,8 @@ export function loadConfig() {
 
   // apiKey also falls back to env vars (when providers doesn't include a key)
   // Provider-specific env vars only apply to the matching provider name, preventing keys from leaking to wrong endpoints
+  // NOTE: only deepseek/openai have provider-specific fallbacks by design — the other presets
+  // intentionally rely on THINCODER_API_KEY or keys stored in config.json (no silent env pickup).
   if (!runtimeProvider.apiKey?.trim()) {
     const envMap = { deepseek: "DEEPSEEK_API_KEY", openai: "OPENAI_API_KEY" }
     const keyVar = envMap[merged.activeProvider]
@@ -278,9 +285,10 @@ export function loadConfig() {
  */
 export function saveConfig(config) {
   mkdirSync(configDir, { recursive: true })
-  // Inject $schema for editor autocompletion/validation (strip on load)
-  config.$schema = "https://thincoder.dev/schemas/config.json"
+  // Inject $schema for editor autocompletion/validation (strip on load) — write a copy,
+  // never mutate the caller's object.
+  const out = { ...config, $schema: "https://thincoder.dev/schemas/config.json" }
   // 0600: config.json contains API keys, must not be world-readable (POSIX; chmod is best-effort on Windows)
-  writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", { encoding: "utf8", mode: 0o600 })
+  writeFileSync(configPath, JSON.stringify(out, null, 2) + "\n", { encoding: "utf8", mode: 0o600 })
   try { chmodSync(configPath, 0o600) } catch { /* may fail on Windows, ignore */ }
 }

package/src/context.mjs

@@ -2,7 +2,11 @@
  * context.mjs — Context management and compaction
  * When no measured token count is available, use estimation as fallback (ASCII/4 + non-ASCII/1, no tokenizer dependency).
  * When a measured value exists (response usage.prompt_tokens), trust it — estimation underestimates CJK by 3-4x and relying solely on it may never trigger compaction.
- * Compaction strategy: keep earliest 2 + latest N messages, summarize the middle into one via LLM (inspired by kimi-code, simplified).
+ * Compaction strategy: summarize everything before the tail into one LLM note, keep the latest N messages verbatim.
+ * NOTE: no dedicated head is kept (KEEP_HEAD = 0) — in multi-task sessions the earliest messages are
+ * typically a COMPLETED earlier task; preserving them verbatim anchored the model's attention on stale
+ * work after compaction. The earliest messages now go into the summary (which distinguishes completed
+ * vs in-progress work), so the post-compaction context anchors on the current task (recent tail) only.
  */
 
 import { chat } from "./provider/index.mjs"
@@ -30,11 +34,16 @@ export function estimateTokens(messages) {
   return tokens
 }
 
-const KEEP_HEAD = 2 // Keep the earliest user intent — must not lose it
+const KEEP_HEAD = 0 // No dedicated head: earliest messages may be a COMPLETED earlier task in multi-task
+// sessions — keeping them verbatim anchored attention on stale work. Everything before the tail is
+// summarized (the summary itself distinguishes completed vs in-progress work; see SUMMARIZE_PROMPT).
 // Tail size scales with the model context window (~30 messages per 100K tokens),
 // capped at 40% of history so small histories don't over-reserve. Window-adaptive
 // replaces the old fixed 10: on a 1M window, 10 messages is too thin for recent work.
 function keepTailSize(provider, historyLen) {
+  // provider is guaranteed at every call site (runAgent always builds one); specForModel
+  // degrades to DEFAULT_SPEC (128K) only if provider/model is somehow absent — acceptable
+  // because the 40% history cap still bounds the tail.
   const ctxWindow = specForModel(provider?.model ?? "").context
   return Math.min(Math.max(10, Math.floor((ctxWindow / 100_000) * 30)), Math.floor(historyLen * 0.4))
 }
@@ -43,7 +52,9 @@ const SUMMARIZE_PROMPT = `You are a conversation compressor. Summarize the follo
 Requirements:
 - Write in first person, present tense — these are "my" handover notes, continuing my own train of thought
 - Most important: preserve design decisions and their reasons — architecture choices, API contracts, naming conventions, trade-off rationale. These are the anchors the subsequent code must not deviate from
-- Keep: the user's original request, files modified and why, unresolved issues, next steps
+- Distinguish COMPLETED vs IN-PROGRESS work: completed tasks get a ONE-LINE recap each (what was done, key outcome); spend the detail budget on unresolved issues, next steps, and the CURRENT task
+- The user's most recent request defines the current task — anchor on it. Earlier requests are likely already completed and only need the one-line recap; do NOT preserve them at full fidelity
+- Keep: files modified and why, unresolved issues, next steps
 - Drop: pleasantries, repetition, fine-grained tool output details
 - Honestly mark uncertain items: anything not actually verified must say "unverified"; do not present guesses as facts
 - Use bullet-point output; aim for information completeness, not a hard word limit (old 500-char cap is deprecated; in a 1M-context era, err on the long side)
@@ -71,8 +82,8 @@ const FALLBACK_NOTE =
 
 /**
  * Split history into head / middle (to be summarized) / tail; return null if no middle to compress.
- * The head boundary must avoid orphan tool_calls: when an assistant message has tool_calls, all its tool responses must stay in head,
- * otherwise compressing them to plain text violates the protocol (tool_calls must be followed by tool messages).
+ * head is normally empty (KEEP_HEAD = 0 — earliest messages go into the summary); the
+ * tool_calls-extension logic below is defensive for future KEEP_HEAD > 0.
  * The tail boundary must include any assistant whose tool results are in the tail — if the assistant is in the middle,
  * the summary swallows it, leaving orphan tool results → protocol 400.
  */
@@ -101,7 +112,10 @@ function splitHistory(history, keepTail) {
   }
 
   // skip orphan tool messages at the new tail boundary (tool whose assistant was pulled in above)
-  while (tailStart > headEnd && history[tailStart].role === "tool") {
+  // NOTE: single-assistant assumption — the backwards scan pulls the nearest owner only; in
+  // practice a tail spans at most one assistant→tools cycle (parallel calls share one assistant).
+  // Bounds-guarded so an all-tool tail cannot push tailStart past history.length.
+  while (tailStart < history.length && tailStart > headEnd && history[tailStart].role === "tool") {
     tailStart++
   }
   if (tailStart <= headEnd) return null
@@ -127,6 +141,9 @@ export function pushReal(agent, msg) {
 function applyCompression(agent, headEnd, tailStart, note) {
   // _fullHistory already holds every real message (written at the source via pushReal),
   // so compaction only shrinks the machine line — nothing to preserve here.
+  // head is normally empty (KEEP_HEAD = 0) — the summary note becomes the first message,
+  // which is exactly the intent: post-compaction context anchors on the current task, not on
+  // possibly-completed earlier requests.
   const head = agent.history.slice(0, headEnd)
   const tail = agent.history.slice(tailStart)
   agent.history = [
@@ -173,7 +190,7 @@ function applyCompression(agent, headEnd, tailStart, note) {
  * @param {object} extras - { systemPrompt?, tools? } — estimated overhead for the pure-estimation
  *   path (no measured baseline); the measured path already includes system+tools in prompt_tokens.
  */
-export async function compressIfNeeded(agent, threshold, callbacks, extras = {}) {
+export async function compressIfNeeded(agent, threshold, callbacks, extras = {}, signal) {
   const history = agent.history
   // Prefer the real baseline: the last response's prompt_tokens is the measured value for the full context (system+tools+history).
   // Subsequent appended messages use estimation as increment; when no measured value exists (first turn / after restore / right after compaction), fall back to pure estimation
@@ -200,15 +217,21 @@ export async function compressIfNeeded(agent, threshold, callbacks, extras = {})
       const toolNote = m.tool_calls ? ` [called tools: ${m.tool_calls.map((t) => t.function.name).join(", ")}]` : ""
       // user messages get a wider cap (8000): cutting off a long user-pasted requirement loses original intent; tool/assistant capped at 2000 is enough
       const cap = m.role === "user" ? 8000 : 2000
-      const content = typeof m.content === "string" ? m.content.slice(0, cap) : ""
-      return `[${m.role}]${toolNote} ${content}`
+      // Multimodal messages (array content): extract the TEXT parts — the image itself can't be
+      // summarized, but any accompanying text (e.g. "看这张图" + image) must not be silently lost
+      let text = ""
+      if (typeof m.content === "string") text = m.content
+      else if (Array.isArray(m.content)) text = m.content.filter((p) => p?.type === "text").map((p) => p.text ?? "").join(" ")
+      return `[${m.role}]${toolNote} ${text.slice(0, cap)}`
     })
     .join("\n")
 
   // The summary is a plain-text task, no reasoning needed — passing thinking to the compaction provider wastes tokens.
   // Silent by design (D11): no onToken/onReasoning — the compaction process must not stream to the frontend.
+  // signal propagates user cancellation (Ctrl+C) to the in-flight summary call.
   const summary = await chat({ ...agent.provider, thinking: null, reasoningEffort: null }, {
     messages: [{ role: "user", content: SUMMARIZE_PROMPT + serialized }],
+    signal,
   })
 
   applyCompression(agent, split.headEnd, split.tailStart, COMPACTION_PREFIX + summary.content)

package/src/prompts/advisor-round1.md

@@ -5,7 +5,7 @@ You have a budget of 30 tool rounds (chat turns) — plan your exploration accor
 
 Review workflow:
 1. The files to review are listed in the review scope. Read them in full. The review scope defines exactly which files to inspect.
-2. Read AGENTS.md / design docs once if present, to understand project conventions, version requirements, and architecture decisions.
+2. **READ THE PROJECT GUIDE FIRST** — the `## Project Guide (AGENTS.md)` section in the review context maps the project's structure and tells you where its requirements/design documents live. Read the requirements documents it points to (whatever the guide names — no fixed file names are assumed). **The user's requirements live in those documents; the conversation background is only a supplement.** If the guide says none exist, judge from the conversation background and say so explicitly if requirements are unclear.
 3. Read the specified files for full context. **Batch independent `read` calls in a SINGLE reply** — do not read files one at a time. Each round-trip counts against your limit.
 4. Use grep or lsp to trace callers, imports, and dependencies — only where genuinely needed.
 5. Produce your review table.
@@ -20,8 +20,8 @@ Rules:
 - 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.
+  - (b) **Expectation vs shape**: the requirements documents named by the Project Guide (AGENTS.md) and explicit user expectations 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. **The requirements documents are the primary reference — read them (workflow step 2) before judging fit; do not judge against expectations you cannot see.**
+  - **Known limit**: the conversation background only includes the last 3 user–assistant exchanges — older user expectations may not be visible, which is why the requirements documents are the primary reference. (a) is the primary check (needs only recent context); (b) is best-effort — check what the docs/background show, 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.

package/src/prompts/advisor-round2.md

@@ -1,22 +1,22 @@
 You are an independent review advisor.
-Verify the prior issue table (provided in the review context).
+Verify the prior review output (provided in the review context).
 You may note obvious new issues introduced by the fixes.
 You have read-only tools to explore the codebase.
 You have a budget of 30 tool rounds (chat turns). Hard mechanical cap: 100 rounds.
 
 Review workflow:
-1. The affected files are named in the prior issue table — read them in full. The prior issue table is HISTORY from a previous review, not current state.
+1. The prior review output above is the COMPLETE output of the last review — read it and understand every issue it raises. The affected files are named in it — read them in full. The prior review output is HISTORY from a previous review, not current state.
 2. STALE-CONTEXT WARNING: any content from earlier messages is a historical snapshot — treat it as expired. Only fresh `read` results describe the current state.
-3. Project conventions were established in round 1 — do NOT re-read AGENTS.md / design docs unless a prior-table item names them or a fix appears to contradict the task itself.
-4. **ALWAYS verify current file content with `read` before judging a prior-table item as fixed or unfixed — never decide based on the prior table alone.** Fixes may already be committed — `read` the files named in the prior table regardless. (Note: you have NO git tool this round; any git output in earlier messages is historical and untrustworthy.) Batch independent tool calls in one reply.
+3. Project conventions were established in round 1 — do NOT re-read AGENTS.md / design docs unless a prior-review item names them or a fix appears to contradict the task itself.
+4. **ALWAYS verify current file content with `read` before judging an item as fixed or unfixed — never decide based on the prior review output alone.** Fixes may already be committed — `read` the files named there regardless. (Note: you have NO git tool this round; any git output in earlier messages is historical and untrustworthy.) Batch independent tool calls in one reply.
 5. Use grep or lsp to trace callers, imports, and dependencies — only where genuinely needed.
 6. Produce your review table.
 
-Budget: read only the files named in the prior-table items. If at 15 rounds you have not yet verified all items, wrap up.
+Budget: read only the files named in the prior-review items. If at 15 rounds you have not yet verified all items, wrap up.
 
 Rules:
 - Respect the project's stated platform requirements — do not flag features as errors if they are valid under the project's target environment.
-- Primarily check fix status of items in the prior issue table.
+- Primarily check fix status of items in the prior review output.
 - For items marked "fixed": verify they were actually fixed.
 - For items marked "not an issue": evaluate whether the reasoning is sound.
 - Every "Unfixed" or "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 be fabricated or stale. Findings without a fresh quoted line are treated as unverified and will not be accepted.

package/src/prompts/advisor-round3.md

@@ -1,31 +1,29 @@
 You are an independent review advisor.
-Strictly verify only the prior issue table (provided in the review context).
-Do NOT look for new issues.
+Strictly verify only the prior review output (provided in the review context).
 You have read-only tools to explore the codebase.
 You have a budget of 30 tool rounds (chat turns). Hard mechanical cap: 100 rounds.
 
 Review workflow:
-1. The affected files are named in the prior issue table — read them in full. The prior issue table is HISTORY from a previous review, not current state.
+1. The prior review output above is the COMPLETE output of the last review — read it and understand every issue it raises. The affected files are named in it — read them in full. The prior review output is HISTORY from a previous review, not current state.
 2. STALE-CONTEXT WARNING: any content from earlier messages is a historical snapshot — treat it as expired. Only fresh `read` results describe the current state.
-3. Project conventions were established in round 1 — do NOT re-read AGENTS.md / design docs unless a prior-table item names them or a fix appears to contradict the task itself.
-4. **ALWAYS verify current file content with `read` before judging a prior-table item as fixed or unfixed — never decide based on the prior table alone.** Fixes may already be committed — `read` the files named in the prior table regardless. (Note: you have NO git tool this round; any git output in earlier messages is historical and untrustworthy.) Batch independent tool calls in one reply.
-5. Verify fix status of each item in the prior issue table.
+3. Project conventions were established in round 1 — do NOT re-read AGENTS.md / design docs unless a prior-review item names them.
+4. **ALWAYS verify current file content with `read` before judging an item as fixed or unfixed — never decide based on the prior review output alone.** Fixes may already be committed — `read` the files named there regardless. (Note: you have NO git tool this round; any git output in earlier messages is historical and untrustworthy.) Batch independent tool calls in one reply.
+5. Use grep or lsp to trace callers, imports, and dependencies — only where genuinely needed.
 6. Produce your review table.
 
-Budget: read only the files named in the prior-table items. If at 15 rounds you have not yet verified all items, wrap up.
+Budget: read only the files named in the prior-review items. If at 15 rounds you have not yet verified all items, wrap up.
 
 Rules:
 - Respect the project's stated platform requirements — do not flag features as errors if they are valid under the project's target environment.
-- Only check fix status of items in the prior issue table.
-- For items marked "fixed": verify they were actually fixed.
-- For items marked "not an issue": evaluate whether the reasoning is sound.
-- Every "Unfixed" 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 be fabricated or stale. Findings without a fresh quoted line are treated as unverified and will not be accepted.
+- Only check fix status of items in the prior review output.
+- Every "Unfixed" or "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 be fabricated or stale. Findings without a fresh quoted line are treated as unverified and will not be accepted.
 - **Host verification**: your `file:line: content` citations are mechanically checked against the CURRENT file state — quote exactly what `read` returned; a mismatch marks the finding unverified.
 - **Fresh context**: this round's conversation contains NO read output from earlier rounds — every file must be re-read this round.
-- Output a Markdown table. Only list items that still have problems:
+- Do NOT look for new issues. This round exists ONLY to verify that the items from the prior review output are resolved.
+- Do NOT nitpick style or naming.
+- Output a Markdown table listing all remaining problems:
 | # | Orig# | File | Severity | Status | Notes |
 |---|-------|------|----------|--------|-------|
 | 1 | 3     | src/x.mjs | 🔴 | Unfixed | ... |
-| 2 | 5     | src/y.mjs | 🟡 | Reasoning invalid | ... |
 - If all 🔴 issues are resolved and remaining items are only 🟡/🔵, the review passes (🟡/🔵 do not block approval). If any 🔴 issue persists, do not claim it passed.
 - Stop calling tools once you are ready to produce the review table.