thincoder 0.12.58 → 0.12.60

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

package/src/tui/tool-args.mjs

@@ -48,8 +48,16 @@ export function describeToolArgs(name, args) {
     case "advisor": return String(a.type ?? "review")
     case "read_image": return String(a.path ?? "")
     case "question": return String(a.question ?? "").replace(/\s+/g, " ").trim().slice(0, 60)
-    case "memory_put": return String(a.title ?? "")
-    case "memory_search": return String(a.query ?? "")
+    case "memory": {
+      // §6 action-routed summary (D-M5): one readable line per action
+      const action = String(a.action ?? "")
+      if (action === "put") return String(a.title ?? "")
+      if (action === "search") return String(a.query ?? "")
+      if (action === "list") return [a.layer && `layer ${a.layer}`, a.type && `type ${a.type}`, a.keyword && `kw ${a.keyword}`].filter(Boolean).join(" ")
+      if (action === "delete") return a.id ? `id ${a.id}${a.layer ? ` (layer ${a.layer})` : ""}` : `batch ${a.layer ?? ""} ${a.type ? `type ${a.type} ` : ""}${a.keyword ? `kw ${a.keyword}` : ""}`.trim()
+      if (action === "clear") return `clear ${a.layer ?? ""}`
+      return action || JSON.stringify(a)
+    }
     case "lsp": return [a.subcommand, a.uri].filter(Boolean).map(String).join(" ")
     case "repo_outline": return a.path ? String(a.path) : ""
     case "checkpoint": return [a.checkpointAction ?? a.action, a.checkpointId, a.path].filter(Boolean).map(String).join(" ")

package/src/tui/tool-display.mjs

@@ -0,0 +1,142 @@
+/**
+ * tool-display.mjs — 工具块显示/计时/清扫 helper 族（2026-09-05 module-split：
+ * tool-events.mjs 537 > 500 硬限——28-162 区（ticks/subActions maps、sweep/slim/
+ * settle/async 探测/find）verbatim 迁入，语义零变；tool-events.mjs import 回
+ * （buildToolCallbacks 调用点零改）+ re-export sweepToolBlocks（agent-turn 消费面）。
+ * 注意：_subActions/_subActionQ/_toolTicks 为模块级**可变对象**导出——ESM 只读绑定
+ * 不禁内容变更（.set/.delete/.push），调用方行为与同模块时代一致。
+ */
+
+// Tool execution start timestamps (performance.now ms). Keyed by tool_call id
+// when available (parallel same-name tools each get their own tick — the
+// P0-3 fix, 2026-08-30), falling back to a per-name FIFO queue for callers
+// without ids (subagent relay). FIFO shift assumes near-call-order completion;
+// a parallel same-name batch finishing out of order swaps durations between
+// siblings — same magnitude, both keep an elapsed (display-level, acceptable).
+
+// Named caps (consult P2, 2026-08-30): inline 200/8/120/3/5 were magic numbers.
+export const TOOL_OUTPUT_LINE_CAP = 200     // per-call streaming output ring buffer
+export const SUBAGENT_PREVIEW_LINES = 8     // report preview rows in the conversation
+export const PREVIEW_LINE_CHARS = 120       // per-line preview slice
+export const REMINDER_CAP = 3               // max pending reminders shown on turn end
+export const REMINDER_PERSIST_TURNS = 5     // persist reminders every N turns
+
+export const _toolTicks = new Map()
+// §19 action registry: tool_call id → subagent action (non-spawn only — spawn is
+// the default when no record exists). onToolCall sees the args, onToolResult only
+// the name; without the record every subagent result would route as a spawn.
+export const _subActions = new Map()
+export const _subActionQ = [] // FIFO for subagent calls without a tool id (same fallback as tick queue)
+
+export function tickStart(name, toolId) {
+  const key = toolId ?? name
+  if (toolId) { _toolTicks.set(key, performance.now()); return }
+  const q = _toolTicks.get(key) ?? []
+  q.push(performance.now())
+  _toolTicks.set(key, q)
+}
+
+/** Settle one pending tick: by tool_call id, or per-name FIFO. Returns start or null. */
+export function tickTake(name, toolId) {
+  const key = toolId ?? name
+  const v = _toolTicks.get(key)
+  if (v === undefined) return null
+  if (toolId) { _toolTicks.delete(key); return v }
+  if (v.length === 0) { _toolTicks.delete(key); return null }
+  const started = v.shift()
+  if (v.length === 0) _toolTicks.delete(key)
+  return started
+}
+
+/** P0-2 sweep (2026-08-30 consult): an interrupted turn (Ctrl+C / error) leaves
+ *  running tool-block carriers without an onToolResult — their header would say
+ *  "running" forever. runAgentTurn's finally calls this: mark them done with an
+ *  "(interrupted)" status and clear the tick table so no stale start time leaks
+ *  into the next turn. Mirrors freezeAllSubTasks for the tool-block family. */
+export function sweepToolBlocks(state) {
+  for (const l of state.lines ?? []) {
+    const b = l._toolBlock
+    if (b && !b.done) {
+      b.done = true
+      b.summary = "(interrupted)"
+      b.interrupted = true
+    }
+  }
+  _toolTicks.clear()
+  _subActions.clear()
+  _subActionQ.length = 0
+}
+
+/** Shared display guard for tool results — LIVE and RESTORE use the same
+ *  function (P1, 2026-08-30 consult: restore lacked the live path's guards).
+ *  1) Multimodal results (read_image) embed FULL base64 images in the JSON —
+ *     the human needs only the text part (model gets images via the multimodal
+ *     channel); 2) results beyond maxRows are truncated in the block (full
+ *     text always lives in history for the model). Returns row array. */
+export function slimToolResultForDisplay(result, maxRows = 400) {
+  let displayResult = result
+  try {
+    const parsed = JSON.parse(result)
+    if (parsed?.images?.length) displayResult = parsed.text ?? result
+  } catch { /* not JSON — show as-is */ }
+  const rows = String(displayResult).split("\n").filter((l) => l.trim())
+  return rows.length > maxRows
+    ? [...rows.slice(0, maxRows), `… (result truncated at ${maxRows} rows — full text in history)`]
+    : rows
+}
+/** Mark the dispatch-level tool carrier done when its result is consumed by a
+ *  dedicated branch (subagent/escalate/advisor blocks) — without this the turn
+ *  sweep mislabels successful calls as "(interrupted)" (consult P1, 2026-08-30). */
+export function settleToolBlock(state, name, toolId, summary) {
+  const block = findToolBlock(state, name, toolId)
+  if (block) {
+    block.done = true
+    block.summary = summary
+    const started = tickTake(name, toolId)
+    block.elapsed = started !== null ? Math.round(performance.now() - started) : null
+  }
+}
+
+/** Async spawn detection (§15 D-A1): the subagent tool's async:true result is a
+ *  status JSON ({id, role, status: running|queued}), NOT a report — the child
+ *  keeps running, so its activity block must not be frozen at spawn time (it
+ *  freezes via the ⟦ev⟧done event at settle — §15 D-A3). */
+export function isAsyncSpawnResult(result) {
+  try {
+    const o = JSON.parse(result)
+    return Boolean(o && typeof o === "object" && typeof o.id !== "undefined" && (o.status === "running" || o.status === "queued"))
+  } catch {
+    return false
+  }
+}
+
+/** §7.2.3 spawn 门拒错误探测（T-F5）：subagent spawn 的机械拒绝以 {status:"error"}
+ *  JSON 返回（例：manual auto-turn digest spawn 门——digest 语义 organize-only）——
+ *  错误路径不得触发完成冻结（round1 #1——错误路径不冻结任何 running 块）。该形态只
+ *  出现在无 subKey 的拒绝路径（成功路径恒带 dispatch 传的 ctx._subagentKey）。 */
+export function isSpawnErrorResult(result) {
+  try {
+    const o = JSON.parse(result)
+    return Boolean(o && typeof o === "object" && o.status === "error")
+  } catch {
+    return false
+  }
+}
+
+/** Find the live tool-block carrier for a tool event: exact id match when the
+ *  callback carries one (P0-3 — parallel same-name tools route to their own
+ *  block); falls back to the last unfinished block of that name. */
+export function findToolBlock(state, name, toolId) {
+  const lines = state.lines ?? []
+  if (toolId !== undefined && toolId !== null) {
+    for (let i = lines.length - 1; i >= 0; i--) {
+      if (lines[i]._toolBlock?.id === toolId) return lines[i]._toolBlock
+    }
+    return null
+  }
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const b = lines[i]._toolBlock
+    if (b && b.name === name && !b.done) return b
+  }
+  return null
+}