@epoch-agent/server 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,3907 @@
+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';
+
+/**
+ * 绑定策略 —— 「监听哪儿、给不给 token、拒不拒绝启动」。
+ *
+ * [方案 20 §6.1](../../../docs/verify/VERIFY_RECORD-20-web.md)：默认只绑 `127.0.0.1`；
+ * `--host 0.0.0.0` 不给 token 就**拒绝启动**，不是警告后照跑。
+ *
+ * OpenCode 在没配密码时只打一句 `Warning: ... server is unsecured` 然后照跑
+ * （`packages/opencode/src/cli/cmd/serve.ts`）。我们不学这条：本地工具的默认值
+ * 必须是安全的，而「警告 + 照跑」在管道里就等于没警告。
+ *
+ * 整个文件是纯函数 —— 判定不能藏在 CLI 的 action 回调里，那种地方写不了用例，
+ * 而这条判定恰恰是验收第 12 / 13 条。
+ */
+/** 默认端口。4400 是方案里举的那个，没被常见服务占用 */
+declare const DEFAULT_WEB_PORT = 4400;
+/** 默认监听地址 —— 只有回环。改这个默认值需要重读 §6.1 */
+declare const DEFAULT_WEB_HOST = "127.0.0.1";
+interface BindRequest {
+    /** `--host`，缺省 `127.0.0.1` */
+    host?: string;
+    /** `--port`，缺省 4400。`0` = 让内核分配（用例靠它避免端口打架） */
+    port?: number;
+    /** `--token`。非回环绑定时**必填** */
+    token?: string;
+}
+type BindDecision = {
+    ok: true;
+    host: string;
+    port: number;
+    token: string;
+    /** 绑在回环之外。鉴权中间件据此放宽 `Host` 白名单，见 auth.ts */
+    lanExposed: boolean;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * 算出这次该怎么绑。**不做任何 I/O**。
+ *
+ * 拒绝启动的唯一理由是「暴露到回环之外却没有 token」。端口非法也拒 ——
+ * 那属于参数拼错，不该让它一路走到 `listen()` 再抛一个 `ERR_SOCKET_BAD_PORT`。
+ */
+declare function decideBinding(req?: BindRequest): BindDecision;
+/**
+ * 每次启动一个新 token。
+ *
+ * 刻意**不用环境变量密码**（OpenCode 走的是 `OPENCODE_SERVER_PASSWORD` + Basic）：
+ * 那是给远程服务设计的，本地工具不该要求用户先配一个环境变量才能用。
+ * 32 字节 = 256 位，base64url 之后可以直接放进 URL 而不用再转义。
+ */
+declare function generateToken(): string;
+/**
+ * 首屏 query 上那两个键（方案 54 §七）。
+ *
+ * **和 web 的 `src/prefs.ts` / `index.html` 逐字一致**，三份字面量由
+ * `packages/web/__tests__/prefs.test.ts` 钉着 —— 那边读这个文件的原文来比。
+ * 不能 import：`@epoch-agent/web` 是 `private: true` 的应用包，server 不依赖它
+ * （反过来才对：web 的产物随 server 发）。
+ */
+declare const UI_THEME_PARAM = "theme";
+declare const UI_LANG_PARAM = "lang";
+/**
+ * 宿主给界面的主题初值。值域和界面存进 `localStorage['epoch.theme']` 的那份**相同**。
+ *
+ * `'system'` 不是「不给」—— 它是明确的第三档（跟随系统），和不传这个字段
+ * （用户上次自己选的那个还算数）是两件事。
+ */
+type UiThemePref = 'system' | 'light' | 'dark';
+/** 同上，对应 `localStorage['epoch.lang']`。值域跟着 protocol 的 `LANGS` 走 */
+type UiLangPref = 'system' | 'zh' | 'en';
+/**
+ * 宿主给界面的首屏初值（方案 54 §七）。
+ *
+ * ⚠️ **是初值，不是锁。** 它写进浏览器的 localStorage 之后，用户在设置页的
+ * 「外观」分区仍然改得动；下次启动宿主再给一次初值。刻意**没有**「强制主题、
+ * 界面上不许改」的开关：那是把宿主的偏好升成锁，而外观是今天用户在这张界面上
+ * 唯一能自己调的东西（方案 54 §七末尾 + §十一）。
+ */
+interface UiPreset {
+    theme?: UiThemePref;
+    lang?: UiLangPref;
+}
+/**
+ * 首屏地址 —— 带 `?token=` 的那一条，用来换 cookie。
+ *
+ * @param port 必须是**实际监听**的端口（`--port 0` 时由内核分配），
+ *             不是命令行里那个
+ * @param ui   宿主给的主题 / 语言初值。不给就一个参数都不拼 ——
+ *             URL 逐字节和以前一样（`epoch web` 走的就是这条）
+ */
+declare function firstScreenUrl(host: string, port: number, token: string, ui?: UiPreset): string;
+
+/**
+ * `mcp.json` 的**原文**那三条端点 —— `GET` / `PUT /api/mcp/config` 和
+ * `POST /api/mcp/config/apply`（2026-08-18）。
+ *
+ * [connectors.tsx](../../web/src/capability/connectors.tsx) 文件头那句「**「添加
+ * server」/「看它的配置」**：没有读写 `mcp.json` 的端点」，前一半那天由
+ * `POST /api/mcp` 到期，**后一半就是这三条**。
+ *
+ * ## 为什么不跟着 [mcp.ts](./mcp.ts) 住一起
+ *
+ * **刀口按题目下不按行数**（那条规矩是 `mcp.ts` 自己从 `capability.ts` 里搬出来时
+ * 立的）：那个文件答的是「怎么动这个进程里的 MCP 连接」和「怎么往那份文件里**加
+ * 一台**」，而这三条答的是「怎么把**整份原文**发出去、收回来、再搬进这个进程」。
+ * 而且这一份自带一道闸门 + 三套结构镜像 + 十档拒绝。
+ *
+ * ## 三条端点，三个不同的作用域 —— 而这件事必须写在界面上
+ *
+ * | 端点                         | 改的是               | 影响                                              |
+ * | ---------------------------- | -------------------- | ------------------------------------------------- |
+ * | `GET /api/mcp/config`        | 什么都不改           | —                                                 |
+ * | `PUT /api/mcp/config`        | **落盘的那份文件**   | 这台机器上**以后每一个** epoch 进程               |
+ * | `POST /api/mcp/config/apply` | **这个进程的连接**   | 这个进程里所有会话，**立刻**                      |
+ *
+ * ⚠️ 后两条不是同一句话，别合并（判据全文在 protocol 的 `wire-mcp-config.ts`
+ * 文件头第二节）：一个是「盘上那份变了」，一个是「正在跑的这些变了」。**保存不
+ * 生效、应用才生效**，而那句话要恒画在界面上。
+ *
+ * ## ⚠️ 闸门：`ctx.lanExposed` 为真时三条**全部** 403
+ *
+ * 判据借的是 `POST /api/roles` 那道（[role-add.ts](./role-add.ts) 文件头），
+ * 但这条路上**连读都要挡**，两条理由各自成立：
+ *
+ * 1. **读**：这份文件里的 `env` 是**明文密钥**。把它的原文发给一个我们无法确认
+ *    在本机的浏览器就是把那几个 token 发出去 —— 而 agent 自己那条读文件的路
+ *    够不到它（在工作区边界之外）。所以这**不是**「反正他本来就读得到」；
+ * 2. **写**：这条路写得下 `command` 那一格 = 这台机器上任意一个可执行文件加它的
+ *    参数，而 `apply` 会把它 spawn 起来。它比 role-add 那条（往 system prompt 里
+ *    塞字）还要直接一格。
+ *
+ * ⚠️ 界面那一侧另有一道，但它是**给人的**（`GET /api/config` 的 `lanExposed`，
+ * 决定 20 ①）。两道各答一半，别拿一条当另一条用 —— 那一格是客户端自己改得动的
+ * 布尔。
+ *
+ * ## 结构镜像，不是 import（同 `mcp.ts` / `role-add.ts` 文件头）
+ *
+ * `McpControl` 的真身在 runtime，这里按用得到的字段再声明一遍，`EpochRuntime`
+ * **结构上**正好满足。镜像里只有三个方法，于是这个包**写不出**
+ * `disconnectAll()` —— 那不是靠 review 盯住的，是编译期的事。
+ */
+
+/** 一条诊断。`McpConfigIssue`（runtime）的镜像，也和网线上那个逐字同形 */
+interface McpConfigIssueView {
+    path: string;
+    message: string;
+}
+/** 盘上那份此刻的样子。`McpConfigSnapshot`（runtime）的镜像 */
+interface McpConfigSnapshotView {
+    configPath: string;
+    text: string;
+    exists: boolean;
+    revision: string;
+    issues: readonly McpConfigIssueView[];
+}
+type McpConfigReadView = {
+    ok: true;
+    snapshot: McpConfigSnapshotView;
+} | {
+    ok: false;
+    reason: 'unreadable';
+    detail: string;
+};
+type McpConfigSaveView = {
+    ok: true;
+    configPath: string;
+    revision: string;
+    issues: readonly McpConfigIssueView[];
+} | {
+    ok: false;
+    reason: 'stale' | 'invalid-json' | 'unwritable';
+    detail: string;
+};
+/**
+ * 逐台一行。⚠️ `status` 那一格是 **`McpView`**（这个包对状态的镜像），不是
+ * runtime 的 `McpServerStatus` —— 判据同 `McpControlView` 上那两条回执。
+ */
+interface McpApplyChangeView {
+    name: string;
+    action: 'added' | 'reconnected' | 'unchanged' | 'removed' | 'skipped';
+    status?: McpView;
+    reason?: 'name-taken';
+}
+type McpApplyView = {
+    ok: true;
+    configPath: string;
+    revision: string;
+    issues: readonly McpConfigIssueView[];
+    changes: readonly McpApplyChangeView[];
+} | {
+    ok: false;
+    reason: 'unreadable' | 'stale' | 'invalid-json' | 'no-servers';
+    detail: string;
+};
+/**
+ * `McpControl` 里**管那份文件的那三个方法**在服务端眼里的样子。
+ *
+ * ## 为什么是第二份镜像，而不是往 `McpControlView` 上加三行
+ *
+ * 那三个方法和 `reconnect` / `add` 挂在**同一个** runtime 对象上（`runtime.mcp`），
+ * 所以这两份镜像在装配点上是一个交集（见 `RuntimeCapabilities.mcp`）。分成两份是
+ * 为了让**镜像跟着 handler 走**：判据同这个文件为什么不跟 `mcp.ts` 住一起 ——
+ * 下一个改这三条端点的人，要读的判据全在这一个文件里。
+ *
+ * @see McpConfigControlView.writeConfig 上那条 `lang` 的 ⚠️
+ */
+interface McpConfigControlView {
+    readConfig(): McpConfigReadView;
+    /**
+     * @param lang 这一次的 `detail` 用哪个语言说（方案 58 PR-2）。
+     *
+     * ⚠️ **镜像上这一格是必须的**：这个包不 import runtime 的类型
+     * （`check-layers` 是硬闸门），少声明它的话 `EpochRuntime` 照样满足这份镜像
+     * （多一个可选参数是宽化），而这一层就**递不出去** —— 一声不吭地回中文。
+     * 判据逐字同 `RoleWriteControlView.add`。
+     */
+    writeConfig(text: string, revision: string, lang?: Lang): McpConfigSaveView;
+    applyConfig(revision: string, lang?: Lang): Promise<McpApplyView>;
+}
+
+/**
+ * 那一屏上的两个 **MCP 动作** —— `POST /api/mcp/:name/reconnect`（方案 56 §1.1）
+ * 和 `POST /api/mcp`（2026-08-18）。
+ *
+ * ## 为什么从 [capability.ts](./capability.ts) 里搬出来
+ *
+ * 那个文件答的是「能力页那三栏取什么数、怎么投影」。这两条答的是**别的问题**：
+ * 「怎么动这个进程里的 MCP 连接」和「怎么往用户磁盘上那份 `mcp.json` 里加一台」。
+ * 2026-08-18 加完「添加」之后那边到了 546 行（铁律 3 是 500），而**刀口按题目下**
+ * ——不是按行数硬切一半。
+ *
+ * 技能正文那条（`GET /api/sessions/:id/skills/:name`）**留在那边**：它是同一份三栏
+ * 数据的下钻，和这两条不是一类。
+ *
+ * ## ⚠️ 两条 URL 上都没有 `:id`，而且不许有
+ *
+ * MCP 连接是装配期起的那几个 client，一个进程一份 —— 挂到 `/sessions/:id/` 下面会
+ * 得到一条**名字是会话级、行为是进程级**的端点，比不一致更坏。而能力页读的偏偏
+ * 是会话作用域的那一发（`GET /api/sessions/:id/capabilities`）。
+ *
+ * **这处读写作用域不一致由界面在按下去之前说清**（决定 20 ①），不由 URL 假装。
+ *
+ * ⚠️ 而且**那两句话不是同一句，别合并**：
+ *
+ * | 端点                            | 改的是                | 影响                                                    |
+ * | ------------------------------- | --------------------- | ------------------------------------------------------- |
+ * | `POST /api/mcp/:name/reconnect` | 这个进程里的一个连接  | 这个进程里所有会话                                      |
+ * | `POST /api/mcp`                 | **落盘的 `mcp.json`** | 这个进程，**外加这台机器上以后每一个 epoch 进程**       |
+ *
+ * ## ⚠️ 两条端点上只有下面那条有闸门，而那不是不一致
+ *
+ * `addMcp` 在 `ctx.lanExposed` 为真时 **403 `mcp-add-lan-exposed`，一个字节都不写**；
+ * `reconnectMcp` 没有这一道。两者的分界线**逐字就是上面那张表**：重连动的是这个
+ * 进程里已经存在的一个连接（那台 server 是用户自己早先写进 `mcp.json` 的），
+ * 而添加往那份文件里**新落一条 `command`** —— 那一格是这台机器上任意一个可执行文件，
+ * 加进来的那台当场就被 spawn 起来，而且这台机器上以后每一个 epoch 进程都会照着它起。
+ *
+ * 判据全文在 protocol 的 [wire-agent-role.ts](../../protocol/src/wire-agent-role.ts)
+ * 文件头那五节 + [wire-capability.ts](../../protocol/src/wire-capability.ts) 的
+ * `WireMcpAddRequest` 上（**同一套论证，三条写口共用**，另两条是 `POST /api/roles`
+ * 和 [mcp-config.ts](./mcp-config.ts) 那三条）。这里只记它对这一层的两条直接后果：
+ *
+ * 1. **闸门在读请求体之前**（同 `addRole` / `saveConfig`）：被拒的那一发连正文都不该
+ *    被解析，更不该有任何一个字节走到 `ctx.runtime.mcp.add` 那条路上。⚠️ 用例要断的
+ *    因此是**写口的调用次数为 0**，不是状态码 —— 一个「先调写口、再看 `lanExposed`
+ *    决定回什么码」的实现照样能让「回了 403」那条绿，而它已经写下去、还起了一个进程；
+ * 2. **只挡这一条，不挡重连**。别顺手把 `reconnectMcp` 一起关掉：那会让一个绑在
+ *    `0.0.0.0` 上的服务连「对面重启过、点一下重连」都做不到，而那一下不落任何字节。
+ *
+ * ## 结构镜像，不是 import（同 capability.ts 文件头）
+ *
+ * `@epoch-agent/server` 不许 import `@epoch-agent/core`，而 `McpControl` 的真身在
+ * runtime。所以这里按用得到的字段再声明一遍，`EpochRuntime` **结构上**正好满足它。
+ * 镜像里只有两个方法，于是这个包**写不出** `disconnectAll()` —— 那不是靠 review
+ * 盯住的，是编译期的事。
+ */
+
+/**
+ * `McpControl`（runtime）在服务端眼里的样子 —— **重连和添加，就这两件事**。
+ *
+ * 镜像里只有这两个方法，于是这个包**写不出** `disconnectAll()`：那不是靠
+ * review 盯住的，是编译期的事（同五份安全镜像各自漏掉一个中文字段的做法）。
+ * ⚠️ 加一格的时候是**在这份镜像上加一个方法**，不是把 `McpRegistry` 转过来 ——
+ * 方案 56 立的规矩，判据在 runtime 的 `McpControl` 上。
+ */
+interface McpControlView {
+    reconnect(name: string): Promise<McpReconnectView>;
+    add(input: McpAddView): Promise<McpAddResultView>;
+}
+/**
+ * 重连回执的镜像。`detail` 是**底层原样那句话**（可缺席）——
+ * 这一层不改写它，也不在它缺席时编一句，判据同 `WireMcpConnector.lastError`。
+ */
+type McpReconnectView = {
+    ok: true;
+    status: McpView;
+} | {
+    ok: false;
+    reason: 'failed';
+    detail?: string;
+    status: McpView;
+} | {
+    ok: false;
+    reason: 'unknown';
+};
+/**
+ * `McpAddInput`（runtime）的镜像。**和 `WireMcpAddRequest` 逐字同形，但不能合并**
+ * —— 一个是网线契约（浏览器和我们之间），一个是这个包对 runtime 的期望。
+ * 两者今天一样，是因为这条路上没有任何投影要做；哪天要做（比如服务端替用户
+ * 补一个默认超时），分开的这两份就是那次改动落脚的地方。
+ */
+interface McpAddView {
+    name: string;
+    transport: 'stdio' | 'sse' | 'http';
+    command?: string;
+    args?: readonly string[];
+    url?: string;
+    env?: Readonly<Record<string, string>>;
+}
+/**
+ * 添加回执的镜像。
+ *
+ * ⚠️ **`ok: true` 的判据是「配置落了盘」，不是「连上了」。** 连不上的那台照样
+ * `ok: true`，那时 `status.connected` 是 false —— 判据全文在
+ * `WireMcpAddResponse` 上（「连不上不是失败，那是这条端点上最要紧的一句话」）。
+ */
+type McpAddResultView = {
+    ok: true;
+    status: McpView;
+    configPath: string;
+} | {
+    ok: false;
+    reason: 'invalid-name' | 'invalid-config' | 'duplicate' | 'unwritable';
+    detail: string;
+};
+
+/**
+ * 「新建一个身份」那条端点 —— `POST /api/roles`（2026-08-18）。
+ *
+ * 能力页那三栏里，技能和连接器 2026-08-18 各长出了一个写口
+ * （[skill-import.ts](./skill-import.ts)、[mcp.ts](./mcp.ts)），
+ * **只有身份那一栏还是纯只读的**。这一条把它补上。
+ *
+ * ## ⚠️ 闸门：**绑在回环之外就一律 403**，这是这个文件存在的正题
+ *
+ * 判据全文在 protocol 的 [wire-agent-role.ts](../../protocol/src/wire-agent-role.ts)
+ * 文件头（五节），这里记它对这一层的四条直接后果：
+ *
+ * 1. **`ctx.lanExposed` 为真时 403 `role-add-lan-exposed`，一个字节都不写。**
+ *    往 `~/.epoch/agents/` 落一份 md = 让那段文字无条件进往后每一轮的上下文
+ *    （`description` 那一格进 `delegate_task` 的工具描述，**不需要任何人挑它**），
+ *    而角色目录那张闸门表上用户级那一格逐字写着「无（是用户自己的机器）」——
+ *    「是用户自己的机器」正是 `--host 0.0.0.0` 那一档下不成立的那条；
+ * 2. **不能拿「反正他能让 agent 跑命令」开绿灯。** `plan` 档和只读会话下 agent
+ *    一个字节都落不了盘，而这条端点落得了 —— 那是一次**跨权限轴的提权**，
+ *    不是「本来就能做的事换个写法」（方案 42 §11.2 那句现成的话在这里不成立）；
+ * 3. **是 POST，而且必须是**：`auth.ts` 的 Origin 校验只在非安全方法上要求，
+ *    而这一条会在用户机器上真的写文件（同 skill-import 那条第 2 点）；
+ * 4. **skill-import 那个答案抄不了。** 那条判成「收路径不收字节」，而
+ *    「新建一个身份」的本体就是用户敲一段 prompt 正文 —— 收路径不收字节 =
+ *    这条路整个不存在。所以这一格必须另外答，答案就是上面第 1 条。
+ *
+ * ⚠️ **界面那一侧还有一道，但它是给人的**：`GET /api/config` 上带着
+ * `lanExposed`，能力页据此在**按下去之前**就把「这一档下建不了」画出来
+ * （决定 20 ①）。两道各答一半 —— 别因为界面上画了就把这一道摘掉，
+ * 那一格是客户端自己改得动的布尔（同 skill-import 那张两道闸门的表）。
+ *
+ * ## 为什么单开一个文件
+ *
+ * 同 [mcp.ts](./mcp.ts) 从 `capability.ts` 里搬出来那次，**刀口按题目下不按行数**：
+ * 那个文件答的是「能力页那三栏取什么数、怎么投影」，这一条答的是「怎么往这台
+ * 机器上建一个身份」。而且这一份带着一整套结构镜像 + 一道闸门 + 六档拒绝的映射。
+ *
+ * ## 进程级，所以 URL 上没有 `:id`
+ *
+ * 落点是 `~/.epoch/agents/`（用户级，一个进程一份），判据逐字同 `reconnectMcp` 和
+ * `importSkills`：挂在 `/sessions/:id/` 下面会得到一条名字是会话级、行为是进程级
+ * 的端点，比不一致更坏。
+ *
+ * ⚠️ 而它比重连**远一格**、和 `POST /api/mcp` **同一格**：改的是落盘的东西，
+ * 影响这个进程外加这台机器上以后每一个 epoch 进程（CLI / TUI / 别的宿主）。
+ * 界面上那句话不能照抄重连那一句。
+ */
+
+/**
+ * `RoleAddInput`（runtime）的镜像。**和 `WireRoleAddRequest` 逐字同形，但不能合并** ——
+ * 一个是网线契约（浏览器和我们之间），一个是这个包对 runtime 的期望。判据逐字同
+ * `McpAddView`：两者今天一样是因为这条路上没有投影要做；哪天要做，分开的这两份
+ * 就是那次改动的落脚点。
+ */
+interface RoleAddView {
+    name: string;
+    description: string;
+    prompt?: string;
+    tools?: readonly string[];
+    maxTurns?: number;
+}
+/**
+ * 建成之后那一份。**`role` 是重载之后那张表里的那一个**，不是把请求体抄一遍 ——
+ * 判据在 `WireRoleAddResponse.role` 上。
+ */
+type RoleAddResultView = {
+    ok: true;
+    role: RoleView;
+    path: string;
+} | {
+    ok: false;
+    reason: 'invalid-name' | 'invalid-field' | 'duplicate' | 'unknown-tool' | 'unwritable';
+    detail: string;
+};
+/**
+ * `RoleWriteControl`（runtime）在服务端眼里的样子 —— **只有 `add` 这一个动作**。
+ *
+ * 镜像里只有它，于是这个包**写不出**「删一个身份」「改一个身份」：那不是靠
+ * review 盯住的，是编译期的事（同 `McpControlView` 只有两个方法、
+ * `SkillImportControlView` 只有两个动作）。
+ *
+ * ⚠️ 要加 `remove` 的时候**先回去读 protocol 那份文件头第三节**：删一个身份不会
+ * 往 system prompt 里塞字，但会**静默拿掉**别人正依赖的一段边界 ——
+ * 那道闸门的判据和「建」不一样，是一次独立的判断。
+ */
+interface RoleWriteControlView {
+    /**
+     * @param lang 这一次的 `detail` 用哪个语言说（方案 58 PR-2）。
+     *             六档拒绝里有五档的文案（runtime 那侧的 `role_write.*`）**在那一层
+     *             渲染**，这一层只原样转发 —— 所以这一格必须穿过去，否则英文界面上
+     *             建身份失败拿到的是一句中文。
+     *
+     * ⚠️ 镜像上加这一格是**必须的**：这个包不 import runtime 的类型（`check-layers`
+     *    是硬闸门），少声明它的话 `EpochRuntime` 照样满足这份镜像（多一个可选参数是
+     *    宽化），而这一层就**递不出去** —— 一声不吭地回中文。判据同 `McpView.source`
+     *    那条 ⚠️：镜像漏一格不一定会红。
+     */
+    add(input: RoleAddView, lang?: Lang): RoleAddResultView;
+}
+
+/**
+ * 从本机目录导入技能的两条端点（方案 42 §六，2026-08-18）：
+ *
+ * ```
+ * POST /api/skills/import/preview   {path}         → 「将导入什么」，不写字节
+ * POST /api/skills/import           {path, token}  → 真导入
+ * ```
+ *
+ * ## ⚠️ 闸门：这两条**收路径，不收字节**
+ *
+ * 判据全文在 core 的 [skill/import.ts](../../core/src/skill/import.ts) 文件头，
+ * 这里记它对这一层的三条直接后果：
+ *
+ * 1. 请求体里只有 `path` 和 `token`，**没有 `content`**。用户级技能目录连信任
+ *    闸门都没有 —— 往它里面落一份文件 = 让那段文字无条件进往后每一轮的 system
+ *    prompt。而 `--host 0.0.0.0` 那一档下浏览器可能不在用户自己那台机器上；
+ * 2. 两条都是 **POST**，而且必须是：`auth.ts` 的 Origin 校验只在非安全方法上
+ *    要求，而第二条会在用户机器上真的写文件。写成 GET 等于任何一个页面都能
+ *    替用户按下那个确认；
+ * 3. `token` 是**服务端自己重算的**，不是信客户端说的。它防的是预览和导入之间
+ *    目录被改过 —— 插件那条路在一个进程里跑完，没有这条缝。
+ *
+ * ⚠️ **界面上那一屏「导入前预览」是另一道闸门，两道都要有。** 它防的是**人**
+ * 装错，这一层防的是**网线**决定 system prompt 里的字。两条各答一半，
+ * 别拿一条当另一条用（同 core 那个文件头那张表）。
+ *
+ * ## 为什么单开一个文件
+ *
+ * 同 `workspace/dirs.ts` 从 `handlers.ts` 里分出来那两条判据：
+ *
+ * 1. **作用域不同。** [capability.ts](./capability.js) 那几条按 `:id` 取，
+ *    这两条答的是「往这台机器的 `~/.epoch/skills/` 里放一份」—— 和你现在看着
+ *    哪个会话无关，所以它们连 sessionId 都不收（同 `POST /api/mcp/:name/reconnect`）；
+ * 2. 那个文件已经 400 多行，而这一份带着一整套结构镜像加两个 handler。
+ *
+ * ## 进程级，所以 URL 上没有 `:id`
+ *
+ * 写入落点是 `~/.epoch/skills/`（用户级，一个进程一份），判据逐字同
+ * `reconnectMcp`：挂在 `/sessions/:id/` 下面会得到一条名字是会话级、行为是
+ * 进程级的端点，比不一致更坏。
+ *
+ * ## ⚠️ 这两条上的文案是**第三种形态**，不是 `sendError`（方案 58 §1.2 那条 📮）
+ *
+ * `issues[].message` / `skipped[].message` / `detail` 走的是 **200 响应体**，
+ * 不是 `{error:{code,message}}`，也不是启动诊断。它们在 **core** 里现渲染
+ * （`skill/import.ts` + `import-source.ts` 十几处 `t()`），所以 `lang` 要从这一层
+ * 一路穿过 runtime 的 `SkillControl` 递到 `SkillImportOptions`。
+ *
+ * 这个病 **2026-08-18 用 CDP 实测见过**：中文界面上那一屏的诊断块里印的是英文
+ * （开发机 `resolveLang()` 解析成 en，而那几条当时跟着**进程**语言走）。
+ *
+ * ⚠️ **只有这两条端点递 `lang`，`SkillSystem` 别的写口一个都不递** —— 那些的产物
+ * 会进 system prompt / 落盘，属于方案 58 §2.6 第三档「谁都不跟」。
+ *
+ * ⚠️ 但**撞名判定里 `shadowed` 那一档确实读了「项目级」那一层**，而项目级跟着
+ * 工作区走（决定 18）。今天这个进程里只有一个会话，两者重合；等方案 30 §6.3
+ * 的多会话工厂落地，那一档要按 `workspaces.of(sessionId)` 重算 —— 口径逐字同
+ * [capability.ts](./capability.js) 文件头最后那条 ⚠️。**写入那一半不受影响**，
+ * 它本来就是进程级的。
+ */
+
+/** 一条诊断在服务端眼里的样子（core 的 `ParseIssue`，不能直接 import） */
+interface IssueView {
+    path: string;
+    message: string;
+}
+/** `SkillImportEntry` 的镜像。`conflict` 那个联合同 `RoleView.source` 那条 ⚠️ */
+interface ImportEntryView {
+    name: string;
+    category: string;
+    description: string;
+    files: number;
+    bytes: number;
+    conflict?: {
+        scope: 'user' | 'project' | 'plugin' | 'host';
+        verdict: 'refuse' | 'shadowed';
+    };
+}
+interface ImportPreviewView {
+    form: WireSkillImportForm;
+    source: string;
+    skills: readonly ImportEntryView[];
+    issues: readonly IssueView[];
+    token: string;
+}
+interface ImportDoneView {
+    preview: ImportPreviewView;
+    imported: readonly string[];
+    skipped: readonly IssueView[];
+}
+type ImportResultView<T> = ({
+    ok: true;
+} & T) | {
+    ok: false;
+    reason: WireSkillImportFailure;
+    detail: string;
+    issues?: readonly IssueView[];
+};
+/**
+ * `SkillControl`（runtime）在服务端眼里的样子 —— **只有这两个动作**。
+ *
+ * 镜像里只有它们，于是这个包**写不出** `SkillSystem` 上那六个写方法、
+ * 也写不出会 `matchCount++` 的 `view()` 和会自动删技能的 `maintain()`：
+ * 那不是靠 review 盯住的，是编译期的事（同 `McpControlView` 只有 reconnect）。
+ */
+interface SkillImportControlView {
+    preview(source: string, lang?: Lang): Promise<ImportResultView<{
+        preview: ImportPreviewView;
+    }>>;
+    import(source: string, token: string, lang?: Lang): Promise<ImportResultView<ImportDoneView>>;
+}
+
+/**
+ * 能力页的取数与投影 —— `GET /api/sessions/:id/capabilities`（方案 42 PR-1），
+ * 外加技能正文那条下钻（方案 56 §1.2）。
+ *
+ * 不在 [api.ts](./api.ts) 里，理由和 `workspace/handlers.ts` 一样：那个文件是
+ * 「一个端点一个函数」，而这里有一份 runtime 能力的**结构镜像**加三段投影 ——
+ * 塞进去会让它变成「一个端点一个函数，外加一百行别的」。
+ *
+ * ## 后补的那条下钻（方案 56 §1.2）
+ *
+ * `GET /api/sessions/:id/skills/:name` —— 一个技能的正文。
+ *
+ * ⚠️ **走的是 `runtime.skillBody()`，不是引擎那条 `view()`。** 后者会
+ * `matchCount++`，而那个数决定模型看得见哪些技能 —— 一次浏览不该被算成一次命中。
+ * 判据在 core 的 `SkillSystem.body` 上。
+ *
+ * ## ⚠️ 那两条 MCP 动作**不在这个文件里**，在 [mcp.ts](./mcp.ts)
+ *
+ * `POST /api/mcp/:name/reconnect`（方案 56 §1.1）和 `POST /api/mcp`（2026-08-18）
+ * 2026-08-18 搬出去了。刀口**按题目下不按行数**：这个文件答的是「那三栏取什么数、
+ * 怎么投影」，那两条答的是「怎么动这个进程里的 MCP 连接 / 怎么往用户磁盘上那份
+ * `mcp.json` 里加一台」。正文那条留下来，因为它是同一份三栏数据的下钻。
+ *
+ * （直接原因是加完「添加」之后这个文件到了 546 行，铁律 3 是 500。但**按行数切
+ * 一半**会切出一个没有题目的文件，那比超一点更坏。）
+ *
+ * ## 结构镜像，不是 import
+ *
+ * `@epoch-agent/server` **不许 import `@epoch-agent/core`**（check-layers.mjs
+ * 是硬闸门），而角色 / 技能 / MCP 状态这三样的真身都是 core 或插件的类型。
+ * 所以这里按用得到的字段再声明一遍，`EpochRuntime` **结构上**正好满足它 ——
+ * 对不上就是镜像漏了一块，装配那一行当场编译不过。收窄到这几项还有一个好处：
+ * 用例喂一个十几行的假对象就能跑，不用起一个真 runtime。
+ *
+ * ## 「进程有什么」和「这个会话有什么」，今天是同一份
+ *
+ * 角色和技能里的「项目」那一层来自工作区（`<root>/.epoch/agents/`、
+ * `<root>/.epoch/skills/`），而工作区是**按会话**绑的（决定 18）。今天这个进程
+ * 里只有一个会话（`server/src/index.ts` 只 `hub.register()` 一次），所以两者
+ * 重合，直接读 `runtime.agentRoles` / `runtime.skills` 是对的。
+ *
+ * ⚠️ 等方案 30 §6.3 的多会话工厂落地，同一个进程里的两个会话会绑在两个仓库上，
+ * 那时**这里要改**：项目那一层得按 `workspaces.of(sessionId)` 重新加载，
+ * 而不是读进程装配时那一份。URL 现在就定成会话作用域，为的就是那天不用再动
+ * 一次前端 —— 换成 `/api/capabilities` 的话，那天要改的是两个包。
+ */
+
+/**
+ * `AgentRole` 在服务端眼里的样子（`@epoch-agent/core` 的类型，不能直接 import）。
+ *
+ * ⚠️ `source` 那个联合是**抄**过来的，所以它是这份镜像上唯一会静默走散的字段 ——
+ * 真源加一格而这里不加，`EpochRuntime` 当场不满足 `WebRuntimeView`，装配那一行
+ * 编译不过（文件头「结构镜像，不是 import」那一节说的就是这条）。方案 44 加
+ * `'host'` 时走的正是这条路，那个红就是它的验收手段。
+ */
+interface RoleView {
+    name: string;
+    description: string;
+    tools?: readonly string[];
+    maxTurns?: number;
+    source: 'builtin' | 'user' | 'project' | 'plugin' | 'host';
+}
+/**
+ * `RoleMergeNotice` 的镜像。**只取 `role` 和 `cut`** —— `detail` 是中文文案，
+ * 浏览器要用自己的 catalog 组句（同诊断的规矩），下发它等于让英文界面照抄中文。
+ */
+interface RoleNoticeView {
+    role: string;
+    cut: readonly string[];
+}
+/** `SkillMeta` 在服务端眼里的样子。`scope` 同上一条 ⚠️ */
+interface SkillView {
+    name: string;
+    description: string;
+    category: string;
+    type: string;
+    scope: 'user' | 'project' | 'plugin' | 'host';
+}
+/**
+ * `McpServerStatus`（`@epoch-agent/plugin-mcp`）在服务端眼里的样子。
+ *
+ * ⚠️ `source` 那一格和上面两条 ⚠️ **不是同一回事，别照着读**。角色的 `source` /
+ * 技能的 `scope` 是**已有**联合多一格，真源加而这里不加会当场编译不过；这一格
+ * 是真源上**新增**的一个字段 —— 加字段是宽化，这份镜像不声明它只会一声不吭地
+ * 不下发，没有任何东西会红（方案 44 §3.4 点名的就是这一样）。
+ *
+ * 它今天之所以照样漏不掉，是因为 `WireMcpConnector.source` **写成了必填**：
+ * 这里不声明 → `toWireMcp` 读不到那一格 → 产出的对象不满足 `WireMcpConnector`
+ * → 本包 typecheck 当场红。完整判据在 protocol 那一侧那条 JSDoc 上。
+ */
+interface McpView {
+    name: string;
+    connected: boolean;
+    toolCount: number;
+    lastError?: string;
+    reconnectAttempts: number;
+    /** 认证过不去。**重连解决不了它**，要 `epoch mcp login <name>` */
+    needsLogin?: boolean;
+    /** 谁带进来的：用户的 `mcp.json` / 嵌入宿主 / 某个已装插件（方案 44 PR-2、PR-3） */
+    source: 'user' | 'host' | 'plugin';
+}
+/** server 从 runtime 借的「能力」那一片。`WebRuntimeView` 继承它 */
+interface RuntimeCapabilities {
+    agentRoles: readonly RoleView[];
+    agentRoleNotices: readonly RoleNoticeView[];
+    readonly skills: readonly SkillView[];
+    readonly mcpServers: readonly McpView[];
+    /**
+     * 一个技能的正文，**不动统计**（方案 56 §1.2）。没有这个技能 / 技能系统
+     * 没起来时是 `null` —— 两者对这一层是同一件事：没有正文可发。
+     */
+    skillBody(name: string): string | null;
+    /**
+     * 从**本机目录**导入技能（方案 42 §六）。**进程级**，同 {@link mcp}。
+     *
+     * ⚠️ 它收的是**路径**不是字节 —— 那是这条路上的安全性质本体，判据全文在
+     * [skill-import.ts](./skill-import.js) 的文件头。
+     */
+    readonly skillImport: SkillImportControlView;
+    /**
+     * MCP 的写口：重连一台（方案 56 §1.1）+ 加一台（2026-08-18）+ **那份文件的原文
+     * 读写与应用**（2026-08-18）。**全都是进程级**。
+     *
+     * 镜像跟着各自的 handler 走：前两个在 [mcp.ts](./mcp.ts)，后三个在
+     * [mcp-config.ts](./mcp-config.ts)（两个文件头各有全部判据）—— 这一格只是把
+     * 它们挂进 `RuntimeCapabilities`，因为**装配那一行是在这儿对形状的**。
+     *
+     * ## ⚠️ 为什么是交集，不是一份镜像
+     *
+     * 五个方法挂在**同一个** runtime 对象上（`runtime.mcp`），形状上它们本来就是一个
+     * 交集。分成两份声明是为了让**镜像跟着 handler 走**（判据同 `mcp.ts` 当初从这个
+     * 文件里搬出去那次：刀口按题目下）—— 改那三条端点的人要读的判据全在那一个文件
+     * 里，不用先在这儿绕一圈。
+     *
+     * ⚠️ 那三条端点各有一道**回环绑定**的闸门（`ctx.lanExposed` 为真就 403，
+     * **连读都挡**），而它**不在这份镜像上** —— 镜像答的是「runtime 借得到什么」，
+     * 闸门答的是「这一发准不准发」。判据同下面 `roleWrite` 那一格。
+     */
+    readonly mcp: McpControlView & McpConfigControlView;
+    /**
+     * 身份那一栏的写口：建一个（2026-08-18）。**进程级**，同上面那两条。
+     *
+     * 镜像和 handler 一起住在 [role-add.ts](./role-add.ts)（那边的文件头有全部
+     * 判据）—— 这一格只是把它挂进 `RuntimeCapabilities`，因为**装配那一行是在
+     * 这儿对形状的**（同 `mcp` 那一条）。
+     *
+     * ⚠️ 那条端点有一道**回环绑定**的闸门（`ctx.lanExposed` 为真就 403），
+     * 而它**不在这份镜像上** —— 镜像答的是「runtime 借得到什么」，闸门答的是
+     * 「这一发准不准发」。判据全文在 protocol 的 `wire-agent-role.ts` 文件头。
+     */
+    readonly roleWrite: RoleWriteControlView;
+}
+/**
+ * 三栏一次取齐。
+ *
+ * @param bound 这个会话绑的工作区（`workspaces.of(sessionId)`）。没绑就是 null，
+ *   那时「项目」那一层整个不存在 —— 不是「有但是空的」
+ */
+declare function collectCapabilities(runtime: RuntimeCapabilities, tools: readonly {
+    name: string;
+    source: string;
+}[], bound: {
+    workspace: {
+        root: string;
+    };
+    trust: {
+        trusted: boolean;
+    };
+} | null): WireCapabilitiesResponse;
+/**
+ * 一份 `SKILL.md` 最多发多少字节。形状照
+ * [workspace/diff.ts](./workspace/diff.ts) 的 `MAX_DIFF_BYTES`。
+ *
+ * ## 为什么必须有一个数
+ *
+ * `SKILL.md` 没有天然上界 —— 它是一个用户（或者一个 `git clone` 下来的仓库、
+ * 一个装进来的插件）自己写的文件。没有上限的话，一次点击就能让服务端把一份
+ * 任意大的文件读进内存、序列化成 JSON、再塞进一个 `<pre>`。
+ *
+ * ## 为什么这个数在**这一层**而不是 core
+ *
+ * 「多大算太大」是一个**展示决定**，不是引擎的事实：`skill_view` 那条路
+ * （模型读正文）一个字节都不该被截，它读多少是上下文预算的问题。
+ * `MAX_DIFF_BYTES` 住在 server 而不是 git 那一层，是同一条判据。
+ *
+ * 256KiB 比 diff 那个数小一半：diff 是「一个文件的两侧」，而这是一份人写的
+ * 说明文档 —— 到这个量级它早就不是「点开看一眼」能读的东西了。
+ */
+declare const MAX_SKILL_BODY_BYTES: number;
+/**
+ * 正文 → 载荷。**截断是要说出来的**（验收第 8 条），不静默。
+ *
+ * 按**字节**截而不是按字符：上限守的是网线和内存，而一个中文字符在 UTF-8 里
+ * 是三个字节 —— 按 `length` 截的话，一份全中文的 SKILL.md 实际能发出三倍。
+ *
+ * ⚠️ 截口用 `Buffer.toString()` 而不是自己找边界：多字节字符被切成两半时，
+ * Node 会把残缺的那几个字节还原成 `U+FFFD`，而**不会**吐出一段非法 UTF-8。
+ * 自己按字符倒退着找边界也行，但那是给一处「显示成一个问号」的问题写一段
+ * 会算错的代码。
+ *
+ * ⚠️ **但那个 `U+FFFD` 自己占 3 个字节，比它替掉的那 1–2 个残字节更长** ——
+ * 于是 `subarray(0, N).toString()` 的产物重新编码回去可能是 `N + 2`，
+ * 而那时这个「上限」就不是上限了。多减一个字符是**必须的一步**，不是保险：
+ * 一份全中文的 SKILL.md 每次都会走到这一支（用例里断的就是它）。
+ */
+declare function toWireSkillBody(name: string, body: string): WireSkillBodyResponse;
+
+/**
+ * Hub 和登记表共用的两个契约。
+ *
+ * 单独一个文件是为了**断开循环依赖**：`hub.ts` 用 `SessionRegistry`，而登记表里
+ * 每一格装的是一个 `HubSession` —— 两个类型互相引用的话
+ * `import/no-cycle`（oxlint 里是 error）当场红。放在依赖链的底下，两边都只往下引。
+ *
+ * `hub.ts` 把它们原样再导出一次，所以包的公共 API 形状一个字都没变。
+ */
+
+/**
+ * Hub 需要会话提供的能力 —— `runtime` 的 `AgentSession` 结构上就满足它。
+ *
+ * 刻意收窄成两个成员而不是直接吃 `AgentSession`：用例要喂一个**脚本化的假 agent**
+ * 去对着 `fixtures/wire/*.json` 断言信封序列（§9.5 的交接锚点），而真 AgentSession
+ * 背后拖着 provider、SQLite 和一整个 AgentLoop。
+ */
+interface HubSession {
+    readonly sessionId: string;
+    run(message: EpochUserContent, opts?: {
+        signal?: {
+            readonly aborted: boolean;
+        };
+    }): AsyncGenerator<AgentEvent>;
+}
+/** SSE 连接从 Hub 收帧的出口 */
+type FrameSink = (frame: WireEnvelope) => void;
+/**
+ * 给**这一轮**的事件流套一层的包装（方案 23 的 web 那一半）。
+ *
+ * 自定义斜杠命令的 `allowed-tools` / `model:` 都只管一轮，而进出必须成对 ——
+ * 那两个包装（`withToolScope` / `withModelScope`）住在 runtime，规矩和会红的用例
+ * 都在那边。Hub **不认识命令这个概念**：它只知道「这一轮的流要先过一遍这个函数」。
+ *
+ * ## 为什么是一个闭包，而不是让 Hub 收 `{allowedTools, model}`
+ *
+ * 收字段的话 Hub 就得自己去 import `commands.ts` 里的收窄逻辑，而 `commands.ts`
+ * 要用 `ApiContext`（在 `context.ts`）、`context.ts` 又要 import 本文件旁边的
+ * `hub.ts` —— 那是一个环，`import/no-cycle` 在 oxlint 里是 error。
+ * 收闭包之后依赖方向是单向的：`api → commands → (protocol, runtime)`，
+ * 而 Hub 只多认识一个函数类型。
+ *
+ * ⚠️ **它在轮次真正开始时才被调用**，不是在收下消息那一刻 —— 排队的消息可能等上
+ * 几分钟。这一点是安全的：`withToolScope` 是异步生成器，第一次 `next()` 之前一行
+ * 都不执行，所以它读到的仍然是进入作用域之后的工具表（runtime 那边写着同一句）。
+ */
+type TurnDecorator = (stream: AsyncGenerator<AgentEvent>) => AsyncIterable<AgentEvent>;
+/**
+ * 排队里的一条消息 —— 正文 + 它那一轮的包装。
+ *
+ * 两者必须**一起排队**：包装描述的是「这条消息该在什么工具表 / 什么模型下跑」，
+ * 只排正文的话，一条 `/review`（带 `allowed-tools`）排在别人后面之后，
+ * 轮到它时会跑在一张没收窄的工具表上，而屏幕上没有任何迹象。
+ */
+interface QueuedMessage {
+    message: EpochUserContent;
+    /** 不是命令（绝大多数消息）时缺席 —— 零开销直通，不套任何一层 */
+    decorate?: TurnDecorator;
+}
+
+/**
+ * 自定义斜杠命令的取数、判定与展开 —— `GET /api/sessions/:id/commands` 那张表，
+ * 加上 `POST /api/sessions/:id/messages` 上那一步「这条输入是不是 `/xxx`」。
+ *
+ * 不在 [api.ts](./api.ts) 里，理由和 [capability.ts](./capability.ts) 一样：那个
+ * 文件是「一个端点一个函数」，而这里有一份 runtime 能力的**结构镜像**、一个
+ * 输入解析器、和一段把两个作用域包装接上去的接线 —— 塞进去会让它变成
+ * 「一个端点一个函数，外加一百行别的」。
+ *
+ * ## 结构镜像，不是 import
+ *
+ * `@epoch-agent/server` 依赖得到 `@epoch-agent/runtime`（`ALLOWED` 表里有），
+ * 所以这里**本来可以**直接 import `CommandControl` / `ModelControl`。仍然写镜像，
+ * 判据和 `capability.ts` / `security.ts` 那两处逐字相同：
+ *
+ * - **只借用得到的那几格。** `ModelControl` 上还有 `get` / `set` / `reset` /
+ *   `drainNotices` 四个动词，本文件一个都不该碰 —— 借过来就是给下一个人一个
+ *   「原来这条路上能换模型」的暗示，而 web 上刻意没有那个入口
+ *   （`web/README.md`「界面上没有的东西」）
+ * - **用例喂一个十几行的假对象就能跑**，不用起一个真 runtime（那要 provider、
+ *   SQLite 和 MCP 子进程）。这一节的核心用例是「中途 abort 之后工具表还全不全」，
+ *   它必须能在毫秒级反复跑
+ *
+ * 镜像和真身**结构上必须相等**：`EpochRuntime` 正好满足 {@link RuntimeCommands}，
+ * 对不上就是镜像漏了一块，`createWebServer({ runtime })` 那一行当场编译不过。
+ * 而下面 {@link scopeTurn} 反过来把镜像传给 runtime 的 `withToolScope` ——
+ * 于是这份镜像的两个方向都被编译器钉住了。
+ *
+ * ## 展开为什么只能在服务端做
+ *
+ * 插值要引号感知（`/foo "a b" c` 的 `$1` 是 `a b`），那个 tokenizer 住在
+ * `@epoch-agent/infra`；`utility` 关键字和 `<provider>/<model>` 的切法在 core。
+ * `@epoch-agent/web` 只许依赖 protocol + view（`check-layers.mjs` 是硬闸门），
+ * 两样都够不着。在浏览器里手写第二个「差不多的」切词器，后果是同一条命令在
+ * TUI 和 web 里断句不一样 —— 而那种分歧只会在用户抱怨「同一条命令在两边结果不同」
+ * 的时候才被发现。
+ */
+
+/**
+ * `CommandControl`（runtime）在服务端眼里的样子。
+ *
+ * 三样一个不多：`list` 画补全面板、`expand` 做插值、`scope` 收窄这一轮的工具表。
+ * 一行文件 I/O 都不在这一侧 —— 加载、同名冲突、工作区信任闸门全在引擎里。
+ */
+interface CommandsView {
+    /** 加载好的命令表，已按名字排序、同名冲突已解决 */
+    readonly list: readonly CustomCommandDef[];
+    /**
+     * 展开成一次 turn 的输入。**命令名不认识时返回 `undefined`** ——
+     * 那时这行输入按普通消息原样发给模型，不是报错（见 {@link expandUserContent}）。
+     */
+    expand: (name: string, args: string) => ExpandedCommand | undefined;
+    /** 收窄这一轮的工具表，返回还原函数。`allow` 不给就是不收窄 */
+    scope: (allow: readonly string[] | undefined) => () => void;
+}
+/**
+ * `ModelControl` 里 {@link scopeTurn} 用得到的**那一格**。
+ *
+ * 只有 `enterTurn`：它的语义是「只换这一轮，`restore` 无条件还原」，
+ * 而这正是命令 frontmatter 的 `model:` 要的东西。`set` / `reset` 刻意不借 ——
+ * 见文件头。
+ *
+ * 返回值里的 `result` 这一侧一个字都不读，但形状必须写全：少写它，
+ * 这个镜像就不能再传给 runtime 的 `withModelScope`（函数返回值是协变的）。
+ */
+interface ModelTurnsView {
+    enterTurn: (ref: ModelRef) => {
+        result: SetSelectionResult;
+        restore: () => void;
+    };
+}
+/**
+ * `RoleControl` 里 {@link scopeTurn} 用得到的**那一格**（方案 57 §3.4）。
+ *
+ * 只有 `enterTurn`，判据逐字同上面那个 `ModelTurnsView`：`has()` 是**收下消息
+ * 那一刻**才用得到的（`postMessage()` 据此回 400），而这个文件只管「这一轮怎么跑」。
+ * 借过来就是给下一个人一个「原来这条路上也能判专家名」的暗示，而在这条路上
+ * 判已经太晚了 —— 排队的消息可能等上几分钟。
+ *
+ * 收**名字**不收角色对象：`@epoch-agent/server` 不许 import `@epoch-agent/core`，
+ * 名字 → `AgentRole` 的解析归 runtime 一处（`createRoleControl`）。
+ */
+interface RoleTurnsView {
+    enterTurn: (name: string) => () => void;
+}
+/**
+ * 「这一条消息挑了哪个专家」—— 名字 + 它那个会话的控制口（方案 57 §3.4）。
+ *
+ * 一个对象而不是两个参数：这两样**必须来自同一个会话**（控制口是
+ * `sessionFactory.get(sessionId)?.roles`，名字是那一次请求体里的），
+ * 拆成两个参数的话调用方可以只给其中一个，而那时收窄会打在别的会话身上。
+ *
+ * 整个给 `null` = **这一条没挑专家**，那时 {@link scopeTurn} 对角色那一层是
+ * 零开销直通 —— 这个会话跑在它自己的默认角色上，槽里本来就是那一个。
+ */
+interface TurnRole {
+    control: RoleTurnsView;
+    /** 已经过 `has()` 校验的角色名 —— 认不出来的在 `postMessage()` 就 400 了 */
+    name: string;
+}
+/** server 从 runtime 借的「斜杠命令」那一片。`WebRuntimeView` 继承它 */
+interface RuntimeCommands {
+    /**
+     * 命令表 + 展开 + 收窄。**不可为 null** —— 加载失败、目录不存在、工作区不受信任，
+     * 得到的都是一张空表加若干条诊断，不是「这个能力没有」（`EpochRuntime.commands`
+     * 上写着同一句）。所以这一侧不用为「有没有命令系统」分支。
+     */
+    commands: CommandsView;
+}
+/**
+ * 一条命令 → 补全面板那一行。
+ *
+ * ⚠️ **`prompt` 不进这个投影**，判据在 `WireCustomCommand` 的 JSDoc 上：
+ * 那是用户自己写的工作指令原文，隐私和体积两头都不该下发，而面板一个字都用不上。
+ * 少发它是编译期生效的 —— `WireCustomCommand` 上没有这个字段，写了当场不过。
+ *
+ * `allowedTools` / `model` / `source` / `filePath` 同样不发，理由弱一些但同向：
+ * 面板上没有它们的位置，而「这条命令会收窄工具表」是**展开之后**才该说的事
+ * （那时说的是「这一轮」，而不是「这条命令平时」）。
+ */
+declare function toWireCommand(def: CustomCommandDef): WireCustomCommand;
+/** {@link expandUserContent} 的结果 */
+interface ExpansionOutcome {
+    /** 真正发给引擎的那条消息。不是命令时 === 传进来的那条 */
+    message: EpochUserContent;
+    /**
+     * 这一轮的作用域包装。三样都不要（不是命令 / 命令既没收窄也没换模型 /
+     * 这一条也没挑专家）时缺席 —— 零开销直通。
+     *
+     * ⚠️ **它不再只为命令而存在**（方案 57 §3.4）：一条普通消息带着一枚 chip
+     * 同样要包一层，那时下面三层里只有角色那一层真的进出。
+     */
+    decorate?: TurnDecorator;
+    /** 回给发送方的那句话（命令名 + 警告）。不是命令时缺席 */
+    notice?: WireCommandExpansion;
+}
+/**
+ * 「这条输入是不是一条自定义斜杠命令」—— 是就展开，不是就原样放行。
+ *
+ * ## 认不出来的命令名**照原样发给模型**，不是报错
+ *
+ * `CommandControl.expand` 返回 `undefined` 就是这一档，那条规矩写在 runtime 那侧的
+ * 注释里。回 400 的代价：用户问「/etc/hosts 是什么」会收到一句「未知命令」，
+ * 而他要的只是一句回答。判错的方向必须偏向「当普通文本」。
+ *
+ * ## 带附件的那一支也走这条路
+ *
+ * 输入可以是字符串，也可以是 `EpochContentPart[]`（粘了图片时）。后者**只看第一个
+ * 部件**，而且只在它是文本时才试着展开 —— 输入框拼数组时文本永远在最前面
+ * （`composer/index.tsx` 的 `submit`）。不处理数组那一支的后果不是报错，是**静默
+ * 走样**：打了 `/review` 又顺手贴了张截图，命令就悄悄没生效了，而屏幕上没有
+ * 任何区别。
+ *
+ * ## ⚠️ 逐条专家走的是同一条路，所以「不是命令」不再等于「不用包」
+ *
+ * `role` 给了（这一条挑了专家，方案 57 §3.4）时，**一条普通消息也要拿到
+ * `decorate`** —— 那正是 2026-08-17 之前这个函数唯一的形状变化。漏掉的表现是
+ * chip 对普通消息完全无效、只有敲了 `/xxx` 才生效，而屏幕上没有任何区别。
+ *
+ * @param role 这一条挑的专家，没挑就给 `null`。**名字必须已经过 `has()` 校验** ——
+ *   认不出来那一档在 `postMessage()` 就 400 了，这条路上没有回话的地方
+ */
+declare function expandUserContent(runtime: RuntimeCommands, message: EpochUserContent, model: ModelTurnsView | null, role: TurnRole | null): ExpansionOutcome;
+
+/**
+ * SessionHub —— 事件总线 + 回合状态机 + 审批生命周期。
+ *
+ * [方案 20 §4.1 / §4.2 / §4.3](../../../docs/verify/VERIFY_RECORD-20-web.md) 三块在
+ * **同一个类**里（§9.6 第 1 条明写了不要拆）：它们共享同一份状态 ——
+ * 状态机的迁移由事件流驱动、审批的挂起数又是状态机的输入、而三者都要往同一个
+ * 全局游标上发帧。拆成三个文件只会让每一次迁移都跨文件读一遍。
+ *
+ * ## 唯一写者
+ *
+ * 今天 `AgentSession.run()` 是**单消费者** async generator：一个 for-await 吃掉
+ * 所有事件。浏览器要的是「N 个标签页看同一个会话 + 刷新之后接着看」，所以这里
+ * 由 Hub 独占那个 for-await，再扇出给每一条 SSE 连接和环形缓冲。
+ *
+ * ```
+ * AgentSession.run() ─► serializeStream(relay) ─► SessionHub（唯一写者）
+ *                                                     │
+ *                              ┌──────────────────────┼──────────────────┐
+ *                          SSE 客户端 A           SSE 客户端 B        环形缓冲
+ * ```
+ *
+ * 方案 54 §三之后多一条同进程的支流（`observe()`）：它**只挂在广播上**，
+ * 不进上面那个「连接」的概念里 —— 理由见下面第 5 条。
+ *
+ * ## 五条不许改回去的规矩
+ *
+ * 1. **`seq` 是全局单调计数器**，不是 per-session（理由见 wire.ts 的长注释）。
+ * 2. **连接级帧（`connected` / `stream-reset`）`seq: 0`**，只发给刚接上来的那一个
+ *    连接、不进缓冲、不写 SSE 的 `id:` 行。占了广播序号就意味着「有人开了个新
+ *    标签页」会把别人的续传游标推走。
+ * 3. **断连不是拒绝。** 任何情况下都不许逐个 `relay.respond(id, 'deny')` ——
+ *    模型收到一串「用户拒绝」会认为这是有意否决，然后换个方式再试一遍
+ *    （`runtime/src/serialize.ts` 的类注释把这条写死了）。要放弃就 `abandon()`
+ *    整轮 + `abort()`。
+ * 4. **一个会话同一时刻只有一个 `run()`**（方案 30 §2.3）。同一会话的第二条消息
+ *    **排队**而不是并发；不同会话之间**可以**并行 —— 那正是多会话的意义。
+ *    理由与「谁在表里、谁排在后面」的实现都在 [sessions/registry.ts](./sessions/registry.ts)。
+ * 5. **旁听者（`observe()`）不许进 `sinks`**（方案 54 §三）。`sinks.size` 是用来回答
+ *    「**人**还在不在」的那个计数器，全仓有四处判它：`connectionCount`、
+ *    `armGrace()` 的触发、`drainQueue()`、`reap()`。宿主为了在自己的窗口上点亮一枚
+ *    状态灯会常驻一条旁听 —— 那要是算一条连接，「全断 30 秒放弃挂起的审批 + 中止
+ *    回合」和「全断了丢掉排队的消息」就一起失效了，**而宿主没有任何办法知道**。
+ *    加集合、不加计数：新东西进不了那个计数器。
+ */
+
+interface SessionHubOptions {
+    /** 环形缓冲容量，默认 512 */
+    ringCapacity?: number;
+    /**
+     * **所有**连接都断开之后，等多久才 `abandon()` + `abort()`。默认 30 秒。
+     *
+     * 不是 0：浏览器刷新是常态，按一下 F5 就把跑了三分钟的任务杀掉是
+     * [EMBEDDING.md 那套 Electron 规矩](../../../docs/EMBEDDING.md)照抄到 web 上的
+     * 后果。也不是 ∞：标签页真关了之后没人会来收尾，审批会永远挂着。
+     */
+    idleGraceMs?: number;
+    /**
+     * 时钟。默认 `Date.now`。
+     *
+     * 注入它是为了让 fixture 用例能断言信封**逐条等于** JSON（含 `ts`）。
+     * 不变量：**每产出一个信封恰好调用一次** —— 用例的脚本化时钟就靠这条对齐。
+     *
+     * ⚠️ 方案 30 之后它多了一个消费者：会话登记表拿它记 `lastActiveAt`（LRU 冷却
+     * 的判据）。那几次读**不产出信封**，所以上面那条不变量的说法要收窄成
+     * 「每产出一个信封恰好读一次」——`scriptedClock` 的用例因此只在
+     * `maxActive` 没被触碰的场景里逐格对齐。
+     */
+    clock?: () => number;
+    /** 同时活跃的会话数上限，缺省 8（方案 30 §2.3） */
+    maxActiveSessions?: number;
+    /** 单个会话最多排几条消息，缺省 8 */
+    maxQueuedMessages?: number;
+    /**
+     * 一个会话被**冷却**掉时叫一声（方案 30 §6.3 的多会话工厂落地之后才真会触发）。
+     *
+     * Hub 这一侧的冷却只是「从这张表里摘掉」——它管不到那个会话在**引擎**里占的
+     * 东西（对话历史、它那个 `AgentLoop`、它的审批桥）。而释放那批内存正是冷却
+     * 的全部意义：不给这个回调的话，`maxActiveSessions` 只挡住了 Hub 的表变长，
+     * 一个人开 50 个标签页照样能把内存吃光 —— 也就是 §2.3 那条上限白设了。
+     *
+     * 是**回调不是返回值**：`register()` 的调用方（`POST /api/sessions`）关心的是
+     * 「我这一个建出来没有」，而被挤走的是**另一个**会话。让它顺手去处理别人的
+     * 后事，等于把一条不变量的执行摊到每个调用点上，漏一处就是一次静默泄漏。
+     */
+    onCooled?: (sessionId: string) => void;
+}
+/**
+ * `start()` 的结果。
+ *
+ * `busy` 在方案 30 之后**不再是「同一个会话再发一条」的出口** —— 那条现在排队
+ * （`ok: true, queued: true`）。它只剩下「排满了」这一种，所以带上 `reason`
+ * 让调用方能说清楚是哪一种拒绝。
+ */
+type StartResult = 
+/** 收下了。`queued` = 排在当前这一轮后面，还没开始跑 */
+{
+    ok: true;
+    queued: boolean;
+} | {
+    ok: false;
+    reason: 'unknown-session';
+}
+/** 会话被冷却了（活跃数超上限），要宿主重新 `register()` 才能再跑 */
+ | {
+    ok: false;
+    reason: 'cooled';
+}
+/** 队列满了。`state` 是当前这一轮的状态，调用方回 409 时带上它 */
+ | {
+    ok: false;
+    reason: 'queue-full';
+    state: WireTurnState;
+};
+/** 一个会话在 Hub 侧的实时状态。DB 那半（标题 / 成本 / 消息数）不在这里 */
+interface HubSessionState {
+    id: string;
+    state: WireTurnState;
+    /** 挂起的审批数。别的会话卡在审批上时，列表要看得见（方案 30 §2.5） */
+    pendingApprovals: number;
+    /** 挂起的提问数，理由同上 */
+    pendingQuestions: number;
+    /**
+     * 这个会话**从什么时候起被拦住**；一条挂起的都没有时 null。
+     *
+     * 上面两个数答「有几条」，这一格答「等了多久」。**两张表合成一格**在这一层
+     * 完成（`earlierOf`），不是往上送两个字段 —— 判据在
+     * `WireSessionSummary.pendingSince` 上，一句话是「合错（取晚的那个）会让一个
+     * 卡了两小时的会话报『已等 3 秒』，而那个判断不该摊到每个读它的人身上」。
+     */
+    pendingSince: number | null;
+    /** 排队等着开的消息数 */
+    queued: number;
+    /** 本轮开跑的时刻；没在跑时 null。见 `WireSessionSummary.turnStartedAt` */
+    turnStartedAt: number | null;
+    /** 上一轮的终局；还没跑过时 null。见 `WireSessionSummary.lastFinish` */
+    lastFinish: WireSessionFinish | null;
+}
+declare class SessionHub {
+    private readonly ring;
+    private readonly idleGraceMs;
+    private readonly clock;
+    /** 见 {@link SessionHubOptions.onCooled} */
+    private readonly onCooled;
+    private readonly registry;
+    private readonly sinks;
+    /**
+     * 同进程旁听者（方案 54 §三）。**故意是第二个集合，而不是 `sinks` 上的一个标记位。**
+     *
+     * 标记位那种写法要求每一处 `sinks.size` 都改成「数一下里面有几个不是标记的」，
+     * 而那四处判定里有两处（`reap()` / `drainQueue()`）的错法是**静默的**：
+     * 挂起的审批永远不被放弃、没人看着的时候凭空开始跑一条排队的消息。
+     * 两个集合的写法让那四处一个字都不用改。
+     */
+    private readonly observers;
+    /** requestId → sessionId。`POST /api/approvals/:requestId` 上没有会话 id */
+    private readonly requestOwner;
+    /** 全局广播游标。0 是保留值（连接级帧），所以广播帧从 1 开始 */
+    private seq;
+    private graceTimer;
+    private closed;
+    constructor(opts?: SessionHubOptions);
+    /**
+     * 把一个会话交给 Hub 管。重复注册同一个 id 是空操作。
+     *
+     * 活跃会话超过上限时，最久没动过的**空闲**会话会被顺带冷却掉 ——
+     * 它从此不在 Hub 里，但**仍然在会话列表里**（列表的另一半来自 DB），
+     * 重新打开时历史走 `GET /api/sessions/:id/messages` 回放。
+     */
+    register(session: HubSession): void;
+    has(sessionId: string): boolean;
+    /** 这个 id 是被冷却掉的（而不是从来没存在过）吗 */
+    isCooled(sessionId: string): boolean;
+    /** 不认识的会话按 idle 报 —— 调用方要区分的话先问 `has()` */
+    stateOf(sessionId: string): WireTurnState;
+    /** Hub 手里这些会话此刻的样子。Map 的插入序 = 注册序 */
+    listSessions(): HubSessionState[];
+    /**
+     * 把一个会话从 Hub 里摘掉（`DELETE /api/sessions/:id`）。
+     *
+     * 收尾按 §4.3 那套：**放弃**挂起的请求（不是逐个 deny）+ 中止在跑的回合 +
+     * 丢掉排队的消息。删掉的会话不进冷却名单 —— 它是真没了，不是被挤走。
+     *
+     * @returns Hub 里本来有没有它
+     */
+    unregister(sessionId: string): boolean;
+    /** 当前活着的 SSE 连接数。给 `/api/config` 和用例看 */
+    get connectionCount(): number;
+    /**
+     * 接一条 SSE 连接。
+     *
+     * 同步完成三件事，顺序不能换：先 `connected`（把响应头刷出去、证明流通了），
+     * 再按 `Last-Event-ID` 补发或回 `stream-reset`，最后才登记进扇出集合 ——
+     * 反过来的话补发和实时帧会交织，页面上就是一段乱序的对话。
+     *
+     * @param lastEventId 客户端带上来的断点。省略 = 全新的流（历史归 GET /messages）
+     * @returns 取消订阅。**幂等**，连接关闭和服务 close 会各调一次
+     */
+    subscribe(sink: FrameSink, lastEventId?: number): () => void;
+    /**
+     * 同进程旁听广播（方案 54 §三）。**不是一条连接。**
+     *
+     * 和 `subscribe()` 的差别不是「少发一帧」，是它整条不进那套连接语义：
+     *
+     * - **不进 `sinks`**：不计入 `connectionCount`，不影响 idle-grace 的收摊
+     *   （`armGrace()` → `reap()`），也不影响 `drainQueue()` 的「全断了就丢队列」。
+     *   那三处判的是「**人**还在不在」，而旁听者是宿主的代码，不是一双眼睛
+     * - **不发 `connected`、不认 `Last-Event-ID`、不从环形缓冲补帧**：补帧机制存在的
+     *   理由是网线断过一段，而同进程的函数调用不会丢帧。真要历史就走
+     *   `GET /api/sessions/:id/messages`，和浏览器同一条路
+     *
+     * 收到的是**和 SSE 上同一个信封对象**（同一个 `seq`），所以「宿主看到的和浏览器
+     * 看到的是同一条流」不需要额外的对齐机制。四种状态怎么映射到宿主界面上的一枚灯，
+     * 那是宿主的产品决定，不在这里做。
+     *
+     * @returns 取消旁听。**幂等** —— 多调几次不会误删后来注册的同一个函数
+     */
+    observe(sink: FrameSink): () => void;
+    /**
+     * 发一条消息。会话空闲就立刻开一轮，否则**排队**（方案 30 §2.3 第 4 条）。
+     *
+     * 排队而不是并发：`AgentSession` 的历史累积发生在 `run()` 的末尾，两轮并发跑
+     * 会让历史顺序变成不确定的 —— 那不是「偶尔乱序」，是每次重开会话看到的对话
+     * 都可能不一样。**不同会话之间不受这条限制**，它们各跑各的。
+     *
+     * 这是对方案 20 验收第 7 条（「running 时第二个 POST 直接 409」）的**有意
+     * 修改**：那时只有一个会话，409 是唯一能给的答复；现在排队和「不交织」
+     * 这个不变量并不冲突，而 409 会逼每个客户端自己实现一遍重试。
+     *
+     * @param decorate 给这一轮的事件流套一层（见 {@link TurnDecorator}）。
+     *   自定义斜杠命令的工具收窄和临时模型走的就是它 —— Hub 自己不认识命令这个概念，
+     *   只负责把这个函数**跟着消息一路带到轮次真正开始的那一刻**（排队也带着）。
+     */
+    start(sessionId: string, message: EpochUserContent, decorate?: TurnDecorator): StartResult;
+    /**
+     * 中止本轮，并**丢掉排在后面的消息**。
+     *
+     * 排队的一起丢是刻意的：用户按下「停」要的是「现在别干了」，而不是
+     * 「停掉这一轮然后立刻开始下一轮」—— 后者的表现是按了停之后 agent 又动起来了。
+     *
+     * @returns 是否真有一轮在跑（**只看这个**，丢掉的队列不算）。
+     *          `false` 表示这一轮本来就没在跑，不是失败
+     */
+    abort(sessionId: string): boolean;
+    /** 补拉挂起的审批 —— 新连上来的页面靠它把弹层恢复出来（§4.3） */
+    listPending(sessionId: string): SerializableApprovalRequest[];
+    /** 补拉挂起的提问（方案 34 验收 9）。与 `listPending` 同构 */
+    listPendingQuestions(sessionId: string): SerializableQuestionRequest[];
+    /**
+     * 答复一个审批。
+     *
+     * @returns `false` = 这个 requestId 不认识（重复答复 / 上一轮的 ID / 已被放弃）。
+     *          调用方该回 404 而不是 500：用户在两个标签页上各点一下就会走到这里。
+     */
+    respondApproval(requestId: string, outcome: ApprovalOutcome, note?: string): boolean;
+    /**
+     * 答复一个提问（方案 34）。
+     *
+     * **另一个方法而不是给 `respondApproval` 加个联合入参**：两者的载荷没有交集，
+     * 合成一个之后路由层要先猜「这个 requestId 是审批还是提问」，
+     * 而猜错的表现是一个拼错的答案被判成合法的 `deny`。
+     *
+     * @returns `false` = 这个 requestId 不认识（重复答复 / 上一轮的 / 已被放弃）。
+     *          调用方回 404，同审批。
+     */
+    respondQuestion(requestId: string, answer: QuestionAnswer): boolean;
+    /**
+     * 收摊：撤掉倒计时、放弃所有挂起的审批、中止所有在跑的回合。
+     *
+     * 进程收到 SIGINT 时立即调它（§4.3 最后一行），之后宿主再 `dispose()`。
+     * 幂等。
+     */
+    shutdown(): void;
+    /**
+     * 广播一帧：占一个全局序号、进环形缓冲、扇出给所有连接和旁听者。
+     *
+     * **回传发出去的那个信封**（调用方绝大多数不看）。这是「一轮跑了多久」
+     * 唯一合法的取数口：`clock` 上钉着「每产出一个信封恰好读一次」的不变量
+     * （见 `sessions/registry.ts` 的 `lastActiveTick`），想知道某一帧的时刻
+     * 只能从那一帧上拿，**不许再读一次挂钟**。
+     */
+    private publish;
+    /** 连接级帧：`seq: 0`、没有 `sessionId`、不进缓冲、不写 SSE 的 `id:` */
+    private connectionFrame;
+    /**
+     * 状态迁移。**只在真的变了的时候发帧** —— 否则并行审批会刷出一串重复状态。
+     *
+     * 回传那一帧的时刻（没发帧时 undefined），给 {@link beginTurn} 记回合起点用。
+     */
+    private setState;
+    /**
+     * 按「还挂着几条请求」把状态摆正。
+     *
+     * 只在回合真的在跑的时候动（`controller !== null`）：回合已经收尾之后
+     * 状态该是 idle，这里不能把它拽回 running。
+     *
+     * **审批优先于提问**：两者同时挂着时报 `awaiting-approval`。理由是界面上
+     * 审批层压在提问层上面（它是安全边界，不该被一个选择题挡住），
+     * 而状态栏那句话得和用户眼前看到的那个框对上。
+     */
+    private syncApprovalState;
+    /**
+     * 开一轮：换一副新的登记表、拉起中止闸、广播状态、然后驱动。
+     *
+     * 状态帧必须在 `start()` 返回前就广播出去：POST 拿到 202 之后前端立刻可能
+     * 再问一次状态，而第二个标签页只靠这一帧才知道「现在正在跑」。
+     */
+    private beginTurn;
+    /**
+     * 独占那个 for-await，把事件扇出去。
+     *
+     * `serializeStream` 负责把 `approval-request` 里的闭包摘成 `requestId` 并登记
+     * 进 relay —— 这一段是 runtime 现成的，不在这里重写一遍。
+     *
+     * ## `decorate` 套在**最里面**，紧贴 `run()`
+     *
+     * 顺序不能换：那一层管的是「这一轮引擎能看见哪些工具、用哪个模型」，
+     * 而 `serializeStream` 只是把事件里的闭包摘掉 —— 套反了的话，收窄会在
+     * 序列化那一层进出，而真正跑工具的 `run()` 在它外面，等于整层白做。
+     */
+    private drive;
+    /**
+     * 一轮跑完，把排在后面的那条接上（方案 30 §2.3 第 4 条）。
+     *
+     * 三个前提缺一不可，缺了就是「浏览器早就关了，服务端自己接着聊」：
+     * 会话还在表里（没被删）、Hub 没收摊、且**还有连接活着**。
+     */
+    private drainQueue;
+    private armGrace;
+    private clearGrace;
+    /**
+     * 放弃挂起的审批并中止在跑的回合。
+     *
+     * **`abandon()` 而不是逐个 `deny`**：前者一个 promise 都不 resolve，随后的
+     * `abort()` 让流收尾，引擎侧的 finally 才去兜底 —— 模型看到的是「这一轮被中止
+     * 了」而不是「用户否了我五次」。后者会让模型换个方式再试一遍。
+     */
+    private reap;
+}
+
+/**
+ * 一个会话自己那三样（模型 / 权限档 / plan 模式）在**服务端眼里**的样子
+ * （[方案 30](../../../../docs/verify/VERIFY_RECORD-30-web-multi-session.md) §六，2026-08-16）。
+ *
+ * ## 为什么单开一个文件，而不是挂在 `context.ts` 的 `WebRuntimeView` 上
+ *
+ * 这三样从这一轮起**一个会话一份**，所以它们的落点是
+ * [factory.ts](./factory.ts) 的 `LiveSessionView`，不是那个进程级的视图 ——
+ * 判据逐字同 2026-08-15 那次把 `checkpoints` 从 `WebRuntimeView` 上**删掉**
+ * （不是留着不读）的处置：
+ *
+ * > 留着的话下一个写 handler 的人照样够得着它，而它编译得过、跑得通、
+ * > 只是答错会话 —— 这一整条 bug 就是这么长出来的。
+ *
+ * 镜像声明住在这儿而不是直接写进 `factory.ts`，只有一条理由：
+ * [model.ts](../model.ts) / [permission.ts](../permission.ts) /
+ * [plan-mode.ts](../plan-mode.ts) 三个 handler 都要引它们，而那三个文件
+ * 各自 import 了 `context.ts`（`ApiContext`），`context.ts` 又 import
+ * `factory.ts` —— 把镜像放进 `factory.ts` 就是一个环，
+ * 而 `import/no-cycle` 在 oxlint 里是 error。这个文件**什么都不 import**
+ * （除了 protocol 的类型），所以它在依赖图的最底下。
+ *
+ * ## 同一条老规矩：`@epoch-agent/server` 不许 import `@epoch-agent/core`
+ *
+ * （`check-layers.mjs` 是硬闸门。）所以下面按用得到的字段再声明一遍，
+ * runtime 的 `LiveSession` **结构上**正好满足它们 —— 对不上就是镜像漏了一块，
+ * 装配那一行当场编译不过。收窄之后用例也能喂一个几十行的假对象。
+ *
+ * ## ⚠️ 三份镜像都**刻意漏掉了中文**
+ *
+ * runtime 那边 `SetSelectionResult` 上真有 `reason` / `warnings` 两个中文字段，
+ * `PlanControl.enter()` 回的 `reason` 也是中文。镜像上没有的字段，投影里写不出来 ——
+ * 那就是「中文不上网线」那道闸门本身（判据同 `model.ts` / `security.ts` 的文件头）。
+ */
+
+/** core 的 `ModelSelection` 在服务端眼里的样子 */
+interface SelectionView {
+    /**
+     * 钉成 {@link ProviderType} 而不是 `string`，判据同 `settings.ts` 那处 `layer`：
+     * 引擎那边加一家 provider 而忘了同步时**装配那一行当场编译不过**。
+     * 写成 `string` 的话，那家会一路发到浏览器然后在菜单里显示成一个查不到文案的空白。
+     */
+    provider: ProviderType;
+    model: string;
+    origin: ModelSelectionOrigin;
+}
+/**
+ * core 的 `SetSelectionResult` 的镜像。
+ *
+ * ⚠️ **`reason` 和 `warnings` 两个字段刻意不在这上面**，虽然引擎侧真有 ——
+ * 它们是中文散文（见文件头）。
+ */
+type SetSelectionView = {
+    ok: true;
+    selection: SelectionView;
+    contextLength: number;
+    caveats: readonly WireModelCaveat[];
+} | {
+    ok: false;
+    rejection: WireModelRejection;
+};
+/**
+ * **这个会话**的 `ModelControl` —— 这条路借 `get` / `set` / `reset` 三个动词，
+ * 外加 2026-08-16 合并时收进来的 `enterTurn`。
+ *
+ * `drainNotices` 仍然刻意不借（它是轮末该拉的东西，判据在 [model.ts](../model.ts)
+ * 的文件头）。
+ *
+ * 四样都是函数而不是拍下来的值：换模型这件事的全部意义就是它会变，
+ * 快照等于让这个端点永远回装配时那一份。
+ */
+interface SessionModelView {
+    get(): SelectionView;
+    set(ref: {
+        provider?: ProviderType;
+        model: string;
+    }, ctx: {
+        hasImages?: boolean;
+        usedTokens?: number;
+    }): SetSelectionView;
+    reset(ctx: {
+        hasImages?: boolean;
+        usedTokens?: number;
+    }): SetSelectionView;
+    /**
+     * 只换**这一轮**（自定义斜杠命令 frontmatter 的 `model:`），`restore` 无条件还原。
+     *
+     * ## 为什么它 2026-08-16 才进来，以及进来意味着什么
+     *
+     * `model.ts` 文件头原来那句「`enterTurn` 刻意不借」是这么说的：借它等于
+     * 承认「这条路上有一个和 `run()` 成对的还原动作」，而那句话只有
+     * [commands.ts](../commands.ts) 说得出口。**现在它说了** —— `scopeTurn()`
+     * 那一轮的临时模型从这一格取，不再取引导会话那一份。
+     *
+     * 不收的后果不是少一个功能：`model:` 在第二个会话上**对自己无效**，
+     * 而且**顺带把引导会话的选择换掉一轮**（A 正好在跑就用上了 B 点名的模型）。
+     *
+     * ⚠️ 返回值这一格是**唯一一处**镜像上带 `SetSelectionResult`（也就是带那两个
+     * 中文字段）的地方，而它不违反文件头那道闸：`scopeTurn` 一个字都不读它，
+     * **它一步都不会走上网线**。形状仍然必须写全 —— 少写它，这个镜像就传不给
+     * runtime 的 `withModelScope`（函数返回值协变），判据逐字在
+     * `commands.ts` 的 `ModelTurnsView` 上。
+     */
+    enterTurn(ref: ModelRef): {
+        result: SetSelectionResult;
+        restore: () => void;
+    };
+}
+/**
+ * **这个会话**的角色槽 —— 逐条专家（方案 57 §3.4，2026-08-17）。
+ *
+ * 两个动词，一个不多：`has` 给 `postMessage()` 判 400，`enterTurn` 给
+ * `scopeTurn()` 套那一层。runtime 的 `RoleControl` **结构上正好满足它**。
+ *
+ * ## 为什么和 `SessionModelView.enterTurn` 一样住在这一层，而不是进程级
+ *
+ * 槽是 `assemble()` 里一个会话建一个，和那个会话的 `AgentLoop` 绑死 ——
+ * 判据逐字同这个文件里其余几样：拿引导会话那一份去答别的会话，表现是
+ * 「给 B 挑了专家，换掉的是 A 的身份」，而 B 那边一切正常、只是跑在自己的
+ * 默认角色上。方案 57 §3.4 的草图上写的是 `runtime.roles`（进程级那张**角色表**），
+ * 那是 PR-1 把槽落进 `assemble()` 之前的写法。
+ *
+ * ⚠️ **`enterTurn` 收名字不收对象**：`@epoch-agent/server` 不许 import
+ * `@epoch-agent/core`，`AgentRole` 这个类型它够不着 —— 名字 → 角色的解析归
+ * runtime 一处（`createRoleControl`），这一层只负责把网线上那个字符串递下去。
+ */
+interface SessionRoleView {
+    /**
+     * 这个名字认得吗。
+     *
+     * **和 `enterTurn` 分开**，因为两件事发生在完全不同的两个时刻：判定在收下
+     * 消息那一刻（认不出来就 400，这一条根本不发出去），进作用域要等轮次真正
+     * 开始 —— 排队的消息可能等上几分钟。合成一个动词的话，那句 400 只能等到轮到
+     * 它才说得出口，而那时用户早就以为消息发出去了。
+     */
+    has(name: string): boolean;
+    /** 换上这一条的专家，返回还原函数。⚠️ 调用方必须把还原放进 `finally` */
+    enterTurn(name: string): () => void;
+}
+/**
+ * **这个会话**的权限档 —— `level` / `managed` / `setLevel` 三格，一格不多。
+ *
+ * ⚠️ `rules` / `shadows` / `audit` **刻意不在这上面**：那三样是安全中心那一屏的
+ * 素材、而且是**进程级**的一份（规则表全进程一份、流水全进程一本）。放进来只会
+ * 诱使下一个人把它们也塞进这条端点的载荷 —— 而那时它就成了
+ * `GET /api/sessions/:id/security` 的第二个说法。判据同 `permission.ts` 的文件头。
+ */
+interface SessionPermissionsView {
+    /**
+     * 这个会话此刻那一档。
+     *
+     * ✅ **安全中心那一屏（`GET .../security`）读的就是这一格**（2026-08-17 接上）。
+     *
+     * 在那之前它读的是 `security.ts` 的 `PermissionsView.level()` —— 进程那一份，
+     * 也就是引导会话那一档，于是看着会话 B 时它印的是会话 A 的档位。收的那一笔
+     * 只有一处：`api.ts` 的 `getSecurity()` 多传一个实参。
+     *
+     * ⚠️ **这一层仍然什么都不缺，别在这儿加格子。** 那一屏另外四样
+     * （`rules` / `shadows` / `managed` / `audit`）是**进程级**的，判据在上面那段
+     * 和 core 的 `permission/shared.ts` 里。把它们挪到这个接口上，表现是安全中心
+     * 只剩下这一个会话判过的那几行 —— **一本漏了行的安全流水比没有账更坏，
+     * 因为它看起来是完整的。**
+     */
+    level(): string;
+    /**
+     * 「哪一档改不成」那一格的原料。**只有一个布尔** —— `present` / `rulesOnly` /
+     * `path` 三样归安全中心那一屏，判据在 `permission.ts` 的 `blockedLevels()` 上。
+     */
+    managed(): {
+        bypassDisabled: boolean;
+    };
+    setLevel(level: PermissionLevel): SetLevelView;
+}
+/**
+ * 一次换档的结果。**只有码，没有句子** —— 措辞归浏览器的两份 catalog
+ * （runtime 的 `LevelChangeResult` 逐字同形）。
+ */
+type SetLevelView = {
+    ok: true;
+} | {
+    ok: false;
+    reason: 'managed-bypass-disabled';
+};
+/**
+ * **这个会话**的 plan 模式。
+ *
+ * ⚠️ `forget()` 刻意不借，而理由从 2026-08-15 起就没变过：
+ * 「用户自己设级别 ⇒ plan 模式那段区间作废」是引擎内部两件事的耦合，它住在
+ * runtime 的 `SessionPermissions.setLevel()` 第 3 步。服务端手里同时握着
+ * `setLevel` 和 `forget` 的话，「谁负责作废」立刻有两个答案，而漏调的那一侧
+ * **不会红**：用户在 plan 模式里换完档一切正常，直到下一次计划批准把级别
+ * 悄悄改回进入前那一档。
+ */
+interface SessionPlanView {
+    active(): boolean;
+    from(): string | null;
+    /**
+     * 用户主动进入。已经在里面时回 `{ok:false}` —— `reason` 是给模型看的那句中文，
+     * **这一层不往下发**（见 `WirePlanModeResponse`），所以镜像上只留 `ok`。
+     */
+    enter(): {
+        ok: boolean;
+    };
+    /** 用户主动退出，恢复进入前那一档并回到底恢复成了什么；本来就不在模式里时 null */
+    leave(): string | null;
+    /** 已批准的计划正文；还没有就是 null */
+    approvedPlan(): string | null;
+}
+/**
+ * 「这段会话里出现过图片吗」——只借**读历史**这一件事。
+ *
+ * 收窄到「一串带 `parts` 的东西」而不是把 `AgentSession` 整个借过来：这一层要
+ * 回答的问题只有「有没有 `type: 'image'`」，而 `AgentSession` 上还挂着
+ * `run` / `compact` / `abort` 这些**引擎自己的生命周期**方法。
+ *
+ * ⚠️ 它 2026-08-16 从 `WebRuntimeView.session` 挪到了 `LiveSessionView.session` ——
+ * 判据同这个文件里其余三样：`POST .../model` 现在对**任意一个活着的会话**成立，
+ * 而「这段对话里有没有图片」问的必须是**那一段**（引导会话的历史里有图片、
+ * 而 B 那段没有的话，B 换一个不认图的模型会被一道莫名其妙的闸拦下来）。
+ */
+interface SessionHistoryFacts {
+    getHistory(): readonly {
+        parts?: readonly {
+            type: string;
+        }[];
+    }[];
+}
+
+/**
+ * 这个会话**此刻**用哪个模型 —— `GET` / `POST /api/sessions/:id/model`
+ * （方案 26 的 web 那一半，2026-08-15）。
+ *
+ * ## 为什么有这个文件
+ *
+ * TUI 有 `/model`、CLI 有 `--model`，而 web 的路由表里**一条都没有**：
+ * `runtime.model` 那套 `ModelControl`（`runtime/src/build.ts`）早就做完了，
+ * 缺的只是转出去这一步。`packages/web/README.md` 把这笔账记了三轮
+ * （「要让用户换这个会话此刻的模型，得先在 server 加端点」）。
+ *
+ * ⚠️ **和 [settings.ts](./settings.ts) 那条写端点不是一回事，别合并。**
+ * 那一条改盘上的配置文件、要重启才生效、答的是「以后默认用哪个」；
+ * 这一条改的是这个进程里正在跑的那个选择、立刻生效、什么都不写盘。
+ * 整张对照表在 `protocol/src/wire-model.ts` 的文件头。
+ *
+ * ## 结构镜像，不是 import
+ *
+ * `@epoch-agent/server` **不许 import `@epoch-agent/core`**（`check-layers.mjs`
+ * 是硬闸门），而 `ModelControl` 的真身在 runtime、判据在 core 的
+ * `provider/selection.ts`。所以这里按用得到的字段再声明一遍，
+ * `EpochRuntime` **结构上**正好满足 —— 对不上就是镜像漏了一块，
+ * 装配那一行当场编译不过。同 `settings.ts` / `security.ts` 的规矩。
+ *
+ * ### 只借三个动词，`enterTurn` / `drainNotices` 刻意不借
+ *
+ * 同 `plan` 那一处「`forget()` 刻意不借」的判据：
+ *
+ * - **`enterTurn`** 是斜杠命令 frontmatter 的 `model:` 那条路，它只管一轮、
+ *   轮末无条件还原，而且**必须和一次 `run()` 成对**。web 上那一对的两半分别
+ *   在 `commands.ts` 和 Hub 的 `TurnDecorator` 里，从这个端点上够得着它
+ *   等于给下一个人一条「在这儿也能换一轮」的暗示 —— 而那条路上没有还原的对手方
+ * - **`drainNotices`** 是**拉**模型（引擎攒下的提示，一轮收尾时拉一次）。
+ *   它的正确落点是回合收尾那一帧，不是一个用户点出来的换模型请求。
+ *   借到这儿的后果是：用户不换模型就永远看不到「这个模型连续失败太多次」，
+ *   而那句话恰恰是他该去换模型的理由
+ *
+ * ## 中文一律不上网线：拒绝原因走**码 + 参数**
+ *
+ * core 的 `evaluateSelection()` 产出的是**码加参数**（`SelectionRejection`），
+ * `reason` 那句中文只是它的一次渲染，给同进程宿主（TUI / CLI）用的。
+ * 这一层**只转码，不转那句话** —— 服务端硬塞一句中文等于把界面语言钉死在
+ * 服务进程的 locale 上，判据逐字同 `settings.ts` 文件头第 1 条。
+ * 三种拒绝、两种代价的措辞在浏览器的两份 catalog 里。
+ *
+ * ⚠️ 这一处**特别容易图省事**：镜像上真有中文可拿（`reason` / `warnings`
+ * 就在同一个对象上，字段名还写着「给用户看的」）。所以下面那两份镜像
+ * **刻意漏掉了它们** —— 漏掉之后投影里根本写不出来，同 `security.ts` 那四处
+ * 「刻意漏掉一个中文字段」的机制。
+ *
+ * ## ⚠️ 只剩一道闸了（2026-08-16）
+ *
+ * ```
+ * 1. 工厂手里有没有这个会话的运行时 → 404 unknown-session
+ * ```
+ *
+ * 这一节上一版是**三道**，中间那道是 409 `bootstrap-session-only`
+ * （「`ModelControl` 挂在 runtime 上、不按会话分，所以只有最先打开的那个会话
+ * 换得了」）。**那道闸这一轮整个拆了，因为它挡的那件事不存在了**：模型选择从
+ * 2026-08-16 起一个会话一份（方案 30 §十四，落地在 runtime 的
+ * `session-model.ts`），「A 标签页换了模型把 B 会话一起换了」这种错法
+ * 在底座上已经说不出口。
+ *
+ * 第 3 道（503 `no-model-control`）**也一并没了，而这不是把它藏起来**：
+ * provider 层起不来时这个进程**一个会话都建不出来**（`SessionRuntimeFactory`
+ * 的 `assemble()` 当场回 null），于是第 1 道闸先答 404。硬把 503 挪到最前面
+ * 的话，一个打错的 sessionId 会换回一句「这台机器没有 provider 层」——
+ * 一句真话，但答的不是他问的那个问题。码本身留在契约上，这条端点不再发它。
+ *
+ * ## 问**工厂**，不问 Hub，也不问会话目录
+ *
+ * 这条路要的对手方是「这个会话在这个进程里的那份运行时」，而工厂就是那张表
+ * 本身。Hub 那张表今天和它逐条相同（冷却时两边一起掉），但**问对了对象**
+ * 比「今天恰好相等」强 —— 判据同 2026-08-15 那次把三条回退端点从
+ * `WebRuntimeView.checkpoints` 改成 `checkpointsOf()` 的处置。
+ *
+ * ## `hasImages` 由**这一层**填，不收浏览器报的数
+ *
+ * 判据逐字同 `cli/src/tui-host.ts` 的 `sessionHasImages()`：界面只看得见
+ * 自己画过的那些，`--resume` 接回来的历史、以及压缩掉的那一截里的图片，
+ * 它一概不知道。让界面报这一项等于把一道真闸门交给一个看不全的人，
+ * 而判成 false 的代价很具体：切到不认图的模型，下一轮把整段带图历史发出去，
+ * provider 报 400 且**已经计费**。
+ *
+ * 另一项（`usedTokens`）反过来**只有浏览器有**，见 {@link readModelSetBody}。
+ *
+ * ## ✅ 2026-08-16 合并时收掉了（原文是一张 📮，留着当判据）
+ *
+ * 自定义斜杠命令 frontmatter 的 `model:`（「这一条命令只换这一轮」）走的是
+ * [commands.ts](./commands.ts) 的 `scopeTurn()`，它读的**曾经**是 `runtime.model`
+ * 那一格 —— 也就是引导会话那一份。模型选择这一轮变成会话级之后，那条路在
+ * 第二个会话上的表现是：
+ *
+ * - 那条命令的 `model:` **对这个会话一点作用都没有**（B 的循环读的是 B 自己
+ *   那个 router，而 `enterTurn` 换的是引导会话那个）；
+ * - 更糟的一半：它**顺带把引导会话的选择换掉了一轮**。A 正好在跑的话，
+ *   A 那一轮会用上 B 那条命令点名的模型。
+ *
+ * ⚠️ **这不是这一轮引入的一个新 bug，是一个旧 bug 换了形状**：在会话级之前，
+ * B 那条命令换的是**所有人共用**的那个选择，A 同样会被拖下水。两版都错，
+ * 而这一版多了「对 B 无效」这一半。如实记着，别当成没动过。
+ *
+ * **写这张 📮 的那一轮不改**：`commands.ts` / `api.ts` 不归它，而正确的改法要动
+ * 它们两个（[方案 30 §十二](../../../docs/verify/VERIFY_RECORD-30-web-multi-session.md)
+ * 的第 3 条：不绕过去、不伸手改、就地写下来）。合并的那一轮照着三步收完了：
+ *
+ * 1. `RuntimeCommandModel`（`commands.ts` 上那个 `model: ModelTurnsView | null`）
+ *    **整个删掉**了 —— 它借的恒是进程那一份。`expandUserContent()` /
+ *    `scopeTurn()` 改成从调用方收这一格，形状照 `checkpointsOf(ctx, sessionId)`；
+ * 2. 真源本来就在手边：`ctx.runtime.sessionFactory.get(sessionId)?.model`。
+ *    **runtime 一个字没加** —— `ModelControl` 上五个动词一直都全，
+ *    只差 server 这一跳；
+ * 3. `enterTurn` 加进了 `sessions/scope.ts` 那份镜像。原文说这一步「有意留给
+ *    收的人做」，因为加它等于承认「这条路上有一个和 `run()` 成对的还原动作」——
+ *    那句话由 `commands.ts` 说了，判据抄在 `SessionModelView.enterTurn` 上。
+ *
+ * ⚠️ 一处**没有**跟着变的：取不到会话（冷却中、或 `sessionFactory` 里没有）时
+ * 传 null，`withModelScope` 对 null 是零开销直通 —— 命令正文照跑，只有 `model:`
+ * 那一半不生效。**和 provider 没配起来时同一档**，判据在 `api.ts` 那一处。
+ */
+
+/**
+ * `ModelControl` 的镜像 —— 这条路上要的 `get` / `set` / `reset` 三个动词，
+ * 外加 `enterTurn`（**这一层一个字都不读它**，见下）。`drainNotices` 不借，
+ * 判据见文件头。
+ *
+ * 三样都是函数而不是拍下来的值：换模型这件事的全部意义就是它会变，
+ * 快照等于让这个端点永远回装配时那一份。
+ *
+ * ## 为什么还 `extends ModelTurnsView`
+ *
+ * 这条路要 `get` / `set` / `reset` 三个，`ModelTurnsView` 那一格
+ * （`enterTurn`）2026-08-16 起**已经没有第二个消费者从 `runtime` 上取它了**
+ * —— 斜杠命令那条路改成从会话那份镜像取（`sessions/scope.ts` 的
+ * `SessionModelView.enterTurn`）。
+ *
+ * 那为什么不把 `enterTurn` 从这儿摘掉？因为**这一份镜像照的是引导会话那个
+ * `ModelControl` 本体**，而它身上就是有这个动词。摘掉等于让镜像比本体窄，
+ * 下一个人会以为「进程那一份没有 enterTurn」——真相是「有，但没人该从这儿拿」。
+ * 那句话由上面 ✅ 那一节说，不由类型形状说。
+ */
+interface ModelControlView extends ModelTurnsView {
+    get(): SelectionView;
+    set(ref: {
+        provider?: ProviderType;
+        model: string;
+    }, ctx: {
+        hasImages?: boolean;
+        usedTokens?: number;
+    }): SetSelectionView;
+    reset(ctx: {
+        hasImages?: boolean;
+        usedTokens?: number;
+    }): SetSelectionView;
+}
+/**
+ * 这段会话里出现过图片吗 —— 只借**读历史**这一件事。
+ *
+ * 形状本体 2026-08-16 搬去了 [sessions/scope.ts](./sessions/scope.js)
+ * （`SessionHistoryFacts`）：这条路要问的是**这一段**会话的历史，而那份形状
+ * 现在挂在 `LiveSessionView.session` 上。这个别名留着是因为
+ * `context.ts` 的 `WebRuntimeView.session` 仍然引它 —— 那一格答的是
+ * **引导会话**，形状一个字没变。
+ */
+type ModelSessionFacts = SessionHistoryFacts;
+/**
+ * server 从 runtime 借的「模型」那一片。`WebRuntimeView` 继承它。
+ *
+ * **可以为 null** —— provider 层起不来时这个进程整个没有「换模型」这回事，
+ * 那时读端点回 `selection: null`、写端点回 503（`EpochRuntime.model` 上是同一句）。
+ * 不假装成功：回 200 的话，界面会画上新模型名，而引擎下一轮照旧用旧的。
+ */
+interface RuntimeModel {
+    model: ModelControlView | null;
+    /** 配置里那个模型（`reset` 的目标）。`EpochConfig.model` 结构上满足它 */
+    config: {
+        model: string;
+    };
+}
+
+/**
+ * 「我们支持哪几家、这一家有哪些模型」 —— `GET /api/providers` 和
+ * `POST /api/providers/:type/models`。
+ *
+ * ## ⚠️ 这两条**进程级，URL 上一个 `:id` 都没有**
+ *
+ * 判据同 `POST /api/mcp/:name/reconnect` 和 `GET /api/workspaces/dirs`：
+ * provider 清单和模型清单**不属于某一段会话**。挂到 `/sessions/:id/` 底下会得到
+ * 一组名字是会话级、行为是进程级的端点 —— 比不一致更坏（`packages/web/README.md`
+ * 那一节逐字记着这条）。这一下的作用域由**界面在按下去之前说清**，不由 URL 说。
+ *
+ * ## 为什么是两条而不是一条
+ *
+ * 它们的**代价差三个数量级**，合成一条就必然有一半是浪费：
+ *
+ * - `GET /api/providers` 读的是一张编译期常量表加一次凭据探测，**没有网络**。
+ *   界面一打开就要它（不然 provider 那个选择器画不出来）。
+ * - `POST /api/providers/:type/models` 是一发**真的网络请求**（10 秒超时），
+ *   只在用户点了某一家之后才该发。
+ *
+ * 合成一条的话，要么每次开菜单都替用户去 provider 那儿探一次，
+ * 要么第一次开菜单看不到 provider 单子。两条都不行。
+ *
+ * ## 后一条是 POST，而它**不是**因为「要带参数」
+ *
+ * 这一下有两处真实的副作用：带着用户那把 key 发一个外网请求、以及把结果
+ * **写进磁盘缓存**。`auth.ts` 那道 Origin 校验只在非安全方法上要求 ——
+ * 写成 GET 等于让任何一个页面都能驱使这台机器去 provider 那儿发请求。
+ * 判据同 plan / rewind / settings / `POST .../model` 那几条。
+ *
+ * ## 结构镜像，不是 import
+ *
+ * `@epoch-agent/server` **不许 import `@epoch-agent/core`**（`check-layers.mjs`
+ * 是硬闸门），而 `discoverModels()` 的真身在 core、收窄口在 runtime 的
+ * `model-catalog.ts`。所以这里按用得到的字段再声明一遍，`EpochRuntime`
+ * **结构上**正好满足 —— 对不上就是镜像漏了一块，装配那一行当场编译不过。
+ * 同 `model.ts` / `settings.ts` / `security.ts` 的规矩。
+ *
+ * ## ⚠️ 这一层**一个中文字都不发**
+ *
+ * 四档「探到 / 探不到」走的是**码**（`WireModelProbeStatus`），措辞在浏览器的
+ * 两份 catalog 里。判据逐字同 `settings.ts` 文件头第 1 条：服务端硬塞一句中文
+ * 等于把界面语言钉死在服务进程的 locale 上。
+ *
+ * ⚠️ 而这一处**特别容易图省事**：`epoch model` 那边已经有一句现成的中文了
+ * （`cli/src/commands/model.ts` 的 `describeDiscovery()`），照抄过来就能省一份
+ * catalog。不许 —— 那一句是给同进程宿主（终端）拼的一次渲染，
+ * 而且它只分两档（有没有 key），这一屏要分四档。
+ */
+
+/** 一个可挑的 provider 在服务端眼里的样子。runtime 的 `ProviderOption` 满足它 */
+interface ProviderOptionView {
+    type: ProviderType;
+    label: string;
+    envVar: string | null;
+    hasKey: boolean;
+}
+/** 探一家的结果。runtime 的 `ModelSuggestions` 满足它 */
+interface ModelSuggestionsView {
+    provider: ProviderType;
+    models: readonly string[];
+    source: WireModelSource;
+    status: WireModelProbeStatus;
+}
+/**
+ * `ModelCatalogControl`（runtime）在服务端眼里的样子 —— **只有两个动词**。
+ *
+ * 镜像里只有这两个，于是这个包**写不出**「把 homeDir 拿来自己拼一个缓存路径」
+ * 或者「读一把裸 key」这种事：那两样在收窄口上压根不存在。
+ * 同 `McpControlView` 只有 `reconnect`、五份安全镜像各自漏掉一个中文字段。
+ */
+interface ModelCatalogView {
+    providers(): readonly ProviderOptionView[];
+    discover(provider: ProviderType, opts?: {
+        refresh?: boolean;
+    }): Promise<ModelSuggestionsView>;
+}
+/**
+ * server 从 runtime 借的「provider 目录」那一片。`WebRuntimeView` 继承它。
+ *
+ * ⚠️ **不可为 null，和 `RuntimeModel.model` 刻意不同档。** 那一个是「换模型」，
+ * provider 层起不来就没有对手方；这一个是「有哪些可选」——
+ * 而**恰恰是一把 key 都没配的那台机器最需要它**。判据在 runtime 那个字段上。
+ */
+interface RuntimeModelCatalog {
+    modelCatalog: ModelCatalogView;
+}
+
+/**
+ * `WebRuntimeView.schedules` —— **server 从 runtime 借的定时任务那一片**
+ * （[方案 45](../../../../.agents/plans/45-scheduled-automation-plan.md) PR-3）。
+ *
+ * ## 为什么是一份结构镜像，而不是 `import type { ScheduleControl }`
+ *
+ * `@epoch-agent/server` 依赖得到 runtime，所以直接 import 那个类型在编译上是通的。
+ * 不那么做有两条理由，第二条是硬的：
+ *
+ * 1. **`context.ts` 那句话**：这一层只借「用得到的那一小片」。`ScheduleControl`
+ *    上有 `create` / `update` 的完整入参类型，而它们的字段来自 core
+ *    （`CreateScheduleInput`）—— 借整个接口等于让 `@epoch-agent/server` 的公开
+ *    `.d.ts` 引用一个它没声明依赖的包；
+ * 2. **用例要造得出一个假的**。`server/__tests__/harness.ts` 的假 runtime 是手写
+ *    对象（那份文件头写着理由：起一个真 runtime 要 provider、SQLite 和 MCP 子进程）。
+ *    镜像用 protocol 的类型写完之后，那个假件一行 core 都不用碰。
+ *
+ * ⚠️ **镜像必须和真身逐字段对得上**，否则 `cli/src/commands/web.ts` 那一行
+ * `createWebServer({ runtime })` 当场编译不过 —— 那正是这份镜像的全部强制力。
+ * 别在这儿「顺手宽松一点」：`create` 的入参在 TS 里是逆变的，宽一格就意味着
+ * 服务端能构造出一个真身收不下的请求。
+ *
+ * ## 判定、算术、缺省值**一样都不在这一层**
+ *
+ * 校验（`validateSchedule`）、注册进 OS（`ScheduleRegistrar`）、跑一次
+ * （`fireSchedule`）、下一次触发时刻（`nextRunAt`）、读录像（`readRecording`）
+ * 全在 core / runtime。这个目录只做两件事：**把 HTTP 翻成那几个方法**，
+ * 以及**把结果投影成网线形状**。
+ */
+
+/**
+ * 建一条任务要给的东西 —— core 的 `CreateScheduleInput` 那一份。
+ *
+ * ⚠️ **字段清单必须逐项相同**（含可选性），见文件头那条 ⚠️。
+ * `id` / 时间戳 / `os*` 那几样不在这里：它们由 store 和注册器写。
+ */
+interface ScheduleCreateView {
+    name: string;
+    prompt: string;
+    /** 不给就落到 `~/.epoch/automation/<id>/`，**不是**服务进程的 cwd */
+    workDir?: string;
+    model?: string;
+    permission: PermissionLevel;
+    allowTools?: readonly string[];
+    allowOperations?: readonly OperationType[];
+    allowRules?: readonly string[];
+    maxTurns?: number;
+    /** **必填，没有默认值**（§3.5）。这一条摊在类型上，不靠注释 */
+    maxBudgetUsd: number;
+    timeoutMs?: number;
+    trigger: ScheduleTrigger;
+    startDate?: string;
+    endDate?: string;
+    enabled?: boolean;
+}
+/** 改一条任务 —— core 的 `UpdateScheduleInput`。没给的字段一个都不动 */
+type ScheduleUpdateView = Partial<ScheduleCreateView>;
+/** 存下来了没有 —— core / runtime 的 `ScheduleSaveResult` */
+interface ScheduleSaveView {
+    /** 校验不过时 `undefined`，且库里一个字都没写 */
+    schedule?: ScheduleDefinition;
+    /** 一条都没有才算存下来了 */
+    issues: WireScheduleIssue[];
+    /** 没要求注册时不带 */
+    registration?: ScheduleRegisterView;
+}
+/**
+ * 注册进操作系统的结果 —— core 的 `RegisterOutcome`。
+ *
+ * 三种 `ok: false` 里只有 `backend-error` 是故障，另两种是如实作答 ——
+ * 判据在网线那一份（`WireScheduleRegistration`）上。
+ */
+type ScheduleRegisterView = {
+    ok: true;
+    warnings: 'source'[];
+} | {
+    ok: false;
+    reason: 'refused';
+    refusal: 'npx' | 'no-host-runner';
+} | {
+    ok: false;
+    reason: 'unsupported-platform';
+} | {
+    ok: false;
+    reason: 'backend-error';
+    detail: string;
+};
+/** 跑一次的结果 —— runtime 的 `FireResult` */
+interface ScheduleFireView {
+    status: ScheduleRunStatus;
+    exitCode: number;
+    /** 真的落了一条运行记录时才有 */
+    run?: ScheduleRun;
+    /** 库里压根没有这条任务 */
+    missing?: boolean;
+    /** 任务停用着（非 `manual` 路径） */
+    disabled?: boolean;
+    detail?: string;
+}
+/** 这台机器 / 这个宿主能做到哪一步 —— runtime 的 `ScheduleCapability` */
+interface ScheduleCapabilityView {
+    backend: ScheduleBackendKind | null;
+    canRegister: boolean;
+}
+/**
+ * 定时任务那一片能力。`EpochRuntime.schedules` 结构上正好满足它。
+ *
+ * ⚠️ **不可为 null**：底下只有一张 SQLite 表和一次平台探测，没有起不来的可能
+ * （`build.ts` 上那个字段的 JSDoc 写着同一句）。本平台没有 OS 后端时
+ * `capability()` 如实说 `backend: null` —— 那是一个答案，不是一个缺失的能力。
+ */
+interface ScheduleControlView {
+    list: () => ScheduleDefinition[];
+    get: (id: string) => ScheduleDefinition | undefined;
+    /** 某条任务最近几次运行，最新的在前 */
+    runs: (id: string, limit?: number) => ScheduleRun[];
+    /** 全部任务的最近运行 —— 「运行记录」那个 tab 的素材 */
+    recentRuns: (limit?: number) => ScheduleRun[];
+    capability: () => Promise<ScheduleCapabilityView>;
+    create: (input: ScheduleCreateView, opts?: {
+        register?: boolean;
+        bypassAcknowledged?: boolean;
+    }) => Promise<ScheduleSaveView>;
+    update: (id: string, patch: ScheduleUpdateView, opts?: {
+        register?: boolean;
+        bypassAcknowledged?: boolean;
+    }) => Promise<ScheduleSaveView>;
+    remove: (id: string) => Promise<boolean>;
+    setEnabled: (id: string, enabled: boolean) => Promise<ScheduleRegisterView>;
+    /** 立刻跑一次。「先跑一次」那个按钮和 OS 触发跑的是同一段执行器 */
+    fire: (id: string, opts?: {
+        manual?: boolean;
+    }) => Promise<ScheduleFireView>;
+    /** 这一档权限档下那份清单有没有意义（界面据此把整块灰掉） */
+    needsAllowlist: (permission: PermissionLevel) => boolean;
+}
+
+/**
+ * 会话 ↔ 工作区的绑定在服务端这一侧（[决定 18](../../../../design/web-ui/README.md)）。
+ *
+ * 三件事，都刻意**不在** [api.ts](../api.ts) 里：那个文件是「一个端点一个函数」，
+ * 而这三件是端点之间共用的料。
+ *
+ *   1. runtime 那片能力的**结构镜像**（`@epoch-agent/server` 不许 import
+ *      `@epoch-agent/core`，而 `WorkspaceControl` 上挂着 `Workspace` /
+ *      `TrustDecision` / `ProjectContext` 三个 core 类型）
+ *   2. 绑定 → Wire 载荷的投影
+ *   3. `POST /api/sessions` 那个可选字段的解析，以及绑定失败 → HTTP 状态码的映射
+ *
+ * ## 为什么再声明一遍而不是 import runtime 的类型
+ *
+ * 同 `WebRuntimeView` / `SessionCatalog` 的理由：收窄到真正用得到的那几项，于是
+ * 用例能喂一个几十行的假对象。`EpochRuntime.workspaces` **结构上**满足
+ * {@link WorkspaceView} —— 对不上就是接口漏了一块，当场编译不过。
+ */
+
+/**
+ * 一个已经绑好的工作区。三段刚好对上 runtime 的 `SessionWorkspace`：
+ * 路径边界 / 信任判定 / 判定的产物。
+ */
+interface BoundWorkspace {
+    workspace: {
+        root: string;
+        extra: readonly string[];
+    };
+    /** `trusted: false` = 这个目录的指令文件**不进** system prompt */
+    trust: TrustView;
+    projectContext: {
+        /** 真加载了的那几份 */
+        instructions: ReadonlyArray<{
+            path: string;
+        }>;
+        /** 存在、但被信任闸门挡下的那几份 */
+        skippedInstructions: readonly string[];
+    };
+    /**
+     * **额外根**里存在、但一律不加载的约定文件（安全中心要报它，方案 42 PR-3）。
+     *
+     * 和 `projectContext.skippedInstructions` 不是一回事：那一份是**主根**的、
+     * 被信任闸门挡下、信任了就会加载；这一份是 `--add-dir` 进来的目录里那些、
+     * **信任了也不会加载**。合并之后界面只能给一句话，而两处的出路完全不同。
+     *
+     * 为什么由 runtime 算好递过来：算它要 core 的 `unloadedInstructionFiles()`，
+     * 而这个包不许 import core。
+     */
+    unloadedInstructions: readonly string[];
+}
+/**
+ * `TrustDecision` 的镜像。
+ *
+ * **没有 `reason`** —— 那是「人类可读的判定依据，进启动 diagnostics」，也就是
+ * 一句中文。浏览器要按自己的语言组句（同 `RoleNoticeView` 丢掉 `detail`）。
+ *
+ * `level` 和 `trusted` 两个都留着，因为它们能不一样、而差别处正是用户要看的：
+ * `unknown` + 未信任 是「还没问过你」，`untrusted` + 未信任 是「你自己拒过」。
+ */
+interface TrustView {
+    trusted: boolean;
+    /** 存储里的原始判定，**未经**降级规则处理 */
+    level: TrustLevel;
+}
+/**
+ * 绑定失败的四种原因。
+ *
+ * **逐字抄 runtime 那个联合而不是收成 `string`**：这四个值决定 HTTP 状态码
+ * （`locked` 是 409，其余是 400），写成 `string` 之后 runtime 那边加第五种，
+ * 这里会静默把它当成 400 —— 而那第五种完全可能该是别的码。
+ */
+type WorkspaceBindFailure = 'not-absolute' | 'missing' | 'not-a-directory' | 'locked';
+type WorkspaceBindOutcome = 
+/** `changed: false` = 本来就绑在这个目录上，这次是幂等的 */
+{
+    ok: true;
+    bound: BoundWorkspace;
+    changed: boolean;
+} | {
+    ok: false;
+    reason: WorkspaceBindFailure;
+    detail: string;
+};
+/**
+ * 一个会话和工作区的关系（方案 55 §2.1）—— 逐字抄 runtime 的
+ * `WorkspaceBindingState`，理由同上面 {@link WorkspaceBindFailure}：
+ * 这三个值直接决定 `POST .../workspace` 收不收得动（只有 `unbound` 收），
+ * 收成 `string` 之后 runtime 那边加第四档，这里会静默把它当成「收得动」。
+ */
+type WorkspaceBindingState = 'bound' | 'none' | 'unbound';
+/** runtime 的 `WorkspaceControl` 在服务端眼里的样子 */
+interface WorkspaceView {
+    of(sessionId: string): BoundWorkspace | null;
+    /**
+     * @param lang 失败那几档的 `detail` 用哪个语言渲染（方案 58 PR-2）。
+     *             不给 = 进程语言，逐字节等于这一轮之前。
+     *
+     * ⚠️ **`detail` 是这条路上唯一跟语言走的东西**：`reason` 是契约
+     * （`bindFailureToHttp` 拿它挑状态码和 `code`），一个字都不许翻。
+     */
+    bind(sessionId: string, dir: string, lang?: Lang): WorkspaceBindOutcome;
+    /** 记一笔「建出来了、还没选地盘」（方案 55 PR-1）。已绑的会话上是空操作 */
+    defer(sessionId: string): void;
+    /**
+     * 记一笔「用户明确选了**不使用**工作区」（会话库 v7，2026-08-19）。
+     *
+     * `POST /api/sessions/:id/workspace` 的 `{none:true}` 那一支走它。
+     * 2026-08-19 之前那一支走的是 {@link release} —— 在内存里两者等价，
+     * 换掉是因为这一档现在要落盘，而 `release()` 同时还是「建会话失败回滚」
+     * 和「会话被删」两条路。判据全文在 runtime 的 `WorkspaceControl.decideNone` 上。
+     */
+    decideNone(sessionId: string): void;
+    /** 这个会话是哪一档。**不答「这个进程认不认识它」**，那一问由 Hub 答 */
+    stateOf(sessionId: string): WorkspaceBindingState;
+    release(sessionId: string): void;
+    /** 本机「已知工作区」清单，最近使用的在前 */
+    known(): ReadonlyArray<{
+        root: string;
+        name: string;
+    }>;
+    /**
+     * **任意**目录的信任判定，不要求它被哪个会话绑着（方案 42 PR-3）。
+     *
+     * {@link known} 给的清单一个信任状态都没有，而安全中心那张状态卡上写的是
+     * 「N 个 · M 个未信任」—— 没有这个方法，M 只能拿 {@link of} 去数当前进程
+     * 绑着的那几个，于是绝大多数行会显示成「未知」，而真相是它们各有各的记录。
+     */
+    trustOf(dir: string): TrustView;
+}
+
+/**
+ * 安全中心的取数与投影 —— `GET /api/sessions/:id/security`（方案 42 PR-3）。
+ *
+ * 不在 [api.ts](./api.ts) 里，同 [capability.ts](./capability.ts) 的理由：那个
+ * 文件是「一个端点一个函数」，而这里有五份 runtime 能力的**结构镜像**加六段投影。
+ *
+ * ## 结构镜像，不是 import
+ *
+ * `@epoch-agent/server` **不许 import `@epoch-agent/core`**（`check-layers.mjs`
+ * 是硬闸门），而隔离报告 / 权限规则 / 遮蔽发现 / 信任判定 / 审计流水五样的真身
+ * 都在 core。所以这里按用得到的字段再声明一遍，`EpochRuntime` **结构上**正好
+ * 满足 —— 对不上就是镜像漏了一块，装配那一行当场编译不过。
+ *
+ * ## 这一层的主要工作是**把中文挡在外面**
+ *
+ * 五份镜像里有四份刻意漏掉了一个字段，全是中文散文（判据见
+ * `protocol/wire-security.ts` 的文件头那张表）：
+ *
+ * - `IsolationView` 没有 `detail` —— 用 `reason` 那个码
+ * - `ShadowView` 没有 `message` —— 用 `kind` + `rule` + `by`
+ * - `ManagedView` 没有 `switches` —— 用 `rulesOnly` / `bypassDisabled`
+ * - `AuditRowView` 没有 `reason` —— 用 `code` 那个码
+ *
+ * 漏掉是**编译期生效的**：镜像上没有那个字段，投影里就写不出
+ * `iso.detail`，写了当场不过。这比在 review 里靠眼睛盯可靠。
+ *
+ * 第四条是这四条里最硬的一条：前三处丢的是一句可有可无的补充说明，
+ * `PermissionAuditEntry.reason` 是审计流水那张表的**一整列**。
+ *
+ * ## 「进程有什么」和「这个会话有什么」
+ *
+ * 权限规则、托管锁、审计流水、策略目录四样今天是**进程级**的。前三样的判据在
+ * core 的 [permission/shared.ts](../../core/src/permission/shared.ts) 文件头：
+ * 它们是关于**用户**和**这台机器**的事实，跟着会话走反而会说假话（审批缓存
+ * 分了家，「总是允许」在第二个会话上白点；流水分了家，这一屏会漏掉除引导会话
+ * 之外的全部裁决）。策略目录是装配时读一次。工作区和它的信任判定是**会话级**
+ * 的（决定 18）。URL 定成会话作用域是就着后者 —— 反过来定成 `/api/security`
+ * 的话，那天要改的是两个包（同 capabilities 的判断）。
+ *
+ * ⚠️ **档位不在上面任何一档里 —— 它 2026-08-16 起是会话级的**（方案 30 §十四，
+ * core 的 `PermissionManager.scoped()`）。这个文件 2026-08-16 之前发的是进程
+ * 那一份，那是一处真缺陷；**2026-08-17 合并那一轮收掉了**，判据见下一节。
+ *
+ * ⚠️ 等方案 30 §6.3 的多会话工厂落地，策略目录也会跟着工作区变（项目那一级
+ * 是 `<root>/.epoch/policies`），**那时这里要改**：`runtime.policy` 得按
+ * `workspaces.of(sessionId)` 重算，而不是读装配时那一份。
+ *
+ * ## ✅ 收掉了（2026-08-17）：`permission.level` 这一格曾经答的是**引导会话**
+ *
+ * 下面整节是那张 📮 的原文，**一个字没改**。它留着不是纪念品：这一格今天对了
+ * 靠的是 `api.ts` 里那**一个实参**，而那一行看上去像是可有可无的第四个参数。
+ * 哪天有人为了「少传一个东西」把它删回三参，症状就是下面写的那些 ——
+ * 印错一个词、外加一张在最该发黄的时候是绿的卡。**判据比修法长，是因为
+ * 这类 bug 编译得过、跑得通、每一条用例都绿。**
+ *
+ * {@link collectSecurity} 里那句 `perms.level()` 读的是 {@link PermissionsView}，
+ * 也就是 `WebRuntimeView.permissions`。runtime 的 `buildPermissionsControl()`
+ * 把 `level` / `setLevel` 两格**整个转发给引导会话那一份**（那边逐字是
+ * `level: () => bootstrap?.level() ?? services.config.permission`）。
+ * 于是浏览器看着会话 B 时，安全中心那一格印的是会话 A 那一档。
+ *
+ * 这和 2026-08-15 治掉的 `config.workspace` 是同一类病（方案 30 §10.4 第 1 条）：
+ * **端点按会话取，载荷里那一格却是进程级的。** 契约那边早把它说死了 ——
+ * `WirePermissionState.level` 的 JSDoc 逐字写着「安全中心那一格和底栏这一格印的
+ * **必须是同一个名词**」，而底栏那一格从 2026-08-16 起按会话取
+ * （[permission.ts](./permission.js) 的 `permissionState()`）。今天这两格能不一样。
+ *
+ * ⚠️ **代价不止是印错一个词。** 那一屏顶上四张状态卡的第一条纪律是「取最差的
+ * 那一处」，而档位那张卡的色带就照这个值算：会话 B 在 `bypass` 上、引导会话在
+ * `default` 上时，**那张卡是绿的**。一屏「我现在安不安全」的界面，在最该发黄的
+ * 那一刻答了别人的状态。
+ *
+ * **缺的那一段只有一处，而它在 [api.ts](./api.ts) 里，那个文件这一轮不归我改**
+ * （✅ 这一段就是收掉的那一笔，`getSecurity()` 里现在逐字是这个 diff）：
+ *
+ * ```diff
+ *    // api.ts / getSecurity()
+ *    const payload = collectSecurity(
+ *      ctx.runtime,
+ *      ctx.runtime.workspaces,
+ *      ctx.runtime.workspaces.of(sessionId),
+ * +    ctx.runtime.sessionFactory.get(sessionId)?.permissions ?? null,
+ *    );
+ * ```
+ *
+ * 这一层跟着收第四个参数
+ * `session: Pick<SessionPermissionsView, 'level'> | null`（类型在
+ * [sessions/scope.ts](./sessions/scope.js)，**那一层已经镜像好了，不用动
+ * core / runtime**），投影里 `level` 改成 `session?.level() ?? perms.level()` ——
+ * 这个进程没在跑那段会话（只剩历史 / 被冷却）时退回进程那一份，那仍然是一句
+ * 真话，判据逐字同 `permissionState()` 那条兜底。
+ *
+ * ⚠️ **`rules` / `shadows` / `managed` / `audit` 四样一个都不许跟着搬。**
+ * 判据在 core 的 `permission/shared.ts`：它们**没有**跟着会话分家。搬过去的
+ * 具体代价是这一屏只剩下这一个会话判过的那几行 ——
+ * **一本漏了行的安全流水比没有账更坏，因为它看起来是完整的。**
+ *
+ * ⚠️ 这一轮**刻意没有**顺手加一个「不传就回落到进程那一份」的可选第四参。
+ * 那个形状编译得过、跑得通、只是答错会话，正是 `context.ts` 删掉进程级
+ * `checkpoints` 那一段点名的病；而且半接上的参数会让下一个人以为这条已经收了。
+ * 要么四个实参一起到位，要么这一格照旧是一处**写在文件头上的**缺陷。
+ *
+ * > ✅ **收的时候按这句办了：第四参是必填的，不是可选的。** 唯一的调用点
+ * > （`api.ts` 的 `getSecurity()`）传的是
+ * > `sessionFactory.get(sessionId)?.permissions ?? null` —— **`null` 是显式的**，
+ * > 由调用方写出来，不是省略出来的。回落发生在投影里
+ * > （`session?.level() ?? perms.level()`），而不是发生在「忘了传」这件事上。
+ * > 这两者的区别不在行为上（都退回进程那一份），在于**下一个新加调用点的人
+ * > 会不会被编译器拦住**：可选参数不拦，必填参数拦。
+ */
+
+/**
+ * `IsolationReport` 在服务端眼里的样子。
+ *
+ * **没有 `detail`** —— 那是给终端里的人读的一句中文散文。见文件头。
+ */
+interface IsolationView {
+    level: 'os' | 'process';
+    backend: 'seatbelt' | 'bubblewrap' | 'none';
+    reason: WireSandboxReason;
+    platform: string;
+}
+/** `EffectiveRule` 的镜像。`layer` 是 `string`，服务端**如实转发**、不归一 */
+interface RuleView {
+    bucket: 'allow' | 'ask' | 'deny';
+    rule: string;
+    layer: string;
+}
+/** `ShadowFinding` 的镜像。**没有 `message`** —— 中文，见文件头 */
+interface ShadowView {
+    kind: 'shadowed' | 'partial' | 'redundant';
+    rule: string;
+    by: string;
+}
+/** `ManagedNote` 的镜像。**没有 `switches`** —— 那是「逐条一句人话」，见文件头 */
+interface ManagedView {
+    present: boolean;
+    path: string;
+    rulesOnly: boolean;
+    bypassDisabled: boolean;
+}
+/**
+ * `PermissionAuditEntry` 的镜像。**没有 `reason`** —— 中文，见文件头。
+ *
+ * `code` 直接用 wire 上那个联合而不是 `string`，是刻意的：core 那边加一个新的
+ * 原因码而忘了同步 `WireAuditCode` 时，**装配那一行当场编译不过**
+ * （同 `IsolationView.reason` 用 `WireSandboxReason` 的机制）。写成 `string`
+ * 的话，那个新码会一路发到浏览器，然后在界面上显示成一个查不到文案的空白格。
+ */
+interface AuditRowView {
+    at: number;
+    toolName: string;
+    type: OperationType;
+    target: string;
+    outcome: WireAuditOutcome;
+    code: WireAuditCode;
+}
+/** `PermissionAuditSnapshot` 的镜像 */
+interface AuditView {
+    entries: readonly AuditRowView[];
+    dropped: number;
+}
+/**
+ * `PermissionsControl` 的镜像。前五样都是函数，因为它们**每次读都是当前值** ——
+ * 审计流水尤其如此，它每判一次就长一条。
+ *
+ * ## ⚠️ 第六样是**写**，而它的消费方不在这个文件里
+ *
+ * `setLevel` 是 2026-08-15 补的（决定 20 ③），用它的是
+ * [permission.ts](./permission.js) 那条端点 —— 底栏那一格的真菜单。
+ * 声明摆在这儿而不是那儿，判据同 `model.ts` 的
+ * `ModelControlView extends ModelTurnsView` 那一节：`WebRuntimeView.permissions`
+ * 是**一个**字段，两份镜像各声明一次的话，同时继承两者当场编译不过（TS2320）。
+ * 这个文件是那个字段的主人（它最先镜像它），所以新格子加在这儿。
+ *
+ * **安全中心那一屏一个字都没跟着变**：它照旧只读前五样，
+ * 「这一屏全是读」那条纪律没松（判据在 `wire-security.ts` 的文件头）。
+ */
+interface PermissionsView {
+    rules: () => readonly RuleView[];
+    shadows: () => readonly ShadowView[];
+    /**
+     * ⚠️ **引导会话那一档，不是「这个会话」那一档。**
+     *
+     * 这个名字读起来像是进程级的一个事实，而档位从 2026-08-16 起一个会话一份 ——
+     * runtime 的 `buildPermissionsControl()` 把这一格整个转发给引导会话
+     * （`bootstrap?.level() ?? services.config.permission`）。**按会话取的那一份在
+     * `LiveSessionView.permissions`**（`sessions/scope.ts` 的
+     * `SessionPermissionsView`）。
+     *
+     * ✅ **2026-08-17 起载荷接上它了**：{@link collectSecurity} 的第四参赢过这一格，
+     * 这一格只在工厂手里没有那段会话时兜底。**这个警告留着** —— 它描述的是这个
+     * 类型自己的语义，而那句语义一个字都没变：读它读到的仍然是引导会话那一档。
+     */
+    level: () => string;
+    /**
+     * **配置里那一档** + 它赢在哪一层（方案 56 §1.3）。
+     *
+     * ⚠️ 和上面那个 {@link PermissionsView.level} 是**两个值**，而且这一个
+     * **不跟着会话走**：它是一个配置事实，一个进程一份。所以上面那条
+     * 「第四参赢过这一格」的规矩在这儿不适用，也不该适用 —— 两个值刻意不同步
+     * （决定 20 ④），而界面上正是靠这一点画成两行的。
+     */
+    configured: () => {
+        level: string;
+        layer: 'builtin' | 'user' | 'env';
+    };
+    managed: () => ManagedView;
+    audit: () => AuditView;
+    /**
+     * 切到某一档。**判定本体一个字都不在 server** —— 托管挡 bypass、
+     * `PermissionManager.setLevel()`、`plan.forget()` 三步都在 runtime 的
+     * `PermissionsControl.setLevel()` 里，理由在 `permission.ts` 的文件头。
+     *
+     * 返回类型钉成 `LevelChangeResult` 而不是 `{ok:boolean; reason?:string}`：
+     * runtime 那边加一个拒绝码时，`permission.ts` 那张 `REFUSAL` 映射表
+     * **当场编译不过**（同 `AuditRowView.code` 用 `WireAuditCode` 的机制）。
+     * 写成 `string` 的话，新码会被静默报成 `managed`，而界面照着它说一句
+     * 和真实原因无关的话。
+     */
+    setLevel: (level: PermissionLevel) => LevelChangeResult;
+    /**
+     * ⚠️ 第七样，消费方也不在这个文件里 —— 是 [tools.ts](./tools.js)
+     * （设置 › 工具那一节）。摆在这儿的理由同上面 `setLevel` 那一段：
+     * `WebRuntimeView.permissions` 是**一个**字段，两份镜像各声明一次的话，
+     * 同时继承两者当场编译不过（TS2320）。
+     *
+     * **档位是参数，不是从 `level()` 读的**：那一格是引导会话那一档
+     * （上面那条 ⚠️），而这张表每一行的判定都按档走 —— 在 runtime 里顺手读它的话，
+     * 症状逐字是这个文件头那一整节记着的那件事，只是这次错的是一整张表。
+     *
+     * 返回的是**当下**的判定，别缓存：规则可以在两次请求之间被改盘、
+     * 沙箱可以在第一次 `code_exec` 之后从 `os` 降到 `process`。
+     */
+    gates: (level: PermissionLevel) => readonly GateRowView[];
+}
+/**
+ * `ToolGateRow` 的镜像 —— 一个工具此刻被谁挡着（方案 43 §七的「工具」那一节）。
+ *
+ * **这一份没有刻意漏掉的字段**，和上面四份镜像不同：`description` 是工具自己
+ * 报的一句话（`WireToolSummary.description` 早就在网线上发着同一份），
+ * 不是「给终端里的人读的散文」。
+ *
+ * `verdict` / `by` 直接钉成网线那两个联合而不是 `string`，同 `AuditRowView.code`
+ * 的机制：core 那边给 `GateVerdict` 加一档而忘了同步契约时，**装配那一行当场
+ * 编译不过**；写成 `string` 的话，新档会一路发到浏览器，在界面上显示成一个
+ * 查不到文案的空白格。
+ */
+interface GateRowView {
+    name: string;
+    description: string;
+    source: string;
+    type: OperationType;
+    verdict: WireToolVerdict;
+    by: WireToolGateAxis;
+    rule?: string;
+    layer?: string;
+    conditional: number;
+}
+/** `PolicyStatus` 的镜像 */
+interface PolicyView {
+    dirs: ReadonlyArray<{
+        dir: string;
+        source: 'user' | 'project';
+        ruleCount: number;
+    }>;
+    projectSkipped: boolean;
+    skippedDir: string | null;
+}
+/**
+ * server 从 runtime 借的「安全」那一片。`WebRuntimeView` 继承它。
+ *
+ * `permissions` 可为 null：`PermissionManager` 起不来时整个 `PermissionsControl`
+ * 就是 null（`buildPermissionsControl` 那边），而那时「有哪些规则」的诚实答案是
+ * 「这一层没起来」，不是「零条规则」。
+ */
+interface RuntimeSecurity {
+    isolation: IsolationView | null;
+    permissions: PermissionsView | null;
+    policy: PolicyView;
+}
+/**
+ * 五块一次取齐。
+ *
+ * ⚠️ 五块里**只有工作区那两样按会话取**（`bound` 那个参数）。
+ * `permission.level` 今天走的是进程那一份，也就是引导会话那一档 ——
+ * 那是一处真缺陷，缺的那一段和它的代价逐字写在文件头那节 📮 上。
+ *
+ * @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;
+
+/**
+ * 检查点与回退的取数、投影与三条端点（方案 27 的 web 那一半）。
+ *
+ * ```
+ * GET  /api/sessions/:id/checkpoints        这个进程现在能退哪几轮
+ * GET  /api/sessions/:id/checkpoints/:turn  按下去之前先看：会动哪些文件
+ * POST /api/sessions/:id/rewind             真的退
+ * ```
+ *
+ * 引擎那三件套（`CheckpointControl.list` / `preview` / `rewind`）2026-05 就做完了，
+ * 缺的一直是这一段传输 —— 方案 54 §1.2 那张表第一行的原话是「**今天没有主**。
+ * web 里 `checkpoint` / `rewind` 零命中」。TUI 那边的形态（`/rewind` + Esc Esc
+ * 那个面板）是现成的参照，交互设计照着它抄。
+ *
+ * 不在 [api.ts](./api.ts) 里，理由同 [capability.ts](./capability.ts) 和
+ * [plan.ts](./plan.ts)：那个文件是「一个端点一个函数」，而这里有一份 runtime 能力的
+ * **结构镜像**加三段投影加一段请求体校验。
+ *
+ * ## 结构镜像，不是 import
+ *
+ * `@epoch-agent/server` **不许 import `@epoch-agent/core`**（`check-layers.mjs`
+ * 是硬闸门），而 `CheckpointSummary` / `RewindPreview` / `RewindOutcome` 的真身
+ * 都在 core。所以这里按用得到的字段再声明一遍，`EpochRuntime.checkpoints`
+ * **结构上**正好满足它 —— 对不上就是镜像漏了一块，装配那一行当场编译不过。
+ * 收窄到这几项还有一个好处：用例喂一个几十行的假对象就能跑。
+ *
+ * ⚠️ **别把这份镜像塞进 [workspace/diff.ts](./workspace/diff.ts) 的
+ * `WorkspaceCheckpoints`。** 那个接口的注释写明了它为什么窄：「只要 `list` 和
+ * `preview`：**快照和回退都不该从这里够得着**。这个端点是只读的，而 `rewind`
+ * 会真的改用户的文件」。两个形状因此是**宽的赋给窄的**（`RuntimeCheckpoints`
+ * 结构上满足 `WorkspaceCheckpoints`），diff 那边一行都不用改。
+ *
+ * ## 会话作用域：**向工厂要这个会话自己那一份**
+ *
+ * `CheckpointControl` 的会话 id **由它自己取**（runtime 的 `buildCheckpointControl`
+ * 那句「不让宿主传：`/resume` 之后 `AgentSession.sessionId` 会变」），所以这一层
+ * 不能拿一个 id 去问某一份控制面 —— 它得先拿到**对的那一份**。
+ * 那一份在 {@link checkpointsOf}：`sessionFactory.get(sessionId)?.checkpoints`。
+ *
+ * ⚠️ **这三条端点 2026-08-15 之前读的是 `ctx.runtime.checkpoints`，那是引导会话
+ * 那一份。** 判据写成 `sessionId === ctx.runtime.sessionId` 并叫它 `isLive()`，
+ * 而在多会话工厂之前那两句话恰好同义。工厂落地当天它们分了家：一个进程里活着
+ * N 个 `AgentSession`，每个各有一份 `CheckpointManager`（`workDir` 跟着自己绑的
+ * 工作区走），于是第二个会话拿到的是「列表空数组 + 回退 409『不是本进程正在跑
+ * 的那个』」——**而这个进程正握着它的检查点管理器**。全文与判据在方案 30 §9.5。
+ *
+ * 接对之后两种答法各自答的是真问题：
+ *
+ * - **列表**对「这个进程手里没有的会话」回**空数组**。它答的是「这个进程现在能退
+ *   哪几轮」，而那个问题对一段只剩历史的会话的正确答案就是「一轮都不能」。
+ *   界面据此不画按钮
+ * - **preview / rewind** 对同样的会话回 409 `not-live-session`。它们是「对某一轮
+ *   动手」，而浏览器只可能从上面那份（空的）列表里拿到 turnIndex —— 走到这儿
+ *   说明请求不是这张界面发的，如实拒绝比默默退错一个会话强
+ *
+ * 那个码从今天起**只在这两处**用（`plan-mode.ts` / `model.ts` 换成了
+ * `bootstrap-session-only`），判据见 {@link checkpointsOf}。
+ */
+
+/**
+ * `CheckpointSummary` 在服务端眼里的样子。
+ *
+ * **没有 `cursor`** —— 那是消息表的主键，浏览器拿它什么都做不了。它唯一的用途
+ * （`>= 0` 就能退对话）在 preview 那份里已经是一个布尔了，见
+ * `WireRewindPreview.canRewindConversation`。镜像上没有这个字段是**编译期生效**的：
+ * 投影里写不出 `summary.cursor`，写了当场不过。
+ */
+interface CheckpointSummaryView {
+    turnIndex: number;
+    createdAt: number;
+    preview: string;
+    fileCount: number;
+    incomplete: boolean;
+}
+/** `RewindAction` 的镜像。四个词逐字对齐 core，别在这一层重命名 */
+type RewindActionView = 'restore' | 'delete' | 'recreate' | 'skip';
+/** `RewindDrift` 的镜像。同上 */
+type RewindDriftView = 'as-agent-left-it' | 'changed-since' | 'unknown';
+interface RewindFilePlanView {
+    path: string;
+    action: RewindActionView;
+    drift: RewindDriftView;
+}
+/** `RewindPreview` 的镜像。同样**没有 `cursor`**，理由见 `CheckpointSummaryView` */
+interface RewindPreviewView {
+    turnIndex: number;
+    createdAt: number;
+    preview: string;
+    canRewindConversation: boolean;
+    incomplete: boolean;
+    files: readonly RewindFilePlanView[];
+    conflicts: readonly RewindFilePlanView[];
+}
+/** `RewindOutcome` 的镜像 */
+interface RewindOutcomeView {
+    restored: readonly string[];
+    deleted: readonly string[];
+    recreated: readonly string[];
+    skippedConflicts: readonly string[];
+    /** 整体失败的原因；成功时缺席。**失败即什么都没改** */
+    failed?: string;
+}
+/** `RewindResult` 的镜像 */
+interface RewindResultView {
+    files: RewindOutcomeView | null;
+    messagesRemoved: number | null;
+}
+/**
+ * server 从 runtime 借的「检查点」那一片 —— `EpochRuntime.checkpoints`
+ * （也就是 `CheckpointControl`）结构上正好满足它。
+ *
+ * ⚠️ **三个方法一起借**，不留「只借读的那两个」这条中间形态：那正是本轮之前的
+ * 状态（`WorkspaceCheckpoints` 只有 `list` + `preview`，而且是给 diff 兜底用的），
+ * 而它的表现是界面上一个回退入口都没有。
+ */
+interface RuntimeCheckpoints {
+    /** 这个会话有哪些检查点，**新的在前** */
+    list(): Promise<readonly CheckpointSummaryView[]>;
+    /** 回退之前先看：会动哪些文件、哪些因为漂过而不敢动。检查点不存在时 `null` */
+    preview(turnIndex: number): Promise<RewindPreviewView | null>;
+    /**
+     * 真的退。
+     *
+     * `overwrite` 是用户**逐个点过头**的冲突文件路径；不在里面的冲突一律跳过。
+     * 这里刻意没有、将来也不许长出一个 `force: true` —— 判据在
+     * `WireRewindRequest.overwrite` 上。
+     */
+    rewind(turnIndex: number, opts: {
+        scope: WireRewindScope;
+        overwrite?: readonly string[];
+    }): Promise<RewindResultView>;
+}
+declare function toWireCheckpoint(summary: CheckpointSummaryView): WireCheckpointSummary;
+declare function toWirePreview(preview: RewindPreviewView): WireRewindPreview;
+declare function toWireRewindResult(result: RewindResultView): WireRewindResponse;
+type RewindInput = {
+    ok: true;
+    value: WireRewindRequest;
+} | {
+    ok: false;
+    code: string;
+    message: string;
+};
+/**
+ * `POST /rewind` 的 body → 一个可执行的请求。
+ *
+ * ## `overwrite` 那一条不许静默降级
+ *
+ * 给了但不是字符串数组时**回 400**，而不是当成「没给」。判据是这个字段的语义：
+ * 它是「用户逐个点过头的那几个文件」。静默当成 `[]` 的话，一个把它拼成
+ * `{overwrite: true}` 的客户端会收到 200 + 一份「全都跳过了」的结果，
+ * 而它以为自己刚刚覆盖成功了 —— 那种误会的代价是用户手写的改动被当成已经没了。
+ *
+ * 反过来 `force: true` 这类形状在这条路上**说不出口**：这里只认路径清单。
+ */
+declare function readRewindInput(body: unknown, lang?: Lang): RewindInput;
+
+/**
+ * 多会话工厂在服务端眼里的样子（[方案 30 §6.3](../../../../docs/verify/VERIFY_RECORD-30-web-multi-session.md)）。
+ *
+ * 同 `WorkspaceView` / `SessionCatalog` 的规矩：`@epoch-agent/server` **不许
+ * import `@epoch-agent/core`**，而 runtime 那个 `SessionFactory` 上挂着
+ * `AgentSession` / `SessionWorkspace` 两个 core 侧的类型。所以这里按用得到的
+ * 字段再声明一遍 —— `EpochRuntime.sessionFactory` **结构上**正好满足
+ * {@link SessionFactoryView}，对不上就是镜像漏了一块，装配那一行当场编译不过。
+ *
+ * 收窄之后用例能喂一个几十行的假对象（`__tests__/harness.ts` 的
+ * `fakeSessionFactory`），而不用起一个真 provider。
+ *
+ * ## 建会话的三种结局，和它们各自的 HTTP 码
+ *
+ * | 结局                       | 码  | 用户的下一步        |
+ * | -------------------------- | --- | ------------------- |
+ * | 建出来了 / 复用了一个       | 200 | 开始聊              |
+ * | 路径不对（四种）           | 400 / 409 | 改路径 |
+ * | 专家名不认识               | 400 | 改专家名            |
+ * | provider 没起来            | 503 | 去配一个 API key    |
+ *
+ * 倒数第二档 2026-08-15 加的（决定 20 ② 的底座）。**400 而不是静默降级成
+ * 不分角色**：判据逐字照 `--agent`（runtime 的 `pickMainRole` 抛 `AgentRoleError`）
+ * —— 用户显式点了一个专家，给他跑一个能力范围不同的 agent 是最坏的结果。
+ *
+ * 最后一档是多会话工厂那一轮新出现的：在工厂之前，`POST /api/sessions` 回的恒是
+ * 引导会话，而那个会话就算跑不了也**存在**，所以这条路答不出「建不出来」。
+ * 现在能了 —— 而 503 是唯一诚实的答案：请求没毛病、路径没毛病，是这台机器还没配好。
+ */
+
+/**
+ * runtime 的 `LiveSession` 在服务端眼里的样子 ——「谁」「怎么跑」「退到哪」，
+ * 外加 2026-08-16 收窄进来的那三样（模型 / 权限档 / plan 模式）。
+ *
+ * ⚠️ **那三样以前挂在 `WebRuntimeView` 上，那是进程级的一份**，于是三条写端点
+ * 对非引导会话只能一律 409 `bootstrap-session-only`（方案 30 §10.4 第 2 条 /
+ * §9.5）。搬到这儿之后那三条 409 全部消失 —— 判据在 [scope.ts](./scope.ts)。
+ */
+interface LiveSessionView {
+    readonly sessionId: string;
+    /**
+     * `AgentSession` 结构上满足 `HubSession`（两个成员），Hub 直接收它。
+     *
+     * ⚠️ **2026-08-16 起还多要一个 `getHistory()`**（{@link SessionHistoryFacts}）：
+     * 换模型那条路要问「**这段**对话里有没有图片」。写成交集而不是各借一个字段，
+     * 判据同它原来在 `WebRuntimeView.session` 上那句：它们说的是**同一个对象**，
+     * 拆成两个字段的话装配那边可以只填其中一个。
+     */
+    readonly session: HubSession & SessionHistoryFacts;
+    /**
+     * **这个会话此刻用哪个模型**。runtime 那边 provider 起不来时一个会话都建不出来，
+     * 所以这一格不为 null。
+     */
+    readonly model: SessionModelView;
+    /**
+     * **这一条消息用哪个专家**（方案 57 §3.4，2026-08-17）。
+     *
+     * **不为 null**：一个角色都没加载出来时它照样在，只是 `has()` 恒 false ——
+     * 那是一句真话，不是一个缺失的能力（同 `RuntimeCommands.commands` 那条判据）。
+     * 于是 `POST /messages` 那一侧不用为「这个进程有没有专家」分支。
+     */
+    readonly roles: SessionRoleView;
+    /**
+     * **这个会话以什么身份跑**（会话级那一份，2026-08-18）。
+     *
+     * ⚠️ 和上面 `roles` 是两件事：这一格是**底座身份**（建会话时定，整段不变、决定
+     * system prompt 和工具表），`roles` 是**逐条消息的临时顶替**（那枚 chip）。
+     * 判据全文在 runtime 的 `LiveSession.role` 上。
+     *
+     * `null` = 这个进程压根没指定身份（也没有 `--agent`）。那是一句真话 ——
+     * 界面上那一格整个不画，不是画一个 `general`（决定 20 ①）。
+     */
+    readonly role: ActiveAgentRole | null;
+    /** **这个会话此刻是哪一档**。这个进程没有权限层时 null */
+    readonly permissions: SessionPermissionsView | null;
+    /** **这个会话的 plan 模式**。没有权限层就没有 plan 模式 */
+    readonly plan: SessionPlanView | null;
+    /**
+     * **这个会话自己那一份**安全网（方案 27），2026-08-15 加。
+     *
+     * 它是这一层唯一够得着「第二个会话能退哪几轮」的地方：runtime 那边
+     * `CheckpointManager` 按 `workDir` 解析相对路径、按 sessionId 分目录，两样都
+     * 跟着会话走。在它之前三条回退端点读的是 `WebRuntimeView.checkpoints`
+     * ——**引导会话那一份**，于是第二个会话被告知「一轮都不能退」，
+     * 而这个进程正握着它的检查点管理器（方案 30 §9.5）。
+     */
+    readonly checkpoints: RuntimeCheckpoints;
+    /** 这个会话绑在哪儿；没绑过 null */
+    readonly workspace: BoundWorkspace | null;
+}
+type CreateSessionResult = {
+    ok: true;
+    live: LiveSessionView;
+    created: boolean;
+}
+/** provider 没起来 —— 这个进程一个会话都跑不了。**没有 detail**，措辞归这一层 */
+ | {
+    ok: false;
+    reason: 'unavailable';
+} | {
+    ok: false;
+    reason: WorkspaceBindFailure;
+    detail: string;
+}
+/** 点名的专家不存在（决定 20 ②）。`detail` 是那个名字，措辞归这一层 */
+ | {
+    ok: false;
+    reason: 'unknown-role';
+    detail: string;
+};
+/**
+ * 「这个会话当初把地盘定在哪儿」—— 从**库里**读回来的那一份决定
+ * （`sessions.workspace_state` / `workspace_root`，会话库 v7）。
+ *
+ * 又一份镜像：runtime 那边它叫 `WorkspaceDecision`，而这一层不许 import core
+ * 也拿不到那个类型。**两态就是全部** —— `null`（没记过）不在这个联合里，
+ * 它是 `revive(decision: … | null)` 那个 `null`。
+ */
+type PersistedWorkspaceDecision = {
+    state: 'bound';
+    root: string;
+} | {
+    state: 'none';
+};
+/**
+ * 复活的四种结局（2026-08-19）。判据全文在 runtime 的 `ReviveSessionOutcome` 上。
+ *
+ * `no-decision` **不是错误**：这个会话没有落盘的工作区决定（v7 之前的老行），
+ * 于是这条路照旧回今天那个 404 —— 见 [revive.ts](./revive.ts)。
+ */
+type ReviveSessionResult = {
+    ok: true;
+    live: LiveSessionView;
+} | {
+    ok: false;
+    reason: 'unavailable';
+} | {
+    ok: false;
+    reason: 'no-decision';
+} | {
+    ok: false;
+    reason: WorkspaceBindFailure;
+    detail: string;
+};
+/** runtime 的 `SessionFactory` 在服务端眼里的样子 */
+interface SessionFactoryView {
+    /** 装配时那个会话的 id */
+    readonly bootstrapId: string;
+    list(): readonly LiveSessionView[];
+    get(sessionId: string): LiveSessionView | null;
+    /**
+     * @param input.lang 绑工作区失败时那句 `detail` 用哪个语言渲染（方案 58 PR-2）。
+     *                   不给 = 进程语言。**只影响 `detail`，`reason` 是契约**
+     */
+    create(input: {
+        workspace: string | null;
+        reuse: boolean;
+        role?: string;
+        lang?: Lang;
+    }): CreateSessionResult;
+    /**
+     * 把一段**库里还在、这个进程手里没有**的会话装起来（2026-08-19）。
+     *
+     * 唯一调用点是 [revive.ts](./revive.ts)（`POST /messages` 上「发第一句话时
+     * 才复活」那一步）。历史**不从这一层递进去** —— 它是 core 那种形状，
+     * 而这个包不许 import core；runtime 那边用会话自己那份 store 读。
+     *
+     * @param input.decision 库里那份决定。**内存里那份优先**（冷却掉的会话
+     *   绑定还在），两份都没有 → `no-decision`。判据全文在 runtime 那一侧
+     */
+    revive(input: {
+        sessionId: string;
+        decision: PersistedWorkspaceDecision | null;
+        lang?: Lang;
+    }): ReviveSessionResult;
+    release(sessionId: string): void;
+}
+/**
+ * 建不出来 → HTTP。
+ *
+ * **503 而不是 500**：服务本身是好的，是它依赖的那样东西（provider 凭据）
+ * 还没就位。两者在界面上读起来完全不同 —— 500 让人去重启服务，
+ * 503 加这句话让人去配 key。
+ */
+declare function unavailableToHttp(lang?: Lang): {
+    status: 503;
+    code: string;
+    message: string;
+};
+
+/**
+ * 会话列表的一行是怎么拼出来的（方案 30 §2.2）。
+ *
+ * ## 两个真源
+ *
+ * ```
+ * Hub（这个进程知道的）        DB（落盘的）
+ *   state / live                title / model / messageCount
+ *   pendingApprovals            costUsd / startedAt / updatedAt
+ *   pendingQuestions            endedAt
+ *   pendingSince
+ *   turnStartedAt / lastFinish
+ *          \                      /
+ *           └──► WireSessionSummary
+ *                     ↑
+ *              workspace 这一格是**两边都能答**的那一个（会话库 v7，
+ *              2026-08-19）—— 唯一一处真的要合，合法在
+ *              `toWireSummaryWorkspace` 上
+ * ```
+ *
+ * 两边都可能单独存在，所以两边都不能当成必要条件：
+ *
+ * - **只有 Hub 有**：会话刚建出来、一条消息都还没落盘。DB 那半全 null，
+ *   但它必须出现在列表里 —— 否则用户新建一个会话，列表上什么都没有
+ * - **只有 DB 有**：上次进程留下的会话，或者本进程里被冷却掉的。它照样要出现，
+ *   `live: false` 说明「Hub 手里没有它」，重新打开时走 `GET /messages` 回放
+ *
+ * ## 排序
+ *
+ * **活着的排前面，然后按最后活动倒序。** 不是纯按时间：正在跑的那个会话是用户
+ * 此刻在意的东西，把它排在一堆历史会话中间等于让人每次都去找。
+ *
+ * ⚠️ 第二段原来是「按开始时间」，2026-08-16 跟着 `WireSessionSummary.updatedAt`
+ * 一起改 —— 理由（选谁进这一页和怎么排这一页必须同一个量）写在 `compareSummaries` 上。
+ */
+
+/**
+ * 落盘会话的一行 —— `@epoch-agent/runtime` 的 `SessionSummary` 结构上满足它。
+ *
+ * 这里再声明一遍而不是 import 那个类型，理由和 `WebRuntimeView` 一样：
+ * 收窄到真正用得到的那几项，于是用例能喂一个几十行的假对象。
+ */
+interface CatalogRow {
+    id: string;
+    title: string;
+    startedAt: number;
+    /**
+     * 最后一次动的时刻。**不可空** —— 落盘的每一行都有它（口径见 runtime 的
+     * `SessionSummary.updatedAt`）；网线上那一格可空，说的是另一件事
+     * （「DB 里查不到这段会话」）。
+     */
+    updatedAt: number;
+    endedAt: number | null;
+    messageCount: number;
+    model: string;
+    costUsd: number;
+    /**
+     * 用户当初对「这段会话在哪儿干活」做的那次决定（会话库 v7，2026-08-19）。
+     * `undefined` = 库里没记过（v7 之前的老行），网线上那是
+     * {@link WireSummaryWorkspace} 的 `unknown` 档。
+     *
+     * ⚠️ **这是 DB 那半唯一一格「Hub 也答得出同一个问题」的字段**，所以它是
+     * 这个文件里唯一一处**两个真源要合**的地方（其余每一格各归各家）。
+     * 合法在 {@link toWireSummary} 的 `workspace` 那一行上。
+     */
+    workspaceState?: 'bound' | 'none';
+    /** `workspaceState === 'bound'` 那一档的目录 */
+    workspaceRoot?: string;
+}
+/** 一条 FTS5 命中 —— runtime 的 `SessionHit` 结构上满足它 */
+interface CatalogHit {
+    sessionId: string;
+    title: string;
+    snippet: string;
+    score: number;
+}
+/** 一次删除的结果 —— runtime 的 `SessionDeletion` 结构上满足它 */
+interface CatalogDeletion {
+    deleted: boolean;
+    checkpointsRemoved: boolean;
+}
+/**
+ * 会话目录 —— server 从 runtime 借的第二片能力（第一片是 `sessionStore`）。
+ *
+ * `@epoch-agent/server` **不许 import `@epoch-agent/core`**，所以「列举 / 检索 /
+ * 改名 / 删除」这些底下全是 `SessionManager` 的动作，只能由 runtime 转出来。
+ * 起不来（SQLite 挂了）时整个是 `null`，列表退化成「只有 Hub 里那几个」。
+ */
+interface SessionCatalog {
+    list(limit?: number): CatalogRow[];
+    get(sessionId: string): CatalogRow | null;
+    rename(sessionId: string, title: string): CatalogRow | null;
+    delete(sessionId: string): Promise<CatalogDeletion>;
+    search(query: string, limit?: number): CatalogHit[];
+}
+
+/**
+ * 设置页的取数、投影与改写 —— `GET` / `POST /api/sessions/:id/settings`
+ * （方案 43 §七）。
+ *
+ * 不在 [api.ts](./api.ts) 里，同 [security.ts](./security.ts) / [capability.ts](./capability.ts)
+ * 的理由：那个文件是「一个端点一个函数」，而这里有一份 runtime 能力的**结构镜像**
+ * 加几段投影。两个端点的处理函数照旧在 `api.ts`（`getSettings` / `writeSetting`），
+ * 这里只管镜像和投影 —— 和 `plan.ts` / `plan-mode.ts` 那对**刻意不同**：
+ * 那两个拆开是因为读写的作用域差一层（会话的一份文档 vs 进程的一个开关），
+ * 而这里读和写答的是同一批键的同一件事，共用同一份镜像，拆开只会让两边各留一半。
+ *
+ * ## 结构镜像，不是 import
+ *
+ * `@epoch-agent/server` **不许 import `@epoch-agent/core`**（`check-layers.mjs`
+ * 是硬闸门），而「每个键赢在哪一层」的真身在 core 的 `config/provenance.ts`。
+ * 所以这里按用得到的字段再声明一遍，`EpochRuntime` **结构上**正好满足 ——
+ * 对不上就是镜像漏了一块，装配那一行当场编译不过。
+ *
+ * ## 这一层的三处编译期闸门
+ *
+ * 1. **镜像上没有的字段，投影里写不出来。** 和 `security.ts` 那四处「刻意漏掉
+ *    一个中文字段」是同一个机制。这一份没有中文候选字段可漏 —— 引擎侧的
+ *    `EffectiveSetting` 上只有 `key` / `value` / `layer` / `chain` /
+ *    `overridable` / `writes`，一个句子都没有。**行标题、单位、说明全在浏览器的
+ *    catalog 里**，key 就是那条点分路径。
+ *
+ *    ⚠️ 写那一半的**失败理由**尤其要盯住这一条：core 那边 `writeSettingValue()`
+ *    产出的是一个**码**（`unwritable-file` 之类），不是一句中文 —— 而它下面那些
+ *    分支里真有中文可拿（`describeJsonError()` 就在隔壁）。哪天有人图省事把
+ *    那句话透出来，中文就上了网线。措辞在两份 catalog 里，见 {@link WRITE_FAILURE}。
+ * 2. **`layer` 钉成 {@link WireSettingLayer} 而不是 `string`。** 同
+ *    `AuditRowView.code` 那一处：引擎那边加一个新层而忘了同步 wire 上这个联合时，
+ *    **装配那一行当场编译不过**。写成 `string` 的话，那个新层会一路发到浏览器，
+ *    然后在徽标上显示成一个查不到文案的空白格 —— 而这一屏存在的全部理由就是
+ *    「告诉用户这个值从哪来」。
+ *
+ *    ⚠️ 这一处和 `RuleView.layer: string`（安全中心那份**如实转发、不归一**）
+ *    刻意不同，别照着那一个改回去：规则表上 `unknown` 是一档真会出现的值，
+ *    而设置页这一份的层集合是闭的（core 的 `SettingLayer` 那个联合）。
+ * 3. **{@link WRITE_FAILURE} 是一张 `Record<SettingWriteFailureCode, …>`。**
+ *    引擎那边加一种写失败而忘了同步，这张表当场编译不过。漏一档的后果是那种失败
+ *    落进 500，而 500 在界面上读作「服务坏了」—— 用户会去重启服务，
+ *    而真相可能只是「你填的 maxTurns 不是正整数」。
+ *
+ * ## 「进程有什么」和「这个会话有什么」——✅ 2026-08-15 这笔账还了
+ *
+ * 这一节原来挂着一条欠账：「等方案 30 §6.3 的多会话工厂落地，③④ 会真的跟着
+ * 工作区变，**那时这里要改**」。工厂那一轮同时改了这里。
+ *
+ * 现在的形状是：`collectSettings(runtime, sessionId)` 把会话 id 一路递给
+ * `SettingsControl.rows(sessionId)` / `write({…, sessionId})`，由 runtime 自己去
+ * `workspaces.of(sessionId)` 取工作区并重算 ③④。**这一层不解释那个 id**，
+ * 只是传话 —— 理由见下一段。
+ *
+ * ## ⚠️ 为什么是「递一个 id」而不是「递工作区和信任判定两样」
+ *
+ * 那笔账里最要紧的一句是这个（原话留着，别删）：
+ *
+ * - 读算错了，代价是界面上标错一个来源层徽标 —— 难看，看得出来，改一行就好
+ * - 写算错了，代价是**往错的目录里写了一个文件**。`SettingWriteTarget.path`
+ *   （④ 写哪个 `.epoch/settings.local.json`）和信任判定（未信任时 ④ 里的标量
+ *   整份被丢）必须属于**同一个工作区**；只把其中一个改成按会话取，表现就是
+ *   「拿 A 工作区的信任判定去决定往 B 工作区写」，而那在任何一屏上都看不出来
+ *
+ * 所以这一层**递的是一个 sessionId，不是拆开的两个参数**：拆开就等于把「这两样
+ * 必须同源」这条不变量交给调用点去守，而这一层有两个调用点（`getSettings` /
+ * `writeSetting`）。递 id 之后，两样由 runtime 侧**同一个函数**一次取齐
+ * （`makeSettingsScope`），「只改了其中一个」这种状态在类型上说不出口。
+ *
+ * 同一句话在 core 的 [config/write.ts](../../core/src/config/write.ts) 文件头
+ * 第四节也记了一份 —— 因为改的人可能从任何一头进来。
+ */
+
+/** core 的 `SettingStep` 在服务端眼里的样子 */
+interface SettingStepView {
+    layer: WireSettingLayer;
+    value?: WireSettingValue;
+}
+/**
+ * core 的 `SettingFutile` 的镜像 —— 「写进去了也不生效」的两种成因。
+ *
+ * `reason` 钉成闭的联合而不是 `string`，判据同下面 `layer` 那一处：界面按这个码
+ * 去查一句**带下一步**的话（`shadowed` → 改写更高那层，`untrusted` → 去信任这个
+ * 目录）。引擎那边加一种成因而忘了同步，装配那一行当场编译不过；写成 `string`
+ * 的话，那个新成因会一路发到浏览器，然后显示成一句空话 —— 而这个字段存在的
+ * 全部理由就是「别让用户白写一次」。
+ */
+interface SettingFutileView {
+    reason: WireSettingFutile['reason'];
+    by?: WireSettingLayer;
+}
+/** core 的 `SettingWriteTarget` 的镜像 */
+interface SettingWriteView {
+    layer: WireSettingWriteLayer;
+    path: string;
+    futile?: SettingFutileView;
+    apply: WireSettingApply;
+}
+/**
+ * runtime 的 `EffectiveSetting` 的镜像。
+ *
+ * 字段一个不多一个不少 —— 引擎侧那个类型上也只有这几样，所以这里没有
+ * 「刻意漏掉的中文字段」那张表（见文件头）。
+ */
+interface SettingRowView {
+    key: string;
+    value?: WireSettingValue;
+    layer: WireSettingLayer;
+    chain: readonly SettingStepView[];
+    overridable: boolean;
+    writes: readonly SettingWriteView[];
+}
+/** runtime 的 `SettingWriteReport` 的镜像。`reason` 是码，不是句子 —— 见文件头第 1 条 */
+type SettingWriteReportView = {
+    ok: true;
+    key: string;
+    layer: WireSettingWriteLayer;
+    path: string;
+    value: WireSettingValue;
+    futile?: SettingFutileView;
+    apply: WireSettingApply;
+} | {
+    ok: false;
+    reason: SettingWriteFailureCode;
+    path?: string;
+};
+/**
+ * 写不成的四种理由 —— **和 core 的 `SettingWriteFailure` 逐字相同**。
+ *
+ * 在这儿再声明一遍而不是 import，是这一层通篇的规矩（server 不许 import core）。
+ * 少一档的后果是 {@link WRITE_FAILURE} 那张表编译不过 —— 那正是要的，
+ * 判据见文件头第 3 条。
+ */
+type SettingWriteFailureCode = 'unknown-key' | 'bad-value' | 'unwritable-file' | 'io';
+/**
+ * `SettingsControl` 的镜像。三样都是函数，因为它们**每次读都是当前值** ——
+ * 今天这份配置在装配后不会变，但把它拍成快照等于替将来那次「运行期改配置」
+ * 做了一个不该在这层做的决定（同 `PermissionsView` 那五个函数）。
+ */
+interface SettingsView {
+    /**
+     * @param sessionId 按**这个会话**绑的工作区算 ③④（2026-08-15）。
+     *   不给 = 引导会话那一份 —— 那是 CLI / TUI 这些单会话宿主唯一的答案。
+     */
+    rows: (sessionId?: string) => readonly SettingRowView[];
+    overridableKeys: () => readonly string[];
+    /**
+     * ⚠️ `sessionId` 在这一支上**不是可选的精细化**，是那条「写哪个文件」和
+     * 「按谁的信任判定」必须同源的不变量的载体。判据见文件头第三节。
+     */
+    write: (input: {
+        key: string;
+        layer: WireSettingWriteLayer;
+        value: unknown;
+        sessionId?: string;
+    }) => SettingWriteReportView;
+}
+/**
+ * server 从 runtime 借的「设置」那一片。`WebRuntimeView` 继承它。
+ *
+ * **不可为 null** —— 它读的是配置本身加两本已经记好的账，没有「起不来」这回事
+ * （`EpochRuntime.settings` 上写着同一句）。
+ */
+interface RuntimeSettings {
+    settings: SettingsView;
+}
+/**
+ * 一次取齐。
+ *
+ * `managedPath` 借的是**安全中心那一份**（`PermissionsControl.managed()`），
+ * 不另算一遍：同一台机器上的同一个文件出现两个说法，是这个仓库反复吃过亏的形状。
+ * 权限层起不来时它是 `null` —— 那时「托管文件在哪」的诚实答案是「说不出来」。
+ *
+ * **`present: false` 时也回 `null`**，虽然那份镜像里 `path` 照旧带着：
+ * 这个字段只在有行赢在 `managed` 时用得上，而那一档必然 `present`。
+ * 发一个不存在的文件路径过去，界面上只会多一个没人点得动的东西。
+ */
+declare function collectSettings(runtime: RuntimeSettings & Pick<RuntimeSecurity, 'permissions'>, 
+/**
+ * 按**这个会话**绑的工作区算 ③④（2026-08-15，多会话工厂）。
+ *
+ * `managedPath` 不跟着它变 —— 企业托管是**机器级**的一个文件（第 ∞ 层），
+ * 它跟工作区无关。同一屏上两个作用域并存不是疏漏，是这两层本来就不同级。
+ */
+sessionId?: string): WireSettingsResponse;
+
+/**
+ * 端点处理函数共用的两个类型 —— **`server` 从 runtime 借了哪片能力**，以及
+ * 一次请求手里握着什么。
+ *
+ * ## 为什么单开一个文件
+ *
+ * 依赖图必须单向、无环（`import/no-cycle` 在 oxlint 里是 error，而「只是个类型」
+ * 在那条规则眼里不算理由）。这两个类型原来住在 [api.ts](./api.ts)，那时所有
+ * 端点也都在那儿，没问题；决定 18 之后端点分成了两处
+ * （`api.ts` 和 [workspace/handlers.ts](./workspace/handlers.ts)），
+ * 留在任何一处都会让另一处反过来 import 它 —— 那就是环。
+ *
+ * 现在的图是：`index → routes → {api, workspace/handlers} → context`。
+ * `api.ts` 和 `index.ts` 各把它们再导出一次，公共 API 的形状不受影响。
+ */
+
+/**
+ * server 从 runtime 借的那一小片能力。
+ *
+ * `@epoch-agent/server` **不许 import `@epoch-agent/core`**（与
+ * examples/electron-minimal 同规矩）：需要什么就让 runtime 转出来。
+ * `sessionStore` 就是为此加到 `EpochRuntime` 上的 —— 回放旧会话要
+ * `loadMessages()`，而那是 core 的 `SessionManager` 才有的东西。
+ */
+interface WebRuntimeView extends RuntimeCapabilities, RuntimeSecurity, RuntimeSettings, RuntimeCommands, RuntimeModel, RuntimeModelCatalog {
+    /**
+     * 正在跑的那个会话。
+     *
+     * ⚠️ **两个形状的交集**，2026-08-15 起：Hub 要的是 `run()`（开一轮），
+     * 换模型那条路要的是 `getHistory()`（这段对话里有没有图片，判据见
+     * [model.ts](./model.js) 的文件头）。写成交集而不是各借一个字段，
+     * 是因为它们说的是**同一个对象** —— 拆成两个字段的话，装配那边可以
+     * 只填其中一个，而「历史是空的」和「没有会话」在闸门那一侧长得一模一样。
+     * `AgentSession` 结构上同时满足两者。
+     */
+    session: (HubSession & ModelSessionFacts) | null;
+    sessionId: string;
+    /**
+     * 多会话工厂（方案 30 §6.3）。`EpochRuntime.sessionFactory` 结构上满足它。
+     *
+     * **不可为 null** —— provider 起不来时它照样在，只是 `create()` 一律回
+     * `unavailable`（那是一句真话，不是一个缺失的能力）。
+     *
+     * ⚠️ 它和上面那个 `session` 的分工：`session` 是**引导会话**，
+     * `createWebServer()` 起来时 `hub.register()` 的就是它；工厂管的是「再开一个」。
+     * 两者指向同一个对象时（`sessionFactory.get(sessionId)`）不是冗余 ——
+     * 前者是 `createWebServer` 的入参形状（嵌入宿主可能只给这一个），
+     * 后者是这一轮新加的能力。
+     *
+     * ## ⚠️ 这里原来还有一个进程级的 `checkpoints`，2026-08-15 **删掉了**
+     *
+     * 它借的是 `EpochRuntime.checkpoints` ——**引导会话那一份**，而三条回退端点
+     * 加 `GET /diff` 都在拿它答任意一个 sessionId。工厂给每个会话各建了一份
+     * （`LiveSessionView.checkpoints`），所以那个字段从此是同一件事的第二个说法，
+     * 而两个说法只在单会话时恰好相等。
+     *
+     * **删掉而不是留着不读**：留着的话下一个写 handler 的人照样够得着它，
+     * 而它编译得过、跑得通、只是答错会话 —— 这一整条 bug 就是这么长出来的
+     * （方案 30 §9.5）。取数一律走 `checkpoints.ts` 的 `checkpointsOf()`。
+     */
+    sessionFactory: SessionFactoryView;
+    config: EpochConfig;
+    /**
+     * artifact 的根目录（`<homeDir>/artifacts`）——`createWebServer()` 不传
+     * `artifactsRoot` 时的缺省值（方案 54 §二）。`EpochRuntime.artifactsRoot`
+     * 结构上正好满足它。
+     *
+     * **拿的是 runtime 报的字符串，不是自己算的**：`server` 不许 import `infra`，
+     * 而这恰好就是它该有的样子 —— 在这边 `join(config.homeDir, 'artifacts')`
+     * 拼一遍等于给同一个目录第二个说法，而两个说法分叉的表现是产物栏点开 404、
+     * 服务日志状态码诊断全部正常。那正是这一节要修的病本身。
+     */
+    artifactsRoot: string;
+    usageScope: 'session' | 'run';
+    /**
+     * 自动压缩那条线（决定 8 的第三个时刻，2026-08-16）。`EpochRuntime.compression`
+     * 结构上正好满足它 —— **对不上就是两边长歪了，装配那一行当场编译不过**。
+     *
+     * 类型直接钉成网线那一份而不是再写一遍三个字段：这份东西原样进
+     * `GET /api/config` 的响应，中间没有任何投影。抄一遍形状的下场同
+     * `sessionStore.loadMessages` 那条 —— 那个端点的载荷从此没被类型检查过。
+     *
+     * ⚠️ **不可为 null。** 三个数这个进程永远答得出（窗口有装配时那个值、阈值有
+     * schema 默认、`auto` 是个布尔），所以「说不出来」这一档不存在。
+     * 判据与「换了模型这三个数变不变」全文在 {@link WireCompressionLine}。
+     */
+    compression: WireCompressionLine;
+    providerInfo: WireProviderSummary | null;
+    readonly tools: readonly WireToolSummary[];
+    diagnosticList: Diagnostic[];
+    /**
+     * 同一批诊断，**用这次请求的语言再说一遍**（方案 58 §2.4）。
+     * `EpochRuntime.diagnosticsIn` 结构上正好满足它。
+     *
+     * ## ⚠️ 可选，而且这是一句真话不是偷懒
+     *
+     * 自己手拼 `WebRuntimeView` 的嵌入宿主（`__tests__/harness.ts` 里那个假 runtime
+     * 就是）交上来的 `diagnosticList` 是一个**已经渲染好的常量数组** —— 它没法被
+     * 再渲染一次，回落到进程语言是那时唯一说得出口的话。
+     *
+     * 所以 `api.ts` 那一行是 `runtime.diagnosticsIn?.(lang) ?? runtime.diagnosticList`：
+     * 给了就按请求语言，没给就照旧。**不给不是错**，`GET /api/config` 照常回。
+     */
+    diagnosticsIn?: (lang: Lang) => Diagnostic[];
+    /**
+     * 会话持久化。起不来时为 null，回放端点退化成空数组而不是 500。
+     *
+     * 返回类型钉成 `WireReplayMessage[]` 而不是 `unknown[]`：`GET /messages` 直接把它
+     * 塞进响应，`unknown[]` 等于这个端点的载荷从来没被类型检查过。runtime 的
+     * `StoredMessage` 结构上正好满足它 —— 对不上就是契约漏了一块，当场编译不过。
+     */
+    sessionStore: {
+        loadMessages(sessionId: string): WireReplayMessage[];
+        /**
+         * 这个会话在工作区里改过哪些文件（方案 42 PR-4）。
+         *
+         * 返回类型钉成 `WireFileChange[]` 同上一条：这份东西直接进
+         * `GET /api/sessions/:id/artifacts` 的响应。runtime 的 `SessionFileChange`
+         * 结构上正好满足它 —— 对不上就是两边长歪了，装配那一行当场编译不过。
+         *
+         * 聚合本身**只能在 runtime 做**：判据是操作类型（core 的 `mapOperationType`）、
+         * 路径抽取走 core 的 `affectedPaths()`，而 server 不许 import core。
+         * 在这边照着 `toolCalls` 自己数一遍，等于给「一次调用会碰哪些文件」
+         * 这个问题第二个答案。
+         */
+        fileChanges(sessionId: string, workDir: string): WireFileChange[];
+        /**
+         * 这段会话已批准的计划正文（方案 35 PR-2）；没有就是 null。
+         *
+         * **只用来答别的会话**：跑在这个进程里的那一个走 `plan.approvedPlan()`
+         * （下一条），理由写在那儿。runtime 的 `SessionStore.loadPlan` 结构上正好
+         * 满足它 —— 那一份不 `ensure()`，查一个不存在的会话回 null 而不是顺手
+         * 建一段空会话，正是这个端点要的语义。
+         */
+        loadPlan(sessionId: string): string | null;
+    } | null;
+    /**
+     * Plan 模式（方案 35）。权限层起不来时为 null ——
+     * 那个模式整个是「临时换一个权限级别」，没有权限层就没有它。
+     *
+     * ⚠️ **这个进程正在跑的那个会话，计划的真源是这儿，不是 SQLite。**
+     * 落盘是 `PlanModeState.setApproved()` 顺手做的（`savePlan` 失败只回 false，
+     * 不抛），而 `--resume` 接回来时又是它把盘上那份 `restore()` 进内存的。
+     * 两者分叉的时候，「模型的 system prompt 里到底挂着哪一份」只有内存这份说得准 ——
+     * 而 `GET .../plan` 那一格问的就是这件事。
+     *
+     * ## 这里原来只借了 `approvedPlan()` 一个方法，2026-08-15 放宽
+     *
+     * 原话是「写那一侧（`enter` / `leave` / `forget`）在这个端点上没有位置，借过来
+     * 就是给浏览器开一条改权限级别的路」。**前半句仍然对**（那是 `GET` 的事），
+     * 后半句被一次人眼验收推翻了：web 上一个进 plan 模式的入口都没有，于是
+     * 「先给我一份计划、别动手」能不能生效取决于模型这一轮愿不愿意调
+     * `enter_plan_mode`（`docs/verify/VERIFY_RECORD-web-loose-ends.md` §4.1）。
+     *
+     * 借的是**两个动词，不是一个级别参数**：`enter` 只能压到 `plan`、`leave` 只能
+     * 恢复成进入前记着的那一档，两者都由 core 的 `PlanModeState` 说了算。所以这条路
+     * 上表达不出「把级别设成 auto」——「给浏览器开一条改权限级别的路」那句担心的事，
+     * 在这个形状下**说不出口**。
+     *
+     * ## ⚠️ `forget()` 照旧不借，而理由 2026-08-15 换了一个
+     *
+     * 原话是「web 上没有任何改级别的入口，借一个没有调用方的方法等于给下一个人
+     * 一个『原来这儿能改级别』的暗示」。**前半句从这一轮起不成立了** ——
+     * `POST /api/sessions/:id/permission` 就是那个入口（决定 20 ③）。
+     *
+     * 但结论没变，而且比原来更硬：**那条路不该从这儿调 `forget()`**。
+     * 「用户自己设级别 ⇒ plan 模式那段区间作废」是引擎内部两件事的耦合，它住在
+     * runtime 的 `PermissionsControl.setLevel()` 第 3 步 —— 服务端手里同时握着
+     * `setLevel` 和 `forget` 的话，「谁负责作废」立刻有两个答案，
+     * 而漏调的那一侧不会红：用户在 plan 模式里换完档一切正常，直到下一次计划
+     * 批准把级别悄悄改回进入前那一档。判据全文在 `PermissionsControl.setLevel`
+     * 的 JSDoc 上。
+     */
+    plan: {
+        approvedPlan(): string | null;
+        /** 现在在不在 plan 模式里 */
+        active(): boolean;
+        /** 进入前的权限级别；不在模式里时 null */
+        from(): string | null;
+        /**
+         * 用户主动进入。**已经在里面时回 `{ok:false}`**，`reason` 是给模型看的那句话
+         * （`server` 不往下发，见 `WirePlanModeResponse`）。重入会把「进入前的级别」
+         * 覆盖成 `plan`，退出时就再也回不去了 —— 那条判据在 core，这一层只是别绕过它
+         */
+        enter(): {
+            ok: boolean;
+            from?: string;
+            reason?: string;
+        };
+        /** 用户主动退出，恢复进入前的级别并返回恢复到哪一档；本来就不在模式里时 null */
+        leave(): string | null;
+    } | null;
+    /**
+     * 会话目录：列举 / 检索 / 改名 / 删除（方案 30 §2.2）。SQLite 起不来时为 null。
+     *
+     * 和 `sessionStore` 一样是「让 runtime 转出来」的产物，`EpochRuntime.sessions`
+     * 结构上正好满足它。为 null 时列表退化成「只有 Hub 里那几个会话」，
+     * 而 DELETE / PATCH 回 503 —— 不是假装成功。
+     */
+    sessions: SessionCatalog | null;
+    /**
+     * 每会话的工作区绑定（[决定 18](../../../design/web-ui/README.md)）。
+     * `EpochRuntime.workspaces` 结构上满足它。
+     *
+     * **不可为 null** —— 底下只有一个 Map 和一个 JSON 文件。引导会话在装配时就绑好了，
+     * 所以 `workspaces.of(runtime.sessionId)` 永远非 null。
+     *
+     * ⚠️ `ApiContext` 上原来有一个 `workDir: string`，是这个字段替掉的。那个是
+     * **进程级**的展示用工作目录 —— 一旦两个会话跑在两个仓库里，它只能是其中一个的，
+     * 而它不说是哪个。留着两个真源的代价不是多一个字段，是它们慢慢长歪。
+     */
+    workspaces: WorkspaceView;
+    /**
+     * 定时任务（方案 45 PR-3）。`EpochRuntime.schedules` 结构上正好满足它 ——
+     * **对不上就是两边长歪了，`cli/src/commands/web.ts` 那一行当场编译不过**。
+     *
+     * ## ⚠️ 不可为 null，而这是一句真话不是省事
+     *
+     * 底下只有一张 SQLite 表和一次平台探测，没有起不来的可能（`build.ts` 上那个
+     * 字段的 JSDoc 写着同一句）。本平台没有 OS 后端时 `capability()` 如实说
+     * `backend: null` —— 那是一个答案，不是一个缺失的能力。
+     *
+     * ## ⚠️ 它是这份视图上**唯一一格不按会话取的能力状态**
+     *
+     * 一条定时任务不属于任何一段会话 —— 它反过来**产出**会话（每次运行落一条
+     * `source='schedule'` 的）。所以那九条端点挂在 `/api/schedules*` 而不是
+     * `/api/sessions/:id/schedules`，判据全文在 [schedule/handlers.ts](./schedule/handlers.js)
+     * 的文件头。别照着 `settings` / `security` 那两片的样子给它加一个 `:id`。
+     *
+     * 借的是**一整片控制面**而不是几个字段，理由和 `sessionFactory` 同类：
+     * 那一片本来就是一个整体（列、建、改、删、跑、算下一次），而拆成散字段之后
+     * 「校验不过就什么都不写」这条不变量会分散到两处去守。
+     */
+    schedules: ScheduleControlView;
+    dispose(): void;
+}
+interface ApiContext {
+    hub: SessionHub;
+    runtime: WebRuntimeView;
+    /** `/api/health` 回的版本号。由 cli 传进来 —— server 不该去猜宿主的版本 */
+    version: string;
+    /** artifacts 目录的**父目录**（即 `~/.epoch/artifacts`） */
+    artifactsRoot: string;
+    /**
+     * 这个服务**绑在回环之外**吗（`--host 0.0.0.0` 那一档）。来自
+     * [bind.ts](./bind.js) 的 `decideBinding().lanExposed` —— `auth.ts` 一直拿它
+     * 放宽 `Host` 白名单，这一格是把同一个事实递给 handler。
+     *
+     * ## ⚠️ **必传，没有默认值**，判据同 `LoadRolesOptions.trusted`
+     *
+     * 给一个 `= false` 的默认参数，就等于「忘了传的人自动获得『我在本机』」——
+     * 而今天读它的那条端点（`POST /api/roles`）正是靠它决定要不要往用户的
+     * `~/.epoch/agents/` 里写一段会进 system prompt 的文字。**fail closed 的
+     * 前提是没人能靠省略拿到 open。**
+     *
+     * 今天的两个消费方：那条端点的 403，和 `GET /api/config` 上原样下发的那一格
+     * （界面据此在按下去之前把话说出来）。完整判据在 protocol 的
+     * `wire-agent-role.ts` 文件头。
+     */
+    lanExposed: boolean;
+}
+
+/**
+ * 鉴权中间件 —— cookie + Origin/Host 校验。
+ *
+ * [方案 20 §6.2 / §6.3](../../../docs/verify/VERIFY_RECORD-20-web.md)。纯函数：进去一个
+ * `WireAuthRequestView`，出来一个 `WireAuthVerdict`，不碰 socket 也不写响应。
+ * 于是这一整套能脱离 HTTP 服务器单测 —— 而它恰恰是最不该「等下次再补测」的部分。
+ *
+ * ## 为什么是 cookie 而不是 `Authorization: Bearer`
+ *
+ * **浏览器原生 `EventSource` 不支持自定义 header**，它的构造器只接受
+ * `withCredentials` 一个选项。而 `/api/events` 是整个方案最重要的端点 ——
+ * Bearer 在这里直接不可用。定案是「URL 里的 token 只用来换一次 cookie」，
+ * 之后所有请求（含 SSE）靠 `HttpOnly` cookie，前端一个
+ * `credentials: 'same-origin'` 完事。
+ *
+ * ## 两道，不是一道
+ *
+ * | 挡什么          | 靠什么               | 为什么另一道挡不住                                                    |
+ * | --------------- | -------------------- | --------------------------------------------------------------------- |
+ * | DNS rebinding   | Origin / Host 校验   | 简单请求（`text/plain` 之类）**不触发 preflight**，CORS 只能拦住攻击者 |
+ * |                 |                      | 读响应，拦不住请求已经执行完了                                        |
+ * | CSRF            | `SameSite=Strict`    | Origin 校验对「浏览器自动附 cookie」无能为力                           |
+ *
+ * 还有第三道是天然的：cookie 没有 `Domain` 属性，因此**只发给用户实际打开的那个
+ * 主机名**。rebinding 攻击页面的请求会带着「evil.com 的 cookie」过来，也就是
+ * 什么都不带 —— 于是即使前两道有疏漏，落点仍然是 401。
+ */
+
+interface AuthGuardOptions {
+    /** 本次启动的随机 token */
+    token: string;
+    /** 服务实际监听的端口。`Host` / `Origin` 的端口必须与它一致 */
+    port: number;
+    /**
+     * 是否绑在回环之外（`--host 0.0.0.0`）。
+     *
+     * 这时候**没法枚举合法主机名**（局域网里那台机器叫什么我们不知道），所以
+     * `Host` 只校验端口 + 与 `Origin` 一致。这不是偷懒，是这个模式下 Origin 白名单
+     * 本身就不成立；真正的防线是上面说的第三道（cookie 只发给用户打开的那个主机名）
+     * 加上「不给 token 就拒绝启动」。
+     */
+    lanExposed: boolean;
+}
+/**
+ * 造一个鉴权判定函数。
+ *
+ * `/api/health` **不过这一关**（验收第 10 条：不带 cookie 时它仍然 200）——
+ * 那是路由层的事，这里不认端点。
+ */
+declare function createAuthGuard(opts: AuthGuardOptions): WireAuthGuard;
+
+/**
+ * 会话登记表 —— Hub 手里「有哪些会话、谁在排队、谁该被冷却」那一半（方案 30 §2.3）。
+ *
+ * 从 [hub.ts](../hub.ts) 里摘出来是因为它是**纯数据结构**：一个 Map、一条
+ * 每会话的消息队列、一条 LRU 冷却策略，没有任何发帧或跑轮次的逻辑。
+ * Hub 那个类刻意不拆（方案 20 §9.6 第 1 条：事件总线 / 状态机 / 审批生命周期
+ * 共享同一份状态），但「谁在表里」不属于那三样中的任何一个。
+ *
+ * ## 两条规矩
+ *
+ * 1. **一个会话同一时刻只有一个 `run()`。** 第二条消息**排队**，不是并发 ——
+ *    `AgentSession` 的历史累积发生在 `run()` 的末尾，两轮并发跑会让历史顺序
+ *    变成不确定的。那不是「偶尔乱序」，是每次重开会话看到的对话都可能不一样。
+ *    不同会话之间**可以**并行，那是多会话的意义所在。
+ * 2. **活跃会话有上限。** 超了就把最久没动过的**空闲**会话冷却掉 ——
+ *    不设上限的话，一个人开 50 个标签页就能把内存吃光，而 `epoch web`
+ *    默认只绑回环不代表它可以随便挂。
+ */
+
+/**
+ * 同时活跃的会话数上限。
+ *
+ * 8 是「一个人能同时盯着的标签页数」的量级 —— 再多也看不过来，而每多一个
+ * 活跃会话就多一份内存里的对话历史。
+ */
+declare const DEFAULT_MAX_ACTIVE_SESSIONS = 8;
+/**
+ * 单个会话最多能排多少条消息。
+ *
+ * 排队是给「手快连发两条」准备的，不是消息队列中间件。超过就直说排满了，
+ * 而不是无声地把请求收下 —— 一个能无限入队的端点等于一个内存放大器：
+ * 每条消息都要在服务端活到轮到它为止。
+ */
+declare const DEFAULT_MAX_QUEUED_MESSAGES = 8;
+
+/**
+ * 信封环形缓冲 —— SSE 续传的唯一数据源。
+ *
+ * [方案 20 §4.1](../../../docs/verify/VERIFY_RECORD-20-web.md)。单独成文件不是为了凑
+ * 结构，是因为「续得上 / 续不上」这条判定有四种边界，而它们全都只需要
+ * `(lastEventId, 缓冲里现有的 seq 区间)` 就能算出来 —— 从 Hub 里摘出来就能被
+ * 直接单测，不用先起一个 HTTP 服务器再断线重连。
+ *
+ * ## 缓冲是**全局**一份，不是 per-session
+ *
+ * 与 `WireEnvelope.seq` 同一条理由（见 wire.ts）：一条 SSE 连接上的 `id:` 行是
+ * 这条流的游标。既然 seq 是全局单调的，缓冲也只能是全局一份，靠 `sessionId`
+ * 把每帧路由回去。per-session 缓冲会让「A 会话刷了 600 条」把 B 会话的可续区间
+ * 也一起顶掉 —— 或者反过来，让全局游标落在一个某会话缓冲里不存在的洞上。
+ *
+ * ## 续不上就说续不上
+ *
+ * `since()` 返回 `null` 表示「这段已经没了」。调用方**必须**回 `stream-reset`
+ * 让前端重拉全量，**不许**把剩下的那半截补给它 —— 那会让页面上出现一段静默
+ * 丢失的对话，而用户永远不知道自己少看了什么。
+ */
+
+/**
+ * 默认容量（方案 20 §4.1 的初值）。
+ *
+ * 512 条大约是一轮中等长度对话的量级（文本增量占绝大多数）。它是「刷新页面还能
+ * 无缝接上」和「内存不无限涨」之间的折中，不是什么魔法数字 —— 真嫌小就调
+ * `SessionHubOptions.ringCapacity`，而不是让缓冲无界。
+ */
+declare const DEFAULT_RING_CAPACITY = 512;
+declare class EnvelopeRing {
+    private readonly capacity;
+    /**
+     * 按 seq 升序、**连续无洞**的一段。
+     *
+     * 连续性是 `since()` 能只靠首尾两个 seq 判定的前提：每个广播帧都让全局计数器
+     * 恰好 +1，所以缓冲里存的一定是 `[latest-size+1, latest]` 这个闭区间。
+     * 哪天出现「某些帧不进缓冲」的需求，这条前提就断了，`since()` 必须跟着改。
+     */
+    private readonly frames;
+    constructor(capacity?: number);
+    /**
+     * 收一帧。**只收广播帧**（`seq >= 1`）。
+     *
+     * 连接级帧（`connected` / `stream-reset`，`seq: 0`）不进来：它们只发给刚接上来
+     * 的那一个连接，进了缓冲就会在下一次续传时被当成历史补给别人。
+     */
+    push(frame: WireEnvelope): void;
+    /** 缓冲里最新那一帧的 seq；空缓冲是 0（= 还没发过任何广播帧） */
+    get latestSeq(): number;
+    /** 缓冲里最老那一帧的 seq；空缓冲是 undefined */
+    get oldestSeq(): number | undefined;
+    /** 现存帧数 */
+    get size(): number;
+    /**
+     * 断点之后的帧。
+     *
+     * @param lastEventId 客户端带上来的 `Last-Event-ID`（它已经收到的最后一个 seq）
+     * @returns 要补发的帧（可能是空数组 = 一条没落下）；
+     *          **`null` 表示续不上**，调用方必须回 `stream-reset`
+     *
+     * 四种边界，全都在这里一次判掉：
+     *
+     * | 情况                        | 返回        | 为什么                                             |
+     * | --------------------------- | ----------- | -------------------------------------------------- |
+     * | `last === latest`           | `[]`        | 断得很干净，一条没落下                             |
+     * | `last > latest`             | `null`      | 游标比我们发过的还新 —— 换了个进程，seq 从头数过了 |
+     * | `last + 1 < oldest`         | `null`      | 中间那段被挤掉了，这就是验收第 4 条                |
+     * | 其余                        | `(last, ∞)` | 正常续传，一条不丢一条不重（验收第 3 条）          |
+     */
+    since(lastEventId: number): WireEnvelope[] | null;
+}
+
+/**
+ * 静态资源 —— artifact 出口（§缺口 2）与 web 产物。
+ *
+ * ## 路径收束是这个文件存在的理由
+ *
+ * [方案 20 §6.4](../../../docs/verify/VERIFY_RECORD-20-web.md) 的三条「绝不」之一：
+ * **artifact 端点绝不直接拼路径**。`GET /api/artifacts/:sid/:name` 的两段都来自
+ * URL，`..` 一穿越就是任意文件读取（验收第 11 条）。
+ *
+ * 这里做四道，缺一不可：
+ *
+ * 1. 拒绝 `name` 里的路径分隔符 —— artifact 是「会话目录里的一个文件」，不是子树
+ * 2. `resolve()` 之后确认仍在 artifacts 目录之内
+ * 3. **`realpath()` 之后再确认一次** —— 第 2 道不看符号链接，而 agent 自己就能
+ *    在 artifact 目录里造一个指向 `~/.ssh` 的链接
+ * 4. 必须是普通文件 —— 否则 `name = '..'` 会解析到目录本身（它确实「在目录之内」）
+ *
+ * ## artifact 的 MIME 与 web 产物的 MIME 是两张表
+ *
+ * 前者是**工具产出的、可能被模型间接控制的**内容：只有图片和音频给 `inline`，
+ * 其余一律 `application/octet-stream` + `attachment`。让浏览器把一个 artifact
+ * 当成 HTML 渲染 = 在本服务的同源里执行任意脚本，而这个源上挂着能操作
+ * agent 的全部 API。后者是我们自己 build 出来的产物，按扩展名正常给。
+ */
+
+/**
+ * 把 `:sid` / `:name` 解析成一个**确定在 artifacts 目录里的普通文件**。
+ *
+ * @returns 绝对路径；任何一道没过就是 `null`（调用方回 404，**绝不读出文件**）
+ */
+declare function resolveArtifactPath(root: string, sessionId: string, name: string): string | null;
+
+/**
+ * 定位随包发出去的 web 前端产物。
+ *
+ * ## 为什么这段代码在 server 而不在 cli
+ *
+ * 到 2026-08-14 之前，产物拷在 `cli/dist/web`，由 `epoch web` 探到之后传给
+ * `createWebServer({ webRoot })`。这让**嵌入宿主**掉进一个不报错的坑：
+ * Electron / VS Code 这类宿主依赖的是 `@epoch-agent/server`（它们要的就是这张
+ * 现成的界面，不想自己拿 REST + SSE 再画一遍），而产物在 cli 包里 ——
+ * 不传 `webRoot` 就是占位页，**服务本身一切正常，日志里一个字都没有**。
+ *
+ * 现在产物随 server 一起发（`scripts/copy-web-assets.mjs`），这里负责在运行期
+ * 找到它。于是 `webRoot` 从「必须传」降级成「想换掉自带界面时才传」。
+ *
+ * ## 两条候选路径
+ *
+ * 产物永远在 `<server 包>/dist/web`，变的只是**本文件相对它的位置**：
+ *
+ *   - 发布形态：整个包被 tsup 打进 `dist/index.js`，`import.meta.url` 指向
+ *     `dist/index.js`，产物是同级的 `web/`
+ *   - 源码形态（vitest、`pnpm epoch:dev` 里被 workspace 链接的那份 src）：
+ *     `import.meta.url` 指向 `src/web-root.ts`，要退一级再进 `dist/web`
+ *
+ * 两条都只依赖**server 包自己的内部布局**，不去猜 monorepo 的相对位置。
+ * 形状与 `cli/src/tui-entry` 的 `resolveTuiEntry()` 一致。
+ *
+ * 探的是 `index.html` 而不是目录：空目录一样存在，而那时静态请求会逐个 404，
+ * 比直接发占位页更难懂。
+ */
+/**
+ * 随包发出去的前端产物目录。
+ *
+ * @param baseDir 本模块所在目录。默认现算，参数只给用例注入
+ * @param exists 存在性判据，默认 `existsSync`。同上
+ * @returns 产物目录；没构建过就是 `undefined`（调用方降级到占位页）
+ */
+declare function defaultWebRoot(baseDir?: string, exists?: (path: string) => boolean): string | undefined;
+
+/**
+ * `GET /api/sessions/:id/diff` 的实现（方案 30 §2.4，作用域按决定 18 收窄到会话）。
+ *
+ * 「这次会话到底改了什么」是用 Web UI 而不是 TUI 的主要理由（屏幕大，能好好看
+ * diff），而在这之前界面上只有**单次 `file_patch`** 的 diff。
+ *
+ * ## 三条来路，按可靠性排
+ *
+ * | source        | 范围                                      | 旧内容                          |
+ * | ------------- | ----------------------------------------- | ------------------------------- |
+ * | `git`         | HEAD → 工作区（已暂存 + 未暂存 + 未跟踪） | `git cat-file blob`（原始字节） |
+ * | `checkpoints` | 本次会话经过文件工具改过的路径            | **没有**（见下）                |
+ * | `none`        | —                                         | —                               |
+ *
+ * 退化到检查点时**拿不到旧内容**：方案 27 的 blob 在
+ * `~/.epoch/checkpoints/<sid>/<turn>/blobs/<hash>` 底下，读它要 core 的
+ * `CheckpointStore`，而 `@epoch-agent/server` 不许 import core。与其拿现状冒充
+ * 旧内容（那会画出一份「什么都没改」的假 diff），不如如实标 `no-snapshot`。
+ * 想补上得让 runtime 转出一个读 blob 的口子 —— 那是另一次改动。
+ *
+ * ## 二进制和大文件
+ *
+ * 前 8000 字节里有 NUL 就当二进制（git 自己的判据），**不试图画 diff**，
+ * 只报字节数（验收第 21 条）。超过 {@link MAX_DIFF_BYTES} 的同样只报字节数 ——
+ * 把一个 40MB 的 minified bundle 塞进 JSON 响应，页面会直接卡死。
+ *
+ * 两侧**任意一侧**触发就整个文件不给内容：只给半边的 diff 会被画成
+ * 「整个文件都是新增的」，比不给更误导。
+ */
+
+/** 单个文件单侧的内容上限（512 KB）。超了只报字节数 */
+declare const MAX_DIFF_BYTES: number;
+/** 一次响应最多几个文件。超了截断并在 `notes` 里说明 —— **不静默截断** */
+declare const MAX_DIFF_FILES = 200;
+/**
+ * 检查点那一侧要的最小能力面 —— runtime 的 `CheckpointControl` 结构上满足它。
+ *
+ * 只要 `list` 和 `preview`：**快照和回退都不该从这里够得着**。这个端点是只读的，
+ * 而 `rewind` 会真的改用户的文件。
+ */
+interface WorkspaceCheckpoints {
+    list(): Promise<ReadonlyArray<{
+        turnIndex: number;
+    }>>;
+    preview(turnIndex: number): Promise<{
+        files: ReadonlyArray<{
+            path: string;
+            action: string;
+        }>;
+        conflicts: ReadonlyArray<{
+            path: string;
+            action: string;
+        }>;
+    } | null>;
+}
+interface WorkspaceDiffOptions {
+    /**
+     * 比较的起点 —— **这个会话绑定的工作区主根**（决定 18），不是服务进程的工作目录。
+     * 不是 git 仓库时它就是 `root`。
+     */
+    workDir: string;
+    /** 非 git 目录时的退路。没有就只能回 `source: 'none'` */
+    checkpoints: WorkspaceCheckpoints | null;
+}
+/**
+ * 算一份工作区 diff。**任何失败都不抛** —— 空视图 + 一句说明就是这个端点的
+ * 正常输出（验收第 22、23 条），而 500 会让界面上只剩一个红叉。
+ */
+declare function collectWorkspaceDiff(opts: WorkspaceDiffOptions): Promise<WireWorkspaceDiffResponse>;
+
+/**
+ * 后台任务的取数与投影 —— `GET /api/sessions/:id/tasks`（方案 36 PR-2 的 Web 那半）。
+ *
+ * 不在 [api.ts](./api.ts) 里，理由和 [capability.ts](./capability.ts) 一样：那个文件
+ * 是「一个端点一个函数」，而这里有一份任务表的**结构镜像**加一段取尾巴的算术 ——
+ * 塞进去会让它变成「一个端点一个函数，外加一段只有这一个端点用得上的窗口计算」。
+ *
+ * ## ✅ `:id` 现在**真的筛选**（2026-08-15 收窄）
+ *
+ * 这一段原来是一条 ⚠️：任务表曾经是 `plugin-terminal/src/background.ts` 里一个
+ * **进程级**的 `Map`，于是同一个进程里两个会话，这个端点回的是**同一批任务**，
+ * 而 `:id` 只起一件事 —— 认门。当时的理由记在那边的文件头上：宿主是**会话**而
+ * 不是一次工具调用，而 plugin 拿不到会话对象。
+ *
+ * 那条理由 2026-08-15 被拆掉了（plugin 拿不到会话*对象*，但一直拿得到
+ * `ToolContext.sessionId`），任务表按会话分了区。于是 `:id` 现在有**两件事**：
+ *
+ * 1. **认门** —— 不存在的会话 404，不能回一份空清单冒充「这个会话没有后台任务」
+ * 2. **筛选** —— 回的是这个会话起的那些，别的会话一条都不在里面
+ *
+ * ### 这是一次判断被验证的记录，所以留着
+ *
+ * 当时那一段末尾写着：「URL 仍然定成会话作用域，与 `capability.ts` 文件头那一条
+ * 同理由：等任务表真按会话分了（那要 plugin 层拿得到会话），改的是**这一个
+ * 文件**，而不是所有客户端的 URL。」
+ *
+ * 这一轮兑现的正是它：URL 一个字没改，`WireTasksResponse` 一个字段没加没减，
+ * web 那边除了撤掉一句不再成立的说明之外没有动过 —— 改的确实只有这一个文件
+ * （加上任务表自己）。**当初把 URL 定成会话作用域，是对的。**
+ *
+ * 反过来那条代价也随之作废：界面上原来必须画一句「这里是整个服务进程的后台任务」
+ * （`web/src/inspector/output.tsx` 的 `web.ui.output.note`），这一轮**如实撤掉**了。
+ *
+ * ## 从 runtime 借道，不 import plugin-terminal
+ *
+ * `@epoch-agent/server` 只许依赖 protocol + runtime（`scripts/check-layers.mjs`
+ * 是硬闸门）。`listBackgroundTasks` / `backgroundTaskOutput` 都是 runtime 转出来的
+ * 那两个口子，见 `runtime/src/index.ts` 末尾那段注释。
+ */
+
+/**
+ * 每个任务最多给多少字节输出。
+ *
+ * 8 个任务跑满时这个端点的上限就是 8 × 这个数 —— 检视面板那一格只有 384px 宽，
+ * 再多也没人读得完，而它们要经过一次 `JSON.stringify` 和一次网络往返。
+ *
+ * 数值跟 `plugin-terminal` 的 `MAX_OUTPUT_CHUNK`（给模型的那个上限）**刻意一致
+ * 但不共用**：那一个的判据是「取一次输出就把上下文塞满」，这一个的判据是
+ * 「一块 384px 的面板」。两个判据将来会各自变，共用一个常量的话，调其中一边
+ * 就会静默改掉另一边。
+ *
+ * ⚠️ 它只是**请求**的窗口大小：`backgroundTaskOutput` 自己还有一道
+ * `MAX_OUTPUT_CHUNK` 的截断，真给到多少以返回值为准（见 {@link toWireTask}）。
+ */
+declare const TASK_TAIL_BYTES: number;
+/**
+ * `taskOutput()` 在服务端眼里的样子（`@epoch-agent/plugin-terminal` 的
+ * `TaskOutputResult`，不能直接 import）。
+ *
+ * 只取用得上的两个字段。`missed` / `hasMore` 不在这里，因为这一层要报的是
+ * {@link WireBackgroundTask.omittedBytes} 那**一个**数，而它由 `nextCursor` 和
+ * `output.length` 算得出来 —— 收窄到两项还顺带让用例喂一个两行的假对象就能跑。
+ */
+interface TaskOutputView {
+    /** 这一段输出 */
+    output: string;
+    /** 下次传回来的游标（绝对偏移）。`起点 + output.length` */
+    nextCursor: number;
+}
+/**
+ * 任务表的只读视图。
+ *
+ * 单开这个接口**只为了用例能注入**：真的那张表是 plugin 里的模块状态，服务端
+ * 用例里起不出一个「跑着的 `pnpm build`」来，于是 running / 已结束 / 被环形缓冲
+ * 截断三种形态一种都摆不出来。默认值 {@link LIVE_TASKS} 接的是真表，路由那一行不传。
+ *
+ * ⚠️ 两个方法**都收 `sessionId`**，而那不是一个可选的精细化：它就是「筛选」
+ * 那一半本身（见文件头）。少一个参数的桩能让「服务端忘了传会话 id」这类错
+ * 在用例里照样绿，而那个错的表现恰好是收窄之前那个毛病原样复发。
+ */
+interface TaskRegistryView {
+    list(sessionId: string): readonly BackgroundTaskInfo[];
+    /**
+     * 取 `since`（绝对偏移）之后的输出。任务不存在时 `undefined`。
+     *
+     * **别的会话的 `id` 也是 `undefined`** —— 任务表那边故意不区分这两种情况
+     * （判据在 `background.ts` 的 `taskIn()`），这一层原样转它的结论。
+     */
+    output(sessionId: string, id: string, since: number): TaskOutputView | undefined;
+}
+/**
+ * 一个任务 → 载荷。
+ *
+ * ## 为什么要自己算 `since` 而不是直接 `output(id, 0)`
+ *
+ * `taskOutput()` 是给模型设计的**增量**读法：从 `since` 往后取一段，一次最多
+ * `MAX_OUTPUT_CHUNK`。传 0 拿到的是缓冲区**开头**那 8KB —— 对一个刷屏的
+ * `pnpm dev` 来说，那是二十分钟前的日志。而后台任务里有价值的永远是最后几行
+ * （构建结果、报错栈），所以这里把游标推到末尾窗口的起点再取。
+ *
+ * `omittedBytes` 取的是**真实起点**（`nextCursor - output.length`）而不是我们
+ * 请求的那个 `since`：两者在两种情况下不同 —— 环形缓冲已经把 `since` 之前的
+ * 丢了（真实起点更靠后），或者取样这一刻任务又长出了新字节。拿请求值去报，
+ * 界面上那句「前面还有 N 字节」就会是一个我们自己编的数。
+ */
+declare function toWireTask(sessionId: string, info: BackgroundTaskInfo, registry: TaskRegistryView): WireBackgroundTask;
+/** 这个会话那一格 → 载荷。**纯函数**，好让三种形态的投影直接断言 */
+declare function collectTasks(sessionId: string, registry: TaskRegistryView): WireTasksResponse;
+
+/**
+ * 定时任务那九条端点（[方案 45](../../../../.agents/plans/45-scheduled-automation-plan.md) PR-3）。
+ *
+ * ```
+ * GET    /api/schedules                              两个 tab 一次取齐
+ * POST   /api/schedules                              建一条
+ * GET    /api/schedules/:id                          一条的全部字段
+ * PATCH  /api/schedules/:id                          改一条（含那个开关）
+ * DELETE /api/schedules/:id                          删一条，同时撤 OS 注册
+ * GET    /api/schedules/:id/runs                     这条任务的运行记录
+ * POST   /api/schedules/:id/run                      「先跑一次」
+ * POST   /api/schedules/:id/fix                      把欠条变成下一次的授权
+ * GET    /api/schedules/:id/runs/:runId/recording    那一次的录像
+ * ```
+ *
+ * ## ⚠️ 这一组**没有 `:sessionId`**，而且不许有
+ *
+ * 一条定时任务不属于任何一段会话 —— 它反过来**产出**会话（每次运行落一条
+ * `source='schedule'` 的）。挂到 `/sessions/:id/` 底下会得到一组名字是会话级、
+ * 行为是进程级的端点，比不一致更坏。判据同 `POST /api/mcp/:name/reconnect`
+ * 和 `GET /api/workspaces/dirs` 那两条（`routes.ts` 里各有一段 ⚠️）。
+ *
+ * ## 六条写端点全是非 GET，一条都不许写成带查询串的 GET
+ *
+ * `auth.ts` 的 Origin 校验**只在非安全方法上要求**。而这一组里最该守住 CSRF 的
+ * 不是「改一个字段」，是 `POST /run`：它会在用户机器上**真的起一次 agent 运行**，
+ * 按那条任务自己的清单不经确认地跑命令。写成 `GET /run?id=…` 等于任何一个页面
+ * 都能替用户点那个按钮。
+ *
+ * ## 校验不过是 200 + `issues`，不是 400
+ *
+ * 判据在 `WireScheduleSaveResponse` 上：请求本身完全合法，是表单里某几格填错了，
+ * 而那几格要在表单上逐格标红。这一层的 400 只留给「这个 JSON 读不懂」
+ * （`body.ts` 那一层）。
+ */
+
+/**
+ * 一份录像最多回多少帧。
+ *
+ * 一次跑飞的运行能写出几万帧（每个 `text-delta` 一帧），整份推给浏览器会让
+ * 那个标签页卡死。超了就截断 + `truncated: true` —— **必须说出来**，
+ * 判据同 `WireSkillBodyResponse.truncated`：一份看起来完整、其实少了后半截的
+ * 回放，比一句「太长了没给全」坏得多。
+ */
+declare const MAX_RECORDING_FRAMES = 4000;
+/**
+ * 库里那条任务 → 网线上那一行。
+ *
+ * 两格算出来的东西都在这一层算：
+ *
+ * - `nextRunAt` 走 core 的那份日期算术（runtime 转出来的），**不在浏览器里抄**；
+ * - `allowlistApplies` 问 `needsAllowlist()`，**不在浏览器里判第二遍** ——
+ *   「只读」和「跳过全部检查」两档下都是 `false`，而理由正好相反，
+ *   一个布尔在这儿就够（界面对两档说的话由 `permission` 那一格决定）。
+ */
+declare function toWireRow(control: ScheduleControlView, def: ScheduleDefinition): WireScheduleRow;
+
+/**
+ * @epoch-agent/server —— 本地 HTTP + SSE 服务端
+ *
+ * ✅ 做：`node:http` 手写路由、SessionHub 扇出、SSE 续传、cookie 鉴权 + Origin 校验
+ * ❌ 不做：
+ *   - **不许 import `@epoch-agent/core`**。与 examples/electron-minimal 同规矩：
+ *     需要什么能力就让 runtime 转出来，这里出现 core 就是接口设计漏了一块
+ *     （`pnpm check:layers` 会红）
+ *   - **不许写 `console`**。它被宿主嵌着跑，打印 URL 是宿主的事
+ *     （在 `LIBRARY_DIRS` 里，同样是 `check:layers` 会红）。宿主有两类：
+ *     仓库里的 cli（`epoch web`），和仓库外**要现成界面**的嵌入方
+ *     （Electron / VS Code，见 docs/EMBEDDING.md §9）—— 后者也是
+ *     `dist/web` 随本包发的原因，见 web-root.ts
+ *   - 不引第三方 HTTP 框架（方案 20 §9.6 第 3 条）
+ *
+ * 契约在 `@epoch-agent/protocol` 的 `wire.ts`：信封 `WireEnvelope`、Hub 事件
+ * `WireHubEvent`、鉴权 `WireAuthGuard`。fixture 在仓库根的 `fixtures/wire/`，
+ * `__tests__/wire-fixtures.test.ts` 断言本服务产出的信封序列逐条等于它。
+ *
+ * ## 端口被占了怎么办（方案 20 §12 留给 Track A 的那条）
+ *
+ * **报错退出，不自动找下一个可用端口。** 自动顺延意味着每次启动的 URL 都可能不同：
+ * 用户收藏的那个标签页会连到一个「不是这次这个」的服务上（或者一个别的程序），
+ * 而两边都不会报错。`--port` 本来就是给这种情况准备的。
+ */
+
+/**
+ * `createWebServer()` 的返回值 —— cli 的 `epoch web` 拿到的就是这个。
+ *
+ * `close()` 必须是幂等的（Ctrl+C 和进程退出钩子会各调一次），
+ * `url` 含首屏换 cookie 的 `?token=` —— 打给用户看没问题（那是他自己的终端），
+ * 但**不要写进日志文件或遥测**。
+ */
+interface EpochWebServer {
+    /** 带 `?token=` 的首屏地址。给浏览器打开用 */
+    url: string;
+    /** 实际监听的端口（`--port 0` 时由内核分配） */
+    port: number;
+    /** 实际监听的地址 */
+    host: string;
+    /**
+     * 本次生效的 token —— 宿主没传 `token` 时由这里随机生成，**返回来是唯一出口**。
+     *
+     * 不返回的话宿主只能去正则 `url` 里的 `?token=` 才能自己发一条带鉴权的请求，
+     * 那等于把 URL 的拼法变成公开契约。同样**不要写进日志文件或遥测**。
+     */
+    token: string;
+    /**
+     * 这次实际在发的前端产物目录。`undefined` = 没找到，发的是占位页。
+     *
+     * 返回它是为了让宿主**能把这件事说出来**：占位页和真界面都是 200，
+     * 服务日志里一个字都没有，不返回的话「装出来的界面永远是占位页」这种事
+     * 只能靠人眼发现（这正是 2026-08-14 之前嵌入宿主踩的那个坑，
+     * 见 [web-root.ts](./web-root.ts)）。
+     */
+    webRoot?: string;
+    /**
+     * 同进程旁听事件流（方案 54 §三）。**不是一条连接。**
+     *
+     * 不给这个出口的话，嵌入宿主要感知「agent 在跑 / 卡在审批上 / 刚做完」，唯一的
+     * 办法是**从自己的 Node 里连一条 `GET /api/events`** —— 那条连接在 Hub 眼里和一个
+     * 开着的浏览器标签页没有区别，于是宿主为了点亮一枚状态灯，把引擎的两条不变量
+     * 一起废掉了：**全部连接断开 30 秒后放弃挂起的审批 + 中止在跑的回合**，以及
+     * **全断之后丢掉排队的消息**。那不是「接得不方便」，那是我们的行为在嵌入形态下
+     * 和文档写的不一样，**而宿主没有任何办法知道**。所以这里给的是一条明确不算人的路：
+     *
+     * - 不计入连接数、不影响上面那两条判定
+     * - 没有 `Last-Event-ID` / 补帧（同进程的函数调用不会丢帧）
+     * - 收到的是和 SSE 上**同一个** `WireEnvelope`（`seq` 都一样），
+     *   但没有连接级的 `connected` / `stream-reset` —— 那两帧描述的是「这条连接」
+     *
+     * 「四种状态怎么映射到宿主窗口上的一枚灯」是宿主的产品决定，我们不替它做。
+     *
+     * @returns 取消旁听。**幂等**。`close()` 之后所有旁听自动失效
+     */
+    observe(sink: (frame: WireEnvelope) => void): () => void;
+    /**
+     * 当前所有会话在 Hub 侧的状态快照 —— 等价于 `GET /api/sessions` 的实时那一半，
+     * 不过 HTTP。
+     *
+     * **光有 `observe()` 不够，所以它不是顺手加的。** SSE 上的 `session-state`
+     * 只在状态**真的变了**的时候发（`hub.ts` 的 `setState`：不变就不发，否则并行审批
+     * 会刷出一串重复状态）。于是一个刚起来的宿主在下一次状态变化之前什么都不知道 ——
+     * 它会把一个正在跑的回合画成 idle，一直画到那一轮结束。
+     * **首屏要的是快照，之后才是增量**，两个都得有。
+     */
+    snapshot(): HubSessionState[];
+    /** 幂等：断开所有 SSE 连接 + 关监听 + `dispose()` 运行时 */
+    close(): Promise<void>;
+}
+interface CreateWebServerOptions {
+    /** `buildRuntime()` 的产物。`EpochRuntime` 结构上满足 `WebRuntimeView` */
+    runtime: WebRuntimeView;
+    /** `/api/health` 回的版本号 —— server 不该去猜宿主的版本 */
+    version: string;
+    /**
+     * artifacts 的**父目录**（`<homeDir>/artifacts`）。
+     *
+     * **缺省是 `runtime.artifactsRoot`，也就是引擎这次真的往里写产物的那个目录** ——
+     * 所以正常宿主一个字都不用填（方案 54 §二）。
+     *
+     * 在这条缺省存在之前，这个选项是**全文档最容易静默出错的一处**：宿主必须
+     * 自己算一个路径，并保证它和引擎算的逐字符相同，而它没有任何办法验证。
+     * 分叉的表现是产物栏点开 404 —— 而服务、日志、状态码、诊断全部正常，一个字不报。
+     *
+     * 传它只有一种正当理由：宿主真的想让界面从别处读（比如把产物挪到了另一个卷）。
+     * **那时对不上就是宿主自己的选择，不再是我们的缺省害的。**
+     * server 不许 import infra，所以这个字符串只能由 runtime 报。
+     */
+    artifactsRoot?: string;
+    /** `--host`，缺省 `127.0.0.1` */
+    host?: string;
+    /** `--port`，缺省 4400。`0` = 内核分配 */
+    port?: number;
+    /** `--token`。非回环绑定时必填，否则**拒绝启动** */
+    token?: string;
+    /**
+     * web 构建产物目录。**缺省是本包自带的那份**（`<server 包>/dist/web`，
+     * 见 [web-root.ts](./web-root.ts)），所以想要第一方界面的宿主什么都不用传。
+     *
+     * 只有两种情况需要显式给：自带的产物不合用（宿主要发自己那套前端），
+     * 或者开发时想指到 vite 的输出目录。
+     */
+    webRoot?: string;
+    /**
+     * 界面的首屏初值 —— 主题和语言（方案 54 §七）。
+     *
+     * 给了就拼进 {@link EpochWebServer.url}（`?theme=dark&lang=zh`），界面在第一帧
+     * 之前读它、写进自己的 `localStorage` 再按现有逻辑走。**不给就一个参数都不拼**，
+     * URL 和以前逐字节相同。
+     *
+     * 存在的理由是宿主今天**只能抄一个我们没承诺的 key 名**：那两个 key
+     * （`epoch.theme` / `epoch.lang`）是 `@epoch-agent/web` 的导出常量，而那个包是
+     * `private: true` —— 宿主 import 不到，只能给 webview 挂一个 preload、
+     * 在页面脚本之前手写 localStorage。能用，但它依赖的是一个我们随时能改的名字。
+     *
+     * ⚠️ **是初值，不是锁**，判据见 {@link UiPreset}。
+     */
+    ui?: UiPreset;
+    /** 环形缓冲容量，缺省 512 */
+    ringCapacity?: number;
+    /**
+     * 同时活跃的会话数上限，缺省 8（方案 30 §2.3）。
+     *
+     * 转出来是因为它**这一轮才真的会被碰到**：在多会话工厂之前活跃会话恒为 1，
+     * 这个旋钮除了用例没人用得上。超了就把最久没动过的**空闲**会话冷却掉 ——
+     * 它从此不在 Hub 里，但仍然在会话列表里（列表的另一半来自 DB），
+     * 重新打开时历史走 `GET /api/sessions/:id/messages` 回放。
+     */
+    maxActiveSessions?: number;
+    /** 全部连接断开之后的宽限期，缺省 30 秒 */
+    idleGraceMs?: number;
+    /** SSE 心跳间隔，缺省 15 秒 */
+    heartbeatMs?: number;
+    /** 时钟注入，缺省 `Date.now`。用例靠它对齐 fixture 的 `ts` */
+    clock?: () => number;
+}
+type CreateWebServerResult = {
+    ok: true;
+    server: EpochWebServer;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * 起服务。
+ *
+ * 失败一律走返回值不走异常：两种失败（绑定策略不允许 / 端口起不来）都是
+ * 「要打给用户看的一句话」，而不是编程错误 —— 让调用方去 try/catch 一个
+ * 预期之内的结果只会让 cli 那边写得更难看。
+ */
+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 };