@epoch-agent/protocol 0.11.0 → 0.12.0

package/dist/index.d.ts

@@ -2026,6 +2026,18 @@ interface EpochConfig {
      */
     maxTurns: number;
     contextLength: number;
+    /**
+     * 单次模型请求的输出上限，原样递给 provider 的 `maxOutputTokens`（2026-09-16）。
+     *
+     * **缺省 = 整格不发**，那时出站请求里没有 `max_tokens`、各家服务端按自己的
+     * 默认值办（DeepSeek 是 4K，而它的思维链和正文共用这个预算）。判据全文
+     * ——包括「为什么不默认套用能力表里那个数」——在 core 的
+     * `config/schema.ts` 同名字段上。
+     *
+     * ⚠️ 别和 {@link EpochConfig.budget} 里的 `maxTokens` 弄混：那个是**整个会话**
+     * 的成本闸门，这个是**单次请求**能生成多长。两者量纲不同。
+     */
+    maxOutputTokens?: number;
     homeDir: string;
     dbPath: string;
     /**
@@ -3375,1987 +3387,2085 @@ declare const METRIC: {
 declare const NOOP_TELEMETRY: Telemetry;
 
 /**
- * 结构化提问契约（方案 34）—— 模型遇到分叉时能问一句，而不是瞎猜。
- *
- * ## 它和审批是两件事
+ * 会话消息契约。
  *
- * 审批问的是「**允不允许**我做这件事」，答案是四个固定出口，且**默认往严的方向落**
- * （走开 = 拒绝）。提问问的是「**你想要哪一种**」，答案是内容，而且
- * **没有安全的默认值** —— 替用户挑一个和替他点「允许」一样糟，只是失败的方式不同：
- * 前者让模型基于一个假答案干半小时活。
+ * 这是我们**自己的**消息格式，不是 Vercel AI SDK 的 `ModelMessage`。
  *
- * 所以这里刻意**不提供**任何「宿主答不上来时的兜底答案」。答不上来只有一种表达：
- * `skipped: true`（见 {@link QuestionAnswer}）。
+ * 为什么要有这么一层：改造前 AgentLoop、message-codec、以及 AgentProvider
+ * 这个「依赖倒置接口」全都直接用 `ModelMessage`。后果有三个：
+ *   1. 依赖倒置是假的 —— 想塞一个脚本化的假 provider 做测试，得先 import 'ai'
+ *   2. AI SDK 的消息形状是**联合类型 + 部件数组**，`content` 可能是 string
+ *      也可能是 `Array<{type:'text'|'tool-call'|...}>`，于是 loop 里到处
+ *      `as Array<Record<string, unknown>>` 地摸字段
+ *   3. SDK 换大版本（v5→v6→v7 每次都动过消息形状）要改的是整个 agent 层，
+ *      而不是一个转换函数
  *
- * ## 为什么不过权限层
+ * 形状故意和 SQLite 里持久化的 `Message`（core/session/types.ts）对齐 ——
+ * 一份扁平 content + 可选的工具部件。两边不一致的话，存盘和回放各自要一套转换。
  *
- * 提问不碰文件、不起进程、不联网。方案 34 §三把 `core/src/permission/**`
- * 列进禁止触碰，就是这个意思 —— 给它加一道权限判定，等于让 `deny` 规则能把
- * 「问一句」拦掉，而拦掉的表现是模型继续瞎猜。
+ * 转成 SDK 格式只发生在一个地方：core/provider/sdk-adapter.ts。
  */
-/** 一个选项。**没有「其他」** —— 自由输入由宿主自动提供，不占模型的选项额度 */
-interface QuestionOption {
-    /** 选项正文，用户看到的就是它，模型收到的答案也是它 */
-    label: string;
-    /** 这个选项意味着什么 / 选了会发生什么 */
-    description: string;
+
+/** 模型请求执行的一次工具调用 */
+interface EpochToolCall {
+    toolCallId: string;
+    toolName: string;
+    /** 模型给出的入参 */
+    input: Record<string, unknown>;
 }
-/** 一个问题 */
-interface QuestionItem {
-    /** 完整问句，带问号 */
-    question: string;
-    /** 极短标签，UI 上当 chip 用（≤ {@link MAX_HEADER_CHARS} 字） */
-    header: string;
-    /** {@link MIN_OPTIONS}–{@link MAX_OPTIONS} 个选项 */
-    options: QuestionOption[];
-    /** 多选（答案是数组）还是单选（答案是一个字符串） */
-    multiSelect: boolean;
+/** 一次工具执行的结果 */
+interface EpochToolResult {
+    toolCallId: string;
+    toolName: string;
+    /** 输出的文本形式。工具的返回值统一收成字符串，不往下传结构 */
+    output: string;
+    /**
+     * 二进制产物。**只有过完四道闸门、带 `data` 的才会真的进模型上下文**
+     * （见 core/src/context/artifact-gate.ts）；否则这里只有 summary + path，
+     * `output` 里已经含了那句 summary。
+     */
+    artifacts?: ToolArtifact[];
+}
+/** 文本部件 */
+interface EpochTextPart {
+    type: 'text';
+    text: string;
 }
 /**
- * 一次结构化提问。
+ * 图片部件。
  *
- * **刻意没有 `requestId`**（方案初稿里有）。跨进程时的凭据由
- * `runtime/src/serialize.ts` 的 `toSerializable()` 生成，和 `approval-request`
- * 逐字同构 —— 请求内容里再带一个 id 的话，进程内的宿主（TUI）手上会有一个
- * 它永远不用的字段，而跨进程那侧有两个候选 id，对不齐时没人说得清该信哪个。
+ * `image` 三种形态：裸 base64、`data:` URL、`http(s)` URL。
+ * 字段名是 `mediaType` 不是 `mimeType` —— 与 `@ai-sdk/provider-utils` 的
+ * `ImagePart` 对齐，省掉边界上的一次改名。
  */
-interface QuestionRequest {
-    /** 一次最多 {@link MAX_QUESTIONS} 个问题（超过就该拆成两轮对话了） */
-    questions: QuestionItem[];
+interface EpochImagePart {
+    type: 'image';
+    image: string;
+    mediaType?: string;
 }
+/** 附件为什么只有路径没有内容 */
+type FileOmitReason = 
+/** 探测到 NUL 字节，是二进制 */
+'binary'
+/** 权限判定没放行（与 `file_read` 同一条判定） */
+ | 'denied'
+/** 读不到（不存在 / 没权限 / 是目录） */
+ | 'unreadable'
+/** 这一条消息附的文件个数或总量超了上限 */
+ | 'over-limit'
 /**
- * 宿主的答复。
+ * 会话是 resume 出来的，附件内容**不重读**。
  *
- * `answers` 的键是 {@link QuestionItem.question} 原文 —— 不是下标。模型写出问句
- * 的时候就知道自己在问什么，拿问句当键它读答案不用再对一次序；而下标一旦和
- * 宿主的呈现顺序错开（多问题逐个走完再一起回），错位是静默的。
+ * 内容当初是过了权限判定才附上的，而那次判定发生在另一个上下文里
+ * （当时的权限级别、当时的信任状态）。恢复时无声地再读一遍磁盘等于让一次
+ * 旧的授权在新的上下文里继续生效。模型仍然看得见路径，要内容就自己调
+ * `file_read` —— 那条路有完整的审批。
+ */
+ | 'not-restored';
+/**
+ * 文件附件部件 —— 用户用 `@路径` 提到的文件（方案 25）。
  *
- * `skipped` 是方案 §2.4 那条「用户 Esc → 模型自己决定，整轮不失败」在类型上的
- * 落点。它和「`answers` 是空对象」**不等价**：用户答完前两问才按 Esc 时，
- * 前两个答案照样交出去，同时 `skipped: true` 告诉模型「剩下的没答上，别当成
- * 用户选了默认」。
+ * ## 为什么是一种部件，而不是把内容拼进文本里
+ *
+ * 拼字符串看起来省事，代价有四个，每一个都要在很久以后才暴露：压缩器分不清
+ * 「用户打的字」和「附的文件」于是压错东西、token 统计把文件算成用户输入、
+ * artifact 化那条路完全绕过、web 宿主收到的 wire 载荷里两者无法区分。
+ * 单独一种部件之后，这四件事各自都有地方判。
+ *
+ * ## `text` 缺席是常态，不是异常
+ *
+ * 二进制、超限、权限没放行时**只留路径**。这时候模型看到的是「用户提到了这个
+ * 文件，但内容没给你，原因是 X」—— 它可以自己去调 `file_read`（那条路有完整的
+ * 审批流程）。比起静默附上或者静默丢掉，这是唯一不会让人误判的形态。
  */
-interface QuestionAnswer {
-    /** question 原文 → 选中的 label（多选是数组）。用户自由输入时是他打的原文 */
-    answers: Record<string, string | string[]>;
-    /** 用户中途放弃（Esc / 关掉弹窗）。已答的那几个仍在 `answers` 里 */
-    skipped?: boolean;
+interface EpochFilePart {
+    type: 'file';
+    /** 用户敲的那个路径（相对工作区，`/` 分隔），原样保留用于显示 */
+    path: string;
+    /** 文件内容。**缺席时看 `omitted`** */
+    text?: string;
+    /** 没给内容的原因；给了 `text` 时不出现 */
+    omitted?: FileOmitReason;
+    /** 内容被截断到多少字节。给了就是截断过 —— 截断**永远不静默** */
+    truncatedTo?: number;
+    /** 文件原始字节数，用于展示 */
+    bytes?: number;
 }
 /**
- * 一次最多几个问题。
+ * 引用的会话为什么只有标题没有内容（方案 53 §4.2）。
  *
- * 超过就该拆成两轮对话 —— 四个连续弹窗已经是用户能忍的上限，而模型一次问八个
- * 通常意味着它没读上下文。工具会**拒绝**并把这个上限说给模型（验收 5）。
+ * 前五个是**稳定的错误码**，给宿主路由用（headless / 嵌入宿主要能按码分流，
+ * TUI 和 Web 要各自渲染）。清单本体是 {@link SESSION_REFERENCE_ERROR_CODES}，
+ * 那才是同构位置的唯一真源。
  */
-declare const MAX_QUESTIONS = 4;
-/** 每个问题的选项数下界。一个选项不是问题，是通知 */
-declare const MIN_OPTIONS = 2;
-/** 每个问题的选项数上界。超过四个用户就开始扫而不是读了 */
-declare const MAX_OPTIONS = 4;
-/** `header` 的长度上界。它是 UI 上的 chip，长了会把弹窗撑破 */
-declare const MAX_HEADER_CHARS = 12;
+type SessionOmitReason = 
+/** `@:xxx` 匹配不到**唯一**的一段会话（零个，或好几个） */
+'invalid-reference'
+/** 引用的是当前这段会话自己 */
+ | 'self-reference'
+/** 超过每条消息能引用的会话个数 */
+ | 'too-many'
+/** 会话可读性判定不放行（方案 48 的那一处判定，见 core/session/authorization.ts） */
+ | 'not-authorized'
+/** 这一条消息的附件总量已经用完 */
+ | 'budget-exceeded'
 /**
- * 收窄**外部来的**答复载荷。
+ * 会话是 resume 出来的，引用的内容**不重读**。
  *
- * 需要它的是跨进程的宿主（headless 的 `question-response`、`epoch web` 的 REST）：
- * 那条路上答复是一段 JSON，不过校验直接喂给引擎等于让宿主随手拼个
- * `{"answers": 3}` 就让模型读到一个数字。进程内的宿主由类型保证，用不到它。
+ * 判据逐字同 {@link FileOmitReason} 的 `not-restored`：内容当初是过了可读性
+ * 判定才附上的，而那次判定发生在另一个上下文里。恢复时无声地再读一遍等于让
+ * 一次旧的授权在新的上下文里继续生效。模型仍然看得见「用户引用过这段会话」，
+ * 要内容就自己调 `session_search`（方案 48 那条路，有工具审批）。
  *
- * 和 `isApprovalOutcome` 同一条理由住在 protocol：判据只有一处，
- * 两个出口（stdin / REST）各写一遍就会有一边漏掉数组那一种形态。
+ * **它不是错误码**，所以不在 {@link SESSION_REFERENCE_ERROR_CODES} 里。
  */
-declare function isQuestionAnswerMap(value: unknown): value is Record<string, string | string[]>;
-
+ | 'not-restored';
 /**
- * Agent 事件契约 —— 引擎 → 宿主（TUI / CLI / 未来的 server）的唯一协议。
+ * 五个稳定的错误码（方案 53 §4.2）—— **同构位置的唯一真源**。
  *
- * 为什么是判别联合而不是「一个 type 字段 + 一堆可选字段」：
- * 旧的 StreamChunk / StreamEvent 是后者，所有载荷字段都是 optional，于是
- *   - 三个包各写一份、字段名还不一样（input/args、success/isError），
- *     靠 cli 里一段手写适配缝合；漏一个字段编译器不报错，只是界面上少显示东西。
- *   - 协议里没有 callId，TUI 只能靠「toolName + 调用顺序 FIFO」猜工具结果
- *     属于哪次调用，并行工具就会串台。
- * 判别联合让每个事件的必填字段由编译器保证，callId 成为一等字段。
+ * 为什么要稳定的码而不是一句话：headless / 嵌入宿主要能路由这些失败
+ * （`docs/HEADLESS.md` 的退出码那套已经是这个思路），而且 TUI 和 Web 要各自渲染。
+ *
+ * `not-restored` 刻意不在里面 —— 它是「会话恢复了」这个事实，不是一次失败。
  */
-
+declare const SESSION_REFERENCE_ERROR_CODES: readonly SessionOmitReason[];
 /**
- * Token 用量。
+ * 引用另一段会话的部件 —— 用户用 `@:xxx` 提到的那段会话（方案 53）。
  *
- * 之前 protocol 侧和 core/context/types.ts 各有一个 TokenUsage，
- * 后者多两个字段——同名不同义，收成一个超集。
+ * ## 塞进来的是那段会话的「当前面」，不是原始全量（§二）
  *
- * ## 五个 token 字段的口径（方案 42 PR-0）
+ * 一个跑了两小时、压缩过三次的会话，`messages` 表里有 800 条，但模型当时能看到
+ * 的只有 60 条（其余 `active = 0`）。这里带的是**那 60 条**。三条理由：800 条
+ * 任何预算都塞不下；那 60 条就是这段会话的结论（压缩器已经把前面浓缩进去了）；
+ * 原始全量里有已经被推翻的内容（「先试了 A 不行改用 B」，压缩之后留下的是 B）。
  *
- * **两种关系并存，别一视同仁地相加**：
+ * ## 它是**快照**，不是活引用
  *
- * | 字段                            | 与谁的关系                  |
- * | ------------------------------- | --------------------------- |
- * | `cacheHitTokens` `cacheWriteTokens` | 与 `inputTokens` **不重叠** |
- * | `reasoningTokens`               | **包含在** `outputTokens` 里 |
- * | `totalTokens`                   | 输入总量 + 输出总量         |
+ * 引用是发消息那一刻的快照，之后源会话被归档、删除、继续聊都不影响这一条。
+ * **别去做「引用失效」的检测** —— 那等于让一条已经发出去的消息随时间变形。
  *
- * 所以「一共多少 token」= `inputTokens + outputTokens + cacheHit + cacheWrite`，
- * **不加** `reasoningTokens`。计价同理，见 `core/src/cost/pricing.ts` 文件头。
+ * ## `text` 缺席是常态
  *
- * 这个口径不是我们凭空定的，是 AI SDK v7 那边就这么分的：
- * `inputTokenDetails.noCacheTokens + cacheReadTokens + cacheWriteTokens
- * === inputTokens`，而 `outputTokenDetails.textTokens = outputTokens - reasoning`。
+ * 匹配不到、引用自己、超上限、判定不放行时**只留 `ref` 和原因**。这时候模型
+ * 看到的是「用户引用了某段会话，但内容没给你，原因是 X」—— 要内容它可以自己调
+ * `session_search`（方案 48）。这保证了 `@:` 永远不会成为一条比 `session_search`
+ * **更宽松**的读取通道，和 `@文件` 对 `file_read` 那条判据逐字对应。
  */
-interface TokenUsage {
-    /**
-     * **非缓存**的输入 token，即 SDK 的 `inputTokenDetails.noCacheTokens`。
-     *
-     * ⚠️ 不是 SDK 的 `usage.inputTokens`（那个是含缓存的输入总量）。填总量会让
-     * 缓存命中被按原价算第二遍 —— 缓存读通常只要原价的 10%，这两个数差一个量级。
-     */
-    inputTokens: number;
-    outputTokens: number;
-    /** 缓存命中读到的输入 token，与 `inputTokens` 不重叠，单独计价 */
-    cacheHitTokens?: number;
-    /** 写入缓存的输入 token，与 `inputTokens` 不重叠，单独计价 */
-    cacheWriteTokens?: number;
-    /**
-     * 推理模型的思考 token（SDK 的 `outputTokenDetails.reasoningTokens`）。
-     *
-     * ⚠️ 它**包含在 `outputTokens` 里**，和上面两个缓存字段的口径正好相反。
-     * 只用来展示「这一轮想了多少」，**不许再加进总数、也不单独计价**，
-     * 否则输出侧被算两遍。provider 不是推理模型 / 不上报时为 undefined。
-     */
-    reasoningTokens?: number;
-    /**
-     * SDK 报的总数：输入总量（含缓存两项）+ 输出总量。
-     *
-     * 要显示「一共多少 token」优先用这个，自己四项相加的只当兜底 ——
-     * 前者是 provider 报的两个总量直接相加，后者要先经过我们的拆分算术
-     * （`inputTokens` 取的是 noCache），多一层就多一个出错的地方。
-     * provider 没上报用量时为 undefined。
-     */
-    totalTokens?: number;
-    /**
-     * 本次用量折算的美元金额。模型没有定价数据时为 undefined，**不要填 0**。
-     *
-     * 0 意味着「免费」，undefined 意味着「不知道」。预算闸门对这两种情况的处理
-     * 必须不同——未知定价不能当免费放行。
-     */
-    costUsd?: number;
+interface EpochSessionPart {
+    type: 'session';
+    /** 用户敲的那个引用串（`@:` 后面那一截），原样保留用于显示 */
+    ref: string;
+    /** 匹配到的会话 id。**没匹配上时缺席** */
+    sessionId?: string;
+    /** 那段会话的标题（空标题时是 sessionId，见方案 53 §5.3） */
+    title?: string;
+    /** 那段会话的工作目录，用于让人 / 模型看出「这是哪个项目的会话」 */
+    cwd?: string;
+    /** 当前面的正文。**缺席时看 `omitted`** */
+    text?: string;
+    /** 没给内容的原因；给了 `text` 时不出现 */
+    omitted?: SessionOmitReason;
+    /** 内容被截断到多少字节。给了就是截断过 —— 截断**永远不静默** */
+    truncatedTo?: number;
+    /** 当前面有多少条消息（`active = 1` 的那些） */
+    messageCount?: number;
+    /** 那段会话一共多少条（含被压掉的）。两个数不等就说明它压缩过 */
+    totalMessages?: number;
 }
+type EpochContentPart = EpochTextPart | EpochImagePart | EpochFilePart | EpochSessionPart;
+/** 用户消息内容 —— 纯文本或多模态部件数组 */
+type EpochUserContent = string | EpochContentPart[];
 /**
- * 预算触顶的原因。
- *
- * 住在 protocol 而不是 `core/src/cost/types.ts`：它出现在 `finish` 事件上，
- * 于是**跨进程的宿主也要认它** —— headless 的 `result.reason` 要靠它区分
- * 「这个月的额度用完了」和「这一次调用的 `--max-budget-usd` 到了」。
- * core 那边 re-export 这一份，不另立一个同名类型。
- */
-type BudgetBreach = 
-/** 金额超过 `budget.maxCostUsd`（跨会话累计） */
-'cost'
-/** token 数超过 `budget.maxTokens`（跨会话累计） */
- | 'tokens'
-/** 模型无定价数据，且 `budget.onUnknownPricing` 为 `'block'` */
- | 'unknown-pricing'
-/**
- * **本次调用**的金额上限到了（`RunInput.maxCallCostUsd` / `--max-budget-usd`）。
+ * 附件在**给模型的**纯文本投影里长什么样。**不吐文件内容** —— 内容走 `parts` 那一路。
  *
- * 和 `'cost'` 分开是因为处理方式不同：`'cost'` 意味着用户配的那份长期预算见底了，
- * 要么等下个周期要么调高上限；`'call-cost'` 只是这一次跑得比预期贵，
- * 换个说法再问一次就好。CI 的退出码也据此分叉。
+ * 输出**逐字冻住**：门禁在 `packages/protocol/__tests__/message-projection.test.ts`，
+ * 它把五种 `omitted` 原因加截断、不截断两支全钉死了。改一个字那份会当场红 ——
+ * 那不是「用例过时了」，是你正在改模型的输入契约（判据见 {@link OMIT_LABEL}）。
  */
- | 'call-cost';
-/** 一次运行的收尾原因 */
-type FinishReason = 
-/** 模型正常收工 */
-'stop'
-/** 用尽轮次预算 */
- | 'max-turns'
-/** 死循环检测触发 —— 连续多轮重复同一个工具调用 */
- | 'stalled'
+declare function filePartSummary(part: EpochFilePart): string;
 /**
- * 模型在**一次回复内**开始复读，被我们掐掉了（core 的 `repetition-detector.ts`）。
- *
- * ⚠️ **和 `'stalled'` 刻意分开。** 那一档是「连续多轮调同一个工具」，
- * 用户能做的是换个说法或者自己接手；这一档整轮工具调用为零，是解码退化，
- * 处置是重发一次（大概率就好了）。混成一个值之后，界面上只能给出一句
- * 同时对两种情况都不准的话。
+ * 历史里的图被**摘掉**之后留在原位的那一行（2026-09-12）。
  *
- * ⚠️ **也不是 `'length'`。** 那一档是 provider 按 max output tokens 切的、
- * 那半截正文是模型真想说的；这一档是**我们**在它撞上上限之前主动停的，
- * 已经产出的正文留着但没有价值。两者在账上差一整个输出预算 ——
- * 现场那一份是 31.6 KB 里只有 12 种句子。
- */
- | 'looping'
-/** 被宿主中止 */
- | 'aborted'
-/** 模型安全策略拒答 —— 是 **provider** 拒答，不是我们拦的 */
- | 'content-filter'
-/**
- * 我们自己的内容合规闸门拦下了（core 的 `compliance/`）。
+ * ## 它补的是一个静默的口子，不是「又一个占位符」
  *
- * ⚠️ **刻意不复用 `content-filter`。** 那个值的含义是「provider 拒答了」，
- * 处置和说法都不一样：那一档用户能做的是换个说法再问，这一档是内容触了
- * 部署方配的合规红线（词表 + 类别档位），换说法不一定有用，而且该看的是
- * 「哪个类别」。混成一个值之后，界面上只能给出一句同时对两种情况都不准的话。
+ * 喂模型的历史里图片是 base64 部件（`session-store.loadHistory()` 把
+ * `inlineImages` 写死成 true）。而「当前模型认不认图」那道闸门在
+ * `core/agent/loop.ts` 上，读的是**这一轮用户新发的图**
+ * （`imageParts(input.userMessage)`）—— 也就是说换到一个不认图的模型之后只要
+ * 不再发新图，历史里那些图会原样发出去：provider 那侧要么 400、要么**一声不吭
+ * 地吞掉**（后者实测存在，判据全文在 `core/provider/capability-probe.ts` 的
+ * 文件头）。摘掉它们的是 `AgentLoop`，留下的那一行是这一个。
  *
- * 输入侧被拦下时也是这个值 —— 那一次**请求根本没发出去**（`usage` 全零），
- * 与输出侧被拦下的区别在文本里说清，不在这个枚举里分叉。
- */
- | 'compliance'
-/**
- * provider 把这一轮的回复**按 max output tokens 截断了**（2026-09-04）。
+ * ## 为什么不复用 `contentToText` 那个 `[图片 image/jpeg]`
  *
- * ## 为什么必须和 `'stop'` 分开
+ * 那一个是**另一个消费者**的投影（`imagesCarriedAsParts: false`，喂压缩器 /
+ * 审计 / `messages.content` 那一列），而且它有前科：图片真的送达之后，它成了
+ * 「唯一还在撒谎的地方」（判据在 {@link ContentToTextOptions.imagesCarriedAsParts}）。
+ * 这一行要说的是另一件事 —— 图**确实没给它**，以及为什么。
  *
- * 分不开的时候，「模型自己收的」和「话没说完就被切了」在事后**无法区分** ——
- * 两者在界面上长得一模一样（都是「这一轮没有工具调用」）。而这是所有
- * 「模型半路停下」类问题的**第一个分诊问题**：一句
- * 「我先确认苏菲店的信息，再拉昨日数据。」+ 0 个工具调用，到底是模型宣布了
- * 下一步就收工（该由 `verify:stop` 那道闸救），还是它正要发工具调用时
- * 被截断（该调高 max output tokens）—— 处置完全相反。
+ * 措辞里带上「不支持」这半句，判据同 `agent/prompt.ts` 里那条
+ * 「不支持那一档要说清后果，别笼统一句不支持」：只写「图片未附上」的话，
+ * 模型会去猜是不是传坏了，然后建议用户重发一次 —— 而重发多少次都一样。
  *
- * 实测过一次：`sessions.db` 里 687 条消息的 `finish_reason` 列**全是 NULL**，
- * 而 `AgentLoop` 当时只判了 `'content-filter'`，没有任何一处判 `'length'`。
- * 那一轮到底是哪一种，事后答不出来。
+ * ⚠️ **不给「你可以自己去读」这类下一步**，和 `OMIT_LABEL` 的 `binary` 那档
+ * 不同：那一档有 `file_read` 真的能拿到内容，这一档模型没有任何办法看见像素。
+ * 给一个不存在的出口，比不给更糟。
  *
- * ⚠️ **这一档不是「出错了」。** 请求成功、已经计费、那半截正文是真的，
- * 只是它不完整。宿主该说的话是「回复被截断了」而不是「失败了」。
+ * 逐字冻住，理由同 {@link OMIT_LABEL}（进模型 prompt、进 eval 指纹、不进 catalog）。
  */
- | 'length'
-/** 触达成本或 token 预算上限 */
- | 'budget-exceeded'
-/** 异常终止（详情见前一个 error 事件） */
- | 'error';
-type AgentEvent = 
+declare function imagePartOmittedSummary(part: EpochImagePart): string;
 /**
- * 这一轮真的要发出去了 —— **决定 8 的第一个时刻**（方案 42 §七，2026-08-15）。
+ * 引用的会话在纯文本投影里长什么样。**不吐那段会话的正文** —— 同 `filePartSummary`。
  *
- * ## 发它的是谁
+ * ## 这一行刻意是英文 + 码，不是中文散文
  *
- * core 的 `agent/loop.ts`，在**第一次模型请求之前**、且**在预算闸门之后**。
- * 位置是有判据的：闸门拦下的那一次请求根本没发出去，给它发一条「这一轮开跑了」
- * 是在宣布一件没发生的事（events.ts 上一条 ⚠️ 骂的正是「声明了却没有发射方」，
- * 这一条反过来 —— 别发一件没发生的）。
+ * 它的读者有三个，**没有一个是界面**：模型（经 sdk-adapter 进上下文）、
+ * `messages.content` 那一列（存盘 / 压缩 / 审计 / FTS）、以及宿主的日志。
+ * 界面要展示这一部件时读的是结构化字段（`omitted` / `title` / `messageCount`），
+ * 自己组措辞 —— TUI 那一侧的中文在宿主用 `t()` 拼，见 locales 的 `mention.*`。
  *
- * 一次 `run()` 最多一条：它是「这一轮」的头，不是「这一步」的。
- * 收尾那条 `finish` 是它的另一半，两者一头一尾夹住同一段。
+ * > ⚠️ 「没有一个是界面」这句话 2026-08-24 之前**有个洞**：`contentToText()`
+ * > 会把这一行塞进 tui / web 的气泡里，于是它事实上也是界面的。洞补在
+ * > §34.4 —— 界面改走 `contentToDisplayText()`，那一份把这一行换成
+ * > catalog 的 `message_part.session*`。所以上面那句话现在是真的了。
  *
- * ## `estimatedTokens` 是**估算**，而且永远是
+ * 所以这里直接把**那五个稳定错误码**原样写进去（§4.2）：宿主能 grep，模型能读，
+ * 而且它不必跟着界面语言变 —— 一条落库的记录跟着 `EPOCH_LANG` 变语言，
+ * 等于把同一段会话的历史劈成两半（`goal/wording.ts` 那条豁免记的是同一个坑）。
  *
- * 它是那一刻手里那份完整待发送载荷（system prompt + 工具定义 + 全部消息）
- * 过一遍 `estimateTokens()` 的结果。2026-08-15 换了真分词器（o200k_base）之后
- * 这个数**说得出真话**了 —— 在那之前 `chars/4` 在中文场景系统性低估 2–2.7 倍。
+ * 显示名用标题而不是 sessionId：后者是一串随机字符，对人和模型都没有信息量。
+ * 标题为空的会话在解析那一侧已经用 sessionId 兜过底了（方案 53 §5.3）。
+ */
+declare function sessionPartSummary(part: EpochSessionPart): string;
+/**
+ * 取部件数组的纯文本投影：图片折成一句占位，绝不吐 base64；
+ * 文件和引用的会话同样只折成一行占位，**不吐内容**。
  *
- * ⚠️ **换了真分词器不等于它变成了事实**，别把这两句话弄反：
+ * 投影是**存盘、压缩、审计**看的那一份。把几十 KB 的文件内容塞进来，
+ * `sessions.db` 会跟着一起胖，而回放时那份内容本来就能从 `parts` 里拿。
  *
- * 1. 分词器是 o200k_base，而模型可能是 Claude / DeepSeek，各家 BPE 不同 ——
- *    这是 `provider/tokenizer.ts` 文件头明写的「有意的近似」；
- * 2. 更硬的一条：这个数是**发之前**算的，而真值只有 provider 回的 usage 说了算，
- *    中途还会插进压缩、任务通知、工具结果。
+ * ## ⚠️ 这一份**只给模型和落库**，界面不许用它（RECORD-40-i18n §34.4）
  *
- * 所以界面上那枚「估算」徽标**不许摘**，判据同 `design/web-ui/thread.css`
- * 里 `.est` 那条：token 的三个时刻里只有运行前这一个是猜的。
+ * 改造前它一个人喂三类消费者，于是把界面切成 English 的人会在**自己那条消息的
+ * 气泡里**看到 `[图片 image/png]` / `[文件 …：二进制文件，未附内容]`。
+ * 这笔债在 §34.4 记了、§34.4 还掉，处置是**分家**：
  *
- * ## 为什么不复用 `usage` 事件
+ * | 谁要 | 用哪一份 | 为什么 |
+ * | ---- | -------- | ------ |
+ * | 模型（`sdk-adapter.ts` / `agent/loop.ts` / `runtime/agent-session.ts`） | **这一个** | 模型输入契约 + eval 指纹，跟着 locale 变就漂（§33.2） |
+ * | ↳ 其中 `agent/loop.ts` 拼**给模型的文本部件**那一次 | 这一个 + `{ imagesCarriedAsParts: true }` | 图片另有真部件带着，占位符会变成一句假话（判据见 {@link ContentToTextOptions}） |
+ * | `messages.content` 那一列（存盘 / 压缩 / 审计 / FTS） | **这一个** | 一条落库的记录跟着 `EPOCH_LANGUAGE` 变语言，等于把同一段会话的历史劈成两半 |
+ * | 界面（tui 的历史项、web 的气泡） | `contentToDisplayText(content, t)` | 那一份走 catalog 的 `message_part.*`，住在两个宿主里 |
  *
- * `usage` 上两个数都来自 provider 的实测回报（`cumulative` / `run`），
- * 往里塞一个猜出来的数，就得让每个消费方去判「这个字段是真的还是估的」——
- * 而那正是徽标要替用户回答的问题。两笔账两条事件，别合。
+ * 界面那一份**落在宿主层**而不是这儿，判据同 §34.6 给 `view` 那 1 处的做法
+ * （兜底文案挪给渲染端）：这个包的依赖白名单是空的，`t()` 只能由有它的那一层调。
  */
-{
-    type: 'run-start';
+interface ContentToTextOptions {
     /**
-     * 这一轮由哪个角色在跑。**顶层会话没指定角色时整个键缺席**，
-     * 不是给一个 `general` —— 「没选专家」在决定 20 ② 里是一个有形状的值
-     * （底栏没有 chip），编一个默认名等于把那个值抹掉。
+     * 这一条消息的图片**是不是另有真部件带着**（`EpochMessage.parts` 里那份
+     * base64，最终变成 provider 的原生图片部件）。
+     *
+     * 默认 `false` —— 也就是改造前的行为，落库那一列要的正是它：那一行
+     * `[图片 image/png]` 是**这一轮带过一张图**的唯一记录（`parts` 列另存，
+     * 但 FTS / 预览 / 标题只看 content）。
+     *
+     * `true` 时图片那一支整个**不折占位符**。判据是那句占位符的含义 ——
+     * 「这里本来有张图，但你看不到」。图真的在旁边时它就成了一句假话，而且是
+     * 会被照着信的那种：2026-09-01 实测，`@ai-sdk/deepseek@3.0.20` 把图片
+     * 静默丢了之后，模型读到的就是这一行，于是它逐字回答「我只看到
+     * 「[图片 image/jpeg]」这个占位符，图片没有传到我这边」。**升级 SDK 让图片
+     * 真的送达之后，这一行反而成了唯一还在撒谎的地方。**
+     *
+     * ⚠️ 只关图片那一支。`file` / `session` 的占位符**照旧**：它们说的是
+     * 「内容没附上」（`omitted` / `not-restored`），那句话在任何情况下都是真的，
+     * 而且是模型唯一能知道「有个东西没给我」的途径。
      */
-    role?: ActiveAgentRole;
-    /** 运行前估算。见上面那两条为什么它永远带「估算」二字 */
-    estimatedTokens: number;
-}
-/** 回复正文增量 */
- | {
-    type: 'text-delta';
-    text: string;
-}
-/** 推理模型的思考过程增量 */
- | {
-    type: 'reasoning-delta';
-    text: string;
-}
-/** 模型请求调用工具（执行前） */
- | {
-    type: 'tool-call';
-    callId: string;
-    toolName: string;
-    input: Record<string, unknown>;
+    imagesCarriedAsParts?: boolean;
 }
+declare function contentToText(content: EpochUserContent, opts?: ContentToTextOptions): string;
 /**
- * 工具**执行过程中**的输出增量。callId 与对应的 tool-call 一致。
+ * 「上一轮实际动过手」在**给模型的**历史里长什么样（2026-08-28）。
  *
- * 这是一条**只给人看**的旁路通道：模型看到的永远是最终 `tool-result.output`
- * （那份已经截断、已经包过隔离标签）。加它是因为 `tool-call` 和 `tool-result`
- * 之间可以隔着一次三分钟的 `pnpm build` —— 在那三分钟里宿主一个事件都收不到，
- * 屏幕上是一行不动的 `⏳ terminal`，用户分不清是在跑还是挂了。
+ * ## 它修的是什么
  *
- * 发这个事件的工具不必逐 chunk 发：引擎侧统一做合并窗口、剥 ANSI、`\r` 折叠
- * 和总量封顶（见 core 的 tool-output-pump.ts），工具只管把原始 chunk 交出来。
+ * 喂模型的那份历史只有 user / assistant 两种角色的**文本**
+ * （`runtime/src/agent-session.ts` 的累积、`session-store.ts` 的 `loadHistory()`），
+ * 工具调用和结果一条都不在里面 —— 这是刻意的（孤立的 tool 消息会被 provider 拒掉，
+ * 全量 transcript 是另一个体量的事）。代价此前没人算：一段五条消息的会话，
+ * 模型看到的是**五条又长又具体的指令，配四句十来个字的「办完了」**。
+ * 早期那几条指令的字数远大于「它已经做完了」的证据量，于是模型把它们当成还在
+ * 生效的待办，回头去做 —— 而用户刚发的那一条被摊薄。实测在
+ * `packages/runtime/__tests__/context-recency.test.ts`。
  *
- * 宿主可以完全忽略它 —— 忽略的结果就是改动前的行为。
- */
- | {
-    type: 'tool-output-delta';
-    callId: string;
-    toolName: string;
-    text: string;
-}
-/**
- * 工具执行完毕。callId 与对应的 tool-call 一致。
+ * 这一行就是补那份证据：不复原过程，只留一句「这一轮真的调了这些工具」。
  *
- * `artifacts` 给宿主渲染缩略图 / 打开文件用。它和 `output` 是**两个通道**：
- * `output` 是喂给模型的纯文本（已含每个 artifact 的 summary），
- * `artifacts` 是给人看的那一份 —— 宿主不必解析 output 去猜有没有图。
- */
- | {
-    type: 'tool-result';
-    callId: string;
-    toolName: string;
-    output: string;
-    ok: boolean;
-    artifacts?: ToolArtifact[];
-}
-/** 一轮 ReAct 结束（轮次从 1 开始） */
- | {
-    type: 'turn-complete';
-    turn: number;
-}
-/**
- * 需要用户确认。宿主**必须**调用 respond()，否则引擎会一直阻塞在这里。
- * 引擎侧对未答复的请求有兜底（流结束时按 deny 处理），但那意味着操作被拒。
+ * ## 判据用**结果**而不是调用
  *
- * `note` 只有计划审批的 `plan-revise` 用得上 —— 它装的是用户的修改意见，
- * 其余出口一律忽略。**没有它这个出口就是个死循环**：模型不知道要改什么，
- * 只会把同一份计划原样再交一次。
- */
- | {
-    type: 'approval-request';
-    request: ApprovalRequest;
-    respond: (outcome: ApprovalOutcome, note?: string) => void;
-}
-/**
- * 模型问了一个结构化问题，等用户选（方案 34）。宿主**必须**调用 `respond()`，
- * 否则引擎会一直阻塞在这里。
+ * `EpochToolCall` 上有工具名，但一次跑到一半被中止的轮次里那些调用**从没执行过**
+ * （判据逐字同 `runtime/src/session-file-changes.ts` 的边界 1）。而一条
+ * `EpochToolResult` 存在就意味着它跑完了 —— 拿结果当输入，「执行过没有」这件事
+ * 不需要另外判一次。
  *
- * 结构与 `approval-request` 同构（请求 + 一个答复闭包），于是中继、wire 编码、
- * 宿主回调那几层一个都不用新造。但**语义不同，别把两者的兜底混用**：
- * 审批答不上来时有一个安全侧（`deny`），提问没有 —— 替用户挑一个选项和替他
- * 点「允许」一样糟。答不上来只有一种表达：`respond({ answers: {}, skipped: true })`，
- * 模型收到之后**自己决定**（通常是选默认继续），这一轮不算失败。
+ * ⚠️ **它分不出成功和失败**：落盘的结果上没有 `success`（同上那份的边界 2）。
+ * 所以措辞是「调用过」而不是「做成了」—— 一次被权限拒掉的 `file_write`
+ * 在这里照样留一笔，而那句话仍然是真的。
  *
- * 引擎侧对未答复的请求有兜底（流结束时按「跳过」处理）—— 那不是伪造答案，
- * 是如实说「没人答」。
- */
- | {
-    type: 'question';
-    request: QuestionRequest;
-    respond: (answer: QuestionAnswer) => void;
-}
-/**
- * 补丁预览：这次工具调用真的改了哪个文件、改成什么样。
+ * ## 为什么住在 protocol、且是冻住的中文
  *
- * 发它的是 core 的 `agent/file-diff.ts`（`ToolExecutor` 在写类工具动手前后
- * 各读一遍盘），排在同一次调用的 `tool-result` **之前**。
- * `oldContent` 缺 = 这个文件是新建的；`newContent` 缺 = 被删了；两者都在 = 改了。
+ * 它的读者是**模型**，和 {@link contentToText} / {@link filePartSummary} 同一类，
+ * 所以走同一条规矩：住在这个零依赖的包里、逐字冻住、**不跟着界面语言变**
+ * （门禁在 `packages/protocol/__tests__/message-projection.test.ts`）。一条进了
+ * 上下文的历史跟着 `EPOCH_LANGUAGE` 变语言，等于把同一段会话劈成两半。
  *
- * ⚠️ 这个类型 2026-08-13 之前**声明在这里、消费在 view、渲染在两个宿主，
- * 中间一个发射方都没有** —— 三边契约测试全绿，因为站在引擎位置上的是
- * fixture 喂出来的假 agent。判据见 `.agents/plans/43-web-ui-shell-plan.md` §12.5。
- * **往这个 union 里加新类型时，先想清楚谁发。**
+ * 只有工具名，不带参数 / 路径：带路径要 `affectedPaths()` + 工作目录，而那两样
+ * 住在 core 和装配层，拿不到的地方（`loadHistory()`）就会退化成另一种措辞 ——
+ * 两条路产出的历史一旦不一样，症状就是「刷新之后模型看到的和刚才不是同一段」。
+ *
+ * ⚠️ **调用方要的多半是 {@link assistantTurnText}，不是这一个** —— 那一份连
+ * 「正文和这一行之间怎么接」一起定了，而那正是两条路会走散的地方。
+ *
+ * @param results 这**一轮**（不是一步）执行过的全部工具结果，按发生序
+ * @returns 空数组时是空串 —— 这一轮没动手，那就没有这句话可说
  */
- | {
-    type: 'diff';
-    filePath: string;
-    oldContent?: string;
-    newContent?: string;
-}
-/** 累计用量变化（每轮结束时发一次，宿主用来更新状态栏） */
- | {
-    type: 'usage';
-    cumulative: TokenUsage;
-    /**
-     * **到此刻为止、这一次 run** 的用量（方案 42 PR-2）。
-     *
-     * 和 `finish.runUsage` 同一笔账，只是这一份是**过程中**的快照 ——
-     * 界面上「运行中：已消耗 N token」要的就是它。
-     *
-     * ⚠️ 为什么不让宿主拿 `cumulative` 相减：相减要有一个起算基线，而
-     * 「run 开始那一刻的累计」在事件流上根本没有 —— 第一帧 `usage` 到达时，
-     * 它的 `cumulative` 既可能是本轮用量、也可能是 `BudgetStore` 恢复的历史
-     * 加上本轮，从流本身分辨不了。基线猜错的代价是屏幕上那个数直接差一个量级。
-     */
-    run?: TokenUsage;
-    budgetRemaining?: {
-        costUsd?: number;
-        tokens?: number;
-    };
-}
+declare function turnDigest(results: readonly Pick<EpochToolResult, 'toolName'>[]): string;
 /**
- * 运行结束。
+ * 一轮的 assistant 消息在**给模型的历史**里长什么样：正文 + {@link turnDigest}。
  *
- * `breach` 只在 `reason === 'budget-exceeded'` 时有值，说明是哪条上限触顶的。
- * 没有它的话「触顶」在事件流上只是一句中文提示（`describeBreach()` 的产物），
- * 而机器宿主要分支就只能去正则匹配那句中文 —— 我们改一个字它就碎。
+ * ## 为什么这条胶水也得住在这儿
  *
- * ## `usage` 和 `runUsage` 是两笔账，别当同义词（方案 42 PR-2）
+ * 因为它有**两个调用方，走两条路，产出必须逐字节相同**：
  *
- * `usage` 是 `BudgetGuard.snapshot()` —— **累计**，口径由 `EpochRuntime.usageScope`
- * 决定（配了 `BudgetStore` 就是跨会话累计，否则是本进程从零算）。宿主拿它画
- * 「这个会话一共花了多少」。
+ * - 直播：`runtime/src/agent-session.ts` 用 `TurnStepCollector` 收的那一轮；
+ * - 恢复：`runtime/src/session-store.ts` 的 `loadHistory()` 从 DB 行折回来的那一轮。
  *
- * `runUsage` 是**这一次 run** 的用量，由本次循环里每一轮的 `result.usage`
- * 累加而成。加它的理由很具体：界面上每一轮结束时要写「共 14,270 token」，
- * 而那个数**减不出来** —— 累计值可能被 `BudgetStore` 从上次会话恢复，
- * 「第一个累计值」既可能是本轮用量、也可能是历史 + 本轮，
- * 从事件流本身分辨不了（`AgentLoopConfig.onTurnUsage` 那段注释骂的是同一件事）。
+ * 两边各写一次 `text + '\n\n' + digest` 的下场是：某天一边多一个换行，
+ * 而症状是**刷新页面之后模型看到的历史和刷新前不是同一段** —— `reloadHistory()`
+ * 的 JSDoc 里那句「它们一旦分叉，症状就是屏幕上和模型看到的对不上」骂的正是这个。
+ * 门禁是 `packages/runtime/__tests__/context-recency.test.ts` 里那条逐字节比对。
  *
- * **两个都是可选的，那不是偷懒**：一次 run 可以一次模型调用都没发生就结束
- * （装配抛异常、预算在发送前拦下）。那时候「这一轮用了多少 / 用的哪个模型」
- * 没有答案，而给一个 0 和给配置里那个模型名都是撒谎 —— 与
- * `TokenUsage.costUsd` 的「0 是免费，undefined 是不知道」同一条约定。
+ * 正文为空、只有工具痕迹时**不留前导空行**：那一轮模型只调了工具没说话
+ * （`loop.ts` 允许），这时这条消息的全部内容就是那一段。
+ *
+ * ⚠️ **断在半路那一轮走的是另一份投影**，判据全文在 {@link unfinishedTurnText} 上：
+ * 收了尾 = 结论在正文里，工具只留一行名字；断在半路 = 工具结果是唯一的记录，
+ * 得把正文一起带回去。
+ *
+ * @param finishReason 这一轮的收尾原因（取值域是 `FinishReason`）。
+ *        **缺省 = 没有记录**（老会话的 `finish_reason` 列是 NULL，嵌入宿主也可能
+ *        不传）→ 一律按「收了尾」处理。往宽了判的代价是把工具正文焊进历史，
+ *        而那是每一轮都要重发的东西。
+ *
+ *        ⚠️ **收 `string` 而不是 `FinishReason`，这是刻意的。** 恢复那一条路是从
+ *        `messages.finish_reason` 读回来的，而它在库里就是一列 `TEXT`
+ *        （`core/src/session/db.ts`），读出来是 `string`。把这里收窄成联合类型，
+ *        唯一的效果是逼 `loadHistory()` 写一次**没有依据的** cast ——
+ *        那一列可以装着任何历史版本写进去的字符串，断言它属于今天这个联合
+ *        是一句我们证明不了的话。宽收窄判：不认识的值一律走「收了尾」那一支。
+ * @returns 空串 = 这一轮既没正文也没动手，调用方**别往历史里塞这一条**
  */
- | {
-    type: 'finish';
-    reason: FinishReason;
-    usage: TokenUsage;
-    /** **这一次 run** 的用量。provider 一次都没上报就没有这个键 */
-    runUsage?: TokenUsage;
+declare function assistantTurnText(text: string, results: readonly Pick<EpochToolResult, 'toolName' | 'output'>[], finishReason?: string): string;
+/**
+ * 部件类型的穷尽性守卫 —— **这是「加了一种部件却漏了一处分支」的那道会红的门禁**。
+ *
+ * 消费 `EpochContentPart` 的地方有五处（这里、`sdk-adapter` 的 `toSdkPart`、
+ * `session/payload` 的 `persistParts` / `restoreParts`、以及展示层），改造前它们
+ * 全都写成「if text / if file / 剩下的当图片」。那个形状下加一种部件**不会有
+ * 任何东西变红**：新部件会被静默当成图片，而症状是模型收到一个 `image:` 里
+ * 塞着会话正文的请求，provider 报 400。
+ */
+declare function assertNeverPart(part: never): never;
+type EpochMessageRole = 'system' | 'user' | 'assistant' | 'tool';
+/**
+ * 一条会话消息。
+ *
+ * `content` 永远是字符串（tool 消息为空串，内容在 `toolResults` 里），
+ * 这样「取这条消息的文本」永远不需要判类型。
+ *
+ * 多模态**不是**把 `content` 放宽成联合类型 —— 那正是本文件开头骂过的病，
+ * 会让 loop / codec / 压缩器每处都得判一次类型。改成加一个 `parts` 旁路：
+ * `content` 仍然是权威的**文本投影**（压缩器、审计、持久化都只看它），
+ * `parts` 只在 sdk-adapter 那一处被读走。两者的关系由 `contentToText` 保证。
+ */
+interface EpochMessage {
+    role: EpochMessageRole;
+    content: string;
     /**
-     * 最后一次模型调用**实际回来**的模型（`GenerateOutput.model`）。
-     *
-     * ⚠️ 不是配置里选的那个。降级和 `switch_model` 之后两者不一样，而
-     * 「这一轮到底是谁答的」正是那时候用户最需要知道的一件事。
+     * 多模态部件。给了就以它为准喂模型，`content` 退化成它的文本投影。
+     * **不落 SQLite** —— 图片走 artifact 目录，DB 里只留 content 的占位文本。
      */
-    model?: string;
+    parts?: EpochContentPart[];
+    /** assistant 要求的工具调用；与 content 并存（模型可以边说话边调工具） */
+    toolCalls?: EpochToolCall[];
+    /** role 为 'tool' 时携带的执行结果 */
+    toolResults?: EpochToolResult[];
     /**
-     * 最后一次模型调用**要求**的那个模型（`GenerateOutput.requestedModel`）。
+     * 这一步模型的思考原文（推理模型的 `reasoning-delta` 累加）。2026-08-18。
      *
-     * 和上面的 {@link model} 是一对，宿主要的那个事实是**两者是否相等** ——
-     * 不等 = 引擎降级了，相等 = 用户/命令自己挑的。
+     * **只给人看，不回灌模型**：`sdk-adapter.ts` 一个字都不读它。加它是因为
+     * 刷新页面之前屏幕上有「深度思考」那一段，刷新之后整段消失 —— 而那不是
+     * 「这一轮没想」，是我们没记。
      *
-     * ⚠️ **读侧不许拿 `model` 去和「当前配置/当前选择」比来代替这个判断。**
-     * 那是一个按**此刻**的值，而这条断言是按**轮**的 —— 它会被拿去比对所有
-     * 历史轮，于是用户在顶栏换一次模型，之前那些跑得好好的轮子集体变成
-     * 「故障转移」。web 脚注那枚徽标栽过这一次，判据全文在
-     * `core/src/provider/types.ts` 的 `GenerateOutput.requestedModel` 上。
+     * ⚠️ **它属于某一步，不属于整轮。** 一轮里模型可以想一次、调个工具、再想一次，
+     * 每次的思考挂在**它自己那条 assistant 行**上，位置就是它真实的时序位置。
+     * 拿它当「整轮的思考」拼成一根，回放时那一段会被钉到最前面，讲的却可能是
+     * 二十步之后的事（web 的 `thoughtParts` 治过同一个病，判据在
+     * `web/src/state/reducer.ts` 的 `trackThought()`）。
+     *
+     * 落盘走 `messages.reasoning` 列 —— 那一列**从会话库 v1 就在**，只是一直没人
+     * 写过，所以这一档不需要迁移。
      */
-    requestedModel?: string;
-    breach?: BudgetBreach;
+    reasoning?: string;
 }
+
 /**
- * 引擎有一句话要对用户说，而**它不是回复正文**（2026-08-26）。
- *
- * ## 发它的是谁，以及为什么非要一条新帧
- *
- * 今天唯一的发射方是 core 的 `AgentLoop`：技能学习器在上一轮收尾之后
- * fire-and-forget 学到了一条技能，而那件事没有任何出口（判据全文在
- * `agent/loop.ts` 的 `maybeLearn()`）。三条现成的路各自被什么挡掉：
+ * 结构化提问契约（方案 34）—— 模型遇到分叉时能问一句，而不是瞎猜。
  *
- * 1. **`text-delta`** —— 它会被折进 assistant 那一段正文，于是这句话进历史、
- *    进落盘、下一轮再进模型。一句「你学会了 X」被当成模型自己说过的话，
- *    等于往上下文里塞一条它没说过的发言；
- * 2. **往 system prompt 里塞** —— 那是 prompt cache 的前缀，每轮加一句会让整段
- *    对话的缓存逐轮失效。同一条判据 `loop.ts` 里为后台任务通知讲过一遍；
- * 3. **一条 `[系统]` 进历史**（`systemNote()` + `recordNote()`，样板是
- *    `runtime` 的 `markRoleHandoff()`）—— 它是真出口，但那句话**只在刷新 /
- *    回放时看得见**，而且今天只有 web 认那个前缀，TUI 会把 `[系统] ` 原样露出来。
+ * ## 它和审批是两件事
  *
- * ## 为什么是「码 + 已经翻好的话」两个字段
+ * 审批问的是「**允不允许**我做这件事」，答案是四个固定出口，且**默认往严的方向落**
+ * （走开 = 拒绝）。提问问的是「**你想要哪一种**」，答案是内容，而且
+ * **没有安全的默认值** —— 替用户挑一个和替他点「允许」一样糟，只是失败的方式不同：
+ * 前者让模型基于一个假答案干半小时活。
  *
- * `text` 由**发射方**（core，它有 `t()`）翻好：`@epoch-agent/view` 只依赖
- * protocol、够不着 catalog，在那儿兜底就只能是中文 —— 同 `error` 那条空 message
- * 的兜底为什么落在两个宿主身上，是同一条判据。
+ * 所以这里刻意**不提供**任何「宿主答不上来时的兜底答案」。答不上来只有一种表达：
+ * `skipped: true`（见 {@link QuestionAnswer}）。
  *
- * `code` 是给**要分支的宿主**的：判「这是哪一类通知」不许去 `includes()` 那句
- * 随时会改的话（RECORD-40-i18n §32.1 那条 `reason === '已取消'` 的教训）。
+ * ## 为什么不过权限层
  *
- * ⚠️ **要拿技能名去做别的事**（跳到能力页、打开那份 SKILL.md），就再加一个
- * 字段，别去正则 `text` —— 那句话是会随文案改的。
+ * 提问不碰文件、不起进程、不联网。方案 34 §三把 `core/src/permission/**`
+ * 列进禁止触碰，就是这个意思 —— 给它加一道权限判定，等于让 `deny` 规则能把
+ * 「问一句」拦掉，而拦掉的表现是模型继续瞎猜。
  */
- | {
-    type: 'notice';
-    code: NoticeCode;
-    text: string;
+/** 一个选项。**没有「其他」** —— 自由输入由宿主自动提供，不占模型的选项额度 */
+interface QuestionOption {
+    /** 选项正文，用户看到的就是它，模型收到的答案也是它 */
+    label: string;
+    /** 这个选项意味着什么 / 选了会发生什么 */
+    description: string;
+}
+/** 一个问题 */
+interface QuestionItem {
+    /** 完整问句，带问号 */
+    question: string;
+    /** 极短标签，UI 上当 chip 用（≤ {@link MAX_HEADER_CHARS} 字） */
+    header: string;
+    /** {@link MIN_OPTIONS}–{@link MAX_OPTIONS} 个选项 */
+    options: QuestionOption[];
+    /** 多选（答案是数组）还是单选（答案是一个字符串） */
+    multiSelect: boolean;
 }
-/** 运行中出错（随后会有一个 finish: 'error'） */
- | {
-    type: 'error';
-    message: string;
-};
 /**
- * 一条 `notice` 是哪一类。
- *
- * 写成联合而不是 `string`，是为了让**加一档时消费方的 switch 会红** ——
- * 判据同 wire.ts 的 `WireResetReason`。
+ * 一次结构化提问。
  *
- * ⚠️ 这里原来写着「今天只有一种」—— 那句话在写下之后就一直在过期
- * （`images-dropped` / `compliance-masked` / `response-truncated` 陆续进来）。
- * 有几种去数下面这个联合，别在散文里再抄一个会骗人的数字。
+ * **刻意没有 `requestId`**（方案初稿里有）。跨进程时的凭据由
+ * `runtime/src/serialize.ts` 的 `toSerializable()` 生成，和 `approval-request`
+ * 逐字同构 —— 请求内容里再带一个 id 的话，进程内的宿主（TUI）手上会有一个
+ * 它永远不用的字段，而跨进程那侧有两个候选 id，对不齐时没人说得清该信哪个。
  */
-type NoticeCode = 
+interface QuestionRequest {
+    /** 一次最多 {@link MAX_QUESTIONS} 个问题（超过就该拆成两轮对话了） */
+    questions: QuestionItem[];
+}
 /**
- * 技能学习器在上一轮收尾之后学到了一条技能。
+ * 宿主的答复。
  *
- * ⚠️ 这一帧发在**下一轮的头上**，不是学成的那一刻 —— 学成时那条流早关了
- * （`maybeLearn()` 紧接着就是 `yield finish('stop'); return;`）。发在这里还有
- * 第二层意思：那一轮正是这条技能**真的进了 system prompt** 的那一轮。
+ * `answers` 的键是 {@link QuestionItem.question} 原文 —— 不是下标。模型写出问句
+ * 的时候就知道自己在问什么，拿问句当键它读答案不用再对一次序；而下标一旦和
+ * 宿主的呈现顺序错开（多问题逐个走完再一起回），错位是静默的。
+ *
+ * `skipped` 是方案 §2.4 那条「用户 Esc → 模型自己决定，整轮不失败」在类型上的
+ * 落点。它和「`answers` 是空对象」**不等价**：用户答完前两问才按 Esc 时，
+ * 前两个答案照样交出去，同时 `skipped: true` 告诉模型「剩下的没答上，别当成
+ * 用户选了默认」。
  */
-'skill-learned'
+interface QuestionAnswer {
+    /** question 原文 → 选中的 label（多选是数组）。用户自由输入时是他打的原文 */
+    answers: Record<string, string | string[]>;
+    /** 用户中途放弃（Esc / 关掉弹窗）。已答的那几个仍在 `answers` 里 */
+    skipped?: boolean;
+}
 /**
- * provider **把用户发的图片丢了**，而请求已经发出去、已经计费（2026-09-01）。
+ * 一次最多几个问题。
  *
- * 和 `agent_run.images_unsupported` 那条错误分得很清，两者别混：
+ * 超过就该拆成两轮对话 —— 四个连续弹窗已经是用户能忍的上限，而模型一次问八个
+ * 通常意味着它没读上下文。工具会**拒绝**并把这个上限说给模型（验收 5）。
+ */
+declare const MAX_QUESTIONS = 4;
+/** 每个问题的选项数下界。一个选项不是问题，是通知 */
+declare const MIN_OPTIONS = 2;
+/** 每个问题的选项数上界。超过四个用户就开始扫而不是读了 */
+declare const MAX_OPTIONS = 4;
+/** `header` 的长度上界。它是 UI 上的 chip，长了会把弹窗撑破 */
+declare const MAX_HEADER_CHARS = 12;
+/**
+ * 收窄**外部来的**答复载荷。
  *
- * | | 谁判的 | 什么时候 | 钱 |
- * | --- | --- | --- | --- |
- * | `images_unsupported`（`error` 帧） | **我们**（闸门 1 的输入侧） | 发请求**之前** | 没花 |
- * | 这一条（`notice` 帧） | **provider 自己报的 warning** | 请求回来之后 | **已经花了** |
+ * 需要它的是跨进程的宿主（headless 的 `question-response`、`epoch web` 的 REST）：
+ * 那条路上答复是一段 JSON，不过校验直接喂给引擎等于让宿主随手拼个
+ * `{"answers": 3}` 就让模型读到一个数字。进程内的宿主由类型保证，用不到它。
  *
- * 也就是说走到这一帧意味着闸门 1 判「这个模型认图」，而 provider 那侧不认。
- * 2026-09-01 那次事故就是这一格：`@ai-sdk/deepseek@3.0.20` 静默丢弃图片，
- * 模型对着一张不存在的图回答「我只看到一个占位符」，而屏幕上一个字都没有。
+ * 和 `isApprovalOutcome` 同一条理由住在 protocol：判据只有一处，
+ * 两个出口（stdin / REST）各写一遍就会有一边漏掉数组那一种形态。
+ */
+declare function isQuestionAnswerMap(value: unknown): value is Record<string, string | string[]>;
+
+/**
+ * Agent 事件契约 —— 引擎 → 宿主（TUI / CLI / 未来的 server）的唯一协议。
  *
- * ⚠️ **一次 run 只发一帧**，不是每轮一帧：带图的那条用户消息在这一次 run 的
- * 每一轮都会重发，逐轮报的话一次多工具调用的对话会刷出十几行同样的话。
+ * 为什么是判别联合而不是「一个 type 字段 + 一堆可选字段」：
+ * 旧的 StreamChunk / StreamEvent 是后者，所有载荷字段都是 optional，于是
+ *   - 三个包各写一份、字段名还不一样（input/args、success/isError），
+ *     靠 cli 里一段手写适配缝合；漏一个字段编译器不报错，只是界面上少显示东西。
+ *   - 协议里没有 callId，TUI 只能靠「toolName + 调用顺序 FIFO」猜工具结果
+ *     属于哪次调用，并行工具就会串台。
+ * 判别联合让每个事件的必填字段由编译器保证，callId 成为一等字段。
  */
- | 'images-dropped'
+
 /**
- * 内容合规的输入闸门**改写了用户刚发的那句话**（`mask` 档，2026-09-01）。
+ * Token 用量。
  *
- * ## 没有这一帧的话，这件事是**静默**的
+ * 之前 protocol 侧和 core/context/types.ts 各有一个 TokenUsage，
+ * 后者多两个字段——同名不同义，收成一个超集。
  *
- * `mask` 档不拒绝、也不报错：它把命中处换成 `*` 之后照常发出去。而屏幕上那条
- * 用户气泡显示的是**用户自己敲的原文**（宿主回显的是输入框里那份），
- * 模型收到的是打过码的那份 —— 两边不一样，且没有任何东西说过这件事。
+ * ## 五个 token 字段的口径（方案 42 PR-0）
  *
- * 实测过：`帮我翻译一下黑鬼这个词` 发出去变成 `帮我翻译一下**这个词`。
- * 用户看着自己那句完整的话，收到一个答非所问的回复，**没有任何线索**。
- * 这一帧就是那个线索。
+ * **两种关系并存，别一视同仁地相加**：
  *
- * ⚠️ 和 `block` 那一档分得很清：那一档请求根本没发，走的是
- * `finish: 'compliance'` + 一句正文，用户当场知道发生了什么。
- * 这一档请求照发，所以只欠一句旁白。
+ * | 字段                            | 与谁的关系                  |
+ * | ------------------------------- | --------------------------- |
+ * | `cacheHitTokens` `cacheWriteTokens` | 与 `inputTokens` **不重叠** |
+ * | `reasoningTokens`               | **包含在** `outputTokens` 里 |
+ * | `totalTokens`                   | 输入总量 + 输出总量         |
+ *
+ * 所以「一共多少 token」= `inputTokens + outputTokens + cacheHit + cacheWrite`，
+ * **不加** `reasoningTokens`。计价同理，见 `core/src/cost/pricing.ts` 文件头。
+ *
+ * 这个口径不是我们凭空定的，是 AI SDK v7 那边就这么分的：
+ * `inputTokenDetails.noCacheTokens + cacheReadTokens + cacheWriteTokens
+ * === inputTokens`，而 `outputTokenDetails.textTokens = outputTokens - reasoning`。
  */
- | 'compliance-masked'
+interface TokenUsage {
+    /**
+     * **非缓存**的输入 token，即 SDK 的 `inputTokenDetails.noCacheTokens`。
+     *
+     * ⚠️ 不是 SDK 的 `usage.inputTokens`（那个是含缓存的输入总量）。填总量会让
+     * 缓存命中被按原价算第二遍 —— 缓存读通常只要原价的 10%，这两个数差一个量级。
+     */
+    inputTokens: number;
+    outputTokens: number;
+    /** 缓存命中读到的输入 token，与 `inputTokens` 不重叠，单独计价 */
+    cacheHitTokens?: number;
+    /** 写入缓存的输入 token，与 `inputTokens` 不重叠，单独计价 */
+    cacheWriteTokens?: number;
+    /**
+     * 推理模型的思考 token（SDK 的 `outputTokenDetails.reasoningTokens`）。
+     *
+     * ⚠️ 它**包含在 `outputTokens` 里**，和上面两个缓存字段的口径正好相反。
+     * 只用来展示「这一轮想了多少」，**不许再加进总数、也不单独计价**，
+     * 否则输出侧被算两遍。provider 不是推理模型 / 不上报时为 undefined。
+     */
+    reasoningTokens?: number;
+    /**
+     * SDK 报的总数：输入总量（含缓存两项）+ 输出总量。
+     *
+     * 要显示「一共多少 token」优先用这个，自己四项相加的只当兜底 ——
+     * 前者是 provider 报的两个总量直接相加，后者要先经过我们的拆分算术
+     * （`inputTokens` 取的是 noCache），多一层就多一个出错的地方。
+     * provider 没上报用量时为 undefined。
+     */
+    totalTokens?: number;
+    /**
+     * 本次用量折算的美元金额。模型没有定价数据时为 undefined，**不要填 0**。
+     *
+     * 0 意味着「免费」，undefined 意味着「不知道」。预算闸门对这两种情况的处理
+     * 必须不同——未知定价不能当免费放行。
+     */
+    costUsd?: number;
+}
 /**
- * provider 按 max output tokens **把这一轮的回复切了**（2026-09-04）。
+ * 预算触顶的原因。
  *
- * 和 `FinishReason` 的 `'length'` 是同一件事的两个出口，两个都要：
- * 收尾原因是给**机器**分支的（headless 的 `result.reason`、落盘的
- * `finish_reason` 列、web 那枚记号），这一帧是给**人**看的那句话 ——
- * 屏幕上那半截正文自己不会说「我是半截的」。
+ * 住在 protocol 而不是 `core/src/cost/types.ts`：它出现在 `finish` 事件上，
+ * 于是**跨进程的宿主也要认它** —— headless 的 `result.reason` 要靠它区分
+ * 「这个月的额度用完了」和「这一次调用的 `--max-budget-usd` 到了」。
+ * core 那边 re-export 这一份，不另立一个同名类型。
+ */
+type BudgetBreach = 
+/** 金额超过 `budget.maxCostUsd`（跨会话累计） */
+'cost'
+/** token 数超过 `budget.maxTokens`（跨会话累计） */
+ | 'tokens'
+/** 模型无定价数据，且 `budget.onUnknownPricing` 为 `'block'` */
+ | 'unknown-pricing'
+/**
+ * **本次调用**的金额上限到了（`RunInput.maxCallCostUsd` / `--max-budget-usd`）。
  *
- * ⚠️ 走 `notice` 而不是 `text-delta`，判据同上面 `skill-learned` 那三条：
- * 它不是模型说的话，塞进正文就会进历史、进落盘、下一轮再进模型。
+ * 和 `'cost'` 分开是因为处理方式不同：`'cost'` 意味着用户配的那份长期预算见底了，
+ * 要么等下个周期要么调高上限；`'call-cost'` 只是这一次跑得比预期贵，
+ * 换个说法再问一次就好。CI 的退出码也据此分叉。
  */
- | 'response-truncated'
+ | 'call-cost';
+/** 一次运行的收尾原因 */
+type FinishReason = 
+/** 模型正常收工 */
+'stop'
+/** 用尽轮次预算 */
+ | 'max-turns'
+/** 死循环检测触发 —— 连续多轮重复同一个工具调用 */
+ | 'stalled'
 /**
- * 这一条消息发出去之前，**上下文被自动压了一次**（2026-09-10）。
+ * 模型在**一次回复内**开始复读，被我们掐掉了（core 的 `repetition-detector.ts`）。
  *
- * ## 没有这一帧的话，用户看到的是「它忘了我们刚才聊的」
+ * ⚠️ **和 `'stalled'` 刻意分开。** 那一档是「连续多轮调同一个工具」，
+ * 用户能做的是换个说法或者自己接手；这一档整轮工具调用为零，是解码退化，
+ * 处置是重发一次（大概率就好了）。混成一个值之后，界面上只能给出一句
+ * 同时对两种情况都不准的话。
  *
- * 自动压缩是有损的：摘要替掉了早期几十轮的原文。屏幕上那段对话还在
- * （宿主回显的是自己那份记录），而模型手上只剩摘要 —— 于是它接下来那句
- * 「你之前说的那个方案」答得对不上，而**没有任何线索**说过发生了什么。
- * 这一帧就是那个线索，也是「为什么这一轮多花了一笔」的唯一出处。
+ * ⚠️ **也不是 `'length'`。** 那一档是 provider 按 max output tokens 切的、
+ * 那半截正文是模型真想说的；这一档是**我们**在它撞上上限之前主动停的，
+ * 已经产出的正文留着但没有价值。两者在账上差一整个输出预算 ——
+ * 现场那一份是 31.6 KB 里只有 12 种句子。
+ */
+ | 'looping'
+/** 被宿主中止 */
+ | 'aborted'
+/** 模型安全策略拒答 —— 是 **provider** 拒答，不是我们拦的 */
+ | 'content-filter'
+/**
+ * 我们自己的内容合规闸门拦下了（core 的 `compliance/`）。
  *
- * ⚠️ 走 `notice` 而不是 `text-delta`，判据同 `skill-learned`：它不是模型说的话，
- * 塞进正文就会进历史、进落盘、下一轮再进模型。
+ * ⚠️ **刻意不复用 `content-filter`。** 那个值的含义是「provider 拒答了」，
+ * 处置和说法都不一样：那一档用户能做的是换个说法再问，这一档是内容触了
+ * 部署方配的合规红线（词表 + 类别档位），换说法不一定有用，而且该看的是
+ * 「哪个类别」。混成一个值之后，界面上只能给出一句同时对两种情况都不准的话。
  *
- * ⚠️ **两个位置都发这一帧，语义相同**（都是「这一发之前压了」）：
- * `AgentSession` 跑前那道（软线，压完写回会话历史）和 `AgentLoop` 送出前那道
- * （硬线，见 protocol 的 `isPromptOversize`）。不给它们分两档码是因为
- * 用户要知道的是同一件事，而「哪道闸判的」是我们的实现细节。
+ * 输入侧被拦下时也是这个值 —— 那一次**请求根本没发出去**（`usage` 全零），
+ * 与输出侧被拦下的区别在文本里说清，不在这个枚举里分叉。
  */
- | 'context-compacted'
+ | 'compliance'
 /**
- * 这个模型认不认图，**我们查不到，正在现问它本人**（2026-09-11）。
- *
- * ## 为什么这一次探测必须说出来
+ * provider 把这一轮的回复**按 max output tokens 截断了**（2026-09-04）。
  *
- * 它是**用户没要求过的一次额外请求**：多一趟往返（约两秒）、多一笔约 225 token
- * 的账。屏幕上那段静默否则解释不了 —— 用户发了张图，等了两秒，什么都没有。
+ * ## 为什么必须和 `'stop'` 分开
  *
- * 判据同上面几条：多花的钱和多等的时间，只要不是用户自己点的，就欠一句旁白。
+ * 分不开的时候，「模型自己收的」和「话没说完就被切了」在事后**无法区分** ——
+ * 两者在界面上长得一模一样（都是「这一轮没有工具调用」）。而这是所有
+ * 「模型半路停下」类问题的**第一个分诊问题**：一句
+ * 「我先确认苏菲店的信息，再拉昨日数据。」+ 0 个工具调用，到底是模型宣布了
+ * 下一步就收工（该由 `verify:stop` 那道闸救），还是它正要发工具调用时
+ * 被截断（该调高 max output tokens）—— 处置完全相反。
  *
- * ⚠️ **一次探测最多两帧**（「正在问」+ 只在**认图**时补一句「确认认图」）：
- * 不认图那一路后面紧跟着 `error` 帧，那句话已经把结论说全了，再发一帧确认
- * 就是同一件事说两遍。
+ * 实测过一次：`sessions.db` 里 687 条消息的 `finish_reason` 列**全是 NULL**，
+ * 而 `AgentLoop` 当时只判了 `'content-filter'`，没有任何一处判 `'length'`。
+ * 那一轮到底是哪一种，事后答不出来。
  *
- * ⚠️ 每个型号**一辈子只探一次**（结论进 `~/.epoch/cache/model_probe.json`，
- * 认图存 30 天、不认图存 24 小时），所以这一帧天然罕见。要是它开始每轮都出现，
- * 说明缓存写不进去（只读的 home），那是个 bug，不是这一帧的问题。
+ * ⚠️ **这一档不是「出错了」。** 请求成功、已经计费、那半截正文是真的，
+ * 只是它不完整。宿主该说的话是「回复被截断了」而不是「失败了」。
  */
- | 'image-probe'
+ | 'length'
 /**
- * **历史里**那几张图被摘掉了，因为此刻这个模型不认图（2026-09-12）。
+ * 这一轮**干了活却什么都没说**：零工具调用收尾，而正文是空的（或只有几个字），
+ * 而且踢回去重答一次之后还是这样（2026-09-16）。
  *
- * ## 和上面 `images-dropped`、和 `agent_run.images_unsupported` 三者的分工
+ * ## 为什么必须和 `'stop'` 分开
  *
- * | | 图从哪来 | 谁判的 | 请求 | 钱 |
- * | --- | --- | --- | --- | --- |
- * | `images_unsupported`（`error` 帧） | **这一轮新发的** | 我们（闸门 1） | 不发 | 没花 |
- * | 这一条（`notice` 帧） | **历史里的** | 我们（装 history 时） | 照发 | 花了，但图不占 token |
- * | `images-dropped`（`notice` 帧） | 这一轮新发的 | **provider 的 warning** | 已发 | 花了 |
+ * 分不开的时候，它和「模型正常收工」在事后**和当场都**无法区分 —— 两边都是
+ * 「这一轮没有工具调用」+ 一个 `finish_reason` 说 `stop`。现场是
+ * `deepseek-flash` 调了 8 次工具、烧掉 289.2k token，最后正文只有「阿飞」
+ * 两个字；同一个库里第二例正文是**空串**，reasoning 只有一个 `The`。
+ * 两条都被记成了成功收工：`hooks.fire('stop')` 照发、`maybeLearn()` 照跑、
+ * headless 的 `ok` 照给。
+ *
+ * ⚠️ **这一档和 `'length'` 不是一回事。** 那一档 provider 亲口说了它切了
+ * （`finishReason === 'length'`），处置是调高 max output tokens；这一档
+ * provider 说的是 `stop` —— 它认为自己正常说完了，而说出来的是空气。
+ * 实测那两例的账：`outputTokens − reasoningTokens` 减掉工具调用 JSON 之后
+ * 残差是 −61 / −58 token（估计噪声 ±484），也就是**正文真的没生成**，
+ * 不是生成了没落库。
+ *
+ * ⚠️ **这一档不是「出错了」。** 请求成功、已经计费。宿主该说的是
+ * 「这一轮没有产出回复」，而不是「失败了」—— 但它**也不是成功**，
+ * 所以 headless 的 `ok` 和调度的 `ok` 都不该给（判据在
+ * `runtime/src/schedule/executor.ts` 的 `FINISH_STATUS` 上）。
+ */
+ | 'blank'
+/** 触达成本或 token 预算上限 */
+ | 'budget-exceeded'
+/** 异常终止（详情见前一个 error 事件） */
+ | 'error';
+type AgentEvent = 
+/**
+ * 这一轮真的要发出去了 —— **决定 8 的第一个时刻**（方案 42 §七，2026-08-15）。
  *
- * 第一行是「你现在做的这件事做不了」，用户当场能改（换模型 / 去掉图）；
- * 这一条是「你**以前**做的那件事，从现在起看不见了」—— 他此刻什么都没做，
- * 所以更需要一句旁白。
+ * ## 发它的是谁
  *
- * ## 没有这一帧的话，这件事是彻底静默的
+ * core 的 `agent/loop.ts`，在**第一次模型请求之前**、且**在预算闸门之后**。
+ * 位置是有判据的：闸门拦下的那一次请求根本没发出去，给它发一条「这一轮开跑了」
+ * 是在宣布一件没发生的事（events.ts 上一条 ⚠️ 骂的正是「声明了却没有发射方」，
+ * 这一条反过来 —— 别发一件没发生的）。
  *
- * 触发面是两个：`epoch --resume` 装一段贴过图的会话（启动路径上**没有任何
- * 能力检查**），以及 `/model` 切到一个能力**查不到**的型号
- * （`provider/selection.ts` 那条硬拒绝只挡查得到不认图的）。两条路上用户都
- * 没有再发图，于是屏幕上不会有任何东西提到图 —— 而模型接下来那句
- * 「你发的那张截图我看不到」会像是它在犯病。
+ * 一次 `run()` 最多一条：它是「这一轮」的头，不是「这一步」的。
+ * 收尾那条 `finish` 是它的另一半，两者一头一尾夹住同一段。
  *
- * ⚠️ **一次 run 只发一帧**，判据逐字同 `images-dropped`：那几张历史图在这次
- * run 的每一轮都要重新摘一次，逐轮报的话一次多工具调用的对话会刷出十几行。
- */
- | 'history-images-stripped';
-type AgentEventType = AgentEvent['type'];
-/** 取出某个具体事件的类型，例如 AgentEventOf<'tool-call'> */
-type AgentEventOf<T extends AgentEventType> = Extract<AgentEvent, {
-    type: T;
-}>;
-
-/**
- * 插件契约。
+ * ## `estimatedTokens` 是**估算**，而且永远是
  *
- * 插件是 epoch-agent 的扩展单元：一个独立 npm 包，实现 EpochPlugin 接口来提供
- * 工具、技能和生命周期钩子。插件只需依赖本包（@epoch-agent/protocol），
- * 不依赖引擎实现。
+ * 它是那一刻手里那份完整待发送载荷（system prompt + 工具定义 + 全部消息）
+ * 过一遍 `estimateTokens()` 的结果。2026-08-15 换了真分词器（o200k_base）之后
+ * 这个数**说得出真话**了 —— 在那之前 `chars/4` 在中文场景系统性低估 2–2.7 倍。
  *
- * 设计参考：
- * - MCP (Model Context Protocol) 的 tool 定义格式
- * - Vercel AI SDK 的 tool 接口
+ * ⚠️ **换了真分词器不等于它变成了事实**，别把这两句话弄反：
+ *
+ * 1. 分词器是 o200k_base，而模型可能是 Claude / DeepSeek，各家 BPE 不同 ——
+ *    这是 `provider/tokenizer.ts` 文件头明写的「有意的近似」；
+ * 2. 更硬的一条：这个数是**发之前**算的，而真值只有 provider 回的 usage 说了算，
+ *    中途还会插进压缩、任务通知、工具结果。
+ *
+ * 所以界面上那枚「估算」徽标**不许摘**，判据同 `design/web-ui/thread.css`
+ * 里 `.est` 那条：token 的三个时刻里只有运行前这一个是猜的。
+ *
+ * ## 为什么不复用 `usage` 事件
+ *
+ * `usage` 上两个数都来自 provider 的实测回报（`cumulative` / `run`），
+ * 往里塞一个猜出来的数，就得让每个消费方去判「这个字段是真的还是估的」——
+ * 而那正是徽标要替用户回答的问题。两笔账两条事件，别合。
  */
-
-/** 技能定义 */
-interface EpochSkill {
-    /** 技能名称 */
-    name: string;
-    /** 触发条件（自然语言描述 LLM 何时应加载此技能） */
-    trigger: string;
-    /** 技能内容（Markdown 格式的流程指南） */
-    content: string;
+{
+    type: 'run-start';
+    /**
+     * 这一轮由哪个角色在跑。**顶层会话没指定角色时整个键缺席**，
+     * 不是给一个 `general` —— 「没选专家」在决定 20 ② 里是一个有形状的值
+     * （底栏没有 chip），编一个默认名等于把那个值抹掉。
+     */
+    role?: ActiveAgentRole;
+    /** 运行前估算。见上面那两条为什么它永远带「估算」二字 */
+    estimatedTokens: number;
 }
-/** 生命周期钩子 */
-interface EpochHook {
-    /** 钩子类型 */
-    type: HookType;
-    /** 执行函数 */
-    handler: (event: HookEvent) => Promise<void>;
+/** 回复正文增量 */
+ | {
+    type: 'text-delta';
+    text: string;
+}
+/** 推理模型的思考过程增量 */
+ | {
+    type: 'reasoning-delta';
+    text: string;
+}
+/** 模型请求调用工具（执行前） */
+ | {
+    type: 'tool-call';
+    callId: string;
+    toolName: string;
+    input: Record<string, unknown>;
 }
 /**
- * 日志出口 —— 库代码唯一允许的「说点什么」的通道。
+ * 工具**执行过程中**的输出增量。callId 与对应的 tool-call 一致。
  *
- * 库不许直接写 stderr：嵌进 Electron 主进程或服务端之后，`console.warn` 既进不了
- * 宿主的日志系统，也没法在 UI 上呈现，更关不掉。所以凡是原来想 console 的地方，
- * 一律收成这个签名，由装配层从宿主那里接一个进来；宿主不给就静默 —— 不是退回 stderr。
+ * 这是一条**只给人看**的旁路通道：模型看到的永远是最终 `tool-result.output`
+ * （那份已经截断、已经包过隔离标签）。加它是因为 `tool-call` 和 `tool-result`
+ * 之间可以隔着一次三分钟的 `pnpm build` —— 在那三分钟里宿主一个事件都收不到，
+ * 屏幕上是一行不动的 `⏳ terminal`，用户分不清是在跑还是挂了。
  *
- * 这本来就是 `PluginContext.log` 的签名，只是以前只有插件能用。
+ * 发这个事件的工具不必逐 chunk 发：引擎侧统一做合并窗口、剥 ANSI、`\r` 折叠
+ * 和总量封顶（见 core 的 tool-output-pump.ts），工具只管把原始 chunk 交出来。
  *
- * **`message` 必须自带完整信息**：`detail` 是给结构化日志系统的补充，
- * 一个只看 `message` 的朴素宿主实现不能因此丢掉错误原因。
+ * 宿主可以完全忽略它 —— 忽略的结果就是改动前的行为。
+ */
+ | {
+    type: 'tool-output-delta';
+    callId: string;
+    toolName: string;
+    text: string;
+}
+/**
+ * 工具执行完毕。callId 与对应的 tool-call 一致。
  *
- * 级别刻意写成内联联合、不另开一个 `LogLevel` 导出：infra 的 logger 里已经有一个
- * 结构完全相同的 `LogLevel`，而 protocol 和 infra 都是零内部依赖的包，谁也 import
- * 不了谁。与其在两个包里各挂一个同名类型让人猜该用哪个，不如这里不占这个名字 ——
- * 要单独引用级别时写 `Parameters<LogFn>[0]`。
+ * `artifacts` 给宿主渲染缩略图 / 打开文件用。它和 `output` 是**两个通道**：
+ * `output` 是喂给模型的纯文本（已含每个 artifact 的 summary），
+ * `artifacts` 是给人看的那一份 —— 宿主不必解析 output 去猜有没有图。
  */
-type LogFn = (level: 'debug' | 'info' | 'warn' | 'error', message: string, detail?: object) => void;
-/** 插件上下文（初始化时注入） */
-interface PluginContext {
-    /** 工作目录 */
-    workDir: string;
-    /** 配置数据 */
-    config: Record<string, unknown>;
-    /** 日志函数 */
-    log: LogFn;
+ | {
+    type: 'tool-result';
+    callId: string;
+    toolName: string;
+    output: string;
+    ok: boolean;
+    artifacts?: ToolArtifact[];
 }
-/** 插件定义 */
-interface EpochPlugin {
-    /** 插件唯一标识（对应 npm 包名） */
-    name: string;
-    /** 语义化版本 */
-    version: string;
-    /** 插件描述 */
-    description: string;
-    /** 提供的工具列表 */
-    tools?: EpochTool[];
-    /** 提供的技能（可复用的 prompt 模板） */
-    skills?: EpochSkill[];
-    /** 注册的生命周期钩子 */
-    hooks?: EpochHook[];
-    /** 初始化回调 */
-    onInit?: (ctx: PluginContext) => Promise<void>;
-    /** 清理回调 */
-    onDestroy?: () => Promise<void>;
+/** 一轮 ReAct 结束（轮次从 1 开始） */
+ | {
+    type: 'turn-complete';
+    turn: number;
 }
-
 /**
- * Hook 契约。
+ * 需要用户确认。宿主**必须**调用 respond()，否则引擎会一直阻塞在这里。
+ * 引擎侧对未答复的请求有兜底（流结束时按 deny 处理），但那意味着操作被拒。
  *
- * 参考 Hermes hermes_cli/plugins.py → VALID_HOOKS + invoke_hook
+ * `note` 只有计划审批的 `plan-revise` 用得上 —— 它装的是用户的修改意见，
+ * 其余出口一律忽略。**没有它这个出口就是个死循环**：模型不知道要改什么，
+ * 只会把同一份计划原样再交一次。
+ */
+ | {
+    type: 'approval-request';
+    request: ApprovalRequest;
+    respond: (outcome: ApprovalOutcome, note?: string) => void;
+}
+/**
+ * 模型问了一个结构化问题，等用户选（方案 34）。宿主**必须**调用 `respond()`，
+ * 否则引擎会一直阻塞在这里。
  *
- * 注意：HookType 之前在 core/src/plugin.ts 和 core/src/hook/types.ts 各有一份，
- * 且**内容不同**（plugin.ts 那份只有 7 个事件，缺 compress:after / transform:* /
- * verify:stop）。插件作者按 EpochHook 写代码时拿到的是窄的那份，注册进
- * HookManager 却是宽的那份。这里合并成唯一一份。
+ * 结构与 `approval-request` 同构（请求 + 一个答复闭包），于是中继、wire 编码、
+ * 宿主回调那几层一个都不用新造。但**语义不同，别把两者的兜底混用**：
+ * 审批答不上来时有一个安全侧（`deny`），提问没有 —— 替用户挑一个选项和替他
+ * 点「允许」一样糟。答不上来只有一种表达：`respond({ answers: {}, skipped: true })`，
+ * 模型收到之后**自己决定**（通常是选默认继续），这一轮不算失败。
+ *
+ * 引擎侧对未答复的请求有兜底（流结束时按「跳过」处理）—— 那不是伪造答案，
+ * 是如实说「没人答」。
  */
-
-type HookType = 'session:start' | 'session:end' | 'turn:before' | 'turn:after' | 'tool:before' | 'tool:after' | 'stop' | 'compress:after' | 'transform:tool:output' | 'transform:response' | 'transform:user:input' | 'verify:stop';
-interface HookEvent {
-    type: HookType;
-    sessionId: string;
-    timestamp: number;
-    turnIndex?: number;
-    userMessage?: string;
-    response?: string;
+ | {
+    type: 'question';
+    request: QuestionRequest;
+    respond: (answer: QuestionAnswer) => void;
+}
+/**
+ * 补丁预览：这次工具调用真的改了哪个文件、改成什么样。
+ *
+ * 发它的是 core 的 `agent/file-diff.ts`（`ToolExecutor` 在写类工具动手前后
+ * 各读一遍盘），排在同一次调用的 `tool-result` **之前**。
+ * `oldContent` 缺 = 这个文件是新建的；`newContent` 缺 = 被删了；两者都在 = 改了。
+ *
+ * ⚠️ 这个类型 2026-08-13 之前**声明在这里、消费在 view、渲染在两个宿主，
+ * 中间一个发射方都没有** —— 三边契约测试全绿，因为站在引擎位置上的是
+ * fixture 喂出来的假 agent。判据见 `.agents/plans/43-web-ui-shell-plan.md` §12.5。
+ * **往这个 union 里加新类型时，先想清楚谁发。**
+ */
+ | {
+    type: 'diff';
+    filePath: string;
+    oldContent?: string;
+    newContent?: string;
+}
+/** 累计用量变化（每轮结束时发一次，宿主用来更新状态栏） */
+ | {
+    type: 'usage';
+    cumulative: TokenUsage;
     /**
-     * 这一轮的用量。**provider 没上报时整个字段缺席**，不是一个填了 0 的对象 ——
-     * 插件据此能区分「这轮没花钱」和「这轮花了多少不知道」（方案 42 PR-0）。
+     * **到此刻为止、这一次 run** 的用量（方案 42 PR-2）。
+     *
+     * 和 `finish.runUsage` 同一笔账，只是这一份是**过程中**的快照 ——
+     * 界面上「运行中：已消耗 N token」要的就是它。
+     *
+     * ⚠️ 为什么不让宿主拿 `cumulative` 相减：相减要有一个起算基线，而
+     * 「run 开始那一刻的累计」在事件流上根本没有 —— 第一帧 `usage` 到达时，
+     * 它的 `cumulative` 既可能是本轮用量、也可能是 `BudgetStore` 恢复的历史
+     * 加上本轮，从流本身分辨不了。基线猜错的代价是屏幕上那个数直接差一个量级。
      */
-    usage?: TokenUsage;
-    toolName?: string;
-    toolArgs?: Record<string, unknown>;
-    toolResult?: {
-        success: boolean;
-        output: string;
-        error?: {
-            code: number;
-            message: string;
-        };
+    run?: TokenUsage;
+    budgetRemaining?: {
+        costUsd?: number;
+        tokens?: number;
     };
-    rawOutput?: string;
-    rawInput?: string;
-    reason?: string;
-    messageCount?: number;
-    totalTokens?: number;
-    prunedCount?: number;
-    summaryTokens?: number;
-    turns?: Array<{
-        index: number;
-        llmResponse: string | null;
-    }>;
-    data?: Record<string, unknown>;
-}
-interface HookContext {
-    workDir: string;
-    log: (level: 'debug' | 'info' | 'warn' | 'error', message: string) => void;
-}
-type HookHandler<T = void> = (event: HookEvent, ctx: HookContext) => Promise<T>;
-interface HookRegistration {
-    type: HookType;
-    handler: HookHandler<unknown>;
-    priority: number;
-    plugin: string;
-}
-interface VerifyResult {
-    action: 'stop' | 'continue';
-    message?: string;
 }
-/** Hook 管理器接口（实现在 core） */
-interface HookManager {
+/**
+ * 运行结束。
+ *
+ * `breach` 只在 `reason === 'budget-exceeded'` 时有值，说明是哪条上限触顶的。
+ * 没有它的话「触顶」在事件流上只是一句中文提示（`describeBreach()` 的产物），
+ * 而机器宿主要分支就只能去正则匹配那句中文 —— 我们改一个字它就碎。
+ *
+ * ## `usage` 和 `runUsage` 是两笔账，别当同义词（方案 42 PR-2）
+ *
+ * `usage` 是 `BudgetGuard.snapshot()` —— **累计**，口径由 `EpochRuntime.usageScope`
+ * 决定（配了 `BudgetStore` 就是跨会话累计，否则是本进程从零算）。宿主拿它画
+ * 「这个会话一共花了多少」。
+ *
+ * `runUsage` 是**这一次 run** 的用量，由本次循环里每一轮的 `result.usage`
+ * 累加而成。加它的理由很具体：界面上每一轮结束时要写「共 14,270 token」，
+ * 而那个数**减不出来** —— 累计值可能被 `BudgetStore` 从上次会话恢复，
+ * 「第一个累计值」既可能是本轮用量、也可能是历史 + 本轮，
+ * 从事件流本身分辨不了（`AgentLoopConfig.onTurnUsage` 那段注释骂的是同一件事）。
+ *
+ * **两个都是可选的，那不是偷懒**：一次 run 可以一次模型调用都没发生就结束
+ * （装配抛异常、预算在发送前拦下）。那时候「这一轮用了多少 / 用的哪个模型」
+ * 没有答案，而给一个 0 和给配置里那个模型名都是撒谎 —— 与
+ * `TokenUsage.costUsd` 的「0 是免费，undefined 是不知道」同一条约定。
+ */
+ | {
+    type: 'finish';
+    reason: FinishReason;
+    usage: TokenUsage;
+    /** **这一次 run** 的用量。provider 一次都没上报就没有这个键 */
+    runUsage?: TokenUsage;
     /**
-     * 宿主注入的诊断出口，同时也是 `HookContext.log` 的来源。
+     * 最后一次模型调用**实际回来**的模型（`GenerateOutput.model`）。
      *
-     * 挂在管理器上而不是让 `AgentLoop` 另外收一个 logger：那样宿主要接两次，
-     * 接漏一处就是「hook 系统自己的告警有人收、插件在 hook 里说的话没人收」。
-     * 可选是给别的实现留的余地，缺省时 `HookContext.log` 退化成静默。
+     * ⚠️ 不是配置里选的那个。降级和 `switch_model` 之后两者不一样，而
+     * 「这一轮到底是谁答的」正是那时候用户最需要知道的一件事。
      */
-    readonly log?: LogFn;
-    register(reg: HookRegistration): void;
-    trigger(type: HookType, event: HookEvent, ctx: HookContext): Promise<void>;
-    triggerTransform<T>(type: HookType, event: HookEvent, ctx: HookContext): Promise<T | null>;
-    triggerVerify(type: HookType, event: HookEvent, ctx: HookContext): Promise<VerifyResult[]>;
-    /** 从 EpochConfig.hooks 加载 command hooks */
-    loadFromConfig(rawHooks: Record<string, unknown> | undefined): void;
-    /** 触发 command hooks（用于 tool:before 等可阻止的事件） */
-    triggerCommandHooks(type: HookType, event: HookEvent, workDir: string): Promise<{
-        blocked: boolean;
-        reason?: string;
-    } | null>;
-    hasHook(type: HookType): boolean;
-    unregister(type: HookType, handler: HookHandler<unknown>): void;
-    count(type: HookType): number;
+    model?: string;
+    /**
+     * 最后一次模型调用**要求**的那个模型（`GenerateOutput.requestedModel`）。
+     *
+     * 和上面的 {@link model} 是一对，宿主要的那个事实是**两者是否相等** ——
+     * 不等 = 引擎降级了，相等 = 用户/命令自己挑的。
+     *
+     * ⚠️ **读侧不许拿 `model` 去和「当前配置/当前选择」比来代替这个判断。**
+     * 那是一个按**此刻**的值，而这条断言是按**轮**的 —— 它会被拿去比对所有
+     * 历史轮，于是用户在顶栏换一次模型，之前那些跑得好好的轮子集体变成
+     * 「故障转移」。web 脚注那枚徽标栽过这一次，判据全文在
+     * `core/src/provider/types.ts` 的 `GenerateOutput.requestedModel` 上。
+     */
+    requestedModel?: string;
+    breach?: BudgetBreach;
 }
-
 /**
- * 定时任务契约（方案 45）。
+ * 引擎有一句话要对用户说，而**它不是回复正文**（2026-08-26）。
  *
- * 这一份只装**形状**：触发器怎么表达、一条任务有哪些字段、一次运行留下什么。
- * 注册进操作系统、抢锁、跑一次，全在 `core/src/schedule/` 和 `runtime` 里。
+ * ## 发它的是谁，以及为什么非要一条新帧
  *
- * ## 为什么触发器是判别联合，而存储是一段 JSON
+ * 今天唯一的发射方是 core 的 `AgentLoop`：技能学习器在上一轮收尾之后
+ * fire-and-forget 学到了一条技能，而那件事没有任何出口（判据全文在
+ * `agent/loop.ts` 的 `maybeLearn()`）。三条现成的路各自被什么挡掉：
  *
- * 三档的字段完全不同（每周要 `weekdays`、按间隔要 `everyMinutes`、单次还要个
- * 日期），拆成列会得到一张一半是 NULL 的表。所以库里 `trigger_spec` 是一段
- * JSON —— 但**类型是这个联合**，JSON 只是它的存储形式。反过来（先有列再拼
- * 类型）的代价是「每周三个字段里只填了两个」这种状态在类型上说得出口。
+ * 1. **`text-delta`** —— 它会被折进 assistant 那一段正文，于是这句话进历史、
+ *    进落盘、下一轮再进模型。一句「你学会了 X」被当成模型自己说过的话，
+ *    等于往上下文里塞一条它没说过的发言；
+ * 2. **往 system prompt 里塞** —— 那是 prompt cache 的前缀，每轮加一句会让整段
+ *    对话的缓存逐轮失效。同一条判据 `loop.ts` 里为后台任务通知讲过一遍；
+ * 3. **一条 `[系统]` 进历史**（`systemNote()` + `recordNote()`，样板是
+ *    `runtime` 的 `markRoleHandoff()`）—— 它是真出口，但那句话**只在刷新 /
+ *    回放时看得见**，而且今天只有 web 认那个前缀，TUI 会把 `[系统] ` 原样露出来。
  *
- * ## 为什么没有完整 cron 表达式
+ * ## 为什么是「码 + 已经翻好的话」两个字段
  *
- * 这三档正好是 Windows 任务计划（`schtasks`）与 macOS launchd 的**公共**能力，
- * 而 5 字段 cron 不是。写全 cron 等于把「时区 + 夏令时 + 闰日」搬回我们自己的
- * 代码里算下一次触发时刻 —— 而把触发交给操作系统的全部意义就是不碰它们。
- * 判据一句话：**一个语义在两个平台上不能逐字一致，就不做这个语义。**
- */
-
-/** 三档频率。和 WorkBuddy 的分档逐字一致，理由见文件头 */
-type ScheduleTriggerKind = 'cron' | 'interval' | 'once';
-/** 星期。`0` = 周日 … `6` = 周六，与 `Date.prototype.getDay()` 同口径 */
-type ScheduleWeekday = 0 | 1 | 2 | 3 | 4 | 5 | 6;
-/**
- * 「周期」档的三种周期。
+ * `text` 由**发射方**（core，它有 `t()`）翻好：`@epoch-agent/view` 只依赖
+ * protocol、够不着 catalog，在那儿兜底就只能是中文 —— 同 `error` 那条空 message
+ * 的兜底为什么落在两个宿主身上，是同一条判据。
  *
- * 和 `ScheduleTriggerKind` 不是一回事：那个分的是三档，这个只细分 `cron` 那一档。
+ * `code` 是给**要分支的宿主**的：判「这是哪一类通知」不许去 `includes()` 那句
+ * 随时会改的话（RECORD-40-i18n §32.1 那条 `reason === '已取消'` 的教训）。
+ *
+ * ⚠️ **要拿技能名去做别的事**（跳到能力页、打开那份 SKILL.md），就再加一个
+ * 字段，别去正则 `text` —— 那句话是会随文案改的。
  */
-type ScheduleCycle = 'daily' | 'weekly' | 'monthly';
+ | {
+    type: 'notice';
+    code: NoticeCode;
+    text: string;
+}
 /**
- * 触发器。
+ * 用户在这一轮**跑到一半时**插进来的一句话，已经被引擎取走并拌进上下文
+ * （2026-09-16）。
  *
- * 所有带时刻的档共用 `at: 'HH:mm'`（24 小时制，**本机时区**）—— 统一成一个字段名
- * 是为了让「几点跑」在三档之间读起来是同一件事；单次那一档另加 `date`。
+ * ## 它是「已经发生」的回执，不是请求
+ *
+ * 发它的是 core 的 `agent/loop.ts`，**在那句话真的被 push 进 `messages`
+ * 的同一处**。宿主收到它就意味着「模型下一次请求会看见这句话」——
+ * 在这之前那条消息只是躺在宿主自己的队列里，随时可能因为
+ * 到了 `maxTurns`、或者这一轮被中止而**根本没进去**。
+ *
+ * 两件事因此只能由这一帧回答，别在宿主侧猜：
+ *
+ * 1. **落盘位置**。`runtime` 收到它才写那条 user 行，写下去的位置正是它在
+ *    事件流里的位置 —— 也就是模型看到的位置。宿主自己按「发送时刻」插的话，
+ *    会插到那一刻还在流式输出的 assistant 行**前面**去
+ *    （hermes 的 #73793 就是这个形状：mid-turn user bubble 被拼在
+ *    active assistant stream row 之前）。
+ * 2. **界面上说哪句话**。「插进这一轮了」和「排在这一轮后面」是两件事，
+ *    而 `POST /messages` 那一刻答不出是哪一件（见 `WireSendMessageResponse`）。
+ *
+ * ## 为什么不复用 `text-delta` 或者 `notice`
+ *
+ * 前者是**模型**说的话，宿主拿它拼 assistant 正文；这一条是**用户**说的，
+ * 拼进去等于把用户的话记成模型的回答。后者是「给人看一眼就过去」的旁路，
+ * 不落盘（判据在 `TurnStepCollector` 那个 `default` 上），而这一条必须落盘。
+ *
+ * ## `text` 与 `parts`
+ *
+ * 同 `EpochMessage`：`text` 是文本投影（落 `content` 列、进 FTS），
+ * `parts` 只在有图片 / 文件时出现。**`parts` 里的 base64 不落 `text`** ——
+ * 判据同 `AgentSession.run()` 里那句「绝不能把 base64 塞进这里」。
  */
-type ScheduleTrigger = {
-    kind: 'cron';
-    cycle: 'daily';
-    at: string;
-} | {
-    kind: 'cron';
-    cycle: 'weekly';
-    at: string;
-    weekdays: readonly ScheduleWeekday[];
-}
-/** `days` 是几号（1–31）。31 号在小月不触发，两个平台的原生行为一致 */
  | {
-    kind: 'cron';
-    cycle: 'monthly';
-    at: string;
-    days: readonly number[];
-} | {
-    kind: 'interval';
-    everyMinutes: number;
+    type: 'steer';
+    text: string;
+    parts?: EpochContentPart[];
 }
-/** `date` 是 `YYYY-MM-DD` */
+/** 运行中出错（随后会有一个 finish: 'error'） */
  | {
-    kind: 'once';
-    date: string;
-    at: string;
+    type: 'error';
+    message: string;
 };
 /**
- * 「按间隔」档的**全部**合法取值（分钟）。
+ * 一条 `notice` 是哪一类。
  *
- * 收紧成「60 的约数」和「整小时数」不是洁癖，是 launchd 的硬约束：那一侧只能用
- * `StartCalendarInterval`（列举时刻），不能用 `StartInterval`（睡眠时那一次会被
- * 丢掉，10.11 起文档明写）。60 除不尽 7 时，「每 7 分钟」列举出来的那 9 个时刻
- * 在每小时边界上会漂 —— 于是 Windows 上准、macOS 上漂，而那种平台差异是 bug 的温床。
+ * 写成联合而不是 `string`，是为了让**加一档时消费方的 switch 会红** ——
+ * 判据同 wire.ts 的 `WireResetReason`。
  *
- * 界面上因此是个下拉而不是数字输入框：下拉能表达「只有这些值」，
- * 输入框会让人填 7 然后得到一个漂的任务。
+ * ⚠️ 这里原来写着「今天只有一种」—— 那句话在写下之后就一直在过期
+ * （`images-dropped` / `compliance-masked` / `response-truncated` 陆续进来）。
+ * 有几种去数下面这个联合，别在散文里再抄一个会骗人的数字。
  */
-declare const SCHEDULE_INTERVAL_MINUTES: readonly number[];
+type NoticeCode = 
 /**
- * 一次运行的结局。
+ * 技能学习器在上一轮收尾之后学到了一条技能。
  *
- * 后三个是「没跑」而不是「跑失败了」，它们必须和 `failed` 分开 ——
- * 界面上把「上一次因为上一次还在跑所以跳过了」显示成红叉，用户会去查一个不存在的故障。
+ * ⚠️ 这一帧发在**下一轮的头上**，不是学成的那一刻 —— 学成时那条流早关了
+ * （`maybeLearn()` 紧接着就是 `yield finish('stop'); return;`）。发在这里还有
+ * 第二层意思：那一轮正是这条技能**真的进了 system prompt** 的那一轮。
  */
-type ScheduleRunStatus = 'ok' | 'failed' | 'denied' | 'timeout' | 'budget' | 'skipped-overlap' | 'skipped-window' | 'missed';
-/** 合法结局全集。存进库之前用它收窄，别让一个拼错的状态混进 `last_status` */
-declare const SCHEDULE_RUN_STATUSES: readonly ScheduleRunStatus[];
+'skill-learned'
 /**
- * 任务注册在哪儿。
+ * provider **把用户发的图片丢了**，而请求已经发出去、已经计费（2026-09-01）。
  *
- * - `schtasks` / `launchd` —— 真的注册进了操作系统的调度器，**epoch 不用开着**
- * - `host` —— **一行都没注册进 OS**（方案 45 §2.6 的路 B）。到点了唤起它的只能是
- *   宿主自己（`setInterval` 调 `fire()`）—— 而宿主有没有真的这么做，**这一格答不出来**，
- *   它唯一承诺的事实就是「没进 OS」。所以界面上不许把它写成「已启用」，
- *   也**不许许诺「开着就会跑」**（判据全文在 locales 的 `notice_host` 上）
+ * 和 `agent_run.images_unsupported` 那条错误分得很清，两者别混：
+ *
+ * | | 谁判的 | 什么时候 | 钱 |
+ * | --- | --- | --- | --- |
+ * | `images_unsupported`（`error` 帧） | **我们**（闸门 1 的输入侧） | 发请求**之前** | 没花 |
+ * | 这一条（`notice` 帧） | **provider 自己报的 warning** | 请求回来之后 | **已经花了** |
+ *
+ * 也就是说走到这一帧意味着闸门 1 判「这个模型认图」，而 provider 那侧不认。
+ * 2026-09-01 那次事故就是这一格：`@ai-sdk/deepseek@3.0.20` 静默丢弃图片，
+ * 模型对着一张不存在的图回答「我只看到一个占位符」，而屏幕上一个字都没有。
+ *
+ * ⚠️ **一次 run 只发一帧**，不是每轮一帧：带图的那条用户消息在这一次 run 的
+ * 每一轮都会重发，逐轮报的话一次多工具调用的对话会刷出十几行同样的话。
  */
-type ScheduleBackendKind = 'schtasks' | 'launchd' | 'host';
+ | 'images-dropped'
 /**
- * 无人值守清单 —— 「要确认，但没人在，怎么办」。
+ * 内容合规的输入闸门**改写了用户刚发的那句话**（`mask` 档，2026-09-01）。
  *
- * 和权限档（`ScheduleDefinition.permission`）**各管一条轴**：档位回答「这个操作
- * 要不要人确认」，这份清单回答「要确认但没人在时，哪几条可以不问」。
- * 它不是「更宽的一档」，是把「要问人」逐条变成「这一条可以不问」。
+ * ## 没有这一帧的话，这件事是**静默**的
  *
- * 三个字段由粗到细，同时命中任一条即放行：
- * `allowTools` 整个工具 / `allowOperations` 五类操作 / `allowRules` 规则字符串
- * （`terminal(git status)`、`mcp__github__*`、`file_write(./reports/**)`）。
- */
-interface ScheduleAllowlist {
-    allowTools: readonly string[];
-    allowOperations: readonly OperationType[];
-    allowRules: readonly string[];
-}
-/**
- * 一条欠条 —— 「本该问人，但没人可问」。
+ * `mask` 档不拒绝、也不报错：它把命中处换成 `*` 之后照常发出去。而屏幕上那条
+ * 用户气泡显示的是**用户自己敲的原文**（宿主回显的是输入框里那份），
+ * 模型收到的是打过码的那份 —— 两边不一样，且没有任何东西说过这件事。
  *
- * ⚠️ **只收这一类**。权限档自己判出的拒绝（选了「只读」档然后去写文件）
- * **不进欠条** —— 那是档位的判定结果，不是缺授权；把它记成欠条等于建议用户
- * 去加一条永远不会被查到的规则（第 2 层判 deny 时压根走不到第 3 层）。
- */
-interface SchedulePendingApproval {
-    toolName: string;
-    type: OperationType;
-    target: string;
-    /** 权限层给的原因，原样带着 —— 人回来时最想看的就是这句 */
-    reason: string;
-    /**
-     * 该往清单里加哪条规则（`rule-suggest` 算的精确规则）。
-     *
-     * 算不出来时**整个不带这个键**：硬编一条 `terminal()` 出来只会让用户
-     * 加进去一个死规则。
-     */
-    suggestedRule?: string;
-    at: number;
-}
-/**
- * 一条定时任务。
+ * 实测过：`帮我翻译一下黑鬼这个词` 发出去变成 `帮我翻译一下**这个词`。
+ * 用户看着自己那句完整的话，收到一个答非所问的回复，**没有任何线索**。
+ * 这一帧就是那个线索。
  *
- * 时间一律是 **epoch 毫秒**而不是 `Date`：这个形状要过 JSON（存库、将来上 SSE），
- * `Date` 一过 JSON 就变成字符串，于是同一个字段在两处是两种类型。
+ * ⚠️ 和 `block` 那一档分得很清：那一档请求根本没发，走的是
+ * `finish: 'compliance'` + 一句正文，用户当场知道发生了什么。
+ * 这一档请求照发，所以只欠一句旁白。
  */
-interface ScheduleDefinition {
-    id: string;
-    name: string;
-    /**
-     * 停用不等于删除。停用的任务在系统的任务计划里**仍然看得见，只是停着** ——
-     * 删掉再建的话，用户在任务计划程序里看到条目消失会以为我们把他的任务弄丢了。
-     */
-    enabled: boolean;
-    createdAt: number;
-    updatedAt: number;
-    prompt: string;
-    /**
-     * 工作目录。**执行器不许继承 cwd** —— OS 调度器起进程时的 cwd 不由我们决定
-     * （Windows 上是 `%SystemRoot%\System32`）。用户没填时落在
-     * `~/.epoch/automation/<id>/`，那是一个确定的目录，不是「随便哪儿」。
-     */
-    workDir: string;
-    model?: string;
-    /**
-     * 「召唤专家」。**今天永远不带 —— 但已经不是被别人挡着了。**
-     *
-     * 立案时写的是「等方案 42 PR-1 把顶层会话的角色接线」，而那一笔
-     * **2026-08-15 就结清了**（`SessionFactory.create({ role })` +
-     * `WireCreateSessionRequest.role`，见 [agent-role.ts](./agent-role.ts) 文件头）。
-     * 挡着这一格的只剩「没人做」：`add` / 表单 / 端点三条写入路都不写它。
-     * ⚠️ **别把「被别人挡着」和「没人做」读成一件事** —— 逐条状态在
-     * [验收记录 9.2](../../../docs/verify/VERIFY_RECORD-45-automation.md)。
-     */
-    role?: string;
-    /** 同 {@link role}：方案 44 的清单契约早就到齐了，缺的是写入点。今天永远不带 */
-    skills?: readonly string[];
-    /**
-     * 同 {@link role}，缺的是写入点。
-     * 连接器的免确认另有一条现成的路：`allowRules` 里的 `mcp__<server>__*`。
-     */
-    mcpServers?: readonly string[];
-    /**
-     * 权限档 —— **和对话里那枚胶囊同一套取值、同一套词**。
-     *
-     * 界面只暴露四档（`plan` / `default` / `acceptEdits` / `bypass`）。
-     * 不为定时任务发明新词：用户在对话里已经学过这四个词一次，
-     * 再教一套等于让他学两遍同一件事的两种说法。
-     */
-    permission: PermissionLevel;
-    allowTools: readonly string[];
-    allowOperations: readonly OperationType[];
-    allowRules: readonly string[];
-    /** 无人看着的一轮不该比有人看着的更长（交互缺省是 50） */
-    maxTurns: number;
-    /**
-     * **必填，没有默认值。** 这是整个方案唯一一处刻意增加摩擦的地方：
-     * 一个假默认会让「一觉醒来 40 美元」变成我们的错。
-     */
-    maxBudgetUsd: number;
-    /**
-     * 墙钟超时。前两把尺子拦不住「一条 `terminal` 命令挂住了」——
-     * 那种情况轮次和花费都不增长，这把尺子是唯一能拦它的。
-     */
-    timeoutMs: number;
-    trigger: ScheduleTrigger;
-    /**
-     * 生效区间（`YYYY-MM-DD`，含首尾），留空表示始终生效。
-     *
-     * ⚠️ **两个平台在这个字段上语义不同**：Windows 有原生的 `/SD` `/ED`，过了截止日
-     * 系统压根不会调我们；launchd 没有这个概念，所以 macOS 上我们会被调起来、
-     * 然后由执行器自己判出区间外并退 0。
-     */
-    startDate?: string;
-    endDate?: string;
-    osBackend: ScheduleBackendKind;
-    /** 注册进 OS 时用的标识（Windows 的 `epoch\<id>` / launchd 的 `Label`） */
-    osTaskId: string;
-    /** 没注册进 OS 时不带（`osBackend: 'host'`，或者注册失败） */
-    osRegisteredAt?: number;
-    /**
-     * **真正注册进去的那条 argv**，逐字。`doctor` 靠它比对 OS 侧有没有漂。
-     *
-     * 存下来而不是每次现算：现算的结果依赖**此刻**的 `process.execPath` 和入口路径，
-     * 而漂移检查要问的恰恰是「当初写进去的是什么」。
-     */
-    osCommand: readonly string[];
-    lastRunAt?: number;
-    lastStatus?: ScheduleRunStatus;
-}
-/** 一次运行的记录 */
-interface ScheduleRun {
-    id: string;
-    scheduleId: string;
-    /** 真的起了会话才有；三种 `skipped-*` / `missed` 都没有 */
-    sessionId?: string;
-    startedAt: number;
-    endedAt?: number;
-    status: ScheduleRunStatus;
-    exitCode?: number;
-    reason?: string;
-    costUsd: number;
-    tokens?: TokenUsage;
-    turns: number;
-    /** 欠条。空数组 = 这一轮没撞上需要确认的操作 */
-    pendingApprovals: readonly SchedulePendingApproval[];
-    /** 录像（`<runId>.ndjson`）的绝对路径；没起会话时不带 */
-    logPath?: string;
-    /**
-     * `epoch schedule run` 手动跑的那一次。
-     *
-     * 标出来是因为它**不该影响「上一次到点跑成没有」的判断** ——
-     * 用户手点一次成功，不等于明天 9 点那次会成功。
-     */
-    manual: boolean;
-}
+ | 'compliance-masked'
 /**
- * 宿主注入的「怎么以无界面方式唤起我自己」（方案 45 §2.6）。
+ * provider 按 max output tokens **把这一轮的回复切了**（2026-09-04）。
  *
- * 把引擎 `import` 进 Electron / VS Code 扩展的宿主**没有 `epoch` 可执行文件**，
- * 而**库自己分辨不出宿主打算怎么被唤起** —— 所以这件事必须由宿主说。
+ * 和 `FinishReason` 的 `'length'` 是同一件事的两个出口，两个都要：
+ * 收尾原因是给**机器**分支的（headless 的 `result.reason`、落盘的
+ * `finish_reason` 列、web 那枚记号），这一帧是给**人**看的那句话 ——
+ * 屏幕上那半截正文自己不会说「我是半截的」。
  *
- * ⚠️ **绝对不许拿 `process.execPath` + `argv[1]` 去猜。** 在 Electron 里那两个值
- * 是「Electron 的 exe」+「宿主的 main.js」，注册进去的后果是**到点了给用户弹出
- * 整个应用的主窗口**（甚至一天弹 24 次）。那不是「不够好」，是把定时任务变成骚扰。
+ * ⚠️ 走 `notice` 而不是 `text-delta`，判据同上面 `skill-learned` 那三条：
+ * 它不是模型说的话，塞进正文就会进历史、进落盘、下一轮再进模型。
  */
-interface ScheduleRunnerSpec {
-    /**
-     * 无界面入口的 argv 前缀，绝对路径。我们在后面追加
-     * `schedule fire <id> --home <dir>`。
-     *
-     * 那个入口必须**不建窗口、跑完就退**（Electron 里就是在 `whenReady` 之前
-     * 分叉出去）。
-     */
-    argv: readonly string[];
-    /** 注册进 OS 时给人看的名字前缀。不给就用 `epoch` */
-    label?: string;
-}
-
+ | 'response-truncated'
 /**
- * 内置模板六张（[方案 45](../../../docs/verify/VERIFY_RECORD-45-automation.md) §7.3）。
- *
- * 判据是「**这件事必须每天/每周做一次，而且做完是一份能读的东西**」——
- * 所以 WorkBuddy 那 12 张消费级的（儿童睡前故事 / 父母联系提醒 / 萌宠壁纸）
- * 一张都没抄，换成开发者场景。
- *
- * ## ⚠️ 三条硬约束都摊在类型上，不靠注释
- *
- * | §7.3 那句话                     | 落在类型的哪一格                                                     |
- * | ------------------------------- | -------------------------------------------------------------------- |
- * | 模板**不联网**                  | 这是一份 `const`，没有取数入口 —— 在线模板市场 42 已定不做           |
- * | 一律不预设「跳过全部检查」      | {@link ScheduleTemplate.permission} 的取值里**没有** `bypass`         |
- * | 填进表单后**必须让用户过一遍**  | 整份形状里**没有** `maxBudgetUsd`，而它是必填 —— 表单因此保存不了     |
+ * 这一轮零工具调用收尾，而正文是空的（或只有几个字）—— **已经踢回去让它重答**
+ * （2026-09-16）。
  *
- * 最后一条是三条里最要紧的，而它是**结构性**的而不是靠一句提示：预算必填、
- * 没有默认值（§3.5），于是一张模板卡填进表单之后那个保存按钮**天然是灰的**，
- * 用户不看完那一屏就出不去。写成「模板里预填 0.50 + 一句『请检查』」的话，
- * 「必须过一遍」就退化成一句没人读的话。
+ * 和 `FinishReason` 的 `'blank'` 是同一件事的两个出口，但**两者不同时出现**，
+ * 这一点和 `response-truncated` / `'length'` 那一对相反：
  *
- * ## 为什么住在 protocol，而不是「core 一份 + 这里抄一份」
+ *   - 这一帧发在**第一次**判空的那一刻，后面紧跟一次重答。重答成功了的话
+ *     那一轮的收尾原因是 `'stop'`（它确实正常收工了），而屏幕上留着这一句话，
+ *     解释「刚才为什么多花了一轮」；
+ *   - `'blank'` 只在重答**之后还是空**时才落下去。
  *
- * 任务书给的两条路是「从 server 端点下发」或者「抄一份到 protocol + 一条逐项相等
- * 的用例」（照 `WireScheduleIssueCode` 的先例）。**两条都不用，因为这一份和那个
- * 先例不是同一种东西**：
+ * 所以少了这一帧，用户看到的是一次莫名其妙多出来的等待；少了 `'blank'`，
+ * 两次都空的那一轮会被记成成功。两个都要。
  *
- * - `WireScheduleIssueCode` 的真源在 core**必须**在 core —— 那张码表是
- *   `validateSchedule()` 的出口集合，它和判定逻辑长在一起，搬不动；
- * - 而这一份是**纯数据、零判定**：六个触发器、六档权限、六份最小清单。
- *   它谁都不依赖。而 [AGENTS.md](../../../AGENTS.md) 的分层表里 protocol 那一行
- *   写着「跨包共享的东西**只能**放这里」。
- *
- * 放这儿的直接收益是**不存在第二份**：`packages/web` 够得着它（只依赖
- * protocol + view）、cli 够得着、server 够得着、假服务端也够得着。抄一份到
- * protocol 再钉一条「逐项相等」的用例，是在为一个可以不存在的分叉修围栏；
- * 走一条 server 端点则要为一份**从不改变的常量**加一条 HTTP 往返和一个失败态
- * （「模板拉不下来」——而它明明就在包里）。
- *
- * ## ⚠️ 这里一个中文字都没有，措辞在 web 那份 catalog 里
- *
- * 名字 / 说明 / **提示词**三样都是文案：提示词要跟着用户的界面语言走
- * （一个英文界面的用户不该收到一份中文报告），而 protocol 里没有 `t()`、
- * 也不该有。所以这一份只给 `id`，措辞表在
- * `web/src/automation/labels.ts` 的 `TEMPLATE_TEXT` 上 —— 那张表
- * `satisfies Record<ScheduleTemplateId, …>`，**加一张模板而不给它文案会当场编译不过**。
+ * ⚠️ 走 `notice` 而不是 `text-delta`，判据同上面 `skill-learned` 那三条：
+ * 它不是模型说的话，塞进正文就会进历史、进落盘、下一轮再进模型。
  */
-
+ | 'blank-response'
 /**
- * 六张模板的 id。
+ * 这一条消息发出去之前，**上下文被自动压了一次**（2026-09-10）。
  *
- * 它同时是**文案表的键**（web 那侧 `satisfies Record<ScheduleTemplateId, …>`），
- * 所以这个联合就是「有几张模板」的唯一真源 —— 加一张要改的地方由编译器点出来。
- */
-type ScheduleTemplateId = 'repo-sweep' | 'weekly-digest' | 'dep-checkup' | 'stale-docs' | 'test-flake' | 'todo-digest';
-/**
- * 一张模板 = 一条任务除了「名字 / 提示词 / 预算」之外的那些格子。
+ * ## 没有这一帧的话，用户看到的是「它忘了我们刚才聊的」
  *
- * 三样刻意缺席，各有各的理由：
+ * 自动压缩是有损的：摘要替掉了早期几十轮的原文。屏幕上那段对话还在
+ * （宿主回显的是自己那份记录），而模型手上只剩摘要 —— 于是它接下来那句
+ * 「你之前说的那个方案」答得对不上，而**没有任何线索**说过发生了什么。
+ * 这一帧就是那个线索，也是「为什么这一轮多花了一笔」的唯一出处。
  *
- * - `name` / `prompt` —— 是**文案**，见文件头最后一节；
- * - `maxBudgetUsd` —— 必填且没有默认值（§3.5），见文件头那张表第三行；
- * - `workDir` —— 模板不知道用户的仓库在哪儿。留空的语义是
- *   `~/.epoch/automation/<id>/`（`ScheduleDefinition.workDir` 上的判据），
- *   而**清单里那条 `file_write(./reports/**)` 是相对的**，所以它跟着工作区走 ——
- *   不管用户填不填，报告都落在那条任务自己的目录下面。
- */
-interface ScheduleTemplate {
-    id: ScheduleTemplateId;
-    trigger: ScheduleTrigger;
-    /**
-     * 权限档。**取值里没有 `bypass`**（§7.3：模板一律不预设「跳过全部检查」），
-     * 也没有 `auto`（界面压根不暴露它，§3.2）。
-     *
-     * 两档各有各的用法，而分界线是 by-level 那张表：
-     *
-     * - `plan`（只读）—— 「读一遍然后写一份报告」的那几张。它天然零授权面，
-     *   清单里只要一条 `file_write`（那条走**第 2 层**规则匹配，所以在只读档下
-     *   照样放行 —— §3.2 那句「只读 + `file_write(<任务目录>/**)`」说的就是它）；
-     * - `default`（按需确认）—— 要跑命令的那几张。**除了 `bypass`，写命令在每一档
-     *   下都要确认**，所以它们只能靠清单逐条放行，而这正是清单存在的理由。
-     */
-    permission: 'plan' | 'default' | 'acceptEdits';
-    /** 整个工具免确认（粗）。多数模板不用它 —— 逐条列出来的清单才审得动 */
-    allowTools?: readonly string[];
-    allowOperations?: readonly OperationType[];
-    /** 规则（细）。⚠️ **路径一律写成相对的**，理由见 {@link ScheduleTemplate} */
-    allowRules?: readonly string[];
-    /**
-     * 墙钟超时（毫秒）。不给就用引擎缺省的 15 分钟。
-     *
-     * 只有「测试 flake 复盘」给了 —— 它真的要跑一遍测试，而缺省那把尺子会在
-     * 半路把它砍掉。**这一格存在的意义就是让那一张不至于生下来就超时**。
-     */
-    timeoutMs?: number;
-}
-/**
- * 六张。顺序就是界面上卡片的顺序：**两张每天的排在前面** ——
- * 「每天一次」比「每周一次」更容易让人第一次就试出效果，而这一屏的空状态
- * 要答的问题是「这东西能替我做什么」。
+ * ⚠️ 走 `notice` 而不是 `text-delta`，判据同 `skill-learned`：它不是模型说的话，
+ * 塞进正文就会进历史、进落盘、下一轮再进模型。
+ *
+ * ⚠️ **两个位置都发这一帧，语义相同**（都是「这一发之前压了」）：
+ * `AgentSession` 跑前那道（软线，压完写回会话历史）和 `AgentLoop` 送出前那道
+ * （硬线，见 protocol 的 `isPromptOversize`）。不给它们分两档码是因为
+ * 用户要知道的是同一件事，而「哪道闸判的」是我们的实现细节。
  */
-declare const SCHEDULE_TEMPLATES: readonly ScheduleTemplate[];
-
+ | 'context-compacted'
 /**
- * 「还欠着的那几张欠条」——
- * [方案 45](../../../docs/verify/VERIFY_RECORD-45-automation.md) §八 ① / ③ 的素材。
+ * 这个模型认不认图，**我们查不到，正在现问它本人**（2026-09-11）。
  *
- * 三个界面读的是同一个数：dock 上那一条「自动化待确认」、侧栏「自动化」入口上
- * 那个点、TUI 启动时那一行。**它们必须是同一个数** —— 三处各数一遍的下场是
- * 侧栏有点、点进去 dock 上什么都没有。
+ * ## 为什么这一次探测必须说出来
  *
- * ## 一、为什么这份投影住在 protocol
+ * 它是**用户没要求过的一次额外请求**：多一趟往返（约两秒）、多一笔约 225 token
+ * 的账。屏幕上那段静默否则解释不了 —— 用户发了张图，等了两秒，什么都没有。
+ *
+ * 判据同上面几条：多花的钱和多等的时间，只要不是用户自己点的，就欠一句旁白。
  *
- * 它是**纯集合运算**：手上有哪几条任务、每条最近跑过什么、清单里已经有哪几条规则。
- * 没有日期算术、不读盘、不查权限，一个字的 core 知识都不需要。
- * 而它的消费者有四个：`server`（那条端点）、`cli`（`--fix` 和 TUI 那行开机提示）、
- * `packages/web/dev` 那台假服务端、以及将来任何一个嵌入宿主。
- * [AGENTS.md](../../../AGENTS.md) 分层表里 protocol 那一行写着
- * 「跨包共享的东西**只能**放这里」，这就是那一行说的情况。
+ * ⚠️ **一次探测最多两帧**（「正在问」+ 只在**认图**时补一句「确认认图」）：
+ * 不认图那一路后面紧跟着 `error` 帧，那句话已经把结论说全了，再发一帧确认
+ * 就是同一件事说两遍。
  *
- * ⚠️ **这一份落地之前，那个集合运算在仓库里有三份**（`server` 的 `fixSchedule`、
- * `cli` 的 `applyFix`、假服务端的 `fakeScheduleFix`），逐字一样的六行。
- * 三份都是「往授权清单里加规则」这条路上的判定 —— 也就是**提权路径上的重复实现**。
- * 收成一份是这个文件存在的第二个理由，比第一个理由更硬。
+ * ⚠️ 每个型号**一辈子只探一次**（结论进 `~/.epoch/cache/model_probe.json`，
+ * 认图存 30 天、不认图存 24 小时），所以这一帧天然罕见。要是它开始每轮都出现，
+ * 说明缓存写不进去（只读的 home），那是个 bug，不是这一帧的问题。
+ */
+ | 'image-probe'
+/**
+ * **历史里**那几张图被摘掉了，因为此刻这个模型不认图（2026-09-12）。
  *
- * ## 二、「还欠着」= 算得出规则、而且规则还不在清单里
+ * ## 和上面 `images-dropped`、和 `agent_run.images_unsupported` 三者的分工
  *
- * 两道筛，**缺一道这个数就会自己卡住**：
+ * | | 图从哪来 | 谁判的 | 请求 | 钱 |
+ * | --- | --- | --- | --- | --- |
+ * | `images_unsupported`（`error` 帧） | **这一轮新发的** | 我们（闸门 1） | 不发 | 没花 |
+ * | 这一条（`notice` 帧） | **历史里的** | 我们（装 history 时） | 照发 | 花了，但图不占 token |
+ * | `images-dropped`（`notice` 帧） | 这一轮新发的 | **provider 的 warning** | 已发 | 花了 |
  *
- * 1. **`suggestedRule` 必须有值。** 算不出精确规则的那几条（目标为空的操作）
- *    进不了这份清单 —— dock 上唯一的动作是「加进授权清单」，而对它们那一下
- *    什么都加不了。一条点了没用的通知比没有通知坏（设计稿决定 20 ①），
- *    而且它**永远清不掉**：没有任何动作能让它消失。
- *    ⚠️ 它们并没有被藏起来：「运行记录」那一屏上那一轮照旧列着它们、
- *    照旧写着「这一条反推不出精确规则」。这里筛掉的是**通知**，不是事实。
- * 2. **规则还不在 `allowRules` 里。** 用户按过那一下之后规则就进清单了，
- *    于是这个数**自己减一**。这条让整件事不需要「读标记」那套东西 ——
- *    没有迁移、没有「哪个界面算看过」这个产品判断、也没有一个只能靠
- *    「我看过了」来清的角标。
+ * 第一行是「你现在做的这件事做不了」，用户当场能改（换模型 / 去掉图）；
+ * 这一条是「你**以前**做的那件事，从现在起看不见了」—— 他此刻什么都没做，
+ * 所以更需要一句旁白。
  *
- * ## ⚠️ 三、这个数**不含**「上一次没跑成」的那几条，而那是一条判断不是遗漏
+ * ## 没有这一帧的话，这件事是彻底静默的
  *
- * `failed` / `timeout` / `budget` 三档同样是「你该知道的事」，但它们**没有下一步
- * 动作**：屏幕上给不出一个按钮，用户只能去看运行记录。把它们算进来的话，这个点
- * 会一直亮着，直到那条任务下一次跑成 —— 而在那之前它已经不再指向任何可做的事，
- * 也就退化成了一个「有东西发生过」的常亮灯。
+ * 触发面是两个：`epoch --resume` 装一段贴过图的会话（启动路径上**没有任何
+ * 能力检查**），以及 `/model` 切到一个能力**查不到**的型号
+ * （`provider/selection.ts` 那条硬拒绝只挡查得到不认图的）。两条路上用户都
+ * 没有再发图，于是屏幕上不会有任何东西提到图 —— 而模型接下来那句
+ * 「你发的那张截图我看不到」会像是它在犯病。
  *
- * 三档失败在「运行记录」那一屏上有自己的三态色（✅ ⚠️ ❌），一条都没藏。
- * 📮 真要给它们一个计数，前置是一份**读标记**（`schedule` 那个 namespace 加一次
- * 迁移 + 一条写端点 + 「web 打开那个 tab 算不算看过、TUI 启动算不算」这个产品
- * 判断）。那是独立的一次改动，不该顺手塞进这一轮。
+ * ⚠️ **一次 run 只发一帧**，判据逐字同 `images-dropped`：那几张历史图在这次
+ * run 的每一轮都要重新摘一次，逐轮报的话一次多工具调用的对话会刷出十几行。
  */
+ | 'history-images-stripped';
+type AgentEventType = AgentEvent['type'];
+/** 取出某个具体事件的类型，例如 AgentEventOf<'tool-call'> */
+type AgentEventOf<T extends AgentEventType> = Extract<AgentEvent, {
+    type: T;
+}>;
 
 /**
- * 一条**算得出规则**的欠条。
+ * 插件契约。
  *
- * `suggestedRule` 从可选收成必填 —— 这不是换个写法：它让「dock 上那个按钮
- * 一定加得进东西」变成一件类型上成立的事，而不是一句要人记住的注释。
- */
-type FixableApproval = SchedulePendingApproval & {
-    suggestedRule: string;
-};
-/**
- * dock / 侧栏 / TUI 三处共用的一条。
+ * 插件是 epoch-agent 的扩展单元：一个独立 npm 包，实现 EpochPlugin 接口来提供
+ * 工具、技能和生命周期钩子。插件只需依赖本包（@epoch-agent/protocol），
+ * 不依赖引擎实现。
  *
- * 带 `scheduleName` 而不是只带 id：这条通知的措辞必须**有宾语**
- * （「《每日仓库巡检》差一条授权」，不是「有 1 条待确认」）——
- * 判据和跨会话待办条那一条同源（`web/src/dock/crossbar.tsx` 文件头
- * 「措辞必须带宾语」那一节）：一个不带宾语的计数器逼用户挨个点开去看。
+ * 设计参考：
+ * - MCP (Model Context Protocol) 的 tool 定义格式
+ * - Vercel AI SDK 的 tool 接口
  */
-interface SchedulePendingItem {
-    scheduleId: string;
-    scheduleName: string;
-    /** 欠条挂在哪一次运行上。`POST /api/schedules/:id/fix` 收的就是它 */
-    runId: string;
-    /** 那一次运行的开始时刻（epoch 毫秒）。界面上那句「已欠了多久」 */
-    at: number;
-    /** 还没进清单的那几条，**至少一条**（空的那几轮压根不进这份清单） */
-    approvals: readonly FixableApproval[];
+
+/** 技能定义 */
+interface EpochSkill {
+    /** 技能名称 */
+    name: string;
+    /** 触发条件（自然语言描述 LLM 何时应加载此技能） */
+    trigger: string;
+    /** 技能内容（Markdown 格式的流程指南） */
+    content: string;
+}
+/** 生命周期钩子 */
+interface EpochHook {
+    /** 钩子类型 */
+    type: HookType;
+    /** 执行函数 */
+    handler: (event: HookEvent) => Promise<void>;
 }
 /**
- * 这一轮的欠条里，有哪几条规则还不在清单里。**去重，顺序照欠条的顺序。**
- *
- * 三个调用点：这个文件自己（算那个计数）、`POST /api/schedules/:id/fix`
- * （真往清单里写的那一下）、`epoch schedule run --fix`。
- * ⚠️ **三处必须是同一个函数**：它决定的是「往授权清单里加哪几条规则」，
- * 而三份实现走散的方向可能是提权（一边加了另一边没加）。
- */
-declare function unfixedRules(allowRules: readonly string[], approvals: readonly SchedulePendingApproval[]): string[];
-/**
- * 手上那几条任务 + 最近那些运行 → 该通知的清单。
+ * 日志出口 —— 库代码唯一允许的「说点什么」的通道。
  *
- * ## ⚠️ 同一条任务只报**最近**那一次，不是每一次
+ * 库不许直接写 stderr：嵌进 Electron 主进程或服务端之后，`console.warn` 既进不了
+ * 宿主的日志系统，也没法在 UI 上呈现，更关不掉。所以凡是原来想 console 的地方，
+ * 一律收成这个签名，由装配层从宿主那里接一个进来；宿主不给就静默 —— 不是退回 stderr。
  *
- * 一条「每天 9 点」的任务每天记同一条欠条，一周就是七条一模一样的通知。
- * 所以按任务收拢、取最近那一次。这不会漏掉东西：修最近那一次加进去的规则
- * 通常把老的那几次也一起覆盖了；万一老的那次欠的是**另一条**规则，
- * 它在下一次取数时自然浮上来成为「最近的那条未解决的」。
+ * 这本来就是 `PluginContext.log` 的签名，只是以前只有插件能用。
  *
- * ⚠️ 判的是「最近的**还欠着的**那一次」，不是「最近的那一次」：一条任务昨天
- * 卡了、今天跑成了，昨天那条欠条**仍然欠着**（清单里那条规则还是没加），
- * 下一次到点还会再卡一遍。拿「最近一次的状态」当判据会把它静默吞掉。
+ * **`message` 必须自带完整信息**：`detail` 是给结构化日志系统的补充，
+ * 一个只看 `message` 的朴素宿主实现不能因此丢掉错误原因。
  *
- * @param defs 全部任务（`ScheduleControl.list()`）
- * @param runs 最近那些运行，**最新的在前**（`ScheduleControl.recentRuns()` 的顺序）
+ * 级别刻意写成内联联合、不另开一个 `LogLevel` 导出：infra 的 logger 里已经有一个
+ * 结构完全相同的 `LogLevel`，而 protocol 和 infra 都是零内部依赖的包，谁也 import
+ * 不了谁。与其在两个包里各挂一个同名类型让人猜该用哪个，不如这里不占这个名字 ——
+ * 要单独引用级别时写 `Parameters<LogFn>[0]`。
  */
-declare function collectPendingApprovals(defs: readonly ScheduleDefinition[], runs: readonly ScheduleRun[]): SchedulePendingItem[];
+type LogFn = (level: 'debug' | 'info' | 'warn' | 'error', message: string, detail?: object) => void;
+/** 插件上下文（初始化时注入） */
+interface PluginContext {
+    /** 工作目录 */
+    workDir: string;
+    /** 配置数据 */
+    config: Record<string, unknown>;
+    /** 日志函数 */
+    log: LogFn;
+}
+/** 插件定义 */
+interface EpochPlugin {
+    /** 插件唯一标识（对应 npm 包名） */
+    name: string;
+    /** 语义化版本 */
+    version: string;
+    /** 插件描述 */
+    description: string;
+    /** 提供的工具列表 */
+    tools?: EpochTool[];
+    /** 提供的技能（可复用的 prompt 模板） */
+    skills?: EpochSkill[];
+    /** 注册的生命周期钩子 */
+    hooks?: EpochHook[];
+    /** 初始化回调 */
+    onInit?: (ctx: PluginContext) => Promise<void>;
+    /** 清理回调 */
+    onDestroy?: () => Promise<void>;
+}
 
 /**
- * 模型在对话里交上来的一份定时任务**草稿**。
- *
- * `epoch schedule add` 和自动化面板那张表单是两条**人操作**的写入路。这一份是
- * 第三条来路，而它**不是写入路** —— 草稿谁都落不了库，它只是一份摆到人眼前的
- * 提案。真正落库的仍然是那两条：人点「审阅并保存」之后走的是同一个
- * `POST /api/schedules`，人粘贴命令行走的是同一个 `epoch schedule add`。
+ * Hook 契约。
  *
- * ## ⚠️ 三条硬约束都摊在类型上，不靠注释（照 [schedule-templates.ts](./schedule-templates.js) 那三条办）
+ * 参考 Hermes hermes_cli/plugins.py → VALID_HOOKS + invoke_hook
  *
- * | 要守住的                       | 落在类型的哪一格                                                     |
- * | ------------------------------ | -------------------------------------------------------------------- |
- * | 模型不许把任务放到「跳过全部检查」 | {@link ScheduleDraftPermission} 的取值里**没有** `bypass`            |
- * | 填进表单后**必须让用户过一遍**  | 整份形状里**没有** `maxBudgetUsd`，而它是必填 —— 表单因此保存不了     |
- * | 草稿不是写入路                  | 这里只有数据，没有 id 生成、没有 `enabled`、没有 `createdAt`          |
+ * 注意：HookType 之前在 core/src/plugin.ts 和 core/src/hook/types.ts 各有一份，
+ * 且**内容不同**（plugin.ts 那份只有 7 个事件，缺 compress:after / transform:* /
+ * verify:stop）。插件作者按 EpochHook 写代码时拿到的是窄的那份，注册进
+ * HookManager 却是宽的那份。这里合并成唯一一份。
+ */
+
+type HookType = 'session:start' | 'session:end' | 'turn:before' | 'turn:after' | 'tool:before' | 'tool:after' | 'stop' | 'compress:after' | 'transform:tool:output' | 'transform:response' | 'transform:user:input' | 'verify:stop';
+interface HookEvent {
+    type: HookType;
+    sessionId: string;
+    timestamp: number;
+    turnIndex?: number;
+    userMessage?: string;
+    response?: string;
+    /**
+     * 这一轮的用量。**provider 没上报时整个字段缺席**，不是一个填了 0 的对象 ——
+     * 插件据此能区分「这轮没花钱」和「这轮花了多少不知道」（方案 42 PR-0）。
+     */
+    usage?: TokenUsage;
+    toolName?: string;
+    toolArgs?: Record<string, unknown>;
+    toolResult?: {
+        success: boolean;
+        output: string;
+        error?: {
+            code: number;
+            message: string;
+        };
+    };
+    rawOutput?: string;
+    rawInput?: string;
+    reason?: string;
+    messageCount?: number;
+    totalTokens?: number;
+    prunedCount?: number;
+    summaryTokens?: number;
+    turns?: Array<{
+        index: number;
+        llmResponse: string | null;
+    }>;
+    data?: Record<string, unknown>;
+}
+interface HookContext {
+    workDir: string;
+    log: (level: 'debug' | 'info' | 'warn' | 'error', message: string) => void;
+}
+type HookHandler<T = void> = (event: HookEvent, ctx: HookContext) => Promise<T>;
+interface HookRegistration {
+    type: HookType;
+    handler: HookHandler<unknown>;
+    priority: number;
+    plugin: string;
+}
+interface VerifyResult {
+    action: 'stop' | 'continue';
+    message?: string;
+}
+/** Hook 管理器接口（实现在 core） */
+interface HookManager {
+    /**
+     * 宿主注入的诊断出口，同时也是 `HookContext.log` 的来源。
+     *
+     * 挂在管理器上而不是让 `AgentLoop` 另外收一个 logger：那样宿主要接两次，
+     * 接漏一处就是「hook 系统自己的告警有人收、插件在 hook 里说的话没人收」。
+     * 可选是给别的实现留的余地，缺省时 `HookContext.log` 退化成静默。
+     */
+    readonly log?: LogFn;
+    register(reg: HookRegistration): void;
+    trigger(type: HookType, event: HookEvent, ctx: HookContext): Promise<void>;
+    triggerTransform<T>(type: HookType, event: HookEvent, ctx: HookContext): Promise<T | null>;
+    triggerVerify(type: HookType, event: HookEvent, ctx: HookContext): Promise<VerifyResult[]>;
+    /** 从 EpochConfig.hooks 加载 command hooks */
+    loadFromConfig(rawHooks: Record<string, unknown> | undefined): void;
+    /** 触发 command hooks（用于 tool:before 等可阻止的事件） */
+    triggerCommandHooks(type: HookType, event: HookEvent, workDir: string): Promise<{
+        blocked: boolean;
+        reason?: string;
+    } | null>;
+    hasHook(type: HookType): boolean;
+    unregister(type: HookType, handler: HookHandler<unknown>): void;
+    count(type: HookType): number;
+}
+
+/**
+ * 定时任务契约（方案 45）。
  *
- * 第二条是三条里最要紧的，而它和模板那一条**是同一条**：预算必填、没有默认值
- * （方案 45 §3.5），于是一份草稿填进表单之后那个保存按钮**天然是灰的**，
- * 用户不看完那一屏就出不去。写成「草稿里预填 0.50 + 一句『请检查』」的话，
- * 「必须过一遍」就退化成一句没人读的话 —— 而这一格错了的后果很具体：
- * 一觉醒来 40 美元。
+ * 这一份只装**形状**：触发器怎么表达、一条任务有哪些字段、一次运行留下什么。
+ * 注册进操作系统、抢锁、跑一次，全在 `core/src/schedule/` 和 `runtime` 里。
  *
- * ## 为什么住在 protocol
+ * ## 为什么触发器是判别联合，而存储是一段 JSON
  *
- * 和 `SCHEDULE_TEMPLATES` 同一个理由，而且更硬一档：这一份的**两端都要读它** ——
- * core 那侧要解析模型发来的入参（`tools/builtin/schedule-draft.ts`），
- * `packages/web` 那侧要从那次工具调用的入参里把它读回来渲染成一张卡片
- * （`thread/rows.ts`，照 `todo` 的先例）。web 只依赖 protocol + view，够不着 core。
+ * 三档的字段完全不同（每周要 `weekdays`、按间隔要 `everyMinutes`、单次还要个
+ * 日期），拆成列会得到一张一半是 NULL 的表。所以库里 `trigger_spec` 是一段
+ * JSON —— 但**类型是这个联合**，JSON 只是它的存储形式。反过来（先有列再拼
+ * 类型）的代价是「每周三个字段里只填了两个」这种状态在类型上说得出口。
  *
- * ## ⚠️ 这里一个中文字都没有
+ * ## 为什么没有完整 cron 表达式
  *
- * 判据同 schedule-templates.ts 最后一节：措辞在 `locales/*.yaml` 的
- * `web.ui.thread.draft_*` 底下（卡片）和 core 的工具输出里（给模型看的那半，
- * 按 `locales/zh.yaml` 的范围说明不进 catalog）。
+ * 这三档正好是 Windows 任务计划（`schtasks`）与 macOS launchd 的**公共**能力，
+ * 而 5 字段 cron 不是。写全 cron 等于把「时区 + 夏令时 + 闰日」搬回我们自己的
+ * 代码里算下一次触发时刻 —— 而把触发交给操作系统的全部意义就是不碰它们。
+ * 判据一句话：**一个语义在两个平台上不能逐字一致，就不做这个语义。**
  */
 
+/** 三档频率。和 WorkBuddy 的分档逐字一致，理由见文件头 */
+type ScheduleTriggerKind = 'cron' | 'interval' | 'once';
+/** 星期。`0` = 周日 … `6` = 周六，与 `Date.prototype.getDay()` 同口径 */
+type ScheduleWeekday = 0 | 1 | 2 | 3 | 4 | 5 | 6;
 /**
- * 那个工具的名字。**真源在这儿而不是 core**，因为读它的有两个包：
- * core 注册工具时用它，web 从工具流里认出那次调用时用它
- * （`thread/rows.ts`）。
+ * 「周期」档的三种周期。
  *
- * ⚠️ 这一点上它和隔壁 `TODO_TOOL` 的做法不一样：那个名字今天在
- * `web/src/thread/rows.ts` 里另写了一份字面量（那时 protocol 里没有落脚点）。
- * 别照那个抄 —— 两份字面量漂了的表现是「卡片再也不渲染了」，而 typecheck
- * 一声不响。
+ * 和 `ScheduleTriggerKind` 不是一回事：那个分的是三档，这个只细分 `cron` 那一档。
  */
-declare const SCHEDULE_DRAFT_TOOL = "schedule_draft";
+type ScheduleCycle = 'daily' | 'weekly' | 'monthly';
 /**
- * 草稿能落在哪几档权限上 —— **`bypass` 不在里面**。
- *
- * 不是「运行期会拒绝」，是那一档在类型上根本不存在（判据同
- * `ScheduleTemplate.permission`）。理由比模板那一侧更直接：`bypass` 要一次
- * 二次确认（`bypass-not-confirmed`），而那次确认的**对象是人**；让模型提议
- * 一个「等着人去勾确认框」的档位，等于把那道确认变成一道例行手续。
+ * 触发器。
  *
- * 用户自己想要那一档时照旧走表单 —— 那条路一个字都没改。
+ * 所有带时刻的档共用 `at: 'HH:mm'`（24 小时制，**本机时区**）—— 统一成一个字段名
+ * 是为了让「几点跑」在三档之间读起来是同一件事；单次那一档另加 `date`。
  */
-type ScheduleDraftPermission = Exclude<PermissionLevel, 'bypass'>;
-/** 草稿里那份清单。三个字段各自**可选**：没提到的一格 = 「这一格我没意见」 */
-interface ScheduleDraftAllowlist {
-    allowTools?: readonly string[];
-    allowOperations?: readonly OperationType[];
-    allowRules?: readonly string[];
+type ScheduleTrigger = {
+    kind: 'cron';
+    cycle: 'daily';
+    at: string;
+} | {
+    kind: 'cron';
+    cycle: 'weekly';
+    at: string;
+    weekdays: readonly ScheduleWeekday[];
 }
-/** 起草一条新任务 */
-interface ScheduleDraftCreate extends ScheduleDraftAllowlist {
-    action: 'create';
-    name: string;
-    prompt: string;
-    trigger: ScheduleTrigger;
-    /** 工作目录。不给就是引擎那份缺省（`~/.epoch/automation/<id>/`） */
-    workDir?: string;
-    permission: ScheduleDraftPermission;
-    /**
-     * 为什么建议这一条，一句话。**给人看的**，会印在卡片上。
-     *
-     * 必填，而这是刻意的：一条凭空出现在对话里的定时任务，用户第一个问题
-     * 一定是「你为什么觉得我需要它」。答不上来的提案不该提。
-     */
-    note: string;
+/** `days` 是几号（1–31）。31 号在小月不触发，两个平台的原生行为一致 */
+ | {
+    kind: 'cron';
+    cycle: 'monthly';
+    at: string;
+    days: readonly number[];
+} | {
+    kind: 'interval';
+    everyMinutes: number;
 }
+/** `date` 是 `YYYY-MM-DD` */
+ | {
+    kind: 'once';
+    date: string;
+    at: string;
+};
 /**
- * 提议改一条**已有**的任务。
- *
- * 每一格都可选（`undefined` = 这一格不动），但至少要动一格 —— 一份什么都不改的
- * 提案是在浪费用户的一次点击。这条判定在 core 那侧
- * （`schedule/draft.ts` 的 `draft-update-empty`）。
+ * 「按间隔」档的**全部**合法取值（分钟）。
  *
- * ## ⚠️ 「放宽」和别的改动在类型上长得一样，所以判定必须在别处
+ * 收紧成「60 的约数」和「整小时数」不是洁癖，是 launchd 的硬约束：那一侧只能用
+ * `StartCalendarInterval`（列举时刻），不能用 `StartInterval`（睡眠时那一次会被
+ * 丢掉，10.11 起文档明写）。60 除不尽 7 时，「每 7 分钟」列举出来的那 9 个时刻
+ * 在每小时边界上会漂 —— 于是 Windows 上准、macOS 上漂，而那种平台差异是 bug 的温床。
  *
- * 把超时从 10 分钟调到 30 分钟，和往清单里加一条 `terminal(rm:*)`，在这个形状里
- * 是同一种东西：几个可选字段。而后者是**提权**。所以两个宿主都必须自己把
- * 「这次提案放宽了什么」单独标出来（web 的卡片、core 的工具输出），
- * 不许把它混在一列改动里 —— 用户扫一眼就点保存的那一下，正是这条要防的。
+ * 界面上因此是个下拉而不是数字输入框：下拉能表达「只有这些值」，
+ * 输入框会让人填 7 然后得到一个漂的任务。
  */
-interface ScheduleDraftUpdate extends ScheduleDraftAllowlist {
-    action: 'update';
-    /** 改哪一条。模型得先用 `action: 'list'` 看见 id，界面上那串它猜不出来 */
-    id: string;
-    name?: string;
-    prompt?: string;
-    trigger?: ScheduleTrigger;
-    workDir?: string;
-    permission?: ScheduleDraftPermission;
-    enabled?: boolean;
-    maxTurns?: number;
-    timeoutMs?: number;
-    /** 同 {@link ScheduleDraftCreate.note}，必填 */
-    note: string;
-}
-type ScheduleDraft = ScheduleDraftCreate | ScheduleDraftUpdate;
+declare const SCHEDULE_INTERVAL_MINUTES: readonly number[];
 /**
- * 一次提案里「放宽了什么」的分类。
- *
- * 只有三类，而三类都是**授权面变大**的方向：档位往松走、清单多了条目、
- * 从停用变成启用。别往里加「超时变长」这种 —— 它花的是钱和时间，不是权限，
- * 而把两种东西混进同一枚警示标，那枚标就不再有信息量。
+ * 一次运行的结局。
  *
- * 判定在 core（`schedule/draft.ts` 的 `draftWidening`），渲染在 web
- * （`thread/schedule-draft.tsx`）—— 两侧各算一遍是刻意的，判据同
- * `web/src/thread/rows.ts` 文件头那条：web 读的是**模型发出的原始入参**，
- * 而不是 core 归一化之后的结论。
+ * 后三个是「没跑」而不是「跑失败了」，它们必须和 `failed` 分开 ——
+ * 界面上把「上一次因为上一次还在跑所以跳过了」显示成红叉，用户会去查一个不存在的故障。
  */
-type ScheduleWideningKind = 'permission' | 'allowlist' | 'enabled';
-
+type ScheduleRunStatus = 'ok' | 'failed' | 'denied' | 'timeout' | 'budget' | 'skipped-overlap' | 'skipped-window' | 'missed';
+/** 合法结局全集。存进库之前用它收窄，别让一个拼错的状态混进 `last_status` */
+declare const SCHEDULE_RUN_STATUSES: readonly ScheduleRunStatus[];
 /**
- * 工作区信任契约。
- *
- * 为什么需要：clone 一个仓库就等于让它的 `AGENTS.md` 进 system prompt、
- * 它的 hook 配置被执行、它的 policy 覆盖本地权限判定。这是漏洞，不是缺功能。
- * 信任判定把「加载项目级配置」这件事收到一次显式用户决策后面。
- *
- * 竞品：Codex `codex-rs/tui/src/onboarding/trust_directory.rs`；
- * Gemini CLI `packages/cli/src/config/trustedFolders.ts` + `packages/core/src/utils/trust.ts`。
- * 两家都只是读过的参照物：契约形状跟它们都不一样（上游是 TRUST_FOLDER / TRUST_PARENT /
- * DO_NOT_TRUST 三枚举 + 靠 TRUST_PARENT 取 dirname 来编码作用域，这里是三态字面量 +
- * 独立的 scope 字段 + decidedAt）。本文件是独立实现，不带 SPDX 头。
- * 判定证据见 docs/verify/VERIFY_RECORD-D-license-attribution.md
+ * 任务注册在哪儿。
  *
- * 这里只有类型，实现在 core —— 注意实现那边（`core/src/trust/manager.ts`）**是**
- * gemini 的衍生作品（搬了「归一成生效目录再取最长匹配」那条算法），带头、在 NOTICE 里。
- * 契约与实现的授权状态不同是对的，不是漏登记。
+ * - `schtasks` / `launchd` —— 真的注册进了操作系统的调度器，**epoch 不用开着**
+ * - `host` —— **一行都没注册进 OS**（方案 45 §2.6 的路 B）。到点了唤起它的只能是
+ *   宿主自己（`setInterval` 调 `fire()`）—— 而宿主有没有真的这么做，**这一格答不出来**，
+ *   它唯一承诺的事实就是「没进 OS」。所以界面上不许把它写成「已启用」，
+ *   也**不许许诺「开着就会跑」**（判据全文在 locales 的 `notice_host` 上）
  */
-/** 一个目录的信任状态 */
-type TrustLevel = 
-/** 用户明确信任：加载项目指令 / hook / policy */
-'trusted'
-/** 用户明确拒绝：只当普通工作目录，不加载任何项目级配置 */
- | 'untrusted'
-/** 还没问过 */
- | 'unknown';
-/** 用户已经做过决策的信任状态（排除「还没问过」） */
-type DecidedTrustLevel = Exclude<TrustLevel, 'unknown'>;
-/** 信任决策的作用域 */
-type TrustScope = 
-/** 只这个目录 */
-'directory'
-/** 这个目录及其所有子目录 */
- | 'directory-tree';
+type ScheduleBackendKind = 'schtasks' | 'launchd' | 'host';
 /**
- * 一次授信授到哪一档（2026-09-11）。**两档是相加的：`exec` 蕴含 `read`。**
- *
- * ## 为什么拆
+ * 无人值守清单 —— 「要确认，但没人在，怎么办」。
  *
- * 在它之前 `trusted` 是一个布尔，而那一个布尔后面挂着七样东西 —— 其中
- * `.epoch/hooks.json` 和 `.claude/settings.json` 的每一项都是一条要 spawn 子进程的
- * 命令（判据在 [core/hook/sources.ts](../../core/src/hook/sources.ts) 的文件头）。
- * 而用户被问到的那句话逐字是「本目录的项目指令会加载」（`trust_prompt.granted`），
- * **从来没提过 hook**。也就是说「往上下文里注入一段文本」和「在这台机器上执行
- * 任意命令」共用了同一次点击，而问话只描述了前者。这不是 UX 问题，是知情同意错位。
+ * 和权限档（`ScheduleDefinition.permission`）**各管一条轴**：档位回答「这个操作
+ * 要不要人确认」，这份清单回答「要确认但没人在时，哪几条可以不问」。
+ * 它不是「更宽的一档」，是把「要问人」逐条变成「这一条可以不问」。
  *
- * | 档  | 放开什么                                                        | 风险       |
- * | --- | --------------------------------------------------------------- | ---------- |
- * | `read` | 指令文件 / 技能 / 角色 / 命令                                  | 注入上下文 |
- * | `exec` | `hooks.json` / `.claude/settings*.json` / `policies/` / settings 的 allow 那一半 | 执行、放宽判定 |
+ * 三个字段由粗到细，同时命中任一条即放行：
+ * `allowTools` 整个工具 / `allowOperations` 五类操作 / `allowRules` 规则字符串
+ * （`terminal(git status)`、`mcp__github__*`、`file_write(./reports/**)`）。
+ */
+interface ScheduleAllowlist {
+    allowTools: readonly string[];
+    allowOperations: readonly OperationType[];
+    allowRules: readonly string[];
+}
+/**
+ * 一条欠条 —— 「本该问人，但没人可问」。
  *
- * ## ⚠️ 两条边界，别把它当别的东西
+ * ⚠️ **只收这一类**。权限档自己判出的拒绝（选了「只读」档然后去写文件）
+ * **不进欠条** —— 那是档位的判定结果，不是缺授权；把它记成欠条等于建议用户
+ * 去加一条永远不会被查到的规则（第 2 层判 deny 时压根走不到第 3 层）。
+ */
+interface SchedulePendingApproval {
+    toolName: string;
+    type: OperationType;
+    target: string;
+    /** 权限层给的原因，原样带着 —— 人回来时最想看的就是这句 */
+    reason: string;
+    /**
+     * 该往清单里加哪条规则（`rule-suggest` 算的精确规则）。
+     *
+     * 算不出来时**整个不带这个键**：硬编一条 `terminal()` 出来只会让用户
+     * 加进去一个死规则。
+     */
+    suggestedRule?: string;
+    at: number;
+}
+/**
+ * 一条定时任务。
  *
- * 1. **`exec` 不是权限档。** 它放开的是「这个仓库自带的 hook / policy 算不算数」，
- *    不是「这次操作要不要问用户」——[两套机制照旧正交](../../core/src/trust/gate.ts)。
- *    未授 `exec` 的目录里 agent 照样能跑 bash，只是仓库里那份 `hooks.json` 不生效；
- * 2. **`read` 不是「安全档」。** 一份 `AGENTS.md` 能指挥 agent 去做任何它有权限做的
- *    事，包括执行命令。拆开不是因为 `read` 无害，是因为**两者的问话不该合并成一次**。
+ * 时间一律是 **epoch 毫秒**而不是 `Date`：这个形状要过 JSON（存库、将来上 SSE），
+ * `Date` 一过 JSON 就变成字符串，于是同一个字段在两处是两种类型。
  */
-type TrustTier = 'read' | 'exec';
-interface TrustRecord {
-    /** 绝对路径（已 resolve） */
-    path: string;
-    level: DecidedTrustLevel;
+interface ScheduleDefinition {
+    id: string;
+    name: string;
     /**
-     * 这条决策管到哪儿。
-     *
-     * `check()` 会把它折叠进 `TrustLevel`，所以判定方用不上；但**列出记录**的一方
-     * （`epoch trust` 要显示「仅此目录 / 含子目录」）必须能看见 —— 少了它，
-     * `list()` 返回的就不是一条完整的决策，而是一条读不懂的决策。
+     * 停用不等于删除。停用的任务在系统的任务计划里**仍然看得见，只是停着** ——
+     * 删掉再建的话，用户在任务计划程序里看到条目消失会以为我们把他的任务弄丢了。
      */
-    scope: TrustScope;
-    /** 记录时间戳（ms） */
-    decidedAt: number;
+    enabled: boolean;
+    createdAt: number;
+    updatedAt: number;
+    prompt: string;
     /**
-     * 执行类也授了吗（{@link TrustTier}）。`level: 'untrusted'` 时无意义。
-     *
-     * ⚠️ **缺省（`undefined`）= 没授**，而这一格正是存量记录的迁移：拆档之前写下的
-     * 记录没有这一格，于是升级之后它们**只剩读类** —— 判据就是上面那张表下面那段：
-     * 那些记录是在一句只说了「项目指令会加载」的问话下拿到的，把它们追认成执行类
-     * 等于替用户补签一份他没看过的同意书。代价（老用户的项目 hook 会停）由
-     * `trust_gate.exec_migrated` 那条诊断明说，不静默。
+     * 工作目录。**执行器不许继承 cwd** —— OS 调度器起进程时的 cwd 不由我们决定
+     * （Windows 上是 `%SystemRoot%\System32`）。用户没填时落在
+     * `~/.epoch/automation/<id>/`，那是一个确定的目录，不是「随便哪儿」。
      */
-    exec?: boolean;
+    workDir: string;
+    model?: string;
     /**
-     * 授 `exec` 那一刻，执行类输入文件的内容指纹（见 core 的 `trust/exec-hash.ts`）。
-     *
-     * 对不上 = 那些文件在授信之后被改过 → `exec` 退回未授，重新问一次。
-     * `exec` 为假时这一格不该存在。
-     *
-     * ## ⚠️ 这是对 [manager.ts](../../core/src/trust/manager.ts) 文件头「两条明确不做」
-     * 第 2 条的一次**窄口推翻**，不是把它作废
+     * 「召唤专家」。**今天永远不带 —— 但已经不是被别人挡着了。**
      *
-     * 那一条 2026-08-08 写着：记内容 hash「代价是『改一行 AGENTS.md 就被打断一次』，
-     * 这个打断比它挡住的风险更贵」。**那个结论在读类上照旧成立，一个字不改** ——
-     * 指令文件天天在动，为它记 hash 会把授信变成一件每天都要重做的事。
+     * 立案时写的是「等方案 42 PR-1 把顶层会话的角色接线」，而那一笔
+     * **2026-08-15 就结清了**（`SessionFactory.create({ role })` +
+     * `WireCreateSessionRequest.role`，见 [agent-role.ts](./agent-role.ts) 文件头）。
+     * 挡着这一格的只剩「没人做」：`add` / 表单 / 端点三条写入路都不写它。
+     * ⚠️ **别把「被别人挡着」和「没人做」读成一件事** —— 逐条状态在
+     * [验收记录 9.2](../../../docs/verify/VERIFY_RECORD-45-automation.md)。
+     */
+    role?: string;
+    /** 同 {@link role}：方案 44 的清单契约早就到齐了，缺的是写入点。今天永远不带 */
+    skills?: readonly string[];
+    /**
+     * 同 {@link role}，缺的是写入点。
+     * 连接器的免确认另有一条现成的路：`allowRules` 里的 `mcp__<server>__*`。
+     */
+    mcpServers?: readonly string[];
+    /**
+     * 权限档 —— **和对话里那枚胶囊同一套取值、同一套词**。
      *
-     * 翻的只有执行类那一半，因为它的两项输入都变了：
+     * 界面只暴露四档（`plan` / `default` / `acceptEdits` / `bypass`）。
+     * 不为定时任务发明新词：用户在对话里已经学过这四个词一次，
+     * 再教一套等于让他学两遍同一件事的两种说法。
+     */
+    permission: PermissionLevel;
+    allowTools: readonly string[];
+    allowOperations: readonly OperationType[];
+    allowRules: readonly string[];
+    /** 无人看着的一轮不该比有人看着的更长（交互缺省是 50） */
+    maxTurns: number;
+    /**
+     * **必填，没有默认值。** 这是整个方案唯一一处刻意增加摩擦的地方：
+     * 一个假默认会让「一觉醒来 40 美元」变成我们的错。
+     */
+    maxBudgetUsd: number;
+    /**
+     * 墙钟超时。前两把尺子拦不住「一条 `terminal` 命令挂住了」——
+     * 那种情况轮次和花费都不增长，这把尺子是唯一能拦它的。
+     */
+    timeoutMs: number;
+    trigger: ScheduleTrigger;
+    /**
+     * 生效区间（`YYYY-MM-DD`，含首尾），留空表示始终生效。
      *
-     * | | 读类（AGENTS.md）      | 执行类（hooks.json / policies） |
-     * | --- | ---------------------- | -------------------------------- |
-     * | 改动频率 | 每天              | 几乎不动                          |
-     * | 改动后果 | 多一段文本        | **多一条会跑的命令**              |
+     * ⚠️ **两个平台在这个字段上语义不同**：Windows 有原生的 `/SD` `/ED`，过了截止日
+     * 系统压根不会调我们；launchd 没有这个概念，所以 macOS 上我们会被调起来、
+     * 然后由执行器自己判出区间外并退 0。
+     */
+    startDate?: string;
+    endDate?: string;
+    osBackend: ScheduleBackendKind;
+    /** 注册进 OS 时用的标识（Windows 的 `epoch\<id>` / launchd 的 `Label`） */
+    osTaskId: string;
+    /** 没注册进 OS 时不带（`osBackend: 'host'`，或者注册失败） */
+    osRegisteredAt?: number;
+    /**
+     * **真正注册进去的那条 argv**，逐字。`doctor` 靠它比对 OS 侧有没有漂。
      *
-     * 也就是说，同一个做法在这一侧的打断成本低一个量级、挡住的东西贵一个量级。
-     * 参照物：codex 对 hook 记 `trusted_hash`（`codex-rs/config/src/hook_config.rs`），
-     * 而它的 `AGENTS.md` 压根不过闸门 —— 同一条判据的两侧，它也是这么分的。
+     * 存下来而不是每次现算：现算的结果依赖**此刻**的 `process.execPath` 和入口路径，
+     * 而漂移检查要问的恰恰是「当初写进去的是什么」。
      */
-    execHash?: string;
+    osCommand: readonly string[];
+    lastRunAt?: number;
+    lastStatus?: ScheduleRunStatus;
 }
-/** {@link TrustManager.record} 的可选档位。不给 = 只授读类 */
-interface TrustGrant {
-    /** 连执行类一起授。**调用方必须真的为这一档单独问过用户** */
-    exec?: boolean;
-    /** 授 `exec` 时一并记下的内容指纹 */
-    execHash?: string;
+/** 一次运行的记录 */
+interface ScheduleRun {
+    id: string;
+    scheduleId: string;
+    /** 真的起了会话才有；三种 `skipped-*` / `missed` 都没有 */
+    sessionId?: string;
+    startedAt: number;
+    endedAt?: number;
+    status: ScheduleRunStatus;
+    exitCode?: number;
+    reason?: string;
+    costUsd: number;
+    tokens?: TokenUsage;
+    turns: number;
+    /** 欠条。空数组 = 这一轮没撞上需要确认的操作 */
+    pendingApprovals: readonly SchedulePendingApproval[];
+    /** 录像（`<runId>.ndjson`）的绝对路径；没起会话时不带 */
+    logPath?: string;
+    /**
+     * `epoch schedule run` 手动跑的那一次。
+     *
+     * 标出来是因为它**不该影响「上一次到点跑成没有」的判断** ——
+     * 用户手点一次成功，不等于明天 9 点那次会成功。
+     */
+    manual: boolean;
 }
 /**
- * {@link TrustManager.checkExec} 的答案 —— **记录里写的，不含新鲜度校验**。
+ * 宿主注入的「怎么以无界面方式唤起我自己」（方案 45 §2.6）。
  *
- * 两格一起交出来是因为校验方（`core/src/trust/gate.ts`）需要拿 {@link hash} 去和
- * 现算的值比；拆成两次调用的话，两次之间可能命中**不同的记录**
- * （`bestRecord()` 是按最长匹配现算的），于是拿 A 记录的授信配上 B 记录的指纹。
+ * 把引擎 `import` 进 Electron / VS Code 扩展的宿主**没有 `epoch` 可执行文件**，
+ * 而**库自己分辨不出宿主打算怎么被唤起** —— 所以这件事必须由宿主说。
+ *
+ * ⚠️ **绝对不许拿 `process.execPath` + `argv[1]` 去猜。** 在 Electron 里那两个值
+ * 是「Electron 的 exe」+「宿主的 main.js」，注册进去的后果是**到点了给用户弹出
+ * 整个应用的主窗口**（甚至一天弹 24 次）。那不是「不够好」，是把定时任务变成骚扰。
  */
-interface TrustExecGrant {
-    /** 记录里授过执行类吗 */
-    granted: boolean;
+interface ScheduleRunnerSpec {
     /**
-     * 授的时候记下的内容指纹。
+     * 无界面入口的 argv 前缀，绝对路径。我们在后面追加
+     * `schedule fire <id> --home <dir>`。
      *
-     * ⚠️ **`undefined` = 校验不了，而这一档照旧放行**（判据在 gate 的 `decide()` 上）。
-     * 今天所有写入口都会带上它，所以这一档只可能来自手改 `trust.json`。
-     */
-    hash?: string;
-}
-interface TrustManager {
-    /** 查某个目录的信任状态（含父目录的 directory-tree 继承） */
-    check(dir: string): TrustLevel;
-    /**
-     * 查某个目录的执行类授信（含继承）。**和 {@link check} 是两个问题**：
-     * 这一个只在 `check()` 回 `'trusted'` 时才可能授过，反过来不成立。
+     * 那个入口必须**不建窗口、跑完就退**（Electron 里就是在 `whenReady` 之前
+     * 分叉出去）。
      */
-    checkExec(dir: string): TrustExecGrant;
-    /** 记录一次决策 */
-    record(dir: string, level: DecidedTrustLevel, scope: TrustScope, grant?: TrustGrant): void;
-    list(): readonly TrustRecord[];
-    revoke(dir: string): void;
+    argv: readonly string[];
+    /** 注册进 OS 时给人看的名字前缀。不给就用 `epoch` */
+    label?: string;
 }
 
 /**
- * 会话消息契约。
+ * 内置模板六张（[方案 45](../../../docs/verify/VERIFY_RECORD-45-automation.md) §7.3）。
  *
- * 这是我们**自己的**消息格式，不是 Vercel AI SDK 的 `ModelMessage`。
+ * 判据是「**这件事必须每天/每周做一次，而且做完是一份能读的东西**」——
+ * 所以 WorkBuddy 那 12 张消费级的（儿童睡前故事 / 父母联系提醒 / 萌宠壁纸）
+ * 一张都没抄，换成开发者场景。
  *
- * 为什么要有这么一层：改造前 AgentLoop、message-codec、以及 AgentProvider
- * 这个「依赖倒置接口」全都直接用 `ModelMessage`。后果有三个：
- *   1. 依赖倒置是假的 —— 想塞一个脚本化的假 provider 做测试，得先 import 'ai'
- *   2. AI SDK 的消息形状是**联合类型 + 部件数组**，`content` 可能是 string
- *      也可能是 `Array<{type:'text'|'tool-call'|...}>`，于是 loop 里到处
- *      `as Array<Record<string, unknown>>` 地摸字段
- *   3. SDK 换大版本（v5→v6→v7 每次都动过消息形状）要改的是整个 agent 层，
- *      而不是一个转换函数
+ * ## ⚠️ 三条硬约束都摊在类型上，不靠注释
  *
- * 形状故意和 SQLite 里持久化的 `Message`（core/session/types.ts）对齐 ——
- * 一份扁平 content + 可选的工具部件。两边不一致的话，存盘和回放各自要一套转换。
+ * | §7.3 那句话                     | 落在类型的哪一格                                                     |
+ * | ------------------------------- | -------------------------------------------------------------------- |
+ * | 模板**不联网**                  | 这是一份 `const`，没有取数入口 —— 在线模板市场 42 已定不做           |
+ * | 一律不预设「跳过全部检查」      | {@link ScheduleTemplate.permission} 的取值里**没有** `bypass`         |
+ * | 填进表单后**必须让用户过一遍**  | 整份形状里**没有** `maxBudgetUsd`，而它是必填 —— 表单因此保存不了     |
  *
- * 转成 SDK 格式只发生在一个地方：core/provider/sdk-adapter.ts。
- */
-
-/** 模型请求执行的一次工具调用 */
-interface EpochToolCall {
-    toolCallId: string;
-    toolName: string;
-    /** 模型给出的入参 */
-    input: Record<string, unknown>;
-}
-/** 一次工具执行的结果 */
-interface EpochToolResult {
-    toolCallId: string;
-    toolName: string;
-    /** 输出的文本形式。工具的返回值统一收成字符串，不往下传结构 */
-    output: string;
-    /**
-     * 二进制产物。**只有过完四道闸门、带 `data` 的才会真的进模型上下文**
-     * （见 core/src/context/artifact-gate.ts）；否则这里只有 summary + path，
-     * `output` 里已经含了那句 summary。
-     */
-    artifacts?: ToolArtifact[];
-}
-/** 文本部件 */
-interface EpochTextPart {
-    type: 'text';
-    text: string;
-}
-/**
- * 图片部件。
+ * 最后一条是三条里最要紧的，而它是**结构性**的而不是靠一句提示：预算必填、
+ * 没有默认值（§3.5），于是一张模板卡填进表单之后那个保存按钮**天然是灰的**，
+ * 用户不看完那一屏就出不去。写成「模板里预填 0.50 + 一句『请检查』」的话，
+ * 「必须过一遍」就退化成一句没人读的话。
+ *
+ * ## 为什么住在 protocol，而不是「core 一份 + 这里抄一份」
+ *
+ * 任务书给的两条路是「从 server 端点下发」或者「抄一份到 protocol + 一条逐项相等
+ * 的用例」（照 `WireScheduleIssueCode` 的先例）。**两条都不用，因为这一份和那个
+ * 先例不是同一种东西**：
+ *
+ * - `WireScheduleIssueCode` 的真源在 core**必须**在 core —— 那张码表是
+ *   `validateSchedule()` 的出口集合，它和判定逻辑长在一起，搬不动；
+ * - 而这一份是**纯数据、零判定**：六个触发器、六档权限、六份最小清单。
+ *   它谁都不依赖。而 [AGENTS.md](../../../AGENTS.md) 的分层表里 protocol 那一行
+ *   写着「跨包共享的东西**只能**放这里」。
+ *
+ * 放这儿的直接收益是**不存在第二份**：`packages/web` 够得着它（只依赖
+ * protocol + view）、cli 够得着、server 够得着、假服务端也够得着。抄一份到
+ * protocol 再钉一条「逐项相等」的用例，是在为一个可以不存在的分叉修围栏；
+ * 走一条 server 端点则要为一份**从不改变的常量**加一条 HTTP 往返和一个失败态
+ * （「模板拉不下来」——而它明明就在包里）。
  *
- * `image` 三种形态：裸 base64、`data:` URL、`http(s)` URL。
- * 字段名是 `mediaType` 不是 `mimeType` —— 与 `@ai-sdk/provider-utils` 的
- * `ImagePart` 对齐，省掉边界上的一次改名。
+ * ## ⚠️ 这里一个中文字都没有，措辞在 web 那份 catalog 里
+ *
+ * 名字 / 说明 / **提示词**三样都是文案：提示词要跟着用户的界面语言走
+ * （一个英文界面的用户不该收到一份中文报告），而 protocol 里没有 `t()`、
+ * 也不该有。所以这一份只给 `id`，措辞表在
+ * `web/src/automation/labels.ts` 的 `TEMPLATE_TEXT` 上 —— 那张表
+ * `satisfies Record<ScheduleTemplateId, …>`，**加一张模板而不给它文案会当场编译不过**。
  */
-interface EpochImagePart {
-    type: 'image';
-    image: string;
-    mediaType?: string;
-}
-/** 附件为什么只有路径没有内容 */
-type FileOmitReason = 
-/** 探测到 NUL 字节，是二进制 */
-'binary'
-/** 权限判定没放行（与 `file_read` 同一条判定） */
- | 'denied'
-/** 读不到（不存在 / 没权限 / 是目录） */
- | 'unreadable'
-/** 这一条消息附的文件个数或总量超了上限 */
- | 'over-limit'
+
 /**
- * 会话是 resume 出来的，附件内容**不重读**。
+ * 六张模板的 id。
  *
- * 内容当初是过了权限判定才附上的，而那次判定发生在另一个上下文里
- * （当时的权限级别、当时的信任状态）。恢复时无声地再读一遍磁盘等于让一次
- * 旧的授权在新的上下文里继续生效。模型仍然看得见路径，要内容就自己调
- * `file_read` —— 那条路有完整的审批。
+ * 它同时是**文案表的键**（web 那侧 `satisfies Record<ScheduleTemplateId, …>`），
+ * 所以这个联合就是「有几张模板」的唯一真源 —— 加一张要改的地方由编译器点出来。
  */
- | 'not-restored';
+type ScheduleTemplateId = 'repo-sweep' | 'weekly-digest' | 'dep-checkup' | 'stale-docs' | 'test-flake' | 'todo-digest';
 /**
- * 文件附件部件 —— 用户用 `@路径` 提到的文件（方案 25）。
- *
- * ## 为什么是一种部件，而不是把内容拼进文本里
- *
- * 拼字符串看起来省事，代价有四个，每一个都要在很久以后才暴露：压缩器分不清
- * 「用户打的字」和「附的文件」于是压错东西、token 统计把文件算成用户输入、
- * artifact 化那条路完全绕过、web 宿主收到的 wire 载荷里两者无法区分。
- * 单独一种部件之后，这四件事各自都有地方判。
+ * 一张模板 = 一条任务除了「名字 / 提示词 / 预算」之外的那些格子。
  *
- * ## `text` 缺席是常态，不是异常
+ * 三样刻意缺席，各有各的理由：
  *
- * 二进制、超限、权限没放行时**只留路径**。这时候模型看到的是「用户提到了这个
- * 文件，但内容没给你，原因是 X」—— 它可以自己去调 `file_read`（那条路有完整的
- * 审批流程）。比起静默附上或者静默丢掉，这是唯一不会让人误判的形态。
+ * - `name` / `prompt` —— 是**文案**，见文件头最后一节；
+ * - `maxBudgetUsd` —— 必填且没有默认值（§3.5），见文件头那张表第三行；
+ * - `workDir` —— 模板不知道用户的仓库在哪儿。留空的语义是
+ *   `~/.epoch/automation/<id>/`（`ScheduleDefinition.workDir` 上的判据），
+ *   而**清单里那条 `file_write(./reports/**)` 是相对的**，所以它跟着工作区走 ——
+ *   不管用户填不填，报告都落在那条任务自己的目录下面。
  */
-interface EpochFilePart {
-    type: 'file';
-    /** 用户敲的那个路径（相对工作区，`/` 分隔），原样保留用于显示 */
-    path: string;
-    /** 文件内容。**缺席时看 `omitted`** */
-    text?: string;
-    /** 没给内容的原因；给了 `text` 时不出现 */
-    omitted?: FileOmitReason;
-    /** 内容被截断到多少字节。给了就是截断过 —— 截断**永远不静默** */
-    truncatedTo?: number;
-    /** 文件原始字节数，用于展示 */
-    bytes?: number;
+interface ScheduleTemplate {
+    id: ScheduleTemplateId;
+    trigger: ScheduleTrigger;
+    /**
+     * 权限档。**取值里没有 `bypass`**（§7.3：模板一律不预设「跳过全部检查」），
+     * 也没有 `auto`（界面压根不暴露它，§3.2）。
+     *
+     * 两档各有各的用法，而分界线是 by-level 那张表：
+     *
+     * - `plan`（只读）—— 「读一遍然后写一份报告」的那几张。它天然零授权面，
+     *   清单里只要一条 `file_write`（那条走**第 2 层**规则匹配，所以在只读档下
+     *   照样放行 —— §3.2 那句「只读 + `file_write(<任务目录>/**)`」说的就是它）；
+     * - `default`（按需确认）—— 要跑命令的那几张。**除了 `bypass`，写命令在每一档
+     *   下都要确认**，所以它们只能靠清单逐条放行，而这正是清单存在的理由。
+     */
+    permission: 'plan' | 'default' | 'acceptEdits';
+    /** 整个工具免确认（粗）。多数模板不用它 —— 逐条列出来的清单才审得动 */
+    allowTools?: readonly string[];
+    allowOperations?: readonly OperationType[];
+    /** 规则（细）。⚠️ **路径一律写成相对的**，理由见 {@link ScheduleTemplate} */
+    allowRules?: readonly string[];
+    /**
+     * 墙钟超时（毫秒）。不给就用引擎缺省的 15 分钟。
+     *
+     * 只有「测试 flake 复盘」给了 —— 它真的要跑一遍测试，而缺省那把尺子会在
+     * 半路把它砍掉。**这一格存在的意义就是让那一张不至于生下来就超时**。
+     */
+    timeoutMs?: number;
 }
 /**
- * 引用的会话为什么只有标题没有内容（方案 53 §4.2）。
- *
- * 前五个是**稳定的错误码**，给宿主路由用（headless / 嵌入宿主要能按码分流，
- * TUI 和 Web 要各自渲染）。清单本体是 {@link SESSION_REFERENCE_ERROR_CODES}，
- * 那才是同构位置的唯一真源。
+ * 六张。顺序就是界面上卡片的顺序：**两张每天的排在前面** ——
+ * 「每天一次」比「每周一次」更容易让人第一次就试出效果，而这一屏的空状态
+ * 要答的问题是「这东西能替我做什么」。
  */
-type SessionOmitReason = 
-/** `@:xxx` 匹配不到**唯一**的一段会话（零个，或好几个） */
-'invalid-reference'
-/** 引用的是当前这段会话自己 */
- | 'self-reference'
-/** 超过每条消息能引用的会话个数 */
- | 'too-many'
-/** 会话可读性判定不放行（方案 48 的那一处判定，见 core/session/authorization.ts） */
- | 'not-authorized'
-/** 这一条消息的附件总量已经用完 */
- | 'budget-exceeded'
+declare const SCHEDULE_TEMPLATES: readonly ScheduleTemplate[];
+
 /**
- * 会话是 resume 出来的，引用的内容**不重读**。
+ * 「还欠着的那几张欠条」——
+ * [方案 45](../../../docs/verify/VERIFY_RECORD-45-automation.md) §八 ① / ③ 的素材。
  *
- * 判据逐字同 {@link FileOmitReason} 的 `not-restored`：内容当初是过了可读性
- * 判定才附上的，而那次判定发生在另一个上下文里。恢复时无声地再读一遍等于让
- * 一次旧的授权在新的上下文里继续生效。模型仍然看得见「用户引用过这段会话」，
- * 要内容就自己调 `session_search`（方案 48 那条路，有工具审批）。
+ * 三个界面读的是同一个数：dock 上那一条「自动化待确认」、侧栏「自动化」入口上
+ * 那个点、TUI 启动时那一行。**它们必须是同一个数** —— 三处各数一遍的下场是
+ * 侧栏有点、点进去 dock 上什么都没有。
  *
- * **它不是错误码**，所以不在 {@link SESSION_REFERENCE_ERROR_CODES} 里。
- */
- | 'not-restored';
-/**
- * 五个稳定的错误码（方案 53 §4.2）—— **同构位置的唯一真源**。
+ * ## 一、为什么这份投影住在 protocol
  *
- * 为什么要稳定的码而不是一句话：headless / 嵌入宿主要能路由这些失败
- * （`docs/HEADLESS.md` 的退出码那套已经是这个思路），而且 TUI 和 Web 要各自渲染。
+ * 它是**纯集合运算**：手上有哪几条任务、每条最近跑过什么、清单里已经有哪几条规则。
+ * 没有日期算术、不读盘、不查权限，一个字的 core 知识都不需要。
+ * 而它的消费者有四个：`server`（那条端点）、`cli`（`--fix` 和 TUI 那行开机提示）、
+ * `packages/web/dev` 那台假服务端、以及将来任何一个嵌入宿主。
+ * [AGENTS.md](../../../AGENTS.md) 分层表里 protocol 那一行写着
+ * 「跨包共享的东西**只能**放这里」，这就是那一行说的情况。
  *
- * `not-restored` 刻意不在里面 —— 它是「会话恢复了」这个事实，不是一次失败。
- */
-declare const SESSION_REFERENCE_ERROR_CODES: readonly SessionOmitReason[];
-/**
- * 引用另一段会话的部件 —— 用户用 `@:xxx` 提到的那段会话（方案 53）。
+ * ⚠️ **这一份落地之前，那个集合运算在仓库里有三份**（`server` 的 `fixSchedule`、
+ * `cli` 的 `applyFix`、假服务端的 `fakeScheduleFix`），逐字一样的六行。
+ * 三份都是「往授权清单里加规则」这条路上的判定 —— 也就是**提权路径上的重复实现**。
+ * 收成一份是这个文件存在的第二个理由，比第一个理由更硬。
  *
- * ## 塞进来的是那段会话的「当前面」，不是原始全量（§二）
+ * ## 二、「还欠着」= 算得出规则、而且规则还不在清单里
  *
- * 一个跑了两小时、压缩过三次的会话，`messages` 表里有 800 条，但模型当时能看到
- * 的只有 60 条（其余 `active = 0`）。这里带的是**那 60 条**。三条理由：800 条
- * 任何预算都塞不下；那 60 条就是这段会话的结论（压缩器已经把前面浓缩进去了）；
- * 原始全量里有已经被推翻的内容（「先试了 A 不行改用 B」，压缩之后留下的是 B）。
+ * 两道筛，**缺一道这个数就会自己卡住**：
  *
- * ## 它是**快照**，不是活引用
+ * 1. **`suggestedRule` 必须有值。** 算不出精确规则的那几条（目标为空的操作）
+ *    进不了这份清单 —— dock 上唯一的动作是「加进授权清单」，而对它们那一下
+ *    什么都加不了。一条点了没用的通知比没有通知坏（设计稿决定 20 ①），
+ *    而且它**永远清不掉**：没有任何动作能让它消失。
+ *    ⚠️ 它们并没有被藏起来：「运行记录」那一屏上那一轮照旧列着它们、
+ *    照旧写着「这一条反推不出精确规则」。这里筛掉的是**通知**，不是事实。
+ * 2. **规则还不在 `allowRules` 里。** 用户按过那一下之后规则就进清单了，
+ *    于是这个数**自己减一**。这条让整件事不需要「读标记」那套东西 ——
+ *    没有迁移、没有「哪个界面算看过」这个产品判断、也没有一个只能靠
+ *    「我看过了」来清的角标。
  *
- * 引用是发消息那一刻的快照，之后源会话被归档、删除、继续聊都不影响这一条。
- * **别去做「引用失效」的检测** —— 那等于让一条已经发出去的消息随时间变形。
+ * ## ⚠️ 三、这个数**不含**「上一次没跑成」的那几条，而那是一条判断不是遗漏
  *
- * ## `text` 缺席是常态
+ * `failed` / `timeout` / `budget` 三档同样是「你该知道的事」，但它们**没有下一步
+ * 动作**：屏幕上给不出一个按钮，用户只能去看运行记录。把它们算进来的话，这个点
+ * 会一直亮着，直到那条任务下一次跑成 —— 而在那之前它已经不再指向任何可做的事，
+ * 也就退化成了一个「有东西发生过」的常亮灯。
  *
- * 匹配不到、引用自己、超上限、判定不放行时**只留 `ref` 和原因**。这时候模型
- * 看到的是「用户引用了某段会话，但内容没给你，原因是 X」—— 要内容它可以自己调
- * `session_search`（方案 48）。这保证了 `@:` 永远不会成为一条比 `session_search`
- * **更宽松**的读取通道，和 `@文件` 对 `file_read` 那条判据逐字对应。
+ * 三档失败在「运行记录」那一屏上有自己的三态色（✅ ⚠️ ❌），一条都没藏。
+ * 📮 真要给它们一个计数，前置是一份**读标记**（`schedule` 那个 namespace 加一次
+ * 迁移 + 一条写端点 + 「web 打开那个 tab 算不算看过、TUI 启动算不算」这个产品
+ * 判断）。那是独立的一次改动，不该顺手塞进这一轮。
  */
-interface EpochSessionPart {
-    type: 'session';
-    /** 用户敲的那个引用串（`@:` 后面那一截），原样保留用于显示 */
-    ref: string;
-    /** 匹配到的会话 id。**没匹配上时缺席** */
-    sessionId?: string;
-    /** 那段会话的标题（空标题时是 sessionId，见方案 53 §5.3） */
-    title?: string;
-    /** 那段会话的工作目录，用于让人 / 模型看出「这是哪个项目的会话」 */
-    cwd?: string;
-    /** 当前面的正文。**缺席时看 `omitted`** */
-    text?: string;
-    /** 没给内容的原因；给了 `text` 时不出现 */
-    omitted?: SessionOmitReason;
-    /** 内容被截断到多少字节。给了就是截断过 —— 截断**永远不静默** */
-    truncatedTo?: number;
-    /** 当前面有多少条消息（`active = 1` 的那些） */
-    messageCount?: number;
-    /** 那段会话一共多少条（含被压掉的）。两个数不等就说明它压缩过 */
-    totalMessages?: number;
-}
-type EpochContentPart = EpochTextPart | EpochImagePart | EpochFilePart | EpochSessionPart;
-/** 用户消息内容 —— 纯文本或多模态部件数组 */
-type EpochUserContent = string | EpochContentPart[];
+
 /**
- * 附件在**给模型的**纯文本投影里长什么样。**不吐文件内容** —— 内容走 `parts` 那一路。
+ * 一条**算得出规则**的欠条。
  *
- * 输出**逐字冻住**：门禁在 `packages/protocol/__tests__/message-projection.test.ts`，
- * 它把五种 `omitted` 原因加截断、不截断两支全钉死了。改一个字那份会当场红 ——
- * 那不是「用例过时了」，是你正在改模型的输入契约（判据见 {@link OMIT_LABEL}）。
+ * `suggestedRule` 从可选收成必填 —— 这不是换个写法：它让「dock 上那个按钮
+ * 一定加得进东西」变成一件类型上成立的事，而不是一句要人记住的注释。
  */
-declare function filePartSummary(part: EpochFilePart): string;
+type FixableApproval = SchedulePendingApproval & {
+    suggestedRule: string;
+};
 /**
- * 历史里的图被**摘掉**之后留在原位的那一行（2026-09-12）。
- *
- * ## 它补的是一个静默的口子，不是「又一个占位符」
+ * dock / 侧栏 / TUI 三处共用的一条。
  *
- * 喂模型的历史里图片是 base64 部件（`session-store.loadHistory()` 把
- * `inlineImages` 写死成 true）。而「当前模型认不认图」那道闸门在
- * `core/agent/loop.ts` 上，读的是**这一轮用户新发的图**
- * （`imageParts(input.userMessage)`）—— 也就是说换到一个不认图的模型之后只要
- * 不再发新图，历史里那些图会原样发出去：provider 那侧要么 400、要么**一声不吭
- * 地吞掉**（后者实测存在，判据全文在 `core/provider/capability-probe.ts` 的
- * 文件头）。摘掉它们的是 `AgentLoop`，留下的那一行是这一个。
+ * 带 `scheduleName` 而不是只带 id：这条通知的措辞必须**有宾语**
+ * （「《每日仓库巡检》差一条授权」，不是「有 1 条待确认」）——
+ * 判据和跨会话待办条那一条同源（`web/src/dock/crossbar.tsx` 文件头
+ * 「措辞必须带宾语」那一节）：一个不带宾语的计数器逼用户挨个点开去看。
+ */
+interface SchedulePendingItem {
+    scheduleId: string;
+    scheduleName: string;
+    /** 欠条挂在哪一次运行上。`POST /api/schedules/:id/fix` 收的就是它 */
+    runId: string;
+    /** 那一次运行的开始时刻（epoch 毫秒）。界面上那句「已欠了多久」 */
+    at: number;
+    /** 还没进清单的那几条，**至少一条**（空的那几轮压根不进这份清单） */
+    approvals: readonly FixableApproval[];
+}
+/**
+ * 这一轮的欠条里，有哪几条规则还不在清单里。**去重，顺序照欠条的顺序。**
  *
- * ## 为什么不复用 `contentToText` 那个 `[图片 image/jpeg]`
+ * 三个调用点：这个文件自己（算那个计数）、`POST /api/schedules/:id/fix`
+ * （真往清单里写的那一下）、`epoch schedule run --fix`。
+ * ⚠️ **三处必须是同一个函数**：它决定的是「往授权清单里加哪几条规则」，
+ * 而三份实现走散的方向可能是提权（一边加了另一边没加）。
+ */
+declare function unfixedRules(allowRules: readonly string[], approvals: readonly SchedulePendingApproval[]): string[];
+/**
+ * 手上那几条任务 + 最近那些运行 → 该通知的清单。
  *
- * 那一个是**另一个消费者**的投影（`imagesCarriedAsParts: false`，喂压缩器 /
- * 审计 / `messages.content` 那一列），而且它有前科：图片真的送达之后，它成了
- * 「唯一还在撒谎的地方」（判据在 {@link ContentToTextOptions.imagesCarriedAsParts}）。
- * 这一行要说的是另一件事 —— 图**确实没给它**，以及为什么。
+ * ## ⚠️ 同一条任务只报**最近**那一次，不是每一次
  *
- * 措辞里带上「不支持」这半句，判据同 `agent/prompt.ts` 里那条
- * 「不支持那一档要说清后果，别笼统一句不支持」：只写「图片未附上」的话，
- * 模型会去猜是不是传坏了，然后建议用户重发一次 —— 而重发多少次都一样。
+ * 一条「每天 9 点」的任务每天记同一条欠条，一周就是七条一模一样的通知。
+ * 所以按任务收拢、取最近那一次。这不会漏掉东西：修最近那一次加进去的规则
+ * 通常把老的那几次也一起覆盖了；万一老的那次欠的是**另一条**规则，
+ * 它在下一次取数时自然浮上来成为「最近的那条未解决的」。
  *
- * ⚠️ **不给「你可以自己去读」这类下一步**，和 `OMIT_LABEL` 的 `binary` 那档
- * 不同：那一档有 `file_read` 真的能拿到内容，这一档模型没有任何办法看见像素。
- * 给一个不存在的出口，比不给更糟。
+ * ⚠️ 判的是「最近的**还欠着的**那一次」，不是「最近的那一次」：一条任务昨天
+ * 卡了、今天跑成了，昨天那条欠条**仍然欠着**（清单里那条规则还是没加），
+ * 下一次到点还会再卡一遍。拿「最近一次的状态」当判据会把它静默吞掉。
  *
- * 逐字冻住，理由同 {@link OMIT_LABEL}（进模型 prompt、进 eval 指纹、不进 catalog）。
+ * @param defs 全部任务（`ScheduleControl.list()`）
+ * @param runs 最近那些运行，**最新的在前**（`ScheduleControl.recentRuns()` 的顺序）
  */
-declare function imagePartOmittedSummary(part: EpochImagePart): string;
+declare function collectPendingApprovals(defs: readonly ScheduleDefinition[], runs: readonly ScheduleRun[]): SchedulePendingItem[];
+
 /**
- * 引用的会话在纯文本投影里长什么样。**不吐那段会话的正文** —— 同 `filePartSummary`。
+ * 模型在对话里交上来的一份定时任务**草稿**。
  *
- * ## 这一行刻意是英文 + 码，不是中文散文
+ * `epoch schedule add` 和自动化面板那张表单是两条**人操作**的写入路。这一份是
+ * 第三条来路，而它**不是写入路** —— 草稿谁都落不了库，它只是一份摆到人眼前的
+ * 提案。真正落库的仍然是那两条：人点「审阅并保存」之后走的是同一个
+ * `POST /api/schedules`，人粘贴命令行走的是同一个 `epoch schedule add`。
  *
- * 它的读者有三个，**没有一个是界面**：模型（经 sdk-adapter 进上下文）、
- * `messages.content` 那一列（存盘 / 压缩 / 审计 / FTS）、以及宿主的日志。
- * 界面要展示这一部件时读的是结构化字段（`omitted` / `title` / `messageCount`），
- * 自己组措辞 —— TUI 那一侧的中文在宿主用 `t()` 拼，见 locales 的 `mention.*`。
+ * ## ⚠️ 三条硬约束都摊在类型上，不靠注释（照 [schedule-templates.ts](./schedule-templates.js) 那三条办）
  *
- * > ⚠️ 「没有一个是界面」这句话 2026-08-24 之前**有个洞**：`contentToText()`
- * > 会把这一行塞进 tui / web 的气泡里，于是它事实上也是界面的。洞补在
- * > §34.4 —— 界面改走 `contentToDisplayText()`，那一份把这一行换成
- * > catalog 的 `message_part.session*`。所以上面那句话现在是真的了。
+ * | 要守住的                       | 落在类型的哪一格                                                     |
+ * | ------------------------------ | -------------------------------------------------------------------- |
+ * | 模型不许把任务放到「跳过全部检查」 | {@link ScheduleDraftPermission} 的取值里**没有** `bypass`            |
+ * | 填进表单后**必须让用户过一遍**  | 整份形状里**没有** `maxBudgetUsd`，而它是必填 —— 表单因此保存不了     |
+ * | 草稿不是写入路                  | 这里只有数据，没有 id 生成、没有 `enabled`、没有 `createdAt`          |
  *
- * 所以这里直接把**那五个稳定错误码**原样写进去（§4.2）：宿主能 grep，模型能读，
- * 而且它不必跟着界面语言变 —— 一条落库的记录跟着 `EPOCH_LANG` 变语言，
- * 等于把同一段会话的历史劈成两半（`goal/wording.ts` 那条豁免记的是同一个坑）。
+ * 第二条是三条里最要紧的，而它和模板那一条**是同一条**：预算必填、没有默认值
+ * （方案 45 §3.5），于是一份草稿填进表单之后那个保存按钮**天然是灰的**，
+ * 用户不看完那一屏就出不去。写成「草稿里预填 0.50 + 一句『请检查』」的话，
+ * 「必须过一遍」就退化成一句没人读的话 —— 而这一格错了的后果很具体：
+ * 一觉醒来 40 美元。
  *
- * 显示名用标题而不是 sessionId：后者是一串随机字符，对人和模型都没有信息量。
- * 标题为空的会话在解析那一侧已经用 sessionId 兜过底了（方案 53 §5.3）。
- */
-declare function sessionPartSummary(part: EpochSessionPart): string;
-/**
- * 取部件数组的纯文本投影：图片折成一句占位，绝不吐 base64；
- * 文件和引用的会话同样只折成一行占位，**不吐内容**。
+ * ## 为什么住在 protocol
  *
- * 投影是**存盘、压缩、审计**看的那一份。把几十 KB 的文件内容塞进来，
- * `sessions.db` 会跟着一起胖，而回放时那份内容本来就能从 `parts` 里拿。
+ * 和 `SCHEDULE_TEMPLATES` 同一个理由，而且更硬一档：这一份的**两端都要读它** ——
+ * core 那侧要解析模型发来的入参（`tools/builtin/schedule-draft.ts`），
+ * `packages/web` 那侧要从那次工具调用的入参里把它读回来渲染成一张卡片
+ * （`thread/rows.ts`，照 `todo` 的先例）。web 只依赖 protocol + view，够不着 core。
  *
- * ## ⚠️ 这一份**只给模型和落库**，界面不许用它（RECORD-40-i18n §34.4）
+ * ## ⚠️ 这里一个中文字都没有
  *
- * 改造前它一个人喂三类消费者，于是把界面切成 English 的人会在**自己那条消息的
- * 气泡里**看到 `[图片 image/png]` / `[文件 …：二进制文件，未附内容]`。
- * 这笔债在 §34.4 记了、§34.4 还掉，处置是**分家**：
+ * 判据同 schedule-templates.ts 最后一节：措辞在 `locales/*.yaml` 的
+ * `web.ui.thread.draft_*` 底下（卡片）和 core 的工具输出里（给模型看的那半，
+ * 按 `locales/zh.yaml` 的范围说明不进 catalog）。
+ */
+
+/**
+ * 那个工具的名字。**真源在这儿而不是 core**，因为读它的有两个包：
+ * core 注册工具时用它，web 从工具流里认出那次调用时用它
+ * （`thread/rows.ts`）。
  *
- * | 谁要 | 用哪一份 | 为什么 |
- * | ---- | -------- | ------ |
- * | 模型（`sdk-adapter.ts` / `agent/loop.ts` / `runtime/agent-session.ts`） | **这一个** | 模型输入契约 + eval 指纹，跟着 locale 变就漂（§33.2） |
- * | ↳ 其中 `agent/loop.ts` 拼**给模型的文本部件**那一次 | 这一个 + `{ imagesCarriedAsParts: true }` | 图片另有真部件带着，占位符会变成一句假话（判据见 {@link ContentToTextOptions}） |
- * | `messages.content` 那一列（存盘 / 压缩 / 审计 / FTS） | **这一个** | 一条落库的记录跟着 `EPOCH_LANGUAGE` 变语言，等于把同一段会话的历史劈成两半 |
- * | 界面（tui 的历史项、web 的气泡） | `contentToDisplayText(content, t)` | 那一份走 catalog 的 `message_part.*`，住在两个宿主里 |
+ * ⚠️ 这一点上它和隔壁 `TODO_TOOL` 的做法不一样：那个名字今天在
+ * `web/src/thread/rows.ts` 里另写了一份字面量（那时 protocol 里没有落脚点）。
+ * 别照那个抄 —— 两份字面量漂了的表现是「卡片再也不渲染了」，而 typecheck
+ * 一声不响。
+ */
+declare const SCHEDULE_DRAFT_TOOL = "schedule_draft";
+/**
+ * 草稿能落在哪几档权限上 —— **`bypass` 不在里面**。
  *
- * 界面那一份**落在宿主层**而不是这儿，判据同 §34.6 给 `view` 那 1 处的做法
- * （兜底文案挪给渲染端）：这个包的依赖白名单是空的，`t()` 只能由有它的那一层调。
+ * 不是「运行期会拒绝」，是那一档在类型上根本不存在（判据同
+ * `ScheduleTemplate.permission`）。理由比模板那一侧更直接：`bypass` 要一次
+ * 二次确认（`bypass-not-confirmed`），而那次确认的**对象是人**；让模型提议
+ * 一个「等着人去勾确认框」的档位，等于把那道确认变成一道例行手续。
+ *
+ * 用户自己想要那一档时照旧走表单 —— 那条路一个字都没改。
  */
-interface ContentToTextOptions {
+type ScheduleDraftPermission = Exclude<PermissionLevel, 'bypass'>;
+/** 草稿里那份清单。三个字段各自**可选**：没提到的一格 = 「这一格我没意见」 */
+interface ScheduleDraftAllowlist {
+    allowTools?: readonly string[];
+    allowOperations?: readonly OperationType[];
+    allowRules?: readonly string[];
+}
+/** 起草一条新任务 */
+interface ScheduleDraftCreate extends ScheduleDraftAllowlist {
+    action: 'create';
+    name: string;
+    prompt: string;
+    trigger: ScheduleTrigger;
+    /** 工作目录。不给就是引擎那份缺省（`~/.epoch/automation/<id>/`） */
+    workDir?: string;
+    permission: ScheduleDraftPermission;
     /**
-     * 这一条消息的图片**是不是另有真部件带着**（`EpochMessage.parts` 里那份
-     * base64，最终变成 provider 的原生图片部件）。
-     *
-     * 默认 `false` —— 也就是改造前的行为，落库那一列要的正是它：那一行
-     * `[图片 image/png]` 是**这一轮带过一张图**的唯一记录（`parts` 列另存，
-     * 但 FTS / 预览 / 标题只看 content）。
-     *
-     * `true` 时图片那一支整个**不折占位符**。判据是那句占位符的含义 ——
-     * 「这里本来有张图，但你看不到」。图真的在旁边时它就成了一句假话，而且是
-     * 会被照着信的那种：2026-09-01 实测，`@ai-sdk/deepseek@3.0.20` 把图片
-     * 静默丢了之后，模型读到的就是这一行，于是它逐字回答「我只看到
-     * 「[图片 image/jpeg]」这个占位符，图片没有传到我这边」。**升级 SDK 让图片
-     * 真的送达之后，这一行反而成了唯一还在撒谎的地方。**
+     * 为什么建议这一条，一句话。**给人看的**，会印在卡片上。
      *
-     * ⚠️ 只关图片那一支。`file` / `session` 的占位符**照旧**：它们说的是
-     * 「内容没附上」（`omitted` / `not-restored`），那句话在任何情况下都是真的，
-     * 而且是模型唯一能知道「有个东西没给我」的途径。
+     * 必填，而这是刻意的：一条凭空出现在对话里的定时任务，用户第一个问题
+     * 一定是「你为什么觉得我需要它」。答不上来的提案不该提。
      */
-    imagesCarriedAsParts?: boolean;
+    note: string;
 }
-declare function contentToText(content: EpochUserContent, opts?: ContentToTextOptions): string;
 /**
- * 「上一轮实际动过手」在**给模型的**历史里长什么样（2026-08-28）。
- *
- * ## 它修的是什么
- *
- * 喂模型的那份历史只有 user / assistant 两种角色的**文本**
- * （`runtime/src/agent-session.ts` 的累积、`session-store.ts` 的 `loadHistory()`），
- * 工具调用和结果一条都不在里面 —— 这是刻意的（孤立的 tool 消息会被 provider 拒掉，
- * 全量 transcript 是另一个体量的事）。代价此前没人算：一段五条消息的会话，
- * 模型看到的是**五条又长又具体的指令，配四句十来个字的「办完了」**。
- * 早期那几条指令的字数远大于「它已经做完了」的证据量，于是模型把它们当成还在
- * 生效的待办，回头去做 —— 而用户刚发的那一条被摊薄。实测在
- * `packages/runtime/__tests__/context-recency.test.ts`。
- *
- * 这一行就是补那份证据：不复原过程，只留一句「这一轮真的调了这些工具」。
- *
- * ## 判据用**结果**而不是调用
- *
- * `EpochToolCall` 上有工具名，但一次跑到一半被中止的轮次里那些调用**从没执行过**
- * （判据逐字同 `runtime/src/session-file-changes.ts` 的边界 1）。而一条
- * `EpochToolResult` 存在就意味着它跑完了 —— 拿结果当输入，「执行过没有」这件事
- * 不需要另外判一次。
- *
- * ⚠️ **它分不出成功和失败**：落盘的结果上没有 `success`（同上那份的边界 2）。
- * 所以措辞是「调用过」而不是「做成了」—— 一次被权限拒掉的 `file_write`
- * 在这里照样留一笔，而那句话仍然是真的。
+ * 提议改一条**已有**的任务。
  *
- * ## 为什么住在 protocol、且是冻住的中文
+ * 每一格都可选（`undefined` = 这一格不动），但至少要动一格 —— 一份什么都不改的
+ * 提案是在浪费用户的一次点击。这条判定在 core 那侧
+ * （`schedule/draft.ts` 的 `draft-update-empty`）。
  *
- * 它的读者是**模型**，和 {@link contentToText} / {@link filePartSummary} 同一类，
- * 所以走同一条规矩：住在这个零依赖的包里、逐字冻住、**不跟着界面语言变**
- * （门禁在 `packages/protocol/__tests__/message-projection.test.ts`）。一条进了
- * 上下文的历史跟着 `EPOCH_LANGUAGE` 变语言，等于把同一段会话劈成两半。
+ * ## ⚠️ 「放宽」和别的改动在类型上长得一样，所以判定必须在别处
  *
- * 只有工具名，不带参数 / 路径：带路径要 `affectedPaths()` + 工作目录，而那两样
- * 住在 core 和装配层，拿不到的地方（`loadHistory()`）就会退化成另一种措辞 ——
- * 两条路产出的历史一旦不一样，症状就是「刷新之后模型看到的和刚才不是同一段」。
+ * 把超时从 10 分钟调到 30 分钟，和往清单里加一条 `terminal(rm:*)`，在这个形状里
+ * 是同一种东西：几个可选字段。而后者是**提权**。所以两个宿主都必须自己把
+ * 「这次提案放宽了什么」单独标出来（web 的卡片、core 的工具输出），
+ * 不许把它混在一列改动里 —— 用户扫一眼就点保存的那一下，正是这条要防的。
+ */
+interface ScheduleDraftUpdate extends ScheduleDraftAllowlist {
+    action: 'update';
+    /** 改哪一条。模型得先用 `action: 'list'` 看见 id，界面上那串它猜不出来 */
+    id: string;
+    name?: string;
+    prompt?: string;
+    trigger?: ScheduleTrigger;
+    workDir?: string;
+    permission?: ScheduleDraftPermission;
+    enabled?: boolean;
+    maxTurns?: number;
+    timeoutMs?: number;
+    /** 同 {@link ScheduleDraftCreate.note}，必填 */
+    note: string;
+}
+type ScheduleDraft = ScheduleDraftCreate | ScheduleDraftUpdate;
+/**
+ * 一次提案里「放宽了什么」的分类。
  *
- * ⚠️ **调用方要的多半是 {@link assistantTurnText}，不是这一个** —— 那一份连
- * 「正文和这一行之间怎么接」一起定了，而那正是两条路会走散的地方。
+ * 只有三类，而三类都是**授权面变大**的方向：档位往松走、清单多了条目、
+ * 从停用变成启用。别往里加「超时变长」这种 —— 它花的是钱和时间，不是权限，
+ * 而把两种东西混进同一枚警示标，那枚标就不再有信息量。
  *
- * @param results 这**一轮**（不是一步）执行过的全部工具结果，按发生序
- * @returns 空数组时是空串 —— 这一轮没动手，那就没有这句话可说
+ * 判定在 core（`schedule/draft.ts` 的 `draftWidening`），渲染在 web
+ * （`thread/schedule-draft.tsx`）—— 两侧各算一遍是刻意的，判据同
+ * `web/src/thread/rows.ts` 文件头那条：web 读的是**模型发出的原始入参**，
+ * 而不是 core 归一化之后的结论。
  */
-declare function turnDigest(results: readonly Pick<EpochToolResult, 'toolName'>[]): string;
+type ScheduleWideningKind = 'permission' | 'allowlist' | 'enabled';
+
 /**
- * 一轮的 assistant 消息在**给模型的历史**里长什么样：正文 + {@link turnDigest}。
- *
- * ## 为什么这条胶水也得住在这儿
+ * 工作区信任契约。
  *
- * 因为它有**两个调用方，走两条路，产出必须逐字节相同**：
+ * 为什么需要：clone 一个仓库就等于让它的 `AGENTS.md` 进 system prompt、
+ * 它的 hook 配置被执行、它的 policy 覆盖本地权限判定。这是漏洞，不是缺功能。
+ * 信任判定把「加载项目级配置」这件事收到一次显式用户决策后面。
  *
- * - 直播：`runtime/src/agent-session.ts` 用 `TurnStepCollector` 收的那一轮；
- * - 恢复：`runtime/src/session-store.ts` 的 `loadHistory()` 从 DB 行折回来的那一轮。
+ * 竞品：Codex `codex-rs/tui/src/onboarding/trust_directory.rs`；
+ * Gemini CLI `packages/cli/src/config/trustedFolders.ts` + `packages/core/src/utils/trust.ts`。
+ * 两家都只是读过的参照物：契约形状跟它们都不一样（上游是 TRUST_FOLDER / TRUST_PARENT /
+ * DO_NOT_TRUST 三枚举 + 靠 TRUST_PARENT 取 dirname 来编码作用域，这里是三态字面量 +
+ * 独立的 scope 字段 + decidedAt）。本文件是独立实现，不带 SPDX 头。
+ * 判定证据见 docs/verify/VERIFY_RECORD-D-license-attribution.md
  *
- * 两边各写一次 `text + '\n\n' + digest` 的下场是：某天一边多一个换行，
- * 而症状是**刷新页面之后模型看到的历史和刷新前不是同一段** —— `reloadHistory()`
- * 的 JSDoc 里那句「它们一旦分叉，症状就是屏幕上和模型看到的对不上」骂的正是这个。
- * 门禁是 `packages/runtime/__tests__/context-recency.test.ts` 里那条逐字节比对。
+ * 这里只有类型，实现在 core —— 注意实现那边（`core/src/trust/manager.ts`）**是**
+ * gemini 的衍生作品（搬了「归一成生效目录再取最长匹配」那条算法），带头、在 NOTICE 里。
+ * 契约与实现的授权状态不同是对的，不是漏登记。
+ */
+/** 一个目录的信任状态 */
+type TrustLevel = 
+/** 用户明确信任：加载项目指令 / hook / policy */
+'trusted'
+/** 用户明确拒绝：只当普通工作目录，不加载任何项目级配置 */
+ | 'untrusted'
+/** 还没问过 */
+ | 'unknown';
+/** 用户已经做过决策的信任状态（排除「还没问过」） */
+type DecidedTrustLevel = Exclude<TrustLevel, 'unknown'>;
+/** 信任决策的作用域 */
+type TrustScope = 
+/** 只这个目录 */
+'directory'
+/** 这个目录及其所有子目录 */
+ | 'directory-tree';
+/**
+ * 一次授信授到哪一档（2026-09-11）。**两档是相加的：`exec` 蕴含 `read`。**
  *
- * 正文为空、只有 digest 时**不留前导空行**：那一轮模型只调了工具没说话
- * （`loop.ts` 允许），这时这条消息的全部内容就是那一行。
+ * ## 为什么拆
  *
- * @returns 空串 = 这一轮既没正文也没动手，调用方**别往历史里塞这一条**
- */
-declare function assistantTurnText(text: string, results: readonly Pick<EpochToolResult, 'toolName'>[]): string;
-/**
- * 部件类型的穷尽性守卫 —— **这是「加了一种部件却漏了一处分支」的那道会红的门禁**。
+ * 在它之前 `trusted` 是一个布尔，而那一个布尔后面挂着七样东西 —— 其中
+ * `.epoch/hooks.json` 和 `.claude/settings.json` 的每一项都是一条要 spawn 子进程的
+ * 命令（判据在 [core/hook/sources.ts](../../core/src/hook/sources.ts) 的文件头）。
+ * 而用户被问到的那句话逐字是「本目录的项目指令会加载」（`trust_prompt.granted`），
+ * **从来没提过 hook**。也就是说「往上下文里注入一段文本」和「在这台机器上执行
+ * 任意命令」共用了同一次点击，而问话只描述了前者。这不是 UX 问题，是知情同意错位。
  *
- * 消费 `EpochContentPart` 的地方有五处（这里、`sdk-adapter` 的 `toSdkPart`、
- * `session/payload` 的 `persistParts` / `restoreParts`、以及展示层），改造前它们
- * 全都写成「if text / if file / 剩下的当图片」。那个形状下加一种部件**不会有
- * 任何东西变红**：新部件会被静默当成图片，而症状是模型收到一个 `image:` 里
- * 塞着会话正文的请求，provider 报 400。
- */
-declare function assertNeverPart(part: never): never;
-type EpochMessageRole = 'system' | 'user' | 'assistant' | 'tool';
-/**
- * 一条会话消息。
+ * | 档  | 放开什么                                                        | 风险       |
+ * | --- | --------------------------------------------------------------- | ---------- |
+ * | `read` | 指令文件 / 技能 / 角色 / 命令                                  | 注入上下文 |
+ * | `exec` | `hooks.json` / `.claude/settings*.json` / `policies/` / settings 的 allow 那一半 | 执行、放宽判定 |
  *
- * `content` 永远是字符串（tool 消息为空串，内容在 `toolResults` 里），
- * 这样「取这条消息的文本」永远不需要判类型。
+ * ## ⚠️ 两条边界，别把它当别的东西
  *
- * 多模态**不是**把 `content` 放宽成联合类型 —— 那正是本文件开头骂过的病，
- * 会让 loop / codec / 压缩器每处都得判一次类型。改成加一个 `parts` 旁路：
- * `content` 仍然是权威的**文本投影**（压缩器、审计、持久化都只看它），
- * `parts` 只在 sdk-adapter 那一处被读走。两者的关系由 `contentToText` 保证。
+ * 1. **`exec` 不是权限档。** 它放开的是「这个仓库自带的 hook / policy 算不算数」，
+ *    不是「这次操作要不要问用户」——[两套机制照旧正交](../../core/src/trust/gate.ts)。
+ *    未授 `exec` 的目录里 agent 照样能跑 bash，只是仓库里那份 `hooks.json` 不生效；
+ * 2. **`read` 不是「安全档」。** 一份 `AGENTS.md` 能指挥 agent 去做任何它有权限做的
+ *    事，包括执行命令。拆开不是因为 `read` 无害，是因为**两者的问话不该合并成一次**。
  */
-interface EpochMessage {
-    role: EpochMessageRole;
-    content: string;
+type TrustTier = 'read' | 'exec';
+interface TrustRecord {
+    /** 绝对路径（已 resolve） */
+    path: string;
+    level: DecidedTrustLevel;
     /**
-     * 多模态部件。给了就以它为准喂模型，`content` 退化成它的文本投影。
-     * **不落 SQLite** —— 图片走 artifact 目录，DB 里只留 content 的占位文本。
+     * 这条决策管到哪儿。
+     *
+     * `check()` 会把它折叠进 `TrustLevel`，所以判定方用不上；但**列出记录**的一方
+     * （`epoch trust` 要显示「仅此目录 / 含子目录」）必须能看见 —— 少了它，
+     * `list()` 返回的就不是一条完整的决策，而是一条读不懂的决策。
      */
-    parts?: EpochContentPart[];
-    /** assistant 要求的工具调用；与 content 并存（模型可以边说话边调工具） */
-    toolCalls?: EpochToolCall[];
-    /** role 为 'tool' 时携带的执行结果 */
-    toolResults?: EpochToolResult[];
+    scope: TrustScope;
+    /** 记录时间戳（ms） */
+    decidedAt: number;
     /**
-     * 这一步模型的思考原文（推理模型的 `reasoning-delta` 累加）。2026-08-18。
+     * 执行类也授了吗（{@link TrustTier}）。`level: 'untrusted'` 时无意义。
      *
-     * **只给人看，不回灌模型**：`sdk-adapter.ts` 一个字都不读它。加它是因为
-     * 刷新页面之前屏幕上有「深度思考」那一段，刷新之后整段消失 —— 而那不是
-     * 「这一轮没想」，是我们没记。
+     * ⚠️ **缺省（`undefined`）= 没授**，而这一格正是存量记录的迁移：拆档之前写下的
+     * 记录没有这一格，于是升级之后它们**只剩读类** —— 判据就是上面那张表下面那段：
+     * 那些记录是在一句只说了「项目指令会加载」的问话下拿到的，把它们追认成执行类
+     * 等于替用户补签一份他没看过的同意书。代价（老用户的项目 hook 会停）由
+     * `trust_gate.exec_migrated` 那条诊断明说，不静默。
+     */
+    exec?: boolean;
+    /**
+     * 授 `exec` 那一刻，执行类输入文件的内容指纹（见 core 的 `trust/exec-hash.ts`）。
      *
-     * ⚠️ **它属于某一步，不属于整轮。** 一轮里模型可以想一次、调个工具、再想一次，
-     * 每次的思考挂在**它自己那条 assistant 行**上，位置就是它真实的时序位置。
-     * 拿它当「整轮的思考」拼成一根，回放时那一段会被钉到最前面，讲的却可能是
-     * 二十步之后的事（web 的 `thoughtParts` 治过同一个病，判据在
-     * `web/src/state/reducer.ts` 的 `trackThought()`）。
+     * 对不上 = 那些文件在授信之后被改过 → `exec` 退回未授，重新问一次。
+     * `exec` 为假时这一格不该存在。
      *
-     * 落盘走 `messages.reasoning` 列 —— 那一列**从会话库 v1 就在**，只是一直没人
-     * 写过，所以这一档不需要迁移。
+     * ## ⚠️ 这是对 [manager.ts](../../core/src/trust/manager.ts) 文件头「两条明确不做」
+     * 第 2 条的一次**窄口推翻**，不是把它作废
+     *
+     * 那一条 2026-08-08 写着：记内容 hash「代价是『改一行 AGENTS.md 就被打断一次』，
+     * 这个打断比它挡住的风险更贵」。**那个结论在读类上照旧成立，一个字不改** ——
+     * 指令文件天天在动，为它记 hash 会把授信变成一件每天都要重做的事。
+     *
+     * 翻的只有执行类那一半，因为它的两项输入都变了：
+     *
+     * | | 读类（AGENTS.md）      | 执行类（hooks.json / policies） |
+     * | --- | ---------------------- | -------------------------------- |
+     * | 改动频率 | 每天              | 几乎不动                          |
+     * | 改动后果 | 多一段文本        | **多一条会跑的命令**              |
+     *
+     * 也就是说，同一个做法在这一侧的打断成本低一个量级、挡住的东西贵一个量级。
+     * 参照物：codex 对 hook 记 `trusted_hash`（`codex-rs/config/src/hook_config.rs`），
+     * 而它的 `AGENTS.md` 压根不过闸门 —— 同一条判据的两侧，它也是这么分的。
      */
-    reasoning?: string;
+    execHash?: string;
+}
+/** {@link TrustManager.record} 的可选档位。不给 = 只授读类 */
+interface TrustGrant {
+    /** 连执行类一起授。**调用方必须真的为这一档单独问过用户** */
+    exec?: boolean;
+    /** 授 `exec` 时一并记下的内容指纹 */
+    execHash?: string;
+}
+/**
+ * {@link TrustManager.checkExec} 的答案 —— **记录里写的，不含新鲜度校验**。
+ *
+ * 两格一起交出来是因为校验方（`core/src/trust/gate.ts`）需要拿 {@link hash} 去和
+ * 现算的值比；拆成两次调用的话，两次之间可能命中**不同的记录**
+ * （`bestRecord()` 是按最长匹配现算的），于是拿 A 记录的授信配上 B 记录的指纹。
+ */
+interface TrustExecGrant {
+    /** 记录里授过执行类吗 */
+    granted: boolean;
+    /**
+     * 授的时候记下的内容指纹。
+     *
+     * ⚠️ **`undefined` = 校验不了，而这一档照旧放行**（判据在 gate 的 `decide()` 上）。
+     * 今天所有写入口都会带上它，所以这一档只可能来自手改 `trust.json`。
+     */
+    hash?: string;
+}
+interface TrustManager {
+    /** 查某个目录的信任状态（含父目录的 directory-tree 继承） */
+    check(dir: string): TrustLevel;
+    /**
+     * 查某个目录的执行类授信（含继承）。**和 {@link check} 是两个问题**：
+     * 这一个只在 `check()` 回 `'trusted'` 时才可能授过，反过来不成立。
+     */
+    checkExec(dir: string): TrustExecGrant;
+    /** 记录一次决策 */
+    record(dir: string, level: DecidedTrustLevel, scope: TrustScope, grant?: TrustGrant): void;
+    list(): readonly TrustRecord[];
+    revoke(dir: string): void;
 }
 
 /**
@@ -6090,8 +6200,20 @@ type WireAgentEvent = (FunctionKeys<PlainAgentEvent> extends never ? PlainAgentE
 /**
  * 一个会话的回合状态。
  *
- * `running` 时第二个 `POST /messages` 直接 409，不排队也不交织：`AgentSession`
- * 的历史累积发生在 `run()` 末尾，两轮并发跑会让历史顺序变成不确定的。
+ * `running` 时第二个 `POST /messages` **不会再开一轮**：`AgentSession` 的历史累积
+ * 发生在 `run()` 末尾，两轮并发跑会让历史顺序变成不确定的。
+ *
+ * ⚠️ 这句话的**后半截改过两次，别再照着旧版本推断**：
+ *
+ * | 时期 | 第二个 POST 的下场 |
+ * | --- | --- |
+ * | 方案 20 | 直接 409（那时只有一个会话，409 是唯一能给的答复） |
+ * | 方案 30 §2.3 | **排队**，等这一轮跑完再开（`{ok:true, queued:true}`） |
+ * | 2026-09-16 | 默认被**拌进正在跑的那一轮**（`steered: true`），排队只剩斜杠命令那一档 |
+ *
+ * 三版共同的不变量只有一条：**一个会话同一时刻只有一个 `run()`**。
+ * 「409」和「排队」都是那条不变量在某一版的**实现**，不是契约。
+ * 今天的两档分别在 `WireSendMessageResponse.steered` 和 `SessionHub.steerFrom` 上。
  */
 type WireTurnState = 'idle' | 'running' | 'awaiting-approval' | 'awaiting-question';
 /**
@@ -6201,7 +6323,8 @@ type WireHubEvent =
     type: 'session-cooled';
 }
 /**
- * **会话列表变了** —— 多了一段，或者少了一段（2026-09-11）。
+ * **会话列表变了** —— 多了一段、少了一段，或者有一段被收进 / 移出归档
+ * （2026-09-11；归档那一档 2026-09-16 补）。
  *
  * ## 它治的是「不是我建的那一段」
  *
@@ -6230,12 +6353,25 @@ type WireHubEvent =
  * （`reducer.ts` 的 `applyFrame`：别的会话的帧会进 `parked`，而 `parkFrame`
  * 只认 `session-state` / `session-cooled`，别的 Hub 事件在那儿被丢掉）。
  *
- * ## ⚠️ 覆盖不到的那一档：**标题改了不发这一帧**
+ * ## ⚠️ 「多一段 / 少一段」不等于「建了 / 删了」（2026-09-16 补的第三个产地）
+ *
+ * 原文写的是「它的两个产地都在**进出 Hub** 这条路上」，并据此把整条
+ * `PATCH /api/sessions/:id` 划到覆盖范围之外（「压根不经过 Hub，只动 DB」）。
+ * **那句推论是错的**：这一帧的宾语是**那条列表端点答出来的那几行**，不是 Hub 的表。
+ * 而列表默认**不列归档的会话**，于是「收进归档」在列表上就是少一行、「取回」
+ * 就是多一行 —— 和 DELETE / POST 那两个产地一模一样。
+ *
+ * 症状是这一轮的正题（2026-09-16 用户实测）：在设置页「会话」那一分区点「取回」，
+ * 左边侧栏那份列表一动不动，**重启应用才看得见**取回来的那一段 —— 和上面那个
+ * 飞书宿主的原话逐字同形。产地在 `server/src/api.ts` 的 `patchSession`，
+ * **只在 `archived` 真的翻了的时候发**。
+ *
+ * ## ⚠️ 覆盖不到的那一档：**标题改了仍然不发这一帧**
  *
- * 它的两个产地都在「进出 Hub」这条路上（建会话、删会话那两条端点）。而改标题
- * （`PATCH /api/sessions/:id`）压根不经过 Hub，只动 DB —— 于是另一个标签页上
- * 那一行的标题仍然会过期到下一次重取。📮 那一档要治得给它自己的产地，
- * 别照着这一帧的名字想当然。
+ * 同一条端点上的另一半：改标题不改变「列哪几段」，只改变某一行上的一格。
+ * 于是另一个标签页上那一行的标题仍然会过期到下一次重取。📮 那一档要治得给它
+ * 自己的产地（一帧带得动「哪一行的哪一格变了」的事件），别顺手挂到这一帧上 ——
+ * 让所有标签页因为别人改了个名字就重取一次整份列表，是拿错误的粒度换方便。
  */
  | {
     type: 'sessions-changed';
@@ -8166,6 +8302,26 @@ interface WireReplayMessage extends EpochMessage {
      * 「这一轮不知道花了多少」处理 —— 界面上那半行字整个不画，而不是画一行 0。
      */
     turnFacts?: EpochTurnFacts;
+    /**
+     * 这一轮**为什么停**。和 {@link WireReplayMessage.turnFacts} 一样，只有一轮里
+     * 最后一条 assistant 行有。
+     *
+     * ## 没有它的时候，刷新一下就再也看不出这一轮出过事（2026-09-16）
+     *
+     * 引擎在**直播**时是说得出话的：截断发一帧 `response-truncated`、跑完工具
+     * 却没说话发一帧 `blank-response`，两者都画成一行 ℹ️。但那些 `notice`
+     * **不落盘**（`TurnStepCollector.observe()` 只收 text / reasoning / tool / finish），
+     * 而回合一结束 web 就拿权威历史整体换掉 pending —— 那一行当场消失。
+     *
+     * 于是用户回头看到的是：一条两个字的回复，底下是一模一样的脚注
+     * 「共 289.2k token · deepseek-flash · 8 次工具 · 42s」，没有任何东西说过
+     * 刚才发生了什么。这一格就是那个记号。
+     *
+     * ⚠️ 类型是 `string` 而不是 {@link FinishReason}：真源是 `messages.finish_reason`
+     * 那一列，它在库里就是 `TEXT`（老库里还可能是 NULL）。读侧要按码分叉的话，
+     * **认不出来的值一律当「不知道」**，别画成任何一档 —— 编一个终局比不画贵。
+     */
+    finishReason?: string;
 }
 interface WireMessageListResponse {
     messages: readonly WireReplayMessage[];
@@ -8196,6 +8352,56 @@ interface WireMessageListResponse {
      * 三种都是「不知道」，界面上一律整格不画 —— 画 0 是一个假事实。
      */
     usage?: TokenUsage;
+    /**
+     * 上面那批 `messages` **含正在跑的那一轮**，而且它的已落盘部分对应到这一帧
+     * 广播序号为止（按步增量落盘，2026-09-16）。缺席 = 这段会话此刻没有在本进程
+     * 跑着的轮次。
+     *
+     * ## 它治的是什么
+     *
+     * 2026-09-16 之前，「回合在跑 ⇒ 这一发答不出本轮那几条」是一条不变量，
+     * 浏览器整个 `replay` 分支建立在它上面（`web/src/state/reducer.ts`）——
+     * 因为一轮问答要等 `run()` 末尾才整批落盘。代价是**刷新 / 关掉重开 / 切走
+     * 再切回来**都看不见正在跑的那一轮，`WebState` 上那两块补丁
+     * （`localTail` / `parked`）就是在浏览器里兜这件事，而它们的注释逐字写着
+     * 「治不到的那一档……真要修得让服务端答出在飞的那一轮」。
+     *
+     * 改成按步落盘之后服务端答得出了，于是冒出**去重**这个新问题：同一步既在
+     * 这批 `messages` 里、又在浏览器自己攒的 pending 里。
+     *
+     * ## 为什么钥匙是 `seq`
+     *
+     * 因为它是两边**已经共用**的那一个：每一帧信封上都有、是 SSE 续传的游标，
+     * 而浏览器早就把它锚进了每一个 pending 项（`HistoryItemBase.seq`）。
+     * 落盘的消息 id 在浏览器那侧不存在，`seq` 是唯一对得上的东西。
+     *
+     * ## ⚠️ 服务端取这个数和截断 `messages` 是**同一瞬**的两半
+     *
+     * 这一格的语义是「`messages` 里的在飞部分**恰好**到这一帧为止」。所以服务端
+     * 记的是一对 `(消息 id, seq)`，两个数在同一次 `publish()` 之后一起取，
+     * 然后按那个 id 截断。分两次取的话会出现「行已经写下去、对应那一帧还没发」
+     * 的窗口，而那个窗口里浏览器会把同一步画两遍。
+     *
+     * 浏览器拿到它之后做两件事：丢掉 `localTail`（用户那句话已经在库里了），
+     * 以及丢掉 `seq <= 这个数` 的 pending 项。
+     */
+    inFlightThroughSeq?: number;
+    /**
+     * 有一轮**没跑完**，它从这条消息 id 开始（按步增量落盘，2026-09-16）。
+     * 缺席 = 没有这种轮次（绝大多数情况）。
+     *
+     * 和上面那一格**互斥**：那一格说「正在跑」，这一格说「跑过但没收尾」。
+     * 两者都由 `sessions.open_turn_from` 那格标记来判，区别只在「这个进程手上
+     * 有没有它」—— 判据全文在 `SessionMeta.openTurnFrom` 上。
+     *
+     * ⚠️ **不能靠 `finishReason` 为空来推断。** 那一列在会话库 v6 之前的行上
+     * 全是 NULL（一台真机上量过 687 条 687 个 NULL），拿它判会把每一段老会话的
+     * 每一轮都标成「没跑完」。
+     *
+     * 界面拿它在那一轮上画一句「这一轮没跑完」。不画的话，用户看到的是一段
+     * 说到一半就断的对话，而分不出「模型自己停了」和「程序被关掉了」。
+     */
+    interruptedTurnFrom?: number;
 }
 declare const WIRE_MESSAGE_LIST_FIELDS: WireFields<WireMessageListResponse>;
 /**
@@ -8290,6 +8496,31 @@ interface WireSendMessageResponse {
     accepted: true;
     /** 这一条被排到了当前这一轮后面，还没开始跑 */
     queued: boolean;
+    /**
+     * `queued: true` 的两种去向里的哪一种（2026-09-16）。
+     *
+     * | 值           | 意思                                                       |
+     * | ------------ | ---------------------------------------------------------- |
+     * | `true`       | 正在跑的那一轮会在下一次模型请求前把它拌进去（**插进本轮**）|
+     * | `false`      | 排在后面，等这一轮跑完再**开新的一轮**                     |
+     * | 整个键缺席   | `queued: false`（这条消息立刻开了一轮），问题不成立         |
+     *
+     * ## 为什么必须由服务端说
+     *
+     * 两条判据都在服务端手上：队列里排在它前面的那几条**能不能**折进去，
+     * 以及它自己是不是一条带轮级设置的斜杠命令（`allowed-tools` / `model:`
+     * 那种收窄只对一整轮成立，折进别人的轮里就整个落空）。浏览器两条都看不见。
+     *
+     * ## ⚠️ 它是「会被拌进去」，不是「已经拌进去了」
+     *
+     * 真的进上下文那一刻由事件流上的 `steer` 那一帧宣布。这一轮在那之前撞上轮次
+     * 上限、或者被用户中止时，这条消息会退回队列（开新一轮）或者被
+     * `WireAbortResponse.returned` 交还 —— 那时这一格就说早了。
+     *
+     * 所以界面**据它选措辞**（「插入本轮」/「排队中」）可以，
+     * **据它把消息画成已送达**不行。
+     */
+    steered?: boolean;
     /**
      * 这条输入是一条自定义斜杠命令，服务端把它展开了（方案 23 的 web 那一半）。
      *
@@ -8412,6 +8643,30 @@ declare const WIRE_SEND_MESSAGE_RESPONSE_FIELDS: WireFields<WireSendMessageRespo
 /** `aborted: false` 表示这一轮本来就没在跑，不是失败 */
 interface WireAbortResponse {
     aborted: boolean;
+    /**
+     * 按下停那一刻**还没被引擎取走**的排队消息，按用户发送的先后（2026-09-16）。
+     *
+     * ## 它答的是「我刚打的那段话去哪了」
+     *
+     * 中止一直会把队列一起清掉（判据在 `SessionHub.abort` 上：按下停要的是现在
+     * 别干了，不是停掉这一轮然后立刻开始下一轮）。「跑到一半插一句话」落地之后，
+     * 那条清空变成一个真会咬人的形状 —— 用户盯着屏幕打了一整段修正意见、发出去、
+     * 看见模型还在往错的方向跑，于是顺手按了停，**那段话就没了**。
+     *
+     * 所以原样交出来，宿主把它放回输入框。codex 的同一处叫
+     * `submit_pending_steers_after_interrupt`。
+     *
+     * ## ⚠️ 已经拌进上下文的那些**不在这里**
+     *
+     * 事件流上已经发过 `steer` 的那几条早就是这段对话的一部分（库里有、屏幕上有），
+     * 交还一次就成了重复。这一条不靠服务端判断保证 —— 两条路（引擎取用和这里的
+     * 清空）动的是同一个数组。
+     *
+     * **一条都没有时整个键缺席**，不是空数组：绝大多数中止发生在没有排队消息的
+     * 时候，写一个 `[]` 会让每个读它的人多判一次「空数组是没有，还是这一版
+     * 服务端不支持」。
+     */
+    returned?: EpochUserContent[];
 }
 declare const WIRE_ABORT_FIELDS: WireFields<WireAbortResponse>;
 /**
@@ -10450,6 +10705,83 @@ interface WireRoleAddResponse {
     path: string;
 }
 declare const WIRE_ROLE_ADD_RESPONSE_FIELDS: WireFields<WireRoleAddResponse>;
+/**
+ * 一次删除为什么没成 —— 五档，**每一档对一个不同的下一步**。
+ *
+ * | 　            | 意思                                   | 用户的下一步                          |
+ * | ------------- | -------------------------------------- | ------------------------------------- |
+ * | `missing`     | 请求里没给名字                         | （界面不该发出这一发，见下）          |
+ * | `not-found`   | 角色表里没有这个名字                   | 刷新这一栏再看，多半已经没了          |
+ * | `not-user`    | 它来自内置 / 项目 / 插件 / 宿主        | 那句话里点名了是哪一层，各有各的删法  |
+ * | `ambiguous`   | 目录里两份以上都叫这个名字             | 去那个目录里留下要的那一份            |
+ * | `failed`      | 真的删不动（权限 / 只读盘）            | 去那条路径那儿看一眼                  |
+ *
+ * ⚠️ `missing` 那一档**照走 200 + `ok:false`**，不是 400 —— 判据逐字同
+ * {@link WireSkillRemoveFailure}：`{error:{code,message}}` 在界面上会走到
+ * 「请求坏了」那一支去。
+ */
+type WireRoleRemoveFailure = 'missing' | 'not-found' | 'not-user' | 'ambiguous' | 'failed';
+/**
+ * `POST /api/roles/remove` —— 删掉一个**用户级**身份。
+ *
+ * 请求体只有 `{name}`，所以不给它单开一个类型（同 `WireSkillRemoveResponse`
+ * 那条：一个只有一格的请求体类型，读者要多跳一次才知道它就是那一格）。
+ *
+ * ## ⚠️ 没有「预览 → 确认」那一对，而那不是省事
+ *
+ * 判据逐字借技能那条：导入那个 token 防的是「用户看过的那一份」和「真装上的
+ * 那一份」不是一份，而删除这边**要删掉的东西由名字唯一确定**。
+ * 挡住不可撤销的是另外两样：界面上那一步「再按一次确认」，和回执里的
+ * {@link path} —— 用户得看得见自己刚销毁了盘上的哪一处。
+ *
+ * ⚠️ 而身份这条比技能那条多一格 {@link takenOverBy}，理由见那一格。
+ */
+interface WireRoleRemoveResponse {
+    ok: boolean;
+    /**
+     * 谁真的没了。**没删成时是空串**，不是把请求里那个名字抄回去 ——
+     * 判据逐字同 `WireSkillRemoveResponse.name`：回一个其实还在盘上的名字，
+     * 是这条端点最坏的说谎方式。
+     */
+    name: string;
+    /**
+     * 刚刚被销毁的是盘上哪一份（服务端的绝对路径）。没删成时 `null`。
+     *
+     * **必须发出来**，判据同技能那条（不可撤销的动作，回执得说得出销毁了哪一处）。
+     * ⚠️ 而这条路上它还多一层意思：**文件名可以和身份名不一样**
+     * （frontmatter 的 `name` 优先于文件名，判据在 core 的 `removeRoleFile`
+     * 文件头第一节）—— 所以这条路径是用户**唯一**能核对「我删掉的是不是那一份」
+     * 的东西，浏览器自己拼不出来。
+     */
+    path: string | null;
+    /**
+     * 删完之后，**这个名字还在不在合并表里**（`null` = 真的没了）。
+     *
+     * ## ⚠️ 这一格答的是「那一行会不会消失」，而答案常常是「不会」
+     *
+     * 用户级那一份可能是一个**同名覆盖**（手写一份 `general.md` 就是，
+     * `mergeRoles` 的同名语义是「prompt / description 整份替换、工具取交集」）。
+     * 删掉它之后下层那一份**浮上来**：能力页刷新出来，那一行**还在**，只是挪去了
+     * 「内置」那一组、描述和工具都变了。
+     *
+     * 少了这一格，那一屏对用户说的是「已经删掉 x」而列表里 x 还在 —— 一次成功的
+     * 删除长成了一次失败的删除，而屏幕上没有任何地方解释得了。
+     *
+     * 非 `null` 时它是**接管者那一层**（`builtin` / `project` / `plugin` / `host`），
+     * 界面据此多印一句。⚠️ 它**不可能**是 `'user'`：用户级那一份刚被删掉，
+     * 而同一个目录里还有第二份同名的话，上面那道 `ambiguous` 已经把这一发拦掉了。
+     */
+    takenOverBy: AgentRoleSource | null;
+    /**
+     * 没删成时那一句话（`reason` 各配一句，含「那该去哪儿改」）。删成了是 `null`。
+     *
+     * ⚠️ 它在 **core / runtime** 里现渲染，所以 `lang` 要从服务端一路递下去 ——
+     * 这条病 2026-08-18 在导入那一屏上实测见过一次。
+     */
+    detail: string | null;
+    reason: WireRoleRemoveFailure | null;
+}
+declare const WIRE_ROLE_REMOVE_FIELDS: WireFields<WireRoleRemoveResponse>;
 
 /**
  * 插件那一页的契约 —— 十四条端点（方案 59 §六 E2，2026-08-21；本地源与市场管理
@@ -12778,6 +13110,16 @@ declare const WIRE_PERMISSION_SET_RESPONSE_FIELDS: WireFields<WirePermissionSetR
  * 新值，就是这一屏存在的理由本身要消灭的那种撒谎 —— 而这一条对 `new-session`
  * 那一档**同样成立**（正在跑的会话按的仍是旧值），只是它下一次 `GET` 会真的变。
  *
+ * ## ✅ 2026-09-16：值照旧不变，但**盘上是什么现在也发出来了**
+ *
+ * 上面那一条一个字都没改，改的是它**只说了一半**这件事：行上的值不动是对的，
+ * 可那句「已写进 X，重启后生效」当时只活在浏览器的一个组件 state 里 —— 切一次分区、
+ * 刷一次页面就没了，屏幕上回到「旧值 + ① 内置默认」，而那个文件里躺着用户刚写的值。
+ * 用户的原话是「改完了保存了，页面也没有展示新的数字，不知道有没有生效」。
+ *
+ * 所以现在每一行可以多带一格 {@link WireSettingRow.pending}：**盘上那一份**。
+ * 两格并排、各答各的问题，没有哪一格需要撒谎。
+ *
  * ## 会话作用域，不是进程级的 `/api/settings`
  *
  * 项目级那两层（③④）跟着**工作区**走，而工作区按会话绑（决定 18）。
@@ -12956,6 +13298,54 @@ interface WireSettingStep {
     value?: WireSettingValue;
 }
 declare const WIRE_SETTING_STEP_FIELDS: WireFields<WireSettingStep>;
+/**
+ * **已经写进盘、但这个进程还没在用**的那一次改动（2026-09-16）。
+ *
+ * ## 它补的是上面那条「值不变」留下的另一半
+ *
+ * `restart` 那一档写完，行上的 {@link WireSettingRow.value} 一个字都不变 —— 那是对的
+ * （判据在 {@link WireSettingApply}，把它乐观换成新值是这一屏存在的理由本身要消灭的
+ * 那种撒谎）。可**只做到这一步，屏幕上就一条线索都不剩了**：用户按完保存、切一次
+ * 分区再回来，看到的是「旧值 + ① 内置默认」，而 `~/.epoch/config.yaml` 里明明躺着他
+ * 刚写的那个值 —— 不但没人告诉他写成了，那枚来源徽标还在说一句会被文件反驳的话。
+ *
+ * 所以这一格发的是**盘上那一份**，和行上那个「进程正在用的」并排摆着。两件事从来
+ * 就不是一件事，这一轮之前只是没地方说出后者。
+ *
+ * ## ⚠️ 它只认「**这个进程**里有人按过保存」
+ *
+ * 服务端记的是一本进程内的账（runtime 的 `SettingsControl.write()` 每成功一次记一笔），
+ * **不是**每次 `GET` 去重读那几个文件。于是 `epoch config set` 和用户自己拿编辑器改
+ * `config.yaml` 这两条路**不会**在这里出现 —— 那是这个取舍写在脸上的代价，别把它
+ * 读成 bug。重读那条路要重走一遍配置解析，还要分辨 `EPOCH_*` 环境变量造成的
+ * 「文件值和进程快照天然不同」，而那种差别报出来全是假的 pending。
+ *
+ * ## 三件让这一格不至于自己变成假话的事
+ *
+ * 1. **和生效值相等时整个不带这个键。** 用户改完又改回原值，盘上和进程就一致了，
+ *    那时还挂着一句「待重启」是自己造出来的焦虑；
+ * 2. **`value` 是落盘后回读验证过的那个**，不是把请求原样回显（同
+ *    {@link WireSettingsWriteResponse.value}）；
+ * 3. **`futile` / `apply` 是现算的**，不是记账那一刻拍下来的 —— 它们必须和这一行此刻
+ *    那个 {@link WireSettingWrite} 说的是同一句话，否则行上的警告和行下的回执会打架。
+ *
+ * 字段和 {@link WireSettingsWriteResponse} 逐字相同，那不是巧合：「刚刚写完的那一次」
+ * 和「写过了还没生效的那一次」是同一件事的两个时刻。所以那一份**继承这一份**，
+ * 界面也只有一个渲染回执的地方。
+ */
+interface WireSettingPending {
+    /** 写进了哪一层 */
+    layer: WireSettingWriteLayer;
+    /** 真正写了的那个文件的绝对路径，含义同 {@link WireSettingWrite.path} */
+    path: string;
+    /** **盘上现在**是这个值。行上那个 `value` 是进程正在用的，两者此刻不同 */
+    value: WireSettingValue;
+    /** 写进去了也照样不生效的理由。生效时整个不带，含义同 {@link WireSettingWrite.futile} */
+    futile?: WireSettingFutile;
+    /** 要做什么它才会被用上，见 {@link WireSettingApply} */
+    apply: WireSettingApply;
+}
+declare const WIRE_SETTING_PENDING_FIELDS: WireFields<WireSettingPending>;
 /** 设置页上的一行 */
 interface WireSettingRow {
     /**
@@ -13019,6 +13409,18 @@ interface WireSettingRow {
      * 的话，schema 哪天多一档，那一档在文档里存在、在界面上点不出来。
      */
     choices?: readonly string[];
+    /**
+     * 这一行**已经写进盘、而这个进程还没在用**的那个值（2026-09-16）。
+     * **没有这回事时整个不带这个键**，同 `value` / `futile` 那条规矩。
+     *
+     * ⚠️ **它不是 `value` 的候补，两格必须同时读。** `value` 答的是「这个进程此刻按的
+     * 是什么」，这一格答的是「盘上现在是什么」—— 界面拿前者画那一行、拿后者在行上挂一枚
+     * 芯片加一句回执。把后者显示成前者，就退回成了 {@link WireSettingApply} 里那条判据
+     * 明令禁止的乐观更新。
+     *
+     * 整个契约在 {@link WireSettingPending} 上，包括「为什么它照不到 `epoch config set`」。
+     */
+    pending?: WireSettingPending;
 }
 declare const WIRE_SETTING_ROW_FIELDS: WireFields<WireSettingRow>;
 interface WireSettingsResponse {
@@ -13106,29 +13508,19 @@ declare const WIRE_SETTINGS_WRITE_REQUEST_FIELDS: WireFields<WireSettingsWriteRe
  *
  * 值真的变没变由下一次 `GET` 说（`model` 走 `new-session` 那一档时它会跟着动，
  * 判据在 {@link WireSettingApply}）。
+ *
+ * ## ⚠️ 它**继承** {@link WireSettingPending}，多出来的只有一个 `key`（2026-09-16）
+ *
+ * 那一份是「写过了、还没生效」，这一份是「刚刚写完」—— 同一件事的两个时刻，
+ * 于是字段逐字相同。声明成两个独立的接口的话，哪天有人往其中一边加一格，
+ * 界面上「刚保存完看到的」和「刷新之后看到的」就会分叉，而那种分叉在屏幕上
+ * 看起来只是「刷新一下少了点东西」，没人会报这个 bug。
+ *
+ * `key` 只在这一份上，因为那一份是**挂在行上的**（{@link WireSettingRow.pending}），
+ * 键已经由那一行说了 —— 再发一遍就是同一个问题的两个答案。
  */
-interface WireSettingsWriteResponse {
+interface WireSettingsWriteResponse extends WireSettingPending {
     key: string;
-    layer: WireSettingWriteLayer;
-    /** 真正写了的那个文件 */
-    path: string;
-    /**
-     * **校验之后**落盘的那个值，不是把请求原样回显。
-     *
-     * 两者在 zod 修剪过的输入上会不一样，而界面印的必须是文件里现在那个 ——
-     * 回显请求等于让屏幕上出现一个文件里没有的东西。
-     */
-    value: WireSettingValue;
-    /**
-     * 落盘之后**仍然**不生效的理由，含义同 {@link WireSettingWrite.futile}。
-     *
-     * 写之前那一份已经说过一次了，这里再算一次不是重复：用户是看着警告按下去的
-     * （那是他的权利 —— 把用户级默认值钉住、由项目本地临时压着是件正常事），
-     * 所以回执里必须把同一句话再说一遍，否则「保存成功」四个字会盖掉它。
-     */
-    futile?: WireSettingFutile;
-    /** 见 {@link WireSettingApply} */
-    apply: WireSettingApply;
 }
 declare const WIRE_SETTINGS_WRITE_FIELDS: WireFields<WireSettingsWriteResponse>;
 
@@ -14907,4 +15299,4 @@ declare const SECRET_SERVICE = "epoch-agent";
  */
 declare const MCP_DATA_KEY_NAME = "mcp-auth-data-key";
 
-export { ACTION_CONTEXTS, AGENT_ROLE_NAME_PATTERN, API_KEY_ENV_VARS, APPROVAL_OUTCOMES, type ActiveAgentRole, type AgentEvent, type AgentEventOf, type AgentEventType, type AgentRole, type AgentRoleScope, type AgentRoleSource, type ApprovalAnswer, type ApprovalOutcome, type ApprovalReply, type ApprovalRequest, type ArtifactKind, type AttributeValue, type Attributes, type BackgroundTaskInfo, type BackgroundTaskKind, type BackgroundTaskStatus, type BlankCard, type BlankGreeting, type BoundKey, type BudgetBreach, COMMAND_NAME_PATTERN, COMPLIANCE_ACTIONS, COMPLIANCE_CATEGORIES, CURRENCIES, type Catalogs, type ComplianceAction, type ComplianceCategory, type ContextBreakdown, type ContextSegment, type Currency, type CurrencyDisplay, type CustomCommandDef, type CustomCommandSource, DEFAULT_AGENT_ROLE, DEFAULT_LANG, type DecidedTrustLevel, type Diagnostic, DiagnosticSink, type DiagnosticStatus, type EpochConfig, type EpochContentPart, type EpochFilePart, type EpochHook, type EpochImagePart, type EpochMessage, type EpochMessageRole, type EpochPlugin, type EpochSessionPart, type EpochSkill, type EpochTextPart, type EpochTool, type EpochToolCall, type EpochToolResult, type EpochTurnFacts, type EpochUserContent, type ExpandedCommand, type FileOmitReason, type FinishReason, type FixableApproval, type FlatCatalog, type FormatMoneyOptions, GEN_AI, HEADLESS_INPUT_EVENT_TYPES, HEADLESS_INPUT_FORMATS, HEADLESS_OUTPUT_FORMATS, HEADLESS_PROTOCOL_VERSION, type HeadlessEnvelope, type HeadlessEvent, type HeadlessInit, type HeadlessInputEvent, type HeadlessInputEventType, type HeadlessInputFormat, type HeadlessLifecycleEvent, type HeadlessOutputFormat, type HeadlessResult, type HeadlessResultReason, type HookContext, type HookEvent, type HookHandler, type HookManager, type HookRegistration, type HookType, type HostText, type HostUser, type JsonSchema, KEY_ACTIONS, type KeyAction, type KeyChord, type KeyContext, type KeySequence, type KeybindingReport, type KeybindingSource, type KeybindingTable, LANGS, type Lang, type LocalizedDetail, type LogFn, MAX_ATTACH_BYTES, MAX_ATTACH_FILES, MAX_ATTACH_TOTAL_BYTES, MAX_HEADER_CHARS, MAX_OPTIONS, MAX_QUESTIONS, MAX_SESSION_ATTACH_BYTES, MAX_SESSION_REFS, MCP_DATA_KEY_NAME, METRIC, MIN_OPTIONS, type MentionSet, type ModelRef, type ModelSelection, type ModelSelectionOrigin, type MoneyDigits, NOOP_TELEMETRY, type NoticeCode, OPERATION_TYPES, OVERSIZE_RATIO, type Operation, type OperationType, PERMISSION_LEVELS, PLAN_OUTCOMES, PROVIDER_INFOS, PROVIDER_TYPES, type PermissionDecision, type PermissionLevel, type PermissionManager, type PermissionRuleLists, type PlanApprovalOutcome, type PlanProposal, type PluginContext, type ProviderInfo, type ProviderType, type QuestionAnswer, type QuestionItem, type QuestionOption, type QuestionRequest, RESERVED_CHORDS, RESERVED_COMMAND_NAMES, type RejectReason, type RejectedKey, type RuleValue, SCHEDULE_DRAFT_TOOL, SCHEDULE_INTERVAL_MINUTES, SCHEDULE_RUN_STATUSES, SCHEDULE_TEMPLATES, SEARCH_API_KEY_ENV, SEARCH_PROVIDER_TYPES, SECRET_SERVICE, SEQUENCE_CONTEXTS, SESSION_MENTION_PREFIX, SESSION_REFERENCE_ERROR_CODES, SHELL_KINDS, SIDEBAR_MENU_MESSAGE_TYPE, SIMULTANEOUS_CONTEXTS, SYSTEM_NOTE_PREFIX, type ScheduleAllowlist, type ScheduleBackendKind, type ScheduleCycle, type ScheduleDefinition, type ScheduleDraft, type ScheduleDraftAllowlist, type ScheduleDraftCreate, type ScheduleDraftPermission, type ScheduleDraftUpdate, type SchedulePendingApproval, type SchedulePendingItem, type ScheduleRun, type ScheduleRunStatus, type ScheduleRunnerSpec, type ScheduleTemplate, type ScheduleTemplateId, type ScheduleTrigger, type ScheduleTriggerKind, type ScheduleWeekday, type ScheduleWideningKind, type SearchProviderType, type SecretBackendId, type SecretStore, type SelectionContext, type SelectionRejection, type SelectionWarning, type SessionAttachKind, type SessionAttachResult, type SessionOmitReason, type SessionSurfaceMessage, type SessionSurfaceView, type SetSelectionResult, type ShellKind, type SidebarMenuItem, type SidebarMenuMessage, type SpanLike, type SubToolCall, type SubToolCallResult, type Telemetry, type TokenUsage, type ToolAnnotations, type ToolArtifact, type ToolArtifactInput, type ToolContext, type ToolDefinition, ToolExposure, type ToolProvider, type ToolResult, type Translate, type TranslateVars, type TrustExecGrant, type TrustGrant, type TrustLevel, type TrustManager, type TrustRecord, type TrustScope, type TrustTier, UNLIMITED_TURNS, type VerifyResult, WIRE_ABORT_FIELDS, WIRE_ABOUT_FIELDS, WIRE_AGENT_ROLE_FIELDS, WIRE_APPROVAL_CACHE_REVOKE_REQUEST_FIELDS, WIRE_APPROVAL_CACHE_REVOKE_RESPONSE_FIELDS, WIRE_APPROVAL_LIST_FIELDS, WIRE_APPROVAL_ROW_FIELDS, WIRE_ARTIFACTS_FIELDS, WIRE_ATTACHMENT_UPLOAD_FIELDS, WIRE_AUDIT_LOG_FIELDS, WIRE_AUDIT_ROW_FIELDS, WIRE_AUTH_COOKIE, WIRE_AUTH_COOKIE_ATTRS, WIRE_AUTH_TOKEN_PARAM, WIRE_BACKGROUND_TASK_FIELDS, WIRE_BLOCKED_GOALS_FIELDS, WIRE_BLOCKED_GOAL_FIELDS, WIRE_BLOCKED_LEVEL_FIELDS, WIRE_BUILTIN_CONNECTOR_FIELDS, WIRE_CACHED_APPROVAL_FIELDS, WIRE_CAPABILITIES_FIELDS, WIRE_CAPABILITY_PROJECT_FIELDS, WIRE_CHECKPOINT_LIST_FIELDS, WIRE_CHECKPOINT_SUMMARY_FIELDS, WIRE_COMMANDS_FIELDS, WIRE_COMMAND_EXPANSION_FIELDS, WIRE_COMPACT_FIELDS, WIRE_COMPRESSION_LINE_FIELDS, WIRE_CONFIG_FIELDS, WIRE_CONTEXT_FIELDS, WIRE_CREATE_SESSION_FIELDS, WIRE_CREATE_WORKSPACE_FIELDS, WIRE_CREATE_WORKSPACE_RESPONSE_FIELDS, WIRE_CUSTOM_COMMAND_FIELDS, WIRE_DELETE_SESSION_FIELDS, WIRE_DIFF_FILE_FIELDS, WIRE_ERROR_FIELDS, WIRE_FILE_CANDIDATES_FIELDS, WIRE_FILE_CANDIDATE_FIELDS, WIRE_FILE_CHANGE_FIELDS, WIRE_FILE_OPEN_RESPONSE_FIELDS, WIRE_FILE_REFERENCE_FIELDS, WIRE_FILE_STAT_MAX, WIRE_FILE_STAT_OK_FIELDS, WIRE_FILE_STAT_REFUSED_FIELDS, WIRE_FILE_STAT_RESPONSE_FIELDS, WIRE_FILE_TEXT_RESPONSE_FIELDS, WIRE_FORGET_WORKSPACE_FIELDS, WIRE_FORGET_WORKSPACE_RESPONSE_FIELDS, WIRE_GOAL_ACTIONS, WIRE_GOAL_BLOCK_FIELDS, WIRE_GOAL_CLEAR_FIELDS, WIRE_GOAL_CREATE_FIELDS, WIRE_GOAL_FIELDS, WIRE_GOAL_LIMITS_FIELDS, WIRE_GOAL_PHASES, WIRE_GOAL_REFUSALS, WIRE_GOAL_RESPONSE_FIELDS, WIRE_GOAL_WRITE_FIELDS, WIRE_HEALTH_FIELDS, WIRE_IMAGE_REFERENCE_FIELDS, WIRE_KNOWN_WORKSPACE_FIELDS, WIRE_LANG_PARAM, WIRE_LAST_SESSION_FIELDS, WIRE_LAST_SESSION_RESPONSE_FIELDS, WIRE_MANAGED_LOCK_FIELDS, WIRE_MCP_ADD_FIELDS, WIRE_MCP_ADD_RESPONSE_FIELDS, WIRE_MCP_APPLY_ENTRY_FIELDS, WIRE_MCP_APPLY_RESPONSE_FIELDS, WIRE_MCP_CONFIG_APPLY_FIELDS, WIRE_MCP_CONFIG_FIELDS, WIRE_MCP_CONFIG_ISSUE_FIELDS, WIRE_MCP_CONFIG_SAVE_FIELDS, WIRE_MCP_CONFIG_SAVE_RESPONSE_FIELDS, WIRE_MCP_CONNECTOR_FIELDS, WIRE_MCP_RECONNECT_FIELDS, WIRE_MESSAGE_LIST_FIELDS, WIRE_MODEL_FIELDS, WIRE_MODEL_SELECTION_FIELDS, WIRE_MODEL_SET_FIELDS, WIRE_MODEL_SUGGESTIONS_FIELDS, WIRE_PATCH_SESSION_FIELDS, WIRE_PATCH_SESSION_RESPONSE_FIELDS, WIRE_PERMISSION_RULE_FIELDS, WIRE_PERMISSION_SET_REQUEST_FIELDS, WIRE_PERMISSION_SET_RESPONSE_FIELDS, WIRE_PERMISSION_SHADOW_FIELDS, WIRE_PERMISSION_STATE_FIELDS, WIRE_PERMISSION_STATUS_FIELDS, WIRE_PLAN_ACTIONS, WIRE_PLAN_FIELDS, WIRE_PLAN_MODE_REQUEST_FIELDS, WIRE_PLAN_MODE_RESPONSE_FIELDS, WIRE_PLAN_MODE_STATE_FIELDS, WIRE_PLUGINS_FIELDS, WIRE_PLUGIN_ACTION_FIELDS, WIRE_PLUGIN_ARCHIVE_SUFFIXES, WIRE_PLUGIN_INSTALL_FIELDS, WIRE_PLUGIN_LOCAL_FIELDS, WIRE_PLUGIN_LOCAL_INSTALL_FIELDS, WIRE_PLUGIN_MARKETPLACE_FIELDS, WIRE_PLUGIN_MARKETPLACE_RESPONSE_FIELDS, WIRE_PLUGIN_NAME_FIELDS, WIRE_PLUGIN_PREVIEW_FIELDS, WIRE_PLUGIN_PREVIEW_RESPONSE_FIELDS, WIRE_PLUGIN_REFRESH_RESPONSE_FIELDS, WIRE_PLUGIN_STAGE_FIELDS, WIRE_PLUGIN_STAGE_RESPONSE_FIELDS, WIRE_PLUGIN_UPDATE_FIELDS, WIRE_PLUGIN_UPLOAD_CONFIRM_FIELDS, WIRE_PLUGIN_UPLOAD_FIELDS, WIRE_PLUGIN_UPLOAD_FORM_FIELDS, WIRE_PLUGIN_UPLOAD_PREVIEW_RESPONSE_FIELDS, WIRE_PLUGIN_UPLOAD_RESPONSE_FIELDS, WIRE_POLICY_DIR_FIELDS, WIRE_POLICY_STATUS_FIELDS, WIRE_PROJECT_INVENTORY_FIELDS, WIRE_PROVIDERS_FIELDS, WIRE_PROVIDER_KEY_FIELDS, WIRE_PROVIDER_MODELS_FIELDS, WIRE_PROVIDER_OPTION_FIELDS, WIRE_QUESTION_LIST_FIELDS, WIRE_QUESTION_ROW_FIELDS, WIRE_RESPOND_APPROVAL_FIELDS, WIRE_RESPOND_APPROVAL_RESPONSE_FIELDS, WIRE_RESPOND_QUESTION_FIELDS, WIRE_RESPOND_QUESTION_RESPONSE_FIELDS, WIRE_REWIND_FILE_PLAN_FIELDS, WIRE_REWIND_OUTCOME_FIELDS, WIRE_REWIND_PREVIEW_FIELDS, WIRE_REWIND_REQUEST_FIELDS, WIRE_REWIND_RESPONSE_FIELDS, WIRE_REWIND_SCOPES, WIRE_ROLE_ADD_FIELDS, WIRE_ROLE_ADD_RESPONSE_FIELDS, WIRE_RUNNING_SCHEDULE_FIELDS, WIRE_SANDBOX_STATUS_FIELDS, WIRE_SCHEDULE_CAPABILITY_FIELDS, WIRE_SCHEDULE_CREATE_FIELDS, WIRE_SCHEDULE_DEFAULTS_FIELDS, WIRE_SCHEDULE_DELETE_FIELDS, WIRE_SCHEDULE_FIELDS, WIRE_SCHEDULE_FIX_FIELDS, WIRE_SCHEDULE_FIX_REQUEST_FIELDS, WIRE_SCHEDULE_ISSUE_CODES, WIRE_SCHEDULE_LIST_FIELDS, WIRE_SCHEDULE_PENDING_FIELDS, WIRE_SCHEDULE_RECORDING_FIELDS, WIRE_SCHEDULE_ROW_FIELDS, WIRE_SCHEDULE_RUNNING_FIELDS, WIRE_SCHEDULE_RUNS_FIELDS, WIRE_SCHEDULE_RUN_FIELDS, WIRE_SCHEDULE_SAVE_FIELDS, WIRE_SECURITY_FIELDS, WIRE_SECURITY_WORKSPACE_FIELDS, WIRE_SEND_MESSAGE_FIELDS, WIRE_SEND_MESSAGE_RESPONSE_FIELDS, WIRE_SESSION_CANDIDATES_FIELDS, WIRE_SESSION_CANDIDATE_FIELDS, WIRE_SESSION_FINISH_FIELDS, WIRE_SESSION_LIST_FIELDS, WIRE_SESSION_REFERENCE_FIELDS, WIRE_SESSION_RESPONSE_FIELDS, WIRE_SESSION_SUMMARY_FIELDS, WIRE_SESSION_WORKSPACE_FIELDS, WIRE_SESSION_WORKSPACE_RESPONSE_FIELDS, WIRE_SETTINGS_FIELDS, WIRE_SETTINGS_WRITE_FIELDS, WIRE_SETTINGS_WRITE_REQUEST_FIELDS, WIRE_SETTING_ROW_FIELDS, WIRE_SETTING_STEP_FIELDS, WIRE_SETTING_WRITE_FIELDS, WIRE_SETTING_WRITE_LAYERS, WIRE_SKILL_BODY_FIELDS, WIRE_SKILL_DROP_SUFFIXES, WIRE_SKILL_FIELDS, WIRE_SKILL_IMPORT_FIELDS, WIRE_SKILL_IMPORT_PREVIEW_FIELDS, WIRE_SKILL_REMOVE_FIELDS, WIRE_SKILL_STAGE_FIELDS, WIRE_TASKS_FIELDS, WIRE_TOOLS_FIELDS, WIRE_TOOL_GATE_FIELDS, WIRE_TOOL_ROW_FIELDS, WIRE_TRUST_REQUEST_FIELDS, WIRE_TRUST_REQUEST_RESPONSE_FIELDS, WIRE_WORKSPACE_DIFF_FIELDS, WIRE_WORKSPACE_DIRS_FIELDS, WIRE_WORKSPACE_DIR_ENTRY_FIELDS, WIRE_WORKSPACE_REF_FIELDS, type WireAbortResponse, type WireAbout, type WireAgentEnvelope, type WireAgentEvent, type WireAgentRoleSummary, type WireApprovalCacheRevokeRequest, type WireApprovalCacheRevokeResponse, type WireApprovalListResponse, type WireApprovalRequest, type WireArtifactsResponse, type WireAttachmentUploadResponse, type WireAuditCode, type WireAuditLog, type WireAuditOutcome, type WireAuditRow, type WireAuthDenyReason, type WireAuthDenyStatus, type WireAuthGuard, type WireAuthRequestView, type WireAuthVerdict, type WireBackgroundTask, type WireBindWorkspaceRequest, type WireBlockedGoal, type WireBlockedGoalsResponse, type WireBlockedLevel, type WireBuiltinConnector, type WireCachedApproval, type WireCachedDecision, type WireCapabilitiesResponse, type WireCapabilityProject, type WireCheckpointListResponse, type WireCheckpointSummary, type WireCommandExpansion, type WireCommandsResponse, type WireCompactRequest, type WireCompactResponse, type WireCompressionLine, type WireConfigResponse, type WireContextResponse, type WireCreateSessionRequest, type WireCreateSessionResponse, type WireCreateWorkspaceRequest, type WireCreateWorkspaceResponse, type WireCustomCommand, type WireDeleteSessionResponse, type WireDiffFile, type WireDiffNote, type WireDiffOmitReason, type WireDiffSource, type WireDiffStatus, type WireEnvelope, type WireErrorResponse, type WireEvent, type WireFields, type WireFileCandidate, type WireFileCandidatesResponse, type WireFileChange, type WireFileKind, type WireFileOpenRefusal, type WireFileOpenResponse, type WireFileReference, type WireFileRefusal, type WireFileStat, type WireFileStatOk, type WireFileStatRefused, type WireFileStatResponse, type WireFileTextResponse, type WireFixture, type WireFixtureCase, type WireForgetWorkspaceRequest, type WireForgetWorkspaceResponse, type WireGoal, type WireGoalBlock, type WireGoalClearResponse, type WireGoalCreateRequest, type WireGoalLimits, type WireGoalPhase, type WireGoalRefusal, type WireGoalResponse, type WireGoalUpdateRequest, type WireGoalWriteResponse, type WireHealthResponse, type WireHubEnvelope, type WireHubEvent, type WireImageReference, type WireKnownWorkspace, type WireKnownWorkspaceRef, type WireLastSessionRequest, type WireLastSessionResponse, type WireManagedLock, type WireMcpAddRequest, type WireMcpAddResponse, type WireMcpApplyAction, type WireMcpApplyEntry, type WireMcpApplyResponse, type WireMcpConfigApplyRequest, type WireMcpConfigIssue, type WireMcpConfigResponse, type WireMcpConfigSaveRequest, type WireMcpConfigSaveResponse, type WireMcpConnector, type WireMcpReconnectResponse, type WireMessageListResponse, type WireModelCaveat, type WireModelProbeStatus, type WireModelRejection, type WireModelResponse, type WireModelSelection, type WireModelSetRequest, type WireModelSetResponse, type WireModelSource, type WireModelSuggestions, type WirePatchSessionRequest, type WirePatchSessionResponse, type WirePermissionRememberFailure, type WirePermissionRuleRow, type WirePermissionSetRequest, type WirePermissionSetResponse, type WirePermissionShadow, type WirePermissionState, type WirePermissionStatus, type WirePickDirectoryResponse, type WirePlanAction, type WirePlanModeRequest, type WirePlanModeResponse, type WirePlanModeState, type WirePlanResponse, type WirePluginActionResponse, type WirePluginCounts, type WirePluginEntry, type WirePluginHit, type WirePluginHookTally, type WirePluginInstallRequest, type WirePluginLocalInstallRequest, type WirePluginLocalRequest, type WirePluginMarketplace, type WirePluginMarketplaceRequest, type WirePluginMarketplaceResponse, type WirePluginNameRequest, type WirePluginPreview, type WirePluginPreviewRequest, type WirePluginPreviewResponse, type WirePluginRefreshResponse, type WirePluginRefuseReason, type WirePluginSourceType, type WirePluginStageRequest, type WirePluginStageResponse, type WirePluginStatus, type WirePluginUpdateRequest, type WirePluginUploadChoice, type WirePluginUploadConfirmRequest, type WirePluginUploadField, type WirePluginUploadFieldName, type WirePluginUploadFields, type WirePluginUploadFile, type WirePluginUploadForm, type WirePluginUploadPlan, type WirePluginUploadPreviewResponse, type WirePluginUploadRequest, type WirePluginUploadResponse, type WirePluginVisibility, type WirePluginsResponse, type WirePolicyDir, type WirePolicyStatus, type WireProjectInventory, type WireProviderKeyRequest, type WireProviderKeyResponse, type WireProviderModelsRequest, type WireProviderModelsResponse, type WireProviderOption, type WireProviderSummary, type WireProvidersResponse, type WireQuestionListResponse, type WireQuestionRequest, type WireReplayMessage, type WireResetReason, type WireRespondApprovalRequest, type WireRespondApprovalResponse, type WireRespondQuestionRequest, type WireRespondQuestionResponse, type WireRewindAction, type WireRewindDrift, type WireRewindFilePlan, type WireRewindOutcome, type WireRewindPreview, type WireRewindRequest, type WireRewindResponse, type WireRewindScope, type WireRoleAddRequest, type WireRoleAddResponse, type WireRunningSchedule, type WireSandboxReason, type WireSandboxStatus, type WireScheduleCapability, type WireScheduleCreateRequest, type WireScheduleDefaults, type WireScheduleDeleteResponse, type WireScheduleFixRequest, type WireScheduleFixResponse, type WireScheduleIssue, type WireScheduleIssueCode, type WireScheduleListResponse, type WireSchedulePendingResponse, type WireScheduleRecordingResponse, type WireScheduleRegisterRefusal, type WireScheduleRegisterWarning, type WireScheduleRegistration, type WireScheduleResponse, type WireScheduleRow, type WireScheduleRunResponse, type WireScheduleRunningResponse, type WireScheduleRunsResponse, type WireScheduleSaveResponse, type WireScheduleUpdateRequest, type WireSecurityResponse, type WireSecurityWorkspace, type WireSendMessageRequest, type WireSendMessageResponse, type WireSessionCandidate, type WireSessionCandidatesResponse, type WireSessionFinish, type WireSessionListResponse, type WireSessionReference, type WireSessionResponse, type WireSessionSummary, type WireSessionWorkspace, type WireSessionWorkspaceResponse, type WireSettingApply, type WireSettingFutile, type WireSettingLayer, type WireSettingRow, type WireSettingStep, type WireSettingValue, type WireSettingValueKind, type WireSettingWrite, type WireSettingWriteLayer, type WireSettingsResponse, type WireSettingsWriteRequest, type WireSettingsWriteResponse, type WireSkillBodyResponse, type WireSkillImportConflict, type WireSkillImportEntry, type WireSkillImportFailure, type WireSkillImportForm, type WireSkillImportIssue, type WireSkillImportPreviewResponse, type WireSkillImportResponse, type WireSkillRemoveFailure, type WireSkillRemoveResponse, type WireSkillStageFailure, type WireSkillStageResponse, type WireSkillSummary, type WireSummaryWorkspace, type WireTaggedEvent, type WireTasksResponse, type WireToolGate, type WireToolGateAxis, type WireToolRow, type WireToolSummary, type WireToolVerdict, type WireToolsResponse, type WireTrustRequestRequest, type WireTrustRequestResponse, type WireTurnState, type WireWorkspaceBinding, type WireWorkspaceDiffResponse, type WireWorkspaceDirEntry, type WireWorkspaceDirsResponse, type WireWorkspaceRef, apiKeyEnvVar, assertNeverPart, assistantTurnText, attachSessionSurface, chordId, collectPendingApprovals, compressionThresholdTokens, conformsToWire, contentToText, diagnosticToLine, extractAllMentions, extractMentions, extractSessionMentions, filePartSummary, flattenCatalog, formatMoney, getProviderInfo, hasFailure, imagePartOmittedSummary, isApprovalOutcome, isContextNearlyFull, isCurrency, isHeadlessInputFormat, isHeadlessLifecycleEvent, isHeadlessOutputFormat, isKeyAction, isLang, isMentionableFilePath, isOperationType, isPermissionLevel, isPlanOutcome, isPromptOversize, isProviderType, isQuestionAnswerMap, isSearchProviderType, isValidAgentRoleName, isValidCommandName, isWireGoalPhase, isWireHubEvent, isWirePlanAction, isWirePluginArchiveName, isWireRewindScope, isWireSettingWriteLayer, isWireSkillDropName, makeTranslate, mcpConnectorState, normalizeApproval, packSessionSurface, parseChord, parseModelRef, parseSequence, perAction, placeholdersOf, promptTokens, resolveHostText, sequenceId, sessionPartSummary, stripSystemNote, systemNote, tableOf, totalUsageTokens, translatorFor, truncateToBudget, turnDigest, unfixedRules, utf8ByteLength, wireFields };
+export { ACTION_CONTEXTS, AGENT_ROLE_NAME_PATTERN, API_KEY_ENV_VARS, APPROVAL_OUTCOMES, type ActiveAgentRole, type AgentEvent, type AgentEventOf, type AgentEventType, type AgentRole, type AgentRoleScope, type AgentRoleSource, type ApprovalAnswer, type ApprovalOutcome, type ApprovalReply, type ApprovalRequest, type ArtifactKind, type AttributeValue, type Attributes, type BackgroundTaskInfo, type BackgroundTaskKind, type BackgroundTaskStatus, type BlankCard, type BlankGreeting, type BoundKey, type BudgetBreach, COMMAND_NAME_PATTERN, COMPLIANCE_ACTIONS, COMPLIANCE_CATEGORIES, CURRENCIES, type Catalogs, type ComplianceAction, type ComplianceCategory, type ContextBreakdown, type ContextSegment, type Currency, type CurrencyDisplay, type CustomCommandDef, type CustomCommandSource, DEFAULT_AGENT_ROLE, DEFAULT_LANG, type DecidedTrustLevel, type Diagnostic, DiagnosticSink, type DiagnosticStatus, type EpochConfig, type EpochContentPart, type EpochFilePart, type EpochHook, type EpochImagePart, type EpochMessage, type EpochMessageRole, type EpochPlugin, type EpochSessionPart, type EpochSkill, type EpochTextPart, type EpochTool, type EpochToolCall, type EpochToolResult, type EpochTurnFacts, type EpochUserContent, type ExpandedCommand, type FileOmitReason, type FinishReason, type FixableApproval, type FlatCatalog, type FormatMoneyOptions, GEN_AI, HEADLESS_INPUT_EVENT_TYPES, HEADLESS_INPUT_FORMATS, HEADLESS_OUTPUT_FORMATS, HEADLESS_PROTOCOL_VERSION, type HeadlessEnvelope, type HeadlessEvent, type HeadlessInit, type HeadlessInputEvent, type HeadlessInputEventType, type HeadlessInputFormat, type HeadlessLifecycleEvent, type HeadlessOutputFormat, type HeadlessResult, type HeadlessResultReason, type HookContext, type HookEvent, type HookHandler, type HookManager, type HookRegistration, type HookType, type HostText, type HostUser, type JsonSchema, KEY_ACTIONS, type KeyAction, type KeyChord, type KeyContext, type KeySequence, type KeybindingReport, type KeybindingSource, type KeybindingTable, LANGS, type Lang, type LocalizedDetail, type LogFn, MAX_ATTACH_BYTES, MAX_ATTACH_FILES, MAX_ATTACH_TOTAL_BYTES, MAX_HEADER_CHARS, MAX_OPTIONS, MAX_QUESTIONS, MAX_SESSION_ATTACH_BYTES, MAX_SESSION_REFS, MCP_DATA_KEY_NAME, METRIC, MIN_OPTIONS, type MentionSet, type ModelRef, type ModelSelection, type ModelSelectionOrigin, type MoneyDigits, NOOP_TELEMETRY, type NoticeCode, OPERATION_TYPES, OVERSIZE_RATIO, type Operation, type OperationType, PERMISSION_LEVELS, PLAN_OUTCOMES, PROVIDER_INFOS, PROVIDER_TYPES, type PermissionDecision, type PermissionLevel, type PermissionManager, type PermissionRuleLists, type PlanApprovalOutcome, type PlanProposal, type PluginContext, type ProviderInfo, type ProviderType, type QuestionAnswer, type QuestionItem, type QuestionOption, type QuestionRequest, RESERVED_CHORDS, RESERVED_COMMAND_NAMES, type RejectReason, type RejectedKey, type RuleValue, SCHEDULE_DRAFT_TOOL, SCHEDULE_INTERVAL_MINUTES, SCHEDULE_RUN_STATUSES, SCHEDULE_TEMPLATES, SEARCH_API_KEY_ENV, SEARCH_PROVIDER_TYPES, SECRET_SERVICE, SEQUENCE_CONTEXTS, SESSION_MENTION_PREFIX, SESSION_REFERENCE_ERROR_CODES, SHELL_KINDS, SIDEBAR_MENU_MESSAGE_TYPE, SIMULTANEOUS_CONTEXTS, SYSTEM_NOTE_PREFIX, type ScheduleAllowlist, type ScheduleBackendKind, type ScheduleCycle, type ScheduleDefinition, type ScheduleDraft, type ScheduleDraftAllowlist, type ScheduleDraftCreate, type ScheduleDraftPermission, type ScheduleDraftUpdate, type SchedulePendingApproval, type SchedulePendingItem, type ScheduleRun, type ScheduleRunStatus, type ScheduleRunnerSpec, type ScheduleTemplate, type ScheduleTemplateId, type ScheduleTrigger, type ScheduleTriggerKind, type ScheduleWeekday, type ScheduleWideningKind, type SearchProviderType, type SecretBackendId, type SecretStore, type SelectionContext, type SelectionRejection, type SelectionWarning, type SessionAttachKind, type SessionAttachResult, type SessionOmitReason, type SessionSurfaceMessage, type SessionSurfaceView, type SetSelectionResult, type ShellKind, type SidebarMenuItem, type SidebarMenuMessage, type SpanLike, type SubToolCall, type SubToolCallResult, type Telemetry, type TokenUsage, type ToolAnnotations, type ToolArtifact, type ToolArtifactInput, type ToolContext, type ToolDefinition, ToolExposure, type ToolProvider, type ToolResult, type Translate, type TranslateVars, type TrustExecGrant, type TrustGrant, type TrustLevel, type TrustManager, type TrustRecord, type TrustScope, type TrustTier, UNLIMITED_TURNS, type VerifyResult, WIRE_ABORT_FIELDS, WIRE_ABOUT_FIELDS, WIRE_AGENT_ROLE_FIELDS, WIRE_APPROVAL_CACHE_REVOKE_REQUEST_FIELDS, WIRE_APPROVAL_CACHE_REVOKE_RESPONSE_FIELDS, WIRE_APPROVAL_LIST_FIELDS, WIRE_APPROVAL_ROW_FIELDS, WIRE_ARTIFACTS_FIELDS, WIRE_ATTACHMENT_UPLOAD_FIELDS, WIRE_AUDIT_LOG_FIELDS, WIRE_AUDIT_ROW_FIELDS, WIRE_AUTH_COOKIE, WIRE_AUTH_COOKIE_ATTRS, WIRE_AUTH_TOKEN_PARAM, WIRE_BACKGROUND_TASK_FIELDS, WIRE_BLOCKED_GOALS_FIELDS, WIRE_BLOCKED_GOAL_FIELDS, WIRE_BLOCKED_LEVEL_FIELDS, WIRE_BUILTIN_CONNECTOR_FIELDS, WIRE_CACHED_APPROVAL_FIELDS, WIRE_CAPABILITIES_FIELDS, WIRE_CAPABILITY_PROJECT_FIELDS, WIRE_CHECKPOINT_LIST_FIELDS, WIRE_CHECKPOINT_SUMMARY_FIELDS, WIRE_COMMANDS_FIELDS, WIRE_COMMAND_EXPANSION_FIELDS, WIRE_COMPACT_FIELDS, WIRE_COMPRESSION_LINE_FIELDS, WIRE_CONFIG_FIELDS, WIRE_CONTEXT_FIELDS, WIRE_CREATE_SESSION_FIELDS, WIRE_CREATE_WORKSPACE_FIELDS, WIRE_CREATE_WORKSPACE_RESPONSE_FIELDS, WIRE_CUSTOM_COMMAND_FIELDS, WIRE_DELETE_SESSION_FIELDS, WIRE_DIFF_FILE_FIELDS, WIRE_ERROR_FIELDS, WIRE_FILE_CANDIDATES_FIELDS, WIRE_FILE_CANDIDATE_FIELDS, WIRE_FILE_CHANGE_FIELDS, WIRE_FILE_OPEN_RESPONSE_FIELDS, WIRE_FILE_REFERENCE_FIELDS, WIRE_FILE_STAT_MAX, WIRE_FILE_STAT_OK_FIELDS, WIRE_FILE_STAT_REFUSED_FIELDS, WIRE_FILE_STAT_RESPONSE_FIELDS, WIRE_FILE_TEXT_RESPONSE_FIELDS, WIRE_FORGET_WORKSPACE_FIELDS, WIRE_FORGET_WORKSPACE_RESPONSE_FIELDS, WIRE_GOAL_ACTIONS, WIRE_GOAL_BLOCK_FIELDS, WIRE_GOAL_CLEAR_FIELDS, WIRE_GOAL_CREATE_FIELDS, WIRE_GOAL_FIELDS, WIRE_GOAL_LIMITS_FIELDS, WIRE_GOAL_PHASES, WIRE_GOAL_REFUSALS, WIRE_GOAL_RESPONSE_FIELDS, WIRE_GOAL_WRITE_FIELDS, WIRE_HEALTH_FIELDS, WIRE_IMAGE_REFERENCE_FIELDS, WIRE_KNOWN_WORKSPACE_FIELDS, WIRE_LANG_PARAM, WIRE_LAST_SESSION_FIELDS, WIRE_LAST_SESSION_RESPONSE_FIELDS, WIRE_MANAGED_LOCK_FIELDS, WIRE_MCP_ADD_FIELDS, WIRE_MCP_ADD_RESPONSE_FIELDS, WIRE_MCP_APPLY_ENTRY_FIELDS, WIRE_MCP_APPLY_RESPONSE_FIELDS, WIRE_MCP_CONFIG_APPLY_FIELDS, WIRE_MCP_CONFIG_FIELDS, WIRE_MCP_CONFIG_ISSUE_FIELDS, WIRE_MCP_CONFIG_SAVE_FIELDS, WIRE_MCP_CONFIG_SAVE_RESPONSE_FIELDS, WIRE_MCP_CONNECTOR_FIELDS, WIRE_MCP_RECONNECT_FIELDS, WIRE_MESSAGE_LIST_FIELDS, WIRE_MODEL_FIELDS, WIRE_MODEL_SELECTION_FIELDS, WIRE_MODEL_SET_FIELDS, WIRE_MODEL_SUGGESTIONS_FIELDS, WIRE_PATCH_SESSION_FIELDS, WIRE_PATCH_SESSION_RESPONSE_FIELDS, WIRE_PERMISSION_RULE_FIELDS, WIRE_PERMISSION_SET_REQUEST_FIELDS, WIRE_PERMISSION_SET_RESPONSE_FIELDS, WIRE_PERMISSION_SHADOW_FIELDS, WIRE_PERMISSION_STATE_FIELDS, WIRE_PERMISSION_STATUS_FIELDS, WIRE_PLAN_ACTIONS, WIRE_PLAN_FIELDS, WIRE_PLAN_MODE_REQUEST_FIELDS, WIRE_PLAN_MODE_RESPONSE_FIELDS, WIRE_PLAN_MODE_STATE_FIELDS, WIRE_PLUGINS_FIELDS, WIRE_PLUGIN_ACTION_FIELDS, WIRE_PLUGIN_ARCHIVE_SUFFIXES, WIRE_PLUGIN_INSTALL_FIELDS, WIRE_PLUGIN_LOCAL_FIELDS, WIRE_PLUGIN_LOCAL_INSTALL_FIELDS, WIRE_PLUGIN_MARKETPLACE_FIELDS, WIRE_PLUGIN_MARKETPLACE_RESPONSE_FIELDS, WIRE_PLUGIN_NAME_FIELDS, WIRE_PLUGIN_PREVIEW_FIELDS, WIRE_PLUGIN_PREVIEW_RESPONSE_FIELDS, WIRE_PLUGIN_REFRESH_RESPONSE_FIELDS, WIRE_PLUGIN_STAGE_FIELDS, WIRE_PLUGIN_STAGE_RESPONSE_FIELDS, WIRE_PLUGIN_UPDATE_FIELDS, WIRE_PLUGIN_UPLOAD_CONFIRM_FIELDS, WIRE_PLUGIN_UPLOAD_FIELDS, WIRE_PLUGIN_UPLOAD_FORM_FIELDS, WIRE_PLUGIN_UPLOAD_PREVIEW_RESPONSE_FIELDS, WIRE_PLUGIN_UPLOAD_RESPONSE_FIELDS, WIRE_POLICY_DIR_FIELDS, WIRE_POLICY_STATUS_FIELDS, WIRE_PROJECT_INVENTORY_FIELDS, WIRE_PROVIDERS_FIELDS, WIRE_PROVIDER_KEY_FIELDS, WIRE_PROVIDER_MODELS_FIELDS, WIRE_PROVIDER_OPTION_FIELDS, WIRE_QUESTION_LIST_FIELDS, WIRE_QUESTION_ROW_FIELDS, WIRE_RESPOND_APPROVAL_FIELDS, WIRE_RESPOND_APPROVAL_RESPONSE_FIELDS, WIRE_RESPOND_QUESTION_FIELDS, WIRE_RESPOND_QUESTION_RESPONSE_FIELDS, WIRE_REWIND_FILE_PLAN_FIELDS, WIRE_REWIND_OUTCOME_FIELDS, WIRE_REWIND_PREVIEW_FIELDS, WIRE_REWIND_REQUEST_FIELDS, WIRE_REWIND_RESPONSE_FIELDS, WIRE_REWIND_SCOPES, WIRE_ROLE_ADD_FIELDS, WIRE_ROLE_ADD_RESPONSE_FIELDS, WIRE_ROLE_REMOVE_FIELDS, WIRE_RUNNING_SCHEDULE_FIELDS, WIRE_SANDBOX_STATUS_FIELDS, WIRE_SCHEDULE_CAPABILITY_FIELDS, WIRE_SCHEDULE_CREATE_FIELDS, WIRE_SCHEDULE_DEFAULTS_FIELDS, WIRE_SCHEDULE_DELETE_FIELDS, WIRE_SCHEDULE_FIELDS, WIRE_SCHEDULE_FIX_FIELDS, WIRE_SCHEDULE_FIX_REQUEST_FIELDS, WIRE_SCHEDULE_ISSUE_CODES, WIRE_SCHEDULE_LIST_FIELDS, WIRE_SCHEDULE_PENDING_FIELDS, WIRE_SCHEDULE_RECORDING_FIELDS, WIRE_SCHEDULE_ROW_FIELDS, WIRE_SCHEDULE_RUNNING_FIELDS, WIRE_SCHEDULE_RUNS_FIELDS, WIRE_SCHEDULE_RUN_FIELDS, WIRE_SCHEDULE_SAVE_FIELDS, WIRE_SECURITY_FIELDS, WIRE_SECURITY_WORKSPACE_FIELDS, WIRE_SEND_MESSAGE_FIELDS, WIRE_SEND_MESSAGE_RESPONSE_FIELDS, WIRE_SESSION_CANDIDATES_FIELDS, WIRE_SESSION_CANDIDATE_FIELDS, WIRE_SESSION_FINISH_FIELDS, WIRE_SESSION_LIST_FIELDS, WIRE_SESSION_REFERENCE_FIELDS, WIRE_SESSION_RESPONSE_FIELDS, WIRE_SESSION_SUMMARY_FIELDS, WIRE_SESSION_WORKSPACE_FIELDS, WIRE_SESSION_WORKSPACE_RESPONSE_FIELDS, WIRE_SETTINGS_FIELDS, WIRE_SETTINGS_WRITE_FIELDS, WIRE_SETTINGS_WRITE_REQUEST_FIELDS, WIRE_SETTING_PENDING_FIELDS, WIRE_SETTING_ROW_FIELDS, WIRE_SETTING_STEP_FIELDS, WIRE_SETTING_WRITE_FIELDS, WIRE_SETTING_WRITE_LAYERS, WIRE_SKILL_BODY_FIELDS, WIRE_SKILL_DROP_SUFFIXES, WIRE_SKILL_FIELDS, WIRE_SKILL_IMPORT_FIELDS, WIRE_SKILL_IMPORT_PREVIEW_FIELDS, WIRE_SKILL_REMOVE_FIELDS, WIRE_SKILL_STAGE_FIELDS, WIRE_TASKS_FIELDS, WIRE_TOOLS_FIELDS, WIRE_TOOL_GATE_FIELDS, WIRE_TOOL_ROW_FIELDS, WIRE_TRUST_REQUEST_FIELDS, WIRE_TRUST_REQUEST_RESPONSE_FIELDS, WIRE_WORKSPACE_DIFF_FIELDS, WIRE_WORKSPACE_DIRS_FIELDS, WIRE_WORKSPACE_DIR_ENTRY_FIELDS, WIRE_WORKSPACE_REF_FIELDS, type WireAbortResponse, type WireAbout, type WireAgentEnvelope, type WireAgentEvent, type WireAgentRoleSummary, type WireApprovalCacheRevokeRequest, type WireApprovalCacheRevokeResponse, type WireApprovalListResponse, type WireApprovalRequest, type WireArtifactsResponse, type WireAttachmentUploadResponse, type WireAuditCode, type WireAuditLog, type WireAuditOutcome, type WireAuditRow, type WireAuthDenyReason, type WireAuthDenyStatus, type WireAuthGuard, type WireAuthRequestView, type WireAuthVerdict, type WireBackgroundTask, type WireBindWorkspaceRequest, type WireBlockedGoal, type WireBlockedGoalsResponse, type WireBlockedLevel, type WireBuiltinConnector, type WireCachedApproval, type WireCachedDecision, type WireCapabilitiesResponse, type WireCapabilityProject, type WireCheckpointListResponse, type WireCheckpointSummary, type WireCommandExpansion, type WireCommandsResponse, type WireCompactRequest, type WireCompactResponse, type WireCompressionLine, type WireConfigResponse, type WireContextResponse, type WireCreateSessionRequest, type WireCreateSessionResponse, type WireCreateWorkspaceRequest, type WireCreateWorkspaceResponse, type WireCustomCommand, type WireDeleteSessionResponse, type WireDiffFile, type WireDiffNote, type WireDiffOmitReason, type WireDiffSource, type WireDiffStatus, type WireEnvelope, type WireErrorResponse, type WireEvent, type WireFields, type WireFileCandidate, type WireFileCandidatesResponse, type WireFileChange, type WireFileKind, type WireFileOpenRefusal, type WireFileOpenResponse, type WireFileReference, type WireFileRefusal, type WireFileStat, type WireFileStatOk, type WireFileStatRefused, type WireFileStatResponse, type WireFileTextResponse, type WireFixture, type WireFixtureCase, type WireForgetWorkspaceRequest, type WireForgetWorkspaceResponse, type WireGoal, type WireGoalBlock, type WireGoalClearResponse, type WireGoalCreateRequest, type WireGoalLimits, type WireGoalPhase, type WireGoalRefusal, type WireGoalResponse, type WireGoalUpdateRequest, type WireGoalWriteResponse, type WireHealthResponse, type WireHubEnvelope, type WireHubEvent, type WireImageReference, type WireKnownWorkspace, type WireKnownWorkspaceRef, type WireLastSessionRequest, type WireLastSessionResponse, type WireManagedLock, type WireMcpAddRequest, type WireMcpAddResponse, type WireMcpApplyAction, type WireMcpApplyEntry, type WireMcpApplyResponse, type WireMcpConfigApplyRequest, type WireMcpConfigIssue, type WireMcpConfigResponse, type WireMcpConfigSaveRequest, type WireMcpConfigSaveResponse, type WireMcpConnector, type WireMcpReconnectResponse, type WireMessageListResponse, type WireModelCaveat, type WireModelProbeStatus, type WireModelRejection, type WireModelResponse, type WireModelSelection, type WireModelSetRequest, type WireModelSetResponse, type WireModelSource, type WireModelSuggestions, type WirePatchSessionRequest, type WirePatchSessionResponse, type WirePermissionRememberFailure, type WirePermissionRuleRow, type WirePermissionSetRequest, type WirePermissionSetResponse, type WirePermissionShadow, type WirePermissionState, type WirePermissionStatus, type WirePickDirectoryResponse, type WirePlanAction, type WirePlanModeRequest, type WirePlanModeResponse, type WirePlanModeState, type WirePlanResponse, type WirePluginActionResponse, type WirePluginCounts, type WirePluginEntry, type WirePluginHit, type WirePluginHookTally, type WirePluginInstallRequest, type WirePluginLocalInstallRequest, type WirePluginLocalRequest, type WirePluginMarketplace, type WirePluginMarketplaceRequest, type WirePluginMarketplaceResponse, type WirePluginNameRequest, type WirePluginPreview, type WirePluginPreviewRequest, type WirePluginPreviewResponse, type WirePluginRefreshResponse, type WirePluginRefuseReason, type WirePluginSourceType, type WirePluginStageRequest, type WirePluginStageResponse, type WirePluginStatus, type WirePluginUpdateRequest, type WirePluginUploadChoice, type WirePluginUploadConfirmRequest, type WirePluginUploadField, type WirePluginUploadFieldName, type WirePluginUploadFields, type WirePluginUploadFile, type WirePluginUploadForm, type WirePluginUploadPlan, type WirePluginUploadPreviewResponse, type WirePluginUploadRequest, type WirePluginUploadResponse, type WirePluginVisibility, type WirePluginsResponse, type WirePolicyDir, type WirePolicyStatus, type WireProjectInventory, type WireProviderKeyRequest, type WireProviderKeyResponse, type WireProviderModelsRequest, type WireProviderModelsResponse, type WireProviderOption, type WireProviderSummary, type WireProvidersResponse, type WireQuestionListResponse, type WireQuestionRequest, type WireReplayMessage, type WireResetReason, type WireRespondApprovalRequest, type WireRespondApprovalResponse, type WireRespondQuestionRequest, type WireRespondQuestionResponse, type WireRewindAction, type WireRewindDrift, type WireRewindFilePlan, type WireRewindOutcome, type WireRewindPreview, type WireRewindRequest, type WireRewindResponse, type WireRewindScope, type WireRoleAddRequest, type WireRoleAddResponse, type WireRoleRemoveFailure, type WireRoleRemoveResponse, type WireRunningSchedule, type WireSandboxReason, type WireSandboxStatus, type WireScheduleCapability, type WireScheduleCreateRequest, type WireScheduleDefaults, type WireScheduleDeleteResponse, type WireScheduleFixRequest, type WireScheduleFixResponse, type WireScheduleIssue, type WireScheduleIssueCode, type WireScheduleListResponse, type WireSchedulePendingResponse, type WireScheduleRecordingResponse, type WireScheduleRegisterRefusal, type WireScheduleRegisterWarning, type WireScheduleRegistration, type WireScheduleResponse, type WireScheduleRow, type WireScheduleRunResponse, type WireScheduleRunningResponse, type WireScheduleRunsResponse, type WireScheduleSaveResponse, type WireScheduleUpdateRequest, type WireSecurityResponse, type WireSecurityWorkspace, type WireSendMessageRequest, type WireSendMessageResponse, type WireSessionCandidate, type WireSessionCandidatesResponse, type WireSessionFinish, type WireSessionListResponse, type WireSessionReference, type WireSessionResponse, type WireSessionSummary, type WireSessionWorkspace, type WireSessionWorkspaceResponse, type WireSettingApply, type WireSettingFutile, type WireSettingLayer, type WireSettingPending, type WireSettingRow, type WireSettingStep, type WireSettingValue, type WireSettingValueKind, type WireSettingWrite, type WireSettingWriteLayer, type WireSettingsResponse, type WireSettingsWriteRequest, type WireSettingsWriteResponse, type WireSkillBodyResponse, type WireSkillImportConflict, type WireSkillImportEntry, type WireSkillImportFailure, type WireSkillImportForm, type WireSkillImportIssue, type WireSkillImportPreviewResponse, type WireSkillImportResponse, type WireSkillRemoveFailure, type WireSkillRemoveResponse, type WireSkillStageFailure, type WireSkillStageResponse, type WireSkillSummary, type WireSummaryWorkspace, type WireTaggedEvent, type WireTasksResponse, type WireToolGate, type WireToolGateAxis, type WireToolRow, type WireToolSummary, type WireToolVerdict, type WireToolsResponse, type WireTrustRequestRequest, type WireTrustRequestResponse, type WireTurnState, type WireWorkspaceBinding, type WireWorkspaceDiffResponse, type WireWorkspaceDirEntry, type WireWorkspaceDirsResponse, type WireWorkspaceRef, apiKeyEnvVar, assertNeverPart, assistantTurnText, attachSessionSurface, chordId, collectPendingApprovals, compressionThresholdTokens, conformsToWire, contentToText, diagnosticToLine, extractAllMentions, extractMentions, extractSessionMentions, filePartSummary, flattenCatalog, formatMoney, getProviderInfo, hasFailure, imagePartOmittedSummary, isApprovalOutcome, isContextNearlyFull, isCurrency, isHeadlessInputFormat, isHeadlessLifecycleEvent, isHeadlessOutputFormat, isKeyAction, isLang, isMentionableFilePath, isOperationType, isPermissionLevel, isPlanOutcome, isPromptOversize, isProviderType, isQuestionAnswerMap, isSearchProviderType, isValidAgentRoleName, isValidCommandName, isWireGoalPhase, isWireHubEvent, isWirePlanAction, isWirePluginArchiveName, isWireRewindScope, isWireSettingWriteLayer, isWireSkillDropName, makeTranslate, mcpConnectorState, normalizeApproval, packSessionSurface, parseChord, parseModelRef, parseSequence, perAction, placeholdersOf, promptTokens, resolveHostText, sequenceId, sessionPartSummary, stripSystemNote, systemNote, tableOf, totalUsageTokens, translatorFor, truncateToBudget, turnDigest, unfixedRules, utf8ByteLength, wireFields };