@epoch-agent/protocol 0.10.1 → 0.12.0

package/dist/index.d.ts

@@ -2026,8 +2026,32 @@ 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;
+    /**
+     * 默认权限档。
+     *
+     * ⚠️ **这一格是 `string` 而 `EpochConfigSchema` 那一格是
+     * `z.enum(PERMISSION_LEVELS)`** —— 两边值域对不上，写 `permission: 'yolo'`
+     * 在类型上过得去而运行时会让整份配置退回默认值。
+     *
+     * 2026-09-15 试过把它收成联合（那会让这一格不再撒谎），但收紧之后
+     * `sandbox` 等好几格跟着暴露同族不一致 —— 那是一次独立的收口，不该混在
+     * 「让 build 过」那一笔里。`loader.ts` 那处已经改成用 schema 自己的产出
+     * 当 fallback，所以构建不再卡在这儿。**这条注释是给做那次收口的人留的。**
+     */
     permission: string;
     /**
      * 紧凑权限规则（方案 22）。三张列表，写法是 `terminal(pnpm test:*)`。
@@ -2311,22 +2335,47 @@ interface EpochConfig {
         endpoint?: string;
     };
     /**
-     * web 搜索（方案 37）。**缺省 = 不启用**，`web_search` 工具压根不注册。
+     * web 搜索（方案 37；2026-09-15 改口径）。
      *
-     * 搜索 API 全都要 key、都有配额、都可能被墙 —— 绑死一家等于给用户一个大概率
-     * 不可用的功能。所以做成 provider 化，而且**没配就诚实地没有这个工具**：
-     * 注册一个一调就报错的工具，比不注册更糟（模型会反复试）。
+     * ## 整段不配 = **照样能搜**（这一条 2026-09-15 反过来了）
      *
-     * 不配 `provider` 时会按凭据自动挑：环境里有哪家的 key 就用哪家。
-     * 显式写了就只认那一家 —— 配了却缺 key 时报诊断，不静默回落到别家。
+     * 原来的口径是「没配就诚实地没有这个工具」。它在只看 tavily / brave / searxng
+     * 时是对的（三家都要办账号），但后果是把一个**宿主根本没意识到的漏配**
+     * 变成了「所有终端用户都没有搜索」，而且对模型是静默的 ——
+     * 实测它会改用浏览器抓搜索引擎结果页，把 SEO 广告写进交付物。
+     *
+     * 现在加了两档不用办账号的：`native`（借当前 LLM provider 的能力）和
+     * `keyless`（免费公开端点）。于是缺省状态是**有搜索**，
+     * 而「没有搜索」退化成一个需要显式关掉两档才能到达的用户选择。
+     *
+     * 「配了却缺 key 不回落」那条判据没变：显式写了就只认那一家。
      */
     search?: {
-        /** 用哪家。不给 = 按凭据自动挑（`tavily` → `brave` → `searxng`） */
+        /**
+         * 用哪家。不给 = 按凭据自动挑
+         * （`native` → `tavily` → `brave` → `searxng` → `keyless`）。
+         *
+         * ⚠️ 只设了 `TAVILY_API_KEY` 而没写这一格的人，从 2026-09-15 起会走 `native`
+         * —— 要钉住某一家就把它显式写在这里。
+         */
         provider?: SearchProviderType;
         /** `searxng` 自建实例地址（那一家没有 key，靠它定位） */
         baseUrl?: string;
         /** 一次返回几条，缺省 5。上限 20 —— 再多也超出模型能有效读的范围 */
         maxResults?: number;
+        /**
+         * `native` 档的开关，缺省**开**。
+         *
+         * 关掉的理由通常是成本：那一档一次搜索等于一个完整的模型轮次。
+         */
+        native?: boolean;
+        /**
+         * `keyless` 档的开关，缺省**开**。
+         *
+         * 关掉的理由通常是隐私：那一档会把查询词发给 Exa / Parallel。
+         * 两档都关掉 + 三家都没配 = 回到「没有 `web_search`」那个状态。
+         */
+        keyless?: boolean;
     };
     /**
      * 内容合规过滤（core 的 `compliance/`）。
@@ -2629,16 +2678,53 @@ interface EpochConfig {
          */
         maxTotalBytes?: number;
     };
+    /**
+     * 会话库的保留期清理（方案 64 PR-4）。三格逐字照 hermes 的
+     * `sessions: auto_prune / retention_days / vacuum_after_prune`。
+     *
+     * ## ⚠️ `autoPrune` 缺省 `false`，而这是 hermes 写下的判据不是保守
+     *
+     * 它那段文档逐字说的是：**会话历史是 `session_search` 跨历史召回的燃料**，
+     * 删掉就是削弱 agent 的记忆；数百个会话才 10–15 MB，不值得。开启判据是一个
+     * 具体数字：**约 1000 个会话 / 384 MB 的 state.db** 会让 FTS5 插入和
+     * `/resume` 列表变慢。
+     *
+     * ⚠️ 关掉它**不影响手动那条路**（`epoch sessions prune`）——
+     * 这一格管的只是「要不要在每次启动时自己跑一遍」。
+     */
+    sessions?: {
+        /** 开机时自动清理一次（至多一天一次）。**缺省关** */
+        autoPrune?: boolean;
+        /** 多少天没动过算旧，缺省 90（同 hermes 的 `retention_days`） */
+        retentionDays?: number;
+        /**
+         * 清完之后回收磁盘（`VACUUM`），缺省 `true`。
+         *
+         * ⚠️ **开着也不一定会跑**：还要过「真删掉了东西」「距上次 VACUUM 超过 30 天」
+         * 「空页超过 25%」三道 —— 它要独占整个库文件做全量重写。
+         */
+        vacuumAfterPrune?: boolean;
+    };
 }
-/** 支持的搜索后端。`searxng` 是**自托管无 key**那一档，内网 / 隐私敏感场景的答案 */
-declare const SEARCH_PROVIDER_TYPES: readonly ["tavily", "brave", "searxng"];
+/**
+ * 支持的搜索后端。**三档「不用再办一个账号」的**：
+ *
+ * - `native`  —— 让当前 LLM provider 自己搜（借已有的 provider key）
+ * - `searxng` —— 自托管无 key，内网 / 隐私敏感场景的答案
+ * - `keyless` —— 免费公开端点组成的环，零 key 零服务器
+ */
+declare const SEARCH_PROVIDER_TYPES: readonly ["native", "tavily", "brave", "searxng", "keyless"];
 type SearchProviderType = (typeof SEARCH_PROVIDER_TYPES)[number];
 declare function isSearchProviderType(value: string): value is SearchProviderType;
 /**
- * 各搜索后端的 API key 环境变量名。`searxng` 不需要 key，所以是 null。
+ * 各搜索后端的 API key 环境变量名。不需要**自己的** key 的那几档是 null。
+ *
+ * ⚠️ `native` 是 null **不代表它不要凭据** —— 它借的是 `provider.apiKey`，
+ * 而那把 key 已经在 `PROVIDER_META` 那张表里登记过了。这里再登记一次会让
+ * `API_KEY_ENV_VARS`（凭据预取用的清单）出现重复项。
  *
  * 和 provider 的 `apiKeyEnv` 分开一张表：那张是 LLM provider 的，
- * 混进来会让 `API_KEY_ENV_VARS`（凭据预取用的清单）多出几个不相干的名字。
+ * 混进来会让那份清单多出几个不相干的名字。
  */
 declare const SEARCH_API_KEY_ENV: Record<SearchProviderType, string | null>;
 
@@ -3301,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）。
+ * 结构化提问契约（方案 34）—— 模型遇到分叉时能问一句，而不是瞎猜。
  *
- * ## 发它的是谁，以及为什么非要一条新帧
+ * ## 它和审批是两件事
  *
- * 今天唯一的发射方是 core 的 `AgentLoop`：技能学习器在上一轮收尾之后
- * fire-and-forget 学到了一条技能，而那件事没有任何出口（判据全文在
- * `agent/loop.ts` 的 `maybeLearn()`）。三条现成的路各自被什么挡掉：
+ * 审批问的是「**允不允许**我做这件事」，答案是四个固定出口，且**默认往严的方向落**
+ * （走开 = 拒绝）。提问问的是「**你想要哪一种**」，答案是内容，而且
+ * **没有安全的默认值** —— 替用户挑一个和替他点「允许」一样糟，只是失败的方式不同：
+ * 前者让模型基于一个假答案干半小时活。
  *
- * 1. **`text-delta`** —— 它会被折进 assistant 那一段正文，于是这句话进历史、
- *    进落盘、下一轮再进模型。一句「你学会了 X」被当成模型自己说过的话，
- *    等于往上下文里塞一条它没说过的发言；
- * 2. **往 system prompt 里塞** —— 那是 prompt cache 的前缀，每轮加一句会让整段
- *    对话的缓存逐轮失效。同一条判据 `loop.ts` 里为后台任务通知讲过一遍；
- * 3. **一条 `[系统]` 进历史**（`systemNote()` + `recordNote()`，样板是
- *    `runtime` 的 `markRoleHandoff()`）—— 它是真出口，但那句话**只在刷新 /
- *    回放时看得见**，而且今天只有 web 认那个前缀，TUI 会把 `[系统] ` 原样露出来。
+ * 所以这里刻意**不提供**任何「宿主答不上来时的兜底答案」。答不上来只有一种表达：
+ * `skipped: true`（见 {@link QuestionAnswer}）。
  *
- * ## 为什么是「码 + 已经翻好的话」两个字段
- *
- * `text` 由**发射方**（core，它有 `t()`）翻好：`@epoch-agent/view` 只依赖
- * protocol、够不着 catalog，在那儿兜底就只能是中文 —— 同 `error` 那条空 message
- * 的兜底为什么落在两个宿主身上，是同一条判据。
+ * ## 为什么不过权限层
  *
- * `code` 是给**要分支的宿主**的：判「这是哪一类通知」不许去 `includes()` 那句
- * 随时会改的话（RECORD-40-i18n §32.1 那条 `reason === '已取消'` 的教训）。
+ * 提问不碰文件、不起进程、不联网。方案 34 §三把 `core/src/permission/**`
+ * 列进禁止触碰，就是这个意思 —— 给它加一道权限判定，等于让 `deny` 规则能把
+ * 「问一句」拦掉，而拦掉的表现是模型继续瞎猜。
+ */
+/** 一个选项。**没有「其他」** —— 自由输入由宿主自动提供，不占模型的选项额度 */
+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;
+}
+/**
+ * 一次结构化提问。
  *
- * ⚠️ **要拿技能名去做别的事**（跳到能力页、打开那份 SKILL.md），就再加一个
- * 字段，别去正则 `text` —— 那句话是会随文案改的。
+ * **刻意没有 `requestId`**（方案初稿里有）。跨进程时的凭据由
+ * `runtime/src/serialize.ts` 的 `toSerializable()` 生成，和 `approval-request`
+ * 逐字同构 —— 请求内容里再带一个 id 的话，进程内的宿主（TUI）手上会有一个
+ * 它永远不用的字段，而跨进程那侧有两个候选 id，对不齐时没人说得清该信哪个。
  */
- | {
-    type: 'notice';
-    code: NoticeCode;
-    text: string;
+interface QuestionRequest {
+    /** 一次最多 {@link MAX_QUESTIONS} 个问题（超过就该拆成两轮对话了） */
+    questions: QuestionItem[];
 }
-/** 运行中出错（随后会有一个 finish: 'error'） */
- | {
-    type: 'error';
-    message: string;
-};
 /**
- * 一条 `notice` 是哪一类。
+ * 宿主的答复。
  *
- * 写成联合而不是 `string`，是为了让**加一档时消费方的 switch 会红** ——
- * 判据同 wire.ts 的 `WireResetReason`。
+ * `answers` 的键是 {@link QuestionItem.question} 原文 —— 不是下标。模型写出问句
+ * 的时候就知道自己在问什么，拿问句当键它读答案不用再对一次序；而下标一旦和
+ * 宿主的呈现顺序错开（多问题逐个走完再一起回），错位是静默的。
  *
- * ⚠️ 这里原来写着「今天只有一种」—— 那句话在写下之后就一直在过期
- * （`images-dropped` / `compliance-masked` / `response-truncated` 陆续进来）。
- * 有几种去数下面这个联合，别在散文里再抄一个会骗人的数字。
+ * `skipped` 是方案 §2.4 那条「用户 Esc → 模型自己决定，整轮不失败」在类型上的
+ * 落点。它和「`answers` 是空对象」**不等价**：用户答完前两问才按 Esc 时，
+ * 前两个答案照样交出去，同时 `skipped: true` 告诉模型「剩下的没答上，别当成
+ * 用户选了默认」。
  */
-type NoticeCode = 
+interface QuestionAnswer {
+    /** question 原文 → 选中的 label（多选是数组）。用户自由输入时是他打的原文 */
+    answers: Record<string, string | string[]>;
+    /** 用户中途放弃（Esc / 关掉弹窗）。已答的那几个仍在 `answers` 里 */
+    skipped?: boolean;
+}
 /**
- * 技能学习器在上一轮收尾之后学到了一条技能。
+ * 一次最多几个问题。
  *
- * ⚠️ 这一帧发在**下一轮的头上**，不是学成的那一刻 —— 学成时那条流早关了
- * （`maybeLearn()` 紧接着就是 `yield finish('stop'); return;`）。发在这里还有
- * 第二层意思：那一轮正是这条技能**真的进了 system prompt** 的那一轮。
+ * 超过就该拆成两轮对话 —— 四个连续弹窗已经是用户能忍的上限，而模型一次问八个
+ * 通常意味着它没读上下文。工具会**拒绝**并把这个上限说给模型（验收 5）。
  */
-'skill-learned'
+declare const MAX_QUESTIONS = 4;
+/** 每个问题的选项数下界。一个选项不是问题，是通知 */
+declare const MIN_OPTIONS = 2;
+/** 每个问题的选项数上界。超过四个用户就开始扫而不是读了 */
+declare const MAX_OPTIONS = 4;
+/** `header` 的长度上界。它是 UI 上的 chip，长了会把弹窗撑破 */
+declare const MAX_HEADER_CHARS = 12;
 /**
- * provider **把用户发的图片丢了**，而请求已经发出去、已经计费（2026-09-01）。
- *
- * 和 `agent_run.images_unsupported` 那条错误分得很清，两者别混：
- *
- * | | 谁判的 | 什么时候 | 钱 |
- * | --- | --- | --- | --- |
- * | `images_unsupported`（`error` 帧） | **我们**（闸门 1 的输入侧） | 发请求**之前** | 没花 |
- * | 这一条（`notice` 帧） | **provider 自己报的 warning** | 请求回来之后 | **已经花了** |
+ * 收窄**外部来的**答复载荷。
  *
- * 也就是说走到这一帧意味着闸门 1 判「这个模型认图」，而 provider 那侧不认。
- * 2026-09-01 那次事故就是这一格：`@ai-sdk/deepseek@3.0.20` 静默丢弃图片，
- * 模型对着一张不存在的图回答「我只看到一个占位符」，而屏幕上一个字都没有。
+ * 需要它的是跨进程的宿主（headless 的 `question-response`、`epoch web` 的 REST）：
+ * 那条路上答复是一段 JSON，不过校验直接喂给引擎等于让宿主随手拼个
+ * `{"answers": 3}` 就让模型读到一个数字。进程内的宿主由类型保证，用不到它。
  *
- * ⚠️ **一次 run 只发一帧**，不是每轮一帧：带图的那条用户消息在这一次 run 的
- * 每一轮都会重发，逐轮报的话一次多工具调用的对话会刷出十几行同样的话。
+ * 和 `isApprovalOutcome` 同一条理由住在 protocol：判据只有一处，
+ * 两个出口（stdin / REST）各写一遍就会有一边漏掉数组那一种形态。
  */
- | 'images-dropped'
+declare function isQuestionAnswerMap(value: unknown): value is Record<string, string | string[]>;
+
 /**
- * 内容合规的输入闸门**改写了用户刚发的那句话**（`mask` 档，2026-09-01）。
- *
- * ## 没有这一帧的话，这件事是**静默**的
- *
- * `mask` 档不拒绝、也不报错：它把命中处换成 `*` 之后照常发出去。而屏幕上那条
- * 用户气泡显示的是**用户自己敲的原文**（宿主回显的是输入框里那份），
- * 模型收到的是打过码的那份 —— 两边不一样，且没有任何东西说过这件事。
- *
- * 实测过：`帮我翻译一下黑鬼这个词` 发出去变成 `帮我翻译一下**这个词`。
- * 用户看着自己那句完整的话，收到一个答非所问的回复，**没有任何线索**。
- * 这一帧就是那个线索。
+ * Agent 事件契约 —— 引擎 → 宿主（TUI / CLI / 未来的 server）的唯一协议。
  *
- * ⚠️ 和 `block` 那一档分得很清：那一档请求根本没发，走的是
- * `finish: 'compliance'` + 一句正文，用户当场知道发生了什么。
- * 这一档请求照发，所以只欠一句旁白。
+ * 为什么是判别联合而不是「一个 type 字段 + 一堆可选字段」：
+ * 旧的 StreamChunk / StreamEvent 是后者，所有载荷字段都是 optional，于是
+ *   - 三个包各写一份、字段名还不一样（input/args、success/isError），
+ *     靠 cli 里一段手写适配缝合；漏一个字段编译器不报错，只是界面上少显示东西。
+ *   - 协议里没有 callId，TUI 只能靠「toolName + 调用顺序 FIFO」猜工具结果
+ *     属于哪次调用，并行工具就会串台。
+ * 判别联合让每个事件的必填字段由编译器保证，callId 成为一等字段。
  */
- | 'compliance-masked'
+
 /**
- * provider 按 max output tokens **把这一轮的回复切了**（2026-09-04）。
+ * Token 用量。
  *
- * 和 `FinishReason` 的 `'length'` 是同一件事的两个出口，两个都要：
- * 收尾原因是给**机器**分支的（headless 的 `result.reason`、落盘的
- * `finish_reason` 列、web 那枚记号），这一帧是给**人**看的那句话 ——
- * 屏幕上那半截正文自己不会说「我是半截的」。
+ * 之前 protocol 侧和 core/context/types.ts 各有一个 TokenUsage，
+ * 后者多两个字段——同名不同义，收成一个超集。
  *
- * ⚠️ 走 `notice` 而不是 `text-delta`，判据同上面 `skill-learned` 那三条：
- * 它不是模型说的话，塞进正文就会进历史、进落盘、下一轮再进模型。
- */
- | 'response-truncated'
-/**
- * 这一条消息发出去之前，**上下文被自动压了一次**（2026-09-10）。
+ * ## 五个 token 字段的口径（方案 42 PR-0）
  *
- * ## 没有这一帧的话，用户看到的是「它忘了我们刚才聊的」
+ * **两种关系并存，别一视同仁地相加**：
  *
- * 自动压缩是有损的：摘要替掉了早期几十轮的原文。屏幕上那段对话还在
- * （宿主回显的是自己那份记录），而模型手上只剩摘要 —— 于是它接下来那句
- * 「你之前说的那个方案」答得对不上，而**没有任何线索**说过发生了什么。
- * 这一帧就是那个线索，也是「为什么这一轮多花了一笔」的唯一出处。
+ * | 字段                            | 与谁的关系                  |
+ * | ------------------------------- | --------------------------- |
+ * | `cacheHitTokens` `cacheWriteTokens` | 与 `inputTokens` **不重叠** |
+ * | `reasoningTokens`               | **包含在** `outputTokens` 里 |
+ * | `totalTokens`                   | 输入总量 + 输出总量         |
  *
- * ⚠️ 走 `notice` 而不是 `text-delta`，判据同 `skill-learned`：它不是模型说的话，
- * 塞进正文就会进历史、进落盘、下一轮再进模型。
+ * 所以「一共多少 token」= `inputTokens + outputTokens + cacheHit + cacheWrite`，
+ * **不加** `reasoningTokens`。计价同理，见 `core/src/cost/pricing.ts` 文件头。
  *
- * ⚠️ **两个位置都发这一帧，语义相同**（都是「这一发之前压了」）：
- * `AgentSession` 跑前那道（软线，压完写回会话历史）和 `AgentLoop` 送出前那道
- * （硬线，见 protocol 的 `isPromptOversize`）。不给它们分两档码是因为
- * 用户要知道的是同一件事，而「哪道闸判的」是我们的实现细节。
+ * 这个口径不是我们凭空定的，是 AI SDK v7 那边就这么分的：
+ * `inputTokenDetails.noCacheTokens + cacheReadTokens + cacheWriteTokens
+ * === inputTokens`，而 `outputTokenDetails.textTokens = outputTokens - reasoning`。
  */
- | 'context-compacted'
+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;
+}
 /**
- * 这个模型认不认图，**我们查不到，正在现问它本人**（2026-09-11）。
- *
- * ## 为什么这一次探测必须说出来
- *
- * 它是**用户没要求过的一次额外请求**：多一趟往返（约两秒）、多一笔约 225 token
- * 的账。屏幕上那段静默否则解释不了 —— 用户发了张图，等了两秒，什么都没有。
- *
- * 判据同上面几条：多花的钱和多等的时间，只要不是用户自己点的，就欠一句旁白。
+ * 预算触顶的原因。
  *
- * ⚠️ **一次探测最多两帧**（「正在问」+ 只在**认图**时补一句「确认认图」）：
- * 不认图那一路后面紧跟着 `error` 帧，那句话已经把结论说全了，再发一帧确认
- * 就是同一件事说两遍。
+ * 住在 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`）。
  *
- * ⚠️ 每个型号**一辈子只探一次**（结论进 `~/.epoch/cache/model_probe.json`，
- * 认图存 30 天、不认图存 24 小时），所以这一帧天然罕见。要是它开始每轮都出现，
- * 说明缓存写不进去（只读的 home），那是个 bug，不是这一帧的问题。
+ * 和 `'cost'` 分开是因为处理方式不同：`'cost'` 意味着用户配的那份长期预算见底了，
+ * 要么等下个周期要么调高上限；`'call-cost'` 只是这一次跑得比预期贵，
+ * 换个说法再问一次就好。CI 的退出码也据此分叉。
  */
- | 'image-probe'
+ | 'call-cost';
+/** 一次运行的收尾原因 */
+type FinishReason = 
+/** 模型正常收工 */
+'stop'
+/** 用尽轮次预算 */
+ | 'max-turns'
+/** 死循环检测触发 —— 连续多轮重复同一个工具调用 */
+ | 'stalled'
 /**
- * **历史里**那几张图被摘掉了，因为此刻这个模型不认图（2026-09-12）。
+ * 模型在**一次回复内**开始复读，被我们掐掉了（core 的 `repetition-detector.ts`）。
  *
- * ## 和上面 `images-dropped`、和 `agent_run.images_unsupported` 三者的分工
+ * ⚠️ **和 `'stalled'` 刻意分开。** 那一档是「连续多轮调同一个工具」，
+ * 用户能做的是换个说法或者自己接手；这一档整轮工具调用为零，是解码退化，
+ * 处置是重发一次（大概率就好了）。混成一个值之后，界面上只能给出一句
+ * 同时对两种情况都不准的话。
  *
- * | | 图从哪来 | 谁判的 | 请求 | 钱 |
- * | --- | --- | --- | --- | --- |
- * | `images_unsupported`（`error` 帧） | **这一轮新发的** | 我们（闸门 1） | 不发 | 没花 |
- * | 这一条（`notice` 帧） | **历史里的** | 我们（装 history 时） | 照发 | 花了，但图不占 token |
- * | `images-dropped`（`notice` 帧） | 这一轮新发的 | **provider 的 warning** | 已发 | 花了 |
+ * ⚠️ **也不是 `'length'`。** 那一档是 provider 按 max output tokens 切的、
+ * 那半截正文是模型真想说的；这一档是**我们**在它撞上上限之前主动停的，
+ * 已经产出的正文留着但没有价值。两者在账上差一整个输出预算 ——
+ * 现场那一份是 31.6 KB 里只有 12 种句子。
+ */
+ | 'looping'
+/** 被宿主中止 */
+ | 'aborted'
+/** 模型安全策略拒答 —— 是 **provider** 拒答，不是我们拦的 */
+ | 'content-filter'
+/**
+ * 我们自己的内容合规闸门拦下了（core 的 `compliance/`）。
  *
- * 第一行是「你现在做的这件事做不了」，用户当场能改（换模型 / 去掉图）；
- * 这一条是「你**以前**做的那件事，从现在起看不见了」—— 他此刻什么都没做，
- * 所以更需要一句旁白。
+ * ⚠️ **刻意不复用 `content-filter`。** 那个值的含义是「provider 拒答了」，
+ * 处置和说法都不一样：那一档用户能做的是换个说法再问，这一档是内容触了
+ * 部署方配的合规红线（词表 + 类别档位），换说法不一定有用，而且该看的是
+ * 「哪个类别」。混成一个值之后，界面上只能给出一句同时对两种情况都不准的话。
  *
- * ## 没有这一帧的话，这件事是彻底静默的
+ * 输入侧被拦下时也是这个值 —— 那一次**请求根本没发出去**（`usage` 全零），
+ * 与输出侧被拦下的区别在文本里说清，不在这个枚举里分叉。
+ */
+ | 'compliance'
+/**
+ * provider 把这一轮的回复**按 max output tokens 截断了**（2026-09-04）。
  *
- * 触发面是两个：`epoch --resume` 装一段贴过图的会话（启动路径上**没有任何
- * 能力检查**），以及 `/model` 切到一个能力**查不到**的型号
- * （`provider/selection.ts` 那条硬拒绝只挡查得到不认图的）。两条路上用户都
- * 没有再发图，于是屏幕上不会有任何东西提到图 —— 而模型接下来那句
- * 「你发的那张截图我看不到」会像是它在犯病。
+ * ## 为什么必须和 `'stop'` 分开
  *
- * ⚠️ **一次 run 只发一帧**，判据逐字同 `images-dropped`：那几张历史图在这次
- * run 的每一轮都要重新摘一次，逐轮报的话一次多工具调用的对话会刷出十几行。
+ * 分不开的时候，「模型自己收的」和「话没说完就被切了」在事后**无法区分** ——
+ * 两者在界面上长得一模一样（都是「这一轮没有工具调用」）。而这是所有
+ * 「模型半路停下」类问题的**第一个分诊问题**：一句
+ * 「我先确认苏菲店的信息，再拉昨日数据。」+ 0 个工具调用，到底是模型宣布了
+ * 下一步就收工（该由 `verify:stop` 那道闸救），还是它正要发工具调用时
+ * 被截断（该调高 max output tokens）—— 处置完全相反。
+ *
+ * 实测过一次：`sessions.db` 里 687 条消息的 `finish_reason` 列**全是 NULL**，
+ * 而 `AgentLoop` 当时只判了 `'content-filter'`，没有任何一处判 `'length'`。
+ * 那一轮到底是哪一种，事后答不出来。
+ *
+ * ⚠️ **这一档不是「出错了」。** 请求成功、已经计费、那半截正文是真的，
+ * 只是它不完整。宿主该说的话是「回复被截断了」而不是「失败了」。
  */
- | 'history-images-stripped';
-type AgentEventType = AgentEvent['type'];
-/** 取出某个具体事件的类型，例如 AgentEventOf<'tool-call'> */
-type AgentEventOf<T extends AgentEventType> = Extract<AgentEvent, {
-    type: T;
-}>;
-
+ | 'length'
 /**
- * 插件契约。
+ * 这一轮**干了活却什么都没说**：零工具调用收尾，而正文是空的（或只有几个字），
+ * 而且踢回去重答一次之后还是这样（2026-09-16）。
  *
- * 插件是 epoch-agent 的扩展单元：一个独立 npm 包，实现 EpochPlugin 接口来提供
- * 工具、技能和生命周期钩子。插件只需依赖本包（@epoch-agent/protocol），
- * 不依赖引擎实现。
+ * ## 为什么必须和 `'stop'` 分开
  *
- * 设计参考：
- * - MCP (Model Context Protocol) 的 tool 定义格式
- * - Vercel AI SDK 的 tool 接口
+ * 分不开的时候，它和「模型正常收工」在事后**和当场都**无法区分 —— 两边都是
+ * 「这一轮没有工具调用」+ 一个 `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 上一条 ⚠️ 骂的正是「声明了却没有发射方」，
+ * 这一条反过来 —— 别发一件没发生的）。
+ *
+ * 一次 `run()` 最多一条：它是「这一轮」的头，不是「这一步」的。
+ * 收尾那条 `finish` 是它的另一半，两者一头一尾夹住同一段。
+ *
+ * ## `estimatedTokens` 是**估算**，而且永远是
+ *
+ * 它是那一刻手里那份完整待发送载荷（system prompt + 工具定义 + 全部消息）
+ * 过一遍 `estimateTokens()` 的结果。2026-08-15 换了真分词器（o200k_base）之后
+ * 这个数**说得出真话**了 —— 在那之前 `chars/4` 在中文场景系统性低估 2–2.7 倍。
+ *
+ * ⚠️ **换了真分词器不等于它变成了事实**，别把这两句话弄反：
+ *
+ * 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;
-    /**
-     * 这一轮的用量。**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;
+ | {
+    type: 'question';
+    request: QuestionRequest;
+    respond: (answer: QuestionAnswer) => void;
 }
-interface VerifyResult {
-    action: 'stop' | 'continue';
-    message?: string;
+/**
+ * 补丁预览：这次工具调用真的改了哪个文件、改成什么样。
+ *
+ * 发它的是 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;
 }
-/** Hook 管理器接口（实现在 core） */
-interface HookManager {
+/** 累计用量变化（每轮结束时发一次，宿主用来更新状态栏） */
+ | {
+    type: 'usage';
+    cumulative: TokenUsage;
     /**
-     * 宿主注入的诊断出口，同时也是 `HookContext.log` 的来源。
+     * **到此刻为止、这一次 run** 的用量（方案 42 PR-2）。
      *
-     * 挂在管理器上而不是让 `AgentLoop` 另外收一个 logger：那样宿主要接两次，
-     * 接漏一处就是「hook 系统自己的告警有人收、插件在 hook 里说的话没人收」。
-     * 可选是给别的实现留的余地，缺省时 `HookContext.log` 退化成静默。
+     * 和 `finish.runUsage` 同一笔账，只是这一份是**过程中**的快照 ——
+     * 界面上「运行中：已消耗 N token」要的就是它。
+     *
+     * ⚠️ 为什么不让宿主拿 `cumulative` 相减：相减要有一个起算基线，而
+     * 「run 开始那一刻的累计」在事件流上根本没有 —— 第一帧 `usage` 到达时，
+     * 它的 `cumulative` 既可能是本轮用量、也可能是 `BudgetStore` 恢复的历史
+     * 加上本轮，从流本身分辨不了。基线猜错的代价是屏幕上那个数直接差一个量级。
      */
-    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;
+    run?: TokenUsage;
+    budgetRemaining?: {
+        costUsd?: number;
+        tokens?: number;
+    };
 }
-
 /**
- * 定时任务契约（方案 45）。
+ * 运行结束。
  *
- * 这一份只装**形状**：触发器怎么表达、一条任务有哪些字段、一次运行留下什么。
- * 注册进操作系统、抢锁、跑一次，全在 `core/src/schedule/` 和 `runtime` 里。
+ * `breach` 只在 `reason === 'budget-exceeded'` 时有值，说明是哪条上限触顶的。
+ * 没有它的话「触顶」在事件流上只是一句中文提示（`describeBreach()` 的产物），
+ * 而机器宿主要分支就只能去正则匹配那句中文 —— 我们改一个字它就碎。
  *
- * ## 为什么触发器是判别联合，而存储是一段 JSON
+ * ## `usage` 和 `runUsage` 是两笔账，别当同义词（方案 42 PR-2）
  *
- * 三档的字段完全不同（每周要 `weekdays`、按间隔要 `everyMinutes`、单次还要个
- * 日期），拆成列会得到一张一半是 NULL 的表。所以库里 `trigger_spec` 是一段
- * JSON —— 但**类型是这个联合**，JSON 只是它的存储形式。反过来（先有列再拼
- * 类型）的代价是「每周三个字段里只填了两个」这种状态在类型上说得出口。
+ * `usage` 是 `BudgetGuard.snapshot()` —— **累计**，口径由 `EpochRuntime.usageScope`
+ * 决定（配了 `BudgetStore` 就是跨会话累计，否则是本进程从零算）。宿主拿它画
+ * 「这个会话一共花了多少」。
  *
- * ## 为什么没有完整 cron 表达式
+ * `runUsage` 是**这一次 run** 的用量，由本次循环里每一轮的 `result.usage`
+ * 累加而成。加它的理由很具体：界面上每一轮结束时要写「共 14,270 token」，
+ * 而那个数**减不出来** —— 累计值可能被 `BudgetStore` 从上次会话恢复，
+ * 「第一个累计值」既可能是本轮用量、也可能是历史 + 本轮，
+ * 从事件流本身分辨不了（`AgentLoopConfig.onTurnUsage` 那段注释骂的是同一件事）。
  *
- * 这三档正好是 Windows 任务计划（`schtasks`）与 macOS launchd 的**公共**能力，
- * 而 5 字段 cron 不是。写全 cron 等于把「时区 + 夏令时 + 闰日」搬回我们自己的
- * 代码里算下一次触发时刻 —— 而把触发交给操作系统的全部意义就是不碰它们。
- * 判据一句话：**一个语义在两个平台上不能逐字一致，就不做这个语义。**
+ * **两个都是可选的，那不是偷懒**：一次 run 可以一次模型调用都没发生就结束
+ * （装配抛异常、预算在发送前拦下）。那时候「这一轮用了多少 / 用的哪个模型」
+ * 没有答案，而给一个 0 和给配置里那个模型名都是撒谎 —— 与
+ * `TokenUsage.costUsd` 的「0 是免费，undefined 是不知道」同一条约定。
  */
-
-/** 三档频率。和 WorkBuddy 的分档逐字一致，理由见文件头 */
-type ScheduleTriggerKind = 'cron' | 'interval' | 'once';
-/** 星期。`0` = 周日 … `6` = 周六，与 `Date.prototype.getDay()` 同口径 */
-type ScheduleWeekday = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+ | {
+    type: 'finish';
+    reason: FinishReason;
+    usage: TokenUsage;
+    /** **这一次 run** 的用量。provider 一次都没上报就没有这个键 */
+    runUsage?: TokenUsage;
+    /**
+     * 最后一次模型调用**实际回来**的模型（`GenerateOutput.model`）。
+     *
+     * ⚠️ 不是配置里选的那个。降级和 `switch_model` 之后两者不一样，而
+     * 「这一轮到底是谁答的」正是那时候用户最需要知道的一件事。
+     */
+    model?: string;
+    /**
+     * 最后一次模型调用**要求**的那个模型（`GenerateOutput.requestedModel`）。
+     *
+     * 和上面的 {@link model} 是一对，宿主要的那个事实是**两者是否相等** ——
+     * 不等 = 引擎降级了，相等 = 用户/命令自己挑的。
+     *
+     * ⚠️ **读侧不许拿 `model` 去和「当前配置/当前选择」比来代替这个判断。**
+     * 那是一个按**此刻**的值，而这条断言是按**轮**的 —— 它会被拿去比对所有
+     * 历史轮，于是用户在顶栏换一次模型，之前那些跑得好好的轮子集体变成
+     * 「故障转移」。web 脚注那枚徽标栽过这一次，判据全文在
+     * `core/src/provider/types.ts` 的 `GenerateOutput.requestedModel` 上。
+     */
+    requestedModel?: string;
+    breach?: BudgetBreach;
+}
 /**
- * 「周期」档的三种周期。
+ * 引擎有一句话要对用户说，而**它不是回复正文**（2026-08-26）。
  *
- * 和 `ScheduleTriggerKind` 不是一回事：那个分的是三档，这个只细分 `cron` 那一档。
+ * ## 发它的是谁，以及为什么非要一条新帧
+ *
+ * 今天唯一的发射方是 core 的 `AgentLoop`：技能学习器在上一轮收尾之后
+ * fire-and-forget 学到了一条技能，而那件事没有任何出口（判据全文在
+ * `agent/loop.ts` 的 `maybeLearn()`）。三条现成的路各自被什么挡掉：
+ *
+ * 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
+ * 的兜底为什么落在两个宿主身上，是同一条判据。
+ *
+ * `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` 分开 ——
- * 界面上把「上一次因为上一次还在跑所以跳过了」显示成红叉，用户会去查一个不存在的故障。
- */
-type ScheduleRunStatus = 'ok' | 'failed' | 'denied' | 'timeout' | 'budget' | 'skipped-overlap' | 'skipped-window' | 'missed';
-/** 合法结局全集。存进库之前用它收窄，别让一个拼错的状态混进 `last_status` */
-declare const SCHEDULE_RUN_STATUSES: readonly ScheduleRunStatus[];
-/**
- * 任务注册在哪儿。
- *
- * - `schtasks` / `launchd` —— 真的注册进了操作系统的调度器，**epoch 不用开着**
- * - `host` —— **一行都没注册进 OS**（方案 45 §2.6 的路 B）。到点了唤起它的只能是
- *   宿主自己（`setInterval` 调 `fire()`）—— 而宿主有没有真的这么做，**这一格答不出来**，
- *   它唯一承诺的事实就是「没进 OS」。所以界面上不许把它写成「已启用」，
- *   也**不许许诺「开着就会跑」**（判据全文在 locales 的 `notice_host` 上）
- */
-type ScheduleBackendKind = 'schtasks' | 'launchd' | 'host';
-/**
- * 无人值守清单 —— 「要确认，但没人在，怎么办」。
- *
- * 和权限档（`ScheduleDefinition.permission`）**各管一条轴**：档位回答「这个操作
- * 要不要人确认」，这份清单回答「要确认但没人在时，哪几条可以不问」。
- * 它不是「更宽的一档」，是把「要问人」逐条变成「这一条可以不问」。
- *
- * 三个字段由粗到细，同时命中任一条即放行：
- * `allowTools` 整个工具 / `allowOperations` 五类操作 / `allowRules` 规则字符串
- * （`terminal(git status)`、`mcp__github__*`、`file_write(./reports/**)`）。
+ * ⚠️ 这一帧发在**下一轮的头上**，不是学成的那一刻 —— 学成时那条流早关了
+ * （`maybeLearn()` 紧接着就是 `yield finish('stop'); return;`）。发在这里还有
+ * 第二层意思：那一轮正是这条技能**真的进了 system prompt** 的那一轮。
  */
-interface ScheduleAllowlist {
-    allowTools: readonly string[];
-    allowOperations: readonly OperationType[];
-    allowRules: readonly string[];
-}
+'skill-learned'
 /**
- * 一条欠条 —— 「本该问人，但没人可问」。
+ * provider **把用户发的图片丢了**，而请求已经发出去、已经计费（2026-09-01）。
  *
- * ⚠️ **只收这一类**。权限档自己判出的拒绝（选了「只读」档然后去写文件）
- * **不进欠条** —— 那是档位的判定结果，不是缺授权；把它记成欠条等于建议用户
- * 去加一条永远不会被查到的规则（第 2 层判 deny 时压根走不到第 3 层）。
- */
-interface SchedulePendingApproval {
-    toolName: string;
-    type: OperationType;
-    target: string;
-    /** 权限层给的原因，原样带着 —— 人回来时最想看的就是这句 */
-    reason: string;
-    /**
-     * 该往清单里加哪条规则（`rule-suggest` 算的精确规则）。
-     *
-     * 算不出来时**整个不带这个键**：硬编一条 `terminal()` 出来只会让用户
-     * 加进去一个死规则。
-     */
-    suggestedRule?: string;
-    at: number;
-}
-/**
- * 一条定时任务。
+ * 和 `agent_run.images_unsupported` 那条错误分得很清，两者别混：
  *
- * 时间一律是 **epoch 毫秒**而不是 `Date`：这个形状要过 JSON（存库、将来上 SSE），
- * `Date` 一过 JSON 就变成字符串，于是同一个字段在两处是两种类型。
- */
-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;
-}
-/**
- * 宿主注入的「怎么以无界面方式唤起我自己」（方案 45 §2.6）。
+ * | | 谁判的 | 什么时候 | 钱 |
+ * | --- | --- | --- | --- |
+ * | `images_unsupported`（`error` 帧） | **我们**（闸门 1 的输入侧） | 发请求**之前** | 没花 |
+ * | 这一条（`notice` 帧） | **provider 自己报的 warning** | 请求回来之后 | **已经花了** |
  *
- * 把引擎 `import` 进 Electron / VS Code 扩展的宿主**没有 `epoch` 可执行文件**，
- * 而**库自己分辨不出宿主打算怎么被唤起** —— 所以这件事必须由宿主说。
+ * 也就是说走到这一帧意味着闸门 1 判「这个模型认图」，而 provider 那侧不认。
+ * 2026-09-01 那次事故就是这一格：`@ai-sdk/deepseek@3.0.20` 静默丢弃图片，
+ * 模型对着一张不存在的图回答「我只看到一个占位符」，而屏幕上一个字都没有。
  *
- * ⚠️ **绝对不许拿 `process.execPath` + `argv[1]` 去猜。** 在 Electron 里那两个值
- * 是「Electron 的 exe」+「宿主的 main.js」，注册进去的后果是**到点了给用户弹出
- * 整个应用的主窗口**（甚至一天弹 24 次）。那不是「不够好」，是把定时任务变成骚扰。
+ * ⚠️ **一次 run 只发一帧**，不是每轮一帧：带图的那条用户消息在这一次 run 的
+ * 每一轮都会重发，逐轮报的话一次多工具调用的对话会刷出十几行同样的话。
  */
-interface ScheduleRunnerSpec {
-    /**
-     * 无界面入口的 argv 前缀，绝对路径。我们在后面追加
-     * `schedule fire <id> --home <dir>`。
-     *
-     * 那个入口必须**不建窗口、跑完就退**（Electron 里就是在 `whenReady` 之前
-     * 分叉出去）。
-     */
-    argv: readonly string[];
-    /** 注册进 OS 时给人看的名字前缀。不给就用 `epoch` */
-    label?: string;
-}
-
+ | 'images-dropped'
 /**
- * 内置模板六张（[方案 45](../../../docs/verify/VERIFY_RECORD-45-automation.md) §7.3）。
- *
- * 判据是「**这件事必须每天/每周做一次，而且做完是一份能读的东西**」——
- * 所以 WorkBuddy 那 12 张消费级的（儿童睡前故事 / 父母联系提醒 / 萌宠壁纸）
- * 一张都没抄，换成开发者场景。
- *
- * ## ⚠️ 三条硬约束都摊在类型上，不靠注释
- *
- * | §7.3 那句话                     | 落在类型的哪一格                                                     |
- * | ------------------------------- | -------------------------------------------------------------------- |
- * | 模板**不联网**                  | 这是一份 `const`，没有取数入口 —— 在线模板市场 42 已定不做           |
- * | 一律不预设「跳过全部检查」      | {@link ScheduleTemplate.permission} 的取值里**没有** `bypass`         |
- * | 填进表单后**必须让用户过一遍**  | 整份形状里**没有** `maxBudgetUsd`，而它是必填 —— 表单因此保存不了     |
- *
- * 最后一条是三条里最要紧的，而它是**结构性**的而不是靠一句提示：预算必填、
- * 没有默认值（§3.5），于是一张模板卡填进表单之后那个保存按钮**天然是灰的**，
- * 用户不看完那一屏就出不去。写成「模板里预填 0.50 + 一句『请检查』」的话，
- * 「必须过一遍」就退化成一句没人读的话。
- *
- * ## 为什么住在 protocol，而不是「core 一份 + 这里抄一份」
- *
- * 任务书给的两条路是「从 server 端点下发」或者「抄一份到 protocol + 一条逐项相等
- * 的用例」（照 `WireScheduleIssueCode` 的先例）。**两条都不用，因为这一份和那个
- * 先例不是同一种东西**：
+ * 内容合规的输入闸门**改写了用户刚发的那句话**（`mask` 档，2026-09-01）。
  *
- * - `WireScheduleIssueCode` 的真源在 core**必须**在 core —— 那张码表是
- *   `validateSchedule()` 的出口集合，它和判定逻辑长在一起，搬不动；
- * - 而这一份是**纯数据、零判定**：六个触发器、六档权限、六份最小清单。
- *   它谁都不依赖。而 [AGENTS.md](../../../AGENTS.md) 的分层表里 protocol 那一行
- *   写着「跨包共享的东西**只能**放这里」。
+ * ## 没有这一帧的话，这件事是**静默**的
  *
- * 放这儿的直接收益是**不存在第二份**：`packages/web` 够得着它（只依赖
- * protocol + view）、cli 够得着、server 够得着、假服务端也够得着。抄一份到
- * protocol 再钉一条「逐项相等」的用例，是在为一个可以不存在的分叉修围栏；
- * 走一条 server 端点则要为一份**从不改变的常量**加一条 HTTP 往返和一个失败态
- * （「模板拉不下来」——而它明明就在包里）。
+ * `mask` 档不拒绝、也不报错：它把命中处换成 `*` 之后照常发出去。而屏幕上那条
+ * 用户气泡显示的是**用户自己敲的原文**（宿主回显的是输入框里那份），
+ * 模型收到的是打过码的那份 —— 两边不一样，且没有任何东西说过这件事。
  *
- * ## ⚠️ 这里一个中文字都没有，措辞在 web 那份 catalog 里
+ * 实测过：`帮我翻译一下黑鬼这个词` 发出去变成 `帮我翻译一下**这个词`。
+ * 用户看着自己那句完整的话，收到一个答非所问的回复，**没有任何线索**。
+ * 这一帧就是那个线索。
  *
- * 名字 / 说明 / **提示词**三样都是文案：提示词要跟着用户的界面语言走
- * （一个英文界面的用户不该收到一份中文报告），而 protocol 里没有 `t()`、
- * 也不该有。所以这一份只给 `id`，措辞表在
- * `web/src/automation/labels.ts` 的 `TEMPLATE_TEXT` 上 —— 那张表
- * `satisfies Record<ScheduleTemplateId, …>`，**加一张模板而不给它文案会当场编译不过**。
+ * ⚠️ 和 `block` 那一档分得很清：那一档请求根本没发，走的是
+ * `finish: 'compliance'` + 一句正文，用户当场知道发生了什么。
+ * 这一档请求照发，所以只欠一句旁白。
  */
-
+ | 'compliance-masked'
 /**
- * 六张模板的 id。
+ * provider 按 max output tokens **把这一轮的回复切了**（2026-09-04）。
  *
- * 它同时是**文案表的键**（web 那侧 `satisfies Record<ScheduleTemplateId, …>`），
- * 所以这个联合就是「有几张模板」的唯一真源 —— 加一张要改的地方由编译器点出来。
+ * 和 `FinishReason` 的 `'length'` 是同一件事的两个出口，两个都要：
+ * 收尾原因是给**机器**分支的（headless 的 `result.reason`、落盘的
+ * `finish_reason` 列、web 那枚记号），这一帧是给**人**看的那句话 ——
+ * 屏幕上那半截正文自己不会说「我是半截的」。
+ *
+ * ⚠️ 走 `notice` 而不是 `text-delta`，判据同上面 `skill-learned` 那三条：
+ * 它不是模型说的话，塞进正文就会进历史、进落盘、下一轮再进模型。
  */
-type ScheduleTemplateId = 'repo-sweep' | 'weekly-digest' | 'dep-checkup' | 'stale-docs' | 'test-flake' | 'todo-digest';
+ | 'response-truncated'
 /**
- * 一张模板 = 一条任务除了「名字 / 提示词 / 预算」之外的那些格子。
+ * 这一轮零工具调用收尾，而正文是空的（或只有几个字）—— **已经踢回去让它重答**
+ * （2026-09-16）。
  *
- * 三样刻意缺席，各有各的理由：
+ * 和 `FinishReason` 的 `'blank'` 是同一件事的两个出口，但**两者不同时出现**，
+ * 这一点和 `response-truncated` / `'length'` 那一对相反：
  *
- * - `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;
-}
-/**
- * 六张。顺序就是界面上卡片的顺序：**两张每天的排在前面** ——
- * 「每天一次」比「每周一次」更容易让人第一次就试出效果，而这一屏的空状态
- * 要答的问题是「这东西能替我做什么」。
- */
-declare const SCHEDULE_TEMPLATES: readonly ScheduleTemplate[];
-
-/**
- * 「还欠着的那几张欠条」——
- * [方案 45](../../../docs/verify/VERIFY_RECORD-45-automation.md) §八 ① / ③ 的素材。
+ *   - 这一帧发在**第一次**判空的那一刻，后面紧跟一次重答。重答成功了的话
+ *     那一轮的收尾原因是 `'stop'`（它确实正常收工了），而屏幕上留着这一句话，
+ *     解释「刚才为什么多花了一轮」；
+ *   - `'blank'` 只在重答**之后还是空**时才落下去。
  *
- * 三个界面读的是同一个数：dock 上那一条「自动化待确认」、侧栏「自动化」入口上
- * 那个点、TUI 启动时那一行。**它们必须是同一个数** —— 三处各数一遍的下场是
- * 侧栏有点、点进去 dock 上什么都没有。
+ * 所以少了这一帧，用户看到的是一次莫名其妙多出来的等待；少了 `'blank'`，
+ * 两次都空的那一轮会被记成成功。两个都要。
  *
- * ## 一、为什么这份投影住在 protocol
+ * ⚠️ 走 `notice` 而不是 `text-delta`，判据同上面 `skill-learned` 那三条：
+ * 它不是模型说的话，塞进正文就会进历史、进落盘、下一轮再进模型。
+ */
+ | 'blank-response'
+/**
+ * 这一条消息发出去之前，**上下文被自动压了一次**（2026-09-10）。
  *
- * 它是**纯集合运算**：手上有哪几条任务、每条最近跑过什么、清单里已经有哪几条规则。
- * 没有日期算术、不读盘、不查权限，一个字的 core 知识都不需要。
- * 而它的消费者有四个：`server`（那条端点）、`cli`（`--fix` 和 TUI 那行开机提示）、
- * `packages/web/dev` 那台假服务端、以及将来任何一个嵌入宿主。
- * [AGENTS.md](../../../AGENTS.md) 分层表里 protocol 那一行写着
- * 「跨包共享的东西**只能**放这里」，这就是那一行说的情况。
+ * ## 没有这一帧的话，用户看到的是「它忘了我们刚才聊的」
  *
- * ⚠️ **这一份落地之前，那个集合运算在仓库里有三份**（`server` 的 `fixSchedule`、
- * `cli` 的 `applyFix`、假服务端的 `fakeScheduleFix`），逐字一样的六行。
- * 三份都是「往授权清单里加规则」这条路上的判定 —— 也就是**提权路径上的重复实现**。
- * 收成一份是这个文件存在的第二个理由，比第一个理由更硬。
+ * 自动压缩是有损的：摘要替掉了早期几十轮的原文。屏幕上那段对话还在
+ * （宿主回显的是自己那份记录），而模型手上只剩摘要 —— 于是它接下来那句
+ * 「你之前说的那个方案」答得对不上，而**没有任何线索**说过发生了什么。
+ * 这一帧就是那个线索，也是「为什么这一轮多花了一笔」的唯一出处。
  *
- * ## 二、「还欠着」= 算得出规则、而且规则还不在清单里
+ * ⚠️ 走 `notice` 而不是 `text-delta`，判据同 `skill-learned`：它不是模型说的话，
+ * 塞进正文就会进历史、进落盘、下一轮再进模型。
  *
- * 两道筛，**缺一道这个数就会自己卡住**：
+ * ⚠️ **两个位置都发这一帧，语义相同**（都是「这一发之前压了」）：
+ * `AgentSession` 跑前那道（软线，压完写回会话历史）和 `AgentLoop` 送出前那道
+ * （硬线，见 protocol 的 `isPromptOversize`）。不给它们分两档码是因为
+ * 用户要知道的是同一件事，而「哪道闸判的」是我们的实现细节。
+ */
+ | 'context-compacted'
+/**
+ * 这个模型认不认图，**我们查不到，正在现问它本人**（2026-09-11）。
  *
- * 1. **`suggestedRule` 必须有值。** 算不出精确规则的那几条（目标为空的操作）
- *    进不了这份清单 —— dock 上唯一的动作是「加进授权清单」，而对它们那一下
- *    什么都加不了。一条点了没用的通知比没有通知坏（设计稿决定 20 ①），
- *    而且它**永远清不掉**：没有任何动作能让它消失。
- *    ⚠️ 它们并没有被藏起来：「运行记录」那一屏上那一轮照旧列着它们、
- *    照旧写着「这一条反推不出精确规则」。这里筛掉的是**通知**，不是事实。
- * 2. **规则还不在 `allowRules` 里。** 用户按过那一下之后规则就进清单了，
- *    于是这个数**自己减一**。这条让整件事不需要「读标记」那套东西 ——
- *    没有迁移、没有「哪个界面算看过」这个产品判断、也没有一个只能靠
- *    「我看过了」来清的角标。
+ * ## 为什么这一次探测必须说出来
  *
- * ## ⚠️ 三、这个数**不含**「上一次没跑成」的那几条，而那是一条判断不是遗漏
+ * 它是**用户没要求过的一次额外请求**：多一趟往返（约两秒）、多一笔约 225 token
+ * 的账。屏幕上那段静默否则解释不了 —— 用户发了张图，等了两秒，什么都没有。
  *
- * `failed` / `timeout` / `budget` 三档同样是「你该知道的事」，但它们**没有下一步
- * 动作**：屏幕上给不出一个按钮，用户只能去看运行记录。把它们算进来的话，这个点
- * 会一直亮着，直到那条任务下一次跑成 —— 而在那之前它已经不再指向任何可做的事，
- * 也就退化成了一个「有东西发生过」的常亮灯。
+ * 判据同上面几条：多花的钱和多等的时间，只要不是用户自己点的，就欠一句旁白。
  *
- * 三档失败在「运行记录」那一屏上有自己的三态色（✅ ⚠️ ❌），一条都没藏。
- * 📮 真要给它们一个计数，前置是一份**读标记**（`schedule` 那个 namespace 加一次
- * 迁移 + 一条写端点 + 「web 打开那个 tab 算不算看过、TUI 启动算不算」这个产品
- * 判断）。那是独立的一次改动，不该顺手塞进这一轮。
- */
-
-/**
- * 一条**算得出规则**的欠条。
+ * ⚠️ **一次探测最多两帧**（「正在问」+ 只在**认图**时补一句「确认认图」）：
+ * 不认图那一路后面紧跟着 `error` 帧，那句话已经把结论说全了，再发一帧确认
+ * 就是同一件事说两遍。
  *
- * `suggestedRule` 从可选收成必填 —— 这不是换个写法：它让「dock 上那个按钮
- * 一定加得进东西」变成一件类型上成立的事，而不是一句要人记住的注释。
+ * ⚠️ 每个型号**一辈子只探一次**（结论进 `~/.epoch/cache/model_probe.json`，
+ * 认图存 30 天、不认图存 24 小时），所以这一帧天然罕见。要是它开始每轮都出现，
+ * 说明缓存写不进去（只读的 home），那是个 bug，不是这一帧的问题。
  */
-type FixableApproval = SchedulePendingApproval & {
-    suggestedRule: string;
-};
+ | 'image-probe'
 /**
- * dock / 侧栏 / TUI 三处共用的一条。
+ * **历史里**那几张图被摘掉了，因为此刻这个模型不认图（2026-09-12）。
  *
- * 带 `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[];
-}
-/**
- * 这一轮的欠条里，有哪几条规则还不在清单里。**去重，顺序照欠条的顺序。**
+ * ## 和上面 `images-dropped`、和 `agent_run.images_unsupported` 三者的分工
  *
- * 三个调用点：这个文件自己（算那个计数）、`POST /api/schedules/:id/fix`
- * （真往清单里写的那一下）、`epoch schedule run --fix`。
- * ⚠️ **三处必须是同一个函数**：它决定的是「往授权清单里加哪几条规则」，
- * 而三份实现走散的方向可能是提权（一边加了另一边没加）。
- */
-declare function unfixedRules(allowRules: readonly string[], approvals: readonly SchedulePendingApproval[]): string[];
-/**
- * 手上那几条任务 + 最近那些运行 → 该通知的清单。
+ * | | 图从哪来 | 谁判的 | 请求 | 钱 |
+ * | --- | --- | --- | --- | --- |
+ * | `images_unsupported`（`error` 帧） | **这一轮新发的** | 我们（闸门 1） | 不发 | 没花 |
+ * | 这一条（`notice` 帧） | **历史里的** | 我们（装 history 时） | 照发 | 花了，但图不占 token |
+ * | `images-dropped`（`notice` 帧） | 这一轮新发的 | **provider 的 warning** | 已发 | 花了 |
  *
- * ## ⚠️ 同一条任务只报**最近**那一次，不是每一次
+ * 第一行是「你现在做的这件事做不了」，用户当场能改（换模型 / 去掉图）；
+ * 这一条是「你**以前**做的那件事，从现在起看不见了」—— 他此刻什么都没做，
+ * 所以更需要一句旁白。
  *
- * 一条「每天 9 点」的任务每天记同一条欠条，一周就是七条一模一样的通知。
- * 所以按任务收拢、取最近那一次。这不会漏掉东西：修最近那一次加进去的规则
- * 通常把老的那几次也一起覆盖了；万一老的那次欠的是**另一条**规则，
- * 它在下一次取数时自然浮上来成为「最近的那条未解决的」。
+ * ## 没有这一帧的话，这件事是彻底静默的
  *
- * ⚠️ 判的是「最近的**还欠着的**那一次」，不是「最近的那一次」：一条任务昨天
- * 卡了、今天跑成了，昨天那条欠条**仍然欠着**（清单里那条规则还是没加），
- * 下一次到点还会再卡一遍。拿「最近一次的状态」当判据会把它静默吞掉。
+ * 触发面是两个：`epoch --resume` 装一段贴过图的会话（启动路径上**没有任何
+ * 能力检查**），以及 `/model` 切到一个能力**查不到**的型号
+ * （`provider/selection.ts` 那条硬拒绝只挡查得到不认图的）。两条路上用户都
+ * 没有再发图，于是屏幕上不会有任何东西提到图 —— 而模型接下来那句
+ * 「你发的那张截图我看不到」会像是它在犯病。
  *
- * @param defs 全部任务（`ScheduleControl.list()`）
- * @param runs 最近那些运行，**最新的在前**（`ScheduleControl.recentRuns()` 的顺序）
+ * ⚠️ **一次 run 只发一帧**，判据逐字同 `images-dropped`：那几张历史图在这次
+ * run 的每一轮都要重新摘一次，逐轮报的话一次多工具调用的对话会刷出十几行。
  */
-declare function collectPendingApprovals(defs: readonly ScheduleDefinition[], runs: readonly ScheduleRun[]): SchedulePendingItem[];
+ | 'history-images-stripped';
+type AgentEventType = AgentEvent['type'];
+/** 取出某个具体事件的类型，例如 AgentEventOf<'tool-call'> */
+type AgentEventOf<T extends AgentEventType> = Extract<AgentEvent, {
+    type: T;
+}>;
 
 /**
- * 模型在对话里交上来的一份定时任务**草稿**。
- *
- * `epoch schedule add` 和自动化面板那张表单是两条**人操作**的写入路。这一份是
- * 第三条来路，而它**不是写入路** —— 草稿谁都落不了库，它只是一份摆到人眼前的
- * 提案。真正落库的仍然是那两条：人点「审阅并保存」之后走的是同一个
- * `POST /api/schedules`，人粘贴命令行走的是同一个 `epoch schedule add`。
- *
- * ## ⚠️ 三条硬约束都摊在类型上，不靠注释（照 [schedule-templates.ts](./schedule-templates.js) 那三条办）
+ * 插件契约。
  *
- * | 要守住的                       | 落在类型的哪一格                                                     |
- * | ------------------------------ | -------------------------------------------------------------------- |
- * | 模型不许把任务放到「跳过全部检查」 | {@link ScheduleDraftPermission} 的取值里**没有** `bypass`            |
- * | 填进表单后**必须让用户过一遍**  | 整份形状里**没有** `maxBudgetUsd`，而它是必填 —— 表单因此保存不了     |
- * | 草稿不是写入路                  | 这里只有数据，没有 id 生成、没有 `enabled`、没有 `createdAt`          |
+ * 插件是 epoch-agent 的扩展单元：一个独立 npm 包，实现 EpochPlugin 接口来提供
+ * 工具、技能和生命周期钩子。插件只需依赖本包（@epoch-agent/protocol），
+ * 不依赖引擎实现。
  *
- * 第二条是三条里最要紧的，而它和模板那一条**是同一条**：预算必填、没有默认值
- * （方案 45 §3.5），于是一份草稿填进表单之后那个保存按钮**天然是灰的**，
- * 用户不看完那一屏就出不去。写成「草稿里预填 0.50 + 一句『请检查』」的话，
- * 「必须过一遍」就退化成一句没人读的话 —— 而这一格错了的后果很具体：
- * 一觉醒来 40 美元。
+ * 设计参考：
+ * - MCP (Model Context Protocol) 的 tool 定义格式
+ * - Vercel AI SDK 的 tool 接口
+ */
+
+/** 技能定义 */
+interface EpochSkill {
+    /** 技能名称 */
+    name: string;
+    /** 触发条件（自然语言描述 LLM 何时应加载此技能） */
+    trigger: string;
+    /** 技能内容（Markdown 格式的流程指南） */
+    content: string;
+}
+/** 生命周期钩子 */
+interface EpochHook {
+    /** 钩子类型 */
+    type: HookType;
+    /** 执行函数 */
+    handler: (event: HookEvent) => Promise<void>;
+}
+/**
+ * 日志出口 —— 库代码唯一允许的「说点什么」的通道。
  *
- * ## 为什么住在 protocol
+ * 库不许直接写 stderr：嵌进 Electron 主进程或服务端之后，`console.warn` 既进不了
+ * 宿主的日志系统，也没法在 UI 上呈现，更关不掉。所以凡是原来想 console 的地方，
+ * 一律收成这个签名，由装配层从宿主那里接一个进来；宿主不给就静默 —— 不是退回 stderr。
  *
- * 和 `SCHEDULE_TEMPLATES` 同一个理由，而且更硬一档：这一份的**两端都要读它** ——
- * core 那侧要解析模型发来的入参（`tools/builtin/schedule-draft.ts`），
- * `packages/web` 那侧要从那次工具调用的入参里把它读回来渲染成一张卡片
- * （`thread/rows.ts`，照 `todo` 的先例）。web 只依赖 protocol + view，够不着 core。
+ * 这本来就是 `PluginContext.log` 的签名，只是以前只有插件能用。
  *
- * ## ⚠️ 这里一个中文字都没有
+ * **`message` 必须自带完整信息**：`detail` 是给结构化日志系统的补充，
+ * 一个只看 `message` 的朴素宿主实现不能因此丢掉错误原因。
  *
- * 判据同 schedule-templates.ts 最后一节：措辞在 `locales/*.yaml` 的
- * `web.ui.thread.draft_*` 底下（卡片）和 core 的工具输出里（给模型看的那半，
- * 按 `locales/zh.yaml` 的范围说明不进 catalog）。
+ * 级别刻意写成内联联合、不另开一个 `LogLevel` 导出：infra 的 logger 里已经有一个
+ * 结构完全相同的 `LogLevel`，而 protocol 和 infra 都是零内部依赖的包，谁也 import
+ * 不了谁。与其在两个包里各挂一个同名类型让人猜该用哪个，不如这里不占这个名字 ——
+ * 要单独引用级别时写 `Parameters<LogFn>[0]`。
  */
+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>;
+}
 
 /**
- * 那个工具的名字。**真源在这儿而不是 core**，因为读它的有两个包：
- * core 注册工具时用它，web 从工具流里认出那次调用时用它
- * （`thread/rows.ts`）。
- *
- * ⚠️ 这一点上它和隔壁 `TODO_TOOL` 的做法不一样：那个名字今天在
- * `web/src/thread/rows.ts` 里另写了一份字面量（那时 protocol 里没有落脚点）。
- * 别照那个抄 —— 两份字面量漂了的表现是「卡片再也不渲染了」，而 typecheck
- * 一声不响。
- */
-declare const SCHEDULE_DRAFT_TOOL = "schedule_draft";
-/**
- * 草稿能落在哪几档权限上 —— **`bypass` 不在里面**。
+ * Hook 契约。
  *
- * 不是「运行期会拒绝」，是那一档在类型上根本不存在（判据同
- * `ScheduleTemplate.permission`）。理由比模板那一侧更直接：`bypass` 要一次
- * 二次确认（`bypass-not-confirmed`），而那次确认的**对象是人**；让模型提议
- * 一个「等着人去勾确认框」的档位，等于把那道确认变成一道例行手续。
+ * 参考 Hermes hermes_cli/plugins.py → VALID_HOOKS + invoke_hook
  *
- * 用户自己想要那一档时照旧走表单 —— 那条路一个字都没改。
+ * 注意：HookType 之前在 core/src/plugin.ts 和 core/src/hook/types.ts 各有一份，
+ * 且**内容不同**（plugin.ts 那份只有 7 个事件，缺 compress:after / transform:* /
+ * verify:stop）。插件作者按 EpochHook 写代码时拿到的是窄的那份，注册进
+ * HookManager 却是宽的那份。这里合并成唯一一份。
  */
-type ScheduleDraftPermission = Exclude<PermissionLevel, 'bypass'>;
-/** 草稿里那份清单。三个字段各自**可选**：没提到的一格 = 「这一格我没意见」 */
-interface ScheduleDraftAllowlist {
-    allowTools?: readonly string[];
-    allowOperations?: readonly OperationType[];
-    allowRules?: readonly string[];
+
+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 ScheduleDraftCreate extends ScheduleDraftAllowlist {
-    action: 'create';
-    name: string;
-    prompt: string;
-    trigger: ScheduleTrigger;
-    /** 工作目录。不给就是引擎那份缺省（`~/.epoch/automation/<id>/`） */
-    workDir?: string;
-    permission: ScheduleDraftPermission;
+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` 退化成静默。
      */
-    note: string;
+    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）。
  *
- * 每一格都可选（`undefined` = 这一格不动），但至少要动一格 —— 一份什么都不改的
- * 提案是在浪费用户的一次点击。这条判定在 core 那侧
- * （`schedule/draft.ts` 的 `draft-update-empty`）。
+ * 这一份只装**形状**：触发器怎么表达、一条任务有哪些字段、一次运行留下什么。
+ * 注册进操作系统、抢锁、跑一次，全在 `core/src/schedule/` 和 `runtime` 里。
+ *
+ * ## 为什么触发器是判别联合，而存储是一段 JSON
+ *
+ * 三档的字段完全不同（每周要 `weekdays`、按间隔要 `everyMinutes`、单次还要个
+ * 日期），拆成列会得到一张一半是 NULL 的表。所以库里 `trigger_spec` 是一段
+ * JSON —— 但**类型是这个联合**，JSON 只是它的存储形式。反过来（先有列再拼
+ * 类型）的代价是「每周三个字段里只填了两个」这种状态在类型上说得出口。
+ *
+ * ## 为什么没有完整 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;
+/**
+ * 「周期」档的三种周期。
  *
- * ## ⚠️ 「放宽」和别的改动在类型上长得一样，所以判定必须在别处
+ * 和 `ScheduleTriggerKind` 不是一回事：那个分的是三档，这个只细分 `cron` 那一档。
+ */
+type ScheduleCycle = 'daily' | 'weekly' | 'monthly';
+/**
+ * 触发器。
  *
- * 把超时从 10 分钟调到 30 分钟，和往清单里加一条 `terminal(rm:*)`，在这个形状里
- * 是同一种东西：几个可选字段。而后者是**提权**。所以两个宿主都必须自己把
- * 「这次提案放宽了什么」单独标出来（web 的卡片、core 的工具输出），
- * 不许把它混在一列改动里 —— 用户扫一眼就点保存的那一下，正是这条要防的。
+ * 所有带时刻的档共用 `at: 'HH:mm'`（24 小时制，**本机时区**）—— 统一成一个字段名
+ * 是为了让「几点跑」在三档之间读起来是同一件事；单次那一档另加 `date`。
  */
-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 ScheduleTrigger = {
+    kind: 'cron';
+    cycle: 'daily';
+    at: string;
+} | {
+    kind: 'cron';
+    cycle: 'weekly';
+    at: string;
+    weekdays: readonly ScheduleWeekday[];
 }
-type ScheduleDraft = ScheduleDraftCreate | ScheduleDraftUpdate;
+/** `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;
+};
 /**
- * 一次提案里「放宽了什么」的分类。
+ * 「按间隔」档的**全部**合法取值（分钟）。
  *
- * 只有三类，而三类都是**授权面变大**的方向：档位往松走、清单多了条目、
- * 从停用变成启用。别往里加「超时变长」这种 —— 它花的是钱和时间，不是权限，
- * 而把两种东西混进同一枚警示标，那枚标就不再有信息量。
+ * 收紧成「60 的约数」和「整小时数」不是洁癖，是 launchd 的硬约束：那一侧只能用
+ * `StartCalendarInterval`（列举时刻），不能用 `StartInterval`（睡眠时那一次会被
+ * 丢掉，10.11 起文档明写）。60 除不尽 7 时，「每 7 分钟」列举出来的那 9 个时刻
+ * 在每小时边界上会漂 —— 于是 Windows 上准、macOS 上漂，而那种平台差异是 bug 的温床。
  *
- * 判定在 core（`schedule/draft.ts` 的 `draftWidening`），渲染在 web
- * （`thread/schedule-draft.tsx`）—— 两侧各算一遍是刻意的，判据同
- * `web/src/thread/rows.ts` 文件头那条：web 读的是**模型发出的原始入参**，
- * 而不是 core 归一化之后的结论。
+ * 界面上因此是个下拉而不是数字输入框：下拉能表达「只有这些值」，
+ * 输入框会让人填 7 然后得到一个漂的任务。
  */
-type ScheduleWideningKind = 'permission' | 'allowlist' | 'enabled';
-
+declare const SCHEDULE_INTERVAL_MINUTES: readonly number[];
 /**
- * 工作区信任契约。
- *
- * 为什么需要：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 里。
- * 契约与实现的授权状态不同是对的，不是漏登记。
+ * 后三个是「没跑」而不是「跑失败了」，它们必须和 `failed` 分开 ——
+ * 界面上把「上一次因为上一次还在跑所以跳过了」显示成红叉，用户会去查一个不存在的故障。
  */
-/** 一个目录的信任状态 */
-type TrustLevel = 
-/** 用户明确信任：加载项目指令 / hook / policy */
-'trusted'
-/** 用户明确拒绝：只当普通工作目录，不加载任何项目级配置 */
- | 'untrusted'
-/** 还没问过 */
- | 'unknown';
-/** 用户已经做过决策的信任状态（排除「还没问过」） */
-type DecidedTrustLevel = Exclude<TrustLevel, 'unknown'>;
-/** 信任决策的作用域 */
-type TrustScope = 
-/** 只这个目录 */
-'directory'
-/** 这个目录及其所有子目录 */
- | 'directory-tree';
+type ScheduleRunStatus = 'ok' | 'failed' | 'denied' | 'timeout' | 'budget' | 'skipped-overlap' | 'skipped-window' | 'missed';
+/** 合法结局全集。存进库之前用它收窄，别让一个拼错的状态混进 `last_status` */
+declare const SCHEDULE_RUN_STATUSES: readonly ScheduleRunStatus[];
 /**
- * 一次授信授到哪一档（2026-09-11）。**两档是相加的：`exec` 蕴含 `read`。**
+ * 任务注册在哪儿。
  *
- * ## 为什么拆
+ * - `schtasks` / `launchd` —— 真的注册进了操作系统的调度器，**epoch 不用开着**
+ * - `host` —— **一行都没注册进 OS**（方案 45 §2.6 的路 B）。到点了唤起它的只能是
+ *   宿主自己（`setInterval` 调 `fire()`）—— 而宿主有没有真的这么做，**这一格答不出来**，
+ *   它唯一承诺的事实就是「没进 OS」。所以界面上不许把它写成「已启用」，
+ *   也**不许许诺「开着就会跑」**（判据全文在 locales 的 `notice_host` 上）
+ */
+type ScheduleBackendKind = 'schtasks' | 'launchd' | 'host';
+/**
+ * 无人值守清单 —— 「要确认，但没人在，怎么办」。
  *
- * 在它之前 `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;
     /**
-     * 这条决策管到哪儿。
+     * 停用不等于删除。停用的任务在系统的任务计划里**仍然看得见，只是停着** ——
+     * 删掉再建的话，用户在任务计划程序里看到条目消失会以为我们把他的任务弄丢了。
+     */
+    enabled: boolean;
+    createdAt: number;
+    updatedAt: number;
+    prompt: string;
+    /**
+     * 工作目录。**执行器不许继承 cwd** —— OS 调度器起进程时的 cwd 不由我们决定
+     * （Windows 上是 `%SystemRoot%\System32`）。用户没填时落在
+     * `~/.epoch/automation/<id>/`，那是一个确定的目录，不是「随便哪儿」。
+     */
+    workDir: string;
+    model?: string;
+    /**
+     * 「召唤专家」。**今天永远不带 —— 但已经不是被别人挡着了。**
      *
-     * `check()` 会把它折叠进 `TrustLevel`，所以判定方用不上；但**列出记录**的一方
-     * （`epoch trust` 要显示「仅此目录 / 含子目录」）必须能看见 —— 少了它，
-     * `list()` 返回的就不是一条完整的决策，而是一条读不懂的决策。
+     * 立案时写的是「等方案 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)。
      */
-    scope: TrustScope;
-    /** 记录时间戳（ms） */
-    decidedAt: number;
+    role?: string;
+    /** 同 {@link role}：方案 44 的清单契约早就到齐了，缺的是写入点。今天永远不带 */
+    skills?: readonly string[];
     /**
-     * 执行类也授了吗（{@link TrustTier}）。`level: 'untrusted'` 时无意义。
+     * 同 {@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 侧有没有漂。
      *
-     * ⚠️ **缺省（`undefined`）= 没授**，而这一格正是存量记录的迁移：拆档之前写下的
-     * 记录没有这一格，于是升级之后它们**只剩读类** —— 判据就是上面那张表下面那段：
-     * 那些记录是在一句只说了「项目指令会加载」的问话下拿到的，把它们追认成执行类
-     * 等于替用户补签一份他没看过的同意书。代价（老用户的项目 hook 会停）由
-     * `trust_gate.exec_migrated` 那条诊断明说，不静默。
+     * 存下来而不是每次现算：现算的结果依赖**此刻**的 `process.execPath` 和入口路径，
+     * 而漂移检查要问的恰恰是「当初写进去的是什么」。
      */
-    exec?: boolean;
+    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;
     /**
-     * 授 `exec` 那一刻，执行类输入文件的内容指纹（见 core 的 `trust/exec-hash.ts`）。
-     *
-     * 对不上 = 那些文件在授信之后被改过 → `exec` 退回未授，重新问一次。
-     * `exec` 为假时这一格不该存在。
-     *
-     * ## ⚠️ 这是对 [manager.ts](../../core/src/trust/manager.ts) 文件头「两条明确不做」
-     * 第 2 条的一次**窄口推翻**，不是把它作废
-     *
-     * 那一条 2026-08-08 写着：记内容 hash「代价是『改一行 AGENTS.md 就被打断一次』，
-     * 这个打断比它挡住的风险更贵」。**那个结论在读类上照旧成立，一个字不改** ——
-     * 指令文件天天在动，为它记 hash 会把授信变成一件每天都要重做的事。
-     *
-     * 翻的只有执行类那一半，因为它的两项输入都变了：
-     *
-     * | | 读类（AGENTS.md）      | 执行类（hooks.json / policies） |
-     * | --- | ---------------------- | -------------------------------- |
-     * | 改动频率 | 每天              | 几乎不动                          |
-     * | 改动后果 | 多一段文本        | **多一条会跑的命令**              |
+     * `epoch schedule run` 手动跑的那一次。
      *
-     * 也就是说，同一个做法在这一侧的打断成本低一个量级、挡住的东西贵一个量级。
-     * 参照物：codex 对 hook 记 `trusted_hash`（`codex-rs/config/src/hook_config.rs`），
-     * 而它的 `AGENTS.md` 压根不过闸门 —— 同一条判据的两侧，它也是这么分的。
+     * 标出来是因为它**不该影响「上一次到点跑成没有」的判断** ——
+     * 用户手点一次成功，不等于明天 9 点那次会成功。
      */
-    execHash?: string;
-}
-/** {@link TrustManager.record} 的可选档位。不给 = 只授读类 */
-interface TrustGrant {
-    /** 连执行类一起授。**调用方必须真的为这一档单独问过用户** */
-    exec?: boolean;
-    /** 授 `exec` 时一并记下的内容指纹 */
-    execHash?: string;
+    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。
+ * 最后一条是三条里最要紧的，而它是**结构性**的而不是靠一句提示：预算必填、
+ * 没有默认值（§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 往返和一个失败态
+ * （「模板拉不下来」——而它明明就在包里）。
+ *
+ * ## ⚠️ 这里一个中文字都没有，措辞在 web 那份 catalog 里
+ *
+ * 名字 / 说明 / **提示词**三样都是文案：提示词要跟着用户的界面语言走
+ * （一个英文界面的用户不该收到一份中文报告），而 protocol 里没有 `t()`、
+ * 也不该有。所以这一份只给 `id`，措辞表在
+ * `web/src/automation/labels.ts` 的 `TEMPLATE_TEXT` 上 —— 那张表
+ * `satisfies Record<ScheduleTemplateId, …>`，**加一张模板而不给它文案会当场编译不过**。
  */
 
-/** 模型请求执行的一次工具调用 */
-interface EpochToolCall {
-    toolCallId: string;
-    toolName: string;
-    /** 模型给出的入参 */
-    input: Record<string, unknown>;
-}
-/** 一次工具执行的结果 */
-interface EpochToolResult {
-    toolCallId: string;
-    toolName: string;
-    /** 输出的文本形式。工具的返回值统一收成字符串，不往下传结构 */
-    output: string;
+/**
+ * 六张模板的 id。
+ *
+ * 它同时是**文案表的键**（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;
     /**
-     * 二进制产物。**只有过完四道闸门、带 `data` 的才会真的进模型上下文**
-     * （见 core/src/context/artifact-gate.ts）；否则这里只有 summary + path，
-     * `output` 里已经含了那句 summary。
+     * 权限档。**取值里没有 `bypass`**（§7.3：模板一律不预设「跳过全部检查」），
+     * 也没有 `auto`（界面压根不暴露它，§3.2）。
+     *
+     * 两档各有各的用法，而分界线是 by-level 那张表：
+     *
+     * - `plan`（只读）—— 「读一遍然后写一份报告」的那几张。它天然零授权面，
+     *   清单里只要一条 `file_write`（那条走**第 2 层**规则匹配，所以在只读档下
+     *   照样放行 —— §3.2 那句「只读 + `file_write(<任务目录>/**)`」说的就是它）；
+     * - `default`（按需确认）—— 要跑命令的那几张。**除了 `bypass`，写命令在每一档
+     *   下都要确认**，所以它们只能靠清单逐条放行，而这正是清单存在的理由。
      */
-    artifacts?: ToolArtifact[];
-}
-/** 文本部件 */
-interface EpochTextPart {
-    type: 'text';
-    text: string;
+    permission: 'plan' | 'default' | 'acceptEdits';
+    /** 整个工具免确认（粗）。多数模板不用它 —— 逐条列出来的清单才审得动 */
+    allowTools?: readonly string[];
+    allowOperations?: readonly OperationType[];
+    /** 规则（细）。⚠️ **路径一律写成相对的**，理由见 {@link ScheduleTemplate} */
+    allowRules?: readonly string[];
+    /**
+     * 墙钟超时（毫秒）。不给就用引擎缺省的 15 分钟。
+     *
+     * 只有「测试 flake 复盘」给了 —— 它真的要跑一遍测试，而缺省那把尺子会在
+     * 半路把它砍掉。**这一格存在的意义就是让那一张不至于生下来就超时**。
+     */
+    timeoutMs?: number;
 }
 /**
- * 图片部件。
- *
- * `image` 三种形态：裸 base64、`data:` URL、`http(s)` URL。
- * 字段名是 `mediaType` 不是 `mimeType` —— 与 `@ai-sdk/provider-utils` 的
- * `ImagePart` 对齐，省掉边界上的一次改名。
+ * 六张。顺序就是界面上卡片的顺序：**两张每天的排在前面** ——
+ * 「每天一次」比「每周一次」更容易让人第一次就试出效果，而这一屏的空状态
+ * 要答的问题是「这东西能替我做什么」。
  */
-interface EpochImagePart {
-    type: 'image';
-    image: string;
-    mediaType?: string;
-}
-/** 附件为什么只有路径没有内容 */
-type FileOmitReason = 
-/** 探测到 NUL 字节，是二进制 */
-'binary'
-/** 权限判定没放行（与 `file_read` 同一条判定） */
- | 'denied'
-/** 读不到（不存在 / 没权限 / 是目录） */
- | 'unreadable'
-/** 这一条消息附的文件个数或总量超了上限 */
- | 'over-limit'
+declare const SCHEDULE_TEMPLATES: readonly ScheduleTemplate[];
+
 /**
- * 会话是 resume 出来的，附件内容**不重读**。
+ * 「还欠着的那几张欠条」——
+ * [方案 45](../../../docs/verify/VERIFY_RECORD-45-automation.md) §八 ① / ③ 的素材。
+ *
+ * 三个界面读的是同一个数：dock 上那一条「自动化待确认」、侧栏「自动化」入口上
+ * 那个点、TUI 启动时那一行。**它们必须是同一个数** —— 三处各数一遍的下场是
+ * 侧栏有点、点进去 dock 上什么都没有。
+ *
+ * ## 一、为什么这份投影住在 protocol
  *
- * 内容当初是过了权限判定才附上的，而那次判定发生在另一个上下文里
- * （当时的权限级别、当时的信任状态）。恢复时无声地再读一遍磁盘等于让一次
- * 旧的授权在新的上下文里继续生效。模型仍然看得见路径，要内容就自己调
- * `file_read` —— 那条路有完整的审批。
- */
- | 'not-restored';
-/**
- * 文件附件部件 —— 用户用 `@路径` 提到的文件（方案 25）。
+ * 它是**纯集合运算**：手上有哪几条任务、每条最近跑过什么、清单里已经有哪几条规则。
+ * 没有日期算术、不读盘、不查权限，一个字的 core 知识都不需要。
+ * 而它的消费者有四个：`server`（那条端点）、`cli`（`--fix` 和 TUI 那行开机提示）、
+ * `packages/web/dev` 那台假服务端、以及将来任何一个嵌入宿主。
+ * [AGENTS.md](../../../AGENTS.md) 分层表里 protocol 那一行写着
+ * 「跨包共享的东西**只能**放这里」，这就是那一行说的情况。
  *
- * ## 为什么是一种部件，而不是把内容拼进文本里
+ * ⚠️ **这一份落地之前，那个集合运算在仓库里有三份**（`server` 的 `fixSchedule`、
+ * `cli` 的 `applyFix`、假服务端的 `fakeScheduleFix`），逐字一样的六行。
+ * 三份都是「往授权清单里加规则」这条路上的判定 —— 也就是**提权路径上的重复实现**。
+ * 收成一份是这个文件存在的第二个理由，比第一个理由更硬。
  *
- * 拼字符串看起来省事，代价有四个，每一个都要在很久以后才暴露：压缩器分不清
- * 「用户打的字」和「附的文件」于是压错东西、token 统计把文件算成用户输入、
- * artifact 化那条路完全绕过、web 宿主收到的 wire 载荷里两者无法区分。
- * 单独一种部件之后，这四件事各自都有地方判。
+ * ## 二、「还欠着」= 算得出规则、而且规则还不在清单里
  *
- * ## `text` 缺席是常态，不是异常
+ * 两道筛，**缺一道这个数就会自己卡住**：
  *
- * 二进制、超限、权限没放行时**只留路径**。这时候模型看到的是「用户提到了这个
- * 文件，但内容没给你，原因是 X」—— 它可以自己去调 `file_read`（那条路有完整的
- * 审批流程）。比起静默附上或者静默丢掉，这是唯一不会让人误判的形态。
+ * 1. **`suggestedRule` 必须有值。** 算不出精确规则的那几条（目标为空的操作）
+ *    进不了这份清单 —— dock 上唯一的动作是「加进授权清单」，而对它们那一下
+ *    什么都加不了。一条点了没用的通知比没有通知坏（设计稿决定 20 ①），
+ *    而且它**永远清不掉**：没有任何动作能让它消失。
+ *    ⚠️ 它们并没有被藏起来：「运行记录」那一屏上那一轮照旧列着它们、
+ *    照旧写着「这一条反推不出精确规则」。这里筛掉的是**通知**，不是事实。
+ * 2. **规则还不在 `allowRules` 里。** 用户按过那一下之后规则就进清单了，
+ *    于是这个数**自己减一**。这条让整件事不需要「读标记」那套东西 ——
+ *    没有迁移、没有「哪个界面算看过」这个产品判断、也没有一个只能靠
+ *    「我看过了」来清的角标。
+ *
+ * ## ⚠️ 三、这个数**不含**「上一次没跑成」的那几条，而那是一条判断不是遗漏
+ *
+ * `failed` / `timeout` / `budget` 三档同样是「你该知道的事」，但它们**没有下一步
+ * 动作**：屏幕上给不出一个按钮，用户只能去看运行记录。把它们算进来的话，这个点
+ * 会一直亮着，直到那条任务下一次跑成 —— 而在那之前它已经不再指向任何可做的事，
+ * 也就退化成了一个「有东西发生过」的常亮灯。
+ *
+ * 三档失败在「运行记录」那一屏上有自己的三态色（✅ ⚠️ ❌），一条都没藏。
+ * 📮 真要给它们一个计数，前置是一份**读标记**（`schedule` 那个 namespace 加一次
+ * 迁移 + 一条写端点 + 「web 打开那个 tab 算不算看过、TUI 启动算不算」这个产品
+ * 判断）。那是独立的一次改动，不该顺手塞进这一轮。
  */
-interface EpochFilePart {
-    type: 'file';
-    /** 用户敲的那个路径（相对工作区，`/` 分隔），原样保留用于显示 */
-    path: string;
-    /** 文件内容。**缺席时看 `omitted`** */
-    text?: string;
-    /** 没给内容的原因；给了 `text` 时不出现 */
-    omitted?: FileOmitReason;
-    /** 内容被截断到多少字节。给了就是截断过 —— 截断**永远不静默** */
-    truncatedTo?: number;
-    /** 文件原始字节数，用于展示 */
-    bytes?: number;
-}
+
 /**
- * 引用的会话为什么只有标题没有内容（方案 53 §4.2）。
+ * 一条**算得出规则**的欠条。
  *
- * 前五个是**稳定的错误码**，给宿主路由用（headless / 嵌入宿主要能按码分流，
- * TUI 和 Web 要各自渲染）。清单本体是 {@link SESSION_REFERENCE_ERROR_CODES}，
- * 那才是同构位置的唯一真源。
+ * `suggestedRule` 从可选收成必填 —— 这不是换个写法：它让「dock 上那个按钮
+ * 一定加得进东西」变成一件类型上成立的事，而不是一句要人记住的注释。
  */
-type SessionOmitReason = 
-/** `@:xxx` 匹配不到**唯一**的一段会话（零个，或好几个） */
-'invalid-reference'
-/** 引用的是当前这段会话自己 */
- | 'self-reference'
-/** 超过每条消息能引用的会话个数 */
- | 'too-many'
-/** 会话可读性判定不放行（方案 48 的那一处判定，见 core/session/authorization.ts） */
- | 'not-authorized'
-/** 这一条消息的附件总量已经用完 */
- | 'budget-exceeded'
+type FixableApproval = SchedulePendingApproval & {
+    suggestedRule: string;
+};
 /**
- * 会话是 resume 出来的，引用的内容**不重读**。
- *
- * 判据逐字同 {@link FileOmitReason} 的 `not-restored`：内容当初是过了可读性
- * 判定才附上的，而那次判定发生在另一个上下文里。恢复时无声地再读一遍等于让
- * 一次旧的授权在新的上下文里继续生效。模型仍然看得见「用户引用过这段会话」，
- * 要内容就自己调 `session_search`（方案 48 那条路，有工具审批）。
+ * dock / 侧栏 / TUI 三处共用的一条。
  *
- * **它不是错误码**，所以不在 {@link SESSION_REFERENCE_ERROR_CODES} 里。
+ * 带 `scheduleName` 而不是只带 id：这条通知的措辞必须**有宾语**
+ * （「《每日仓库巡检》差一条授权」，不是「有 1 条待确认」）——
+ * 判据和跨会话待办条那一条同源（`web/src/dock/crossbar.tsx` 文件头
+ * 「措辞必须带宾语」那一节）：一个不带宾语的计数器逼用户挨个点开去看。
  */
- | 'not-restored';
+interface SchedulePendingItem {
+    scheduleId: string;
+    scheduleName: string;
+    /** 欠条挂在哪一次运行上。`POST /api/schedules/:id/fix` 收的就是它 */
+    runId: string;
+    /** 那一次运行的开始时刻（epoch 毫秒）。界面上那句「已欠了多久」 */
+    at: number;
+    /** 还没进清单的那几条，**至少一条**（空的那几轮压根不进这份清单） */
+    approvals: readonly FixableApproval[];
+}
 /**
- * 五个稳定的错误码（方案 53 §4.2）—— **同构位置的唯一真源**。
- *
- * 为什么要稳定的码而不是一句话：headless / 嵌入宿主要能路由这些失败
- * （`docs/HEADLESS.md` 的退出码那套已经是这个思路），而且 TUI 和 Web 要各自渲染。
+ * 这一轮的欠条里，有哪几条规则还不在清单里。**去重，顺序照欠条的顺序。**
  *
- * `not-restored` 刻意不在里面 —— 它是「会话恢复了」这个事实，不是一次失败。
+ * 三个调用点：这个文件自己（算那个计数）、`POST /api/schedules/:id/fix`
+ * （真往清单里写的那一下）、`epoch schedule run --fix`。
+ * ⚠️ **三处必须是同一个函数**：它决定的是「往授权清单里加哪几条规则」，
+ * 而三份实现走散的方向可能是提权（一边加了另一边没加）。
  */
-declare const SESSION_REFERENCE_ERROR_CODES: readonly SessionOmitReason[];
+declare function unfixedRules(allowRules: readonly string[], approvals: readonly SchedulePendingApproval[]): string[];
 /**
- * 引用另一段会话的部件 —— 用户用 `@:xxx` 提到的那段会话（方案 53）。
- *
- * ## 塞进来的是那段会话的「当前面」，不是原始全量（§二）
- *
- * 一个跑了两小时、压缩过三次的会话，`messages` 表里有 800 条，但模型当时能看到
- * 的只有 60 条（其余 `active = 0`）。这里带的是**那 60 条**。三条理由：800 条
- * 任何预算都塞不下；那 60 条就是这段会话的结论（压缩器已经把前面浓缩进去了）；
- * 原始全量里有已经被推翻的内容（「先试了 A 不行改用 B」，压缩之后留下的是 B）。
+ * 手上那几条任务 + 最近那些运行 → 该通知的清单。
  *
- * ## 它是**快照**，不是活引用
+ * ## ⚠️ 同一条任务只报**最近**那一次，不是每一次
  *
- * 引用是发消息那一刻的快照，之后源会话被归档、删除、继续聊都不影响这一条。
- * **别去做「引用失效」的检测** —— 那等于让一条已经发出去的消息随时间变形。
+ * 一条「每天 9 点」的任务每天记同一条欠条，一周就是七条一模一样的通知。
+ * 所以按任务收拢、取最近那一次。这不会漏掉东西：修最近那一次加进去的规则
+ * 通常把老的那几次也一起覆盖了；万一老的那次欠的是**另一条**规则，
+ * 它在下一次取数时自然浮上来成为「最近的那条未解决的」。
  *
- * ## `text` 缺席是常态
+ * ⚠️ 判的是「最近的**还欠着的**那一次」，不是「最近的那一次」：一条任务昨天
+ * 卡了、今天跑成了，昨天那条欠条**仍然欠着**（清单里那条规则还是没加），
+ * 下一次到点还会再卡一遍。拿「最近一次的状态」当判据会把它静默吞掉。
  *
- * 匹配不到、引用自己、超上限、判定不放行时**只留 `ref` 和原因**。这时候模型
- * 看到的是「用户引用了某段会话，但内容没给你，原因是 X」—— 要内容它可以自己调
- * `session_search`（方案 48）。这保证了 `@:` 永远不会成为一条比 `session_search`
- * **更宽松**的读取通道，和 `@文件` 对 `file_read` 那条判据逐字对应。
+ * @param defs 全部任务（`ScheduleControl.list()`）
+ * @param runs 最近那些运行，**最新的在前**（`ScheduleControl.recentRuns()` 的顺序）
  */
-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[];
+declare function collectPendingApprovals(defs: readonly ScheduleDefinition[], runs: readonly ScheduleRun[]): SchedulePendingItem[];
+
 /**
- * 附件在**给模型的**纯文本投影里长什么样。**不吐文件内容** —— 内容走 `parts` 那一路。
+ * 模型在对话里交上来的一份定时任务**草稿**。
  *
- * 输出**逐字冻住**：门禁在 `packages/protocol/__tests__/message-projection.test.ts`，
- * 它把五种 `omitted` 原因加截断、不截断两支全钉死了。改一个字那份会当场红 ——
- * 那不是「用例过时了」，是你正在改模型的输入契约（判据见 {@link OMIT_LABEL}）。
- */
-declare function filePartSummary(part: EpochFilePart): string;
-/**
- * 历史里的图被**摘掉**之后留在原位的那一行（2026-09-12）。
+ * `epoch schedule add` 和自动化面板那张表单是两条**人操作**的写入路。这一份是
+ * 第三条来路，而它**不是写入路** —— 草稿谁都落不了库，它只是一份摆到人眼前的
+ * 提案。真正落库的仍然是那两条：人点「审阅并保存」之后走的是同一个
+ * `POST /api/schedules`，人粘贴命令行走的是同一个 `epoch schedule add`。
  *
- * ## 它补的是一个静默的口子，不是「又一个占位符」
+ * ## ⚠️ 三条硬约束都摊在类型上，不靠注释（照 [schedule-templates.ts](./schedule-templates.js) 那三条办）
  *
- * 喂模型的历史里图片是 base64 部件（`session-store.loadHistory()` 把
- * `inlineImages` 写死成 true）。而「当前模型认不认图」那道闸门在
- * `core/agent/loop.ts` 上，读的是**这一轮用户新发的图**
- * （`imageParts(input.userMessage)`）—— 也就是说换到一个不认图的模型之后只要
- * 不再发新图，历史里那些图会原样发出去：provider 那侧要么 400、要么**一声不吭
- * 地吞掉**（后者实测存在，判据全文在 `core/provider/capability-probe.ts` 的
- * 文件头）。摘掉它们的是 `AgentLoop`，留下的那一行是这一个。
+ * | 要守住的                       | 落在类型的哪一格                                                     |
+ * | ------------------------------ | -------------------------------------------------------------------- |
+ * | 模型不许把任务放到「跳过全部检查」 | {@link ScheduleDraftPermission} 的取值里**没有** `bypass`            |
+ * | 填进表单后**必须让用户过一遍**  | 整份形状里**没有** `maxBudgetUsd`，而它是必填 —— 表单因此保存不了     |
+ * | 草稿不是写入路                  | 这里只有数据，没有 id 生成、没有 `enabled`、没有 `createdAt`          |
  *
- * ## 为什么不复用 `contentToText` 那个 `[图片 image/jpeg]`
+ * 第二条是三条里最要紧的，而它和模板那一条**是同一条**：预算必填、没有默认值
+ * （方案 45 §3.5），于是一份草稿填进表单之后那个保存按钮**天然是灰的**，
+ * 用户不看完那一屏就出不去。写成「草稿里预填 0.50 + 一句『请检查』」的话，
+ * 「必须过一遍」就退化成一句没人读的话 —— 而这一格错了的后果很具体：
+ * 一觉醒来 40 美元。
  *
- * 那一个是**另一个消费者**的投影（`imagesCarriedAsParts: false`，喂压缩器 /
- * 审计 / `messages.content` 那一列），而且它有前科：图片真的送达之后，它成了
- * 「唯一还在撒谎的地方」（判据在 {@link ContentToTextOptions.imagesCarriedAsParts}）。
- * 这一行要说的是另一件事 —— 图**确实没给它**，以及为什么。
+ * ## 为什么住在 protocol
  *
- * 措辞里带上「不支持」这半句，判据同 `agent/prompt.ts` 里那条
- * 「不支持那一档要说清后果，别笼统一句不支持」：只写「图片未附上」的话，
- * 模型会去猜是不是传坏了，然后建议用户重发一次 —— 而重发多少次都一样。
+ * 和 `SCHEDULE_TEMPLATES` 同一个理由，而且更硬一档：这一份的**两端都要读它** ——
+ * core 那侧要解析模型发来的入参（`tools/builtin/schedule-draft.ts`），
+ * `packages/web` 那侧要从那次工具调用的入参里把它读回来渲染成一张卡片
+ * （`thread/rows.ts`，照 `todo` 的先例）。web 只依赖 protocol + view，够不着 core。
  *
- * ⚠️ **不给「你可以自己去读」这类下一步**，和 `OMIT_LABEL` 的 `binary` 那档
- * 不同：那一档有 `file_read` 真的能拿到内容，这一档模型没有任何办法看见像素。
- * 给一个不存在的出口，比不给更糟。
+ * ## ⚠️ 这里一个中文字都没有
  *
- * 逐字冻住，理由同 {@link OMIT_LABEL}（进模型 prompt、进 eval 指纹、不进 catalog）。
+ * 判据同 schedule-templates.ts 最后一节：措辞在 `locales/*.yaml` 的
+ * `web.ui.thread.draft_*` 底下（卡片）和 core 的工具输出里（给模型看的那半，
+ * 按 `locales/zh.yaml` 的范围说明不进 catalog）。
  */
-declare function imagePartOmittedSummary(part: EpochImagePart): string;
+
 /**
- * 引用的会话在纯文本投影里长什么样。**不吐那段会话的正文** —— 同 `filePartSummary`。
- *
- * ## 这一行刻意是英文 + 码，不是中文散文
- *
- * 它的读者有三个，**没有一个是界面**：模型（经 sdk-adapter 进上下文）、
- * `messages.content` 那一列（存盘 / 压缩 / 审计 / FTS）、以及宿主的日志。
- * 界面要展示这一部件时读的是结构化字段（`omitted` / `title` / `messageCount`），
- * 自己组措辞 —— TUI 那一侧的中文在宿主用 `t()` 拼，见 locales 的 `mention.*`。
- *
- * > ⚠️ 「没有一个是界面」这句话 2026-08-24 之前**有个洞**：`contentToText()`
- * > 会把这一行塞进 tui / web 的气泡里，于是它事实上也是界面的。洞补在
- * > §34.4 —— 界面改走 `contentToDisplayText()`，那一份把这一行换成
- * > catalog 的 `message_part.session*`。所以上面那句话现在是真的了。
- *
- * 所以这里直接把**那五个稳定错误码**原样写进去（§4.2）：宿主能 grep，模型能读，
- * 而且它不必跟着界面语言变 —— 一条落库的记录跟着 `EPOCH_LANG` 变语言，
- * 等于把同一段会话的历史劈成两半（`goal/wording.ts` 那条豁免记的是同一个坑）。
+ * 那个工具的名字。**真源在这儿而不是 core**，因为读它的有两个包：
+ * core 注册工具时用它，web 从工具流里认出那次调用时用它
+ * （`thread/rows.ts`）。
  *
- * 显示名用标题而不是 sessionId：后者是一串随机字符，对人和模型都没有信息量。
- * 标题为空的会话在解析那一侧已经用 sessionId 兜过底了（方案 53 §5.3）。
+ * ⚠️ 这一点上它和隔壁 `TODO_TOOL` 的做法不一样：那个名字今天在
+ * `web/src/thread/rows.ts` 里另写了一份字面量（那时 protocol 里没有落脚点）。
+ * 别照那个抄 —— 两份字面量漂了的表现是「卡片再也不渲染了」，而 typecheck
+ * 一声不响。
  */
-declare function sessionPartSummary(part: EpochSessionPart): string;
+declare const SCHEDULE_DRAFT_TOOL = "schedule_draft";
 /**
- * 取部件数组的纯文本投影：图片折成一句占位，绝不吐 base64；
- * 文件和引用的会话同样只折成一行占位，**不吐内容**。
- *
- * 投影是**存盘、压缩、审计**看的那一份。把几十 KB 的文件内容塞进来，
- * `sessions.db` 会跟着一起胖，而回放时那份内容本来就能从 `parts` 里拿。
- *
- * ## ⚠️ 这一份**只给模型和落库**，界面不许用它（RECORD-40-i18n §34.4）
- *
- * 改造前它一个人喂三类消费者，于是把界面切成 English 的人会在**自己那条消息的
- * 气泡里**看到 `[图片 image/png]` / `[文件 …：二进制文件，未附内容]`。
- * 这笔债在 §34.4 记了、§34.4 还掉，处置是**分家**：
+ * 草稿能落在哪几档权限上 —— **`bypass` 不在里面**。
  *
- * | 谁要 | 用哪一份 | 为什么 |
- * | ---- | -------- | ------ |
- * | 模型（`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.*`，住在两个宿主里 |
+ * 不是「运行期会拒绝」，是那一档在类型上根本不存在（判据同
+ * `ScheduleTemplate.permission`）。理由比模板那一侧更直接：`bypass` 要一次
+ * 二次确认（`bypass-not-confirmed`），而那次确认的**对象是人**；让模型提议
+ * 一个「等着人去勾确认框」的档位，等于把那道确认变成一道例行手续。
  *
- * 界面那一份**落在宿主层**而不是这儿，判据同 §34.6 给 `view` 那 1 处的做法
- * （兜底文案挪给渲染端）：这个包的依赖白名单是空的，`t()` 只能由有它的那一层调。
+ * 用户自己想要那一档时照旧走表单 —— 那条路一个字都没改。
  */
-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`。
- *
- * 这一行就是补那份证据：不复原过程，只留一句「这一轮真的调了这些工具」。
+ * 提议改一条**已有**的任务。
  *
- * ## 判据用**结果**而不是调用
+ * 每一格都可选（`undefined` = 这一格不动），但至少要动一格 —— 一份什么都不改的
+ * 提案是在浪费用户的一次点击。这条判定在 core 那侧
+ * （`schedule/draft.ts` 的 `draft-update-empty`）。
  *
- * `EpochToolCall` 上有工具名，但一次跑到一半被中止的轮次里那些调用**从没执行过**
- * （判据逐字同 `runtime/src/session-file-changes.ts` 的边界 1）。而一条
- * `EpochToolResult` 存在就意味着它跑完了 —— 拿结果当输入，「执行过没有」这件事
- * 不需要另外判一次。
+ * ## ⚠️ 「放宽」和别的改动在类型上长得一样，所以判定必须在别处
  *
- * ⚠️ **它分不出成功和失败**：落盘的结果上没有 `success`（同上那份的边界 2）。
- * 所以措辞是「调用过」而不是「做成了」—— 一次被权限拒掉的 `file_write`
- * 在这里照样留一笔，而那句话仍然是真的。
+ * 把超时从 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;
+/**
+ * 一次提案里「放宽了什么」的分类。
  *
- * ## 为什么住在 protocol、且是冻住的中文
+ * 只有三类，而三类都是**授权面变大**的方向：档位往松走、清单多了条目、
+ * 从停用变成启用。别往里加「超时变长」这种 —— 它花的是钱和时间，不是权限，
+ * 而把两种东西混进同一枚警示标，那枚标就不再有信息量。
  *
- * 它的读者是**模型**，和 {@link contentToText} / {@link filePartSummary} 同一类，
- * 所以走同一条规矩：住在这个零依赖的包里、逐字冻住、**不跟着界面语言变**
- * （门禁在 `packages/protocol/__tests__/message-projection.test.ts`）。一条进了
- * 上下文的历史跟着 `EPOCH_LANGUAGE` 变语言，等于把同一段会话劈成两半。
+ * 判定在 core（`schedule/draft.ts` 的 `draftWidening`），渲染在 web
+ * （`thread/schedule-draft.tsx`）—— 两侧各算一遍是刻意的，判据同
+ * `web/src/thread/rows.ts` 文件头那条：web 读的是**模型发出的原始入参**，
+ * 而不是 core 归一化之后的结论。
+ */
+type ScheduleWideningKind = 'permission' | 'allowlist' | 'enabled';
+
+/**
+ * 工作区信任契约。
  *
- * 只有工具名，不带参数 / 路径：带路径要 `affectedPaths()` + 工作目录，而那两样
- * 住在 core 和装配层，拿不到的地方（`loadHistory()`）就会退化成另一种措辞 ——
- * 两条路产出的历史一旦不一样，症状就是「刷新之后模型看到的和刚才不是同一段」。
+ * 为什么需要：clone 一个仓库就等于让它的 `AGENTS.md` 进 system prompt、
+ * 它的 hook 配置被执行、它的 policy 覆盖本地权限判定。这是漏洞，不是缺功能。
+ * 信任判定把「加载项目级配置」这件事收到一次显式用户决策后面。
  *
- * ⚠️ **调用方要的多半是 {@link assistantTurnText}，不是这一个** —— 那一份连
- * 「正文和这一行之间怎么接」一起定了，而那正是两条路会走散的地方。
+ * 竞品：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
  *
- * @param results 这**一轮**（不是一步）执行过的全部工具结果，按发生序
- * @returns 空数组时是空串 —— 这一轮没动手，那就没有这句话可说
+ * 这里只有类型，实现在 core —— 注意实现那边（`core/src/trust/manager.ts`）**是**
+ * gemini 的衍生作品（搬了「归一成生效目录再取最长匹配」那条算法），带头、在 NOTICE 里。
+ * 契约与实现的授权状态不同是对的，不是漏登记。
  */
-declare function turnDigest(results: readonly Pick<EpochToolResult, 'toolName'>[]): string;
+/** 一个目录的信任状态 */
+type TrustLevel = 
+/** 用户明确信任：加载项目指令 / hook / policy */
+'trusted'
+/** 用户明确拒绝：只当普通工作目录，不加载任何项目级配置 */
+ | 'untrusted'
+/** 还没问过 */
+ | 'unknown';
+/** 用户已经做过决策的信任状态（排除「还没问过」） */
+type DecidedTrustLevel = Exclude<TrustLevel, 'unknown'>;
+/** 信任决策的作用域 */
+type TrustScope = 
+/** 只这个目录 */
+'directory'
+/** 这个目录及其所有子目录 */
+ | 'directory-tree';
 /**
- * 一轮的 assistant 消息在**给模型的历史**里长什么样：正文 + {@link turnDigest}。
- *
- * ## 为什么这条胶水也得住在这儿
- *
- * 因为它有**两个调用方，走两条路，产出必须逐字节相同**：
+ * 一次授信授到哪一档（2026-09-11）。**两档是相加的：`exec` 蕴含 `read`。**
  *
- * - 直播：`runtime/src/agent-session.ts` 用 `TurnStepCollector` 收的那一轮；
- * - 恢复：`runtime/src/session-store.ts` 的 `loadHistory()` 从 DB 行折回来的那一轮。
+ * ## 为什么拆
  *
- * 两边各写一次 `text + '\n\n' + digest` 的下场是：某天一边多一个换行，
- * 而症状是**刷新页面之后模型看到的历史和刷新前不是同一段** —— `reloadHistory()`
- * 的 JSDoc 里那句「它们一旦分叉，症状就是屏幕上和模型看到的对不上」骂的正是这个。
- * 门禁是 `packages/runtime/__tests__/context-recency.test.ts` 里那条逐字节比对。
+ * 在它之前 `trusted` 是一个布尔，而那一个布尔后面挂着七样东西 —— 其中
+ * `.epoch/hooks.json` 和 `.claude/settings.json` 的每一项都是一条要 spawn 子进程的
+ * 命令（判据在 [core/hook/sources.ts](../../core/src/hook/sources.ts) 的文件头）。
+ * 而用户被问到的那句话逐字是「本目录的项目指令会加载」（`trust_prompt.granted`），
+ * **从来没提过 hook**。也就是说「往上下文里注入一段文本」和「在这台机器上执行
+ * 任意命令」共用了同一次点击，而问话只描述了前者。这不是 UX 问题，是知情同意错位。
  *
- * 正文为空、只有 digest 时**不留前导空行**：那一轮模型只调了工具没说话
- * （`loop.ts` 允许），这时这条消息的全部内容就是那一行。
+ * | 档  | 放开什么                                                        | 风险       |
+ * | --- | --------------------------------------------------------------- | ---------- |
+ * | `read` | 指令文件 / 技能 / 角色 / 命令                                  | 注入上下文 |
+ * | `exec` | `hooks.json` / `.claude/settings*.json` / `policies/` / settings 的 allow 那一半 | 执行、放宽判定 |
  *
- * @returns 空串 = 这一轮既没正文也没动手，调用方**别往历史里塞这一条**
- */
-declare function assistantTurnText(text: string, results: readonly Pick<EpochToolResult, 'toolName'>[]): string;
-/**
- * 部件类型的穷尽性守卫 —— **这是「加了一种部件却漏了一处分支」的那道会红的门禁**。
+ * ## ⚠️ 两条边界，别把它当别的东西
  *
- * 消费 `EpochContentPart` 的地方有五处（这里、`sdk-adapter` 的 `toSdkPart`、
- * `session/payload` 的 `persistParts` / `restoreParts`、以及展示层），改造前它们
- * 全都写成「if text / if file / 剩下的当图片」。那个形状下加一种部件**不会有
- * 任何东西变红**：新部件会被静默当成图片，而症状是模型收到一个 `image:` 里
- * 塞着会话正文的请求，provider 报 400。
+ * 1. **`exec` 不是权限档。** 它放开的是「这个仓库自带的 hook / policy 算不算数」，
+ *    不是「这次操作要不要问用户」——[两套机制照旧正交](../../core/src/trust/gate.ts)。
+ *    未授 `exec` 的目录里 agent 照样能跑 bash，只是仓库里那份 `hooks.json` 不生效；
+ * 2. **`read` 不是「安全档」。** 一份 `AGENTS.md` 能指挥 agent 去做任何它有权限做的
+ *    事，包括执行命令。拆开不是因为 `read` 无害，是因为**两者的问话不该合并成一次**。
  */
-declare function assertNeverPart(part: never): never;
-type EpochMessageRole = 'system' | 'user' | 'assistant' | 'tool';
+type TrustTier = 'read' | 'exec';
+interface TrustRecord {
+    /** 绝对路径（已 resolve） */
+    path: string;
+    level: DecidedTrustLevel;
+    /**
+     * 这条决策管到哪儿。
+     *
+     * `check()` 会把它折叠进 `TrustLevel`，所以判定方用不上；但**列出记录**的一方
+     * （`epoch trust` 要显示「仅此目录 / 含子目录」）必须能看见 —— 少了它，
+     * `list()` 返回的就不是一条完整的决策，而是一条读不懂的决策。
+     */
+    scope: TrustScope;
+    /** 记录时间戳（ms） */
+    decidedAt: number;
+    /**
+     * 执行类也授了吗（{@link TrustTier}）。`level: 'untrusted'` 时无意义。
+     *
+     * ⚠️ **缺省（`undefined`）= 没授**，而这一格正是存量记录的迁移：拆档之前写下的
+     * 记录没有这一格，于是升级之后它们**只剩读类** —— 判据就是上面那张表下面那段：
+     * 那些记录是在一句只说了「项目指令会加载」的问话下拿到的，把它们追认成执行类
+     * 等于替用户补签一份他没看过的同意书。代价（老用户的项目 hook 会停）由
+     * `trust_gate.exec_migrated` 那条诊断明说，不静默。
+     */
+    exec?: boolean;
+    /**
+     * 授 `exec` 那一刻，执行类输入文件的内容指纹（见 core 的 `trust/exec-hash.ts`）。
+     *
+     * 对不上 = 那些文件在授信之后被改过 → `exec` 退回未授，重新问一次。
+     * `exec` 为假时这一格不该存在。
+     *
+     * ## ⚠️ 这是对 [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` 压根不过闸门 —— 同一条判据的两侧，它也是这么分的。
+     */
+    execHash?: string;
+}
+/** {@link TrustManager.record} 的可选档位。不给 = 只授读类 */
+interface TrustGrant {
+    /** 连执行类一起授。**调用方必须真的为这一档单独问过用户** */
+    exec?: boolean;
+    /** 授 `exec` 时一并记下的内容指纹 */
+    execHash?: string;
+}
 /**
- * 一条会话消息。
- *
- * `content` 永远是字符串（tool 消息为空串，内容在 `toolResults` 里），
- * 这样「取这条消息的文本」永远不需要判类型。
+ * {@link TrustManager.checkExec} 的答案 —— **记录里写的，不含新鲜度校验**。
  *
- * 多模态**不是**把 `content` 放宽成联合类型 —— 那正是本文件开头骂过的病，
- * 会让 loop / codec / 压缩器每处都得判一次类型。改成加一个 `parts` 旁路：
- * `content` 仍然是权威的**文本投影**（压缩器、审计、持久化都只看它），
- * `parts` 只在 sdk-adapter 那一处被读走。两者的关系由 `contentToText` 保证。
+ * 两格一起交出来是因为校验方（`core/src/trust/gate.ts`）需要拿 {@link hash} 去和
+ * 现算的值比；拆成两次调用的话，两次之间可能命中**不同的记录**
+ * （`bestRecord()` 是按最长匹配现算的），于是拿 A 记录的授信配上 B 记录的指纹。
  */
-interface EpochMessage {
-    role: EpochMessageRole;
-    content: string;
+interface TrustExecGrant {
+    /** 记录里授过执行类吗 */
+    granted: boolean;
     /**
-     * 多模态部件。给了就以它为准喂模型，`content` 退化成它的文本投影。
-     * **不落 SQLite** —— 图片走 artifact 目录，DB 里只留 content 的占位文本。
+     * 授的时候记下的内容指纹。
+     *
+     * ⚠️ **`undefined` = 校验不了，而这一档照旧放行**（判据在 gate 的 `decide()` 上）。
+     * 今天所有写入口都会带上它，所以这一档只可能来自手改 `trust.json`。
      */
-    parts?: EpochContentPart[];
-    /** assistant 要求的工具调用；与 content 并存（模型可以边说话边调工具） */
-    toolCalls?: EpochToolCall[];
-    /** role 为 'tool' 时携带的执行结果 */
-    toolResults?: EpochToolResult[];
+    hash?: string;
+}
+interface TrustManager {
+    /** 查某个目录的信任状态（含父目录的 directory-tree 继承） */
+    check(dir: string): TrustLevel;
     /**
-     * 这一步模型的思考原文（推理模型的 `reasoning-delta` 累加）。2026-08-18。
-     *
-     * **只给人看，不回灌模型**：`sdk-adapter.ts` 一个字都不读它。加它是因为
-     * 刷新页面之前屏幕上有「深度思考」那一段，刷新之后整段消失 —— 而那不是
-     * 「这一轮没想」，是我们没记。
-     *
-     * ⚠️ **它属于某一步，不属于整轮。** 一轮里模型可以想一次、调个工具、再想一次，
-     * 每次的思考挂在**它自己那条 assistant 行**上，位置就是它真实的时序位置。
-     * 拿它当「整轮的思考」拼成一根，回放时那一段会被钉到最前面，讲的却可能是
-     * 二十步之后的事（web 的 `thoughtParts` 治过同一个病，判据在
-     * `web/src/state/reducer.ts` 的 `trackThought()`）。
-     *
-     * 落盘走 `messages.reasoning` 列 —— 那一列**从会话库 v1 就在**，只是一直没人
-     * 写过，所以这一档不需要迁移。
+     * 查某个目录的执行类授信（含继承）。**和 {@link check} 是两个问题**：
+     * 这一个只在 `check()` 回 `'trusted'` 时才可能授过，反过来不成立。
      */
-    reasoning?: string;
+    checkExec(dir: string): TrustExecGrant;
+    /** 记录一次决策 */
+    record(dir: string, level: DecidedTrustLevel, scope: TrustScope, grant?: TrustGrant): void;
+    list(): readonly TrustRecord[];
+    revoke(dir: string): void;
 }
 
 /**
@@ -6016,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';
 /**
@@ -6127,7 +6323,8 @@ type WireHubEvent =
     type: 'session-cooled';
 }
 /**
- * **会话列表变了** —— 多了一段，或者少了一段（2026-09-11）。
+ * **会话列表变了** —— 多了一段、少了一段，或者有一段被收进 / 移出归档
+ * （2026-09-11；归档那一档 2026-09-16 补）。
  *
  * ## 它治的是「不是我建的那一段」
  *
@@ -6156,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 那两个产地一模一样。
  *
- * 它的两个产地都在「进出 Hub」这条路上（建会话、删会话那两条端点）。而改标题
- * （`PATCH /api/sessions/:id`）压根不经过 Hub，只动 DB —— 于是另一个标签页上
- * 那一行的标题仍然会过期到下一次重取。📮 那一档要治得给它自己的产地，
- * 别照着这一帧的名字想当然。
+ * 症状是这一轮的正题（2026-09-16 用户实测）：在设置页「会话」那一分区点「取回」，
+ * 左边侧栏那份列表一动不动，**重启应用才看得见**取回来的那一段 —— 和上面那个
+ * 飞书宿主的原话逐字同形。产地在 `server/src/api.ts` 的 `patchSession`，
+ * **只在 `archived` 真的翻了的时候发**。
+ *
+ * ## ⚠️ 覆盖不到的那一档：**标题改了仍然不发这一帧**
+ *
+ * 同一条端点上的另一半：改标题不改变「列哪几段」，只改变某一行上的一格。
+ * 于是另一个标签页上那一行的标题仍然会过期到下一次重取。📮 那一档要治得给它
+ * 自己的产地（一帧带得动「哪一行的哪一格变了」的事件），别顺手挂到这一帧上 ——
+ * 让所有标签页因为别人改了个名字就重取一次整份列表，是拿错误的粒度换方便。
  */
  | {
     type: 'sessions-changed';
@@ -7345,8 +7555,59 @@ interface WireConfigResponse {
      * 而其中第一条是一句**关于浏览器在哪儿**的推断。
      */
     nativeDirPicker: boolean;
+    /**
+     * **上次停留的那段会话**（2026-09-14）。首屏该开的是它，不是 {@link sessionId}。
+     *
+     * ## 它和 `sessionId` 的分工
+     *
+     * `sessionId` 是**这个进程**装配出来的引导会话，恒新、恒空 —— 首屏照它开，
+     * 用户每启动一次就看见一段「未命名会话」，昨天那段活得自己去侧栏里翻。
+     * 这一格是**上一个进程退出时界面停在哪儿**（服务端那份 `~/.epoch/last-sessions.json`
+     * 记的，由 `PUT /api/last-session` 写）。第一方界面的口径是
+     * `lastSessionId ?? sessionId`。
+     *
+     * ## ⚠️ 没记过 / 那段已经被删了 → **不带这个键**（同 `maxCostUsd` 那一族）
+     *
+     * 服务端在下发之前会按**和 404 同一份判据**查一次它还在不在，查不到就整个不带。
+     * 所以客户端那句 `?? sessionId` 就是「找不到就开一段新的」，**不需要**第二段
+     * 兜底逻辑，更不该自己再去 `GET /api/sessions/:id` 探一发 —— 那是同一个问题的
+     * 第二个说法，而两个说法迟早不一致。
+     *
+     * ⚠️ 它是**可选键**，所以故意不在 {@link WIRE_CONFIG_FIELDS} 上（见那张表上的 ⚠️）。
+     */
+    lastSessionId?: string;
 }
 declare const WIRE_CONFIG_FIELDS: WireFields<WireConfigResponse>;
+/**
+ * `PUT /api/last-session` —— 「我现在停在这段会话上」（2026-09-14）。
+ * 服务端记下来，**下一次启动**的 {@link WireConfigResponse.lastSessionId} 就是它。
+ *
+ * ## 三件容易理解反的事
+ *
+ * 1. **URL 上没有 `:sessionId`，而且不该有。** 落点是 `~/.epoch/last-sessions.json`
+ *    ——一台机器一份、按项目根分格的**进程级**记录。挂到 `/sessions/:id/` 底下会
+ *    得到一条名字是会话级、行为是机器级的端点（判据逐字同 `mcp/:name/reconnect`
+ *    那一条）。会话 id 是**载荷**，因为它是被记的那个**值**。
+ * 2. **它不改这段会话的任何东西**，也不要求它是活的 —— 只要求它在会话库里还在
+ *    （不在就 404，判据同别处那道 `unknown-session`）。校验在服务端的理由：
+ *    客户端因此可以无脑上报，不必先探一发「这个 id 还有效吗」。
+ * 3. **`PUT` 不是 `POST`。** 同一个项目反复报同一段会话是常态（每次切会话、
+ *    每次刷新都报一次），而结果只有一个格子被覆盖 —— 幂等的写该是 `PUT`。
+ *    非 GET 这件事本身也是必须的：它要过 `auth.ts` 那道 Origin 闸，因为它会往
+ *    用户磁盘上写文件。
+ */
+interface WireLastSessionRequest {
+    sessionId: string;
+}
+declare const WIRE_LAST_SESSION_FIELDS: WireFields<WireLastSessionRequest>;
+/**
+ * 记下来了。**回执里不带 id** —— 带的话就等于在网线上多了一个「当前是哪段」的
+ * 说法，而那件事的真源是 URL（`/s/<id>`），不是这条端点。
+ */
+interface WireLastSessionResponse {
+    ok: true;
+}
+declare const WIRE_LAST_SESSION_RESPONSE_FIELDS: WireFields<WireLastSessionResponse>;
 /**
  * 列表里的一行**和工作区的关系** —— 三档（决定 18；`unknown` 那一档是会话库 v7
  * 加的，2026-08-19）。
@@ -7661,6 +7922,18 @@ interface WireSessionSummary {
      * 普通列举时缺席（所以它是可选的，不进下面那份必填清单）。
      */
     snippet?: string;
+    /**
+     * 这段会话被收进归档了吗（方案 64 PR-2）。
+     *
+     * **必填，不是可选**：界面上这一格决定「要不要画那枚归档记号」以及
+     * 「那一行的操作是归档还是取回」，而 `undefined` 在那两处都会被读成 `false` ——
+     * 于是一个归档过的会话在归档列表里长得和普通会话一模一样，操作还是「归档」。
+     *
+     * ⚠️ **Hub 里有、DB 里还没有的那种行（新会话第一条消息落盘之前）一律 `false`。**
+     * 那是**实话**不是兜底：一段还没落盘的会话根本没有归档状态可言，
+     * 而它按定义不可能被归档过（归档写的是 DB 里那一列）。
+     */
+    archived: boolean;
 }
 /**
  * 上面那张接口的必填清单。**要数字段有几个，数这里，别在别处手抄**（抄过去的那份
@@ -7904,14 +8177,46 @@ interface WireDeleteSessionResponse {
 }
 declare const WIRE_DELETE_SESSION_FIELDS: WireFields<WireDeleteSessionResponse>;
 /**
- * 重命名。今天只有 `title` 一个可改字段。
+ * 改一段会话的元信息。
+ *
+ * ## 「将来」到了（方案 64 PR-2，2026-09-14）
  *
- * 写成对象而不是裸字符串，是为了将来加 `pinned` / `archived` 时不换形状 ——
- * 那时这里多一个可选字段，老客户端一行不用改。
+ * 上一版这里写着「今天只有 `title` 一个可改字段……将来加 `pinned` / `archived`
+ * 时不换形状，那时这里多一个可选字段，老客户端一行不用改」。`archived` 那一格
+ * 现在真的来了，而那句预言**兑现了**：老客户端仍然只发 `title`，一个字不用改。
+ *
+ * ⚠️ **两个字段都是可选的，但不能一个都不给。** 服务端对「两个都没给」回 400 ——
+ * 一次什么都不改的 PATCH 是调用方写错了，静默回 200 会让它以为改成功了。
+ * 判据在 `server/src/api.ts` 的 `patchSession` 上。
+ *
+ * ⚠️ `title` 仍然**不许是空串**（那条老判据一个字没变）：空标题不是「清空」
+ * 而是「没给」—— 标题空着的会话在列表里只剩一个 uuid，而那正是用户点重命名
+ * 想解决的问题。要只改归档状态就别带 `title` 这个键。
  */
 interface WirePatchSessionRequest {
-    title: string;
+    title?: string;
+    /**
+     * 收进归档（`true`）还是从归档里取回（`false`）。
+     *
+     * **归档不是删除**：它只把这段会话从默认列表和模糊搜里收起来，消息一条不少、
+     * 给了 id 照样读得出来。判据是 core 的 `session/authorization.ts` 那张
+     * 「全仓唯一一份」的表 —— 那张表这一份只用、不改。
+     */
+    archived?: boolean;
 }
+/**
+ * ⚠️ **空清单，而且只能是空的。**
+ *
+ * `wireFields` 收的是**必填**字段（那条约束写在它自己的 JSDoc 第三节上：
+ * 可选键写进清单就等于在运行时把它变成必填，于是一个合法的、没带那个字段的
+ * 请求会被 `conformsToWire()` 判成不合契约）。这张请求上两个字段都是可选的 ——
+ * 只改名的调用方不带 `archived`，只归档的不带 `title`。
+ *
+ * 于是「至少给一个」这条约束**没有地方由类型来守**，它由服务端那道 400 守
+ * （`server/src/api.ts` 的 `patchSession`）。这是刻意的分工：`wireFields`
+ * 管的是「字段在不在」，管不了「这几个里至少要有一个」——
+ * 硬把它塞进来的代价是让两种合法请求各自不合契约。
+ */
 declare const WIRE_PATCH_SESSION_FIELDS: WireFields<WirePatchSessionRequest>;
 /**
  * 改完之后的那一行 —— **回整行而不是回 `{ok:true}`**。
@@ -7997,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[];
@@ -8027,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>;
 /**
@@ -8121,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 那一半）。
      *
@@ -8243,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>;
 /**
@@ -10281,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；本地源与市场管理
@@ -10547,18 +11048,34 @@ declare const WIRE_PLUGIN_UPLOAD_FORM_FIELDS: readonly ["displayName", "descript
 /** {@link WIRE_PLUGIN_UPLOAD_FORM_FIELDS} 里的一格 */
 type WirePluginUploadFieldName = (typeof WIRE_PLUGIN_UPLOAD_FORM_FIELDS)[number];
 /**
- * 上传表单上一格在浏览器眼里的样子（2026-09-10）。
+ * 下拉里的一项（2026-09-15）。**两格都恒有** —— 宿主写 `'office'` 这种裸字符串
+ * 时 `label` 在 runtime 那一侧就补成了同一个值，判据同下面那条「界面要的是结论」。
+ */
+interface WirePluginUploadChoice {
+    /** 真发上去的那个值。它要和宿主自己那份目录里的分类名逐字相同 */
+    value: string;
+    /** 屏幕上印的那几个字 */
+    label: string;
+}
+/**
+ * 上传表单上一格在浏览器眼里的样子（2026-09-10 两格 → 2026-09-15 四格）。
  *
- * ⚠️ **两格都恒有**（`value` 空串 = 宿主没预填，`editable` 恒是布尔）——
- * 口径同 `WirePluginsResponse.uploadOptions`：界面要的是结论，不是三种等价写法。
+ * ⚠️ **四格都恒有**（`value` 空串 = 宿主没预填，`editable` / `required` 恒是布尔，
+ * `choices` 空数组 = 这一格不是下拉）—— 口径同 `WirePluginsResponse.uploadOptions`：
+ * 界面要的是结论，不是三种等价写法。
  */
 interface WirePluginUploadField {
     /**
-     * 预填的值。**宿主没给就是空串**。
+     * **宿主**预填的值。没给就是空串。
      *
-     * ⚠️ 它**不是从包里读出来的** —— 这一屏上从包里读出来的那几样（名字 / 版本 /
-     * 描述 / 作者）是**印在上面的事实**，不是表单的默认值。判据在
-     * `HostMarketplaces` 的 `PluginUploadField.value` 上。
+     * ⚠️ **它不是这一格最终从什么值开始** —— 那个答案在
+     * {@link WirePluginUploadPreviewResponse.prefill} 上（2026-09-15 起还有
+     * 第三个来源：包里那份 `epoch-plugin.json` 的同名格）。这一格只说宿主
+     * 那一侧写了什么，而它排在包里那一份**前面**（四档优先级见那一处）。
+     *
+     * ⚠️ 所以界面上**别拿它当输入框的初值**：它只在 {@link editable} 为假那一档
+     * 直接上屏（印着的那段静态文字）。真要画的初值一律走 `prefill`，
+     * 否则「这一格该填什么」在浏览器里就有了第二个答案。
      */
     value: string;
     /**
@@ -10573,6 +11090,38 @@ interface WirePluginUploadField {
      * `PluginUploadForm` 上那两条规矩）。少了那一半，改一次请求体就绕过去了。
      */
     editable: boolean;
+    /**
+     * 能挑的就这几个（2026-09-15）。**非空 = 这一格画成 `<select>`。**
+     *
+     * ## ⚠️ 判据是 `choices.length > 0`，不是 `choices` 本身
+     *
+     * 这一格恒有（不画下拉那几格是 `[]`，不是缺席也不是 `null`），而 `[]` 在 JS
+     * 里是**真值** —— 写成 `shape.choices ? … : …` 的那天每一格都会变成一个
+     * 零选项的下拉，而类型上一点问题都没有。这仓库为这件事栽过。
+     *
+     * ## ⚠️ 它是**闭集**，而那一半同样在服务端兑现
+     *
+     * 「下拉是形态，开集是契约」（判据全文在 `shell/model-menu.tsx` 的文件头）：
+     * 宿主给了单子就是在说它那份目录只认得这几类。所以 runtime 那一层会把
+     * **单子外的值整个丢掉**，和 {@link editable} 那一条是同一条规矩的第三半。
+     *
+     * ⚠️ 它还管着**包里那一份**：上传者在 `epoch-plugin.json` 里写的同名格
+     * 只有命中这张单子才会进 {@link WirePluginUploadPreviewResponse.prefill}。
+     *
+     * ⚠️ `visibility` 那一格恒是 `[]`（它的值域固定两档、屏幕上画的是两枚单选）。
+     */
+    choices: readonly WirePluginUploadChoice[];
+    /**
+     * 空着就发不出去吗（2026-09-15）。
+     *
+     * ⚠️ **界面上那一道只是「别让他白按一下」**：标签上一个 `*`、空着时那枚
+     * 「确认上传」是禁用的。真正算数的在服务端 —— 必填格空着时 `POST /api/plugins/upload`
+     * 回一档 `missing-field`，**宿主回调一次都不调**。判据逐字同 {@link editable}。
+     *
+     * ⚠️ `visibility` 上它恒是 `false` 且没有意义：那一格恒有值（认不出的退
+     * `private`），永远不会空着。
+     */
+    required: boolean;
 }
 /**
  * 七格的形态表 —— **每个键恒有，不画的那几格是 `null`**。
@@ -11120,7 +11669,15 @@ type WirePluginRefuseReason = 'unknown-ref' | 'not-local'
  * - `not-plugin`   —— 解开了，但里面没有 `epoch-plugin.json`。
  *   下一步：确认拖的是插件本身那一层，而不是装着它的那个上级目录。
  */
- | 'not-archive' | 'unpack-failed' | 'not-plugin' | 'remote-disabled' | 'conflict' | 'stale-token' | 'not-installed' | 'nothing-to-do' | 'upload-unavailable' | 'refresh-unavailable' | 'upload-rejected' | 'failed';
+ | 'not-archive' | 'unpack-failed' | 'not-plugin' | 'remote-disabled' | 'conflict' | 'stale-token' | 'not-installed' | 'nothing-to-do' | 'upload-unavailable' | 'refresh-unavailable' | 'upload-rejected'
+/**
+ * 宿主标了必填的格子还空着（2026-09-15）。**下一步在用户那儿**（回去把那几格
+ * 填上），所以不并进 `failed`（那一档的下一步是「看 detail 重试」）。
+ *
+ * ⚠️ 界面上正常走不到这一档（那枚按钮在必填格空着时是禁用的）—— 它拦的是
+ * **改了请求体那一发**，判据同 `editable: false` 为什么在服务端兑现。
+ */
+ | 'missing-field' | 'failed';
 /** 一次 hook 盘点：这个事件上有几条 */
 interface WirePluginHookTally {
     type: string;
@@ -11426,6 +11983,31 @@ interface WirePluginUploadPreviewResponse {
     plan: WirePluginUploadPlan | null;
     /** 成了才有。原样发回 {@link WirePluginUploadConfirmRequest.token} */
     token: string | null;
+    /**
+     * 那张表单**每一格从什么值开始**（2026-09-15）。成了才有。
+     *
+     * ## ⚠️ 它和 `uploadOptions` 各答一半，别拿一格顶两格
+     *
+     * `GET /api/plugins` 那份 {@link WirePluginUploadFields} 答的是
+     * 「**这一屏画成什么样**」（画哪几格、哪几格用户改不动）—— 它是装配期定死的，
+     * 和用户选了哪个目录无关。这一格答的是「**这一次**每一格填什么」，
+     * 而它要等读到包里那份 `epoch-plugin.json` 才知道。
+     *
+     * ⚠️ **界面把它原样塞进表单 state 就行，不用再和 `uploadOptions` 合并一次** ——
+     * 四档优先级（宿主锁死 > 宿主初值 > 包里同名格 > 空）在服务端算完了。
+     * 在浏览器里再算一遍的话，「这一格该填什么」就有了两个答案。
+     *
+     * ⚠️ 只含**宿主真声明了的**那几格，口径同 {@link WirePluginUploadForm}。
+     */
+    prefill: WirePluginUploadForm | null;
+    /**
+     * {@link prefill} 里**值是从包里读出来的**那几格（2026-09-15）。成了才有。
+     *
+     * ⚠️ 它只管屏幕上那一句提示，一个判断都不参与。没有它的话界面分不出
+     * 「宿主替你填的」和「你自己在包里写的」—— 而用户的下一步不一样：
+     * 前者去问宿主，后者去改自己那份 `epoch-plugin.json`。
+     */
+    fromManifest: readonly WirePluginUploadFieldName[] | null;
     /** 没成才有 */
     reason: WirePluginRefuseReason | null;
     /** 没成才有。**服务端渲染好的一句人话**，界面原样上屏 */
@@ -12528,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）。
@@ -12706,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 {
     /**
@@ -12769,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 {
@@ -12856,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>;
 
@@ -14024,6 +14666,46 @@ interface WireSchedulePendingResponse {
     items: readonly SchedulePendingItem[];
 }
 declare const WIRE_SCHEDULE_PENDING_FIELDS: WireFields<WireSchedulePendingResponse>;
+/**
+ * 一条正在跑的任务。
+ *
+ * ⚠️ **只有两格，而缺的那两格是刻意的**：底下那张锁表里还有 `pid` 和 `host`，
+ * 它们**不上网线** —— 界面画不了它们（写一个 pid 在卡片上没有任何人用得上），
+ * 而把本机的进程号推给浏览器是白送的信息泄露。要排查「是哪个进程占着」的人
+ * 手上有那张表本身（`sqlite3 ~/.epoch/sessions.db`）。
+ */
+interface WireRunningSchedule {
+    scheduleId: string;
+    /** 抢到锁那一刻（epoch 毫秒）。界面上那个走秒的数拿它减出来 */
+    startedAt: number;
+}
+declare const WIRE_RUNNING_SCHEDULE_FIELDS: WireFields<WireRunningSchedule>;
+/**
+ * `GET /api/schedules/running` —— 自动化那一屏上每张卡「在不在跑」的真源。
+ *
+ * ## 它答的是那一发 `GET /api/schedules` 答不了的事
+ *
+ * 那一发里的 `recentRuns` 要等一轮**跑完**才有行（执行器是收尾时才 `recordRun`
+ * 的），所以在它跑着的那几分钟里，整个系统里唯一记着这件事的地方是那张锁表。
+ * 而**手点「先跑一次」和到点自己跑抢的是同一把锁** —— 于是界面上「谁在跑」
+ * 只有一个真源，不用把两种来源缝起来。
+ *
+ * ## ⚠️ 单开一条，理由逐字同 {@link WireSchedulePendingResponse} 那一节
+ *
+ * 那一发回的是「全部任务 + 最近 100 条运行 + 一次平台探测 + 表单缺省」，
+ * 而这一格**要每几秒问一次**。把它塞进那一发等于让每一次轮询都付那份钱。
+ *
+ * ## ⚠️ 这一条**必须**靠客户端轮询，而那不是偷懒
+ *
+ * 到点触发跑在另一个进程里，服务进程不知道它存在 —— SSE 上没有任何一帧能报它
+ * （同上面那一节）。所以第一方界面在**自动化那一屏开着时**每 5 秒拉一次，
+ * 别的屏一发都不发。自己画前端的宿主不拉也不会坏，只是那个转子不会出现。
+ */
+interface WireScheduleRunningResponse {
+    /** 顺序不当契约（锁表没有有意义的排序）。一条都没跑时空数组 */
+    items: readonly WireRunningSchedule[];
+}
+declare const WIRE_SCHEDULE_RUNNING_FIELDS: WireFields<WireScheduleRunningResponse>;
 
 /**
  * 目标那一格的网线形状（[方案 52](../../../docs/verify/VERIFY_RECORD-52-goal.md) PR-4 的
@@ -14617,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_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_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_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 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 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 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 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 };