@xmoxmo/bncr 0.1.0 → 0.1.2

package/README.md

@@ -34,6 +34,14 @@ openclaw plugins update bncr
 openclaw gateway restart
 ```
 
+> 兼容范围：`openclaw >= 2026.3.22`
+>
+> 如果你是从精确版本升级，或本地安装记录仍钉在旧版本，也可以显式执行：
+>
+> ```bash
+> openclaw plugins install @xmoxmo/bncr@0.1.1
+> openclaw gateway restart
+> ```
 
 ### Bncr / 无界侧
 
@@ -137,7 +145,35 @@ openclaw health --json
 
 ---
 
-## 8. 自检与测试
+## 8. 常见安装/加载问题
+
+### 报错：`Cannot find module 'openclaw/plugin-sdk/core'`
+
+这通常不是 bncr 没装上，而是：
+
+- bncr 已经安装到 `~/.openclaw/extensions/bncr`
+- 但插件目录当前解析不到宿主 `openclaw` 包
+- 因而在加载 `openclaw/plugin-sdk/core` 时失败
+
+bncr 0.1.1 会先尝试自动修复插件目录下的 `node_modules/openclaw` 解析链；如果仍失败，可手动执行：
+
+```bash
+mkdir -p ~/.openclaw/extensions/bncr/node_modules
+ln -s "$(npm root -g)/openclaw" ~/.openclaw/extensions/bncr/node_modules/openclaw
+openclaw gateway restart
+openclaw plugins inspect bncr
+```
+
+如果 `npm root -g` 指向的不是实际宿主位置，请先检查：
+
+```bash
+which openclaw
+npm root -g
+```
+
+然后把 `openclaw` 的真实安装目录软链接到 `~/.openclaw/extensions/bncr/node_modules/openclaw`。
+
+## 9. 自检与测试
 
 ```bash
 cd plugins/bncr
@@ -151,6 +187,18 @@ npm pack
 - `npm test`：跑回归测试
 - `npm run selfcheck`：检查插件骨架是否完整
 - `npm pack`：确认当前版本可正常打包
+- `npm run check-register-drift -- --duration-sec 300 --interval-sec 15`：静置采样 `bncr.diagnostics`，观察 `registerCount / apiGeneration / postWarmupRegisterCount` 是否在 warmup 后继续增长
+
+示例输出重点：
+
+- `delta.registerCount`
+- `delta.apiGeneration`
+- `delta.postWarmupRegisterCount`
+- `historicalWarmupExternalDrift`
+- `newDriftDuringWindow`
+- `last.postWarmupRegisterCount`
+- `last.unexpectedRegisterAfterWarmup`
+- `driftDetected`
 
 ---
 

package/index.ts

@@ -1,31 +1,292 @@
-import type {
-  OpenClawPluginApi,
-  GatewayRequestHandlerOptions,
-} from "openclaw/plugin-sdk/core";
-import { BncrConfigSchema } from "./src/core/config-schema.ts";
-import { createBncrBridge, createBncrChannelPlugin } from "./src/channel.ts";
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { BncrConfigSchema } from './src/core/config-schema.ts';
 
-type BridgeSingleton = ReturnType<typeof createBncrBridge>;
+const pluginFile = fileURLToPath(import.meta.url);
+const pluginDir = path.dirname(pluginFile);
+const pluginRequire = createRequire(import.meta.url);
+const sdkCoreSpecifier = 'openclaw/plugin-sdk/core';
+const linkType = process.platform === 'win32' ? 'junction' : 'dir';
+
+type ChannelModule = typeof import('./src/channel.ts');
+type OpenClawPluginApi = Parameters<ChannelModule['createBncrBridge']>[0];
+type BridgeSingleton = ReturnType<ChannelModule['createBncrBridge']>;
+
+type LoadedRuntime = {
+  createBncrBridge: ChannelModule['createBncrBridge'];
+  createBncrChannelPlugin: ChannelModule['createBncrChannelPlugin'];
+};
+
+const BNCR_REGISTER_META = Symbol.for('bncr.register.meta');
+
+type RegisterMeta = {
+  service?: boolean;
+  channel?: boolean;
+  methods?: Set<string>;
+  apiInstanceId?: string;
+  registryFingerprint?: string;
+};
+
+type OpenClawPluginApiWithMeta = OpenClawPluginApi & {
+  [BNCR_REGISTER_META]?: RegisterMeta;
+};
+
+let runtime: LoadedRuntime | null = null;
+const identityIds = new WeakMap<object, string>();
+let identitySeq = 0;
+
+const tryExec = (command: string, args: string[]) => {
+  try {
+    return execFileSync(command, args, {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+  } catch {
+    return '';
+  }
+};
+
+const readOpenClawPackageName = (pkgPath: string) => {
+  try {
+    const raw = fs.readFileSync(pkgPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    return typeof parsed?.name === 'string' ? parsed.name : '';
+  } catch {
+    return '';
+  }
+};
+
+const findOpenClawPackageRoot = (startPath: string) => {
+  let current = startPath;
+  try {
+    current = fs.realpathSync(startPath);
+  } catch {
+    // keep original path when realpath fails
+  }
+
+  let cursor = current;
+  while (true) {
+    const statPath = fs.existsSync(cursor) ? cursor : path.dirname(cursor);
+    const pkgPath = path.join(statPath, 'package.json');
+    if (fs.existsSync(pkgPath) && readOpenClawPackageName(pkgPath) === 'openclaw') {
+      return statPath;
+    }
+    const parent = path.dirname(statPath);
+    if (parent === statPath) break;
+    cursor = parent;
+  }
+  return '';
+};
+
+const unique = (items: string[]) => {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const item of items) {
+    if (!item) continue;
+    const normalized = path.normalize(item);
+    if (seen.has(normalized)) continue;
+    seen.add(normalized);
+    out.push(normalized);
+  }
+  return out;
+};
+
+const collectOpenClawCandidates = () => {
+  const directCandidates = [
+    path.join(pluginDir, 'node_modules', 'openclaw'),
+    path.join('/usr/lib/node_modules', 'openclaw'),
+    path.join('/usr/local/lib/node_modules', 'openclaw'),
+    path.join('/opt/homebrew/lib/node_modules', 'openclaw'),
+    path.join(process.env.HOME || '', '.npm-global/lib/node_modules', 'openclaw'),
+  ];
+
+  const npmRoot = tryExec('npm', ['root', '-g']);
+  if (npmRoot) directCandidates.push(path.join(npmRoot, 'openclaw'));
+
+  const nodePathEntries = (process.env.NODE_PATH || '')
+    .split(path.delimiter)
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+  for (const entry of nodePathEntries) {
+    directCandidates.push(path.join(entry, 'openclaw'));
+  }
+
+  const openclawBin = tryExec('which', ['openclaw']);
+  if (openclawBin) {
+    directCandidates.push(openclawBin);
+    directCandidates.push(path.dirname(openclawBin));
+  }
+
+  const packageRoots = unique(
+    directCandidates
+      .map((candidate) => findOpenClawPackageRoot(candidate))
+      .filter(Boolean),
+  );
+
+  return packageRoots.filter((candidate) => {
+    const pkgJson = path.join(candidate, 'package.json');
+    return fs.existsSync(pkgJson) && readOpenClawPackageName(pkgJson) === 'openclaw';
+  });
+};
+
+const canResolveSdkCore = () => {
+  try {
+    pluginRequire.resolve(sdkCoreSpecifier);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+const ensurePluginNodeModulesLink = (targetRoot: string) => {
+  const nodeModulesDir = path.join(pluginDir, 'node_modules');
+  const linkPath = path.join(nodeModulesDir, 'openclaw');
+  fs.mkdirSync(nodeModulesDir, { recursive: true });
+
+  try {
+    const stat = fs.lstatSync(linkPath);
+    if (stat.isSymbolicLink()) {
+      const existingTarget = fs.realpathSync(linkPath);
+      const normalizedExisting = path.normalize(existingTarget);
+      const normalizedTarget = path.normalize(fs.realpathSync(targetRoot));
+      if (normalizedExisting === normalizedTarget) return;
+      fs.unlinkSync(linkPath);
+    } else {
+      return;
+    }
+  } catch {
+    // missing link is fine
+  }
+
+  fs.symlinkSync(targetRoot, linkPath, linkType as fs.symlink.Type);
+};
+
+const ensureOpenClawSdkResolution = () => {
+  if (canResolveSdkCore()) return;
+
+  let lastError = '';
+  const candidates = collectOpenClawCandidates();
+  for (const candidate of candidates) {
+    try {
+      ensurePluginNodeModulesLink(candidate);
+      if (canResolveSdkCore()) return;
+    } catch (error) {
+      lastError = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+    }
+  }
+
+  const suffix = candidates.length
+    ? ` Tried candidates: ${candidates.join(', ')}.`
+    : ' No openclaw package root candidates were found from npm root, NODE_PATH, common global paths, or the openclaw binary path.';
+  const extra = lastError ? ` Last repair error: ${lastError}.` : '';
+  throw new Error(
+    `bncr failed to resolve ${sdkCoreSpecifier} from ${pluginDir}.${suffix}${extra} ` +
+      `You can repair manually with: mkdir -p ${path.join(pluginDir, 'node_modules')} && ln -s "$(npm root -g)/openclaw" ${path.join(pluginDir, 'node_modules', 'openclaw')}`,
+  );
+};
+
+const loadRuntimeSync = (): LoadedRuntime => {
+  if (runtime) return runtime;
+  ensureOpenClawSdkResolution();
+  try {
+    const mod = pluginRequire('./src/channel.ts') as ChannelModule;
+    runtime = {
+      createBncrBridge: mod.createBncrBridge,
+      createBncrChannelPlugin: mod.createBncrChannelPlugin,
+    };
+    return runtime;
+  } catch (error) {
+    const detail = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+    throw new Error(`bncr failed to load channel runtime after dependency bootstrap: ${detail}`);
+  }
+};
+
+const getIdentityId = (obj: object, prefix: string) => {
+  const existing = identityIds.get(obj);
+  if (existing) return existing;
+  const next = `${prefix}_${++identitySeq}`;
+  identityIds.set(obj, next);
+  return next;
+};
+
+const getRegistryFingerprint = (api: OpenClawPluginApi) => {
+  const serviceId = getIdentityId(api.registerService as object, 'svc');
+  const channelId = getIdentityId(api.registerChannel as object, 'chn');
+  const methodId = getIdentityId(api.registerGatewayMethod as object, 'mth');
+  return `${serviceId}:${channelId}:${methodId}`;
+};
+
+const getRegisterMeta = (api: OpenClawPluginApi): RegisterMeta => {
+  const host = api as OpenClawPluginApiWithMeta;
+  if (!host[BNCR_REGISTER_META]) {
+    host[BNCR_REGISTER_META] = { methods: new Set<string>() };
+  }
+  if (!host[BNCR_REGISTER_META]!.methods) {
+    host[BNCR_REGISTER_META]!.methods = new Set<string>();
+  }
+  if (!host[BNCR_REGISTER_META]!.apiInstanceId) {
+    host[BNCR_REGISTER_META]!.apiInstanceId = getIdentityId(api as object, 'api');
+  }
+  if (!host[BNCR_REGISTER_META]!.registryFingerprint) {
+    host[BNCR_REGISTER_META]!.registryFingerprint = getRegistryFingerprint(api);
+  }
+  return host[BNCR_REGISTER_META]!;
+};
+
+const ensureGatewayMethodRegistered = (
+  api: OpenClawPluginApi,
+  name: string,
+  handler: (opts: any) => any,
+  debugLog: (...args: any[]) => void,
+) => {
+  const meta = getRegisterMeta(api);
+  if (meta.methods?.has(name)) {
+    debugLog(`bncr register method skip ${name} (already registered on this api)`);
+    return;
+  }
+  api.registerGatewayMethod(name, handler);
+  meta.methods?.add(name);
+  debugLog(`bncr register method ok ${name}`);
+};
 
 const getBridgeSingleton = (api: OpenClawPluginApi) => {
+  const loaded = loadRuntimeSync();
   const g = globalThis as typeof globalThis & { __bncrBridge?: BridgeSingleton };
-  if (!g.__bncrBridge) g.__bncrBridge = createBncrBridge(api);
-  return g.__bncrBridge;
+  let created = false;
+  if (!g.__bncrBridge) {
+    g.__bncrBridge = loaded.createBncrBridge(api);
+    created = true;
+  } else {
+    g.__bncrBridge.bindApi?.(api);
+  }
+  return { bridge: g.__bncrBridge, runtime: loaded, created };
 };
 
 const plugin = {
-  id: "bncr",
-  name: "Bncr",
-  description: "Bncr channel plugin",
+  id: 'bncr',
+  name: 'Bncr',
+  description: 'Bncr channel plugin',
   configSchema: BncrConfigSchema,
   register(api: OpenClawPluginApi) {
-    const bridge = getBridgeSingleton(api);
+    const meta = getRegisterMeta(api);
+    const { bridge, runtime, created } = getBridgeSingleton(api);
+    bridge.noteRegister?.({
+      source: '~/.openclaw/workspace/plugins/bncr/index.ts',
+      pluginVersion: '0.1.1',
+      apiRebound: !created,
+      apiInstanceId: meta.apiInstanceId,
+      registryFingerprint: meta.registryFingerprint,
+    });
     const debugLog = (...args: any[]) => {
       if (!bridge.isDebugEnabled?.()) return;
       api.logger.info?.(...args);
     };
 
-    debugLog(`bncr plugin register bridge=${(bridge as any)?.bridgeId || 'unknown'}`);
+    debugLog(`bncr plugin register begin bridge=${bridge.getBridgeId?.() || 'unknown'} created=${created}`);
+    if (!created) debugLog('bncr bridge api rebound');
 
     const resolveDebug = async () => {
       try {
@@ -36,57 +297,40 @@ const plugin = {
       }
     };
 
-    api.registerService({
-      id: "bncr-bridge-service",
-      start: async (ctx) => {
-        const debug = await resolveDebug();
-        await bridge.startService(ctx, debug);
-      },
-      stop: bridge.stopService,
-    });
+    if (!meta.service) {
+      api.registerService({
+        id: 'bncr-bridge-service',
+        start: async (ctx) => {
+          const debug = await resolveDebug();
+          await bridge.startService(ctx, debug);
+        },
+        stop: bridge.stopService,
+      });
+      meta.service = true;
+      debugLog('bncr register service ok');
+    } else {
+      debugLog('bncr register service skip (already registered on this api)');
+    }
+
+    if (!meta.channel) {
+      api.registerChannel({ plugin: runtime.createBncrChannelPlugin(bridge) });
+      meta.channel = true;
+      debugLog('bncr register channel ok');
+    } else {
+      debugLog('bncr register channel skip (already registered on this api)');
+    }
 
-    api.registerChannel({ plugin: createBncrChannelPlugin(bridge) });
-
-    api.registerGatewayMethod(
-      "bncr.connect",
-      (opts: GatewayRequestHandlerOptions) => bridge.handleConnect(opts),
-    );
-    api.registerGatewayMethod(
-      "bncr.inbound",
-      (opts: GatewayRequestHandlerOptions) => bridge.handleInbound(opts),
-    );
-    api.registerGatewayMethod(
-      "bncr.activity",
-      (opts: GatewayRequestHandlerOptions) => bridge.handleActivity(opts),
-    );
-    api.registerGatewayMethod(
-      "bncr.ack",
-      (opts: GatewayRequestHandlerOptions) => bridge.handleAck(opts),
-    );
-    api.registerGatewayMethod(
-      "bncr.diagnostics",
-      (opts: GatewayRequestHandlerOptions) => bridge.handleDiagnostics(opts),
-    );
-    api.registerGatewayMethod(
-      "bncr.file.init",
-      (opts: GatewayRequestHandlerOptions) => bridge.handleFileInit(opts),
-    );
-    api.registerGatewayMethod(
-      "bncr.file.chunk",
-      (opts: GatewayRequestHandlerOptions) => bridge.handleFileChunk(opts),
-    );
-    api.registerGatewayMethod(
-      "bncr.file.complete",
-      (opts: GatewayRequestHandlerOptions) => bridge.handleFileComplete(opts),
-    );
-    api.registerGatewayMethod(
-      "bncr.file.abort",
-      (opts: GatewayRequestHandlerOptions) => bridge.handleFileAbort(opts),
-    );
-    api.registerGatewayMethod(
-      "bncr.file.ack",
-      (opts: GatewayRequestHandlerOptions) => bridge.handleFileAck(opts),
-    );
+    ensureGatewayMethodRegistered(api, 'bncr.connect', (opts) => bridge.handleConnect(opts), debugLog);
+    ensureGatewayMethodRegistered(api, 'bncr.inbound', (opts) => bridge.handleInbound(opts), debugLog);
+    ensureGatewayMethodRegistered(api, 'bncr.activity', (opts) => bridge.handleActivity(opts), debugLog);
+    ensureGatewayMethodRegistered(api, 'bncr.ack', (opts) => bridge.handleAck(opts), debugLog);
+    ensureGatewayMethodRegistered(api, 'bncr.diagnostics', (opts) => bridge.handleDiagnostics(opts), debugLog);
+    ensureGatewayMethodRegistered(api, 'bncr.file.init', (opts) => bridge.handleFileInit(opts), debugLog);
+    ensureGatewayMethodRegistered(api, 'bncr.file.chunk', (opts) => bridge.handleFileChunk(opts), debugLog);
+    ensureGatewayMethodRegistered(api, 'bncr.file.complete', (opts) => bridge.handleFileComplete(opts), debugLog);
+    ensureGatewayMethodRegistered(api, 'bncr.file.abort', (opts) => bridge.handleFileAbort(opts), debugLog);
+    ensureGatewayMethodRegistered(api, 'bncr.file.ack', (opts) => bridge.handleFileAck(opts), debugLog);
+    debugLog('bncr plugin register done');
   },
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmoxmo/bncr",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "private": false,
   "type": "module",
   "license": "MIT",
@@ -25,7 +25,8 @@
   ],
   "scripts": {
     "selfcheck": "node ./scripts/selfcheck.mjs",
-    "test": "node --import ./tests/register-ts-hooks.mjs --test ./tests/*.test.mjs"
+    "test": "node --import ./tests/register-ts-hooks.mjs --test ./tests/*.test.mjs",
+    "check-register-drift": "node ./scripts/check-register-drift.mjs"
   },
   "peerDependencies": {
     "openclaw": ">=2026.3.22"

package/scripts/check-register-drift.mjs

@@ -0,0 +1,105 @@
+import { execFileSync } from 'node:child_process';
+
+const readNumber = (value, fallback) => {
+  const n = Number(value);
+  return Number.isFinite(n) ? n : fallback;
+};
+
+const args = process.argv.slice(2);
+const options = {
+  durationSec: 300,
+  intervalSec: 15,
+  accountId: 'Primary',
+  gatewayBin: 'openclaw',
+};
+
+for (let i = 0; i < args.length; i += 1) {
+  const arg = args[i];
+  if (arg === '--duration-sec') options.durationSec = readNumber(args[++i], options.durationSec);
+  else if (arg === '--interval-sec') options.intervalSec = readNumber(args[++i], options.intervalSec);
+  else if (arg === '--account-id') options.accountId = args[++i] || options.accountId;
+  else if (arg === '--gateway-bin') options.gatewayBin = args[++i] || options.gatewayBin;
+  else if (arg === '--help' || arg === '-h') {
+    console.log(`Usage: node ./scripts/check-register-drift.mjs [--duration-sec 300] [--interval-sec 15] [--account-id Primary] [--gateway-bin openclaw]\n\nSamples bncr.diagnostics over time and reports whether register counters drift after warmup.`);
+    process.exit(0);
+  }
+}
+
+if (options.durationSec <= 0) throw new Error('durationSec must be > 0');
+if (options.intervalSec <= 0) throw new Error('intervalSec must be > 0');
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+const fetchDiagnostics = () => {
+  const raw = execFileSync(
+    options.gatewayBin,
+    ['gateway', 'call', 'bncr.diagnostics', '--json', '--params', JSON.stringify({ accountId: options.accountId })],
+    { encoding: 'utf8' },
+  );
+  const parsed = JSON.parse(raw);
+  const reg = parsed?.diagnostics?.register || {};
+  const summary = reg?.traceSummary || {};
+  return {
+    now: parsed?.now ?? Date.now(),
+    registerCount: reg?.registerCount ?? null,
+    apiGeneration: reg?.apiGeneration ?? null,
+    apiInstanceId: reg?.apiInstanceId ?? null,
+    registryFingerprint: reg?.registryFingerprint ?? null,
+    warmupRegisterCount: summary?.warmupRegisterCount ?? null,
+    postWarmupRegisterCount: summary?.postWarmupRegisterCount ?? null,
+    unexpectedRegisterAfterWarmup: summary?.unexpectedRegisterAfterWarmup ?? null,
+    lastUnexpectedRegisterAt: summary?.lastUnexpectedRegisterAt ?? null,
+    sourceBuckets: summary?.sourceBuckets ?? null,
+  };
+};
+
+const startedAt = Date.now();
+const samples = [];
+const deadline = startedAt + options.durationSec * 1000;
+
+while (true) {
+  const sample = fetchDiagnostics();
+  samples.push(sample);
+  const nextAt = Date.now() + options.intervalSec * 1000;
+  if (nextAt > deadline) break;
+  await sleep(Math.max(0, nextAt - Date.now()));
+}
+
+const first = samples[0] || {};
+const last = samples[samples.length - 1] || {};
+const deltaRegisterCount = (last.registerCount ?? 0) - (first.registerCount ?? 0);
+const deltaApiGeneration = (last.apiGeneration ?? 0) - (first.apiGeneration ?? 0);
+const deltaPostWarmupRegisterCount = (last.postWarmupRegisterCount ?? 0) - (first.postWarmupRegisterCount ?? 0);
+const historicalWarmupExternalDrift = Boolean(first.unexpectedRegisterAfterWarmup);
+const newWarmupExternalDriftDuringWindow = deltaPostWarmupRegisterCount > 0;
+const newDriftDuringWindow = deltaRegisterCount > 0 || deltaApiGeneration > 0 || newWarmupExternalDriftDuringWindow;
+const driftDetected = historicalWarmupExternalDrift || newDriftDuringWindow;
+
+const result = {
+  ok: true,
+  accountId: options.accountId,
+  durationSec: options.durationSec,
+  intervalSec: options.intervalSec,
+  startedAt,
+  endedAt: Date.now(),
+  sampleCount: samples.length,
+  first,
+  last,
+  delta: {
+    registerCount: deltaRegisterCount,
+    apiGeneration: deltaApiGeneration,
+    postWarmupRegisterCount: deltaPostWarmupRegisterCount,
+  },
+  historicalWarmupExternalDrift,
+  newWarmupExternalDriftDuringWindow,
+  newDriftDuringWindow,
+  driftDetected,
+  conclusion: newDriftDuringWindow
+    ? 'new register drift was observed during this sampling window'
+    : historicalWarmupExternalDrift
+      ? 'no new drift during this window, but warmup-external drift had already happened before sampling began'
+      : 'register counters stayed stable during this window and no warmup-external drift was flagged',
+  samples,
+};
+
+console.log(JSON.stringify(result, null, 2));

package/src/channel.ts

@@ -63,6 +63,7 @@ const FILE_CHUNK_RETRY = 3;
 const FILE_ACK_TIMEOUT_MS = 30_000;
 const FILE_TRANSFER_ACK_TTL_MS = 30_000;
 const FILE_TRANSFER_KEEP_MS = 6 * 60 * 60 * 1000;
+const REGISTER_WARMUP_WINDOW_MS = 30_000;
 let BNCR_DEBUG_VERBOSE = false; // 全局调试日志开关（默认关闭）
 
 type FileSendTransferState = {
@@ -130,6 +131,18 @@ type PersistedState = {
     accountId: string;
     updatedAt: number;
   }>;
+  lastDriftSnapshot?: {
+    capturedAt: number;
+    registerCount: number | null;
+    apiGeneration: number | null;
+    postWarmupRegisterCount: number | null;
+    apiInstanceId: string | null;
+    registryFingerprint: string | null;
+    dominantBucket: string | null;
+    sourceBuckets: Record<string, number>;
+    traceWindowSize: number;
+    traceRecent: Array<Record<string, unknown>>;
+  } | null;
 };
 
 function now() {
@@ -205,6 +218,56 @@ class BncrBridgeRuntime {
   private api: OpenClawPluginApi;
   private statePath: string | null = null;
   private bridgeId = `${process.pid}-${Math.random().toString(16).slice(2, 8)}`;
+  private gatewayPid = process.pid;
+  private registerCount = 0;
+  private apiGeneration = 0;
+  private firstRegisterAt: number | null = null;
+  private lastRegisterAt: number | null = null;
+  private lastApiRebindAt: number | null = null;
+  private pluginSource: string | null = null;
+  private pluginVersion: string | null = null;
+  private connectionEpoch = 0;
+  private primaryLeaseId: string | null = null;
+  private acceptedConnections = 0;
+  private lastConnectAt: number | null = null;
+  private lastDisconnectAt: number | null = null;
+  private lastInboundAtGlobal: number | null = null;
+  private lastActivityAtGlobal: number | null = null;
+  private lastAckAtGlobal: number | null = null;
+  private recentConnections = new Map<string, {
+    epoch: number;
+    connectedAt: number;
+    lastActivityAt: number | null;
+    isPrimary: boolean;
+  }>();
+  private staleCounters = {
+    staleConnect: 0,
+    staleInbound: 0,
+    staleActivity: 0,
+    staleAck: 0,
+    staleFileInit: 0,
+    staleFileChunk: 0,
+    staleFileComplete: 0,
+    staleFileAbort: 0,
+    lastStaleAt: null as number | null,
+  };
+  private lastApiInstanceId: string | null = null;
+  private lastRegistryFingerprint: string | null = null;
+  private lastDriftSnapshot: PersistedState['lastDriftSnapshot'] = null;
+  private registerTraceRecent: Array<{
+    ts: number;
+    bridgeId: string;
+    gatewayPid: number;
+    registerCount: number;
+    apiGeneration: number;
+    apiRebound: boolean;
+    apiInstanceId: string | null;
+    registryFingerprint: string | null;
+    source: string | null;
+    pluginVersion: string | null;
+    stack: string;
+    stackBucket: string;
+  }> = [];
 
   private connections = new Map<string, BncrConnection>(); // connectionKey -> connection
   private activeConnectionByAccount = new Map<string, string>(); // accountId -> connectionKey
@@ -246,6 +309,266 @@ class BncrBridgeRuntime {
     this.api = api;
   }
 
+  bindApi(api: OpenClawPluginApi) {
+    this.api = api;
+  }
+
+  getBridgeId() {
+    return this.bridgeId;
+  }
+
+  private classifyRegisterTrace(stack: string) {
+    if (stack.includes('prepareSecretsRuntimeSnapshot') || stack.includes('resolveRuntimeWebTools') || stack.includes('resolvePluginWebSearchProviders')) {
+      return 'runtime/webtools';
+    }
+    if (stack.includes('startGatewayServer') || stack.includes('loadGatewayPlugins')) {
+      return 'gateway/startup';
+    }
+    if (stack.includes('resolvePluginImplicitProviders')) {
+      return 'provider/discovery/implicit';
+    }
+    if (stack.includes('resolvePluginDiscoveryProviders')) {
+      return 'provider/discovery/discovery';
+    }
+    if (stack.includes('resolvePluginProviders')) {
+      return 'provider/discovery/providers';
+    }
+    return 'other';
+  }
+
+  private dominantRegisterBucket(sourceBuckets: Record<string, number>) {
+    let winner: string | null = null;
+    let winnerCount = -1;
+    for (const [bucket, count] of Object.entries(sourceBuckets)) {
+      if (count > winnerCount) {
+        winner = bucket;
+        winnerCount = count;
+      }
+    }
+    return winner;
+  }
+
+  private captureDriftSnapshot(summary: ReturnType<BncrBridgeRuntime['buildRegisterTraceSummary']>) {
+    this.lastDriftSnapshot = {
+      capturedAt: now(),
+      registerCount: this.registerCount,
+      apiGeneration: this.apiGeneration,
+      postWarmupRegisterCount: summary.postWarmupRegisterCount,
+      apiInstanceId: this.lastApiInstanceId,
+      registryFingerprint: this.lastRegistryFingerprint,
+      dominantBucket: summary.dominantBucket,
+      sourceBuckets: { ...summary.sourceBuckets },
+      traceWindowSize: this.registerTraceRecent.length,
+      traceRecent: this.registerTraceRecent.map((trace) => ({ ...trace })),
+    };
+    this.scheduleSave();
+  }
+
+  private buildRegisterTraceSummary() {
+    const buckets: Record<string, number> = {};
+    let warmupCount = 0;
+    let postWarmupCount = 0;
+    let unexpectedRegisterAfterWarmup = false;
+    let lastUnexpectedRegisterAt: number | null = null;
+    const baseline = this.firstRegisterAt;
+
+    for (const trace of this.registerTraceRecent) {
+      buckets[trace.stackBucket] = (buckets[trace.stackBucket] || 0) + 1;
+      const isWarmup = baseline != null && (trace.ts - baseline) <= REGISTER_WARMUP_WINDOW_MS;
+      if (isWarmup) {
+        warmupCount += 1;
+      } else {
+        postWarmupCount += 1;
+        unexpectedRegisterAfterWarmup = true;
+        lastUnexpectedRegisterAt = trace.ts;
+      }
+    }
+
+    const dominantBucket = this.dominantRegisterBucket(buckets);
+    const likelyRuntimeRegistryDrift = postWarmupCount > 0;
+    const likelyStartupFanoutOnly = warmupCount > 0 && postWarmupCount === 0;
+
+    return {
+      startupWindowMs: REGISTER_WARMUP_WINDOW_MS,
+      traceWindowSize: this.registerTraceRecent.length,
+      sourceBuckets: buckets,
+      dominantBucket,
+      warmupRegisterCount: warmupCount,
+      postWarmupRegisterCount: postWarmupCount,
+      unexpectedRegisterAfterWarmup,
+      lastUnexpectedRegisterAt,
+      likelyRuntimeRegistryDrift,
+      likelyStartupFanoutOnly,
+    };
+  }
+
+  noteRegister(meta: {
+    source?: string;
+    pluginVersion?: string;
+    apiRebound?: boolean;
+    apiInstanceId?: string;
+    registryFingerprint?: string;
+  }) {
+    const ts = now();
+    this.registerCount += 1;
+    if (this.firstRegisterAt == null) this.firstRegisterAt = ts;
+    this.lastRegisterAt = ts;
+    if (meta.apiRebound) {
+      this.apiGeneration += 1;
+      this.lastApiRebindAt = ts;
+    } else if (this.registerCount === 1 && this.apiGeneration === 0) {
+      this.apiGeneration = 1;
+    }
+    if (meta.source) this.pluginSource = meta.source;
+    if (meta.pluginVersion) this.pluginVersion = meta.pluginVersion;
+    if (meta.apiInstanceId) this.lastApiInstanceId = meta.apiInstanceId;
+    if (meta.registryFingerprint) this.lastRegistryFingerprint = meta.registryFingerprint;
+
+    const stack = String(new Error().stack || '')
+      .split('\n')
+      .slice(2, 7)
+      .map((line) => line.trim())
+      .filter(Boolean)
+      .join(' <- ');
+    const stackBucket = this.classifyRegisterTrace(stack);
+
+    const trace = {
+      ts,
+      bridgeId: this.bridgeId,
+      gatewayPid: this.gatewayPid,
+      registerCount: this.registerCount,
+      apiGeneration: this.apiGeneration,
+      apiRebound: meta.apiRebound === true,
+      apiInstanceId: this.lastApiInstanceId,
+      registryFingerprint: this.lastRegistryFingerprint,
+      source: this.pluginSource,
+      pluginVersion: this.pluginVersion,
+      stack,
+      stackBucket,
+    };
+    this.registerTraceRecent.push(trace);
+    if (this.registerTraceRecent.length > 12) this.registerTraceRecent.splice(0, this.registerTraceRecent.length - 12);
+
+    const summary = this.buildRegisterTraceSummary();
+    if (summary.postWarmupRegisterCount > 0) this.captureDriftSnapshot(summary);
+
+    this.api.logger.info?.(
+      `[bncr-register-trace] ${JSON.stringify(trace)}`,
+    );
+  }
+
+  private createLeaseId() {
+    return typeof crypto?.randomUUID === 'function'
+      ? `lease_${crypto.randomUUID()}`
+      : `lease_${Math.random().toString(16).slice(2)}${Date.now().toString(16)}`;
+  }
+
+  private acceptConnection() {
+    const ts = now();
+    const leaseId = this.createLeaseId();
+    const connectionEpoch = ++this.connectionEpoch;
+    this.primaryLeaseId = leaseId;
+    this.acceptedConnections += 1;
+    this.lastConnectAt = ts;
+    this.recentConnections.set(leaseId, {
+      epoch: connectionEpoch,
+      connectedAt: ts,
+      lastActivityAt: null,
+      isPrimary: true,
+    });
+    for (const [id, entry] of this.recentConnections.entries()) {
+      if (id !== leaseId) entry.isPrimary = false;
+    }
+    while (this.recentConnections.size > 8) {
+      const oldest = this.recentConnections.keys().next().value;
+      if (!oldest) break;
+      this.recentConnections.delete(oldest);
+    }
+    return { leaseId, connectionEpoch, acceptedAt: ts };
+  }
+
+  private observeLease(
+    kind: 'connect' | 'inbound' | 'activity' | 'ack' | 'file.init' | 'file.chunk' | 'file.complete' | 'file.abort',
+    params: { leaseId?: string; connectionEpoch?: number },
+  ) {
+    const leaseId = typeof params.leaseId === 'string' ? params.leaseId.trim() : '';
+    const connectionEpoch = typeof params.connectionEpoch === 'number' ? params.connectionEpoch : undefined;
+    if (!leaseId && connectionEpoch == null) return { stale: false, reason: 'missing' as const };
+    const staleByLease = !!leaseId && this.primaryLeaseId != null && leaseId !== this.primaryLeaseId;
+    const staleByEpoch = connectionEpoch != null && this.connectionEpoch > 0 && connectionEpoch !== this.connectionEpoch;
+    const stale = staleByLease || staleByEpoch;
+    if (!stale) return { stale: false, reason: 'ok' as const };
+    this.staleCounters.lastStaleAt = now();
+    switch (kind) {
+      case 'connect': this.staleCounters.staleConnect += 1; break;
+      case 'inbound': this.staleCounters.staleInbound += 1; break;
+      case 'activity': this.staleCounters.staleActivity += 1; break;
+      case 'ack': this.staleCounters.staleAck += 1; break;
+      case 'file.init': this.staleCounters.staleFileInit += 1; break;
+      case 'file.chunk': this.staleCounters.staleFileChunk += 1; break;
+      case 'file.complete': this.staleCounters.staleFileComplete += 1; break;
+      case 'file.abort': this.staleCounters.staleFileAbort += 1; break;
+    }
+    this.api.logger.warn?.(
+      `[bncr] stale ${kind} observed lease=${leaseId || '-'} epoch=${connectionEpoch ?? '-'} currentLease=${this.primaryLeaseId || '-'} currentEpoch=${this.connectionEpoch}`,
+    );
+    return { stale: true, reason: 'mismatch' as const };
+  }
+
+  private buildExtendedDiagnostics(accountId: string) {
+    const diagnostics = this.buildIntegratedDiagnostics(accountId) as Record<string, any>;
+    return {
+      ...diagnostics,
+      register: {
+        bridgeId: this.bridgeId,
+        gatewayPid: this.gatewayPid,
+        pluginVersion: this.pluginVersion,
+        source: this.pluginSource,
+        apiInstanceId: this.lastApiInstanceId,
+        registryFingerprint: this.lastRegistryFingerprint,
+        registerCount: this.registerCount,
+        firstRegisterAt: this.firstRegisterAt,
+        lastRegisterAt: this.lastRegisterAt,
+        lastApiRebindAt: this.lastApiRebindAt,
+        apiGeneration: this.apiGeneration,
+        traceRecent: this.registerTraceRecent.slice(),
+        traceSummary: this.buildRegisterTraceSummary(),
+        lastDriftSnapshot: this.lastDriftSnapshot,
+      },
+      connection: {
+        active: this.activeConnectionCount(accountId),
+        primaryLeaseId: this.primaryLeaseId,
+        primaryEpoch: this.connectionEpoch || null,
+        acceptedConnections: this.acceptedConnections,
+        lastConnectAt: this.lastConnectAt,
+        lastDisconnectAt: this.lastDisconnectAt,
+        lastActivityAt: this.lastActivityAtGlobal,
+        lastInboundAt: this.lastInboundAtGlobal,
+        lastAckAt: this.lastAckAtGlobal,
+        recent: Array.from(this.recentConnections.entries()).map(([leaseId, entry]) => ({
+          leaseId,
+          epoch: entry.epoch,
+          connectedAt: entry.connectedAt,
+          lastActivityAt: entry.lastActivityAt,
+          isPrimary: entry.isPrimary,
+        })),
+      },
+      protocol: {
+        bridgeVersion: BRIDGE_VERSION,
+        protocolVersion: 2,
+        minClientProtocol: 1,
+        features: {
+          leaseId: true,
+          connectionEpoch: true,
+          staleObserveOnly: true,
+          staleRejectAck: false,
+          staleRejectFile: false,
+        },
+      },
+      stale: { ...this.staleCounters },
+    };
+  }
+
   isDebugEnabled(): boolean {
     try {
       const cfg = (this.api.runtime.config?.get?.() as any) || {};
@@ -500,6 +823,25 @@ class BncrBridgeRuntime {
       this.lastOutboundByAccount.set(accountId, updatedAt);
     }
 
+    this.lastDriftSnapshot = data.lastDriftSnapshot && typeof data.lastDriftSnapshot === 'object'
+      ? {
+          capturedAt: Number((data.lastDriftSnapshot as any).capturedAt || 0),
+          registerCount: Number.isFinite(Number((data.lastDriftSnapshot as any).registerCount)) ? Number((data.lastDriftSnapshot as any).registerCount) : null,
+          apiGeneration: Number.isFinite(Number((data.lastDriftSnapshot as any).apiGeneration)) ? Number((data.lastDriftSnapshot as any).apiGeneration) : null,
+          postWarmupRegisterCount: Number.isFinite(Number((data.lastDriftSnapshot as any).postWarmupRegisterCount)) ? Number((data.lastDriftSnapshot as any).postWarmupRegisterCount) : null,
+          apiInstanceId: asString((data.lastDriftSnapshot as any).apiInstanceId || '').trim() || null,
+          registryFingerprint: asString((data.lastDriftSnapshot as any).registryFingerprint || '').trim() || null,
+          dominantBucket: asString((data.lastDriftSnapshot as any).dominantBucket || '').trim() || null,
+          sourceBuckets: ((data.lastDriftSnapshot as any).sourceBuckets && typeof (data.lastDriftSnapshot as any).sourceBuckets === 'object')
+            ? { ...((data.lastDriftSnapshot as any).sourceBuckets as Record<string, number>) }
+            : {},
+          traceWindowSize: Number((data.lastDriftSnapshot as any).traceWindowSize || 0),
+          traceRecent: Array.isArray((data.lastDriftSnapshot as any).traceRecent)
+            ? [ ...((data.lastDriftSnapshot as any).traceRecent as Array<Record<string, unknown>>) ]
+            : [],
+        }
+      : null;
+
     // 兼容旧状态文件：若尚未持久化 lastSession*/lastActivity*，从 sessionRoutes 回填。
     if (this.lastSessionByAccount.size === 0 && this.sessionRoutes.size > 0) {
       for (const [sessionKey, info] of this.sessionRoutes.entries()) {
@@ -560,6 +902,20 @@ class BncrBridgeRuntime {
         accountId,
         updatedAt,
       })),
+      lastDriftSnapshot: this.lastDriftSnapshot
+        ? {
+            capturedAt: this.lastDriftSnapshot.capturedAt,
+            registerCount: this.lastDriftSnapshot.registerCount,
+            apiGeneration: this.lastDriftSnapshot.apiGeneration,
+            postWarmupRegisterCount: this.lastDriftSnapshot.postWarmupRegisterCount,
+            apiInstanceId: this.lastDriftSnapshot.apiInstanceId,
+            registryFingerprint: this.lastDriftSnapshot.registryFingerprint,
+            dominantBucket: this.lastDriftSnapshot.dominantBucket,
+            sourceBuckets: { ...this.lastDriftSnapshot.sourceBuckets },
+            traceWindowSize: this.lastDriftSnapshot.traceWindowSize,
+            traceRecent: this.lastDriftSnapshot.traceRecent.map((trace) => ({ ...trace })),
+          }
+        : null,
     };
 
     await writeJsonFileAtomically(this.statePath, data);
@@ -1718,6 +2074,7 @@ class BncrBridgeRuntime {
     this.markSeen(accountId, connId, clientId);
     this.markActivity(accountId);
     this.incrementCounter(this.connectEventsByAccount, accountId);
+    const lease = this.acceptConnection();
 
     respond(true, {
       channel: CHANNEL_ID,
@@ -1729,7 +2086,13 @@ class BncrBridgeRuntime {
       activeConnections: this.activeConnectionCount(accountId),
       pending: Array.from(this.outbox.values()).filter((v) => v.accountId === accountId).length,
       deadLetter: this.deadLetter.filter((v) => v.accountId === accountId).length,
-      diagnostics: this.buildIntegratedDiagnostics(accountId),
+      diagnostics: this.buildExtendedDiagnostics(accountId),
+      leaseId: lease.leaseId,
+      connectionEpoch: lease.connectionEpoch,
+      protocolVersion: 2,
+      acceptedAt: lease.acceptedAt,
+      serverPid: this.gatewayPid,
+      bridgeId: this.bridgeId,
       now: now(),
     });
 
@@ -1743,6 +2106,8 @@ class BncrBridgeRuntime {
     const clientId = asString((params as any)?.clientId || '').trim() || undefined;
     this.rememberGatewayContext(context);
     this.markSeen(accountId, connId, clientId);
+    this.observeLease('ack', params ?? {});
+    this.lastAckAtGlobal = now();
     this.incrementCounter(this.ackEventsByAccount, accountId);
 
     const messageId = asString(params?.messageId || '').trim();
@@ -1802,6 +2167,8 @@ class BncrBridgeRuntime {
     const accountId = normalizeAccountId(asString(params?.accountId || ''));
     const connId = asString(client?.connId || '').trim() || `no-conn-${Date.now()}`;
     const clientId = asString((params as any)?.clientId || '').trim() || undefined;
+    this.observeLease('activity', params ?? {});
+    this.lastActivityAtGlobal = now();
     if (BNCR_DEBUG_VERBOSE) {
       this.api.logger.info?.(
         `[bncr-activity] ${JSON.stringify({
@@ -1834,7 +2201,7 @@ class BncrBridgeRuntime {
     const accountId = normalizeAccountId(asString(params?.accountId || ''));
     const cfg = await this.api.runtime.config.loadConfig();
     const runtime = this.getAccountRuntimeSnapshot(accountId);
-    const diagnostics = this.buildIntegratedDiagnostics(accountId);
+    const diagnostics = this.buildExtendedDiagnostics(accountId);
     const permissions = buildBncrPermissionSummary(cfg ?? {});
     const probe = probeBncrAccount({
       accountId,
@@ -1869,6 +2236,7 @@ class BncrBridgeRuntime {
     const clientId = asString((params as any)?.clientId || '').trim() || undefined;
     this.rememberGatewayContext(context);
     this.markSeen(accountId, connId, clientId);
+    this.observeLease('file.init', params ?? {});
     this.markActivity(accountId);
 
     const transferId = asString(params?.transferId || '').trim();
@@ -1938,6 +2306,7 @@ class BncrBridgeRuntime {
     const clientId = asString((params as any)?.clientId || '').trim() || undefined;
     this.rememberGatewayContext(context);
     this.markSeen(accountId, connId, clientId);
+    this.observeLease('file.chunk', params ?? {});
     this.markActivity(accountId);
 
     const transferId = asString(params?.transferId || '').trim();
@@ -1991,6 +2360,7 @@ class BncrBridgeRuntime {
     const clientId = asString((params as any)?.clientId || '').trim() || undefined;
     this.rememberGatewayContext(context);
     this.markSeen(accountId, connId, clientId);
+    this.observeLease('file.complete', params ?? {});
     this.markActivity(accountId);
 
     const transferId = asString(params?.transferId || '').trim();
@@ -2054,6 +2424,7 @@ class BncrBridgeRuntime {
     const clientId = asString((params as any)?.clientId || '').trim() || undefined;
     this.rememberGatewayContext(context);
     this.markSeen(accountId, connId, clientId);
+    this.observeLease('file.abort', params ?? {});
     this.markActivity(accountId);
 
     const transferId = asString(params?.transferId || '').trim();
@@ -2149,7 +2520,9 @@ class BncrBridgeRuntime {
     const clientId = asString((params as any)?.clientId || '').trim() || undefined;
     this.rememberGatewayContext(context);
     this.markSeen(accountId, connId, clientId);
+    this.observeLease('inbound', params ?? {});
     this.markActivity(accountId);
+    this.lastInboundAtGlobal = now();
     this.incrementCounter(this.inboundEventsByAccount, accountId);
 
     if (!platform || (!userId && !groupId)) {