@agentunion/fastaun 0.5.6 → 0.5.9

package/dist/client.js

@@ -16,17 +16,17 @@ import * as https from 'node:https';
 import { URL } from 'node:url';
 import { configFromMap, getDeviceId, normalizeSlotId } from './config.js';
 import { CryptoProvider } from './crypto.js';
-import { AIDStore } from './aid-store.js';
 import { GatewayDiscovery } from './discovery.js';
 import { DnsResilientNet } from './net.js';
 import { AUNError, AuthError, ConnectionError, E2EEError, NotFoundError, PermissionError, StateError, TimeoutError, ValidationError, } from './errors.js';
 import { EventDispatcher } from './events.js';
 import { LocalTokenStore } from './keystore/local-token-store.js';
 import { AUNLogger } from './logger.js';
+import { normalizeGroupId } from './group-id.js';
 import { validateAIDFormat, validateGroupIDFormat } from './validators.js';
 import { RPCTransport } from './transport.js';
 import { AuthFlow } from './auth.js';
-import { AgentMdManager } from './agent-md.js';
+import { AgentMdManager, buildDefaultAgentMd } from './agent-md.js';
 import { GroupIndexMetaCache } from './group-index.js';
 import { SeqTracker } from './seq-tracker.js';
 import { ClientRuntime } from './client/runtime.js';
@@ -37,7 +37,7 @@ import { LifecycleController } from './client/lifecycle.js';
 import { PeerDirectory } from './client/peers.js';
 import { RpcPipeline } from './client/rpc-pipeline.js';
 import { CollabClient } from './collab/client.js';
-import { GroupFacade, MessageFacade, StreamFacade } from './facades.js';
+import { GroupFacade, MailFacade, MessageFacade, StreamFacade } from './facades.js';
 import { StorageVFS } from './storage/vfs.js';
 import { V2E2EECoordinator } from './client/v2-e2ee.js';
 import { GroupStateCoordinator } from './client/group-state.js';
@@ -45,7 +45,7 @@ import { decryptMessage, } from './v2/e2ee/index.js';
 import { ecdsaVerifyRaw } from './v2/crypto/ecdsa.js';
 import { isJsonObject, ConnectionState, STATE_TO_PUBLIC, } from './types.js';
 import { AID } from './aid.js';
-import { certMatchesFingerprint, normalizeFingerprintHex } from './cert-utils.js';
+import { certMatchesFingerprint, normalizeFingerprintHex, publicKeyMatchesFingerprint } from './cert-utils.js';
 function isPromiseLike(value) {
     return Boolean(value && typeof value.then === 'function');
 }
@@ -124,7 +124,7 @@ const MAX_NOTIFY_PAYLOAD_SIZE = 64 * 1024;
 // P1-23: 非幂等方法使用更长超时（35s），避免 SDK 10s 超时 < gateway 30s 处理时间
 const NON_IDEMPOTENT_TIMEOUT_MS = 35_000;
 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',
@@ -332,6 +332,7 @@ function createAgentMdManagerForRuntime(opts) {
         aunPath: opts.config().aunPath,
         verifySsl: opts.config().verifySsl,
         discoveryPort: opts.config().discoveryPort,
+        uploadViaGatewayHost: true,
         logger: opts.logger(),
         ownerAidGetter: opts.ownerAid,
         currentAidGetter: opts.currentAid,
@@ -435,6 +436,7 @@ export class AUNClient {
     _gatewayCandidates = [];
     /** 是否正在关闭 */
     _closing = false;
+    _disconnecting = false;
     /** 事件调度器 */
     _dispatcher;
     /** Gateway 发现 */
@@ -458,6 +460,8 @@ export class AUNClient {
     /** peer 证书缓存 */
     _certCache = new Map();
     _agentMdManager;
+    _aidStore;
+    _groupIdentityOperations = new Map();
     _groupIndexMetaCache = new GroupIndexMetaCache();
     /** 消息序列号跟踪器（群消息 + P2P 空洞检测） */
     _seqTracker = new SeqTracker();
@@ -483,12 +487,6 @@ export class AUNClient {
     _pushProcessQueues = new Map();
     /** P2P pull 进行中到达的纯通知 push 上界；pull gate 释放后需要补拉一次。 */
     _pendingP2pPullUpper = new Map();
-    /** 在线未读 hint 队列：同一 group 只保留最后一条，延迟 drain 降低登录瞬时拉取压力。 */
-    _onlineUnreadHintQueue = new Map();
-    _onlineUnreadHintTimer = null;
-    _onlineUnreadHintDrainActive = false;
-    _onlineUnreadHintInitialDelayMs = 750;
-    _onlineUnreadHintIntervalMs = 50;
     /** 缺 sender IK 时暂存原始 V2 消息，后台补齐 IK 后重试解密。 */
     _v2SenderIKPending = new Map();
     /** sender IK 后台补齐任务去重。 */
@@ -520,6 +518,8 @@ export class AUNClient {
     _peerCache = new Map();
     _reconnectActive = false;
     _reconnectAbort = null;
+    _reconnectTask = null;
+    _reconnectEventDispatchDepth = 0;
     _serverKicked = false;
     /** 缓存最近一次 gateway.disconnect 信息（含服务端附带的 detail），用于后续 connection.state 透传 */
     _lastDisconnectInfo = null;
@@ -536,6 +536,7 @@ export class AUNClient {
     _storage;
     _collab;
     _message;
+    _mail;
     _group;
     _stream;
     constructor(aid) {
@@ -543,6 +544,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;
@@ -685,7 +687,7 @@ export class AUNClient {
         // 群组状态提交事件：验证 state_hash 链并更新本地存储
         this._dispatcher.subscribe('_raw.group.state_committed', (data) => 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));
         }
         // 服务端主动断开通知：记录日志并标记不重连
@@ -696,6 +698,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)
@@ -804,6 +814,7 @@ export class AUNClient {
         this._v2LazyProposeTriggered.clear();
     }
     _applyAidRuntimeContext(aid) {
+        this._aidStore = aid._aidStore;
         const oldTransport = this._transport;
         try {
             const closeResult = oldTransport?.close?.();
@@ -841,6 +852,7 @@ export class AUNClient {
         this._peerCache.clear();
         this._certCache.clear();
         this._gatewayUrl = null;
+        this._gatewayCandidates = [];
         this._deviceId = aid.deviceId || getDeviceId(nextConfig.aunPath);
         this._slotId = aid.slotId || 'default';
         const debugFlag = nextConfig.debug;
@@ -1011,16 +1023,124 @@ 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 = store.load(groupAid);
+            if (!loaded.ok || !loaded.data?.aid?.isPrivateKeyValid())
+                return false;
+            await this._runGroupIdentityOperation(groupAid, () => this._uploadGroupAgentMd(store, groupAid, {}, {}));
+            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;
+        let agentMd = buildDefaultAgentMd(target);
+        try {
+            agentMd = this._agentMdManager.readContent(target);
+        }
+        catch { }
+        await this._agentMdManager.upload(agentMd);
+        return true;
+    }
+    async _runGroupIdentityOperation(groupId, operation) {
+        const aid = String(this._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;
+        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);
+        if (payload.group_name === undefined && payload.groupName !== undefined) {
+            payload.group_name = payload.groupName;
+            delete payload.groupName;
+        }
+        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 pendingKey = `create:${String(payload.group_name).trim().toLowerCase()}`;
+        const keystore = store._keystore;
+        let keyPair = null;
+        if (keystore && typeof keystore.loadPendingGroupBind === 'function') {
+            keyPair = keystore.loadPendingGroupBind(pendingKey);
+        }
+        if (!keyPair || !keyPair.public_key_der_b64 || !keyPair.private_key_pem) {
+            keyPair = new CryptoProvider().generateIdentity();
+            if (keystore && typeof keystore.savePendingGroupBind === 'function') {
+                keystore.savePendingGroupBind(pendingKey, keyPair);
+            }
+        }
+        if (!keyPair || !keyPair.public_key_der_b64 || !keyPair.private_key_pem) {
+            throw new ValidationError('createGroup: failed to generate or load key pair');
         }
-        const keyPair = new CryptoProvider().generateIdentity();
         payload.public_key = keyPair.public_key_der_b64;
         payload.curve = keyPair.curve;
         const result = await this.call('group.create', payload);
@@ -1030,31 +1150,65 @@ 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,
-            verifySsl: this._configModel.verifySsl,
-            rootCaPath: this._configModel.rootCaPath,
-            debug: this._configModel.debug,
+        const imported = 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 = 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();
+        await this._uploadGroupAgentMd(store, groupAid, payload, group);
+        if (keystore && typeof keystore.clearPendingGroupBind === 'function') {
+            keystore.clearPendingGroupBind(pendingKey);
+        }
+        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 item = String(source[key] ?? '').trim();
+                    if (item)
+                        return item;
+                }
+            }
+            return '';
+        };
+        const name = value('name', 'group_name', 'title') || groupAid;
+        const description = (value('description', 'group_description') || `AUN group ${name}`)
+            .replace(/\s+/g, ' ')
+            .slice(0, 100);
+        return [
+            '---',
+            `aid: ${JSON.stringify(groupAid)}`,
+            `name: ${JSON.stringify(name)}`,
+            'type: "group"',
+            'version: "1.0.0"',
+            `description: ${JSON.stringify(description)}`,
+            '---',
+            '',
+            `# ${name}`,
+            '',
+        ].join('\n');
+    }
+    async _uploadGroupAgentMd(store, groupAid, params, group) {
+        const uploaderAid = String(this._aid ?? '').trim();
+        if (!uploaderAid) {
+            throw new ValidationError('group agent.md upload requires current owner AID');
+        }
+        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)) {
@@ -1064,12 +1218,17 @@ 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 pendingKey = `bind:${groupId}`;
         const keystore = store._keystore; // AIDStore._keystore: LocalIdentityStore
         let keyPair = null;
         // 优先复用 pending 槽位中已暂存的待绑定密钥（崩溃/重试幂等）
         if (groupId && keystore && typeof keystore.loadPendingGroupBind === 'function') {
-            keyPair = keystore.loadPendingGroupBind(groupId);
+            keyPair = keystore.loadPendingGroupBind(pendingKey);
+            if (!keyPair || !keyPair.public_key_der_b64 || !keyPair.private_key_pem) {
+                keyPair = keystore.loadPendingGroupBind(groupId);
+            }
         }
         if (!keyPair || !keyPair.public_key_der_b64 || !keyPair.private_key_pem) {
             // 未命中 pending，生成新密钥
@@ -1081,7 +1240,7 @@ export class AUNClient {
             };
             // 发 RPC 前先落盘暂存，确保崩溃后重试能复用同一密钥
             if (groupId && keystore && typeof keystore.savePendingGroupBind === 'function') {
-                keystore.savePendingGroupBind(groupId, keyPair);
+                keystore.savePendingGroupBind(pendingKey, keyPair);
             }
         }
         if (!keyPair) {
@@ -1113,8 +1272,10 @@ export class AUNClient {
         if (!imported.ok) {
             throw new ValidationError(imported.error.message);
         }
+        await this._uploadGroupAgentMd(store, groupAid, payload, group);
         // 落盘成功，清除 pending 槽位
         if (groupId && keystore && typeof keystore.clearPendingGroupBind === 'function') {
+            keystore.clearPendingGroupBind(pendingKey);
             keystore.clearPendingGroupBind(groupId);
         }
         return result;
@@ -1137,7 +1298,7 @@ export class AUNClient {
             const info = await this.call('group.get_info', { group_id: groupId, required: ['member'] });
             const infoMap = isJsonObject(info) ? info : {};
             const grp = isJsonObject(infoMap.group) ? infoMap.group : infoMap;
-            groupAid = String(info?.group_aid ?? '').trim();
+            groupAid = String(info?.group_aid ?? grp?.group_aid ?? '').trim();
         }
         if (!groupAid) {
             throw new ValidationError('startGroupTransfer: unable to determine group_aid');
@@ -1185,7 +1346,7 @@ export class AUNClient {
             const info = await this.call('group.get_info', { group_id: groupId, required: ['member'] });
             const infoMap = isJsonObject(info) ? info : {};
             const grp = isJsonObject(infoMap.group) ? infoMap.group : infoMap;
-            groupAid = String(info?.group_aid ?? '').trim();
+            groupAid = String(info?.group_aid ?? grp?.group_aid ?? '').trim();
         }
         if (!groupAid) {
             throw new ValidationError('renewGroupAid: unable to determine group_aid');
@@ -1204,7 +1365,21 @@ export class AUNClient {
             throw new ValidationError(`renewGroupAid: cannot determine old public key for ${groupAid}`);
         }
         // 生成新密钥
-        const newKeyPair = new CryptoProvider().generateIdentity();
+        const keystore = store._keystore;
+        const pendingKey = `renew:${groupId}`;
+        let newKeyPair = null;
+        if (keystore && typeof keystore.loadPendingGroupBind === 'function') {
+            newKeyPair = keystore.loadPendingGroupBind(pendingKey);
+        }
+        if (!newKeyPair || !newKeyPair.public_key_der_b64 || !newKeyPair.private_key_pem) {
+            newKeyPair = new CryptoProvider().generateIdentity();
+            if (keystore && typeof keystore.savePendingGroupBind === 'function') {
+                keystore.savePendingGroupBind(pendingKey, newKeyPair);
+            }
+        }
+        if (!newKeyPair || !newKeyPair.public_key_der_b64 || !newKeyPair.private_key_pem) {
+            throw new ValidationError('renewGroupAid: failed to generate or load key pair');
+        }
         const newPublicKey = newKeyPair.public_key_der_b64;
         const newPrivateKey = newKeyPair.private_key_pem;
         const curve = newKeyPair.curve || 'P-256';
@@ -1259,6 +1434,10 @@ export class AUNClient {
         if (!imported.ok) {
             throw new ValidationError(`renewGroupAid failed to persist group identity: ${imported.error.message}`);
         }
+        await this._uploadGroupAgentMd(store, returnedGroupAid, payload, group);
+        if (keystore && typeof keystore.clearPendingGroupBind === 'function') {
+            keystore.clearPendingGroupBind(pendingKey);
+        }
         return result;
     }
     async completeGroupTransfer(params = {}, options = {}) {
@@ -1269,18 +1448,32 @@ export class AUNClient {
         if (!store) {
             throw new ValidationError('completeGroupTransfer requires aidStore');
         }
-        const keyPair = new CryptoProvider().generateIdentity();
         const payload = { ...params };
         const groupId = String(params.group_id ?? '').trim();
         if (!groupId) {
             throw new ValidationError('completeGroupTransfer requires group_id');
         }
+        const pendingKey = `complete:${groupId}`;
+        const keystore = store._keystore;
+        let keyPair = null;
+        if (keystore && typeof keystore.loadPendingGroupBind === 'function') {
+            keyPair = keystore.loadPendingGroupBind(pendingKey);
+        }
+        if (!keyPair || !keyPair.public_key_der_b64 || !keyPair.private_key_pem) {
+            keyPair = new CryptoProvider().generateIdentity();
+            if (keystore && typeof keystore.savePendingGroupBind === 'function') {
+                keystore.savePendingGroupBind(pendingKey, keyPair);
+            }
+        }
+        if (!keyPair || !keyPair.public_key_der_b64 || !keyPair.private_key_pem) {
+            throw new ValidationError('completeGroupTransfer: failed to generate or load key pair');
+        }
         let groupAid = String(params.group_aid ?? '').trim();
         if (!groupAid) {
             const info = await this.call('group.get_info', { group_id: groupId, required: ['member'] });
             const infoMap = isJsonObject(info) ? info : {};
             const grp = isJsonObject(infoMap.group) ? infoMap.group : infoMap;
-            groupAid = String(info?.group_aid ?? '').trim();
+            groupAid = String(info?.group_aid ?? grp?.group_aid ?? '').trim();
         }
         if (!groupAid) {
             throw new ValidationError('completeGroupTransfer: unable to determine group_aid');
@@ -1330,31 +1523,25 @@ export class AUNClient {
         if (!imported.ok) {
             throw new ValidationError(imported.error.message);
         }
+        await this._uploadGroupAgentMd(store, returnedGroupAid, payload, group);
+        if (keystore && typeof keystore.clearPendingGroupBind === 'function') {
+            keystore.clearPendingGroupBind(pendingKey);
+        }
         return result;
     }
     /** 证书公钥校验：确保服务端返回的证书公钥 == 本地公钥（DER base64） */
     async verifyCertPublicKeyMatch(certPem, localPublicKeyDerB64, operation) {
-        // 简化实现：使用 Node.js crypto 或浏览器 Web Crypto API
-        // 完整实现需要解析 X.509 证书提取 subjectPublicKeyInfo
-        // 这里先做基本校验，后续可增强
-        const crypto = globalThis.crypto;
-        if (!crypto || !crypto.subtle) {
-            // 浏览器环境或 Node < 15，跳过校验（非致命）
-            console.warn(`${operation}: crypto.subtle not available, skipping cert public key verification`);
-            return;
-        }
         try {
-            // TODO: 完整实现需要 ASN.1 解析库提取证书公钥
-            // 当前仅做导入测试，确保证书格式有效
-            const certLines = certPem.split('\n').filter(l => l && !l.startsWith('-----'));
-            const certDer = Buffer.from(certLines.join(''), 'base64');
-            // 验证本地公钥可导入
+            const cert = new crypto.X509Certificate(certPem);
+            const certPubDer = cert.publicKey.export({ type: 'spki', format: 'der' });
             const localPubDer = Buffer.from(localPublicKeyDerB64, 'base64');
-            await crypto.subtle.importKey('spki', localPubDer, { name: 'ECDSA', namedCurve: 'P-256' }, false, ['verify']);
-            // 证书公钥提取需要完整 ASN.1 解析，暂时依赖服务端正确性
-            // 后续迭代可引入 @peculiar/x509 或类似库
+            if (!localPubDer.length || !certPubDer.equals(localPubDer)) {
+                throw new AuthError(`${operation}: certificate public key mismatch`);
+            }
         }
         catch (err) {
+            if (err instanceof AuthError)
+                throw err;
             throw new AuthError(`${operation}: certificate or public key validation failed: ${err.message}`);
         }
     }
@@ -1566,9 +1753,11 @@ export class AUNClient {
             this._clientLog.debug(`P2P pending pull postponed: ns=${ns}, upper_seq=${upperSeq}, contiguous=${contig}, state=${this._state}, closing=${this._closing}, reason=${reason}`);
             return false;
         }
+        if (this._rpcPipeline?.hasPullActivity?.(ns, false))
+            return false;
         this._pendingP2pPullUpper.delete(ns);
         this._clientLog.info(`P2P pending push follow-up pull scheduled: ns=${ns}, upper_seq=${upperSeq}, contiguous=${contig}, reason=${reason}`);
-        void this._fillP2pGap();
+        this._safeAsync(this._onV2PushNotification({ seq: upperSeq }, 'v2'));
         return true;
     }
     _markPublishedSeq(ns, seq) {
@@ -1707,18 +1896,6 @@ export class AUNClient {
         }
         return Math.max(0, ...values.filter((value) => Number.isFinite(value)));
     }
-    _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 ?? ''));
-    }
     async _withBackgroundRpc(operation) {
         this._backgroundRpcDepth += 1;
         try {
@@ -1731,6 +1908,12 @@ export class AUNClient {
     async _runPullSerialized(key, operation, background = false) {
         return await this._rpcPipeline.runPullSerialized(key, operation, background);
     }
+    /** Mail bridge facade 入口 */
+    get mail() {
+        if (!this._mail)
+            this._mail = new MailFacade(this);
+        return this._mail;
+    }
     async _tryRunInlineRealtime(namespace, seq, operation) {
         return await this._rpcPipeline.tryRunInlineRealtime(namespace, seq, operation);
     }
@@ -1760,14 +1943,14 @@ export class AUNClient {
         }
         return true;
     }
-    async _drainOrderedMessages(ns, beforeSeq, pullResponse = false) {
-        return this._delivery.drainOrderedMessages(ns, beforeSeq, pullResponse);
+    async _drainOrderedMessages(ns, beforeSeq, pullResponse = false, persist = true) {
+        return 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);
     }
     _markOrderedSeqDelivered(ns, seq) {
         if (!ns || !Number.isFinite(seq) || !Number.isInteger(seq) || seq <= 0)
@@ -1836,7 +2019,7 @@ export class AUNClient {
         this._seqTracker.removeNamespace(groupEventNs);
         this._persistRepairedSeq(groupNs);
         this._persistRepairedSeq(groupEventNs);
-        this._saveSeqTrackerState();
+        void this._saveSeqTrackerState();
         for (const key of this._gapFillDone.keys()) {
             if (key.includes(groupId)) {
                 this._gapFillDone.delete(key);
@@ -1929,7 +2112,8 @@ export class AUNClient {
             if (!normalizeFingerprintHex(expectedFP)) {
                 throw new ValidationError(`unsupported cert_fingerprint format for ${aid}: ${expectedFP.slice(0, 24)}`);
             }
-            if (!certMatchesFingerprint(certPem, expectedFP)) {
+            if (!certMatchesFingerprint(certPem, expectedFP)
+                && !publicKeyMatchesFingerprint(certPem, expectedFP)) {
                 throw new ValidationError(`peer cert fingerprint mismatch for ${aid}: expected=${expectedFP.slice(0, 24)}...`);
             }
         }
@@ -2103,8 +2287,9 @@ export class AUNClient {
         return JSON.stringify([this._aid, this._deviceId, this._slotId]);
     }
     _resetSeqTrackingState() {
-        this._saveSeqTrackerState();
+        void this._saveSeqTrackerState();
         this._resetV2IdentityRuntime();
+        this._v2E2EE.resetForwardCursorState();
         this._delivery.resetInlineAckState();
         this._seqTracker = new SeqTracker();
         this._seqTrackerContext = null;
@@ -2115,18 +2300,13 @@ export class AUNClient {
         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;
-        this._saveSeqTrackerState();
+        void this._saveSeqTrackerState();
+        this._v2E2EE.resetForwardCursorState();
         this._delivery.resetInlineAckState();
         this._seqTracker = new SeqTracker();
         this._gapFillDone.clear();
@@ -2136,12 +2316,6 @@ export class AUNClient {
         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 */
@@ -2210,8 +2384,10 @@ export class AUNClient {
     }
     // ── 内部：连接 ────────────────────────────────────────────
     /** 执行一次连接流程 */
-    async _connectOnce(params, allowReauth) {
+    async _connectOnce(params, allowReauth, reconnectOwner, connectionOwner) {
         const tStart = Date.now();
+        connectionOwner ??= this._connectAbort ?? undefined;
+        this._lifecycle.assertConnectionAttemptOwner(connectionOwner);
         const gatewayUrl = this._resolveGateway(params);
         this._gatewayUrl = gatewayUrl;
         this._slotId = String(params.slot_id ?? '');
@@ -2228,8 +2404,11 @@ export class AUNClient {
         // 避免 reader 把积压 push 交给空 tracker 的 handler，触发 S2 历史 gap 误补拉。
         this._refreshSeqTrackerContext();
         this._restoreSeqTrackerState();
+        this._lifecycle.assertConnectionAttemptOwner(connectionOwner);
         try {
             const challenge = await this._transport.connect(gatewayUrl);
+            this._assertReconnectOwner(reconnectOwner);
+            this._lifecycle.assertConnectionAttemptOwner(connectionOwner);
             this._clientLog.debug(`WebSocket connection established: gateway=${gatewayUrl}`);
             this._state = 'authenticating';
             if (allowReauth) {
@@ -2242,6 +2421,8 @@ export class AUNClient {
                     shortTtlMs: Number(params.short_ttl_ms ?? 0),
                     extraInfo,
                 });
+                this._assertReconnectOwner(reconnectOwner);
+                this._lifecycle.assertConnectionAttemptOwner(connectionOwner);
                 if (isJsonObject(authContext)) {
                     const auth = authContext;
                     const identity = auth.identity;
@@ -2268,11 +2449,15 @@ export class AUNClient {
                     shortTtlMs: Number(params.short_ttl_ms ?? 0),
                     extraInfo,
                 });
+                this._assertReconnectOwner(reconnectOwner);
+                this._lifecycle.assertConnectionAttemptOwner(connectionOwner);
                 this._syncIdentityAfterConnect(String(params.access_token));
                 if (isJsonObject(hello) && 'heartbeat_interval' in hello) {
                     this._applyServerHeartbeatInterval(hello.heartbeat_interval, 'auth');
                 }
             }
+            this._assertReconnectOwner(reconnectOwner);
+            this._lifecycle.assertConnectionAttemptOwner(connectionOwner);
             if (!this._transport.isConnected()) {
                 throw new ConnectionError('websocket disconnected during authentication');
             }
@@ -2288,13 +2473,29 @@ export class AUNClient {
                 this._gatewayCandidates = [gatewayUrl];
             }
             this._clientLog.debug(`auth complete, connection ready: aid=${this._aid ?? ''}, gateway=${gatewayUrl}`);
-            await this._dispatcher.publish('state_change', { state: this._publicState(this._state), gateway: 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);
             // auth 阶段 aid 可能被 identity 覆盖（上方 this._aid = identity.aid）；
             // 若 context 发生变化，重新 refresh + restore，保持 tracker 与真实身份一致。
             if (this._seqTrackerContext !== this._currentSeqTrackerContext()) {
                 this._refreshSeqTrackerContext();
                 this._restoreSeqTrackerState();
             }
+            this._lifecycle.assertConnectionAttemptOwner(connectionOwner);
             this._startBackgroundTasks();
             const connectionKind = String(params.connection_kind ?? 'long');
             const isShortConnection = connectionKind === 'short';
@@ -2303,6 +2504,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');
@@ -2317,7 +2520,11 @@ export class AUNClient {
             this._clientLog.debug(`_connectOnce exit: elapsed=${Date.now() - tStart}ms gateway=${gatewayUrl}, aid=${this._aid ?? ''}`);
         }
         catch (err) {
-            this._state = (prevState === 'connected' || prevState === 'ready') ? 'standby' : (this._currentAid ? 'standby' : 'no_identity');
+            if ((!reconnectOwner || this._ownsReconnect(reconnectOwner))
+                && (!connectionOwner || this._lifecycle.ownsConnectionAttempt(connectionOwner))
+                && !this._closing) {
+                this._state = (prevState === 'connected' || prevState === 'ready') ? 'standby' : (this._currentAid ? 'standby' : 'no_identity');
+            }
             this._clientLog.debug(`_connectOnce exit (error): elapsed=${Date.now() - tStart}ms gateway=${gatewayUrl} err=${err instanceof Error ? err.message : String(err)}`);
             throw err;
         }
@@ -2523,7 +2730,7 @@ export class AUNClient {
         return await this._v2E2EE.ackGroupV2(groupId, upToSeq, groupAid);
     }
     /** 解密单条 V2 pull 消息。缺 sender IK 时先入 pending，后台补齐后重试。 */
-    async _decryptV2Message(msg, allowPending = true, emitUndecryptable = true, rotateKeys = true, observeAgentMd = true) {
+    async _decryptV2Message(msg, allowPending = true, emitUndecryptable = true, rotateKeys = true, observeAgentMd = true, deferStatus, deferKeyFetch = false) {
         const session = this._v2Session;
         if (!session)
             return null;
@@ -2585,6 +2792,24 @@ export class AUNClient {
         }
         catch (exc) {
             this._clientLog.warn(`V2 decrypt: SPK lookup failed seq=${String(msg.seq)} spk_id=${spkId}: ${formatCaughtError(exc)}`);
+            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;
+            }
             const event = {
                 message_id: String(msg.message_id ?? ''),
                 from: String(msg.from_aid ?? ''),
@@ -2610,13 +2835,19 @@ export class AUNClient {
         const senderDeviceId = String(aad.from_device ?? '');
         const senderCertFingerprint = String(envelope.sender_cert_fingerprint ?? '').trim().toLowerCase();
         let senderPubDer = await this._getV2SenderPubDer(fromAid, senderDeviceId, senderCertFingerprint);
-        if (!senderPubDer) {
+        if (!senderPubDer && !deferKeyFetch) {
             this._clientLog.warn(`V2 decrypt: no sender IK for ${fromAid} device=${senderDeviceId}`);
             senderPubDer = await this._fetchV2SenderIKOnce(fromAid, senderDeviceId, groupIdForKeys, senderCertFingerprint);
         }
         if (!senderPubDer) {
-            if (allowPending) {
-                this._scheduleV2SenderIKPending({ msg, fromAid, senderDeviceId, groupId: groupIdForKeys });
+            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;
             }
             const event = {
@@ -2641,9 +2872,13 @@ export class AUNClient {
         let plaintext;
         try {
             plaintext = 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)}: ${formatCaughtError(exc)}`);
+            if (deferStatus)
+                deferStatus.terminal = true;
             const event = {
                 message_id: String(msg.message_id ?? ''),
                 from: fromAid,
@@ -2896,6 +3131,11 @@ export class AUNClient {
         if (!resolvedAid) {
             throw new StateError('gateway discovery requires a loaded AID');
         }
+        const discovery = this._discovery;
+        const tokenStore = this._tokenStore;
+        const discoveryIsCurrent = () => (this._discovery === discovery
+            && this._tokenStore === tokenStore
+            && !this._closing);
         if (this._gatewayCandidates.length > 0)
             return [...this._gatewayCandidates];
         if (this._gatewayUrl) {
@@ -2903,9 +3143,9 @@ export class AUNClient {
             return [...this._gatewayCandidates];
         }
         try {
-            const loadMetadata = this._tokenStore.loadMetadata;
+            const loadMetadata = tokenStore.loadMetadata;
             const metadata = typeof loadMetadata === 'function'
-                ? loadMetadata.call(this._tokenStore, resolvedAid)
+                ? loadMetadata.call(tokenStore, resolvedAid)
                 : null;
             const cachedList = isJsonObject(metadata) && Array.isArray(metadata.gateway_urls)
                 ? metadata.gateway_urls.map((item) => String(item ?? '').trim()).filter(Boolean)
@@ -2932,12 +3172,13 @@ export class AUNClient {
             try {
                 // discoverAll 是生产路径；若调用方注入了旧版/测试 discovery
                 // 替身而只提供 discover，则保留单候选兼容，不影响多候选发现。
-                const discovery = this._discovery;
                 const hasInjectedDiscover = Object.prototype.hasOwnProperty.call(discovery, 'discover')
                     && typeof discovery.discover === 'function';
                 const discovered = hasInjectedDiscover
                     ? [await discovery.discover(url)]
                     : await discovery.discoverAll(url);
+                if (!discoveryIsCurrent())
+                    throw new StateError('gateway discovery superseded by identity change');
                 const gatewayUrls = [...new Set(discovered.map((item) => String(item ?? '').trim()).filter(Boolean))];
                 if (gatewayUrls.length === 0)
                     throw new ValidationError('gateway discovery returned no candidates');
@@ -2945,9 +3186,9 @@ export class AUNClient {
                 const gateway = gatewayUrls[0];
                 this._gatewayUrl = gateway;
                 try {
-                    const saveMetadata = this._tokenStore.saveMetadata;
+                    const saveMetadata = tokenStore.saveMetadata;
                     if (typeof saveMetadata === 'function') {
-                        saveMetadata.call(this._tokenStore, resolvedAid, {
+                        saveMetadata.call(tokenStore, resolvedAid, {
                             gateway_url: gateway,
                             gateway_urls: gatewayUrls,
                             gateway_cached_at: Date.now(),
@@ -2960,6 +3201,8 @@ export class AUNClient {
                 return [...gatewayUrls];
             }
             catch (err) {
+                if (!discoveryIsCurrent())
+                    throw new StateError('gateway discovery superseded by identity change');
                 lastErr = err;
                 this._clientLog.warn(`gateway discovery failed: aid=${resolvedAid} url=${url} err=${formatCaughtError(err)}`);
             }
@@ -3311,8 +3554,8 @@ export class AUNClient {
         }
     }
     /** 传输层断线回调 */
-    async _handleTransportDisconnect(error, closeCode) {
-        if (this._closing || this.state === ConnectionState.CLOSED)
+    async _handleTransportDisconnect(error, closeCode, initialOptions) {
+        if (this._closing || this._disconnecting || this.state === ConnectionState.CLOSED)
             return;
         // 已在重连中则跳过，避免心跳超时和 transport 断线回调重复触发
         if (this._reconnectActive)
@@ -3321,6 +3564,9 @@ export class AUNClient {
         this._delivery.resetInlineAckState();
         // 原子化标志，防止 await 期间并发调用再次进入
         this._reconnectActive = true;
+        // 在首个 await 前创建取消控制器，覆盖 disconnect 与清理动作的竞态窗口。
+        const reconnectAbort = new AbortController();
+        this._reconnectAbort = reconnectAbort;
         this._clientLog.warn(`transport disconnected: closeCode=${closeCode ?? 'none'}, error=${error ? formatCaughtError(error) : 'none'}`);
         this._state = 'standby';
         this._stopBackgroundTasks();
@@ -3330,9 +3576,28 @@ export class AUNClient {
         catch (exc) {
             this._clientLog.debug(`transport cleanup skipped: ${formatCaughtError(exc)}`);
         }
-        await this._dispatcher.publish('state_change', { state: this._publicState(this._state), error });
+        if (!await this._publishReconnectEvent(reconnectAbort, 'state_change', {
+            state: this._publicState(this._state),
+            error,
+        })) {
+            if (this._reconnectAbort === reconnectAbort) {
+                this._reconnectAbort = null;
+                this._reconnectActive = false;
+            }
+            return;
+        }
+        if (reconnectAbort.signal.aborted || this._reconnectAbort !== reconnectAbort || this._closing) {
+            if (this._reconnectAbort === reconnectAbort) {
+                this._reconnectAbort = null;
+                this._reconnectActive = false;
+            }
+            return;
+        }
         if (!this._sessionOptions.auto_reconnect) {
-            this._reconnectActive = false;
+            if (this._reconnectAbort === reconnectAbort) {
+                this._reconnectAbort = null;
+                this._reconnectActive = false;
+            }
             return;
         }
         // 不重连 close code（认证失败/权限错误/被踢等）或服务端通知断开：抑制重连
@@ -3352,38 +3617,111 @@ export class AUNClient {
             if (disconnectInfo.code !== undefined && disconnectInfo.code !== null) {
                 eventPayload.code = disconnectInfo.code;
             }
-            await this._dispatcher.publish('state_change', eventPayload);
-            this._reconnectActive = false;
+            await this._publishReconnectEvent(reconnectAbort, '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 = false;
-        this._startReconnect(serverInitiated);
+        if (reconnectAbort.signal.aborted || this._reconnectAbort !== reconnectAbort || this._closing) {
+            if (this._reconnectAbort === reconnectAbort) {
+                this._reconnectAbort = null;
+                this._reconnectActive = false;
+            }
+            return;
+        }
+        this._startReconnect(serverInitiated, initialOptions, reconnectAbort);
     }
     /** 启动重连循环（默认无限重试 + 当前基数抖动，仅在不可重试错误、close() 或 max_attempts 耗尽时终止） */
-    _startReconnect(serverInitiated = false) {
-        if (this._reconnectActive)
-            return;
-        this._reconnectActive = true;
-        const reconnectAbort = new AbortController();
-        this._reconnectAbort = reconnectAbort;
+    _startReconnect(serverInitiated = false, initialOptions, existingAbort) {
+        if (existingAbort) {
+            if (existingAbort.signal.aborted || this._reconnectAbort !== existingAbort)
+                return;
+        }
+        else {
+            if (this._reconnectActive)
+                return;
+            this._reconnectActive = true;
+            this._reconnectAbort = new AbortController();
+        }
+        const reconnectAbort = existingAbort ?? this._reconnectAbort;
         this._clientLog.debug(`reconnect loop started: serverInitiated=${String(serverInitiated)}, aid=${this._aid ?? ''}`);
-        this._reconnectLoop(serverInitiated, reconnectAbort).catch((exc) => {
-            this._clientLog.warn(`reconnect loop error: ${formatCaughtError(exc)}`);
-        });
+        if (!reconnectAbort)
+            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);
+    }
+    _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();
+        this._discovery?._cancelPending?.();
+        this._auth?._cancelPending?.();
+        this._stopBackgroundTasks();
+        try {
+            await this._transport.close();
+        }
+        catch (exc) {
+            this._clientLog.debug(`reconnect cancellation transport cleanup skipped: ${formatCaughtError(exc)}`);
+        }
+        // 重连事件 handler 内等待所属任务会自锁；事件返回后的 owner 复核负责收尾。
+        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, reconnectAbort = this._reconnectAbort) {
+    async _reconnectLoop(serverInitiated, reconnectAbort = this._reconnectAbort, initialOptions) {
         let releasedOwnGeneration = false;
         try {
-            await this._runReconnectLoop(serverInitiated, reconnectAbort);
+            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;
             }
         }
@@ -3394,44 +3732,47 @@ export class AUNClient {
         }
     }
     /** 重连循环主体（for 循环 + AbortController，与 JS/Python 对齐） */
-    async _runReconnectLoop(serverInitiated, reconnectAbort) {
+    async _runReconnectLoop(serverInitiated, reconnectAbort, initialOptions) {
         const retry = this._sessionOptions.retry;
         const maxBaseDelay = clampReconnectDelayMs(Number(retry.max_delay ?? 64.0) * 1000, RECONNECT_MAX_BASE_DELAY_MS);
         const maxAttemptsRaw = Number(retry.max_attempts ?? 0);
         const maxAttempts = Number.isFinite(maxAttemptsRaw) && maxAttemptsRaw > 0 ? Math.floor(maxAttemptsRaw) : 0;
         this._retryMaxAttempts = maxAttempts;
         let delay = clampReconnectDelayMs(serverInitiated ? 16_000 : Number(retry.initial_delay ?? 1.0) * 1000, serverInitiated ? 16_000 : RECONNECT_MIN_BASE_DELAY_MS, maxBaseDelay);
-        for (let attempt = 1; !reconnectAbort?.signal.aborted; attempt++) {
-            if (this._closing)
-                break;
+        if (!this._ownsReconnect(reconnectAbort))
+            return;
+        for (let attempt = 1; this._ownsReconnect(reconnectAbort); attempt++) {
             // max_attempts 检查在循环顶部，覆盖所有路径（含 health-fail）
             if (maxAttempts > 0 && attempt > maxAttempts) {
                 this._state = 'connection_failed';
-                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',
+                    });
                 break;
             }
             this._retryAttempt = attempt;
             this._nextRetryAt = Date.now() + reconnectSleepDelayMs(delay, maxBaseDelay);
             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,
-            });
+            }))
+                return;
             try {
                 // 抖动随当前 base 增长且不超过 max_base，避免首次重连被放大到几十秒。
                 await this._sleep(Math.max(0, this._nextRetryAt - Date.now()), reconnectAbort?.signal);
-                if (reconnectAbort?.signal.aborted || this._closing)
-                    break;
+                if (!this._ownsReconnect(reconnectAbort))
+                    return;
                 this._state = 'reconnecting';
-                await this._dispatcher.publish('state_change', {
+                if (!reconnectAbort || !await this._publishReconnectEvent(reconnectAbort, 'state_change', {
                     state: this._publicState(this._state),
                     attempt,
-                });
+                }))
+                    return;
                 // /health 仅作旁路诊断，不能阻止实际 WebSocket 重连。
                 if (this._gatewayUrl) {
                     void this._discovery.checkHealth(this._gatewayUrl, 5_000)
@@ -3444,6 +3785,20 @@ export class AUNClient {
                     });
                 }
                 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 === null) {
                     throw new StateError('missing connect params for reconnect');
                 }
@@ -3471,7 +3826,9 @@ export class AUNClient {
                 for (const gateway of candidates) {
                     const attemptParams = { ...this._sessionParams, gateway };
                     try {
-                        await this._connectOnce(attemptParams, true);
+                        await this._connectOnce(attemptParams, true, reconnectAbort ?? undefined);
+                        if (!this._ownsReconnect(reconnectAbort))
+                            return;
                         if (!this._transport.isConnected()) {
                             throw new ConnectionError('websocket disconnected while reconnecting');
                         }
@@ -3480,8 +3837,12 @@ export class AUNClient {
                         break;
                     }
                     catch (exc) {
+                        if (!this._ownsReconnect(reconnectAbort))
+                            return;
                         lastGatewayError = exc;
                         await this._transport.close().catch(() => { });
+                        if (!this._ownsReconnect(reconnectAbort))
+                            return;
                         if (candidates.length > 1) {
                             this._clientLog.warn(`reconnect gateway failed, trying next: gateway=${gateway}, error=${formatCaughtError(exc)}`);
                         }
@@ -3497,17 +3858,21 @@ export class AUNClient {
                 return;
             }
             catch (exc) {
-                await this._dispatcher.publish('connection.error', {
+                if (!this._ownsReconnect(reconnectAbort))
+                    return;
+                if (!reconnectAbort || !await this._publishReconnectEvent(reconnectAbort, 'connection.error', {
                     error: formatCaughtError(exc),
                     attempt,
-                });
+                }))
+                    return;
                 if (!AUNClient._shouldRetryReconnect(exc)) {
                     this._state = 'connection_failed';
-                    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,
+                        });
                     break;
                 }
                 delay = Math.min(delay * 2, maxBaseDelay);
@@ -3573,7 +3938,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;