thincoder 0.12.59 → 0.12.61

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

@@ -0,0 +1,346 @@
+/**
+ * advisor-async.mjs — async advisor reviews (AGENT-LOOP.md §11.2 — R13, 2026-09-06).
+ *
+ * The advisor tool runs reviews in a background pool at depth 0 (default async —
+ * ruling ②-3 A): the launch returns an ack, the turn ends naturally, the session
+ * suspends, the review settles into _pendingAsyncResults and a digest turn
+ * delivers the report (§17 consumption machinery — role-agnostic; entries carry
+ * role "advisor" and ride the subagent panel as a pseudo-role, ruling ②-4 A).
+ *
+ * This module owns:
+ *  1. the per-review INSTANCE registry (agent._advisorRuns — ruling ②-5 A:
+ *     Map<reviewId, {reviewType, round, priorOutput, stale, open, docSetKey,
+ *     designId}>) — the 5-round convergence cap is PER REVIEW (fix #4), no longer
+ *     a run-global shared budget (design + code used to share _advisorRound);
+ *  2. launch resolution: design reviews continue the instance of the same
+ *     document set (reviewId = the designId minted at the instance's first
+ *     launch); code reviews continue the newest OPEN code instance (round 2+ of
+ *     a fix loop) and CLOSE at normal user-run ends once no review is in flight
+ *     (a converged/abandoned thread must not burn the cap of later tasks);
+ *  3. the async pool (agent._asyncAdvisors — ADVISOR_POOL_LIMIT = 4 default,
+ *     agent.poolLimits.advisor configurable — POOL-CONFIG-UNIFIED; over-limit and
+ *     same-scope-running launches are refused at once — never queued (②-6a; F-5);
+ *     cancel (ruling ②-6b — directed abort → cancelled settle: no
+ *     pending entry, no token, a "评审已取消——token 未签发" reminder);
+ *  4. SETTLE accounting (fixes #2/#4 — moved from the tool-result commit): a
+ *     review whose targets mutated after launch settles STALE — it marks no
+ *     _calledAdvisorThisRun and issues no token (the guard pushes back); a
+ *     non-stale code review marks _calledAdvisorThisRun; a passing design review
+ *     issues its token under the designId slot at settle time.
+ *     2026-09-11 第 11 批拆分：settle 记账 + 变更日志 + 陈旧/冻结判定迁 `advisor-settle.mjs`
+ *     （本文件 500 行 = 硬帽在册）；既有 import 面经本文件 re-export 保持不变。
+ *
+ * The sync path (depth>0 eng-coder self-review / explicit async:false) reuses
+ * the same instance resolution (rounds/prior/cap) — its accounting still lands
+ * in recordToolResults (agent.mjs run loop), marker-keyed by toolCall id.
+ */
+import { randomUUID } from "node:crypto"
+// design-token 工具组（2026-09-08 自本文件迁至 design-token.mjs——再越 500 行硬限）——
+// 既有 import 面（advisor.mjs / 测试）不变：原导出全部经此 re-export 保留。
+export {
+  buildApprovedSuffix, stripApprovedSuffix, effectiveTokenTtlMs, generateDesignToken,
+  validateDesignToken, makeDesignTokenRegex, settleDesignReview,
+} from "./design-token.mjs"
+// 第 11 批拆分（2026-09-11）：settle 记账 + 变更日志（noteMutations）+ 陈旧判定
+// （reviewIsStale）+ 冻结冲突（inflightDesignReviewConflict）迁 advisor-settle.mjs——
+// 既有 import 面（dispatch / subagent-async / escalate-async / 测试）经此 re-export 不变。
+import { normAbs, mutationSeqOf, settleAdvisorRun } from "./advisor-settle.mjs"
+export {
+  mutationSeqOf, noteMutations, reviewIsStale, settleAdvisorRun, inflightDesignReviewConflict,
+} from "./advisor-settle.mjs"
+// 第 33 批（§17.5）：doc-set 键迁 `review-streak.mjs`（护栏与实例续跑同锚单源；原为私有
+// ——零 import 面）。本文件继续在实例解析 / 池 entries 上消费它。
+import { docSetKey } from "./review-streak.mjs"
+import { runAdvisorReview, resolveAdvisorProvider, ADVISOR_THINKING_PLACEHOLDER } from "../advisor/run.mjs"
+import { stripEventToken } from "../agent/spawn-child.mjs"
+import { logEvent } from "../log.mjs"
+import { deathLine } from "../abort-provenance.mjs"
+// ASYNC-RESULT-CONTAINER.md D3/D6：settle 公共收尾单点 + child signal 构建单点
+import { buildChildSignal, settleAsyncEntry } from "./async-settle.mjs"
+import { nextSubagentId } from "./subagent-scheduler.mjs"
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Review-instance registry (agent._advisorRuns — per-review rounds/prior/cap)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export function advisorRuns(agent) {
+  if (!(agent._advisorRuns instanceof Map)) agent._advisorRuns = new Map()
+  return agent._advisorRuns
+}
+
+/** The newest OPEN code instance (the thread a fix-round launch continues), or null. */
+export function openCodeRun(agent) {
+  const runs = agent?._advisorRuns
+  if (!(runs instanceof Map) || runs.size === 0) return null
+  for (const r of [...runs.values()].reverse()) {
+    if (r.reviewType === "code" && r.open) return r
+  }
+  return null
+}
+
+/** The newest OPEN design instance for the given document set, or null. */
+function openDesignRun(agent, key) {
+  const runs = agent?._advisorRuns
+  if (!(runs instanceof Map) || runs.size === 0) return null
+  for (const r of [...runs.values()].reverse()) {
+    if (r.reviewType === "design" && r.open && r.docSetKey === key) return r
+  }
+  return null
+}
+
+/**
+ * Resolve the review instance a launch continues (§11.2 ③ — per-review
+ * rounds/prior; reviewId = designId for design reviews, a random id for code).
+ *  - design: continue the OPEN instance of the same document set (fix rounds of
+ *    a review thread keep its designId and its round/prior); none → new instance.
+ *  - code: continue the newest OPEN code instance (guard-driven fix loops);
+ *    none → new instance.
+ * The legacy agent._advisorRound/_lastAdvisorOutput fields are SCOPED to the
+ * instance before the launch (message building + the run.mjs cap read them) —
+ * prior-less continuation degrades to round 1 semantics (fresh full review).
+ * @returns {{run: object, isNew: boolean, reviewId: string, designId: string|null}}
+ */
+export function resolveAdvisorLaunch(agent, reviewType, { documents = null } = {}) {
+  const runs = advisorRuns(agent)
+  let run = null
+  if (reviewType === "design") {
+    const key = docSetKey(documents, agent.cwd)
+    run = openDesignRun(agent, key)
+    if (!run) {
+      const reviewId = randomUUID()
+      // F2h (§29.1 2026-09-07): a same-scope re-review reuses the session's
+      // designId for this doc-set (any prior instance of the scope — open OR
+      // closed — the newest wins). A passed re-review overwrites the slot under
+      // the same id (no slot residue — T14: the old token is then rejected at
+      // the gate); old slots die at TTL only, kept as the fail-safe fallback.
+      const prior = [...runs.values()].reverse().find((r) => r.reviewType === "design" && r.docSetKey === key)
+      run = {
+        reviewId, reviewType, designId: prior?.designId ?? reviewId,
+        round: 0, priorOutput: null, stale: false, open: true, docSetKey: key,
+      }
+      runs.set(reviewId, run)
+    }
+  } else {
+    run = openCodeRun(agent)
+    if (!run) {
+      const reviewId = randomUUID()
+      run = {
+        reviewId, reviewType, designId: null,
+        round: 0, priorOutput: null, stale: false, open: true, docSetKey: null,
+      }
+      runs.set(reviewId, run)
+    }
+  }
+  // Scope the legacy mirror fields (message builder + run.mjs cap + displays).
+  agent._advisorRound = run.priorOutput ? run.round : 0
+  agent._lastAdvisorOutput = run.priorOutput
+  return { run, isNew: run.round === 0 && !run.priorOutput, reviewId: run.reviewId, designId: run.designId }
+}
+
+/** Guard round — the OPEN CODE instance only (2026-09-07 §8 F2): the design-written
+ *  mirror never gates the code guard — no open code instance → 0. */
+export function effectiveAdvisorRound(agent) {
+  return openCodeRun(agent)?.round ?? 0
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Async pool (agent._asyncAdvisors — pool 上限 F-1/F-2:常量 = 运行时回退权威(2 → 4),
+// config.mjs DEFAULTS.agent.poolLimits.advisor = config 层镜像——耦合锁 config-pool
+// .test.mjs 逐键断言——勿单侧改默认)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export const ADVISOR_POOL_LIMIT = 4
+
+/** §11.2 advisor 池生效上限（纯——读 agent.poolLimits.advisor——合法 ≥1 整数生效——
+ *  非法/缺省回退 ADVISOR_POOL_LIMIT——与 subagent 域 resolvePoolLimits 独立不共享
+ *  （subagent 两键表不含本键——键表语义不同——POOL-CONFIG-UNIFIED F-2））。 */
+export function resolveAdvisorPoolLimit(raw) {
+  const v = raw?.advisor
+  return Number.isInteger(v) && v >= 1 ? v : ADVISOR_POOL_LIMIT
+}
+
+/** launch 判定点每次读 agent.config（/config 热应用——变更即生效下个 launch——文案
+ *  如实报本值）。 */
+export function advisorPoolLimitFor(agent) {
+  return resolveAdvisorPoolLimit(agent?.config?.agent?.poolLimits)
+}
+/** §11.2 同 scope 守卫（F-5——用户裁①）：同 reviewType+scope 有 running 评审 → true
+ *  （拒——running 并行多实例歧义放大——settled 续跑语义不变）。design scope = 文档集键
+ *  （docSetKey）；code = 单 code 线程（记录不记路径键——与 openCodeRun 语义一致）。
+ *  与池容量守卫独立：容量 = 全局 ≤N——scope = 同 scope ≤1——两关都过才启动。 */
+export function runningAdvisorOfScope(agent, reviewType, docSetKey) {
+  const pool = agent?._asyncAdvisors
+  if (!(pool instanceof Map)) return false
+  for (const e of pool.values()) {
+    if (e.status !== "running" || e.reviewType !== reviewType) continue
+    if (reviewType === "design" && e.run?.docSetKey !== docSetKey) continue
+    return true
+  }
+  return false
+}
+
+export function runningAdvisorCount(agent) {
+  return [...(agent?._asyncAdvisors?.values() ?? [])].filter((e) => e.status === "running").length
+}
+
+/** Any in-flight (non-done) async advisor review? — the completion guard skips
+ *  its push-back while a review is pending (T-24b4: 未决不算未评审). */
+export function advisorReviewPending(agent) {
+  return [...(agent?._asyncAdvisors?.values() ?? [])].some((e) => !e.done)
+}
+
+/** Directed cancel (ruling ②-6b — ⏹/cancel): abort the running review's
+ *  controller (run.mjs signal chain) → the settle callback runs the cancelled
+ *  branch (no pending entry / no token / "评审已取消——token 未签发" reminder). */
+export function cancelAsyncAdvisor(agent, id) {
+  const key = String(id)
+  const map = agent?._asyncAdvisors ?? new Map()
+  const entry = map.get(key)
+  if (!entry) {
+    return { id: key, status: "error", error: `unknown async advisor review id: ${key}` }
+  }
+  if (entry.done) {
+    return { id: key, status: "error", error: `async advisor review #${key} has already finished — nothing to cancel` }
+  }
+  if (entry.cancelled) return { id: key, status: "cancelled" } // abort already in flight — idempotent
+  entry.cancelled = true
+  // §20.3 站点 #11（第 24 批）：定向中止 = cancel（reason 载荷）
+  entry.controller?.abort?.({ abortTrigger: "cancel", abortDetail: "advisor-cancel" })
+  return { id: key, status: "cancelled" }
+}
+
+/** Relay an advisor onOutput chunk into the subagent block channel (`advisor#N/`
+ *  prefix — kind-preserving: think via onReasoning, tool via onToolOutput, text
+ *  via onToken; the wait placeholder is stripped — it is a live indicator, not
+ *  content, and the sync path strips it at freeze too). */
+function relayAdvisorOutput(callbacks, prefix, chunk) {
+  if (!callbacks) return
+  const kind = typeof chunk === "string" ? "text" : (chunk?.kind ?? "text")
+  const text = typeof chunk === "string" ? chunk : String(chunk?.text ?? "")
+  if (!text) return
+  if (kind === "think") {
+    callbacks.onReasoning?.(prefix + text.replaceAll(ADVISOR_THINKING_PLACEHOLDER, ""))
+  } else if (kind === "tool") {
+    callbacks.onToolOutput?.(prefix + "tool", { kind: "tool", text })
+  } else {
+    callbacks.onToken?.(prefix + stripEventToken(text))
+  }
+}
+
+/**
+ * Launch an async advisor review (pool entry + background runner + settle
+ * wiring — mirrors subagent-run.mjs's lifecycle, minus queueing/scheduler).
+ * The runner wraps runAdvisorReview (promise → report/error) — the subagent
+ * pipeline is untouched (ruling ②-2 A). The entry carries role "advisor" so the
+ * digest/panel/freeze consumers route it like any other settled block.
+ * @returns {{ok: true, id: string}} — ack; or {{error: string}} — scope guard
+ *   (same reviewType+scope running — §11.2 F-5) or pool full (the effective
+ *   agent.poolLimits.advisor limit, never queued) or invalid ctx.
+ */
+export function launchAsyncAdvisor(parent, ctx, launch) {
+  const { reviewType, documents, paths, object, designToken, designId, run } = launch
+  const limit = advisorPoolLimitFor(parent)
+  // §11.2 same-scope guard（F-5——用户裁①）：同 type+scope 有 running → 拒——与池容量
+  // 守卫独立两关都过才启动——不等不排（②-6a 无排队语义保持——settled 续跑不变）。
+  if (runningAdvisorOfScope(parent, reviewType, run?.docSetKey ?? null)) {
+    const scopeNote = reviewType === "design"
+      ? "a design review of this document set is still running"
+      : "a code review is still running (code reviews are a single thread — launch the next one after it settles)"
+    return { error: `Advisor: 此 scope 已有评审在跑——settle 后逐个发起 — ${scopeNote}; round/prior continuation would be ambiguous while it is in flight — wait for it to settle, then launch the next review (AGENT-LOOP.md §11.2).` }
+  }
+  if (runningAdvisorCount(parent) >= limit) {
+    return { error: `Advisor: 另有一评审在跑——逐个发起 — another review is already running in the background pool (${limit} reviews at most — agent.poolLimits.advisor, default ${ADVISOR_POOL_LIMIT}); launch them one at a time (AGENT-LOOP.md §11.2 ruling ②-6a).` }
+  }
+  parent._asyncAdvisors ??= new Map()
+  // SUBAGENT-ID-COUNTER-AGENT（2026-09-09）：取号统一走 nextSubagentId——池活续号兜底 + 跨池共号（§11.2）。
+  const id = nextSubagentId(parent)
+  const entry = {
+    id, role: "advisor", reviewType, run,
+    reviewId: run.reviewId, designId, designToken, documents, paths, object,
+    launchSeq: mutationSeqOf(parent),
+    docAbs: reviewType === "design" && Array.isArray(documents)
+      ? documents.filter((d) => typeof d === "string").map((d) => normAbs(d, parent.cwd))
+      : [],
+    relayPrefix: `advisor#${id}/`,
+    status: "running", position: undefined,
+    report: null, error: null, done: false, cancelled: false,
+    promise: null, _settle: null,
+    model: (() => { try { return resolveAdvisorProvider(parent).model ?? null } catch { return null } })(),
+    startedAt: Date.now(), turn: 0, maxTurns: 0,
+    controller: null,
+  }
+  // Entry controller chained to the session/run base signal (subagent-run parity):
+  // Ctrl+C / session abort propagates into the review's chat; a digest's own
+  // Ctrl+I must not orphan it (children hold the session signal while suspended).
+  // D6 buildChildSignal 单点（ASYNC-RESULT-CONTAINER.md）。
+  const ctrl = new AbortController()
+  entry.controller = ctrl
+  const baseSignal = buildChildSignal(parent, ctx)
+  if (baseSignal) {
+    // §20.3 站点 #10（第 24 批）：hop 逐跳保 reason
+    if (baseSignal.aborted) ctrl.abort(baseSignal.reason)
+    else baseSignal.addEventListener("abort", () => ctrl.abort(baseSignal.reason), { once: true })
+  }
+  entry.promise = new Promise((res) => { entry._settle = res })
+  entry.start = () => {
+    entry.startedAt = Date.now()
+    // Async mark + [model] — the TUI block opens at ACTUAL start (⏹ gating reads it).
+    ctx?.callbacks?.onToken?.(entry.relayPrefix + "⟦ev⟧async\x1e")
+    ctx?.callbacks?.onToken?.(entry.relayPrefix + "[model]" + (entry.model ?? ""))
+    runAdvisorReview(parent, reviewType, {
+      onOutput: (chunk) => relayAdvisorOutput(ctx?.callbacks, entry.relayPrefix, chunk),
+      signal: entry.controller.signal,
+    }, designToken, documents, paths, object, designId)
+      .then((report) => { entry.report = report })
+      // §20.3 第 3 条合成器（第 24 批）：原 message 前缀逐字保留 + 来源后缀
+      .catch((err) => { entry.error = deathLine(err, entry.controller?.signal) })
+      .finally(() => {
+        // settle 公共收尾单点（ASYNC-RESULT-CONTAINER.md D3——settleAsyncEntry）：日志三连
+        // /cancelled 分支（出池+墓碑+⟦ev⟧stopped+"评审已取消——token 未签发"提醒）/挂起分流
+        // （pending 单容器+出池——统一守卫 !parentAborted——D4）/公共尾部（settleSeq/_settle/
+        // 唤醒 waiter）统一走共享 helper。族特有 hook = settleAdvisorRun 记账（fix #2/#4——
+        // 陈旧判定/轮次/token D1 落盘——settle 分支输出写回 entry.report，digest 原样进）；
+        // cancelled/parent-aborted 不调（不消费预算——settleAdvisorRun 自己的早退语义等价）。
+        settleAsyncEntry(parent, entry, {
+          pool: parent._asyncAdvisors,
+          ctx,
+          onAccounting: () => {
+            const settled = settleAdvisorRun(parent, entry)
+            // §29 fix B：settle 分支输出（清洗/未签发提示）写回 entry.report——digest 原样进。
+            if (settled.report != null) entry.report = settled.report
+          },
+        })
+      })
+  }
+  parent._asyncAdvisors.set(String(id), entry)
+  logEvent("child:spawn", { role: "advisor", id: `advisor#${id}`, kind: "async", status: "running", ms: 0 })
+  entry.start()
+  return { ok: true, id: String(id) }
+}
+
+/**
+ * Close every OPEN code instance at a normal non-auto run end (finalizeAgentTurn)
+ * when no review/child activity remains: a code thread that settled and whose
+ * digest was consumed must not burn the 5-round cap of a later task — the next
+ * code review starts a fresh full review (round 1). Runs that END with a review
+ * or an eng-coder child in flight keep the thread open (fix-round continuation).
+ * @returns {boolean} whether any instance was closed
+ */
+export function closeOpenCodeAdvisorRuns(agent) {
+  const advisors = agent?._asyncAdvisors
+  // Any pooled advisor entry — running OR settled-not-consumed — keeps the
+  // thread open: an in-run settle whose report has not reached the model (the
+  // suspension sweep / digest consumes it next) must still be continuable by
+  // the fix round that follows the disposition.
+  if ((advisors?.size ?? 0) > 0) return false
+  if ((agent?._asyncSubagents?.size ?? 0) > 0) return false
+  if ((agent?._pendingAsyncResults ?? []).some((e) => e.role === "advisor")) return false
+  let closed = false
+  const runs = agent?._advisorRuns
+  if (runs instanceof Map) {
+    for (const r of runs.values()) {
+      if (r.reviewType === "code" && r.open) { r.open = false; closed = true }
+    }
+  }
+  return closed
+}

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

@@ -0,0 +1,231 @@
+/**
+ * advisor-settle.mjs — advisor settle accounting + mutation log + stale / freeze
+ * determination（2026-09-11 第 11 批自 advisor-async.mjs 拆出——500 行 = 硬帽在册，
+ * 任何新增必越；既有 import 面经 advisor-async.mjs **re-export 保持不变**
+ * （noteMutations / mutationSeqOf / reviewIsStale / settleAdvisorRun）。
+ *
+ * 内容 = 迁入（逐字搬移含注释）+ 本批两处接线：
+ *  - `settleAdvisorRun` —— 记账本体零改（轮次 / 陈旧 / token D1 落盘 / prior）；A 族
+ *    未完成判定改用单谓词 `advisorIncompleteMarker`（§14.3 消费点 1/2）：design 结算经
+ *    `settleDesignReview(…, { incomplete })` 未完成即不签发；code 完成守卫同谓词
+ *    （旧 `^` 锚首行失败正则退役——六形态语义零丢，含 review_failed 字符串
+ *    resolve 形态）；
+ *  - `inflightDesignReviewConflict` —— E 族（F17/§14.14）D5 冻结窗口冲突检测：与
+ *    `reviewIsStale` 同族（同 docAbs / 同 normAbs）、仅扫 running 且未取消的设计条目
+ *    （dispatch Phase-1 预闸消费）。
+ *
+ * 第 33 批（2026-09-11——评审失败护栏 §17.5）：`normAbs` 本体迁 `review-streak.mjs`
+ * （原处 re-export 保面）+ design 结算计数接线（分类单源 `designReviewOutcome` →
+ * `noteDesignReviewOutcome`，三出口）——记账本体 / 陈旧判定 / 轮次 / token 落盘零改。
+ */
+import { persistEngTokens } from "../token-ttl.mjs"
+import { settleDesignReview, makeDesignTokenRegex, stripApprovedSuffix } from "./design-token.mjs"
+import { looksLikeReviewOutput, advisorIncompleteMarker, ADVISOR_LAUNCH_REFUSAL_PREFIX } from "../advisor/run.mjs"
+import { isCodePath, loadConventions } from "../conventions.mjs"
+import { logEvent } from "../log.mjs"
+// 第 33 批（§17.5）：`normAbs` 迁 `review-streak.mjs`（中立模块——护栏与陈旧判定共用同一归一）
+// + 结算分类 / 计数落账（异步结算计数点）。
+import { normAbs, designReviewOutcome, noteDesignReviewOutcome } from "./review-streak.mjs"
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Mutation log (stale-review determination — fix #2: FILE_MUTATORS after the
+// review launch make the settle stale: no called-mark, no token, guard re-pushes)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export function mutationSeqOf(agent) {
+  return agent._mutationSeq ?? 0
+}
+
+/** Record a file-mutation commit — bounded ring feeding the stale scan. paths = ABSOLUTE.
+ *  唯一记账点（§29 fix A）：dispatch runOne 写执行成功即刻调用（取代批后段 + 中断分支——
+ *  不双计）；mergeChildMutations（子代理合入）是独立事件面。 */
+export function noteMutations(agent, paths) {
+  const list = (paths ?? []).filter((p) => typeof p === "string" && p.length > 0)
+  if (list.length === 0) return
+  agent._mutationSeq = (agent._mutationSeq ?? 0) + 1
+  const log = agent._mutLog ??= []
+  log.push({ seq: agent._mutationSeq, paths: [...new Set(list)] })
+  if (log.length > 200) log.splice(0, log.length - 200)
+}
+
+// 第 33 批（§17.5）：`normAbs` 本体迁 `review-streak.mjs`；原处 re-export 保既有 import 面
+// （advisor-async / 测试）零变。
+export { normAbs } from "./review-streak.mjs"
+
+/** Stale = a mutation committed after the launch touched the review's face:
+ *  code reviews judge the CODE face; design reviews judge their OWN documents. */
+export function reviewIsStale(agent, entry) {
+  const log = agent?._mutLog
+  if (!Array.isArray(log) || log.length === 0) return false
+  const since = log.filter((m) => m.seq > (entry.launchSeq ?? -1))
+  if (since.length === 0) return false
+  if (entry.reviewType === "design") {
+    const scope = (entry.docAbs ?? []).map((p) => normAbs(p, agent?.cwd))
+    if (scope.length === 0) return false // no explicit doc scope — nothing to judge stale
+    const set = new Set(scope)
+    return since.some((m) => (m.paths ?? []).some((p) => set.has(normAbs(p, agent?.cwd))))
+  }
+  // Code face = the shared classifier (src/conventions.mjs) — one authority with
+  // the design gate and the mutation guard (PORTABILITY FR12 / PO-10).
+  const conv = loadConventions(agent?.cwd)
+  return since.some((m) => (m.paths ?? []).some((p) => isCodePath(normAbs(p, agent?.cwd), conv)))
+}
+
+/**
+ * E 族（F17/§14.14 E-3d）——D5 冻结窗口写前拦截的冲突检测：设计评审**在途**（点火 → 结算）
+ * 期间，父侧对被审文件集（`docAbs` = 声明文档集，含批次档）的写入会被 dispatch 预闸拒绝。
+ * 判据与 `reviewIsStale` **同源**（同一 docAbs / 同一 normAbs）；仅扫 **running 且未取消**
+ * 的设计条目（已结算 / 已取消条目不拦——结算后写不再致 stale、取消的结算早退不判）。
+ * 保守残余（如实注）：回合中止后池清前的窗口可能拒一笔不致 stale 的写（保守方向）。
+ * @param {Object} agent
+ * @param {string[]} absPaths — 本次写将触碰的路径（ABS——调用方 resolve(agent.cwd, p)）
+ * @returns {{id: string, path: string}|null} 命中评审 id + 冲突路径（ABS），无冲突 null
+ */
+export function inflightDesignReviewConflict(agent, absPaths) {
+  const pool = agent?._asyncAdvisors
+  if (!(pool instanceof Map) || pool.size === 0) return null
+  const wanted = (absPaths ?? [])
+    .filter((p) => typeof p === "string" && p.length > 0)
+    .map((p) => normAbs(p, agent?.cwd))
+  if (wanted.length === 0) return null
+  for (const entry of pool.values()) {
+    if (!entry || entry.reviewType !== "design") continue
+    if (entry.status !== "running" || entry.cancelled || entry.done) continue
+    const scope = (entry.docAbs ?? []).map((p) => normAbs(p, agent?.cwd))
+    if (scope.length === 0) continue
+    const set = new Set(scope)
+    for (const p of wanted) if (set.has(p)) return { id: String(entry.id), path: p }
+  }
+  return null
+}
+
+/**
+ * Settle accounting (fix #2/#4 — runs when a non-cancelled review settles,
+ * BEFORE the pending transfer / digest injection):
+ *  1. round++ (attempts count — parity with the legacy _advisorRound++ budget);
+ *  2. stale determination — mutated targets since launch → no called-mark, no token;
+ *  3. non-stale: code review → _calledAdvisorThisRun = true; design review →
+ *     token echo check (settleDesignReview: slot + instance close; single-value
+ *     mirror retired per DESIGN-TOKEN-SETTLEMENT D3) + D1 settle-time slot persist
+ *     (persistEngTokens — write failure = settle failure: no registration, no
+ *     Approved echo, re-review — 评审 #1);
+ *  4. §29 fix B — branch-shaped report output (the caller writes it back to
+ *     entry.report; digest injects the CLEANED form): pass → stripped +
+ *     Approved/designId suffix (sync 参照形态); persist-failed → stripped +
+ *     "D1: …token could NOT be durably written…" re-review notice (no Approved
+ *     suffix — never an unregistered token); stale → echo stripped +
+ *     "评审目标已变更——token 未签发" prefix — never an unregistered token.
+ * 第 11 批增补（A/F11）：`incomplete` = 宿主尾族判定（单谓词）——design 结算未完成即不
+ * 签发（`settleDesignReview` 的 `opts.incomplete`）；code 完成守卫的失败判定改用同谓词
+ * （六形态语义零丢——旧 `^` 锚正则退役）。
+ * 第 33 批增补（§17.5 计数点 1）：design 结算按分类单源（`designReviewOutcome`）落账到
+ * 会话级护栏 `agent._designReviewStreaks`（三出口：非陈旧 / 陈旧 / 无报告）——cancel 早退
+ * 与无实例路径不计（neutral 语义 = 无尝试发生）。
+ * Cancelled / parent-aborted reviews consume nothing (the user dropped the
+ * attempt — the retry must not lose budget).
+ * @returns {{cancelled: boolean, stale: boolean, passed: boolean, report: string|null}}
+ */
+export function settleAdvisorRun(agent, entry) {
+  if (entry.cancelled) return { cancelled: true, stale: false, passed: false, report: null }
+  const run = entry.run
+  if (!run) return { cancelled: false, stale: false, passed: false, report: entry.report ?? null }
+  const result = entry.report ?? null
+  run.round++
+  agent._advisorRound = run.round
+  const stale = reviewIsStale(agent, entry)
+  run.stale = stale
+  let report = result
+  let passed = false
+  let persistFailed = false
+  // 宿主尾族判定（单谓词——design 结算与 code 守卫共用；§14.3 消费点 1/2）。
+  const incomplete = result != null ? advisorIncompleteMarker(String(result)) : null
+  // 启动拒绝报告（未发起请求——无评审产出）：第 33 批上移为本结算段**单点**——消费 = ① design
+  // 失败分类（neutral——无尝试发生，§17.3 #1）② code 守卫 failureVerdict（既有语义零变）。
+  const launchRefused = result != null && String(result).startsWith(ADVISOR_LAUNCH_REFUSAL_PREFIX)
+  if (!stale) {
+    if (run.reviewType === "design" && entry.designToken && result) {
+      // settle 前 Map 快照——落盘失败时回滚用（settle 失败 = 结算未发生，不留半结算态：
+      // 重评覆盖旧槽的边角（F2h 复用 designId）也原样恢复旧 token——内存与盘一致）。
+      const preMap = agent._engDesignTokens instanceof Map
+        ? new Map(agent._engDesignTokens)
+        : null
+      const settled = settleDesignReview(agent, run, entry.designToken, result, { incomplete })
+      if (settled.passed) {
+        // DESIGN-TOKEN-SETTLEMENT D1（2026-09-08）：settle 是唯一结算点——settle 当场
+        // 同步落盘 token 字段到槽文件（persistEngTokens = engTokenSlotFields 序列化 +
+        // session 安全写/轮转——勿裸写文件），不等下个回合尾 saveSession（消除"settle→
+        // 下个 saveSession"间的重启丢 token 窗口）。
+        // 写失败即 settle 失败（评审 #1）：token 不注册（Map 回滚到 settle 前快照）、无
+        // Approved 回显、可重评——不静默吞错、不产生"内存有盘上无"态（宁可结算失败
+        // 可重评，不留半结算态）。
+        let durable = false
+        try {
+          durable = persistEngTokens(agent)
+        } catch (e) {
+          logEvent("advisor:error", { id: `advisor#${entry.id}`, err: `engDesignTokens slot persist threw: ${e?.message ?? String(e)}` })
+        }
+        if (durable) {
+          passed = true
+          report = settled.output
+        } else {
+          if (preMap) agent._engDesignTokens = preMap
+          else delete agent._engDesignTokens
+          run.approvedSuffix = null
+          persistFailed = true
+          logEvent("advisor:error", { id: `advisor#${entry.id}`, err: "engDesignTokens slot persist failed — settle failed (re-review)" })
+          const stripped = String(result)
+            .replace(makeDesignTokenRegex(entry.designToken, "g"), "")
+            .trim()
+          report = `${stripped}\n\nD1: the design review passed but the token could NOT be durably written to the session ledger (slot persist failed) — re-run advisor(type='design') to re-issue; no eng-coder spawn is authorized for this review (评审通过但 token 未能持久化——需重评).`.trim()
+        }
+      } else {
+        report = settled.output
+      }
+    }
+    // A completed review covers the code face ONLY when it actually produced a
+    // verdict: a mechanical-failure settle ("Advisor: review failed/timeout/…" —
+    // run.mjs resolves with the failure text, it never throws) must not satisfy
+    // the guard silently — the digest shows the failure and the guard pushes
+    // back for a retry (fix #2 anti-silent-skip intent; attempts still consume
+    // the per-review round budget, so repeated failures stay bounded by the
+    // cap). An error settle (rejection path — report null with an error) has no
+    // verdict either — same exclusion (advisor 复评补边). Design reviews keep
+    // the mark on any completed verdict (parity with the sync recordToolResults
+    // mark — they have no code face to cover) — EXCEPT a launch-refusal report
+    // (nothing was sent, no verdict at all: see launchRefused below).
+    // 第 11 批（F16/A3）：失败判定 = 单谓词六 kind（含 review_failed 字符串 resolve 形态）
+    // ——旧 `^` 锚正则只认首行形态，漏「时间线 + 尾」；语义零丢（六形态全覆盖）。
+    // 另：设计评审的**启动拒绝报告**（未发起请求——无评审产出）同样不得计为评审覆盖
+    // （§14.4 异步结算面判据；与同步工具面 _advisorRefusals 同源前缀；正常链不可达＝防御纵深）
+    // ——判定已上移为本结算段单点（launchRefused，上方）。
+    const failureVerdict = (run.reviewType !== "design" && (
+      incomplete !== null ||
+      (result == null && entry.error != null)
+    )) || launchRefused
+    if (!failureVerdict) {
+      agent._calledAdvisorThisRun = true
+    }
+  } else if (run.reviewType === "design" && entry.designToken && result != null) {
+    // §29 fix B（stale 分支）：陈旧评审不签发——digest 不得展示未注册 token——先剥
+    // 方括号回显 + 前置 "评审目标已变更——token 未签发"（不变式——两分支都清洗）。
+    const stripped = String(result)
+      .replace(makeDesignTokenRegex(entry.designToken, "g"), "")
+      .trim()
+    report = `评审目标已变更——token 未签发 (review target changed after launch — this review judged a stale state; no design token was issued — re-run the review on the current state)\n\n${stripped}`.trim()
+  }
+  // 第 33 批（§17.5 计数点 1——异步结算）：design 三出口（非陈旧 / 陈旧 / design 无报告）统一
+  // 按分类单源落账——count/stale/no_credential/no_report 增计数，可用判决复位，取消 / 中断 /
+  // 拒发 neutral（分类表见 §17.3）。cancel 早退 / 无实例在函数头已返回（不计）。
+  if (run.reviewType === "design") {
+    noteDesignReviewOutcome(agent, run.docSetKey, designReviewOutcome({
+      launchRefused, stale, hasResult: result != null, incomplete, persistFailed,
+    }))
+  }
+  // Prior of round 2+ = the last REVIEW-LOOKING output (mirror of run.mjs's guard).
+  // F2e (§29.1): strip the engine-approved suffix FIRST — the prior must never
+  // carry the raw token / designId (exact truncation — zero collateral).
+  if (report && looksLikeReviewOutput(report)) {
+    run.priorOutput = stripApprovedSuffix(report, run.approvedSuffix)
+  }
+  return { cancelled: false, stale, passed, report }
+}