thincoder 0.12.59 → 0.12.60

package/src/tui/subagent-freeze.mjs

@@ -0,0 +1,172 @@
+/**
+ * subagent-freeze.mjs — 子agent 区块完成/冻结族（2026-09-05 module-split：
+ * subagent-blocks.mjs 625 > 500 硬限——§19.6 面板镜像 syncPanelSnapshot + finish/
+ * freeze 家族 verbatim 迁入，语义零变；subagent-blocks.mjs import 回（routeSub* 与
+ * compression panel 调用点）+ re-export 保外部 import 面（index.mjs 等）。
+ */
+
+import { C } from "./ansi.mjs"
+import { closeOpenSubChildren } from "./subagent-children.mjs"
+
+// ─── §19.6 D-P1 面板镜像（subagent panel 检查工具）───
+// TUI 装配处（index.mjs startTUI）state._agent = agent——块级状态变更点经
+// syncPanelSnapshot 刷新 agent._panelSnapshot（区块数组快照：{key, role,
+// status: running|done|awaitingDigest, startedAt}——状态变更即刷——O(n) 小——
+// 不逐 token——NF-P）。agent 层 subagent action:"panel" 读此镜像（视图与用户
+// 所见一致）+ 冻结门控（D-P3）。未挂载（headless/mock——无 state._agent）=
+// 无镜像——no-op（降级路径由 agent 侧判定）。
+
+/** 刷新面板镜像（调用点 = 本模块全部 state.subTasks 块级变更点末尾——map 已稳定）。 */
+export function syncPanelSnapshot(state) {
+  const agent = state._agent
+  if (!agent) return // 未挂载（headless/mock 无 TUI 装配）——无镜像
+  const snap = []
+  for (const sub of Object.values(state.subTasks ?? {})) {
+    // §20 D-SD3b：waiting/等位块（sub.queued——未启动）以 queued 态入镜（镜像与面板
+    // 所见一致——action:'panel' 视图 + freeze 门控读此态）。
+    const status = sub.done ? (sub.awaitingDigest ? "awaitingDigest" : "done") : (sub.queued ? "queued" : "running")
+    snap.push({ key: sub.key, role: sub.role ?? null, status, startedAt: sub.started ?? Date.now() })
+  }
+  agent._panelSnapshot = snap
+}
+
+/** Mark the earliest running child of the given role(s) as done (✓ header, frozen elapsed). */
+export function finishSubTask(state, roles, lastError = null) {
+  state.subTasks ??= {}
+  const roleSet = new Set(Array.isArray(roles) ? roles : [roles])
+  const running = Object.values(state.subTasks)
+    .filter((s) => !s.done && roleSet.has(s.role))
+    .sort((a, b) => a.started - b.started)
+  if (running.length === 0) return
+  const sub = running[0]
+  sub.done = true
+  sub.doneAt = Date.now()
+  sub.currentTool = null
+  sub.approval = null
+  if (lastError) sub.lastError = lastError
+  sub.blockEpoch = (sub.blockEpoch ?? 0) + 1
+  syncPanelSnapshot(state) // §19.6 D-P1: done 状态变更刷镜
+}
+
+/** §7.2.3 sync spawn 完成精确冻结（2026-09-03）：按 relay key 精确 settle。finishSubTask
+ *  的"最早 started"启发式只在面板单 running 块时成立——§15 async 化后 async eng-coder
+ *  （先启动）与 sync explore 并存时 explore 完成会误冻先启动的 eng-coder 块（7.2.3.1）。
+ *  dispatch 沿 ctx._subagentKey（relayPrefix 去尾 = `role#N`）把 key 传进 onToolResult——
+ *  有 key 即精确标 done（冻结载体进流 + 删条目由调用方 freezeDoneSubTasks 承接——与
+ *  finishSubTask 同一契约）；无匹配块（已冻结 tombstone/不存在）返回 null——调用方不得
+ *  落启发式兜底（精确 key 无匹配 = 无从归属——不误冻他块）。 */
+export function finishSubTaskKey(state, key, lastError = null) {
+  const sub = state.subTasks?.[key]
+  if (!sub) return null
+  sub.done = true
+  sub.doneAt = Date.now()
+  sub.currentTool = null
+  sub.approval = null
+  if (lastError) sub.lastError = lastError
+  sub.blockEpoch = (sub.blockEpoch ?? 0) + 1
+  syncPanelSnapshot(state) // §19.6 D-P1: done 状态变更刷镜
+  return sub
+}
+
+/** 冻结完成/中断区块进 state.lines（§7.2 D4——_frozenSubTask 载体行，渲染端
+ *  render-conversation 识别；折叠交互 key = sub-${key} 与运行面板同源跨冻结延续）。
+ *  §27 R23 D-R23c2 收尾语义（T-R23c.2a）：外层先冻结而内层子块未收尾（外层 abort/
+ *  中断）→ 子块随外层冻结定格 stopped（closeOpenSubChildren——不悬空）。
+ *  锚点插入（2026-09-03 修复轮）：settled 块带 _freezeAt（settle 时刻流位置）——
+ *  splice 落位使挂起期补发冻结块位于其 digest 总览文本之前；无锚点尾推不变；
+ *  多锚点批量冻结按降序（绝对位置 splice——先插小锚点会移走大锚点目标）。 */
+export function freezeSubTaskLines(state, sub) {
+  if (!sub) return
+  closeOpenSubChildren(sub) // R23 D-R23c2——开子块随外层冻结定格 stopped
+  state._frozenSubKeys ??= new Set()
+  state._frozenSubKeys.add(sub.key)
+  sub.done = true
+  sub.doneAt = sub.doneAt ?? Date.now()
+  const anchor = sub._freezeAt ?? state.lines.length
+  state.lines.splice(Math.min(anchor, state.lines.length), 0, {
+    text: `subagent activity: ${sub.key}`, color: C.dim, _frozenSubTask: sub,
+  })
+}
+
+/** 头裁锚点校正（index.mjs pushLine 调用）：裁 removedCount 补 1 标记行 = 净位移
+ *  removedCount−1（code review round1 #3）；在途锚点前移，min 0 兜底。 */
+export function shiftFreezeAnchors(state, removedCount) {
+  const shift = removedCount - 1
+  for (const sub of Object.values(state.subTasks ?? {})) {
+    if (sub._freezeAt !== undefined) sub._freezeAt = Math.max(0, sub._freezeAt - shift)
+  }
+}
+
+/** 冻结 + 释放全部已 done 块（工具结果清扫路径）。锚点降序（后 settle 先插——
+ *  绝对位置 splice 语义）；无锚点（-1）排末尾推；sort 稳定。 */
+export function freezeDoneSubTasks(state) {
+  const subs = Object.values(state.subTasks ?? {})
+    .filter((s) => s.done)
+    .sort((a, b) => (b._freezeAt ?? -1) - (a._freezeAt ?? -1))
+  for (const sub of subs) {
+    freezeSubTaskLines(state, sub)
+    delete state.subTasks[sub.key]
+  }
+  syncPanelSnapshot(state) // §19.6 D-P1: 删除后刷镜（块移出面板）
+}
+
+/** 按角色整组标记 done——consult N 并行 children 的会话级 settle（单发
+ *  finishSubTask 只结最早一个——consult 残项 2026-08-30）。 */
+export function finishSubTasksByRole(state, roles, lastError = null) {
+  state.subTasks ??= {}
+  const roleSet = new Set(Array.isArray(roles) ? roles : [roles])
+  for (const sub of Object.values(state.subTasks)) {
+    if (!sub.done && roleSet.has(sub.role)) {
+      sub.done = true
+      sub.doneAt = Date.now()
+      sub.currentTool = null
+      sub.approval = null
+      if (lastError) sub.lastError = lastError
+      sub.blockEpoch = (sub.blockEpoch ?? 0) + 1
+    }
+  }
+  syncPanelSnapshot(state) // §19.6 D-P1: done 状态变更刷镜
+}
+
+/** 回合尾/挂起退出清扫（runAgentTurn finally / suspensionSession finally）：冻结全部
+ *  剩余块——中断（Ctrl+C/错误）不留下钉住输入框的 ghost；未 done 者
+ *  lastError="interrupted"（Ready 态跳过）。§17.5.5：挂起自然退出时本函数只兜底
+ *  **未消化残项**（已消化块由 freezeReclaimDigestedBlocks 逐条先行回收——块回收与
+ *  池空解耦）。锚点降序同 freezeDoneSubTasks（挂起期 settle 锚点交错批次各按其
+ *  settle 位置落位）。 */
+export function freezeAllSubTasks(state) {
+  const subs = Object.values(state.subTasks ?? {})
+    .sort((a, b) => (b._freezeAt ?? -1) - (a._freezeAt ?? -1))
+  for (const sub of subs) {
+    if (!sub.done) {
+      sub.done = true
+      sub.doneAt = Date.now()
+      if (!sub.lastError && state.status !== "Ready") sub.lastError = "interrupted"
+    }
+    freezeSubTaskLines(state, sub)
+    delete state.subTasks[sub.key]
+  }
+  syncPanelSnapshot(state) // §19.6 D-P1: 冻结回收后刷镜（块移出面板）
+}
+
+/** §17.5.5 消化完成逐条冻结回收（2026-09-03 实测修订 + round1 #1 位置裁定）：digest/会话内
+ *  用户回合消化完 pending 条目（run 首行已注入）后调用——把"已消化但仍驻留面板"的
+ *  awaitingDigest 块立即冻结进流（不等池空——块回收与池空解耦；池空 freezeAllSubTasks
+ *  仅兜底未消化残项）。归属不变式：会话内任何 run 开始前 pinned 块的条目必在 pending
+ *  （settle 即移交）；run 消费后条目不在 pending 的 pinned 块 = 本 run 消化者——无需
+ *  快照即精确归属。位置（round1 #1 裁定——与 17.5.5 早版文本的矛盾已消解，见
+ *  AGENT-LOOP.md §17.5.5）：**settle 锚点 splice 落位——digest 总览文本之前**——同
+ *  §7.2 D4 修复轮/D-S8 锚点语义（T-S6/T-S14 位置断言同口径）——锚点降序逐块冻结
+ *  （splice 绝对位互不位移）。@returns {number} 回收块数 */
+export function freezeReclaimDigestedBlocks(state, pendingList) {
+  const pend = pendingList ?? []
+  const targets = Object.values(state.subTasks ?? {})
+    .filter((s) => s.awaitingDigest && !pend.some((e) => `${e.role}#${e.id}` === s.key))
+    .sort((a, b) => (b._freezeAt ?? -1) - (a._freezeAt ?? -1)) // 锚点降序（同 freezeAllSubTasks）
+  for (const sub of targets) {
+    freezeSubTaskLines(state, sub) // splice 落 settle 锚点（digest 总览文本之前）
+    delete state.subTasks[sub.key]
+  }
+  syncPanelSnapshot(state) // §19.6 D-P1: 逐条回收后刷镜（块移出面板）
+  return targets.length
+}

package/src/tui/subagent-panel.mjs

@@ -12,7 +12,8 @@
  *
  * §19.5 D-M7 ⏹：运行中（非 done）折叠头右缘停止标记（dim，仅折叠头）——点击 =
  * cancel（mouse.mjs 列级命中 _stopCol——不触发折叠翻转）。
- * §19.5 D-M8：本模块同时承载子标行 dim 样式（styleSubLabelRow——面板与冻结渲染共用）。
+ * §27 R23（supersede §19.5 D-M8 子标方案）：嵌套子代理渲染为子块段（renderSubChildSections
+ * ——子块头 + 独立折叠键——面板与冻结渲染共用——styleSubLabelRow 已随子标机制退役）。
  *
  * 中立模块（D1 评审 #6）：layout.mjs 调 renderSubagentPanel 预计算面板高度
  * （subagentLines → subagentH），render-frame.mjs 直接 put 预计算行（不重复
@@ -30,26 +31,61 @@ import { sliceByWidth, stringWidth } from "./render.mjs"
 import { isExpanded, renderBlockTimeline, renderExpandedBlock, foldTailLines } from "./fold-block.mjs"
 import { SUBAGENT_ROLES } from "./subagent-blocks.mjs"
 
-/** 子标行行首标记（`explore#1 · `——sublabelLine 写入的字面形态）。 */
-const SUB_LABEL_RE = /^([\w-]+#\d+(?:\/[\w-]+#\d+)* · )/
+/**
+ * §27 R23 子块（嵌套子代理）段渲染——面板与冻结渲染共用（中立纯函数模块）：
+ * 每子块 = 工具式头行（`❯ explore#N · model · elapsed`——D-R23b，dim ❯ + role#N 亮 +
+ * model/elapsed dim——与 C 工具头同排式；done/stopped 定格动词——D-R23c2）+ 折叠态
+ * tail 2 / 展开态全量窗口（60% 封顶 + 块内滚动——fold-block 公共组件）；孙块递归
+ * （任意 inner 深度——D-R23d——每层独立折叠键）。折叠键 = `sub-{outerKey}/{innerPath}`
+ * （D-R23e——与既有 sub-{key} 同族——_foldToggle 命中映射复用 fold-block 通用通道——
+ * mouse.mjs 零改动）。行数配额在数据层（子块计入外层 500 行环——NFR）。
+ */
 
-/** §19.5 D-M8 子标行 dim 样式（最终渲染点注入——行对象单色外 wrap 无法表达行内
- *  双色）：行首 `explore#1 · ` 子标转 gray（90m），其后内容恢复该行 kind 色
- *  （tool=cyan / text=白 / think=默认 fg——dim 属性本就由 C.reason 施加，不受
- *  fg 切换影响）。折叠 tail / dim 行不需调用（整行已 dim）。返回新行对象。 */
-export function styleSubLabelRow(row) {
-  const content = String(row.text).replace(/^│ /, "")
-  const m = content.match(SUB_LABEL_RE)
-  if (!m) return row
-  const restore = row.color === C.tool ? ansi.fg(6)
-    : row.color === C.text ? ansi.fg(7)
-    : ansi.fg(9) // 默认 fg（think 行 C.reason=dim 属性——90m 后切回默认即还原 dim 白）
-  return {
-    ...row,
-    text: `│ ${ansi.gray}${m[1]}${restore}${content.slice(m[1].length)}`,
-  }
+/** 子块折叠键（D-R23e）：sub-{outerKey}/{innerPath}。 */
+export function subChildFoldKey(rootKey, innerPath) {
+  return `sub-${rootKey}/${innerPath}`
 }
 
+/** 子块头行（D-R23b/c2）——返回带 _foldToggle 的行（可点击折叠/展开——fold-block 通道）。 */
+function subChildHeadRow(rootKey, child, innerPath, cols) {
+  const foldKey = subChildFoldKey(rootKey, innerPath)
+  const end = child.done ? (child.doneAt ?? Date.now()) : Date.now()
+  const secs = Math.max(0, Math.floor((end - (child.started ?? end)) / 1000))
+  const verb = child.done ? (child.stopped ? `stopped ${secs}s` : `done ${secs}s`) : `${secs}s`
+  const raw = `❯ ${child.key}${child.model ? ` · ${child.model}` : ""} · ${verb}`
+  let text = sliceByWidth(raw, Math.max(1, cols - 2))
+  // dim 注入（截断后——自闭合：行末由打印端 reset 兜底；灰色段间 restore 恢复行基色）。
+  const restore = ansi.fg(6) // 行基色 C.tool（cyan）
+  if (text.startsWith("❯")) text = `${ansi.gray}❯${restore}${text.slice(1)}`
+  const sep = text.indexOf(" · ")
+  if (sep > 0) text = `${text.slice(0, sep)}${ansi.gray}${text.slice(sep)}`
+  return { text, color: C.tool, _foldToggle: foldKey }
+}
+
+/** 子块段行（head + 折叠 tail2 / 展开窗口）——递归孙块。root = 外层块（key 为折叠前缀源）。 */
+export function renderSubChildSections(state, root, cols, maxRows) {
+  const out = []
+  const walk = (carrier, path) => {
+    for (const child of carrier.children ?? []) {
+      const innerPath = path ? `${path}/${child.key}` : child.key
+      out.push(subChildHeadRow(root.key, child, innerPath, cols))
+      const foldKey = subChildFoldKey(root.key, innerPath)
+      if (isExpanded(state, foldKey)) {
+        // 展开：全量时间线窗口化（per-kind 着色，60% 封顶 + 块内滚动——公共组件）
+        const body = renderBlockTimeline(child.blocks, cols)
+        out.push(...renderExpandedBlock({ body, foldKey, state, maxRows, cols, label: `${child.key} activity` }))
+      } else {
+        // 折叠：tail 2 非空行（最近活动）——dim（与既有外层折叠 tail 同型）
+        for (const line of foldTailLines(child.blocks, 2)) {
+          out.push({ text: `│ ${sliceByWidth(line, cols - 4)}`, color: C.dim, _skipDimFold: true })
+        }
+      }
+      walk(child, innerPath)
+    }
+  }
+  walk(root, "")
+  return out
+}
 /**
  * 面板行构建（纯函数）：顶部分隔线 `─` + 各运行中区块（折叠头 + tail 3 /
  * 展开全量）。maxRows = 终端行数（展开态 60% 封顶窗口化）；省略 = 不封顶
@@ -71,14 +107,15 @@ export function renderSubagentPanel(state, cols, maxRows) {
     const icon = sub.approval ? "⏸" : sub.done ? "✓" : "▶"
     const elapsed = Math.floor(((sub.done ? (sub.doneAt ?? Date.now()) : Date.now()) - sub.started) / 1000)
     // §19.5 D-M7b ②: sync/async 显式头标（B 形态——不靠"没标推断"）——async 由
-    // ⟦ev⟧async 标记置位；sync 区块（无标记）显式标 sync。仅真实 subagent 角色
+    // ⟦ev⟧async 标记置位；sync 区块（无标记）显式标 sync。真实 subagent 角色
     // （escalate/consult/compress 等复用面板槽的条目无语义——非 spawn 角色豁免）；
+    // §24 D-24b：role "advisor" 伪角色同面板（块/⏹/冻结复用——ruling ②-4 A）。
     // 冻结后保留（与 model 标识同生命周期——render-conversation frozenSubTaskLines
     // 同款 modePart）。**颜色后置注入**（code review 🔵#4）：bracket 宽度预算用纯文
     // 本（dim ANSI 内嵌会被 sliceByWidth 截断在 restore 之前 → 行尾残留 dim）——
     // 截断后对完整存活的 mode word 单独套 dim + 恢复行色（自闭合——截断落在词内
     // 则 replace 不命中 → 无 ANSI 泄漏，词以行色显示）。
-    const isSubRole = SUBAGENT_ROLES.includes(sub.role)
+    const isSubRole = SUBAGENT_ROLES.includes(sub.role) || sub.role === "advisor"
     // §20 D-SD3b waiting 块（sub.queued——排队 spawn 返回即建——未启动无 relay 流）：
     // 括号状态词 = waiting（依赖/域冲突等位——detail 即原因）或 queued（槽满等位——
     // 状态区显示 position）；不显示 sync/async 词（尚未启动——无 async 标记可言——
@@ -130,7 +167,7 @@ export function renderSubagentPanel(state, cols, maxRows) {
     // 🟡#1——glyph 在 cols−1、最右列留 margin——避免终端最末列点击不可靠/全角字形
     // 顶格被裁；命中区 = col ≥ _stopCol = cols−1——含 glyph 与其右 margin，左邻
     // padding 空格仍走折叠）。整行 ≤ cols：内容先按 cols−3 截断。
-    if (!sub.done && sub.async === true && SUBAGENT_ROLES.includes(sub.role)) {
+    if (!sub.done && sub.async === true && (SUBAGENT_ROLES.includes(sub.role) || sub.role === "advisor")) {
       const cut = sliceByWidth(headText, Math.max(0, cols - 3))
       headText = cut + " ".repeat(Math.max(0, cols - 3 - stringWidth(cut)))
       line.text = `${headText} ${ansi.dim}⏹${ansi.reset} `
@@ -142,8 +179,7 @@ export function renderSubagentPanel(state, cols, maxRows) {
     out.push(line)
     if (isExpanded(state, foldKey)) {
       // 展开态：全量活动时间线（per-kind 着色，60% 屏封顶 + 块内滚动——公共组件）。
-      // §19.5 D-M8：时间线行过 styleSubLabelRow——行首子标 dim、内容恢复 kind 色。
-      const body = renderBlockTimeline(sub.blocks, cols).map(styleSubLabelRow)
+      const body = renderBlockTimeline(sub.blocks, cols)
       out.push(...renderExpandedBlock({ body, foldKey, state, maxRows, cols, label: "subagent activity" }))
     } else {
       // 折叠态：tail 3 非空 block 行（最近活动），dim。
@@ -151,6 +187,8 @@ export function renderSubagentPanel(state, cols, maxRows) {
         out.push({ text: `│ ${sliceByWidth(line, cols - 4)}`, color: C.dim })
       }
     }
+    // §27 R23：子块段（嵌套子代理——头 + tail2/展开窗口）随外层块渲染（面板与冻结共用）。
+    out.push(...renderSubChildSections(state, sub, cols, maxRows))
   }
   return out
 }

package/src/tui/suspension-drive.mjs

@@ -0,0 +1,351 @@
+/**
+ * suspension-drive.mjs — §17 挂起会话驱动器（2026-09-05 module-split：agent-turn.mjs
+ * 535 > 500 硬限——poolCounts + §17 挂起会话段 verbatim 迁入，语义零变；agent-turn.mjs
+ * re-import（runAgentTurn ↔ suspensionSession 函数级静态环——模块求值期无顶层调用，
+ * 环安全——session-slots ↔ session.mjs 同款先例）。
+ *
+ * §17（2026-09-02，AGENT-LOOP.md §17 D-S1..S9）：回合尾后台池非空 → 不阻塞等待，
+ * 进入挂起态——输入放开（Enter = 新回合 / digest 中 Enter 排队 pendingInput）、
+ * settle 事件驱动 auto-turn 消化（手动档 organize-only / AUTO 档全语义）、池空 + 无
+ * 待处理输入 → 补发 done 冻结自然退出。状态机行表见 AGENT-LOOP.md §17 D-S9。
+ */
+
+// 函数级静态环（2026-09-05）：drive 的 digestTurn/用户回合经 runAgentTurn 递归进入
+// agent-turn；agent-turn 的回合尾经 suspensionSession 进入本文件——互相 import。
+import { runAgentTurn } from "./agent-turn.mjs"
+import { freezeAllSubTasks, freezeReclaimDigestedBlocks } from "./subagent-blocks.mjs"
+import { sweepToolBlocks } from "./tool-events.mjs"
+import { logEvent } from "../log.mjs"
+import { C } from "./ansi.mjs"
+// ASYNC-RESULT-CONTAINER.md D1/D2：池 accessor（双池 absorb）+ pending 单容器停靠
+import { getAsyncPool, parkAsyncPending } from "../agent-tools/async-settle.mjs"
+
+// ── §24 D-24c（R15——2026-09-06）排队用户指令合并常量：单批 ≤8 条且合并注入
+// ≤2000 字符（双端逐字一致——§22 D-Q3 常量先例）；超限截批先行（余下下批——不丢
+// 不截断单条）；单条 >2000 字符直发不进批；/cmd 不进合并（逐条保序即时）。──
+export const MAX_MERGE_ITEMS = 8
+export const MAX_MERGE_CHARS = 2000
+
+/** 合并注入形态（编号逐条——模型一次处理全部——设计措辞锚）。 */
+export function formatMergedMessages(items) {
+  return `你排队了 ${items.length} 条消息：\n${items.map((m, i) => `${i + 1}. ${m}`).join("\n")}\n——一次处理`
+}
+
+/**
+ * R15 攒批计划（纯函数——消费点共享同一事实源）：按队列顺序产出动作序列。
+ * - { kind:"slash", text, count:1 }——/cmd 逐条即时执行（保序——不进合并缓冲）；
+ * - { kind:"turn", text, count, merged }——文本批次：连续非 / 条目攒批（单批 ≤8 条；
+ *   合并注入（格式化后）≤2000 字符；count ≥2 → merged 编号注入；count === 1 → 原文
+ *   直发（含单条 >2000 字符——不进批）；超限截批先行——余下条目留待下批（不丢）。
+ * 消费者每次取动作 [0] 并按 count 从源队列移除——下轮重新计划余项（边界幂等）。
+ */
+export function planQueuedInput(items) {
+  const actions = []
+  const n = items.length
+  let i = 0
+  while (i < n) {
+    const cur = String(items[i])
+    if (cur.startsWith("/")) { actions.push({ kind: "slash", text: cur, count: 1 }); i++; continue }
+    let j = i
+    for (;;) {
+      if (j - i >= MAX_MERGE_ITEMS || j >= n) break
+      const it = String(items[j])
+      if (it.startsWith("/")) break
+      if (it.length > MAX_MERGE_CHARS) break // 单条超长——不进批（留作直发）
+      const cand = items.slice(i, j + 1)
+      if (cand.length > 1 && formatMergedMessages(cand).length > MAX_MERGE_CHARS) break // 批总长超限——截批
+      j++
+    }
+    // 超长条目堵头（内环一步未进）→ 该条直发（不进批——也不与前后合并）
+    if (j === i) { actions.push({ kind: "turn", text: String(items[i]), count: 1, merged: false }); i++; continue }
+    const taken = items.slice(i, j)
+    if (taken.length === 1) {
+      actions.push({ kind: "turn", text: String(taken[0]), count: 1, merged: false })
+    } else {
+      actions.push({ kind: "turn", text: formatMergedMessages(taken), count: taken.length, merged: true })
+    }
+    i = j
+  }
+  return actions
+}
+
+/** 后台池计数（LOGGING susp/digest 事件字段——pendingN/poolN）。
+ *  poolN = _asyncSubagents + _asyncAdvisors（§24 D-24b advisor 池同面板计数——queued
+ *  条目同样在 map 内——2026-09-03 code review #2：不再 +queue.length 双计）。
+ *  R17（§25 D-R17a/b）：pendingN = pending 单容器 `_pendingAsyncResults` 条数（
+ *  ASYNC-RESULT-CONTAINER.md D2——四族统一停靠——digest 驱动判据同单容器）。 */
+export function poolCounts(agent) {
+  const map = agent?._asyncSubagents
+  const adv = agent?._asyncAdvisors
+  const running = (map ? [...map.values()].filter((e) => e.status === "running").length : 0)
+    + (adv ? [...adv.values()].filter((e) => e.status === "running").length : 0)
+    + consultRunningChildren(agent)
+  return {
+    poolN: (map?.size ?? 0) + (adv?.size ?? 0),
+    pendingN: pendingFamilyCount(agent),
+    runningN: running,
+  }
+}
+
+/** 运行中 consult children（会诊会话已跨回合——挂起判据/状态行计数同源）。 */
+function consultRunningChildren(agent) {
+  let n = 0
+  for (const s of agent?._consultSessions?.values() ?? []) {
+    if (!s.stopped) n += Math.max(0, s.pending ?? 0)
+  }
+  return n
+}
+
+/** pending 单容器条数（§25 D-R17a 消费驱动判据——T-R17j——ASYNC-RESULT-CONTAINER.md
+ *  D2：四族统一 `_pendingAsyncResults` +role，不再分族三容器）。 */
+export function pendingFamilyCount(agent) {
+  return agent?._pendingAsyncResults?.length ?? 0
+}
+
+/** pending 单容器非空（digest 触发判据——D-S2/D-S9——§25 D-R17a）。 */
+export function pendingFamiliesNonEmpty(agent) {
+  return pendingFamilyCount(agent) > 0
+}
+
+/** pending 单容器条目（freezeReclaimDigestedBlocks 的归属比对表——四族同容器）。 */
+export function allPendingEntries(agent) {
+  return [...(agent?._pendingAsyncResults ?? [])]
+}
+
+// ─── §17 挂起会话（AGENT-LOOP.md §17 D-S2/D-S9 状态机行表）────────────────
+
+/** 后台池存活判据（D-S2/F5 口径）：running/queued 子代理或后台评审，或已 settle 未注入结果
+ *  （pending 单容器非空 = D-S3 "未注入"），或 running consult 会话（会诊跨回合——
+ *  §25 D-R17a 挂起活度钩子——consult 启动回合尾即入挂起态）。回合尾与每次轮末都用它
+ *  评估退出。§24 D-24b：_asyncAdvisors（后台评审池）与子代理池同判——评审飞行中挂起
+ *  会话必须存活。 */
+export function poolLive(agent) {
+  const map = agent._asyncSubagents
+  const adv = agent._asyncAdvisors
+  return (map && map.size > 0) || (adv && adv.size > 0)
+    || pendingFamilyCount(agent) > 0
+    || consultRunningChildren(agent) > 0
+}
+
+/** D-S3 ③ 记账清扫：回合边界竞态落下的已 settle 项（settle 回调未及移交——发生在
+ *  回合刚结束、_suspended 尚未置位的窗口）补入 pending。幂等：回调已移交的条目已从
+ *  map 删除并带 _inPending 标记，不会重复入列。
+ *  ASYNC-RESULT-CONTAINER.md D2：pending 单容器（parkAsyncPending——四族统一停靠
+ *  +role；escalate 不再走独立流）。 */
+function sweepSettledToPending(agent) {
+  const maps = [getAsyncPool(agent, "subagent"), getAsyncPool(agent, "advisor")].filter((m) => m instanceof Map && m.size > 0)
+  if (maps.length === 0) return
+  for (const map of maps) {
+    for (const e of [...map.values()]) {
+      if (e.done && !e._inPending) {
+        parkAsyncPending(agent, e)
+        map.delete(String(e.id))
+      }
+    }
+  }
+}
+
+/** 等待下一次 settle（running 子代理 promise 完成）或用户唤醒（Enter 入队 / Ctrl+C /
+ *  会话 abort）。唤醒器经 state._suspWake 单槽注入；abort 监听兜底。 */
+function waitForSettleOrWake(agent, state) {
+  return new Promise((resolve) => {
+    let finished = false
+    const cleanup = () => {
+      state._suspWake = null
+      const i = (agent._asyncWaiters ?? []).indexOf(w)
+      if (i >= 0) agent._asyncWaiters.splice(i, 1)
+      agent._sessionAbort?.signal.removeEventListener("abort", onAbort)
+    }
+    const finish = (why) => {
+      if (finished) return
+      finished = true
+      cleanup()
+      resolve(why)
+    }
+    const w = () => finish("settle")
+    const wake = () => finish("wake")
+    const onAbort = () => finish("aborted")
+    ;(agent._asyncWaiters ??= []).push(w)
+    state._suspWake = wake
+    if (agent._sessionAbort?.signal.aborted) { onAbort(); return }
+    agent._sessionAbort?.signal.addEventListener("abort", onAbort, { once: true })
+  })
+}
+
+/** 后台模式状态行文本（D-S8；17.5.4 #6 顺手对齐）："后台 N 子代理运行中 · M 完成待消化"
+ *  ——"运行中" = running + queued（含后台评审——§24 D-24b 同面板计数）+ running consult
+ *  children（R17——会诊跨回合）；"完成待消化" = pending 任一族移交项 + §17.5 回合尾留池
+ *  的 settled 未消费项（挂起会话 sweep 前的可见窗口）。 */
+function backgroundStatusText(agent) {
+  const map = agent._asyncSubagents
+  const adv = agent._asyncAdvisors
+  const running = (map ? [...map.values()].filter((e) => e.status === "running").length : 0)
+    + (adv ? [...adv.values()].filter((e) => e.status === "running").length : 0)
+    + consultRunningChildren(agent)
+  const queued = agent._asyncQueue?.length ?? 0
+  const pending = pendingFamilyCount(agent)
+  const doneInPool = (map ? [...map.values()].filter((e) => e.done).length : 0)
+    + (adv ? [...adv.values()].filter((e) => e.done).length : 0) // §17.5 留池未消费
+  const awaiting = pending + doneInPool
+  const active = running + queued
+  return active > 0 || awaiting > 0
+    ? `后台 ${active} 子代理运行中${awaiting ? ` · ${awaiting} 完成待消化` : ""}`
+    : "后台子代理收尾…"
+}
+
+/** 消化轮：系统驱动的 auto-turn（D-S6）。手动档不传权限/问答 handler（D-S7 装配
+ *  契约——denied 不弹面板、不悬挂）；AUTO 档沿用普通回调（autoApprove 短路自动
+ *  执行）。_suspended 保持 true：消化中 settle 延迟冻结 + 移交 pending。R17：pending
+ *  计数/消化触发 = 任一 pending 族（T-R17j——consult/escalate 空闲 settle 也触发消化轮）。 */
+async function digestTurn(ctx) {
+  const { agent, pushLine } = ctx
+  const manual = !agent.autoApprove
+  pushLine(manual
+    ? "[auto-turn: digesting finished subagent reports…]"
+    : "[auto-turn: continuing background work…]", C.dim)
+  const digestCtx = manual
+    ? { ...ctx, askPermission: null, askBatchPermission: null, askQuestion: null }
+    : ctx
+  // LOGGING：digest:* 事件（D-S9 消化轮边界——LOGGING.md F-L4 挂起态覆盖）
+  const d0 = Date.now()
+  const pend0 = pendingFamilyCount(agent)
+  logEvent("digest:start", { pendingN: pend0 })
+  await runAgentTurn(digestCtx, "", { autoTurn: true, skipSession: true })
+  logEvent("digest:end", { pendingN: pendingFamilyCount(agent), ms: Date.now() - d0 })
+}
+
+/**
+ * §17 挂起会话驱动（D-S9 行表；由 runAgentTurn 回合尾进入，池空自然退出）：
+ * - suspension：池项 settle → 入 pending → 开 auto-turn（合并消化近邻 settle）；
+ *   用户 Enter → pendingInput（digest 运行中排队，D-S5）——用户输入优先于 digest；
+ * - auto-turn：消化中 settle 不并发开新轮（单 runAgent 循环），轮末按 pending/池态
+ *   续开合并消化轮或回挂起；pendingInput 非空 → 以该消息开新回合（不触发新 digest）；
+ * - §17.5.5：每次消化/会话内用户回合消费 pending 后 → freezeReclaimDigestedBlocks
+ *   逐条冻结回收（消化完成块不滞留面板——不等池空；settle 锚点 splice——digest 总览
+ *   文本之前——round1 #1 裁定）；
+ * - 退出：池空 + pending 空 + 无待处理输入 → freezeAllSubTasks 补发冻结（仅兜底
+ *   未消化残项——17.5.5 块回收与池空解耦）→ idle。
+ * _suspended 翻转：会话期 true（settle 回调据此延迟冻结 + 移交 pending）；会话内
+ * 用户回合执行期翻 false（普通回合语义：settle 即冻结 + 回合尾直注入 ①）。
+ */
+export async function suspensionSession(ctx) {
+  const { agent, state, render, pushLine } = ctx
+  state.pendingInput ??= []
+  state._suspAborted = false
+  agent._suspended = true
+  agent._sessionSignal = agent._sessionAbort.signal // 会话内 spawn 的 children 共享（subagent.mjs）
+  state.suspended = true
+  state._suspPending = false // 偏差 #1：进入真正挂起态——标志只在释放窗口期有效（此后由 state.suspended 分流）
+  const suspTick = setInterval(() => {
+    if (state.suspended && !state.processing) {
+      state.status = backgroundStatusText(agent)
+      render()
+    }
+  }, 1000)
+  state.status = backgroundStatusText(agent)
+  render()
+  // LOGGING：susp:* 事件（挂起态进入/退出——F-L4；挂起期输入事件 v1 不记——refinement #1）
+  const s0 = Date.now()
+  logEvent("susp:enter", poolCounts(agent))
+  try {
+    while (!state._suspAborted && !agent._sessionAbort.signal.aborted) {
+      sweepSettledToPending(agent)
+      // 1. 用户输入优先（D-S5）：pendingInput（digest 期排队）→ queue（处理期排队）。
+      //    §24 D-24c（R15）：空闲消费攒批合并——同源连续文本合成单条注入（编号逐条
+      //    ——单批 ≤8 条 / ≤2000 字符；单条超长直发不进批；余下留待下批——不丢）；
+      //    /cmd 不进合并——逐条保序即时（位置 = 源内队列序）。每次取计划动作 [0]——
+      //    单回合消费后回环续取（新到消息自然并进下一回合——不设延迟窗口）。
+      const fromPending = state.pendingInput.length > 0
+      const srcLen = fromPending ? state.pendingInput.length : state.queue.length
+      if (srcLen > 0) {
+        const src = fromPending ? state.pendingInput : state.queue.map((q) => q.text)
+        const head = planQueuedInput(src)[0]
+        if (fromPending) state.pendingInput.splice(0, head.count)
+        else state.queue.splice(0, head.count)
+        if (head.kind === "slash") {
+          await ctx.handleSlash?.(head.text)
+          render()
+          continue
+        }
+        agent._suspended = false // 用户回合 = 普通回合语义（① 直注入 + settle 即冻结）
+        await runAgentTurn(ctx, head.text, { skipSession: true })
+        agent._suspended = true
+        // §17.5.5：该回合消化完 pending（run 首行注入）→ 逐条冻结回收驻留块
+        // （不等池空——settle 锚点 splice——digest 总览文本之前；与 digest 回收同规则）
+        // R17：回收比对 = pending 单容器（四族统一——ASYNC-RESULT-CONTAINER.md D2）
+        freezeReclaimDigestedBlocks(state, allPendingEntries(agent))
+        state.status = backgroundStatusText(agent)
+        continue
+      }
+      // 2. pending 任一族非空 → 合并消化轮（注入由 runAgent 首行统一完成——D-S3 单注入点；
+      //    R17 判据推广——consult/escalate 族同样触发——T-R17j）
+      if (pendingFamiliesNonEmpty(agent)) {
+        await digestTurn(ctx)
+        // §17.5.5 实测修订（2026-09-03）：digest 消化完成（pending 条目已注入）→ 逐条补发
+        // done 冻结回收——不等池空——块从面板移除进流（settle 锚点 splice 落位——digest
+        // 总览文本之前——round1 #1 裁定）；池空 freeze-out 仅兜底未消化残项（挂起会话
+        // 结束统一清场）——块回收与池空解耦（T-H7/AC-H5）。
+        // 归属不变式：会话内任何 run 开始前 pinned 块（awaitingDigest）的条目必在 pending
+        // 任一族——run 消费后不在 pending 的 pinned 块即本 run 消化者（无需快照即精确归属）。
+        freezeReclaimDigestedBlocks(state, allPendingEntries(agent))
+        state.status = backgroundStatusText(agent)
+        continue
+      }
+      // 3. 池空（无 running/queued/未注入）→ 自然退出回 idle（补发冻结在 finally）
+      if (!poolLive(agent)) break
+      // 4. 等下一 settle / 用户唤醒（Enter 入队、Ctrl+C）
+      await waitForSettleOrWake(agent, state)
+    }
+  } finally {
+    clearInterval(suspTick)
+    const aborted = state._suspAborted || agent._sessionAbort.signal.aborted
+    if (aborted && (agent._asyncSubagents?.size ?? 0) > 0) logEvent("ev:stopped", { poolN: agent._asyncSubagents?.size ?? 0, where: "suspension-abort" })
+    logEvent("susp:exit", { ...poolCounts(agent), ms: Date.now() - s0, reason: aborted ? "aborted" : "idle" })
+    agent._suspended = false
+    agent._sessionSignal = null
+    agent._sessionAbort = null
+    agent._sessionAbortAll = null // 偏差 #3：会话期 controller 集合随句柄一并释放
+    state.suspended = false
+    state._suspWake = null
+    state.suspAbortArmed = false // round2 偏差 #4：会话退出即解除挂起中止武装（防跨会话粘滞）
+    if (aborted) {
+      // §15 abort 语义：清池不注入（用户显式停——不注入陈旧错误）
+      agent._asyncSubagents?.clear()
+      agent._asyncAdvisors?.clear()
+      agent._asyncQueue = []
+      // ASYNC-RESULT-CONTAINER.md D2：pending 单容器——中止清容器不注入陈旧结果（四族
+      // 统一一处清；consult 会话标记 stopped——settle 不入 digest 流——T-R17c）+
+      // children abort。
+      agent._pendingAsyncResults = []
+      const { cleanupConsultSessions } = await import("../agent-tools/consult.mjs")
+      cleanupConsultSessions(agent)
+      // §17 round2 偏差 #2-CLI（code review round2 #2-CLI）：中止时不静默丢弃挂起期
+      // 排队的用户消息——Enter 已清空输入框并入 pendingInput（用户视为已发送），
+      // 残余转回 state.queue（{text} 条目，下个普通回合的队列循环续发——零丢失）
+      // + 提示行明示去向（不静默丢）。
+      const queuedN = state.pendingInput?.length ?? 0
+      if (queuedN > 0) {
+        state.queue.push(...state.pendingInput.splice(0).map((t) => ({ text: String(t) })))
+        pushLine(`[background work stopped — ${queuedN} queued message${queuedN > 1 ? "s" : ""} will run as a normal turn]`, C.warn)
+      }
+    } else {
+      // D-S3 ③ 兜底：退出前残余（极端竞态）直注入再退——结果零丢失（AC-S2；
+      // ASYNC-RESULT-CONTAINER.md D2：pending 单容器一处清——注入器按 role 分发
+      // （consult → injectConsultResult；其余 → injectAsyncResult——四族同容器）。
+      const { injectAsyncResult } = await import("../agent-tools/subagent.mjs")
+      const { injectConsultResult } = await import("../agent-tools/consult.mjs")
+      const residual = agent._pendingAsyncResults
+      if (residual?.length) {
+        for (const e of residual.splice(0)) {
+          if (e.role === "consult") await injectConsultResult(agent, e)
+          else await injectAsyncResult(agent, e)
+        }
+      }
+    }
+    // 补发 done 冻结：驻留面板的 awaiting-digest 块随池空冻结进流（T-S14）
+    freezeAllSubTasks(state)
+    sweepToolBlocks(state)
+    state.status = "Ready"
+    render()
+  }
+}