@pi-flash-plugins/pf-wxbot 0.0.0-stage → 0.1.3

package/pi/transport.mjs

@@ -0,0 +1,335 @@
+// transport —— 微信渠道传输，自 PF 仓 wxprobe src/transport.rs **逐条移植**（JS 版）。
+//
+// **结构** —— 对齐 ZCode：JS 单线程下 90s 长轮询 `await` 期间 sendMessage
+// 仍能并发发出（这就是 ZCode 用两条 Rust 线程模拟的形态；JS 的 async 循环
+// 天然就是双任务，无须线程）：
+//
+// ```text
+// [pollLoop] getupdates(90s) ──► batch 队列 ──► 泵 recv()
+// [sendLoop] send(text) 入队 ──► sendmessage
+// ```
+//
+// **游标（§6 坑 2「处理完再写」）**：循环内只在**内存**里推进 cursor，
+// 落盘由 `ack_cursor()` 触发 —— app 处理完一批才 ack。进程中途崩溃则下次
+// 启动从上次 ack 的游标重拉，**可能重复、绝不丢失**（at-least-once）。
+//
+// **生命周期铁律**（pi extensions.md）：transport 只在 `session_start` 起、
+// `session_shutdown` 幂等收（stop()）。stop 不等待在途 90s 长轮询（Rust
+// 「drop 不 join」的 UI 冻结教训，2026-10-24）——置停止标志后自然到点退出，
+// 未 ack 的游标下个轮询者重收（重复而非丢失，方向正确）。
+
+import { get_updates, send_text, parse_updates } from "./poller.mjs";
+import { require_token, config_from_state } from "./config.mjs";
+import { acquire, LEASE_MS, HEARTBEAT_MS } from "./lock.mjs";
+import * as state from "./state.mjs";
+import { Wire, POLL_TIMEOUT_MS } from "./wire.mjs";
+
+export { require_token, config_from_state };
+
+/** 一次 `getupdates` 拉回的消息批。整批一起交付：`next_buf` 是这批处理完
+ * 之后应落盘的游标，app 必须在**全部处理完**后再 ack。 */
+export class Batch {
+  constructor(messages, next_buf) {
+    this.messages = messages;
+    this.next_buf = next_buf;
+  }
+}
+
+/** `errcode:-14 session timeout`：iLink 判这是**过期会话**而非网络抖动。
+ *
+ * 两种来源（都真机踩过）：①换绑后 `buf` 里嵌着旧 bot 的游标（2026-10-23）；
+ * ②PF 重启后拿上一进程的游标续会话、旧长轮询还挂在服务端（2026-10-24：
+ * 重启即全天 -14）。 */
+export function is_session_timeout(msg) {
+  return msg.includes("session timeout") || msg.includes("errcode=Some(-14") || /errcode=-14\b/.test(msg);
+}
+
+/** 指数退避，封顶 30s（Rust `500ms << min(failures,6)` 同式）。 */
+export function next_wait_ms(failures) {
+  return Math.min(500 * 2 ** Math.min(failures, 6), 30_000);
+}
+
+/**
+ * 一拍错误的处置决策（pollLoop 骨架的纯函数化，供单测）：
+ * - `cursor_flush`：拿着旧游标被拒 = 会话还活着，洗掉 buf 用同一 token
+ *   重新接洽即可（模块内部自愈，不打扰用户）；
+ * - `session_dead`：**空游标仍被拒** = 微信服务侧已把 bot 会话作废（长期
+ *   不活动过期）。置位交 app 自动回绑定页（002）；轮询保持低频重试。
+ * - `generic`：网络抖动，退避重试，**不退出**（§6 坑 4：一次失败退出 = bot
+ *   静默死掉）。
+ */
+export function classify_poll_error(has_cursor) {
+  return has_cursor ? "cursor_flush" : "session_dead";
+}
+
+// ---------------------------------------------------------------- 工厂
+
+/** 锁根展示串（避免为展示再引 fs）。 */
+function lock_root_display() {
+  return `${process.env.PI_FLASH_DIR || "~/.pi-flash"}/bots-runtime-locks`;
+}
+
+// ---------------------------------------------------------------- Transport
+
+export class Transport {
+  /**
+   * 起渠道。失败（已被别的轮询者持有锁）时不起任何循环。
+   * deps 可注入（单测）；生产用默认。static 才能触达 #start 私有。
+   */
+  static async spawn(cfg, deps = {}) {
+    const lock =
+      deps.lock ??
+      (await acquire("weixin-polling", cfg.token, cfg.bot_id, {
+        heartbeatMs: deps.heartbeatMs ?? HEARTBEAT_MS,
+        leaseMs: deps.leaseMs ?? LEASE_MS,
+      }));
+    if (!lock) {
+      throw new Error(`另一个轮询者已持有该 bot 的锁，见 ${lock_root_display()}`);
+    }
+    const t = new Transport(cfg, lock, deps);
+    t.#start();
+    return t;
+  }
+
+  constructor(cfg, lock, deps = {}) {
+    this.cfg = cfg;
+    this._lock = lock;
+    this.wire = deps.wire ?? new Wire(state.dump_dir());
+    this.loadState = deps.loadState ?? state.load;
+    this.saveState = deps.saveState ?? state.save;
+    this.getUpdates =
+      deps.getUpdates ??
+      ((token, buf) => get_updates(this.wire, token, buf));
+    this.sendText =
+      deps.sendText ??
+      ((token, from, to, text, ctxToken, clientId) =>
+        send_text(this.wire, token, from, to, text, ctxToken, clientId));
+    this.sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    this.pollTimeoutMs = deps.pollTimeoutMs ?? POLL_TIMEOUT_MS;
+
+    this._stopped = false;
+    this._last_poll_error = null;
+    this._session_dead = false;
+    this._warned = { send: false, poll: false, route: false };
+    this._batches = [];
+    this._waiting = null; // recv() 的等待者
+    this._sendQueue = [];
+    this._sendWaiting = null;
+  }
+
+ // ---- 生命周期 ----
+
+ #start() {
+    const startCursor = state.get_str(this.loadState(), "buf") ?? null;
+    this.#pollLoop(startCursor); // 不 await：双异步任务（ZCode 同款）
+    this.#sendLoop();
+  }
+
+  /** 幂等收（session_shutdown 语义）：置标志、唤醒等待者、释放锁。
+   * **不等待在途 90s**——旧轮询到点后见 stopped 自行退出。 */
+  stop() {
+    if (this._stopped) return;
+    this._stopped = true;
+    this.#wakeRecv();
+    this.#wakeSend();
+    this._lock.release();
+  }
+
+ // ---- 入站面（泵侧） ----
+
+  /** 非阻塞取一批；空则 null。 */
+  try_recv() {
+    return this._batches.shift() ?? null;
+  }
+
+  /** 阻塞取一批；stop 后返回 null（泵自然收尾）。 */
+  recv() {
+    const b = this.try_recv();
+    if (b) return Promise.resolve(b);
+    if (this._stopped) return Promise.resolve(null);
+    return new Promise((resolve) => {
+      this._waiting = resolve;
+    });
+  }
+
+  /** 批次处理完后落盘游标（§6 坑 2：**处理完才写**）。 */
+  ack_cursor(batch) {
+    if (batch.next_buf === null || batch.next_buf === undefined) return;
+    const st = this.loadState();
+    state.set(st, "buf", batch.next_buf);
+    this.saveState(st);
+  }
+
+  /** **处理动作之前**先落路由字段（真机 2026-10-24：首条回执找不到对端
+   * 即此——route 时回执已进出站队列，send 线程随即重读状态）。 */
+  ack_routing(batch) {
+    const m = batch.messages[0];
+    if (!m) return;
+    const st = this.loadState();
+    let dirty = false;
+    if (m.chat_id) { state.set(st, "chat_id", m.chat_id); dirty = true; }
+    if (m.user_id !== "") { state.set(st, "user_id", m.user_id); dirty = true; }
+    if (m.bot_user_id) { state.set(st, "bot_user_id", m.bot_user_id); dirty = true; }
+    if (m.context_token) { state.set(st, "context_token", m.context_token); dirty = true; }
+    if (dirty) this.saveState(st);
+  }
+
+  /** 兼容入口：路由 + 游标一次完成。 */
+  ack(batch) {
+    this.ack_routing(batch);
+    this.ack_cursor(batch);
+  }
+
+ // ---- 出站面 ----
+
+  /** 发一条文本到微信 —— 只入队，实际 HTTP 在 sendLoop 里跑，**绝不阻塞调用方**。 */
+  send(text) {
+    if (this._stopped) throw new Error("send 线程已退出");
+    this._sendQueue.push(text);
+    this.#wakeSend();
+  }
+
+ // ---- 观测面 ----
+
+  is_closed() { return this._stopped; }
+  poll_error() { return this._last_poll_error; }
+  session_dead() { return this._session_dead; }
+
+ // ---- 内部：双异步任务 ----
+
+  async #pollLoop(cursor) {
+    let failures = 0;
+    while (!this._stopped) {
+      let up;
+      try {
+        up = await this.getUpdates(this.cfg.token, cursor);
+      } catch (e) {
+        const msg = String(e?.message ?? e);
+ // -14 分两档（002「服务侧会话过期」）
+        if (is_session_timeout(msg) && cursor !== null) {
+          cursor = null;
+          const st = this.loadState();
+          state.set(st, "buf", null);
+          this.saveState(st);
+          failures = 0;
+ // 停 1 秒再试：服务端持续拒绝时别打成热循环（可被 stop 打断）
+          await this.#interruptibleSleep(1000);
+          continue;
+        }
+        if (is_session_timeout(msg)) this._session_dead = true;
+        failures += 1;
+        this._last_poll_error = msg;
+        this.#warnOnce("poll", `getupdates 失败：${msg}`);
+ // 指数退避，封顶 30s；分小段睡以便及时响应 stop
+        await this.#interruptibleSleep(next_wait_ms(failures));
+        continue;
+      }
+      failures = 0;
+      this._last_poll_error = null;
+ // 游标只在内存推进；落盘交给泵的 ack_cursor()
+      cursor = up.next_buf ?? null;
+      if (up.messages.length > 0) {
+        this.#deliver(new Batch(up.messages, up.next_buf));
+      }
+    }
+  }
+
+  async #sendLoop() {
+    while (!this._stopped) {
+      let text;
+      try {
+        text = await this.#nextSend();
+      } catch {
+        break; // stop 唤醒
+      }
+ // 每次发送前重读状态：chat_id / bot_user_id 可能在首条入站后才被发现
+      const st = this.loadState();
+ // 对端解析：群聊 = chat_id（room id）；**私聊 = user_id**（入站
+ // from_user_id 随 ack_routing 回写）。曾只认 chat_id —— 而私聊（决策 5：
+ // 唯一支持形态）chat_id 恒为 None，所有回执被静默丢弃（真机
+ // 「发了没反应」，2026-10-23 修复）。
+      const to_user = state.get_str(st, "chat_id") ?? state.get_str(st, "user_id");
+      const from_user = state.get_str(st, "bot_user_id");
+      if (!to_user || !from_user) {
+ // **必须出声**：静默丢弃正是「微信收不到回执」迟迟查不出的原因
+        this.#warnOnce(
+          "route",
+          "出站消息被丢弃：状态盘缺 chat_id/user_id / bot_user_id（首条入站后随 ack_routing 回写）",
+        );
+        continue;
+      }
+      const client_id = state.ensure_client_id(st);
+      const token = state.get_str(st, "bot_token");
+      if (!token) break; // 状态被清（换绑中）：sendLoop 退出，重绑后 transport 重建
+      try {
+        await this.sendText(token, from_user, to_user, text, state.get_str(st, "context_token"), client_id);
+      } catch (e) {
+ // 发送失败同样不能吞：对用户来说就是「发了没反应」
+        this.#warnOnce("send", `sendmessage 失败：${String(e?.message ?? e)}`);
+      }
+    }
+  }
+
+ // ---- 队列与可中断睡眠 ----
+
+ #deliver(batch) {
+    if (this._waiting) {
+      const resolve = this._waiting;
+      this._waiting = null;
+      resolve(batch);
+    } else {
+      this._batches.push(batch);
+    }
+  }
+
+ #wakeRecv() {
+    if (this._waiting) {
+      const resolve = this._waiting;
+      this._waiting = null;
+      resolve(null);
+    }
+  }
+
+ #nextSend() {
+    const text = this._sendQueue.shift();
+    if (text !== undefined) return Promise.resolve(text);
+    if (this._stopped) return Promise.reject(new Error("stopped"));
+    return new Promise((resolve, reject) => {
+      this._sendWaiting = { resolve, reject };
+    });
+  }
+
+ #wakeSend() {
+    if (this._sendWaiting && this._sendQueue.length > 0) {
+      const { resolve } = this._sendWaiting;
+      this._sendWaiting = null;
+      resolve(this._sendQueue.shift());
+    } else if (this._sendWaiting && this._stopped) {
+      const { reject } = this._sendWaiting;
+      this._sendWaiting = null;
+      reject(new Error("stopped"));
+    }
+  }
+
+  /** 分 100ms 小段睡，stop 立即返回（Rust poll_loop 同款）。 */
+  async #interruptibleSleep(totalMs) {
+    let left = totalMs;
+    while (left > 0 && !this._stopped) {
+      const step = Math.min(100, left);
+      await this.sleep(step);
+      left -= step;
+    }
+  }
+
+ #warnOnce(channel, msg) {
+    if (this._warned[channel]) return;
+    this._warned[channel] = true;
+    console.error(`[wxbridge] ${msg}（此提示只出现一次）`);
+  }
+}
+
+// parse_updates 再导出：泵侧拿到裸 payload 时复用同一解析（transport 单测用）
+export { parse_updates };
+
+/** 起渠道（Transport.spawn 的模块级别名，Rust transport::spawn 对位）。 */
+export const spawn = Transport.spawn.bind(Transport);

package/pi/transport.test.mjs

@@ -0,0 +1,327 @@
+// transport 单测 —— 与 wxprobe src/transport.rs 语义逐条对齐（JS 版）。
+// 跑法：node --test packages/wechat-bridge/pi/
+// 全部用注入 deps（fake getUpdates/sendText/state），零真网络。
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+
+import {
+  spawn, Transport, Batch,
+  is_session_timeout, next_wait_ms, classify_poll_error,
+} from "./transport.mjs";
+import { require_token } from "./config.mjs";
+import { parse_updates } from "./poller.mjs";
+import { Wire } from "./wire.mjs";
+import { parse } from "./jsonx.mjs";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const fixtureText = readFileSync(join(here, "fixtures", "getupdates-real.json"), "utf8");
+
+// ---------------------------------------------------------------- 测试基建
+
+/** 独立临时状态盘（不碰包内 data/）。 */
+function fakeState(initial = {}) {
+  let st = { ...initial };
+  return {
+    load: () => ({ ...st }),
+    save: (next) => { st = { ...next }; },
+    get current() { return { ...st }; },
+  };
+}
+
+/** 脚本化 poll 序列：逐拍消费 {payload}（成功）或 {error}（失败）或 {hang}（挂起）。
+ * payload 走 parse_updates —— 与真 getUpdates（wire.post_poll + parse_updates）同构。 */
+function scriptedGetUpdates(entries, { seen = [] } = {}) {
+  let i = 0;
+  return async (token, buf) => {
+    seen.push(buf ?? null);
+    if (i >= entries.length) {
+ // 剧本演完：永久挂起（保持循环活着的自然态）
+      return new Promise(() => {});
+    }
+    const step = entries[i++];
+    if (step.hang) return new Promise(() => {});
+    if (step.error) throw step.error;
+    return parse_updates(parse(JSON.stringify(step.payload)), buf ?? null);
+  };
+}
+
+const fakeLock = { release() {} };
+const tick = (n = 1) => new Promise((r) => setTimeout(r, n));
+const noSleep = () => Promise.resolve(); // 退避/1s 罚时不真等
+
+async function makeTransport({ stateInit = {}, pollScript, sendText = async () => ({}), seen = [] } = {}) {
+  const fake = fakeState(stateInit);
+  const t = await spawn(
+    { token: "tk", bot_id: "bot", client_id: "c" },
+    {
+      lock: fakeLock,
+      wire: new Wire(null), // 不落 dump（避免测试在包内建 data/）
+      loadState: fake.load,
+      saveState: fake.save,
+      getUpdates: scriptedGetUpdates(pollScript ?? [{ hang: true }], { seen }),
+      sendText,
+      sleep: noSleep,
+    },
+  );
+  return { t, fake };
+}
+
+// ---------------------------------------------------------------- 配置面（Rust require_token 单测同款）
+
+test("token_must_be_non_empty", () => {
+  assert.throws(() => require_token({ bot_token: "" }), /未扫码/);
+  assert.throws(() => require_token({ bot_token: "   " }), /未扫码/);
+  assert.throws(() => require_token({}), /未扫码/);
+  assert.equal(require_token({ bot_token: "tk" }), "tk");
+});
+
+test("config_from_state_carries_all_fields", async () => {
+  const { config_from_state } = await import("./config.mjs");
+  const cfg = config_from_state({
+    bot_token: "tk", bot_id: "b1", bot_user_id: "bot@im.bot",
+    chat_id: "u@im.wechat", context_token: "ctx", client_id: "c0",
+  });
+  assert.deepEqual(cfg, {
+    token: "tk", bot_id: "b1", bot_user: "bot@im.bot",
+    chat_user: "u@im.wechat", context_token: "ctx", client_id: "c0",
+  });
+  const minimal = config_from_state({ bot_token: "tk" });
+  assert.equal(minimal.bot_id, "");
+  assert.equal(minimal.chat_user, null);
+  assert.ok(minimal.client_id.startsWith("wxbridge-"), "client_id 兜底生成");
+});
+
+// ---------------------------------------------------------------- 错误分类（-14 两档）
+
+test("is_session_timeout_matches_both_error_shapes", () => {
+  assert.ok(is_session_timeout("getupdates: iLink 业务错误 ret=None errcode=-14 session timeout"));
+  assert.ok(is_session_timeout("…errcode=Some(-14) session timeout…"), "Rust 错误串形态");
+  assert.ok(is_session_timeout("server said: session timeout"));
+  assert.ok(!is_session_timeout("POST /getupdates: network timeout"), "网络超时不是会话过期");
+  assert.ok(!is_session_timeout("HTTP 500"));
+});
+
+test("classify_poll_error_two_tiers", () => {
+  assert.equal(classify_poll_error(true), "cursor_flush", "有游标被拒 = 洗游标自愈");
+  assert.equal(classify_poll_error(false), "session_dead", "空游标仍拒 = 服务侧作废");
+});
+
+test("next_wait_ms_exponential_capped_30s", () => {
+  assert.equal(next_wait_ms(0), 500);
+  assert.equal(next_wait_ms(1), 1000);
+  assert.equal(next_wait_ms(6), 30_000, "500<<6=32000 → 封顶 30s");
+  assert.equal(next_wait_ms(50), 30_000);
+});
+
+// ---------------------------------------------------------------- 游标 at-least-once（端到端）
+
+test("cursor_written_only_after_ack", async () => {
+  const payload = parse(fixtureText);
+  const { t, fake } = await makeTransport({
+    stateInit: { bot_token: "tk", buf: null },
+    pollScript: [{ payload }],
+  });
+  const batch = await t.recv();
+  assert.equal(batch.messages.length, 1);
+  assert.equal(batch.next_buf, payload.get_updates_buf);
+ // 收到批但**尚未 ack**：盘上必须还没有新游标（崩溃窗口 = 重复而非丢失）
+  assert.notEqual(fake.current.buf, payload.get_updates_buf, "处理完才落盘（§6 坑 2）");
+  t.ack(batch);
+  assert.equal(fake.current.buf, payload.get_updates_buf, "ack 后落盘");
+  t.stop();
+});
+
+test("crash_without_ack_repulls_same_batch_at_least_once", async () => {
+  const payload = parse(fixtureText);
+ // 第一条命：收到批、模拟崩溃（不 ack 即 stop）
+  const seen1 = [];
+  const { t: t1 } = await makeTransport({
+    stateInit: { bot_token: "tk", buf: "OLD_CURSOR" },
+    pollScript: [{ payload }],
+    seen: seen1,
+  });
+  await t1.recv();
+  t1.stop(); // 崩溃：游标未 ack
+
+ // 第二条命：从盘上旧游标重拉 —— 同一批必须再来（可能重复、绝不丢失）
+  const seen2 = [];
+  const { t: t2 } = await makeTransport({
+    stateInit: { bot_token: "tk", buf: "OLD_CURSOR" },
+    pollScript: [{ payload }],
+    seen: seen2,
+  });
+  const batch2 = await t2.recv();
+  assert.equal(batch2.messages.length, 1, "未 ack 的批重启后重收（at-least-once）");
+  assert.equal(seen2[0], "OLD_CURSOR", "从上次 ack 的游标重拉");
+  t2.ack(batch2);
+  t2.stop();
+});
+
+test("twenty_start_stop_cycles_cursor_stable", async () => {
+ // 与 poller 纯函数版同语义的 transport 端到端版：ack 驱动落盘
+  const payload = parse(fixtureText);
+  const fake = fakeState({ bot_token: "tk" });
+  const seen = [];
+  const script = [{ payload }, ...Array.from({ length: 19 }, () => ({ payload: { msgs: [] } }))];
+  const t = await spawn(
+    { token: "tk", bot_id: "bot" },
+    {
+      lock: fakeLock, wire: new Wire(null), loadState: fake.load, saveState: fake.save,
+      getUpdates: scriptedGetUpdates(script, { seen }),
+      sendText: async () => ({}), sleep: noSleep,
+    },
+  );
+  const first = await t.recv();
+  t.ack(first);
+ // 之后 19 拍空闲：不产生批，游标保持
+  await tick(5);
+  assert.equal(fake.current.buf, payload.get_updates_buf, "空闲拍不改写游标");
+  t.stop();
+});
+
+// ---------------------------------------------------------------- 双异步（send 不等 poll）
+
+test("send_flows_while_long_poll_hangs", async () => {
+ // 状态盘已带路由字段（首条入站 ack_routing 之后的常态）
+  const sent = [];
+  const { t } = await makeTransport({
+    stateInit: {
+      bot_token: "tk", bot_user_id: "bot@im.bot", user_id: "u@im.wechat",
+      chat_id: null, context_token: "ctx", client_id: "c0",
+    },    pollScript: [{ hang: true }], // 长轮询永远挂着
+    sendText: async (token, from, to, text, ctx, cid) => {
+      sent.push({ token, from, to, text, ctx, cid });
+    },
+  });
+  await tick();
+  t.send("你好");
+  await tick();
+  assert.equal(sent.length, 1, "长轮询挂起期间 sendMessage 照发（双异步核心语义）");
+  assert.equal(sent[0].to, "u@im.wechat", "私聊对端 = user_id（chat_id 缺省回退）");
+  assert.equal(sent[0].from, "bot@im.bot");
+  assert.equal(sent[0].ctx, "ctx");
+  assert.equal(sent[0].cid, "c0", "transport 只传稳定实例 id；每条唯一拼装在 poller.send_text 内（Rust 同款分层）");
+  t.stop();
+});
+
+test("send_text_builds_unique_client_id_and_crlf_payload", async () => {
+ // 真 send_text：每条唯一 client_id（实例id-毫秒-序号）+ strip_ansi + CRLF
+  const sent = [];
+  let seq = 0;
+  const fakeWire = { post: async (tag, path, token, body) => { sent.push({ tag, path, token, body }); return {}; } };
+  const { send_text } = await import("./poller.mjs");
+  await send_text(fakeWire, "tk", "bot@im.bot", "u@im.wechat", "第一行\n\x1b[38;5;5m带色码", "ctx", "c0");
+  await send_text(fakeWire, "tk", "bot@im.bot", "u@im.wechat", "第二条", null, "c0");
+  assert.equal(sent.length, 2);
+  const { body: b1 } = sent[0];
+  assert.equal(sent[0].tag, "sendmessage");
+  assert.equal(sent[0].path, "/sendmessage");
+  assert.equal(sent[0].token, "tk");
+  assert.equal(b1.msg.from_user_id, "bot@im.bot");
+  assert.equal(b1.msg.to_user_id, "u@im.wechat");
+  assert.equal(b1.msg.message_type, 2);
+  assert.equal(b1.msg.item_list[0].text_item.text, "第一行\r\n带色码", "LF→CRLF + ANSI 色码剥除");
+  assert.equal(b1.msg.context_token, "ctx");
+  assert.match(b1.msg.client_id, /^c0-\d+-\d+$/, "实例id-毫秒-序号，每条唯一");
+  const { body: b2 } = sent[1];
+  assert.ok(!("context_token" in b2.msg), "空 context_token 不进参（Rust if let Some(filter) 同款）");
+  assert.notEqual(b1.msg.client_id, b2.msg.client_id, "两条消息 client_id 必不相同");
+});
+
+test("send_dropped_with_loud_warning_when_no_peer", async () => {
+  const sent = [];
+  const errors = [];
+  const origErr = console.error;
+  console.error = (...a) => errors.push(a.join(" "));
+  try {
+    const { t } = await makeTransport({
+      stateInit: { bot_token: "tk" }, // 无路由字段
+      sendText: async (...a) => sent.push(a),
+    });
+    await tick();
+    t.send("没人收");
+    await tick();
+    assert.equal(sent.length, 0, "缺对端必须丢弃");
+    assert.ok(errors.some((s) => s.includes("出站消息被丢弃")), "静默丢弃 = 真机事故根源，必须出声");
+    t.stop();
+  } finally {
+    console.error = origErr;
+  }
+});
+
+test("ack_routing_writes_route_fields_before_processing", async () => {
+  const payload = parse(fixtureText);
+  const { t, fake } = await makeTransport({ pollScript: [{ payload }] });
+  const batch = await t.recv();
+  t.ack_routing(batch);
+  const st = fake.current;
+  assert.equal(st.chat_id, undefined, "私聊无 chat_id 不写");
+  assert.equal(st.user_id, "user_sandbox@im.wechat");
+  assert.equal(st.bot_user_id, "bot_sandbox@im.bot");
+  assert.equal(st.context_token, "SANITIZED_CONTEXT_TOKEN");
+  assert.equal(st.buf, undefined, "ack_routing 不碰游标（§6 坑 2 分工）");
+  t.stop();
+});
+
+// ---------------------------------------------------------------- -14 两档（端到端）
+
+test("session_timeout_with_cursor_flushes_cursor_and_self_heals", async () => {
+  const seen = [];
+  const { t, fake } = await makeTransport({
+    stateInit: { bot_token: "tk", buf: "STALE_BOT_CURSOR" },
+    pollScript: [
+      { error: new Error("iLink 业务错误 ret=None errcode=-14 session timeout") },
+      { payload: { msgs: [] } }, // 洗完游标后同 token 重新接洽成功
+    ],
+    seen,
+  });
+  await tick(5);
+  assert.equal(fake.current.buf, null || undefined, "旧游标被洗掉");
+  assert.equal(seen[0], "STALE_BOT_CURSOR", "第一拍带着旧游标被拒");
+  assert.equal(seen[1], null, "第二拍空游标重新接洽（自愈）");
+  assert.equal(t.poll_error(), null, "自愈成功即清错");
+  assert.equal(t.session_dead(), false, "一档不是会话作废");
+  t.stop();
+});
+
+test("session_timeout_without_cursor_marks_session_dead", async () => {
+  let polls = 0;
+  const { t } = await makeTransport({
+    stateInit: { bot_token: "tk", buf: null },
+    pollScript: Array.from({ length: 30 }, () => ({
+      error: new Error("errcode=-14 session timeout"),
+      count: ++polls,
+    })),
+  });
+  await tick(10);
+  assert.equal(t.session_dead(), true, "空游标仍被拒 = 服务侧会话作废（002：回绑定页）");
+  assert.ok(polls > 2, "轮询保持低频重试，不退出（§6 坑 4）");
+  assert.ok(t.poll_error()?.includes("session timeout"));
+  t.stop();
+});
+
+// ---------------------------------------------------------------- 生命周期（幂等收）
+
+test("stop_is_idempotent_and_wakes_recv", async () => {
+  const { t } = await makeTransport({});
+  const p = t.recv(); // 挂起等待
+  t.stop();
+  assert.equal(await p, null, "stop 唤醒 recv 返回 null（泵自然收尾）");
+  t.stop(); // 二次调用 no-op
+  assert.equal(t.is_closed(), true);
+  assert.throws(() => t.send("x"), /send 线程已退出/);
+});
+
+test("recv_returns_batch_before_stop_null_after", async () => {
+  const payload = parse(fixtureText);
+  const { t } = await makeTransport({ pollScript: [{ payload }] });
+  const b = await t.recv();
+  assert.ok(b instanceof Batch);
+  t.stop();
+  assert.equal(await t.recv(), null);
+});