@xmoxmo/bncr 0.2.2 → 0.2.4

package/src/channel.ts

@@ -83,6 +83,8 @@ const RECENT_INBOUND_SEND_WINDOW_MS = 60_000;
 const MAX_RETRY = 10;
 const PUSH_DRAIN_INTERVAL_MS = 500;
 const PUSH_ACK_TIMEOUT_MS = 30_000;
+const OUTBOUND_READY_TTL_MS = 30_000;
+const PREFERRED_OUTBOUND_TTL_MS = 12_000;
 const FILE_FORCE_CHUNK = true; // 统一走 WS 分块，保留 base64 仅作兜底
 const FILE_INLINE_THRESHOLD = 5 * 1024 * 1024; // fallback 阈值（仅 FILE_FORCE_CHUNK=false 时生效）
 const FILE_CHUNK_SIZE = 256 * 1024; // 256KB
@@ -135,6 +137,12 @@ type FileRecvTransferState = {
   error?: string;
 };
 
+type FileAckPayloadState = {
+  payload: Record<string, unknown>;
+  ok: boolean;
+  at: number;
+};
+
 type ChatType = 'direct' | 'group' | (string & {});
 
 type ChannelMessageActionAdapter = {
@@ -190,6 +198,99 @@ type PersistedState = {
   } | null;
 };
 
+type NormalizedBncrSendParams = {
+  to: string;
+  accountId: string;
+  message: string;
+  caption: string;
+  mediaUrl?: string;
+  asVoice: boolean;
+  audioAsVoice: boolean;
+};
+
+function normalizeBncrSendParams(input: {
+  params: unknown;
+  accountId: string;
+}): NormalizedBncrSendParams {
+  const paramsObj = isPlainObject(input.params) ? input.params : {};
+  const to = readStringParam(paramsObj, 'to', { required: true });
+  const resolvedAccountId = normalizeAccountId(
+    readStringParam(paramsObj, 'accountId') ?? input.accountId,
+  );
+
+  const message = readStringParam(paramsObj, 'message', { allowEmpty: true }) ?? '';
+  const caption = readStringParam(paramsObj, 'caption', { allowEmpty: true }) ?? '';
+  const mediaUrl =
+    readStringParam(paramsObj, 'media', { trim: false }) ??
+    readStringParam(paramsObj, 'path', { trim: false }) ??
+    readStringParam(paramsObj, 'filePath', { trim: false }) ??
+    readStringParam(paramsObj, 'mediaUrl', { trim: false });
+  const asVoice = readBooleanParam(paramsObj, 'asVoice') ?? false;
+  const audioAsVoice = readBooleanParam(paramsObj, 'audioAsVoice') ?? false;
+
+  if (asVoice && !mediaUrl) throw new Error('send voice requires media path');
+
+  const normalizedMessage = mediaUrl ? '' : message || caption || '';
+  const normalizedCaption = mediaUrl ? caption || message || '' : '';
+
+  if (!normalizedMessage.trim() && !normalizedCaption.trim() && !mediaUrl) {
+    throw new Error('send requires message or media');
+  }
+
+  return {
+    to,
+    accountId: resolvedAccountId,
+    message: normalizedMessage,
+    caption: normalizedCaption,
+    mediaUrl: mediaUrl || undefined,
+    asVoice,
+    audioAsVoice,
+  };
+}
+
+type MediaDedupeCacheEntry = {
+  mediaUrl: string;
+  text: string;
+  replyToId: string;
+  createdAt: number;
+};
+
+function normalizeReplyToId(value: unknown): string {
+  return asString(value || '').trim();
+}
+
+function normalizeMessageText(value: unknown): string {
+  return asString(value || '').trim();
+}
+
+function shouldTreatReplyToAsSame(currentReplyToId: string, previousReplyToId: string): boolean {
+  if (!currentReplyToId || !previousReplyToId) return true;
+  return currentReplyToId === previousReplyToId;
+}
+
+function buildMediaTextFallback(params: {
+  currentText: string;
+  previousText: string;
+  currentReplyToId: string;
+  previousReplyToId: string;
+}): { text: string; reason: 'same-text-sent-checkmark' | 'text-changed-downgrade' } | null {
+  if (!shouldTreatReplyToAsSame(params.currentReplyToId, params.previousReplyToId)) {
+    return null;
+  }
+
+  if (params.currentText && params.currentText !== params.previousText) {
+    return {
+      text: params.currentText,
+      reason: 'text-changed-downgrade',
+    };
+  }
+
+  return {
+    text: '✅已发送',
+    reason: 'same-text-sent-checkmark',
+  };
+}
+
 function now() {
   return Date.now();
 }
@@ -200,6 +301,10 @@ function asString(v: unknown, fallback = ''): string {
   return String(v);
 }
 
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
 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));
@@ -273,6 +378,7 @@ class BncrBridgeRuntime {
   private api: OpenClawPluginApi;
   private statePath: string | null = null;
   private bridgeId = `${process.pid}-${Math.random().toString(16).slice(2, 8)}`;
+  private recentMediaDedupeBySession = new Map<string, Map<string, MediaDedupeCacheEntry>>();
   private gatewayPid = process.pid;
   private registerCount = 0;
   private apiGeneration = 0;
@@ -349,6 +455,8 @@ class BncrBridgeRuntime {
   private lastActivityByAccount = new Map<string, number>();
   private lastInboundByAccount = new Map<string, number>();
   private lastOutboundByAccount = new Map<string, number>();
+  private channelAccountTimers = new Map<string, NodeJS.Timeout>();
+  private logDedupeState = new Map<string, { at: number; sig: string }>();
   private canonicalAgentId: string | null = null;
   private canonicalAgentSource: 'startup' | 'runtime' | 'fallback-main' | null = null;
   private canonicalAgentResolvedAt: number | null = null;
@@ -383,6 +491,7 @@ class BncrBridgeRuntime {
       timer: NodeJS.Timeout;
     }
   >();
+  private earlyFileAcks = new Map<string, FileAckPayloadState>();
 
   constructor(api: OpenClawPluginApi) {
     this.api = api;
@@ -408,6 +517,102 @@ class BncrBridgeRuntime {
     emitBncrLog('error', scope, message, options, () => this.isDebugEnabled());
   }
 
+  private buildDebugJsonMessage(event: string, payload: Record<string, unknown>) {
+    return `${event} ${JSON.stringify(payload)}`;
+  }
+
+  private logInfoJson(
+    scope: string | undefined,
+    event: string,
+    payload: Record<string, unknown>,
+    options?: { debugOnly?: boolean },
+  ) {
+    this.logInfo(scope, this.buildDebugJsonMessage(event, payload), options);
+  }
+
+  private logWarnJson(
+    scope: string | undefined,
+    event: string,
+    payload: Record<string, unknown>,
+    options?: { debugOnly?: boolean },
+  ) {
+    this.logWarn(scope, this.buildDebugJsonMessage(event, payload), options);
+  }
+
+  private logErrorJson(
+    scope: string | undefined,
+    event: string,
+    payload: Record<string, unknown>,
+    options?: { debugOnly?: boolean },
+  ) {
+    this.logError(scope, this.buildDebugJsonMessage(event, payload), options);
+  }
+
+  private shouldEmitDedupLog(key: string, sig: string, windowMs = 5 * 60 * 1000) {
+    const t = now();
+    const prev = this.logDedupeState.get(key) || null;
+    if (prev && prev.sig === sig && t - prev.at < windowMs) return false;
+    this.logDedupeState.set(key, { at: t, sig });
+    return true;
+  }
+
+  private logInfoDedup(
+    scope: string | undefined,
+    message: string,
+    options: { key: string; sig: string; debugOnly?: boolean; windowMs?: number },
+  ) {
+    if (!this.shouldEmitDedupLog(options.key, options.sig, options.windowMs)) return;
+    this.logInfo(scope, message, { debugOnly: options.debugOnly });
+  }
+
+  private logWarnDedup(
+    scope: string | undefined,
+    message: string,
+    options: { key: string; sig: string; debugOnly?: boolean; windowMs?: number },
+  ) {
+    if (!this.shouldEmitDedupLog(options.key, options.sig, options.windowMs)) return;
+    this.logWarn(scope, message, { debugOnly: options.debugOnly });
+  }
+
+  private logErrorDedup(
+    scope: string | undefined,
+    message: string,
+    options: { key: string; sig: string; debugOnly?: boolean; windowMs?: number },
+  ) {
+    if (!this.shouldEmitDedupLog(options.key, options.sig, options.windowMs)) return;
+    this.logError(scope, message, { debugOnly: options.debugOnly });
+  }
+
+  private logInfoDedupJson(
+    scope: string | undefined,
+    event: string,
+    payload: Record<string, unknown>,
+    options: { key: string; sig: string; debugOnly?: boolean; windowMs?: number },
+  ) {
+    if (!this.shouldEmitDedupLog(options.key, options.sig, options.windowMs)) return;
+    this.logInfoJson(scope, event, payload, { debugOnly: options.debugOnly });
+  }
+
+  private logWarnDedupJson(
+    scope: string | undefined,
+    event: string,
+    payload: Record<string, unknown>,
+    options: { key: string; sig: string; debugOnly?: boolean; windowMs?: number },
+  ) {
+    if (!this.shouldEmitDedupLog(options.key, options.sig, options.windowMs)) return;
+    this.logWarnJson(scope, event, payload, { debugOnly: options.debugOnly });
+  }
+
+  private logErrorDedupJson(
+    scope: string | undefined,
+    event: string,
+    payload: Record<string, unknown>,
+    options: { key: string; sig: string; debugOnly?: boolean; windowMs?: number },
+  ) {
+    if (!this.shouldEmitDedupLog(options.key, options.sig, options.windowMs)) return;
+    this.logErrorJson(scope, event, payload, { debugOnly: options.debugOnly });
+  }
+
   private summarizeTextPreview(raw: string, limit = 8) {
     const compact = asString(raw || '')
       .replace(/\s+/g, ' ')
@@ -441,6 +646,19 @@ class BncrBridgeRuntime {
     this.logInfo('outbound', [type, this.summarizeScope(entry.route), preview].join('|'));
   }
 
+  private clearChannelAccountWorker(accountId: string, reason: string) {
+    const timer = this.channelAccountTimers.get(accountId);
+    if (!timer) return false;
+    clearInterval(timer);
+    this.channelAccountTimers.delete(accountId);
+    this.logInfo(
+      'health',
+      `status-worker cleared ${JSON.stringify({ bridge: this.bridgeId, accountId, reason })}`,
+      { debugOnly: true },
+    );
+    return true;
+  }
+
   private classifyRegisterTrace(stack: string) {
     if (
       stack.includes('prepareSecretsRuntimeSnapshot') ||
@@ -715,7 +933,8 @@ class BncrBridgeRuntime {
   }
 
   private buildExtendedDiagnostics(accountId: string) {
-    const diagnostics = this.buildIntegratedDiagnostics(accountId) as Record<string, any>;
+    const acc = normalizeAccountId(accountId);
+    const diagnostics = this.buildIntegratedDiagnostics(acc) as Record<string, any>;
     return {
       ...diagnostics,
       register: {
@@ -735,7 +954,7 @@ class BncrBridgeRuntime {
         lastDriftSnapshot: this.lastDriftSnapshot,
       },
       connection: {
-        active: this.activeConnectionCount(accountId),
+        active: this.activeConnectionCount(acc),
         primaryLeaseId: this.primaryLeaseId,
         primaryEpoch: this.connectionEpoch || null,
         acceptedConnections: this.acceptedConnections,
@@ -821,6 +1040,7 @@ class BncrBridgeRuntime {
       clearTimeout(waiter.timer);
     }
     this.fileAckWaiters.clear();
+    this.earlyFileAcks.clear();
   }
 
   private scheduleSave() {
@@ -1262,11 +1482,92 @@ class BncrBridgeRuntime {
     const acc = normalizeAccountId(accountId);
     const t = now();
     const primaryKey = this.activeConnectionByAccount.get(acc);
-    if (!primaryKey) return null;
-    const primary = this.connections.get(primaryKey);
-    if (!primary?.connId) return null;
-    if (t - primary.lastSeenAt > CONNECT_TTL_MS) return null;
-    return primary;
+    const primary = primaryKey ? this.connections.get(primaryKey) : null;
+
+    const isEligible = (conn: BncrConnection | null | undefined): conn is BncrConnection & {
+      outboundReadyUntil?: number;
+      preferredForOutboundUntil?: number;
+      inboundOnly?: boolean;
+    } => {
+      if (!conn?.connId) return false;
+      if (t - conn.lastSeenAt > CONNECT_TTL_MS) return false;
+      if ((conn as any).inboundOnly === true) return false;
+      return true;
+    };
+
+    const recentInboundConnIds = this.resolveRecentInboundConnIds(acc);
+    const candidateScore = (conn: BncrConnection) => {
+      const preferredForOutboundUntil = Number((conn as any).preferredForOutboundUntil || 0);
+      const outboundReadyUntil = Number((conn as any).outboundReadyUntil || 0);
+      const lastPushTimeoutAt = Number((conn as any).lastPushTimeoutAt || 0);
+      const lastAckOkAt = Number((conn as any).lastAckOkAt || 0);
+      const pushFailureScore = Number((conn as any).pushFailureScore || 0);
+      const recentTimeoutPenalty = lastPushTimeoutAt > 0 && t - lastPushTimeoutAt <= 30_000 ? 1 : 0;
+      return {
+        preferred: preferredForOutboundUntil > t ? 1 : 0,
+        ready: outboundReadyUntil > t ? 1 : 0,
+        recentInbound: recentInboundConnIds.has(conn.connId) ? 1 : 0,
+        recentTimeoutPenalty,
+        pushFailureScore,
+        lastAckOkAt,
+        lastPushTimeoutAt,
+        lastSeenAt: conn.lastSeenAt,
+        connectedAt: conn.connectedAt,
+      };
+    };
+
+    if (isEligible(primary)) {
+      const score = candidateScore(primary);
+      if (score.preferred || score.ready) return primary;
+    }
+
+    const candidates = Array.from(this.connections.values())
+      .filter((c): c is BncrConnection => c.accountId === acc)
+      .filter((c) => isEligible(c))
+      .sort((a, b) => {
+        const sa = candidateScore(a);
+        const sb = candidateScore(b);
+        if (sb.preferred !== sa.preferred) return sb.preferred - sa.preferred;
+        if (sb.ready !== sa.ready) return sb.ready - sa.ready;
+        if (sa.recentTimeoutPenalty !== sb.recentTimeoutPenalty) return sa.recentTimeoutPenalty - sb.recentTimeoutPenalty;
+        if (sa.pushFailureScore !== sb.pushFailureScore) return sa.pushFailureScore - sb.pushFailureScore;
+        if (sb.lastAckOkAt !== sa.lastAckOkAt) return sb.lastAckOkAt - sa.lastAckOkAt;
+        if (sa.lastPushTimeoutAt !== sb.lastPushTimeoutAt) return sa.lastPushTimeoutAt - sb.lastPushTimeoutAt;
+        if (sb.recentInbound !== sa.recentInbound) return sb.recentInbound - sa.recentInbound;
+        if (sb.lastSeenAt !== sa.lastSeenAt) return sb.lastSeenAt - sa.lastSeenAt;
+        return sb.connectedAt - sa.connectedAt;
+      });
+
+    const next = candidates[0] || null;
+    if (!next) return null;
+
+    const nextKey = this.connectionKey(acc, next.clientId);
+    if (primaryKey !== nextKey) {
+      this.activeConnectionByAccount.set(acc, nextKey);
+      this.logInfo(
+        'connection',
+        `owner:promote ${JSON.stringify({
+          bridge: this.bridgeId,
+          accountId: acc,
+          previousActiveKey: primaryKey || null,
+          previousActiveConn: primary || null,
+          nextActiveKey: nextKey,
+          nextActiveConn: {
+            connId: next.connId,
+            clientId: next.clientId,
+            connectedAt: next.connectedAt,
+            lastSeenAt: next.lastSeenAt,
+            outboundReadyUntil: (next as any).outboundReadyUntil || null,
+            preferredForOutboundUntil: (next as any).preferredForOutboundUntil || null,
+            inboundOnly: (next as any).inboundOnly === true,
+          },
+          reason: 'better-outbound-candidate',
+        })}`,
+        { debugOnly: true },
+      );
+    }
+
+    return next;
   }
 
   private resolvePushConnIds(accountId: string): Set<string> {
@@ -1274,14 +1575,67 @@ class BncrBridgeRuntime {
     const t = now();
     const connIds = new Set<string>();
 
+    const isEligible = (conn: BncrConnection | null | undefined): conn is BncrConnection & {
+      outboundReadyUntil?: number;
+      preferredForOutboundUntil?: number;
+      inboundOnly?: boolean;
+    } => {
+      if (!conn?.connId) return false;
+      if (t - conn.lastSeenAt > CONNECT_TTL_MS) return false;
+      if ((conn as any).inboundOnly === true) return false;
+      return true;
+    };
+
+    const recentInboundConnIds = this.resolveRecentInboundConnIds(acc);
+    const candidateScore = (conn: BncrConnection) => {
+      const preferredForOutboundUntil = Number((conn as any).preferredForOutboundUntil || 0);
+      const outboundReadyUntil = Number((conn as any).outboundReadyUntil || 0);
+      const lastPushTimeoutAt = Number((conn as any).lastPushTimeoutAt || 0);
+      const lastAckOkAt = Number((conn as any).lastAckOkAt || 0);
+      const pushFailureScore = Number((conn as any).pushFailureScore || 0);
+      const recentTimeoutPenalty = lastPushTimeoutAt > 0 && t - lastPushTimeoutAt <= 30_000 ? 1 : 0;
+      return {
+        preferred: preferredForOutboundUntil > t ? 1 : 0,
+        ready: outboundReadyUntil > t ? 1 : 0,
+        recentInbound: recentInboundConnIds.has(conn.connId) ? 1 : 0,
+        recentTimeoutPenalty,
+        pushFailureScore,
+        lastAckOkAt,
+        lastPushTimeoutAt,
+        lastSeenAt: conn.lastSeenAt,
+        connectedAt: conn.connectedAt,
+      };
+    };
+
     const primaryKey = this.activeConnectionByAccount.get(acc);
     if (primaryKey) {
       const primary = this.connections.get(primaryKey);
-      if (primary?.connId && t - primary.lastSeenAt <= CONNECT_TTL_MS) {
+      if (isEligible(primary)) {
         connIds.add(primary.connId);
       }
     }
 
+    const candidates = Array.from(this.connections.values())
+      .filter((c): c is BncrConnection => c.accountId === acc)
+      .filter((c) => isEligible(c))
+      .sort((a, b) => {
+        const sa = candidateScore(a);
+        const sb = candidateScore(b);
+        if (sb.preferred !== sa.preferred) return sb.preferred - sa.preferred;
+        if (sb.ready !== sa.ready) return sb.ready - sa.ready;
+        if (sa.recentTimeoutPenalty !== sb.recentTimeoutPenalty) return sa.recentTimeoutPenalty - sb.recentTimeoutPenalty;
+        if (sa.pushFailureScore !== sb.pushFailureScore) return sa.pushFailureScore - sb.pushFailureScore;
+        if (sb.lastAckOkAt !== sa.lastAckOkAt) return sb.lastAckOkAt - sa.lastAckOkAt;
+        if (sa.lastPushTimeoutAt !== sb.lastPushTimeoutAt) return sa.lastPushTimeoutAt - sb.lastPushTimeoutAt;
+        if (sb.recentInbound !== sa.recentInbound) return sb.recentInbound - sa.recentInbound;
+        if (sb.lastSeenAt !== sa.lastSeenAt) return sb.lastSeenAt - sa.lastSeenAt;
+        return sb.connectedAt - sa.connectedAt;
+      });
+
+    for (const c of candidates) {
+      connIds.add(c.connId);
+    }
+
     if (connIds.size > 0) return connIds;
 
     for (const c of this.connections.values()) {
@@ -1319,7 +1673,480 @@ class BncrBridgeRuntime {
     return connIds;
   }
 
-  private tryPushEntry(entry: OutboxEntry): boolean {
+  private isRecentlyReachableConn(accountId: string, connId?: string, clientId?: string): boolean {
+    const acc = normalizeAccountId(accountId);
+    const cid = asString(connId || '').trim();
+    const client = asString(clientId || '').trim() || undefined;
+    if (!cid) return false;
+
+    const recentConnIds = this.resolveRecentInboundConnIds(acc);
+    if (recentConnIds.has(cid)) return true;
+
+    const activeKey = this.activeConnectionByAccount.get(acc);
+    if (!activeKey) return false;
+    const active = this.connections.get(activeKey);
+    if (!active?.connId) return false;
+    if (active.connId !== cid) return false;
+    if (client && active.clientId && active.clientId !== client) return false;
+    return true;
+  }
+
+  private isRevalidatedAttemptedConn(entry: OutboxEntry, connId: string): boolean {
+    const targetConnId = asString(connId || '').trim();
+    if (!targetConnId) return false;
+
+    const acc = normalizeAccountId(entry.accountId);
+    const t = now();
+    const lastAttemptAt = Number(entry.lastAttemptAt || 0);
+    const recentInboundReachable = this.hasRecentInboundReachability(acc);
+
+    for (const conn of this.connections.values()) {
+      if (conn.accountId !== acc) continue;
+      if (conn.connId !== targetConnId) continue;
+      if (t - conn.lastSeenAt > CONNECT_TTL_MS) continue;
+      if ((conn as any).inboundOnly === true) continue;
+
+      const preferredForOutboundUntil = Number((conn as any).preferredForOutboundUntil || 0);
+      const outboundReadyUntil = Number((conn as any).outboundReadyUntil || 0);
+      const lastAckOkAt = Number((conn as any).lastAckOkAt || 0);
+      const lastPushTimeoutAt = Number((conn as any).lastPushTimeoutAt || 0);
+
+      const revalidatedByPreferred = preferredForOutboundUntil > t;
+      const revalidatedByReady = outboundReadyUntil > t;
+      const revalidatedByAck = lastAckOkAt > 0 && lastAckOkAt > lastAttemptAt;
+      const revalidatedByFreshReachability =
+        recentInboundReachable &&
+        lastPushTimeoutAt > 0 &&
+        lastPushTimeoutAt <= lastAttemptAt &&
+        conn.lastSeenAt > lastPushTimeoutAt;
+
+      const revalidated =
+        revalidatedByPreferred ||
+        revalidatedByReady ||
+        revalidatedByAck ||
+        revalidatedByFreshReachability;
+
+      if (revalidated) {
+        this.logInfo(
+          'outbox',
+          `revalidated-retry ${JSON.stringify({
+            messageId: entry.messageId,
+            accountId: acc,
+            connId: targetConnId,
+            reason: revalidatedByAck
+              ? 'ack-after-last-attempt'
+              : revalidatedByPreferred
+                ? 'preferred-ttl'
+                : revalidatedByReady
+                  ? 'ready-ttl'
+                  : 'fresh-reachability',
+            lastAttemptAt,
+            lastAckOkAt: lastAckOkAt || null,
+            lastPushTimeoutAt: lastPushTimeoutAt || null,
+            outboundReadyUntil: outboundReadyUntil || null,
+            preferredForOutboundUntil: preferredForOutboundUntil || null,
+            lastSeenAt: conn.lastSeenAt,
+            recentInboundReachable,
+          })}`,
+          { debugOnly: true },
+        );
+      }
+
+      return revalidated;
+    }
+
+    return false;
+  }
+
+  private tryAdoptTransferOwner(args: {
+    accountId: string;
+    transfer:
+      | FileSendTransferState
+      | FileRecvTransferState
+      | undefined;
+    connId: string;
+    clientId?: string;
+  }): boolean {
+    const { accountId, transfer, connId, clientId } = args;
+    if (!transfer) return false;
+    if (!this.hasRecentInboundReachability(accountId)) return false;
+    if (!this.isRecentlyReachableConn(accountId, connId, clientId)) return false;
+
+    transfer.ownerConnId = connId;
+    transfer.ownerClientId = asString(clientId || '').trim() || undefined;
+    return true;
+  }
+
+  private isRetryableFileTransferError(error: unknown): boolean {
+    const msg = asString((error as any)?.message || error || '')
+      .trim()
+      .toLowerCase();
+    if (!msg) return true;
+
+    const retryableMarkers = [
+      'gateway context unavailable',
+      'no active bncr client for file chunk transfer',
+      'chunk ack timeout',
+      'complete ack timeout',
+      'transfer state missing',
+      'transfer aborted',
+      'temporarily unavailable',
+      'timeout',
+      'econn',
+      'socket',
+      'network',
+    ];
+
+    return retryableMarkers.some((marker) => msg.includes(marker));
+  }
+
+  private buildFileTransferOutboxEntry(params: {
+    accountId: string;
+    sessionKey: string;
+    route: BncrRoute;
+    mediaUrl: string;
+    mediaLocalRoots?: readonly string[];
+    text?: string;
+    asVoice?: boolean;
+    audioAsVoice?: boolean;
+    kind?: 'tool' | 'block' | 'final';
+    replyToId?: string;
+  }): OutboxEntry {
+    const messageId = randomUUID();
+    return {
+      messageId,
+      accountId: normalizeAccountId(params.accountId),
+      sessionKey: params.sessionKey,
+      route: params.route,
+      payload: {
+        type: 'message.outbound',
+        sessionKey: params.sessionKey,
+        _meta: {
+          kind: 'file-transfer',
+          mediaUrl: params.mediaUrl,
+          mediaLocalRoots: params.mediaLocalRoots ? Array.from(params.mediaLocalRoots) : undefined,
+          text: asString(params.text || ''),
+          asVoice: params.asVoice === true,
+          audioAsVoice: params.audioAsVoice === true,
+          finalEvent: BNCR_PUSH_EVENT,
+          replyToId: asString(params.replyToId || '').trim() || undefined,
+          messageKind: params.kind,
+        },
+      },
+      createdAt: now(),
+      retryCount: 0,
+      nextAttemptAt: now(),
+    };
+  }
+
+  private pruneMediaDedupeCache(sessionKey: string, currentTime = now()) {
+    const sessionCache = this.recentMediaDedupeBySession.get(sessionKey);
+    if (!sessionCache) return;
+
+    for (const [mediaUrl, entry] of sessionCache.entries()) {
+      if (currentTime - entry.createdAt > 10_000) {
+        sessionCache.delete(mediaUrl);
+      }
+    }
+
+    if (sessionCache.size === 0) {
+      this.recentMediaDedupeBySession.delete(sessionKey);
+    }
+  }
+
+  private rememberRecentMediaSend(params: {
+    sessionKey: string;
+    mediaUrl: string;
+    text: string;
+    replyToId: string;
+    createdAt?: number;
+  }) {
+    const sessionKey = asString(params.sessionKey || '').trim();
+    const mediaUrl = asString(params.mediaUrl || '').trim();
+    if (!sessionKey || !mediaUrl) return;
+
+    const createdAt = typeof params.createdAt === 'number' ? params.createdAt : now();
+    this.pruneMediaDedupeCache(sessionKey, createdAt);
+    let sessionCache = this.recentMediaDedupeBySession.get(sessionKey);
+    if (!sessionCache) {
+      sessionCache = new Map<string, MediaDedupeCacheEntry>();
+      this.recentMediaDedupeBySession.set(sessionKey, sessionCache);
+    }
+    sessionCache.set(mediaUrl, {
+      mediaUrl,
+      text: normalizeMessageText(params.text),
+      replyToId: normalizeReplyToId(params.replyToId),
+      createdAt,
+    });
+  }
+
+  private tryBuildMediaDedupeFallback(params: {
+    sessionKey: string;
+    mediaUrl: string;
+    text: string;
+    replyToId: string;
+    currentTime?: number;
+  }): { text: string; reason: 'same-text-sent-checkmark' | 'text-changed-downgrade' } | null {
+    const sessionKey = asString(params.sessionKey || '').trim();
+    const mediaUrl = asString(params.mediaUrl || '').trim();
+    if (!sessionKey || !mediaUrl) return null;
+
+    const currentTime = typeof params.currentTime === 'number' ? params.currentTime : now();
+    this.pruneMediaDedupeCache(sessionKey, currentTime);
+    const sessionCache = this.recentMediaDedupeBySession.get(sessionKey);
+    const previous = sessionCache?.get(mediaUrl);
+    if (!previous) return null;
+    if (currentTime - previous.createdAt > 10_000) return null;
+
+    return buildMediaTextFallback({
+      currentText: normalizeMessageText(params.text),
+      previousText: previous.text,
+      currentReplyToId: normalizeReplyToId(params.replyToId),
+      previousReplyToId: previous.replyToId,
+    });
+  }
+
+  private buildTextOutboxEntry(params: {
+    accountId: string;
+    sessionKey: string;
+    route: BncrRoute;
+    text: string;
+    kind?: 'tool' | 'block' | 'final';
+    replyToId?: string;
+  }): OutboxEntry {
+    const messageId = randomUUID();
+    const frame = {
+      type: 'message.outbound',
+      messageId,
+      idempotencyKey: messageId,
+      sessionKey: params.sessionKey,
+      replyToId: normalizeReplyToId(params.replyToId) || undefined,
+      message: {
+        platform: params.route.platform,
+        groupId: params.route.groupId,
+        userId: params.route.userId,
+        type: 'text',
+        kind: params.kind,
+        msg: params.text,
+        path: '',
+        base64: '',
+        fileName: '',
+      },
+      ts: now(),
+    };
+
+    return {
+      messageId,
+      accountId: normalizeAccountId(params.accountId),
+      sessionKey: params.sessionKey,
+      route: params.route,
+      payload: frame,
+      createdAt: now(),
+      retryCount: 0,
+      nextAttemptAt: now(),
+    };
+  }
+
+  private async tryPushEntry(entry: OutboxEntry): Promise<boolean> {
+    const meta = isPlainObject(entry.payload?._meta) ? entry.payload._meta : null;
+    if (meta?.kind === 'file-transfer') {
+      const ctx = this.gatewayContext;
+      if (!ctx) {
+        entry.lastError = 'gateway context unavailable';
+        this.outbox.set(entry.messageId, entry);
+        this.logInfo(
+          'outbox',
+          `push-skip ${JSON.stringify({
+            messageId: entry.messageId,
+            accountId: entry.accountId,
+            kind: 'file-transfer',
+            reason: 'no-gateway-context',
+          })}`,
+          { debugOnly: true },
+        );
+        return false;
+      }
+
+      const attemptedConnIds = new Set(
+        Array.isArray(entry.routeAttemptConnIds)
+          ? entry.routeAttemptConnIds.filter((v): v is string => typeof v === 'string' && !!v)
+          : [],
+      );
+      const routeCandidates = Array.from(this.resolvePushConnIds(entry.accountId));
+      const filteredCandidates = routeCandidates.filter(
+        (connId) =>
+          !attemptedConnIds.has(connId) || this.isRevalidatedAttemptedConn(entry, connId),
+      );
+      const owner = this.resolveOutboxPushOwner(entry.accountId);
+      const ownerConnId = owner?.connId && !attemptedConnIds.has(owner.connId) ? owner.connId : undefined;
+      let connIds = ownerConnId
+        ? new Set([ownerConnId])
+        : new Set(filteredCandidates.length ? filteredCandidates : routeCandidates);
+      const recentInboundReachable = this.hasRecentInboundReachability(entry.accountId);
+      const routeReason = ownerConnId
+        ? 'owner'
+        : connIds.size > 0
+          ? filteredCandidates.length > 0
+            ? 'active-connections'
+            : 'active-connections-reused'
+          : recentInboundReachable
+            ? 'recent-inbound-fallback'
+            : 'none';
+      if (!connIds.size && recentInboundReachable) {
+        const recentInboundConnIds = Array.from(this.resolveRecentInboundConnIds(entry.accountId));
+        const filteredRecentInboundConnIds = recentInboundConnIds.filter(
+          (connId) => !attemptedConnIds.has(connId),
+        );
+        connIds = new Set(
+          filteredRecentInboundConnIds.length > 0 ? filteredRecentInboundConnIds : recentInboundConnIds,
+        );
+      }
+      if (!connIds.size) {
+        entry.lastError = 'no active bncr client for file chunk transfer';
+        this.outbox.set(entry.messageId, entry);
+        this.logInfo(
+          'outbox',
+          `push-skip ${JSON.stringify({
+            messageId: entry.messageId,
+            accountId: entry.accountId,
+            kind: 'file-transfer',
+            reason: 'no-active-connection',
+            recentInboundReachable,
+          })}`,
+          { debugOnly: true },
+        );
+        return false;
+      }
+
+      const mediaUrl = asString(meta.mediaUrl || '').trim();
+      if (!mediaUrl) {
+        entry.lastError = 'file transfer mediaUrl missing';
+        this.outbox.set(entry.messageId, entry);
+        this.logInfo(
+          'outbox',
+          `push-fail ${JSON.stringify({
+            messageId: entry.messageId,
+            accountId: entry.accountId,
+            kind: 'file-transfer',
+            error: entry.lastError,
+          })}`,
+          { debugOnly: true },
+        );
+        return false;
+      }
+
+      try {
+        const media = await this.transferMediaToBncrClient({
+          accountId: entry.accountId,
+          sessionKey: entry.sessionKey,
+          route: entry.route,
+          mediaUrl,
+          mediaLocalRoots: Array.isArray(meta.mediaLocalRoots)
+            ? meta.mediaLocalRoots.filter((v): v is string => typeof v === 'string')
+            : undefined,
+        });
+        const wantsVoice = meta.asVoice === true || meta.audioAsVoice === true;
+        const frame = buildBncrMediaOutboundFrame({
+          messageId: entry.messageId,
+          sessionKey: entry.sessionKey,
+          route: entry.route,
+          media,
+          mediaUrl,
+          mediaMsg: asString(meta.text || ''),
+          fileName: resolveOutboundFileName({
+            mediaUrl,
+            fileName: media.fileName,
+            mimeType: media.mimeType,
+          }),
+          hintedType: wantsVoice ? 'voice' : undefined,
+          kind:
+            meta.messageKind === 'tool' ||
+            meta.messageKind === 'block' ||
+            meta.messageKind === 'final'
+              ? meta.messageKind
+              : undefined,
+          replyToId: asString(meta.replyToId || '').trim() || undefined,
+          now: now(),
+        });
+
+        ctx.broadcastToConnIds(
+          BNCR_PUSH_EVENT,
+          {
+            ...frame,
+            idempotencyKey: entry.messageId,
+          },
+          connIds,
+        );
+        this.logInfo(
+          'outbox',
+          `route-select ${JSON.stringify({
+            messageId: entry.messageId,
+            accountId: entry.accountId,
+            kind: 'file-transfer',
+            routeReason,
+            connIds: Array.from(connIds),
+            ownerConnId: owner?.connId || '',
+            ownerClientId: owner?.clientId || '',
+            recentInboundReachable,
+            event: BNCR_PUSH_EVENT,
+          })}`,
+          { debugOnly: true },
+        );
+        entry.lastPushAt = now();
+        entry.lastPushConnId =
+          owner?.connId || (connIds.size === 1 ? Array.from(connIds)[0] : undefined);
+        entry.lastPushClientId = owner?.clientId;
+        if (!Array.isArray(entry.routeAttemptConnIds)) entry.routeAttemptConnIds = [];
+        if (entry.lastPushConnId && !entry.routeAttemptConnIds.includes(entry.lastPushConnId)) {
+          entry.routeAttemptConnIds.push(entry.lastPushConnId);
+        }
+        entry.lastError = undefined;
+        this.outbox.set(entry.messageId, entry);
+        this.lastOutboundByAccount.set(entry.accountId, entry.lastPushAt);
+        this.markActivity(entry.accountId, entry.lastPushAt);
+        this.scheduleSave();
+        this.logInfo('outbox push ok', `mid=${entry.messageId}|q=${this.outbox.size}`);
+        this.logInfo(
+          'outbox',
+          `push-ok ${JSON.stringify({
+            messageId: entry.messageId,
+            accountId: entry.accountId,
+            kind: 'file-transfer',
+            connIds: Array.from(connIds),
+            ownerConnId: entry.lastPushConnId || '',
+            ownerClientId: entry.lastPushClientId || '',
+            recentInboundReachable,
+            event: BNCR_PUSH_EVENT,
+          })}`,
+          { debugOnly: true },
+        );
+        return true;
+      } catch (error) {
+        entry.lastError = asString((error as any)?.message || error || 'file-transfer-error');
+        this.outbox.set(entry.messageId, entry);
+        this.scheduleSave();
+        this.logInfo(
+          'outbox push fail',
+          `mid=${entry.messageId}|q=${this.outbox.size}|err=${entry.lastError}`,
+        );
+        this.logInfo(
+          'outbox',
+          `push-fail ${JSON.stringify({
+            messageId: entry.messageId,
+            accountId: entry.accountId,
+            kind: 'file-transfer',
+            retryable: this.isRetryableFileTransferError(error),
+            error: entry.lastError,
+          })}`,
+          { debugOnly: true },
+        );
+        if (!this.isRetryableFileTransferError(error)) {
+          this.moveToDeadLetter(entry, entry.lastError || 'file-transfer-failed');
+        }
+        return false;
+      }
+    }
+
     const ctx = this.gatewayContext;
     if (!ctx) {
       this.logInfo(
@@ -1334,13 +2161,42 @@ class BncrBridgeRuntime {
       return false;
     }
 
+    const attemptedConnIds = new Set(
+      Array.isArray(entry.routeAttemptConnIds)
+        ? entry.routeAttemptConnIds.filter((v): v is string => typeof v === 'string' && !!v)
+        : [],
+    );
+    const routeCandidates = Array.from(this.resolvePushConnIds(entry.accountId));
+    const unattemptedCandidates = routeCandidates.filter((connId) => !attemptedConnIds.has(connId));
+    const revalidatedCandidates = routeCandidates.filter(
+      (connId) => attemptedConnIds.has(connId) && this.isRevalidatedAttemptedConn(entry, connId),
+    );
+    const preferredCandidates = unattemptedCandidates.length > 0 ? unattemptedCandidates : routeCandidates;
     const owner = this.resolveOutboxPushOwner(entry.accountId);
-    let connIds = owner?.connId
-      ? new Set([owner.connId])
-      : this.resolvePushConnIds(entry.accountId);
+    const ownerConnId = owner?.connId && preferredCandidates.includes(owner.connId) ? owner.connId : undefined;
+    let connIds = ownerConnId ? new Set([ownerConnId]) : new Set(preferredCandidates);
     const recentInboundReachable = this.hasRecentInboundReachability(entry.accountId);
+    const routeReason = ownerConnId
+      ? 'owner'
+      : connIds.size > 0
+        ? unattemptedCandidates.length > 0
+          ? 'active-connections-unattempted-first'
+          : revalidatedCandidates.length > 0
+            ? 'active-connections-revalidated'
+            : 'active-connections-all-visible'
+        : recentInboundReachable
+          ? 'recent-inbound-fallback'
+          : 'none';
     if (!connIds.size && recentInboundReachable) {
-      connIds = this.resolveRecentInboundConnIds(entry.accountId);
+      const recentInboundConnIds = Array.from(this.resolveRecentInboundConnIds(entry.accountId));
+      const unattemptedRecentInboundConnIds = recentInboundConnIds.filter(
+        (connId) => !attemptedConnIds.has(connId),
+      );
+      connIds = new Set(
+        unattemptedRecentInboundConnIds.length > 0
+          ? unattemptedRecentInboundConnIds
+          : recentInboundConnIds,
+      );
     }
     if (!connIds.size) {
       this.logInfo(
@@ -1363,11 +2219,30 @@ class BncrBridgeRuntime {
       };
 
       ctx.broadcastToConnIds(BNCR_PUSH_EVENT, payload, connIds);
+      this.logInfo(
+        'outbox',
+        `route-select ${JSON.stringify({
+          messageId: entry.messageId,
+          accountId: entry.accountId,
+          routeReason,
+          connIds: Array.from(connIds),
+          ownerConnId: owner?.connId || '',
+          ownerClientId: owner?.clientId || '',
+          recentInboundReachable,
+          event: BNCR_PUSH_EVENT,
+        })}`,
+        { debugOnly: true },
+      );
       entry.lastPushAt = now();
       entry.lastPushConnId =
-        owner?.connId || (connIds.size === 1 ? Array.from(connIds)[0] : undefined);
-      entry.lastPushClientId = owner?.clientId;
+        ownerConnId || (connIds.size === 1 ? Array.from(connIds)[0] : undefined);
+      entry.lastPushClientId = ownerConnId ? owner?.clientId : undefined;
+      if (!Array.isArray(entry.routeAttemptConnIds)) entry.routeAttemptConnIds = [];
+      if (entry.lastPushConnId && !entry.routeAttemptConnIds.includes(entry.lastPushConnId)) {
+        entry.routeAttemptConnIds.push(entry.lastPushConnId);
+      }
       this.outbox.set(entry.messageId, entry);
+      this.logInfo('outbox push ok', `mid=${entry.messageId}|q=${this.outbox.size}`);
       this.logInfo(
         'outbox',
         `push-ok ${JSON.stringify({
@@ -1388,6 +2263,7 @@ class BncrBridgeRuntime {
     } catch (error) {
       entry.lastError = asString((error as any)?.message || error || 'push-error');
       this.outbox.set(entry.messageId, entry);
+      this.logInfo('outbox push fail', `mid=${entry.messageId}|q=${this.outbox.size}|err=${entry.lastError}`);
       this.logInfo(
         'outbox',
         `push-fail ${JSON.stringify({
@@ -1406,7 +2282,7 @@ class BncrBridgeRuntime {
     const delay = Math.max(0, Math.min(Number(delayMs || 0), 30_000));
     this.pushTimer = setTimeout(() => {
       this.pushTimer = null;
-      void this.flushPushQueue();
+      void this.flushPushQueue({ trigger: 'timer', reason: 'scheduled-drain' });
     }, delay);
   }
 
@@ -1446,8 +2322,14 @@ class BncrBridgeRuntime {
     };
   }
 
-  private async flushPushQueue(accountId?: string): Promise<void> {
-    const filterAcc = accountId ? normalizeAccountId(accountId) : null;
+  private async flushPushQueue(args?: {
+    accountId?: string;
+    trigger?: string;
+    reason?: string;
+  }): Promise<void> {
+    const filterAcc = args?.accountId ? normalizeAccountId(args.accountId) : null;
+    const trigger = asString(args?.trigger || '').trim() || 'manual';
+    const reason = asString(args?.reason || '').trim() || undefined;
     const targetAccounts = filterAcc
       ? [filterAcc]
       : Array.from(
@@ -1462,6 +2344,8 @@ class BncrBridgeRuntime {
         accountId: filterAcc,
         targetAccounts,
         outboxSize: this.outbox.size,
+        trigger,
+        reason,
       })}`,
       { debugOnly: true },
     );
@@ -1507,8 +2391,9 @@ class BncrBridgeRuntime {
             break;
           }
 
-          const onlineNow = this.isOnline(acc) || this.hasRecentInboundReachability(acc);
-          const pushed = this.tryPushEntry(entry);
+          const onlineNow = this.isOnline(acc);
+          const recentInboundReachable = this.hasRecentInboundReachability(acc);
+          const pushed = await this.tryPushEntry(entry);
           if (pushed) {
             const requireAck = this.isOutboundAckRequired(acc);
             let ackResult: 'acked' | 'timeout' = requireAck ? 'timeout' : 'acked';
@@ -1524,6 +2409,7 @@ class BncrBridgeRuntime {
                 requireAck,
                 ackResult,
                 onlineNow,
+                recentInboundReachable,
               })}`,
               { debugOnly: true },
             );
@@ -1538,19 +2424,72 @@ class BncrBridgeRuntime {
               continue;
             }
 
+            if (entry.lastPushConnId || entry.lastPushClientId) {
+              this.degradeOutboundCapability({
+                accountId: acc,
+                connId: entry.lastPushConnId || undefined,
+                clientId: entry.lastPushClientId || undefined,
+                reason: requireAck ? 'ack-timeout' : 'push-unconfirmed',
+              });
+            }
+
+            const attemptedConnIds = Array.isArray(entry.routeAttemptConnIds)
+              ? entry.routeAttemptConnIds.filter((v): v is string => typeof v === 'string' && !!v)
+              : [];
+            const currentConnId = asString(entry.lastPushConnId || '').trim();
+            if (currentConnId && !attemptedConnIds.includes(currentConnId)) attemptedConnIds.push(currentConnId);
+            const availableConnIds = Array.from(this.resolvePushConnIds(acc));
+            const revalidatedConnIds = attemptedConnIds.filter((connId) =>
+              this.isRevalidatedAttemptedConn(entry, connId),
+            );
+            const hasUntriedAlternative = availableConnIds.some((connId) => !attemptedConnIds.includes(connId));
+            const shouldFastReroute = requireAck && entry.fastReroutePending !== true && hasUntriedAlternative;
+
+            entry.routeAttemptConnIds = attemptedConnIds;
+            if (shouldFastReroute) entry.fastReroutePending = true;
+
             entry.retryCount += 1;
             entry.lastAttemptAt = now();
             if (entry.retryCount > MAX_RETRY) {
+              this.logInfo(
+                'outbox ack fatal',
+                `mid=${entry.messageId}|q=${this.outbox.size}|err=${entry.lastError || (requireAck ? 'push-ack-timeout' : 'push-delivery-unconfirmed')}`,
+              );
               this.moveToDeadLetter(
                 entry,
                 entry.lastError || (requireAck ? 'push-ack-timeout' : 'push-delivery-unconfirmed'),
               );
               continue;
             }
-            entry.nextAttemptAt = now() + backoffMs(entry.retryCount);
+            entry.nextAttemptAt = shouldFastReroute ? now() + 1_000 : now() + backoffMs(entry.retryCount);
             entry.lastError = requireAck ? 'push-ack-timeout' : 'push-delivery-unconfirmed';
+            if (!hasUntriedAlternative) {
+              entry.routeAttemptConnIds = [];
+              entry.routeAttemptRound = Number(entry.routeAttemptRound || 0) + 1;
+              entry.fastReroutePending = false;
+            }
             this.outbox.set(entry.messageId, entry);
             this.scheduleSave();
+            this.logInfo(
+              requireAck ? 'outbox ack timeout' : 'outbox ack retry',
+              `mid=${entry.messageId}|q=${this.outbox.size}${requireAck ? '' : `|err=${entry.lastError}`}`,
+            );
+            this.logInfo(
+              'outbox',
+              `retry-reroute ${JSON.stringify({
+                messageId: entry.messageId,
+                accountId: acc,
+                currentConnId,
+                attemptedConnIds,
+                availableConnIds,
+                revalidatedConnIds,
+                hasUntriedAlternative,
+                shouldFastReroute,
+                routeAttemptRound: entry.routeAttemptRound || 0,
+                nextAttemptAt: entry.nextAttemptAt,
+              })}`,
+              { debugOnly: true },
+            );
 
             const wait = Math.max(0, entry.nextAttemptAt - now());
             localNextDelay = localNextDelay == null ? wait : Math.min(localNextDelay, wait);
@@ -1558,6 +2497,11 @@ class BncrBridgeRuntime {
             break;
           }
 
+          if (!this.outbox.has(entry.messageId)) {
+            await this.sleepMs(PUSH_DRAIN_INTERVAL_MS);
+            continue;
+          }
+
           const nextAttempt = entry.retryCount + 1;
           if (nextAttempt > MAX_RETRY) {
             this.moveToDeadLetter(entry, entry.lastError || 'push-retry-limit');
@@ -1650,6 +2594,9 @@ class BncrBridgeRuntime {
     for (const [id, st] of this.fileRecvTransfers.entries()) {
       if (t - st.startedAt > FILE_TRANSFER_KEEP_MS) this.fileRecvTransfers.delete(id);
     }
+    for (const [key, ack] of this.earlyFileAcks.entries()) {
+      if (t - ack.at > FILE_TRANSFER_ACK_TTL_MS) this.earlyFileAcks.delete(key);
+    }
   }
 
   private markSeen(accountId: string, connId: string, clientId?: string) {
@@ -1659,43 +2606,283 @@ class BncrBridgeRuntime {
     const key = this.connectionKey(acc, clientId);
     const t = now();
     const prev = this.connections.get(key);
+    const previousActiveKey = this.activeConnectionByAccount.get(acc) || null;
+    const previousActiveConn = previousActiveKey ? this.connections.get(previousActiveKey) || null : null;
 
-    const nextConn: BncrConnection = {
+    const nextConn = {
       accountId: acc,
       connId,
       clientId: asString(clientId || '').trim() || undefined,
       connectedAt: prev?.connectedAt || t,
       lastSeenAt: t,
+      outboundReadyUntil: (prev as any)?.outboundReadyUntil,
+      preferredForOutboundUntil: (prev as any)?.preferredForOutboundUntil,
+      inboundOnly: (prev as any)?.inboundOnly,
+    } as BncrConnection & {
+      outboundReadyUntil?: number;
+      preferredForOutboundUntil?: number;
+      inboundOnly?: boolean;
+    };
+
+    this.connections.set(key, nextConn as BncrConnection);
+    const connectionSeenPayload = {
+      bridge: this.bridgeId,
+      accountId: acc,
+      connId,
+      clientId: nextConn.clientId,
+      connectedAt: nextConn.connectedAt,
+      lastSeenAt: nextConn.lastSeenAt,
+      outboundReadyUntil: nextConn.outboundReadyUntil || null,
+      preferredForOutboundUntil: nextConn.preferredForOutboundUntil || null,
+      inboundOnly: nextConn.inboundOnly === true,
+    };
+    const connectionSeenSig = JSON.stringify({
+      bridge: this.bridgeId,
+      accountId: acc,
+      connId,
+      clientId: nextConn.clientId || null,
+      inboundOnly: nextConn.inboundOnly === true,
+      outboundReadyActive: Number(nextConn.outboundReadyUntil || 0) > t,
+      preferredForOutboundActive: Number(nextConn.preferredForOutboundUntil || 0) > t,
+    });
+    this.logInfoDedupJson('connection', 'seen', connectionSeenPayload, {
+      key: `connection-seen:${acc}:${nextConn.clientId || connId}`,
+      sig: connectionSeenSig,
+      debugOnly: true,
+    });
+
+    const current = this.activeConnectionByAccount.get(acc);
+    if (!current) {
+      this.activeConnectionByAccount.set(acc, key);
+      this.logInfo(
+        'connection',
+        `seen:promote ${JSON.stringify({
+          bridge: this.bridgeId,
+          accountId: acc,
+          reason: 'no-current-active',
+          previousActiveKey,
+          previousActiveConn,
+          nextActiveKey: key,
+          nextActiveConn: nextConn,
+          activeConnections: Array.from(this.connections.values())
+            .filter((c) => c.accountId === acc)
+            .map((c) => ({
+              connId: c.connId,
+              clientId: c.clientId,
+              connectedAt: c.connectedAt,
+              lastSeenAt: c.lastSeenAt,
+              outboundReadyUntil: (c as any).outboundReadyUntil || null,
+              preferredForOutboundUntil: (c as any).preferredForOutboundUntil || null,
+              inboundOnly: (c as any).inboundOnly === true,
+            })),
+        })}`,
+        { debugOnly: true },
+      );
+      return;
+    }
+
+    const curConn = this.connections.get(current);
+    if (!curConn || t - curConn.lastSeenAt > CONNECT_TTL_MS) {
+      this.activeConnectionByAccount.set(acc, key);
+      this.logInfo(
+        'connection',
+        `seen:promote ${JSON.stringify({
+          bridge: this.bridgeId,
+          accountId: acc,
+          reason: !curConn ? 'current-missing' : 'current-stale',
+          previousActiveKey,
+          previousActiveConn,
+          nextActiveKey: key,
+          nextActiveConn: nextConn,
+          activeConnections: Array.from(this.connections.values())
+            .filter((c) => c.accountId === acc)
+            .map((c) => ({
+              connId: c.connId,
+              clientId: c.clientId,
+              connectedAt: c.connectedAt,
+              lastSeenAt: c.lastSeenAt,
+              outboundReadyUntil: (c as any).outboundReadyUntil || null,
+              preferredForOutboundUntil: (c as any).preferredForOutboundUntil || null,
+              inboundOnly: (c as any).inboundOnly === true,
+            })),
+        })}`,
+        { debugOnly: true },
+      );
+    }
+  }
+
+  private markOutboundCapability(args: {
+    accountId: string;
+    connId: string;
+    clientId?: string;
+    outboundReady?: boolean;
+    preferredForOutbound?: boolean;
+    inboundOnly?: boolean;
+    at?: number;
+  }) {
+    const acc = normalizeAccountId(args.accountId);
+    const key = this.connectionKey(acc, args.clientId);
+    const t = Number(args.at || now());
+    const current = this.connections.get(key) as (BncrConnection & {
+      outboundReadyUntil?: number;
+      preferredForOutboundUntil?: number;
+      inboundOnly?: boolean;
+    }) | undefined;
+    if (!current || current.connId !== args.connId) return;
+
+    if (args.inboundOnly === true) {
+      current.inboundOnly = true;
+      current.outboundReadyUntil = undefined;
+      current.preferredForOutboundUntil = undefined;
+    } else {
+      if (typeof args.inboundOnly === 'boolean') current.inboundOnly = false;
+      if (args.outboundReady === true || args.preferredForOutbound === true) {
+        current.outboundReadyUntil = t + OUTBOUND_READY_TTL_MS;
+      }
+      if (args.preferredForOutbound === true) {
+        current.preferredForOutboundUntil = t + PREFERRED_OUTBOUND_TTL_MS;
+      }
+    }
+
+    this.connections.set(key, current as BncrConnection);
+    const connectionCapabilityPayload = {
+      bridge: this.bridgeId,
+      accountId: acc,
+      connId: current.connId,
+      clientId: current.clientId,
+      outboundReady: args.outboundReady === true,
+      preferredForOutbound: args.preferredForOutbound === true,
+      inboundOnly: current.inboundOnly === true,
+      outboundReadyUntil: current.outboundReadyUntil || null,
+      preferredForOutboundUntil: current.preferredForOutboundUntil || null,
+    };
+    const connectionCapabilitySig = JSON.stringify({
+      bridge: this.bridgeId,
+      accountId: acc,
+      connId: current.connId,
+      clientId: current.clientId || null,
+      outboundReady: args.outboundReady === true,
+      preferredForOutbound: args.preferredForOutbound === true,
+      inboundOnly: current.inboundOnly === true,
+      outboundReadyActive: Number(current.outboundReadyUntil || 0) > t,
+      preferredForOutboundActive: Number(current.preferredForOutboundUntil || 0) > t,
+    });
+    this.logInfoDedupJson('connection', 'capability', connectionCapabilityPayload, {
+      key: `connection-capability:${acc}:${current.clientId || current.connId}`,
+      sig: connectionCapabilitySig,
+      debugOnly: true,
+    });
+  }
+
+  private hasAlternativeLiveConnection(
+    accountId: string,
+    currentConnId?: string,
+    currentClientId?: string,
+  ): boolean {
+    const acc = normalizeAccountId(accountId);
+    const t = now();
+    const currentConn = asString(currentConnId || '').trim();
+    const currentClient = asString(currentClientId || '').trim() || undefined;
+
+    for (const conn of this.connections.values()) {
+      if (conn.accountId !== acc) continue;
+      if (!conn.connId) continue;
+      if (t - conn.lastSeenAt > CONNECT_TTL_MS) continue;
+      const sameConn = !!currentConn && conn.connId === currentConn;
+      const sameClient = !currentConn && !!currentClient && conn.clientId === currentClient;
+      if (sameConn || sameClient) continue;
+      return true;
+    }
+    return false;
+  }
+
+  private degradeOutboundCapability(args: {
+    accountId: string;
+    connId?: string;
+    clientId?: string;
+    reason: string;
+    at?: number;
+  }) {
+    const acc = normalizeAccountId(args.accountId);
+    const t = Number(args.at || now());
+    const hasAlternativeLiveConnection = this.hasAlternativeLiveConnection(
+      acc,
+      args.connId,
+      args.clientId,
+    );
+    const currentKey = this.activeConnectionByAccount.get(acc) || null;
+    let matchedKey: string | null = null;
+    let matchedConn: (BncrConnection & {
+      outboundReadyUntil?: number;
+      preferredForOutboundUntil?: number;
+      inboundOnly?: boolean;
+    }) | null = null;
+
+    for (const [key, conn] of this.connections.entries()) {
+      if (conn.accountId !== acc) continue;
+      if (args.connId && conn.connId !== args.connId) continue;
+      if (args.clientId && conn.clientId !== args.clientId) continue;
+      matchedKey = key;
+      matchedConn = conn as BncrConnection & {
+        outboundReadyUntil?: number;
+        preferredForOutboundUntil?: number;
+        inboundOnly?: boolean;
+      };
+      break;
+    }
+
+    if (!matchedKey || !matchedConn) return;
+
+    const before = {
+      outboundReadyUntil: matchedConn.outboundReadyUntil || null,
+      preferredForOutboundUntil: matchedConn.preferredForOutboundUntil || null,
+      inboundOnly: matchedConn.inboundOnly === true,
     };
 
-    this.connections.set(key, nextConn);
+    if (!hasAlternativeLiveConnection) {
+      this.logInfo(
+        'connection',
+        `outbound-degrade skip ${JSON.stringify({
+          bridge: this.bridgeId,
+          accountId: acc,
+          connId: matchedConn.connId,
+          clientId: matchedConn.clientId,
+          reason: args.reason,
+          at: t,
+          currentActiveKey: currentKey,
+          degradedKey: matchedKey,
+          skipReason: 'no-alternative-live-connection',
+          before,
+        })}`,
+        { debugOnly: true },
+      );
+      return;
+    }
+
+    matchedConn.outboundReadyUntil = undefined;
+    matchedConn.preferredForOutboundUntil = undefined;
+    this.connections.set(matchedKey, matchedConn as BncrConnection);
+
     this.logInfo(
       'connection',
-      `seen ${JSON.stringify({
+      `outbound-degrade ${JSON.stringify({
         bridge: this.bridgeId,
         accountId: acc,
-        connId,
-        clientId: nextConn.clientId,
-        connectedAt: nextConn.connectedAt,
-        lastSeenAt: nextConn.lastSeenAt,
+        connId: matchedConn.connId,
+        clientId: matchedConn.clientId,
+        reason: args.reason,
+        at: t,
+        currentActiveKey: currentKey,
+        degradedKey: matchedKey,
+        before,
+        after: {
+          outboundReadyUntil: matchedConn.outboundReadyUntil || null,
+          preferredForOutboundUntil: matchedConn.preferredForOutboundUntil || null,
+          inboundOnly: matchedConn.inboundOnly === true,
+        },
       })}`,
       { debugOnly: true },
     );
-
-    const current = this.activeConnectionByAccount.get(acc);
-    if (!current) {
-      this.activeConnectionByAccount.set(acc, key);
-      return;
-    }
-
-    const curConn = this.connections.get(current);
-    if (
-      !curConn ||
-      t - curConn.lastSeenAt > CONNECT_TTL_MS ||
-      nextConn.connectedAt >= curConn.connectedAt
-    ) {
-      this.activeConnectionByAccount.set(acc, key);
-    }
   }
 
   private isOnline(accountId: string): boolean {
@@ -1858,9 +3045,61 @@ class BncrBridgeRuntime {
       Math.min(Number(params.timeoutMs || FILE_ACK_TIMEOUT_MS), 120_000),
     );
 
+    const cached = this.earlyFileAcks.get(key);
+    if (cached) {
+      this.earlyFileAcks.delete(key);
+      this.logInfo(
+        'file-ack-cache-hit',
+        JSON.stringify({
+          bridge: this.bridgeId,
+          transferId,
+          stage,
+          chunkIndex:
+            Number.isFinite(Number(params.chunkIndex)) ? Number(params.chunkIndex) : undefined,
+          key,
+          ok: cached.ok,
+          payload: cached.payload,
+        }),
+        { debugOnly: true },
+      );
+      if (cached.ok) return Promise.resolve(cached.payload);
+      return Promise.reject(
+        new Error(
+          asString(cached.payload?.errorMessage || cached.payload?.error || 'file ack failed'),
+        ),
+      );
+    }
+
+    this.logInfo(
+      'file-ack-wait',
+      JSON.stringify({
+        bridge: this.bridgeId,
+        transferId,
+        stage,
+        chunkIndex:
+          Number.isFinite(Number(params.chunkIndex)) ? Number(params.chunkIndex) : undefined,
+        key,
+        timeoutMs,
+      }),
+      { debugOnly: true },
+    );
+
     return new Promise<Record<string, unknown>>((resolve, reject) => {
       const timer = setTimeout(() => {
         this.fileAckWaiters.delete(key);
+        this.logWarn(
+          'file-ack-timeout',
+          JSON.stringify({
+            bridge: this.bridgeId,
+            transferId,
+            stage,
+            chunkIndex:
+              Number.isFinite(Number(params.chunkIndex)) ? Number(params.chunkIndex) : undefined,
+            key,
+            timeoutMs,
+          }),
+          { debugOnly: true },
+        );
         reject(new Error(`file ack timeout: ${key}`));
       }, timeoutMs);
       this.fileAckWaiters.set(key, { resolve, reject, timer });
@@ -1878,9 +3117,45 @@ class BncrBridgeRuntime {
     const stage = asString(params.stage).trim();
     const key = this.fileAckKey(transferId, stage, params.chunkIndex);
     const waiter = this.fileAckWaiters.get(key);
-    if (!waiter) return false;
+    if (!waiter) {
+      this.earlyFileAcks.set(key, {
+        payload: params.payload,
+        ok: params.ok,
+        at: now(),
+      });
+      this.logInfo(
+        'file-ack-early-cache',
+        JSON.stringify({
+          bridge: this.bridgeId,
+          transferId,
+          stage,
+          chunkIndex:
+            Number.isFinite(Number(params.chunkIndex)) ? Number(params.chunkIndex) : undefined,
+          key,
+          ok: params.ok,
+          payload: params.payload,
+          cached: true,
+        }),
+        { debugOnly: true },
+      );
+      return false;
+    }
     this.fileAckWaiters.delete(key);
     clearTimeout(waiter.timer);
+    this.logInfo(
+      'file-ack-resolve',
+      JSON.stringify({
+        bridge: this.bridgeId,
+        transferId,
+        stage,
+        chunkIndex:
+          Number.isFinite(Number(params.chunkIndex)) ? Number(params.chunkIndex) : undefined,
+        key,
+        ok: params.ok,
+        payload: params.payload,
+      }),
+      { debugOnly: true },
+    );
     if (params.ok) waiter.resolve(params.payload);
     else
       waiter.reject(
@@ -2254,9 +3529,46 @@ class BncrBridgeRuntime {
     }
 
     const ctx = this.gatewayContext;
+    const owner = this.resolveOutboxPushOwner(params.accountId);
+    const recentInboundReachable = this.hasRecentInboundReachability(params.accountId);
+    const directConnIds = this.resolvePushConnIds(params.accountId);
+    const recentConnIds = recentInboundReachable
+      ? this.resolveRecentInboundConnIds(params.accountId)
+      : new Set<string>();
+    const accountId = normalizeAccountId(params.accountId);
+    const activeConnectionKey = this.activeConnectionByAccount.get(accountId) || null;
+    const accountConnections = Array.from(this.connections.values())
+      .filter((c) => c.accountId === accountId)
+      .map((c) => ({
+        connId: c.connId,
+        clientId: c.clientId,
+        connectedAt: c.connectedAt,
+        lastSeenAt: c.lastSeenAt,
+      }));
+    this.logInfo(
+      'file-chunk-diag',
+      JSON.stringify({
+        bridge: this.bridgeId,
+        accountId,
+        sessionKey: params.sessionKey,
+        mediaUrl: params.mediaUrl,
+        hasGatewayContext: Boolean(ctx),
+        activeConnectionKey,
+        ownerConnId: owner?.connId || null,
+        ownerClientId: owner?.clientId || null,
+        directConnIds: Array.from(directConnIds),
+        recentInboundReachable,
+        recentConnIds: Array.from(recentConnIds),
+        accountConnections,
+      }),
+      { debugOnly: true },
+    );
     if (!ctx) throw new Error('gateway context unavailable');
 
-    const connIds = this.resolvePushConnIds(params.accountId);
+    let connIds = directConnIds;
+    if (!connIds.size && recentInboundReachable) {
+      connIds = recentConnIds;
+    }
     if (!connIds.size) throw new Error('no active bncr client for file chunk transfer');
 
     const transferId = randomUUID();
@@ -2264,7 +3576,26 @@ class BncrBridgeRuntime {
     const totalChunks = Math.ceil(size / chunkSize);
     const fileSha256 = createHash('sha256').update(loaded.buffer).digest('hex');
 
-    const owner = this.resolveOutboxPushOwner(params.accountId);
+    this.logInfo(
+      'file-transfer-start',
+      JSON.stringify({
+        bridge: this.bridgeId,
+        transferId,
+        accountId,
+        sessionKey: params.sessionKey,
+        mediaUrl: params.mediaUrl,
+        fileName,
+        mimeType,
+        fileSize: size,
+        chunkSize,
+        totalChunks,
+        connIds: Array.from(connIds),
+        ownerConnId: owner?.connId || null,
+        ownerClientId: owner?.clientId || null,
+      }),
+      { debugOnly: true },
+    );
+
     const st: FileSendTransferState = {
       transferId,
       accountId: normalizeAccountId(params.accountId),
@@ -2329,16 +3660,54 @@ class BncrBridgeRuntime {
           connIds,
         );
 
+        this.logInfo(
+          'file-transfer-chunk-send',
+          JSON.stringify({
+            bridge: this.bridgeId,
+            transferId,
+            accountId,
+            chunkIndex: idx,
+            attempt,
+            offset: start,
+            size: slice.byteLength,
+            connIds: Array.from(connIds),
+          }),
+          { debugOnly: true },
+        );
+
         try {
           await this.waitChunkAck({
             transferId,
             chunkIndex: idx,
             timeoutMs: FILE_TRANSFER_ACK_TTL_MS,
           });
+          this.logInfo(
+            'file-transfer-chunk-ack',
+            JSON.stringify({
+              bridge: this.bridgeId,
+              transferId,
+              accountId,
+              chunkIndex: idx,
+              attempt,
+            }),
+            { debugOnly: true },
+          );
           ok = true;
           break;
         } catch (err) {
           lastErr = err;
+          this.logWarn(
+            'file-transfer-chunk-ack-fail',
+            JSON.stringify({
+              bridge: this.bridgeId,
+              transferId,
+              accountId,
+              chunkIndex: idx,
+              attempt,
+              error: asString((err as Error)?.message || err),
+            }),
+            { debugOnly: true },
+          );
           await this.sleepMs(150 * attempt);
         }
       }
@@ -2369,8 +3738,30 @@ class BncrBridgeRuntime {
       connIds,
     );
 
+    this.logInfo(
+      'file-transfer-complete-send',
+      JSON.stringify({
+        bridge: this.bridgeId,
+        transferId,
+        accountId,
+        connIds: Array.from(connIds),
+      }),
+      { debugOnly: true },
+    );
+
     const done = await this.waitCompleteAck({ transferId, timeoutMs: 60_000 });
 
+    this.logInfo(
+      'file-transfer-complete-ack',
+      JSON.stringify({
+        bridge: this.bridgeId,
+        transferId,
+        accountId,
+        payload: done,
+      }),
+      { debugOnly: true },
+    );
+
     return {
       mode: 'chunk',
       mimeType,
@@ -2396,6 +3787,29 @@ class BncrBridgeRuntime {
   }) {
     const { accountId, sessionKey, route, payload, mediaLocalRoots } = params;
 
+    this.logInfo(
+      'outbound',
+      `enqueue-from-reply ${JSON.stringify({
+        accountId,
+        sessionKey,
+        route: {
+          platform: route?.platform,
+          groupId: route?.groupId,
+          userId: route?.userId,
+        },
+        payload: {
+          text: asString(payload?.text || ''),
+          mediaUrl: asString(payload?.mediaUrl || ''),
+          mediaUrls: Array.isArray(payload?.mediaUrls) ? payload.mediaUrls : undefined,
+          asVoice: payload?.asVoice === true,
+          audioAsVoice: payload?.audioAsVoice === true,
+          kind: payload?.kind,
+          replyToId: asString(payload?.replyToId || ''),
+        },
+      })}`,
+      { debugOnly: true },
+    );
+
     const mediaList = payload.mediaUrls?.length
       ? payload.mediaUrls
       : payload.mediaUrl
@@ -2404,44 +3818,67 @@ class BncrBridgeRuntime {
 
     if (mediaList.length > 0) {
       let first = true;
+      const currentTime = now();
       for (const mediaUrl of mediaList) {
-        const media = await this.transferMediaToBncrClient({
-          accountId,
-          sessionKey,
-          route,
-          mediaUrl,
-          mediaLocalRoots,
-        });
-        const messageId = randomUUID();
-        const mediaMsg = first ? asString(payload.text || '') : '';
-        const wantsVoice = payload.asVoice === true || payload.audioAsVoice === true;
-        const frame = buildBncrMediaOutboundFrame({
-          messageId,
+        const normalizedMediaUrl = asString(mediaUrl || '').trim();
+        if (!normalizedMediaUrl) continue;
+
+        const normalizedText = normalizeMessageText(first ? payload.text : '');
+        const normalizedReplyToId = normalizeReplyToId(payload.replyToId);
+        const fallback = this.tryBuildMediaDedupeFallback({
           sessionKey,
-          route,
-          media,
-          mediaUrl,
-          mediaMsg,
-          fileName: resolveOutboundFileName({
-            mediaUrl,
-            fileName: media.fileName,
-            mimeType: media.mimeType,
-          }),
-          hintedType: wantsVoice ? 'voice' : undefined,
-          kind: payload.kind,
-          replyToId: asString(payload.replyToId || '').trim() || undefined,
-          now: now(),
+          mediaUrl: normalizedMediaUrl,
+          text: normalizedText,
+          replyToId: normalizedReplyToId,
+          currentTime,
         });
 
-        this.enqueueOutbound({
-          messageId,
-          accountId: normalizeAccountId(accountId),
+        if (fallback !== null) {
+          this.logInfo(
+            'outbound',
+            `media-dedupe-hit ${JSON.stringify({
+              sessionKey,
+              mediaUrl: normalizedMediaUrl,
+              replyToId: normalizedReplyToId || undefined,
+              fallbackText: fallback.text,
+              reason: fallback.reason,
+            })}`,
+            { debugOnly: true },
+          );
+          this.enqueueOutbound(
+            this.buildTextOutboxEntry({
+              accountId,
+              sessionKey,
+              route,
+              text: fallback.text,
+              kind: payload.kind,
+              replyToId: normalizedReplyToId || undefined,
+            }),
+          );
+          first = false;
+          continue;
+        }
+
+        this.enqueueOutbound(
+          this.buildFileTransferOutboxEntry({
+            accountId,
+            sessionKey,
+            route,
+            mediaUrl: normalizedMediaUrl,
+            mediaLocalRoots,
+            text: first ? asString(payload.text || '') : '',
+            asVoice: payload.asVoice,
+            audioAsVoice: payload.audioAsVoice,
+            kind: payload.kind,
+            replyToId: normalizedReplyToId || undefined,
+          }),
+        );
+        this.rememberRecentMediaSend({
           sessionKey,
-          route,
-          payload: frame,
-          createdAt: now(),
-          retryCount: 0,
-          nextAttemptAt: now(),
+          mediaUrl: normalizedMediaUrl,
+          text: normalizedText,
+          replyToId: normalizedReplyToId,
+          createdAt: currentTime,
         });
         first = false;
       }
@@ -2451,37 +3888,16 @@ class BncrBridgeRuntime {
     const text = asString(payload.text || '').trim();
     if (!text) return;
 
-    const messageId = randomUUID();
-    const frame = {
-      type: 'message.outbound',
-      messageId,
-      idempotencyKey: messageId,
-      sessionKey,
-      replyToId: asString(payload.replyToId || '').trim() || undefined,
-      message: {
-        platform: route.platform,
-        groupId: route.groupId,
-        userId: route.userId,
-        type: 'text',
+    this.enqueueOutbound(
+      this.buildTextOutboxEntry({
+        accountId,
+        sessionKey,
+        route,
+        text,
         kind: payload.kind,
-        msg: text,
-        path: '',
-        base64: '',
-        fileName: '',
-      },
-      ts: now(),
-    };
-
-    this.enqueueOutbound({
-      messageId,
-      accountId: normalizeAccountId(accountId),
-      sessionKey,
-      route,
-      payload: frame,
-      createdAt: now(),
-      retryCount: 0,
-      nextAttemptAt: now(),
-    });
+        replyToId: asString(payload.replyToId || '').trim() || undefined,
+      }),
+    );
   }
 
   handleConnect = async ({ params, respond, client, context }: GatewayRequestHandlerOptions) => {
@@ -2489,6 +3905,9 @@ 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;
+    const outboundReady = (params as any)?.outboundReady === true;
+    const preferredForOutbound = (params as any)?.preferredForOutbound === true;
+    const inboundOnly = (params as any)?.inboundOnly === true;
 
     this.logInfo(
       'connection',
@@ -2497,6 +3916,9 @@ class BncrBridgeRuntime {
         accountId,
         connId,
         clientId,
+        outboundReady,
+        preferredForOutbound,
+        inboundOnly,
         hasContext: Boolean(context),
       })}`,
       { debugOnly: true },
@@ -2504,6 +3926,14 @@ class BncrBridgeRuntime {
 
     this.rememberGatewayContext(context);
     this.markSeen(accountId, connId, clientId);
+    this.markOutboundCapability({
+      accountId,
+      connId,
+      clientId,
+      outboundReady,
+      preferredForOutbound,
+      inboundOnly,
+    });
     this.markActivity(accountId);
     this.incrementCounter(this.connectEventsByAccount, accountId);
     const lease = this.acceptConnection();
@@ -2534,7 +3964,7 @@ class BncrBridgeRuntime {
     });
 
     // WS 一旦在线，立即尝试把离线期间积压队列直推出去
-    this.flushPushQueue(accountId);
+    this.flushPushQueue({ accountId, trigger: 'connect', reason: 'ws-online' });
   };
 
   handleAck = async ({ params, respond, client, context }: GatewayRequestHandlerOptions) => {
@@ -2600,19 +4030,29 @@ class BncrBridgeRuntime {
     const fatal = params?.fatal === true;
 
     if (ok) {
+      this.markOutboundCapability({
+        accountId,
+        connId,
+        clientId,
+        outboundReady: true,
+        preferredForOutbound: true,
+      });
       this.outbox.delete(messageId);
       this.scheduleSave();
       this.resolveMessageAck(messageId, 'acked');
+      this.logInfo('outbox ack ok', `mid=${messageId}|q=${this.outbox.size}`);
       respond(
         true,
         staleObserved.stale ? { ok: true, stale: true, staleAccepted: true } : { ok: true },
       );
-      this.flushPushQueue(accountId);
+      this.flushPushQueue({ accountId, trigger: 'ack-ok', reason: 'message-acked' });
       return;
     }
 
     if (fatal) {
-      this.moveToDeadLetter(entry, asString(params?.error || 'fatal-ack'));
+      const error = asString(params?.error || 'fatal-ack');
+      this.moveToDeadLetter(entry, error);
+      this.logInfo('outbox ack fatal', `mid=${messageId}|q=${this.outbox.size}|err=${error}`);
       respond(
         true,
         staleObserved.stale
@@ -2626,6 +4066,7 @@ class BncrBridgeRuntime {
     entry.lastError = asString(params?.error || 'retryable-ack');
     this.outbox.set(messageId, entry);
     this.scheduleSave();
+    this.logInfo('outbox ack retry', `mid=${messageId}|q=${this.outbox.size}|err=${entry.lastError}`);
 
     respond(
       true,
@@ -2640,6 +4081,9 @@ 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;
+    const outboundReady = (params as any)?.outboundReady === true;
+    const preferredForOutbound = (params as any)?.preferredForOutbound === true;
+    const inboundOnly = (params as any)?.inboundOnly === true;
     if (
       this.shouldIgnoreStaleEvent({
         kind: 'activity',
@@ -2660,12 +4104,23 @@ class BncrBridgeRuntime {
         accountId,
         connId,
         clientId,
+        outboundReady,
+        preferredForOutbound,
+        inboundOnly,
         hasContext: Boolean(context),
       })}`,
       { debugOnly: true },
     );
     this.rememberGatewayContext(context);
     this.markSeen(accountId, connId, clientId);
+    this.markOutboundCapability({
+      accountId,
+      connId,
+      clientId,
+      outboundReady,
+      preferredForOutbound,
+      inboundOnly,
+    });
     this.markActivity(accountId);
     this.incrementCounter(this.activityEventsByAccount, accountId);
 
@@ -2679,7 +4134,7 @@ class BncrBridgeRuntime {
       deadLetter: this.deadLetter.filter((v) => v.accountId === accountId).length,
       now: now(),
     });
-    this.flushPushQueue(accountId);
+    this.flushPushQueue({ accountId, trigger: 'activity', reason: 'activity-heartbeat' });
   };
 
   handleDiagnostics = async ({ params, respond }: GatewayRequestHandlerOptions) => {
@@ -3073,6 +4528,24 @@ class BncrBridgeRuntime {
     const ok = params?.ok !== false;
     const chunkIndex = Number(params?.chunkIndex ?? -1);
 
+    this.logInfo(
+      'file-ack-inbound',
+      JSON.stringify({
+        bridge: this.bridgeId,
+        accountId,
+        connId,
+        clientId: clientId || null,
+        transferId,
+        stage,
+        ok,
+        chunkIndex: chunkIndex >= 0 ? chunkIndex : undefined,
+        errorCode: asString(params?.errorCode || ''),
+        errorMessage: asString(params?.errorMessage || ''),
+        path: asString(params?.path || '').trim(),
+      }),
+      { debugOnly: true },
+    );
+
     if (!transferId || !stage) {
       respond(false, { error: 'transferId/stage required' });
       return;
@@ -3092,7 +4565,15 @@ class BncrBridgeRuntime {
       const sameConn = !!st?.ownerConnId && st.ownerConnId === connId;
       const sameClient =
         !st?.ownerConnId && !!st?.ownerClientId && !!clientId && st.ownerClientId === clientId;
-      if (!(sameConn || sameClient)) {
+      const adopted =
+        !(sameConn || sameClient) &&
+        this.tryAdoptTransferOwner({
+          accountId,
+          transfer: st,
+          connId,
+          clientId,
+        });
+      if (!(sameConn || sameClient || adopted)) {
         this.logWarn(
           'stale',
           `ignore kind=file.ack accountId=${accountId} connId=${connId} clientId=${clientId || '-'} transferId=${transferId} stage=${stage} reason=owner-mismatch ownerConnId=${st?.ownerConnId || '-'} ownerClientId=${st?.ownerClientId || '-'}`,
@@ -3186,6 +4667,9 @@ class BncrBridgeRuntime {
     } = parsed;
     const connId = asString(client?.connId || '').trim() || `no-conn-${Date.now()}`;
     const clientId = asString((params as any)?.clientId || '').trim() || undefined;
+    const outboundReady = (params as any)?.outboundReady === true;
+    const preferredForOutbound = (params as any)?.preferredForOutbound === true;
+    const inboundOnly = (params as any)?.inboundOnly === true;
     if (
       this.shouldIgnoreStaleEvent({
         kind: 'inbound',
@@ -3206,7 +4690,40 @@ class BncrBridgeRuntime {
     }
     this.rememberGatewayContext(context);
     this.markSeen(accountId, connId, clientId);
+    this.markOutboundCapability({
+      accountId,
+      connId,
+      clientId,
+      outboundReady,
+      preferredForOutbound,
+      inboundOnly,
+    });
     this.markActivity(accountId);
+    this.logInfo(
+      'inbound',
+      `lifecycle ${JSON.stringify({
+        stage: 'accepted',
+        bridge: this.bridgeId,
+        accountId,
+        connId,
+        clientId,
+        outboundReady,
+        preferredForOutbound,
+        inboundOnly,
+        onlineAfterSeen: this.isOnline(accountId),
+        recentInboundReachable: this.hasRecentInboundReachability(accountId),
+        activeConnectionKey: this.activeConnectionByAccount.get(accountId) || null,
+        activeConnections: Array.from(this.connections.values())
+          .filter((c) => c.accountId === accountId)
+          .map((c) => ({
+            connId: c.connId,
+            clientId: c.clientId,
+            connectedAt: c.connectedAt,
+            lastSeenAt: c.lastSeenAt,
+          })),
+      })}`,
+      { debugOnly: true },
+    );
     this.lastInboundAtGlobal = now();
     this.incrementCounter(this.inboundEventsByAccount, accountId);
 
@@ -3289,7 +4806,7 @@ class BncrBridgeRuntime {
       msgId: msgId ?? null,
       taskKey: extracted.taskKey ?? null,
     });
-    this.flushPushQueue(accountId);
+    this.flushPushQueue({ accountId, trigger: 'inbound', reason: 'inbound-accepted' });
 
     void dispatchBncrInbound({
       api: this.api,
@@ -3316,11 +4833,50 @@ class BncrBridgeRuntime {
 
   channelStartAccount = async (ctx: any) => {
     const accountId = normalizeAccountId(ctx.accountId);
+    this.clearChannelAccountWorker(accountId, 'start-replace');
 
     const tick = () => {
-      const connected = this.isOnline(accountId);
       const previous = ctx.getStatus?.() || {};
-      const lastActAt = this.lastActivityByAccount.get(accountId) || previous?.lastEventAt || null;
+      const onlineByConn = this.isOnline(accountId);
+      const recentInboundReachable = this.hasRecentInboundReachability(accountId);
+      const connected = onlineByConn || recentInboundReachable;
+      const lastActAt =
+        this.lastActivityByAccount.get(accountId) ||
+        this.lastInboundByAccount.get(accountId) ||
+        this.lastOutboundByAccount.get(accountId) ||
+        previous?.lastEventAt ||
+        null;
+      const healthSig = JSON.stringify({
+        bridge: this.bridgeId,
+        accountId,
+        connected,
+        onlineByConn,
+        recentInboundReachable,
+        activeConnectionKey: this.activeConnectionByAccount.get(accountId) || null,
+        activeConnections: Array.from(this.connections.values())
+          .filter((c) => c.accountId === accountId)
+          .map((c) => ({
+            connId: c.connId,
+            clientId: c.clientId,
+            inboundOnly: c.inboundOnly === true,
+            outboundReady: c.outboundReady === true,
+            preferredForOutbound: c.preferredForOutbound === true,
+          })),
+      });
+      const conns = Array.from(this.connections.values()).filter((c) => c.accountId === accountId).length;
+      this.logInfoDedup(
+        'health',
+        `status-tick ${accountId}|changed|${connected ? 'linked' : 'configured'}|onlineByConn=${onlineByConn}|recentInboundReachable=${recentInboundReachable}|conns=${conns}`,
+        {
+          key: `health-status-tick:${accountId}`,
+          sig: healthSig,
+        },
+      );
+      this.logInfoDedup('health', `status-tick ${healthSig}`, {
+        key: `health-status-tick-debug:${accountId}`,
+        sig: healthSig,
+        debugOnly: true,
+      });
 
       ctx.setStatus?.({
         ...previous,
@@ -3337,13 +4893,31 @@ class BncrBridgeRuntime {
 
     tick();
     const timer = setInterval(tick, 5_000);
+    this.channelAccountTimers.set(accountId, timer);
 
     await new Promise<void>((resolve) => {
-      const onAbort = () => {
-        clearInterval(timer);
+      let settled = false;
+      const finish = (reason: string) => {
+        if (settled) return;
+        settled = true;
+        const activeTimer = this.channelAccountTimers.get(accountId);
+        if (activeTimer === timer) {
+          clearInterval(timer);
+          this.channelAccountTimers.delete(accountId);
+        } else {
+          clearInterval(timer);
+        }
+        this.logInfo(
+          'health',
+          `status-worker finished ${JSON.stringify({ bridge: this.bridgeId, accountId, reason })}`,
+          { debugOnly: true },
+        );
+        this.logInfo('health', `status-worker finished ${accountId}|${reason}`);
         resolve();
       };
 
+      const onAbort = () => finish('abort');
+
       if (ctx.abortSignal?.aborted) {
         onAbort();
         return;
@@ -3353,8 +4927,24 @@ class BncrBridgeRuntime {
     });
   };
 
-  channelStopAccount = async (_ctx: any) => {
-    // no-op
+  channelStopAccount = async (ctx: any) => {
+    const accountId = normalizeAccountId(ctx?.accountId);
+    const cleared = this.clearChannelAccountWorker(accountId, 'explicit-stop');
+    const previous = ctx?.getStatus?.() || {};
+    ctx?.setStatus?.({
+      ...previous,
+      accountId,
+      running: false,
+      restartPending: false,
+      lastStopAt: Date.now(),
+      meta: this.buildStatusMeta(accountId),
+    });
+    this.logInfo(
+      'health',
+      `status-stop ${JSON.stringify({ bridge: this.bridgeId, accountId, cleared })}`,
+      { debugOnly: true },
+    );
+    this.logInfo('health', `status-stop ${accountId}|cleared=${cleared}`);
   };
 
   channelSendText = async (ctx: any) => {
@@ -3431,6 +5021,7 @@ class BncrBridgeRuntime {
       to,
       text: asString(ctx.text || ''),
       mediaUrl: asString(ctx.mediaUrl || ''),
+      mediaUrls: Array.isArray(ctx?.mediaUrls) ? ctx.mediaUrls : undefined,
       asVoice,
       audioAsVoice,
       replyToId: asString(ctx?.replyToId || ctx?.replyToMessageId || '').trim() || undefined,
@@ -3448,7 +5039,7 @@ export function createBncrBridge(api: OpenClawPluginApi) {
   return new BncrBridgeRuntime(api);
 }
 
-export function createBncrChannelPlugin(bridge: BncrBridgeRuntime) {
+export function createBncrChannelPlugin(getBridge: () => BncrBridgeRuntime) {
   const messageActions: ChannelMessageActionAdapter = {
     describeMessageTool: ({ cfg }) => {
       const channelCfg = cfg?.channels?.[CHANNEL_ID];
@@ -3460,9 +5051,10 @@ export function createBncrChannelPlugin(bridge: BncrBridgeRuntime) {
           (accountId) => resolveAccount(cfg, accountId).enabled !== false,
         );
 
+      const runtimeBridge = getBridge();
       const hasConnectedRuntime = listAccountIds(cfg).some((accountId) => {
         const resolved = resolveAccount(cfg, accountId);
-        const runtime = bridge.getAccountRuntimeSnapshot(resolved.accountId);
+        const runtime = runtimeBridge.getAccountRuntimeSnapshot(resolved.accountId);
         return Boolean(runtime?.connected);
       });
 
@@ -3480,49 +5072,37 @@ export function createBncrChannelPlugin(bridge: BncrBridgeRuntime) {
     handleAction: async ({ action, params, accountId, mediaLocalRoots }) => {
       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 }) ?? '';
-      const content = message || caption || '';
-      const mediaUrl =
-        readStringParam(params, 'media', { trim: false }) ??
-        readStringParam(params, 'path', { trim: false }) ??
-        readStringParam(params, 'filePath', { trim: false }) ??
-        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 normalized = normalizeBncrSendParams({ params, accountId });
 
-      if (!content.trim() && !mediaUrl) throw new Error('send requires text or media');
-
-      const result = mediaUrl
+      const runtimeBridge = getBridge();
+      const result = normalized.mediaUrl
         ? await sendBncrMedia({
             channelId: CHANNEL_ID,
-            accountId: resolvedAccountId,
-            to,
-            text: content,
-            mediaUrl,
-            asVoice,
-            audioAsVoice,
+            accountId: normalized.accountId,
+            to: normalized.to,
+            text: normalized.caption,
+            mediaUrl: normalized.mediaUrl,
+            asVoice: normalized.asVoice,
+            audioAsVoice: normalized.audioAsVoice,
             mediaLocalRoots,
-            resolveVerifiedTarget: (to, accountId) => bridge.resolveVerifiedTarget(to, accountId),
+            resolveVerifiedTarget: (to, accountId) =>
+              runtimeBridge.resolveVerifiedTarget(to, accountId),
             rememberSessionRoute: (sessionKey, accountId, route) =>
-              bridge.rememberSessionRoute(sessionKey, accountId, route),
-            enqueueFromReply: (args) => bridge.enqueueFromReply(args as any),
+              runtimeBridge.rememberSessionRoute(sessionKey, accountId, route),
+            enqueueFromReply: (args) => runtimeBridge.enqueueFromReply(args as any),
             createMessageId: () => randomUUID(),
           })
         : await sendBncrText({
             channelId: CHANNEL_ID,
-            accountId: resolvedAccountId,
-            to,
-            text: content,
+            accountId: normalized.accountId,
+            to: normalized.to,
+            text: normalized.message,
             mediaLocalRoots,
-            resolveVerifiedTarget: (to, accountId) => bridge.resolveVerifiedTarget(to, accountId),
+            resolveVerifiedTarget: (to, accountId) =>
+              runtimeBridge.resolveVerifiedTarget(to, accountId),
             rememberSessionRoute: (sessionKey, accountId, route) =>
-              bridge.rememberSessionRoute(sessionKey, accountId, route),
-            enqueueFromReply: (args) => bridge.enqueueFromReply(args as any),
+              runtimeBridge.rememberSessionRoute(sessionKey, accountId, route),
+            enqueueFromReply: (args) => runtimeBridge.enqueueFromReply(args as any),
             createMessageId: () => randomUUID(),
           });
 
@@ -3557,9 +5137,10 @@ export function createBncrChannelPlugin(bridge: BncrBridgeRuntime) {
         const resolvedAccountId = normalizeAccountId(
           asString(accountId || BNCR_DEFAULT_ACCOUNT_ID),
         );
+        const runtimeBridge = getBridge();
         const canonicalAgentId =
-          bridge.canonicalAgentId ||
-          bridge.ensureCanonicalAgentId({ cfg, accountId: resolvedAccountId });
+          runtimeBridge.canonicalAgentId ||
+          runtimeBridge.ensureCanonicalAgentId({ cfg, accountId: resolvedAccountId });
         return parseExplicitTarget(asString(raw).trim(), { canonicalAgentId });
       },
       formatTargetDisplay: ({ target }: any) => {
@@ -3571,13 +5152,14 @@ export function createBncrChannelPlugin(bridge: BncrBridgeRuntime) {
         const resolvedAccountId = normalizeAccountId(
           asString(accountId || BNCR_DEFAULT_ACCOUNT_ID),
         );
+        const runtimeBridge = getBridge();
         const canonicalAgentId =
-          bridge.canonicalAgentId ||
-          bridge.ensureCanonicalAgentId({ cfg, accountId: resolvedAccountId });
+          runtimeBridge.canonicalAgentId ||
+          runtimeBridge.ensureCanonicalAgentId({ cfg, accountId: resolvedAccountId });
 
         let parsed = parseExplicitTarget(raw, { canonicalAgentId });
         if (!parsed) {
-          const route = bridge.resolveRouteBySession(raw, resolvedAccountId);
+          const route = runtimeBridge.resolveRouteBySession(raw, resolvedAccountId);
           if (route) {
             parsed = parseExplicitTarget(formatDisplayScope(route), { canonicalAgentId });
           }
@@ -3588,13 +5170,15 @@ export function createBncrChannelPlugin(bridge: BncrBridgeRuntime) {
         const accountId = normalizeAccountId(
           asString(params?.accountId || BNCR_DEFAULT_ACCOUNT_ID),
         );
+        const runtimeBridge = getBridge();
         const canonicalAgentId =
-          bridge.canonicalAgentId || bridge.ensureCanonicalAgentId({ cfg: params?.cfg, accountId });
+          runtimeBridge.canonicalAgentId ||
+          runtimeBridge.ensureCanonicalAgentId({ cfg: params?.cfg, accountId });
         return resolveBncrOutboundSessionRoute({
           ...params,
           canonicalAgentId,
           resolveRouteBySession: (raw: string, acc: string) =>
-            bridge.resolveRouteBySession(raw, acc),
+            runtimeBridge.resolveRouteBySession(raw, acc),
         });
       },
       targetResolver: {
@@ -3602,11 +5186,12 @@ export function createBncrChannelPlugin(bridge: BncrBridgeRuntime) {
           return looksLikeBncrExplicitTarget(asString(normalized || raw).trim());
         },
         resolveTarget: async ({ accountId, input, normalized }) => {
+          const runtimeBridge = getBridge();
           const resolved = resolveBncrOutboundTarget({
             target: asString(normalized || input).trim(),
             accountId: normalizeAccountId(asString(accountId || BNCR_DEFAULT_ACCOUNT_ID)),
             resolveRouteBySession: (raw: string, acc: string) =>
-              this.resolveRouteBySession(raw, acc),
+              runtimeBridge.resolveRouteBySession(raw, acc),
           });
           if (!resolved) return null;
           return {
@@ -3669,8 +5254,8 @@ export function createBncrChannelPlugin(bridge: BncrBridgeRuntime) {
     },
     outbound: {
       deliveryMode: 'gateway' as const,
-      sendText: bridge.channelSendText,
-      sendMedia: bridge.channelSendMedia,
+      sendText: async (ctx: any) => getBridge().channelSendText(ctx),
+      sendMedia: async (ctx: any) => getBridge().channelSendMedia(ctx),
       replyAction: async (ctx: any) =>
         sendBncrReplyAction({
           accountId: normalizeAccountId(ctx?.accountId),
@@ -3679,7 +5264,7 @@ export function createBncrChannelPlugin(bridge: BncrBridgeRuntime) {
           replyToMessageId:
             asString(ctx?.replyToId || ctx?.replyToMessageId || '').trim() || undefined,
           sendText: async ({ accountId, to, text }) =>
-            bridge.channelSendText({ accountId, to, text }),
+            getBridge().channelSendText({ accountId, to, text }),
         }),
       deleteAction: async (ctx: any) =>
         deleteBncrMessageAction({
@@ -3704,10 +5289,11 @@ export function createBncrChannelPlugin(bridge: BncrBridgeRuntime) {
         mode: 'ws-offline',
       }),
       buildChannelSummary: async ({ defaultAccountId }: any) => {
-        return bridge.getChannelSummary(defaultAccountId || BNCR_DEFAULT_ACCOUNT_ID);
+        return getBridge().getChannelSummary(defaultAccountId || BNCR_DEFAULT_ACCOUNT_ID);
       },
       buildAccountSnapshot: async ({ account, runtime }: any) => {
-        const rt = runtime || bridge.getAccountRuntimeSnapshot(account?.accountId);
+        const runtimeBridge = getBridge();
+        const rt = runtime || runtimeBridge.getAccountRuntimeSnapshot(account?.accountId);
         const meta = rt?.meta || {};
 
         const pending = Number(rt?.pending ?? meta.pending ?? 0);
@@ -3742,7 +5328,7 @@ export function createBncrChannelPlugin(bridge: BncrBridgeRuntime) {
           mode: normalizedMode,
           pending,
           deadLetter,
-          healthSummary: bridge.getStatusHeadline(account?.accountId),
+          healthSummary: runtimeBridge.getStatusHeadline(account?.accountId),
           lastSessionKey,
           lastSessionScope,
           lastSessionAt,
@@ -3760,7 +5346,7 @@ export function createBncrChannelPlugin(bridge: BncrBridgeRuntime) {
         if (!enabled) return 'disabled';
         const resolved = resolveAccount(cfg, account?.accountId);
         if (!(resolved.enabled && configured)) return 'not configured';
-        const rt = runtime || bridge.getAccountRuntimeSnapshot(account?.accountId);
+        const rt = runtime || getBridge().getAccountRuntimeSnapshot(account?.accountId);
         return rt?.connected ? 'linked' : 'configured';
       },
     },
@@ -3777,8 +5363,8 @@ export function createBncrChannelPlugin(bridge: BncrBridgeRuntime) {
       'bncr.file.ack',
     ],
     gateway: {
-      startAccount: bridge.channelStartAccount,
-      stopAccount: bridge.channelStopAccount,
+      startAccount: async (ctx: any) => getBridge().channelStartAccount(ctx),
+      stopAccount: async (ctx: any) => getBridge().channelStopAccount(ctx),
     },
   };