thincoder 0.12.61 → 0.12.63

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,191 +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 ───────────────────────────────────────────────────
-
-/**
- * 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)
-  }
-}

package/src/agent-tools/batch-segment.mjs

@@ -1,195 +0,0 @@
-/**
- * agent-tools/batch-segment.mjs — 批次档段写入工具（ENGINEERING-MODE.md §2.20 · FR22 F1-F7）。
- *
- * 规则、守卫与 fail-closed 清单的**权威正文在 §2.20.1**（本文件不重述——D2 单一权威源）；
- * 实现要点（正文未定死、由代码承载）：
- *  - 身份判据 = 评审实例绑定（`review` 形态）/ `agent._role`；
- *  - append-only：在段尾（下一条 `## §N` 或 EOF）插入，既有行字节不变；
- *  - 来源戳 `### 轮次 N（评审子代理）`（仅 §3）——N = §3 内该形态行计数 + 1，**调用方自带**
- *    的同名标题行被丢弃（否则伪造戳会污染 N 计数——§2.20.8 #5）；
- *  - 凭证剥除：含凭证形态的行剥掉该子串，剥后为空则整行丢弃（「零命中」+「其余逐字保留」）；
- *  - 路径门禁：`resolveBatchDocPath`（评审侧「若传则须可读」）；工具内再查一次可读性。
- *
- * 导出面：`batchSegmentTool` · `resolveBatchDocPath` · `batchDocForReview`（异步评审实例键取绑定）。
- */
-import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs"
-import { resolve } from "node:path"
-
-/** text 单次上限（§2.20.1——超出引导分段追加，不承诺"不新盖戳"）。 */
-export const MAX_TEXT_CHARS = 20000
-/** 身份 → 可写段号（§2.20.1 段白名单）。 */
-export const SEGMENT_BY_ROLE = { "eng-designer": 2, "eng-coder": 5 }
-/** 工具写入的轮次节标题形态（N 计数口径 = 该形态行；`### 轮次与发现（…）` 骨架行不匹配）。 */
-const ROUND_HEADING_RE = /^### 轮次 \d+（评审子代理）/
-/** 段标题定位（`## §N` 独立标题——`## §20` 不误命中 §2）。 */
-const sectionHeaderRe = (seg) => new RegExp(`^## §${seg}(?=\\s|$)`, "m")
-/** 凭证形态（§2.7 冒号态）：`[DESIGN-TOKEN:…]` 与 `designId: …`——本节自有正则。 */
-const CRED_RE = /\[DESIGN-TOKEN:[^\]]*\]|designId\s*:\s*\S+/g
-const CRED_TEST_RE = /\[DESIGN-TOKEN:[^\]]*\]|designId\s*:\s*\S+/
-
-/** 可读文件判据（存在且为文件——目录/缺失同判不可读）。 */
-function readableFile(abs) {
-  try { return existsSync(abs) && statSync(abs).isFile() } catch { return false }
-}
-
-/**
- * 批次档路径门禁（评审侧 §2.20.2 口径 = **「若传则须可读」**）：空/非字符串/不可读 → throw。
- * 非空且可读 → 返回绝对路径（`\` 归一——照 `files`/`batchDoc` spawn 门先例）。
- */
-export function resolveBatchDocPath(cwd, given) {
-  const raw = typeof given === "string" ? given.trim() : ""
-  if (!raw) {
-    throw new Error("batchDoc must be a non-empty path to the batch record (ENGINEERING-MODE.md §2.20.2) — pass the batch record currently in flight, or omit the parameter entirely when no batch record is in flight.")
-  }
-  const abs = resolve(cwd ?? process.cwd(), raw.replace(/\\/g, "/"))
-  if (!readableFile(abs)) {
-    throw new Error(`batchDoc is not a readable file: ${raw} — pass the path of the batch record currently in flight (a path that resolves to an existing file), or omit the parameter when no batch record is in flight.`)
-  }
-  return abs
-}
-
-/**
- * 设计评审的实例绑定解析（§2.20.2/§2.20.3——batch_segment 的唯一路径来源）：
- *  - 同步路径：调用方（advisor 工具）把实例绑定显式放进 callbacks（**带 batchDoc 键**，
- *    未绑定即 null）——以此为准，不再回看池条目（防同步/异步混跑时串档）；
- *  - 异步路径：本评审所在**池条目**的 `run.batchDoc`（文档集 = 实例键，各评审各取各条）。
- */
-export function batchDocForReview(agent, documents, callbacks = null) {
-  if (callbacks && "batchDoc" in callbacks) return callbacks.batchDoc ?? null
-  const key = JSON.stringify([...(documents ?? [])].sort())
-  for (const e of agent?._asyncAdvisors?.values?.() ?? []) {
-    if (e.status === "running" && e.reviewType === "design" && JSON.stringify([...(e.documents ?? [])].sort()) === key) {
-      return e.run?.batchDoc ?? null
-    }
-  }
-  return null
-}
-
-/** 段号解析：`§2` / `2` / `§2 批次任务` 均可；无法解析 → null。 */
-function segmentNumber(raw) {
-  const m = /^§?\s*(\d+)/.exec(String(raw ?? "").trim())
-  return m ? Number(m[1]) : null
-}
-
-/** 身份 → 可写段号；无写权身份 → null。评审实例绑定优先（评审者的身份即"设计评审"。） */
-function allowedSegment(agent, review) {
-  if (review) return 3
-  return SEGMENT_BY_ROLE[agent?._role] ?? null
-}
-
-/**
- * 凭证剥除 + 伪造轮次标题丢弃（§2.20.1 F6/AC30/AC34）。
- * 逐行处理：含凭证形态的行 → 剥除该子串，剥后为空则整行丢弃（其余内容逐字保留）。
- * `dropStamp`（仅 §3 目标段）：调用方自带的 `### 轮次 N（评审子代理）` 行被丢弃——
- * 工具生成才是唯一来源戳（否则伪造戳会污染 N 计数）。
- */
-function sanitizeText(text, dropStamp) {
-  const kept = []
-  for (const line of text.replace(/\r\n?/g, "\n").split("\n")) {
-    if (dropStamp && ROUND_HEADING_RE.test(line)) continue
-    if (!CRED_TEST_RE.test(line)) { kept.push(line); continue }
-    const cleaned = line.replace(CRED_RE, "").replace(/[ \t]+$/, "")
-    if (cleaned.trim()) kept.push(cleaned)
-  }
-  return kept.join("\n")
-}
-
-/** §3 内工具写入的轮次行计数（N = 计数 + 1；收窄口径——只数工具戳形态）。 */
-function roundCount(src, headerMatch, endIdx) {
-  const body = src.slice(headerMatch.index + headerMatch[0].length, endIdx)
-  return body.split("\n").filter((l) => ROUND_HEADING_RE.test(l)).length
-}
-
-/** 段尾定位 + 插入（append-only：只在段尾插入，既有字节不变；返回新全文 + 本轮 N）。 */
-function insertIntoSection(src, seg, text) {
-  const hdr = sectionHeaderRe(seg).exec(src)
-  if (!hdr) {
-    throw new Error(`batch_segment: the bound batch record has no "## §${seg}" section header — the six-section skeleton is written by the record's creator before any segment write (§1.12). Fix: ask the parent/creator to add the "## §${seg} …" heading (with the template's sub-headings) first, then call batch_segment again. Nothing was written.`)
-  }
-  const nextRe = /^## §\d/gm
-  nextRe.lastIndex = hdr.index + hdr[0].length
-  const next = nextRe.exec(src)
-  const endIdx = next ? next.index : src.length
-  // 来源戳（仅 §3）：工具生成标题 + N——调用方写不进自己的标题（sanitize 已丢弃同名行）。
-  const roundN = seg === 3 ? roundCount(src, hdr, endIdx) + 1 : 0
-  const payload = (seg === 3 ? `### 轮次 ${roundN}（评审子代理）\n\n` : "") + text
-  const before = src.slice(0, endIdx)
-  const after = src.slice(endIdx)
-  const eol = src.includes("\r\n") ? "\r\n" : "\n"
-  const lead = before === "" ? "" : before.endsWith(eol + eol) ? "" : before.endsWith(eol) ? eol : eol + eol
-  // 尾随 eol 恒加（块自成行）；后面还有段标题时再补一个空行（保持模板的空行分隔）。
-  const written = before + lead + payload.replaceAll("\n", eol) + eol + (after === "" ? "" : eol) + after
-  return { written, roundN }
-}
-
-/**
- * 批次档段写入工具工厂。
- * @param {string|null} batchDoc — 绑定的目标档（spawn：`child._batchDoc`；评审：实例键）
- * @param {{review?: boolean}} [opts] — review=true 表示"设计评审实例"形态（写 §3 + 工具盖戳）
- */
-export function batchSegmentTool(batchDoc = null, { review = false } = {}) {
-  const own = review ? "§3" : null
-  return {
-    name: "batch_segment",
-    description:
-      "Append your own section of the batch record (ENGINEERING-MODE.md §2.20 — 一段一作者). " +
-      "There is NO path parameter: the target record is bound to you (at spawn for eng-designer/eng-coder, per review instance for a design review) and your identity fixes the section you may write " +
-      "(eng-designer → §2, design review → §3, eng-coder → §5) — a write outside your own section is refused. " +
-      "Append-only: the text lands at the end of your section; existing lines are never rewritten or deleted. " +
-      "Credential values are stripped mechanically before writing (never write a token or designId value — §2.7). " +
-      "A design review's append is stamped by the tool with a `### 轮次 N（评审子代理）` heading — N is tool-counted; do not write your own heading (it would be dropped). " +
-      "Failures are hard and visible (no silent fallback): if the write is refused or fails, say so in your report — “§× 未写入”.",
-    parameters: {
-      type: "object",
-      properties: {
-        segment: {
-          type: "string",
-          description: `The batch-record section you are writing${own ? ` — yours is ${own}` : ""}. Declares the section number only; your identity decides what is actually writable (§2.20.1).`,
-        },
-        text: {
-          type: "string",
-          description: "The markdown to append (verbatim — findings table + VERDICT + counts for a design review §3). Limit 20000 characters per call; longer content is refused — split it into multiple calls (each call becomes its own section, N continues).",
-        },
-      },
-      required: ["segment", "text"],
-    },
-    async execute(args, ctx) {
-      const agent = ctx?.agent ?? {}
-      const seg = allowedSegment(agent, review)
-      if (seg === null) {
-        throw new Error("batch_segment: no segment is writable by this caller — the channel exists for eng-designer (§2), eng-coder (§5) and design reviews bound to a batch record (§3); the parent agent writes §1/§4/§6 through ordinary document writes (ENGINEERING-MODE.md §2.20.1/§2.20.3).")
-      }
-      const n = segmentNumber(args?.segment)
-      if (n === null) {
-        throw new Error(`batch_segment: unknown segment ${JSON.stringify(args?.segment ?? null)} — pass the section number you write (e.g. "§${seg}").`)
-      }
-      if (n !== seg) {
-        throw new Error(`batch_segment: §${n} is not yours to write — this caller writes §${seg} only (一段一作者: eng-designer → §2, design review → §3, eng-coder → §5; ENGINEERING-MODE.md §2.20.1).`)
-      }
-      if (!batchDoc) {
-        throw new Error("batch_segment: no batch record is bound to this caller — there is no path parameter by design (the target arrives via the spawn binding / the review instance key, ENGINEERING-MODE.md §2.20.2). Report the section as not written.")
-      }
-      const abs = resolve(agent.cwd ?? process.cwd(), String(batchDoc).replace(/\\/g, "/"))
-      if (!readableFile(abs)) {
-        throw new Error(`batch_segment: the bound batch record is not a readable file: ${abs} — nothing was written (§2.20.1 fail-closed). Check the record still exists, then report the section as not written.`)
-      }
-      if (typeof args?.text !== "string") {
-        throw new Error("batch_segment: text must be a string (the markdown to append).")
-      }
-      if (args.text.length > MAX_TEXT_CHARS) {
-        throw new Error(`batch_segment: text is ${args.text.length} characters — the limit is ${MAX_TEXT_CHARS} per call. Split it into multiple calls: each call becomes its own section and the round number N continues (分段追加——每次调用各成节、N 顺延; ENGINEERING-MODE.md §2.20.1).`)
-      }
-      if (/^## §\d/m.test(args.text)) {
-        throw new Error("batch_segment: the text contains a section header line matching `^## §N` — that would break section location and the append-only guarantee. Rewrite it (escape the heading, or drop the leading `## §N`), then call again (§2.20.1 骨架保护). Nothing was written.")
-      }
-      const body = sanitizeText(args.text, seg === 3).replace(/^\n+/, "").replace(/\s+$/, "")
-      if (!body.trim()) {
-        throw new Error("batch_segment: nothing to append — the text is empty after credential stripping (credential values never reach the record; ENGINEERING-MODE.md §2.7/§2.20.1).")
-      }
-      const src = readFileSync(abs, "utf8")
-      const { written, roundN } = insertIntoSection(src, seg, body)
-      writeFileSync(abs, written)
-      return `batch_segment: appended ${body.length} characters to §${seg} of the batch record${roundN ? ` (### 轮次 ${roundN}（评审子代理）)` : ""}.`
-    },
-  }
-}