@agentunion/fastaun-browser 0.5.4 → 0.5.8

package/dist/client.js

@@ -9,17 +9,17 @@ import { EventDispatcher } from './events.js';
 import { normalizeGroupId } from './group-id.js';
 import { validateAIDFormat, validateGroupIDFormat } from './validators.js';
 import { GatewayDiscovery } from './discovery.js';
-import { AIDStore } from './aid-store.js';
 import { RPCTransport } from './transport.js';
 import { AuthFlow } from './auth.js';
 import { SeqTracker } from './seq-tracker.js';
 import { ClientRuntime } from './client/runtime.js';
 import { MessageDeliveryEngine } from './client/delivery.js';
+import { normalizeGroupMentionMode } from './client/mention-mode.js';
 import { IdentityRuntimeManager } from './client/identity.js';
 import { LifecycleController } from './client/lifecycle.js';
 import { PeerDirectory } from './client/peers.js';
 import { RpcPipeline } from './client/rpc-pipeline.js';
-import { GroupFacade, MessageFacade, StreamFacade } from './facades.js';
+import { GroupFacade, MailFacade, MessageFacade, StreamFacade } from './facades.js';
 import { StorageVFS } from './storage/vfs.js';
 import { CollabClient } from './collab/client.js';
 import { V2E2EECoordinator } from './client/v2-e2ee.js';
@@ -29,7 +29,7 @@ import { IndexedDBTokenStore } from './keystore/indexeddb-token-store.js';
 import { decryptMessage, } from './v2/e2ee/index.js';
 import { ecdsaVerifyRaw } from './v2/crypto/ecdsa.js';
 import { AUNLogger } from './logger.js';
-import { AgentMdManager } from './agent-md.js';
+import { AgentMdManager, buildDefaultAgentMd } from './agent-md.js';
 import { GroupIndexMetaCache } from './group-index.js';
 import { certMatchesFingerprint, normalizeFingerprintHex } from './cert-utils.js';
 import { AUNError, AuthError, ConnectionError, E2EEError, NotFoundError, PermissionError, StateError, TimeoutError, ValidationError, } from './errors.js';
@@ -78,7 +78,7 @@ function groupIndexBodyText(value) {
 }
 const DEFAULT_SESSION_OPTIONS = {
     auto_reconnect: true,
-    heartbeat_interval: 30.0,
+    heartbeat_interval: 0.0,
     token_refresh_before: 1800.0,
     retry: {
         initial_delay: 1.0,
@@ -96,24 +96,10 @@ const RECONNECT_MIN_BASE_DELAY_SECONDS = 1.0;
 const RECONNECT_MAX_BASE_DELAY_SECONDS = 64.0;
 const TOKEN_REFRESH_CHECK_INTERVAL_MS = 30_000;
 const MAX_NOTIFY_PAYLOAD_SIZE = 64 * 1024;
-// 心跳间隔下/上限（秒）。0 = 关闭心跳；负值视为 0；其余值 clamp 到 [10, 600]。
-// 服务端通过 hello.heartbeat_interval 与 meta.ping pong 中的同名字段下发。
-const HEARTBEAT_MIN_INTERVAL_SECONDS = 10;
-const HEARTBEAT_MAX_INTERVAL_SECONDS = 600;
-function clampHeartbeatInterval(value) {
-    const n = Number(value);
-    if (!Number.isFinite(n) || n <= 0)
-        return 0;
-    if (n < HEARTBEAT_MIN_INTERVAL_SECONDS)
-        return HEARTBEAT_MIN_INTERVAL_SECONDS;
-    if (n > HEARTBEAT_MAX_INTERVAL_SECONDS)
-        return HEARTBEAT_MAX_INTERVAL_SECONDS;
-    return n;
-}
 // P1-23: 非幂等方法使用更长超时（35s），避免 SDK 10s 超时 < gateway 30s 处理时间
 const NON_IDEMPOTENT_TIMEOUT = 35;
 const NON_IDEMPOTENT_METHODS = new Set([
-    'message.send', 'group.send', 'group.create', 'group.invite',
+    'message.send', 'mail.send', 'group.send', 'group.create', 'group.invite',
     'group.kick', 'group.remove_member', 'group.leave', 'group.dissolve',
     'group.set_settings',
     'group.update_announcement', 'group.update_rules',
@@ -204,7 +190,8 @@ function clampReconnectDelaySeconds(value, fallback, upper = RECONNECT_MAX_BASE_
     return Math.min(Math.max(seconds, RECONNECT_MIN_BASE_DELAY_SECONDS), upper);
 }
 function reconnectSleepDelaySeconds(baseDelay, maxBaseDelay) {
-    return baseDelay + Math.random() * maxBaseDelay;
+    const jitterLimit = Math.min(Math.max(baseDelay, 0), Math.max(maxBaseDelay - baseDelay, 0));
+    return baseDelay + Math.random() * jitterLimit;
 }
 /** 对端证书缓存 TTL（秒） */
 const PEER_CERT_CACHE_TTL = 3600;
@@ -244,6 +231,7 @@ function createAgentMdManagerForRuntime(opts) {
     return new AgentMdManager({
         aunPath: opts.config().aunPath,
         tokenStore: opts.tokenStore(),
+        uploadViaGatewayHost: true,
         logger: opts.logger(),
         ownerAidGetter: opts.ownerAid,
         currentAidGetter: opts.currentAid,
@@ -303,7 +291,6 @@ function createAgentMdManagerForRuntime(opts) {
             if (current?.aid === target) {
                 if (!expectedFp || await certMatchesFingerprint(current.certPem, expectedFp))
                     return current;
-                throw new StateError(`current AID certificate fingerprint mismatch for ${target}`);
             }
             if (!opts.gateway.get()) {
                 try {
@@ -529,6 +516,7 @@ export class AUNClient {
     _currentAid = null;
     _instanceProtectedHeaders = null;
     _gatewayUrl = null;
+    _gatewayCandidates = [];
     _deviceId;
     _slotId;
     _connectedAt = 0;
@@ -574,6 +562,8 @@ export class AUNClient {
     _v2LazyProposeTriggered = new Map();
     /** agent.md 运行时管理器，负责上传、下载、缓存和 RPC 元数据观察。 */
     _agentMdManager;
+    _aidStore;
+    _groupIdentityOperations = new Map();
     _groupIndexMetaCache = new GroupIndexMetaCache();
     _groupIndexCacheLoaded = new Set();
     /** 消息序列号跟踪器（群消息 + P2P 空洞检测） */
@@ -593,20 +583,17 @@ export class AUNClient {
     _messageRecallSeen = new Map();
     /** 群撤回去重：group_id|sorted(message_ids) -> 时间戳，保证应用层只回调一次 */
     _groupRecallSeen = new Map();
-    /** 在线未读 hint 队列：同一 group 只保留最后一条，延迟 drain 降低登录瞬时拉取压力。 */
-    _onlineUnreadHintQueue = new Map();
-    _onlineUnreadHintTimer = null;
-    _onlineUnreadHintDrainActive = false;
-    _onlineUnreadHintInitialDelayMs = 750;
-    _onlineUnreadHintIntervalMs = 50;
     /** gap fill 来源标记：true 表示当前正在补洞（pull 触发），false 表示非补洞 */
     _gapFillActive = false;
     _backgroundRpcDepth = 0;
     // Pull Gate：序列化同一 key 的并发 pull 操作，防止重复拉取
     _pullGates = new Map();
+    _pullResponseKeys = new Map();
     // 重连相关
     _reconnectActive = false;
     _reconnectAbort = null;
+    _reconnectTask = null;
+    _reconnectEventDispatchDepth = 0;
     _serverKicked = false;
     // 重连状态追踪（对齐 Python client.py）
     _nextRetryAt = null;
@@ -640,6 +627,7 @@ export class AUNClient {
     _storage;
     _collab;
     _messageFacade;
+    _mailFacade;
     _groupFacade;
     _streamFacade;
     constructor(aid) {
@@ -647,6 +635,7 @@ export class AUNClient {
             throw new ValidationError('AUNClient only accepts an AID object or no argument');
         }
         const inputAid = aid ?? null;
+        this._aidStore = inputAid?._aidStore;
         const rawConfig = {};
         if (inputAid)
             rawConfig.aun_path = inputAid.aunPath;
@@ -782,7 +771,7 @@ export class AUNClient {
             this._safeAsync(this._onGroupStateCommitted(data));
         });
         // 其他事件直接透传
-        for (const evt of ['message.ack', 'storage.object_changed']) {
+        for (const evt of ['message.ack', 'storage.object_changed', 'stream/created', 'stream/closed']) {
             this._dispatcher.subscribe(`_raw.${evt}`, (data) => {
                 this._dispatcher.publish(evt, data);
             });
@@ -796,6 +785,14 @@ export class AUNClient {
     get aid() {
         return this._aid;
     }
+    /** 返回后台刷新任务维护的最新 access token。 */
+    getAccessToken() {
+        const identityToken = String(this._identity?.access_token ?? '').trim();
+        if (identityToken)
+            return identityToken;
+        const sessionToken = String(this._sessionParams?.access_token ?? '').trim();
+        return sessionToken || null;
+    }
     /** AUN Storage VFS 入口 */
     get storage() {
         if (!this._storage)
@@ -842,7 +839,6 @@ export class AUNClient {
         for (const groupAid of Object.keys(groupIndexes)) {
             await this._persistGroupIndexCache(groupAid, {
                 remote_meta: this._groupIndexMetaCache.remoteMeta(this._aid ?? '', groupAid) ?? {},
-                local_etag: this._groupIndexMetaCache.localEtag(this._aid ?? '', groupAid),
             });
         }
     }
@@ -850,8 +846,23 @@ export class AUNClient {
         return this._groupIndexMetaCache.isStale(this._aid ?? '', groupAid);
     }
     markGroupIndexFresh(groupAid, options) {
-        this._groupIndexMetaCache.markFresh(this._aid ?? '', groupAid, options);
-        void this._persistGroupIndexCache(groupAid, { local_etag: String(options.etag ?? '') });
+        const verificationVersion = this._groupIndexMetaCache.markFresh(this._aid ?? '', groupAid, options);
+        const fields = {
+            local_etag: String(options.etag ?? ''),
+            verification_version: verificationVersion,
+        };
+        if (verificationVersion !== 1) {
+            fields.index_jsonl = '';
+            fields.settings = {};
+            fields.entry_etags = {};
+        }
+        void this._persistGroupIndexCache(groupAid, fields);
+    }
+    /** Mail bridge facade 入口 */
+    get mail() {
+        if (!this._mailFacade)
+            this._mailFacade = new MailFacade(this);
+        return this._mailFacade;
     }
     getGroupIndexRemoteMeta(groupAid) {
         return this._groupIndexMetaCache.remoteMeta(this._aid ?? '', groupAid);
@@ -868,6 +879,9 @@ export class AUNClient {
         return this._groupIndexMetaCache.cachedSettingsByEntries(this._aid ?? '', groupAid, keys.map((item) => String(item)), entries);
     }
     cacheGroupIndexSettings(groupAid, settings, options) {
+        if (!Array.isArray(options?.entries) || !String(options?.etag ?? '').trim()) {
+            return Promise.resolve();
+        }
         this._groupIndexMetaCache.cacheSettings(this._aid ?? '', groupAid, settings, options);
         const entryEtags = {};
         for (const item of options?.entries ?? []) {
@@ -876,6 +890,7 @@ export class AUNClient {
                 entryEtags[key] = String(item.etag ?? '');
         }
         const fields = {
+            verification_version: 1,
             settings,
             entry_etags: entryEtags,
             remote_meta: this._groupIndexMetaCache.remoteMeta(this._aid ?? '', groupAid) ?? {},
@@ -906,6 +921,7 @@ export class AUNClient {
             local_etag: record.local_etag,
             settings: record.settings,
             entry_etags: record.entry_etags,
+            verification_version: record.verification_version,
         });
     }
     async _persistGroupIndexCache(groupAid, fields) {
@@ -920,6 +936,7 @@ export class AUNClient {
             local_etag: record.local_etag,
             settings: record.settings,
             entry_etags: record.entry_etags,
+            verification_version: record.verification_version,
         });
     }
     get state() {
@@ -980,6 +997,8 @@ export class AUNClient {
     }
     _resetV2IdentityRuntime() {
         this._v2RuntimeGeneration += 1;
+        // 身份或 V2 会话代次切换时，隔离仍在途的 inline 解密/应用回调。
+        this._delivery?.resetInlineAckState();
         const keyStore = this._v2KeyStore;
         try {
             keyStore?.close?.();
@@ -1004,6 +1023,7 @@ export class AUNClient {
         this._v2PullPending = false;
     }
     _applyAidRuntimeContext(aid) {
+        this._aidStore = aid._aidStore;
         const oldTransport = this._transport;
         try {
             const closeResult = oldTransport?.close?.();
@@ -1111,8 +1131,8 @@ export class AUNClient {
     getPeer(aid) {
         return this._peerDirectory.getPeer(aid);
     }
-    async lookupPeer(aid) {
-        return this._peerDirectory.lookupPeer(aid);
+    async lookupPeer(aid, certFingerprint) {
+        return this._peerDirectory.lookupPeer(aid, certFingerprint);
     }
     peers() {
         return this._peerDirectory.peers();
@@ -1169,14 +1189,102 @@ export class AUNClient {
             return;
         await this._handleTransportDisconnect(err);
     }
-    async createGroup(params = {}) {
+    async _recoverIdentityAdmission(err, _method = '', params = {}) {
+        if (!(err instanceof AUNError) || err.code !== -32003)
+            return false;
+        const message = String(err.message ?? '').trim();
+        const groupCertPrefix = 'valid group identity certificate is required for ';
+        if (message.toLowerCase().startsWith(groupCertPrefix)) {
+            const fallback = message.slice(groupCertPrefix.length).trim();
+            const store = this._aidStore;
+            const groupId = String(params.group_id ?? params.groupId ?? params.group_aid ?? params.groupAid ?? fallback).trim();
+            if (!groupId || !store)
+                return false;
+            try {
+                await this._runGroupIdentityOperation(groupId, () => this.bindGroupAid({ group_id: groupId }, { aidStore: store }));
+            }
+            catch {
+                return false;
+            }
+            return true;
+        }
+        const groupMDPrefix = 'valid group agent.md is required for ';
+        if (message.toLowerCase().startsWith(groupMDPrefix)) {
+            const groupAid = message.slice(groupMDPrefix.length).trim();
+            const store = this._aidStore;
+            if (!groupAid || !store)
+                return false;
+            const loaded = await store.load(groupAid);
+            if (!loaded.ok || !loaded.data?.aid?.isPrivateKeyValid())
+                return false;
+            const ownerAid = String(this._aid ?? this._currentAid?.aid ?? '').trim();
+            if (!ownerAid)
+                return false;
+            await this._runGroupIdentityOperation(groupAid, () => this._uploadGroupAgentMd(store, groupAid, {}, {}, ownerAid));
+            return true;
+        }
+        const agentPrefix = 'valid agent.md is required for ';
+        if (!message.toLowerCase().startsWith(agentPrefix))
+            return false;
+        const target = message.slice(agentPrefix.length).trim();
+        if (!target || target.toLowerCase() !== String(this._aid ?? '').trim().toLowerCase())
+            return false;
+        await this._agentMdManager.upload(buildDefaultAgentMd(target));
+        return true;
+    }
+    async _runGroupIdentityOperation(groupId, operation) {
+        const aid = String(this._aid ?? this._currentAid?.aid ?? '').trim();
+        const dot = aid.indexOf('.');
+        const key = normalizeGroupId(groupId, { localIssuer: dot >= 0 ? aid.slice(dot + 1) : '' }).toLowerCase();
+        if (!key)
+            return operation();
+        let task = this._groupIdentityOperations.get(key);
+        if (!task) {
+            task = Promise.resolve().then(operation);
+            this._groupIdentityOperations.set(key, task);
+        }
+        try {
+            return await task;
+        }
+        finally {
+            if (this._groupIdentityOperations.get(key) === task)
+                this._groupIdentityOperations.delete(key);
+        }
+    }
+    async createGroup(params = {}, options = {}) {
         if (!isJsonObject(params)) {
             throw new ValidationError('createGroup params must be an object');
         }
+        const store = options.aidStore ?? this._aidStore;
+        if (!store) {
+            throw new ValidationError('createGroup requires aidStore');
+        }
+        this._aidStore = store;
         const payload = { ...params };
-        const groupName = String(payload.group_name ?? payload.groupName ?? '').trim();
-        if (!groupName) {
-            return await this.call('group.create', payload);
+        const isNamed = Boolean(String(payload.group_name ?? '').trim());
+        payload._defer_group_ready_postprocess = true;
+        if (!isNamed) {
+            delete payload.public_key;
+            delete payload.curve;
+            const created = await this.call('group.create', payload);
+            const createdMap = isJsonObject(created) ? created : {};
+            const createdGroup = isJsonObject(createdMap.group) ? createdMap.group : {};
+            const groupId = String(createdGroup.group_id ?? createdGroup.group_aid ?? createdMap.group_id ?? createdMap.group_aid ?? '').trim();
+            if (!groupId) {
+                throw new ValidationError('group.create response missing group.group_id');
+            }
+            const bindParams = { group_id: groupId };
+            for (const key of ['name', 'description', 'group_description', 'group_agent_md', 'groupAgentMd', 'content']) {
+                if (key in payload)
+                    bindParams[key] = payload[key];
+            }
+            const bound = await this._runGroupIdentityOperation(groupId, () => this.bindGroupAid(bindParams, { aidStore: store }));
+            const boundMap = isJsonObject(bound) ? bound : {};
+            const boundGroup = isJsonObject(boundMap.group) ? boundMap.group : {};
+            const result = { ...createdMap, ...boundMap, group: { ...createdGroup, ...boundGroup } };
+            const postprocessParams = { ...payload };
+            delete postprocessParams._defer_group_ready_postprocess;
+            return await this._groupState.postprocessResult('group.create', postprocessParams, result);
         }
         const keyPair = await new CryptoProvider().generateIdentity();
         payload.public_key = keyPair.public_key_der_b64;
@@ -1188,30 +1296,63 @@ export class AUNClient {
         const groupAid = String(group.group_aid ?? resultMap.group_aid ?? '').trim();
         const certPem = String(aidCert.cert ?? aidCert.cert_pem ?? resultMap.cert ?? resultMap.cert_pem ?? '').trim();
         if (!groupAid || !certPem) {
-            throw new ValidationError('group.create named group response missing group.group_aid or aid_cert.cert');
+            throw new ValidationError('group.create response missing group.group_aid or aid_cert.cert');
         }
-        const store = new AIDStore({
-            aunPath: this.configModel.aunPath,
-            encryptionSeed: this.configModel.seedPassword ?? '',
-            slotId: this._slotId,
-            rootCaPem: this.configModel.rootCaPem,
-            verifySsl: this.configModel.verifySsl,
+        const imported = await store.importGroupIdentity(groupAid, {
+            private_key_pem: keyPair.private_key_pem,
+            public_key_der_b64: keyPair.public_key_der_b64,
+            curve: keyPair.curve,
+            cert_pem: certPem,
         });
-        try {
-            const imported = await store.importGroupIdentity(groupAid, {
-                private_key_pem: keyPair.private_key_pem,
-                public_key_der_b64: keyPair.public_key_der_b64,
-                curve: keyPair.curve,
-                cert_pem: certPem,
-            });
-            if (!imported.ok) {
-                throw new ValidationError(imported.error.message);
-            }
+        if (!imported.ok) {
+            throw new ValidationError(imported.error.message);
         }
-        finally {
-            store.close();
+        const uploaderAid = String(this._aid ?? this._currentAid?.aid ?? '').trim();
+        if (!uploaderAid) {
+            throw new ValidationError('createGroup requires current owner AID for group agent.md upload');
+        }
+        await this._uploadGroupAgentMd(store, groupAid, payload, group, uploaderAid);
+        const postprocessParams = { ...payload };
+        delete postprocessParams._defer_group_ready_postprocess;
+        return await this._groupState.postprocessResult('group.create', postprocessParams, result);
+    }
+    _groupAgentMdContent(groupAid, params = {}, group = {}) {
+        const explicit = params.group_agent_md ?? params.groupAgentMd ?? params.content;
+        if (explicit !== undefined && explicit !== null)
+            return String(explicit);
+        const value = (...keys) => {
+            for (const source of [group, params]) {
+                for (const key of keys) {
+                    const candidate = String(source[key] ?? '').trim();
+                    if (candidate)
+                        return candidate;
+                }
+            }
+            return '';
+        };
+        const name = value('name', 'group_name', 'title') || groupAid;
+        const normalizedDescription = (value('description', 'group_description') || `AUN group ${name}`)
+            .split(/\s+/).filter(Boolean).join(' ');
+        const description = Array.from(normalizedDescription).slice(0, 100).join('');
+        return [
+            '---\n',
+            `aid: ${JSON.stringify(groupAid)}\n`,
+            `name: ${JSON.stringify(name)}\n`,
+            'type: "group"\n',
+            'version: "1.0.0"\n',
+            `description: ${JSON.stringify(description)}\n`,
+            '---\n\n',
+            `# ${name}\n`,
+        ].join('');
+    }
+    async _uploadGroupAgentMd(store, groupAid, params, group, uploaderAid) {
+        if (typeof store.uploadAgentMd !== 'function') {
+            throw new ValidationError('group agent.md upload is unavailable');
+        }
+        const uploaded = await store.uploadAgentMd(groupAid, this._groupAgentMdContent(groupAid, params, group), { uploaderAid });
+        if (!uploaded.ok) {
+            throw new ValidationError(`group agent.md upload failed: ${uploaded.error.message}`);
         }
-        return result;
     }
     async bindGroupAid(params = {}, options = {}) {
         if (!isJsonObject(params)) {
@@ -1221,6 +1362,7 @@ export class AUNClient {
         if (!store) {
             throw new ValidationError('bindGroupAid requires aidStore');
         }
+        this._aidStore = store;
         const groupId = String(params.group_id ?? params.group_aid ?? '').trim();
         const keystore = store._keystore;
         let keyPair = null;
@@ -1268,6 +1410,11 @@ export class AUNClient {
         if (!imported.ok) {
             throw new ValidationError(imported.error.message);
         }
+        const uploaderAid = String(this._aid ?? this._currentAid?.aid ?? '').trim();
+        if (!uploaderAid) {
+            throw new ValidationError('bindGroupAid requires current owner AID for group agent.md upload');
+        }
+        await this._uploadGroupAgentMd(store, groupAid, payload, group, uploaderAid);
         // 落盘成功，清除 pending 槽位
         if (groupId && keystore && typeof keystore.clearPendingGroupBind === 'function') {
             await keystore.clearPendingGroupBind(groupId);
@@ -1289,7 +1436,7 @@ export class AUNClient {
         let groupAid = String(params.group_aid ?? '').trim();
         if (!groupAid) {
             const info = await this.call('group.get_info', { group_id: groupId, required: ['member'] });
-            groupAid = String(info?.group_aid ?? '').trim();
+            groupAid = String(info?.group_aid ?? info?.group?.group_aid ?? '').trim();
         }
         if (!groupAid) {
             throw new ValidationError('renewGroupAid: unable to determine group_aid');
@@ -1357,6 +1504,11 @@ export class AUNClient {
         if (!imported.ok) {
             throw new ValidationError(`renewGroupAid failed to persist group identity: ${imported.error.message}`);
         }
+        const uploaderAid = String(this._aid ?? this._currentAid?.aid ?? '').trim();
+        if (!uploaderAid) {
+            throw new ValidationError('renewGroupAid requires current owner AID for group agent.md upload');
+        }
+        await this._uploadGroupAgentMd(store, returnedGroupAid, payload, group, uploaderAid);
         return result;
     }
     async startGroupTransfer(params = {}, options = {}) {
@@ -1375,7 +1527,7 @@ export class AUNClient {
         let groupAid = String(params.group_aid ?? '').trim();
         if (!groupAid) {
             const info = await this.call('group.get_info', { group_id: groupId, required: ['member'] });
-            groupAid = String(info?.group_aid ?? '').trim();
+            groupAid = String(info?.group_aid ?? info?.group?.group_aid ?? '').trim();
         }
         if (!groupAid) {
             throw new ValidationError('startGroupTransfer: unable to determine group_aid');
@@ -1423,7 +1575,7 @@ export class AUNClient {
         let groupAid = String(params.group_aid ?? '').trim();
         if (!groupAid) {
             const info = await this.call('group.get_info', { group_id: groupId, required: ['member'] });
-            groupAid = String(info?.group_aid ?? '').trim();
+            groupAid = String(info?.group_aid ?? info?.group?.group_aid ?? '').trim();
         }
         if (!groupAid) {
             throw new ValidationError('completeGroupTransfer: unable to determine group_aid');
@@ -1471,6 +1623,11 @@ export class AUNClient {
         if (!imported.ok) {
             throw new ValidationError(imported.error.message);
         }
+        const uploaderAid = String(this._aid ?? this._currentAid?.aid ?? '').trim();
+        if (!uploaderAid) {
+            throw new ValidationError('completeGroupTransfer requires current owner AID for group agent.md upload');
+        }
+        await this._uploadGroupAgentMd(store, returnedGroupAid, payload, group, uploaderAid);
         return result;
     }
     static _notifyParamsSizeOk(params) {
@@ -1539,15 +1696,16 @@ export class AUNClient {
             const eventMethod = AUNClient._validateNotifyEventMethod(method);
             // 校验目标 Group ID 格式
             validateGroupIDFormat(targetGroupId, 'notify.group_id');
-            const normalizedGroupId = normalizeGroupId(targetGroupId);
-            if (!normalizedGroupId) {
+            if (!targetGroupId) {
                 throw new ValidationError('group_id is required for group notify');
             }
             const routeParams = {
-                group_aid: normalizedGroupId,
-                group_id: normalizedGroupId,
+                group_id: targetGroupId,
                 deliver: { method: eventMethod, params: payload },
             };
+            const explicitGroupAid = String(options.group_aid ?? options.groupAid ?? '').trim();
+            if (explicitGroupAid)
+                routeParams.group_aid = explicitGroupAid;
             if (ttl !== undefined)
                 routeParams.ttl_ms = ttl;
             await this._transport.notify('notification/group.route', routeParams);
@@ -1564,17 +1722,26 @@ export class AUNClient {
     }
     async _callRawV2Rpc(method, params) {
         const p = { ...(params ?? {}) };
-        const rpcBackground = Boolean(p._rpc_background) || this._backgroundRpcDepth > 0;
+        const forceForeground = Boolean(p._rpc_foreground);
+        const rpcBackground = !forceForeground
+            && (Boolean(p._rpc_background) || this._backgroundRpcDepth > 0);
+        delete p._rpc_foreground;
         delete p._rpc_background;
         delete p._pull_gate_locked;
         delete p._skip_auto_ack;
         delete p.skip_auto_ack;
         delete p._group_cursor_params;
-        if (method.startsWith('group.') && p.group_aid !== undefined && p.group_aid !== null) {
-            p.group_aid = normalizeGroupId(String(p.group_aid)) || String(p.group_aid);
-        }
-        else if (method.startsWith('group.') && p.group_id !== undefined && p.group_id !== null) {
-            p.group_aid = normalizeGroupId(String(p.group_id)) || String(p.group_id);
+        if (method.startsWith('group.')) {
+            const rawGroupAid = String(p.group_aid ?? p.groupAid ?? '').trim();
+            const rawGroupId = String(p.group_id ?? p.groupId ?? '').trim();
+            if (rawGroupId)
+                p.group_id = rawGroupId;
+            else if (rawGroupAid)
+                p.group_id = rawGroupAid;
+            if (rawGroupAid)
+                p.group_aid = rawGroupAid;
+            delete p.groupAid;
+            delete p.groupId;
         }
         if (method.startsWith('group.') && p.device_id === undefined) {
             p.device_id = this._deviceId;
@@ -1678,30 +1845,30 @@ export class AUNClient {
         const trace = `${this._echoTimestamp()} [AUN-SDK.receive] aid=${this._aid ?? '-'} conn_uptime=${uptime}s`;
         msg.payload = { ...payload, text: payload.text + '\n' + trace };
     }
-    async _drainOrderedMessages(ns, beforeSeq) {
-        await this._delivery.drainOrderedMessages(ns, beforeSeq);
+    async _drainOrderedMessages(ns, beforeSeq, pullResponse = false, persist = true) {
+        await this._delivery.drainOrderedMessages(ns, beforeSeq, pullResponse, persist);
     }
     async _publishOrderedMessage(event, ns, seq, payload) {
         return this._delivery.publishOrderedMessage(event, ns, seq, payload);
     }
-    async _publishPulledMessage(event, ns, seq, payload) {
-        return this._delivery.publishPulledMessage(event, ns, seq, payload);
+    async _publishPulledMessage(event, ns, seq, payload, persist = true) {
+        return this._delivery.publishPulledMessage(event, ns, seq, payload, persist);
     }
     _extractGroupIdFromResult(result) {
         const group = isJsonObject(result.group) ? result.group : null;
-        const gid = group ? String(group.group_aid ?? group.group_id ?? '') : '';
+        const gid = group ? String(group.group_id ?? group.groupId ?? group.group_aid ?? group.groupAid ?? '') : '';
         if (gid)
             return gid;
-        const directGid = String(result.group_aid ?? result.group_id ?? '');
+        const directGid = String(result.group_id ?? result.groupId ?? result.group_aid ?? result.groupAid ?? '');
         if (directGid)
             return directGid;
         const member = isJsonObject(result.member) ? result.member : null;
-        return member ? String(member.group_aid ?? member.group_id ?? '') : '';
+        return member ? String(member.group_id ?? member.groupId ?? member.group_aid ?? member.groupAid ?? '') : '';
     }
     async _onRawGroupChanged(data) {
         const tStart = Date.now();
         const action = String(data?.action ?? '');
-        const groupIdInit = String(data?.group_aid ?? data?.group_id ?? '');
+        const groupIdInit = String(data?.group_id ?? data?.group_aid ?? '');
         this._clientLog.debug(`_onRawGroupChanged enter: group_id=${groupIdInit} action=${action}`);
         try {
             if (isJsonObject(data)) {
@@ -1717,7 +1884,7 @@ export class AUNClient {
                         d._verified = this._isEventSignatureVerified(verified);
                     }
                 }
-                const groupId = (d.group_aid ?? d.group_id ?? '');
+                const groupId = (d.group_id ?? d.group_aid ?? '');
                 await this._delivery.handleGroupChangedEventSeq(d, groupId);
             }
             else {
@@ -1923,8 +2090,10 @@ export class AUNClient {
         await this._rpcPipeline.signClientOperation(method, params);
     }
     // ── 内部：连接 ────────────────────────────────────
-    async _connectOnce(params, allowReauth) {
+    async _connectOnce(params, allowReauth, reconnectOwner, connectionOwner) {
         const tStart = Date.now();
+        connectionOwner ??= this._connectAbort ?? undefined;
+        this._lifecycle.assertConnectionAttemptOwner(connectionOwner);
         this._clientLog.debug(`_connectOnce enter: allow_reauth=${allowReauth}`);
         try {
             const gatewayUrl = this._resolveGateway(params);
@@ -1937,8 +2106,12 @@ export class AUNClient {
             // 避免 reader 把积压 push 交给空 tracker 的 handler，触发 S2 历史 gap 误补拉。
             this._refreshSeqTrackerContext();
             await this._restoreSeqTrackerState();
+            this._assertReconnectOwner(reconnectOwner);
+            this._lifecycle.assertConnectionAttemptOwner(connectionOwner);
             try {
                 const challenge = await this._transport.connect(gatewayUrl);
+                this._assertReconnectOwner(reconnectOwner);
+                this._lifecycle.assertConnectionAttemptOwner(connectionOwner);
                 this._state = 'authenticating';
                 if (allowReauth) {
                     const authContext = await this._auth.connectSession(this._transport, challenge, gatewayUrl, {
@@ -1950,6 +2123,8 @@ export class AUNClient {
                         shortTtlMs: Number(params.short_ttl_ms ?? 0),
                         extraInfo: params.extra_info,
                     });
+                    this._assertReconnectOwner(reconnectOwner);
+                    this._lifecycle.assertConnectionAttemptOwner(connectionOwner);
                     if (isJsonObject(authContext)) {
                         const auth = authContext;
                         const identity = auth.identity;
@@ -1974,7 +2149,10 @@ export class AUNClient {
                         shortTtlMs: Number(params.short_ttl_ms ?? 0),
                         extraInfo: params.extra_info,
                     });
+                    this._assertReconnectOwner(reconnectOwner);
+                    this._lifecycle.assertConnectionAttemptOwner(connectionOwner);
                     await this._syncIdentityAfterConnect(String(params.access_token));
+                    this._assertReconnectOwner(reconnectOwner);
                     if (isJsonObject(hello) && 'heartbeat_interval' in hello) {
                         this._applyServerHeartbeatInterval(hello.heartbeat_interval, 'auth');
                     }
@@ -1982,23 +2160,57 @@ export class AUNClient {
             }
             catch (err) {
                 // P1-19: 首连失败时重置状态，避免半连接残留
-                this._state = 'standby';
+                if ((!reconnectOwner || this._ownsReconnect(reconnectOwner))
+                    && (!connectionOwner || this._lifecycle.ownsConnectionAttempt(connectionOwner))
+                    && !this._closing) {
+                    this._state = 'standby';
+                }
                 try {
                     await this._transport.close();
                 }
                 catch { /* 忽略关闭错误 */ }
                 throw err;
             }
+            this._assertReconnectOwner(reconnectOwner);
+            this._lifecycle.assertConnectionAttemptOwner(connectionOwner);
+            if (!this._transport.isConnected()) {
+                throw new ConnectionError('websocket disconnected during authentication');
+            }
+            this._serverKicked = false;
+            this._lastDisconnectInfo = null;
             this._state = 'connected';
             this._connectedAt = Date.now();
-            await this._dispatcher.publish('state_change', {
+            if (Array.isArray(params.gateways)) {
+                this._gatewayCandidates = [...new Set(params.gateways
+                        .map((item) => String(item ?? '').trim()).filter(Boolean))];
+            }
+            else if (gatewayUrl) {
+                this._gatewayCandidates = [gatewayUrl];
+            }
+            const statePayload = {
                 state: this._publicState(this._state),
                 gateway: gatewayUrl,
-            });
+            };
+            if (reconnectOwner) {
+                if (!await this._publishReconnectEvent(reconnectOwner, 'state_change', statePayload)) {
+                    throw new ConnectionError('reconnect attempt superseded');
+                }
+            }
+            else if (connectionOwner) {
+                if (!await this._lifecycle.publishConnectionEvent(connectionOwner, 'state_change', statePayload)) {
+                    throw new StateError('connection attempt superseded');
+                }
+            }
+            else {
+                await this._dispatcher.publish('state_change', statePayload);
+            }
+            this._assertReconnectOwner(reconnectOwner);
+            this._lifecycle.assertConnectionAttemptOwner(connectionOwner);
             if (this._seqTrackerContext !== this._currentSeqTrackerContext()) {
                 this._refreshSeqTrackerContext();
                 await this._restoreSeqTrackerState();
             }
+            this._lifecycle.assertConnectionAttemptOwner(connectionOwner);
             this._startBackgroundTasks();
             const connectionKind = String(params.connection_kind ?? 'long');
             const isShortConnection = connectionKind === 'short';
@@ -2007,6 +2219,8 @@ export class AUNClient {
                 && (!isShortConnection || hasExplicitBackgroundSync);
             if (!isShortConnection) {
                 await this._v2E2EE.onConnected({ backgroundSync: backgroundSyncEnabled });
+                this._assertReconnectOwner(reconnectOwner);
+                this._lifecycle.assertConnectionAttemptOwner(connectionOwner);
             }
             else {
                 this._clientLog.debug('V2 session init deferred for short connection');
@@ -2023,26 +2237,43 @@ export class AUNClient {
         }
     }
     _resolveGateway(params) {
+        const explicitGateway = String(params.gateway ?? '').trim();
+        if (explicitGateway)
+            return explicitGateway;
         const gateways = this._resolveGateways(params);
         return gateways[0];
     }
     async _resolveGatewayForAid(aid) {
+        const gateways = await this._resolveGatewayCandidatesForAid(aid);
+        return gateways[0];
+    }
+    async _resolveGatewayCandidatesForAid(aid) {
         const target = String(aid ?? this._aid ?? '').trim();
         if (!target)
             throw new StateError('gateway discovery requires a loaded AID');
-        if (this._gatewayUrl)
-            return this._gatewayUrl;
+        if (this._gatewayCandidates.length > 0)
+            return [...this._gatewayCandidates];
+        if (this._gatewayUrl) {
+            this._gatewayCandidates = [this._gatewayUrl];
+            return [...this._gatewayCandidates];
+        }
         try {
             const getMetadata = this._tokenStore.getMetadata;
+            const rawList = typeof getMetadata === 'function'
+                ? String(await getMetadata.call(this._tokenStore, target, 'gateway_urls') ?? '').trim()
+                : '';
+            const cachedList = rawList ? JSON.parse(rawList) : [];
             const raw = typeof getMetadata === 'function'
                 ? String(await getMetadata.call(this._tokenStore, target, 'gateway_url') ?? '').trim()
                 : '';
-            if (raw) {
-                const gateway = raw.startsWith('"') && raw.endsWith('"') ? String(JSON.parse(raw)).trim() : raw;
-                if (gateway) {
-                    this._gatewayUrl = gateway;
-                    return gateway;
-                }
+            const candidates = Array.isArray(cachedList)
+                ? cachedList.map((item) => String(item ?? '').trim()).filter(Boolean)
+                : [];
+            const gateway = candidates[0] ?? (raw.startsWith('"') && raw.endsWith('"') ? String(JSON.parse(raw)).trim() : raw);
+            if (gateway) {
+                this._gatewayCandidates = [...new Set([gateway, ...candidates])];
+                this._gatewayUrl = this._gatewayCandidates[0];
+                return [...this._gatewayCandidates];
             }
         }
         catch {
@@ -2058,18 +2289,24 @@ export class AUNClient {
         let lastError = null;
         for (const url of candidates) {
             try {
-                const gateway = await this._discovery.discover(url);
+                const discovered = await this._discovery.discoverAll(url);
+                const gatewayUrls = [...new Set(discovered.map((item) => String(item ?? '').trim()).filter(Boolean))];
+                if (gatewayUrls.length === 0)
+                    throw new ValidationError('gateway discovery returned no candidates');
+                const gateway = gatewayUrls[0];
+                this._gatewayCandidates = gatewayUrls;
                 this._gatewayUrl = gateway;
                 try {
                     const setMetadata = this._tokenStore.setMetadata;
                     if (typeof setMetadata === 'function') {
                         await setMetadata.call(this._tokenStore, target, 'gateway_url', gateway);
+                        await setMetadata.call(this._tokenStore, target, 'gateway_urls', JSON.stringify(gatewayUrls));
                     }
                 }
                 catch {
                     // 缓存写入失败不影响连接。
                 }
-                return gateway;
+                return [...gatewayUrls];
             }
             catch (err) {
                 lastError = err;
@@ -2088,7 +2325,9 @@ export class AUNClient {
                 throw new ValidationError('relay topology is not implemented in the Browser SDK');
             }
         }
-        const gw = params.gateway ?? params.gateways;
+        const gw = Array.isArray(params.gateways) && params.gateways.length > 0
+            ? params.gateways
+            : params.gateway;
         if (Array.isArray(gw)) {
             const urls = gw.map((g) => String(g ?? '')).filter((u) => u.length > 0);
             if (urls.length > 0)
@@ -2118,7 +2357,13 @@ export class AUNClient {
     _normalizeConnectParams(params) {
         const request = { ...params };
         const accessToken = String(request.access_token ?? '');
-        const gateway = String(request.gateway ?? this._gatewayUrl ?? '');
+        const rawGateways = request.gateways;
+        const normalizedGateways = Array.isArray(rawGateways)
+            ? [...new Set(rawGateways.map((item) => String(item ?? '').trim()).filter(Boolean))]
+            : [];
+        if (normalizedGateways.length > 0)
+            request.gateways = normalizedGateways;
+        const gateway = String(request.gateway ?? normalizedGateways[0] ?? this._gatewayUrl ?? '');
         if (!gateway)
             throw new StateError('connect requires non-empty gateway');
         if (accessToken)
@@ -2190,9 +2435,6 @@ export class AUNClient {
         if ('auto_reconnect' in params) {
             options.auto_reconnect = Boolean(params.auto_reconnect);
         }
-        if ('heartbeat_interval' in params) {
-            options.heartbeat_interval = Number(params.heartbeat_interval);
-        }
         if ('token_refresh_before' in params) {
             options.token_refresh_before = Number(params.token_refresh_before);
         }
@@ -2208,10 +2450,9 @@ export class AUNClient {
     }
     // ── 内部：后台任务 ────────────────────────────────
     _startBackgroundTasks() {
-        // 短连接不启动 heartbeat 与 token 刷新（生命周期短，不需要长期会话维护）；
-        // auto_reconnect 仍允许，由 _sessionOptions.auto_reconnect 决定
+        // WebSocket Ping/Pong 由 Gateway 与传输层处理；SDK 不发送 RPC 心跳。
+        // 短连接生命周期短，不需要 token 刷新。
         if (this._sessionOptions?.connection_kind !== 'short') {
-            this._startHeartbeat();
             this._startTokenRefresh();
         }
         // V2 内存缓存定时清理（每小时扫描过期条目）
@@ -2252,56 +2493,19 @@ export class AUNClient {
     }
     /** 心跳定时器 */
     _startHeartbeat() {
-        if (this._heartbeatTimer !== null)
-            return;
-        const interval = clampHeartbeatInterval(this._sessionOptions.heartbeat_interval ?? DEFAULT_SESSION_OPTIONS.heartbeat_interval);
-        if (interval <= 0)
-            return;
-        // M25: 把连续失败阈值从 3 次收窄到 2 次。既能容忍一次网络抖动/GC 暂停，
-        // 又把半开连接的检测延迟从 3 个心跳周期降到 2 个，避免 RPC 长时间挂起。
-        // 真正的 socket 死亡由 ws.on('close') 立即触发 _handleTransportDisconnect，
-        // 不依赖此心跳路径。
-        let consecutiveFailures = 0;
-        const maxFailures = 2;
-        this._heartbeatTimer = setInterval(async () => {
-            if (this.state !== ConnectionState.READY || this._closing)
-                return;
-            try {
-                const pong = await this._transport.call('meta.ping', {});
-                this._heartbeatCount++;
-                consecutiveFailures = 0;
-                // 服务端可在 pong 中下发新的 heartbeat_interval（秒，0=关闭）
-                if (isJsonObject(pong) && 'heartbeat_interval' in pong) {
-                    this._applyServerHeartbeatInterval(pong.heartbeat_interval, 'pong');
-                }
-            }
-            catch (exc) {
-                consecutiveFailures++;
-                this._clientLog.warn(`heartbeat failed (${consecutiveFailures}/${maxFailures}): ${String(exc)}`);
-                this._dispatcher.publish('connection.error', { error: formatCaughtError(exc) });
-                if (consecutiveFailures >= maxFailures) {
-                    this._clientLog.warn(`consecutive ${maxFailures}  heartbeat failed, trigger disconnect reconnect`);
-                    this._handleTransportDisconnect(exc instanceof Error ? exc : new Error(String(exc)));
-                }
-            }
-        }, interval * 1000);
-    }
-    /** 服务端通过 hello/pong 下发 heartbeat_interval；clamp 后写入 session_options 并按需重启心跳。 */
-    _applyServerHeartbeatInterval(raw, source) {
-        const newInterval = clampHeartbeatInterval(raw);
-        const oldInterval = clampHeartbeatInterval(this._sessionOptions.heartbeat_interval);
-        if (newInterval === oldInterval)
-            return;
-        this._sessionOptions.heartbeat_interval = newInterval;
-        this._clientLog.debug(`heartbeat_interval updated by ${source}: ${oldInterval} -> ${newInterval}`);
-        // 重启定时器以应用新间隔（关闭/启动通过定时器有/无区分）
         if (this._heartbeatTimer !== null) {
             clearInterval(this._heartbeatTimer);
             this._heartbeatTimer = null;
         }
-        if (newInterval > 0 && this.state === ConnectionState.READY && !this._closing) {
-            this._startHeartbeat();
+        this._sessionOptions.heartbeat_interval = 0;
+    }
+    /** 忽略旧 Gateway 的 RPC 心跳配置，固定使用 WebSocket Ping/Pong。 */
+    _applyServerHeartbeatInterval(_raw, _source) {
+        if (this._heartbeatTimer !== null) {
+            clearInterval(this._heartbeatTimer);
+            this._heartbeatTimer = null;
         }
+        this._sessionOptions.heartbeat_interval = 0;
     }
     /** Token 刷新定时器 */
     _startTokenRefresh() {
@@ -2399,7 +2603,7 @@ export class AUNClient {
     }
     // ── 内部：断线重连 ────────────────────────────────
     /** 不重连 close code 集合：认证失败/权限错误/被踢等，重连无意义 */
-    static _NO_RECONNECT_CODES = new Set([4001, 4003, 4008, 4009, 4010, 4011, 4012, 4013, 4014, 4015]);
+    static _NO_RECONNECT_CODES = new Set([4001, 4003, 4008, 4009, 4010, 4011, 4013, 4014, 4015]);
     /** 处理服务端主动断开通知 event/gateway.disconnect
      *
      * 服务端可能附带结构化 detail 字段（如配额超限时含 aid/device_id/slot_id/quota_kind/evicted_by）。
@@ -2411,7 +2615,11 @@ export class AUNClient {
         const reason = obj.reason ?? '';
         const detail = (obj.detail && typeof obj.detail === 'object') ? obj.detail : {};
         this._clientLog.warn(`server initiated disconnect: code=${code}, reason=${reason}, detail=${JSON.stringify(detail)}`);
-        this._serverKicked = true;
+        const reasonText = String(reason ?? '').trim().toLowerCase();
+        const retryable = Number(code) === 4012
+            || reasonText.includes('long_connection_already_exists')
+            || reasonText.includes('long connection already exists');
+        this._serverKicked = !retryable;
         // 缓存最近一次 disconnect 信息，让后续 connection.state(terminal_failed) 也能带 detail
         this._lastDisconnectInfo = { code, reason, detail };
         // 透传给应用层订阅者
@@ -2422,25 +2630,48 @@ export class AUNClient {
             this._clientLog.debug(`publish gateway.disconnect failed: ${exc?.message ?? exc}`);
         }
     }
-    async _handleTransportDisconnect(error, closeCode) {
+    async _handleTransportDisconnect(error, closeCode, initialOptions) {
         if (this._closing || this._state === 'closed')
             return;
+        // 在首个 await 前占位，避免 close/error 与 token 刷新并发启动多条重连链。
+        if (this._reconnectActive)
+            return;
+        this._reconnectActive = true;
+        // 在首个 await 前创建取消控制器，覆盖 disconnect 与清理动作的竞态窗口。
+        const reconnectAbort = new AbortController();
+        this._reconnectAbort = reconnectAbort;
+        // 不等待状态事件或 transport 清理，先隔离已在途的 inline Push 回调。
+        this._delivery.resetInlineAckState();
         this._state = 'standby';
         // 先停止后台任务，避免心跳/token刷新在重连期间继续触发
         this._stopBackgroundTasks();
-        void this._transport.close().catch((exc) => {
+        try {
+            await this._transport.close();
+        }
+        catch (exc) {
             this._clientLog.debug(`transport cleanup skipped: ${formatCaughtError(exc)}`);
-        });
+        }
         await this._dispatcher.publish('state_change', {
             state: this._publicState(this._state),
             error,
         });
-        if (!this._sessionOptions.auto_reconnect)
+        if (reconnectAbort.signal.aborted || this._reconnectAbort !== reconnectAbort || this._closing) {
+            if (this._reconnectAbort === reconnectAbort) {
+                this._reconnectAbort = null;
+                this._reconnectActive = false;
+            }
             return;
-        if (this._reconnectActive)
+        }
+        if (!this._sessionOptions.auto_reconnect) {
+            if (this._reconnectAbort === reconnectAbort) {
+                this._reconnectAbort = null;
+                this._reconnectActive = false;
+            }
             return;
+        }
         // 不重连 close code（认证失败/权限错误/被踢等）或服务端通知断开：抑制重连
-        if (this._serverKicked || (closeCode !== undefined && AUNClient._NO_RECONNECT_CODES.has(closeCode))) {
+        const retryableClose = closeCode === 4012;
+        if ((this._serverKicked && !retryableClose) || (closeCode !== undefined && AUNClient._NO_RECONNECT_CODES.has(closeCode))) {
             this._state = 'terminal_failed';
             const reason = this._serverKicked ? 'server kicked' : `close code ${closeCode}`;
             this._clientLog.warn(`suppress auto-reconnect: ${reason}`);
@@ -2457,16 +2688,99 @@ export class AUNClient {
                 eventPayload.code = disconnectInfo.code;
             }
             await this._dispatcher.publish('state_change', eventPayload);
+            if (this._reconnectAbort === reconnectAbort) {
+                this._reconnectAbort = null;
+                this._reconnectActive = false;
+            }
             return;
         }
         // 1000 = 正常关闭, 1006 = 网络异常断开（无 close frame），其他 code = 服务端主动关闭
         const serverInitiated = closeCode !== undefined && closeCode !== 1000 && closeCode !== 1006;
-        this._reconnectActive = true;
-        this._reconnectAbort = new AbortController();
-        this._safeAsync(this._reconnectLoop(serverInitiated));
+        if (this._closing || reconnectAbort.signal.aborted || this._reconnectAbort !== reconnectAbort) {
+            if (this._reconnectAbort === reconnectAbort) {
+                this._reconnectAbort = null;
+                this._reconnectActive = false;
+            }
+            return;
+        }
+        const reconnectTask = Promise.resolve().then(() => this._reconnectLoop(serverInitiated, reconnectAbort, initialOptions));
+        this._reconnectTask = reconnectTask;
+        this._safeAsync(reconnectTask);
+    }
+    _ownsReconnect(owner) {
+        return Boolean(owner
+            && !owner.signal.aborted
+            && !this._closing
+            && this._reconnectAbort === owner);
     }
-    /** 指数退避 + 固定上限抖动重连循环（默认无限重试，仅在不可重试错误或 close() 或 max_attempts 耗尽时终止） */
-    async _reconnectLoop(serverInitiated = false) {
+    _assertReconnectOwner(owner) {
+        if (owner && !this._ownsReconnect(owner)) {
+            throw new ConnectionError('reconnect attempt superseded');
+        }
+    }
+    async _publishReconnectEvent(owner, event, payload) {
+        if (!this._ownsReconnect(owner))
+            return false;
+        this._reconnectEventDispatchDepth += 1;
+        try {
+            await this._dispatcher.publish(event, payload);
+        }
+        finally {
+            this._reconnectEventDispatchDepth -= 1;
+        }
+        return this._ownsReconnect(owner);
+    }
+    async _cancelReconnectAndWait() {
+        const owner = this._reconnectAbort;
+        const task = this._reconnectTask;
+        if (!owner && !task && !this._reconnectActive)
+            return;
+        owner?.abort();
+        try {
+            await this._transport.close();
+        }
+        catch (exc) {
+            this._clientLog.debug(`reconnect cancellation transport cleanup skipped: ${formatCaughtError(exc)}`);
+        }
+        // state_change handler 内等待其所属重连任务会自锁；该路径由事件返回后的
+        // owner 复核负责收尾，且事件回调期间尚未进入下一次 transport 操作。
+        if (task && this._reconnectEventDispatchDepth === 0) {
+            try {
+                await task;
+            }
+            catch (exc) {
+                this._clientLog.debug(`cancelled reconnect task exited with error: ${formatCaughtError(exc)}`);
+            }
+        }
+        if (this._reconnectAbort === owner) {
+            this._reconnectAbort = null;
+            this._reconnectActive = false;
+            this._nextRetryAt = null;
+        }
+        if (this._reconnectTask === task)
+            this._reconnectTask = null;
+    }
+    /** 重连循环入口；无论正常退出还是意外异常，都只清理自己这一代控制器。 */
+    async _reconnectLoop(serverInitiated = false, reconnectAbort = this._reconnectAbort, initialOptions) {
+        let releasedOwnGeneration = false;
+        try {
+            await this._runReconnectLoop(serverInitiated, reconnectAbort, initialOptions);
+        }
+        finally {
+            if (this._reconnectAbort === reconnectAbort) {
+                this._nextRetryAt = null;
+                this._reconnectActive = false;
+                this._reconnectAbort = null;
+                this._reconnectTask = null;
+                releasedOwnGeneration = true;
+            }
+        }
+        if (releasedOwnGeneration && !this._closing && this._state === 'connected' && !this._transport.isConnected()) {
+            await this._handleTransportDisconnect(new ConnectionError('websocket disconnected while reconnect completed'));
+        }
+    }
+    /** 指数退避 + 当前基数抖动重连循环主体。 */
+    async _runReconnectLoop(serverInitiated, reconnectAbort, initialOptions) {
         const retry = { ...this._sessionOptions.retry };
         const maxBaseDelay = clampReconnectDelaySeconds(retry.max_delay, RECONNECT_MAX_BASE_DELAY_SECONDS);
         // M25: max_attempts=0 表示无限重试（与 Go/Python 对齐）
@@ -2476,18 +2790,17 @@ export class AUNClient {
         let delay = clampReconnectDelaySeconds(serverInitiated ? 16.0 : retry.initial_delay, serverInitiated ? 16.0 : 1.0, maxBaseDelay);
         this._retryAttempt = 0;
         this._retryMaxAttempts = maxAttempts;
-        for (let attempt = 1; !this._reconnectAbort?.signal.aborted; attempt++) {
+        for (let attempt = 1; !reconnectAbort?.signal.aborted; attempt++) {
             // R1 fix: max_attempts 检查在循环顶部，覆盖所有路径（含 health-fail）
             if (maxAttempts > 0 && attempt > maxAttempts) {
                 this._state = 'terminal_failed';
                 this._nextRetryAt = null;
-                this._reconnectActive = false;
-                this._reconnectAbort = null;
-                await this._dispatcher.publish('state_change', {
-                    state: this._publicState(this._state),
-                    attempt: attempt - 1,
-                    reason: 'max_attempts_exhausted',
-                });
+                if (reconnectAbort)
+                    await this._publishReconnectEvent(reconnectAbort, 'state_change', {
+                        state: this._publicState(this._state),
+                        attempt: attempt - 1,
+                        reason: 'max_attempts_exhausted',
+                    });
                 return;
             }
             // 先进入 retry_backoff 状态（对齐 Python：先退避再重连）
@@ -2495,35 +2808,52 @@ export class AUNClient {
             const sleepMs = reconnectSleepDelaySeconds(delay, maxBaseDelay) * 1000;
             this._nextRetryAt = new Date(Date.now() + sleepMs);
             this._state = 'retry_backoff';
-            await this._dispatcher.publish('state_change', {
+            if (!reconnectAbort || !await this._publishReconnectEvent(reconnectAbort, 'state_change', {
                 state: this._publicState(this._state),
                 attempt,
                 next_retry_at: this._nextRetryAt.getTime() / 1000,
-            });
+            }))
+                return;
             try {
-                await this._sleep(sleepMs);
+                await this._sleep(sleepMs, reconnectAbort?.signal);
                 this._nextRetryAt = null;
-                if (this._reconnectAbort?.signal.aborted) {
-                    this._reconnectActive = false;
+                if (!this._ownsReconnect(reconnectAbort))
                     return;
-                }
                 // 退避结束，进入 reconnecting 状态
                 this._state = 'reconnecting';
-                await this._dispatcher.publish('state_change', {
+                if (!reconnectAbort || !await this._publishReconnectEvent(reconnectAbort, 'state_change', {
                     state: this._publicState(this._state),
                     attempt,
-                });
-                // 重连前先 GET /health 探测，不健康则跳过本轮
+                }))
+                    return;
+                if (!this._ownsReconnect(reconnectAbort))
+                    return;
+                // /health 仅作旁路诊断，不能阻止实际 WebSocket 重连。
                 if (this._gatewayUrl) {
-                    const healthy = await this._discovery.checkHealth(this._gatewayUrl, 5000);
-                    if (!healthy) {
-                        this._lastError = new Error('gateway health check failed');
-                        this._lastErrorCode = 'gateway_unhealthy';
-                        delay = Math.min(delay * 2, maxBaseDelay);
-                        continue;
-                    }
+                    void this._discovery.checkHealth(this._gatewayUrl, 5000)
+                        .then((healthy) => {
+                        if (!healthy)
+                            this._clientLog.warn(`reconnect health advisory failed: gateway=${this._gatewayUrl}`);
+                    })
+                        .catch((exc) => {
+                        this._clientLog.debug(`reconnect health advisory error: ${exc instanceof Error ? exc.message : String(exc)}`);
+                    });
                 }
                 await this._transport.close();
+                if (!this._ownsReconnect(reconnectAbort))
+                    return;
+                if (initialOptions) {
+                    // 首连失败时没有可复用的 session/gateway，必须重新 discovery + authenticate。
+                    await this._lifecycle.retryInitialConnect(initialOptions, reconnectAbort ?? undefined);
+                    if (!this._ownsReconnect(reconnectAbort))
+                        return;
+                    if (!this._transport.isConnected()) {
+                        throw new ConnectionError('websocket disconnected while initial reconnect completed');
+                    }
+                    this._clientLog.debug(`initial reconnect success: attempt=${attempt}, aid=${this._aid ?? ''}`);
+                    this._nextRetryAt = null;
+                    return;
+                }
                 if (!this._sessionParams) {
                     throw new StateError('missing connect params for reconnect');
                 }
@@ -2545,44 +2875,72 @@ export class AUNClient {
                         this._sessionParams.access_token = '';
                     }
                 }
-                await this._connectOnce(this._sessionParams, true);
+                const candidates = this._orderedReconnectGateways(this._sessionParams);
+                let lastGatewayError = null;
+                let connected = false;
+                for (const gateway of candidates) {
+                    const attemptParams = { ...this._sessionParams, gateway };
+                    try {
+                        await this._connectOnce(attemptParams, true, reconnectAbort ?? undefined);
+                        if (!this._ownsReconnect(reconnectAbort))
+                            return;
+                        if (!this._transport.isConnected()) {
+                            throw new ConnectionError('websocket disconnected while reconnecting');
+                        }
+                        this._sessionParams.gateway = gateway;
+                        connected = true;
+                        break;
+                    }
+                    catch (exc) {
+                        lastGatewayError = exc;
+                        await this._transport.close().catch(() => { });
+                        if (candidates.length > 1) {
+                            this._clientLog.warn(`reconnect gateway failed, trying next: gateway=${gateway}, error=${exc instanceof Error ? exc.message : String(exc)}`);
+                        }
+                        if (!this._shouldRetryReconnect(exc))
+                            throw exc;
+                    }
+                }
+                if (!connected)
+                    throw (lastGatewayError instanceof Error ? lastGatewayError : new ConnectionError('all gateway candidates failed'));
                 this._lastError = null;
                 this._lastErrorCode = null;
                 this._nextRetryAt = null;
-                this._reconnectActive = false;
-                this._reconnectAbort = null;
                 return;
             }
             catch (exc) {
+                if (!this._ownsReconnect(reconnectAbort))
+                    return;
                 this._lastError = exc instanceof Error ? exc : new Error(String(exc));
                 this._lastErrorCode = 'reconnect_failed';
-                await this._dispatcher.publish('connection.error', {
+                if (!reconnectAbort || !await this._publishReconnectEvent(reconnectAbort, 'connection.error', {
                     error: formatCaughtError(exc),
                     attempt,
-                });
+                }))
+                    return;
                 if (!this._shouldRetryReconnect(exc)) {
                     this._state = 'terminal_failed';
                     this._nextRetryAt = null;
-                    this._reconnectActive = false;
-                    this._reconnectAbort = null;
-                    await this._dispatcher.publish('state_change', {
-                        state: this._publicState(this._state),
-                        error: formatCaughtError(exc),
-                        attempt,
-                    });
+                    if (reconnectAbort)
+                        await this._publishReconnectEvent(reconnectAbort, 'state_change', {
+                            state: this._publicState(this._state),
+                            error: formatCaughtError(exc),
+                            attempt,
+                        });
                     return;
                 }
                 delay = Math.min(delay * 2, maxBaseDelay);
             }
         }
-        this._reconnectActive = false;
-        this._reconnectAbort = null;
     }
     /** 判断是否应重试重连 */
     _shouldRetryReconnect(error) {
         if (error instanceof AuthError) {
             const message = String(error.message ?? '').toLowerCase();
-            if (message.includes('aid_login1_failed') || message.includes('aid_login2_failed')) {
+            if (message.includes('long_connection_already_exists')
+                || message.includes('long connection already exists')
+                || message.includes('aid_login1_failed')
+                || message.includes('aid_login2_failed')) {
                 return true;
             }
             return false;
@@ -2591,7 +2949,7 @@ export class AUNClient {
             || error instanceof ValidationError || error instanceof StateError) {
             return false;
         }
-        if (error instanceof ConnectionError)
+        if (error instanceof ConnectionError || error instanceof TimeoutError)
             return true;
         if (error instanceof AUNError)
             return error.retryable;
@@ -2611,39 +2969,32 @@ export class AUNClient {
     _resetSeqTrackingState() {
         void this._saveSeqTrackerState();
         this._resetV2IdentityRuntime();
+        this._v2E2EE.resetForwardCursorState();
         this._seqTracker = new SeqTracker();
         this._seqTrackerContext = null;
         this._gapFillDone.clear();
         this._pushedSeqs.clear();
+        this._pullResponseKeys.clear();
         this._pendingOrderedMsgs.clear();
         this._v2SenderIKPending.clear();
         this._v2SenderIKFetching.clear();
         this._groupSynced.clear();
-        this._onlineUnreadHintQueue.clear();
-        if (this._onlineUnreadHintTimer) {
-            clearTimeout(this._onlineUnreadHintTimer);
-            this._onlineUnreadHintTimer = null;
-        }
-        this._onlineUnreadHintDrainActive = false;
     }
     _refreshSeqTrackerContext() {
         const nextContext = this._currentSeqTrackerContext();
         if (nextContext === this._seqTrackerContext)
             return;
         void this._saveSeqTrackerState();
+        this._v2E2EE.resetForwardCursorState();
         this._seqTracker = new SeqTracker();
+        this._delivery.resetInlineAckState();
         this._gapFillDone.clear();
         this._pushedSeqs.clear();
+        this._pullResponseKeys.clear();
         this._pendingOrderedMsgs.clear();
         this._v2SenderIKPending.clear();
         this._v2SenderIKFetching.clear();
         this._groupSynced.clear();
-        this._onlineUnreadHintQueue.clear();
-        if (this._onlineUnreadHintTimer) {
-            clearTimeout(this._onlineUnreadHintTimer);
-            this._onlineUnreadHintTimer = null;
-        }
-        this._onlineUnreadHintDrainActive = false;
         this._seqTrackerContext = nextContext;
     }
     /** 将 SeqTracker 状态保存到 keystore */
@@ -2653,6 +3004,9 @@ export class AUNClient {
     _persistSeq(ns, forceSeq) {
         return this._delivery.persistSeq(ns, forceSeq);
     }
+    async _commitSeqTrackerState(ns) {
+        await this._delivery.commitSeqTrackerState(ns);
+    }
     _persistRepairedSeq(ns) {
         return this._delivery.persistRepairedSeq(ns);
     }
@@ -2805,6 +3159,9 @@ export class AUNClient {
     async _getV2SenderPubDer(fromAid, senderDeviceId, certFingerprint) {
         return await this._v2E2EE.getV2SenderPubDer(fromAid, senderDeviceId, certFingerprint);
     }
+    async _fetchV2SenderIKOnce(fromAid, senderDeviceId, groupId, certFingerprint) {
+        return await this._v2E2EE.fetchSenderIKOnce(fromAid, senderDeviceId, groupId, certFingerprint);
+    }
     _cacheV2PeerIKFromDevice(dev, fallbackAid = '') {
         const session = this._v2Session;
         if (!session || !isJsonObject(dev))
@@ -2850,11 +3207,17 @@ export class AUNClient {
      *
      * @param upToSeq 确认到此 seq；省略则用当前 contiguous
      */
-    async _ackV2(upToSeq) {
-        return await this._v2E2EE.ackV2(upToSeq);
+    async _ackV2(upToSeq, inlineGeneration) {
+        return await this._v2E2EE.ackV2(upToSeq, inlineGeneration);
     }
-    /** 解密单条 V2 消息（与 Python `_decrypt_v2_message` 对齐）。缺 sender IK 时先入 pending，后台补齐后重试。 */
-    async _decryptV2Message(msg, allowPending = true) {
+    /**
+     * 解密单条 V2 消息（与 Python `_decrypt_v2_message` 对齐）。
+     *
+     * 默认保持 Pull / 普通 Push 的既有行为：缺 sender IK 时入 pending、失败发布
+     * undecryptable 事件、成功消费后触发 SPK 轮换。inline Push 在游标提交和
+     * Head/正文绑定校验前调用本入口时必须显式关闭这些副作用。
+     */
+    async _decryptV2Message(msg, allowPending = true, emitUndecryptable = true, rotateKeys = true, observeAgentMd = true, deferStatus, deferKeyFetch = false) {
         const session = this._v2Session;
         if (!session)
             return null;
@@ -2870,7 +3233,8 @@ export class AUNClient {
             return null;
         }
         const e2eeMeta = v2E2eeMeta(envelope);
-        await this._observeAgentMdFromEnvelope(envelope);
+        if (observeAgentMd)
+            await this._observeAgentMdFromEnvelope(envelope);
         // 确定 spk_id 和 recipient_key_source
         let spkId = '';
         let recipientKeySource = '';
@@ -2920,100 +3284,127 @@ export class AUNClient {
         }
         catch (exc) {
             this._clientLog.warn(`V2 decrypt: SPK lookup failed seq=${String(msg.seq)} spk_id=${spkId}: ${String(exc)}`);
-            try {
-                const event = {
-                    message_id: String(msg.message_id ?? ''),
-                    from: String(msg.from_aid ?? ''),
-                    to: String(msg.to ?? ''),
-                    seq: msg.seq,
-                    timestamp: (msg.t_server ?? msg.timestamp),
-                    device_id: String(msg.device_id ?? ''),
-                    slot_id: String(msg.slot_id ?? ''),
-                    _decrypt_error: String(exc),
-                    _decrypt_stage: 'spk_lookup',
-                    _envelope_type: String(envelope.type ?? ''),
-                    _suite: String(envelope.suite ?? ''),
-                    _spk_id: spkId,
-                };
-                attachV2EnvelopeMetadata(event, e2eeMeta);
-                await this._dispatcher.publish(undecryptableEvent, event);
+            if (allowPending || deferStatus) {
+                const fromAid = String(msg.from_aid ?? '');
+                const senderDeviceId = String(aad.from_device ?? '');
+                if (deferStatus) {
+                    deferStatus.deferred = true;
+                    deferStatus.fromAid = fromAid;
+                    deferStatus.senderDeviceId = senderDeviceId;
+                    deferStatus.groupId = groupIdForKeys;
+                }
+                this._scheduleV2SenderIKPending({
+                    msg,
+                    fromAid,
+                    senderDeviceId,
+                    groupId: groupIdForKeys,
+                    startFetch: !deferKeyFetch,
+                });
+                return null;
+            }
+            if (emitUndecryptable) {
+                try {
+                    const event = {
+                        message_id: String(msg.message_id ?? ''),
+                        from: String(msg.from_aid ?? ''),
+                        to: String(msg.to ?? ''),
+                        seq: msg.seq,
+                        timestamp: (msg.t_server ?? msg.timestamp),
+                        device_id: String(msg.device_id ?? ''),
+                        slot_id: String(msg.slot_id ?? ''),
+                        _decrypt_error: String(exc),
+                        _decrypt_stage: 'spk_lookup',
+                        _envelope_type: String(envelope.type ?? ''),
+                        _suite: String(envelope.suite ?? ''),
+                        _spk_id: spkId,
+                    };
+                    attachV2EnvelopeMetadata(event, e2eeMeta);
+                    await this._dispatcher.publish(undecryptableEvent, event);
+                }
+                catch { /* publish 异常不影响主流程 */ }
             }
-            catch { /* publish 异常不影响主流程 */ }
             return null;
         }
         const fromAid = String(msg.from_aid ?? '');
         const senderDeviceId = String(aad.from_device ?? '');
         const senderCertFingerprint = String(envelope.sender_cert_fingerprint ?? '').trim().toLowerCase();
-        const senderPubDer = await this._getV2SenderPubDer(fromAid, senderDeviceId, senderCertFingerprint);
-        if (!senderPubDer) {
+        let senderPubDer = await this._getV2SenderPubDer(fromAid, senderDeviceId, senderCertFingerprint);
+        if (!senderPubDer && !deferKeyFetch) {
             this._clientLog.warn(`V2 decrypt: no sender IK for ${fromAid} device=${senderDeviceId}`);
-            if (allowPending) {
-                this._scheduleV2SenderIKPending({ msg, fromAid, senderDeviceId, groupId: groupIdForKeys });
+            senderPubDer = await this._fetchV2SenderIKOnce(fromAid, senderDeviceId, groupIdForKeys, senderCertFingerprint);
+        }
+        if (!senderPubDer) {
+            if (allowPending || deferStatus) {
+                if (deferStatus) {
+                    deferStatus.deferred = true;
+                    deferStatus.fromAid = fromAid;
+                    deferStatus.senderDeviceId = senderDeviceId;
+                    deferStatus.groupId = groupIdForKeys;
+                }
+                this._scheduleV2SenderIKPending({ msg, fromAid, senderDeviceId, groupId: groupIdForKeys, startFetch: !deferKeyFetch });
                 return null;
             }
-            try {
-                const event = {
-                    message_id: String(msg.message_id ?? ''),
-                    from: fromAid,
-                    to: String(msg.to ?? ''),
-                    seq: msg.seq,
-                    timestamp: (msg.t_server ?? msg.timestamp),
-                    device_id: String(msg.device_id ?? ''),
-                    slot_id: String(msg.slot_id ?? ''),
-                    _decrypt_error: 'sender_ik_not_found',
-                    _decrypt_stage: 'sender_ik',
-                    _envelope_type: String(envelope.type ?? ''),
-                    _suite: String(envelope.suite ?? ''),
-                };
-                attachV2EnvelopeMetadata(event, e2eeMeta);
-                await this._dispatcher.publish(undecryptableEvent, event);
+            if (emitUndecryptable) {
+                try {
+                    const event = {
+                        message_id: String(msg.message_id ?? ''),
+                        from: fromAid,
+                        to: String(msg.to ?? ''),
+                        seq: msg.seq,
+                        timestamp: (msg.t_server ?? msg.timestamp),
+                        device_id: String(msg.device_id ?? ''),
+                        slot_id: String(msg.slot_id ?? ''),
+                        _decrypt_error: 'sender_ik_not_found',
+                        _decrypt_stage: 'sender_ik',
+                        _envelope_type: String(envelope.type ?? ''),
+                        _suite: String(envelope.suite ?? ''),
+                    };
+                    attachV2EnvelopeMetadata(event, e2eeMeta);
+                    await this._dispatcher.publish(undecryptableEvent, event);
+                }
+                catch { /* publish 异常不影响主流程 */ }
             }
-            catch { /* publish 异常不影响主流程 */ }
             return null;
         }
         let plaintext;
         try {
             plaintext = await decryptMessage(envelope, this._aid ?? '', this._deviceId, ikPriv, spkPriv, senderPubDer);
+            if (plaintext === null)
+                throw new Error('recipient_not_found_or_envelope_verification_failed');
         }
         catch (exc) {
             this._clientLog.warn(`V2 decrypt failed for msg seq=${String(msg.seq)}: ${String(exc)}`);
-            try {
-                const event = {
-                    message_id: String(msg.message_id ?? ''),
-                    from: fromAid,
-                    to: String(msg.to ?? ''),
-                    seq: msg.seq,
-                    timestamp: (msg.t_server ?? msg.timestamp),
-                    device_id: String(msg.device_id ?? ''),
-                    slot_id: String(msg.slot_id ?? ''),
-                    _decrypt_error: String(exc),
-                    _decrypt_stage: 'decrypt',
-                    _envelope_type: String(envelope.type ?? ''),
-                    _suite: String(envelope.suite ?? ''),
-                };
-                attachV2EnvelopeMetadata(event, e2eeMeta);
-                await this._dispatcher.publish(undecryptableEvent, event);
+            if (deferStatus)
+                deferStatus.terminal = true;
+            if (emitUndecryptable) {
+                try {
+                    const event = {
+                        message_id: String(msg.message_id ?? ''),
+                        from: fromAid,
+                        to: String(msg.to ?? ''),
+                        seq: msg.seq,
+                        timestamp: (msg.t_server ?? msg.timestamp),
+                        device_id: String(msg.device_id ?? ''),
+                        slot_id: String(msg.slot_id ?? ''),
+                        _decrypt_error: String(exc),
+                        _decrypt_stage: 'decrypt',
+                        _envelope_type: String(envelope.type ?? ''),
+                        _suite: String(envelope.suite ?? ''),
+                    };
+                    attachV2EnvelopeMetadata(event, e2eeMeta);
+                    await this._dispatcher.publish(undecryptableEvent, event);
+                }
+                catch { /* publish 异常不影响主流程 */ }
             }
-            catch { /* publish 异常不影响主流程 */ }
             return null;
         }
         if (plaintext == null)
             return null;
         // 消费触发 SPK 轮换（fire-and-forget，不阻塞消息处理）
-        if (groupIdForKeys && recipientKeySource === 'group_device_prekey' && session.isLastUploadedGroupSPK(groupIdForKeys, spkId)) {
-            this._v2E2EE.scheduleGroupSpkRotation(groupIdForKeys, { reason: 'group_spk_consumed' });
-        }
-        else if (groupIdForKeys && recipientKeySource === 'peer_device_prekey') {
-            this._v2E2EE.scheduleGroupSpkRegistrationAfterPeerFallback(groupIdForKeys);
-        }
-        else if (!groupIdForKeys && session.isLastUploadedSPK(spkId)) {
-            const callFn = async (method, params) => this.call(method, params);
-            session.rotateSPK(callFn).catch(exc => {
-                this._clientLog.debug(`V2 SPK rotation failed (non-fatal): ${exc}`);
-            });
-        }
+        if (rotateKeys)
+            this._scheduleV2KeyRotationForMessage(msg, envelope);
         const e2ee = v2E2eeMeta(envelope);
-        const result = {
+        let result = {
             message_id: String(msg.message_id ?? ''),
             from: fromAid,
             to: this._aid ?? '',
@@ -3031,8 +3422,67 @@ export class AUNClient {
             result.slot_id = msg.slot_id;
         attachGatewayProximity(result, msg);
         attachV2EnvelopeMetadata(result, e2ee);
+        if (groupIdForKeys)
+            result = normalizeGroupMentionMode(result, msg, envelope);
         return result;
     }
+    _scheduleV2KeyRotationForMessage(msg, envelope) {
+        const session = this._v2Session;
+        if (!session)
+            return;
+        let spkId = '';
+        let recipientKeySource = '';
+        const recipientObj = envelope.recipient;
+        if (recipientObj && typeof recipientObj === 'object') {
+            spkId = String(recipientObj.spk_id ?? '');
+            recipientKeySource = String(recipientObj.key_source ?? '');
+        }
+        else if (Array.isArray(envelope.recipients)) {
+            spkId = String(msg.spk_id ?? '');
+            for (const row of envelope.recipients) {
+                if (Array.isArray(row) && row.length >= 6 && row[0] === this._aid && (row[1] === this._deviceId || row[1] === '')) {
+                    if (!spkId)
+                        spkId = String(row[5] ?? '');
+                    recipientKeySource = row.length > 3 ? String(row[3] ?? '') : '';
+                    break;
+                }
+            }
+        }
+        const aad = isJsonObject(envelope.aad) ? envelope.aad : {};
+        const groupId = String(msg.group_id ?? aad.group_id ?? envelope.group_id ?? '').trim();
+        if (groupId && recipientKeySource === 'group_device_prekey' && session.isLastUploadedGroupSPK(groupId, spkId)) {
+            this._v2E2EE.scheduleGroupSpkRotation(groupId, { reason: 'group_spk_consumed' });
+        }
+        else if (groupId && recipientKeySource === 'peer_device_prekey') {
+            this._v2E2EE.scheduleGroupSpkRegistrationAfterPeerFallback(groupId);
+        }
+        else if (!groupId && session.isLastUploadedSPK(spkId)) {
+            const callFn = async (method, params) => this.call(method, params);
+            session.rotateSPK(callFn).catch(exc => {
+                this._clientLog.debug(`V2 SPK rotation failed (non-fatal): ${exc}`);
+            });
+        }
+    }
+    /** inline 消息仅在应用提交且 ACK 成功后补做可变副作用。 */
+    async _postInlineV2CommitAndAck(msg) {
+        const envJson = msg.envelope_json;
+        if (!envJson || typeof envJson !== 'string')
+            return;
+        let envelope;
+        try {
+            envelope = JSON.parse(envJson);
+        }
+        catch {
+            return;
+        }
+        try {
+            await this._observeAgentMdFromEnvelope(envelope);
+        }
+        catch (exc) {
+            this._clientLog.debug(`inline V2 agent.md observe failed (non-fatal): ${String(exc)}`);
+        }
+        this._scheduleV2KeyRotationForMessage(msg, envelope);
+    }
     /**
      * V2 Group 加密发送（推测性：用缓存 bootstrap 直接发，失败刷新重试一次）。
      *
@@ -3067,8 +3517,8 @@ export class AUNClient {
      * @param groupId 群 ID
      * @param upToSeq 确认到此 seq；省略则用当前 contiguous
      */
-    async _ackGroupV2(groupId, upToSeq) {
-        return await this._v2E2EE.ackGroupV2(groupId, upToSeq);
+    async _ackGroupV2(groupId, upToSeq, groupAid, inlineGeneration) {
+        return await this._v2E2EE.ackGroupV2(groupId, upToSeq, groupAid, inlineGeneration);
     }
     /**
      * V2 P2P 多设备 wrap envelope 构造（不发送）。
@@ -3175,18 +3625,6 @@ export class AUNClient {
             this._clientLog.warn(`background task exception:${String(exc)}`);
         });
     }
-    _explicitGroupCursorParams(params) {
-        const value = params._group_cursor_params;
-        if (!isJsonObject(value))
-            return {};
-        return { ...value };
-    }
-    _groupCursorTargetsCurrentInstance(params) {
-        const deviceId = String(params.device_id ?? '').trim();
-        const slotId = String(params.slot_id ?? '').trim();
-        return (!deviceId || deviceId === (this._deviceId ?? ''))
-            && (!slotId || slotId === (this._slotId ?? ''));
-    }
     // ── Pull Gate（序列化同一 key 的并发 pull）──────────────────
     async _withBackgroundRpc(operation) {
         this._backgroundRpcDepth += 1;
@@ -3197,13 +3635,56 @@ export class AUNClient {
             this._backgroundRpcDepth = Math.max(0, this._backgroundRpcDepth - 1);
         }
     }
-    async _runPullSerialized(key, operation) {
-        return await this._rpcPipeline.runPullSerialized(key, operation);
+    async _runPullSerialized(key, operation, background = false) {
+        return await this._rpcPipeline.runPullSerialized(key, operation, background);
     }
-    /** 可取消的 sleep */
-    _sleep(ms) {
+    async _withPullResponseProcessing(ns, operation) {
+        if (!ns)
+            return await operation();
+        this._pullResponseKeys.set(ns, (this._pullResponseKeys.get(ns) ?? 0) + 1);
+        try {
+            return await operation();
+        }
+        finally {
+            const remaining = (this._pullResponseKeys.get(ns) ?? 1) - 1;
+            if (remaining <= 0)
+                this._pullResponseKeys.delete(ns);
+            else
+                this._pullResponseKeys.set(ns, remaining);
+        }
+    }
+    /** 每轮重连从当前地址之后开始轮转，避免永远黏在失效的首个 Gateway。 */
+    _orderedReconnectGateways(params) {
+        const raw = Array.isArray(params.gateways) && params.gateways.length > 0
+            ? params.gateways
+            : (this._gatewayCandidates.length > 0 ? this._gatewayCandidates : [params.gateway ?? this._gatewayUrl]);
+        const candidates = [...new Set(raw.map((item) => String(item ?? '').trim()).filter(Boolean))];
+        if (candidates.length <= 1)
+            return candidates;
+        const current = String(this._gatewayUrl ?? params.gateway ?? '').trim();
+        const index = candidates.indexOf(current);
+        const start = index >= 0 ? (index + 1) % candidates.length : 0;
+        return [...candidates.slice(start), ...candidates.slice(0, start)];
+    }
+    /** 可取消的 sleep；重连终止时立即释放退避等待。 */
+    _sleep(ms, signal) {
         return new Promise((resolve) => {
-            globalThis.setTimeout(resolve, ms);
+            let settled = false;
+            const finish = () => {
+                if (settled)
+                    return;
+                settled = true;
+                globalThis.clearTimeout(timer);
+                signal?.removeEventListener('abort', finish);
+                resolve();
+            };
+            const timer = globalThis.setTimeout(finish, ms);
+            if (signal) {
+                if (signal.aborted)
+                    finish();
+                else
+                    signal.addEventListener('abort', finish, { once: true });
+            }
         });
     }
 }