@xmoxmo/bncr 0.1.1 → 0.1.2

package/README.md

@@ -187,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

@@ -20,7 +20,23 @@ type LoadedRuntime = {
   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 {
@@ -188,11 +204,65 @@ const loadRuntimeSync = (): LoadedRuntime => {
   }
 };
 
+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 = loaded.createBncrBridge(api);
-  return { bridge: g.__bncrBridge, runtime: loaded };
+  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 = {
@@ -201,13 +271,22 @@ const plugin = {
   description: 'Bncr channel plugin',
   configSchema: BncrConfigSchema,
   register(api: OpenClawPluginApi) {
-    const { bridge, runtime } = 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 {
@@ -218,27 +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: runtime.createBncrChannelPlugin(bridge) });
-
-    api.registerGatewayMethod('bncr.connect', (opts) => bridge.handleConnect(opts));
-    api.registerGatewayMethod('bncr.inbound', (opts) => bridge.handleInbound(opts));
-    api.registerGatewayMethod('bncr.activity', (opts) => bridge.handleActivity(opts));
-    api.registerGatewayMethod('bncr.ack', (opts) => bridge.handleAck(opts));
-    api.registerGatewayMethod('bncr.diagnostics', (opts) => bridge.handleDiagnostics(opts));
-    api.registerGatewayMethod('bncr.file.init', (opts) => bridge.handleFileInit(opts));
-    api.registerGatewayMethod('bncr.file.chunk', (opts) => bridge.handleFileChunk(opts));
-    api.registerGatewayMethod('bncr.file.complete', (opts) => bridge.handleFileComplete(opts));
-    api.registerGatewayMethod('bncr.file.abort', (opts) => bridge.handleFileAbort(opts));
-    api.registerGatewayMethod('bncr.file.ack', (opts) => 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.1",
+  "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)) {