thincoder 0.12.64 → 0.12.66

package/src/tui/input-face.mjs

@@ -0,0 +1,187 @@
+import { PassThrough } from "node:stream"
+import { readFileSync } from "node:fs"
+import { emitKeypressEvents } from "node:readline"
+import { C } from "./ansi.mjs"
+import { insertPastedText, translateShiftEnter, stripKeyboardProtocol } from "./clipboard.mjs"
+import { parseMouseClicks, handleWheel, createMouseDispatch, mouseOob } from "./mouse.mjs"
+import { createKeyHandler, convMaxScroll, clearAttention } from "./key-handler.mjs"
+import { writeStartupSequence, writeLoadingLine, setTuiActive } from "./tui-lifecycle.mjs"
+
+/** 输入面（2026-09-22 structure-debt §2.2 · #159）——**二段接口**：
+ *  ① 早挂载工厂（本函数体 = 输入流 / raw mode / 启动序列 / 解码器 + stdin data 处理器整块）；
+ *  ② 后置挂载入口 `mountKeys(deps)` / `mountMouse(deps)`——构造期读值面（createKeyHandler 构造时
+ *  一次解构 ctx / createMouseDispatch 参数解构），须在原址（键盘 :455 · 鼠标 :473）调用，
+ *  此时 18 + 5 键全已初始化；早挂载 ctx 以惰性取值器承接 render / pushLine / loadOlder
+ *  （晚定义名——TDZ 语义逐字保持）。
+ *  @param {{ state: object, render: Function, pushLine: Function, loadOlder: Function }} ctx
+ *  @returns {{ keyStream: object, mountKeys: Function, mountMouse: Function }} */
+export function createInputFace(ctx) {
+  const { state } = ctx
+  // 晚定义名转发（render / pushLine / loadOlder 于 startTUI 后段方初始化——调用点在事件回调内）
+  const render = (...a) => ctx.render(...a)
+  const pushLine = (...a) => ctx.pushLine(...a)
+  const loadOlder = (...a) => ctx.loadOlder(...a)
+  // 后置槽：鼠标两路（mountMouse 回填；挂载前 undefined = 原址 TDZ 语义——② 的调用点保持在 try 内）
+  let mouseCtx
+  let onMouseClick
+  // Input stream goes through a filter: mouse sequences (scroll wheel) are intercepted and handled here,
+  // stripped clean before passing to keypress parsing, preventing sequence fragments (e.g. "64;72;42M")
+  // from leaking into the input box
+  const keyStream = new PassThrough()
+  let mousePending = "" // incomplete mouse sequence tail spanning chunks
+  let lastRenderedScroll = 0
+  emitKeypressEvents(keyStream)
+  process.stdin.setRawMode(true)
+  // Keyboard enhancement — enable BOTH protocols (unsupported terminals ignore them):
+  // kitty push (\x1b[>1u): Shift+Enter → \x1b[13;2u (Windows Terminal 1.19+, VS Code, kitty, iTerm2)
+  // modifyOtherKeys lvl 2 (\x1b[>4;2m): Shift+Enter → \x1b[27;2;13~ (mintty / Git Bash)
+  // translateShiftEnter (stdin layer) maps both to \x1b\r → meta+return → multiline branch.
+  writeStartupSequence()
+  // 启动加载画面（2026-09-21 用户）：冷启动剩余期（memory 同步 / 索引扫描）非黑。
+  // 静态读（render-frame 先例——module-load 一次 ✗ 首帧 render 覆盖本行 ✗ 无需清除逻辑）。
+  {
+    let v = ""
+    try { v = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")).version } catch { /* 尽力面 */ }
+    writeLoadingLine(undefined, v)
+  }
+  setTuiActive(true) // R25（F-R25a）：终端接管完成——置 TUI 活动态（崩溃钩子恢复判定源）
+
+  const utf8Decoder = new TextDecoder("utf-8", { fatal: false })
+
+  let pasteMode = false
+  let pasteAccum = ""
+
+  process.stdin.on("data", (chunk) => {
+    try {
+
+      let text = mousePending + utf8Decoder.decode(chunk, { stream: true })
+      mousePending = ""
+
+    // 第 33 批（TUI §14.3(e) 鼠标点）：stdin 数据到达即用户在场 ⇒ 清 attention 位
+    // （单点覆盖下方滚轮分支与 onMouseClick；键盘入口在 key-handler）。
+    clearAttention(state, render)
+
+    // Bracketed paste: terminal wraps pasted text in \x1b[200~ ... \x1b[201~
+    // Route pasted content to the active text target (question answer / input box) in one shot,
+    // avoiding slow char-by-char keypress render — see insertPastedText in clipboard.mjs
+    if (pasteMode) {
+      const endIdx = text.indexOf("\x1b[201~")
+      if (endIdx >= 0) {
+        pasteAccum += text.slice(0, endIdx)
+        pasteMode = false
+        const pasted = pasteAccum
+        pasteAccum = ""
+        if (pasted) {
+          insertPastedText(state, pasted)
+          render()
+        }
+        text = text.slice(endIdx + 6)
+      } else {
+        pasteAccum += text
+        return
+      }
+    }
+
+    // Check for paste start (may appear mid-chunk alongside other input)
+    const pasteStartIdx = text.indexOf("\x1b[200~")
+    if (pasteStartIdx >= 0) {
+      const before = text.slice(0, pasteStartIdx)
+      const after = text.slice(pasteStartIdx + 6)
+      const endIdx = after.indexOf("\x1b[201~")
+      if (endIdx >= 0) {
+        // Paste begin and end in the same chunk: insert pasted content directly
+        const pasted = after.slice(0, endIdx)
+        if (pasted) {
+          insertPastedText(state, pasted)
+          render()
+        }
+        text = before + after.slice(endIdx + 6)
+      } else {
+        // Paste spans multiple chunks: write prefix, enter paste mode
+        if (before) keyStream.write(before)
+        pasteMode = true
+        pasteAccum = after
+        return
+      }
+    }
+
+    // Scroll wheel: \x1b[<64;col;rowM = up, \x1b[<65;col;rowM = down（3 lines each）
+    // 2026-08-31：坐标命中展开块内容行 → 块内滚动（handleWheel）；未命中 → 会话滚动（现状）
+    for (const m of text.matchAll(/\x1b\[<(\d+);(\d+);(\d+)([Mm])/g)) {
+      const button = Number(m[1])
+      if (button === 64 || button === 65) {
+        // F-3 sane-gate ③（RESIZE-MOUSE-LEAK-FIX）：越界 wheel 禁止会话滚动——handleWheel
+        // 对越界返回未消费会穿到 fallback 滚动（mouse.mjs 内 gate 覆盖不到此路径）
+        const dims = state.dims ? state.dims.get() : { cols: process.stdout.columns || 80, rows: process.stdout.rows || 24 }
+        if (mouseOob(Number(m[2]), Number(m[3]), dims)) continue
+        const consumed = handleWheel(mouseCtx(), button, Number(m[2]), Number(m[3]))
+        if (!consumed) {
+          if (button === 64) {
+            state.scroll += 3
+            state._followTail = false // 2026-08-31：用户上滚 = 暂停流式跟随（不抢视角）
+            // 2026-08-31 用户约定修复：滚动到头自动加载（原来只挂 PgUp 键——违约）
+            if (state._hasOlder && state.scroll >= convMaxScroll(state)) loadOlder()
+          } else {
+            state.scroll = Math.max(0, state.scroll - 3)
+            if (state.scroll === 0) state._followTail = true // 滚回底部恢复跟随
+          }
+        }
+      }
+    }
+
+    // Left-click: \x1b[<0;col;rowM → picker selection / line action menu
+    for (const click of parseMouseClicks(text)) {
+      try {
+        onMouseClick(click.col, click.row)
+      } catch (e) {
+        pushLine(`[mouse] ${e.message || e}`, C.error)
+        render()
+      }
+    }
+
+    // Strip complete mouse sequences; keep incomplete tail for reassembly with next chunk
+    text = text.replace(/\x1b\[<\d+;\d+;\d+[Mm]/g, "")
+    const tail = text.match(/\x1b\[<[\d;]*$/)
+    if (tail) {
+      mousePending = tail[0]
+      text = text.slice(0, -tail[0].length)
+    }
+
+    // Shift+Enter (keyboard-enhanced terminals) → Alt+Enter path (\x1b\r = meta+return)
+    text = translateShiftEnter(text)
+    text = stripKeyboardProtocol(text)
+
+    if (state.scroll !== lastRenderedScroll) {
+      lastRenderedScroll = state.scroll
+      render()
+    }
+    if (text) keyStream.write(text)
+    } catch (e) {
+      pushLine(`[input-error] ${e.message || e}`, C.error)
+    }
+  })
+
+  // 后置挂载入口③：键盘接线（原址 :455——18 键 deps 由调用侧按原样构造）
+  function mountKeys(deps) {
+    // keypress is attached to filtered keyStream: mouse sequences already intercepted and stripped upstream
+    const onKeypress = createKeyHandler(deps)
+    keyStream.on("keypress", (str, key) => {
+      try {
+        onKeypress(str, key)
+      } catch (e) {
+        pushLine(`[input-error] ${e.message || e}`, C.error)
+        render()
+      }
+    })
+  }
+
+  // 后置挂载入口④：鼠标 dispatch（原址 :473——5 键 deps）
+  function mountMouse(deps) {
+    // 鼠标点击/滚轮 ctx 装配（mouse.mjs createMouseDispatch——D-S1a：cancelSubagent/onMouseClick/mouseCtx）
+    const dispatch = createMouseDispatch(deps)
+    mouseCtx = dispatch.mouseCtx
+    onMouseClick = dispatch.onMouseClick
+  }
+
+  return { keyStream, mountKeys, mountMouse }
+}

package/src/tui/key-handler-busy.mjs

@@ -0,0 +1,42 @@
+import { C } from "./ansi.mjs"
+
+/** busy 门禁（2026-09-22 structure-debt §2.1 分族 4 · #226）：processing（含 digest）期
+ *  Enter 单槽受理 + 吞面四（模态 / 斜杠 / 空 / 槽满）+ 槽满提示 + 挂起面唤醒，Tab 恒吞；
+ *  块体自 key-handler.mjs createKeyHandler 逐字搬移（仅去缩进；函数体自持原块入口判定）。
+ *  路由 = 分派器 createKeyHandler（守卫 = busy 块内返回条件：tab / 无 meta 的 Enter、回车）。 */
+export function handleBusyEnter(str, key, state, ctx) {
+  const { pushLine, render } = ctx
+  if (state.processing) {
+    // busy 门禁（INPUT-LOCK C'——2026-09-09 + F16 busy 单槽注入——2026-09-21 · busy-extend
+    // 扩面 2026-09-22）：processing（含 digest——单一判据）输入不禁——打字照常回显；Enter
+    // 提交 = 单槽注入（放行判据五条 = TUI-INPUT-BOX.md §4.1：非模态 · 非斜杠 · 非空 · 槽空
+    // ⇒ 清框入 pendingInput——回合尾 drain / 挂起 driver 送达；挂起两态不再是吞面）；
+    // 吞面四 = 模态 / 斜杠 / 空 / 槽满（吞 + 提示，文本保留；斜杠同禁发——白名单已删）；
+    // 多行换行（meta/enter——编辑）照常放行；Tab 仍吞。**第 31 批**：↑↓ 分流见下方三规则块。
+    if (key.name === "tab") return
+    if ((key.name === "return" && !key.meta) || (str === "\r" && !key.meta)) {
+      const text = state.input.join("").trim()
+      if (!text) return // 条件 4：空 Enter 静默（既有）
+      state.pendingInput ??= []
+      // 条件 2/3 不满足（模态 / 斜杠——模态分派在前，此处按判据表如实守卫）→ 吞 + busy 提示
+      if (text.startsWith("/") || state.permission || state.question) {
+        pushLine(`[主会话处理中 —— 消息未发送（回合结束后请重按 Enter）]`, C.warn)
+        render(); return
+      }
+      // 条件 5：单槽满 = 拒绝 + 提示 + 文本保留（二次提交裁定——与挂起态槽满分支逐字同构）
+      if (state.pendingInput.length > 0) {
+        pushLine(`[主会话处理中 —— 已有一条消息待发送，请等其处理完成后再发送]`, C.warn)
+        render(); return
+      }
+      // 入槽（判据全满足）：清框 + history 收录 + 草稿复位 + 单槽填充（§4.1 执行序）
+      state.input = []; state.cursor = 0
+      state.history.push(text)
+      state.historyIndex = -1
+      state._draft = null
+      state.pendingInput.push(text)
+      // 挂起面入槽同款唤醒（§4.1）——busy 期该槽恒 null ⇒ 零动作；普通 busy 面零唤醒
+      if (state.suspended || state._suspPending) state._suspWake?.()
+      render(); return
+    }
+  }
+}

package/src/tui/key-handler-ctrlc.mjs

@@ -0,0 +1,118 @@
+import { C } from "./ansi.mjs"
+// F-XR1 退出释放（EXIT-CLAIM-RELEASE · SESSION.md §6.18 D-SE41）：核薄函数——退出恒达
+// （永不抛出，失败返回 false）；零触碰 marker 面（F-XR2 路标保留）。
+import { releaseClaimsAll } from "@thincoder/core/session-slots-manifest.mjs"
+
+/** Ctrl+C 族（2026-09-22 structure-debt §2.1 分族 1 · #226）：picker 取消 / 武装窗口全停 /
+ *  挂起态两级中止 / 回合 interrupt / 空闲退出武装五分支——块体自 key-handler.mjs
+ *  createKeyHandler 逐字搬移（仅去缩进；函数体自持原块入口判定）。
+ *  路由 = 分派器 createKeyHandler（守卫 = 同一条原块入口条件）。 */
+export function handleCtrlCFamily(str, key, ctx) {
+  const { agent, state, render, popPicker, pushLine, cleanup } = ctx
+  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()
+    // F-XR1 退出释放（EXIT-CLAIM-RELEASE · SESSION.md §6.18）：先于定时器注册同步完成
+    // （D-SE42——100ms 窗零竞态）；退出前保存已完成 ⇒ 释放 = 收口前最后一步。
+    releaseClaimsAll(process.cwd())
+    // 延迟退出可注入（测试传大值并清理定时器，避免定时器在 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
+  }
+}

package/src/tui/key-handler-edit.mjs

@@ -0,0 +1,115 @@
+import { C } from "./ansi.mjs"
+import { readClipboardText, insertPastedText } from "./clipboard.mjs"
+
+/** 编辑族（2026-09-22 structure-debt §2.1 分族 5 · #226）：Tab 补全 / Ctrl+U 清框 /
+ *  退格·删除 / Enter（多行换行 · 挂起单槽 · submit）/ 剪贴板文本与图片粘贴 / 可打印字符；
+ *  各块自 key-handler.mjs createKeyHandler 逐字搬移（仅去缩进）。
+ *  路由 = 分派器 createKeyHandler 末族（其后无可达分支 —— 块内 return 即终结本次按键）。 */
+export function handleEditKeys(str, key, ctx) {
+  const { agent, state, render, handleTab, submit, pasteClipboardImage, pushLine } = ctx
+  // 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
+  }
+
+  // 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（含 digest）
+      // 提交经 busy 门禁入同槽（F16 §4.1——两分支同槽、同款清理与唤醒）；输入框零干扰（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
+  }
+
+  // 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))
+    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()
+  }
+}

package/src/tui/key-handler-modals.mjs

@@ -0,0 +1,87 @@
+import { computeLayout } from "./layout.mjs"
+
+/** 模态族之一（2026-09-22 structure-debt §2.1 分族 2 · #226）：通用列表 picker——
+ *  ↑↓/PgUp/PgDn/Home/End 导航 + 输入即过滤 + Enter 选中 + Esc 取消；块体自 key-handler.mjs
+ *  createKeyHandler 逐字搬移（仅去缩进；函数体自持原块入口判定）。
+ *  路由 = 分派器 createKeyHandler（守卫 = 同一条原块入口条件 `state.picker`）。 */
+export function handlePickerKeys(str, key, ctx) {
+  const { state, renderPickerLines, popPicker } = ctx
+  // 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
+  }
+}
+
+/** 模态族之二（分族 2 · #226）：初始配置 wizard——menu step ↑↓/Enter/Esc；text step Enter 提交 /
+ *  Esc 取消，其余编辑键回落至编辑族（落空面由分派器守卫与块内返回点共同界定）。
+ *  路由 = 分派器 createKeyHandler。 */
+export function handleWizardKeys(str, key, ctx) {
+  const { state, renderWizard, cancelWizard, wizardProviderItems, wizardChooseProvider, wizardSubmitText } = ctx
+  // initial config wizard: menu step ↑↓/Enter/Esc; text step Enter submit, Esc cancel, edit keys fall through to normal input
+  if (state.wizard) {
+    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()
+      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
+  }
+}

package/src/tui/key-handler-scroll.mjs

@@ -0,0 +1,110 @@
+import { inputContentWidth } from "./layout.mjs"
+import { moveCursorVertical } from "./render.mjs"
+import { convMaxScroll } from "./key-handler.mjs"
+
+/** scroll 族之一（2026-09-22 structure-debt §2.1 分族 3 · #226）：PgUp/PgDn 翻页 + 顶部
+ *  loadOlder 边界加载；块体自 key-handler.mjs createKeyHandler 逐字搬移（仅去缩进）。
+ *  路由 = 分派器 createKeyHandler（守卫 = 原块入口条件 pageup/pagedown）。 */
+export function handleScrollKeys(key, ctx) {
+  const { state, render, loadOlder } = ctx
+  // 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
+  }
+}
+
+/** scroll 族之二（分族 3 · #226）：↑↓ 三规则（TUI-INPUT-BOX.md §3）+ 输入历史导航；
+ *  块体逐字搬移（仅去缩进）。路由 = 分派器（守卫 = up/down）。 */
+export function handleHistoryKeys(key, ctx) {
+  const { state, render } = ctx
+  // ↑/↓ 三规则（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
+  }
+}
+
+/** scroll 族之三（分族 3 · #226）：←→/Home/End 光标移动；块体逐字搬移（仅去缩进）。
+ *  路由 = 分派器（守卫 = left/right/home/end）。 */
+export function handleCursorKeys(key, ctx) {
+  const { state, render } = ctx
+  // 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
+  }
+}