@agentunion/fastaun 0.2.15 → 0.2.17

package/dist/client.js

@@ -19,12 +19,13 @@ import { configFromMap, getDeviceId, normalizeInstanceId } from './config.js';
 import { CryptoProvider } from './crypto.js';
 import { GatewayDiscovery } from './discovery.js';
 import { E2EEManager } from './e2ee.js';
-import { GroupE2EEManager, computeMembershipCommitment, storeGroupSecret, buildKeyDistribution, buildKeyRequest, buildMembershipManifest, signMembershipManifest, } from './e2ee-group.js';
+import { GroupE2EEManager, computeMembershipCommitment, computeStateHash, storeGroupSecret, storeGroupSecretEpoch, buildKeyDistribution, buildKeyRequest, buildMembershipManifest, signMembershipManifest, verifyEpochChain, } from './e2ee-group.js';
 import { AUNError, AuthError, ConnectionError, E2EEError, PermissionError, StateError, TimeoutError, ValidationError, } from './errors.js';
 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)
@@ -83,7 +72,7 @@ const INTERNAL_ONLY_METHODS = new Set([
 const DEFAULT_SESSION_OPTIONS = {
     auto_reconnect: true,
     heartbeat_interval: 30.0,
-    token_refresh_before: 60.0,
+    token_refresh_before: 1800.0,
     retry: {
         initial_delay: 1.0,
         max_delay: 64.0,
@@ -98,6 +87,7 @@ const DEFAULT_SESSION_OPTIONS = {
 };
 const RECONNECT_MIN_BASE_DELAY_MS = 1_000;
 const RECONNECT_MAX_BASE_DELAY_MS = 64_000;
+const TOKEN_REFRESH_CHECK_INTERVAL_MS = 30_000;
 const GROUP_ROTATION_LEASE_MS = 120_000;
 const GROUP_ROTATION_RETRY_MAX_DELAY_MS = 300_000;
 const PENDING_DECRYPT_LIMIT = 100;
@@ -139,9 +129,15 @@ const SIGNED_METHODS = new Set([
     'group.resources.delete', 'group.resources.request_add',
     'group.resources.direct_add', 'group.resources.approve_request',
     'group.resources.reject_request',
+    'group.commit_state',
+    'group.e2ee.begin_rotation', 'group.e2ee.commit_rotation',
+    'group.e2ee.abort_rotation',
+    'group.ban', 'group.unban',
+    'group.dissolve', 'group.suspend', 'group.resume',
 ]);
-/** peer 证书缓存 TTL（10 分钟） */
-const PEER_CERT_CACHE_TTL = 600;
+/** peer 证书缓存 TTL（1 小时） */
+const PEER_CERT_CACHE_TTL = 3600;
+const PEER_PREKEYS_CACHE_TTL = 3600;
 const PREKEY_FALLBACK_DEVICE_ID = 'aun_device_id';
 function isGroupServiceAid(value) {
     const text = String(value ?? '').trim();
@@ -213,6 +209,19 @@ function normalizePeerPrekeys(prekeys) {
     }
     return filtered;
 }
+/** 判断加密失败是否由过期的对端证书或 prekey 引起，可通过刷新缓存重试 */
+function isRetryablePeerMaterialError(error) {
+    const localCode = String(error?.localCode ?? error?.code ?? '').trim();
+    if (localCode === 'PEER_CERT_FINGERPRINT_MISMATCH'
+        || localCode === 'PREKEY_CERT_FINGERPRINT_MISMATCH'
+        || localCode === 'PREKEY_SIGNATURE_VERIFY_FAILED') {
+        return true;
+    }
+    const message = error instanceof Error ? error.message : String(error ?? '');
+    return message.includes('peer cert fingerprint mismatch for ')
+        || message.includes('prekey cert fingerprint mismatch')
+        || message.includes('prekey 签名验证失败');
+}
 function formatCaughtError(error) {
     return error instanceof Error ? error : String(error);
 }
@@ -352,6 +361,8 @@ export class AUNClient {
     _groupEpochRotationInflight = new Set();
     _groupEpochRecoveryInflight = new Map();
     _groupMembershipRotationDone = new Set();
+    /** 群密钥 backfill 去重：已完成/进行中的 key 集合，防止重复分发 */
+    _groupMemberKeyBackfillDone = new Set();
     _groupEpochRotationRetryTimers = new Map();
     // ── 后台任务定时器 ──────────────────────────────────────────
     _heartbeatTimer = null;
@@ -364,6 +375,8 @@ export class AUNClient {
     _reconnectActive = false;
     _reconnectAbort = null;
     _serverKicked = false;
+    _logger;
+    _clientLog;
     constructor(config, debug = false) {
         const rawConfig = { ...(config ?? {}) };
         this._configModel = configFromMap(rawConfig);
@@ -372,20 +385,27 @@ export class AUNClient {
             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 初始化完成 (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 };
@@ -397,24 +417,28 @@ export class AUNClient {
             slotId: this._slotId,
             rootCaPath: this._configModel.rootCaPath ?? undefined,
             verifySsl: this._configModel.verifySsl,
+            logger: this._logger.for('aun_core.auth'),
         });
         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);
@@ -425,6 +449,8 @@ export class AUNClient {
         this._dispatcher.subscribe('_raw.group.message_created', (data) => this._onRawGroupMessageCreated(data));
         // 群组变更事件：拦截处理成员变更触发的 epoch 轮换，然后透传
         this._dispatcher.subscribe('_raw.group.changed', (data) => this._onRawGroupChanged(data));
+        // 群组状态提交事件：验证 state_hash 链并更新本地存储
+        this._dispatcher.subscribe('_raw.group.state_committed', (data) => this._onGroupStateCommitted(data));
         // 其他事件直接透传
         for (const evt of ['message.recalled', 'message.ack', 'storage.object_changed']) {
             this._dispatcher.subscribe(`_raw.${evt}`, (data) => this._dispatcher.publish(evt, data));
@@ -468,6 +494,7 @@ export class AUNClient {
         if (this._state !== 'idle' && this._state !== 'closed' && this._state !== 'disconnected') {
             throw new StateError(`connect not allowed in state ${this._state}`);
         }
+        this._state = 'connecting';
         const params = { ...auth };
         if (options)
             Object.assign(params, options);
@@ -477,7 +504,16 @@ export class AUNClient {
         const callTimeoutSec = this._sessionOptions.timeouts.call;
         this._transport.setTimeout(callTimeoutSec != null ? callTimeoutSec * 1000 : 10_000);
         this._closing = false;
-        await this._connectOnce(normalized, false);
+        try {
+            await this._connectOnce(normalized, false);
+        }
+        catch (err) {
+            // 连接失败时回退状态，允许重试
+            if (this._state === 'connecting' || this._state === 'authenticating') {
+                this._state = 'disconnected';
+            }
+            throw err;
+        }
     }
     /** 关闭连接 */
     async close() {
@@ -489,6 +525,7 @@ export class AUNClient {
             const closableKeyStore = this._keystore;
             closableKeyStore.close?.();
             this._state = 'closed';
+            this._logger.close();
             this._resetSeqTrackingState();
             return;
         }
@@ -496,6 +533,7 @@ export class AUNClient {
         const closableKeyStore = this._keystore;
         closableKeyStore.close?.();
         this._state = 'closed';
+        this._logger.close();
         await this._dispatcher.publish('connection.state', { state: this._state });
         this._resetSeqTrackingState();
     }
@@ -555,6 +593,11 @@ export class AUNClient {
         const p = { ...(params ?? {}) };
         this._validateOutboundCall(method, p);
         this._injectMessageCursorContext(method, p);
+        // group.* 方法的 group_id 归一化为 canonical 格式（兼容老/污染数据）
+        // 不对无域输入补本域——保持与历史行为兼容，交给服务端归一化
+        if (method.startsWith('group.') && p.group_id !== undefined && p.group_id !== null && p.group_id !== '') {
+            p.group_id = normalizeGroupId(p.group_id);
+        }
         // group.* 方法注入 device_id（服务端用于多设备消息路由）
         if (method.startsWith('group.') && this._deviceId && p.device_id === undefined) {
             p.device_id = this._deviceId;
@@ -569,8 +612,7 @@ export class AUNClient {
             if (encrypt) {
                 return await this._sendEncrypted(p);
             }
-            delete p.protected_headers;
-            delete p.headers;
+            // encrypt=false：明文走通用 RPC 路径；protected_headers/headers 是信封元数据，加密与否都保留
         }
         // 自动加密：group.send 默认加密（encrypt 默认 True）
         if (method === 'group.send') {
@@ -579,24 +621,20 @@ export class AUNClient {
             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 (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');
+            if (encrypt) {
+                return await this._putMessageThoughtEncrypted(p);
             }
-            return await this._putMessageThoughtEncrypted(p);
         }
         // 关键操作自动附加客户端签名
         if (SIGNED_METHODS.has(method)) {
@@ -628,7 +666,7 @@ export class AUNClient {
                 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._clientLog.info(`message.pull retention-floor 推进: ns=${ns} contiguous=${contig} -> server_ack_seq=${serverAck}`);
                         this._seqTracker.forceContiguousSeq(ns, serverAck);
                     }
                 }
@@ -640,7 +678,7 @@ export class AUNClient {
                         seq: contig,
                         device_id: this._deviceId,
                         slot_id: this._slotId,
-                    }).catch((e) => { _clientLog('debug', 'message.pull auto-ack 失败: %s', formatCaughtError(e)); });
+                    }).catch((e) => { this._clientLog.debug(`message.pull auto-ack 失败: ${formatCaughtError(e)}`); });
                 }
             }
         }
@@ -667,7 +705,7 @@ export class AUNClient {
                     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(`group.pull retention-floor 推进: ns=${ns} contiguous=${contig} -> cursor.current_seq=${serverAck}`);
                             this._seqTracker.forceContiguousSeq(ns, serverAck);
                         }
                     }
@@ -682,7 +720,7 @@ export class AUNClient {
                         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)); });
+                    }).catch((e) => { this._clientLog.debug(`group.pull auto-ack 失败: group=${gid} ${formatCaughtError(e)}`); });
                 }
             }
         }
@@ -722,10 +760,13 @@ export class AUNClient {
             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);
+                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)));
+                await Promise.race([rotationPromise, timeoutPromise]).catch((exc) => this._clientLog.warn(`membership RPC epoch rotation fallback failed: ${formatCaughtError(exc)}`));
             }
         }
         return result;
@@ -780,50 +821,73 @@ export class AUNClient {
         if (!this._p2pSynced) {
             await this._lazySyncP2p();
         }
-        const recipientPrekeys = await this._fetchPeerPrekeys(toAid);
-        const selfSyncCopies = await this._buildSelfSyncCopies({
-            logicalToAid: toAid,
-            payload,
-            messageId,
-            timestamp,
-            protectedHeaders,
-        });
-        if (recipientPrekeys.length <= 1 && selfSyncCopies.length === 0) {
-            return await this._sendEncryptedSingle({
+        // 内部发送逻辑，refreshPeerMaterial=true 时强制清缓存重新拉取对端材料
+        const sendAttempt = async (refreshPeerMaterial = false) => {
+            const recipientPrekeys = refreshPeerMaterial
+                ? await this._refreshPeerPrekeys(toAid)
+                : await this._fetchPeerPrekeys(toAid);
+            const selfSyncCopies = await this._buildSelfSyncCopies({
+                logicalToAid: toAid,
+                payload,
+                messageId,
+                timestamp,
+                protectedHeaders,
+            });
+            // 多设备过滤：只保留有有效 device_id 的可路由 prekey，
+            // 占位符 PREKEY_FALLBACK_DEVICE_ID 表示服务端未分配真实设备 ID，不可用于多设备路由
+            const routablePrekeys = recipientPrekeys.filter(pk => {
+                const did = String(pk.device_id ?? '').trim();
+                return did && did !== PREKEY_FALLBACK_DEVICE_ID;
+            });
+            const canUseMultiDevice = routablePrekeys.length > 0
+                && (routablePrekeys.length > 1 || selfSyncCopies.length > 0);
+            if (!canUseMultiDevice) {
+                return await this._sendEncryptedSingle({
+                    toAid,
+                    payload,
+                    messageId,
+                    timestamp,
+                    prekey: routablePrekeys[0] ?? recipientPrekeys[0],
+                    persistRequired,
+                    protectedHeaders,
+                });
+            }
+            const recipientCopies = await this._buildRecipientDeviceCopies({
                 toAid,
                 payload,
                 messageId,
                 timestamp,
-                prekey: recipientPrekeys[0],
-                persistRequired,
+                prekeys: routablePrekeys,
                 protectedHeaders,
             });
-        }
-        const recipientCopies = await this._buildRecipientDeviceCopies({
-            toAid,
-            payload,
-            messageId,
-            timestamp,
-            prekeys: recipientPrekeys,
-            protectedHeaders,
-        });
-        const sendParams = {
-            to: toAid,
-            payload: {
+            const sendParams = {
+                to: toAid,
+                payload: {
+                    type: 'e2ee.multi_device',
+                    logical_message_id: messageId,
+                    recipient_copies: recipientCopies,
+                    self_copies: selfSyncCopies,
+                },
                 type: 'e2ee.multi_device',
-                logical_message_id: messageId,
-                recipient_copies: recipientCopies,
-                self_copies: selfSyncCopies,
-            },
-            type: 'e2ee.multi_device',
-            encrypted: true,
-            message_id: messageId,
-            timestamp,
+                encrypted: true,
+                message_id: messageId,
+                timestamp,
+            };
+            if (persistRequired) {
+                sendParams.persist_required = true;
+            }
+            return await this._transport.call('message.send', sendParams);
         };
-        if (persistRequired) {
-            sendParams.persist_required = true;
+        // 首次尝试（使用缓存）；若对端证书/prekey 过期导致指纹不匹配，清缓存后重试一次
+        try {
+            return await sendAttempt(false);
         }
-        return await this._transport.call('message.send', sendParams);
+        catch (exc) {
+            if (!isRetryablePeerMaterialError(exc))
+                throw exc;
+            this._clientLog.warn(`peer cert/prekey mismatch for ${toAid}, refreshing and retrying once`);
+        }
+        return await sendAttempt(true);
     }
     async _sendEncryptedSingle(opts) {
         let prekey = opts.prekey ?? null;
@@ -927,7 +991,15 @@ export class AUNClient {
             if (deviceId === this._deviceId) {
                 continue;
             }
-            const peerCertPem = await this._resolveSelfCopyPeerCert(String(prekey.cert_fingerprint ?? '').trim().toLowerCase() || undefined);
+            let peerCertPem;
+            try {
+                peerCertPem = await this._resolveSelfCopyPeerCert(String(prekey.cert_fingerprint ?? '').trim().toLowerCase() || undefined);
+            }
+            catch (e) {
+                // 旧设备的 prekey 可能携带已轮换的证书指纹，跳过该设备的自同步副本
+                this._clientLog.warn(`self-sync 跳过设备 ${deviceId}: 证书解析失败 (${e})，可能是旧 prekey`);
+                continue;
+            }
             const [envelope, encryptResult] = this._encryptCopyPayload({
                 logicalToAid: opts.logicalToAid,
                 payload: opts.payload,
@@ -963,7 +1035,7 @@ export class AUNClient {
                 mode: encryptResult.mode,
                 reason: encryptResult.degradation_reason,
             }).catch((exc) => {
-                _clientLog('warn', '发布 e2ee.degraded 事件失败: %s', formatCaughtError(exc));
+                this._clientLog.warn(`发布 e2ee.degraded 事件失败: ${formatCaughtError(exc)}`);
             });
         }
     }
@@ -1028,7 +1100,7 @@ export class AUNClient {
             }
             catch (exc) {
                 if (attempt === 0 && this._isRecoverableGroupEpochError(exc)) {
-                    _clientLog('warn', '群 %s 调用 %s 时 epoch 已过旧，恢复密钥后重加密重试一次: %s', groupId, method, formatCaughtError(exc));
+                    this._clientLog.warn(`群 ${groupId} 调用 ${method} 时 epoch 已过旧，恢复密钥后重加密重试一次: ${formatCaughtError(exc)}`);
                     ({ sendParams, groupId } = await this._prepareGroupEncryptedRpcParams(method, params, options, true));
                     continue;
                 }
@@ -1114,11 +1186,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(`惰性同步群 ${groupId}: pull ${messages.length} 条消息, after_seq=${afterSeq}`);
             }
         }
         catch (exc) {
-            _clientLog('warn', '惰性同步群 %s 失败: %s', groupId, formatCaughtError(exc));
+            this._clientLog.warn(`惰性同步群 ${groupId} 失败: ${formatCaughtError(exc)}`);
         }
     }
     /** 惰性同步：首次激活 P2P 通道时 pull 最近消息，建立 seq 基线 */
@@ -1141,11 +1213,11 @@ export class AUNClient {
             }
             if (messages.length > 0) {
                 this._saveSeqTrackerState();
-                _clientLog('info', '惰性同步 P2P: pull %d 条消息, after_seq=%d', messages.length, afterSeq);
+                this._clientLog.info(`惰性同步 P2P: pull ${messages.length} 条消息, after_seq=${afterSeq}`);
             }
         }
         catch (exc) {
-            _clientLog('warn', '惰性同步 P2P 失败: %s', formatCaughtError(exc));
+            this._clientLog.warn(`惰性同步 P2P 失败: ${formatCaughtError(exc)}`);
         }
     }
     _isGroupEpochTooOldError(exc) {
@@ -1201,10 +1273,10 @@ export class AUNClient {
                 encrypt: true,
                 persist_required: true,
             });
-            _clientLog('info', '已向 %s 请求群 %s 的 epoch %s 密钥', targetAid, groupId, epoch);
+            this._clientLog.info(`已向 ${targetAid} 请求群 ${groupId} 的 epoch ${epoch} 密钥`);
         }
         catch (exc) {
-            _clientLog('warn', '向 %s 请求群 %s 密钥失败: %s', targetAid, groupId, formatCaughtError(exc));
+            this._clientLog.warn(`向 ${targetAid} 请求群 ${groupId} 密钥失败: ${formatCaughtError(exc)}`);
         }
     }
     async _requestGroupKeyFromCandidates(groupId, serverEpoch, epochResult) {
@@ -1219,7 +1291,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(`群 ${groupId} 检测到本地 epoch 1 已存在但服务端 epoch 仍为 0，尝试补同步初始 epoch`);
         await this._syncEpochToServer(groupId);
         try {
             const refreshed = await this.call('group.e2ee.get_epoch', { group_id: groupId });
@@ -1227,7 +1299,7 @@ export class AUNClient {
                 return refreshed;
         }
         catch (exc) {
-            _clientLog('warn', '群 %s 初始 epoch 补同步后刷新服务端 epoch 失败: %s', groupId, formatCaughtError(exc));
+            this._clientLog.warn(`群 ${groupId} 初始 epoch 补同步后刷新服务端 epoch 失败: ${formatCaughtError(exc)}`);
         }
         return epochResult;
     }
@@ -1244,10 +1316,10 @@ 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.epoch ?? 0);
+        let serverEpoch = Number(epochResult.committed_epoch ?? epochResult.epoch ?? 0);
         if (!Number.isFinite(serverEpoch))
             return;
         const pending = isJsonObject(epochResult.pending_rotation) ? epochResult.pending_rotation : null;
@@ -1263,7 +1335,7 @@ export class AUNClient {
         let effectiveLocalEpoch = initialLocalEpoch;
         if (serverEpoch === 0 && effectiveLocalEpoch === 1) {
             epochResult = await this._recoverInitialGroupEpochIfNeeded(groupId, effectiveLocalEpoch, epochResult);
-            serverEpoch = Number(epochResult.epoch ?? 0);
+            serverEpoch = Number(epochResult.committed_epoch ?? epochResult.epoch ?? 0);
             if (serverEpoch === 0) {
                 throw new StateError(`group ${groupId} initial epoch sync has not completed; refuse to send with local epoch 1 while server epoch is 0`);
             }
@@ -1275,7 +1347,9 @@ export class AUNClient {
             while (Date.now() < waitDeadline) {
                 await new Promise(resolve => setTimeout(resolve, 150));
                 const refreshed = await this.call('group.e2ee.get_epoch', { group_id: groupId });
-                const refreshedEpoch = isJsonObject(refreshed) ? Number(refreshed.epoch ?? 0) : 0;
+                const refreshedEpoch = isJsonObject(refreshed)
+                    ? Number(refreshed.committed_epoch ?? refreshed.epoch ?? 0)
+                    : 0;
                 const currentLocal = await this._groupE2ee.currentEpoch(groupId);
                 if (Number.isFinite(refreshedEpoch) && refreshedEpoch > serverEpoch) {
                     epochResult = refreshed;
@@ -1290,8 +1364,8 @@ 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);
-        await this._requestGroupKeyFromCandidates(groupId, serverEpoch, epochResult);
+        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) {
             await new Promise(resolve => setTimeout(resolve, 150));
@@ -1314,7 +1388,7 @@ export class AUNClient {
                 members = isJsonObject(membersResult) ? membersResult.members : null;
             }
             catch (exc) {
-                _clientLog('debug', '群 %s 成员 epoch floor 预检跳过: %s', groupId, formatCaughtError(exc));
+                this._clientLog.debug(`群 ${groupId} 成员 epoch floor 预检跳过: ${formatCaughtError(exc)}`);
                 return;
             }
             let maxMinReadEpoch = 0;
@@ -1329,7 +1403,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(`群 ${groupId} 成员 min_read_epoch 高于 committed epoch，按 committed epoch 继续发送: committed=${committedEpoch} floor=${maxMinReadEpoch}`);
             return;
         }
     }
@@ -1340,7 +1414,7 @@ export class AUNClient {
                 return epochResult;
         }
         catch (exc) {
-            _clientLog('warn', '群 %s 查询 committed epoch 状态失败，回退本地 epoch: %s', groupId, formatCaughtError(exc));
+            this._clientLog.warn(`群 ${groupId} 查询 committed epoch 状态失败，回退本地 epoch: ${formatCaughtError(exc)}`);
         }
         const localEpoch = await this._groupE2ee.currentEpoch(groupId);
         return { epoch: localEpoch ?? 0, committed_epoch: localEpoch ?? 0 };
@@ -1364,13 +1438,28 @@ export class AUNClient {
     async _ensureCommittedGroupSecretForSend(groupId, committedEpoch, epochResult) {
         if (committedEpoch <= 0)
             return committedEpoch;
-        const secretData = await this._groupE2ee.loadSecret(groupId, committedEpoch);
-        const committedRotation = isJsonObject(epochResult.committed_rotation) ? epochResult.committed_rotation : null;
+        let secretData = await this._groupE2ee.loadSecret(groupId, committedEpoch);
+        let committedRotation = isJsonObject(epochResult.committed_rotation) ? epochResult.committed_rotation : null;
+        if (await this._committedRotationMembershipGap(groupId, committedEpoch, committedRotation)) {
+            const allowMember = await this._groupAllowsMemberEpochRotation(groupId);
+            this._clientLog.warn(`群 ${groupId} committed epoch ${committedEpoch} 的成员快照与当前成员不一致，触发成员变更轮换修复`);
+            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);
+            if (Number.isFinite(refreshedCommittedEpoch) && refreshedCommittedEpoch > committedEpoch) {
+                committedEpoch = refreshedCommittedEpoch;
+                committedRotation = isJsonObject(refreshed.committed_rotation) ? refreshed.committed_rotation : null;
+                secretData = await this._groupE2ee.loadSecret(groupId, committedEpoch);
+            }
+            if (await this._committedRotationMembershipGap(groupId, committedEpoch, committedRotation)) {
+                throw new StateError(`group ${groupId} committed membership is stale at epoch ${committedEpoch}; key rotation repair has not completed`);
+            }
+        }
         if (this._groupSecretMatchesCommittedRotation(secretData, committedRotation)) {
             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(`群 ${groupId} epoch ${committedEpoch} 本地 pending key 未匹配服务端 committed rotation，先恢复密钥: local_rotation=${pendingRotationId || '-'}`);
         await this._recoverGroupEpochKey(groupId, committedEpoch, '', 5000);
         let refreshed = await this._committedGroupEpochState(groupId);
         const refreshedCommittedEpoch = Number(refreshed.committed_epoch ?? refreshed.epoch ?? committedEpoch);
@@ -1386,6 +1475,45 @@ export class AUNClient {
         }
         return committedEpoch;
     }
+    async _committedRotationMembershipGap(groupId, committedEpoch, committedRotation) {
+        if (!this._aid || committedEpoch <= 0 || !committedRotation)
+            return false;
+        const expectedMembers = Array.isArray(committedRotation.expected_members)
+            ? committedRotation.expected_members.map((item) => String(item ?? '').trim()).filter(Boolean).sort()
+            : [];
+        if (expectedMembers.length === 0)
+            return false;
+        try {
+            const membersResult = await this.call('group.get_members', { group_id: groupId });
+            const rawMembers = isJsonObject(membersResult)
+                ? (Array.isArray(membersResult.members) ? membersResult.members : membersResult.items)
+                : [];
+            if (!Array.isArray(rawMembers))
+                return false;
+            const activeMembers = rawMembers
+                .filter((item) => isJsonObject(item))
+                .map((item) => ({
+                aid: String(item.aid ?? '').trim(),
+                status: String(item.status ?? 'active').trim().toLowerCase(),
+            }))
+                .filter((item) => item.aid && ['', 'active'].includes(item.status))
+                .map((item) => item.aid)
+                .sort();
+            if (!activeMembers.includes(this._aid) || activeMembers.length === 0)
+                return false;
+            if (activeMembers.join('\n') !== expectedMembers.join('\n')) {
+                const missing = activeMembers.filter((aid) => !expectedMembers.includes(aid));
+                const extra = expectedMembers.filter((aid) => !activeMembers.includes(aid));
+                this._clientLog.info(`群 ${groupId} committed membership gap: epoch=${committedEpoch} missing=${JSON.stringify(missing)} extra=${JSON.stringify(extra)}`);
+                return true;
+            }
+            return false;
+        }
+        catch (exc) {
+            this._clientLog.debug(`查询当前成员失败，无法判断 committed membership gap: group=${groupId} err=${formatCaughtError(exc)}`);
+            return false;
+        }
+    }
     // ── 客户端签名 ────────────────────────────────────────────
     /**
      * 为关键操作附加客户端 ECDSA 签名（client_signature 字段）。
@@ -1434,7 +1562,7 @@ export class AUNClient {
     async _onRawMessageReceived(data) {
         // 异步处理，不阻塞事件调度
         this._processAndPublishMessage(data).catch((exc) => {
-            _clientLog('warn', 'P2P 消息解密失败: %s', formatCaughtError(exc));
+            this._clientLog.warn(`P2P 消息解密失败: ${formatCaughtError(exc)}`);
             // H26: 不再投递原始密文 payload；改发 message.undecryptable 事件，仅携带安全 header
             if (isJsonObject(data)) {
                 const safeEvent = {
@@ -1470,7 +1598,7 @@ 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._fillP2pGap().catch(exc => this._clientLog.warn(`后台补洞触发失败: ${formatCaughtError(exc)}`));
             }
             // auto-ack contiguous_seq
             const contig = this._seqTracker.getContiguousSeq(ns);
@@ -1479,7 +1607,7 @@ 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 失败: ${formatCaughtError(e)}`); });
             }
             // 即时持久化 cursor，异常断连后不回退
             this._saveSeqTrackerState();
@@ -1496,7 +1624,7 @@ export class AUNClient {
     /** 处理群组消息推送：自动解密后 re-publish */
     async _onRawGroupMessageCreated(data) {
         this._processAndPublishGroupMessage(data).catch((exc) => {
-            _clientLog('warn', '群消息解密失败: %s', formatCaughtError(exc));
+            this._clientLog.warn(`群消息解密失败: ${formatCaughtError(exc)}`);
             // H26: 不再投递原始密文 payload；改发 group.message_undecryptable 事件
             if (isJsonObject(data)) {
                 const safeEvent = {
@@ -1541,7 +1669,7 @@ export class AUNClient {
             const ns = `group:${groupId}`;
             const needPull = this._seqTracker.onMessageSeq(ns, seq);
             if (needPull) {
-                this._fillGroupGap(groupId).catch(exc => _clientLog('warn', '后台补洞触发失败: %s', formatCaughtError(exc)));
+                this._fillGroupGap(groupId).catch(exc => this._clientLog.warn(`后台补洞触发失败: ${formatCaughtError(exc)}`));
             }
             const contig = this._seqTracker.getContiguousSeq(ns);
             if (contig > 0) {
@@ -1550,7 +1678,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(`群消息 auto-ack 失败: group=${groupId} ${formatCaughtError(e)}`); });
             }
             this._saveSeqTrackerState();
         }
@@ -1618,7 +1746,7 @@ export class AUNClient {
             }
         }
         catch (exc) {
-            _clientLog('debug', '自动 pull 群消息失败: %s', formatCaughtError(exc));
+            this._clientLog.debug(`自动 pull 群消息失败: ${formatCaughtError(exc)}`);
         }
         await this._publishAppEvent('group.message_created', notification);
     }
@@ -1661,7 +1789,7 @@ export class AUNClient {
             }
         }
         catch (exc) {
-            _clientLog('warn', '群消息补洞失败: %s', formatCaughtError(exc));
+            this._clientLog.warn(`群消息补洞失败: ${formatCaughtError(exc)}`);
         }
         finally {
             this._gapFillDone.delete(dedupKey);
@@ -1706,7 +1834,7 @@ export class AUNClient {
             }
         }
         catch (exc) {
-            _clientLog('warn', 'P2P 消息补洞失败: %s', formatCaughtError(exc));
+            this._clientLog.warn(`P2P 消息补洞失败: ${formatCaughtError(exc)}`);
         }
         finally {
             this._gapFillDone.delete(dedupKey);
@@ -1863,7 +1991,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 推进: ns=${ns} contiguous=${contigBefore} -> cursor.current_seq=${serverAck}`);
                             this._seqTracker.forceContiguousSeq(ns, serverAck);
                         }
                     }
@@ -1876,7 +2004,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(`群事件 auto-ack 失败: group=${groupId} ${formatCaughtError(e)}`); });
                     }
                     for (const evt of events) {
                         if (isJsonObject(evt)) {
@@ -1885,6 +2013,11 @@ export class AUNClient {
                             // 消息事件由 _fillGroupGap 负责，事件补洞不重复投递
                             if (et === 'group.message_created')
                                 continue;
+                            // 验签：有 client_signature 就验（与实时事件路径对齐）
+                            const cs = evt.client_signature;
+                            if (cs && typeof cs === 'object') {
+                                evt._verified = await this._verifyEventSignatureAsync(evt, cs);
+                            }
                             // group.changed 或缺失/其他 → 发布到 group.changed（向后兼容）
                             await this._dispatcher.publish('group.changed', evt);
                         }
@@ -1893,43 +2026,12 @@ export class AUNClient {
             }
         }
         catch (exc) {
-            _clientLog('warn', '群事件补洞失败: %s', formatCaughtError(exc));
+            this._clientLog.warn(`群事件补洞失败: ${formatCaughtError(exc)}`);
         }
         finally {
             this._gapFillDone.delete(dedupKey);
         }
     }
-    /**
-     * 上线/重连后一次性同步所有已加入群：
-     * 1. 有 epoch key 的群 → 补消息 + 补事件
-     * 2. 无 epoch key 的群 → 仅补事件（事件不加密，等推送触发密钥恢复）
-     */
-    async _syncAllGroupsOnce() {
-        try {
-            const result = await this.call('group.list_my', {});
-            if (!isJsonObject(result))
-                return;
-            const items = result.items;
-            if (!Array.isArray(items))
-                return;
-            for (const g of items) {
-                if (isJsonObject(g)) {
-                    const gid = String(g.group_id ?? '');
-                    if (gid) {
-                        // 有 epoch key → 补消息
-                        if (this._groupE2ee.hasSecret(gid)) {
-                            await this._fillGroupGap(gid);
-                        }
-                        // 所有群都补事件（事件不加密）
-                        await this._fillGroupEventGap(gid);
-                    }
-                }
-            }
-        }
-        catch (exc) {
-            _clientLog('debug', '批量同步群失败: %s', formatCaughtError(exc));
-        }
-    }
     /**
      * 处理群组变更事件：透传给用户，并在成员离开/被踢时自动触发 epoch 轮换。
      * 按协议，轮换由剩余在线 admin/owner 负责。
@@ -2081,12 +2183,12 @@ 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(`群事件推送 auto-ack 失败: group=${groupId} ${formatCaughtError(e)}`); });
                 }
             }
             // 仅在真实 event gap 时才触发补拉（补洞回来的事件不再触发新补洞）
             if (needPull && groupId && !d._from_gap_fill) {
-                this._fillGroupEventGap(groupId).catch(exc => _clientLog('warn', '后台补洞触发失败: %s', formatCaughtError(exc)));
+                this._fillGroupEventGap(groupId).catch(exc => this._clientLog.warn(`后台补洞触发失败: ${formatCaughtError(exc)}`));
             }
             // 成员退出或被踢 → 剩余 admin/owner 自动补位轮换
             // H21: 避免 epoch 轮换风暴——所有剩余 admin 同时收到事件不能都发起轮换，
@@ -2097,7 +2199,7 @@ export class AUNClient {
                     {
                         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 ?? ''));
+                            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 ?? '')}`);
                         }
                         else {
                             this._maybeLeadRotateGroupEpoch(groupId, this._membershipRotationTriggerId(groupId, d), expectedEpoch).catch((exc) => this._logE2eeError('rotate_epoch', groupId, '', exc));
@@ -2105,15 +2207,38 @@ export class AUNClient {
                     }
                 }
             }
+            // 成员加入：按 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);
-                        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 ?? ''));
+                        const joinedAids = this._joinedMemberAidsFromPayload(d);
+                        const isSelfJoining = joinedAids.includes(this._aid ?? '') && (action === 'joined' || action === 'invite_code_used');
+                        this._clientLog.warn(`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);
+                            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));
+                            }
                         }
                     }
                 }
@@ -2130,11 +2255,94 @@ export class AUNClient {
             await this._dispatcher.publish('group.changed', data);
         }
     }
+    /**
+     * 处理 event/group.state_committed：验证 state_hash 链并更新本地存储。
+     * 当链断裂时回源 group.get_state，并对回源结果做本地 hash 重算验证。
+     */
+    async _onGroupStateCommitted(data) {
+        if (!isJsonObject(data))
+            return;
+        const d = data;
+        const groupId = String(d.group_id ?? '').trim();
+        if (!groupId)
+            return;
+        // 提交者签名验证（兼容旧版：无签名时继续）
+        const cs = d.client_signature;
+        if (cs && isJsonObject(cs)) {
+            const verified = await this._verifyEventSignatureAsync(d, cs);
+            if (verified === false) {
+                this._clientLog.warn(`state_committed 提交者签名验证失败 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 链不连续 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(`回源 state_hash 验证失败 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);
+                    }
+                }
+            }
+            catch (exc) {
+                this._clientLog.warn(`state 回源失败 group=${groupId}: ${formatCaughtError(exc)}`);
+            }
+            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) {
+            this._clientLog.warn(`state_hash 重算不匹配 group=${groupId} sv=${stateVersion} expected=${stateHash} got=${computed}`);
+            return;
+        }
+        // 3. 更新本地存储
+        const saveFn = this._keystore.saveGroupState;
+        if (saveFn) {
+            saveFn.call(this._keystore, groupId, stateVersion, stateHash, keyEpoch, membershipSnapshot, policySnapshot);
+        }
+    }
     /**
      * 成员退出/被踢后，判断本地是否为 leader admin 并发起 epoch 轮换。
      * 避免所有剩余 admin 同时触发 `_rotateGroupEpoch` 造成 CAS 风暴。
      */
-    async _maybeLeadRotateGroupEpoch(groupId, triggerId = '', expectedEpoch = null) {
+    async _maybeLeadRotateGroupEpoch(groupId, triggerId = '', expectedEpoch = null, allowMember = false) {
         const myAid = this._aid;
         if (!myAid || this._closing || this._state !== 'connected')
             return;
@@ -2145,7 +2353,7 @@ export class AUNClient {
             if (this._closing || this._state !== 'connected')
                 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 || '-'})`);
                 return;
             }
             await new Promise((resolve) => setTimeout(resolve, 200));
@@ -2163,24 +2371,46 @@ export class AUNClient {
             if (!Array.isArray(rawList))
                 return;
             const admins = [];
+            const members = [];
             for (const m of rawList) {
                 if (!isJsonObject(m))
                     continue;
                 const role = String(m.role ?? '');
                 const aid = String(m.aid ?? '');
-                if (aid && (role === 'admin' || role === 'owner'))
+                if (!aid)
+                    continue;
+                if (role === 'admin' || role === 'owner') {
                     admins.push(aid);
+                }
+                else if (allowMember && role === 'member') {
+                    members.push(aid);
+                }
             }
-            if (admins.length === 0)
+            // 候选列表：admin/owner 排序在前，member 排序在后
+            let candidates = [...admins.sort(), ...members.sort()];
+            if (candidates.length === 0)
                 return;
-            admins.sort();
-            const leader = admins[0];
+            // 没有当前 epoch key 的成员不参与 leader 选举。
+            // open/invite_code 群排除后为空时保留自己兜底（从服务端取 prev chain）。
+            if (expectedEpoch !== null && expectedEpoch > 0) {
+                const localSecret = this._groupE2ee.loadSecret(groupId, expectedEpoch);
+                if (!localSecret) {
+                    const filtered = candidates.filter(c => c !== myAid);
+                    if (filtered.length > 0) {
+                        candidates = filtered;
+                    }
+                    else if (!allowMember) {
+                        return;
+                    }
+                }
+            }
+            const leader = candidates[0];
             if (leader === myAid) {
                 // 我是 leader，直接发起
                 await this._rotateGroupEpoch(groupId, triggerId, expectedEpoch);
                 return;
             }
-            if (!admins.includes(myAid))
+            if (!candidates.includes(myAid))
                 return;
             // 非 leader：随机 jitter（2~6s）后查询服务端 epoch 是否已被 leader 推进
             const jitterMs = 2000 + Math.floor(Math.random() * 4000);
@@ -2218,11 +2448,11 @@ export class AUNClient {
                 });
                 return;
             }
-            _clientLog('info', '[H21] leader 未完成 epoch 轮换，非 leader 兜底: group=%s myAid=%s', groupId, myAid);
+            this._clientLog.info(`[H21] leader 未完成 epoch 轮换，非 leader 兜底: group=${groupId} myAid=${myAid}`);
             await this._rotateGroupEpoch(groupId, triggerId, expectedEpoch);
         }
         catch (exc) {
-            _clientLog('warn', '_maybeLeadRotateGroupEpoch 失败: %s', formatCaughtError(exc));
+            this._clientLog.warn(`_maybeLeadRotateGroupEpoch 失败: ${formatCaughtError(exc)}`);
         }
         finally {
             this._groupEpochRotationInflight.delete(groupId);
@@ -2240,7 +2470,7 @@ export class AUNClient {
             this._groupE2ee.removeGroup(groupId);
         }
         catch (exc) {
-            _clientLog('warn', '清理解散群组 %s epoch 密钥失败: %s', groupId, formatCaughtError(exc));
+            this._clientLog.warn(`清理解散群组 ${groupId} epoch 密钥失败: ${formatCaughtError(exc)}`);
         }
         // 2. 清理 seq_tracker 中的群消息和群事件命名空间
         this._seqTracker.removeNamespace(`group:${groupId}`);
@@ -2257,7 +2487,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(`已清理解散群组 ${groupId} 的本地状态`);
     }
     /** 同步验签群事件 client_signature。返回 true/false/"pending"。 */
     /**
@@ -2292,7 +2522,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(`验签失败：证书指纹不匹配 aid=${sigAid}`);
                     return false;
                 }
             }
@@ -2303,7 +2533,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(`群事件验签失败 aid=${sigAid} method=${method}`);
                 // P1-16: 签名失败统一发布事件
                 this._dispatcher.publish('signature.verification_failed', {
                     aid: sigAid, method, error: 'ECDSA verification failed',
@@ -2312,7 +2542,7 @@ export class AUNClient {
             return ok;
         }
         catch (exc) {
-            _clientLog('warn', '群事件验签异常: %s', formatCaughtError(exc));
+            this._clientLog.warn(`群事件验签异常: ${formatCaughtError(exc)}`);
             // P1-16: 签名失败统一发布事件
             this._dispatcher.publish('signature.verification_failed', {
                 aid: String(cs.aid ?? ''), method: String(cs._method ?? ''),
@@ -2370,6 +2600,11 @@ export class AUNClient {
         result = this._groupE2ee.handleIncoming(actualPayload);
         if (result === 'distribution') {
             await this._discardGroupDistributionIfStale(actualPayload);
+            // 收到 epoch key 说明该群有活动，触发惰性同步建立 seq 基线
+            const distGroupId = actualPayload.group_id;
+            if (distGroupId && !this._groupSynced.has(distGroupId)) {
+                this._lazySyncGroup(distGroupId).catch(() => { });
+            }
         }
         // S14: 非控制面消息且 handleIncoming 不识别 → 不拦截
         if (!isControlPlane && result === null)
@@ -2379,7 +2614,9 @@ export class AUNClient {
             const groupId = String(actualPayload.group_id ?? '');
             const requester = String(actualPayload.requester_aid ?? '');
             let members = this._groupE2ee.getMemberAids(groupId);
-            // 请求者不在本地成员列表时，回源查询服务端最新成员列表
+            // 请求者不在本地成员列表时，回源查询服务端最新成员列表，
+            // 仅用于传递给 handleKeyRequestMsg 做鉴权，不更新本地密钥存储
+            // （历史 epoch 的成员隔离由 handleKeyRequest 内部负责）。
             if (requester && !members.includes(requester)) {
                 try {
                     const membersResult = await this.call('group.get_members', { group_id: groupId });
@@ -2387,18 +2624,9 @@ export class AUNClient {
                         ? membersResult.members
                         : [];
                     members = memberList.map((m) => String(m.aid));
-                    // 更新本地当前 epoch 的 member_aids/commitment
-                    if (members.includes(requester)) {
-                        const secretData = this._groupE2ee.loadSecret(groupId);
-                        if (secretData && this._aid) {
-                            const epoch = secretData.epoch;
-                            const commitment = computeMembershipCommitment(members, epoch, groupId, secretData.secret);
-                            storeGroupSecret(this._keystore, this._aid, groupId, epoch, secretData.secret, commitment, members);
-                        }
-                    }
                 }
                 catch (exc) {
-                    _clientLog('warn', '群组 %s 成员列表回源失败: %s', groupId, formatCaughtError(exc));
+                    this._clientLog.warn(`群组 ${groupId} 成员列表回源失败: ${formatCaughtError(exc)}`);
                 }
             }
             const response = this._groupE2ee.handleKeyRequestMsg(actualPayload, members);
@@ -2412,7 +2640,7 @@ export class AUNClient {
                     });
                 }
                 catch (exc) {
-                    _clientLog('warn', '向 %s 回复群组密钥失败: %s', requester, formatCaughtError(exc));
+                    this._clientLog.warn(`向 ${requester} 回复群组密钥失败: ${formatCaughtError(exc)}`);
                 }
             }
         }
@@ -2423,7 +2651,7 @@ export class AUNClient {
             const keyCommitment = String(actualPayload.commitment ?? '');
             if (rotationId && keyCommitment) {
                 this._ackGroupRotationKey(rotationId, keyCommitment)
-                    .catch((exc) => _clientLog('warn', '提交 epoch key ack 失败: %s', formatCaughtError(exc)));
+                    .catch((exc) => this._clientLog.warn(`提交 epoch key ack 失败: ${formatCaughtError(exc)}`));
             }
             this._scheduleRetryPendingDecryptMsgs(groupId);
         }
@@ -2498,7 +2726,7 @@ export class AUNClient {
             this._keystore.saveCert(aid, certPem, certFingerprint, { makeActive: false });
         }
         catch (exc) {
-            _clientLog('error', '写入证书到 keystore 失败 (aid=%s, fp=%s): %s', aid, certFingerprint ?? '', formatCaughtError(exc));
+            this._clientLog.error(`写入证书到 keystore 失败 (aid=${aid}, fp=${certFingerprint ?? ''}): ${formatCaughtError(exc)}`, exc instanceof Error ? exc : undefined);
         }
         return certPem;
     }
@@ -2531,7 +2759,7 @@ export class AUNClient {
                 if (normalized.length > 0) {
                     this._peerPrekeysCache.set(peerAid, {
                         items: normalized.map((item) => ({ ...item })),
-                        expireAt: Date.now() / 1000 + 300,
+                        expireAt: Date.now() / 1000 + PEER_PREKEYS_CACHE_TTL,
                     });
                     this._e2ee.cachePrekey(peerAid, normalized[0]);
                     return normalized;
@@ -2546,7 +2774,7 @@ export class AUNClient {
                 if (normalized.length > 0) {
                     this._peerPrekeysCache.set(peerAid, {
                         items: normalized.map((item) => ({ ...item })),
-                        expireAt: Date.now() / 1000 + 300,
+                        expireAt: Date.now() / 1000 + PEER_PREKEYS_CACHE_TTL,
                     });
                     this._e2ee.cachePrekey(peerAid, normalized[0]);
                     return normalized.map((item) => ({ ...item }));
@@ -2579,6 +2807,25 @@ export class AUNClient {
         }
         return { ...prekeys[0] };
     }
+    /** 清除对端 prekey 的双层缓存（_peerPrekeysCache + e2ee 内部缓存） */
+    _invalidatePeerPrekeyCache(peerAid) {
+        this._peerPrekeysCache.delete(peerAid);
+        this._e2ee.invalidatePrekeyCache(peerAid);
+    }
+    /** 清除对端证书缓存（精确匹配 aid 或 aid# 前缀的所有条目） */
+    _clearPeerCertCache(peerAid) {
+        for (const cacheKey of this._certCache.keys()) {
+            if (cacheKey === peerAid || cacheKey.startsWith(`${peerAid}#`)) {
+                this._certCache.delete(cacheKey);
+            }
+        }
+    }
+    /** 清除对端所有缓存后重新拉取 prekey（用于指纹不匹配时的强制刷新） */
+    async _refreshPeerPrekeys(peerAid) {
+        this._invalidatePeerPrekeyCache(peerAid);
+        this._clearPeerCertCache(peerAid);
+        return await this._fetchPeerPrekeys(peerAid);
+    }
     /** 生成 prekey 并上传到服务端 */
     async _uploadPrekey() {
         const prekeyMaterial = this._e2ee.generatePrekey();
@@ -2630,10 +2877,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(`刷新发送方 ${aid} 证书失败，继续使用已验证的内存缓存: ${formatCaughtError(exc)}`);
                 return true;
             }
-            _clientLog('warn', '获取发送方 %s 证书失败且无已验证缓存，拒绝信任: %s', aid, formatCaughtError(exc));
+            this._clientLog.warn(`获取发送方 ${aid} 证书失败且无已验证缓存，拒绝信任: ${formatCaughtError(exc)}`);
             return false;
         }
     }
@@ -2642,7 +2889,11 @@ export class AUNClient {
      * 零信任：不直接信任 keystore 中可能由恶意服务端注入的证书。
      */
     _getVerifiedPeerCert(aid, certFingerprint) {
-        const cached = this._certCache.get(AUNClient._certCacheKey(aid, certFingerprint));
+        let cached = this._certCache.get(AUNClient._certCacheKey(aid, certFingerprint));
+        // 带 fingerprint 查不到时，降级用 aid 再查一次
+        if (!cached && certFingerprint) {
+            cached = this._certCache.get(AUNClient._certCacheKey(aid, undefined));
+        }
         const now = Date.now() / 1000;
         if (cached && now < cached.validatedAt + PEER_CERT_CACHE_TTL * 2) {
             return cached.certPem;
@@ -2665,7 +2916,7 @@ export class AUNClient {
         if (fromAid) {
             const certReady = await this._ensureSenderCertCached(fromAid, senderCertFingerprint || undefined);
             if (!certReady) {
-                _clientLog('warn', '无法获取发送方 %s 的证书，跳过解密', fromAid);
+                this._clientLog.warn(`无法获取发送方 ${fromAid} 的证书，跳过解密`);
                 throw new Error(`发送方证书不可用: from=${fromAid}, mid=${message.message_id}`);
             }
         }
@@ -2701,7 +2952,7 @@ export class AUNClient {
                 if (fromAid) {
                     const certReady = await this._ensureSenderCertCached(fromAid, senderCertFingerprint || undefined);
                     if (!certReady) {
-                        _clientLog('warn', '无法获取发送方 %s 的证书，跳过解密', fromAid);
+                        this._clientLog.warn(`无法获取发送方 ${fromAid} 的证书，跳过解密`);
                         continue;
                     }
                 }
@@ -2712,7 +2963,7 @@ export class AUNClient {
                 }
                 else {
                     // TS-015: 解密失败不回退到密文，跳过该消息并记录
-                    _clientLog('warn', 'pull 消息解密失败，跳过: from=%s mid=%s', msg.from, msg.message_id);
+                    this._clientLog.warn(`pull 消息解密失败，跳过: from=${msg.from} mid=${msg.message_id}`);
                 }
             }
             else {
@@ -2765,7 +3016,7 @@ 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(`群 ${groupId} pending 消息重试失败: ${formatCaughtError(exc)}`));
     }
     async _recoverGroupEpochKey(groupId, epoch, senderAid = '', timeoutMs = 5000) {
         const existing = await this._groupE2ee.loadSecret(groupId, epoch);
@@ -2783,7 +3034,254 @@ export class AUNClient {
         this._groupEpochRecoveryInflight.set(key, promise);
         return promise;
     }
+    static _extractGroupJoinMode(payload) {
+        if (!isJsonObject(payload))
+            return '';
+        for (const key of ['join_mode', 'mode']) {
+            const v = String(payload[key] ?? '').trim().toLowerCase();
+            if (v)
+                return v;
+        }
+        for (const key of ['join_requirements', 'join']) {
+            const nested = payload[key];
+            if (isJsonObject(nested)) {
+                for (const nk of ['mode', 'join_mode']) {
+                    const v = String(nested[nk] ?? '').trim().toLowerCase();
+                    if (v)
+                        return v;
+                }
+            }
+        }
+        if (isJsonObject(payload.group)) {
+            const v = AUNClient._extractGroupJoinMode(payload.group);
+            if (v)
+                return v;
+        }
+        const settings = payload.settings;
+        if (isJsonObject(settings)) {
+            for (const key of ['join.mode', 'join_mode', 'mode']) {
+                const v = String(settings[key] ?? '').trim().toLowerCase();
+                if (v)
+                    return v;
+            }
+        }
+        if (Array.isArray(settings)) {
+            for (const item of settings) {
+                if (!isJsonObject(item))
+                    continue;
+                const k = String(item.key ?? item.name ?? '').trim().toLowerCase();
+                if (k === 'join.mode' || k === 'join_mode' || k === 'mode') {
+                    const v = String(item.value ?? '').trim().toLowerCase();
+                    if (v)
+                        return v;
+                }
+            }
+        }
+        return '';
+    }
+    static _joinModeAllowsMemberEpochRotation(mode) {
+        const m = mode.trim().toLowerCase();
+        return m === 'open' || m === 'invite_only' || m === 'invite_code';
+    }
+    async _groupAllowsMemberEpochRotation(groupId) {
+        try {
+            const resp = await this.call('group.get_join_requirements', { group_id: groupId });
+            const mode = AUNClient._extractGroupJoinMode(resp);
+            if (mode)
+                return AUNClient._joinModeAllowsMemberEpochRotation(mode);
+        }
+        catch { /* best effort */ }
+        try {
+            const resp = await this.call('group.get_settings', { group_id: groupId, keys: ['join.mode'] });
+            const mode = AUNClient._extractGroupJoinMode(resp);
+            if (mode)
+                return AUNClient._joinModeAllowsMemberEpochRotation(mode);
+        }
+        catch { /* best effort */ }
+        try {
+            const resp = await this.call('group.get', { group_id: groupId });
+            const mode = AUNClient._extractGroupJoinMode(resp);
+            if (mode)
+                return AUNClient._joinModeAllowsMemberEpochRotation(mode);
+        }
+        catch { /* best effort */ }
+        return false;
+    }
+    /** 尝试从服务端拉取 ECIES 加密的 epoch key 并解密存入 keystore */
+    async _tryRecoverEpochKeyFromServer(groupId, epoch) {
+        try {
+            const params = { group_id: groupId };
+            if (epoch > 0)
+                params.epoch = epoch;
+            const result = await this.call('group.e2ee.get_epoch_key', params);
+            if (!isJsonObject(result))
+                return false;
+            const encryptedB64 = result.encrypted_key;
+            if (!encryptedB64 || typeof encryptedB64 !== 'string')
+                return false;
+            const serverEpoch = Number(result.epoch ?? epoch);
+            const encryptedBytes = Buffer.from(encryptedB64, 'base64');
+            // 用自己的 AID 私钥 ECIES 解密
+            const myAid = this._aid || '';
+            const keyPair = this._keystore.loadKeyPair(myAid);
+            if (!keyPair?.private_key_pem) {
+                this._clientLog.warn(`无法加载 AID 私钥用于 ECIES 解密: aid=${myAid}`);
+                return false;
+            }
+            const { eciesDecrypt } = await import('./e2ee-group.js');
+            const groupSecret = eciesDecrypt(keyPair.private_key_pem, encryptedBytes);
+            if (!groupSecret || groupSecret.length !== 32) {
+                this._clientLog.warn(`服务端 epoch key ECIES 解密结果长度异常: group=${groupId} epoch=${serverEpoch} len=${groupSecret?.length ?? 0}`);
+                return false;
+            }
+            // 获取成员列表和 committed_rotation 用于 commitment / epoch_chain 验证
+            let memberAids = [];
+            let committedRotation = null;
+            let epochChain = '';
+            try {
+                const epochInfo = await this.call('group.e2ee.get_epoch', { group_id: groupId });
+                if (isJsonObject(epochInfo)) {
+                    if (Array.isArray(epochInfo.members)) {
+                        memberAids = epochInfo.members
+                            .map((m) => {
+                            if (typeof m === 'string')
+                                return m;
+                            if (isJsonObject(m) && typeof m.aid === 'string')
+                                return m.aid;
+                            return '';
+                        })
+                            .filter((s) => s.length > 0);
+                    }
+                    if (isJsonObject(epochInfo.committed_rotation)) {
+                        committedRotation = epochInfo.committed_rotation;
+                        const rawChain = String(committedRotation.epoch_chain ?? '').trim();
+                        if (rawChain)
+                            epochChain = rawChain;
+                        // 如果有 expected_members，用它覆盖 memberAids
+                        if (Array.isArray(committedRotation.expected_members) && committedRotation.expected_members.length > 0) {
+                            memberAids = committedRotation.expected_members
+                                .map(item => String(item ?? '').trim())
+                                .filter(s => s.length > 0);
+                        }
+                    }
+                }
+            }
+            catch { /* best effort */ }
+            if (memberAids.length === 0) {
+                this._clientLog.warn(`服务端 epoch key 恢复缺少成员快照: group=${groupId} epoch=${serverEpoch}`);
+                return false;
+            }
+            const commitment = computeMembershipCommitment(memberAids, serverEpoch, groupId, groupSecret);
+            // committed_rotation 存在时验证 commitment 和 epoch_chain
+            let epochChainUnverified = null;
+            let epochChainUnverifiedReason = null;
+            if (committedRotation) {
+                const committedEpoch = Number(committedRotation.target_epoch ?? serverEpoch);
+                const committedCommitment = String(committedRotation.key_commitment ?? '').trim();
+                if (committedEpoch === serverEpoch && committedCommitment && committedCommitment !== commitment) {
+                    this._clientLog.warn(`服务端 epoch key 恢复 commitment 不匹配: group=${groupId} epoch=${serverEpoch}`);
+                    return false;
+                }
+                if (epochChain && committedEpoch === serverEpoch) {
+                    let rotatorAid = '';
+                    for (const key of ['rotated_by', 'lease_owner', 'committed_by']) {
+                        const v = String(committedRotation[key] ?? '').trim();
+                        if (v) {
+                            rotatorAid = v;
+                            break;
+                        }
+                    }
+                    const prevData = this._groupE2ee.loadSecret(groupId, serverEpoch - 1);
+                    const prevChain = String(prevData?.epoch_chain ?? '').trim();
+                    if (prevChain && rotatorAid) {
+                        if (!verifyEpochChain(epochChain, prevChain, serverEpoch, commitment, rotatorAid)) {
+                            this._clientLog.warn(`服务端 epoch key 恢复 epoch_chain 验证失败: group=${groupId} epoch=${serverEpoch} rotator=${rotatorAid}`);
+                            return false;
+                        }
+                        epochChainUnverified = false;
+                    }
+                    else {
+                        epochChainUnverified = true;
+                        epochChainUnverifiedReason = prevChain ? 'missing_rotator_aid' : 'missing_prev_chain';
+                    }
+                }
+            }
+            const stored = storeGroupSecretEpoch(this._keystore, myAid, groupId, serverEpoch, groupSecret, commitment, memberAids, epochChain || undefined, '', epochChainUnverified, epochChainUnverifiedReason);
+            if (!stored) {
+                this._clientLog.warn(`服务端 epoch key 恢复存储失败: group=${groupId} epoch=${serverEpoch}`);
+                return false;
+            }
+            this._clientLog.info(`从服务端恢复 epoch key 成功: group=${groupId} epoch=${serverEpoch}`);
+            return true;
+        }
+        catch (exc) {
+            this._clientLog.debug(`从服务端恢复 epoch key 失败: group=${groupId} epoch=${epoch} err=${formatCaughtError(exc)}`);
+            return false;
+        }
+    }
+    /** 为每个成员用其 AID 证书公钥 ECIES 加密 group_secret，返回 {aid: base64_ciphertext} */
+    async _buildEpochEncryptedKeys(info, memberAids, targetEpoch, groupId) {
+        try {
+            const { eciesEncrypt } = await import('./e2ee-group.js');
+            // 从 distribution payload 中提取 group_secret
+            let groupSecretBytes = null;
+            const distributions = Array.isArray(info.distributions) ? info.distributions : [];
+            for (const dist of distributions) {
+                if (isJsonObject(dist) && isJsonObject(dist.payload)) {
+                    const gsB64 = dist.payload.group_secret;
+                    if (typeof gsB64 === 'string' && gsB64.length > 0) {
+                        groupSecretBytes = Buffer.from(gsB64, 'base64');
+                        break;
+                    }
+                }
+            }
+            if (!groupSecretBytes) {
+                // fallback: 从本地 keystore 加载
+                const loaded = this._groupE2ee.loadSecret(groupId, targetEpoch);
+                if (loaded?.secret) {
+                    groupSecretBytes = loaded.secret;
+                }
+                else {
+                    this._clientLog.debug(`无法获取 group_secret 用于 ECIES 加密: group=${groupId} epoch=${targetEpoch}`);
+                    return {};
+                }
+            }
+            const encryptedKeys = {};
+            for (const aid of memberAids) {
+                try {
+                    const certPem = await this._fetchPeerCert(aid);
+                    const x509Cert = new crypto.X509Certificate(certPem);
+                    const pubKey = x509Cert.publicKey;
+                    // 导出未压缩 EC 公钥点
+                    const jwk = pubKey.export({ format: 'jwk' });
+                    if (jwk.crv !== 'P-256' || !jwk.x || !jwk.y)
+                        continue;
+                    const xBuf = Buffer.from(jwk.x, 'base64url');
+                    const yBuf = Buffer.from(jwk.y, 'base64url');
+                    const pubkeyBytes = Buffer.concat([Buffer.from([0x04]), xBuf, yBuf]);
+                    const ciphertext = eciesEncrypt(pubkeyBytes, groupSecretBytes);
+                    encryptedKeys[aid] = ciphertext.toString('base64');
+                }
+                catch (exc) {
+                    this._clientLog.debug(`为成员 ${aid} 构建 ECIES epoch key 失败: ${formatCaughtError(exc)}`);
+                    continue;
+                }
+            }
+            return encryptedKeys;
+        }
+        catch (exc) {
+            this._clientLog.debug(`构建 encrypted_keys 失败: group=${groupId} err=${formatCaughtError(exc)}`);
+            return {};
+        }
+    }
     async _doRecoverGroupEpochKey(groupId, epoch, senderAid, timeoutMs) {
+        // 仅 open / invite_code 群允许从服务端拉取 ECIES 加密的 epoch key
+        if (await this._groupAllowsMemberEpochRotation(groupId)) {
+            if (await this._tryRecoverEpochKeyFromServer(groupId, epoch)) {
+                this._scheduleRetryPendingDecryptMsgs(groupId);
+                return true;
+            }
+        }
         let epochResult = { epoch };
         try {
             const raw = await this.call('group.e2ee.get_epoch', { group_id: groupId });
@@ -2797,7 +3295,31 @@ export class AUNClient {
             const current = Array.isArray(epochResult.recovery_candidates) ? epochResult.recovery_candidates : [];
             epochResult.recovery_candidates = [senderAid, ...current];
         }
-        await this._requestGroupKeyFromCandidates(groupId, epoch, epochResult);
+        // 在线优先恢复：先查在线成员列表，只向在线成员发送密钥请求
+        let onlineAids = null;
+        try {
+            const onlineResp = await this.call('group.get_online_members', { group_id: groupId });
+            if (isJsonObject(onlineResp)) {
+                const rawMembers = Array.isArray(onlineResp.members) ? onlineResp.members
+                    : Array.isArray(onlineResp.items) ? onlineResp.items : [];
+                onlineAids = rawMembers
+                    .filter((m) => isJsonObject(m) && m.online === true && String(m.aid ?? '') !== this._aid)
+                    .map(m => String(m.aid ?? ''));
+            }
+        }
+        catch {
+            this._clientLog.debug(`群 ${groupId} 查询在线成员失败，回退全量候选`);
+        }
+        if (onlineAids !== null) {
+            if (onlineAids.length === 0) {
+                this._clientLog.info(`群 ${groupId} epoch ${String(epoch)} 恢复失败：无在线成员可请求密钥`);
+                return false;
+            }
+            await this._requestGroupKeyFromOnline(groupId, epoch, onlineAids, epochResult);
+        }
+        else {
+            await this._requestGroupKeyFromCandidates(groupId, epoch, epochResult);
+        }
         const deadline = Date.now() + timeoutMs;
         while (Date.now() < deadline) {
             await new Promise(resolve => setTimeout(resolve, 150));
@@ -2813,6 +3335,22 @@ export class AUNClient {
             this._scheduleRetryPendingDecryptMsgs(groupId);
         return ready;
     }
+    /** 只向在线成员发送密钥恢复请求 */
+    async _requestGroupKeyFromOnline(groupId, epoch, onlineAids, epochResult) {
+        const candidates = this._groupKeyRecoveryCandidates(groupId, epochResult);
+        const ordered = [];
+        for (const aid of candidates) {
+            if (onlineAids.includes(aid) && !ordered.includes(aid))
+                ordered.push(aid);
+        }
+        for (const aid of onlineAids) {
+            if (!ordered.includes(aid))
+                ordered.push(aid);
+        }
+        for (const aid of ordered) {
+            await this._requestGroupKeyFrom(groupId, aid, epoch);
+        }
+    }
     async _groupEpochSecretReadyForRecovery(groupId, epoch, secret) {
         if (!isJsonObject(secret))
             return false;
@@ -2855,7 +3393,7 @@ export class AUNClient {
         if (senderAid) {
             const certOk = await this._ensureSenderCertCached(senderAid);
             if (!certOk) {
-                _clientLog('warn', '群消息解密跳过：发送方 %s 证书不可用', senderAid);
+                this._clientLog.warn(`群消息解密跳过：发送方 ${senderAid} 证书不可用`);
                 return message;
             }
         }
@@ -2882,7 +3420,7 @@ export class AUNClient {
                 }
             }
             catch (exc) {
-                _clientLog('debug', '群 %s epoch %s 同步恢复失败: %s', groupId, epoch, formatCaughtError(exc));
+                this._clientLog.debug(`群 ${groupId} epoch ${epoch} 同步恢复失败: ${formatCaughtError(exc)}`);
             }
         }
         return message;
@@ -2943,18 +3481,27 @@ export class AUNClient {
                 payload: payload ?? {},
                 created_at: Number(item.created_at ?? 0),
             };
+            if (isJsonObject(item.context))
+                message.context = item.context;
             const decrypted = await this._decryptGroupMessage(message, { skipReplay: true });
+            let decryptFailed = false;
             if (payload?.type === 'e2ee.group_encrypted' && groupId && !decrypted.e2ee) {
-                this._enqueuePendingDecrypt(groupId, message);
-                continue;
+                decryptFailed = true;
+                // 安全网：触发 epoch key 恢复（内部有去重，重复调用安全）
+                const epoch = Number(payload.epoch ?? 0);
+                if (epoch > 0) {
+                    this._recoverGroupEpochKey(groupId, epoch, senderAid, 5000).catch(() => { });
+                }
             }
             const thought = {
                 thought_id: thoughtId,
                 message_id: thoughtId,
-                payload: decrypted.payload,
+                payload: decryptFailed ? (payload ?? {}) : decrypted.payload,
                 created_at: item.created_at,
                 e2ee: decrypted.e2ee,
             };
+            if (decryptFailed)
+                thought.decrypt_failed = true;
             if ('context' in item)
                 thought.context = item.context;
             thoughts.push(thought);
@@ -2985,19 +3532,25 @@ export class AUNClient {
                 encrypted: item.encrypted !== false,
                 timestamp: Number(item.created_at ?? 0),
             };
+            if (isJsonObject(item.context))
+                message.context = item.context;
             let decrypted = message;
+            let decryptFailed = false;
             if (payload?.type === 'e2ee.encrypted') {
                 const senderCertFingerprint = String(payload.sender_cert_fingerprint ?? payload.aad?.sender_cert_fingerprint ?? '').trim().toLowerCase();
                 if (fromAid) {
                     const certReady = await this._ensureSenderCertCached(fromAid, senderCertFingerprint || undefined);
                     if (!certReady) {
-                        _clientLog('warn', '无法获取发送方 %s 的证书，跳过 message.thought.get 解密', fromAid);
-                        continue;
+                        this._clientLog.warn(`无法获取发送方 ${fromAid} 的证书，跳过 message.thought.get 解密`);
+                        decryptFailed = true;
                     }
                 }
-                decrypted = this._e2ee._decryptMessage(message);
-                if (decrypted === null || (isJsonObject(decrypted.payload) && decrypted.payload.type === 'e2ee.encrypted')) {
-                    continue;
+                if (!decryptFailed) {
+                    decrypted = this._e2ee._decryptMessage(message);
+                    if (decrypted === null || (isJsonObject(decrypted.payload) && decrypted.payload.type === 'e2ee.encrypted')) {
+                        decryptFailed = true;
+                        decrypted = message;
+                    }
                 }
             }
             const thought = {
@@ -3005,10 +3558,12 @@ export class AUNClient {
                 message_id: thoughtId,
                 from: fromAid,
                 to: toAid,
-                payload: decrypted.payload,
+                payload: decryptFailed ? (payload ?? {}) : decrypted.payload,
                 created_at: item.created_at,
-                e2ee: decrypted.e2ee,
+                e2ee: decryptFailed ? undefined : decrypted.e2ee,
             };
+            if (decryptFailed)
+                thought.decrypt_failed = true;
             if ('context' in item)
                 thought.context = item.context;
             thoughts.push(thought);
@@ -3071,7 +3626,7 @@ export class AUNClient {
                     }
                     else {
                         failed.push(String(dist.to));
-                        _clientLog('warn', 'epoch 密钥分发失败 (to=%s): %s', dist.to, formatCaughtError(exc));
+                        this._clientLog.warn(`epoch 密钥分发失败 (to=${dist.to}): ${formatCaughtError(exc)}`);
                     }
                 }
             }
@@ -3089,7 +3644,7 @@ 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(`刷新 epoch rotation lease 失败: rotation=${rotationId} err=${formatCaughtError(exc)}`);
             return false;
         }
     }
@@ -3105,7 +3660,7 @@ export class AUNClient {
             return isJsonObject(result) && result.success === true;
         }
         catch (exc) {
-            _clientLog('warn', '提交 epoch key ack 失败: rotation=%s err=%s', rotationId, formatCaughtError(exc));
+            this._clientLog.warn(`提交 epoch key ack 失败: rotation=${rotationId} err=${formatCaughtError(exc)}`);
             return false;
         }
     }
@@ -3128,12 +3683,21 @@ export class AUNClient {
                 if (Number.isFinite(epoch) && epoch > 0 && epoch <= committedEpoch) {
                     if (committedRotation && Number(committedRotation.target_epoch ?? committedEpoch) === epoch) {
                         const committedCommitment = String(committedRotation.key_commitment ?? '').trim();
-                        if (committedCommitment && commitment && committedCommitment !== commitment)
-                            return false;
+                        if (committedCommitment && commitment && committedCommitment !== commitment) {
+                            const expectedMembers = Array.isArray(committedRotation.expected_members)
+                                ? committedRotation.expected_members.map((item) => String(item ?? '').trim()).filter(Boolean)
+                                : [];
+                            if (this._aid && !expectedMembers.includes(this._aid)) {
+                                this._clientLog.debug(`放行 group key 分发：新成员恢复 commitment 不匹配属正常 group=${groupId} epoch=${epoch}`);
+                            }
+                            else {
+                                return false;
+                            }
+                        }
                     }
                     return true;
                 }
-                _clientLog('info', '拒绝缺少 rotation_id 的未来 epoch key 分发: group=%s epoch=%s committed=%s', groupId, epoch, committedEpoch);
+                this._clientLog.info(`拒绝缺少 rotation_id 的未来 epoch key 分发: group=${groupId} epoch=${epoch} committed=${committedEpoch}`);
                 return false;
             }
             const pending = isJsonObject(epochResult.pending_rotation) ? epochResult.pending_rotation : null;
@@ -3154,10 +3718,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(`拒绝无法校验 active rotation 的 epoch key 分发: 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(`拒绝非 pending/committed 状态的 epoch key 分发: group=${groupId} rotation=${rotationId} epoch=${epoch}`);
         return false;
     }
     async _discardGroupDistributionIfStale(payload) {
@@ -3172,10 +3736,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(`丢弃 verify 后变为 stale 的 group epoch key: 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(`清理 stale group epoch key 失败: group=${groupId} epoch=${epoch} rotation=${rotationId} err=${formatCaughtError(exc)}`);
         }
     }
     async _verifyGroupKeyResponseEpoch(payload) {
@@ -3192,19 +3756,28 @@ 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(`拒绝未提交 epoch 的 group key response: group=${groupId} epoch=${epoch} committed=${committedEpoch}`);
                 return false;
             }
             const committedRotation = isJsonObject(epochResult.committed_rotation) ? epochResult.committed_rotation : null;
             if (committedRotation && Number(committedRotation.target_epoch ?? committedEpoch) === epoch) {
                 const committedCommitment = String(committedRotation.key_commitment ?? '').trim();
-                if (committedCommitment && commitment && committedCommitment !== commitment)
-                    return false;
+                if (committedCommitment && commitment && committedCommitment !== commitment) {
+                    const expectedMembers = Array.isArray(committedRotation.expected_members)
+                        ? committedRotation.expected_members.map((item) => String(item ?? '').trim()).filter(Boolean)
+                        : [];
+                    if (this._aid && !expectedMembers.includes(this._aid)) {
+                        this._clientLog.debug(`放行 group key response：新成员恢复 commitment 不匹配属正常 group=${groupId} epoch=${epoch}`);
+                    }
+                    else {
+                        return false;
+                    }
+                }
             }
             return true;
         }
         catch (exc) {
-            _clientLog('warn', '拒绝无法校验 committed epoch 的 group key response: group=%s epoch=%s err=%s', groupId, epoch, formatCaughtError(exc));
+            this._clientLog.warn(`拒绝无法校验 committed epoch 的 group key response: group=${groupId} epoch=${epoch} err=${formatCaughtError(exc)}`);
             return false;
         }
     }
@@ -3219,7 +3792,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(`中止 epoch rotation 失败: rotation=${rotationId} err=${formatCaughtError(exc)}`);
             return false;
         }
     }
@@ -3253,7 +3826,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);
@@ -3265,7 +3838,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));
@@ -3298,31 +3871,39 @@ 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;
                     }
-                    const commitResult = await this.call('group.e2ee.commit_rotation', { rotation_id: activeRotationId });
+                    const commitParams2 = { rotation_id: activeRotationId };
+                    const createMembers = secretData.member_aids.length > 0 ? secretData.member_aids : (this._aid ? [this._aid] : []);
+                    const encKeys2 = await this._buildEpochEncryptedKeys({ distributions: [{ payload: { group_secret: secretData.secret.toString('base64') } }] }, createMembers, 1, groupId);
+                    if (await this._groupAllowsMemberEpochRotation(groupId)) {
+                        if (encKeys2 && Object.keys(encKeys2).length > 0) {
+                            commitParams2.encrypted_keys = encKeys2;
+                        }
+                    }
+                    const commitResult = await this.call('group.e2ee.commit_rotation', commitParams2);
                     if (isJsonObject(commitResult) && commitResult.success === true) {
                         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(`同步 epoch 到服务端失败 (group=${groupId}, 第${attempt}/${maxRetries}次): ${formatCaughtError(exc)}, ${delay}ms后重试`);
                         await new Promise(r => setTimeout(r, delay));
                     }
                     else {
-                        _clientLog('error', '同步 epoch 到服务端最终失败 (group=%s, 已重试%d次): %s', groupId, maxRetries, formatCaughtError(exc));
+                        this._clientLog.error(`同步 epoch 到服务端最终失败 (group=${groupId}, 已重试${maxRetries}次): ${formatCaughtError(exc)}`, exc instanceof Error ? exc : undefined);
                     }
                 }
             }
@@ -3353,7 +3934,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, {
@@ -3368,20 +3949,35 @@ 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;
             const targetEpoch = currentEpoch + 1;
+            // 新成员可能没有 prev epoch key，或有 key 但缺少 epoch_chain（通过 backfill 接收）。
+            // 从 committed_rotation.epoch_chain 获取 prev chain hint。
+            let prevChainHint = null;
+            const localPrev = this._groupE2ee.loadSecret(groupId, currentEpoch);
+            const localPrevChain = String(localPrev?.epoch_chain ?? '');
+            if (!localPrevChain && isJsonObject(epochResult)) {
+                const cr = epochResult.committed_rotation;
+                if (isJsonObject(cr)) {
+                    const rawChain = String(cr.epoch_chain ?? '').trim();
+                    if (rawChain) {
+                        prevChainHint = rawChain;
+                        this._clientLog.info(`新成员轮换补充 prev epoch chain from server: group=${groupId} epoch=${currentEpoch}`);
+                    }
+                }
+            }
             const rotationId = `rot-${crypto.randomUUID().replace(/-/g, '')}`;
-            const info = this._groupE2ee.rotateEpochTo(groupId, targetEpoch, memberAids, { rotationId });
+            const info = this._groupE2ee.rotateEpochTo(groupId, targetEpoch, memberAids, { rotationId, prevChainHint });
             this._attachRotationId(info, rotationId);
             const discardGeneratedPending = () => {
                 try {
                     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(`清理本地 pending group key 失败: group=${groupId} epoch=${targetEpoch} rotation=${rotationId} err=${formatCaughtError(cleanupExc)}`);
                 }
             };
             const rotateParams = {
@@ -3435,14 +4031,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',
@@ -3455,7 +4051,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',
@@ -3466,9 +4062,17 @@ export class AUNClient {
                 discardGeneratedPending();
                 return;
             }
-            const commitResult = await this.call('group.e2ee.commit_rotation', { rotation_id: activeRotationId });
+            const commitParams = { rotation_id: activeRotationId };
+            // 构建 per-member ECIES 加密的 epoch key 上传到服务端
+            if (await this._groupAllowsMemberEpochRotation(groupId)) {
+                const encryptedKeys = await this._buildEpochEncryptedKeys(info, memberAids, targetEpoch, groupId);
+                if (encryptedKeys && Object.keys(encryptedKeys).length > 0) {
+                    commitParams.encrypted_keys = encryptedKeys;
+                }
+            }
+            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,
@@ -3492,7 +4096,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) {
@@ -3534,7 +4138,7 @@ export class AUNClient {
             if (identity && identity.private_key_pem) {
                 manifest = signMembershipManifest(manifest, String(identity.private_key_pem));
             }
-            const distPayload = buildKeyDistribution(groupId, epoch, secretData.secret, memberAids, this._aid ?? '', manifest);
+            const distPayload = buildKeyDistribution(groupId, epoch, secretData.secret, memberAids, this._aid ?? '', manifest, String(secretData.epoch_chain ?? ''));
             // 重试 3 次，间隔递增（1s, 2s）
             for (let attempt = 0; attempt < 3; attempt++) {
                 try {
@@ -3560,7 +4164,79 @@ export class AUNClient {
             this._logE2eeError('distribute_key', groupId, newMemberAid, exc);
         }
     }
-    /** 构建 epoch 轮换签名参数。失败时抛错，调用方需在 try/catch 中决定是否跳过轮换。 */
+    /** 从成员加入事件 payload 中提取新加入的成员 AID 列表。 */
+    _joinedMemberAidsFromPayload(payload) {
+        const aids = new Set();
+        const addAid = (value) => {
+            const aid = String(value ?? '').trim();
+            if (aid)
+                aids.add(aid);
+        };
+        addAid(payload.aid ?? payload.applicant_aid ?? payload.applicantAid);
+        addAid(payload.actor_aid);
+        for (const key of ['member_aid', 'target_aid', 'new_member_aid', 'used_by']) {
+            addAid(payload[key]);
+        }
+        for (const key of ['member', 'request', 'invite_code']) {
+            const nested = isJsonObject(payload[key]) ? payload[key] : null;
+            if (!nested)
+                continue;
+            addAid(nested.aid ?? nested.applicant_aid ?? nested.applicantAid);
+            for (const nk of ['member_aid', 'target_aid', 'used_by'])
+                addAid(nested[nk]);
+        }
+        if (Array.isArray(payload.results)) {
+            for (const item of payload.results) {
+                if (!isJsonObject(item))
+                    continue;
+                const obj = item;
+                const status = String(obj.status ?? '').trim().toLowerCase();
+                if (status !== 'approved' && obj.approved !== true)
+                    continue;
+                addAid(obj.aid ?? obj.applicant_aid ?? obj.applicantAid);
+                for (const key of ['member_aid', 'target_aid'])
+                    addAid(obj[key]);
+                for (const key of ['member', 'request']) {
+                    const nested = isJsonObject(obj[key]) ? obj[key] : null;
+                    if (!nested)
+                        continue;
+                    addAid(nested.aid ?? nested.applicant_aid);
+                    for (const nk of ['member_aid', 'target_aid'])
+                        addAid(nested[nk]);
+                }
+            }
+        }
+        return Array.from(aids);
+    }
+    // ── 入群密钥恢复策略 ──────────────────────────────────────
+    /** 延迟轮换等待时间（毫秒）：给新成员恢复 committed_epoch 的窗口 */
+    static _JOIN_ROTATION_DELAY_MS = 3000;
+    // 新成员自身延迟轮换时间：优先让其他在线成员先轮换
+    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));
+        await this._maybeLeadRotateGroupEpoch(groupId, triggerId, expectedEpoch, allowMember);
+    }
+    /** 当新成员加入但缺少 old_epoch 时，将当前 epoch 密钥分发给新成员。 */
+    async _maybeBackfillKeyToJoinedMember(groupId, payload, triggerId = '') {
+        const memberAids = this._joinedMemberAidsFromPayload(payload)
+            .filter(aid => aid && aid !== this._aid);
+        if (!groupId || !this._aid || memberAids.length === 0)
+            return;
+        if (!this._groupE2ee.hasSecret(groupId))
+            return;
+        for (const memberAid of memberAids) {
+            const dedupeKey = `${triggerId || this._membershipRotationTriggerId(groupId, payload)}:backfill:${memberAid}`;
+            if (this._groupMemberKeyBackfillDone.has(dedupeKey))
+                continue;
+            this._groupMemberKeyBackfillDone.add(dedupeKey);
+            if (this._groupMemberKeyBackfillDone.size > 2000) {
+                this._groupMemberKeyBackfillDone = new Set(Array.from(this._groupMemberKeyBackfillDone).slice(-1000));
+            }
+            await this._distributeKeyToNewMember(groupId, memberAid);
+        }
+    }
     _buildRotationSignature(groupId, currentEpoch, newEpoch = 0, source) {
         const identity = this._identity;
         if (!identity || !identity.private_key_pem) {
@@ -3613,8 +4289,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;
                 }
@@ -3624,12 +4301,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(`恢复 SeqTracker 状态失败: ${formatCaughtError(exc)}`);
             // 通过内部 dispatcher 发布可观测事件，便于上层监控
             this._dispatcher.publish('seq_tracker.persist_error', {
                 phase: 'restore',
@@ -3640,6 +4319,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 迁移：${Object.keys(renameMap).length} 个命名空间重写`);
+        // 落盘
+        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(`删除旧 seq ns 失败: ns=${oldNs} err=${formatCaughtError(e)}`);
+                    }
+                }
+                try {
+                    saver.call(this._keystore, this._aid, this._deviceId, this._slotId, newNs, newState[newNs]);
+                }
+                catch (e) {
+                    this._clientLog.debug(`写入新 seq ns 失败: ns=${newNs} err=${formatCaughtError(e)}`);
+                }
+            }
+        }
+        return newState;
+    }
     _currentSeqTrackerContext() {
         if (!this._aid)
             return null;
@@ -3694,7 +4426,7 @@ export class AUNClient {
             }
         }
         catch (exc) {
-            _clientLog('warn', '保存 SeqTracker 状态失败: %s', formatCaughtError(exc));
+            this._clientLog.warn(`保存 SeqTracker 状态失败: ${formatCaughtError(exc)}`);
             // 通过内部 dispatcher 发布可观测事件，便于上层监控
             this._dispatcher.publish('seq_tracker.persist_error', {
                 phase: 'save',
@@ -3776,8 +4508,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 ?? '');
                         }
@@ -3806,7 +4538,7 @@ export class AUNClient {
                 await this._uploadPrekey();
             }
             catch (exc) {
-                _clientLog('warn', 'prekey 上传失败: %s', formatCaughtError(exc));
+                this._clientLog.warn(`prekey 上传失败: ${formatCaughtError(exc)}`);
             }
         }
         catch (err) {
@@ -3843,8 +4575,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);
@@ -3923,8 +4655,6 @@ export class AUNClient {
         this._startHeartbeatTask();
         this._startTokenRefreshTask();
         this._startGroupEpochTasks();
-        // 上线/重连后一次性补齐群消息和群事件
-        this._syncAllGroupsOnce().catch(exc => _clientLog('warn', '后台补洞触发失败: %s', formatCaughtError(exc)));
     }
     /** 停止所有后台任务 */
     _stopBackgroundTasks() {
@@ -3961,9 +4691,10 @@ export class AUNClient {
     _startHeartbeatTask() {
         if (this._heartbeatTimer !== null)
             return;
-        const interval = Number(this._sessionOptions.heartbeat_interval ?? 30) * 1000;
-        if (interval <= 0)
+        const rawIntervalSeconds = Number(this._sessionOptions.heartbeat_interval ?? DEFAULT_SESSION_OPTIONS.heartbeat_interval);
+        if (!Number.isFinite(rawIntervalSeconds) || rawIntervalSeconds <= 0)
             return;
+        const interval = Math.max(rawIntervalSeconds, 30) * 1000;
         // M25: 把连续失败阈值从 3 次收窄到 2 次。既能容忍一次网络抖动/GC 暂停，
         // 又把半开连接的检测延迟从 3 个心跳周期降到 2 个。
         // 真正的 socket 死亡由 ws.on('close') 立即触发 _handleTransportDisconnect，
@@ -3977,10 +4708,10 @@ export class AUNClient {
                 consecutiveFailures = 0;
             }).catch((exc) => {
                 consecutiveFailures++;
-                _clientLog('warn', '心跳失败 (%s/%s): %s', consecutiveFailures, maxFailures, formatCaughtError(exc));
+                this._clientLog.warn(`心跳失败 (${consecutiveFailures}/${maxFailures}): ${formatCaughtError(exc)}`);
                 this._dispatcher.publish('connection.error', { error: formatCaughtError(exc) }).catch(() => { });
                 if (consecutiveFailures >= maxFailures) {
-                    _clientLog('warn', '连续 %s 次心跳失败，触发断线重连', maxFailures);
+                    this._clientLog.warn(`连续 ${maxFailures} 次心跳失败，触发断线重连`);
                     this._handleTransportDisconnect(exc instanceof Error ? exc : new Error(String(exc)));
                 }
             });
@@ -3994,31 +4725,36 @@ export class AUNClient {
     _startTokenRefreshTask() {
         if (this._tokenRefreshTimer !== null)
             return;
-        const lead = Number(this._sessionOptions.token_refresh_before ?? 60);
-        const minimumSleep = 1000;
-        const scheduleNext = () => {
+        const rawLead = Number(this._sessionOptions.token_refresh_before ?? DEFAULT_SESSION_OPTIONS.token_refresh_before);
+        const lead = Number.isFinite(rawLead) && rawLead > 0
+            ? rawLead
+            : DEFAULT_SESSION_OPTIONS.token_refresh_before;
+        const scheduleNext = (delayMs = TOKEN_REFRESH_CHECK_INTERVAL_MS) => {
             if (this._closing)
                 return;
-            if (this._state !== 'connected' || !this._gatewayUrl) {
-                this._tokenRefreshTimer = setTimeout(scheduleNext, minimumSleep);
-                this._unrefTimer(this._tokenRefreshTimer);
-                return;
-            }
-            let identity = this._identity ?? this._auth.loadIdentityOrNone() ?? null;
-            if (identity === null) {
-                this._tokenRefreshTimer = setTimeout(scheduleNext, minimumSleep);
-                this._unrefTimer(this._tokenRefreshTimer);
-                return;
-            }
-            this._identity = identity;
-            const expiresAt = this._auth.getAccessTokenExpiry(identity);
-            if (expiresAt === null) {
-                this._tokenRefreshTimer = setTimeout(scheduleNext, minimumSleep);
-                this._unrefTimer(this._tokenRefreshTimer);
-                return;
-            }
-            const delay = Math.max((expiresAt - lead - Date.now() / 1000) * 1000, minimumSleep);
             this._tokenRefreshTimer = setTimeout(async () => {
+                if (this._closing)
+                    return;
+                this._tokenRefreshTimer = null;
+                if (this._state !== 'connected' || !this._gatewayUrl) {
+                    scheduleNext();
+                    return;
+                }
+                let identity = this._identity ?? this._auth.loadIdentityOrNone() ?? null;
+                if (identity === null) {
+                    scheduleNext();
+                    return;
+                }
+                this._identity = identity;
+                const expiresAt = this._auth.getAccessTokenExpiry(identity);
+                if (expiresAt === null) {
+                    scheduleNext();
+                    return;
+                }
+                if ((expiresAt - Date.now() / 1000) > lead) {
+                    scheduleNext();
+                    return;
+                }
                 if (this._closing || this._state !== 'connected' || !this._gatewayUrl) {
                     scheduleNext();
                     return;
@@ -4039,7 +4775,7 @@ export class AUNClient {
                     if (exc instanceof AuthError) {
                         this._tokenRefreshFailures++;
                         if (this._tokenRefreshFailures >= 3) {
-                            _clientLog('warn', 'token 刷新连续失败 %d 次，停止刷新循环并触发重连', this._tokenRefreshFailures);
+                            this._clientLog.warn(`token 刷新连续失败 ${this._tokenRefreshFailures} 次，停止刷新循环并触发重连`);
                             await this._dispatcher.publish('token.refresh_exhausted', {
                                 aid: this._identity?.aid ?? null,
                                 consecutive_failures: this._tokenRefreshFailures,
@@ -4049,17 +4785,17 @@ 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 刷新失败 (${this._tokenRefreshFailures}/3)，下次重试: ${exc}`);
                     }
                     else {
                         await this._dispatcher.publish('connection.error', { error: formatCaughtError(exc) });
                     }
                 }
                 scheduleNext();
-            }, delay);
+            }, delayMs);
             this._unrefTimer(this._tokenRefreshTimer);
         };
-        scheduleNext();
+        scheduleNext(0);
     }
     /** 启动 prekey 刷新任务 */
     _startPrekeyRefreshTask() {
@@ -4151,7 +4887,7 @@ export class AUNClient {
                 this._prekeyReplenished.add(prekeyId);
             }
             catch (exc) {
-                _clientLog('warn', '消费 prekey %s 后补充 current prekey 失败: %s', prekeyId, formatCaughtError(exc));
+                this._clientLog.warn(`消费 prekey ${prekeyId} 后补充 current prekey 失败: ${formatCaughtError(exc)}`);
             }
             finally {
                 this._prekeyReplenishInflight.delete(prekeyId);
@@ -4176,7 +4912,7 @@ export class AUNClient {
                     }
                 }
                 catch (exc) {
-                    _clientLog('warn', 'epoch 清理失败: %s', formatCaughtError(exc));
+                    this._clientLog.warn(`epoch 清理失败: ${formatCaughtError(exc)}`);
                 }
             }, 3600_000);
             this._unrefTimer(this._groupEpochCleanupTimer);
@@ -4192,11 +4928,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 轮换失败: ${formatCaughtError(exc)}`));
                     }
                 }
                 catch (exc) {
-                    _clientLog('warn', 'epoch 轮换失败: %s', formatCaughtError(exc));
+                    this._clientLog.warn(`epoch 轮换失败: ${formatCaughtError(exc)}`);
                 }
             }, rotateInterval * 1000);
             this._unrefTimer(this._groupEpochRotateTimer);
@@ -4244,7 +4980,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(`服务端主动断开: code=${code}, reason=${reason}`);
         this._serverKicked = true;
     }
     /** 传输层断线回调 */
@@ -4265,7 +5001,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(`抑制自动重连: ${reason}`);
             await this._dispatcher.publish('connection.state', {
                 state: this._state, error, reason,
             });
@@ -4282,7 +5018,7 @@ export class AUNClient {
         this._reconnectActive = true;
         this._reconnectAbort = new AbortController();
         this._reconnectLoop(serverInitiated).catch((exc) => {
-            _clientLog('warn', '重连循环异常: %s', formatCaughtError(exc));
+            this._clientLog.warn(`重连循环异常: ${formatCaughtError(exc)}`);
         });
     }
     /** 重连循环（for 循环 + AbortController，与 JS/Python 对齐） */
@@ -4368,6 +5104,69 @@ export class AUNClient {
         }
         this._reconnectActive = false;
     }
+    // ── Named Group（命名群）高层 API ────────────────────────────
+    /**
+     * 创建命名群：本地生成 P-256 keypair，调用 group.create 传入 public_key，
+     * 服务端签发群 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);
+            }
+        }
+        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,
+                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);
+            }
+        }
+        return result;
+    }
     /** 判断是否应重试重连 */
     static _shouldRetryReconnect(error) {
         if (error instanceof AuthError) {