@agentunion/fastaun 0.2.16 → 0.2.18

package/dist/client.js

@@ -25,6 +25,7 @@ import { EventDispatcher } from './events.js';
 import { FileKeyStore } from './keystore/file.js';
 import { AUNLogger } from './logger.js';
 import { SQLiteBackup } from './keystore/sqlite-backup.js';
+import { normalizeGroupId } from './group-id.js';
 import { AuthNamespace } from './namespaces/auth.js';
 import { CustodyNamespace } from './namespaces/custody.js';
 import { MetaNamespace } from './namespaces/meta.js';
@@ -32,18 +33,6 @@ import { RPCTransport } from './transport.js';
 import { AuthFlow } from './auth.js';
 import { SeqTracker } from './seq-tracker.js';
 import { isJsonObject, } from './types.js';
-// ── 日志辅助 ──────────────────────────────────────────────────
-/** 文件日志（模块级单例） */
-let _debugLogger = null;
-/** 简易日志：前缀 [aun_core.client] */
-function _clientLog(level, msg, ...args) {
-    const ts = new Date().toISOString();
-    const formatted = args.reduce((s, a) => s.replace('%s', String(a)), msg);
-    // eslint-disable-next-line no-console
-    console.log(`[${ts}] [aun_core.client] ${level}: ${formatted}`);
-    if (_debugLogger)
-        _debugLogger.log(`${level}: ${formatted}`);
-}
 /**
  * 递归排序键的 JSON 序列化（Canonical JSON for AUN）
  * 等价于 Python json.dumps(sort_keys=True, separators=(",",":"), ensure_ascii=False)
@@ -386,57 +375,72 @@ export class AUNClient {
     _reconnectActive = false;
     _reconnectAbort = null;
     _serverKicked = false;
+    _logger;
+    _clientLog;
     constructor(config, debug = false) {
         const rawConfig = { ...(config ?? {}) };
         this._configModel = configFromMap(rawConfig);
+        const initAid = String(rawConfig.aid ?? '').trim() || null;
         this.config = {
             aun_path: this._configModel.aunPath,
             root_ca_path: this._configModel.rootCaPath,
             seed_password: this._configModel.seedPassword,
         };
-        this._dispatcher = new EventDispatcher();
+        // 初始化 Logger（per-client 单例，必须最早创建）
+        const debugFlag = this._configModel.debug || debug;
+        this._logger = new AUNLogger({
+            debug: debugFlag,
+            aunPath: this._configModel.aunPath,
+        });
+        this._clientLog = this._logger.for('aun_core.client');
+        if (debugFlag) {
+            this._clientLog.info(`AUNClient initialized (debug=true, aunPath=${this._configModel.aunPath})`);
+        }
+        this._dispatcher = new EventDispatcher(this._logger.for('aun_core.events'));
         this._discovery = new GatewayDiscovery({ verifySsl: this._configModel.verifySsl });
-        const defaultSQLiteBackup = new SQLiteBackup(join(this._configModel.aunPath, '.aun_backup', 'aun_backup.db'));
+        const defaultSQLiteBackup = new SQLiteBackup(join(this._configModel.aunPath, '.aun_backup', 'aun_backup.db'), { logger: this._logger.for('aun_core.keystore') });
         const keystore = new FileKeyStore(this._configModel.aunPath, {
             encryptionSeed: this._configModel.seedPassword ?? undefined,
             sqliteBackup: defaultSQLiteBackup,
+            logger: this._logger.for('aun_core.keystore'),
+            secretStoreLogger: this._logger.for('aun_core.secret-store'),
         });
         this._keystore = keystore;
         this._deviceId = getDeviceId(this._configModel.aunPath);
-        // 初始化文件日志（仅 debug 模式）
-        if (debug) {
-            _debugLogger = new AUNLogger();
-            _clientLog('info', 'AUNClient 初始化完成 (debug=true, aunPath=%s)', this._configModel.aunPath);
-        }
         this._slotId = '';
         this._connectDeliveryMode = normalizeDeliveryModeConfig({ mode: 'fanout' });
         this._defaultConnectDeliveryMode = { ...this._connectDeliveryMode };
         this._auth = new AuthFlow({
             keystore,
             crypto: new CryptoProvider(),
-            aid: null,
+            aid: initAid,
             deviceId: this._deviceId,
             slotId: this._slotId,
             rootCaPath: this._configModel.rootCaPath ?? undefined,
             verifySsl: this._configModel.verifySsl,
+            logger: this._logger.for('aun_core.auth'),
         });
+        this._aid = initAid;
         this._transport = new RPCTransport({
             eventDispatcher: this._dispatcher,
             timeout: 10_000,
             onDisconnect: (err, closeCode) => this._handleTransportDisconnect(err, closeCode),
             verifySsl: this._configModel.verifySsl,
+            logger: this._logger.for('aun_core.transport'),
         });
         this._e2ee = new E2EEManager({
             identityFn: () => this._identity ?? {},
             deviceIdFn: () => this._deviceId,
             keystore,
             replayWindowSeconds: this._configModel.replayWindowSeconds,
+            logger: this._logger.for('aun_core.e2ee'),
         });
         this._groupE2ee = new GroupE2EEManager({
             identityFn: () => this._identity ?? {},
             keystore,
             senderCertResolver: (aid) => this._getVerifiedPeerCert(aid),
             initiatorCertResolver: (aid) => this._getVerifiedPeerCert(aid),
+            logger: this._logger.for('aun_core.e2ee-group'),
         });
         this.auth = new AuthNamespace(this);
         this.custody = new CustodyNamespace(this);
@@ -479,7 +483,17 @@ export class AUNClient {
     }
     /** 向 gatewayUrl 的 /health 端点发送 GET 请求，检查网关可用性 */
     async checkGatewayHealth(gatewayUrl, timeout = 5_000) {
-        return this._discovery.checkHealth(gatewayUrl, timeout);
+        const tStart = Date.now();
+        this._clientLog.debug(`checkGatewayHealth enter: gatewayUrl=${gatewayUrl}`);
+        try {
+            const result = await this._discovery.checkHealth(gatewayUrl, timeout);
+            this._clientLog.debug(`checkGatewayHealth exit: elapsed=${Date.now() - tStart}ms healthy=${result}`);
+            return result;
+        }
+        catch (err) {
+            this._clientLog.debug(`checkGatewayHealth exit (error): elapsed=${Date.now() - tStart}ms err=${err instanceof Error ? err.message : String(err)}`);
+            throw err;
+        }
     }
     // ── 生命周期 ──────────────────────────────────────────────
     /**
@@ -489,6 +503,7 @@ export class AUNClient {
      * @param options - 会话选项（auto_reconnect、heartbeat_interval 等）
      */
     async connect(auth, options) {
+        const tStart = Date.now();
         if (this._state !== 'idle' && this._state !== 'closed' && this._state !== 'disconnected') {
             throw new StateError(`connect not allowed in state ${this._state}`);
         }
@@ -502,77 +517,117 @@ export class AUNClient {
         const callTimeoutSec = this._sessionOptions.timeouts.call;
         this._transport.setTimeout(callTimeoutSec != null ? callTimeoutSec * 1000 : 10_000);
         this._closing = false;
+        this._clientLog.debug(`connect enter: gateway=${String(normalized.gateway ?? '')}, device_id=${this._deviceId}`);
         try {
             await this._connectOnce(normalized, false);
+            this._clientLog.debug(`connect exit: elapsed=${Date.now() - tStart}ms aid=${this._aid ?? ''}, state=${this._state}`);
         }
         catch (err) {
             // 连接失败时回退状态，允许重试
             if (this._state === 'connecting' || this._state === 'authenticating') {
                 this._state = 'disconnected';
             }
+            this._clientLog.error(`connect failed: ${formatCaughtError(err)}`, err instanceof Error ? err : undefined);
+            this._clientLog.debug(`connect exit (error): elapsed=${Date.now() - tStart}ms err=${err instanceof Error ? err.message : String(err)}`);
             throw err;
         }
     }
     /** 关闭连接 */
     async close() {
-        this._closing = true;
-        this._saveSeqTrackerState();
-        this._stopBackgroundTasks();
-        this._stopReconnect();
-        if (this._state === 'idle' || this._state === 'closed') {
+        const tStart = Date.now();
+        this._clientLog.debug(`close enter: state=${this._state}, aid=${this._aid ?? ''}`);
+        try {
+            this._closing = true;
+            this._saveSeqTrackerState();
+            this._stopBackgroundTasks();
+            this._stopReconnect();
+            if (this._state === 'idle' || this._state === 'closed') {
+                const closableKeyStore = this._keystore;
+                closableKeyStore.close?.();
+                this._state = 'closed';
+                this._logger.close();
+                this._resetSeqTrackingState();
+                this._clientLog.debug(`close exit: elapsed=${Date.now() - tStart}ms (was idle/closed)`);
+                return;
+            }
+            await this._transport.close();
             const closableKeyStore = this._keystore;
             closableKeyStore.close?.();
             this._state = 'closed';
+            this._logger.close();
+            await this._dispatcher.publish('connection.state', { state: this._state });
             this._resetSeqTrackingState();
-            return;
+            this._clientLog.debug(`close exit: elapsed=${Date.now() - tStart}ms`);
+        }
+        catch (err) {
+            this._clientLog.debug(`close exit (error): elapsed=${Date.now() - tStart}ms err=${err instanceof Error ? err.message : String(err)}`);
+            throw err;
         }
-        await this._transport.close();
-        const closableKeyStore = this._keystore;
-        closableKeyStore.close?.();
-        this._state = 'closed';
-        await this._dispatcher.publish('connection.state', { state: this._state });
-        this._resetSeqTrackingState();
     }
     /**
      * 断开连接但不关闭客户端（可重新 connect，对齐 Python disconnect）。
      * disconnect 是可恢复的：停止心跳、关闭 WebSocket，但不清理 keystore 等状态。
      */
     async disconnect() {
-        // 若 close() 已在执行中，跳过 disconnect 避免竞态
-        if (this._closing)
-            return;
-        if (this._state !== 'connected' && this._state !== 'reconnecting')
-            return;
-        this._saveSeqTrackerState();
-        this._stopBackgroundTasks();
-        this._stopReconnect();
-        await this._transport.close();
-        this._state = 'disconnected';
-        await this._dispatcher.publish('connection.state', { state: this._state });
+        const tStart = Date.now();
+        this._clientLog.debug(`disconnect enter: state=${this._state}, aid=${this._aid ?? ''}, closing=${this._closing}`);
+        try {
+            // 若 close() 已在执行中，跳过 disconnect 避免竞态
+            if (this._closing) {
+                this._clientLog.debug(`disconnect exit: elapsed=${Date.now() - tStart}ms (closing)`);
+                return;
+            }
+            if (this._state !== 'connected' && this._state !== 'reconnecting') {
+                this._clientLog.debug(`disconnect exit: elapsed=${Date.now() - tStart}ms (state=${this._state})`);
+                return;
+            }
+            this._saveSeqTrackerState();
+            this._stopBackgroundTasks();
+            this._stopReconnect();
+            await this._transport.close();
+            this._state = 'disconnected';
+            await this._dispatcher.publish('connection.state', { state: this._state });
+            this._clientLog.debug(`disconnect exit: elapsed=${Date.now() - tStart}ms`);
+        }
+        catch (err) {
+            this._clientLog.debug(`disconnect exit (error): elapsed=${Date.now() - tStart}ms err=${err instanceof Error ? err.message : String(err)}`);
+            throw err;
+        }
     }
     /**
      * 列出本地所有已存储的身份摘要（仅返回有有效私钥的 AID）。
      */
     listIdentities() {
-        const listFn = this._keystore.listIdentities;
-        if (typeof listFn !== 'function')
-            return [];
-        const aids = listFn.call(this._keystore);
-        const summaries = [];
-        for (const aid of [...aids].sort()) {
-            const identity = this._keystore.loadIdentity(aid);
-            if (!identity || !identity.private_key_pem)
-                continue;
-            const summary = { aid };
-            const loadMetadata = this._keystore.loadMetadata;
-            if (typeof loadMetadata === 'function') {
-                const md = loadMetadata.call(this._keystore, aid);
-                if (md)
-                    summary.metadata = md;
+        const tStart = Date.now();
+        this._clientLog.debug(`listIdentities enter`);
+        try {
+            const listFn = this._keystore.listIdentities;
+            if (typeof listFn !== 'function') {
+                this._clientLog.debug(`listIdentities exit: elapsed=${Date.now() - tStart}ms (no_list_fn)`);
+                return [];
+            }
+            const aids = listFn.call(this._keystore);
+            const summaries = [];
+            for (const aid of [...aids].sort()) {
+                const identity = this._keystore.loadIdentity(aid);
+                if (!identity || !identity.private_key_pem)
+                    continue;
+                const summary = { aid };
+                const loadMetadata = this._keystore.loadMetadata;
+                if (typeof loadMetadata === 'function') {
+                    const md = loadMetadata.call(this._keystore, aid);
+                    if (md)
+                        summary.metadata = md;
+                }
+                summaries.push(summary);
             }
-            summaries.push(summary);
+            this._clientLog.debug(`listIdentities exit: elapsed=${Date.now() - tStart}ms count=${summaries.length}`);
+            return summaries;
+        }
+        catch (err) {
+            this._clientLog.debug(`listIdentities exit (error): elapsed=${Date.now() - tStart}ms err=${err instanceof Error ? err.message : String(err)}`);
+            throw err;
         }
-        return summaries;
     }
     // ── RPC ───────────────────────────────────────────────────
     /**
@@ -580,214 +635,257 @@ export class AUNClient {
      * 自动处理内部方法限制、E2EE 加解密、客户端签名等。
      */
     async call(method, params) {
-        if (this._state !== 'connected') {
-            throw new ConnectionError('client is not connected');
-        }
-        if (INTERNAL_ONLY_METHODS.has(method)) {
-            throw new PermissionError(`method is internal_only: ${method}`);
-        }
-        const p = { ...(params ?? {}) };
-        this._validateOutboundCall(method, p);
-        this._injectMessageCursorContext(method, p);
-        // group.* 方法注入 device_id（服务端用于多设备消息路由）
-        if (method.startsWith('group.') && this._deviceId && p.device_id === undefined) {
-            p.device_id = this._deviceId;
-        }
-        if (method.startsWith('group.') && p.slot_id === undefined) {
-            p.slot_id = this._slotId;
-        }
-        // 自动加密：message.send 默认加密（encrypt 默认 True）
-        if (method === 'message.send') {
-            const encrypt = p.encrypt ?? true;
-            delete p.encrypt;
-            if (encrypt) {
-                return await this._sendEncrypted(p);
-            }
-            delete p.protected_headers;
-            delete p.headers;
-        }
-        // 自动加密：group.send 默认加密（encrypt 默认 True）
-        if (method === 'group.send') {
-            const encrypt = p.encrypt ?? true;
-            delete p.encrypt;
-            if (encrypt) {
-                return await this._sendGroupEncrypted(p);
+        const tStart = Date.now();
+        this._clientLog.debug(`call enter: method=${method}`);
+        try {
+            if (this._state !== 'connected') {
+                throw new ConnectionError('client is not connected');
+            }
+            if (INTERNAL_ONLY_METHODS.has(method)) {
+                throw new PermissionError(`method is internal_only: ${method}`);
+            }
+            const p = { ...(params ?? {}) };
+            this._validateOutboundCall(method, p);
+            this._injectMessageCursorContext(method, p);
+            // group.* 方法注入 device_id（服务端用于多设备消息路由）
+            if (method.startsWith('group.') && this._deviceId && p.device_id === undefined) {
+                p.device_id = this._deviceId;
+            }
+            if (method.startsWith('group.') && p.slot_id === undefined) {
+                p.slot_id = this._slotId;
+            }
+            // 自动加密：message.send 默认加密（encrypt 默认 True）
+            if (method === 'message.send') {
+                const encrypt = p.encrypt ?? true;
+                delete p.encrypt;
+                if (encrypt) {
+                    return await this._sendEncrypted(p);
+                }
+                // encrypt=false：明文走通用 RPC 路径；protected_headers/headers 是信封元数据，加密与否都保留
+            }
+            // 自动加密：group.send 默认加密（encrypt 默认 True）
+            if (method === 'group.send') {
+                const encrypt = p.encrypt ?? true;
+                delete p.encrypt;
+                if (encrypt) {
+                    return await this._sendGroupEncrypted(p);
+                }
             }
-            delete p.protected_headers;
-            delete p.headers;
-        }
-        if (method === 'group.thought.put') {
-            const encrypt = p.encrypt ?? true;
-            delete p.encrypt;
-            if (!encrypt) {
-                throw new ValidationError('group.thought.put requires encrypt=true');
+            if (method === 'group.thought.put') {
+                const encrypt = p.encrypt ?? true;
+                delete p.encrypt;
+                if (encrypt) {
+                    return await this._putGroupThoughtEncrypted(p);
+                }
             }
-            return await this._putGroupThoughtEncrypted(p);
-        }
-        if (method === 'message.thought.put') {
-            const encrypt = p.encrypt ?? true;
-            delete p.encrypt;
-            if (!encrypt) {
-                throw new ValidationError('message.thought.put requires encrypt=true');
-            }
-            return await this._putMessageThoughtEncrypted(p);
-        }
-        // 关键操作自动附加客户端签名
-        if (SIGNED_METHODS.has(method)) {
-            this._signClientOperation(method, p);
-        }
-        // P1-23: 非幂等方法使用更长超时
-        const callTimeout = NON_IDEMPOTENT_METHODS.has(method) ? NON_IDEMPOTENT_TIMEOUT_MS : undefined;
-        let result = callTimeout
-            ? await this._transport.call(method, p, callTimeout)
-            : await this._transport.call(method, p);
-        // 自动解密：message.pull 返回的消息
-        if (method === 'message.pull' && isJsonObject(result)) {
-            const r = result;
-            const messages = r.messages;
-            const rawMessages = Array.isArray(messages) ? messages.filter(isJsonObject) : [];
-            if (rawMessages.length > 0) {
-                r.messages = await this._decryptMessages(rawMessages);
+            if (method === 'message.thought.put') {
+                const encrypt = p.encrypt ?? true;
+                delete p.encrypt;
+                if (encrypt) {
+                    return await this._putMessageThoughtEncrypted(p);
+                }
             }
-            if (this._aid) {
-                const ns = `p2p:${this._aid}`;
+            // 关键操作自动附加客户端签名
+            if (SIGNED_METHODS.has(method)) {
+                this._signClientOperation(method, p);
+            }
+            // P1-23: 非幂等方法使用更长超时
+            const callTimeout = NON_IDEMPOTENT_METHODS.has(method) ? NON_IDEMPOTENT_TIMEOUT_MS : undefined;
+            let result = callTimeout
+                ? await this._transport.call(method, p, callTimeout)
+                : await this._transport.call(method, p);
+            // 自动解密：message.pull 返回的消息
+            if (method === 'message.pull' && isJsonObject(result)) {
+                const r = result;
+                const messages = r.messages;
+                const rawMessages = Array.isArray(messages) ? messages.filter(isJsonObject) : [];
+                this._clientLog.debug(`message.pull result: ${rawMessages.length} messages`);
                 if (rawMessages.length > 0) {
-                    this._seqTracker.onPullResult(ns, rawMessages);
-                }
-                // ⚠️ 逻辑边界 L1/L3：P2P retention floor 通道 = server_ack_seq
-                // 服务端在持久化/设备视图分支返回 server_ack_seq，客户端若 contiguous 落后必须 force 跳过
-                // retention window 外的空洞。与 S2 [1,seq-1] 历史 gap 配合；若去掉 force，首条消息建的 gap 会
-                // 永远悬挂触发无限 pull。临时消息淘汰走 ephemeral_earliest_available_seq（当前仅提示），与此互斥。
-                const serverAck = Number(r.server_ack_seq ?? 0);
-                if (serverAck > 0) {
-                    const contig = this._seqTracker.getContiguousSeq(ns);
-                    if (contig < serverAck) {
-                        _clientLog('info', 'message.pull retention-floor 推进: ns=%s contiguous=%d -> server_ack_seq=%d', ns, contig, serverAck);
-                        this._seqTracker.forceContiguousSeq(ns, serverAck);
-                    }
+                    r.messages = await this._decryptMessages(rawMessages);
                 }
-                this._saveSeqTrackerState();
-                // auto-ack contiguous_seq
-                const contig = this._seqTracker.getContiguousSeq(ns);
-                if (contig > 0 && (rawMessages.length > 0 || serverAck > 0)) {
-                    this._transport.call('message.ack', {
-                        seq: contig,
-                        device_id: this._deviceId,
-                        slot_id: this._slotId,
-                    }).catch((e) => { _clientLog('debug', 'message.pull auto-ack 失败: %s', formatCaughtError(e)); });
-                }
-            }
-        }
-        // 自动解密：group.pull 返回的群消息
-        if (method === 'group.pull' && isJsonObject(result)) {
-            const r = result;
-            const messages = r.messages;
-            const rawMessages = Array.isArray(messages) ? messages.filter(isJsonObject) : [];
-            if (rawMessages.length > 0) {
-                r.messages = await this._decryptGroupMessages(rawMessages);
-            }
-            const gid = (p.group_id ?? '');
-            if (gid) {
-                const ns = `group:${gid}`;
-                if (rawMessages.length > 0) {
-                    this._seqTracker.onPullResult(ns, rawMessages);
-                }
-                // ⚠️ 逻辑边界 L4：group retention floor 通道 = cursor.current_seq
-                // 群路径目前无独立 earliest_available_seq 字段；若未来引入 group retention，需新增字段并同步更新此处。
-                // 与 S2 [1,seq-1] 历史 gap 配合使用，force_contiguous_seq 是跳过空洞的唯一手段。
-                const cursor = isJsonObject(r.cursor) ? r.cursor : null;
-                if (cursor) {
-                    const serverAck = Number(cursor.current_seq ?? 0);
+                if (this._aid) {
+                    const ns = `p2p:${this._aid}`;
+                    if (rawMessages.length > 0) {
+                        this._seqTracker.onPullResult(ns, rawMessages);
+                    }
+                    // ⚠️ 逻辑边界 L1/L3：P2P retention floor 通道 = server_ack_seq
+                    // 服务端在持久化/设备视图分支返回 server_ack_seq，客户端若 contiguous 落后必须 force 跳过
+                    // retention window 外的空洞。与 S2 [1,seq-1] 历史 gap 配合；若去掉 force，首条消息建的 gap 会
+                    // 永远悬挂触发无限 pull。临时消息淘汰走 ephemeral_earliest_available_seq（当前仅提示），与此互斥。
+                    const serverAck = Number(r.server_ack_seq ?? 0);
                     if (serverAck > 0) {
                         const contig = this._seqTracker.getContiguousSeq(ns);
                         if (contig < serverAck) {
-                            _clientLog('info', 'group.pull retention-floor 推进: ns=%s contiguous=%d -> cursor.current_seq=%d', ns, contig, serverAck);
+                            this._clientLog.info(`message.pull retention-floor advance: ns=${ns} contiguous=${contig} -> server_ack_seq=${serverAck}`);
                             this._seqTracker.forceContiguousSeq(ns, serverAck);
                         }
                     }
+                    this._saveSeqTrackerState();
+                    // auto-ack contiguous_seq
+                    const contig = this._seqTracker.getContiguousSeq(ns);
+                    if (contig > 0 && (rawMessages.length > 0 || serverAck > 0)) {
+                        this._transport.call('message.ack', {
+                            seq: contig,
+                            device_id: this._deviceId,
+                            slot_id: this._slotId,
+                        }).catch((e) => { this._clientLog.debug(`message.pull auto-ack failed: ${formatCaughtError(e)}`); });
+                    }
                 }
-                this._saveSeqTrackerState();
-                // auto-ack contiguous_seq
-                const contig = this._seqTracker.getContiguousSeq(ns);
-                const shouldAck = rawMessages.length > 0 || (cursor !== null && Number(cursor.current_seq ?? 0) > 0);
-                if (contig > 0 && shouldAck) {
-                    this._transport.call('group.ack_messages', {
-                        group_id: gid,
-                        msg_seq: contig,
-                        device_id: this._deviceId,
-                        slot_id: this._slotId,
-                    }).catch((e) => { _clientLog('debug', 'group.pull auto-ack 失败: group=%s %s', gid, formatCaughtError(e)); });
-                }
-            }
-        }
-        if (method === 'group.thought.get' && isJsonObject(result)) {
-            result = await this._decryptGroupThoughts(result);
-        }
-        if (method === 'message.thought.get' && isJsonObject(result)) {
-            result = await this._decryptMessageThoughts(result);
-        }
-        // ── Group E2EE 自动编排（必备能力，始终启用）────────
-        {
-            // 建群后自动创建 epoch（幂等：已有 secret 时跳过）
-            if (method === 'group.create' && isJsonObject(result)) {
-                const group = isJsonObject(result.group) ? result.group : null;
-                const gid = group ? String(group.group_id ?? '') : '';
-                if (gid && this._aid && !this._groupE2ee.hasSecret(gid)) {
-                    try {
-                        this._groupE2ee.createEpoch(gid, [this._aid]);
-                        // 同步到服务端：将服务端 epoch 从 0 推到 1；必须在 group.create 返回前完成，
-                        // 否则调用方紧接着加成员时会让初始 rotation 因成员集变化而提交失败。
-                        await this._syncEpochToServer(gid);
+            }
+            // 自动解密：group.pull 返回的群消息
+            if (method === 'group.pull' && isJsonObject(result)) {
+                const r = result;
+                const messages = r.messages;
+                const rawMessages = Array.isArray(messages) ? messages.filter(isJsonObject) : [];
+                this._clientLog.debug(`group.pull result: group_id=${String(p.group_id ?? '')}, ${rawMessages.length} messages`);
+                if (rawMessages.length > 0) {
+                    r.messages = await this._decryptGroupMessages(rawMessages);
+                }
+                const gid = (p.group_id ?? '');
+                if (gid) {
+                    const ns = `group:${gid}`;
+                    if (rawMessages.length > 0) {
+                        this._seqTracker.onPullResult(ns, rawMessages);
+                    }
+                    // ⚠️ 逻辑边界 L4：group retention floor 通道 = cursor.current_seq
+                    // 群路径目前无独立 earliest_available_seq 字段；若未来引入 group retention，需新增字段并同步更新此处。
+                    // 与 S2 [1,seq-1] 历史 gap 配合使用，force_contiguous_seq 是跳过空洞的唯一手段。
+                    const cursor = isJsonObject(r.cursor) ? r.cursor : null;
+                    if (cursor) {
+                        const serverAck = Number(cursor.current_seq ?? 0);
+                        if (serverAck > 0) {
+                            const contig = this._seqTracker.getContiguousSeq(ns);
+                            if (contig < serverAck) {
+                                this._clientLog.info(`group.pull retention-floor advance: ns=${ns} contiguous=${contig} -> cursor.current_seq=${serverAck}`);
+                                this._seqTracker.forceContiguousSeq(ns, serverAck);
+                            }
+                        }
                     }
-                    catch (exc) {
-                        this._logE2eeError('create_epoch', gid, '', exc);
+                    this._saveSeqTrackerState();
+                    // auto-ack contiguous_seq
+                    const contig = this._seqTracker.getContiguousSeq(ns);
+                    const shouldAck = rawMessages.length > 0 || (cursor !== null && Number(cursor.current_seq ?? 0) > 0);
+                    if (contig > 0 && shouldAck) {
+                        this._transport.call('group.ack_messages', {
+                            group_id: gid,
+                            msg_seq: contig,
+                            device_id: this._deviceId,
+                            slot_id: this._slotId,
+                        }).catch((e) => { this._clientLog.debug(`group.pull auto-ack failed: group=${gid} ${formatCaughtError(e)}`); });
                     }
                 }
             }
-            // 入群类 RPC 的成员集变更统一由 group.changed 事件驱动 epoch 轮换。
-        }
-        // 成员集变更主要由 group.changed 事件驱动；RPC 成功返回路径做幂等兜底，避免事件丢失或延迟时不轮换。
-        const membershipMethods = new Set([
-            'group.add_member', 'group.kick', 'group.remove_member', 'group.leave',
-            'group.review_join_request', 'group.batch_review_join_request',
-            'group.use_invite_code', 'group.request_join',
-        ]);
-        if (membershipMethods.has(method) && isJsonObject(result) && !('error' in result)) {
-            const groupId = this._extractGroupIdFromResult(result) || String(p.group_id ?? '');
-            if (groupId && this._membershipRotationChanged(method, result)) {
-                const expectedEpoch = this._membershipRotationExpectedEpoch(result);
-                // 自加入方法（request_join/use_invite_code）需要 allowMember=true，
-                // 因为新成员角色是 member，必须允许 member 参与 leader 选举。
-                const allowMember = method === 'group.request_join' || method === 'group.use_invite_code';
-                // P0-12: await rotation 完成（带超时兜底），确保后续 group.send 使用新 epoch
-                const rotationPromise = this._maybeLeadRotateGroupEpoch(groupId, this._membershipRotationTriggerId(groupId, result), expectedEpoch, allowMember);
-                const timeoutPromise = new Promise((resolve) => globalThis.setTimeout(resolve, 5000));
-                await Promise.race([rotationPromise, timeoutPromise]).catch((exc) => _clientLog('warn', 'membership RPC epoch rotation fallback failed: %s', formatCaughtError(exc)));
+            if (method === 'group.thought.get' && isJsonObject(result)) {
+                result = await this._decryptGroupThoughts(result);
+            }
+            if (method === 'message.thought.get' && isJsonObject(result)) {
+                result = await this._decryptMessageThoughts(result);
+            }
+            // ── Group E2EE 自动编排（必备能力，始终启用）────────
+            {
+                // 建群后自动创建 epoch（幂等：已有 secret 时跳过）
+                if (method === 'group.create' && isJsonObject(result)) {
+                    const group = isJsonObject(result.group) ? result.group : null;
+                    const gid = group ? String(group.group_id ?? '') : '';
+                    if (gid && this._aid && !this._groupE2ee.hasSecret(gid)) {
+                        try {
+                            this._groupE2ee.createEpoch(gid, [this._aid]);
+                            // 同步到服务端：将服务端 epoch 从 0 推到 1；必须在 group.create 返回前完成，
+                            // 否则调用方紧接着加成员时会让初始 rotation 因成员集变化而提交失败。
+                            await this._syncEpochToServer(gid);
+                        }
+                        catch (exc) {
+                            this._logE2eeError('create_epoch', gid, '', exc);
+                        }
+                    }
+                }
+                // 入群类 RPC 的成员集变更统一由 group.changed 事件驱动 epoch 轮换。
+            }
+            // 成员集变更主要由 group.changed 事件驱动；RPC 成功返回路径做幂等兜底，避免事件丢失或延迟时不轮换。
+            const membershipMethods = new Set([
+                'group.add_member', 'group.kick', 'group.remove_member', 'group.leave',
+                'group.review_join_request', 'group.batch_review_join_request',
+                'group.use_invite_code', 'group.request_join',
+            ]);
+            if (membershipMethods.has(method) && isJsonObject(result) && !('error' in result)) {
+                const groupId = this._extractGroupIdFromResult(result) || String(p.group_id ?? '');
+                if (groupId && this._membershipRotationChanged(method, result)) {
+                    const expectedEpoch = this._membershipRotationExpectedEpoch(result);
+                    // 自加入方法（request_join/use_invite_code）需要 allowMember=true，
+                    // 因为新成员角色是 member，必须允许 member 参与 leader 选举。
+                    const allowMember = method === 'group.request_join' || method === 'group.use_invite_code';
+                    // P0-12: await rotation 完成（带超时兜底），确保后续 group.send 使用新 epoch
+                    const rotationPromise = this._maybeLeadRotateGroupEpoch(groupId, this._membershipRotationTriggerId(groupId, result), expectedEpoch, allowMember);
+                    const timeoutPromise = new Promise((resolve) => globalThis.setTimeout(resolve, 5000));
+                    await Promise.race([rotationPromise, timeoutPromise]).catch((exc) => this._clientLog.warn(`membership RPC epoch rotation fallback failed: ${formatCaughtError(exc)}`));
+                }
             }
+            this._clientLog.debug(`call exit: method=${method} elapsed=${Date.now() - tStart}ms`);
+            return result;
+        }
+        catch (err) {
+            this._clientLog.debug(`call exit (error): method=${method} elapsed=${Date.now() - tStart}ms err=${err instanceof Error ? err.message : String(err)}`);
+            throw err;
         }
-        return result;
     }
     // ── 便利方法 ──────────────────────────────────────────────
     /** 心跳检测 */
     async ping(params) {
-        return await this.call('meta.ping', params ?? {});
+        const tStart = Date.now();
+        this._clientLog.debug(`ping enter`);
+        try {
+            const result = await this.call('meta.ping', params ?? {});
+            this._clientLog.debug(`ping exit: elapsed=${Date.now() - tStart}ms`);
+            return result;
+        }
+        catch (err) {
+            this._clientLog.debug(`ping exit (error): elapsed=${Date.now() - tStart}ms err=${err instanceof Error ? err.message : String(err)}`);
+            throw err;
+        }
     }
     /** 获取服务端状态 */
     async status(params) {
-        return await this.call('meta.status', params ?? {});
+        const tStart = Date.now();
+        this._clientLog.debug(`status enter`);
+        try {
+            const result = await this.call('meta.status', params ?? {});
+            this._clientLog.debug(`status exit: elapsed=${Date.now() - tStart}ms`);
+            return result;
+        }
+        catch (err) {
+            this._clientLog.debug(`status exit (error): elapsed=${Date.now() - tStart}ms err=${err instanceof Error ? err.message : String(err)}`);
+            throw err;
+        }
     }
     /** 获取信任根证书列表 */
     async trustRoots(params) {
-        return await this.call('meta.trust_roots', params ?? {});
+        const tStart = Date.now();
+        this._clientLog.debug(`trustRoots enter`);
+        try {
+            const result = await this.call('meta.trust_roots', params ?? {});
+            this._clientLog.debug(`trustRoots exit: elapsed=${Date.now() - tStart}ms`);
+            return result;
+        }
+        catch (err) {
+            this._clientLog.debug(`trustRoots exit (error): elapsed=${Date.now() - tStart}ms err=${err instanceof Error ? err.message : String(err)}`);
+            throw err;
+        }
     }
     // ── 事件 ──────────────────────────────────────────────────
     /** 订阅事件 */
     on(event, handler) {
-        return this._dispatcher.subscribe(event, handler);
+        const tStart = Date.now();
+        this._clientLog.debug(`on enter: event=${event}`);
+        const result = this._dispatcher.subscribe(event, handler);
+        this._clientLog.debug(`on exit: elapsed=${Date.now() - tStart}ms event=${event}`);
+        return result;
     }
     /** P2-13: 取消订阅事件（对齐 Python/JS off 方法） */
     off(event, handler) {
+        const tStart = Date.now();
+        this._clientLog.debug(`off enter: event=${event}`);
         this._dispatcher.unsubscribe(event, handler);
+        this._clientLog.debug(`off exit: elapsed=${Date.now() - tStart}ms event=${event}`);
     }
     // ── E2EE 加密发送 ────────────────────────────────────────
     _protectedHeadersFromParams(params) {
@@ -803,6 +901,7 @@ export class AUNClient {
     }
     /** 自动加密并发送 P2P 消息 */
     async _sendEncrypted(params) {
+        const tStart = Date.now();
         const toAid = String(params.to ?? '');
         this._validateMessageRecipient(toAid);
         const payload = isJsonObject(params.payload) ? params.payload : null;
@@ -813,6 +912,7 @@ export class AUNClient {
         }
         const persistRequired = Boolean(params.persist_required || params.durable);
         const protectedHeaders = this._protectedHeadersFromParams(params);
+        this._clientLog.debug(`_sendEncrypted enter: to=${toAid}, message_id=${messageId}`);
         // 惰性同步：首次发送 P2P 消息时先 pull 一次
         if (!this._p2pSynced) {
             await this._lazySyncP2p();
@@ -876,18 +976,33 @@ export class AUNClient {
         };
         // 首次尝试（使用缓存）；若对端证书/prekey 过期导致指纹不匹配，清缓存后重试一次
         try {
-            return await sendAttempt(false);
+            const result = await sendAttempt(false);
+            this._clientLog.debug(`_sendEncrypted exit: elapsed=${Date.now() - tStart}ms to=${toAid}, message_id=${messageId}`);
+            return result;
         }
         catch (exc) {
-            if (!isRetryablePeerMaterialError(exc))
+            if (!isRetryablePeerMaterialError(exc)) {
+                this._clientLog.error(`message.send failed: to=${toAid}, message_id=${messageId}, err=${formatCaughtError(exc)}`, exc instanceof Error ? exc : undefined);
+                this._clientLog.debug(`_sendEncrypted exit (error): elapsed=${Date.now() - tStart}ms to=${toAid} err=${exc instanceof Error ? exc.message : String(exc)}`);
                 throw exc;
-            _clientLog('warn', 'peer cert/prekey mismatch for %s, refreshing and retrying once', toAid);
+            }
+            this._clientLog.warn(`peer cert/prekey mismatch for ${toAid}, refreshing and retrying once`);
+        }
+        try {
+            const retryResult = await sendAttempt(true);
+            this._clientLog.debug(`_sendEncrypted exit: elapsed=${Date.now() - tStart}ms (retry success) to=${toAid}, message_id=${messageId}`);
+            return retryResult;
+        }
+        catch (exc) {
+            this._clientLog.debug(`_sendEncrypted exit (error): elapsed=${Date.now() - tStart}ms (retry failed) to=${toAid} err=${exc instanceof Error ? exc.message : String(exc)}`);
+            throw exc;
         }
-        return await sendAttempt(true);
     }
     async _sendEncryptedSingle(opts) {
+        this._clientLog.debug(`_sendEncryptedSingle enter: to=${opts.toAid}, message_id=${opts.messageId}, has_prekey=${!!opts.prekey}, persist_required=${!!opts.persistRequired}`);
         let prekey = opts.prekey ?? null;
         if (!prekey) {
+            this._clientLog.debug(`_sendEncryptedSingle fetching peer prekey: to=${opts.toAid}`);
             prekey = await this._fetchPeerPrekey(opts.toAid);
         }
         const peerCertFingerprint = typeof prekey?.cert_fingerprint === 'string' ? prekey.cert_fingerprint : undefined;
@@ -902,6 +1017,7 @@ export class AUNClient {
             protectedHeaders: opts.protectedHeaders,
         });
         this._ensureEncryptResult(opts.toAid, encryptResult);
+        this._clientLog.debug(`_sendEncryptedSingle envelope built: to=${opts.toAid}, message_id=${opts.messageId}, scheme=${String(envelope?.scheme ?? '')}`);
         const sendParams = {
             to: opts.toAid,
             payload: envelope,
@@ -916,6 +1032,7 @@ export class AUNClient {
         return await this._transport.call('message.send', sendParams);
     }
     async _buildRecipientDeviceCopies(opts) {
+        this._clientLog.debug(`_buildRecipientDeviceCopies enter: to=${opts.toAid}, message_id=${opts.messageId}, prekey_count=${opts.prekeys.length}`);
         const recipientCopies = [];
         const certCache = new Map();
         for (const prekey of normalizePeerPrekeys(opts.prekeys)) {
@@ -945,6 +1062,7 @@ export class AUNClient {
         if (recipientCopies.length === 0) {
             throw new E2EEError(`no recipient device copies generated for ${opts.toAid}`);
         }
+        this._clientLog.debug(`_buildRecipientDeviceCopies built: to=${opts.toAid}, message_id=${opts.messageId}, copies=${recipientCopies.length}`);
         return recipientCopies;
     }
     async _resolveSelfCopyPeerCert(certFingerprint) {
@@ -993,7 +1111,7 @@ export class AUNClient {
             }
             catch (e) {
                 // 旧设备的 prekey 可能携带已轮换的证书指纹，跳过该设备的自同步副本
-                _clientLog('warn', `self-sync 跳过设备 ${deviceId}: 证书解析失败 (${e})，可能是旧 prekey`);
+                this._clientLog.warn(`self-sync skip device ${deviceId}: cert parse failed (${e}), possibly old prekey`);
                 continue;
             }
             const [envelope, encryptResult] = this._encryptCopyPayload({
@@ -1031,16 +1149,27 @@ export class AUNClient {
                 mode: encryptResult.mode,
                 reason: encryptResult.degradation_reason,
             }).catch((exc) => {
-                _clientLog('warn', '发布 e2ee.degraded 事件失败: %s', formatCaughtError(exc));
+                this._clientLog.warn(`failed to publish e2ee.degraded event: ${formatCaughtError(exc)}`);
             });
         }
     }
     /** 自动加密并发送群组消息 */
     async _sendGroupEncrypted(params) {
-        return await this._callGroupEncryptedRpc('group.send', params, {
-            idField: 'message_id',
-            idPrefix: 'gm',
-        });
+        const tStart = Date.now();
+        const groupId = String(params.group_id ?? '');
+        this._clientLog.debug(`_sendGroupEncrypted enter: group_id=${groupId}`);
+        try {
+            const result = await this._callGroupEncryptedRpc('group.send', params, {
+                idField: 'message_id',
+                idPrefix: 'gm',
+            });
+            this._clientLog.debug(`_sendGroupEncrypted exit: elapsed=${Date.now() - tStart}ms group_id=${groupId}`);
+            return result;
+        }
+        catch (err) {
+            this._clientLog.debug(`_sendGroupEncrypted exit (error): elapsed=${Date.now() - tStart}ms group_id=${groupId} err=${err instanceof Error ? err.message : String(err)}`);
+            throw err;
+        }
     }
     async _putGroupThoughtEncrypted(params) {
         return await this._callGroupEncryptedRpc('group.thought.put', params, {
@@ -1092,14 +1221,17 @@ export class AUNClient {
         let { sendParams, groupId } = await this._prepareGroupEncryptedRpcParams(method, params, options);
         for (let attempt = 0; attempt < 2; attempt += 1) {
             try {
-                return await this._transport.call(method, sendParams);
+                const result = await this._transport.call(method, sendParams);
+                this._clientLog.debug(`${method} send success: group_id=${groupId}`);
+                return result;
             }
             catch (exc) {
                 if (attempt === 0 && this._isRecoverableGroupEpochError(exc)) {
-                    _clientLog('warn', '群 %s 调用 %s 时 epoch 已过旧，恢复密钥后重加密重试一次: %s', groupId, method, formatCaughtError(exc));
+                    this._clientLog.warn(`group ${groupId} ${method} epoch stale, recovering key and retrying: ${formatCaughtError(exc)}`);
                     ({ sendParams, groupId } = await this._prepareGroupEncryptedRpcParams(method, params, options, true));
                     continue;
                 }
+                this._clientLog.error(`${method} send failed: group_id=${groupId}, err=${formatCaughtError(exc)}`, exc instanceof Error ? exc : undefined);
                 throw exc;
             }
         }
@@ -1114,6 +1246,7 @@ export class AUNClient {
         if (payload === null) {
             throw new ValidationError(`${method} payload must be an object when encrypt=true`);
         }
+        this._clientLog.debug(`${method} encrypt prepare: group_id=${groupId}, strictEpochReady=${String(strictEpochReady)}`);
         if (!this._groupSynced.has(groupId)) {
             await this._lazySyncGroup(groupId);
         }
@@ -1182,11 +1315,11 @@ export class AUNClient {
             }
             if (messages.length > 0) {
                 this._saveSeqTrackerState();
-                _clientLog('info', '惰性同步群 %s: pull %d 条消息, after_seq=%d', groupId, messages.length, afterSeq);
+                this._clientLog.info(`lazy sync group ${groupId}: pull ${messages.length} messages, after_seq=${afterSeq}`);
             }
         }
         catch (exc) {
-            _clientLog('warn', '惰性同步群 %s 失败: %s', groupId, formatCaughtError(exc));
+            this._clientLog.warn(`lazy sync group ${groupId} failed: ${formatCaughtError(exc)}`);
         }
     }
     /** 惰性同步：首次激活 P2P 通道时 pull 最近消息，建立 seq 基线 */
@@ -1209,11 +1342,11 @@ export class AUNClient {
             }
             if (messages.length > 0) {
                 this._saveSeqTrackerState();
-                _clientLog('info', '惰性同步 P2P: pull %d 条消息, after_seq=%d', messages.length, afterSeq);
+                this._clientLog.info(`lazy sync P2P: pull ${messages.length} messages, after_seq=${afterSeq}`);
             }
         }
         catch (exc) {
-            _clientLog('warn', '惰性同步 P2P 失败: %s', formatCaughtError(exc));
+            this._clientLog.warn(`lazy sync P2P failed: ${formatCaughtError(exc)}`);
         }
     }
     _isGroupEpochTooOldError(exc) {
@@ -1269,10 +1402,10 @@ export class AUNClient {
                 encrypt: true,
                 persist_required: true,
             });
-            _clientLog('info', '已向 %s 请求群 %s 的 epoch %s 密钥', targetAid, groupId, epoch);
+            this._clientLog.info(`requested group ${groupId} epoch ${epoch} key from ${targetAid}`);
         }
         catch (exc) {
-            _clientLog('warn', '向 %s 请求群 %s 密钥失败: %s', targetAid, groupId, formatCaughtError(exc));
+            this._clientLog.warn(`requesting group ${groupId} key from ${targetAid} failed: ${formatCaughtError(exc)}`);
         }
     }
     async _requestGroupKeyFromCandidates(groupId, serverEpoch, epochResult) {
@@ -1287,7 +1420,7 @@ export class AUNClient {
         const secretData = this._groupE2ee.loadSecret(groupId, 1);
         if (!secretData || secretData.pending_rotation_id)
             return epochResult;
-        _clientLog('warn', '群 %s 检测到本地 epoch 1 已存在但服务端 epoch 仍为 0，尝试补同步初始 epoch', groupId);
+        this._clientLog.warn(`group ${groupId} detected local epoch 1 exists but server epoch still 0, attempting initial epoch resync`);
         await this._syncEpochToServer(groupId);
         try {
             const refreshed = await this.call('group.e2ee.get_epoch', { group_id: groupId });
@@ -1295,7 +1428,7 @@ export class AUNClient {
                 return refreshed;
         }
         catch (exc) {
-            _clientLog('warn', '群 %s 初始 epoch 补同步后刷新服务端 epoch 失败: %s', groupId, formatCaughtError(exc));
+            this._clientLog.warn(`group ${groupId} initial epoch resync refresh server epoch failed: ${formatCaughtError(exc)}`);
         }
         return epochResult;
     }
@@ -1312,7 +1445,7 @@ export class AUNClient {
         catch (exc) {
             if (strict)
                 throw new StateError(`group ${groupId} failed to query server epoch before retry: ${formatCaughtError(exc)}`);
-            _clientLog('warn', 'group %s epoch precheck failed: %s', groupId, formatCaughtError(exc));
+            this._clientLog.warn(`group ${groupId} epoch precheck failed: ${formatCaughtError(exc)}`);
             return;
         }
         let serverEpoch = Number(epochResult.committed_epoch ?? epochResult.epoch ?? 0);
@@ -1360,7 +1493,7 @@ export class AUNClient {
                 throw new StateError(`group ${groupId} epoch rotation has not completed`);
             }
         }
-        _clientLog('warn', 'group %s local epoch=%s < server epoch=%s; requesting key recovery', groupId, effectiveLocalEpoch, serverEpoch);
+        this._clientLog.warn(`group ${groupId} local epoch=${effectiveLocalEpoch} < server epoch=${serverEpoch}; requesting key recovery`);
         await this._recoverGroupEpochKey(groupId, serverEpoch, '', 5000);
         const deadline = Date.now() + 5000;
         while (Date.now() < deadline) {
@@ -1384,7 +1517,7 @@ export class AUNClient {
                 members = isJsonObject(membersResult) ? membersResult.members : null;
             }
             catch (exc) {
-                _clientLog('debug', '群 %s 成员 epoch floor 预检跳过: %s', groupId, formatCaughtError(exc));
+                this._clientLog.debug(`group ${groupId} member epoch floor pre-check skipped: ${formatCaughtError(exc)}`);
                 return;
             }
             let maxMinReadEpoch = 0;
@@ -1399,7 +1532,7 @@ export class AUNClient {
             }
             if (maxMinReadEpoch <= committedEpoch)
                 return;
-            _clientLog('warn', '群 %s 成员 min_read_epoch 高于 committed epoch，按 committed epoch 继续发送: committed=%s floor=%s', groupId, committedEpoch, maxMinReadEpoch);
+            this._clientLog.warn(`group ${groupId} member min_read_epoch higher than committed epoch, continuing with committed epoch: committed=${committedEpoch} floor=${maxMinReadEpoch}`);
             return;
         }
     }
@@ -1410,7 +1543,7 @@ export class AUNClient {
                 return epochResult;
         }
         catch (exc) {
-            _clientLog('warn', '群 %s 查询 committed epoch 状态失败，回退本地 epoch: %s', groupId, formatCaughtError(exc));
+            this._clientLog.warn(`group ${groupId} query committed epoch status failed, falling back to local epoch: ${formatCaughtError(exc)}`);
         }
         const localEpoch = await this._groupE2ee.currentEpoch(groupId);
         return { epoch: localEpoch ?? 0, committed_epoch: localEpoch ?? 0 };
@@ -1438,7 +1571,7 @@ export class AUNClient {
         let committedRotation = isJsonObject(epochResult.committed_rotation) ? epochResult.committed_rotation : null;
         if (await this._committedRotationMembershipGap(groupId, committedEpoch, committedRotation)) {
             const allowMember = await this._groupAllowsMemberEpochRotation(groupId);
-            _clientLog('warn', '群 %s committed epoch %s 的成员快照与当前成员不一致，触发成员变更轮换修复', groupId, committedEpoch);
+            this._clientLog.warn(`group ${groupId} committed epoch ${committedEpoch} member snapshot inconsistent with current members, triggering membership change rotation`);
             await this._maybeLeadRotateGroupEpoch(groupId, `${groupId}:committed_membership_gap:aid:${this._aid}:epoch:${committedEpoch}`, committedEpoch, allowMember);
             const refreshed = await this._committedGroupEpochState(groupId);
             const refreshedCommittedEpoch = Number(refreshed.committed_epoch ?? refreshed.epoch ?? committedEpoch);
@@ -1455,7 +1588,7 @@ export class AUNClient {
             return committedEpoch;
         }
         const pendingRotationId = secretData ? String(secretData.pending_rotation_id ?? '') : '';
-        _clientLog('warn', '群 %s epoch %s 本地 pending key 未匹配服务端 committed rotation，先恢复密钥: local_rotation=%s', groupId, committedEpoch, pendingRotationId || '-');
+        this._clientLog.warn(`group ${groupId} epoch ${committedEpoch} local pending key does not match server committed rotation, recovering key first: local_rotation=${pendingRotationId || '-'}`);
         await this._recoverGroupEpochKey(groupId, committedEpoch, '', 5000);
         let refreshed = await this._committedGroupEpochState(groupId);
         const refreshedCommittedEpoch = Number(refreshed.committed_epoch ?? refreshed.epoch ?? committedEpoch);
@@ -1500,13 +1633,13 @@ export class AUNClient {
             if (activeMembers.join('\n') !== expectedMembers.join('\n')) {
                 const missing = activeMembers.filter((aid) => !expectedMembers.includes(aid));
                 const extra = expectedMembers.filter((aid) => !activeMembers.includes(aid));
-                _clientLog('info', '群 %s committed membership gap: epoch=%s missing=%s extra=%s', groupId, committedEpoch, JSON.stringify(missing), JSON.stringify(extra));
+                this._clientLog.info(`group ${groupId} committed membership gap: epoch=${committedEpoch} missing=${JSON.stringify(missing)} extra=${JSON.stringify(extra)}`);
                 return true;
             }
             return false;
         }
         catch (exc) {
-            _clientLog('debug', '查询当前成员失败，无法判断 committed membership gap: group=%s err=%s', groupId, formatCaughtError(exc));
+            this._clientLog.debug(`query current members failed, cannot determine committed membership gap: group=${groupId} err=${formatCaughtError(exc)}`);
             return false;
         }
     }
@@ -1556,9 +1689,16 @@ export class AUNClient {
     // ── 事件自动解密管线 ──────────────────────────────────────
     /** 处理 transport 层推送的原始 P2P 消息 */
     async _onRawMessageReceived(data) {
+        const tStart = Date.now();
+        if (isJsonObject(data)) {
+            this._clientLog.debug(`_onRawMessageReceived enter: from=${String(data.from ?? '')}, message_id=${String(data.message_id ?? '')}, seq=${String(data.seq ?? '')}`);
+        }
+        else {
+            this._clientLog.debug(`_onRawMessageReceived enter: non-object payload`);
+        }
         // 异步处理，不阻塞事件调度
         this._processAndPublishMessage(data).catch((exc) => {
-            _clientLog('warn', 'P2P 消息解密失败: %s', formatCaughtError(exc));
+            this._clientLog.warn(`P2P message decrypt failed: ${formatCaughtError(exc)}`);
             // H26: 不再投递原始密文 payload；改发 message.undecryptable 事件，仅携带安全 header
             if (isJsonObject(data)) {
                 const safeEvent = {
@@ -1572,6 +1712,7 @@ export class AUNClient {
                 this._publishAppEvent('message.undecryptable', safeEvent).catch(() => { });
             }
         });
+        this._clientLog.debug(`_onRawMessageReceived exit: elapsed=${Date.now() - tStart}ms (handler dispatched)`);
     }
     /** 实际处理推送消息的异步任务 */
     async _processAndPublishMessage(data) {
@@ -1594,7 +1735,8 @@ export class AUNClient {
             const ns = `p2p:${this._aid}`;
             const needPull = this._seqTracker.onMessageSeq(ns, seq);
             if (needPull) {
-                this._fillP2pGap().catch(exc => _clientLog('warn', '后台补洞触发失败: %s', formatCaughtError(exc)));
+                this._clientLog.debug(`P2P seq gap detected: ns=${ns}, seq=${seq}, contiguous=${this._seqTracker.getContiguousSeq(ns)}`);
+                this._fillP2pGap().catch(exc => this._clientLog.warn(`background gap fill trigger failed: ${formatCaughtError(exc)}`));
             }
             // auto-ack contiguous_seq
             const contig = this._seqTracker.getContiguousSeq(ns);
@@ -1603,12 +1745,13 @@ export class AUNClient {
                     seq: contig,
                     device_id: this._deviceId,
                     slot_id: this._slotId,
-                }).catch((e) => { _clientLog('debug', 'P2P auto-ack 失败: %s', formatCaughtError(e)); });
+                }).catch((e) => { this._clientLog.debug(`P2P auto-ack failed: ${formatCaughtError(e)}`); });
             }
             // 即时持久化 cursor，异常断连后不回退
             this._saveSeqTrackerState();
         }
         const decrypted = await this._decryptSingleMessage(msg);
+        this._clientLog.debug(`P2P message decrypt done: from=${String(msg.from ?? '')}, mid=${String(msg.message_id ?? '')}, seq=${String(seq ?? '')}`);
         if (seq !== undefined && seq !== null && this._aid) {
             const ns = `p2p:${this._aid}`;
             await this._publishOrderedMessage('message.received', ns, seq, decrypted);
@@ -1619,8 +1762,15 @@ export class AUNClient {
     }
     /** 处理群组消息推送：自动解密后 re-publish */
     async _onRawGroupMessageCreated(data) {
+        const tStart = Date.now();
+        if (isJsonObject(data)) {
+            this._clientLog.debug(`_onRawGroupMessageCreated enter: group_id=${String(data.group_id ?? '')}, message_id=${String(data.message_id ?? '')}, seq=${String(data.seq ?? '')}`);
+        }
+        else {
+            this._clientLog.debug(`_onRawGroupMessageCreated enter: non-object payload`);
+        }
         this._processAndPublishGroupMessage(data).catch((exc) => {
-            _clientLog('warn', '群消息解密失败: %s', formatCaughtError(exc));
+            this._clientLog.warn(`group message decrypt failed: ${formatCaughtError(exc)}`);
             // H26: 不再投递原始密文 payload；改发 group.message_undecryptable 事件
             if (isJsonObject(data)) {
                 const safeEvent = {
@@ -1634,6 +1784,7 @@ export class AUNClient {
                 this._publishAppEvent('group.message_undecryptable', safeEvent).catch(() => { });
             }
         });
+        this._clientLog.debug(`_onRawGroupMessageCreated exit: elapsed=${Date.now() - tStart}ms (handler dispatched)`);
     }
     /**
      * 处理群组推送消息的异步任务。
@@ -1660,12 +1811,14 @@ export class AUNClient {
             return;
         }
         const decrypted = await this._decryptGroupMessage(msg);
+        this._clientLog.debug(`group message decrypt done: group=${groupId}, from=${String(msg.from ?? '')}, seq=${String(seq ?? '')}, e2ee=${String(!!decrypted.e2ee)}`);
         // 只有带 payload 的真实消息，在同步解密/恢复尝试结束后才推进游标。
         if (groupId && seq !== undefined && seq !== null) {
             const ns = `group:${groupId}`;
             const needPull = this._seqTracker.onMessageSeq(ns, seq);
             if (needPull) {
-                this._fillGroupGap(groupId).catch(exc => _clientLog('warn', '后台补洞触发失败: %s', formatCaughtError(exc)));
+                this._clientLog.debug(`group message seq gap detected: group=${groupId}, seq=${seq}, contiguous=${this._seqTracker.getContiguousSeq(ns)}`);
+                this._fillGroupGap(groupId).catch(exc => this._clientLog.warn(`background gap fill trigger failed: ${formatCaughtError(exc)}`));
             }
             const contig = this._seqTracker.getContiguousSeq(ns);
             if (contig > 0) {
@@ -1674,7 +1827,7 @@ export class AUNClient {
                     msg_seq: contig,
                     device_id: this._deviceId,
                     slot_id: this._slotId,
-                }).catch((e) => { _clientLog('debug', '群消息 auto-ack 失败: group=%s %s', groupId, formatCaughtError(e)); });
+                }).catch((e) => { this._clientLog.debug(`group message auto-ack failed: group=${groupId} ${formatCaughtError(e)}`); });
             }
             this._saveSeqTrackerState();
         }
@@ -1742,7 +1895,7 @@ export class AUNClient {
             }
         }
         catch (exc) {
-            _clientLog('debug', '自动 pull 群消息失败: %s', formatCaughtError(exc));
+            this._clientLog.debug(`auto pull group messages failed: ${formatCaughtError(exc)}`);
         }
         await this._publishAppEvent('group.message_created', notification);
     }
@@ -1755,6 +1908,7 @@ export class AUNClient {
         if (this._gapFillDone.has(dedupKey))
             return;
         this._gapFillDone.set(dedupKey, Date.now());
+        this._clientLog.debug(`group message gap fill start: group=${groupId}, after_seq=${afterSeq}`);
         try {
             const result = await this.call('group.pull', {
                 group_id: groupId,
@@ -1762,6 +1916,7 @@ export class AUNClient {
                 device_id: this._deviceId,
                 limit: 50,
             });
+            let filled = 0;
             if (isJsonObject(result)) {
                 const messages = result.messages;
                 if (Array.isArray(messages)) {
@@ -1778,14 +1933,16 @@ export class AUNClient {
                             else {
                                 await this._publishAppEvent('group.message_created', msg);
                             }
+                            filled += 1;
                         }
                     }
                     this._prunePushedSeqs(ns);
                 }
             }
+            this._clientLog.debug(`group message gap fill done: group=${groupId}, after_seq=${afterSeq}, filled=${filled}`);
         }
         catch (exc) {
-            _clientLog('warn', '群消息补洞失败: %s', formatCaughtError(exc));
+            this._clientLog.warn(`group message gap fill failed: ${formatCaughtError(exc)}`);
         }
         finally {
             this._gapFillDone.delete(dedupKey);
@@ -1802,11 +1959,13 @@ export class AUNClient {
         if (this._gapFillDone.has(dedupKey))
             return;
         this._gapFillDone.set(dedupKey, Date.now());
+        this._clientLog.debug(`P2P message gap fill start: after_seq=${afterSeq}`);
         try {
             const result = await this.call('message.pull', {
                 after_seq: afterSeq,
                 limit: 50,
             });
+            let filled = 0;
             if (isJsonObject(result)) {
                 const messages = result.messages;
                 if (Array.isArray(messages)) {
@@ -1823,14 +1982,16 @@ export class AUNClient {
                             else {
                                 await this._publishAppEvent('message.received', msg);
                             }
+                            filled += 1;
                         }
                     }
                     this._prunePushedSeqs(ns);
                 }
             }
+            this._clientLog.debug(`P2P message gap fill done: after_seq=${afterSeq}, filled=${filled}`);
         }
         catch (exc) {
-            _clientLog('warn', 'P2P 消息补洞失败: %s', formatCaughtError(exc));
+            this._clientLog.warn(`P2P message gap fill failed: ${formatCaughtError(exc)}`);
         }
         finally {
             this._gapFillDone.delete(dedupKey);
@@ -1971,6 +2132,7 @@ export class AUNClient {
         if (this._gapFillDone.has(dedupKey))
             return;
         this._gapFillDone.set(dedupKey, Date.now());
+        this._clientLog.debug(`group event gap fill start: group=${groupId}, after_seq=${afterSeq}`);
         try {
             const result = await this.call('group.pull_events', {
                 group_id: groupId,
@@ -1978,6 +2140,7 @@ export class AUNClient {
                 device_id: this._deviceId,
                 limit: 50,
             });
+            let filled = 0;
             if (isJsonObject(result)) {
                 const events = result.events;
                 if (Array.isArray(events)) {
@@ -1987,7 +2150,7 @@ export class AUNClient {
                     if (serverAck > 0) {
                         const contigBefore = this._seqTracker.getContiguousSeq(ns);
                         if (contigBefore < serverAck) {
-                            _clientLog('info', 'group.pull_events retention-floor 推进: ns=%s contiguous=%d -> cursor.current_seq=%d', ns, contigBefore, serverAck);
+                            this._clientLog.info(`group.pull_events retention-floor advance: ns=${ns} contiguous=${contigBefore} -> cursor.current_seq=${serverAck}`);
                             this._seqTracker.forceContiguousSeq(ns, serverAck);
                         }
                     }
@@ -2000,7 +2163,7 @@ export class AUNClient {
                             event_seq: contig,
                             device_id: this._deviceId,
                             slot_id: this._slotId,
-                        }).catch((e) => { _clientLog('debug', '群事件 auto-ack 失败: group=%s %s', groupId, formatCaughtError(e)); });
+                        }).catch((e) => { this._clientLog.debug(`group event auto-ack failed: group=${groupId} ${formatCaughtError(e)}`); });
                     }
                     for (const evt of events) {
                         if (isJsonObject(evt)) {
@@ -2016,13 +2179,15 @@ export class AUNClient {
                             }
                             // group.changed 或缺失/其他 → 发布到 group.changed（向后兼容）
                             await this._dispatcher.publish('group.changed', evt);
+                            filled += 1;
                         }
                     }
                 }
             }
+            this._clientLog.debug(`group event gap fill done: group=${groupId}, after_seq=${afterSeq}, filled=${filled}`);
         }
         catch (exc) {
-            _clientLog('warn', '群事件补洞失败: %s', formatCaughtError(exc));
+            this._clientLog.warn(`group event gap fill failed: ${formatCaughtError(exc)}`);
         }
         finally {
             this._gapFillDone.delete(dedupKey);
@@ -2152,103 +2317,113 @@ export class AUNClient {
         return member ? String(member.group_id ?? '') : '';
     }
     async _onRawGroupChanged(data) {
-        if (isJsonObject(data)) {
-            const d = data;
-            // 验签：有 client_signature 就验，没有默认安全（H20: 严格 boolean）
-            const cs = d.client_signature;
-            if (cs && isJsonObject(cs)) {
-                d._verified = await this._verifyEventSignatureAsync(d, cs);
-            }
-            await this._dispatcher.publish('group.changed', d);
-            const groupId = String(d.group_id ?? '');
-            // event_seq 空洞检测：持久化后的 group.changed 会携带 event_seq。
-            // 用 onMessageSeq 返回值决定是否补拉，与 P2P / group.message 路径对齐。
-            let needPull = false;
-            const rawEventSeq = d.event_seq;
-            if (rawEventSeq != null && groupId) {
-                const es = Number(rawEventSeq);
-                if (Number.isFinite(es) && es > 0) {
-                    needPull = this._seqTracker.onMessageSeq(`group_event:${groupId}`, es);
-                }
-                // ISSUE-TS-002: 群事件推送路径 ack + 持久化，与 P2P/群消息路径对齐
-                this._saveSeqTrackerState();
-                const contig = this._seqTracker.getContiguousSeq(`group_event:${groupId}`);
-                if (contig > 0) {
-                    this._transport.call('group.ack_events', {
-                        group_id: groupId,
-                        event_seq: contig,
-                        device_id: this._deviceId,
-                        slot_id: this._slotId,
-                    }).catch((e) => { _clientLog('debug', '群事件推送 auto-ack 失败: group=%s %s', groupId, formatCaughtError(e)); });
-                }
-            }
-            // 仅在真实 event gap 时才触发补拉（补洞回来的事件不再触发新补洞）
-            if (needPull && groupId && !d._from_gap_fill) {
-                this._fillGroupEventGap(groupId).catch(exc => _clientLog('warn', '后台补洞触发失败: %s', formatCaughtError(exc)));
-            }
-            // 成员退出或被踢 → 剩余 admin/owner 自动补位轮换
-            // H21: 避免 epoch 轮换风暴——所有剩余 admin 同时收到事件不能都发起轮换，
-            // 否则 CAS 冲突激增。策略：本地 AID 为"排序最小 admin"时才发起，其他 admin
-            // 叠加随机 jitter 作为超时兜底（本地最小 admin 失败时由下一位顶上）。
-            if (d.action === 'member_left' || d.action === 'member_removed') {
-                if (groupId) {
-                    {
-                        const expectedEpoch = this._membershipRotationExpectedEpoch(d);
-                        if (expectedEpoch === null) {
-                            _clientLog('debug', 'membership event without old_epoch skipped for epoch rotation: aid=%s group=%s action=%s event_seq=%s', this._aid ?? '', groupId, String(d.action ?? ''), String(d.event_seq ?? ''));
-                        }
-                        else {
-                            this._maybeLeadRotateGroupEpoch(groupId, this._membershipRotationTriggerId(groupId, d), expectedEpoch).catch((exc) => this._logE2eeError('rotate_epoch', groupId, '', exc));
-                        }
+        const tStart = Date.now();
+        try {
+            if (isJsonObject(data)) {
+                const d = data;
+                const groupId = String(d.group_id ?? '');
+                const action = String(d.action ?? '');
+                this._clientLog.debug(`_onRawGroupChanged enter: group_id=${groupId}, action=${action}, event_seq=${String(d.event_seq ?? '')}`);
+                // 验签：有 client_signature 就验，没有默认安全（H20: 严格 boolean）
+                const cs = d.client_signature;
+                if (cs && isJsonObject(cs)) {
+                    d._verified = await this._verifyEventSignatureAsync(d, cs);
+                }
+                await this._dispatcher.publish('group.changed', d);
+                // event_seq 空洞检测：持久化后的 group.changed 会携带 event_seq。
+                // 用 onMessageSeq 返回值决定是否补拉，与 P2P / group.message 路径对齐。
+                let needPull = false;
+                const rawEventSeq = d.event_seq;
+                if (rawEventSeq != null && groupId) {
+                    const es = Number(rawEventSeq);
+                    if (Number.isFinite(es) && es > 0) {
+                        needPull = this._seqTracker.onMessageSeq(`group_event:${groupId}`, es);
+                    }
+                    // ISSUE-TS-002: 群事件推送路径 ack + 持久化，与 P2P/群消息路径对齐
+                    this._saveSeqTrackerState();
+                    const contig = this._seqTracker.getContiguousSeq(`group_event:${groupId}`);
+                    if (contig > 0) {
+                        this._transport.call('group.ack_events', {
+                            group_id: groupId,
+                            event_seq: contig,
+                            device_id: this._deviceId,
+                            slot_id: this._slotId,
+                        }).catch((e) => { this._clientLog.debug(`group event push auto-ack failed: group=${groupId} ${formatCaughtError(e)}`); });
                     }
                 }
-            }
-            // 成员加入：按 action 区分策略
-            // - member_added / join_approved（私密群/审批群）：admin 必然在线，立即轮换
-            // - joined / invite_code_used（开放群/邀请码群）：新成员先恢复 committed_epoch，延迟轮换
-            if (['member_added', 'joined', 'join_approved', 'invite_code_used'].includes(String(d.action ?? ''))) {
-                if (groupId) {
-                    {
-                        const action = String(d.action ?? '');
-                        const expectedEpoch = this._membershipRotationExpectedEpoch(d);
-                        const joinedAids = this._joinedMemberAidsFromPayload(d);
-                        const isSelfJoining = joinedAids.includes(this._aid ?? '') && (action === 'joined' || action === 'invite_code_used');
-                        _clientLog('warn', 'DEBUG: group.changed action=%s groupId=%s joinedAids=%s myAid=%s isSelfJoining=%s expectedEpoch=%s', action, groupId, JSON.stringify(joinedAids), this._aid, String(isSelfJoining), String(expectedEpoch));
-                        if (isSelfJoining || (action === 'joined' || action === 'invite_code_used')) {
-                            // open/invite_code 群：所有在线成员都参与延迟轮换
-                            // 新成员自己延迟更长，优先让其他在线成员先轮换
-                            const triggerId = this._membershipRotationTriggerId(groupId, d);
-                            if (!isSelfJoining) {
-                                this._maybeBackfillKeyToJoinedMember(groupId, d, triggerId).catch((exc) => this._logE2eeError('backfill_key', groupId, '', exc));
+                // 仅在真实 event gap 时才触发补拉（补洞回来的事件不再触发新补洞）
+                if (needPull && groupId && !d._from_gap_fill) {
+                    this._fillGroupEventGap(groupId).catch(exc => this._clientLog.warn(`background gap fill trigger failed: ${formatCaughtError(exc)}`));
+                }
+                // 成员退出或被踢 → 剩余 admin/owner 自动补位轮换
+                // H21: 避免 epoch 轮换风暴——所有剩余 admin 同时收到事件不能都发起轮换，
+                // 否则 CAS 冲突激增。策略：本地 AID 为"排序最小 admin"时才发起，其他 admin
+                // 叠加随机 jitter 作为超时兜底（本地最小 admin 失败时由下一位顶上）。
+                if (d.action === 'member_left' || d.action === 'member_removed') {
+                    if (groupId) {
+                        {
+                            const expectedEpoch = this._membershipRotationExpectedEpoch(d);
+                            if (expectedEpoch === null) {
+                                this._clientLog.debug(`membership event without old_epoch skipped for epoch rotation: aid=${this._aid ?? ''} group=${groupId} action=${String(d.action ?? '')} event_seq=${String(d.event_seq ?? '')}`);
                             }
-                            if (expectedEpoch !== null) {
-                                const delay = isSelfJoining ? AUNClient._SELF_JOIN_ROTATION_DELAY_MS : undefined;
-                                this._delayedRotateAfterJoin(groupId, triggerId, expectedEpoch, true, delay).catch((exc) => this._logE2eeError('rotate_epoch', groupId, '', exc));
+                            else {
+                                this._maybeLeadRotateGroupEpoch(groupId, this._membershipRotationTriggerId(groupId, d), expectedEpoch).catch((exc) => this._logE2eeError('rotate_epoch', groupId, '', exc));
                             }
                         }
-                        else {
-                            // member_added / join_approved：立即轮换
-                            if (expectedEpoch === null) {
+                    }
+                }
+                // 成员加入：按 action 区分策略
+                // - member_added / join_approved（私密群/审批群）：admin 必然在线，立即轮换
+                // - joined / invite_code_used（开放群/邀请码群）：新成员先恢复 committed_epoch，延迟轮换
+                if (['member_added', 'joined', 'join_approved', 'invite_code_used'].includes(String(d.action ?? ''))) {
+                    if (groupId) {
+                        {
+                            const action = String(d.action ?? '');
+                            const expectedEpoch = this._membershipRotationExpectedEpoch(d);
+                            const joinedAids = this._joinedMemberAidsFromPayload(d);
+                            const isSelfJoining = joinedAids.includes(this._aid ?? '') && (action === 'joined' || action === 'invite_code_used');
+                            this._clientLog.debug(`group.changed action=${action} groupId=${groupId} joinedAids=${JSON.stringify(joinedAids)} myAid=${this._aid} isSelfJoining=${String(isSelfJoining)} expectedEpoch=${String(expectedEpoch)}`);
+                            if (isSelfJoining || (action === 'joined' || action === 'invite_code_used')) {
+                                // open/invite_code 群：所有在线成员都参与延迟轮换
+                                // 新成员自己延迟更长，优先让其他在线成员先轮换
                                 const triggerId = this._membershipRotationTriggerId(groupId, d);
-                                this._maybeBackfillKeyToJoinedMember(groupId, d, triggerId).catch((exc) => this._logE2eeError('backfill_key', groupId, '', exc));
+                                if (!isSelfJoining) {
+                                    this._maybeBackfillKeyToJoinedMember(groupId, d, triggerId).catch((exc) => this._logE2eeError('backfill_key', groupId, '', exc));
+                                }
+                                if (expectedEpoch !== null) {
+                                    const delay = isSelfJoining ? AUNClient._SELF_JOIN_ROTATION_DELAY_MS : undefined;
+                                    this._delayedRotateAfterJoin(groupId, triggerId, expectedEpoch, true, delay).catch((exc) => this._logE2eeError('rotate_epoch', groupId, '', exc));
+                                }
                             }
                             else {
-                                this._maybeLeadRotateGroupEpoch(groupId, this._membershipRotationTriggerId(groupId, d), expectedEpoch).catch((exc) => this._logE2eeError('rotate_epoch', groupId, '', exc));
+                                // member_added / join_approved：立即轮换
+                                if (expectedEpoch === null) {
+                                    const triggerId = this._membershipRotationTriggerId(groupId, d);
+                                    this._maybeBackfillKeyToJoinedMember(groupId, d, triggerId).catch((exc) => this._logE2eeError('backfill_key', groupId, '', exc));
+                                }
+                                else {
+                                    this._maybeLeadRotateGroupEpoch(groupId, this._membershipRotationTriggerId(groupId, d), expectedEpoch).catch((exc) => this._logE2eeError('rotate_epoch', groupId, '', exc));
+                                }
                             }
                         }
                     }
                 }
-            }
-            // 群组解散 → 清理本地 epoch key、seq_tracker、补洞去重缓存
-            if (d.action === 'dissolved') {
-                if (groupId) {
-                    this._cleanupDissolvedGroup(groupId);
+                // 群组解散 → 清理本地 epoch key、seq_tracker、补洞去重缓存
+                if (d.action === 'dissolved') {
+                    if (groupId) {
+                        this._cleanupDissolvedGroup(groupId);
+                    }
                 }
             }
+            else {
+                // data 非对象也透传给用户（兼容旧版）
+                await this._dispatcher.publish('group.changed', data);
+            }
+            this._clientLog.debug(`_onRawGroupChanged exit: elapsed=${Date.now() - tStart}ms`);
         }
-        else {
-            // data 非对象也透传给用户（兼容旧版）
-            await this._dispatcher.publish('group.changed', data);
+        catch (err) {
+            this._clientLog.debug(`_onRawGroupChanged exit (error): elapsed=${Date.now() - tStart}ms err=${err instanceof Error ? err.message : String(err)}`);
+            throw err;
         }
     }
     /**
@@ -2256,82 +2431,95 @@ export class AUNClient {
      * 当链断裂时回源 group.get_state，并对回源结果做本地 hash 重算验证。
      */
     async _onGroupStateCommitted(data) {
-        if (!isJsonObject(data))
+        const tStart = Date.now();
+        if (!isJsonObject(data)) {
+            this._clientLog.debug(`_onGroupStateCommitted exit: elapsed=${Date.now() - tStart}ms (non-object payload)`);
             return;
+        }
         const d = data;
         const groupId = String(d.group_id ?? '').trim();
-        if (!groupId)
+        if (!groupId) {
+            this._clientLog.debug(`_onGroupStateCommitted exit: elapsed=${Date.now() - tStart}ms (no group_id)`);
             return;
-        // 提交者签名验证（兼容旧版：无签名时继续）
-        const cs = d.client_signature;
-        if (cs && isJsonObject(cs)) {
-            const verified = await this._verifyEventSignatureAsync(d, cs);
-            if (verified === false) {
-                _clientLog('warn', 'state_committed 提交者签名验证失败 group=%s', groupId);
-                return;
-            }
-            d._verified = verified;
-        }
-        const stateVersion = Number(d.state_version ?? 0);
-        const stateHash = String(d.state_hash ?? '').trim();
-        const prevStateHash = String(d.prev_state_hash ?? '').trim();
-        const keyEpoch = Number(d.key_epoch ?? 0);
-        const membershipSnapshot = String(d.membership_snapshot ?? '').trim();
-        const policySnapshot = String(d.policy_snapshot ?? '').trim();
-        // 1. 验证 prev_state_hash 连续性
-        const loadFn = this._keystore.loadGroupState;
-        const localState = loadFn ? loadFn.call(this._keystore, groupId) : null;
-        if (localState && localState.state_hash && localState.state_hash !== prevStateHash) {
-            _clientLog('warn', 'state_hash 链不连续 group=%s local_sv=%d event_sv=%d', groupId, localState.state_version, stateVersion);
-            // 回源同步
-            try {
-                const serverState = await this._transport.call('group.get_state', { group_id: groupId });
-                if (serverState && isJsonObject(serverState) && 'state_version' in serverState) {
-                    const sv = Number(serverState.state_version ?? 0);
-                    const sHash = String(serverState.state_hash ?? '');
-                    const sEpoch = Number(serverState.key_epoch ?? 0);
-                    const sMembersJson = String(serverState.membership_snapshot ?? '');
-                    const sPolicyJson = String(serverState.policy_snapshot ?? '');
-                    const sPrev = String(serverState.prev_state_hash ?? '');
-                    // 回源也做 hash 验证
-                    if (sMembersJson && sHash) {
-                        const sMembers = sMembersJson ? JSON.parse(sMembersJson) : [];
-                        const sPolicy = sPolicyJson ? JSON.parse(sPolicyJson) : {};
-                        const computed = computeStateHash({
-                            groupId, stateVersion: sv, keyEpoch: sEpoch,
-                            members: sMembers, policy: sPolicy, prevStateHash: sPrev,
-                        });
-                        if (computed !== sHash) {
-                            _clientLog('warn', '回源 state_hash 验证失败 group=%s sv=%d expected=%s got=%s', groupId, sv, sHash, computed);
-                            return;
+        }
+        this._clientLog.debug(`_onGroupStateCommitted enter: group_id=${groupId}, state_version=${String(d.state_version ?? '')}`);
+        try {
+            // 提交者签名验证（兼容旧版：无签名时继续）
+            const cs = d.client_signature;
+            if (cs && isJsonObject(cs)) {
+                const verified = await this._verifyEventSignatureAsync(d, cs);
+                if (verified === false) {
+                    this._clientLog.warn(`state_committed committer signature verification failed group=${groupId}`);
+                    return;
+                }
+                d._verified = verified;
+            }
+            const stateVersion = Number(d.state_version ?? 0);
+            const stateHash = String(d.state_hash ?? '').trim();
+            const prevStateHash = String(d.prev_state_hash ?? '').trim();
+            const keyEpoch = Number(d.key_epoch ?? 0);
+            const membershipSnapshot = String(d.membership_snapshot ?? '').trim();
+            const policySnapshot = String(d.policy_snapshot ?? '').trim();
+            // 1. 验证 prev_state_hash 连续性
+            const loadFn = this._keystore.loadGroupState;
+            const localState = loadFn ? loadFn.call(this._keystore, groupId) : null;
+            if (localState && localState.state_hash && localState.state_hash !== prevStateHash) {
+                this._clientLog.warn(`state_hash chain discontinuous group=${groupId} local_sv=${localState.state_version} event_sv=${stateVersion}`);
+                // 回源同步
+                try {
+                    const serverState = await this._transport.call('group.get_state', { group_id: groupId });
+                    if (serverState && isJsonObject(serverState) && 'state_version' in serverState) {
+                        const sv = Number(serverState.state_version ?? 0);
+                        const sHash = String(serverState.state_hash ?? '');
+                        const sEpoch = Number(serverState.key_epoch ?? 0);
+                        const sMembersJson = String(serverState.membership_snapshot ?? '');
+                        const sPolicyJson = String(serverState.policy_snapshot ?? '');
+                        const sPrev = String(serverState.prev_state_hash ?? '');
+                        // 回源也做 hash 验证
+                        if (sMembersJson && sHash) {
+                            const sMembers = sMembersJson ? JSON.parse(sMembersJson) : [];
+                            const sPolicy = sPolicyJson ? JSON.parse(sPolicyJson) : {};
+                            const computed = computeStateHash({
+                                groupId, stateVersion: sv, keyEpoch: sEpoch,
+                                members: sMembers, policy: sPolicy, prevStateHash: sPrev,
+                            });
+                            if (computed !== sHash) {
+                                this._clientLog.warn(`backfill state_hash verification failed group=${groupId} sv=${sv} expected=${sHash} got=${computed}`);
+                                return;
+                            }
+                        }
+                        const saveFn = this._keystore.saveGroupState;
+                        if (saveFn) {
+                            saveFn.call(this._keystore, groupId, sv, sHash, sEpoch, sMembersJson || membershipSnapshot, sPolicyJson || policySnapshot);
                         }
                     }
-                    const saveFn = this._keystore.saveGroupState;
-                    if (saveFn) {
-                        saveFn.call(this._keystore, groupId, sv, sHash, sEpoch, sMembersJson || membershipSnapshot, sPolicyJson || policySnapshot);
-                    }
                 }
+                catch (exc) {
+                    this._clientLog.warn(`state backfill failed group=${groupId}: ${formatCaughtError(exc)}`);
+                }
+                return;
             }
-            catch (exc) {
-                _clientLog('warn', 'state 回源失败 group=%s: %s', groupId, formatCaughtError(exc));
+            // 2. 本地重算验证
+            const members = membershipSnapshot ? JSON.parse(membershipSnapshot) : [];
+            const policy = policySnapshot ? JSON.parse(policySnapshot) : {};
+            const computed = computeStateHash({
+                groupId, stateVersion, keyEpoch,
+                members, policy, prevStateHash,
+            });
+            if (computed !== stateHash) {
+                this._clientLog.warn(`state_hash recompute mismatch group=${groupId} sv=${stateVersion} expected=${stateHash} got=${computed}`);
+                return;
             }
-            return;
-        }
-        // 2. 本地重算验证
-        const members = membershipSnapshot ? JSON.parse(membershipSnapshot) : [];
-        const policy = policySnapshot ? JSON.parse(policySnapshot) : {};
-        const computed = computeStateHash({
-            groupId, stateVersion, keyEpoch,
-            members, policy, prevStateHash,
-        });
-        if (computed !== stateHash) {
-            _clientLog('warn', 'state_hash 重算不匹配 group=%s sv=%d expected=%s got=%s', groupId, stateVersion, stateHash, computed);
-            return;
+            // 3. 更新本地存储
+            const saveFn = this._keystore.saveGroupState;
+            if (saveFn) {
+                saveFn.call(this._keystore, groupId, stateVersion, stateHash, keyEpoch, membershipSnapshot, policySnapshot);
+            }
+            this._clientLog.debug(`_onGroupStateCommitted exit: elapsed=${Date.now() - tStart}ms group=${groupId}`);
         }
-        // 3. 更新本地存储
-        const saveFn = this._keystore.saveGroupState;
-        if (saveFn) {
-            saveFn.call(this._keystore, groupId, stateVersion, stateHash, keyEpoch, membershipSnapshot, policySnapshot);
+        catch (err) {
+            this._clientLog.debug(`_onGroupStateCommitted exit (error): elapsed=${Date.now() - tStart}ms group=${groupId} err=${err instanceof Error ? err.message : String(err)}`);
+            throw err;
         }
     }
     /**
@@ -2339,23 +2527,34 @@ export class AUNClient {
      * 避免所有剩余 admin 同时触发 `_rotateGroupEpoch` 造成 CAS 风暴。
      */
     async _maybeLeadRotateGroupEpoch(groupId, triggerId = '', expectedEpoch = null, allowMember = false) {
+        const tStart = Date.now();
         const myAid = this._aid;
-        if (!myAid || this._closing || this._state !== 'connected')
+        if (!myAid || this._closing || this._state !== 'connected') {
+            this._clientLog.debug(`_maybeLeadRotateGroupEpoch exit: elapsed=${Date.now() - tStart}ms group=${groupId} reason=${!myAid ? 'no_aid' : this._closing ? 'closing' : 'not_connected'}`);
             return;
+        }
+        this._clientLog.debug(`_maybeLeadRotateGroupEpoch enter: group=${groupId}, trigger=${triggerId || '-'}, expectedEpoch=${String(expectedEpoch)}, allowMember=${String(allowMember)}`);
         const started = Date.now();
         while (this._groupEpochRotationInflight.has(groupId)) {
-            if (triggerId && this._groupMembershipRotationDone.has(triggerId))
+            if (triggerId && this._groupMembershipRotationDone.has(triggerId)) {
+                this._clientLog.debug(`_maybeLeadRotateGroupEpoch exit: elapsed=${Date.now() - tStart}ms group=${groupId} (trigger_done)`);
                 return;
-            if (this._closing || this._state !== 'connected')
+            }
+            if (this._closing || this._state !== 'connected') {
+                this._clientLog.debug(`_maybeLeadRotateGroupEpoch exit: elapsed=${Date.now() - tStart}ms group=${groupId} (closing/disconnected)`);
                 return;
+            }
             if (Date.now() - started > 20000) {
-                _clientLog('warn', 'group epoch rotation still in-flight; skip pending trigger (group=%s trigger=%s)', groupId, triggerId || '-');
+                this._clientLog.warn(`group epoch rotation still in-flight; skip pending trigger (group=${groupId} trigger=${triggerId || '-'})`);
+                this._clientLog.debug(`_maybeLeadRotateGroupEpoch exit: elapsed=${Date.now() - tStart}ms group=${groupId} (inflight_timeout)`);
                 return;
             }
             await new Promise((resolve) => setTimeout(resolve, 200));
         }
-        if (this._closing || this._state !== 'connected')
+        if (this._closing || this._state !== 'connected') {
+            this._clientLog.debug(`_maybeLeadRotateGroupEpoch exit: elapsed=${Date.now() - tStart}ms group=${groupId} (closing/disconnected after wait)`);
             return;
+        }
         this._groupEpochRotationInflight.add(groupId);
         try {
             if (this._closing || this._state !== 'connected')
@@ -2403,11 +2602,14 @@ export class AUNClient {
             const leader = candidates[0];
             if (leader === myAid) {
                 // 我是 leader，直接发起
+                this._clientLog.debug(`_maybeLeadRotateGroupEpoch leader election: group=${groupId}, I am leader, initiating rotation`);
                 await this._rotateGroupEpoch(groupId, triggerId, expectedEpoch);
                 return;
             }
-            if (!candidates.includes(myAid))
+            if (!candidates.includes(myAid)) {
+                this._clientLog.debug(`_maybeLeadRotateGroupEpoch skipped: group=${groupId}, not in candidate list`);
                 return;
+            }
             // 非 leader：随机 jitter（2~6s）后查询服务端 epoch 是否已被 leader 推进
             const jitterMs = 2000 + Math.floor(Math.random() * 4000);
             let beforeEpoch = 0;
@@ -2444,14 +2646,15 @@ export class AUNClient {
                 });
                 return;
             }
-            _clientLog('info', '[H21] leader 未完成 epoch 轮换，非 leader 兜底: group=%s myAid=%s', groupId, myAid);
+            this._clientLog.info(`[H21] leader did not complete epoch rotation, non-leader fallback: group=${groupId} myAid=${myAid}`);
             await this._rotateGroupEpoch(groupId, triggerId, expectedEpoch);
         }
         catch (exc) {
-            _clientLog('warn', '_maybeLeadRotateGroupEpoch 失败: %s', formatCaughtError(exc));
+            this._clientLog.warn(`_maybeLeadRotateGroupEpoch failed: ${formatCaughtError(exc)}`);
         }
         finally {
             this._groupEpochRotationInflight.delete(groupId);
+            this._clientLog.debug(`_maybeLeadRotateGroupEpoch exit: elapsed=${Date.now() - tStart}ms group=${groupId}`);
         }
     }
     /**
@@ -2466,7 +2669,7 @@ export class AUNClient {
             this._groupE2ee.removeGroup(groupId);
         }
         catch (exc) {
-            _clientLog('warn', '清理解散群组 %s epoch 密钥失败: %s', groupId, formatCaughtError(exc));
+            this._clientLog.warn(`cleanup disbanded group ${groupId} epoch key failed: ${formatCaughtError(exc)}`);
         }
         // 2. 清理 seq_tracker 中的群消息和群事件命名空间
         this._seqTracker.removeNamespace(`group:${groupId}`);
@@ -2483,7 +2686,7 @@ export class AUNClient {
         this._pushedSeqs.delete(`group_event:${groupId}`);
         this._pendingOrderedMsgs.delete(`group:${groupId}`);
         this._pendingDecryptMsgs.delete(`group:${groupId}`);
-        _clientLog('info', '已清理解散群组 %s 的本地状态', groupId);
+        this._clientLog.info(`cleaned up disbanded group ${groupId} local state`);
     }
     /** 同步验签群事件 client_signature。返回 true/false/"pending"。 */
     /**
@@ -2518,7 +2721,7 @@ export class AUNClient {
             if (expectedFP) {
                 const actualFP = 'sha256:' + certObj.fingerprint256.replace(/:/g, '').toLowerCase();
                 if (actualFP !== expectedFP) {
-                    _clientLog('warn', '验签失败：证书指纹不匹配 aid=%s', sigAid);
+                    this._clientLog.warn(`signature verification failed: cert fingerprint mismatch aid=${sigAid}`);
                     return false;
                 }
             }
@@ -2529,7 +2732,7 @@ export class AUNClient {
             const pubKey = certObj.publicKey;
             const ok = crypto.verify('SHA256', signData, pubKey, Buffer.from(sigB64, 'base64'));
             if (!ok) {
-                _clientLog('warn', '群事件验签失败 aid=%s method=%s', sigAid, method);
+                this._clientLog.warn(`group event signature verification failed aid=${sigAid} method=${method}`);
                 // P1-16: 签名失败统一发布事件
                 this._dispatcher.publish('signature.verification_failed', {
                     aid: sigAid, method, error: 'ECDSA verification failed',
@@ -2538,7 +2741,7 @@ export class AUNClient {
             return ok;
         }
         catch (exc) {
-            _clientLog('warn', '群事件验签异常: %s', formatCaughtError(exc));
+            this._clientLog.warn(`group event signature verification error: ${formatCaughtError(exc)}`);
             // P1-16: 签名失败统一发布事件
             this._dispatcher.publish('signature.verification_failed', {
                 aid: String(cs.aid ?? ''), method: String(cs._method ?? ''),
@@ -2596,6 +2799,7 @@ export class AUNClient {
         result = this._groupE2ee.handleIncoming(actualPayload);
         if (result === 'distribution') {
             await this._discardGroupDistributionIfStale(actualPayload);
+            this._clientLog.debug(`group key distribution received: group_id=${String(actualPayload.group_id ?? '')}, epoch=${String(actualPayload.epoch ?? '')}, rotation=${String(actualPayload.rotation_id ?? '')}`);
             // 收到 epoch key 说明该群有活动，触发惰性同步建立 seq 基线
             const distGroupId = actualPayload.group_id;
             if (distGroupId && !this._groupSynced.has(distGroupId)) {
@@ -2609,6 +2813,7 @@ export class AUNClient {
             // 处理密钥请求并回复
             const groupId = String(actualPayload.group_id ?? '');
             const requester = String(actualPayload.requester_aid ?? '');
+            this._clientLog.debug(`group key request received: group_id=${groupId}, requester=${requester}, epoch=${String(actualPayload.epoch ?? '')}`);
             let members = this._groupE2ee.getMemberAids(groupId);
             // 请求者不在本地成员列表时，回源查询服务端最新成员列表，
             // 仅用于传递给 handleKeyRequestMsg 做鉴权，不更新本地密钥存储
@@ -2622,7 +2827,7 @@ export class AUNClient {
                     members = memberList.map((m) => String(m.aid));
                 }
                 catch (exc) {
-                    _clientLog('warn', '群组 %s 成员列表回源失败: %s', groupId, formatCaughtError(exc));
+                    this._clientLog.warn(`group ${groupId} member list backfill failed: ${formatCaughtError(exc)}`);
                 }
             }
             const response = this._groupE2ee.handleKeyRequestMsg(actualPayload, members);
@@ -2636,7 +2841,7 @@ export class AUNClient {
                     });
                 }
                 catch (exc) {
-                    _clientLog('warn', '向 %s 回复群组密钥失败: %s', requester, formatCaughtError(exc));
+                    this._clientLog.warn(`replying group key to ${requester} failed: ${formatCaughtError(exc)}`);
                 }
             }
         }
@@ -2645,9 +2850,10 @@ export class AUNClient {
             const groupId = String(actualPayload.group_id ?? '');
             const rotationId = String(actualPayload.rotation_id ?? '');
             const keyCommitment = String(actualPayload.commitment ?? '');
+            this._clientLog.debug(`group key ${result} handled: group_id=${groupId}, epoch=${String(actualPayload.epoch ?? '')}, rotation=${rotationId}`);
             if (rotationId && keyCommitment) {
                 this._ackGroupRotationKey(rotationId, keyCommitment)
-                    .catch((exc) => _clientLog('warn', '提交 epoch key ack 失败: %s', formatCaughtError(exc)));
+                    .catch((exc) => this._clientLog.warn(`submit epoch key ack failed: ${formatCaughtError(exc)}`));
             }
             this._scheduleRetryPendingDecryptMsgs(groupId);
         }
@@ -2659,133 +2865,158 @@ export class AUNClient {
      * 跨域时自动路由到 peer 所在域的 Gateway。
      */
     async _fetchPeerCert(aid, certFingerprint) {
-        const cacheKey = AUNClient._certCacheKey(aid, certFingerprint);
-        const cached = this._certCache.get(cacheKey);
-        const now = Date.now() / 1000;
-        if (cached && now < cached.refreshAfter) {
-            return cached.certPem;
-        }
-        const gatewayUrl = this._gatewayUrl;
-        if (!gatewayUrl) {
-            throw new ValidationError('gateway url unavailable for e2ee cert fetch');
-        }
-        // 跨域时用 peer 所在域的 Gateway URL
-        const peerGatewayUrl = AUNClient._resolvePeerGatewayUrl(gatewayUrl, aid);
-        let certPem;
+        const tStart = Date.now();
+        this._clientLog.debug(`_fetchPeerCert enter: aid=${aid}, fp=${certFingerprint ?? ''}`);
         try {
-            const certUrl = AUNClient._buildCertUrl(peerGatewayUrl, aid, certFingerprint);
-            certPem = await _httpGetText(certUrl, this._configModel.verifySsl);
-        }
-        catch (exc) {
-            if (!certFingerprint) {
-                throw exc;
+            const cacheKey = AUNClient._certCacheKey(aid, certFingerprint);
+            const cached = this._certCache.get(cacheKey);
+            const now = Date.now() / 1000;
+            if (cached && now < cached.refreshAfter) {
+                this._clientLog.debug(`_fetchPeerCert exit: elapsed=${Date.now() - tStart}ms aid=${aid} (cache_hit)`);
+                return cached.certPem;
+            }
+            const gatewayUrl = this._gatewayUrl;
+            if (!gatewayUrl) {
+                throw new ValidationError('gateway url unavailable for e2ee cert fetch');
+            }
+            // 跨域时用 peer 所在域的 Gateway URL
+            const peerGatewayUrl = AUNClient._resolvePeerGatewayUrl(gatewayUrl, aid);
+            let certPem;
+            try {
+                const certUrl = AUNClient._buildCertUrl(peerGatewayUrl, aid, certFingerprint);
+                certPem = await _httpGetText(certUrl, this._configModel.verifySsl);
             }
-            const fallbackCert = await _httpGetText(AUNClient._buildCertUrl(peerGatewayUrl, aid), this._configModel.verifySsl);
-            certPem = fallbackCert;
-        }
-        // H7: 严格校验指纹（DER SHA-256 或 SPKI SHA-256 任一匹配即可）
-        if (certFingerprint) {
-            const expectedFP = String(certFingerprint).trim().toLowerCase();
-            if (!expectedFP.startsWith('sha256:')) {
-                throw new ValidationError(`unsupported cert_fingerprint format for ${aid}: ${expectedFP.slice(0, 24)}`);
-            }
-            const expectedHex = expectedFP.slice('sha256:'.length);
-            const x509Cert = new crypto.X509Certificate(certPem);
-            const derHex = x509Cert.fingerprint256.replace(/:/g, '').toLowerCase();
-            let spkiHex = '';
+            catch (exc) {
+                if (!certFingerprint) {
+                    throw exc;
+                }
+                const fallbackCert = await _httpGetText(AUNClient._buildCertUrl(peerGatewayUrl, aid), this._configModel.verifySsl);
+                certPem = fallbackCert;
+            }
+            // H7: 严格校验指纹（DER SHA-256 或 SPKI SHA-256 任一匹配即可）
+            if (certFingerprint) {
+                const expectedFP = String(certFingerprint).trim().toLowerCase();
+                if (!expectedFP.startsWith('sha256:')) {
+                    throw new ValidationError(`unsupported cert_fingerprint format for ${aid}: ${expectedFP.slice(0, 24)}`);
+                }
+                const expectedHex = expectedFP.slice('sha256:'.length);
+                const x509Cert = new crypto.X509Certificate(certPem);
+                const derHex = x509Cert.fingerprint256.replace(/:/g, '').toLowerCase();
+                let spkiHex = '';
+                try {
+                    const spkiDer = x509Cert.publicKey.export({ type: 'spki', format: 'der' });
+                    spkiHex = crypto.createHash('sha256').update(spkiDer).digest('hex');
+                }
+                catch {
+                    spkiHex = '';
+                }
+                if (expectedHex !== derHex && (!spkiHex || expectedHex !== spkiHex)) {
+                    throw new ValidationError(`peer cert fingerprint mismatch for ${aid}: expected=${expectedFP.slice(0, 24)}...`);
+                }
+            }
+            // 完整 PKI 验证
             try {
-                const spkiDer = x509Cert.publicKey.export({ type: 'spki', format: 'der' });
-                spkiHex = crypto.createHash('sha256').update(spkiDer).digest('hex');
+                await this._auth.verifyPeerCertificate(peerGatewayUrl, certPem, aid);
             }
-            catch {
-                spkiHex = '';
+            catch (exc) {
+                throw new ValidationError(`peer cert verification failed for ${aid}: ${exc instanceof Error ? exc.message : String(exc)}`);
             }
-            if (expectedHex !== derHex && (!spkiHex || expectedHex !== spkiHex)) {
-                throw new ValidationError(`peer cert fingerprint mismatch for ${aid}: expected=${expectedFP.slice(0, 24)}...`);
+            const nowSec = Date.now() / 1000;
+            this._certCache.set(cacheKey, {
+                certPem,
+                validatedAt: nowSec,
+                refreshAfter: nowSec + PEER_CERT_CACHE_TTL,
+            });
+            try {
+                // peer 证书只存版本目录，不覆盖 cert.pem
+                this._keystore.saveCert(aid, certPem, certFingerprint, { makeActive: false });
             }
+            catch (exc) {
+                this._clientLog.error(`failed to write cert to keystore (aid=${aid}, fp=${certFingerprint ?? ''}): ${formatCaughtError(exc)}`, exc instanceof Error ? exc : undefined);
+            }
+            this._clientLog.debug(`_fetchPeerCert exit: elapsed=${Date.now() - tStart}ms aid=${aid} (fetched)`);
+            return certPem;
         }
-        // 完整 PKI 验证
-        try {
-            await this._auth.verifyPeerCertificate(peerGatewayUrl, certPem, aid);
-        }
-        catch (exc) {
-            throw new ValidationError(`peer cert verification failed for ${aid}: ${exc instanceof Error ? exc.message : String(exc)}`);
-        }
-        const nowSec = Date.now() / 1000;
-        this._certCache.set(cacheKey, {
-            certPem,
-            validatedAt: nowSec,
-            refreshAfter: nowSec + PEER_CERT_CACHE_TTL,
-        });
-        try {
-            // peer 证书只存版本目录，不覆盖 cert.pem
-            this._keystore.saveCert(aid, certPem, certFingerprint, { makeActive: false });
-        }
-        catch (exc) {
-            _clientLog('error', '写入证书到 keystore 失败 (aid=%s, fp=%s): %s', aid, certFingerprint ?? '', formatCaughtError(exc));
+        catch (err) {
+            this._clientLog.debug(`_fetchPeerCert exit (error): elapsed=${Date.now() - tStart}ms aid=${aid} err=${err instanceof Error ? err.message : String(err)}`);
+            throw err;
         }
-        return certPem;
     }
     /** 获取对方所有设备的 prekey 列表。 */
     async _fetchPeerPrekeys(peerAid) {
-        const cachedList = this._peerPrekeysCache.get(peerAid);
-        if (cachedList && Date.now() / 1000 < cachedList.expireAt) {
-            const normalized = normalizePeerPrekeys(cachedList.items);
-            if (normalized.length > 0) {
-                return normalized.map((item) => ({ ...item }));
-            }
-        }
-        const cached = this._e2ee.getCachedPrekey(peerAid);
-        if (cached !== null) {
-            const normalized = normalizePeerPrekeys([cached]);
-            if (normalized.length > 0)
-                return normalized.map((item) => ({ ...item }));
-        }
+        const tStart = Date.now();
+        this._clientLog.debug(`_fetchPeerPrekeys enter: aid=${peerAid}`);
         try {
-            const result = await this._transport.call('message.e2ee.get_prekey', { aid: peerAid });
-            if (!isJsonObject(result)) {
-                throw new ValidationError(`invalid prekey response for ${peerAid}`);
-            }
-            if (result.found === false) {
-                return [];
-            }
-            const devicePrekeys = Array.isArray(result.device_prekeys) ? result.device_prekeys : null;
-            if (devicePrekeys) {
-                const normalized = normalizePeerPrekeys(devicePrekeys);
+            const cachedList = this._peerPrekeysCache.get(peerAid);
+            if (cachedList && Date.now() / 1000 < cachedList.expireAt) {
+                const normalized = normalizePeerPrekeys(cachedList.items);
                 if (normalized.length > 0) {
-                    this._peerPrekeysCache.set(peerAid, {
-                        items: normalized.map((item) => ({ ...item })),
-                        expireAt: Date.now() / 1000 + PEER_PREKEYS_CACHE_TTL,
-                    });
-                    this._e2ee.cachePrekey(peerAid, normalized[0]);
-                    return normalized;
+                    this._clientLog.debug(`_fetchPeerPrekeys exit: elapsed=${Date.now() - tStart}ms aid=${peerAid} (cache_hit count=${normalized.length})`);
+                    return normalized.map((item) => ({ ...item }));
                 }
             }
-            if (!isPeerPrekeyResponse(result)) {
-                throw new ValidationError(`invalid prekey response for ${peerAid}`);
-            }
-            const prekey = result.prekey;
-            if (prekey) {
-                const normalized = normalizePeerPrekeys([prekey]);
+            const cached = this._e2ee.getCachedPrekey(peerAid);
+            if (cached !== null) {
+                const normalized = normalizePeerPrekeys([cached]);
                 if (normalized.length > 0) {
-                    this._peerPrekeysCache.set(peerAid, {
-                        items: normalized.map((item) => ({ ...item })),
-                        expireAt: Date.now() / 1000 + PEER_PREKEYS_CACHE_TTL,
-                    });
-                    this._e2ee.cachePrekey(peerAid, normalized[0]);
+                    this._clientLog.debug(`_fetchPeerPrekeys exit: elapsed=${Date.now() - tStart}ms aid=${peerAid} (e2ee_cache_hit)`);
                     return normalized.map((item) => ({ ...item }));
                 }
             }
-            if (result.found) {
-                throw new ValidationError(`invalid prekey response for ${peerAid}`);
+            try {
+                const result = await this._transport.call('message.e2ee.get_prekey', { aid: peerAid });
+                if (!isJsonObject(result)) {
+                    throw new ValidationError(`invalid prekey response for ${peerAid}`);
+                }
+                if (result.found === false) {
+                    this._clientLog.debug(`_fetchPeerPrekeys exit: elapsed=${Date.now() - tStart}ms aid=${peerAid} (not_found)`);
+                    return [];
+                }
+                const devicePrekeys = Array.isArray(result.device_prekeys) ? result.device_prekeys : null;
+                if (devicePrekeys) {
+                    const normalized = normalizePeerPrekeys(devicePrekeys);
+                    if (normalized.length > 0) {
+                        this._peerPrekeysCache.set(peerAid, {
+                            items: normalized.map((item) => ({ ...item })),
+                            expireAt: Date.now() / 1000 + PEER_PREKEYS_CACHE_TTL,
+                        });
+                        this._e2ee.cachePrekey(peerAid, normalized[0]);
+                        this._clientLog.debug(`_fetchPeerPrekeys exit: elapsed=${Date.now() - tStart}ms aid=${peerAid} (devices=${normalized.length})`);
+                        return normalized;
+                    }
+                }
+                if (!isPeerPrekeyResponse(result)) {
+                    throw new ValidationError(`invalid prekey response for ${peerAid}`);
+                }
+                const prekey = result.prekey;
+                if (prekey) {
+                    const normalized = normalizePeerPrekeys([prekey]);
+                    if (normalized.length > 0) {
+                        this._peerPrekeysCache.set(peerAid, {
+                            items: normalized.map((item) => ({ ...item })),
+                            expireAt: Date.now() / 1000 + PEER_PREKEYS_CACHE_TTL,
+                        });
+                        this._e2ee.cachePrekey(peerAid, normalized[0]);
+                        this._clientLog.debug(`_fetchPeerPrekeys exit: elapsed=${Date.now() - tStart}ms aid=${peerAid} (legacy_single)`);
+                        return normalized.map((item) => ({ ...item }));
+                    }
+                }
+                if (result.found) {
+                    throw new ValidationError(`invalid prekey response for ${peerAid}`);
+                }
+                this._clientLog.debug(`_fetchPeerPrekeys exit: elapsed=${Date.now() - tStart}ms aid=${peerAid} (empty)`);
+                return [];
             }
-            return [];
-        }
-        catch (exc) {
-            if (exc instanceof ValidationError) {
-                throw exc;
+            catch (exc) {
+                if (exc instanceof ValidationError) {
+                    throw exc;
+                }
+                throw new ValidationError(`failed to fetch peer prekey for ${peerAid}: ${exc instanceof Error ? exc.message : String(exc)}`);
             }
-            throw new ValidationError(`failed to fetch peer prekey for ${peerAid}: ${exc instanceof Error ? exc.message : String(exc)}`);
+        }
+        catch (err) {
+            this._clientLog.debug(`_fetchPeerPrekeys exit (error): elapsed=${Date.now() - tStart}ms aid=${peerAid} err=${err instanceof Error ? err.message : String(err)}`);
+            throw err;
         }
     }
     /** 获取对方的单个 prekey（兼容接口，优先返回第一条 device prekey）。 */
@@ -2873,10 +3104,10 @@ export class AUNClient {
         catch (exc) {
             // 刷新失败时：若内存缓存有 PKI 验证过的证书（未过期 x2 倍 TTL）则继续用
             if (cached && now < cached.validatedAt + PEER_CERT_CACHE_TTL * 2) {
-                _clientLog('debug', '刷新发送方 %s 证书失败，继续使用已验证的内存缓存: %s', aid, formatCaughtError(exc));
+                this._clientLog.debug(`refresh sender ${aid} cert failed, continuing with verified memory cache: ${formatCaughtError(exc)}`);
                 return true;
             }
-            _clientLog('warn', '获取发送方 %s 证书失败且无已验证缓存，拒绝信任: %s', aid, formatCaughtError(exc));
+            this._clientLog.warn(`failed to get sender ${aid} cert and no verified cache, rejecting trust: ${formatCaughtError(exc)}`);
             return false;
         }
     }
@@ -2898,33 +3129,50 @@ export class AUNClient {
     }
     /** 解密单条 P2P 消息 */
     async _decryptSingleMessage(message) {
-        const payload = message.payload;
-        if (!isJsonObject(payload))
-            return message;
-        const payloadObj = payload;
-        if (payloadObj.type !== 'e2ee.encrypted')
-            return message;
-        if (message.encrypted === false)
-            return message;
-        // 确保发送方证书已缓存到 keystore
-        const fromAid = String(message.from ?? '');
-        const senderCertFingerprint = String(payloadObj.sender_cert_fingerprint ?? payloadObj.aad?.sender_cert_fingerprint ?? '').trim().toLowerCase();
-        if (fromAid) {
-            const certReady = await this._ensureSenderCertCached(fromAid, senderCertFingerprint || undefined);
-            if (!certReady) {
-                _clientLog('warn', '无法获取发送方 %s 的证书，跳过解密', fromAid);
-                throw new Error(`发送方证书不可用: from=${fromAid}, mid=${message.message_id}`);
-            }
-        }
-        // 密码学解密（E2EEManager.decryptMessage 内含本地防重放）
-        const decrypted = this._e2ee.decryptMessage(message);
-        this._schedulePrekeyReplenishIfConsumed(decrypted);
-        // TS-015: 解密返回 null 表示失败（密文损坏/签名无效/重放等），
-        // 不得回退到原始密文投递给应用层，应抛出错误触发 undecryptable 事件
-        if (decrypted === null) {
-            throw new Error(`E2EE 解密失败: from=${message.from}, mid=${message.message_id}`);
-        }
-        return decrypted;
+        const tStart = Date.now();
+        const fromLog = String(message.from ?? '');
+        const midLog = String(message.message_id ?? '');
+        this._clientLog.debug(`_decryptSingleMessage enter: from=${fromLog}, mid=${midLog}`);
+        try {
+            const payload = message.payload;
+            if (!isJsonObject(payload)) {
+                this._clientLog.debug(`_decryptSingleMessage exit: elapsed=${Date.now() - tStart}ms (non-object payload)`);
+                return message;
+            }
+            const payloadObj = payload;
+            if (payloadObj.type !== 'e2ee.encrypted') {
+                this._clientLog.debug(`_decryptSingleMessage exit: elapsed=${Date.now() - tStart}ms (not encrypted type)`);
+                return message;
+            }
+            if (message.encrypted === false) {
+                this._clientLog.debug(`_decryptSingleMessage exit: elapsed=${Date.now() - tStart}ms (encrypted=false)`);
+                return message;
+            }
+            // 确保发送方证书已缓存到 keystore
+            const fromAid = String(message.from ?? '');
+            const senderCertFingerprint = String(payloadObj.sender_cert_fingerprint ?? payloadObj.aad?.sender_cert_fingerprint ?? '').trim().toLowerCase();
+            if (fromAid) {
+                const certReady = await this._ensureSenderCertCached(fromAid, senderCertFingerprint || undefined);
+                if (!certReady) {
+                    this._clientLog.warn(`cannot get sender ${fromAid} cert, skipping decrypt`);
+                    throw new Error(`发送方证书不可用: from=${fromAid}, mid=${message.message_id}`);
+                }
+            }
+            // 密码学解密（E2EEManager.decryptMessage 内含本地防重放）
+            const decrypted = this._e2ee.decryptMessage(message);
+            this._schedulePrekeyReplenishIfConsumed(decrypted);
+            // TS-015: 解密返回 null 表示失败（密文损坏/签名无效/重放等），
+            // 不得回退到原始密文投递给应用层，应抛出错误触发 undecryptable 事件
+            if (decrypted === null) {
+                throw new Error(`E2EE 解密失败: from=${message.from}, mid=${message.message_id}`);
+            }
+            this._clientLog.debug(`_decryptSingleMessage exit: elapsed=${Date.now() - tStart}ms from=${fromAid}, mid=${midLog}`);
+            return decrypted;
+        }
+        catch (err) {
+            this._clientLog.debug(`_decryptSingleMessage exit (error): elapsed=${Date.now() - tStart}ms err=${err instanceof Error ? err.message : String(err)}`);
+            throw err;
+        }
     }
     /** 批量解密 P2P 消息（用于 message.pull） */
     async _decryptMessages(messages) {
@@ -2948,7 +3196,7 @@ export class AUNClient {
                 if (fromAid) {
                     const certReady = await this._ensureSenderCertCached(fromAid, senderCertFingerprint || undefined);
                     if (!certReady) {
-                        _clientLog('warn', '无法获取发送方 %s 的证书，跳过解密', fromAid);
+                        this._clientLog.warn(`cannot get sender ${fromAid} cert, skipping decrypt`);
                         continue;
                     }
                 }
@@ -2959,7 +3207,7 @@ export class AUNClient {
                 }
                 else {
                     // TS-015: 解密失败不回退到密文，跳过该消息并记录
-                    _clientLog('warn', 'pull 消息解密失败，跳过: from=%s mid=%s', msg.from, msg.message_id);
+                    this._clientLog.warn(`pull message decrypt failed, skipping: from=${msg.from} mid=${msg.message_id}`);
                 }
             }
             else {
@@ -3012,23 +3260,37 @@ export class AUNClient {
     _scheduleRetryPendingDecryptMsgs(groupId) {
         if (!groupId || !this._pendingDecryptMsgs.has(`group:${groupId}`))
             return;
-        this._retryPendingDecryptMsgs(groupId).catch((exc) => _clientLog('warn', '群 %s pending 消息重试失败: %s', groupId, formatCaughtError(exc)));
+        this._retryPendingDecryptMsgs(groupId).catch((exc) => this._clientLog.warn(`group ${groupId} pending message retry failed: ${formatCaughtError(exc)}`));
     }
     async _recoverGroupEpochKey(groupId, epoch, senderAid = '', timeoutMs = 5000) {
-        const existing = await this._groupE2ee.loadSecret(groupId, epoch);
-        if (await this._groupEpochSecretReadyForRecovery(groupId, epoch, existing)) {
-            this._scheduleRetryPendingDecryptMsgs(groupId);
-            return true;
+        const tStart = Date.now();
+        this._clientLog.debug(`_recoverGroupEpochKey enter: group=${groupId}, epoch=${epoch}, sender=${senderAid || '-'}, timeout=${timeoutMs}ms`);
+        try {
+            const existing = await this._groupE2ee.loadSecret(groupId, epoch);
+            if (await this._groupEpochSecretReadyForRecovery(groupId, epoch, existing)) {
+                this._scheduleRetryPendingDecryptMsgs(groupId);
+                this._clientLog.debug(`_recoverGroupEpochKey exit: elapsed=${Date.now() - tStart}ms group=${groupId} (already_ready)`);
+                return true;
+            }
+            // inflight 去重：同 groupId:epoch 的并发恢复共享同一个 Promise
+            const key = `${groupId}:${epoch}`;
+            const inflight = this._groupEpochRecoveryInflight.get(key);
+            if (inflight) {
+                const result = await inflight;
+                this._clientLog.debug(`_recoverGroupEpochKey exit: elapsed=${Date.now() - tStart}ms group=${groupId} (joined_inflight) result=${result}`);
+                return result;
+            }
+            const promise = this._doRecoverGroupEpochKey(groupId, epoch, senderAid, timeoutMs)
+                .finally(() => this._groupEpochRecoveryInflight.delete(key));
+            this._groupEpochRecoveryInflight.set(key, promise);
+            const result = await promise;
+            this._clientLog.debug(`_recoverGroupEpochKey exit: elapsed=${Date.now() - tStart}ms group=${groupId} result=${result}`);
+            return result;
+        }
+        catch (err) {
+            this._clientLog.debug(`_recoverGroupEpochKey exit (error): elapsed=${Date.now() - tStart}ms group=${groupId} err=${err instanceof Error ? err.message : String(err)}`);
+            throw err;
         }
-        // inflight 去重：同 groupId:epoch 的并发恢复共享同一个 Promise
-        const key = `${groupId}:${epoch}`;
-        const inflight = this._groupEpochRecoveryInflight.get(key);
-        if (inflight)
-            return inflight;
-        const promise = this._doRecoverGroupEpochKey(groupId, epoch, senderAid, timeoutMs)
-            .finally(() => this._groupEpochRecoveryInflight.delete(key));
-        this._groupEpochRecoveryInflight.set(key, promise);
-        return promise;
     }
     static _extractGroupJoinMode(payload) {
         if (!isJsonObject(payload))
@@ -3121,13 +3383,13 @@ export class AUNClient {
             const myAid = this._aid || '';
             const keyPair = this._keystore.loadKeyPair(myAid);
             if (!keyPair?.private_key_pem) {
-                _clientLog('warn', '无法加载 AID 私钥用于 ECIES 解密: aid=%s', myAid);
+                this._clientLog.warn(`cannot load AID private key for ECIES decrypt: aid=${myAid}`);
                 return false;
             }
             const { eciesDecrypt } = await import('./e2ee-group.js');
             const groupSecret = eciesDecrypt(keyPair.private_key_pem, encryptedBytes);
             if (!groupSecret || groupSecret.length !== 32) {
-                _clientLog('warn', '服务端 epoch key ECIES 解密结果长度异常: group=%s epoch=%d len=%d', groupId, serverEpoch, groupSecret?.length ?? 0);
+                this._clientLog.warn(`server epoch key ECIES decrypt result length abnormal: group=${groupId} epoch=${serverEpoch} len=${groupSecret?.length ?? 0}`);
                 return false;
             }
             // 获取成员列表和 committed_rotation 用于 commitment / epoch_chain 验证
@@ -3164,7 +3426,7 @@ export class AUNClient {
             }
             catch { /* best effort */ }
             if (memberAids.length === 0) {
-                _clientLog('warn', '服务端 epoch key 恢复缺少成员快照: group=%s epoch=%d', groupId, serverEpoch);
+                this._clientLog.warn(`server epoch key recovery missing member snapshot: group=${groupId} epoch=${serverEpoch}`);
                 return false;
             }
             const commitment = computeMembershipCommitment(memberAids, serverEpoch, groupId, groupSecret);
@@ -3175,7 +3437,7 @@ export class AUNClient {
                 const committedEpoch = Number(committedRotation.target_epoch ?? serverEpoch);
                 const committedCommitment = String(committedRotation.key_commitment ?? '').trim();
                 if (committedEpoch === serverEpoch && committedCommitment && committedCommitment !== commitment) {
-                    _clientLog('warn', '服务端 epoch key 恢复 commitment 不匹配: group=%s epoch=%d', groupId, serverEpoch);
+                    this._clientLog.warn(`server epoch key recovery commitment mismatch: group=${groupId} epoch=${serverEpoch}`);
                     return false;
                 }
                 if (epochChain && committedEpoch === serverEpoch) {
@@ -3191,7 +3453,7 @@ export class AUNClient {
                     const prevChain = String(prevData?.epoch_chain ?? '').trim();
                     if (prevChain && rotatorAid) {
                         if (!verifyEpochChain(epochChain, prevChain, serverEpoch, commitment, rotatorAid)) {
-                            _clientLog('warn', '服务端 epoch key 恢复 epoch_chain 验证失败: group=%s epoch=%d rotator=%s', groupId, serverEpoch, rotatorAid);
+                            this._clientLog.warn(`server epoch key recovery epoch_chain verification failed: group=${groupId} epoch=${serverEpoch} rotator=${rotatorAid}`);
                             return false;
                         }
                         epochChainUnverified = false;
@@ -3204,14 +3466,14 @@ export class AUNClient {
             }
             const stored = storeGroupSecretEpoch(this._keystore, myAid, groupId, serverEpoch, groupSecret, commitment, memberAids, epochChain || undefined, '', epochChainUnverified, epochChainUnverifiedReason);
             if (!stored) {
-                _clientLog('warn', '服务端 epoch key 恢复存储失败: group=%s epoch=%d', groupId, serverEpoch);
+                this._clientLog.warn(`server epoch key recovery store failed: group=${groupId} epoch=${serverEpoch}`);
                 return false;
             }
-            _clientLog('info', '从服务端恢复 epoch key 成功: group=%s epoch=%d', groupId, serverEpoch);
+            this._clientLog.info(`recovered epoch key from server: group=${groupId} epoch=${serverEpoch}`);
             return true;
         }
         catch (exc) {
-            _clientLog('debug', '从服务端恢复 epoch key 失败: group=%s epoch=%d err=%s', groupId, epoch, formatCaughtError(exc));
+            this._clientLog.debug(`recover epoch key from server failed: group=${groupId} epoch=${epoch} err=${formatCaughtError(exc)}`);
             return false;
         }
     }
@@ -3238,7 +3500,7 @@ export class AUNClient {
                     groupSecretBytes = loaded.secret;
                 }
                 else {
-                    _clientLog('debug', '无法获取 group_secret 用于 ECIES 加密: group=%s epoch=%d', groupId, targetEpoch);
+                    this._clientLog.debug(`cannot get group_secret for ECIES encrypt: group=${groupId} epoch=${targetEpoch}`);
                     return {};
                 }
             }
@@ -3259,21 +3521,23 @@ export class AUNClient {
                     encryptedKeys[aid] = ciphertext.toString('base64');
                 }
                 catch (exc) {
-                    _clientLog('debug', '为成员 %s 构建 ECIES epoch key 失败: %s', aid, formatCaughtError(exc));
+                    this._clientLog.debug(`building ECIES epoch key for member ${aid} failed: ${formatCaughtError(exc)}`);
                     continue;
                 }
             }
             return encryptedKeys;
         }
         catch (exc) {
-            _clientLog('debug', '构建 encrypted_keys 失败: group=%s err=%s', groupId, formatCaughtError(exc));
+            this._clientLog.debug(`building encrypted_keys failed: group=${groupId} err=${formatCaughtError(exc)}`);
             return {};
         }
     }
     async _doRecoverGroupEpochKey(groupId, epoch, senderAid, timeoutMs) {
+        this._clientLog.debug(`group ${groupId} epoch ${epoch} key recovery start: sender=${senderAid || '-'}, timeout=${timeoutMs}ms`);
         // 仅 open / invite_code 群允许从服务端拉取 ECIES 加密的 epoch key
         if (await this._groupAllowsMemberEpochRotation(groupId)) {
             if (await this._tryRecoverEpochKeyFromServer(groupId, epoch)) {
+                this._clientLog.debug(`group ${groupId} epoch ${epoch} recovered from server`);
                 this._scheduleRetryPendingDecryptMsgs(groupId);
                 return true;
             }
@@ -3304,16 +3568,18 @@ export class AUNClient {
             }
         }
         catch {
-            _clientLog('debug', '群 %s 查询在线成员失败，回退全量候选', groupId);
+            this._clientLog.debug(`group ${groupId} query online members failed, falling back to all candidates`);
         }
         if (onlineAids !== null) {
             if (onlineAids.length === 0) {
-                _clientLog('info', '群 %s epoch %s 恢复失败：无在线成员可请求密钥', groupId, String(epoch));
+                this._clientLog.info(`group ${groupId} epoch ${String(epoch)} recovery failed: no online members to request key`);
                 return false;
             }
+            this._clientLog.debug(`group ${groupId} epoch ${epoch} P2P key recovery: requesting from ${onlineAids.length} online members`);
             await this._requestGroupKeyFromOnline(groupId, epoch, onlineAids, epochResult);
         }
         else {
+            this._clientLog.debug(`group ${groupId} epoch ${epoch} P2P key recovery: requesting from all candidates`);
             await this._requestGroupKeyFromCandidates(groupId, epoch, epochResult);
         }
         const deadline = Date.now() + timeoutMs;
@@ -3321,14 +3587,20 @@ export class AUNClient {
             await new Promise(resolve => setTimeout(resolve, 150));
             const secret = await this._groupE2ee.loadSecret(groupId, epoch);
             if (await this._groupEpochSecretReadyForRecovery(groupId, epoch, secret)) {
+                this._clientLog.debug(`group ${groupId} epoch ${epoch} P2P key recovery success`);
                 this._scheduleRetryPendingDecryptMsgs(groupId);
                 return true;
             }
         }
         const secret = await this._groupE2ee.loadSecret(groupId, epoch);
         const ready = await this._groupEpochSecretReadyForRecovery(groupId, epoch, secret);
-        if (ready)
+        if (ready) {
+            this._clientLog.debug(`group ${groupId} epoch ${epoch} P2P key recovery success (post-deadline check)`);
             this._scheduleRetryPendingDecryptMsgs(groupId);
+        }
+        else {
+            this._clientLog.warn(`group ${groupId} epoch ${epoch} P2P key recovery timeout: timeout=${timeoutMs}ms`);
+        }
         return ready;
     }
     /** 只向在线成员发送密钥恢复请求 */
@@ -3378,48 +3650,70 @@ export class AUNClient {
         }
     }
     async _decryptGroupMessage(message, opts) {
-        const payload = message.payload;
-        if (!isJsonObject(payload))
-            return this._attachGroupDispatchModeToPayload(message);
-        const payloadObj = payload;
-        if (payloadObj.type !== 'e2ee.group_encrypted')
-            return this._attachGroupDispatchModeToPayload(message);
-        // 确保发送方证书已缓存（签名验证需要）
-        const senderAid = String(message.from ?? message.sender_aid ?? '');
-        if (senderAid) {
-            const certOk = await this._ensureSenderCertCached(senderAid);
-            if (!certOk) {
-                _clientLog('warn', '群消息解密跳过：发送方 %s 证书不可用', senderAid);
-                return message;
-            }
-        }
-        // 先尝试直接解密
-        const result = this._groupE2ee.decrypt(message, opts);
-        if (result !== null && result.e2ee) {
-            return this._attachGroupDispatchModeToPayload(result);
-        }
-        // replay guard 命中：decrypt 返回了原消息（非 null）但无 e2ee 字段
-        // 不是解密失败，不应触发 recover
-        if (result !== null) {
-            return result;
-        }
-        // 真正的解密失败（result === null），尝试密钥恢复后重试
-        const groupId = String(message.group_id ?? '');
-        const sender = String(message.from ?? message.sender_aid ?? '');
-        const epoch = Number(payloadObj.epoch ?? 0);
-        if (epoch > 0 && groupId) {
-            try {
-                if (await this._recoverGroupEpochKey(groupId, epoch, sender, 5000)) {
-                    const retry = await this._groupE2ee.decrypt(message, opts);
-                    if (retry !== null && retry.e2ee)
-                        return this._attachGroupDispatchModeToPayload(retry);
+        const tStart = Date.now();
+        const groupIdLog = String(message.group_id ?? '');
+        const senderLog = String(message.from ?? message.sender_aid ?? '');
+        this._clientLog.debug(`_decryptGroupMessage enter: group=${groupIdLog}, from=${senderLog}, mid=${String(message.message_id ?? '')}`);
+        try {
+            const payload = message.payload;
+            if (!isJsonObject(payload)) {
+                const r = this._attachGroupDispatchModeToPayload(message);
+                this._clientLog.debug(`_decryptGroupMessage exit: elapsed=${Date.now() - tStart}ms (non-object payload)`);
+                return r;
+            }
+            const payloadObj = payload;
+            if (payloadObj.type !== 'e2ee.group_encrypted') {
+                const r = this._attachGroupDispatchModeToPayload(message);
+                this._clientLog.debug(`_decryptGroupMessage exit: elapsed=${Date.now() - tStart}ms (not group_encrypted)`);
+                return r;
+            }
+            // 确保发送方证书已缓存（签名验证需要）
+            const senderAid = String(message.from ?? message.sender_aid ?? '');
+            if (senderAid) {
+                const certOk = await this._ensureSenderCertCached(senderAid);
+                if (!certOk) {
+                    this._clientLog.warn(`group message decrypt skipped: sender ${senderAid} cert unavailable`);
+                    this._clientLog.debug(`_decryptGroupMessage exit: elapsed=${Date.now() - tStart}ms (cert_unavailable)`);
+                    return message;
                 }
             }
-            catch (exc) {
-                _clientLog('debug', '群 %s epoch %s 同步恢复失败: %s', groupId, epoch, formatCaughtError(exc));
+            // 先尝试直接解密
+            const result = this._groupE2ee.decrypt(message, opts);
+            if (result !== null && result.e2ee) {
+                this._clientLog.debug(`_decryptGroupMessage exit: elapsed=${Date.now() - tStart}ms (direct_ok)`);
+                return this._attachGroupDispatchModeToPayload(result);
+            }
+            // replay guard 命中：decrypt 返回了原消息（非 null）但无 e2ee 字段
+            // 不是解密失败，不应触发 recover
+            if (result !== null) {
+                this._clientLog.debug(`_decryptGroupMessage exit: elapsed=${Date.now() - tStart}ms (replay_guard)`);
+                return result;
+            }
+            // 真正的解密失败（result === null），尝试密钥恢复后重试
+            const groupId = String(message.group_id ?? '');
+            const sender = String(message.from ?? message.sender_aid ?? '');
+            const epoch = Number(payloadObj.epoch ?? 0);
+            if (epoch > 0 && groupId) {
+                try {
+                    if (await this._recoverGroupEpochKey(groupId, epoch, sender, 5000)) {
+                        const retry = await this._groupE2ee.decrypt(message, opts);
+                        if (retry !== null && retry.e2ee) {
+                            this._clientLog.debug(`_decryptGroupMessage exit: elapsed=${Date.now() - tStart}ms (recover_ok)`);
+                            return this._attachGroupDispatchModeToPayload(retry);
+                        }
+                    }
+                }
+                catch (exc) {
+                    this._clientLog.debug(`group ${groupId} epoch ${epoch} sync recovery failed: ${formatCaughtError(exc)}`);
+                }
             }
+            this._clientLog.debug(`_decryptGroupMessage exit: elapsed=${Date.now() - tStart}ms (fallback_plain)`);
+            return message;
+        }
+        catch (err) {
+            this._clientLog.debug(`_decryptGroupMessage exit (error): elapsed=${Date.now() - tStart}ms err=${err instanceof Error ? err.message : String(err)}`);
+            throw err;
         }
-        return message;
     }
     _attachGroupDispatchModeToPayload(message) {
         const payload = message.payload;
@@ -3537,7 +3831,7 @@ export class AUNClient {
                 if (fromAid) {
                     const certReady = await this._ensureSenderCertCached(fromAid, senderCertFingerprint || undefined);
                     if (!certReady) {
-                        _clientLog('warn', '无法获取发送方 %s 的证书，跳过 message.thought.get 解密', fromAid);
+                        this._clientLog.warn(`cannot get sender ${fromAid} cert, skipping message.thought.get decrypt`);
                         decryptFailed = true;
                     }
                 }
@@ -3598,6 +3892,7 @@ export class AUNClient {
         const failed = [];
         let lastHeartbeat = Date.now();
         const distributions = (Array.isArray(info.distributions) ? info.distributions : []);
+        this._clientLog.debug(`epoch key distribution start: rotation=${rotationId}, target_members=${distributions.length}`);
         for (const dist of distributions) {
             if (!isJsonObject(dist) || !dist.to || !isJsonObject(dist.payload))
                 continue;
@@ -3622,7 +3917,7 @@ export class AUNClient {
                     }
                     else {
                         failed.push(String(dist.to));
-                        _clientLog('warn', 'epoch 密钥分发失败 (to=%s): %s', dist.to, formatCaughtError(exc));
+                        this._clientLog.warn(`epoch key distribution failed (to=${dist.to}): ${formatCaughtError(exc)}`);
                     }
                 }
             }
@@ -3640,23 +3935,26 @@ export class AUNClient {
             return isJsonObject(result) && result.success === true;
         }
         catch (exc) {
-            _clientLog('warn', '刷新 epoch rotation lease 失败: rotation=%s err=%s', rotationId, formatCaughtError(exc));
+            this._clientLog.warn(`refresh epoch rotation lease failed: rotation=${rotationId} err=${formatCaughtError(exc)}`);
             return false;
         }
     }
     async _ackGroupRotationKey(rotationId, keyCommitment, deviceId) {
         if (!rotationId)
             return false;
+        this._clientLog.debug(`_ackGroupRotationKey enter: rotation=${rotationId}, commitment=${keyCommitment}, device=${deviceId ?? this._deviceId}`);
         try {
             const result = await this.call('group.e2ee.ack_rotation_key', {
                 rotation_id: rotationId,
                 key_commitment: keyCommitment,
                 device_id: deviceId ?? this._deviceId,
             });
-            return isJsonObject(result) && result.success === true;
+            const success = isJsonObject(result) && result.success === true;
+            this._clientLog.debug(`_ackGroupRotationKey done: rotation=${rotationId}, success=${success}`);
+            return success;
         }
         catch (exc) {
-            _clientLog('warn', '提交 epoch key ack 失败: rotation=%s err=%s', rotationId, formatCaughtError(exc));
+            this._clientLog.warn(`submit epoch key ack failed: rotation=${rotationId} err=${formatCaughtError(exc)}`);
             return false;
         }
     }
@@ -3684,7 +3982,7 @@ export class AUNClient {
                                 ? committedRotation.expected_members.map((item) => String(item ?? '').trim()).filter(Boolean)
                                 : [];
                             if (this._aid && !expectedMembers.includes(this._aid)) {
-                                _clientLog('debug', '放行 group key 分发：新成员恢复 commitment 不匹配属正常 group=%s epoch=%s', groupId, epoch);
+                                this._clientLog.debug(`allowing group key distribution: new member recovery commitment mismatch is normal group=${groupId} epoch=${epoch}`);
                             }
                             else {
                                 return false;
@@ -3693,7 +3991,7 @@ export class AUNClient {
                     }
                     return true;
                 }
-                _clientLog('info', '拒绝缺少 rotation_id 的未来 epoch key 分发: group=%s epoch=%s committed=%s', groupId, epoch, committedEpoch);
+                this._clientLog.info(`rejecting future epoch key distribution missing rotation_id: group=${groupId} epoch=${epoch} committed=${committedEpoch}`);
                 return false;
             }
             const pending = isJsonObject(epochResult.pending_rotation) ? epochResult.pending_rotation : null;
@@ -3714,10 +4012,10 @@ export class AUNClient {
             }
         }
         catch (exc) {
-            _clientLog('warn', '拒绝无法校验 active rotation 的 epoch key 分发: group=%s rotation=%s err=%s', groupId, rotationId, formatCaughtError(exc));
+            this._clientLog.warn(`rejecting epoch key distribution: cannot verify active rotation: group=${groupId} rotation=${rotationId} err=${formatCaughtError(exc)}`);
             return false;
         }
-        _clientLog('info', '拒绝非 pending/committed 状态的 epoch key 分发: group=%s rotation=%s epoch=%s', groupId, rotationId, epoch);
+        this._clientLog.info(`rejecting epoch key distribution: rotation not in pending/committed state: group=${groupId} rotation=${rotationId} epoch=${epoch}`);
         return false;
     }
     async _discardGroupDistributionIfStale(payload) {
@@ -3732,10 +4030,10 @@ export class AUNClient {
             return;
         try {
             this._groupE2ee.discardPendingSecret(groupId, epoch, rotationId);
-            _clientLog('info', '丢弃 verify 后变为 stale 的 group epoch key: group=%s epoch=%s rotation=%s', groupId, epoch, rotationId);
+            this._clientLog.info(`discarding stale group epoch key after verify: group=${groupId} epoch=${epoch} rotation=${rotationId}`);
         }
         catch (exc) {
-            _clientLog('debug', '清理 stale group epoch key 失败: group=%s epoch=%s rotation=%s err=%s', groupId, epoch, rotationId, formatCaughtError(exc));
+            this._clientLog.debug(`cleanup stale group epoch key failed: group=${groupId} epoch=${epoch} rotation=${rotationId} err=${formatCaughtError(exc)}`);
         }
     }
     async _verifyGroupKeyResponseEpoch(payload) {
@@ -3752,7 +4050,7 @@ export class AUNClient {
                 return false;
             const committedEpoch = Number(epochResult.committed_epoch ?? epochResult.epoch ?? 0);
             if (epoch > committedEpoch) {
-                _clientLog('info', '拒绝未提交 epoch 的 group key response: group=%s epoch=%s committed=%s', groupId, epoch, committedEpoch);
+                this._clientLog.info(`rejecting uncommitted epoch group key response: group=${groupId} epoch=${epoch} committed=${committedEpoch}`);
                 return false;
             }
             const committedRotation = isJsonObject(epochResult.committed_rotation) ? epochResult.committed_rotation : null;
@@ -3763,7 +4061,7 @@ export class AUNClient {
                         ? committedRotation.expected_members.map((item) => String(item ?? '').trim()).filter(Boolean)
                         : [];
                     if (this._aid && !expectedMembers.includes(this._aid)) {
-                        _clientLog('debug', '放行 group key response：新成员恢复 commitment 不匹配属正常 group=%s epoch=%s', groupId, epoch);
+                        this._clientLog.debug(`allowing group key response: new member recovery commitment mismatch is normal group=${groupId} epoch=${epoch}`);
                     }
                     else {
                         return false;
@@ -3773,7 +4071,7 @@ export class AUNClient {
             return true;
         }
         catch (exc) {
-            _clientLog('warn', '拒绝无法校验 committed epoch 的 group key response: group=%s epoch=%s err=%s', groupId, epoch, formatCaughtError(exc));
+            this._clientLog.warn(`rejecting group key response: cannot verify committed epoch: group=${groupId} epoch=${epoch} err=${formatCaughtError(exc)}`);
             return false;
         }
     }
@@ -3788,7 +4086,7 @@ export class AUNClient {
             return isJsonObject(result) && result.success === true;
         }
         catch (exc) {
-            _clientLog('warn', '中止 epoch rotation 失败: rotation=%s err=%s', rotationId, formatCaughtError(exc));
+            this._clientLog.warn(`abort epoch rotation failed: rotation=${rotationId} err=${formatCaughtError(exc)}`);
             return false;
         }
     }
@@ -3822,7 +4120,7 @@ export class AUNClient {
             if (this._closing || this._state !== 'connected')
                 return;
             this._maybeLeadRotateGroupEpoch(groupId, opts.triggerId, opts.expectedEpoch)
-                .catch((exc) => _clientLog('warn', 'group epoch rotation retry failed: %s', formatCaughtError(exc)));
+                .catch((exc) => this._clientLog.warn(`group epoch rotation retry failed: ${formatCaughtError(exc)}`));
         }, this._rotationRetryDelayMs(opts.pending));
         this._groupEpochRotationRetryTimers.set(retryKey, timer);
         this._unrefTimer(timer);
@@ -3834,7 +4132,7 @@ export class AUNClient {
             if (this._closing || this._state !== 'connected')
                 return;
             if (Date.now() - started > 20000) {
-                _clientLog('warn', 'group epoch create sync still in-flight; skip duplicate sync (group=%s)', groupId);
+                this._clientLog.warn(`group epoch create sync still in-flight; skip duplicate sync (group=${groupId})`);
                 return;
             }
             await new Promise((resolve) => setTimeout(resolve, 200));
@@ -3867,12 +4165,12 @@ export class AUNClient {
                     const beginResult = await this.call('group.e2ee.begin_rotation', rotateParams);
                     const rotation = isJsonObject(beginResult) && isJsonObject(beginResult.rotation) ? beginResult.rotation : null;
                     if (!isJsonObject(beginResult) || beginResult.success !== true || !rotation) {
-                        _clientLog('warn', 'group epoch begin failed; stop key distribution (group=%s, returned=%s)', groupId, JSON.stringify(beginResult));
+                        this._clientLog.warn(`group epoch begin failed; stop key distribution (group=${groupId}, returned=${JSON.stringify(beginResult)})`);
                         return;
                     }
                     const activeRotationId = String(rotation.rotation_id ?? rotationId);
                     if (!await this._ackGroupRotationKey(activeRotationId, secretData.commitment)) {
-                        _clientLog('warn', 'group epoch self ack failed (group=%s, rotation=%s)', groupId, activeRotationId);
+                        this._clientLog.warn(`group epoch self ack failed (group=${groupId}, rotation=${activeRotationId})`);
                         await this._abortGroupRotation(activeRotationId, 'self_ack_failed');
                         return;
                     }
@@ -3889,17 +4187,17 @@ export class AUNClient {
                         storeGroupSecret(this._keystore, this._aid, groupId, 1, secretData.secret, secretData.commitment, secretData.member_aids, secretData.epoch_chain);
                         return;
                     }
-                    _clientLog('warn', 'group epoch commit failed (group=%s, returned=%s)', groupId, JSON.stringify(commitResult));
+                    this._clientLog.warn(`group epoch commit failed (group=${groupId}, returned=${JSON.stringify(commitResult)})`);
                     return;
                 }
                 catch (exc) {
                     if (attempt < maxRetries) {
                         const delay = 500 * Math.pow(2, attempt - 1);
-                        _clientLog('warn', '同步 epoch 到服务端失败 (group=%s, 第%d/%d次): %s, %dms后重试', groupId, attempt, maxRetries, formatCaughtError(exc), delay);
+                        this._clientLog.warn(`sync epoch to server failed (group=${groupId}, attempt ${attempt}/${maxRetries}): ${formatCaughtError(exc)}, retrying in ${delay}ms`);
                         await new Promise(r => setTimeout(r, delay));
                     }
                     else {
-                        _clientLog('error', '同步 epoch 到服务端最终失败 (group=%s, 已重试%d次): %s', groupId, maxRetries, formatCaughtError(exc));
+                        this._clientLog.error(`sync epoch to server final failure (group=${groupId}, retried ${maxRetries} times): ${formatCaughtError(exc)}`, exc instanceof Error ? exc : undefined);
                     }
                 }
             }
@@ -3913,9 +4211,13 @@ export class AUNClient {
      * 使用服务端两阶段 rotation，避免服务端先提交但密钥未分发。
      */
     async _rotateGroupEpoch(groupId, triggerId = '', expectedEpoch = null) {
+        const tStart = Date.now();
+        this._clientLog.debug(`_rotateGroupEpoch enter: group=${groupId}, trigger=${triggerId || '-'}, expectedEpoch=${String(expectedEpoch)}`);
         try {
-            if (!this._aid)
+            if (!this._aid) {
+                this._clientLog.debug(`_rotateGroupEpoch exit: elapsed=${Date.now() - tStart}ms group=${groupId} (no_aid)`);
                 return;
+            }
             const memberAids = await this._getGroupMemberAids(groupId);
             if (triggerId && this._groupMembershipRotationDone.has(triggerId))
                 return;
@@ -3930,7 +4232,7 @@ export class AUNClient {
                     && serverEpoch === expectedEpoch
                     && this._rotationExpectedMembersStale(pendingRotation, memberAids));
                 if (stalePending && await this._abortGroupRotation(pendingRotationId, 'membership_changed_during_rotation')) {
-                    _clientLog('info', 'aborted stale pending group epoch rotation: group=%s rotation=%s', groupId, pendingRotationId || '-');
+                    this._clientLog.info(`aborted stale pending group epoch rotation: group=${groupId} rotation=${pendingRotationId || '-'}`);
                 }
                 else {
                     this._scheduleGroupRotationRetry(groupId, {
@@ -3945,7 +4247,7 @@ export class AUNClient {
             if (expectedEpoch !== null && serverEpoch !== expectedEpoch) {
                 if (triggerId)
                     this._groupMembershipRotationDone.add(triggerId);
-                _clientLog('info', 'skip membership epoch rotation: group=%s expected_epoch=%d server_epoch=%d trigger=%s', groupId, expectedEpoch, serverEpoch, triggerId || '-');
+                this._clientLog.info(`skip membership epoch rotation: group=${groupId} expected_epoch=${expectedEpoch} server_epoch=${serverEpoch} trigger=${triggerId || '-'}`);
                 return;
             }
             const currentEpoch = expectedEpoch ?? serverEpoch;
@@ -3961,7 +4263,7 @@ export class AUNClient {
                     const rawChain = String(cr.epoch_chain ?? '').trim();
                     if (rawChain) {
                         prevChainHint = rawChain;
-                        _clientLog('info', '新成员轮换补充 prev epoch chain from server: group=%s epoch=%d', groupId, currentEpoch);
+                        this._clientLog.info(`new member rotation supplementing prev epoch chain from server: group=${groupId} epoch=${currentEpoch}`);
                     }
                 }
             }
@@ -3973,7 +4275,7 @@ export class AUNClient {
                     this._groupE2ee.discardPendingSecret(groupId, targetEpoch, rotationId);
                 }
                 catch (cleanupExc) {
-                    _clientLog('debug', '清理本地 pending group key 失败: group=%s epoch=%s rotation=%s err=%s', groupId, targetEpoch, rotationId, formatCaughtError(cleanupExc));
+                    this._clientLog.debug(`cleanup local pending group key failed: group=${groupId} epoch=${targetEpoch} rotation=${rotationId} err=${formatCaughtError(cleanupExc)}`);
                 }
             };
             const rotateParams = {
@@ -4027,14 +4329,14 @@ export class AUNClient {
                         pending: null,
                     });
                 }
-                _clientLog('warn', 'group epoch begin failed; stop key distribution (group=%s, current_epoch=%d, returned=%s)', groupId, currentEpoch, JSON.stringify(beginResult));
+                this._clientLog.warn(`group epoch begin failed; stop key distribution (group=${groupId}, current_epoch=${currentEpoch}, returned=${JSON.stringify(beginResult)})`);
                 discardGeneratedPending();
                 return;
             }
             const activeRotationId = String(rotation.rotation_id ?? rotationId);
             const distributeResult = await this._distributeGroupEpochKey(info, activeRotationId);
             if (distributeResult.failed.length > 0) {
-                _clientLog('warn', 'group epoch key distribution incomplete; abort rotation before retry (group=%s rotation=%s failed=%s)', groupId, activeRotationId, distributeResult.failed.join(','));
+                this._clientLog.warn(`group epoch key distribution incomplete; abort rotation before retry (group=${groupId} rotation=${activeRotationId} failed=${distributeResult.failed.join(',')})`);
                 await this._abortGroupRotation(activeRotationId, 'distribution_failed');
                 this._scheduleGroupRotationRetry(groupId, {
                     reason: 'membership_changed',
@@ -4047,7 +4349,7 @@ export class AUNClient {
             }
             await this._heartbeatGroupRotation(activeRotationId);
             if (!await this._ackGroupRotationKey(activeRotationId, String(info.commitment ?? ''))) {
-                _clientLog('warn', 'group epoch self ack failed; abort rotation before retry (group=%s rotation=%s)', groupId, activeRotationId);
+                this._clientLog.warn(`group epoch self ack failed; abort rotation before retry (group=${groupId} rotation=${activeRotationId})`);
                 await this._abortGroupRotation(activeRotationId, 'self_ack_failed');
                 this._scheduleGroupRotationRetry(groupId, {
                     reason: 'membership_changed',
@@ -4068,7 +4370,7 @@ export class AUNClient {
             }
             const commitResult = await this.call('group.e2ee.commit_rotation', commitParams);
             if (!isJsonObject(commitResult) || commitResult.success !== true) {
-                _clientLog('warn', 'group epoch commit failed (group=%s, rotation=%s, returned=%s)', groupId, activeRotationId, JSON.stringify(commitResult));
+                this._clientLog.warn(`group epoch commit failed (group=${groupId}, rotation=${activeRotationId}, returned=${JSON.stringify(commitResult)})`);
                 this._scheduleGroupRotationRetry(groupId, {
                     reason: 'membership_changed',
                     triggerId,
@@ -4092,7 +4394,7 @@ export class AUNClient {
                     storeGroupSecret(this._keystore, this._aid, groupId, targetEpoch, committedSecret.secret, committedSecret.commitment, committedSecret.member_aids.length > 0 ? committedSecret.member_aids : memberAids, committedSecret.epoch_chain);
                 }
                 else {
-                    _clientLog('warn', 'group epoch commit succeeded but local target key does not match committed rotation; keep pending blocked (group=%s rotation=%s epoch=%s)', groupId, activeRotationId, targetEpoch);
+                    this._clientLog.warn(`group epoch commit succeeded but local target key does not match committed rotation; keep pending blocked (group=${groupId} rotation=${activeRotationId} epoch=${targetEpoch})`);
                 }
             }
             if (triggerId) {
@@ -4101,13 +4403,17 @@ export class AUNClient {
                     this._groupMembershipRotationDone = new Set(Array.from(this._groupMembershipRotationDone).slice(-1000));
                 }
             }
+            this._clientLog.debug(`_rotateGroupEpoch done: group=${groupId}, targetEpoch=${targetEpoch}, rotation=${activeRotationId}, trigger=${triggerId || '-'}`);
+            this._clientLog.debug(`_rotateGroupEpoch exit: elapsed=${Date.now() - tStart}ms group=${groupId}`);
         }
         catch (exc) {
             this._logE2eeError('rotate_epoch', groupId, '', exc);
+            this._clientLog.debug(`_rotateGroupEpoch exit (error): elapsed=${Date.now() - tStart}ms group=${groupId} err=${exc instanceof Error ? exc.message : String(exc)}`);
         }
     }
     /** 将当前 group_secret 通过 P2P E2EE 分发给新成员 */
     async _distributeKeyToNewMember(groupId, newMemberAid) {
+        this._clientLog.debug(`_distributeKeyToNewMember enter: group=${groupId}, new_member=${newMemberAid}`);
         try {
             const secretData = this._groupE2ee.loadSecret(groupId);
             if (secretData === null)
@@ -4138,16 +4444,19 @@ export class AUNClient {
             // 重试 3 次，间隔递增（1s, 2s）
             for (let attempt = 0; attempt < 3; attempt++) {
                 try {
+                    this._clientLog.debug(`_distributeKeyToNewMember send attempt: group=${groupId}, new_member=${newMemberAid}, attempt=${attempt + 1}/3, epoch=${epoch}`);
                     await this.call('message.send', {
                         to: newMemberAid,
                         payload: distPayload,
                         encrypt: true,
                         persist_required: true,
                     });
+                    this._clientLog.debug(`_distributeKeyToNewMember success: group=${groupId}, new_member=${newMemberAid}, epoch=${epoch}`);
                     break; // 成功则跳出重试循环
                 }
                 catch (sendExc) {
                     if (attempt < 2) {
+                        this._clientLog.debug(`_distributeKeyToNewMember attempt failed, will retry: group=${groupId}, new_member=${newMemberAid}, attempt=${attempt + 1}/3, err=${formatCaughtError(sendExc)}`);
                         await new Promise(resolve => setTimeout(resolve, (attempt + 1) * 1000));
                     }
                     else {
@@ -4211,7 +4520,9 @@ export class AUNClient {
     static _SELF_JOIN_ROTATION_DELAY_MS = 6000;
     /** open/invite_code 入群后延迟轮换。 */
     async _delayedRotateAfterJoin(groupId, triggerId, expectedEpoch, allowMember = false, delayMs) {
-        await new Promise(resolve => setTimeout(resolve, delayMs ?? AUNClient._JOIN_ROTATION_DELAY_MS));
+        const delay = delayMs ?? AUNClient._JOIN_ROTATION_DELAY_MS;
+        this._clientLog.debug(`_delayedRotateAfterJoin enter: group=${groupId}, trigger_id=${triggerId}, expected_epoch=${expectedEpoch}, allow_member=${allowMember}, delay_ms=${delay}`);
+        await new Promise(resolve => setTimeout(resolve, delay));
         await this._maybeLeadRotateGroupEpoch(groupId, triggerId, expectedEpoch, allowMember);
     }
     /** 当新成员加入但缺少 old_epoch 时，将当前 epoch 密钥分发给新成员。 */
@@ -4220,8 +4531,11 @@ export class AUNClient {
             .filter(aid => aid && aid !== this._aid);
         if (!groupId || !this._aid || memberAids.length === 0)
             return;
-        if (!this._groupE2ee.hasSecret(groupId))
+        if (!this._groupE2ee.hasSecret(groupId)) {
+            this._clientLog.debug(`backfill skipped: group=${groupId}, no local epoch key`);
             return;
+        }
+        this._clientLog.debug(`backfill key distribution start: group=${groupId}, target_members=${JSON.stringify(memberAids)}`);
         for (const memberAid of memberAids) {
             const dedupeKey = `${triggerId || this._membershipRotationTriggerId(groupId, payload)}:backfill:${memberAid}`;
             if (this._groupMemberKeyBackfillDone.has(dedupeKey))
@@ -4285,8 +4599,9 @@ export class AUNClient {
             // 优先从 seq_tracker 表按行读取
             const loadAll = this._keystore.loadAllSeqs;
             if (typeof loadAll === 'function') {
-                const state = loadAll.call(this._keystore, this._aid, this._deviceId, this._slotId);
+                let state = loadAll.call(this._keystore, this._aid, this._deviceId, this._slotId);
                 if (state && Object.keys(state).length > 0) {
+                    state = this._migrateSeqStateGroupIds(state);
                     this._seqTracker.restoreState(state);
                     return;
                 }
@@ -4296,12 +4611,14 @@ export class AUNClient {
             if (typeof loader === 'function') {
                 const instanceState = loader.call(this._keystore, this._aid, this._deviceId, this._slotId);
                 if (instanceState && typeof instanceState.seq_tracker_state === 'object') {
-                    this._seqTracker.restoreState(instanceState.seq_tracker_state);
+                    let state = instanceState.seq_tracker_state;
+                    state = this._migrateSeqStateGroupIds(state);
+                    this._seqTracker.restoreState(state);
                 }
             }
         }
         catch (exc) {
-            _clientLog('warn', '恢复 SeqTracker 状态失败: %s', formatCaughtError(exc));
+            this._clientLog.warn(`restore SeqTracker state failed: ${formatCaughtError(exc)}`);
             // 通过内部 dispatcher 发布可观测事件，便于上层监控
             this._dispatcher.publish('seq_tracker.persist_error', {
                 phase: 'restore',
@@ -4312,6 +4629,59 @@ export class AUNClient {
             }).catch(() => { });
         }
     }
+    /**
+     * 把 seq_tracker state 里 group_event:/group_msg: 前缀的老/污染 group_id 归一化为 canonical。
+     * 冲突取 max。同时落盘删除老 ns、写入新 ns，避免下次启动重复迁移。
+     */
+    _migrateSeqStateGroupIds(state) {
+        if (!state || Object.keys(state).length === 0)
+            return state;
+        const renameMap = {};
+        for (const ns of Object.keys(state)) {
+            for (const prefix of ['group_event:', 'group_msg:']) {
+                if (ns.startsWith(prefix)) {
+                    const oldGid = ns.slice(prefix.length);
+                    const newGid = normalizeGroupId(oldGid);
+                    if (newGid && newGid !== oldGid) {
+                        renameMap[ns] = `${prefix}${newGid}`;
+                    }
+                    break;
+                }
+            }
+        }
+        if (Object.keys(renameMap).length === 0)
+            return state;
+        const newState = { ...state };
+        for (const [oldNs, newNs] of Object.entries(renameMap)) {
+            const oldVal = Number(newState[oldNs] ?? 0);
+            const curVal = Number(newState[newNs] ?? 0);
+            delete newState[oldNs];
+            newState[newNs] = Math.max(oldVal, curVal);
+        }
+        this._clientLog.info(`SeqTracker group_id migration: ${Object.keys(renameMap).length} namespaces rewritten`);
+        // 落盘
+        const saver = this._keystore.saveSeq;
+        const deleter = this._keystore.deleteSeq;
+        if (typeof saver === 'function' && this._aid) {
+            for (const [oldNs, newNs] of Object.entries(renameMap)) {
+                if (typeof deleter === 'function') {
+                    try {
+                        deleter.call(this._keystore, this._aid, this._deviceId, this._slotId, oldNs);
+                    }
+                    catch (e) {
+                        this._clientLog.debug(`delete old seq ns failed: ns=${oldNs} err=${formatCaughtError(e)}`);
+                    }
+                }
+                try {
+                    saver.call(this._keystore, this._aid, this._deviceId, this._slotId, newNs, newState[newNs]);
+                }
+                catch (e) {
+                    this._clientLog.debug(`write new seq ns failed: ns=${newNs} err=${formatCaughtError(e)}`);
+                }
+            }
+        }
+        return newState;
+    }
     _currentSeqTrackerContext() {
         if (!this._aid)
             return null;
@@ -4366,7 +4736,7 @@ export class AUNClient {
             }
         }
         catch (exc) {
-            _clientLog('warn', '保存 SeqTracker 状态失败: %s', formatCaughtError(exc));
+            this._clientLog.warn(`save SeqTracker state failed: ${formatCaughtError(exc)}`);
             // 通过内部 dispatcher 发布可观测事件，便于上层监控
             this._dispatcher.publish('seq_tracker.persist_error', {
                 phase: 'save',
@@ -4421,6 +4791,7 @@ export class AUNClient {
     // ── 内部：连接 ────────────────────────────────────────────
     /** 执行一次连接流程 */
     async _connectOnce(params, allowReauth) {
+        const tStart = Date.now();
         const gatewayUrl = this._resolveGateway(params);
         this._gatewayUrl = gatewayUrl;
         this._slotId = String(params.slot_id ?? '');
@@ -4428,12 +4799,14 @@ export class AUNClient {
         const prevState = this._state;
         this._auth.setInstanceContext({ deviceId: this._deviceId, slotId: this._slotId });
         this._state = 'connecting';
+        this._clientLog.debug(`_connectOnce enter: gateway=${gatewayUrl}, allowReauth=${allowReauth}`);
         // 前置 restore：在 transport.connect 启动 reader 之前完成，
         // 避免 reader 把积压 push 交给空 tracker 的 handler，触发 S2 历史 gap 误补拉。
         this._refreshSeqTrackerContext();
         this._restoreSeqTrackerState();
         try {
             const challenge = await this._transport.connect(gatewayUrl);
+            this._clientLog.debug(`WebSocket connection established: gateway=${gatewayUrl}`);
             this._state = 'authenticating';
             if (allowReauth) {
                 const authContext = await this._auth.connectSession(this._transport, challenge, gatewayUrl, {
@@ -4448,8 +4821,8 @@ export class AUNClient {
                     if (identity && isJsonObject(identity)) {
                         this._identity = identity;
                         this._aid = String(identity.aid ?? this._aid ?? '');
-                        if (_debugLogger)
-                            _debugLogger.setAid(` [${this._aid}]`);
+                        if (this._aid)
+                            this._logger.bindAid(this._aid);
                         if (this._sessionParams !== null) {
                             this._sessionParams.access_token = String(auth.token ?? params.access_token ?? '');
                         }
@@ -4465,6 +4838,7 @@ export class AUNClient {
                 this._syncIdentityAfterConnect(String(params.access_token));
             }
             this._state = 'connected';
+            this._clientLog.debug(`auth complete, connection ready: aid=${this._aid ?? ''}, gateway=${gatewayUrl}`);
             await this._dispatcher.publish('connection.state', { state: this._state, gateway: gatewayUrl });
             // auth 阶段 aid 可能被 identity 覆盖（上方 this._aid = identity.aid）；
             // 若 context 发生变化，重新 refresh + restore，保持 tracker 与真实身份一致。
@@ -4478,11 +4852,13 @@ export class AUNClient {
                 await this._uploadPrekey();
             }
             catch (exc) {
-                _clientLog('warn', 'prekey 上传失败: %s', formatCaughtError(exc));
+                this._clientLog.warn(`prekey upload failed: ${formatCaughtError(exc)}`);
             }
+            this._clientLog.debug(`_connectOnce exit: elapsed=${Date.now() - tStart}ms gateway=${gatewayUrl}, aid=${this._aid ?? ''}`);
         }
         catch (err) {
             this._state = prevState === 'connected' ? 'disconnected' : 'idle';
+            this._clientLog.debug(`_connectOnce exit (error): elapsed=${Date.now() - tStart}ms gateway=${gatewayUrl} err=${err instanceof Error ? err.message : String(err)}`);
             throw err;
         }
     }
@@ -4515,8 +4891,8 @@ export class AUNClient {
         identity.access_token = accessToken;
         this._identity = identity;
         this._aid = String(identity.aid ?? this._aid ?? '');
-        if (_debugLogger)
-            _debugLogger.setAid(` [${this._aid}]`);
+        if (this._aid)
+            this._logger.bindAid(this._aid);
         const persistIdentity = this._auth._persistIdentity;
         if (typeof persistIdentity === 'function') {
             persistIdentity.call(this._auth, identity);
@@ -4648,10 +5024,10 @@ export class AUNClient {
                 consecutiveFailures = 0;
             }).catch((exc) => {
                 consecutiveFailures++;
-                _clientLog('warn', '心跳失败 (%s/%s): %s', consecutiveFailures, maxFailures, formatCaughtError(exc));
+                this._clientLog.warn(`heartbeat failed (${consecutiveFailures}/${maxFailures}): ${formatCaughtError(exc)}`);
                 this._dispatcher.publish('connection.error', { error: formatCaughtError(exc) }).catch(() => { });
                 if (consecutiveFailures >= maxFailures) {
-                    _clientLog('warn', '连续 %s 次心跳失败，触发断线重连', maxFailures);
+                    this._clientLog.warn(`${maxFailures} consecutive heartbeat failures, triggering reconnect`);
                     this._handleTransportDisconnect(exc instanceof Error ? exc : new Error(String(exc)));
                 }
             });
@@ -4715,7 +5091,7 @@ export class AUNClient {
                     if (exc instanceof AuthError) {
                         this._tokenRefreshFailures++;
                         if (this._tokenRefreshFailures >= 3) {
-                            _clientLog('warn', 'token 刷新连续失败 %d 次，停止刷新循环并触发重连', this._tokenRefreshFailures);
+                            this._clientLog.warn(`token refresh failed ${this._tokenRefreshFailures} consecutive times, stopping refresh loop and triggering reconnect`);
                             await this._dispatcher.publish('token.refresh_exhausted', {
                                 aid: this._identity?.aid ?? null,
                                 consecutive_failures: this._tokenRefreshFailures,
@@ -4725,7 +5101,7 @@ export class AUNClient {
                             this._handleTransportDisconnect(new Error('token refresh exhausted, triggering reconnect'));
                             return;
                         }
-                        _clientLog('debug', 'token 刷新失败 (%d/3)，下次重试: %s', this._tokenRefreshFailures, exc);
+                        this._clientLog.debug(`token refresh failed (${this._tokenRefreshFailures}/3), will retry: ${exc}`);
                     }
                     else {
                         await this._dispatcher.publish('connection.error', { error: formatCaughtError(exc) });
@@ -4827,7 +5203,7 @@ export class AUNClient {
                 this._prekeyReplenished.add(prekeyId);
             }
             catch (exc) {
-                _clientLog('warn', '消费 prekey %s 后补充 current prekey 失败: %s', prekeyId, formatCaughtError(exc));
+                this._clientLog.warn(`replenish current prekey after consuming ${prekeyId} failed: ${formatCaughtError(exc)}`);
             }
             finally {
                 this._prekeyReplenishInflight.delete(prekeyId);
@@ -4852,7 +5228,7 @@ export class AUNClient {
                     }
                 }
                 catch (exc) {
-                    _clientLog('warn', 'epoch 清理失败: %s', formatCaughtError(exc));
+                    this._clientLog.warn(`epoch cleanup failed: ${formatCaughtError(exc)}`);
                 }
             }, 3600_000);
             this._unrefTimer(this._groupEpochCleanupTimer);
@@ -4868,11 +5244,11 @@ export class AUNClient {
                         ? this._keystore.listGroupSecretIds(this._aid)
                         : [];
                     for (const gid of groupIds) {
-                        this._maybeLeadRotateGroupEpoch(gid).catch((exc) => _clientLog('warn', 'epoch 轮换失败: %s', formatCaughtError(exc)));
+                        this._maybeLeadRotateGroupEpoch(gid).catch((exc) => this._clientLog.warn(`epoch rotation failed: ${formatCaughtError(exc)}`));
                     }
                 }
                 catch (exc) {
-                    _clientLog('warn', 'epoch 轮换失败: %s', formatCaughtError(exc));
+                    this._clientLog.warn(`epoch rotation failed: ${formatCaughtError(exc)}`);
                 }
             }, rotateInterval * 1000);
             this._unrefTimer(this._groupEpochRotateTimer);
@@ -4920,7 +5296,7 @@ export class AUNClient {
     _onGatewayDisconnect(data) {
         const code = data?.code;
         const reason = data?.reason ?? '';
-        _clientLog('warn', '服务端主动断开: code=%s, reason=%s', code, reason);
+        this._clientLog.warn(`server initiated disconnect: code=${code}, reason=${reason}`);
         this._serverKicked = true;
     }
     /** 传输层断线回调 */
@@ -4930,6 +5306,7 @@ export class AUNClient {
         // 已在重连中则跳过，避免心跳超时和 transport 断线回调重复触发
         if (this._reconnectActive)
             return;
+        this._clientLog.warn(`transport disconnected: closeCode=${closeCode ?? 'none'}, error=${error ? formatCaughtError(error) : 'none'}`);
         this._state = 'disconnected';
         this._stopBackgroundTasks();
         await this._dispatcher.publish('connection.state', { state: this._state, error });
@@ -4941,7 +5318,7 @@ export class AUNClient {
         if (this._serverKicked || (closeCode !== undefined && AUNClient._NO_RECONNECT_CODES.has(closeCode))) {
             this._state = 'terminal_failed';
             const reason = this._serverKicked ? 'server kicked' : `close code ${closeCode}`;
-            _clientLog('warn', '抑制自动重连: %s', reason);
+            this._clientLog.warn(`suppressing auto-reconnect: ${reason}`);
             await this._dispatcher.publish('connection.state', {
                 state: this._state, error, reason,
             });
@@ -4957,8 +5334,9 @@ export class AUNClient {
             return;
         this._reconnectActive = true;
         this._reconnectAbort = new AbortController();
+        this._clientLog.debug(`reconnect loop started: serverInitiated=${String(serverInitiated)}, aid=${this._aid ?? ''}`);
         this._reconnectLoop(serverInitiated).catch((exc) => {
-            _clientLog('warn', '重连循环异常: %s', formatCaughtError(exc));
+            this._clientLog.warn(`reconnect loop error: ${formatCaughtError(exc)}`);
         });
     }
     /** 重连循环（for 循环 + AbortController，与 JS/Python 对齐） */
@@ -5005,6 +5383,7 @@ export class AUNClient {
                 }
                 await this._connectOnce(this._sessionParams, true);
                 // 重连成功，退出循环
+                this._clientLog.debug(`reconnect success: attempt=${attempt}, aid=${this._aid ?? ''}`);
                 this._reconnectActive = false;
                 this._reconnectAbort = null;
                 return;
@@ -5050,62 +5429,80 @@ export class AUNClient {
      * 服务端签发群 AID 证书，返回后将证书和私钥存入 keystore。
      */
     async createNamedGroup(groupName, opts = {}) {
-        const cp = new CryptoProvider();
-        const identity = cp.generateIdentity();
-        const params = {};
-        for (const [k, v] of Object.entries(opts)) {
-            params[k] = v;
-        }
-        params.group_name = groupName;
-        params.public_key = identity.public_key_der_b64;
-        params.curve = 'P-256';
-        const result = await this.call('group.create', params);
-        const groupInfo = result?.group;
-        const aidCert = result?.aid_cert;
-        const groupAid = String(groupInfo?.group_aid ?? '');
-        if (groupAid && aidCert) {
-            this._keystore.saveIdentity(groupAid, {
-                private_key_pem: identity.private_key_pem,
-                public_key: identity.public_key_der_b64,
-                curve: 'P-256',
-                type: 'group_identity',
-            });
-            const certPem = String(aidCert.cert ?? '');
-            if (certPem) {
-                this._keystore.saveCert(groupAid, certPem);
+        const tStart = Date.now();
+        this._clientLog.debug(`createNamedGroup enter: groupName=${groupName}`);
+        try {
+            const cp = new CryptoProvider();
+            const identity = cp.generateIdentity();
+            const params = {};
+            for (const [k, v] of Object.entries(opts)) {
+                params[k] = v;
+            }
+            params.group_name = groupName;
+            params.public_key = identity.public_key_der_b64;
+            params.curve = 'P-256';
+            const result = await this.call('group.create', params);
+            const groupInfo = result?.group;
+            const aidCert = result?.aid_cert;
+            const groupAid = String(groupInfo?.group_aid ?? '');
+            if (groupAid && aidCert) {
+                this._keystore.saveIdentity(groupAid, {
+                    private_key_pem: identity.private_key_pem,
+                    public_key: identity.public_key_der_b64,
+                    curve: 'P-256',
+                    type: 'group_identity',
+                });
+                const certPem = String(aidCert.cert ?? '');
+                if (certPem) {
+                    this._keystore.saveCert(groupAid, certPem);
+                }
             }
+            this._clientLog.debug(`createNamedGroup exit: elapsed=${Date.now() - tStart}ms groupAid=${groupAid}`);
+            return result;
+        }
+        catch (err) {
+            this._clientLog.debug(`createNamedGroup exit (error): elapsed=${Date.now() - tStart}ms err=${err instanceof Error ? err.message : String(err)}`);
+            throw err;
         }
-        return result;
     }
     /**
      * 为已有普通群绑定命名 AID（升级为命名群）。
      */
     async bindGroupAid(groupId, groupName) {
-        const cp = new CryptoProvider();
-        const identity = cp.generateIdentity();
-        const params = {
-            group_id: groupId,
-            group_name: groupName,
-            public_key: identity.public_key_der_b64,
-            curve: 'P-256',
-        };
-        const result = await this.call('group.bind_aid', params);
-        const groupInfo = result?.group;
-        const aidCert = result?.aid_cert;
-        const groupAid = String(groupInfo?.group_aid ?? '');
-        if (groupAid && aidCert) {
-            this._keystore.saveIdentity(groupAid, {
-                private_key_pem: identity.private_key_pem,
+        const tStart = Date.now();
+        this._clientLog.debug(`bindGroupAid enter: groupId=${groupId}, groupName=${groupName}`);
+        try {
+            const cp = new CryptoProvider();
+            const identity = cp.generateIdentity();
+            const params = {
+                group_id: groupId,
+                group_name: groupName,
                 public_key: identity.public_key_der_b64,
                 curve: 'P-256',
-                type: 'group_identity',
-            });
-            const certPem = String(aidCert.cert ?? '');
-            if (certPem) {
-                this._keystore.saveCert(groupAid, certPem);
+            };
+            const result = await this.call('group.bind_aid', params);
+            const groupInfo = result?.group;
+            const aidCert = result?.aid_cert;
+            const groupAid = String(groupInfo?.group_aid ?? '');
+            if (groupAid && aidCert) {
+                this._keystore.saveIdentity(groupAid, {
+                    private_key_pem: identity.private_key_pem,
+                    public_key: identity.public_key_der_b64,
+                    curve: 'P-256',
+                    type: 'group_identity',
+                });
+                const certPem = String(aidCert.cert ?? '');
+                if (certPem) {
+                    this._keystore.saveCert(groupAid, certPem);
+                }
             }
+            this._clientLog.debug(`bindGroupAid exit: elapsed=${Date.now() - tStart}ms groupAid=${groupAid}`);
+            return result;
+        }
+        catch (err) {
+            this._clientLog.debug(`bindGroupAid exit (error): elapsed=${Date.now() - tStart}ms err=${err instanceof Error ? err.message : String(err)}`);
+            throw err;
         }
-        return result;
     }
     /** 判断是否应重试重连 */
     static _shouldRetryReconnect(error) {