thincoder 0.12.64 → 0.12.65

package/src/tui/key-handler.mjs

@@ -1,10 +1,12 @@
-import { ansi, C } from "./ansi.mjs"
-import { readClipboardText, insertPastedText } from "./clipboard.mjs"
-import { computeLayout, inputContentWidth } from "./layout.mjs"
-import { moveCursorVertical } from "./render.mjs"
+import { computeLayout } from "./layout.mjs"
 import { handleSearchKey } from "./key-handler-search.mjs"
 import { countConvLines } from "./render-conversation.mjs"
 import { handlePermissionMode, handleQuestionMode, handleInterruptMode } from "./key-modes.mjs"
+import { handleCtrlCFamily } from "./key-handler-ctrlc.mjs"
+import { handlePickerKeys, handleWizardKeys } from "./key-handler-modals.mjs"
+import { handleScrollKeys, handleHistoryKeys, handleCursorKeys } from "./key-handler-scroll.mjs"
+import { handleBusyEnter } from "./key-handler-busy.mjs"
+import { handleEditKeys } from "./key-handler-edit.mjs"
 
 /** 第 33 批（TUI §14.3(e)——attention 清位）：输入即在场——仅当原值为真时置假 + `render()`
  *  （已假则零副作用、零重绘）。键盘入口与本文件（`onKeypress`）与鼠标输入路径（index.mjs
@@ -28,12 +30,15 @@ export function convMaxScroll(state) {
 
 /** Keyboard event dispatch: permission confirm / question / picker / wizard / edit / scroll / history / paste.
  *  Extracted from index.mjs.
+ *  2026-09-22 structure-debt §2.1（#226）：五族块体迁出为 key-handler-{ctrlc,modals,scroll,busy,edit}.mjs
+ *  （逐字搬移）；本档保留 attention 清位 / 三模态前置委派 / F1 表 / Ctrl+I 入口 / interrupt 模态 +
+ *  五族顺序委派（委派守卫 = 原块入口条件；族体自持同一入口判定，可直接调用）。
  *  ctx: { agent, state, render, renderPickerLines, popPicker,
  *         handleSlash, handleTab, submit, pasteClipboardImage,
  *         wizardChooseProvider, wizardSubmitText, cancelWizard, wizardProviderItems,
  *         renderWizard, pushLine, cleanup, showPicker } */
 export function createKeyHandler(ctx) {
-  const { agent, state, render, popPicker, renderPickerLines, handleSlash, handleTab, submit, pasteClipboardImage, wizardChooseProvider, wizardSubmitText, cancelWizard, wizardProviderItems, renderWizard, pushLine, cleanup, showPicker, loadOlder } = ctx
+  const { agent, state, render, pushLine, showPicker } = ctx
 
   return function onKeypress(str, key = {}) {
     // 第 33 批（TUI §14.3(e) 键盘点）：模态分派**之前**——任意按键 = 用户在场 ⇒ 清 attention
@@ -50,109 +55,9 @@ export function createKeyHandler(ctx) {
     // Search mode: Ctrl+F to enter, Ctrl+N/Ctrl+P (or Ctrl+G/Ctrl+R) navigate, Esc exit
     if (handleSearchKey(str, key, state, render)) return
 
-    if (key.ctrl && key.name === "c") {
-      // picker 打开时 Ctrl+C = 取消当前 picker（等同 Esc），不杀进程
-      if (state.picker) {
-        popPicker(null)
-        return
-      }
-      // §17.6（2026-09-03）：武装窗口内第二次 Ctrl+C = 显式全停（D-C4 /abort 语义）。
-      // 在状态路由前检查（picker 取消分支例外——picker 打开时 Ctrl+C 语义 = 取消
-      // picker，武装让位；场景极窄——3s 窗口内需另有 picker 被打开）——两次按下之间
-      // 状态会迁移（首按停回合 → 释放窗口/挂起会话启动），武装必须跨态桥接：只查挂起
-      // 分支会让非挂起 processing 首按后的二按落入空闲退出分支（三按误退出应用）。
-      if (state.suspAbortArmed) {
-        if (ctx.suspArmTimer) clearTimeout(ctx.suspArmTimer)
-        state.suspAbortArmed = false
-        // 无可停目标（无 processing 回合 / 无会话 abort 集合 / 未挂起）时不吞键：
-        // 首按停的是普通回合（无后台池）——二按落回下方空闲退出分支（exitArmed 双
-        // 确认），不打印误导性的 "[Aborting background subagents…]"（advisor round1
-        // 🟡——停回合后连按退出的第二次按下被空转吞掉 → 退出从 3 按变 4 按）。
-        const hasStopTarget = (state.processing && state.controller) ||
-          (agent._sessionAbortAll?.length ?? 0) > 0 ||
-          (agent._sessionAbort != null && !agent._sessionAbort.signal.aborted) ||
-          state.suspended
-        if (hasStopTarget) {
-          // 当前回合平 abort（无 interrupt——命中 agent.mjs 回合收尾清池分支——全停）
-          // §20.3 站点 #11（第 24 批）：整批 / 会话级停 = stop（reason 载荷）
-          if (state.processing && state.controller) state.controller.abort({ abortTrigger: "stop", abortDetail: "session-stop" })
-          // 会话 abort 集合 = 链条内全部 controller（含 Ctrl+I/ContinueError 重建的旧
-          // controller——children 不逃逸，round1 偏差 #3）。挂起态才标记 _suspAborted +
-          // 唤醒 driver（driver 收尾清池）——非挂起语境置位会粘滞阻塞未来挂起会话重入
-          // （round2 偏差 #1 语义）。
-          for (const c of agent._sessionAbortAll ?? (agent._sessionAbort ? [agent._sessionAbort] : [])) c?.abort({ abortTrigger: "stop", abortDetail: "session-stop" })
-          if (state.suspended) {
-            state._suspAborted = true
-            state._suspWake?.()
-          }
-          pushLine("[Aborting background subagents…]", C.warn)
-          render()
-          return
-        }
-        // 无目标可停 → 落空继续到下方分支（processing 已停 → 空闲态 exitArmed 双确认）
-      }
-      if (state.suspended) {
-        // §17 D-S9 + round2 偏差 #4（2026-09-02）+ §17.6 修订（2026-09-03）：挂起态
-        // Ctrl+C = 武装窗口两级中止——一次按键直接清池中止全部后台子代理的误触代价高
-        // （digest 刷屏时用户可能只想停住当前回合）；仿空闲态退出武装语义（同下方空闲态
-        // exitArmed 双确认分支）。§17.6 修订 ①：中止当前回合的 abort 带 interrupt
-        // （无 message）——此前平 abort 命中 agent.mjs 回合收尾清池分支（aborted &&
-        // !reason.interrupt → 无条件 _asyncSubagents.clear()），一次首按即误杀全部后台
-        // 子代理（2026-09-03 用户两次实测——提示"再按才杀"与实际"一次就全杀"不符）；
-        // interrupt 排除清池分支——会话与后台保留（agent-turn 区分：无 message 停回合
-        // 不续跑）：
-        //   ① 未武装 + 有回合在跑（digest 消化/会话内回合）：仅中止当前回合
-        //      （controller.abort({ interrupt: true })）——会话继续、后台子代理不受
-        //      影响，回挂起等待；
-        //   ② 未武装 + 纯挂起等待：仅提示不清池；
-        //   ③ 3s 武装窗口内再次 Ctrl+C：彻底中止——上方统一块（二按语义不变）。
-        if (state.processing && state.controller) {
-          state.controller.abort({ interrupt: true }) // ① 仅中止当前回合（digest/会话内回合），不碰后台池
-          pushLine("[stopped current turn — press Ctrl+C again within 3s to abort all background subagents]", C.warn)
-        } else {
-          const bgActive = [...(agent._asyncSubagents?.values() ?? [])].filter((e) => e.status === "running").length + (agent._asyncQueue?.length ?? 0)
-          pushLine(`[abort] Press Ctrl+C again within 3s to abort all background subagents (${bgActive} running)`, C.warn)
-        }
-        state.suspAbortArmed = true
-        if (ctx.suspArmTimer) clearTimeout(ctx.suspArmTimer)
-        ctx.suspArmTimer = setTimeout(() => { state.suspAbortArmed = false }, ctx.exitArmDelay ?? 3000)
-        ctx.suspArmTimer.unref?.()
-        render()
-        return
-      }
-      if (state.processing && state.controller) {
-        // §17.6 D-C1（2026-09-03 紧急修复——processing 态曾无武装窗口，第一按直接平
-        // abort() → 命中 agent.mjs 回合收尾清池分支 → 一次 Ctrl+C 误杀全部后台子代理，
-        // 用户两次实测被坑）：首按 = interrupt 语义（无 message——停当前回合不续跑——
-        // interrupt 排除 agent.mjs 清池分支——后台池保留——agent-turn 区分不重建续跑）
-        // + 武装 3s（复用 suspArmTimer/exitArmDelay——与挂起态同构——过期自动复位）；
-        // 窗口内再按 = 上方统一块全停（平 abort → agent.mjs 清池）。
-        state.controller.abort({ interrupt: true })
-        pushLine("[stopped current turn — press Ctrl+C again within 3s to abort all background subagents]", C.warn)
-        state.suspAbortArmed = true
-        if (ctx.suspArmTimer) clearTimeout(ctx.suspArmTimer)
-        ctx.suspArmTimer = setTimeout(() => { state.suspAbortArmed = false }, ctx.exitArmDelay ?? 3000)
-        ctx.suspArmTimer.unref?.()
-        render()
-        return
-      }
-      // 防误触：空闲态第一次 Ctrl+C 仅提示并武装，窗口内再按才真正退出
-      if (!state.exitArmed) {
-        state.exitArmed = true
-        if (ctx.exitArmTimer) clearTimeout(ctx.exitArmTimer)
-        ctx.exitArmTimer = setTimeout(() => { state.exitArmed = false }, ctx.exitArmDelay ?? 3000)
-        ctx.exitArmTimer.unref?.()
-        pushLine("[exit] Press Ctrl+C again within 3s to exit", C.warn)
-        render()
-        return
-      }
-      if (ctx.exitArmTimer) clearTimeout(ctx.exitArmTimer)
-      cleanup()
-      // 延迟退出可注入（测试传大值并清理定时器，避免定时器在 mock 恢复后调到真 process.exit）
-      ctx.exitTimer = setTimeout(() => process.exit(0), ctx.exitDelay ?? 100)
-      ctx.exitTimer.unref?.()
-      return // review #5 fix: exiting — don't fall through to later branches
-    }
+    // 序 1：Ctrl+C 族（key-handler-ctrlc.mjs）——picker 取消 / 武装窗口全停 / 挂起态两级中止 /
+    // 回合 interrupt / 空闲退出武装（守卫 = 原块入口条件）
+    if (key.ctrl && key.name === "c") { handleCtrlCFamily(str, key, ctx); return }
 
     // F1: 显示快捷键帮助
     if (key.name === "f1" && !state.picker && !state.permission && !state.question) {
@@ -186,289 +91,34 @@ export function createKeyHandler(ctx) {
     // key-modes.mjs handleInterruptMode（D-S4）
     if (handleInterruptMode(str, key, { state, pushLine, render })) return
 
-    // generic list picker: ↑↓/PgUp/PgDn/Home/End 导航，输入即过滤，Enter 选中，Esc 取消
-    if (state.picker) {
-      const p = state.picker
-      const items = p.filteredItems ?? p.entries.filter((e) => e.type === "item")
-      // 可视窗高度：直接取 layout 算出的实际 picker 面板高（含小终端 pickerFinalH 压缩），减标题行。
-      // 单一数据源，避免与 layout.mjs 公式漂移
-      const winH = Math.max(1, (computeLayout(state, { cols: (state.dims?.get() ?? {}).cols ?? (process.stdout.columns || 80), rows: (state.dims?.get() ?? {}).rows ?? ((state.dims?.get() ?? {}).rows ?? (process.stdout.rows || 24)) }).panels.picker?.h ?? p.lines.length + 1) - 1)
-      const applyFilter = (f) => {
-        p.filter = f
-        p.index = 0
-        p.scroll = 0
-        renderPickerLines()
-      }
-      if (key.name === "escape") {
-        popPicker(null)
-      } else if (key.name === "up" && items.length) {
-        p.index = (p.index - 1 + items.length) % items.length
-        renderPickerLines()
-      } else if (key.name === "down" && items.length) {
-        p.index = (p.index + 1) % items.length
-        renderPickerLines()
-      } else if (key.name === "pageup" && items.length) {
-        p.index = Math.max(0, p.index - winH)
-        renderPickerLines()
-      } else if (key.name === "pagedown" && items.length) {
-        p.index = Math.min(items.length - 1, p.index + winH)
-        renderPickerLines()
-      } else if (key.name === "home" && items.length) {
-        p.index = 0
-        renderPickerLines()
-      } else if (key.name === "end" && items.length) {
-        p.index = items.length - 1
-        renderPickerLines()
-      } else if (key.name === "backspace") {
-        if (p.filter) applyFilter(p.filter.slice(0, -1))
-      } else if ((key.name === "return" || key.name === "enter" || str === "\r") && items.length) {
-        popPicker(items[p.index]) // 选中即关闭
-      } else if (str && !key.ctrl && !key.meta) {
-        // 输入即过滤；粘贴的多行文本先去换行（与输入框清洗口径一致），仍含控制字符则整段丢弃
-        const text = str.replace(/[\r\n]+/g, "")
-        if (text && !/[\x00-\x1f\x7f]/.test(text)) applyFilter(p.filter + text)
-      }
-      return
-    }
-
-    // initial config wizard: menu step ↑↓/Enter/Esc; text step Enter submit, Esc cancel, edit keys fall through to normal input
+    // 序 2：模态族（key-handler-modals.mjs）——picker 导航 / 初始配置 wizard
+    if (state.picker) { handlePickerKeys(str, key, ctx); return }
     if (state.wizard) {
+      // 守卫 = wizard 块内返回分支（provider 步恒返回；文本步仅 escape / return / ↑↓ / PgUp·PgDn 返回，
+      // 其余编辑键落空至编辑族 —— 守卫项与 key-handler-modals.mjs 块内返回点逐条对应）
       const w = state.wizard
-      if (key.name === "escape") {
-        cancelWizard()
-        return
-      }
-      if (w.step === "provider") {
-        const items = wizardProviderItems()
-        if (key.name === "up" && items.length) {
-          w.index = (w.index - 1 + items.length) % items.length
-          renderWizard()
-        } else if (key.name === "down" && items.length) {
-          w.index = (w.index + 1) % items.length
-          renderWizard()
-        } else if ((key.name === "return" || key.name === "enter" || str === "\r") && items.length) {
-          wizardChooseProvider(items[w.index])
-        }
-        return
-      }
-      if (key.name === "return") {
-        wizardSubmitText()
+      if (w.step === "provider" || key.name === "escape" || key.name === "return" ||
+          key.name === "up" || key.name === "down" || key.name === "pageup" || key.name === "pagedown") {
+        handleWizardKeys(str, key, ctx)
         return
       }
-      // text steps: block scroll/history, remaining edit keys fall through to normal input logic below
-      if (key.name === "up" || key.name === "down" || key.name === "pageup" || key.name === "pagedown") return
-    }
-
-    // page scroll
-    if (key.name === "pageup") {
-      // At the top of the conversation → load the next earlier history page
-      // (lazy restore, parity with VS Code's scroll-back loadOlder).
-      if (state._hasOlder && loadOlder && state.scroll >= convMaxScroll(state)) {
-        loadOlder()
-      } else {
-        state.scroll += Math.max(1, ((state.dims?.get() ?? {}).rows ?? (process.stdout.rows || 24)) - 8)
-      }
-      state._followTail = false // 2026-08-31：用户上滚 = 暂停流式跟随
-      render()
-      return
-    }
-    if (key.name === "pagedown") {
-      state.scroll = Math.max(0, state.scroll - Math.max(1, ((state.dims?.get() ?? {}).rows ?? (process.stdout.rows || 24)) - 8))
-      if (state.scroll === 0) state._followTail = true // 滚回底部恢复跟随
-      render()
-      return
-    }
-
-    if (state.processing) {
-      // busy 门禁（INPUT-LOCK C'——2026-09-09 + INPUT-LOCK-BEHAVIOR-REVISED——2026-09-09）：
-      // processing（含 digest——单一判据）输入不禁——吞提交不吞字符（打字照常回显）；Enter
-      // 提交吞 + busy 提示——斜杠同禁发（白名单已删——/exit 也发不出——退出靠 Ctrl+C 终端
-      // 层通道——门禁前不误伤）；空 Enter 静默（text 非空才吞）；多行换行
-      // （meta/enter——编辑）照常放行。**第 31 批**：↑↓ 不再在此全屏蔽——分流下沉到下方
-      // 三规则块（竖移放行 / 历史导航禁；TUI-INPUT-BOX.md §3）；Tab 仍吞（死条件在案——原样保留）。
-      if (key.name === "tab") return
-      const isSend = (key.name === "return" && !key.meta) || (str === "\r" && !key.meta)
-      if (isSend && state.input.join("").trim()) {
-        pushLine(`[主会话处理中 —— 消息未发送（回合结束后请重按 Enter）]`, C.warn)
-        render()
-        return
-      }
-    }
-
-    // Tab: slash-command completion (cycle candidates); other input ignored (\t would blow up input box, never inserted directly)
-    if (key.name === "tab") {
-      handleTab()
-      return
-    }
-
-    // Ctrl+U: clear entire input box
-    if ((key.name === "u" && key.ctrl) || str === "\x15") {
-      if (state.historyIndex !== -1) state._draft = [...state.input]
-      state.input = []
-      state.cursor = 0
-      render()
-      return
-    }
-
-    // ↑/↓ 三规则（TUI-INPUT-BOX.md §3——第 31 批）：① 翻历史中恒历史（多行条目不竖移）
-    // ② 竖移优先（可视行口径——折行与 \n 同权；显示列保持 + 短行端钳制）③ 边界回落历史（↑）
-    // ／无动作（↓）。processing 期：竖移放行（纯编辑——与字符/退格/←→ 同权）、历史导航禁
-    // （规则 ①/③ 的历史分支吞——不进入、不切换）。
-    if (key.name === "up" || key.name === "down") {
-      if (state.historyIndex === -1) { // 规则 ① 优先——翻历史中不竖移
-        const cols = (state.dims?.get() ?? {}).cols ?? (process.stdout.columns || 80)
-        const next = moveCursorVertical(state.input, state.cursor, inputContentWidth(cols), key.name)
-        if (next !== null) {
-          state.cursor = next // 规则 ②：竖移（草稿/历史指针零涉——D-31.6）
-          render()
-          return
-        }
-      }
-      if (state.processing) return // 规则 ①/③ 的历史分支吞——processing 期历史导航禁
-    }
-
-    // input history（规则 ① 恒历史 + 规则 ③ 边界回落——历史语义零改）
-    if (key.name === "up") {
-      if (state.history.length) {
-        // Save current input as draft when entering history mode (historyIndex === -1).
-        // Subsequent edits while in history mode are saved separately (see printable/editing handlers).
-        if (state.historyIndex === -1) {
-          state._draft = [...state.input]
-        }
-        state.historyIndex = state.historyIndex === -1 ? state.history.length - 1 : Math.max(0, state.historyIndex - 1)
-        state.input = [...state.history[state.historyIndex]]
-        state.cursor = state.input.length
-        render()
-      }
-      return
-    }
-    if (key.name === "down") {
-      if (state.historyIndex !== -1) {
-        state.historyIndex++
-        if (state.historyIndex >= state.history.length) {
-          state.historyIndex = -1
-          // Restore the stashed draft instead of wiping back to blank
-          state.input = state._draft ? [...state._draft] : []
-          state._draft = null
-        } else {
-          state.input = [...state.history[state.historyIndex]]
-        }
-        state.cursor = state.input.length
-        render()
-      }
-      return
-    }
-
-    // cursor movement
-    if (key.name === "left") {
-      state.cursor = Math.max(0, state.cursor - 1)
-      render()
-      return
-    }
-    if (key.name === "right") {
-      state.cursor = Math.min(state.input.length, state.cursor + 1)
-      render()
-      return
-    }
-    if (key.name === "home") {
-      state.cursor = 0
-      render()
-      return
-    }
-    if (key.name === "end") {
-      state.cursor = state.input.length
-      render()
-      return
-    }
-
-    // editing
-    if (key.name === "backspace") {
-      if (state.cursor > 0) {
-        state.input.splice(state.cursor - 1, 1)
-        state.cursor--
-        if (state.historyIndex !== -1) state._draft = [...state.input]
-        render()
-      }
-      return
-    }
-    if (key.name === "delete") {
-      if (state.cursor < state.input.length) {
-        state.input.splice(state.cursor, 1)
-        if (state.historyIndex !== -1) state._draft = [...state.input]
-        render()
-      }
-      return
-    }
-    if (key.name === "return" || key.name === "enter" || str === "\r") {
-      // Multiline newline (docs/design/TUI-INPUT-BOX.md §1.5): Alt+Enter / Shift+Enter
-      // (translateShiftEnter) / Ctrl+J — the universal no-protocol fallback.
-      if ((key.name === "return" && key.meta) || key.name === "enter") {
-        state.input.splice(state.cursor, 0, "\n")
-        state.cursor++
-        render()
-      } else {
-        const text = state.input.join("").trim()
-        // §17 D-S5/F3/F7 + 偏差 #1 + INPUT-LOCK 单槽化（F-6——2026-09-09）：挂起态
-        // （suspended 或释放窗口 _suspPending）Enter = 新回合输入（非打断）——填
-        // pendingInput 单槽（至多一条待交接——busy 提交吞在 L265 门禁先拦，digest 期
-        // 不会到这——仅挂起空闲/释放窗口触达）由挂起会话调度；输入框零干扰（F3）。
-        // 槽满（竞态防御——不覆盖不丢失）→ 吞 + 提示，文本保留在输入框。
-        if ((state.suspended || state._suspPending) && text && !text.startsWith("/")) {
-          state.pendingInput ??= []
-          if (state.pendingInput.length > 0) {
-            pushLine(`[主会话处理中 —— 已有一条消息待发送，请等其处理完成后再发送]`, C.warn)
-            render()
-            return
-          }
-          state.input = []
-          state.cursor = 0
-          state.history.push(text)
-          state.historyIndex = -1
-          state._draft = null
-          state.pendingInput.push(text)
-          state._suspWake?.()
-          render()
-          return
-        }
-        submit().catch((e) => pushLine(`[error] ${e.message}`, C.error))
-      }
-      return
     }
 
-    // Ctrl+V: paste clipboard text into the active text target.
-    // Exclude meta (ESC-prefix) so Ctrl+Alt+V — which readline reports as ctrl+meta —
-    // falls through to the image-paste branch below instead of being eaten here.
-    if (key.ctrl && !key.alt && !key.meta && key.name === "v") {
-      ;(async () => {
-        const text = await readClipboardText()
-        if (text) {
-          insertPastedText(state, text)
-          render()
-        }
-      })()
-      return
-    }
+    // 序 3：scroll 族（key-handler-scroll.mjs）——PgUp/PgDn 翻页（含 loadOlder 边界加载）/
+    // ↑↓ 三规则 + 历史导航 / ←→·Home·End 光标
+    if (key.name === "pageup" || key.name === "pagedown") { handleScrollKeys(key, ctx); return }
+    if (key.name === "up" || key.name === "down") { handleHistoryKeys(key, ctx); return }
+    if (key.name === "left" || key.name === "right" || key.name === "home" || key.name === "end") { handleCursorKeys(key, ctx); return }
 
-    // Alt+V / Ctrl+Alt+V: paste clipboard image.
-    // NOTE: readline reports ESC-prefixed combos as key.meta, NOT key.alt (probe-verified:
-    // \x1b + char → { meta: true, alt: false }). Checking key.alt alone is a dead branch —
-    // the key fell through to the printable handler which ignores meta keys, so image paste
-    // silently did nothing. Accept meta (and alt, for terminals that set it); the text-paste
-    // branch above excludes meta so Ctrl+Alt+V reaches here.
-    const isPasteImage = key.name === "v" && (key.alt || key.meta)
-    if (isPasteImage) {
-      pasteClipboardImage(agent).catch((e) => pushLine(`[error] ${e.message}`, C.error))
+    // 序 4：busy 门禁（key-handler-busy.mjs）——Enter 单槽受理 + 吞面四 / Tab 吞
+    // （守卫 = busy 块内返回条件：processing 期仅 tab 与无 meta 的 Enter/回车 被吞，余键落空至编辑族）
+    if (state.processing && (key.name === "tab" || ((key.name === "return" && !key.meta) || (str === "\r" && !key.meta)))) {
+      handleBusyEnter(str, key, state, ctx)
       return
     }
 
-    // printable characters / paste (str may contain multiple chars at once); Tab always converted to two spaces (\t has variable display width, would blow up input box)
-    // \r\n may leak through in Windows raw mode and scramble the display
-    if (str && !key.ctrl && !key.meta) {
-      const chars = [...str.replace(/[\r\n]+/g, "").replace(/\t/g, "  ")]
-      state.input.splice(state.cursor, 0, ...chars)
-      state.cursor += chars.length
-      if (state.historyIndex !== -1) state._draft = [...state.input]
-      render()
-    }
+    // 序 5：编辑族（key-handler-edit.mjs）——Tab 补全 / Ctrl+U 清框 / 退格·删除 / Enter 提交 /
+    // 剪贴板文本与图片粘贴 / 可打印字符（末族：其后无可达分支）
+    handleEditKeys(str, key, ctx)
   }
 }

package/src/tui/render-frame.mjs

@@ -395,9 +395,14 @@ function buildStatusLine(state, agent, { cols, slashCommands }) {
   const ctxTokensHint = state.ctxCache.tokens > 0 ? ` ${fmtK(state.ctxCache.tokens)}` : ""
   const ctxHint = ctxPct > 0
     ? ctxPct >= 80 ? ` │ ${ansi.reset}${C.warn}context ${ctxPct}%${ctxTokensHint}${ansi.reset}${ansi.dim}` : ` │ context ${ctxPct}%${ctxTokensHint}` : ""
-  // INPUT-LOCK-ASYNC（C'——F-3）：busy（processing 含 digest）状态栏提示——取代旧
-  // 排队提示（F-7 已删）——“主会话处理中——Enter 提交禁用”
-  const enterHint = state.processing ? `主会话处理中 — Enter 提交禁用（字符可输入，回合结束请重按 Enter）` : "Enter: send"
+  // INPUT-LOCK-ASYNC（C'——F-3）：busy（processing 含 digest）状态栏提示——取代旧排队提示
+  // （F-7 已删）；F16（TUI.md §7.5）三态分流：单槽已填 ⇒ queued 段（dim 段样式 · 零注意力色对
+  // ——F13 豁免 · 消费即消失）；槽空 ⇒ 按 busy 面分排队句（判据同 TUI-INPUT-BOX.md §4.1）。
+  const enterHint = state.processing
+    ? ((state.pendingInput?.length ?? 0) > 0 ? "已排队 1 条消息"
+      : state.suspended || state._suspPending ? `会话内回合处理中 — Enter 排队（本轮结束后优先发送）`
+        : `主会话处理中 — Enter 排队（回合结束后自动发送）`)
+    : "Enter: send"
   // LEDGER-SURFACE（§2.30.3.3/§2.30.3.4）：L1 常驻标记——状态段簇尾（scrollHint 后、键位组前）；
   // 空标记零注入（半态逐字节等价——同 :233-238 纪律）；warn = 当前项目老化 > 0（警示色段包裹）
   const lg = state.ledger

package/src/tui/subagent-freeze.mjs

@@ -224,13 +224,13 @@ export function freezeAllSubTasks(state) {
   }
 }
 
-/** §17.5.5 消化完成逐条冻结回收（2026-09-03 实测修订 + round1 #1 位置裁定）：digest/会话内
+/** 消化完成逐条冻结回收（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 总览文本之前**——同
+ *  快照即精确归属。位置（round1 #1 裁定——与早版文本的矛盾已消解；digest 面 =
+ *  AGENT-LOOP-ASYNC-POOL.md §6.8）：**settle 锚点 splice 落位——digest 总览文本之前**——同
  *  §7.2 D4 修复轮/D-S8 锚点语义（T-S6/T-S14 位置断言同口径）——锚点降序逐块冻结
  *  （splice 绝对位互不位移）。@returns {number} 回收块数 */
 export function freezeReclaimDigestedBlocks(state, pendingList) {

package/src/tui/suspension-drive.mjs

@@ -6,10 +6,10 @@
  *
  * §17（2026-09-02，AGENT-LOOP.md §9 D-S1..S9）：回合尾后台池非空 → 不阻塞等待，
  * 进入挂起态——挂起空闲输入开放（Enter = 新回合填单槽 + 唤醒）、busy（processing 含
- * digest）输入禁用（INPUT-LOCK-ASYNC C'——提交吞——2026-09-09）、settle 事件驱动
+ * digest）提交亦入同槽（busy-extend 批 2026-09-22——`TUI-INPUT-BOX.md` §4.1）、settle 事件驱动
  * auto-turn 消化（手动档 organize-only / AUTO 档全语义）、池空 + 无待处理输入 → 补发
  * done 冻结自然退出。状态机行表见 AGENT-LOOP.md §9.2。
- * F-UC7（2026-09-19 批，AGENT-LOOP-SUBAGENT.md §6.27.12）：第二开轮源 = 未 drain 的上行
+ * F-UC7（2026-09-19 批，AGENT-LOOP-UPSTREAM.md §6.27.12）：第二开轮源 = 未 drain 的上行
  * ask（`upstreamWaiting` 谓词——ask 入队即唤醒本驱动）；唤醒轮同走 auto-turn（旗标
  * `upstreamTurn` 供核域文本选择）。
  * F-UC8（2026-09-21 批，§6.27.12.13）：可见提示面**按因两档**（ask 携「谁 + 啥」——
@@ -25,17 +25,17 @@ import { logEvent } from "@thincoder/core/log.mjs"
 import { C } from "./ansi.mjs"
 // ASYNC-RESULT-CONTAINER.md D1/D2：池 accessor（双池 absorb）+ pending 单容器停靠
 import { getAsyncPool, parkAsyncPending, releaseSettledEntry } from "@thincoder/core/agent-tools/async-settle.mjs"
-// F-UC7（AGENT-LOOP-SUBAGENT.md §6.27.12——2026-09-19 批）：上行 ask 开轮谓词单点（核导出）
+// F-UC7（AGENT-LOOP-UPSTREAM.md §6.27.12——2026-09-19 批）：上行 ask 开轮谓词单点（核导出）
 // F-UC8（§6.27.12.13 ②——2026-09-21 批）：ask 提示行携参单点（同档导出——显示面单源）
 import { upstreamAskLabelVars, upstreamWaiting } from "@thincoder/core/agent-tools/parent-channel.mjs"
 // X9（2026-09-20 端差·显示面消差批）：消化收尾文案单源 = 核 i18n 容器（禁第三份字面）
 import { t } from "@thincoder/core/i18n.mjs"
-// 批 4 CLI-ASYNC-DISCARD（AGENT-LOOP-SUBAGENT.md §6.20）：中止分支「只清已死」收尾单点
+// 批 4 CLI-ASYNC-DISCARD（AGENT-LOOP-ASYNC-POOL.md §6.20）：中止分支「只清已死」收尾单点
 import { discardAbortedPool, discardAbortedAdvisors } from "@thincoder/core/agent-tools/async-discard.mjs"
 
 // INPUT-LOCK-ASYNC（C'——2026-09-09，本档 INPUT-LOCK-ASYNC.md）：R15 排队
 // 用户指令合并（§11.3 D-24c——攒批计划/合并文案/上限常量）整批废弃
-// ——busy 提交吞 + pendingInput 单槽化（至多一条待交接——单消息逐发不攒批）。
+// ——pendingInput 单槽化（至多一条待交接——单消息逐发不攒批；busy 提交入槽 = busy-extend 批 2026-09-22 扩面）。
 
 /** 后台池计数（LOGGING susp/digest 事件字段——pendingN/poolN）。
  *  poolN = _asyncSubagents + _asyncAdvisors（§11.2 D-24b advisor 池同面板计数——queued
@@ -80,7 +80,7 @@ export function allPendingEntries(agent) {
   return [...(agent?._pendingAsyncResults ?? [])]
 }
 
-// ─── §17 挂起会话（AGENT-LOOP.md §17 D-S2/D-S9 状态机行表）────────────────
+// ─── 挂起会话（AGENT-LOOP-ASYNC-POOL.md §6.8 D-S2/D-S9 状态机行表）────────────────
 
 /** 后台池存活判据（D-S2/F5 口径）：running/queued 子代理或后台评审，或已 settle 未注入结果
  *  （pending 单容器非空 = D-S3 "未注入"），或 running consult 会话（会诊跨回合——
@@ -205,7 +205,7 @@ async function digestTurn(ctx, upstream = false) {
  * §17 挂起会话驱动（D-S9 行表；由 runAgentTurn 回合尾进入，池空自然退出）：
  * - suspension：池项 settle → 入 pending → 开 auto-turn（合并消化近邻 settle）；
  *   上行 ask 入队 → 唤醒 + 谓词 → 开唤醒轮（F-UC7——谓词先于池空退出判，见第 2 步）；
- *   挂起空闲用户 Enter → pendingInput 单槽（busy 含 digest 提交吞——INPUT-LOCK-ASYNC）
+ *   挂起空闲用户 Enter、会话内 busy Enter → pendingInput 单槽（busy-extend 2026-09-22 同判据）
  *   ——用户输入优先于 digest；
  * - auto-turn：消化中 settle 不并发开新轮（单 runAgent 循环），轮末按 pending/池态
  *   续开合并消化轮或回挂起；pendingInput 非空 → 以该消息开新回合（不触发新 digest）；
@@ -240,11 +240,12 @@ export async function suspensionSession(ctx) {
     while (!state._suspAborted && !agent._sessionAbort.signal.aborted) {
       sweepSettledToPending(agent)
       // 1. 用户输入优先（D-S5）：pendingInput 单槽（INPUT-LOCK-ASYNC C'——busy（processing
-      //    含 digest）提交吞——Enter 只可能落在挂起空闲/释放窗口——至多一条待交接——driver
+      //    含 digest）提交亦入本槽——TUI-INPUT-BOX.md §4.1；至多一条待交接——driver
       //    消费清槽即开新回合）。R15 攒批/queue 双源已随排队机制废弃收敛（2026-09-09——
       //    单消息交接——无合并无 /cmd 分流——key-handler 只收非斜杠文本——单消息逐发）。
       if ((state.pendingInput?.length ?? 0) > 0) {
         const head = String(state.pendingInput.shift())
+        pushLine("[sending queued message]", C.tool) // F16 消费回执（TUI.md §7.5——driver 消费点）
         agent._suspended = false // 用户回合 = 普通回合语义（① 直注入 + settle 即冻结）
         await runAgentTurn(ctx, head, { skipSession: true })
         agent._suspended = true
@@ -290,7 +291,7 @@ export async function suspensionSession(ctx) {
     state._suspWake = null
     state.suspAbortArmed = false // round2 偏差 #4：会话退出即解除挂起中止武装（防跨会话粘滞）
     if (aborted) {
-      // §15 abort 语义：只清已死条目（AGENT-LOOP-SUBAGENT.md §6.20——墓碑/出池/队列剔除/
+      // §15 abort 语义：只清已死条目（AGENT-LOOP-ASYNC-POOL.md §6.20——墓碑/出池/队列剔除/
       // 整批一次提醒；存活与已 settle 者留池消化——不注入陈旧错误）。
       discardAbortedPool(agent)
       discardAbortedAdvisors(agent)

package/src/tui/tui-state.mjs

@@ -0,0 +1,65 @@
+import { makeDimsState } from "./dims.mjs"
+
+/** TUI state 工厂（2026-09-22 structure-debt §2.2 · #159）：state 字面量自 index.mjs startTUI
+ *  逐字搬移（仅去包裹）；`dims` 种子以调用侧采样值入参（Cols/Rows 名保持字面量原样），
+ *  `tasks` 由 agent 承接（`agent.tasks ?? []` 原地保留）。
+ *  @param {{ cols: number, rows: number, agent: object }} deps
+ *  @returns {object} TUI state（会话面字段 / dims 单源 / 面板回指位） */
+export function createTuiState({ cols, rows, agent }) {
+  // 名字桥：字面量内沿用调用侧采样名（逐字搬移所需）
+  const startupCols = cols
+  const startupRows = rows
+  return {
+    lines: [], // conversation lines: { text, color }
+    streaming: "", // current streaming buffer
+    _advisorBlocks: [], // advisor ordered blocks: [{ kind: "think"|"text", text }] — preserves emission order (think ↔ tool interleaving)
+    input: [], // input buffer (codepoint array)
+    cursor: 0,
+    history: [],
+    historyIndex: -1,
+    _draft: null, // stashed unsent input while navigating history (restored on down past newest)
+    scroll: 0, // scroll lines from bottom upward
+    _foldScroll: new Map(), // 2026-08-31 块内滚动：foldKey → 窗口 offset（展开块 ▲▼ 翻窗）
+    _followTail: true, // 2026-08-31 流式跟随：渲染前 scroll=0；用户上滚暂停、到底/新消息恢复
+    processing: false,
+    controller: null, // AbortController for current agent run
+    permission: null, // { name, args, resolve }
+    permissionPreview: [], // content preview lines for permission approval (rendered above input box, without separation)
+    question: null, // { text, options, resolve } — agent question tool callback
+    picker: null, // active picker (stack top) { title, entries, lines, index, scroll, selectedLine, filter }
+    pickerStack: [], // picker 栈：showPicker push，Enter/Esc pop；state.picker 始终指向栈顶
+    pendingNotice: null, // 后台更新提示：有 picker 打开时挂起，picker 全部关闭后再弹
+    wizard: null, // first-launch config wizard { step, index, scroll, selectedLine, fields, error, lines }
+    tasks: agent.tasks ?? [], // task list from task tool (progress shown in status bar); carried over on session restore, auto-collapsed when all done
+    dims: makeDimsState({ cols: startupCols, rows: startupRows }), // terminal dims single source (Windows ConPTY instability, 2026-08-30) — seeded pre-raw-mode, re-sampled by event hooks only (startup retry / resize / idle watchdog)
+    tokens: { prompt: 0, completion: 0, cacheHit: 0, cacheMiss: 0, reasoningTokens: 0 }, // cumulative token usage (shown in status bar)
+    ctxCache: { len: -1, tokens: 0 }, // context utilization estimate cache (estimateTokens is O(n), only recompute when history grows)
+    reasoning: "", // thinking stream buffer (dimmed display)
+    completion: null, // Tab completion state { candidates, index }
+
+    subTasks: {}, // sub-agent activity blocks (§7.2 D4): { "coder#1": { key, role, model, started, done, doneAt, blocks: [{kind,text}], currentTool, toolArgs, turn, maxTurns, approval, lastError, dropped, blockEpoch, awaitingDigest（§17 挂起中间态）, _freezeAt（冻结锚点）, stopped, children: []（SUBAGENT-TAIL：嵌套子代理**守护载体**——内容行并入本块 blocks——subagent-children.mjs） } } — rendered as collapsible in-conversation blocks; persists across turns (blocks are the child activity's ONLY carrier — child tool calls never enter the parent history); bounded by the N2 500-line per-child ring buffer（SUBAGENT-TAIL 单环：内层行同环计数、单载体最旧先行——TUI.md §6）
+    currentTool: null, // currently executing tool name (shown in status bar)
+    processingStarted: 0, // current turn start time (status bar timer)
+    status: "Ready",
+    ledger: { marker: null, warn: false, scannedAt: 0 }, // LEDGER-SURFACE（§2.30.3.4）：L1 标记位——ledger-surface 写 / render-frame 读
+    queue: [], // 交接残项单容器 [{ text }]（INPUT-LOCK：submit 不再排队——仅释放窗口兜底/挂起中止残余——回合尾队列循环续发，至多一条）
+    interruptPrompt: null, // Ctrl+I inject box（第 31 批——TUI-INPUT-BOX.md §8）: { chars: string[], cursor: number } or null
+    attentionAwaiting: false, // 第 33 批（TUI §14.3(f)）：回合结束等待输入——链尾置位 / 用户输入清位；不落盘、不进会话
+    search: null, // Ctrl+F search mode: { query: "", matches: [{lineIndex, charIndex}], index: 0 } or null
+    expandedBlocks: new Set(), // block hashes that are expanded (Enter toggles)
+    foldEnabled: true, // global fold toggle — /fold on|off
+    exitArmed: false, // Ctrl+C double-confirm: first press arms, second (within window) exits
+    // Lazy history window (parity with VS Code): only the latest messages are
+    // materialized on restore; PgUp-at-top loads earlier pages via loadOlder.
+    _historyLoaded: 0, // messages loaded from the TAIL of _fullHistory
+    _historyTotal: 0, // total messages in the restored session
+    _hasOlder: false, // more earlier messages remain unloaded
+    _linesChars: 0, // TUI-OOM-ROOTCAUSE（§15.3.2）：state.lines 全部行与载体文本总量（字符账——唯一新增状态位）
+    _agent: null, // TUI state → agent 回指挂载点：startTUI 装配时置 agent 引用——
+    // ① SYNC-CANCEL ⏹ 门控读 state._agent._syncChildAborts（subagent-panel.mjs，2026-09-09）；
+    // ② CLI-ACTIVITY-DEBLOAT F-3（2026-09-10）：agent._tuiState = state 反向挂载——
+    // action:"panel" 经 ctx.state（= agent._tuiState）**读时现算**面板块（computePanelBlocks
+    // ——subTasks 活值纯推导——单账本）。headless/VS Code 无此装配 = 无面板 → panel 动作
+    // 恒降级池视图（CLI-only 完整能力——AC-P4）。
+  }
+}