@agentunion/fastaun-browser 0.5.6 → 0.5.8

package/dist/client.js

@@ -6,9 +6,9 @@
 //   - 后台任务使用 setTimeout/setInterval
 import { createConfig, getDeviceId, normalizeSlotId } from './config.js';
 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';
@@ -19,7 +19,7 @@ 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';
@@ -99,7 +99,7 @@ const MAX_NOTIFY_PAYLOAD_SIZE = 64 * 1024;
 // 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',
@@ -231,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,
@@ -561,6 +562,8 @@ export class AUNClient {
     _v2LazyProposeTriggered = new Map();
     /** agent.md 运行时管理器，负责上传、下载、缓存和 RPC 元数据观察。 */
     _agentMdManager;
+    _aidStore;
+    _groupIdentityOperations = new Map();
     _groupIndexMetaCache = new GroupIndexMetaCache();
     _groupIndexCacheLoaded = new Set();
     /** 消息序列号跟踪器（群消息 + P2P 空洞检测） */
@@ -580,12 +583,6 @@ 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;
@@ -595,6 +592,8 @@ export class AUNClient {
     // 重连相关
     _reconnectActive = false;
     _reconnectAbort = null;
+    _reconnectTask = null;
+    _reconnectEventDispatchDepth = 0;
     _serverKicked = false;
     // 重连状态追踪（对齐 Python client.py）
     _nextRetryAt = null;
@@ -628,6 +627,7 @@ export class AUNClient {
     _storage;
     _collab;
     _messageFacade;
+    _mailFacade;
     _groupFacade;
     _streamFacade;
     constructor(aid) {
@@ -635,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;
@@ -770,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);
             });
@@ -784,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)
@@ -849,6 +858,12 @@ export class AUNClient {
         }
         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);
     }
@@ -1008,6 +1023,7 @@ export class AUNClient {
         this._v2PullPending = false;
     }
     _applyAidRuntimeContext(aid) {
+        this._aidStore = aid._aidStore;
         const oldTransport = this._transport;
         try {
             const closeResult = oldTransport?.close?.();
@@ -1173,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;
@@ -1192,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)) {
@@ -1225,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;
@@ -1272,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);
@@ -1293,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');
@@ -1361,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 = {}) {
@@ -1379,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');
@@ -1427,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');
@@ -1475,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) {
@@ -1692,14 +1845,14 @@ 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;
@@ -1937,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);
@@ -1951,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, {
@@ -1964,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;
@@ -1988,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');
                     }
@@ -1996,13 +2160,19 @@ 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');
             }
@@ -2017,14 +2187,30 @@ export class AUNClient {
             else if (gatewayUrl) {
                 this._gatewayCandidates = [gatewayUrl];
             }
-            await this._dispatcher.publish('state_change', {
+            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';
@@ -2033,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');
@@ -2442,13 +2630,16 @@ 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';
@@ -2464,8 +2655,18 @@ export class AUNClient {
             state: this._publicState(this._state),
             error,
         });
+        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（认证失败/权限错误/被踢等）或服务端通知断开：抑制重连
@@ -2487,30 +2688,90 @@ export class AUNClient {
                 eventPayload.code = disconnectInfo.code;
             }
             await this._dispatcher.publish('state_change', eventPayload);
-            this._reconnectActive = false;
+            if (this._reconnectAbort === reconnectAbort) {
+                this._reconnectAbort = null;
+                this._reconnectActive = false;
+            }
             return;
         }
         // 1000 = 正常关闭, 1006 = 网络异常断开（无 close frame），其他 code = 服务端主动关闭
         const serverInitiated = closeCode !== undefined && closeCode !== 1000 && closeCode !== 1006;
-        if (this._closing) {
-            this._reconnectActive = false;
+        if (this._closing || reconnectAbort.signal.aborted || this._reconnectAbort !== reconnectAbort) {
+            if (this._reconnectAbort === reconnectAbort) {
+                this._reconnectAbort = null;
+                this._reconnectActive = false;
+            }
             return;
         }
-        const reconnectAbort = new AbortController();
-        this._reconnectAbort = reconnectAbort;
-        this._safeAsync(this._reconnectLoop(serverInitiated, reconnectAbort));
+        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();
+        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) {
+    async _reconnectLoop(serverInitiated = false, 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;
             }
         }
@@ -2519,7 +2780,7 @@ export class AUNClient {
         }
     }
     /** 指数退避 + 当前基数抖动重连循环主体。 */
-    async _runReconnectLoop(serverInitiated, reconnectAbort) {
+    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 对齐）
@@ -2534,11 +2795,12 @@ export class AUNClient {
             if (maxAttempts > 0 && attempt > maxAttempts) {
                 this._state = 'terminal_failed';
                 this._nextRetryAt = 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：先退避再重连）
@@ -2546,22 +2808,26 @@ 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, reconnectAbort?.signal);
                 this._nextRetryAt = null;
-                if (reconnectAbort?.signal.aborted)
+                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,
-                });
+                }))
+                    return;
+                if (!this._ownsReconnect(reconnectAbort))
+                    return;
                 // /health 仅作旁路诊断，不能阻止实际 WebSocket 重连。
                 if (this._gatewayUrl) {
                     void this._discovery.checkHealth(this._gatewayUrl, 5000)
@@ -2574,6 +2840,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) {
                     throw new StateError('missing connect params for reconnect');
                 }
@@ -2601,7 +2881,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');
                         }
@@ -2627,20 +2909,24 @@ export class AUNClient {
                 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;
-                    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);
@@ -2663,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;
@@ -2683,6 +2969,7 @@ export class AUNClient {
     _resetSeqTrackingState() {
         void this._saveSeqTrackerState();
         this._resetV2IdentityRuntime();
+        this._v2E2EE.resetForwardCursorState();
         this._seqTracker = new SeqTracker();
         this._seqTrackerContext = null;
         this._gapFillDone.clear();
@@ -2692,18 +2979,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;
         void this._saveSeqTrackerState();
+        this._v2E2EE.resetForwardCursorState();
         this._seqTracker = new SeqTracker();
         this._delivery.resetInlineAckState();
         this._gapFillDone.clear();
@@ -2713,12 +2995,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 */
@@ -2941,7 +3217,7 @@ export class AUNClient {
      * undecryptable 事件、成功消费后触发 SPK 轮换。inline Push 在游标提交和
      * Head/正文绑定校验前调用本入口时必须显式关闭这些副作用。
      */
-    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;
@@ -3008,6 +3284,24 @@ export class AUNClient {
         }
         catch (exc) {
             this._clientLog.warn(`V2 decrypt: SPK lookup failed seq=${String(msg.seq)} spk_id=${spkId}: ${String(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;
+            }
             if (emitUndecryptable) {
                 try {
                     const event = {
@@ -3035,13 +3329,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;
             }
             if (emitUndecryptable) {
@@ -3069,9 +3369,13 @@ export class AUNClient {
         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)}`);
+            if (deferStatus)
+                deferStatus.terminal = true;
             if (emitUndecryptable) {
                 try {
                     const event = {
@@ -3321,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;