@x-otto/tui 0.0.1-alpha.0

package/dist/Tabable-B7PtwING.d.ts

@@ -0,0 +1,3940 @@
+import React from "react";
+import i18next, { i18n } from "i18next";
+import { StoreApi } from "zustand";
+import * as _$_x_otto_interchange0 from "@x-otto/interchange";
+import { A2uiComponent, StopReason, StreamEvent } from "@x-otto/interchange";
+import { TaskItem, TaskItem as TaskItem$1, TurnRecord } from "@x-otto/session-contract";
+
+//#region src/types.d.ts
+interface ToolCall {
+  id: string;
+  type: 'function';
+  function: {
+    name: string;
+    arguments: string;
+  };
+}
+interface TextContent {
+  type: 'text';
+  text: string;
+}
+interface ThinkingContent {
+  type: 'thinking';
+  thinking: string;
+}
+/**
+ * A2UI 声明式 UI 内容块（RFC-105 D6）——渲染投影层直接复用 `@x-otto/interchange` 的
+ * `A2uiComponent`（非手抄副本，见 `messages/a2ui-renderer.ts` 已是同一权威类型的消费方）。
+ * 前向兼容补全（2026-07-12，非修复已发生回归——全仓核实当前无任何生产者产出 a2ui 内容块，
+ * `@x-otto/interchange` 的 `AssistantMessage.content` 类型目前也不含 A2uiContent，详见
+ * `cli/src/view-model-adapter.ts` 头注释的完整分析）：此前 `MessageContent` 联合缺此分支，
+ * 若协议层未来开放该字段，`agentMessagesToChatMessages`（cli 侧 resume 转换）的 switch 会
+ * 落入 default 静默丢弃 a2ui 块——而 `message-lines.ts` 的实时渲染通道已是完整的，会形成
+ * "实时能显示、resume 后消失"的不对称。本次补齐使两条路径提前对齐。
+ */
+interface A2uiContent {
+  type: 'a2ui';
+  version: string;
+  components: A2uiComponent[];
+}
+type MessageContent = TextContent | ThinkingContent | A2uiContent;
+interface AssistantMessage {
+  role: 'assistant';
+  content: MessageContent[];
+  tool_calls?: ToolCall[];
+  id?: string;
+}
+/** user message for TUI display (echo user input). */
+interface UserMessage {
+  role: 'user';
+  content: string;
+  /**
+   * pending 标记——prompt 发出后、模型返回首字节前为 true（灰色 dim 渲染 + ESC 可撤回）。
+   * streaming.start 事件到达后由 clearPendingEcho 转正（置 false）。撤回时整条消息从
+   * 对话流移除（等价于"没发过这条消息"）。
+   */
+  streaming?: boolean;
+  id?: string;
+}
+/** tool call message — ⏺ Name(args) + ⎿ result + ✓/✗，按工具类型分发渲染. */
+interface ToolMessage {
+  role: 'tool';
+  name: string;
+  args?: string;
+  /** 原始参数对象（供 edit diff / write_todos 任务栏 / task_delegate 子代理分发） */
+  argsObj?: Record<string, unknown>;
+  result?: string;
+  isError?: boolean;
+  id?: string;
+}
+/** 回合完成摘要（底部一行：状态 + 工具数 + 耗时 + token 消耗 + 模型）。 */
+interface SummaryMessage {
+  role: 'summary';
+  /**
+   * `incomplete` = 回合停了但 todo 面板仍有未完成项（不再用 `done` 冒充 task-complete）。
+   */
+  status: 'done' | 'error' | 'interrupted' | 'incomplete';
+  toolCount: number;
+  elapsedMs: number;
+  /** 本轮 token 消耗（prompt + completion），显示在主摘要行工具数和耗时之后。 */
+  tokensUsed?: number;
+  /**
+   * RFC-019 M1：本轮缓存命中率（R1 = cacheRead / totalInput，范围 [0,1]）。
+   * `undefined` = 供应商没有相应缓存 API 或本回合无 usage 数据——渲染层据此隐藏该字段，
+   * 不展示可能永远是 0 的误导性数字。
+   */
+  cacheHitRatio?: number;
+  /** 本轮实际使用的模型 id（summary 行末显示；session.model 真源）。 */
+  model?: string;
+  /** `incomplete` 时携带 todo 完成度，渲染 "N/M · K left"。 */
+  tasksDone?: number;
+  tasksTotal?: number;
+  /** 回合完成时刻（epoch ms，cli 侧 reducer 生成）。摘要行末尾灰色渲染 "YYYY-MM-DD HH:MM:SS"。 */
+  completedAt?: number;
+  id?: string;
+}
+/**
+ * P0 (anti-flicker)：流式正文的「已稳定块」增量提交进 <Static>，使动态区高度恒定
+ * （用终端原生 scrollback 承载已稳定块）。lead=该回复首块（渲 ⏺ 圆点），
+ * 续块对齐缩进无圆点，视觉上仍是同一段连续回复。
+ */
+interface StreamChunkMessage {
+  role: 'assistant_stream';
+  text: string;
+  lead?: boolean;
+  id?: string;
+}
+/** 面板/模态信息——仅上下边框，如 /permissions 输出。代码块 JSON 渲染。 */
+interface PaneMessage {
+  role: 'pane';
+  /** 可选标题（上边框下方第一行，bold）。 */
+  title?: string;
+  /** 代码块正文。 */
+  code: string;
+  /** 代码语言（如 json）。 */
+  language?: string;
+  id?: string;
+}
+/**
+ * 压缩边界——对话流内工具调用风格的单行标记（headerLine：`✓ Compact(before → after
+ * 比例条)`），与 Edit/Write/Read 等真实工具调用共用同一视觉语言。自动压缩与手动
+ * /compact 都经 compaction.end 会话事件推此消息进转录，取代瞬时 toast，使压缩在
+ * 对话流中可见（Gap B）。
+ */
+interface CompactBoundaryMessage {
+  role: 'compact_boundary';
+  /** 压缩前/后的 LLM 视图消息数（buildContext 口径）。 */
+  before: number;
+  after: number;
+  id?: string;
+}
+/**
+ * 裁剪边界——本会话首次裁剪(prune)时对话流插一条单行标记「工具输出已裁剪以适应上下文」。
+ * prune 每轮可触发,故 CLI 端只在首次推此消息(去重),之后静默。区别于压缩(离散边界、带前后计数)。
+ */
+interface PruneBoundaryMessage {
+  role: 'prune_boundary';
+  id?: string;
+}
+/**
+ * 历史封顶边界（修复：历史裁剪可观测性，2026-07-12；语义澄清：RFC-159 T6，2026-07-13）——
+ * 会话内存态消息数超上限（默认 2000 条）时对话流插一条单行标记「最早 N 条历史已从内存
+ * 视图移除」。与 prune_boundary 的区别：prune 是 token 维度的工具输出截短（可能每轮触发，
+ * 只提示一次即静默）；本消息是**驻留维度的内存视图裁剪**（@x-otto/session
+ * capStoredHistory / capStoredHistoryByBytes，只操作内存数组）。
+ *
+ * **RFC-321 语义更新**：①主闸已由条数改为字节预算（条数退为结构兜底），故不再是"纯条数
+ * 维度"；②"与模型上下文塑造无关"仅在**无损**路径成立——常态下裁剪只碰已被摘要覆盖的
+ * 死历史（R12 压缩前置保证），但压缩连续失败后的兜底裁剪（`lossy`）会真实削减模型上下文，
+ * 此时该表述不成立，必须按 lossy 分型提示。**RFC-159 起持久层为
+ * append-forever**：默认 SQLite 后端从不因此裁剪删除已持久化的 DB 行，被移出内存视图的
+ * 消息仍完整保留在存储中（`/session export` 可导出全量）；仅已废弃的 `OTTO_SESSION_BLOB=1`
+ * 逃生口后端会整份快照覆写、导致真实数据丢失。携带具体条数（`removedCount`）供用户感知
+ * 内存视图收窄的范围。
+ */
+interface HistoryCappedMessage {
+  role: 'history_capped';
+  /** 本次从内存视图移除的消息条目数（不代表持久化层删除，见上方类型注释）。 */
+  removedCount: number;
+  /** RFC-178 D6：触发来源分型（缺省视为 'count'）——条数上限 / 字节预算 / 内存压力收紧。 */
+  trigger?: 'count' | 'bytes' | 'memory-pressure';
+  /**
+   * RFC-321 R12：本次裁剪是否**有损**——即裁掉的是模型仍在使用、且**没有摘要覆盖**的
+   * 活跃上下文（纯信息丢失），而非常态的"已被摘要替换的死历史"（无损）。
+   *
+   * 仅在"裁剪会触及活跃上下文 + 逃生阀压缩已连续失败达阈值"时为 true。渲染上**优先于
+   * `trigger` 分型**并走 warn 态——其余三种分型的文案都写着"存储中仍完整保留"，对 lossy
+   * 场景会误导用户以为上下文没有损失。
+   */
+  lossy?: boolean;
+  id?: string;
+}
+/**
+ * 写租约被拒边界（2026-07-14 修复）——RFC-159 D3 会话写租约被另一存活进程持有时，
+ * 对话流插一条单行标记「本轮改动未保存」。与 history_capped 同一"持续性数据风险，
+ * 每次真实发生都留痕"的设计（不做"仅首次"去重）——每条标记代表一次真实的落盘失败，
+ * 用户滚动历史时能看清从哪一轮开始丢失，是事后排查数据丢失范围的直接线索。toast
+ * 只在首次弹出详细原因+解决路径（易错过、瞬时），本消息是不会消失的持久痕迹。
+ */
+interface WriteLeaseDeniedMessage {
+  role: 'write_lease_denied';
+  id?: string;
+}
+/**
+ * 写租约恢复边界（2026-07-14 修复）——与 write_lease_denied 对称：此前只读降级的会话
+ * 后续 save 成功获取到租约后插入，与 denied 标记在转录里首尾呼应，用户能精确看到
+ * 只读区间的边界（从哪轮开始丢、到哪轮恢复）。
+ */
+interface WriteLeaseRestoredMessage {
+  role: 'write_lease_restored';
+  id?: string;
+}
+/**
+ * RFC-186 D6：turn 边界暂停已生效——Agent 运行已暂停，排队消息不会自动执行。
+ * 对话流中的持久边界标记，供历史回看时知晓"何时暂停、何时恢复"。
+ */
+interface RunPausedMessage {
+  role: 'run_paused';
+  id?: string;
+  /** 本回合总共执行的工具数 */
+  toolCount?: number;
+}
+/**
+ * RFC-186 D6：暂停已解除，Agent 已恢复运行。
+ */
+interface RunResumedMessage {
+  role: 'run_resumed';
+  id?: string;
+}
+/**
+ * RFC-186 D6：等待中的暂停请求已被取消——仅在 turn 边界到达前有效。
+ */
+interface RunPauseCancelledMessage {
+  role: 'run_pause_cancelled';
+  id?: string;
+}
+/**
+ * RFC-144 M2：lifecycleAsync 工具完成通知——渲染投影层，语义与协议层
+ * `SystemNotificationMessage`（role:'system_notification'）不同（同 lesson_46：手抄
+ * ToolCall/AssistantMessage 是刻意维持的独立渲染形状，非协议层镜像）。单行标记，
+ * 区别于 ToolMessage（同步/普通异步工具的完整 ⏺/⎿ 渲染）——lifecycleAsync 工具的
+ * "启动"事件走 ToolMessage（placeholder tool_result），"完成"事件才走本类型。
+ */
+interface ToolCompletionMessage {
+  role: 'tool_completion';
+  /** 已格式化的通知正文（对应协议层 SystemNotificationMessage.content）。 */
+  content: string;
+  isError?: boolean;
+  id?: string;
+}
+/** 模型切换边界——切换模型时对话流插一条单行标记，使切换在转录里可见。 */
+interface ModelSwitchMessage {
+  role: 'model_switch';
+  /** 已格式化的模型显示串（如 "claude-haiku-4-5-20251001 (200K)"）。 */
+  label: string;
+  id?: string;
+}
+/** 推理投入档切换边界——/effort 切换时对话流插一条单行标记（与 model_switch 同族）。 */
+interface EffortSwitchMessage {
+  role: 'effort_switch';
+  /** 已格式化的档位显示串（如 "High"）。 */
+  label: string;
+  id?: string;
+}
+/**
+ * 模型回退边界——启动时配置的模型不可用(未认证 provider / catalog 未拉),引擎回退到可用模型。
+ * 区别于 model_switch(主动切换、单行标记):这是降级事件、信息量大,渲染为对话流 Dialog
+ * (标题/隔行/configured→active/提示/隔行)。
+ */
+interface ModelFallbackMessage {
+  role: 'model_fallback';
+  /** 配置但不可用的模型 id（如 "anthropic/claude-haiku-4-5-20251001"）。 */
+  configured: string;
+  /** 实际回退生效的模型显示串（如 "deepseek-v4-pro (1M)"）。 */
+  active: string;
+  id?: string;
+}
+/**
+ * 本地命令回显（RFC-233）——斜杠命令的调用与结果作为对话流内一个独立视觉单元渲染，
+ * UI-only：`pushMessage` 只写入 TUI 渲染层的 `messageStore`（纯内存数组），从不落
+ * trace（无 `recorder.record` 调用）、从不进 `AgentMessage[]`/session（无
+ * `session.session.append` 调用）、因此永不作为上下文发给 LLM——与 compact_boundary/
+ * history_capped 等既有 UI-only 类型同源架构保证。
+ *
+ * 取代此前把命令结果伪装成 `pushMessage({role:'assistant'})` 的反模式（8+ 处历史调用点，
+ * 见 model-auth.ts 的迁移注释："此前用 pushMessage 把结果塞进对话转录，既污染对话历史又
+ * 无法承载可操作按钮"）——本类型有独立 role，视觉上明确标记"这是本地命令，非 AI 发言"。
+ *
+ * 使用边界：仅用于**产出信息性内容**的命令（如 /diagnose、/trace-gc --dry-run、
+ * /session unlock 诊断态）；纯确认性、无信息增量的操作（/clear、/rename、/pin 等）
+ * 继续用 `showToast`（瞬态浮层，无需留痕在转录流）。
+ */
+interface CommandEchoMessage {
+  role: 'command_echo';
+  /** 完整命令行回显（如 "/diagnose" 或 "/trace-gc --dry-run"）。 */
+  command: string;
+  /** 结果状态——决定 headerLine 符号与配色（✓ success / ⚠ warning / ✗ error）。缺省 'ok'。 */
+  status?: 'ok' | 'warn' | 'error';
+  /** 单行结果摘要（headerLine argPreview 位置，超宽 truncate-end）。 */
+  summary?: string;
+  /** 多行详情（可选，缩进渲染）。默认不截断——命令回显多为用户主动查询的诊断性内容，
+   *  截断会丢失用户想看的信息；需要限流由调用方自行截断后传入。 */
+  detail?: string;
+  id?: string;
+}
+/** Any message renderable in the TUI REPL. */
+type ChatMessage = AssistantMessage | UserMessage | ToolMessage | SummaryMessage | StreamChunkMessage | PaneMessage | CompactBoundaryMessage | PruneBoundaryMessage | HistoryCappedMessage | ModelSwitchMessage | EffortSwitchMessage | ModelFallbackMessage | ToolCompletionMessage | WriteLeaseDeniedMessage | WriteLeaseRestoredMessage | RunPausedMessage | RunResumedMessage | RunPauseCancelledMessage | CommandEchoMessage;
+/** 通知项（通知中心弹窗 + 状态栏铃铛）。 */
+interface AppNotification {
+  id: number;
+  source: 'job' | 'version' | 'extension' | 'system';
+  level: 'info' | 'warning' | 'error';
+  title: string;
+  message: string;
+  timestamp: number;
+  read: boolean;
+  /** 可选操作（如 "/delegates"、"/extension"，enter 时触发）。 */
+  action?: string;
+}
+/**
+ * RFC-186 D3：暂停浮层数据项。notificationStore.pauseDialog 非 null 时 App.tsx 渲染
+ * PauseDialog 组件。两个阶段：requested（等待 turn 边界）+ active（已暂停）。
+ */
+interface PauseDialogItem {
+  phase: 'requested' | 'active';
+  requestedAt: number;
+  toolCount: number;
+  totalToolCount?: number;
+  onCancel?: () => void;
+  onResume?: () => void;
+  onDismiss?: () => void;
+}
+/** RFC-208：满意度脉冲调查三档评分。 */
+type PulseSurveyRating = 'good' | 'neutral' | 'bad';
+/**
+ * RFC-208 §3.2/§3.4：满意度脉冲调查浮层数据项。notificationStore.pulseSurvey 非 null 时
+ * App.tsx 渲染 PulseSurveyOverlay 组件（Band B 标准形态——同 errorRetry/retry）。
+ * RFC-251 Phase 4f 后，键盘处理由 PulseSurveyOverlay 通过 FocusBus 自管。
+ *
+ * 两阶段：'rating'（评分选择）→ 'comment'（可选意见输入）。阶段切换/选中态/输入内容
+ * 由组件 FocusBus handler 调用 onPulseSurveyChange 驱动更新。
+ */
+interface PulseSurveyItem {
+  phase: 'rating' | 'comment';
+  /** phase='comment' 时已确定；phase='rating' 时为 null。 */
+  rating: PulseSurveyRating | null;
+  /** phase='rating' 时的 Choices 高亮索引（0=good, 1=neutral, 2=bad）。 */
+  selectedIndex: number;
+  /** phase='comment' 时的当前输入内容。 */
+  commentText: string;
+  /** phase='comment' 时的光标偏移（字符索引，同 InputDialog 模式）。 */
+  commentOffset: number;
+  /** 提交（评分 + 可能为空的意见文字）——阶段 2 无论 Enter 还是 Esc 退出都调用。 */
+  onSubmit: (rating: PulseSurveyRating, comment: string | undefined) => void;
+  /** 关闭（Esc 阶段 1 不留痕迹 / 阶段 2 提交后 / forced-upgrade 抢占清除）。 */
+  onClose: () => void;
+}
+//#endregion
+//#region src/theme/colors.d.ts
+/**
+ * colors.ts — 调色板、语义色、色值工具函数。
+ */
+/** 基础调色板。 */
+declare const PALETTE: {
+  readonly ink: "#0D0E11";
+  readonly carbon: "#16181D";
+  readonly white: "#F4F3EF"; /** 品牌三色：远航藏青 Brand Navy / 拾月紫 Accent Purple / 沧溟墨 Ink Gray。 */
+  readonly brandNavy: "#14348C";
+  readonly brandPurple: "#A28EF9";
+  readonly brandInk: "#12152B"; /** 拾月紫亮/暗端。 */
+  readonly purpleBright: "#D1BCFF";
+  readonly purpleDim: "#4F3E8C"; /** 远航藏青"交互焦点"亮端——focusBorder/selection/suggestion/permission 专用。 */
+  readonly navyBright: "#2D59C8";
+  readonly navyDim: "#0F2A73"; /** 注释蓝灰（品牌手册官方灰阶 gray-8）。 */
+  readonly comment: "#9498B8";
+};
+/** 状态五色（取自语法高亮 One-Dark 系）。 */
+declare const STATUS: {
+  readonly success: "#98C379";
+  readonly error: "#E06C75";
+  readonly warning: "#E5C07B";
+  readonly info: "#61AFEF";
+  readonly special: "#C678DD";
+};
+/**
+ * 语义角色 → 具体色。消费方只引语义名，便于整体换肤。
+ * 分组：品牌琥珀 / 文本 / 状态 / 信息蓝 / diff / chrome。
+ */
+interface ThemeColors {
+  /** 品牌字标（Welcome "otto"）。 */
+  brand: string;
+  /** 品牌字标渐变亮端。 */
+  brandShimmer: string;
+  accent: string;
+  /** 呼吸/glow 渐变暗端（hex）。 */
+  accentDim: string;
+  /** 呼吸/glow 渐变亮端。 */
+  accentBright: string;
+  /** 主文本——undefined=终端默认前景（自适应明暗）。 */
+  text: string | undefined;
+  inactive: string;
+  /** 次级文本——比 inactive 深，用于工具名/面板 label 等需要明确可读但非主角的内容。 */
+  secondary: string;
+  /** 预留：比 inactive 更弱的次级文本（当前同 inactive 值；保留供分级弱化）。 */
+  subtle: string;
+  /** 助手回复行首前缀 `>` 的颜色——与用户前缀（inactive 灰）区分。 */
+  replyPrefix: string;
+  success: string;
+  error: string;
+  warning: string;
+  special: string;
+  /** 自动补全/提示/标识符高亮（模型名、/命令、语言标签）。 */
+  suggestion: string;
+  /** 权限请求高亮（工具名/命令）。 */
+  permission: string;
+  /** 行内 `code` 强调色——青/蓝系，区别于 *italic*（斜体）与 **bold**（加粗）；用青系区分 codespan。 */
+  codeText: string;
+  diffAdd: string;
+  diffRemove: string;
+  /** diff 行背景 tint（GitHub 风）。 */
+  diffAddBg: string;
+  diffRemoveBg: string;
+  /** 浮层/面板统一边框色——所有弹层/面板的上下灰线（配合 PANEL_BORDER 形状常量）。 */
+  panelBorder: string;
+  /** 浮层/面板暗底——所有 dialog/toast 的统一背景色（hex）。 */
+  overlayBg: string;
+  /** 内联标签（Tag 组件）的浅色底——比 overlayBg 稍亮的微高亮块，衬托 `[label]`。 */
+  tagBg: string;
+  /** 工具调用 / Thought 块文字色——同 secondary。
+   *  @deprecated 新代码用 THEME.secondary 替代，toolText 保留兼容旧消费方。 */
+  toolText: string;
+  /** 聚焦态高亮——亮蓝色：弹窗标题文字、配置引导提示等（边框已统一为 panelBorder 灰，不再用蓝）。 */
+  focusBorder: string;
+  /** 选中/激活前景——亮蓝色（与 focusBorder 同色系，语义独立）：列表/菜单/树选中行、激活 tab/按钮。 */
+  selection: string;
+}
+/** 固定配色——所有 AA 正常文字 ≥4.5:1。 */
+declare const THEME: ThemeColors;
+//#endregion
+//#region src/theme/figures.d.ts
+/** 符号常量（统一字形）。渲染层引这里，不写裸字形。 */
+declare const DEFAULT_FIGURES: {
+  /** 助手回复行首前缀 ●（实心圆,与用户前缀 `>` 异符异色,强化对话角色区分）。 */readonly bullet: "●"; /** 工具结果折叠角标 ⎿ */
+  readonly toolResult: "⎿"; /** thinking 前缀 ∴ */
+  readonly thinking: "∴"; /** 引用竖线 ▎ */
+  readonly quoteBar: "▎"; /** 用户输入前缀 > */
+  readonly userPrompt: ">"; /** 本地命令回显前缀 ❯ */
+  readonly commandPrompt: "❯"; /** 水平分隔 ─（细线） */
+  readonly hr: "─"; /** 成功/失败标记 */
+  readonly check: "✓";
+  readonly cross: "✗"; /** 任务列表复选框：未勾 ☐ / 已勾 ☑ */
+  readonly checkboxOff: "☐";
+  readonly checkboxOn: "☑"; /** 任务状态：未开始 ○ / 进行中 ◐ / 完成 ● */
+  readonly todoPending: "○";
+  readonly todoActive: "◐";
+  readonly todoDone: "●"; /** 呼吸圆圈：暗（空心）○ / 亮（实心）● */
+  readonly breatheDim: "○";
+  readonly breatheBright: "●"; /** 省略号 */
+  readonly ellipsis: "…"; /** 列表/typeahead 选中行指示箭头 ▶ */
+  readonly pointer: "▶"; /** 开关态：开 ◉ / 关 ○ */
+  readonly toggleOn: "◉";
+  readonly toggleOff: "○"; /** 告警符号 ⚠ */
+  readonly warn: "⚠"; /** 对话选中态保护——用户手动冻结指示 ❄ */
+  readonly frozen: "❄"; /** 等待输入态 ◑ */
+  readonly needsInput: "◑"; /** 状态圆点 ● */
+  readonly statusDot: "●"; /** 条目激活标记 ▸ */
+  readonly itemActive: "▸"; /** 注意/待处理菱形 ◆ */
+  readonly attention: "◆"; /** Sparkline 八阶块字符 */
+  readonly sparkline: "▁▂▃▄▅▆▇█"; /** LineGauge 已完成段 ━ */
+  readonly gaugeFilled: "━"; /** LineGauge 未完成段 ╌ */
+  readonly gaugeRest: "╌"; /** Scrollbar thumb 右半块 ▐ */
+  readonly scrollThumb: "▐"; /** 委托任务识别到的服务前缀 ↕ */
+  readonly service: "↕"; /** 已编辑文件标记 ✎（RFC-309 SummaryStrip） */
+  readonly edited: "✎"; /** 定时/计划任务标记 ◷（RFC-309 SummaryStrip） */
+  readonly scheduled: "◷"; /** 剪贴板信号 ✓（复制成功提示） */
+  readonly clipboard: "✓"; /** LLM 调用阶段箭头：requesting ↑，responding ↓ */
+  readonly requesting: "↑";
+  readonly responding: "↓";
+};
+type FiguresMap = typeof DEFAULT_FIGURES;
+/** 符号常量表（固定值，不再支持运行时覆盖）。 */
+declare const FIGURES: FiguresMap;
+//#endregion
+//#region src/theme/borders.d.ts
+/**
+ * borders.ts — 面板/弹层边框形态常量。
+ */
+/**
+ * 内联面板统一边框形状——仅上下两条单线（无左右）。
+ *
+ * **单一真源**：所有内联 UI 元素写 `<Box {...PANEL_BORDER} borderColor={THEME.panelBorder}>`。
+ */
+declare const PANEL_BORDER: {
+  readonly borderStyle: "single";
+  readonly borderTop: true;
+  readonly borderBottom: true;
+  readonly borderLeft: false;
+  readonly borderRight: false;
+};
+/**
+ * DIALOG_BORDER — 所有弹层/对话框的统一边框形态（四边圆角 `╭─╮`）。
+ *
+ * **单一真源**：所有经 DialogFrame 呈现的弹层写此常量。历史上曾有 `BORDER_VARIANTS`
+ * 三档（hard/nav/overlay）按界面层级分不同形态（RFC-183 D1），但 2026-07-22 commit
+ * 9466cb7c9「统一所有弹层为四边圆角」有意将三档收敛为同一形态；RFC-266 D1 据此删除
+ * 无差异的 variant API，收敛为本单一常量（语义分层由 focus-registry band 承载，边框层
+ * 不再重复编码）。将来若需按层级再分化边框，以新 RFC 重新设计，不保留投机性 API。
+ */
+declare const DIALOG_BORDER: {
+  readonly borderStyle: "round";
+  readonly borderTop: true;
+  readonly borderBottom: true;
+  readonly borderLeft: true;
+  readonly borderRight: true;
+};
+//#endregion
+//#region src/theme/spacing.d.ts
+/**
+ * spacing.ts — 间距 scale 与布局裕量常量。
+ */
+/**
+ * SPACING — 间距 scale（对标 Radix Themes 9 级 spacing，缩减为终端字符网格 4 级）。
+ *
+ * **单一真源**：全部 margin/padding/gap 系 Ink Box props 引用本常量，不再写裸数字。
+ */
+declare const SPACING: {
+  readonly none: 0;
+  readonly tight: 1;
+  readonly section: 2;
+  readonly loose: 4;
+};
+/**
+ * LAYOUT — 宽度裕量常量。
+ */
+declare const LAYOUT: {
+  /** 通用内容裕量——最常见的 `columns - 4` 场景。 */readonly contentInset: 4; /** 边框内裕量——已在 DialogFrame/PANEL_BORDER 内部的场景（`columns - 2`）。 */
+  readonly borderInset: 2;
+};
+//#endregion
+//#region src/theme/theme-registry.d.ts
+type ThemeAppearance = 'dark' | 'light';
+type ThemeResolveMode = ThemeAppearance | 'system';
+type ThemePresetSource = {
+  kind: 'builtin';
+} | {
+  kind: 'extension';
+  extensionId: string;
+};
+interface MarkdownThemeOverrides {
+  heading1?: keyof ThemeColors;
+  heading2?: keyof ThemeColors;
+  headingWeak?: keyof ThemeColors;
+  listMarker?: keyof ThemeColors;
+  listMarkerMuted?: keyof ThemeColors;
+  quoteBar?: keyof ThemeColors;
+  quoteText?: keyof ThemeColors;
+  link?: keyof ThemeColors;
+  inlineCode?: keyof ThemeColors;
+  codeFence?: keyof ThemeColors;
+  tableHeader?: keyof ThemeColors;
+  tableDivider?: keyof ThemeColors;
+  listIndent?: 2 | 3;
+  listMarkers?: readonly [string, string, string, string];
+  codeBlockDivider?: 'hr' | 'none';
+}
+interface ThemePresetInput {
+  /** Builtin may pass id directly; extension ids are generated as `${extensionId}/${localId}`. */
+  id?: string;
+  localId?: string;
+  label: string;
+  appearance: ThemeAppearance;
+  colors: ThemeColors;
+  markdown?: MarkdownThemeOverrides;
+  meta?: {
+    author?: string;
+    description?: string;
+    version?: string;
+  };
+}
+interface ThemePreset extends Omit<ThemePresetInput, 'id'> {
+  id: string;
+  source: ThemePresetSource;
+}
+interface ThemePresetSelection {
+  dark?: string;
+  light?: string;
+}
+declare class ThemeRegistry {
+  private readonly presets;
+  private readonly presetSourceKeys;
+  register(source: ThemePresetSource, input: ThemePresetInput): ThemePreset;
+  unregisterBySource(source: ThemePresetSource): number;
+  get(id: string): ThemePreset | undefined;
+  list(): ThemePreset[];
+  resolve(mode: ThemeResolveMode, systemAppearance?: ThemeAppearance, selection?: ThemePresetSelection): ThemePreset;
+}
+declare function createBuiltinThemeRegistry(): ThemeRegistry;
+//#endregion
+//#region src/i18n/types/index.d.ts
+/**
+ * i18n-types.ts — 共享基础类型（Risk / Lang / LangMode）。
+ *
+ * 从 i18n.ts 提取，供所有子接口文件无循环依赖地引用。
+ */
+type Risk = 'low' | 'medium' | 'high';
+type Lang = 'en' | 'zh';
+type LangMode = Lang | 'auto';
+//#endregion
+//#region src/i18n/setup.d.ts
+type Locale = 'en' | 'zh';
+/** 初始化 i18next（幂等：已初始化则切 locale）。lng 由调用方按环境/配置解析后传入。 */
+declare function initI18n(lng: Locale): i18n;
+/**
+ * 全局翻译函数（= i18next.t，类型安全）。组件与非组件统一用它，避免 hook 放置约束。
+ * 运行时切语言经 changeLanguage + 全量重渲染刷新（P6 接线）。
+ */
+declare const t: typeof i18next.t;
+//#endregion
+//#region src/i18n/index.d.ts
+/** 自动检测语言：读环境 LC_ALL/LC_MESSAGES/LANG，含 zh 即中文，否则英文。 */
+declare function detectLanguage(): Lang;
+//#endregion
+//#region src/stores/store.d.ts
+interface Store<T> {
+  getState: () => T;
+  setState: (update: Partial<T> | ((prev: T) => Partial<T>)) => void;
+  subscribe: (listener: () => void) => () => void;
+  /** 底层 zustand StoreApi，供需要 zustand 原生能力的高级消费方（devtools 等）使用；
+   *  常规消费走上面三个方法即可。 */
+  readonly zustand: StoreApi<T>;
+}
+declare function useAppState<T, R>(store: Store<T>, selector: (state: T) => R): R;
+//#endregion
+//#region src/stores/perf-store.d.ts
+/** 内存快照——字段对齐 `@x-otto/coding` 的 `MemorySample`（不直接 import 跨包类型，
+ *  tui 包不依赖 coding 包，由 cli 层组装时结构对齐即可，见 RFC-116 D2）。 */
+interface PerfMemorySnapshot {
+  level: 'healthy' | 'warning' | 'critical';
+  heapUsed: number;
+  heapSizeLimit: number;
+  usedPct: number;
+}
+/** 渲染健康度快照——字段对齐 `NotifyStats`（M2 里程碑填充，M1 阶段为 undefined）。 */
+interface PerfNotifySnapshot {
+  coalescedCalls: number;
+  coalescedFires: number;
+  immediateCalls: number;
+  flushFires: number;
+  coalesceRatio: number;
+  alert: 'healthy' | 'warning';
+}
+/**
+ * 单个插件采集器的结果。
+ * RFC-118 小修（S10）：原 RFC-116 D2 的手动镜像定义已收口——类型本体上移
+ * `@x-otto/interchange`（coding 生产侧同源），此处别名保持 tui 内既有消费方命名兼容。
+ */
+type PluginMetricResult = _$_x_otto_interchange0.PluginPerfMetricResult;
+interface PerfPaneState {
+  memory: PerfMemorySnapshot | undefined;
+  /** 内存采样历史（RFC-183 M4：PerfPane sparkline 趋势，环形窗口 ≤32 点，heapUsed 字节）。 */
+  memoryHistory: number[];
+  /** M1 阶段恒为 undefined（渲染区占位）；M2 起由 CLI 层喂入真实值。 */
+  notify: PerfNotifySnapshot | undefined;
+  /**
+   * RFC-116 M3：footer 常驻指示器的实时分级——与 `memory`（面板手动刷新快照）解耦，
+   * 因为 footer 需要"异常时才浮现、健康时零宽度"的常驻感知（不依赖用户是否打开过
+   * `/perf` 面板），由 `MemoryGovernor.onLevelChange` 回调驱动（每次分级变化都推送，
+   * 含恢复到 healthy 的方向）。初始为 'healthy'（保守假设，避免启动瞬间误报）。
+   */
+  indicatorLevel: 'healthy' | 'warning' | 'critical';
+  /**
+   * RFC-116 M5：插件贡献的性能采集器结果——手动刷新时喂入（对齐 D7 手动刷新决策，
+   * 不做自动轮询）。空数组 = 无插件贡献采集器或本次刷新尚未获取，两者在渲染层
+   * 不做区分（均不显示该区块），因为区分"无贡献"与"未刷新"对用户价值不大。
+   */
+  pluginMetrics: PluginMetricResult[];
+}
+interface PerfStore {
+  store: Store<PerfPaneState>;
+  /** /clear 会话重置——全字段回初始值（indicatorLevel 回 'healthy' 保守假设）。
+   *  RFC-256 收尾：面板可见性已改由 Router 栈单一真源派生（isInStack('/pane/perf')），
+   *  store 不再持 `open` 布尔——原 toggle() 已删除。 */
+  reset(): void;
+  /** CLI 喂入最新内存快照（面板手动刷新）。 */
+  setMemory(snapshot: PerfMemorySnapshot): void;
+  /** CLI 喂入最新渲染健康度快照（M2 起使用；M1 阶段调用方不传，保持 undefined）。 */
+  setNotify(snapshot: PerfNotifySnapshot): void;
+  /** CLI 喂入 footer 常驻指示器的最新分级（`MemoryGovernor.onLevelChange` 驱动）。 */
+  setIndicatorLevel(level: 'healthy' | 'warning' | 'critical'): void;
+  /** CLI 喂入最新插件采集器结果（手动刷新触发）。 */
+  setPluginMetrics(results: PluginMetricResult[]): void;
+}
+//#endregion
+//#region src/components/DataList.d.ts
+type DataListTone = 'success' | 'warning' | 'error' | 'muted' | 'secondary';
+interface DataListRow {
+  label: string;
+  value: string;
+  /** value 侧的可选强调色；不传走默认前景色。 */
+  tone?: DataListTone;
+}
+type DataListEntry = {
+  kind: 'group';
+  title: string;
+} | ({
+  kind: 'row';
+} & DataListRow) | {
+  kind: 'blank';
+} /** 无 label/value 配对的纯文本行（如底部提示语），不参与组内标签对齐计算。 */ | {
+  kind: 'text';
+  value: string;
+  tone?: DataListTone;
+};
+interface DataListProps {
+  entries: readonly DataListEntry[];
+}
+declare function DataList({
+  entries
+}: DataListProps): React.ReactElement;
+//#endregion
+//#region src/keybindings/types.d.ts
+/**
+ * RFC-114 D1：按键谓词，对应 Ink `Key` 类型的同名字段，做逐字段相等比较。
+ *
+ * RFC-174 M1：新增 upArrow/downArrow 字段（控件导航层 registry 需要），
+ * 对既有 KEY_BINDINGS 零影响（所有现有记录这两个字段均为 undefined，
+ * 谓词匹配规则将 undefined 视为通配——向后兼容）。
+ */
+type KeyBindingPredicate = {
+  ctrl?: boolean;
+  shift?: boolean;
+  meta?: boolean; /** 单字符按键，如 'n'、'y'、'g'、'k'、'j'。 */
+  input?: string;
+  /**
+   * 修饰键外的命名按键——仅含全局命令实际使用的值。
+   * Ink `Key` 的 leftArrow/rightArrow 等继续控件级处理。
+   */
+  key?: 'tab' | 'escape' | 'return'; /** 上箭头（RFC-174 M1 控件导航层）。 */
+  upArrow?: boolean; /** 下箭头（RFC-174 M1 控件导航层）。 */
+  downArrow?: boolean;
+};
+//#endregion
+//#region src/dialogs/OnboardingDialog.d.ts
+/** 引导两步的产出（cli 侧据此落盘；未设置的字段=用户跳过）。 */
+interface OnboardingResult {
+  nickname?: string;
+  language?: 'en' | 'zh' | 'auto';
+}
+//#endregion
+//#region src/stores/context-store.d.ts
+/** 系统提示分段摘要（从 BudgetView + 静态 section 元数据推导）。 */
+interface SystemSectionRow {
+  label: string;
+  lane: 'stable' | 'volatile';
+  estimatedTokens: number;
+}
+/** 对话回合摘要（CLI 从 trace 事件提取）。 */
+interface ConversationTurnRow {
+  turnIndex: number;
+  role: 'user' | 'assistant';
+  messageCount: number;
+  estimatedTokens: number;
+  /** 该回合已被压缩替换为摘要（compaction.reactive 标记）。 */
+  compacted: boolean;
+  /** 该回合因 max_tokens 被截断（lifecycle:turn.truncated）。 */
+  truncated: boolean;
+  /** 该回合已从上下文中移出（lifecycle:memory.prune）。 */
+  pruned: boolean;
+}
+interface ContextDetailPaneState {
+  /** 面板开关态。 */
+  open: boolean;
+  /** 对话回合行（CLI 喂入，按 turnIndex 升序）。 */
+  conversationTurns: ConversationTurnRow[];
+  /** 系统提示分段（从 BudgetView.overheadTokens + 静态 section 表推导）。 */
+  systemSections: SystemSectionRow[];
+  /** 模型名（从 BudgetView 提取，供面板标题展示）。 */
+  modelName: string;
+  /** 上下文窗口总大小（token）。 */
+  contextWindow: number;
+  /** 上下文占用百分比。 */
+  contextPercent: number;
+  /** 全部已用 token */
+  totalUsed: number;
+  /** 可用 token */
+  free: number;
+}
+interface ContextStore {
+  store: Store<ContextDetailPaneState>;
+  /** 开/关面板；open 省略 = 翻转。 */
+  toggle(open?: boolean): void;
+  /** /clear 会话重置——全字段回初始值。 */
+  reset(): void;
+  /** CLI 追加一条回合行。 */
+  addTurn(row: ConversationTurnRow): void;
+  /** CLI 批量更新回合标记（compacted/truncated/pruned）。 */
+  markTurns(patch: {
+    turnIndex: number;
+  } & Partial<ConversationTurnRow>): void;
+  /** CLI 喂入 budget + 静态 section 元数据 → 推导 systemSections。 */
+  setBudget(budget: {
+    modelName: string;
+    contextWindow: number;
+    contextPercent: number;
+    totalUsed: number;
+    free: number;
+    overheadTokens: number;
+  }): void;
+}
+//#endregion
+//#region src/dialogs/ErrorRetryDialog.d.ts
+/** 硬额度限流类型（原定义于已并入本卡片的 RateLimitCountdown.tsx，RFC-147 M3 D-C4 迁移）。 */
+type RateLimitType = 'five_hour' | 'seven_day' | 'seven_day_opus' | 'seven_day_sonnet' | 'seven_day_overage_included';
+type ErrorRetryActionKind = 'retryNow' | 'login' | 'switchModel';
+interface ErrorRetryAction {
+  kind: ErrorRetryActionKind;
+  label: string;
+  run: () => void;
+}
+interface ErrorRetryItem {
+  /** 触发本次错误的原因（单行截断展示）。 */
+  reason: string;
+  /** 当前 per-prompt 重投次数（1-based；0 表示首次失败尚未重试过）。 */
+  attempt: number;
+  /** per-prompt 最大重试配额（默认 5）。 */
+  max: number;
+  /** 'auto'=30s×5 自动重投；'resetsAt'=倒计时到官方 resetsAt；'manual'=无自动倒计时。 */
+  mode: 'auto' | 'resetsAt' | 'manual';
+  /** mode='resetsAt' 时为 Unix 秒时间戳；其余 mode 忽略。 */
+  resetsAt?: number;
+  /** mode='resetsAt'|'manual'（硬额度场景）时的限流类型标签；其余 mode 忽略。 */
+  limitType?: RateLimitType;
+  /** 按钮列表（不含取消——取消固定追加在末尾，见渲染逻辑）。至少 1 个动作按钮。 */
+  actions: ErrorRetryAction[];
+  /** 当前聚焦按钮索引（含隐式追加的取消按钮，取值范围 0..actions.length）。 */
+  focusIndex: number;
+  /** 倒计时到期回调（mode='auto'|'resetsAt' 时触发一次）。 */
+  onExpired: () => void;
+  /** 取消（Esc 或选中取消按钮触发）。 */
+  onCancel: () => void;
+  /** 终态：per-prompt 配额已耗尽（mode='auto' 且 attempt>=max 仍失败）——不再自动倒计时，
+   *  保留手动重试（重置计数）与取消。 */
+  exhausted: boolean;
+  /** RFC-153 D6：错误来源插件 id（`CodedError.pluginSource`/`ToolResult.pluginSource` 透传）；
+   *  undefined 表示非插件来源（内建能力），不展示来源行（规则 8：只标记来源，不改变重试策略）。 */
+  pluginSource?: string;
+  /** RFC-230：mode='auto' 自动倒计时秒数（默认 30）。随 item 一起流转（`showErrorRetry` 的
+   *  `...item` 展开自动透传新增字段），不单独开辟传递路径。 */
+  intervalSeconds?: number;
+}
+//#endregion
+//#region src/panes/EditedFilesPane.d.ts
+interface EditedFileEntry {
+  /** 文件路径（相对项目根或绝对） */
+  path: string;
+  /** 操作类型 */
+  operation: 'edit' | 'write' | 'delete';
+  /** 旧内容（edit/delete 时有值） */
+  oldContent?: string;
+  /** 新内容（edit/write 时有值） */
+  newContent?: string;
+  /** 新增行数 */
+  addedLines: number;
+  /** 删除行数 */
+  removedLines: number;
+  /** 工具调用时间戳（epoch ms） */
+  timestamp: number;
+  /** 关联的 turn ID（可选） */
+  turnId?: string;
+  /** 工具调用 ID（去重用） */
+  toolCallId?: string;
+}
+//#endregion
+//#region src/status-bar/background-task-indicator-logic.d.ts
+/**
+ * RFC-223：委托后台进程的服务协议分类——从运行时输出识别，best-effort。
+ * 结构上与 `@x-otto/tools`/`@x-otto/runtime` 的同名类型一致（不 import，tui 零运行时
+ * 依赖 tools/runtime，靠结构化类型满足契约，同既有 tools↔runtime 解耦策略）。
+ */
+type ServiceProtocol = 'http' | 'ws' | 'tcp';
+/** RFC-223：从后台进程运行时输出识别到的服务信息（url 优先，退化到纯端口）。 */
+interface DetectedService {
+  url?: string;
+  port?: number;
+  protocol: ServiceProtocol;
+}
+type BackgroundTaskType = 'process' | 'agent-session';
+/** 来源：user = 用户 /delegate 委派；main = 主对话（模型）起的；plugin = 插件经
+ *  agent.dispatch 自主发起（RFC-287 D2）。分类上与 main 同归 'subagent'（非人手委派）。 */
+type BackgroundTaskOrigin = 'user' | 'main' | 'plugin';
+type AgentJobUiStatus = 'running' | 'needs_input' | 'ready' | 'applied' | 'failed' | 'canceled';
+interface BackgroundTaskSummary {
+  id: string;
+  /** 进程=command；agent-session=作业 title。 */
+  command: string;
+  status: 'running' | 'exited' | 'killed' | 'failed';
+  /** kind（缺省 process，向后兼容既有进程喂入）。 */
+  type?: BackgroundTaskType;
+  /** 来源（缺省 user）：面板分组用——用户委派 vs 主对话委派。 */
+  origin?: BackgroundTaskOrigin;
+  port?: number;
+  startedAt: number;
+  exitCode?: number;
+  /** 作业状态（真源；type==='agent-session' 时用它而非 status）。 */
+  agentStatus?: AgentJobUiStatus;
+  /** 完整的委托提示词（供 SubagentsPane / 详情面板展示）。 */
+  prompt?: string;
+  /** ready 后的 diff 概况，如 "+5/-2"。 */
+  diffStat?: string;
+  /** 当前 turn 序号。 */
+  turnIndex?: number;
+  /** 累积工具调用数。 */
+  toolUseCount?: number;
+  /** 累积文件编辑次数（子代理编辑的 pod 信号）。 */
+  filesEdited?: number;
+  /** 累积输出 token。 */
+  tokenCount?: number;
+  /** 分配模型 id（供 SubagentsPane 面板显示）。 */
+  model?: string;
+  /** 模型决策层(explicit/slot/category/default/fallback)——面板显示「为何用这个模型」。 */
+  modelDecidedBy?: string;
+  /** 当前活动（thinking / responding / using <tool> / awaiting approval …）。 */
+  lastActivity?: string;
+  /** stall 级别（派生：none/warn/stalled）——驱动行图标变色 + 诊断块。 */
+  stall?: 'none' | 'warn' | 'stalled';
+  /** 距上次事件毫秒（stall 时显示 "idle 4s"）。 */
+  idleMs?: number;
+  /** 当前等待类别：model_io / approval / process。 */
+  blockedOn?: string;
+  /** 父 abort 能否中断它（false 时诊断块显式标注 NOT abortable）。 */
+  abortable?: boolean;
+  /** RFC-223：运行时输出识别到的服务信息（仅 process 类任务有意义）。 */
+  detectedService?: DetectedService;
+}
+/** 观测快照里 cli 喂面板用到的字段（与 runtime AgentObservationSnapshot 同形子集；tui 不依赖 runtime）。 */
+interface ObservationLike {
+  id: string;
+  agentName: string;
+  origin: 'user' | 'main';
+  status: string;
+  /** 完整的委托提示词（供 SubagentsPane / 详情面板展示）。 */
+  prompt?: string;
+  startedAt: number;
+  turnIndex?: number;
+  toolUseCount?: number;
+  /** 累积文件编辑次数（子代理编辑的 pod 信号；≥1 时面板末行追加 "~N files"）。 */
+  filesEdited?: number;
+  tokenCount?: number;
+  /** 分配模型 id（供 SubagentsPane 面板显示）。 */
+  model?: string;
+  /** 模型决策层。 */
+  modelDecidedBy?: string;
+  lastActivity?: string;
+  stall?: 'none' | 'warn' | 'stalled';
+  idleMs?: number;
+  blockedOn?: string;
+  abortable?: boolean;
+}
+/**
+ * BackgroundTaskSummary → 持久化 SubagentEntry.status 的归一映射。
+ * agentStatus（agent-session 真源）优先；缺省回退通用 status。供 cli persistSubagents 写盘。
+ */
+declare function subagentEntryStatus(t: Pick<BackgroundTaskSummary, 'agentStatus' | 'status'>): 'running' | 'done' | 'error' | 'killed';
+/**
+ * 持久化 SubagentEntry.status → 恢复行的 BackgroundTaskSummary 字段（反向）。
+ * status=agent-session 真源 agentStatus（驱动行图标）+ 通用 status。供 tui addSubagent 重建面板行。
+ */
+declare function subagentRestoreFields(status: 'running' | 'done' | 'error' | 'killed'): {
+  agentStatus: AgentJobUiStatus;
+  status: BackgroundTaskSummary['status'];
+};
+/** 观测 → 面板行的 live 字段子集（用于富化已有 detached /job 行）。 */
+declare function observationLiveFields(o: ObservationLike): Partial<BackgroundTaskSummary>;
+/** 观测 → 完整面板行（用于 swarm 成员等不在 jobRegistry 的被观测 agent）。 */
+declare function observationRow(o: ObservationLike): BackgroundTaskSummary;
+/**
+ * 视图B：turn timeline 文本行（形如「turn 6 ✓ 3 tools 2.1s」/「▸ turn 7 … 8s」）。
+ * 已完成轮 `✓`，当前轮 `▸ … `（用 now 算 in-flight 时长）。空 → []。
+ */
+declare function formatTurnTimeline(turns: TurnRecord[], now: number): string[];
+/**
+ * 诊断块的**纯文本**行（供 o-键详情视图顶部，复用 DelegateOutputPane 不碰 App.tsx）。
+ * 非被观测 agent → []。`! ` 前缀标 warn 行（stalled / 不可中止）。
+ */
+declare function formatAgentDiagnosticsText(t: BackgroundTaskSummary, now: number): string[];
+//#endregion
+//#region src/panes/DelegatesPane.d.ts
+/** 单个后台进程的实时输出视图（cli 每 ~500ms 读 logPath 末尾回喂 text）。 */
+interface DelegateOutputView {
+  id: string;
+  command: string;
+  status: BackgroundTaskSummary['status'];
+  /** 完整的委托提示词（设置即启用 Prompt tab）。 */
+  prompt?: string;
+  /** 已废弃——子代理对话流改用 messages 渲染（同 SubagentContextView），不再走纯文本 text。 */
+  text: string;
+  /** 被观测子代理的诊断摘要（activity/blocked/tokens/abortable + turn timeline，纯文本）。
+   *  真实用户反馈修复：此前本字段撑起一个独占的 "Response" tab，但子代理内容以 markdown
+   *  对话为主，诊断信息本身没有独立可读性——已改为渲在 header 里的一行摘要，不占 tab。 */
+  responseText?: string;
+  /** 结构化转录消息——渲染时走 renderMessageLines（同 SubagentContextView 的对话流）。 */
+  messages?: ChatMessage[];
+  /** 运行中 in-flight 流式文本（接在 messages 末尾，跟随最新输出）。 */
+  streamText?: string;
+  /** 作业产出的统一 diff（ready/applied 的 agent-session 作业）——设置即启用 Diff tab，
+   *  人审 diff 的唯一 TUI 入口（此前 diff 全程不可见，只有 +N/-M stat）。 */
+  diff?: string;
+}
+//#endregion
+//#region src/input/shell-complete-backend.d.ts
+/**
+ * shell-complete-backend.ts — Shell completion backends.
+ * BashBackend (compgen), ZshBackend (_comps), BuiltinBackend (PATH+fs).
+ * RFC-121: user input via env vars, never string interpolation.
+ */
+interface CompletionItem {
+  /** 补全候选值 */
+  value: string;
+  /** 显示标签（可选，与 value 不同时用于展示） */
+  display?: string;
+  /** 候选类型 */
+  type: 'command' | 'file' | 'dir' | 'arg';
+  /** 描述（可选） */
+  description?: string;
+}
+interface CompletedWord {
+  /** 单词原始文本 */
+  word: string;
+  /** 在原始输入中的偏移 */
+  offset: number;
+}
+interface CompletionRequest {
+  /** 要补全的文本（不含 ! 前缀） */
+  text: string;
+  /** 光标在 text 中的偏移 */
+  cursorOffset: number;
+  /** 解析后的单词数组（供 COMP_WORDS/COMP_CWORD 使用） */
+  words: CompletedWord[];
+  /** 光标所在的单词索引（COMP_CWORD） */
+  wordIndex: number;
+  /** 工作目录 */
+  cwd: string;
+  /** 取消信号 */
+  signal?: AbortSignal;
+}
+interface ShellBackend {
+  /** 后端名称（用于诊断日志） */
+  name: string;
+  /** 获取命令列表（首词补全），prefix 为空时返回全部 */
+  getCommands(prefix: string): Promise<CompletionItem[]>;
+  /** 获取参数补全（后续词补全） */
+  getCompletions(request: CompletionRequest): Promise<CompletionItem[]>;
+  /** 销毁后端（清理资源） */
+  destroy(): void;
+}
+//#endregion
+//#region src/input/shell-complete.d.ts
+/**
+ * shell-complete.ts — Shell tab completion for ! (bash) mode.
+ * Sources: command (PATH) / path (filesystem). Tab: common-prefix then cycle. Zero React dependency.
+ */
+interface ShellCompletion {
+  completions: string[];
+  selectedIndex: number;
+  prefix: string;
+  wordStart: number;
+  visible: boolean;
+  commonPrefixApplied: boolean;
+}
+//#endregion
+//#region src/input/shell-complete-orchestrator.d.ts
+interface CompleterOptions {
+  /** 命令补全超时（ms） */
+  commandTimeoutMs: number;
+  /** 参数补全超时（ms） */
+  argTimeoutMs: number;
+  /** 最大结果数 */
+  maxResults: number;
+  /** 命令列表缓存 TTL（ms，默认 30s） */
+  commandCacheTtlMs: number;
+  /** 参数补全缓存 TTL（ms，默认 30s，含 CWD 信息） */
+  argCacheTtlMs: number;
+  /** 缓存最大条目数 */
+  maxCacheEntries: number;
+}
+declare class Completer {
+  private backend;
+  private opts;
+  private commandCache;
+  /** 参数补全缓存：键 = `${cwd}|${command}`，TTL 30s */
+  private argCache;
+  private abortController;
+  constructor(backend: ShellBackend | null, opts?: Partial<CompleterOptions>);
+  /**
+   * 取消当前正在进行的补全查询。
+   */
+  cancelPending(): void;
+  /**
+   * 获取命令列表（首词补全），异步。
+   *
+   * 策略：
+   *   1. 会话级缓存（TTL 30s，不依赖 CWD，因 PATH 全局不变）
+   *   2. shell 后端查询（超时 commandTimeoutMs）
+   *   3. PATH 扫描兜底（instant）
+   *   4. 合并去重后返回
+   */
+  getCommands(prefix: string): Promise<string[]>;
+  /**
+   * 发起异步参数补全查询。
+   */
+  getCompletions(request: {
+    text: string;
+    cursorOffset: number;
+    cwd: string;
+  }): Promise<string[]>;
+  /**
+   * 设置参数补全缓存，超限时淘汰最旧条目。
+   */
+  private setArgCache;
+  /**
+   * 桥接方法：从字符串补全结果创建 ShellCompletion 状态。
+   */
+  makeShellCompletion(completions: string[], wordStart: number, prefix: string): ShellCompletion;
+  /**
+   * 销毁编排器及后端。
+   */
+  destroy(): void;
+}
+//#endregion
+//#region src/input/paste-refs.d.ts
+/**
+ * paste-refs.ts — Paste reference folding/expansion + memory lifecycle (M48-06, RFC-198).
+ * LRU with pressure-graded capacity (healthy=1x, warning=½, critical=¼).
+ * nextId monotonic (never reset). findMissingIds before expandAll.
+ * Known: image refs not managed (RFC-181 gap).
+ *
+ * RFC-338：新增跨重启持久化支持（hydrate/toSnapshot）。本文件仍是**纯内存 + 纯函数**，
+ * 不碰文件系统——落盘由宿主（cli）经 `@x-otto/persistence` 完成，本层只负责
+ * 「内存状态 ⇄ 可序列化快照」的转换。
+ */
+/**
+ * 压力分级来源的自描述接口——不直接 import `ResidencyGovernor` 类，只声明所需的最小读取面
+ * （`currentLevel`），避免 `paste-refs.ts` 对 `@x-otto/runtime` 产生编译期类型依赖（tui 包当前
+ * 零 `@x-otto/runtime` 依赖）。`App` 侧的 `ResidencyGovernor` 实例满足这个接口的结构化子集，
+ * 传递时无需显式转换（TypeScript 结构化类型天然兼容）。
+ */
+interface PasteStoreResidencySource {
+  readonly currentLevel: 'healthy' | 'warning' | 'critical';
+}
+interface CreatePasteStoreOptions {
+  /** 压力分级来源；省略时退化为固定的 healthy 上限（测试/无 governor 场景兼容）。 */
+  residencyGovernor?: PasteStoreResidencySource;
+}
+/**
+ * RFC-338：可序列化的粘贴条目。
+ *
+ * 结构与 `@x-otto/persistence` 的 `PasteStateEntry` **刻意保持一致但不 import**——
+ * tui 包零 `@x-otto/persistence` 依赖（同 `PasteStoreResidencySource` 对
+ * `@x-otto/runtime` 的既有处理方式），靠 TypeScript 结构化类型在 cli 装配层天然兼容。
+ */
+interface PasteSnapshotEntry {
+  id: number;
+  text: string;
+  byteLength: number;
+}
+/**
+ * RFC-338：粘贴缓存快照（内存 ⇄ 持久化的交换格式）。
+ *
+ * `entries` 的**数组顺序即 LRU 顺序**（头 = 最久未访问，尾 = 最近访问），
+ * 与内存 `Map` 的插入顺序一一对应——不引入独立 seq/时间戳字段（D2：那会与
+ * Map 顺序构成双真源；且时间源违反引擎确定性重放约束）。
+ */
+interface PasteSnapshot {
+  entries: PasteSnapshotEntry[];
+  /** id 分配游标，单调不回退（重要事项规则 1，红线）。 */
+  nextId: number;
+}
+interface PasteStore {
+  foldIfLarge(text: string): string;
+  /** 展开占位符为原文。missingIds 非空即存在无法解析的引用——调用方应先用
+   *  `findMissingIds` 做提交前校验，不要依赖本方法的 missingIds 做阻断判定（本方法会
+   *  同时产生副作用：续命或释放，不是纯查询）。 */
+  expandAll(text: string): {
+    text: string;
+    missingIds: number[];
+  };
+  /** 提交前的纯校验（不消费、不改变 LRU 状态），返回文本中引用但当前不可解析的 id 列表。 */
+  findMissingIds(text: string): number[];
+  /**
+   * RFC-212 D3：只读查看单条 paste 内容（不消费、不改变 LRU 访问顺序/字节计数/驱逐计数），
+   * 供 chip 内容查看器展示原文——与 `expandAll` 的关键差异：`expandAll` 会触发续命
+   * （healthy 分级）或释放（warning/critical 分级）的副作用，查看操作不应影响该副作用时序
+   * （用户只是看一眼，不代表"已经真正使用/提交"这次引用）。id 不存在（已失效）返回 undefined。
+   */
+  peek(id: number): string | undefined;
+  truncateIfNeeded(text: string): string;
+  addImageRef(): string;
+  /**
+   * RFC-338 D5：一次提交完成后的收尾。**取代此前无条件的 `clear()`**。
+   *
+   * - healthy：保留全部条目（仅按容量做 LRU 裁剪）——这正是本 RFC 的核心价值：
+   *   用户从输入历史 recall 出旧命令后，其中的 chip 仍能展开。
+   * - warning/critical：沿用「用完即释放」。注意 `expandAll` 在这两档已经删过命中的
+   *   条目，本方法**不重复扣减**，只清理那些本次提交引用过、但 expandAll 未覆盖的残留。
+   *
+   * @param submittedText 本次提交的原始文本（含 `[@paste:#N]` 占位符）
+   */
+  afterSubmit(submittedText: string): void;
+  /**
+   * RFC-338：导出可持久化快照。数组顺序 = 当前 LRU 顺序。
+   *
+   * 落盘字节上限（`OTTO_PASTE_STORE_PERSIST_MAX_BYTES`，默认 8MB）在此处生效——
+   * 从**最久未访问端**（数组头）开始裁剪，保证留下的是最可能被 recall 的近期条目。
+   * 这不改变内存状态，只影响写盘内容（内存仍受 32MB 闸约束）。
+   */
+  toSnapshot(): PasteSnapshot;
+  /**
+   * RFC-338：从持久化快照恢复（整份替换当前状态）。
+   *
+   * `nextId` 取 `max(快照声明值, 全部 id + 1, 当前 nextId)` —— 三者取最大，
+   * 保证游标既不回退也不与既存 id 碰撞（重要事项规则 1，红线）。
+   * 快照中的非法条目被静默丢弃（fail-open），但**丢弃不会让出 id 空间**。
+   */
+  hydrate(snapshot: PasteSnapshot | null | undefined): void;
+  readonly size: number;
+  /** 当前 store 占用字节数（LRU 容量判据的另一维度）。 */
+  readonly bytesUsed: number;
+  /** 累计驱逐次数（LRU 超限淘汰 + 内存紧张分级用完即释放，两者都计数）。纯计数器，不驱动
+   *  任何行为，供未来 `/perf` 面板或调试场景观测。 */
+  readonly evictionCount: number;
+  /**
+   * 清空全部映射。
+   *
+   * RFC-338 D5 起**不再挂在提交路径上**（提交走 `afterSubmit`），仅供显式清理场景
+   * （如 `/clear`）使用。`nextId` 不复位——见实现处注释。
+   */
+  clear(): void;
+}
+declare function createPasteStore(options?: CreatePasteStoreOptions): PasteStore;
+//#endregion
+//#region src/input/use-typeahead.d.ts
+/**
+ * useTypeahead.ts — Slash command completion engine (CC useTypeahead port, M48-07).
+ *
+ * / slash command completion only. Pure functions, zero React dependency.
+ * RFC-036 T036-11: @ file/agent/MCP dead code removed — replaced by SigilPane + registry.search().
+ *
+ * Usage:
+ *   const reg = createCommandRegistry([{name:'help', description:'Show help'}])
+ *   const sug = getCommandSuggestions('/he', 3, reg)
+ *   if (sug) renderList(sug.suggestions, sug.selectedIndex)
+ */
+interface CommandEntry {
+  name: string;
+  description?: string;
+  disabled?: boolean;
+  /**
+   * 命令别名（如 `auth` 的 `['login']`）——**参与 typeahead 模糊匹配**。
+   *
+   * 缺失此字段曾导致：`/login` 在斜杠面板零结果（用户报告"login 没有入口"），
+   * 且 `/log` 只匹配到 `logout`（退出登录）——想登录的人看到的唯一选项是退出。
+   * CLI 侧 `registerBuiltinTuiCommands` 一直在传 `aliases`（目录条目 `auth` 确有
+   * `aliases: ['login']`），但本接口此前无该字段，值被静默丢弃，从未参与匹配。
+   */
+  aliases?: string[];
+  /**
+   * 排序键（RFC-158 D5）：缺省用 `name`。用于展示名与排序键需要解耦的场景——如
+   * `/pin`⇄`/unpin` 动态展示名，排序始终固定用原始指令 id（`'pin'`），避免展示名
+   * 切换导致列表位置跳动。
+   */
+  sortKey?: string;
+}
+type SlashNavigateAction = 'prev' | 'next' | 'accept' | 'dismiss';
+interface TypeaheadState {
+  suggestions: CommandEntry[];
+  selectedIndex: number;
+  prefix: string;
+  /** 边框候选列表是否可见；slash 有匹配时自动 true（RFC-128 D3）。 */
+  panelOpen: boolean;
+  /**
+   * 命中「命令参数补全」（`registerArgumentSuggester`）时的宿主命令名，如 `'model'`。
+   * 未设置（`undefined`）表示 `suggestions` 是「命令名候选」（`/mo` → `/model`）。
+   * 消费方（PromptInput 边框列表 accept 分支）据此区分调用 `applyArgCompletion`
+   * （只替换参数段）还是 `applySlashCompletion`（替换命令名段）——回归修复：此前恒调用
+   * 后者，导致接受参数建议时把命令名整段误替换成参数值（如 `/model gpt` 选中 `gpt-4`
+   * 后变成 `/gpt-4 gpt`）。
+   */
+  argCommand?: string;
+}
+/**
+ * Argument suggestion provider for specific commands.
+ * Maps command name → function that suggests arguments.
+ */
+type ArgumentSuggester = (prefix: string, maxResults?: number) => Array<{
+  name: string;
+  description?: string;
+}>;
+interface CommandRegistry {
+  register(commands: CommandEntry[]): void;
+  search(prefix: string, maxResults?: number): CommandEntry[];
+  getAll(): readonly CommandEntry[];
+  find(name: string): CommandEntry | undefined;
+  registerArgumentSuggester(command: string, suggester: ArgumentSuggester): void;
+  getArgumentSuggester(command: string): ArgumentSuggester | undefined;
+}
+declare function createCommandRegistry(initial?: CommandEntry[]): CommandRegistry;
+/**
+ * 仅行首触发 `/` typeahead（trimStart 后以 / 开头）。
+ * 旧正则 `(?:^|\s)` 太宽：`ls /tmp`、`cd /usr` 都会误弹面板。
+ * 新正则 `/^\/(.*)$/` 允许空格（用于 `/command arg` 参数补全）。
+ */
+declare function extractSlashPrefix(input: string, cursorOffset: number): string | null;
+declare function getCommandSuggestions(input: string, cursorOffset: number, registry: CommandRegistry): TypeaheadState | null;
+declare function navigateSuggestions(state: TypeaheadState, action: SlashNavigateAction): TypeaheadState | 'accept' | 'dismiss';
+declare function applySlashCompletion(input: string, cursorOffset: number, command: CommandEntry): {
+  text: string;
+  offset: number;
+};
+//#endregion
+//#region src/panes/sigil-types.d.ts
+/**
+ * RFC-036 T036-07：TUI 侧 sigil 类型（本地结构镜像）。
+ *
+ * R3：TUI 是叶子包，零 `@x-otto/*` 运行时依赖。故不 import `@x-otto/coding`，
+ * 而是在此定义与 coding `SigilEntry`/`PluginInputRegistry` **结构同构**的本地类型。
+ * App.tsx 接线点处 coding 的具体 registry 经 props 流入——结构类型使其可赋值。
+ *
+ * 若 coding 侧契约变更，需同步此镜像（两处保持一致是 R3 解耦的成本）。
+ */
+type SigilPrefix = '#' | '@';
+type SigilKind = 'hashtag' | 'file' | 'person' | 'agent' | 'skill' | 'mcp' | 'plugin' | 'model' | 'resource' | 'shortcut';
+/** 面板条目：label 展示 / value 替换，严格分离（R2）。 */
+interface SigilEntry {
+  label: string;
+  value: string;
+  description?: string;
+  kind: SigilKind;
+  source?: string;
+  /** 预览内容（@file 等）：非空时 Enter 先弹出预览弹窗再确认插入。TUI 消费方可选。 */
+  preview?: string;
+  /** RFC-210 D2：resolve 引用（结构镜像，语义见 @x-otto/interchange input.ts 同名字段）。 */
+  resolverId?: string;
+}
+/** TUI 仅消费 search——渲染数据源。其余生命周期方法 TUI 不触及。 */
+interface SigilSearchRegistry {
+  search(query: string, sigil?: SigilPrefix, maxResults?: number): SigilEntry[];
+  /**
+   * 异步搜索：含 @file 等动态 provider 结果（RFC-044 M044-07）。
+   * 可选——registry 未实现时 SigilPane 退回同步 search。
+   */
+  searchAsync?(query: string, sigil?: SigilPrefix, maxResults?: number): Promise<SigilEntry[]>;
+}
+//#endregion
+//#region src/input/PromptInput.d.ts
+type SubmitMode = 'send' | 'bash' | 'bash_async' | 'memory';
+interface PromptInputProps {
+  columns?: number;
+  /** RFC-306 后修复（光标锚定）：终端总行数——用于把光标锚定到输入行（Ink 输出原点相对坐标）。 */
+  rows?: number;
+  placeholder?: string;
+  /** RFC-294 D7：真禁用（强制升级/确认框占据交互）→ 塌缩为单行提示。 */
+  disabled?: boolean;
+  /** RFC-300 优化：回看态（滚动回看中）——保留完整外观（不塌缩），仅不注册键盘
+   *  （滚动独占）且不渲染光标。区别于 disabled：disabled 塌缩，reviewing 不塌缩。 */
+  reviewing?: boolean;
+  /** 空闲提示卡片是否可见——卡片在输入框上方占 3+ 行且有 480ms 动画，
+   *  出现时物理光标隐藏（光标残影防护）。 */
+  idleTipVisible?: boolean;
+  /** 斜杠命令表（typeahead 数据源） */
+  commands?: CommandEntry[];
+  /** force=true 表示修饰键+Enter（Alt/Ctrl/Cmd）——上层据此映射为 followUp/排队;plain Enter→steer/send。 */
+  /**
+   * 提交回调。
+   *
+   * 返回 `'rejected'` 表示宿主**拒绝了本次提交**（如 FTUE 未就绪、无可用模型），
+   * 此时输入框**保留原文**，用户修完配置可直接重发（RFC-326 §6.7：
+   * "未发出的 prompt 保留在输入框"）。返回 void/其它值一律按已受理处理并清空。
+   *
+   * 背景：此前 `setText('')` 在 onSubmit 之后**无条件**执行——CLI 侧虽然在
+   * `!modelReady` 时 early-return 且注释写着"输入不回显、不丢失"，但那只保证
+   * 不进对话流，输入框其实已经被清掉了。用户敲完一整段 prompt、按下回车、
+   * 看到一个转瞬即逝的 toast，然后**文字没了**。
+   */
+  onSubmit?: (text: string, mode: SubmitMode, force?: boolean) => void | 'rejected';
+  onInterrupt?: () => void;
+  onClear?: () => void;
+  /** 输入为空时的 Esc 委托（App:关 inspector→删队列→中断）。输入有内容时 Esc 先逐行清空,不调此回调——
+   *  以此让 Esc 单一归属,消除"输入有内容+队列有内容时按 Esc 同帧既清输入又删队列"的双吃 bug。 */
+  onEscape?: () => void;
+  /** Ctrl+R 打开 history 模式的 SigilPane（宿主处理面板状态/路由）。 */
+  onHistorySearch?: () => void;
+  /** history 面板是否在场（宿主传入）——在场时关闭 typeahead 建议，避免与面板叠显。 */
+  historySearchOpen?: boolean;
+  /** toast 通知回调（ctrl+s 存草稿 / ctrl+x 外部编辑） */
+  onToast?: (title: string, content: string) => void;
+  /** ctrl+s 保存当前输入为一条自动命名的草稿（随会话快照持久化）。 */
+  onDraftSave?: (text: string) => void;
+  /** 用户快捷键覆盖表（settings `keybinding_overrides`）——`save-draft` 键位据此解析。 */
+  keybindingOverrides?: Record<string, KeyBindingPredicate>;
+  /** 大段粘贴确认回调（>800 字符或 >20 行时弹确认对话框）。
+   *  text 为原始粘贴内容（供对话框预览）；handlers.confirm() 折叠为 #paste_N 插入；
+   *  handlers.cancel() 丢弃。 */
+  onPasteConfirm?: (text: string, handlers: {
+    confirm: () => void;
+    cancel: () => void;
+  }) => void;
+  /** 是否启用 #/@ sigil 检测（无 pluginInput 数据源时 false，行为完全旁路）。 */
+  sigilEnabled?: boolean;
+  /**
+   * RFC-212 D3：光标停靠在"面板来源" chip（file/agent/skill/mcp/person/plugin/model
+   * 等）上按 Enter——重新拉起 @ 面板做范围替换。与 `onSigilTrigger`（正常 @ 输入触发）
+   * 是独立回调，不复用其 handlers（chip 重开的替换区间是 `[chipRange.start,
+   * chipRange.end)`，与 `onSigilTrigger` 依赖的 anchor/cursor 触发上下文语义不同）。
+   */
+  onChipReopen?: (kind: string, chipRange: {
+    start: number;
+    end: number;
+  }, handlers: {
+    select: (entry: SigilEntry) => void;
+    cancel: () => void;
+  }) => void;
+  /**
+   * RFC-212 D3：光标停靠在 paste chip 上按 Enter——打开只读内容查看器。pasteId 已失效
+   * （不在 PasteStore 中）时不调用本回调，由 PromptInput 自行 toast 提示。
+   */
+  onChipViewPaste?: (label: string, content: string) => void;
+  /** shell-complete 的工作目录（路径补全的依据），由 App 传入 welcome.cwd。 */
+  cwd?: string;
+  /** /history 面板选中后回填文本——PromptInput 在 mount 时将 fill() 写入此 ref。
+   *  App 持有此 ref，用户选择历史条目后调用 ref.current.fill(text)。 */
+  historyInsertRef?: {
+    current: {
+      fill: (text: string) => void;
+      append?: (text: string) => void;
+    } | null;
+  };
+  /**
+   * RFC-338 D7a：粘贴缓存的树外桥接句柄（宿主 cli 用于 hydrate/落盘）。
+   * 与 `historyInsertRef` 同款命令式 ref 模式——paste store 是本组件的 useRef
+   * 单例，且组件不感知 sessionId，会话切换时的重绑必须由 cli 侧驱动。
+   */
+  pasteBridgeRef?: {
+    current: {
+      hydrate: (snapshot: PasteSnapshot | null | undefined) => void;
+      export: () => PasteSnapshot;
+    } | null;
+  };
+  /** 持久化输入历史初始条目（从磁盘恢复）。PromptInput 用此初始化 InputHistory。 */
+  initialHistory?: readonly string[];
+  /** RFC-129：外部 shell 历史（只读，供 ghost/Ctrl+R；不落盘）。 */
+  externalHistoryCommands?: readonly string[];
+  /** 每次 push 新历史条目时回调——携带完整 entries 列表供外层落盘。 */
+  onHistoryPush?: (entries: readonly string[]) => void;
+  /**
+   * 历史导航态变化回调——会话头 logo 旁 HUD 据此展示「N/total + 当前条目」。
+   * 导航中传 { position, total, entry }，回到底部/开始打新字/提交后传 null。
+   */
+  onHistoryNavChange?: (nav: {
+    position: number;
+    total: number;
+    entry: string;
+  } | null) => void;
+  /** RFC-198 §4.4：PasteStore 内存压力分级来源只读视图（省略时固定 healthy 上限）。 */
+  residencyGovernor?: PasteStoreResidencySource;
+  /** 检测到 #/@ 触发时上报 App（App 持有面板状态/焦点，F-focus）。
+   *  handlers.select(entry) / handlers.cancel(deleteSigil) 由 App 在选择/关闭时回调，
+   *  PromptInput 据此把替换/删除应用到文本（走 applyText 'completion' 来源刷新 mode，D7/R7）。 */
+  onSigilTrigger?: (sigil: SigilPrefix, query: string, handlers: {
+    select: (entry: SigilEntry) => void;
+    cancel: (deleteSigil: boolean) => void;
+  }) => void;
+  /**
+   * RFC-215 D3：sigil 触发条件被编辑破坏（decision.action === 'close'）时通知宿主关面板。
+   * 不传时退化为 suppress 行为（面板关闭交由既有失焦/Esc 机制，向后兼容不回归）。
+   */
+  onSigilClose?: () => void;
+  /** 向外暴露命令 registry（用于在 TUI 初始化后注册参数补全函数）。 */
+  registryRef?: {
+    current: ReturnType<typeof createCommandRegistry> | null;
+  };
+  /** Shell 补全编排器引用。由外层创建并注入。 */
+  shellBackendRef?: {
+    current: Completer | null;
+  };
+}
+declare function PromptInput({
+  columns,
+  placeholder,
+  disabled,
+  reviewing,
+  commands,
+  onSubmit,
+  onInterrupt,
+  onClear,
+  onEscape,
+  onHistorySearch,
+  historySearchOpen,
+  sigilEnabled,
+  onSigilTrigger,
+  onSigilClose,
+  onChipReopen,
+  onChipViewPaste,
+  onToast,
+  onDraftSave,
+  keybindingOverrides,
+  onPasteConfirm,
+  cwd,
+  historyInsertRef,
+  pasteBridgeRef,
+  initialHistory,
+  externalHistoryCommands,
+  onHistoryPush,
+  onHistoryNavChange,
+  residencyGovernor,
+  registryRef,
+  shellBackendRef
+}: PromptInputProps): React.ReactElement;
+//#endregion
+//#region src/input/QueuedCommands.d.ts
+interface QueuedItem {
+  text: string;
+  mode: SubmitMode;
+}
+interface QueuedCommandsProps {
+  items: QueuedItem[];
+}
+declare function QueuedCommands({
+  items
+}: QueuedCommandsProps): React.ReactElement | null;
+//#endregion
+//#region src/panes/DraftPane.d.ts
+interface DraftItemView$1 {
+  id: string;
+  name: string;
+  text: string;
+  savedAt: number;
+}
+//#endregion
+//#region src/status-bar/provider-usage-badge.d.ts
+type ProviderUsageLimitType = 'five_hour' | 'seven_day' | 'seven_day_opus' | 'seven_day_sonnet' | 'seven_day_overage_included';
+/** 'unknown' = 无订阅配额数据（OpenAI 等无 unified 头族的 provider，RFC-118 S11）——中性态，不判额度充足也不报警。 */
+type ProviderUsageStatusKind = 'allowed' | 'allowed_warning' | 'rejected' | 'unknown';
+interface ProviderUsageBadgeItem {
+  status: ProviderUsageStatusKind;
+  limitType?: ProviderUsageLimitType;
+  resetsAt?: number;
+  usedPercent?: number;
+  overageStatus?: ProviderUsageStatusKind;
+  overageResetsAt?: number;
+}
+/** 完整人类可读标签（/usage 命令用，区别于状态栏紧凑短标签）。未知类型兜底原始字符串。 */
+declare function formatProviderUsageLimitTypeFull(limitType: ProviderUsageLimitType | string): string;
+/**
+ * Overage 判定——标准额度已耗尽但其额外用量池仍可用。
+ * 逻辑：`status === 'rejected' && overage in (allowed, warning)`。
+ */
+declare function isUsingOverage(status: ProviderUsageStatusKind, overageStatus?: ProviderUsageStatusKind): boolean;
+//#endregion
+//#region src/services/status-widget-registry.d.ts
+/**
+ * 宿主组装的只读快照。`providerUsage` 用 TUI 内部 `ProviderUsageBadgeItem`（App.tsx 状态栏
+ * 实际持有的类型，`overageStatus` 含 `'unknown'` 中性态，见 RFC-118 S11）而非 `@x-otto/interchange
+ * ProviderUsageSnapshot`（更严格的协议层类型，不含 `'unknown'`）——两者跨包各自定义同构类型是
+ * 既有纹理（同 `RegisteredRenderer` 先例），`@x-otto/coding status-widget-loader.ts` 侧的
+ * `StatusWidgetContext` 是装载模块的文档性类型镜像，实际快照组装与 render 调用只发生在本侧。
+ */
+interface StatusWidgetContext {
+  nowMs: number;
+  model: string;
+  providerUsage: ProviderUsageBadgeItem | null;
+  columns: number;
+}
+type StatusWidgetColorKind = 'warning' | 'inactive';
+type PluginStatusWidgetRenderFn = (ctx: StatusWidgetContext) => {
+  text: string;
+  color?: StatusWidgetColorKind;
+} | null;
+interface RegisteredStatusWidget {
+  id: string;
+  pluginId: string;
+  render: PluginStatusWidgetRenderFn;
+  tickMs?: number;
+  order?: number;
+}
+//#endregion
+//#region src/views/recovery-card.d.ts
+/**
+ * recovery-card.ts — RFC-326 §6.7：Home 常驻恢复卡的纯呈现逻辑。
+ *
+ * 问题：用户 Esc 退出向导后，Home 上**没有任何**"还差什么"的线索——配置状态只
+ * 活在一个转瞬即逝的 toast 里，之后就只能靠用户记住 `/setup`。§6.7 要求把它变成
+ * 常驻可见的事实：每个未就绪阶段给一个明确的主行动。
+ *
+ * 本模块只做「阶段 → 文案键 + 单一 CTA」的映射与窄屏降级，不碰渲染：
+ *  - 纯函数，便于穷举每个阶段的产物；
+ *  - 文案返回 **i18n key** 而非成品字符串，避免纯逻辑层耦合语言资源。
+ *
+ * 设计约束（§6.7 明文）：
+ *  - **单一 CTA**：每张卡只给一个推荐动作，不并列 `/login` `/model` `/plugin`
+ *    让新用户猜（§4 原则 4）。
+ *  - **常态 ≤4 行**、窄屏（<80 列）降为两行标题+CTA。
+ *  - 卡片走文档流，不得占用 ChatInputArea / StatusBar 的稳定行位——这条由渲染层
+ *    保证（放在 Home 主区域内），本模块只负责把行数压在预算内。
+ */
+/** 与 `FtueStage` 同构；此处独立声明避免 tui 反向依赖 cli 的 ftue 模块。 */
+type RecoveryStage = 'provider' | 'authentication' | 'model' | 'ready' | 'first-prompt';
+//#endregion
+//#region src/views/Home.d.ts
+interface SessionListItem {
+  id: string;
+  title: string;
+  status: 'busy' | 'idle' | 'needs-input' | 'idle-cold';
+  lastActivityAt: string;
+  isCurrent: boolean;
+  isPinned: boolean;
+  isArchived: boolean;
+  isReadOnly: boolean;
+}
+interface HomeProps {
+  version?: string;
+  /** build ID（git rev-list --count HEAD），非空时在版本号后显示 "(build N)"。 */
+  buildId?: number;
+  cwd?: string;
+  width?: number;
+  /** 用户昵称（settings.nickname）：织入问候语并以 accent 高亮；缺省回退无名问候。 */
+  nickname?: string;
+  /** 更新提示：非空时在 version 行后展示新版通知。 */
+  updateAvailable?: {
+    latest: string;
+    current: string;
+    newer: boolean;
+    forced: boolean;
+  };
+  /** 天气信息（可选，未实现时留空）。 */
+  weather?: {
+    condition: string;
+    temp: number;
+    location: string;
+  };
+  /**
+   * RFC-326 §6.7：FTUE 阶段——非 ready 时在首屏渲染常驻恢复卡。
+   * 省略/ready 时不渲染，老用户零干扰。
+   */
+  ftueStage?: RecoveryStage;
+  /** RFC-234 P2-b：多会话列表。未提供时不渲染。 */
+  sessionList?: readonly SessionListItem[];
+  /** RFC-234 P2-b：选择会话回调。 */
+  onSessionSelect?: (id: string) => void;
+  /** 当前语言检测 */
+  lang?: string;
+  /** RFC-345 D6：影子会话——在首屏横幅下方展示保证/不保证清单。 */
+  shadow?: boolean;
+}
+/**
+ * 品牌像素字标 "otto" 及其扫光动画抽取至 `./Wordmark`，Home 首屏与对话中
+ * SessionHeader 共用（避免像素行/扫光逻辑双份维护）。
+ */
+declare function Home({
+  version,
+  buildId,
+  cwd,
+  width,
+  nickname,
+  updateAvailable,
+  weather: _weather,
+  ftueStage,
+  shadow
+}: HomeProps): React.ReactElement;
+//#endregion
+//#region src/stores/task-store.d.ts
+interface TaskState {
+  tasks: TaskItem$1[];
+  tasksTitle: string | undefined;
+  turnBoundaries: number[];
+  editedFiles: EditedFileEntry[];
+  backgroundTasks: BackgroundTaskSummary[];
+  subagentsAccum: Map<string, BackgroundTaskSummary>;
+  scheduleTasks: Array<{
+    id: string;
+    name: string;
+    cronExpression: string;
+    enabled: boolean;
+    recurring: boolean;
+    nextFireAt: number;
+    lastFiredAt?: number;
+  }>;
+  drafts: DraftItemView$1[];
+  /** 最近复制字符数（SignalBar 剪贴板信号，TTL 后归零） */
+  clipboardChars: number;
+  /** 最近一次复制的正文（供剪贴板面板/查看器展示；单条覆盖式，随每次复制更新）。
+   *  与 clipboardChars 的 TTL 无关——TTL 只控制 SignalBar 那行提示显隐，正文保留到
+   *  下次复制或会话结束（否则 12s 后就没有查看入口了）。 */
+  clipboardText: string;
+  /** 复制写入两路通道均失败（SignalBar 显示失败兜底信号，非 Toast）。TTL 后归零。 */
+  clipboardFailed: boolean;
+  queued: QueuedItem[];
+  pendingPermission: unknown | null;
+  backgroundOutput: DelegateOutputView | null;
+  subagentContext: unknown | null;
+  forcedUpgrade: string | null;
+  modelName: string;
+  pluginStatusItems: readonly {
+    id: string;
+    text: string;
+  }[];
+  /** 状态栏代码式徽标（RFC-184 D2/D3）——`setPluginRegistrations` 同步写入，同 pluginStatusItems 语义。 */
+  statusWidgets: readonly RegisteredStatusWidget[];
+  needsSetup: boolean;
+  permissionMode: string;
+  commands: unknown[];
+  paneOwnsViewportFlag: boolean;
+  /** 刚 echo、模型尚未返回首字节的 user 消息——ESC 击键据此走『撤回』而非 abort 对话框。 */
+  pendingEcho: {
+    text: string;
+    mode: string;
+  } | null;
+  /** RFC-337 D3：运行中追加（steer）但尚未被模型消费的消息（延迟 commit，live 区渲染）。
+   *  ESC 撤回最近一条（列表末尾）；被模型 drain 时经 steer.consumed 转正 commit 到 scrollback。 */
+  pendingSteers: readonly {
+    text: string;
+    id: string;
+  }[];
+  /** shellExecution + shellTimer 成对出现，不进 store（timer 是副作用句柄）。 */
+  shellExecution: unknown;
+  /** 最近 @ 到的条目（MRU，最多 5 条，最近在前）；SigilPane「最近使用」分组数据源。
+   *  持久化真源在 cli 侧 settings.recent_mentions（.otto/config.json 项目层），
+   *  经 setRecentMentions() 单向下发到本 store（cli→tui，与 setDrafts 同款模式）。 */
+  recentMentions: SigilEntry[];
+  /** RFC-234 P2-b：Home 多会话列表。 */
+  sessionList: readonly SessionListItem[];
+  /** 当前会话标题（对话中 SessionHeader 展示）——cli 侧 resolveSessionTitle 单一真源下推。 */
+  sessionTitle: string;
+}
+interface TaskStore {
+  store: Store<TaskState>;
+  reset(): void;
+  /**
+   * 注入渲染触发器（RFC-333 M2-A）。store 创建早于 notify（main.ts:192 vs :304），
+   * 故沿用 perfStore.setNotify 的 post-creation 注入范式。未注入时 actions 内 notify 为 no-op
+   * （供无渲染环境的纯 store 单测）。
+   */
+  setNotify(notify: () => void): void;
+  /**
+   * 注入副作用钩子（RFC-335 T335-07 前置 P0a）。原 TuiHandle 残留 setter 是"字段 setter
+   * + 副作用"混合体（如 setForcedUpgrade = setState + syncOverlayRoute + notify）——
+   * 直接变纯 action 会丢副作用。setEffects 把副作用接入口子化注入（仿 setNotify 的
+   * post-creation 注入范式），store 层不 import 树外 ref（routerRef/plugin registry），
+   * 由 main.ts 接线处把闭包函数传进来。未注入时副作用为 no-op（对齐 notify 防过早调用）。
+   */
+  setEffects(effects: TaskStoreEffects): void;
+  /**
+   * store action 出口（RFC-333 M2-A）。封装原 TuiHandle setter 的派生逻辑（sort/merge/
+   * Map 累积）+ notify，使写入方（现为 TuiHandle setter 转发，M2-B 后为 cli 直调、
+   * T335-07 后为 service-client adapter）调 action 即获得一致语义，store 成为唯一写入汇聚点。
+   */
+  actions: TaskActions;
+}
+/**
+ * taskStore 副作用接入口子。注入方（main.ts）把闭包函数绑进来——这些闭包内部可
+ * `getRouterRef()` 取真 router / `registerPlugin` 调中央 registry，故接口不把 router/
+ * registry 作为参数传递（保持 store 层不引用任何树外类型）。这是"store 不依赖树外
+ * 全局"的类型层体现（P0c 先导）。
+ */
+interface TaskStoreEffects {
+  /** 强制升级 overlay 开/关（router 副作用）；true→开、false→关。注入方内部 syncOverlayRoute。 */
+  syncForcedUpgradeRoute?(open: boolean): void;
+  /** 后台输出视图 follow：true→navigate '/pane/delegates/output'；false 且正停该 path→goBack。 */
+  backgroundOutputRoute?(open: boolean): void;
+  /** 后台输出变更后若空闲则冲刷滚动缓冲（原 inline 的 flushScrollbackIfIdle()）。 */
+  flushScrollbackIfIdle?(): void;
+  /** 注册插件状态条目到中央 registry（原 inline 的 registerPlugin('cli-status', ...)）。 */
+  registerStatusItems?(items: readonly {
+    id: string;
+    text: string;
+  }[]): void;
+}
+interface TaskActions {
+  setTasks(tasks: TaskItem$1[], title?: string): void;
+  setEditedFiles(files: EditedFileEntry[]): void;
+  addEditedFile(entry: EditedFileEntry): void;
+  setBackgroundTasks(tasks: BackgroundTaskSummary[]): void;
+  setTurnBoundaries(boundaries: number[]): void;
+  addTurnBoundary(messageIndex: number): void;
+  setDrafts(drafts: DraftItemView$1[]): void;
+  setScheduleTasks(tasks: TaskState['scheduleTasks']): void;
+  setRecentMentions(entries: SigilEntry[]): void;
+  setModelName(name: string): void;
+  setSessionList(list: TaskState['sessionList']): void;
+  setSessionTitle(title: string): void;
+  setNeedsSetup(value: boolean): void;
+  setPermissionMode(mode: string): void;
+  /** 强制升级提示（RFC-335 P0a 自 TuiHandle.setForcedUpgrade 下沉）：字段 + overlay 路由 + notify。 */
+  setForcedUpgrade(msg: string | null): void;
+  /** 插件状态栏条目（RFC-335 P0a 自 TuiHandle.setPluginStatusItems）：字段 + 注册中央 registry + notify。 */
+  setPluginStatusItems(items: readonly {
+    id: string;
+    text: string;
+  }[]): void;
+  /** 实时输出跟随视图（RFC-335 P0a 自 TuiHandle.setBackgroundOutput）：字段 + 路由 follow + 空闲冲刷 + notify。 */
+  setBackgroundOutput(view: DelegateOutputView | null): void;
+}
+//#endregion
+//#region src/stores/budget-store.d.ts
+interface BudgetView {
+  /** 模型名（展示用）。 */
+  modelName: string;
+  /** 上下文窗口总大小（token）。 */
+  contextWindow: number;
+  /** 上下文占用 %（totalUsed / contextWindow * 100）。 */
+  contextPercent: number;
+  /** 固定开销 token = estimateTokens(systemPrompt) + getToolTokens(tools)。 */
+  overheadTokens: number;
+  /** 消息 token = 真实已用 − 固定开销（totalUsed − overheadTokens）；prompt cache 下含历史。 */
+  messageTokens: number;
+  /** 当前会话消息条数（messages 段显示为 token(条数)）。 */
+  messageCount: number;
+  /** 全部已用 token = cacheReadTokens + cacheWriteTokens + inputTokens。 */
+  totalUsed: number;
+  /** 可用 token = contextWindow − overhead − messages（三段恒闭合；正常态 = window − totalUsed）。 */
+  free: number;
+  /** prune 触发线 token 数（70% contextWindow）。 */
+  pruneLine: number;
+  /** compact 触发线 token 数（85% contextWindow）。 */
+  compactLine: number;
+  /** 最近一轮 input（非 cache 部分，API 返回）。 */
+  lastInput: number;
+  /** 最近一轮 output。 */
+  lastOutput: number;
+  /** 全会话累计 input。 */
+  totalInput: number;
+  /** 全会话累计 output。 */
+  totalOutput: number;
+  /** 估算成本（USD，按模型费率；未知/0 时省略）。 */
+  cost?: number;
+  /**
+   * true = 本次读数含"尚未被 provider usage 结算"的本地实时估算（agent 工作中：prompt 已提交／
+   * 工具结果已产出／正在流式输出）。UI 据此标注 `~`，避免用户把 live 估算当成权威值、
+   * 在回合结算校准后误以为占用"回退"了。false/缺省 = provider usage 结算后的权威快照。
+   */
+  live?: boolean;
+}
+interface BudgetState {
+  /** 尚未收到任何预算快照时为 null（状态栏据此不渲染占用条）。 */
+  budget: BudgetView | null;
+}
+interface BudgetStore {
+  store: Store<BudgetState>;
+  setBudget(v: BudgetView): void;
+  /** `/clear` 等会话重置：回到"无预算"初值，避免旧会话读数残留。 */
+  reset(): void;
+}
+declare function createBudgetStore(): BudgetStore;
+//#endregion
+//#region src/stores/cache-store.d.ts
+/** 单模型的缓存用量明细（对齐 `@x-otto/ai` 的 `ModelCost` 子集，不跨包 import 类型）。 */
+interface CacheModelRow {
+  modelId: string;
+  modelName: string;
+  cacheReadTokens: number;
+  cacheWriteTokens: number;
+  inputTokens: number;
+  /**
+   * 该模型的命中率（R1 = cacheRead / totalInput）。`null` = 该模型的 api 不在
+   * 缓存报告白名单内（供应商没有相应缓存 API），或本模型累计 totalInput 为 0。
+   */
+  hitRatio: number | null;
+}
+interface CacheView {
+  /** 最近一回合的命中率（`AgentSession.getLastCacheHitRatio()`）；`null` = 无数据或供应商不支持。 */
+  lastTurnHitRatio: number | null;
+  /** 会话级加权命中率 = 全会话 cacheReadTokens / 全会话 totalInputTokens；`null` = 无可计算数据。 */
+  sessionHitRatio: number | null;
+  /** 会话累计缓存读取 token。 */
+  totalCacheReadTokens: number;
+  /** 会话累计缓存写入 token。 */
+  totalCacheWriteTokens: number;
+  /** 会话累计非缓存 input token。 */
+  totalInputTokens: number;
+  /** 估算的会话总成本（USD）；无定价数据时为 undefined。 */
+  totalCostUSD?: number;
+  /** 按模型拆分（多模型会话时展示每个模型各自的命中率）。 */
+  perModel: CacheModelRow[];
+}
+interface CachePaneState {
+  view: CacheView | null;
+}
+interface CacheStore {
+  store: Store<CachePaneState>;
+  /** CLI 喂入最新缓存统计视图（`/cache-stats` 命令触发）。
+   *  RFC-256 收尾：面板可见性由 Router 栈单一真源派生（isInStack('/pane/cache')），
+   *  store 不再持 `open` 布尔——原 toggle() 已删除。 */
+  setView(view: CacheView): void;
+}
+//#endregion
+//#region src/stores/proxy-store.d.ts
+/** 探测状态机：idle（未测过）→ probing（进行中）→ ok / failed。 */
+type ProxyProbeState = {
+  status: 'idle';
+} | {
+  status: 'probing';
+} | {
+  status: 'ok';
+  latencyMs: number;
+  target: string;
+} | {
+  status: 'failed';
+  reason: string;
+  blamesProxy: boolean;
+  target: string;
+};
+interface ProxyPanelView {
+  /** 代理地址（http:// 或 https://），未配置时为 undefined。 */
+  url?: string;
+  /** 代理是否已启用（false = 已配置但停用）。缺省=未配置时不显示。 */
+  enabled?: boolean;
+  /** 配置文件路径（展示用）。 */
+  configPath: string;
+  /**
+   * 当前**进程内实际生效**的代理（`getDefaultProxy()`），与 `url`/`enabled` 表达的
+   * **配置态**区分（RFC-288 D3）。二者一致是常态，面板据此保持静默；不一致才说明
+   * "改了配置但尚未生效"，需要显式告警——否则用户无从回答"我设了为什么没用"。
+   */
+  effectiveUrl?: string;
+  /**
+   * 启动时从环境变量检测到的系统代理（RFC-288 D5）。此前 `interactive-setup.ts` 检测到
+   * 后只弹一次 toast 就丢弃，面板完全不知情，用户环境里明明有可用地址却仍需手打。
+   * **仅作建议值**：必须用户显式确认才落盘（沿用前身 RFC 规则 5，避免"代理突然生效
+   * 但用户不知道"）。
+   */
+  detectedEnvProxy?: {
+    value: string; /** 来源变量名（`HTTP_PROXY`/`HTTPS_PROXY`…）——用户需要知道它从哪来才敢采用。 */
+    source: string;
+  };
+  /** 连通性探测状态（RFC-288 D4），由面板动作行触发、CLI 侧回推。 */
+  probe?: ProxyProbeState;
+}
+interface ProxyStoreState {
+  view: ProxyPanelView;
+}
+interface ProxyStore {
+  store: Store<ProxyStoreState>;
+  setView(view: ProxyPanelView): void;
+}
+//#endregion
+//#region src/overlays/Toast.d.ts
+interface ToastItem {
+  id: number;
+  title: string;
+  content: string;
+}
+//#endregion
+//#region src/dialogs/RetryDialog.d.ts
+interface RetryDialogItem {
+  attempt: number;
+  max: number;
+  delayMs: number;
+  /** 共享可变引用——TUI 置位，agent 轮询检测后跳过剩余 sleep。 */
+  accelerate: {
+    skip: boolean;
+  };
+  /** 倒计时到期回调（清除渲染）。 */
+  onExpired: () => void;
+  /** 触发本次重试的错误原因（如 "socket hang up"）——为空/undefined 时不渲染原因行。 */
+  reason?: string;
+  /**
+   * 停止按钮 / Esc 回调（用户请求：重试倒计时浮层此前无法关闭、也无法真正终止
+   * 底层重试循环——唯一出路是隐藏快捷键 Ctrl+C 且会额外弹二次确认框）。
+   * undefined 时（如画廊静态演示无真实重试循环可停）Esc 退化为默认路由 goBack，
+   * 不渲染 Stop 按钮语义之外的强行为——调用方（`interactive-agent-toasts.ts`）始终
+   * 传入真实回调，直接中止当前 agent 回合（不二次确认，见 RFC-303 决策）。
+   */
+  onStop?: () => void;
+}
+//#endregion
+//#region src/stores/notification-store.d.ts
+interface NotificationState {
+  toast: ToastItem | null;
+  retryCountdown: RetryDialogItem | null;
+  /** RFC-147 M3：替代原 rateLimitCountdown 字段——统一错误重试卡片（覆盖硬额度+通用错误场景）。 */
+  errorRetry: ErrorRetryItem | null;
+  providerUsage: ProviderUsageBadgeItem | null;
+  notifications: AppNotification[];
+  /**
+   * RFC-180 D7：turn 边界软停止已生效（AgentSession.pauseRequested 镜像，经
+   * run.paused/run.resumed 事件由 cli 层 tui.setPaused() 下推）。状态栏据此渲染
+   * 常驻"已暂停"提示；agentBusy() 判忙组合链（submit-routing.busyWithPause）据此
+   * 挡住 drainQueue 自动出队。
+   */
+  paused: boolean;
+  /**
+   * RFC-186 D7：暂停浮层数据。非 null 时 App.tsx 渲染 PauseDialog。
+   * M3 的 interactive-events.ts 负责任意时刻写入本字段。
+   */
+  pauseDialog: PauseDialogItem | null;
+  /**
+   * RFC-186 D7：暂停等待中的状态栏实时信息（工具计数 + 已等待秒数）。
+   * 由 M3 的 interactive-events.ts 每秒推送；null = 无暂停等待态。
+   */
+  pausePending: {
+    elapsedSec: number;
+    toolCount: number;
+  } | null;
+  /**
+   * RFC-208：满意度脉冲调查浮层数据。非 null 时 App.tsx 渲染 PulseSurveyOverlay。
+   * interactive-events.ts 的 prompt.end case 负责写入（触发判定命中时）。
+   */
+  pulseSurvey: PulseSurveyItem | null;
+}
+interface NotificationStore {
+  store: Store<NotificationState>;
+  reset(): void;
+  /**
+   * 注入渲染触发器（RFC-333 M2-B4）。providerUsage 是 C-class（无 useAppState 消费方，
+   * 经 TuiRoot snapshot prop + 手动 notify 渲染），故 action 必须保留 notify，不得裸删。
+   */
+  setNotify(notify: () => void): void;
+  /**
+   * 注入副作用钩子（RFC-335 T335-07 前置 P0a）。同 taskStore.setEffects——残留
+   * TuiHandle setter（setPaused/setPulseSurvey）是"字段 setter + 副作用"混合体，须
+   * 注入 side-effect 闭包才能下沉为 store action 而不丢路由/出队行为。未注入时 no-op。
+   */
+  setEffects(effects: NotificationStoreEffects): void;
+  /** provider usage 徽标数据（cli 回推）。C-class：写后必须 notify 触发全树重渲染。 */
+  setProviderUsage(item: ProviderUsageBadgeItem | null): void;
+  /** pause pending 信息（cli 回推）。C-class：无 useAppState 消费方，写后必须 notify。 */
+  setPausePending(info: NotificationState['pausePending']): void;
+  /** paused 字段（RFC-335 P0a 自 TuiHandle.setPaused）：字段 + paused=false 时 drainQueue + notify。 */
+  setPaused(paused: boolean): void;
+  /** 满意度调查浮层（RFC-335 P0a 自 TuiHandle.setPulseSurvey）：字段 + overlay 路由 + notify。 */
+  setPulseSurvey(item: NotificationState['pulseSurvey']): void;
+}
+/**
+ * notificationStore 副作用接入口子。注入方（main.ts）闭包内取真 router / drainQueue —
+ * —接口不暴露树外类型，与 taskStore 同款。
+ */
+interface NotificationStoreEffects {
+  /** paused 由 true→false 时尝试出队（原 inline 的 drainQueue()）。 */
+  drainQueueOnResume?(): void;
+  /** 满意度调查 overlay 开/关（router 副作用）；true→开、false→关。 */
+  syncPulseSurveyRoute?(open: boolean): void;
+}
+//#endregion
+//#region src/messages/plugin-renderer-registry.d.ts
+type PluginMessageRenderer = (message: unknown, columns: number) => string[];
+interface RegisteredRenderer {
+  /** 全局唯一 id（`pluginId:rendererId`），用于日志与 unregister。 */
+  id: string;
+  matcher: {
+    role?: string;
+    toolName?: string;
+    contentType?: string;
+  };
+  render: PluginMessageRenderer;
+}
+/** 幂等注册（RFC-131：委托到中央注册表，source='cli'）。 */
+declare function registerPluginRenderers(next: readonly RegisteredRenderer[]): void;
+/** 清空全部注册（RFC-131：委托到中央注册表）。 */
+declare function clearPluginRenderers(): void;
+//#endregion
+//#region src/messages/plugin-file-viewer-registry.d.ts
+type PluginFileViewerRenderFn = (content: string, path: string, columns: number) => {
+  lines: string[];
+  wrapMode?: 'pre-wrap' | 'truncate';
+} | null;
+interface RegisteredFileViewer {
+  /** 全局唯一 id（`pluginId:entryId`）。 */
+  id: string;
+  pluginId: string;
+  label: string;
+  matcher: {
+    extensions?: string[];
+    filenames?: string[];
+    glob?: string[];
+  };
+  render: PluginFileViewerRenderFn;
+  order?: number;
+}
+//#endregion
+//#region src/components/Button.d.ts
+type ButtonVariant = 'solid' | 'outline' | 'ghost';
+type ButtonColor = 'accent' | 'amber' | 'red' | 'green' | 'gray';
+interface ButtonProps {
+  label: string;
+  variant?: ButtonVariant;
+  /** 语义色彩（ghost 变体下忽略，始终用 accent 蓝）。默认 accent。 */
+  color?: ButtonColor;
+  /** @deprecated 使用 tabIndex 替代。向后兼容：传入时覆盖 useTabable 结果。 */
+  focused?: boolean;
+  disabled?: boolean;
+  /** 强制方括号格式（outline 默认 true；solid/ghost 默认 false）。
+   *  solid+brackets=true 时 unfocused 用 inactive 灰色（而非 color 色）。 */
+  brackets?: boolean;
+  /** tabIndex for focus traversal（默认 -1 = 不参与；0+ = 参与）。 */
+  tabIndex?: number;
+  /** Enter 触发的 action（tabIndex ≥ 0 时通过 useTabable onAction 注册）。 */
+  onAction?: () => void;
+}
+declare function Button({
+  label,
+  variant,
+  color,
+  focused: focusedProp,
+  disabled,
+  brackets,
+  tabIndex,
+  onAction
+}: ButtonProps): React.ReactElement;
+//#endregion
+//#region src/panes/PluginPane.d.ts
+/**
+ * PluginPane.tsx — 插件面板组件的动态加载 + 错误隔离（RFC-081）。
+ *
+ * `PluginPane`：只加载并渲染插件组件（无外框/标题），嵌进独立的 `PluginDialog`
+ * （RFC-167：插件面板全屏 dialog，取代此前内嵌 `ExtensionDetailDialog` body 槽位的方案）。
+ * `PanelErrorBoundary` 隔离坏插件 render 抛错为一行降级提示。dynamic import 编译后的 ESM
+ * 模块（而非 React.lazy + Suspense，避 Ink 对 Suspense 支持不确定）。
+ *
+ * 崩溃兜底（RFC-166 D9 P0 修复思路延续，RFC-167 精简为单向信号）：面板一旦在**加载期**
+ * （`import()` 失败）、**渲染期**（`PanelErrorBoundary` 捕获）或**异步期**
+ * （`usePanelAsyncErrorGuard` 捕获）三条路径中的任意一条崩溃，面板组件本身会立即卸载/
+ * 停渲染——不会再有任何面板代码调用 `requestClose()`，`PluginDialog` 若不感知这次
+ * 崩溃，会永久停留在"面板已死、无人监听键盘"的死区（用户只能强杀 TUI 进程）。三条错误
+ * 路径命中即调用 `panelFocusBridge.reportCrashed()`，`PluginDialog` 订阅后激活自己
+ * 的兜底 `useInput`（用户至少能 Esc 关闭独立面板 dialog，退回详情页）。
+ */
+interface PanelInfo {
+  title: string;
+  modulePath: string;
+  exportName: string;
+  /**
+   * RFC-165 M2 T7：面板所属插件 id——`usePanelBackend()` 据此定位对应的 backend MCP
+   * server 连接。可选（历史构造点可能未透传，见 `PluginPane` 挂载前注入逻辑的
+   * fail-soft 处理：缺失时 `usePanelBackend()` 恒返回 `status:'disabled'`，不崩溃面板）。
+   */
+  pluginId?: string;
+}
+//#endregion
+//#region src/dialogs/ExtensionDetailDialog.d.ts
+/**
+ * ExtensionDetailDialog.tsx — `/extension` 扩展详情统一 dialog（取代 /panels 独立面板视图）。
+ *
+ * 结构：标题 + 元信息 → 控制按钮行（启用/禁用 · 重载 · 重连 · 信任/不信任 · 打开面板，由调用方
+ * 按类别/状态组装）→ body（`dataListEntries`/`info` 回退展示）。
+ *
+ * RFC-167（架构重设计，取代 RFC-166 D9 键盘归属桥）：插件面板不再内嵌本 dialog 的 body 槽位
+ * ——此前面板一旦需要真实交互（Tab 切子标签/编辑字段/登录流程），必须与本 dialog 互斥仲裁
+ * 键盘归属（`panelFocusBridge`），导致宿主控制按钮在面板接管期间完全不可达（真实用户反馈：
+ * "看得见按钮按不动"），且面板内部 Tab 语义与"跨区域焦点移动"直觉冲突。现在插件面板改为
+ * 独立顶层 dialog（`PluginDialog`，见该文件），本组件对有 `panelInfo` 的详情追加一个
+ * "打开面板 →"控制按钮（`value: 'open-panel'`），点击后经 `req.onOpenPanel()` 回调打开独立
+ * dialog——两层模态各自拥有 100% 键盘，不再需要互斥仲裁。本组件因此恢复最初设计意图
+ * （首个提交注释："body 为被动展示，不夺焦点"）：← → 切按钮、Enter 执行、Esc 关闭，全程统一
+ * 行为，不再有"键位由面板接管"这种运行时切换的复杂度。
+ *
+ * "extension 默认面板"（无自定义 panel 时的回退展示）走 `DataList`（`dataListEntries`）渲染
+ * ——分组标题 + label 弱化/value 正常前景双色，与 `/about` 视觉统一。`info` 仍保留作为更简单
+ * 场景的向后兼容路径（`dataListEntries` 提供时优先）。
+ *
+ * 正文查看子视图（Skill/Agent 详情页"查看正文"按钮）：`req.fullText` 提供时，`onAction`
+ * 命中约定 value（`'view-full-text'`）触发本组件内部子状态切到 `FileContentViewer`（对齐
+ * `MemoryDialog`/`PasteConfirmDialog` 的"列表/详情 → 全文查看"三段式先例），Esc 退回本
+ * dialog（不触发 `onClose`——只读浏览不代表用户想关闭详情页）。正文可能很长（SKILL.md 正文/
+ * agent systemPromptTemplate），不适合塞进 DataList 行内，故复用滚动查看器而非展开渲染。
+ */
+interface ExtensionDetailAction {
+  label: string;
+  value: string;
+  color?: ButtonColor;
+}
+/** RFC-153 D4：插件健康度摘要（PluginHealthTracker.query() 的投影，全零不展示该行）。 */
+interface ExtensionHealthSummary {
+  hookTimeouts: number;
+  toolTimeouts: number;
+  lastError?: {
+    message: string;
+    timestamp: number;
+  };
+}
+/** RFC-153 D4：单条插件日志（readPluginLogTail() 的投影）。 */
+interface ExtensionLogEntry {
+  ts: number;
+  level: string;
+  msg: string;
+}
+interface ExtensionDetailRequest {
+  title: string;
+  /**
+   * 元信息行前缀，如 "plugin · user"（不含启用态词——启用态走 `metaStatus` 独立着色渲染，
+   * 真实用户反馈修复：灰底一整行文本无法区分"启用"应为绿色、"禁用"应为红色的语义强调）。
+   */
+  meta?: string;
+  /** 启用态：渲染在 `meta` 之后，`enabled` 为 true 时用 colors.success（绿），false 用 colors.error（红）。 */
+  metaStatus?: {
+    label: string;
+    enabled: boolean;
+  };
+  /** `metaStatus` 之后的尾随文本（如 plugin 详情页的信任状态），仍走默认灰色。 */
+  metaSuffix?: string;
+  /** 控制按钮（启用/禁用 · 重载 · 重连 · 信任/不信任 …，不含"打开面板"——由 `panelInfo` 派生）。 */
+  actions: ExtensionDetailAction[];
+  /**
+   * 该插件贡献的面板（RFC-167：不再内嵌渲染，仅用于判断是否展示"打开面板 →"按钮）。
+   * 提供时本组件在 `actions` 末尾追加该按钮，点击触发 `onOpenPanel()`。
+   */
+  panelInfo?: PanelInfo;
+  /** 点击"打开面板 →"按钮时调用（宿主经 `openModal('pluginPanel', ...)` 打开独立 dialog）。 */
+  onOpenPanel?: () => void;
+  /**
+   * 无 panel 时的回退展示——分组键值信息（经 `DataList` 渲染，`/about` 同款双色排版）。
+   * 提供时优先于 `info`（RFC-166 D10 后续："extension 默认面板"统一走 DataList）。
+   */
+  dataListEntries?: DataListEntry[];
+  /** 无 panel、无 `dataListEntries` 时的回退信息行（如 MCP 的 command/url，纯文本兼容路径）。 */
+  info?: string[];
+  /** RFC-153 D4：健康度摘要（挂起/超时计数）；undefined 或全零时不展示该行。 */
+  healthStats?: ExtensionHealthSummary;
+  /** RFC-153 D4：最近日志（最多 20 条，已按时间正序排列）；undefined/空数组时展示"暂无日志"占位。 */
+  logEntries?: ExtensionLogEntry[];
+  /** RFC-153 D4：手动刷新键（r，对齐 /perf 面板同款绑定）——重新查询健康度+日志并回填。 */
+  onRefresh?: () => void;
+  /**
+   * "查看正文"子视图内容（可选，Skill/Agent 详情页用）——提供时 `actions` 里应包含一个
+   * `value: 'view-full-text'` 的按钮，命中后本组件内部切到 `FileContentViewer` 展示这段
+   * 长文本（SKILL.md 正文 / agent systemPromptTemplate），Esc 退回本 dialog。未提供时
+   * `'view-full-text'` action 不会有任何特殊处理（调用方也不应该注册该 value 的按钮）。
+   *
+   * RFC-187 M0：正文经 `resolveFileContentViews` 统一调度渲染（此前是裸文本 bug）。两类
+   * 正文（SKILL.md 正文 / agent systemPromptTemplate）均为 markdown 风格散文，`kind` 缺省
+   * 为 `'markdown'` 时以合成路径 `${title}.md` 送入调度函数，获得 rendered/raw 双候选；
+   * 未来若有非 markdown 正文来源，可扩展 `kind: 'plain'` 跳过 markdown 候选。
+   */
+  fullText?: {
+    title: string;
+    content: string;
+    kind?: 'markdown' | 'plain';
+  };
+  /** 执行某控制按钮（value）。 */
+  onAction: (value: string) => void;
+  onClose: () => void;
+}
+//#endregion
+//#region src/dialogs/FileViewerDialog.d.ts
+interface FileViewerRequest {
+  /** 展示用路径（可以是相对路径，仅用于 header 展示与语言判定，不做文件系统操作）。 */
+  path: string;
+  /** 文件原始内容（由 `handleOpen` 读取，已过二进制探测——见 RFC-189 R5）。 */
+  content: string;
+  /**
+   * 调用方是否已在读取阶段用 `readFileCapped` 截断内容（RFC-189 追加修复）——
+   * true 时强制走大文件降级候选，不依赖 `content.length` 判断（截断后长度恒不超阈值，
+   * 单凭长度判断会误判为"文件不大"而漏显示"文件过大"提示）。
+   */
+  preTruncated?: boolean;
+  onDismiss: () => void;
+}
+//#endregion
+//#region src/dialogs/HelpViewerDialog.d.ts
+interface HelpViewerRequest {
+  /** 标题（上边框下方展示，如 "Help" / "Commands"）。 */
+  title: string;
+  /** 已组装好的正文行（分组标题 + 对齐后的命令行，见 `buildHelpLines`/`handleHelp`）。 */
+  lines: string[];
+  onDismiss: () => void;
+}
+//#endregion
+//#region src/dialogs/ExtensionsListDialog.d.ts
+interface ExtensionListEntry {
+  category: string;
+  id: string;
+  name: string;
+  enabled: boolean;
+  description?: string;
+  /** 'live' | 'next-turn' 等——非 'live' 时在 detail 追加提示。 */
+  applies?: string;
+}
+/** 全局菜单贡献条目（RFC-105 D5/M105-4）——独立分组，追加在内置列表之后。 */
+interface ExtensionMenuContribution {
+  id: string;
+  title: string;
+}
+interface ExtensionsListRequest {
+  entries: ExtensionListEntry[];
+  menuContributions?: ExtensionMenuContribution[];
+  /**
+   * 上次选中的条目 value（`category:id` / `contrib:id`）——进入详情后 Esc 退回列表时，
+   * 列表 Select.Root 用 `defaultValue` 恢复游标到该条目（不重置为第一条）。
+   */
+  lastSelectedValue?: string;
+  onSelect: (value: string) => void;
+  onCancel?: () => void;
+}
+//#endregion
+//#region src/dialogs/PluginDialog.d.ts
+/**
+ * PluginDialog.tsx — 插件面板独立全屏 dialog（RFC-167）。
+ *
+ * 背景：插件面板此前内嵌在 `ExtensionDetailDialog` 的 body 槽位，与宿主详情页的控制按钮
+ * （启用/禁用·重载·信任）共享同一屏——面板一旦需要真实交互（Tab 切子标签、编辑字段、
+ * 登录流程），键盘归属就必须在宿主/面板之间做互斥仲裁（RFC-166 D9 `panel-focus-bridge.ts`），
+ * 导致两个真实可用性问题：① 宿主按钮在面板接管键盘期间完全不可达（用户反馈"看得见按不动"）；
+ * ② Tab 键在"面板内部切子标签"与"跨区域移动焦点"两种语义间冲突，无法两全。
+ *
+ * 本方案根治：插件面板从宿主详情页拆出，改为独立的顶层 hard modal（同 `extensionDetail`/
+ * `extensionsList` 走 `FOCUS_REGISTRY` Band A，任意时刻与其他模态互斥）。面板挂载即拥有
+ * 100% 键盘（不再需要与宿主协商），`ExtensionDetailDialog` 一侧只渲染"打开面板 →"入口按钮，
+ * 点击后经 `openModal('pluginPanel')` 打开本 dialog；Esc 关闭本 dialog、退回详情页（不是
+ * "关闭详情页"——两层模态各自独立，符合用户对"进一层、退一层"的直觉）。
+ *
+ * 键盘归属桥（`panel-focus-bridge.ts`）随本改造整体退休：面板不再需要 claim/release，
+ * `usePanelFocusClaimed()`/`claimPanelFocus()`/`releasePanelFocus()` 三个 banner 注入
+ * 标识符改为恒定桩实现（见 `panel-compiler.ts`），面板产物无需改动即可在新架构下正常工作
+ * （`usePanelFocusClaimed()` 恒返回 `true` — 面板挂载即天然独占键盘，无需再"声明接管"）。
+ * `requestPanelClose()` 的语义随之改变：从"把控制权交还宿主 dialog"变为"关闭本 dialog"，
+ * 两种场景下面板侧代码调用方式完全一致（`requestPanelClose()`），无需感知底层机制变化。
+ */
+interface PluginPanelRequest {
+  panelInfo: PanelInfo;
+  onClose: () => void;
+}
+//#endregion
+//#region src/dialogs/InfoDialog.d.ts
+interface InfoDialogAction {
+  /**
+   * 'retry'：重试原请求；'login'：唤起 /login 面板（认证失效场景，重试必然复现同一失败）；
+   * 'extension'：唤起 /extension 面板（插件高危能力待授权场景——用户需要的是去信任插件
+   * 授予能力，而非重新登录/重试，见 /model refresh 结果 dialog 的"待授权"分支）。
+   */
+  kind: 'retry' | 'login' | 'extension';
+  run: () => void;
+}
+/**
+ * 单行语义色调（RFC-126 附带修复：/model refresh 结果三态视觉分离）：
+ * 'success' = 正向反馈（绿，如 provider 已可用）；'muted' = 中性/可忽略状态（灰弱化，
+ * 如未认证——不是错误，无需处理）；'warning' = 需要用户动作（琥珀，如能力待授权）；
+ * 未指定 = 默认前景色（既有行为，兼容全部现有调用点）。
+ */
+type InfoLineTone = 'success' | 'muted' | 'warning';
+interface InfoDialogProps {
+  /** 标题行（上边框下方第一行，blue bold）。 */
+  title: string;
+  /** 正文行列表。`dataListEntries` 提供时忽略（见下）。 */
+  lines: string[];
+  /**
+   * 按行索引指定色调（可选，稀疏映射——只需给需要着色的行索引赋值）。
+   * 不提供时全部行走默认前景色，与既有 ~12 处 openInfo 调用点零行为变化。仅在 `lines`
+   * 路径生效（`dataListEntries` 路径下由 `DataList` 自行控制着色）。
+   */
+  lineTones?: Record<number, InfoLineTone>;
+  onDismiss: () => void;
+  /** 底部单个可操作按钮（非空时渲染，Enter 触发）。取代原 onRetry——语义由 kind 决定文案/颜色。 */
+  action?: InfoDialogAction;
+  /**
+   * 分组键值正文（可选）——供需要「分组标题 + 行内 label/value 双色」的场景（如 `/about`）
+   * 替代 `lines` 纯文本渲染，经 `DataList` 渲染。提供时优先于 `lines`（`lines` 仍需传
+   * 空数组占位，类型上不做互斥以保持向后兼容——~12 处既有 `lines` 调用点零改动）。
+   * 用纯数据（非 `ReactNode`）传递，避免 `@x-otto/cli` 引入 `react` 依赖。
+   */
+  dataListEntries?: DataListEntry[];
+}
+declare function InfoDialog({
+  title,
+  lines,
+  lineTones,
+  onDismiss,
+  action,
+  dataListEntries
+}: InfoDialogProps): React.ReactElement;
+//#endregion
+//#region src/dialogs/MemoryDialog.d.ts
+type MemoryEntrySource = 'project' | 'user';
+interface MemoryEntry {
+  name: string;
+  slug: string;
+  description: string;
+  source: MemoryEntrySource;
+}
+interface MemoryDialogProps {
+  /** 项目记忆索引文本（.otto/memory）。空串 = 无条目。 */
+  projectIndex: string;
+  /** 用户记忆索引文本（~/.otto/memory）。空串 = 无条目。 */
+  userIndex: string;
+  /** 查看选中条目全文（异步）；返回 null 表示未找到/读取失败。 */
+  onViewEntry: (entry: MemoryEntry) => Promise<string | null>;
+  /** 确认删除选中条目（异步）。 */
+  onForget: (entry: MemoryEntry) => Promise<void>;
+  onDismiss: () => void;
+  /** 终端总行数（RFC-301：列表窗口 + DetailView 内 FileContentViewer 共用）。 */
+  rows?: number;
+  /** 终端总列宽（DetailView 内 FileContentViewer 需要，默认 80）。 */
+  columns?: number;
+}
+declare function MemoryDialog({
+  projectIndex,
+  userIndex,
+  onViewEntry,
+  onForget,
+  onDismiss,
+  rows,
+  columns
+}: MemoryDialogProps): React.ReactElement;
+//#endregion
+//#region src/messages/notify-scheduler.d.ts
+/**
+ * notify-scheduler.ts — RFC-038 P1：notify 入口合帧。
+ *
+ * 区别于 stream-coalesce（折叠「数据值」apply(v)），本调度器折叠「React 触发」——
+ * 即无参的 `listener()`（= startTui 的 setTick → 全树 reconcile）。
+ *
+ * 根因（RFC-038 §1）：现状 `notify()` 每个流式 token 都立即触发全树 reconcile，与用户
+ * 输入争抢 React 渲染管线；Ink 只在输出末端 throttle 丢帧，被丢帧的 reconcile+yoga 已白做。
+ * 采用请求入口合帧的调度模型：合并发生在「请求入口」，被合并的请求
+ * 零成本（reconcile 根本没发生）。
+ *
+ * 两条路径（RFC-038 §5.1 · R1/R2）：
+ * - `coalesced()`：流式触发走此路。窗口内多次调用只触发一次 `listener`（窗口末），消灭无效
+ *   reconcile。无 leading edge——流式预览容忍 1 帧延迟；即时反馈由 `immediate` 路径负责。
+ * - `immediate()`：用户交互（输入/模态/resize）走此路，立即触发 `listener`，零延迟（G2）。
+ *   并冲掉任何挂起的合帧 timer，避免随后多余触发。
+ * - `flush()`：finalize（块/回合结束/stop）立即触发挂起的 coalesced，禁丢尾段（R2）。
+ * - `cancel()`：unmount 时丢弃挂起触发。
+ *
+ * `intervalMs` 必须与 stream-coalesce / Ink stdout throttle 对齐（`coalesceIntervalForFps(maxFps)`），
+ * 三者错位会让多余触发与输入争管线（RFC-019 已坐实，R6）。
+ */
+interface NotifyStats {
+  /** coalesced() 被调用次数（含被合并跳过的） */
+  coalescedCalls: number;
+  /** listener 实际被触发次数（从 coalesced 路径） */
+  coalescedFires: number;
+  /** immediate() 被调用次数 */
+  immediateCalls: number;
+  /** flush() 实际触发 listener 的次数 */
+  flushFires: number;
+}
+interface NotifyScheduler {
+  /** 流式路径：入口合并，窗口内多次只触发一次 listener（窗口末）。 */
+  coalesced(): void;
+  /** 交互路径：立即触发 listener，并冲掉挂起的合帧 timer。 */
+  immediate(): void;
+  /** finalize：立即触发挂起的 coalesced（若有），禁丢尾段。 */
+  flush(): void;
+  /** unmount：丢弃挂起触发。 */
+  cancel(): void;
+  /** 获取统计（P3-01 可观测）。 */
+  getStats(): NotifyStats;
+}
+interface NotifySchedulerOptions {
+  /** 实际触发 React 重渲的回调（= startTui 的 state.listener，无参）。 */
+  listener: () => void;
+  /** 合帧窗口（ms），须与 stream-coalesce / Ink throttle 对齐。 */
+  intervalMs: number;
+}
+declare function makeNotifyScheduler(opts: NotifySchedulerOptions): NotifyScheduler;
+//#endregion
+//#region src/messages/a2ui-renderer.d.ts
+/**
+ * 提取自 a2ui content block 的 Button 交互元数据（M-N3）。
+ * 由调用方（startTui/App）用于注册快捷键路由，实现无需手动输入 /a2ui-action 的数字键触发。
+ */
+interface A2uiButtonInfo {
+  /** 快捷键（"1"-"9"，按渲染顺序自动分配）。 */
+  key: string;
+  /** 按钮显示标签。 */
+  label: string;
+  /** A2UI 组件 id。 */
+  componentId: string;
+  /** 声明的 action（如 "click"/"submit"）。 */
+  action: string;
+  /** 可选的附加 payload（当前 Button 组件不支持，预留扩展）。 */
+  payload?: Record<string, unknown>;
+}
+//#endregion
+//#region src/dialogs/select.d.ts
+/** color 仅 layout='buttons' 模式生效：调用方为每个按钮指定语义色（缺省按位置回退）。 */
+interface SelectOption {
+  label: string;
+  value: string;
+  disabled?: boolean;
+  hotkey?: number;
+  group?: string;
+  detail?: string;
+  color?: ButtonColor;
+  /** 条目行前导空白（`Select.Item` 的 `indent` prop 透传，默认一个空格）。 */
+  indent?: string;
+  /**
+   * 序号标记（`Select.Item` 的 `marker` prop 透传）：
+   *   - `'number'`：渲染该项在列表中的序数（1-based，跨分组连续计数）
+   *   - `'-'` / `'·'`：渲染固定项目符
+   *   不传 = 不渲染任何标记（默认现状）。
+   */
+  marker?: 'number' | '-' | '·';
+  /** `marker='number'` 时使用的序数（compileOptions 自动计算，1-based）。 */
+  ordinal?: number;
+  /**
+   * 行内尾随文案（`Select.Item` 的 `trailingLabel` prop 透传）：渲染在条目同一行右侧
+   * （非另起一行的 `detail`），用于 Welcome 扩展列表这类"名称 + 状态"同行双栏布局。
+   */
+  trailingLabel?: string;
+  /** `trailingLabel` 的颜色（默认 THEME.inactive）。 */
+  trailingColor?: string;
+  /**
+   * label 颜色覆盖（独立于 `disabled`——`disabled` 会额外追加 " (disabled)" 后缀文案，
+   * 不适合"仅需弱化配色、不需要追加文案"的场景，如 Welcome 未启用扩展行）。
+   *
+   * 缺省 = `colors.inactive`（未选中项统一灰，与选中态的品牌紫拉开对比）。
+   */
+  labelColor?: string;
+  /**
+   * 模糊搜索用纯语义文本（RFC-125 review 修复）：`label` 常含渲染态装饰（当前项标记 `●`/
+   * 空格 padding/上下文窗口后缀等），直接对其模糊评分会因短 query 命中装饰字符产生假阳性
+   * （如 "dsk" 因 "200k" 的 k 误中不相关模型）。提供 `searchText` 时 searchable 模式改为
+   * 对它评分（缺省回退 `label`，向后兼容不提供该字段的调用方）。
+   */
+  searchText?: string;
+}
+interface SelectOptions {
+  maxVisible?: number;
+  onBoundary?: (dir: 'top' | 'bottom') => void;
+}
+interface SelectState {
+  readonly selectedIndex: number;
+  readonly scrollOffset: number;
+  getVisibleOptions(): SelectOption[];
+  getOptionAt(index: number): SelectOption | undefined;
+  hasMoreAbove(): boolean;
+  hasMoreBelow(): boolean;
+  getSelected(): SelectOption | null;
+  moveUp(): void;
+  moveDown(): void;
+  accept(): SelectOption | null;
+  selectByHotkey(key: number): SelectOption | null;
+  selectByIndex(index: number): void;
+}
+declare function createSelectState(options: SelectOption[], opts?: SelectOptions): SelectState;
+//#endregion
+//#region src/dialogs/questions-dialog-logic.d.ts
+interface QuestionOption {
+  label: string;
+  description?: string;
+}
+interface Question {
+  /** 短标签（标签页/答案键）。 */
+  header: string;
+  /** 完整问题文本。 */
+  question: string;
+  /** 是否多选（多选用 Space 切换；单选 Enter/Space 选定并自动前进）。 */
+  multiSelect: boolean;
+  options: QuestionOption[];
+  /** grill_me allowFreeform：选项页底部渲染补充文本输入。 */
+  freeformInput?: boolean;
+  /** 补充文本输入框占位文字。 */
+  freeformPlaceholder?: string;
+}
+//#endregion
+//#region src/stores/message-store.d.ts
+/** 窗口模式 store 条目：ChatMessage + M2 边界定位预留 seq（DB 主键 seq）。 */
+type StoredMessage = ChatMessage & {
+  seq?: number;
+};
+interface MessageState {
+  /** 转录消息数组（scrollbackMode=false 的 legacy 路径 + RFC-300 窗口模式使用；直写模式恒空）。 */
+  messages: StoredMessage[];
+}
+interface MessageStore {
+  store: Store<MessageState>;
+  /** 追加一条消息（不可变 append，自动补 id）。seq 为 M2 边界定位预留（DB 主键）。 */
+  append(msg: ChatMessage, id: string, seq?: number): void;
+  /** 批量追加。 */
+  appendMany(msgs: readonly ChatMessage[], makeId: () => string): void;
+  /**
+   * RFC-300 M2：头部插入更早历史（DB 补页）——消息带 seq（StoredMessage.seq，
+   * DB 主键边界定位），插入数组头部；触发 ScrollableTranscript 全量重建（头部
+   * 连续性断裂）+ 视口补偿（新增行数由渲染层上报）。
+   */
+  prependMany(msgs: readonly ChatMessage[]): void;
+  /** 原地更新最后一条消息（不可变 patch）。用于 pending→转正等就地标记切换。
+   *  @deprecated 竞态敏感——若 pushMessage 在 echoUserInput 与 setPendingEcho/clearPendingEcho
+   *  之间追加了新消息，patchLast 会更新错误的消息。新代码使用 patchById（ID-based，无竞态）。 */
+  patchLast(patch: Partial<ChatMessage>): void;
+  /** 通过 id 定位并更新一条消息（不可变 patch）。用于 pending→转正，解决 patchLast
+   *   的竞态：若 pushMessage 在 echoUserInput 与 setPendingEcho/clearPendingEcho
+   *   之间追加了新消息，patchLast 会更新错误的消息而非用户 pending 消息。 */
+  patchById(id: string, patch: Partial<ChatMessage>): void;
+  /** 移除最后一条消息（不可变）。用于 ESC 撤回 pending user 消息。
+   *  @deprecated 竞态敏感——若 pushMessage 在 echoUserInput 与 withdrawPendingEcho
+   *  之间追加了新消息，removeLast 会移除错误的消息。新代码使用 removeById（ID-based，无竞态）。 */
+  removeLast(): void;
+  /** 通过 id 定位并移除一条消息（不可变）。用于 ESC 撤回，解决 removeLast 的竞态：
+   *   若 pushMessage 在 echoUserInput 与 withdrawPendingEcho 之间追加了新消息，
+   *   removeById 会移除错误的消息而非用户 pending 消息。 */
+  removeById(id: string): void;
+  /** /clear 会话重置。 */
+  reset(): void;
+}
+//#endregion
+//#region src/bootstrap/session-data-source.d.ts
+/** service `SessionSnapshot.session` 的最小消费面（字段名与 service DTO 一致）。 */
+interface RemoteSessionSnapshot {
+  session: {
+    id: string;
+    status: string;
+    messages: ReadonlyArray<StoredMessage>;
+  };
+  /** 快照时刻的事件游标（M3）。作为 subscribe.since 传回以补发期间事件。 */
+  cursor: number;
+}
+/** service `Session.subscribe(since)` 之后到达的单条 Session.event（包一层 seq 去重）。 */
+interface RemoteSessionEvent {
+  /** 服务端单调分配；客户端按它去重 + 检测乱序/缺口。 */
+  seq: number;
+  /** 事件负载（类型形如 Session.event 的 kind 集合；具体译码在 S1 映射表）。 */
+  payload: unknown;
+}
+/**
+ * 远端 session 的传输端口。attach 模式下的 client（otto service WS client）实现它；
+ * 本模块只依赖该最小面，可注入 mock（单测不需要真 WS/网络）。
+ */
+interface SessionTransport {
+  /** 取 session 快照（messages + cursor）。连接建立后首个动作。 */
+  fetchSnapshot(sessionId: string): Promise<RemoteSessionSnapshot>;
+  /**
+   * 订阅该 session 的实时事件流；`since` 传 snapshot.cursor 由服务端补发期间事件。
+   * 返回取消函数。断线重连由实现方负责（对齐 web-ui otto-client.resubscribeAll 语义）。
+   */
+  subscribe(sessionId: string, since: number, onEvent: (event: RemoteSessionEvent) => void, onGap: (info: {
+    reason: 'gap';
+    oldestAvailable: number;
+  }) => void): () => void;
+}
+/**
+ * 数据源注入后受驱动的 store 面（本地 zustand store 的最小可写接口——用 setState 而非
+ * action，因为远端译码直接产出字段值；调用方在 main.ts 装配时传入具体 store）。
+ */
+interface SessionDataTarget {
+  /** 镜像 messages 数组（追加/重设）。 */
+  messageStore: {
+    setState: Store<unknown>['setState'];
+  };
+}
+/**
+ * Session 数据源抽象：local = 现行（cli 在进程内嵌 session、经 TuiHandle/setters 喂），
+ * attach = 服务 Authority（snapshot+subscribe 灌入本地 store）。
+ *
+ * 这是 P0b 的核心 deliverable：把"数据来源"显式化成一个可注入、可替换的端口，
+ * 取代 RFC-333 之前"数据硬编码来自 cli 回调"的隐含耦合。详见 RFC-335-milestone-m3-t335-07.md §8.2。
+ */
+interface SessionDataSource {
+  /**
+   * 启动数据源并开始驱动 target stores。返回停止函数。
+   * local 模式可在无网络下返回 no-op（由 cli 侧现行 writer 继续喂 store）。
+   */
+  start(target: SessionDataTarget): Promise<() => void> | (() => void);
+}
+/** 现行本地模式：全部为 no-op——store 由 cli/main.ts 既有的 handle/stores writer 喂。 */
+declare function createLocalSessionDataSource(): SessionDataSource;
+interface AttachDataSourceDeps {
+  transport: SessionTransport;
+  sessionId: string;
+  /**
+   * 远端 Session.event → 本地 store 增量 的译码回调。S1 契约映射表产出；本模块只
+   * 负责"按 seq 有序、去重后逐条给它"。返回 void；副作用（调 store action）由实现方做。
+   */
+  onSessionEvent: (event: RemoteSessionEvent) => void;
+  /** 快照 messages 灌入 messageStore 的写函数（避免本模块直接 import messageStore）。 */
+  hydrateMessages: (target: SessionDataTarget, messages: ReadonlyArray<StoredMessage>) => void;
+  /** gap 显式通知（EVENT_LOG_GAP）——实现方应显式呈"丢事件、需重水合"，绝不静默少发。 */
+  onGap: (info: {
+    reason: 'gap';
+    oldestAvailable: number;
+  }) => void;
+}
+/**
+ * attach 模式数据源。snapshot(cursor) → subscribe(since) → onSessionEvent 逐条驱动。
+ * 事件按 seq 去重（M3 客户端 MUST）；遇 gap → onGap 显式上报（调用方决定重水合/报错）。
+ *
+ * 注：本数据源**只做 Session.event 域的驱动**。首期 attach 的下行写（prompt 经
+ * Chat.query）在 cli 侧，不流经本模块。
+ */
+declare function createAttachSessionDataSource(deps: AttachDataSourceDeps): SessionDataSource;
+//#endregion
+//#region src/bootstrap/types.d.ts
+/**
+ * M-N3b：高频流式引擎事件判别联合——收敛原 TuiHandle 8 个独立 setter
+ * （setAgentProcessing/setStreamingText/setStreamingThinking/setActiveTool/setSpinnerMode
+ * /setOutputTokensThisTurn/setMaxOutputTokens/setToolBudget）为单一 pushEngineEvent 通道。
+ */
+type TuiStreamEvent = {
+  kind: 'agentProcessing';
+  value: boolean;
+} | {
+  kind: 'streamingText';
+  text: string;
+} | {
+  kind: 'streamingThinking';
+  text: string;
+} | {
+  kind: 'activeTool';
+  name: string | null;
+} | {
+  kind: 'spinnerMode';
+  mode: 'requesting' | 'responding' | null;
+} | {
+  kind: 'outputTokensThisTurn';
+  n: number;
+} | {
+  kind: 'maxOutputTokens';
+  n: number;
+} | {
+  kind: 'toolBudget';
+  toolTurnCount: number;
+  maxToolTurns: number;
+  outputTokens?: number;
+  outputTokenBudget?: number;
+} | {
+  kind: 'perf';
+  memory?: PerfMemorySnapshot;
+  notify?: PerfNotifySnapshot;
+  indicatorLevel?: 'healthy' | 'warning' | 'critical';
+  pluginMetrics?: PluginMetricResult[];
+} | ({
+  kind: 'compactionLog';
+  entryKind: 'compact';
+  before: number;
+  after: number;
+  summary?: string;
+} | {
+  kind: 'compactionLog';
+  entryKind: 'prune';
+  tokensSaved: number;
+  prunedCount?: number;
+} | {
+  kind: 'compactionLog';
+  entryKind: 'history_capped';
+  removedCount: number;
+});
+/**
+ * 提交意图（前端无关语义层）：cli 据此决定如何处理一次提交。
+ *   - 'send'  : 起新回合（空闲时的普通提交，或斜杠命令分发）。
+ *   - 'steer' : agent 运行中时注入当前回合（session.steer）。
+ * followUp/排队 由 TUI 自身的 state.queued 承载（空闲即出队），不经此枚举。
+ * 后续移植 GUI：同一 intent 层，GUI 直接绑 Enter→steer / Cmd+Enter→followUp，语义零改。
+ */
+type SubmitIntent = 'send' | 'steer';
+/**
+ * RFC-148 M3：模态对话框判别联合——收敛原 TuiHandle 9 个独立 open* 方法
+ * （openInfo/openPermissions/openContext/openMemory/openSelect/openExtensionDetail/
+ * openInput/openQuestions/openConfirm）为单一 openModal 通道。（RFC-253 M-T6：底层
+ * modalStore 已删除，dialog 改由 <Route>+resolvers 渲染，openModal 通道语义不变。）
+ *
+ * 不收编 openAlert/openPrompt（全仓 grep 零调用点，见 findings-backlog.md 死代码候选）。
+ * infoDialog 三种来源（openInfo/openPermissions/openContext）在此拆分为三个判别联合
+ * 成员（而非合一个 'info' 成员塞可选字段），保留各自原有的固定语义（如 openContext
+ * 的空 lines 数组是有意为之，非可选省略）。
+ */
+type ModalRequest = {
+  kind: 'info';
+  title: string;
+  lines: string[];
+  action?: InfoDialogAction;
+  lineTones?: Record<number, InfoLineTone>;
+  /**
+   * 分组键值正文（可选，优先于 `lines`）——见 `InfoDialog.tsx` `dataListEntries` prop 注释。
+   * 纯数据（非 `ReactNode`），`@x-otto/cli` 可零依赖 `react` 地构造。
+   */
+  dataListEntries?: DataListEntry[];
+} | {
+  kind: 'permissions';
+  lines: string[];
+} | {
+  kind: 'context';
+} | {
+  kind: 'memory';
+  projectIndex: string;
+  userIndex: string; /** 查看选中条目全文（异步）；返回 null 表示未找到/读取失败。 */
+  onViewEntry: (entry: MemoryEntry) => Promise<string | null>; /** 确认删除选中条目（异步）。 */
+  onForget: (entry: MemoryEntry) => Promise<void>;
+} | ({
+  kind: 'select';
+} & SelectRequest) | ({
+  kind: 'extensionDetail';
+} & ExtensionDetailRequest) /** RFC-166：`/extension` 列表页——独立 hard modal（对齐 memory 走 Select.Group 组合式规范）。 */ | ({
+  kind: 'extensionsList';
+} & ExtensionsListRequest) /** RFC-167：插件面板独立全屏 dialog（取代面板内嵌 extensionDetail body 槽位的方案）。 */ | ({
+  kind: 'pluginPanel';
+} & PluginPanelRequest) | ({
+  kind: 'input';
+} & InputRequest) | ({
+  kind: 'questions';
+} & QuestionsRequest) | ({
+  kind: 'confirm';
+} & ConfirmRequest) /** RFC-174 M5：/keybindings 命令打开可视化快捷键面板（独立 hard modal，Band A）。 */ | {
+  kind: 'keybindingPanel';
+  overrides: Record<string, KeyBindingPredicate> | undefined;
+  onSave: (commandId: string, predicate: KeyBindingPredicate, target: 'global' | 'project') => void;
+  onSaveReplace: (actions: Array<{
+    commandId: string;
+    predicate: KeyBindingPredicate;
+  }>, target: 'global' | 'project') => void;
+  onReset: (commandId: string) => void;
+  onResetAll: () => void;
+} /** RFC-233：/shortcuts 命令打开用户自定义快捷方式管理面板（独立 hard modal，Band A）。 */ | {
+  kind: 'shortcutsPanel';
+  shortcuts: ReadonlyArray<{
+    name: string;
+    text: string;
+  }>;
+  onSave: (name: string, text: string, previousName?: string) => void;
+  onDelete: (name: string) => void;
+} /** RFC-189 D4：`/open <path>` 命令打开的文件查看器独立 dialog（Band A hard modal）。 */ | ({
+  kind: 'fileViewer';
+} & FileViewerRequest) /** `/help` 命令面板独立查看器（Band A hard modal，复用 FileContentViewer 固定高度+滚动逻辑）。 */ | ({
+  kind: 'helpViewer';
+} & HelpViewerRequest) /** install 进度条 dialog（Band A hard modal 阻断输入，不可取消）。 */ | ({
+  kind: 'progress';
+} & ProgressDialogProps) /** Setup 向导弹窗（五步线性引导：Provider→Trust→Login→Model→Start）。 */ | ({
+  kind: 'wizard';
+} & WizardRequest) /** 首次启动引导单弹层（昵称→语言→主题三步合一）；resolve 携带用户已设置的字段。 */ | {
+  kind: 'onboarding'; /** 语言步选中时立即切换界面语言（后续步骤文案即时生效）。 */
+  onLanguagePreview?: (language: 'en' | 'zh' | 'auto') => void;
+} /** RFC-211 M2：a2ui Form 组件交互式弹窗。 */ | {
+  kind: 'a2uiForm'; /** Form 组件的完整定义（含字段列表）。 */
+  component: A2uiComponent; /** 提交回调：收集字段值 → onA2uiAction(componentId, action, payload)。 */
+  onAction: (componentId: string, action: string, payload?: Record<string, unknown>) => void;
+};
+/** install 进度条 dialog props。 */
+interface ProgressDialogProps {
+  /** 标题，如 "Installing browser-use" */
+  title: string;
+  /** 四个阶段标签 */
+  phases: string[];
+}
+/** Setup 向导弹窗请求（openModal({kind:'wizard',...}) 入参）。 */
+/**
+ * OAuth 流程句柄——向导内嵌授权，不跳转独立面板。
+ * RFC-274 M2：补 `code`/`instructions`（对齐真实 `OAuthInfo` 字段），供等待态渲染
+ * device-flow 场景（有 code 展示设备码 UI，无 code 展示纯浏览器 UI）——不在选项列表层
+ * 区分 pkce/device-flow，只在这个等待态句柄层区分。
+ */
+/**
+ * OAuth 轮询失败分类（RFC-326 §6.3）——决定 UI 给出哪个主 CTA。
+ *  - `network`：连不上授权服务（含代理不通）→ 主 CTA 为「打开代理设置」
+ *  - `cancelled`：用户主动取消 → 静默回选择态，不当作错误
+ *  - `rejected`：provider 明确拒绝/超时 → 建议重试或换授权方式
+ */
+type OAuthFailureReason = 'network' | 'cancelled' | 'rejected';
+/** 轮询结果：兼容旧的裸字符串形态，新实现可返回带分类的对象。 */
+type OAuthPollResult = 'pending' | 'done' | 'error' | {
+  status: 'pending' | 'done';
+} | {
+  status: 'error';
+  reason: OAuthFailureReason;
+};
+interface OAuthHandle {
+  authorizationUrl: string;
+  /** 设备码流程的 user code（`OAuthInfo.code`）；pkce 浏览器流程通常为空。 */
+  code?: string;
+  /** provider 侧提示语（`OAuthInfo.instructions`），如 "Enter code: XXXX-XXXX"。 */
+  instructions?: string;
+  /**
+   * 轮询授权结果。
+   *
+   * RFC-326 §6.3：失败必须可分类——`'error'` 一把梭会让 UI 无法给出对症的下一步
+   * （网络/代理不通该引导去配代理，用户主动取消不该报错，provider 拒绝该建议换个
+   * 方式）。返回对象形态时携带 `reason`；仍支持返回裸字符串以兼容旧实现。
+   *
+   * **不传 raw error/stack**：§6.3 明确"不要把 raw stack 放在第一屏"，故契约层
+   * 只允许受限分类，从类型上杜绝调用方顺手把异常原文塞进 UI。
+   */
+  poll: () => Promise<OAuthPollResult>;
+  cancel: () => void;
+  /**
+   * 重新打开授权页（RFC-326 §6.3 "Open again"）。
+   *
+   * 浏览器没弹出来是 OAuth 最常见的失败形态——无头环境、默认浏览器未配置、
+   * 焦点被抢走后用户误关了标签页。此前等待态只有 Esc（取消整个授权），用户必须
+   * 退出重来才能再看一眼链接。省略时 UI 不显示该动作（向后兼容）。
+   */
+  openAgain?: () => void;
+}
+interface WizardRequest {
+  kind: 'wizard';
+  title: string;
+  /** 五步名称（i18n），按顺序：Provider/Trust/Login/Model/Start。 */
+  stepNames: readonly string[];
+  /** 五步副标题（i18n），按顺序。 */
+  stepSubtitles: readonly string[];
+  /** 已完成步骤索引集（0-based）。 */
+  initialCompleted: readonly number[];
+  /** 初始显示的步骤（0-based）。所有步骤需在 range 内。 */
+  initialCurrent: number;
+  /** Welcome 页 i18n 文案。 */
+  welcomeTitle: string;
+  welcomeGreeting: string;
+  welcomeDescription: string;
+  welcomeDontShowAgainLabel: string;
+  welcomeStartLabel: string;
+  welcomeCancelLabel: string;
+  providerOptions: Array<{
+    label: string;
+    value: string;
+    detail?: string;
+  }>;
+  /**
+   * Step 1 (Provider Auth) — 函数而非静态数组：根据 Step 0 用户选择的 provider 动态计算。
+   * RFC-274 M2：从硬编码白名单改为查 `OAuthRegistry`（不区分 pkce/device-flow，理由见
+   * RFC-274 §4"实施修正记录"）。命名对齐"provider 授权≠账号登录"语义切分（RFC-274 §0.1）
+   * ——历史名 `loginOptions` 已改名，避免与未来 `/login`（Otto/Aniwei 账号登录）语义混淆。
+   */
+  providerAuthOptions: (providerId: string) => Array<{
+    label: string;
+    value: string;
+    detail?: string;
+  }>;
+  /** Provider Auth 面板中显示的 provider 名称（如 "Anthropic"）。 */
+  authProviderName?: string;
+  /**
+   * Step 2 模型选项。
+   *
+   * RFC-326 §6.4：不能是"无排序的技术清单"——`recommended` 标出首选（至多一个），
+   * `unusableReason` 说明为何不可用（缺凭据 / 订阅 429 风险）。两个字段均可选：
+   * 省略时退化为原来的平列表渲染，旧调用方无需改动。
+   */
+  modelOptions: Array<{
+    label: string;
+    value: string;
+    detail?: string;
+    recommended?: boolean;
+    unusableReason?: 'unauthenticated' | 'oauth-429-risk';
+  }>;
+  examplePrompts: readonly string[];
+  /** 信任步骤（Step 1）中显示的工作区路径。 */
+  workspacePath?: string;
+  /**
+   * `capabilities`（RFC-326）：安装过程中**实际被授予**的高危能力 id 列表，供成功终态
+   * 向用户披露。向导走 `autoTrust` 跳过了确认弹窗，但授权照常发生——不披露会让用户
+   * 在毫无感知的情况下授出 provider 级权限（详见 WizardDialog 成功态注释）。
+   * 空数组/省略 = 该插件未声明任何高危能力，无需披露。
+   *
+   * `pendingCapabilities`（RFC-326 M2-05）：安装后 reload 时该插件仍有**未授予**
+   * 的高危能力。此时它的 providers 被 fail-closed 整体跳过——装上了却贡献零个
+   * 模型。必须在成功态显式告知，否则用户只看到 "✓ Installed" 就继续下一步，
+   * 到模型步才发现列表是空的、却不知道原因。
+   */
+  onInstallProvider: (value: string, onProgress: (phase: string) => void) => Promise<{
+    ok: true;
+    providerId?: string;
+    capabilities?: readonly string[];
+    pendingCapabilities?: boolean;
+  } | {
+    ok: false;
+    error: string;
+  }>;
+  /**
+   * 发起 provider OAuth 授权——向导内嵌等待态，不弹出独立面板。
+   * RFC-274 M2：补 `providerId` 显式传参，禁止调用方继续用 `providers[0]` 猜测
+   * （多 provider 场景下 Step 0 选中的 provider 必须与实际授权目标一致）。
+   */
+  onProviderOAuthStart?: (providerId: string) => Promise<OAuthHandle | null>;
+  /**
+   * 打开代理设置（RFC-326 §6.3：网络/代理错误的主 CTA）。
+   * 省略时该动作不显示——宿主未提供代理配置面板的场景下不给假入口。
+   */
+  onOpenProxySettings?: () => void;
+  /**
+   * 验证并保存 provider API key——向导内嵌输入框，不弹 InputDialog。
+   * RFC-274 M2：补 `providerId` 显式传参，同上。
+   */
+  onSubmitProviderApiKey?: (providerId: string, key: string) => Promise<{
+    ok: true;
+  } | {
+    ok: false;
+    error: string;
+  }>;
+  onSelectModel: (modelId: string) => Promise<void>;
+  onComplete: () => void;
+  onDismiss: () => void;
+  /** 用户在欢迎页勾选/取消"不再提示"。 */
+  onDontShowAgain: (value: boolean) => void;
+}
+/** ProgressDialog 运行时状态更新（由 updateProgress 推送）。 */
+interface ProgressUpdate {
+  phaseIndex?: number;
+  phaseStatuses?: Array<'pending' | 'active' | 'done' | 'error'>;
+  percent?: number;
+  detail?: string;
+  subProgress?: {
+    current: number;
+    total: number;
+  };
+  /**
+   * RFC-286 D2：`partial` = 部分成功（N 成功 / M 失败）的一等终态。
+   *
+   * 多 skill 安装遵循 RFC-130 D5「独立安装、失败不回滚」，半成功是**合法常态**，
+   * 因此 UI 必须有对应的第一等表达：用 `success` 近似会假绿（失败项静默隐藏），
+   * 用 `error` 近似会假红（用户误以为需要全部重装）。`partial` 亦用于
+   * 「产物已落盘但能力刷新失败」的 degraded success（D5）。
+   */
+  status?: 'running' | 'success' | 'partial' | 'error';
+  errorMessage?: string;
+  /**
+   * RFC-290 D2：终态「下一步」建议——**必须由调用方结构化下发**，组件零推断。
+   *
+   * 严禁改为在组件内对 `errorMessage` 做子串匹配（如判断是否含"已存在"）：错误文案
+   * 会随 locale 变化，文本嗅探在英文环境必然失效；且调用方本就掌握 `InstallResult`
+   * 的结构化信息，无需猜测。判定不出时**不下发本字段**，组件即不渲染建议行——
+   * 错误的建议比没有建议更有害。
+   *
+   * `label` 由调用方本地化后传入（组件不持有安装领域文案）。
+   */
+  nextStep?: {
+    kind: 'force' | 'reload';
+    label: string;
+  };
+}
+/** openModal 的 'input' 分支入参（供重载签名引用）。 */
+type ModalRequestInput = Extract<ModalRequest, {
+  kind: 'input';
+}>;
+/** openModal 的 'questions' 分支入参（供重载签名引用）。 */
+type ModalRequestQuestions = Extract<ModalRequest, {
+  kind: 'questions';
+}>;
+/** openModal 的 'onboarding' 分支入参（供重载签名引用）。 */
+type ModalRequestOnboarding = Extract<ModalRequest, {
+  kind: 'onboarding';
+}>;
+/** openModal 的其余 8 个同步分支入参（供重载签名引用）。 */
+type ModalRequestVoid = Exclude<ModalRequest, {
+  kind: 'input';
+} | {
+  kind: 'questions';
+} | {
+  kind: 'onboarding';
+}>;
+/** openQuestions 的返回值类型（供 openModal 'questions' 重载引用）。 */
+type QuestionsAnswer = {
+  answers: Record<string, string[]>;
+  freeformText?: string;
+};
+/**
+ * RFC-148 M3：面板 toggle 判别联合——收敛原 TuiHandle 10 个独立 toggle 类/"伪 open"方法
+ * （toggleHistory/toggleBackgroundTasks/toggleDraftPane/toggleQueuePane/toggleNotifications/
+ * toggleInspector/openSchedulePane/openPerf/openCacheStats/openGallery）为单一
+ * togglePane 通道。open 省略=翻转（对齐原 toggle* 方法的既有语义）；伪 open 类
+ * （原本只能"开"不能"关"）保留同样只开的语义，togglePane 调用时省略 open 参数即可。
+ *
+ * 不收编 toggleEditedFiles（全仓 grep 零调用点，见 findings-backlog.md 死代码候选）。
+ */
+type PaneName = 'history' | 'backgroundTasks' | 'draftPane' | 'queuePane' | 'notifications' | 'schedulePane' | 'perf' | 'cacheStats' | 'compactionLog' | 'gallery' | 'proxy' | 'prompts';
+interface TuiOptions {
+  stdin: NodeJS.ReadStream;
+  stdout: NodeJS.WriteStream;
+  columns?: number;
+  /** 终端总行数（自适应流式预览高度用；缺省读 stdout.rows）。 */
+  rows?: number;
+  /** 已完成历史改由 insertHistory 直写终端 scrollback（不进 Ink Static）。
+   *  缺省读 env OTTO_TUI_SCROLLBACK=1。开启后 Ink 只渲底部恒小 live 区。 */
+  scrollback?: boolean;
+  /** RFC-345 D5/D6：影子模式——TUI 侧渲染常驻可见性（状态栏徽标 + 输入区 chip + Home 横幅）。 */
+  shadow?: boolean;
+  modelName?: string;
+  /** 初始「无可用模型」态（未登录/无凭证）→ 输入框显 promptSetup 引导。 */
+  needsSetup?: boolean;
+  /** 斜杠命令表（typeahead） */
+  commands?: CommandEntry[];
+  /** #/@ sigil 条目数据源（coding 层 PluginInputRegistry，结构同构）。
+   *  静态注入（启动时一次），透传给 App 渲染 SigilPane。 */
+  pluginInput?: SigilSearchRegistry;
+  /**
+   * RFC-253 M-T5：初始路由。resume 到有历史会话时传 '/'（直接进对话，消除首帧闪 Home）；
+   * 全新会话缺省 '/home'。
+   */
+  initialPath?: string;
+  /** 启动横幅（version/cwd）；未提供则不显示 */
+  welcome?: {
+    version?: string;
+    buildId?: number;
+    cwd?: string; /** 用户昵称（settings.nickname）：Welcome 具名问候；缺省无名版。 */
+    nickname?: string;
+    updateAvailable?: {
+      latest: string;
+      current: string;
+      newer: boolean;
+      forced: boolean;
+    };
+    weather?: {
+      condition: string;
+      temp: number;
+      location: string;
+    };
+  };
+  /** RFC-234 P2-b：选择会话回调。 */
+  onSessionSelect?: (id: string) => void;
+  /** RFC-198 §4.4：PasteStore 的内存压力分级来源只读视图（cli 层传入 App._residencyGovernor
+   *  的结构化子集，零 @x-otto/runtime 编译期依赖）。省略时 PasteStore 固定 healthy 上限。 */
+  residencyGovernor?: PasteStoreResidencySource;
+  /**
+   * RFC-217 D1：EditedFileFullPane「整个文件 diff」（vs git HEAD）异步取数 provider。
+   * cli 层绑定 projectRoot 调用 `gitFallbackEditedFileContentAsync`（`@x-otto/cli`）注入；
+   * 缺省 `undefined` 时该模式不可用，`f` 键三态循环退化为现状 diff/full 二态。永远异步
+   * ——TUI 单线程渲染循环不可被子进程调用阻塞。
+   */
+  resolveWholeFileDiff?: (path: string, operation: EditedFileEntry['operation']) => Promise<{
+    oldContent?: string;
+    newContent?: string;
+    error?: string;
+  }>;
+  /** 界面语言（en/zh/auto）；缺省 auto（按环境 LANG 检测）。 */
+  language?: LangMode;
+  /** TUI 主题模式（RFC-263 M5）；缺省 dark。'system' 时 startTui 在 render 前经 OSC 11 探测终端背景明暗。 */
+  theme?: 'dark' | 'light' | 'system';
+  /**
+   * RFC-277 M6：主题预设注册表（builtin + extension 贡献，见 `@x-otto/cli`
+   * `theme-preset-wiring.ts` 装配）。未传时落回内置 dark/light（M1-M5 既有行为）。
+   */
+  themeRegistry?: ThemeRegistry;
+  /** RFC-277 M6：按 appearance 分槽的 preset 初值（settings `theme_preset` 字段）。 */
+  presetSelection?: ThemePresetSelection;
+  /**
+   * 用户快捷键覆盖表（settings `keybinding_overrides`）——**运行时按键分发的输入**。
+   *
+   * RFC-174 M4/M5 交付了 `/keybindings` 面板与持久化，却漏接运行时消费：`matchKeyBinding`
+   * 曾直接吃编译期 `KEY_BINDINGS`，导致用户改完键位、settings.json 也写了，但按键行为
+   * 不变（且无"需重启"提示）。此字段补上那条线；与 `language`/`theme`/`presetSelection`
+   * 同属"settings 派生的启动期配置"，故走 TuiOptions 而非新增 `TuiHandle.set*`
+   * （后者会撞 tuihandle-growth-gate 门禁，且键位覆盖不是流式数据推送）。
+   *
+   * ⚠️ 生效时机：**启动期读取一次**，运行时改绑需重启会话才生效（cli
+   * `handlers/keybindings.ts` 的四条写入路径均会 toast 提示这一点——没有该提示时，
+   * 用户"存了却没动静"的观感与修复前"改了永远不生效"完全相同）。
+   */
+  keybindingOverrides?: Record<string, KeyBindingPredicate>;
+  /** 当前权限 mode：confirm/auto/bypass。状态栏初值。 */
+  permissionMode?: string;
+  /** 快捷键（Shift+Tab）循环切换权限 mode 回调；cli 据此切并落盘。 */
+  onCyclePermissionMode?: () => void;
+  /** DEC1004 终端焦点变化（opt-in OTTO_TUI_FOCUS=1）；cli 喂 app.setTerminalFocus。 */
+  onFocusChange?: (focused: boolean) => void;
+  /** /proxy 面板内提交代理地址（编辑/设置）；cli 据此 settings.persist 落盘并回推 setProxyView。 */
+  onProxySubmitUrl?: (url: string) => void;
+  /** /proxy 面板内切换启用/停用；cli 据此 settings.persist 落盘并回推 setProxyView。 */
+  onProxyToggleEnabled?: () => void;
+  /** /proxy 面板内清除代理配置（ConfirmDialog 确认后）；cli 据此 settings.persist 落盘并回推 setProxyView。 */
+  onProxyClear?: () => void;
+  /** /proxy 面板内触发连通性探测（RFC-288 D4）；cli 探测后回推 setProxyView。 */
+  onProxyTest?: () => void;
+  /** 流式合帧 fps（缺省 30）：流式 token 在 App 级 coalescer 按此压帧，限流式渲染 CPU。 */
+  maxFps?: number;
+  /** Ink 渲染节流 fps（缺省 90，输入回显响应度）：与流式 fps 解耦——输入渲染只被 Ink maxFps 节流，
+   *  调高即解放输入（修「打字/删除卡顿」），流式仍由 App coalescer 压在 maxFps。 */
+  renderMaxFps?: number;
+  /** RFC-089 M8 spike：Ink ConcurrentRoot（键击 DiscreteEventPriority 插队 + 可中断 reconcile）。
+   *  缺省读 OTTO_TUI_CONCURRENT=1；A/B 稳定后再定默认。 */
+  concurrent?: boolean;
+  /** intent='steer' 时 cli 应注入当前运行回合（session.steer）而非起新回合；缺省/'send' 走原路径。 */
+  /**
+   * 提交回调（fire-and-forget）。
+   *
+   * **返回值不参与"是否保留草稿"的判定**（RFC-326 §6.7 定稿）：cli 侧实现是 async，
+   * 且真正的阻断点位于若干 `await` 之后（命令派发 / 文件命令展开），同步拿不到结论——
+   * 曾把本签名放宽为 `void | 'rejected'` 试图让宿主回传拒绝信号，但 async 实现返回的
+   * 恒是 `Promise`、永远不等于 `'rejected'`，该通道是**恒不生效的空契约**（且使
+   * cli 的 `Promise<void>` 与本类型不兼容，全仓 typecheck 红）。
+   *
+   * 草稿保留的真实实现在 TUI 侧：`InputRegion.handleSubmitWithDraftGuard` 用同步可得的
+   * `needsSetup` 判据返回 `'rejected'` 给 `PromptInput`（见其头注释）——判据更早、更准，
+   * 不依赖宿主异步结论。故此处收窄回 `void`，不留误导性的死契约。
+   */
+  onSubmit?: (text: string, mode: SubmitMode, intent?: SubmitIntent) => void;
+  /**
+   * 引擎真·忙判定探针（session.isBusy）。提交分流(routeSubmit)与出队(drainQueue)的判忙以此为准，
+   * 不再信 TUI 的 state.processing 镜像态——镜像态会被断点暂停 setAgentProcessing(false)、完成事件
+   * 抢跑等窗口骗成"空闲"，导致消息在引擎仍忙时漏到起新回合 → 撞裸 prompt() 抛 "Agent is processing"。
+   * 缺省（未接线）回落到 state.processing，保持纯前端可单测。
+   */
+  isAgentBusy?: () => boolean;
+  /**
+   * RFC-180 D6：turn 边界暂停态探针（AgentSession.isPaused）。与 isAgentBusy 正交——
+   * 暂停生效后 isAgentBusy() 天然变回 false，但暂停仍应阻止 drainQueue 自动出队，故
+   * agentBusy() 组合链需额外 OR 本探针。缺省（未接线）视为未暂停，行为与改动前一致
+   * （fail-open，同 isAgentBusy 缺省语义）。
+   */
+  isPaused?: () => boolean;
+  /**
+   * 命令名（小写,无 /）是否为「本地立即处理、不起 agent 回合」的注册命令（cli 的 CLI_COMMANDS）。
+   * 决定运行中斜杠命令立即执行 vs 入队——未注册命令(fallthrough)放行会撞 isBusy,必须入队。
+   */
+  isImmediateCommand?: (command: string) => boolean;
+  /**
+   * 命令名是否为「中止当前回合」命令(/abort)。运行中也立即放行→onSubmit 直接走中断入口,
+   * 不被当普通斜杠命令入队(否则中止要等当前回合跑完才回放,彻底失效)。
+   */
+  isInterruptCommand?: (command: string) => boolean;
+  onInterrupt?: () => void;
+  /**
+   * 问 AI（RFC-225 M2）：shell 面板错误态下 `a` 键触发。cli 侧应读取
+   * `tui.getShellExecutionSnapshot()` 组装消息，经自身 `onSubmit`/`handleSubmit`
+   * 提交到当前会话，并在提交后关闭对应面板（`dismissShellExecution()` /
+   * `setShellFullOutput(null)`，具体哪个由触发来源决定，cli 侧不感知触发来源，
+   * TUI 侧统一在两处调用点各自负责关闭，见 AppProps.onShellAskAi 的两个消费方）。
+   */
+  onShellAskAi?: () => void;
+  /**
+   * ESC 撤回 pending 消息时触发——TUI 侧已完成 UI 清理（占位消息/文本回填/清 pendingEcho），
+   * CLI 侧据此判定是否需直接 abort（不弹对话框）。text=原文、mode=提交模式。
+   */
+  onWithdrawPending?: (text: string, mode: string) => void;
+  /**
+   * RFC-337 D3：ESC 撤回一条运行中追加（steer）时触发。CLI 侧 `session.removeSteer(id)`
+   * 命中（未被模型消费）→ `withdrawPendingSteer` 清 live 回显；未命中（已 drain）→ 退化
+   * `requestStop('abort')` 中止整回合。id = steer 稳定 id（setPendingSteer 记录）。
+   */
+  onWithdrawSteer?: (id: string) => void;
+  /**
+   * M-N3：A2UI Button 真交互回调——用户按数字键 1-9 触发时，TUI 据此通知 CLI 执行对应 action。
+   * CLI 侧收到后经 dispatchCliCommand('a2ui-action', [componentId, action, ...]) 分流到 handleA2uiAction。
+   */
+  onA2uiAction?: (componentId: string, action: string, payload?: Record<string, unknown>) => void;
+  /**
+   * RFC-116 M5：`/perf` 面板内手动刷新键（r）触发——CLI 侧重新执行 `handlePerf` 的核心
+   * 采集逻辑（内存/渲染/插件三类数据源），回填后面板自动重渲（数据经 setPerf* 系列
+   * TuiHandle 方法喂回，不由本回调直接返回值）。手动触发，不做自动轮询（对齐 D7）。
+   */
+  onPerfRefresh?: () => void;
+  /** /tasks 面板：k 杀选中后台进程。 */
+  onBackgroundKill?: (id: string) => void;
+  /** /tasks 面板：o 看选中后台进程输出（cli 据此启动 logPath tail 轮询）。 */
+  onBackgroundViewOutput?: (id: string) => void;
+  /** 退出实时输出跟随（esc）：cli 据此停轮询并清空视图。 */
+  onBackgroundOutputClose?: () => void;
+  /** a 键应用 ready 的 agent-session 作业 diff 到主仓。 */
+  onBackgroundApply?: (id: string) => void;
+  /** 向运行中的 delegate 补充信息（输出视图内打字 + Enter）。 */
+  onDelegateSupply?: (id: string, text: string) => void;
+  /** ctrl+s 保存当前输入为一条自动命名的草稿（随会话快照持久化，cli 侧写 session.setDrafts + save）。 */
+  onDraftSave?: (text: string) => void;
+  /**
+   * `@` 面板选中一条条目后回调（`#` hashtag 不计入——@ 面板 MRU 语义只服务 @ sigil）。
+   * cli 侧据此写入 `settings.recent_mentions`（MRU push + 落盘）并调用
+   * `tui.setRecentMentions()` 回推最新列表——单向数据流对齐 onDraftSave/setDrafts。
+   */
+  onSigilSelect?: (entry: SigilEntry) => void;
+  /** DraftPane 内 d 删除选中草稿（cli 侧从 session.setDrafts 移除 + save）。 */
+  onDraftDelete?: (id: string) => void;
+  /** DraftPane 内 d 批量删除全部勾选（Space 多选）的草稿——单次 setDrafts + 单次 save，
+   *  避免 N 条依次调用 onDraftDelete 触发 N 次并发落盘。 */
+  onDraftDeleteMany?: (ids: string[]) => void;
+  /**
+   * QueueEditDialog「直接发送」：TUI 侧已把该项出队，text/mode 为出队前的原始内容——
+   * cli 层按 mode 分流：'send' 复用 handleSubmit 的 steer/send 语义（busy→steer 注入
+   * 当前回合，idle→立即起新回合）；'bash'/'bash_async'/'memory' 走各自原始执行通道
+   * （不套 steer 语义）。见 QueueEditDialog.tsx 头注释。
+   */
+  onQueueSendNow?: (text: string, mode: SubmitMode) => void;
+  /** enter 键切换对话流到 sub-agent。 */
+  onBackgroundSwitch?: (id: string) => void;
+  /** d 键删除已终结的委派项（cli 据类型分派到对应 registry.remove）。 */
+  onBackgroundDelete?: (id: string) => void;
+  /** esc 退出 sub-agent 对话流（CLI 停轮询 + unpin + retain(false)）。 */
+  onSubagentExit?: () => void;
+  /** 持久化输入历史初始条目（从磁盘恢复，传给 PromptInput）。 */
+  initialHistory?: string[];
+  /** RFC-129：外部 shell 历史命令（只读，ghost/Ctrl+R）。 */
+  externalHistoryCommands?: readonly string[];
+  /** 持久化草稿初始列表（随会话快照恢复，cli 侧从 session.session.getDrafts() 读取）。 */
+  initialDrafts?: DraftItemView[];
+  /** 持久化「最近 @ 到的资源」初始列表（cli 侧从 app.settings.get('recent_mentions') 读取，
+   *  结构随 RecentMentionEntry→SigilEntry 转换，见 recent-mentions.ts）。 */
+  initialRecentMentions?: SigilEntry[];
+  /** 每次 push 新历史条目时回调——携带完整 entries 供 CLI 落盘。 */
+  onHistoryPush?: (entries: readonly string[]) => void;
+  /**
+   * RFC-300 M2：加载更早历史（DB 补页）。上滚到内存顶部折叠接缝时调用——
+   * 补页锚由 CLI 侧闭包维护（resume 尾窗口 / 实时启动时 entryCount），TUI 只发
+   * `{limit}` 请求；返回更早消息数组（带稳定 id `hist-<seq>` 与 seq）或 null
+   * （无更早——优雅结束补页）。
+   */
+  loadHistory?: (req: {
+    limit: number;
+  }) => Promise<ChatMessage[] | null>;
+  onStop?: () => void;
+}
+/** 插件面板注册（TUI 侧镜像，同 PluginPane.PanelInfo 但含 id）。 */
+interface TuiPanelRegistration {
+  /** 面板唯一 id（`pluginId:panelId`）。 */
+  id: string;
+  /** 面板标题。 */
+  title: string;
+  /** 已编译组件的绝对路径（同 PluginPane.PanelInfo.modulePath）。 */
+  modulePath: string;
+  /** 导出名（'default' 或具名）。 */
+  exportName: string;
+  /** 面板所属插件 id（RFC-165 M2 T7，供 `usePanelBackend()` 定位 backend server）。 */
+  pluginId?: string;
+}
+/**
+ * a2ui 组件渲染函数签名（RFC-105 D1/D6, RFC-155 M155-3），与 `@x-otto/coding
+ * a2ui-component-loader.ts` 的 `PluginA2uiRenderFn` 同构（结构相同、跨包各自定义类型，
+ * 避免 tui→coding 反向类型依赖）。`resolveChild` 由宿主（`a2ui-renderer.ts`）闭包持有
+ * `visited` 循环引用防护，插件侧不可绕过——见 RFC-155 §3 D4。
+ */
+type PluginA2uiRenderFn = (component: unknown, columns: number, resolveChild: (id: string) => string[]) => string[];
+/** 单条已注册的 a2ui 组件（TUI 侧运行时形态）。 */
+interface RegisteredA2uiComponent {
+  /** 组件类型名（跨插件全局命名空间，供渲染分发按 type 查表）。 */
+  type: string;
+  pluginId: string;
+  render: PluginA2uiRenderFn;
+}
+/** 单插件注册数据（宿主侧构造，经 TuiHandle.setPluginRegistrations 喂入）。 */
+interface PluginRegistration {
+  /** 插件 id（宿主侧传入的 plugin.id，唯一标识）。 */
+  pluginId: string;
+  /** 消息渲染器（原 registerPluginRenderers 的数据）。 */
+  renderers?: readonly RegisteredRenderer[];
+  /** 状态栏文本条目（原 setPluginStatusItems 的数据）。 */
+  statusItems?: readonly {
+    id: string;
+    text: string;
+  }[];
+  /** 插件面板注册。 */
+  panels?: readonly TuiPanelRegistration[];
+  /** 命令表（typeahead 数据源，原 setCommands 的数据）。 */
+  commands?: readonly CommandEntry[];
+  /** a2ui 组件扩展（RFC-105 D1/D6, RFC-155 M155-3：插件扩展 a2ui 渲染 catalog）。 */
+  a2uiComponents?: readonly RegisteredA2uiComponent[];
+  /** 状态栏代码式徽标（RFC-184 D2/D3：插件贡献带颜色语义/动态数据的状态栏徽标）。 */
+  statusWidgets?: readonly RegisteredStatusWidget[];
+  /** 文件查看器候选视图（RFC-187 D3/D5：插件贡献的文件类型专属渲染候选）。 */
+  fileViewers?: readonly RegisteredFileViewer[];
+}
+interface TuiModalHandle {
+  /**
+   * 模态对话框统一通道——收敛原 openInfo/openPermissions/openContext/openMemory/
+   * openSelect/openExtensionDetail/openInput/openQuestions/openConfirm 九个独立方法。
+   * 'input'/'questions' 分支返回 Promise（等待用户输入/选择后 resolve），其余七个分支同步
+   * void（fire 回调后立即返回）。三组重载覆盖返回类型正确推断，与判别联合 kind 一一对应。
+   *
+   * ⚠️ 同一 dialog 生命周期内禁止重复调用 openModal（RFC-285）。
+   * 同步路径每次调用都是 router push 新栈条目（非 replace），重复调用会导致对话框堆积、
+   * 用户需多次 Esc 退出。需要更新已打开 dialog 内容时：
+   * - select：使用 `async` 字段（RFC-227），框架自动 replace
+   * - progress：使用 `updateProgress()`，框架自动 replace
+   * - 其他 kind：先关闭当前 dialog（用户操作触发 goBack）再 openModal
+   */
+  openModal(req: ModalRequestInput): Promise<string | null>;
+  openModal(req: ModalRequestQuestions): Promise<QuestionsAnswer | null>;
+  openModal(req: ModalRequestOnboarding): Promise<OnboardingResult>;
+  openModal(req: ModalRequestVoid): void;
+  /** 通用提示对话框（只读信息 + [OK]）：Enter/Esc 解除，回调 onOk。 */
+  openAlert(req: AlertRequest): void;
+  /** 通用单行输入对话框：Enter 提交当前输入，Esc 取消。
+   *  返回 Promise：Enter 提交→输入串，Esc 取消→null。 */
+  openPrompt(req: PromptRequest): Promise<string | null>;
+  /** 更新 install 进度条 dialog 状态（progress modal 打开后调用）。 */
+  updateProgress(partial: ProgressUpdate): void;
+  /**
+   * 程序化 settle 当前在场的 confirm 对话框（等价用户点按钮）。
+   *
+   * 唯一消费方是 `requestStop().escalateToExit()`（Ctrl+C 升级阶梯二级）：把在场的停止框
+   * 就地升级为「终止并退出」后，必须**经本方法**走 resolver 通道 settle，而不是绕过它直接
+   * 执行副作用——绕过会导致 resolver 不清空、路由不 goBack，留下无法关闭的孤儿条目。
+   *
+   * 幂等：无 confirm 在场（resolver 已空）时为 no-op。
+   *
+   * @param confirmed true = 确认（触发 onConfirm）；false = 取消（触发 onCancel）
+   */
+  resolveConfirm(confirmed: boolean): void;
+  /** 权限请求：渲染对话框并等用户决定（工具使用确认队列）。
+   * 返回 approved + mode（'always'=用户选「始终允许」，cli 据此持久化）。 */
+  requestPermission(req: {
+    tool: string;
+    input: string;
+    risk?: 'low' | 'medium' | 'high';
+    description?: string; /** bash「始终允许」拟持久化的命令前缀（如 `git status`），弹窗显式呈现给用户。 */
+    alwaysAllowLabel?: string;
+  }): Promise<PermissionDecision>;
+}
+interface TuiPendingHandle {
+  /** 标记最后一条 user echo 为『pending』——ESC 撤回窗口的起点。 */
+  setPendingEcho(text: string, mode: string): void;
+  /** 模型已接起首字节，关闭 ESC 撤回窗口（pending 转正）。 */
+  clearPendingEcho(): void;
+  /** ESC 撤回 pending 消息——从对话流移除最后一条 user echo + 回填输入框 + 清 pendingEcho。 */
+  withdrawPendingEcho(): void;
+  /** RFC-337 D3：注入一条运行中追加（steer）的待定 echo（延迟 commit，live 区渲染）。 */
+  setPendingSteer(text: string, id: string): void;
+  /** RFC-337 D3：steer 被模型消费 → 转正 commit 到 scrollback（此后不再可撤回）。 */
+  commitPendingSteer(id: string): void;
+  /** RFC-337 D3：ESC 撤回未被消费的 steer 追加——清 live 区渲染，不 commit。 */
+  withdrawPendingSteer(id: string): void;
+  /** RFC-337 D3：回合结束时清空所有仍待定的 steer（未被消费的 steer 不会再进上下文，防跨回合残留）。 */
+  clearPendingSteers(): void;
+  /** 把指定文本回填到 PromptInput（ESC 撤回时用）。 */
+  restoreInputText(text: string): void;
+  /** RFC-338：把持久化的粘贴缓存恢复进输入框 store（启动/切会话/fork 时调用）。 */
+  hydratePaste(snapshot: PasteSnapshot | null | undefined): void;
+  /** RFC-338：导出当前粘贴缓存快照供落盘；桥未就绪（TUI 未挂载）时返回 null。 */
+  exportPaste(): PasteSnapshot | null;
+}
+interface TuiPanesHandle {
+  /** 面板 open/toggle 统一通道——收敛原 toggleHistory/toggleBackgroundTasks/
+   * toggleDraftPane/toggleQueuePane/toggleNotifications/toggleInspector/openSchedulePane/
+   * openPerf/openCacheStats/openGallery 十个独立方法。 */
+  togglePane(name: PaneName, open?: boolean): void;
+  /** 打开/关闭 /services 进程服务列表面板。 */
+  setServices(open: boolean): void;
+  /** 切换到 sub-agent 对话流。传入 null 清除（esc）。 */
+  switchToSubagentContext(ctx: SubagentContext | null): void;
+  /** 开关编辑文件面板（Ctrl+V）。open 省略=翻转。 */
+  toggleEditedFiles(open?: boolean): void;
+  /** 清空编辑文件列表。 */
+  clearEditedFiles(): void;
+  /** 按索引删除一条排队项（QueuePane 内 d 键）。 */
+  removeQueuedAt(index: number): void;
+  /** 清空全部排队项（/queue clear）。 */
+  clearQueue(): void;
+  /** 把队列中 index 处的项移动 delta 位（-1=上移/下移+1，越界时 no-op）（QueuePane 内 J/K 键）。 */
+  moveQueuedItem(index: number, delta: number): void;
+}
+interface TuiPluginsHandle {
+  /** 统一插件注册入口——替代 setPluginStatusItems 等 4 个独立方法。 */
+  setPluginRegistrations(regs: readonly PluginRegistration[]): void;
+  /** 按源卸载插件全部贡献（热重载/禁用时调用）。 */
+  unregisterPluginSource(pluginId: string): void;
+  /** 存量委托：插件状态栏文本条目（被 setPluginRegistrations 替代）。 */
+  setPluginStatusItems: (items: Array<{
+    icon: string;
+    text: string;
+    color?: 'warning' | 'default';
+  }>) => void;
+  /** 更新斜杠命令表（typeahead 数据源）；语言切换后 cli 回推本地化描述。 */
+  setCommands(commands: CommandEntry[]): void;
+  /** 注册斜杠命令的参数补全函数。 */
+  registerArgumentSuggester(command: string, suggester: (prefix: string, maxResults?: number) => Array<{
+    name: string;
+    description?: string;
+  }>): void;
+  /** 注册当前消息流中的 A2UI 按钮（用于数字键 1-9 快捷触发）。 */
+  setA2uiButtons(buttons: A2uiButtonInfo[]): void;
+  /** 注入持久化恢复的子代理条目到累计 Map（--continue 重建面板）。 */
+  addSubagent(entry: {
+    id: string;
+    name: string;
+    status: 'running' | 'done' | 'error' | 'killed';
+    startedAt?: number;
+  }): void;
+  /** 获取子代理累计 Map（供持久化，stat-only）。 */
+  getSubagents(): ReadonlyMap<string, BackgroundTaskSummary>;
+  /** 清空子代理累计列表（跨回合重置）。 */
+  clearSubagents(): void;
+}
+interface TuiInfoHandle {
+  /** 推送一条通知到通知中心（状态栏铃铛 +1，ctrl+n 查看）。 */
+  pushNotification(title: string, message: string, source?: AppNotification['source'], level?: AppNotification['level']): void;
+  /** 消除单条通知。 */
+  dismissNotification(id: number): void;
+  /** 全部标已读（esc 关闭通知中心时）。 */
+  markAllNotificationsRead(): void;
+  /** 读取 notify scheduler 统计（coalesced 调用/触发、immediate 调用、flush 触发）。 */
+  getNotifyStats(): NotifyStats;
+  /** 当前路由路径（树外只读探针）。 */
+  getCurrentPath(): string;
+  /** 当前是否有强制升级横幅在场（taskStore.forcedUpgrade 非 null）。 */
+  isForcedUpgradeActive(): boolean;
+  /** 是否有全屏/独占视口面板在场（子代理详情、后台任务输出、编辑文件全屏、shell 执行面板等）。 */
+  isFullScreenPaneActive(): boolean;
+  /** 读取当前 shell 执行的结构化快照（RFC-225 M2）。 */
+  getShellExecutionSnapshot(): {
+    command: string;
+    output: string;
+    exitCode: number | null;
+    terminated?: boolean;
+  } | null;
+  /** 追加一条对话回合行到 ContextDetailPane（CLI 从会话消息构建）。 */
+  addContextTurn(row: ConversationTurnRow): void;
+  /** 批量更新回合标记（compacted/truncated/pruned —— trace 事件驱动）。 */
+  markContextTurns(patch: {
+    turnIndex: number;
+  } & Partial<ConversationTurnRow>): void;
+  /** 弹出 toast 通知（自动 2 秒消失，不占用对话历史）。 */
+  showToast(title: string, content: string): void;
+  /** 从 Home 进入某会话视图。cli 首次 prompt（interactive-events prompt.start）
+   * 或切会话/resume 后单向下推。 */
+  setTopView(view: {
+    session: string;
+  }): void;
+}
+interface TuiEngineHandle {
+  /** 高频流式事件统一通道——收敛原 8 个独立 setter 为单一判别联合方法。 */
+  pushEngineEvent(event: TuiStreamEvent): void;
+  /** 是否有待跑的 follow-up（state.queued 非空）——cli 喂 app 抑制完成通知。 */
+  hasQueuedFollowUp(): boolean;
+  /** 取出最近追加的 follow-up。错误重试优先消费最近追加意图，而非最早失败原 prompt。 */
+  takeLastQueuedFollowUp?(): {
+    text: string;
+    mode: SubmitMode;
+  } | undefined;
+  /**
+   * 把一条提交塞进"回合之后"队列（state.queued，与 Shift+Enter 同一队列），引擎空闲时自动出队起新回合。
+   * 供 cli 兜底：若消息因镜像态去同步漏到"引擎仍忙却走起新回合"的路，按此回落到回合后队列，
+   * 而非撞裸 prompt() 抛错。出队由 drainQueue 以引擎真·忙判定为闸，不会在忙时立即回拉打转。
+   */
+  enqueueFollowUp(text: string, mode?: SubmitMode): void;
+  /** 设置暂停浮层数据。非 null 时 App.tsx 渲染 PauseDialog 组件。 */
+  setPauseDialog(item: PauseDialogItem | null): void;
+  /** 展示退避重试倒计时条。 */
+  showRetryDialog(attempt: number, max: number, delayMs: number, accelerate: {
+    skip: boolean;
+  }, onExpired: () => void, reason?: string, onStop?: () => void): void;
+  /** 强制清除当前退避倒计时。 */
+  clearRetryDialog(): void;
+  /** 展示统一错误重试卡片（覆盖回合终止性错误的全部场景）。 */
+  showErrorRetry(item: {
+    reason: string;
+    attempt: number;
+    max: number;
+    mode: 'auto' | 'resetsAt' | 'manual';
+    resetsAt?: number;
+    limitType?: RateLimitType;
+    actions: Array<{
+      kind: ErrorRetryActionKind;
+      label: string;
+      run: () => void;
+    }>;
+    exhausted?: boolean;
+    onExpired: () => void;
+    onCancel: () => void; /** RFC-153 D6：错误来源插件 id；undefined=非插件来源，卡片不展示来源行。 */
+    pluginSource?: string; /** RFC-230：mode='auto' 自动倒计时秒数（默认 30，可经 ResilienceConfig.errorRetry.intervalMs 覆盖）。 */
+    intervalSeconds?: number;
+  }): void;
+  /** 强制清除当前错误重试卡片。 */
+  clearErrorRetry(): void;
+}
+interface TuiMessagesHandle {
+  /** 追加一条对话消息到转录（scrollback/window 双模内部分流）。 */
+  pushMessage(msg: ChatMessage): void;
+  /** 批量提交多条历史（resume/会话切换回放）：scrollback 模式下合成单次写出 →
+   *  避免逐条 inkWrite 的 N 次 live 区清/还原抖动（缓冲整段后单次 flush）。 */
+  pushMessages(msgs: readonly ChatMessage[]): void;
+  /** 回显用户输入。`pending=true` 标记为 pending 态（dim 渲染 + ESC 可撤回）。 */
+  echoUserInput(text: string, opts?: {
+    pending?: boolean;
+  }): void;
+  /** 按回合编号获取对应消息列表（turn 1-based）。 */
+  getTurnMessages(turn: number): ChatMessage[];
+  /** 获取当前回合边界数组快照。 */
+  getTurnBoundaries(): number[];
+  /** 获取当前编辑文件列表快照（持久化用）。 */
+  getEditedFiles(): EditedFileEntry[];
+}
+interface TuiLifecycleHandle {
+  /** 停止 TUI（卸载 Ink 渲染树 + 清理平台副作用）。 */
+  stop(): void;
+  /** 清屏并重置会话界面状态（/clear）：
+   *   - 清终端（ANSI \x1B[2J\x1B[H）和 scrollback 状态
+   *   - 清除任务面板、委托面板、动态区状态
+   *   - 重新显示欢迎横幅
+   */
+  clearSession(): void;
+  /** 运行时切语言（/lang 或 Ctrl+Y）；返回最终生效的具体语言。notify 全树重渲即时生效。 */
+  setLanguage(mode: LangMode): Lang;
+  /**
+   * RFC-277 M6 / RFC-283：运行时切换/预览 preset 选择（`/preference theme` 高亮移动即预览、确认
+   * 后落定；传 `undefined` 清空回退到各 appearance 的 builtin preset）。深浅自动跟随终端背景色。
+   */
+  setPresetSelection?(selection: ThemePresetSelection | undefined): void;
+  /** 写入终端窗口标题（OSC 0，\x1b]0;...\x07）。非 tty 时无操作。
+   *  标题经 sanitize 后写入：strip 控制字符、零宽字符、压缩空白、truncate 240 字符。 */
+  setTerminalTitle(title: string): void;
+  /** RFC-312 D5：切换鼠标协议（应用内选择 ↔ 终端原生选择）。返回切换后状态。
+   *  闭包捕获 handle 引用——调用时 handle.info.showToast 已存在（非构造期）。 */
+  toggleMouse(): boolean;
+  /** RFC-335 T335-07：attach source belongs to this TUI root; lifecycle.stop detaches it. */
+  attachSessionSource(source: SessionDataSource): Promise<() => void>;
+  /** Stop the attached source explicitly; idempotent. */
+  detachSessionSource(): void;
+}
+interface TuiShellHandle {
+  /** 开始异步 shell 执行面板（`!! <cmd>`）。显示固定高度输出区，non-blocking。 */
+  startShellExecution(command: string): void;
+  /** 追加输出到 shell 执行面板。 */
+  appendShellOutput(text: string): void;
+  /** 完成 shell 执行：更新退出码/状态。面板保持打开，由用户 Esc 手动关闭。 */
+  finishShellExecution(exitCode: number | null, error?: string, terminated?: boolean): void;
+  /** 手动关闭 shell 执行面板。 */
+  dismissShellExecution(): void;
+  /** 复制当前 shell 执行的完整输出到系统剪贴板（OSC 52，RFC-225 M1）。纯读操作。 */
+  copyShellOutput(): void;
+  /** 读取当前 shell 执行的结构化快照（RFC-225 M2，供 cli 层组装"问 AI"消息）。 */
+  getShellExecutionSnapshot(): {
+    command: string;
+    output: string;
+    exitCode: number | null;
+    terminated?: boolean;
+  } | null;
+}
+interface TuiHandle {
+  /**
+   * RFC-347 M1：模态对话框/问询/权限确认能力的领域命名空间。
+   * 调用方应使用 `tui.modal.openModal(...)`/`tui.modal.openAlert(...)`/...
+   */
+  readonly modal: TuiModalHandle;
+  /**
+   * RFC-347 M1.1：pending echo/pending steer/输入框回填/粘贴缓存的领域命名空间。
+   * 调用方应使用 `tui.pending.setPendingEcho(...)`/`tui.pending.withdrawPendingEcho(...)`/...
+   */
+  readonly pending: TuiPendingHandle;
+  /**
+   * RFC-347 M1.2：生命周期/全局配置能力（stop/clearSession/语言/主题/终端元信息/鼠标切换）。
+   * 调用方应使用 `tui.lifecycle.stop()`/`tui.lifecycle.setLanguage(...)`/...
+   */
+  readonly lifecycle: TuiLifecycleHandle;
+  /**
+   * RFC-347 M1.3：消息回显/转录获取能力的领域命名空间。
+   * 调用方应使用 `tui.messages.pushMessage(...)`/`tui.messages.getTurnMessages(...)`/...
+   */
+  readonly messages: TuiMessagesHandle;
+  /**
+   * RFC-347 M1.4：引擎事件推送 + 暂停/重试/错误卡片浮层 + 回合后队列管理的领域命名空间。
+   * 调用方应使用 `tui.engine.pushEngineEvent(...)`/`tui.engine.showErrorRetry(...)`/...
+   */
+  readonly engine: TuiEngineHandle;
+  /**
+   * RFC-347 M1.5：面板开关（togglePane/setServices/switchToSubagentContext 等 +
+   * 队列管理（removeQueuedAt/clearQueue/moveQueuedItem）领域命名空间。
+   * 调用方应使用 `tui.panes.togglePane(...)`/`tui.panes.setServices(...)`/...。
+   */
+  readonly panes: TuiPanesHandle;
+  /**
+   * RFC-347 M1.5：插件注册（setPluginRegistrations/unregisterPluginSource 等 +
+   * 子代理数据（addSubagent/getSubagents/clearSubagents）领域命名空间。
+   */
+  readonly plugins: TuiPluginsHandle;
+  /**
+   * RFC-347 M1.5：通知中心（pushNotification/dismissNotification 等 + 状态读取
+   * （getNotifyStats/getCurrentPath/isForcedUpgradeActive 等 + context feed + toast + topView。
+   */
+  readonly info: TuiInfoHandle;
+  /** RFC-347 终局：shell 执行面板生命周期域。调用方经 `tui.shell.*` 访问。 */
+  readonly shell: TuiShellHandle;
+  /**
+   * RFC-333 M2-B：store 引用出口（D1 方案A）。cli 经此直接调 store action 写数据，
+   * 逐步替代 TuiHandle 上的字段 setter——store 成为唯一写入汇聚点（T335-07 换 writer 的 seam）。
+   * 迁移期只暴露已收敛为 action 的 store 域；每迁完一组即从本对象加入、并从 TuiHandle 删对应 setter。
+   */
+  stores: {
+    tasks: TaskActions;
+    budget: Pick<BudgetStore, 'setBudget'>;
+    context: Pick<ContextStore, 'setBudget' | 'addTurn' | 'markTurns'>;
+    cache: Pick<CacheStore, 'setView'>;
+    proxy: Pick<ProxyStore, 'setView'>;
+    notification: Pick<NotificationStore, 'setProviderUsage' | 'setPausePending' | 'setPaused' | 'setPulseSurvey'>;
+  };
+}
+/** 一条草稿记录（DraftPane 数据源 · /draft 命令 · Ctrl+S/O）。 */
+interface DraftItemView {
+  id: string;
+  name: string;
+  text: string;
+  savedAt: number;
+}
+/** 模态单选请求（openSelect 入参）。 */
+interface SelectRequest {
+  title?: string;
+  subtitle?: string;
+  /** 副标题语义色调：default=普通弱化提示；warning=需要用户处理的醒目提示。 */
+  subtitleTone?: 'default' | 'warning';
+  options: SelectOption[];
+  onSelect: (value: string) => void;
+  onCancel?: () => void;
+  /** 单屏可见物理行数（默认 10；/model、/resume 可加高）。 */
+  maxVisible?: number;
+  /** 开启搜索过滤输入框（如 /resume 会话列表）。 */
+  searchable?: boolean;
+  /** 渲染形式：'list'（默认）｜'buttons'（横排 [ 按钮 ] 行，Tab 切换）｜'tabs'（横排选项卡，Tab 切换）。 */
+  layout?: 'list' | 'buttons' | 'tabs';
+  /** 副标题内联动作按钮（list 模式逃生口，如无可用模型时的 [登录]/[配置凭证]）；触发经 onSelect 回吐其 value。 */
+  subtitleActions?: Array<{
+    label: string;
+    value: string;
+  }>;
+  /**
+   * detail 排布位置（RFC-292 D1）：`'below'`（缺省）detail 独占条目下方一行（适合变长
+   * 多段文本，如 `/model` 的 `coding/reasoning/knowledge`）；`'inline'` detail 并入 label
+   * 同一行右侧、按组内最大宽度对齐（适合短徽章，如 `/login` provider 选择的 `订阅`/`密钥`）。
+   */
+  detailPlacement?: 'below' | 'inline';
+  /**
+   * 初始过滤文本（searchable 模式）——modal 被销毁重建的场景下恢复用户上次输入的
+   * 过滤词（如 `/open` 目录浏览器）。缺省空串。
+   */
+  initialFilter?: string;
+  /** 过滤文本变化回调——调用方据此持久化过滤词，供下次重建时经 initialFilter 回灌。 */
+  onFilterChange?: (text: string) => void;
+  /**
+   * RFC-277 M6：高亮项变化回调（移动即预览，语义同 `SelectDialogProps.onHighlight`）。
+   * 与 `onSelect`（Enter 确认）分离，调用方不应假定 onHighlight 代表用户已确认。
+   */
+  onHighlight?: (value: string) => void;
+  /** 初始游标位置——按 value 匹配 options（偏好面板返回父级时保留游标位置）。 */
+  defaultSelectedValue?: string;
+  /**
+   * RFC-253 续/偏好面板闪动修复：就地替换当前 select 弹窗的 state（不 push 新栈条目）。
+   * 用于「布尔项就地翻转」这类**同一弹窗内容原地更新**场景——避免每次翻转都 openModal
+   * 重开导致整屏闪动/Esc 栈堆积（RFC-285 D2 的 re-entrant push 问题）。仅当当前路由已是
+   * `/dialog/select` 时生效（等价 async 路径的 `navigate(replace:true)` 语义）；否则退化为
+   * 正常 push。SelectDialog 组件不重挂 → 本地 useState（过滤/游标）保留、无闪动。
+   */
+  replace?: boolean;
+  /**
+   * RFC-227：异步内容加载 promise——调用方声明"options/subtitle/title 不是同步可用的"，
+   * 需经一次 async 操作（如网络请求、SQLite 扫描）才能构造。框架层自动展示 loading 占位
+   * （options=[] 空数组，subtitle 展示 loading 文案），resolve 后原地过渡为真实内容。
+   *
+   * ⚠️ 仅对 `kind: 'select'` 有效——传入其他 modal 类型时被框架层静默丢弃（R1）。
+   * 与 `options` 互斥——传了 `async` 就不该传 `options`（框架层以 async 优先），
+   * 但 TypeScript 类型层面不会报错（非类型级互斥）。
+   */
+  async?: Promise<SelectAsyncContent>;
+}
+/**
+ * RFC-227 D3：`SelectRequest.async` resolve 的返回值——框架层 merge 回原始
+ * `SelectRequest` 的不变字段（`onSelect`/`onCancel`/`layout`/`searchable`/
+ * `subtitleActions` 等），实现"一次声明、自动过渡"。
+ *
+ * merge 策略：`{ ...req, ...content }`——content 中的字段覆盖 req 中的同名字段，
+ * 不在本接口中的字段保持调用方原始值不变（纯透传，lesson_104 纪律）。
+ */
+interface SelectAsyncContent {
+  /** 异步加载完成后替换 loading title 的新标题（可选；缺省保持 loading 态 title）。
+   *  例：/search loading title "Search 'keyword'" → resolve 后 "Search 'keyword' — 20 hits"。 */
+  title?: string;
+  /** 异步加载完成后替换 loading subtitle 的新文案（可选）。 */
+  subtitle?: string;
+  /** 异步加载完成后的真实选项列表。 */
+  options: SelectOption[];
+}
+/** 模态输入请求（openInput 入参）。 */
+interface InputRequest {
+  title?: string;
+  /** 正文描述行（如 OAuth 授权 URL），展示在标题与输入框之间，支持多行、自动换行。 */
+  description?: string[];
+  placeholder?: string;
+  /** 初始值（预填输入框，如 /fork 的命名预填源会话标题）。 */
+  defaultValue?: string;
+  mask?: boolean;
+  /** 外部取消信号（如 OAuth loopback 回调先完成）：abort 时关闭输入框并 resolve null。 */
+  signal?: AbortSignal;
+  /** 输入框下方可选的 action 按钮（如 OAuth 流程里的「打开浏览器」）。 */
+  actionButton?: {
+    label: string;
+    onPress: () => void;
+  };
+}
+/** 多问题复核请求（openQuestions 入参）。 */
+interface QuestionsRequest {
+  title?: string;
+  questions: Question[];
+}
+/** 通用确认对话框请求（openConfirm 入参）。 */
+interface ConfirmRequest {
+  title: string;
+  /** 正文（单行或多行）。 */
+  message: string | string[];
+  /** 确认按钮文案（默认 i18next.t('common.confirmButton')）。 */
+  confirmLabel?: string;
+  /** 取消按钮文案（默认 i18next.t('common.genericCancelButton')）。 */
+  cancelLabel?: string;
+  /** 确认按钮颜色（默认 'accent'）。 */
+  confirmColor?: 'accent' | 'amber' | 'red' | 'green';
+  /** 破坏性确认：默认焦点落「取消」（中止/删除等防误触）。 */
+  dangerous?: boolean;
+  /** 可选的第三个按钮（位置在确认和取消之间）。不传=双按钮。 */
+  extraLabel?: string;
+  /** 第三个按钮颜色（默认 'amber'）。 */
+  extraColor?: 'accent' | 'amber' | 'red' | 'green';
+  onConfirm: () => void;
+  onCancel?: () => void;
+  /** 第三个按钮回调（仅在 extraLabel 提供时生效）。 */
+  onExtra?: () => void;
+}
+/** 通用提示对话框请求（openAlert 入参）。 */
+interface AlertRequest {
+  title: string;
+  /** 正文（单行或多行）。 */
+  message: string | string[];
+  /** OK 按钮文案（默认 i18next.t('common.okButton')）。 */
+  okLabel?: string;
+  onOk?: () => void;
+}
+/** 通用单行文本输入对话框请求（openPrompt 入参）。 */
+interface PromptRequest {
+  title?: string;
+  /** 提示正文（单行或多行）。 */
+  message?: string | string[];
+  placeholder?: string;
+  initialValue?: string;
+  /** 提交按钮文案（默认 i18next.t('prompt.submitButton')）。 */
+  submitLabel?: string;
+  /** 取消按钮文案（默认 i18next.t('common.genericCancelButton')）。 */
+  cancelLabel?: string;
+}
+interface PermissionDecision {
+  approved: boolean;
+  mode?: 'once' | 'always';
+}
+/** sub-agent 对话流上下文切换时 TuiHandle.switchToSubagentContext 的入参。 */
+interface SubagentContext {
+  id: string;
+  title: string;
+  messages: ChatMessage[];
+  status: 'running' | 'needs_input' | 'ready' | 'applied' | 'failed' | 'canceled';
+  /** 诊断块（卡死/空闲/blockedOn 等，来自 agentDiagnostics）。 */
+  diagnostics?: string[];
+  /** turn timeline 行。 */
+  timeline?: string[];
+  /** 流式中 in-flight 文本（running 态持续刷新）。 */
+  streamText?: string;
+}
+//#endregion
+//#region src/dialogs/ConfirmDialog.d.ts
+interface ConfirmDialogProps {
+  title: string;
+  /** 正文（单行或多行）。 */
+  message: string | string[];
+  /** 确认按钮文案（默认 i18next.t('common.confirmButton')）。 */
+  confirmLabel?: string;
+  /** 取消按钮文案（默认 i18next.t('common.genericCancelButton')）。 */
+  cancelLabel?: string;
+  /** 确认按钮颜色（默认 'accent'）。 */
+  confirmColor?: 'accent' | 'amber' | 'red' | 'green';
+  /** 破坏性确认（如中止/删除）：默认焦点落在安全的「取消」上，防 Enter 误触。 */
+  dangerous?: boolean;
+  /** 可选的第三个按钮（位置在确认和取消之间）。不传=双按钮。 */
+  extraLabel?: string;
+  /** 第三个按钮颜色（默认 'amber'）。 */
+  extraColor?: 'accent' | 'amber' | 'red' | 'green';
+  /** 可选的勾选框文案（如"不再提醒"）。不传=不渲染勾选框。 */
+  checkLabel?: string;
+  /** 勾选框初始状态（默认未勾选）。 */
+  checked?: boolean;
+  onConfirm: () => void;
+  onCancel: () => void;
+  /** 第三个按钮回调（仅在 extraLabel 提供时生效）。 */
+  onExtra?: () => void;
+  /** 勾选框变化回调（仅在 checkLabel 提供时生效）。 */
+  onCheckChange?: (checked: boolean) => void;
+}
+declare function ConfirmDialog({
+  title,
+  message,
+  confirmLabel,
+  cancelLabel,
+  confirmColor,
+  dangerous,
+  extraLabel,
+  extraColor,
+  checkLabel,
+  checked,
+  onConfirm,
+  onCancel,
+  onExtra,
+  onCheckChange
+}: ConfirmDialogProps): React.ReactElement;
+//#endregion
+//#region src/router/Tabable.d.ts
+type FocusStyle = 'pointer' | 'highlight' | 'background' | 'border' | 'cursor' | 'none';
+interface TabableContextValue {
+  /** 是否拥有焦点 */
+  focused: boolean;
+  /** 注册 ID */
+  id: string;
+  /** 是否 disabled */
+  disabled: boolean;
+  /** 当前聚焦样式 */
+  focusStyle: FocusStyle;
+}
+/**
+ * 子组件读取最近 <Tabable> 的聚焦状态。
+ * focusStyle='none' 时组件自己根据 focused 自绘。
+ */
+declare function useTabableContext(): TabableContextValue;
+interface TabableEntry {
+  id: string;
+  tabIndex: number;
+  disabled: boolean;
+  order: number;
+  routePath: string;
+  autoFocus: boolean;
+  /** Enter 拦截器。返回 true = 阻止默认穿透。 */
+  onAction?: () => boolean | void;
+  /** Esc 拦截器。返回 true = 阻止默认 goBack。 */
+  onEscape?: () => boolean | void;
+  /** Tab 拦截器。返回 true = 阻止默认焦点切换。 */
+  onTab?: (shift: boolean) => boolean | void;
+}
+declare class TabableRegistry {
+  private entries;
+  private focusMemory;
+  register(entry: TabableEntry): void;
+  unregister(id: string): void;
+  getTabable(routePath: string): TabableEntry[];
+  getInitialFocus(routePath: string): string | null;
+  next(currentId: string, routePath: string): string | null;
+  prev(currentId: string, routePath: string): string | null;
+  rememberFocus(routePath: string, id: string): void;
+  get(id: string): TabableEntry | undefined;
+  static nextOrder(): number;
+}
+interface RouteContextValue {
+  routePath: string;
+  currentPath: string;
+  activeId: string | null;
+  registry: TabableRegistry;
+  onFocusFallback?: (nextId: string | null) => void;
+  /** true when inside a real <Router> provider (vs default context) */
+  hasRouter?: boolean;
+}
+declare const RouteContext: React.Context<RouteContextValue>;
+interface UseTabableOptions {
+  tabIndex?: number;
+  disabled?: boolean;
+  autoFocus?: boolean;
+  /** Enter 拦截器。返回 true = 阻止默认穿透。 */
+  onAction?: () => boolean | void;
+  /** Esc 拦截器。返回 true = 阻止默认 goBack。 */
+  onEscape?: () => boolean | void;
+  /** Tab 拦截器。返回 true = 阻止默认焦点切换。 */
+  onTab?: (shift: boolean) => boolean | void;
+  id?: string;
+}
+declare function useTabable(opts?: UseTabableOptions): {
+  focused: boolean;
+  id: string;
+};
+interface TabableProps {
+  tabIndex?: number;
+  disabled?: boolean;
+  autoFocus?: boolean;
+  onAction?: () => boolean | void;
+  onEscape?: () => boolean | void;
+  onTab?: (shift: boolean) => boolean | void;
+  id?: string;
+  /** 聚焦时的视觉样式。默认 'pointer'（▶ + 蓝色 + bold） */
+  focusStyle?: FocusStyle;
+  children: React.ReactNode;
+}
+declare function Tabable({
+  tabIndex,
+  disabled,
+  autoFocus,
+  onAction,
+  onEscape,
+  id,
+  focusStyle,
+  children
+}: TabableProps): React.ReactElement;
+//#endregion
+export { ExtensionListEntry as $, ToolCompletionMessage as $n, observationRow as $t, RemoteSessionSnapshot as A, ThemePresetSource as An, SigilKind as At, SelectState as B, STATUS as Bn, getCommandSuggestions as Bt, TuiHandle as C, LangMode as Cn, ProviderUsageBadgeItem as Ct, WizardRequest as D, ThemePreset as Dn, PromptInput as Dt, TuiStreamEvent as E, ThemeAppearance as En, QueuedCommands as Et, createLocalSessionDataSource as F, DIALOG_BORDER as Fn, SlashNavigateAction as Ft, makeNotifyScheduler as G, ChatMessage as Gn, PasteStore as Gt, A2uiButtonInfo as H, ThemeColors as Hn, CreatePasteStoreOptions as Ht, MessageStore as I, PANEL_BORDER as In, TypeaheadState as It, MemoryEntry as J, StopReason as Jn, Completer as Jt, MemoryDialog as K, MessageContent as Kn, PasteStoreResidencySource as Kt, Question as L, FIGURES as Ln, applySlashCompletion as Lt, SessionDataTarget as M, createBuiltinThemeRegistry as Mn, SigilSearchRegistry as Mt, SessionTransport as N, LAYOUT as Nn, CommandEntry as Nt, AttachDataSourceDeps as O, ThemePresetInput as On, SubmitMode as Ot, createAttachSessionDataSource as P, SPACING as Pn, CommandRegistry as Pt, InfoDialogProps as Q, ToolCall as Qn, observationLiveFields as Qt, SelectOption as R, FiguresMap as Rn, createCommandRegistry as Rt, SubagentContext as S, Lang as Sn, SessionListItem as St, TuiPanelRegistration as T, MarkdownThemeOverrides as Tn, isUsingOverage as Tt, NotifyScheduler as U, A2uiContent as Un, PasteSnapshot as Ut, createSelectState as V, THEME as Vn, navigateSuggestions as Vt, NotifyStats as W, AssistantMessage as Wn, PasteSnapshotEntry as Wt, InfoDialog as X, TextContent as Xn, formatAgentDiagnosticsText as Xt, MemoryEntrySource as Y, StreamEvent as Yn, ObservationLike as Yt, InfoDialogAction as Z, ThinkingContent as Zn, formatTurnTimeline as Zt, ModalRequestInput as _, useAppState as _n, BudgetView as _t, TabableContextValue as a, ErrorRetryItem as an, ButtonColor as at, PluginRegistration as b, initI18n as bn, Home as bt, TabableRegistry as c, OnboardingResult as cn, PluginMessageRenderer as ct, useTabableContext as d, DataListEntry as dn, registerPluginRenderers as dt, subagentEntryStatus as en, ToolMessage as er, ExtensionMenuContribution as et, ConfirmDialog as f, DataListProps as fn, NotificationStore as ft, DraftItemView as g, Store as gn, BudgetStore as gt, ConfirmRequest as h, PerfStore as hn, BudgetState as ht, Tabable as i, ErrorRetryActionKind as in, Button as it, SessionDataSource as j, ThemeRegistry as jn, SigilPrefix as jt, RemoteSessionEvent as k, ThemePresetSelection as kn, SigilEntry as kt, UseTabableOptions as l, KeyBindingPredicate as ln, RegisteredRenderer as lt, AlertRequest as m, DataListTone as mn, CacheStore as mt, RouteContext as n, EditedFileEntry as nn, ExtensionDetailAction as nt, TabableEntry as o, RateLimitType as on, ButtonProps as ot, ConfirmDialogProps as p, DataListRow as pn, ProxyStore as pt, MemoryDialogProps as q, PulseSurveyItem as qn, createPasteStore as qt, RouteContextValue as r, ErrorRetryAction as rn, ExtensionDetailRequest as rt, TabableProps as s, ContextStore as sn, ButtonVariant as st, FocusStyle as t, subagentRestoreFields as tn, UserMessage as tr, ExtensionsListRequest as tt, useTabable as u, DataList as un, clearPluginRenderers as ut, ModalRequestVoid as v, detectLanguage as vn, createBudgetStore as vt, TuiOptions as w, Risk as wn, formatProviderUsageLimitTypeFull as wt, PromptRequest as x, t as xn, HomeProps as xt, PermissionDecision as y, i18next as yn, TaskStore as yt, SelectOptions as z, PALETTE as zn, extractSlashPrefix as zt };
+//# sourceMappingURL=Tabable-B7PtwING.d.ts.map