thincoder 0.12.49 → 0.12.51

package/src/tui/render-frame.mjs

@@ -10,7 +10,7 @@ import { ansi, C, ESC } from "./ansi.mjs"
 import { convCacheKey, renderConversation, countConvLines } from "./render-conversation.mjs"
 import { sliceByWidth, stringWidth, sanitizeDisplay } from "./render.mjs"
 import { specForModel } from "../config.mjs"
-import { computeLayout, MAX_SUB_LINES } from "./layout.mjs"
+import { computeLayout } from "./layout.mjs"
 import { basename } from "node:path"
 
 export { convCacheKey, renderConversation, countConvLines } from "./render-conversation.mjs"
@@ -45,93 +45,16 @@ export function renderHeader(agent, cols) {
   return `${ansi.bold}${C.tool} ThinCoder ${ansi.reset}${ansi.dim}│ ${sliceByWidth(model, 30)}${thinkBadge ? " " + thinkBadge : ""} │ ${sliceByWidth(basename(agent.cwd), Math.max(10, cols - 60))}${ansi.reset}`
 }
 
-/** Todo/task panel. Returns empty array when no tasks visible. */
+/** Todo/task panel. Returns empty array when no tasks visible. The first row is
+ *  a divider line separating the panel from the conversation above it (user
+ *  request 2026-08-30). */
 export function renderTodo(visibleTasks, cols) {
-  return visibleTasks.map((t) => {
+  const divider = `${C.dim}${"─".repeat(Math.max(1, cols - 1))}${ansi.reset}`
+  return [divider, ...visibleTasks.map((t) => {
     const mark = t.status === "done" ? "✓" : t.status === "in_progress" ? "▶" : "○"
     const color = t.status === "done" ? `${C.dim}${ESC}[9m` : t.status === "in_progress" ? C.tool : C.text
     return `${color} ${mark} ${sliceByWidth(t.title, cols - 4)}${ansi.reset}`
-  })
-}
-
-/** Subagent panel. Returns empty when no subagents. */
-export function renderSubagent(allSubs, W) {
-  const subs = allSubs
-  if (subs.length === 0) return []
-  const out = []
-  for (const s of subs.slice(0, MAX_SUB_LINES)) {
-    const icon = s.done ? "✓" : "…"
-    const color = s.done ? C.dim : C.tool
-    const label = `[${s.role}${s.model ? " · " + s.model : ""}]`.padEnd(10)
-    let content
-    if (s.done) {
-      const elapsed = Math.floor((Date.now() - s.started) / 1000)
-      content = `done ${elapsed}s`
-    } else if (s.tool) {
-      content = s.tool
-    } else if (s.text) {
-      const textLines = s.text.split("\n").filter((l) => l.trim())
-      content = textLines.length > 0 ? textLines[textLines.length - 1] : "thinking..."
-    } else {
-      content = "thinking..."
-    }
-    out.push(`${color} ${icon} ${label} ${sliceByWidth(content, Math.max(10, W - 4 - stringWidth(label)))}${ansi.reset}`)
-  }
-  if (subs.length > MAX_SUB_LINES) {
-    out.push(`${C.dim}  ... +${subs.length - MAX_SUB_LINES} more subagents${ansi.reset}`)
-  }
-  return out
-}
-
-/** Per-kind panel colors: reasoning faint, tool progress cyan, main output gray. */
-const PANEL_KIND_COLORS = { think: C.reason, tool: C.tool, text: C.dim }
-
-/**
- * Flatten panel parts into display lines, tracking each line's kind.
- * A part not starting mid-line continues the previous line (kind of the line's first fragment wins).
- */
-function panelLines(p) {
-  const lines = []
-  for (const part of p.parts ?? []) {
-    part.text.split("\n").forEach((seg, j) => {
-      if (j === 0 && lines.length > 0) {
-        const last = lines[lines.length - 1]
-        // Empty trailing line = previous part ended exactly at a line break — the new
-        // part owns this line's kind. Otherwise it's a genuine mid-line continuation.
-        if (last.text === "") last.kind = part.kind
-        last.text += seg
-      } else {
-        lines.push({ kind: part.kind, text: seg })
-      }
-    })
-  }
-  return lines.filter((l) => l.text.trim())
-}
-
-/** Tool output panels (streaming output like tail -f). Returns empty when no visible output. */
-export function renderOutput(state, W, panelH) {
-  // Same visibility predicate as computeLayout: done panels linger until closeAt
-  const active = Object.entries(state.outputPanels ?? {}).filter(([_, p]) => !p.done || (p.closeAt ?? 0) > Date.now())
-  if (active.length === 0) return []
-  const out = []
-  const linesPerPanel = Math.max(1, Math.floor(panelH / active.length))
-  for (const [toolName, p] of active) {
-    const status = p.done ? `${C.dim}done${ansi.reset}` : `${C.tool}running${ansi.reset}`
-    out.push(`${C.text}❯ ${sliceByWidth(sanitizeDisplay(toolName), Math.max(10, W - 25))} — ${status}`)
-    const titleRows = 1
-    const contentRows = Math.max(0, linesPerPanel - titleRows)
-    const lines = contentRows > 0 ? panelLines(p).slice(-contentRows) : []
-    for (const l of lines) {
-      const color = PANEL_KIND_COLORS[l.kind] ?? C.dim
-      out.push(`${color}  │ ${sliceByWidth(sanitizeDisplay(l.text), W - 5)}${ansi.reset}`)
-    }
-  }
-  // Safety: never exceed allocated height (could happen with many panels + small terminal)
-  if (out.length > panelH) out.length = panelH
-  // Fill remaining rows to match panelH exactly. `out.length` is accurate because
-  // every pushed entry is a non-empty string (title or content line with prefix).
-  for (let i = out.length; i < panelH; i++) out.push("")
-  return out
+  })]
 }
 
 /** Permission preview panel. Returns empty when no permission request. */
@@ -293,7 +216,7 @@ export function renderRows(state, agent, opts) {
   const slashCommands = opts.slashCommands ?? []
 
   const layout = computeLayout(state, { cols, rows })
-  const { W, panels, inputLayout, inputOffset, boxLines, visibleTasks, allSubs, permPreviewLines, overlay } = layout
+  const { W, panels, inputLayout, inputOffset, boxLines, visibleTasks, permPreviewLines, overlay } = layout
 
   const screen = new Array(rows).fill("")
   const put = (y, lines) => {
@@ -303,9 +226,7 @@ export function renderRows(state, agent, opts) {
   }
 
   put(panels.header.y, [renderHeader(agent, cols)])
-  put(panels.conversation.y, renderConversation(state, cols, panels.conversation.h, state.scroll))
-  if (panels.subagent) put(panels.subagent.y, renderSubagent(allSubs, W))
-  if (panels.output) put(panels.output.y, renderOutput(state, W, panels.output.h))
+  put(panels.conversation.y, renderConversation(state, cols, panels.conversation.h, state.scroll, rows))
   if (panels.todo) put(panels.todo.y, renderTodo(visibleTasks, cols))
   if (panels.picker) put(panels.picker.y, renderPicker(state, cols, panels.picker, overlay))
   if (panels.permission) put(panels.permission.y, renderPermission(permPreviewLines))

package/src/tui/render-loop.mjs

@@ -56,19 +56,23 @@ export function createRenderLoop(state, agent, ctx, pushLine, write = (s) => pro
 
   function doRender() {
     try {
-      const dims = { cols: process.stdout.columns || startupDims.cols, rows: process.stdout.rows || startupDims.rows }
+      // Single source (Windows ConPTY instability, 2026-08-30). CACHE ONLY —
+      // no per-frame refresh: during heavy streaming output ConPTY reports a
+      // STALE buffer size (80) and per-frame sampling let that stale value
+      // hijack the cache (streaming content crammed into a left-hand sliver,
+      // restored to full width only after flush stopped the output). dims are
+      // updated by: startup seed + a delayed re-sample + resize events.
+      const dims = state.dims ? state.dims.get() : { cols: process.stdout.columns || startupDims.cols, rows: process.stdout.rows || startupDims.rows }
 
-      // Expired output panels: prune once their close grace elapsed (done + closeAt in the past)
-      const now = Date.now()
-      for (const [name, p] of Object.entries(state.outputPanels ?? {})) {
-        if (p.done && (p.closeAt ?? 0) <= now) delete state.outputPanels[name]
-      }
+      // NOTE (§7.2 D6): the old state.outputPanels prune is gone — output panels
+      // are abolished; subagent blocks live in the conversation and are never
+      // auto-pruned (bounded by the N2 per-child line cap instead).
 
       const { rows, cursorRow, cursorCol, layout } = renderRows(state, agent,
         { cols: dims.cols, rows: dims.rows, slashCommands: SLASH_COMMANDS })
 
       // Clamp scroll (bookkeeping for the status-bar hint; renderConversation clamps internally too)
-      state.scroll = Math.min(state.scroll, Math.max(0, countConvLines(state, dims.cols) - layout.panels.conversation.h))
+      state.scroll = Math.min(state.scroll, Math.max(0, countConvLines(state, dims.cols, dims.rows) - layout.panels.conversation.h))
 
       if (state.ctxCache.len !== agent.history.length) {
         state.ctxCache = { len: agent.history.length, tokens: estimateTokens(agent.history) }
@@ -107,5 +111,5 @@ export function createRenderLoop(state, agent, ctx, pushLine, write = (s) => pro
     }
   }
 
-  return { render, scheduleRender }
+  return { render, scheduleRender, get lastRenderAt() { return lastRenderAt } }
 }

package/src/tui/render.mjs

@@ -209,6 +209,11 @@ const ANSI_SEQUENCE_RE = new RegExp(ANSI_SEQUENCE.source, "g")
 export function sanitizeDisplay(s) {
   return s
     .replace(ANSI_SEQUENCE_RE, "")
+    // §7.2 D5 fallback: an unparsed ⟦ev⟧ event token must never reach the grid —
+    // strip the sentinel + its RS-wrapped payload (⟦ev⟧turn\x1e…\x1e / bare RS/GS chars).
+    .replace(/⟦ev⟧[^\x1e\x1d]*\x1e[^\x1e\x1d]*\x1e[^\x1e\x1d]*\x1e[^\x1e\x1d]*\x1e?/g, "")
+    .replace(/⟦ev⟧[^\x1e\x1d]*/g, "")
+    .replace(/[\x1d\x1e]/g, "")
     .replace(/\r\n/g, "\n")
     .replace(/\r/g, "\n")
     .replace(/\t/g, "    ")

package/src/tui/startup.mjs

@@ -1,5 +1,8 @@
 import { listSlots } from "../session.mjs"
 import { ansi, C } from "./ansi.mjs"
+import { describeToolArgs, toolArgsLines } from "./tool-args.mjs"
+import { sliceByWidth } from "./render.mjs"
+import { slimToolResultForDisplay } from "./tool-events.mjs"
 
 /** Lazy history window (parity with VS Code HISTORY_PAGE_SIZE): first paint loads
  *  the latest INITIAL_HISTORY_MESSAGES, then PgUp-at-top loads HISTORY_PAGE_MESSAGES
@@ -28,9 +31,19 @@ export function historyToLines(history, startIdx, endIdx) {
     const m = history[i]
     if (m.role === "user") {
       if (typeof m.content === "string" && m.content.startsWith("[System reminder:")) continue
+      // Label only when there is something to show: multimodal user messages
+      // (content = [text, image] array, injected after read_image) render NO
+      // text on restore — the image is invisible to the terminal and the user
+      // just saw it live. A label with no content under it is noise (user
+      // report 2026-08-30: stray "❯ You:" after the read_image block).
+      const userText = typeof m.content === "string"
+        ? m.content
+        : (Array.isArray(m.content) ? m.content.find((p) => p?.type === "text")?.text ?? "" : "")
+      const displayable = typeof m.content === "string" ? !!m.content : !!(userText && userText.trim())
+      if (!displayable) continue
       if (lines.length > 0) lines.push({ text: "", color: C.dim })
       lines.push({ text: "❯ You:", color: ansi.bold + C.user })
-      if (typeof m.content === "string" && m.content) lines.push({ text: m.content, color: C.text })
+      if (userText) lines.push({ text: userText, color: C.text, _kind: "text" })
       inTurn = false
     } else if (m.role === "assistant") {
       if (!inTurn) {
@@ -39,22 +52,57 @@ export function historyToLines(history, startIdx, endIdx) {
         lines.push({ text: "❯ ThinCoder:", color: ansi.bold + C.assistant })
       }
       inTurn = true
-      // Reasoning restored as dim lines (folded by the consecutive-dim rule when
-      // long) — matches the live thinking stream instead of vanishing on restore.
+      // Reasoning restored as ONE C.reason line entry — the exact shape
+      // flushStream produces live (single line, full string, no indent), so
+      // buildConvLines treats restored thinking IDENTICALLY: >12 wrapped rows
+      // fold under the named "▶ thinking" header, short fragments stay visible
+      // — same thresholds, same label, both paths. (History: restored thinking
+      // used to be split into dim fragments — the consecutive-dim rule's >8
+      // threshold never fired on short agentic thinking bursts, so restored
+      // sessions showed every fragment unfolded and mislabeled "tool output";
+      // user reported thinking "no longer folds" after a restart, 2026-08-30.)
       const reasoning = m.reasoning_content ?? m.reasoning
-      if (typeof reasoning === "string" && reasoning.trim()) {
-        for (const line of reasoning.split("\n")) lines.push({ text: "  " + line, color: C.dim })
-      }
+      if (typeof reasoning === "string" && reasoning.trim()) lines.push({ text: reasoning, color: C.reason, _kind: "thinking" })
       if (typeof m.content === "string" && m.content) lines.push({ text: m.content, color: C.text })
       for (const tc of m.tool_calls ?? []) {
         const toolResult = history[i + 1]
         const hasResult = toolResult?.role === "tool" && toolResult?.tool_call_id === tc.id
-        lines.push({ text: `  [tool] ${tc.function?.name ?? "?"}`, color: C.tool })
-        if (hasResult && String(toolResult.content).trim()) {
-          // FULL tool result as dim lines (auto-folded when > 8) — the old
-          // first-line-only summary made restore feel nothing like the live run.
-          for (const line of String(toolResult.content).split("\n")) lines.push({ text: "  " + line, color: C.dim })
-        }
+        const tcName = tc.function?.name ?? "?"
+        // Tool arguments are part of the visible conversation (2026-08-30 user
+        // report: restored sessions showed no args at all — the deprecated
+        // display snapshot made historyToLines the ONLY restore path, and it
+        // never rendered arguments). Header line = readable key-args summary
+        // (describeToolArgs, vscode card-header parity); full pretty JSON rides
+        // below as dim lines, auto-folded by the consecutive-dim rule exactly
+        // like the restored tool result — same convention, same readability.
+        let argsSummary = ""
+        let argJson = []
+        let rawArgs = null
+        try {
+          const args = JSON.parse(tc.function?.arguments || "{}")
+          argsSummary = describeToolArgs(tcName, args)
+          argJson = toolArgsLines(args)
+        } catch { rawArgs = String(tc.function?.arguments ?? "").slice(0, 120) /* malformed — raw fallback */ }
+        // ONE BLOCK PER TOOL CALL — same carrier the live path emits (user
+        // ruling 2026-08-30): header=name+args, body=args JSON + result.
+        // Same carrier the live path emits — identical fields, so buildConvLines
+        // renders both through one code path (line-level parity by construction).
+        lines.push({
+          text: "", color: C.tool,
+          _kind: "tool",
+          _toolBlock: {
+            name: tcName,
+            roundTag: "",
+            argsSummary,
+            argsJson: rawArgs ? [rawArgs] : argJson,
+            output: [],
+            result: hasResult ? slimToolResultForDisplay(String(toolResult.content)) : null,
+            summary: null,
+            started: 0,
+            done: true,
+            elapsed: null,
+          },
+        })
       }
     }
   }
@@ -72,7 +120,13 @@ export function restoreLines(state, history) {
   const total = Array.isArray(history) ? history.length : 0
   if (total === 0) return
   const start = Math.max(0, total - INITIAL_HISTORY_MESSAGES)
-  state.lines.push(...historyToLines(history, start, total))
+  state._lineIdCounter = state._lineIdCounter ?? 0
+  const fresh = historyToLines(history, start, total)
+  // Stable per-line ids (P1, 2026-08-30): fold keys for tool blocks derive from
+  // _lineId so loadOlder's head-unshift cannot re-bind an expanded block to a
+  // different tool (positional tool-{i} keys drift under unshift).
+  for (const l of fresh) l._lineId = ++state._lineIdCounter
+  state.lines.push(...fresh)
   state._historyLoaded = total - start
   state._historyTotal = total
   state._hasOlder = start > 0

package/src/tui/subagent-blocks.mjs

@@ -0,0 +1,326 @@
+/**
+ * subagent-blocks.mjs — 子agent 活动区块缓冲（AGENT-LOOP.md §7.2 D4，消费端）。
+ *
+ * state.subTasks[key] 是完整的活动缓冲：{ key, role, model, started, done, doneAt,
+ * blocks: [{kind,text}], currentTool, toolArgs, turn, maxTurns, approval, lastError,
+ * dropped, blockEpoch }。区块是子agent 活动的唯一载体（子工具调用不进父历史），
+ * 跨 turn 保留、可重新展开；渲染为会话流内可折叠区块（render-conversation.mjs）。
+ *
+ * 数据层职责：前缀路由、事件 token 解析（D1/D2）、kind 合并追加、N2 环形上限、
+ * N1 渲染节流（渲染调度节流，数据追加永不延迟）、完成冻结（freezeSubTaskLines
+ * 家族——_frozenSubTask 载体行，渲染端 render-conversation.mjs 识别）。
+ */
+
+import { C } from "./ansi.mjs"
+
+/** `role#id/` prefix router — hyphen included since the eng-coder fix (2026-08-21). */
+export const SUB_PREFIX_RE = /^([\w-]+)#(\d+)\//
+/** ⟦ev⟧ event token parser (D1/D2): `⟦ev⟧<name>\x1e<n>\x1e<max>\x1e<phase>\x1e<detail>`. */
+export const SUB_EVENT_RE = /^⟦ev⟧(turn|approval)\x1e([^\x1e]*)\x1e([^\x1e]*)\x1e([^\x1e]*)\x1e?([\s\S]*)$/
+/** N2: per-child display-line ring buffer cap — oldest lines drop with a marker. */
+export const SUB_BLOCK_LINE_LIMIT = 500
+/** N1: render-layer throttle for child tool-output appends (generation relays verbatim). */
+export const SUB_RELAY_THROTTLE_MS = 250
+/** Roles a subagent tool child can take (finishSubTask matches the block's role). */
+export const SUBAGENT_ROLES = ["sub", "explore", "plan", "coder", "eng-coder"]
+
+let _subRenderLast = 0
+let _subRenderTimer = null
+
+/** N1 throttle: leading-edge render + one coalesced trailing flush (final chunk
+ *  within a window is not lost). Data appends are NEVER throttled — rendering only. */
+export function throttleSubRender(scheduleRender) {
+  const now = performance.now()
+  const wait = SUB_RELAY_THROTTLE_MS - (now - _subRenderLast)
+  if (wait <= 0) {
+    _subRenderLast = now
+    scheduleRender()
+    return
+  }
+  if (_subRenderTimer) return
+  _subRenderTimer = setTimeout(() => {
+    _subRenderTimer = null
+    _subRenderLast = performance.now()
+    scheduleRender()
+  }, wait)
+  _subRenderTimer.unref?.()
+}
+
+export function ensureSubTask(state, subMatch) {
+  const key = `${subMatch[1]}#${subMatch[2]}`
+  // Tombstone guard (2026-08-30 consult residual): a child aborted mid-flight
+  // can relay tail tokens AFTER its block was frozen — ensureSubTask must not
+  // resurrect it (the recreated running block had no one left to freeze it and
+  // sat pinned above the input box until the next turn).
+  state._frozenSubKeys ??= new Set()
+  if (state._frozenSubKeys.has(key)) return null
+  state.subTasks ??= {}
+  if (!state.subTasks[key]) {
+    state.subTasks[key] = {
+      key, role: subMatch[1], model: undefined, started: Date.now(), done: false, doneAt: null,
+      blocks: [], currentTool: null, toolArgs: null, turn: 0, maxTurns: 0, approval: null,
+      lastError: null, dropped: 0,
+    }
+  }
+  return state.subTasks[key]
+}
+
+const countBlockLines = (text) => text.split("\n").length
+
+/** Append (kind-merging) with the N2 ring-buffer cap. fresh=true starts a new block
+ *  even when the previous block has the same kind (used per tool call). */
+export function appendSubBlock(sub, kind, text, { fresh = false } = {}) {
+  if (!text) return
+  const last = sub.blocks.at(-1)
+  if (!fresh && last && last.kind === kind) {
+    // Merged append: account only the NET new lines. Counting the full split of
+    // every single-line chunk (each ends with \n → 2 segments) would inflate the
+    // incremental total far above the block's real line count (P1 修, 2026-08-30).
+    const before = countBlockLines(last.text)
+    last.text += text
+    sub._lineCount = (sub._lineCount ?? 0) + countBlockLines(last.text) - before
+  } else {
+    sub.blocks.push({ kind, text })
+    sub._lineCount = (sub._lineCount ?? 0) + countBlockLines(text)
+  }
+  sub.blockEpoch = (sub.blockEpoch ?? 0) + 1
+  trimSubBlocks(sub)
+}
+
+/** N2: keep at most SUB_BLOCK_LINE_LIMIT display lines per child; drop oldest
+ *  lines and leave one cumulative "…（已省略 N 行）" marker block. Done blocks
+ *  are bounded by the same cap (called from every append). */
+export function trimSubBlocks(sub) {
+  // Incremental line accounting (P1, 2026-08-30): appendSubBlock keeps
+  // sub._lineCount; the old implementation recomputed the total with a full
+  // blocks.reduce on EVERY append — O(n) per token, O(n²) over a stream.
+  sub._lineCount = (sub._lineCount ?? 0)
+  let over = sub._lineCount - SUB_BLOCK_LINE_LIMIT
+  if (over <= 0) return
+  let droppedNow = 0
+  while (over > 0 && sub.blocks.length > 0) {
+    const first = sub.blocks[0]
+    const lines = countBlockLines(first.text)
+    const take = Math.min(lines, over)
+    if (take >= lines) {
+      sub.blocks.shift()
+      droppedNow += lines
+    } else {
+      first.text = first.text.split("\n").slice(take).join("\n")
+      droppedNow += take
+    }
+    over -= take
+  }
+  sub._lineCount -= droppedNow
+  sub.dropped += droppedNow
+  const marker = `…（已省略 ${sub.dropped} 行）`
+  const first = sub.blocks[0]
+  if (first && first.kind === "meta") first.text = marker
+  else { sub.blocks.unshift({ kind: "meta", text: marker }); sub._lineCount += 1 }
+}
+
+/** 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
+}
+
+/** Freeze a finished (or interrupted) child's activity block into state.lines
+ *  (§7.2 D4 — the block is the child activity's only carrier; moved here from
+ *  agent-turn.mjs 2026-08-30). Rendering it as a pinned conversation-tail section
+ *  made every ✓ block a permanent "ghost" stuck above the input box (user report
+ *  2026-08-30); frozen into the stream it scrolls away with the conversation AND
+ *  stays an independent collapsible block — the folded form is a single header
+ *  summary line, the expanded form re-renders the full activity timeline from the
+ *  SAME block source. The payload travels as a JSON line flagged with
+ *  _frozenSubTask; render-conversation.mjs recognizes it and renders the ▶/▼
+ *  interaction keyed by `sub-${key}` (user ruled 2026-08-30: clickable after
+ *  freezing — full design interaction, not a dim-lines fallback). subTasks loses
+ *  the entry on release; memory stays bounded by N2 (ring buffer already applied). */
+export function freezeSubTaskLines(state, sub) {
+  if (!sub) return
+  state._frozenSubKeys ??= new Set()
+  state._frozenSubKeys.add(sub.key)
+  if (!sub) return
+  sub.done = true
+  sub.doneAt = sub.doneAt ?? Date.now()
+  state.lines.push({ text: `subagent activity: ${sub.key}`, color: C.dim, _frozenSubTask: sub })
+}
+
+/** Freeze + release every already-done child block (tool-result sweep:
+ *  subagent/escalate/consult-check completions each call this after finishSubTask). */
+export function freezeDoneSubTasks(state) {
+  for (const key of Object.keys(state.subTasks ?? {})) {
+    if (state.subTasks[key].done) {
+      freezeSubTaskLines(state, state.subTasks[key])
+      delete state.subTasks[key]
+    }
+  }
+}
+
+/** Mark ALL running blocks of the given role(s) done — session-level settle.
+ *  A consult spawns N parallel children (consult#1..#N); the single-shot
+ *  finishSubTask only ever settled the earliest one, leaving N-1 running
+ *  ghosts pinned above the input box until turn end (consult residual,
+ *  2026-08-30 consult review — 4/4 models converged on this). */
+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
+    }
+  }
+}
+
+/** Precise settle: mark the child of `role` whose [model] token recorded
+ *  `model` as done. consult_check returns the reply's model — the earliest-
+ *  running heuristic froze the WRONG block when models settle out of order. */
+export function finishSubTaskByModel(state, role, model, lastError = null) {
+  state.subTasks ??= {}
+  // Model-string normalization (2026-08-30 follow-up consult): the [model]
+  // token carries the BARE model name (resolveChildProvider keeps mname),
+  // while consult_check's r.model is consultLabel = "provider:model". Compare
+  // tail segments — a full "provider:model" reply matches a bare-name block.
+  const want = String(model ?? "").includes(":") ? String(model).split(":").pop() : String(model ?? "")
+  for (const sub of Object.values(state.subTasks)) {
+    const have = String(sub.model ?? "")
+    const haveTail = have.includes(":") ? have.split(":").pop() : have
+    if (!sub.done && sub.role === role && haveTail === want) {
+      sub.done = true
+      sub.doneAt = Date.now()
+      sub.currentTool = null
+      sub.approval = null
+      if (lastError) sub.lastError = lastError
+      sub.blockEpoch = (sub.blockEpoch ?? 0) + 1
+      return sub
+    }
+  }
+  return null
+}
+
+/** Turn-end sweep (runAgentTurn finally): freeze ALL remaining blocks — interrupted
+ *  runs (Ctrl+C abort / error mid-turn) would otherwise linger as pinned ghosts
+ *  above the input box. Not-done children get done + lastError="interrupted"
+ *  (skipped when the status already recovered to "Ready"). */
+export function freezeAllSubTasks(state) {
+  for (const key of Object.keys(state.subTasks ?? {})) {
+    const sub = state.subTasks[key]
+    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[key]
+  }
+}
+
+/**
+ * Apply one ⟦ev⟧ event token payload to the child's block header (D1/D2):
+ * turn/approval update turn n/max + waiting state. Events NEVER enter blocks
+ * or the main stream — header only.
+ * @returns {boolean} true = payload was a well-formed event token (consumed)
+ */
+export function applySubEvent(sub, payload) {
+  const ev = payload.match(SUB_EVENT_RE)
+  if (!ev) return false
+  if (ev[1] === "turn") {
+    sub.turn = Number(ev[2]) || sub.turn
+    sub.maxTurns = Number(ev[3]) || sub.maxTurns
+    sub.approval = null
+  } else if (ev[1] === "approval") {
+    sub.turn = Number(ev[2]) || sub.turn
+    sub.maxTurns = Number(ev[3]) || sub.maxTurns
+    sub.approval = ev[5] ? ev[5].slice(0, 40) : (ev[4] === "approval" ? "tool" : ev[4])
+  }
+  return true
+}
+
+// ─── Prefix routing (agent-turn callbacks delegate here) ────────────────────
+// Each router returns true when the name/token carried a role#id/ prefix and was
+// consumed into the child's block buffer; false = not a child item (main path).
+
+/** Child LLM text / `[model]` metadata / ⟦ev⟧ event token (onToken branch). */
+export function routeSubToken(state, t, scheduleRender) {
+  const subMatch = t.match(SUB_PREFIX_RE)
+  if (!subMatch) return false
+  const sub = ensureSubTask(state, subMatch)
+  if (!sub) return true // frozen tombstone — late token from an aborted child: drop
+  const payload = t.slice(subMatch[0].length)
+  // ⟦ev⟧ event token: turn/approval progress → header ONLY (never blocks,
+  // never the main stream — D1).
+  if (payload.startsWith("⟦ev⟧")) {
+    applySubEvent(sub, payload)
+    scheduleRender()
+    return true
+  }
+  // `[model]<name>` metadata token: record the subagent's model (may differ from the
+  // parent's) — shown in the block header, NOT appended to its content stream.
+  // Only treat as metadata when the model isn't set yet (it's always the FIRST token);
+  // a child content token that happens to start with "[model]" must not be swallowed.
+  if (payload.startsWith("[model]") && sub.model === undefined) {
+    sub.model = payload.slice(7)
+    scheduleRender()
+    return true
+  }
+  // Child LLM text → text block (N2 cap inside appendSubBlock).
+  appendSubBlock(sub, "text", payload)
+  scheduleRender()
+  return true
+}
+
+/** Child reasoning token → think block (F2: same treatment as main reasoning). */
+export function routeSubReasoning(state, t, scheduleRender) {
+  const subMatch = t.match(SUB_PREFIX_RE)
+  if (!subMatch) return false
+  const sub = ensureSubTask(state, subMatch)
+  if (!sub) return true // frozen tombstone — drop late token
+  appendSubBlock(sub, "think", t.slice(subMatch[0].length))
+  scheduleRender()
+  return true
+}
+
+/** Child tool call → fresh tool block + header currentTool. */
+export function routeSubToolCall(state, name, args, scheduleRender) {
+  const subMatch = name.match(SUB_PREFIX_RE)
+  if (!subMatch) return false
+  const sub = ensureSubTask(state, subMatch)
+  if (!sub) return true // frozen tombstone — drop late token
+  sub.currentTool = name.slice(subMatch[0].length)
+  sub.toolArgs = args
+  sub.approval = null
+  appendSubBlock(sub, "tool", `❯ ${sub.currentTool}${args?.command ? " — " + String(args.command).replace(/\s+/g, " ").trim().slice(0, 80) : ""}\n`, { fresh: true })
+  scheduleRender()
+  return true
+}
+
+/** Child tool output (D1 prefixed-name relay) → append into the CURRENT tool block.
+ *  Data append immediate; render throttled (N1). */
+export function routeSubToolOutput(state, name, part, scheduleRender) {
+  const subMatch = name.match(SUB_PREFIX_RE)
+  if (!subMatch) return false
+  const sub = ensureSubTask(state, subMatch)
+  if (!sub) return true // frozen tombstone — drop late token
+  const toolName = name.slice(subMatch[0].length)
+  appendSubBlock(sub, "tool", part.text + "\n", { fresh: sub.currentTool !== toolName })
+  if (sub.currentTool !== toolName) sub.currentTool = toolName
+  throttleSubRender(scheduleRender)
+  return true
+}