thincoder 0.12.58 → 0.12.60

package/src/advisor/messages.mjs

@@ -105,6 +105,49 @@ function injectProjectGuide(agent, parts, scopeFiles = []) {
   return root // guide injected — requirement-fit criteria apply (truthy root)
 }
 
+/**
+ * Build the mechanical review-object declaration block (AGENT-LOOP.md §18.8
+ * D-OA2 — English anchored form). Injected at the START of the review user
+ * message every round: round 1 (design + code), the legacy convergence path,
+ * and the round-2+ follow-up (see buildAdvisorFollowUp) — the reviewer must
+ * not re-derive "who is being reviewed / why" from the documents (T-OA2:
+ * every round stays anchored). Absent object → "" (legacy calls degrade to
+ * the current behavior — T-OA3).
+ * @param {Object|null} [object] — { type, target, status, reason, exclude }
+ *   (strings; `exclude` may also be a list — joined with ", ")
+ * @returns {string} the declaration block (empty when no object)
+ */
+export function buildObjectDeclarationBlock(object = null) {
+  if (!object || typeof object !== "object" || Array.isArray(object)) return ""
+  const field = (v) => (Array.isArray(v) ? v.join(", ") : v == null ? "" : String(v))
+  return [
+    "## Review-object declaration (mechanical — do not infer)",
+    `Review type: ${field(object.type)} | Target: ${field(object.target)} | Object state: ${field(object.status)} | Trigger: ${field(object.reason)}`,
+    `Excluded (not in this review): ${field(object.exclude)}`,
+    "Follow this declaration — do not infer the review target from the documents.",
+    "",
+  ].join("\n")
+}
+
+/**
+ * Approval-signal block for design reviews (round 1 and round 2+ — §24 D-24b:
+ * an async fix-round continuation must be able to re-approve, so the token is
+ * injected into EVERY design round; the reviewer echoes it only on a clean pass).
+ * §29.1 F2a (2026-09-07): BOTH values are injected — the token AND the designId
+ * (anchor sentence verbatim — Copy BOTH values). designId null (legacy direct
+ * callers without a resolved instance) degrades to the token-only form.
+ */
+export function buildDesignApprovalBlock(designToken, designId) {
+  const echo = designId
+    ? `If — and ONLY if — your review finds NO 🔴 (Critical) issues, end your reply with this exact token: [DESIGN-TOKEN:${designToken}] and this exact designId: ${designId}. Copy BOTH values verbatim.`
+    : `If — and ONLY if — your review finds NO 🔴 (Critical) issues, end your reply with this exact token: [DESIGN-TOKEN:${designToken}]`
+  return [
+    "## Approval Signal",
+    echo,
+    "🟡 (Advisory) and 🔵 (Note) findings do NOT block approval — list them if present, but still include the token. If there are any 🔴 issues, do NOT include the token.",
+  ].join("\n")
+}
+
 /**
  * Build the user message for an advisor review session.
  * @param {Object} agent — the parent agent
@@ -115,15 +158,27 @@ function injectProjectGuide(agent, parts, scopeFiles = []) {
  *   When set, the review input is built from this list ONLY — no git-diff change-set collection.
  *   When absent, the legacy git-diff-based scope is kept (backward compatible).
  * @param {string[]|null} [paths] — code review only: explicit list of file/dir paths to review (deduped; shown under Review Scope)
+ * @param {Object|null} [object] — review-object declaration (§18.8 D-OA1/D-OA3):
+ *   { type, target, status, reason, exclude } — mechanically injected at the
+ *   start of the user message; absent → no injection (legacy calls unchanged).
+ * @param {string|null} [designId] — §29.1 F2a: injected next to the token in the
+ *   Approval Signal (both values — the reviewer copies both verbatim); null →
+ *   token-only degradation (legacy direct callers).
  * @returns {string} the user message
  */
-export function buildAdvisorUserMessage(agent, prior, reviewType, designToken = null, documents = null, paths = null) {
+export function buildAdvisorUserMessage(agent, prior, reviewType, designToken = null, documents = null, paths = null, object = null, designId = null) {
   // 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 = []
+  // Review-object declaration FIRST — D-OA1: at the start of the user message
+  // (after the system prompt, before the review content). Covers round 1
+  // design/code and the legacy convergence path; the round-2+ normal path
+  // prepends it in buildAdvisorFollowUp (T-OA2 — every round stays anchored).
+  const declaration = buildObjectDeclarationBlock(object)
+  if (declaration) parts.push(declaration)
   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()))] : []
 
@@ -213,9 +268,7 @@ export function buildAdvisorUserMessage(agent, prior, reviewType, designToken =
     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")
-      parts.push(`If — and ONLY if — your review finds NO 🔴 (Critical) issues, end your reply with this exact token: [DESIGN-TOKEN:${designToken}]`)
-      parts.push("🟡 (Advisory) and 🔵 (Note) findings do NOT block approval — list them if present, but still include the token. If there are any 🔴 issues, do NOT include the token.")
+      parts.push(buildDesignApprovalBlock(designToken, designId))
     }
     return parts.join("\n")
   }

package/src/advisor/run.mjs

@@ -10,11 +10,10 @@ import { appendCitationReport } from "./citations.mjs"
 import { describeToolArgs } from "../tui/tool-args.mjs"
 
 const MAX_ADVISOR_TURNS = 100
-// Mechanical convergence cap: the protocol assumes up to 5 rounds suffice
-// (full review, verify+fix cycles, strict verification). A 6th call means the
-// model is looping — refuse it instead of burning tokens on a review that cannot
-// converge. Code AND design reviews share the 5-round budget (each advances
-// _advisorRound in agent.mjs; the cap no longer exempts design).
+// Mechanical convergence cap: up to 5 rounds suffice; a 6th call means the model
+// is looping — refuse it instead of burning tokens. §24 D-24b (2026-09-06): PER
+// REVIEW INSTANCE (agent._advisorRuns); CODE REVIEWS ONLY (2026-09-07 §8 ruling)
+// — design reviews are EXEMPT: their rounds keep advancing, the cap never refuses.
 export const MAX_ADVISOR_ROUNDS = 5
 
 // NOTE: prompts/advisor-round{1,2,3}.md encourage the model to finish within
@@ -120,6 +119,9 @@ function renderTimeline(timeline, tail = "") {
 }
 // Test seam (mirrors _advisorToolsFor).
 export { renderTimeline as _renderTimeline }
+// Test seam (T-TS8/9): the tool loop itself — toolsOverride injects a mock tool
+// set with controllable timing/errors (the real set comes from advisorToolsFor).
+export { runAdvisorToolLoop as _runAdvisorToolLoop }
 
 /**
  * Run the advisor's tool loop: chat → execute tools → repeat.
@@ -129,7 +131,7 @@ export { renderTimeline as _renderTimeline }
  * the panel keeps moving while the advisor explores — otherwise the panel sits
  * frozen through every tool-call phase and the review appears to have stalled.
  */
-async function runAdvisorToolLoop(provider, messages, onOutput, signal, agent, cwd) {
+async function runAdvisorToolLoop(provider, messages, onOutput, signal, agent, cwd, toolsOverride = null) {
   // Kind-tagged wrappers: the TUI panel colors reasoning / answer / tool progress differently.
   // Every chunk is ALSO recorded into an ordered timeline — the persisted record
   // must show the review process (thinking ↔ tool progress ↔ final text) at its
@@ -145,7 +147,9 @@ async function runAdvisorToolLoop(provider, messages, onOutput, signal, agent, c
   const onThink = emit("think")
   const onText = emit("text")
   const onTool = emit("tool")
-  const { schemas: toolSchemas, byName: toolByName } = advisorToolsFor(agent)
+  // toolsOverride = test seam (T-TS8/9): the real advisor tool set, or a mock
+  // set with controllable timing/errors.
+  const { schemas: toolSchemas, byName: toolByName } = toolsOverride ?? advisorToolsFor(agent)
   let turns = 0
   const startTime = Date.now()
   
@@ -198,13 +202,25 @@ async function runAdvisorToolLoop(provider, messages, onOutput, signal, agent, c
       signal: signal ?? null,
       onToken: onText,
       onReasoning: onThink,
+      // LOGGING（vscode advisor/run.mjs parity——按 stage 可 grep）
+      // §18.6 D-TR4：轨迹元数据增补——kind=advisor（评审独立于子代理——T-TR2）；role
+      // 透出调用方角色（eng-coder 内嵌评审时为 "eng-coder"）；session/cwd 供轨迹对回；
+      // traces 开关沿 agent.config（D-TR6）。
+      logCtx: {
+        stage: "advisor",
+        role: agent?._role ?? null,
+        kind: "advisor",
+        session: agent?._sessionStart ?? null,
+        cwd,
+        traces: agent?.config?.traces?.enabled !== false,
+      },
     })
 
     // No tool calls — this is the final review text. The final answer was
     // already streamed into the timeline via onText; fall back to
     // response.content only if nothing was recorded.
     if (!response.toolCalls?.length) {
-      if (!response.content?.trim()) return renderTimeline(timeline) || "Advisor: (empty response — review was inconclusive)"
+      if (!response.content?.trim()) return renderTimeline(timeline) || "Advisor: empty response — review was inconclusive"
       return renderTimeline(timeline) || response.content.trim()
     }
 
@@ -226,8 +242,19 @@ async function runAdvisorToolLoop(provider, messages, onOutput, signal, agent, c
         : {}),
     })
 
-    // Execute each tool call
-    for (const tc of response.toolCalls) {
+    // B1 (AGENT-LOOP.md §18.7 D-TS7): the SAME LLM reply's multiple read-only
+    // tool calls run in PARALLEL (Promise.all) — results are backfilled in
+    // toolCalls order (Promise.all preserves the input order → tool_call_id
+    // never mismatches); each tool's timeout/error is captured independently
+    // (the existing TOOL_TIMEOUT stays — one failing tool does not block the
+    // others); progress lines are emitted in toolCalls order. The read-only
+    // tool set has no side effects — no sequencing/serialization needed.
+    // Scope note (round1 review #10): B1 is ONLY in-loop tool parallelism — it
+    // does NOT solve the TODO "platform execution: advisor parallel calls are
+    // actually serial" mystery (docs/TODO.md — LOGGING evidence item), which
+    // concerns multiple advisor CALLS observed as serial, not one reply's
+    // tool calls.
+    const parsed = response.toolCalls.map((tc) => {
       const tool = toolByName.get(tc.name)
       let args = {}
       let parseError = null
@@ -236,63 +263,69 @@ async function runAdvisorToolLoop(provider, messages, onOutput, signal, agent, c
       } catch (e) {
         parseError = `Error: invalid JSON in tool arguments: ${e.message}\nRaw arguments: ${(tc.arguments || "").slice(0, 200)}`
       }
-      
-      // If parse failed, return error to model immediately
-      if (parseError) {
-        messages.push({ role: "tool", tool_call_id: tc.id, content: parseError })
-        continue
-      }
-      
-      const argsLine = describeToolArgs(tc.name, args)
-      onTool(`\n→ ${tc.name}${argsLine ? " " + argsLine : ""}\n`)
-      let result
-      if (!tool) {
-        result = `Error: unknown tool "${tc.name}". Available: ${[...toolByName.keys()].join(", ")}`
-      } else {
-        // Execute with timeout (clear the timer when the tool wins the race —
-        // otherwise up to MAX_ADVISOR_TURNS dangling timers accumulate)
+      return { tc, tool, args, parseError }
+    })
+    // Progress lines first, in toolCalls order (emitted before the parallel
+    // run — display order is independent of completion order).
+    for (const p of parsed) {
+      if (p.parseError) continue // parse-error tools get no progress line (legacy behavior)
+      const argsLine = describeToolArgs(p.tc.name, p.args)
+      onTool(`\n→ ${p.tc.name}${argsLine ? " " + argsLine : ""}\n`)
+    }
+    // Every tool runs CONCURRENTLY; each result/error lands in its own slot —
+    // Promise.all preserves input order, so index i always matches parsed[i].
+    const executed = await Promise.all(parsed.map(async (p) => {
+      // Parse failure → error to model immediately (no execution)
+      if (p.parseError) return p.parseError
+      if (!p.tool) return `Error: unknown tool "${p.tc.name}". Available: ${[...toolByName.keys()].join(", ")}`
+      // Execute with timeout (clear the timer when the tool wins the race —
+      // otherwise up to MAX_ADVISOR_TURNS dangling timers accumulate)
+      try {
+        let timeoutId
+        const timeoutPromise = new Promise((_, reject) => {
+          timeoutId = setTimeout(() => reject(new Error(`tool timeout after ${TOOL_TIMEOUT_MS}ms`)), TOOL_TIMEOUT_MS)
+        })
+        let toolPromise
         try {
-          let timeoutId
-          const timeoutPromise = new Promise((_, reject) => {
-            timeoutId = setTimeout(() => reject(new Error(`tool timeout after ${TOOL_TIMEOUT_MS}ms`)), TOOL_TIMEOUT_MS)
-          })
-          let toolPromise
-          try {
-            toolPromise = tool.execute(args, { cwd, agent, onOutput, signal })
-            result = await Promise.race([toolPromise, timeoutPromise])
-          } finally {
-            clearTimeout(timeoutId)
-            // Timeout won → toolPromise is still pending; a later rejection
-            // would surface as an unhandled rejection. The race already
-            // consumed the result/error in the normal path, so this no-op
-            // catch only fires for the abandoned-tool case.
-            toolPromise?.catch(() => {})
-          }
-        } catch (e) {
-          const errorType = e.message.includes("timeout") ? "timeout"
-            : e.message.includes("ENOENT") ? "file_not_found"
-            : e.message.includes("permission") ? "permission_denied"
-            : "execution_error"
-          result = `Error (${errorType}): ${e.message}`
+          toolPromise = p.tool.execute(p.args, { cwd, agent, onOutput, signal })
+          return await Promise.race([toolPromise, timeoutPromise])
+        } finally {
+          clearTimeout(timeoutId)
+          // Timeout won → toolPromise is still pending; a later rejection
+          // would surface as an unhandled rejection. The race already
+          // consumed the result/error in the normal path, so this no-op
+          // catch only fires for the abandoned-tool case.
+          toolPromise?.catch(() => {})
         }
+      } catch (e) {
+        const errorType = e.message.includes("timeout") ? "timeout"
+          : e.message.includes("ENOENT") ? "file_not_found"
+          : e.message.includes("permission") ? "permission_denied"
+          : "execution_error"
+        return `Error (${errorType}): ${e.message}`
       }
+    }))
+
+    // Backfill in toolCalls order (executed[i] ↔ parsed[i]); per-result
+    // non-string serialization + line-aware truncation stay per-tool.
+    for (let i = 0; i < parsed.length; i++) {
+      let result = executed[i]
       if (typeof result !== "string") result = JSON.stringify(result)
-      
-      // Line-aware truncation: preserve line integrity
+
       if (result.length > MAX_RESULT_CHARS) {
         const lines = result.split("\n")
         let truncated = ""
         let charCount = 0
         let keptLines = 0
-        
-        for (let i = 0; i < lines.length; i++) {
-          const line = lines[i]
+
+        for (let j = 0; j < lines.length; j++) {
+          const line = lines[j]
           if (charCount + line.length + 1 > MAX_RESULT_CHARS) break
           truncated += line + "\n"
           charCount += line.length + 1
           keptLines++
         }
-        
+
         const remainingLines = lines.length - keptLines
         result = (
           truncated +
@@ -300,8 +333,8 @@ async function runAdvisorToolLoop(provider, messages, onOutput, signal, agent, c
           `To see more content, use: read(path, offset=${keptLines + 1}, limit=200)`
         )
       }
-      
-      messages.push({ role: "tool", tool_call_id: tc.id, content: result })
+
+      messages.push({ role: "tool", tool_call_id: parsed[i].tc.id, content: result })
     }
   }
 }
@@ -354,13 +387,35 @@ function extractUnfixedIssues(priorText) {
     .filter(Boolean)
     .slice(0, MAX_UNFIXED_DISPLAY)
 }
+/** Review-looking guard (async settle parity): a markdown table row or ≥200 chars of prose counts as a prior. */
+export function looksLikeReviewOutput(text) {
+  const trimmed = String(text ?? "").trim()
+  return /\|.*\|.*\|/.test(trimmed) || trimmed.length >= 200
+}
+/** Cap message (shared by runAdvisorReview and the async pre-check — per-review refusal). */
+export function buildCapMessage(agent) {
+  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) {
+    message += `\nUnresolved issues from prior rounds:\n${unfixed.map((i) => `- ${i}`).join("\n")}\n`
+  } else {
+    message += "\nAll prior issues appear resolved.\n"
+  }
+  message += "\nOptions:\n1. Accept current state and proceed\n2. Manually review specific concerns with read/grep\n3. Start a new session (/new) to reset the advisor"
+  return message
+}
 
 /**
  * Run an advisor review. reviewType: "code" (default) or "design". Returns review text or null when skipped.
  * @param {string|null} [designToken] — injected into the design-review prompt; the advisor echoes it only on approval.
  * @param {string[]|null} [documents] — design review only: explicit list of doc paths to review; passed through to the message builder.
+ * @param {string[]|null} [paths] — code review only: explicit list of file/dir paths to review.
+ * @param {Object|null} [object] — review-object declaration (§18.8 D-OA1/D-OA3): { type, target, status, reason, exclude }; absent → legacy behavior (no injection).
+ * @param {string|null} [designId] — §29.1 F2a: injected next to the design token in
+ *   the Approval Signal (passed through to the message builders).
  */
-export async function runAdvisorReview(agent, reviewType, callbacks, designToken = null, documents = null, paths = null) {
+export async function runAdvisorReview(agent, reviewType, callbacks, designToken = null, documents = null, paths = null, object = null, designId = null) {
   const onOutput = callbacks?.onOutput
   const signal = callbacks?.signal
   const startTime = Date.now()
@@ -369,33 +424,19 @@ export async function runAdvisorReview(agent, reviewType, callbacks, designToken
   // former advisor.enabled gate is removed — review capability has no off
   // switch; only the guard (completion pushback) is opt-in via advisor.guard.
 
-  // Mechanical convergence cap — refuse further reviews once the protocol has run
-  // its rounds. _advisorRound counts completed advisor calls (incremented by the
-  // agent after each one — code AND design reviews alike), so >= MAX_ADVISOR_ROUNDS
-  // 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) {
-    // 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) {
-      message += `\nUnresolved issues from prior rounds:\n${unfixed.map((i) => `- ${i}`).join("\n")}\n`
-    } else {
-      message += "\nAll prior issues appear resolved.\n"
-    }
-    message += "\nOptions:\n1. Accept current state and proceed\n2. Manually review specific concerns with read/grep\n3. Start a new session (/new) to reset the advisor"
-    
-    return message
+  // Mechanical convergence cap — CODE REVIEWS ONLY (2026-09-07 §8 ruling: design
+  // reviews are exempt). _advisorRound is scoped to the current review instance
+  // (§24 D-24b ③), so >= MAX_ADVISOR_ROUNDS blocks the next call of THIS instance.
+  // 5 rounds max; after that the review is never pushed back.
+  if (reviewType !== "design" && (agent._advisorRound || 0) >= MAX_ADVISOR_ROUNDS) {
+    return buildCapMessage(agent)
   }
 
   const provider = resolveAdvisorProvider(agent)
   // Advisor always works in the agent's cwd — scope is defined by paths/documents.
   const advisorCwd = agent.cwd
 
-  const messages = prepareAdvisorMessages(agent, reviewType, designToken, documents, paths)
+  const messages = prepareAdvisorMessages(agent, reviewType, designToken, documents, paths, null, object, designId)
 
   try {
     const result = await runAdvisorToolLoop(provider, messages, onOutput, signal, agent, advisorCwd)
@@ -416,8 +457,7 @@ export async function runAdvisorReview(agent, reviewType, callbacks, designToken
       // 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
+      const looksLikeReview = looksLikeReviewOutput(final)
       if (looksLikeReview) {
         agent._lastAdvisorOutput = final
       }

package/src/advisor.mjs

@@ -45,12 +45,13 @@ import { readFileSync } from "node:fs"
 import { join, dirname } from "node:path"
 import { fileURLToPath } from "node:url"
 import { extractAgentResponseTable } from "./advisor/history.mjs"
-import { buildAdvisorUserMessage, resolveScopeFiles } from "./advisor/messages.mjs"
+import { buildAdvisorUserMessage, resolveScopeFiles, buildObjectDeclarationBlock, buildDesignApprovalBlock } from "./advisor/messages.mjs"
 import { buildConvergenceBody } from "./advisor/convergence.mjs"
 import { escapeLiteralEscapes } from "./escape.mjs"
 // Re-export for run.mjs and tests (keeps their imports from "../advisor.mjs" stable)
 export { ADVISOR_MD_PATH, extractAgentResponseTable, extractConversationBackground } from "./advisor/history.mjs"
 export { buildAdvisorUserMessage } from "./advisor/messages.mjs"
+export { buildObjectDeclarationBlock, buildDesignApprovalBlock } from "./advisor/messages.mjs"
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 
@@ -135,13 +136,15 @@ export function buildAdvisorSystemPrompt(agent, prior, reviewType) {
  * @param {Object} agent — the parent agent (history used for the response table)
  * @param {Object|null} prior — prior issue table (extracted from history when null)
  * @param {string[]|null} [scopeFiles] — review surface for the no-response fallback (cwd-relative)
+ * @param {Object|null} [object] — review-object declaration (§18.8): mechanically
+ *   prepended to the round-2+ follow-up so every round stays anchored (T-OA2).
  * @returns {string} the follow-up user message — or a plain "System reminder: …"
  *   fresh-review fallback (NO brackets — some OpenAI-compatible servers parse
  *   '['-prefixed content as structured data / expand escapes) when no prior
  *   review exists at all (caller misuse; the response-table extraction would
  *   otherwise scan history from index 0 and could match an unrelated stale table)
  */
-export function buildAdvisorFollowUp(agent, prior, scopeFiles = null) {
+export function buildAdvisorFollowUp(agent, prior, scopeFiles = null, object = null) {
   // Convergence follow-up REQUIRES a prior review record — the full output of
   // the last review, injected VERBATIM (decision 2026-08-08: the model
   // understands the review output; no table/header/phrase parsing). The caller
@@ -164,7 +167,9 @@ export function buildAdvisorFollowUp(agent, prior, scopeFiles = null) {
     : "(Agent did not provide a response table — perform a fresh full review; the review surface is unknown, ask the user for the file list)"
   const response = extractAgentResponseTable(agent.history) || noResponseFallback
   const round = (agent._advisorRound || 0) + 1
-  return buildConvergenceBody(p, response, round, scopeFiles)
+  // Review-object declaration FIRST (T-OA2 — round 2+ stays anchored, no re-archaeology).
+  const declaration = buildObjectDeclarationBlock(object)
+  return (declaration ? declaration + "\n" : "") + buildConvergenceBody(p, response, round, scopeFiles)
 }
 
 /**
@@ -187,8 +192,13 @@ export { escapeLiteralEscapes }
  * @param {string|null} [designToken] — design-review approval token (design only)
  * @param {string[]|null} [documents] — design review only: explicit list of doc paths to review (passed through to buildAdvisorUserMessage)
  * @param {string[]|null} [paths] — code review only: explicit list of file/dir paths to review
+ * @param {Object|null} [object] — review-object declaration (§18.8 D-OA1): passed through
+ *   to the user-message builders; mechanically injected at the start of every review
+ *   round (round 1 design/code + round 2+ follow-up). Absent → legacy behavior.
+ * @param {string|null} [designId] — §29.1 F2a: injected next to the design token in
+ *   the Approval Signal (round 1 + round 2+ — both values, verbatim anchor).
  */
-export function prepareAdvisorMessages(agent, reviewType, designToken = null, documents = null, paths = null, priorParam = null) {
+export function prepareAdvisorMessages(agent, reviewType, designToken = null, documents = null, paths = null, priorParam = null, object = null, designId = null) {
   // Deterministic convergence state (decision 2026-08-08): round 2+ requires
   // _advisorRound > 0 AND a stored prior review output. No history parsing.
   // priorParam (direct callers) wins over the stored output — same derivation
@@ -201,7 +211,7 @@ export function prepareAdvisorMessages(agent, reviewType, designToken = null, do
   if (reviewType === "design" && (agent._advisorRound || 0) === 0) {
     return [
       { role: "system", content: withTime(buildAdvisorSystemPrompt(agent, prior, reviewType)) },
-      { role: "user", content: escapeLiteralEscapes(buildAdvisorUserMessage(agent, prior, reviewType, designToken, documents, paths)) },
+      { role: "user", content: escapeLiteralEscapes(buildAdvisorUserMessage(agent, prior, reviewType, designToken, documents, paths, object, designId)) },
     ]
   }
 
@@ -226,7 +236,7 @@ export function prepareAdvisorMessages(agent, reviewType, designToken = null, do
       agent._advisorRound = 0
     }
     // Mutations exist → KEEP the round (cap keeps advancing through retries).
-    const user = buildAdvisorUserMessage(agent, prior, reviewType, designToken, documents, paths)
+    const user = buildAdvisorUserMessage(agent, prior, reviewType, designToken, documents, paths, object, designId)
     return [
       { role: "system", content: withTime(buildAdvisorSystemPrompt(agent, prior, reviewType)) },
       {
@@ -255,8 +265,25 @@ export function prepareAdvisorMessages(agent, reviewType, designToken = null, do
   // scopeFiles gives the fallback (agent gave no response table) a concrete
   // review surface.
   const scopeFiles = resolveScopeFiles(agent, paths)
+  const followUp = buildAdvisorFollowUp(agent, prior, scopeFiles, object)
+  // §24 D-24b (design round 2+ — async fix-round continuations must be able to
+  // re-approve): re-anchor the review scope (the convergence follow-up carries no
+  // document list) and inject the round's design token with the approval signal.
+  if (reviewType === "design") {
+    const docList = Array.isArray(documents)
+      ? documents.filter((d) => typeof d === "string" && d.trim())
+      : []
+    const scopeBlock = docList.length > 0
+      ? `\n\n## Documents to Review\nThe documents below are the review scope. Review ONLY these files — do not scan git diff or read any other files.\n${docList.map((d) => `- ${d} — Read this file in full`).join("\n")}`
+      : ""
+    const tokenBlock = designToken ? `\n\n${buildDesignApprovalBlock(designToken, designId)}` : ""
+    return [
+      { role: "system", content: withTime(buildAdvisorSystemPrompt(agent, prior, reviewType)) },
+      { role: "user", content: escapeLiteralEscapes(followUp + scopeBlock + tokenBlock) },
+    ]
+  }
   return [
     { role: "system", content: withTime(buildAdvisorSystemPrompt(agent, prior, reviewType)) },
-    { role: "user", content: escapeLiteralEscapes(buildAdvisorFollowUp(agent, prior, scopeFiles)) },
+    { role: "user", content: escapeLiteralEscapes(followUp) },
   ]
 }

package/src/agent/completion.mjs

@@ -7,6 +7,7 @@
 import { hasCodeMutations } from "../advisor/repos.mjs"
 import { pushReal } from "../context.mjs"
 import { MAX_ADVISOR_ROUNDS } from "../advisor/run.mjs"
+import { advisorReviewPending, effectiveAdvisorRound } from "../agent-tools/advisor-async.mjs"
 
 const MAX_VERIFY_PUSHBACKS = 2
 const MAX_VERIFY_RETRIES = 3
@@ -77,18 +78,20 @@ export function handleCompletion(agent, response, depth, turn, guardPushbacks, h
       pushReal(agent, { role: "assistant", content: response.content })
       agent.history.push({
         role: "user",
-        content: "[System reminder: you modified files in this run but have not verified the changes. Before finishing: call the verify tool to run syntax checks and tests. If verify reports failures, fix them and run verify again. If verification is genuinely impossible here, say so explicitly in your reply.]",
+        content: "[System reminder: you modified files in this run but have not verified the changes. Before finishing: run the project's verification yourself (per its AGENTS.md test method), then call verify declaring the outcome via verification.status. verify mechanically gates on your declaration. If verification is genuinely impossible here, say so explicitly in your reply.]",
       })
       callbacks.onTurnEnd?.(agent, turn)
       return { action: "continue", guardPushbacks, honestReminderInjected, advisorPushbacks }
     }
-    // Verified but still failing → pushback to fix (up to MAX_VERIFY_RETRIES)
+    // Verified but not passed → pushback to fix/complete (up to MAX_VERIFY_RETRIES).
+    // _verifyPassed === false means the declaration was failed, skipped without a
+    // reason, or not declared — not necessarily that a test failed.
     if (agent._verifiedThisRun && agent._verifyPassed === false && agent._verifyRetries < MAX_VERIFY_RETRIES) {
       agent._verifyRetries++
       pushReal(agent, { role: "assistant", content: response.content })
       agent.history.push({
         role: "user",
-        content: `[System reminder: verify reported test failures (retry ${agent._verifyRetries}/${MAX_VERIFY_RETRIES}). Review the failures, fix the issues, then run verify again. If you cannot fix after ${MAX_VERIFY_RETRIES} attempts, explain honestly what's blocking you.]`,
+        content: `[System reminder: (retry ${agent._verifyRetries}/${MAX_VERIFY_RETRIES}) verify was not passed — either your verification declared failed, was skipped without a reason, or was not declared. Fix or complete your verification, then call verify again declaring the outcome. If you cannot fix after ${MAX_VERIFY_RETRIES} attempts, explain honestly what's blocking you.]`,
       })
       callbacks.onTurnEnd?.(agent, turn)
       return { action: "continue", guardPushbacks, honestReminderInjected, advisorPushbacks }
@@ -103,7 +106,7 @@ export function handleCompletion(agent, response, depth, turn, guardPushbacks, h
       pushReal(agent, { role: "assistant", content: response.content })
       agent.history.push({
         role: "user",
-        content: `[System reminder: ${MAX_VERIFY_RETRIES} verify attempts exhausted and tests are still failing. In your response to the user, you MUST state explicitly: (1) what tests are still failing, (2) what you tried, (3) what you believe the root cause is. Do not present this as complete — the user needs to know the work is unfinished.]`,
+        content: `[System reminder: ${MAX_VERIFY_RETRIES} verify attempts exhausted. You have not passed verification. Either state explicitly that your verification could not be completed, or run verify again once it is. If your verification could not be completed, say so explicitly in your reply to the user — state what you tried and what you believe is blocking you, and do not present the work as complete; the user needs to know it is unfinished.]`,
       })
       callbacks.onTurnEnd?.(agent, turn)
       return { action: "continue", guardPushbacks, honestReminderInjected, advisorPushbacks }
@@ -117,18 +120,21 @@ export function handleCompletion(agent, response, depth, turn, guardPushbacks, h
   const cfg = agent.config?.advisor
   const advisorReview = cfg?.guard === true
   if (depth === 0 && advisorReview && !agent.config?.agent?.engineering) {
-    // 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)
+    // §24 D-24b (T-24b4 — guard timing): an async review that is still in flight
+    // (or queued in the advisor pool) means the review was launched — the guard
+    // does NOT push back while it is pending (未决不算未评审); once it settles
+    // non-stale it marks _calledAdvisorThisRun, and a STALE settle leaves the
+    // mark unset so the guard pushes back here again (fix #2 — no silent skip).
+    const pending = advisorReviewPending(agent)
+    const rounds = effectiveAdvisorRound(agent)
+    if (!pending && agent._mutatedThisRun && !agent._calledAdvisorThisRun && hasCodeMutations(agent)
         && advisorPushbacks < MAX_ADVISOR_PUSHBACKS
-        && (agent._advisorRound || 0) < MAX_ADVISOR_ROUNDS) {
+        && rounds < MAX_ADVISOR_ROUNDS) {
       advisorPushbacks++
       pushReal(agent, { role: "assistant", content: response.content })
       agent.history.push({
         role: "user",
-        content: `[System reminder: you changed code in this run and MUST get an advisor review before finishing (round ${agent._advisorRound + 1}). Call the \`advisor\` tool now. This is required, not optional — do not skip it even if you believe the changes are trivial — the review will be quick either way. After the review, produce a response table for every issue found (see discipline rules for format).]`,
+        content: `[System reminder: you changed code in this run and MUST get an advisor review before finishing (round ${rounds + 1}). Call the \`advisor\` tool now. This is required, not optional — do not skip it even if you believe the changes are trivial — the review will be quick either way. After the review, produce a response table for every issue found (see discipline rules for format).]`,
       })
       callbacks.onTurnEnd?.(agent, turn)
       return { action: "continue", guardPushbacks, honestReminderInjected, advisorPushbacks }