minimal-agent 0.10.0 → 0.12.0

package/src/ui/hooks/useChat.ts

@@ -0,0 +1,1578 @@
+/**
+ * ============================================================
+ *  src/ui/hooks/useChat.ts —— 把 loop.runQuery 桥接到 React 状态
+ * ------------------------------------------------------------
+ *  这个 hook 是 UI 层的核心：
+ *    - 维护 history 数组（用 ref 持久引用，version 计数器触发重渲染）
+ *    - 维护"当前正在打字"的 streamingText
+ *    - 维护"工作过程显示"用的 progressStage / reasoningPreview / runningTools
+ *    - 暴露 submit() 给 InputBox 调用、abort() 给 Ctrl+C 处理
+ *
+ *  为什么 history 用 ref 而不是 state？
+ *    runQuery 内部会 mutate history 数组（push 新消息、压缩时清空重建），
+ *    React state 的"不可变更新"规则不适合。用 ref 持有可变引用，
+ *    用 version 计数器驱动 setState 触发 re-render 是更顺手的写法。
+ * ============================================================
+ */
+
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { stat } from 'node:fs/promises';
+
+import { getWorkingDir, setWorkingDir } from '../../bootstrap/workingDir.js';
+import { forceCompact } from '../../context/compact.js';
+import {
+  clearContext,
+  loadContext,
+  saveContext,
+} from '../../context/persistContext.js';
+import { resetReactiveCompactState } from '../../context/reactiveCompact.js';
+import { acquireContextLock } from '../../context/contextLock.js';
+import { workspaceIndexService } from '../../context/workspaceIndex.js';
+import {
+  getActiveSession,
+  setActiveSession,
+  updateSessionMetadata,
+} from '../../context/sessionRegistry.js';
+import {
+  resolveSessionFile,
+  sessionFileFor,
+} from '../../context/sessionPath.js';
+import { runQuery } from '../../loop.js';
+import { buildBaseSystemPrompt, buildTransientPromptBundle } from '../../prompts/system.js';
+import { createPromptCacheContext } from '../../llm/promptCache.js';
+import {
+  createAgentRuntimeContext,
+  filterToolsForRuntime,
+  memoryContextFromRuntime,
+} from '../../runtime/agentRuntimeContext.js';
+import { startTurnJournal, type TurnJournal } from '../../memory/turnJournal.js';
+import { ALL_TOOLS, getToolByName } from '../../tools/index.js';
+import { createInputQueue } from '../../messageQueue.js';
+import {
+  createAskCoordinator,
+  setAskHandler,
+  type AskAnswer,
+  type AskQuestionSpec,
+  type AskSource,
+} from '../../askBridge.js';
+import { createAskSlot } from './askSlot.js';
+import { figures } from '../figures.js';
+import { clearFileState } from '../../tools/shared/fileState.js';
+import { getOrCreateSessionState, sessionStateKey } from '../../session/sessionState.js';
+import { hydrateSessionWorktree } from '../../tools/worktree/sessionWorktree.js';
+import type {
+  LoopEvent,
+  Message,
+  ProgressStage,
+  Provider,
+  ToolResult,
+  ToolStatusState,
+} from '../../types.js';
+import { runAdvisor } from '../../tools/advisor/advisor.js';
+import type { PluginEvent } from '../../plugins/pluginApi.js';
+import { runWithPlugins } from '../../plugins/pluginRunner.js';
+import { dlog } from '../../utils/debugLog.js';
+import type { ComputerUseCliMode } from '../../cli/computerUse.js';
+import { createCliComputerRun, createComputerUseHostGate } from '../../cli/computerUse.js';
+import {
+  computerUseService,
+} from '../../tools/computeruse/computerUseService.js';
+import {
+  HumanInterventionCoordinator,
+  type PendingHumanIntervention,
+} from '../../humanIntervention.js';
+import { createComputerInterventionAdapter } from '../../tools/computeruse/intervention.js';
+import type {
+  ComputerUseRunContext,
+} from '../../tools/computeruse/protocol.js';
+
+export interface PluginProgressState {
+  pluginId: string;
+  /** 块内/迭代进度数字；undefined = 纯文案进度（UI 不渲染数字，只显示 message） */
+  current?: number;
+  max?: number;
+  message?: string;
+}
+
+/** loop.ts 每轮 yield 的 context_usage 事件（去掉 type 字段）。 */
+export type ContextUsageInfo = Omit<Extract<LoopEvent, { type: 'context_usage' }>, 'type'>;
+
+export interface UseChatResult {
+  history: Message[];
+  /** 当前流式中的文本（assistant 还在打字） */
+  streamingText: string;
+  /** 是否正在等模型 */
+  isLoading: boolean;
+  /** 最近一次错误（红色提示，永久进 scrollback 区上方） */
+  error: string | null;
+  /**
+   * 暂态错误（黄色，LiveArea 状态行下方一行）。喂给 LiveArea，可被覆盖刷新。
+   *
+   * 用途：工作流步执行中 LLM 调用失败（会被该步重试）时，把错误存这里而非作为
+   * 永久红字提交 —— 重试成功 / 步结束后由 useChat 清空，自然消失，不留痕。
+   * 同时承载 runner 的"重试 N/M…"进度（覆盖刷新，让用户一眼看出在第几次重试）。
+   */
+  transientError: string | null;
+  /** 用户按了 ESC/Ctrl+C 中断了任务（显示一行提示而不是红色错误） */
+  interrupted: boolean;
+  /** 当前插件循环状态（迭代进度） */
+  pluginProgress: PluginProgressState | null;
+  /** compact / clearHistory 触发的代号，作为 <Static key={}> remount 触发器 */
+  compactGeneration: number;
+  /** 当前阶段标签（'idle' 时 LiveArea 隐藏） */
+  progressStage: ProgressStage;
+  /** 思维链流式预览（环形 buffer，保留最近 ~600 字符 / ~10 行） */
+  reasoningPreview: string;
+  /** 当前所有运行中工具（用数组而不是 Map，便于 React render；按 callId 顺序稳定） */
+  runningTools: ToolStatusState[];
+  /**
+   * 内核最近一次 yield 的真实上下文用量；启动后/尚未跑过一轮时为 null，
+   * StatusLine 此时降级回本地 useTokenUsage 估算。
+   */
+  contextUsage: ContextUsageInfo | null;
+  /** 默认关闭；只有 /computer takeover 明确开启后，后续回合才获得宿主上下文。 */
+  computerUseMode: ComputerUseCliMode;
+  setComputerUseMode: (mode: ComputerUseCliMode) => void;
+  /** 精确停止当前 TUI 回合的 Computer Use；不会影响其他 Session。 */
+  stopComputerUse: () => Promise<string>;
+  pendingComputerIntervention: PendingHumanIntervention | null;
+  resumeComputerUse: () => Promise<string>;
+  cancelComputerUse: () => Promise<string>;
+  /** 当前激活的 session id（默认 'default'）。多 session 切换用 */
+  activeSessionId: string;
+  /** 排队等待执行的输入数量 */
+  queuedCount: number;
+  /** 排队中的输入项（只读快照，用于UI显示队列列表） */
+  queuedItems: readonly import('../../messageQueue.js').QueuedInput[];
+  /** 提交一次用户输入 */
+  submit: (input: string) => Promise<void>;
+  /** 中断当前执行 */
+  abort: () => void;
+  /** 清空对话上下文（保留 system prompt）；isLoading 时无效 */
+  clearHistory: () => void;
+  /** 手动压缩对话上下文（不看阈值）；isLoading 时无效 */
+  compactNow: () => Promise<void>;
+  /**
+   * `/advisor ask` 手动咨询顾问模型。与工具路径共用过程显示（LiveArea 进度行）
+   * 并可被 ESC 中断；isLoading 时拒绝执行并返回带原因的失败结果。
+   */
+  runManualAdvisor: (note?: string) => Promise<ToolResult>;
+  /**
+   * v2 新增：切换到指定 session（同 cwd 下）。
+   *   1. 保存当前 history 到当前 session 文件
+   *   2. 写 active-sessions.json 标记新 active id
+   *   3. 加载新 session 的历史（如不存在则新建空 history 含 fresh system prompt）
+   *   4. 触发 <Static> remount 让 MessageList 重画
+   * isLoading 时拒绝执行。
+   *
+   * `opts.force === true` 时即便 id 等于当前 active 也强制重新加载（/restore 用）。
+   */
+  switchSession: (id: string, opts?: { force?: boolean }) => Promise<void>;
+  /** Save the current Session and load a Session owned by another Workspace. */
+  switchWorkspace: (cwd: string, sessionId: string) => Promise<boolean>;
+  /**
+   * v2.x 新增：用 system+_ephemeral 形式把临时提示落进 scrollback。
+   *
+   * 替代直接 process.stdout.write 旁路 Ink（slash 命令输出等）。
+   * Ink 的 <Static> 会按 normal commit 流程把该消息推进 scrollback，
+   * 既显示给用户，又不破坏 log-update 的 previousLineCount 计数。
+   *
+   * - 持久化时 saveContext 会过滤掉这些 ephemeral 消息（不污染历史文件）
+   * - MessageList 识别 _ephemeral=true 走暗灰单行样式
+   * - 已知限制：本期不过滤 LLM 入参，短消息无害；下版本再做
+   */
+  ephemeralLine: (text: string) => void;
+  /**
+   * 当前待用户回答的提问（AskUserQuestion 工具触发）；null = 无。
+   * 非 null 时 App 渲染 <AskQuestion> 独占输入焦点（不渲染 InputBox）。
+   */
+  pendingAsk: AskQuestionSpec[] | null;
+  /** 当前提问的来源；子任务提问时 kind:'subagent' + description，供 AskQuestion 显示徽标。 */
+  pendingAskSource: AskSource | null;
+  /** 同一所有者尚未展示的排队问题数。 */
+  pendingAskQueueCount: number;
+  /** 回答当前提问 → resolve 工具侧 Promise，让主循环 / workflow 继续。 */
+  answerAsk: (answers: AskAnswer[]) => void;
+  /** 取消当前提问；子任务来源只取消该子任务。 */
+  cancelAsk: () => void;
+  /** 切换当前使用的 provider（/model 命令使用）；立即生效，后续请求使用新 provider。 */
+  setProvider: (provider: Provider) => void;
+  /** 获取当前 provider ref（用于状态行显示最新模型名）。 */
+  getCurrentProvider: () => Provider;
+}
+
+/**
+ * reasoningPreview 环形 buffer 容量（字符）。
+ * LiveArea 现在多行显示思维链尾部（最近 N 行），需要喂饱足够文本；
+ * 2400 字符约 30~40 行中文，LiveArea wrapToDisplayLines 后再取尾部最近 N 行。
+ * 上界由 LiveArea 的 contentMaxLines 兜底，这里只管"留够素材"。
+ */
+const REASONING_PREVIEW_MAX_CHARS = 2400;
+
+/**
+ * streamingText 环形 buffer 容量（字符）—— 仅用于 live 区"答案流式预览"。
+ *
+ * ★ 安全性：完整答案由 loop.ts 独立组装进 history（loop.ts 的 assistantText →
+ *   assistantMsg.content，整条 push），streamingText 是**纯预览**，环形截断不丢
+ *   最终结果（落定后 <Static> 渲染完整 message.content 接管）。
+ *   截断保证长答案流式时 LiveArea 只需 wrap 末段、render 成本恒定。
+ */
+const STREAM_PREVIEW_MAX_CHARS = 1500;
+
+/**
+ * Streaming text setState 节流参数。
+ *
+ * Why throttle：LLM 流式输出 60+ chunk/秒，原本每个 delta 立即 setStreamingText
+ * 在 Windows PowerShell 终端下 Ink ANSI cursor 重绘跟不上，导致每个字打成新行
+ * （已确认根因，Plan agent 验证过）。这里用 leading-edge throttle：首个 delta
+ * 启动 100ms timer，期间所有 delta 累积到 ref，到点 flush 一次 setStreamingText。
+ *
+ *   STREAM_FLUSH_MS    : 100ms 节流（React rerender 频率 ≤ 10 Hz，叠加 Ink 内部
+ *                        32ms throttle 后实际重画 ≤ 10 Hz，Windows 终端能跟上）
+ *   STREAM_FLUSH_MAX_CHARS : 缓冲超 200 字符立即 flush（防长段中文 100ms 内塞太
+ *                        多触发 React 大量 reconcile）
+ *
+ * Why not debounce：debounce 在 token 持续到达时永远刷新定时器，流式期间可能
+ * 完全不更新 UI，等于"看不见"。leading-edge throttle 保证稳定 10 Hz 出现新内容。
+ */
+const STREAM_FLUSH_MS = 100;
+const STREAM_FLUSH_MAX_CHARS = 200;
+
+/** 按字符尾部截断（多字节字符 JS 字符串以 UTF-16 code unit 计，对中文已足够"差不多"）。 */
+function sliceLatest(s: string, maxChars: number): string {
+  if (s.length <= maxChars) return s;
+  return s.slice(s.length - maxChars);
+}
+
+function useThrottledFlush({
+  delayMs,
+  maxChars,
+  flushEmpty,
+  onFlush,
+}: {
+  delayMs: number;
+  maxChars?: number;
+  flushEmpty?: boolean;
+  onFlush: (buffered: string) => void;
+}) {
+  const bufferRef = useRef<string>('');
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const flush = useCallback(() => {
+    if (timerRef.current) {
+      clearTimeout(timerRef.current);
+      timerRef.current = null;
+    }
+    const buffered = bufferRef.current;
+    bufferRef.current = '';
+    if (buffered.length === 0 && !flushEmpty) return;
+    onFlush(buffered);
+  }, [flushEmpty, onFlush]);
+
+  const cancel = useCallback(() => {
+    if (timerRef.current) {
+      clearTimeout(timerRef.current);
+      timerRef.current = null;
+    }
+    bufferRef.current = '';
+  }, []);
+
+  const schedule = useCallback(() => {
+    if (timerRef.current !== null) return;
+    timerRef.current = setTimeout(flush, delayMs);
+  }, [delayMs, flush]);
+
+  const append = useCallback(
+    (delta: string) => {
+      bufferRef.current += delta;
+      if (typeof maxChars === 'number' && bufferRef.current.length >= maxChars) {
+        flush();
+        return;
+      }
+      schedule();
+    },
+    [flush, maxChars, schedule],
+  );
+
+  return useMemo(
+    () => ({ append, flush, cancel, schedule }),
+    [append, flush, cancel, schedule],
+  );
+}
+
+export function useChat(args: {
+  provider: Provider;
+  initialHistory: Message[];
+  /**
+   * 压缩完成后被回调，供 UI 层清屏。
+   */
+  onCompactDone?: () => void;
+}): UseChatResult {
+  // 历史用 ref（可变），用 version 触发 re-render
+  const historyRef = useRef<Message[]>(args.initialHistory.slice());
+  const [version, setVersion] = useState(0);
+  const bump = useCallback(() => setVersion((v) => v + 1), []);
+
+  // provider 用 ref 存储，支持运行时切换（/model 命令切换基座模型）
+  const providerRef = useRef<Provider>(args.provider);
+
+  const [streamingText, setStreamingText] = useState('');
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [transientError, setTransientError] = useState<string | null>(null);
+  const [interrupted, setInterrupted] = useState(false);
+
+  /**
+   * 暂态错误状态机的跨事件可变上下文（用 ref，不需要为它单独重渲染）。
+   *   - activeStepId：当前正在执行的 workflow step id（workflow_step_start 记下，
+   *     该 step 的 workflow_step_end 清除）；null = 不在任何 step 内。
+   *   - pendingLlmError：该 step 执行中捕获到的最近一次 llm_error 文案（暂存，
+   *     等 step 结束才决定丢弃 or 提升为永久红字）。
+   * handleEvent 通过 setters.workflowCtx 同步读写这个对象（pure 逻辑，测试可注入 stub）。
+   */
+  const workflowCtxRef = useRef<{
+    activeStepId: string | null;
+    pendingLlmError: string | null;
+  }>({ activeStepId: null, pendingLlmError: null });
+  // 工作流步骤 id → 人话进度名（title）映射：start 记入、end/skipped 回查，
+  // 让 scrollback 三种进度行（▶/✓/⊘）都显示同一人话名而非 id。跨事件持 ref。
+  const stepTitlesRef = useRef<Map<string, string>>(new Map());
+  const [pluginProgress, setPluginProgress] =
+    useState<PluginProgressState | null>(null);
+
+  // ---- 工作过程显示相关 state ----
+  const [compactGeneration, setCompactGeneration] = useState(0);
+  const [progressStage, setProgressStage] = useState<ProgressStage>('idle');
+  const [reasoningPreview, setReasoningPreview] = useState('');
+  /**
+   * 内核每轮 yield 的真实上下文用量（含 tools-schema 开销 + 真实 provider usage，
+   * 见 loop.ts 的 context_usage 事件）。收到过至少一次前 StatusLine 用它渲染，
+   * 比 useTokenUsage 的本地估算更准；未收到过（如刚启动、纯只读问答走了只读快速
+   * 路径）时该值仍是 null，StatusLine 降级回 useTokenUsage 估算。
+   */
+  const [contextUsage, setContextUsage] = useState<ContextUsageInfo | null>(null);
+  const [computerUseMode, setComputerUseMode] =
+    useState<ComputerUseCliMode>('disabled');
+  const promptToolSignatureRef = useRef('');
+  const activeComputerRunRef = useRef<ComputerUseRunContext | null>(null);
+  const [computerInterventions] = useState(() => new HumanInterventionCoordinator());
+  const [pendingComputerIntervention, setPendingComputerIntervention] =
+    useState<PendingHumanIntervention | null>(null);
+  useEffect(() => computerInterventions.subscribe((event) => {
+    if (event.type === 'started') {
+      setPendingComputerIntervention(event.intervention);
+    } else {
+      setPendingComputerIntervention((current) =>
+        current?.id === event.resolution.intervention.id ? null : current);
+    }
+  }), [computerInterventions]);
+  /**
+   * 工具并行执行：以 callId 为 key 保存所有运行中工具。
+   * 用 Map 是为了 O(1) 增删；对外 memo 物化成稳定数组（Map 迭代顺序 = 插入顺序，
+   * 给 React 渲染天然稳定）。
+   */
+  const [runningToolsMap, setRunningToolsMap] = useState<
+    Map<string, ToolStatusState>
+  >(new Map());
+  const runningTools = useMemo(
+    () => Array.from(runningToolsMap.values()),
+    [runningToolsMap],
+  );
+  const abortRef = useRef<AbortController | null>(null);
+
+  const [inputQueue] = useState(() => createInputQueue());
+  const [queuedCount, setQueuedCount] = useState(0);
+  const [queuedItems, setQueuedItems] = useState<readonly import('../../messageQueue.js').QueuedInput[]>([]);
+  const runningToolsRef = useRef<Map<string, { toolName: string; isCancelable: boolean }>>(new Map());
+
+  useEffect(() => {
+    return inputQueue.subscribe(() => {
+      setQueuedCount(inputQueue.size());
+      setQueuedItems(inputQueue.getSnapshot());
+    });
+  }, [inputQueue]);
+
+  // ---- AskUserQuestion：执行中向用户提问 ----
+  // pendingAsk 非 null 时 App 渲染 <AskQuestion> 独占输入（不渲染 InputBox）。
+  // 单槽状态机（resolve/reject 持有、abort 归属校验、悬挂防护）抽在
+  // askSlot.ts（纯函数可单测）；这里只桥接 React 状态。
+  const [pendingAsk, setPendingAsk] = useState<AskQuestionSpec[] | null>(null);
+  // 提问来源：子任务提问时 kind:'subagent' + description → AskQuestion 显示徽标。
+  const [pendingAskSource, setPendingAskSource] = useState<AskSource | null>(null);
+  const [pendingAskQueueCount, setPendingAskQueueCount] = useState(0);
+  const [askSlot] = useState(() =>
+    createAskSlot((questions, source) => {
+      setPendingAsk(questions);
+      setPendingAskSource(questions ? source ?? null : null);
+    }),
+  );
+
+  const streamingFlush = useThrottledFlush({
+    delayMs: STREAM_FLUSH_MS,
+    maxChars: STREAM_FLUSH_MAX_CHARS,
+    onFlush: useCallback((buffered: string) => {
+      setStreamingText((prev) =>
+        sliceLatest(prev + buffered, STREAM_PREVIEW_MAX_CHARS),
+      );
+    }, []),
+  });
+
+  // ---- reasoning preview setState 节流 ----
+  // 用户反馈思考阶段需要看到流式思维链。reasoning delta 频率跟 text delta 一样高
+  // （60+ chunk/秒），不节流的话每个 delta 立即 setReasoningPreview → LiveArea
+  // rerender → Ink 重绘扛不住。复用 streaming 一样的 100ms / 200 字符节流参数。
+  const reasoningFlush = useThrottledFlush({
+    delayMs: STREAM_FLUSH_MS,
+    maxChars: STREAM_FLUSH_MAX_CHARS,
+    onFlush: useCallback((buffered: string) => {
+      setReasoningPreview((prev) =>
+        sliceLatest(prev + buffered, REASONING_PREVIEW_MAX_CHARS),
+      );
+    }, []),
+  });
+
+  // ---- tool_start/end 的 bump 节流 ----
+  // tool_start / tool_end 单独触发 bump 会导致每个工具事件都是一次顶层 rerender；
+  // 200ms 内合并成单次 bump，避免高频"工具状态切换"压垮 Ink ANSI 重绘。
+  // 注意：assistant_message 走立即 bump（不节流），因为 history 增长时 Static 需要
+  // 立即 commit 新 item，不能延迟。
+  const toolBumpFlush = useThrottledFlush({
+    delayMs: 200,
+    flushEmpty: true,
+    onFlush: useCallback(() => {
+      bump();
+    }, [bump]),
+  });
+
+  /**
+   * 把 turn 结束 / 切换 session / clearHistory 时的"工作过程显示 state
+   * 归位"集中成一个函数。React 18 自动 batch 这一组 setState（同一个 microtask 内
+   * 调用），结果就是 1 次 commit。集中后调用点更清晰，也方便后续再优化。
+   */
+  const resetTurnState = useCallback(() => {
+    setStreamingText('');
+    setProgressStage('idle');
+    setReasoningPreview('');
+    setRunningToolsMap(new Map());
+    // 暂态错误是"过程级"提示，turn 结束 / 切换时一并清掉，不残留到下一轮
+    setTransientError(null);
+    workflowCtxRef.current = { activeStepId: null, pendingLlmError: null };
+  }, []);
+
+  /** turn 结束 / 中断 / 切换时一并取消所有节流 buffer 的 pending timer。 */
+  const cancelAllThrottles = useCallback(() => {
+    streamingFlush.cancel();
+    reasoningFlush.cancel();
+    toolBumpFlush.cancel();
+  }, [streamingFlush, reasoningFlush, toolBumpFlush]);
+
+  // ---- v2 multi-session ----
+  // activeSessionId 启动时同步默认 'default'；mount 后异步读 active-sessions.json
+  // 更新为该 cwd 真正激活的 session。所有持久化路径都按 ref 取最新值，
+  // ref 比 state 顺手——switchSession 内同步切换 ref 后下一行立刻 saveContext 能用新值。
+  const activeSessionIdRef = useRef<string>('default');
+  const [activeSessionId, setActiveSessionId] = useState<string>('default');
+
+  /** 当前 active session 对应的持久化文件路径（同步，按 ref 取） */
+  const sessionFile = useCallback(() => {
+    return sessionFileFor(getWorkingDir(), activeSessionIdRef.current);
+  }, []);
+
+  // 卸载时取消任何进行中的请求
+  useEffect(() => {
+    return () => {
+      abortRef.current?.abort();
+    };
+  }, []);
+
+  // mount 时把「弹选择界面」的处理器注册到 askBridge；unmount 注销。
+  // 两层组合：createAskCoordinator（FIFO 队列——主循环与并行 general 子 Agent 都可能
+  // 提问，用户一次只看一个问题，其余排队；实例按 TUI 挂载创建，不同进程互不阻塞）
+  // 包住 askSlot.handler（呈现层单槽 + abort 归属校验——同轮多次提问共享 turn signal，
+  // 归属校验保证已答完提问的 abort 监听器不会清掉后来提问的槽，否则后者 promise
+  // 永不落定 → 整轮死挂，见 askSlot.ts 头注）。
+  useEffect(() => {
+    setAskHandler(createAskCoordinator(askSlot.handler, (status) => {
+      setPendingAskQueueCount(status.queuedCount ?? 0);
+    }));
+    return () => setAskHandler(null);
+  }, [askSlot]);
+
+  /** 用户答完当前提问：清 pending + resolve 工具侧 Promise，执行继续。 */
+  const answerAsk = useCallback(
+    (answers: AskAnswer[]) => askSlot.answer(answers),
+    [askSlot],
+  );
+
+  const cancelAsk = useCallback(() => {
+    if (pendingAskSource?.kind === 'subagent') askSlot.cancel();
+    else abortRef.current?.abort();
+  }, [askSlot, pendingAskSource]);
+
+  // Root 已按 active session 加载初始历史；这里同步同一 active id 给交互状态。
+  useEffect(() => {
+    let cancelled = false;
+    void (async () => {
+      try {
+        const id = await getActiveSession(getWorkingDir());
+        if (cancelled) return;
+        activeSessionIdRef.current = id;
+        setActiveSessionId(id);
+      } catch {
+        // 读失败保持 default，不影响功能
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  /**
+   * 最新 submit 的 latest-ref。runManualAdvisor 定义在 submit 之前（它不能依赖
+   * submit 的闭包），但结束时要把排队输入交回去执行 —— 用 ref 打破定义顺序，
+   * 而不是把两者的定义顺序倒过来（那会让 submit 依赖 runManualAdvisor，更绕）。
+   */
+  const submitRef = useRef<((input: string) => Promise<void>) | null>(null);
+
+  /**
+   * `/advisor ask` 的执行体：让手动咨询和工具咨询共用同一套过程显示。
+   *
+   * 此前 App.tsx 里是裸 `await runAdvisor(...)` —— 顾问最长跑 180 秒，这期间 TUI
+   * 一个字都不动，也按不停。工具路径早就修过同款问题（advisor.ts 的 reportProgress
+   * 节流发布，源于 2026-07「2m05s 无变化被误判死机」的真实反馈），手动路径却没跟上：
+   * 同一个功能两条路径，用户**主动发起**的那条体验反而更差。
+   *
+   * 复用既有的 runningTools + progressStage（不新增 UI 概念）：塞一个运行中条目给
+   * LiveArea，进度行由 runAdvisor 的 reportProgress 驱动；挂 abortRef 让 ESC/Ctrl+C
+   * 真能掐断，而不是干等到超时。
+   */
+  const runManualAdvisor = useCallback(
+    async (note?: string): Promise<ToolResult> => {
+      if (isLoading) {
+        return { ok: false, error: '当前有任务在执行；等它结束或按 ESC 中断后再咨询顾问。' };
+      }
+      const callId = 'manual-advisor';
+      const ac = new AbortController();
+      abortRef.current = ac;
+      setIsLoading(true);
+      setProgressStage('tool_executing');
+      setRunningToolsMap(new Map([[callId, {
+        toolName: 'Advisor',
+        argsPreview: note ?? '',
+        status: 'running' as const,
+        argsFriendly: '正在咨询顾问模型',
+      }]]));
+      try {
+        return await runAdvisor(
+          note ? { note } : {},
+          ac.signal,
+          {
+            history: historyRef.current,
+            advisorCalls: { used: 0, max: 1 },
+            advisorInvocation: 'manual',
+            reportProgress: (message) => {
+              // advisor.ts 侧已有 200ms 节流，这里直接落状态即可。
+              setRunningToolsMap((prev) => {
+                const current = prev.get(callId);
+                if (!current) return prev;
+                return new Map(prev).set(callId, { ...current, progress: message });
+              });
+            },
+          },
+        );
+      } finally {
+        setIsLoading(false);
+        setProgressStage('idle');
+        setRunningToolsMap(new Map());
+        abortRef.current = null;
+        // ⚠️ 必须消费排队输入。设了 isLoading 之后，用户在咨询期间敲的内容会被
+        // submit 送进 inputQueue，而队列此前**只在 submit 自己的 finally 里**出队
+        // （见下方 consumeQueued）—— 手动咨询不走那条路径，排队的话就会静静躺着，
+        // 用户看到「排队 1 条」却永远不执行，直到下次提交才错序跑掉。
+        const queued = inputQueue.dequeue();
+        if (queued) queueMicrotask(() => { void submitRef.current?.(queued.value); });
+      }
+    },
+    [isLoading, inputQueue],
+  );
+
+  const submit = useCallback(
+    async (input: string) => {
+      const trimmed = input.trim();
+      if (trimmed.length === 0) return;
+
+      if (isLoading) {
+        inputQueue.enqueue(trimmed, 'next');
+        const running = Array.from(runningToolsRef.current.values());
+        const allCancelable = running.length > 0 && running.every(t => t.isCancelable);
+        if (allCancelable) {
+          abortRef.current?.abort('interrupt');
+        }
+        bump();
+        return;
+      }
+
+      setIsLoading(true);
+      setError(null);
+      setTransientError(null);
+      setInterrupted(false);
+      cancelAllThrottles();
+      setStreamingText('');
+      setPluginProgress(null);
+      // 进入新一轮，把工作过程显示相关 state 全部归位
+      setProgressStage('idle');
+      setReasoningPreview('');
+      setRunningToolsMap(new Map());
+      // 重置暂态错误状态机（防上一轮工作流残留）
+      workflowCtxRef.current = { activeStepId: null, pendingLlmError: null };
+
+      const ac = new AbortController();
+      abortRef.current = ac;
+      let releaseContextLock: (() => Promise<void>) | null = null;
+      let turnJournal: TurnJournal | null = null;
+      let turnJournalStart = 0;
+      dlog('ui', 'turn START', { input: trimmed.slice(0, 80) });
+
+      // 长时间运行时（如工作流 agent 步骤）的定时 token 刷新：
+      // runQuery 的 text/reasoning 事件不触发 bump，导致 StatusLine token 数
+      // 可能冻结数十秒。此定时器每 10s 强制刷新一次，确保用户看到上下文增长。
+      const tokenRefreshTimer = setInterval(() => {
+        bump();
+      }, 10_000);
+
+      try {
+        await updateSessionMetadata(getWorkingDir(), activeSessionIdRef.current, {
+          lastMessagePreview: trimmed,
+        }).catch(() => {});
+        const activeFile = sessionFileFor(getWorkingDir(), activeSessionIdRef.current);
+        releaseContextLock = await acquireContextLock(activeFile, ac.signal);
+        // Gateway/Cron may have written this cwd since the TUI rendered its last frame.
+        // Reload after acquiring the cross-process lock so this turn extends the newest history.
+        const latest = await loadContext(activeFile);
+        if (latest) {
+          const ephemeral = historyRef.current.filter((message) => message.role === 'system' && message._ephemeral);
+          historyRef.current.length = 0;
+          historyRef.current.push(...latest, ...ephemeral);
+        }
+        const workspace = await workspaceIndexService.findByPath(getWorkingDir()).catch(() => null);
+        const computerRun =
+          computerUseMode !== 'disabled'
+            ? createCliComputerRun({
+                mode: computerUseMode,
+                surface: 'tui',
+                conversationKey: `workspace:${workspace?.id ?? getWorkingDir()}:session:${activeSessionIdRef.current}`,
+                userInput: trimmed,
+                allowedFileRoots: [getWorkingDir()],
+                supervised: true,
+              })
+            : undefined;
+        activeComputerRunRef.current = computerRun ?? null;
+        const computerIntervention = computerRun
+          ? createComputerInterventionAdapter({
+              coordinator: computerInterventions,
+              context: computerRun,
+              observe: async (signal) => {
+                // Resume is a canonical boundary: it invalidates every old
+                // coordinate/AX reference and clears the native takeover
+                // cancellation for this run only.
+                const response = await computerUseService.request(
+                  computerRun,
+                  { action: 'observe' },
+                  signal,
+                );
+                return response.ok ? response.state : undefined;
+              },
+            })
+          : undefined;
+        const toolGate = computerRun ? createComputerUseHostGate(computerRun) : undefined;
+        const turnSessionState = getOrCreateSessionState(sessionStateKey({
+          surface: 'tui', workspaceId: workspace?.id,
+          cwd: workspace?.id ? undefined : getWorkingDir(),
+          sessionId: activeSessionIdRef.current,
+        }));
+        await hydrateSessionWorktree({
+          sessionState: turnSessionState, workspaceId: workspace?.id,
+          sessionId: activeSessionIdRef.current, cwd: getWorkingDir(),
+        });
+        const effectiveCwd = turnSessionState.activeWorktree?.path ?? getWorkingDir();
+        const runtimeContext = createAgentRuntimeContext({
+          surface: 'tui',
+          profile: 'main',
+          cwd: effectiveCwd,
+          workspaceId: workspace?.id,
+          sessionId: activeSessionIdRef.current,
+          owner: 'local-owner',
+          memoryAccess: 'read-write',
+          interactiveAsk: true,
+          computer: computerRun,
+          computerIntervention,
+          toolGate,
+        });
+        const turnTools = filterToolsForRuntime(ALL_TOOLS, runtimeContext);
+        const toolSignature = `${effectiveCwd}\0${turnTools.map((tool) => tool.name).join(',')}`;
+        if (promptToolSignatureRef.current !== toolSignature) {
+          const stablePrompt = await buildBaseSystemPrompt(effectiveCwd, turnTools);
+          const rest = historyRef.current[0]?.role === 'system'
+            ? historyRef.current.slice(1)
+            : [...historyRef.current];
+          historyRef.current.length = 0;
+          historyRef.current.push({ role: 'system', content: stablePrompt }, ...rest);
+          promptToolSignatureRef.current = toolSignature;
+        }
+        // 每回合只刷新易变层；稳定层仅在实际能力目录变化时重建。
+        const turnTransient = await buildTransientPromptBundle({
+          cwd: effectiveCwd,
+          tools: turnTools,
+          runtime: {
+            surface: 'tui',
+            cwd: effectiveCwd,
+            currentUserInput: trimmed,
+            workspaceId: workspace?.id,
+            sessionId: activeSessionIdRef.current,
+            interactiveAsk: true,
+            supervisedBrowser: false,
+            memoryAccess: 'read-write',
+          },
+        }).catch(() => undefined);
+        // 会话原文记账（与 session/runTurn.ts 共用同一份实现）。
+        // TUI 不经过 runTurn，此前整条路径都不入库，SearchConversations 对 TUI 用户静默失效。
+        turnJournalStart = historyRef.current.length;
+        turnJournal = await startTurnJournal({
+          memoryContext: memoryContextFromRuntime(runtimeContext),
+          userInput: trimmed,
+        }).catch(() => null);
+        for await (const ev of runWithPlugins(trimmed, {
+          provider: providerRef.current,
+          history: historyRef.current,
+          signal: ac.signal,
+          runtimeContext,
+          allowedTools: turnTools.map((tool) => tool.name),
+          sessionState: turnSessionState,
+          parseInlineImages: true,
+          ...(turnTransient ? { transientBundle: turnTransient } : {}),
+          promptCache: createPromptCacheContext(
+            `workspace:${workspace?.id ?? getWorkingDir()}:session:${activeSessionIdRef.current}`,
+          ),
+          hasQueuedInput: () => inputQueue.size() > 0,
+          memoryContext: memoryContextFromRuntime(runtimeContext),
+          ...(computerRun ? { computerRun } : {}),
+          ...(computerIntervention ? { computerIntervention } : {}),
+          ...(toolGate ? { toolGate } : {}),
+          onToolStart: (name, id) => {
+            const tool = getToolByName(name);
+            runningToolsRef.current.set(id, {
+              toolName: name,
+              isCancelable: tool?.interruptBehavior?.() === 'cancel',
+            });
+          },
+          onToolEnd: (id) => {
+            runningToolsRef.current.delete(id);
+          },
+        })) {
+          handleEvent(ev, {
+            setStreamingText,
+            setError,
+            setInterrupted,
+            setPluginProgress,
+            setCompactGeneration,
+            setProgressStage,
+            setReasoningPreview,
+            setRunningToolsMap,
+            setContextUsage,
+            // 暂态错误（工作流步内 llm_error / 重试进度）→ LiveArea 黄字
+            setTransientError,
+            workflowCtx: workflowCtxRef.current,
+            // 步骤 id→人话名映射：scrollback 进度行三态（▶/✓/⊘）统一显示 title
+            stepTitles: stepTitlesRef.current,
+            // 节流相关 —— buffer 累积 + 100ms timer flush
+            appendStreamingDelta: streamingFlush.append,
+            flushStreamingBuffer: streamingFlush.flush,
+            cancelStreamingFlush: streamingFlush.cancel,
+            // reasoning preview 节流 + 落定清空
+            appendReasoningDelta: reasoningFlush.append,
+            cancelReasoningFlush: reasoningFlush.cancel,
+            // tool_start/end 节流 bump
+            scheduleToolBump: toolBumpFlush.schedule,
+            cancelToolBump: toolBumpFlush.cancel,
+            bump,
+            // 工作流进度逐步可见（持久暗色行）
+            emitProgressLine: ephemeralLine,
+          });
+        }
+      } catch (e) {
+        setError(`未捕获异常：${(e as Error).message}`);
+        dlog('ui', 'turn THREW', { err: (e as Error).message });
+      } finally {
+        dlog('ui', 'turn END (finally)');
+        clearInterval(tokenRefreshTimer);
+        setIsLoading(false);
+        cancelAllThrottles();
+        resetTurnState();
+        setPluginProgress(null);
+        abortRef.current = null;
+        if (activeComputerRunRef.current) {
+          computerInterventions.abort(activeComputerRunRef.current);
+        }
+        activeComputerRunRef.current = null;
+        runningToolsRef.current.clear();
+        // 记账失败不影响落盘与解锁（它是附加能力，不是功能）。
+        await turnJournal?.finish(historyRef.current, turnJournalStart).catch(() => undefined);
+        turnJournal = null;
+        // v2 multi-session：持久化到当前 active session 文件。
+        try {
+          await saveContext(historyRef.current, sessionFileFor(getWorkingDir(), activeSessionIdRef.current));
+        } finally {
+          await releaseContextLock?.();
+        }
+
+        const consumeQueued = () => {
+          const next = inputQueue.dequeue();
+          if (!next) return;
+          queueMicrotask(() => {
+            void submit(next.value);
+          });
+        };
+        consumeQueued();
+      }
+    },
+    [
+      bump,
+      isLoading,
+      sessionFile,
+      streamingFlush,
+      cancelAllThrottles,
+      reasoningFlush,
+      toolBumpFlush,
+      resetTurnState,
+      inputQueue,
+      computerUseMode,
+      computerInterventions,
+    ],
+  );
+
+  // latest-ref 赋值：runManualAdvisor 的 finally 靠它把排队输入交回 submit。
+  // 渲染体内直接赋值是 latest-ref 的常规写法；用 useEffect 会晚一帧，而咨询
+  // 结束时机与渲染无关，晚一帧就可能取到上一轮的闭包。
+  submitRef.current = submit;
+
+  const abort = useCallback(() => {
+    inputQueue.clear();
+    runningToolsRef.current.clear();
+    if (activeComputerRunRef.current) {
+      computerInterventions.abort(activeComputerRunRef.current);
+    }
+    abortRef.current?.abort();
+  }, [computerInterventions, inputQueue]);
+
+  const stopComputerUse = useCallback(async (): Promise<string> => {
+    setComputerUseMode('disabled');
+    const context = activeComputerRunRef.current;
+    if (!context) return '已撤销后续回合授权；当前没有正在运行的 Computer Use。';
+    computerInterventions.abort(context);
+    const response = await computerUseService.request(context, { action: 'stop' });
+    return response.ok
+      ? '已停止当前回合的 Computer Use，并撤销后续回合授权。'
+      : `已撤销后续回合授权；原生停止失败：${response.error?.message ?? '未知错误'}`;
+  }, [computerInterventions]);
+
+  const resumeComputerUse = useCallback(async (): Promise<string> => {
+    const pending = pendingComputerIntervention;
+    if (!pending) return '当前没有等待人工处理的 Computer Use。';
+    const resumed = computerInterventions.resume({
+      id: pending.id,
+      resumeToken: pending.resumeToken,
+      ownerId: pending.ownerId,
+      conversationKey: pending.conversationKey,
+      runId: pending.runId,
+    });
+    return resumed
+      ? '已恢复原 Computer Use 运行，将先重新观察目标应用再继续。'
+      : '人工介入请求已失效，请重新观察目标应用。';
+  }, [computerInterventions, pendingComputerIntervention]);
+
+  const cancelComputerUse = useCallback(async (): Promise<string> => {
+    const pending = pendingComputerIntervention;
+    if (!pending) return stopComputerUse();
+    const cancelled = computerInterventions.cancel({
+      id: pending.id,
+      resumeToken: pending.resumeToken,
+      ownerId: pending.ownerId,
+      conversationKey: pending.conversationKey,
+      runId: pending.runId,
+    });
+    setComputerUseMode('disabled');
+    return cancelled
+      ? '已取消当前人工介入并停止该 Computer Use 任务。'
+      : '人工介入请求已失效。';
+  }, [computerInterventions, pendingComputerIntervention, stopComputerUse]);
+
+  const setProvider = useCallback((next: Provider) => {
+    providerRef.current = next;
+  }, []);
+
+  const getCurrentProvider = useCallback(() => providerRef.current, []);
+
+  /**
+   * v2.x 新增：把一段临时提示文本作为 _ephemeral 的 system 消息插入 history。
+   *
+   * 用途：替代 slash 命令分支直接 process.stdout.write 旁路 Ink 的写法
+   * （那种写法每次都让 ink log-update 的 previousLineCount 失步，
+   * 下一帧 eraseLines 会留下未擦行）。
+   *
+   * 流程：push 进 historyRef → bump() 触发 history useMemo 重算 →
+   * MessageList <Static> 把它作为新 item commit 进 scrollback。
+   * saveContext 写盘时过滤掉这些 ephemeral 消息。
+   */
+  const ephemeralLine = useCallback(
+    (text: string) => {
+      historyRef.current.push({
+        role: 'system',
+        content: text,
+        _ephemeral: true,
+        timestamp: Date.now(),
+      });
+      bump();
+    },
+    [bump],
+  );
+
+  /**
+   * /new —— 清空历史，重新生成 system prompt（带最新 skills + 项目指令）。
+   * 不复用启动时的初始 history 快照，避免把磁盘里的损坏数据带回来。
+   * isLoading 时拒绝执行，避免和正在跑的 runQuery 抢状态。
+   */
+  const clearHistory = useCallback(async () => {
+    if (isLoading) return;
+
+    // 生成全新的 system prompt（实时扫 skills + 拼项目指令），
+    // 与启动时 main.tsx buildInitialHistory 行为完全一致
+    const newSystemPrompt = await buildBaseSystemPrompt(getWorkingDir(), ALL_TOOLS);
+    historyRef.current.length = 0;
+    historyRef.current.push({ role: 'system', content: newSystemPrompt });
+    promptToolSignatureRef.current = '';
+
+    // 允许新 session 再次触发反应式压缩自救
+    resetReactiveCompactState();
+
+    cancelAllThrottles();
+    setError(null);
+    setInterrupted(false);
+    // 清空工作过程显示状态，避免 /new 后旧 turn 残留闪现
+    resetTurnState();
+    // 强制 MessageList 内 <Static> remount，避免旧消息卡在屏幕上
+    setCompactGeneration((g) => g + 1);
+    bump();
+
+    // 清空磁盘上的持久化文件（防止下次启动又加载损坏数据）
+    await clearContext();
+    // 清空 pre-read guard 状态表（防止跨 session 的 Read 记录污染新会话）
+    const workspace = await workspaceIndexService.findByPath(getWorkingDir()).catch(() => null);
+    clearFileState(getOrCreateSessionState(sessionStateKey({
+      surface: 'tui',
+      workspaceId: workspace?.id,
+      cwd: workspace?.id ? undefined : getWorkingDir(),
+      sessionId: activeSessionIdRef.current,
+    })).fileReads);
+    // 刚清空，不需要再保存一次"空历史"
+  }, [bump, isLoading, cancelAllThrottles, resetTurnState]);
+
+  /**
+   * /compact —— 手动跑一次压缩（不看阈值）。
+   * isLoading 时拒绝执行；压缩自身的 setIsLoading(true) 会让 InputBox 显示 ⏳。
+   *
+   * ✅ 关键改进：压缩失败时不保存 history（可能包含损坏数据）
+   */
+  const compactNow = useCallback(async () => {
+    if (isLoading) return;
+    setIsLoading(true);
+    // 手动压缩仍然把 progressStage 切到 compacting，给 LiveArea 显示用
+    setProgressStage('compacting');
+    setError(null);
+    // 压缩前清掉任何待 flush 的 streaming buffer（避免压缩中 timer 触发干扰）
+    cancelAllThrottles();
+    let success = false;
+    try {
+      const cwd = getWorkingDir();
+      const workspace = await workspaceIndexService.findByPath(cwd).catch(() => null);
+      const r = await forceCompact(
+        historyRef.current,
+        args.provider,
+        undefined,
+        undefined,
+        createPromptCacheContext(
+          `workspace:${workspace?.id ?? cwd}:session:${activeSessionIdRef.current}`,
+        ),
+      );
+      historyRef.current.length = 0;
+      historyRef.current.push(...r.messages);
+      // 压缩后 MessageList 要 remount，丢掉旧 <Static> 缓存
+      setCompactGeneration((g) => g + 1);
+      bump();
+      success = true; // ✅ 标记成功
+    } catch (e) {
+      setError(`手动压缩失败：${(e as Error).message}`);
+      // ❌ 不修改 historyRef.current，保持原样（不保存可能损坏的数据）
+    } finally {
+      setProgressStage('idle');
+      setIsLoading(false);
+      // ✅ 只在成功时才持久化，避免保存损坏的历史到磁盘
+      if (success) {
+        // v2 multi-session：持久化到当前 active session 文件
+        saveContext(historyRef.current, sessionFile()).catch(() => {});
+        args.onCompactDone?.();
+      }
+    }
+  }, [
+    args.provider,
+    args.onCompactDone,
+    bump,
+    isLoading,
+    sessionFile,
+    cancelAllThrottles,
+  ]);
+
+  /**
+   * /session <id> —— 切换到指定 session（同 cwd 下）。
+   *
+   * 流程：
+   *   1) saveContext 保住当前 session 的最新历史
+   *   2) setActiveSession 更新注册表
+   *   3) 改 activeSessionIdRef + state（让 UI 显示 / 持久化路径都走新 id）
+   *   4) resolveSessionFile + loadContext 读新 session 历史（不存在则新建空）
+   *   5) 替换 historyRef.current（保留 system prompt 在头部）
+   *   6) bump + setCompactGeneration 触发 Static remount
+   *
+   * isLoading 时拒绝执行，避免与 runQuery 抢状态。
+   */
+  const switchSession = useCallback(
+    async (id: string, opts?: { force?: boolean }) => {
+      if (isLoading) return;
+      const trimmed = id.trim();
+      if (trimmed.length === 0) return;
+      // force=true 时即便同 id 也强制重新加载（/restore 覆盖文件后用）
+      if (!opts?.force && trimmed === activeSessionIdRef.current) return;
+
+      const cwd = getWorkingDir();
+
+      // 1. 保住当前 session
+      try {
+        await saveContext(historyRef.current, sessionFileFor(cwd, activeSessionIdRef.current));
+      } catch {
+        // 保存失败不阻塞切换（用户可能就是想切走止损）
+      }
+
+      // 2. 更新注册表
+      try {
+        await setActiveSession(cwd, trimmed);
+      } catch {
+        // 注册失败不阻塞切换
+      }
+
+      // 3. 切 ref + state
+      activeSessionIdRef.current = trimmed;
+      setActiveSessionId(trimmed);
+
+      // 4. 加载新 session 历史（resolveSessionFile 支持 v1 → v2 路径兜底）
+      let loaded: Message[] | null = null;
+      try {
+        const newPath = await resolveSessionFile(cwd, trimmed);
+        loaded = await loadContext(newPath);
+      } catch {
+        loaded = null;
+      }
+
+      // 5. 替换 historyRef，保留启动时的 system prompt 在头部
+      const systemMsg = historyRef.current.find((m) => m.role === 'system');
+      historyRef.current.length = 0;
+      if (systemMsg) historyRef.current.push(systemMsg);
+      if (loaded && loaded.length > 0) {
+        // loaded 可能含旧 system prompt（旧版 last-context.json 保存了一份），跳过
+        const rest = loaded[0]?.role === 'system' ? loaded.slice(1) : loaded;
+        historyRef.current.push(...rest);
+      }
+
+      // 6. 清掉中间态、触发 Static remount
+      cancelAllThrottles();
+      setError(null);
+      setInterrupted(false);
+      resetTurnState();
+      setCompactGeneration((g) => g + 1);
+      bump();
+    },
+    [bump, isLoading, cancelAllThrottles, resetTurnState],
+  );
+
+  const switchWorkspace = useCallback(async (cwd: string, sessionId: string) => {
+    if (isLoading) return false;
+    const targetCwd = cwd.trim();
+    const targetSessionId = sessionId.trim();
+    if (!targetCwd || !targetSessionId) return false;
+
+    let loaded: Message[] | null = null;
+    let targetExists = false;
+    try {
+      const targetFile = await resolveSessionFile(targetCwd, targetSessionId);
+      try { targetExists = (await stat(targetFile)).isFile(); } catch { targetExists = false; }
+      loaded = await loadContext(targetFile);
+      if (targetExists && loaded === null) throw new Error('目标会话历史损坏或无法读取');
+    } catch (error) {
+      setError(error instanceof Error ? error.message : String(error));
+      bump();
+      return false;
+    }
+
+    let systemPrompt: string;
+    try { systemPrompt = await buildBaseSystemPrompt(targetCwd, ALL_TOOLS); }
+    catch (error) {
+      setError(`无法打开工作区：${error instanceof Error ? error.message : String(error)}`);
+      bump();
+      return false;
+    }
+
+    const previousCwd = getWorkingDir();
+    try {
+      await saveContext(historyRef.current, sessionFileFor(previousCwd, activeSessionIdRef.current));
+    } catch {
+      // A damaged old workspace must not trap the user in it.
+    }
+
+    try { await setActiveSession(targetCwd, targetSessionId); }
+    catch (error) {
+      setError(`无法切换 Session：${error instanceof Error ? error.message : String(error)}`);
+      bump();
+      return false;
+    }
+    setWorkingDir(targetCwd);
+    activeSessionIdRef.current = targetSessionId;
+    setActiveSessionId(targetSessionId);
+
+    historyRef.current.length = 0;
+    historyRef.current.push({ role: 'system', content: systemPrompt });
+    promptToolSignatureRef.current = '';
+    if (loaded?.length) {
+      historyRef.current.push(...(loaded[0]?.role === 'system' ? loaded.slice(1) : loaded));
+    }
+
+    const targetWorkspace = await workspaceIndexService.findByPath(targetCwd).catch(() => null);
+    clearFileState(getOrCreateSessionState(sessionStateKey({
+      surface: 'tui',
+      workspaceId: targetWorkspace?.id,
+      cwd: targetWorkspace?.id ? undefined : targetCwd,
+      sessionId: targetSessionId,
+    })).fileReads);
+    resetReactiveCompactState();
+    cancelAllThrottles();
+    setContextUsage(null);
+    setError(null);
+    setInterrupted(false);
+    resetTurnState();
+    setCompactGeneration((generation) => generation + 1);
+    bump();
+    return true;
+  }, [bump, isLoading, cancelAllThrottles, resetTurnState]);
+
+  // history 用 useMemo 托管：version 变化时返回 historyRef.current 的浅拷贝。
+  // 为什么必须 .slice()：runQuery 内部 mutate 同一个数组（push 新消息），如果这里
+  // 返回同一引用，Ink <Static items={history}> 浅比较看不到 prop 变化 → 不 commit
+  // 新增 message → turn 结束 LiveArea 消失后屏幕空白，看起来像"输出被吃掉"。
+  // slice 后元素引用不变，只是数组容器是新的，足够让 Static 检测到 length 增长并 commit。
+  const history = useMemo(() => historyRef.current.slice(), [version]);
+
+  return {
+    history,
+    streamingText,
+    isLoading,
+    error,
+    transientError,
+    interrupted,
+    pluginProgress,
+    compactGeneration,
+    progressStage,
+    reasoningPreview,
+    runningTools,
+    contextUsage,
+    computerUseMode,
+    setComputerUseMode,
+    stopComputerUse,
+    pendingComputerIntervention,
+    resumeComputerUse,
+    cancelComputerUse,
+    activeSessionId,
+    queuedCount,
+    queuedItems,
+    submit,
+    abort,
+    clearHistory,
+    compactNow,
+    runManualAdvisor,
+    switchSession,
+    switchWorkspace,
+    ephemeralLine,
+    pendingAsk,
+    pendingAskSource,
+    pendingAskQueueCount,
+    answerAsk,
+    cancelAsk,
+    setProvider,
+    getCurrentProvider,
+  };
+}
+
+/**
+ * 把一个事件派发到对应的 setState。
+ *
+ * 接受 LoopEvent（框架已识别）或 PluginEvent（插件私有，type 可为任意字符串）。
+ * switch 只匹配 LoopEvent 字面量 type；未识别走 default no-op，等同静默忽略。
+ *
+ * 导出供单测直接调用（避免在 bun:test 里跑 React hook 渲染的复杂度）。
+ */
+export interface HandleEventSetters {
+  setStreamingText: (updater: (prev: string) => string) => void;
+  setError: (e: string | null) => void;
+  setInterrupted: (b: boolean) => void;
+  setPluginProgress: (s: PluginProgressState | null) => void;
+  setCompactGeneration: (updater: (prev: number) => number) => void;
+  setProgressStage: (s: ProgressStage) => void;
+  setReasoningPreview: (updater: (prev: string) => string) => void;
+  setRunningToolsMap: (
+    updater: (prev: Map<string, ToolStatusState>) => Map<string, ToolStatusState>,
+  ) => void;
+  /**
+   * 内核 context_usage 事件的落地 setter（可选——不传时该事件被静默忽略，
+   * 行为等同修复前）。StatusLine 优先用它渲染，缺省才降级回本地估算。
+   */
+  setContextUsage?: (usage: ContextUsageInfo) => void;
+  /** streaming text 节流相关回调。 */
+  appendStreamingDelta: (delta: string) => void;
+  flushStreamingBuffer: () => void;
+  cancelStreamingFlush: () => void;
+  /** reasoning preview 节流（跟 streaming 一样 100ms / 200 字符）。 */
+  appendReasoningDelta: (delta: string) => void;
+  /** assistant_message 落定时取消 reasoning 待 flush buffer。 */
+  cancelReasoningFlush: () => void;
+  /** tool_start / tool_end 的节流 bump（200ms 内合并）。 */
+  scheduleToolBump: () => void;
+  cancelToolBump: () => void;
+  bump: () => void;
+  /**
+   * 把一行工作流进度作为持久暗色行落进 scrollback（复用 ephemeralLine）。
+   * 让 /workflow 执行过程在 TUI 里逐步可见、且出错后仍停留在屏幕上——用户一眼看出停在哪步。
+   * 可选：非工作流场景（测试 / -p）不传也不影响。
+   */
+  emitProgressLine?: (text: string) => void;
+  /**
+   * 暂态错误 setter（喂 LiveArea 黄字，可被覆盖刷新）。
+   * 可选：不传时退化为"工作流步内 llm_error 不再永久红字残留 + 重试聚合"特性关闭，
+   *       非工作流路径行为完全不变（既有单测不传也不受影响）。
+   */
+  setTransientError?: (e: string | null) => void;
+  /**
+   * 暂态错误状态机的跨事件可变上下文（由 useChat 持 ref 注入）。
+   *   - activeStepId：当前正在执行的 workflow step id（null = 不在任何 step 内）
+   *   - pendingLlmError：该 step 内捕获的最近一次 llm_error 文案（暂存待裁决）
+   * handleEvent 同步读写它；可选——不传时降级（同 setTransientError 缺省）。
+   */
+  workflowCtx?: { activeStepId: string | null; pendingLlmError: string | null };
+  /**
+   * 工作流步骤 id → 已插值人话进度名（title）的映射（由 useChat 持 ref 注入）。
+   * workflow_step_start 带 title 时记入，step_end / step_skipped 据 id 回查，
+   * 让 scrollback 的 ▶/✓/✗/⊘ 三种进度行都显示同一个人话名而非 id + 块内序号。
+   * 可选——不传时退化为「end/skipped 显示 id」（既有单测不传也不受影响）。
+   */
+  stepTitles?: Map<string, string>;
+}
+
+export function handleEvent(
+  ev: LoopEvent | PluginEvent,
+  setters: HandleEventSetters,
+): void {
+  // ---- 工作流进度事件（WorkflowEvent，不在 LoopEvent union 里）----
+  // 渲染成持久的暗色行落进 scrollback：跑到哪一步、成功/失败/跳过都看得见，
+  // 且出错后仍停留在屏幕上 —— 解决"工作流执行过程不可见、不知道停在哪"。
+  const wf = ev as {
+    type: string;
+    id?: string;
+    kind?: string;
+    index?: number;
+    total?: number;
+    ok?: boolean;
+    error?: string;
+    reason?: string;
+    name?: string;
+    totalSteps?: number;
+    title?: string;
+  };
+  // 据 id 回查人话进度名：声明了 title 的步走 title，否则回落 id（end/skipped 用）。
+  const titleOrId = (id: string | undefined): string =>
+    (id && setters.stepTitles?.get(id)) || id || '?';
+  switch (wf.type) {
+    case 'workflow_start':
+      setters.emitProgressLine?.(`${figures.step} 工作流 ${wf.name} 开始（共 ${wf.totalSteps} 步）`);
+      // 新工作流开始：清空上一条工作流残留的 title 映射，避免同名步串味。
+      setters.stepTitles?.clear();
+      // 工作流开始：立即刷新 token（可能已积累大量前置对话上下文）
+      setters.bump();
+      return;
+    case 'workflow_step_start':
+      // 声明了 title 的步显示人话名（与状态行一致、不显示块内相对序号——嵌套块
+      // 的 i/total 拼在一起会被误读成"跳步"）；未声明 title 的步保持 legacy 格式。
+      // ⎿ 前缀：step 行挂在「▶ 工作流 x 开始」下的层次连接符（figures.elbow 语汇，
+      // 与工具结果/蜂群树统一）。ephemeral 是尾部追加消息，不触任何既有前缀字节。
+      if (wf.title) {
+        if (wf.id) setters.stepTitles?.set(wf.id, wf.title);
+        setters.emitProgressLine?.(`  ${figures.elbow} ${figures.step} ${wf.title}`);
+      } else {
+        setters.emitProgressLine?.(
+          `  ${figures.elbow} ${figures.step} ${(wf.index ?? 0) + 1}/${wf.total ?? '?'} ${wf.id} (${wf.kind})`,
+        );
+      }
+      // 暂态错误状态机：记下当前正在执行的 step id，进入"该步内的 llm_error 暂态化"窗口。
+      // 进新步先清掉上一步可能残留的暂态错误（上一步已 end、不应跨步显示）。
+      if (setters.workflowCtx) {
+        setters.workflowCtx.activeStepId = wf.id ?? null;
+        setters.workflowCtx.pendingLlmError = null;
+      }
+      setters.setTransientError?.(null);
+      return;
+    case 'workflow_step_end':
+      setters.emitProgressLine?.(
+        `  ${figures.elbow} ${wf.ok ? figures.ok : figures.fail} ${titleOrId(wf.id)}${wf.error ? `：${wf.error}` : ''}`,
+      );
+      // 暂态错误裁决（仅当 end 的是当前活跃步）：
+      //   ok:true  → 重试/恢复成功 → 丢弃 pending llm_error，短暂显示"已恢复"后随刷新消失。
+      //   ok:false → 该步彻底失败 → 把暂态错误提升为永久红字（chat.error，进 scrollback 上方）。
+      if (setters.workflowCtx && setters.workflowCtx.activeStepId === wf.id) {
+        const pending = setters.workflowCtx.pendingLlmError;
+        if (wf.ok) {
+          if (pending) {
+            // 成功收回：留一条灰底"已恢复"提示，下一次状态行刷新自然覆盖消失
+            setters.setTransientError?.(`${figures.ok} ${wf.id} 已恢复（此前 LLM 调用失败已重试成功）`);
+          } else {
+            setters.setTransientError?.(null);
+          }
+        } else {
+          // 彻底失败：暂态升永久红字。优先用 step.error，回落到 pending llm_error。
+          const finalMsg = wf.error ?? pending;
+          if (finalMsg) setters.setError(finalMsg);
+          setters.setTransientError?.(null);
+        }
+        setters.workflowCtx.activeStepId = null;
+        setters.workflowCtx.pendingLlmError = null;
+      }
+      // 步骤完成：强制刷新 token（agent/llm 步骤可能写入大量上下文）
+      setters.bump();
+      return;
+    case 'workflow_step_skipped':
+      setters.emitProgressLine?.(`  ${figures.elbow} ${figures.skip} ${titleOrId(wf.id)}：${wf.reason ?? ''}`);
+      return;
+    case 'workflow_done':
+      setters.emitProgressLine?.(`${figures.ok} 工作流 ${wf.name} 完成`);
+      // 工作流结束：最终刷新（反映完整执行后的上下文量）
+      setters.bump();
+      return;
+  }
+
+  // 收口到 LoopEvent：未识别的 PluginEvent type 走 default no-op
+  const e = ev as LoopEvent;
+  switch (e.type) {
+    case 'user_message_committed':
+      // loop 刚把用户消息 push 进 history。立即 bump → history useMemo 重算 →
+      // <Static> 把用户消息 commit 进 scrollback，第一时间置顶（T-A-O-R）。
+      setters.bump();
+      break;
+    case 'text':
+      setters.appendStreamingDelta(e.delta);
+      break;
+    case 'assistant_message':
+      // history 已被 runQuery 直接 push。先 flush 残留 streaming buffer
+      // 把末段 text 落到 streamingText state（avoid 视觉跳跃），再清空
+      // streamingText —— Static 已 commit 完整 assistant message 接管显示。
+      setters.flushStreamingBuffer();
+      setters.setStreamingText(() => '');
+      // 该段 reasoning 已随 assistant 消息进 history → MessageList 提交进 scrollback（💭 块）。
+      // 清空 Zone B 的 live 预览：① 本轮 streaming 阶段不再回显旧 reasoning；
+      // ② 多轮工具调用时，下一轮 thinking 从空白起步，不残留上一轮思维链。
+      setters.cancelReasoningFlush();
+      setters.setReasoningPreview(() => '');
+      setters.cancelToolBump();
+      setters.setProgressStage('idle');
+      setters.setRunningToolsMap(() => new Map());
+      setters.bump();
+      break;
+    case 'tool_start':
+      // 把工具加入运行集合；并行多个工具时这里会累积。
+      // v2: argsFriendly 是 loop.ts 通过 LoopEvent 扩展字段传过来的人话描述
+      // （如 "Reading src/foo.ts"）。LoopEvent 类型上没声明此字段时通过
+      // (e as { argsFriendly?: string }) 安全读取，缺省 fallback 在 UI 层。
+      setters.setRunningToolsMap((prev) => {
+        const next = new Map(prev);
+        next.set(e.toolCallId, {
+          toolName: e.toolName,
+          argsPreview: e.argsPreview,
+          status: 'running',
+          argsFriendly: (e as { argsFriendly?: string }).argsFriendly,
+        });
+        return next;
+      });
+      // 工具状态切换走 200ms 节流，避免连续 tool_start/end 高频 rerender
+      // 压垮 Ink ANSI 重绘。
+      setters.scheduleToolBump();
+      break;
+    case 'tool_progress':
+      setters.setRunningToolsMap((prev) => {
+        const current = prev.get(e.toolCallId);
+        if (!current) return prev;
+        const next = new Map(prev);
+        next.set(e.toolCallId, { ...current, progress: e.message, progressDetail: e.detail });
+        return next;
+      });
+      setters.scheduleToolBump();
+      break;
+    case 'tool_end':
+      // 仅删除对应 callId 的 entry；其余并行工具继续
+      setters.setRunningToolsMap((prev) => {
+        if (!prev.has(e.toolCallId)) return prev;
+        const next = new Map(prev);
+        next.delete(e.toolCallId);
+        return next;
+      });
+      setters.scheduleToolBump();
+      break;
+    case 'tool_messages_committed':
+      setters.cancelStreamingFlush();
+      setters.setStreamingText(() => '');
+      setters.cancelReasoningFlush();
+      setters.setReasoningPreview(() => '');
+      setters.cancelToolBump();
+      setters.setProgressStage('idle');
+      setters.setRunningToolsMap(() => new Map());
+      setters.bump();
+      break;
+    case 'compact_start':
+      // reactive 自救场景：LLM 失败前可能已经 yield 过部分 text delta，
+      // 压缩前清掉残留 streamingText + 待 flush buffer，避免重发后新文本追加在
+      // 旧 buffer 后面。autoCompact 场景下 streamingText 本来就是空。
+      // 注意：progressStage 由 loop 端的 stage_change 'compacting' 负责切换。
+      setters.cancelStreamingFlush();
+      setters.setStreamingText(() => '');
+      setters.cancelReasoningFlush();
+      setters.setReasoningPreview(() => '');
+      setters.bump();
+      break;
+    case 'compact_done':
+      // 触发 MessageList 内 <Static> remount，丢弃旧消息缓存
+      setters.setCompactGeneration((g) => g + 1);
+      setters.bump();
+      break;
+    case 'harness_diagnostics':
+      // Diagnostics are intentionally local-safe and currently consumed by CLI/stream hosts.
+      break;
+    case 'turn_done':
+      setters.bump();
+      break;
+    case 'interrupted':
+      setters.setInterrupted(true);
+      setters.bump();
+      break;
+    case 'error': {
+      const code = (e as { code?: string }).code;
+      // compact_failed：非致命压缩失败（loop 会继续硬上）。不当红字，作为黄字暂态提示。
+      if (code === 'compact_failed') {
+        setters.setTransientError?.(`压缩失败（已忽略继续）：${e.error}`);
+        setters.bump();
+        break;
+      }
+      // 工作流步执行中的 max_turns 是可恢复截断信号：runner 会在共享 history 上续跑。
+      // 这里不要落入永久红字错误区；顶层非工作流 max_turns 仍保持原有错误展示。
+      if (
+        code === 'max_turns' &&
+        setters.workflowCtx &&
+        setters.workflowCtx.activeStepId !== null &&
+        setters.setTransientError
+      ) {
+        setters.setTransientError('↻ 当前步骤达到轮数预算，正在续跑…');
+        setters.bump();
+        break;
+      }
+      // 工作流步执行中的 llm_error：暂态而非永久红字 ——
+      // 该步通常会被重试，这里只暂存 + 喂 LiveArea 黄字，等 step_end 裁决去留。
+      // 非工作流场景（无活跃 step，或缺 setTransientError 降级）走原有永久红字路径。
+      if (
+        code === 'llm_error' &&
+        setters.workflowCtx &&
+        setters.workflowCtx.activeStepId !== null &&
+        setters.setTransientError
+      ) {
+        setters.workflowCtx.pendingLlmError = e.error;
+        setters.setTransientError(`⚠ LLM 调用失败（重试中）：${e.error}`);
+        setters.bump();
+        break;
+      }
+      // 其余：顶层 halt（无 code）、非工作流 llm_error、aborted 等 → 永久红字。
+      setters.setError(e.error);
+      setters.bump();
+      break;
+    }
+    case 'warning': {
+      // 通用非致命警告。workflow 这类插件已另发 plugin_progress 把同文案镜像到状态行。
+      // 这里额外把"重试 N/M"类警告聚合到 LiveArea 黄色暂态行（覆盖刷新，不 append），
+      // 让用户一眼看出"正在第 N/M 次重试"而非"卡住"。其余 warning 仍 no-op。
+      const msg = (e as { message?: string }).message;
+      if (
+        setters.setTransientError &&
+        typeof msg === 'string' &&
+        msg.includes('重试')
+      ) {
+        setters.setTransientError(`↻ ${msg}`);
+        setters.bump();
+      }
+      break;
+    }
+    case 'plugin_progress':
+      setters.setPluginProgress({
+        pluginId: e.pluginId,
+        current: e.current,
+        max: e.max,
+        message: e.message,
+      });
+      // 重试进度也镜像到暂态行（覆盖刷新）：runner 在重试时发 "↻ 重试 x N/M…"。
+      // 与 warning 分支互为补充（plugin_progress 文案更短，适合状态行下方一行）。
+      if (
+        setters.setTransientError &&
+        typeof e.message === 'string' &&
+        e.message.includes('↻ 重试')
+      ) {
+        setters.setTransientError(e.message);
+      }
+      setters.bump();
+      break;
+    case 'reasoning':
+      // reasoning delta 频率跟 text delta 一样高（60+/秒），不节流的话每个 delta 立即
+      // setReasoningPreview → LiveArea rerender → Ink 重绘扛不住。
+      setters.appendReasoningDelta(e.delta);
+      // 不调用 bump：reasoningPreview 是 LiveArea 单独的 state，history 没变化，
+      // 避免高频 reasoning token 引起 MessageList re-render
+      break;
+    case 'stage_change':
+      // 注意：tool_executing → streaming 切回时不清 runningTools，
+      // 工具集合的清空时机是各自 tool_end
+      setters.setProgressStage(e.stage);
+      break;
+    case 'context_usage':
+      // 内核每轮算出的真实用量（含 tools-schema 开销 + 真实 provider usage）——
+      // 比 StatusLine 本地 useTokenUsage 估算更准，落地后 StatusLine 优先用它。
+      setters.setContextUsage?.({
+        usedTokens: e.usedTokens,
+        contextWindow: e.contextWindow,
+        remainingTokens: e.remainingTokens,
+        compactThreshold: e.compactThreshold,
+        source: e.source,
+      });
+      break;
+    default:
+      // 落到这里 = 插件私有事件（PluginEvent，type 任意字符串），TUI 不识别即忽略。
+      // 这里**故意不**写 console.warn —— Ink 渲染期间写 stdout/stderr 会撕裂终端画面。
+      // 要排查插件 yield 了拼错的事件 type，请用 `minimal-agent -p --verbose`（print.ts 落 stderr）。
+      break;
+  }
+}