@xmoxmo/bncr 0.1.1 → 0.1.3

package/src/channel.ts

@@ -1,56 +1,70 @@
+import { createHash, randomUUID } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
-import { createHash, randomUUID } from 'node:crypto';
+import { readBooleanParam } from 'openclaw/plugin-sdk/boolean-param';
 import type {
+  GatewayRequestHandlerOptions,
   OpenClawPluginApi,
   OpenClawPluginServiceContext,
-  GatewayRequestHandlerOptions,
 } from 'openclaw/plugin-sdk/core';
 import {
-  setAccountEnabledInConfigSection,
   applyAccountNameToChannelSection,
+  setAccountEnabledInConfigSection,
 } from 'openclaw/plugin-sdk/core';
-import type { ChatType, ChannelMessageActionAdapter } from 'openclaw/plugin-sdk/mattermost';
-import { createDefaultChannelRuntimeState } from 'openclaw/plugin-sdk/status-helpers';
-import { writeJsonFileAtomically, readJsonFileWithFallback } from 'openclaw/plugin-sdk/json-store';
+import { readJsonFileWithFallback, writeJsonFileAtomically } from 'openclaw/plugin-sdk/json-store';
+import type { ChannelMessageActionAdapter, ChatType } from 'openclaw/plugin-sdk/mattermost';
 import { readStringParam } from 'openclaw/plugin-sdk/param-readers';
-import { readBooleanParam } from 'openclaw/plugin-sdk/boolean-param';
-import { extractToolSend } from 'openclaw/plugin-sdk/tool-send';
+import { createDefaultChannelRuntimeState } from 'openclaw/plugin-sdk/status-helpers';
 import { jsonResult } from 'openclaw/plugin-sdk/telegram-core';
-import { CHANNEL_ID, BNCR_DEFAULT_ACCOUNT_ID, normalizeAccountId, resolveDefaultDisplayName, resolveAccount, listAccountIds } from './core/accounts.ts';
-import type { BncrRoute, BncrConnection, OutboxEntry } from './core/types.ts';
+import { extractToolSend } from 'openclaw/plugin-sdk/tool-send';
 import {
-  parseRouteFromScope,
-  parseRouteFromDisplayScope,
+  BNCR_DEFAULT_ACCOUNT_ID,
+  CHANNEL_ID,
+  listAccountIds,
+  normalizeAccountId,
+  resolveAccount,
+  resolveDefaultDisplayName,
+} from './core/accounts.ts';
+import { BncrConfigSchema } from './core/config-schema.ts';
+import { buildBncrPermissionSummary } from './core/permissions.ts';
+import { resolveBncrChannelPolicy } from './core/policy.ts';
+import { probeBncrAccount } from './core/probe.ts';
+import {
+  buildAccountRuntimeSnapshot,
+  buildIntegratedDiagnostics as buildIntegratedDiagnosticsFromRuntime,
+  buildStatusHeadlineFromRuntime,
+  buildStatusMetaFromRuntime,
+} from './core/status.ts';
+import {
+  buildCanonicalBncrSessionKey,
   formatDisplayScope,
   isLowerHex,
-  routeScopeToHex,
+  normalizeInboundSessionKey,
+  normalizeStoredSessionKey,
+  parseRouteFromDisplayScope,
   parseRouteFromHexScope,
+  parseRouteFromScope,
   parseRouteLike,
-  parseLegacySessionKeyToStrict,
-  normalizeStoredSessionKey,
   parseStrictBncrSessionKey,
-  normalizeInboundSessionKey,
-  withTaskSessionKey,
-  buildFallbackSessionKey,
   routeKey,
+  routeScopeToHex,
+  withTaskSessionKey,
 } from './core/targets.ts';
-import { parseBncrInboundParams } from './messaging/inbound/parse.ts';
+import type { BncrConnection, BncrRoute, OutboxEntry } from './core/types.ts';
 import { dispatchBncrInbound } from './messaging/inbound/dispatch.ts';
 import { checkBncrMessageGate } from './messaging/inbound/gate.ts';
-import { sendBncrText, sendBncrMedia } from './messaging/outbound/send.ts';
-import { buildBncrMediaOutboundFrame, resolveBncrOutboundMessageType } from './messaging/outbound/media.ts';
-import { sendBncrReplyAction, deleteBncrMessageAction, reactBncrMessageAction, editBncrMessageAction } from './messaging/outbound/actions.ts';
+import { parseBncrInboundParams } from './messaging/inbound/parse.ts';
 import {
-  buildIntegratedDiagnostics as buildIntegratedDiagnosticsFromRuntime,
-  buildStatusHeadlineFromRuntime,
-  buildStatusMetaFromRuntime,
-  buildAccountRuntimeSnapshot,
-} from './core/status.ts';
-import { probeBncrAccount } from './core/probe.ts';
-import { BncrConfigSchema } from './core/config-schema.ts';
-import { resolveBncrChannelPolicy } from './core/policy.ts';
-import { buildBncrPermissionSummary } from './core/permissions.ts';
+  deleteBncrMessageAction,
+  editBncrMessageAction,
+  reactBncrMessageAction,
+  sendBncrReplyAction,
+} from './messaging/outbound/actions.ts';
+import {
+  buildBncrMediaOutboundFrame,
+  resolveBncrOutboundMessageType,
+} from './messaging/outbound/media.ts';
+import { sendBncrMedia, sendBncrText } from './messaging/outbound/send.ts';
 const BRIDGE_VERSION = 2;
 const BNCR_PUSH_EVENT = 'bncr.push';
 const CONNECT_TTL_MS = 120_000;
@@ -63,6 +77,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 +145,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() {
@@ -142,13 +169,11 @@ function asString(v: unknown, fallback = ''): string {
   return String(v);
 }
 
-
 function backoffMs(retryCount: number): number {
   // 1s,2s,4s,8s... capped by retry count checks
   return Math.max(1_000, 1_000 * 2 ** Math.max(0, retryCount - 1));
 }
 
-
 function fileExtFromMime(mimeType?: string): string {
   const mt = asString(mimeType || '').toLowerCase();
   const map: Record<string, string> = {
@@ -171,7 +196,15 @@ function fileExtFromMime(mimeType?: string): string {
 function sanitizeFileName(rawName?: string, fallback = 'file.bin'): string {
   const name = asString(rawName || '').trim();
   const base = name || fallback;
-  const cleaned = base.replace(/[\\/:*?"<>|\x00-\x1F]+/g, '_').replace(/\s+/g, ' ').trim();
+  const cleaned = Array.from(base, (ch) => {
+    const code = ch.charCodeAt(0);
+    if (code <= 0x1f) return '_';
+    if ('\\/:*?"<>|'.includes(ch)) return '_';
+    return ch;
+  })
+    .join('')
+    .replace(/\s+/g, ' ')
+    .trim();
   return cleaned || fallback;
 }
 
@@ -183,7 +216,11 @@ function buildTimestampFileName(mimeType?: string): string {
   return `bncr_${ts}_${Math.random().toString(16).slice(2, 8)}${ext}`;
 }
 
-function resolveOutboundFileName(params: { mediaUrl?: string; fileName?: string; mimeType?: string }): string {
+function resolveOutboundFileName(params: {
+  mediaUrl?: string;
+  fileName?: string;
+  mimeType?: string;
+}): string {
   const mediaUrl = asString(params.mediaUrl || '').trim();
   const mimeType = asString(params.mimeType || '').trim();
 
@@ -205,20 +242,85 @@ 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
   private outbox = new Map<string, OutboxEntry>(); // messageId -> entry
   private deadLetter: OutboxEntry[] = [];
 
-  private sessionRoutes = new Map<string, { accountId: string; route: BncrRoute; updatedAt: number }>();
-  private routeAliases = new Map<string, { accountId: string; route: BncrRoute; updatedAt: number }>();
+  private sessionRoutes = new Map<
+    string,
+    { accountId: string; route: BncrRoute; updatedAt: number }
+  >();
+  private routeAliases = new Map<
+    string,
+    { accountId: string; route: BncrRoute; updatedAt: number }
+  >();
 
   private recentInbound = new Map<string, number>();
-  private lastSessionByAccount = new Map<string, { sessionKey: string; scope: string; updatedAt: number }>();
+  private lastSessionByAccount = new Map<
+    string,
+    { sessionKey: string; scope: string; updatedAt: number }
+  >();
   private lastActivityByAccount = new Map<string, number>();
   private lastInboundByAccount = new Map<string, number>();
   private lastOutboundByAccount = new Map<string, number>();
+  private canonicalAgentId: string | null = null;
+  private canonicalAgentSource: 'startup' | 'runtime' | 'fallback-main' | null = null;
+  private canonicalAgentResolvedAt: number | null = null;
 
   // 内置健康/回归计数（替代独立脚本）
   private startedAt = now();
@@ -236,16 +338,313 @@ class BncrBridgeRuntime {
   // 文件互传状态（V1：尽力而为，重连不续传）
   private fileSendTransfers = new Map<string, FileSendTransferState>(); // OpenClaw -> Bncr（服务端发起）
   private fileRecvTransfers = new Map<string, FileRecvTransferState>(); // Bncr -> OpenClaw（客户端发起）
-  private fileAckWaiters = new Map<string, {
-    resolve: (payload: Record<string, unknown>) => void;
-    reject: (err: Error) => void;
-    timer: NodeJS.Timeout;
-  }>();
+  private fileAckWaiters = new Map<
+    string,
+    {
+      resolve: (payload: Record<string, unknown>) => void;
+      reject: (err: Error) => void;
+      timer: NodeJS.Timeout;
+    }
+  >();
 
   constructor(api: OpenClawPluginApi) {
     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) || {};
@@ -258,10 +657,18 @@ class BncrBridgeRuntime {
   startService = async (ctx: OpenClawPluginServiceContext, debug?: boolean) => {
     this.statePath = path.join(ctx.stateDir, 'bncr-bridge-state.json');
     await this.loadState();
+    try {
+      const cfg = await this.api.runtime.config.loadConfig();
+      this.initializeCanonicalAgentId(cfg);
+    } catch {
+      // ignore startup canonical agent initialization errors
+    }
     if (typeof debug === 'boolean') BNCR_DEBUG_VERBOSE = debug;
     const bootDiag = this.buildIntegratedDiagnostics(BNCR_DEFAULT_ACCOUNT_ID);
     if (BNCR_DEBUG_VERBOSE) {
-      this.api.logger.info(`bncr-channel service started (bridge=${this.bridgeId} diag.ok=${bootDiag.regression.ok} routes=${bootDiag.regression.totalKnownRoutes} pending=${bootDiag.health.pending} dead=${bootDiag.health.deadLetter} debug=${BNCR_DEBUG_VERBOSE})`);
+      this.api.logger.info(
+        `bncr-channel service started (bridge=${this.bridgeId} diag.ok=${bootDiag.regression.ok} routes=${bootDiag.regression.totalKnownRoutes} pending=${bootDiag.health.pending} dead=${bootDiag.health.deadLetter} debug=${BNCR_DEBUG_VERBOSE})`,
+      );
     }
   };
 
@@ -307,6 +714,65 @@ class BncrBridgeRuntime {
     }
   }
 
+  private tryResolveBindingAgentId(args: {
+    cfg: any;
+    accountId: string;
+    peer?: any;
+    channelId?: string;
+  }): string | null {
+    try {
+      const resolved = this.api.runtime.channel.routing.resolveAgentRoute({
+        cfg: args.cfg,
+        channel: args.channelId || CHANNEL_ID,
+        accountId: normalizeAccountId(args.accountId),
+        peer: args.peer,
+      });
+      const agentId = asString(resolved?.agentId || '').trim();
+      return agentId || null;
+    } catch {
+      return null;
+    }
+  }
+
+  private initializeCanonicalAgentId(cfg: any) {
+    if (this.canonicalAgentId) return;
+    const agentId = this.tryResolveBindingAgentId({
+      cfg,
+      accountId: BNCR_DEFAULT_ACCOUNT_ID,
+      channelId: CHANNEL_ID,
+      peer: { kind: 'direct', id: 'bootstrap' },
+    });
+    if (!agentId) return;
+    this.canonicalAgentId = agentId;
+    this.canonicalAgentSource = 'startup';
+    this.canonicalAgentResolvedAt = now();
+  }
+
+  private ensureCanonicalAgentId(args: {
+    cfg: any;
+    accountId: string;
+    peer?: any;
+    channelId?: string;
+  }): string {
+    if (this.canonicalAgentId) return this.canonicalAgentId;
+
+    const agentId = this.tryResolveBindingAgentId(args);
+    if (agentId) {
+      this.canonicalAgentId = agentId;
+      this.canonicalAgentSource = 'runtime';
+      this.canonicalAgentResolvedAt = now();
+      return agentId;
+    }
+
+    this.canonicalAgentId = 'main';
+    this.canonicalAgentSource = 'fallback-main';
+    this.canonicalAgentResolvedAt = now();
+    this.api.logger.warn?.(
+      '[bncr-canonical-agent] binding agent unresolved; fallback to main for current process lifetime',
+    );
+    return this.canonicalAgentId;
+  }
+
   private countInvalidOutboxSessionKeys(accountId: string): number {
     const acc = normalizeAccountId(accountId);
     let count = 0;
@@ -319,7 +785,8 @@ class BncrBridgeRuntime {
 
   private countLegacyAccountResidue(accountId: string): number {
     const acc = normalizeAccountId(accountId);
-    const mismatched = (raw?: string | null) => asString(raw || '').trim() && normalizeAccountId(raw) !== acc;
+    const mismatched = (raw?: string | null) =>
+      asString(raw || '').trim() && normalizeAccountId(raw) !== acc;
 
     let count = 0;
 
@@ -365,7 +832,8 @@ class BncrBridgeRuntime {
       lastActivityAt: this.lastActivityByAccount.get(acc) || null,
       lastInboundAt: this.lastInboundByAccount.get(acc) || null,
       lastOutboundAt: this.lastOutboundByAccount.get(acc) || null,
-      sessionRoutesCount: Array.from(this.sessionRoutes.values()).filter((v) => v.accountId === acc).length,
+      sessionRoutesCount: Array.from(this.sessionRoutes.values()).filter((v) => v.accountId === acc)
+        .length,
       invalidOutboxSessionKeys: this.countInvalidOutboxSessionKeys(acc),
       legacyAccountResidue: this.countLegacyAccountResidue(acc),
       channelRoot: path.join(process.cwd(), 'plugins', 'bncr'),
@@ -386,11 +854,12 @@ class BncrBridgeRuntime {
       if (!entry?.messageId) continue;
       const accountId = normalizeAccountId(entry.accountId);
       const sessionKey = asString(entry.sessionKey || '').trim();
-      const normalized = normalizeStoredSessionKey(sessionKey);
+      const normalized = normalizeStoredSessionKey(sessionKey, this.canonicalAgentId);
       if (!normalized) continue;
 
       const route = parseRouteLike(entry.route) || normalized.route;
-      const payload = (entry.payload && typeof entry.payload === 'object') ? { ...entry.payload } : {};
+      const payload =
+        entry.payload && typeof entry.payload === 'object' ? { ...entry.payload } : {};
       (payload as any).sessionKey = normalized.sessionKey;
       (payload as any).platform = route.platform;
       (payload as any).groupId = route.groupId;
@@ -417,11 +886,12 @@ class BncrBridgeRuntime {
       if (!entry?.messageId) continue;
       const accountId = normalizeAccountId(entry.accountId);
       const sessionKey = asString(entry.sessionKey || '').trim();
-      const normalized = normalizeStoredSessionKey(sessionKey);
+      const normalized = normalizeStoredSessionKey(sessionKey, this.canonicalAgentId);
       if (!normalized) continue;
 
       const route = parseRouteLike(entry.route) || normalized.route;
-      const payload = (entry.payload && typeof entry.payload === 'object') ? { ...entry.payload } : {};
+      const payload =
+        entry.payload && typeof entry.payload === 'object' ? { ...entry.payload } : {};
       (payload as any).sessionKey = normalized.sessionKey;
       (payload as any).platform = route.platform;
       (payload as any).groupId = route.groupId;
@@ -444,7 +914,10 @@ class BncrBridgeRuntime {
     this.sessionRoutes.clear();
     this.routeAliases.clear();
     for (const item of data.sessionRoutes || []) {
-      const normalized = normalizeStoredSessionKey(asString(item?.sessionKey || ''));
+      const normalized = normalizeStoredSessionKey(
+        asString(item?.sessionKey || ''),
+        this.canonicalAgentId,
+      );
       if (!normalized) continue;
 
       const route = parseRouteLike(item?.route) || normalized.route;
@@ -464,7 +937,10 @@ class BncrBridgeRuntime {
     this.lastSessionByAccount.clear();
     for (const item of data.lastSessionByAccount || []) {
       const accountId = normalizeAccountId(item?.accountId);
-      const normalized = normalizeStoredSessionKey(asString(item?.sessionKey || ''));
+      const normalized = normalizeStoredSessionKey(
+        asString(item?.sessionKey || ''),
+        this.canonicalAgentId,
+      );
       const updatedAt = Number(item?.updatedAt || 0);
       if (!normalized || !Number.isFinite(updatedAt) || updatedAt <= 0) continue;
 
@@ -500,6 +976,39 @@ 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()) {
@@ -542,24 +1051,46 @@ class BncrBridgeRuntime {
       outbox: Array.from(this.outbox.values()),
       deadLetter: this.deadLetter.slice(-1000),
       sessionRoutes,
-      lastSessionByAccount: Array.from(this.lastSessionByAccount.entries()).map(([accountId, v]) => ({
-        accountId,
-        sessionKey: v.sessionKey,
-        scope: v.scope,
-        updatedAt: v.updatedAt,
-      })),
-      lastActivityByAccount: Array.from(this.lastActivityByAccount.entries()).map(([accountId, updatedAt]) => ({
-        accountId,
-        updatedAt,
-      })),
-      lastInboundByAccount: Array.from(this.lastInboundByAccount.entries()).map(([accountId, updatedAt]) => ({
-        accountId,
-        updatedAt,
-      })),
-      lastOutboundByAccount: Array.from(this.lastOutboundByAccount.entries()).map(([accountId, updatedAt]) => ({
-        accountId,
-        updatedAt,
-      })),
+      lastSessionByAccount: Array.from(this.lastSessionByAccount.entries()).map(
+        ([accountId, v]) => ({
+          accountId,
+          sessionKey: v.sessionKey,
+          scope: v.scope,
+          updatedAt: v.updatedAt,
+        }),
+      ),
+      lastActivityByAccount: Array.from(this.lastActivityByAccount.entries()).map(
+        ([accountId, updatedAt]) => ({
+          accountId,
+          updatedAt,
+        }),
+      ),
+      lastInboundByAccount: Array.from(this.lastInboundByAccount.entries()).map(
+        ([accountId, updatedAt]) => ({
+          accountId,
+          updatedAt,
+        }),
+      ),
+      lastOutboundByAccount: Array.from(this.lastOutboundByAccount.entries()).map(
+        ([accountId, updatedAt]) => ({
+          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);
@@ -682,7 +1213,11 @@ class BncrBridgeRuntime {
     const filterAcc = accountId ? normalizeAccountId(accountId) : null;
     const targetAccounts = filterAcc
       ? [filterAcc]
-      : Array.from(new Set(Array.from(this.outbox.values()).map((entry) => normalizeAccountId(entry.accountId))));
+      : Array.from(
+          new Set(
+            Array.from(this.outbox.values()).map((entry) => normalizeAccountId(entry.accountId)),
+          ),
+        );
     if (BNCR_DEBUG_VERBOSE) {
       this.api.logger.info?.(
         `[bncr-outbox-flush] ${JSON.stringify({
@@ -761,10 +1296,14 @@ class BncrBridgeRuntime {
         if (!directPayloads.length) continue;
 
         try {
-          ctx.broadcastToConnIds(BNCR_PUSH_EVENT, {
-            forcePush: true,
-            items: directPayloads,
-          }, new Set(directConnIds));
+          ctx.broadcastToConnIds(
+            BNCR_PUSH_EVENT,
+            {
+              forcePush: true,
+              items: directPayloads,
+            },
+            new Set(directConnIds),
+          );
 
           const pushedIds = directPayloads
             .map((item: any) => asString(item?.messageId || item?.idempotencyKey || '').trim())
@@ -842,7 +1381,8 @@ class BncrBridgeRuntime {
         }
 
         if (localNextDelay != null) {
-          globalNextDelay = globalNextDelay == null ? localNextDelay : Math.min(globalNextDelay, localNextDelay);
+          globalNextDelay =
+            globalNextDelay == null ? localNextDelay : Math.min(globalNextDelay, localNextDelay);
         }
       } finally {
         this.pushDrainRunningAccounts.delete(acc);
@@ -964,7 +1504,11 @@ class BncrBridgeRuntime {
     }
 
     const curConn = this.connections.get(current);
-    if (!curConn || t - curConn.lastSeenAt > CONNECT_TTL_MS || nextConn.connectedAt >= curConn.connectedAt) {
+    if (
+      !curConn ||
+      t - curConn.lastSeenAt > CONNECT_TTL_MS ||
+      nextConn.connectedAt >= curConn.connectedAt
+    ) {
       this.activeConnectionByAccount.set(acc, key);
     }
   }
@@ -1016,9 +1560,6 @@ class BncrBridgeRuntime {
     const info = { accountId: acc, route, updatedAt: t };
 
     this.sessionRoutes.set(key, info);
-    // 同步维护旧格式与新格式，便于平滑切换
-    this.sessionRoutes.set(buildFallbackSessionKey(route), info);
-
     this.routeAliases.set(routeKey(acc, route), info);
     this.lastSessionByAccount.set(acc, {
       sessionKey: key,
@@ -1048,7 +1589,10 @@ class BncrBridgeRuntime {
   // 1) 标准 to 仅认 Bncr:<platform>:<groupId>:<userId> / Bncr:<platform>:<userId>
   // 2) 仍接受 strict sessionKey 作为内部兼容输入
   // 3) 其他旧格式直接失败，并输出标准格式提示日志
-  private resolveVerifiedTarget(rawTarget: string, accountId: string): { sessionKey: string; route: BncrRoute; displayScope: string } {
+  private resolveVerifiedTarget(
+    rawTarget: string,
+    accountId: string,
+  ): { sessionKey: string; route: BncrRoute; displayScope: string } {
     const acc = normalizeAccountId(accountId);
     const raw = asString(rawTarget).trim();
     if (!raw) throw new Error('bncr invalid target(empty)');
@@ -1068,17 +1612,23 @@ class BncrBridgeRuntime {
 
     if (!route) {
       this.api.logger.warn?.(
-        `[bncr-target-invalid] raw=${raw} accountId=${acc} reason=unparseable-or-unknown standardTo=Bncr:<platform>:<groupId>:<userId>|Bncr:<platform>:<userId> standardSessionKey=agent:main:bncr:direct:<hex(scope)>`,
+        `[bncr-target-invalid] raw=${raw} accountId=${acc} reason=unparseable-or-unknown standardTo=Bncr:<platform>:<groupId>:<userId>|Bncr:<platform>:<userId> standardSessionKey=agent:<agentId>:bncr:direct:<hex(scope)>`,
+      );
+      throw new Error(
+        `bncr invalid target(standard: Bncr:<platform>:<groupId>:<userId> | Bncr:<platform>:<userId>): ${raw}`,
       );
-      throw new Error(`bncr invalid target(standard: Bncr:<platform>:<groupId>:<userId> | Bncr:<platform>:<userId>): ${raw}`);
     }
 
     const wantedRouteKey = routeKey(acc, route);
     let best: { sessionKey: string; route: BncrRoute; updatedAt: number } | null = null;
 
     if (BNCR_DEBUG_VERBOSE) {
-      this.api.logger.info?.(`[bncr-target-incoming-route] raw=${raw} accountId=${acc} route=${JSON.stringify(route)}`);
-      this.api.logger.info?.(`[bncr-target-incoming-sessionRoutes] raw=${raw} accountId=${acc} sessionRoutes=${JSON.stringify(this.sessionRoutes.entries())}`);
+      this.api.logger.info?.(
+        `[bncr-target-incoming-route] raw=${raw} accountId=${acc} route=${JSON.stringify(route)}`,
+      );
+      this.api.logger.info?.(
+        `[bncr-target-incoming-sessionRoutes] raw=${raw} accountId=${acc} sessionRoutes=${JSON.stringify(this.sessionRoutes.entries())}`,
+      );
     }
 
     for (const [key, info] of this.sessionRoutes.entries()) {
@@ -1090,29 +1640,40 @@ class BncrBridgeRuntime {
       const updatedAt = Number(info.updatedAt || 0);
       if (!best || updatedAt >= best.updatedAt) {
         best = {
-          sessionKey: parsed.sessionKey,
+          sessionKey: key,
           route: parsed.route,
           updatedAt,
         };
       }
     }
 
-    // 直接根据raw生成标准sessionkey
     if (!best) {
       const updatedAt = 0;
+      const canonicalAgentId =
+        this.canonicalAgentId ||
+        this.ensureCanonicalAgentId({
+          cfg: this.api.runtime.config?.get?.() || {},
+          accountId: acc,
+          channelId: CHANNEL_ID,
+          peer: { kind: 'direct', id: route.groupId === '0' ? route.userId : route.groupId },
+        });
       best = {
-        sessionKey: `agent:main:bncr:direct:${routeScopeToHex(route)}`,
+        sessionKey: buildCanonicalBncrSessionKey(route, canonicalAgentId),
         route,
         updatedAt,
       };
     }
 
     if (BNCR_DEBUG_VERBOSE) {
-      this.api.logger.info?.(`[bncr-target-incoming-best] raw=${raw} accountId=${acc} best=${JSON.stringify(best)}`);
+      this.api.logger.info?.(
+        `[bncr-target-incoming-best] raw=${raw} accountId=${acc} best=${JSON.stringify(best)}`,
+      );
     }
 
     if (!best) {
-      this.api.logger.warn?.(`[bncr-target-miss] raw=${raw} accountId=${acc} sessionRoutes=${this.sessionRoutes.size}`);
+      this.api.logger.warn?.(
+        `[bncr-target-miss] raw=${raw} accountId=${acc} sessionRoutes=${this.sessionRoutes.size}`,
+      );
       throw new Error(`bncr target not found in known sessions: ${raw}`);
     }
 
@@ -1140,11 +1701,19 @@ class BncrBridgeRuntime {
     return `${transferId}|${stage}|${idx}`;
   }
 
-  private waitForFileAck(params: { transferId: string; stage: string; chunkIndex?: number; timeoutMs?: number }) {
+  private waitForFileAck(params: {
+    transferId: string;
+    stage: string;
+    chunkIndex?: number;
+    timeoutMs?: number;
+  }) {
     const transferId = asString(params.transferId).trim();
     const stage = asString(params.stage).trim();
     const key = this.fileAckKey(transferId, stage, params.chunkIndex);
-    const timeoutMs = Math.max(1_000, Math.min(Number(params.timeoutMs || FILE_ACK_TIMEOUT_MS), 120_000));
+    const timeoutMs = Math.max(
+      1_000,
+      Math.min(Number(params.timeoutMs || FILE_ACK_TIMEOUT_MS), 120_000),
+    );
 
     return new Promise<Record<string, unknown>>((resolve, reject) => {
       const timer = setTimeout(() => {
@@ -1155,7 +1724,13 @@ class BncrBridgeRuntime {
     });
   }
 
-  private resolveFileAck(params: { transferId: string; stage: string; chunkIndex?: number; payload: Record<string, unknown>; ok: boolean }) {
+  private resolveFileAck(params: {
+    transferId: string;
+    stage: string;
+    chunkIndex?: number;
+    payload: Record<string, unknown>;
+    ok: boolean;
+  }) {
     const transferId = asString(params.transferId).trim();
     const stage = asString(params.stage).trim();
     const key = this.fileAckKey(transferId, stage, params.chunkIndex);
@@ -1164,11 +1739,20 @@ class BncrBridgeRuntime {
     this.fileAckWaiters.delete(key);
     clearTimeout(waiter.timer);
     if (params.ok) waiter.resolve(params.payload);
-    else waiter.reject(new Error(asString(params.payload?.errorMessage || params.payload?.error || 'file ack failed')));
+    else
+      waiter.reject(
+        new Error(
+          asString(params.payload?.errorMessage || params.payload?.error || 'file ack failed'),
+        ),
+      );
     return true;
   }
 
-  private pushFileEventToAccount(accountId: string, event: string, payload: Record<string, unknown>) {
+  private pushFileEventToAccount(
+    accountId: string,
+    event: string,
+    payload: Record<string, unknown>,
+  ) {
     const connIds = this.resolvePushConnIds(accountId);
     if (!connIds.size || !this.gatewayContext) {
       throw new Error(`no active bncr connection for account=${accountId}`);
@@ -1191,7 +1775,9 @@ class BncrBridgeRuntime {
     return dir;
   }
 
-  private async materializeRecvTransfer(st: FileRecvTransferState): Promise<{ path: string; fileSha256: string }> {
+  private async materializeRecvTransfer(
+    st: FileRecvTransferState,
+  ): Promise<{ path: string; fileSha256: string }> {
     const dir = this.resolveInboundFilesDir();
     const safeName = asString(st.fileName).trim() || `${st.transferId}.bin`;
     const finalPath = path.join(dir, safeName);
@@ -1233,7 +1819,8 @@ class BncrBridgeRuntime {
       lastActivityAt: this.lastActivityByAccount.get(acc) || null,
       lastInboundAt: this.lastInboundByAccount.get(acc) || null,
       lastOutboundAt: this.lastOutboundByAccount.get(acc) || null,
-      sessionRoutesCount: Array.from(this.sessionRoutes.values()).filter((v) => v.accountId === acc).length,
+      sessionRoutesCount: Array.from(this.sessionRoutes.values()).filter((v) => v.accountId === acc)
+        .length,
       invalidOutboxSessionKeys: this.countInvalidOutboxSessionKeys(acc),
       legacyAccountResidue: this.countLegacyAccountResidue(acc),
       channelRoot: path.join(process.cwd(), 'plugins', 'bncr'),
@@ -1257,7 +1844,8 @@ class BncrBridgeRuntime {
       lastActivityAt: this.lastActivityByAccount.get(acc) || null,
       lastInboundAt: this.lastInboundByAccount.get(acc) || null,
       lastOutboundAt: this.lastOutboundByAccount.get(acc) || null,
-      sessionRoutesCount: Array.from(this.sessionRoutes.values()).filter((v) => v.accountId === acc).length,
+      sessionRoutesCount: Array.from(this.sessionRoutes.values()).filter((v) => v.accountId === acc)
+        .length,
       invalidOutboxSessionKeys: this.countInvalidOutboxSessionKeys(acc),
       legacyAccountResidue: this.countLegacyAccountResidue(acc),
       running: true,
@@ -1282,7 +1870,8 @@ class BncrBridgeRuntime {
       lastActivityAt: this.lastActivityByAccount.get(acc) || null,
       lastInboundAt: this.lastInboundByAccount.get(acc) || null,
       lastOutboundAt: this.lastOutboundByAccount.get(acc) || null,
-      sessionRoutesCount: Array.from(this.sessionRoutes.values()).filter((v) => v.accountId === acc).length,
+      sessionRoutesCount: Array.from(this.sessionRoutes.values()).filter((v) => v.accountId === acc)
+        .length,
       invalidOutboxSessionKeys: this.countInvalidOutboxSessionKeys(acc),
       legacyAccountResidue: this.countLegacyAccountResidue(acc),
       channelRoot: path.join(process.cwd(), 'plugins', 'bncr'),
@@ -1407,7 +1996,10 @@ class BncrBridgeRuntime {
     timeoutMs?: number;
   }): Promise<void> {
     const { transferId, chunkIndex } = params;
-    const timeoutMs = Math.max(1_000, Math.min(Number(params.timeoutMs || FILE_TRANSFER_ACK_TTL_MS), 60_000));
+    const timeoutMs = Math.max(
+      1_000,
+      Math.min(Number(params.timeoutMs || FILE_TRANSFER_ACK_TTL_MS), 60_000),
+    );
     const started = now();
 
     return new Promise<void>((resolve, reject) => {
@@ -1476,7 +2068,13 @@ class BncrBridgeRuntime {
     route: BncrRoute;
     mediaUrl: string;
     mediaLocalRoots?: readonly string[];
-  }): Promise<{ mode: 'base64' | 'chunk'; mimeType?: string; fileName?: string; mediaBase64?: string; path?: string }> {
+  }): Promise<{
+    mode: 'base64' | 'chunk';
+    mimeType?: string;
+    fileName?: string;
+    mediaBase64?: string;
+    path?: string;
+  }> {
     const loaded = await this.api.runtime.media.loadWebMedia(params.mediaUrl, {
       localRoots: params.mediaLocalRoots,
       maxBytes: 50 * 1024 * 1024,
@@ -1528,21 +2126,25 @@ class BncrBridgeRuntime {
     };
     this.fileSendTransfers.set(transferId, st);
 
-    ctx.broadcastToConnIds('bncr.file.init', {
-      transferId,
-      direction: 'oc2bncr',
-      sessionKey: params.sessionKey,
-      platform: params.route.platform,
-      groupId: params.route.groupId,
-      userId: params.route.userId,
-      fileName,
-      mimeType,
-      fileSize: size,
-      chunkSize,
-      totalChunks,
-      fileSha256,
-      ts: now(),
-    }, connIds);
+    ctx.broadcastToConnIds(
+      'bncr.file.init',
+      {
+        transferId,
+        direction: 'oc2bncr',
+        sessionKey: params.sessionKey,
+        platform: params.route.platform,
+        groupId: params.route.groupId,
+        userId: params.route.userId,
+        fileName,
+        mimeType,
+        fileSize: size,
+        chunkSize,
+        totalChunks,
+        fileSha256,
+        ts: now(),
+      },
+      connIds,
+    );
 
     // 逐块发送并等待 ACK
     for (let idx = 0; idx < totalChunks; idx++) {
@@ -1554,18 +2156,26 @@ class BncrBridgeRuntime {
       let ok = false;
       let lastErr: unknown = null;
       for (let attempt = 1; attempt <= 3; attempt++) {
-        ctx.broadcastToConnIds('bncr.file.chunk', {
-          transferId,
-          chunkIndex: idx,
-          offset: start,
-          size: slice.byteLength,
-          chunkSha256,
-          base64: slice.toString('base64'),
-          ts: now(),
-        }, connIds);
+        ctx.broadcastToConnIds(
+          'bncr.file.chunk',
+          {
+            transferId,
+            chunkIndex: idx,
+            offset: start,
+            size: slice.byteLength,
+            chunkSha256,
+            base64: slice.toString('base64'),
+            ts: now(),
+          },
+          connIds,
+        );
 
         try {
-          await this.waitChunkAck({ transferId, chunkIndex: idx, timeoutMs: FILE_TRANSFER_ACK_TTL_MS });
+          await this.waitChunkAck({
+            transferId,
+            chunkIndex: idx,
+            timeoutMs: FILE_TRANSFER_ACK_TTL_MS,
+          });
           ok = true;
           break;
         } catch (err) {
@@ -1578,19 +2188,27 @@ class BncrBridgeRuntime {
         st.status = 'aborted';
         st.error = String((lastErr as any)?.message || lastErr || `chunk-${idx}-failed`);
         this.fileSendTransfers.set(transferId, st);
-        ctx.broadcastToConnIds('bncr.file.abort', {
-          transferId,
-          reason: st.error,
-          ts: now(),
-        }, connIds);
+        ctx.broadcastToConnIds(
+          'bncr.file.abort',
+          {
+            transferId,
+            reason: st.error,
+            ts: now(),
+          },
+          connIds,
+        );
         throw new Error(st.error);
       }
     }
 
-    ctx.broadcastToConnIds('bncr.file.complete', {
-      transferId,
-      ts: now(),
-    }, connIds);
+    ctx.broadcastToConnIds(
+      'bncr.file.complete',
+      {
+        transferId,
+        ts: now(),
+      },
+      connIds,
+    );
 
     const done = await this.waitCompleteAck({ transferId, timeoutMs: 60_000 });
 
@@ -1606,7 +2224,14 @@ class BncrBridgeRuntime {
     accountId: string;
     sessionKey: string;
     route: BncrRoute;
-    payload: { text?: string; mediaUrl?: string; mediaUrls?: string[]; asVoice?: boolean; audioAsVoice?: boolean; kind?: 'block' | 'final' };
+    payload: {
+      text?: string;
+      mediaUrl?: string;
+      mediaUrls?: string[];
+      asVoice?: boolean;
+      audioAsVoice?: boolean;
+      kind?: 'block' | 'final';
+    };
     mediaLocalRoots?: readonly string[];
   }) {
     const { accountId, sessionKey, route, payload, mediaLocalRoots } = params;
@@ -1718,6 +2343,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 +2355,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 +2375,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 +2436,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 +2470,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 +2505,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();
@@ -1902,11 +2539,12 @@ class BncrBridgeRuntime {
       return;
     }
 
-    const route = parseRouteLike({
-      platform: asString(params?.platform || normalized.route.platform),
-      groupId: asString(params?.groupId || normalized.route.groupId),
-      userId: asString(params?.userId || normalized.route.userId),
-    }) || normalized.route;
+    const route =
+      parseRouteLike({
+        platform: asString(params?.platform || normalized.route.platform),
+        groupId: asString(params?.groupId || normalized.route.groupId),
+        userId: asString(params?.userId || normalized.route.userId),
+      }) || normalized.route;
 
     this.fileRecvTransfers.set(transferId, {
       transferId,
@@ -1938,6 +2576,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();
@@ -1985,12 +2624,18 @@ class BncrBridgeRuntime {
     }
   };
 
-  handleFileComplete = async ({ params, respond, client, context }: GatewayRequestHandlerOptions) => {
+  handleFileComplete = async ({
+    params,
+    respond,
+    client,
+    context,
+  }: GatewayRequestHandlerOptions) => {
     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.rememberGatewayContext(context);
     this.markSeen(accountId, connId, clientId);
+    this.observeLease('file.complete', params ?? {});
     this.markActivity(accountId);
 
     const transferId = asString(params?.transferId || '').trim();
@@ -2007,10 +2652,14 @@ class BncrBridgeRuntime {
 
     try {
       if (st.receivedChunks.size < st.totalChunks) {
-        throw new Error(`chunk not complete received=${st.receivedChunks.size} total=${st.totalChunks}`);
+        throw new Error(
+          `chunk not complete received=${st.receivedChunks.size} total=${st.totalChunks}`,
+        );
       }
 
-      const ordered = Array.from(st.bufferByChunk.entries()).sort((a, b) => a[0] - b[0]).map((x) => x[1]);
+      const ordered = Array.from(st.bufferByChunk.entries())
+        .sort((a, b) => a[0] - b[0])
+        .map((x) => x[1]);
       const merged = Buffer.concat(ordered);
       if (st.fileSize > 0 && merged.length !== st.fileSize) {
         throw new Error(`file size mismatch expected=${st.fileSize} got=${merged.length}`);
@@ -2054,6 +2703,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();
@@ -2144,12 +2794,31 @@ class BncrBridgeRuntime {
 
   handleInbound = async ({ params, respond, client, context }: GatewayRequestHandlerOptions) => {
     const parsed = parseBncrInboundParams(params);
-    const { accountId, platform, groupId, userId, sessionKeyfromroute, route, text, msgType, mediaBase64, mediaPathFromTransfer, mimeType, fileName, msgId, dedupKey, peer, extracted } = parsed;
+    const {
+      accountId,
+      platform,
+      groupId,
+      userId,
+      sessionKeyfromroute,
+      route,
+      text,
+      msgType,
+      mediaBase64,
+      mediaPathFromTransfer,
+      mimeType,
+      fileName,
+      msgId,
+      dedupKey,
+      peer,
+      extracted,
+    } = parsed;
     const connId = asString(client?.connId || '').trim() || `no-conn-${Date.now()}`;
     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)) {
@@ -2182,13 +2851,21 @@ class BncrBridgeRuntime {
       return;
     }
 
-    const baseSessionKey = normalizeInboundSessionKey(sessionKeyfromroute, route)
-      || this.api.runtime.channel.routing.resolveAgentRoute({
-        cfg,
-        channel: CHANNEL_ID,
-        accountId,
-        peer,
-      }).sessionKey;
+    const canonicalAgentId = this.ensureCanonicalAgentId({
+      cfg,
+      accountId,
+      peer,
+      channelId: CHANNEL_ID,
+    });
+    const resolvedRoute = this.api.runtime.channel.routing.resolveAgentRoute({
+      cfg,
+      channel: CHANNEL_ID,
+      accountId,
+      peer,
+    });
+    const baseSessionKey =
+      normalizeInboundSessionKey(sessionKeyfromroute, route, canonicalAgentId) ||
+      resolvedRoute.sessionKey;
     const taskSessionKey = withTaskSessionKey(baseSessionKey, extracted.taskKey);
     const sessionKey = taskSessionKey || baseSessionKey;
 
@@ -2205,7 +2882,9 @@ class BncrBridgeRuntime {
       channelId: CHANNEL_ID,
       cfg,
       parsed,
-      rememberSessionRoute: (sessionKey, accountId, route) => this.rememberSessionRoute(sessionKey, accountId, route),
+      canonicalAgentId,
+      rememberSessionRoute: (sessionKey, accountId, route) =>
+        this.rememberSessionRoute(sessionKey, accountId, route),
       enqueueFromReply: (args) => this.enqueueFromReply(args),
       setInboundActivity: (accountId, at) => {
         this.lastInboundByAccount.set(accountId, at);
@@ -2291,7 +2970,8 @@ class BncrBridgeRuntime {
       text: asString(ctx.text || ''),
       mediaLocalRoots: ctx.mediaLocalRoots,
       resolveVerifiedTarget: (to, accountId) => this.resolveVerifiedTarget(to, accountId),
-      rememberSessionRoute: (sessionKey, accountId, route) => this.rememberSessionRoute(sessionKey, accountId, route),
+      rememberSessionRoute: (sessionKey, accountId, route) =>
+        this.rememberSessionRoute(sessionKey, accountId, route),
       enqueueFromReply: (args) => this.enqueueFromReply(args),
       createMessageId: () => randomUUID(),
     });
@@ -2335,7 +3015,8 @@ class BncrBridgeRuntime {
       audioAsVoice,
       mediaLocalRoots: ctx.mediaLocalRoots,
       resolveVerifiedTarget: (to, accountId) => this.resolveVerifiedTarget(to, accountId),
-      rememberSessionRoute: (sessionKey, accountId, route) => this.rememberSessionRoute(sessionKey, accountId, route),
+      rememberSessionRoute: (sessionKey, accountId, route) =>
+        this.rememberSessionRoute(sessionKey, accountId, route),
       enqueueFromReply: (args) => this.enqueueFromReply(args),
       createMessageId: () => randomUUID(),
     });
@@ -2350,10 +3031,13 @@ export function createBncrChannelPlugin(bridge: BncrBridgeRuntime) {
   const messageActions: ChannelMessageActionAdapter = {
     describeMessageTool: ({ cfg }) => {
       const channelCfg = cfg?.channels?.[CHANNEL_ID];
-      const hasExplicitConfiguredAccount = Boolean(channelCfg && typeof channelCfg === 'object')
-        && resolveBncrChannelPolicy(channelCfg).enabled !== false
-        && Boolean(channelCfg.accounts && typeof channelCfg.accounts === 'object')
-        && Object.keys(channelCfg.accounts).some((accountId) => resolveAccount(cfg, accountId).enabled !== false);
+      const hasExplicitConfiguredAccount =
+        Boolean(channelCfg && typeof channelCfg === 'object') &&
+        resolveBncrChannelPolicy(channelCfg).enabled !== false &&
+        Boolean(channelCfg.accounts && typeof channelCfg.accounts === 'object') &&
+        Object.keys(channelCfg.accounts).some(
+          (accountId) => resolveAccount(cfg, accountId).enabled !== false,
+        );
 
       const hasConnectedRuntime = listAccountIds(cfg).some((accountId) => {
         const resolved = resolveAccount(cfg, accountId);
@@ -2373,7 +3057,8 @@ export function createBncrChannelPlugin(bridge: BncrBridgeRuntime) {
     supportsAction: ({ action }) => action === 'send',
     extractToolSend: ({ args }) => extractToolSend(args, 'sendMessage'),
     handleAction: async ({ action, params, accountId, mediaLocalRoots }) => {
-      if (action !== 'send') throw new Error(`Action ${action} is not supported for provider ${CHANNEL_ID}.`);
+      if (action !== 'send')
+        throw new Error(`Action ${action} is not supported for provider ${CHANNEL_ID}.`);
       const to = readStringParam(params, 'to', { required: true });
       const message = readStringParam(params, 'message', { allowEmpty: true }) ?? '';
       const caption = readStringParam(params, 'caption', { allowEmpty: true }) ?? '';
@@ -2385,36 +3070,40 @@ export function createBncrChannelPlugin(bridge: BncrBridgeRuntime) {
         readStringParam(params, 'mediaUrl', { trim: false });
       const asVoice = readBooleanParam(params, 'asVoice') ?? false;
       const audioAsVoice = readBooleanParam(params, 'audioAsVoice') ?? false;
-      const resolvedAccountId = normalizeAccountId(readStringParam(params, 'accountId') ?? accountId);
+      const resolvedAccountId = normalizeAccountId(
+        readStringParam(params, 'accountId') ?? accountId,
+      );
 
       if (!content.trim() && !mediaUrl) throw new Error('send requires text or media');
 
       const result = mediaUrl
         ? await sendBncrMedia({
-          channelId: CHANNEL_ID,
-          accountId: resolvedAccountId,
-          to,
-          text: content,
-          mediaUrl,
-          asVoice,
-          audioAsVoice,
-          mediaLocalRoots,
-          resolveVerifiedTarget: (to, accountId) => bridge.resolveVerifiedTarget(to, accountId),
-          rememberSessionRoute: (sessionKey, accountId, route) => bridge.rememberSessionRoute(sessionKey, accountId, route),
-          enqueueFromReply: (args) => bridge.enqueueFromReply(args as any),
-          createMessageId: () => randomUUID(),
-        })
+            channelId: CHANNEL_ID,
+            accountId: resolvedAccountId,
+            to,
+            text: content,
+            mediaUrl,
+            asVoice,
+            audioAsVoice,
+            mediaLocalRoots,
+            resolveVerifiedTarget: (to, accountId) => bridge.resolveVerifiedTarget(to, accountId),
+            rememberSessionRoute: (sessionKey, accountId, route) =>
+              bridge.rememberSessionRoute(sessionKey, accountId, route),
+            enqueueFromReply: (args) => bridge.enqueueFromReply(args as any),
+            createMessageId: () => randomUUID(),
+          })
         : await sendBncrText({
-          channelId: CHANNEL_ID,
-          accountId: resolvedAccountId,
-          to,
-          text: content,
-          mediaLocalRoots,
-          resolveVerifiedTarget: (to, accountId) => bridge.resolveVerifiedTarget(to, accountId),
-          rememberSessionRoute: (sessionKey, accountId, route) => bridge.rememberSessionRoute(sessionKey, accountId, route),
-          enqueueFromReply: (args) => bridge.enqueueFromReply(args as any),
-          createMessageId: () => randomUUID(),
-        });
+            channelId: CHANNEL_ID,
+            accountId: resolvedAccountId,
+            to,
+            text: content,
+            mediaLocalRoots,
+            resolveVerifiedTarget: (to, accountId) => bridge.resolveVerifiedTarget(to, accountId),
+            rememberSessionRoute: (sessionKey, accountId, route) =>
+              bridge.rememberSessionRoute(sessionKey, accountId, route),
+            enqueueFromReply: (args) => bridge.enqueueFromReply(args as any),
+            createMessageId: () => randomUUID(),
+          });
 
       return jsonResult({ ok: true, ...result });
     },
@@ -2447,7 +3136,7 @@ export function createBncrChannelPlugin(bridge: BncrBridgeRuntime) {
         looksLikeId: (raw: string, normalized?: string) => {
           return Boolean(asString(normalized || raw).trim());
         },
-        hint: 'Standard to=Bncr:<platform>:<group>:<user> or Bncr:<platform>:<user>; sessionKey keeps existing strict/legacy compatibility, canonical sessionKey=agent:main:bncr:direct:<hex>',
+        hint: 'Standard to=Bncr:<platform>:<group>:<user> or Bncr:<platform>:<user>; sessionKey keeps existing strict/legacy compatibility, canonical sessionKey=agent:<agentId>:bncr:direct:<hex>',
       },
     },
     configSchema: BncrConfigSchema,
@@ -2503,27 +3192,33 @@ export function createBncrChannelPlugin(bridge: BncrBridgeRuntime) {
       textChunkLimit: 4000,
       sendText: bridge.channelSendText,
       sendMedia: bridge.channelSendMedia,
-      replyAction: async (ctx: any) => sendBncrReplyAction({
-        accountId: normalizeAccountId(ctx?.accountId),
-        to: asString(ctx?.to || '').trim(),
-        text: asString(ctx?.text || ''),
-        replyToMessageId: asString(ctx?.replyToId || ctx?.replyToMessageId || '').trim() || undefined,
-        sendText: async ({ accountId, to, text }) => bridge.channelSendText({ accountId, to, text }),
-      }),
-      deleteAction: async (ctx: any) => deleteBncrMessageAction({
-        accountId: normalizeAccountId(ctx?.accountId),
-        targetMessageId: asString(ctx?.messageId || ctx?.targetMessageId || '').trim(),
-      }),
-      reactAction: async (ctx: any) => reactBncrMessageAction({
-        accountId: normalizeAccountId(ctx?.accountId),
-        targetMessageId: asString(ctx?.messageId || ctx?.targetMessageId || '').trim(),
-        emoji: asString(ctx?.emoji || '').trim(),
-      }),
-      editAction: async (ctx: any) => editBncrMessageAction({
-        accountId: normalizeAccountId(ctx?.accountId),
-        targetMessageId: asString(ctx?.messageId || ctx?.targetMessageId || '').trim(),
-        text: asString(ctx?.text || ''),
-      }),
+      replyAction: async (ctx: any) =>
+        sendBncrReplyAction({
+          accountId: normalizeAccountId(ctx?.accountId),
+          to: asString(ctx?.to || '').trim(),
+          text: asString(ctx?.text || ''),
+          replyToMessageId:
+            asString(ctx?.replyToId || ctx?.replyToMessageId || '').trim() || undefined,
+          sendText: async ({ accountId, to, text }) =>
+            bridge.channelSendText({ accountId, to, text }),
+        }),
+      deleteAction: async (ctx: any) =>
+        deleteBncrMessageAction({
+          accountId: normalizeAccountId(ctx?.accountId),
+          targetMessageId: asString(ctx?.messageId || ctx?.targetMessageId || '').trim(),
+        }),
+      reactAction: async (ctx: any) =>
+        reactBncrMessageAction({
+          accountId: normalizeAccountId(ctx?.accountId),
+          targetMessageId: asString(ctx?.messageId || ctx?.targetMessageId || '').trim(),
+          emoji: asString(ctx?.emoji || '').trim(),
+        }),
+      editAction: async (ctx: any) =>
+        editBncrMessageAction({
+          accountId: normalizeAccountId(ctx?.accountId),
+          targetMessageId: asString(ctx?.messageId || ctx?.targetMessageId || '').trim(),
+          text: asString(ctx?.text || ''),
+        }),
     },
     status: {
       defaultRuntime: createDefaultChannelRuntimeState(BNCR_DEFAULT_ACCOUNT_ID, {
@@ -2550,9 +3245,7 @@ export function createBncrChannelPlugin(bridge: BncrBridgeRuntime) {
         const lastOutboundAgo = rt?.lastOutboundAgo ?? meta.lastOutboundAgo ?? '-';
         const diagnostics = rt?.diagnostics ?? meta.diagnostics ?? null;
         // 右侧状态字段统一：离线时也显示 Status（避免出现 configured 文案）
-        const normalizedMode = rt?.mode === 'linked'
-          ? 'linked'
-          : 'Status';
+        const normalizedMode = rt?.mode === 'linked' ? 'linked' : 'Status';
 
         const displayName = resolveDefaultDisplayName(account?.name, account?.accountId);