@pi-flash-plugins/pf-wxbot 0.1.3 → 0.2.0

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@pi-flash-plugins/pf-wxbot",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "engines": {
-    "pf": ">=0.3.2"
+    "pf": ">=0.4.0"
   },
   "publishConfig": {
     "access": "public",

package/pf-plugin.toml

@@ -2,7 +2,7 @@
 schema = 5
 id = "pf-wxbot"
 title = { zh = "微信通信", en = "PF-WeChat" }
-version = "0.1.3"
+version = "0.2.0"
 
 wasm = "plugin.wasm"
 

package/pi/index.mjs

@@ -39,18 +39,6 @@ function default_session_exists(key) {
   }
 }
 
-/** 绑定落地的会话文件键：ownFile → 宿主给的 qr_owner 键（pi 首条消息前
- * getSessionFile() 是 undefined，只写 uuid 会让壳的 icon/badge 永远匹配不上）。 */
-export function resolve_session_file(ownFile, ownerKey) {
-  return ownFile ?? ownerKey ?? null;
-}
-
-/** 本进程出生时刻（模块加载即定格，早于 session_start 数百毫秒）。卸载
- * 水位线：壳写的 unload_ts > BOOT_TS = 本进程服役期内被停用。与盘上快照
- * 无关，免疫「快照晚于壳写」竞态与整文件回写弄脏序号两类坑。
- */
-const BOOT_TS = Date.now();
-
 const TICK_MS = 200; // 泵节拍（mod.rs 200ms 采样同款）
 const SESSION_CHECK_TICKS = 150; // 会话存在性校验周期（150 拍 ≈ 30s；可注 deps.sessionCheckTicks）
 // 运行中心跳节拍默认 30s（2026-11-01 buglist#1 定案，用户拍板 30s）：agent
@@ -79,10 +67,6 @@ export function create_entry(deps = {}) {
   const now = deps.now ?? (() => Date.now());
   const S = deps.state ?? state; // state 模块面（测试注内存盘）
   const sessionExists = deps.sessionExists ?? null; // (sessionKey) => Promise<bool|null>；null = 通道未接（PF 轨）
-  const ownKeyOf =
-    deps.ownKeyOf ??
-    ((sessionCtx) => sessionCtx?.sessionManager?.getSessionId?.() ?? null);
-
   /** 原子写状态键（读-改-写当场盘，最小面复用 set/save）。 */
   function set_keys(keys) {
     const st = S.load();
@@ -98,7 +82,6 @@ export function create_entry(deps = {}) {
     const snap = new Snapshot({ stat: deps.stat, load: S.load });
     let ctx = null; // session 域上下文（session_start 绑定）
     let ownKey = null; // 本进程会话身份（门控比对源：getSessionId）
-    let ownFile = null; // 会话文件路径（门控双口径之二：getSessionFile）
     let wasActive = null; // 上一拍门控结果（null = 未判定；失绑清旗的依据）
     let started_once = false; // 本进程成功起过渠道（「已连接」③判据：重载后首连）
     let announce_next = false; // 待宣告「已连接」：①换绑落地 / ②用户 off→on（to_on 时冲）
@@ -332,7 +315,7 @@ export function create_entry(deps = {}) {
             set_keys({
  // 单变量模型：绑定 id = **PF 会话键**（点 icon 时宿主给的那把），
  // 不是 pi 的 uuid —— 壳/列表/钩子全用同一把键比对
-              session_id: ownerKey ?? ownFile ?? ownKey ?? null,
+              session_id: ownerKey ?? ownKey ?? null,
               session_file: null, // 单变量模型：不再存会话文件（壳只认 session_id）
               qr_pending: null,
               qr_request: null,
@@ -394,42 +377,44 @@ export function create_entry(deps = {}) {
       const pendingKey = S.get_str(st, "qr_pending");
       const enabled = S.get_str(st, "enabled");
 
- // 壳卸载标记（002·通知②；PF 面板停用不回调 session_shutdown 的补信号）：
- // 水位 = 本进程出生时刻（BOOT_TS，模块加载即定格，早于 session_start）。壳
- // 写的 unload_ts 比它新 = 插件被停用 → 主动关停 + 宣告「已失联」+ 释放锁
- //（重载秒连），本进程进 unloaded 终态——面板再启用 = 新 runtime（新
- // BOOT_TS），本进程不复活。不用盘上快照比序号：快照本身会晚于壳写
- //（attach 重启竞态：新 ext 的 session_start 落在壳写之后，照抄新值当
- // 基线，检测永不触发——tc7 实测，服务反而在停用后起来）；整文件回写
- // 覆盖也会弄脏序号比对（unload_seq 真机从 16 次卸载被打回 "1"）。
-      const uts = Number(S.get_str(st, "unload_ts") ?? 0);
-      if (!unloaded && uts > BOOT_TS) {
+ // 运行许可（005 §③，宿主协议文件 pf-runtime.json 唯一写者 = 宿主）：
+ // off → 停渠道 + 宣告「已失联」+ 取消出码 + **待机（进程保留，不自杀）**；
+ // on → 待机复活（回 Pending，门控/许可恢复后服务自起），停用→启用循环
+ // 无需重启 pi。取代旧 unload_ts 时间戳水位——壳每次 reload 都写时间戳，
+ // 出生早于写入的活 ext 一律被冤杀（真机 2026-11-03：更新重载的 ext 被
+ // 随后的 unload 水位打死，出码/收发全断）。
+      const permitted = S.runtime()?.pf_enabled !== false;
+      if (!permitted && !unloaded) {
         unloaded = true;
         if (qrCancel) {
           qrCancel();
           qrCancel = null;
         }
-        stop_service(true, "shell-unload");
+        stop_service(true, "host-disable");
+        note("host-disable idle");
+      } else if (permitted && unloaded) {
+        unloaded = false;
+        if (svc.variant === "stopped" || svc.variant === "off") svc.to_pending();
+        announce_next = true; // ⚡②许可恢复：重连后宣告「已连接」
+        note("host-enable resume");
       }
       if (unloaded) return;
 
- // 门控（双口径）：绑定键可能是 pi sessionId（uuid）或会话文件路径——
- // pi 进程重启后 uuid 会漂、首条消息前 getSessionFile() 是 undefined，
- // 单一口径必有失配窗口。门控结果落镜像：
+ // 门控（005 §② 单键）：绑定键/出码归属都与宿主注入的 PF_SESSION_KEY
+ // 规范键比对——uuid 漂移、getSessionFile 未就绪、argv 形态差异全成历史。
+ // 门控结果落镜像：
  // active → bound_current=1（仅标记身份，壳不看它）
  // 失绑 → 仅当**自己之前是激活方**才清 bound_current（多会话 ext
  // 共享一份镜像，没绑定过的不得清别人的 1 —— 防抖动）
- // 单变量模型（schema/pf-hooks.json）：只认 PF 给的两把 id——page_id（当前页）
- // 与 session_id（已绑定）。ownKey/ownFile 仅用于“我是不是被点名的那页”。
       const sameKey = (a, b) => {
         if (!a || !b) return false;
         const n = (x) => String(x).split(String.fromCharCode(92)).join("/").toLowerCase();
         return n(a) === n(b);
       };
-      const active = sameKey(boundKey, ownKey) || sameKey(boundKey, ownFile);
- // 出码归属（002·绑定2）：壳点 icon 写 qr_owner=会话键，**只**让该会话的
+      const active = sameKey(boundKey, ownKey);
+ // 出码归属（002·绑定2）：壳点 icon 写 qr_pending=会话键，**只**让该会话的
  // ext 出码。出码 ≠ 绑定：本会话不因此变 bound_current，灯不亮、徽标不打。
-      const asked = sameKey(pendingKey, ownKey) || sameKey(pendingKey, ownFile);
+      const asked = sameKey(pendingKey, ownKey);
       if (active !== wasActive || (active && snap.bound_current !== "1")) {
         if (active) {
  // 只标「我是当前绑定方」；session_file 只由扫码成功写入。
@@ -563,26 +548,17 @@ export function create_entry(deps = {}) {
     pi.on("session_start", (event, sessionCtx) => {
       ctx = sessionCtx;
       shutdown = false;
- // 卸载水位：出生前落盘的标记属上一轮生命周期，忽略；出生后落进来的
- //（含模块加载与 session_start 之间的窗口）= 本进程已被停用，当场自我
- // 隔离——渠道绝不允许在停用后起来（tc7 实测：boot 期吃标记的 ext 会
- // 照常 spawn 服务，插件已停而渠道照跑）。
-      const bootMark = Number(S.get_str(S.load(), "unload_ts") ?? 0);
-      if (bootMark > BOOT_TS) {
-        unloaded = true;
-        note("boot-after-unload");
-      }
- // unloaded 进程内粘性，不在此重置：同进程 runtime 替换（session_start 重入）
- // 不得让已停用 ext 复活渠道；重新启用 = attach 重启挂载 = 新进程。
- // 自身身份（004 §7-1）：pi ReadonlySessionManager.getSessionId()
-      ownKey = ownKeyOf(sessionCtx);
-      ownFile = (() => {
-        try {
-          return sessionCtx?.sessionManager?.getSessionFile?.() ?? null;
-        } catch {
-          return null;
-        }
-      })();
+ // 自身身份（005 §②）：**宿主注入**（PF_SESSION_KEY env，与挂载台账键 /
+ // 命令 env session.key 规范键同源）。不再用 uuid/getSessionFile/argv 猜
+ // ——首条消息前 undefined + uuid 随重启漂移，门控必失配（真机 2026-11-03）。
+      ownKey = deps.env?.PF_SESSION_KEY ?? process.env.PF_SESSION_KEY ?? null;
+ // 启动自报家门（005 现场诊断）：身份 + 运行许可 + 出码归属，落 svc_log。
+ // 身份/许可/数据目录任一错位时，这里就是第一现场（真机 2026-11-03 教训）。
+      note(
+        `boot key=${ownKey ?? "null"} pf_enabled=${
+          S.runtime()?.pf_enabled ?? "null"
+        } pending=${S.get_str(S.load(), "qr_pending") ?? "null"}`,
+      );
       line.key = ownKey;
       line.name = sessionCtx?.sessionManager?.getSessionName?.() ?? ownKey;
       snap.refresh(true);
@@ -638,7 +614,6 @@ export function create_entry(deps = {}) {
       hook.flush_notice(); // 无下一拍：当场冲（升沿无处入队自灭，降沿直发）
       ctx = null;
       ownKey = null;
-      ownFile = null;
     });
   };
 }

package/pi/index.test.mjs

@@ -5,14 +5,16 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
 
-import { create_entry, resolve_session_file } from "./index.mjs";
+import { create_entry } 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 = {}) {
+/** 内存状态盘（state.mjs 同面：load/save/get_str/set/base_dir/dump_dir/runtime）。
+ * `runtimeState`：宿主协议文件 pf-runtime.json 的内存替身（null = 缺文件 = 许可）。 */
+function mem_state(initial = {}, runtimeState = null) {
   let store = { ...initial };
+  let rt = runtimeState;
   return {
     store: () => store,
     load: () => ({ ...store }),
@@ -31,6 +33,10 @@ function mem_state(initial = {}) {
     },
     base_dir: () => "<mem>/data",
     dump_dir: () => "<mem>/dump",
+    runtime: () => rt,
+    set_runtime: (next) => {
+      rt = next;
+    },
   };
 }
 
@@ -133,9 +139,21 @@ function fake_wire_class(script = () => ({ status: "pending" })) {
   };
 }
 
-/** 标准装配：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 });
+/** 标准装配：ownKey = 宿主注入的 PF_SESSION_KEY（005 §②）；镜像 initial
+ * 与 pf-runtime 协议替身由用例给。 */
+function mk_entry({
+  ownKey = "sA",
+  state: st = {},
+  runtime: rtState = null,
+  ctx,
+  wire,
+  sessionExists,
+  deps: extra = {},
+} = {}) {
+  const S = mem_state(
+    { bot_token: "T1", bot_id: "bot@im", bot_user_id: "bot@im", ...st },
+    rtState,
+  );
   const { cls, spawned } = fake_transport_class();
   const f = fake_pi(ctx ? ctx_stub({ ownKey, ...ctx }) : ctx_stub({ ownKey }));
   const directs = []; // 降沿直发记录器（生产 = hook.mjs 真直发；测试绝不碰真盘/真网）
@@ -144,6 +162,7 @@ function mk_entry({ ownKey = "sA", state: st = {}, ctx, wire, sessionExists, dep
     Transport: cls,
     Wire: wire ?? fake_wire_class(),
     sessionExists,
+    env: { PF_SESSION_KEY: ownKey }, // 005 §② 身份注入（生产 = spawn env）
     sessionCheckTicks: 2, // 测试用快周期
     sleep: () => new Promise(() => {}), // QR 轮询挂起（不堆计时器）
     tickMs: TICK,
@@ -171,8 +190,8 @@ test("factory_registers_handlers_and_starts_nothing", () => {
 // ---------------------------------------------------------------- 门控（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 });
+async function start({ ownKey, state: st, runtime: rtState, ctx, wire, sessionExists, deps } = {}) {
+  const h = mk_entry({ ownKey, state: st, runtime: rtState, ctx, wire, sessionExists, deps });
   await h.fire("session_start", {}, ctx ? ctx_stub({ ownKey, ...ctx }) : ctx_stub({ ownKey }));
   return h;
 }
@@ -474,6 +493,24 @@ test("session_dead_marks_expired_and_starts_qr_flow", async () => {
   h.fire("session_shutdown");
 });
 
+test("qr_main_chain —— 壳点 bind 写请求 → ext 消费出码（005 T1 主链路锁）", async () => {
+ // 真机 2026-11-03 全部故障的共同受害者就是这条链：壳与 ext 状态一旦劈叉
+ // （数据目录/身份/水位任一错位），弹窗照开而码永远不出，此前 158 个单测
+ // 全部测不到。锁：未绑定会话点 icon → 壳写 qr_request/qr_pending → ext
+ // 消费 → runQrFlow begin → qrcode_grid 落镜像（弹窗有码可画）。
+  const KEY = "C:/s/a.jsonl";
+  const h = await start({ ownKey: KEY, state: {} }); // 未绑定
+  await settle();
+  assert.equal(h.spawned.length, 0, "未绑定不起渠道");
+  h.S.save({ ...h.S.store(), qr_request: "1", qr_pending: KEY }); // 壳 bind 命令的镜像写
+  await wait_for(() => !!h.S.store().qrcode_grid, 3000);
+  assert.ok(h.S.store().qrcode_grid, "ext 消费出码请求：QR 网格落镜像");
+  assert.equal(h.S.store().qr_request, undefined, "qr_request 已消费清除");
+  assert.equal(h.S.store().qr_pending, KEY, "qr_pending 保留（出码即持有归属，扫码成功才清）");
+  assert.equal(h.spawned.length, 0, "出码 ≠ 起渠道（点名未绑定态只跑出码流）");
+  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();
@@ -529,14 +566,6 @@ test("shutdown_stops_transport_idempotent", async () => {
   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("switch 关再开必须能恢复通信（Stopped 终态 → 回 Pending）", async () => {
  // 真机 2026-10-28：off 走 stop_service(true) = Stopped，wants_start 恒 false，
  // 打开回来后渠道永远不起 → 消息不回。这里盯状态机的可达性。
@@ -625,61 +654,79 @@ test("通知① 换绑（on_rebind）→ 停机静默 + 新渠道宣告已连接
   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" } });
+test("005 T3 宿主收许可（pf-runtime off）→ 停服 + 失联直发 + 待机；on → 原地复活", async () => {
+ // 005 §③：宿主写 pf-runtime.json（唯一写者），ext 泵见 off = 被停用 →
+ // 关停 + 宣告失联 + 待机（进程保留，**不自杀**）；on = 许可恢复 → 原地
+ // 复活（回 Pending，服务自起），停用→启用循环无需重启 pi。取代旧
+ // unload_ts 时间戳水位——它在 reload 循环里冤杀出生较早的活 ext
+ //（真机 2026-11-03：更新重载的 ext 被随后的 unload 水位打死）。
+  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()
+  h.S.set_runtime({ pf_enabled: false, pf_seq: 2, pf_reason: "disable" }); // 宿主 evict
   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 重入不起渠道");
+  assert.ok(slog.some((l) => l.includes("stop:host-disable user=true was_on=true")), "停机原因有痕");
+  assert.ok(slog.some((l) => l.includes("host-disable idle")), "待机有痕（非终态）");
+  h.S.set_runtime({ pf_enabled: true, pf_seq: 3, pf_reason: "enable" }); // 宿主 attach
+  await wait_for(() => (h.spawned[1]?.sends ?? []).includes(WX_LINK_ON), 1500);
+  assert.equal(h.spawned.length, 2, "许可恢复：原地复活新渠道（进程未重启）");
+  const slog2 = h.S.store().svc_log ?? [];
+  assert.ok(slog2.some((l) => l.includes("host-enable resume")), "复活有痕");
   h.fire("session_shutdown");
 });
 
-test("通知 出生前落盘的旧标记不误报（水位 = 出生时刻，不看快照）", async () => {
+test("005 T3 boot 期许可已收（宿主先于 ext 出生写 off）→ 隔离不起渠道；on → 复活", async () => {
+ // tc7 场景的新协议形态：attach 重启竞态下宿主在 ext 出生前已写 off——
+ // 渠道绝不起；许可恢复后原地复活（水位时代的「终态不复活」已成历史）。
   const h = await start({
     ownKey: "sA",
- // 上一轮卸载残留：unload_ts 远早于本进程出生（0 = 无标记同口径）
-    state: { session_id: "sA", chat_id: "c@im", unload_seq: "3", unload_ts: "1" },
+    state: { session_id: "sA", chat_id: "c@im" },
+    runtime: { pf_enabled: false, pf_seq: 1, pf_reason: "disable" },
   });
   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));
+  assert.equal(h.spawned.length, 0, "boot 期已停用：渠道绝不起");
+  const slog = h.S.store().svc_log ?? [];
+  assert.ok(slog.some((l) => l.includes("host-disable idle")), "待机有痕");
+  h.S.set_runtime({ pf_enabled: true, pf_seq: 2, pf_reason: "enable" });
+  await wait_for(() => h.spawned.length === 1, 1500);
+  assert.equal(h.spawned.length, 1, "许可恢复：原地复活");
   h.fire("session_shutdown");
 });
 
-test("通知 boot 期吃标记：session_start 前已落盘的新标记 → 自我隔离不起渠道", async () => {
- // tc7 实测的 attach 重启竞态：壳在 ext 出生与 session_start 之间写入标记，
- // 旧语义（快照序号当基线）会照抄新值、永不触发，服务反而在停用后起来。
- // 新语义：出生后落盘的标记在 session_start 当场置 unloaded，渠道不起。
+test("005 T3 缺协议文件 = 许可（兜底安全，旧 PF 兼容）", async () => {
   const h = await start({
     ownKey: "sA",
-    state: {
-      session_id: "sA",
-      chat_id: "c@im",
-      unload_seq: "1",
-      unload_ts: String(Date.now() + 50), // 出生后才会出现的标记（未来 50ms）
-    },
+    state: { session_id: "sA", chat_id: "c@im" },
+    runtime: null, // 缺文件
   });
-  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")), "自我隔离有痕");
+  await wait_for(() => (h.spawned[0]?.sends ?? []).includes(WX_LINK_ON));
+  assert.deepEqual(h.directs, [], "无 off 不报失联");
   h.fire("session_shutdown");
 });
+
+test("005 T2 进程重启模拟：新 ext（env 身份）+ 同镜像 → 服务自恢复", async () => {
+ // 真机 2026-11-03 全部故障的回归锁：停用→启用/更新链重启 pi 后，新 ext
+ // 进程凭宿主注入的 PF_SESSION_KEY 认回同一会话 → 门控命中 → 服务自起，
+ // 无需用户先打字预热（旧身份三钥匙在恢复进程里全落空）。
+  const KEY = "C:/s/a.jsonl";
+  const first = await start({
+    ownKey: KEY,
+    state: { session_id: KEY, chat_id: "c@im" },
+  });
+  await wait_for(() => (first.spawned[0]?.sends ?? []).includes(WX_LINK_ON));
+  first.fire("session_shutdown"); // 旧进程消亡（镜像留在「盘上」）
+  // 新进程：全新装配，仅 env 身份 + 盘上镜像（上一轮 S 的 store）
+  const second = await start({
+    ownKey: KEY,
+    state: { ...first.S.store(), bot_token: "T1", bot_id: "bot@im", bot_user_id: "bot@im" },
+  });
+  await wait_for(() => (second.spawned[0]?.sends ?? []).includes(WX_LINK_ON), 1500);
+  assert.equal(second.spawned.length, 1, "新 ext 门控命中：服务自恢复");
+  assert.equal(second.S.store().bound_current, "1", "激活方标记落回");
+  second.fire("session_shutdown");
+});

package/pi/lock.mjs

@@ -8,9 +8,15 @@
 // - 心跳每 HEARTBEAT_MS 刷一次 `lease-<nonce>` 的 mtime；
 // - 抢占时只有「租约新鲜」才让路，否则删掉陈旧锁目录重试。
 //
-// 与 ZCode 的唯一差异（wxprobe 同款）：只用**租约新鲜度**判死活——心跳 10s
+// 与 ZCode 的唯一差异（wxprobe 同款）：以**租约新鲜度**为主判据——心跳 10s
 // 刷一次 mtime，租约 30s 未刷在本机语义上等价于持有者已死。
 //
+// **同机快路**（2026-11-03 补）：owner.json 带 `host`，同主机且 pid 已不存在 →
+// 当场接管，不等 30s 租约过期。真机：PF 退出时 pi 子进程被直接杀掉，ext
+// 来不及 `release()`，新实例启动只能干等租约到期（开机到 `on` 实测 18s）——
+// 用户看到的就是「重启后十几秒不给我发已连接」。异主机/旧格式（无 host）
+// 一律回落租约语义，避免网络盘共享数据目录时 PID 号巧合误判。
+//
 // **锁根必须是全局目录**（`~/.pi-flash/bots-runtime-locks/`）：真机历史上
 // PF 自带轮询器（remote_control / wxprobe 探针）曾与本插件抢同一个 bot——
 // 那两个实现已移除（微信通信现只有本插件），但锁位仍是**跨实现共享约定**：
@@ -23,7 +29,7 @@ import {
   existsSync, mkdirSync, readFileSync, renameSync,
   rmSync, statSync, utimesSync, writeFileSync,
 } from "node:fs";
-import { homedir } from "node:os";
+import { homedir, hostname } from "node:os";
 import { join } from "node:path";
 import { sha256_hex } from "./wire.mjs";
 
@@ -74,6 +80,7 @@ export async function acquire(namespace, lockKey, botId, { heartbeatMs = HEARTBE
     botId,
     nonce: `${Date.now().toString(16)}${process.pid.toString(16)}`,
     createdAt: now_ms(),
+    host: hostname(), // 同机 pid 快判的依据（异主机不认识 → 回落租约）
   };
   mkdirSync(join(lock_root(), namespace), { recursive: true });
 
@@ -108,10 +115,12 @@ export async function acquire(namespace, lockKey, botId, { heartbeatMs = HEARTBE
       await remove_dir_with_retry(lockPath);
       continue;
     }
- // 竞争分支：只有「租约仍新鲜」才让路
+ // 竞争分支：先看「同机 pid 已死」快路，再落到租约新鲜度
+    // （顺序不能反：pid 快路只是**提前**判死，不改变「活者让路」语义）
     const leaseAt = lease_mtime(lockPath, current.nonce);
     const age = now_ms() - Math.max(leaseAt, 0);
-    if (leaseAt > 0 && age < leaseMs) return null;
+    const dead_here = is_same_host_dead(current);
+    if (!dead_here && leaseAt > 0 && age < leaseMs) return null;
     await remove_dir_with_retry(lockPath);
   }
   return null;
@@ -124,7 +133,13 @@ function now_ms() {
 function write_owner(dir, owner) {
   writeFileSync(
     join(dir, "owner.json"),
-    JSON.stringify({ pid: owner.pid, botId: owner.botId, nonce: owner.nonce, createdAt: owner.createdAt }, null, 2),
+    JSON.stringify({
+      pid: owner.pid,
+      botId: owner.botId,
+      nonce: owner.nonce,
+      createdAt: owner.createdAt,
+      host: owner.host,
+    }, null, 2),
   );
 }
 
@@ -132,12 +147,31 @@ function read_owner(lockPath) {
   try {
     const v = JSON.parse(readFileSync(join(lockPath, "owner.json"), "utf8"));
     if (typeof v.pid !== "number" || typeof v.botId !== "string" || typeof v.nonce !== "string") return null;
-    return v;
+    return v; // host 可缺（旧格式）：缺失 = 未知主机 = 回落租约语义
   } catch {
     return null;
   }
 }
 
+/** 持有者是不是**本机**上一个已经消失的进程（崩溃/被杀，来不及 release）。
+ * 旧格式（无 host）/ 异主机 / pid 仍活 → false（保守：让路给租约）。 */
+export function is_same_host_dead(owner) {
+  if (!owner || typeof owner.host !== "string" || owner.host === "") return false;
+  if (owner.host !== hostname()) return false;
+  return !pid_alive(owner.pid);
+}
+
+/** pid 存活探测（跨平台）：ESRCH = 不存在；EPERM = 存在但无权限（算活）。 */
+function pid_alive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return e?.code === "EPERM";
+  }
+}
+
 function lease_mtime(lockPath, nonce) {
   try {
     return statSync(join(lockPath, `lease-${nonce}`)).mtimeMs;

package/pi/lock.test.mjs

@@ -0,0 +1,125 @@
+// lock.test —— 本地租约锁：同机死进程快路接管（2026-11-03）。
+//
+// 背景（真机）：PF 退出时 pi 子进程被直接杀掉，ext 来不及 `release()`，锁目录
+// 留在 `<数据目录>/bots-runtime-locks/` 里且租约还新鲜（30s）→ 新实例启动只能
+// 干等租约到期，实测「开机 → 服务 on」18s，用户看到的就是「重启后十几秒不给
+// 我发已连接」。修法：owner.json 带 host，**同主机且 pid 已不存在**当场接管。
+// 异主机 / 旧格式（无 host）/ pid 仍活 → 一律回落租约语义（不改变互斥保证）。
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync, utimesSync, writeFileSync } from "node:fs";
+import { hostname, tmpdir } from "node:os";
+import { join } from "node:path";
+import { createHash } from "node:crypto";
+
+import { acquire, is_same_host_dead, LEASE_MS, HEARTBEAT_MS } from "./lock.mjs";
+
+const sha256 = (s) => createHash("sha256").update(s, "utf8").digest("hex");
+
+/** 造一份「已存在的锁」：返回 lockPath（不经过 acquire，好自由设定 owner）。
+ * 租约 mtime 默认 = 刚心跳过（新鲜）；`lease_age_ms` > 0 则改成那么久之前。 */
+function plant_lock(base, ns, key, owner, { lease_age_ms = 0 } = {}) {
+  const lockPath = join(base, "bots-runtime-locks", ns, `${sha256(key)}.lock`);
+  mkdirSync(lockPath, { recursive: true });
+  writeFileSync(join(lockPath, "owner.json"), JSON.stringify(owner, null, 2));
+  const lease = join(lockPath, `lease-${owner.nonce}`);
+  writeFileSync(lease, "");
+  if (lease_age_ms > 0) {
+    const t = new Date(Date.now() - lease_age_ms);
+    utimesSync(lease, t, t);
+  }
+  return lockPath;
+}
+
+/** 一个「肯定不存在」的 pid：向下探测号段，撞到 ESRCH 即停。 */
+function dead_pid() {
+  for (let pid = 999_990; pid > 999_900; pid -= 1) {
+    let alive = true;
+    try {
+      process.kill(pid, 0);
+    } catch (e) {
+      if (e?.code === "ESRCH") alive = false;
+    }
+    if (!alive) return pid;
+  }
+  return 999_000;
+}
+
+function with_base(fn) {
+  const base = mkdtempSync(join(tmpdir(), "pf-lock-"));
+  const prev = process.env.PI_FLASH_DIR;
+  process.env.PI_FLASH_DIR = base; // lock_root() 每次读环境
+  return Promise.resolve(fn(base)).finally(() => {
+    if (prev === undefined) delete process.env.PI_FLASH_DIR;
+    else process.env.PI_FLASH_DIR = prev;
+    rmSync(base, { recursive: true, force: true });
+  });
+}
+
+const NS = "weixin-polling";
+const KEY = "bot-token-fixture";
+
+test("same_host_dead_owner_takes_over_immediately", () =>
+  with_base(async (base) => {
+    plant_lock(base, NS, KEY, {
+      pid: dead_pid(),
+      botId: "dead@im.bot",
+      nonce: "n1",
+      createdAt: Date.now(),
+      host: hostname(),
+    });
+    const t0 = Date.now();
+    const lock = await acquire(NS, KEY, "self@im.bot", { heartbeatMs: HEARTBEAT_MS, leaseMs: LEASE_MS });
+    const elapsed = Date.now() - t0;
+    assert.ok(lock, "同机死持有者必须能立刻接管");
+    assert.ok(elapsed < 2000, `接管应即时（实测 ${elapsed}ms）——不得等 30s 租约`);
+    lock.release();
+  }));
+
+test("live_owner_still_blocks", () =>
+  with_base(async (base) => {
+    plant_lock(base, NS, KEY, {
+      pid: process.pid, // 自己 = 活
+      botId: "live@im.bot",
+      nonce: "n2",
+      createdAt: Date.now(),
+      host: hostname(),
+    });
+    const lock = await acquire(NS, KEY, "self@im.bot", { heartbeatMs: HEARTBEAT_MS, leaseMs: LEASE_MS });
+    assert.equal(lock, null, "租约新鲜且持有者活着 → 必须让路");
+  }));
+
+test("legacy_owner_without_host_falls_back_to_lease", () =>
+  with_base(async (base) => {
+    plant_lock(base, NS, KEY, {
+      pid: dead_pid(), // pid 死了，但旧格式没 host：不敢判死
+      botId: "legacy@im.bot",
+      nonce: "n3",
+      createdAt: Date.now(),
+    });
+    const lock = await acquire(NS, KEY, "self@im.bot", { heartbeatMs: HEARTBEAT_MS, leaseMs: LEASE_MS });
+    assert.equal(lock, null, "旧格式（无 host）回落租约：不能靠 pid 号冒险接管");
+  }));
+
+test("stale_lease_without_pid_fast_path_takes_over", () =>
+  with_base(async (base) => {
+    plant_lock(
+      base,
+      NS,
+      KEY,
+      { pid: dead_pid(), botId: "old@im.bot", nonce: "n4", createdAt: Date.now() - 60_000, host: hostname() },
+      { lease_age_ms: 60_000 },
+    );
+    const lock = await acquire(NS, KEY, "self@im.bot", { heartbeatMs: HEARTBEAT_MS, leaseMs: 30_000 });
+    assert.ok(lock, "租约过期 → 照旧接管（原有语义不变）");
+    lock.release();
+  }));
+
+test("is_same_host_dead_predicates", () => {
+  assert.equal(is_same_host_dead(null), false);
+  assert.equal(is_same_host_dead({ pid: dead_pid(), host: hostname() }), true);
+  assert.equal(is_same_host_dead({ pid: process.pid, host: hostname() }), false);
+  assert.equal(is_same_host_dead({ pid: dead_pid(), host: "another-host" }), false);
+  assert.equal(is_same_host_dead({ pid: dead_pid() }), false, "无 host = 未知主机");
+});

package/pi/register.mjs

@@ -102,15 +102,24 @@ export function normalize(status) {
 
 // ---------------------------------------------------------------- 状态落地
 
-/** 扫码成功后清掉属于**上一个 bot 会话**的路由字段。
- * 游标/对端/上下文都绑在旧 token 上：换绑后带着它们用新 token 去 getupdates，
- * iLink 以 errcode:-14 拒之（2026-10-23 真机事故）。`session_key` 是 PF 侧
- * 会话归属，与 bot 无关，保留。 */
+/** 扫码成功后清掉**绑在旧 bot token / 旧会话上下文**的字段：
+ * - `buf`：getUpdates 游标（token 级）。换绑后带旧游标去 getupdates，iLink 以
+ *   errcode:-14 拒之（2026-10-23 真机事故）——必须清。
+ * - `context_token`：上一轮会话上下文（会话级），随旧会话过期——清。
+ *
+ * **对端 `chat_id` / `user_id` 保留**（2026-11-03 改）：它是「谁在用这个微信
+ * 机器人」的**用户级**身份，跨 bot 换代稳定。清掉它，新 bot 就再也找不到对端，
+ * 「已连接」只能挂在待发队列里等用户第一条入站消息（它才带回 user_id）——
+ * 真机：重绑新 bot → 立刻退出 → 重启，十几秒无任何通知，直到用户主动发微信
+ * 才「已连接 + agent 回复」一起到（用户当成插件失效）。发送本身不依赖
+ * context_token（真机验证：清 ctx、留 user_id，sendmessage 正常受理）。
+ * `session_key` 是 PF 侧会话归属，与 bot 无关，保留。 */
 export function reset_session_fields(st) {
-  for (const k of ["buf", "chat_id", "user_id", "context_token"]) delete st[k];
+  for (const k of ["buf", "context_token"]) delete st[k];
 }
 
-/** 重绑落地：**清旧路由字段 + 写新 bot 三件**（2026-10-24 用户定夺）。
+/** 重绑落地：**清旧会话字段（游标/上下文）+ 写新 bot 三件**（2026-10-24 用户定夺；
+ * 对端保留见 [`reset_session_fields`]）。
  * 必须喂**当场 loadState()** 的内容——严禁攥着旧快照整文件回写（自动续码
  * 时代每个到期 worker 都把 begin 时的快照原样 save，把换绑刚写好的
  * bot_token 盖回旧值——「重绑就废」的根因）。 */

package/pi/register.test.mjs

@@ -63,9 +63,11 @@ test("rebind_clears_old_routing_fields_and_swaps_bot", () => {
   assert.equal(st.bot_token, "NEW-TOKEN");
   assert.equal(st.bot_id, "new@im.bot");
   assert.equal(st.bot_user_id, "new@im.bot", "from_user_id 必须跟新 bot 走");
-  for (const k of ["buf", "chat_id", "user_id", "context_token", "qrcode", "qrcode_grid"]) {
+  for (const k of ["buf", "context_token", "qrcode", "qrcode_grid"]) {
     assert.ok(st[k] === undefined || st[k] === null, `${k} 必须被清掉`);
   }
+  assert.equal(st.user_id, "old@im.wechat", "对端是用户级身份，跨 bot 保留（否则已连接发不出）");
+  assert.equal(st.chat_id, "old@im.wechat", "群聊对端同理保留");
   assert.equal(st.session_key, "C:\\s.jsonl", "PF 侧会话归属保留");
 });
 
@@ -80,9 +82,16 @@ test("reset_clears_old_bot_routing_fields", () => {
     session_key: "C:\\sess\\a.jsonl",
   };
   reset_session_fields(st);
-  for (const k of ["buf", "chat_id", "user_id", "context_token"]) {
-    assert.ok(st[k] === undefined || st[k] === null, `${k} 必须被清掉——留着就是旧 bot 会话的游标/对端`);
+  // 游标（token 级）/ 上下文（会话级）必须清：带旧游标用新 token 去 getupdates
+  // 会被 iLink 以 errcode:-14 拒（2026-10-23 真机事故）
+  for (const k of ["buf", "context_token"]) {
+    assert.ok(st[k] === undefined || st[k] === null, `${k} 必须被清掉`);
   }
+  // 对端必须留：清了新 bot 就找不到人，「已连接」只能等用户先发消息
+  //（真机 2026-11-03：重绑→退出→重启，十几秒无通知，直到用户发微信才
+  // 「已连接 + 回复」一起到）
+  assert.equal(st.user_id, "u@im.wechat", "对端 user_id 保留");
+  assert.equal(st.chat_id, "room@im.wechat", "对端 chat_id 保留");
   assert.equal(st.session_key, "C:\\sess\\a.jsonl", "PF 侧会话归属保留");
   assert.equal(st.bot_token, "new-token", "新 bot 字段不受影响");
 });

package/pi/state.mjs

@@ -10,12 +10,26 @@
 // 先写游标会让进程中途失败时跳过未处理消息（weixinChannelRuntime.ts:155-163）。
 
 import { mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { basename, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { parse } from "./jsonx.mjs";
 
-const pkgDir = join(dirname(fileURLToPath(import.meta.url)), "..");
-const dataDir = join(pkgDir, "data");
+/** 包内 data 目录解析——**两档布局自定位**（005 §①，90-4 契约 `<pkg>/data`
+ * 无版本维度）：源码/dev 平铺（`<pkg>/pi/` 上跳一级 = 包根）与 market 版本层
+ * （`<pkg>/<ver>/pi/` 上跳一级 = 版本目录，须再跳一级）。此前只跳一级，安装
+ * 布局下落版本层 `<ver>/data`，与壳（宿主 dataDir=包层）劈叉——出码/收发
+ * 全断（真机 2026-11-03，协调层九连故障的原罪）。判据：上跳一级的目录名
+ * 以数字开头（semver 版本目录）即再多跳一级；`data/`、`.cache/` 等非版本
+ * 目录不受影响。
+ * @param {string} pi_dir ext 模块所在目录（…/pi）
+ */
+export function resolve_data_dir(pi_dir) {
+  const up1 = join(pi_dir, "..");
+  const pkgDir = /^\d/.test(basename(up1)) ? join(up1, "..") : up1;
+  return join(pkgDir, "data");
+}
+
+const dataDir = resolve_data_dir(dirname(fileURLToPath(import.meta.url)));
 
 /** 包内状态目录（约定①）。 */
 export function base_dir() {
@@ -30,6 +44,19 @@ export function dump_dir() {
   return join(dataDir, "dump");
 }
 
+/** 宿主协议文件 `<pkg>/pf-runtime.json`（005 §③，90-4 §8）：宿主写、插件
+ * 只读的运行许可。缺文件/坏 JSON = 许可（兜底安全）。返回
+ * `{pf_enabled, pf_seq, pf_reason}` 或 null。 */
+export function runtime() {
+  try {
+    const raw = readFileSync(join(dirname(dataDir), "pf-runtime.json"), "utf8");
+    const v = parse(raw);
+    return v && typeof v === "object" && !Array.isArray(v) ? v : null;
+  } catch {
+    return null;
+  }
+}
+
 /** 坏 JSON / 缺文件 → {}（宿主把坏盘落成空串，兜底是插件的责任）。 */
 export function load() {
   try {

package/pi/state.test.mjs

@@ -136,3 +136,25 @@ test("snapshot_missing_file_retries_every_beat", () => {
   assert.equal(snap.refresh(false), true, "null 不命中缓存短路");
   assert.equal(snap.refresh(false), true);
 });
+
+// ---------------------------------------------------------------- data 目录两档布局（005 §①）
+
+import { resolve_data_dir } from "./state.mjs";
+
+test("resolve_data_dir —— 源码/dev 平铺与 market 版本层都落 <pkg>/data", () => {
+  // dev 平铺：<pkg>/pi → 上跳一级 = 包根（目录名非数字开头）
+  assert.equal(
+    resolve_data_dir("D:/w/packages/pf-wxbot/pi").replaceAll("\\", "/"),
+    "D:/w/packages/pf-wxbot/data",
+  );
+  // market 版本层：<pkg>/<ver>/pi → 上跳一级是版本目录（数字开头）→ 再跳一级
+  assert.equal(
+    resolve_data_dir("C:/u/.pi-flash/plugins/@x__pf-wxbot/0.1.4/pi").replaceAll("\\", "/"),
+    "C:/u/.pi-flash/plugins/@x__pf-wxbot/data",
+  );
+  // 版本层多段版本号（0.10.2 同样数字开头）
+  assert.equal(
+    resolve_data_dir("C:/p/@x__w/0.10.2/pi").replaceAll("\\", "/"),
+    "C:/p/@x__w/data",
+  );
+});