dsh-remote-bridge 2.5.1 → 2.6.0

package/lib/index.d.ts

@@ -79,7 +79,32 @@ declare class WorkspaceDatabase {
   readonly trashDir: string;
   private readonly db;
   private closed;
+  /**
+   * 「设备集合或设备权限发生过写」的进程内单调计数。
+   *
+   * ## 为什么需要它
+   *
+   * WebSocket 广播的每一条事件都要确认「这条连接背后的设备还有效吗、scope/root 变了吗」
+   * —— 旧实现是**每条事件查一次库**（`getActiveDevice`）。多条连接 × 持续事件
+   * 就是成百次纯浪费的 SQLite 查询。
+   *
+   * 有了这个计数，`server.ts` 可以只在**它变了**的时候重新水化设备
+   * （特性探测：getter 不存在就退回逐事件查库，所以迟到或缺席都不会更差）。
+   *
+   * ## 语义（与 perf-reader 的 PERF-1 契约一致）
+   *
+   * 「任何改变**设备是否存在 / scope / rootIds** 的写」都要 +1。当前四处：
+   * `exchangePairing` / `updateDevice` / `revokeDevice` / `purgeRevokedDevices`。
+   *
+   * 根（roots）的增删**不** +1：设备记录本身没变；`/roots` 那条路径本来就是实时查库。
+   *
+   * 保守性：宁可多 +1（多一次缓存失效，代价是一次查询），不可漏 +1
+   * （漏了就是「撤销后仍能收事件」—— 那正是 `device-revocation` 要防的事）。
+   */
+  private devicesRevisionCounter;
   constructor(dataDir: string);
+  /** 当前设备状态版本号。用途见字段注释（`server.ts` 的广播缓存失效）。 */
+  get devicesRevision(): number;
   /** 关闭数据库。**幂等** —— 重复调用不抛错。 */
   close(): void;
   /**
@@ -92,8 +117,16 @@ declare class WorkspaceDatabase {
   dumpSchema(): string;
   getSetting(key: string): string | undefined;
   setSetting(key: string, value: string): void;
+  /**
+   * 登记一条授权根。
+   *
+   * @param options.requestId - 发起这次登记的那条 HTTP 请求的 id。
+   *   审计的用途不只是「记下发生了什么」，还要能回答「**哪一次请求**干的」；
+   *   不传（插件启动期登记内置根）时审计行的 `request_id` 为 null。
+   */
   addRoot(inputPath: string, label?: string, options?: {
     allowDuplicate?: boolean;
+    requestId?: string;
   }): Promise<StoredRoot>;
   listRoots(): StoredRoot[];
   getRoot(id: string): StoredRoot | undefined;
@@ -126,11 +159,27 @@ declare class WorkspaceDatabase {
    */
   ensureBuiltinRoot(realPath: string, label: string): Promise<StoredRoot | undefined>;
   removeRoot(id: string): void;
-  createPairing(rootIds: string[], scopes: DeviceScope[], ttlMs?: number): {
+  /**
+   * 生成一枚配对码。
+   *
+   * @param options.requestId - 发起这次请求的 HTTP requestId（审计可追溯）。
+   */
+  createPairing(rootIds: string[], scopes: DeviceScope[], ttlMs?: number, options?: {
+    requestId?: string;
+  }): {
     code: string;
     expiresAt: number;
   };
-  exchangePairing(code: string, deviceName: string): {
+  /**
+   * 用配对码换一枚设备令牌。
+   *
+   * 审计**在事务内**写（FUNC-5）：它是「这台设备被授权了」的唯一留痕，
+   * 与设备行同生共死。审计写不进去 → 整个兑换回滚 → 客户端重试，
+   * 而不是「拿到令牌但库里没有这笔授权的记录」。
+   */
+  exchangePairing(code: string, deviceName: string, options?: {
+    requestId?: string;
+  }): {
     token: string;
     device: DeviceView;
   };
@@ -139,7 +188,18 @@ declare class WorkspaceDatabase {
   private hydrateDevice;
   listDevices(): DeviceView[];
   isDeviceActive(id: string): boolean;
-  updateDevice(id: string, scopes: DeviceScope[], rootIds: string[]): DeviceView;
+  /**
+   * 改一台设备的 scope 与 root 授权。
+   *
+   * 审计**在事务内**写（FUNC-5）：它是「谁的权限被扩大了」的唯一留痕。
+   * 审计失败 → 整个更新回滚。宁可让用户重试，也不能出现「权限已经变宽、
+   * 但没有任何记录说是谁在什么时候改的」—— 那是不可审计的提权。
+   *
+   * @param options.requestId - 发起这次请求的 HTTP requestId（审计可追溯）。
+   */
+  updateDevice(id: string, scopes: DeviceScope[], rootIds: string[], options?: {
+    requestId?: string;
+  }): DeviceView;
   /**
    * 撤销设备 = **直接删除这一行**（用户要求：已撤销的不显示，并自动从数据库中删除）。
    *
@@ -153,7 +213,18 @@ declare class WorkspaceDatabase {
    * - `authenticate` 仍保留 `revoked_at IS NULL` 作为兜底，万一有别处留下的标记行，
    *   它们依然登不进来 —— 两层保险不冲突。
    */
-  revokeDevice(id: string): void;
+  /**
+   * 撤销一台设备 = 删除设备行。
+   *
+   * 审计与删除**在同一事务里**（FUNC-5），且顺序是「先留痕、再删除」：
+   * 审计的 `actor_id` 不带外键，删设备不会把记录带走。反过来若先删后写、
+   * 而写审计失败，就会留下「设备已经没了，但没有任何记录说谁撤的」。
+   *
+   * @param options.requestId - 发起这次请求的 HTTP requestId（审计可追溯）。
+   */
+  revokeDevice(id: string, options?: {
+    requestId?: string;
+  }): void;
   /**
    * 一次性清理历史遗留的「标记式」撤销设备（`revoked_at IS NOT NULL` 的行）。
    *
@@ -171,8 +242,68 @@ declare class WorkspaceDatabase {
    * 干净的办法制造这种行，而它不该走生产代码路径 —— 所以显式开一个测试专用入口，
    * 并起一个自见其明的名字，免得有人把它当成正常 API。
    */
+  /**
+   * 仅供测试：把某台设备的「最后使用时间/创建时间」拨到过去。
+   *
+   * 生产路径没法造出「30 天没动过」的设备（认证一次就刷新 `last_seen_at`），而
+   * `pruneInactiveDevices` 的核心语义恰恰只在这种时间跨度上才看得见。与
+   * `markRevokedForTest` 同样的理由：显式开一个自见其明的测试入口，别让人误当 API。
+   */
+  backdateDeviceForTest(id: string, options: {
+    lastSeenAt?: number;
+    createdAt?: number;
+  }): void;
   markRevokedForTest(id: string): void;
+  /**
+   * 按「最后使用时间」批量清掉长期没动过的设备。
+   *
+   * 「最后使用」取 `last_seen_at`（每次令牌认证成功都会刷新），从没认证过的设备退回
+   * `created_at` —— 否则一条配好就再没开过的设备会永远躲过清理，而那恰恰是用户最想
+   * 一键清掉的那类（换手机、临时配对、旧测试探针）。
+   *
+   * 与 `purgeRevokedDevices` 的区别：后者清的是历史遗留的「标记式撤销」脏行，这里清的是
+   * **仍然有效、但已经不用了**的设备 —— 用户的原话是「一键清理多少天未使用设备」。
+   *
+   * 语义边界（故意这么定）：
+   * - 只删设备行 + 级联的 `device_roots`，不碰审计（审计的 `actor_id` 不是外键）；
+   * - **不删本机正在用的那台**（`keepDeviceId`）：调用方就是它，删掉自己会让当前
+   *   客户端立刻 401，看起来像「点一下清理把手机踢下线了」；
+   * - 天数被夹在 1..3650，避免 `0` 或负数变成「清空所有设备」；
+   * - 返回真正删掉的条数，0 也是一次合法结果。
+   */
+  pruneInactiveDevices(olderThanDays: number, options?: {
+    keepDeviceId?: string;
+    requestId?: string;
+  }): number;
   purgeRevokedDevices(): number;
+  /**
+   * 删掉早于 `cutoffMs` 的幂等回放记录，返回删除行数。
+   *
+   * 由 `retention.ts`（perf-reader）按调度调用，本方法只做 SQL —— 不判断策略、
+   * 不写日志，所以它可以被单独测试。
+   *
+   * 为什么用 `created_at` 而不是加一列 `expires_at`：24 小时的过期**完全**由
+   * `created_at` 推导得出，加列会让每次插入多写一个字段，还多一次 migration 风险。
+   */
+  pruneIdempotency(cutoffMs: number): number;
+  /**
+   * 清理审计：先按时间删，再兜「总数超过 `keepMax` 就删最旧的」。
+   *
+   * ## 为什么是两段而不是一段
+   *
+   * 只按时间删不够：桥可以被一个「短时间高频写入」的场景灌满审计表
+   * （例如每秒几十条 `chat.delta` 对应的写操作），时间窗内的量仍然能压垮库。
+   * 只按数量删也不够：用户可能希望「一年前的都清掉」，而不在乎条数。
+   *
+   * ## `keepMax` 是**下限保护**
+   *
+   * 即使 `cutoffMs` 设成了未来（把全部行都判成过期），也**至少**保留最近
+   * `keepMax` 条 —— 一句写错的调用不该把审计清空。审计被清空本身就等于
+   * 「抹掉证据」，这个方向必须由这一层挡住。
+   *
+   * 返回删除的行数（两段之和）。
+   */
+  pruneAudit(cutoffMs: number, keepMax: number): number;
   insertTrash(record: TrashRecord): void;
   updateTrashStatus(id: string, status: string): void;
   getTrash(id: string): TrashRecord | undefined;
@@ -204,15 +335,56 @@ declare class WorkspaceDatabase {
   private hasRootColumn;
 }
 //#endregion
-//#region src/host/settings-adapter.d.ts
+//#region src/host/settings-namespace.d.ts
+/**
+ * 内核 `settings.describe()` 的命名空间视图（DSH 0.2.x）。
+ *
+ * 字段比 2.6.0 之前多：`autoGenerate` / `applies` / `secrets` 都原样透出，
+ * 手机端要靠 `secrets[].path` 判断「哪些字段是密钥位、只读」，比按键名猜可靠。
+ */
 interface SettingsNamespaceView {
   ns: string;
+  autoGenerate?: unknown;
   schema?: unknown;
   value: unknown;
   base?: unknown;
   user?: unknown;
+  applies?: unknown;
+  secrets?: SettingsNamespaceSecret[];
   revision: number;
 }
+/** 一个密钥位的路径与「是否已设置」；**只有路径，没有值**。 */
+interface SettingsNamespaceSecret {
+  path: string[];
+  set: boolean;
+}
+type SettingsNamespaceReason = 'HOST_READONLY' | 'HIGH_RISK_NAMESPACE';
+/** 手机端看到的单个命名空间：内核视图 + 能不能写 + 为什么不能写。 */
+interface SettingsNamespaceEntry {
+  ns: string;
+  revision: number;
+  schema?: unknown;
+  value: unknown;
+  base?: unknown;
+  user?: unknown;
+  autoGenerate?: unknown;
+  applies?: unknown;
+  secrets?: SettingsNamespaceSecret[];
+  writable: boolean;
+  reason?: SettingsNamespaceReason;
+}
+/**
+ * `GET /api/v1/settings/namespaces` 的响应。
+ *
+ * 刻意**不**透出内核的 `hasDocument`：它对手机端没有决策价值，而响应多一个字段
+ * 就等于契约多一个字段（另一侧已按 `{writable, namespaces}` 定稿）。
+ */
+interface SettingsNamespacesView {
+  writable: boolean;
+  namespaces: SettingsNamespaceEntry[];
+}
+//#endregion
+//#region src/host/settings-adapter.d.ts
 interface ConfigurableProvider {
   provider: string;
   displayName: string;
@@ -377,7 +549,31 @@ interface CustomProviderCapability {
 }
 declare class DshSettingsAdapter {
   private readonly api;
-  constructor(api: SettingsApiProxy);
+  private readonly options;
+  /**
+   * @param options.writeNamespaces 额外允许手机端写入的设置命名空间（精确 ns 或
+   *   `前缀*`），与内置策略（`ui-*` / 以 `locale` 结尾）叠加；默认为空。
+   */
+  constructor(api: SettingsApiProxy, options?: {
+    writeNamespaces?: readonly string[];
+  });
+  /**
+   * 列出全部设置命名空间（通用设置面的读侧）。
+   *
+   * 与 `listProviders()` 的区别：它不理解任何 provider 语义，原样透出内核按插件
+   * 划分的命名空间，由手机端按 `schema` 自己长表单 —— 新装插件不必等 App 发版。
+   */
+  describeNamespaces(): Promise<SettingsNamespacesView>;
+  /**
+   * 按路径改一个命名空间（通用设置面的写侧）。
+   *
+   * 校验顺序是刻意的：ns 策略 → ops 结构 → 内核 describe（host 可写性）→ mutate。
+   * 先验策略既省一次内核往返，也保证「高危命名空间」无论 ops 怎么错都先得到 403。
+   */
+  mutateNamespace(ns: string, ops: unknown, expectedRevision?: number): Promise<SettingsNamespaceEntry>;
+  private get writeNamespaces();
+  /** 内核 settings 服务缺失时给 503（而不是把 `TypeError` 漏成 500）。 */
+  private settingsService;
   listProviders(): Promise<{
     writable: boolean;
     revisionByNamespace: Record<string, number>;
@@ -399,7 +595,33 @@ declare class DshSettingsAdapter {
     api?: string;
     apiKey?: string;
   }): Promise<ProviderModelView[]>;
+  /**
+   * 取一个 provider 的上下文（目录条目 + 设置命名空间 + 当前 profile）。
+   *
+   * ## 为什么加一层「单请求内复用」
+   *
+   * 修复前 `updateProvider()` 会**连续**调它两次（一次在开头做校验、一次在
+   * `createProvider`/`removeProvider` 里），而每次 `providerContext` 都要打
+   * **两次**内核 RPC（`llm.providers` + `settings.describe`）。于是一次 PATCH
+   * 实际可能产生 4~5 次内核往返 —— 而它们问的是**同一份数据**。
+   *
+   * 这里用一个极短的 TTL（默认 1 秒，覆盖「同一请求内」的连续调用）缓存结果。
+   * 为什么不用「请求作用域」的显式传参：那要改每个方法的签名，而调用点散在
+   * router 与 adapter 两处 —— 收益远不抵这次改动。1 秒 TTL 的副作用是：
+   * 同一秒内两次改同一个 provider 时，第二次读到的是第一次之前的快照 ——
+   * 而 `settings.mutate` 有 `expectedRevision` 做真正的并发控制，所以不会写坏。
+   */
+  private readonly providerContextCache;
   private providerContext;
+  /**
+   * 写操作之后**必须**让缓存失效。
+   *
+   * 为什么不能只靠 TTL：`updateProvider` 改完 baseURL 之后，同一个请求尾部的
+   * `listProviders()` 要给出新值。靠 TTL 等 1 秒等于把一个「刚刚改成功」的
+   * 界面回滚成旧值 —— 那会被用户当成「改了没生效」。
+   */
+  private invalidateProviderContext;
+  private loadProviderContext;
 }
 //#endregion
 //#region src/host/dsh-0.2-bridge.d.ts
@@ -1422,6 +1644,31 @@ declare class DshChatAdapter {
   private readonly api;
   private readonly database;
   private readonly commandServices?;
+  /**
+   * 会话 → 可见性快照的短 TTL 缓存。
+   *
+   * ## 为什么需要（这是本文件最热的一处浪费）
+   *
+   * `requireSession()` 会在**几乎每个** API 调用里跑一遍 `listSessions()`，
+   * 而 `listSessions` 一次要打两次内核 RPC（`sessions.list` + `workspace.list`）
+   * 加一次 `database.listRoots()`。也就是说 history / commands / approvals /
+   * models / questions / prompt 每条请求都白花两次内核往返 —— 只为回答
+   * 「这个 session 能不能被这台设备看见」。
+   *
+   * ## 为什么 TTL 是 2 秒（短到近乎无感，长到足以省掉重复）
+   *
+   * 客户端在打开一个会话时会**连续**打四五个接口（历史、审批、提问、命令、模型），
+   * 2 秒足以把这一串并成一两次真实查询。再长就会让「刚建的会话看不到」
+   * 变成一个可感受到的延迟 —— 而那正是我们要避免的另一类 bug。
+   *
+   * ## 缓存的是什么（关键：缓存的是**授权结论**，不是会话内容）
+   *
+   * 只缓存「这个 sessionId 对当前设备可见吗」这一个布尔结论，且按 `principal.id`
+   * 分桶。**不缓存会话正文**：正文会被 `rename`/`archive`/新消息改掉，
+   * 缓存它等于制造陈旧数据；而可见性只随「根授权变没变」与「会话删没删」变，
+   * 两者都是低频且由用户操作驱动的。
+   */
+  private readonly sessionVisibility;
   private readonly sessionRootIds;
   private readonly sessionRootLookups;
   private readonly pendingApprovals;
@@ -1603,6 +1850,15 @@ declare class DshChatAdapter {
    */
   private commandAgent;
   private requireSession;
+  /**
+   * 记一条可见性结论，并顺手把过期条目清掉。
+   *
+   * 为什么在这里做清扫而不是定时器：缓存条目数与「设备数 × 会话数」同阶，
+   * 对单机部署来说是千级 —— 每次写入顺手扫一遍完全够，而且**没有定时器泄漏**。
+   * （本仓的纪律：服务端不引入 `setInterval`，见 `server.ts` 的心跳是唯一的例外，
+   * 且它 `unref` 过。）
+   */
+  private rememberVisibility;
   private requireWorkspace;
   private visibleWorkspaces;
   private requireAuthorizedRoot;
@@ -1633,10 +1889,35 @@ interface AuthServiceOptions {
 declare class AuthService {
   private readonly database;
   private readonly options;
-  private readonly authFailures;
-  readonly pairingAttempts: FixedWindowLimiter;
-  readonly requests: FixedWindowLimiter;
+  /**
+   * 两个「按对端分类」分开计的桶（键 = `<class>:<remoteAddress>`）。
+   *
+   * 阈值刻意**两边一致**：分桶的目的是「互不连坐」，不是「给本机开后门」。
+   * 如果本机侧更宽，那它就成了一条「怎么把自己伪装成本机」的动机 —— 而伪装是免费的
+   * （不发头即可），于是更宽的那一侧等于被取消。
+   * 阈值相等时，攻击者伪装成 local 只会消耗 local 配额，**没有额外收益**。
+   *
+   * `requests`：120/60s。`authFailures`：20/5min。
+   */
+  private readonly authFailuresByPeer;
+  /** 配对兑换：本机与隧道分开。隧道侧公网暴力尝试不该锁死本机的配对。 */
+  readonly pairingAttemptsByPeer: {
+    local: FixedWindowLimiter;
+    tunnelled: FixedWindowLimiter;
+  };
+  readonly requestsByPeer: {
+    local: FixedWindowLimiter;
+    tunnelled: FixedWindowLimiter;
+  };
   constructor(database: WorkspaceDatabase, options?: AuthServiceOptions);
+  /** 这套服务当前的对端分类（`tunnelActive` 走 fail-closed 探针）。 */
+  private peerOf;
+  /** 按对端取请求配额桶。 */
+  requestLimiter(req: IncomingMessage): FixedWindowLimiter;
+  /** 按对端取认证失败桶。 */
+  failureLimiter(req: IncomingMessage): FixedWindowLimiter;
+  /** 按对端取配对尝试桶（`router.ts` 的 exchange 端点用）。 */
+  pairingLimiter(req: IncomingMessage): FixedWindowLimiter;
   /**
    * 隧道是否在跑。探针抛错时**按「在跑」处理**（fail closed）：探针读的是我们自己
    * 对象上的 getter，它抛错意味着状态不可知；状态不可知时放行管理面正是这次修复要
@@ -1849,23 +2130,82 @@ interface TunnelPublicState {
   /** 对外地址，已统一为 `https://` 前缀原文，供配置文本直接使用。 */
   url: string | null;
   running: boolean;
+  /**
+   * 兜底的**英文短消息**（调试/日志用）。
+   *
+   * 2.5.2 起它**已脱敏**：不含完整 URL、不含绝对路径（见 `sanitizeDownloadError`）。
+   * 客户端应优先用 `errorKey` 本地化；这个字段只在没有键可用时兜底。
+   */
   error?: string;
+  /**
+   * 结构化错误键（客户端据此本地化）。渲染优先级 **errorKey > error**。
+   */
+  errorKey?: TunnelErrorKey;
+  /** `errorKey` 的插值参数。 */
+  errorParams?: Record<string, string | number>;
 }
 /** 「创建云隧道」进行中任务的阶段状态，供前端轮询显示进度。`percent=null` 表示该阶段无确定百分比（流动条）。 */
 interface TunnelActivity {
   /** 阶段标识：locating / downloading / unpacking / starting；`idle` 表示当前无进行中任务。 */
   stage: 'idle' | 'locating' | 'downloading' | 'unpacking' | 'starting';
-  /** 人类可读的阶段文案（如「已找到本机二进制，直接复用」）。 */
-  label: string;
+  /**
+   * 阶段文案的 **i18n 键**（不是给人看的句子）。
+   *
+   * 2.5.2 起取代原来的 `label: string`：服务端不再决定用哪种语言说这句话，
+   * 由客户端按自己的界面语言渲染。`''` 表示 idle（无进行中任务）。
+   *
+   * 键清单是**跨端契约**（见 `TunnelStageKeys`），改名会让 UI 显示原始键名。
+   * `''` = idle（没有进行中的任务，UI 不显示进度条）。
+   */
+  labelKey: TunnelStageKey | '';
+  /** 键里的插值参数（如下载进度的 `{ mb, all }`）。 */
+  labelParams?: Record<string, string | number>;
   /** 0-100 的进度百分比；null = 该阶段无法量化（前端显示流动条）。 */
   percent: number | null;
 }
+/**
+ * 隧道阶段文案的 i18n 键 —— **跨端契约，不得随意改名**。
+ *
+ * 客户端（`dsh-companion` / 桌面面板）按这套键查词典。改名 = UI 直接显示键名。
+ */
+type TunnelStageKey =
+/** 正在定位本机二进制。 */
+'tunnelStageLocating' |
+/** 已找到本机二进制，直接复用（不需要下载）。 */
+'tunnelStageBinaryFound' |
+/** 正在从官方 GitHub 下载。 */
+'tunnelStageDownloadGithub' |
+/** 正在从官方 deb 仓库下载。 */
+'tunnelStageDownloadDeb' |
+/** 下载中，带进度：`labelParams = { mb, all }`。 */
+'tunnelStageDownloadProgress' |
+/** 下载完成但**没有校验和可用**：内容未经验证（H5 的可见化）。 */
+'tunnelStageDownloadUnverified' |
+/** 正在解包 deb 并提取二进制。 */
+'tunnelStageUnpackDeb' |
+/** 正在写入二进制并赋执行权限。 */
+'tunnelStageWriteBinary' |
+/** 正在启动 cloudflared 隧道。 */
+'tunnelStageStarting';
+/**
+ * 隧道错误的结构化键。与 `error`（兜底英文短消息）并存：
+ * 客户端渲染优先级 **errorKey > error**。
+ */
+type TunnelErrorKey =
+/** cloudflared 进程退出且没拿到地址：`errorParams = { code, signal }`。 */
+'tunnelErrorExited' |
+/** 下载/解包失败（已脱敏，无参数）。 */
+'tunnelErrorDownload' |
+/** 已经在运行，拒绝重复启动。 */
+'tunnelErrorAlreadyRunning';
 /** 一次 cloudflared 子进程生命周期 + 对外状态机。 */
 declare class CloudflaredTunnelManager {
   private process;
   private url;
   private channel;
   private errorText;
+  private errorKey;
+  private errorParams;
   private listeners;
   private activity;
   /** 当前进行中任务的阶段进度（无任务时 stage 为 idle）。 */
@@ -1888,7 +2228,13 @@ declare class CloudflaredTunnelManager {
   get publicState(): TunnelPublicState;
   /** 订阅状态变化；返回取消函数。 */
   onStatus(cb: () => void): () => void;
+  /** 取消一个状态订阅（onStatus 返回的函数与 waitForUrl 共用）。 */
+  private offStatus;
   private emit;
+  /**
+   * 记录一次错误。`error` 保留脱敏后的短消息（兜底/日志），
+   * `errorKey` + `errorParams` 供客户端本地化（优先级 errorKey > error）。
+   */
   private setError;
   /**
    * 启动一次 Quick Tunnel。
@@ -1896,6 +2242,18 @@ declare class CloudflaredTunnelManager {
    * @param port bridge 监听端口，cloudflared 把外网请求转发到 localhost:port
    */
   startQuick(exe: string, port: number): Promise<TunnelPublicState>;
+  /**
+   * 等待子进程把随机域名打印到 stdout（spawn 后 `url` 通常还要几秒才有）。
+   *
+   * 存在的理由（2.5.2）：`POST /manage/cloudflare/create` 发生在隧道**起来之前**，
+   * 此刻管理面还没被判据 0 关门；一旦在这次请求里等出地址并顺带出令牌配置文本，
+   * 客户端就不必在隧道运行后再打一次 `/manage/config/text`（那时必然 403，
+   * 这正是「一键开隧道+出令牌」失效的根因）。
+   *
+   * 任一条件满足即结算：地址出现 → resolve(url)；进程退出/超时 → resolve(null)
+   * （不抛，调用方据 null 决定要不要让客户端走轮询补一步）。调用方传 AbortSignal 可提前走人。
+   */
+  waitForUrl(timeoutMs?: number, signal?: AbortSignal): Promise<string | null>;
   /** 停止当前隧道。 */
   stop(): TunnelPublicState;
   /** 注入已抓到的地址 + 通道（命名隧道用）。 */
@@ -2020,6 +2378,37 @@ declare class ApiRouter {
   handle(req: IncomingMessage, res: ServerResponse, stripPrefix?: string): Promise<void>;
   private dispatch;
   private dispatchManagement;
+  /**
+   * 打开隧道并（可选）顺带产出配置文本 —— HTTP `POST /manage/cloudflare/create` 与
+   * IM `/tunnel` 命令**共用**这一条实现。
+   *
+   * 抽出来的原因：两条入口的前半段完全一致（确保 cloudflared → startQuick → 等随机域名 →
+   * 建配置文本），差别只在「谁在调用」——HTTP 侧要先把请求体读干净（流会随时间关闭），
+   * 命令侧没有请求体。复制一份会让「一键出令牌」在两条路径上慢慢漂移。
+   *
+   * @param createBody - 已解析的请求体（HTTP 侧）或 `{ configText: true }`（命令侧）。
+   * @param requestId - 审计与配对记录共用的请求 ID。
+   * @param actorLabel - 审计里的操作者标签：`loopback-admin`（本机管理面）或 `im-command`。
+   * @returns 合并了「等到地址」的 state，以及（wantConfig 且拿到地址时）配置文本。
+   */
+  private createTunnel;
+  /**
+   * IM `/tunnel` 命令的宿主侧入口：开隧道并返回一行可粘贴的配置文本。
+   *
+   * 与 HTTP 路径的两点差别：
+   *
+   * 1. **隧道已在运行时直接复用当前地址**，不重复 spawn（第二次 `startQuick` 会撞
+   *    `TUNNEL_ALREADY_RUNNING`，而用户在 IM 里连发两条是很常见的）。
+   * 2. 配置文本的 endpoint 只用隧道地址，设备名缺省由 `buildConfigText` 决定 —— 命令
+   *    不接受参数，所以没有 `endpointLabel` / `rootIds` 的透传面。
+   *
+   * @throws 当 12 秒内没拿到公网地址，或 cloudflared 下载失败时。
+   */
+  openTunnelForCommand(): Promise<{
+    url: string;
+    text: string;
+    deviceName: string;
+  }>;
   /**
    * 隧道状态视图。
    *
@@ -2035,6 +2424,19 @@ declare class ApiRouter {
    * 评估结论见报告：本轮选择「远程一律 403」而不是「远程读得到但 `url` 为 null」，
    * 因为后者需要为状态端点在判据 1 上再开一个口子，而那正是这次修复要消灭的东西。
    */
+  /**
+   * 生成一行可粘贴的 `DSH1:` 配置文本（POST /manage/config/text 与「一键开隧道并出令牌」
+   * 的 create 端点共用，避免两处各写一套配对/兑换/编码逻辑而漂移）。
+   *
+   * 入参字段与 /manage/config/text 的窄格式一致：
+   * - endpoints：显式给出则不再做本机网卡探测（隧道场景必须只塞隧道地址，不能混入 LAN）；
+   * - rootIds / scopes / deviceName / displayName / port：全部可选，缺省沿用原端点口径；
+   * - scopes 缺省是**五个非破坏性默认权限**（不含 files.delete / settings.write），
+   *   调用方若显式传 DEVICE_SCOPES 会放大手机权限，create 一键路径不传。
+   *
+   * 刻意不返回 pairing.expiresAt：那是配对码的十分钟有效期，设备令牌本身不过期。
+   */
+  private buildConfigText;
   private tunnelStateFor;
   private dispatchEntries;
   private dispatchContent;
@@ -2056,6 +2458,31 @@ interface RemoteApiServerOptions {
   chat: DshChatAdapter;
   events: WorkspaceEventBus;
   handle: (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+  /**
+   * 同时允许的 WebSocket 连接数上限（默认 [DEFAULT_MAX_CONNECTIONS]）。
+   *
+   * 为什么必须有：`sockets` 此前是一个无界 Map —— 一个循环重连的客户端就能堆出任意多
+   * 连接，每条都参与广播、每条都查一次库。上限在**鉴权之后**才判定，所以它不会成为
+   * 未鉴权用户可探测的攻击面。
+   */
+  maxConnections?: number;
+  /** 单帧最大字节数（默认 1 MiB）。超限由 `ws` 直接 `close(1009)`。 */
+  maxPayloadBytes?: number;
+  /** 心跳间隔（默认 30 s）。测试传小值，不必干等半分钟。 */
+  heartbeatIntervalMs?: number;
+  /** 单连接事件队列上限（默认 512）。溢出按「丢可重建帧」策略处理。 */
+  socketQueueLimit?: number;
+  /** 发送缓冲高水位（默认 4 MiB）。连续两次越过就 `close(1013)`。 */
+  highWaterMarkBytes?: number;
+  /**
+   * 运行时能力开关，喂给 `connectionReadyData()`。
+   *
+   * 为什么在构造参数里而不是全局变量：能力位是**这台服务端此刻**能做什么，
+   * 同一进程里可能有多个实例（测试、重绑），用实例参数才不会被互相污染。
+   */
+  capabilities?: {
+    jobs?: boolean;
+  };
 }
 declare class RemoteApiServer implements RemoteControl {
   private readonly options;
@@ -2070,8 +2497,15 @@ declare class RemoteApiServer implements RemoteControl {
   private readonly webSockets;
   private readonly eventsAbort;
   private unsubscribeEvents;
-  private broadcastQueue;
+  /** 所有连接的 drain 完成信号；`Promise.all` 它们即可等排空。 */
+  private readonly pendingDrains;
+  private heartbeatTimer;
+  private changeTimer;
   private changing;
+  private readonly maxConnections;
+  private readonly socketQueueLimit;
+  private readonly highWaterMarkBytes;
+  private readonly heartbeatIntervalMs;
   constructor(options: RemoteApiServerOptions);
   start(): Promise<void>;
   stop(): Promise<void>;
@@ -2087,12 +2521,39 @@ declare class RemoteApiServer implements RemoteControl {
   disable(): RemoteOperationView;
   configure(host: string, port: number): RemoteOperationView;
   private scheduleChange;
+  /** 取消还没触发的监听变更。幂等：没定时器就什么都不做。 */
+  private clearChangeTimer;
   private performChange;
   private rebind;
   private bind;
   private createBoundServer;
+  /**
+   * 关掉当前监听与全部连接，**有界**。
+   *
+   * `server.close()` 的回调要等所有连接结束；而**升级过的 WebSocket 不在
+   * `closeAllConnections()` 的管理范围里**（HTTP 层已经不跟踪它了）。于是只要有一条
+   * 连接读不动（暂停读 / 半开），`close()` 就永远等不到回调 —— 插件卸载会挂死。
+   *
+   * 所以这里的顺序是：先礼后兵 —— 发 1012（客户端会看到「服务端重绑」而不是异常断开），
+   * 等一小段宽限期；宽限期到就 `terminate()`，同时让 `close()` 的等待一起收尾。
+   */
   private closeCurrent;
   private handleUpgrade;
+  /**
+   * 心跳循环：每 `heartbeatIntervalMs` 检查一次存活标记。
+   *
+   * 时序要看清：`isAlive` **先读后置假**，并且只在本轮「活着」时才补一次 `ping`。
+   * 于是：
+   * - 本轮活着 → 标记为可疑，再 ping 一次；
+   * - 本轮仍可疑（上一轮 ping 没换来 pong）→ `terminate()`。
+   *
+   * 结果是**连续错过两个周期**才踢人。偶发丢一个包不会误杀在线设备，真正断掉的
+   * （手机切网 / 熄屏后 NAT 表项过期）最多两个周期就清掉 —— 而修复前它只能等
+   * TCP 自己超时，等于「半开连接长期占着额度，还在每轮广播里被白查一次库」。
+   *
+   * `unref()` 必需：这个定时器永不结束，不 unref 会让进程退不掉。
+   */
+  private startHeartbeat;
   /**
    * 把待处理的**审批与提问**补推给刚建立的这条连接。
    *
@@ -2102,15 +2563,78 @@ declare class RemoteApiServer implements RemoteControl {
    * 重连窗口里产生的审批就会静默消失（内核阻塞着等决定、手机上却一片安静）。
    * 重放把「新连接一定能拿到仍待处理的审批」变成**服务端保证**，而不是客户端的义务。
    *
-   * 三个刻意的取舍：
+   * 四个刻意的取舍：
    * - **不 await**：重放要按会话做授权过滤（异步），握手不能为它排队；
    * - **只发这一条连接**：不走 `broadcast`，避免每次有人重连就骚扰所有在线设备；
    * - **失败静默**：重放是补救措施，它出错不该影响这条连接正常收事件。
-   *   客户端侧「连接后/亮屏后主动刷新」仍是兜底，但不再是唯一依赖。
+   *   客户端侧「连接后/亮屏后主动刷新」仍是兜底，但不再是唯一依赖；
+   * - **走连接自己的队列**：重放帧与随后的广播帧必须保序。直接 `socket.send`
+   *   会让「重放的第 2 帧」插到「广播的第 1 帧」前面去。
    */
   private replayPendingInteractions;
-  private broadcast;
+  /** 当前设备授权版本；`database` 还没提供就返回 undefined（退回逐事件查库的旧路径）。 */
+  private devicesRevisionOf;
+  /**
+   * 广播入口：**只做快照 + 入队**，全程同步。
+   *
+   * 这里是宿主事件循环上的热路径 —— 订阅回调里的任何 `await`（查库、查内核、
+   * 发网络）都会反过来把宿主的 `push` 拖住。修复前正是这样：一条全局 promise 链
+   * 串起「事件 × 连接」，一个慢判定让所有事件、所有客户端一起排队，`stop()`
+   * 还得 `await` 那条链。
+   */
+  private enqueueBroadcast;
+  /**
+   * 单连接入队：溢出时按「先丢可重建帧」处理，并给客户端一个 resync 信号。
+   *
+   * 为什么溢出不断连：手机端解码慢一次不该被踢下线（那会触发一条重连风暴，
+   * 而重连风暴又会把刚建好的连接再挤掉）。但「静默丢帧」更糟 —— 客户端会以为
+   * 事件流还连续，于是它手里的状态永远停在丢帧之前。所以丢的时候记一笔，
+   * 随后补发 `connection.resyncRequired`，把「静默」变成「告知」。
+   */
+  private enqueue;
+  /** 保证一条连接只有一个 drain 循环（否则同一连接内的顺序会被打乱）。 */
+  private startDrain;
+  /**
+   * 一条连接的发送循环。
+   *
+   * `await` 只发生在「这条连接自己的准备工作」上（刷新设备身份、判断会话授权）。
+   * 于是慢连接只慢它自己 —— 这正是与修复前的根本区别。
+   */
+  private drain;
+  /**
+   * 记录一次「越过发送高水位」，并安排复查。
+   *
+   * @returns 这条连接是否已经被关掉（调用方据此决定还要不要继续 drain）。
+   *
+   * 两拍才关是刻意的：一次越线可能只是客户端的短暂抖动（切网、GC），
+   * 立刻踢下线会制造重连风暴。但**必须有复查** —— 否则「第二拍」永远不会发生，
+   * 连接就卡在「不发也不关」的僵尸态，比直接断掉更难排查。
+   */
+  private noteHighWater;
+  private sendFrame;
+  /** 清掉这条连接自己的定时器。**必须**在连接被摘掉时调用，否则定时器会拖住进程。 */
+  private clearSocketTimers;
+  private closeBackpressured;
+  /**
+   * 按需刷新这条连接的身份快照。
+   *
+   * 有 `devicesRevision` 时：只有版本变了才查库 —— 正常情况**一件事都不做**，
+   * 而修复前是「每个事件、每条连接都查一次 `getActiveDevice`」。
+   * 没有该 getter 时退回旧行为（逐事件查库）：老数据库上功能不变，只是慢一点。
+   * 这比「广播路径依赖一个可能不存在的 API」安全得多，也让两侧改动可以分批落地。
+   *
+   * @returns 最新身份；设备已被撤销时返回 undefined。
+   */
+  private refreshPrincipal;
   private eventAllowed;
+  /**
+   * 等所有连接排空，**有上限**。
+   *
+   * `stop()` 不能无限等：一条读不动的 socket 会让插件卸载挂死，进而拖住进程退出。
+   * 超时后照样会断开它们（`closeCurrent` 负责），只是不再尝试把队列里的东西送出去 ——
+   * 卸载路径上「送达」本来就不是目标。
+   */
+  private drainAll;
   private trimOperations;
 }
 /** 一条挂在 DSH webserver 上的插件自有路由。 */
@@ -2164,6 +2688,14 @@ interface Config {
   port?: number;
   remoteHost?: string;
   maxUploadBytes?: number;
+  /**
+   * 额外允许手机端写入的设置命名空间（默认空）。
+   *
+   * 精确 ns（`ui-chat`）或通配前缀（`llm-*`）。与内置策略叠加：`ui-*` 与以
+   * `locale` 结尾的命名空间本来就可写；其余默认只读，因为改模型/权限等于把
+   * 遥控器交出去（理由见 docs/project/SECURITY.md）。
+   */
+  settingsWriteNamespaces?: readonly string[];
 }
 interface HostContext extends Dsh02HostServices {
   webServer: Parameters<typeof attachEmbeddedRoutes>[0];