@epoch-agent/server 0.10.1 → 0.12.0

package/README.md

@@ -118,6 +118,7 @@ tarball 里真的有那些字节。
 | `POST   /api/skills/stage`                                 | 把手里那一份字节交上来 → 一条本机路径（**回环绑定才给**，见下）                        |
 | `POST   /api/skills/remove`                                | `{name}` → 删掉一份用户级技能（**不可撤销；只有用户级删得掉**，见下）                  |
 | `POST   /api/roles`                                        | 新建一个身份，写进 `~/.epoch/agents/`（**回环绑定才给**，见下）                        |
+| `POST   /api/roles/remove`                                 | `{name}` → 删掉一份用户级身份（**不可撤销；回环绑定才给**，见下）                      |
 | `GET    /api/plugins`                                      | 装着的 + 市场里有什么 + `pendingRestart`（**进程级**，方案 59 E2，见下）               |
 | `POST   /api/plugins/install/preview`                      | 「将安装什么」，不写字节（**只收 `<市场>/<插件>`**，见下）                             |
 | `POST   /api/plugins/install`                              | `{ref, token}` → 真装（**回环绑定才给；装完不生效**，见下）                            |
@@ -785,10 +786,60 @@ frontmatter 逐格对上**（`mcp.json` 那条刻意收窄，这一条刻意不
 - **建完当场重载角色表**，不用重启：能力页刷新出来当场多一行，`delegate_task` 的
   枚举里也有它了。不重载的话这一下只做了一半（判据在
   [runtime/src/role-write.ts](../runtime/src/role-write.ts) 的文件头第二节）
-- ⚠️ **只有「建」，没有删也没有改**：`RoleWriteControlView` 上只有一个 `add`，
-  所以这个包**写不出**别的动作。要加 `remove` 先回去读 protocol 那份文件头第三节
-  —— 删一个身份不会往 system prompt 里塞字，但会静默拿掉别人正依赖的一段边界，
-  那道闸门的判据和「建」不一样
+- ⚠️ **这个文件里只有「建」**：`RoleWriteControlView` 上只有一个 `add`，所以
+  [src/role-add.ts](./src/role-add.ts) **写不出**别的动作。删那一条 2026-09-16
+  开了，镜像和 handler 一起住在另一个文件里（下面那一节）；**「改」照旧没有**，
+  而那条叮嘱对它仍然成立 —— 先回去读 protocol 那份文件头第三节
+
+#### `POST /api/roles/remove` —— **能加就得能删**（2026-09-16）
+
+> handler 在 [src/role-remove.ts](./src/role-remove.ts)。**和上面那条分两个文件**，
+> 判据同 `skill-remove.ts` 从 `skill-import.ts` 拆出来那次：镜像跟着 handler 走，
+> 于是这个文件写不出 `add`、那个文件写不出 `remove`，而
+> `RuntimeCapabilities.roleWrite` 是两张镜像的交集。
+
+起因是一句话，和技能那条逐字相同：这一栏原来只有「新建」，拿掉一个建错的身份
+得让用户自己去 `~/.epoch/agents/` 里翻目录 —— 而那一份里的 `description`
+是**每一轮都在进** `delegate_task` 工具描述的。
+
+##### ⚠️ 它吃**和「建」同一道**闸，而理由和 `POST /api/skills/remove` 刻意相反
+
+技能删除那条**不吃**闸门，判据逐字是「导入那条也不吃」（只给删加闸 =
+`--host 0.0.0.0` 下技能变成「只能加不能删」）。身份这边照抄那条推理会得出
+**相反**的结论，而那正是对的：**建那一侧本来就要回环**。于是删也要回环，
+一点不对称都不制造 —— 那一档下用户既建不出也删不掉，fail closed。
+
+⚠️ 哪天上面那道闸松了，这一道要跟着松，**两条一起动别只动半边**。判据全文在
+[protocol/src/wire-agent-role.ts](../protocol/src/wire-agent-role.ts) 文件头第六节。
+
+五档拒绝各对**一个不同的下一步**（**403 之外全是 200 + `ok:false`**）：
+
+| `reason`    | 什么情况                        | 用户该做什么                         |
+| ----------- | ------------------------------- | ------------------------------------ |
+| `missing`   | 请求里没给名字                  | （界面不该发出这一发）               |
+| `not-found` | 这个名字不在角色表里            | 手上那份清单旧了，刷新               |
+| `not-user`  | 它来自内置 / 项目 / 插件 / 宿主 | 那句话里点名了是哪一层，各有各的删法 |
+| `ambiguous` | 目录里两份以上都叫这个名字      | 去那个目录里留下要的那一份           |
+| `failed`    | 真的删不动（权限 / 只读盘）     | 去回执那条路径那儿看一眼             |
+
+- **失败是 200 而不是 `addRole` 那样的 4xx**，分野在**界面形状**：那边是一张
+  表单（失败落在表单底下，改一格再提交），这边是卡片上一枚按钮（失败落在那张卡
+  自己那一行小字上）。`{error:{code,message}}` 那个形状在界面上会走到「请求坏了」
+  那一支去。⚠️ **那道 403 是例外**：它答的不是「这一下没删成」，是「这条路在这一档
+  下不开」
+- **只有用户级删得掉**，而那道闸在 runtime（它才看得见合并后那张表）不在这一层。
+  界面上那颗按钮只画在「我的」那一组的卡上，但那是**体贴，不是安全性质**：
+  手搓一条 `POST /api/roles/remove {"name":"general"}` 会拿到 200 + `not-user`
+- **没删成时 `name` / `path` / `takenOverBy` 是空的**，判据逐字同技能那条
+- ⚠️ **`takenOverBy` 是这条路比技能那条多出来的那一格**：删掉的要是一个**同名
+  覆盖**，下层那一份会浮上来 —— 能力页刷新出来那一行**还在**（只是换了组）。
+  不下发这一格的话，界面对用户说「已经删掉 general」而列表里 general 还在，
+  也就是一次成功的删除长成了一次失败的删除。算它要查**重载之后**那张合并表，
+  所以这一层原样转发、一个字都不判
+- ⚠️ **「谁正用着它」这条路不查**，那是一个判断不是遗漏：服务端只数得到活着的
+  会话，数不到磁盘上休眠的那些，而报一个半真的数字比不报更糟。说清后果那件事
+  归界面上那一问（判据在 protocol 那份文件头 6.3）
+- **删完当场重载角色表**，同上面那条
 
 #### `/api/plugins*` 那六条 —— 插件那一页（方案 59 §六 E2，2026-08-21）
 

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { Lang, WireSkillImportFailure, WireSkillImportForm, WireSkillRemoveFailure, WireSkillStageFailure, WireProjectInventory, WireCapabilitiesResponse, WireSkillBodyResponse, EpochUserContent, AgentEvent, WireEnvelope, CustomCommandDef, ExpandedCommand, ModelRef, SetSelectionResult, WireCommandExpansion, WireCustomCommand, WireGoalPhase, WireGoalRefusal, WireTurnState, WireSessionFinish, ApprovalOutcome, QuestionAnswer, SessionSurfaceView, WireSessionReference, WireFileReference, ProviderType, ModelSelectionOrigin, WireModelCaveat, WireModelRejection, ContextBreakdown, PermissionLevel, WirePermissionRememberFailure, WirePluginSourceType, WirePluginVisibility, WirePluginStatus, WirePluginRefuseReason, WirePluginUploadFieldName, WirePluginUploadFields, WirePluginEntry, WireModelSource, WireModelProbeStatus, ScheduleDefinition, ScheduleRun, ScheduleBackendKind, OperationType, ScheduleTrigger, WireScheduleIssue, ScheduleRunStatus, TrustLevel, WireSandboxReason, WireAuditOutcome, WireAuditCode, WireCachedApproval, WireCachedDecision, WireToolVerdict, WireToolGateAxis, WireSecurityResponse, WireRewindScope, WireRewindRequest, WireCheckpointSummary, WireRewindPreview, WireRewindResponse, ActiveAgentRole, WireSettingValue, WireSettingLayer, WireSettingWriteLayer, WireSettingFutile, WireSettingApply, WireSettingValueKind, WireSettingsResponse, EpochConfig, TokenUsage, WireCompressionLine, WireProviderSummary, WireToolSummary, Diagnostic, WireReplayMessage, WireFileChange, WireAuthGuard, WireWorkspaceDiffResponse, BackgroundTaskInfo, WireTasksResponse, WireBackgroundTask, WireScheduleRow } from '@epoch-agent/protocol';
-import { SerializableApprovalRequest, SerializableQuestionRequest, ApprovalRevokeResult, LevelChangeResult, WorkspaceFilesView } from '@epoch-agent/runtime';
+import { 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, 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 { ServerResponse } from 'node:http';
 
 /**
@@ -491,13 +491,19 @@ type RoleAddResultView = {
 /**
  * `RoleWriteControl`（runtime）在服务端眼里的样子 —— **只有 `add` 这一个动作**。
  *
- * 镜像里只有它，于是这个包**写不出**「删一个身份」「改一个身份」：那不是靠
- * review 盯住的，是编译期的事（同 `McpControlView` 只有两个方法、
- * `SkillImportControlView` 只有两个动作）。
+ * 镜像里只有它，于是**这个文件里写不出「删一个身份」**：那不是靠 review 盯住的，
+ * 是编译期的事（同 `McpControlView` 只有两个方法、`SkillImportControlView`
+ * 只有两个动作）。
  *
- * ⚠️ 要加 `remove` 的时候**先回去读 protocol 那份文件头第三节**：删一个身份不会
- * 往 system prompt 里塞字，但会**静默拿掉**别人正依赖的一段边界 ——
- * 那道闸门的判据和「建」不一样，是一次独立的判断。
+ * > ⚠️ **2026-09-16：删那条路开了，但它在另一个文件里**
+ * > （[role-remove.ts](./role-remove.js) 的 `RoleRemoveControlView`）。
+ * > **镜像跟着 handler 走**，判据逐字同 `skill-remove.ts` 从 skill-import 拆出来
+ * > 那次：这个文件写不出 `remove`、那个文件写不出 `add`，而
+ * > `RuntimeCapabilities.roleWrite` 是两张镜像的交集。
+ * >
+ * > 这儿原来那条「要加 `remove` 先回去读 protocol 那份文件头第三节」的叮嘱
+ * > **已经兑现**：答案在那份文件头新的第六节（删吃和建**同一道**回环闸，
+ * > 理由和技能那条刻意相反）。**`edit` 那一半照旧没有，那条叮嘱对它仍然成立。**
  */
 interface RoleWriteControlView {
     /**
@@ -514,6 +520,96 @@ interface RoleWriteControlView {
     add(input: RoleAddView, lang?: Lang): RoleAddResultView;
 }
 
+/**
+ * 「删掉一个身份」那条端点 —— `POST /api/roles/remove`（2026-09-16）。
+ *
+ * ```
+ * POST /api/roles/remove   {name}   → 删掉 ~/.epoch/agents/ 里定义着它的那一份 md
+ * ```
+ *
+ * 起因是一句话，和技能那条逐字相同：**能加就得能删**。身份那一栏 2026-08-18 长出
+ * 了「新建」（[role-add.ts](./role-add.js)），而拿掉一个建错的身份得让用户自己去
+ * `~/.epoch/agents/` 里翻目录 —— 「加一个入口、不给出口」正是决定 20 ① 骂的那一族。
+ *
+ * ## 一、⚠️ 它**吃那道回环闸**，而理由和 `POST /api/skills/remove` **刻意相反**
+ *
+ * 技能删除那条**不吃**闸门，判据逐字是「导入那条也不吃」——只给删除加一道闸的
+ * 结果是 `--host 0.0.0.0` 下技能变成「只能加不能删」，那正是那一轮要修的病。
+ *
+ * 身份这边照抄那条推理会得出**相反**的结论，而那正是对的：
+ * **加那一侧本来就要回环**（`POST /api/roles` 那一道 403）。于是删也要回环，
+ * 一点不对称都不制造 —— 那一档下用户既建不出也删不掉。fail closed。
+ *
+ * ⚠️ 哪天上面那道闸松了，这一道要跟着松，**两条一起动别只动半边**。
+ * 判据全文在 protocol 的 [wire-agent-role.ts](../../protocol/src/wire-agent-role.ts)
+ * 文件头第六节。
+ *
+ * ## 二、⚠️ 那道 403 在**读请求体之前**，别挪进路由层
+ *
+ * 逐字同 `addRole`：被拒的那一发连正文都不该被解析。而路由那一层认的是
+ * 「哪条路」，不是「这一发准不准发」。
+ *
+ * ## 三、失败是 **200 + `ok:false`**，而 `addRole` 是 400 / 409 —— 分野在界面形状
+ *
+ * | 　       | 界面上是什么     | 一次失败落在哪儿                     |
+ * | -------- | ---------------- | ------------------------------------ |
+ * | 新建     | 一张表单         | 表单底下那一句，用户改一格再提交一次 |
+ * | 删除     | 卡片上一枚按钮   | **那张卡自己**那一行小字             |
+ *
+ * `{error:{code,message}}` 那个形状在界面上会走到「请求坏了」那一支去
+ * （判据逐字同 `removeSkill`）。⚠️ **上面那道 403 是例外，它仍旧是 `sendError`**：
+ * 它答的不是「这一下没删成」，是「这条路在这一档下不开」。
+ *
+ * ## 四、⚠️ 只有**用户级**删得掉，而那道闸不在这一层
+ *
+ * 内置 / 项目 / 插件 / 宿主四档由 runtime 的 `RoleWriteControl.remove` 判成
+ * `not-user`，并带一句点名是哪一层的话（那四档出路各不相同）。这一层
+ * **不自己判 source** —— 判两遍会有一天判得不一样，而只有那一层看得见合并后
+ * 那张表（判据逐字同 `skill-remove.ts` 文件头第三节）。
+ *
+ * 界面上那颗按钮只画在用户级那些卡上，但那是**体贴，不是安全性质**：
+ * 手搓一条 `POST /api/roles/remove {"name":"general"}` 会拿到 200 + `ok:false`
+ * + `not-user`。
+ *
+ * ## 五、`takenOverBy` 原样转发，这一层一个字都不判
+ *
+ * 那一格答的是「删完之后这个名字还在不在」（同名覆盖档下，下层那一份会浮上来，
+ * 于是界面上那一行**不会消失**）。算它要查重载之后那张合并表，只有 runtime
+ * 那一层做得到 —— 判据全文在 `WireRoleRemoveResponse.takenOverBy` 上。
+ */
+
+/** 删成了那一下回的东西（runtime 的 `RoleRemoveOutcome` 成功那一支） */
+interface RoleRemoveDoneView {
+    name: string;
+    path: string;
+    /** 删完之后谁接管了这个名字。`null` = 这个名字真的没了 */
+    takenOverBy: AgentRoleSource | null;
+}
+type RoleRemoveResultView = ({
+    ok: true;
+} & RoleRemoveDoneView) | {
+    ok: false;
+    reason: WireRoleRemoveFailure;
+    detail: string;
+};
+/**
+ * `RoleWriteControl`（runtime）在这条 handler 眼里的样子 —— **只有 `remove`**。
+ *
+ * 和 [role-add.ts](./role-add.js) 那张镜像刻意分开，判据逐字同 `skill-remove.ts`：
+ * 镜像跟着 handler 走，于是**这个文件里写不出 `add`**，而
+ * `RuntimeCapabilities.roleWrite` 是两张镜像的交集。
+ */
+interface RoleRemoveControlView {
+    /**
+     * @param lang 这一次的 `detail` 用哪个语言说（方案 58）。⚠️ **镜像上这一格是
+     *            必须的**：五档拒绝的话全在 runtime / core 里渲染，这一层只转发 ——
+     *            少声明它的话 `EpochRuntime` 照样满足这份镜像（多一个可选参数是
+     *            宽化），而这一层就递不出去，一声不吭地回中文。判据同
+     *            `RoleWriteControlView.add` 上那条 ⚠️
+     */
+    remove(name: string, lang?: Lang): RoleRemoveResultView;
+}
+
 /**
  * 从本机目录导入技能的两条端点（方案 42 §六，2026-08-18）：
  *
@@ -982,17 +1078,22 @@ interface RuntimeCapabilities {
      */
     readonly mcp: McpControlView & McpConfigControlView;
     /**
-     * 身份那一栏的写口：建一个（2026-08-18）。**进程级**，同上面那两条。
+     * 身份那一栏的写口：建一个（2026-08-18）+ 删一个（2026-09-16）。
+     * **进程级**，同上面那两条。
+     *
+     * ## ⚠️ 为什么是交集，不是一份镜像
      *
-     * 镜像和 handler 一起住在 [role-add.ts](./role-add.ts)（那边的文件头有全部
-     * 判据）—— 这一格只是把它挂进 `RuntimeCapabilities`，因为**装配那一行是在
-     * 这儿对形状的**（同 `mcp` 那一条）。
+     * 判据逐字同上面 `mcp` 那一格：两个方法挂在**同一个** runtime 对象上
+     * （`runtime.roleWrite`），分成两份声明是为了让**镜像跟着 handler 走** ——
+     * [role-add.ts](./role-add.ts) 里写不出 `remove`，[role-remove.ts](./role-remove.ts)
+     * 里写不出 `add`，而改哪条端点的人要读的判据就在那一个文件里。
      *
-     * ⚠️ 那条端点有一道**回环绑定**的闸门（`ctx.lanExposed` 为真就 403），
+     * ⚠️ **两条端点吃的是同一道**回环绑定闸门（`ctx.lanExposed` 为真就 403），
      * 而它**不在这份镜像上** —— 镜像答的是「runtime 借得到什么」，闸门答的是
-     * 「这一发准不准发」。判据全文在 protocol 的 `wire-agent-role.ts` 文件头。
+     * 「这一发准不准发」。判据全文在 protocol 的 `wire-agent-role.ts` 文件头
+     * （建那一道在第四节，删那一道**为什么不照抄技能那条**在第六节）。
      */
-    readonly roleWrite: RoleWriteControlView;
+    readonly roleWrite: RoleWriteControlView & RoleRemoveControlView;
 }
 /**
  * 三栏一次取齐。
@@ -1084,7 +1185,30 @@ interface HubSession {
         signal?: {
             readonly aborted: boolean;
         };
+        /**
+         * 「跑到一半插一句话」的取用口（2026-09-16）。Hub 拿自己那条消息队列
+         * 做一个递进来（`SessionHub.steerFrom`），引擎每次模型请求成形之前拉一次。
+         *
+         * ⚠️ **结构类型，不写 `SteerSource`**：这个文件在依赖链的最底下（文件头
+         * 那条「断开循环依赖」），从这儿 import runtime 会把环接回来。形状由
+         * `AgentSession.run` 的签名在编译期对齐 —— 走散了 `hub.ts` 那一行当场红。
+         */
+        steer?: {
+            pending(): boolean;
+            take(): EpochUserContent[];
+        };
     }): AsyncGenerator<AgentEvent>;
+    /**
+     * 在飞那一轮已经落盘到哪条消息了（按步增量落盘，2026-09-16）；
+     * 没有开着的轮时 `null`。`AgentSession.persistedThrough` 结构上满足它。
+     *
+     * **可选**，而这一档是真话不是偷懒：上面那句注释说的「脚本化的假会话」
+     * 一个也不会落盘，纯内存模式的真会话（没有 store）也答不出这个数。
+     * 答不出时 Hub 就不记水位线，于是 `GET /messages` 不带
+     * `inFlightThroughSeq` —— 浏览器退回 2026-09-16 之前那条路（用自己攒的
+     * 那半截），**那条路今天仍然是对的**，只是看不见在飞的那一轮。
+     */
+    persistedThrough?(): number | null;
 }
 /** SSE 连接从 Hub 收帧的出口 */
 type FrameSink = (frame: WireEnvelope) => void;
@@ -1549,10 +1673,34 @@ interface SessionHubOptions {
  * 让调用方能说清楚是哪一种拒绝。
  */
 type StartResult = 
-/** 收下了。`queued` = 排在当前这一轮后面，还没开始跑 */
+/**
+ * 收下了。`queued` = 排在当前这一轮后面，还没开始跑。
+ *
+ * `steered` 把 `queued: true` 那一档再劈成两半（2026-09-16）：
+ *
+ * | 两格            | 含义                                                     |
+ * | --------------- | -------------------------------------------------------- |
+ * | `queued: false` | 会话本来空着，这条消息**立刻**开了一轮                   |
+ * | `steered: true` | 正在跑的那一轮会在下一次模型请求前把它拌进去（插进本轮） |
+ * | `steered: false`| 排在后面，等这一轮跑完才轮到它（**开新的一轮**）         |
+ *
+ * ## 为什么必须分出第三格，而不是让界面自己猜
+ *
+ * 「插进本轮」和「排在后面」对用户是两件事：前者是「它马上会看到」，
+ * 后者是「它得先把手头这摊做完」。`queued: true` 一格答不了这个问题，
+ * 而界面**猜不出来** —— 判据有两条都在服务端手上：队列里排在它前面的那几条
+ * 是不是都能折进去，以及它自己是不是一条带轮级设置的斜杠命令
+ * （判据全文在 `SessionHub.steerFrom` 上）。
+ *
+ * ⚠️ **它是「会被拌进去」而不是「已经拌进去了」。** 真的进上下文那一刻由事件流
+ * 上的 `steer` 那一帧宣布（protocol 的 `AgentEvent`）—— 这一轮在那之前撞上
+ * `maxTurns` 或者被中止时，它会退回队列 / 交还给用户，那时这一格就说早了。
+ * 界面据它选措辞可以，据它把消息画成「已送达」不行。
+ */
 {
     ok: true;
     queued: boolean;
+    steered?: boolean;
 } | {
     ok: false;
     reason: 'unknown-session';
@@ -1634,6 +1782,19 @@ declare class SessionHub {
     has(sessionId: string): boolean;
     /** 这个 id 是被冷却掉的（而不是从来没存在过）吗 */
     isCooled(sessionId: string): boolean;
+    /**
+     * 在飞那一轮的落盘水位线 `(消息 id, 广播序号)`；没在跑 / 答不出时 `null`
+     * （按步增量落盘，2026-09-16）。
+     *
+     * 唯一调用方是 `GET /api/sessions/:id/messages`（[api.ts](./api.ts) 的
+     * `listMessages`）：它按 `id` 截断回放、把 `seq` 交给浏览器去重。
+     * 判据全文在 `SessionEntry.persisted` 和
+     * `WireMessageListResponse.inFlightThroughSeq` 上。
+     */
+    persistedThrough(sessionId: string): {
+        id: number;
+        seq: number;
+    } | null;
     /** 不认识的会话按 idle 报 —— 调用方要区分的话先问 `has()` */
     stateOf(sessionId: string): WireTurnState;
     /** Hub 手里这些会话此刻的样子。Map 的插入序 = 注册序 */
@@ -1715,15 +1876,37 @@ declare class SessionHub {
      */
     start(sessionId: string, message: EpochUserContent, decorate?: TurnDecorator): StartResult;
     /**
-     * 中止本轮，并**丢掉排在后面的消息**。
+     * 中止本轮，并**把排在后面的消息交还给调用方**。
+     *
+     * 不接着跑它们是刻意的，那句判据没变：用户按下「停」要的是「现在别干了」，
+     * 而不是「停掉这一轮然后立刻开始下一轮」—— 后者的表现是按了停之后 agent
+     * 又动起来了。
      *
-     * 排队的一起丢是刻意的：用户按下「停」要的是「现在别干了」，而不是
-     * 「停掉这一轮然后立刻开始下一轮」—— 后者的表现是按了停之后 agent 又动起来了。
+     * ## ⚠️ 2026-09-16：从「丢掉」改成「交还」
      *
-     * @returns 是否真有一轮在跑（**只看这个**，丢掉的队列不算）。
-     *          `false` 表示这一轮本来就没在跑，不是失败
+     * 在这之前这里是 `entry.queue.length = 0`，一句话都不说。那一档在排队时代
+     * 勉强说得过去（用户刚发出去、还没上屏几秒）；而「跑到一半插一句话」落地
+     * 之后它变成一个真会咬人的形状：用户盯着屏幕打了一整段修正意见、发出去、
+     * 看见模型还在往错的方向跑，于是顺手按了停 —— **那段话就没了**，
+     * 输入框是空的，剪贴板里也没有。
+     *
+     * 所以现在原样交出来，由宿主放回输入框。codex 的同一处叫
+     * `submit_pending_steers_after_interrupt`（`tui/src/chatwidget/input_queue.rs`），
+     * 它在「退回输入框」和「整批重提成新一轮」之间可切；这里只做前者 ——
+     * 后者是「我按了停它却又跑起来了」的另一种形状。
+     *
+     * **只交还没被引擎取走的那几条**：已经被 {@link steerFrom} 拌进上下文的那些
+     * 早就不在这个数组里了，它们已经是这段对话的一部分（库里有、屏幕上有），
+     * 再交还一次就成了重复。这一条不靠判断保证，靠的是两条路取同一个数组。
+     *
+     * @returns `running` = 是否真有一轮在跑（**只看这个**，交还的队列不算）；
+     *   `false` 表示这一轮本来就没在跑，不是失败。
+     *   `returned` = 交还的消息，按用户发送的先后；没有就是空数组。
      */
-    abort(sessionId: string): boolean;
+    abort(sessionId: string): {
+        running: boolean;
+        returned: EpochUserContent[];
+    };
     /** 补拉挂起的审批 —— 新连上来的页面靠它把弹层恢复出来（§4.3） */
     listPending(sessionId: string): SerializableApprovalRequest[];
     /** 补拉挂起的提问（方案 34 验收 9）。与 `listPending` 同构 */
@@ -1798,6 +1981,13 @@ 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` 真的翻了** | 列表默认不列归档的那几段，所以归档 = 少一行、取回 = 多一行。判据全文在那个调用点上 |
+     *
+     * ⚠️ 第三个产地**不在「进出 Hub」这条路上**，而上一版这段话正是按那条路数的
+     * （原文「那是第一版……`hub-register-sites.test.ts` 已经钉住了会话只能从那三处
+     * 变活」）。钉住的是**活性**，而这一帧的宾语是**列表端点答出来的那几行** ——
+     * 两者在归档这一档上分叉：一段会话被收进归档时进出 Hub 的表一个字没动，
+     * 可侧栏那份列表少了一行。别再拿「经不经过 Hub」当这一帧的判据。
      *
      * 另外两处刻意**不发**：
      *
@@ -1861,6 +2051,32 @@ declare class SessionHub {
      * 序列化那一层进出，而真正跑工具的 `run()` 在它外面，等于整层白做。
      */
     private drive;
+    /**
+     * 把这个会话的队列做成引擎能拉的样子 —— 「跑到一半插一句话」（2026-09-16）。
+     *
+     * 队列还是原来那一条（`entry.queue`），这里只是**多开一个取用口**：引擎在每
+     * 次模型请求成形之前来拉一次，拉到就拌进这一轮的上下文。拉不到、或者这一轮
+     * 到了 `maxTurns`，那几条原样留在队列里，由 {@link drainQueue} 按老路开下一轮。
+     * 两条路取的是同一个数组，所以**不会有一条消息被送进去两遍**。
+     *
+     * ## ⚠️ 带 `decorate` 的那种**不许折进当前这一轮**
+     *
+     * `decorate` 是**轮级**的（自定义斜杠命令的工具收窄、临时换模型，见
+     * {@link TurnDecorator}）。把一条 `/xxx` 命令折进正在跑的这一轮，它要求的收窄
+     * 就整个落空了 —— 而收窄落空的语义是「本该只给三个工具的那一轮，拿到了全部
+     * 工具」。所以这里只取**队首那一段连续的、没有 `decorate` 的**消息，遇到第一条
+     * 带 `decorate` 的就停手，让它去开自己那一轮。
+     *
+     * codex 在同一处的说法是 `NotSubmittedReason::ActiveTurnNotSteerable` ——
+     * 它的不可插入轮是 `Review` / `Compact`，理由同构：那两种轮次自带一套只属于
+     * 它们的设置。
+     *
+     * ## 为什么 `pending()` 不许取走
+     *
+     * 判据全文在 core 的 `SteerSource` 上：到顶的那一轮取走了却跑不了，
+     * 那句话就凭空蒸发了。这里两个方法因此算的是同一段前缀，只有 `take()` 动数组。
+     */
+    private steerFrom;
     /**
      * 一轮跑完，把排在后面的那条接上（方案 30 §2.3 第 4 条）。
      *
@@ -2869,6 +3085,21 @@ type UploadPreviewOutcomeView = {
     ok: true;
     plan: PackPlanView;
     token: string;
+    /**
+     * 那张表单每一格**从什么值开始**（2026-09-15）。
+     *
+     * ⚠️ **这一层原样转，一格都不算**（口径同这个文件头那句「一条策略判断
+     * 都没有」）：四档优先级（宿主锁死 > 宿主初值 > 包里同名格 > 空）在
+     * runtime 的 `resolveUploadPrefill` 上，在这儿兜一次的表现是同一格
+     * 在两处得出两个值。
+     *
+     * ⚠️ 键取自 `WirePluginUploadFieldName` 而不是自造一套：这一份最终原样
+     * 落到 `WirePluginUploadPreviewResponse.prefill` 上，两套名字会逼出一张
+     * 会错的映射表（判据同 runtime 的 `PLUGIN_UPLOAD_FIELDS`）。
+     */
+    prefill: WirePluginUploadForm;
+    /** {@link prefill} 里值是从包里读出来的那几格。只管屏幕上那一句提示 */
+    fromManifest: readonly WirePluginUploadFieldName[];
 } | RefusalView;
 /**
  * 上传的结局。
@@ -3259,6 +3490,13 @@ interface ScheduleControlView {
     runs: (id: string, limit?: number) => ScheduleRun[];
     /** 全部任务的最近运行 —— 「运行记录」那个 tab 的素材 */
     recentRuns: (limit?: number) => ScheduleRun[];
+    /**
+     * **此刻**哪几条在跑（2026-09-15）。素材是那张锁表，判定（心跳 + pid）留在 core。
+     *
+     * ⚠️ **它和上面两格答的不是同一个问题**：那两格要等一轮**跑完**才有行
+     * （执行器收尾时才 `recordRun`），所以「正在跑」在它们眼里是不存在的。
+     */
+    running: () => readonly RunningSchedule[];
     capability: () => Promise<ScheduleCapabilityView>;
     create: (input: ScheduleCreateView, opts?: {
         register?: boolean;
@@ -4252,6 +4490,13 @@ interface CatalogRow {
     workspaceState?: 'bound' | 'none';
     /** `workspaceState === 'bound'` 那一档的目录 */
     workspaceRoot?: string;
+    /**
+     * 被收进归档了吗（方案 64 PR-2）。
+     *
+     * **必填**：这一列从会话库 v1 起就有、`NOT NULL DEFAULT 0`，
+     * 每一行都答得出。上面那两格可选说的是另一件事（v7 之前的老行没记过）。
+     */
+    archived: boolean;
 }
 /** 一条 FTS5 命中 —— runtime 的 `SessionHit` 结构上满足它 */
 interface CatalogHit {
@@ -4273,9 +4518,17 @@ interface CatalogDeletion {
  * 起不来（SQLite 挂了）时整个是 `null`，列表退化成「只有 Hub 里那几个」。
  */
 interface SessionCatalog {
-    list(limit?: number): CatalogRow[];
+    /**
+     * ⚠️ `archived` 是三态（方案 64 PR-2）：不给 = 只列没归档的，
+     * `true` = **只**列归档的。判据同 runtime 的 `SessionControl.list`。
+     */
+    list(limit?: number, opts?: {
+        archived?: boolean;
+    }): CatalogRow[];
     get(sessionId: string): CatalogRow | null;
     rename(sessionId: string, title: string): CatalogRow | null;
+    /** 收进归档 / 取回。**不是删除** —— 判据在 runtime 的 `SessionControl.setArchived` 上 */
+    setArchived(sessionId: string, archived: boolean): CatalogRow | null;
     delete(sessionId: string): Promise<CatalogDeletion>;
     search(query: string, limit?: number): CatalogHit[];
 }
@@ -4378,6 +4631,16 @@ interface SettingWriteView {
     futile?: SettingFutileView;
     apply: WireSettingApply;
 }
+/**
+ * runtime 的 `SettingPending` 的镜像 —— 「写进盘了，而那个进程还没在用」（2026-09-16）。
+ *
+ * 引擎侧那个类型是 `SettingWriteTarget` 加一个 `value`，所以这里也是
+ * {@link SettingWriteView} 加一个 `value`：形状从哪一头改都得改两处，而两处都在这个
+ * 文件里，扫一眼就对得上。
+ */
+interface SettingPendingView extends SettingWriteView {
+    value: WireSettingValue;
+}
 /**
  * runtime 的 `EffectiveSetting` 的镜像。
  *
@@ -4400,6 +4663,14 @@ interface SettingRowView {
      */
     valueKind?: WireSettingValueKind;
     choices?: readonly string[];
+    /**
+     * 这一行写进盘了、而引擎那个进程还没在用的那个值（2026-09-16）。
+     *
+     * ⚠️ **它和 `value` 不是二选一，两格一起发。** 前者是「引擎此刻按的是什么」，
+     * 这一格是「盘上现在是什么」—— 这一层要做的只是原样转发，别在投影里替界面
+     * 二选一（判据在 protocol 的 `WireSettingPending` 上）。
+     */
+    pending?: SettingPendingView;
 }
 /** runtime 的 `SettingWriteReport` 的镜像。`reason` 是码，不是句子 —— 见文件头第 1 条 */
 type SettingWriteReportView = {
@@ -4617,6 +4888,16 @@ interface WebRuntimeView extends RuntimeCapabilities, RuntimeSecurity, RuntimeSe
      */
     sessionStore: {
         loadMessages(sessionId: string): WireReplayMessage[];
+        /**
+         * 库里那格「这一轮开着」的标记；没有就 null（按步增量落盘，2026-09-16）。
+         * runtime 的 `SessionStore.openTurnFrom` 结构上正好满足它。
+         *
+         * ⚠️ 它**不是**「正在跑」—— 那个问题问 `hub.persistedThrough()`。这一格
+         * 活过进程重启，所以「它非空而 Hub 手上没有这个会话」恰好就是
+         * 「上一个进程没能给那一轮收尾」，也就是 `interruptedTurnFrom` 那一档。
+         * 判据全文在 `SessionMeta.openTurnFrom` 上。
+         */
+        openTurnFrom(sessionId: string): number | null;
         /**
          * 这个会话在工作区里改过哪些文件（方案 42 PR-4）。
          *
@@ -4704,6 +4985,22 @@ interface WebRuntimeView extends RuntimeCapabilities, RuntimeSecurity, RuntimeSe
      * 而 DELETE / PATCH 回 503 —— 不是假装成功。
      */
     sessions: SessionCatalog | null;
+    /**
+     * 「这个项目上次停在哪段会话」（2026-09-14）。`EpochRuntime.lastOpenSession`
+     * 结构上正好满足它。
+     *
+     * ## ⚠️ 可选，而这一档和 `sessions` 那个 `| null` 不是同一种「没有」
+     *
+     * 那一格是「SQLite 起不来」（这个进程有这项能力，只是坏了）。这一格是
+     * **自己手拼 `WebRuntimeView` 的宿主压根没给** —— 嵌入宿主和
+     * `__tests__/harness.ts` 里那份假 runtime 都是手拼的，写成必填等于这一笔
+     * 改动把它们全打断，而它们不给这一格照样能跑（首屏退回引导会话，逐字等于
+     * 这一轮之前的行为）。
+     *
+     * 没给时：`GET /api/config` 不带 `lastSessionId`，`PUT /api/last-session`
+     * 回 503 —— **不是假装记下来了**（同 `sessions` 为 null 时那两条的口径）。
+     */
+    lastOpenSession?: LastOpenSessionControl;
     /**
      * `@:` 引用另一段会话那一片（方案 53 PR-4）。SQLite 起不来时为 null。
      * `EpochRuntime.sessionReferences` 结构上正好满足它。
@@ -5467,12 +5764,13 @@ declare function toWireTask(sessionId: string, info: BackgroundTaskInfo, registr
 declare function collectTasks(sessionId: string, registry: TaskRegistryView): WireTasksResponse;
 
 /**
- * 定时任务那十条端点（[方案 45](../../../../docs/verify/VERIFY_RECORD-45-automation.md)
- * PR-3 九条 + PR-4 那条 `pending`）。
+ * 定时任务那十一条端点（[方案 45](../../../../docs/verify/VERIFY_RECORD-45-automation.md)
+ * PR-3 九条 + PR-4 那条 `pending` + 2026-09-15 那条 `running`）。
  *
  * ```
  * GET    /api/schedules                              两个 tab 一次取齐
  * GET    /api/schedules/pending                      还欠着的那几张欠条（PR-4）
+ * GET    /api/schedules/running                      此刻哪几条在跑（2026-09-15）
  * POST   /api/schedules                              建一条
  * GET    /api/schedules/:id                          一条的全部字段
  * PATCH  /api/schedules/:id                          改一条（含那个开关）