thincoder 0.12.59 → 0.12.60

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

@@ -1,10 +1,12 @@
 /**
- * subagent-async.mjs — async subagent 机械 + 共享 post-spawn 管线 + check/cancel 动作执行器
- * （AGENT-LOOP.md §19：subagent 单工具六动作 spawn/check/status/escalate/cancel/panel——
- * spawn 路径与工具面在 subagent.mjs；check/cancel 动作执行器与机械、管线在本模块）。
- * 内容：resolveChildProvider / async 常量（ASYNC_SUBAGENT_LIMIT/MAX_ASYNC_CHECKS）/
- * executeCheckAction / executeCancelAction + cancelAsyncSubagent（§19.5 D-M6——工具与
- * TUI ⏹ 共用）/ runChildPipeline / injectAsyncResult / buildChildRunOpts / mergeChildMutations。
+ * subagent-async.mjs — async subagent 机械 + 共享 post-spawn 管线 + cancel 动作执行器
+ * （AGENT-LOOP.md §19：subagent 单工具多动作——spawn/status/escalate/cancel/panel/
+ * consume-design + observe/send（SUBAGENT-OBSERVE-SEND）——§19.8 check 已删；spawn 路径与
+ * 工具面在 subagent.mjs；cancel 动作执行器与机械、管线在本模块——check 执行器随 §19.8 删除）。
+ * 内容：resolveChildProvider / async 池常量与域助手（ASYNC_POOL_LIMITS/poolDomainOf/
+ * resolvePoolLimits/poolLimitsFor/runningPoolCount——§24 D-24a）/ executeCancelAction +
+ * cancelAsyncSubagent（§19.5 D-M6——工具与 TUI ⏹ 共用）/ runChildPipeline /
+ * injectAsyncResult / buildChildRunOpts / mergeChildMutations。
  * 拆分（2026-09-05——Module Split Policy §20.9——纯迁移零行为变化）：§20 调度器 + 文件域
  * 组 → ./subagent-scheduler.mjs（尾部 re-export 保测试动态 import 面——queueRunnable/
  * describeBlockers）；status/panel/escalate 动作执行器 → ./subagent-actions.mjs。
@@ -17,13 +19,92 @@ import { runWithContinue, TURN_CAP_MARK } from "../agent/spawn-child.mjs"
 import { pushReal } from "../context.mjs"
 import { offloadToolResult } from "../agent/helpers.mjs"
 import {
-  describeBlockers, dependentLabels, detectStall, maybeRefillAsync, refreshQueuedTokens, STALL_NOTE,
+  dependentLabels, maybeRefillAsync, refreshQueuedTokens,
 } from "./subagent-scheduler.mjs"
+// §24 D-24b (R13): advisor-pool cancel fallback + mutation logging for merged
+// code（lazy function-level cycle——advisor-async → async-settle → scheduler →
+// 本模块——全函数级绑定无求值期依赖，环安全）。
+import { cancelAsyncAdvisor, noteMutations } from "./advisor-async.mjs"
 
-// Async subagent limits (AGENT-LOOP.md §15 D-A4): mechanical concurrency cap for
-// background spawns + the per-turn check budget (consult-style loop guard).
-export const ASYNC_SUBAGENT_LIMIT = 4
-export const MAX_ASYNC_CHECKS = 3
+// Async pool limits per role domain (AGENT-LOOP.md §24 D-24a — R14, 2026-09-06):
+// the old single cap (ASYNC_SUBAGENT_LIMIT = 4, §15 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
+// budget was deleted with the check action (§19.8 — results arrive only via the
+// auto channel; no loop guard needed).
+// ⚠ 与 config.mjs DEFAULTS.agent.poolLimits 逐键同值（loadConfig/settings 默认源）——
+// 耦合锚 T-24a4 断言锁住——勿单侧改默认。
+export const ASYNC_POOL_LIMITS = { engCoder: 4, other: 4 }
+
+/**
+ * Role → pool domain (single source of truth — §24 D-24a 修正 #8): the CLI role
+ * enum/assembly table is subagent.mjs's ROLES = { explore, plan, coder, eng-coder }
+ * (mode-filtered: normal → explore/plan/coder, engineering → explore/plan/eng-coder).
+ * eng-coder → engCoder pool; every other role (including unknown roles — fail-safe)
+ * → other pool. escalate spawns its expert internally (role "coder" — other pool).
+ */
+export function poolDomainOf(role) {
+  return role === "eng-coder" ? "engCoder" : "other"
+}
+
+/**
+ * Per-domain limit validation (T-24a4): each key must be a positive integer ≥1 —
+ * invalid (0 / -1 / "abc") or absent keys fall back to that domain's default (4),
+ * independent per key (a partial config — e.g. settings set
+ * agent.poolLimits.engCoder — takes effect with the untouched domain at default).
+ * Non-object raw (missing / string / number / array) → both domains at default.
+ */
+export function resolvePoolLimits(raw) {
+  const limits = { ...ASYNC_POOL_LIMITS }
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return limits
+  for (const key of Object.keys(ASYNC_POOL_LIMITS)) {
+    const v = raw[key]
+    if (Number.isInteger(v) && v >= 1) limits[key] = v
+  }
+  return limits
+}
+
+/** One-time fallback warn dedupe (warnedModels / warnedContextProviders precedent). */
+const warnedPoolConfigs = new Set()
+
+/**
+ * Effective per-domain limits — read at EVERY pool admission (D-24a 生效语义:
+ * 不缓存常驻——配置变更即生效下个 spawn; /config 与 settings 保存经 reloadConfig /
+ * 热应用替换 agent.config——本函数每次读最新值). Invalid present values emit ONE
+ * warning per value shape, then fall back (timeoutMs precedent).
+ */
+export function poolLimitsFor(agent) {
+  const raw = agent?.config?.agent?.poolLimits
+  const limits = resolvePoolLimits(raw)
+  if (raw !== undefined && raw !== null && (typeof raw !== "object" || Array.isArray(raw))) {
+    warnPoolFallback(`poolLimits has invalid shape (${JSON.stringify(raw)})`, "shape:" + JSON.stringify(raw))
+    return limits
+  }
+  if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+    for (const key of Object.keys(ASYNC_POOL_LIMITS)) {
+      const v = raw[key]
+      if (v !== undefined && !(Number.isInteger(v) && v >= 1)) {
+        warnPoolFallback(`poolLimits.${key} = ${JSON.stringify(v)}`, `${key}:` + JSON.stringify(v))
+      }
+    }
+  }
+  return limits
+}
+
+function warnPoolFallback(what, sig) {
+  if (warnedPoolConfigs.has(sig)) return
+  warnedPoolConfigs.add(sig)
+  console.warn(`[config] agent.poolLimits: ${what} — must be a positive integer ≥1 — falling back to default ${JSON.stringify(ASYNC_POOL_LIMITS)} (AGENT-LOOP.md §24 D-24a)`)
+}
+
+/** Running count within ONE pool domain (口径同 §15 D-A1/T6: queued 与已完成不计入；
+ *  条目带 _pool 域字段——spawn 时 poolDomainOf(role) 落位；缺字段（手工/旧条目）按
+ *  other——既有 coder 域测试语义不变)。 */
+export function runningPoolCount(parent, pool) {
+  return [...(parent?._asyncSubagents?.values() ?? [])]
+    .filter((e) => e.status === "running" && (e._pool ?? "other") === pool).length
+}
 
 /**
  * Resolve the sub-agent's provider from a model override string (shared with the
@@ -60,160 +141,6 @@ export function resolveChildProvider(parent, modelArg) {
   return { ...parent.provider, model: modelArg }
 }
 
-/** Wait for an async entry to settle (or the parent signal to abort), parked on
- *  the agent's waiter list — the entry settle finally wakes every waiter (same
- *  pattern as consult_check's session waiters). Returns "aborted" on signal. */
-function wakeOnAsyncSettle(agent, ctx) {
-  return new Promise((resolve) => {
-    const cleanup = () => {
-      const i = (agent._asyncWaiters ?? []).indexOf(w)
-      if (i >= 0) agent._asyncWaiters.splice(i, 1)
-      ctx.signal?.removeEventListener("abort", onAbort)
-    }
-    const w = () => { cleanup(); resolve("settled") }
-    const onAbort = () => { cleanup(); resolve("aborted") }
-    ;(agent._asyncWaiters ??= []).push(w)
-    if (ctx.signal) {
-      if (ctx.signal.aborted) { onAbort(); return }
-      ctx.signal.addEventListener("abort", onAbort, { once: true })
-    }
-  })
-}
-
-/**
- * subagent action:"check" (§19 — the retired subagent_check's semantics verbatim,
- * AGENT-LOOP.md §15 D-A2): fetch async subagent results.
- * - id omitted → the next completed child in ARRIVAL order (first finished first)
- * - id given → block until THAT child finishes (queued items wait for their start)
- * - n (required) → 1-based read counter, strictly incrementing per run (loop
- *   guard); capped at MAX_ASYNC_CHECKS per turn — beyond that, use the turn-end
- *   auto-wait. Errors never consume results.
- * Consumed entries are deleted from the map — a re-check of the same id is the
- * same "unknown async subagent id" error (T12).
- */
-export async function executeCheckAction(args, ctx) {
-  const agent = ctx.agent
-  const map = agent._asyncSubagents ?? new Map()
-  const { id, n } = args ?? {}
-  // Strict 1-based incrementing read counter (D-A2, review #1): out-of-order /
-  // repeated n is rejected WITHOUT consuming a result (T14).
-  const lastN = agent._asyncCheckLastN ?? 0
-  if (!Number.isInteger(n) || n !== lastN + 1) {
-    return JSON.stringify({ status: "error", error: "invalid read counter — pass n = lastN+1" })
-  }
-  if (n > MAX_ASYNC_CHECKS) {
-    return JSON.stringify({ status: "error", error: "check limit exceeded — use turn-end auto-wait for the rest" })
-  }
-  agent._asyncCheckLastN = n
-
-  let target = null
-  if (id !== undefined && id !== null && String(id) !== "") {
-    target = map.get(String(id))
-    // Unknown OR already-consumed ids (consumed entries are deleted) — same error (T12).
-    if (!target) return JSON.stringify({ id: String(id), status: "error", error: `unknown async subagent id: ${id}` })
-  }
-
-  // Block until the target settles (specific id / next completed in arrival order).
-  // §20（advisor code review 🟡 处置）：不可启动的 queued 条目会让阻塞等待永久悬挂
-  // （check 是同步工具调用——模型回合被钉死——仅 Ctrl+C 可解）。补位（refill）只由
-  // settle/cancel/spawn 事件驱动：**池内无 running 条目 = 无未来 settle 事件 = queued
-  // 条目永不启动**（槽满等位的 slot 条目在 running 归零时已被最后一次 settle 的 refill
-  // 启动——此时仍 queued 者必为不可启动：depc 锁定或阻塞源本身不可启动）。
-  for (;;) {
-    if (target) {
-      if (target.done) break
-      // 守卫 ①（target 级）：queued 目标在无 running 池中不可启动 → 立即返回（无论
-      // wait/depc——阻塞源链底为 depc 的 wait 条目同样无 settle 可期）。
-      if (target.status === "queued" && !target.cancelled) {
-        const blk = describeBlockers(agent, target)
-        if (blk.kind === "depc") {
-          return JSON.stringify({
-            id: String(target.id), status: "queued", waiting: "dependency-cancelled",
-            reason: blk.detail,
-            note: "check would block forever — this task is locked by a cancelled/failed dependency and will not start on its own; cancel it (action:'cancel') or run an AUTO session to release it (AGENT-LOOP.md §20 round2 #3)",
-          })
-        }
-        if (![...map.values()].some((e) => e.status === "running")) {
-          const qi = (agent._asyncQueue ?? []).indexOf(target)
-          const out = { id: String(target.id), status: "queued", position: qi >= 0 ? qi + 1 : undefined }
-          if (blk.detail) out.reason = blk.detail
-          // §21.1 P-SL2（D-SL2）：停滞机械检测——目标处于不可自行解除的等待闭包（无
-          // running + 每 queued 的 blocker 均闭包内 + 无 depc）→ 明确报错列本任务
-          // 阻塞链 + 引导 cancel 破环重派（F-SL2——非静默）；不满足停滞判据的形态
-          // （单 queued/depc 滞留/外逃 blocker）维持下方原守卫文本——零行为变化。
-          const stall = detectStall(agent)
-          if (stall) {
-            const chain = stall.chains.find((c) => c.task === target)?.text ?? stall.chains[0]?.text
-            out.stall = true
-            out.note = `scheduler stall — the queued tasks block each other in a closed wait loop that can never settle on its own:\n${chain}\n${STALL_NOTE}`
-          } else {
-            out.note = "check would block indefinitely — this queued task cannot start while the pool has no running task (starts are settle-driven); cancel it (action:'cancel') or make pool progress (AUTO session starts it on the next settle/refill)"
-          }
-          return JSON.stringify(out)
-        }
-      }
-      const woke = await wakeOnAsyncSettle(agent, ctx)
-      if (woke === "aborted") return JSON.stringify({ done: true, stopped: true })
-      continue
-    }
-    const completed = [...map.values()].filter((e) => e.done)
-    if (completed.length > 0) {
-      target = completed.sort((a, b) => (a._settleSeq ?? 0) - (b._settleSeq ?? 0))[0]
-      break
-    }
-    if (map.size === 0) return JSON.stringify({ done: true })
-    // 守卫 ②（arrival-order）：池内无 running（completed 已空 → 无 done）且仍有条目 →
-    // 全为 queued 且永不启动 → 立即返回明确错误（防无界悬挂——补 cancel 引导）。
-    if (![...map.values()].some((e) => e.status === "running")) {
-      // §21.1 P-SL2（D-SL2）：停滞机械检测——全 queued 且每 blocker 闭包内（无 depc 等
-      // 外部可解形态）→ 明确错误逐条列阻塞链（F-SL2——列链 + 引导 cancel 破环重派）；
-      // 不满足停滞判据的形态（单 queued/depc 滞留/外逃 blocker）维持原守卫文本——零变化。
-      const stall = detectStall(agent)
-      if (stall) {
-        return JSON.stringify({
-          status: "error",
-          error: `scheduler stall — the pool holds only queued tasks that block each other in closed wait loops; nothing can ever settle on its own:\n${stall.chains.map((c) => c.text).join("\n")}\n${STALL_NOTE}`,
-        })
-      }
-      const stuck = [...map.values()]
-        .map((e) => `${e.role}#${e.id}（${describeBlockers(agent, e).kind === "depc" ? "dependency-cancelled" : "blocked"}）`)
-        .join(", ")
-      return JSON.stringify({
-        status: "error",
-        error: `nothing will settle — the pool holds only queued task(s) that cannot start without a running task: ${stuck}; cancel them (action:'cancel') or make pool progress (AUTO session starts them on the next settle/refill)`,
-      })
-    }
-    const woke = await wakeOnAsyncSettle(agent, ctx)
-    if (woke === "aborted") return JSON.stringify({ done: true, stopped: true })
-  }
-
-  map.delete(String(target.id))
-  // §20（advisor code review 🟡 处置）：check 消费与挂起期 settle 的竞态——settle 在挂起
-  // 分支先把条目移交 _pendingAsyncResults（本 check 在途等待期间发生——digest 回合）——
-  // 消费时若条目已被移入 pending，反向清除（两消费点互斥——防下轮 prepareRun 重复注入
-  // ——D-S3"只注入一次"不变式——同一报告双送达违例）。
-  const pend = agent._pendingAsyncResults
-  if (Array.isArray(pend)) {
-    const pendIdx = pend.findIndex((x) => String(x.id) === String(target.id))
-    if (pendIdx >= 0) pend.splice(pendIdx, 1)
-  }
-  // §20 D-SD5 终态墓碑（T-SD14）：消费即终态——dependsOn 引用该 id 的条目视其终态
-  // 满足/标注（consumed-ok = 已满足；failed/cancelled = 依赖取消/失败分支）。写于
-  // 观察 cancelled/error 之后——取消/失败条目不被误记 consumed。
-  if (target.cancelled) {
-    const tombstones = (agent._asyncTombstones ??= new Map())
-    tombstones.set(String(target.id), { status: "cancelled", role: target.role })
-    // Cancelled entries are removed from the pool at their cancel — an in-flight
-    // check that held the entry object observes `cancelled` and reports the same
-    // unknown-id error a fresh check gets (nothing to consume; §19.5 T-M27).
-    return JSON.stringify({ id: String(target.id), status: "error", error: `unknown async subagent id: ${target.id}` })
-  }
-  const tombstones = (agent._asyncTombstones ??= new Map())
-  tombstones.set(String(target.id), { status: target.error ? "failed" : "consumed", role: target.role })
-  if (target.error) return JSON.stringify({ id: String(target.id), status: "error", error: target.error })
-  return JSON.stringify({ id: String(target.id), role: target.role, status: "done", report: target.report ?? "" })
-}
-
 /**
  * §19.5 D-M6 cancel 核心（工具路径与 TUI ⏹ 共用）：定向中止单个后台子代理，id 必填。
  * - queued 目标（未启动无 controller）：出队 + 后续 position 前移 + settle waiter
@@ -235,7 +162,7 @@ export function cancelAsyncSubagent(agent, id) {
   }
   if (entry.cancelled) return { id: key, status: "cancelled" } // abort already in flight — idempotent
   if (entry.status === "queued") {
-    // 出队 + position 释放/前移；settle 使在途 check waiter 终止（观察 cancelled）
+    // 出队 + position 释放/前移（§19.5 D-M6——无 abort）
     const queue = agent._asyncQueue ?? []
     const qi = queue.indexOf(entry)
     if (qi >= 0) {
@@ -251,7 +178,6 @@ export function cancelAsyncSubagent(agent, id) {
     const tombstones = (agent._asyncTombstones ??= new Map())
     tombstones.set(key, { status: "cancelled", role: entry.role })
     entry._settle?.()
-    for (const w of agent._asyncWaiters?.splice(0) ?? []) { try { w() } catch { /* noop */ } }
     return { id: key, status: "cancelled", was: "queued" }
   }
   // running：标记 + 条目 abort——settle finally 跑 cancelled 分支（移除 + stopped + 提醒）
@@ -276,6 +202,12 @@ export function executeCancelAction(args, ctx) {
   const key = String(id)
   const agent = ctx.agent
   const entry = agent._asyncSubagents?.get(key)
+  // §24 D-24b (②-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).
+  if (!entry && agent?._asyncAdvisors?.has(key)) {
+    return JSON.stringify(cancelAsyncAdvisor(agent, key))
+  }
   const wasQueued = entry?.status === "queued"
   // 依赖者快照（出队前——用于 AUTO 分支判定"是否有依赖者被本次取消波及"；note 组装在
   // refill 后按**仍 queued** 的实况重算——防 AUTO 已自动启动后文案称 "stay queued"）
@@ -350,22 +282,40 @@ export async function runChildPipeline(child, input, childOpts, childRunOpts, {
 
 /**
  * Inject one settled async entry into the parent history as a user-role reminder
- * (§17 D-S3 — single shared form for BOTH consumption points: turn-end collection
- * (collectSettledAsync, agent.mjs) and the run-start _pendingAsyncResults injection;
- * the message shape is identical to the §15 collector's). Consumed = the caller
- * removes the entry from its container; no double-inject across the two paths.
+ * (§17 D-S3 — the auto channel, sole consumption path since §19.8: turn-end
+ * collection (collectSettledAsync, agent.mjs) and the run-start _pendingAsyncResults
+ * injection; the message shape is identical to the §15 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) {
   const body = entry.error ?? entry.report ?? "(no report)"
   const preview = await offloadToolResult(String(body), `async-subagent-${entry.id}`)
+  // §24 D-24b: 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
+  // themselves the same way — the entry report body carries the merge/overlap
+  // notes composed at settle (done/error classification — digest 指令语义 = 已
+  // merge 报告可继续处置——动作域仍按消费回合档位——无族例外).
+  let label
+  if (entry.role === "advisor") {
+    label = `[System reminder: async advisor review #${entry.id} finished]\n${escapeXml(preview)}`
+  } else if (entry.role === "escalate") {
+    label = entry.error != null
+      ? `[System reminder: async escalate #${entry.id} ended with an error]\n${escapeXml(preview)}`
+      : `[System reminder: async escalate #${entry.id} finished — post-op report (mutations merged)]\n${escapeXml(preview)}`
+  } else {
+    label = `[System reminder: async subagent #${entry.id} (${entry.role}) finished]\n${escapeXml(preview)}`
+  }
   pushReal(agent, {
     role: "user",
-    content: `[System reminder: async subagent #${entry.id} (${entry.role}) finished]\n${escapeXml(preview)}`,
+    content: label,
   })
   // §20 D-SD5 终态墓碑：本函数是全部自动注入路径的共享形态（回合尾 collect + 挂起
   // digest 首行注入）——注入即消费（调用方随即从容器移除）——dependsOn 引用该 id 的
-  // 后续 spawn 视为已满足（T-SD14 同 check 消费语义；error 条目记 failed——依赖取消/
-  // 失败分支照旧，不误标成功）。
+  // 后续 spawn 视为已满足（T-SD14 消费终态语义——§19.8 后 check 消费路径删除，本自动
+  // 通道为唯一消费方；error 条目记 failed——依赖取消/失败分支照旧，不误标成功）。
   const tombstones = (agent._asyncTombstones ??= new Map())
   tombstones.set(String(entry.id), { status: entry.error != null ? "failed" : "consumed", role: entry.role })
 }
@@ -409,9 +359,14 @@ export function mergeChildMutations(parent, child) {
   // to the parent's guard state.
   if (!child._mutatedThisRun || !(child._touchedFiles?.length)) return false
   parent._mutatedThisRun = true
+  const merged = []
   for (const abs of child._touchedFiles ?? []) {
     if (!parent._touchedFiles.includes(abs)) parent._touchedFiles.push(abs)
+    merged.push(abs)
   }
+  // §24 D-24b: 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
   if (parent._verifiedThisRun) {
     parent._verifiedThisRun = false

package/src/agent-tools/subagent-panel.mjs

@@ -0,0 +1,153 @@
+/**
+ * subagent-panel.mjs — subagent action:"panel" 执行器（§19.6——2026-09-08 自
+ * subagent-actions.mjs 拆分——Module Split Policy：601 > 500 硬限跨档，§19.6 面板段
+ * verbatim 迁入 + ASYNC-RESULT-CONTAINER.md D1/D2 落地（池 accessor getAsyncPool +
+ * pending 单容器 _pendingAsyncResults 四族统一——escalate/consult 独立族退役））。
+ * 内容：executePanelAction（D-P2——readonly 视图面 + 门控 freeze）+ panelFreezeGate
+ * （D-P3 冻结门控）+ blockKeyIn（块归属判定随行）。
+ * subagent-actions.mjs 尾部 re-export executePanelAction 保 subagent.mjs 既有 import 面。
+ */
+import { getAsyncPool } from "./async-settle.mjs"
+
+/** 面板块 key（role#N）在池（Map——条目值）/pending 单容器（数组）中的归属判定。 */
+function blockKeyIn(container, key) {
+  const entries = container instanceof Map ? [...container.values()] : (container ?? [])
+  return entries.some((e) => `${e.role}#${e.id}` === key)
+}
+
+/**
+ * §19.6 D-P3 冻结门控（安全）：仅允许冻结 awaitingDigest 且池（_asyncSubagents/
+ * _asyncAdvisors——经 getAsyncPool accessor——D1）无对应运行条目 + pending 单容器
+ * （_pendingAsyncResults——D2）无对应条目的块（= 已消化驻留块——报告已入模型上下文
+ * ——pending 已消费——状态滞后——补发冻结不破坏任何顺序）。
+ * - pending 仍有对应（报告未达模型）→ 拒绝（提前回收破坏消化顺序——T-P3）
+ * - 不存在的 key / 仍 running / done 的块 → 拒绝（T-P4——running 块 settle 时自冻）
+ * - 无镜像 → 拒绝（headless/VS Code——freeze 不可用——T-P5）
+ * 错误信息明确（模型可解释 + 自助修正）。返回 { ok:true } 或 { err }。
+ */
+function panelFreezeGate(agent, key) {
+  const snap = agent._panelSnapshot
+  if (!Array.isArray(snap)) {
+    return { err: "panel unavailable — no CLI TUI panel mirror in this session (headless / VS Code / subagent contexts — freeze unavailable; panel is CLI-TUI-only, AC-P4)" }
+  }
+  const block = snap.find((b) => b.key === key)
+  if (!block) {
+    const live = snap.map((b) => `${b.key}(${b.status})`).join(", ")
+    return { err: `unknown panel block key: ${key} — the live panel holds: ${live || "(no blocks)"}` }
+  }
+  if (block.status !== "awaitingDigest") {
+    if (block.status === "done") {
+      return { err: `block ${key} is already done — nothing to freeze; it was (or is about to be) reclaimed into the conversation by the freeze sweep at the turn end / settle (only digested-stuck awaitingDigest blocks need a manual freeze)` }
+    }
+    if (block.status === "running") {
+      return { err: `block ${key} is still running — freeze only reclaims awaitingDigest blocks whose report is already digested; a running block freezes on its own settle (or stop it with action:'cancel' if it is a background async child)` }
+    }
+    return { err: `block ${key} is in state ${block.status} — freeze only reclaims awaitingDigest blocks whose report is already digested` }
+  }
+  if (blockKeyIn(getAsyncPool(agent, "subagent"), key) || blockKeyIn(getAsyncPool(agent, "advisor"), 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(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 — §17.5.5)` }
+  }
+  return { ok: true }
+}
+
+/**
+ * §19.6 subagent action:"panel"（D-P2——readonly 视图面 + 门控干预面——单动作双参，
+ * freeze 优先）：
+ * - view（缺省——返回镜像区块列表）：agent._panelSnapshot = TUI 面板镜像（块级
+ *   状态变更点由 subagent-blocks syncPanelSnapshot 同步刷新——与用户所见一致——
+ *   index.mjs 装配 state._agent）。awaitingDigest 条目**读时交叉**
+ *   _pendingAsyncResults/池 标注 digested（round1 #3——digested:true
+ *   = 报告已消化但块仍驻留——异常块——freeze 候选；模型可定位解释 UI 怪相）。
+ * - freeze:key（D-P3 门控通过 → 发 key + "/" + ⟦ev⟧done 哨兵字面 token——
+ *   onToken——TUI routeSubToken 冻结回收——落位复用 sub._freezeAt settle 锚点
+ *   splice，无锚点尾推兜底——§17.5.5 同口径——round1 #2）。
+ * 无镜像（headless/VS Code——D-P2 round1 #1：webview 无 state.subTasks 对应物——
+ * 7.2.3.2 #8 先例）→ view 恒降级池视图（双池经 getAsyncPool + pending 单容器
+ * 合成）+ no panel 注；freeze 报不可用。CLI-only 完整能力（AC-P4）。
+ */
+export function executePanelAction(args, ctx) {
+  const agent = ctx.agent
+  const freezeKey = (args?.freeze !== undefined && args?.freeze !== null && String(args.freeze) !== "")
+    ? String(args.freeze)
+    : null
+  // ── freeze 面（优先——D-P2 单动作双参互斥）──
+  if (freezeKey) {
+    if ((ctx.depth ?? 0) > 0) {
+      return JSON.stringify({ status: "error", error: "panel freeze is only available at depth 0 — a child agent has no panel of its own (AGENT-LOOP.md §19.6 D-P2)" })
+    }
+    const gate = panelFreezeGate(agent, freezeKey)
+    if (gate.err) return JSON.stringify({ status: "error", error: gate.err })
+    if (!ctx.callbacks?.onToken) {
+      return JSON.stringify({ status: "error", error: `panel mirror present but no token relay in this context — the freeze of ${freezeKey} cannot reach the TUI` })
+    }
+    // 门控通过 → 发 done 冻结事件（settle 同机制字面格式——TUI routeSubToken done
+    // 分支冻结回收——落位 _freezeAt settle 锚点 splice；无锚点（旧会话残留）时
+    // freezeSubTaskLines 尾推兜底——注明两种落位，模型不被误导（advisor 🟡1）。
+    ctx.callbacks.onToken(`${freezeKey}/⟦ev⟧done\x1e0\x1e0\x1edone\x1e`)
+    return JSON.stringify({
+      key: freezeKey,
+      status: "frozen",
+      note: "done freeze event issued — the TUI reclaimed the block into the conversation (spliced at its settle anchor when one is recorded, else appended at the current stream end — §17.5.5 same-rule position)",
+    })
+  }
+  // ── view 面（缺省——readonly）──
+  // 双参互斥（D-P2）：freeze 优先；显式 view:false 且无 freeze = 无请求可执行——报错。
+  if (args?.view === false) {
+    return JSON.stringify({ status: "error", error: "panel has nothing to do — view:false with no freeze key; pass freeze:'role#N' to reclaim a digested-stuck block, or omit view (defaults to true)" })
+  }
+  const snap = agent._panelSnapshot
+  if (!Array.isArray(snap)) {
+    // F-P3 降级：无镜像（headless/VS Code/子代理上下文——CLI TUI-only 完整能力）→
+    // 池视图（双池经 getAsyncPool——运行/排队条目 + pending 单容器待消化条目）
+    const blocks = []
+    const queue = agent._asyncQueue ?? []
+    for (const e of [...(getAsyncPool(agent, "subagent")?.values() ?? []), ...(getAsyncPool(agent, "advisor")?.values() ?? [])]) {
+      const b = { key: `${e.role}#${e.id}`, role: e.role }
+      if (e.status === "running") {
+        b.status = "running"
+        b.elapsedSec = e.startedAt ? Math.max(0, Math.floor((Date.now() - e.startedAt) / 1000)) : 0
+      } else if (e.status === "queued") {
+        b.status = "queued"
+        const qi = queue.indexOf(e)
+        b.position = qi >= 0 ? qi + 1 : (e.position ?? null)
+      } else {
+        b.status = "done" // 回合内 settle 未取——自动通道（回合尾 collect/挂起 digest）送达
+      }
+      blocks.push(b)
+    }
+    // ASYNC-RESULT-CONTAINER.md D2：pending 单容器（四族统一——原 escalate/consult
+    // 独立族退役）——族注记按 role 保留。
+    for (const e of agent._pendingAsyncResults ?? []) {
+      const note = e.role === "consult"
+        ? "consultation digest pending — injected at the next run start (§25 D-R17a)"
+        : e.role === "escalate"
+          ? "report pending — injected at the next run start (§25 D-R17b)"
+          : "report pending — injected at the next run start (§17)"
+      blocks.push({ key: `${e.role}#${e.id}`, role: e.role, status: "awaitingDigest", note })
+    }
+    return JSON.stringify({
+      degraded: true,
+      note: "no panel — this session has no CLI TUI panel mirror (headless / VS Code / subagent context — panel view is CLI-TUI-only, AC-P4); pool-derived view below; action:'status' shows the full pool",
+      panel: blocks,
+    })
+  }
+  const panel = snap.map((b) => {
+    const out = { key: b.key, role: b.role, status: b.status }
+    if (b.status === "running") {
+      out.elapsedSec = b.startedAt ? Math.max(0, Math.floor((Date.now() - b.startedAt) / 1000)) : 0
+    } else if (b.status === "awaitingDigest") {
+      // 读时交叉（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)
+    }
+    return out
+  })
+  return JSON.stringify({ panel })
+}