@epoch-agent/server 0.20.1 → 0.22.0

package/README.md

@@ -86,6 +86,7 @@ tarball 里真的有那些字节。
 
 | 端点                                                       | 说明                                                                                   |
 | ---------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| `POST   /api/appearance`                                   | `{theme?, lang?}` → 记下界面外观（**进程级、无会话**，见下）                           |
 | `GET    /api/health`                                       | **不鉴权**，只回 `{ok, version}`                                                       |
 | `GET    /api/config`                                       | 模型 / 权限级别 / 工作区 / 品牌 / 启动诊断 / 绑没绑在回环之外（`?lang=` 见下）         |
 | `GET    /api/events`                                       | SSE，负载是 `WireEnvelope`                                                             |
@@ -178,6 +179,41 @@ tarball 里真的有那些字节。
 清单以外还要知道的六件事（鉴权两段式、`Origin` 校验、`seq` 与 `Last-Event-ID` 续传、
 断连不等于人走了）写在 [docs/EMBEDDING.md §10](../../docs/EMBEDDING.md)。
 
+### `POST /api/appearance` —— 界面外观偏好（2026-09-29）
+
+```
+POST /api/appearance    {theme?: 'system'|'light'|'dark', lang?: 'system'|'zh'|'en'}
+                     →  200 {ok: true, theme?, lang?}   ← 盘上现在那一份
+```
+
+**它治的是「用户选的外观活不过一次进程重启」**：主题和语言原来只写在浏览器的
+`localStorage` 里，而它**按 origin 隔离** —— 嵌入宿主用 `port: 0` 时每次启动都是
+一个新的 `http://127.0.0.1:<新端口>`，上次那份读不到（升级必然重启一次，
+所以它在升级那里最显眼）。这一条把偏好落进 `~/.epoch/appearance.json`，
+下一次启动由 `createWebServer()` 拼进首屏 URL（`?theme=&lang=`）。
+
+四条边界：
+
+- **无会话，而且只能是 POST。** 路径上没有 `:sessionId`（判据同
+  `PUT /api/last-session`：落点是**进程级**文件）；非 GET 是硬要求 ——
+  `auth.ts` 的 Origin 校验只在非安全方法上要求，而这条路会往用户磁盘写文件。
+- **载荷是补丁，所以不是 PUT。** 缺席的键 = **那一格别动**，不是「设成跟随系统」；
+  同一个 URL 上提交 `{theme}` 和 `{lang}` 得到两种结果，那不是幂等的全量替换。
+- **读没有端点。** 读那条路**必须发生在第一帧之前**，所以它是 `server.url` 上的
+  两个 query 参数，而服务端拼的是「盘上那份压过 `ui` 初值」之后的结果。
+  ⚠️ 每次首屏导航（那次换 cookie 的 303）都会按**当下**盘上那份重盖一遍 ——
+  `server.url` 是启动那一刻的常量，而盘上那份会变。
+- **认不出来的值回 400，一个字节都不落盘。** 值域的判定在消费侧
+  （写入口 = 这里，读出口 = `storedUiPreset` 和内联脚本），存储那一层只做持久化 ——
+  手改出来的坏值读得出来、用不上、也不报错。第一方界面**不看看回执**
+  （它那一发是 fire-and-forget，写不进去就静默降级），那两档状态码是给排查的人
+  和自己画前端的宿主的：503 = 宿主没接这条路，500 = 写盘失败（带原话）。
+
+宿主那一侧的完整语义（`ui` 的准确含义、那张三档对照表、为什么偏好不落在
+`config.yaml`）在 [docs/EMBEDDING.md §9](../../docs/EMBEDDING.md)；
+存储本体和四条「为什么不塞进 `display.*`」的判据在
+[core/src/appearance.ts](../core/src/appearance.ts)。
+
 ### `/api/host/*` —— 宿主把一句话送进输入框（2026-09-28）
 
 ```
@@ -1658,14 +1694,21 @@ role 上。
 3. **[bind.ts](src/bind.ts) 那条「非回环不给 token 就拒绝启动」不放松**，也不为这个
    字段开例外
 
-**绑定后不给改**（决定 18）：中途换地盘会让前面那些工具调用里的 `./src/a.ts`
+**开过工之后不给改**（决定 18）：中途换地盘会让前面那些工具调用里的 `./src/a.ts`
 指向另一个目录，而记录里没有任何地方写着从哪条开始换的。
 
-⚠️ **所以「换一个工作区」的唯一形态是新建一个会话** —— 2026-08-15 多会话工厂落地
-之后，`POST /api/sessions` 带另一个目录**不再是 409 `workspace-locked`**，而是
-建一个绑在那儿的新会话（见上面那张表）。那个码没有作废：它守的仍然是同一条规矩，
-只是这条路上再也走不到它了，真正会撞到它的是 runtime 那一层
-（`SessionWorkspaces.bind`）。
+⚠️ **2026-09-30：这条锁的边界从「绑过没有」挪到了「开过工没有」。** 判据就是上面
+那句话自己 —— 还没开过工就**一条工具调用都没有**，锁在那段窗口里没有对象。
+所以「挑一个 → 想换一个」在一段还没发过消息的会话上是允许的，而开过工之后照旧
+一个字不能改。判据只有一份（`WorkspaceControl.canChange`），三处共用：runtime 里
+`bind()` 那道 `locked`、这条端点那道 409 闸、以及网线上给界面的 `changeable`。
+三处各判一次的表现是「界面画着一张 picker、按下去 409」。
+
+⚠️ **所以「换一个工作区」的唯一形态**（开过工之后）**仍然是新建一个会话**
+—— 2026-08-15 多会话工厂落地之后，`POST /api/sessions` 带另一个目录**不再是
+409 `workspace-locked`**，而是建一个绑在那儿的新会话（见上面那张表）。那个码没有
+作废：它守的仍然是同一条规矩，只是这条路上再也走不到它了，真正会撞到它的是
+runtime 那一层（`SessionWorkspaces.bind`）和这条端点那个 409 闸。
 
 ### 「这个会话绑在哪儿」是一条独立端点（2026-08-15）
 
@@ -1685,6 +1728,11 @@ role 上。
 | 建好了、**还没选**地盘         | 200 + `{binding:{state:'unbound'}}`  |
 | 这个进程手里**没有**这段会话   | 409 `not-live-session`               |
 
+⚠️ **`bound` / `none` 还各带一格 `changeable`**（2026-09-30）：这次决定还能不能改，
+判据只有一条 —— 这段会话**开过工没有**（和上面那道 409 闸、以及 runtime 里
+`bind()` 那道 `locked` 读的是同一个方法，见下面 POST 那一节）。`unbound` 不带它：
+那一档还没有决定，一直可挑。这一格是**界面画菜单还是画 diff 门**的依据。
+
 第 3 行和第 5 行是这条端点原本全部的难点。绑定活在进程内存里、**不落盘**，所以上
 一个进程留下的会话在 `workspaces.of()` 那儿也是 `null` —— 和「这个会话真的不使用
 工作区」在数据上一模一样。合成一个的表现很具体：一段昨天在某个仓库里干了一整轮活
@@ -1771,27 +1819,35 @@ body: {root: '<绝对路径>'} | {none: true}
 「宿主看得见的那一面」上，路径校验、信任闸门、`locked` 幂等三样一个字都没动 ——
 这条端点只是第二个调用点。
 
-**只有 `unbound` 收得动：**
+**只有 `unbound`，或者还没开过工的已定会话，收得动：**
+
+| 这个会话此刻                     | 结果                                                  |
+| -------------------------------- | ----------------------------------------------------- |
+| `unbound` 且 idle                | 绑 / 转 `none`，200 回**改完之后**的整份 binding      |
+| `unbound` 但在跑                 | 409 `busy` —— 等这一轮结束再挑（2026-08-20）          |
+| `bound` / `none`，**还没开过工** | 同上第一行 —— 换一个「还没被任何工具调用用上的选择」  |
+| `bound` / `none`，**开过工了**   | 409 `workspace-locked` —— 决定 18「开过工之后不给改」 |
+| 上面任一档，但这一轮在跑         | 409 `busy`                                            |
 
-| 这个会话此刻      | 结果                                                 |
-| ----------------- | ---------------------------------------------------- |
-| `unbound` 且 idle | 绑 / 转 `none`，200 回**改完之后**的整份 binding     |
-| `unbound` 但在跑  | 409 `busy` —— 等这一轮结束再挑（2026-08-20）         |
-| `bound`           | 409 `workspace-locked` —— 决定 18「绑定后不给改」    |
-| `none`            | 409 `workspace-locked` —— **「不使用」也是一次决定** |
+⚠️ 第三行 2026-09-30 才有（判据在 `WorkspaceControl.canChange` 上，读的是会话库
+——「这段会话开过工没有」）。**它不是放宽**：那条锁要护的是「前面那些工具调用里的
+相对路径」，而那段窗口里一条都没有。
 
-⚠️ 第二行和另外两行**不是同一句话**，别合并：`workspace-locked` 说的是「已经定了，
-永远不能改」（下一步是新建会话），`busy` 说的是「现在不行，等一下」（下一步还是
-同一个按钮）。合成一句的话，用户会去建一个他不需要的会话。它是迟绑那一轮
-（2026-08-20）补的：绑定这一下现在会真的改引擎脚下的目录，而一次 `run()` 底下可能有
+⚠️ `workspace-locked` 和 `busy` **不是同一句话**，别合并：前者说的是「已经定了，
+不能改」（下一步是新建会话），后者说的是「现在不行，等一下」（下一步还是
+同一个按钮）。合成一句的话，用户会去建一个他不需要的会话。`busy` 是迟绑那一轮
+（2026-08-20）补的：绑定这一下会真的改引擎脚下的目录，而一次 `run()` 底下可能有
 二十次工具调用 —— 半路换根等于同一轮里前几次按 A、后几次按 B 解析相对路径，而历史里
 那条 `[系统]` 留痕是**轮次开始时**插的，盖不住这一档。响应头带 `X-Epoch-Turn-State`，
 和 `POST /messages` 那条 409 同一对形状。
 
-⚠️ 第三行是这条端点唯一一处会被读错的地方：`none` 看着像「还空着」，但它是用户
-**明确按过**的一档（决定 18 侧栏「任务」组的成员）。让它还能被改，等于给一段说过
-「不要地盘」的会话补一个地盘 —— 而它前面那些工具调用里的相对路径已经按服务进程的
-启动目录解析过了，判据逐字同 `bound` 那一行。**不做 `PATCH`，也不做换绑。**
+⚠️ `none` 那一档是这条端点唯一一处会被读错的地方：它看着像「还空着」，但它是用户
+**明确按过**的一档（决定 18 侧栏「任务」组的成员）。**开过工之后**让它还能被改，
+等于给一段说过「不要地盘」的会话补一个地盘 —— 而它前面那些工具调用里的相对路径
+已经按服务进程的启动目录解析过了，判据逐字同 `bound` 那一行。而还没开过工时它和
+`bound` 一样放行：底栏那张菜单里「不使用工作区」和「换一个目录」本来就是同一层的
+两项，一项能改、另一项点了没反应，用户看到的是「菜单里有一项坏了」。
+**不做 `PATCH`，也不做换绑** —— 这条端点只是在那个窗口里允许「改一个还没用上的选择」。
 
 请求体**两支恰好一支**：两支都给 / 都不给一律 400 `bad-workspace`。「两支都给」
 不许挑一支执行 —— 那两支通向的是两段完全不同的会话。**这一层一次路径校验都不做**

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { Lang, AgentRoleSource, WireRoleRemoveFailure, WireSkillImportFailure, WireSkillImportForm, WireSkillRemoveFailure, WireSkillStageFailure, WireProjectInventory, WireCapabilitiesResponse, WireSkillBodyResponse, EpochUserContent, AgentEvent, WireEnvelope, CustomCommandDef, ExpandedCommand, ModelRef, SetSelectionResult, WireCommandExpansion, WireCustomCommand, WireGoalPhase, WireGoalRefusal, WireTurnState, WireSessionFinish, ApprovalOutcome, QuestionAnswer, WireHubEvent, SessionSurfaceView, WireSessionReference, WireFileReference, ProviderType, ModelSelectionOrigin, WireModelCaveat, WireModelRejection, ContextBreakdown, PermissionLevel, WirePermissionRememberFailure, WirePluginSourceType, WirePluginVisibility, WirePluginStatus, WirePluginRefuseReason, WirePluginUploadForm, WirePluginUploadFieldName, WirePluginUploadFields, WirePluginEntry, WireModelSource, WireModelProbeStatus, ScheduleDefinition, ScheduleRun, ScheduleBackendKind, OperationType, ScheduleTrigger, WireScheduleIssue, ScheduleRunStatus, TrustLevel, WireSandboxReason, WireAuditOutcome, WireAuditCode, WireCachedApproval, WireCachedDecision, WireToolVerdict, WireToolGateAxis, WireSecurityResponse, WireRewindScope, WireRewindRequest, WireCheckpointSummary, WireRewindPreview, WireRewindResponse, ActiveAgentRole, WireSettingValue, WireSettingLayer, WireSettingWriteLayer, WireSettingFutile, WireSettingApply, WireSettingValueKind, WireSettingsResponse, EpochConfig, TokenUsage, WireCompressionLine, WireProviderSummary, WireToolSummary, Diagnostic, WireReplayMessage, WireFileChange, WireAuthGuard, WireWorkspaceDiffResponse, BackgroundTaskInfo, WireTasksResponse, WireBackgroundTask, WireScheduleRow } from '@epoch-agent/protocol';
-import { SerializableApprovalRequest, SerializableQuestionRequest, RunningSchedule, ApprovalRevokeResult, LevelChangeResult, LastOpenSessionControl, WorkspaceFilesView } from '@epoch-agent/runtime';
+import { AppearanceTheme, AppearanceLang, Lang, AgentRoleSource, WireRoleRemoveFailure, WireSkillImportFailure, WireSkillImportForm, WireSkillRemoveFailure, WireSkillStageFailure, WireProjectInventory, WireCapabilitiesResponse, WireSkillBodyResponse, EpochUserContent, AgentEvent, WireEnvelope, CustomCommandDef, ExpandedCommand, ModelRef, SetSelectionResult, WireCommandExpansion, WireCustomCommand, WireGoalPhase, WireGoalRefusal, WireTurnState, WireSessionFinish, ApprovalOutcome, QuestionAnswer, WireHubEvent, SessionSurfaceView, WireSessionReference, WireFileReference, ProviderType, ModelSelectionOrigin, WireModelCaveat, WireModelRejection, ContextBreakdown, PermissionLevel, WirePermissionRememberFailure, WirePluginSourceType, WirePluginVisibility, WirePluginStatus, WirePluginRefuseReason, WirePluginUploadForm, WirePluginUploadFieldName, WirePluginUploadFields, WirePluginEntry, WireModelSource, WireModelProbeStatus, ScheduleDefinition, ScheduleRun, ScheduleBackendKind, OperationType, ScheduleTrigger, WireScheduleIssue, ScheduleRunStatus, TrustLevel, WireSandboxReason, WireAuditOutcome, WireAuditCode, WireCachedApproval, WireCachedDecision, WireToolVerdict, WireToolGateAxis, WireSecurityResponse, WireRewindScope, WireRewindRequest, WireCheckpointSummary, WireRewindPreview, WireRewindResponse, ActiveAgentRole, WireSettingValue, WireSettingLayer, WireSettingWriteLayer, WireSettingFutile, WireSettingApply, WireSettingValueKind, WireSettingsResponse, EpochConfig, TokenUsage, WireCompressionLine, WireProviderSummary, WireToolSummary, Diagnostic, WireReplayMessage, WireFileChange, WireAuthGuard, WireWorkspaceDiffResponse, BackgroundTaskInfo, WireTasksResponse, WireBackgroundTask, WireScheduleRow } from '@epoch-agent/protocol';
+import { SerializableApprovalRequest, SerializableQuestionRequest, RunningSchedule, ApprovalRevokeResult, LevelChangeResult, LastOpenSessionControl, AppearanceControl, WorkspaceFilesView } from '@epoch-agent/runtime';
 import { ServerResponse } from 'node:http';
 
 /**
@@ -15,6 +15,7 @@ import { ServerResponse } from 'node:http';
  * 整个文件是纯函数 —— 判定不能藏在 CLI 的 action 回调里，那种地方写不了用例，
  * 而这条判定恰恰是验收第 12 / 13 条。
  */
+
 /** 默认端口。4400 是方案里举的那个，没被常见服务占用 */
 declare const DEFAULT_WEB_PORT = 4400;
 /** 默认监听地址 —— 只有回环。改这个默认值需要重读 §6.1 */
@@ -68,10 +69,15 @@ declare const UI_LANG_PARAM = "lang";
  *
  * `'system'` 不是「不给」—— 它是明确的第三档（跟随系统），和不传这个字段
  * （用户上次自己选的那个还算数）是两件事。
+ *
+ * ⚠️ **2026-09-29 起它从 protocol 派生**（`AppearanceTheme`），不再在这里
+ * 自己写一份字面量：同一个值域现在有四个消费者（界面 / 这儿的首屏 URL /
+ * 引擎落盘那份 / 宿主这个入参），而 `web` 是 private 包、`core` 不许依赖它 ——
+ * 除了 protocol 没有第三处放得下。判据在 protocol 的 `wire-appearance.ts` 文件头。
  */
-type UiThemePref = 'system' | 'light' | 'dark';
+type UiThemePref = AppearanceTheme;
 /** 同上，对应 `localStorage['epoch.lang']`。值域跟着 protocol 的 `LANGS` 走 */
-type UiLangPref = 'system' | 'zh' | 'en';
+type UiLangPref = AppearanceLang;
 /**
  * 宿主给界面的首屏初值（方案 54 §七）。
  *
@@ -79,6 +85,13 @@ type UiLangPref = 'system' | 'zh' | 'en';
  * 「外观」分区仍然改得动；下次启动宿主再给一次初值。刻意**没有**「强制主题、
  * 界面上不许改」的开关：那是把宿主的偏好升成锁，而外观是今天用户在这张界面上
  * 唯一能自己调的东西（方案 54 §七末尾 + §十一）。
+ *
+ * ⚠️⚠️ **2026-09-29 起它还多了一条：用户自己选过的那一档压得过它。**
+ * 上面那句「下次启动宿主再给一次初值」原来的意思是「宿主每次都给、给了就生效」，
+ * 而那个意思在「宿主用 `port: 0`」的现实下等于**用户的选择活不过一次重启**
+ * （localStorage 按 origin 隔离，每次都是新 origin）。现在首屏带的是
+ * {@link resolveUiPreset} 算出来的那一份：**盘上有就用盘上的，缺的那一格才轮到
+ * 这里**。所以 `ui` 的准确语义是「我的产品默认外观」，而不是「每次启动重置外观」。
  */
 interface UiPreset {
     theme?: UiThemePref;
@@ -89,8 +102,9 @@ interface UiPreset {
  *
  * @param port 必须是**实际监听**的端口（`--port 0` 时由内核分配），
  *             不是命令行里那个
- * @param ui   宿主给的主题 / 语言初值。不给就一个参数都不拼 ——
- *             URL 逐字节和以前一样（`epoch web` 走的就是这条）
+ * @param ui   这次首屏该带哪几档。**调用方算完再传**（{@link resolveUiPreset}：
+ *             用户选过的压过宿主初值）。一个键都没有就一个参数都不拼 ——
+ *             URL 逐字节和以前一样（`epoch web` 没配 `ui` 时走的就是这条）
  */
 declare function firstScreenUrl(host: string, port: number, token: string, ui?: UiPreset): string;
 
@@ -1753,6 +1767,20 @@ interface SessionHubOptions {
      * 后事，等于把一条不变量的执行摊到每个调用点上，漏一处就是一次静默泄漏。
      */
     onCooled?: (sessionId: string) => void;
+    /**
+     * 读某一段会话**此刻**的标题。答不出就 `null`（不在目录里 / DB 起不来）。
+     *
+     * 这是 `session-title-changed` 那一帧唯一的真源（2026-09-29）。Hub 自己不认识
+     * 会话目录 —— 判据同 {@link SessionHubOptions.onCooled}：那是引擎那一侧的东西，
+     * 而 Hub 在这条链上只负责发帧。
+     *
+     * ⚠️ **为什么读的是「此刻」**：标题在轮次开头就落库了（`core` 那句
+     * `store.beginTurn()` → `appendMessage`），而这里是在 `drive()` 的**落盘节拍**
+     * 上读 —— 两者都发生在这一轮跑完之前。那个节拍只在落盘进度真的往前走了才触发，
+     * 所以读到 `null` 是常态（这一段还没有标题）。
+     * **读到 `null` 就什么都不做**，不许拿它当「标题被清空了」发出去。
+     */
+    readTitle?: (sessionId: string) => string | null;
 }
 /**
  * `start()` 的结果。
@@ -1835,6 +1863,8 @@ declare class SessionHub {
     private readonly clock;
     /** 见 {@link SessionHubOptions.onCooled} */
     private readonly onCooled;
+    /** 见 {@link SessionHubOptions.readTitle} */
+    private readonly readTitle;
     private readonly registry;
     private readonly sinks;
     /**
@@ -2064,19 +2094,36 @@ declare class SessionHub {
      *
      * 为一帧发给**零个**收件人的帧去改一份三边共用的契约，换不回任何东西。
      *
-     * ## 所以产地是两条端点，各自的判据
+     * ## 所以产地是四条端点，各自的判据
      *
      * | 产地 | 什么时候发 | 为什么 |
      * | --- | --- | --- |
      * | `POST /api/sessions`（`workspace/handlers.ts`） | **只在 `outcome.created`** | 复用那一支没多出一行来，发了等于让所有标签页白重取一次 |
      * | `DELETE /api/sessions/:id`（`api.ts`） | 删成了就发 | 不发的话**别的**标签页会一直挂着一行已经没了的会话，点进去才拿 404 |
      * | `PATCH /api/sessions/:id`（`api.ts`，2026-09-16） | **只在 `archived` 真的翻了** | 列表默认不列归档的那几段，所以归档 = 少一行、取回 = 多一行。判据全文在那个调用点上 |
+     * | `POST /api/sessions/:id/workspace`（`workspace/handlers.ts`，2026-09-30） | **只在那一行真的换了组的时候**（`bind` 那一支看 `outcome.changed`、「不使用工作区」那一支看调用前是不是已经是 `none`） | 它改的是那一行上的 `workspace` 格 —— 而侧栏「空间 / 任务 / 早先的会话」三组正是读它分出来的。判据全文在那个调用点上，和下面「置顶」那一档的分界见下一节 |
      *
      * ⚠️ 第三个产地**不在「进出 Hub」这条路上**，而上一版这段话正是按那条路数的
      * （原文「那是第一版……`hub-register-sites.test.ts` 已经钉住了会话只能从那三处
      * 变活」）。钉住的是**活性**，而这一帧的宾语是**列表端点答出来的那几行** ——
      * 两者在归档这一档上分叉：一段会话被收进归档时进出 Hub 的表一个字没动，
      * 可侧栏那份列表少了一行。别再拿「经不经过 Hub」当这一帧的判据。
+     * ⚠️ 第四个产地（绑定）**同样不经过 Hub**，而且它比归档那一档更远：它在
+     * 字面上不增不减任何一行，改的只是**其中一行上的一个格子**。
+     *
+     * ## ⚠️ 绑定那一档和「置顶不发」看着像，分界是「那句话会不会骗人」
+     *
+     * 绑定和置顶一样不改成员数，但**只有它发**：
+     *
+     * - 置顶只是**顺序旧一拍** —— 那一行还在列表里、点得开、内容也对，而按下去
+     *   的那一页自己会重取。过期看得见，但**不会骗人**，所以不发（判据全文在
+     *   protocol 的 `sessions-changed` 上）；
+     * - 绑定把那一行**放进了错误的分组**：屏幕说「这段会话在 epoch-agent 里干活」，
+     *   而它其实在 `lw` 里 —— 那句话是假的，而且**不会自己修**，得用户刷新页面、
+     *   或者切到一段列表里没有的会话才把它捡回来（2026-09-30 用户报的正是这个）。
+     *
+     * 代价如实记：一次换绑 = **每个标签页**各重取一次整份列表（本机 loopback GET，
+     * 50 行封顶）。绑定是用户手动、低频的一次动作，不在一轮里反复发生，认下它。
      *
      * 另外两处刻意**不发**：
      *
@@ -2085,6 +2132,33 @@ declare class SessionHub {
      *   而那一行**本来就在列表里**（列表的另一半来自 DB）。列表没变，不该发。
      */
     notifySessionsChanged(sessionId: string): void;
+    /**
+     * 广播「某一行上的**标题**变了」（2026-09-29）。语义、为什么带载荷、以及
+     * 「别的会话那一行也覆写得到」全在 protocol 的 `session-title-changed` 上。
+     *
+     * ## 两个产地
+     *
+     * | 产地 | 什么时候发 |
+     * | --- | --- |
+     * | {@link drive} 的落盘节拍 | 自动截出来的那个标题（`core` 拿首条 user 消息截的），一轮跑着跑着就长出来了 |
+     * | `PATCH /api/sessions/:id`（`api.ts` 的 `patchSession`） | 用户手动改名 |
+     *
+     * ## 为什么自动那一支挂在落盘节拍上，而不是「user 帧发完就发」
+     *
+     * 标题是**跟着那条 user 行一起落的**（`core` 的 `manager.ts` 的 `appendMessage`）。
+     * 落盘节拍正是「库里往前走了」这件事的采样点，而它已经在那儿了 —— 借它顺手读一次
+     * 标题，比另开一个「哪一帧之后再读一次库」的判断便宜，也不会漏掉别的落盘路径。
+     *
+     * ⚠️ **它不许只发给「正看着这一段」的人**：这一帧的宾语是**一行**，而侧栏吃所有
+     * 会话的帧（判据在 protocol 那一帧的 JSDoc 上）。`publish` 那一层本来就是扇出到
+     * 所有连接，所以这里不需要额外处理 —— 记这一笔是为了别有人顺手加个过滤。
+     *
+     * ⚠️ **`announcedTitle` 的写点只有这一处**（读它的是 `drive()`）：两个产地各更新
+     * 一遍的话，「哪一格才是已经宣布过的那个」就有了两份实现，而它们只要有一处忘了
+     * 更新，症状是**一轮跑完多发一帧内容一样的标题** —— 不致命、但没人会去查。
+     * 会话可能已经不在 Hub 里（被冷却 / 从没注册过），那时这一格没地方记，照发。
+     */
+    notifySessionTitleChanged(sessionId: string, title: string): void;
     /**
      * 广播「插件那张表变了」（2026-09-24）。语义和「为什么不带 `sessionId`」全在
      * protocol 的 `plugins-changed` 上。
@@ -3132,6 +3206,45 @@ interface PluginPreviewView {
         name: string;
         version: string;
     };
+    /** `InstallDependency`（core，经 runtime 原样透出）的镜像 —— 见 `WirePluginDependency` */
+    dependencies?: readonly DependencyView[];
+}
+/**
+ * 一个依赖。**手写一份镜像**，理由同 {@link PluginPreviewView}：这一层只依赖
+ * protocol + runtime，而 core 那个类型是经 runtime 透出来的，直接 import 会把
+ * 分层绕过去（`check-layers` 会红）。
+ *
+ * ⚠️ 镜像的代价是**加一格要两边一起加**，而漏了的表现是「core 算了、界面没有」——
+ * 所以 `toWireDependency` 是照着这个形状逐格写的，不是 spread 过去的。
+ */
+interface DependencyView {
+    name: string;
+    status: 'installed' | 'plan' | 'unresolved';
+    requiredBy: string;
+    source?: string;
+    reason?: string;
+    versionUnmet?: {
+        required: string;
+        current: string;
+        reason: string;
+    };
+    manifest?: {
+        name: string;
+        version: string;
+    };
+    inventory?: {
+        commands: readonly string[];
+        roles: readonly string[];
+        skills: readonly string[];
+        hooks: readonly {
+            type: string;
+            count: number;
+        }[];
+        denyRules: number;
+        mcpServers: readonly string[];
+        ignoredBuckets: readonly string[];
+        jsTools: boolean;
+    };
 }
 /** 七档拒绝的共同形状（runtime 的 `PluginRefusal`） */
 interface RefusalView {
@@ -3804,6 +3917,16 @@ interface WorkspaceView {
     decideNone(sessionId: string): void;
     /** 这个会话是哪一档。**不答「这个进程认不认识它」**，那一问由 Hub 答 */
     stateOf(sessionId: string): WorkspaceBindingState;
+    /**
+     * 这次决定还能不能改（2026-09-30）。
+     *
+     * **两处问它，而且必须是同一个答案**：`bindWorkspace` 那道 409 闸，
+     * 以及 GET / POST 两条路下发给界面的 `changeable`。三处各判一次的表现是
+     * 「界面上画着一张 picker、按下去 409」—— 那句话读起来像功能坏了。
+     *
+     * 判据全文在 runtime 的 `WorkspaceControl.canChange` 上。
+     */
+    canChange(sessionId: string): boolean;
     release(sessionId: string): void;
     /** 本机「已知工作区」清单，最近使用的在前 */
     known(): ReadonlyArray<{
@@ -4624,6 +4747,15 @@ interface CatalogRow {
      * 每一行都答得出。上面那两格可选说的是另一件事（v7 之前的老行没记过）。
      */
     archived: boolean;
+    /**
+     * 被置顶了吗（2026-09-29 接下网线）。
+     *
+     * 和 `archived` **同一档来路、同一档理由**：`sessions.pinned` 从会话库 v1 起
+     * 就在、`NOT NULL DEFAULT 0`，每一行都答得出，所以它是必填而不是可选。
+     *
+     * ⚠️ **两件事正交**：归档说「列不列」，置顶说「排哪儿」。一行可以两个都是真。
+     */
+    pinned: boolean;
 }
 /** 一条 FTS5 命中 —— runtime 的 `SessionHit` 结构上满足它 */
 interface CatalogHit {
@@ -4648,14 +4780,31 @@ interface SessionCatalog {
     /**
      * ⚠️ `archived` 是三态（方案 64 PR-2）：不给 = 只列没归档的，
      * `true` = **只**列归档的。判据同 runtime 的 `SessionControl.list`。
+     *
+     * `pinnedOnly: true` 只列置顶的那些（2026-09-29）。要它的是
+     * {@link listSessionSummaries}：那段函数必须把「很久没动过、按时间排已经掉出
+     * 这一页」的置顶会话单独取回来，否则用户置顶它就是白置顶。
      */
     list(limit?: number, opts?: {
         archived?: boolean;
+        pinnedOnly?: boolean;
     }): CatalogRow[];
     get(sessionId: string): CatalogRow | null;
     rename(sessionId: string, title: string): CatalogRow | null;
     /** 收进归档 / 取回。**不是删除** —— 判据在 runtime 的 `SessionControl.setArchived` 上 */
     setArchived(sessionId: string, archived: boolean): CatalogRow | null;
+    /**
+     * 置顶 / 取消置顶（2026-09-29）。
+     *
+     * 收成一个带布尔的方法，形状**逐字同** {@link setArchived}：调用点（web 那张
+     * 行菜单）拿到的本来就是一个布尔，拆成 `pin()` / `unpin()` 两个只会让每个
+     * 调用点自己写一次 `if`。
+     *
+     * ⚠️ **它不推 `updatedAt`**（置顶不是「活动」——判据在 runtime 的
+     * `SessionControl.setPinned` 上），所以这一发不改这一行**按时间排**的位置。
+     * 变的是排序里置顶那一档，判据在 {@link compareSummaries} 上。
+     */
+    setPinned(sessionId: string, pinned: boolean): CatalogRow | null;
     delete(sessionId: string): Promise<CatalogDeletion>;
     search(query: string, limit?: number): CatalogHit[];
 }
@@ -4910,6 +5059,26 @@ interface WebRuntimeView extends RuntimeCapabilities, RuntimeSecurity, RuntimeSe
      */
     session: (HubSession & ModelSessionFacts) | null;
     sessionId: string;
+    /**
+     * 不绑工作区时引擎**实际**跑在哪个目录（2026-09-30）。
+     * `EpochRuntime.defaultWorkDir` 结构上满足它。
+     *
+     * ⚠️ **它是可选字段**，同 `diagnosticsIn?` / `lastOpenSession?` 那一条：
+     * 自己拼 `WebRuntimeView` 的宿主可以不给 —— 那时 `GET /api/config` 整个不下发
+     * `defaultWorkDir`，界面退回「选择工作区」那个纯动作（两种形态都画得出来）。
+     * 把 `EpochRuntime` 整个传进来的宿主什么都不用做：它恒有这一格。
+     *
+     * ⚠️ **它是进程级的一份，所有会话共用**：绑定表答不出来时每个会话都回落到它
+     * （`session-factory.ts` 的 `site()` 那一行 `now?.workspace.root ?? opts.defaultWorkDir`）。
+     * 别读成「引导会话的工作目录」—— 引导会话只是**恰好**也跑在它上面。
+     *
+     * ⚠️ 在这儿**不要**用 `process.cwd()` 重算：宿主可以显式传 `workDir` 起引擎
+     * （`buildRuntime({ workDir })`），而那是**宿主进程**的 cwd，两者不是一回事。
+     *
+     * 上网线的形态、以及它为什么非下发不可，在 protocol 的
+     * `WireConfigResponse.defaultWorkDir` 上。
+     */
+    defaultWorkDir?: string;
     /**
      * 多会话工厂（方案 30 §6.3）。`EpochRuntime.sessionFactory` 结构上满足它。
      *
@@ -5128,6 +5297,19 @@ interface WebRuntimeView extends RuntimeCapabilities, RuntimeSecurity, RuntimeSe
      * 回 503 —— **不是假装记下来了**（同 `sessions` 为 null 时那两条的口径）。
      */
     lastOpenSession?: LastOpenSessionControl;
+    /**
+     * 界面外观偏好（主题 / 语言，2026-09-29）。`EpochRuntime.appearance`
+     * 结构上正好满足它。判据（含「为什么不是 `config.yaml` 的 `display`」四条）
+     * 在 core 的 `appearance.ts` 文件头。
+     *
+     * ## ⚠️ 可选，理由逐字同上面 `lastOpenSession`
+     *
+     * 自己手拼 `WebRuntimeView` 的嵌入宿主和 `__tests__/harness.ts` 那份假 runtime
+     * 都是手拼的，写成必填等于这一笔改动把它们全打断。不给时：首屏 URL 上一个
+     * 外观参数都不多拼、那次 303 也不重盖（行为逐字等于这一轮之前），
+     * 而 `POST /api/appearance` 回 503 —— **不是假装记下来了**。
+     */
+    appearance?: AppearanceControl;
     /**
      * `@:` 引用另一段会话那一片（方案 53 PR-4）。SQLite 起不来时为 null。
      * `EpochRuntime.sessionReferences` 结构上正好满足它。
@@ -6122,7 +6304,13 @@ interface CreateWebServerOptions {
      * `private: true` —— 宿主 import 不到，只能给 webview 挂一个 preload、
      * 在页面脚本之前手写 localStorage。能用，但它依赖的是一个我们随时能改的名字。
      *
-     * ⚠️ **是初值，不是锁**，判据见 {@link UiPreset}。
+     * ⚠️ **是初值，不是锁**，判据见 {@link UiPreset}。⚠️⚠️ **2026-09-29 起它还有一个
+     * 更容易读反的地方：用户自己选过的那一档压得过它。** 值不直接拼进 URL，而是先过
+     * {@link resolveUiPreset}（`<homeDir>/appearance.json` 里那一份优先，缺的那一格
+     * 才轮到这里）—— 所以准确的语义是「**我的产品默认外观**」，不是「每次启动重置外观」。
+     * 这一条在宿主用 `port: 0` 时尤其要紧：localStorage 按 origin 隔离，
+     * 每次启动都是一个新 origin，于是「宿主每次都给」曾经等于「用户的选择活不过一次
+     * 重启」。判据全文在 docs/EMBEDDING.md §9「给 ui，别去写 localStorage」那一节。
      */
     ui?: UiPreset;
     /** 环形缓冲容量，缺省 512 */