thincoder 0.12.59 → 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"
@@ -113,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))) {
@@ -167,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
@@ -188,7 +202,7 @@ 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 { consultStartTool, consultStopTool } = await import("../agent-tools/consult.mjs")
   const { CONSULT_BASE } = await import("../agent.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
@@ -275,9 +289,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"

package/src/agent/spawn-child.mjs

@@ -106,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 文本）。
@@ -173,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 })