thincoder 0.12.59 → 0.12.61

package/src/agent-tools/design-token.mjs

@@ -0,0 +1,117 @@
+/**
+ * design-token.mjs — design-token utilities（2026-09-08 自 advisor-async.mjs 提取——
+ * advisor-async 随 DESIGN-TOKEN-SETTLEMENT D1 落盘块再越 500 行硬限；本工具组 verbatim
+ * 迁入，零语义变）。
+ *
+ * 沿革：初由 agent-tools/advisor.mjs 迁至 advisor-async.mjs（sync wrapper 与 async
+ * settle 共享一套实现——无 wrapper↔runner 环），再由 advisor-async.mjs 迁入本文件。
+ * 既有 import 面不变：advisor-async.mjs re-export 全部 7 个导出（advisor.mjs 与测试
+ * 的 import 路径原样保留——advisor.mjs 再转发 validateDesignToken 给 spawn 门禁）。
+ */
+
+import { randomUUID } from "node:crypto"
+import { tokenExpiryMs } from "../token-ttl.mjs"
+
+/**
+ * F2c/F2e (§29.1 2026-09-07): the engine-generated Approved suffix — ONE builder
+ * shared by the sync settle and the async settle (and the prior stores, which
+ * strip it with stripApprovedSuffix — exact-suffix truncation, never a regex
+ * guess, zero collateral). The slot count is a point-in-time snapshot taken at
+ * settle time — the situation at spawn time may differ (F2d backs that up).
+ */
+export function buildApprovedSuffix(designToken, designId, slotCount) {
+  return `Approved. 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; ${slotCount} approved design slot(s) held as of this approval, and the count may have changed since — with several designs the spawn gate refuses a missing designId and lists the held ids)`
+}
+
+/** F2e (§29.1): strip the engine-generated Approved suffix from a report before
+ *  it becomes a prior — the suffix is deterministic (buildApprovedSuffix), so the
+ *  truncation is exact; a text not ending in it passes through untouched. */
+export function stripApprovedSuffix(text, suffix) {
+  if (typeof text !== "string" || !suffix) return text
+  return text.endsWith(suffix) ? text.slice(0, text.length - suffix.length).trim() : text
+}
+
+const TOKEN_TTL_DEFAULT_MS = 7 * 24 * 3600 * 1000 // 7-day ceiling (v2 2026-08-25)
+
+/** Effective token TTL: config override with runtime validation (timeoutMs precedent). */
+export function effectiveTokenTtlMs(agent) {
+  const cfg = agent?.config?.agent?.engTokenTtlMs
+  return (Number.isFinite(cfg) && cfg > 0) ? cfg : TOKEN_TTL_DEFAULT_MS
+}
+
+/** Mint an unsigned design token with expiration (2026-09-06: HMAC layer removed —
+ *  the token is a FLOW credential: uuid:expiresAt, exact slot match + TTL only). */
+export function generateDesignToken(agent) {
+  const uuid = randomUUID()
+  const expiresAt = Math.floor(Date.now() + effectiveTokenTtlMs(agent))
+  return `${uuid}:${expiresAt}`
+}
+
+/** Validate a design token: format + expiration — ALL fail-closed (v2 2026-08-25).
+ *  R16: format/expiry semantics live in token-ttl.mjs (tokenExpiryMs — single source
+ *  shared with restore filtering / enter cleanup / spawn-gate slot deletion — D-R16b). */
+export function validateDesignToken(token) {
+  const expiry = tokenExpiryMs(token)
+  return expiry !== null && expiry >= Date.now()
+}
+
+/** Build a [DESIGN-TOKEN:...] regex matching the FULL token (uuid:expiresAt). */
+export function makeDesignTokenRegex(token, flags = "") {
+  const escaped = token.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+  return new RegExp(
+    `(?:^|\\s|\`|\\*)\\[DESIGN-TOKEN:\\s*${escaped}\\s*\\](?:\\s|$|\`|\\*)`,
+    flags + "ms"
+  )
+}
+
+/**
+ * Shared design-review settlement (sync wrapper + async settle): the token echo
+ * IS the verdict — the advisor echoes it only on approval. On echo: slot the
+ * token under designId (+ eng-coder gate flag; single-value mirror retired per
+ * DESIGN-TOKEN-SETTLEMENT D3) and return
+ * the clean output with the Approved suffix; the review instance CLOSES (a
+ * later review of the same doc-set starts a fresh full review). On non-echo:
+ * strip every dead token occurrence and return the findings text — slots stay
+ * untouched (方案 ②: a failed re-review revokes nothing).
+ * @param {Object} [opts] — 第 11 批（A/F11）：`opts.incomplete` = 宿主尾族判定 kind
+ *   （单谓词 `advisorIncompleteMarker`——结算方透传）。非空 ⇒ **一律不签发**（无论评审文本
+ *   是否回显 token）：剥除全部 token 回显 + 追加未签发提示（原因 + 恢复指引），不写槽、
+ *   不关实例（可重评）。
+ * @returns {{passed: boolean, output: string}}
+ */
+export function settleDesignReview(agent, run, designToken, rawResult, opts = {}) {
+  if (!designToken || typeof rawResult !== "string") {
+    return { passed: false, output: rawResult ?? "" }
+  }
+  // A（F11/§14.3 消费点 1）：未完成即不签发——判据与 code 完成守卫同源（单谓词）。
+  const incomplete = opts?.incomplete ?? null
+  if (incomplete) {
+    const stripped = rawResult.replace(makeDesignTokenRegex(designToken, "g"), "").trim()
+    return {
+      passed: false,
+      output: `${stripped}\n\n评审未完成——token 未签发 (review incomplete — no design token issued; reason: ${incomplete})\n以更小范围重跑设计评审（逐档 / 逐节拆分，或拆到两次评审），或调大 agent.advisor.timeoutMs 后重试；补充检查未完成的部分不得按已核处理。`.trim(),
+    }
+  }
+  const tokenPattern = makeDesignTokenRegex(designToken)
+  if (!tokenPattern.test(rawResult)) {
+    const stripped = rawResult.replace(makeDesignTokenRegex(designToken, "g"), "").trim()
+    return { passed: false, output: stripped || "Advisor: design review did not pass." }
+  }
+  // Echoed the token → review passed. Issue it to the parent for eng-coder.
+  agent._engDesignTokens ??= new Map()
+  agent._engDesignTokens.set(run.designId, designToken)
+  // DESIGN-TOKEN-SETTLEMENT D3（2026-09-08）：单值镜像 `_engDesignToken` 退役——
+  // 只写多槽 Map（AC3 零镜像写）；settle 落盘由调用方（settleAdvisorRun）当场做。
+  // Unlock the dispatch design gate for eng-coder SELF-review (defense-in-depth —
+  // see the sync wrapper's note: unreachable today, kept for parity).
+  if (agent._role === "eng-coder") agent._engDesignReviewed = true
+  run.open = false // approval closes this doc-set instance — next review is fresh
+  const clean = rawResult.replace(makeDesignTokenRegex(designToken, "g"), "").trim()
+  // F2c (§29.1): id echo + omission guidance + point-in-time slot snapshot — the
+  // same suffix the F2e prior stores strip with (stored for the exact truncation).
+  run.approvedSuffix = buildApprovedSuffix(designToken, run.designId, agent._engDesignTokens.size)
+  return {
+    passed: true,
+    output: `${clean}\n\n${run.approvedSuffix}`,
+  }
+}

package/src/agent-tools/digest-budget.mjs

@@ -0,0 +1,76 @@
+/**
+ * digest-budget.mjs — digest 注入批量预算单源（群 B 批 B5——AGENT-LOOP.md §22 语义源）。
+ * 原预算块居 subagent-async.mjs（只覆盖经 injectAsyncResult 的三族：subagent / advisor /
+ * escalate），consult 族注入器（injectConsultResult）绕过 ⇒ 多族条目同轮合并注入时可累计
+ * 超限（BATCH-3-STRUCTURE F-2 原始事故面 1.3MB 请求体）。本档把常量 / 判超 / 记账 / 落盘
+ * 四处合一（D2 单源）+ 四族全接线（D-DG2）。
+ *
+ * 契约（D-DG1 三导出——CLI 面）：
+ * - `DIGEST_INJECT_BUDGET`（64×1024——与 offload 单条预览同量级）；
+ * - `digestBudgetOver(agent, size)`——判超 + 记账：`used > 0 && used + size > BUDGET`
+ *   首条豁免保留（单条大报告 >64K 走 offload 预览照旧——预算只约束轮累计）；轮界定
+ *   `agent.history.length !== r.len + 1` 语义逐字迁入（相邻注入间 history 无其他落史 = 同轮；
+ *   每次注入 pushReal 恰 +1——他人落史 = 新请求窗口 → 预算复位）；键 = agent（会话级复用
+ *   ——Map 常驻一两项）。
+ * - `persistOverflowReport(raw, { tag })`——超限条目全量落盘（`configDir/tool-results` +
+ *   `cleanupOldToolResults` 轮转；落盘名 `<ts>-<tag>.log`（tag = 溯源标签：写入族 + 条目 id
+ *   ——非法字符归一 `_`））。返回清单行文本（inline = 仅此——不 inline 全文）；落盘失败 →
+ *   null（调用方回退常规 inline 路径——offload 同款「失败不吞报告」语义）。
+ *
+ * 计数口径（D-DG3）：计入预算的 raw = 报告 / 错误正文（不含 `[System reminder: …]` 标签行
+ * ——与既有口径一致）；错误条目同计同落盘。
+ *
+ * 兼容面（D-DG4）：subagent-async.mjs 保留 `DIGEST_INJECT_BUDGET` +
+ * `_setDigestOffloadDirForTest` re-export（测试导入面零改）；单条 offload 预览路径零改。
+ *
+ * 模块图：import node:fs/promises + node:path + ../agent/helpers.mjs（cleanupOldToolResults）+
+ * ../config.mjs（configDir）——叶子级；subagent-async / consult 单向 import 本档（无环）。
+ */
+import { mkdir, writeFile } from "node:fs/promises"
+import { join } from "node:path"
+import { cleanupOldToolResults } from "../agent/helpers.mjs"
+import { configDir } from "../config.mjs"
+
+export const DIGEST_INJECT_BUDGET = 64 * 1024 // 64K——与 offload 单条预览同量级
+
+// 轮记账：agent → { len, used }（逐字自 subagent-async.mjs 迁入——语义零变）。
+const digestRounds = new Map()
+function digestRoundFor(agent) {
+  const h = agent.history
+  const r = digestRounds.get(agent)
+  if (!r || h.length !== r.len + 1) {
+    const fresh = { len: h.length, used: 0 }
+    digestRounds.set(agent, fresh)
+    return fresh
+  }
+  r.len = h.length
+  return r
+}
+
+/** 判超 + 记账（size = 原始正文字符数——标签行不计；先判后记：首条恒豁免）。 */
+export function digestBudgetOver(agent, size) {
+  const round = digestRoundFor(agent)
+  const over = round.used > 0 && round.used + size > DIGEST_INJECT_BUDGET
+  round.used += size
+  return over
+}
+
+/** Test seam: 落盘目录重定向（单测沙箱——生产从不调用）。 */
+let _digestOffloadDirOverride = null
+export function _setDigestOffloadDirForTest(dir) { _digestOffloadDirOverride = dir }
+
+/** 超限条目全量落盘（返回清单行文本；失败 null——调用方回退 inline——结果零丢失）。
+ *  tag 入文件名（溯源：写入族 + 条目 id）。 */
+export async function persistOverflowReport(raw, { tag }) {
+  try {
+    const dir = _digestOffloadDirOverride ?? join(configDir, "tool-results")
+    await cleanupOldToolResults(dir)
+    await mkdir(dir, { recursive: true })
+    const file = join(dir, `${Date.now()}-${String(tag).replace(/[^a-zA-Z0-9_-]/g, "_")}.log`)
+    await writeFile(file, raw, "utf8")
+    return `Report saved to disk (digest inject budget exceeded — full text not inlined): ${file}\nRead it with the read tool (offset/limit).`
+  } catch (e) {
+    console.warn(`[digest] report persist failed — falling back to inline (report not lost): ${e.message}`)
+    return null
+  }
+}

package/src/agent-tools/eng.mjs

@@ -1,9 +1,18 @@
 /**
  * eng tool: enter/exit engineering mode.
  * In engineering mode the agent follows design-before-code methodology.
- * Toggled here at session level; persisted by /eng.
+ * Toggled here at session level (in-memory flag; the session slot is the sole authority —
+ * saveSession round-trips it at turn end; /eng writes the slot directly). The old ctx
+ * state-persist hook was removed 2026-09-08 (ENG-SESSION-PROVIDER-CLEANUP D1.2): no
+ * provider existed and its legacy payload keys were never read by applySession.
+ * R16 (2026-09-06): design tokens are session-level flow credentials — mode toggles
+ * do NOT clear them (ON→OFF keeps, OFF→ON does not require a fresh review); only TTL
+ * expiry cleans tokens, at three points: restore filtering (session.mjs applySession) /
+ * eng enter expired cleanup (below + cmd-eng ON) / spawn-gate expired rejection
+ * (subagent-spawn.mjs). See docs/design/ENG-TOKEN-BINDING-TUNING.md §5/§5.1 (F-R16).
  */
 import { ENG_ON_REMINDER, ENG_OFF_REMINDER } from "../agent.mjs"
+import { purgeExpiredDesignTokens } from "../token-ttl.mjs"
 
 export const engTool = {
   name: "eng",
@@ -22,50 +31,36 @@ export const engTool = {
     ctx.agent.config.agent ??= {}
     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
+      // R16 (F-R16a): OFF 不清 token——有效 token 跨模式存活（设计评审过的产物不因
+      // 开关重复烧）。过期清理跑在另外三处（恢复过滤 / 开模式 / spawn 门禁拒）。
       ctx.agent._advisorRound = 0          // reset convergence budget
+      ctx.agent._advisorRuns = new Map()   // §11.2 D-24b: per-review instances die with the mode (fresh cycles)
       ctx.agent._touchedFiles = []         // clear mutation tracking
       ctx.agent._lastEngState = false
       ctx.agent._pendingReminders = ctx.agent._pendingReminders ?? []
       ctx.agent._pendingReminders.push(ENG_OFF_REMINDER)
-      // 持久化工程模式状态到会话
-      if (ctx.persistState) {
-        await ctx.persistState({
-          engineering: false,
-          engDesignToken: null,
-          engDesignReviewed: false,
-          advisorRound: 0,
-          touchedFiles: []
-        })
-      }
       return "Engineering mode exited. Standard discipline now applies. You may edit files directly."
     }
     if (args.action === "enter") {
-      // Idempotent enter (v2 2026-08-25): already in engineering mode → no-op. The old
-      // unconditional token clear killed standing design tokens on a redundant defensive
-      // eng(enter) — only a real off→on transition requires a fresh design review.
+      // Idempotent enter (v2 2026-08-25): already in engineering mode → pure no-op
+      // (cleanup only runs on a real off→on transition — T-R16c precondition: first
+      // exit/OFF, then enter; an already-on enter must not touch tokens at all).
       if (ctx.agent.config.agent.engineering) {
         return "Engineering mode already active. Existing design tokens stay valid."
       }
       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)
+      // R16 (F-R16b ②): off→on 不重评——只清过期 token（用户裁定"打开工程模式时
+      // 应该清理"），有效 token 原样保留——遍历 Map 删过期，返回文案含清理个数。
+      const cleared = purgeExpiredDesignTokens(ctx.agent)
+      ctx.agent._advisorRuns = new Map() // §11.2 D-24b: per-review instances die with the mode (fresh cycles)
       ctx.agent._lastEngState = true
       ctx.agent._pendingReminders = ctx.agent._pendingReminders ?? []
       ctx.agent._pendingReminders.push(ENG_ON_REMINDER)
-      // 持久化工程模式状态到会话
-      if (ctx.persistState) {
-        await ctx.persistState({
-          engineering: true,
-          engDesignToken: null,
-          engDesignReviewed: false,
-          advisorRound: 0,
-          touchedFiles: []
-        })
+      let msg = "Engineering mode activated. Design-before-code enforced: write a design document first (location per your project's document conventions), run advisor with type='design', get user approval, then implement via eng-coder subagents."
+      if (cleared > 0) {
+        msg += ` Cleared ${cleared} expired design token${cleared === 1 ? "" : "s"} — 清 ${cleared} 个过期 token，有效 token 保留（TTL 内不重评）。`
       }
-      return "Engineering mode activated. Design-before-code enforced: write a design document in docs/, run advisor with type='design', get user approval, then implement via eng-coder subagents."
+      return msg
     }
     return "Invalid action: expected 'enter' or 'exit'"
   },

package/src/agent-tools/escalate-async.mjs

@@ -0,0 +1,289 @@
+/**
+ * escalate-async.mjs — async 飞刀 runner (AGENT-LOOP.md §25 D-R17b — R17, 2026-09-06).
+ *
+ * The subagent action:"escalate" is DEFAULT-async at depth 0 (decision ③: the
+ * depth-0-only escalate flips to async like every other background family;
+ * `async: false` keeps the legacy synchronous flight). An async escalate runs in
+ * the SHARED "other" pool domain (decision Q2 🅰 — the entry lives in
+ * `_asyncSubagents` with role "escalate"/_pool "other", so it shares the 4-slot
+ * other domain with explore/plan/coder spawns — capacity, queueing, refill,
+ * status and cancel all come from the generic machinery):
+ * - launch → ack {id, role:"escalate", status:"running"|"queued"[, position]};
+ *   the turn ends naturally, the session suspends (poolLive counts the entry).
+ * - settle THREE-WAY classification (review #4): done → merge-all mutations back
+ *   into the parent's bookkeeping + overlap warning appended to the report
+ *   (report-level, not a gate — round2 #4); error (child failure / turn cap) →
+ *   partial mutations merged ONLY when the parent did not touch overlapping
+ *   files since launch (overlap → no merge + differences listed in the report);
+ *   cancelled → never reaches the digest stream (D-M6 — no merge, stopped
+ *   reminder).
+ * - the classified report lands in `_pendingAsyncResults`（pending 单容器 +role——
+ *   ASYNC-RESULT-CONTAINER.md D2——挂起期 settle 移交）when the settle happens in a
+ *   suspension, or stays pooled for the turn-end collection otherwise;
+ *   injectAsyncResult's escalate
+ *   role branch delivers the digest ("报告已 merge——可继续处置" — the action
+ *   domain still follows the consuming turn's tier — no family exception).
+ */
+import { relative, isAbsolute } from "node:path"
+import { runAgent, createAgent, DEFAULT_SUBAGENT_TURNS } from "../agent.mjs"
+import { runWithContinue, TURN_CAP_MARK, wrapChildCallbacks } from "../agent/spawn-child.mjs"
+import { logEvent } from "../log.mjs"
+import { deathLine } from "../abort-provenance.mjs"
+import {
+  mergeChildMutations, runningPoolCount, poolDomainOf, poolLimitsFor, ASYNC_POOL_LIMITS, enqueueAsk,
+} from "./subagent-async.mjs"
+import { refreshQueuedTokens, nextSubagentId } from "./subagent-scheduler.mjs"
+import { mutationSeqOf } from "./advisor-async.mjs"
+// ASYNC-RESULT-CONTAINER.md D3/D6：settle 公共收尾单点 + child signal 构建单点
+import { buildChildSignal, settleAsyncEntry } from "./async-settle.mjs"
+
+/** Parent-side mutations (absolute paths) committed AFTER the escalate launch —
+ *  the overlap scan feeds the settle classification (review #4/round2 #4: the
+ *  parent may have edited files while the flight ran). */
+function parentMutationsSince(parent, launchSeq) {
+  const out = []
+  for (const m of parent?._mutLog ?? []) {
+    if (m.seq <= (launchSeq ?? -1)) continue
+    for (const p of m.paths ?? []) if (!out.includes(p)) out.push(p)
+  }
+  return out
+}
+
+/** Files BOTH sides touched since launch (case-insensitive key on win32 —
+ *  filesOverlap precedent). */
+function overlapPaths(parent, launchSeq, childTouched) {
+  const since = parentMutationsSince(parent, launchSeq)
+  if (since.length === 0 || !childTouched?.length) return []
+  const key = (p) => (process.platform === "win32" ? String(p).toLowerCase() : String(p))
+  const sinceKeys = new Set(since.map(key))
+  const hits = childTouched.filter((p) => sinceKeys.has(key(p)))
+  // relative display form (touchedFilesNote precedent)
+  const cwd = parent?.cwd ?? process.cwd()
+  return hits.map((p) => {
+    const r = relative(cwd, p)
+    return r && !r.startsWith("..") && !isAbsolute(r) ? r : p
+  })
+}
+
+/** Escalate-side touched files, relative display (or a placeholder). */
+function childTouchedDisplay(child, cwd) {
+  const touched = child?._touchedFiles ?? []
+  if (touched.length === 0) return "(none recorded)"
+  const shown = touched.map((f) => {
+    const r = relative(cwd ?? process.cwd(), f)
+    return r && !r.startsWith("..") && !isAbsolute(r) ? r : f
+  })
+  return shown.join(", ")
+}
+
+/** Relative touched-file list (mirror of the sync path's note). */
+function touchedFilesNote(child, cwd) {
+  const touched = child?._touchedFiles ?? []
+  if (touched.length === 0) return ""
+  const shown = touched.map((f) => {
+    const r = relative(cwd ?? process.cwd(), f)
+    return r && !r.startsWith("..") && !isAbsolute(r) ? r : f
+  })
+  return `\nTouched files: ${shown.join(", ")}`
+}
+
+/**
+ * Async escalate settle — three-way classification (§25 D-R17b review #4):
+ *  - done: merge ALL mutations (the escalation's changes are the parent's —
+ *    verify/advisor guards must see them) + overlap warning into the report
+ *    (report-level hint — not a gate — round2 #4);
+ *  - error (child failure / turn cap): partial mutations merge ONLY without a
+ *    parent-side overlap — overlap → NO merge + differences listed (the report
+ *    carries both sides so the model can decide);
+ *  - cancelled: nothing merges, never reaches pending (D-M6 — stopped reminder).
+ * Runs BEFORE the pending transfer / digest injection. Mutates entry.report /
+ * entry.error into the FINAL digest body (the family wording rides
+ * injectAsyncResult's escalate branch).
+ */
+export function classifyEscalateSettle(parent, entry) {
+  if (entry.cancelled) return { cancelled: true }
+  const child = entry.childAgent
+  const touched = child?._touchedFiles ?? []
+  const overlap = overlapPaths(parent, entry.launchSeq, touched)
+  const hasError = entry.error != null
+  const raw = hasError ? entry.error : entry.report
+  if (hasError) {
+    // error branch (child failure / turn cap — review #4): partial mutations
+    // merge ONLY when the parent did not touch overlapping files since launch.
+    // childAgent may be null when the flight died before child creation (advisor
+    // 复评 🟡2——防御：无 child 即无 partial mutations——不 merge 不崩）。
+    const merged = child != null && overlap.length === 0 && mergeChildMutations(parent, child)
+    let decision = ""
+    if (merged) {
+      decision = `\nPartial changes merged into the parent's bookkeeping (no parent-side overlap since launch).`
+    } else if (overlap.length > 0) {
+      decision = `\nPartial changes NOT merged — the parent changed overlapping files while this escalate ran: ${overlap.join(", ")}. Escalate-side changes: ${childTouchedDisplay(child, parent?.cwd)}. Review the conflict and decide what to keep (report-level — not a gate; AGENT-LOOP.md §25 D-R17b).`
+    }
+    // (nothing to merge + no overlap → the plain error report stands alone)
+    entry.error = `${raw}${decision}`
+    entry.report = null
+    return { cancelled: false, merged, overlap }
+  }
+  // done — merge-all + overlap warning into the report (report-level — not a gate)
+  const merged = mergeChildMutations(parent, child)
+  const overlapNote = overlap.length > 0
+    ? `\n⚠ Overlapping writes: the parent changed ${overlap.join(", ")} while this escalate ran — mutations merged all the same; review those files before building on the report (report-level warning — not a gate; AGENT-LOOP.md §25 D-R17b round2 #4).`
+    : ""
+  entry.report = `${raw}${overlapNote}`
+  return { cancelled: false, merged, overlap }
+}
+
+/**
+ * Launch the async escalate (preflights already passed in executeEscalateAction):
+ * pool admission into the shared OTHER domain → entry in `_asyncSubagents`
+ * (generic queue/refill/status/cancel machinery) → ack. The flight starts on
+ * entry.start() (immediately, or later via maybeRefillAsync when a slot frees).
+ */
+export function launchEscalateAsync(parent, ctx, launch) {
+  const { task, provider, tag, effortNote } = launch
+  parent._asyncSubagents ??= new Map()
+  parent._asyncQueue ??= []
+  // Async id allocation (AGENT-LOOP.md §15 D-A1 precedent): reserve the relay
+  // counter at launch — the returned id stays stable while the entry sits queued.
+  // The [model] token (TUI block creation) is DEFERRED to actual start so queued
+  // flights don't paint an empty panel block (subagent-parity).
+  // SUBAGENT-ID-COUNTER-AGENT（2026-09-09）：取号统一走 nextSubagentId（池活续号
+  // 兜底——counter 载体= agent 本体 _subAgentCounter——跨 run/跨压缩存活）。
+  const id = nextSubagentId(parent)
+  const relayPrefix = `escalate#${id}/`
+  const entry = {
+    id, role: "escalate", relayPrefix,
+    _pool: poolDomainOf("escalate"), // other — shares the domain with explore/plan/coder (§11.1 D-24a)
+    status: "queued",
+    position: undefined,
+    report: null, error: null, done: false, cancelled: false,
+    promise: null, _settle: null, _settleSeq: 0,
+    model: provider.model ?? null,
+    startedAt: null,
+    turn: 0, maxTurns: 0,
+    controller: null,
+    _files: undefined, _dependsOn: undefined,
+    childAgent: null,
+    tag, effortNote, launchSeq: mutationSeqOf(parent),
+  }
+  const limits = poolLimitsFor(parent)
+  entry.status = runningPoolCount(parent, entry._pool) >= (limits[entry._pool] ?? ASYNC_POOL_LIMITS[entry._pool])
+    ? "queued" : "running"
+  entry.promise = new Promise((res) => { entry._settle = res })
+  const ctrl = new AbortController()
+  entry.controller = ctrl
+  // D6 buildChildSignal 单点（ASYNC-RESULT-CONTAINER.md——D5 同款：_sessionSignal 兜底）。
+  const baseSignal = buildChildSignal(parent, ctx)
+  if (baseSignal) {
+    // §20.3 站点 #10（第 24 批）：hop 逐跳保 reason
+    if (baseSignal.aborted) ctrl.abort(baseSignal.reason)
+    else baseSignal.addEventListener("abort", () => ctrl.abort(baseSignal.reason), { once: true })
+  }
+  // Turn mirror (⟦ev⟧turn from the child runAgent → entry.turn/maxTurns — status parity).
+  const flight = async () => {
+    entry.status = "running"
+    entry.position = undefined
+    entry.startedAt = Date.now()
+    ctx.callbacks?.onToken?.(relayPrefix + "⟦ev⟧async\x1e")
+    ctx.callbacks?.onToken?.(relayPrefix + "[model]" + (provider.model ?? ""))
+    const child = createAgent({
+      provider,
+      tools: parent.tools,
+      config: parent.config,
+      cwd: parent.cwd,
+      memory: parent.memory,
+      // G3（施工②）：overlay 摘除——coder 人格槽由 assemblePrompt 场景表承载（G3 映射）。
+      role: "coder",
+    })
+    entry.childAgent = child // settle 分类/status touched 摘要绑定（start 时刻）
+    child._logId = relayPrefix.slice(0, -1)
+    logEvent("child:spawn", { role: "escalate", id: child._logId, kind: "async", status: "running", ms: 0 })
+    const childCallbacks = wrapChildCallbacks(relayPrefix, ctx.callbacks ?? {})
+    const relayOnToken = childCallbacks.onToken
+    if (relayOnToken) {
+      childCallbacks.onToken = (t) => {
+        const ev = String(t).match(/^⟦ev⟧turn\x1e(\d+)\x1e(\d+)\x1e/)
+        if (ev) {
+          entry.turn = Number(ev[1]) || 0
+          entry.maxTurns = Number(ev[2]) || 0
+        }
+        return relayOnToken(t)
+      }
+    }
+    const runner = ctx.runAgent ?? runAgent
+    const runOpts = {
+      depth: 1,
+      maxTurns: parent.config?.agent?.subagentTurns ?? DEFAULT_SUBAGENT_TURNS,
+      signal: entry.controller.signal,
+    }
+    // 权限按 async 子代理同款装配：AUTO 直放行；手动档经父 _permQueue（并行子代理
+    // 审批不叠弹窗）——背景飞行撞门时无 handler → denied 不悬挂（D-S7 同规则）。
+    const childPermission = parent.autoApprove
+      ? async () => true
+      : async (name, toolArgs) => {
+          if (!ctx.onPermissionRequest) return false
+          const ask = () => ctx.onPermissionRequest(`escalate/${name}`, toolArgs)
+          return enqueueAsk(parent, "_permQueue", ask)
+        }
+    const report = await runWithContinue(
+      (childAgent, input, cbs, opts) => runner(childAgent, input, cbs, opts),
+      child, task,
+      { ...childCallbacks, onPermissionRequest: childPermission },
+      runOpts,
+      {
+        // 后台飞行不弹 continue 面板（D-A3 §15 例外同款）：AUTO && engineering 自动
+        // resume——escalate 只在 normal 模式可用（engineering 拒）——恒自动拒 → partial。
+        askContinue: () => Promise.resolve(Boolean(parent.config?.agent?.engineering && parent.autoApprove)),
+        onDeclined: (e, output) => `escalate (${tag})${entry.effortNote} ${TURN_CAP_MARK} (${e.turn} turns) — work may be partial; review recent_changes before deciding next steps.\nPartial output: ${output.slice(0, 2000)}`,
+      },
+    )
+    // done: compose the post-op body (the settle classification appends the
+    // overlap warning / merge notes afterwards)
+    return `escalate (${tag})${entry.effortNote} post-op report:\n${report || (child._capturedOutput ?? "").slice(0, 4000)}${touchedFilesNote(child, parent.cwd)}`
+  }
+  entry.start = () => {
+    flight()
+      .then((report) => {
+        // Turn-cap partial (runWithContinue auto-declined) classifies as the ERROR
+        // branch (design: 撞 turn cap = error — partial-merge decision applies):
+        // move it to entry.error so the classification + error digest wording fire.
+        if (String(report).includes(TURN_CAP_MARK)) entry.error = report
+        else entry.report = report
+      })
+      .catch((e) => {
+        // 运行失败/中止：错误文本落 entry.error（子代理同款——cancel 分支忽略它；
+        // Ctrl+I 中止的残条目由收尾消化带错误文本——不落空 "(no report)" digest）。
+        const child = entry.childAgent
+        // §20.3 第 3 条合成器（第 24 批）：原 message 前缀逐字保留 + 来源后缀
+        entry.error = `escalate (${tag}) error: ${deathLine(e, entry.controller?.signal)}\nPartial output: ${(child?._capturedOutput ?? "").slice(0, 2000)}`
+      })
+      .finally(() => {
+        // settle 公共收尾单点（ASYNC-RESULT-CONTAINER.md D3——settleAsyncEntry）：日志三连
+        // /cancelled 分支（出池+墓碑+⟦ev⟧stopped+提醒）/挂起分流（pending 单容器+出池——
+        // 统一守卫 !parentAborted——D4）/公共尾部（settleSeq/_settle/唤醒 waiter + 腾槽补位
+        // ——helper 尾部恒补）统一走共享 helper。族特有 hook = 三分类 merge 决策
+        // （classifyEscalateSettle——done/error 分类；cancelled 不经此——helper cancelled
+        // 分支先行）。
+        settleAsyncEntry(parent, entry, {
+          pool: parent._asyncSubagents,
+          ctx,
+          onAccounting: () => {
+            // Three-way settle classification (done/error/cancelled — review #4)：
+            // done → merge-all + 重叠警告；error → 无父侧重叠才 partial merge；
+            // cancelled 不经此（helper cancelled 分支先行）。
+            void classifyEscalateSettle(parent, entry)
+          },
+        })
+      })
+  }
+  parent._asyncSubagents.set(String(id), entry)
+  logEvent("child:spawn", { role: "escalate", id: `escalate#${id}`, kind: "async", status: entry.status, ms: 0 })
+  if (entry.status === "queued") {
+    parent._asyncQueue.push(entry)
+    entry.position = parent._asyncQueue.length
+    refreshQueuedTokens(parent, ctx.callbacks?.onToken)
+    return JSON.stringify({ id: String(id), role: "escalate", status: "queued", position: entry.position })
+  }
+  entry.start()
+  return JSON.stringify({ id: String(id), role: "escalate", status: "running" })
+}