thincoder 0.12.62 → 0.12.64

package/src/agent-tools/advisor.mjs

@@ -1,260 +0,0 @@
-/**
- * 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 { 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"
-
-// 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",
-  description:
-    "Run an independent review on your work. " +
-    "Use type='design' to review design documents before implementation — pass documents=[...] with the explicit list of doc paths to review; use documents in code review too (the task's Docs involved list). " +
-    "Use type='code' (default) to review code changes after implementation — pass paths=[...] to specify which files or directories to review, or documents=[...] for acceptance criteria context. " +
-    "The advisor is an independent read-only sub-agent that explores the codebase, " +
-    "reads files, and traces callers via grep/lsp. " +
-    "For code review: round 1 does a full review, round 2 verifies the agent's fix claims, " +
-    "round 3+ strictly checks only the fix claims — convergence, not divergence. " +
-    "For design review: single-pass review against methodology and requirements. " +
-    "Review criteria come from .thincoder/advisor.md (if present) or sensible defaults. " +
-    "After the review, you MUST produce a response table (see discipline rules for format). " +
-    "If advisor says all clear, call verify. " +
-    "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: {
-          type: { type: "string", description: "Review type as declared by the caller (design/code)" },
-          target: { type: "string", description: "Review target — document + section, or file(s)" },
-          status: { type: "string", description: "Object state: 待评审 / 已批准 / 已实现 (pending-review / approved / implemented)" },
-          reason: { type: "string", description: "Why this review runs: user-initiated / delivery verification" },
-          exclude: { type: "string", description: "Explicit exclusion list — approved/implemented items NOT in this review" },
-        },
-        description: "Review-object declaration (§18.8): mechanically injected at the start of the review user message so the advisor does not re-derive the review target. Absent → no injection (legacy behavior).",
-      },
-      paths: {
-        type: "array",
-        items: { type: "string" },
-        description: "Code files or directories to review (for code review). Required unless documents is provided. The advisor reads the files/directories listed here — it has no git tool and never inspects diffs.",
-      },
-      documents: {
-        type: "array",
-        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,
-  sideEffectExempt: true,
-  outputPanel: true,
-  async execute(args, ctx) {
-    const agent = ctx.agent
-    const reviewType = args.type || "code"
-    const documents = args.documents || null
-    // Review-object declaration (§18.8 D-OA3): the PARENT constructs it and the
-    // advisor tool passes it through — mechanical anchoring, not model inference.
-    // Any non-object value (string/array/primitive, possibly from a malformed
-    // tool call) degrades to null = no injection (legacy calls unchanged).
-    const reviewObject = args.object && typeof args.object === "object" && !Array.isArray(args.object)
-      ? args.object
-      : null
-    // Scope fallback: the runtime mutation record (zero git) covers guard-triggered
-    // reviews where the model did not pass explicit paths.
-    const paths = args.paths || (agent._touchedFiles?.length ? [...agent._touchedFiles] : null)
-
-    // 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: 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 conv = loadConventions(agent.cwd)
-      const invalidDocs = documents.filter((doc) => !isDocPath(doc, conv))
-      if (invalidDocs.length > 0) {
-        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(", ")}`
-      }
-    }
-
-    // §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.)
-
-    // 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" ? 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,
-      // 同步路径的实例绑定传递（异步路径由池条目 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") {
-      // Design pass/fail settlement — token echo IS the verdict (prompt-enforced);
-      // no findings-table heuristics: a design with issues never carries the token.
-      // (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

@@ -1,204 +0,0 @@
-/**
- * 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 ───────────────────────────────────────────────────
-
-/**
- * §23.3.1 消化窗口持有释放（TUI-OOM-ROOTCAUSE——D-SM2 表 2 候选 1）：注入完成后置空条目
- * 对子代理对象的引用（`childAgent`/`report`——条目前此从不显式释放，挂起期 = 分钟级驻留）。
- * 幂等（重入不抛）；池内/挂起未消化窗口语义零变（settle 时刻不释放——表 2 候选 2 否决：
- * status/observe 在窗口内仍读 child 摘要）。三消费点（回合尾收集 / run 起始 pending 注入 /
- * 挂起残差注入）在注入完成后调本 helper。
- */
-export function releaseSettledEntry(entry) {
-  if (!entry || typeof entry !== "object") return
-  entry.childAgent = null
-  entry.report = null
-}
-
-/**
- * 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)
-  }
-}