thincoder 0.12.58 → 0.12.60

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

@@ -0,0 +1,382 @@
+/**
+ * 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。
+ */
+import {
+  runAgent, escapeXml,
+  MIN_REPORT_CHARS, REPORT_CONTINUATION, DEFAULT_SUBAGENT_TURNS,
+} from "../agent.mjs"
+import { runWithContinue, TURN_CAP_MARK } from "../agent/spawn-child.mjs"
+import { pushReal } from "../context.mjs"
+import { offloadToolResult } from "../agent/helpers.mjs"
+import {
+  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 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
+ * VS Code port). Forms accepted:
+ *   "provider:model"  → the named provider with the named model
+ *   "provider"        → the named provider's configured model
+ *   "model"           → same provider as the parent, different model
+ *   "default"         → same as null: the parent's provider unchanged (explicit
+ *                       "use the default model" — 2026-09-05 user ruling; matched
+ *                       case-insensitively — parser-layer alias guard)
+ * null → parent's provider unchanged.
+ * API keys come from config.json only (env vars are not a key source).
+ */
+export function resolveChildProvider(parent, modelArg) {
+  if (!modelArg) return { ...parent.provider }
+  // "default" alias (2026-09-05 user ruling — ARCHITECTURE.md 子 agent 模型指定):
+  // the literal "default", matched case-insensitively, declares "no override →
+  // inherit the default model" — equivalent to null/omission (parent provider
+  // unchanged). Checked BEFORE the provider-name lookup so the alias is reserved
+  // (≡ omission — providers are not consulted) and never falls through to the
+  // model-name swap branch. Any other single-segment value keeps the legacy
+  // semantics below.
+  if (String(modelArg).toLowerCase() === "default") return { ...parent.provider }
+  const providers = parent.config?.providersList ?? []
+  const withKey = (p) => (p.apiKey?.trim() ? { ...p, apiKey: p.apiKey.trim() } : { ...p })
+  if (modelArg.includes(":")) {
+    const [pname, mname] = modelArg.split(":")
+    const p = providers.find((x) => x.name === pname)
+    if (!p) throw new Error(`subagent model: unknown provider "${pname}" (available: ${providers.map((x) => x.name).join(", ") || "none"})`)
+    return { ...withKey(p), model: mname || p.model }
+  }
+  const byName = providers.find((x) => x.name === modelArg)
+  if (byName) return withKey(byName)
+  return { ...parent.provider, model: modelArg }
+}
+
+/**
+ * §19.5 D-M6 cancel 核心（工具路径与 TUI ⏹ 共用）：定向中止单个后台子代理，id 必填。
+ * - queued 目标（未启动无 controller）：出队 + 后续 position 前移 + settle waiter
+ *   → { id, status:"cancelled", was:"queued" }——无 abort（T-M27）
+ * - running 目标：置 entry.cancelled + 条目 controller abort（child runAgent signal）
+ *   → settle finally 跑 cancelled 分支（⟦ev⟧stopped 冻结 + 模型提醒；不入 pending/
+ *   不直注入）→ { id, status:"cancelled" }（T-M19）
+ * - 未知/已完成 id → error（T-M20）；重复 cancel 幂等（abort 已在途）
+ */
+export function cancelAsyncSubagent(agent, id) {
+  const key = String(id)
+  const map = agent._asyncSubagents ?? new Map()
+  const entry = map.get(key)
+  if (!entry) {
+    return { id: key, status: "error", error: `unknown async subagent id: ${key}` }
+  }
+  if (entry.done) {
+    return { id: key, status: "error", error: `async subagent #${key} has already finished — nothing to cancel` }
+  }
+  if (entry.cancelled) return { id: key, status: "cancelled" } // abort already in flight — idempotent
+  if (entry.status === "queued") {
+    // 出队 + position 释放/前移（§19.5 D-M6——无 abort）
+    const queue = agent._asyncQueue ?? []
+    const qi = queue.indexOf(entry)
+    if (qi >= 0) {
+      queue.splice(qi, 1)
+      for (let i = 0; i < queue.length; i++) queue[i].position = i + 1
+    }
+    entry.cancelled = true
+    entry.done = true
+    entry.status = "done"
+    map.delete(key)
+    // §20 D-SD5 终态墓碑：queued 取消（无 settle 事件——出队即终态）——依赖者经
+    // 墓碑查得 cancelled 分支（round1 #4——cancel 返回时即重估标注）。
+    const tombstones = (agent._asyncTombstones ??= new Map())
+    tombstones.set(key, { status: "cancelled", role: entry.role })
+    entry._settle?.()
+    return { id: key, status: "cancelled", was: "queued" }
+  }
+  // running：标记 + 条目 abort——settle finally 跑 cancelled 分支（移除 + stopped + 提醒）
+  entry.cancelled = true
+  entry.controller?.abort?.()
+  return { id: key, status: "cancelled" }
+}
+
+/** subagent action:"cancel" (§19.5 D-M6): depth-0 main-session control only.
+ *  §20 D-SD5/round1 #4（queued 依赖取消——无 settle 事件）：出队后**返回即**重估
+ *  依赖者——依赖者留 queued 标 dependency cancelled（refreshQueuedTokens 发更新块头
+ *  token）+ 工具结果内注依赖者（模型可见——工具结果内——round1 #4 明示通道）+ 补位
+ *  （AUTO 档依赖者自动启动/槽位竞态释放）。被取消条目自身发 ⟦ev⟧cancelled 移除等待块。 */
+export function executeCancelAction(args, ctx) {
+  if ((ctx.depth ?? 0) > 0) {
+    return JSON.stringify({ status: "error", error: "cancel is only available at depth 0 — a child agent has no async pool of its own (AGENT-LOOP.md §19.5 D-M6)" })
+  }
+  const id = args?.id
+  if (id === undefined || id === null || String(id) === "") {
+    return JSON.stringify({ status: "error", error: "cancel requires the id of the async subagent to stop — omitting it would mean a blanket cancel (Ctrl+C stops everything; AGENT-LOOP.md §19.5 D-M6)" })
+  }
+  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"）
+  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 分支）
+    ctx.callbacks?.onToken?.(`${entry.relayPrefix}⟦ev⟧cancelled\x1e`)
+    // 依赖者标注 + 位置前移 + AUTO 自动启动（round2 #3：AUTO 档才启动——手动留 queued）
+    maybeRefillAsync(agent)
+    refreshQueuedTokens(agent, ctx.callbacks?.onToken)
+    if (hadDependents) {
+      // refill 后重算——AUTO 下依赖者已启动者不再列（文案与实际状态一致——code review 🔵）
+      const dependents = dependentLabels(agent, key)
+      if (dependents.length > 0) {
+        result.dependents = dependents
+        result.note = `queued dependents ${dependents.join(", ")} marked "dependency cancelled" — they stay queued until you cancel them (this action again with their id) or an AUTO session starts them (AGENT-LOOP.md §20 D-SD5)`
+      } else if (agent.autoApprove) {
+        result.note = `dependents of the cancelled task auto-started (AUTO session — round2 #3: an AUTO session starts dependency-cancelled dependents on slot availability)`
+      }
+    }
+  }
+  return JSON.stringify(result)
+}
+
+/**
+ * 共享 post-spawn 管线（阻塞与 async 同一条——§15 D-A1 "全不变"）：turn-cap continue
+ * 循环 → 拒绝降级 partial 返回 → MIN_REPORT_CHARS 扩写 → eng-coder mutation merge →
+ * designId 后缀。onDeclined 在此（两路同一形态）——只有 askContinue 不同：阻塞经权限
+ * 面板询问；async 永不弹面板（自动拒绝；engineering && AUTO 自动 resume——§15 D-A3）。
+ */
+export async function runChildPipeline(child, input, childOpts, childRunOpts, { parent, role, args, askContinue }) {
+  const declined = { partial: null }
+  let report = await runWithContinue(
+    (child, input, cbs, opts) => runAgent(child, input, cbs, opts), // opts = childRunOpts + resume (由管线管理)
+    child, input, childOpts, childRunOpts,
+    {
+      askContinue,
+      onDeclined: (e, output) => {
+        if (role === "eng-coder" && child._mutatedThisRun) mergeChildMutations(parent, child)
+        // 拒绝 = 早退语义：不带 MIN_REPORT_CHARS 扩写（对已 cap 的 child 追问长报告是错的）；
+        // review #2：用管线捕获的 output（此时 report 仍 ""——runWithContinue 未返回）
+        declined.partial = `Subagent (${role}) ${TURN_CAP_MARK} (${e.turn} turns) — work may be partial; review recent_changes before deciding next steps.\nPartial output: ${output || ""}`
+      },
+    },
+  )
+  if (declined.partial !== null) {
+    // 被拒的 eng-coder 交付仍带 designId（fix round 以同 slot 重 spawn——2026-09-01）
+    if (role === "eng-coder") declined.partial += `\ndesignId: ${args.designId ?? "(single-design session — designId optional)"} — reuse it (with the same designToken) when re-spawning this eng-coder.`
+    return declined.partial
+  }
+
+  // 报告过短 = 交接不完整：送回扩写一次（kimi-code summaryPolicy: min 200 chars 同源）
+  if (report.length < MIN_REPORT_CHARS) {
+    report = await runAgent(child, REPORT_CONTINUATION, childOpts, childRunOpts)
+  }
+
+  // 工程模式机械码门：委托的文件改动不得绕过父侧 advisor/verify guard——eng-coder ONLY
+  // 有意为之（review #8）：普通 coder 自带自评纪律；normal 模式无父侧 gate 可喂。
+  // 只在实际 mutated 时 merge（防 runAgent 写前抛错时传播空 mutation 声明——纵深防御）
+  if (role === "eng-coder" && child._mutatedThisRun) {
+    mergeChildMutations(parent, child)
+  }
+
+  // designId 随交付报告（2026-09-01）：divergence audit fix round 用同一 designId+token 重 spawn
+  if (role === "eng-coder") {
+    report += `\ndesignId: ${args.designId ?? "(single-design session — designId optional)"} — reuse this designId with the same designToken (from the approved advisor type='design' review) when re-spawning this eng-coder for an audit fix round.`
+  }
+
+  return report
+}
+
+/**
+ * Inject one settled async entry into the parent history as a user-role reminder
+ * (§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: label,
+  })
+  // §20 D-SD5 终态墓碑：本函数是全部自动注入路径的共享形态（回合尾 collect + 挂起
+  // digest 首行注入）——注入即消费（调用方随即从容器移除）——dependsOn 引用该 id 的
+  // 后续 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 })
+}
+
+/**
+ * Child agent run options — the parent's abort signal MUST propagate to the
+ * child: without it, Ctrl+C aborts the parent's controller but the child keeps
+ * running its full turn budget (up to subagentTurns) while the parent awaits —
+ * the interrupt appears to do nothing.
+ * §17 D-S9: during a suspension session children share the SESSION signal instead
+ * (agent._sessionSignal) — a digest's own Ctrl+I/Ctrl+C must not abort the whole
+ * pool; the session driver aborts the session controller to stop everything.
+ */
+export function buildChildRunOpts(ctx) {
+  return {
+    depth: (ctx.depth ?? 0) + 1,
+    maxTurns: ctx.agent?.config?.agent?.subagentTurns ?? DEFAULT_SUBAGENT_TURNS,
+    signal: ctx.agent?._sessionSignal ?? ctx.signal ?? null,
+  }
+}
+
+/**
+ * Merge an eng-coder child's mutations into the parent agent's bookkeeping.
+ * The parent must stay aware of delegated file changes: `_touchedFiles` enables
+ * the advisor guard (completion.mjs) to detect that code was modified and
+ * pushback for review. Prior verify/advisor state is invalidated because it
+ * judged an older state.
+ *
+ * `_advisorRound` is NOT reset: merged code enters the CURRENT convergence
+ * cycle. Resetting here would break the review→fix→re-review loop (the parent
+ * reviews, spawns an eng-coder to fix, merges, reviews again — every merge
+ * would restart at round 1 and the 5-round cap could never be reached).
+ * `_calledAdvisorThisRun` IS cleared so the merged code triggers a fresh
+ * advisor call (the guard demands review of new mutations).
+ *
+ * Returns true when mutations were merged (kept for future caller checks).
+ */
+export function mergeChildMutations(parent, child) {
+  // A child claiming mutations without any touched file is a misbehaving
+  // child (or a bookkeeping bug) — do not propagate an empty mutation claim
+  // 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
+    parent._verifyPassed = undefined
+  }
+  // Stale session cleanup only — the round counter survives (see above).
+  parent._advisorSession = null
+  return true
+}
+
+// Re-export shim (2026-09-05 拆分轮): §20 调度符号迁至 ./subagent-scheduler.mjs——本面
+// 保留供 test/subagent-scheduler.test.mjs 动态 import（测试零改动——freeze.mjs 同款转发链）。
+export { queueRunnable, describeBlockers } from "./subagent-scheduler.mjs"

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 })
+}