thincoder 0.12.59 → 0.12.61

package/src/agent-tools/advisor.mjs

@@ -2,67 +2,29 @@
  * agent-tools/advisor.mjs — advisor tool wrapper.
  * The agent calls this explicitly to get an independent review.
  * type="design" for design doc review, type="code" for code review (default).
+ * §11.2 (R13 — async advisor): at depth 0 the review launches into the
+ * background pool by DEFAULT (async:true / omitted; async:false forces the
+ * blocking review); depth>0 (eng-coder self-review) stays synchronous always.
  */
-import { randomUUID, createHmac } from "node:crypto"
-import { runAdvisorReview } from "../advisor/run.mjs"
-import { isDocFile } from "../advisor/repos.mjs"
+import { runAdvisorReview, MAX_ADVISOR_ROUNDS, buildCapMessage, advisorIncompleteMarker, ADVISOR_LAUNCH_REFUSAL_PREFIX, buildDesignReviewGuardMessage } from "../advisor/run.mjs"
+import { resolveBatchDocPath } from "./batch-segment.mjs"
+import { isDocPath, loadConventions } from "../conventions.mjs"
+import {
+  generateDesignToken,
+  settleDesignReview,
+  resolveAdvisorLaunch,
+  launchAsyncAdvisor,
+  stripApprovedSuffix,
+} from "./advisor-async.mjs"
+// 第 33 批（§17.5）：护栏消费面——工具层预检（检查点 1）+ 同步面计数（计数点 2）。
+import {
+  designReviewOutcome, designReviewStreakRecord, designReviewStreakStopped, noteDesignReviewOutcome,
+} from "./review-streak.mjs"
 
-const TOKEN_TTL_DEFAULT_MS = 7 * 24 * 3600 * 1000 // 7-day ceiling (v2 2026-08-25): multi-batch delivery must not re-review an unchanged design within a week; agent.engTokenTtlMs overrides
-const TOKEN_SECRET = process.env.THINCODER_TOKEN_SECRET || "thincoder-default-secret"
-
-/** Effective token TTL: config override with runtime validation (advisor timeoutMs precedent —
- *  invalid values fall back to the default, never silently disable the ceiling). */
-function effectiveTokenTtlMs(agent) {
-  const cfg = agent?.config?.agent?.engTokenTtlMs
-  return (Number.isFinite(cfg) && cfg > 0) ? cfg : TOKEN_TTL_DEFAULT_MS
-}
-
-/** Generate a signed design token with expiration */
-function generateDesignToken(agent) {
-  const uuid = randomUUID()
-  const expiresAt = Date.now() + effectiveTokenTtlMs(agent)
-  const payload = `${uuid}:${expiresAt}`
-  const signature = createHmac("sha256", TOKEN_SECRET).update(payload).digest("hex").slice(0, 16)
-  return `${payload}:${signature}`
-}
-
-/** Validate design token: format, expiration, signature — ALL fail-closed (v2 2026-08-25).
- *  The two legacy fail-open branches (parts!=3 → true, NaN expiry → true) were pass-through
- *  backdoors: any malformed string bypassed validation. Only exact signed tokens pass now.
- *  Format must be exactly uuid:expiresAt:hmacSig. */
-export function validateDesignToken(token) {
-  if (!token || typeof token !== "string") return false
-
-  // New format: uuid:expiresAt:signature (3 parts separated by ':')
-  const parts = token.split(":")
-  if (parts.length !== 3) return false // fail-closed (was: return true)
-
-  const [uuid, expiresAt, signature] = parts
-  const expTime = parseInt(expiresAt, 10)
-  if (isNaN(expTime)) return false // fail-closed (was: return true)
-
-  // Check expiration
-  if (Date.now() > expTime) return false
-  
-  // Check signature
-  const payload = `${uuid}:${expiresAt}`
-  const expectedSig = createHmac("sha256", TOKEN_SECRET).update(payload).digest("hex").slice(0, 16)
-  return signature === expectedSig
-}
-
-/** Build a [DESIGN-TOKEN:...] regex; escapes special chars as a safety net.
- *  Matches the FULL token (uuid:expiresAt:signature) — prompt tells advisor
- *  to echo the complete token verbatim, not just the UUID segment.
- *  Flexible matching: allows token to be on its own line, in a code block,
- *  or surrounded by whitespace. */
-const makeDesignTokenRegex = (token, flags = "") => {
-  // Escape the entire token, not just UUID — advisor echoes [DESIGN-TOKEN:uuid:expiresAt:signature]
-  const escaped = token.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
-  return new RegExp(
-    `(?:^|\\s|\`|\\*)\\[DESIGN-TOKEN:\\s*${escaped}\\s*\\](?:\\s|$|\`|\\*)`,
-    flags + "ms"
-  )
-}
+// Design-token utilities moved to advisor-async.mjs (the async settle shares
+// them — no wrapper↔runner module cycle); validateDesignToken stays exported
+// here for the tests' import surface (implementation re-exported).
+export { validateDesignToken } from "./advisor-async.mjs"
 
 export const advisorTool = {
   name: "advisor",
@@ -81,11 +43,22 @@ export const advisorTool = {
     "Optionally pass object={type,target,status,reason,exclude} to anchor the review target " +
     "(AGENT-LOOP.md §18.8 — the review-object declaration is mechanically injected into the review message); " +
     "absent → legacy behavior (no injection). " +
+    "ASYNC (AGENT-LOOP.md §11.2): at depth 0 the review runs in the BACKGROUND by default " +
+    "(async:true or omitted) — the call returns an ack immediately, the turn ends, and the report " +
+    "arrives automatically in a digest turn when the review finishes; background reviews share one pool — " +
+    "at most agent.poolLimits.advisor concurrent reviews (default 4 — configurable via /config 并发池 or " +
+    "config.json; pool-full and same-scope refusals state the current limit) — launch reviews one at a time. " +
+    "Inside a child (depth>0 — eng-coder self-review) " +
+    "reviews are always synchronous; async:true is rejected there. " +
     "Returns the review report — the advisor's findings verdict: all-clear (call verify) or a findings list to fix.",
   parameters: {
     type: "object",
     properties: {
       type: { type: "string", enum: ["code", "design"], description: "Review type: 'design' for design doc review, 'code' for code review (default)" },
+      async: {
+        type: "boolean",
+        description: "Background review: default at depth 0 = true (async — ack now, report via digest); async:false forces the blocking review (mechanism parameter — top-level launches are async by default). depth>0 → always sync (async:true rejected).",
+      },
       object: {
         type: "object",
         properties: {
@@ -107,6 +80,10 @@ export const advisorTool = {
         items: { type: "string" },
         description: "Explicit list of doc paths to review (design docs, requirements docs, referenced docs). The advisor reviews ONLY these — it does NOT scan git diff. Use for both design review and code review to pass the task's Docs involved list.",
       },
+      batchDoc: {
+        type: "string",
+        description: "Design review only: path to the batch record currently in flight. Validated WHENEVER passed (any review type) — a value that is not a readable file is refused with an error rather than ignored; for design reviews the reviewer then ALSO gets the batch_segment write channel to record its findings table + VERDICT + counts into §3 (ENGINEERING-MODE.md §2.20). Omit when no batch record is in flight — the review then runs unchanged with no write channel (zero regression).",
+      },
     },
   },
   readonly: true,
@@ -129,80 +106,154 @@ export const advisorTool = {
 
     // Code review must have a scope — no implicit fallback.
     if (reviewType !== "design" && !paths && !documents) {
+      if (ctx._toolCallId !== undefined) (agent._advisorRefusals ??= new Set()).add(ctx._toolCallId)
       return "Advisor: no review scope specified. Provide paths (files/directories to review) or documents (acceptance criteria context)."
     }
 
-    // Design review: validate that documents are in docs/ or are recognized doc files
+    // Design review: the review scope must be documentation files. Classification
+    // comes from the single authority (src/conventions.mjs) — the old `docs/`
+    // prefix test is retired with it (FR12: no directory-name hardcoding in the
+    // gate; a project whose docs live elsewhere just declares its code paths).
     if (reviewType === "design" && documents) {
-      const invalidDocs = documents.filter((doc) => {
-        // Allow docs/ directory and recognized doc files (METHODOLOGY.md, README.md, etc.)
-        if (doc.startsWith("docs/") || doc.startsWith("docs\\")) return false
-        return !isDocFile(doc)
-      })
+      const conv = loadConventions(agent.cwd)
+      const invalidDocs = documents.filter((doc) => !isDocPath(doc, conv))
       if (invalidDocs.length > 0) {
-        return `Advisor: design review documents must be in docs/ directory or be recognized doc files. Invalid: ${invalidDocs.join(", ")}`
+        if (ctx._toolCallId !== undefined) (agent._advisorRefusals ??= new Set()).add(ctx._toolCallId)
+        return `Advisor: design review documents must be documentation files (per the project's conventions). Invalid: ${invalidDocs.join(", ")}`
       }
     }
 
-    // Design review: NO round reset — design reviews share the 5-round convergence
-    // budget with code reviews (round advances in agent.mjs; cap in run.mjs).
-    // Session reset also removed: design rounds 2+ continue the advisor session
-    // like code reviews (fix claims + round-aware prompts).
+    // §11.2 (R13 — ruling ②-3 A): async gate. Depth-0 defaults to the
+    // background pool; depth>0 (eng-coder internal self-review) is ALWAYS sync —
+    // an explicit async:true there is rejected, the default never flips.
+    const depth = ctx?.depth
+    if (args.async === true && depth !== 0) {
+      // 拒发登记（与 cap/池满拒同款）：评审未跑——不置 called/不耗轮次（record-results
+      // 的 REFUSED 契约——advisor 评审发现 #1：拒发不得静默满足 guard）。
+      if (ctx._toolCallId !== undefined) (agent._advisorRefusals ??= new Set()).add(ctx._toolCallId)
+      return "Advisor: async reviews are only available at depth 0 — the top-level session owns the background pool (AGENT-LOOP.md §11.2); inside a child (eng-coder self-review) reviews run synchronously. Call advisor again without async:true (or with async:false)."
+    }
+    const isAsync = args.async === true || (depth === 0 && args.async !== false)
+    // (ctx.depth undefined = direct callers/tests without a dispatch context —
+    // legacy sync semantics.)
 
-    // Generate the design token BEFORE the review and inject it into the advisor's prompt.
-    // The advisor (LLM) decides pass/fail itself and echoes the token only on approval —
-    // the gate is a mechanical string match, not fragile semantics parsing.
-    // A random designId is minted for EVERY design-review call (2026-09-01 multi-design
-    // slots): on pass the token is stored in parent._engDesignTokens keyed by this id and
-    // the id is echoed to the parent; on failure the id is dropped — never stored, so it
-    // cannot clobber any other design's slot. Not a document anchor (rejected 2026-08-31).
+    // Per-review instance resolution (§11.2 ③ — ruling ②-5 A): fix rounds
+    // continue the same reviewId (design = the doc-set instance's designId —
+    // slot/spawn continuity; code = the newest OPEN instance). The resolution
+    // scopes agent._advisorRound/_lastAdvisorOutput so the message builder and
+    // the run.mjs cap read THIS instance's round/prior (multi-review isolation).
+    const resolved = resolveAdvisorLaunch(agent, reviewType, { documents })
+    // §2.20.2 评审侧批次档门禁 + 实例键绑定（batch_segment 的唯一路径来源）：
+    // 口径 = **「若传则须可读」**（空/不可读 → throw；不强制必传——无批次档的在途设计评审
+    // 零回归，N5）；绑定落在 resolved.run（评审实例键，与 reviewType/round/designId 同族）——
+    // 并发设计评审各绑各档，不用单值会话态（§2.20.8 #6）。
+    if (args.batchDoc !== undefined && args.batchDoc !== null) {
+      resolved.run.batchDoc = resolveBatchDocPath(agent.cwd, args.batchDoc)
+    }
+    // Design token minted for EVERY design round — the reviewer echoes it only on
+    // a clean pass; on pass it is slotted under the instance's designId at settle
+    // (sync: right here; async: the settle callback — fix #2). A NEW instance
+    // gets a fresh designId; a continued fix round keeps the original one — and a
+    // same-scope re-review after a pass REUSES the session's id (F2h §29.1).
     const designToken = reviewType === "design" ? generateDesignToken(agent) : null
-    const designId = reviewType === "design" ? randomUUID() : null
+    const designId = reviewType === "design" ? resolved.designId : null
+
+    // Cap pre-check (T-24b11 — per-review ≤5 rounds, CODE REVIEWS ONLY): a 6th
+    // launch of a capped CODE instance is refused synchronously — the review
+    // never starts (sync and async alike; runAdvisorReview's own cap check stays
+    // for legacy direct callers). DESIGN reviews are EXEMPT (2026-09-07 §8
+    // ruling): their rounds keep advancing (ROUND2/3 convergence prompts + TUI
+    // round display) but the cap never refuses them. The refusal marks no
+    // called/round state (guard keeps pushing only while a review can still run
+    // — at the cap the round check stops it).
+    if (resolved.run.reviewType !== "design" && resolved.run.round >= MAX_ADVISOR_ROUNDS) {
+      if (ctx._toolCallId !== undefined) (agent._advisorRefusals ??= new Set()).add(ctx._toolCallId)
+      return buildCapMessage(agent)
+    }
+
+    // 第 33 批（§17.5 检查点 1——工具层预检；cap 预检邻位 / sync / async 分叉前）：同一 doc-set
+    // 连续 `MAX_DESIGN_REVIEW_STREAK` 次未产出可用结算 ⇒ 拒发（登记 `_advisorRefusals` 同 cap /
+    // 池满款——不置 called / 不耗轮次 / **零 LLM**），返回结论串。
+    if (reviewType === "design" && designReviewStreakStopped(agent, resolved.run.docSetKey)) {
+      if (ctx._toolCallId !== undefined) (agent._advisorRefusals ??= new Set()).add(ctx._toolCallId)
+      return buildDesignReviewGuardMessage(designReviewStreakRecord(agent, resolved.run.docSetKey), documents ?? [])
+    }
+
+    if (isAsync) {
+      const ack = launchAsyncAdvisor(agent, ctx, {
+        reviewType, documents, paths, object: reviewObject,
+        designToken, designId, run: resolved.run,
+      })
+      if (ack.error) {
+        // Pool-full refusal (②-6a — no queueing): the review did NOT launch — the
+        // model must not count it as "advisor called" (the guard keeps pushing).
+        if (ctx._toolCallId !== undefined) (agent._advisorRefusals ??= new Set()).add(ctx._toolCallId)
+        return ack.error
+      }
+      // Async-ack marker: recordToolResults must NOT do the launch-time
+      // accounting (called/round) for this call — the settle owns it.
+      if (ctx._toolCallId !== undefined) {
+        (agent._advisorAsyncAcks ??= new Set()).add(ctx._toolCallId)
+      }
+      // E（F17/§14.14 E-3c）：设计评审点火回执追加冻结句（代码评审 ack 零改）——窗口下界以
+      // 可观察信号表达：报告送达 / 取消前，被审文档（含批次档）零写入。
+      const freezeNote = reviewType === "design"
+        ? "；D5 冻结窗口：被审文档（含批次档）在报告送达前零写入——在途写入会被拒绝，写入将使本轮结算为陈旧 (pass 不发 token)"
+        : ""
+      return JSON.stringify({
+        id: ack.id, kind: "advisor", status: "running",
+        reviewId: resolved.reviewId,
+        note: "评审已后台启动——完成自动回来 (review started in the background — the report arrives in a digest turn automatically; pass this id to cancel if needed)" + freezeNote,
+      })
+    }
+
+    // Sync path (depth>0 / explicit async:false / direct callers without depth):
+    // legacy blocking review. The design token/echo handling runs below; the
+    // instance accounting (round++ per completed attempt) lands in
+    // recordToolResults, marker-keyed by this tool call's id.
+    if (ctx._toolCallId !== undefined) {
+      (agent._advisorSyncCalls ??= new Map()).set(ctx._toolCallId, resolved.reviewId)
+    }
     const result = await runAdvisorReview(agent, reviewType, {
       onOutput: ctx.onOutput,
       signal: ctx.signal,
-    }, designToken, documents, paths, reviewObject)
+      // 同步路径的实例绑定传递（异步路径由池条目 run.batchDoc 取——run.mjs 自行解析）。
+      batchDoc: resolved.run.batchDoc ?? null,
+    }, designToken, documents, paths, reviewObject, designId)
+
+    // B 启动拒绝（§14.4 #2——稳定前缀）：拒发登记（同池满 / cap 款——不置 called、不耗轮次），
+    // 可见报错照常返回（record-results 的 REFUSED 契约）。第 33 批：判定单点——同时供设计
+    // 失败分类复用（launchRefused ⇒ neutral——无尝试发生，§17.3 #1）。
+    const launchRefused = String(result).startsWith(ADVISOR_LAUNCH_REFUSAL_PREFIX)
+    if (launchRefused && ctx._toolCallId !== undefined) {
+      (agent._advisorRefusals ??= new Set()).add(ctx._toolCallId)
+    }
 
     if (reviewType === "design") {
-      // Whitespace-tolerant match (LLM may add spaces or wrap in fences).
-      // The token IS the verdict — the advisor echoes it only on approval (prompt-enforced);
+      // Design pass/fail settlement — token echo IS the verdict (prompt-enforced);
       // no findings-table heuristics: a design with issues never carries the token.
-      const tokenPattern = makeDesignTokenRegex(designToken)
-      if (designToken && result && tokenPattern.test(result)) {
-        // Advisor echoed the token → review passed. Issue it to the parent for eng-coder.
-        // (session cleanup for design reviews is owned by runAdvisorReview)
-        // Multi-design slots (2026-09-01): store under this review's designId; the single
-        // `_engDesignToken` mirror stays for the legacy boolean gates (dispatch "has token",
-        // session persistence) — key decision ② of ENGINEERING-MODE.md §7 2026-09-01.
-        agent._engDesignTokens ??= new Map()
-        agent._engDesignTokens.set(designId, designToken)
-        agent._engDesignToken = designToken
-        // Unlock the dispatch design gate (dispatch.mjs) for eng-coder SELF-review:
-        // an eng-coder whose own design review passed may write files without the
-        // parent spawn-time authorization. NOTE: unreachable today — eng-coder.md
-        // tells the child not to re-run the design review, and spawn already sets
-        // _engDesignReviewed (subagent.mjs). Kept as defense-in-depth for a future
-        // eng-coder autonomous design-revision entry. Parent agents (role undefined)
-        // don't use this flag — their runAgent resets it anyway; they are trusted
-        // via the engineering prompt.
-        if (agent._role === "eng-coder") agent._engDesignReviewed = true
-        // Strip the bracketed token so only ONE unambiguous format (plain UUID) reaches the main agent
-        const cleanResult = result.replace(makeDesignTokenRegex(designToken, "g"), "").trim()
-        // designId rides the Approved block (review #1): the parent needs it to aim the FIRST
-        // eng-coder spawn when several designs live in the same session.
-        return `${cleanResult}\n\nApproved. Pass this exact token to eng-coder (designToken parameter): ${designToken}\ndesignId: ${designId} (pass as the designId parameter when spawning eng-coder; optional while this session holds a single design)`
-      }
-      // Review failed (or advisor chose not to pass) → do NOT touch ANY slot (方案 ②, review #2:
-      // a failed RE-review leaves the previously approved token alive until TTL; the failed call's
-      // own designId was never stored, so there is nothing to clear). Isolation (2026-08-30,
-      // extended to the multi-slot Map 2026-09-01): a network glitch must not clear / other
-      // designs' slots must not be affected — only a COMPLETED non-passing review lands here,
-      // and it revokes nothing.
-      // Strip every dead token occurrence from the raw output so the main agent can't grab an invalid one
-      if (result) {
-        const stripped = result.replace(makeDesignTokenRegex(designToken, "g"), "").trim()
-        return stripped || "Advisor: design review did not pass."
+      // (session cleanup for design reviews is owned by runAdvisorReview)
+      // Multi-design slots (2026-09-01): store under this review's designId.
+      // DESIGN-TOKEN-SETTLEMENT D3 (2026-09-08): the single `_engDesignToken` mirror is
+      // retired — no mirror write here; the dispatch/spawn gates read the authoritative
+      // multi-slot Map (+ slot-file re-read). Slotting moved into settleDesignReview
+      // (shared with the async settle — fix #2).
+      const incomplete = advisorIncompleteMarker(result)
+      const settled = settleDesignReview(agent, resolved.run, designToken, result, { incomplete })
+      // 第 33 批（§17.5 计数点 2——同步面）：同分类单源落账（同步面无 stale / 无落盘步骤
+      // ⇒ persistFailed 恒 false）。
+      noteDesignReviewOutcome(agent, resolved.run.docSetKey, designReviewOutcome({
+        launchRefused, stale: false, hasResult: result != null, incomplete, persistFailed: false,
+      }))
+      // F2e (§29.1): the sync prior mirror must not carry the raw echo the runner
+      // stored — overwrite with the clean settled form (exact-suffix truncation).
+      if (settled.passed) {
+        agent._lastAdvisorOutput = stripApprovedSuffix(settled.output, resolved.run.approvedSuffix)
+      } else if (incomplete) {
+        // 未完成 ⇒ 同步 prior 镜像覆写为清洗后输出（防未注册 token 进 prior——§14.3）。
+        agent._lastAdvisorOutput = settled.output
       }
+      return settled.output
     }
     return result
   },

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

@@ -0,0 +1,191 @@
+/**
+ * async-settle.mjs — async 结果容器统一共享 helper（ASYNC-RESULT-CONTAINER.md D1-D6，
+ * 2026-09-08——CLI 端落地；VS Code 同名机制各自独立实现）。根治四族 settle 记账逐字
+ * 重复（subagent/advisor/escalate/consult）+ pending 三族分叉（_pendingEscalateResults/
+ * _pendingConsultResults 独立族废弃）+ done-in-pool 三表示 + _sessionSignal 兜底抄 3 处
+ * （consult 无兜底）：
+ * - D1 池 accessor：`getAsyncPool(parent, role)`——role "advisor" 返 `_asyncAdvisors`，
+ *   其余返 `_asyncSubagents`——底层保留双池（advisor 无队列独立调度），accessor 吸收差异。
+ * - D2 pending 单容器：全族统一 `_pendingAsyncResults`，条目带 role 字段（consult 升格
+ *   完整 entry）；`parkAsyncPending` 统一停靠（`_inPending` 标记保留防重复移交——settle
+ *   回调与 sweepSettledToPending 同一表示，done-in-pool 统一：留池 done:true + pending
+ *   单容器）。
+ * - D3 settle 共享 helper：`settleAsyncEntry(parent, entry, {pool, ctx, onAccounting})`——
+ *   公共收尾单点（日志三连（ev:cancelled / child:done|error + ev:settled）→ cancelled /
+ *   parentAborted / 挂起分流 → settleSeq/`_settle` 唤醒 waiter）。族特有段作 onAccounting
+ *   hook 注入（advisor 陈旧判定/token D1 落盘记账；escalate 三分类 merge 决策 + 腾槽补位）。
+ * - D4 守卫统一：`parentAborted`（= `ctx.signal?.aborted || entry.controller?.signal?.
+ *   aborted`——escalate 严格版）——日志三连与挂起分流共用同一守卫。
+ * - D6 buildChildSignal：`parent._sessionSignal ?? ctx.signal ?? null` 单点（原 3 处
+ *   逐字抄；consult 补 _sessionSignal 兜底——D5）。
+ * 模块图：单向 import subagent-scheduler.mjs（dependentLabels——cancelled 提醒依赖者
+ * 列表）+ log/context/helpers/spawn-child——四族 settle 回调（subagent-run/advisor-async/
+ * escalate-async/consult）单向 import 本模块；scheduler 反向 import 本模块（getAsyncPool）
+ * 与既有 scheduler ↔ subagent-async 同款惰性环——无求值期依赖。
+ */
+import { logEvent, errText } from "../log.mjs"
+import { pushReal } from "../context.mjs"
+import { escapeXml } from "../agent/helpers.mjs"
+import { TURN_CAP_MARK } from "../agent/spawn-child.mjs"
+import { dependentLabels, maybeRefillAsync, refreshQueuedTokens } from "./subagent-scheduler.mjs"
+
+// ─── D1 池 accessor（吸收双池）────────────────────────────────────────────────
+
+/** 池 accessor（D1）：role "advisor" → `_asyncAdvisors`（独立评审池——无队列独立调度）；
+ *  其余角色 → `_asyncSubagents`（子代理/飞刀共享槽位队列池）。未初始化返 null——调用方
+ *  以 `?? new Map()` / 可选链处置。 */
+export function getAsyncPool(parent, role) {
+  if (role === "advisor") return parent?._asyncAdvisors ?? null
+  return parent?._asyncSubagents ?? null
+}
+
+// ─── D2 pending 单容器（+role）───────────────────────────────────────────────
+
+/** pending 单容器停靠（settle 挂起分流 / sweep 补扫共用——统一表示：条目置 `_inPending`
+ *  防重复移交（sweep 幂等判据），includes 去重兜底）。 */
+export function parkAsyncPending(parent, entry) {
+  const pend = (parent._pendingAsyncResults ??= [])
+  if (pend.includes(entry)) return
+  entry._inPending = true
+  pend.push(entry)
+}
+
+// ─── D4 守卫统一（严格版）+ D6 信号兜底单点 ──────────────────────────────────
+
+/** D4 settle 守卫统一（escalate 严格版）：父侧中止 = 回合 signal aborted 或条目
+ *  controller aborted（取消先行——cancelled 分支在守卫之前分流，定向 cancel 不算父中止）。
+ *  日志三连与挂起分流共用本守卫。 */
+export function parentAborted(ctx, entry) {
+  return Boolean(ctx?.signal?.aborted || entry?.controller?.signal?.aborted)
+}
+
+/** D6 child signal 构建单点（D5——consult 补 _sessionSignal 兜底）：挂起会话内的回合
+ *  （digest/用户回合）子代理持会话 signal（`parent._sessionSignal`——会话 Stop 逐链中止，
+ *  消化轮自身 Ctrl+I/Ctrl+C 不误伤）；回合级 `ctx.signal` 兜底。原 subagent/advisor/
+ *  escalate 3 处逐字抄 + consult 补上统一入此。 */
+export function buildChildSignal(parent, ctx) {
+  return parent?._sessionSignal ?? ctx?.signal ?? null
+}
+
+// ─── D3 settle 共享 helper ───────────────────────────────────────────────────
+
+/**
+ * D3 settle 共享 helper——四族 settle 回调公共收尾单点（ASYNC-RESULT-CONTAINER.md
+ * AC1：settle 记账单点，无逐字重复）。流程：
+ *   ① 落 done/status="done"（settle 即翻——不再占槽/持文件域；report/error 由各族
+ *      在调用前落好——subagent 的未投递注记先于本调用附加）；
+ *   ② 日志三连（统一守卫 !parentAborted——cancelled → ev:cancelled；非中止 →
+ *      child:done|:error（族形态：advisor 合并单事件；escalate 撞 cap 归 partial）+
+ *      挂起期 ev:settled；consult 族跳过——per-model 日志已在子代理 settle 时记录）；
+ *   ③ 分流：cancelled（出池 + cancelled 墓碑 + ⟦ev⟧stopped + 族提醒——不入 pending）→
+ *      parentAborted（守卫抑制——不落事件不入流——中止清池在回合尾/挂起中止统一做）→
+ *      settled（族 onAccounting hook 记账 → 挂起期（或 consult 族恒停靠）移交 pending
+ *      单容器 + 出池 + ⟦ev⟧settled；回合内 ⟦ev⟧done 留池 done:true）；
+ *   ④ 公共尾部：settleSeq 递增 + `_settle` 唤醒 waiter + 腾槽补位（subagent/escalate 族
+ *      恒补——settle/cancel 释放槽 → maybeRefillAsync + refreshQueuedTokens——AGENT-LOOP.md
+ *      §10 "settle/cancel 释放槽后…启动到槽满"；advisor（独立评审池——无队列）/consult
+ *      （会话池）豁免）。
+ * opts（设计签名 `{pool, onAccounting}` + 实现参数 ctx）：
+ * - pool：条目所在池 Map（出池 delete 目标；consult 传 null——会话池无条目）。
+ * - ctx：回合上下文（守卫读 ctx.signal；⟦ev⟧ 事件经 ctx.callbacks.onToken；腾槽补位
+ *   的 refreshQueuedTokens 也经 ctx.callbacks.onToken；consult 传 null——无 TUI 事件
+ *   无守卫）。
+ * - onAccounting(parent, entry)：族特有 hook——advisor 调 settleAdvisorRun 记账（D1
+ *   落盘保留）；escalate 调 classifyEscalateSettle（三分类 merge 决策）。
+ *   设计偏差注（advisor code review 发现——交付报告同步）：设计 D3 把 maybeRefillAsync
+ *   归入 onAccounting hook（仅 settled 分支执行）——running 取消的 cancelled 分支将不再
+ *   补位（槽释放但 queued 头停滞——挂起会话无回合尾补位覆盖），违背既有不变式
+ *   （AGENT-LOOP.md §10 + subagent-scheduler maybeRefillAsync 文档 "called from every
+ *   settle"）与 VSC 镜像（无条件 refill）。修正：腾槽补位移入公共尾部（subagent/escalate
+ *   族恒补——旧行为零回归；advisor/consult 豁免——同 VSC refill!==false 语义）。
+ */
+export function settleAsyncEntry(parent, entry, opts = {}) {
+  const { pool = null, ctx = null, onAccounting = null } = opts
+  const role = entry.role ?? "subagent"
+  entry.done = true
+  entry.status = "done"
+  const childLogId = `${role}#${entry.id}`
+  const childMs = entry.startedAt ? Date.now() - entry.startedAt : 0
+  const aborted = parentAborted(ctx, entry)
+  // ② 日志三连（D4 统一守卫——中止不落错误事件——ev:stopped 已在中止清池点表达；
+  // 定向 cancel 走 ev:cancelled）。族形态差异（LOGGING.md）：
+  // - advisor：合并单 child:done（kind error/ok）；
+  // - escalate：撞 cap 归 child:done partial（error 且非 capPartial 才 child:error）；
+  // - 其余（subagent 族）：error → child:error；done kind 按报告撞 cap 判 partial。
+  if (role !== "consult") {
+    if (entry.cancelled) {
+      logEvent("ev:cancelled", { id: childLogId })
+    } else if (!aborted) {
+      if (role === "advisor") {
+        const err = entry.error != null ? errText(entry.error, 200) : null
+        logEvent("child:done", { role, id: childLogId, ms: childMs, kind: err ? "error" : "ok" })
+      } else if (role === "escalate") {
+        const capPartial = String(entry.error ?? entry.report ?? "").includes(TURN_CAP_MARK)
+        if (entry.error != null && !capPartial) logEvent("child:error", { role, id: childLogId, ms: childMs, err: errText(entry.error, 200) })
+        else logEvent("child:done", { role, id: childLogId, ms: childMs, kind: capPartial ? "partial" : "ok" })
+      } else {
+        if (entry.error != null) logEvent("child:error", { role, id: childLogId, ms: childMs, err: errText(entry.error, 200) })
+        else logEvent("child:done", { role, id: childLogId, ms: childMs, kind: String(entry.report ?? "").includes(TURN_CAP_MARK) ? "partial" : "ok" })
+      }
+      if (parent._suspended) logEvent("ev:settled", { id: childLogId, kind: "suspended" })
+    }
+  }
+  // ③ 分流
+  if (entry.cancelled) {
+    // §19.5 cancelled settle 分支（D-M6）：不入 pending、不参与回合尾直注入——清池 +
+    // 终态墓碑（dependsOn 取消语义）+ ⟦ev⟧stopped 冻结 + 族提醒（半成品警示对模型可见）。
+    pool?.delete(String(entry.id))
+    const tombstones = (parent._asyncTombstones ??= new Map())
+    tombstones.set(String(entry.id), { status: "cancelled", role })
+    ctx?.callbacks?.onToken?.(`${entry.relayPrefix}⟦ev⟧stopped\x1e0\x1e0\x1estopped\x1e`)
+    if (role === "advisor") {
+      // ②-6b：评审取消——token 未签发提醒（settleAdvisorRun 不消费预算）。
+      pushReal(parent, {
+        role: "user",
+        content: `[System reminder: async advisor review #${escapeXml(String(entry.id))} cancelled — the review did not settle; token not issued (评审已取消——token 未签发)]`,
+      })
+    } else if (role === "escalate") {
+      pushReal(parent, {
+        role: "user",
+        content: `[System reminder: async escalate #${entry.id} (${entry.tag}) cancelled by user — partial changes not merged/audited]`,
+      })
+    } else {
+      // §20 D-SD5：running 依赖取消——提醒列出依赖者（供模型决策）。
+      const dependents = dependentLabels(parent, String(entry.id))
+      const autoNote = parent.autoApprove
+        ? " — AUTO session: they auto-start on slot availability (round2 #3)"
+        : " — they stay queued until you cancel them or an AUTO session starts them"
+      pushReal(parent, {
+        role: "user",
+        content: `[System reminder: subagent ${escapeXml(role)}#${entry.id} cancelled by user — partial changes not merged/audited${dependents.length > 0 ? `; queued dependents ${dependents.join(", ")} marked "dependency cancelled"${autoNote}` : ""}]`,
+      })
+    }
+  } else if (!aborted) {
+    // 族记账 hook（advisor 陈旧判定/token D1 落盘；escalate 三分类 merge 决策；subagent/
+    // escalate 腾槽补位）——可改写 entry.report（settle 分支输出——digest 原样进）。
+    onAccounting?.(parent, entry)
+    // 挂起分流（§17 D-S8 + D-S3 记账——以读取时刻为准）：挂起期 settle → 移交 pending
+    // 单容器（digest 注入）+ 出池 + ⟦ev⟧settled 驻留；回合内 → ⟦ev⟧done 立即冻结
+    // （条目留池——done-in-pool 统一表示——回合尾 collectSettledAsync 注入）。
+    // consult 族恒停靠（settle 即出会话池入 pending——无 TUI 冻结事件——子块各自冻结）。
+    if (parent._suspended || role === "consult") {
+      parkAsyncPending(parent, entry)
+      pool?.delete(String(entry.id))
+      ctx?.callbacks?.onToken?.(`${entry.relayPrefix}⟦ev⟧settled\x1e0\x1e0\x1esettled\x1e`)
+    } else {
+      ctx?.callbacks?.onToken?.(`${entry.relayPrefix}⟦ev⟧done\x1e0\x1e0\x1edone\x1e`)
+    }
+  }
+  // ④ 公共尾部：settleSeq 递增 + _settle 唤醒（never rejects）+ 唤醒挂起驱动 waiter
+  entry._settleSeq = (parent._asyncSettleSeq = (parent._asyncSettleSeq ?? 0) + 1)
+  entry._settle?.()
+  for (const w of parent._asyncWaiters?.splice(0) ?? []) { try { w() } catch { /* noop */ } }
+  // §20 D-SD4 释放点：settle/cancel 释放槽 + 依赖终态转移 → 补位（依赖满足者/域冲突
+  // 解除者自动启动——槽 ≤4）→ 排队态面板刷新（等待块头标注随终态更新——dependency
+  // cancelled / 位置前移）。subagent/escalate 族恒补（旧行为零回归——cancelled 分支
+  // 同样补位）；advisor（独立评审池——无队列）/consult（会话池）豁免。
+  if (role !== "advisor" && role !== "consult") {
+    maybeRefillAsync(parent)
+    refreshQueuedTokens(parent, ctx?.callbacks?.onToken)
+  }
+}