thincoder 0.12.58 → 0.12.60

package/src/agent/run-stages.mjs

@@ -0,0 +1,227 @@
+/**
+ * run-stages.mjs — runAgent 主循环的阶段函数族（CLI，2026-09-05 实践轮：agent.mjs
+ * runAgent 383 ≥300 按骨干—细节两层提取——VS Code 端同构文件（双端 parity——拆分
+ * 两端同步））。本文件承载：回合压缩检查（runCompactionCheck）、回合注入组
+ * （injectTurnReminders——plan cadence + eng 状态）、回合收尾（finalizeAgentTurn——
+ * consult 清理/async 池分流/guard 继承）与其收集器（collectSettledAsync——自
+ * agent.mjs 迁入，agent.mjs 内无其他引用）。verbatim 迁移 + 签名化，语义零变。
+ */
+
+import { compressIfNeeded, compressFallback, COMPRESS_FAILURE_LIMIT } from "../context.mjs"
+import { ensureAutoReminder, injectEngineeringReminder, ContinueError } from "./helpers.mjs"
+import { cleanupConsultSessions } from "../agent-tools/consult.mjs"
+import { logEvent } from "../log.mjs"
+// ASYNC-RESULT-CONTAINER.md D1：池 accessor（absorb 双池——advisor 独立池无队列）
+import { getAsyncPool } from "../agent-tools/async-settle.mjs"
+// R10 L3 (MULTI-INSTANCE-COLLAB §2a.5 D-L3a)：回合末域登记 flush（写工具钩子累积 →
+// 整写一次本实例 peers 文件——无写入跳过；失败容忍不抛）
+import { flushPeerDomains } from "../peer-domains.mjs"
+
+/**
+ * 响应后置提醒注入（2026-09-05 实践轮——自 runAgent 响应处理链提取，verbatim）：
+ * 流规则 warning（warn 动作——流已完成——去重注入，模型下轮可见）+ 异常 finish
+ * reason 警告（响应可能不完整/截断——reasonMap 人类化描述注入）。
+ */
+export function injectResponseReminders(agent, response) {
+  // Stream rule warnings (action: "warn"): stream completed; inject de-duplicated
+  // warnings so the model sees them before its next response.
+  if (response._warnings?.length) {
+    const deDuplicated = [...new Map(response._warnings.map(w => [w.name || w.pattern, w])).values()]
+    agent.history.push({
+      role: "user",
+      content: `[System reminder — stream rule warnings from your last response:\n${deDuplicated.map(w => `- ${w.name || w.pattern}: ${w.message}`).join("\n")}]`,
+    })
+  }
+
+  // Warn on abnormal finish reasons — the response may be incomplete/truncated.
+  if (response.finishReason && response.finishReason !== "stop" && response.finishReason !== "tool_calls") {
+    const reasonMap = {
+      length: "output token limit reached after exhausting continuations",
+      insufficient_system_resource: "provider inference resources exhausted — consider retrying or switching models",
+      content_filter: "response blocked by provider content filtering",
+    }
+    const detail = reasonMap[response.finishReason] || `unknown reason "${response.finishReason}"`
+    agent.history.push({
+      role: "user",
+      content: `[System reminder: the previous turn ended abnormally — ${detail}. The assistant response that follows may be incomplete.]`,
+    })
+  }
+}
+
+/**
+ * 回合压缩检查（2026-09-05 实践轮——自 runAgent 主循环提取）：仅安全点（history 以
+ * 完整交换结尾——user/tool 位）。成功：失败计数清零/计划提醒 cadence 复位/停滞检测
+ * 计数复位（recentCallSigs——runAgent 回合级局部——经 ctx 传对象引用）/压缩完成事件
+ * /AUTO 提醒重注入。失败：AbortError 透传；计数 + Q3 onCompressFail；
+ * COMPRESS_FAILURE_LIMIT 连续失败降级 compressFallback（确定性截断——不发 LLM）。
+ */
+export async function runCompactionCheck(agent, ctx) {
+  const { threshold, callbacks, compactionOverhead, signal, recentCallSigs } = ctx
+  try {
+    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
+      // Completion info (CONTEXT-COMPACTION §7 D-C2): { mode, tokensFreed, elapsedMs } —
+      // the TUI panel renders it; callers that ignore the arg keep prior onCompress semantics.
+      callbacks.onCompress?.(agent._lastCompressInfo ?? {})
+      ensureAutoReminder(agent)
+    }
+  } catch (compressError) {
+    // AbortError must not be swallowed: user cancellation must propagate
+    if (compressError?.name === "AbortError" || signal?.aborted) throw compressError
+    agent._compressFailures = (agent._compressFailures ?? 0) + 1
+    // Q3 (CONTEXT-COMPACTION §7 D-C1): a failed compression is surfaced to the panel;
+    // COMPRESS_FAILURE_LIMIT consecutive failures still degrade to compressFallback.
+    callbacks?.onCompressFail?.(compressError)
+    if (agent._compressFailures >= COMPRESS_FAILURE_LIMIT) {
+      agent._compressFailures = 0
+      if (compressFallback(agent)) callbacks.onCompress?.(agent._lastCompressInfo ?? {})
+    }
+  }
+}
+
+/**
+ * 回合注入组（2026-09-05 实践轮——自 runAgent 主循环提取）：plan-mode 提醒 cadence
+ * （稀疏 2 轮/满 5 轮/新用户消息重置——限制不淡化）+ 工程模式状态注入（depth-0 每新
+ * 用户消息一次——见 injectEngineeringReminder）。verbatim——语义零变。
+ */
+export async function injectTurnReminders(agent, ctx) {
+  const { depth } = ctx
+  // Plan-mode reminder cadence: re-inject constraint reminders while plan mode is active
+  // (sparse every 2 turns, full every 5 / on new user message) so the restriction never fades.
+  if (agent.planMode) {
+    const lastMsg = agent.history.at(-1)
+    const realUserMsg = lastMsg?.role === "user"
+      && typeof lastMsg.content === "string"
+      && !lastMsg.content.startsWith("[System reminder:")
+      && !lastMsg.content.startsWith("[User interrupt:")
+    const newUserSince = realUserMsg && agent.history.length > (agent._planReminderAtLen ?? 0)
+    const { planReminderForTurn } = await import("../agent-tools/plan.mjs")
+    const reminder = planReminderForTurn(agent, newUserSince)
+    if (reminder) {
+      agent._planReminderAtLen = agent.history.length + 1
+      agent.history.push({ role: "user", content: reminder, transient: true })
+    }
+  }
+
+  // Engineering-mode status injection on every new user message (design-before-code
+  // vs standard discipline) — see injectEngineeringReminder.
+  if (depth === 0) {
+    injectEngineeringReminder(agent)
+  }
+}
+
+/**
+ * 回合收尾（2026-09-05 实践轮——自 runAgent finally 提取，verbatim + 签名化）：
+ * consult 清理（无孤儿烧 token 的 consult children）→ async 池回合尾分流（Ctrl+C
+ * 清池不注入 / ContinueError 留池续跑 / 其余 collectSettledAsync）→ auto-turn guard
+ * 标记继承（对象字段清单——正常结束才继承；中止丢弃；ContinueError 由续跑快照）。
+ */
+export async function finalizeAgentTurn(agent, ctx) {
+  const { signal, autoTurn, suspDriven, thrownError } = ctx
+  // R10 L3（MULTI-INSTANCE-COLLAB §2a.5 D-L3a）：回合末登记 flush——本回合写足迹整写
+  // 一次（首行执行：收尾链后续任何异常都不吞登记）；无写入 → 跳过（hot 窗口自然衰减）。
+  flushPeerDomains(agent)
+  // R17（AGENT-LOOP.md §25 D-R17a）: consultation sessions are cross-turn
+  // background work now — NO unconditional turn-end cleanup (the old rule aborted
+  // leftover consult children at every turn end because check-loop consumption was
+  // turn-scoped). Sessions stay alive across normal turn ends (and ContinueError
+  // resumes); the Ctrl+C abort branch below is the only path that aborts them
+  // (cleanupConsultSessions — marked stopped → no digest), and the suspension
+  // driver aborts them on its own abort unwind.
+  // Async subagent turn-end handling (AGENT-LOOP.md §15 D-A3 + §17 D-S1). Lifecycle:
+  // - Ctrl+C (plain abort): children were aborted with the parent signal — clear
+  //   WITHOUT injecting stale errors (user explicitly stopped); consultation
+  //   sessions are cross-turn background work since R17 — the abort branch is the
+  //   ONLY normal-path place that aborts them (cleanupConsultSessions marks
+  //   stopped → their settles never reach the digest stream).
+  // - Ctrl+I (interrupt): keeps the pool AND the consult sessions: the turn
+  //   resumes with the interrupt message, children stay tracked (in a suspension
+  //   session children hold agent._sessionSignal and a digest's own Ctrl+I must
+  //   not orphan them).
+  // - ContinueError (turn cap): no wait, no injection — children keep running and
+  //   the RESUME run's turn-end collection takes over.
+  // - anything else: inject the SETTLED entries only; running/queued stay in the
+  //   pool for the suspension session (D-S1 — no allSettled turn-end wait).
+  if (signal?.aborted && !signal?.reason?.interrupt) {
+    const subPool = getAsyncPool(agent, "subagent")
+    const advPool = getAsyncPool(agent, "advisor")
+    if ((subPool?.size ?? 0) > 0 || (advPool?.size ?? 0) > 0) {
+      logEvent("ev:stopped", { poolN: (subPool?.size ?? 0) + (advPool?.size ?? 0), where: "turn-end-abort" })
+    }
+    subPool?.clear()
+    advPool?.clear()
+    agent._asyncQueue = []
+    // R17: the consult family dies with the user stop (marked stopped — no digest).
+    cleanupConsultSessions(agent)
+    // ASYNC-RESULT-CONTAINER.md D2：pending 单容器——中止丢弃 consult/escalate 族停靠
+    // （原 _pendingConsultResults/_pendingEscalateResults 同口径——VSC 同语义 filter）；
+    // subagent/advisor 停靠保留（挂起期 settle 的已完成结果不随中止丢）。
+    agent._pendingAsyncResults = (agent._pendingAsyncResults ?? []).filter((e) => e.role !== "consult" && e.role !== "escalate")
+  } else if (thrownError instanceof ContinueError) {
+    // keep _asyncSubagents/_asyncAdvisors/_consultSessions — the resumed run continues them
+  } else {
+    const injectedAdvisor = await collectSettledAsync(agent, { suspDriven })
+    // §24 D-24b: a normally-ended USER run with no review/child activity closes
+    // the OPEN code instances — the converged/abandoned thread must not burn the
+    // 5-round cap of a later task (the next code review starts a fresh round 1).
+    // Digest auto-turns are exempt (their disposition precedes the fix round).
+    // A run whose turn-end collection just INJECTED a settled review report
+    // (headless, suspDriven=false) must NOT close: the model has not digested
+    // the findings yet — the fix round that follows still continues the thread.
+    if (!autoTurn && !injectedAdvisor) {
+      const { closeOpenCodeAdvisorRuns } = await import("../agent-tools/advisor-async.mjs")
+      closeOpenCodeAdvisorRuns(agent)
+    }
+  }
+  agent._inAutoTurn = false
+  // §17 D-S6: auto-turn guard marks survive into the next USER run (restored at its
+  // !resume reset above). Normal ends only — abort discards; ContinueError lets the
+  // auto-resumed run snapshot at its own end.
+  if (autoTurn && !(signal?.aborted && !signal?.reason?.interrupt) && !(thrownError instanceof ContinueError)) {
+    agent._inheritedGuard = {
+      _mutatedThisRun: agent._mutatedThisRun, _verifiedThisRun: agent._verifiedThisRun,
+      _verifyPassed: agent._verifyPassed, _calledAdvisorThisRun: agent._calledAdvisorThisRun,
+      _touchedFiles: agent._touchedFiles, _verifyRetries: agent._verifyRetries,
+      _advisorRound: agent._advisorRound,
+    }
+  }
+}
+
+/**
+ * Turn-end async subagent collection (AGENT-LOOP.md §17 D-S1 + §17.5 supersede):
+ * two modes, selected by the caller's driver context (17.5.2/17.5.4 #2):
+ * - suspDriven=false (fallback — headless/direct runAgent callers without a
+ *   suspension driver): inject every entry that SETTLED during this run
+ *   (XML-escaped report/error — child reports may carry file/webpage content;
+ *   >64K offloaded with preview + path) and remove it from the pool. Running/
+ *   queued STAY — no allSettled wait. Results never lost without a session.
+ * - suspDriven=true (the interaction layer runs suspensionSession after this
+ *   run): NO direct inject — settled entries STAY pooled (settled not consumed)
+ *   for the session's first sweepSettledToPending → digest turn (§17.5 — done
+ *   条目留池等消化轮注入；status 在 sweep 前仍从池读——17.5.2 不变面（§19.8：check 已删——自动通道为唯一消费方）)。
+ * maybeRefillAsync runs in both modes (starts queued heads whose slot freed).
+ * Single ownership: entries settled inside a suspension session were moved to
+ * _pendingAsyncResults by the settle callback, so this only sees user-turn
+ * settles (no double inject — D-S3 points ①/②). The ⟦ev⟧done freeze is NOT
+ * emitted here — each settle callback emits it (§15 D-A3).
+ * 2026-09-05 实践轮：自 agent.mjs 迁入（agent.mjs 内仅 finalize 引用——随收尾同迁）。
+ */
+async function collectSettledAsync(agent, { suspDriven = false } = {}) {
+  const maps = [getAsyncPool(agent, "subagent"), getAsyncPool(agent, "advisor")].filter((m) => m instanceof Map && m.size > 0)
+  if (maps.length === 0) return false
+  const { maybeRefillAsync, injectAsyncResult } = await import("../agent-tools/subagent.mjs")
+  maybeRefillAsync(agent) // start queued heads now that slots may have freed — no waiting
+  if (suspDriven) return false // §17.5: settled stays pooled — the suspension session digests it
+  let injectedAdvisor = false
+  for (const map of maps) {
+    for (const e of [...map.values()]) {
+      if (!e.done) continue // still running — stays in the pool (D-S1)
+      await injectAsyncResult(agent, e)
+      if (e.role === "advisor") injectedAdvisor = true
+      map.delete(String(e.id))
+    }
+  }
+  return injectedAdvisor
+}

package/src/agent/setup-reminders.mjs

@@ -0,0 +1,62 @@
+/**
+ * agent/setup-reminders.mjs — per-turn transient reminders
+ * (SESSION.md §11.1 — 2026-09-06 需求池 R5/R8/R9/R11 合并设计; R10 L1 peer 注入同文件).
+ *
+ * One unified transient user reminder per turn covers the whole self-awareness
+ * family: env identity (R8 — §10 D-1 END 常量先例：静态常量，不做 cmdline 判别),
+ * engineering mode (R9), active model (R11), restart awareness (R5 resumed).
+ * Change awareness needs no dedicated injection — every turn carries the
+ * CURRENT state, so a mode/model flip shows up in the next turn's line.
+ * git is NOT a field here (§11.1: CLI 不重复注入 clean|dirty 摘要) — the rich
+ * git-context injection (branch/commits/uncommitted — helpers.mjs
+ * collectGitContext, wired in setup.mjs) carries it.
+ * Peer awareness (R10 L1) rides the same per-turn transient channel:
+ * pushPeerReminder injects the live co-cwd instance list when present.
+ */
+import { END } from "../session-slots.mjs"
+import { peerInstances } from "../peer-instances.mjs"
+
+/** env-state line builder — pure, unit-testable. */
+export function envStateLine({ mode, model, resumed }) {
+  return `[System reminder: env: ${END}, mode: ${mode}, model: ${model}, resumed: ${resumed ? "yes" : "no"}.]`
+}
+
+/**
+ * Push the per-turn env-state reminder (setup.mjs calls it for depth-0 runs —
+ * the line describes the MAIN agent's host/mode/model identity). resumed=yes
+ * exactly once: the first turn after a restored session (setup.mjs sets
+ * agent._envResumed alongside the `process restarted` reminder); consumed here
+ * so every later turn reads resumed=no (T-E5).
+ * Degrades safely: activeModel null → provider.model → "unknown" (T-E12);
+ * a missing config/history never throws (T-E13).
+ */
+export function pushEnvStateReminder(agent) {
+  const mode = agent.config?.agent?.engineering ? "eng" : "normal"
+  const model = agent.activeModel ?? agent.provider?.model ?? "unknown"
+  const resumed = agent._envResumed === true
+  agent._envResumed = false
+  agent.history.push({ role: "user", content: envStateLine({ mode, model, resumed }), transient: true })
+}
+
+/**
+ * R10 L1 peer reminder（MULTI-INSTANCE-COLLAB §2a.4 D-L1a——仿 pushEnvStateReminder
+ * 形态：depth-0、transient:true——注入纪律同 env-state）。有同伴（非 self > 0）才注入
+ * ——无同伴零开销（peerInstances 惰性 mtime 缓存保证：manifest 未变零 exec）。任何
+ * 感知失败静默跳过（注入绝不打断回合）。文案（设计逐字）："本目录另有 N 个活跃
+ * thincoder（{end} pid={pid}…）——文件操作注意避让"。
+ */
+export function pushPeerReminder(agent) {
+  let peers
+  try {
+    peers = peerInstances(agent.cwd).filter((p) => !p.self)
+  } catch {
+    return // 感知失败降级——不注入
+  }
+  if (peers.length === 0) return
+  const who = peers.map((p) => (p.end ? `${p.end} pid=${p.pid}` : `pid=${p.pid}`)).join("、")
+  agent.history.push({
+    role: "user",
+    content: `[System reminder: 本目录另有 ${peers.length} 个活跃 thincoder（${who}）——文件操作注意避让]`,
+    transient: true,
+  })
+}

package/src/agent/setup.mjs

@@ -15,6 +15,7 @@ import {
   collectGitContext, loadProjectInstructions, OUTLINE_INJECT_PREFIX,
   DEFAULT_MAX_TURNS, ensureAutoReminder,
 } from "./helpers.mjs"
+import { pushEnvStateReminder, pushPeerReminder } from "./setup-reminders.mjs"
 import { readFileSync, existsSync } from "node:fs"
 import { resolve, dirname } from "node:path"
 import { fileURLToPath } from "node:url"
@@ -36,7 +37,7 @@ function safeSliceUTF16(text, max) {
 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 = ""
@@ -49,8 +50,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
@@ -104,6 +114,9 @@ export async function prepareRun(agent, input, callbacks, {
       }
       if (wasRestored && !agent._restartReminderInjected) {
         agent._restartReminderInjected = true
+        // SESSION.md §11.1 R5: the per-turn env-state reminder carries resumed:yes
+        // on THIS first turn after the restore (consumed by pushEnvStateReminder).
+        agent._envResumed = true
         agent.history.push({ role: "user", content: `[System reminder: process restarted at ${new Date().toISOString()}.]`, transient: true })
       }
       if (agent.memory && !agent.history.some((m) => typeof m.content === "string" && m.content.startsWith(OUTLINE_INJECT_PREFIX))) {
@@ -158,6 +171,16 @@ export async function prepareRun(agent, input, callbacks, {
     }
     pushReal(agent, { role: "user", content: input })
   }
+  // SESSION.md §11.1: unified per-turn env-state transient reminder (env/mode/
+  // model/resumed — R5/R8/R9/R11 one-shot coverage; changes surface next turn).
+  // R10 L1 (MULTI-INSTANCE-COLLAB §2a.4 D-L1a): peer-instance reminder right after
+  // env-state, BEFORE the time reminder — the time reminder stays LAST (prefix-cache
+  // contract). Both depth-0 only (describe the MAIN agent / its workspace peers).
+  if (depth === 0) {
+    pushEnvStateReminder(agent)
+    pushPeerReminder(agent)
+  }
+
   // Time grounding for EVERY agent depth AND every resume, pushed LAST (after the user
   // input): transient on the HUMAN line — dropped on persist; on the MACHINE line — kept
   // (byte-identical resume for the provider prefix cache, 2026-08-16), fresh at every run start
@@ -178,13 +201,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 { consultStartTool, consultCheckTool, consultStopTool } = await import("../agent-tools/consult.mjs")
-  const { subagentCheckTool } = await import("../agent-tools/subagent-check.mjs")
-  const { escalateTool } = await import("../agent-tools/escalate.mjs")
+  const { planTool, subagentTool, taskTool, skillTool, goalTool, verifyTool, recentChangesTool, timerTool, advisorTool, engTool, readHistoryTool } = await import("../agent-tools.mjs")
+  const { consultStartTool, consultStopTool } = await import("../agent-tools/consult.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(", ")
@@ -211,28 +234,84 @@ 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 内拒绝）。
+  // §25 D-R17a: consult_check 已退役（digest 自动注入是唯一消费通道）——consult 家族
+  // 只剩 2 工具（consult_start/consult_stop——setup 注册点与描述面同步清零）。
   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), consultStopTool]
     : []
-  const depthOnly = depth === 0 ? [filteredSubagent, subagentCheckTool, 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]))
@@ -264,7 +343,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 上，多轮/并行子代理互不冲突。
@@ -81,25 +106,45 @@ export function stripEventTokensForCapture(text) {
  * - onToolOutput 带**已加前缀**的 name 走父 onToolOutput（name 形如
  *   "coder#1/bash"，消费端剥前缀路由进对应区块；chunk 对象/裸串原样透传）。
  * 父回调缺省时不包装（headless 嵌入）。
+ * §27 R23 D-R23c1：包装产物在 onToken 上留 `_relayPrefix` 标记——同步收尾段据此
+ * 判定"ctx.callbacks 已是嵌套 wrapper"（本 spawn 处于更深一层——eng-coder 内
+ * explore）→ emitNestedChildEvent 补发射内层完成事件（T-R23c.2b 断言源）。
  */
 export function wrapChildCallbacks(relayPrefix, parentCallbacks = {}) {
+  const mark = (fn) => { fn._relayPrefix = relayPrefix; return fn }
   const wrapped = {
     onToken: parentCallbacks.onToken
-      ? (t) => parentCallbacks.onToken(relayPrefix + stripEventToken(String(t)))
+      ? mark((t) => parentCallbacks.onToken(relayPrefix + stripEventToken(String(t))))
       : null,
     onReasoning: parentCallbacks.onReasoning
-      ? (t) => parentCallbacks.onReasoning(relayPrefix + t)
+      ? mark((t) => parentCallbacks.onReasoning(relayPrefix + t))
       : null,
     onToolCall: parentCallbacks.onToolCall
-      ? (name, args) => parentCallbacks.onToolCall(relayPrefix + name, args)
+      ? mark((name, args) => parentCallbacks.onToolCall(relayPrefix + name, args))
       : null,
     onToolOutput: parentCallbacks.onToolOutput
-      ? (name, chunk) => parentCallbacks.onToolOutput(relayPrefix + name, chunk)
+      ? mark((name, chunk) => parentCallbacks.onToolOutput(relayPrefix + name, chunk))
       : null,
   }
   return wrapped
 }
 
+/**
+ * §27 R23 D-R23c1（生成侧补发射——评审 #1 🅰）：sync spawn 同步收尾时若父回调已是
+ * 嵌套 wrapper（onToken 带 `_relayPrefix` 标记——即本 spawn 的父本身是子代理，如
+ * eng-coder 内 explore 审计）→ 发内层 done/stopped 事件（带完整嵌套前缀——wrapper
+ * 链自动补外层前缀）→ 主 TUI routeSubToken 路由到子块定格。非嵌套（depth-0 直连主
+ * 回调——无标记）不发——完成冻结仍走既有 onToolResult/subKey 路径（零行为变化）。
+ * @returns {boolean} true = 已发射（嵌套上下文）
+ */
+export function emitNestedChildEvent(ctx, relayPrefix, kind) {
+  const onToken = ctx?.callbacks?.onToken
+  if (typeof onToken?._relayPrefix !== "string" || !onToken._relayPrefix) return false
+  if (kind !== "done" && kind !== "stopped") return false
+  onToken(`${relayPrefix}⟦ev⟧${kind}\x1e0\x1e0\x1e${kind}\x1e`)
+  return true
+}
+
 /**
  * 子 agent provider API key 检查：trim 后非空才保留；缺失返回 null（调用方
  * 按各自业务语汇报错——subagent 抛出 / escalate·consult 返回 Error 文本）。
@@ -148,6 +193,11 @@ export async function runWithContinue(runner, child, input, callbacks, runOpts,
   const capture = callbacks?.onToken
     ? (t) => { output += stripEventTokensForCapture(String(t)); child._capturedOutput = output; callbacks.onToken(t) }
     : (t) => { output += stripEventTokensForCapture(String(t)); child._capturedOutput = output }
+  // §27 R23 D-R23c1（评审 🔴 修复——2026-09-07）：capture 是子代理 runAgent/dispatch ctx
+  // 实际收到的 onToken——嵌套 wrapper 标记（wrapChildCallbacks `_relayPrefix`）必须随
+  // capture 透传，否则 eng-coder 内 explore 同步收尾的 emitNestedChildEvent 判定恒 false
+  // （生成侧补发射结构性不可达——T-R23c.2b 真实路径回归）。
+  if (callbacks?.onToken?._relayPrefix) capture._relayPrefix = callbacks.onToken._relayPrefix
   for (let resume = false; ; resume = true) {
     try {
       return await runner(child, input, { ...callbacks, onToken: capture }, { ...runOpts, resume })