@agentunion/fastaun-browser 0.5.4 → 0.5.6

package/dist/client.js

@@ -6,7 +6,6 @@
 //   - 后台任务使用 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';
@@ -15,6 +14,7 @@ import { AuthFlow } from './auth.js';
 import { SeqTracker } from './seq-tracker.js';
 import { ClientRuntime } from './client/runtime.js';
 import { MessageDeliveryEngine } from './client/delivery.js';
+import { normalizeGroupMentionMode } from './client/mention-mode.js';
 import { IdentityRuntimeManager } from './client/identity.js';
 import { LifecycleController } from './client/lifecycle.js';
 import { PeerDirectory } from './client/peers.js';
@@ -78,7 +78,7 @@ function groupIndexBodyText(value) {
 }
 const DEFAULT_SESSION_OPTIONS = {
     auto_reconnect: true,
-    heartbeat_interval: 30.0,
+    heartbeat_interval: 0.0,
     token_refresh_before: 1800.0,
     retry: {
         initial_delay: 1.0,
@@ -96,20 +96,6 @@ const RECONNECT_MIN_BASE_DELAY_SECONDS = 1.0;
 const RECONNECT_MAX_BASE_DELAY_SECONDS = 64.0;
 const TOKEN_REFRESH_CHECK_INTERVAL_MS = 30_000;
 const MAX_NOTIFY_PAYLOAD_SIZE = 64 * 1024;
-// 心跳间隔下/上限（秒）。0 = 关闭心跳；负值视为 0；其余值 clamp 到 [10, 600]。
-// 服务端通过 hello.heartbeat_interval 与 meta.ping pong 中的同名字段下发。
-const HEARTBEAT_MIN_INTERVAL_SECONDS = 10;
-const HEARTBEAT_MAX_INTERVAL_SECONDS = 600;
-function clampHeartbeatInterval(value) {
-    const n = Number(value);
-    if (!Number.isFinite(n) || n <= 0)
-        return 0;
-    if (n < HEARTBEAT_MIN_INTERVAL_SECONDS)
-        return HEARTBEAT_MIN_INTERVAL_SECONDS;
-    if (n > HEARTBEAT_MAX_INTERVAL_SECONDS)
-        return HEARTBEAT_MAX_INTERVAL_SECONDS;
-    return n;
-}
 // P1-23: 非幂等方法使用更长超时（35s），避免 SDK 10s 超时 < gateway 30s 处理时间
 const NON_IDEMPOTENT_TIMEOUT = 35;
 const NON_IDEMPOTENT_METHODS = new Set([
@@ -204,7 +190,8 @@ function clampReconnectDelaySeconds(value, fallback, upper = RECONNECT_MAX_BASE_
     return Math.min(Math.max(seconds, RECONNECT_MIN_BASE_DELAY_SECONDS), upper);
 }
 function reconnectSleepDelaySeconds(baseDelay, maxBaseDelay) {
-    return baseDelay + Math.random() * maxBaseDelay;
+    const jitterLimit = Math.min(Math.max(baseDelay, 0), Math.max(maxBaseDelay - baseDelay, 0));
+    return baseDelay + Math.random() * jitterLimit;
 }
 /** 对端证书缓存 TTL（秒） */
 const PEER_CERT_CACHE_TTL = 3600;
@@ -303,7 +290,6 @@ function createAgentMdManagerForRuntime(opts) {
             if (current?.aid === target) {
                 if (!expectedFp || await certMatchesFingerprint(current.certPem, expectedFp))
                     return current;
-                throw new StateError(`current AID certificate fingerprint mismatch for ${target}`);
             }
             if (!opts.gateway.get()) {
                 try {
@@ -529,6 +515,7 @@ export class AUNClient {
     _currentAid = null;
     _instanceProtectedHeaders = null;
     _gatewayUrl = null;
+    _gatewayCandidates = [];
     _deviceId;
     _slotId;
     _connectedAt = 0;
@@ -604,6 +591,7 @@ export class AUNClient {
     _backgroundRpcDepth = 0;
     // Pull Gate：序列化同一 key 的并发 pull 操作，防止重复拉取
     _pullGates = new Map();
+    _pullResponseKeys = new Map();
     // 重连相关
     _reconnectActive = false;
     _reconnectAbort = null;
@@ -842,7 +830,6 @@ export class AUNClient {
         for (const groupAid of Object.keys(groupIndexes)) {
             await this._persistGroupIndexCache(groupAid, {
                 remote_meta: this._groupIndexMetaCache.remoteMeta(this._aid ?? '', groupAid) ?? {},
-                local_etag: this._groupIndexMetaCache.localEtag(this._aid ?? '', groupAid),
             });
         }
     }
@@ -850,8 +837,17 @@ export class AUNClient {
         return this._groupIndexMetaCache.isStale(this._aid ?? '', groupAid);
     }
     markGroupIndexFresh(groupAid, options) {
-        this._groupIndexMetaCache.markFresh(this._aid ?? '', groupAid, options);
-        void this._persistGroupIndexCache(groupAid, { local_etag: String(options.etag ?? '') });
+        const verificationVersion = this._groupIndexMetaCache.markFresh(this._aid ?? '', groupAid, options);
+        const fields = {
+            local_etag: String(options.etag ?? ''),
+            verification_version: verificationVersion,
+        };
+        if (verificationVersion !== 1) {
+            fields.index_jsonl = '';
+            fields.settings = {};
+            fields.entry_etags = {};
+        }
+        void this._persistGroupIndexCache(groupAid, fields);
     }
     getGroupIndexRemoteMeta(groupAid) {
         return this._groupIndexMetaCache.remoteMeta(this._aid ?? '', groupAid);
@@ -868,6 +864,9 @@ export class AUNClient {
         return this._groupIndexMetaCache.cachedSettingsByEntries(this._aid ?? '', groupAid, keys.map((item) => String(item)), entries);
     }
     cacheGroupIndexSettings(groupAid, settings, options) {
+        if (!Array.isArray(options?.entries) || !String(options?.etag ?? '').trim()) {
+            return Promise.resolve();
+        }
         this._groupIndexMetaCache.cacheSettings(this._aid ?? '', groupAid, settings, options);
         const entryEtags = {};
         for (const item of options?.entries ?? []) {
@@ -876,6 +875,7 @@ export class AUNClient {
                 entryEtags[key] = String(item.etag ?? '');
         }
         const fields = {
+            verification_version: 1,
             settings,
             entry_etags: entryEtags,
             remote_meta: this._groupIndexMetaCache.remoteMeta(this._aid ?? '', groupAid) ?? {},
@@ -906,6 +906,7 @@ export class AUNClient {
             local_etag: record.local_etag,
             settings: record.settings,
             entry_etags: record.entry_etags,
+            verification_version: record.verification_version,
         });
     }
     async _persistGroupIndexCache(groupAid, fields) {
@@ -920,6 +921,7 @@ export class AUNClient {
             local_etag: record.local_etag,
             settings: record.settings,
             entry_etags: record.entry_etags,
+            verification_version: record.verification_version,
         });
     }
     get state() {
@@ -980,6 +982,8 @@ export class AUNClient {
     }
     _resetV2IdentityRuntime() {
         this._v2RuntimeGeneration += 1;
+        // 身份或 V2 会话代次切换时，隔离仍在途的 inline 解密/应用回调。
+        this._delivery?.resetInlineAckState();
         const keyStore = this._v2KeyStore;
         try {
             keyStore?.close?.();
@@ -1111,8 +1115,8 @@ export class AUNClient {
     getPeer(aid) {
         return this._peerDirectory.getPeer(aid);
     }
-    async lookupPeer(aid) {
-        return this._peerDirectory.lookupPeer(aid);
+    async lookupPeer(aid, certFingerprint) {
+        return this._peerDirectory.lookupPeer(aid, certFingerprint);
     }
     peers() {
         return this._peerDirectory.peers();
@@ -1539,15 +1543,16 @@ export class AUNClient {
             const eventMethod = AUNClient._validateNotifyEventMethod(method);
             // 校验目标 Group ID 格式
             validateGroupIDFormat(targetGroupId, 'notify.group_id');
-            const normalizedGroupId = normalizeGroupId(targetGroupId);
-            if (!normalizedGroupId) {
+            if (!targetGroupId) {
                 throw new ValidationError('group_id is required for group notify');
             }
             const routeParams = {
-                group_aid: normalizedGroupId,
-                group_id: normalizedGroupId,
+                group_id: targetGroupId,
                 deliver: { method: eventMethod, params: payload },
             };
+            const explicitGroupAid = String(options.group_aid ?? options.groupAid ?? '').trim();
+            if (explicitGroupAid)
+                routeParams.group_aid = explicitGroupAid;
             if (ttl !== undefined)
                 routeParams.ttl_ms = ttl;
             await this._transport.notify('notification/group.route', routeParams);
@@ -1564,17 +1569,26 @@ export class AUNClient {
     }
     async _callRawV2Rpc(method, params) {
         const p = { ...(params ?? {}) };
-        const rpcBackground = Boolean(p._rpc_background) || this._backgroundRpcDepth > 0;
+        const forceForeground = Boolean(p._rpc_foreground);
+        const rpcBackground = !forceForeground
+            && (Boolean(p._rpc_background) || this._backgroundRpcDepth > 0);
+        delete p._rpc_foreground;
         delete p._rpc_background;
         delete p._pull_gate_locked;
         delete p._skip_auto_ack;
         delete p.skip_auto_ack;
         delete p._group_cursor_params;
-        if (method.startsWith('group.') && p.group_aid !== undefined && p.group_aid !== null) {
-            p.group_aid = normalizeGroupId(String(p.group_aid)) || String(p.group_aid);
-        }
-        else if (method.startsWith('group.') && p.group_id !== undefined && p.group_id !== null) {
-            p.group_aid = normalizeGroupId(String(p.group_id)) || String(p.group_id);
+        if (method.startsWith('group.')) {
+            const rawGroupAid = String(p.group_aid ?? p.groupAid ?? '').trim();
+            const rawGroupId = String(p.group_id ?? p.groupId ?? '').trim();
+            if (rawGroupId)
+                p.group_id = rawGroupId;
+            else if (rawGroupAid)
+                p.group_id = rawGroupAid;
+            if (rawGroupAid)
+                p.group_aid = rawGroupAid;
+            delete p.groupAid;
+            delete p.groupId;
         }
         if (method.startsWith('group.') && p.device_id === undefined) {
             p.device_id = this._deviceId;
@@ -1689,19 +1703,19 @@ export class AUNClient {
     }
     _extractGroupIdFromResult(result) {
         const group = isJsonObject(result.group) ? result.group : null;
-        const gid = group ? String(group.group_aid ?? group.group_id ?? '') : '';
+        const gid = group ? String(group.group_id ?? group.groupId ?? group.group_aid ?? group.groupAid ?? '') : '';
         if (gid)
             return gid;
-        const directGid = String(result.group_aid ?? result.group_id ?? '');
+        const directGid = String(result.group_id ?? result.groupId ?? result.group_aid ?? result.groupAid ?? '');
         if (directGid)
             return directGid;
         const member = isJsonObject(result.member) ? result.member : null;
-        return member ? String(member.group_aid ?? member.group_id ?? '') : '';
+        return member ? String(member.group_id ?? member.groupId ?? member.group_aid ?? member.groupAid ?? '') : '';
     }
     async _onRawGroupChanged(data) {
         const tStart = Date.now();
         const action = String(data?.action ?? '');
-        const groupIdInit = String(data?.group_aid ?? data?.group_id ?? '');
+        const groupIdInit = String(data?.group_id ?? data?.group_aid ?? '');
         this._clientLog.debug(`_onRawGroupChanged enter: group_id=${groupIdInit} action=${action}`);
         try {
             if (isJsonObject(data)) {
@@ -1717,7 +1731,7 @@ export class AUNClient {
                         d._verified = this._isEventSignatureVerified(verified);
                     }
                 }
-                const groupId = (d.group_aid ?? d.group_id ?? '');
+                const groupId = (d.group_id ?? d.group_aid ?? '');
                 await this._delivery.handleGroupChangedEventSeq(d, groupId);
             }
             else {
@@ -1989,8 +2003,20 @@ export class AUNClient {
                 catch { /* 忽略关闭错误 */ }
                 throw err;
             }
+            if (!this._transport.isConnected()) {
+                throw new ConnectionError('websocket disconnected during authentication');
+            }
+            this._serverKicked = false;
+            this._lastDisconnectInfo = null;
             this._state = 'connected';
             this._connectedAt = Date.now();
+            if (Array.isArray(params.gateways)) {
+                this._gatewayCandidates = [...new Set(params.gateways
+                        .map((item) => String(item ?? '').trim()).filter(Boolean))];
+            }
+            else if (gatewayUrl) {
+                this._gatewayCandidates = [gatewayUrl];
+            }
             await this._dispatcher.publish('state_change', {
                 state: this._publicState(this._state),
                 gateway: gatewayUrl,
@@ -2023,26 +2049,43 @@ export class AUNClient {
         }
     }
     _resolveGateway(params) {
+        const explicitGateway = String(params.gateway ?? '').trim();
+        if (explicitGateway)
+            return explicitGateway;
         const gateways = this._resolveGateways(params);
         return gateways[0];
     }
     async _resolveGatewayForAid(aid) {
+        const gateways = await this._resolveGatewayCandidatesForAid(aid);
+        return gateways[0];
+    }
+    async _resolveGatewayCandidatesForAid(aid) {
         const target = String(aid ?? this._aid ?? '').trim();
         if (!target)
             throw new StateError('gateway discovery requires a loaded AID');
-        if (this._gatewayUrl)
-            return this._gatewayUrl;
+        if (this._gatewayCandidates.length > 0)
+            return [...this._gatewayCandidates];
+        if (this._gatewayUrl) {
+            this._gatewayCandidates = [this._gatewayUrl];
+            return [...this._gatewayCandidates];
+        }
         try {
             const getMetadata = this._tokenStore.getMetadata;
+            const rawList = typeof getMetadata === 'function'
+                ? String(await getMetadata.call(this._tokenStore, target, 'gateway_urls') ?? '').trim()
+                : '';
+            const cachedList = rawList ? JSON.parse(rawList) : [];
             const raw = typeof getMetadata === 'function'
                 ? String(await getMetadata.call(this._tokenStore, target, 'gateway_url') ?? '').trim()
                 : '';
-            if (raw) {
-                const gateway = raw.startsWith('"') && raw.endsWith('"') ? String(JSON.parse(raw)).trim() : raw;
-                if (gateway) {
-                    this._gatewayUrl = gateway;
-                    return gateway;
-                }
+            const candidates = Array.isArray(cachedList)
+                ? cachedList.map((item) => String(item ?? '').trim()).filter(Boolean)
+                : [];
+            const gateway = candidates[0] ?? (raw.startsWith('"') && raw.endsWith('"') ? String(JSON.parse(raw)).trim() : raw);
+            if (gateway) {
+                this._gatewayCandidates = [...new Set([gateway, ...candidates])];
+                this._gatewayUrl = this._gatewayCandidates[0];
+                return [...this._gatewayCandidates];
             }
         }
         catch {
@@ -2058,18 +2101,24 @@ export class AUNClient {
         let lastError = null;
         for (const url of candidates) {
             try {
-                const gateway = await this._discovery.discover(url);
+                const discovered = await this._discovery.discoverAll(url);
+                const gatewayUrls = [...new Set(discovered.map((item) => String(item ?? '').trim()).filter(Boolean))];
+                if (gatewayUrls.length === 0)
+                    throw new ValidationError('gateway discovery returned no candidates');
+                const gateway = gatewayUrls[0];
+                this._gatewayCandidates = gatewayUrls;
                 this._gatewayUrl = gateway;
                 try {
                     const setMetadata = this._tokenStore.setMetadata;
                     if (typeof setMetadata === 'function') {
                         await setMetadata.call(this._tokenStore, target, 'gateway_url', gateway);
+                        await setMetadata.call(this._tokenStore, target, 'gateway_urls', JSON.stringify(gatewayUrls));
                     }
                 }
                 catch {
                     // 缓存写入失败不影响连接。
                 }
-                return gateway;
+                return [...gatewayUrls];
             }
             catch (err) {
                 lastError = err;
@@ -2088,7 +2137,9 @@ export class AUNClient {
                 throw new ValidationError('relay topology is not implemented in the Browser SDK');
             }
         }
-        const gw = params.gateway ?? params.gateways;
+        const gw = Array.isArray(params.gateways) && params.gateways.length > 0
+            ? params.gateways
+            : params.gateway;
         if (Array.isArray(gw)) {
             const urls = gw.map((g) => String(g ?? '')).filter((u) => u.length > 0);
             if (urls.length > 0)
@@ -2118,7 +2169,13 @@ export class AUNClient {
     _normalizeConnectParams(params) {
         const request = { ...params };
         const accessToken = String(request.access_token ?? '');
-        const gateway = String(request.gateway ?? this._gatewayUrl ?? '');
+        const rawGateways = request.gateways;
+        const normalizedGateways = Array.isArray(rawGateways)
+            ? [...new Set(rawGateways.map((item) => String(item ?? '').trim()).filter(Boolean))]
+            : [];
+        if (normalizedGateways.length > 0)
+            request.gateways = normalizedGateways;
+        const gateway = String(request.gateway ?? normalizedGateways[0] ?? this._gatewayUrl ?? '');
         if (!gateway)
             throw new StateError('connect requires non-empty gateway');
         if (accessToken)
@@ -2190,9 +2247,6 @@ export class AUNClient {
         if ('auto_reconnect' in params) {
             options.auto_reconnect = Boolean(params.auto_reconnect);
         }
-        if ('heartbeat_interval' in params) {
-            options.heartbeat_interval = Number(params.heartbeat_interval);
-        }
         if ('token_refresh_before' in params) {
             options.token_refresh_before = Number(params.token_refresh_before);
         }
@@ -2208,10 +2262,9 @@ export class AUNClient {
     }
     // ── 内部：后台任务 ────────────────────────────────
     _startBackgroundTasks() {
-        // 短连接不启动 heartbeat 与 token 刷新（生命周期短，不需要长期会话维护）；
-        // auto_reconnect 仍允许，由 _sessionOptions.auto_reconnect 决定
+        // WebSocket Ping/Pong 由 Gateway 与传输层处理；SDK 不发送 RPC 心跳。
+        // 短连接生命周期短，不需要 token 刷新。
         if (this._sessionOptions?.connection_kind !== 'short') {
-            this._startHeartbeat();
             this._startTokenRefresh();
         }
         // V2 内存缓存定时清理（每小时扫描过期条目）
@@ -2252,56 +2305,19 @@ export class AUNClient {
     }
     /** 心跳定时器 */
     _startHeartbeat() {
-        if (this._heartbeatTimer !== null)
-            return;
-        const interval = clampHeartbeatInterval(this._sessionOptions.heartbeat_interval ?? DEFAULT_SESSION_OPTIONS.heartbeat_interval);
-        if (interval <= 0)
-            return;
-        // M25: 把连续失败阈值从 3 次收窄到 2 次。既能容忍一次网络抖动/GC 暂停，
-        // 又把半开连接的检测延迟从 3 个心跳周期降到 2 个，避免 RPC 长时间挂起。
-        // 真正的 socket 死亡由 ws.on('close') 立即触发 _handleTransportDisconnect，
-        // 不依赖此心跳路径。
-        let consecutiveFailures = 0;
-        const maxFailures = 2;
-        this._heartbeatTimer = setInterval(async () => {
-            if (this.state !== ConnectionState.READY || this._closing)
-                return;
-            try {
-                const pong = await this._transport.call('meta.ping', {});
-                this._heartbeatCount++;
-                consecutiveFailures = 0;
-                // 服务端可在 pong 中下发新的 heartbeat_interval（秒，0=关闭）
-                if (isJsonObject(pong) && 'heartbeat_interval' in pong) {
-                    this._applyServerHeartbeatInterval(pong.heartbeat_interval, 'pong');
-                }
-            }
-            catch (exc) {
-                consecutiveFailures++;
-                this._clientLog.warn(`heartbeat failed (${consecutiveFailures}/${maxFailures}): ${String(exc)}`);
-                this._dispatcher.publish('connection.error', { error: formatCaughtError(exc) });
-                if (consecutiveFailures >= maxFailures) {
-                    this._clientLog.warn(`consecutive ${maxFailures}  heartbeat failed, trigger disconnect reconnect`);
-                    this._handleTransportDisconnect(exc instanceof Error ? exc : new Error(String(exc)));
-                }
-            }
-        }, interval * 1000);
-    }
-    /** 服务端通过 hello/pong 下发 heartbeat_interval；clamp 后写入 session_options 并按需重启心跳。 */
-    _applyServerHeartbeatInterval(raw, source) {
-        const newInterval = clampHeartbeatInterval(raw);
-        const oldInterval = clampHeartbeatInterval(this._sessionOptions.heartbeat_interval);
-        if (newInterval === oldInterval)
-            return;
-        this._sessionOptions.heartbeat_interval = newInterval;
-        this._clientLog.debug(`heartbeat_interval updated by ${source}: ${oldInterval} -> ${newInterval}`);
-        // 重启定时器以应用新间隔（关闭/启动通过定时器有/无区分）
         if (this._heartbeatTimer !== null) {
             clearInterval(this._heartbeatTimer);
             this._heartbeatTimer = null;
         }
-        if (newInterval > 0 && this.state === ConnectionState.READY && !this._closing) {
-            this._startHeartbeat();
+        this._sessionOptions.heartbeat_interval = 0;
+    }
+    /** 忽略旧 Gateway 的 RPC 心跳配置，固定使用 WebSocket Ping/Pong。 */
+    _applyServerHeartbeatInterval(_raw, _source) {
+        if (this._heartbeatTimer !== null) {
+            clearInterval(this._heartbeatTimer);
+            this._heartbeatTimer = null;
         }
+        this._sessionOptions.heartbeat_interval = 0;
     }
     /** Token 刷新定时器 */
     _startTokenRefresh() {
@@ -2399,7 +2415,7 @@ export class AUNClient {
     }
     // ── 内部：断线重连 ────────────────────────────────
     /** 不重连 close code 集合：认证失败/权限错误/被踢等，重连无意义 */
-    static _NO_RECONNECT_CODES = new Set([4001, 4003, 4008, 4009, 4010, 4011, 4012, 4013, 4014, 4015]);
+    static _NO_RECONNECT_CODES = new Set([4001, 4003, 4008, 4009, 4010, 4011, 4013, 4014, 4015]);
     /** 处理服务端主动断开通知 event/gateway.disconnect
      *
      * 服务端可能附带结构化 detail 字段（如配额超限时含 aid/device_id/slot_id/quota_kind/evicted_by）。
@@ -2411,7 +2427,11 @@ export class AUNClient {
         const reason = obj.reason ?? '';
         const detail = (obj.detail && typeof obj.detail === 'object') ? obj.detail : {};
         this._clientLog.warn(`server initiated disconnect: code=${code}, reason=${reason}, detail=${JSON.stringify(detail)}`);
-        this._serverKicked = true;
+        const reasonText = String(reason ?? '').trim().toLowerCase();
+        const retryable = Number(code) === 4012
+            || reasonText.includes('long_connection_already_exists')
+            || reasonText.includes('long connection already exists');
+        this._serverKicked = !retryable;
         // 缓存最近一次 disconnect 信息，让后续 connection.state(terminal_failed) 也能带 detail
         this._lastDisconnectInfo = { code, reason, detail };
         // 透传给应用层订阅者
@@ -2425,22 +2445,32 @@ export class AUNClient {
     async _handleTransportDisconnect(error, closeCode) {
         if (this._closing || this._state === 'closed')
             return;
+        // 在首个 await 前占位，避免 close/error 与 token 刷新并发启动多条重连链。
+        if (this._reconnectActive)
+            return;
+        this._reconnectActive = true;
+        // 不等待状态事件或 transport 清理，先隔离已在途的 inline Push 回调。
+        this._delivery.resetInlineAckState();
         this._state = 'standby';
         // 先停止后台任务，避免心跳/token刷新在重连期间继续触发
         this._stopBackgroundTasks();
-        void this._transport.close().catch((exc) => {
+        try {
+            await this._transport.close();
+        }
+        catch (exc) {
             this._clientLog.debug(`transport cleanup skipped: ${formatCaughtError(exc)}`);
-        });
+        }
         await this._dispatcher.publish('state_change', {
             state: this._publicState(this._state),
             error,
         });
-        if (!this._sessionOptions.auto_reconnect)
-            return;
-        if (this._reconnectActive)
+        if (!this._sessionOptions.auto_reconnect) {
+            this._reconnectActive = false;
             return;
+        }
         // 不重连 close code（认证失败/权限错误/被踢等）或服务端通知断开：抑制重连
-        if (this._serverKicked || (closeCode !== undefined && AUNClient._NO_RECONNECT_CODES.has(closeCode))) {
+        const retryableClose = closeCode === 4012;
+        if ((this._serverKicked && !retryableClose) || (closeCode !== undefined && AUNClient._NO_RECONNECT_CODES.has(closeCode))) {
             this._state = 'terminal_failed';
             const reason = this._serverKicked ? 'server kicked' : `close code ${closeCode}`;
             this._clientLog.warn(`suppress auto-reconnect: ${reason}`);
@@ -2457,16 +2487,39 @@ export class AUNClient {
                 eventPayload.code = disconnectInfo.code;
             }
             await this._dispatcher.publish('state_change', eventPayload);
+            this._reconnectActive = false;
             return;
         }
         // 1000 = 正常关闭, 1006 = 网络异常断开（无 close frame），其他 code = 服务端主动关闭
         const serverInitiated = closeCode !== undefined && closeCode !== 1000 && closeCode !== 1006;
-        this._reconnectActive = true;
-        this._reconnectAbort = new AbortController();
-        this._safeAsync(this._reconnectLoop(serverInitiated));
+        if (this._closing) {
+            this._reconnectActive = false;
+            return;
+        }
+        const reconnectAbort = new AbortController();
+        this._reconnectAbort = reconnectAbort;
+        this._safeAsync(this._reconnectLoop(serverInitiated, reconnectAbort));
+    }
+    /** 重连循环入口；无论正常退出还是意外异常，都只清理自己这一代控制器。 */
+    async _reconnectLoop(serverInitiated = false, reconnectAbort = this._reconnectAbort) {
+        let releasedOwnGeneration = false;
+        try {
+            await this._runReconnectLoop(serverInitiated, reconnectAbort);
+        }
+        finally {
+            if (this._reconnectAbort === reconnectAbort) {
+                this._nextRetryAt = null;
+                this._reconnectActive = false;
+                this._reconnectAbort = null;
+                releasedOwnGeneration = true;
+            }
+        }
+        if (releasedOwnGeneration && !this._closing && this._state === 'connected' && !this._transport.isConnected()) {
+            await this._handleTransportDisconnect(new ConnectionError('websocket disconnected while reconnect completed'));
+        }
     }
-    /** 指数退避 + 固定上限抖动重连循环（默认无限重试，仅在不可重试错误或 close() 或 max_attempts 耗尽时终止） */
-    async _reconnectLoop(serverInitiated = false) {
+    /** 指数退避 + 当前基数抖动重连循环主体。 */
+    async _runReconnectLoop(serverInitiated, reconnectAbort) {
         const retry = { ...this._sessionOptions.retry };
         const maxBaseDelay = clampReconnectDelaySeconds(retry.max_delay, RECONNECT_MAX_BASE_DELAY_SECONDS);
         // M25: max_attempts=0 表示无限重试（与 Go/Python 对齐）
@@ -2476,13 +2529,11 @@ export class AUNClient {
         let delay = clampReconnectDelaySeconds(serverInitiated ? 16.0 : retry.initial_delay, serverInitiated ? 16.0 : 1.0, maxBaseDelay);
         this._retryAttempt = 0;
         this._retryMaxAttempts = maxAttempts;
-        for (let attempt = 1; !this._reconnectAbort?.signal.aborted; attempt++) {
+        for (let attempt = 1; !reconnectAbort?.signal.aborted; attempt++) {
             // R1 fix: max_attempts 检查在循环顶部，覆盖所有路径（含 health-fail）
             if (maxAttempts > 0 && attempt > maxAttempts) {
                 this._state = 'terminal_failed';
                 this._nextRetryAt = null;
-                this._reconnectActive = false;
-                this._reconnectAbort = null;
                 await this._dispatcher.publish('state_change', {
                     state: this._publicState(this._state),
                     attempt: attempt - 1,
@@ -2501,27 +2552,26 @@ export class AUNClient {
                 next_retry_at: this._nextRetryAt.getTime() / 1000,
             });
             try {
-                await this._sleep(sleepMs);
+                await this._sleep(sleepMs, reconnectAbort?.signal);
                 this._nextRetryAt = null;
-                if (this._reconnectAbort?.signal.aborted) {
-                    this._reconnectActive = false;
+                if (reconnectAbort?.signal.aborted)
                     return;
-                }
                 // 退避结束，进入 reconnecting 状态
                 this._state = 'reconnecting';
                 await this._dispatcher.publish('state_change', {
                     state: this._publicState(this._state),
                     attempt,
                 });
-                // 重连前先 GET /health 探测，不健康则跳过本轮
+                // /health 仅作旁路诊断，不能阻止实际 WebSocket 重连。
                 if (this._gatewayUrl) {
-                    const healthy = await this._discovery.checkHealth(this._gatewayUrl, 5000);
-                    if (!healthy) {
-                        this._lastError = new Error('gateway health check failed');
-                        this._lastErrorCode = 'gateway_unhealthy';
-                        delay = Math.min(delay * 2, maxBaseDelay);
-                        continue;
-                    }
+                    void this._discovery.checkHealth(this._gatewayUrl, 5000)
+                        .then((healthy) => {
+                        if (!healthy)
+                            this._clientLog.warn(`reconnect health advisory failed: gateway=${this._gatewayUrl}`);
+                    })
+                        .catch((exc) => {
+                        this._clientLog.debug(`reconnect health advisory error: ${exc instanceof Error ? exc.message : String(exc)}`);
+                    });
                 }
                 await this._transport.close();
                 if (!this._sessionParams) {
@@ -2545,12 +2595,35 @@ export class AUNClient {
                         this._sessionParams.access_token = '';
                     }
                 }
-                await this._connectOnce(this._sessionParams, true);
+                const candidates = this._orderedReconnectGateways(this._sessionParams);
+                let lastGatewayError = null;
+                let connected = false;
+                for (const gateway of candidates) {
+                    const attemptParams = { ...this._sessionParams, gateway };
+                    try {
+                        await this._connectOnce(attemptParams, true);
+                        if (!this._transport.isConnected()) {
+                            throw new ConnectionError('websocket disconnected while reconnecting');
+                        }
+                        this._sessionParams.gateway = gateway;
+                        connected = true;
+                        break;
+                    }
+                    catch (exc) {
+                        lastGatewayError = exc;
+                        await this._transport.close().catch(() => { });
+                        if (candidates.length > 1) {
+                            this._clientLog.warn(`reconnect gateway failed, trying next: gateway=${gateway}, error=${exc instanceof Error ? exc.message : String(exc)}`);
+                        }
+                        if (!this._shouldRetryReconnect(exc))
+                            throw exc;
+                    }
+                }
+                if (!connected)
+                    throw (lastGatewayError instanceof Error ? lastGatewayError : new ConnectionError('all gateway candidates failed'));
                 this._lastError = null;
                 this._lastErrorCode = null;
                 this._nextRetryAt = null;
-                this._reconnectActive = false;
-                this._reconnectAbort = null;
                 return;
             }
             catch (exc) {
@@ -2563,8 +2636,6 @@ export class AUNClient {
                 if (!this._shouldRetryReconnect(exc)) {
                     this._state = 'terminal_failed';
                     this._nextRetryAt = null;
-                    this._reconnectActive = false;
-                    this._reconnectAbort = null;
                     await this._dispatcher.publish('state_change', {
                         state: this._publicState(this._state),
                         error: formatCaughtError(exc),
@@ -2575,14 +2646,15 @@ export class AUNClient {
                 delay = Math.min(delay * 2, maxBaseDelay);
             }
         }
-        this._reconnectActive = false;
-        this._reconnectAbort = null;
     }
     /** 判断是否应重试重连 */
     _shouldRetryReconnect(error) {
         if (error instanceof AuthError) {
             const message = String(error.message ?? '').toLowerCase();
-            if (message.includes('aid_login1_failed') || message.includes('aid_login2_failed')) {
+            if (message.includes('long_connection_already_exists')
+                || message.includes('long connection already exists')
+                || message.includes('aid_login1_failed')
+                || message.includes('aid_login2_failed')) {
                 return true;
             }
             return false;
@@ -2615,6 +2687,7 @@ export class AUNClient {
         this._seqTrackerContext = null;
         this._gapFillDone.clear();
         this._pushedSeqs.clear();
+        this._pullResponseKeys.clear();
         this._pendingOrderedMsgs.clear();
         this._v2SenderIKPending.clear();
         this._v2SenderIKFetching.clear();
@@ -2632,8 +2705,10 @@ export class AUNClient {
             return;
         void this._saveSeqTrackerState();
         this._seqTracker = new SeqTracker();
+        this._delivery.resetInlineAckState();
         this._gapFillDone.clear();
         this._pushedSeqs.clear();
+        this._pullResponseKeys.clear();
         this._pendingOrderedMsgs.clear();
         this._v2SenderIKPending.clear();
         this._v2SenderIKFetching.clear();
@@ -2653,6 +2728,9 @@ export class AUNClient {
     _persistSeq(ns, forceSeq) {
         return this._delivery.persistSeq(ns, forceSeq);
     }
+    async _commitSeqTrackerState(ns) {
+        await this._delivery.commitSeqTrackerState(ns);
+    }
     _persistRepairedSeq(ns) {
         return this._delivery.persistRepairedSeq(ns);
     }
@@ -2805,6 +2883,9 @@ export class AUNClient {
     async _getV2SenderPubDer(fromAid, senderDeviceId, certFingerprint) {
         return await this._v2E2EE.getV2SenderPubDer(fromAid, senderDeviceId, certFingerprint);
     }
+    async _fetchV2SenderIKOnce(fromAid, senderDeviceId, groupId, certFingerprint) {
+        return await this._v2E2EE.fetchSenderIKOnce(fromAid, senderDeviceId, groupId, certFingerprint);
+    }
     _cacheV2PeerIKFromDevice(dev, fallbackAid = '') {
         const session = this._v2Session;
         if (!session || !isJsonObject(dev))
@@ -2850,11 +2931,17 @@ export class AUNClient {
      *
      * @param upToSeq 确认到此 seq；省略则用当前 contiguous
      */
-    async _ackV2(upToSeq) {
-        return await this._v2E2EE.ackV2(upToSeq);
+    async _ackV2(upToSeq, inlineGeneration) {
+        return await this._v2E2EE.ackV2(upToSeq, inlineGeneration);
     }
-    /** 解密单条 V2 消息（与 Python `_decrypt_v2_message` 对齐）。缺 sender IK 时先入 pending，后台补齐后重试。 */
-    async _decryptV2Message(msg, allowPending = true) {
+    /**
+     * 解密单条 V2 消息（与 Python `_decrypt_v2_message` 对齐）。
+     *
+     * 默认保持 Pull / 普通 Push 的既有行为：缺 sender IK 时入 pending、失败发布
+     * undecryptable 事件、成功消费后触发 SPK 轮换。inline Push 在游标提交和
+     * Head/正文绑定校验前调用本入口时必须显式关闭这些副作用。
+     */
+    async _decryptV2Message(msg, allowPending = true, emitUndecryptable = true, rotateKeys = true, observeAgentMd = true) {
         const session = this._v2Session;
         if (!session)
             return null;
@@ -2870,7 +2957,8 @@ export class AUNClient {
             return null;
         }
         const e2eeMeta = v2E2eeMeta(envelope);
-        await this._observeAgentMdFromEnvelope(envelope);
+        if (observeAgentMd)
+            await this._observeAgentMdFromEnvelope(envelope);
         // 确定 spk_id 和 recipient_key_source
         let spkId = '';
         let recipientKeySource = '';
@@ -2920,55 +3008,62 @@ export class AUNClient {
         }
         catch (exc) {
             this._clientLog.warn(`V2 decrypt: SPK lookup failed seq=${String(msg.seq)} spk_id=${spkId}: ${String(exc)}`);
-            try {
-                const event = {
-                    message_id: String(msg.message_id ?? ''),
-                    from: String(msg.from_aid ?? ''),
-                    to: String(msg.to ?? ''),
-                    seq: msg.seq,
-                    timestamp: (msg.t_server ?? msg.timestamp),
-                    device_id: String(msg.device_id ?? ''),
-                    slot_id: String(msg.slot_id ?? ''),
-                    _decrypt_error: String(exc),
-                    _decrypt_stage: 'spk_lookup',
-                    _envelope_type: String(envelope.type ?? ''),
-                    _suite: String(envelope.suite ?? ''),
-                    _spk_id: spkId,
-                };
-                attachV2EnvelopeMetadata(event, e2eeMeta);
-                await this._dispatcher.publish(undecryptableEvent, event);
+            if (emitUndecryptable) {
+                try {
+                    const event = {
+                        message_id: String(msg.message_id ?? ''),
+                        from: String(msg.from_aid ?? ''),
+                        to: String(msg.to ?? ''),
+                        seq: msg.seq,
+                        timestamp: (msg.t_server ?? msg.timestamp),
+                        device_id: String(msg.device_id ?? ''),
+                        slot_id: String(msg.slot_id ?? ''),
+                        _decrypt_error: String(exc),
+                        _decrypt_stage: 'spk_lookup',
+                        _envelope_type: String(envelope.type ?? ''),
+                        _suite: String(envelope.suite ?? ''),
+                        _spk_id: spkId,
+                    };
+                    attachV2EnvelopeMetadata(event, e2eeMeta);
+                    await this._dispatcher.publish(undecryptableEvent, event);
+                }
+                catch { /* publish 异常不影响主流程 */ }
             }
-            catch { /* publish 异常不影响主流程 */ }
             return null;
         }
         const fromAid = String(msg.from_aid ?? '');
         const senderDeviceId = String(aad.from_device ?? '');
         const senderCertFingerprint = String(envelope.sender_cert_fingerprint ?? '').trim().toLowerCase();
-        const senderPubDer = await this._getV2SenderPubDer(fromAid, senderDeviceId, senderCertFingerprint);
+        let senderPubDer = await this._getV2SenderPubDer(fromAid, senderDeviceId, senderCertFingerprint);
         if (!senderPubDer) {
             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 });
                 return null;
             }
-            try {
-                const event = {
-                    message_id: String(msg.message_id ?? ''),
-                    from: fromAid,
-                    to: String(msg.to ?? ''),
-                    seq: msg.seq,
-                    timestamp: (msg.t_server ?? msg.timestamp),
-                    device_id: String(msg.device_id ?? ''),
-                    slot_id: String(msg.slot_id ?? ''),
-                    _decrypt_error: 'sender_ik_not_found',
-                    _decrypt_stage: 'sender_ik',
-                    _envelope_type: String(envelope.type ?? ''),
-                    _suite: String(envelope.suite ?? ''),
-                };
-                attachV2EnvelopeMetadata(event, e2eeMeta);
-                await this._dispatcher.publish(undecryptableEvent, event);
+            if (emitUndecryptable) {
+                try {
+                    const event = {
+                        message_id: String(msg.message_id ?? ''),
+                        from: fromAid,
+                        to: String(msg.to ?? ''),
+                        seq: msg.seq,
+                        timestamp: (msg.t_server ?? msg.timestamp),
+                        device_id: String(msg.device_id ?? ''),
+                        slot_id: String(msg.slot_id ?? ''),
+                        _decrypt_error: 'sender_ik_not_found',
+                        _decrypt_stage: 'sender_ik',
+                        _envelope_type: String(envelope.type ?? ''),
+                        _suite: String(envelope.suite ?? ''),
+                    };
+                    attachV2EnvelopeMetadata(event, e2eeMeta);
+                    await this._dispatcher.publish(undecryptableEvent, event);
+                }
+                catch { /* publish 异常不影响主流程 */ }
             }
-            catch { /* publish 异常不影响主流程 */ }
             return null;
         }
         let plaintext;
@@ -2977,43 +3072,35 @@ export class AUNClient {
         }
         catch (exc) {
             this._clientLog.warn(`V2 decrypt failed for msg seq=${String(msg.seq)}: ${String(exc)}`);
-            try {
-                const event = {
-                    message_id: String(msg.message_id ?? ''),
-                    from: fromAid,
-                    to: String(msg.to ?? ''),
-                    seq: msg.seq,
-                    timestamp: (msg.t_server ?? msg.timestamp),
-                    device_id: String(msg.device_id ?? ''),
-                    slot_id: String(msg.slot_id ?? ''),
-                    _decrypt_error: String(exc),
-                    _decrypt_stage: 'decrypt',
-                    _envelope_type: String(envelope.type ?? ''),
-                    _suite: String(envelope.suite ?? ''),
-                };
-                attachV2EnvelopeMetadata(event, e2eeMeta);
-                await this._dispatcher.publish(undecryptableEvent, event);
+            if (emitUndecryptable) {
+                try {
+                    const event = {
+                        message_id: String(msg.message_id ?? ''),
+                        from: fromAid,
+                        to: String(msg.to ?? ''),
+                        seq: msg.seq,
+                        timestamp: (msg.t_server ?? msg.timestamp),
+                        device_id: String(msg.device_id ?? ''),
+                        slot_id: String(msg.slot_id ?? ''),
+                        _decrypt_error: String(exc),
+                        _decrypt_stage: 'decrypt',
+                        _envelope_type: String(envelope.type ?? ''),
+                        _suite: String(envelope.suite ?? ''),
+                    };
+                    attachV2EnvelopeMetadata(event, e2eeMeta);
+                    await this._dispatcher.publish(undecryptableEvent, event);
+                }
+                catch { /* publish 异常不影响主流程 */ }
             }
-            catch { /* publish 异常不影响主流程 */ }
             return null;
         }
         if (plaintext == null)
             return null;
         // 消费触发 SPK 轮换（fire-and-forget，不阻塞消息处理）
-        if (groupIdForKeys && recipientKeySource === 'group_device_prekey' && session.isLastUploadedGroupSPK(groupIdForKeys, spkId)) {
-            this._v2E2EE.scheduleGroupSpkRotation(groupIdForKeys, { reason: 'group_spk_consumed' });
-        }
-        else if (groupIdForKeys && recipientKeySource === 'peer_device_prekey') {
-            this._v2E2EE.scheduleGroupSpkRegistrationAfterPeerFallback(groupIdForKeys);
-        }
-        else if (!groupIdForKeys && session.isLastUploadedSPK(spkId)) {
-            const callFn = async (method, params) => this.call(method, params);
-            session.rotateSPK(callFn).catch(exc => {
-                this._clientLog.debug(`V2 SPK rotation failed (non-fatal): ${exc}`);
-            });
-        }
+        if (rotateKeys)
+            this._scheduleV2KeyRotationForMessage(msg, envelope);
         const e2ee = v2E2eeMeta(envelope);
-        const result = {
+        let result = {
             message_id: String(msg.message_id ?? ''),
             from: fromAid,
             to: this._aid ?? '',
@@ -3031,8 +3118,67 @@ export class AUNClient {
             result.slot_id = msg.slot_id;
         attachGatewayProximity(result, msg);
         attachV2EnvelopeMetadata(result, e2ee);
+        if (groupIdForKeys)
+            result = normalizeGroupMentionMode(result, msg, envelope);
         return result;
     }
+    _scheduleV2KeyRotationForMessage(msg, envelope) {
+        const session = this._v2Session;
+        if (!session)
+            return;
+        let spkId = '';
+        let recipientKeySource = '';
+        const recipientObj = envelope.recipient;
+        if (recipientObj && typeof recipientObj === 'object') {
+            spkId = String(recipientObj.spk_id ?? '');
+            recipientKeySource = String(recipientObj.key_source ?? '');
+        }
+        else if (Array.isArray(envelope.recipients)) {
+            spkId = String(msg.spk_id ?? '');
+            for (const row of envelope.recipients) {
+                if (Array.isArray(row) && row.length >= 6 && row[0] === this._aid && (row[1] === this._deviceId || row[1] === '')) {
+                    if (!spkId)
+                        spkId = String(row[5] ?? '');
+                    recipientKeySource = row.length > 3 ? String(row[3] ?? '') : '';
+                    break;
+                }
+            }
+        }
+        const aad = isJsonObject(envelope.aad) ? envelope.aad : {};
+        const groupId = String(msg.group_id ?? aad.group_id ?? envelope.group_id ?? '').trim();
+        if (groupId && recipientKeySource === 'group_device_prekey' && session.isLastUploadedGroupSPK(groupId, spkId)) {
+            this._v2E2EE.scheduleGroupSpkRotation(groupId, { reason: 'group_spk_consumed' });
+        }
+        else if (groupId && recipientKeySource === 'peer_device_prekey') {
+            this._v2E2EE.scheduleGroupSpkRegistrationAfterPeerFallback(groupId);
+        }
+        else if (!groupId && session.isLastUploadedSPK(spkId)) {
+            const callFn = async (method, params) => this.call(method, params);
+            session.rotateSPK(callFn).catch(exc => {
+                this._clientLog.debug(`V2 SPK rotation failed (non-fatal): ${exc}`);
+            });
+        }
+    }
+    /** inline 消息仅在应用提交且 ACK 成功后补做可变副作用。 */
+    async _postInlineV2CommitAndAck(msg) {
+        const envJson = msg.envelope_json;
+        if (!envJson || typeof envJson !== 'string')
+            return;
+        let envelope;
+        try {
+            envelope = JSON.parse(envJson);
+        }
+        catch {
+            return;
+        }
+        try {
+            await this._observeAgentMdFromEnvelope(envelope);
+        }
+        catch (exc) {
+            this._clientLog.debug(`inline V2 agent.md observe failed (non-fatal): ${String(exc)}`);
+        }
+        this._scheduleV2KeyRotationForMessage(msg, envelope);
+    }
     /**
      * V2 Group 加密发送（推测性：用缓存 bootstrap 直接发，失败刷新重试一次）。
      *
@@ -3067,8 +3213,8 @@ export class AUNClient {
      * @param groupId 群 ID
      * @param upToSeq 确认到此 seq；省略则用当前 contiguous
      */
-    async _ackGroupV2(groupId, upToSeq) {
-        return await this._v2E2EE.ackGroupV2(groupId, upToSeq);
+    async _ackGroupV2(groupId, upToSeq, groupAid, inlineGeneration) {
+        return await this._v2E2EE.ackGroupV2(groupId, upToSeq, groupAid, inlineGeneration);
     }
     /**
      * V2 P2P 多设备 wrap envelope 构造（不发送）。
@@ -3197,13 +3343,56 @@ export class AUNClient {
             this._backgroundRpcDepth = Math.max(0, this._backgroundRpcDepth - 1);
         }
     }
-    async _runPullSerialized(key, operation) {
-        return await this._rpcPipeline.runPullSerialized(key, operation);
+    async _runPullSerialized(key, operation, background = false) {
+        return await this._rpcPipeline.runPullSerialized(key, operation, background);
     }
-    /** 可取消的 sleep */
-    _sleep(ms) {
+    async _withPullResponseProcessing(ns, operation) {
+        if (!ns)
+            return await operation();
+        this._pullResponseKeys.set(ns, (this._pullResponseKeys.get(ns) ?? 0) + 1);
+        try {
+            return await operation();
+        }
+        finally {
+            const remaining = (this._pullResponseKeys.get(ns) ?? 1) - 1;
+            if (remaining <= 0)
+                this._pullResponseKeys.delete(ns);
+            else
+                this._pullResponseKeys.set(ns, remaining);
+        }
+    }
+    /** 每轮重连从当前地址之后开始轮转，避免永远黏在失效的首个 Gateway。 */
+    _orderedReconnectGateways(params) {
+        const raw = Array.isArray(params.gateways) && params.gateways.length > 0
+            ? params.gateways
+            : (this._gatewayCandidates.length > 0 ? this._gatewayCandidates : [params.gateway ?? this._gatewayUrl]);
+        const candidates = [...new Set(raw.map((item) => String(item ?? '').trim()).filter(Boolean))];
+        if (candidates.length <= 1)
+            return candidates;
+        const current = String(this._gatewayUrl ?? params.gateway ?? '').trim();
+        const index = candidates.indexOf(current);
+        const start = index >= 0 ? (index + 1) % candidates.length : 0;
+        return [...candidates.slice(start), ...candidates.slice(0, start)];
+    }
+    /** 可取消的 sleep；重连终止时立即释放退避等待。 */
+    _sleep(ms, signal) {
         return new Promise((resolve) => {
-            globalThis.setTimeout(resolve, ms);
+            let settled = false;
+            const finish = () => {
+                if (settled)
+                    return;
+                settled = true;
+                globalThis.clearTimeout(timer);
+                signal?.removeEventListener('abort', finish);
+                resolve();
+            };
+            const timer = globalThis.setTimeout(finish, ms);
+            if (signal) {
+                if (signal.aborted)
+                    finish();
+                else
+                    signal.addEventListener('abort', finish, { once: true });
+            }
         });
     }
 }