@thincoder/core 0.9.1

package/agent-tools/advisor-settle.mjs

@@ -0,0 +1,240 @@
+/**
+ * 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-facts.mjs`
+ * （原处 re-export 保面）；**2026-09-18 顾问面治理批**：计数落账（`designReviewOutcome` →
+ * `noteDesignReviewOutcome`）随会话级计数器整体退场——改治**失败结论**：结算出口按
+ * `settlementCriterion`（纯函数单源，`advisor/notice.mjs`）追加结论块（**两轨共用**——
+ * ADVISOR-GUARDS.md §7）。记账本体 / 陈旧判定 / 轮次 / 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-facts.mjs`（中立模块——陈旧判定与事实面共用同一归一）；
+// 2026-09-18：结算分类 / 结论文案单源迁 `advisor/notice.mjs`（纯函数、零状态、零计数载体）。
+import { normAbs } from "./review-facts.mjs"
+import { settlementCriterion, buildSettlementConclusion, scopeSummary } from "../advisor/notice.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-facts.mjs`；原处 re-export 保既有 import 面
+// （advisor-async / 测试）零变。
+export { normAbs } from "./review-facts.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）：design 结算按分类单源落账到会话级护栏——**2026-09-18 撤**（零载体）。
+ * 现行：结算出口按判据名单源（`settlementCriterion`）追加失败结论块（两轨共用；F28/F29）——
+ * 判据名非空 ⇒ 块在位（块首行 = 对象标识行）；可用判决 / 中断 / 拒发 ⇒ 零噪声（无块）。
+ * 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()
+  }
+  // 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).
+  // 结论块（下方）刻意晚于 prior 归一：prior 只承载评审正文，不携带机制文案。
+  if (report && looksLikeReviewOutput(report)) {
+    run.priorOutput = stripApprovedSuffix(report, run.approvedSuffix)
+  }
+  // F28/F29 失败结论（2026-09-18 顾问面治理批——**两轨共用**，ADVISOR-GUARDS.md §7 契约二）：
+  // 判据名非空 ⇒ 结算出口追加结论块（块首行 = 对象标识行 + 既有正文逐字 + 本次尝试单行 +
+  // 选项三值）。**零会话级计数载体 / 零封禁**——下一次发起照常受理（cap / 连败停止预检已撤除）。
+  const criterion = settlementCriterion({ launchRefused, stale, hasResult: result != null, incomplete, persistFailed })
+  if (criterion) {
+    report = buildSettlementConclusion({
+      type: run.reviewType,
+      scope: scopeSummary(entry.documents?.length ? entry.documents : entry.paths),
+      round: run.round,
+      criterion,
+      body: report,
+    })
+  }
+  return { cancelled: false, stale, passed, report }
+}

package/agent-tools/advisor.mjs

@@ -0,0 +1,280 @@
+/**
+ * agent-tools/advisor.mjs — advisor tool wrapper.
+ * The agent calls this explicitly to get an independent review.
+ * The top-level `type` is REQUIRED and must be exactly "code" or "design"
+ * (F30 fail-closed — no silent default; ADVISOR-GUARDS.md §2.4).
+ * §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, advisorIncompleteMarker, ADVISOR_LAUNCH_REFUSAL_PREFIX } from "../advisor/run.mjs"
+import { resolveBatchDocPath } from "./batch-segment.mjs"
+// M6（模块设计 §2.1 F3）：评审对象来源读 manifest docRoot（声明面）——复用 M4 的
+// write-gate.mjs 单一权威源（KD-M6-1），替代 v1 的 loadConventions/isDocPath 分类；
+// normAbs 同源 re-export（指针非副本）。不 import dispatch.mjs（簇间回边，环风险）。
+import { resolveReviewTargetPaths, normAbs } from "../agent/write-gate.mjs"
+import { sep } from "node:path"
+import {
+  generateDesignToken,
+  settleDesignReview,
+  resolveAdvisorLaunch,
+  launchAsyncAdvisor,
+  stripApprovedSuffix,
+} from "./advisor-async.mjs"
+// F30/F31（2026-09-18 顾问面治理批）：类型门判定 / 拒发串 / 对象标识行——单源 `advisor/notice.mjs`
+// （文案逐字 = ADVISOR-GUARDS.md §2.4 / §2.5）；零计数载体（计数护栏随撤 cap 整体退场）。
+import { typeGateCriterion, buildTypeGateRefusal, scopeSummary, withIdentityLine } from "../advisor/notice.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. " +
+    "type is REQUIRED — exactly one of the two legal values: type='design' reviews design / requirement documents before implementation (pass documents=[...] with the explicit list of doc paths; plus batchDoc when a batch record is in flight); type='code' reviews the code you changed after implementation (pass paths=[...] to scope files/directories — documents=[...] adds acceptance-criteria context). " +
+    "A call without a type (or with a conflicting object.type) is refused — there is no default and no silent fallback. " +
+    "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 " +
+    " (the review-object declaration is mechanically injected into the review message); " +
+    "absent → legacy behavior (no injection). " +
+    "ASYNC: 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 (required): 'design' for design doc review, 'code' for code review. Omitting it is refused — there is no 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: 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. Omit when no batch record is in flight — the review then runs unchanged with no write channel (zero regression).",
+      },
+    },
+    required: ["type"],
+  },
+  readonly: true,
+  sideEffectExempt: true,
+  outputPanel: true,
+  async execute(args, ctx) {
+    const agent = ctx.agent
+    // 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
+    // F30 类型门（**最早判定**——先于范围判定 / 实例解析 / 一切拒发族）：顶层 `type` 必须逐字
+    // ∈ {"code","design"}——缺失 / 空串 / 非法值 / 非字符串 / 与 `object.type` 声明冲突 ⇒ 拒发
+    // （前缀 `Advisor: launch refused` + Why + 两个合法值行 + 标识行），登记 `_advisorRefusals`；
+    // **零实例 / 零 token / 零 LLM**（不静默降级——用户 2026-09-18 裁定）。
+    const gateCriterion = typeGateCriterion(args.type, reviewObject?.type)
+    if (gateCriterion) {
+      if (ctx._toolCallId !== undefined) (agent._advisorRefusals ??= new Set()).add(ctx._toolCallId)
+      return buildTypeGateRefusal({
+        criterion: gateCriterion, received: args.type, declared: reviewObject?.type ?? null,
+        scope: scopeSummary(args.documents?.length ? args.documents : args.paths),
+      })
+    }
+    const reviewType = args.type
+    const documents = args.documents || 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)
+      // F31：既有稳定前缀逐字（行首）+ 标识块尾随（单源 notice.mjs）。
+      return withIdentityLine(
+        "Advisor: no review scope specified. Provide paths (files/directories to review) or documents (acceptance criteria context).",
+        { type: reviewType, scope: "none", round: "—", criterion: "scope-missing" },
+      )
+    }
+
+    // Design review: the review scope must be documentation files. Classification
+    // comes from the manifest-declared review-target roots (M4 write-gate.mjs single
+    // authority — FR12: no directory-name hardcoding; a project whose docs live
+    // elsewhere declares them in PROJECT-MANIFEST.json docRoot).
+    if (reviewType === "design" && documents) {
+      const roots = resolveReviewTargetPaths(agent).map((r) => r.replace(/[\\/]/g, sep))
+      const invalidDocs = documents.filter((doc) => {
+        const n = normAbs(doc, agent.cwd).replace(/[\\/]/g, sep)
+        return !roots.some((r) => n === r || n.startsWith(r + sep))
+      })
+      if (invalidDocs.length > 0) {
+        if (ctx._toolCallId !== undefined) (agent._advisorRefusals ??= new Set()).add(ctx._toolCallId)
+        return withIdentityLine(
+          `Advisor: design review documents must be documentation files (per the project's conventions). Invalid: ${invalidDocs.join(", ")}`,
+          { type: reviewType, scope: scopeSummary(documents), round: "—", criterion: "scope-not-doc" },
+        )
+      }
+    }
+
+    // §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.
+    // depth 显式校验（归一形态——判定单点：`depth` 取一次 + `asyncRequested` 显式布尔，
+    // 判定表与原逐值等价）：
+    //   depth 0 + 未传/true ⇒ 异步（本层默认）/ depth 0 + false ⇒ 同步；
+    //   depth>0（或直调方无 depth） + 显式 true ⇒ 拒；其余 ⇒ 同步。
+    // 「无 depth」= 无 dispatch 上下文的直调方（测试/legacy）——按同步处理。
+    const depth = ctx?.depth ?? null
+    const asyncRequested = args.async === true
+    if (asyncRequested && 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; inside a child (eng-coder self-review) reviews run synchronously. Call advisor again without async:true (or with async:false)."
+    }
+    const isAsync = asyncRequested || (depth === 0 && args.async !== false)
+
+    // 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 预检 / 撤停止预检（2026-09-18 用户裁定——ADVISOR-CONVERGENCE.md §3.1）：本工具层
+    // **无任何按计数拒发**——第 6 次及以后的发起照常受理（轮次仅作提示词衰减与显示）；失败路径
+    // 的出口 = 结算出口的失败结论块（F28/F29——两轨共用，ADVISOR-GUARDS.md §7）。
+
+    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)"
+        : ""
+      if (ack.queued) {
+        // ED-4（2026-09-16 · AGENT-LOOP-SUBAGENT.md §6.10）：排队 ack——模型可见状态如实 queued +
+        // position（评审槽空自动启动——不误导模型等待即刻 digest）。
+        return JSON.stringify({
+          id: ack.id, kind: "advisor", status: "queued", position: ack.position,
+          reviewId: resolved.reviewId,
+          note: `评审已排队（第 ${ack.position} 位）——评审槽空自动启动，完成自动回来 (review queued at position ${ack.position} — it starts automatically when a pool slot frees; the report arrives in a digest turn automatically; pass this id to cancel if needed)` + freezeNote,
+        })
+      }
+      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 })
+      // 撤计数（2026-09-18 用户裁定）：原同步面“分类落账”随会话级计数器整体退场（零载体——F28③）；
+      // 失败结论块由**结算出口**产出（异步结算 `settleAdvisorRun`——两轨共用，ADVISOR-GUARDS.md §7）。
+      // 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
+  },
+}