thincoder 0.12.59 → 0.12.61

package/src/agent/setup.mjs

@@ -10,14 +10,13 @@ import { search as memorySearch, docSearch } from "../memory.mjs"
 import { pushReal } from "../context.mjs"
 import { toOpenAISchema } from "../tools/index.mjs"
 import { loadSkills, formatSkillListing } from "../skills.mjs"
+import { assemblePrompt } from "../prompt-overlays.mjs"
 import {
   escapeXml, repairHistory, listWorkDir,
   collectGitContext, loadProjectInstructions, OUTLINE_INJECT_PREFIX,
   DEFAULT_MAX_TURNS, ensureAutoReminder,
 } from "./helpers.mjs"
-import { readFileSync, existsSync } from "node:fs"
-import { resolve, dirname } from "node:path"
-import { fileURLToPath } from "node:url"
+import { pushEnvStateReminder, pushPeerReminder } from "./setup-reminders.mjs"
 
 const DEFAULT_COMPACT_THRESHOLD = 100_000
 const DOC_SEARCH_LIMIT = 5
@@ -35,45 +34,12 @@ 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 */
-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 = ""
-  let templateMissing = false
-  try { engTemplate = readFileSync(engTemplatePath, "utf8") } catch {
-    templateMissing = true
-    if (role === "eng-coder") console.warn(`[setup] engineering-sub.md missing — eng-coder will run with degraded engineering constraints. Path: ${engTemplatePath}`)
-    else console.warn(`[setup] engineering.md missing — engineering mode will use template-only constraints. Path: ${engTemplatePath}`)
-  }
-  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. 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
-    ? `${engTemplate}\n\n---\n\n## Project METHODOLOGY.md\n\n${methodology}`
-    : `[ENGINEERING MODE]\n\nFollow this methodology strictly:\n\n${methodology}`
-  return { prompt, templateMissing, methodologyMissing: false }
-}
-
 /**
  * Prepare an agent run: inject context, build system prompt, inject tools.
  * Returns all state needed by the main loop, and writes initialization messages into agent.history.
  */
 export async function prepareRun(agent, input, callbacks, {
-  depth = 0, signal, overrideTurns, resume, systemPrompt: corePrompt, disciplineRules, mainOverlay,
+  depth = 0, signal, overrideTurns, resume,
 } = {}) {
   const maxTurns = overrideTurns ?? agent.config?.agent?.maxTurns ?? DEFAULT_MAX_TURNS
   const threshold = agent.config?.agent?.compactThreshold ?? DEFAULT_COMPACT_THRESHOLD
@@ -83,21 +49,21 @@ export async function prepareRun(agent, input, callbacks, {
   agent.history = repairHistory(agent.history)
 
   if (!resume) {
-      // Git context: branch, recent commits, uncommitted changes
-      if (depth === 0) {
-        const gitCtx = collectGitContext(agent.cwd)
-        if (gitCtx) {
-          agent.history.push({
-            role: "user",
-            content: `[System reminder: git context:\n${escapeXml(gitCtx)}]`,
-            transient: true,
-          })
-        }
+    // Git context: branch, recent commits, uncommitted changes
+    // GIT-ASYNC L21：collectGitContext → async（3×execFile 并行 + 失败冷却）——await
+    if (depth === 0) {
+      const gitCtx = await collectGitContext(agent.cwd)
+      if (gitCtx) {
+        agent.history.push({
+          role: "user",
+          content: `[System reminder: git context:\n${escapeXml(gitCtx)}]`,
+          transient: true,
+        })
       }
+    }
     if (depth === 0) {
       const tree = listWorkDir(agent.cwd)
       const platform = { win32: 'Windows', darwin: 'macOS', linux: 'Linux' }[process.platform] ?? process.platform
-      const wasRestored = agent._sessionStart != null
       agent._sessionStart ??= new Date().toISOString()
       // Inject OS/cwd + cwd-tree only ONCE per process (restored sessionStart keeps the
       // content byte-identical across restarts — 2026-08-16 cache audit). Without the guard
@@ -111,8 +77,14 @@ export async function prepareRun(agent, input, callbacks, {
         }
   
       }
-      if (wasRestored && !agent._restartReminderInjected) {
-        agent._restartReminderInjected = true
+      // SESSION.md §11.2（2026-09-08——N6 评审 🔴 修复：注入句解耦——双信号独立消费）：
+      // process restarted 句 = 进程级信号 _processRestartPending——仅 TUI 启动 resume 路径
+      // （bin/thincoder.mjs resumeSlot→applySession）设一次；/session 切换与 ACP 加载不设。
+      // 发句即清——进程内只发一次。resumed:yes 走 _envResumed（applySession 载入历史非空
+      // 时武装——每次恢复一次——pushEnvStateReminder 读即清）——互不绑门：切槽恢复只发
+      // resumed:yes、不误报进程重启（F3 伪触发消除——不再用 _sessionStart != null 推断）。
+      if (agent._processRestartPending) {
+        agent._processRestartPending = false
         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))) {
@@ -167,6 +139,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
@@ -187,9 +169,8 @@ 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, readHistoryTool } = await import("../agent-tools.mjs")
-  const { consultStartTool, consultCheckTool, consultStopTool } = await import("../agent-tools/consult.mjs")
-  const { CONSULT_BASE } = await import("../agent.mjs")
+  const { planTool, subagentTool, taskTool, skillTool, goalTool, verifyTool, recentChangesTool, timerTool, advisorTool, engTool, readHistoryTool, batchSegmentTool } = await import("../agent-tools.mjs")
+  const { consultStartTool, consultStopTool } = await import("../agent-tools/consult.mjs")
   // 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
@@ -200,12 +181,12 @@ export async function prepareRun(agent, input, callbacks, {
     if (!list) return tool
     return { ...tool, description: tool.description + `\nCurrently configured consultants (this tool's pool): ${list}` }
   }
-  // Role enum is mutually exclusive: normal mode has "coder", engineering mode has "eng-coder"
+  // Role enum is mutually exclusive: normal mode has "coder", engineering mode has "eng-coder"/"eng-designer"
   const subagentRoles = (depth === 0 && agent.config?.agent?.engineering)
     ? {
-        enum: ["explore", "plan", "eng-coder"],
+        enum: ["explore", "plan", "eng-designer", "eng-coder"],
         description: "The sub-agent role — see the tool description for the role capability matrix. Exact spelling required.",
-        suffix: " In engineering mode, use role='eng-coder' for implementation (coder is disabled).",
+        suffix: " In engineering mode, use role='eng-coder' for implementation (coder is disabled) and role='eng-designer' for writing the requirements/design documents.",
       }
     : {
         enum: ["explore", "plan", "coder"],
@@ -234,39 +215,49 @@ export async function prepareRun(agent, input, callbacks, {
     },
   } : subagentTool
 
-  // §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"
+  // §18 D-E3 + ENGINEERING-MODE.md §2.15 D（第 2 批——参数化复用，不并列第二个 IIFE）：
+  // 工程子代理（depth>0；eng-coder = 偏差审计 / eng-designer = 自己勘察）get a restricted
+  // spawn 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）。描述文案按父角色分流（审计 vs 勘察）。
+  const engChildRole = depth > 0 && (agent._role === "eng-coder" || agent._role === "eng-designer") ? agent._role : null
+  const engChildSubagent = engChildRole
     ? (() => {
         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
+        // §19 review hygiene: the child channel is spawn-only sync explore — drop
+        // async, the check/status params (id/n), the eng-coder token params
+        // (designToken/designId are meaningless for a read-only spawn; the parent
+        // spawn already carried the token) and batchDoc (an audit child derives no
+        // batch parameter — its task book rides the mechanical summary of the
+        // parent's _engTaskInput instead). 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.async // sync only — the parent blocks on the child's report
         delete props.id
         delete props.n
         delete props.designToken
         delete props.designId
+        delete props.batchDoc
+        const designer = engChildRole === "eng-designer"
         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).",
+          description: designer
+            ? "explore only — the eng-designer's internal spawn channel is reserved for read-only surveys of the current state (ENGINEERING-MODE.md §2.15 D; ≤6 spawns per batch)."
+            : "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).",
+          description: `spawn only — the ${engChildRole}'s internal spawn channel is read-only (escalate/status/cancel/panel/consume-design/observe/send are refused: escalate spawns a coder+WRITE child, and the pool/panel actions have no async pool or panel mirror 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).",
+          description: designer
+            ? "Spawn a read-only `explore` sub-agent to SURVEY the current state for the design (ENGINEERING-MODE.md §2.15 D): it reads code / docs / existing designs and reports evidence with file:line. BLOCKING ONLY (no async) and action:'spawn' ONLY — the survey channel is read-only; escalate/status/cancel/panel/consume-design/observe/send are not available (AGENT-LOOP.md §19). Survey budget: ≤6 explore spawns per batch — the main agent's survey result is reference only; do your own."
+            : "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/status/cancel/panel/consume-design/observe/send 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 },
         }
       })()
@@ -275,9 +266,11 @@ export async function prepareRun(agent, input, callbacks, {
   // 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 consultTools = consultModels.length
-    ? [withPool(consultStartTool), consultCheckTool, consultStopTool]
+    ? [withPool(consultStartTool), consultStopTool]
     : []
   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"
@@ -288,70 +281,57 @@ export async function prepareRun(agent, input, callbacks, {
     // escalate hit "unknown tool" and fell back to bash node --check / npm test to
     // self-verify (2026-08-16 deepseek escalate diagnosis; plugin parity).
     // eng-coder: advisor + verify + the §18 audit-only subagent channel (D-E3).
-    : agent._role === "eng-coder" ? [advisorTool, verifyTool, ...(engAuditSubagent ? [engAuditSubagent] : [])]
+    // eng-designer (§2.15 D): the survey-only subagent channel alone — no advisor
+    // (it does not fire reviews) and no verify (its deliverable is documents, not code).
+    // §2.20.3（第 4 批）：两分支各追加 batch_segment——目标档 = spawn 时绑定的
+    // `agent._batchDoc`（§2.20.2）；主 agent 不挂载（§1/§4/§6 走普通文档写）。
+    : engChildRole === "eng-coder" ? [advisorTool, verifyTool, batchSegmentTool(agent._batchDoc ?? null), ...(engChildSubagent ? [engChildSubagent] : [])]
+    : engChildRole === "eng-designer" ? [batchSegmentTool(agent._batchDoc ?? null), ...(engChildSubagent ? [engChildSubagent] : [])]
     : 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]))
   agent._onTaskUpdate = callbacks.onTaskUpdate
 
-  // system prompt
-  const needsDiscipline = depth === 0 || agent._role === "coder" || agent._role === "eng-coder"
-  let base
-  if (agent._role === "consult") {
-    // consult children: a lean, purpose-built base prompt (consult-base.md) — NOT the full
-    // main-agent system.md (whose coding-agent persona, checklist/task/verify workflows and
-    // tool references conflict with a read-only diagnosis and cost tokens every turn).
-    base = CONSULT_BASE
-  } else if ((depth === 0 || agent._role === "eng-coder") && agent.config?.agent?.engineering) {
-    // Engineering mode: strict methodology, NO standard discipline injection.
-    // Falling back to standard discipline on METHODOLOGY.md absence would leak
-    // advisor enforcement into engineering mode — the two prompt sets stay separate.
-    const engResult = await buildEngineeringPrompt(agent.cwd, agent._role)
-    if (engResult.prompt) {
-      base = `${corePrompt}\n\n${engResult.prompt}`
-    } else {
-      // Template unreadable — last resort: core prompt only, no methodology.
-      base = corePrompt
-    }
-    // Warn when templates or METHODOLOGY.md are missing (degraded engineering constraints).
-    if (depth === 0) {
-      const warnings = []
-      if (engResult.templateMissing) {
-        warnings.push(`Engineering template (${agent._role === "eng-coder" ? "engineering-sub.md" : "engineering.md"}) not found — using degraded constraints.`)
-      }
-      if (engResult.methodologyMissing) {
-        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({
-          role: "user",
-          content: `[System reminder: ENGINEERING MODE is active but ${warnings.join(" ")}]`,
-        })
-      }
-    }
-  } else {
-    base = needsDiscipline ? `${corePrompt}\n\n${disciplineRules}` : corePrompt
+  // ── system prompt ── PROMPT-SYSTEM 施工② G2/G3（2026-09-10）：四槽位装配函数
+  // assemblePrompt({scenario}) 表驱动（D1 场景表 = 蓝图 §3.2 装配矩阵）——取代旧
+  // consult/工程/普通三分支 + overlay 前缀。固定序 人格→common→纪律（§3.1）；[4] 层
+  // （AGENTS + skills）由下方既有尾部逻辑承担。降级链（蓝图 §3.4）：人格/纪律/common
+  // 槽文件缺失 → 该槽空缺跳过 + 醒目警告（不 fallback 其他槽——层间隔离）；AGENTS.md
+  // 缺失 → loadProjectInstructions 静默跳过（无警告——既有语义）。
+  // consult = 特殊模块（§3.3）——CONSULT_BASE 自含基底直接返回，不入主链、无四槽。
+  // eng-coder 场景即工程纪律（G6——subagent-spawn 的 childConfig engineering=true
+  // 强制语义由此表行承载：scenario=eng-coder → discipline-engineering 槽）。
+  const { prompt: base, warnings: slotWarnings } = assemblePrompt(
+    agent._role === "consult"
+      ? "consult"
+      : (depth === 0 || engChildRole) && agent.config?.agent?.engineering
+        ? (engChildRole ?? "engineering")
+        : (depth === 0 ? "normal" : agent._role ?? "normal"),
+  )
+  // D2 警告通道 = 既有 setup 警告通道（history 注入）——不新增机制。深度 0 才注入
+  // （子代理警告不打扰主会话历史——旧工程警告块同款深度门）。
+  // ── Q1 审计收敛（蓝图 §3.4 第 4 款）：特殊模块基底缺失 → 该模块不可用报错（不自降级
+  // ——空基底绝不可静默上岗）。consult 场景在外部消费点收口：入历史后抛错（Agent 循环
+  // → 历史已含错误句可见——不静默、不降级）。四槽场景维持跳过+警告降级链（AC-2 三款）。
+  if (agent._role === "consult" && !base) {
+    const msg = "[Consult module unavailable: prompts/consult-base.md missing — the consultation module refuses to degrade (蓝图 §3.4 特殊模块不自降级). Check the installation's prompts directory.]"
+    agent.history.push({ role: "user", content: msg })
+    throw new Error(`consult-base.md missing — consultation module unavailable (no degraded fallback per PROMPT-SYSTEM §3.4)`)
+  }
+  if (depth === 0 && slotWarnings.length > 0) {
+    agent.history.push({
+      role: "user",
+      content: `[System reminder: prompt slots degraded — ${slotWarnings.join(" ")}]`,
+    })
   }
-  let systemPrompt = agent.overlay
-    ? `${agent.overlay}\n\n${base}`
-    : depth === 0 && !agent.config?.agent?.engineering
-      ? `${base}\n\n${mainOverlay}`
-      : base
+  // G3（施工②审计收敛）：overlay（人格）前缀分支退役——CLI/VSC 同构（人格槽由场景表
+  // 承载，spawn 侧 overlay 恒空——createAgent 的 overlay 参数留空兼容位）。
+  // let——下方按 projectRules / skills listing 尾部追加（L326/L331 +=）再赋值；
+  // const 声明会 TypeError: Assignment to constant variable（每次 run 必炸）。
+  let systemPrompt = base
 
   // Time injection deliberately does NOT live here: system prompts must be byte-identical
   // across runs (provider prefix caches). The time rides a transient user reminder per turn

package/src/agent/spawn-child.mjs

@@ -16,6 +16,10 @@
  */
 import { specForModel } from "../config.mjs"
 import { ContinueError } from "../agent.mjs"
+import { relayPrefixOf } from "./relay-prefix.mjs"
+// 第 27 批 §12.3①：relay 前缀文法单一权威模块（`src/agent/relay-prefix.mjs`）——
+// 生成侧枢纽再导出（TUI/ACP 消费方可经此导入；消费方按 §12.3① 直连模块亦可）。
+export { RELAY_PREFIX_RE, parseRelayPath, relayPrefixOf } from "./relay-prefix.mjs"
 
 /** 事件 token 哨兵串（D1）——LLM 正常内容混淆概率极低；字段分隔用 RS (\x1e)。 */
 export const EVENT_SENTINEL = "⟦ev⟧"
@@ -26,23 +30,36 @@ const RS = "\x1e"
  *  单源化（2026-08-30 评审）：文案演进只改这里，消除文案与检测正则的漂移面。 */
 export const TURN_CAP_MARK = "stopped: turn cap reached"
 
+/** SYNC-CANCEL（L52）：sync spawn ⏹ 定向中止折叠报告的公共锚点——sync 折叠文案必含
+ *  此子串（buildSyncStoppedReport）；消费端（TUI tool-events onToolResult）用
+ *  includes() 检测"用户定向中止——工作可能不完整"语义（块冻结标 stopped 而非 done——
+ *  R6）。与 TURN_CAP_MARK 同族单源纪律。 */
+export const STOPPED_MARK = "stopped by user"
+
 /**
- * §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 上下文（不加限制）；返回审计尝试序号 = 通过。
+ * §18 D-E3 工程子代理内部 spawn 机械门（AGENT-LOOP.md §18 D-E2 round5 #2 后备 +
+ * ENGINEERING-MODE.md §2.15 D）：eng-coder（偏差审计）与 **eng-designer（自己勘察）**
+ * 同为受限通道——depth>0 且父角色 ∈ 集合时，内部 spawn 只允许 role='explore'、
+ * async 强制同步。
+ * **审计预算（6）只计 eng-coder**（designer 勘察非审计——designer 父路径校验通过后
+ * 返回 null：不计数、且调用方以 `engAuditAttempt !== null` 为审计任务书注入开关——
+ * 非 null 会把审计范围误注进勘察任务书）。
+ * 返回 null = 非工程子代理上下文（不加限制）或 designer 勘察路径（无须计数）；
+ * 返回审计尝试序号 = 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
+  const parentRole = parent?._role
+  if ((depth ?? 0) <= 0 || (parentRole !== "eng-coder" && parentRole !== "eng-designer")) 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)")
+    throw new Error(`${parentRole} subagents may only spawn role='explore' — internal spawns exist solely for read-only work (the eng-coder divergence audit / the designer's own survey) (AGENT-LOOP.md §18 D-E3, ENGINEERING-MODE.md §2.15 D)`)
   }
   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)")
+    throw new Error(`${parentRole} internal spawns are sync-only — the child's report must return before the next protocol step; async spawn is only available at the top level (AGENT-LOOP.md §18 D-E3)`)
   }
+  // designer 勘察路径：校验通过即返回 null（非审计——不计数、不触发审计任务书注入）
+  if (parentRole === "eng-designer") return null
   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)")
@@ -58,7 +75,7 @@ export function gateEngCoderSpawn(parent, depth, role, async) {
  */
 export function makeRelay(parent, label, emit, model) {
   parent._subAgentCounter = (parent._subAgentCounter ?? 0) + 1
-  const relayPrefix = `${label}#${parent._subAgentCounter}/`
+  const relayPrefix = relayPrefixOf(label, parent._subAgentCounter)
   emit?.(relayPrefix + "[model]" + (model ?? ""))
   return relayPrefix
 }
@@ -106,25 +123,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 文本）。
@@ -173,6 +210,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 })