@thincoder/core 0.9.4 → 0.10.1

package/agent-tools/advisor.mjs

@@ -3,16 +3,17 @@
  * 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
+ * AGENT-LOOP-ASYNC-POOL.md §6.10 (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.mjs"
 // M6（模块设计 §2.1 F3）：评审对象来源读 manifest docRoot（声明面）——复用 M4 的
-// write-gate.mjs 单一权威源（KD-M6-1），替代 v1 的 loadConventions/isDocPath 分类；
+// write-gate.mjs 单一权威源（KD-M6-1），替代 v1 的逐档分类面（isDocPath）；
 // normAbs 同源 re-export（指针非副本）。不 import dispatch.mjs（簇间回边，环风险）。
-import { resolveReviewTargetPaths, normAbs } from "../agent/write-gate.mjs"
+import { resolveReviewTargetPaths, resolveReviewRootsFor, normAbs } from "../agent/write-gate.mjs"
+import { owningProject } from "../manifest-discovery.mjs"
 import { sep } from "node:path"
 import {
   generateDesignToken,
@@ -24,6 +25,8 @@ import {
 // 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"
+// #15 描述外置：描述文本单点 = tool-docs/advisor.md（DESC 单解析面，缺档抛错语义不变）
+import { DESC } from "../tools/shared.mjs"
 
 // Design-token utilities moved to advisor-async.mjs (the async settle shares
 // them — no wrapper↔runner module cycle); validateDesignToken stays exported
@@ -32,36 +35,14 @@ 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.",
+  description: DESC("advisor"),
   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).",
+        description: "Background review: default at depth 0 = true (ack now, report via digest); async:false forces the blocking review. depth>0 → always sync.",
       },
       object: {
         type: "object",
@@ -72,21 +53,21 @@ export const advisorTool = {
           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).",
+        description: "Review-object declaration — mechanically injected at the start of the review message. 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.",
+        description: "Code files or directories to review (for code review). Required unless documents is provided. The advisor reads exactly these — 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.",
+        description: "Doc paths to review (design / requirements / referenced docs). The advisor reviews ONLY these — no git diff scan. Use for both review types to pass the task's docs 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` write channel (transition alias `batch_segment`) 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).",
+        description: "Design review only: the in-flight batch record path — validated whenever passed (unreadable ⇒ refused, not ignored); the reviewer then also gets the `batch` write channel to record its findings + verdict. Omit when no batch record is in flight (no write channel — zero regression).",
       },
     },
     required: ["type"],
@@ -96,7 +77,7 @@ export const advisorTool = {
   outputPanel: true,
   async execute(args, ctx) {
     const agent = ctx.agent
-    // Review-object declaration (§18.8 D-OA3): the PARENT constructs it and the
+    // Review-object declaration (AGENT-LOOP-ASYNC-POOL.md §6.18 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).
@@ -137,9 +118,23 @@ export const advisorTool = {
     // elsewhere declares them in PROJECT-MANIFEST.json docRoot).
     if (reviewType === "design" && documents) {
       const roots = resolveReviewTargetPaths(agent).map((r) => r.replace(/[\\/]/g, sep))
+      // 按用点解析（2026-09-21 之裁收口 · 台账 #828）：逐文档按**其所属项目**（最近带档祖先）
+      // 的 docRoot 判定；无主档文档回退会话根集判定（原行为零变）。
+      const ownerRootsCache = new Map()
+      const ownRoots = (abs) => {
+        const owner = owningProject(abs)
+        if (!owner) return []
+        let r = ownerRootsCache.get(owner)
+        if (!r) {
+          r = resolveReviewRootsFor(owner).map((x) => x.replace(/[\\/]/g, sep))
+          ownerRootsCache.set(owner, r)
+        }
+        return r
+      }
       const invalidDocs = documents.filter((doc) => {
         const n = normAbs(doc, agent.cwd).replace(/[\\/]/g, sep)
-        return !roots.some((r) => n === r || n.startsWith(r + sep))
+        const under = (r) => n === r || n.startsWith(r + sep)
+        return !roots.some(under) && !ownRoots(n).some(under)
       })
       if (invalidDocs.length > 0) {
         if (ctx._toolCallId !== undefined) (agent._advisorRefusals ??= new Set()).add(ctx._toolCallId)
@@ -150,7 +145,7 @@ export const advisorTool = {
       }
     }
 
-    // §11.2 (R13 — ruling ②-3 A): async gate. Depth-0 defaults to the
+    // §6.10 (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` 显式布尔，
@@ -168,16 +163,16 @@ export const advisorTool = {
     }
     const isAsync = asyncRequested || (depth === 0 && args.async !== false)
 
-    // Per-review instance resolution (§11.2 ③ — ruling ②-5 A): fix rounds
+    // Per-review instance resolution (§6.10 ③ — 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 的唯一路径来源）：
+    // BATCH-RECORD.md §4.2 评审侧批次档门禁 + 实例键绑定（评审实例的唯一路径来源）：
     // 口径 = **「若传则须可读」**（空/不可读 → throw；不强制必传——无批次档的在途设计评审
     // 零回归，N5）；绑定落在 resolved.run（评审实例键，与 reviewType/round/designId 同族）——
-    // 并发设计评审各绑各档，不用单值会话态（§2.20.8 #6）。
+    // 并发设计评审各绑各档，不用单值会话态（BATCH-RECORD.md §4.7 #6）。
     if (args.batchDoc !== undefined && args.batchDoc !== null) {
       resolved.run.batchDoc = resolveBatchDocPath(agent.cwd, args.batchDoc)
     }
@@ -185,7 +180,7 @@ export const advisorTool = {
     // 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).
+    // same-scope re-review after a pass REUSES the session's id (F2h).
     const designToken = reviewType === "design" ? generateDesignToken(agent) : null
     const designId = reviewType === "design" ? resolved.designId : null
 
@@ -209,7 +204,7 @@ export const advisorTool = {
       if (ctx._toolCallId !== undefined) {
         (agent._advisorAsyncAcks ??= new Set()).add(ctx._toolCallId)
       }
-      // E（F17/§14.14 E-3c）：设计评审点火回执追加冻结句（代码评审 ack 零改）——窗口下界以
+      // E（F17/ADVISOR-GUARDS.md §5 E-3c）：设计评审点火回执追加冻结句（代码评审 ack 零改）——窗口下界以
       // 可观察信号表达：报告送达 / 取消前，被审文档（含批次档）零写入。
       const freezeNote = reviewType === "design"
         ? "；D5 冻结窗口：被审文档（含批次档）在报告送达前零写入——在途写入会被拒绝，写入将使本轮结算为陈旧 (pass 不发 token)"
@@ -244,9 +239,9 @@ export const advisorTool = {
       batchDoc: resolved.run.batchDoc ?? null,
     }, designToken, documents, paths, reviewObject, designId)
 
-    // B 启动拒绝（§14.4 #2——稳定前缀）：拒发登记（同池满 / cap 款——不置 called、不耗轮次），
+    // B 启动拒绝（稳定前缀）：拒发登记（同池满 / cap 款——不置 called、不耗轮次），
     // 可见报错照常返回（record-results 的 REFUSED 契约）。第 33 批：判定单点——同时供设计
-    // 失败分类复用（launchRefused ⇒ neutral——无尝试发生，§17.3 #1）。
+    // 失败分类复用（launchRefused ⇒ neutral——无尝试发生；`ADVISOR-GUARDS.md` §7 失败结算表行 1）。
     const launchRefused = String(result).startsWith(ADVISOR_LAUNCH_REFUSAL_PREFIX)
     if (launchRefused && ctx._toolCallId !== undefined) {
       (agent._advisorRefusals ??= new Set()).add(ctx._toolCallId)
@@ -265,12 +260,12 @@ export const advisorTool = {
       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
+      // F2e: 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）。
+        // 未完成 ⇒ 同步 prior 镜像覆写为清洗后输出（防未注册 token 进 prior——ADVISOR-GUARDS.md §1）。
         agent._lastAdvisorOutput = settled.output
       }
       return settled.output

package/agent-tools/async-discard.mjs

@@ -13,6 +13,11 @@
  * - 保留 ⟺ 其余——存活条目（controller 未中止——报告沿自动通道到达）/ done-in-pool（回合尾
  *   收集 / 挂起 sweep 消化）/ cancelled（settle cancelled 分支收尾）。
  *
+ * #9 后台 bash 任务族（三族同面并入——D9-7 收尾档②）：bg 条目的「已死」不由 controller 杀达
+ * ——其控制器链只作**判据**（杀 ⟺ 控制器已中止），杀树动作经本收尾面 `spec.dispose` 钩子落
+ * `bash-async.mjs` 杀单点（`killBgTree`）；回合中断（Ctrl+I）经 `bindChildController`
+ * interrupt 豁免不中止控制器 ⇒ 本面零动作（F2 同款豁免——池保留）。
+ *
  * 判据口径（D-AD6）：两接线点**均不传 `ctx`** ⇒ 实走 controller 支（`parentAborted(null, entry)`）
  * ——与对侧有效判据同判（对侧传入的 `ctx` 为死参）；`ctx` 保留为签名备用面（直调用例 / 对侧收敛）。
  * 「controller 已中止 = 条目真死」由 `bindChildController` 单点保证（`async-settle.mjs:88-98`
@@ -36,6 +41,8 @@ import { carrierField, getAsyncPool, parentAborted, writeTombstone } from "./asy
 import { pushReal } from "../context.mjs"
 import { escapeXml } from "../agent/helpers.mjs"
 import { logEvent } from "../log.mjs"
+// #9（后台 bash 任务族——收尾档②）：杀单点（树杀）经 `bash-async.mjs` 落面。
+import { killBgTree } from "./bash-async.mjs"
 
 /** 提醒模板（verbatim 同源 = 对侧 `async-discard.mjs:37-44`；测试断关键子串，不逐行断）。 */
 const subagentReminderText = (n, list) =>
@@ -47,6 +54,11 @@ const advisorReminderText = (n, list) =>
   `[System reminder: ${n} background advisor review(s) were discarded by the user's Stop — their reports will NOT arrive: ${list}.\n` +
   "No design token was issued for a discarded design review; launch the review again if it is still needed.]"
 
+/** #9 后台 bash 任务族提醒模板（同族形态——报告不可达的可视化：进程已杀，全量 log 仍在盘上）。 */
+const bgReminderText = (n, list) =>
+  `[System reminder: ${n} background bash task(s) were killed by the user's Stop — their processes are gone and no digest will arrive: ${list}. ` +
+  "Full output logs remain on disk (paths were given in the start ack).]"
+
 /** 列表词（wasStatus 数据源）：queued → "(was queued — never started)"；其余 "(was running)"。 */
 const wasPhrase = (wasStatus) => (wasStatus === "queued" ? " (was queued — never started)" : " (was running)")
 
@@ -87,6 +99,7 @@ function discardRole(parent, spec, ctx) {
     if (!discardable(entry, ctx)) continue
     out.discarded.push(spec.describe(entry))
     ids.add(String(entry.id))
+    spec.dispose?.(entry) // 族特有处置（#9 bg：杀树——判据成立即条目真死；其余族无此钩子）
     writeTombstone(parent, entry.id, "discarded", spec.roleOf(entry))
     removeFromPool(map, entry.id)
   }
@@ -94,7 +107,11 @@ function discardRole(parent, spec, ctx) {
   if (out.discarded.length === 0) return out // 零丢弃 = 零噪音（零注入 / 零事件）
   spec.pruneQueue?.(parent, ids)
   const list = out.discarded.map(spec.listPhrase).join(", ")
-  pushReal(parent, { role: "user", content: spec.reminder(out.discarded.length, escapeXml(list)) })
+  // 注入面（#94 载体两形吸收）：agent 形（run-stages ∕ 挂起中止接线点——`parent.history` 在）走
+  // `pushReal`（机器 + 人读双线）；**history 数组本体形**（VSC 挂起载体——池挂数组）无注入目标 ⇒
+  // 跳过（与对侧 VSC copy 的 `parent?.history` 守卫同判；§6.20.1「carrier 形无注入目标」先例）
+  // ——墓碑与 `ev:discarded` 照发，仅模型可见提醒缺席（数组形无人读线可达面）。
+  if (parent?.history) pushReal(parent, { role: "user", content: spec.reminder(out.discarded.length, escapeXml(list)) })
   logEvent("ev:discarded", { n: out.discarded.length, ids: out.discarded.map((d) => `${d.role}#${d.id}`).join(", ") })
   return out
 }
@@ -120,6 +137,20 @@ const ADVISOR_SPEC = {
   pruneQueue: (parent, ids) => pruneQueue(parent, ids, "_asyncAdvisorQueue"),
 }
 
+/** #9 后台 bash 任务族 spec（收尾档②）：dispose = 杀树（杀单点 `killBgTree`）+ 标记 discarded
+ *  （settle 面据此不注入——报告不可达）；无队列面（超限 = 起跑显式拒，无排队语义）。 */
+const BG_SPEC = {
+  pool: "bg",
+  describe: (entry) => ({ id: entry.id, role: "bg", command: entry.command }),
+  roleOf: () => "bg",
+  listPhrase: (d) => `bash#${d.id} (\`${d.command}\`)`,
+  reminder: bgReminderText,
+  dispose: (entry) => {
+    entry.discarded = true
+    killBgTree(entry)
+  },
+}
+
 /**
  * 中止收尾（F1–F3）：只清已死子代理条目——写 `discarded` 墓碑 + 出池 + 队列剔除 + 整批一次提醒。
  * @param parent agent 形态（载体双形经 `getAsyncPool` / `writeTombstone` 吸收）
@@ -141,3 +172,15 @@ export function discardAbortedPool(parent, ctx = null) {
 export function discardAbortedAdvisors(parent, ctx = null) {
   return discardRole(parent, ADVISOR_SPEC, ctx)
 }
+
+/**
+ * 中止收尾（#9 后台 bash 任务族——收尾档②）：只清已死条目——逐条**杀树**（判据成立 ⟺ 条目
+ * 控制器已中止；杀单点经 `killBgTree`）+ `discarded` 墓碑 + 出池 + 整批一次提醒；回合中断
+ * （Ctrl+I）不中止控制器 ⇒ 本面零动作（池保留——F2 同款豁免）。
+ * @param parent agent 形态
+ * @param ctx 判据 ctx（接线点不传——controller 支，同上）
+ * @returns {{discarded: Array<{id, role: "bg", command}>, kept: number}}
+ */
+export function discardAbortedBgTasks(parent, ctx = null) {
+  return discardRole(parent, BG_SPEC, ctx)
+}

package/agent-tools/async-settle.mjs

@@ -43,7 +43,8 @@ import { refillAdvisorQueue } from "./advisor-async.mjs"
 /**
  * 载体字段读取吸收（#94——「VSC 的跨 runAgent 存活载体面按核内结构归一」）：
  * §2.3 载体口径 = `_asyncSubagents` · `_asyncAdvisors` · `_consultSessions` ·
- * `_pendingAsyncResults` · `_suspended`（AGENT-LOOP.md §2.3 seam 表）。
+ * `_pendingAsyncResults` · `_suspended`（AGENT-LOOP.md §2.3 seam 表）；#9 后台任务池
+ * `_bgTasks` 同列（写侧父字段 + 借用/别名 history——见 `bash-async.mjs` `ensureBgPool`）。
  * CLI 形：字段直接挂 agent（跨 run 存活）；VSC 形：字段挂 depth-0 `history`
  * （agent per-run 重建——run 起始把 history 容器绑到 agent 字段，绑定不变式）。
  * 本函数吸收两形为同一读取：父对象字段优先，缺字段回退 `parent.history`。
@@ -91,7 +92,7 @@ export function tombstoneOf(parent, id) {
 /**
  * 条目 controller 链到基信号单点（#98 VSC 侧并入——interrupt 豁免面；原 subagent-run /
  * advisor-async / escalate-async / consult 四处逐字同构）：
- * - 基信号**已 aborted** 且非 interrupt ⇒ 立即 abort（reason 逐跳保留——§20.3 站点 #10）；
+ * - 基信号**已 aborted** 且非 interrupt ⇒ 立即 abort（reason 逐跳保留——AGENT-LOOP-SUBAGENT.md §6.12 站点 #10）；
  * - interrupt aborted（Ctrl+I——中断消息注入后同回合续跑）⇒ **不逐链中止**（池保留；
  *   子代理 / 评审继续跑完，settle 照常注入——「Ctrl+I keeps the pool」意图对齐）；
  * - 未来 abort ⇒ 非 interrupt 才逐链传播（Stop / 会话中止全停语义不变）。
@@ -111,11 +112,12 @@ export function bindChildController(ctrl, baseSignal) {
 // ─── D1 池 accessor（吸收双池）────────────────────────────────────────────────
 
 /** 池 accessor（D1）：role "advisor" → `_asyncAdvisors`（独立评审池——无队列独立调度）·
- *  role "consult" → `_consultSessions`（会话池）· 其余 → `_asyncSubagents`（子代理/飞刀
- *  共享槽位队列池）。载体经 `carrierField` 吸收（#94）；未初始化返 null——调用方以
- *  `?? new Map()` / 可选链处置。 */
+ *  role "consult" → `_consultSessions`（会话池）· role "bg" → `_bgTasks`（#9 后台 bash
+ *  任务池）· 其余 → `_asyncSubagents`（子代理/飞刀共享槽位队列池）。载体经 `carrierField`
+ *  吸收（#94）；未初始化返 null——调用方以 `?? new Map()` / 可选链处置。 */
 export function getAsyncPool(parent, role) {
-  const field = role === "advisor" ? "_asyncAdvisors" : role === "consult" ? "_consultSessions" : "_asyncSubagents"
+  const field = role === "advisor" ? "_asyncAdvisors" : role === "consult" ? "_consultSessions"
+    : role === "bg" ? "_bgTasks" : "_asyncSubagents"
   return carrierField(parent, field) ?? null
 }
 
@@ -155,7 +157,7 @@ export function buildChildSignal(parent, ctx) {
 // ─── D3 settle 共享 helper ───────────────────────────────────────────────────
 
 /**
- * §23.3.1 消化窗口持有释放（TUI-OOM-ROOTCAUSE——D-SM2 表 2 候选 1）：注入完成后置空条目
+ * AGENT-LOOP.md §6.15 消化窗口持有释放（TUI-OOM-ROOTCAUSE——D-SM2 表 2 候选 1）：注入完成后置空条目
  * 对子代理对象的引用（`childAgent`/`report`——条目前此从不显式释放，挂起期 = 分钟级驻留）。
  * 幂等（重入不抛）；池内/挂起未消化窗口语义零变（settle 时刻不释放——表 2 候选 2 否决：
  * status/observe 在窗口内仍读 child 摘要）。三消费点（回合尾收集 / run 起始 pending 注入 /
@@ -178,10 +180,10 @@ export function releaseSettledEntry(entry) {
  *   ③ 分流：cancelled（出池 + cancelled 墓碑 + ⟦ev⟧stopped + 族提醒——不入 pending）→
  *      parentAborted（守卫抑制——不落事件不入流——中止清池在回合尾/挂起中止统一做）→
  *      settled（族 onAccounting hook 记账 → 挂起期（或 consult 族恒停靠）移交 pending
- *      单容器 + 出池 + ⟦ev⟧settled；回合内 ⟦ev⟧done 留池 done:true）；
+ *      单容器 + 出池，非挂起期留池 done:true；两态一律 ⟦ev⟧settled——⟦ev⟧done = 消费面补发）；
  *   ④ 公共尾部：settleSeq 递增 + `_settle` 唤醒 waiter + 腾槽补位（subagent/escalate 族
  *      恒补——settle/cancel 释放槽 → maybeRefillAsync + refreshQueuedTokens——AGENT-LOOP.md
- *      §10 "settle/cancel 释放槽后…启动到槽满"；advisor 经 refillAdvisorQueue 补位
+ *      AGENT-LOOP-SUBAGENT.md §6.9 "settle/cancel 释放槽后…启动到槽满"；advisor 经 refillAdvisorQueue 补位
  *      （ED-4——评审池有排队语义后不再豁免）；consult（会话池）豁免）。
  * opts（设计签名 `{pool, onAccounting}` + 实现参数 ctx）：
  * - pool：条目所在池 Map（出池 delete 目标；consult 传 null——会话池无条目）。
@@ -193,7 +195,7 @@ export function releaseSettledEntry(entry) {
  *   设计偏差注（advisor code review 发现——交付报告同步）：设计 D3 把 maybeRefillAsync
  *   归入 onAccounting hook（仅 settled 分支执行）——running 取消的 cancelled 分支将不再
  *   补位（槽释放但 queued 头停滞——挂起会话无回合尾补位覆盖），违背既有不变式
- *   （AGENT-LOOP.md §10 + subagent-scheduler maybeRefillAsync 文档 "called from every
+ *   （AGENT-LOOP-SUBAGENT.md §6.9 + subagent-scheduler maybeRefillAsync 文档 "called from every
  *   settle"）与 VSC 镜像（无条件 refill）。修正：腾槽补位移入公共尾部（subagent/escalate
  *   族恒补——旧行为零回归；advisor/consult 豁免——同 VSC refill!==false 语义）。
  */
@@ -232,10 +234,10 @@ export function settleAsyncEntry(parent, entry, opts = {}) {
   }
   // ③ 分流
   if (entry.cancelled) {
-    // §19.5 cancelled settle 分支（D-M6）：不入 pending、不参与回合尾直注入——清池 +
+    // AGENT-LOOP-SUBAGENT.md §6.7.2 cancelled settle 分支（D-M6）：不入 pending、不参与回合尾直注入——清池 +
     // 终态墓碑（dependsOn 取消语义）+ ⟦ev⟧stopped 冻结 + 族提醒（半成品警示对模型可见）。
     pool?.delete(String(entry.id))
-    writeTombstone(parent, entry.id, "cancelled", role) // §20 D-SD5：单点写入（#94 载体吸收）
+    writeTombstone(parent, entry.id, "cancelled", role) // AGENT-LOOP-SUBAGENT.md §6.9 D-SD5：单点写入（#94 载体吸收）
     ctx?.callbacks?.onToken?.(`${entry.relayPrefix}⟦ev⟧stopped\x1e0\x1e0\x1estopped\x1e`)
     if (role === "advisor") {
       // ②-6b：评审取消——token 未签发提醒（settleAdvisorRun 不消费预算）。
@@ -249,7 +251,7 @@ export function settleAsyncEntry(parent, entry, opts = {}) {
         content: `[System reminder: async escalate #${entry.id} (${entry.tag}) cancelled by user — partial changes not merged/audited]`,
       })
     } else {
-      // §20 D-SD5：running 依赖取消——提醒列出依赖者（供模型决策）。
+      // §6.9 D-SD5：running 依赖取消——提醒列出依赖者（供模型决策）。
       const dependents = dependentLabels(parent, String(entry.id))
       const autoNote = parent.autoApprove
         ? " — AUTO session: they auto-start on slot availability (round2 #3)"
@@ -263,23 +265,24 @@ export function settleAsyncEntry(parent, entry, opts = {}) {
     // 族记账 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 注入）。
+    // 挂起分流（AGENT-LOOP-ASYNC-POOL.md §6.8 D-S8 + D-S3 记账——以读取时刻为准）：挂起期 settle → 移交 pending
+    // 单容器（digest 注入）+ 出池；非挂起期 ⇒ 留池 done-in-pool（回合尾 collectSettledAsync 注入兜底 ∥
+    // 挂起会话 sweep 消费链照旧）。
     // consult 族恒停靠（settle 即出会话池入 pending——无 TUI 冻结事件——子块各自冻结）。
     if (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`)
     }
+    // 发射单点（块到达时点归位批 · #746｜§6.8「settle 延迟冻结（两态统一）」）：settle 一律 ⟦ev⟧settled
+    // （区块头恒中间态「done · awaiting digestion」驻留面板）；⟦ev⟧done = 消费面补发（消费窗清单单源
+    // = §6.8）⇒ 冻结 ∥ 归档恒落消费时点——回合运行中零归档触发器（「S 不夹运行中回合」结构不变式）。
+    ctx?.callbacks?.onToken?.(`${entry.relayPrefix}⟦ev⟧settled\x1e0\x1e0\x1esettled\x1e`)
   }
   // ④ 公共尾部：settleSeq 递增 + _settle 唤醒（never rejects）+ 唤醒挂起驱动 waiter
   entry._settleSeq = (parent._asyncSettleSeq = (parent._asyncSettleSeq ?? 0) + 1)
   entry._settle?.()
   wakeAsyncWaiters(parent) // §6.27.12.4 ①：挂起驱动唤醒单点（settle 尾 / 上行 ask 入队尾两处调用）
-  // §20 D-SD4 释放点：settle/cancel 释放槽 + 依赖终态转移 → 补位（依赖满足者/域冲突
+  // §6.9 D-SD4 释放点：settle/cancel 释放槽 + 依赖终态转移 → 补位（依赖满足者/域冲突
   // 解除者自动启动——槽 ≤4）→ 排队态面板刷新（等待块头标注随终态更新——dependency
   // cancelled / 位置前移）。subagent/escalate 族恒补（旧行为零回归——cancelled 分支
   // 同样补位）；advisor（ED-4——独立评审池的排队语义）经 refillAdvisorQueue 补位；

package/agent-tools/audit-block.mjs

@@ -9,7 +9,7 @@
  */
 
 /**
- * §18.7 D-TS5 (A2): mechanically summarize the parent spawn task book for the
+ * AGENT-LOOP-SUBAGENT.md §6.7.6 D-TS5 (A2): mechanically summarize the parent spawn task book for the
  * audit spawn — the three audit-relevant elements VERBATIM (design doc paths /
  * affected-file list / acceptance criteria); verbose context/background is
  * dropped (the auditor can read the design docs themselves — they stay
@@ -70,8 +70,8 @@ export function summarizeEngTaskBook(taskInput) {
 export function buildAuditBlock(ctx) {
   const touched = (ctx.agent._touchedFiles ?? []).map((f) => `- ${f}`).join("\n") || "- (none yet)"
   return `[Audit scope — mechanical context, independent of the eng-coder's self-report:]\n` +
-    // §18.7 D-TS4 A1：审计指令模板（四类偏差 + 范围限制 + 校验清单格式）——审计语义
-    // 不再靠模型自悟；范围限制是 §18.5 D-AG3 声明（下方 Zero-git scope authority）
+    // §6.7.6 D-TS4 A1：审计指令模板（四类偏差 + 范围限制 + 校验清单格式）——审计语义
+    // 不再靠模型自悟；范围限制是 §6.7.4 D-AG3 声明（下方 Zero-git scope authority）
     // 的同源一句指注，不重复声明。
     `[Audit instructions — mechanical template:]\n` +
     `You are auditing an eng-coder delivery against its approved design — audit for EXACTLY these four deviation categories:\n` +
@@ -83,21 +83,21 @@ export function buildAuditBlock(ctx) {
     `workspace changes not listed there are unrelated to this delivery and are NOT grounds for an out-of-list finding.\n` +
     `Scope discipline (F-TS6 A1): read ONLY the audited files and the design-doc sections relevant to this delivery — do NOT re-read whole documents.\n` +
     `Every deviation item MUST be fieldized: file:line + design reference (doc path + section/AC id) + severity + evidence (quoted code or doc text).\n` +
-    // §18.7 D-TS5 A2：任务书从全量 verbatim 改机械摘要块（三要素逐字——排除冗长上下文）。
+    // §6.7.6 D-TS5 A2：任务书从全量 verbatim 改机械摘要块（三要素逐字——排除冗长上下文）。
     `[Parent spawn task book — mechanical summary: design docs + affected-file list + acceptance criteria verbatim; verbose context/background dropped — the design docs are still available for reading outside this input:]\n` +
     `${summarizeEngTaskBook(ctx.agent._engTaskInput)}\n` +
     `Files actually touched by the eng-coder (mechanical union — audit these against the file list):\n${touched}\n` +
     // §18.5 D-AG3（2026-09-04）：审计零 git 范围权威声明——本审计任务零 git（不注入
-    // git 上下文——§18.5 全角色零 git）；_touchedFiles 为审计范围；工作区未列于
+    // git 上下文——§6.7.4 全角色零 git）；_touchedFiles 为审计范围；工作区未列于
     // _touchedFiles 的改动与本任务无关，不作超清单依据（VS Code auditTaskBook 同款措辞）。
     "Zero-git scope authority: this audit task receives NO git context — nothing is injected. " +
     "The evidence base is the design documents, the current disk state (read/glob/grep), and the _touchedFiles list above. " +
     "Workspace changes NOT listed in _touchedFiles are unrelated to this delivery — they are NOT grounds for an out-of-file-list finding." +
-    // §18.13 D-A1.2：审计预算句——A1 指令模板 + A2 摘要块之后、A3 报告模板之前（定序——评审 #7）。
+    // §6.7.6 D-A1.2：审计预算句——A1 指令模板 + A2 摘要块之后、A3 报告模板之前（定序——评审 #7）。
     // 逐字设计锚（D-A1.2 代码块）：只读该读的——10 轮机械预算——超时报 PROBLEM 下结论。
     // 前导 \n 与 A3 同款块分隔约定（上一句 Zero-git 句末无换行——不触碰既有句）。
     `\n[Audit budget — mechanical]: read ONLY the touched files listed above and the design-doc sections the parent task book names (affected-files table, acceptance criteria, status line). Do NOT read whole documents. Budget = 10 tool rounds max — if you cannot conclude within it, report PROBLEM (inconclusive) rather than continuing to explore.\n` +
-    // §18.7 D-TS6 A3：审计输出报告格式模板（三态——字段化行——不让模型自由发挥）。
+    // §6.7.6 D-TS6 A3：审计输出报告格式模板（三态——字段化行——不让模型自由发挥）。
     `\n[Audit report format — mechanical template:]\n` +
     `Report EXACTLY one of three states:\n` +
     `- CLEAN — no deviation across the four categories: reply the line "Four deviation categories: none found." (四类偏差均未发现);\n` +