@epoch-agent/protocol 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -114,12 +114,18 @@ interface PlanProposal {
 /**
  * 计划审批独有的三个出口。第四个出口是 `deny`（拒绝），与工具审批**共用** ——
  * 「不批」这件事在两种审批里语义相同，没必要有两个名字。
+ *
+ * ⚠️ **这里只有码，没有文案。** 四个出口的显示文字在 catalog 的 `approval.*` 下
+ * （`plan_execute` / `plan_readonly` / `plan_revise` / `deny`），cli / tui / web
+ * 三个宿主共用那四条。以前这个文件里还有一个 `PLAN_OUTCOME_LABELS` 常量装中文，
+ * 2026-08-22（RECORD-40-i18n §34.2）删了：protocol 是零依赖层，够不着 `t()`，所以任何
+ * 装在这里的文案都只能是**单语言**的 —— web 当时被迫在自己的 catalog 段下抄了
+ * 第二份，再用一条用例锁住两边逐字相等。判据同 `Diagnostic.module`：**协议层出码，
+ * 文案在 catalog**。
  */
 declare const PLAN_OUTCOMES: readonly ["plan-execute", "plan-readonly", "plan-revise"];
 type PlanApprovalOutcome = (typeof PLAN_OUTCOMES)[number];
 declare function isPlanOutcome(value: string): value is PlanApprovalOutcome;
-/** 计划审批四个出口各自的一行说明。宿主直接拿去当选项文案，别各写一份 */
-declare const PLAN_OUTCOME_LABELS: Record<PlanApprovalOutcome | 'deny', string>;
 
 /**
  * 权限契约。
@@ -356,6 +362,23 @@ interface ToolContext {
     homeDir?: string;
     /** 当前权限级别 */
     permissionLevel: string;
+    /**
+     * `terminal` 家族的 OS 沙箱开关（`EpochConfig.sandbox.terminal`，方案 46 §11.3
+     * 第一条）。**不给 = 开着**，也就是没有这个字段之前的行为，逐字节相同。
+     *
+     * 唯一的消费者是 `plugin-terminal` 的 `sandboxPolicyFor()`；`code_exec` 那条路
+     * 走另一个接缝（`isolate()`），**不读这一格**。为什么开关在这里而不是让插件
+     * 自己去读配置：插件按分层只许依赖 protocol + infra，够不着 core 的 loader ——
+     * 而这一格是引擎侧唯一同时握着「用户的配置」和「这一次工具调用」的地方。
+     *
+     * ⚠️ **判它必须显式跟 `false` 比**（`ctx.sandboxTerminal !== false`）。
+     * 写成裸真值判断的话，任何一个没填这一格的宿主（嵌入宿主自己拼 `ToolContext`
+     * 是支持的用法）都会**静默失去 OS 强制的写入边界**，而工具输出那一行沙箱说明
+     * 会一致地跟着说「关」—— 于是看起来像是用户自己关的。缺省朝「开」是刻意的：
+     * 漏填这一格的表现是**开关失灵**（配了 `false` 却照旧有沙箱），
+     * 而那种失败用户报得出来。
+     */
+    sandboxTerminal?: boolean;
     /** 取消信号（AbortController.signal） */
     signal?: {
         readonly aborted: boolean;
@@ -373,6 +396,50 @@ interface ToolContext {
      * 调用它是**同步且廉价**的（往缓冲区里塞一段字符串），可以在 data 事件里直接调。
      */
     onOutput?: (chunk: string) => void;
+    /**
+     * 从一个工具里再调一次工具（方案 51「不是绕过审批的后门」）。**这是 `run_code` 的子调用通道。**
+     *
+     * ## 它不是后门，是同一条管线的入口
+     *
+     * 引擎侧把它实现成**递归调用 `ToolExecutor.execute()` 自己**，所以一次子调用
+     * 逐字走完和模型直接调那个工具一模一样的五步：危险命令表 → 权限规则
+     * （deny > ask > allow）→ 审批 → 沙箱 → 不可信内容包裹。
+     *
+     * 方案 51「不是绕过审批的后门」 那句话是硬要求：「`run_code` 的工具绑定必须走 `ToolExecutor`，
+     * 不许直连 `tool.execute()`」。**在别处包一层门面绕过它，就是把审批关掉。**
+     *
+     * ## 引擎侧还叠了两道，判据都不在这个字段上
+     *
+     * 1. **只放行只读工具**（方案 51 PR-1 的范围，判据在 core 的
+     *    `code-mode/readonly.ts`）—— 写类工具要等 PR-3 的审批取舍先拍板；
+     * 2. **只有第一层拿得到它。** 一次子调用自己的 `ToolContext` 里**这一格是缺席
+     *    的**，于是「工具 A 调 B、B 再调 C」这条路在第二跳就断了。少了它，
+     *    一个工具就能靠自己调自己把线程转到底。
+     *
+     * ## 不给 = 这条通道没接上，`run_code` 报错
+     *
+     * 缺省朝「不可用」是刻意的：嵌入宿主自己拼 `ToolContext` 是支持的用法，
+     * 而漏填这一格的表现是**工具明说自己不可用**，不是一条静默绕过管线的路。
+     * 方向和 `sandboxTerminal` 那一格相反，因为两者「漏填」的危险面相反 ——
+     * 那一格漏了会少一层边界，这一格漏了只是少一个能力。
+     */
+    callTool?: SubToolCall;
+}
+/** {@link ToolContext.callTool} 的形状 */
+interface SubToolCall {
+    (name: string, args: Record<string, unknown>): Promise<SubToolCallResult>;
+}
+/**
+ * 一次子调用的结果。
+ *
+ * **只有两格，刻意的**：`output` 是**过完整条链之后**的那份文本（含不可信包裹和
+ * 截断），也就是模型直接调那个工具时会看到的**同一份**。交原始 `ToolResult`
+ * 的话，`run_code` 的程序会看到一份比模型更「干净」的输出 —— 那等于给它开了一条
+ * 跳过输出治理的路，而那些治理（截断、包裹）本来就是安全和成本的一部分。
+ */
+interface SubToolCallResult {
+    success: boolean;
+    output: string;
 }
 /** 工具执行结果 */
 interface ToolResult {
@@ -463,10 +530,25 @@ interface ToolProvider {
 /**
  * 国际化契约（方案 40）。
  *
- * 这里**只有值域**，没有实现 —— `t()` / `setLang()` / `resolveLang()` 住在
- * [infra/src/i18n.ts](../../infra/src/i18n.ts)。分开的理由和 `SHELL_KINDS`
- * 一样：tui / web / cli 都要能写出 `Lang` 这个类型，而它们里面有两个
- * （tui、web）连 infra 都不许依赖。
+ * ## 这里有什么、没有什么（边界 2026-08-22 挪过一次）
+ *
+ * | 在这儿                              | 不在这儿                                          |
+ * | ----------------------------------- | ------------------------------------------------- |
+ * | **值域**：{@link Lang} / {@link LANGS} / {@link DEFAULT_LANG} | 加载：读盘、找 `locales/` 目录、缓存        |
+ * | **纯查表**：{@link makeTranslate} / {@link flattenCatalog} / {@link placeholdersOf} | 进程级状态：`setLang()` / `currentLang()` / `resolveLang()` |
+ *
+ * 右边那一列住在 [infra/src/i18n.ts](../../infra/src/i18n.ts)。
+ * 分界是**「有没有 I/O 和状态」**：纯函数放这儿，读盘和进程语言放 infra。
+ *
+ * > ⚠️ 这段原来写的是「这里**只有值域**，没有实现」。2026-08-22（方案 40 PR-2）
+ * > 把纯查表提上来了，理由是**第三个消费方**：tui 只许依赖 protocol + view，
+ * > 而 web 已经为此在 `web/src/i18n/catalog.ts` 抄了一份 `t()`（那个文件头自己
+ * > 写着「两份 t() 会走散」）。tui 再抄一份就是三份。提上来之后 web 和 tui
+ * > 兼一份实现，infra 那份留着（它是零内部依赖包，import 不了这里 ——
+ * > 判据写在 {@link makeTranslate} 上）。
+ *
+ * 分开的理由和 `SHELL_KINDS` 一样：tui / web / cli 都要能写出 `Lang` 这个类型，
+ * 而它们里面有两个（tui、web）连 infra 都不许依赖。
  *
  * ## ⚠️ 值域是封闭的：`zh` 和 `en`，没有第三个
  *
@@ -541,6 +623,71 @@ declare function isLang(value: string): value is Lang;
  * （浏览器的系统偏好，不是用户在设置页里选的那一档）。逐条判据在方案 58 §1.1。
  */
 declare const WIRE_LANG_PARAM = "lang";
+/**
+ * 一条文案的占位符取值。
+ *
+ * 数字也收：`{count}` 那种地方调用方手动 `String()` 一遍纯属噪音，
+ * 而 `t()` 里本来就要 `String()`（判据在 {@link makeTranslate}）。
+ */
+type TranslateVars = Record<string, string | number>;
+/** 取一条文案的签名。tui 的 `t()` 和 web 的 `useT()` 拿到的都是它 */
+type Translate = (key: string, vars?: TranslateVars) => string;
+/** 一份拍平的 catalog：点分 key → 文案 */
+type FlatCatalog = Record<string, string>;
+/** 语言 → 拍平的 catalog。宿主注入 / 构建期注入的那份就是这个形状 */
+type Catalogs = Partial<Record<Lang, FlatCatalog>>;
+/**
+ * 一句文案里用到的占位符（去重，按出现顺序）。
+ *
+ * 导出它是因为**判据必须只有一份**：查表按这个正则替换，一致性用例按同一个正则
+ * 比对 zh / en 两边。抄成两份的话，「翻译时漏了 `{path}`」这种错误就会从
+ * 「用例红」退化成「运行时少一句关键信息，而且不报错」。
+ */
+declare function placeholdersOf(text: string): string[];
+/**
+ * 把嵌套的 catalog（yaml 解出来的那棵树）拍成点分 key。
+ *
+ * 非字符串的叶子（数字、布尔、数组）**直接丢掉**而不是 `String()` 一下：
+ * catalog 里出现它们一定是写错了，静默转成 `[object Object]` 只会让错误晚几个
+ * 小时才被发现。丢掉之后根那条一致性用例会把它报成「zh 有 en 没有」。
+ *
+ * 住在 protocol 是因为**读盘的人和不读盘的人都要它**：web 的 vite 插件在 node 上
+ * 读 yaml、tui 的用例夹具也读 yaml，而这两个包都不许 import infra。
+ */
+declare function flattenCatalog(value: unknown, prefix?: string, out?: FlatCatalog): FlatCatalog;
+/**
+ * 绑一组 catalog，得到查表函数 —— **三层回落，永不抛**。
+ *
+ * ```
+ * 目标语言的 key → DEFAULT_LANG 的 key → 返回 key 路径本身
+ * ```
+ *
+ * 第三层是关键：**catalog 写坏了不能让界面白屏 / 终端空行**。最坏情况用户看到
+ * `tui.commands.help_title` 这种字符串 —— 难看，但能跑。
+ *
+ * `vars` 里没给的占位符**原样留着**（`{path}` 照样显示）：换成空串会让一句话
+ * 看起来完好无损、实际丢了关键信息，那正是最难查的形态。
+ *
+ * ## 为什么是工厂而不是直接读一个模块级常量
+ *
+ * 为了**回落链能被单独测**：「en 缺一条 → 回落中文」这种场景拿真 catalog 造不出来
+ * —— 根 `__tests__/i18n-catalog.test.ts` 恰好钉着两边 key 集合完全相同。
+ * infra 那边用 `EPOCH_LOCALES_DIR` 指一个临时目录达到同样效果，
+ * 而浏览器和 tui 里没有那个东西，所以换成注入。
+ *
+ * ## ⚠️ infra 里还有一份**同语义**的实现，那不是漏改
+ *
+ * `infra/src/i18n.ts` 的 `t()` 走的是同一条回落链，但它**不能**调这里 ——
+ * infra 是零内部依赖包（`check-layers.mjs` 的 `ALLOWED` 里它的内部依赖是空的，
+ * 只挂着三个没有源码的 vendor-ripgrep）。这跟 {@link LANGS} 在两边各写一份是
+ * 同一个形状、同一个办法：**抄一份 + 一条钉住「两边行为逐项相等」的用例**
+ * （根 `__tests__/i18n-catalog.test.ts`）。
+ * 反过来把 infra 那份删掉、让它 import protocol，等于把 protocol ← infra 这条
+ * 依赖方向反过来 —— 那是 `check:layers` 当场打红的事。
+ */
+declare function makeTranslate(catalogs: Catalogs): (lang: Lang, key: string, vars?: TranslateVars) => string;
+/** 绑定语言，得到一个 {@link Translate}。tui 和 web 的 React 那半边都用它 */
+declare function translatorFor(catalogs: Catalogs, lang: Lang): Translate;
 
 /**
  * 启动诊断的契约（方案 17）。
@@ -604,6 +751,21 @@ interface Diagnostic {
      *
      * 同一个模块的多条诊断共用一个 module（比如 Trust 可能既有 OK 也有一条说明）。
      * 按 server / 插件分格的用 `MCP <name>` 这种带实例名的形式。
+     *
+     * ⚠️ **一律英文 PascalCase**（2026-08-23 定死，RECORD-40-i18n §32.2）。它是标识符不是文案，
+     * 所以**永远不进 catalog、永远不走 `t()`** —— 翻它等于把宿主的分支和去重键换掉。
+     * 而「不翻」还剩两种写法，这一条要的是后者：
+     *
+     * - ❌ 中文标识（`Agent 角色` / `额外目录`）：不翻，于是英文界面上 `epoch doctor`
+     *   的第一列是「一堆英文夹几个中文」，而那一列正是宿主和用户都拿来对齐的东西；
+     * - ✅ 英文标识（`AgentRole` / `ExtraDirs`）：两种界面语言下第一列都一样。
+     *
+     * 单复数跟着这一行说的东西走（`Plugin` 是一个子系统、`ExtraDirs` 是用户给的一批
+     * 目录），**不算契约的一部分** —— 契约只是「这个字符串不许变」。
+     *
+     * 门禁是 i18n 那个棘轮（`scripts/i18n-scan.mjs`）：module 是字面量，新写一个中文的
+     * 当场把基线顶上去。⚠️ 它数的是中文，所以**只挡得住中文标识**，挡不住把一个已有的
+     * 英文标识改个字面 —— 后者只有引用它的用例会红。
      */
     module: string;
     status: DiagnosticStatus;
@@ -784,6 +946,80 @@ interface AgentRole {
      * 不含 `terminal` 也不含 `code_exec`，那时它才是硬边界。
      */
     tools?: string[];
+    /**
+     * 技能索引白名单（2026-08-26）。**缺省语义同 `tools`**：不给 = 全量索引，
+     * 给 `[]` = 技能段整个缺席，给了就是交集 —— 它是同一份 frontmatter 里
+     * 挨着 `tools` 的两行，给邻居两套缺省是纯陷阱。
+     *
+     * ## ⚠️ 它收窄的是**索引**，不是技能本身 —— 这不是漏接，是判断
+     *
+     * 读正文那个工具**不受这一格约束**：父 agent 说「读一下 deploy 技能」时，
+     * 被收窄过的子 agent 照样读得到。两条判据：
+     *
+     * 1. **它当不了边界，想当也当不了。** 技能是盘上的 md 文件，任何拿得到
+     *    `file_read` 的角色都能直接读 `~/.epoch/skills/` 下任何一条 `SKILL.md` ——
+     *    而两个内置只读角色的 `READ_ONLY_TOOLS` 里**都有 `file_read`**。
+     *    这比上面 `tools` 那句「对含 `terminal` 的角色不构成安全边界」更彻底：
+     *    那边是「某些角色能绕」，这边是**每个**角色都能绕。所以它的定位只能是
+     *    **上下文预算**（同 `skills.maxIndexed` 封顶那一档），不是权限轴；
+     * 2. 顺着这个定位，读正文保持开着是对的：收窄从不推翻一句明确的指令。
+     *
+     * ## ⚠️ 📮 2026-08-27：**「技术上它也够不着」那句话是假的，删了。**
+     *
+     * 原话是：「`ToolContext` 上没有角色，而那个工具是装配期注册一次的进程级实例。
+     * 要它按角色分叉得先往 `ToolContext` 上加一格，那是另一次判断。」于是那笔账
+     * （`RECORD-skill-index-narrowing` §四第 4 条）被写成「要修得先答『角色进不进
+     * `ToolContext`』」。**核下来它够得着，而且很便宜**：
+     *
+     * - `AgentConfig.role` 是一个 `() => {name, prompt?, scope?}` 的**现读口**，
+     *   `AgentLoop` 每一轮都在调它（`run-start` 那枚徽标）；
+     * - `ToolExecutor` 是那个 loop **自己 `new` 的**（`loop.ts`），deps 里加一个
+     *   现读口、再填进 `ToolContext` —— 加上契约上那一格，**四处各一行**。
+     *
+     * 这不是估的：2026-08-27 反向验证时**真接了一遍**（`ToolContext` 一格 +
+     * `ToolExecutor` 的 deps 和填充各一行 + loop 那一行），四处，然后让
+     * `skill_view` 按它分叉 —— 下面那条门禁当场红。接完就还原了。
+     *
+     * 那句话在的时候，上面判据 2（「读正文保持开着是对的」）读起来像是在给一个
+     * 做不到的事找台阶。**它不是台阶，它是结论**：这不是「做不到」，是**不做**。
+     *
+     * ## 那个问题的答案：**角色不进 `ToolContext`**，三条判据
+     *
+     * 1. **它会成为「按角色收窄」的第二处实现，而第一处已经在了。** 今天角色收窄
+     *    只有一个机制：`roleScopedProvider` —— 一层 `ToolProvider` 上的过滤器，
+     *    管的是**哪些工具存在**。把角色挂上 `ToolContext` 是另开一条轴：**每个工具
+     *    自己决定拿角色干什么**。两条轴并存就能不一致，而不一致从外面看不出来
+     *    （同一个角色下，读 `ctx.role` 的工具和不读的工具行为不同）。
+     *    `agent-role/scope.ts` 文件头写着那套收窄之所以住在 core 而不是装配层，
+     *    是因为「装配层每写一遍就多一处可能写错的地方」—— 发给每个工具是同一件事
+     *    的放大版：不是装配层那几处，是**每一个工具作者**；
+     * 2. **今天没有一个够格的消费者，而唯一的候选已经被判成不该分叉**（就是上面
+     *    判据 2 本身）。为一个我们决定不写的消费者加一格字段，它唯一的作用是
+     *    引诱下一个人；
+     * 3. **`ToolContext` 上今天没有一样东西是「策略」。** `sessionId` / `workDir` /
+     *    `homeDir` / `permissionLevel` / `signal` 全是**环境事实** —— 任何工具都可能
+     *    正当地需要，而且没有一个是别的层已经做完的判断。角色不是事实，是一个
+     *    **已经在别处执行过的策略**（工具表早按它裁过了）。再发一份给工具，
+     *    等于把一个已经落地的决定重新变成一个开放问题。
+     *    ⚠️ 唯一的近似反例是 `ToolContext.sandboxTerminal`，而它自己的 JSDoc 就在
+     *    解释为什么例外：插件按分层够不着 core 的 loader，**引擎侧只有那一处同时
+     *    握着用户的配置和这一次调用**。角色没有那个理由 —— 需要它的那一层
+     *    （装配层）本来就握着它。
+     *
+     * 这个决定由 `core/__tests__/skill-in-prompt.test.ts` 里那条钉着：一个被收窄过
+     * 的角色**照样 `skill_view` 得到白名单外那条技能的正文**。
+     *
+     * ## 顺着这个答案，`available()` 那件事**不是劈叉**，定性改了
+     *
+     * 模型把名字打错时，读正文那个工具会把全量技能名（≤20 个）吐给一个被收窄过的
+     * 子 agent。2026-08-26 把它记成「劈叉」；顺着上面的答案它**不是** ——
+     * `skill_view` 本来就对全量开放，报出全量的名字和那个政策**是一致的**。
+     *
+     * 它是一笔**预算**上的小漏（打错名字那一次多花几十个 token），不是**边界**上的
+     * 漏。仍然不修，但理由换了：不是「有界所以先欠着」，是「和已定的政策一致，
+     * 只是不省钱」。
+     */
+    skills?: string[];
     /** 轮次预算。不给则沿用 `max(4, floor(父 maxTurns / 2))` */
     maxTurns?: number;
     source: AgentRoleSource;
@@ -817,7 +1053,7 @@ declare function isValidAgentRoleName(name: string): boolean;
  * > 逐段的核对结果就贴在每一段的开头，读的时候连着读。
  *
  * **接完之后这一档仍然不加**，判据在方案 57 §2.1：身份行 `session` 那句是
- * 「你是 epoch-agent CLI 智能体，**这一次**以「x」的身份工作」——「这一次」在逐条
+ * 「你是一个本地智能体，**这一次**以「x」的身份工作」——「这一次」在逐条
  * 语境下正好是对的，**逐条和会话级在模型读到的字节上没有区别**。加一档要么两句
  * 一模一样（那就是一个没有消费方的枚举值，同 {@link AgentRole} 上那条判据），
  * 要么另编一句措辞而没有任何理由。
@@ -893,9 +1129,29 @@ declare function isValidAgentRoleName(name: string): boolean;
  * > 把身份那一半留在外面**换不回缓存**，只换来一个作用域劈叉。
  * > 上限判据没变：chip 粘住不清空，连发五条不换专家就只作废一次。
  *
- * 身份行是 `systemPromptSegments()` 拼出来的 `head` 的**第一行**，也就是整段
- * prompt cache 的前缀。逐条换专家 ⇒ **每换一次作废整段缓存**。而那个函数的文件头
- * 逐字写着它存在的目的是「整轮对话中只构建一次，保证字节级不变」。
+ * > 📮 **2026-08-26 再订正一次：上面那条订正的前提没了，结论要分两半看。**
+ * > `## 可用工具` 那一段删掉了（判据在 `core/agent/message-utils.ts` 的
+ * > `SystemPromptSegments` 上：它和发给 provider 的 tools schema 数组完全重复）。
+ * > 于是：
+ * >
+ * > - **「工具那一半无论如何都要动 system prompt」不再成立。** 今天工具表只通过
+ * >   `PromptBuilder.projectBlock()` 里那四个策略块影响 prompt
+ * >   （`isOpenWorldTool` / `enter_plan_mode` / `lsp_diagnostics` /
+ * >   `ask_user_question`）。一条只收窄了别的工具的 `allowed-tools` 斜杠命令
+ * >   **现在真的一个字节都不动 system prompt** —— 那笔「大家早就在付」的账，
+ * >   多数情况下已经不用付了。
+ * > - **「进 system prompt」那个结论不变。** 它靠的是身份那一半本身：身份要真的
+ * >   换，就必须动 prompt。变的只是它不能再借工具那一半的车 —— 这笔缓存失效
+ * >   现在是逐条专家自己买单，而上限判据（chip 粘住不清空）还是那一条。
+ *
+ * 身份行是 `systemPromptSegments()` 的 `identity` 段，也就是整段 prompt cache 的
+ * 前缀。逐条换专家 ⇒ **每换一次作废整段缓存**。而那个函数的文件头逐字写着它存在
+ * 的目的是「整轮对话中只构建一次，保证字节级不变」。
+ *
+ * > ⚠️ 2026-08-21 订正一处：这里原来写的是「`head` 的**第一行**」，而当时
+ * > `PromptBuilder.buildSystem()` 把项目块拼在 `head` **前面** —— 也就是身份行
+ * > 那时并不是整段的前缀，「作废整段缓存」这句话反而是**偏保守**的（真正在前面的
+ * > 项目块不受影响）。那一轮把身份行拆成独立一段并提到最前，于是这句话从此为真。
  *
  * 这条代价本仓库已经**拒过一次**：`core/agent/loop.ts` 里那条后台任务通知，宁可作为
  * 末尾的一条 `user` 消息挂进去，也不并进 system prompt，逐字理由是「每轮往里塞一句
@@ -979,6 +1235,18 @@ interface ProviderInfo {
     /** 是否在交互式 provider 选择列表里出现（bedrock/azure 需要额外凭据，走配置文件） */
     interactive: boolean;
 }
+/**
+ * ⚠️ **`label` 只放品牌名，一个注解都不挂。**
+ *
+ * `ollama` 和 `openai-compatible` 这两条原来是 `'Ollama (本地)'` /
+ * `'OpenAI Compatible (通用适配)'` —— 括号里那半句是**注解，该翻**，而 protocol 是
+ * 零依赖层、够不着 `t()`，挂在这里就只能是单语言的：一个把界面切成 English 的人，
+ * 在模型菜单上会看到「Ollama (本地)」。2026-08-22（RECORD-40-i18n §34.3）把注解挪到了
+ * runtime 的 `providerLabel()`，那两条完整显示名在 catalog 的 `provider.label_*` 下。
+ *
+ * 判据同这个文件删掉 `PLAN_OUTCOME_LABELS` 那一次：**协议层出码和品牌名，文案在
+ * catalog**。品牌名不进 catalog 是因为它本来就不翻 —— 十三家里另外十一家一个字都不用动。
+ */
 declare const PROVIDER_INFOS: readonly ProviderInfo[];
 declare const PROVIDER_TYPES: readonly ProviderType[];
 declare function isProviderType(value: string): value is ProviderType;
@@ -1068,6 +1336,104 @@ interface EpochConfig {
         /** 关掉就是最初的行为：任何目录都直接加载项目指令 / hook / policy */
         enabled?: boolean;
     };
+    /**
+     * `terminal` 家族的 OS 沙箱开关（方案 46 §11.3 第一条，2026-08-21 落地）。
+     * **缺省 = 开着**，整段不配和显式写 `terminal: true` 行为逐字节相同。
+     *
+     * 它管的是 infra 那个 `confine()` 接缝 —— 也就是 `terminal` 的三条路径
+     * （管道 / 后台 / PTY）和 `shell_*` 那一族。**`code_exec` 不受它影响**：
+     * 那条路走的是另一个接缝（`isolate()`），边界也不一样（写入限于沙箱临时目录、
+     * 默认断网、读取白名单），它自己那半从第一天起就没有开关。
+     *
+     * ## 为什么需要一个能关掉的开关
+     *
+     * 2026-08-16 起**每一条终端命令**都套上了 OS 强制的写入边界，而
+     * `workspace-write` 那张可写目录表（工作区 + 临时目录 + 一张工具链缓存表，
+     * 逐条列在 infra 的 `TOOLCHAIN_CACHE_DIRS` 上）**是猜出来的**。真撞上一条
+     * 表里没有的缓存目录时，用户看到的是**一条本来能跑的命令突然被挡** ——
+     * 那时他需要的是一个能立刻关掉的开关，而不是等我们发一版把目录补进表里。
+     *
+     * ## ⚠️ `bypass` 档不是它的替代品
+     *
+     * `bypass` 映射到 `danger-full-access`，沙箱确实整个让开 —— 但它**同时把审批
+     * 也全放开了**，而那两件事本来正交（方案 46 §2.3「我们不做二维」）。
+     * 一个只想解开写入边界的人被迫连审批一起关掉，那不是应急路径，是一次降级。
+     * 这条判据不止写在这儿：`sandboxPolicyFor()` 关掉这个开关时**`mode` 照旧按
+     * 权限档位推**（`default` 仍然是 `workspace-write`，不会被改写成
+     * `danger-full-access`），所以两个轴始终分得开，`plugin-terminal` 那边有一条
+     * 用例钉着这一点。
+     *
+     * ## ⚠️ 只有开 / 关，不许长出第二个维度
+     *
+     * 不加 per-command、不加 per-directory、不加第二张模式表 —— 方案 46 §2.3
+     * 已经拍过「保持一维」，代价当时就说明了（想「自动批准但绝对不许写文件」的人
+     * 今天只能用 `plan` 档）。真要做二维，路径是命名预设 + 派生 `custom`，
+     * 那是另一次立项，不是往这一段上加键。
+     *
+     * ## 判它必须显式跟 `false` 比
+     *
+     * ```ts
+     * config.sandbox?.terminal !== false; // ✅ 没配 = 沙箱在
+     * config.sandbox?.terminal;           // ❌ undefined 是 falsy = 没配就裸跑
+     * ```
+     *
+     * 第二种写法的后果是**静默关掉一层 OS 强制边界**，而屏幕上什么都不会变
+     * （工具输出那行沙箱说明也会跟着说「关」，于是看起来还挺一致）。
+     * 这条线上每一跳的缺省都是「开」，所以漏填一跳的表现是**开关失灵**
+     * （配了 `false` 却照旧有沙箱），不是沙箱静默消失 —— 方向是刻意选的。
+     *
+     * ## 它只在用户级那一层（②）
+     *
+     * 不进 `<项目根>/.epoch/settings.json`（那份只认 `permissions` / `model` /
+     * `maxTurns`）。判据比 `artifacts` 那条更硬：一份 clone 下来、提交进仓库的
+     * 文件如果关得掉 OS 强制边界，那就是一条能靠 PR 送进来的提权路径 ——
+     * 方向和 [SETTINGS.md](../../../docs/SETTINGS.md) 第三节那句「可以替你收紧、
+     * 不能替你放开」是同一条。
+     */
+    sandbox?: {
+        /** 缺省 = `true`（沙箱照常包）。见上面那段「判它必须显式跟 `false` 比」 */
+        terminal?: boolean;
+    };
+    /**
+     * 按需发现工具（2026-08-26）。
+     *
+     * 判据全文在 `core/src/config/schema.ts` 的 `ToolsSchema` 上，这里只留结论：
+     * **默认关**，因为打开是一次**静默的能力缩减**（模型的初始工具列表里少了一批，
+     * 而屏幕上没有任何东西说明发生了什么）。值不值得开由 `/context` 的工具那一行
+     * 告诉你 —— 实测每个 MCP 工具边际 ≈ 200 tokens。
+     */
+    tools?: {
+        /** MCP 工具改成 `Deferred` 曝光：不进初始工具列表，模型用 `tool_search` 按需发现 */
+        deferMcp?: boolean;
+        /**
+         * code mode（方案 51）。**缺省 = `'tools'`**，也就是今天的行为，一个字不变。
+         *
+         * 判据全文在 `core/src/config/schema.ts` 的 `ToolsSchema.mode` 上，
+         * 这里只留结论：**默认关**，因为打开会把审批的粒度从「一次工具调用」放大到
+         * 「一个程序」，而那是一次用户必须知情的安全模型改动。
+         *
+         * `'code'`（2026-08-27，PR-2）比 `'both'` 多做一件事：**程序真能调的那些
+         * 工具从模型的工具表里切走**，改以一段生成的 SDK 声明进 system prompt。
+         * 判据全文在 `core/src/code-mode/exposure.ts` 上，这里只留那一句：
+         * **一个工具从工具表里消失，当且仅当程序真的能替模型调它** —— 于是这一档
+         * 不会让任何工具变得没有路可走。
+         */
+        mode?: 'tools' | 'both' | 'code';
+    };
+    /**
+     * 技能索引的封顶（2026-08-26）。
+     *
+     * 判据全文在 `core/src/config/schema.ts` 的 `SkillsSchema` 上，这里只留结论：
+     * **默认不封**，而且比 `tools.deferMcp` 更该守这条 —— 被 defer 的工具模型自己
+     * `tool_search` 找得回来，被索引截掉的技能模型**永远不知道它存在**，全仓没有
+     * 第二条发现路径。封顶是「丢哪些、要不要告诉人」两半，这里只管条数这一半，
+     * 另一半（丢的次序、索引末尾那句提示、`/context` 上的 hint）是 `SkillSystem`
+     * 的事。
+     */
+    skills?: {
+        /** 索引里最多列几条。缺省 = 不封（全部进索引，改造前的行为） */
+        maxIndexed?: number;
+    };
     /** 成本与预算闸门。全部缺省 = 不限制 */
     budget?: {
         /** 单次会话的美元上限，超了发 finish: 'budget-exceeded' */
@@ -1257,6 +1623,32 @@ interface EpochConfig {
      * 因为侧栏那一行还要装搜索框。
      */
     brand?: string;
+    /**
+     * `~/.epoch/artifacts/` 的保留策略（方案 47 PR-4）。**缺省 = 内置默认**
+     * （7 天 / 512MB）—— 整段不配和显式写这两个默认值，行为逐字节相同。
+     *
+     * 清理本来就一直在跑（core 的 `pruneArtifacts`，每进程一次、清在第一次真要
+     * 落盘那一刻），这一段加的是**旋钮不是开关** —— 同 `compression` 那一类，
+     * 不同于 `search` 那种「不配就压根没有这个能力」的段。
+     *
+     * ## 为什么只有 artifact 这一半可配
+     *
+     * `~/.epoch/` 上有两条容量上限：检查点 200MB、artifact 512MB（两个数字现在
+     * 写在 core 的 `disk-ledger.ts` 同一张表里，不再互不知道）。只有这一条开了
+     * 配置项，判据是**谁会真的想改它**：artifact 装的是命令输出全文，一个天天跑
+     * 大输出的用户几天就能把它撑到上限；而检查点那边先被「每会话 20 条」那道闸
+     * 兜住，200MB 至今没人撞到过。**没有消费方的配置项就是死键**，所以那一半
+     * 留在构造参数上（`CheckpointStoreOptions`），等真有人撞到再提上来。
+     */
+    artifacts?: {
+        /** 超过这个天数的**会话目录**整个删掉，缺省 7。当前会话目录永远不删 */
+        maxAgeDays?: number;
+        /**
+         * `artifacts/` 根目录的总容量上限（字节），缺省 512MB。超了从最旧的会话
+         * 目录开始删 —— **不逐文件删**，半个会话的截图比没有更难理解。
+         */
+        maxTotalBytes?: number;
+    };
 }
 /** 支持的搜索后端。`searxng` 是**自托管无 key**那一档，内网 / 隐私敏感场景的答案 */
 declare const SEARCH_PROVIDER_TYPES: readonly ["tavily", "brave", "searxng"];
@@ -1564,10 +1956,11 @@ declare const COMMAND_NAME_PATTERN: RegExp;
 declare function isValidCommandName(name: string): boolean;
 
 /**
- * 键位契约（方案 31 PR-1）—— 「这个按键是哪个动作」的**值域**。
+ * 键位契约（方案 31 PR-1 / PR-2）—— 「这个按键是哪个动作」的**值域**。
  *
- * 这里只有三样跨包共用的东西：动作的全集（{@link KEY_ACTIONS}）、一个按键组合
- * 的形状（{@link KeyChord}）、以及把 `"ctrl+l"` 这种写法和它互转的纯函数。
+ * 这里只有三样跨包共用的东西：动作的全集（{@link KEY_ACTIONS}）、一条绑定的形状
+ * （{@link KeyChord} 与 {@link KeySequence}）、以及把 `"ctrl+l"` / `"escape escape"`
+ * 这种写法和它互转的纯函数。
  * 默认表住在 [tui/src/keybindings/defaults.ts](../../tui/src/keybindings/defaults.ts)，
  * 读盘 / 校验 / 冲突检测住在
  * [core/src/config/keybindings.ts](../../core/src/config/keybindings.ts)。
@@ -1596,8 +1989,21 @@ declare function isValidCommandName(name: string): boolean;
  * （见 `resolver.ts` 的索引构建）。今天默认表里一个冲突都没有，这只是兜底。
  *
  * PR-1 只收**今天已经硬编码在 app.tsx / input-box.tsx 里的那些键**，
- * 外加一个 `rewind`（见 defaults.ts）。vim 的 `vim-normal` / `vim-insert` 等归
- * PR-3 —— 提前登记会让 `/keybindings` 列出一堆按不出效果的动作。
+ * 外加一个 `rewind`（见 defaults.ts）。
+ *
+ * ⚠️ **PR-3 一个 vim 动作都没加**，而 PR-1 这里原先写的是「`vim-normal` /
+ * `vim-insert` 等归 PR-3」。落地时那个设计走不通，两条理由：
+ *
+ * 1. **进 NORMAL 那一下不该是一个新动作。** 它就是 `interrupt`（Esc）——
+ *    在 INSERT 里回 NORMAL、在 NORMAL 里照旧中断本轮（§4.3 #19）。真给它开一个
+ *    `vim-normal` 并默认绑 Esc，冲突检测会**当场拒掉**它：`interrupt` 是 `global`、
+ *    它是 `input`，而这两个上下文是同时活着的（{@link SIMULTANEOUS_CONTEXTS}）。
+ * 2. **NORMAL 里那几十个键压根不走这张表。** `d` / `w` / `x` / `.` 是一台状态机
+ *    的输入（`tui/src/vim/machine.ts`），不是二十几个各自可绑的动作 ——
+ *    把它们登记进来等于让用户能把 `dw` 拆散。
+ *
+ * PR-2 一个动作都没加：序列（`escape escape`）改的是**一条绑定长什么样**，
+ * 不是有哪些动作。`rewind` 早在 PR-1 就登记了，只是那时没有键。
  */
 declare const KEY_ACTIONS: readonly ["interrupt", "rewind", "clear-screen", "open-artifact", "transcript-search", "exit", "exit-if-empty", "submit", "newline", "history-prev", "history-next", "cursor-left", "cursor-right", "line-start", "line-end", "kill-word", "kill-line-start", "kill-line-end", "delete-char-left", "delete-char-right", "paste-image", "complete", "complete-prev", "complete-next"];
 /** 一个动作 */
@@ -1656,12 +2062,49 @@ interface KeyChord {
     shift?: boolean;
 }
 /**
- * 一张生效的绑定表：动作 → 若干个键（一个动作可以绑多个键）。
+ * 一条绑定 —— **按顺序按下的一个或多个 chord**（方案 31 PR-2 §4.2）。
+ *
+ * 长度 1 是绝大多数（`ctrl+l`），长度 ≥ 2 是序列（`escape escape`）。
+ *
+ * ## 为什么是「非空元组」而不是 `KeyChord[]`
+ *
+ * 空序列没有意义，而它能从两处混进来：用户写了 `[""]`，或者代码里 `.slice()` 出
+ * 一段。类型上堵住之后，`seq[0]` 在 `noUncheckedIndexedAccess` 下也不用再兜一次
+ * undefined —— 那种兜底代码里必然有一支永远走不到，也就永远测不到。
+ *
+ * ## 为什么不是「单键表 + 序列表」两张
+ *
+ * 想过。两张表就要在**每一处**构造点同时填对两张（默认表、用户合并、冲突检测），
+ * 而它们迟早会漂 —— 同 `RESERVED_COMMAND_NAMES` 那条判据（一份真源，别养双向
+ * 用例去锁两份相等）。代价是 {@link resolveAction} 那侧要显式跳过长度 ≥ 2 的，
+ * 那一句写在它的索引构建里。
+ */
+type KeySequence = readonly [KeyChord, ...KeyChord[]];
+/**
+ * 一张生效的绑定表：动作 → 若干条绑定（一个动作可以绑多个键 / 多条序列）。
  *
  * **交给 tui 的一定是已经校验过的**：动作名合法、chord 解析过、保留键剔掉了、
  * 冲突消解过。tui 这一侧不做校验，也就没有「一半有效的表」这种状态。
  */
-type KeybindingTable = Readonly<Record<KeyAction, readonly KeyChord[]>>;
+type KeybindingTable = Readonly<Record<KeyAction, readonly KeySequence[]>>;
+/**
+ * 序列**目前只在这些上下文里生效**（方案 31 PR-2 起，PR-3 补上 `input`）。
+ *
+ * 不是设计上的限制，是**落地范围**：序列的状态机是一台一台接上去的 ——
+ * PR-2 接了 `app.tsx`（`global`），PR-3 接了 `input-box.tsx`（`input`）。
+ * `dialog` 还没接：补全面板开着的那几个键（↑↓ / Tab / Enter）今天走的是单键那一层
+ * （`input-box.tsx` 里那次 `actionOf(input, key, 'dialog')`），而面板开着的时候
+ * 用户正在选东西，把它做成「按一下等半秒看有没有第二下」的形状收益是负的。
+ *
+ * ⚠️ **两个上下文各是一台状态机，不是一台服务两边。** 一次按键会被两个 `useInput`
+ * 各收一次（见 {@link SIMULTANEOUS_CONTEXTS}），共用一台等于把窗口推进两步 ——
+ * 判据全文在 `tui/src/keybindings/use-key-sequences.ts` 的文件头。
+ *
+ * 加载期据此**拒绝**绑在还没接的那些动作上的序列并出一条诊断，而不是收下来让它不
+ * 生效：「配了但没反应」是最难自查的一类问题，而这一条自查起来尤其难 ——
+ * 同一份文件里 `rewind` 那条序列明明是好的。
+ */
+declare const SEQUENCE_CONTEXTS: readonly KeyContext[];
 /**
  * 保留键：**不许被重绑**。试图绑上去的那一条拒绝加载 + 一条 warn 诊断
  * （不是整份配置作废 —— 那是「文件坏了」，另一回事）。
@@ -1687,13 +2130,96 @@ declare function chordId(chord: KeyChord): string;
  * 不认识的修饰键、空的键名、多于一个 code point 的键名一律判不合法 ——
  * 静默忽略半个 chord 会让「配了没生效」变成一个没人查得出的问题。
  *
- * ⚠️ **序列（`"escape escape"`）不在这里** —— 那是 PR-2 的事，它会在**外面**
- * 按空格切开再逐段调本函数。所以这里遇到空白直接判不合法，而不是取第一段：
- * 取第一段的话，PR-1 装了一份带序列的配置会静默降级成单键，用户以为序列生效了。
+ * ⚠️ **序列（`"escape escape"`）不在这里**，在 {@link parseSequence} —— 它按空格
+ * 切开再逐段调本函数。所以这里遇到空白仍然直接判不合法，而不是取第一段：
+ * 取第一段的话，一份带序列的配置会静默降级成单键，用户以为序列生效了。
  */
 declare function parseChord(text: string): KeyChord | undefined;
+/**
+ * 序列的规范字符串：`"escape escape"`。**比较和展示都走它**，同 {@link chordId}。
+ *
+ * 分隔符是一个空格，而 {@link parseSequence} 收任意空白 —— 用户写两个空格、写
+ * tab，归一之后仍然是同一条绑定。
+ */
+declare function sequenceId(sequence: KeySequence): string;
+/**
+ * `"escape escape"` → 序列；`"ctrl+l"` → 长度 1 的序列。认不出来返回 undefined。
+ *
+ * **整条要么全对要么全废**：`"escape ctrl+shit+l"` 判不合法，而不是留下前半段。
+ * 半条序列在运行期的表现是「按了第一下有反应、第二下没有」，而用户会以为是
+ * 时间窗口的问题，跑去调那个 500ms。
+ */
+declare function parseSequence(text: string): KeySequence | undefined;
 /** 是不是一个我们认识的动作名。用户输入（配置文件的键名）收窄用 */
 declare function isKeyAction(value: string): value is KeyAction;
+/**
+ * 一条绑定是哪一层来的。
+ *
+ * 这是 PR-2 真正的工作量所在：PR-1 的 `loadKeybindings` 只回「最后生效的表」+
+ * 诊断，**表里看不出哪条是用户改的** —— 而用户查键位问题时的第一个问题永远是
+ * 「这条是谁定的、我该去改哪个文件」（同 `/permissions` 那个 `layer`）。
+ */
+type KeybindingSource = 'default' | 'user';
+/** 一条生效的绑定 + 它的来源 */
+interface BoundKey {
+    keys: KeySequence;
+    source: KeybindingSource;
+}
+/**
+ * 一条**没**生效的绑定，以及为什么。
+ *
+ * `keys` 是**用户写的原文**而不是 {@link sequenceId}：`invalid` 那一档压根解析不
+ * 出来，而用户要拿这一串回去在文件里找到它。
+ */
+interface RejectedKey {
+    /** 动作名。`unknown-action` 那一档它就是那个拼错的名字，所以类型是 string */
+    action: string;
+    /** 用户写的那一串，逐字 */
+    keys: string;
+    reason: RejectReason;
+    /** `conflict` 那一档：这个键被谁占住了 */
+    winner?: KeyAction;
+}
+/**
+ * 一条绑定被丢掉的原因。五档各对应一条加载期判定：
+ *
+ * | 档              | 判据                                                       |
+ * | --------------- | ---------------------------------------------------------- |
+ * | `reserved`      | 撞上 {@link RESERVED_CHORDS}（逃生通道不许被锁死）         |
+ * | `conflict`      | 同时活着的上下文里这个键已经有主人了                       |
+ * | `invalid`       | {@link parseSequence} 认不出来                             |
+ * | `unknown-action`| 动作名不在 {@link KEY_ACTIONS} 里                          |
+ * | `unsupported`   | 序列绑在了输入框动作上，见 {@link SEQUENCE_CONTEXTS}       |
+ */
+type RejectReason = 'reserved' | 'conflict' | 'invalid' | 'unknown-action' | 'unsupported';
+/**
+ * 一次加载的完整账本 —— `/keybindings` 印的就是它。
+ *
+ * 和 {@link KeybindingTable} 的分工：表是**给键盘用的**（每次按键查一次，所以它
+ * 只有「哪个键 → 哪个动作」），账本是**给人看的**（多了来源和被丢掉的那些）。
+ * 表由 {@link tableOf} 从账本投影出来，**不是两处各构造一遍** —— 后者迟早会出现
+ * 「/keybindings 说 ctrl+k 是清屏，按下去却不清」。
+ */
+interface KeybindingReport {
+    /** 用户那份配置文件的路径。「我该去改哪个文件」的答案 */
+    path: string;
+    /** 那个文件在不在。不在是**正常情况**（绝大多数人不改键） */
+    present: boolean;
+    bindings: Readonly<Record<KeyAction, readonly BoundKey[]>>;
+    rejected: readonly RejectedKey[];
+}
+/**
+ * 逐动作造一张全量表。**「每个动作都有一格」这件事由这个函数保证**，调用方不用再
+ * 各自 `Object.fromEntries(...) as` 一次。
+ *
+ * 里面那次断言是 `Partial<Record<…>>` → `Record<…>`，也就是「循环跑完之后每一格都
+ * 填上了」—— 这一句在这里成立（循环由 {@link KEY_ACTIONS} 驱动），而它是全仓唯一
+ * 需要成立的一处。`fromEntries` 那种写法给出的是索引签名，断成 `Record` 会被
+ * TS 判成两个类型压根不重叠，只能再套一层 `as unknown`，而那就真的什么都不检查了。
+ */
+declare function perAction<T>(make: (action: KeyAction) => T): Readonly<Record<KeyAction, T>>;
+/** 账本 → 键盘要查的那张表。投影，不是第二份真源 */
+declare function tableOf(bindings: KeybindingReport['bindings']): KeybindingTable;
 
 /**
  * 可观测性契约（方案 14）。
@@ -2201,11 +2727,61 @@ type AgentEvent =
     model?: string;
     breach?: BudgetBreach;
 }
+/**
+ * 引擎有一句话要对用户说，而**它不是回复正文**（2026-08-26）。
+ *
+ * ## 发它的是谁，以及为什么非要一条新帧
+ *
+ * 今天唯一的发射方是 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: 'notice';
+    code: NoticeCode;
+    text: string;
+}
 /** 运行中出错（随后会有一个 finish: 'error'） */
  | {
     type: 'error';
     message: string;
 };
+/**
+ * 一条 `notice` 是哪一类。
+ *
+ * 今天只有一种，但写成联合是为了让**将来加第二种时消费方的 switch 会红** ——
+ * 判据同 wire.ts 的 `WireResetReason`。
+ */
+type NoticeCode = 
+/**
+ * 技能学习器在上一轮收尾之后学到了一条技能。
+ *
+ * ⚠️ 这一帧发在**下一轮的头上**，不是学成的那一刻 —— 学成时那条流早关了
+ * （`maybeLearn()` 紧接着就是 `yield finish('stop'); return;`）。发在这里还有
+ * 第二层意思：那一轮正是这条技能**真的进了 system prompt** 的那一轮。
+ */
+'skill-learned';
 type AgentEventType = AgentEvent['type'];
 /** 取出某个具体事件的类型，例如 AgentEventOf<'tool-call'> */
 type AgentEventOf<T extends AgentEventType> = Extract<AgentEvent, {
@@ -2529,11 +3105,23 @@ interface ScheduleDefinition {
      */
     workDir: string;
     model?: string;
-    /** 「召唤专家」。等方案 42 PR-1 把顶层会话的角色接线，今天永远不带 */
+    /**
+     * 「召唤专家」。**今天永远不带 —— 但已经不是被别人挡着了。**
+     *
+     * 立案时写的是「等方案 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;
-    /** 等方案 44 的清单契约，今天永远不带 */
+    /** 同 {@link role}：方案 44 的清单契约早就到齐了，缺的是写入点。今天永远不带 */
     skills?: readonly string[];
-    /** 等方案 44。连接器的免确认落在 `allowRules` 的 `mcp__<server>__*` 上 */
+    /**
+     * 同 {@link role}，缺的是写入点。
+     * 连接器的免确认另有一条现成的路：`allowRules` 里的 `mcp__<server>__*`。
+     */
     mcpServers?: readonly string[];
     /**
      * 权限档 —— **和对话里那枚胶囊同一套取值、同一套词**。
@@ -2632,6 +3220,213 @@ interface ScheduleRunnerSpec {
     label?: string;
 }
 
+/**
+ * 内置模板六张（[方案 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` 的先例）。**两条都不用，因为这一份和那个
+ * 先例不是同一种东西**：
+ *
+ * - `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, …>`，**加一张模板而不给它文案会当场编译不过**。
+ */
+
+/**
+ * 六张模板的 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;
+    /**
+     * 权限档。**取值里没有 `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) §八 ① / ③ 的素材。
+ *
+ * 三个界面读的是同一个数：dock 上那一条「自动化待确认」、侧栏「自动化」入口上
+ * 那个点、TUI 启动时那一行。**它们必须是同一个数** —— 三处各数一遍的下场是
+ * 侧栏有点、点进去 dock 上什么都没有。
+ *
+ * ## 一、为什么这份投影住在 protocol
+ *
+ * 它是**纯集合运算**：手上有哪几条任务、每条最近跑过什么、清单里已经有哪几条规则。
+ * 没有日期算术、不读盘、不查权限，一个字的 core 知识都不需要。
+ * 而它的消费者有四个：`server`（那条端点）、`cli`（`--fix` 和 TUI 那行开机提示）、
+ * `packages/web/dev` 那台假服务端、以及将来任何一个嵌入宿主。
+ * [AGENTS.md](../../../AGENTS.md) 分层表里 protocol 那一行写着
+ * 「跨包共享的东西**只能**放这里」，这就是那一行说的情况。
+ *
+ * ⚠️ **这一份落地之前，那个集合运算在仓库里有三份**（`server` 的 `fixSchedule`、
+ * `cli` 的 `applyFix`、假服务端的 `fakeScheduleFix`），逐字一样的六行。
+ * 三份都是「往授权清单里加规则」这条路上的判定 —— 也就是**提权路径上的重复实现**。
+ * 收成一份是这个文件存在的第二个理由，比第一个理由更硬。
+ *
+ * ## 二、「还欠着」= 算得出规则、而且规则还不在清单里
+ *
+ * 两道筛，**缺一道这个数就会自己卡住**：
+ *
+ * 1. **`suggestedRule` 必须有值。** 算不出精确规则的那几条（目标为空的操作）
+ *    进不了这份清单 —— dock 上唯一的动作是「加进授权清单」，而对它们那一下
+ *    什么都加不了。一条点了没用的通知比没有通知坏（设计稿决定 20 ①），
+ *    而且它**永远清不掉**：没有任何动作能让它消失。
+ *    ⚠️ 它们并没有被藏起来：「运行记录」那一屏上那一轮照旧列着它们、
+ *    照旧写着「这一条反推不出精确规则」。这里筛掉的是**通知**，不是事实。
+ * 2. **规则还不在 `allowRules` 里。** 用户按过那一下之后规则就进清单了，
+ *    于是这个数**自己减一**。这条让整件事不需要「读标记」那套东西 ——
+ *    没有迁移、没有「哪个界面算看过」这个产品判断、也没有一个只能靠
+ *    「我看过了」来清的角标。
+ *
+ * ## ⚠️ 三、这个数**不含**「上一次没跑成」的那几条，而那是一条判断不是遗漏
+ *
+ * `failed` / `timeout` / `budget` 三档同样是「你该知道的事」，但它们**没有下一步
+ * 动作**：屏幕上给不出一个按钮，用户只能去看运行记录。把它们算进来的话，这个点
+ * 会一直亮着，直到那条任务下一次跑成 —— 而在那之前它已经不再指向任何可做的事，
+ * 也就退化成了一个「有东西发生过」的常亮灯。
+ *
+ * 三档失败在「运行记录」那一屏上有自己的三态色（✅ ⚠️ ❌），一条都没藏。
+ * 📮 真要给它们一个计数，前置是一份**读标记**（`schedule` 那个 namespace 加一次
+ * 迁移 + 一条写端点 + 「web 打开那个 tab 算不算看过、TUI 启动算不算」这个产品
+ * 判断）。那是独立的一次改动，不该顺手塞进这一轮。
+ */
+
+/**
+ * 一条**算得出规则**的欠条。
+ *
+ * `suggestedRule` 从可选收成必填 —— 这不是换个写法：它让「dock 上那个按钮
+ * 一定加得进东西」变成一件类型上成立的事，而不是一句要人记住的注释。
+ */
+type FixableApproval = SchedulePendingApproval & {
+    suggestedRule: string;
+};
+/**
+ * dock / 侧栏 / TUI 三处共用的一条。
+ *
+ * 带 `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[];
+}
+/**
+ * 这一轮的欠条里，有哪几条规则还不在清单里。**去重，顺序照欠条的顺序。**
+ *
+ * 三个调用点：这个文件自己（算那个计数）、`POST /api/schedules/:id/fix`
+ * （真往清单里写的那一下）、`epoch schedule run --fix`。
+ * ⚠️ **三处必须是同一个函数**：它决定的是「往授权清单里加哪几条规则」，
+ * 而三份实现走散的方向可能是提权（一边加了另一边没加）。
+ */
+declare function unfixedRules(allowRules: readonly string[], approvals: readonly SchedulePendingApproval[]): string[];
+/**
+ * 手上那几条任务 + 最近那些运行 → 该通知的清单。
+ *
+ * ## ⚠️ 同一条任务只报**最近**那一次，不是每一次
+ *
+ * 一条「每天 9 点」的任务每天记同一条欠条，一周就是七条一模一样的通知。
+ * 所以按任务收拢、取最近那一次。这不会漏掉东西：修最近那一次加进去的规则
+ * 通常把老的那几次也一起覆盖了；万一老的那次欠的是**另一条**规则，
+ * 它在下一次取数时自然浮上来成为「最近的那条未解决的」。
+ *
+ * ⚠️ 判的是「最近的**还欠着的**那一次」，不是「最近的那一次」：一条任务昨天
+ * 卡了、今天跑成了，昨天那条欠条**仍然欠着**（清单里那条规则还是没加），
+ * 下一次到点还会再卡一遍。拿「最近一次的状态」当判据会把它静默吞掉。
+ *
+ * @param defs 全部任务（`ScheduleControl.list()`）
+ * @param runs 最近那些运行，**最新的在前**（`ScheduleControl.recentRuns()` 的顺序）
+ */
+declare function collectPendingApprovals(defs: readonly ScheduleDefinition[], runs: readonly ScheduleRun[]): SchedulePendingItem[];
+
 /**
  * 工作区信任契约。
  *
@@ -2795,45 +3590,246 @@ interface EpochFilePart {
     /** 文件原始字节数，用于展示 */
     bytes?: number;
 }
-type EpochContentPart = EpochTextPart | EpochImagePart | EpochFilePart;
-/** 用户消息内容 —— 纯文本或多模态部件数组 */
-type EpochUserContent = string | EpochContentPart[];
-/** 附件在纯文本投影里长什么样。**不吐文件内容** —— 内容走 `parts` 那一路 */
-declare function filePartSummary(part: EpochFilePart): string;
 /**
- * 取部件数组的纯文本投影：图片折成一句占位，绝不吐 base64；
- * 文件同样只折成一行占位，**不吐内容**。
+ * 引用的会话为什么只有标题没有内容（方案 53 §4.2）。
  *
- * 投影是**存盘、压缩、审计**看的那一份。把几十 KB 的文件内容塞进来，
- * `sessions.db` 会跟着一起胖，而回放时那份内容本来就能从 `parts` 里拿。
+ * 前五个是**稳定的错误码**，给宿主路由用（headless / 嵌入宿主要能按码分流，
+ * TUI 和 Web 要各自渲染）。清单本体是 {@link SESSION_REFERENCE_ERROR_CODES}，
+ * 那才是同构位置的唯一真源。
  */
-declare function contentToText(content: EpochUserContent): string;
-type EpochMessageRole = 'system' | 'user' | 'assistant' | 'tool';
+type SessionOmitReason = 
+/** `@:xxx` 匹配不到**唯一**的一段会话（零个，或好几个） */
+'invalid-reference'
+/** 引用的是当前这段会话自己 */
+ | 'self-reference'
+/** 超过每条消息能引用的会话个数 */
+ | 'too-many'
+/** 会话可读性判定不放行（方案 48 的那一处判定，见 core/session/authorization.ts） */
+ | 'not-authorized'
+/** 这一条消息的附件总量已经用完 */
+ | 'budget-exceeded'
 /**
- * 一条会话消息。
+ * 会话是 resume 出来的，引用的内容**不重读**。
  *
- * `content` 永远是字符串（tool 消息为空串，内容在 `toolResults` 里），
- * 这样「取这条消息的文本」永远不需要判类型。
+ * 判据逐字同 {@link FileOmitReason} 的 `not-restored`：内容当初是过了可读性
+ * 判定才附上的，而那次判定发生在另一个上下文里。恢复时无声地再读一遍等于让
+ * 一次旧的授权在新的上下文里继续生效。模型仍然看得见「用户引用过这段会话」，
+ * 要内容就自己调 `session_search`（方案 48 那条路，有工具审批）。
  *
- * 多模态**不是**把 `content` 放宽成联合类型 —— 那正是本文件开头骂过的病，
- * 会让 loop / codec / 压缩器每处都得判一次类型。改成加一个 `parts` 旁路：
- * `content` 仍然是权威的**文本投影**（压缩器、审计、持久化都只看它），
- * `parts` 只在 sdk-adapter 那一处被读走。两者的关系由 `contentToText` 保证。
+ * **它不是错误码**，所以不在 {@link SESSION_REFERENCE_ERROR_CODES} 里。
  */
-interface EpochMessage {
-    role: EpochMessageRole;
-    content: string;
-    /**
-     * 多模态部件。给了就以它为准喂模型，`content` 退化成它的文本投影。
-     * **不落 SQLite** —— 图片走 artifact 目录，DB 里只留 content 的占位文本。
-     */
-    parts?: EpochContentPart[];
-    /** assistant 要求的工具调用；与 content 并存（模型可以边说话边调工具） */
-    toolCalls?: EpochToolCall[];
-    /** role 为 'tool' 时携带的执行结果 */
-    toolResults?: EpochToolResult[];
-    /**
-     * 这一步模型的思考原文（推理模型的 `reasoning-delta` 累加）。2026-08-18。
+ | 'not-restored';
+/**
+ * 五个稳定的错误码（方案 53 §4.2）—— **同构位置的唯一真源**。
+ *
+ * 为什么要稳定的码而不是一句话：headless / 嵌入宿主要能路由这些失败
+ * （`docs/HEADLESS.md` 的退出码那套已经是这个思路），而且 TUI 和 Web 要各自渲染。
+ *
+ * `not-restored` 刻意不在里面 —— 它是「会话恢复了」这个事实，不是一次失败。
+ */
+declare const SESSION_REFERENCE_ERROR_CODES: readonly SessionOmitReason[];
+/**
+ * 引用另一段会话的部件 —— 用户用 `@:xxx` 提到的那段会话（方案 53）。
+ *
+ * ## 塞进来的是那段会话的「当前面」，不是原始全量（§二）
+ *
+ * 一个跑了两小时、压缩过三次的会话，`messages` 表里有 800 条，但模型当时能看到
+ * 的只有 60 条（其余 `active = 0`）。这里带的是**那 60 条**。三条理由：800 条
+ * 任何预算都塞不下；那 60 条就是这段会话的结论（压缩器已经把前面浓缩进去了）；
+ * 原始全量里有已经被推翻的内容（「先试了 A 不行改用 B」，压缩之后留下的是 B）。
+ *
+ * ## 它是**快照**，不是活引用
+ *
+ * 引用是发消息那一刻的快照，之后源会话被归档、删除、继续聊都不影响这一条。
+ * **别去做「引用失效」的检测** —— 那等于让一条已经发出去的消息随时间变形。
+ *
+ * ## `text` 缺席是常态
+ *
+ * 匹配不到、引用自己、超上限、判定不放行时**只留 `ref` 和原因**。这时候模型
+ * 看到的是「用户引用了某段会话，但内容没给你，原因是 X」—— 要内容它可以自己调
+ * `session_search`（方案 48）。这保证了 `@:` 永远不会成为一条比 `session_search`
+ * **更宽松**的读取通道，和 `@文件` 对 `file_read` 那条判据逐字对应。
+ */
+interface EpochSessionPart {
+    type: 'session';
+    /** 用户敲的那个引用串（`@:` 后面那一截），原样保留用于显示 */
+    ref: string;
+    /** 匹配到的会话 id。**没匹配上时缺席** */
+    sessionId?: string;
+    /** 那段会话的标题（空标题时是 sessionId，见方案 53 §5.3） */
+    title?: string;
+    /** 那段会话的工作目录，用于让人 / 模型看出「这是哪个项目的会话」 */
+    cwd?: string;
+    /** 当前面的正文。**缺席时看 `omitted`** */
+    text?: string;
+    /** 没给内容的原因；给了 `text` 时不出现 */
+    omitted?: SessionOmitReason;
+    /** 内容被截断到多少字节。给了就是截断过 —— 截断**永远不静默** */
+    truncatedTo?: number;
+    /** 当前面有多少条消息（`active = 1` 的那些） */
+    messageCount?: number;
+    /** 那段会话一共多少条（含被压掉的）。两个数不等就说明它压缩过 */
+    totalMessages?: number;
+}
+type EpochContentPart = EpochTextPart | EpochImagePart | EpochFilePart | EpochSessionPart;
+/** 用户消息内容 —— 纯文本或多模态部件数组 */
+type EpochUserContent = string | EpochContentPart[];
+/**
+ * 附件在**给模型的**纯文本投影里长什么样。**不吐文件内容** —— 内容走 `parts` 那一路。
+ *
+ * 输出**逐字冻住**：门禁在 `packages/protocol/__tests__/message-projection.test.ts`，
+ * 它把五种 `omitted` 原因加截断、不截断两支全钉死了。改一个字那份会当场红 ——
+ * 那不是「用例过时了」，是你正在改模型的输入契约（判据见 {@link OMIT_LABEL}）。
+ */
+declare function filePartSummary(part: EpochFilePart): 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` 那条豁免记的是同一个坑）。
+ *
+ * 显示名用标题而不是 sessionId：后者是一串随机字符，对人和模型都没有信息量。
+ * 标题为空的会话在解析那一侧已经用 sessionId 兜过底了（方案 53 §5.3）。
+ */
+declare function sessionPartSummary(part: EpochSessionPart): string;
+/**
+ * 取部件数组的纯文本投影：图片折成一句占位，绝不吐 base64；
+ * 文件和引用的会话同样只折成一行占位，**不吐内容**。
+ *
+ * 投影是**存盘、压缩、审计**看的那一份。把几十 KB 的文件内容塞进来，
+ * `sessions.db` 会跟着一起胖，而回放时那份内容本来就能从 `parts` 里拿。
+ *
+ * ## ⚠️ 这一份**只给模型和落库**，界面不许用它（RECORD-40-i18n §34.4）
+ *
+ * 改造前它一个人喂三类消费者，于是把界面切成 English 的人会在**自己那条消息的
+ * 气泡里**看到 `[图片 image/png]` / `[文件 …：二进制文件，未附内容]`。
+ * 这笔债在 §34.4 记了、§34.4 还掉，处置是**分家**：
+ *
+ * | 谁要 | 用哪一份 | 为什么 |
+ * | ---- | -------- | ------ |
+ * | 模型（`sdk-adapter.ts` / `agent/loop.ts` / `runtime/agent-session.ts`） | **这一个** | 模型输入契约 + eval 指纹，跟着 locale 变就漂（§33.2） |
+ * | `messages.content` 那一列（存盘 / 压缩 / 审计 / FTS） | **这一个** | 一条落库的记录跟着 `EPOCH_LANGUAGE` 变语言，等于把同一段会话的历史劈成两半 |
+ * | 界面（tui 的历史项、web 的气泡） | `contentToDisplayText(content, t)` | 那一份走 catalog 的 `message_part.*`，住在两个宿主里 |
+ *
+ * 界面那一份**落在宿主层**而不是这儿，判据同 §34.6 给 `view` 那 1 处的做法
+ * （兜底文案挪给渲染端）：这个包的依赖白名单是空的，`t()` 只能由有它的那一层调。
+ */
+declare function contentToText(content: EpochUserContent): string;
+/**
+ * 「上一轮实际动过手」在**给模型的**历史里长什么样（2026-08-28）。
+ *
+ * ## 它修的是什么
+ *
+ * 喂模型的那份历史只有 user / assistant 两种角色的**文本**
+ * （`runtime/src/agent-session.ts` 的累积、`session-store.ts` 的 `loadHistory()`），
+ * 工具调用和结果一条都不在里面 —— 这是刻意的（孤立的 tool 消息会被 provider 拒掉，
+ * 全量 transcript 是另一个体量的事）。代价此前没人算：一段五条消息的会话，
+ * 模型看到的是**五条又长又具体的指令，配四句十来个字的「办完了」**。
+ * 早期那几条指令的字数远大于「它已经做完了」的证据量，于是模型把它们当成还在
+ * 生效的待办，回头去做 —— 而用户刚发的那一条被摊薄。实测在
+ * `packages/runtime/__tests__/context-recency.test.ts`。
+ *
+ * 这一行就是补那份证据：不复原过程，只留一句「这一轮真的调了这些工具」。
+ *
+ * ## 判据用**结果**而不是调用
+ *
+ * `EpochToolCall` 上有工具名，但一次跑到一半被中止的轮次里那些调用**从没执行过**
+ * （判据逐字同 `runtime/src/session-file-changes.ts` 的边界 1）。而一条
+ * `EpochToolResult` 存在就意味着它跑完了 —— 拿结果当输入，「执行过没有」这件事
+ * 不需要另外判一次。
+ *
+ * ⚠️ **它分不出成功和失败**：落盘的结果上没有 `success`（同上那份的边界 2）。
+ * 所以措辞是「调用过」而不是「做成了」—— 一次被权限拒掉的 `file_write`
+ * 在这里照样留一笔，而那句话仍然是真的。
+ *
+ * ## 为什么住在 protocol、且是冻住的中文
+ *
+ * 它的读者是**模型**，和 {@link contentToText} / {@link filePartSummary} 同一类，
+ * 所以走同一条规矩：住在这个零依赖的包里、逐字冻住、**不跟着界面语言变**
+ * （门禁在 `packages/protocol/__tests__/message-projection.test.ts`）。一条进了
+ * 上下文的历史跟着 `EPOCH_LANGUAGE` 变语言，等于把同一段会话劈成两半。
+ *
+ * 只有工具名，不带参数 / 路径：带路径要 `affectedPaths()` + 工作目录，而那两样
+ * 住在 core 和装配层，拿不到的地方（`loadHistory()`）就会退化成另一种措辞 ——
+ * 两条路产出的历史一旦不一样，症状就是「刷新之后模型看到的和刚才不是同一段」。
+ *
+ * ⚠️ **调用方要的多半是 {@link assistantTurnText}，不是这一个** —— 那一份连
+ * 「正文和这一行之间怎么接」一起定了，而那正是两条路会走散的地方。
+ *
+ * @param results 这**一轮**（不是一步）执行过的全部工具结果，按发生序
+ * @returns 空数组时是空串 —— 这一轮没动手，那就没有这句话可说
+ */
+declare function turnDigest(results: readonly Pick<EpochToolResult, 'toolName'>[]): string;
+/**
+ * 一轮的 assistant 消息在**给模型的历史**里长什么样：正文 + {@link turnDigest}。
+ *
+ * ## 为什么这条胶水也得住在这儿
+ *
+ * 因为它有**两个调用方，走两条路，产出必须逐字节相同**：
+ *
+ * - 直播：`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` 里那条逐字节比对。
+ *
+ * 正文为空、只有 digest 时**不留前导空行**：那一轮模型只调了工具没说话
+ * （`loop.ts` 允许），这时这条消息的全部内容就是那一行。
+ *
+ * @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。
+ */
+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;
+    /**
+     * 多模态部件。给了就以它为准喂模型，`content` 退化成它的文本投影。
+     * **不落 SQLite** —— 图片走 artifact 目录，DB 里只留 content 的占位文本。
+     */
+    parts?: EpochContentPart[];
+    /** assistant 要求的工具调用；与 content 并存（模型可以边说话边调工具） */
+    toolCalls?: EpochToolCall[];
+    /** role 为 'tool' 时携带的执行结果 */
+    toolResults?: EpochToolResult[];
+    /**
+     * 这一步模型的思考原文（推理模型的 `reasoning-delta` 累加）。2026-08-18。
      *
      * **只给人看，不回灌模型**：`sdk-adapter.ts` 一个字都不读它。加它是因为
      * 刷新页面之前屏幕上有「深度思考」那一段，刷新之后整段消失 —— 而那不是
@@ -2852,23 +3848,262 @@ interface EpochMessage {
 }
 
 /**
- * `@路径` 提及的抽取规则（方案 25 §2.2）。
+ * `@` 提及的抽取规则、附件的体量上限、以及会话引用的装配
+ * （方案 25 §2.2、方案 53 §1.2 / §二 / §4.1）。
  *
  * ## 为什么这条规则住在 protocol
  *
  * 它有**两个**消费方，而且两边必须逐字一致：
  *
- * - TUI（`app.tsx`）—— 提交时要知道这条消息提到了哪几个文件
- * - 引擎（`core/context/mentions.ts`）—— 拿着这几个路径去读内容
+ * - TUI（`app.tsx`）—— 提交时要知道这条消息提到了哪几个文件 / 哪几段会话
+ * - 引擎（`core/context/mentions.ts`）—— 拿着这些提及去读内容
  *
  * 两边各写一份的后果不是崩溃，是**静默错位**：面板让你选了一个文件、
  * 抽取那侧却不认它，于是内容没附上，而界面上看不出任何异常。
  * tui 不许 import core，所以这条规则只能落在两边都够得着的地方。
  *
+ * ## 下半截（体量上限 + `attachSessionSurface`）为什么也在这儿（方案 53 PR-4）
+ *
+ * 同一条判据，只是消费方换了一对：会话引用的装配从 2026-08-21 起有**两条路**——
+ *
+ * | 路              | 谁在解析                            | `t()` 从哪来          |
+ * | --------------- | ----------------------------------- | --------------------- |
+ * | TUI / CLI       | `core/src/context/mentions.ts`      | `infra`               |
+ * | Web             | `server/src/mentions.ts`（PR-4）    | `runtime` 转出来的那份 |
+ *
+ * 而 **`@epoch-agent/server` 不许 import core**（`check-layers.mjs` 的 ALLOWED 表），
+ * 于是「50KB 怎么截、截了之后 `EpochSessionPart` 长什么样」这件事只有两个落点：
+ * 在服务端抄第二遍，或者搬到两边都够得着的这里。抄第二遍的形态很具体 ——
+ * TUI 上一段会话附了 48 条、web 上同一段附了 60 条，两边都不报错，
+ * 而「模型到底看见了什么」从此有两个答案。
+ *
+ * ⚠️ **那五个错误码（`SESSION_REFERENCE_ERROR_CODES`）住在 `message.ts` 已经是同一条
+ * 判据的先例**；这一份搬的是产出那个码的算术。
+ *
+ * ⚠️ **上限那张表整张搬，不搬一半。** 文件那三个数（单文件 / 每条几个 / 总量）和会话
+ * 那两个是**四道关卡的第四道**同一张表，而总量那一个本来就由两者共享 ——
+ * 拆成「文件的在 core、会话的在 protocol」的下场是两半各自漂移，
+ * 而它们相加才是「这一条消息能有多大」。
+ *
+ * ⚠️ **这个文件里不许出现 `Buffer`。** protocol 会被 `@epoch-agent/web` 打进浏览器包，
+ * 而 `Buffer` 在浏览器里不存在。字节口径一律走 `TextEncoder` / `TextDecoder`
+ * （两边都有，且和 `Buffer.byteLength(s, 'utf8')` 同值）。
+ *
  * 补全面板的**触发**条件（`tui/completion/files.ts` 的 `mentionAtCursor`）
  * 也必须和这里对齐 —— 那一侧是「光标处」的判定，逻辑不同但边界相同。
+ *
+ * ## 两种提及，一个前缀字符分开（方案 53 §1.2）
+ *
+ * ```
+ * @src/a.ts     → 文件（方案 25）
+ * @:ses_abc…    → 会话（方案 53）
+ * ```
+ *
+ * 用 `@:` 而不是让解析器去猜「这个字符串是路径还是会话」。判据是**猜会错**：
+ * 一个叫 `refactor` 的会话和一个叫 `refactor` 的目录长得一样，而猜错的后果是
+ * 「我明明要引用那个会话，它给我塞了一个目录」。
+ *
+ * ⚠️ **两种提及走的是同一条正则、同一套边界**（见下面那三条规则）。会话那一种
+ * 只是在拿到 `@` 后面那一截之后多剥一个 `:` —— 分成两条正则的话，
+ * 「`@` 前面必须是行首或空白」这条约束就有了两个实现，而它是挡住邮箱
+ * `a@b.com` 的唯一一道。
+ */
+
+/**
+ * 会话提及的前缀。**只有这一个字符**：`@:` 之后整截都是会话的匹配串
+ * （补全面板插进来的是 sessionId，手打时是标题 / cwd 的子串）。
+ */
+declare const SESSION_MENTION_PREFIX = ":";
+/** 一条消息里提到的东西，按种类分开 */
+interface MentionSet {
+    /** `@路径` 提到的文件，去重保序 */
+    files: string[];
+    /** `@:xxx` 提到的会话匹配串（**不含** `:` 前缀），去重保序 */
+    sessions: string[];
+}
+/**
+ * 从一行输入里抽出所有 `@` 提及。
+ *
+ * 三条规则（两种提及共用）：
+ *
+ * 1. **`@` 前面必须是行首或空白**。否则邮箱 `a@b.com` 会被当成提及了一个叫
+ *    `b.com` 的文件 —— 用户不会理解为什么自己的邮箱变成了附件
+ * 2. **中文标点直接不算路径字符**，英文标点只在结尾剥掉。这两条不对称是刻意的：
+ *    中文里「看一下 @src/a.ts，然后…」逗号后面**不留空格**，靠「剥结尾」救不了
+ *    （整串 `src/a.ts，然后…` 中间没有空白）；而英文的 `.` `-` `_` 在文件名里
+ *    极常见，不能整个排除，只能剥结尾
+ * 3. **去重保序**，两种提及各自去重。同一个文件在一句话里提两次不该附两遍
+ *
+ * 反斜杠一律换成 `/`：Windows 上用户可能敲 `@src\a.ts`，而候选清单、
+ * 匹配、以及最终的部件 `path` 全都用 `/`。
+ *
+ * ⚠️ **光秃秃一个 `@:` 什么都不产出**（既不是会话也不是文件）。改造前它会变成
+ * 一个叫 `:` 的文件提及，然后附上一句「`@:` 不在工作区里」—— 而用户那一刻
+ * 其实是刚敲下前缀、面板还没选。这一条有用例守着。
+ */
+declare function extractAllMentions(text: string): MentionSet;
+/**
+ * 只要文件那一种。
+ *
+ * 留着这个名字是因为它有一堆调用点，而**它的语义没变**：`@:xxx` 从来就不是
+ * 一个文件提及（改造前它会变成一个叫 `:xxx` 的路径，那是个 bug 不是特性）。
  */
 declare function extractMentions(text: string): string[];
+/** 只要会话那一种（方案 53） */
+declare function extractSessionMentions(text: string): string[];
+/**
+ * 这个路径**能不能被 `@` 表达出来**（方案 63：web 那一半的 `@文件`）。
+ *
+ * ## 为什么是一个「跑一遍真规则」的函数，而不是一张字符表
+ *
+ * 补全面板列出来的每一条，用户选中之后会被填进输入框，然后由
+ * {@link extractAllMentions} 再读一遍。这两侧不一致的后果**在界面上完全看不出来**：
+ * 面板让你选了 `src/my file.ts`，抽取那侧只认到 `src/my`，于是模型收到的是
+ * 「用户提到了一个叫 `src/my` 的文件，而它不存在」——
+ * 而屏幕上那一行字看起来一切正常。
+ *
+ * 所以这个判定**不许自己写一遍字符类**（`/[\s，。；]/` 那种）。上面那条
+ * `MENTION_RE` 加上剥尾巴、剥反斜杠、`:` 分流一共四条规则，抄成一张表的那一刻
+ * 它就有了两个实现，而它们会在下一次改规则时分叉 —— 而分叉的形态正是上一段
+ * 那种「看不出来的错位」。这里的做法是**把候选真的过一遍抽取器，看它回来还是不是
+ * 原样**，于是「边界逐字相同」不是一句叮嘱，是一个恒等式。
+ *
+ * 今天被它挡掉的四类（都不是假想的）：
+ *
+ * | 路径长什么样        | 为什么 `@` 表达不出来                      |
+ * | ------------------- | ------------------------------------------ |
+ * | `src/my file.ts`    | 空白就是提及的右边界                       |
+ * | `src/a，b.ts`       | 中文标点直接不算路径字符                   |
+ * | `notes/(1).md`      | 结尾的 `)` 会被当标点剥掉                  |
+ * | `:weird`            | 开头那个 `:` 会把它分流成一个**会话**提及  |
+ *
+ * ⚠️ **挡掉不等于可以不说。** 候选清单少一条而屏幕上没有任何交代，就是这个仓库
+ * 反复在骂的那种沉默截断 —— 所以数出来那个数要一路递到面板上
+ * （`WireFileCandidatesResponse.unmentionable`）。
+ */
+declare function isMentionableFilePath(path: string): boolean;
+/** 单个文件最多附多少字节 */
+declare const MAX_ATTACH_BYTES: number;
+/** 一条消息最多附几个文件 */
+declare const MAX_ATTACH_FILES = 20;
+/**
+ * 一条消息附件总量上限。**文件和会话共享这一个数**（方案 53 §4.1）——
+ * 两者进的是同一条消息，各自记一本账等于这条消息实际能有 400KB。
+ */
+declare const MAX_ATTACH_TOTAL_BYTES: number;
+/**
+ * 单段会话的当前面最多附多少字节（方案 53 §4.1）。
+ *
+ * 比单文件的 100KB 紧一半：一个会话的当前面比一个文件更容易失控 ——
+ * 文件是人写的，当前面是几十轮对话加工具输出攒出来的。
+ *
+ * ## 2026-08-21 拿真库量过一次（方案 53 §九「单个 50 KB 是否合适」）
+ *
+ * 一个 9 段会话的真实 `sessions.db`：**3 段超过 50KB**（57.4 / 69.8 / 71.9 KB），
+ * 而它们的当前面里 **72% ~ 85% 是工具输出** —— 上面那句「更容易失控」是量出来的，
+ * 不是猜的。三段各自被截成 49.9 / 49.2 / 49.7 KB，分别丢掉 6 / 17 / 24 条。
+ *
+ * **数字不改**，两条判据：一是总量共享 200KB，放到 100KB 之后两段引用就能吃掉
+ * 这条消息的全部预算（而 `@文件` 排在会话前面吃预算，见 `resolveMentions`）；
+ * 二是丢掉的那一段是**中间**，两头（压缩摘要 + 结论）都留着。
+ * 真正的结论是**截断是常态而不是边界情况**，所以那句提示语一个都不能省。
+ */
+declare const MAX_SESSION_ATTACH_BYTES: number;
+/**
+ * 一条消息最多引用几段会话。
+ *
+ * **2 而不是 20**（文件那个数）：引用三段会话说明该用检索而不是引用 ——
+ * 那时候用户其实不知道自己要哪一段，而 `session_search` 才是干这个的。
+ */
+declare const MAX_SESSION_REFS = 2;
+/**
+ * 当前面里的一条消息。
+ *
+ * **是结构镜像，不是把 core 的类型导出来**：真身是
+ * `core/src/session/reference.ts` 的 `SurfaceMessage`，而它结构上满足这一份
+ * （多出来的字段无所谓）。protocol 不许依赖 core，而这条判据在
+ * [wire-goal.ts](./wire-goal.js) 的文件头已经写过一遍。
+ */
+interface SessionSurfaceMessage {
+    role: string;
+    content: string;
+    /** 工具消息才有 */
+    toolName?: string | undefined;
+}
+/** 一段会话的当前面。core 的 `SessionSurface` 结构上满足它 */
+interface SessionSurfaceView {
+    sessionId: string;
+    /** 空标题在读的那一侧已经兜过 sessionId 了（方案 53 §5.3） */
+    title: string;
+    cwd?: string | undefined;
+    /** `active = 1` 的那些，时间正序 */
+    messages: readonly SessionSurfaceMessage[];
+    /** 那段会话一共多少条（含被压掉的） */
+    totalMessages: number;
+}
+/**
+ * 这一段引用最后落成了哪一档。
+ *
+ * 四档**穷尽**，而且各配一句不同的话（措辞归调用方 —— TUI 走 `locales` 的
+ * `mention.*`，web 走它自己那份 catalog）：
+ *
+ * | 档                 | 部件上                          | 该说的话                       |
+ * | ------------------ | ------------------------------- | ------------------------------ |
+ * | `full`             | `text` 全在                     | 不必说话，这是正常路径         |
+ * | `truncated`        | `text` + `truncatedTo`          | 附了几条 / 一共几条 / 上限多少 |
+ * | `empty`            | `text` 是空串                   | 那段会话还没有留下消息         |
+ * | `budget-exceeded`  | 没有 `text`，`omitted` 是那个码 | 这条消息的附件总量用满了       |
+ */
+type SessionAttachKind = 'full' | 'truncated' | 'empty' | 'budget-exceeded';
+/** {@link attachSessionSurface} 的结果 */
+interface SessionAttachResult {
+    part: EpochSessionPart;
+    kind: SessionAttachKind;
+    /** 真的附上了几条 */
+    kept: number;
+    /** 当前面一共几条 */
+    surfaced: number;
+    /** 这一段实际能用的字节预算；`budget-exceeded` 那一档是 0 */
+    budget: number;
+    /** 正文的字节数。**调用方拿它记这条消息的总账**，没附内容时 0 */
+    bytes: number;
+}
+/**
+ * 一段当前面 + 已经用掉的预算 → 一个 `EpochSessionPart`。
+ *
+ * **可读性判定不在这儿**（`SessionReferences.resolve` 已经判过了，那一处和方案 48
+ * 共用）。这个函数只做算术：够不够预算、要不要截、截了之后那几个字段怎么填。
+ *
+ * ⚠️ **`usedBytes` 是这条消息已经用掉的字节**（文件先吃、会话后到，见
+ * `core/src/context/mentions.ts` 的 `resolveMentions`）。传 0 就是「这条消息上
+ * 只有会话引用」—— web 那条路今天恰好是这一档（浏览器上还没有 `@文件`）。
+ */
+declare function attachSessionSurface(ref: string, surface: SessionSurfaceView, usedBytes: number): SessionAttachResult;
+/**
+ * utf8 字节数 —— 预算的单位。
+ *
+ * ⚠️ **`TextEncoder` 而不是 `Buffer.byteLength`**，理由见文件头最后那条 ⚠️：
+ * 这个文件会被打进浏览器包。两者对良构字符串同值。
+ */
+declare function utf8ByteLength(text: string): number;
+/**
+ * 当前面 → 一段文本，超预算时**从中间丢**（方案 53 §4.1「截断并告知，不是拒绝」）。
+ *
+ * ## 为什么丢中间，而不是像文件那样切尾巴
+ *
+ * 当前面的两头恰好是最值钱的两段：**头部**多半是压缩摘要（压缩器把前面几百条
+ * 浓缩成的那一段），**尾部**是这段会话的结论。切尾巴等于把结论丢掉，
+ * 只留头等于把结论丢掉的另一种写法。
+ *
+ * ## 为什么按**消息边界**丢，而不是按字节切
+ *
+ * 按字节切会在一条消息中间断开，模型读到半句话 + 一个替换字符。文件那一路只能
+ * 按字节切（它没有「条」这个结构），这一路有，就该用上。
+ */
+declare function packSessionSurface(messages: readonly SessionSurfaceMessage[], budget: number): {
+    text: string;
+    dropped: number;
+};
 
 /**
  * 「这一条 `user` 消息其实是系统在说话」—— 那个前缀的**唯一真源**
@@ -3791,24 +5026,128 @@ declare const HEADLESS_INPUT_EVENT_TYPES: ReadonlySet<string>;
  */
 type HeadlessInputEventType = HeadlessInputEvent['type'];
 
+/**
+ * 上下文预算的构成（方案 25 §2.5 的 `/context`）。
+ *
+ * ## 为什么值得一个契约
+ *
+ * 我们有压缩器，会在接近上限时自动压。但用户看不见**预算怎么花的** ——
+ * 压缩发生时他只知道「压了」，不知道「为什么这么快就压了」。
+ * 而答案常常很具体：一个 MCP server 的工具定义吃掉了四分之一窗口。
+ *
+ * 形状住在 protocol 是因为 TUI 和 web 都要画它，而两边都不许 import core。
+ */
+/** 预算里的一段 */
+interface ContextSegment {
+    /** 展示名，例如「工具定义」 */
+    label: string;
+    /** 估算的 token 数 */
+    tokens: number;
+    /** 一句补充说明，例如「14 个内置 + 6 个 MCP」。没有就不显示 */
+    detail?: string;
+}
+/**
+ * 一次上下文预算快照。
+ *
+ * ⚠️ **不变式：`segments` 之和 === `used`；`limit > 0` 时还有 `used + remaining === limit`。**
+ * 这不是「顺便成立」的性质，是这个结构存在的意义 —— 一个分段账目如果对不上，
+ * 它给用户的每一个结论都是错的。生产它的那一侧必须**由 segments 推出 used**，
+ * 而不是两边各算一遍。有用例钉着（`context-breakdown.test.ts`）。
+ *
+ * 第二条为什么要挂 `limit > 0`：查不到模型元数据时 `limit` 和 `remaining` **都是 0**，
+ * 而 `used` 照样是真数 —— 此时等式必然不成立，这是刻意的（见 `remaining` 的说明）。
+ * 消费侧要么先判 `limit > 0`，要么别用 `limit - used` 反推剩余。
+ */
+interface ContextBreakdown {
+    /** 模型的上下文窗口。查不到模型元数据时是 0 */
+    limit: number;
+    /** 已用 = 各段之和 */
+    used: number;
+    /** 剩余 = limit - used。limit 为 0 时也是 0（「不知道」不是「满了」） */
+    remaining: number;
+    segments: ContextSegment[];
+    /**
+     * 给用户的建议，例如「MCP server github 一家占了 18%，考虑改成 Deferred 曝光」。
+     *
+     * 只在**真有可操作动作**时给。「你的历史很长」不算建议 —— 用户对此无能为力，
+     * 而压缩器本来就会处理它。
+     */
+    hints: string[];
+}
+
 /**
  * 后台任务的契约（方案 36）。
  *
  * 「后台任务」= 一条不等它跑完就返回的命令。宿主要展示它们（TUI 的状态栏计数、
  * `/tasks` 列表、Web 的抽屉），所以形状住在 protocol。
  */
+/**
+ * 这一格是哪一类作业（方案 62，2026-08-26）。
+ *
+ * ⚠️ **它和 infra 那份 `JobKind` 必须逐字相同，而两边只能各存一份** ——
+ * `protocol` 零依赖、`infra` 也没有任何内部依赖（`scripts/check-layers.mjs` 的
+ * `ALLOWED` 表里两个都是空的），所以谁都 import 不到谁。
+ *
+ * 漂移不是靠叮嘱守的：**桥在 `plugin-terminal`**（它同时依赖两边），那儿有一条
+ * 编译期等式断言，任一边多一档或改一个字面量就当场编译不过。判据全文在
+ * `plugin-terminal/src/background.ts` 的 `KIND_MIRROR` 上。
+ */
+type BackgroundTaskKind = 'command' | 'shell' | 'agent';
 /**
  * 任务状态。
  *
  * `killed` 和 `exited` 分开，因为它们对模型意味着完全不同的事：前者是**我们**
  * 停的（`task_stop` 或宿主退出），后者是命令自己结束的（退出码才有意义）。
  * 合成一个 `done` 的话，模型看到一个非零退出码分不清是命令失败了还是被我们杀了。
+ *
+ * ## 2026-08-26（方案 62）：从四档变六档，多的两档是持久会话那一族的
+ *
+ * `closed`（主动关掉）和 `reaped`（空闲超时被回收）原来只活在 infra 那份
+ * `JobStatus` 上，到网线这一层被 `taskStatus()` 并成 `killed`。持久会话搬上
+ * 宿主界面之后那次合并**变成了一句假话**，而且正好是最要紧的那一句：
+ * `reaped` 在文案里写着「里面的工作目录、venv、REPL 都没了」
+ * （`locales/zh.yaml` 的 `reaped`，那一段自己标着「这里最要紧的一条」），
+ * 而屏幕上说「已停止」的东西看起来还能接着用。
+ *
+ * ⚠️ **别把这两档和 `killed` 并回去。** 判据不是「多两档更精确」，是
+ * **产出方各自的措辞已经发出去了** —— 逐字同 infra `JobStatus` 上那一段。
  */
-type BackgroundTaskStatus = 'running' | 'exited' | 'killed' | 'failed';
+type BackgroundTaskStatus = 'running' | 'exited' | 'killed' | 'failed' | 'closed' | 'reaped';
 interface BackgroundTaskInfo {
     /** 短 id，模型要在对话里引用它，所以是 `t1` 这种而不是 uuid */
     id: string;
-    command: string;
+    /**
+     * 哪一类（方案 62）。**新必填字段** —— 宿主要按它分支，
+     * 因为下面 {@link BackgroundTaskInfo.command} 只在 `'command'` 那一档才有。
+     */
+    kind: BackgroundTaskKind;
+    /**
+     * 一行标签，**各 kind 各自的「这是什么」**：命令行 / 持久会话的工作目录 /
+     * 子 agent 的目标。
+     *
+     * ## 为什么是一个合成字段，而不是三个可选字段
+     *
+     * 消费方（`/tasks` 那一行、检视面板那一格、`epoch -p` 的收尾摘要）要的正是
+     * 「一行说清楚它是什么」。判据逐字同 infra `JobInfo.label` —— 这一格就是
+     * **把那个已经设计好的形状搬到网线上**，不是新设计一个。
+     */
+    label: string;
+    /**
+     * 命令行。**只有 `kind === 'command'` 时才有。**
+     *
+     * ## ⚠️ 它没有变成 `label` 的别名，那是刻意的
+     *
+     * 「留着当别名」看起来最不破坏，但在持久会话那一档上 `command` 会是**一个工作
+     * 目录** —— 于是屏幕上同时出现两句互相打脸的话（判据同
+     * `WireMcpReconnectResponse.ok` 上那条）。这正是 2026-08-26 之前**不做**这件事的
+     * 全部理由：那时的结论是「`command` 那一格填不出实话」，所以宿主口子干脆只报
+     * 后台命令一类。
+     *
+     * 所以现在的形状是：`kind` 分支 + `label` 通用 + `command` **只在老那一档有**。
+     * 老宿主读 `.command` 在老那一档仍然拿到同一个值，新那一档拿到 `undefined`
+     * 而不是一句假话。新代码请一律读 `label`。
+     */
+    command?: string;
     cwd?: string;
     /**
      * 子 shell 的 pid。
@@ -4932,20 +6271,99 @@ interface WireSendMessageResponse {
      * 形状见 {@link WireCommandExpansion}。
      */
     command?: WireCommandExpansion;
+    /**
+     * 这条消息里 `@:` 引用到的那几段会话，**逐段一条收据**（方案 53 PR-4）。
+     *
+     * **一段都没引用时整个键缺席**（同上面那个 `command`），所以它不在下面那份
+     * 必填清单里。
+     *
+     * ## 为什么收据必须回在这一发上
+     *
+     * 引用的解析在**服务端**（可读性判定在引擎里，浏览器不许自己读
+     * `sessions.db` —— 判据在 `EpochRuntime.sessionReferences` 上），而这一发之后
+     * 浏览器不会再为这条消息去问一次：SSE 上流的是模型那一侧的事件，
+     * 用户自己那条消息是本地乐观回显的（`state/reducer.ts` 的 `submit`）。
+     * 不回收据的话，界面只知道「用户打了 `@:xxx`」，说不出**它有没有生效**，
+     * 而那五个错误码（匹配不到 / 引用自己 / 超上限 / 判定不放行 / 预算用满）
+     * 恰好全是「看起来发出去了、实际没附内容」的形态。
+     *
+     * ⚠️ **它不带一个字的转录文本**，判据在 {@link WireSessionReference} 上。
+     */
+    references?: readonly WireSessionReference[];
+    /**
+     * 这条消息里 `@路径` 附上了哪几个文件，**逐个一条收据**（方案 63）。
+     *
+     * **一个都没附时整个键缺席**，判据逐字同上面那两个键。
+     *
+     * ## 为什么这一份也必须回在这一发上
+     *
+     * 理由和上面那条 `references` 是同一条，而且这一半更急：`@文件` 那四个失败档
+     * （被权限拦了 / 是二进制 / 读不到 / 超了上限）**全都是「看起来发出去了、
+     * 实际没附内容」的形态**，而其中「被权限拦了」还是一句用户必须听见的话 ——
+     * 这条路上刻意**不弹审批**（判据在 `core/src/context/mentions.ts` 的
+     * 「权限没放行时不弹审批，只是不附」那一节），所以屏幕上那张卡是他唯一的交代。
+     * 不回收据的话，一个 `deny` 规则挡住的 `@.env` 和一次正常附上长得一模一样。
+     *
+     * ⚠️ **它不带一个字的文件正文**，判据在 {@link WireFileReference} 上。
+     */
+    files?: readonly WireFileReference[];
 }
-declare const WIRE_SEND_MESSAGE_RESPONSE_FIELDS: WireFields<WireSendMessageResponse>;
-/** `aborted: false` 表示这一轮本来就没在跑，不是失败 */
-interface WireAbortResponse {
-    aborted: boolean;
-}
-declare const WIRE_ABORT_FIELDS: WireFields<WireAbortResponse>;
 /**
- * `GET /api/sessions/:id/approvals` —— 重连之后补拉挂起的审批。
+ * 一段会话引用**在网线上的样子** —— 就是那个部件**摘掉正文**。
  *
- * `state` **不是**附赠字段：刷新一次页面之后，「现在到底有没有东西在跑」只有它答得上来
- * （SSE 的 `session-state` 要等下一次状态变化才发）。前端首屏必须用它。
+ * 写成 `Omit<EpochSessionPart, 'type' | 'text'>` 而不是再抄一遍七个字段：
  *
- * 每一行就是 SSE 上那个 `WireApprovalRequest`（**带 `type`**），不另造一个形状 ——
+ * - 抄一遍的下场是部件上加一格（比如将来的 `startedAt`）而这儿忘了加，
+ *   于是界面永远看不到它，**而两边都编译得过**；
+ * - 摘掉 `text` 是**契约上的一句话**：这条线上不许出现另一段会话的转录。
+ *   正文是给模型的 —— 它已经进了这条消息的 `parts`（而且落库那一侧刻意不存，
+ *   见 `core/src/session/payload.ts` 的 `persistParts`），
+ *   而浏览器拿它只能把几十 KB 的别人家转录再复制一份到网线上。
+ *   写成 `Omit` 之后，谁想把正文发给浏览器得先来改这一行 ——
+ *   那正好是该被人看见的一次改动；
+ * - 摘掉 `type` 是因为它在这儿是恒等式（`'session'`），
+ *   而在 `parts` 数组里它是判别标签。
+ *
+ * ⚠️ 这一条顺带把「界面上那张卡要不要能展开」答了：**没有可展开的正文**。
+ * 判据全文在 `web/src/mention/reference-card.tsx` 的文件头。
+ *
+ * ⚠️ `omitted` 那五个码是稳定契约，真源是 `SESSION_REFERENCE_ERROR_CODES`
+ * （`message.ts`）。界面按**码**分档说话，别按话分档。
+ */
+type WireSessionReference = Omit<EpochSessionPart, 'type' | 'text'>;
+declare const WIRE_SESSION_REFERENCE_FIELDS: WireFields<WireSessionReference>;
+/**
+ * 一个文件附件**在网线上的样子** —— 就是那个部件**摘掉正文**（方案 63）。
+ *
+ * 写成 `Omit<EpochFilePart, 'type' | 'text'>`，三条判据逐字同
+ * {@link WireSessionReference}（那一份是这一份的先例，先读它）：
+ *
+ * - 摘掉 `text` 是**契约上的一句话**：这条线上不许出现文件正文。正文是给模型的
+ *   ——它已经进了这条消息的 `parts`。发给浏览器只能把同一份内容在网线上再抄一遍，
+ *   而浏览器拿它没有任何用处（用户手上就有那个文件，点开编辑器就能看）；
+ * - 摘掉 `type` 是因为它在这儿是恒等式（`'file'`）；
+ * - 写成 `Omit` 而不是抄一遍四个字段，是为了让部件上加一格（比如将来的 `mtime`）
+ *   时这儿不会**忘了加而两边都编译得过**。
+ *
+ * ⚠️ **`path` 之外每一格都可缺席，而这正是它要表达的东西**：二进制、超限、
+ * 权限没放行的那几档**只有路径**。界面按 `omitted` 那个**码**分档说话，
+ * 别按话分档 —— 真源是 {@link FileOmitReason}。
+ */
+type WireFileReference = Omit<EpochFilePart, 'type' | 'text'>;
+declare const WIRE_FILE_REFERENCE_FIELDS: WireFields<WireFileReference>;
+declare const WIRE_SEND_MESSAGE_RESPONSE_FIELDS: WireFields<WireSendMessageResponse>;
+/** `aborted: false` 表示这一轮本来就没在跑，不是失败 */
+interface WireAbortResponse {
+    aborted: boolean;
+}
+declare const WIRE_ABORT_FIELDS: WireFields<WireAbortResponse>;
+/**
+ * `GET /api/sessions/:id/approvals` —— 重连之后补拉挂起的审批。
+ *
+ * `state` **不是**附赠字段：刷新一次页面之后，「现在到底有没有东西在跑」只有它答得上来
+ * （SSE 的 `session-state` 要等下一次状态变化才发）。前端首屏必须用它。
+ *
+ * 每一行就是 SSE 上那个 `WireApprovalRequest`（**带 `type`**），不另造一个形状 ——
  * 前端补拉回来的东西可以和 SSE 推过来的走同一条处理路径。
  */
 interface WireApprovalListResponse {
@@ -5838,6 +7256,69 @@ interface WireCreateWorkspaceResponse {
     entry: WireWorkspaceDirEntry;
 }
 declare const WIRE_CREATE_WORKSPACE_RESPONSE_FIELDS: WireFields<WireCreateWorkspaceResponse>;
+/**
+ * `GET /api/sessions/:id/context` —— **这一段会话**此刻的预算构成。
+ *
+ * 包一层而不是裸发 {@link ContextBreakdown}，判据同本文件开头那条列表规矩：
+ * 将来要加「上次压缩发生在哪一轮」之类的同级事实时，响应形状不用整个换掉。
+ *
+ * ⚠️ **`breakdown` 可以是 `null`，那不是错误。** 这个进程认得这段会话、但它此刻
+ * 没有活着的循环（只读会话、provider 没起来）时就是这一档 —— 那时正确的答案是
+ * 「不知道」，不是 404（会话真的在），也不是一份全零的构成（那是在编一个数）。
+ * 界面据此**整块不画**（决定 20 ①），而不是画一张空的条形图。
+ */
+interface WireContextResponse {
+    breakdown: ContextBreakdown | null;
+}
+declare const WIRE_CONTEXT_FIELDS: WireFields<WireContextResponse>;
+/**
+ * `POST /api/sessions/:id/compact` 的请求体。
+ *
+ * `instruction` 是「这次帮我留住什么」，逐字对应 TUI `/compact <说明>` 的那段参数
+ * （`tui/src/commands/session.ts`）。**不给和给空串是同一件事** ——
+ * 底下 `AgentSession.compact()` 收的就是 `string | undefined`。
+ */
+interface WireCompactRequest {
+    instruction?: string;
+}
+/**
+ * `POST /api/sessions/:id/compact` —— 压完之后的账。
+ *
+ * 四个字段**逐字照抄** `runtime/src/agent-session.ts` 的 `compact()` 返回值，
+ * 一个都不重新命名：这条路上服务端不做任何判断，它只是把引擎那句话搬过网线。
+ * 在这儿改个名字的代价是同一件事在两侧有两个说法，而那正是这个文件存在的理由。
+ *
+ * ## ⚠️ 「没压动」是一个正常结果，不是错误
+ *
+ * `ran: false` 有两种来路（历史太短、压缩器没装上），`ran: true` 但
+ * `after === before` 是第三种（摘要生成失败时压缩器原样返回消息）。**三种都回
+ * 200**，因为这次请求确实办完了 —— 而且第三种**钱是真花了**，用户该知道花在了哪。
+ * 界面必须把这三档和「已压缩」分开说，报一个假的「已压缩」是在骗人
+ * （判据全文在 TUI 那条命令的实现上，两边共用同一组结论）。
+ *
+ * ## ⚠️ 压缩**不动落盘的那份记录**
+ *
+ * 它换掉的是内存里那份对话（`AgentSession.history`）—— 也就是「下一轮送进模型的
+ * 是什么」。`GET /messages` 读的是会话库，压完之后**一行都不会少**。
+ * 所以调用方压完**不该**去重拉消息：拉回来的和压之前逐字相同，而那一下
+ * 会让人以为压缩没生效。
+ */
+interface WireCompactResponse {
+    /** 压缩器**跑了没有**。`false` 时 `before === after`，理由在 `reason` 里 */
+    ran: boolean;
+    /** 压之前内存里的消息条数 */
+    before: number;
+    /** 压之后的条数。`ran` 为真时仍可能等于 `before`，见上面那一节 */
+    after: number;
+    /**
+     * 没跑的原因，**引擎渲染好的一句话**，原样透传。
+     *
+     * 不在服务端重新编：两种来路（太短 / 没装上）的下一步完全不同，
+     * 而它们的措辞已经过了引擎那侧的 catalog。
+     */
+    reason?: string;
+}
+declare const WIRE_COMPACT_FIELDS: WireFields<WireCompactResponse>;
 
 /**
  * 能力页的载荷契约 —— `GET /api/sessions/:id/capabilities`（方案 42 PR-1）。
@@ -5893,6 +7374,35 @@ interface WireAgentRoleSummary {
      * 用 `null` 而不是省略这个键，是因为省略在 JSON 里和「忘了填」长得一模一样。
      */
     tools: readonly string[] | null;
+    /**
+     * 技能索引白名单（`AgentRole.skills`，2026-08-27）。**`null` = 不限**（全量
+     * 索引），空数组 = 索引里一条都不列 —— 缺省语义和上面 `tools` 逐字相同，
+     * 用 `null` 而不是省略这个键的理由也逐字相同。
+     *
+     * ## 为什么补这一格：这一屏原来看不见一个身份的技能白名单
+     *
+     * `skills` 2026-08-26 就在引擎里生效了，2026-08-27 又长出了界面上那张表单
+     * （`WireRoleAddRequest.skills`）—— 而这一份摘要上一直没有它。于是**填了白名单
+     * 建出来的那张卡一个字都不提它**，手写 md 建的身份同样看不见：两条路缺的是
+     * 同一样东西，也就是这一格。
+     *
+     * ⚠️ 它**不是** {@link skillsCut} 的另一个说法，两格答的是两个问题：
+     *
+     * | 这一格       | 答的是                                         |
+     * | ------------ | ---------------------------------------------- |
+     * | `skills`     | 这个身份**自己声明**了哪几条（`null` = 没声明） |
+     * | `skillsCut`  | 同名覆盖时**被上一层砍掉**了哪几条             |
+     *
+     * 合成一格的话，「我写了三条」和「我写了五条掉了两条」在网线上长得一样。
+     *
+     * ## ⚠️ 界面上别把它画成一道墙
+     *
+     * 被这一格挡在索引外的技能，这个身份**照样 `skill_view` 得到正文** ——
+     * 收窄的宾语是上下文预算，不是可达性（判据全文在 `AgentRole.skills` 上，
+     * 由 `core/__tests__/skill-in-prompt.test.ts` 那条钉着）。措辞的口径逐字同
+     * `web.ui.cap.role_add_skills_hint`：**只管索引里列不列得出**。
+     */
+    skills: readonly string[] | null;
     /** 轮次上限。`null` = 跟全局（`max(4, floor(父 maxTurns / 2))`） */
     maxTurns: number | null;
     /**
@@ -5904,6 +7414,29 @@ interface WireAgentRoleSummary {
      * 本来就是那几枚划掉的工具芯片（设计稿的 `[data-cut]`）。
      */
     toolsCut: readonly string[];
+    /**
+     * 同名覆盖被收窄时**掉了哪几条技能**（`AgentRole.skills`，2026-08-27）。
+     * 没收窄就是空数组。
+     *
+     * ## ⚠️ 为什么是**第二格**，不是往 `toolsCut` 里混
+     *
+     * 这一格是补一笔明写着「加第一个带 `skills` 的内置角色**之前必须先补**」的账
+     * （记账全文在
+     * [RECORD-skill-index-narrowing](../../../docs/verify/VERIFY_RECORD-skill-index-narrowing.md) §四第 3 条）。
+     * 那笔账的**内容**就是这一句：`toolsCut` 被 web 画成划掉的**工具**芯片
+     * （`[data-cut]`），把技能名混进去的表现是界面上多出几枚**根本不存在的工具**，
+     * 而没有任何东西会红 —— 两边都是 `string[]`。
+     *
+     * 所以刀口下在这儿而不是把 `toolsCut` 泛化成 `cut: {kind, names}[]`：后者要动
+     * 一个已经在用的字段，而它的读者（`experts.tsx` 那两处）今天一个字没错。
+     * core 那一侧的 `RoleMergeNotice` 加的是一格 `kind` —— **投影这一层按 `kind`
+     * 分流**，`server/src/capability.ts` 的 `toWireRole()` 那两行 `find` 就是分流点。
+     *
+     * ⚠️ **今天三个内置角色一条 `skills` 都没有，所以这一格恒空。** 那不代表它是
+     * 死代码：它守的正是「加第一个带技能白名单的内置角色那一天」——
+     * 那天没有这一格的话，收窄会**静默**发生。
+     */
+    skillsCut: readonly string[];
 }
 declare const WIRE_AGENT_ROLE_FIELDS: WireFields<WireAgentRoleSummary>;
 /**
@@ -5933,8 +7466,45 @@ interface WireSkillSummary {
      * 是估算不是实测：真值取决于具体模型的分词器，而这里没有分词器。
      * 引擎自己的预算账（`context-breakdown.ts`）用的就是同一个估法，
      * 所以这个数和引擎看到的是同一个数 —— 只是它们一起是估的。
+     *
+     * ⚠️ **这个数说的是「它那一行**如果*进索引*要多少钱」，不是「它一定在付」** ——
+     * 后半句归 {@link residency}，2026-08-27 补的就是它。别在界面上单独印这一格，
+     * 判据在那一格上。
      */
     tokens: number;
+    /**
+     * 这一条**此刻**在不在 `<available_skills>` 里 —— 也就是上面那个
+     * {@link tokens} 到底付没付（2026-08-27）。
+     *
+     * ## 为什么补这一格：那一栏行尾原来在说一句会变假的话
+     *
+     * 能力页每一行行尾印的是「这条技能每一轮的常驻开销」。那句话在两道口子都
+     * 关着时是真的，而它们各自都能把它变成假话：
+     *
+     * | 值        | 谁挡的                                        | 用户的下一步                              |
+     * | --------- | --------------------------------------------- | ----------------------------------------- |
+     * | `indexed` | 没人挡，它真的每一轮都在                      | 没有下一步                                |
+     * | `capped`  | `skills.maxIndexed` 封了顶（**进程级**）      | 那一格调大或去掉                          |
+     * | `role`    | 这段会话身份的 `skills` 白名单（**会话级**）  | 换个身份开会话，或改那份角色 md           |
+     *
+     * 三档不是三种颜色，是三种下一步 —— 形状和判据逐字同 {@link WireMcpConnector.state}。
+     * 合成一个 `indexed: boolean` 的话，界面只说得出「它不在」，说不出去哪儿改。
+     *
+     * ## ⚠️ `role` 这一档**不是一把锁**
+     *
+     * 被它挡住的技能，模型照样 `skill_view` 得到正文 —— 收窄的宾语是**上下文预算**，
+     * 不是可达性（判据全文在 `agent-role.ts` 的 `AgentRole.skills`）。所以界面上
+     * 别给它画锁 / 画禁行标：那会让用户以为自己配出了一道边界，
+     * 而任何带 `file_read` 的角色都能直接读那份 `SKILL.md`。
+     *
+     * ## 它是**这个会话**的答案，所以这条端点是会话作用域的
+     *
+     * `capped` 那一半是进程级的，`role` 那一半跟着会话走
+     * （服务端拿的是 `LiveSession.role`，也就是**底座身份**，不是那枚 chip 挑的
+     * 逐条身份 —— 「常驻」的宾语是整段会话）。`GET /api/sessions/:id/capabilities`
+     * 早就是会话作用域了，判据在 `server/src/capability.ts` 文件头最后一节。
+     */
+    residency: 'indexed' | 'capped' | 'role';
     /** `host` 同 {@link WireAgentRoleSummary.source} 那一格：宿主 ship 的技能目录 */
     scope: 'user' | 'project' | 'plugin' | 'host';
     /** `workflow` / `rule` / `pattern` / `checklist` */
@@ -6363,7 +7933,7 @@ declare const WIRE_SKILL_IMPORT_FIELDS: WireFields<WireSkillImportResponse>;
 /**
  * `POST /api/roles` 的请求体 —— 稿子上有、身份那一栏一直没有的那张「新建」。
  *
- * ## 五格，和 frontmatter 逐格对上，一格不多
+ * ## 六格，和 frontmatter 逐格对上，一格不多
  *
  * 角色文件是 Markdown + YAML frontmatter，认得的键只有四个
  * （`name` / `description` / `tools` / `maxTurns`，真源是 `loader.ts` 的
@@ -6372,6 +7942,19 @@ declare const WIRE_SKILL_IMPORT_FIELDS: WireFields<WireSkillImportResponse>;
  * 十几格而表单只解决「第一台加不进来」；这边总共就四个键，砍掉任何一个都会让
  * 「从界面建的身份」和「手写的身份」变成两种东西。
  *
+ * > 📮 **2026-08-26 这句话过期了一半：** `FrontmatterSchema` 那时起认**五个**键
+ * > —— 技能收窄那一轮加了 `skills`（`AgentRole.skills`），「只有四个」成了假话。
+ * > 当时 `skills` **刻意不在请求体里**，理由逐字是：「加了就是一个界面写得出、
+ * > 引擎读得到、但**没有一张表单会填它**的字段，那比不加更坏。」
+ * >
+ * > ✅ **2026-08-27 补齐了，那条理由因此到期 —— 但它没被推翻，是被满足了。**
+ * > 这一轮同时加了请求体那一格**和 `role-add.tsx` 上那张表单里的那一格**，
+ * > 两个一起落地。⚠️ 所以那句话的**规矩**照旧有效：往这张表里加第六格的人，
+ * > 要么连表单一起加，要么别加。
+ * >
+ * > 于是「六格，和 frontmatter 逐格对上，一格不多」重新是逐字真的：
+ * > `name` / `description` / `tools` / `maxTurns` / `skills` 五个键 + 正文 = `prompt`。
+ *
  * ## ⚠️ 落点恒为**用户级**（`~/.epoch/agents/<name>.md`），请求体里没有这一格
  *
  * 不给「写用户级还是项目级」的选择：项目级那一层跟着工作区走（决定 18），
@@ -6417,6 +8000,32 @@ interface WireRoleAddRequest {
      * 「引用了不存在的工具」，那时屏幕上没有任何东西指向这个输入框。
      */
     tools?: readonly string[];
+    /**
+     * 技能索引白名单（2026-08-27）。**不给 = 不限**（全量索引），给空数组 =
+     * 一条都不列 —— 缺省语义和上面 `tools` 逐字相同，判据在 `AgentRole.skills` 上。
+     *
+     * ## ⚠️ 和 `tools` 那一格**唯一的不同**：服务端**不当场校验这几个名字**
+     *
+     * 工具那一格认不出名字就 400，理由是「用户此刻正在敲它，而服务端此刻手上就有
+     * 那张工具表」。这一格照抄那条会是错的，因为**两张表的性质不同**：
+     *
+     * | 　     | 什么时候定的           | 「此刻不认识」意味着什么           |
+     * | ------ | ---------------------- | ---------------------------------- |
+     * | 工具表 | **装配期**，一次定死   | 这个名字打错了                     |
+     * | 技能表 | **会话中途还会变**     | 可能只是还没装 / 还没被学出来      |
+     *
+     * 技能表会变这件事不是推测，是 `createSkillViewTool` 的 JSDoc 上现成的判据：
+     * `SkillLearner` 学一条就往用户级目录里落一份 SKILL.md。把「此刻没装」判成
+     * 400，等于拒掉一个**明天就成立**的名字，而用户手上没有任何办法让它今天成立。
+     *
+     * 打错的那一档没有被放过：启动诊断 `unknownRoleSkills()` 照旧逐个报出来
+     * （`role_unknown_skills`）—— 那条路对「今天没有、明天会有」的名字恰好是对的
+     * 语气（一句警告，不是一次拒绝）。
+     *
+     * ⚠️ **别顺手补一道 400。** 补之前先回答：一个用户想给身份预留一条还没装的
+     * 技能名，他该怎么办。
+     */
+    skills?: readonly string[];
     /** 轮次上限。不给 = 跟全局。范围由 `FrontmatterSchema` 说了算（1–200 的整数） */
     maxTurns?: number;
 }
@@ -6461,6 +8070,395 @@ interface WireRoleAddResponse {
 }
 declare const WIRE_ROLE_ADD_RESPONSE_FIELDS: WireFields<WireRoleAddResponse>;
 
+/**
+ * 插件那一页的契约 —— 六条端点（方案 59 §六 E2，2026-08-21）。
+ *
+ * ```
+ * GET  /api/plugins                    装着的 + 市场里有什么 + pendingRestart
+ * POST /api/plugins/install/preview    {ref}          → 将安装什么，一个字节都不写
+ * POST /api/plugins/install            {ref, token}   → 真装
+ * POST /api/plugins/update/preview     {name}         → 更新会带来什么
+ * POST /api/plugins/update             {name, token}  → 真更新
+ * POST /api/plugins/uninstall          {name}         → 卸载
+ * ```
+ *
+ * 底座是 `EpochRuntime.plugins`（方案 59 PR-4 落的那一片，判据全文在
+ * `runtime/src/plugin-control.ts` 的文件头）。**这一层一条策略判断都没有** ——
+ * 谁能装、装什么、要不要重启，三个问题的答案全在那一片里，网线这一侧只是把它
+ * 转出来。⚠️ 唯一的例外是下面第二节那道闸，而它答的是一个 runtime 那一层**问不到**
+ * 的问题（「网线另一头是不是这台机器」）。
+ *
+ * ## 为什么不塞进 [wire-capability.ts](./wire-capability.ts)
+ *
+ * 判据逐字同 [wire-agent-role.ts](./wire-agent-role.ts) 从那儿分出来那次：那个文件
+ * 已经压过 500 行线，而**刀口按题目下不按行数** —— 那份答的是「能力页那三栏读什么」，
+ * 这一份答的是「怎么往这台机器上装一包扩展物」，而后者带着一整套预览形状 +
+ * 七档拒绝 + 一格 `pendingRestart`。
+ *
+ * ---
+ *
+ * # 一、⚠️ **只收 `<市场>/<插件>`，收不了路径** —— 这是这条路的安全性质本体
+ *
+ * {@link WirePluginInstallRequest} 上**没有 `source` 这个东西**，只有一个
+ * {@link WirePluginInstallRequest.ref}。于是「指一条任意路径装一个插件」这件事
+ * 在这个形状下**说不出口** —— 不是靠 review 盯住的，是编译期的事
+ * （同 `HostAgentRole` 少一个 `source`、同 runtime 那一层 `preview(ref)` 的入参）。
+ *
+ * 逐条对着今天那条最像的路（`POST /api/skills/import`）：
+ *
+ * | 判据             | `skills/import` 今天      | 这一条                     |
+ * | ---------------- | ------------------------- | -------------------------- |
+ * | 能不能传字节     | 不能（只收路径）          | 不能                       |
+ * | 能不能指任意路径 | **能**（收一个任意 path） | **不能**（只能从清单里挑） |
+ * | 清单是谁放的     | —                         | 宿主主进程 / 用户自己敲的  |
+ *
+ * ⚠️ 「清单」= `~/.epoch/marketplaces.json` 里那些，也就是**宿主预置的**加上
+ * **用户自己 `epoch plugin marketplace add` 加的**。要装清单外的东西，路仍然在，
+ * 只是**在命令行上** —— 那一问的闸门只该有一份。
+ *
+ * # 二、⚠️ 闸门：**绑在回环之外时那五条 POST 一律 403**
+ *
+ * 判据同 [wire-agent-role.ts](./wire-agent-role.ts) 那道，但**这条路比它还远一格**，
+ * 三条：
+ *
+ * 1. **装一个插件会带进 hook 和 `mcp.json`，那两样起子进程。** 一份 `hooks.json`
+ *    里的 `PreToolUse` 就是一条 shell 命令，`mcp.json` 里的一台就是一个可执行
+ *    文件的启动项 —— 下一程启动时它们照着跑。往 `~/.epoch/agents/` 落一份 md
+ *    只影响模型看到的字，这一条影响的是**这台机器上会跑起什么进程**；
+ * 2. **`install/preview` 那条也吃这道闸，虽然它一个字节都不写。**
+ *    `allowRemote: true` 的宿主上，预览一条远程条目会 spawn `git clone --depth 1`
+ *    到 staging（判据在 core 的 `install.ts` 那张表）—— 那是一次**由网线发起的
+ *    子进程**，不是一次只读。五条一起挡，比按「写不写盘」切一刀诚实；
+ * 3. **不能拿「反正他能让 agent 跑命令」开绿灯**，判据逐字同 `wire-agent-role.ts`
+ *    第三节：`plan` 档和只读会话下 agent 一个字节都落不了盘，而这条端点落得了。
+ *
+ * ⚠️ **界面那一侧还有一道，但它是给人的**：`GET /api/config` 上带着 `lanExposed`，
+ * 那一页据此在**按下去之前**把「这一档下装不了」画出来（决定 20 ①）。
+ * 两道各答一半 —— 别因为界面上画了就把服务端这道摘掉，那一格是客户端自己改得动
+ * 的布尔。
+ *
+ * ⚠️ **`GET /api/plugins` 刻意不挡**，而这和 `GET /api/mcp/config` 刻意挡**不矛盾**：
+ * 那份文件里的 `env` 是明文密钥，这一份里是插件名、版本、目录路径 —— 和
+ * `GET /api/sessions/:id/capabilities` 早就在发的那些（技能名、角色名、工作区根）
+ * 同一档。挡掉它的唯一后果是那一页在 LAN 那一档下变成一片空白，
+ * 而**用户最需要的恰恰是在那一档下也看得见「我装了什么、生效了没有」**。
+ *
+ * # 三、⚠️ `pendingRestart`：装完**不会生效**，而这一格是那句话的全部凭据
+ *
+ * 扩展物在启动时加载（`loadPlugins` 一程跑一次），所以一次成功的 install /
+ * update / uninstall 之后 {@link WirePluginsResponse.pendingRestart} 变 `true`
+ * 并且**此后不再变回去**。判据、以及「为什么重建一次就够（加载器一个字节 JS
+ * 都不执行）」，全文在 `runtime/src/plugin-control.ts` 文件头第二节。
+ *
+ * **界面上必须能看出这个中间态**，而它需要**两格一起看**才成立：
+ *
+ * | 那一格                                    | 答的是                             |
+ * | ----------------------------------------- | ---------------------------------- |
+ * | {@link WirePluginsResponse.pendingRestart} | **这一程**动过插件、还没生效       |
+ * | {@link WirePluginEntry.active}             | **这一个**此刻真的在生效吗         |
+ *
+ * 少了前者，用户点完那一下之后没有任何东西提示他还差一步；少了后者，一个刚装完
+ * 的插件在列表里和一个正在生效的**长得一模一样**（那正是「点了半个反应」的形态）。
+ * ⚠️ 而 `active: false` 有两种成因，界面要分开说：**这一程刚装上**（要重启），
+ * 或者**它被停用 / 版本不符 / 目录没了**（那时启动诊断里有一条指名道姓的）——
+ * 前者的判据就是 `pendingRestart`，所以那两格必须一起下发。
+ *
+ * # 四、这一整片可以整个不存在（503 `no-plugin-control`）
+ *
+ * `EpochRuntime.plugins` 在宿主没给 `hostMarketplaces` 时是 `null`，而那不是
+ * 「底下那层起不来了」，是**「宿主没打算给用户这条路」**（判据在 `build.ts` 那一格
+ * 的 JSDoc 上：它是一个真的新攻击面，所以是选进来的，不是白送的）。
+ *
+ * 六条端点那时一律 **503 `no-plugin-control`**，判据同 `no-goal-store`：
+ * 那一档是一句关于**这个部署**的真话，不是一份「装了 0 个插件」的空列表 ——
+ * 两者在界面上是两句完全不同的话（后者会让用户去找那个不存在的「安装」按钮）。
+ */
+/**
+ * 一个插件是从哪儿装来的。**照抄 core 的 `PluginSourceType`，不是第二套枚举** ——
+ * 界面据此说「这是一条软链 / 这是 clone 下来的」。
+ */
+type WirePluginSourceType = 'local' | 'git' | 'npm' | 'archive';
+/** 六类扩展物各贡献了几条。字段名照 core 的 `PluginCounts`，不自造映射 */
+interface WirePluginCounts {
+    commands: number;
+    roles: number;
+    skills: number;
+    /** hook 的**条数**（跨所有事件），不是事件种类数 */
+    hooks: number;
+    /** `settings.json` 里的 deny 条数。`allow` / `ask` 不算：它们本来就不生效 */
+    denyRules: number;
+    mcpServers: number;
+}
+/** 装着的一个插件在浏览器眼里的样子 */
+interface WirePluginEntry {
+    name: string;
+    version: string;
+    /** 用户 / 宿主敲的那串来源，原样 */
+    source: string;
+    sourceType: WirePluginSourceType;
+    /** 插件目录的绝对路径。**要发**，同 `WireRoleAddResponse.path`：出了事用户得知道去哪儿看 */
+    path: string;
+    /** 本地目录装的是软链（改源码、重启即生效），其余是真实拷贝 */
+    linked: boolean;
+    enabled: boolean;
+    installedAt: number;
+    /** 从市场装的才有，否则 `null`（**不是省掉这个键**，见 {@link counts}） */
+    marketplace: string | null;
+    /**
+     * **这一程真的加载了它吗。**
+     *
+     * ⚠️ 这一格和 {@link WirePluginsResponse.pendingRestart} 是一对，判据在文件头
+     * 第三节：少了它，一个刚装完的插件和一个正在生效的在列表里长得一模一样。
+     */
+    active: boolean;
+    /**
+     * 它带来了什么。**只有 {@link active} 那些有**，其余是 `null` ——
+     * 没加载的插件我们没有数过它，给一个全 0 的对象会被读成「它什么都不带」。
+     *
+     * ⚠️ 缺席时下发 `null` 而不是省掉这个键，判据同 `WireSkillImportEntry.conflict`：
+     * 写成必填之后「服务端忘了转这一格」当场编译不过。
+     */
+    counts: WirePluginCounts | null;
+}
+/** 市场里的一条 */
+interface WirePluginHit {
+    /** 哪个市场 */
+    marketplace: string;
+    /** `<市场>/<插件>` —— 原样发回 {@link WirePluginInstallRequest.ref} */
+    ref: string;
+    name: string;
+    /** 目录里那句。没写就是空串 */
+    description: string;
+    category: string | null;
+    keywords: readonly string[];
+    /** 解析出来的来源档位；这一条的 source 看不懂时 `null` */
+    sourceType: WirePluginSourceType | null;
+    /**
+     * 在**当前**开关下装得上吗。
+     *
+     * ⚠️ **不从结果里剔掉装不上的那些**（runtime 那一层就已经这么定了，判据在
+     * `PluginSearchHit.installable` 上）：剔掉的话界面上少一条，而用户唯一能得出
+     * 的结论是「这个市场里没有那个东西」。该画成不可点 **+ 说出原因**。
+     *
+     * ## ⚠️ `false` 有两种成因，而它们**从这两格就分得出来**，不用第三格
+     *
+     * | `installable` | `sourceType` | 说的是                                    |
+     * | ------------- | ------------ | ----------------------------------------- |
+     * | `false`       | 非 `null`    | 它是远程 source，而**远程那一档关着**     |
+     * | `false`       | `null`       | 这一条的 `source` 我们**看不懂**（写错了）|
+     *
+     * 所以这份回执上**刻意没有一格 `allowRemote`**：那个开关是 runtime 那一层的
+     * 状态（`HostMarketplaces.allowRemote`），而 `installable` 已经是它作用在**这
+     * 一条**上的结论了。再发一格全局开关，界面就有两个地方能推出「这条装不装得上」——
+     * 而两处分叉的表现是一条画成可点、点了却被拒的行。判据同 `server/src/plugin.ts`
+     * 文件头那句「这一层一条策略判断都没有」。
+     */
+    installable: boolean;
+    /** 已经装过同名的了。界面据此把「安装」换成「已装上」 */
+    installed: boolean;
+}
+/**
+ * `GET /api/plugins` —— 那一页的首屏，**一次取齐**。
+ *
+ * 判据同 `GET /api/sessions/:id/capabilities` 一个端点回三栏：这一页上的两块
+ * （装着的 / 市场里有什么）**永远一起看** —— 「市场里那一条我是不是已经装了」
+ * 这个问题要两块都在手上才答得出（{@link WirePluginHit.installed} 就是那个答案）。
+ *
+ * ⚠️ **没有 `?q=`，搜索在前端做**：市场目录是加进来那一刻的本地快照
+ * （`epoch plugin search` 要能在飞机上跑），全量本来就已经在手上了 ——
+ * 再发一发只是把同一份东西又要一遍。口径同能力页那三栏的搜索框。
+ */
+interface WirePluginsResponse {
+    /** 盘上那份记录（`plugins.json`），**不是这一程加载出来的那张表** */
+    installed: readonly WirePluginEntry[];
+    /** 已加的市场里全部条目。空关键词的答案是「全部」而不是「零条」 */
+    hits: readonly WirePluginHit[];
+    /**
+     * **这一程动过插件、而那些改动还没生效。** 判据全文见文件头第三节。
+     *
+     * ⚠️ 它答的是「这一程」，不是「盘上有没有变化」：另一个进程装的插件不会让它
+     * 变 true —— 这个进程确实没变过。
+     */
+    pendingRestart: boolean;
+}
+declare const WIRE_PLUGINS_FIELDS: WireFields<WirePluginsResponse>;
+/**
+ * `POST /api/plugins/install/preview` 的请求体。
+ *
+ * ⚠️ **只有一个 `ref`，而这就是这条路的安全性质本体**（文件头第一节）：
+ * 这里**没有** `source` / `path` / `content` 那三格，所以「往任意路径装一个插件」
+ * 在这个形状下说不出口。**别在这儿加一个 `source` 重载。**
+ */
+interface WirePluginPreviewRequest {
+    /** `<市场>/<插件>`。认不出这个形状就是 `unknown-ref`，而一条任意路径永远认不出来 */
+    ref: string;
+}
+declare const WIRE_PLUGIN_PREVIEW_FIELDS: WireFields<WirePluginPreviewRequest>;
+/**
+ * `POST /api/plugins/install` 的请求体。
+ *
+ * ⚠️ `token` **必传**，而且是服务端对着**这一次真正要装的那份预览**重算着对的
+ * （判据在 `runtime/src/plugin-install.ts` 文件头）。缺了它这条端点就退化成
+ * 「给我一个市场引用我就装」——「用户确认过的那一份」和「真装上的那一份」
+ * 之间那条缝就回来了。
+ */
+interface WirePluginInstallRequest extends WirePluginPreviewRequest {
+    token: string;
+}
+declare const WIRE_PLUGIN_INSTALL_FIELDS: WireFields<WirePluginInstallRequest>;
+/**
+ * `POST /api/plugins/update/preview` 的请求体 —— 按**装着的那个名字**，不是 ref。
+ *
+ * 来源取自那条安装记录（`epoch plugin update` 也是这么干的）：一个插件装完之后
+ * 「它从哪儿来」是盘上的事实，让浏览器再报一遍就是给同一件事第二个答案。
+ */
+interface WirePluginNameRequest {
+    name: string;
+}
+declare const WIRE_PLUGIN_NAME_FIELDS: WireFields<WirePluginNameRequest>;
+/**
+ * `POST /api/plugins/update` 的请求体。
+ *
+ * ⚠️ **更新也要过预览这一道**，不是多余的谨慎：新版本可以加 hook（会跑 shell
+ * 命令），一个当初只带三条命令的插件更新之后可能带上一条 `PreToolUse`。
+ * 判据逐字同 CLI 的 `epoch plugin update` 为什么在非交互终端下拒绝无 `--yes` 运行。
+ */
+interface WirePluginUpdateRequest extends WirePluginNameRequest {
+    token: string;
+}
+declare const WIRE_PLUGIN_UPDATE_FIELDS: WireFields<WirePluginUpdateRequest>;
+/**
+ * 一次拒绝的档位。**每一档对一个不同的下一步** —— 照抄 runtime 的
+ * `PluginRefuseReason`，一个字不改也不合并任何两档（合并的表现是界面拿同一句话
+ * 去答两个问题）。
+ *
+ * | 档                | 说的是                                           | 用户的下一步     |
+ * | ----------------- | ------------------------------------------------ | ---------------- |
+ * | `unknown-ref`     | 不是 `<市场>/<插件>`，或那个市场 / 插件不存在    | 换一条           |
+ * | `remote-disabled` | 它是远程 source，而远程那一档关着               | 去开那个开关     |
+ * | `conflict`        | 已经装过同名的                                   | 先卸载           |
+ * | `stale-token`     | 你确认的和现在要装的对不上，**一个字节都没写**   | 重看一次预览     |
+ * | `not-installed`   | update / uninstall 收到一个没装过的名字          | 先装上           |
+ * | `nothing-to-do`   | **不是出错**：软链装的插件一直是最新的           | 什么都不用做     |
+ * | `failed`          | 其余（拉不到 / 清单坏了 / 写记录时被抢先）       | 看 `detail`      |
+ */
+type WirePluginRefuseReason = 'unknown-ref' | 'remote-disabled' | 'conflict' | 'stale-token' | 'not-installed' | 'nothing-to-do' | 'failed';
+/** 一次 hook 盘点：这个事件上有几条 */
+interface WirePluginHookTally {
+    type: string;
+    count: number;
+}
+/**
+ * 「将安装什么」那一屏的内容。
+ *
+ * ## ⚠️ 这一屏本身就是闸门的一半，不是一个装饰性的确认
+ *
+ * 判据照 `epoch plugin install` 的**安装前预览**：装之前那次确认才是这条路上
+ * 给**人**的那道闸门。只给一个「安装」按钮不给这一屏，等于把它拿掉 ——
+ * 而这一包东西里有两样会**起子进程**（{@link hooks} / {@link mcpServers}），
+ * 用户在按下去之前有权知道。
+ *
+ * 六类扩展物**全部列名字**（不只是条数），而且列的是**已加前缀**的那个名字 ——
+ * 那才是用户之后真正会敲 / 会在权限规则里看见的那一个（判据在 core 的
+ * `PluginInventory.mcpServers` 上）。
+ */
+interface WirePluginPreview {
+    name: string;
+    version: string;
+    /** 清单里那句。没写就是空串 */
+    description: string;
+    /** 解析之后的来源原文（`github:acme/x` / 一条绝对路径） */
+    source: string;
+    sourceType: WirePluginSourceType;
+    /** 压缩包源核对过的校验和；没有就是 `null` */
+    checksum: string | null;
+    author: string | null;
+    homepage: string | null;
+    /** 已加前缀的命令名（`my-toolkit:review`） */
+    commands: readonly string[];
+    roles: readonly string[];
+    skills: readonly string[];
+    /** ⚠️ 非空 = 这一包会跑 shell 命令。界面上那一行要醒目 */
+    hooks: readonly WirePluginHookTally[];
+    denyRules: number;
+    /** ⚠️ 已加前缀（`my-toolkit__github`）。非空 = 这一包会起子进程 */
+    mcpServers: readonly string[];
+    /** `settings.json` 里被忽略的桶（`allow` / `ask`）。它们**不生效**，要说出来 */
+    ignoredBuckets: readonly string[];
+    /** 有没有 `tools/` 目录。第一版不跑 JS 工具，探出来只为了说一句话 */
+    hasJsTools: boolean;
+    /** 已经装过同名的了（这次会被拒）。没撞就是 `null` */
+    conflict: {
+        name: string;
+        version: string;
+    } | null;
+}
+/**
+ * `POST /api/plugins/install/preview` / `.../update/preview` 的回执。
+ *
+ * ⚠️ **失败也是 200**（除了那道 403 和请求体本身坏掉）。判据同
+ * `WireSkillImportPreviewResponse`：`remote-disabled` / `unknown-ref` 那几档
+ * 带着一句**点得出下一步**的 `detail`，而 `{error:{code,message}}` 那个形状里
+ * 那句话会被读成「这次请求发坏了」—— 它其实是一个如实的答案。
+ */
+interface WirePluginPreviewResponse {
+    ok: boolean;
+    /** 成了才有 */
+    preview: WirePluginPreview | null;
+    /** 成了才有。原样发回 {@link WirePluginInstallRequest.token} */
+    token: string | null;
+    /** 没成才有 */
+    reason: WirePluginRefuseReason | null;
+    /** 没成才有。**服务端渲染好的一句人话**，界面原样上屏 */
+    detail: string | null;
+}
+declare const WIRE_PLUGIN_PREVIEW_RESPONSE_FIELDS: WireFields<WirePluginPreviewResponse>;
+/**
+ * `POST /api/plugins/install` / `.../update` / `.../uninstall` 的回执。
+ *
+ * ⚠️ **`ok: true` 的意思是「盘上变了」，不是「能用了」** —— 后者要看
+ * {@link pendingRestart}。这两格分开是这条路的正题，判据见文件头第三节。
+ *
+ * ⚠️ 失败也是 200，判据同 {@link WirePluginPreviewResponse}。
+ * `stale-token` 那一档尤其要说清：**一个字节都没写**，重看一次预览就行。
+ */
+interface WirePluginActionResponse {
+    ok: boolean;
+    /**
+     * 成了那一档：装 / 更新完之后**盘上那一条重新读出来**的样子。卸载那条路上是
+     * `null`（它已经不在表里了 —— 回一条记录是句假话）。
+     *
+     * ⚠️ **是重新读出来的，不是把安装结局回显一遍**，而这一条不是洁癖：
+     * {@link WirePluginEntry.active} 那一格只有 runtime 那一层算得出（它手里才有
+     * 「这一程加载了谁」那张表），而**那一格正是这条路的正题**。
+     * 尤其别在服务端硬写一个 `active: false` —— 更新一个**本来就在生效**的插件时
+     * 它是 `true`（生效着的是旧版本），而那时那句话就成了假的。
+     */
+    entry: WirePluginEntry | null;
+    /**
+     * **这一发之后**「动过还没生效」是不是立起来了。
+     *
+     * ⚠️ **必发，而且成败两支都发**：界面靠它在**这一屏上**立刻说出那句话，
+     * 而不是等下一次 `GET /api/plugins`。一个装完之后要用户自己刷新才看得见
+     * 中间态的界面，和不说没有区别。
+     */
+    pendingRestart: boolean;
+    /**
+     * 服务端那句人话 —— 没成时是**拒绝的原因**（七档各一句，在 runtime / core 那侧
+     * 渲染），卸载成功时是 core 那句回执。
+     *
+     * ⚠️ **装 / 更新成功那两档是 `null`，而那是刻意的**：那两档屏幕上要说的话
+     * （「装上了什么、带来了什么、还没生效」）全都在 {@link entry} 和
+     * {@link pendingRestart} 这两格数据里，而它是一句**界面文案** ——
+     * 让服务端拼一句中文发上来，就绕过了浏览器那份 catalog（同 `wire-settings`
+     * 那条「服务端的中文一律不上网线」）。
+     */
+    detail: string | null;
+    /** 没成才有 */
+    reason: WirePluginRefuseReason | null;
+}
+declare const WIRE_PLUGIN_ACTION_FIELDS: WireFields<WirePluginActionResponse>;
+
 /**
  * 一条诊断。**原样来自 `parseMcpConfig` 的 `issues`**，服务端不改写也不筛。
  *
@@ -6673,6 +8671,134 @@ interface WireMcpApplyResponse {
 }
 declare const WIRE_MCP_APPLY_RESPONSE_FIELDS: WireFields<WireMcpApplyResponse>;
 
+/**
+ * 这个进程记下了哪些审批决定，以及**逐条撤销** ——
+ * `POST /api/sessions/:id/approval-cache`（2026-08-27）。
+ *
+ * ## 为什么有这一格
+ *
+ * 审批弹窗上点错一下，那个工具在这个进程里就死了：`allow-always` 落
+ * `~/.epoch/approvals.json`（用户至少删得掉那个文件），而 `deny` 只在内存里、
+ * `ttlMs: 0` 永不过期 —— 在这一格之前，**除了重启进程，一次点错的「拒绝」
+ * 收不回来**，而屏幕上只会一直印「操作被拦截 [权限]: 已缓存拒绝」。
+ * 判据全文在 core 的 [approval-cache.ts](../../core/src/permission/approval-cache.ts)
+ * 的 `revoke()` 上，那张 📮 的原文在 `permission/manager.ts` 的
+ * `checkRulesAndCache` JSDoc 里。
+ *
+ * ## ⚠️ 读那一半**不在这条路上**，它搭在 `GET .../security` 里
+ *
+ * `WirePermissionStatus.cached`（[wire-security.ts](./wire-security.ts) 第二节）
+ * 就是这张表，那个文件从这里 import {@link WireCachedApproval}。
+ * 搭过去而不是在这儿开一条
+ * `GET`，两条判据：
+ *
+ * 1. 安全中心那一屏的纪律是**一次取齐**（`wire-security.ts` 的文件头）。
+ *    这张表和它上面那张规则表要在同一屏、同一眼里读 —— 分两发拉的话，
+ *    屏幕上会同时挂着 T1 时刻的规则和 T2 时刻的缓存；
+ * 2. 审批缓存和 `rules` / `shadows` / `audit` 一样是**进程级**的事实
+ *    （core 的 `permission/shared.ts`），它本来就该和那三样躺在同一个块里。
+ *
+ * 所以这个文件里只有**写**那一半，以及被两边共用的那一行的形状。
+ *
+ * ## ⚠️ 名字不许简称成 `approvals`，那个词已经被占了
+ *
+ * `GET /api/sessions/:id/approvals` 是**挂起的审批请求**（重连后补拉那一条），
+ * `POST /api/approvals/:requestId` 是回答其中一条。那是「现在有人在问你」，
+ * 这一条是「你以前答过什么」—— 两件事共用一个词的话，
+ * `/api/sessions/:id/approvals` 上会同时挂着一个队列和一张历史表。
+ * 所以这一路逐字叫 `approval-cache`，和引擎侧那个类同名。
+ */
+/**
+ * 缓存里存得下的决定。**没有 `allow-once`** —— 那一档刻意不入缓存
+ * （进了就变成「永久允许」了，判据在 core 的 `ApprovalCache.record()` 上），
+ * 所以它在这张表上永远不会出现，写进联合等于给界面留一个画不出来的分支。
+ *
+ * 三档在界面上是三句不同的话，不能合成「允许 / 拒绝」两档：
+ *
+ * | 值              | 用户当时点的     | 撤销之后会怎样                        |
+ * | --------------- | ---------------- | ------------------------------------- |
+ * | `deny`          | 拒绝             | 同一个操作**重新弹窗**，不是静默放行  |
+ * | `allow-session` | 允许（本次会话） | 同上；它本来也会随进程消失            |
+ * | `allow-always`  | 总是允许         | 同上，**而且盘上那份也删掉**          |
+ */
+type WireCachedDecision = 'deny' | 'allow-session' | 'allow-always';
+/**
+ * 面板上的一行 —— 「这个进程记下了什么」。
+ *
+ * ⚠️ **这不是审计流水的另一种写法。** 流水（`WireAuditRow`）记的是
+ * 「判过什么」，一次判定一行、只增不减；这张表记的是「还记着什么」，
+ * 一条决定一行、撤一条少一行。同一次「用户点了拒绝」在两处各留一行，
+ * 而它们的下一步完全不同：流水那行是历史，这一行是**现在还在生效的东西**。
+ */
+interface WireCachedApproval {
+    /**
+     * 撤销时回发的那个 id。**引擎侧那条记录自己的 id**，不是下标 ——
+     * 下标会在别的标签页撤掉一条之后指向另一行，而那时用户按下的「撤销」
+     * 会撤掉一个他没看着的决定。
+     */
+    id: string;
+    /** 记在哪个工具名下（`terminal` / `file_write` / …；工具名缺失时是操作类型） */
+    toolName: string;
+    /**
+     * 归一化之后的目标。**全路径 / 全命令，不脱敏** —— 判据逐字同
+     * `WireAuditRow.target`：洗过之后用户没法判断这条决定该不该撤，
+     * 而那正是他打开这一节的原因。
+     */
+    target: string;
+    /**
+     * `exact` = 只对这一个目标；`prefix` = 对这个目录及其子树。
+     *
+     * **必须印出来**：同一个 `target` 在两档下管的范围差着一整棵目录树，
+     * 而用户判断「这条该不该撤」靠的正是这个。
+     */
+    scope: 'exact' | 'prefix';
+    decision: WireCachedDecision;
+    /** `Date.now()`，记下这条决定的时刻。时区归浏览器，时刻归 wire */
+    at: number;
+}
+declare const WIRE_CACHED_APPROVAL_FIELDS: WireFields<WireCachedApproval>;
+/**
+ * `POST /api/sessions/:id/approval-cache` 的请求体。
+ *
+ * **一次一条，按 id**，不收「把这个工具的都撤了」那种批量：批量要回答
+ * 「第三条失败了前两条呢」（判据同 `WireSettingsWriteRequest`），
+ * 而这条路上根本不需要 —— 面板上每一行自己带一个按钮。
+ *
+ * ⚠️ **没有「全清」那一档，那是刻意的。** 引擎侧 `ApprovalCache.clear()` 一直
+ * 都在，但它会把用户攒了一整程的「总是允许」一起清掉 —— 于是「收回一个误点」
+ * 的代价变成「后面每一次都重新问一遍」。真要那一档的时候它是**另一条路**
+ * （另一个动词、另一次确认），不是这个请求体上多一个布尔。
+ */
+interface WireApprovalCacheRevokeRequest {
+    id: string;
+}
+declare const WIRE_APPROVAL_CACHE_REVOKE_REQUEST_FIELDS: WireFields<WireApprovalCacheRevokeRequest>;
+/**
+ * `POST /api/sessions/:id/approval-cache` 的响应。
+ *
+ * ## 撤一个不存在的 id 是 **200 + `revoked: false`**，不是 404
+ *
+ * 判据同 `WirePermissionSetResponse` 的「本来就是那一档不算错误」：挡的是
+ * **一张开了很久的标签页**，它手里那份列表是另一个标签页撤掉那条之前的。
+ * 用户要的结果（那条决定不再生效）**已经成立**，回一条错误只会让他去重试一件
+ * 已经如愿的事。真正的错在别处 —— 权限层整个没起来时是 503，那一档下这一节
+ * 压根不该画出来。
+ *
+ * ## 回**撤完之后的整张表**，界面直接采信，不自己推算
+ *
+ * 判据同 `WirePermissionSetResponse.state`。在浏览器里做一次
+ * `list.filter(r => r.id !== id)` 看起来一样，但它答不了「刚才那一下顺带清掉了
+ * 两条过期的 `allow-session`」（`listApprovals()` 每次都先 `prune()`）——
+ * 于是屏幕上会留着两行早就不生效的决定，而用户会去撤它们。
+ */
+interface WireApprovalCacheRevokeResponse {
+    /** 这一发真的撤掉了一条吗。`false` = 那个 id 不在表里（见上） */
+    revoked: boolean;
+    /** 撤完之后**这个进程**还记着哪些。空数组是常态 */
+    cached: readonly WireCachedApproval[];
+}
+declare const WIRE_APPROVAL_CACHE_REVOKE_RESPONSE_FIELDS: WireFields<WireApprovalCacheRevokeResponse>;
+
 /**
  * 为什么是这个隔离级别。**结构化的原因码**，替掉那句中文 `detail`。
  *
@@ -6694,6 +8820,10 @@ type WireSandboxReason = 'os-isolated' | 'backend-unavailable' | 'backend-missin
  * ⚠️ 是实测值不是配置值：`describeIsolation()` 每次都去探一遍后端。所以界面上
  * 探测不到时要**如实说探测不到**，不写「已启用」—— 那是这一屏最贵的一句假话
  * （设计稿在沙箱那一节把它单独圈出来了）。
+ *
+ * ⚠️ **`terminalEnabled` 那一格是这上面唯一的配置值**（2026-08-21 补的，方案 46
+ * §11.3 第四条的后半格），理由写在那格的 JSDoc 上。同 {@link WirePermissionStatus}
+ * 里 `level`（实测）+ `configured`（配置）的摆法：一个块里两个轴，各占一行。
  */
 interface WireSandboxStatus {
     /** `os` = 真被 OS 关起来了；`process` = 只有进程隔离（能读写整盘、能联网） */
@@ -6736,6 +8866,33 @@ interface WireSandboxStatus {
      * 都在里面，而**这是最坏的一种误读，因为它让人放心地去把 `terminal` 放宽**。
      */
     excludes: readonly string[];
+    /**
+     * **配置值，不是实测值** —— 这一块里唯一的例外（见文件头）。
+     *
+     * 它答的是「这次 `terminal` 的命令包不包」：`config.yaml` 的
+     * `sandbox.terminal`，默认开（方案 46 §11.3 第一条）。和上面那几格实测的
+     * 隔离能力是**两个正交的轴** —— 关掉它之后 `level` / `backend` / `reason`
+     * 一个字都不变（这台机器的能力没变），`covers` 也照旧列着 `terminal`：
+     * 那张清单答的是「谁的路接在隔离层上」（一份静态常量），
+     * **不是「这次真包了没有」**。两句话合在一格里的话，一个关掉开关的 macOS
+     * 用户和一个 Windows 用户看到的是同一句话 —— 而前者把开关打开就有沙箱，
+     * 后者打开也没有。
+     *
+     * 所以界面上这一格**单独占一行**，而且摆在 `covers` 前面（判据逐字同
+     * `epoch doctor` 的「开关」那一行，方案 46 §11.3 第四条 —— 两个出口是
+     * 同一句话）。
+     *
+     * ⚠️ 服务端总是发**已经折算好的布尔**（`!== false`），不是 raw 配置值：
+     * 缺省朝「开」是这条线上每一跳的规矩（判据在 `EpochConfig.sandbox`，一句话：
+     * 漏填的表现是开关失灵，不是沙箱静默消失）。
+     *
+     * 标成可选不是「可以省」：它给的是**老版本的假件**（web 的 dev 假服务端、
+     * 嵌入宿主的测试夹具）一个不用同步改的机会 —— 读它的一侧缺了按「开」读
+     * （`!== false`），方向和这一跳的缺省一致，同 infra `SandboxPolicy.enabled?`
+     * 那一格的理由。真正的生产者在 server 的 `toWireSandbox`，它的第二参是
+     * **必填的**，漏传当场编译不过 —— 编译期门禁在生产者那一侧，不在消费者上。
+     */
+    terminalEnabled?: boolean;
 }
 declare const WIRE_SANDBOX_STATUS_FIELDS: WireFields<WireSandboxStatus>;
 /**
@@ -6851,6 +9008,28 @@ interface WirePermissionStatus {
     rules: readonly WirePermissionRuleRow[];
     shadows: readonly WirePermissionShadow[];
     managed: WireManagedLock;
+    /**
+     * 这个进程记下了哪些**弹窗答案**（审批缓存，2026-08-27）。空数组是常态。
+     *
+     * ⚠️ **和上面那张 `rules` 是两张表，界面上必须分得开。** 那一张是配置文件里
+     * 写下来的策略，这一张是用户在弹窗上点出来的记忆；判定时**规则的 deny 排在
+     * 缓存前面**（core 的 `checkRulesAndCache`）。合成一张表、或者只给缓存那张
+     * 配一个「撤销」按钮而不说清它撤的是哪一层，后果很具体：用户撤掉一条 deny
+     * 之后发现还是被拦（拦他的是规则那张表），而屏幕上刚刚说「已撤销」——
+     * 比没有那个按钮更坏。
+     *
+     * ⚠️ **它和 {@link WireAuditLog} 也不是一回事**：流水记「判过什么」（只增
+     * 不减的历史），这张表记「还记着什么」（撤一条少一行）。
+     *
+     * 跟着 `rules` / `shadows` / `managed` / `audit` 一档，**是进程级的**、
+     * 不跟着会话分家（判据在 core 的 `permission/shared.ts`）—— 界面上那句话
+     * 得是「这个进程记下的」。
+     *
+     * 写那一半在 [wire-approval-cache.ts](./wire-approval-cache.ts)。搭在这一份
+     * 载荷里而不是另开一条 `GET`，判据在那个文件的文件头（一句话：这一屏的纪律是
+     * **一次取齐**，分两发拉的话屏幕上会同时挂着两个时刻的东西）。
+     */
+    cached: readonly WireCachedApproval[];
 }
 declare const WIRE_PERMISSION_STATUS_FIELDS: WireFields<WirePermissionStatus>;
 /**
@@ -8342,55 +10521,538 @@ interface WireScheduleRecordingResponse {
     truncated: boolean;
 }
 declare const WIRE_SCHEDULE_RECORDING_FIELDS: WireFields<WireScheduleRecordingResponse>;
+/**
+ * `GET /api/schedules/pending`。
+ *
+ * 三个界面读的是这一发：dock 上那一条「自动化待确认」、侧栏「自动化」入口上
+ * 那个点、TUI 启动时那一行（TUI 那条不走 HTTP，它在同一个进程里直接调
+ * `collectPendingApprovals`）。**投影本身在
+ * [schedule-pending.ts](./schedule-pending.js)**，那儿写着两道筛和「同一条任务
+ * 只报最近那一次」的判据，这里只是它的信封。
+ *
+ * ## ⚠️ 为什么不搭 `GET /api/schedules` 那一发的车
+ *
+ * 那一发够用：`schedules` 里有 `allowRules`、`recentRuns` 里有 `pendingApprovals`,
+ * 浏览器自己就能算。**但读它的人不是那一屏** —— 是**侧栏和 dock**，也就是
+ * 每一次首屏都要问一次的东西。那一发回的是「全部任务 + 最近 100 条运行 + 一次
+ * 平台探测 + 表单缺省」，为一个角标拉那么一份，代价会落在每一次刷新上。
+ *
+ * 反过来也不合并进 `GET /api/config`（首屏那一发）：那一份是**进程级的常量**
+ * （品牌 / 口径 / 诊断），一次都不按时间变；而这个数会因为「另一个进程里的
+ * 执行器刚跑了一次」而变。混进去之后，「刷新才更新」会从一句如实的话变成
+ * 一个看不出来的坑。
+ *
+ * ## ⚠️ 它**不轮询**，而这一条要如实说给用户听
+ *
+ * 一次定时运行发生在**另一个进程**里（OS 调度器起的执行器），服务进程压根不知道
+ * 它跑过 —— 所以这个数只在「取数那一刻」是真的，SSE 那条路在这件事上没有素材
+ * （不是漏接：没有任何一帧能报它）。界面因此在两个时刻拉它：首屏，以及每次自己
+ * 动过手之后（按了「加进授权清单」、跑了一次）。
+ */
+interface WireSchedulePendingResponse {
+    /** 最久的在前。一条都没有时空数组 —— 那时侧栏那个点不画 */
+    items: readonly SchedulePendingItem[];
+}
+declare const WIRE_SCHEDULE_PENDING_FIELDS: WireFields<WireSchedulePendingResponse>;
 
 /**
- * 上下文预算的构成（方案 25 §2.5 的 `/context`）。
+ * 目标那一格的网线形状（[方案 52](../../../docs/verify/VERIFY_RECORD-52-goal.md) PR-4 的
+ * 「上网线」那一半）：
  *
- * ## 为什么值得一个契约
+ * ```
+ * GET    /api/sessions/:id/goal   这段会话的目标 + 表单那几格上限与缺省
+ * POST   /api/sessions/:id/goal   建一个（**人专用**）
+ * PATCH  /api/sessions/:id/goal   五个动作之一：改正文 / 改预算 / 按停 / 放行 / 报完成
+ * DELETE /api/sessions/:id/goal   清掉
+ * GET    /api/goals/blocked       哪几段会话此刻卡着（dock 第四档，**进程级**）
+ * ```
  *
- * 我们有压缩器，会在接近上限时自动压。但用户看不见**预算怎么花的** ——
- * 压缩发生时他只知道「压了」，不知道「为什么这么快就压了」。
- * 而答案常常很具体：一个 MCP server 的工具定义吃掉了四分之一窗口。
+ * ## 这是一份**结构镜像**，不是把 core 的 `Goal` 导出去
  *
- * 形状住在 protocol 是因为 TUI 和 web 都要画它，而两边都不许 import core。
+ * 口径逐字照 [wire-schedule.ts](./wire-schedule.js)：那个文件只装两样东西 ——
+ * 包一层的响应壳，以及**界面要而库里没有的那几格**。这一份多一样活，因为
+ * 定时任务那一份的真身（`ScheduleDefinition`）2026-08-17 就已经住在 protocol 里了，
+ * 而 `Goal` 住在 core（`core/src/goal/types.ts`），而 **`packages/web` 只依赖
+ * protocol + view，它够不着 core**（`check-layers.mjs` 是硬闸门）。
+ *
+ * 于是照 `WireScheduleIssueCode` 那处的老办法：**抄一份 + 一条钉住「逐项相等」的
+ * 用例**（`core/__tests__/goal-wire.test.ts`）。抄的代价是两份会走散，而那条用例
+ * 就是不让它走散的那道闸 —— 它两个方向都断（互相可赋值 ⟺ 两个联合逐项相等），
+ * 所以「一边多一个态」和「一边少一个态」都会当场红在 `pnpm typecheck` 上。
+ *
+ * ## 镜像和真身刻意**不同**的三处，每一处都是收窄
+ *
+ * | 真身（core 的 `Goal`） | 这一份         | 为什么                                        |
+ * | ---------------------- | -------------- | --------------------------------------------- |
+ * | `id`                   | **没有**       | 那是 `goals` 表的主键，浏览器拿它什么都做不了 |
+ * | `sessionId`            | **没有**       | 会话级那条路上它在 URL 里；跨会话那条另有一格 |
+ * | 四态都能写             | **写只有三态** | `blocked` 不在写那条路上，见下面第四节        |
+ *
+ * 前两条的判据同 `CheckpointSummaryView` 那处「没有 `cursor`」：镜像上没有这个
+ * 字段是**编译期生效**的 —— 投影里写不出 `goal.id`，写了当场不过。
+ *
+ * ## ⚠️ 网线上发的是**码**，不是句子
+ *
+ * `phase` / `block.code` / `WireGoalRefusal` 三样全是 kebab-case 的码。两条判据，
+ * 缺一条都不够（逐字同 `wire-schedule.ts`）：
+ *
+ * 1. 服务端的中文一律不上网线 —— 浏览器切成英文之后服务端渲染好的字符串换不了；
+ * 2. **同一条拒绝的措辞在 CLI 和这一格上本来就该不一样**：CLI 说
+ *    「先 `/goal clear`」，而这一格上没有 `/goal clear` 这个东西。
+ *
+ * ⚠️ 唯一的例外是 `block.message`，而它**不是我们渲染的文案**：它是模型（或策略层）
+ * 写的一句自然语言，会落库、要被 grep，所以它跟着写它的那一刻走、不跟界面语言走
+ * （判据在 `core/src/goal/wording.ts` 和 52 §4.3）。原样过网线，不翻。
  */
-/** 预算里的一段 */
-interface ContextSegment {
-    /** 展示名，例如「工具定义」 */
-    label: string;
-    /** 估算的 token 数 */
-    tokens: number;
-    /** 一句补充说明，例如「14 个内置 + 6 个 MCP」。没有就不显示 */
-    detail?: string;
+/**
+ * 四态。**真源在 core 的 `GoalPhase`，这是网线上那一份**，见文件头。
+ *
+ * | 态         | 谁能转进来     | 语义                               |
+ * | ---------- | -------------- | ---------------------------------- |
+ * | `active`   | 人（建、放行） | 在跑，预算还有                     |
+ * | `paused`   | 人             | 人主动按停，预算不动               |
+ * | `blocked`  | 模型 / 策略层  | 撞上了具体的东西，**必须说是什么** |
+ * | `complete` | 模型（带依据） | 完成判据满足了                     |
+ *
+ * ⚠️ **预算耗尽转 `blocked` 而不是 `complete`**（GOALS.md §四）：转 `complete`
+ * 正是今天 `maxTurns` 的病 —— 撞上了之后分不出「干完了」还是「跑飞了」。
+ * 界面上这四档因此必须是**四种画法**，不许把 `blocked` 和 `complete` 合成
+ * 一句「结束了」。
+ */
+type WireGoalPhase = 'active' | 'paused' | 'blocked' | 'complete';
+/**
+ * 全集。**顺序也钉着** —— 那条「逐项相等」的用例比的是数组，不是集合，
+ * 判据逐字同 `WIRE_SCHEDULE_ISSUE_CODES`：顺序对不上通常意味着有人在一边插了
+ * 一条而另一边追加在末尾，那时两份的内容还相等，但下一次插入就会真的分叉。
+ */
+declare const WIRE_GOAL_PHASES: readonly WireGoalPhase[];
+/** 从网线上读回来的字符串是不是一个合法的 phase */
+declare function isWireGoalPhase(value: string): value is WireGoalPhase;
+/**
+ * 卡住的理由。**两个字段都必有，而且各有不可替代的用途**（GOALS.md §三）：
+ *
+ * - `code` 让**程序**能路由（`needs-approval` 走审批、`needs-credential` 走凭据）
+ * - `message` 让**人**能看懂（「差一条 `terminal(pnpm publish)` 的授权」）
+ *
+ * 只有 `message` 程序没法分类；只有 `code` 人看不懂。
+ *
+ * ⚠️ **`code` 的取值是开放的** kebab-case（策略层会长出新分类），所以这里是
+ * `string` 而不是一个联合。界面按已知的那几个给图标 / 措辞，**认不出来的那些
+ * 必须照旧画得出来**（原样印那个码 + `message`）—— 收成闭集的代价是每加一种
+ * 阻塞都要改一次协议，而漏改的表现是那一档在屏幕上静默消失。
+ * 已知的那张表在 [docs/GOALS.md](../../../docs/GOALS.md)。
+ */
+interface WireGoalBlock {
+    code: string;
+    message: string;
 }
+declare const WIRE_GOAL_BLOCK_FIELDS: WireFields<WireGoalBlock>;
+/**
+ * 网线上那一份目标。**`id` 和 `sessionId` 都没有**，理由见文件头那张表。
+ *
+ * `block` / `completeEvidence` 两格的**在与不在本身就是信息**，别在服务端补一个
+ * 空串：`phase === 'blocked'` 时 `block` 必有、其余态必无（core 的不变式），
+ * 界面据此不用为「blocked 但没有理由」这种说不出口的状态留一条分支。
+ */
+interface WireGoal {
+    /** 完成判据本身。**只有人能改** */
+    objective: string;
+    phase: WireGoalPhase;
+    /** `phase === 'blocked'` 时必有，其余态必无 */
+    block?: WireGoalBlock;
+    /** 预算：最多几个**被接纳的轮次**（GOALS.md §四，不是模型请求次数） */
+    maxRounds: number;
+    roundsUsed: number;
+    /** `phase === 'complete'` 时必有：凭什么算完成 */
+    completeEvidence?: string;
+    /** 毫秒时间戳 */
+    createdAt: number;
+    updatedAt: number;
+}
+declare const WIRE_GOAL_FIELDS: WireFields<WireGoal>;
 /**
- * 一次上下文预算快照。
+ * 建 / 改目标那个表单该按什么尺子来。
  *
- * ⚠️ **不变式：`segments` 之和 === `used`；`limit > 0` 时还有 `used + remaining === limit`。**
- * 这不是「顺便成立」的性质，是这个结构存在的意义 —— 一个分段账目如果对不上，
- * 它给用户的每一个结论都是错的。生产它的那一侧必须**由 segments 推出 used**，
- * 而不是两边各算一遍。有用例钉着（`context-breakdown.test.ts`）。
+ * 值全部来自 core 的 `DEFAULT_GOAL_MAX_ROUNDS` / `MAX_GOAL_MAX_ROUNDS` /
+ * `MAX_OBJECTIVE_CHARS` / `MAX_REASON_CHARS`，服务端原样转发。判据逐字同
+ * `WireScheduleDefaults`：**不让表单自己写死一份** —— 那几个数一改，
+ * 界面上那个 `maxlength` 和预填的 10 就是一个和引擎不一样的值，而它编译得过、
+ * 跑得通、只在用户正好写到第 2001 个字的那一刻表现成「保存了但被截断了」。
  *
- * 第二条为什么要挂 `limit > 0`：查不到模型元数据时 `limit` 和 `remaining` **都是 0**，
- * 而 `used` 照样是真数 —— 此时等式必然不成立，这是刻意的（见 `remaining` 的说明）。
- * 消费侧要么先判 `limit > 0`，要么别用 `limit - used` 反推剩余。
+ * ⚠️ 它们**不是校验**，是**尺子**：真正判「这个预算合不合法」的是
+ * `GoalService`（回一个 `bad-budget`），界面这一侧只用它们提前把话说出来
+ * （`max=999` 那个 `input`、那句「上限 2000 字」）。两处判据分叉时红的是
+ * 服务端那一份，而它才是写库的那一道 —— 同 `WireScheduleIssueCode` 的分工。
  */
-interface ContextBreakdown {
-    /** 模型的上下文窗口。查不到模型元数据时是 0 */
-    limit: number;
-    /** 已用 = 各段之和 */
-    used: number;
-    /** 剩余 = limit - used。limit 为 0 时也是 0（「不知道」不是「满了」） */
-    remaining: number;
-    segments: ContextSegment[];
+interface WireGoalLimits {
+    /** 建的时候不给预算就是这个数（今天是 10） */
+    defaultMaxRounds: number;
+    /** 预算的硬上限（今天是 999）。下限恒为 1，不必发 */
+    maxRounds: number;
+    /** 目标正文的字数上限。它是**完成判据**不是计划正文 */
+    maxObjectiveChars: number;
+    /** `complete` 的依据 / `blocked` 的 message 各自的字数上限 */
+    maxReasonChars: number;
+}
+declare const WIRE_GOAL_LIMITS_FIELDS: WireFields<WireGoalLimits>;
+/**
+ * `GET /api/sessions/:id/goal`。
+ *
+ * **一发拿齐目标和尺子**，判据同 `GET /api/schedules` 那一发把 `defaults` 捎上：
+ * 这一格上「看一眼」和「改一下」是同一屏（没有目标时它就是那个建的表单），
+ * 拆两发的话表单要么先画一个没有 `maxlength` 的输入框、要么多等一个来回。
+ *
+ * ⚠️ **`goal: null` 是「这段会话没有目标」，不是「问不出来」。** 后者压根不走
+ * 这条 200 —— 这个进程没有目标存储（会话库起不来）时整条端点回 503
+ * `no-goal-store`，判据在 `server/src/goal/handlers.ts` 的文件头。
+ * 两者混成一个 `null` 的代价很具体：界面会对着一台没有会话库的机器画出
+ * 「这个会话还没有目标，来定一条」，而按下去必然失败。
+ */
+interface WireGoalResponse {
+    goal: WireGoal | null;
+    limits: WireGoalLimits;
+}
+declare const WIRE_GOAL_RESPONSE_FIELDS: WireFields<WireGoalResponse>;
+/**
+ * `POST /api/sessions/:id/goal` —— 建一个。
+ *
+ * ⚠️ **只有人走得到这条路，而这件事不是这一层守的。** 目标是完成判据，而完成
+ * 判据是用来约束模型的 —— 让它自己写等于让它自己出考卷（GOALS.md §五）。
+ * 模型手里那个 `goal` 工具的 schema 里**根本没有建目标这个 action**，
+ * 所以「只有人能建」靠的是没有第二条路，不是在这儿加一个 `by: 'human'` 参数
+ * （那等于承认存在一条模型走得到的路，只是我们在运行期拒了它）。
+ *
+ * `maxRounds` 不给就是 {@link WireGoalLimits.defaultMaxRounds}。**这一格可选是
+ * 对的**，和 `WireScheduleCreateRequest.maxBudgetUsd` 那处「必填、没有默认值」
+ * 刻意相反：那一格的假默认会变成一笔真的钱，这一格的默认值花的是轮次 ——
+ * 而 10 轮跑完的下场是一条 `blocked(budget-exhausted)` 的记录，不是账单。
+ */
+interface WireGoalCreateRequest {
+    objective: string;
+    maxRounds?: number;
+}
+declare const WIRE_GOAL_CREATE_FIELDS: WireFields<WireGoalCreateRequest>;
+/**
+ * `PATCH /api/sessions/:id/goal` —— **一条请求恰好一个动作**。
+ *
+ * ## 为什么是判别联合，不是 `WireScheduleUpdateRequest` 那种「没给的不动」
+ *
+ * 那一份改的是**一行任务的字段**，一次 UPDATE 落盘，漏给哪一格就是不动那一格。
+ * 这一份改的是**五个动词**（`GoalService` 上五个方法），每一个各有自己的
+ * 前置条件和拒绝码。写成「字段都可选」的话：
+ *
+ * 1. `{objective, maxRounds}` 一起给要在服务端调两次，而第二次被拒时前一次
+ *    **已经写进库了** —— 一次 PATCH 半成功，而回执里说不清成了哪一半；
+ * 2. `phase` 那一格会长成一个能写四个值的口子，于是浏览器写得出
+ *    `phase: 'blocked'` —— 见下面那条 ⚠️。
+ *
+ * ## ⚠️ 这条路上**表达不出 `blocked`**，而这是本文件最要紧的一处收窄
+ *
+ * `blocked` 是模型 / 策略层的态（GOALS.md §三 那张「谁能转进来」的表）。
+ * 让浏览器报得出 `blocked` 就等于让它编一个 `code` + 一句 `message` 出来，
+ * 而那个 `code` 是**给程序路由用的键** —— dock 第四档按它决定给「加进授权清单」
+ * 还是「去那段会话」。编一个 `needs-approval` 出来的方向是**提权**。
+ *
+ * 所以四态里只有三态在这个联合里（`active` = 放行、`paused` = 按停、
+ * `complete` = 报完成），第四态**在类型上说不出口**。判据同 52 §5.1 结论 3：
+ * 「不许去反推一条规则出来：那是猜，而猜错的方向是提权。」
+ */
+type WireGoalUpdateRequest = 
+/** 改措辞。**不重置轮次、也不改状态** */
+{
+    action: 'edit';
+    objective: string;
+}
+/**
+ * 改预算。⚠️ **两个方向都会顺手改 phase**（52 §3.1 第 1 条）：调到已用轮次
+ * 之下 → 当场转 `blocked(budget-exhausted)`；给一个 `budget-exhausted` 的
+ * 目标加预算 → 直接放回 `active`。界面因此**必须拿回执里那份目标覆盖本地那份**，
+ * 不许只把输入框里那个数写回去。
+ */
+ | {
+    action: 'budget';
+    maxRounds: number;
+}
+/** 人按停。轮次不再推进，目标留着 */
+ | {
+    action: 'pause';
+}
+/** 人放行。`paused` / `blocked` 都能恢复；预算耗尽那一档要先加预算 */
+ | {
+    action: 'resume';
+}
+/** 人替它报完成。**依据必填** —— 那段话是人回来核对的唯一凭据 */
+ | {
+    action: 'complete';
+    evidence: string;
+};
+/** 五个动作的名字。界面和请求体校验共用这一份，别在两处各列一遍 */
+declare const WIRE_GOAL_ACTIONS: readonly WireGoalUpdateRequest['action'][];
+/**
+ * 一次改动被拒的原因。**真源在 core 的 `GoalRefusal`，这是网线上那一份**。
+ *
+ * 每一个码都对应用户**下一步该做的一件不同的事**，这是拆码的唯一判据
+ * （逐字照 core 那个类型上的注释）：`busy` 要先清掉现在那个，`no-goal` 要先建
+ * 一个，`empty-objective` 要重写一句。所以界面上这十条是**十句不同的话**，
+ * 合成一句「操作失败」等于把这十条判据一起扔了。
+ */
+type WireGoalRefusal = 
+/** 已经有一个还没结束的目标 */
+'busy'
+/** 这个会话现在没有目标 */
+ | 'no-goal'
+/** 目标正文是空的 */
+ | 'empty-objective'
+/** 目标正文超过 {@link WireGoalLimits.maxObjectiveChars} */
+ | 'objective-too-long'
+/** 预算不是 1..{@link WireGoalLimits.maxRounds} 之间的整数 */
+ | 'bad-budget'
+/** `blocked` 少了 `code` 或者它不是 kebab-case。**这条到不了浏览器**，见下 */
+ | 'bad-block-code'
+/** `blocked` 少了 `message`。同上 */
+ | 'empty-block-message'
+/** 报完成少了依据 */
+ | 'empty-evidence'
+/** 这个态上做不了这件事（`complete` 的目标不能按停，等等） */
+ | 'wrong-phase'
+/** SQLite 写失败。**不吞** —— goal 的全部意义是留下痕迹 */
+ | 'unavailable';
+/**
+ * 全集，顺序钉着，判据同 {@link WIRE_GOAL_PHASES}。
+ *
+ * ⚠️ 里面那两条 `bad-block-code` / `empty-block-message` **在今天的网线上到不了
+ * 浏览器**（`blocked` 压根不在 {@link WireGoalUpdateRequest} 里）。仍然照抄进来，
+ * 两个理由：这一份是 core 那个联合的镜像，**镜像少一条就不是镜像了**（那条
+ * 「逐项相等」的用例断的正是它）；而界面那张文案表按码穷举，少两条的话下一次
+ * 真有人给 `blocked` 开一条路时，屏幕上会是一个没有文案的空白拒绝。
+ */
+declare const WIRE_GOAL_REFUSALS: readonly WireGoalRefusal[];
+/**
+ * 建 / 改的回执。
+ *
+ * ## ⚠️ 被拒是 **200 + `ok: false`**，不是 4xx
+ *
+ * 判据同 `WireScheduleSaveResponse` 那条「校验不过是 200 + `issues`」：请求本身
+ * 完全合法，是**这个值 / 这个态**不接受 —— 而那句话要出现在用户刚敲字的那一格
+ * 旁边，不是一条「请求发坏了、再试一次」的横幅。真正的 4xx 只留给
+ * 「这条 URL 上的会话不存在」（404）和「请求体不是那个形状」（400）。
+ *
+ * ⚠️ **`unavailable` 也走这条 200**，而它看起来最像一个 5xx。刻意的：它是
+ * {@link WireGoalRefusal} 这个**闭集**里的一员，而界面按码穷举出一张文案表 ——
+ * 把闭集里的一个成员挪到另一个 HTTP 状态上，等于让浏览器为同一个联合写两条
+ * 处理路径，而那两条里被走到的那条永远是常见的那几个码。
+ * 真正「这个进程压根没有目标存储」那一档不走这条路：整条端点 503 `no-goal-store`。
+ *
+ * ⚠️ **`goal` 必带（可以是 `null`），不是可选。** `conformsToWire()` 查的是
+ * 「列出来的字段在不在」，写成可选就等于这一格从来没被那道闸检查过。
+ * 被拒时它是 `null`：**不回一份「当前那个目标」** —— 那样界面分不出
+ * 「这是我刚改成的」还是「这是我没改动的」，而这两者的下一步不同。
+ */
+interface WireGoalWriteResponse {
+    ok: boolean;
+    /** 写完之后那一份；`ok: false` 时 `null` */
+    goal: WireGoal | null;
+    /** `ok: false` 时必有 */
+    reason?: WireGoalRefusal;
+}
+declare const WIRE_GOAL_WRITE_FIELDS: WireFields<WireGoalWriteResponse>;
+/**
+ * `DELETE /api/sessions/:id/goal` 的回执 —— 它没有「写完之后那份目标」。
+ *
+ * `cleared: false` + `ok: true` = **本来就没有**（幂等，不是失败）。这两格分开
+ * 而不是一个布尔：界面对「清掉了」和「本来就没有」说的不是同一句话，而
+ * 「清了个不存在的东西」根本不该报错 —— 用户的意图已经达成了。
+ */
+interface WireGoalClearResponse {
+    ok: boolean;
+    cleared: boolean;
+    reason?: WireGoalRefusal;
+}
+declare const WIRE_GOAL_CLEAR_FIELDS: WireFields<WireGoalClearResponse>;
+/**
+ * 一段卡住了的会话。
+ *
+ * ## 组合而不是摊平 —— 判据同 `WireScheduleRow`
+ *
+ * `goal` 原样嵌着，外面那两格是**这一条通知要的宾语**。摊平之后
+ * `GET /api/sessions/:id/goal` 的响应和这一份会长得像同一个东西，而它们答的是
+ * 两个问题（「我正看着的这段会话怎么样」/「**别的**哪几段卡着」）。
+ *
+ * ## `sessionTitle` 就是「界面要而库里没有的那一格」
+ *
+ * `goals` 表里没有标题（它只认 `session_id`），而 dock 第四档的宾语是**会话标题**
+ * ——GOALS.md §三 那张收敛表上写死的。**服务端 join 而不是浏览器再拉一发会话
+ * 列表**：那样这条通知的宾语来自另一个瞬间，于是一段刚被改名的会话在 dock 上
+ * 会印着旧名字，而没有任何东西会报错。
+ *
+ * 标题是空串时**原样发空串，不在服务端兜一个「未命名会话」**：那句话是界面文案
+ * （`web.ui.topbar.untitled`），服务端渲染好一份发过来，浏览器切成英文就换不了了。
+ */
+interface WireBlockedGoal {
+    sessionId: string;
+    /** 会话标题。空串 = 还没有标题，措辞归界面 */
+    sessionTitle: string;
+    /** `phase` 恒为 `blocked`，`block` 因此恒在 —— 但类型上仍然是那一份 `WireGoal` */
+    goal: WireGoal;
+}
+declare const WIRE_BLOCKED_GOAL_FIELDS: WireFields<WireBlockedGoal>;
+/**
+ * `GET /api/goals/blocked`。
+ *
+ * ## ⚠️ 为什么单开一条，而不是搭会话列表那一发的车
+ *
+ * 判据同 `GET /api/schedules/pending`：读它的是 **dock**，也就是每一次首屏都要
+ * 问一次的东西。会话列表那一发回的是「最近 50 段会话 + 每段的挂起计数 + 活性」，
+ * 而这一条要的是「哪几段的目标卡着」——两件事的真源不同（一个在 Hub 的内存里，
+ * 一个在 `goals` 表里），合并的下场是那一发的形状为一个角标变宽一格。
+ *
+ * 也不合并进 `GET /api/config`（首屏那一发）：那一份是**进程级的常量**
+ * （品牌 / 口径 / 诊断），一次都不按时间变；而这个数会因为「另一段会话刚撞上
+ * 预算」而变。
+ *
+ * ## ⚠️ 它**不订阅**，而这一条要如实说给用户听
+ *
+ * 事件流上**没有「目标变了」这一帧**（52 落地那一轮一个事件都没加，那是刻意的：
+ * 目标是状态加策略，不是循环结构）。所以这个数只在「取数那一刻」为真，
+ * 界面在三个时刻拉它：首屏、这段会话的回合回到 idle、以及用户自己动过手之后。
+ *
+ * ⚠️ 于是**别的**会话在后台撞上预算这件事，要等下一次上面那三个时刻之一才看得见。
+ * 如实记着 —— 不是漏接：真要即时，前置是在事件流上加一帧，而那是独立的一次改动。
+ */
+interface WireBlockedGoalsResponse {
+    /** **最久没动的在前**（`updatedAt` 升序）。一段都没卡住时空数组 */
+    items: readonly WireBlockedGoal[];
+}
+declare const WIRE_BLOCKED_GOALS_FIELDS: WireFields<WireBlockedGoalsResponse>;
+
+/**
+ * `@` 补全面板要列什么 —— 两条候选端点的载荷。
+ *
+ * | 载荷                              | 端点                                     | 落地       |
+ * | --------------------------------- | ---------------------------------------- | ---------- |
+ * | {@link WireSessionCandidate}      | `GET /api/sessions/:id/reference-candidates` | 方案 53 PR-4 |
+ * | {@link WireFileCandidate}         | `GET /api/sessions/:id/file-candidates`      | 方案 63      |
+ *
+ * 两份**不合并成一个「候选」形状**，判据同下面那节（一份清单 vs 一次动作的收据）
+ * 的同一条道理：会话候选有六个字段要印（标题 / 时间 / 条数 / 在哪个工作区），
+ * 文件候选只有一个路径，而合成一个联合之后每个消费方都得先分流一次才能画一行。
+ * 面板那一侧本来就是**一次只开一组**（`@:` 是会话、`@` 后面不是 `:` 就是文件，
+ * 前缀互斥 —— 判据在 `web/src/mention/trigger.ts` 上）。
+ *
+ * ## 这一份和「上一条消息引用到了什么」是两个形状
+ *
+ * 后者是 [wire-rest.ts](./wire-rest.js) 的 `WireSessionReference`（挂在
+ * `POST /messages` 的 202 上），**刻意不合并**：这一份是一份清单（可以为空，
+ * 空就是面板不画）；那一份是一次动作的收据，带着那五个稳定错误码。
+ * 合成一个形状的话，「候选里那一行为什么带着一个 `omitted`」没人答得上来。
+ *
+ * 两份住在两个文件里还有一条更硬的理由：`wireFields` 住在 `wire-rest.ts`，
+ * 而那一份的消费方就在它自己文件里 —— 反过来让 `wire-rest.ts` import 这一份
+ * 会造一个环，而 `import/no-cycle` 在 oxlint 里是 error（判据在
+ * `server/src/context.ts` 的文件头）。
+ *
+ * ## ⚠️ 这份形状里**没有一个字的转录文本**，而且不许加（方案 53 §5.2）
+ *
+ * 判据在 core 的 `SessionCandidate` 上，逐字照搬到这儿：补全面板是**边打边显示**
+ * 的，它一旦带上转录文本，打 `@:密码` 就会在屏幕上列出所有提到过密码的会话及其
+ * 片段 —— 而当前这个会话可能正在被别人看着（结对编程、录屏、演示）。
+ *
+ * `sessions` 表上那个 `preview` 列（首条消息的前几十字）**同样不在这里**：
+ * 它是转录文本的投影，加进来等于把那条边界从「面板不搜正文」偷偷降级成
+ * 「面板不搜正文但会把正文显示出来」。
+ *
+ * ⚠️ **过滤也不在浏览器里做。** `?q=` 原样递给 core 的
+ * `listSessionCandidates`，那条 SQL 只碰 id / cwd / 标题，而且带着可读性判定的
+ * WHERE（方案 48 那一处）。把「拉一池子回来再在前端筛」当成省一次请求的优化，
+ * 代价是那一池子之外的会话**永远搜不到，而且屏幕上没有任何提示**
+ * —— TUI 那一侧今天就挂着这笔账（`SESSION_CANDIDATE_POOL`，40 条封顶）。
+ */
+/**
+ * 补全面板里的一条会话候选。
+ *
+ * **是 core 的 `SessionCandidate` 的结构镜像**（`packages/web` 只依赖
+ * protocol + view，够不着 core），字段逐个对应，一个不多。
+ */
+interface WireSessionCandidate {
+    sessionId: string;
+    /** 会话标题。**空标题在引擎侧已经兜了 sessionId**（方案 53 §5.3），所以永远非空 */
+    title: string;
     /**
-     * 给用户的建议，例如「MCP server github 一家占了 18%，考虑改成 Deferred 曝光」。
+     * 那段会话的工作目录。
      *
-     * 只在**真有可操作动作**时给。「你的历史很长」不算建议 —— 用户对此无能为力，
-     * 而压缩器本来就会处理它。
+     * 递下来是因为**它参与匹配**（§5.2 允许按 cwd 过滤），而不是为了显示一条绝对
+     * 路径 —— 面板上只印它的最后一段（同 TUI 那一侧的 `toCandidateView`）。
      */
-    hints: string[];
+    cwd?: string;
+    /** 最后活动时间（epoch 毫秒）。面板上那句「几天前」用它 */
+    updatedAt: number;
+    /** 一共多少条消息（含被压掉的） */
+    messageCount: number;
+    /** 是不是当前工作区的会话。排序靠它，面板上也要标出来 */
+    sameWorkspace: boolean;
+}
+declare const WIRE_SESSION_CANDIDATE_FIELDS: WireFields<WireSessionCandidate>;
+/**
+ * `GET /api/sessions/:id/reference-candidates` 的响应。
+ *
+ * 包一层而不是裸数组，同这一层别的清单端点：将来加游标不会把响应形状整个换掉。
+ *
+ * **一段都没有时是空数组，不是 404 也不是错误** —— 一台只跑过一段会话的机器上
+ * 这就是正常状态（当前这一段自己不在候选里，见 core 的 `listSessionCandidates`），
+ * 而界面据此整个不画那个面板（决定 20 ①）。
+ */
+interface WireSessionCandidatesResponse {
+    candidates: readonly WireSessionCandidate[];
+}
+declare const WIRE_SESSION_CANDIDATES_FIELDS: WireFields<WireSessionCandidatesResponse>;
+/**
+ * 补全面板里的一条文件候选。
+ *
+ * **只有路径**，而这一格是刻意窄的：面板那一行要印的两截（文件名 + 它上面那层
+ * 目录）都是从这一个字符串切出来的，让服务端多发一个 `name` 等于给同一件事
+ * 两个说法。体积也不是小事 —— 一次响应几十条，每条多一个字段就是多一份重复。
+ *
+ * ⚠️ **这里没有 `bytes`，而且别加。** 加它意味着服务端要对每条候选 `stat()` 一次
+ * ——补全面板是**边打边刷**的，那就是每按一个键几十次系统调用，换来的只是一行
+ * 灰字。真要那个数，它已经在附上之后那张卡上了（`EpochFilePart.bytes`，
+ * 那一刻只 stat 用户真的选中的那一个）。
+ */
+interface WireFileCandidate {
+    /** 相对工作区根的路径，**一律 `/` 分隔**（判据同 core 的 `WorkspaceFiles.files`） */
+    path: string;
+}
+declare const WIRE_FILE_CANDIDATE_FIELDS: WireFields<WireFileCandidate>;
+/**
+ * `GET /api/sessions/:id/file-candidates` 的响应。
+ *
+ * ## 后面那两个数是**沉默截断的解药**，不是诊断字段
+ *
+ * 这条路上有两处「面板本该列出来、而它没有」的地方，两处都会让用户以为
+ * 「这个仓库里没有这个文件」：
+ *
+ * - {@link unmentionable} —— 匹配上了，但 `@` 的抽取规则表达不出这个路径
+ *   （判据全文在 `isMentionableFilePath` 上）；
+ * - {@link truncated} —— 工作区文件清单本身撞了两万条的上限（core 的 `MAX_FILES`），
+ *   于是清单之外的文件**压根没参与匹配**。
+ *
+ * 两个数都直接印在面板上。少印一个，那一档就退化成 TUI 那侧 40 条池子的老病：
+ * 「永远搜不到，而且屏幕上没有任何提示」（那笔账记在方案 53 验收记录第六章）。
+ *
+ * ⚠️ **`candidates` 为空不是错误**：一个刚 `git init` 的空目录上这就是正常状态，
+ * 而界面据此整个不画那个面板（决定 20 ①）。
+ */
+interface WireFileCandidatesResponse {
+    candidates: readonly WireFileCandidate[];
+    /**
+     * 匹配上了、但 `@` 表达不出来因而**没进上面那张清单**的条数。
+     *
+     * 0 是常态。非 0 时面板要多印一行灰字 —— 见上面那节。
+     */
+    unmentionable: number;
+    /** 工作区文件清单撞了上限，清单之外的文件没参与匹配 */
+    truncated: boolean;
 }
+declare const WIRE_FILE_CANDIDATES_FIELDS: WireFields<WireFileCandidatesResponse>;
 
 /**
  * 凭据存储契约。
@@ -8485,4 +11147,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 BackgroundTaskStatus, type BudgetBreach, COMMAND_NAME_PATTERN, type ContextBreakdown, type ContextSegment, 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 EpochSkill, type EpochTextPart, type EpochTool, type EpochToolCall, type EpochToolResult, type EpochTurnFacts, type EpochUserContent, type ExpandedCommand, type FileOmitReason, type FinishReason, 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 JsonSchema, KEY_ACTIONS, type KeyAction, type KeyChord, type KeyContext, type KeybindingTable, LANGS, type Lang, type LocalizedDetail, type LogFn, MAX_HEADER_CHARS, MAX_OPTIONS, MAX_QUESTIONS, MCP_DATA_KEY_NAME, METRIC, MIN_OPTIONS, type ModelRef, type ModelSelection, type ModelSelectionOrigin, NOOP_TELEMETRY, OPERATION_TYPES, type Operation, type OperationType, PERMISSION_LEVELS, PLAN_OUTCOMES, PLAN_OUTCOME_LABELS, 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 RuleValue, SCHEDULE_INTERVAL_MINUTES, SCHEDULE_RUN_STATUSES, SEARCH_API_KEY_ENV, SEARCH_PROVIDER_TYPES, SECRET_SERVICE, SHELL_KINDS, SIMULTANEOUS_CONTEXTS, SYSTEM_NOTE_PREFIX, type ScheduleAllowlist, type ScheduleBackendKind, type ScheduleCycle, type ScheduleDefinition, type SchedulePendingApproval, type ScheduleRun, type ScheduleRunStatus, type ScheduleRunnerSpec, type ScheduleTrigger, type ScheduleTriggerKind, type ScheduleWeekday, type SearchProviderType, type SecretBackendId, type SecretStore, type SelectionContext, type SelectionRejection, type SelectionWarning, type SetSelectionResult, type ShellKind, type SpanLike, type Telemetry, type TokenUsage, type ToolAnnotations, type ToolArtifact, type ToolArtifactInput, type ToolContext, type ToolDefinition, ToolExposure, type ToolProvider, type ToolResult, type TrustLevel, type TrustManager, type TrustRecord, type TrustScope, type VerifyResult, WIRE_ABORT_FIELDS, WIRE_ABOUT_FIELDS, WIRE_AGENT_ROLE_FIELDS, WIRE_APPROVAL_LIST_FIELDS, WIRE_APPROVAL_ROW_FIELDS, WIRE_ARTIFACTS_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_LEVEL_FIELDS, WIRE_BUILTIN_CONNECTOR_FIELDS, WIRE_CAPABILITIES_FIELDS, WIRE_CAPABILITY_PROJECT_FIELDS, WIRE_CHECKPOINT_LIST_FIELDS, WIRE_CHECKPOINT_SUMMARY_FIELDS, WIRE_COMMANDS_FIELDS, WIRE_COMMAND_EXPANSION_FIELDS, WIRE_COMPRESSION_LINE_FIELDS, WIRE_CONFIG_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_CHANGE_FIELDS, WIRE_HEALTH_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_POLICY_DIR_FIELDS, WIRE_POLICY_STATUS_FIELDS, WIRE_PROVIDERS_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_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_FINISH_FIELDS, WIRE_SESSION_LIST_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_FIELDS, WIRE_SKILL_IMPORT_FIELDS, WIRE_SKILL_IMPORT_PREVIEW_FIELDS, WIRE_TASKS_FIELDS, WIRE_TOOLS_FIELDS, WIRE_TOOL_GATE_FIELDS, WIRE_TOOL_ROW_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 WireApprovalListResponse, type WireApprovalRequest, type WireArtifactsResponse, type WireAuditCode, type WireAuditLog, type WireAuditOutcome, type WireAuditRow, type WireAuthDenyReason, type WireAuthDenyStatus, type WireAuthGuard, type WireAuthRequestView, type WireAuthVerdict, type WireBackgroundTask, type WireBindWorkspaceRequest, type WireBlockedLevel, type WireBuiltinConnector, type WireCapabilitiesResponse, type WireCapabilityProject, type WireCheckpointListResponse, type WireCheckpointSummary, type WireCommandExpansion, type WireCommandsResponse, type WireCompressionLine, type WireConfigResponse, 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 WireFileChange, type WireFixture, type WireFixtureCase, type WireHealthResponse, type WireHubEnvelope, type WireHubEvent, type WireKnownWorkspace, 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 WirePermissionRuleRow, type WirePermissionSetRequest, type WirePermissionSetResponse, type WirePermissionShadow, type WirePermissionState, type WirePermissionStatus, type WirePlanAction, type WirePlanModeRequest, type WirePlanModeResponse, type WirePlanModeState, type WirePlanResponse, type WirePolicyDir, type WirePolicyStatus, 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 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 WireSessionFinish, type WireSessionListResponse, type WireSessionResponse, type WireSessionSummary, type WireSessionWorkspace, type WireSessionWorkspaceResponse, type WireSettingApply, type WireSettingFutile, type WireSettingLayer, type WireSettingRow, type WireSettingStep, type WireSettingValue, 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 WireSkillSummary, type WireSummaryWorkspace, type WireTaggedEvent, type WireTasksResponse, type WireToolGate, type WireToolGateAxis, type WireToolRow, type WireToolSummary, type WireToolVerdict, type WireToolsResponse, type WireTurnState, type WireWorkspaceBinding, type WireWorkspaceDiffResponse, type WireWorkspaceDirEntry, type WireWorkspaceDirsResponse, type WireWorkspaceRef, apiKeyEnvVar, chordId, compressionThresholdTokens, conformsToWire, contentToText, diagnosticToLine, extractMentions, filePartSummary, getProviderInfo, hasFailure, isApprovalOutcome, isContextNearlyFull, isHeadlessInputFormat, isHeadlessLifecycleEvent, isHeadlessOutputFormat, isKeyAction, isLang, isOperationType, isPermissionLevel, isPlanOutcome, isProviderType, isQuestionAnswerMap, isSearchProviderType, isValidAgentRoleName, isValidCommandName, isWireHubEvent, isWirePlanAction, isWireRewindScope, isWireSettingWriteLayer, normalizeApproval, parseChord, parseModelRef, promptTokens, stripSystemNote, systemNote, totalUsageTokens, 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 BoundKey, type BudgetBreach, COMMAND_NAME_PATTERN, type Catalogs, type ContextBreakdown, type ContextSegment, 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, 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 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, NOOP_TELEMETRY, type NoticeCode, OPERATION_TYPES, 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_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, SIMULTANEOUS_CONTEXTS, SYSTEM_NOTE_PREFIX, type ScheduleAllowlist, type ScheduleBackendKind, type ScheduleCycle, type ScheduleDefinition, type SchedulePendingApproval, type SchedulePendingItem, type ScheduleRun, type ScheduleRunStatus, type ScheduleRunnerSpec, type ScheduleTemplate, type ScheduleTemplateId, type ScheduleTrigger, type ScheduleTriggerKind, type ScheduleWeekday, 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 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 TrustLevel, type TrustManager, type TrustRecord, type TrustScope, 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_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_REFERENCE_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_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_INSTALL_FIELDS, WIRE_PLUGIN_NAME_FIELDS, WIRE_PLUGIN_PREVIEW_FIELDS, WIRE_PLUGIN_PREVIEW_RESPONSE_FIELDS, WIRE_PLUGIN_UPDATE_FIELDS, WIRE_POLICY_DIR_FIELDS, WIRE_POLICY_STATUS_FIELDS, WIRE_PROVIDERS_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_FIELDS, WIRE_SKILL_IMPORT_FIELDS, WIRE_SKILL_IMPORT_PREVIEW_FIELDS, WIRE_TASKS_FIELDS, WIRE_TOOLS_FIELDS, WIRE_TOOL_GATE_FIELDS, WIRE_TOOL_ROW_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 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 WireFileReference, type WireFixture, type WireFixtureCase, 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 WireKnownWorkspace, 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 WirePermissionRuleRow, type WirePermissionSetRequest, type WirePermissionSetResponse, type WirePermissionShadow, type WirePermissionState, type WirePermissionStatus, type WirePlanAction, type WirePlanModeRequest, type WirePlanModeResponse, type WirePlanModeState, type WirePlanResponse, type WirePluginActionResponse, type WirePluginCounts, type WirePluginEntry, type WirePluginHit, type WirePluginHookTally, type WirePluginInstallRequest, type WirePluginNameRequest, type WirePluginPreview, type WirePluginPreviewRequest, type WirePluginPreviewResponse, type WirePluginRefuseReason, type WirePluginSourceType, type WirePluginUpdateRequest, type WirePluginsResponse, type WirePolicyDir, type WirePolicyStatus, 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 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 WireSkillSummary, type WireSummaryWorkspace, type WireTaggedEvent, type WireTasksResponse, type WireToolGate, type WireToolGateAxis, type WireToolRow, type WireToolSummary, type WireToolVerdict, type WireToolsResponse, 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, getProviderInfo, hasFailure, isApprovalOutcome, isContextNearlyFull, isHeadlessInputFormat, isHeadlessLifecycleEvent, isHeadlessOutputFormat, isKeyAction, isLang, isMentionableFilePath, isOperationType, isPermissionLevel, isPlanOutcome, isProviderType, isQuestionAnswerMap, isSearchProviderType, isValidAgentRoleName, isValidCommandName, isWireGoalPhase, isWireHubEvent, isWirePlanAction, isWireRewindScope, isWireSettingWriteLayer, makeTranslate, normalizeApproval, packSessionSurface, parseChord, parseModelRef, parseSequence, perAction, placeholdersOf, promptTokens, sequenceId, sessionPartSummary, stripSystemNote, systemNote, tableOf, totalUsageTokens, translatorFor, turnDigest, unfixedRules, utf8ByteLength, wireFields };