@epoch-agent/server 0.9.0 → 0.10.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-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, WirePluginVisibility, WirePluginStatus, WirePluginRefuseReason, WirePluginUploadFieldName, WirePluginUploadFields, 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, TokenUsage, WireCompressionLine, WireProviderSummary, WireToolSummary, Diagnostic, WireReplayMessage, WireFileChange, WireAuthGuard, WireWorkspaceDiffResponse, BackgroundTaskInfo, WireTasksResponse, WireBackgroundTask, WireScheduleRow } from '@epoch-agent/protocol';
+import { Lang, WireSkillImportFailure, WireSkillImportForm, WireSkillRemoveFailure, WireSkillStageFailure, WireProjectInventory, 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, WirePluginVisibility, WirePluginStatus, WirePluginRefuseReason, WirePluginUploadFieldName, WirePluginUploadFields, 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, TokenUsage, 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';
 
@@ -94,6 +94,76 @@ interface UiPreset {
  */
 declare function firstScreenUrl(host: string, port: number, token: string, ui?: UiPreset): string;
 
+/**
+ * 输入框附件的那两半（2026-09-11）—— 上传落盘，以及发消息时把它们变成部件。
+ *
+ * ## 这条路和 `@文件` 的分工
+ *
+ * | | `@路径`（方案 63） | 这一条 |
+ * | --- | --- | --- |
+ * | 文件从哪来 | 用户工作区里**本来就有** | 用户**刚拖进来** |
+ * | 字节谁持有 | 用户的盘 | 先经 HTTP 落进 `~/.epoch/attachments/<会话 id>/` |
+ * | 边界 | `resolveInWorkspace()`（工作区内） | 构造保证（只能落在那一个目录里） |
+ * | 权限 | 每次读过 `file_read` | **录入时不过**，判据见下 |
+ *
+ * 两条路最后产出的是**同一种部件**（`EpochFilePart`），走同一本预算账，
+ * 收据也进同一个 `files` 数组 —— 于是界面上「这条消息附了哪些文件」只有一张表，
+ * 而不是两种长得不一样的卡片。
+ *
+ * ## ⚠️ 这一层**一个字节的文件读写都没有**
+ *
+ * 落盘走 `streamBodyToFile()`（`http.ts` 的原语，边收边写），落点由
+ * `ctx.runtime.attachments.place()` 给；读回来走 `.read()`。
+ * 判据同 mentions.ts 文件头那条：路径的清洗规则住在 infra 的 `bySession`，
+ * **而 `server` 不许 import `infra`** —— 在这一层拼一次路径就是给同一个目录
+ * 第二个说法，分叉的表现是「传上去了、模型说看不到」，而 HTTP 200、
+ * 盘上真有那个文件、日志一个字不报。
+ *
+ * ## ⚠️ 上传这条端点没有大小上限
+ *
+ * 是拍过的决定，不是漏了。字节边收边写，峰值内存是一个 chunk；护栏是认证
+ * （同别的 API）和那本 512MB 的总账。完整判据在 `http.ts` 的
+ * `streamBodyToFile` 和 core 的 `ATTACHMENT_MAX_TOTAL_BYTES` 上 ——
+ * 两处都写着「这拦不住当前会话里传一个 2GB 的文件」。
+ */
+
+/**
+ * 读一次附件正文的结果。`EpochRuntime.attachments` 的 `read()` 结构上满足它。
+ *
+ * 两档失败的码**和 `WorkspaceFilesView.FileReadOutcome` 对齐** ——
+ * 少了 `denied`（这条路上不做权限判定，判据见 `AttachmentControlView.read`）。
+ */
+type AttachmentReadView = {
+    ok: true;
+    path: string;
+    text: string;
+    bytes: number;
+} | {
+    ok: false;
+    reason: 'unreadable' | 'binary';
+    bytes?: number;
+};
+/** 引擎那片附件面。`EpochRuntime.attachments` 结构上正好满足它 */
+interface AttachmentControlView {
+    /** 挑落点。`undefined` = 名字不合法（投影之后不是一个文件名） */
+    place(sessionId: string, name: string): {
+        path: string;
+        name: string;
+    } | undefined;
+    /** 已落盘的名字 → 绝对路径；指不出去时 `null` */
+    resolve(sessionId: string, name: string): string | null;
+    /**
+     * 读正文。
+     *
+     * ⚠️ **它不过 `file_read` 权限判定**，判据全文在 runtime 的
+     * `attachment-stage.ts` 上。一句话：附件是用户递进来的消息内容，
+     * 不是 agent 的一次文件访问；判定在模型之后真去读它的那一刻。
+     */
+    read(sessionId: string, name: string): AttachmentReadView;
+    /** 清历史会话的附件，best-effort，不抛 */
+    prune(keepSession: string): number;
+}
+
 /**
  * `mcp.json` 的**原文**那三条端点 —— `GET` / `PUT /api/mcp/config` 和
  * `POST /api/mcp/config/apply`（2026-08-18）。
@@ -640,6 +710,86 @@ interface SkillRemoveControlView {
     remove(name: string, lang?: Lang): Promise<RemoveResultView>;
 }
 
+/**
+ * 「把你手里那一份交上来」那条端点 —— `POST /api/skills/stage`（2026-09-13）。
+ *
+ * ```
+ * POST /api/skills/stage?name=<原始文件名>   <原始字节>  → 落地 + 解包 → 一条本机路径
+ * ```
+ *
+ * 界面上技能页那个落区背后就是这一条。它**一个技能都不装**：出口只是一条服务端
+ * 本机路径，接着还要走 [skill-import.ts](./skill-import.js) 那两条
+ * （`import/preview` → `import`，含 `token` 那道防 TOCTOU 的缝）。
+ * 判据全文在 protocol 的 `WireSkillStageResponse` 上，以及 runtime 的
+ * [skill-stage.ts](../../runtime/src/skill-stage.ts) 文件头。
+ *
+ * ## ⚠️ 一、隔壁那两条说「不收字节」，这一条收 —— 为什么不是自相矛盾
+ *
+ * [skill-import.ts](./skill-import.js) 的文件头第 1 条逐字写着「请求体里只有
+ * `path` 和 `token`，**没有 `content`**」。那句话**今天仍然成立，而且是关于那两条
+ * 端点的**：那两条会往 `~/.epoch/skills/` 里落东西，而落进那儿 = 进往后每一轮的
+ * `<available_skills>`。
+ *
+ * 这一条落进的是 `~/.epoch/skill-drops/`，**那不在 `scanSkillDirs` 的扫描范围里**。
+ * 也就是说这一发结束时 system prompt 里一个字都没变 —— 「传上来」和「装上了」
+ * 是两件分得开的事，而分开它们正是这个设计成立的全部原因。
+ *
+ * ## ⚠️ 二、那道 403 在**读 body 之前**，而这一条上它有两重意思
+ *
+ * 1. **省内存那一重**（同 `POST /api/plugins/stage`）：body 上限 50 MiB，
+ *    漏一格就是让 LAN 上的人一发一发地灌这台机器的内存；
+ * 2. **本体那一重**：`--host 0.0.0.0` 那一档下我们不知道浏览器在谁那儿，而
+ *    这条端点的产物**下一步就会被人按确认装进 system prompt**。技能目录的闸门表
+ *    上用户级那一格逐字写着「无（是用户自己的机器）」——「是用户自己的机器」
+ *    正是这一档下不成立的那条。
+ *
+ * ⚠️ **它和身份 / 插件那两道 403 的措辞不能互抄**，判据记在 catalog 里
+ * `skill_stage_lan_exposed` 上面那几行：技能不起子进程（插件那句是假话），
+ * 而且**这一档下导入本身没关**（只是不收上传）—— 那句出路必须说出来，
+ * 否则用户的结论是「这个功能没了」。
+ *
+ * ⚠️ **界面那一侧还有一道，但它是给人的**：`GET /api/config` 上带着 `lanExposed`，
+ * 能力页据此在按下去之前就把落区收起来。两道各答一半 —— 别因为界面画了就把这一道
+ * 摘掉，那一格是客户端自己改得动的布尔（口径逐字同 `role-add.ts` 文件头）。
+ *
+ * ## ⚠️ 三、这一层一条策略判断都没有
+ *
+ * 后缀认不认、名字削不削、解不解得开，**全在 runtime 那一侧**。这一层只做三件事：
+ * 判那道 403、读 body、把 `?name=` 原样递下去。
+ *
+ * 文件名**在这儿不净化**，判据逐字同 `plugin.ts` 里 `stagePlugin` 那一处：
+ * 唯一那道收窄在 runtime 的 `safeBaseName`（它是落点的产地），在这儿先削一遍的
+ * 下场是两处各削一半，而两处削法分叉的那天没有任何东西会红。
+ *
+ * ## 为什么单开一个文件
+ *
+ * 同 `skill-import.ts` 从 `capability.ts` 里分出来那两条判据。外加一条这一份
+ * 自己的：**镜像必须跟着 handler 走**。`SkillImportControlView` 上只有
+ * `preview` / `import` 两个方法，于是那个文件**写不出**「往盘上落一份字节」这件事；
+ * 把这条 handler 塞进去、再往那张镜像上加一个 `stage`，等于让那两条端点顺手
+ * 也能落字节 —— 判据同 `capability.ts` 上 `mcp` 那一格为什么是两张镜像的交集。
+ */
+
+/**
+ * `SkillStageFlow`（runtime）在服务端眼里的样子 —— **只有一个动作**。
+ *
+ * ⚠️ 它**不和 `SkillImportControlView` 合并**，判据在文件头最后一节：
+ * 合并之后 `import/preview` 那个 handler 也就顺手能往盘上落字节了。
+ */
+interface SkillStageControlView {
+    stage(input: {
+        name: string;
+        data: Uint8Array;
+    }, lang?: Lang): Promise<{
+        ok: true;
+        path: string;
+    } | {
+        ok: false;
+        reason: WireSkillStageFailure;
+        detail: string;
+    }>;
+}
+
 /**
  * 能力页的取数与投影 —— `GET /api/sessions/:id/capabilities`（方案 42 PR-1），
  * 外加技能正文那条下钻（方案 56 §1.2）。
@@ -793,6 +943,24 @@ interface RuntimeCapabilities {
      * 要收得两条一起收。
      */
     readonly skillWrite: SkillImportControlView & SkillRemoveControlView;
+    /**
+     * 把浏览器里那一份字节换成一条本机路径（2026-09-13）—— 技能页那个落区背后的
+     * 那一条。**进程级**，同上面那一格。
+     *
+     * ## ⚠️ 它**单开一格，不并进 {@link skillWrite}**
+     *
+     * 上面那一格的 ⚠️ 说「导入收的是路径不是字节」，而那句话必须继续为真。
+     * 并进去之后 `skill-import.ts` 里那两个 handler 就顺手也能落字节了 ——
+     * 收窄靠的是**镜像里没有那个方法**，不是靠 review 盯着（判据同下面 `mcp`
+     * 那一格为什么是两张镜像的交集）。真源在 runtime 那边同样是两格
+     * （`skillWrite` / `skillStage`），这儿只是照着对形状。
+     *
+     * ⚠️ 这一条**吃一道回环绑定的 403**（`ctx.lanExposed` 为真就拒，连 body 都不读），
+     * 而它**不在这份镜像上** —— 镜像答的是「runtime 借得到什么」，闸门答的是
+     * 「这一发准不准发」。判据同 `roleWrite` 那一格，全文在
+     * [skill-stage.ts](./skill-stage.js) 文件头第二节。
+     */
+    readonly skillStage: SkillStageControlView;
     /**
      * MCP 的写口：重连一台（方案 56 §1.1）+ 加一台（2026-08-18）+ **那份文件的原文
      * 读写与应用**（2026-08-18）。**全都是进程级**。
@@ -849,8 +1017,12 @@ declare function collectCapabilities(runtime: RuntimeCapabilities, tools: readon
     };
     trust: {
         trusted: boolean;
+        exec: boolean;
     };
-} | null, role: string | null): WireCapabilitiesResponse;
+} | null, role: string | null, project: {
+    inventory: WireProjectInventory;
+    trustRequest: boolean;
+}): WireCapabilitiesResponse;
 /**
  * 一份 `SKILL.md` 最多发多少字节。形状照
  * [workspace/diff.ts](./workspace/diff.ts) 的 `MAX_DIFF_BYTES`。
@@ -1282,14 +1454,52 @@ interface GoalCatalogView {
  * 4. **一个会话同一时刻只有一个 `run()`**（方案 30 §2.3）。同一会话的第二条消息
  *    **排队**而不是并发；不同会话之间**可以**并行 —— 那正是多会话的意义。
  *    理由与「谁在表里、谁排在后面」的实现都在 [sessions/registry.ts](./sessions/registry.ts)。
- * 5. **旁听者（`observe()`）不许进 `sinks`**（方案 54 §三）。`sinks.size` 是用来回答
- *    「**人**还在不在」的那个计数器，全仓有四处判它：`connectionCount`、
- *    `armGrace()` 的触发、`drainQueue()`、`reap()`。宿主为了在自己的窗口上点亮一枚
- *    状态灯会常驻一条旁听 —— 那要是算一条连接，「全断 30 秒放弃挂起的审批 + 中止
- *    回合」和「全断了丢掉排队的消息」就一起失效了，**而宿主没有任何办法知道**。
- *    加集合、不加计数：新东西进不了那个计数器。
+ * 5. **旁听者（`observe()`）默认不算「人」**（方案 54 §三）。「人还在不在」这个问题
+ *    有三处在问：`armGrace()` 的触发、`drainQueue()`、`reap()`。宿主为了在自己的
+ *    窗口上点亮一枚状态灯会常驻一条旁听 —— 那要是算一条连接，「全断 30 秒放弃挂起
+ *    的审批 + 中止回合」和「全断了丢掉排队的消息」就一起失效了，**而宿主没有任何
+ *    办法知道**。所以缺省一个字没变。
+ *
+ *    ⚠️ 2026-09-11 起多了一档**由宿主自己声明**的例外：`observe(sink, {counts:true})`
+ *    算一份在场（{@link ObserveOptions.counts}）。一盏状态灯和一条即时通讯桥
+ *    在这个问题上的答案本来就不同，而只有宿主分得清自己是哪一种 ——
+ *    判据全文在那一格上。
+ *
+ *    `connectionCount` **仍然只数 SSE**：它答的是「有几条连接」而不是
+ *    「有没有人」，`/api/config` 把那个数报给界面看。
  */
 
+/** {@link SessionHub.observe} 的可选项。 */
+interface ObserveOptions {
+    /**
+     * 这条旁听**算不算一份「在场」**。缺省 `false`（一个字都没变的老行为）。
+     *
+     * 🔴 **它决定的是三件事：全断之后要不要放弃挂起的审批、要不要中止在跑的回合、
+     * 以及排队的消息要不要丢掉。** 给 `true` 的那一刻，这条旁听在这三处和一个
+     * 开着的标签页等价（`connectionCount` 除外 —— 那一格答的是「有几条连接」）。
+     *
+     * ## 什么时候该给 `true`
+     *
+     * 判据只有一条：**这条旁听的另一头有没有一个人**，而且那个人**答得了审批**。
+     *
+     * | 宿主那一侧是什么 | 给什么 | 为什么 |
+     * | --- | --- | --- |
+     * | 窗口角上一枚状态灯 | 不给 | 灯不会答审批。它亮着不代表有人看着 |
+     * | 写日志 / 采指标 | 不给 | 同上，而且它常驻整个进程 |
+     * | 即时通讯桥（飞书 / Slack / Telegram…） | `true` | 人在手机上，**审批卡就在他手里** |
+     *
+     * ⚠️ **给错的后果不对称，所以缺省落在「不算」那一侧。**
+     * 该给不给：人在手机上等着，而回合在 30 秒后被中止、排队的消息被丢掉
+     * （2026-09-11 一个飞书宿主实测到的就是这一档 —— 用户关掉电脑上的窗口，
+     * 手机上那一轮 30 秒后停了，而他什么都没做）。
+     * 不该给却给了：没人看着的时候一轮活会一直跑下去、挂起的审批永远挂着 ——
+     * 那正是这三处判定存在的理由（方案 20 §4.3）。
+     *
+     * ⚠️ **不做成 Hub 级的开关**（`countObserversAsConnections` 那种）：同一个宿主
+     * 完全可以同时挂一盏灯和一条桥，而那两条的答案不同。这件事是**每条旁听**的属性。
+     */
+    counts?: boolean;
+}
 interface SessionHubOptions {
     /** 环形缓冲容量，默认 512 */
     ringCapacity?: number;
@@ -1399,6 +1609,13 @@ declare class SessionHub {
      * 两个集合的写法让那四处一个字都不用改。
      */
     private readonly observers;
+    /**
+     * 上面那些旁听里，**声明了自己算一份在场**的那几条（{@link ObserveOptions.counts}）。
+     *
+     * 第三个集合而不是在 `observers` 上加标记位，理由同上面那段：判「人还在不在」
+     * 的三处要问的是一个**数**，而 `Set.size` 就是那个数。
+     */
+    private readonly counted;
     /** requestId → sessionId。`POST /api/approvals/:requestId` 上没有会话 id */
     private readonly requestOwner;
     /** 全局广播游标。0 是保留值（连接级帧），所以广播帧从 1 开始 */
@@ -1430,8 +1647,23 @@ declare class SessionHub {
      * @returns Hub 里本来有没有它
      */
     unregister(sessionId: string): boolean;
-    /** 当前活着的 SSE 连接数。给 `/api/config` 和用例看 */
+    /**
+     * 当前活着的 SSE 连接数。给 `/api/config` 和用例看。
+     *
+     * ⚠️ **只数 SSE，不数旁听者 —— 连声明了 `counts` 的那些也不数。**
+     * 它答的是「有几条连接」，而 `/api/config` 把这个数原样报给界面；
+     * 把宿主那条旁听混进去，用户会在界面上看到一个他找不到的「1 个连接」。
+     * 「有没有人在场」是另一个问题，答它的是 {@link present}。
+     */
     get connectionCount(): number;
+    /**
+     * 此刻**有没有人在场** —— `armGrace()` / `drainQueue()` / `reap()` 三处判的都是它。
+     *
+     * = 活着的 SSE 连接 + 声明了 `counts` 的旁听（{@link ObserveOptions.counts}）。
+     * 单独一个私有取数口而不是三处各写一遍加法：那三处里有两处的错法是**静默的**
+     * （挂起的审批永远不被放弃、没人看着的时候凭空开始跑一条排队的消息）。
+     */
+    private get present();
     /**
      * 接一条 SSE 连接。
      *
@@ -1448,9 +1680,13 @@ declare class SessionHub {
      *
      * 和 `subscribe()` 的差别不是「少发一帧」，是它整条不进那套连接语义：
      *
-     * - **不进 `sinks`**：不计入 `connectionCount`，不影响 idle-grace 的收摊
-     *   （`armGrace()` → `reap()`），也不影响 `drainQueue()` 的「全断了就丢队列」。
-     *   那三处判的是「**人**还在不在」，而旁听者是宿主的代码，不是一双眼睛
+     * - **不进 `sinks`**：不计入 `connectionCount`，而且**缺省**也不影响 idle-grace
+     *   的收摊（`armGrace()` → `reap()`）和 `drainQueue()` 的「全断了就丢队列」——
+     *   那三处判的是「**人**还在不在」，而一条旁听可能只是一盏状态灯。
+     *   ⚠️ 后三处从 2026-09-11 起**由宿主自己声明**：
+     *   `observe(sink, { counts: true })` 算一份在场，判据全文在
+     *   {@link ObserveOptions.counts} 上（一条即时通讯桥的另一头真的有个人，
+     *   而审批卡就在他手机里）
      * - **不发 `connected`、不认 `Last-Event-ID`、不从环形缓冲补帧**：补帧机制存在的
      *   理由是网线断过一段，而同进程的函数调用不会丢帧。真要历史就走
      *   `GET /api/sessions/:id/messages`，和浏览器同一条路
@@ -1461,7 +1697,7 @@ declare class SessionHub {
      *
      * @returns 取消旁听。**幂等** —— 多调几次不会误删后来注册的同一个函数
      */
-    observe(sink: FrameSink): () => void;
+    observe(sink: FrameSink, opts?: ObserveOptions): () => void;
     /**
      * 发一条消息。会话空闲就立刻开一轮，否则**排队**（方案 30 §2.3 第 4 条）。
      *
@@ -1538,6 +1774,38 @@ declare class SessionHub {
      * 把这条通道接到 `append` 上），先回来看这一段。
      */
     notifyTasksChanged(sessionId: string): void;
+    /**
+     * 广播「会话列表变了」—— 多了一段或少了一段（2026-09-11）。
+     *
+     * 语义、不带载荷的理由、以及覆盖不到的那一档（改标题）全在 protocol 的
+     * `sessions-changed` 上。这里只记**为什么产地在路由层而不是在 `register()` 里**。
+     *
+     * ## 🔴 为什么不写在 `register()` / `unregister()` 里
+     *
+     * 那是第一版，看着更收敛（`hub-register-sites.test.ts` 已经钉住了「会话只能从
+     * 那三处变活」），**但它会把每一条流的帧序整体后移一格**：`register()` 的第三个
+     * 调用点是起服务时那一次（`index.ts`），那一刻一个连接、一个旁听都还没有，
+     * 而它照样要占一个全局 `seq`、读一格 `clock`、进一格环形缓冲。代价不是那一格
+     * 内存，是 `fixtures/` 那批逐条断言 `seq` / `ts` 的信封 —— 每一段会话的第一帧
+     * 从 `seq: 1` 变成 `seq: 2`，而那批 fixture 是 protocol / server / web 三边共用的
+     * 契约（`scriptedClock` 还会直接抛「时钟被多读了一格」）。
+     *
+     * 为一帧发给**零个**收件人的帧去改一份三边共用的契约，换不回任何东西。
+     *
+     * ## 所以产地是两条端点，各自的判据
+     *
+     * | 产地 | 什么时候发 | 为什么 |
+     * | --- | --- | --- |
+     * | `POST /api/sessions`（`workspace/handlers.ts`） | **只在 `outcome.created`** | 复用那一支没多出一行来，发了等于让所有标签页白重取一次 |
+     * | `DELETE /api/sessions/:id`（`api.ts`） | 删成了就发 | 不发的话**别的**标签页会一直挂着一行已经没了的会话，点进去才拿 404 |
+     *
+     * 另外两处刻意**不发**：
+     *
+     * - **起服务时那一次**（`index.ts`）—— 见上面那段，且那时没有任何收件人；
+     * - **复活**（`sessions/revive.ts`）—— 它把库里还在、手里没有的那段接回 Hub，
+     *   而那一行**本来就在列表里**（列表的另一半来自 DB）。列表没变，不该发。
+     */
+    notifySessionsChanged(sessionId: string): void;
     /**
      * 收摊：撤掉倒计时、放弃所有挂起的审批、中止所有在跑的回合。
      *
@@ -1597,7 +1865,9 @@ declare class SessionHub {
      * 一轮跑完，把排在后面的那条接上（方案 30 §2.3 第 4 条）。
      *
      * 三个前提缺一不可，缺了就是「浏览器早就关了，服务端自己接着聊」：
-     * 会话还在表里（没被删）、Hub 没收摊、且**还有连接活着**。
+     * 会话还在表里（没被删）、Hub 没收摊、且**还有人在场**（`present`，
+     * 判据在它和 {@link ObserveOptions.counts} 上 —— 2026-09-11 之前这里数的是
+     * `sinks.size`，于是一条即时通讯桥的用户在手机上排的第二条消息会被静默丢掉）。
      */
     private drainQueue;
     private armGrace;
@@ -1818,7 +2088,16 @@ interface AttachedMentions {
  * ⚠️ **从 2026-08-26 起这条路上有两个消费方了**：`usedBytes` 不再从 0 起算，
  * 会话那一半排在文件那一半**之后**，拿到的预算是扣掉文件之后的余额。
  */
-declare function attachMentions(ctx: ApiContext, sessionId: string, message: EpochUserContent): AttachedMentions;
+declare function attachMentions(ctx: ApiContext, sessionId: string, message: EpochUserContent, 
+/**
+ * 输入框里拖进来的那几个附件的**文件名**（2026-09-11）。
+ *
+ * 走的是 `POST .../attachments` 落盘之后回来的那个 `name`，判据在
+ * [attachments.ts](./attachments.js) 文件头。它们和 `@文件` 产出**同一种部件**、
+ * 进**同一本预算账**、收据也进**同一个 `files` 数组** —— 于是界面上
+ * 「这条消息附了哪些文件」只有一张表。
+ */
+uploads?: readonly string[]): AttachedMentions;
 
 /**
  * 一个会话自己那三样（模型 / 权限档 / plan 模式）在**服务端眼里**的样子
@@ -1904,6 +2183,19 @@ interface SessionModelView {
         hasImages?: boolean;
         usedTokens?: number;
     }): SetSelectionView;
+    /**
+     * {@link reset} 会把**这段会话**送回哪个模型 —— 开它那一刻配置里那个（2026-09-13）。
+     *
+     * ⚠️ **这一格进来是因为 `runtime.config.model` 从此答不了这个问题。** 设置页改
+     * `model` 那条路现在会推进进程那份默认（`SettingApply` 的 `new-session` 一档），
+     * 而正在跑的会话连同它们的 `reset()` 目标刻意不跟 —— 于是「进程默认」和
+     * 「这段会话回得去的地方」分家了。
+     *
+     * 继续读 `runtime.config.model` 的表现：菜单里那一项写着一个名字、按下去回到
+     * 另一个，两个都是真实存在的模型，屏幕上没有任何东西会红。判据全文在 core 的
+     * `ProviderRouter.configSelection` 上。
+     */
+    configured(): string;
     /**
      * 只换**这一轮**（自定义斜杠命令 frontmatter 的 `model:`），`restore` 无条件还原。
      *
@@ -2122,10 +2414,15 @@ interface SessionLoopView {
  * （「要让用户换这个会话此刻的模型，得先在 server 加端点」）。
  *
  * ⚠️ **和 [settings.ts](./settings.ts) 那条写端点不是一回事，别合并。**
- * 那一条改盘上的配置文件、要重启才生效、答的是「以后默认用哪个」；
- * 这一条改的是这个进程里正在跑的那个选择、立刻生效、什么都不写盘。
+ * 那一条改盘上的配置文件、答的是「以后默认用哪个」；这一条改的是这个进程里
+ * 正在跑的那个选择、只管这一段会话、什么都不写盘。
  * 整张对照表在 `protocol/src/wire-model.ts` 的文件头。
  *
+ * 2026-09-13 那一条从「要重启才生效」变成了「此后新开的会话用它」
+ * （`SettingApply` 的 `new-session` 一档）。**分工一个字没变，但这个文件受了一处
+ * 影响**：`runtime.config.model` 从此会往前走，而正在跑的会话不跟 —— 于是
+ * 下面 `getModel` 的 `configured` 改成问会话自己那份 router，判据写在那一行上。
+ *
  * ## 结构镜像，不是 import
  *
  * `@epoch-agent/server` **不许 import `@epoch-agent/core`**（`check-layers.mjs`
@@ -2264,6 +2561,8 @@ interface ModelControlView extends ModelTurnsView {
         hasImages?: boolean;
         usedTokens?: number;
     }): SetSelectionView;
+    /** `reset` 会把这段会话送回哪儿。判据见 `sessions/scope.ts` 的同名那一格 */
+    configured(): string;
 }
 /**
  * 这段会话里出现过图片吗 —— 只借**读历史**这一件事。
@@ -2284,16 +2583,24 @@ type ModelSessionFacts = SessionHistoryFacts;
  */
 interface RuntimeModel {
     model: ModelControlView | null;
-    /** 配置里那个模型（`reset` 的目标）。`EpochConfig.model` 结构上满足它 */
+    /**
+     * **这个进程此刻的默认模型** —— 也就是现在新建一段会话会从哪个模型起步。
+     * `EpochConfig.model` 结构上满足它。
+     *
+     * ⚠️ **它不是「`reset` 会把你送回哪儿」**（2026-09-13 起）。那个问题由
+     * `ModelControlView.configured()` 按会话答：设置页改 `model` 会推进这一格，
+     * 而已经在跑的会话连同它们的 reset 目标刻意不跟。两者今天在一台没人改过设置的
+     * 机器上恒等 —— 而「今天恰好相等」正是这个仓库反复在治的那种依赖。
+     */
     config: {
         model: string;
     };
 }
 
 /**
- * 插件那一页的十三条端点（方案 59 §六 E2，2026-08-21；本地源与市场管理 2026-09-04
+ * 插件那一页的十四条端点（方案 59 §六 E2，2026-08-21；本地源与市场管理 2026-09-04
  * 补，判据在 protocol 的 `wire-plugin.ts` 文件头第一节那次**翻案**；上传 2026-09-08
- * 补，判据在那份文件头第一节之二；刷新 2026-09-10 补）：
+ * 补，判据在那份文件头第一节之二；刷新 2026-09-10 补；落区 2026-09-11 补）：
  *
  * ```
  * GET  /api/plugins                       装着的 + 市场里有什么 + 已加的市场 + pendingRestart + uploadEnabled
@@ -2309,6 +2616,7 @@ interface RuntimeModel {
  * POST /api/plugins/upload/preview        {path}          → 会打包哪些文件，一个字节都不发
  * POST /api/plugins/upload                {path, token}   → 打包 + 交给宿主
  * POST /api/plugins/refresh               （不读正文）    → 让宿主重拉目录 + 回一份新列表
+ * POST /api/plugins/stage                 {path} 或字节   → 落地 + 解包 + 验清单 → 一条目录路径
  * ```
  *
  * ## ⚠️ 这一层**一条策略判断都没有**
@@ -2322,10 +2630,10 @@ interface RuntimeModel {
  * 界面上是一条画成可点、点了却被拒的行（判据同 `PluginSearchHit.installable`
  * 为什么不从结果里剔掉远程那条）。
  *
- * ## ⚠️ 那一道闸：**十一条 POST 在回环之外一律 403**，这是这个文件的正题
+ * ## ⚠️ 那一道闸：**十三条 POST 在回环之外一律 403**，这是这个文件的正题
  *
  * 判据全文在 protocol 的 [wire-plugin.ts](../../protocol/src/wire-plugin.ts) 文件头
- * 第二节，这里记它对这一层的**六**条直接后果：
+ * 第二节，这里记它对这一层的**七**条直接后果：
  *
  * 1. **`ctx.lanExposed` 为真时 403 `plugin-write-lan-exposed`，一个字节都不写。**
  *    装一包插件会落下 `hooks.json` 和 `mcp.json`，那两样**起子进程** ——
@@ -2348,6 +2656,11 @@ interface RuntimeModel {
  *    目录、把内容**发到外面去**。放行的话，一个 LAN 上的人能指着 `~/.ssh` 说
  *    「上传它」。⚠️ **预览那一条同样挡**，虽然它一个字节都不发 ——
  *    它回的那份**文件清单本身就是情报**（拿它能探这台机器上有什么）。
+ * 7. **落区那一条（`stage`）最容易被当成例外，而它恰恰不能是**（2026-09-11）：
+ *    「字节是浏览器那台机器上的，又不读服务端的目录」—— 但它**落了盘**，
+ *    而落下来的东西下一步就要被装，装进去的 `hooks.json` 起子进程。风险在落地
+ *    之后那一步，不在字节从哪儿来。⚠️ 它还有一条独占的理由，就是上面第 4 条：
+ *    它的 body 上限是 50 MiB，漏一格就是让 LAN 上的任何人一发一发地灌满内存。
  *
  * ## ⚠️ 这一片可以整个不存在 —— 503 `no-plugin-control`
  *
@@ -2370,7 +2683,7 @@ interface RuntimeModel {
  *
  * 同 [role-add.ts](./role-add.ts) 从 `capability.ts` 里搬出来那次，**刀口按题目下
  * 不按行数**：那个文件答的是「能力页那三栏取什么数」，这一份答的是「怎么往这台
- * 机器上装一包扩展物」。而且这一份带着一整套结构镜像 + 一道闸门 + 七档拒绝的映射。
+ * 机器上装一包扩展物」。而且这一份带着一整套结构镜像 + 一道闸门 + 十档拒绝的映射。
  *
  * ## 进程级，所以 URL 上没有 `:id`
  *
@@ -2571,6 +2884,28 @@ type UploadOutcomeView = {
     version: string;
     bytes: number;
 } | RefusalView;
+/**
+ * `PluginStageInput`（runtime）的镜像 —— 落区那一条收的两种入口。
+ *
+ * ⚠️ **一个可辨识联合，不是「一条 path + 一份可选的 bytes」**：后者拼得出
+ * 「两个都给了」，而这一层就得回答「以哪个为准」—— 一个往盘上写东西的动作
+ * 不该有一个含糊的输入。判据全文在 runtime 的 `PluginStageInput` 上。
+ */
+type StageInputView = {
+    kind: 'path';
+    path: string;
+} | {
+    kind: 'bytes';
+    name: string;
+    data: Uint8Array;
+};
+/** 落区那一条的结局。成功那一档回的是**一条目录路径**，判据见 `PluginControlView.stage` */
+type StageOutcomeView = {
+    ok: true;
+    path: string;
+    name: string;
+    version: string;
+} | RefusalView;
 /**
  * `PluginControl`（runtime）在服务端眼里的样子 —— **只有那十四个动词加两格布尔**。
  *
@@ -2641,16 +2976,23 @@ interface PluginControlView {
      * 口径逐字同 {@link uploadEnabled}。
      */
     readonly refreshEnabled: boolean;
+    /**
+     * 一个压缩包 → 一条已经验过的插件目录路径（2026-09-11，落区那一条）。
+     *
+     * ⚠️ **它一个插件都不装**，所以它回的**不是** {@link InstallOutcomeView} ——
+     * 拿那个形状套会让下一个人以为这一下已经装完了（那个类型的成功档里有 `record`）。
+     */
+    stage(input: StageInputView, lang?: Lang): Promise<StageOutcomeView>;
 }
+declare function toWirePluginEntry(entry: PluginEntryView, 
 /**
- * 装着的一条 → 网线上那一行。
+ * {@link displayNamesOf} 那一份。
  *
- * `marketplace` / `counts` 缺席时下发 **`null` 而不是省掉这个键**，判据同
- * `WireSkillImportEntry.conflict`：两格在 wire 上写成必填，于是「服务端忘了转
- * 这一格」会当场编译不过。而 `counts` 漏掉的表现是一个生效中的插件在界面上
- * 「什么都不带」。
+ * ⚠️ **必传**（哪怕是一张空表），不给默认值 —— 判据同这个文件里
+ * `toWirePluginHit(hit, installed)` 那一格：加一个调用点却忘了传的表现是
+ * 「这张卡上的名字变回英文」，而一个带默认值的参数让那件事**编译期不红**。
  */
-declare function toWirePluginEntry(entry: PluginEntryView): WirePluginEntry;
+displayNames: ReadonlyMap<string, string>): WirePluginEntry;
 /** `PluginUploadForm`（runtime）的镜像 —— 上传那一屏上用户填的七格 */
 type UploadFormView = {
     visibility?: WirePluginVisibility;
@@ -2724,6 +3066,7 @@ interface ProviderOptionView {
     envVar: string | null;
     hasKey: boolean;
     keyHint: string | null;
+    current: boolean;
 }
 /** 一次配 key 的结果。runtime 的 `ProviderKeyWritten` 满足它 */
 interface ProviderKeyWrittenView {
@@ -3009,7 +3352,17 @@ interface BoundWorkspace {
  * `unknown` + 未信任 是「还没问过你」，`untrusted` + 未信任 是「你自己拒过」。
  */
 interface TrustView {
+    /** 读类：这个目录的指令文件 / 技能 / 角色 / 命令加载了吗 */
     trusted: boolean;
+    /**
+     * 执行类：它的 hooks / policies / 项目设置生效了吗（2026-09-11）。
+     *
+     * ⚠️ **`trusted: true` + `exec: false` 是最常见的一档**（拆档之前写下的记录
+     * 全在这儿），所以凡是画「已信任」的地方都得把这一格一起画出来 ——
+     * 否则用户看到的是「已信任」配上「我的 hook 没跑」这一对无法自洽的事实。
+     * 档位判据在 [protocol 的 `TrustTier`](../../../protocol/src/trust.ts)。
+     */
+    exec: boolean;
     /** 存储里的原始判定，**未经**降级规则处理 */
     level: TrustLevel;
 }
@@ -3069,6 +3422,14 @@ interface WorkspaceView {
         root: string;
         name: string;
     }>;
+    /**
+     * 从 {@link known} 那份清单里划掉一行（2026-09-11）。
+     *
+     * ⚠️ **它不碰信任记录** —— 划掉的只是「最近在这儿干过活」。那个目录的信任判定
+     * 一个字都不动，下次再绑回去还是原来那一档。判据全文在 runtime 的
+     * `WorkspaceControl.forget` 和 [forget.ts](./forget.js) 的文件头上。
+     */
+    forget(root: string): void;
     /**
      * **任意**目录的信任判定，不要求它被哪个会话绑着（方案 42 PR-3）。
      *
@@ -3077,6 +3438,13 @@ interface WorkspaceView {
      * 绑着的那几个，于是绝大多数行会显示成「未知」，而真相是它们各有各的记录。
      */
     trustOf(dir: string): TrustView;
+    /**
+     * 这个目录里有什么被闸门挡着（方案 61 ②）。**未信任的目录也数得出来**。
+     *
+     * ⚠️ 它比 {@link trustOf} 贵（要 readdir 几个目录），所以「已知工作区」那份
+     * 清单**不要**逐行调它 —— 判据在 runtime 的 `WorkspaceControl.inventoryOf` 上。
+     */
+    inventoryOf(dir: string): WireProjectInventory;
 }
 
 /**
@@ -3439,7 +3807,12 @@ interface RuntimeSecurity {
  * @param bound 这个会话绑的工作区（`workspaces.of(sessionId)`）。没绑就是 null，
  *   那时 `workspace` 是 null 而**不是**一个空壳 —— 「不使用工作区」是真的一档
  */
-declare function collectSecurity(runtime: RuntimeSecurity, workspaces: Pick<WorkspaceView, 'known' | 'trustOf'>, bound: BoundWorkspace | null, session: Pick<SessionPermissionsView, 'level'> | null): WireSecurityResponse;
+declare function collectSecurity(runtime: RuntimeSecurity, workspaces: Pick<WorkspaceView, 'known' | 'trustOf'>, bound: BoundWorkspace | null, session: Pick<SessionPermissionsView, 'level'> | null, 
+/** 清单 + 门铃（方案 61）。由调用方用 `projectInventoryOf()` 算好递进来 */
+project: {
+    inventory: WireProjectInventory;
+    trustRequest: boolean;
+}): WireSecurityResponse;
 
 /**
  * 检查点与回退的取数、投影与三条端点（方案 27 的 web 那一半）。
@@ -3859,7 +4232,14 @@ interface CatalogRow {
     endedAt: number | null;
     messageCount: number;
     model: string;
-    costUsd: number;
+    /**
+     * 累计估算花费。**`undefined` = 这段会话一轮都没算出过钱**，不是 0
+     * （会话库 v9，2026-09-13；判据全文在 core 的 `SessionMeta.estimatedCostUsd`）。
+     *
+     * 底下 `toWireSummary()` 那句 `?? null` 因此有了真实的两档 —— 在 v9 之前
+     * 它恒为 0，那一句 `?? null` 一次都没走到过。
+     */
+    costUsd?: number;
     /**
      * 用户当初对「这段会话在哪儿干活」做的那次决定（会话库 v7，2026-08-19）。
      * `undefined` = 库里没记过（v7 之前的老行），网线上那是
@@ -4168,6 +4548,24 @@ interface WebRuntimeView extends RuntimeCapabilities, RuntimeSecurity, RuntimeSe
      * 服务日志状态码诊断全部正常。那正是这一节要修的病本身。
      */
     artifactsRoot: string;
+    /**
+     * 用户附件的暂存面（2026-09-11）。`EpochRuntime.attachments` 结构上满足它。
+     *
+     * ## ⚠️ 为什么这一格**不是**一个和 `artifactsRoot` 并排的字符串
+     *
+     * 上面那个能是字符串，是因为 artifact **写和读都在引擎侧**，这一层只拿去显示。
+     * 附件反过来：**写在这一层**（上传落盘），**读在引擎侧**（plugin-file 放开
+     * `attachmentsDir(sessionId, homeDir)` 给模型）。
+     *
+     * 于是这一层还得知道 `<会话 id>` 那一层怎么拼 —— 而那是 infra `bySession()`
+     * 的规则（只留 `[A-Za-z0-9_-]`），**而 `server` 不许 import `infra`**。
+     * 照着抄一份的下场是：sessionId 里出现一个 `:` 的那天，这边写进 `sess:1/`、
+     * 引擎去 `sess_1/` 找 —— 表现是「传上去了，模型说看不到这个文件」，
+     * 而 HTTP 200、盘上真有那个文件、日志一个字不报。
+     *
+     * 所以引擎交出来的是**算好的目录**，不是拼它的材料。
+     */
+    attachments: AttachmentControlView;
     usageScope: 'session' | 'run';
     /**
      * 一段会话到此刻的**累计**用量（2026-09-04）。`EpochRuntime.sessionUsage`
@@ -4491,7 +4889,54 @@ interface ApiContext {
      * 自己也要再查一遍**，别指望浏览器只在按钮亮着的时候才发那一下。
      */
     sameMachine: boolean;
+    /**
+     * 宿主接了「请求授信」那条回调吗，以及接的是哪一个（方案 61，2026-09-11）。
+     *
+     * ## ⚠️ 这不是「信任的写入口上了网线」，读完这一段再动它
+     *
+     * 信任的写入口**刻意不上网线**（方案 42 PR-3）：把它搬到 HTTP 上等于让浏览器
+     * 决定「哪个目录里的文件能当指令读」。**这一条一个字都没翻** —— 这个回调
+     * 收不到 `level`，也收不到 `scope`，浏览器能做的只有**按门铃**。
+     * 决定仍然发生在宿主的对话框里，落盘仍然只有 `runtime.trust.record()` 一条路。
+     *
+     * 形状照抄 `POST /api/workspaces/pick`（`workspace/native-pick.ts`）：
+     * 浏览器发起一个**它自己答不了**的请求，答案来自一个人在别处按的那一下。
+     *
+     * `undefined` = 宿主没接（`epoch web` 起的那一档就是）。那时端点回 404，
+     * 而界面上照旧画「复制 `epoch trust add`」那一块 —— **不画灰按钮**（决定 20 ①）。
+     */
+    trustRequest?: TrustRequestFn;
 }
+/**
+ * 宿主那条「去问用户要不要信任这个目录」的回调。
+ *
+ * ## 三件宿主必须做、而这一层**验证不了**的事
+ *
+ * 1. **真的问用户。** `runtime.trust.record()` 不带闸门，它就是那个决定本身
+ *    （判据在 runtime 的 `EpochRuntime.trust` 上）；
+ * 2. **两档分开问。** 读类和执行类不能一个勾选框全包 —— 那正是方案 61 ① 要修的
+ *    那个缺陷（一句只承诺了「项目指令会加载」的问话，顺带把 hook 也授了）；
+ * 3. **档位由宿主定。** 这个回调的入参里**没有** `level` / `scope`，那是刻意的：
+ *    有了它们，浏览器就从「按门铃」变成了「下命令」。
+ *
+ * ## 它 resolve 的时候什么都没发生过，也可能发生了
+ *
+ * 返回值是 `void`：这一层**不报告用户选了什么**。要知道结果就重新取一次状态
+ * （那份载荷里 `trusted` / `execTrusted` 是真源）。
+ * 让它回一个 `granted: boolean` 的话，那个值和盘上的记录会各自演化 ——
+ * 而两者分叉时界面会信错的那一个。
+ */
+type TrustRequestFn = (req: {
+    /** 用户想解锁的那个目录（服务端绝对路径，已归一到项目根） */
+    root: string;
+    /**
+     * 浏览器**想**解锁哪一档 —— 这是个**提示，不是命令**。
+     *
+     * 它只决定宿主的对话框默认摆在哪一档上（用户从技能页点进来的那一下多半只想
+     * 要读类）。宿主完全可以无视它，也完全可以问完之后授一个不一样的档。
+     */
+    want: 'read' | 'exec';
+}) => void | Promise<void>;
 
 /**
  * 鉴权中间件 —— cookie + Origin/Host 校验。
@@ -5158,9 +5603,30 @@ interface EpochWebServer {
      *
      * 「四种状态怎么映射到宿主窗口上的一枚灯」是宿主的产品决定，我们不替它做。
      *
+     * ## 🔴 2026-09-11：`{ counts: true }` —— 「这条旁听的另一头**有一个人**」
+     *
+     * 上面那句「明确不算人」对一枚状态灯是对的，对一条**即时通讯桥**是错的：
+     * 那一头是用户的手机，而审批卡就在他手里。缺省那一档下，两件事会在他等着的
+     * 时候发生 —— 他关掉电脑上那个窗口 30 秒后**那一轮被中止**，以及他连发的
+     * 第二条消息**被静默丢掉**（一个飞书宿主 2026-09-11 实测到的正是这两条）。
+     *
+     * 所以这件事由宿主自己声明：
+     *
+     * ```ts
+     * // 一枚状态灯：不给（缺省）。灯不会答审批，它亮着不代表有人看着
+     * server.observe(paintLamp);
+     * // 一条飞书 / Slack 桥：给。人在手机上，他答得了审批
+     * server.observe(onFrame, { counts: true });
+     * ```
+     *
+     * 给了之后，这条旁听在**上面那两条判定**上和一个开着的标签页等价
+     * （`connectionCount` 除外 —— 那一格答的是「有几条连接」）。
+     * **给错的后果不对称**，判据和那张「什么时候该给」的表全文在
+     * [hub.ts](./hub.ts) 的 `ObserveOptions.counts` 上。
+     *
      * @returns 取消旁听。**幂等**。`close()` 之后所有旁听自动失效
      */
-    observe(sink: (frame: WireEnvelope) => void): () => void;
+    observe(sink: (frame: WireEnvelope) => void, opts?: ObserveOptions): () => void;
     /**
      * 当前所有会话在 Hub 侧的状态快照 —— 等价于 `GET /api/sessions` 的实时那一半，
      * 不过 HTTP。
@@ -5241,6 +5707,45 @@ interface CreateWebServerOptions {
     heartbeatMs?: number;
     /** 时钟注入，缺省 `Date.now`。用例靠它对齐 fixture 的 `ts` */
     clock?: () => number;
+    /**
+     * 「用户在界面上请求授信」时去问谁（方案 61，2026-09-11）。
+     *
+     * ```ts
+     * await createWebServer({
+     *   runtime,
+     *   version,
+     *   onTrustRequest: async ({ root, want }) => {
+     *     const inv = runtime.workspaces.inventoryOf(root);     // 框里要摆的事实
+     *     const answer = await myApp.showTrustDialog({ root, inv, want });
+     *     if (answer.kind === 'trust') {
+     *       runtime.trust?.record(root, 'trusted', answer.scope, { exec: answer.exec });
+     *     }
+     *   },
+     * });
+     * ```
+     *
+     * ## ⚠️ 不给它，界面就退回「复制一条命令」那一块
+     *
+     * 而那块东西对**嵌入宿主的用户是死路**：他没装 CLI。这一格存在的全部理由就是
+     * 那条死路（判据全文在 runtime 的 `EpochRuntime.trust` 上：
+     * 「界面把这件事说得很清楚，然后递给用户一条 `epoch trust add <root>` ——
+     * 而走这条路的用户压根没装 CLI」）。
+     *
+     * 反过来，`epoch web` 起的那一档**就该不给**：敲得出 `epoch web` 的人手边
+     * 有 CLI，那条命令对他是对的；而多一条原生框就多继承一份 `native-pick.ts`
+     * 文件头记的那两个盲区。
+     *
+     * ## 宿主的三条义务（这一层验证不了，所以写在这儿）
+     *
+     * 1. **真的问用户。** `record()` 不带闸门，它就是那个决定本身；
+     * 2. **两档分开问**（读类 / 执行类）。一个勾选框全包就是方案 61 ① 要修的那个
+     *    缺陷本身；
+     * 3. **别信 `want`。** 它是浏览器给的**提示**（对话框默认落在哪一档），
+     *    不是命令 —— 拿它当档位用，等于把决定权还给了浏览器。
+     *
+     * 完整类型和逐条判据在 [context.ts](./context.js) 的 `TrustRequestFn`。
+     */
+    onTrustRequest?: TrustRequestFn;
 }
 type CreateWebServerResult = {
     ok: true;
@@ -5258,4 +5763,4 @@ type CreateWebServerResult = {
  */
 declare function createWebServer(opts: CreateWebServerOptions): Promise<CreateWebServerResult>;
 
-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 };
+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 ObserveOptions, 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 TrustRequestFn, 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 };