@agentunion/fastaun-browser 0.5.4 → 0.5.8

package/dist/client/lifecycle.js

@@ -1,5 +1,25 @@
-import { StateError, ValidationError } from '../errors.js';
 import { ConnectionState } from '../types.js';
+import { AUNError, AuthError, ConnectionError, PermissionError, StateError, TimeoutError, ValidationError, } from '../errors.js';
+function shouldRetryInitialConnect(error) {
+    if (error instanceof AuthError) {
+        const message = String(error.message ?? '').toLowerCase();
+        return message.includes('long_connection_already_exists')
+            || message.includes('long connection already exists')
+            || message.includes('aid_login1_failed')
+            || message.includes('aid_login2_failed');
+    }
+    if (error instanceof PermissionError || error instanceof ValidationError || error instanceof StateError) {
+        return false;
+    }
+    if (error instanceof ConnectionError || error instanceof TimeoutError) {
+        return true;
+    }
+    if (error instanceof AUNError) {
+        return error.retryable;
+    }
+    // 浏览器底层 WebSocket/网络异常不一定继承 SDK 错误类型，默认视为瞬时错误。
+    return true;
+}
 const PUBLIC_CONNECTION_OPTION_KEYS = new Set([
     'auto_reconnect',
     'connect_timeout',
@@ -70,9 +90,144 @@ export class LifecycleController {
     constructor(runtime) {
         this.runtime = runtime;
     }
+    beginConnectionAttempt() {
+        const client = this.runtime.client;
+        if (client._closing || client.state === ConnectionState.CLOSED) {
+            throw new StateError('connect not allowed on a closed client');
+        }
+        if (client._disconnecting) {
+            throw new StateError('connect not allowed while disconnect is in progress');
+        }
+        if (client._connectDone) {
+            throw new StateError('connect already in progress');
+        }
+        const owner = new AbortController();
+        let resolveDone;
+        const done = new Promise((resolve) => { resolveDone = resolve; });
+        client._connectAbort = owner;
+        client._connectDoneOwner = owner;
+        client._connectDone = done;
+        client._connectDoneResolve = resolveDone;
+        client._connectEventDispatchDepth = Number(client._connectEventDispatchDepth ?? 0);
+        return owner;
+    }
+    finishConnectionAttempt(owner) {
+        const client = this.runtime.client;
+        if (client._connectDoneOwner !== owner)
+            return;
+        const resolveDone = client._connectDoneResolve;
+        if (client._connectAbort === owner)
+            client._connectAbort = null;
+        client._connectDoneOwner = null;
+        client._connectDone = null;
+        client._connectDoneResolve = null;
+        resolveDone?.();
+    }
+    ownsConnectionAttempt(owner) {
+        if (!owner)
+            return true;
+        const client = this.runtime.client;
+        return client._connectAbort === owner
+            && !owner.signal.aborted
+            && !client._closing
+            && !client._disconnecting;
+    }
+    assertConnectionAttemptOwner(owner) {
+        if (owner && !this.ownsConnectionAttempt(owner)) {
+            throw new StateError('connection attempt superseded');
+        }
+    }
+    assertAttemptOwners(connectionOwner, reconnectOwner) {
+        this.assertConnectionAttemptOwner(connectionOwner);
+        this.runtime.client._assertReconnectOwner?.(reconnectOwner);
+    }
+    async waitForAttempt(operation, connectionOwner, reconnectOwner) {
+        const owner = connectionOwner ?? reconnectOwner;
+        if (!owner)
+            return operation;
+        this.assertAttemptOwners(connectionOwner, reconnectOwner);
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const finish = (callback) => {
+                if (settled)
+                    return;
+                settled = true;
+                owner.signal.removeEventListener('abort', onAbort);
+                callback();
+            };
+            const onAbort = () => finish(() => reject(connectionOwner
+                ? new StateError('connection attempt superseded')
+                : new ConnectionError('reconnect attempt superseded')));
+            owner.signal.addEventListener('abort', onAbort, { once: true });
+            if (owner.signal.aborted) {
+                onAbort();
+                return;
+            }
+            operation.then((value) => finish(() => {
+                try {
+                    this.assertAttemptOwners(connectionOwner, reconnectOwner);
+                    resolve(value);
+                }
+                catch (err) {
+                    reject(err);
+                }
+            }), (err) => finish(() => reject(err)));
+        });
+    }
+    async publishConnectionEvent(owner, event, payload) {
+        const client = this.runtime.client;
+        this.assertConnectionAttemptOwner(owner);
+        client._connectEventDispatchDepth = Number(client._connectEventDispatchDepth ?? 0) + 1;
+        try {
+            await client._dispatcher.publish(event, payload);
+        }
+        finally {
+            client._connectEventDispatchDepth -= 1;
+        }
+        return this.ownsConnectionAttempt(owner);
+    }
+    async cancelConnectionAttemptAndWait() {
+        const client = this.runtime.client;
+        const owner = client._connectDoneOwner;
+        const done = client._connectDone;
+        if (!owner || !done)
+            return;
+        if (client._connectAbort === owner)
+            client._connectAbort = null;
+        owner.abort();
+        // READY 事件按顺序同步分发；handler 内等待所属 connect 会自锁。
+        if (Number(client._connectEventDispatchDepth ?? 0) > 0)
+            return;
+        let timeout = null;
+        try {
+            await Promise.race([
+                done,
+                new Promise((_, reject) => {
+                    timeout = setTimeout(() => reject(new StateError('timed out waiting for connect attempt to stop')), 1_000);
+                }),
+            ]);
+        }
+        finally {
+            if (timeout !== null)
+                clearTimeout(timeout);
+        }
+    }
+    /** 首连后台重试使用的完整尝试；不在失败时再次创建重连任务。 */
+    async retryInitialConnect(opts, reconnectOwner) {
+        const client = this.runtime.client;
+        client._assertReconnectOwner?.(reconnectOwner);
+        this.runtime.lifecycle.setState('standby');
+        client._gatewayUrl = null;
+        client._gatewayCandidates = [];
+        return this.connect(opts, true, reconnectOwner);
+    }
     async authenticate(options = {}) {
         const client = this.runtime.client;
         const tStart = Date.now();
+        const inheritedAttempt = client._activeAuthenticateAttempt;
+        let connectionOwner = inheritedAttempt?.connectionOwner;
+        const reconnectOwner = inheritedAttempt?.reconnectOwner;
+        let ownsPublicAttempt = false;
         const target = client._currentAid?.aid ?? client._aid ?? '';
         if (!target || !client._currentAid?.isPrivateKeyValid()) {
             throw new StateError('authenticate requires a loaded AID with a valid private key');
@@ -87,14 +242,52 @@ export class LifecycleController {
         if ('aid' in options || 'access_token' in options || 'token' in options || 'kite_token' in options) {
             throw new ValidationError('authenticate options must not include aid or token fields; load an AID object first');
         }
+        if (!connectionOwner && !reconnectOwner) {
+            connectionOwner = this.beginConnectionAttempt();
+            ownsPublicAttempt = true;
+        }
+        this.assertAttemptOwners(connectionOwner, reconnectOwner);
         this.runtime.lifecycle.setState('connecting');
         try {
-            const gateway = String(client._gatewayUrl ?? await client._resolveGatewayForAid(target)).trim();
-            const result = await client._auth.authenticate(gateway, target);
+            let discovered;
+            if (typeof client._resolveGatewayCandidatesForAid === 'function') {
+                discovered = await this.waitForAttempt(Promise.resolve(client._resolveGatewayCandidatesForAid(target)), connectionOwner, reconnectOwner);
+            }
+            else if (client._gatewayUrl) {
+                discovered = [String(client._gatewayUrl).trim()];
+            }
+            else {
+                const gateway = await this.waitForAttempt(Promise.resolve(client._resolveGatewayForAid(target)), connectionOwner, reconnectOwner);
+                discovered = [String(gateway).trim()];
+            }
+            const gateways = [...new Set(discovered
+                    .map((item) => String(item ?? '').trim()).filter(Boolean))];
+            if (gateways.length === 0)
+                throw new StateError('gateway discovery returned no candidates');
+            let gateway = gateways[0];
+            let result = null;
+            let lastError = null;
+            for (const candidate of gateways) {
+                try {
+                    result = await this.waitForAttempt(Promise.resolve(client._auth.authenticate(candidate, target)), connectionOwner, reconnectOwner);
+                    gateway = candidate;
+                    break;
+                }
+                catch (exc) {
+                    lastError = exc;
+                    if (gateways.length === 1)
+                        throw exc;
+                    client._clientLog.warn(`authenticate gateway failed, trying next: gateway=${candidate}, error=${String(exc)}`);
+                }
+            }
+            if (result === null)
+                throw (lastError instanceof Error ? lastError : new Error(String(lastError)));
+            this.assertAttemptOwners(connectionOwner, reconnectOwner);
+            client._gatewayCandidates = gateways;
             this.runtime.lifecycle.setGatewayUrl(gatewayFromAuthResult(result, gateway));
             let loadedIdentity = null;
             try {
-                loadedIdentity = await client._auth.loadIdentityOrNone(target);
+                loadedIdentity = await this.waitForAttempt(Promise.resolve(client._auth.loadIdentityOrNone(target)), connectionOwner, reconnectOwner);
             }
             catch (exc) {
                 client._clientLog.debug(`authenticate identity reload skipped: ${exc instanceof Error ? exc.message : String(exc)}`);
@@ -106,13 +299,19 @@ export class LifecycleController {
             return result;
         }
         catch (err) {
+            this.assertAttemptOwners(connectionOwner, reconnectOwner);
             this.runtime.lifecycle.setState('standby');
             this.runtime.lifecycle.setError(err instanceof Error ? err : new Error(String(err)), 'AUTHENTICATE_FAILED');
             client._clientLog.debug(`authenticate exit (error): elapsed=${Date.now() - tStart}ms err=${err instanceof Error ? err.message : String(err)}`);
             throw err;
         }
+        finally {
+            if (ownsPublicAttempt && connectionOwner) {
+                this.finishConnectionAttempt(connectionOwner);
+            }
+        }
     }
-    async connect(opts) {
+    async connect(opts, fromInitialReconnect = false, reconnectOwner) {
         const client = this.runtime.client;
         const tStart = Date.now();
         if (opts !== undefined && opts !== null && typeof opts === 'object') {
@@ -126,157 +325,303 @@ export class LifecycleController {
         if (!target || !client._currentAid?.isPrivateKeyValid()) {
             throw new StateError('connect requires a loaded AID with a valid private key');
         }
-        const options = {};
-        if (opts?.auto_reconnect !== undefined)
-            options.auto_reconnect = opts.auto_reconnect;
-        if (opts?.heartbeat_interval !== undefined)
-            options.heartbeat_interval = opts.heartbeat_interval;
-        if (opts?.connect_timeout !== undefined || opts?.call_timeout !== undefined) {
-            options.timeouts = {
-                ...(opts.connect_timeout !== undefined ? { connect: opts.connect_timeout } : {}),
-                ...(opts.call_timeout !== undefined ? { call: opts.call_timeout } : {}),
-            };
-        }
-        if (opts?.retry !== undefined)
-            options.retry = opts.retry;
-        if (opts?.retry_initial_delay !== undefined || opts?.retry_max_delay !== undefined || opts?.retry_max_attempts !== undefined) {
-            const baseRetry = isRecord(options.retry)
-                ? { ...options.retry }
-                : { initial_delay: 1, max_delay: 64, max_attempts: 0 };
-            options.retry = {
-                ...baseRetry,
-                ...(opts.retry_initial_delay !== undefined ? { initial_delay: opts.retry_initial_delay } : {}),
-                ...(opts.retry_max_delay !== undefined ? { max_delay: opts.retry_max_delay } : {}),
-                ...(opts.retry_max_attempts !== undefined ? { max_attempts: opts.retry_max_attempts } : {}),
+        const connectionOwner = fromInitialReconnect ? undefined : this.beginConnectionAttempt();
+        try {
+            const options = {};
+            if (opts?.auto_reconnect !== undefined)
+                options.auto_reconnect = opts.auto_reconnect;
+            if (opts?.heartbeat_interval !== undefined)
+                options.heartbeat_interval = opts.heartbeat_interval;
+            if (opts?.connect_timeout !== undefined || opts?.call_timeout !== undefined) {
+                options.timeouts = {
+                    ...(opts.connect_timeout !== undefined ? { connect: opts.connect_timeout } : {}),
+                    ...(opts.call_timeout !== undefined ? { call: opts.call_timeout } : {}),
+                };
+            }
+            if (opts?.retry !== undefined)
+                options.retry = opts.retry;
+            if (opts?.retry_initial_delay !== undefined || opts?.retry_max_delay !== undefined || opts?.retry_max_attempts !== undefined) {
+                const baseRetry = isRecord(options.retry)
+                    ? { ...options.retry }
+                    : { initial_delay: 1, max_delay: 64, max_attempts: 0 };
+                options.retry = {
+                    ...baseRetry,
+                    ...(opts.retry_initial_delay !== undefined ? { initial_delay: opts.retry_initial_delay } : {}),
+                    ...(opts.retry_max_delay !== undefined ? { max_delay: opts.retry_max_delay } : {}),
+                    ...(opts.retry_max_attempts !== undefined ? { max_attempts: opts.retry_max_attempts } : {}),
+                };
+            }
+            if (opts?.connection_kind !== undefined)
+                options.connection_kind = opts.connection_kind;
+            if (opts?.short_ttl_ms !== undefined)
+                options.short_ttl_ms = opts.short_ttl_ms;
+            if (opts?.delivery_mode !== undefined)
+                options.delivery_mode = opts.delivery_mode;
+            if (opts?.extra_info !== undefined)
+                options.extra_info = opts.extra_info;
+            if (opts?.background_sync !== undefined)
+                options.background_sync = opts.background_sync;
+            client._clientLog.debug(`connect enter: state=${client._state} aid=${client._aid ?? '-'}`);
+            const publicState = client.state;
+            const allowed = new Set([
+                ConnectionState.STANDBY,
+                ConnectionState.AUTHENTICATED,
+                ConnectionState.RETRY_BACKOFF,
+                ConnectionState.CONNECTION_FAILED,
+            ]);
+            const hasReconnectController = Boolean(client._reconnectAbort || client._reconnectActive);
+            if (!allowed.has(publicState) && !(hasReconnectController && !fromInitialReconnect)) {
+                client._clientLog.debug(`connect exit (error): elapsed=${Date.now() - tStart}ms err=invalid_state state=${client._state}`);
+                throw new StateError(`connect not allowed in state ${publicState}`);
+            }
+            // 显式 connect 开启新的连接意图，必须取消 standby/retry_backoff 窗口中
+            // 尚未完成的旧重连代；内部首连重试不能取消自己的控制器。
+            if (!fromInitialReconnect && hasReconnectController) {
+                await client._cancelReconnectAndWait();
+            }
+            else if (fromInitialReconnect) {
+                client._assertReconnectOwner?.(reconnectOwner);
+            }
+            if (publicState === ConnectionState.CONNECTION_FAILED) {
+                this.runtime.lifecycle.setRetryAttempt(0);
+                this.runtime.lifecycle.setError(null, null);
+            }
+            this.runtime.lifecycle.setNextRetryAt(null);
+            // 认证/发现发生在 session 参数可归一化之前，先保存会话选项，
+            // 这样首连失败也能沿用同一套退避与 auto_reconnect 配置。
+            this.runtime.lifecycle.setSession(null, client._buildSessionOptions({
+                ...options,
+                connection_kind: opts?.connection_kind ?? 'long',
+            }));
+            let authResult = null;
+            if (!client._gatewayUrl) {
+                const previousAttempt = client._activeAuthenticateAttempt;
+                client._activeAuthenticateAttempt = { connectionOwner, reconnectOwner };
+                try {
+                    authResult = await this.waitForAttempt(Promise.resolve(client.authenticate()), connectionOwner, reconnectOwner);
+                    this.assertAttemptOwners(connectionOwner, reconnectOwner);
+                }
+                catch (err) {
+                    this.assertAttemptOwners(connectionOwner, reconnectOwner);
+                    const connectError = err instanceof Error ? err : new Error(String(err));
+                    this.runtime.lifecycle.setError(connectError, 'CONNECT_FAILED');
+                    if (!fromInitialReconnect && client._sessionOptions?.auto_reconnect && shouldRetryInitialConnect(connectError)
+                        && typeof client._handleTransportDisconnect === 'function') {
+                        try {
+                            await client._handleTransportDisconnect(connectError, undefined, opts ?? {});
+                        }
+                        catch (reconnectErr) {
+                            client._clientLog.warn(`initial reconnect scheduling failed: ${reconnectErr instanceof Error ? reconnectErr.message : String(reconnectErr)}`);
+                        }
+                    }
+                    throw err;
+                }
+                finally {
+                    if (client._activeAuthenticateAttempt?.connectionOwner === connectionOwner
+                        && client._activeAuthenticateAttempt?.reconnectOwner === reconnectOwner) {
+                        client._activeAuthenticateAttempt = previousAttempt ?? null;
+                    }
+                }
+            }
+            this.assertAttemptOwners(connectionOwner, reconnectOwner);
+            this.runtime.lifecycle.setState('connecting');
+            const gateway = String(client._gatewayUrl ?? '').trim();
+            const accessToken = accessTokenFromAuthResult(authResult) || cachedAccessToken(client);
+            const params = {
+                ...options,
+                gateway,
+                ...(Array.isArray(client._gatewayCandidates) && client._gatewayCandidates.length > 0
+                    ? { gateways: [...client._gatewayCandidates] }
+                    : {}),
+                ...(accessToken ? { access_token: accessToken } : {}),
             };
-        }
-        if (opts?.connection_kind !== undefined)
-            options.connection_kind = opts.connection_kind;
-        if (opts?.short_ttl_ms !== undefined)
-            options.short_ttl_ms = opts.short_ttl_ms;
-        if (opts?.delivery_mode !== undefined)
-            options.delivery_mode = opts.delivery_mode;
-        if (opts?.extra_info !== undefined)
-            options.extra_info = opts.extra_info;
-        if (opts?.background_sync !== undefined)
-            options.background_sync = opts.background_sync;
-        client._clientLog.debug(`connect enter: state=${client._state} aid=${client._aid ?? '-'}`);
-        const publicState = client.state;
-        const allowed = new Set([
-            ConnectionState.STANDBY,
-            ConnectionState.AUTHENTICATED,
-            ConnectionState.RETRY_BACKOFF,
-            ConnectionState.CONNECTION_FAILED,
-        ]);
-        if (!allowed.has(publicState)) {
-            client._clientLog.debug(`connect exit (error): elapsed=${Date.now() - tStart}ms err=invalid_state state=${client._state}`);
-            throw new StateError(`connect not allowed in state ${publicState}`);
-        }
-        if (publicState === ConnectionState.RETRY_BACKOFF && client._reconnectAbort) {
-            client._reconnectAbort.abort();
-            this.runtime.lifecycle.clearReconnectState();
-        }
-        if (publicState === ConnectionState.CONNECTION_FAILED) {
-            this.runtime.lifecycle.setRetryAttempt(0);
-            this.runtime.lifecycle.setError(null, null);
-        }
-        this.runtime.lifecycle.setNextRetryAt(null);
-        let authResult = null;
-        if (!client._gatewayUrl) {
-            authResult = await client.authenticate();
-        }
-        this.runtime.lifecycle.setState('connecting');
-        const gateway = String(client._gatewayUrl ?? '').trim();
-        const accessToken = accessTokenFromAuthResult(authResult) || cachedAccessToken(client);
-        const params = { ...options, gateway, ...(accessToken ? { access_token: accessToken } : {}) };
-        const normalized = client._normalizeConnectParams(params);
-        this.runtime.lifecycle.setSession(normalized, client._buildSessionOptions(normalized));
-        client._transport.setTimeout(client._sessionOptions.timeouts.call);
-        this.runtime.lifecycle.setClosing(false);
-        const gateways = client._resolveGateways(normalized);
-        let lastErr = null;
-        for (const gw of gateways) {
-            try {
-                const gwParams = { ...normalized, gateway: gw };
-                await client._connectOnce(gwParams, true);
-                client._clientLog.debug(`connect exit: elapsed=${Date.now() - tStart}ms state=${client._state}`);
-                return;
+            const normalized = client._normalizeConnectParams(params);
+            this.runtime.lifecycle.setSession(normalized, client._buildSessionOptions(normalized));
+            const connectTimeoutSec = client._sessionOptions.timeouts.connect;
+            client._transport.setConnectTimeout(connectTimeoutSec != null ? connectTimeoutSec : 5);
+            const callTimeoutSec = client._sessionOptions.timeouts.call;
+            client._transport.setTimeout(callTimeoutSec != null ? callTimeoutSec : 35);
+            this.assertAttemptOwners(connectionOwner, reconnectOwner);
+            this.runtime.lifecycle.setClosing(false);
+            const gateways = client._resolveGateways(normalized);
+            let lastErr = null;
+            for (const gw of gateways) {
+                try {
+                    const gwParams = { ...normalized, gateway: gw };
+                    await this.waitForAttempt(Promise.resolve(client._connectOnce(gwParams, true, reconnectOwner)), connectionOwner, reconnectOwner);
+                    this.assertAttemptOwners(connectionOwner, reconnectOwner);
+                    client._clientLog.debug(`connect exit: elapsed=${Date.now() - tStart}ms state=${client._state}`);
+                    return;
+                }
+                catch (err) {
+                    lastErr = err;
+                    this.assertAttemptOwners(connectionOwner, reconnectOwner);
+                    try {
+                        await client._transport.close();
+                    }
+                    catch (closeErr) {
+                        client._clientLog.debug(`connect gateway cleanup skipped: ${closeErr instanceof Error ? closeErr.message : String(closeErr)}`);
+                    }
+                    if (gateways.length > 1) {
+                        client._clientLog.warn(`connect: gateway ${gw} failed, trying next: ${err instanceof Error ? err.message : String(err)}`);
+                    }
+                    if (client._state === 'connecting' || client._state === 'authenticating') {
+                        this.runtime.lifecycle.setState('connecting');
+                    }
+                }
             }
-            catch (err) {
-                lastErr = err;
-                if (gateways.length > 1) {
-                    client._clientLog.warn(`connect: gateway ${gw} failed, trying next: ${err instanceof Error ? err.message : String(err)}`);
+            if (client._state === 'connecting' || client._state === 'authenticating') {
+                this.runtime.lifecycle.setState(client._currentAid || client._aid ? 'standby' : 'idle');
+            }
+            const connectError = lastErr instanceof Error ? lastErr : new Error(String(lastErr));
+            this.runtime.lifecycle.setError(connectError, 'CONNECT_FAILED');
+            if (!fromInitialReconnect && client._sessionOptions?.auto_reconnect && shouldRetryInitialConnect(connectError)
+                && typeof client._handleTransportDisconnect === 'function') {
+                try {
+                    // 首连与已建立连接的断线共享同一重连入口，保证退避、并发闸门和取消语义一致。
+                    await client._handleTransportDisconnect(connectError, undefined, opts ?? {});
                 }
-                if (client._state === 'connecting' || client._state === 'authenticating') {
-                    this.runtime.lifecycle.setState('connecting');
+                catch (reconnectErr) {
+                    client._clientLog.warn(`initial reconnect scheduling failed: ${reconnectErr instanceof Error ? reconnectErr.message : String(reconnectErr)}`);
                 }
             }
+            client._clientLog.debug(`connect exit (error): elapsed=${Date.now() - tStart}ms err=${lastErr instanceof Error ? lastErr.message : String(lastErr)}`);
+            throw lastErr;
         }
-        if (client._state === 'connecting' || client._state === 'authenticating') {
-            this.runtime.lifecycle.setState(client._currentAid || client._aid ? 'standby' : 'idle');
+        finally {
+            if (connectionOwner)
+                this.finishConnectionAttempt(connectionOwner);
+        }
+    }
+    lifecycleStopEventIsReentrant() {
+        const client = this.runtime.client;
+        return Boolean(client._lifecycleStopActive)
+            && Number(client._lifecycleStopEventDispatchDepth ?? 0) > 0;
+    }
+    scheduleReentrantClose() {
+        const client = this.runtime.client;
+        const tail = client._lifecycleStopTail;
+        if (!tail)
+            return;
+        void tail.then(() => this.close()).catch((err) => {
+            client._clientLog.warn(`reentrant close failed: ${err instanceof Error ? err.message : String(err)}`);
+        });
+    }
+    async publishLifecycleStopEvent(payload) {
+        const client = this.runtime.client;
+        client._lifecycleStopEventDispatchDepth = Number(client._lifecycleStopEventDispatchDepth ?? 0) + 1;
+        try {
+            await client._dispatcher.publish('state_change', payload);
+        }
+        finally {
+            client._lifecycleStopEventDispatchDepth -= 1;
+        }
+    }
+    async withLifecycleStop(operation, kind) {
+        const client = this.runtime.client;
+        const previous = client._lifecycleStopTail;
+        let release;
+        const gate = new Promise((resolve) => { release = resolve; });
+        // 首个 stop 操作要在当前调用栈内进入清理；只有已有 stop 时才排队等待。
+        // 这样既保持 stop 之间的串行化，也不让调用方观察到无意义的额外微任务延迟。
+        const tail = previous ? previous.catch(() => { }).then(() => gate) : gate;
+        client._lifecycleStopTail = tail;
+        if (previous)
+            await previous.catch(() => { });
+        client._lifecycleStopActive = true;
+        client._lifecycleStopKind = kind;
+        try {
+            return await operation();
+        }
+        finally {
+            client._lifecycleStopActive = false;
+            client._lifecycleStopKind = null;
+            release();
+            if (client._lifecycleStopTail === tail)
+                client._lifecycleStopTail = null;
         }
-        this.runtime.lifecycle.setError(lastErr instanceof Error ? lastErr : new Error(String(lastErr)), 'CONNECT_FAILED');
-        client._clientLog.debug(`connect exit (error): elapsed=${Date.now() - tStart}ms err=${lastErr instanceof Error ? lastErr.message : String(lastErr)}`);
-        throw lastErr;
     }
     async disconnect() {
         const client = this.runtime.client;
         const tStart = Date.now();
         client._clientLog.debug(`disconnect enter: state=${client._state}`);
-        if (client._closing) {
-            client._clientLog.debug(`disconnect exit: elapsed=${Date.now() - tStart}ms reason=closing`);
-            return;
-        }
-        if (![
-            ConnectionState.AUTHENTICATED,
-            ConnectionState.CONNECTING,
-            ConnectionState.READY,
-            ConnectionState.RETRY_BACKOFF,
-            ConnectionState.RECONNECTING,
-            ConnectionState.CONNECTION_FAILED,
-        ].includes(client.state)) {
-            client._clientLog.debug(`disconnect exit: elapsed=${Date.now() - tStart}ms reason=not_connected`);
+        if (client._closing || client._disconnecting || this.lifecycleStopEventIsReentrant())
             return;
+        client._disconnecting = true;
+        try {
+            return await this.withLifecycleStop(async () => {
+                if (client._closing) {
+                    client._clientLog.debug(`disconnect exit: elapsed=${Date.now() - tStart}ms reason=closing`);
+                    return;
+                }
+                const hasInitialReconnect = Boolean(client._reconnectActive || client._reconnectAbort || client._reconnectTask);
+                const hasConnect = Boolean(client._connectDone);
+                if (!([
+                    ConnectionState.AUTHENTICATED,
+                    ConnectionState.CONNECTING,
+                    ConnectionState.READY,
+                    ConnectionState.RETRY_BACKOFF,
+                    ConnectionState.RECONNECTING,
+                    ConnectionState.CONNECTION_FAILED,
+                ].includes(client.state)) && !hasInitialReconnect && !hasConnect) {
+                    client._clientLog.debug(`disconnect exit: elapsed=${Date.now() - tStart}ms reason=not_connected`);
+                    return;
+                }
+                // 不等待持久化或 transport.close，先隔离已在途的 inline Push 回调。
+                client._delivery.resetInlineAckState();
+                await client._cancelReconnectAndWait();
+                await this.cancelConnectionAttemptAndWait();
+                await client._saveSeqTrackerState();
+                client._stopBackgroundTasks();
+                await client._transport.close();
+                // close() 可能在 transport.close 等待期间抢先声明关闭意图；此时不得回写 standby。
+                if (client._closing)
+                    return;
+                this.runtime.lifecycle.resetForDisconnect('standby');
+                await this.publishLifecycleStopEvent({ state: client._publicState(client._state) });
+                client._clientLog.debug(`disconnect exit: elapsed=${Date.now() - tStart}ms`);
+            }, 'disconnect');
         }
-        await client._saveSeqTrackerState();
-        client._stopBackgroundTasks();
-        if (client._reconnectAbort) {
-            client._reconnectAbort.abort();
-            this.runtime.lifecycle.clearReconnectState();
+        finally {
+            client._disconnecting = false;
         }
-        await client._transport.close();
-        this.runtime.lifecycle.resetForDisconnect('standby');
-        await client._dispatcher.publish('state_change', { state: client._publicState(client._state) });
-        client._clientLog.debug(`disconnect exit: elapsed=${Date.now() - tStart}ms`);
     }
     async close() {
         const client = this.runtime.client;
         const tStart = Date.now();
         client._clientLog.debug(`close enter: state=${client._state}`);
+        // 关闭意图必须在第一个 await 前生效，阻止迟到的连接/重连结果复活客户端。
         this.runtime.lifecycle.setClosing(true);
-        await client._saveSeqTrackerState();
-        client._stopBackgroundTasks();
-        if (client._reconnectAbort) {
-            client._reconnectAbort.abort();
-            this.runtime.lifecycle.clearReconnectState();
+        client._delivery.resetInlineAckState();
+        if (this.lifecycleStopEventIsReentrant()) {
+            // 当前 stop 操作正在等待自己的 state_change handler；直接等待闸门会自锁。
+            if (client._lifecycleStopKind !== 'close')
+                this.scheduleReentrantClose();
+            return;
         }
-        if (client._state === 'idle' || client._state === 'closed') {
+        return this.withLifecycleStop(async () => {
+            await client._cancelReconnectAndWait();
+            await this.cancelConnectionAttemptAndWait();
+            await client._saveSeqTrackerState();
+            client._stopBackgroundTasks();
+            if (client._state === 'idle' || client._state === 'closed') {
+                this.runtime.lifecycle.setState('closed');
+                client._resetSeqTrackingState();
+                client._clientLog.debug(`close exit: elapsed=${Date.now() - tStart}ms reason=already_idle`);
+                return;
+            }
+            try {
+                await client._transport.call('auth.logout', {});
+            }
+            catch (err) {
+                client._clientLog.warn(`auth.logout during close failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            await client._transport.close();
             this.runtime.lifecycle.setState('closed');
+            await this.publishLifecycleStopEvent({ state: client._publicState(client._state) });
             client._resetSeqTrackingState();
-            client._clientLog.debug(`close exit: elapsed=${Date.now() - tStart}ms reason=already_idle`);
-            return;
-        }
-        try {
-            await client._transport.call('auth.logout', {});
-        }
-        catch {
-            // auth.logout 失败不影响关闭流程。
-        }
-        await client._transport.close();
-        this.runtime.lifecycle.setState('closed');
-        await client._dispatcher.publish('state_change', { state: client._publicState(client._state) });
-        client._resetSeqTrackingState();
-        client._clientLog.debug(`close exit: elapsed=${Date.now() - tStart}ms`);
+            client._clientLog.debug(`close exit: elapsed=${Date.now() - tStart}ms`);
+        }, 'close');
     }
 }
 //# sourceMappingURL=lifecycle.js.map