@epoch-agent/runtime 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-import { GoalRoundResult, Goal, GoalWrite, GoalClear, Workspace, TrustDecision, ProjectContext, RecentWorkspace, TrustGate, RecentWorkspaces, PermissionManager, SessionManager, AgentLoop, PluginCommandDir, ScheduleRegistrar, HeadlessPolicy, CreateScheduleInput, ScheduleIssue, RegisterOutcome, UpdateScheduleInput, needsAllowlist, ConfigOrigins, SkillDirSpec, ProviderRouter, AgentProvider, GoalService, MemoryManager, SkillSystem, SkillLearner, HookManager, ContextCompressor, TrackerDB, TrustManager, ModelPricing, LayerOutcome, ManagedPolicy, PluginArtifacts, CheckpointSummary, RewindPreview, RewindOutcome, CodeSandbox, ToolRegistry, QuestionAskFn, SettingValue, SettingLayer, SettingStep, SettingWriteTarget, IsolationReport, RoleMergeNotice, SkillMeta, SkillImportResult, SkillImportPreview, SkillImportDone, ShadowFinding, BaseOrigin, PermissionAuditScope, PermissionAuditSnapshot, ToolGate, SettingWriteLayer, SettingApply, SettingWriteFailure, PluginPathRef } from '@epoch-agent/core';
-export { SANDBOX_COVERS, SANDBOX_EXCLUDES, SCHEDULE_DEFAULTS, SCHEDULE_DEFAULT_ALLOWLIST, nextRunAt, readRecording, skillIndexDescription } from '@epoch-agent/core';
+import { GoalRoundResult, Goal, GoalWrite, GoalClear, Workspace, TrustDecision, ProjectContext, RecentWorkspace, TrustGate, RecentWorkspaces, PermissionManager, SessionManager, FtsHealth, FtsReclaim, AgentLoop, PluginCommandDir, InstallPreview, PluginRecord, PluginSourceType, PluginCounts, MarketplaceEntry, ScheduleRegistrar, HeadlessPolicy, CreateScheduleInput, ScheduleIssue, RegisterOutcome, UpdateScheduleInput, needsAllowlist, HookSourceStatus, ConfigOrigins, SkillDirSpec, ProviderRouter, AgentProvider, GoalService, MemoryManager, SkillSystem, SkillLearner, HookManager, ContextCompressor, TrackerDB, TrustManager, ModelPricing, LayerOutcome, ManagedPolicy, PluginArtifacts, CheckpointSummary, RewindPreview, RewindOutcome, ToolRevealState, CodeSandbox, ISkillSystem, ToolRegistry, QuestionAskFn, ResponseFormat, ProviderWarning, SettingValue, SettingLayer, SettingStep, SettingWriteTarget, SessionReferences, IsolationReport, RoleMergeNotice, SkillMeta, SkillIndexResidency, SkillImportResult, SkillImportPreview, SkillImportDone, ShadowFinding, BaseOrigin, PermissionAuditScope, PermissionAuditSnapshot, CachedApproval, ToolGate, SettingWriteLayer, SettingApply, SettingWriteFailure, PluginPathRef } from '@epoch-agent/core';
+export { DEFAULT_GOAL_MAX_ROUNDS, MAX_GOAL_MAX_ROUNDS, MAX_OBJECTIVE_CHARS, MAX_REASON_CHARS, SANDBOX_COVERS, SANDBOX_EXCLUDES, SCHEDULE_DEFAULTS, SCHEDULE_DEFAULT_ALLOWLIST, nextRunAt, readRecording, skillIndexDescription } from '@epoch-agent/core';
 import { McpServerConfig, McpServerStatus, McpServerSource, McpTransport, McpAuthStatus } from '@epoch-agent/plugin-mcp';
 export { McpAuthState, McpAuthStatus, McpServerConfig } from '@epoch-agent/plugin-mcp';
-import { Lang, DiagnosticSink, EpochContentPart, EpochToolCall, EpochToolResult, EpochTurnFacts, TokenUsage, EpochMessage, ApprovalRequest, ApprovalReply, QuestionRequest, QuestionAnswer, EpochUserContent, AgentEvent, CustomCommandDef, ExpandedCommand, ToolProvider, ModelRef, SetSelectionResult, AgentRole, ProviderType, SecretStore, WireModelSource, WireModelProbeStatus, PermissionLevel, ModelSelection, SelectionContext, ScheduleRunStatus, ScheduleRun, ScheduleDefinition, ScheduleBackendKind, ScheduleRunnerSpec, LogFn, EpochConfig, ActiveAgentRole, ApprovalOutcome, PermissionManager as PermissionManager$1, TrustManager as TrustManager$1, ContextBreakdown, Diagnostic } from '@epoch-agent/protocol';
+import { Lang, DiagnosticSink, EpochContentPart, EpochToolCall, EpochToolResult, EpochTurnFacts, TokenUsage, EpochMessage, ApprovalRequest, ApprovalReply, QuestionRequest, QuestionAnswer, EpochUserContent, AgentEvent, CustomCommandDef, ExpandedCommand, ToolProvider, ModelRef, SetSelectionResult, EpochTool, AgentRole, ProviderType, SecretStore, WireModelSource, WireModelProbeStatus, PermissionLevel, ModelSelection, SelectionContext, ScheduleRunStatus, ScheduleRun, ScheduleDefinition, ScheduleBackendKind, ScheduleRunnerSpec, LogFn, EpochConfig, ActiveAgentRole, ApprovalOutcome, PermissionManager as PermissionManager$1, TrustManager as TrustManager$1, ContextBreakdown, Diagnostic } from '@epoch-agent/protocol';
 export { BackgroundTaskInfo, BackgroundTaskStatus } from '@epoch-agent/protocol';
 export { t } from '@epoch-agent/infra';
 export { taskOutput as backgroundTaskOutput, listTasks as listBackgroundTasks } from '@epoch-agent/plugin-terminal';
@@ -75,6 +75,50 @@ interface GoalControl {
 interface GoalRounds {
     beginRound(sessionId: string): GoalRoundResult;
 }
+/**
+ * 「**任意一段**会话的目标」—— 按 sessionId 现查的那一份（方案 52 PR-4）。
+ *
+ * ## 它和上面那个 {@link GoalControl} 是两件事，而且都要
+ *
+ * ```
+ * GoalControl   「**我这一段**的目标怎么样」   —— TUI / 一个会话一个宿主
+ * GoalCatalog   「**那一段**的目标怎么样」     —— 多会话宿主（web 服务端）
+ * ```
+ *
+ * 一个 HTTP 服务进程手里同时有 N 段会话，而每一条请求的 sessionId 来自 URL ——
+ * 它压根没有「我这一段」这个东西。收窄口在那种宿主里反过来变成障碍：要么给每段
+ * 会话各包一个（那是工厂已经干的事，但**它只装得下这个进程正握着的那些**），
+ * 要么让服务端拿一个 id 去问一个和它无关的控制面。
+ *
+ * ⚠️ **这一份能答冷却掉的会话，而工厂那一份不能** —— 这是它存在的正题。
+ * 目标**没有内存态**：`GoalService` 每次都现读 SQLite（`GoalStore.current`），
+ * 所以「这段会话此刻活不活着」和「它的目标是什么」是两个无关的问题。
+ * 计划那一格必须分两个数据源（内存里那份可能比盘上新，判据在
+ * `server/src/plan.ts` 的文件头），目标这一格**只有一个真源**，因此不分支。
+ *
+ * ## ⚠️ 刻意**没有** `block()`，也不许有
+ *
+ * 判据逐字同 {@link GoalControl}（那儿也没有）：`blocked` 是模型 / 策略层的态，
+ * 模型走的是它手里那个 `goal` 工具，策略层走的是 `AgentSession.run()` 里那一步。
+ * 从宿主这一侧露出一个 `block()`，等于给下一个人一条「原来这儿能报卡住」的路 ——
+ * 而那个 `code` 是**给程序路由用的键**（dock 第四档按它决定给哪个动作），
+ * 让宿主编一个出来的方向是提权（52 §5.1 结论 3）。
+ *
+ * `promptView` / `beginRound` 同样不在这儿：前者是 prompt 的事（`goal/provider.ts`），
+ * 后者是划轮的事（{@link GoalRounds}）。**逐个方法转发而不是把 `GoalService`
+ * 原样递出去**，就是为了让上面这三条在类型上成立，而不是靠一句叮嘱。
+ */
+interface GoalCatalog {
+    current: (sessionId: string) => Goal | null;
+    /** 建一个（**人专用**，判据同 `GoalControl.create`） */
+    create: (sessionId: string, objective: string, maxRounds?: number) => GoalWrite;
+    edit: (sessionId: string, objective: string) => GoalWrite;
+    setBudget: (sessionId: string, maxRounds: number) => GoalWrite;
+    pause: (sessionId: string) => GoalWrite;
+    resume: (sessionId: string) => GoalWrite;
+    complete: (sessionId: string, evidence: string) => GoalWrite;
+    clear: (sessionId: string) => GoalClear;
+}
 
 /**
  * 「这个会话在工作区里改过哪些文件」（方案 42 PR-4）。
@@ -736,9 +780,15 @@ declare class SessionStore {
      *
      * ⚠️ **它不是 `cwd`。** 上面那个 `cwd` 记的是「这段会话属于哪个项目」
      * （`epoch -c` 照它找、`core/session/authorization.ts` 拿它当鉴权边界），
-     * 而它在三条路上记的是**服务进程的启动目录**而不是用户选的地盘 ——
-     * 那正是这一格必须另开的原因，判据在 v7 那条迁移的 JSDoc 里。
-     * **这一轮一个字不碰 `cwd`。**
+     * 这一格记的是「用户为这段会话做过什么**决定**」（含「明确不使用工作区」——
+     * 那一档压根没有项目根可记）。两者仍然是两件事。
+     *
+     * ⚠️ 上面那句话 2026-08-20 前半段过期了一次：原文说 `cwd`「在三条路上记的是
+     * **服务进程的启动目录**而不是用户选的地盘」，并把那个偏差当成这一格必须另开的
+     * 理由之一。**那个偏差是迟绑那一轮修掉的 bug 本身**（判据在 `SessionFactory`
+     * 的 `assemble` 上），`cwd` 现在记的就是这段会话真正在跑的那个项目根。
+     * **两格照旧都要在**，但理由收窄成上一段那一条：一个是「哪个项目」、
+     * 一个是「什么决定」，而后者有一档没有前者。
      *
      * ⚠️ **收 sessionId 而不是闭包一个**：`AgentSession.resume()` 会就地换掉
      * `sessionId`，而这个 store 实例跟着那个 `AgentSession` 走（上面 `cwd` /
@@ -760,8 +810,13 @@ declare class SessionStore {
      * 传项目根而不是 `process.cwd()`：在子目录里敲 `epoch -c` 要接上同一个仓库的
      * 会话。读取侧（`SessionManager.getLatestByCwd`）用的是同一个口径。
      * 不给就仍然写 NULL —— 那段会话只是不参与 `-c` 匹配，别的一切照旧。
+     *
+     * ⚠️ **收函数不收字符串**（迟绑，2026-08-20），判据同下面那个 `decision`：
+     * 建行发生在**第一条消息**那一刻，而这段会话的地盘可能是装配之后才选的
+     * （`deferWorkspace` 那一档）。快照的表现是一段在用户挑的目录里干了一整轮活的
+     * 会话，在库里记着服务进程的启动目录 —— 于是 `epoch -c` 在那个项目里接不到它。
      */
-    constructor(sessions: SessionManager, artifactsRoot?: string | undefined, cwd?: string | undefined, 
+    constructor(sessions: SessionManager, artifactsRoot?: string | undefined, cwd?: (() => string | undefined) | undefined, 
     /**
      * 这段会话是谁开的（`sessions.source`）。缺省 `'cli'`。
      *
@@ -785,9 +840,15 @@ declare class SessionStore {
      *
      * ⚠️ **它不是 `cwd`。** 上面那个 `cwd` 记的是「这段会话属于哪个项目」
      * （`epoch -c` 照它找、`core/session/authorization.ts` 拿它当鉴权边界），
-     * 而它在三条路上记的是**服务进程的启动目录**而不是用户选的地盘 ——
-     * 那正是这一格必须另开的原因，判据在 v7 那条迁移的 JSDoc 里。
-     * **这一轮一个字不碰 `cwd`。**
+     * 这一格记的是「用户为这段会话做过什么**决定**」（含「明确不使用工作区」——
+     * 那一档压根没有项目根可记）。两者仍然是两件事。
+     *
+     * ⚠️ 上面那句话 2026-08-20 前半段过期了一次：原文说 `cwd`「在三条路上记的是
+     * **服务进程的启动目录**而不是用户选的地盘」，并把那个偏差当成这一格必须另开的
+     * 理由之一。**那个偏差是迟绑那一轮修掉的 bug 本身**（判据在 `SessionFactory`
+     * 的 `assemble` 上），`cwd` 现在记的就是这段会话真正在跑的那个项目根。
+     * **两格照旧都要在**，但理由收窄成上一段那一条：一个是「哪个项目」、
+     * 一个是「什么决定」，而后者有一档没有前者。
      *
      * ⚠️ **收 sessionId 而不是闭包一个**：`AgentSession.resume()` 会就地换掉
      * `sessionId`，而这个 store 实例跟着那个 `AgentSession` 走（上面 `cwd` /
@@ -919,6 +980,19 @@ declare class SessionStore {
      * `assistantText += event.text`），合完是空就整条不发（那边也是
      * `if (assistantText)`）。判据是 resume 回来的上下文必须和刚才在内存里的那份
      * **逐字相同** —— 差一个换行，模型看到的就是另一段历史。
+     *
+     * ## ⚠️ 2026-08-28：合并之后还要挂上那一行「本轮调用过的工具」
+     *
+     * tool 行仍然不进历史（上面第一段那条理由没变），但它们身上的
+     * `toolResults` 现在要被**读一眼**：那一轮调过哪些工具，折成一行挂在合并后的
+     * assistant 消息末尾。判据全文在 protocol 的 `assistantTurnText` 上，一句话是
+     * 「光留最终正文的话，早期那几条用户指令在模型眼里像是没做完」。
+     *
+     * 所以这个循环从「逐条过滤」改成了**按轮分组**：user 行是轮边界，一轮里的
+     * assistant 正文和 tool 结果各自攒起来，边界上一次性折出一条。
+     * 攒的那一份和直播那边喂给 `assistantTurnText` 的**是同一批东西**
+     * （`steps.flatMap(s => s.toolResults)`），所以两条路产出逐字节相同 ——
+     * 门禁在 `packages/runtime/__tests__/context-recency.test.ts`。
      */
     loadHistory(sessionId: string): Array<{
         role: 'user' | 'assistant';
@@ -948,6 +1022,29 @@ declare class SessionStore {
      * 汇总，它自己坏了不该让整屏 500。
      */
     fileChanges(sessionId: string, workDir: string): SessionFileChange[];
+    /**
+     * FTS 索引体检（方案 48 PR-4）—— `epoch doctor` 的「会话检索」一节。
+     *
+     * 这个方法在这里纯粹是**够得着**的问题：doctor 手上有 `rt.sessionStore`，
+     * 没有 `SessionManager`（`EpochRuntime` 刻意不交出那个 —— 交出去等于给宿主
+     * 一条对会话库执行任意 SQL 的路）。所以照这个类既有的形状再加一层薄封装。
+     *
+     * ⚠️ **只给 doctor 用。** 它要扫全表 + 跑完整性检查（外部内容表上还有一道
+     * `rank = 1` 的逐行比对，要重分词），会话库大起来之后是秒级的。
+     * 别接到启动路径或任何 REST 端点上，
+     * 判据全文在 `core/src/session/fts-health.ts` 的文件头。
+     */
+    ftsHealth(): FtsHealth;
+    /**
+     * 把删掉的会话在索引里留下的字节收回来 —— `epoch doctor --reclaim` 的落点。
+     *
+     * 在这里的理由同上面那一条（doctor 手上只有 `rt.sessionStore`）。
+     *
+     * ⚠️ 这一个**会写**，而且 `VACUUM` 要独占库文件：**只许由用户显式要求触发**，
+     * 别接到任何自动路径上（三条理由在 `core/src/session/fts-health.ts` 的
+     * `reclaimFtsSpace()` 上）。
+     */
+    reclaimFts(vacuum?: boolean): FtsReclaim;
 }
 
 /**
@@ -1054,6 +1151,18 @@ interface AgentSessionOptions {
      * 里 `lastRole` 那一格）：从「有」变成「没有」同样要留痕。
      */
     currentRole?: () => string | undefined;
+    /**
+     * 这一轮在哪个目录里跑（迟绑，2026-08-20，可选）。没给就一条留痕都不插。
+     *
+     * **给函数不给路径**，判据逐字同上面 `currentRole`：`unbound` 那一档的会话
+     * （侧栏「新建会话」）建出来时还没有地盘、跑在服务进程的启动目录上，
+     * 地盘是用户之后在输入框底栏那张 picker 里挑的。快照永远等于启动目录。
+     *
+     * ⚠️ **它是「引擎现在按哪个目录干活」，不是「绑定表里写着什么」**：后者在
+     * 「不使用工作区」和「还没选」两档都是 null，而引擎其实在启动目录里跑着 ——
+     * 拿它留痕会说出一句和真跑的不是同一件事的话。真源见 `AgentSiteRef`。
+     */
+    currentWorkDir?: () => string;
 }
 declare class AgentSession {
     /**
@@ -1084,6 +1193,17 @@ declare class AgentSession {
      * 那个解析器就静默失灵。
      */
     private lastRole;
+    private readonly currentWorkDir;
+    /**
+     * 上一轮在哪个目录里跑（迟绑，2026-08-20）。
+     *
+     * ⚠️ **和 `lastRole` 有一处刻意的差别：它的起点不是构造那一刻的值，而是
+     * `null`**。理由是这条留痕只在**已经聊过**的会话上才有话要说（见
+     * {@link markWorkspaceHandoff}），而构造那一刻历史可能是空的也可能不是
+     * （`revive()` 接回来的那一段），两种情形下起点取哪个都会有一半是错的。
+     * 取 null + 由那个方法自己判「历史空不空」，两种情形就只有一套判据。
+     */
+    private lastWorkDir;
     /** 不是 `readonly` 的数组内容 —— `compact()` 和 `resume()` 会整体换掉它 */
     private history;
     /** 待交给宿主的请求队列（审批 + 提问）+ 「有新请求」的唤醒信号 */
@@ -1208,6 +1328,11 @@ declare class AgentSession {
      * 宿主只要 for-await 这个流，把 approval-request 交给用户点选即可 ——
      * 不用关心阻塞回调、不用自己拼历史、不用自己写持久化。
      *
+     * ⚠️ **每一帧在 `yield` 之前还会投一份到进程级事件观测口**（方案 61，
+     * `EpochRuntime.events`）。这不改变这条流的任何语义 —— 它仍然是**单消费者**、
+     * 仍然是拉式（没人迭代就一帧都不产生），观测口只是「多看了一眼」。
+     * 零订阅者时那一眼是一次 `size === 0` 的检查，不分配。
+     *
      * @param opts.signal 中止信号。`AgentLoop` 一直支持 `input.signal`（轮次之间
      *        和工具执行处都会检查），但这个签名以前不透传，于是宿主唯一的中止手段
      *        是硬杀进程 —— `dispose()` 跑不到，SQLite 连接和子进程都留着。
@@ -1245,6 +1370,34 @@ declare class AgentSession {
      * 「assistantText 为空时它恰好不写第二行」——那是一个实现细节，不是一条承诺。
      */
     private markRoleHandoff;
+    /**
+     * 地盘换了的那一刻，往历史里插一条 `[系统]` 消息（迟绑，2026-08-20）。
+     *
+     * ## 它答的是决定 18 反对中途换地盘的那一条理由
+     *
+     * 那条原话是：「中途换一个，前面那些工具调用里的 `./src/a.ts` 指的就是另一个
+     * 目录了，而**记录里没有任何地方写着「从这条开始换地盘了」**」。
+     * 换地盘这件事本身照旧只许发生一次（`unbound → bound`，服务端那道 409 守着），
+     * 这个方法补的是那句话的后半截 —— 于是那一次换成了一件**记录里说得出**的事。
+     *
+     * 形状三条判据逐字照 {@link markRoleHandoff}（`role: 'user'` + `[系统]` 前缀 /
+     * 两条连续 user 消息是安全的 / 只在真的变了那一条上插），**不在这儿抄第二遍**。
+     *
+     * ## ⚠️ 两道闸，各拦一件事
+     *
+     * 1. **`previous === null` —— 这是这段会话的第一轮。** 主路径（新建会话 →
+     *    挑目录 → 发第一句话）走的就是它：用户从头到尾只挑过一次，插一条
+     *    「地盘换了」是纯噪音，还要占压缩预算。这一轮只记起点；
+     * 2. **`history.length === 0` —— 历史被整体换过。** `compact()` / `resume()`
+     *    会换掉这个数组，而 `lastWorkDir` 活在实例上、换不掉。**这一条不是第 1 条
+     *    的重复**：第一轮之后再撞上空历史，说明前面那几轮已经不在记录里了，
+     *    那时这句话指着一段不存在的对话。
+     *
+     * 旧目录**刻意不印**：`lastWorkDir` 只是这个进程记的一笔（起点是 null，见它的
+     * ⚠️），而模型真正需要的是「此后按哪个目录算」。印一个我们其实没记准的旧路径，
+     * 比不印更糟。
+     */
+    private markWorkspaceHandoff;
     /** 一次性执行并拿最终文本（CLI 单次问答用） */
     once(userMessage: EpochUserContent, opts?: RunOptions): Promise<{
         text: string;
@@ -1358,8 +1511,131 @@ interface CommandWiring {
 declare function wireCommands(opts: WireCommandsOptions): CommandWiring;
 
 /**
- * `hostCapabilities` —— 嵌入宿主往能力清单里塞自己的专家 / 技能
- * （[方案 44 §2.1](../../../docs/verify/VERIFY_RECORD-44-host-capability-list.md)）。
+ * 进程级事件观测口（方案 61 PR-1）—— 让「一帧都没发」这句话**说得出口**。
+ *
+ * ## 这一格在补什么
+ *
+ * 在它之前，`AgentEvent` 没有「存在」这个概念，只有「被某个 for-await 吃掉了」：
+ * `AgentSession.run()` 是**单消费者** async generator（`server/src/hub.ts` 明写），
+ * 三条消费路（TUI / web 的 hub / `once()`）各自独占一个 for-await。于是
+ * 「这条路一帧 `AgentEvent` 都没发」这种断言**做不出真断言** —— 只能退而断
+ * 「事件可见的副作用没变」（跑过一轮的话历史会长、落盘会多）。那条代理断言挡得住
+ * 「utility 偷偷建了个会话」，挡不住「发了一帧没人收的事件」，
+ * 原文在 [VERIFY_RECORD-59 §十 #1](../../../docs/verify/VERIFY_RECORD-59-host-outlets.md)。
+ *
+ * 这个文件就是那个「存在」：`run()` 每产出一帧、**yield 之前**投递一份到这里。
+ *
+ * ## 它**不是**推式化
+ *
+ * `run()` 是拉式的，事件只在有人迭代时产生。这里不改变这一点 —— 发布点写在
+ * yield 之前，语义是「**产生了一帧**就投递」，不是「**主动广播**」。
+ * 没有人跑 `run()`，总线上一帧都不会有，这和今天的直觉一致。
+ *
+ * ## 四条形状判据
+ *
+ * 1. **进程级，不是 runtime 级。** 这是一个模块级单例：同一个进程里
+ *    `buildRuntime()` 建了几份，`EpochRuntime.events` 拿到的都是**同一个**总线。
+ *    这不是省事，是这一格存在的理由 —— 要断的那句话是「**任何**会话一帧都没有」，
+ *    而 runtime 级的总线答不出「别人那个 runtime 偷偷跑了一轮」。
+ * 2. **投递语义：同步 + 订阅者自律。** 回调同步执行，跑慢了会拖慢 `run()`。
+ *    **不许在这里加队列** —— 加队列等于引入「掉队订阅者的积压」这个新问题，
+ *    而今天的三个订阅者（测试 / 诊断 / 宿主）都不是重活。要做重活的宿主自己
+ *    在回调里往自己的队列里塞一条就走。
+ * 3. **零订阅零开销。** {@link ProcessEventBus.publish} 的**第一条语句**是
+ *    `size === 0` 的一次检查，之后再无分配 —— 投递给订阅者时也不构造信封
+ *    （回调签名是两个入参，见 {@link AgentEventSubscriber}）。这条由
+ *    `__tests__/event-bus.test.ts` 里那道扫源码的门禁钉住，不是靠这段注释。
+ * 4. **订阅者抛错不许炸 `run()`。** catch 住、{@link AgentEventBus.deliveryFailures}
+ *    上记一笔、下一个订阅者照常收。
+ *
+ * ## 为什么这条路上一个投影都没有（核过 `serialize.ts`，2026-08-25）
+ *
+ * [serialize.ts](./serialize.js) 做的是「摘闭包 → 换 `requestId`」，它的前提是
+ * **要过进程边界**（`structuredClone` 对函数直接抛 `DataCloneError`）。本总线整条
+ * 只在进程内（方案 61 §七：跨进程不在范围里），闭包原样递过去才是对的。
+ * 于是这条路上的投影是**零个**，不是第二个 —— 方案 §八 第 3 条那句「不许抄两份
+ * 投影」在这里是以「一份都不做」满足的。
+ *
+ * 同理**不复用 hub 的 `WireEnvelope`**：那上面 `seq` 是断线续传的游标、`ts` 上钉着
+ * 「每产出一个信封恰好读一次挂钟」的不变量，两条本总线一条都答不上
+ * （它不缓冲、不发号、不读钟）。
+ *
+ * **要跨进程旁听的宿主，自己在订阅回调里调一次 `toSerializable()`** ——
+ * 那才是复用的正确姿势：一份投影，两个调用点。
+ *
+ * ## 和 server hub 的 `observe()` 是两条不同的支流，别合并
+ *
+ * `observe()`（方案 54 §三）挂在 hub 的**广播层** —— wire 帧、序列化之后，
+ * 因此只有「由 hub 驱动」的会话上得了它。本总线挂在 `run()` 的产出处，
+ * TUI 驱动的会话、宿主自己驱动 `run()` 的会话都在。两者的取舍写在
+ * [docs/EMBEDDING.md](../../../docs/EMBEDDING.md) §13.5 那张表上。
+ */
+
+/**
+ * 一个旁听者。
+ *
+ * ## 为什么是两个入参，不是一个 `{ sessionId, event }` 信封
+ *
+ * 因为信封是一次**分配**。这条路上每一帧都会走一次，而它唯一的职责是把
+ * 「哪个会话」捎上 —— 为此在每帧上造一个对象，等于让「有人在听」这件事
+ * 变成 `run()` 的一笔固定成本。两个入参之后，**有没有订阅者都不分配**，
+ * 于是判据 3（零订阅零开销）不需要在「零」和「非零」之间讲两套话。
+ *
+ * ⚠️ **`event` 是原对象，不是副本。** `approval-request` / `question` 两种帧上
+ * 带着 `respond` 闭包，旁听者**够得着它**：
+ *
+ * > **不许调。** 那是消费者（跑 for-await 的那一位）的事。旁听者调了，
+ * > 用户面前那个审批框就会在没人点的情况下自己有了答案 —— 而那正是
+ * > `QuestionRelay` 拆成独立一个类要防的那件事（「没人答」的唯一合法表达是
+ * > `skipped`，不是一个编出来的答案）。
+ *
+ * 想改事件内容同理：改的是消费者手里那一份。旁听是**只读**的。
+ */
+type AgentEventSubscriber = (event: AgentEvent, sessionId: string) => void;
+/**
+ * 进程级事件观测口的对外面 —— 宿主拿到的是 `EpochRuntime.events`。
+ *
+ * **刻意只有读和订阅，没有 `publish`。** 发布点只有一个（`AgentSession.run()`），
+ * 把它开给宿主等于让「总线上有一帧」不再蕴含「真的产生了一帧」，
+ * 而那正是这一格全部的价值。
+ */
+interface AgentEventBus {
+    /**
+     * 订阅**本进程所有会话**的事件。
+     *
+     * 不带过滤参数是拍过的（方案 61 §八 第 2 条，2026-08-25 拍板「不做」）：
+     *
+     * - 判据一：**过滤一行就能自己写**（`if (sessionId !== mine) return`），
+     *   而总线替你做等于多出一套「传了一个不存在的 sessionId 会怎样」的语义；
+     * - 判据二（更硬的那条）：**第一批订阅者要的恰恰是不过滤。**
+     *   59 §十 #1 那条真断言问的是「**任何**会话一帧都不能有」——
+     *   有了过滤参数，那条用例就会被写成「过滤引导会话 → 零帧」，
+     *   于是它又变回一条代理断言（挡不住「utility 偷偷开了第二个会话」）。
+     *
+     * @returns 退订。**幂等** —— 多调几次不会误删后来注册的同一个函数（同 `observe()`）
+     */
+    subscribe(fn: AgentEventSubscriber): () => void;
+    /** 现在有几个旁听者。宿主诊断面板用；也是「退订真的退了」的锚 */
+    readonly subscriberCount: number;
+    /**
+     * 订阅者抛过几次错（累计，进程级）。
+     *
+     * 有这一格是因为**吞掉的错必须留个数**：订阅者抛错不许炸 `run()`（判据 4），
+     * 但「不炸」和「什么都没发生」是两件事 —— 没有这个数的话，一个每帧都抛的
+     * 旁听者在任何一处都看不出来。
+     *
+     * ⚠️ **只有数，没有日志。** 总线是模块级单例，它够不着 `buildRuntime({ logger })`
+     * 注入的那一路（一个进程里可能建过好几份 runtime，各带各的 logger），
+     * 而库代码不许自己往 stderr 写（EMBEDDING §3「`logger` —— 库不写 stderr」）。
+     * 想知道是哪一次抛的，宿主在自己的回调里包一层 try/catch —— 那儿才有上下文。
+     */
+    readonly deliveryFailures: number;
+}
+
+/**
+ * `hostCapabilities` —— 嵌入宿主往能力清单里塞自己的专家 / 技能 / 连接器 / 工具
+ * （[方案 44 §2.1](../../../docs/verify/VERIFY_RECORD-44-host-capability-list.md)、
+ * 方案 59 §四）。
  *
  * ## 为什么另开一路，而不是扩 `PluginArtifacts`
  *
@@ -1416,31 +1692,73 @@ declare function wireCommands(opts: WireCommandsOptions): CommandWiring;
  *
  * **别把这句话和「注入进去的东西是死的」混起来读。** `EpochRuntime.skills` 是个
  * getter，理由是**引擎自己会改它**（`SkillLearner` 在会话里新学）—— 和「谁能往里
- * 塞」无关。宿主注入的技能照样进索引、照样被 `skill_view` 读、照样被 `SkillLearner`
- * 记有效性。它只是**只读**（`SkillSystem.requireWritable` 的第三档），而那说的是
- * CRUD，不是生命周期。
+ * 塞」无关。宿主注入的技能照样进索引、照样被 `skill_view` 读、被读到时照样
+ * `matchCount++`。它只是**只读**（`SkillSystem.requireWritable` 的第三档），
+ * 而那说的是 CRUD，不是生命周期。
+ *
+ * ⚠️ **这里原来写的是「照样被 `SkillLearner` 记有效性」，那一句是假的**，而它是
+ * 对外契约上的假话（宿主会照它做产品决定）。两处都不成立：`SkillLearner` 只写
+ * `SKILL.md`，它压根不碰统计；而 `effectiveness` 只由 `SkillSystem.feedback()` 改，
+ * 那个方法从引入那天起就没有生产调用者，读它的 `maintain()` 同样没有 ——
+ * 于是每条技能的评分从加载到进程结束恒为初值 1，宿主拿它排序 / 筛选拿到的是常量。
  *
- * ## 连接器那一样（PR-2，2026-08-17）：**前缀用 `__` 不是 `:`**
+ * **2026-08-25 那一整套删了**（`feedback()` / `maintain()` / `effectiveness` /
+ * 三个反馈计数），所以宿主今天不会再看到那个字段 —— 它不是「变成常量」，
+ * 是不存在。`SkillStats` 只剩 `matchCount` / `lastUsedAt` 两格，
+ * 由 `skill_view` 那条路写。判据在那个接口的 JSDoc 上，
+ * 出处 `docs/verify/VERIFY_RECORD-skill-index-not-wired.md`。
  *
- * 三样里只有它拼出来的名字会**上网线进 provider** —— server 名是工具名的一部分
- * （`mcp__<server>__<tool>`），而带 `:` 的工具名被 provider 硬拒（实测，判据全文
- * 在 `McpServerStatus.source` 的 JSDoc 上）。所以三样分两种拼法：
+ * ## 连接器与工具那两样：**前缀用 `__` 不是 `:`**
+ *
+ * 四样里只有这两样拼出来的名字会**上网线进 provider** —— server 名是工具名的
+ * 一部分（`mcp__<server>__<tool>`），而宿主注入的工具**它自己就是工具名**；
+ * 带 `:` 的工具名被 provider 硬拒（实测，判据全文在 `McpServerStatus.source`
+ * 的 JSDoc 上）。所以四样分两种拼法：
  *
  * | 注入的 | 拼出来的名字         | 为什么                                        |
  * | ------ | -------------------- | --------------------------------------------- |
  * | 专家   | `acme:triage`        | 角色名只在我们进程里当键用，不进 provider      |
  * | 技能   | `acme:<分类>/<名字>` | 同上                                          |
  * | server | `acme__github`       | **会**变成 `mcp__acme__github__<工具>` 发出去 |
+ * | 工具   | `acme__list_jobs`    | **它自己就是工具名**                          |
  *
- * ⚠️ 别拿上面两行去类推第三行 —— 那条路今天就是红的。反过来也别为了长得一致把
- * 三样统一成 `__`：`:` 在角色 / 技能那边是**已经在跑**的形状（插件那条路早就这么
+ * ⚠️ 别拿前两行去类推后两行 —— 那条路今天就是红的。反过来也别为了长得一致把
+ * 四样统一成 `__`：`:` 在角色 / 技能那边是**已经在跑**的形状（插件那条路早就这么
  * 拼），改它等于改一批用户手上已经生效的名字。
  *
- * 📮 **没做、也够不着的一笔**：provider 那条正则连着限长 128
+ * ## ⚠️ 工具名这一格收得比 server 名**松**：它允许 `_`（方案 59 §四）
+ *
+ * 另外三样卡的都是 `AGENT_ROLE_NAME_PATTERN`（`[a-z0-9][a-z0-9-]*`），工具卡的是
+ * {@link HOST_TOOL_NAME_PATTERN}（`[a-z0-9][a-z0-9_-]*`）。差的就是一个下划线，
+ * 而这一格不是放宽标准，是**那条禁令在这一格上没有理由**：
+ *
+ * | 这一段在名字的哪儿 | 后面还有分隔符吗                     | 于是 `_` |
+ * | ------------------ | ------------------------------------ | -------- |
+ * | server 名          | 有 —— `mcp__<server>__<工具>` 还要再切一刀 | **禁** —— 放过去 `__` 就有第二种读法 |
+ * | 宿主注入的工具名   | **没有** —— 它是整个名字的末段        | 允许     |
+ *
+ * `namespace` 那一格照旧禁 `_`，所以 `<namespace>__<工具名>` 按**第一个** `__`
+ * 切开永远只有一种读法 —— 这条不变式是 namespace 那张正则守着的，不是工具名这张。
+ *
+ * 反过来禁掉 `_` 的代价很具体：全仓每一个工具都是 snake_case（`file_read` /
+ * `session_search` / `ask_user_question`），宿主照着写必然写 `list_jobs`，
+ * 然后拿到一条「名字不合法」——**宿主注入的工具会成为全 product 里唯一
+ * 不能用 snake_case 的一批**，而挡住它换不来任何一条不变式。
+ *
+ * 📮 **工具名限长 128 那两格，2026-08-24 已治**（判据全文在
+ * VERIFY_RECORD-59 §十 第 5 条）：provider 那条正则连着限长 128
  * （`^[a-zA-Z0-9_-]{1,128}$`），而宿主注入让工具名多出一段 `<namespace>__`。
- * 真撞上的话表现是 provider 拒掉整份工具表，不是只拒那一个 —— 但工具名要连上
- * server 之后才知道，这一层拦不住。要治得在 `registerMcpTools` 注册时逐个量长度，
- * 那会连用户自己那批一起改判，超出这一轮的范围。
+ * 超长撞上的表现是 provider 拒掉**整份**工具表，不是只拒那一个。
+ *
+ * | 哪一格 | 量的是什么                    | 在哪量（**同一份实现**）                                        |
+ * | ------ | ----------------------------- | --------------------------------------------------------------- |
+ * | server | `mcp__<ns>__<server>__<工具>` | `registerMcpTools` —— 名字要连上 server 之后才齐，这一层量不出来 |
+ * | 工具   | `<ns>__<工具名>`              | `build.ts` 的 3.4c（注册那一刻）                                |
+ *
+ * 两格共用 {@link dropOverlongToolNames}：超长的那一条**只跳过它自己**并报一条
+ * 指名道姓的诊断 —— **早报而不是等 provider 拒**，口径同「坏的那一条只跳过它
+ * 自己」（留着它等于拿一条注定不能用的工具换整份工具表陪葬）。分开做等于让
+ * 同一条不变式有两份实现，而那正是这个文件头到处在防的事。
  */
 
 /**
@@ -1500,13 +1818,15 @@ interface HostAgentRole {
  *     roles: [{ name: 'triage', description: '分拣工单，只读' , tools: ['file_read'] }],
  *     skillDirs: [join(app.getAppPath(), 'resources', 'skills')],
  *     mcpServers: [{ name: 'github', transport: 'http', url: 'http://127.0.0.1:3456/mcp' }],
+ *     tools: [listJobsTool], // name: 'list_jobs' → `acme__list_jobs`
  *   },
  * });
  * // → 专家叫 `acme:triage`，技能叫 `acme:<分类>/<名字>`，server 叫 `acme__github`
- * //   （工具因此是 `mcp__acme__github__<工具>`），三样都标着 host 来源
+ * //   （工具因此是 `mcp__acme__github__<工具>`），进程内工具叫 `acme__list_jobs`，
+ * //   四样都标着 host 来源
  * ```
  *
- * 三格给不给互相独立；三格都不给（或者整个选项不给）时**一行都不跑**，
+ * 四格给不给互相独立；四格都不给（或者整个选项不给）时**一行都不跑**，
  * 连一条诊断都不多 —— 老调用方逐字节不变。
  */
 interface HostCapabilities {
@@ -1559,13 +1879,49 @@ interface HostCapabilities {
      *
      * 这一批会在**装配时真连**，和用户 `~/.epoch/mcp.json` 里那批共用同一份
      * `MCP_CONNECT_BUDGET_MS`（不是两份相加）。**不给宿主一个「要不要连」的
-     * 开关**：`## 可用工具` 那一段是按第一轮的工具表拼进 system prompt 的，
-     * 懒连意味着第一轮模型压根不知道这些工具存在，而「装完第一句话就用得上」
+     * 开关**：第一轮发给 provider 的那份工具 schema 数组是按**那一刻的注册表**
+     * 拼的，懒连意味着第一轮模型压根不知道这些工具存在，而「装完第一句话就用得上」
      * 正是宿主注入它们的理由。
+     *
+     * ⚠️ 2026-08-26 换了一次措辞：这里原来说的是「`## 可用工具` 那一段是按第一轮的
+     * 工具表拼进 system prompt 的」。那一段删了（判据在 core 的
+     * `SystemPromptSegments` 上），但**结论一个字没变** —— 顶上来的是 schema 数组，
+     * 它同样是第一轮那一刻取的快照。
      */
     mcpServers?: readonly McpServerConfig[];
+    /**
+     * 宿主**进程内**的工具（方案 59 §四）。收的就是 `EpochTool` 本体 ——
+     * 一个函数，不是一台 server、不是一条路径。
+     *
+     * 它替掉的是「宿主为了给引擎几个工具，先在自己进程里起一台 MCP server，
+     * 再让引擎绕一圈 HTTP 连回来」那条路。绕掉的不只是那一圈开销：
+     * `ToolContext` 停在我们进程里，JSON-RPC 请求上没有它，于是宿主的工具
+     * **拿不到 `sessionId`**（方案 59 §五）。进程内这条路上它天然就在。
+     *
+     * ⚠️ **`name` 写不带前缀的那半截**，前缀由这一层拼成 `<namespace>__<name>`。
+     * 名字卡 {@link HOST_TOOL_NAME_PATTERN}（`[a-z0-9][a-z0-9_-]*`）——
+     * 比另外三格多一个 `_`，判据（以及为什么这一格上放开 `_` 不破坏任何不变式）
+     * 在文件头那张表上。不合法的那一条**只跳过它自己**，其余照常注入。
+     *
+     * ⚠️ **在权限层它和别人一档，而这不是我们答应的一件事** ——
+     * 闸门在 `ToolExecutor.execute` 的第 2 步上，它对 `toolProvider.get()` 交回来
+     * 的**任何**工具过同一道 `checkPermission`，压根不知道工具是谁给的。
+     * 也就是说：宿主不会因为工具跑在同一个进程里就获得一条绕过审批的路。
+     * 想让自己那个工具免确认，走的是和别人一样的路（`annotations.readOnlyHint`
+     * / `operation` / 用户的权限规则），不是「我是宿主」。
+     *
+     * ⚠️ **装配时一次性**，同 `roles` / `skillDirs`：`ToolRegistry` 只有
+     * `registerTools`，没有「换掉某一个」的路（`unregisterBySource` 是按**来源
+     * 整批**撤，给 MCP 那条全量刷新用的，不是单点替换）。宿主 ship 了哪些工具是
+     * 它的构建期属性 —— 要多一个就是下一次 `buildRuntime()`。
+     *
+     * ⚠️ **撞名保住我们自己的**：内置和插件工具先注册，这一批后注册，
+     * 于是撞上的时候赢的是我们那个（判据同 MCP 那批，`ToolRegistry.addTool`
+     * 先注册的赢）。拼了 `<namespace>__` 之后实际撞不着，但规则不能留空。
+     */
+    tools?: readonly EpochTool[];
 }
-/** 一次注入的产物。三样都可能是空数组，那时装配层什么都不用做 */
+/** 一次注入的产物。四样都可能是空数组，那时装配层什么都不用做 */
 interface HostCapabilityWiring {
     /** 已经拼好前缀、`source` 填死 `'host'` 的角色表 */
     roles: AgentRole[];
@@ -1580,6 +1936,14 @@ interface HostCapabilityWiring {
      * 字段，用户就能在自己的 `mcp.json` 里给自己那台贴上宿主的标。
      */
     mcpServers: McpServerConfig[];
+    /**
+     * 已经拼好 `<namespace>__` 前缀的工具。
+     *
+     * **这里也不带来源** —— 同 {@link mcpServers}：来源是注册那一步填的
+     * （`registry.registerTools(tools, 'host')`），而 `EpochTool` 上压根没有那一格，
+     * 于是「宿主自己写 source」这件事在类型上说不出口。
+     */
+    tools: EpochTool[];
 }
 /**
  * 校验 + 拼前缀。**不抛** —— 坏的那一条只跳过它自己，其余照常进来。
@@ -1589,6 +1953,79 @@ interface HostCapabilityWiring {
  */
 declare function wireHostCapabilities(caps: HostCapabilities | undefined, diags: DiagnosticSink): HostCapabilityWiring;
 
+/**
+ * 宿主预置的插件市场 —— **装配时**那一半（方案 59 §六 E1）。
+ *
+ * ```ts
+ * buildRuntime({ hostMarketplaces: { sources: ['/app/resources/market'] } })
+ *   →  把那份 `epoch-marketplace.json` 接进 `marketplaces.json`
+ *   →  之后 `runtime.plugins.search()` 才有东西可搜
+ * ```
+ *
+ * 运行期那六个动词（列 / 搜 / 预览 / 装 / 更新 / 卸）在
+ * [plugin-control.ts](./plugin-control.ts)。**刀口按时机下**：这个文件回答
+ * 「装配那一刻要不要把这份清单接上、接不上说什么」，那个文件回答
+ * 「用户点了一下之后发生什么」—— 两者的失败形态和呈现通道都不同
+ * （这边进启动诊断，那边是返回值）。
+ *
+ * ## 一、⚠️ 这一条**会落盘**，而 `hostCapabilities` 不会 —— 两者不是同一件事
+ *
+ * `hostCapabilities` 的判据是「宿主 ship 的东西是这一程的运行期事实，一个字节
+ * 都不落盘」。这一条反过来，理由很具体：**市场记录是「装插件时去哪儿查」的索引**，
+ * 它必须和用户自己 `epoch plugin marketplace add` 加的那些躺在同一张表里 ——
+ * 否则 `<市场>/<插件>` 这个引用形式会有两个答案。
+ *
+ * 落点是宿主自己的 `homeDir`（Electron 宿主给的是 `userData` 下的子目录），
+ * 不是用户的 `~/.epoch` —— 这一点让它和 `hostPreset`「替宿主把文件写到位」同档，
+ * 而不是「往用户的目录里塞东西」。
+ *
+ * ## 二、每次装配**重拉一遍**
+ *
+ * 已经加过同一个地址的走 `updateMarketplace`（重拉 + 整份替换），没加过的走
+ * `addMarketplace`。判据：宿主 ship 了什么是它的**构建期属性** —— 应用升级之后
+ * 那份清单跟着变，而一份留在上一版的快照是假话。
+ *
+ * ## 三、⚠️ 远程市场地址**默认拒**，而且是拒 + 说一句
+ *
+ * 取一份远端目录要发一次 HTTP（`github:` 走 raw.githubusercontent、`https://`
+ * 直接下），本地目录那档只是读一个文件。这条和插件本体那个开关是**同一个**
+ * {@link HostMarketplaces.allowRemote}，因为它们是同一个风险的两处出口 ——
+ * 完整判据（为什么本地和远程本来就该是两个开关）在
+ * [plugin-control.ts](./plugin-control.ts) 的文件头第三节。
+ *
+ * **坏的那一条只跳过它自己**，口径同 `wireHostCapabilities`：一条接不上不该让
+ * 其余的清单跟着消失。抢不到写锁那一档也收成诊断 —— 少一个预置市场比装配起不来
+ * 轻一个量级。
+ */
+
+/**
+ * 诊断里的模块名。**稳定标识，宿主拿它做分支**（见 `Diagnostic.module`）——
+ * 改它等于改契约。同 `HOST_CAPABILITIES_MODULE`。
+ */
+declare const HOST_MARKETPLACE_MODULE = "HostMarketplaces";
+/** 宿主预置的市场（方案 59 §6.4） */
+interface HostMarketplaces {
+    /**
+     * 市场地址，形状同 `epoch plugin marketplace add` 收的那一串：
+     * 本地目录（或那份 `epoch-marketplace.json` 本身）、`github:owner/repo`、
+     * `https://…/epoch-marketplace.json`。
+     *
+     * ⚠️ **后两种默认被 {@link allowRemote} 挡着**（取目录要发一次 HTTP）。
+     * 宿主 ship 的市场绝大多数是第一种 —— 一个躺在 `resources/` 里的 JSON。
+     *
+     * 每次装配都**重拉一遍**，判据见文件头第二节。
+     */
+    sources: readonly string[];
+    /**
+     * 放开远程 source（`github:` / `git+` / `npm:` / `https://`），**默认 false**。
+     *
+     * 它同时管两处，因为两处是同一个风险：{@link sources} 里的远程市场地址，
+     * 以及清单条目里解析出来是远程的那些插件。判据在
+     * [plugin-control.ts](./plugin-control.ts) 的文件头第三节。
+     */
+    allowRemote?: boolean;
+}
+
 /**
  * `hostPreset` —— 装配前替宿主把那几个文件落到位（[方案 54 §六](../../../docs/verify/VERIFY_RECORD-54-embedding-host-gaps.md)）。
  *
@@ -1732,6 +2169,33 @@ declare function applyHostPreset(opts: ApplyHostPresetOptions): Promise<void>;
  * 封闭集），模型那一层不许闭合。判据全文在 protocol 的 `wire-provider.ts` 上。
  */
 
+/**
+ * 一家 provider 的**显示名**。
+ *
+ * 十三家里十一家原样返回 `PROVIDER_INFOS` 里那个品牌名 —— 品牌名不翻。剩下两家的
+ * 显示名带一句注解（「本地」/「通用适配」），那半句该跟界面语言走，所以走 catalog。
+ *
+ * ## 为什么在 runtime 而不是 protocol 里
+ *
+ * 注解原来就挂在 `PROVIDER_INFOS[].label` 上，而 protocol 是零依赖层、够不着 `t()`
+ * —— 结果是一个把界面切成 English 的人在模型菜单上看到「Ollama (本地)」。
+ * runtime 是**两个消费方都够得着的最低那一层**：`epoch model` 那个向导（cli）和
+ * `GET /api/providers`（server）。放 core 也行，但 provider 目录这件事整个在这个
+ * 文件里，没必要再跨一层。
+ *
+ * ## 为什么是 `switch` 而不是查一张表
+ *
+ * `t()` 的 key 必须是**源码里看得见的字面量**：根 `__tests__/i18n-catalog.test.ts`
+ * 靠扫 `t('...')` 认「哪些 key 是活的」，key 一旦拼出来（`t(`provider.label_${type}`)`）
+ * 那两条会被判成死 key，门禁当场红 —— 而它红得对，因为那种写法下**catalog 里少一条
+ * 没人会发现**。同 `command-safety.ts` 那 66 条 `desc: () => t('danger.x')`。
+ *
+ * @param lang 这一次渲染用哪个语言。server 要按请求给（方案 58），cli 不给 = 进程语言
+ */
+declare function providerLabel(info: {
+    readonly type: ProviderType;
+    readonly label: string;
+}, lang?: Lang): string;
 /** 一个可挑的 provider。和网线那一份 `WireProviderOption` 逐字同形 */
 interface ProviderOption {
     type: ProviderType;
@@ -1807,11 +2271,285 @@ interface ModelCatalogOptions {
  */
 declare function buildModelCatalogControl(opts: ModelCatalogOptions): ModelCatalogControl;
 
+/**
+ * 「装一个插件」这个动作的**结局形状**，以及 preview → install 那两段的实现
+ * （方案 59 §六 E1）。
+ *
+ * 六个动词的控制面在 [plugin-control.ts](./plugin-control.ts)，装配时把宿主预置
+ * 的市场接上在 [host-marketplaces.ts](./host-marketplaces.ts)。**刀口按题目下**：
+ * 这个文件从头到尾只答一个问题 —— 「这一次安装到底成没成，没成是哪一档」。
+ *
+ * ## ⚠️ 两段之间那条缝，用 token 缝上
+ *
+ * 判据逐字同 core 的 [skill/import.ts](../../core/src/skill/import.ts) 文件头：
+ * `preview()` 和 `install()` 是两次调用，中间目录可能被改过 —— 于是
+ * 「你确认的」和「真装上的」是两份。
+ *
+ * 落法**借的是 core 自己那个 `confirm` 回调**，而不是在这一层重新扫一遍目录：
+ *
+ * - `preview()` = 跑一发 `installPlugin`，`confirm` 里把那份预览接走然后回 `false`
+ *   —— core 那条路上 `confirm` 回 false 就整件事作废、staging 清干净，
+ *   所以它天然是「一个字节都不写」；
+ * - `install()` = 再跑一发，`confirm` 里对着**这一次真正要装的那份预览**重算摘要，
+ *   对不上就回 `false`。也就是说比对发生在**要落地的那一刻**，不是比对两份快照。
+ *
+ * ⚠️ 摘要算的是**那一屏上的东西**（清单名 / 版本 / 来源 / 扩展物盘点），
+ * **不是文件内容的哈希**：本地那一档装的是软链，它的内容本来就是活的 ——
+ * 对一份随时会变的东西做完整性检查，只会让一条正常的开发路径随机失败。
+ */
+
+/**
+ * 一次拒绝的档位。**每一档对一个不同的下一步**，合并任意两档都会让上层拿同一句话
+ * 去答两个问题 —— 判据同 `RoleAddOutcome` 那五档。
+ *
+ * | 档                | 说的是                                             | 下一步         |
+ * | ----------------- | -------------------------------------------------- | -------------- |
+ * | `unknown-ref`     | 不是 `<市场>/<插件>`，或者那个市场 / 插件不存在    | 换个引用       |
+ * | `remote-disabled` | 它是远程 source，而 `allowRemote` 关着             | 宿主去开那个开关 |
+ * | `conflict`        | 已经装过同名的                                     | 先卸载         |
+ * | `stale-token`     | 你确认的和现在要装的对不上，**一个字节都没写**     | 重看一次预览   |
+ * | `not-installed`   | `update` / `uninstall` 收到一个没装过的名字        | 先装上         |
+ * | `nothing-to-do`   | **不是出错**：软链装的插件一直是最新的，没得更新   | 什么都不用做   |
+ * | `failed`          | 其余（拉不到 / 清单坏了 / 写记录时被别的进程抢先） | 看 `detail`    |
+ */
+type PluginRefuseReason = 'unknown-ref' | 'remote-disabled' | 'conflict' | 'stale-token' | 'not-installed' | 'nothing-to-do' | 'failed';
+/** 拒绝的共同形状。`preview` 有值时说明失败发生在读完清单之后，界面可以照样画那一屏 */
+interface PluginRefusal {
+    ok: false;
+    reason: PluginRefuseReason;
+    detail: string;
+    preview?: InstallPreview;
+}
+type PluginPreviewOutcome = {
+    ok: true;
+    preview: InstallPreview;
+    /** 拿去 `PluginControl.install`。判据见文件头 */
+    token: string;
+} | PluginRefusal;
+type PluginInstallOutcome = {
+    ok: true;
+    record: PluginRecord;
+    preview: InstallPreview;
+} | PluginRefusal;
+
+/**
+ * 插件的**宿主控制面** —— 「宿主替用户装一个扩展物」那条路（方案 59 §六 E1）。
+ *
+ * ```
+ * buildRuntime({ hostMarketplaces: { sources: ['/app/resources/market'] } })
+ *   →  runtime.plugins.search('office')      // 从宿主预置的那份清单里挑
+ *   →  runtime.plugins.preview('acme/office')  // 「将安装什么」，一个字节都不写
+ *   →  runtime.plugins.install('acme/office', token)
+ *   →  runtime.plugins.pendingRestart === true  // ⚠️ 还没生效，见第二节
+ * ```
+ *
+ * core 那一层（[marketplace.ts](../../core/src/plugin/marketplace.ts) /
+ * [install.ts](../../core/src/plugin/install.ts) / `lifecycle.ts` / `store.ts`）
+ * 早就完整了，这个文件**一条安装逻辑都没有** —— 它只做三件只有装配层做得了的事：
+ * 把「这一程加载了谁」和「盘上装了谁」对起来、守住下面第三 / 第四节那两道闸、
+ * 记住「装完了没生效」这一格。装配那一刻把宿主预置的市场接上是隔壁
+ * [host-marketplaces.ts](./host-marketplaces.ts)（刀口按时机下，判据在那个文件头）。
+ *
+ * ## 一、为什么不塞进 [build.ts](./build.ts)
+ *
+ * 判据逐字同 [session-model.ts](./session-model.ts) / [role-write.ts](./role-write.ts)
+ * 单开那一条：**它有一整套自己的判据要有个落点**（下面四节，每一节都不是偏好）。
+ *
+ * ## 二、⚠️ **不做热加载 —— 装完要重建 runtime 才生效**，而这是对外承诺的形态
+ *
+ * 不是「还没做」，是做不到而且不该假装做得到：hook 和角色表**没有热加载路径**，
+ * 而 [ToolRegistry](../../core/src/tools/registry.ts) 压根没有反注册 / 替换 API。
+ * 补一半的表现是「有些扩展物立刻生效、有些要重启」，而用户没有任何办法分辨。
+ *
+ * 所以这一层给的是一格 {@link PluginControl.pendingRestart}，**怎么说是宿主的决定**
+ * （它比我们知道自己的用户能不能接受重启）。
+ *
+ * ### 而「重建一次就能拿到新装的扩展物」**成立**，理由不是碰巧
+ *
+ * `loadPlugins` **一个字节的 JS 都不执行**：六类扩展物（命令目录 / 角色 / 技能目录 /
+ * `hooks.json` / `settings.json` / `mcp.json`）全是**路径和数据**，插件里那个
+ * `tools/` 目录我们认得出来但刻意不加载（[loader.ts](../../core/src/plugin/loader.ts)
+ * 的 `collect`：「第一版刻意不在 epoch 进程里跑第三方代码」）。
+ *
+ * **没有模块缓存这一层，是这条路能走通的全部理由。** 如果插件是 JS，
+ * `import()` / `require` 的缓存会让「同一路径、新内容」在重建之后**照样是旧的那份** ——
+ * 而那是一个「服务、日志、状态码、诊断全部正常，一个字不报」的失败形态。
+ * 这一句不是附注，删掉它这一整条路就没有判据了。
+ *
+ * ## 三、⚠️ 本地 source 先行，远程默认关 —— 因为风险不是同一个量级
+ *
+ * | source                     | 装的时候真的会发生什么      |
+ * | -------------------------- | --------------------------- |
+ * | 本地目录                   | 建一条**软链**              |
+ * | `github:` / `git+https:`   | spawn `git clone --depth 1` |
+ * | `npm:`                     | spawn `npm pack` + 解包     |
+ * | `https://….zip`            | 下载 + 解压                 |
+ *
+ * 后三档要起子进程或者拉网，第一档只是 `symlinkSync` —— 两者本来就该是两个开关。
+ * 所以 `HostMarketplaces.allowRemote` **默认 false**，而被它挡下的那一条
+ * **是拒绝 + 一句话，不是静默跳过**：静默的表现是搜索里明明有那一条、点了没反应。
+ *
+ * ## 四、⚠️ 这一层**只收 `<市场>/<插件>`，收不了一条路径** —— 比 `skill-import` 更紧
+ *
+ * {@link PluginControl.preview} / {@link PluginControl.install} 的入参上**没有**
+ * 「source」这个东西，只有一个市场引用。于是「指一条任意路径装一个插件」这件事
+ * 在这个形状下**说不出口** —— 同 `HostAgentRole` 少一个 `source` 的手法，
+ * 不是靠 review 盯住的，是编译期的事。逐条对着今天那条最像的路
+ * （`server/src/skill-import.ts`）：
+ *
+ * | 判据             | `skill-import` 今天       | 这一条                     |
+ * | ---------------- | ------------------------- | -------------------------- |
+ * | 能不能传字节     | 不能（只收路径）          | 不能                       |
+ * | 能不能指任意路径 | **能**（收一个任意 path） | **不能**（只能从清单里挑） |
+ * | 清单是谁放的     | —                         | 宿主主进程 / 用户自己敲的  |
+ *
+ * ⚠️ 「清单」= `~/.epoch/marketplaces.json` 里那些，也就是**宿主预置的**加上
+ * **用户自己 `epoch plugin marketplace add` 加的**。后者照样算数：那是用户在自己
+ * 机器上做的决定，和宿主主进程同一档。这条路唯一挡死的是「谁都没列过的那个东西」——
+ * 要装清单外的插件，路仍然在，只是**在命令行上**（那一问的闸门只该有一份）。
+ *
+ * ## 五、preview → install 是两段，中间那条缝用 token 缝上
+ *
+ * {@link PluginControl.preview} 回一个**内容摘要**，install 那一发对着**这一次
+ * 真正要装的那份预览**重算一遍，对不上就整件事作废（`stale-token`）。
+ * 实现和完整判据（含「为什么**不**哈希文件内容」）在
+ * [plugin-install.ts](./plugin-install.ts) 的文件头 —— 这一层只负责在调它之前
+ * 把上面第三 / 第四节那两道闸过掉。
+ */
+
+/**
+ * 装着的一个插件在宿主眼里的样子。
+ *
+ * 就是 `plugins.json` 里那条记录，**多一格 {@link active}** —— 而那一格是这个
+ * 列表存在的全部理由，见它自己的注释。
+ */
+interface PluginListEntry {
+    name: string;
+    version: string;
+    source: string;
+    sourceType: PluginSourceType;
+    path: string;
+    /** 本地目录装的是软链（改源码、重建即生效），其余是真实拷贝 */
+    linked: boolean;
+    enabled: boolean;
+    installedAt: number;
+    /** 从市场装的话是市场名 */
+    marketplace?: string;
+    /**
+     * **这一程真的加载了它吗。**
+     *
+     * `false` 有两种成因，宿主要分开说：这一程刚装上（要重建才生效，见
+     * {@link PluginControl.pendingRestart}），或者它被停用 / 版本不符 / 目录没了
+     * （那时启动诊断里有一条指名道姓的）。
+     *
+     * 少了这一格，一个刚装完的插件在列表里和一个正在生效的插件长得一模一样 ——
+     * 而那正是「点了半个反应」的形态。
+     */
+    active: boolean;
+    /**
+     * 六类扩展物各贡献了几条。**只有 {@link active} 那些有** ——
+     * 没加载的插件我们没有数过它，给一个 0 会被读成「它什么都不带」。
+     */
+    counts?: PluginCounts;
+}
+/** 市场里的一条，加上「在当前开关下装不装得上」 */
+interface PluginSearchHit {
+    marketplace: string;
+    entry: MarketplaceEntry;
+    /** `<市场>/<插件>` —— 直接喂给 {@link PluginControl.preview} */
+    ref: string;
+    /** 解析出来的来源档位；这一条的 `source` 看不懂时 `undefined` */
+    sourceType?: PluginSourceType;
+    /**
+     * 在**当前**开关下装得上吗。`false` = 它是远程 source 而远程档关着。
+     *
+     * ⚠️ **不从结果里剔掉它**，判据同方案 59 §2.3 那条「如实回报比替调用方决定诚实」：
+     * 剔掉的话界面上少一条，而用户唯一能得出的结论是「这个市场里没有那个东西」。
+     * 该画成不可点 + 说出原因。
+     */
+    installable: boolean;
+}
+type PluginActionOutcome = {
+    ok: true;
+    detail: string;
+} | PluginRefusal;
+/**
+ * 收窄到六个动词的控制面。
+ *
+ * 只有这六个，于是上层（`@epoch-agent/server` 那一页，方案 59 E2）**写不出**
+ * 「往任意路径装一个插件」和「改一条安装记录」—— 同 `McpControl` 只露
+ * `reconnect`、`SkillControl` 只露两个导入动作。
+ *
+ * ⚠️ 刻意**没有 enable / disable**（core 的 `setPluginEnabled` 在那儿摆着）：
+ * 那两个动作的正当性和「装 / 卸」不是一回事（停用一个插件会**静默拿掉**别人正
+ * 依赖的一批命令），要开得单独判一次。判据同 `RoleWriteControl` 只有 `add`。
+ */
+interface PluginControl {
+    /**
+     * 装着的插件。**读的是盘上那份记录**（`plugins.json`），不是这一程加载出来的
+     * 那张表 —— 否则刚装完的那个不会出现在列表里。两者的差就是
+     * {@link PluginListEntry.active}。
+     */
+    list(): PluginListEntry[];
+    /**
+     * 在**已加的市场**里搜。空关键词 = 列出全部（那是「里面有什么」的直接答案）。
+     *
+     * 纯本地：目录是加市场那一刻快照下来的，搜索一次网都不上。
+     */
+    search(keyword?: string): PluginSearchHit[];
+    /**
+     * 「将安装什么」。**一个字节都不写**，回的 `token` 拿去 {@link install}。
+     *
+     * @param ref `<市场>/<插件>`。**收不了一条路径**，判据见文件头第四节
+     * @param lang 这一次 `detail` 用哪个语言说。不给 = 进程语言。⚠️ 只影响回给这
+     *             一次调用的话，落到磁盘上的东西一个字都不受它影响
+     */
+    preview(ref: string, lang?: Lang): Promise<PluginPreviewOutcome>;
+    /**
+     * 真装。`token` 来自上一次 {@link preview}，对不上就拒（`stale-token`）。
+     *
+     * ⚠️ 装完**不会生效**，{@link pendingRestart} 会变成 `true`。
+     */
+    install(ref: string, token: string, lang?: Lang): Promise<PluginInstallOutcome>;
+    /**
+     * 「更新会带来什么」。同 {@link preview}，只是来源取自那条安装记录。
+     *
+     * ⚠️ 更新**也要过这一道**，不是多余的谨慎：新版本可以加 hook（会跑 shell 命令），
+     * 一个当初只带三条命令的插件更新之后可能带上一条 `PreToolUse`。判据逐字同
+     * CLI 的 `epoch plugin update` 为什么在非交互终端下拒绝无 `--yes` 运行。
+     */
+    previewUpdate(name: string, lang?: Lang): Promise<PluginPreviewOutcome>;
+    /** 按记录里的来源重装一遍。`token` 来自 {@link previewUpdate} */
+    update(name: string, token: string, lang?: Lang): Promise<PluginInstallOutcome>;
+    /**
+     * 卸载。**软链只解链，不删源码目录**（那是 core 的立场，这里不重判一次）。
+     *
+     * ⚠️ 卸完它就从 {@link list} 里消失了，但它这一程带进来的 hook / 命令
+     * **还活着** —— 同样要重建，见 {@link pendingRestart}。
+     */
+    uninstall(name: string, lang?: Lang): Promise<PluginActionOutcome>;
+    /**
+     * **这一程动过插件、而那些改动还没生效。**
+     *
+     * 一次成功的 install / update / uninstall 之后变 `true`，此后不再变回去 ——
+     * 让它变回去的唯一办法是 `dispose()` + 重新 `buildRuntime()`，那时是一个新的
+     * runtime，这一格从 `false` 开始。
+     *
+     * ⚠️ **它答的是「这一程」，不是「盘上有没有变化」**：另一个进程装的插件不会
+     * 让它变 true（这个 runtime 确实没变过），而那是对的 —— 这一格的消费方是
+     * 「我刚点完那一下，要不要提示用户重启」。
+     *
+     * ⚠️ 这一格从方案 59 §6.5 那一笔挪进来：**宿主自己就要判「装完了没」**，
+     * E2 那个页面只是它的第二个消费方。
+     */
+    readonly pendingRestart: boolean;
+}
+
 /**
  * 身份的写口在装配层的那一格 —— 「新建一个身份」（2026-08-18）。
  *
  * ```
- * runtime.roleWrite.add({name, description, prompt, tools, maxTurns})
+ * runtime.roleWrite.add({name, description, prompt, tools, skills, maxTurns})
  *   →  ~/.epoch/agents/<name>.md 落盘 + **这个进程当场认得它**
  * ```
  *
@@ -1871,6 +2609,15 @@ interface RoleAddInput {
     description: string;
     prompt?: string;
     tools?: readonly string[];
+    /**
+     * 技能索引白名单（2026-08-27）。**这一层原样透传，一个字都不校验** ——
+     * 和上面 `tools` 刻意不同，判据全文在 protocol 的 `WireRoleAddRequest.skills` 上，
+     * 一句话：工具表装配期定死，技能表**会话中途还会变**（`SkillLearner` 学一条就
+     * 往用户级目录里落一份），把「此刻没装」判成 400 是拒掉一个明天就成立的名字。
+     *
+     * 打错的那一档由启动诊断 `unknownRoleSkills()` 报，不在这条路上报。
+     */
+    skills?: readonly string[];
     maxTurns?: number;
 }
 /**
@@ -2369,6 +3116,18 @@ interface ScheduleCapability {
      * 不许写成「已启用」——那是这一整节唯一真正要守住的东西。
      */
     canRegister: boolean;
+    /**
+     * 底下那张表打开了没有（2026-08-26 补的一格）。
+     *
+     * `false` = `sessions.db` 打不开，这一片**整个没法用**：一条都列不出来、
+     * 一条都存不进去。界面上要说的是「读不出来」而**不是「这台机器上没有定时任务」**
+     * —— 后者是一句假话，判据同 `no-goal-store` 那一格（「503 而不是一份空清单」）。
+     *
+     * ⚠️ 和 `canRegister: false` 不是一回事，别合并成一个布尔：那一格是
+     * 「存得下但到点不会自己跑」（一个**降级**，路径 B 完全正当），
+     * 这一格是「什么都做不了」（一个**故障**）。两句话在界面上是两种画法。
+     */
+    storeAvailable: boolean;
 }
 /** 存下来了没有；注册成没成是另一半 */
 interface ScheduleSaveResult {
@@ -2380,6 +3139,15 @@ interface ScheduleSaveResult {
     registration?: RegisterOutcome;
 }
 interface ScheduleControl {
+    /**
+     * 底下那张 SQLite 表打开了没有。**同步的**，因为调用方要拿它当一道前置
+     * （服务端那九条端点在碰 store 之前就要判得出来，而 `capability()` 是 async）。
+     *
+     * ⚠️ **`false` 时下面每一个方法都会抛，不回空清单。** 这是刻意的：一份空清单
+     * 在界面上和「这台机器上没有定时任务」一模一样，而那是假话。抛出去的那一下
+     * 是给**没先看这一格**的宿主的 —— 响亮地坏掉比静静地说谎好。
+     */
+    readonly storeAvailable: boolean;
     list: () => ScheduleDefinition[];
     get: (id: string) => ScheduleDefinition | undefined;
     /** 某条任务最近几次运行，最新的在前 */
@@ -2424,10 +3192,34 @@ interface ScheduleControlOptions {
     /** 平台。可注入是为了让用例能验 Linux 那条「暂不支持」的路 */
     platform?: NodeJS.Platform;
 }
-/** 装一份控制面 + 它的关闭钩子（`dispose` 时要放掉 store 的引用计数） */
+/**
+ * 装一份控制面 + 它的关闭钩子（`dispose` 时要放掉 store 的引用计数）。
+ *
+ * ## ⚠️ 开库那一下**不许抛出这个函数**（2026-08-26 修的一条真 bug）
+ *
+ * `ScheduleStore` 开的是 `dbPath(homeDir)` —— 也就是 `sessions.db`，**和
+ * `SessionManager` / `TrackerDB` 同一个文件**。那两个都是套着 `safeInit` 开的
+ * （起不来就是 null + 一条诊断），而这一处原来是裸调的：于是那个文件打不开时
+ * `buildRuntime()` 整个抛，`epoch web` **退出码 1**，而不是起来之后让相关端点
+ * 各回自己那句「读不出来」。
+ *
+ * 那条 bug 是这么撞见的：方案 53 §6.9 想验会话候选端点的 503 `no-session-store`，
+ * 破坏 `sessions.db` 之后**进程根本起不来**，那条分支在真进程上永远走不到 ——
+ * 一个「起不来的东西挡住了另一个东西的降级路径」。根因和结论记在
+ * [RECORD-53 §6.9](../../../../docs/verify/VERIFY_RECORD-53-session-reference.md)。
+ *
+ * **为什么不是把 `EpochRuntime.schedules` 改成可为 null**（那样最像它那三个邻居）：
+ * 那是一处真破坏（宿主的 `runtime.schedules.list()` 当场编译不过），而
+ * `0.1.0` 2026-08-19 已经发出去了 —— 按 `.changeset/README.md` 那条现行规则要写
+ * `major`，而 major 传染给全组，十五个包一起进 `1.0.0`。为一条降级路径抬整个
+ * 产品的大版本号，代价和收益不成比例。所以这里选的是**加法**：字段照旧不为 null，
+ * 多一格 {@link ScheduleControl.storeAvailable} 说实话。
+ */
 declare function createScheduleControl(opts: ScheduleControlOptions): {
     control: ScheduleControl;
     dispose: () => void;
+    /** 开库失败时是那个异常，成功时 null。装配层拿它写那条诊断 */
+    openError: Error | null;
 };
 
 /**
@@ -2444,6 +3236,23 @@ interface PolicyDirStatus {
     /** 这个目录里加载到的 `[[rule]]` 条数。目录不存在就是 0 */
     ruleCount: number;
 }
+/**
+ * hook 的来源账（方案 50 PR-3 的 `epoch doctor` 要用）。
+ *
+ * 为什么要在这一层留住：`loadHookSources()` 的返回值原来在下一行就被
+ * `loadEntries(hooks.entries)` 吃掉了，只剩一个合并好的表。而 doctor 要答的问题
+ * 全在被吃掉的那一半里 ——「这几条 hook 分别来自哪个文件」。
+ *
+ * 方案 50 之后这个问题第一次变得非答不可：以前七成用户只有一份
+ * `~/.epoch/hooks.json`，现在我们会去读 **Claude Code 的三份**，
+ * 于是「我没写过这条命令，它为什么会跑」成了一个真会被问到的问题。
+ */
+interface HookStatus {
+    /** 逐个来源，按加载顺序。含**存在但因不受信任而没读**的那些（`skipped: true`） */
+    sources: HookSourceStatus[];
+    /** 项目级那几份因为工作区不受信任而整份没加载 */
+    projectSkipped: boolean;
+}
 /** 策略规则的来源账（方案 42 PR-3 的安全中心要用） */
 interface PolicyStatus {
     dirs: PolicyDirStatus[];
@@ -2570,6 +3379,14 @@ interface Services {
      * 「一个策略目录都没生效」是个真结论，null 会让调用方多一个分支去猜。
      */
     policy: PolicyStatus;
+    /**
+     * 这一次装配读了哪几份 hook 配置、每份贡献了几条、项目那几份是不是因为
+     * 不受信任整份没加载（方案 50 PR-3）。
+     *
+     * 和 {@link PolicyStatus} 是同一种东西的两个主题，摊在一屏里要说清区别：
+     * 策略规则管「这个工具碰这个路径算什么」，hook 是**会 spawn 子进程的命令**。
+     */
+    hook: HookStatus;
     /**
      * 已装插件带来的扩展物（方案 32）。**永远非 null** —— 没装过插件时是
      * `noPlugins()`，九个数组全空，调用方因此不用为「有没有插件」分支。
@@ -2881,7 +3698,17 @@ interface LiveSession {
      * 「不是本进程正在跑的那个」，而这个进程正握着它的检查点管理器（方案 30 §9.5）。
      */
     readonly checkpoints: CheckpointControl;
-    /** 这个会话绑在哪儿；没绑过 null */
+    /**
+     * 这个会话绑在哪儿；没绑过 null。
+     *
+     * ⚠️ **现读，不是装配那一刻的快照**（迟绑，2026-08-20）：`unbound` 那一档的
+     * 会话是先建出来、后由用户在输入框底栏那张 picker 里挑目录的
+     * （`POST /api/sessions/:id/workspace`），快照答不出那一次。
+     *
+     * 快照的失败形态有两个，而且都不会红：`create({workspace, reuse:true})` 找不到
+     * 那段刚刚绑上这个目录的会话（于是又建一段新的），以及 `delegate_task` 派出去的
+     * 子 agent 跑在启动目录里（`subRunner` 读的就是这一格）。
+     */
     readonly workspace: SessionWorkspace | null;
     /**
      * **这一条消息用哪个专家**（方案 57 §3.4，2026-08-17）。
@@ -3578,6 +4405,37 @@ declare function writeMcpServer(input: McpAddInput, opts?: {
 
 interface BuildToolsInput {
     homeDir: string;
+    /**
+     * `tools.deferMcp`（2026-08-26）。**开着才注册 `tool_search`。**
+     *
+     * ⚠️ 注册与否只看这个开关，**不看「当下有没有 Deferred 工具」** —— 这一步跑在
+     * `registerMcpTools()` 之前，那时一个 MCP 工具都还没进注册表，按数量判的话
+     * 它永远不注册。
+     *
+     * 反过来，关着时不注册也是判据：那时没有任何 Deferred 工具，一个搜什么都搜不到
+     * 的工具进了工具表，白占 token 还让模型多一条会失败的路。
+     */
+    deferMcp?: boolean;
+    /**
+     * `tools.mode`（方案 51 PR-1 / PR-2）。**`'both'` 和 `'code'` 才注册 `run_code`。**
+     *
+     * 不给 = `'tools'` 档 = 这一轮之前的行为逐字节相同（方案 51「默认关」）。
+     * 这一跳的缺省朝「关」是刻意的：一个嵌入宿主自己拼 `EpochConfig`、整段不写
+     * `tools` 的时候，它拿到的不该是一个能放大审批粒度的工具。
+     *
+     * `'code'` 比 `'both'` 多做一件事：**程序真能调的那些工具从模型的工具表里
+     * 切走**，改以一段生成的 SDK 声明进 system prompt。那一档不在这个函数里落实
+     * （判据见下面 `new ToolRegistry` 那一行）—— 它是 registry 的一格，因为注册
+     * 不止这一处。
+     */
+    toolMode?: 'tools' | 'both' | 'code';
+    /**
+     * 引导会话那一份放开集。**必须和 `buildSessionGuards` 拿到的是同一个实例** ——
+     * 各建一份的表现是：进程里注册的那个 `tool_search` 往 A 记，而引导会话的
+     * provider 读 B，于是「搜到了但工具没出现」，而两边都答得出「我干了我该干的」。
+     * 判据同 `permission` / `planState` 那条「引导会话拿到的就是进程那一份本体」。
+     */
+    bootstrapReveal?: ToolRevealState;
     trackerDb: TrackerDB | null;
     /**
      * 目标（方案 52 PR-3）。null = 会话库没起来 —— 那时 `goal` 工具**不注册**。
@@ -3589,6 +4447,16 @@ interface BuildToolsInput {
     goals: GoalService | null;
     memory: MemoryManager | null;
     sandbox: CodeSandbox | null;
+    /**
+     * 技能系统（`services.skill`）。null = 它初始化失败了（`safeInit` 降级成
+     * 「没有技能」）—— 那时 `skill_view` **不注册**，同 `todo` / `memory` 那几条。
+     *
+     * ⚠️ 反过来，**它在就注册，不管当下扫出来几条技能**（哪怕零条）。判据在
+     * `createSkillViewTool` 上：技能表会在会话中途变（`SkillLearner` 学一条就往
+     * 用户级目录里落一份），而工具表是装配期定的 —— 按「启动那一刻有没有技能」
+     * 决定注册与否的表现是，这一段会话里学到的东西这一段会话永远读不了。
+     */
+    skills: ISkillSystem | null;
     diags: DiagnosticSink;
     /**
      * web 搜索配置（方案 37）。**整段缺席也照样探测**：
@@ -3788,9 +4656,14 @@ interface McpServerBatch {
  *   `<namespace>__` 前缀）和插件带来的（PR-3，由 `wirePluginMcpServers` 拼好
  *   `<插件名>__` 前缀）。**和用户那批一样真连、共用同一份预算**（判据在
  *   {@link connectAllServers} 上），也一样在这个函数返回之前就把工具注册进
- *   `registry` —— 于是它们在**第一轮** system prompt 的 `## 可用工具` 里就在了。
- *   懒连的具体后果不是「稍微慢一点看到工具」：那一段是按第一轮的工具表拼进
- *   prompt 的，第二轮起 loop 重问工具表能自愈，第一轮不能。
+ *   `registry` —— 于是它们在**第一轮**就已经在模型的工具表里了。
+ *   懒连的具体后果不是「稍微慢一点看到工具」：那张表是按第一轮的注册表算出来的，
+ *   第二轮起 loop 重问工具表能自愈，第一轮不能。
+ *
+ *   📮 这段话 2026-08-26 之前写的是「在第一轮 system prompt 的 `## 可用工具` 里
+ *   就在了」。**结论一个字没变，坏的是凭据**：那段散文清单当天删了（它和发给
+ *   provider 的 schema 数组完全重复，判据在 `core` 的 `SystemPromptSegments` 上），
+ *   工具表现在只走 schema 那一条路。
  *
  *   ⚠️ **再来一批就往这个数组里加一个元素，不是加第五个参数** —— 方案 44 §2.2
  *   第 4 处逐字写着「这一处和宿主注入是同一个口子，别开两个」。PR-2 那一轮它还是
@@ -3799,7 +4672,9 @@ interface McpServerBatch {
  *
  *   **顺序即优先级**（先到的赢，重名的后来者跳过），判据在 {@link dropTakenNames}。
  */
-declare function registerMcpTools(registry: ToolRegistry, homeDir: string, diags: DiagnosticSink, injected?: readonly McpServerBatch[]): Promise<McpWiring>;
+declare function registerMcpTools(registry: ToolRegistry, homeDir: string, diags: DiagnosticSink, injected?: readonly McpServerBatch[], 
+/** `tools.deferMcp`：MCP 工具默认不进模型的初始工具列表，判据在 `registerMcpBatch` 上 */
+defer?: boolean): Promise<McpWiring>;
 
 /**
  * 用户直接敲的命令（TUI 的 `!ls -la`）和记忆速记（`#记一下`）—— 方案 25 §2.3 / §2.4。
@@ -3846,6 +4721,331 @@ interface UserActions {
 }
 declare function createUserActions(deps: UserShellDeps): UserActions;
 
+/**
+ * 一次性补全 —— `EpochRuntime.utility`（方案 59 需求 B）。
+ *
+ * 一次**不属于任何会话**的模型调用：不建会话、不落历史、不装 system prompt、
+ * 不带工具。宿主要的是「把这段表格格式化成 JSON」「给这个分片起个标题」这类杂活，
+ * 而在这一格之前他们唯一的路是自己 `new` 一个第二个 provider 实例 —— 那个实例
+ * 有自己的工厂缓存、自己的 `ModelFailureTracker`、自己的 `notices`
+ * （没人取 = 漏），凭据链还得他们自己复刻一遍（`keyEnv` 在构造时快照，
+ * 那条链跨三个包）。
+ *
+ * ## 「不带工具」是**类型上**的承诺，不是注释里的一句话
+ *
+ * {@link UtilityGenerateInput} 上压根没有 `tools` 这一格。于是「这条路不过审批
+ * 闸门」不是我们答应的一件事，是这个形状下**说不出口**的一件事 —— 手法同
+ * `HostAgentRole` 刻意少一个 `source`（见 [host-capabilities.ts](./host-capabilities.ts)）。
+ *
+ * 连带三条语义，一并写死：这条路**不进 `sessions` 表、不发 `AgentEvent`、
+ * 不占 hub 的活跃会话槽**。它底下就是一次 `router.generate()`，
+ * 中间没有 `AgentLoop`，也没有 `AgentSession`。
+ *
+ * ## 挂哪个 router：**引导会话那一份 = 进程那一份**
+ *
+ * 判据在 [session-model.ts](./session-model.ts) 的文件头（「引导会话那一份**就是**
+ * 进程那一份」）。这样宿主关心的四样东西 —— 降级状态、工厂缓存、通知队列、
+ * 凭据来源 —— 都只有一份，而不是「主循环一份、杂活一份」。
+ *
+ * ⚠️ **代价如实记着，和 `getUtilityInfo()` 那条已知代价并排**：第二个会话
+ * `/model` 换过模型之后，`utility` 跟的仍然是**引导**会话那个选择。这不是 bug
+ * （它答的是「这个进程默认用什么」），但宿主必须知道 —— 否则就是「用户在窗口 2
+ * 换了模型，宿主那批一次性调用还在打旧的」，而那正是方案 30 那一整轮要治的
+ * 那种撒谎。要打别的，`model` 那一格显式点名。
+ *
+ * ## ⚠️ 记账：这一格的**两句话**必须让宿主看懂
+ *
+ * 桶的钥匙写死成一行（{@link utilityBudgetKey}）：
+ *
+ * ```
+ * key = sessionId ?? `utility:${sanitize(label) || 'anonymous'}`
+ * ```
+ *
+ * 1. **传一个真 `sessionId` 有后果，而且不只是「多记一笔账」。**
+ *    `BudgetGuard.syncFromStore()` 在**每一轮请求之前**重读那个会话的桶，
+ *    **盘上的数字更大就采纳**（`core/src/agent/loop.ts` 里 `budget.syncFromStore()`
+ *    那一行 + `syncFromStore` 自己的「子 agent 只往 `BudgetStore` 里写、父这边
+ *    采纳」那条判据）。于是：
+ *
+ *    > 记到某个真会话名下的工具花费，**会去撞那个会话自己的 `budget.maxCostUsd`
+ *    > / `maxTokens`**；撞上了，那个会话的**下一轮直接被拦**，
+ *    > 用户看到的是「已达到本次会话的成本上限，任务提前终止」。
+ *
+ *    这**正是「记账才是真话」的完整含义**，不是副作用 —— 那笔钱确实是这段会话
+ *    花的（和 `delegate_task` 派出去那笔走同一条路、同一套判据）。但用户看见的
+ *    是「我让它跑个数据源，然后它就不说话了」，所以宿主界面上要接得住这一下。
+ *
+ * 2. **不传 `sessionId` 那一档，今天没有任何上界。**
+ *    `utility:<label>` 这个桶**没有任何 guard 在读它** —— `BudgetGuard` 只在
+ *    `AgentLoop` 上，而这条路上没有 `AgentLoop`。也就是说落在保留桶里的花费
+ *    **只被记下来，不被拦住**：`budget.maxCostUsd` 配多少都不管它。
+ *    要给它上界得先有一个读它的闸门，那是另一笔（方案 59 §十「跨会话 / 日月预算」）。
+ *
+ * ⚠️ 顺带一条**别误会**的：`label` 今天的价值是「那个 JSON 文件里分得开、
+ * 以后要做视图时数据是齐的」，**不是「今天就能在某一屏上看见」** ——
+ * 全仓没有任何地方展示 `~/.epoch/budget.json` 这本账（`BudgetStore` 只被
+ * `BudgetGuard` 读一次，用来恢复某段会话的累计），`epoch doctor` 上也没有这一行。
+ */
+
+/** 一次一次性补全的入参。**没有 `tools` 这一格**，判据见文件头 */
+interface UtilityGenerateInput {
+    /** 这一次要问的话。就是它的全部上下文 —— 这条路不拼历史、不注入记忆 */
+    messages: EpochMessage[];
+    /**
+     * 系统提示词。**给什么就是什么** —— 引擎那一整套（身份 / 工具说明 / AGENTS.md /
+     * 技能索引）在这条路上一个字都不装。不给就一个字都没有。
+     */
+    system?: string;
+    /** 最大输出 token */
+    maxTokens?: number;
+    /**
+     * 这一次用哪个模型。
+     *
+     * 不给 = 跟随 `models.utility`；它没配就跟随**引导会话**当前的选择
+     * （`getUtilityInfo()` 的口径，代价见文件头那条 ⚠️）。
+     *
+     * `provider` 不给 = 用当前那一家（同 {@link ModelRef} 的语义）。
+     */
+    model?: ModelRef;
+    /**
+     * 强制这一轮只出 JSON（方案 59 需求 A）。**provider 无关**。
+     *
+     * ⚠️ **不支持的 provider 不报错，只回一条 warning** —— 请求照发、结果照回、
+     * 那一轮的约束静默消失。所以这一格必须和回参里的
+     * {@link UtilityGenerateResult.responseFormatApplied} **一起读**，
+     * 别只看有没有抛异常。
+     */
+    responseFormat?: ResponseFormat;
+    /**
+     * 直通给 AI SDK 的 `providerOptions`。**我们不校验、不翻译、不兜底** ——
+     * 外层的 key 是 provider 名，写错就是静默无效。
+     */
+    providerOptions?: Record<string, Record<string, unknown>>;
+    /**
+     * **这次替谁花的钱。** 不给 = 落保留桶（见 {@link label}）。
+     *
+     * ⚠️ 给了它不只是「换一行记账」：那笔钱进这个会话的桶之后，**会去撞这个会话
+     * 自己的 `budget.maxCostUsd` / `maxTokens`** —— 撞上了，这个会话的下一轮就被
+     * 拦下来（`BudgetGuard.syncFromStore()` 每轮采纳盘上更大的那个值）。
+     * 完整判据和「为什么这是真话不是副作用」在文件头第 1 条。
+     *
+     * 判据是**谁发起的**：agent 调你的工具、你拿 `ctx.sessionId` 去跑那一批 →
+     * 传，不传才是假话；用户在你自己的控制台上点了一下、不在任何一次对话里 →
+     * 别传，硬塞一个（尤其是塞引导会话的 id）最省事也最假。
+     */
+    sessionId?: string;
+    /**
+     * 不属于会话的那些花费记在哪一行（桶名 `utility:<label>`）。
+     *
+     * 要它的理由是**量级**：几个调用点的花费能差两个数量级，混成一行那个数字对谁
+     * 都没用。收窄成 `[a-z0-9_-]{1,32}`，**不合的整格丢掉、退回 `utility:anonymous`
+     * 且不抛** —— 它是个标注不是语义，为一个诊断用的字段让调用失败不值。
+     *
+     * ⚠️ **给了 `sessionId` 时这一格被忽略**：一次调用只落一个桶，而
+     * `key = sessionId ?? ...` 里 `sessionId` 赢。
+     *
+     * ⚠️ 落在这个桶里的花费**今天没有上界**，见文件头第 2 条。
+     */
+    label?: string;
+    /**
+     * 中止信号。
+     *
+     * ⚠️ **只在发请求之前判一次。** `GenerateInput` 上没有 signal 这一格，
+     * AI SDK 那一跳我们今天穿不过去 —— 所以它管得住「别再发下一个」，
+     * 管不住「把已经发出去的那个掐掉」。宿主那种「循环里跑一百次」的用法，
+     * 要的正好是前者：置了之后 `generate()` 立刻抛，不再产生新的花费。
+     */
+    signal?: {
+        readonly aborted: boolean;
+    };
+}
+/** 一次一次性补全的结果。四格里后两格照 `GenerateOutput` 原样透，不在这一层重新发明 */
+interface UtilityGenerateResult {
+    text: string;
+    /** provider 没上报时**整个缺席**，不是一份填了 0 的对象（口径同 `GenerateOutput.usage`） */
+    usage?: TokenUsage;
+    /** 这次**实际**落到的模型 / provider（降级之后这两格才是真话） */
+    model: string;
+    provider: ProviderType;
+    /**
+     * 请求里带了 `responseFormat` 时才有这一格，没带就整个缺席。
+     *
+     * **拿不准时是 `false`**：假 `true` 的代价是调用方带着一个已经失效的约束接着跑，
+     * 判据全文在 `core/src/provider/types.ts` 的 `GenerateOutput.responseFormatApplied` 上。
+     */
+    responseFormatApplied?: boolean;
+    /** provider 对这一次请求的抱怨，判别联合原样透出（一条都没有时整个缺席） */
+    warnings?: ProviderWarning[];
+}
+/** 宿主的一次性补全出口。**只有一个动词** —— 这条路能做的事就只有「打一次」 */
+interface UtilityControl {
+    generate(input: UtilityGenerateInput): Promise<UtilityGenerateResult>;
+}
+/**
+ * 这一次的花费记在 `~/.epoch/budget.json` 的哪一行。
+ *
+ * ```
+ * key = sessionId ?? `utility:${sanitize(label) || 'anonymous'}`
+ * ```
+ *
+ * **导出它是为了宿主别自己拼这个字符串**（判据同 `EpochRuntime.artifactsRoot`
+ * 不让宿主 `join(homeDir, 'artifacts')`）：想在那份 JSON 里找到自己那一行，
+ * 问这个函数；哪天前缀改了，照着函数读的宿主什么都不用动。
+ *
+ * 三条刻意的取舍：
+ *
+ * 1. **`label` 不合规就整格丢掉，不做「悄悄改一改」。** 大写字母不 lowercase、
+ *    非法字符不删除 —— 因为这一格的全部价值是「宿主能在文件里找到自己那一行」，
+ *    悄悄换掉之后宿主传的那一格和盘上那一行**对不上**，而它看起来完全正常。
+ *    整格丢掉的表现相反：所有不合规的标注塌成同一行 `utility:anonymous`，
+ *    那是一个看得见的信号。**两种都丢信息，只有一种丢得出声。**
+ * 2. **空串 / 全是空白的 `sessionId` 不算「一个会话」。** `??` 只挡 `null`
+ *    和 `undefined`，`'' ?? x` 是 `''` —— 不判一次就会在账本里落一行键为空串的
+ *    记录，而它既不是任何会话，也不在 `utility:` 那一族里，谁都认不领；
+ * 3. **`sessionId` 本身不收窄。** 键是任意字符串（`Record<string, PersistedBudget>`），
+ *    而这一格的语义是「照你说的那个会话记」—— 替宿主改掉它等于记到另一段会话
+ *    头上，那比记错一行标注严重得多。
+ */
+declare function utilityBudgetKey(input: {
+    sessionId?: string;
+    label?: string;
+}): string;
+
+/**
+ * `@文件` 补全在运行时那一侧的收窄面（方案 63）—— `EpochRuntime.workspaceFiles`。
+ *
+ * ## 和 `sessionReferences` 是同一件事的另一半
+ *
+ * 那一格（方案 53）让 web 能列候选、解析、读当前面，而**不让服务端自己去读
+ * `sessions.db`**；这一格让 web 能列文件候选、解析路径、读正文，而**不让服务端
+ * 自己去 `readFileSync`**。两条路收窄的是同一个东西：`@` 存在的前提是「它永远
+ * 不比 `file_read` 宽松」，而判定只有一份 —— 权限层那一份。
+ *
+ * ## 收窄了哪几样
+ *
+ * 1. **候选清单只交出「`@` 表达得出来的路径」**（`isMentionableFilePath` 判的），
+ *    而且**过滤和去尾都在这一侧做**。判据同会话那一侧的「过滤在 SQL 里」：
+ *    候选被递到浏览器之前必须已经是「提交时会被认出来」的那一批，否则面板让你
+ *    选一条提交时服务端不认的 —— 而屏幕上没有任何异常。
+ *    ⚠️ 被挡掉的那几条**不是悄悄丢掉**：数出来那个数要递到面板上
+ *    （`WireFileCandidatesResponse.unmentionable`）。沉默截断是这个仓库反复在骂
+ *    的病（TUI 那侧 40 条池子的账记在方案 53 验收记录第六章）。
+ * 2. **读正文 = 边界 + 权限 + 二进制，一趟走完**（`readFile` 里）。跑出工作区的
+ *    路径和权限不放行是**同一个码 `denied`**（core 那条路也是 —— 部件上都记
+ *    `omitted: 'denied'`），读不到 / 是二进制各有各的码，见 {@link FileReadOutcome}。
+ * 3. **权限判定和 `file_read` 同一条**（`toolName: 'file_read'`，
+ *    判据逐字同 `core/src/context/mentions.ts` 的 `readOne` —— 审批缓存按工具名
+ *    做 key，写别的名字等于给 `@` 开一份独立的授权账本）。放行才 `readFileSync`，
+ *    而且**只回文本**：二进制探测在前 8KB 上做（判据同 `file_read` 那一条），
+ *    不让一个 100MB 的 mp4 为了确认自己是二进制而整个进内存。
+ *
+ * ## 这一份是**镜像**，不是「把 core 的类型导出来」
+ *
+ * 三个函数和 core 的 `WorkspaceFiles` / `resolveInWorkspace` / `readOne` 逐个
+ * 对应，但 `listFiles` / `resolveInWorkspace` 是**装配时递进来的**（core 的实现），
+ * 这个文件一行都不 import core —— 于是它能像别的 view 一样拿假依赖直接单测，
+ * 而 `check-layers.mjs` 那张表上 runtime → core 的方向照旧只有装配那一处。
+ *
+ * ## 候选清单的缓存：一次 git 的代价换每次按键
+ *
+ * 补全面板是**边打边刷**的，而 `listWorkspaceFiles` 走 `git ls-files` 要 spawn，
+ * 一次几十毫秒。清单**按工作区根缓存**：根变了立刻重算（换会话换根是常态），
+ * 没变就 60 秒才重算一次（同 core 那份文件头的判据：不做文件监听，
+ * 「用户敲 `@` 的那一刻」不值得为它养一个 watcher；过期的代价只是少一个新文件，
+ * 路径照样可以手打）。
+ *
+ * ## 排序：**仓库根那一层的文件在最上面**
+ *
+ * 打 `@` 之后第一屏列的是「所有目录的第一层 + 各自最浅的子文件」——
+ * 和人对「这个仓库长什么样」的第一印象同一个顺序。粗径深排是这一格自己的决定
+ * （core 那份清单是按路径字典序的，而补全面板卖的是「一眼看过去像这个仓库」）。
+ * 稳定起见相等时退回字典序。
+ */
+
+/** 一次候选查询的结果（要上 `WireFileCandidatesResponse` 的那三个数都在这儿） */
+interface FileCandidatesResult {
+    candidates: string[];
+    /** 匹配上了、但 `@` 表达不出来因而**没进清单**的条数（判据见文件头第 1 条） */
+    unmentionable: number;
+    /** 底层清单撞了 `MAX_FILES` 上限，清单之外的文件没参与匹配 */
+    truncated: boolean;
+}
+/**
+ * 装配时要递进来的 core 那一份。
+ *
+ * 写成**两个函数**而不是一个对象：这一格只要这两样，而它俩今天都住在 core 的
+ * 两个不同文件里 —— 合成一个对象的话，宿主将来想自己供一份（比如内存文件树）
+ * 就得把两个不相关的东西绑在一起。
+ */
+interface WorkspaceFilesDeps {
+    listFiles(root: string): {
+        files: string[];
+        truncated: boolean;
+    };
+    resolveInWorkspace(root: string, userPath: string): string | null;
+}
+/**
+ * 读一次文件的结果。
+ *
+ * **三档失败各有一个稳定的码**，而不是一个笼统的 null —— 调用方（web 那条路的
+ * 收据）要按码分档说话：「被权限拦了」和「这是个二进制」和「读不到」是三种
+ * 完全不同的交代。码和 core 的 `FileOmitReason` 对齐（去掉 `over-limit` /
+ * `not-restored` 那两档 —— 它们不是「读」这件事的答案，是装配层的）。
+ */
+type FileReadOutcome = {
+    ok: true;
+    text: string;
+    bytes: number;
+} | {
+    ok: false;
+    reason: 'denied' | 'unreadable' | 'binary';
+    bytes?: number;
+};
+/**
+ * `EpochRuntime.workspaceFiles` 在服务端眼里的样子 —— **三个方法，一个不多**。
+ *
+ * ⚠️ 每一次调用都收 `root`，**不许在门面上存一个「当前工作区」**：这个门面是
+ * **进程级**的（像 `permission`），而工作区**一个会话绑一个**（决定 18）。存根的话，
+ * 第二个会话拿到的是第一个会话的文件树 —— 编译得过、跑得通、只是答错会话
+ * （同 `EpochRuntime.checkpoints` 那段 ⚠️ 骂的那件事）。
+ */
+interface WorkspaceFilesView {
+    /**
+     * 补全面板的候选（方案 63）。
+     *
+     * @param root  工作区根（`projectContext.rootDir`，由调用方按会话现算）。
+     *              **不是启动目录** —— 判据同 `visibilityOf` 的第 2 条。
+     * @param query 正在打的那一截。**空串 = 刚敲下 `@`**，那一档要列最近的一屏。
+     * @param limit 一屏列多少条。**过滤和截断都发生在它之前**，所以它不是
+     *              「能搜到哪几条」的上限 —— 判据同会话那一侧的 `MAX_CANDIDATES`。
+     * @returns `null` = 这个工作区连清单都列不出来（没有 .git 也不是目录）。
+     *          和「一条候选都没有」必须分开：后者是一句真话（空仓库），前者是
+     *          「答不出来」。
+     */
+    candidates(query: string, limit: number, root: string): FileCandidatesResult | null;
+    /**
+     * 读一个文件的文本正文。
+     *
+     * **判定和 `file_read` 同源**（`toolName: 'file_read'`，见文件头第 3 条），
+     * 而且不放行时**不弹审批** —— 判据同 core 那条路的「没放行时不弹审批，
+     * 只是不附」。失败的三档码见 {@link FileReadOutcome}，调用方按码分档说。
+     *
+     * `bytes` 是文件的**原始字节数**（成功和二进制那两档都带）：调用方拿它和
+     * 附件预算比，决定要不要截、截多少 —— 算术在 protocol 那张上限表，
+     * 这一格不替调用方算（它不知道这条消息已经用掉多少预算）。
+     */
+    readFile(path: string, root: string): FileReadOutcome;
+}
+/**
+ * 建那个收窄面。
+ *
+ * @param deps       core 递来的两样（装配那一行从 `@epoch-agent/core` import）。
+ * @param permission 权限管理器；**可为 null** —— 那时的语义同 core 那条路的
+ *                   判据：权限模块没起来，模型调 `file_read` 照样读得到，
+ *                   `@` 单方面收紧只会让两条路给出不一致的答案。
+ */
+declare function buildWorkspaceFilesControl(deps: WorkspaceFilesDeps, permission: PermissionManager | null): WorkspaceFilesView;
+
 /**
  * buildRuntime() —— composition root。
  *
@@ -3915,11 +5115,31 @@ declare function createUserActions(deps: UserShellDeps): UserActions;
  *    - ③ 新用例必须红，**而且红的是断言不是崩**。崩说明它撞在别的东西上，
  *      而那个东西哪天变了它就不再守这一格了。
  *
- * ## 别去发明一个自动检查
+ * ## 转出格那一层：别去发明一个自动检查
  *
  * 「每个转出格都要有对应用例」这种扫描会立刻变成一个人人绕着走的形式主义，
  * 而且「哪几格该有」本身是判断（下面这条排序就是那个判断）。
  *
+ * ## ⚠️ 但**子系统**那一层有一条，2026-08-25 加的
+ *
+ * 上面那句话说的是**转出格**（可选参数、数组元素、`cleanups.push(...)`）——
+ * 63 个格子，哪几格该有用例是判断。它**不覆盖**另一个窄得多的集合：
+ * 这个文件里每一处 `wire*` / `register*` 调用（今天 15 处）。那些不是转出格，
+ * 每一处的语义都是同一句话 —— **一整个子系统在这里接进来**。这个集合是结构性
+ * 命名的、封闭的、名字自己认得出来的，「该不该有装配用例」上没有判断余地。
+ *
+ * 于是 `__tests__/assembly-wiring-sites.test.ts` 拿 TS 的 parser 扫这个文件，
+ * 三个方向都断：清单外没有新的装配点 / 清单里每一格今天仍然在 / 点名的那份用例
+ * **必须真的调 `buildRuntime()`**（拿一份只调那个函数的单元用例来交差会红）。
+ * 它接的是三次同形状的事故：44 §4.3 ①（摘掉插件那一批，6586 条 0 红）、
+ * 59 §十 #2（删 `describeTarget` 转发行，820 条 0 红）、59 §十 #3（注册那行挪
+ * 位置，0 红）。那一轮顺带补出两个当时还空着的格子：`wireWorkspace`
+ * （`--add-dir` 的额外根没告诉权限层）和 `reloadRoles` 里那次 `wireAgentRoles`
+ * （界面上新建的身份要到下次启动才认得）。
+ *
+ * **加一处 `wireXxx()` / `registerXxx()` 就得同时配一条装配用例**，
+ * 否则那份点名册会红。转出格那一层照旧按下面这条排序人工补。
+ *
  * ## 排序依据：按「坏了看不出来」补，不按「格数」补
  *
  * 转出面上的格子补不完，所以顺序是判断的一部分。从上到下：
@@ -4088,7 +5308,8 @@ interface BuildRuntimeOptions {
      */
     hostPreset?: HostPreset;
     /**
-     * 宿主注入的能力清单 —— 它自己 ship 的**专家 / 技能 / 连接器**（方案 44 §2.1）。
+     * 宿主注入的能力清单 —— 它自己 ship 的**专家 / 技能 / 连接器 / 工具**
+     * （方案 44 §2.1、方案 59 §四）。
      *
      * ```ts
      * await buildRuntime({
@@ -4098,6 +5319,7 @@ interface BuildRuntimeOptions {
      *     roles: [{ name: 'triage', description: '分拣工单，只读', tools: ['file_read'] }],
      *     skillDirs: [join(app.getAppPath(), 'resources', 'skills')],
      *     mcpServers: [{ name: 'github', transport: 'http', url: 'http://127.0.0.1:3456/mcp' }],
+     *     tools: [listJobsTool], // name: 'list_jobs' → 模型看到的是 `acme__list_jobs`
      *   },
      * });
      * ```
@@ -4114,15 +5336,20 @@ interface BuildRuntimeOptions {
      * 1. **命名空间是强制的** —— 前缀由装配层按 `namespace` 拼，不由宿主在每条数据
      *    上自己写。不这么做的话，一个叫 `general` 的注入会顶掉 `BUILTIN_ROLES`
      *    里那条，于是每一次没指定角色的派活都跑在宿主那份 prompt 上。
-     *    ⚠️ **三样里 MCP server 那一格拼的是 `<namespace>__` 而不是 `<namespace>:`**，
-     *    因为它会原样变成工具名的一部分发给 provider，而带 `:` 的工具名被硬拒
-     *    （实测，判据全文在 `McpServerStatus.source` 上）；
+     *    ⚠️ **四样里 MCP server 和工具那两格拼的是 `<namespace>__` 而不是
+     *    `<namespace>:`**，因为它们都会原样变成工具名的一部分发给 provider，
+     *    而带 `:` 的工具名被硬拒（实测，判据全文在 `McpServerStatus.source` 上）；
      * 2. **来源枚举各加一格**（`AgentRoleSource` / `SkillMeta.scope` 的 `'host'`，
      *    外加 `McpServerStatus.source` 这个**新增**字段），界面据此把它们单独分
-     *    一组、标上来源；
+     *    一组、标上来源。工具那一样走的是注册表既有的来源标签
+     *    （`registry.sourceOf()` 回 `'host'`），没有新枚举；
      * 3. **坏的那一条只跳过它自己**，其余照常进来，各留一条诊断。唯一整份作废的是
      *    `namespace` 本身坏掉那一档 —— 那时没有前缀，而没有前缀就能顶掉内置角色。
      *
+     * ⚠️ **注入的工具不因为跑在同一个进程里就少一道闸**：审批闸门在
+     * `ToolExecutor.execute` 上，它对**任何**来源的工具过同一道 `checkPermission`。
+     * 这不是我们答应的一件事，是那一层压根不知道工具是谁给的（方案 59 §4.2）。
+     *
      * **注入是装配时一次性的**（同 `secretStore`）：宿主 ship 了什么是它的构建期
      * 属性，一个 Electron 应用不会在跑着的时候长出一个新专家。⚠️ 这句话**不等于**
      * 「注入进去的东西是死的」—— 宿主注入的技能照样被 `SkillLearner` 影响，
@@ -4131,6 +5358,34 @@ interface BuildRuntimeOptions {
      * 不给这个选项时**一行都不跑**，连一条诊断都不多。
      */
     hostCapabilities?: HostCapabilities;
+    /**
+     * 宿主预置的**插件市场** —— 「宿主替用户装一个扩展物」那条路（方案 59 §六 E1）。
+     *
+     * ```ts
+     * await buildRuntime({
+     *   homeDir,
+     *   hostMarketplaces: { sources: [join(app.getAppPath(), 'resources', 'market')] },
+     * });
+     * // → runtime.plugins.search('office') 搜得到，install() 装成软链，全程不联网
+     * ```
+     *
+     * ⚠️ **给了才有 {@link EpochRuntime.plugins}**，不给就是 `null`、一行都不跑。
+     * 它是一个真的新攻击面（往 `~/.epoch/plugins/` 里写东西），所以是**选进来**的，
+     * 不是白送的 —— 同 `installSignalHandlers` 默认 false 那条判据。
+     *
+     * ⚠️ **和 {@link hostCapabilities} 不是一件事**：那一个是「宿主自己 ship 的东西，
+     * 一个字节都不落盘、用户删不掉」；这一个是「宿主给用户一张单子，用户挑一个
+     * **装下来**」—— 装完之后它就是用户的插件，`epoch plugin list` 查得到、
+     * `epoch plugin uninstall` 卸得掉。
+     *
+     * ⚠️ **装完不会立刻生效**（扩展物在启动时加载），要 `dispose()` + 再
+     * `buildRuntime()` 一次。这条不是欠账，是这一轮对外承诺的形态 ——
+     * 判据、以及「为什么重建一次就够」，在
+     * [plugin-control.ts](./plugin-control.ts) 的文件头第二节。
+     *
+     * 远程 source（`github:` / `npm:` / `https:`）**默认关着**，判据同上，第三节。
+     */
+    hostMarketplaces?: HostMarketplaces;
     /**
      * 这一程开出来的会话在 `sessions.source` 那一列记成什么（方案 45 §五）。
      *
@@ -4330,6 +5585,26 @@ interface ManagedNote {
     bypassDisabled: boolean;
 }
 
+/**
+ * 一次撤销审批缓存的结果（2026-08-27）。
+ *
+ * ⚠️ 两个拒绝码是**两回事，不许合成一个布尔**：
+ *
+ * - `no-permission-layer` —— 这个进程整个没有权限层，也就**没有缓存这回事**。
+ *   宿主该说「这一节不适用」（web 那侧回 503，界面上根本不画这一节）；
+ * - `unknown-id` —— 权限层好好的，只是那条不在表里了（另一个界面先撤了，
+ *   或者 `allow-session` 过期被 `prune()` 清掉了）。**这不是错误**：用户要的
+ *   结果已经成立，宿主该做的是把新表画上去，不是报错让他重试。
+ *
+ * 合成一个 `false` 的话，第二档会被画成第一档的样子 —— 屏幕上一句
+ * 「权限层不可用」，而权限层其实好好的。
+ */
+type ApprovalRevokeResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: 'no-permission-layer' | 'unknown-id';
+};
 /**
  * 权限规则的可解释性出口（方案 22 §2.6 / §2.7 / §2.8）。
  *
@@ -4349,6 +5624,22 @@ interface ManagedNote {
  * 具体代价是**第三步会被漏掉** —— 漏了 `plan.forget()` 的那一侧，用户在 plan
  * 模式里换档之后，随后一次计划批准会把级别悄悄改回进入前那一档，
  * 而这件事只在「plan 模式 + 中途换档 + 批准计划」三件事凑齐时才看得见。
+ *
+ * ## ⚠️ 第八样 {@link revokeApproval} 也是**写**（2026-08-27），它同样不破那条
+ *
+ * 上面那条否掉的还是「从 UI 改一条**规则**」。**审批缓存不是规则** ——
+ * 它就是那条判据里点名的那个东西（「那正是审批缓存已经在干的事」）：
+ * 用户在弹窗上点出来的、只属于这台机器这一程的记忆，不写 git、不该写 git。
+ *
+ * **补它的理由是它今天根本收不回来。** `allow-always` 落
+ * `~/.epoch/approvals.json`，用户至少删得掉那个文件；而 `deny` 只在内存里、
+ * `ttlMs: 0` 永不过期 —— 一次点错的「拒绝」之后，那个工具在这个进程里就死了，
+ * 屏幕上只会一直印「操作被拦截 [权限]: 已缓存拒绝」。判据全文在 core 的
+ * `ApprovalCache.revoke()` 上。
+ *
+ * ⚠️ **它撤的只是缓存那一层。** 规则的 deny（三张列表 / `policies/*.toml`）
+ * 排在缓存**前面**（core 的 `checkRulesAndCache`），这一发一个字都不动它们 ——
+ * 宿主的界面上这两者必须分得开，不然用户点了「撤销」发现还是被拦。
  */
 interface PermissionsControl {
     /** 当前生效的全部规则，按 deny → ask → allow 排，每条标出来源层 */
@@ -4399,6 +5690,36 @@ interface PermissionsControl {
      * 没有权限层就等于什么都没判过，而那句话是真的。
      */
     audit: (scope?: PermissionAuditScope) => PermissionAuditSnapshot;
+    /**
+     * 这个进程记下了哪些**弹窗答案**（审批缓存，2026-08-27）。
+     *
+     * ⚠️ **和 {@link audit} 不是同一本账，别拿一个顶另一个。** 流水记「判过什么」
+     * （只增不减的历史，一次判定一行）；这张表记「**还记着什么**」（撤一条少一行）。
+     * 同一次「用户点了拒绝」在两处各留一行，而下一步完全不同：流水那行是历史，
+     * 这一行是现在还在拦人的东西。
+     *
+     * ⚠️ **和 {@link rules} 也不是一回事**：那一张是配置文件里写下来的策略
+     * （能提交进 git），这一张是本机这一程的记忆。判定时**规则的 deny 排在缓存
+     * 前面**，所以撤销这里的一条不等于放行 —— 宿主的界面必须说得清这一点。
+     *
+     * 权限层起不来时是**空表**而不是抛错：没有权限层就等于什么都没记过，
+     * 而那句话是真的（同 {@link audit} 那条兜底，两处必须一致）。
+     */
+    approvals: () => readonly CachedApproval[];
+    /**
+     * 撤销**一条**缓存的决定，判据全文在接口文档最后一节。
+     *
+     * 按 id 不按目标：同一个「工具名 + 目标」上可以躺着不止一条，按目标撤的话
+     * 一次调用会删掉几条而调用方说不出是哪几条 —— 界面上那一行「撤销」
+     * 就成了一个作用范围不确定的按钮。id 是 {@link approvals} 每一行自己带的。
+     *
+     * ⚠️ **没有「全清」那一档，而 core 那边 `ApprovalCache.clear()` 一直都在。**
+     * 不转出来是刻意的：那一下会把用户攒了一整程的「总是允许」一起清掉，
+     * 于是「收回一个误点」的代价变成「后面每一次都重新问一遍」。
+     * 真要那一档时它是另一个方法（另一个动词、宿主另一次确认），
+     * 不是这个方法多一个参数。
+     */
+    revokeApproval: (id: string) => ApprovalRevokeResult;
     /**
      * 切到某一档。**这是宿主改权限档位的唯一入口**（见接口文档最后一节）。
      *
@@ -4450,7 +5771,12 @@ interface PermissionsControl {
 interface ToolGateRow extends ToolGate {
     name: string;
     description: string;
-    /** `builtin` / `plugin-file` / `mcp:<服务器名>`，同 {@link EpochRuntime.tools} */
+    /**
+     * `builtin` / `plugin-file` / `mcp:<服务器名>` / `host`，同 {@link EpochRuntime.tools}。
+     *
+     * 最后那一格是宿主经 `hostCapabilities.tools` 注入的进程内工具（方案 59 §四）——
+     * 它在这张表上**和别人一档**，那正是它该在的位置：闸门不看来源。
+     */
     source: string;
     /**
      * 命中的那条规则来自哪一层（`user` / `project` / …）。
@@ -4610,6 +5936,22 @@ interface SessionDeletion {
      * （对话已经没了），但也不能装作全干净了 —— 残留目录会一直占着磁盘。
      */
     checkpointsRemoved: boolean;
+    /**
+     * `~/.epoch/artifacts/<id>/` 也清掉了（方案 47 PR-4，2026-08-20）。
+     * 本来就没有产物时同样是 `true` —— 绝大多数会话就是这一档。
+     *
+     * 单独一格而不是和 `checkpointsRemoved` 合成一个「附属物清干净了」：
+     * 两个存储的失败原因不一样（检查点是一堆小 blob，artifact 可能是一个正被
+     * 别的进程按着的大文件），合成一格之后界面只能说「有东西没删掉」，
+     * 而用户下一步该去哪个目录看，那句话答不了。
+     *
+     * ⚠️ **这一格没有进 `WireDeleteSessionResponse`**：protocol 那份契约这一轮
+     * 一个字没动（并行分支正占着 protocol / server / web 三个目录）。它照样会随
+     * JSON 出门 —— `conformsToWire()` 只查必填字段在不在、**不查多余字段**
+     * （判据逐字写在 `wireFields()` 上：响应里多一个字段是向前兼容的正常演进）。
+     * 要让 Web 界面**读**它，得先往那份契约上加一格。
+     */
+    artifactsRemoved: boolean;
 }
 /** 会话的列举、检索、恢复与增删改（方案 25 PR-4；方案 30 补了后三个） */
 interface SessionControl {
@@ -4626,9 +5968,10 @@ interface SessionControl {
      */
     rename: (sessionId: string, title: string) => SessionSummary | null;
     /**
-     * 真删一段会话，**连带删掉它的检查点**（方案 30 §2.2 + 方案 27 的交接）。
+     * 真删一段会话，**连带删掉它的检查点和 artifact**（方案 30 §2.2 +
+     * 方案 27 的交接 + 方案 47 PR-4）。
      *
-     * 不可撤销 —— 二次确认是宿主的事。异步是因为检查点在文件系统上。
+     * 不可撤销 —— 二次确认是宿主的事。异步是因为那两处都在文件系统上。
      */
     delete: (sessionId: string) => Promise<SessionDeletion>;
     /**
@@ -4673,6 +6016,25 @@ interface EpochRuntime {
      * [session-factory.ts](./session-factory.ts) 的文件头，**别在别处抄第二份**。
      */
     sessionFactory: SessionFactory;
+    /**
+     * 进程里所有会话产出的每一帧 `AgentEvent`（方案 61）。**不可为 null** ——
+     * 它不依赖任何一样装配得起来的东西，provider 没起来时它照样在（那时它只是
+     * 一帧都不会有，那是一句真话）。
+     *
+     * 在它之前，事件没有「存在」这个概念，只有「被某个 for-await 吃掉了」：
+     * `run()` 是单消费者流，三条消费路各自独占一个 for-await。于是宿主自己驱动
+     * `session.run()` 时，**同进程的其它部件（诊断面板、审计、埋点）一帧都旁听不到**
+     * —— 方案 54 §三那条 `observe()` 只挂在 server hub 的广播层上，够不着这一半。
+     *
+     * ⚠️ **进程级，不是这份 runtime 级**：同一个进程里建两份 runtime，
+     * 两个 `events` 是**同一个对象**，订阅者会看到另一份 runtime 的会话事件。
+     * 这是有意的 —— 「任何会话一帧都没有」这句话只有进程级的总线答得出来。
+     * 判据全文在 [events.ts](./events.js) 文件头。
+     *
+     * 用法与三条禁令（不许调 `respond`、不许在回调里干重活、不许指望顺序之外的
+     * 任何保证）见 [docs/EMBEDDING.md](../../../docs/EMBEDDING.md) §13.5。
+     */
+    events: AgentEventBus;
     /**
      * 会话持久化；SQLite 起不来时为 null。
      *
@@ -4687,6 +6049,33 @@ interface EpochRuntime {
      * 而那正是方案 20 §缺口 1 花一整条线修掉的东西。
      */
     sessionStore: SessionStore | null;
+    /**
+     * `@:` 引用会话那一侧（方案 53）；SQLite 起不来时为 null。
+     *
+     * 摘出来是给**宿主的输入框**用：`@` 提及的解析（`resolveMentions`）要过
+     * 可读性判定，而那条判定在 core 里 —— 让 TUI / web 自己去读 `sessions.db`
+     * 等于给 `@:` 开一条绕过判定的读取通道（同 `resolveMentions` 不让 TUI
+     * 自己 `readFileSync` 那条判据）。
+     *
+     * 和 {@link sessionStore} 分开摆而不是让宿主从那儿翻：前者是「回放旧会话」
+     * 的读路（给 web 的详情页），这一份是「把另一段会话塞进这一条消息」的
+     * 收窄面 —— 它只交出候选 / 解析 / 当前面三件事，交不出任意 SQL。
+     */
+    sessionReferences: SessionReferences | null;
+    /**
+     * `@文件` 补全与解析（方案 63）。**不可为 null** —— 它不依赖任何会起不来的
+     * 东西：底下的清单 `git ls-files` 失败会退到 walk，读文件失败回 null。
+     * 权限层缺席时它照样在，只是 `readFile` 跳过那道判定 —— 判据逐字同 core 的
+     * `resolveMentions`：权限模块没起来时模型调 `file_read` 照样读得到，`@` 单方面
+     * 收紧只会让两条路给出不一致的答案。
+     *
+     * 和 {@link sessionReferences} 是同一件事的另一半：那一份让宿主列会话候选、
+     * 读当前面而**不交出任意 SQL**；这一份让宿主列文件候选、读正文而**不交出任意
+     * `readFileSync`**。收窄的东西是同一句话 —— `@` 永远不比 `file_read` 宽松，
+     * 而判定只有权限层那一份（`toolName: 'file_read'`，判据全文在
+     * [workspace-files.ts](./workspace-files.js) 的文件头）。
+     */
+    workspaceFiles: WorkspaceFilesView;
     /**
      * **引导会话**的检查点与回退（方案 27）。**不可为 null** —— 它只是文件系统上的
      * 一个目录，不像 provider / SQLite 那样有起不来的可能。
@@ -4830,6 +6219,17 @@ interface EpochRuntime {
      * deny 时还能带一句自定义的话）。
      */
     policy: PolicyStatus;
+    /**
+     * 这一次读了哪几份 hook 配置、每份贡献了几条、项目那几份是不是因为不受信任
+     * 整份没加载（方案 50 PR-3）。
+     *
+     * 和 {@link policy} 摊在一屏里要说清区别：策略规则管「这个工具碰这个路径
+     * 算什么」，hook 是**会 spawn 子进程的命令**。而这一份现在还要答一个更基本的
+     * 问题 —— 方案 50 之后 hook 可能来自 Claude Code 的三份配置里的任意一份，
+     * 甚至来自**仓库作者**写给 Claude Code 的那一份，于是
+     * 「我没写过这条命令，它为什么会跑」需要一个能指到文件的答案。
+     */
+    hook: HookStatus;
     /**
      * 对模型可见的工具清单（名字 + 一行说明）。
      *
@@ -4915,6 +6315,23 @@ interface EpochRuntime {
      * 在 [model-catalog.ts](./model-catalog.ts) 的文件头。
      */
     modelCatalog: ModelCatalogControl;
+    /**
+     * 一次性补全（方案 59 需求 B）—— 不建会话、不落历史、不装 system prompt、
+     * **不带工具**。provider 起不来时为 null（同 {@link model}）。
+     *
+     * 它答的是宿主那批「把这段表格格式化成 JSON」的杂活：在这一格之前他们唯一的路
+     * 是自己 `new` 一个第二个 provider 实例，而那个实例有自己的工厂缓存、自己的
+     * 失败节流器、自己的通知队列（没人取 = 漏），凭据链还得自己复刻一遍。
+     *
+     * ⚠️ **它挂的是引导会话那一份 router**，所以第二个会话 `/model` 换过之后，
+     * 这条路跟的仍然是引导会话那个选择。要打别的就显式给 `model`。
+     *
+     * ⚠️ **`sessionId` 这一格有后果**：给了它，这笔花费就去撞那个会话自己的
+     * `budget.maxCostUsd` —— 撞上了那个会话下一轮被拦。不给它则落
+     * `utility:<label>` 保留桶，而那个桶**今天没有任何上界**。
+     * 两条判据全文在 [utility.ts](./utility.ts) 的文件头，别在别处抄第二份。
+     */
+    utility: UtilityControl | null;
     /**
      * 可派给子 agent 的角色表（方案 18）。provider 起不来时是空数组 ——
      * 没有 provider 就没有 `delegate_task`，角色也就无处可派。
@@ -4959,6 +6376,27 @@ interface EpochRuntime {
      * 这里）。嵌入宿主要整份就该拿到整份。
      */
     skillBody(name: string): string | null;
+    /**
+     * 每条技能**此刻进没进** `<available_skills>`，名字 → 三档（2026-08-27）。
+     *
+     * ## 它答的是 web 能力页那一栏行尾那个数到底还算不算数
+     *
+     * 那一栏印着「这条技能每一轮的常驻开销」（`WireSkillSummary.tokens`）。
+     * 那句话在两道口子都关着时是真的，而它们**各自**都能让它对被排除的那几条
+     * 变成假话：`skills.maxIndexed` 封了顶（进程级），或者这段会话的身份带着
+     * `AgentRole.skills` 白名单（会话级）。记账全文在
+     * [RECORD-skill-index-narrowing](../../../docs/verify/VERIFY_RECORD-skill-index-narrowing.md) §四第 1 条。
+     *
+     * @param role **这段会话的底座身份名**（`LiveSession.role?.name`），没绑就是
+     *   `null`。⚠️ 不是那枚 chip 挑的逐条身份 —— 「常驻」这个词的宾语是整段会话，
+     *   而 chip 只活一个轮次（两者的差别逐字在 `LiveSession.role` 那张表上）。
+     *   名字认不出来（角色表热加载过、那份 md 被删了）时按**不收窄**算：
+     *   那时引擎自己也退回会话默认角色跑，报一句「被身份挡了」是假话。
+     *
+     * 技能系统起不来时是空 Map。**那不是「全都没进」** —— 那时 {@link skills}
+     * 本身就是空数组，一格都不会被查到（判据同它为什么是空数组而不是 null）。
+     */
+    skillIndexResidency(role: string | null): ReadonlyMap<string, SkillIndexResidency>;
     /**
      * 从**本机目录**导入技能（方案 42 §六，2026-08-18）。**不可为 null** ——
      * 技能系统没起来时它照样在，只是每次都回 `missing`，而那是一句真话
@@ -4981,6 +6419,25 @@ interface EpochRuntime {
      * 判据在 [role-write.ts](./role-write.ts) 文件头第二节。
      */
     roleWrite: RoleWriteControl;
+    /**
+     * 插件的宿主控制面（方案 59 §六 E1）：列 / 搜 / 预览 / 装 / 更新 / 卸。
+     *
+     * ⚠️ **没给 {@link BuildRuntimeOptions.hostMarketplaces} 时为 `null`**，而这一格
+     * 的可空和 `model` / `memory` 那几格**不同档**：那几个是「底下那层起不来了」，
+     * 这一个是「宿主没打算给用户这条路」。判据是它真的是一个新口子（往
+     * `~/.epoch/plugins/` 里落东西、装完的插件下一程会被加载），
+     * 而一个没预置任何市场的宿主，凭空多一个能装插件的方法只有坏处。
+     *
+     * ⚠️ **装完不会立刻生效** —— 装 / 更新 / 卸之后
+     * `plugins.pendingRestart` 变 `true`，宿主要 `dispose()` + 重新 `buildRuntime()`。
+     * **怎么把这件事说给用户听是宿主的决定**（它比我们知道自己的用户能不能接受），
+     * 我们只给这一格事实。判据全文在
+     * [plugin-control.ts](./plugin-control.ts) 的文件头第二节。
+     *
+     * ⚠️ 这条路**只收 `<市场>/<插件>`，收不了一条路径** —— 那是这一轮的安全性质
+     * 本体（比 {@link skillImport} 那道闸更紧），判据在那个文件头第四节。
+     */
+    plugins: PluginControl | null;
     /**
      * MCP server 的连接状态（方案 25 PR-4）。
      *
@@ -5037,6 +6494,19 @@ interface EpochRuntime {
      * 得向工厂要那个会话自己的（{@link LiveSession.goals}）。
      */
     goals: GoalControl | null;
+    /**
+     * **任意一段会话**的目标（方案 52 PR-4）。会话库起不来时为 null，同上面那格。
+     *
+     * ⚠️ **它不是 `goals` 的另一种写法，两格答的是两个问题**：`goals` 答
+     * 「**我这一段**的目标」（TUI 那种一个会话一个宿主的形态），这一格答
+     * 「**那一段**的目标」（多会话宿主，也就是 web 服务端 —— 它每条请求的
+     * sessionId 来自 URL，压根没有「我这一段」这个东西）。
+     *
+     * **它能答冷却掉的会话，而工厂那一份不能**：目标没有内存态，`GoalService`
+     * 每次现读 SQLite。判据全文（含「为什么这里刻意没有 `block()`」）在
+     * {@link GoalCatalog} 上。
+     */
+    goalCatalog: GoalCatalog | null;
     /**
      * 会话的列举与检索（方案 25 PR-4 的 `/resume` 和 Ctrl+R）。
      *
@@ -5070,8 +6540,21 @@ interface EpochRuntime {
      */
     readonly contextBreakdown: ContextBreakdown | null;
     /**
-     * 定时任务（方案 45）。**不可为 null** —— 底下只有一张 SQLite 表和一个平台探测，
-     * 没有起不来的可能；本平台没有 OS 后端时 `capability()` 如实说 `backend: null`。
+     * 定时任务（方案 45）。**不可为 null**；本平台没有 OS 后端时 `capability()`
+     * 如实说 `backend: null`。
+     *
+     * ⚠️ **这一段原来写着「底下只有一张 SQLite 表和一个平台探测，没有起不来的可能」
+     * —— 后半句是假的**（2026-08-26 改准）。那张表就是 `sessions.db`，和
+     * `SessionManager` / `TrackerDB` 同一个文件，而那两个都套着 `safeInit` 开 ——
+     * 也就是说这个仓库自己早就认了「它开不起来」这件事。真实后果比「一格是 null」
+     * 严重得多：装配那一行原来是裸调的，于是那个文件打不开时**整个 `buildRuntime()`
+     * 抛**，`epoch web` 退出码 1。
+     *
+     * 现在开库失败被兜住，这一格照旧不为 null，**但要先看
+     * `schedules.storeAvailable`** —— `false` 时下面每个方法都会抛（不回空清单，
+     * 那是「这台机器上没有定时任务」，是另一句话）。为什么选加一格而不是把这个
+     * 字段改成可空（`major` 会传染给全组），判据在
+     * [schedule/control.ts](./schedule/control.ts) 的 `createScheduleControl` 上。
      *
      * ⚠️ **这一份是给嵌入宿主的，CLI 不走它**（`epoch schedule` 自己开 store，
      * 因为只有 CLI 知道 `process.execPath` 和入口 js 在哪）。判据、以及
@@ -5649,4 +7132,4 @@ declare function probeMcpServer(name: string, opts?: McpAdminOptions): Promise<{
     needsLogin: boolean;
 }>;
 
-export { AgentRoleError, AgentSession, type AgentSessionOptions, type ApplyHostPresetOptions, ApprovalRelay, type ApproveFn, type BindWorkspaceFailure, type BindWorkspaceResult, type BuildRuntimeOptions, type BuildToolsInput, type CommandControl, type CommandWiring, type DiscoverOptions, type EffectiveSetting, type EpochRuntime, type ExecutorRuntime, type FireResult, type FireScheduleOptions, type GoalControl, HOST_CAPABILITIES_MODULE, HOST_PRESET_MODULE, type HistoryMessage, type HostAgentRole, type HostCapabilities, type HostCapabilityWiring, type HostPreset, type HostPresetProvider, type HostPresetWorkspace, type HostSkillDir, type LevelChangeResult, type McpAddInput, type McpAddOutcome, type McpAdminOptions, type McpApplyAction, type McpApplyChange, type McpApplyOutcome, type McpApplySource, type McpConfigIssue, type McpConfigReadOutcome, type McpConfigSaveOutcome, type McpConfigSnapshot, type McpControl, type McpListResult, type McpLoginCliOptions, type McpReconnectOutcome, type McpServerBatch, type McpServerOverview, type McpWriteOutcome, type ModelCatalogControl, type ModelCatalogOptions, type ModelControl, type ModelSuggestions, type ModelTurnScope, type PermissionsControl, type PlanControl, type PolicyDirStatus, type PolicyStatus, type ProviderOption, QuestionRelay, type RelayClock, type RoleAddInput, type RoleAddOutcome, type RoleControl, type RoleTurnScope, type RoleWriteControl, type RunOptions, SCHEDULE_EXIT_CODES, type ScheduleCapability, type ScheduleControl, type ScheduleControlOptions, type ScheduleSaveResult, type SerializableAgentEvent, type SerializableApprovalRequest, type SerializableQuestionRequest, type SerializedEvent, type ServiceOptions, type Services, type SessionControl, type SessionDeletion, type SessionFileChange, type SessionHit, SessionStore, type SessionSummary, type SessionWorkspace, SessionWorkspaces, type SessionWorkspacesOptions, type SettingWriteDone, type SettingWriteInput, type SettingWriteRefused, type SettingWriteReport, type SettingsControl, type StoredMessage, type TurnDetail, type TurnStep, type UserActionResult, type UserActions, type WireWorkspaceInput, type WorkspaceBindingState, type WorkspaceControl, applyHostPreset, applyMcpConfig, buildModelCatalogControl, buildRuntime, buildServices, collectFileChanges, createScheduleControl, createUserActions, ensureSecretsReady, exitCodeFor, fireSchedule, listMcpServers, mcpConfigRevision, mcpLogin, mcpLogout, probeMcpServer, readMcpConfigFile, registerAskQuestion, registerLocalTools, registerMcpTools, serializeStream, splitDirList, toSerializable, wireCommands, wireHostCapabilities, wirePluginMcpServers, wireWorkspace, withModelScope, withRoleScope, withToolScope, writeMcpConfigFile, writeMcpServer };
+export { type AgentEventBus, type AgentEventSubscriber, AgentRoleError, AgentSession, type AgentSessionOptions, type ApplyHostPresetOptions, ApprovalRelay, type ApprovalRevokeResult, type ApproveFn, type BindWorkspaceFailure, type BindWorkspaceResult, type BuildRuntimeOptions, type BuildToolsInput, type CommandControl, type CommandWiring, type DiscoverOptions, type EffectiveSetting, type EpochRuntime, type ExecutorRuntime, type FileCandidatesResult, type FileReadOutcome, type FireResult, type FireScheduleOptions, type GoalControl, HOST_CAPABILITIES_MODULE, HOST_MARKETPLACE_MODULE, HOST_PRESET_MODULE, type HistoryMessage, type HookStatus, type HostAgentRole, type HostCapabilities, type HostCapabilityWiring, type HostMarketplaces, type HostPreset, type HostPresetProvider, type HostPresetWorkspace, type HostSkillDir, type LevelChangeResult, type McpAddInput, type McpAddOutcome, type McpAdminOptions, type McpApplyAction, type McpApplyChange, type McpApplyOutcome, type McpApplySource, type McpConfigIssue, type McpConfigReadOutcome, type McpConfigSaveOutcome, type McpConfigSnapshot, type McpControl, type McpListResult, type McpLoginCliOptions, type McpReconnectOutcome, type McpServerBatch, type McpServerOverview, type McpWriteOutcome, type ModelCatalogControl, type ModelCatalogOptions, type ModelControl, type ModelSuggestions, type ModelTurnScope, type PermissionsControl, type PlanControl, type PluginActionOutcome, type PluginControl, type PluginInstallOutcome, type PluginListEntry, type PluginPreviewOutcome, type PluginRefusal, type PluginRefuseReason, type PluginSearchHit, type PolicyDirStatus, type PolicyStatus, type ProviderOption, QuestionRelay, type RelayClock, type RoleAddInput, type RoleAddOutcome, type RoleControl, type RoleTurnScope, type RoleWriteControl, type RunOptions, SCHEDULE_EXIT_CODES, type ScheduleCapability, type ScheduleControl, type ScheduleControlOptions, type ScheduleSaveResult, type SerializableAgentEvent, type SerializableApprovalRequest, type SerializableQuestionRequest, type SerializedEvent, type ServiceOptions, type Services, type SessionControl, type SessionDeletion, type SessionFileChange, type SessionHit, SessionStore, type SessionSummary, type SessionWorkspace, SessionWorkspaces, type SessionWorkspacesOptions, type SettingWriteDone, type SettingWriteInput, type SettingWriteRefused, type SettingWriteReport, type SettingsControl, type StoredMessage, type TurnDetail, type TurnStep, type UserActionResult, type UserActions, type UtilityControl, type UtilityGenerateInput, type UtilityGenerateResult, type WireWorkspaceInput, type WorkspaceBindingState, type WorkspaceControl, type WorkspaceFilesDeps, type WorkspaceFilesView, applyHostPreset, applyMcpConfig, buildModelCatalogControl, buildRuntime, buildServices, buildWorkspaceFilesControl, collectFileChanges, createScheduleControl, createUserActions, ensureSecretsReady, exitCodeFor, fireSchedule, listMcpServers, mcpConfigRevision, mcpLogin, mcpLogout, probeMcpServer, providerLabel, readMcpConfigFile, registerAskQuestion, registerLocalTools, registerMcpTools, serializeStream, splitDirList, toSerializable, utilityBudgetKey, wireCommands, wireHostCapabilities, wirePluginMcpServers, wireWorkspace, withModelScope, withRoleScope, withToolScope, writeMcpConfigFile, writeMcpServer };