@mrrisega/dsh-remote 0.7.6-beta.1 → 0.7.6-beta.3

package/clients/dsh-remote/test/bridge-control-priority.test.mjs

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+/**
+ * 隧道发送侧「控制帧快速通道」回归（2026-10-23）。
+ *
+ * 生产事故（手机连不上/断线主因链 #1）：
+ *   手机首屏的 /plugins/?? 聚合包最大 16.33MB。旧发送器把它切成 200KB 分块后在**同一个
+ *   tick 里连续 ws.send**：内核发送缓冲一满，剩余分块全堆进 ws 的内存队列（弱网下十几秒
+ *   的量）。这期间 router 发来的 ws-open，bridge 只需几毫秒就能回，但**回包被排在 16MB
+ *   分块后面** → router 20s 超时（ws_open_timeout），页面一直转圈。
+ *
+ * 本文件用假 socket + 可控调度器锁三条契约：
+ *   ① 大帧传输中插入的 ws-open 回包，在**下一轮**就被发出（不会排到整帧传完之后）；
+ *   ② 发送缓冲高水位以上时停手，控制帧前面最多只有「高水位 + 一片」待发字节；
+ *   ③ 分块信封仍能被接收侧 makeFrameReceiver 完整还原（协议未被改坏）。
+ */
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  CONTROL_FRAME_TYPES,
+  TUNNEL_BULK_HWM_DEFAULT,
+  isControlFrame,
+  makeFrameReceiver,
+  makePrioritySender,
+  tunnelBulkOptionsFromEnv
+} from "../dsh-bridge.mjs";
+
+/** 假 socket：记录每一帧，可选"慢速排空"模型（bufferedAmount 缓慢下降）。 */
+function fakeSocket({ drainPerTick = Infinity } = {}) {
+  const frames = [];
+  let pending = 0;
+  return {
+    frames,
+    rawSend(s) {
+      frames.push(s);
+      pending += s.length;
+    },
+    bufferedAmount: () => pending,
+    /** 模拟一次内核把缓冲排掉一些。 */
+    drain(bytes = drainPerTick) {
+      pending = Math.max(0, pending - bytes);
+      return pending;
+    },
+    get pending() { return pending; }
+  };
+}
+
+function makeScheduler() {
+  const queue = [];
+  return {
+    schedule: (fn) => { queue.push({ fn, kind: "immediate" }); },
+    setTimer: (fn) => { queue.push({ fn, kind: "timer" }); },
+    /** 跑一个排队的回调（模拟一个事件循环轮次）。 */
+    tick() {
+      const job = queue.shift();
+      if (!job) return false;
+      job.fn();
+      return true;
+    },
+    runAll(limit = 5000) {
+      let n = 0;
+      while (n < limit && this.tick()) n += 1;
+      return n;
+    },
+    pending: () => queue.length
+  };
+}
+
+/** 从已发帧里还原出每个分块信封所属的逻辑帧（用真实接收侧实现，顺便守住协议）。 */
+function reassemble(frames) {
+  const out = [];
+  const recv = makeFrameReceiver();
+  for (const raw of frames) recv(raw, (frame) => out.push(frame));
+  return out;
+}
+
+test("契约①：大响应传输中插入的 ws-open 回包在下一轮就发出（不排到整帧之后）", () => {
+  const sock = fakeSocket();
+  const sched = makeScheduler();
+  const sender = makePrioritySender({
+    rawSend: sock.rawSend,
+    bufferedAmount: sock.bufferedAmount,
+    bulkHighWater: TUNNEL_BULK_HWM_DEFAULT,
+    chunkSize: 64 * 1024,
+    schedule: sched.schedule,
+    setTimer: sched.setTimer
+  });
+
+  /** 快速链路：每轮把内核缓冲排空（同时证明"高水位以上才停手"不影响正常链路）。 */
+  const tickDrain = () => { sock.drain(2 * 1024 * 1024); return sched.tick(); };
+
+  // 一条 4MB 的大响应（≈64 个分块）
+  const big = { id: "big", type: "http", status: 200, body: "A".repeat(4 * 1024 * 1024), bodyBase64: true };
+  assert.equal(sender.send(big), true);
+  assert.equal(sock.frames.length, 1, "第一片当场发出");
+  const chunksTotal = Math.ceil(JSON.stringify(big).length / (64 * 1024));
+  assert.ok(chunksTotal >= 60, `应被切成很多片（实际 ${chunksTotal}）`);
+
+  // 让事件循环转几轮（还没传完）
+  for (let i = 0; i < 5; i += 1) assert.equal(tickDrain(), true);
+  const sentBefore = sock.frames.length;
+  assert.ok(sentBefore >= 4 && sentBefore < chunksTotal, `此时应只发了一小部分（${sentBefore}/${chunksTotal}）`);
+
+  // router 的 ws-open 到达 → bridge 处理 → 回包入控制车道
+  sender.send({ id: "w1", type: "ws-open", ok: true, fast: true });
+  const sentAfterControl = sock.frames.length;
+  const pos = sock.frames.findIndex((s) => s.includes('"id":"w1"') && s.includes('"ok":true'));
+  assert.ok(pos >= 0, "控制帧必须已经发出");
+  assert.equal(pos, sentAfterControl - 1, "控制帧应当**立刻**发出（不等当前轮次的剩余分块）");
+  assert.ok(pos < sentBefore + 3, `控制帧位置 ${pos} 必须远早于大帧剩余分块（已发 ${sentBefore}）`);
+
+  // 继续跑完
+  for (let i = 0; i < 5000 && sched.pending() > 0; i += 1) tickDrain();
+  assert.equal(sock.frames.length, chunksTotal + 1);
+  const frames = reassemble(sock.frames);
+  assert.equal(frames.length, 2, "大帧 + ws-open 两帧都应能被接收侧还原");
+  const bigFrame = frames.find((f) => f.id === "big");
+  const ctrlFrame = frames.find((f) => f.id === "w1");
+  assert.ok(bigFrame && ctrlFrame, "两条逻辑帧都要还原出来");
+  assert.equal(ctrlFrame.ok, true);
+  assert.equal(bigFrame.body.length, big.body.length, "分块重组后正文逐字节一致");
+});
+
+test("契约②：发送缓冲高水位以上时停手（控制帧不会被埋进几十秒的队列）", () => {
+  // 慢链路：每发一片，缓冲就积压 100KB（> 64KB 高水位）
+  const sock = fakeSocket();
+  const sched = makeScheduler();
+  const sender = makePrioritySender({
+    rawSend: sock.rawSend,
+    bufferedAmount: sock.bufferedAmount,
+    bulkHighWater: 64 * 1024,
+    chunkSize: 64 * 1024,
+    schedule: sched.schedule,
+    setTimer: sched.setTimer
+  });
+
+  const big = { id: "big2", type: "http", body: "B".repeat(1024 * 1024) };
+  sender.send(big);
+  // 第一片发出后 bufferedAmount = 片长(>64KB) → 下一轮必须停手等排空
+  sched.tick();
+  const afterFirst = sock.frames.length;
+  sched.tick();
+  assert.equal(sock.frames.length, afterFirst, "超过高水位时不得继续灌分块（只能等排空）");
+  assert.ok(sender.stats().waits >= 1, "应记录过背压等待");
+
+  // 此时控制帧到达：它仍然必须立刻出去（控制车道不受批量车道背压影响）
+  sock.drain(10 * 1024 * 1024); // 缓冲排空
+  const beforeControl = sock.frames.length;
+  sender.send({ id: "w2", type: "ws-open", ok: false, code: 1008, reason: "test" });
+  const pos = sock.frames.findIndex((s) => s.includes('"id":"w2"'));
+  assert.equal(pos, beforeControl, "排空后第一时间发控制帧（之前的背压不能把它排到分块后面）");
+});
+
+test("契约③：大帧传输中小帧优先（交互不被整帧传输拖住）；close() 丢弃未发内容", () => {
+  const sock = fakeSocket();
+  const sched = makeScheduler();
+  const sender = makePrioritySender({
+    rawSend: sock.rawSend,
+    bufferedAmount: sock.bufferedAmount,
+    schedule: sched.schedule,
+    setTimer: sched.setTimer
+  });
+  // 大帧刚发出第一片（之后每轮只发一片）
+  sender.send({ id: "big3", type: "http", body: "C".repeat(512 * 1024) });
+  // 传输中插入两条小帧（交互消息 / SSE 块）：必须插在大帧的下一片之前，而不是排在整帧之后
+  sender.send({ id: "i1", type: "ws-msg", data: "hello" });
+  sender.send({ id: "i2", type: "http-chunk", body: "chunk" });
+  const ids = sock.frames.map((s) => {
+    const o = JSON.parse(s);
+    return o.__chunk ? "__chunk" : o.id;
+  });
+  assert.deepEqual(ids.slice(0, 3), ["__chunk", "i1", "i2"], "小帧必须插在大帧的下一片之前");
+  assert.equal(sender.stats().bigChunks, 1, "此时大帧只发了 1 片");
+
+  // close 后：未发内容丢弃，后续 send 返回 false（重连后不能把旧分片发到新连接上）
+  const sock2 = fakeSocket();
+  const sched2 = makeScheduler();
+  const sender2 = makePrioritySender({
+    rawSend: sock2.rawSend,
+    bufferedAmount: sock2.bufferedAmount,
+    schedule: sched2.schedule,
+    setTimer: sched2.setTimer
+  });
+  sender2.send({ id: "big4", type: "http", body: "D".repeat(512 * 1024) });
+  const before = sock2.frames.length;
+  sender2.close();
+  assert.equal(sender2.send({ id: "after", type: "ws-msg", data: "x" }), false, "close 后不再受理");
+  sched2.runAll();
+  assert.equal(sock2.frames.length, before, "close 后不得再发剩余分片");
+});
+
+test("控制帧类型/环境变量解析（纯函数）", () => {
+  for (const t of ["ws-open", "ws-close", "http-abort", "http-end"]) {
+    assert.equal(isControlFrame({ id: 1, type: t }), true, `${t} 必须走控制车道`);
+  }
+  for (const t of ["http", "ws-msg", "http-chunk"]) {
+    assert.equal(isControlFrame({ id: 1, type: t }), false, `${t} 不该抢控制车道`);
+  }
+  assert.equal(isControlFrame(null), false);
+  assert.deepEqual(CONTROL_FRAME_TYPES.slice(0, 2), ["ws-open", "ws-close"]);
+
+  assert.equal(tunnelBulkOptionsFromEnv({}).bulkHighWater, TUNNEL_BULK_HWM_DEFAULT);
+  assert.equal(tunnelBulkOptionsFromEnv({ DSH_BRIDGE_TUNNEL_BULK_HWM_KB: "32" }).bulkHighWater, 32 * 1024);
+  assert.equal(tunnelBulkOptionsFromEnv({ DSH_BRIDGE_TUNNEL_CHUNK_KB: "16" }).chunkSize, 16 * 1024);
+  assert.equal(tunnelBulkOptionsFromEnv({ DSH_BRIDGE_TUNNEL_CHUNK_KB: "abc" }).chunkSize, 64 * 1024, "非法值回默认");
+});

package/clients/dsh-remote/test/bridge-heartbeat-adaptive.test.mjs

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+/**
+ * 心跳自适应回归（2026-10-23）。
+ *
+ * 生产事故（手机频繁断线主因链 #3）：
+ *   固定 20s 心跳 + 固定"丢 2 个 pong 就重连"。DSH 主线程被大任务/大响应占住时，pong 在
+ *   socket 事件里排不上队 → 连续两拍判死 → 重建隧道 → 手机侧全部在途请求断开、页面重连。
+ *   全站 13706 次/天 bridge 断开里有一大批是这么来的。
+ *
+ * 本文件锁「纯函数」契约（真机/集成行为由 bridge 日志与 test:bridge 全量保证）：
+ *   ① 健康链路完全保留旧契约（丢 2 拍才断）；
+ *   ② 本机事件循环延迟高 / RTT 慢 / 已在中断中 → 判定窗口放宽；
+ *   ③ 放宽有上限（默认 4 拍 / 环境变量可调），不会退化成永不重连；
+ *   ④ DSH_BRIDGE_HEARTBEAT_ADAPT=0 可退回旧契约。
+ */
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  HEARTBEAT_LAG_BUSY_MS,
+  HEARTBEAT_MAX_MISSED_CAP_DEFAULT,
+  HEARTBEAT_MAX_MISSED_PONGS,
+  HEARTBEAT_RTT_SLOW_MS,
+  TUNNEL_HEARTBEAT_DEFAULT_MS,
+  __setEventLoopLagForTest,
+  adaptiveHeartbeat,
+  currentEventLoopLagMs,
+  heartbeatStep
+} from "../dsh-bridge.mjs";
+
+const BASE = TUNNEL_HEARTBEAT_DEFAULT_MS;
+
+test("① 健康链路 = 旧契约：收到 pong 就归零，连续 2 拍没 pong 才断", () => {
+  const pong = adaptiveHeartbeat({ pongReceived: true, missedPongs: 5, rttMs: 40, eventLoopLagMs: 1 });
+  assert.equal(pong.missedPongs, 0);
+  assert.equal(pong.terminate, false);
+  assert.equal(pong.intervalMs, BASE, "健康链路 ping 间隔不变");
+  assert.equal(pong.maxMissed, HEARTBEAT_MAX_MISSED_PONGS);
+
+  const one = adaptiveHeartbeat({ pongReceived: false, missedPongs: 0, rttMs: 40, eventLoopLagMs: 1 });
+  assert.equal(one.missedPongs, 1);
+  assert.equal(one.terminate, false, "丢 1 拍不断（旧行为是丢 1 就断）");
+
+  const two = adaptiveHeartbeat({ pongReceived: false, missedPongs: 1, rttMs: 40, eventLoopLagMs: 1 });
+  assert.equal(two.missedPongs, 2);
+  assert.equal(two.terminate, true, "健康链路下连续 2 拍没 pong 仍按旧契约判死");
+
+  // 与旧纯函数 heartbeatStep 在健康链路下结论一致
+  for (const missed of [0, 1, 2, 3]) {
+    const a = adaptiveHeartbeat({ pongReceived: false, missedPongs: missed, rttMs: 40, eventLoopLagMs: 0 });
+    const b = heartbeatStep({ pongReceived: false, missedPongs: missed });
+    assert.equal(a.terminate, b.terminate, `健康链路 missed=${missed} 的判定必须与旧契约一致`);
+  }
+});
+
+test("② 本机繁忙（事件循环延迟 ≥500ms）→ 多给一拍，瞬时卡顿不再判死", () => {
+  const plan = adaptiveHeartbeat({ pongReceived: false, missedPongs: 0, rttMs: 40, eventLoopLagMs: HEARTBEAT_LAG_BUSY_MS });
+  assert.equal(plan.maxMissed, HEARTBEAT_MAX_MISSED_PONGS + 1);
+  assert.ok(plan.reasons.includes("event_loop_busy"));
+  assert.equal(plan.terminate, false);
+  // 第 2 拍仍不断（这正是生产里 DSH 主线程卡 3~5 秒的场景）
+  const second = adaptiveHeartbeat({ pongReceived: false, missedPongs: 1, rttMs: 40, eventLoopLagMs: HEARTBEAT_LAG_BUSY_MS });
+  assert.equal(second.terminate, false, "繁忙时第 2 拍不得判死");
+  // 第 3 拍才断
+  const third = adaptiveHeartbeat({ pongReceived: false, missedPongs: 2, rttMs: 40, eventLoopLagMs: HEARTBEAT_LAG_BUSY_MS });
+  assert.equal(third.terminate, true);
+});
+
+test("③ 慢链路（RTT ≥1s）→ 间隔拉长 + 多给一拍；两者叠加有上限", () => {
+  const slow = adaptiveHeartbeat({ pongReceived: false, missedPongs: 0, rttMs: HEARTBEAT_RTT_SLOW_MS, eventLoopLagMs: 0 });
+  assert.ok(slow.maxMissed > HEARTBEAT_MAX_MISSED_PONGS);
+  assert.ok(slow.intervalMs > BASE, "慢链路 ping 间隔应拉长（减少额外负载）");
+  assert.ok(slow.intervalMs <= 60_000);
+  assert.ok(slow.reasons.includes("rtt_slow"));
+
+  // 繁忙 + 慢链路 + 已在中断中 → 上限封顶，不会无限放宽
+  const worst = adaptiveHeartbeat({
+    pongReceived: false,
+    missedPongs: 1,
+    rttMs: 5000,
+    eventLoopLagMs: 3000,
+    maxMissedCap: HEARTBEAT_MAX_MISSED_CAP_DEFAULT
+  });
+  assert.equal(worst.maxMissed, HEARTBEAT_MAX_MISSED_CAP_DEFAULT);
+  assert.equal(worst.terminate, false);
+  const capped = adaptiveHeartbeat({ pongReceived: false, missedPongs: 3, rttMs: 5000, eventLoopLagMs: 3000 });
+  assert.equal(capped.maxMissed, HEARTBEAT_MAX_MISSED_CAP_DEFAULT);
+  assert.equal(capped.terminate, true, "到了上限那一拍必须判死（不能永不重连）");
+});
+
+test("④ DSH_BRIDGE_HEARTBEAT_ADAPT=0 等价语义：完全退回固定窗口", () => {
+  const plan = adaptiveHeartbeat({
+    pongReceived: false,
+    missedPongs: 1,
+    rttMs: 5000,
+    eventLoopLagMs: 3000,
+    adaptive: false
+  });
+  assert.equal(plan.maxMissed, HEARTBEAT_MAX_MISSED_PONGS);
+  assert.equal(plan.intervalMs, BASE);
+  assert.equal(plan.terminate, true, "退回旧契约：第 2 拍即判死");
+});
+
+test("⑤ 事件循环延迟探针（测试钩子）", () => {
+  assert.equal(currentEventLoopLagMs(), 0);
+  __setEventLoopLagForTest(800);
+  assert.equal(currentEventLoopLagMs(), 800);
+  __setEventLoopLagForTest(-5);
+  assert.equal(currentEventLoopLagMs(), 0);
+});

package/clients/dsh-remote/test/bridge-upstream-refresh.test.mjs

@@ -8,6 +8,10 @@
  * HTTP 失败路径早就会 refreshUpstream，**WS 失败路径之前漏了** —— 而镜像页常先开 WS。
  *
  * 这个用例守住：两条失败路径都必须触发重新发现（否则又回到"只能重启 bridge"）。
+ *
+ * 【2026-10-23 契约变更】ws-open 改为「先快速 ack、再连上游」后，上游建立失败的收尾从
+ *   `{type:"ws-open", ok:false, code:502}` 变成 `{type:"ws-close", code:1011, retryable:true}`
+ *   —— 升级早已完成，再回 ws-open 失败帧没有意义。自愈要求不变：仍必须 refreshUpstream。
  */
 import test from "node:test";
 import assert from "node:assert/strict";
@@ -15,14 +19,28 @@ import { readFileSync } from "node:fs";
 
 const SRC = readFileSync(new URL("../dsh-bridge.mjs", import.meta.url), "utf8");
 
-test("★ WS 打开失败必须触发上游重新发现（不只是回 502）", () => {
-  // 找到 ws.on("error" ...) 的未建立分支
-  const i = SRC.indexOf('ws.on("error"');
-  assert.ok(i > 0, "必须有 ws error 处理");
-  const branch = SRC.slice(i, i + 1200);
-  assert.match(branch, /!session\.opened/, "只对未建立的会话做 502");
-  assert.match(branch, /refreshUpstream\(/, "★ 必须触发重新发现，否则端口变了会一直 502");
-  assert.match(branch, /code: 502/, "行为不变：本次仍然回 502");
+/** 取某个锚点到下一处 `\n}` 的函数体（够做源代码契约断言，不追求通用解析）。 */
+function bodyAfter(anchor, maxLen = 2000) {
+  const i = SRC.indexOf(anchor);
+  assert.ok(i > 0, `找不到锚点：${anchor}`);
+  return SRC.slice(i, i + maxLen);
+}
+
+test("★ WS 上游建立失败必须触发上游重新发现（快速应答后走 ws-close 1011）", () => {
+  // ws.on("error") 的未建立分支 → 统一交给 failUpstream 收尾
+  const errBranch = bodyAfter('ws.on("error"', 900);
+  assert.match(errBranch, /!session\.opened/, "只对未建立的会话做失败收尾");
+  assert.match(errBranch, /failUpstream\(/, "未建立失败必须走统一收尾（不要各写一份）");
+  // failUpstream 内部：重发现 + ws-close（升级已 ack，不能再回 ws-open）
+  const failFn = bodyAfter("const failUpstream =", 2200);
+  assert.match(failFn, /refreshUpstream\(/, "★ 必须触发重新发现，否则端口变了会一直失败");
+  assert.match(failFn, /failAckedWs\(/, "快速应答之后只能 ws-close 收尾");
+  const ackFn = bodyAfter("function failAckedWs(", 600);
+  assert.match(ackFn, /type: "ws-close"/, "收尾帧必须是 ws-close");
+  assert.match(ackFn, /code: 1011/, "ws-close 用 1011(服务端内部错误)");
+  // close 路径也要覆盖「还没 open 就断」：不能只靠 error 事件
+  const closeBranch = bodyAfter('ws.on("close"', 900);
+  assert.match(closeBranch, /failUpstream\(/, "上游没建立就 close 也要触发重发现");
 });
 
 test("★ HTTP 失败路径也要有重新发现（既有能力不得回退）", () => {

package/clients/dsh-remote/test/bridge-ws-open-fast-ack.test.mjs

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+/**
+ * ws-open 快速应答 / 上游建立期间消息不丢 / 上游失败用 ws-close 收尾（2026-10-23）。
+ *
+ * 旧契约：收到 ws-open → 连上游 WebSocket → **等上游 open** 才回 ok。
+ *   上游连不上（桌面端换端口 / 宿主重启）时，手机要等 router 的 20s 超时；
+ *   bridge 发送队列被大响应占住时（见 bridge-control-priority），连"回 ok"都排不上。
+ *
+ * 新契约（本文件锁住）：
+ *   ① 校验通过立刻回 `{ok:true, fast:true}`（同步、<100ms），再连上游；
+ *   ② 上游建立期间手机发来的 ws-msg 进 pending 队列，open 后按序补发（不丢 mux 首帧）；
+ *   ③ 上游最终失败 → 回 `ws-close`(1011, retryable) 而不是干等 20s（升级早已 ack）；
+ *   ④ E2EE 语义不变：带 &e2ee= 的流先校验会话；未知/未验证 → 1008 +
+ *      `retryable:true,action:"rehandshake"`（手机可自动重握手，不用让用户重新解锁）。
+ */
+import assert from "node:assert/strict";
+import http from "node:http";
+import { mkdtempSync, rmSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { setTimeout as delay } from "node:timers/promises";
+
+import { WebSocketServer } from "ws";
+
+// ── 上游假 dsh web：三种升级行为 ───────────────────────────────────────────────
+const upstream = http.createServer((req, res) => { res.writeHead(404); res.end(); });
+const wss = new WebSocketServer({ noServer: true });
+wss.on("connection", (ws) => {
+  ws.on("message", (data, isBinary) => {
+    try { ws.send(data, { binary: isBinary }); } catch { /* 手机侧已断 */ }
+  });
+});
+let upPort = 0;
+await new Promise((resolve) => {
+  upstream.listen(0, "127.0.0.1", () => {
+    upPort = upstream.address().port;
+    resolve();
+  });
+});
+upstream.on("upgrade", (req, socket, head) => {
+  let pathname = "";
+  try { pathname = new URL(req.url || "/", "http://x").pathname; } catch { pathname = ""; }
+  if (pathname === "/ws-slow") {
+    // 上游建立要 400ms：足够断言"ok 已经先回来了"
+    setTimeout(() => {
+      try { wss.handleUpgrade(req, socket, head, (ws) => wss.emit("connection", ws, req)); } catch { /* 手机已断 */ }
+    }, 400);
+    return;
+  }
+  if (pathname === "/ws-reject") {
+    try { socket.destroy(); } catch { /* 忽略 */ }
+    return;
+  }
+  try { wss.handleUpgrade(req, socket, head, (ws) => wss.emit("connection", ws, req)); } catch { /* 忽略 */ }
+});
+
+// ── 环境必须在 import dsh-bridge 之前定好（模块级常量在 import 时求值）────────────
+const tmpDir = mkdtempSync(path.join(os.tmpdir(), "dsh-wsopen-"));
+process.env.DSH_BRIDGE_CONFIG = path.join(tmpDir, ".dsh-config.json");
+process.env.DSH_BRIDGE_UPSTREAM = `http://127.0.0.1:${upPort}`;
+process.env.DSH_BRIDGE_TUNNEL_URL = "ws://127.0.0.1:1"; // 本用例不连隧道
+const bridge = await import("../dsh-bridge.mjs");
+const {
+  __setE2eeForTest,
+  __wsSessionState,
+  handleWsClose,
+  handleWsMessage,
+  handleWsOpen
+} = bridge;
+const e2eeMod = await import("../e2ee-client.mjs");
+
+test.after(() => {
+  try { wss.close(); } catch { /* 忽略 */ }
+  try { upstream.close(); } catch { /* 忽略 */ }
+  try { rmSync(tmpDir, { recursive: true, force: true }); } catch { /* 忽略 */ }
+});
+
+/** 记录 bridge → router 的帧（等价于隧道 send）。 */
+function spy() {
+  const frames = [];
+  const send = (obj) => {
+    frames.push({ ...obj, __at: Date.now() });
+    return true;
+  };
+  return { frames, send };
+}
+
+async function waitFor(label, pred, timeoutMs = 4000) {
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    const v = pred();
+    if (v) return v;
+    if (Date.now() > deadline) throw new Error(`等待超时：${label}`);
+    await delay(10);
+  }
+}
+
+test("① 先把 ok 回给手机（<100ms），再连上游；ok 不等于上游已建立", async () => {
+  const { frames, send } = spy();
+  const t0 = Date.now();
+  await handleWsOpen(send, { id: "fast1", type: "ws-open", path: "/ws-slow", headers: {} });
+  const elapsed = Date.now() - t0;
+  assert.ok(elapsed < 100, `ok 必须立刻回（实测 ${elapsed}ms）`);
+  assert.equal(frames.length, 1, "此刻只有 ws-open 回包，没有上游消息");
+  assert.equal(frames[0].ok, true);
+  assert.equal(frames[0].fast, true, "回包应带 fast:true（可观测：这是快速应答）");
+  // 上游还没建立（400ms 后才 open）
+  await delay(100);
+  assert.equal(__wsSessionState("fast1").opened, false, "100ms 时上游仍未建立");
+  await waitFor("上游 open", () => __wsSessionState("fast1")?.opened === true);
+  handleWsClose(send, { id: "fast1", code: 1000 });
+});
+
+test("② 上游建立期间手机发来的 ws-msg 不丢：排队 → open 后按序补发", async () => {
+  const { frames, send } = spy();
+  await handleWsOpen(send, { id: "fast2", type: "ws-open", path: "/ws-slow", headers: {} });
+  assert.equal(frames[0].ok, true);
+  // 手机拿到 ok 后立刻发（真实 mux 首帧就是这样）：此时上游还没 open
+  handleWsMessage(send, { id: "fast2", data: "first-frame", binary: false });
+  handleWsMessage(send, { id: "fast2", data: "second-frame", binary: false });
+  assert.equal(__wsSessionState("fast2").pending, 2, "两条消息应排队等上游");
+  // 上游 open 后：消息被补发 → echo 回来（顺序必须与发出顺序一致）
+  await waitFor("两条 echo", () => frames.filter((f) => f.type === "ws-msg").length >= 2, 5000);
+  const echoed = frames.filter((f) => f.type === "ws-msg").map((f) => String(f.data));
+  assert.deepEqual(echoed, ["first-frame", "second-frame"], "补发顺序必须与手机发出顺序一致");
+  handleWsClose(send, { id: "fast2", code: 1000 });
+});
+
+test("③ 上游建立失败 → ws-close(1011, retryable)，不再让手机干等 20s", async () => {
+  const { frames, send } = spy();
+  await handleWsOpen(send, { id: "fast3", type: "ws-open", path: "/ws-reject", headers: {} });
+  assert.equal(frames[0].ok, true, "先快速 ok");
+  const close = await waitFor("失败收尾帧", () => frames.find((f) => f.type === "ws-close"), 4000);
+  assert.equal(close.code, 1011);
+  assert.equal(close.retryable, true);
+  assert.match(String(close.reason || ""), /upstream_ws_open_failed/);
+  assert.equal(__wsSessionState("fast3"), null, "失败后会话表应清掉");
+});
+
+test("④ 非法路径仍同步拒绝(400)，不做快速 ok", async () => {
+  const { frames, send } = spy();
+  await handleWsOpen(send, { id: "bad1", type: "ws-open", path: "//evil.example/x", headers: {} });
+  assert.equal(frames.length, 1);
+  assert.equal(frames[0].ok, false);
+  assert.equal(frames[0].code, 400);
+});
+
+test("⑤ E2EE：未知会话 → 1008 + action=rehandshake（手机可自动重握手）", async () => {
+  const mk = Buffer.alloc(32, 7);
+  const svc = new e2eeMod.E2eeService({ enabled: true, mk, profile: "pbkdf2-sha256-600k", salt: "salt-abc", epoch: 0 });
+  __setE2eeForTest(svc);
+  try {
+    const { frames, send } = spy();
+    const sessId = e2eeMod.newSessId();
+    await handleWsOpen(send, {
+      id: "e2ee-locked",
+      type: "ws-open",
+      path: `/ws-echo?e2ee=${sessId}&w=0123456789abcdef`,
+      headers: {}
+    });
+    assert.equal(frames.length, 1);
+    assert.equal(frames[0].ok, false);
+    assert.equal(frames[0].code, 1008);
+    assert.equal(frames[0].retryable, true, "★ 必须显式告诉手机这是可自动重试的");
+    assert.equal(frames[0].action, "rehandshake", "★ 让手机自动重握手，而不是弹「请重新解锁」");
+    assert.match(String(frames[0].reason || ""), /e2ee_session_locked/);
+  } finally {
+    __setE2eeForTest(new e2eeMod.E2eeService({ enabled: false }));
+  }
+});
+
+test("⑥ E2EE 语义保持：已验证会话 → 快速 ok；加密消息解封→上游 echo→重新封装一致", async () => {
+  const mk = Buffer.alloc(32, 7);
+  const salt = "salt-abc";
+  const profile = "pbkdf2-sha256-600k";
+  const svc = new e2eeMod.E2eeService({ enabled: true, mk, profile, salt, epoch: 0 });
+  __setE2eeForTest(svc);
+  try {
+    // 跑 §5.2 握手（与生产同一条路径，只是"手机"在我们进程里）
+    const sessId = e2eeMod.newSessId();
+    const a = e2eeMod.randomB64(32);
+    const { session, ack } = svc.handleHello({ v: 2, type: "e2ee-hello", role: "phone", s: sessId, a: a, salt, profile });
+    const { shk, saltH } = e2eeMod.deriveShk(mk, a, ack.b);
+    const client = new e2eeMod.E2eeSession({ sessId, shk, saltH, profile, epoch: 0 });
+    const probe = client.seal({ kind: "ctrl", dir: "p2b", counter: 0, data: JSON.stringify({ p: "dsh-e2ee-probe-v1", t: 1, c: 0 }) });
+    svc.handleProbe(sessId, probe);
+    assert.equal(session.verified, true);
+
+    const w = "0123456789abcdef";
+    const wsLabel = `/ws-echo?w=${w}`;
+    const { frames, send } = spy();
+    await handleWsOpen(send, {
+      id: "e2ee-ok",
+      type: "ws-open",
+      path: `/ws-echo?e2ee=${sessId}&w=${w}`,
+      headers: {}
+    });
+    assert.equal(frames[0].ok, true);
+    assert.equal(frames[0].fast, true);
+    await waitFor("上游 open", () => __wsSessionState("e2ee-ok")?.opened === true);
+
+    const envP2b = client.seal({ kind: "w", dir: "p2b", counter: 0, data: "ping-加密-你好", wsLabel });
+    handleWsMessage(send, { id: "e2ee-ok", data: JSON.stringify(envP2b), binary: false });
+    const back = await waitFor("b2p 信封", () => frames.find((f) => f.type === "ws-msg" && String(f.data).includes('"k":"w"')), 5000);
+    const envB2p = JSON.parse(String(back.data));
+    const opened = client.open({ kind: "w", dir: "b2p", env: envB2p, counter: envB2p.c, wsLabel });
+    assert.equal(opened.data.toString("utf8"), "ping-加密-你好", "端到端加解密后逐字节一致");
+    handleWsClose(send, { id: "e2ee-ok", code: 1000 });
+  } finally {
+    __setE2eeForTest(new e2eeMod.E2eeService({ enabled: false }));
+  }
+});