thincoder 0.12.54 → 0.12.59

package/src/agent/helpers.mjs

@@ -33,7 +33,47 @@ export const REPORT_CONTINUATION =
   "4. Anything left undone or worth follow-up"
 
 const TOOL_RESULT_OFFLOAD_LIMIT = 64 * 1024 // 65536 chars — offload only above 64K (2026-08-24)
-const TOOL_RESULT_PREVIEW = 64 * 1024 // chars shown inline when offloaded (aligns with CLI/VS Code webview)
+const TOOL_RESULT_PREVIEW = 64 * 1024 // total preview budget: head + middle note + tail ≤ 65536 (aligns with CLI/VS Code webview)
+const TOOL_RESULT_PREVIEW_HEAD = 16 * 1024 // head slice preserved (2026-09-04 §5 — dual-end preview)
+const TOOL_RESULT_PREVIEW_TAIL = 48 * 1024 // nominal tail slice (results/errors/stats live here — actual tail = budget remainder, see buildDualEndPreview)
+
+/** UTF-16 安全截断（2026-09-02 deepseek 400 根因）：slice(0, N) 按码元切会把 emoji 代理对切成孤立
+ *  高代理（如 🔴=U+D83D+DD34 只剩 D83D）——deepseek 解析器严格 UTF-16 报 400
+ *  "unexpected end of hex escape"。截断点落在高代理上时向前收一个码元。
+ *  与 setup.mjs 的 safeSliceUTF16 同语义（两处独立实现——escape.mjs 的 sanitizeLoneSurrogates 是发送兜底，此处是源头）。 */
+function safeSliceUTF16(text, max) {
+  if (text.length <= max) return text
+  const cp = text.charCodeAt(max - 1)
+  if (cp >= 0xd800 && cp <= 0xdbff) return text.slice(0, max - 1)
+  return text.slice(0, max)
+}
+
+/** UTF-16 safe END slice (2026-09-04 §5 dual-end preview — review #5: both boundaries must not split
+ *  a surrogate pair). Same rule as safeSliceUTF16, mirrored: if the slice START lands on a LOW
+ *  surrogate (DC00-DFFF — the second half of a pair whose high half sits just before the boundary),
+ *  advance one code unit so the slice never begins with an orphan low surrogate. */
+function safeSliceUTF16End(text, max) {
+  if (text.length <= max) return text
+  const start = text.length - max
+  const cp = text.charCodeAt(start)
+  if (cp >= 0xdc00 && cp <= 0xdfff) return text.slice(start + 1)
+  return text.slice(start)
+}
+
+/** Dual-end preview (design §5 D-4.1): head + middle-omitted note + tail — the tail carries
+ *  results/errors/stats that a pure-head truncation would cut off.
+ *  Budget (round1 review #2, fixed): head + note + tail ≤ TOOL_RESULT_PREVIEW (65536) — tail is
+ *  computed from constants (tail = TOOL_RESULT_PREVIEW − head − noteLen), never hardcoded.
+ *  The note length depends on the omitted digit count; text.length's digit count is an upper bound
+ *  for omitted (< text.length), so budgeting with it keeps the total ≤ 65536 while the printed
+ *  note reports the actual omitted count. Both boundaries run surrogate-safe slices (review #5). */
+function buildDualEndPreview(text) {
+  const head = safeSliceUTF16(text, TOOL_RESULT_PREVIEW_HEAD)
+  const noteFn = (omitted) => `\n\n… [middle omitted: ${omitted} chars] …\n\n`
+  const tailLen = Math.min(TOOL_RESULT_PREVIEW_TAIL, TOOL_RESULT_PREVIEW - TOOL_RESULT_PREVIEW_HEAD - noteFn(text.length).length)
+  const tail = safeSliceUTF16End(text, tailLen)
+  return head + noteFn(Math.max(0, text.length - head.length - tail.length)) + tail
+}
 
 /** Offload-dir write-time self-cleanup retention window (2026-08-21): files older than 3 days are deleted on the next offload. */
 export const TMP_RETENTION_MS = 3 * 24 * 3600 * 1000
@@ -77,7 +117,8 @@ export async function cleanupOldToolResults(dir) {
   }
 }
 
-/** Offload oversized tool results (>64K chars) to disk, returning a preview + file path.
+/** Offload oversized tool results (>64K chars) to disk, returning a head+tail preview + file path
+ *  (2026-09-04 §5 — dual-end preview; the failed-offload fallback uses the same dual-end slice).
  *  Writes trigger write-time self-cleanup of the offload dir first (dir param overridable for tests). */
 export async function offloadToolResult(text, callId, dir = join(configDir, "tool-results")) {
   if (text.length <= TOOL_RESULT_OFFLOAD_LIMIT) return text
@@ -87,12 +128,13 @@ export async function offloadToolResult(text, callId, dir = join(configDir, "too
     const file = join(dir, `${Date.now()}-${String(callId).replace(/[^a-zA-Z0-9_-]/g, "_")}.log`)
     await writeFile(file, text, "utf8")
     return (
-      text.slice(0, TOOL_RESULT_PREVIEW) +
+      buildDualEndPreview(text) +
       `\n\n[... output too large (${text.length} chars total), full content saved to: ${file}\n` +
       `Page through it with the read tool (offset/limit) or sed -n 'START,ENDp' — do NOT re-run the tool blindly.]`
     )
   } catch {
-    return text.slice(0, TOOL_RESULT_OFFLOAD_LIMIT) + `\n\n[... truncated: ${text.length} chars total, offload to disk failed]`
+    // review #3: fallback uses the same dual-end slice (head + omitted note + tail, no path hint)
+    return buildDualEndPreview(text) + `\n\n[... truncated: ${text.length} chars total, offload to disk failed]`
   }
 }
 

package/src/agent/setup.mjs

@@ -22,10 +22,21 @@ import { fileURLToPath } from "node:url"
 const DEFAULT_COMPACT_THRESHOLD = 100_000
 const DOC_SEARCH_LIMIT = 5
 const DOC_CHUNK_PREVIEW_LEN = 300
+/** UTF-16 安全截断（2026-09-02 deepseek 400 根因）：slice(0, N) 按码元切会把 emoji 代理对切成孤立
+ *  高代理（如 🔴=U+D83D+DD34 只剩 D83D）——deepseek 解析器严格 UTF-16 报 400
+ *  "unexpected end of hex escape"。截断点落在高代理上时向前收一个码元。 */
+function safeSliceUTF16(text, max) {
+  if (text.length <= max) return text
+  const end = max
+  // 截断点恰在高代理（D800-DBFF）上 → 收到高代理之前（不带它）
+  const cp = text.charCodeAt(end - 1)
+  if (cp >= 0xd800 && cp <= 0xdbff) return text.slice(0, end - 1)
+  return text.slice(0, end)
+}
 const MEMORY_SEARCH_LIMIT = 3
 
 /** Build engineering-mode system prompt by reading METHODOLOGY.md and wrapping it in the engineering template */
-async function buildEngineeringPrompt(cwd, role) {
+export async function buildEngineeringPrompt(cwd, role) {
   const engFile = role === "eng-coder" ? "engineering-sub.md" : "engineering.md"
   const engTemplatePath = resolve(dirname(fileURLToPath(import.meta.url)), "..", "prompts", engFile)
   let engTemplate = ""
@@ -38,8 +49,17 @@ async function buildEngineeringPrompt(cwd, role) {
   const methodologyPath = resolve(cwd, "METHODOLOGY.md")
   if (!existsSync(methodologyPath)) {
     // Template-only — engineering constraints stay active, minus project rules.
-    // The caller injects a warning into the history.
-    return { prompt: engTemplate || null, templateMissing, methodologyMissing: true }
+    // The caller injects a warning into the history. Resolve the built-in
+    // methodology template to an absolute path (same-source join as the
+    // engineering template above — the packaged path is unreachable from the
+    // user's cwd) and carry its body so the warning can embed it verbatim
+    // (2026-09-02 D-M1/D-M2: template reachability for the model).
+    const methodologyTemplatePath = resolve(dirname(fileURLToPath(import.meta.url)), "..", "prompts", "methodology-template.md")
+    let methodologyTemplateBody = null
+    try { methodologyTemplateBody = readFileSync(methodologyTemplatePath, "utf8") } catch {
+      // Template unreadable (packaging) — degraded: base warning only (no path/body injected), same as VS Code.
+    }
+    return { prompt: engTemplate || null, templateMissing, methodologyMissing: true, methodologyTemplatePath, methodologyTemplateBody }
   }
   const methodology = readFileSync(methodologyPath, "utf8")
   const prompt = engTemplate
@@ -114,7 +134,7 @@ export async function prepareRun(agent, input, callbacks, {
           role: "user",
           content:
             `[Relevant documentation${more}:\n` +
-            docs.map((d) => `- ${d.path}${d.heading ? " > " + d.heading : ""}: <untrusted_doc_chunk>${escapeXml(d.content.slice(0, DOC_CHUNK_PREVIEW_LEN))}</untrusted_doc_chunk>`).join("\n") +
+            docs.map((d) => `- ${d.path}${d.heading ? " > " + d.heading : ""}: <untrusted_doc_chunk>${escapeXml(safeSliceUTF16(d.content, DOC_CHUNK_PREVIEW_LEN))}</untrusted_doc_chunk>`).join("\n") +
             "]",
           transient: true,
         })
@@ -167,12 +187,13 @@ export async function prepareRun(agent, input, callbacks, {
 
   // task/plan tools are injected with the main loop; subagent/skill/goal/verify only at top level
   // eng-coder subagents get advisor for mandatory design review before coding
-  const { planTool, subagentTool, taskTool, skillTool, goalTool, verifyTool, recentChangesTool, timerTool, advisorTool, engTool } = await import("../agent-tools.mjs")
+  const { planTool, subagentTool, taskTool, skillTool, goalTool, verifyTool, recentChangesTool, timerTool, advisorTool, engTool, readHistoryTool } = await import("../agent-tools.mjs")
   const { consultStartTool, consultCheckTool, consultStopTool } = await import("../agent-tools/consult.mjs")
-  const { escalateTool } = await import("../agent-tools/escalate.mjs")
   const { CONSULT_BASE } = await import("../agent.mjs")
-  // withPool: decorate consult_start/escalate descriptions with the CURRENT candidate pool
-  // so the model knows which models it can pick (CLI parity with the plugin).
+  // withPool: decorate the consult_start description with the CURRENT candidate pool
+  // so the model knows which models it can pick (CLI parity with the plugin). The
+  // retired escalate tool surface is now the subagent action:"escalate" — its pool
+  // list is decorated onto the action property description below (same intent).
   const withPool = (tool) => {
     const models = agent.config?.agent?.consultModels ?? []
     const list = models.map((m) => `${m.provider}:${m.model}${m.effort ? ` (${m.effort})` : ""}`).join(", ")
@@ -199,28 +220,82 @@ export async function prepareRun(agent, input, callbacks, {
       properties: {
         ...subagentTool.parameters.properties,
         role: { ...subagentTool.parameters.properties.role, ...subagentRoles },
+        // §19: escalate 动作的候选池 = consultModels（缺省池首 / 指定 provider:model）。
+        // 池装饰挂在 action 属性描述（原 escalate 工具注册时 withPool 同款意图——模型
+        // 需要知道可选候选人）。escalate 在工程模式禁用——装饰只对正常模式有意义。
+        action: (agent.config?.agent?.consultModels?.length && !agent.config?.agent?.engineering)
+          ? {
+              ...subagentTool.parameters.properties.action,
+              description: subagentTool.parameters.properties.action.description +
+                `\nCurrently configured escalate candidates (agent.consultModels pool): ${agent.config.agent.consultModels.map((m) => `${m.provider}:${m.model}${m.effort ? ` (${m.effort})` : ""}`).join(", ")}`,
+            }
+          : subagentTool.parameters.properties.action,
       },
     },
   } : subagentTool
 
-  // Consult/escalate tools registered only when configured — an unconfigured pool would
-  // otherwise make the model call them and eat an error turn (plugin parity).
-  // escalate is fail-closed in engineering mode (execute() rejects there) — registering it
-  // anyway would hand the model a tool that is guaranteed to eat an error turn.
+  // §18 D-E3: eng-coder children (depth>0) get an audit-only subagent channel —
+  // role enum limited to explore, NO async parameter (sync only) and action pinned
+  // to spawn (§19 D-M3 restricted-variant action gate — escalate/check/status are
+  // refused here at the schema level too; the mechanical re-check lives in
+  // subagent.mjs execute → the §19 action gate + gateEngCoderSpawn (spawn-child.mjs)
+  // — schema enums are advisory, providers don't enforce them).
+  const engAuditSubagent = depth > 0 && agent._role === "eng-coder"
+    ? (() => {
+        const props = { ...subagentTool.parameters.properties }
+        // §19 review hygiene: the audit channel is spawn-only sync explore — drop
+        // async, the check/status params (id/n) and the eng-coder token params
+        // (designToken/designId are meaningless for a read-only audit spawn; the
+        // parent spawn already carried the token). Schema noise would invite the
+        // model to pass irrelevant args.
+        delete props.async // sync only — the eng-coder blocks on the audit report
+        delete props.id
+        delete props.n
+        delete props.designToken
+        delete props.designId
+        props.role = {
+          type: "string",
+          enum: ["explore"],
+          description: "explore only — the eng-coder's internal spawn channel is reserved for read-only divergence audits (AGENT-LOOP.md §18 D-E3).",
+        }
+        props.action = {
+          type: "string",
+          enum: ["spawn"],
+          description: "spawn only — the eng-coder's internal spawn channel is reserved for read-only divergence audits (AGENT-LOOP.md §19 D-M3); escalate/check/status are refused (escalate spawns a coder+WRITE child — against explore-only intent; check/status have no async pool in a child context).",
+        }
+        return {
+          ...subagentTool,
+          name: "subagent",
+          description: "Spawn a read-only `explore` sub-agent to AUDIT your delivery against the design (AGENT-LOOP.md §18 D-E2 ③): it compares the delivered code with the design for divergence — partially implemented acceptance criteria, silent simplifications, doc drift, changes outside the approved file list. BLOCKING ONLY (no async — the audit report decides your next protocol step). action:'spawn' ONLY — the audit channel is a read-only spawn; escalate/check/status are not available (AGENT-LOOP.md §19). The audit task book is appended MECHANICALLY — your own spawn task (docs involved / acceptance criteria / file list) plus the files you actually touched; never hand the audit a self-written file list (a self-report could omit exactly the out-of-scope file it must catch).",
+          parameters: { ...subagentTool.parameters, properties: props },
+        }
+      })()
+    : null
+
+  // consult 工具仅在配置时注册（consultModels 空池时注册会让模型调用后吃一个错误回合）——
+  // §19: escalate 已并入常驻 subagent 的 action:"escalate"（无空池注册问题——动作在
+  // 池空时返回既有错误语义，工程模式 fail-closed 在 execute 内拒绝）。
   const consultModels = agent.config?.agent?.consultModels ?? []
-  const engineering = agent.config?.agent?.engineering
   const consultTools = consultModels.length
-    ? [withPool(consultStartTool), consultCheckTool, consultStopTool, ...(engineering ? [] : [withPool(escalateTool)])]
+    ? [withPool(consultStartTool), consultCheckTool, consultStopTool]
     : []
-  const depthOnly = depth === 0 ? [filteredSubagent, skillTool, goalTool, engTool, verifyTool, recentChangesTool, advisorTool, ...consultTools]
-    // Write-permission coder sub-agents (subagent role="coder" + escalate): the
-    // system prompt names verify (system.md) and advisor (discipline.md) — without them an
+  const depthOnly = depth === 0 ? [filteredSubagent, skillTool, goalTool, engTool, verifyTool, recentChangesTool, readHistoryTool, advisorTool, ...consultTools]
+    // SESSION.md §9 D-S2: read_history is depth-0 ONLY — a subagent querying "the session"
+    // would mix its throwaway context with the parent's record (semantic confusion).
+    // It is readonly:true, so planMode pass and no permission ask come automatically (T-S9).
+    // Write-permission coder sub-agents (subagent role="coder" + escalate action):
+    // the system prompt names verify (system.md) and advisor (discipline.md) — without them an
     // escalate hit "unknown tool" and fell back to bash node --check / npm test to
     // self-verify (2026-08-16 deepseek escalate diagnosis; plugin parity).
-    : agent._role === "eng-coder" ? [advisorTool, verifyTool]
+    // eng-coder: advisor + verify + the §18 audit-only subagent channel (D-E3).
+    : agent._role === "eng-coder" ? [advisorTool, verifyTool, ...(engAuditSubagent ? [engAuditSubagent] : [])]
     : agent._role === "coder" ? [verifyTool, advisorTool]
     : agent._role === "consult" ? [recentChangesTool]
     : []
+  // NOTE: every depth-0 tool schema is estimated into the compaction overhead per turn
+  // (context.mjs extras.tools) — a tool-schema change shifts the compaction fixture
+  // knife-edges (agent.test T3b: read_history's schema +~470 tokens once crossed its
+  // 11000 threshold; fixture adjusted to 12500 — rationale in the test comment).
   const tools = [...agent.tools, taskTool, planTool, timerTool, ...depthOnly]
   const toolSchemas = tools.map(toOpenAISchema)
   const toolByName = new Map(tools.map((t) => [t.name, t]))
@@ -252,7 +327,15 @@ export async function prepareRun(agent, input, callbacks, {
         warnings.push(`Engineering template (${agent._role === "eng-coder" ? "engineering-sub.md" : "engineering.md"}) not found — using degraded constraints.`)
       }
       if (engResult.methodologyMissing) {
-        warnings.push("METHODOLOGY.md not found in the project root — no project methodology is loaded, so every 'per METHODOLOGY' reference in the engineering prompt is dangling and the three-document hard flow (requirements / design / test doc) is NOT enforced. Ask the user whether to create METHODOLOGY.md (scaffold available as src/prompts/methodology-template.md) before designing.")
+        let warning = "METHODOLOGY.md not found in the project root — no project methodology is loaded, so every 'per METHODOLOGY' reference in the engineering prompt is dangling and the three-document hard flow (requirements / design / test doc) is NOT enforced. Ask the user whether to create METHODOLOGY.md; if the user confirms, write cwd/METHODOLOGY.md before designing."
+        // 2026-09-02 D-M1/D-M2 (template accessibility): absolute path + full body — the model
+        // can read the template directly instead of hand-writing one from an unreachable source
+        // path. Body read failure → degraded warning above (path/body not injected). VS Code
+        // setup-reminders.mjs parity (两端警告文本一致，本端以 CLI 为准).
+        if (engResult.methodologyTemplateBody) {
+          warning += `\n\nbuilt-in template（可 read ${engResult.methodologyTemplatePath} 或直接参考以下内容）:\n\n${engResult.methodologyTemplateBody}`
+        }
+        warnings.push(warning)
       }
       if (warnings.length > 0) {
         agent.history.push({

package/src/agent/spawn-child.mjs

@@ -26,6 +26,31 @@ const RS = "\x1e"
  *  单源化（2026-08-30 评审）：文案演进只改这里，消除文案与检测正则的漂移面。 */
 export const TURN_CAP_MARK = "stopped: turn cap reached"
 
+/**
+ * §18 D-E3 eng-coder 内部 spawn 机械门（AGENT-LOOP.md §18 D-E2 round5 #2 后备）：
+ * eng-coder 子代理（depth>0 且 parent._role==="eng-coder"）的内部 spawn 通道只做
+ * 偏差审计——role 仅 explore、async 强制同步；审计 spawn 预算 = 首审 1 + 修正轮
+ * ≤5 的再审（第 7 次审计 spawn 机械拒绝——5 轮纪律失效时不静默，错误即 stalled
+ * 信号）。返回 null = 非 eng-coder 上下文（不加限制）；返回审计尝试序号 = 通过。
+ * schema 层过滤（setup.mjs 受限变体）只是给模型的参数提示——本函数是机械强制。
+ */
+export const ENG_AUDIT_SPAWN_LIMIT = 6 // 允许 6 次审计 spawn；第 7 次拒绝
+export function gateEngCoderSpawn(parent, depth, role, async) {
+  if ((depth ?? 0) <= 0 || parent?._role !== "eng-coder") return null
+  if (role !== "explore") {
+    throw new Error("eng-coder subagents may only spawn role='explore' — internal spawns exist solely for the read-only divergence audit (AGENT-LOOP.md §18 D-E3)")
+  }
+  if (async === true) {
+    throw new Error("eng-coder internal spawns are sync-only — the audit report must return before the next protocol step; async spawn is only available at the top level (AGENT-LOOP.md §18 D-E3)")
+  }
+  const attempt = (parent._engAuditSpawns ?? 0) + 1
+  if (attempt > ENG_AUDIT_SPAWN_LIMIT) {
+    throw new Error("correction-round limit exceeded — deliver a stalled report (AGENT-LOOP.md §18: max 5 fix rounds; the 7th audit spawn is refused mechanically)")
+  }
+  parent._engAuditSpawns = attempt
+  return attempt
+}
+
 /**
  * 构造 relay 前缀 + 发送 `[model]` 元数据 token（显示层据此更新区块头部，
  * 不进内容流）。counter 挂在 parent agent 上，多轮/并行子代理互不冲突。
@@ -51,7 +76,9 @@ export function makeRelay(parent, label, emit, model) {
 // Single source for the event grammar branch lists (consult P3, 2026-08-30):
 // stripEventToken (display) and stripEventTokensForCapture (capture) shared them
 // literally — extending the event set meant touching both regexes.
-const EVENT_PHASE = "turn|approval"
+// "done" = §15 D-A3 async-child completion event (emitted by the parent's
+// turn-end collection, not by children — listed so the grammar stays honest).
+const EVENT_PHASE = "turn|approval|done"
 const EVENT_TYPE = "llm|tool|approval|done"
 const WELL_FORMED_EVENT = new RegExp(`^${EVENT_SENTINEL}(${EVENT_PHASE})${RS}[^${RS}]*${RS}[^${RS}]*${RS}(${EVENT_TYPE})${RS}`)
 export function stripEventToken(text) {

package/src/agent-tools/advisor.mjs

@@ -77,11 +77,26 @@ export const advisorTool = {
     "For design review: single-pass review against methodology and requirements. " +
     "Review criteria come from .thincoder/advisor.md (if present) or sensible defaults. " +
     "After the review, you MUST produce a response table (see discipline rules for format). " +
-    "If advisor says all clear, call verify.",
+    "If advisor says all clear, call verify. " +
+    "Optionally pass object={type,target,status,reason,exclude} to anchor the review target " +
+    "(AGENT-LOOP.md §18.8 — the review-object declaration is mechanically injected into the review message); " +
+    "absent → legacy behavior (no injection). " +
+    "Returns the review report — the advisor's findings verdict: all-clear (call verify) or a findings list to fix.",
   parameters: {
     type: "object",
     properties: {
       type: { type: "string", enum: ["code", "design"], description: "Review type: 'design' for design doc review, 'code' for code review (default)" },
+      object: {
+        type: "object",
+        properties: {
+          type: { type: "string", description: "Review type as declared by the caller (design/code)" },
+          target: { type: "string", description: "Review target — document + section, or file(s)" },
+          status: { type: "string", description: "Object state: 待评审 / 已批准 / 已实现 (pending-review / approved / implemented)" },
+          reason: { type: "string", description: "Why this review runs: user-initiated / delivery verification" },
+          exclude: { type: "string", description: "Explicit exclusion list — approved/implemented items NOT in this review" },
+        },
+        description: "Review-object declaration (§18.8): mechanically injected at the start of the review user message so the advisor does not re-derive the review target. Absent → no injection (legacy behavior).",
+      },
       paths: {
         type: "array",
         items: { type: "string" },
@@ -101,6 +116,13 @@ export const advisorTool = {
     const agent = ctx.agent
     const reviewType = args.type || "code"
     const documents = args.documents || null
+    // Review-object declaration (§18.8 D-OA3): the PARENT constructs it and the
+    // advisor tool passes it through — mechanical anchoring, not model inference.
+    // Any non-object value (string/array/primitive, possibly from a malformed
+    // tool call) degrades to null = no injection (legacy calls unchanged).
+    const reviewObject = args.object && typeof args.object === "object" && !Array.isArray(args.object)
+      ? args.object
+      : null
     // Scope fallback: the runtime mutation record (zero git) covers guard-triggered
     // reviews where the model did not pass explicit paths.
     const paths = args.paths || (agent._touchedFiles?.length ? [...agent._touchedFiles] : null)
@@ -130,11 +152,16 @@ export const advisorTool = {
     // Generate the design token BEFORE the review and inject it into the advisor's prompt.
     // The advisor (LLM) decides pass/fail itself and echoes the token only on approval —
     // the gate is a mechanical string match, not fragile semantics parsing.
+    // A random designId is minted for EVERY design-review call (2026-09-01 multi-design
+    // slots): on pass the token is stored in parent._engDesignTokens keyed by this id and
+    // the id is echoed to the parent; on failure the id is dropped — never stored, so it
+    // cannot clobber any other design's slot. Not a document anchor (rejected 2026-08-31).
     const designToken = reviewType === "design" ? generateDesignToken(agent) : null
+    const designId = reviewType === "design" ? randomUUID() : null
     const result = await runAdvisorReview(agent, reviewType, {
       onOutput: ctx.onOutput,
       signal: ctx.signal,
-    }, designToken, documents, paths)
+    }, designToken, documents, paths, reviewObject)
 
     if (reviewType === "design") {
       // Whitespace-tolerant match (LLM may add spaces or wrap in fences).
@@ -144,6 +171,11 @@ export const advisorTool = {
       if (designToken && result && tokenPattern.test(result)) {
         // Advisor echoed the token → review passed. Issue it to the parent for eng-coder.
         // (session cleanup for design reviews is owned by runAdvisorReview)
+        // Multi-design slots (2026-09-01): store under this review's designId; the single
+        // `_engDesignToken` mirror stays for the legacy boolean gates (dispatch "has token",
+        // session persistence) — key decision ② of ENGINEERING-MODE.md §7 2026-09-01.
+        agent._engDesignTokens ??= new Map()
+        agent._engDesignTokens.set(designId, designToken)
         agent._engDesignToken = designToken
         // Unlock the dispatch design gate (dispatch.mjs) for eng-coder SELF-review:
         // an eng-coder whose own design review passed may write files without the
@@ -156,16 +188,16 @@ export const advisorTool = {
         if (agent._role === "eng-coder") agent._engDesignReviewed = true
         // Strip the bracketed token so only ONE unambiguous format (plain UUID) reaches the main agent
         const cleanResult = result.replace(makeDesignTokenRegex(designToken, "g"), "").trim()
-        return `${cleanResult}\n\nApproved. Pass this exact token to eng-coder (designToken parameter): ${designToken}`
+        // designId rides the Approved block (review #1): the parent needs it to aim the FIRST
+        // eng-coder spawn when several designs live in the same session.
+        return `${cleanResult}\n\nApproved. Pass this exact token to eng-coder (designToken parameter): ${designToken}\ndesignId: ${designId} (pass as the designId parameter when spawning eng-coder; optional while this session holds a single design)`
       }
-      // Review failed (or advisor chose not to pass) → invalidate any previously-issued token.
-      // Guards (v2 2026-08-25): result === null means the review was SKIPPED (advisor disabled /
-      // not engineering mode) — must not revoke. An error reply (own "Advisor:" prefix — the
-      // error-return convention of runAdvisorReview) is a provider crash/timeout artifact, not
-      // a completed verdict — a network glitch must not revoke unrelated standing tokens.
-      // Only a COMPLETED review that did not pass revokes.
-      const isCompletedReview = result !== null && !result.startsWith("Advisor:")
-      if (isCompletedReview) agent._engDesignToken = null
+      // Review failed (or advisor chose not to pass) → do NOT touch ANY slot (方案 ②, review #2:
+      // a failed RE-review leaves the previously approved token alive until TTL; the failed call's
+      // own designId was never stored, so there is nothing to clear). Isolation (2026-08-30,
+      // extended to the multi-slot Map 2026-09-01): a network glitch must not clear / other
+      // designs' slots must not be affected — only a COMPLETED non-passing review lands here,
+      // and it revokes nothing.
       // Strip every dead token occurrence from the raw output so the main agent can't grab an invalid one
       if (result) {
         const stripped = result.replace(makeDesignTokenRegex(designToken, "g"), "").trim()

package/src/agent-tools/consult.mjs

@@ -13,6 +13,7 @@
  */
 import { createAgent, runAgent, readonlyToolNames } from "../agent.mjs"
 import { resolveChildProvider } from "./subagent.mjs"
+import { logEvent, errText } from "../log.mjs"
 import { makeRelay, wrapChildCallbacks, runWithContinue, ensureChildApiKey, clampEffort } from "../agent/spawn-child.mjs"
 
 // Named consult defaults (consult P2, 2026-08-30).
@@ -27,7 +28,7 @@ function consultLabel(m) {
 /** Narrow the configured consultModels pool to a requested subset.
  *  Each selector is "provider:model", a bare provider name, or a bare model name
  *  (case-insensitive). A trailing " (effort)" suffix is tolerated (round2 复核
- *  对齐 escalate.mjs：withPool 列表会带 " (high)" 后缀，模型照抄应可匹配).
+ *  对齐 escalate 动作（subagent action:"escalate"）：withPool 列表会带 " (high)" 后缀，模型照抄应可匹配).
  *  Returns { models, error } — error set when a selector matches
  *  nothing (surface the typo rather than silently dropping it). Absent/empty selectors
  *  → the full pool. */
@@ -145,6 +146,21 @@ async function runConsultChild(ctx, session, id, m, problem, ctrl) {
   }
   let watchdog = armWatchdog()
   const label = consultLabel(m)
+  // LOGGING（LOGGING.md）：child:*（consult）——logSettle 在函数作用域声明（外层 catch
+  // 覆盖 spawn 前失败路径）；spawn 事件在 relay 建立后发射（logArmed 翻转——provider/
+  // 创建失败 = 从未启动，不落子事件、错误仅经 settleChild 进会话）。
+  let childLogId = null
+  let logT0 = 0
+  let logArmed = false
+  let logDone = false
+  const logSettle = (kind, payload) => {
+    if (!logArmed || logDone || !childLogId) return
+    logDone = true
+    const ms = Date.now() - logT0
+    const base = { role: "consult", id: childLogId, ms }
+    if (kind === "ok" || kind === "partial") logEvent("child:done", { ...base, kind })
+    else logEvent("child:error", { ...base, err: errText(payload, 200) })
+  }
   try {
     // Provider resolution: consultModels entries are { provider, model, effort? } — resolve
     // via the subagent's provider resolver ("provider:model" handles cross-provider picks).
@@ -156,9 +172,10 @@ async function runConsultChild(ctx, session, id, m, problem, ctrl) {
     }
     // Clamp the pool's effort to the model's reasoningEffortEnum — an out-of-enum
     // value makes provider/core throw on EVERY chat call (candidate dies on takeoff).
-    // Symmetric with escalate.mjs; 2026-08-16 a real consult died on qwen3.8-max
-    // effort "high" (enum is xhigh/medium/low). Out-of-enum: DROP the effort entirely
-    // (the provider preset default may ALSO be out-of-enum for this override model).
+    // Symmetric with the escalate action (subagent action:"escalate"); 2026-08-16
+    // a real consult died on qwen3.8-max effort "high" (enum is xhigh/medium/low).
+    // Out-of-enum: DROP the effort entirely (the provider preset default may ALSO be
+    // out-of-enum for this override model).
     clampEffort(provider, m.model, m.effort)
 
     // Read-only consultant: filter the parent tool set down to readonly tools + main_history.
@@ -183,6 +200,12 @@ async function runConsultChild(ctx, session, id, m, problem, ctrl) {
     // prefix (same channel subagent uses — parallel consultants stay independent) +
     // onToolOutput passthrough so the consultant's tool output lands in its TUI block.
     const relayPrefix = makeRelay(agent, "consult", ctx.callbacks?.onToken, provider.model ?? "")
+    // LOGGING：arm（spawn 事件——relay 建立后；子内事件归属 _logId）
+    childLogId = relayPrefix.slice(0, -1)
+    child._logId = childLogId
+    logT0 = Date.now()
+    logArmed = true
+    logEvent("child:spawn", { role: "consult", id: childLogId, kind: "consult" })
     const childCallbacks = wrapChildCallbacks(relayPrefix, ctx.callbacks ?? {})
     let declined = false // review #1: guard against double-settle when onDeclined fired
 
@@ -216,6 +239,7 @@ async function runConsultChild(ctx, session, id, m, problem, ctrl) {
           onDeclined: (e) => {
             declined = true
             settleChild(session, id, label, false, `turn cap reached (${e.turn} turns) — stopped, diagnosis may be partial`)
+            logSettle("partial", null)
             return undefined
           },
         },
@@ -224,18 +248,23 @@ async function runConsultChild(ctx, session, id, m, problem, ctrl) {
       // settling again here would push a phantom empty success reply and decrement
       // `pending` twice (negative pending → consult_check's two exits both
       // unreachable → permanent block until user abort).
-      if (!declined) settleChild(session, id, label, true, String(result ?? ""))
+      if (!declined) {
+        settleChild(session, id, label, true, String(result ?? ""))
+        logSettle("ok", null)
+      }
     } catch (e) {
       // Runner errors (incl. the watchdog's abort) settle as a failed reply — the
       // continue/declined paths are already handled inside runWithContinue.
       const note = timedOut ? `consultation timed out after ${Math.round(timeoutMs / 60000)}min (agent.consultTimeoutMs)` : e?.message ?? String(e)
       settleChild(session, id, label, false, note)
+      logSettle("error", note)
     }
   } catch (e) {
     // Errors BEFORE the runner (provider resolution, createAgent) or a throwing
     // continue-prompt settle as failed replies — the runner's own errors are already
     // handled inside the loop above.
     settleChild(session, id, label, false, e?.message ?? String(e))
+    logSettle("error", e?.message ?? String(e))
   } finally {
     clearTimeout(watchdog)
   }
@@ -326,6 +355,7 @@ export const consultCheckTool = {
     "replies are coming.\n" +
     "Call it ALONE in a turn — do NOT batch it with calls that depend on its reply (readonly tools run in parallel).\n" +
     "Replies arrive in arrival order: call it repeatedly (n = 1, 2, 3, …) until done is true.\n" +
+    "Returns JSON: {reply, model, failedReply, received, failed, terminated, total, done} for a reply — or {done: true, received, failed, total} when none are left.\n" +
     "Parameters:\n" +
     "- id (required): the consult id from consult_start\n" +
     "- n (required): the 1-based read number for this consult — pass 1 on the first check, 2 on the next, and so on. It exists so consecutive checks are distinct tool calls (loop detectors) and the transcript reads as a sequence.",
@@ -382,7 +412,8 @@ export const consultStopTool = {
   sideEffectExempt: true,
   description:
     "Terminate the still-running consultations of a session once a reply is good enough — saves tokens and time. " +
-    "Already-answered replies stay available for consult_check.\n" +
+    "Already-answered replies stay available for consult_check. " +
+    "Returns JSON {stopped: <n>, abandoned: <pending count>} — or {error: \"unknown consult id\"}.\n" +
     "Parameters:\n" +
     "- id (required): the consult id from consult_start\n" +
     "- n (required): incrementing call number for this consult (next value after the last consult_check/consult_stop) — keeps repeated calls distinct.",

package/src/agent-tools/eng.mjs

@@ -8,7 +8,8 @@ import { ENG_ON_REMINDER, ENG_OFF_REMINDER } from "../agent.mjs"
 export const engTool = {
   name: "eng",
   description:
-    "Enter or exit engineering mode. In engineering mode, follow design-before-code: write a design document, run advisor design review, get user approval, then implement via eng-coder subagents.",
+    "Enter or exit engineering mode. In engineering mode, follow design-before-code: write a design document, run advisor design review, get user approval, then implement via eng-coder subagents. " +
+    "Returns the mode state — 'Engineering mode activated/exited' (an already-active state is acknowledged).",
   parameters: {
     type: "object",
     properties: {
@@ -22,6 +23,7 @@ export const engTool = {
     if (args.action === "exit") {
       ctx.agent.config.agent.engineering = false
       ctx.agent._engDesignToken = null   // stale token from prior design review invalidated
+      ctx.agent._engDesignTokens = new Map() // multi-design slots die with the mode (2026-09-01 fix #2)
       ctx.agent._engDesignReviewed = false // reset gate state
       ctx.agent._advisorRound = 0          // reset convergence budget
       ctx.agent._touchedFiles = []         // clear mutation tracking
@@ -49,6 +51,7 @@ export const engTool = {
       }
       ctx.agent.config.agent.engineering = true
       ctx.agent._engDesignToken = null   // off→on transition requires a fresh design review
+      ctx.agent._engDesignTokens = new Map() // multi-design slots die with the mode (2026-09-01 fix #2)
       ctx.agent._lastEngState = true
       ctx.agent._pendingReminders = ctx.agent._pendingReminders ?? []
       ctx.agent._pendingReminders.push(ENG_ON_REMINDER)

package/src/agent-tools/goal.mjs

@@ -11,7 +11,8 @@ export const goalTool = {
     "action='set': create or replace the goal — must have a verifiable completion criterion (a machine-checkable proof, not vague effort). " +
     "action='complete': mark achieved — only after the criterion's check has actually passed. " +
     "action='blocked': report an impasse (requires 'reason') — only after 3 genuine attempts. " +
-    "action='cancel': abandon the goal.",
+    "action='cancel': abandon the goal. " +
+    "Returns a status line — the goal set/updated/completed/blocked/cancelled confirmation, or Error: ... with the reason.",
   parameters: {
     type: "object",
     properties: {
@@ -76,6 +77,15 @@ Has this goal been achieved? Answer ONLY "YES" or "NO" followed by a one-sentenc
             }],
             tools: [],
             signal: AbortSignal.timeout(10_000),
+            // §18.6 D-TR4/D-TR6（2026-09-04 fix round1）：goal 独立评审调用经 chat()
+            // 唯一采集点——补轨迹元数据 + traces 开关透传（agent.config.traces.enabled
+            // ——关=不落盘必须全覆盖——与 agent.mjs/context.mjs 同模式）
+            logCtx: {
+              stage: "goal", kind: "goal",
+              role: agent._role ?? null, depth: ctx.depth,
+              session: agent._sessionStart ?? null, cwd: agent.cwd,
+              traces: agent.config?.traces?.enabled !== false,
+            },
           })
           const verdict = (judgeRes.content ?? "").trim()
           if (verdict.toUpperCase().startsWith("NO")) {