@thincoder/core 0.9.5 → 0.10.1

package/agent-tools/subagent-actions.mjs

@@ -1,15 +1,17 @@
 /**
  * subagent-actions.mjs — subagent 动作执行器（AGENT-LOOP-SUBAGENT.md §6.7——2026-09-05 自
- * subagent-async.mjs 拆分——Module Split Policy §20.9——纯迁移零行为变化）。
- * 内容：executeStatusAction（AGENT-LOOP-SUBAGENT.md §6.7.2 D-M5——非阻塞池查询——touchedSummary/
- * shortTouchedPath/statusFields 摘要助手随行）/ executeObserveAction + executeSendAction
- * （SUBAGENT-OBSERVE-SEND——observe 只读/send 控制豁免注入）/ executeEscalateAction（AGENT-LOOP-SUBAGENT.md §6.7
- * D-M4——飞刀——touchedFilesNote 随行）。
+ * subagent-async.mjs 拆分——Module Split Policy——纯迁移零行为变化）。
+ * 内容：executeSendAction（SUBAGENT-OBSERVE-SEND——send 控制豁免注入）/ executeEscalateAction
+ * （AGENT-LOOP-SUBAGENT.md §6.7 D-M4——飞刀——touchedFilesNote 随行）；status ∕ observe 两执行器与
+ * 摘要助手族（touchedSummary/shortTouchedPath/statusFields）随 2026-09-28 三次拆分迁出（见下）。
  * AGENT-LOOP-SUBAGENT.md §6.7.5 check 删除后仅 cancel 动作执行器与共享 post-spawn 管线留在 subagent-async.mjs；
- * §20 调度器 + 文件域组在 ./subagent-scheduler.mjs（describeBlockers 由此导入）。
+ * AGENT-LOOP-SUBAGENT.md §6.9 调度器 + 文件域组在 ./subagent-scheduler.mjs（describeBlockers 由此导入）。
  * 2026-09-08 二次拆分：AGENT-LOOP-SUBAGENT.md §6.7.2 面板段迁至 ./subagent-panel.mjs（601 > 500 硬限跨档——
  * 尾部 re-export executePanelAction 保 subagent.mjs 既有 import 面）+ ASYNC-RESULT-
  * CONTAINER.md D1 落地（池访问点改 getAsyncPool accessor）。
+ * 2026-09-28 三次拆分（Module Split Policy——498/499 贴 500 硬限）：**查询面**（status ∕ observe
+ * 两执行器 + 摘要助手族）迁至 ./subagent-actions-query.mjs（verbatim）；本档保留 send ∕ escalate
+ * 执行器与 panel re-export，并 re-export 上述两执行器保 subagent.mjs 既有 import 面。
  */
 import { isAbsolute, relative } from "node:path"
 import { runAgent, createAgent, DEFAULT_SUBAGENT_TURNS, excludeSubagentTools } from "../agent.mjs"
@@ -18,268 +20,20 @@ import {
   ensureChildApiKey, clampEffort,
 } from "../agent/spawn-child.mjs"
 import { logEvent, errText } from "../log.mjs"
-import { describeBlockers, detectStall, STALL_NOTE } from "./subagent-scheduler.mjs"
 import { resolveChildProvider, mergeChildMutations } from "./subagent-async.mjs"
 import { launchEscalateAsync } from "./escalate-async.mjs"
-// TUI-OOM-ROOTCAUSE §23.3.1：子代理人读线窗口常量（单源——store 零依赖）。
+// TUI-OOM-ROOTCAUSE·AGENT-LOOP.md §6.15：子代理人读线窗口常量（单源——store 零依赖）。
 import { RECORD_WINDOW_MESSAGES } from "../session-store.mjs"
 // ASYNC-RESULT-CONTAINER.md D1：池 accessor（absorb 双池——advisor 独立池无队列）
 import { getAsyncPool } from "./async-settle.mjs"
-
-/**
- * subagent action:"status" (AGENT-LOOP-SUBAGENT.md §6.7 D-M2, new): NON-BLOCKING async-pool query —
- * returns immediately and never consumes a result (results belong to the auto
- * channel — AGENT-LOOP-SUBAGENT.md §6.7.5: no check action any more). Source of truth = the pool
- * (_asyncSubagents): entries moved to _pendingAsyncResults during a suspension
- * (AGENT-LOOP-ASYNC-POOL.md §6.8 D-S3 ② — injected at the next run start) are no longer in the pool and
- * are NOT counted as done-waiting.
- * - id given → { id, role, status, model?, elapsedSec?, turn?, maxTurns?,
- *   touchedFiles?/touchedMore?/touched? ... } for that entry; unknown id → error
- *   (T12 semantics — unknown async-subagent id error, same wording as the pool).
- * - id omitted → { overview: { running: [{id, role, model, elapsedSec, turn,
- *   maxTurns, touchedFiles?/touched?}], queued: [{id, role, position, touched?}],
- *   done: [{id, role}] } } — live queue positions (index in _asyncQueue + 1).
- * AGENT-LOOP-SUBAGENT.md §6.7.2: running 条目带 touched files 摘要（touchedFiles 前 5 + touchedMore 超出
- * 计数——相对查询方 cwd；0 改动 → touched 占位）；queued 条目带 touched 占位
- * "—（未启动）"；done/error/取消条目无 touched 字段（round3 #9）。
- * A settled-but-unconsumed entry (settled during a NORMAL turn) reports done
- * with a "not yet consumed" note — the auto channel (turn-end collection / the
- * suspension digest) still delivers it afterwards (AGENT-LOOP-SUBAGENT.md §6.7.5: sole consumption path).
- */
-/** AGENT-LOOP-SUBAGENT.md §6.7.2 D-M5 decision-field assembly (F9): running entries report
- *  {id, role, model, elapsedSec, turn, maxTurns} — the data needed to decide
- *  WHO to cancel. Model is recorded at spawn (childProvider), startedAt at
- *  ACTUAL start (queued waits don't count), turn/maxTurns mirrored from the
- *  child's ⟦ev⟧turn events at the callbacks-wrap layer (subagent.mjs tracker).
- *  elapsedSec computed at call time from startedAt. */
-/** AGENT-LOOP-SUBAGENT.md §6.7.2 D-SF2/N-SF1 摘要形态：status 调用时实时读 entry.childAgent._touchedFiles
- *  （绝对路径——per-run 记账——§18.12）→ 相对查询方 cwd；cwd 之外保留绝对形态 +
- *  "../" 前缀；>80 字符截尾（不超行）；前 5 个 + 独立截断字段 touchedMore（超出
- *  计数——不混入数组——消费方按类型区分）。占位：running 0 改动 → "—（尚无改动）"
- *  （T-SF2a）；queued 未启动 → "—（未启动）"（T-SF2b）；done/error/取消条目不含
- *  本摘要（round3 #9 明示——本批只做 running/queued）。 */
-function touchedSummary(entry, cwd) {
-  if (entry.status !== "running") return { touched: "—（未启动）" }
-  const files = entry.childAgent?._touchedFiles ?? []
-  if (files.length === 0) return { touched: "—（尚无改动）" }
-  const shown = files.slice(0, 5).map((f) => shortTouchedPath(f, cwd))
-  const out = { touchedFiles: shown }
-  if (files.length > 5) out.touchedMore = files.length - 5
-  return out
-}
-
-/** N-SF1 单路径显示形态：cwd 内 → 相对路径；cwd 外 → "../" + 绝对路径；>80 截尾。 */
-function shortTouchedPath(f, cwd) {
-  let p = f
-  if (cwd) {
-    const rel = relative(cwd, f)
-    p = rel && !rel.startsWith("..") && !isAbsolute(rel) ? rel : `../${f}`
-  }
-  return p.length > 80 ? `${p.slice(0, 79)}…` : p
-}
-
-function statusFields(entry, cwd) {
-  // §18.3 #1（第 10 批——双池并表）：评审池条目专属字段面——role 区分两池；子代理条目
-  // 字段面零变化（NFR-B2）。reviewType(design|code) / round / elapsedSec——与子代理
-  // 的 turn/maxTurns 而非（评审无子回合预算语义）。
-  if (entry.role === "advisor") {
-    const base = { id: String(entry.id), role: entry.role, reviewType: entry.reviewType ?? null, round: entry.round ?? entry.run?.round ?? null }
-    if (entry.model != null) base.model = entry.model
-    if (entry.startedAt) base.elapsedSec = Math.max(0, Math.round((Date.now() - entry.startedAt) / 1000))
-    return base
-  }
-  const base = { id: String(entry.id), role: entry.role }
-  if (entry.status === "running") {
-    base.model = entry.model ?? null
-    base.elapsedSec = entry.startedAt ? Math.max(0, Math.floor((Date.now() - entry.startedAt) / 1000)) : 0
-    base.turn = entry.turn ?? 0
-    base.maxTurns = entry.maxTurns ?? 0
-    // AGENT-LOOP-SUBAGENT.md §6.7.2：touched files 摘要（T-SF1..4——新字段追加——既有字段零破坏）
-    Object.assign(base, touchedSummary(entry, cwd))
-  } else if (entry.status === "queued") {
-    // AGENT-LOOP-SUBAGENT.md §6.7.2 T-SF2b：未启动——确定性占位（不崩；无对象可读）
-    base.touched = "—（未启动）"
-  }
-  return base
-}
-
-export function executeStatusAction(args, ctx) {
-  // #46（批 TOOLFACE-FIXES ①——设计 AGENT-LOOP-SUBAGENT.md §6.25 ①）：七动作族 depth 门收口——
-  // status 与 observe/send/escalate/cancel/panel freeze 同为 depth-0 专有（子代无自有异步池）；
-  // 缺门时子代静默空 overview（把「不可用」读成「无在飞」）。族锚取现行可解析节号（§6.7.2）。
-  if ((ctx.depth ?? 0) > 0) {
-    return JSON.stringify({ status: "error", error: "status is only available at depth 0 — a child agent has no async pool of its own" })
-  }
-  const agent = ctx.agent
-  const map = getAsyncPool(agent, "subagent") ?? new Map()
-  const advisors = getAsyncPool(agent, "advisor") ?? new Map()
-  const queue = agent._asyncQueue ?? []
-  const queuedPosition = (id) => {
-    const i = queue.findIndex((e) => String(e.id) === id)
-    return i >= 0 ? i + 1 : undefined
-  }
-  const { id } = args ?? {}
-  if (id !== undefined && id !== null && String(id) !== "") {
-    const key = String(id)
-    // §11.2 D-24b: by-id queries fall through to the advisor pool (shared counter —
-    // ids are unique across both pools; role identifies the kind).
-    const entry = map.get(key) ?? advisors.get(key)
-    if (!entry) {
-      // Wording kept exact — locked by subagent-async/tool tests (unknown-id error
-      // semantics); an unknown id simply names neither pool (the pools share the
-      // id counter, so the message stays unambiguous).
-      return JSON.stringify({ id: key, status: "error", error: `unknown async subagent id: ${key}` })
-    }
-    const target = statusFields(entry, agent.cwd)
-    if (entry.status === "running") return JSON.stringify({ ...target, status: "running" })
-    if (entry.status === "queued") {
-      // §20 F-SD4/D-SD3b：waiting 语义对模型可见——排队原因（冲突对象/依赖对象）随
-      // status 返回；纯槽满等位（kind slot）无 waiting 字段（position 已足够）。
-      const blk = describeBlockers(agent, entry)
-      const out = { ...target, status: "queued", position: queuedPosition(key) ?? entry.position }
-      if (blk.kind !== "slot") {
-        out.waiting = blk.kind === "depc" ? "dependency-cancelled" : "waiting-deps"
-        out.reason = blk.detail
-      }
-      // §21.1 P-SL2（D-SL2）：停滞机械标记——池停滞时本任务所在闭环阻塞链随 status
-      // 返回（F-SL2——status 视图可显示停滞——模型可见——零正常路径字段变化）。
-      const stall = detectStall(agent)
-      if (stall) {
-        const chain = stall.chains.find((c) => c.task === entry)?.text
-        if (chain) out.stall = { chain, note: STALL_NOTE }
-      }
-      return JSON.stringify(out)
-    }
-    // done = settled during this turn and not yet consumed — the auto channel still
-    // delivers it (AGENT-LOOP-SUBAGENT.md §6.7.5: turn-end collection / the suspension digest — no fetch action).
-    target.status = "done"
-    target.done = true
-    if (entry.error) target.error = entry.error
-    target.note = "settled, not yet consumed — delivered by the auto channel (turn-end collection or the suspension digest injects it)"
-    return JSON.stringify(target)
-  }
-  const overview = { running: [], queued: [], done: [] }
-  const mapEntries = [...map.values(), ...advisors.values()]
-  for (const entry of mapEntries) {
-    if (entry.status === "running") overview.running.push(statusFields(entry, agent.cwd))
-    else if (entry.status === "queued") {
-      // §20：queued 条目补 waiting/reason（F-SD4——依赖/冲突原因模型可见）；
-      // AGENT-LOOP-SUBAGENT.md §6.7.2 T-SF2b：未启动占位（确定性——不崩）。
-      const blk = describeBlockers(agent, entry)
-      const row = statusFields(entry, agent.cwd)
-      row.position = queuedPosition(String(entry.id)) ?? entry.position
-      if (blk.kind !== "slot") {
-        row.waiting = blk.kind === "depc" ? "dependency-cancelled" : "waiting-deps"
-        row.reason = blk.detail
-      }
-      overview.queued.push(row)
-    }
-    else if (entry.done) overview.done.push({ id: String(entry.id), role: entry.role })
-  }
-  // §21.1 P-SL2（D-SL2）：停滞机械标记——overview 级标注（可显示停滞——F-SL2）——
-  // 链文本随视图返回（逐条——每 queued 条目一行——闭环可破环引导同挂）。
-  const stall = detectStall(agent)
-  if (stall) {
-    overview.stall = {
-      chains: stall.chains.map((c) => c.text),
-      note: STALL_NOTE,
-    }
-  }
-  return JSON.stringify({ overview })
-}
+import { settleConsultCheckpoint, settleTurnCheckpoint, resumedSendResult } from "./checkpoint.mjs"
 
 // ═══════════════════════════════════════════════════════════════════════════
-// SUBAGENT-OBSERVE-SEND（SUBAGENT-OBSERVE-SEND.md——CLI 端）
-// observe（D1——readonly 查询）+ send（D2——控制类豁免注入引导）——动作执行器。
-// 目标 = 父自身 spawn 的异步子代理池条目（_asyncSubagents——非 advisor/escalate——
-// 后者共享 id 计数但非"读写子代理"，错误路径明示）。
+// 查询面（status ∕ observe + 摘要助手族）：2026-09-28 拆分（Module Split Policy——498/499
+// 贴 500 硬限跨档）迁至 ./subagent-actions-query.mjs（verbatim）；本面 re-export 两执行器
+// 保 subagent.mjs 既有 import 面（subagent-panel 尾部 re-export 先例）。
 // ═══════════════════════════════════════════════════════════════════════════
-
-/** D1/N2 摘要形态：从子代理 _fullHistory（real 消息——pushReal 累积）倒序收最近 N 个
- *  assistant 回合的一行描述（newest-first；assistant 消息 = 一回合——带 tool_calls =
- *  工具轮、独立 content = 回复首行）。返回纯摘要非全量（N2 隔离——不把子代理噪音灌父）。 */
-function recentTurnLines(child, limit) {
-  const hist = child?._fullHistory
-  if (!Array.isArray(hist)) return []
-  const out = []
-  for (let i = hist.length - 1; i >= 0 && out.length < limit; i--) {
-    const m = hist[i]
-    if (m?.role !== "assistant") continue
-    const tcs = Array.isArray(m.tool_calls)
-      ? m.tool_calls.filter((t) => typeof t?.function?.name === "string")
-      : []
-    if (tcs.length) out.push(`tools: ${tcs.map((t) => t.function.name).join(", ")}`)
-    else if (typeof m.content === "string" && m.content.trim()) {
-      const first = m.content.trim().split(/\r?\n/).find((l) => l.trim())
-      out.push((first ?? m.content.trim()).slice(0, 120))
-    } else out.push("(assistant — no content)")
-  }
-  return out
-}
-
-function queuedPositionOf(agent, key) {
-  const i = (agent?._asyncQueue ?? []).findIndex((e) => String(e.id) === key)
-  return i >= 0 ? i + 1 : undefined
-}
-
-/** recent 参数钳制（默认 ~5 条摘要——可参数；钳到 1..20 防超长 N2 失控）。 */
-function clampRecent(n) {
-  const v = Number.parseInt(n, 10)
-  if (!Number.isFinite(v)) return 5
-  return Math.max(1, Math.min(20, v))
-}
-
-/**
- * subagent action:"observe"（D1——READONLY 查询，父回合内）：按 id 拉运行中异步子代理的
- * 最近活动快照——从 entry.childAgent（subagent-run.mjs start() 绑定）读**已落回合**摘要
- * （_fullHistory 最近 N 条）+ _touchedFiles + turn/maxTurns + status + **in-flight 当前
- * 工具**（评审 #1——从 dispatch runOne 维护的 child._inflightTools 读——非只读已落
- * history：卡在长工具调用时 history 无新回合、恰是 observe 要检测的卡死态）。返摘要非
- * 全量（N2）。observe = readonly——running/queued/done 均可查（done 终报 / queued 占位）。
- */
-export function executeObserveAction(args, ctx) {
-  if ((ctx.depth ?? 0) > 0) {
-    return JSON.stringify({ status: "error", error: "observe is only available at depth 0 — a child agent has no async pool of its own" })
-  }
-  const agent = ctx.agent
-  const id = args?.id
-  if (id === undefined || id === null || String(id) === "") {
-    return JSON.stringify({ status: "error", error: "observe requires the id of the async subagent to inspect (from the async spawn return) — pass the id; omitting it observes nothing" })
-  }
-  const key = String(id)
-  const entry = getAsyncPool(agent, "subagent")?.get(key)
-  if (!entry) {
-    if (getAsyncPool(agent, "advisor")?.has(key)) {
-      return JSON.stringify({ status: "error", error: `id ${key} is an async ADVISOR review — observe is for async subagents (read/edit children); track an advisor with action:'status' or wait for its auto-delivered report` })
-    }
-    return JSON.stringify({ status: "error", error: `unknown async subagent id: ${key}` })
-  }
-  const child = entry.childAgent
-  const out = { id: key, role: entry.role, status: entry.status }
-  if (entry.status === "running") {
-    out.turn = entry.turn ?? 0
-    out.maxTurns = entry.maxTurns ?? 0
-    Object.assign(out, touchedSummary(entry, agent.cwd))
-    // in-flight 当前工具（评审 #1）：child._inflightTools Set——dispatch runOne 在工具
-    // 执行前后维护——LLM 生成/工具间空隙为空；子代理 await 长工具调用时父回合可见它。
-    const inflight = child?._inflightTools
-    if (inflight instanceof Set && inflight.size > 0) out.currentTool = [...inflight]
-    const n = clampRecent(args?.recent)
-    out.recentTurns = recentTurnLines(child, n)
-    out.note = `observing running ${entry.role}#${key} — recentTurns newest-first (cap ${n}); currentTool shown only while a tool is executing (stuck detection); sent directions consume at the next turn boundary`
-  } else if (entry.status === "queued") {
-    out.position = queuedPositionOf(agent, key) ?? entry.position ?? null
-    out.note = "queued — not started yet; no activity to observe (starts when the slot frees / dependencies clear; action:'send' targets running only)"
-  } else {
-    // done = settled this turn, not yet consumed — final report rides the auto channel.
-    out.done = true
-    out.turn = entry.turn ?? 0
-    out.maxTurns = entry.maxTurns ?? 0
-    out.recentTurns = child ? recentTurnLines(child, clampRecent(args?.recent)) : []
-    out.note = "settled — the final report is delivered by the auto channel (turn-end collection or the suspension digest); observe returns the activity summary, not the full report (N2)"
-  }
-  return JSON.stringify(out)
-}
+export { executeStatusAction, executeObserveAction } from "./subagent-actions-query.mjs"
 
 /**
  * subagent action:"send"（D2——控制类豁免，同 cancel/panel-freeze——父回合内显式调用即
@@ -308,6 +62,7 @@ export function executeSendAction(args, ctx) {
     if (getAsyncPool(agent, "advisor")?.has(key)) {
       return JSON.stringify({ status: "error", error: `id ${key} is an async ADVISOR review — send is for async subagents; you cannot inject direction into a running review — track it with action:'status' (role:"advisor") or wait for its report to arrive automatically` })
     }
+    if (settleConsultCheckpoint(agent, key, message)) return resumedSendResult(key, "consult") // 检查点兑现 ②（会诊会话）
     return JSON.stringify({ status: "error", error: `unknown async subagent id: ${key}` })
   }
   if (entry.done || entry.cancelled) {
@@ -318,6 +73,7 @@ export function executeSendAction(args, ctx) {
   }
   entry._injected ??= []
   entry._injected.push(String(message).trim())
+  if (settleTurnCheckpoint(entry)) return resumedSendResult(key, entry.role ?? "subagent") // 检查点兑现 ①（池条目）
   return JSON.stringify({
     id: key,
     status: "delivered",
@@ -337,7 +93,7 @@ export { executePanelAction } from "./subagent-panel.mjs"
 
 /**
  * subagent action:"escalate"（AGENT-LOOP-SUBAGENT.md §6.7 D-M4——退役 escalate 工具语义原样，ESCALATE.md；
- * §25 D-R17b——R17：缺省 async——后台飞刀 + settle 三分类 digest——async:false 保
+ * ESCALATE.md §5 D-R17b——R17：缺省 async——后台飞刀 + settle 三分类 digest——async:false 保
  * 同步旧路径）。飞刀——交给 consultModels 池里更强模型（WRITE + 术后报告）。约束全
  * 保留：depth-0 only / 工程模式拒 / consultModels 空拒 / relay 前缀 `escalate#N/`
  * （与既有前缀同名——TUI 路由零改动）/ mutations merge 回父（async 路径在 settle 分类）。
@@ -380,7 +136,7 @@ export async function executeEscalateAction(args, ctx) {
 
   const tag = label(pick)
 
-  // §25 D-R17b (R17 — 决策点 ③): escalate 缺省 async — the launch returns an ack
+  // ESCALATE.md §5 D-R17b (R17 — 决策点 ③): escalate 缺省 async — the launch returns an ack
   // {id, role:"escalate", status:"running"|"queued"} and the flight runs in the
   // background (shared other pool; settle 三分类 → pending 单容器 digest——
   // ASYNC-RESULT-CONTAINER.md D2)。
@@ -414,7 +170,7 @@ export async function executeEscalateAction(args, ctx) {
       memory: parent.memory,
       role: "coder",
     })
-    child._historyWindow = RECORD_WINDOW_MESSAGES // TUI-OOM-ROOTCAUSE §23.3.1：子代理人读线窗口（四处创建点同置）
+    child._historyWindow = RECORD_WINDOW_MESSAGES // TUI-OOM-ROOTCAUSE·AGENT-LOOP.md §6.15：子代理人读线窗口（四处创建点同置）
     child._logId = escId // LOGGING：子内事件归属（escalate#N）
     // SUBAGENT-UPSTREAM-CHANNEL（§6.27.4 W2——escalate **sync**：单向；工具返回注走同步形）。
     child._upstream = { parent, label: escId, sync: true }
@@ -428,7 +184,7 @@ export async function executeEscalateAction(args, ctx) {
       // §2.5 #78 并入：escalate 子代理输出流式（VSC subagent-escalate 同款豁免）。
       streamOutput: true,
     }
-    // Continue 经 runWithContinue（§7.2 D3，主会话同等 y/n 面板）：resume:true 不重注入
+    // Continue 经 runWithContinue（docs/cli/design/TUI.md §6.8 D3，主会话同等 y/n 面板）：resume:true 不重注入
     // task 文本（setup 跳 input）且保留 child history + mutation 记账，刷新 turn 预算；
     // 无权限 handler（headless）或拒绝 → 部分工作返回；continue 次数无限（每轮可拒）。
     // 残环批（2026-09-16）：飞刀询问名同规包装（`escalate#<id>/<tool>`——端侧键形解析的
@@ -465,7 +221,7 @@ export async function executeEscalateAction(args, ctx) {
     mergeChildMutations(parent, child)
     if (escErr) logEvent("child:error", { role: "escalate", id: escId, ms: Date.now() - escT0, err: errText(escErr.err, 200) })
     else logEvent("child:done", { role: "escalate", id: escId, ms: Date.now() - escT0, kind: String(report).includes(TURN_CAP_MARK) ? "partial" : "ok" })
-    // §7.2.3（round1 #2）：escalate 与 spawn 同享 ctx._subagentKey——同步完成精确冻
+    // docs/cli/design/TUI.md §6.8（round1 #2）：escalate 与 spawn 同享 ctx._subagentKey——同步完成精确冻
     // （relayPrefix 去尾 = `escalate#N`）。仅成功路径（escErr = 运行中途失败——不设
     // key——TUI 回落 escalate 角色启发式：escalate 串行 + 角色限定，天然精确——legacy
     // 行为不变——错误路径不触发冻结 round1 #1）。

package/agent-tools/subagent-async.mjs

@@ -4,7 +4,7 @@
  * consume-design + observe/send（SUBAGENT-OBSERVE-SEND）——AGENT-LOOP-SUBAGENT.md §6.7.5 check 已删；spawn 路径与
  * 工具面在 subagent.mjs；cancel 动作执行器与机械、管线在本模块——check 执行器随 AGENT-LOOP-SUBAGENT.md §6.7.5 删除）。
  * 内容：resolveChildProvider / async 池常量与域助手（ASYNC_POOL_LIMITS/poolDomainOf/
- * resolvePoolLimits/poolLimitsFor/runningPoolCount——§11.1）/ executeCancelAction +
+ * resolvePoolLimits/poolLimitsFor/runningPoolCount——AGENT-LOOP-ASYNC-POOL.md §6.10）/ executeCancelAction +
  * cancelAsyncSubagent（AGENT-LOOP-SUBAGENT.md §6.7.2 D-M6——工具与 TUI ⏹ 共用）/ runChildPipeline /
  * injectAsyncResult / buildChildRunOpts / mergeChildMutations / enqueueAsk（批 6——
  * _permQueue 审批/继续弹窗串行收 helper——消费位 subagent.mjs/subagent-spawn.mjs/
@@ -22,18 +22,20 @@ import { pushReal } from "../context.mjs"
 import { offloadToolResult } from "../agent/helpers.mjs"
 import { logEvent } from "../log.mjs"
 import { digestBudgetOver, persistOverflowReport } from "./digest-budget.mjs"
-// 群 B 批 B5（§22 D-DG4）：预算单源迁出（digest-budget.mjs）——原处 re-export 保测试
+// 群 B 批 B5（AGENT-LOOP.md §6.14 D-DG4）：预算单源迁出（digest-budget.mjs）——原处 re-export 保测试
 // 导入面零改（DIGEST_INJECT_BUDGET / _setDigestOffloadDirForTest）。
 export { DIGEST_INJECT_BUDGET, _setDigestOffloadDirForTest } from "./digest-budget.mjs"
 import {
   dependentLabels, maybeRefillAsync, refreshQueuedTokens,
 } from "./subagent-scheduler.mjs"
-// §11.2 (R13): advisor-pool cancel fallback + mutation logging for merged
+// §6.10 (R13): advisor-pool cancel fallback + mutation logging for merged
 // code（lazy function-level cycle——advisor-async → async-settle → scheduler →
 // 本模块——全函数级绑定无求值期依赖，环安全）。
 import { cancelAsyncAdvisor, noteMutations, refreshAdvisorQueuedTokens } from "./advisor-async.mjs"
 // #94（VSC 侧并入——异步机械族）：池读取载体吸收 + 墓碑写入单点（原 inline 写收口）。
 import { getAsyncPool, tombstoneOf, writeTombstone } from "./async-settle.mjs"
+// #9（TOOLS.md §6.19）：后台 bash 任务注入器（digest 单点族按 role="bg" 分发到本档）。
+import { injectBgResult } from "./bash-async.mjs"
 
 // agent-tools 共享：并行子代理的审批/继续弹窗经 owner 上命名 promise 链串行——
 // 永不叠弹窗（返回链供调用方 .then 续接）。
@@ -44,7 +46,7 @@ export function enqueueAsk(owner, key, ask) {
 }
 
 // Async pool limits per role domain (AGENT-LOOP-ASYNC-POOL.md §6.10 — R14, 2026-09-06):
-// the old single cap (ASYNC_SUBAGENT_LIMIT = 4, §15 D-A4) evolved into two
+// the old single cap (ASYNC_SUBAGENT_LIMIT = 4, AGENT-LOOP-SUBAGENT.md §6.7.3 D-A4) evolved into two
 // independent pools — eng-coder 4 / other roles 4 (user ruling "eng-coder 四路，
 // 其他 4 路") — a full engCoder pool never blocks an explore spawn and vice versa
 // (same-domain cap still 4, cross-domain total up to 8). The per-turn check
@@ -56,7 +58,7 @@ export function enqueueAsk(owner, key, ask) {
 export const ASYNC_POOL_LIMITS = { engCoder: 4, other: 4 }
 
 /**
- * Role → pool domain (single source of truth — §11.1 修正 #8): the CLI role
+ * Role → pool domain (single source of truth — §6.10 修正 #8): the CLI role
  * whitelist is subagent.mjs's ROLES = { explore, plan, coder, eng-coder, eng-designer }
  * (mode-filtered: normal → explore/plan/coder, engineering → explore/eng-designer/eng-coder).
  * eng-coder → engCoder pool; every other role (including unknown roles — fail-safe)
@@ -116,7 +118,7 @@ function warnPoolFallback(what, sig) {
   console.warn(`[config] agent.poolLimits: ${what} — must be a positive integer ≥1 — falling back to default ${JSON.stringify(ASYNC_POOL_LIMITS)}`)
 }
 
-/** Running count within ONE pool domain (口径同 §15 D-A1/T6: queued 与已完成不计入；
+/** Running count within ONE pool domain (口径同 AGENT-LOOP-SUBAGENT.md §6.7.3 D-A1/T6: queued 与已完成不计入；
  *  条目带 _pool 域字段——spawn 时 poolDomainOf(role) 落位；缺字段（手工/旧条目）按
  *  other——既有 coder 域测试语义不变)。 */
 export function runningPoolCount(parent, pool) {
@@ -194,7 +196,7 @@ export function cancelAsyncSubagent(agent, id) {
     entry.done = true
     entry.status = "done"
     map.delete(key)
-    // §20 D-SD5 终态墓碑：queued 取消（无 settle 事件——出队即终态）——依赖者经
+    // AGENT-LOOP-SUBAGENT.md §6.9 D-SD5 终态墓碑：queued 取消（无 settle 事件——出队即终态）——依赖者经
     // 墓碑查得 cancelled 分支（round1 #4——cancel 返回时即重估标注）。
     writeTombstone(agent, key, "cancelled", entry.role)
     // af 批 F-6（§6.11 日志面）：queued 取消不经 settle ⇒ 出队点直记一条 ev:cancelled
@@ -205,7 +207,7 @@ export function cancelAsyncSubagent(agent, id) {
   }
   // running：标记 + 条目 abort——settle finally 跑 cancelled 分支（移除 + stopped + 提醒）
   entry.cancelled = true
-  // §20.3 站点 #11（第 24 批）：定向中止 = cancel（reason 载荷——下游可判「谁杀的」）
+  // AGENT-LOOP-SUBAGENT.md §6.12 站点 #11（第 24 批）：定向中止 = cancel（reason 载荷——下游可判「谁杀的」）
   entry.controller?.abort?.({ abortTrigger: "cancel", abortDetail: "subagent-cancel" })
   return { id: key, status: "cancelled" }
 }
@@ -238,7 +240,7 @@ export function cancelSyncChild(agent, key) {
 }
 
 /** subagent action:"cancel" (AGENT-LOOP-SUBAGENT.md §6.7.2 D-M6): depth-0 main-session control only.
- *  §20 D-SD5/round1 #4（queued 依赖取消——无 settle 事件）：出队后**返回即**重估
+ *  §6.9 D-SD5/round1 #4（queued 依赖取消——无 settle 事件）：出队后**返回即**重估
  *  依赖者——依赖者留 queued 标 dependency cancelled（refreshQueuedTokens 发更新块头
  *  token）+ 工具结果内注依赖者（模型可见——工具结果内——round1 #4 明示通道）+ 补位
  *  （AUTO 档依赖者自动启动/槽位竞态释放）。被取消条目自身发 ⟦ev⟧cancelled 移除等待块。 */
@@ -253,7 +255,7 @@ export function executeCancelAction(args, ctx) {
   const key = String(id)
   const agent = ctx.agent
   const entry = getAsyncPool(agent, "subagent")?.get(key)
-  // §11.2 (②-6b): an id that names no async SUBAGENT falls through to the
+  // §6.10 (②-6b): an id that names no async SUBAGENT falls through to the
   // async ADVISOR pool (the background reviews share the cancel surface — ⏹ on
   // an advisor block / action:'cancel' with an advisor id abort that review).
   // af 批 fix 轮（T-AF2 终态确认面 · §6.11 第 3 条「幂等」）：已出队取消的 advisor id
@@ -277,7 +279,7 @@ export function executeCancelAction(args, ctx) {
   const hadDependents = entry ? dependentLabels(agent, key).length > 0 : false
   const result = cancelAsyncSubagent(agent, key)
   if (wasQueued && result.status === "cancelled" && result.was === "queued" && entry) {
-    // §20 D-SD3b：取消/出队 → 移除等待块（不冻结——TUI routeSubToken cancelled 分支）
+    // §6.9 D-SD3b：取消/出队 → 移除等待块（不冻结——TUI routeSubToken cancelled 分支）
     ctx.callbacks?.onToken?.(`${entry.relayPrefix}⟦ev⟧cancelled\x1e`)
     // 依赖者标注 + 位置前移 + AUTO 自动启动（round2 #3：AUTO 档才启动——手动留 queued）
     maybeRefillAsync(agent)
@@ -297,10 +299,10 @@ export function executeCancelAction(args, ctx) {
 }
 
 /**
- * 共享 post-spawn 管线（阻塞与 async 同一条——§15 D-A1 "全不变"）：turn-cap continue
+ * 共享 post-spawn 管线（阻塞与 async 同一条——AGENT-LOOP-SUBAGENT.md §6.7.3 D-A1 "全不变"）：turn-cap continue
  * 循环 → 拒绝降级 partial 返回 → MIN_REPORT_CHARS 扩写 → eng-coder mutation merge →
  * designId 后缀。onDeclined 在此（两路同一形态）——只有 askContinue 不同：阻塞经权限
- * 面板询问；async 永不弹面板（自动拒绝；engineering && AUTO 自动 resume——§15 D-A3）。
+ * 面板询问；async 永不弹面板（自动拒绝；engineering && AUTO 自动 resume——§6.7.3 D-A3）。
  */
 export async function runChildPipeline(child, input, childOpts, childRunOpts, { parent, role, args, askContinue }) {
   const declined = { partial: null }
@@ -344,29 +346,32 @@ export async function runChildPipeline(child, input, childOpts, childRunOpts, {
 }
 
 // ─── BATCH-3-STRUCTURE F-2：digest 注入批量预算（2026-09-09）───
-// §22 D-DG1（群 B 批 B5）：常量 / 判超 / 记账 / 落盘四处合一入 digest-budget.mjs 叶子模块
+// AGENT-LOOP.md §6.14 D-DG1（群 B 批 B5）：常量 / 判超 / 记账 / 落盘四处合一入 digest-budget.mjs 叶子模块
 // （四族共享单源——D2）；本文件保留 re-export（顶部）与经本入口的三族注入器接线。
 
 /**
  * Inject one settled async entry into the parent history as a user-role reminder
  * (AGENT-LOOP-ASYNC-POOL.md §6.8 D-S3 — the auto channel, sole consumption path since AGENT-LOOP-SUBAGENT.md §6.7.5: turn-end
  * collection (collectSettledAsync, agent.mjs) and the run-start _pendingAsyncResults
- * injection; the message shape is identical to the §15 collector's). Consumed =
+ * injection; the message shape is identical to the §6.7.3 collector's). Consumed =
  * the caller removes the entry from its container; no double-inject across the
  * two paths (D-S3 "inject once" invariant).
  */
 export async function injectAsyncResult(agent, entry) {
+  // #9：后台 bash 任务族（role="bg"）单列——专用注入器（状态行 + 尾截 + 全量在 log）；
+  // 本函为 digest 注入单点族成员，消费面（run-start pending / 端壳残余注入）零改。
+  if (entry.role === "bg") return injectBgResult(agent, entry)
   const body = entry.error ?? entry.report ?? "(no report)"
-  // F-2（BATCH-3-STRUCTURE）+ §22 D-DG2（群 B 批 B5）：注入前查轮累计（单源）——超限条目不
+  // F-2（BATCH-3-STRUCTURE）+ AGENT-LOOP.md §6.14 D-DG2（群 B 批 B5）：注入前查轮累计（单源）——超限条目不
   // inline 全文，改清单行（全文经 persistOverflowReport 落盘——path 随行）。首条豁免
   // （used===0 不判超）：单条大报告 >64K offload 预览照旧——轮预算只约束累计。
   const raw = String(body)
   const over = digestBudgetOver(agent, raw.length)
   const preview = (over && await persistOverflowReport(raw, { tag: `async-subagent-${entry.id}` })) || await offloadToolResult(raw, `async-subagent-${entry.id}`)
-  // §11.2: advisor entries label themselves (role "advisor") — the digest
+  // §6.10: advisor entries label themselves (role "advisor") — the digest
   // reminder says "async advisor review #N finished" (T-24b2 shape); subagent
   // entries keep the legacy wording verbatim.
-  // §25 D-R17b (R17): escalate entries (role "escalate" — async 飞刀) label
+  // ESCALATE.md §5 D-R17b (R17): escalate entries (role "escalate" — async 飞刀) label
   // themselves the same way — the entry report body carries the merge/overlap
   // notes composed at settle (done/error classification — digest 指令语义 = 已
   // merge 报告可继续处置——动作域仍按消费回合档位——无族例外).
@@ -384,7 +389,7 @@ export async function injectAsyncResult(agent, entry) {
     role: "user",
     content: label,
   })
-  // §20 D-SD5 终态墓碑：本函数是全部自动注入路径的共享形态（回合尾 collect + 挂起
+  // §6.9 D-SD5 终态墓碑：本函数是全部自动注入路径的共享形态（回合尾 collect + 挂起
   // digest 首行注入）——注入即消费（调用方随即从容器移除）——dependsOn 引用该 id 的
   // 后续 spawn 视为已满足（T-SD14 消费终态语义——AGENT-LOOP-SUBAGENT.md §6.7.5 后 check 消费路径删除，本自动
   // 通道为唯一消费方；error 条目记 failed——依赖取消/失败分支照旧，不误标成功）。
@@ -438,7 +443,7 @@ export function mergeChildMutations(parent, child) {
     if (!parent._touchedFiles.includes(abs)) parent._touchedFiles.push(abs)
     merged.push(abs)
   }
-  // §11.2: merged code mutates the parent's state — log it for the stale
+  // §6.10: merged code mutates the parent's state — log it for the stale
   // scan of in-flight reviews (a review whose code changed under it is stale).
   noteMutations(parent, merged)
   if (parent._calledAdvisorThisRun) parent._calledAdvisorThisRun = false

package/agent-tools/subagent-panel.mjs

@@ -20,6 +20,27 @@ function blockKeyIn(container, key) {
   return entries.some((e) => `${e.role}#${e.id}` === key)
 }
 
+/** consult 子块键形态（#748）：`consult#<N>`（N = 子块 relay 号——会话条目 `childIds` 表元素同形）。 */
+function consultChildKey(key) {
+  const k = String(key ?? "")
+  return k.startsWith("consult#") && !k.includes("/") && k.length > "consult#".length
+}
+
+/** consult 子块消费判读（#748——与回收 ∥ 补发判据同源）：会话在跑（`_consultSessions` 内未 stopped
+ *  会话携该 relay 号）∥ 会话条目在 pending（`childIds` 携该号）⇒ **未消化**（报告未达模型——
+ *  冻结 ∥ 回收即破坏消化顺序）。非 consult 子块键 ⇒ 恒 false。 */
+function consultChildUndigested(agent, key) {
+  if (!consultChildKey(key)) return false
+  const id = String(key).slice("consult#".length)
+  for (const s of agent?._consultSessions?.values() ?? []) {
+    if (s.stopped !== true && (s.childIds ?? []).includes(id)) return true
+  }
+  for (const e of agent?._pendingAsyncResults ?? []) {
+    if (e?.role === "consult" && (e.childIds ?? []).includes(id)) return true
+  }
+  return false
+}
+
 /**
  * AGENT-LOOP-SUBAGENT.md §6.7.2 D-P3 冻结门控（安全）：仅允许冻结 awaitingDigest 且池（_asyncSubagents/
  * _asyncAdvisors——经 getAsyncPool accessor——D1）无对应运行条目 + pending 单容器
@@ -28,6 +49,7 @@ function blockKeyIn(container, key) {
  * - pending 仍有对应（报告未达模型）→ 拒绝（提前回收破坏消化顺序——T-P3）
  * - 不存在的 key / 仍 running / done 的块 → 拒绝（T-P4——running 块 settle 时自冻）
  * - 无面板（现算返 null）→ 拒绝（headless/VS Code——freeze 不可用——T-P5）
+ * - consult 子块（#748）：会话在跑 ∥ 会话条目在 pending（`childIds` 携该号）→ 拒绝（同判据——与回收 ∥ 补发同源）
  * 错误信息明确（模型可解释 + 自助修正）。返回 { ok:true } 或 { err }。
  */
 function panelFreezeGate(ctx, key) {
@@ -55,10 +77,14 @@ function panelFreezeGate(ctx, key) {
     return { err: `block ${key} still has a live pool entry — it is NOT a digested-stuck block (freeze refused; status action shows the pool)` }
   }
   // ASYNC-RESULT-CONTAINER.md D2：pending 单容器（四族统一——原 escalate/consult
-  // 独立族退役）。
-  if (blockKeyIn(ctx.agent._pendingAsyncResults, key)) {
+  // 独立族退役）。#748：consult 子块键不经裸键比对（会话条目键 `consult#<sessionId>` 与
+  // 子块键可数字撞键）——改判消费判据（会话在跑 ∥ 会话条目在 pending——与回收 ∥ 补发同源）。
+  if (!consultChildKey(key) && blockKeyIn(ctx.agent._pendingAsyncResults, key)) {
     return { err: `block ${key} is still genuinely awaiting digestion — its report is still pending and has NOT reached the model yet; freezing now would break the digestion order (wait for the digest run, which reclaims it automatically)` }
   }
+  if (consultChildUndigested(ctx.agent, key)) {
+    return { err: `block ${key} belongs to a consultation whose digest has not been consumed — the session is still running, or its session entry is still pending (freeze refused; the block is reclaimed at the consumption window)` }
+  }
   return { ok: true }
 }
 
@@ -151,8 +177,11 @@ export function executePanelAction(args, ctx) {
       // 读时交叉（round1 #3）：pending/池均无对应 = 报告已消化（注入即从两者移除）——
       // 块驻留 = 状态滞后——digested:true（freeze 候选——模型可定位异常块）。
       // ASYNC-RESULT-CONTAINER.md D2：pending 单容器参与比对（四族统一）。
-      out.digested = !blockKeyIn(agent._pendingAsyncResults, b.key)
-        && !blockKeyIn(getAsyncPool(agent, "subagent"), b.key) && !blockKeyIn(getAsyncPool(agent, "advisor"), b.key)
+      // #748：consult 子块按消费判据（会话在跑 ∥ 会话条目在 pending ⇒ 未消化）——与门控同源。
+      out.digested = consultChildKey(b.key)
+        ? !consultChildUndigested(agent, b.key)
+        : !blockKeyIn(agent._pendingAsyncResults, b.key)
+          && !blockKeyIn(getAsyncPool(agent, "subagent"), b.key) && !blockKeyIn(getAsyncPool(agent, "advisor"), b.key)
     }
     return out
   })