@epoch-agent/server 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -1,5 +1,6 @@
-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';
+import { Lang, WireSkillImportFailure, WireSkillImportForm, 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, WirePluginSourceType, WirePluginRefuseReason, 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, WireSettingsResponse, EpochConfig, WireCompressionLine, WireProviderSummary, WireToolSummary, Diagnostic, WireReplayMessage, WireFileChange, WireAuthGuard, WireWorkspaceDiffResponse, BackgroundTaskInfo, WireTasksResponse, WireBackgroundTask, WireScheduleRow } from '@epoch-agent/protocol';
+import { SerializableApprovalRequest, SerializableQuestionRequest, ApprovalRevokeResult, LevelChangeResult, WorkspaceFilesView } from '@epoch-agent/runtime';
+import { ServerResponse } from 'node:http';
 
 /**
  * 绑定策略 —— 「监听哪儿、给不给 token、拒不拒绝启动」。
@@ -396,6 +397,12 @@ interface RoleAddView {
     description: string;
     prompt?: string;
     tools?: readonly string[];
+    /**
+     * 技能索引白名单（2026-08-27）。⚠️ **这一层不校验它**，和 `tools` 刻意不同 ——
+     * 判据全文在 protocol 的 `WireRoleAddRequest.skills` 上（技能表会在会话中途变，
+     * 把「此刻没装」判成 400 是拒掉一个明天就成立的名字）。
+     */
+    skills?: readonly string[];
     maxTurns?: number;
 }
 /**
@@ -608,15 +615,32 @@ interface RoleView {
     name: string;
     description: string;
     tools?: readonly string[];
+    /**
+     * 技能索引白名单（`AgentRole.skills`，2026-08-27）。⚠️ **镜像上漏掉这一格不会
+     * 红** —— 真源上它是可选的，少声明照样满足这份镜像，表现只是 `toWireRole()`
+     * 一声不吭地读不到它（判据同下面 `McpView.source` 那条 ⚠️）。它是这一屏上
+     * 「一个身份自己声明了哪几条技能」的唯一来源。
+     */
+    skills?: readonly string[];
     maxTurns?: number;
     source: 'builtin' | 'user' | 'project' | 'plugin' | 'host';
 }
 /**
- * `RoleMergeNotice` 的镜像。**只取 `role` 和 `cut`** —— `detail` 是中文文案，
- * 浏览器要用自己的 catalog 组句（同诊断的规矩），下发它等于让英文界面照抄中文。
+ * `RoleMergeNotice` 的镜像。**只取 `role` / `kind` / `cut`** —— `detail` 是中文
+ * 文案，浏览器要用自己的 catalog 组句（同诊断的规矩），下发它等于让英文界面
+ * 照抄中文。
+ *
+ * ⚠️ **`kind` 这一格是必须的，不是「顺手多带一样」**（2026-08-27）。加上它之前
+ * 这一族 notice 全是工具收窄，于是 `toWireRole()` 里一句 `find(n => n.role === …)`
+ * 就够了；技能收窄一旦也产 notice，那句 `find` 会**抓到技能那一条并把技能名画成
+ * 划掉的工具芯片** —— 两边都是 `string[]`，编译器一个字都不会说。
+ * 记账全文在
+ * [RECORD-skill-index-narrowing](../../../docs/verify/VERIFY_RECORD-skill-index-narrowing.md) §四第 3 条。
  */
 interface RoleNoticeView {
     role: string;
+    /** 收窄的是哪一轴。真源是 core 的 `RoleMergeNotice.kind` */
+    kind: 'tools' | 'skills';
     cut: readonly string[];
 }
 /** `SkillMeta` 在服务端眼里的样子。`scope` 同上一条 ⚠️ */
@@ -661,6 +685,14 @@ interface RuntimeCapabilities {
      * 没起来时是 `null` —— 两者对这一层是同一件事：没有正文可发。
      */
     skillBody(name: string): string | null;
+    /**
+     * 每条技能此刻进没进索引，名字 → 三档（2026-08-27）。**这一层不自己算** ——
+     * 判据是它算不出来：封顶的丢弃顺序（`DROP_RANK`）和角色白名单的交集语义
+     * 都在 core 的 `prompt-index.ts` 里，而这个包不许 import core。按
+     * `role.skills.includes()` 在这儿再判一遍就是第二份实现，
+     * 而它和真索引分叉之后两边都答得出「我算了」。
+     */
+    skillIndexResidency(role: string | null): ReadonlyMap<string, 'indexed' | 'capped' | 'role'>;
     /**
      * 从**本机目录**导入技能（方案 42 §六）。**进程级**，同 {@link mcp}。
      *
@@ -706,6 +738,14 @@ interface RuntimeCapabilities {
  *
  * @param bound 这个会话绑的工作区（`workspaces.of(sessionId)`）。没绑就是 null，
  *   那时「项目」那一层整个不存在 —— 不是「有但是空的」
+ * @param role 这个会话的**底座身份名**（`LiveSession.role?.name`），没绑就是 null。
+ *   只有技能那一栏读它：一个带 `skills` 白名单的身份会让某几条技能不进索引，
+ *   于是那几行行尾那个「常驻开销」是假话（2026-08-27 那笔账）。
+ *
+ *   ⚠️ **它是必传的一格，不是可选参数。** 这个函数今天只有一个调用方，加个
+ *   默认 `null` 只会让下一个调用方在**默认不收窄**这条路上静默走对一半 ——
+ *   而走错的表现是屏幕上多出一个假数字，没有任何东西会红。判据同
+ *   `toWireSkill` 的 `residency` 那一格。
  */
 declare function collectCapabilities(runtime: RuntimeCapabilities, tools: readonly {
     name: string;
@@ -717,7 +757,7 @@ declare function collectCapabilities(runtime: RuntimeCapabilities, tools: readon
     trust: {
         trusted: boolean;
     };
-} | null): WireCapabilitiesResponse;
+} | null, role: string | null): WireCapabilitiesResponse;
 /**
  * 一份 `SKILL.md` 最多发多少字节。形状照
  * [workspace/diff.ts](./workspace/diff.ts) 的 `MAX_DIFF_BYTES`。
@@ -980,6 +1020,138 @@ interface ExpansionOutcome {
  */
 declare function expandUserContent(runtime: RuntimeCommands, message: EpochUserContent, model: ModelTurnsView | null, role: TurnRole | null): ExpansionOutcome;
 
+/**
+ * `WebRuntimeView.goalCatalog` —— **server 从 runtime 借的目标那一片**
+ * （[方案 52](../../../../docs/verify/VERIFY_RECORD-52-goal.md) PR-4）。
+ *
+ * ## 为什么是一份结构镜像，而不是 `import type { GoalCatalog }`
+ *
+ * 判据逐字同 [schedule/view.ts](../schedule/view.js)，两条，第二条是硬的：
+ *
+ * 1. **`context.ts` 那句话**：这一层只借「用得到的那一小片」。`GoalCatalog` 的
+ *    每个方法都回 core 的 `Goal` / `GoalWrite` / `GoalClear` —— 借整个接口等于
+ *    让 `@epoch-agent/server` 的公开 `.d.ts` 引用一个它没声明依赖的包；
+ * 2. **用例要造得出一个假的**。`server/__tests__/harness.ts` 的假 runtime 是手写
+ *    对象。镜像用 protocol 的类型写完之后，那个假件一行 core 都不用碰。
+ *
+ * ⚠️ **镜像必须和真身逐字段对得上**，否则 `cli/src/commands/web.ts` 那一行
+ * `createWebServer({ runtime })` 当场编译不过 —— 那正是这份镜像的全部强制力。
+ *
+ * ## ⚠️ 借的是 `goalCatalog` 而**不是** `goals`，这一条是这个文件的正题
+ *
+ * `EpochRuntime` 上有两格，答的是两个问题：
+ *
+ * ```
+ * runtime.goals        「**引导会话**那一段的目标」   GoalControl（收窄到一段）
+ * runtime.goalCatalog  「**任意一段**会话的目标」     GoalCatalog（按 id 现查）
+ * ```
+ *
+ * 借前者的下场，这个仓库已经付过一次账了：`WebRuntimeView` 上原来有一个进程级的
+ * `checkpoints`，而三条回退端点都在拿它答任意一个 sessionId ——「编译得过、跑得通、
+ * 只是答错会话」（方案 30 §9.5）。那个字段 2026-08-15 删掉了，`context.ts` 上那段
+ * ⚠️ 写着为什么。这一格从第一天起就借对的那一份。
+ *
+ * ## 为什么不像检查点那样「向工厂要这个会话自己那一份」
+ *
+ * 因为**目标没有内存态**。`GoalService` 每次现读 SQLite（`GoalStore.current`），
+ * 于是「这段会话此刻活不活着」和「它的目标是什么」是两个无关的问题：
+ *
+ * | 那一格         | 真源                       | 冷却掉的会话答得出吗 |
+ * | -------------- | -------------------------- | -------------------- |
+ * | 检查点         | 这个进程的 `CheckpointManager` | ❌ 只能回空列表   |
+ * | 计划           | 内存那份优先，回退读盘     | ⚠️ 读盘那份可能旧    |
+ * | **目标**       | **只有 SQLite 一份**       | ✅ 一样准            |
+ *
+ * 走工厂那条路的话，用户打开一段昨天的会话会看到「这个会话还没有目标」——
+ * 而库里那条目标正躺在那儿，那正是「交代完走开」这份方案要修的病本身。
+ *
+ * ## ⚠️ 这里**没有** `block()`
+ *
+ * runtime 那一侧的 `GoalCatalog` 上也没有（判据在它的 JSDoc 上）：`blocked` 是
+ * 模型 / 策略层的态，而那个 `code` 是给程序路由用的键 —— 从 HTTP 这一侧露出一条
+ * 报 `blocked` 的路，等于让浏览器编一个 `needs-approval` 出来，而那个方向是提权
+ * （52 §5.1 结论 3）。网线上那份请求体里同样说不出这个态
+ * （`WireGoalUpdateRequest` 只有三态），**两道各自独立**：这一道是编译期的，
+ * 那一道是契约上的，少任何一道另一道都会变成唯一的防线。
+ */
+
+/**
+ * core 的 `Goal` 在服务端眼里的样子。
+ *
+ * **没有 `id`** —— 那是 `goals` 表的主键，这一层拿它什么都做不了（一个会话至多
+ * 一个目标，寻址靠 sessionId）。镜像上没有它是**编译期生效**的：投影里写不出
+ * `goal.id`，写了当场不过。判据同 `CheckpointSummaryView` 那处「没有 `cursor`」。
+ *
+ * `sessionId` **留着**，和 `id` 刻意不同：跨会话那条端点要拿它去查标题。
+ */
+interface GoalView {
+    sessionId: string;
+    objective: string;
+    phase: WireGoalPhase;
+    /** `phase === 'blocked'` 时必有，其余态必无 */
+    block?: {
+        readonly code: string;
+        readonly message: string;
+    };
+    maxRounds: number;
+    roundsUsed: number;
+    /** `phase === 'complete'` 时必有 */
+    completeEvidence?: string;
+    createdAt: number;
+    updatedAt: number;
+}
+/**
+ * 一次写的结果 —— core 的 `GoalWrite`。
+ *
+ * **判别联合原样照抄，不摊平成 `{ok, goal?, reason?}`**：摊平之后
+ * 「`ok: true` 却没有 goal」在类型上说得出口，而 handler 那一侧只能补一个
+ * `?? null` —— 那个 `null` 会一路走到网线上，界面读成「写成功了但目标没了」。
+ */
+type GoalWriteView = {
+    ok: true;
+    goal: GoalView;
+} | {
+    ok: false;
+    reason: WireGoalRefusal;
+};
+/** `clear` 的结果 —— core 的 `GoalClear`。它没有「写完之后那份目标」 */
+type GoalClearView = {
+    ok: true;
+    cleared: boolean;
+} | {
+    ok: false;
+    reason: WireGoalRefusal;
+};
+/**
+ * 目标那一片能力。`EpochRuntime.goalCatalog` 结构上正好满足它。
+ *
+ * ## ⚠️ 可以为 null，而这和 `schedules` 那一格刻意不同
+ *
+ * 定时任务那一格不可为 null（底下只有一张表和一次平台探测，没有起不来的可能）。
+ * 这一格**会**为 null：目标是**落盘的状态**，会话库起不来时它整个不存在 ——
+ * 判据逐字同 TUI 那一侧的「会话库起不来时 `/goal` 压根不注册」（那时还让它出现在
+ * `/help` 里，等于承诺一个建了就没的东西）。
+ *
+ * 于是那五条端点在这一档回 **503 `no-goal-store`**，而不是一份 `goal: null`：
+ * 后者是「这个会话没有目标」，前者是「问不出来」，两者在界面上是两种画法
+ * （一个是空态加一个「来定一条」的按钮，一个是一句「这台机器上没有会话库」）。
+ * 判据全文在 `WireGoalResponse` 上。
+ */
+interface GoalCatalogView {
+    current: (sessionId: string) => GoalView | null;
+    /** 建一个。**人专用** —— 判据在 runtime 的 `GoalCatalog.create` 上 */
+    create: (sessionId: string, objective: string, maxRounds?: number) => GoalWriteView;
+    /** 改正文。**不重置轮次、不改 phase** */
+    edit: (sessionId: string, objective: string) => GoalWriteView;
+    /** 改预算。⚠️ 两个方向都会顺手改 phase，判据在 `WireGoalUpdateRequest` 上 */
+    setBudget: (sessionId: string, maxRounds: number) => GoalWriteView;
+    pause: (sessionId: string) => GoalWriteView;
+    resume: (sessionId: string) => GoalWriteView;
+    /** 人替它报完成。依据必填 */
+    complete: (sessionId: string, evidence: string) => GoalWriteView;
+    clear: (sessionId: string) => GoalClearView;
+}
+
 /**
  * SessionHub —— 事件总线 + 回合状态机 + 审批生命周期。
  *
@@ -1319,6 +1491,214 @@ declare class SessionHub {
     private reap;
 }
 
+/**
+ * `@` 提及在 Web 那一侧的两半（方案 53 PR-4 的会话 + 方案 63 的文件）——
+ * 补全面板的候选，和发消息那条路上的解析。
+ *
+ * ## 四件事，一个文件
+ *
+ * | 做什么                        | 谁调                                  |
+ * | ----------------------------- | ------------------------------------- |
+ * | `GET .../reference-candidates` | 输入框打 `@:` 那一刻（方案 53 PR-4）  |
+ * | `GET .../file-candidates`      | 输入框打 `@文件` 那一刻（方案 63）    |
+ * | 把解析结果塞进这一条消息      | `api.postMessage`（每条消息都问一次） |
+ *
+ * 不摊进 [api.ts](./api.ts)，理由同 [commands.ts](./commands.js)：那个文件是
+ * 「一个端点一个函数」，而这里有一份 runtime 能力的**结构镜像**加一段提及解析。
+ *
+ * ## ⚠️ 引擎那一侧一行都不重写 —— 这是这一整份的性质
+ *
+ * 三样东西全部来自 `EpochRuntime.sessionReferences`（判据在它的 JSDoc 上）：
+ *
+ * - **候选**（只碰 id / cwd / 标题，一个字的转录文本都不搜，§5.2）
+ * - **解析**（`@:xxx` → 哪一段，或者为什么不是）
+ * - **当前面**（`active = 1` 的那些，§二）
+ *
+ * 而这三样里最要紧的是**可读性判定**：它在 core 里、和[方案 48](../../../docs/verify/VERIFY_RECORD-48-session-query.md)
+ * 共用一处（`core/src/session/authorization.ts` 的 `resolveSessionVisibility`，
+ * 判据全文在那个文件头）。让服务端自己去读 `sessions.db`
+ * 等于给 `@:` 开一条绕过那个判定的读取通道 —— 而 `@:` 存在的前提恰恰是
+ * 「它永远不比 `session_search` 宽松」（方案 53 §4.3）。
+ *
+ * 上限那张表和截断那段算术也不在这儿：它们住在 protocol
+ * （`attachSessionSurface`），和 TUI 那条路**共用同一份**。抄第二遍的形态很具体：
+ * TUI 上一段会话附了 48 条、web 上同一段附了 60 条，两边都不报错，
+ * 而「模型到底看见了什么」从此有两个答案。判据全文在 protocol 的 `mentions.ts`。
+ *
+ * ## `@文件` 那一半（方案 63）的行状
+ *
+ * - **候选**走 `EpochRuntime.workspaceFiles.candidates`（runtime 的收窄面）：
+ *   过滤、`@` 表达不出来的去尾、排序、缓存全在那一侧（判据在那个文件的文件头），
+ *   这里只做「按 `:id` 现算工作区根 → 递进去 → 搬上网线」三件事。
+ * - **解析**走同一条路的两步：`resolve` 出界 = `denied`，`readFile` 一趟走完
+ *   边界 / `file_read` 同源判定 / 二进制探测（失败三档码见 runtime 的
+ *   `FileReadOutcome`）。**服务端这里没有一个字的文件读取** —— 判据同上面
+ *   「让服务端自己去读 sessions.db」那一条：`@` 存在的前提是它永远不比
+ *   `file_read` 宽松，而判定只有权限层那一份。
+ * - **预算**：文件先吃、会话后到，两者共享同一本 200KB 的账 —— 判据逐字同
+ *   `core/src/context/mentions.ts` 的 `resolveMentions`（反过来的话两个小文件
+ *   会被一段长会话挤成 `budget-exceeded`，而用户显然更想要那两个文件）。
+ *
+ * ## 这一层自己拿的两个决定
+ *
+ * 1. **`currentSessionId` 一律是 URL 上那个 `:id`，不是 `runtime.sessionId`。**
+ *    后者是**引导会话**。拿它去答别的会话，表现是「引用自己」判不出来
+ *    （于是真的把自己塞进自己）、血缘链算成另一段会话的 —— 而它编译得过、
+ *    跑得通、只是答错会话（同 `EpochRuntime.checkpoints` 那段 ⚠️ 骂的那件事）。
+ * 2. **工作区取 `projectContext.rootDir`，不是 `workspace.root`。**
+ *    两者在「在子目录里起的那次会话」上不同（前者是仓库根，后者是启动目录），
+ *    而写入侧往 `sessions.cwd` 里写的是前者（判据在 `core/src/session/manager.ts`
+ *    的 `getLatestByCwd` 和 `authorization.ts` 的 `workspaceCwd` 上）。
+ *    给错的表现是**一条候选都列不出来**，而屏幕上只是一个空面板。
+ */
+
+/**
+ * 候选清单一次最多回几条。
+ *
+ * 面板上放不下更多，而这个数同时是那条 SQL 的 `LIMIT` —— 用户打得越细，
+ * 回来的越少（过滤在 SQL 里，见文件头）。
+ *
+ * ⚠️ **它不是 TUI 那个 `SESSION_CANDIDATE_POOL`。** 那一个是「挂载时拉一池子回来、
+ * 之后在前端筛」，于是第 41 段会话**永远搜不到而且屏幕上没有提示**（那笔账记在
+ * `docs/verify/VERIFY_RECORD-53-session-reference.md` 第六章）。这一条路每次带着
+ * `?q=` 现问，所以这个数只封「一屏列多少」，不封「能搜到哪几段」。
+ */
+declare const MAX_CANDIDATES = 20;
+/**
+ * 一段会话候选在引擎眼里的样子（core 的 `SessionCandidate`）。
+ *
+ * ⚠️ **和网线那一份（{@link WireSessionCandidate}）字段逐个相同，而它们仍然是两个
+ * 类型**：这一份是镜像（server 不许 import core），那一份是契约。所以
+ * {@link toWireCandidate} 是一次**显式**的搬运而不是 `as` —— 哪天引擎那侧加了一个
+ * 带转录文本的字段（`preview`），它不会顺着 spread 悄悄上网线。
+ */
+interface SessionCandidateView {
+    sessionId: string;
+    title: string;
+    cwd?: string | undefined;
+    updatedAt: number;
+    messageCount: number;
+    sameWorkspace: boolean;
+}
+/** 解析的结果（core 的 `ResolvedReference`）。三个码见方案 53 §4.2 */
+interface ResolvedReferenceView {
+    sessionId?: string | undefined;
+    reason?: 'invalid-reference' | 'self-reference' | 'not-authorized' | undefined;
+}
+/** 一次可读范围的入参。三格逐字同 core 的 `SessionVisibilityInput`（去掉 `db`） */
+interface VisibilityInput {
+    /** 谁在引用 —— **URL 上那个 `:id`**，见文件头第 1 条 */
+    currentSessionId: string;
+    /** 项目根（`projectContext.rootDir`），见文件头第 2 条 */
+    workspaceCwd?: string | undefined;
+    /** 跨工作区。只能来自已经打开了配置开关的那条路 */
+    allWorkspaces?: boolean;
+}
+/**
+ * `EpochRuntime.sessionReferences` 在服务端眼里的样子 —— **三个方法，一个不多**。
+ *
+ * 写镜像而不是 import core，判据同 `commands.ts` / `capability.ts` 的文件头。
+ * 而这一格还多一条：它收窄的东西本身就是一条安全边界 ——
+ * 那份门面刻意「交不出任意 SQL」（`SessionReferences` 的 JSDoc），
+ * 镜像照着它抄，服务端就连绕过判定的**语法**都没有。
+ *
+ * `EpochRuntime.sessionReferences` 结构上正好满足它，
+ * 对不上就是两边长歪了，`cli/src/commands/web.ts` 那一行当场编译不过。
+ */
+interface SessionReferencesView {
+    /** 补全面板的候选。**只按 id / cwd / 标题过滤**（§5.2） */
+    candidates(input: VisibilityInput & {
+        query: string;
+        limit: number;
+    }): readonly SessionCandidateView[];
+    /** `@:xxx` → 哪一段会话（§1.2） */
+    resolve(input: VisibilityInput & {
+        ref: string;
+    }): ResolvedReferenceView;
+    /** 那一段会话的当前面（§二）。**调用方要先过 `resolve`** */
+    surface(sessionId: string): SessionSurfaceView | undefined;
+}
+/**
+ * `GET /api/sessions/:id/reference-candidates` —— 打 `@:` 那一刻面板该列哪几段。
+ *
+ * `:id` 做两件事，同 `tasks.ts` 的那两件：**认门**（不存在的会话 404，不回一份空
+ * 清单冒充「没有可引用的会话」），以及**真的参与判定** —— 自己不在候选里、
+ * 血缘链从它算起、亲和度按它绑的工作区排。
+ *
+ * ## 会话库起不来时 503，不是空清单；而且 503 **排在 404 前面**
+ *
+ * 判据同 `no-goal-store`（`goal/handlers.ts`）：「这个宿主没有会话库」和
+ * 「一段可引用的会话都没有」在界面上是两种画法；而顺序上，没有会话库的进程连
+ * 「认不认识这个会话」都答不出来（`ctx.runtime.sessions` 是**同一个库**），
+ * 那时的 404 是一句碰巧为真的话。
+ *
+ * 浏览器那一侧对两者的处置恰好相同（面板不画，见 `mention/use-candidates.ts`）——
+ * 那是浏览器的选择，不是服务端可以把两句话合成一句的理由。
+ */
+declare function listReferenceCandidates(ctx: ApiContext, res: ServerResponse, sessionId: string, 
+/** `?q=` / `?limit=` 从这儿取 */
+rawUrl: string | undefined, 
+/** 这一次响应用哪个语言渲染（方案 58）。`undefined` = 这条请求没说，沿用进程语言 */
+lang?: Lang): void;
+/**
+ * `GET /api/sessions/:id/file-candidates` —— 打 `@`（后面不是 `:`）那一刻
+ * 面板该列哪几个文件（方案 63）。
+ *
+ * ## 和 `reference-candidates` 同一条路由判据的两处小差异
+ *
+ * 1. **没绑工作区时 409 `no-workspace`**，而不是像会话那条路那样「有库就能答」：
+ *    文件清单压根是**从工作区算出来的**，没有根连「列不出来」这一档都不存在。
+ *    409 而不是 404：这个会话认得，是它的**状态**（还没选地盘）给不出答案 ——
+ *    同 `workspace-locked` 那条的拆码判据。
+ * 2. **`?q=` 过滤在 runtime 那一侧**（`EpochRuntime.workspaceFiles.candidates`），
+ *    判据同会话那条路的「过滤在 SQL 里」：拉一池子回来再在前端筛，
+ *    池子之外的永远搜不到而且屏幕上没有提示。
+ *
+ * 候选**已经是「提交时会被认出来」的那一批**（`@` 表达不出来的路径 runtime 已
+ * 经去尾，只把条数带回来 —— 见 `WireFileCandidatesResponse.unmentionable`）。
+ * 服务端这里一个字都不再筛：再筛一遍就是给同一件事第二个答案。
+ */
+declare function listFileCandidates(ctx: ApiContext, res: ServerResponse, sessionId: string, 
+/** `?q=` / `?limit=` 从这儿取 */
+rawUrl: string | undefined, 
+/** 这一次响应用哪个语言渲染（方案 58）。`undefined` = 这条请求没说，沿用进程语言 */
+lang?: Lang): void;
+/** {@link attachMentions} 的结果 */
+interface AttachedMentions {
+    /** 真正发给引擎的那条消息。一个提及都没有时 === 传进来的那条 */
+    message: EpochUserContent;
+    /** 逐段一条会话收据。**一段都没引用时是空数组**，调用方据此决定那个键要不要出现 */
+    references: readonly WireSessionReference[];
+    /** 逐个一条文件收据。**一个都没提时是空数组**，判据同上面那个键 */
+    files: readonly WireFileReference[];
+}
+/**
+ * 把这条消息里的 `@` 提及（文件 + 会话）解析成部件，塞在正文**前面**
+ * （方案 53 §二 + 方案 63）。
+ *
+ * ## 三条顺序上的判据
+ *
+ * 1. **抽取读的是用户敲的那一行**，也就是这条消息开头那段文本。数组那一支
+ *    只看第一个部件（同 `commands.ts` 的 `leadingText`）—— 输入框拼数组时文本
+ *    永远在最前面。
+ * 2. **部件排在文本前面**，逐字同 TUI（`app.tsx` 的 `handleSubmit`）：
+ *    模型先看见「这是哪个文件 / 哪段会话」再看见问题，和「工具结果先于追问」
+ *    同一个顺序。
+ * 3. **这一步排在斜杠命令展开之后**（见 `api.postMessage`）。反过来的话，
+ *    展开那一侧的 `leadingText` 拿到的第一个部件是附件而不是文本，
+ *    于是**斜杠命令悄悄失效** —— 而屏幕上没有任何区别。
+ *
+ * ## 预算：文件先吃、会话后到，两者共享同一本 200KB 的账（方案 63）
+ *
+ * 顺序逐字同 core 的 `resolveMentions`：会话的当前面动辄几十 KB，而文件提及是
+ * 高频的那一种。反过来的话，一次 `@:某个长会话 @a.ts @b.ts` 会让两个小文件
+ * 双双 `budget-exceeded` —— 而用户显然更想要那两个文件。
+ *
+ * ⚠️ **从 2026-08-26 起这条路上有两个消费方了**：`usedBytes` 不再从 0 起算，
+ * 会话那一半排在文件那一半**之后**，拿到的预算是扣掉文件之后的余额。
+ */
+declare function attachMentions(ctx: ApiContext, sessionId: string, message: EpochUserContent): AttachedMentions;
+
 /**
  * 一个会话自己那三样（模型 / 权限档 / plan 模式）在**服务端眼里**的样子
  * （[方案 30](../../../../docs/verify/VERIFY_RECORD-30-web-multi-session.md) §六，2026-08-16）。
@@ -1546,6 +1926,51 @@ interface SessionHistoryFacts {
         }[];
     }[];
 }
+/**
+ * 「这段会话的上下文预算怎么花的」+「现在压一次」—— `/context` 和 `/compact`
+ * 那两条命令在 web 上的底座（2026-08-26）。
+ *
+ * ## 为什么和上面 {@link SessionHistoryFacts} 分开，而不是把它加宽
+ *
+ * 两者都要 `getHistory()`，但**要的是同一串东西的两个不同投影**：那一份问
+ * 「有没有 `type: 'image'` 的 part」，这一份要 `content` 那个文本投影去估 token。
+ * 把 `content` 加进那一份的代价是换模型那条路上凭空多出一个它不看的字段 ——
+ * 而收窄镜像这件事的全部意义就是「只借用得到的那几格」。
+ *
+ * ⚠️ **`compact()` 在这儿而不在别处，因为它换掉的是 `AgentSession.history`**
+ * ——「下一轮送进模型的是什么」。它**不动会话库**，所以 `GET /messages`
+ * 压完之后一行都不会少（判据全文在 `WireCompactResponse` 上）。
+ */
+interface SessionContextFacts {
+    /**
+     * 历史的**文本投影**。`content` 就是那个投影本身（见 core 的 `EpochMessage`），
+     * 拼起来算 token 比逐条估更接近真实发出去的量。
+     */
+    getHistory(): readonly {
+        content: string;
+    }[];
+    /** 手动压一次。三种结局（没跑 / 跑了没压动 / 压了）全在返回值里，见 `WireCompactResponse` */
+    compact(instruction?: string): Promise<{
+        ran: boolean;
+        before: number;
+        after: number;
+        reason?: string;
+    }>;
+}
+/**
+ * **这个会话的循环**在服务端眼里的样子。只借 `contextBreakdown` 一件事。
+ *
+ * ⚠️ **别拿它去 `run()`**，runtime 的 `LiveSession.agent` 上那段警告一字不改地
+ * 适用：开一轮必须经过 `AgentSession`（历史累积 + 持久化 + 审批桥），
+ * 绕过去的表现是「聊完之后重开这个会话，刚才那几轮不见了」。镜像上只有这一个
+ * 方法，正是为了让那条路在这一层**够不着**。
+ */
+interface SessionLoopView {
+    contextBreakdown(opts: {
+        historyText: string;
+        toolSource?: (name: string) => string | undefined;
+    }): ContextBreakdown;
+}
 
 /**
  * 这个会话**此刻**用哪个模型 —— `GET` / `POST /api/sessions/:id/model`
@@ -1727,6 +2152,214 @@ interface RuntimeModel {
     };
 }
 
+/**
+ * 插件那一页的六条端点（方案 59 §六 E2，2026-08-21）：
+ *
+ * ```
+ * GET  /api/plugins                    装着的 + 市场里有什么 + pendingRestart
+ * POST /api/plugins/install/preview    {ref}          → 将安装什么，一个字节都不写
+ * POST /api/plugins/install            {ref, token}   → 真装
+ * POST /api/plugins/update/preview     {name}         → 更新会带来什么
+ * POST /api/plugins/update             {name, token}  → 真更新
+ * POST /api/plugins/uninstall          {name}         → 卸载
+ * ```
+ *
+ * ## ⚠️ 这一层**一条策略判断都没有**
+ *
+ * 谁能装（清单里那些）、装什么（`<市场>/<插件>`）、远程那一档开没开、要不要重启 ——
+ * 四个问题的答案全在 `EpochRuntime.plugins` 那一片里（判据全文在
+ * `runtime/src/plugin-control.ts` 的文件头四节）。这个文件只做三件事：
+ * 把请求体收窄成那一片认得的形状、把结局投影上网线、外加下面那**一道闸**。
+ *
+ * 在这儿重判一次的下场是「同一个问题两个答案」——而那两个答案分叉的那天，
+ * 界面上是一条画成可点、点了却被拒的行（判据同 `PluginSearchHit.installable`
+ * 为什么不从结果里剔掉远程那条）。
+ *
+ * ## ⚠️ 那一道闸：**五条 POST 在回环之外一律 403**，这是这个文件的正题
+ *
+ * 判据全文在 protocol 的 [wire-plugin.ts](../../protocol/src/wire-plugin.ts) 文件头
+ * 第二节，这里记它对这一层的四条直接后果：
+ *
+ * 1. **`ctx.lanExposed` 为真时 403 `plugin-write-lan-exposed`，一个字节都不写。**
+ *    装一包插件会落下 `hooks.json` 和 `mcp.json`，那两样**起子进程** ——
+ *    下一程启动时照着跑。往 `~/.epoch/agents/` 落一份 md 只影响模型看到的字，
+ *    这一条影响这台机器上会跑起什么进程，所以它比 `role-add.ts` 那道**还远一格**；
+ * 2. **`install/preview` 也吃这道闸，虽然它一个字节都不写**：`allowRemote: true`
+ *    的部署上，预览一条远程条目会 spawn `git clone --depth 1` 到 staging。
+ *    按「写不写盘」切一刀会漏掉它；
+ * 3. **那道闸在读请求体之前**，同 `addRole`：被拒的那一发连正文都不该被解析；
+ * 4. **`GET` 刻意不挡。** 那一份里是插件名 / 版本 / 目录路径，和
+ *    `GET /api/sessions/:id/capabilities` 早就在发的那些同一档 —— 而挡掉它的
+ *    唯一后果是那一页在 LAN 那一档下一片空白，
+ *    偏偏那时用户最想知道的就是「我装了什么、生效了没有」。
+ *    （对比 `GET /api/mcp/config` 为什么连读都挡：那份文件里的 `env` 是明文密钥。）
+ *
+ * ## ⚠️ 这一片可以整个不存在 —— 503 `no-plugin-control`
+ *
+ * `runtime.plugins` 在宿主没给 `hostMarketplaces` 时是 `null`，而那**不是**
+ * 「底下那层起不来了」，是「宿主没打算给用户这条路」（判据在 `build.ts` 那一格的
+ * JSDoc 上）。六条一律 503，判据同 `no-goal-store`：那是一句关于**这个部署**的
+ * 真话，而一份「装了 0 个插件」的空列表会让用户去找一个不存在的安装按钮。
+ *
+ * ⚠️ **默认的 `epoch web` 就落在这一档上**（不给 `--plugins` 就不传
+ * `hostMarketplaces`）。那一格 2026-08-21 答掉了：`epoch web --plugins` 才接上
+ * （传 `{ sources: [] }`），**默认关**，判据在
+ * [验收记录](../../../docs/verify/VERIFY_RECORD-59-plugin-page.md) 第六章。
+ *
+ * ## 为什么单开一个文件
+ *
+ * 同 [role-add.ts](./role-add.ts) 从 `capability.ts` 里搬出来那次，**刀口按题目下
+ * 不按行数**：那个文件答的是「能力页那三栏取什么数」，这一份答的是「怎么往这台
+ * 机器上装一包扩展物」。而且这一份带着一整套结构镜像 + 一道闸门 + 七档拒绝的映射。
+ *
+ * ## 进程级，所以 URL 上没有 `:id`
+ *
+ * 落点是 `~/.epoch/plugins/`（一个进程一份），判据逐字同 `reconnectMcp` /
+ * `importSkills` / `addRole`：挂在 `/sessions/:id/` 下面会得到一条名字是会话级、
+ * 行为是进程级的端点，比不一致更坏。
+ *
+ * ## 文案是**第三种形态**，不是 `sendError`（方案 58 §1.2 那条 📮）
+ *
+ * `detail` 走的是 **200 响应体**，而它在 **runtime / core** 里现渲染
+ * （`plugin_control.*` 那几条 + core 那些安装失败原因），所以 `lang` 要从这一层
+ * 一路穿到 `PluginControlView` 的每一个方法上 —— 漏一处的表现是英文界面上
+ * 装插件失败拿到一句中文。
+ */
+
+/** 六类扩展物各贡献了几条（core 的 `PluginCounts`，不能直接 import） */
+interface CountsView {
+    commands: number;
+    roles: number;
+    skills: number;
+    hooks: number;
+    denyRules: number;
+    mcpServers: number;
+}
+/** `PluginListEntry`（runtime）的镜像。`marketplace` / `counts` 是**可选**，见投影那两行 */
+interface PluginEntryView {
+    name: string;
+    version: string;
+    source: string;
+    sourceType: WirePluginSourceType;
+    path: string;
+    linked: boolean;
+    enabled: boolean;
+    installedAt: number;
+    marketplace?: string;
+    active: boolean;
+    counts?: CountsView;
+}
+/** `PluginSearchHit`（runtime）的镜像 */
+interface PluginHitView {
+    marketplace: string;
+    ref: string;
+    entry: {
+        name: string;
+        description?: string;
+        source: string;
+        category?: string;
+        keywords?: readonly string[];
+    };
+    sourceType?: WirePluginSourceType;
+    installable: boolean;
+}
+/** `InstallPreview`（core，经 runtime 原样透出）的镜像 —— 「将安装什么」那一屏的内容 */
+interface PluginPreviewView {
+    manifest: {
+        name: string;
+        version: string;
+        description?: string;
+        author?: {
+            name: string;
+        };
+        homepage?: string;
+    };
+    source: {
+        raw: string;
+        type: WirePluginSourceType;
+        sha256?: 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;
+    };
+    conflict?: {
+        name: string;
+        version: string;
+    };
+}
+/** 七档拒绝的共同形状（runtime 的 `PluginRefusal`） */
+interface RefusalView {
+    ok: false;
+    reason: WirePluginRefuseReason;
+    detail: string;
+}
+type PreviewOutcomeView = {
+    ok: true;
+    preview: PluginPreviewView;
+    token: string;
+} | RefusalView;
+/**
+ * 装 / 更新的结局。
+ *
+ * ⚠️ **`record` 上刻意只借了一个 `name`**，尽管 runtime 那边交回来的是一整条
+ * 安装记录：那一条上**没有 `active`**（它是 `list()` 现算的），而这一层要发给
+ * 界面的正是那一格。所以成功之后回头 `list()` 里查一遍才是唯一说得准的做法 ——
+ * 借宽了只会让下一个人顺手拿它拼一个 `active: false`，而更新一个**本来就在生效**
+ * 的插件时那句话是假的。判据在 `WirePluginActionResponse.entry` 上。
+ */
+type InstallOutcomeView = {
+    ok: true;
+    record: {
+        name: string;
+    };
+} | RefusalView;
+type ActionOutcomeView = {
+    ok: true;
+    detail: string;
+} | RefusalView;
+/**
+ * `PluginControl`（runtime）在服务端眼里的样子 —— **只有那六个动词加一格布尔**。
+ *
+ * 镜像里只有它们，于是这个包**写不出** core 的 `setPluginEnabled`
+ * （停用一个插件会静默拿掉别人正依赖的一批命令，正当性和「装 / 卸」不是一回事）、
+ * 也写不出「往任意路径装一个插件」——那不是靠 review 盯住的，是编译期的事
+ * （同 `SkillImportControlView` 只有两个动作、`RoleWriteControlView` 只有 `add`）。
+ *
+ * ⚠️ 每个方法都带 `lang?`。**镜像上漏一格不一定会红**（多一个可选参数是宽化，
+ * `EpochRuntime` 照样满足这份镜像），而漏了的表现是这一层递不出去、一声不吭
+ * 地回中文 —— 判据逐字同 `RoleWriteControlView.add` 上那条 ⚠️。
+ */
+interface PluginControlView {
+    list(): readonly PluginEntryView[];
+    /** 空关键词 = 全部。**这一层永远只传空**，搜索在浏览器里做（判据在 wire 那份文件头） */
+    search(keyword?: string): readonly PluginHitView[];
+    preview(ref: string, lang?: Lang): Promise<PreviewOutcomeView>;
+    install(ref: string, token: string, lang?: Lang): Promise<InstallOutcomeView>;
+    previewUpdate(name: string, lang?: Lang): Promise<PreviewOutcomeView>;
+    update(name: string, token: string, lang?: Lang): Promise<InstallOutcomeView>;
+    uninstall(name: string, lang?: Lang): Promise<ActionOutcomeView>;
+    readonly pendingRestart: boolean;
+}
+/**
+ * 装着的一条 → 网线上那一行。
+ *
+ * `marketplace` / `counts` 缺席时下发 **`null` 而不是省掉这个键**，判据同
+ * `WireSkillImportEntry.conflict`：两格在 wire 上写成必填，于是「服务端忘了转
+ * 这一格」会当场编译不过。而 `counts` 漏掉的表现是一个生效中的插件在界面上
+ * 「什么都不带」。
+ */
+declare function toWirePluginEntry(entry: PluginEntryView): WirePluginEntry;
+
 /**
  * 「我们支持哪几家、这一家有哪些模型」 —— `GET /api/providers` 和
  * `POST /api/providers/:type/models`。
@@ -1817,7 +2450,7 @@ interface RuntimeModelCatalog {
 
 /**
  * `WebRuntimeView.schedules` —— **server 从 runtime 借的定时任务那一片**
- * （[方案 45](../../../../.agents/plans/45-scheduled-automation-plan.md) PR-3）。
+ * （[方案 45](../../../../docs/verify/VERIFY_RECORD-45-automation.md) PR-3）。
  *
  * ## 为什么是一份结构镜像，而不是 `import type { ScheduleControl }`
  *
@@ -1922,11 +2555,22 @@ interface ScheduleCapabilityView {
 /**
  * 定时任务那一片能力。`EpochRuntime.schedules` 结构上正好满足它。
  *
- * ⚠️ **不可为 null**：底下只有一张 SQLite 表和一次平台探测，没有起不来的可能
- * （`build.ts` 上那个字段的 JSDoc 写着同一句）。本平台没有 OS 后端时
- * `capability()` 如实说 `backend: null` —— 那是一个答案，不是一个缺失的能力。
+ * ⚠️ **这一格不可为 null，但「不为 null」不等于「用得了」**（2026-08-26 改准）。
+ * 原来这里写着「底下只有一张 SQLite 表和一次平台探测，**没有起不来的可能**」
+ * —— 后半句是假的：那张表就是 `sessions.db`，打不开的时候这一片一条都列不出来。
+ * 所以多了 {@link ScheduleControlView.storeAvailable} 那一格，十条端点**先过它**
+ * （`handlers.ts` 的 `schedulesOf()`，503 `no-schedule-store`）。
+ *
+ * 本平台没有 OS 后端时 `capability()` 如实说 `backend: null` —— 那是一个答案，
+ * 不是一个缺失的能力；那一格和这一格答的是两件事，别合并。
  */
 interface ScheduleControlView {
+    /**
+     * 底下那张表打开了没有。**同步的** —— 十条端点要在碰 store 之前判得出来。
+     *
+     * `false` 时下面每个方法都会抛，所以调用方**必须先看这一格**。
+     */
+    readonly storeAvailable: boolean;
     list: () => ScheduleDefinition[];
     get: (id: string) => ScheduleDefinition | undefined;
     /** 某条任务最近几次运行，最新的在前 */
@@ -1983,6 +2627,20 @@ interface BoundWorkspace {
     /** `trusted: false` = 这个目录的指令文件**不进** system prompt */
     trust: TrustView;
     projectContext: {
+        /**
+         * **项目根** —— `resolveRootDir(workDir)` 的结果（仓库根，找不到就是启动目录）。
+         *
+         * ⚠️ **和上面那个 `workspace.root` 不是同一个值**，别互相顶替：后者是
+         * `resolve(workDir)`（用户敲 `epoch` 那一刻所在的目录），两者在
+         * 「在子目录里起的那次会话」上不同。
+         *
+         * 2026-08-21 加进这份镜像的（方案 53 PR-4）：`@:` 那条路要按工作区算候选和
+         * 可读范围，而**写入侧往 `sessions.cwd` 里写的是这一个**（判据在 core 的
+         * `SessionManager.getLatestByCwd` 和 `session/authorization.ts` 的 `workspaceCwd`
+         * 上）。给 `workspace.root` 的表现是**一条候选都列不出来**，
+         * 而屏幕上只是一个空面板 —— 没有任何一处会报错。
+         */
+        rootDir: string;
         /** 真加载了的那几份 */
         instructions: ReadonlyArray<{
             path: string;
@@ -2086,7 +2744,9 @@ interface WorkspaceView {
  * 安全中心的取数与投影 —— `GET /api/sessions/:id/security`（方案 42 PR-3）。
  *
  * 不在 [api.ts](./api.ts) 里，同 [capability.ts](./capability.ts) 的理由：那个
- * 文件是「一个端点一个函数」，而这里有五份 runtime 能力的**结构镜像**加六段投影。
+ * 文件是「一个端点一个函数」，而这里是一叠 runtime 能力的**结构镜像**加同样一叠
+ * 投影函数。（这两个数原来写死成「五份 / 六段」，2026-08-27 加审批缓存那一格时
+ * 双双变成假话 —— 改成链到下面的声明本身，同铁律 14 那条「要么写准，要么别写数字」。）
  *
  * ## 结构镜像，不是 import
  *
@@ -2113,7 +2773,9 @@ interface WorkspaceView {
  *
  * ## 「进程有什么」和「这个会话有什么」
  *
- * 权限规则、托管锁、审计流水、策略目录四样今天是**进程级**的。前三样的判据在
+ * 权限规则、托管锁、审计流水、**审批缓存**、策略目录五样今天是**进程级**的。
+ * （审批缓存那一格是 2026-08-27 加的，它和前三样共用同一条判据 —— 见下一句。）
+ * 前四样的判据在
  * core 的 [permission/shared.ts](../../core/src/permission/shared.ts) 文件头：
  * 它们是关于**用户**和**这台机器**的事实，跟着会话走反而会说假话（审批缓存
  * 分了家，「总是允许」在第二个会话上白点；流水分了家，这一屏会漏掉除引导会话
@@ -2174,7 +2836,7 @@ interface WorkspaceView {
  * 这个进程没在跑那段会话（只剩历史 / 被冷却）时退回进程那一份，那仍然是一句
  * 真话，判据逐字同 `permissionState()` 那条兜底。
  *
- * ⚠️ **`rules` / `shadows` / `managed` / `audit` 四样一个都不许跟着搬。**
+ * ⚠️ **`rules` / `shadows` / `managed` / `audit` / `cached` 五样一个都不许跟着搬。**
  * 判据在 core 的 `permission/shared.ts`：它们**没有**跟着会话分家。搬过去的
  * 具体代价是这一屏只剩下这一个会话判过的那几行 ——
  * **一本漏了行的安全流水比没有账更坏，因为它看起来是完整的。**
@@ -2244,6 +2906,29 @@ interface AuditView {
     entries: readonly AuditRowView[];
     dropped: number;
 }
+/**
+ * core 的 `CachedApproval` 的镜像 —— 审批缓存里的一行（2026-08-27）。
+ *
+ * **没有 `ttlMs`**，而这一条和上面四份「漏掉中文」不是同一个理由：它不是散文，
+ * 是引擎侧的一个实现细节（`allow-session` 的有效期）。发过去的话浏览器只能拿它
+ * 算一个「还剩几分钟」，而那个数每一秒都在变、这一屏又没有刷新它的路 ——
+ * 一个一打开就开始撒谎的倒计时。真源在引擎里：`listApprovals()` 每次都先
+ * `prune()`，**过期的根本不在这张表里**。
+ *
+ * `scope` / `decision` 直接钉成网线上那两个联合而不是 `string`，同
+ * {@link AuditRowView} 的 `code` 那条机制：core 那边给缓存多存一档决定而忘了同步
+ * 契约时，**装配那一行当场编译不过**。写成 `string` 的话，新档会一路发到浏览器，
+ * 在界面上显示成一个查不到文案的空白格。
+ */
+interface CachedApprovalView {
+    id: string;
+    toolName: string;
+    target: string;
+    scope: WireCachedApproval['scope'];
+    decision: WireCachedDecision;
+    /** 引擎侧那个字段叫 `createdAt`，网线上叫 `at`（同流水那一列）—— 见投影函数 */
+    createdAt: number;
+}
 /**
  * `PermissionsControl` 的镜像。前五样都是函数，因为它们**每次读都是当前值** ——
  * 审计流水尤其如此，它每判一次就长一条。
@@ -2291,6 +2976,28 @@ interface PermissionsView {
     };
     managed: () => ManagedView;
     audit: () => AuditView;
+    /**
+     * 这个进程记下了哪些弹窗答案（审批缓存，2026-08-27）。
+     *
+     * **和 {@link audit} 一档，跟着进程不跟着会话**（core 的 `permission/shared.ts`）。
+     * 这也是它搭在这一份载荷里、而不是另开一条 `GET` 的理由之一 ——
+     * 判据全文在 `protocol/wire-approval-cache.ts` 的文件头。
+     *
+     * ⚠️ **每次读都是当前值**（同上面五样都是函数）：撤掉一条之后这张表就短一行，
+     * 而那正是撤销那条端点要回读它的原因。
+     */
+    approvals: () => readonly CachedApprovalView[];
+    /**
+     * 撤销一条缓存的决定（2026-08-27）。**判定本体一个字都不在 server** ——
+     * 同下面 `setLevel` 那条：`prune()` → 按 id 删 → `allow-always` 重写盘，
+     * 三步都在 core 的 `ApprovalCache.revoke()` 里。
+     *
+     * 返回类型钉成 `ApprovalRevokeResult` 而不是 `boolean`：runtime 那边把
+     * 「没有权限层」和「这条不在表里」分成了两个码，而它们在界面上是两句完全
+     * 不同的话（一句是「这一节不适用」，一句是「刚才那条已经没了」）。
+     * 收成一个布尔的话，后者会被画成前者的样子。
+     */
+    revokeApproval: (id: string) => ApprovalRevokeResult;
     /**
      * 切到某一档。**判定本体一个字都不在 server** —— 托管挡 bypass、
      * `PermissionManager.setLevel()`、`plan.forget()` 三步都在 runtime 的
@@ -2362,6 +3069,21 @@ interface RuntimeSecurity {
     isolation: IsolationView | null;
     permissions: PermissionsView | null;
     policy: PolicyView;
+    /**
+     * 装配时那份合并后的配置里，沙箱开关那一格（方案 46 §11.3 第四条的后半格）。
+     *
+     * 只镜像 `sandbox.terminal` 这一个键：它是「这次 terminal 的命令包不包」的
+     * **配置事实**，和 {@link RuntimeSecurity.isolation} 那份实测报告是两个正交的
+     * 轴 —— 所以它在载荷上单独一格（`WireSandboxStatus.terminalEnabled`），
+     * 不并进后端那一行、也不并进 `covers` / `excludes` 那两张常量清单（判据逐字
+     * 同 `epoch doctor` 的「开关」那一行）。`EpochRuntime.config` 结构上正好
+     * 满足它，同其余几份镜像的机制：对不上就是装配那一行编译不过。
+     */
+    config: {
+        sandbox?: {
+            terminal?: boolean;
+        };
+    };
 }
 /**
  * 五块一次取齐。
@@ -2579,8 +3301,24 @@ interface LiveSessionView {
      * 换模型那条路要问「**这段**对话里有没有图片」。写成交集而不是各借一个字段，
      * 判据同它原来在 `WebRuntimeView.session` 上那句：它们说的是**同一个对象**，
      * 拆成两个字段的话装配那边可以只填其中一个。
+     *
+     * ⚠️ **2026-08-26 起又多一个 {@link SessionContextFacts}**（`/compact` 那条路要
+     * `compact()`，`/context` 那条路要 `getHistory()` 的**文本**投影）。同一条判据第三次
+     * 用上：三样说的是同一个对象，拆成三个字段的话装配那边可以只填其中一个。
      */
-    readonly session: HubSession & SessionHistoryFacts;
+    readonly session: HubSession & SessionHistoryFacts & SessionContextFacts;
+    /**
+     * **这个会话自己那个循环**（2026-08-26）。转出来只为一件事：
+     * `GET /api/sessions/:id/context` 要问「现在的上下文预算怎么构成的」，
+     * 而那是循环才答得上的。
+     *
+     * ⚠️ **不是 `EpochRuntime.contextBreakdown`。** 那个 getter 答的恒是**引导会话**
+     * ——它内部拿的是装配时那个 `agent` 和 `session`。拿它去答任意一个 sessionId，
+     * 就是 2026-08-15 从 `WebRuntimeView` 上删掉 `checkpoints` 的那条 bug 原样重演
+     * （方案 30 §9.5）：编译得过、跑得通、只是答错会话，而第二个会话看到的是
+     * 别人的预算构成 —— 且屏幕上没有任何一个字说得出这件事。
+     */
+    readonly agent: SessionLoopView;
     /**
      * **这个会话此刻用哪个模型**。runtime 那边 provider 起不来时一个会话都建不出来，
      * 所以这一格不为 null。
@@ -3204,6 +3942,42 @@ interface WebRuntimeView extends RuntimeCapabilities, RuntimeSecurity, RuntimeSe
      * 而 DELETE / PATCH 回 503 —— 不是假装成功。
      */
     sessions: SessionCatalog | null;
+    /**
+     * `@:` 引用另一段会话那一片（方案 53 PR-4）。SQLite 起不来时为 null。
+     * `EpochRuntime.sessionReferences` 结构上正好满足它。
+     *
+     * ## ⚠️ 借的是**那个收窄面**，不是会话库
+     *
+     * 上面 {@link sessionStore} 是「回放旧会话」的读路，这一格是「把另一段会话塞进
+     * 这一条消息」—— 它只交出候选 / 解析 / 当前面三件事，**交不出任意 SQL**。
+     * 这不是省事：那三件事里最要紧的**可读性判定在 core 里**（和方案 48 共用一处），
+     * 而服务端不许 import core。让服务端自己去 `sessionStore` 上拼一条 SQL 出来，
+     * 等于给 `@:` 开一条绕过那个判定的读取通道 —— 而 `@:` 存在的前提恰恰是
+     * 「它永远不比 `session_search` 宽松」（方案 53 §4.3）。
+     * 判据全文在 `EpochRuntime.sessionReferences` 的 JSDoc 上。
+     *
+     * 为 null 时那条候选端点回 503 `no-session-store`（**不是**一份空清单 ——
+     * 判据同 `no-goal-store`），而发消息那条路上 `@:xxx` 一律得到
+     * `invalid-reference`：说「没找到唯一匹配的会话」比悄悄丢掉那个提及诚实。
+     */
+    sessionReferences: SessionReferencesView | null;
+    /**
+     * `@文件` 补全与解析（方案 63）。`EpochRuntime.workspaceFiles` 结构上正好满足它
+     * —— **对不上就是两边长歪了，装配那一行当场编译不过**。
+     *
+     * ## ⚠️ 不可为 null，判据逐字同 `EpochRuntime.workspaceFiles` 那一格
+     *
+     * 它不依赖任何会起不来的东西：清单 `git ls-files` 失败退 walk，读文件失败有
+     * 各自的码（`FileReadOutcome`）。权限层缺席时它照样在，只是读跳过那道判定。
+     *
+     * ## ⚠️ 它和 {@link sessionReferences} 是同一件事的两半
+     *
+     * 那一格让服务端列会话候选而**交不出任意 SQL**；这一格让服务端列文件候选、
+     * 读正文而**交不出任意 `readFileSync`**。收窄的是同一句话 —— `@` 永远不比
+     * `file_read` 宽松，而判定只有权限层那一份（`toolName: 'file_read'`）。
+     * 服务端这里要读文件就得走 `workspaceFiles.readFile`，没有第二条路。
+     */
+    workspaceFiles: WorkspaceFilesView;
     /**
      * 每会话的工作区绑定（[决定 18](../../../design/web-ui/README.md)）。
      * `EpochRuntime.workspaces` 结构上满足它。
@@ -3238,6 +4012,54 @@ interface WebRuntimeView extends RuntimeCapabilities, RuntimeSecurity, RuntimeSe
      * 「校验不过就什么都不写」这条不变量会分散到两处去守。
      */
     schedules: ScheduleControlView;
+    /**
+     * 目标（方案 52 PR-4）。`EpochRuntime.goalCatalog` 结构上正好满足它 ——
+     * **对不上就是两边长歪了，`cli/src/commands/web.ts` 那一行当场编译不过**。
+     *
+     * ## ⚠️ 借的是 `goalCatalog` 而**不是** `runtime.goals`
+     *
+     * 后者是**引导会话**那一份（`GoalControl`，收窄到一段会话）。拿它去答 URL 上
+     * 那个 sessionId，就是上面 `sessionFactory` 那段 ⚠️ 讲的那条 bug 的形状 ——
+     * 「编译得过、跑得通、只是答错会话」（方案 30 §9.5）。这一格从第一天起借的
+     * 就是按 id 现查的那一份。
+     *
+     * ## ⚠️ 可为 null，而这和上面 `schedules` 那一格刻意不同
+     *
+     * 目标是**落盘的状态**：会话库起不来时它整个不存在，判据逐字同 TUI 那一侧的
+     * 「会话库起不来时 `/goal` 压根不注册」。为 null 时那四条会话级端点回 503
+     * `no-goal-store`（不是一份 `goal: null` —— 那是「这个会话没有目标」，
+     * 两句话在界面上是两种画法），而 dock 那条角标端点回空数组。
+     * 全文在 [goal/view.ts](./goal/view.js) 的文件头。
+     *
+     * ## ⚠️ 它也**不像检查点那样向工厂要**
+     *
+     * 目标没有内存态 —— `GoalService` 每次现读 SQLite，所以一段冷却掉的会话在这
+     * 一格上和活着的一样准。走工厂那条路的话，用户打开一段昨天的会话会看到
+     * 「这个会话还没有目标」，而库里那条正躺在那儿。那张三格对照表在
+     * `goal/view.ts` 里。
+     */
+    goalCatalog: GoalCatalogView | null;
+    /**
+     * 插件那一页（方案 59 §六 E2，2026-08-21）。`EpochRuntime.plugins` 结构上正好
+     * 满足它 —— **对不上就是两边长歪了，`cli/src/commands/web.ts` 那一行当场编译不过**。
+     *
+     * ## ⚠️ 可为 null，而这一档和 `goalCatalog` / `sessions` 那两格**不同**
+     *
+     * 那两个是「底下那层起不来了」（SQLite 没起来），这一个是**「宿主没打算给用户
+     * 这条路」**：`buildRuntime()` 没收到 `hostMarketplaces` 时它就是 `null`，
+     * 而那是刻意的 —— 它是一个真的新攻击面（往 `~/.epoch/plugins/` 里落东西，
+     * 而落进去的 hook / `mcp.json` 下一程会起子进程），所以是**选进来**的，
+     * 不是白送的（判据在 `build.ts` 那一格的 JSDoc 上）。
+     *
+     * 为 null 时六条端点一律 503 `no-plugin-control`（**不是**一份空列表 ——
+     * 判据同 `no-goal-store`：那两句话在界面上是两种画法）。
+     * ⚠️ **`epoch web` 今天就落在这一档上**，见 [plugin.ts](./plugin.js) 文件头那条 ⚠️。
+     *
+     * 借的是**一整片控制面**而不是几个方法，理由同 `schedules`：那一片本来就是一个
+     * 整体（列 / 搜 / 预览 / 装 / 更新 / 卸 + 一格 `pendingRestart`），而拆成散字段
+     * 之后「装完了、还没生效」这条不变量会分散到两处去守。
+     */
+    plugins: PluginControlView | null;
     dispose(): void;
 }
 interface ApiContext {
@@ -3675,10 +4497,12 @@ declare function toWireTask(sessionId: string, info: BackgroundTaskInfo, registr
 declare function collectTasks(sessionId: string, registry: TaskRegistryView): WireTasksResponse;
 
 /**
- * 定时任务那九条端点（[方案 45](../../../../.agents/plans/45-scheduled-automation-plan.md) PR-3）。
+ * 定时任务那十条端点（[方案 45](../../../../docs/verify/VERIFY_RECORD-45-automation.md)
+ * PR-3 九条 + PR-4 那条 `pending`）。
  *
  * ```
  * GET    /api/schedules                              两个 tab 一次取齐
+ * GET    /api/schedules/pending                      还欠着的那几张欠条（PR-4）
  * POST   /api/schedules                              建一条
  * GET    /api/schedules/:id                          一条的全部字段
  * PATCH  /api/schedules/:id                          改一条（含那个开关）
@@ -3904,4 +4728,4 @@ type CreateWebServerResult = {
  */
 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 };
+export { type ApiContext, type AttachedMentions, type AuthGuardOptions, type BindDecision, type BindRequest, type BoundWorkspace, type CatalogDeletion, type CatalogHit, type CatalogRow, type CheckpointSummaryView, type CommandsView, type CreateSessionResult, type CreateWebServerOptions, type CreateWebServerResult, DEFAULT_MAX_ACTIVE_SESSIONS, DEFAULT_MAX_QUEUED_MESSAGES, DEFAULT_RING_CAPACITY, DEFAULT_WEB_HOST, DEFAULT_WEB_PORT, EnvelopeRing, type EpochWebServer, type ExpansionOutcome, type FrameSink, type HubSession, type HubSessionState, type LiveSessionView, MAX_CANDIDATES, MAX_DIFF_BYTES, MAX_DIFF_FILES, MAX_RECORDING_FRAMES, MAX_SKILL_BODY_BYTES, type ModelTurnsView, type PluginControlView, type QueuedMessage, type RewindFilePlanView, type RewindOutcomeView, type RewindPreviewView, type RewindResultView, type RuntimeCapabilities, type RuntimeCheckpoints, type RuntimeCommands, type RuntimeSecurity, type RuntimeSettings, type ScheduleCapabilityView, type ScheduleControlView, type ScheduleCreateView, type ScheduleFireView, type ScheduleRegisterView, type ScheduleSaveView, type ScheduleUpdateView, type SelectionView, type SessionCatalog, type SessionContextFacts, type SessionFactoryView, type SessionHistoryFacts, SessionHub, type SessionHubOptions, type SessionLoopView, type SessionModelView, type SessionPermissionsView, type SessionPlanView, type SessionReferencesView, type SessionRoleView, type SetLevelView, type SetSelectionView, type StartResult, TASK_TAIL_BYTES, type TaskRegistryView, type TrustView, type TurnDecorator, UI_LANG_PARAM, UI_THEME_PARAM, type UiLangPref, type UiPreset, type UiThemePref, type WebRuntimeView, type WorkspaceBindFailure, type WorkspaceBindOutcome, type WorkspaceCheckpoints, type WorkspaceDiffOptions, type WorkspaceView, attachMentions, collectCapabilities, collectSecurity, collectSettings, collectTasks, collectWorkspaceDiff, createAuthGuard, createWebServer, decideBinding, defaultWebRoot, expandUserContent, firstScreenUrl, generateToken, listFileCandidates, listReferenceCandidates, readRewindInput, resolveArtifactPath, toWireCheckpoint, toWireCommand, toWirePluginEntry, toWirePreview, toWireRewindResult, toWireRow, toWireSkillBody, toWireTask, unavailableToHttp };