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

package/pi/index.test.mjs

@@ -0,0 +1,696 @@
+// index 入口串接单测 —— v4 全局装载 + 泵内门控（004 §5.2）的行为面。
+// 全部依赖注入（假 pi / 假 ctx / 假 Transport / 内存状态盘），不碰真实盘。
+// 跑法：node --test packages/pf-wxbot/pi/index.test.mjs
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import { create_entry, resolve_session_file, session_file_from_argv } from "./index.mjs";
+import { WX_LINK_ON, WX_LINK_OFF } from "./hook.mjs";
+
+// ---------------------------------------------------------------- 假件
+
+/** 内存状态盘（state.mjs 同面：load/save/get_str/set/base_dir/dump_dir）。 */
+function mem_state(initial = {}) {
+  let store = { ...initial };
+  return {
+    store: () => store,
+    load: () => ({ ...store }),
+    save(next) {
+      store = { ...next };
+    },
+    get_str: (st, k) => {
+      const v = st?.[k];
+      if (typeof v !== "string") return undefined;
+      const s = v.trim();
+      return s === "" ? undefined : s;
+    },
+    set: (st, k, v) => {
+      if (v === null || v === undefined) delete st[k];
+      else st[k] = v;
+    },
+    base_dir: () => "<mem>/data",
+    dump_dir: () => "<mem>/dump",
+  };
+}
+
+/** 假渠道：spawn 即成，try_recv 由测试喂数。 */
+function fake_transport_class() {
+  const spawned = [];
+  class FakeTransport {
+    static spawn(cfg) {
+      const t = new FakeTransport(cfg);
+      spawned.push(t);
+      return Promise.resolve(t);
+    }
+    constructor(cfg) {
+      this.cfg = cfg;
+      this.stopped = false;
+      this.queue = []; // 待收批
+      this.sends = [];
+      this.dead = false;
+    }
+    try_recv() {
+      return this.queue.shift() ?? null;
+    }
+    stop() {
+      this.stopped = true;
+    }
+    is_closed() {
+      return this.stopped;
+    }
+    session_dead() {
+      return this.dead;
+    }
+    send(text) {
+      this.sends.push(text);
+    }
+    ack_routing() {}
+    ack_cursor() {}
+  }
+  return { cls: FakeTransport, spawned };
+}
+
+/** 假 pi：只记录 on 注册与 sendUserMessage 调用。 */
+function fake_pi(ctxObj) {
+  const handlers = {};
+  const calls = { prompt: [] };
+  return {
+    pi: {
+      on(event, handler) {
+        (handlers[event] ??= []).push(handler);
+      },
+      sendUserMessage(text, opts) {
+        calls.prompt.push({ text, opts });
+      },
+    },
+    handlers,
+    calls,
+    async fire(event, arg) {
+      for (const h of handlers[event] ?? []) await h(arg, ctxObj ?? ctx_stub());
+    },
+  };
+}
+
+/** 假 session 域上下文：带 sessionManager（自身身份，004 §7-1）。 */
+function ctx_stub(over = {}) {
+  return {
+    isIdle: over.isIdle ?? (() => true),
+    abort: over.abort ?? (() => {}),
+    cwd: "D:/proj/pi-flash",
+    model: over.model ?? undefined,
+    scopedModels: over.scopedModels ?? [],
+    sessionManager: {
+      getSessionId: () => over.ownKey ?? "sA",
+      getSessionName: () => over.ownName ?? "wx session",
+    },
+    ...over,
+  };
+}
+
+const TICK = 15;
+const settle = (ms = 80) => new Promise((r) => setTimeout(r, ms));
+/** 条件等待（并发跑测试时定时器会被拖慢，用轮询代替固定 sleep）。 */
+async function wait_for(pred, ms = 800) {
+  const t0 = Date.now();
+  while (Date.now() - t0 < ms) {
+    if (pred()) return true;
+    await settle(10);
+  }
+  return pred();
+}
+
+/** 假 Wire：get_qr 出固定码，get_qrcode_status 按脚本走（不碰网络）。 */
+function fake_wire_class(script = () => ({ status: "pending" })) {
+  return class FakeWire {
+    constructor() {}
+    async get_qr(_tag, path) {
+      if (path.includes("get_bot_qrcode")) {
+        return { qrcode: "ENC-1", qrcode_url: "https://qr/ENC-1", expires_in: 120 };
+      }
+      return script();
+    }
+  };
+}
+
+/** 标准装配：ownKey = 本进程会话身份；镜像 initial 由用例给。 */
+function mk_entry({ ownKey = "sA", state: st = {}, ctx, wire, sessionExists, deps: extra = {} } = {}) {
+  const S = mem_state({ bot_token: "T1", bot_id: "bot@im", bot_user_id: "bot@im", ...st });
+  const { cls, spawned } = fake_transport_class();
+  const f = fake_pi(ctx ? ctx_stub({ ownKey, ...ctx }) : ctx_stub({ ownKey }));
+  const directs = []; // 降沿直发记录器（生产 = hook.mjs 真直发；测试绝不碰真盘/真网）
+  const factory = create_entry({
+    state: S,
+    Transport: cls,
+    Wire: wire ?? fake_wire_class(),
+    sessionExists,
+    sessionCheckTicks: 2, // 测试用快周期
+    sleep: () => new Promise(() => {}), // QR 轮询挂起（不堆计时器）
+    tickMs: TICK,
+    stat: () => null, // Snapshot 每拍重读（内存盘无 mtime）
+    directSend: async (t) => {
+      directs.push(t);
+    },
+    ...extra,
+  });
+  factory(f.pi);
+  return { S, spawned, directs, ...f, factory };
+}
+
+// ---------------------------------------------------------------- 工厂（禁起资源）
+
+test("factory_registers_handlers_and_starts_nothing", () => {
+  const { handlers, spawned } = mk_entry();
+  assert.ok(handlers.session_start?.length === 1);
+  assert.ok(handlers.message_end?.length === 1);
+  assert.ok(handlers.agent_settled?.length === 1, "异常停止回执的接线注册");
+  assert.ok(handlers.session_shutdown?.length === 1);
+  assert.equal(spawned.length, 0, "工厂只注册，不起资源（生命周期铁律）");
+});
+
+// ---------------------------------------------------------------- 门控（004 §5.2）
+
+/** 小工具：起一个 entry 并 fire session_start，返回句柄。 */
+async function start({ ownKey, state: st, ctx, wire, sessionExists, deps } = {}) {
+  const h = mk_entry({ ownKey, state: st, ctx, wire, sessionExists, deps });
+  await h.fire("session_start", {}, ctx ? ctx_stub({ ownKey, ...ctx }) : ctx_stub({ ownKey }));
+  return h;
+}
+test("unbound_session_never_spawns_transport", async () => {
+  const h = await start({ ownKey: "sA", state: {} }); // 镜像无 session_id
+  await settle();
+  assert.equal(h.spawned.length, 0, "门控不过 → 永不起渠道");
+  h.fire("session_shutdown");
+});
+
+test("bound_session_spawns_and_pumps", async () => {
+  const h = await start({ ownKey: "sA", state: { session_id: "sA" } });
+  await settle();
+  assert.equal(h.spawned.length, 1, "被绑定会话 → 起渠道");
+  assert.equal(h.spawned[0].cfg.token, "T1");
+  h.fire("session_shutdown");
+});
+
+test("foreign_bound_session_stays_idle", async () => {
+ // 本进程 sA，镜像绑定的是 sB（另一会话抢走指针）
+  const h = await start({ ownKey: "sA", state: { session_id: "sB" } });
+  await settle();
+  assert.equal(h.spawned.length, 0, "指针属于别的会话 → 空转");
+  h.fire("session_shutdown");
+});
+
+test("gate_release_binds_late_pointer", async () => {
+ // 先空转，壳写指针后泵下一拍拾起（004 §5.2：壳写完 session_id 下一拍即被拾起）
+  const h = await start({ ownKey: "sA", state: {} });
+  await settle();
+  assert.equal(h.spawned.length, 0);
+  h.S.save({ ...h.S.store(), session_id: "sA" });
+  await settle();
+  assert.equal(h.spawned.length, 1, "指针落到本会话 → 起渠道");
+  h.fire("session_shutdown");
+});
+
+test("gate_loss_stops_transport_silently", async () => {
+  const h = await start({ ownKey: "sA", state: { session_id: "sA" } });
+  await settle();
+  assert.equal(h.spawned.length, 1);
+  h.S.save({ ...h.S.store(), session_id: "sB" }); // 指针换人
+  await settle();
+  assert.equal(h.spawned[0].stopped, true, "失配 → 渠道停（静默，非用户关停）");
+  assert.deepEqual(h.directs, [], "失门停机不宣告失联（stop_notice：非用户关停）");
+  h.fire("session_shutdown");
+});
+
+// ---------------------------------------------------------------- off 态（002 主动断开）
+
+test("enabled_off_never_starts_and_stops_running", async () => {
+  const h = await start({ ownKey: "sA", state: { session_id: "sA", enabled: "0" } });
+  await settle();
+  assert.equal(h.spawned.length, 0, "off：不起渠道");
+ // 运行中被关：停
+  h.S.save({ ...h.S.store(), enabled: undefined, session_id: "sA" });
+  await settle();
+  assert.equal(h.spawned.length, 1);
+  h.S.save({ ...h.S.store(), enabled: "0" });
+  await settle();
+  assert.equal(h.spawned[0].stopped, true, "运行中 switch off → 停服");
+  h.fire("session_shutdown");
+});
+
+// ---------------------------------------------------------------- 会话删除校验（off 态 case-1）
+
+test("session_deleted_check_clears_binding", async () => {
+ // 快周期（deps.sessionCheckTicks=2，mk_entry 已注）：门控通过 → 校验被周期调用；
+ // PF 说会话已删 → 自动关服务 + 删除持有的 sessionId（002 主动断开 case-1）
+  let calls = 0;
+  let exists = true;
+  const h = mk_entry({
+    ownKey: "sA",
+    state: { session_id: "sA" },
+    sessionExists: async () => {
+      calls += 1;
+      return exists;
+    },
+  });
+  await h.fire("session_start", {}, ctx_stub({ ownKey: "sA" }));
+  await settle();
+  assert.equal(h.spawned.length, 1);
+  assert.ok(calls >= 1, "校验通道被周期调用");
+  exists = false;
+  await settle();
+  assert.equal(h.spawned[0].stopped, true, "会话不存在 → 自动关服务");
+  assert.equal(h.S.store().session_id, undefined, "删除持有的 sessionId");
+  h.fire("session_shutdown");
+});
+
+// ---------------------------------------------------------------- 入站路由（inject 最小面）
+
+test("inbound_text_passes_through_to_pi", async () => {
+  const h = await start({ ownKey: "sA", state: { session_id: "sA" } });
+  await settle();
+  h.spawned[0].queue.push({ messages: [{ text: "帮我跑下测试" }] });
+  await settle();
+  assert.deepEqual(
+    h.calls.prompt.map((p) => p.text),
+    ["帮我跑下测试"],
+    "纯文本透传 sendUserMessage",
+  );
+  h.fire("session_shutdown");
+});
+
+test("stop_command_aborts_current_run", async () => {
+  let aborted = 0;
+  const h = await start({
+    ownKey: "sA",
+    state: { session_id: "sA" },
+    ctx: { abort: () => (aborted += 1) },
+  });
+  await settle();
+  h.spawned[0].queue.push({ messages: [{ text: "/stop" }] });
+  await settle();
+  assert.equal(aborted, 1, "/stop → abort");
+  h.fire("session_shutdown");
+});
+
+test("status_command_replies_via_transport", async () => {
+  const h = await start({
+    ownKey: "sA",
+    state: { session_id: "sA" },
+    ctx: { model: { provider: "zhipu", id: "glm-5" } },
+  });
+  await settle();
+  h.spawned[0].queue.push({ messages: [{ text: "/status" }] });
+  await settle();
+  assert.equal(h.spawned[0].sends.length, 1, "/status → 渠道回执一条");
+  assert.ok(h.spawned[0].sends[0].includes("glm-5"), "回执含模型信息");
+  h.fire("session_shutdown");
+});
+
+test("unknown_slash_command_passes_through", async () => {
+  const h = await start({ ownKey: "sA", state: { session_id: "sA" } });
+  await settle();
+  h.spawned[0].queue.push({ messages: [{ text: "/model glm-5" }] });
+  await settle();
+  assert.deepEqual(h.calls.prompt.map((p) => p.text), ["/model glm-5"], "未知 /命令不吞，原文透传");
+  h.fire("session_shutdown");
+});
+
+// ---------------------------------------------------------------- 异常停止回执（2026-11-01 buglist#2）
+
+/** 出错助手消息（pi agent-loop error 分支同形）。 */
+const error_msg = (errorMessage) => ({
+  role: "assistant",
+  content: [],
+  stopReason: "error",
+  errorMessage,
+  usage: {},
+});
+
+test("agent_error_settled_sends_notice_to_wechat", async () => {
+  const h = await start({ ownKey: "sA", state: { session_id: "sA" } });
+  await settle();
+  assert.equal(h.spawned.length, 1);
+ // 运行中出错：message_end 只记账，微信不响
+  await h.fire("message_end", { message: error_msg("provider 5xx: upstream overloaded") });
+  assert.deepEqual(h.spawned[0].sends, [], "错误不即发");
+ // 运行彻底落定（重试链全停）：错误补发微信
+  await h.fire("agent_settled", { aborted: false });
+  assert.deepEqual(
+    h.spawned[0].sends,
+    ["⚠️任务异常停止：provider 5xx: upstream overloaded"],
+    "settle 后错误必须送达微信",
+  );
+  h.fire("session_shutdown");
+});
+
+test("agent_error_recovered_then_settled_sends_nothing", async () => {
+  const h = await start({ ownKey: "sA", state: { session_id: "sA" } });
+  await settle();
+  await h.fire("message_end", { message: error_msg("transient") });
+ // 重试成功：正常发言照常出站，旧账勾销
+  await h.fire("message_end", {
+    message: { role: "assistant", content: [{ type: "text", text: "好了" }], stopReason: "stop", usage: {} },
+  });
+  await h.fire("agent_settled", { aborted: false });
+  assert.deepEqual(h.spawned[0].sends, ["好了"], "只发恢复后的发言，不报已恢复的错");
+  h.fire("session_shutdown");
+});
+
+test("agent_settled_aborted_no_error_notice", async () => {
+  const h = await start({ ownKey: "sA", state: { session_id: "sA" } });
+  await settle();
+  await h.fire("message_end", { message: error_msg("boom") });
+  await h.fire("agent_settled", { aborted: true });
+  assert.deepEqual(h.spawned[0].sends, [], "/停止 = 用户主动，不报异常");
+  h.fire("session_shutdown");
+});
+
+// ---------------------------------------------------------------- 运行中心跳（2026-11-01 buglist#1 定案）
+
+test("heartbeat_cadence_gated_by_interval_while_running", async () => {
+  let clock = 10_000;
+  const h = await start({
+    ownKey: "sA",
+    state: { session_id: "sA" },
+    ctx: { isIdle: () => false }, // agent 运行中
+    deps: { now: () => clock, heartbeatMs: 60_000 },
+  });
+  await settle();
+  assert.deepEqual(h.spawned[0].sends, [], "运行未满节拍：无心跳");
+  clock += 60_001;
+  await wait_for(() => (h.spawned[0]?.sends.length ?? 0) >= 1);
+  assert.equal(h.spawned[0].sends.length, 1, "一拍只发一张");
+  assert.ok(h.spawned[0].sends[0].includes("运行中"), "内容是运行中状态卡");
+  clock += 10_000; // 距上张卡 10s，不足节拍
+  await settle();
+  assert.equal(h.spawned[0].sends.length, 1, "节拍未到不重发");
+  clock += 60_000;
+  await wait_for(() => (h.spawned[0]?.sends.length ?? 0) >= 2, 1500);
+  h.fire("session_shutdown");
+});
+
+test("agent_start_resets_heartbeat_clock", async () => {
+  let clock = 10_000;
+  const h = await start({
+    ownKey: "sA",
+    state: { session_id: "sA" },
+    ctx: { isIdle: () => false },
+    deps: { now: () => clock, heartbeatMs: 60_000 },
+  });
+  clock += 60_001;
+  await wait_for(() => (h.spawned[0]?.sends.length ?? 0) >= 1);
+  await h.fire("agent_start", {}); // 新一轮运行：节拍从本轮起算
+  clock += 59_000;
+  await settle();
+  assert.equal(h.spawned[0].sends.length, 1, "agent_start 后节拍重算，不足不发");
+  clock += 1_500; // 距 agent_start 共 60.5s
+  await wait_for(() => (h.spawned[0]?.sends.length ?? 0) >= 2, 1500);
+  h.fire("session_shutdown");
+});
+
+test("idle_session_never_heartbeats", async () => {
+  let clock = 10_000;
+  const h = await start({
+    ownKey: "sA",
+    state: { session_id: "sA" },
+    ctx: { isIdle: () => true }, // 空闲
+    deps: { now: () => clock, heartbeatMs: 60_000 },
+  });
+  clock += 600_000; // 空闲再久也不发
+  await settle();
+  await settle();
+  assert.deepEqual(h.spawned[0].sends, [], "空闲不发心跳");
+  h.fire("session_shutdown");
+});
+
+test("outbound_speech_resets_heartbeat_clock", async () => {
+ // 出站口径（用户 2026-11-01 定）：发言发出即归位，不会刚回完话又紧跟状态卡
+  let clock = 10_000;
+  const h = await start({
+    ownKey: "sA",
+    state: { session_id: "sA" },
+    ctx: { isIdle: () => false },
+    deps: { now: () => clock, heartbeatMs: 30_000 },
+  });
+  await settle();
+  assert.deepEqual(h.spawned[0].sends, [], "起点 10s 不足节拍");
+  clock += 5_000; // 15s：agent 发言出站 → 归位
+  await h.fire("message_end", {
+    message: { role: "assistant", content: [{ type: "text", text: "先干着" }], stopReason: "toolUse", usage: {} },
+  });
+  assert.deepEqual(h.spawned[0].sends, ["先干着"]);
+  clock += 25_000; // 距发言 25s < 30s：不心跳
+  await settle();
+  assert.deepEqual(h.spawned[0].sends, ["先干着"], "发言后节拍重算，不紧跟状态卡");
+  clock += 5_000; // 距发言满 30s：心跳照发
+  await wait_for(() => (h.spawned[0]?.sends.length ?? 0) >= 2, 1500);
+  assert.ok(h.spawned[0].sends[1].includes("运行中"), "心跳卡内容正常");
+  h.fire("session_shutdown");
+});
+
+// ---------------------------------------------------------------- 换绑 / 过期
+
+test("token_change_triggers_rebind_respawn", async () => {
+  const h = await start({ ownKey: "sA", state: { session_id: "sA" } });
+  await settle();
+  assert.equal(h.spawned.length, 1);
+  h.S.save({ ...h.S.store(), bot_token: "T2" }); // 重扫换绑
+  await settle();
+  assert.equal(h.spawned[0].stopped, true, "旧渠道停");
+  assert.equal(h.spawned.length, 2, "新 token 重拉");
+  assert.equal(h.spawned[1].cfg.token, "T2");
+  assert.equal(h.S.store().session_expired, undefined, "过期旗标清除");
+  h.fire("session_shutdown");
+});
+
+test("session_dead_marks_expired_and_starts_qr_flow", async () => {
+  const h = await start({ ownKey: "sA", state: { session_id: "sA" } });
+  await settle();
+  h.spawned[0].dead = true; // 服务侧作废本 bot 会话
+  await settle();
+  assert.equal(h.S.store().session_expired, "1", "过期旗标落盘（壳灰 icon + 自动弹窗依据）");
+  await settle(30);
+  assert.ok(h.S.store().qrcode_grid, "出码流已起：QR 网格写镜像（弹窗的码就绪）");
+  h.fire("session_shutdown");
+});
+
+test("token_cleared_under_running_transport_stops_zombie", async () => {
+  const h = await start({ ownKey: "sA", state: { session_id: "sA" } });
+  await settle();
+  assert.equal(h.spawned.length, 1);
+ // 壳侧把 token 清了（重扫清理/旧版壳刷新二维码）：渠道必须跟着停 ——
+ // 否则僵尸轮询者拿内存旧 token 继续 ack，把刚清掉的路由字段整批复活
+ //
+  h.S.save({ ...h.S.store(), bot_token: undefined, buf: undefined, chat_id: undefined });
+  await settle();
+  assert.equal(h.spawned[0].stopped, true, "svc on 但盘上无 token → 停渠道（僵尸终结）");
+  assert.equal(h.spawned.length, 1, "无 token 不重拉（等扫码成功 on_rebind 自起）");
+  h.fire("session_shutdown");
+});
+
+// ---------------------------------------------------------------- 生命周期收尾
+
+test("shell_clearing_code_cancels_stale_flow_and_regenerates", async () => {
+ // 壳【刷新二维码】只清镜像（qrcode/qrcode_grid）不通知 ext：旧协程不会再发
+ // ready，若不识别就会卡到 180s 死线
+  let begins = 0;
+  const Base = fake_wire_class();
+  class CountingWire extends Base {
+    async get_qr(tag, path) {
+      if (path.includes("get_bot_qrcode")) begins += 1;
+      return super.get_qr(tag, path);
+    }
+  }
+  const h = await start({
+    ownKey: "sA",
+    state: { session_id: "sA", bot_token: undefined }, // 未绑定 → 出码
+    wire: CountingWire,
+  });
+  await wait_for(() => !!h.S.store().qrcode_grid, 3000);
+  assert.ok(h.S.store().qrcode_grid, "首轮码已就绪");
+  await settle(200); // 让泵至少看到一次落地码（qr_seen 置位）再模拟壳清码
+  const b0 = begins;
+  const st = { ...h.S.store() };
+  delete st.qrcode;
+  delete st.qrcode_grid;
+  h.S.save(st); // 壳刷新：清码，指针与开关不动
+  await wait_for(() => begins > b0, 3000);
+  assert.ok(begins > b0, "清码 → 旧协程被取消，重新出码");
+  await wait_for(() => !!h.S.store().qrcode_grid, 3000);
+  assert.ok(h.S.store().qrcode_grid, "新码写回镜像（弹窗不再停在生成中）");
+  h.fire("session_shutdown");
+});
+
+test("shutdown_stops_transport_idempotent", async () => {
+  const h = await start({ ownKey: "sA", state: { session_id: "sA" } });
+  await settle();
+  const tr = h.spawned[0];
+  await h.fire("session_shutdown");
+  await h.fire("session_shutdown"); // 幂等
+  assert.equal(tr.stopped, true, "shutdown 停渠道（不保活：进程没了服务停）");
+});
+test("resolve_session_file —— pi 首条消息前 getSessionFile 未就绪时回落到宿主键", () => {
+ // 真机 2026-10-28：切到新会话（还没发过消息）扫码成功，session_file 写 null
+ // → 壳按会话文件核对，icon 永远不亮（表现为“第一次切换绑不上，第二次才行”）
+  assert.equal(resolve_session_file(null, "C:/s/owner.jsonl"), "C:/s/owner.jsonl");
+  assert.equal(resolve_session_file("C:/s/own.jsonl", "C:/s/owner.jsonl"), "C:/s/own.jsonl", "ownFile 优先");
+  assert.equal(resolve_session_file(null, null), null);
+});
+
+test("session_file_from_argv —— 恢复会话进程的第三把身份钥匙", () => {
+ // 真机 2026-11-03：停用→启用真重启 pi 后，恢复会话的进程里 getSessionFile()
+ // 首条消息前 undefined + uuid 漂移，门控两把旧钥匙同时落空 → 服务不起、
+ // 消息无人收。pi spawn 必带 --session <file>，argv 兜底解析。
+  const argv = ["node", "cli.js", "--mode", "rpc", "--session", "C:\\s\\a.jsonl", "-ne"];
+  assert.equal(session_file_from_argv(argv), "C:\\s\\a.jsonl");
+  assert.equal(session_file_from_argv(["node", "x.js"]), null, "无 --session = null");
+  assert.equal(session_file_from_argv(["node", "x.js", "--session"]), null, "缺值 = null");
+  assert.equal(session_file_from_argv(["node", "x.js", "--session", ""]), null, "空值 = null");
+});
+
+test("switch 关再开必须能恢复通信（Stopped 终态 → 回 Pending）", async () => {
+ // 真机 2026-10-28：off 走 stop_service(true) = Stopped，wants_start 恒 false，
+ // 打开回来后渠道永远不起 → 消息不回。这里盯状态机的可达性。
+  const { Service } = await import("./state.mjs");
+  const svc = new Service();
+  svc.to_on({ send() {}, stop() {} }, "TK");
+  svc.to_stopped();
+  assert.equal(svc.wants_start(Date.now()), false, "Stopped 不自动拉起");
+  assert.equal(svc.variant, "stopped");
+  svc.to_pending(); // ext 在「enabled != 0 且 stopped」时的动作
+  assert.equal(svc.wants_start(Date.now()), true, "回 Pending 后可重启");
+});
+
+// ---------------------------------------------------------------- 启停通知（002·通知）
+// 文案 = messages.mjs 文案表单源（hook.test 逐字盯）；这里盯 3+2 触发点的接线。
+// 「已连接」= 升沿：transport 出站队列入队（sends）；「已失联」= 降沿：一次性直发
+//（directs，transport 已停不依赖渠道）。路由未就绪时升沿挂起到路由就绪（hook 面）。
+
+test("通知③ 进程重载（面板卸载→加载）+ 原有绑定 → 宣告已连接", async () => {
+  const h = await start({ ownKey: "sA", state: { session_id: "sA", chat_id: "c@im" } });
+  await wait_for(() => (h.spawned[0]?.sends ?? []).includes(WX_LINK_ON));
+  assert.deepEqual(h.directs, [], "连接是升沿：走渠道入队，不直发");
+  h.fire("session_shutdown");
+});
+
+test("通知① 用户 off → 直发失联；再 on → 重新宣告已连接", async () => {
+  const h = await start({ ownKey: "sA", state: { session_id: "sA", chat_id: "c@im" } });
+  await wait_for(() => (h.spawned[0]?.sends ?? []).includes(WX_LINK_ON));
+  h.S.save({ ...h.S.store(), enabled: "0" }); // 用户 off
+  await wait_for(() => h.directs.includes(WX_LINK_OFF));
+  assert.equal(h.spawned[0].stopped, true, "服务已停");
+  h.S.save({ ...h.S.store(), enabled: undefined }); // 用户 on
+  await wait_for(() => (h.spawned[1]?.sends ?? []).includes(WX_LINK_ON), 1500);
+  assert.deepEqual(h.directs, [WX_LINK_OFF], "重连只补一条连接，失联不重发");
+ // 诊断痕迹（notice_log）：挂起 → 发出全链留痕，真机 wx-state.json 可对账
+  const nlog = h.S.store().notice_log ?? [];
+  assert.ok(nlog.some((l) => l.includes("挂起:已连接")), "连接挂起有痕");
+  assert.ok(nlog.some((l) => l.includes("发出:已连接")), "连接发出有痕");
+  assert.ok(nlog.some((l) => l.includes("挂起:已失联")), "失联挂起有痕");
+  assert.ok(nlog.some((l) => l.includes("发出:已失联")), "失联发出有痕");
+ // svc_log：渠道迁移带原因标签（起/停+原因，面板互搏定位依据）
+  const slog = h.S.store().svc_log ?? [];
+  assert.ok(slog.some((l) => l.endsWith(" stop:switch-off user=true was_on=true")), "停机原因有痕");
+  assert.ok(slog.some((l) => l.endsWith(" on")), "起机有痕");
+  h.fire("session_shutdown");
+});
+
+test("通知② 运行中卸载（session_shutdown）→ 直发失联", async () => {
+  const h = await start({ ownKey: "sA", state: { session_id: "sA", chat_id: "c@im" } });
+  await wait_for(() => (h.spawned[0]?.sends ?? []).includes(WX_LINK_ON));
+  await h.fire("session_shutdown");
+  await settle();
+  assert.deepEqual(h.directs, [WX_LINK_OFF], "卸载即服务关停 → 直发失联");
+});
+
+test("通知 从未连接（未绑定）时卸载 → 静默", async () => {
+  const h = await start({ ownKey: "sA", state: { enabled: "0" } });
+  await settle();
+  await h.fire("session_shutdown");
+  await settle();
+  assert.deepEqual(h.directs, [], "没宣告过连接就不宣告失联");
+  assert.equal(h.spawned.length, 0);
+});
+
+test("通知 已知过期（session_expired=1）不宣告已连接", async () => {
+ // 002：链路通畅才宣告。过期旗标只能重扫解除，此时起渠道发必失败 —— 不宣告
+  const h = await start({
+    ownKey: "sA",
+    state: { session_id: "sA", chat_id: "c@im", session_expired: "1" },
+  });
+  await settle();
+  await settle();
+  assert.equal(h.spawned.length, 1, "渠道照常起（起停行为不变）");
+  assert.ok(!h.spawned[0].sends.includes(WX_LINK_ON), "过期不宣告");
+  h.fire("session_shutdown");
+});
+
+test("通知① 换绑（on_rebind）→ 停机静默 + 新渠道宣告已连接", async () => {
+ // 扫码成功与 token 变更感知都走 on_rebind：落 Pending 静默（不发失联），
+ // 新 token 渠道起来后宣告连接
+  const h = await start({ ownKey: "sA", state: { session_id: "sA", chat_id: "c@im" } });
+  await wait_for(() => (h.spawned[0]?.sends ?? []).includes(WX_LINK_ON));
+  h.S.save({ ...h.S.store(), bot_token: "T2" });
+  await wait_for(() => (h.spawned[1]?.sends ?? []).includes(WX_LINK_ON), 1500);
+  assert.deepEqual(h.directs, [], "换绑静默：不发失联");
+  h.fire("session_shutdown");
+});
+
+test("通知② 壳卸载标记（unload_ts 晚于出生）→ 主动关停 + 失联直发 + 不再复活", async () => {
+ // PF 面板停用不回调 session_shutdown（真机 2026-11-01 铁证）：wasm 壳 unload
+ // 写 unload_ts，ext 泵见晚于本进程出生时刻的标记 = 被停用 → 关停+宣告失联
+ // +释放锁，进程终态。用盘上快照比序号有竞态（快照晚于壳写 → 永不触发，
+ // tc7 实测），水位对比的是自身出生时刻，免疫此坑。
+  const h = await start({ ownKey: "sA", state: { session_id: "sA", chat_id: "c@im" } });
+  await wait_for(() => (h.spawned[0]?.sends ?? []).includes(WX_LINK_ON));
+  h.S.save({ ...h.S.store(), unload_seq: "1", unload_ts: String(Date.now()) }); // 模拟壳 unload()
+  await wait_for(() => h.directs.includes(WX_LINK_OFF));
+  assert.equal(h.spawned[0].stopped, true, "锁当场释放");
+  await settle();
+  h.S.save({ ...h.S.store(), enabled: undefined }); // 即便开关再变也不复活
+  await settle();
+  assert.equal(h.spawned.length, 1, "unloaded 终态：本进程不再起渠道");
+  const slog = h.S.store().svc_log ?? [];
+  assert.ok(slog.some((l) => l.includes("stop:shell-unload user=true was_on=true")), "停机原因有痕");
+ // unloaded 进程内粘性：runtime 替换（session_start 重入）不复活
+  await h.fire("session_start", {}, ctx_stub({ ownKey: "sA" }));
+  await settle();
+  assert.equal(h.spawned.length, 1, "session_start 重入不起渠道");
+  h.fire("session_shutdown");
+});
+
+test("通知 出生前落盘的旧标记不误报（水位 = 出生时刻，不看快照）", async () => {
+  const h = await start({
+    ownKey: "sA",
+ // 上一轮卸载残留：unload_ts 远早于本进程出生（0 = 无标记同口径）
+    state: { session_id: "sA", chat_id: "c@im", unload_seq: "3", unload_ts: "1" },
+  });
+  await settle();
+  await settle();
+  assert.equal(h.spawned.length, 1, "照常起渠道");
+  assert.deepEqual(h.directs, [], "旧标记不是本次卸载：不报失联");
+  h.S.save({ ...h.S.store(), unload_seq: "4", unload_ts: String(Date.now()) }); // 本进程生命内的真卸载
+  await wait_for(() => h.directs.includes(WX_LINK_OFF));
+  h.fire("session_shutdown");
+});
+
+test("通知 boot 期吃标记：session_start 前已落盘的新标记 → 自我隔离不起渠道", async () => {
+ // tc7 实测的 attach 重启竞态：壳在 ext 出生与 session_start 之间写入标记，
+ // 旧语义（快照序号当基线）会照抄新值、永不触发，服务反而在停用后起来。
+ // 新语义：出生后落盘的标记在 session_start 当场置 unloaded，渠道不起。
+  const h = await start({
+    ownKey: "sA",
+    state: {
+      session_id: "sA",
+      chat_id: "c@im",
+      unload_seq: "1",
+      unload_ts: String(Date.now() + 50), // 出生后才会出现的标记（未来 50ms）
+    },
+  });
+  await settle();
+  await settle();
+  assert.equal(h.spawned.length, 0, "boot 期已停用：渠道绝不起");
+  const slog = h.S.store().svc_log ?? [];
+  assert.ok(slog.some((l) => l.includes("boot-after-unload")), "自我隔离有痕");
+  h.fire("session_shutdown");
+});