@epoch-agent/server 0.1.0 → 0.3.1

package/dist/index.d.ts

@@ -1,5 +1,6 @@
-import { Lang, WireSkillImportFailure, WireSkillImportForm, WireCapabilitiesResponse, WireSkillBodyResponse, EpochUserContent, AgentEvent, WireEnvelope, CustomCommandDef, ExpandedCommand, ModelRef, SetSelectionResult, WireCommandExpansion, WireCustomCommand, WireTurnState, WireSessionFinish, ApprovalOutcome, QuestionAnswer, ProviderType, ModelSelectionOrigin, WireModelCaveat, WireModelRejection, PermissionLevel, WireModelSource, WireModelProbeStatus, ScheduleDefinition, ScheduleRun, ScheduleBackendKind, OperationType, ScheduleTrigger, WireScheduleIssue, ScheduleRunStatus, TrustLevel, WireSandboxReason, WireAuditOutcome, WireAuditCode, WireToolVerdict, WireToolGateAxis, WireSecurityResponse, WireRewindScope, WireRewindRequest, WireCheckpointSummary, WireRewindPreview, WireRewindResponse, ActiveAgentRole, WireSettingValue, WireSettingLayer, WireSettingWriteLayer, WireSettingFutile, WireSettingApply, WireSettingsResponse, EpochConfig, WireCompressionLine, WireProviderSummary, WireToolSummary, Diagnostic, WireReplayMessage, WireFileChange, WireAuthGuard, WireWorkspaceDiffResponse, BackgroundTaskInfo, WireTasksResponse, WireBackgroundTask, WireScheduleRow } from '@epoch-agent/protocol';
-import { SerializableApprovalRequest, SerializableQuestionRequest, LevelChangeResult } from '@epoch-agent/runtime';
+import { Lang, WireSkillImportFailure, WireSkillImportForm, WireSkillRemoveFailure, WireCapabilitiesResponse, WireSkillBodyResponse, EpochUserContent, AgentEvent, WireEnvelope, CustomCommandDef, ExpandedCommand, ModelRef, SetSelectionResult, WireCommandExpansion, WireCustomCommand, WireGoalPhase, WireGoalRefusal, WireTurnState, WireSessionFinish, ApprovalOutcome, QuestionAnswer, SessionSurfaceView, WireSessionReference, WireFileReference, ProviderType, ModelSelectionOrigin, WireModelCaveat, WireModelRejection, ContextBreakdown, PermissionLevel, WirePermissionRememberFailure, WirePluginSourceType, WirePluginRefuseReason, WirePluginEntry, WireModelSource, WireModelProbeStatus, ScheduleDefinition, ScheduleRun, ScheduleBackendKind, OperationType, ScheduleTrigger, WireScheduleIssue, ScheduleRunStatus, TrustLevel, WireSandboxReason, WireAuditOutcome, WireAuditCode, WireCachedApproval, WireCachedDecision, WireToolVerdict, WireToolGateAxis, WireSecurityResponse, WireRewindScope, WireRewindRequest, WireCheckpointSummary, WireRewindPreview, WireRewindResponse, ActiveAgentRole, WireSettingValue, WireSettingLayer, WireSettingWriteLayer, WireSettingFutile, WireSettingApply, WireSettingValueKind, WireSettingsResponse, EpochConfig, WireCompressionLine, WireProviderSummary, WireToolSummary, Diagnostic, WireReplayMessage, WireFileChange, WireAuthGuard, WireWorkspaceDiffResponse, BackgroundTaskInfo, WireTasksResponse, WireBackgroundTask, WireScheduleRow } from '@epoch-agent/protocol';
+import { SerializableApprovalRequest, SerializableQuestionRequest, ApprovalRevokeResult, LevelChangeResult, WorkspaceFilesView } from '@epoch-agent/runtime';
+import { ServerResponse } from 'node:http';
 
 /**
  * 绑定策略 —— 「监听哪儿、给不给 token、拒不拒绝启动」。
@@ -396,6 +397,12 @@ interface RoleAddView {
     description: string;
     prompt?: string;
     tools?: readonly string[];
+    /**
+     * 技能索引白名单（2026-08-27）。⚠️ **这一层不校验它**，和 `tools` 刻意不同 ——
+     * 判据全文在 protocol 的 `WireRoleAddRequest.skills` 上（技能表会在会话中途变，
+     * 把「此刻没装」判成 400 是拒掉一个明天就成立的名字）。
+     */
+    skills?: readonly string[];
     maxTurns?: number;
 }
 /**
@@ -536,11 +543,18 @@ type ImportResultView<T> = ({
     issues?: readonly IssueView[];
 };
 /**
- * `SkillControl`（runtime）在服务端眼里的样子 —— **只有这两个动作**。
- *
- * 镜像里只有它们，于是这个包**写不出** `SkillSystem` 上那六个写方法、
- * 也写不出会 `matchCount++` 的 `view()` 和会自动删技能的 `maintain()`：
- * 那不是靠 review 盯住的，是编译期的事（同 `McpControlView` 只有 reconnect）。
+ * `SkillControl`（runtime）在服务端眼里的样子 —— **只有导入那两个动作**。
+ *
+ * 镜像里只有它们，于是这个包**写不出** `SkillSystem` 上那几个写方法、
+ * 也写不出会 `matchCount++` 的 `view()`：那不是靠 review 盯住的，
+ * 是编译期的事（同 `McpControlView` 只有 reconnect）。
+ *
+ * ⚠️ **「删一条技能」不在这张镜像里，它自己有一张**
+ * （[skill-remove.ts](./skill-remove.js) 的 `SkillRemoveControlView`），
+ * 而 `RuntimeCapabilities.skillWrite` 声明成两张的**交集**。镜像跟着 handler
+ * 走、而不是跟着 runtime 那一格走，是这一套收窄能起作用的前提：一张把两件事
+ * 都装进来的镜像，等于任何一个 handler 都能顺手调另一件事 —— 判据同
+ * `capability.ts` 上 `mcp` 那一格。
  */
 interface SkillImportControlView {
     preview(source: string, lang?: Lang): Promise<ImportResultView<{
@@ -549,6 +563,83 @@ interface SkillImportControlView {
     import(source: string, token: string, lang?: Lang): Promise<ImportResultView<ImportDoneView>>;
 }
 
+/**
+ * 删掉一条技能的那一条端点（2026-09-01）：
+ *
+ * ```
+ * POST /api/skills/remove   {name}   → 递归删掉 ~/.epoch/skills/<分类>/<名字>
+ * ```
+ *
+ * 起因是一句话：**能加就得能删**。在这之前能力页技能那一栏只有「导入技能」，
+ * 拿掉一份得让用户自己去 `~/.epoch/skills/` 里翻目录 —— 而那一栏里的每一行
+ * 都是每一轮都在花钱的常驻开销（行尾那个 tokens 数就是它）。
+ *
+ * ## 一、为什么是 POST，为什么没有 token
+ *
+ * POST 和导入那两条同一条判据（`auth.ts` 的 Origin 校验只在非安全方法上要求，
+ * 而这条会在用户机器上真的删文件）。**但没有「预览 → 确认」那一对**，
+ * 而那不是省事：
+ *
+ * - 导入那个 token 防的是「用户看过的那一份」和「真装上的那一份」不是一份 ——
+ *   预览和导入之间目录可能被改过。删除这边没有这条缝：**要删掉的东西由名字
+ *   唯一确定**（技能名在 `SkillSystem` 里是全局唯一的 map 键），而不是由一次
+ *   扫描的结果确定；
+ * - 删除的风险不是「删错了一份」，是**不可撤销**（`rmSync(recursive)`，没有
+ *   回收站）。挡它的是另外两样东西：界面上那一步「再按一次确认」，
+ *   和回执里那个 `path` —— 用户得看得见自己刚销毁了盘上的哪一处。
+ *
+ * ## 二、⚠️ 这条**不吃 `refusedByLan`**，而那是一个判断
+ *
+ * 插件那几个写口和 `POST /api/roles` 都要求回环绑定才给写。这一条不要求，
+ * 判据是：**导入那条也不要求**。只给删除加一道闸的结果，是 `--host 0.0.0.0`
+ * 那一档下技能变成「只能加不能删」—— 那正是这次要修的病，换个地方原样长回来。
+ *
+ * 两条一起加闸不行（那是把已经在用的导入功能收回去），所以这一格的口径是
+ * 「和导入同档」。真要收，得两条一起收，而那是一次独立的决定 ——
+ * 别只改这半边。
+ *
+ * ## 三、只有**用户级**删得掉，而那道闸不在这一层
+ *
+ * 项目级 / 插件 / 宿主那三档 `SkillSystem.requireWritable()` 会抛，
+ * runtime 的 `SkillControl.remove` 把它翻成 `reason: 'readonly'` 加上 core
+ * 那句带路径的原话。这一层**不自己判 scope** —— 判两遍会有一天判得不一样，
+ * 而只有 core 那一遍碰得到磁盘。
+ *
+ * 界面上那颗按钮只画在用户级那一组的行上，但那是**体贴，不是安全性质**：
+ * 手搓一条 `POST /api/skills/remove {"name":"项目里那条"}` 会拿到 200 +
+ * `ok:false` + `readonly`。
+ *
+ * ## 四、失败是 200，判据在 `WireSkillRemoveResponse` 上
+ *
+ * 四个 `reason` 各对一个不同的下一步（那张表在 protocol 那个类型上）。
+ * `detail` 那句话在 **core / runtime** 里现渲染，所以 `lang` 要从这一层
+ * 一路递下去 —— 这条病 2026-08-18 在导入那一屏上实测见过一次
+ * （判据在 [skill-import.ts](./skill-import.js) 文件头倒数第三节）。
+ */
+
+/** 删成了那一下回的东西（runtime 的 `SkillRemoveDone`） */
+interface RemoveDoneView {
+    name: string;
+    path: string;
+}
+type RemoveResultView = ({
+    ok: true;
+} & RemoveDoneView) | {
+    ok: false;
+    reason: WireSkillRemoveFailure;
+    detail: string;
+};
+/**
+ * `SkillControl`（runtime）在服务端眼里的样子 —— **只有 `remove` 一个动作**。
+ *
+ * 和 [skill-import.ts](./skill-import.js) 那张镜像刻意分开，理由在那张镜像的
+ * ⚠️ 上：镜像跟着 handler 走，于是**这个文件里写不出 `import`**，
+ * 而 `RuntimeCapabilities.skillWrite` 是两张的交集（同 `mcp` 那一格）。
+ */
+interface SkillRemoveControlView {
+    remove(name: string, lang?: Lang): Promise<RemoveResultView>;
+}
+
 /**
  * 能力页的取数与投影 —— `GET /api/sessions/:id/capabilities`（方案 42 PR-1），
  * 外加技能正文那条下钻（方案 56 §1.2）。
@@ -608,15 +699,32 @@ interface RoleView {
     name: string;
     description: string;
     tools?: readonly string[];
+    /**
+     * 技能索引白名单（`AgentRole.skills`，2026-08-27）。⚠️ **镜像上漏掉这一格不会
+     * 红** —— 真源上它是可选的，少声明照样满足这份镜像，表现只是 `toWireRole()`
+     * 一声不吭地读不到它（判据同下面 `McpView.source` 那条 ⚠️）。它是这一屏上
+     * 「一个身份自己声明了哪几条技能」的唯一来源。
+     */
+    skills?: readonly string[];
     maxTurns?: number;
     source: 'builtin' | 'user' | 'project' | 'plugin' | 'host';
 }
 /**
- * `RoleMergeNotice` 的镜像。**只取 `role` 和 `cut`** —— `detail` 是中文文案，
- * 浏览器要用自己的 catalog 组句（同诊断的规矩），下发它等于让英文界面照抄中文。
+ * `RoleMergeNotice` 的镜像。**只取 `role` / `kind` / `cut`** —— `detail` 是中文
+ * 文案，浏览器要用自己的 catalog 组句（同诊断的规矩），下发它等于让英文界面
+ * 照抄中文。
+ *
+ * ⚠️ **`kind` 这一格是必须的，不是「顺手多带一样」**（2026-08-27）。加上它之前
+ * 这一族 notice 全是工具收窄，于是 `toWireRole()` 里一句 `find(n => n.role === …)`
+ * 就够了；技能收窄一旦也产 notice，那句 `find` 会**抓到技能那一条并把技能名画成
+ * 划掉的工具芯片** —— 两边都是 `string[]`，编译器一个字都不会说。
+ * 记账全文在
+ * [RECORD-skill-index-narrowing](../../../docs/verify/VERIFY_RECORD-skill-index-narrowing.md) §四第 3 条。
  */
 interface RoleNoticeView {
     role: string;
+    /** 收窄的是哪一轴。真源是 core 的 `RoleMergeNotice.kind` */
+    kind: 'tools' | 'skills';
     cut: readonly string[];
 }
 /** `SkillMeta` 在服务端眼里的样子。`scope` 同上一条 ⚠️ */
@@ -662,12 +770,29 @@ interface RuntimeCapabilities {
      */
     skillBody(name: string): string | null;
     /**
-     * 从**本机目录**导入技能（方案 42 §六）。**进程级**，同 {@link mcp}。
+     * 每条技能此刻进没进索引，名字 → 三档（2026-08-27）。**这一层不自己算** ——
+     * 判据是它算不出来：封顶的丢弃顺序（`DROP_RANK`）和角色白名单的交集语义
+     * 都在 core 的 `prompt-index.ts` 里，而这个包不许 import core。按
+     * `role.skills.includes()` 在这儿再判一遍就是第二份实现，
+     * 而它和真索引分叉之后两边都答得出「我算了」。
+     */
+    skillIndexResidency(role: string | null): ReadonlyMap<string, 'indexed' | 'capped' | 'role'>;
+    /**
+     * 技能目录的写口：从**本机目录**导入（方案 42 §六）+ 删掉一条用户级技能
+     * （2026-09-01）。**进程级**，同 {@link mcp}。
      *
-     * ⚠️ 它收的是**路径**不是字节 —— 那是这条路上的安全性质本体，判据全文在
+     * ⚠️ 导入收的是**路径**不是字节 —— 那是那条路上的安全性质本体，判据全文在
      * [skill-import.ts](./skill-import.js) 的文件头。
+     *
+     * ⚠️ **交集，理由逐字同下面 {@link mcp} 那一格**：两个动作挂在同一个 runtime
+     * 对象上（`runtime.skillWrite`），分成两份声明是为了让镜像跟着 handler 走 ——
+     * 于是 `skill-import.ts` 里写不出 `remove`、`skill-remove.ts` 里写不出 `import`。
+     *
+     * ⚠️ **删除那条刻意不吃 `refusedByLan`**，和导入同档；那是一个判断而不是遗漏，
+     * 判据全文在 [skill-remove.ts](./skill-remove.js) 文件头第二节 ——
+     * 要收得两条一起收。
      */
-    readonly skillImport: SkillImportControlView;
+    readonly skillWrite: SkillImportControlView & SkillRemoveControlView;
     /**
      * MCP 的写口：重连一台（方案 56 §1.1）+ 加一台（2026-08-18）+ **那份文件的原文
      * 读写与应用**（2026-08-18）。**全都是进程级**。
@@ -706,6 +831,14 @@ interface RuntimeCapabilities {
  *
  * @param bound 这个会话绑的工作区（`workspaces.of(sessionId)`）。没绑就是 null，
  *   那时「项目」那一层整个不存在 —— 不是「有但是空的」
+ * @param role 这个会话的**底座身份名**（`LiveSession.role?.name`），没绑就是 null。
+ *   只有技能那一栏读它：一个带 `skills` 白名单的身份会让某几条技能不进索引，
+ *   于是那几行行尾那个「常驻开销」是假话（2026-08-27 那笔账）。
+ *
+ *   ⚠️ **它是必传的一格，不是可选参数。** 这个函数今天只有一个调用方，加个
+ *   默认 `null` 只会让下一个调用方在**默认不收窄**这条路上静默走对一半 ——
+ *   而走错的表现是屏幕上多出一个假数字，没有任何东西会红。判据同
+ *   `toWireSkill` 的 `residency` 那一格。
  */
 declare function collectCapabilities(runtime: RuntimeCapabilities, tools: readonly {
     name: string;
@@ -717,7 +850,7 @@ declare function collectCapabilities(runtime: RuntimeCapabilities, tools: readon
     trust: {
         trusted: boolean;
     };
-} | null): WireCapabilitiesResponse;
+} | null, role: string | null): WireCapabilitiesResponse;
 /**
  * 一份 `SKILL.md` 最多发多少字节。形状照
  * [workspace/diff.ts](./workspace/diff.ts) 的 `MAX_DIFF_BYTES`。
@@ -980,6 +1113,138 @@ interface ExpansionOutcome {
  */
 declare function expandUserContent(runtime: RuntimeCommands, message: EpochUserContent, model: ModelTurnsView | null, role: TurnRole | null): ExpansionOutcome;
 
+/**
+ * `WebRuntimeView.goalCatalog` —— **server 从 runtime 借的目标那一片**
+ * （[方案 52](../../../../docs/verify/VERIFY_RECORD-52-goal.md) PR-4）。
+ *
+ * ## 为什么是一份结构镜像，而不是 `import type { GoalCatalog }`
+ *
+ * 判据逐字同 [schedule/view.ts](../schedule/view.js)，两条，第二条是硬的：
+ *
+ * 1. **`context.ts` 那句话**：这一层只借「用得到的那一小片」。`GoalCatalog` 的
+ *    每个方法都回 core 的 `Goal` / `GoalWrite` / `GoalClear` —— 借整个接口等于
+ *    让 `@epoch-agent/server` 的公开 `.d.ts` 引用一个它没声明依赖的包；
+ * 2. **用例要造得出一个假的**。`server/__tests__/harness.ts` 的假 runtime 是手写
+ *    对象。镜像用 protocol 的类型写完之后，那个假件一行 core 都不用碰。
+ *
+ * ⚠️ **镜像必须和真身逐字段对得上**，否则 `cli/src/commands/web.ts` 那一行
+ * `createWebServer({ runtime })` 当场编译不过 —— 那正是这份镜像的全部强制力。
+ *
+ * ## ⚠️ 借的是 `goalCatalog` 而**不是** `goals`，这一条是这个文件的正题
+ *
+ * `EpochRuntime` 上有两格，答的是两个问题：
+ *
+ * ```
+ * runtime.goals        「**引导会话**那一段的目标」   GoalControl（收窄到一段）
+ * runtime.goalCatalog  「**任意一段**会话的目标」     GoalCatalog（按 id 现查）
+ * ```
+ *
+ * 借前者的下场，这个仓库已经付过一次账了：`WebRuntimeView` 上原来有一个进程级的
+ * `checkpoints`，而三条回退端点都在拿它答任意一个 sessionId ——「编译得过、跑得通、
+ * 只是答错会话」（方案 30 §9.5）。那个字段 2026-08-15 删掉了，`context.ts` 上那段
+ * ⚠️ 写着为什么。这一格从第一天起就借对的那一份。
+ *
+ * ## 为什么不像检查点那样「向工厂要这个会话自己那一份」
+ *
+ * 因为**目标没有内存态**。`GoalService` 每次现读 SQLite（`GoalStore.current`），
+ * 于是「这段会话此刻活不活着」和「它的目标是什么」是两个无关的问题：
+ *
+ * | 那一格         | 真源                       | 冷却掉的会话答得出吗 |
+ * | -------------- | -------------------------- | -------------------- |
+ * | 检查点         | 这个进程的 `CheckpointManager` | ❌ 只能回空列表   |
+ * | 计划           | 内存那份优先，回退读盘     | ⚠️ 读盘那份可能旧    |
+ * | **目标**       | **只有 SQLite 一份**       | ✅ 一样准            |
+ *
+ * 走工厂那条路的话，用户打开一段昨天的会话会看到「这个会话还没有目标」——
+ * 而库里那条目标正躺在那儿，那正是「交代完走开」这份方案要修的病本身。
+ *
+ * ## ⚠️ 这里**没有** `block()`
+ *
+ * runtime 那一侧的 `GoalCatalog` 上也没有（判据在它的 JSDoc 上）：`blocked` 是
+ * 模型 / 策略层的态，而那个 `code` 是给程序路由用的键 —— 从 HTTP 这一侧露出一条
+ * 报 `blocked` 的路，等于让浏览器编一个 `needs-approval` 出来，而那个方向是提权
+ * （52 §5.1 结论 3）。网线上那份请求体里同样说不出这个态
+ * （`WireGoalUpdateRequest` 只有三态），**两道各自独立**：这一道是编译期的，
+ * 那一道是契约上的，少任何一道另一道都会变成唯一的防线。
+ */
+
+/**
+ * core 的 `Goal` 在服务端眼里的样子。
+ *
+ * **没有 `id`** —— 那是 `goals` 表的主键，这一层拿它什么都做不了（一个会话至多
+ * 一个目标，寻址靠 sessionId）。镜像上没有它是**编译期生效**的：投影里写不出
+ * `goal.id`，写了当场不过。判据同 `CheckpointSummaryView` 那处「没有 `cursor`」。
+ *
+ * `sessionId` **留着**，和 `id` 刻意不同：跨会话那条端点要拿它去查标题。
+ */
+interface GoalView {
+    sessionId: string;
+    objective: string;
+    phase: WireGoalPhase;
+    /** `phase === 'blocked'` 时必有，其余态必无 */
+    block?: {
+        readonly code: string;
+        readonly message: string;
+    };
+    maxRounds: number;
+    roundsUsed: number;
+    /** `phase === 'complete'` 时必有 */
+    completeEvidence?: string;
+    createdAt: number;
+    updatedAt: number;
+}
+/**
+ * 一次写的结果 —— core 的 `GoalWrite`。
+ *
+ * **判别联合原样照抄，不摊平成 `{ok, goal?, reason?}`**：摊平之后
+ * 「`ok: true` 却没有 goal」在类型上说得出口，而 handler 那一侧只能补一个
+ * `?? null` —— 那个 `null` 会一路走到网线上，界面读成「写成功了但目标没了」。
+ */
+type GoalWriteView = {
+    ok: true;
+    goal: GoalView;
+} | {
+    ok: false;
+    reason: WireGoalRefusal;
+};
+/** `clear` 的结果 —— core 的 `GoalClear`。它没有「写完之后那份目标」 */
+type GoalClearView = {
+    ok: true;
+    cleared: boolean;
+} | {
+    ok: false;
+    reason: WireGoalRefusal;
+};
+/**
+ * 目标那一片能力。`EpochRuntime.goalCatalog` 结构上正好满足它。
+ *
+ * ## ⚠️ 可以为 null，而这和 `schedules` 那一格刻意不同
+ *
+ * 定时任务那一格不可为 null（底下只有一张表和一次平台探测，没有起不来的可能）。
+ * 这一格**会**为 null：目标是**落盘的状态**，会话库起不来时它整个不存在 ——
+ * 判据逐字同 TUI 那一侧的「会话库起不来时 `/goal` 压根不注册」（那时还让它出现在
+ * `/help` 里，等于承诺一个建了就没的东西）。
+ *
+ * 于是那五条端点在这一档回 **503 `no-goal-store`**，而不是一份 `goal: null`：
+ * 后者是「这个会话没有目标」，前者是「问不出来」，两者在界面上是两种画法
+ * （一个是空态加一个「来定一条」的按钮，一个是一句「这台机器上没有会话库」）。
+ * 判据全文在 `WireGoalResponse` 上。
+ */
+interface GoalCatalogView {
+    current: (sessionId: string) => GoalView | null;
+    /** 建一个。**人专用** —— 判据在 runtime 的 `GoalCatalog.create` 上 */
+    create: (sessionId: string, objective: string, maxRounds?: number) => GoalWriteView;
+    /** 改正文。**不重置轮次、不改 phase** */
+    edit: (sessionId: string, objective: string) => GoalWriteView;
+    /** 改预算。⚠️ 两个方向都会顺手改 phase，判据在 `WireGoalUpdateRequest` 上 */
+    setBudget: (sessionId: string, maxRounds: number) => GoalWriteView;
+    pause: (sessionId: string) => GoalWriteView;
+    resume: (sessionId: string) => GoalWriteView;
+    /** 人替它报完成。依据必填 */
+    complete: (sessionId: string, evidence: string) => GoalWriteView;
+    clear: (sessionId: string) => GoalClearView;
+}
+
 /**
  * SessionHub —— 事件总线 + 回合状态机 + 审批生命周期。
  *
@@ -1319,6 +1584,214 @@ declare class SessionHub {
     private reap;
 }
 
+/**
+ * `@` 提及在 Web 那一侧的两半（方案 53 PR-4 的会话 + 方案 63 的文件）——
+ * 补全面板的候选，和发消息那条路上的解析。
+ *
+ * ## 四件事，一个文件
+ *
+ * | 做什么                        | 谁调                                  |
+ * | ----------------------------- | ------------------------------------- |
+ * | `GET .../reference-candidates` | 输入框打 `@:` 那一刻（方案 53 PR-4）  |
+ * | `GET .../file-candidates`      | 输入框打 `@文件` 那一刻（方案 63）    |
+ * | 把解析结果塞进这一条消息      | `api.postMessage`（每条消息都问一次） |
+ *
+ * 不摊进 [api.ts](./api.ts)，理由同 [commands.ts](./commands.js)：那个文件是
+ * 「一个端点一个函数」，而这里有一份 runtime 能力的**结构镜像**加一段提及解析。
+ *
+ * ## ⚠️ 引擎那一侧一行都不重写 —— 这是这一整份的性质
+ *
+ * 三样东西全部来自 `EpochRuntime.sessionReferences`（判据在它的 JSDoc 上）：
+ *
+ * - **候选**（只碰 id / cwd / 标题，一个字的转录文本都不搜，§5.2）
+ * - **解析**（`@:xxx` → 哪一段，或者为什么不是）
+ * - **当前面**（`active = 1` 的那些，§二）
+ *
+ * 而这三样里最要紧的是**可读性判定**：它在 core 里、和[方案 48](../../../docs/verify/VERIFY_RECORD-48-session-query.md)
+ * 共用一处（`core/src/session/authorization.ts` 的 `resolveSessionVisibility`，
+ * 判据全文在那个文件头）。让服务端自己去读 `sessions.db`
+ * 等于给 `@:` 开一条绕过那个判定的读取通道 —— 而 `@:` 存在的前提恰恰是
+ * 「它永远不比 `session_search` 宽松」（方案 53 §4.3）。
+ *
+ * 上限那张表和截断那段算术也不在这儿：它们住在 protocol
+ * （`attachSessionSurface`），和 TUI 那条路**共用同一份**。抄第二遍的形态很具体：
+ * TUI 上一段会话附了 48 条、web 上同一段附了 60 条，两边都不报错，
+ * 而「模型到底看见了什么」从此有两个答案。判据全文在 protocol 的 `mentions.ts`。
+ *
+ * ## `@文件` 那一半（方案 63）的行状
+ *
+ * - **候选**走 `EpochRuntime.workspaceFiles.candidates`（runtime 的收窄面）：
+ *   过滤、`@` 表达不出来的去尾、排序、缓存全在那一侧（判据在那个文件的文件头），
+ *   这里只做「按 `:id` 现算工作区根 → 递进去 → 搬上网线」三件事。
+ * - **解析**走同一条路的两步：`resolve` 出界 = `denied`，`readFile` 一趟走完
+ *   边界 / `file_read` 同源判定 / 二进制探测（失败三档码见 runtime 的
+ *   `FileReadOutcome`）。**服务端这里没有一个字的文件读取** —— 判据同上面
+ *   「让服务端自己去读 sessions.db」那一条：`@` 存在的前提是它永远不比
+ *   `file_read` 宽松，而判定只有权限层那一份。
+ * - **预算**：文件先吃、会话后到，两者共享同一本 200KB 的账 —— 判据逐字同
+ *   `core/src/context/mentions.ts` 的 `resolveMentions`（反过来的话两个小文件
+ *   会被一段长会话挤成 `budget-exceeded`，而用户显然更想要那两个文件）。
+ *
+ * ## 这一层自己拿的两个决定
+ *
+ * 1. **`currentSessionId` 一律是 URL 上那个 `:id`，不是 `runtime.sessionId`。**
+ *    后者是**引导会话**。拿它去答别的会话，表现是「引用自己」判不出来
+ *    （于是真的把自己塞进自己）、血缘链算成另一段会话的 —— 而它编译得过、
+ *    跑得通、只是答错会话（同 `EpochRuntime.checkpoints` 那段 ⚠️ 骂的那件事）。
+ * 2. **工作区取 `projectContext.rootDir`，不是 `workspace.root`。**
+ *    两者在「在子目录里起的那次会话」上不同（前者是仓库根，后者是启动目录），
+ *    而写入侧往 `sessions.cwd` 里写的是前者（判据在 `core/src/session/manager.ts`
+ *    的 `getLatestByCwd` 和 `authorization.ts` 的 `workspaceCwd` 上）。
+ *    给错的表现是**一条候选都列不出来**，而屏幕上只是一个空面板。
+ */
+
+/**
+ * 候选清单一次最多回几条。
+ *
+ * 面板上放不下更多，而这个数同时是那条 SQL 的 `LIMIT` —— 用户打得越细，
+ * 回来的越少（过滤在 SQL 里，见文件头）。
+ *
+ * ⚠️ **它不是 TUI 那个 `SESSION_CANDIDATE_POOL`。** 那一个是「挂载时拉一池子回来、
+ * 之后在前端筛」，于是第 41 段会话**永远搜不到而且屏幕上没有提示**（那笔账记在
+ * `docs/verify/VERIFY_RECORD-53-session-reference.md` 第六章）。这一条路每次带着
+ * `?q=` 现问，所以这个数只封「一屏列多少」，不封「能搜到哪几段」。
+ */
+declare const MAX_CANDIDATES = 20;
+/**
+ * 一段会话候选在引擎眼里的样子（core 的 `SessionCandidate`）。
+ *
+ * ⚠️ **和网线那一份（{@link WireSessionCandidate}）字段逐个相同，而它们仍然是两个
+ * 类型**：这一份是镜像（server 不许 import core），那一份是契约。所以
+ * {@link toWireCandidate} 是一次**显式**的搬运而不是 `as` —— 哪天引擎那侧加了一个
+ * 带转录文本的字段（`preview`），它不会顺着 spread 悄悄上网线。
+ */
+interface SessionCandidateView {
+    sessionId: string;
+    title: string;
+    cwd?: string | undefined;
+    updatedAt: number;
+    messageCount: number;
+    sameWorkspace: boolean;
+}
+/** 解析的结果（core 的 `ResolvedReference`）。三个码见方案 53 §4.2 */
+interface ResolvedReferenceView {
+    sessionId?: string | undefined;
+    reason?: 'invalid-reference' | 'self-reference' | 'not-authorized' | undefined;
+}
+/** 一次可读范围的入参。三格逐字同 core 的 `SessionVisibilityInput`（去掉 `db`） */
+interface VisibilityInput {
+    /** 谁在引用 —— **URL 上那个 `:id`**，见文件头第 1 条 */
+    currentSessionId: string;
+    /** 项目根（`projectContext.rootDir`），见文件头第 2 条 */
+    workspaceCwd?: string | undefined;
+    /** 跨工作区。只能来自已经打开了配置开关的那条路 */
+    allWorkspaces?: boolean;
+}
+/**
+ * `EpochRuntime.sessionReferences` 在服务端眼里的样子 —— **三个方法，一个不多**。
+ *
+ * 写镜像而不是 import core，判据同 `commands.ts` / `capability.ts` 的文件头。
+ * 而这一格还多一条：它收窄的东西本身就是一条安全边界 ——
+ * 那份门面刻意「交不出任意 SQL」（`SessionReferences` 的 JSDoc），
+ * 镜像照着它抄，服务端就连绕过判定的**语法**都没有。
+ *
+ * `EpochRuntime.sessionReferences` 结构上正好满足它，
+ * 对不上就是两边长歪了，`cli/src/commands/web.ts` 那一行当场编译不过。
+ */
+interface SessionReferencesView {
+    /** 补全面板的候选。**只按 id / cwd / 标题过滤**（§5.2） */
+    candidates(input: VisibilityInput & {
+        query: string;
+        limit: number;
+    }): readonly SessionCandidateView[];
+    /** `@:xxx` → 哪一段会话（§1.2） */
+    resolve(input: VisibilityInput & {
+        ref: string;
+    }): ResolvedReferenceView;
+    /** 那一段会话的当前面（§二）。**调用方要先过 `resolve`** */
+    surface(sessionId: string): SessionSurfaceView | undefined;
+}
+/**
+ * `GET /api/sessions/:id/reference-candidates` —— 打 `@:` 那一刻面板该列哪几段。
+ *
+ * `:id` 做两件事，同 `tasks.ts` 的那两件：**认门**（不存在的会话 404，不回一份空
+ * 清单冒充「没有可引用的会话」），以及**真的参与判定** —— 自己不在候选里、
+ * 血缘链从它算起、亲和度按它绑的工作区排。
+ *
+ * ## 会话库起不来时 503，不是空清单；而且 503 **排在 404 前面**
+ *
+ * 判据同 `no-goal-store`（`goal/handlers.ts`）：「这个宿主没有会话库」和
+ * 「一段可引用的会话都没有」在界面上是两种画法；而顺序上，没有会话库的进程连
+ * 「认不认识这个会话」都答不出来（`ctx.runtime.sessions` 是**同一个库**），
+ * 那时的 404 是一句碰巧为真的话。
+ *
+ * 浏览器那一侧对两者的处置恰好相同（面板不画，见 `mention/use-candidates.ts`）——
+ * 那是浏览器的选择，不是服务端可以把两句话合成一句的理由。
+ */
+declare function listReferenceCandidates(ctx: ApiContext, res: ServerResponse, sessionId: string, 
+/** `?q=` / `?limit=` 从这儿取 */
+rawUrl: string | undefined, 
+/** 这一次响应用哪个语言渲染（方案 58）。`undefined` = 这条请求没说，沿用进程语言 */
+lang?: Lang): void;
+/**
+ * `GET /api/sessions/:id/file-candidates` —— 打 `@`（后面不是 `:`）那一刻
+ * 面板该列哪几个文件（方案 63）。
+ *
+ * ## 和 `reference-candidates` 同一条路由判据的两处小差异
+ *
+ * 1. **没绑工作区时 409 `no-workspace`**，而不是像会话那条路那样「有库就能答」：
+ *    文件清单压根是**从工作区算出来的**，没有根连「列不出来」这一档都不存在。
+ *    409 而不是 404：这个会话认得，是它的**状态**（还没选地盘）给不出答案 ——
+ *    同 `workspace-locked` 那条的拆码判据。
+ * 2. **`?q=` 过滤在 runtime 那一侧**（`EpochRuntime.workspaceFiles.candidates`），
+ *    判据同会话那条路的「过滤在 SQL 里」：拉一池子回来再在前端筛，
+ *    池子之外的永远搜不到而且屏幕上没有提示。
+ *
+ * 候选**已经是「提交时会被认出来」的那一批**（`@` 表达不出来的路径 runtime 已
+ * 经去尾，只把条数带回来 —— 见 `WireFileCandidatesResponse.unmentionable`）。
+ * 服务端这里一个字都不再筛：再筛一遍就是给同一件事第二个答案。
+ */
+declare function listFileCandidates(ctx: ApiContext, res: ServerResponse, sessionId: string, 
+/** `?q=` / `?limit=` 从这儿取 */
+rawUrl: string | undefined, 
+/** 这一次响应用哪个语言渲染（方案 58）。`undefined` = 这条请求没说，沿用进程语言 */
+lang?: Lang): void;
+/** {@link attachMentions} 的结果 */
+interface AttachedMentions {
+    /** 真正发给引擎的那条消息。一个提及都没有时 === 传进来的那条 */
+    message: EpochUserContent;
+    /** 逐段一条会话收据。**一段都没引用时是空数组**，调用方据此决定那个键要不要出现 */
+    references: readonly WireSessionReference[];
+    /** 逐个一条文件收据。**一个都没提时是空数组**，判据同上面那个键 */
+    files: readonly WireFileReference[];
+}
+/**
+ * 把这条消息里的 `@` 提及（文件 + 会话）解析成部件，塞在正文**前面**
+ * （方案 53 §二 + 方案 63）。
+ *
+ * ## 三条顺序上的判据
+ *
+ * 1. **抽取读的是用户敲的那一行**，也就是这条消息开头那段文本。数组那一支
+ *    只看第一个部件（同 `commands.ts` 的 `leadingText`）—— 输入框拼数组时文本
+ *    永远在最前面。
+ * 2. **部件排在文本前面**，逐字同 TUI（`app.tsx` 的 `handleSubmit`）：
+ *    模型先看见「这是哪个文件 / 哪段会话」再看见问题，和「工具结果先于追问」
+ *    同一个顺序。
+ * 3. **这一步排在斜杠命令展开之后**（见 `api.postMessage`）。反过来的话，
+ *    展开那一侧的 `leadingText` 拿到的第一个部件是附件而不是文本，
+ *    于是**斜杠命令悄悄失效** —— 而屏幕上没有任何区别。
+ *
+ * ## 预算：文件先吃、会话后到，两者共享同一本 200KB 的账（方案 63）
+ *
+ * 顺序逐字同 core 的 `resolveMentions`：会话的当前面动辄几十 KB，而文件提及是
+ * 高频的那一种。反过来的话，一次 `@:某个长会话 @a.ts @b.ts` 会让两个小文件
+ * 双双 `budget-exceeded` —— 而用户显然更想要那两个文件。
+ *
+ * ⚠️ **从 2026-08-26 起这条路上有两个消费方了**：`usedBytes` 不再从 0 起算，
+ * 会话那一半排在文件那一半**之后**，拿到的预算是扣掉文件之后的余额。
+ */
+declare function attachMentions(ctx: ApiContext, sessionId: string, message: EpochUserContent): AttachedMentions;
+
 /**
  * 一个会话自己那三样（模型 / 权限档 / plan 模式）在**服务端眼里**的样子
  * （[方案 30](../../../../docs/verify/VERIFY_RECORD-30-web-multi-session.md) §六，2026-08-16）。
@@ -1490,7 +1963,16 @@ interface SessionPermissionsView {
     managed(): {
         bypassDisabled: boolean;
     };
-    setLevel(level: PermissionLevel): SetLevelView;
+    /**
+     * @param opts.remember 这一发**算不算用户显式挑的**（2026-08-31）。
+     *   ⚠️ **照抄真身的必填形状**（runtime 的 `SessionPermissions.setLevel`），
+     *   别在这份镜像上写成可选的：真身那边这个参数存在的理由是「定时任务和用户
+     *   菜单共用同一个方法」，写成可选之后，漏传的那一方会静默拿到默认行为 ——
+     *   而那正是这个参数要防的东西。三行表在 runtime 的 `DefaultLevelSlot` 上。
+     */
+    setLevel(level: PermissionLevel, opts: {
+        remember: boolean;
+    }): SetLevelView;
 }
 /**
  * 一次换档的结果。**只有码，没有句子** —— 措辞归浏览器的两份 catalog
@@ -1498,6 +1980,14 @@ interface SessionPermissionsView {
  */
 type SetLevelView = {
     ok: true;
+    /**
+     * 「换成了，但没记住」（2026-08-31）。**只在真没记住时有值** ——
+     * 它直接转成 `WirePermissionSetResponse.notRemembered`，判据在那儿。
+     */
+    notRemembered?: {
+        reason: WirePermissionRememberFailure;
+        path?: string;
+    };
 } | {
     ok: false;
     reason: 'managed-bypass-disabled';
@@ -1546,6 +2036,51 @@ interface SessionHistoryFacts {
         }[];
     }[];
 }
+/**
+ * 「这段会话的上下文预算怎么花的」+「现在压一次」—— `/context` 和 `/compact`
+ * 那两条命令在 web 上的底座（2026-08-26）。
+ *
+ * ## 为什么和上面 {@link SessionHistoryFacts} 分开，而不是把它加宽
+ *
+ * 两者都要 `getHistory()`，但**要的是同一串东西的两个不同投影**：那一份问
+ * 「有没有 `type: 'image'` 的 part」，这一份要 `content` 那个文本投影去估 token。
+ * 把 `content` 加进那一份的代价是换模型那条路上凭空多出一个它不看的字段 ——
+ * 而收窄镜像这件事的全部意义就是「只借用得到的那几格」。
+ *
+ * ⚠️ **`compact()` 在这儿而不在别处，因为它换掉的是 `AgentSession.history`**
+ * ——「下一轮送进模型的是什么」。它**不动会话库**，所以 `GET /messages`
+ * 压完之后一行都不会少（判据全文在 `WireCompactResponse` 上）。
+ */
+interface SessionContextFacts {
+    /**
+     * 历史的**文本投影**。`content` 就是那个投影本身（见 core 的 `EpochMessage`），
+     * 拼起来算 token 比逐条估更接近真实发出去的量。
+     */
+    getHistory(): readonly {
+        content: string;
+    }[];
+    /** 手动压一次。三种结局（没跑 / 跑了没压动 / 压了）全在返回值里，见 `WireCompactResponse` */
+    compact(instruction?: string): Promise<{
+        ran: boolean;
+        before: number;
+        after: number;
+        reason?: string;
+    }>;
+}
+/**
+ * **这个会话的循环**在服务端眼里的样子。只借 `contextBreakdown` 一件事。
+ *
+ * ⚠️ **别拿它去 `run()`**，runtime 的 `LiveSession.agent` 上那段警告一字不改地
+ * 适用：开一轮必须经过 `AgentSession`（历史累积 + 持久化 + 审批桥），
+ * 绕过去的表现是「聊完之后重开这个会话，刚才那几轮不见了」。镜像上只有这一个
+ * 方法，正是为了让那条路在这一层**够不着**。
+ */
+interface SessionLoopView {
+    contextBreakdown(opts: {
+        historyText: string;
+        toolSource?: (name: string) => string | undefined;
+    }): ContextBreakdown;
+}
 
 /**
  * 这个会话**此刻**用哪个模型 —— `GET` / `POST /api/sessions/:id/model`
@@ -1728,10 +2263,218 @@ interface RuntimeModel {
 }
 
 /**
- * 「我们支持哪几家、这一家有哪些模型」 —— `GET /api/providers` 和
- * `POST /api/providers/:type/models`。
+ * 插件那一页的六条端点（方案 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` 那一片里（判据全文在
+ * `runtime/src/plugin-control.ts` 的文件头四节）。这个文件只做三件事：
+ * 把请求体收窄成那一片认得的形状、把结局投影上网线、外加下面那**一道闸**。
+ *
+ * 在这儿重判一次的下场是「同一个问题两个答案」——而那两个答案分叉的那天，
+ * 界面上是一条画成可点、点了却被拒的行（判据同 `PluginSearchHit.installable`
+ * 为什么不从结果里剔掉远程那条）。
+ *
+ * ## ⚠️ 那一道闸：**五条 POST 在回环之外一律 403**，这是这个文件的正题
+ *
+ * 判据全文在 protocol 的 [wire-plugin.ts](../../protocol/src/wire-plugin.ts) 文件头
+ * 第二节，这里记它对这一层的四条直接后果：
+ *
+ * 1. **`ctx.lanExposed` 为真时 403 `plugin-write-lan-exposed`，一个字节都不写。**
+ *    装一包插件会落下 `hooks.json` 和 `mcp.json`，那两样**起子进程** ——
+ *    下一程启动时照着跑。往 `~/.epoch/agents/` 落一份 md 只影响模型看到的字，
+ *    这一条影响这台机器上会跑起什么进程，所以它比 `role-add.ts` 那道**还远一格**；
+ * 2. **`install/preview` 也吃这道闸，虽然它一个字节都不写**：`allowRemote: true`
+ *    的部署上，预览一条远程条目会 spawn `git clone --depth 1` 到 staging。
+ *    按「写不写盘」切一刀会漏掉它；
+ * 3. **那道闸在读请求体之前**，同 `addRole`：被拒的那一发连正文都不该被解析；
+ * 4. **`GET` 刻意不挡。** 那一份里是插件名 / 版本 / 目录路径，和
+ *    `GET /api/sessions/:id/capabilities` 早就在发的那些同一档 —— 而挡掉它的
+ *    唯一后果是那一页在 LAN 那一档下一片空白，
+ *    偏偏那时用户最想知道的就是「我装了什么、生效了没有」。
+ *    （对比 `GET /api/mcp/config` 为什么连读都挡：那份文件里的 `env` 是明文密钥。）
+ *
+ * ## ⚠️ 这一片可以整个不存在 —— 503 `no-plugin-control`
+ *
+ * `runtime.plugins` 在宿主没给 `hostMarketplaces` 时是 `null`，而那**不是**
+ * 「底下那层起不来了」，是「宿主没打算给用户这条路」（判据在 `build.ts` 那一格的
+ * JSDoc 上）。六条一律 503，判据同 `no-goal-store`：那是一句关于**这个部署**的
+ * 真话，而一份「装了 0 个插件」的空列表会让用户去找一个不存在的安装按钮。
+ *
+ * ⚠️ **默认的 `epoch web` 就落在这一档上**（不给 `--plugins` 就不传
+ * `hostMarketplaces`）。那一格 2026-08-21 答掉了：`epoch web --plugins` 才接上
+ * （传 `{ sources: [] }`），**默认关**，判据在
+ * [验收记录](../../../docs/verify/VERIFY_RECORD-59-plugin-page.md) 第六章。
+ *
+ * ## 为什么单开一个文件
+ *
+ * 同 [role-add.ts](./role-add.ts) 从 `capability.ts` 里搬出来那次，**刀口按题目下
+ * 不按行数**：那个文件答的是「能力页那三栏取什么数」，这一份答的是「怎么往这台
+ * 机器上装一包扩展物」。而且这一份带着一整套结构镜像 + 一道闸门 + 七档拒绝的映射。
+ *
+ * ## 进程级，所以 URL 上没有 `:id`
+ *
+ * 落点是 `~/.epoch/plugins/`（一个进程一份），判据逐字同 `reconnectMcp` /
+ * `importSkills` / `addRole`：挂在 `/sessions/:id/` 下面会得到一条名字是会话级、
+ * 行为是进程级的端点，比不一致更坏。
+ *
+ * ## 文案是**第三种形态**，不是 `sendError`（方案 58 §1.2 那条 📮）
+ *
+ * `detail` 走的是 **200 响应体**，而它在 **runtime / core** 里现渲染
+ * （`plugin_control.*` 那几条 + core 那些安装失败原因），所以 `lang` 要从这一层
+ * 一路穿到 `PluginControlView` 的每一个方法上 —— 漏一处的表现是英文界面上
+ * 装插件失败拿到一句中文。
+ */
+
+/** 六类扩展物各贡献了几条（core 的 `PluginCounts`，不能直接 import） */
+interface CountsView {
+    commands: number;
+    roles: number;
+    skills: number;
+    hooks: number;
+    denyRules: number;
+    mcpServers: number;
+}
+/** `PluginListEntry`（runtime）的镜像。`marketplace` / `counts` 是**可选**，见投影那两行 */
+interface PluginEntryView {
+    name: string;
+    version: string;
+    source: string;
+    sourceType: WirePluginSourceType;
+    path: string;
+    linked: boolean;
+    enabled: boolean;
+    installedAt: number;
+    marketplace?: string;
+    active: boolean;
+    counts?: CountsView;
+}
+/** `PluginSearchHit`（runtime）的镜像 */
+interface PluginHitView {
+    marketplace: string;
+    ref: string;
+    entry: {
+        name: string;
+        description?: string;
+        source: string;
+        category?: string;
+        keywords?: readonly string[];
+    };
+    sourceType?: WirePluginSourceType;
+    installable: boolean;
+}
+/** `InstallPreview`（core，经 runtime 原样透出）的镜像 —— 「将安装什么」那一屏的内容 */
+interface PluginPreviewView {
+    manifest: {
+        name: string;
+        version: string;
+        description?: string;
+        author?: {
+            name: string;
+        };
+        homepage?: string;
+    };
+    source: {
+        raw: string;
+        type: WirePluginSourceType;
+        sha256?: string;
+    };
+    inventory: {
+        commands: readonly string[];
+        roles: readonly string[];
+        skills: readonly string[];
+        hooks: readonly {
+            type: string;
+            count: number;
+        }[];
+        denyRules: number;
+        mcpServers: readonly string[];
+        ignoredBuckets: readonly string[];
+        jsTools: boolean;
+    };
+    conflict?: {
+        name: string;
+        version: string;
+    };
+}
+/** 七档拒绝的共同形状（runtime 的 `PluginRefusal`） */
+interface RefusalView {
+    ok: false;
+    reason: WirePluginRefuseReason;
+    detail: string;
+}
+type PreviewOutcomeView = {
+    ok: true;
+    preview: PluginPreviewView;
+    token: string;
+} | RefusalView;
+/**
+ * 装 / 更新的结局。
+ *
+ * ⚠️ **`record` 上刻意只借了一个 `name`**，尽管 runtime 那边交回来的是一整条
+ * 安装记录：那一条上**没有 `active`**（它是 `list()` 现算的），而这一层要发给
+ * 界面的正是那一格。所以成功之后回头 `list()` 里查一遍才是唯一说得准的做法 ——
+ * 借宽了只会让下一个人顺手拿它拼一个 `active: false`，而更新一个**本来就在生效**
+ * 的插件时那句话是假的。判据在 `WirePluginActionResponse.entry` 上。
+ */
+type InstallOutcomeView = {
+    ok: true;
+    record: {
+        name: string;
+    };
+} | RefusalView;
+type ActionOutcomeView = {
+    ok: true;
+    detail: string;
+} | RefusalView;
+/**
+ * `PluginControl`（runtime）在服务端眼里的样子 —— **只有那六个动词加一格布尔**。
+ *
+ * 镜像里只有它们，于是这个包**写不出** core 的 `setPluginEnabled`
+ * （停用一个插件会静默拿掉别人正依赖的一批命令，正当性和「装 / 卸」不是一回事）、
+ * 也写不出「往任意路径装一个插件」——那不是靠 review 盯住的，是编译期的事
+ * （同 `SkillImportControlView` 只有两个动作、`RoleWriteControlView` 只有 `add`）。
+ *
+ * ⚠️ 每个方法都带 `lang?`。**镜像上漏一格不一定会红**（多一个可选参数是宽化，
+ * `EpochRuntime` 照样满足这份镜像），而漏了的表现是这一层递不出去、一声不吭
+ * 地回中文 —— 判据逐字同 `RoleWriteControlView.add` 上那条 ⚠️。
+ */
+interface PluginControlView {
+    list(): readonly PluginEntryView[];
+    /** 空关键词 = 全部。**这一层永远只传空**，搜索在浏览器里做（判据在 wire 那份文件头） */
+    search(keyword?: string): readonly PluginHitView[];
+    preview(ref: string, lang?: Lang): Promise<PreviewOutcomeView>;
+    install(ref: string, token: string, lang?: Lang): Promise<InstallOutcomeView>;
+    previewUpdate(name: string, lang?: Lang): Promise<PreviewOutcomeView>;
+    update(name: string, token: string, lang?: Lang): Promise<InstallOutcomeView>;
+    uninstall(name: string, lang?: Lang): Promise<ActionOutcomeView>;
+    readonly pendingRestart: boolean;
+}
+/**
+ * 装着的一条 → 网线上那一行。
+ *
+ * `marketplace` / `counts` 缺席时下发 **`null` 而不是省掉这个键**，判据同
+ * `WireSkillImportEntry.conflict`：两格在 wire 上写成必填，于是「服务端忘了转
+ * 这一格」会当场编译不过。而 `counts` 漏掉的表现是一个生效中的插件在界面上
+ * 「什么都不带」。
+ */
+declare function toWirePluginEntry(entry: PluginEntryView): WirePluginEntry;
+
+/**
+ * 「我们支持哪几家、这一家有哪些模型、给这一家配一把 key」 —— `GET /api/providers`、
+ * `POST /api/providers/:type/models` 和 `POST /api/providers/:type/key`。
  *
- * ## ⚠️ 这两条**进程级，URL 上一个 `:id` 都没有**
+ * ## ⚠️ 这三条**进程级，URL 上一个 `:id` 都没有**
  *
  * 判据同 `POST /api/mcp/:name/reconnect` 和 `GET /api/workspaces/dirs`：
  * provider 清单和模型清单**不属于某一段会话**。挂到 `/sessions/:id/` 底下会得到
@@ -1775,6 +2518,17 @@ interface RuntimeModel {
  * （`cli/src/commands/model.ts` 的 `describeDiscovery()`），照抄过来就能省一份
  * catalog。不许 —— 那一句是给同进程宿主（终端）拼的一次渲染，
  * 而且它只分两档（有没有 key），这一屏要分四档。
+ *
+ * ⚠️ 配 key 那一条上同一个诱惑又来了一遍，形状是 `SecretWriteResult.detail`
+ * （「已写入系统钥匙串」那句现成的话）。**照旧不发**：下发的是
+ * `backend` 这个码，措辞在浏览器那侧。判据逐字同上。
+ *
+ * ## ⚠️ 配 key 那一条是**单向**的：key 上得去，下不来
+ *
+ * 请求体里有裸 key，响应体里只有 `maskApiKey` 过的那份。
+ * [§6.4 的第一条「绝不」](../../../docs/verify/VERIFY_RECORD-20-web.md)
+ * 管的是**下行**，这一条一个字都没松 —— 而这个包在 `check-layers.mjs` 的
+ * `LIBRARY_DIRS` 里（一处 console 都不许有），所以它也没有把 key 打进日志的口子。
  */
 
 /** 一个可挑的 provider 在服务端眼里的样子。runtime 的 `ProviderOption` 满足它 */
@@ -1783,6 +2537,15 @@ interface ProviderOptionView {
     label: string;
     envVar: string | null;
     hasKey: boolean;
+    keyHint: string | null;
+}
+/** 一次配 key 的结果。runtime 的 `ProviderKeyWritten` 满足它 */
+interface ProviderKeyWrittenView {
+    envVar: string;
+    backend: string;
+    encrypted: boolean;
+    envPath: string | null;
+    keyHint: string;
 }
 /** 探一家的结果。runtime 的 `ModelSuggestions` 满足它 */
 interface ModelSuggestionsView {
@@ -1792,17 +2555,22 @@ interface ModelSuggestionsView {
     status: WireModelProbeStatus;
 }
 /**
- * `ModelCatalogControl`（runtime）在服务端眼里的样子 —— **只有两个动词**。
+ * `ModelCatalogControl`（runtime）在服务端眼里的样子 —— **只有三个动词**。
  *
- * 镜像里只有这两个，于是这个包**写不出**「把 homeDir 拿来自己拼一个缓存路径」
+ * 镜像里只有这三个，于是这个包**写不出**「把 homeDir 拿来自己拼一个缓存路径」
  * 或者「读一把裸 key」这种事：那两样在收窄口上压根不存在。
  * 同 `McpControlView` 只有 `reconnect`、五份安全镜像各自漏掉一个中文字段。
+ *
+ * ⚠️ `setKey` 是**单向**的：裸 key 只往里走，回来的
+ * {@link ProviderKeyWrittenView} 上只有脱敏串 —— 这个包因此**读不出**
+ * 任何一把已经存着的 key，连自己刚写的那把都读不回来。
  */
 interface ModelCatalogView {
     providers(): readonly ProviderOptionView[];
     discover(provider: ProviderType, opts?: {
         refresh?: boolean;
     }): Promise<ModelSuggestionsView>;
+    setKey(provider: ProviderType, apiKey: string): Promise<ProviderKeyWrittenView>;
 }
 /**
  * server 从 runtime 借的「provider 目录」那一片。`WebRuntimeView` 继承它。
@@ -1817,7 +2585,7 @@ interface RuntimeModelCatalog {
 
 /**
  * `WebRuntimeView.schedules` —— **server 从 runtime 借的定时任务那一片**
- * （[方案 45](../../../../.agents/plans/45-scheduled-automation-plan.md) PR-3）。
+ * （[方案 45](../../../../docs/verify/VERIFY_RECORD-45-automation.md) PR-3）。
  *
  * ## 为什么是一份结构镜像，而不是 `import type { ScheduleControl }`
  *
@@ -1922,11 +2690,22 @@ interface ScheduleCapabilityView {
 /**
  * 定时任务那一片能力。`EpochRuntime.schedules` 结构上正好满足它。
  *
- * ⚠️ **不可为 null**：底下只有一张 SQLite 表和一次平台探测，没有起不来的可能
- * （`build.ts` 上那个字段的 JSDoc 写着同一句）。本平台没有 OS 后端时
- * `capability()` 如实说 `backend: null` —— 那是一个答案，不是一个缺失的能力。
+ * ⚠️ **这一格不可为 null，但「不为 null」不等于「用得了」**（2026-08-26 改准）。
+ * 原来这里写着「底下只有一张 SQLite 表和一次平台探测，**没有起不来的可能**」
+ * —— 后半句是假的：那张表就是 `sessions.db`，打不开的时候这一片一条都列不出来。
+ * 所以多了 {@link ScheduleControlView.storeAvailable} 那一格，十条端点**先过它**
+ * （`handlers.ts` 的 `schedulesOf()`，503 `no-schedule-store`）。
+ *
+ * 本平台没有 OS 后端时 `capability()` 如实说 `backend: null` —— 那是一个答案，
+ * 不是一个缺失的能力；那一格和这一格答的是两件事，别合并。
  */
 interface ScheduleControlView {
+    /**
+     * 底下那张表打开了没有。**同步的** —— 十条端点要在碰 store 之前判得出来。
+     *
+     * `false` 时下面每个方法都会抛，所以调用方**必须先看这一格**。
+     */
+    readonly storeAvailable: boolean;
     list: () => ScheduleDefinition[];
     get: (id: string) => ScheduleDefinition | undefined;
     /** 某条任务最近几次运行，最新的在前 */
@@ -1983,6 +2762,20 @@ interface BoundWorkspace {
     /** `trusted: false` = 这个目录的指令文件**不进** system prompt */
     trust: TrustView;
     projectContext: {
+        /**
+         * **项目根** —— `resolveRootDir(workDir)` 的结果（仓库根，找不到就是启动目录）。
+         *
+         * ⚠️ **和上面那个 `workspace.root` 不是同一个值**，别互相顶替：后者是
+         * `resolve(workDir)`（用户敲 `epoch` 那一刻所在的目录），两者在
+         * 「在子目录里起的那次会话」上不同。
+         *
+         * 2026-08-21 加进这份镜像的（方案 53 PR-4）：`@:` 那条路要按工作区算候选和
+         * 可读范围，而**写入侧往 `sessions.cwd` 里写的是这一个**（判据在 core 的
+         * `SessionManager.getLatestByCwd` 和 `session/authorization.ts` 的 `workspaceCwd`
+         * 上）。给 `workspace.root` 的表现是**一条候选都列不出来**，
+         * 而屏幕上只是一个空面板 —— 没有任何一处会报错。
+         */
+        rootDir: string;
         /** 真加载了的那几份 */
         instructions: ReadonlyArray<{
             path: string;
@@ -2086,7 +2879,9 @@ interface WorkspaceView {
  * 安全中心的取数与投影 —— `GET /api/sessions/:id/security`（方案 42 PR-3）。
  *
  * 不在 [api.ts](./api.ts) 里，同 [capability.ts](./capability.ts) 的理由：那个
- * 文件是「一个端点一个函数」，而这里有五份 runtime 能力的**结构镜像**加六段投影。
+ * 文件是「一个端点一个函数」，而这里是一叠 runtime 能力的**结构镜像**加同样一叠
+ * 投影函数。（这两个数原来写死成「五份 / 六段」，2026-08-27 加审批缓存那一格时
+ * 双双变成假话 —— 改成链到下面的声明本身，同铁律 14 那条「要么写准，要么别写数字」。）
  *
  * ## 结构镜像，不是 import
  *
@@ -2113,7 +2908,9 @@ interface WorkspaceView {
  *
  * ## 「进程有什么」和「这个会话有什么」
  *
- * 权限规则、托管锁、审计流水、策略目录四样今天是**进程级**的。前三样的判据在
+ * 权限规则、托管锁、审计流水、**审批缓存**、策略目录五样今天是**进程级**的。
+ * （审批缓存那一格是 2026-08-27 加的，它和前三样共用同一条判据 —— 见下一句。）
+ * 前四样的判据在
  * core 的 [permission/shared.ts](../../core/src/permission/shared.ts) 文件头：
  * 它们是关于**用户**和**这台机器**的事实，跟着会话走反而会说假话（审批缓存
  * 分了家，「总是允许」在第二个会话上白点；流水分了家，这一屏会漏掉除引导会话
@@ -2174,7 +2971,7 @@ interface WorkspaceView {
  * 这个进程没在跑那段会话（只剩历史 / 被冷却）时退回进程那一份，那仍然是一句
  * 真话，判据逐字同 `permissionState()` 那条兜底。
  *
- * ⚠️ **`rules` / `shadows` / `managed` / `audit` 四样一个都不许跟着搬。**
+ * ⚠️ **`rules` / `shadows` / `managed` / `audit` / `cached` 五样一个都不许跟着搬。**
  * 判据在 core 的 `permission/shared.ts`：它们**没有**跟着会话分家。搬过去的
  * 具体代价是这一屏只剩下这一个会话判过的那几行 ——
  * **一本漏了行的安全流水比没有账更坏，因为它看起来是完整的。**
@@ -2244,6 +3041,29 @@ interface AuditView {
     entries: readonly AuditRowView[];
     dropped: number;
 }
+/**
+ * core 的 `CachedApproval` 的镜像 —— 审批缓存里的一行（2026-08-27）。
+ *
+ * **没有 `ttlMs`**，而这一条和上面四份「漏掉中文」不是同一个理由：它不是散文，
+ * 是引擎侧的一个实现细节（`allow-session` 的有效期）。发过去的话浏览器只能拿它
+ * 算一个「还剩几分钟」，而那个数每一秒都在变、这一屏又没有刷新它的路 ——
+ * 一个一打开就开始撒谎的倒计时。真源在引擎里：`listApprovals()` 每次都先
+ * `prune()`，**过期的根本不在这张表里**。
+ *
+ * `scope` / `decision` 直接钉成网线上那两个联合而不是 `string`，同
+ * {@link AuditRowView} 的 `code` 那条机制：core 那边给缓存多存一档决定而忘了同步
+ * 契约时，**装配那一行当场编译不过**。写成 `string` 的话，新档会一路发到浏览器，
+ * 在界面上显示成一个查不到文案的空白格。
+ */
+interface CachedApprovalView {
+    id: string;
+    toolName: string;
+    target: string;
+    scope: WireCachedApproval['scope'];
+    decision: WireCachedDecision;
+    /** 引擎侧那个字段叫 `createdAt`，网线上叫 `at`（同流水那一列）—— 见投影函数 */
+    createdAt: number;
+}
 /**
  * `PermissionsControl` 的镜像。前五样都是函数，因为它们**每次读都是当前值** ——
  * 审计流水尤其如此，它每判一次就长一条。
@@ -2291,6 +3111,28 @@ interface PermissionsView {
     };
     managed: () => ManagedView;
     audit: () => AuditView;
+    /**
+     * 这个进程记下了哪些弹窗答案（审批缓存，2026-08-27）。
+     *
+     * **和 {@link audit} 一档，跟着进程不跟着会话**（core 的 `permission/shared.ts`）。
+     * 这也是它搭在这一份载荷里、而不是另开一条 `GET` 的理由之一 ——
+     * 判据全文在 `protocol/wire-approval-cache.ts` 的文件头。
+     *
+     * ⚠️ **每次读都是当前值**（同上面五样都是函数）：撤掉一条之后这张表就短一行，
+     * 而那正是撤销那条端点要回读它的原因。
+     */
+    approvals: () => readonly CachedApprovalView[];
+    /**
+     * 撤销一条缓存的决定（2026-08-27）。**判定本体一个字都不在 server** ——
+     * 同下面 `setLevel` 那条：`prune()` → 按 id 删 → `allow-always` 重写盘，
+     * 三步都在 core 的 `ApprovalCache.revoke()` 里。
+     *
+     * 返回类型钉成 `ApprovalRevokeResult` 而不是 `boolean`：runtime 那边把
+     * 「没有权限层」和「这条不在表里」分成了两个码，而它们在界面上是两句完全
+     * 不同的话（一句是「这一节不适用」，一句是「刚才那条已经没了」）。
+     * 收成一个布尔的话，后者会被画成前者的样子。
+     */
+    revokeApproval: (id: string) => ApprovalRevokeResult;
     /**
      * 切到某一档。**判定本体一个字都不在 server** —— 托管挡 bypass、
      * `PermissionManager.setLevel()`、`plan.forget()` 三步都在 runtime 的
@@ -2301,8 +3143,13 @@ interface PermissionsView {
      * **当场编译不过**（同 `AuditRowView.code` 用 `WireAuditCode` 的机制）。
      * 写成 `string` 的话，新码会被静默报成 `managed`，而界面照着它说一句
      * 和真实原因无关的话。
+     *
+     * @param opts.remember 这一发算不算用户显式挑的（2026-08-31）。同 `SetLevelView`
+     *   那份镜像：**照抄真身的必填形状，别写成可选的**，判据在那儿。
      */
-    setLevel: (level: PermissionLevel) => LevelChangeResult;
+    setLevel: (level: PermissionLevel, opts: {
+        remember: boolean;
+    }) => LevelChangeResult;
     /**
      * ⚠️ 第七样，消费方也不在这个文件里 —— 是 [tools.ts](./tools.js)
      * （设置 › 工具那一节）。摆在这儿的理由同上面 `setLevel` 那一段：
@@ -2362,6 +3209,21 @@ interface RuntimeSecurity {
     isolation: IsolationView | null;
     permissions: PermissionsView | null;
     policy: PolicyView;
+    /**
+     * 装配时那份合并后的配置里，沙箱开关那一格（方案 46 §11.3 第四条的后半格）。
+     *
+     * 只镜像 `sandbox.terminal` 这一个键：它是「这次 terminal 的命令包不包」的
+     * **配置事实**，和 {@link RuntimeSecurity.isolation} 那份实测报告是两个正交的
+     * 轴 —— 所以它在载荷上单独一格（`WireSandboxStatus.terminalEnabled`），
+     * 不并进后端那一行、也不并进 `covers` / `excludes` 那两张常量清单（判据逐字
+     * 同 `epoch doctor` 的「开关」那一行）。`EpochRuntime.config` 结构上正好
+     * 满足它，同其余几份镜像的机制：对不上就是装配那一行编译不过。
+     */
+    config: {
+        sandbox?: {
+            terminal?: boolean;
+        };
+    };
 }
 /**
  * 五块一次取齐。
@@ -2579,8 +3441,24 @@ interface LiveSessionView {
      * 换模型那条路要问「**这段**对话里有没有图片」。写成交集而不是各借一个字段，
      * 判据同它原来在 `WebRuntimeView.session` 上那句：它们说的是**同一个对象**，
      * 拆成两个字段的话装配那边可以只填其中一个。
+     *
+     * ⚠️ **2026-08-26 起又多一个 {@link SessionContextFacts}**（`/compact` 那条路要
+     * `compact()`，`/context` 那条路要 `getHistory()` 的**文本**投影）。同一条判据第三次
+     * 用上：三样说的是同一个对象，拆成三个字段的话装配那边可以只填其中一个。
+     */
+    readonly session: HubSession & SessionHistoryFacts & SessionContextFacts;
+    /**
+     * **这个会话自己那个循环**（2026-08-26）。转出来只为一件事：
+     * `GET /api/sessions/:id/context` 要问「现在的上下文预算怎么构成的」，
+     * 而那是循环才答得上的。
+     *
+     * ⚠️ **不是 `EpochRuntime.contextBreakdown`。** 那个 getter 答的恒是**引导会话**
+     * ——它内部拿的是装配时那个 `agent` 和 `session`。拿它去答任意一个 sessionId，
+     * 就是 2026-08-15 从 `WebRuntimeView` 上删掉 `checkpoints` 的那条 bug 原样重演
+     * （方案 30 §9.5）：编译得过、跑得通、只是答错会话，而第二个会话看到的是
+     * 别人的预算构成 —— 且屏幕上没有任何一个字说得出这件事。
      */
-    readonly session: HubSession & SessionHistoryFacts;
+    readonly agent: SessionLoopView;
     /**
      * **这个会话此刻用哪个模型**。runtime 那边 provider 起不来时一个会话都建不出来，
      * 所以这一格不为 null。
@@ -2929,6 +3807,15 @@ interface SettingRowView {
     chain: readonly SettingStepView[];
     overridable: boolean;
     writes: readonly SettingWriteView[];
+    /**
+     * 界面画哪种输入控件。**钉成 {@link WireSettingValueKind} 而不是 `string`**，
+     * 判据同 `layer` 那一处（文件头第 2 条）：引擎那边多一档控件形态而忘了同步
+     * wire 上这个联合，装配那一行当场编译不过 —— 写成 `string` 的话，那一档会
+     * 一路发到浏览器，然后落进「认不出就当输入框」的兜底分支里，
+     * 而那看起来只是「这个控件有点怪」，查不出来。
+     */
+    valueKind?: WireSettingValueKind;
+    choices?: readonly string[];
 }
 /** runtime 的 `SettingWriteReport` 的镜像。`reason` 是码，不是句子 —— 见文件头第 1 条 */
 type SettingWriteReportView = {
@@ -3204,6 +4091,42 @@ interface WebRuntimeView extends RuntimeCapabilities, RuntimeSecurity, RuntimeSe
      * 而 DELETE / PATCH 回 503 —— 不是假装成功。
      */
     sessions: SessionCatalog | null;
+    /**
+     * `@:` 引用另一段会话那一片（方案 53 PR-4）。SQLite 起不来时为 null。
+     * `EpochRuntime.sessionReferences` 结构上正好满足它。
+     *
+     * ## ⚠️ 借的是**那个收窄面**，不是会话库
+     *
+     * 上面 {@link sessionStore} 是「回放旧会话」的读路，这一格是「把另一段会话塞进
+     * 这一条消息」—— 它只交出候选 / 解析 / 当前面三件事，**交不出任意 SQL**。
+     * 这不是省事：那三件事里最要紧的**可读性判定在 core 里**（和方案 48 共用一处），
+     * 而服务端不许 import core。让服务端自己去 `sessionStore` 上拼一条 SQL 出来，
+     * 等于给 `@:` 开一条绕过那个判定的读取通道 —— 而 `@:` 存在的前提恰恰是
+     * 「它永远不比 `session_search` 宽松」（方案 53 §4.3）。
+     * 判据全文在 `EpochRuntime.sessionReferences` 的 JSDoc 上。
+     *
+     * 为 null 时那条候选端点回 503 `no-session-store`（**不是**一份空清单 ——
+     * 判据同 `no-goal-store`），而发消息那条路上 `@:xxx` 一律得到
+     * `invalid-reference`：说「没找到唯一匹配的会话」比悄悄丢掉那个提及诚实。
+     */
+    sessionReferences: SessionReferencesView | null;
+    /**
+     * `@文件` 补全与解析（方案 63）。`EpochRuntime.workspaceFiles` 结构上正好满足它
+     * —— **对不上就是两边长歪了，装配那一行当场编译不过**。
+     *
+     * ## ⚠️ 不可为 null，判据逐字同 `EpochRuntime.workspaceFiles` 那一格
+     *
+     * 它不依赖任何会起不来的东西：清单 `git ls-files` 失败退 walk，读文件失败有
+     * 各自的码（`FileReadOutcome`）。权限层缺席时它照样在，只是读跳过那道判定。
+     *
+     * ## ⚠️ 它和 {@link sessionReferences} 是同一件事的两半
+     *
+     * 那一格让服务端列会话候选而**交不出任意 SQL**；这一格让服务端列文件候选、
+     * 读正文而**交不出任意 `readFileSync`**。收窄的是同一句话 —— `@` 永远不比
+     * `file_read` 宽松，而判定只有权限层那一份（`toolName: 'file_read'`）。
+     * 服务端这里要读文件就得走 `workspaceFiles.readFile`，没有第二条路。
+     */
+    workspaceFiles: WorkspaceFilesView;
     /**
      * 每会话的工作区绑定（[决定 18](../../../design/web-ui/README.md)）。
      * `EpochRuntime.workspaces` 结构上满足它。
@@ -3238,6 +4161,54 @@ interface WebRuntimeView extends RuntimeCapabilities, RuntimeSecurity, RuntimeSe
      * 「校验不过就什么都不写」这条不变量会分散到两处去守。
      */
     schedules: ScheduleControlView;
+    /**
+     * 目标（方案 52 PR-4）。`EpochRuntime.goalCatalog` 结构上正好满足它 ——
+     * **对不上就是两边长歪了，`cli/src/commands/web.ts` 那一行当场编译不过**。
+     *
+     * ## ⚠️ 借的是 `goalCatalog` 而**不是** `runtime.goals`
+     *
+     * 后者是**引导会话**那一份（`GoalControl`，收窄到一段会话）。拿它去答 URL 上
+     * 那个 sessionId，就是上面 `sessionFactory` 那段 ⚠️ 讲的那条 bug 的形状 ——
+     * 「编译得过、跑得通、只是答错会话」（方案 30 §9.5）。这一格从第一天起借的
+     * 就是按 id 现查的那一份。
+     *
+     * ## ⚠️ 可为 null，而这和上面 `schedules` 那一格刻意不同
+     *
+     * 目标是**落盘的状态**：会话库起不来时它整个不存在，判据逐字同 TUI 那一侧的
+     * 「会话库起不来时 `/goal` 压根不注册」。为 null 时那四条会话级端点回 503
+     * `no-goal-store`（不是一份 `goal: null` —— 那是「这个会话没有目标」，
+     * 两句话在界面上是两种画法），而 dock 那条角标端点回空数组。
+     * 全文在 [goal/view.ts](./goal/view.js) 的文件头。
+     *
+     * ## ⚠️ 它也**不像检查点那样向工厂要**
+     *
+     * 目标没有内存态 —— `GoalService` 每次现读 SQLite，所以一段冷却掉的会话在这
+     * 一格上和活着的一样准。走工厂那条路的话，用户打开一段昨天的会话会看到
+     * 「这个会话还没有目标」，而库里那条正躺在那儿。那张三格对照表在
+     * `goal/view.ts` 里。
+     */
+    goalCatalog: GoalCatalogView | null;
+    /**
+     * 插件那一页（方案 59 §六 E2，2026-08-21）。`EpochRuntime.plugins` 结构上正好
+     * 满足它 —— **对不上就是两边长歪了，`cli/src/commands/web.ts` 那一行当场编译不过**。
+     *
+     * ## ⚠️ 可为 null，而这一档和 `goalCatalog` / `sessions` 那两格**不同**
+     *
+     * 那两个是「底下那层起不来了」（SQLite 没起来），这一个是**「宿主没打算给用户
+     * 这条路」**：`buildRuntime()` 没收到 `hostMarketplaces` 时它就是 `null`，
+     * 而那是刻意的 —— 它是一个真的新攻击面（往 `~/.epoch/plugins/` 里落东西，
+     * 而落进去的 hook / `mcp.json` 下一程会起子进程），所以是**选进来**的，
+     * 不是白送的（判据在 `build.ts` 那一格的 JSDoc 上）。
+     *
+     * 为 null 时六条端点一律 503 `no-plugin-control`（**不是**一份空列表 ——
+     * 判据同 `no-goal-store`：那两句话在界面上是两种画法）。
+     * ⚠️ **`epoch web` 今天就落在这一档上**，见 [plugin.ts](./plugin.js) 文件头那条 ⚠️。
+     *
+     * 借的是**一整片控制面**而不是几个方法，理由同 `schedules`：那一片本来就是一个
+     * 整体（列 / 搜 / 预览 / 装 / 更新 / 卸 + 一格 `pendingRestart`），而拆成散字段
+     * 之后「装完了、还没生效」这条不变量会分散到两处去守。
+     */
+    plugins: PluginControlView | null;
     dispose(): void;
 }
 interface ApiContext {
@@ -3262,8 +4233,49 @@ interface ApiContext {
      * 今天的两个消费方：那条端点的 403，和 `GET /api/config` 上原样下发的那一格
      * （界面据此在按下去之前把话说出来）。完整判据在 protocol 的
      * `wire-agent-role.ts` 文件头。
+     *
+     * ⚠️ **2026-09-01 起它还是另一格的输入**：{@link nativeDirPicker} 由它算出来
+     * （远程绑定时不许弹原生框）。那一格是**算出来的结论**，这一格是**事实** ——
+     * 别把两者合成一个，判据在它自己那条 JSDoc 上。
      */
     lanExposed: boolean;
+    /**
+     * 这个进程能不能替浏览器弹一个**系统目录选择框**（2026-09-01）。
+     *
+     * 真源是 `workspace/native-pick.ts` 的 `resolveNativeDirPicker()`，装配时算一次
+     * （回环绑定 + 非 SSH + 平台在支持列表里，三件的合取；它继承的那个 `ssh -L`
+     * 盲区也写在那儿）。
+     *
+     * ## ⚠️ 和 {@link lanExposed} 一样**必传**，理由却更硬一档
+     *
+     * 那一格忘了传的后果是「以为自己在本机」；这一格忘了传（默认成 `true`）的后果是
+     * **一个远程用户点一下，框弹在服务器那台没人看着的机器上，而这一发 HTTP 就
+     * 挂在那儿等一个永远不会有的答复**。所以它没有默认值，而且往「不能弹」那一侧落。
+     *
+     * 两个消费方，形状同上：`POST /api/workspaces/pick` 的 403，和
+     * `GET /api/config` 上原样下发的那一格（界面据此决定那一下走原生框还是自绘
+     * 那一屏）。完整判据在 protocol 的 `WirePickDirectoryResponse` 那一节。
+     */
+    nativeDirPicker: boolean;
+    /**
+     * 浏览器多半就在这个服务进程的机器上吗（2026-09-02）。
+     *
+     * 真源是 `workspace/native-pick.ts` 的 `isSameMachine()` —— **和
+     * {@link nativeDirPicker} 是同一个函数、同一批事实**，今天两格的值必然相等。
+     *
+     * ## 那为什么是两格，而不是一格
+     *
+     * 因为它们是**两个结论**，只是今天恰好共用一条判据：一格答「能不能弹目录框」
+     * （要 osascript / PowerShell 那两套 UI 实现），一格答「能不能把文件交给系统
+     * 默认应用」（要的是 `open` / `rundll32`）。合成一格之后，哪天有人给目录框
+     * 补上 Linux 的 `zenity`，「用默认应用打开」会**跟着**在 Linux 上打开 ——
+     * 而那一侧一次都没验过。判据在 `isSameMachine` 那条 📮 上。
+     *
+     * 消费方只有一个：`GET /api/sessions/:id/file-stat` 里 `openable` 那一格
+     * （界面据此决定画不画那个按钮 —— 决定 20 ①）。⚠️ **`POST .../file-open`
+     * 自己也要再查一遍**，别指望浏览器只在按钮亮着的时候才发那一下。
+     */
+    sameMachine: boolean;
 }
 
 /**
@@ -3565,6 +4577,122 @@ interface WorkspaceDiffOptions {
  */
 declare function collectWorkspaceDiff(opts: WorkspaceDiffOptions): Promise<WireWorkspaceDiffResponse>;
 
+/**
+ * 在**服务进程那台机器**上弹一个系统目录选择框 —— `POST /api/workspaces/pick`
+ * （2026-09-01）。
+ *
+ * ## 它推翻的是 [browse.ts](./browse.js) 文件头那四条里的一条半
+ *
+ * 那份文件头 2026-08-17 写着「为什么不弹原生对话框」四条，末尾那句是
+ * 「哪天这个赌注被推翻了，回来读这一段，**别重新推一遍**」。这一份就是那一天，
+ * 所以这里**只记这一轮新增的判据**，四条各自的下场逐条写在 protocol 的
+ * `WirePickDirectoryResponse` 上（那儿是契约，也是判据的落点）。一句话版：
+ * ① 远程那条**成立**，于是有了下面那道闸；④ 信任那条**作废**（方案 55 §2.6
+ * 判掉了「新建目录默认信任」，今天所有目录一律未信任，裸路径什么都没丢）。
+ *
+ * ## 这道闸是**四件事的合取**，而其中第一件是一句推断
+ *
+ * {@link resolveNativeDirPicker} 那五行的形状照抄 deepseek-harness 的
+ * `packages/host/directory-picker-auto/src/resolve.ts`（同一个形态：纯浏览器页 +
+ * 本机 Node 服务端），判据也是同一条：**原生框弹在服务进程那台机器的屏幕上**，
+ * 所以只有在「浏览器多半就在那台机器上」时它才是对的。
+ *
+ * ⚠️ **继承了它一个修不掉的盲区，如实记下**：`ssh -L` 端口转发时，请求从回环
+ * 进来、`SSH_*` 又不在服务进程的环境里（服务是本机先起的），于是这道闸判成
+ * 「能弹」——框弹在一台没人看着的机器上。harness 的 README 明写这一档
+ * per-connection 适配也修不了，那种部署要直接钉死走自绘。我们这一侧的兜底是
+ * 一样的：`epoch web` 起在一台会被远程访问的机器上时，用 `--host 0.0.0.0`
+ * （那时这道闸自己就关了），别用回环 + 转发。
+ *
+ * ## ⚠️ 第二个盲区，这一个是 2026-09-01 真机量出来的
+ *
+ * **macOS 上，一个连不到 WindowServer 的进程调 `choose folder` 不会报错 ——
+ * 它直接回那个进程的 cwd。** 现场（同一台机器，同一条命令）：
+ *
+ * | 跑在哪儿                     | `osascript … choose folder` 的结果             |
+ * | ---------------------------- | ---------------------------------------------- |
+ * | 普通终端会话                 | 真弹框；取消回 `execution error: 用户已取消。 (-128)` |
+ * | 被 seatbelt 关起来的子进程   | **1.5 秒后回一条路径**（就是 cwd），一个框都没有 |
+ *
+ * 也就是说那一档下用户会**拿到一个他从没挑过的目录**，而屏幕上没有任何东西
+ * 说过这件事。**这道闸拦不住它**：那台机器上 `launchctl managername` 照样是
+ * `Aqua`（实测），SSH 那两格也是空的 —— 会话元数据看着完全正常，被挡掉的是
+ * 真正那次连接。
+ *
+ * **没有为它加探测**，判据是「加一个查不出这一档的探测，比不加更坏」：
+ * 它会让下一个人以为这条缝已经堵上了。今天的形态是**如实记在这儿**，
+ * 而现实里踩得到它的是「epoch web 被某个沙箱化的父进程拉起来」这一种 ——
+ * 用户自己在终端里敲 `epoch web` 不在其中。
+ *
+ * 📮 真要堵它，能想到的唯一可靠做法是**让框自己说话**：给 `choose folder` 一个
+ * `default location`（比如 home），那时「回的是 cwd」就成了一个可判的信号 ——
+ * 但它同时也把「系统记住的上次位置」这件事顶掉了，那是原生框最值钱的东西之一。
+ * 谁要收这张 📮，先量一遍那两件哪个更贵。
+ *
+ * ## 平台只写两个，而这不是「先做一半」
+ *
+ * AGENTS.md「支持平台」那一节只有 Windows 和 macOS。Linux 分支写了也没人验
+ * （harness 那边是 `zenity → kdialog` 两级降级），所以这里**一个字都不写** ——
+ * 那台机器上这道闸判成假，界面回落自绘那一屏，而那一屏在任何机器上都能用。
+ * 这是「不做」，不是「没做完」：加 Linux 的人要连着加它的探测（`DISPLAY` /
+ * `WAYLAND_DISPLAY` + PATH 上有没有那两个二进制），别只加一条命令。
+ *
+ * ## 三条实现上的规矩
+ *
+ * 1. **`execFile` 不过 shell**，全仓同一条（`cli/src/host-actions.ts` /
+ *    `workspace/git.ts`）。这一条在这儿尤其硬：Windows 那一支是一段脚本文本；
+ * 2. **不设 timeout。** `git.ts` 那个 10 秒在这儿是错的 —— 一个对话框本来就可以
+ *    开五分钟。取而代之的是 {@link PickOptions.signal}：HTTP 请求断开（用户关了
+ *    标签页）就杀掉那个子进程，否则那个框会永远留在别人屏幕上；
+ * 3. **同一进程只许一个框**（{@link pickNativeDirectory} 的单飞闸）。两个框叠在
+ *    一台机器上，用户答的那一个未必是浏览器还等着的那一个。
+ */
+/** 这台机器上能不能弹的四件事，全是**事实**不是结论 —— 判据在下面那个函数上 */
+interface NativePickerFacts {
+    /** 服务绑在回环之外吗（`bind.ts` 的 `decideBinding().lanExposed`） */
+    lanExposed: boolean;
+    /** `process.platform` */
+    platform: NodeJS.Platform;
+    /** `process.env` 的一个子集 —— 只读这两格，见下 */
+    env: Readonly<Partial<Record<'SSH_CONNECTION' | 'SSH_TTY', string>>>;
+}
+/**
+ * 这个服务进程能不能替浏览器弹一个系统目录框。**纯函数，装配时算一次。**
+ *
+ * 四条缺一不可，每一条挡的是一种「框弹出来也没用 / 弹错地方」：
+ *
+ * | 条件                     | 挡的是什么                                                |
+ * | ------------------------ | --------------------------------------------------------- |
+ * | 绑在回环上               | `--host 0.0.0.0` 那一档浏览器可能在别的机器上             |
+ * | 没有 `SSH_CONNECTION` / `SSH_TTY` | 服务是被 ssh 进来的人起的 —— 框会弹在无人值守的服务器上 |
+ * | 平台是 darwin / win32    | 别的平台这一份没有实现（见文件头「平台只写两个」）        |
+ *
+ * ⚠️ **一律往「不能弹」那一侧落**：猜错成「能弹」的表现是用户点下去吃一个 403
+ * 或者框弹在别人屏幕上，猜错成「不能弹」的表现只是他看到自绘那一屏 ——
+ * 而那一屏在任何机器上都能用。
+ */
+declare function resolveNativeDirPicker(facts: NativePickerFacts): boolean;
+/**
+ * 「浏览器多半就在服务进程这台机器上」—— 上面那个判断的**正身**。
+ *
+ * 2026-09-02 抽出来，因为有了第二个问同一句话的地方：Web UI 的
+ * 「用默认应用打开」（`workspace/file-view.ts`）。它和弹目录框是**同一个赌注**
+ * —— `open` / `rundll32` 起的那个窗口和 `choose folder` 弹的那个框，
+ * 出现在同一块屏幕上；那块屏幕前面没人的话，两者一样白搭。
+ *
+ * ⚠️ **两处共用一份，不许各写各的。** 三条判据里最容易被漏掉的是 SSH 那两格
+ * （它问的是「这个服务是被谁起的」，不是「这一发请求从哪儿来」），
+ * 而漏掉它的表现不是报错，是**一个窗口弹在无人值守的服务器上**。
+ *
+ * ⚠️ 它继承 `resolveNativeDirPicker` 文件头记的那两个盲区，一个字都没少：
+ * `ssh -L` 端口转发这道闸判不出来；macOS 上被沙箱关起来的进程也判不出来。
+ *
+ * 📮 平台那一条对这一格其实**偏严**了：`xdg-open` 在 Linux 上是有的，
+ * 而目录框那一侧没有 Linux 实现。今天故意不放宽 —— AGENTS.md 的支持平台只有
+ * Windows / macOS，放宽等于多一条没人验的分支。要放宽的人先去改那一节。
+ */
+declare function isSameMachine(facts: NativePickerFacts): boolean;
+
 /**
  * 后台任务的取数与投影 —— `GET /api/sessions/:id/tasks`（方案 36 PR-2 的 Web 那半）。
  *
@@ -3675,10 +4803,12 @@ declare function toWireTask(sessionId: string, info: BackgroundTaskInfo, registr
 declare function collectTasks(sessionId: string, registry: TaskRegistryView): WireTasksResponse;
 
 /**
- * 定时任务那九条端点（[方案 45](../../../../.agents/plans/45-scheduled-automation-plan.md) PR-3）。
+ * 定时任务那十条端点（[方案 45](../../../../docs/verify/VERIFY_RECORD-45-automation.md)
+ * PR-3 九条 + PR-4 那条 `pending`）。
  *
  * ```
  * GET    /api/schedules                              两个 tab 一次取齐
+ * GET    /api/schedules/pending                      还欠着的那几张欠条（PR-4）
  * POST   /api/schedules                              建一条
  * GET    /api/schedules/:id                          一条的全部字段
  * PATCH  /api/schedules/:id                          改一条（含那个开关）
@@ -3904,4 +5034,4 @@ type CreateWebServerResult = {
  */
 declare function createWebServer(opts: CreateWebServerOptions): Promise<CreateWebServerResult>;
 
-export { type ApiContext, type AuthGuardOptions, type BindDecision, type BindRequest, type BoundWorkspace, type CatalogDeletion, type CatalogHit, type CatalogRow, type CheckpointSummaryView, type CommandsView, type CreateSessionResult, type CreateWebServerOptions, type CreateWebServerResult, DEFAULT_MAX_ACTIVE_SESSIONS, DEFAULT_MAX_QUEUED_MESSAGES, DEFAULT_RING_CAPACITY, DEFAULT_WEB_HOST, DEFAULT_WEB_PORT, EnvelopeRing, type EpochWebServer, type ExpansionOutcome, type FrameSink, type HubSession, type HubSessionState, type LiveSessionView, MAX_DIFF_BYTES, MAX_DIFF_FILES, MAX_RECORDING_FRAMES, MAX_SKILL_BODY_BYTES, type ModelTurnsView, type QueuedMessage, type RewindFilePlanView, type RewindOutcomeView, type RewindPreviewView, type RewindResultView, type RuntimeCapabilities, type RuntimeCheckpoints, type RuntimeCommands, type RuntimeSecurity, type RuntimeSettings, type ScheduleCapabilityView, type ScheduleControlView, type ScheduleCreateView, type ScheduleFireView, type ScheduleRegisterView, type ScheduleSaveView, type ScheduleUpdateView, type SelectionView, type SessionCatalog, type SessionFactoryView, type SessionHistoryFacts, SessionHub, type SessionHubOptions, type SessionModelView, type SessionPermissionsView, type SessionPlanView, type SessionRoleView, type SetLevelView, type SetSelectionView, type StartResult, TASK_TAIL_BYTES, type TaskRegistryView, type TrustView, type TurnDecorator, UI_LANG_PARAM, UI_THEME_PARAM, type UiLangPref, type UiPreset, type UiThemePref, type WebRuntimeView, type WorkspaceBindFailure, type WorkspaceBindOutcome, type WorkspaceCheckpoints, type WorkspaceDiffOptions, type WorkspaceView, collectCapabilities, collectSecurity, collectSettings, collectTasks, collectWorkspaceDiff, createAuthGuard, createWebServer, decideBinding, defaultWebRoot, expandUserContent, firstScreenUrl, generateToken, readRewindInput, resolveArtifactPath, toWireCheckpoint, toWireCommand, toWirePreview, toWireRewindResult, toWireRow, toWireSkillBody, toWireTask, unavailableToHttp };
+export { type ApiContext, type AttachedMentions, type AuthGuardOptions, type BindDecision, type BindRequest, type BoundWorkspace, type CatalogDeletion, type CatalogHit, type CatalogRow, type CheckpointSummaryView, type CommandsView, type CreateSessionResult, type CreateWebServerOptions, type CreateWebServerResult, DEFAULT_MAX_ACTIVE_SESSIONS, DEFAULT_MAX_QUEUED_MESSAGES, DEFAULT_RING_CAPACITY, DEFAULT_WEB_HOST, DEFAULT_WEB_PORT, EnvelopeRing, type EpochWebServer, type ExpansionOutcome, type FrameSink, type HubSession, type HubSessionState, type LiveSessionView, MAX_CANDIDATES, MAX_DIFF_BYTES, MAX_DIFF_FILES, MAX_RECORDING_FRAMES, MAX_SKILL_BODY_BYTES, type ModelTurnsView, type NativePickerFacts, type PluginControlView, type QueuedMessage, type RewindFilePlanView, type RewindOutcomeView, type RewindPreviewView, type RewindResultView, type RuntimeCapabilities, type RuntimeCheckpoints, type RuntimeCommands, type RuntimeSecurity, type RuntimeSettings, type ScheduleCapabilityView, type ScheduleControlView, type ScheduleCreateView, type ScheduleFireView, type ScheduleRegisterView, type ScheduleSaveView, type ScheduleUpdateView, type SelectionView, type SessionCatalog, type SessionContextFacts, type SessionFactoryView, type SessionHistoryFacts, SessionHub, type SessionHubOptions, type SessionLoopView, type SessionModelView, type SessionPermissionsView, type SessionPlanView, type SessionReferencesView, type SessionRoleView, type SetLevelView, type SetSelectionView, type StartResult, TASK_TAIL_BYTES, type TaskRegistryView, type TrustView, type TurnDecorator, UI_LANG_PARAM, UI_THEME_PARAM, type UiLangPref, type UiPreset, type UiThemePref, type WebRuntimeView, type WorkspaceBindFailure, type WorkspaceBindOutcome, type WorkspaceCheckpoints, type WorkspaceDiffOptions, type WorkspaceView, attachMentions, collectCapabilities, collectSecurity, collectSettings, collectTasks, collectWorkspaceDiff, createAuthGuard, createWebServer, decideBinding, defaultWebRoot, expandUserContent, firstScreenUrl, generateToken, isSameMachine, listFileCandidates, listReferenceCandidates, readRewindInput, resolveArtifactPath, resolveNativeDirPicker, toWireCheckpoint, toWireCommand, toWirePluginEntry, toWirePreview, toWireRewindResult, toWireRow, toWireSkillBody, toWireTask, unavailableToHttp };