@epoch-agent/server 0.20.1 → 0.21.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）
 
 ```

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;
     /**
@@ -2085,6 +2115,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` 上。
@@ -4624,6 +4681,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 +4714,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[];
 }
@@ -5128,6 +5211,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 +6218,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 */

package/dist/index.js

@@ -1,7 +1,7 @@
 import { createServer } from 'http';
 import { createLogger, t, ApprovalRelay, QuestionRelay, serializeStream, withRoleScope, withModelScope, withToolScope, nextRunAt, observeBackgroundTasks, skillIndexDescription, SANDBOX_EXCLUDES, SANDBOX_COVERS, canProbeGit, guardSpawn, isSystemOpenable, backgroundTaskOutput, listBackgroundTasks, providerLabel, MAX_REASON_CHARS, MAX_OBJECTIVE_CHARS, MAX_GOAL_MAX_ROUNDS, DEFAULT_GOAL_MAX_ROUNDS, SCHEDULE_DEFAULT_ALLOWLIST, SCHEDULE_FORM_BUDGET_USD, SCHEDULE_DEFAULTS, coalesceRecording, readRecording } from '@epoch-agent/runtime';
 import { timingSafeEqual, randomBytes, randomUUID } from 'crypto';
-import { PLAN_OUTCOMES, WIRE_AUTH_COOKIE, WIRE_AUTH_COOKIE_ATTRS, WIRE_AUTH_TOKEN_PARAM, extractAllMentions, MAX_ATTACH_FILES, utf8ByteLength, MAX_SESSION_REFS, attachSessionSurface, isWireRewindScope, WIRE_REWIND_SCOPES, mcpConnectorState, MAX_ATTACH_TOTAL_BYTES, MAX_ATTACH_BYTES, truncateToBudget, WIRE_LANG_PARAM, isLang, conformsToWire, WIRE_LAST_SESSION_FIELDS, isQuestionAnswerMap, isProviderType, apiKeyEnvVar, WIRE_FILE_STAT_MAX, WIRE_SETTING_WRITE_LAYERS, isWirePlanAction, WIRE_PLAN_ACTIONS, isPermissionLevel, PERMISSION_LEVELS, WIRE_TRUST_REQUEST_FIELDS, WIRE_FORGET_WORKSPACE_FIELDS, collectPendingApprovals, unfixedRules, isWireSettingWriteLayer, parseModelRef, WIRE_GOAL_ACTIONS, OPERATION_TYPES, isOperationType, WIRE_PLUGIN_UPLOAD_FORM_FIELDS } from '@epoch-agent/protocol';
+import { PLAN_OUTCOMES, WIRE_AUTH_COOKIE, WIRE_AUTH_COOKIE_ATTRS, WIRE_AUTH_TOKEN_PARAM, extractAllMentions, MAX_ATTACH_FILES, utf8ByteLength, MAX_SESSION_REFS, attachSessionSurface, isWireRewindScope, WIRE_REWIND_SCOPES, mcpConnectorState, MAX_ATTACH_TOTAL_BYTES, MAX_ATTACH_BYTES, truncateToBudget, isAppearanceTheme, isAppearanceLang, WIRE_LANG_PARAM, isLang, conformsToWire, WIRE_LAST_SESSION_FIELDS, isQuestionAnswerMap, isProviderType, apiKeyEnvVar, WIRE_FILE_STAT_MAX, WIRE_SETTING_WRITE_LAYERS, isWirePlanAction, WIRE_PLAN_ACTIONS, isPermissionLevel, PERMISSION_LEVELS, WIRE_TRUST_REQUEST_FIELDS, WIRE_FORGET_WORKSPACE_FIELDS, collectPendingApprovals, unfixedRules, isWireSettingWriteLayer, parseModelRef, WIRE_GOAL_ACTIONS, OPERATION_TYPES, isOperationType, WIRE_PLUGIN_UPLOAD_FORM_FIELDS } from '@epoch-agent/protocol';
 import { resolve, join, relative, isAbsolute, sep, dirname, basename, extname } from 'path';
 import { existsSync, realpathSync, statSync, mkdirSync, createReadStream, readdirSync, createWriteStream, accessSync, constants } from 'fs';
 import { stat, readFile, rm } from 'fs/promises';
@@ -129,12 +129,28 @@ function generateToken() {
 }
 var UI_THEME_PARAM = "theme";
 var UI_LANG_PARAM = "lang";
+function storedUiPreset(stored) {
+  const preset = {};
+  if (isAppearanceTheme(stored.theme)) preset.theme = stored.theme;
+  if (isAppearanceLang(stored.lang)) preset.lang = stored.lang;
+  return preset;
+}
+function resolveUiPreset(host, stored) {
+  return { ...host, ...storedUiPreset(stored) };
+}
+function uiPresetParams(ui) {
+  const params = [];
+  if (ui.theme) params.push([UI_THEME_PARAM, ui.theme]);
+  if (ui.lang) params.push([UI_LANG_PARAM, ui.lang]);
+  return params;
+}
 function firstScreenUrl(host, port, token, ui = {}) {
   const shown = displayHost(host);
   const authority = shown.includes(":") && !shown.startsWith("[") ? `[${shown}]` : shown;
   const params = [`${WIRE_AUTH_TOKEN_PARAM}=${encodeURIComponent(token)}`];
-  if (ui.theme) params.push(`${UI_THEME_PARAM}=${encodeURIComponent(ui.theme)}`);
-  if (ui.lang) params.push(`${UI_LANG_PARAM}=${encodeURIComponent(ui.lang)}`);
+  for (const [name, value] of uiPresetParams(ui)) {
+    params.push(`${name}=${encodeURIComponent(value)}`);
+  }
   return `http://${authority}:${port}/?${params.join("&")}`;
 }
 var HOST_COMPOSE_TTL_MS = 10 * 6e4;
@@ -262,6 +278,7 @@ var SessionRegistry = class {
       turnStartedAt: null,
       lastFinish: null,
       persisted: null,
+      announcedTitle: null,
       queue: [],
       lastActiveTick: ++this.tick
     });
@@ -442,6 +459,7 @@ function toWireSummary(id, hub, row, extra = {}) {
     lastFinish: state.lastFinish,
     role: extra.role ?? null,
     archived: row?.archived ?? false,
+    pinned: row?.pinned ?? false,
     ...extra.snippet === void 0 ? {} : { snippet: extra.snippet }
   };
 }
@@ -474,7 +492,9 @@ function listSessionSummaries(hubStates, catalog, query, workspaceOf = () => nul
     return hits;
   }
   const rows = catalog?.list(limit, archived ? { archived: true } : {}) ?? [];
-  const summaries = rows.map(
+  const pinnedRows = archived ? [] : catalog?.list(limit, { pinnedOnly: true }) ?? [];
+  const listedIds = new Set(rows.map((r) => r.id));
+  const summaries = [...rows, ...pinnedRows.filter((r) => !listedIds.has(r.id))].map(
     (row) => toWireSummary(row.id, byId.get(row.id), row, {
       workspace: workspaceOf(row.id),
       role: roleOf(row.id)
@@ -487,6 +507,7 @@ function listSessionSummaries(hubStates, catalog, query, workspaceOf = () => nul
   return [...fresh, ...summaries].sort(compareSummaries).slice(0, limit);
 }
 function compareSummaries(a, b) {
+  if (a.pinned !== b.pinned) return a.pinned ? -1 : 1;
   if (a.live !== b.live) return a.live ? -1 : 1;
   const at = a.updatedAt ?? Number.POSITIVE_INFINITY;
   const bt = b.updatedAt ?? Number.POSITIVE_INFINITY;
@@ -499,6 +520,7 @@ var SessionHub = class {
   idleGraceMs;
   clock;
   onCooled;
+  readTitle;
   registry;
   sinks = /* @__PURE__ */ new Set();
   observers = /* @__PURE__ */ new Set();
@@ -512,6 +534,7 @@ var SessionHub = class {
     this.idleGraceMs = opts.idleGraceMs ?? 3e4;
     this.clock = opts.clock ?? Date.now;
     this.onCooled = opts.onCooled;
+    this.readTitle = opts.readTitle;
     this.registry = new SessionRegistry({
       ...opts.maxActiveSessions === void 0 ? {} : { maxActive: opts.maxActiveSessions },
       ...opts.maxQueuedMessages === void 0 ? {} : { maxQueued: opts.maxQueuedMessages }
@@ -661,6 +684,12 @@ var SessionHub = class {
     if (this.closed) return;
     this.publish(sessionId, { type: "sessions-changed" });
   }
+  notifySessionTitleChanged(sessionId, title) {
+    if (this.closed) return;
+    const entry = this.registry.get(sessionId);
+    if (entry) entry.announcedTitle = title;
+    this.publish(sessionId, { type: "session-title-changed", title });
+  }
   notifyPluginsChanged() {
     if (this.closed) return;
     this.publish(void 0, { type: "plugins-changed" });
@@ -732,6 +761,10 @@ var SessionHub = class {
         if (through !== null && through !== entry.persisted?.id) {
           entry.persisted = { id: through, seq: frame.seq };
         }
+        const title = this.readTitle?.(sessionId) ?? null;
+        if (title !== null && title !== entry.announcedTitle) {
+          this.notifySessionTitleChanged(sessionId, title);
+        }
         if (event.type === "finish") {
           entry.lastFinish = toWireFinish(event, frame.ts, entry.turnStartedAt);
         }
@@ -1834,9 +1867,11 @@ async function patchSession(ctx, req, res, sessionId, lang) {
   const fields = asRecord(body.value);
   const rawTitle = fields["title"];
   const rawArchived = fields["archived"];
+  const rawPinned = fields["pinned"];
   const wantsTitle = rawTitle !== void 0;
   const wantsArchive = typeof rawArchived === "boolean";
-  if (!wantsTitle && !wantsArchive) {
+  const wantsPinned = typeof rawPinned === "boolean";
+  if (!wantsTitle && !wantsArchive && !wantsPinned) {
     return sendError(res, 400, "bad-patch", t("web.patch_needs_field", void 0, lang));
   }
   const title = typeof rawTitle === "string" ? rawTitle.trim() : "";
@@ -1852,10 +1887,15 @@ async function patchSession(ctx, req, res, sessionId, lang) {
       t("web.session_store_unavailable", void 0, lang)
     );
   }
+  const titleBefore = wantsTitle ? catalog.get(sessionId)?.title ?? null : null;
   let row = wantsTitle ? catalog.rename(sessionId, title) : catalog.get(sessionId);
   const archivedBefore = row?.archived;
   if (row && wantsArchive) row = catalog.setArchived(sessionId, rawArchived);
+  if (row && wantsPinned) row = catalog.setPinned(sessionId, rawPinned);
   if (!row) return sendUnknownSession(res, sessionId, lang);
+  if (wantsTitle && row.title !== titleBefore) {
+    ctx.hub.notifySessionTitleChanged(sessionId, row.title);
+  }
   if (wantsArchive && archivedBefore !== row.archived) ctx.hub.notifySessionsChanged(sessionId);
   const hub = ctx.hub.listSessions().find((s) => s.id === sessionId);
   sendJson(res, 200, {
@@ -2098,6 +2138,37 @@ function parseAttachmentNames(raw) {
   if (!Array.isArray(raw)) return [];
   return raw.filter((name) => typeof name === "string" && name.length > 0);
 }
+async function postAppearance(ctx, req, res, lang) {
+  const control = ctx.runtime.appearance;
+  if (!control) {
+    return sendError(res, 503, "no-appearance-store", t("web.appearance_unavailable", {}, lang));
+  }
+  const body = await readJsonBody(req, void 0, lang);
+  if (!body.ok) return sendError(res, body.status, "bad-body", body.message);
+  const raw = body.value;
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    return sendError(res, 400, "bad-request", t("web.appearance_bad_request", {}, lang));
+  }
+  const record = raw;
+  const rawTheme = record["theme"];
+  const rawLang = record["lang"];
+  const theme = isAppearanceTheme(rawTheme) ? rawTheme : void 0;
+  const langPref = isAppearanceLang(rawLang) ? rawLang : void 0;
+  if (rawTheme !== void 0 && theme === void 0 || rawLang !== void 0 && langPref === void 0) {
+    return sendError(res, 400, "bad-request", t("web.appearance_bad_request", {}, lang));
+  }
+  const failure = control.set({
+    ...theme === void 0 ? {} : { theme },
+    ...langPref === void 0 ? {} : { lang: langPref }
+  });
+  if (failure) return sendError(res, 500, "write-failed", failure(lang));
+  const stored = control.get();
+  sendJson(res, 200, {
+    ok: true,
+    ...isAppearanceTheme(stored.theme) ? { theme: stored.theme } : {},
+    ...isAppearanceLang(stored.lang) ? { lang: stored.lang } : {}
+  });
+}
 async function revokeApprovalCache(ctx, req, res, sessionId, lang) {
   if (!ctx.hub.has(sessionId)) return sendUnknownSession(res, sessionId, lang);
   const perms = ctx.runtime.permissions;
@@ -5072,7 +5143,7 @@ async function dispatch(opts, req, res, lang) {
   }
   if (verdict.setCookie) res.setHeader("Set-Cookie", verdict.setCookie);
   if (verdict.setCookie && isRead(method) && !pathname.startsWith("/api/")) {
-    return redirectWithoutToken(res, req.url);
+    return redirectWithoutToken(res, req.url, ctx.runtime.appearance);
   }
   const segments = splitPath(pathname);
   if (segments[0] === "api") return handleApi(opts, req, res, method, segments, lang);
@@ -5101,6 +5172,9 @@ async function handleApi(opts, req, res, method, segments, lang) {
   if (resource === "last-session" && first === void 0 && method === "PUT") {
     return putLastSession(ctx, req, res, lang);
   }
+  if (resource === "appearance" && first === void 0 && method === "POST") {
+    return postAppearance(ctx, req, res, lang);
+  }
   if (resource === "host" && first === "compose" && second === void 0 && method === "POST") {
     return postHostCompose(ctx, req, res, lang);
   }
@@ -5413,9 +5487,12 @@ function archivedFlag(rawUrl) {
   const raw = new URL(rawUrl ?? "/", "http://127.0.0.1").searchParams.get("archived");
   return raw === "1" || raw === "true";
 }
-function redirectWithoutToken(res, rawUrl) {
+function redirectWithoutToken(res, rawUrl, store) {
   const url = new URL(rawUrl ?? "/", "http://127.0.0.1");
   url.searchParams.delete(WIRE_AUTH_TOKEN_PARAM);
+  for (const [name, value] of uiPresetParams(storedUiPreset(store?.get() ?? {}))) {
+    url.searchParams.set(name, value);
+  }
   res.writeHead(303, { ...baseHeaders(), Location: `${url.pathname}${url.search}` });
   res.end();
 }
@@ -5445,7 +5522,8 @@ async function createWebServer(opts) {
     ...opts.idleGraceMs === void 0 ? {} : { idleGraceMs: opts.idleGraceMs },
     ...opts.clock === void 0 ? {} : { clock: opts.clock },
     ...opts.maxActiveSessions === void 0 ? {} : { maxActiveSessions: opts.maxActiveSessions },
-    onCooled: (sessionId) => opts.runtime.sessionFactory.release(sessionId)
+    onCooled: (sessionId) => opts.runtime.sessionFactory.release(sessionId),
+    readTitle: (sessionId) => opts.runtime.sessions?.get(sessionId)?.title || null
   });
   if (opts.runtime.session) hub.register(opts.runtime.session);
   const unsubscribeTasks = observeBackgroundTasks((sessionId) => {
@@ -5469,7 +5547,12 @@ async function createWebServer(opts) {
   return {
     ok: true,
     server: {
-      url: firstScreenUrl(binding.host, listened.port, binding.token, opts.ui ?? {}),
+      url: firstScreenUrl(
+        binding.host,
+        listened.port,
+        binding.token,
+        resolveUiPreset(opts.ui ?? {}, opts.runtime.appearance?.get() ?? {})
+      ),
       port: listened.port,
       host: binding.host,
       token: binding.token,