@agentunion/fastaun 0.5.26 → 0.5.28

package/dist/client.js

@@ -27,6 +27,7 @@ import { validateAIDFormat, validateGroupIDFormat } from './validators.js';
 import { RPCTransport } from './transport.js';
 import { AuthFlow } from './auth.js';
 import { AgentMdManager, buildDefaultAgentMd } from './agent-md.js';
+import { AgentMdChangeCoordinator } from './agent-md-changes.js';
 import { GroupIndexMetaCache } from './group-index.js';
 import { SeqTracker } from './seq-tracker.js';
 import { ClientRuntime } from './client/runtime.js';
@@ -36,6 +37,8 @@ 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 { RiskController } from './risk-control.js';
+import { ControlMessageCoordinator, messageClassOf } from './client/control-messages.js';
 import { CollabClient } from './collab/client.js';
 import { DebugFacade, CredentialFacade, OrgFacade, GroupFacade, MailFacade, MessageFacade, StreamFacade } from './facades.js';
 import { StorageVFS } from './storage/vfs.js';
@@ -43,7 +46,7 @@ import { V2E2EECoordinator } from './client/v2-e2ee.js';
 import { GroupStateCoordinator } from './client/group-state.js';
 import { decryptMessage, } from './v2/e2ee/index.js';
 import { ecdsaVerifyRaw } from './v2/crypto/ecdsa.js';
-import { decryptedOwnershipJsonText } from './v2/e2ee/decrypt.js';
+import { decryptedOwnershipJsonText, decryptedMessagePayloadBytes } from './v2/e2ee/decrypt.js';
 import { isJsonObject, ConnectionState, STATE_TO_PUBLIC, } from './types.js';
 import { AID } from './aid.js';
 import { certFingerprint, certMatchesFingerprint, normalizeFingerprintHex, publicKeyMatchesFingerprint } from './cert-utils.js';
@@ -51,6 +54,7 @@ import { validateAgentMdCertificate, validateAgentMdDocument } from './agent-md-
 import { OwnershipFiles, OwnershipStorageAdapter, ownershipAid, ownershipFailure } from './ownership-v21.js';
 import { OwnershipWorkflow, OWNERSHIP_SDK_MESSAGE_TYPE, parseOwnershipMessage } from './ownership-workflow.js';
 import { canonicalJson, createCredential, createMemberCredential, signMembershipBinding, digest, validateMembershipBinding, verifyMembershipBinding, verifyCredentialSignature, createRepresentationProof, verifyServiceEvent, buildRequestBinding, validateRequestBinding, CredentialRenewal } from './org-protocol.js';
+import { SemanticProtocolError } from './semantic-protocol.js';
 function isPromiseLike(value) {
     return Boolean(value && typeof value.then === 'function');
 }
@@ -675,12 +679,12 @@ export class AUNClient {
         this._credentialRenewalAbort = abort;
         const current = () => this._credentialRenewalAbort === abort && !abort.signal.aborted && aid === this._aid && version === this._serviceEventIdentityVersion && ['ready', 'connected'].includes(this._state) && !this._closing && !this._disconnecting;
         const guard = { current, signal: abort.signal };
-        this._nextCredentialRevocationSyncAt ||= Date.now() + 3_600_000;
+        this._nextCredentialRevocationSyncAt = Date.now();
         const scan = async () => {
             const task = this._credentialRenewalScan.then(async () => {
                 if (!current())
                     return;
-                const syncRevocations = Date.now() >= this._nextCredentialRevocationSyncAt;
+                const syncRevocations = this._sessionOptions.connection_kind !== 'short' && Date.now() >= this._nextCredentialRevocationSyncAt;
                 if (syncRevocations)
                     this._nextCredentialRevocationSyncAt = Date.now() + 3_600_000;
                 await this._resumeCredentialRenewalAfterConnect(guard, syncRevocations);
@@ -710,13 +714,95 @@ export class AUNClient {
         }
         this._safeAsync(this._getCredentialRenewal().remember(credential, material));
     }
+    _semanticContextKey() {
+        return JSON.stringify([this._aid, this._currentAid?.certFingerprint, this._serviceEventIdentityVersion]);
+    }
+    _loadSemanticState() {
+        const state = (this._tokenStore._loadMetadataStrict?.(this._aid ?? '') ?? this._tokenStore.loadMetadata?.(this._aid ?? ''))?.semantic_credentials_v1;
+        return structuredClone(state ?? {});
+    }
+    _saveSemanticState(state) {
+        if (!this._aid)
+            throw new ValidationError('semantic credential persistence requires a loaded identity');
+        if (!this._tokenStore.saveMetadata)
+            throw new ValidationError('semantic credential metadata storage is unavailable');
+        this._tokenStore.saveMetadata(this._aid, { semantic_credentials_v1: state });
+    }
+    _semanticVerificationContext() {
+        const scope = this._semanticContextKey();
+        const current = () => { if (this._semanticContextKey() !== scope)
+            throw new ValidationError('semantic credential identity changed'); };
+        return {
+            resolveCertificate: async (fingerprint, aid, signedAt) => {
+                current();
+                const certificate = await this._fetchPeerCert(aid, fingerprint, undefined, signedAt);
+                current();
+                return certificate;
+            },
+            verifyCertificateTrust: async (material, context) => {
+                current();
+                const certificate = typeof material === 'string' && material.startsWith('-----BEGIN CERTIFICATE-----')
+                    ? material : new crypto.X509Certificate(typeof material === 'string' ? Buffer.from(material, 'base64') : material).toString();
+                const gateway = await this._resolveOwnershipCertificateGateway(context.expectedAID);
+                await this._auth.verifyPeerCertificate(gateway, certificate, context.expectedAID, context.signedAt);
+                await this._auth.verifyPeerCertificate(gateway, certificate, context.expectedAID, undefined, true);
+                current();
+            },
+        };
+    }
+    _semanticMessageVerificationContext() {
+        const actor = this._aid, device = this._deviceId, scope = this._semanticContextKey(), session = this._v2Session;
+        const trust = this._semanticVerificationContext();
+        const current = () => {
+            if (!actor || this._semanticContextKey() !== scope || device !== this._deviceId || session !== this._v2Session)
+                throw new SemanticProtocolError('SEMANTIC_IDENTITY_INVALID', 'semantic message verification identity changed');
+        };
+        const senderCertificate = async (sender, fingerprint, signedAt) => {
+            current();
+            const certificate = await this._fetchPeerCert(sender, fingerprint, undefined, signedAt);
+            if (!publicKeyMatchesFingerprint(certificate, fingerprint))
+                throw new SemanticProtocolError('SEMANTIC_IDENTITY_INVALID', 'historical sender key fingerprint differs');
+            current();
+            return certificate;
+        };
+        return {
+            selfAid: actor ?? '', selfDeviceId: device,
+            resolveDecryptionKeys: async (envelope) => {
+                current();
+                if (!session || session.aid !== actor || session.deviceId !== device)
+                    throw new SemanticProtocolError('SEMANTIC_STATE_UNAVAILABLE', 'authenticated V2 receiver session is unavailable');
+                const recipient = envelope.recipient;
+                const row = Array.isArray(envelope.recipients) ? envelope.recipients.find((item) => Array.isArray(item) && item.length >= 6 && item[0] === actor && (item[1] === device || item[1] === '')) : undefined;
+                if (!row && (!recipient || recipient.aid !== actor || recipient.device_id !== device && recipient.device_id !== ''))
+                    throw new SemanticProtocolError('SEMANTIC_IDENTITY_INVALID', 'original receiver row is unavailable');
+                const spkId = String(row ? row[5] ?? '' : recipient.spk_id ?? ''), aad = envelope.aad;
+                if (envelope.type === 'e2ee.group_encrypted') {
+                    const keys = session.getGroupDecryptKeys(String(aad.group_id ?? ''), spkId);
+                    return { ikPriv: keys.ikPriv, spkPriv: keys.spkPriv ?? undefined };
+                }
+                return session.getDecryptKeys(spkId);
+            },
+            resolveSenderKey: async (sender, _device, fingerprint, signedAt) => {
+                const certificate = await senderCertificate(sender, fingerprint, signedAt);
+                return new Uint8Array(new crypto.X509Certificate(certificate).publicKey.export({ type: 'spki', format: 'der' }));
+            },
+            verifySenderIdentity: async (sender, _device, fingerprint, signedAt, publicKey) => {
+                const certificate = await senderCertificate(sender, fingerprint, signedAt);
+                await trust.verifyCertificateTrust(certificate, { expectedAID: sender, signedAt, now: Math.trunc(Date.now() / 1000) });
+                const expected = new crypto.X509Certificate(certificate).publicKey.export({ type: 'spki', format: 'der' });
+                if (!expected.equals(Buffer.from(publicKey)))
+                    throw new SemanticProtocolError('SEMANTIC_IDENTITY_INVALID', 'historical sender identity differs from message key');
+                current();
+            },
+        };
+    }
     async _verifyIncomingServiceEvent(event, payload) {
         const targetAid = this._identity?.aid ?? '';
         const version = this._serviceEventIdentityVersion;
         const signal = this._serviceEventIdentityAbort.signal;
         const expiresAt = Number(payload?.expires_at);
         const transport = this._transport, connectionGeneration = transport?._connectionGeneration, workerGeneration = transport?._workerGeneration;
-        const current = () => version === this._serviceEventIdentityVersion && targetAid === (this._identity?.aid ?? '') && transport === this._transport && connectionGeneration === this._transport?._connectionGeneration && workerGeneration === this._transport?._workerGeneration && Date.now() / 1000 < expiresAt;
+        const current = () => version === this._serviceEventIdentityVersion && targetAid === (this._identity?.aid ?? '') && transport === this._transport && connectionGeneration === this._transport?._connectionGeneration && workerGeneration === this._transport?._workerGeneration && Date.now() / 1000 <= expiresAt + 300;
         const verified = await verifyServiceEvent(event, payload, { targetAid, resolveEventCertificate: (aid, fingerprint) => this._fetchServiceEventCertificate(aid, fingerprint), resolveCredentialService: this.resolveCredentialService });
         if (!current())
             throw new ValidationError('service event receiver identity changed');
@@ -846,6 +932,27 @@ export class AUNClient {
     _v2KeyStore;
     _v2SessionInitInFlight = null;
     _v2RuntimeGeneration = 0;
+    _controlMessageCoordinator;
+    _agentMdChanges;
+    _agentMdCommitUnsubscribe;
+    _installAgentMdChangeHooks() {
+        this._agentMdCommitUnsubscribe?.();
+        this._agentMdCommitUnsubscribe = AgentMdManager.subscribeCommits(this._configModel.aunPath, () => {
+            const coordinator = this._getAgentMdChanges();
+            if (this._state === 'ready')
+                void coordinator.flushNotifications().catch((error) => this._clientLog.debug(String(error)));
+            coordinator.schedule();
+        });
+    }
+    _getAgentMdChanges() {
+        return this._agentMdChanges ??= new AgentMdChangeCoordinator(this);
+    }
+    _onSdkControl(protocol, version, payload, senderAid) {
+        return this._getAgentMdChanges().handle(protocol, version, payload, senderAid);
+    }
+    _controlMessages() {
+        return this._controlMessageCoordinator ??= new ControlMessageCoordinator(this);
+    }
     /** V2 bootstrap 缓存：aid/group:id → 设备列表 + 时间戳 */
     _v2BootstrapCache = new Map();
     _v2SigCache = new Map();
@@ -865,6 +972,30 @@ export class AUNClient {
     _reconnectAbort = null;
     _reconnectTask = null;
     _reconnectEventDispatchDepth = 0;
+    _gatewayConnectionId = '';
+    _negotiatedCapabilities = {};
+    _riskNegotiated = false;
+    _riskRestoredAid = '';
+    _riskEvents = [];
+    _riskApplying = false;
+    _riskApplyTail = Promise.resolve();
+    _riskScalarReconnectAt = 0;
+    _riskHttpRetryAt = new Map();
+    _risk = new RiskController({
+        persist: async (state) => {
+            if (!this._aid || !this._tokenStore.saveMetadata || !isJsonObject(state.target) || state.target.aid !== this._aid || state.target.device_id !== this._deviceId)
+                throw new Error('risk persistence unavailable');
+            this._tokenStore.saveMetadata(this._aid, { ...(this._tokenStore.loadMetadata?.(this._aid) ?? {}), [`risk_state_v1:${this._deviceId}`]: state });
+        },
+        onState: (event) => {
+            if (this._riskApplying)
+                this._riskEvents.push(event);
+            else
+                this._dispatcher.enqueue('risk_state_changed', event);
+        },
+    });
+    _migrationPending = false;
+    _migrationRevision = new Map();
     _serverKicked = false;
     /** 缓存最近一次 gateway.disconnect 信息（含服务端附带的 detail），用于后续 connection.state 透传 */
     _lastDisconnectInfo = null;
@@ -973,6 +1104,7 @@ export class AUNClient {
             fetchEntityIdentity: (target, type) => this._freshEntityCertificate(target, type),
             fetchEntitySigner: (target, fingerprint) => this._freshEntitySigner(target, fingerprint),
         });
+        this._installAgentMdChangeHooks();
         this._transport = new RPCTransport({
             eventDispatcher: this._dispatcher,
             timeout: 35_000,
@@ -980,6 +1112,8 @@ export class AUNClient {
             logger: this._logger.for('aun_core.transport'),
             dnsNet,
         });
+        this._installRiskHooks();
+        this._transport.setClassMessageHandler((event, payload) => this._controlMessages().onPush(payload, event.includes('group.')));
         this._transport.setProtocolMetaObserver((meta) => this._observeRpcMeta(meta));
         this._transport.setServiceEventVerifier((event, payload) => this._verifyIncomingServiceEvent(event, payload), () => this._identity?.aid ?? '', () => this._serviceEventIdentityVersion);
         this._transport.setProtocolDisconnectCallback((err, closeCode) => this._handleTransportDisconnect(err, closeCode));
@@ -1014,6 +1148,8 @@ export class AUNClient {
         this._dispatcher.subscribeProtocol('_raw.message.read_changed', (data) => this._onRawReadChanged(data, 'p2p'));
         // V2 P2P 推送通知：收到通知后自动走 message.v2.pull 拉取并解密
         this._dispatcher.subscribeProtocol('_raw.peer.v2.message_received', (data) => {
+            if (this._controlMessages().onPush(data))
+                return;
             const sender = isJsonObject(data) ? String(data.sender_aid ?? '') : '';
             const ns = this._p2pPeerPullEnabled ? (sender ? this._delivery.peerNamespace(sender) : '') : this._aid ? `p2p:${this._aid}` : '';
             const hasInline = isJsonObject(data)
@@ -1025,6 +1161,8 @@ export class AUNClient {
         });
         // V2 群组消息推送通知：收到通知后自动走 group.v2.pull 拉取并解密
         this._dispatcher.subscribeProtocol('_raw.group.v2.message_created', (data) => {
+            if (this._controlMessages().onPush(data, true))
+                return;
             const groupId = isJsonObject(data)
                 ? String(data.group_id ?? '').trim()
                 : '';
@@ -1058,6 +1196,10 @@ export class AUNClient {
         }
         // 服务端主动断开通知：记录日志并标记不重连
         this._dispatcher.subscribeProtocol('_raw.gateway.disconnect', (data) => this._onGatewayDisconnect(data));
+        this._dispatcher.subscribeProtocol('notification', (data) => {
+            if (isJsonObject(data) && data.method === 'gateway.migrate' && !('id' in data))
+                this._onGatewayMigrate(data.params);
+        });
     }
     // ── 属性 ──────────────────────────────────────────────────
     /** 当前 AID */
@@ -1201,7 +1343,9 @@ export class AUNClient {
     async releaseSubaid(subAid) { return this._getOwnershipWorkflow().releaseSubaid(subAid); }
     async transferSubaid(subAid, newOwnerAid) { return this._getOwnershipWorkflow().transferSubaid(subAid, newOwnerAid); }
     async checkOwnershipConsensus(subAid) {
-        return this._createOwnershipFiles((aid) => this._agentMdManager._readOwnershipQuery(aid)).checkConsensus(ownershipAid(subAid ?? this._aid, 'sub_aid'));
+        const target = ownershipAid(subAid ?? this._aid, 'sub_aid');
+        const result = await this._createOwnershipFiles((aid) => this._agentMdManager._readOwnershipQuery(aid)).checkConsensus(target);
+        return result.status === 'consensus' ? result : this._checkOwnershipConsensusFresh(target);
     }
     async _checkOwnershipConsensusFresh(subAid) {
         return this._getOwnershipWorkflow().checkOwnershipConsensus(subAid);
@@ -1301,6 +1445,12 @@ export class AUNClient {
         return session.aid === this._aid && session.deviceId === this._deviceId;
     }
     _resetV2IdentityRuntime() {
+        this._controlMessageCoordinator?.close();
+        this._agentMdChanges?.close();
+        this._agentMdChanges = undefined;
+        this._negotiatedCapabilities = {};
+        this._riskNegotiated = false;
+        this._riskRestoredAid = '';
         this._v2RuntimeGeneration += 1;
         const keyStore = this._v2KeyStore;
         try {
@@ -1416,6 +1566,7 @@ export class AUNClient {
             fetchEntityIdentity: (target, type) => this._freshEntityCertificate(target, type),
             fetchEntitySigner: (target, fingerprint) => this._freshEntitySigner(target, fingerprint),
         });
+        this._installAgentMdChangeHooks();
         this._transport = new RPCTransport({
             eventDispatcher: this._dispatcher,
             timeout: 35_000,
@@ -1423,6 +1574,8 @@ export class AUNClient {
             logger: this._logger.for('aun_core.transport'),
             dnsNet,
         });
+        this._installRiskHooks();
+        this._transport.setClassMessageHandler((event, payload) => this._controlMessages().onPush(payload, event.includes('group.')));
         this._transport.setProtocolMetaObserver((meta) => this._observeRpcMeta(meta));
         this._transport.setServiceEventVerifier((event, payload) => this._verifyIncomingServiceEvent(event, payload), () => this._identity?.aid ?? '', () => this._serviceEventIdentityVersion);
         this._transport.setProtocolDisconnectCallback((err, closeCode) => this._handleTransportDisconnect(err, closeCode));
@@ -1526,6 +1679,7 @@ export class AUNClient {
     }
     /** 关闭连接 */
     async close() {
+        this._risk.close();
         this._peerGatewayCache.clear();
         return this._lifecycle.close();
     }
@@ -1536,6 +1690,155 @@ export class AUNClient {
     async disconnect() {
         return this._lifecycle.disconnect();
     }
+    get riskState() { return Object.freeze(structuredClone(this._risk.state)); }
+    _installRiskHooks() {
+        this._transport.setRiskControlHandler((payload) => this._onRiskControl(payload));
+        this._transport.setRequestAdmission((request) => this._risk.acquire(request));
+        this._transport.setRequestCheck((request) => this._risk.check(request));
+        this._auth.setRequestAdmission((request) => this._risk.acquire(request));
+        this._auth.setRiskSupport(() => this._gatewayUrl?.startsWith('wss://') === true);
+        this._auth.setHttpHandler((url, init, perform) => this._riskFetch(url, init, perform, 'http:gateway:pki'));
+        this._discovery.setHttpHandler((url, init, perform) => this._riskFetch(url, init, perform, new URL(url).pathname === '/health' ? 'http:gateway:health' : 'http:discovery:gateway'));
+        const aid = this._aid;
+        if (aid)
+            this._aidStore?.setRiskController(aid, async () => {
+                if (this._aid !== aid || this._deviceId !== this._aidStore?.deviceId)
+                    return null;
+                await this._restoreRiskState();
+                return this._risk.appliesTo(aid, this._deviceId) ? this._risk : null;
+            });
+        this._agentMdManager.setHttpHandler((url, init, perform) => {
+            const headers = new Headers(init.headers);
+            const scope = headers.has('X-AUN-Ownership-Check') || headers.has('X-AUN-Ownership-Stage') ? 'http:nameservice:ownership' : 'http:nameservice:agent_md';
+            return this._riskFetch(url, init, perform, scope);
+        });
+    }
+    async _restoreRiskState() {
+        const aid = this._aid;
+        if (!aid || this._riskRestoredAid === aid)
+            return;
+        this._risk.reset();
+        this._riskHttpRetryAt.clear();
+        this._riskScalarReconnectAt = 0;
+        const raw = this._tokenStore.loadMetadata?.(aid)?.[`risk_state_v1:${this._deviceId}`];
+        if (raw) {
+            try {
+                const state = typeof raw === 'string' ? JSON.parse(raw) : raw;
+                if (!isJsonObject(state) || !isJsonObject(state.target) || state.target.aid !== aid || state.target.device_id !== this._deviceId || !isJsonObject(state.signing_keys))
+                    throw new Error('risk state invalid');
+                const [keyId, key] = Object.entries(state.signing_keys)[0] ?? [];
+                if (!keyId || !Array.isArray(key))
+                    throw new Error('risk signing key unavailable');
+                this._risk.configure({ aid, device_id: this._deviceId, slot_id: this._slotId, connection_id: '' }, { key_id: keyId, public_key: Buffer.from(key).toString('base64url'), algorithm: 'ECDSA-P256-SHA256' }, Number(state.server_time_ms));
+                await this._risk.restore(state);
+            }
+            catch {
+                throw new StateError('persisted risk state could not be verified', { stringCode: 'risk_state_unavailable', retryable: true });
+            }
+        }
+        this._riskRestoredAid = aid;
+    }
+    _assertRiskReconnect() {
+        const delay = this._riskReconnectDelay();
+        if (delay > 0)
+            throw new ConnectionError('connection postponed by risk policy', { stringCode: 'risk_restricted', retryable: true, data: { retry_after_ms: Math.ceil(delay) } });
+    }
+    _riskReconnectDelay() { return Math.max(this._risk.reconnectDelayMs(), this._riskScalarReconnectAt - (typeof performance !== 'undefined' ? performance.now() : Date.now()), 0); }
+    async _applyRiskHello(hello) {
+        this._riskNegotiated = false;
+        if (!isJsonObject(hello.negotiated_capabilities) || hello.negotiated_capabilities.risk_test_v1 !== true)
+            return;
+        if (!this._gatewayUrl?.startsWith('wss://') || !this._configModel.verifySsl || !this._aid || !isJsonObject(hello.risk_signing_key))
+            return;
+        const key = hello.risk_signing_key;
+        const initial = isJsonObject(hello.risk_state) ? hello.risk_state : {};
+        this._risk.configure({ aid: this._aid, device_id: this._deviceId, slot_id: this._slotId, connection_id: this._gatewayConnectionId }, { key_id: String(key.key_id ?? ''), public_key: String(key.public_key ?? ''), algorithm: String(key.algorithm ?? '') }, Number(hello.server_time_ms ?? initial.server_time_ms));
+        this._riskNegotiated = true;
+        await this._transport.setRiskSnapshot(this._risk.exportState(true));
+        if (Array.isArray(initial.states))
+            for (const state of initial.states)
+                if (isJsonObject(state))
+                    await this._onRiskControl(state);
+    }
+    async _onRiskControl(payload) {
+        const identity = JSON.stringify([this._aid, this._deviceId, this._slotId, this._serviceEventIdentityVersion, this._transport._connectionGeneration]);
+        const run = this._riskApplyTail.then(async () => {
+            const current = () => identity === JSON.stringify([this._aid, this._deviceId, this._slotId, this._serviceEventIdentityVersion, this._transport._connectionGeneration]);
+            if (current())
+                await this._applyRiskControl(payload, current);
+        });
+        this._riskApplyTail = run.catch(() => { });
+        await run;
+    }
+    async _applyRiskControl(payload, current) {
+        if (!this._riskNegotiated)
+            return;
+        this._riskApplying = true;
+        let status;
+        try {
+            status = await this._risk.apply(payload);
+        }
+        catch {
+            this._riskApplying = false;
+            this._riskEvents = [];
+            return;
+        }
+        this._riskApplying = false;
+        await this._transport.setRiskSnapshot(this._risk.exportState(true));
+        if (!current()) {
+            this._riskEvents = [];
+            return;
+        }
+        const params = { version: 1, delivery_id: payload.delivery_id, subject: payload.subject, revision: payload.revision, status: this._risk.persistenceFailed ? 'failed' : status };
+        if (this._risk.persistenceFailed)
+            params.error_code = 'persistence_unavailable';
+        const acknowledgement = this._transport.call('gateway.risk_ack', params, 500).catch(() => { });
+        for (const event of this._riskEvents.splice(0))
+            this._dispatcher.enqueue('risk_state_changed', event);
+        if (this._risk.shouldDisconnect()) {
+            await acknowledgement;
+            if (current())
+                void this._handleTransportDisconnect(new ConnectionError('connection restricted by risk policy', { code: 4029, stringCode: 'risk_restricted', retryable: true }), 4029);
+        }
+    }
+    async _riskFetch(input, init = {}, perform = fetch, requestScope) {
+        await this._restoreRiskState();
+        const url = new URL(input);
+        const route = `${url.origin}${url.pathname}`;
+        const monotonicNow = () => typeof performance !== 'undefined' ? performance.now() : Date.now();
+        const retryAt = this._riskHttpRetryAt.get(route) ?? 0;
+        if (retryAt > monotonicNow())
+            throw new StateError('HTTP request postponed by risk response', { stringCode: 'risk_restricted', retryable: true, data: { retry_after_ms: Math.ceil(retryAt - monotonicNow()) } });
+        const release = this._risk.acquire(requestScope ?? (['GET', 'HEAD'].includes(String(init.method ?? 'GET').toUpperCase()) ? 'http:storage:read' : 'http:storage:write'));
+        try {
+            const response = await perform(input, init);
+            if (response.status === 429) {
+                try {
+                    const body = await response.clone().json();
+                    const detail = isJsonObject(body) && isJsonObject(body.error) && isJsonObject(body.error.data) ? body.error.data : isJsonObject(body) && isJsonObject(body.data) ? body.data : isJsonObject(body) ? body : {};
+                    const wrapper = detail.risk_state;
+                    if (this._riskNegotiated && isJsonObject(wrapper) && Array.isArray(wrapper.states))
+                        for (const state of wrapper.states)
+                            if (isJsonObject(state))
+                                await this._onRiskControl(state);
+                    const delayMs = Number(detail.retry_after_ms);
+                    if (Number.isSafeInteger(delayMs) && delayMs > 0)
+                        this._riskHttpRetryAt.set(route, monotonicNow() + delayMs);
+                }
+                catch { /* 无签名状态的 HTTP 错误由调用入口处理 */ }
+                const header = response.headers.get('Retry-After');
+                if (header) {
+                    const delayMs = /^\d+$/.test(header) ? Number(header) * 1000 : Math.max(0, Date.parse(header) - Date.now());
+                    if (Number.isFinite(delayMs) && delayMs > 0)
+                        this._riskHttpRetryAt.set(route, Math.max(this._riskHttpRetryAt.get(route) ?? 0, monotonicNow() + delayMs));
+                }
+            }
+            return response;
+        }
+        finally {
+            release();
+        }
+    }
     // ── RPC ───────────────────────────────────────────────────
     /**
      * 发送 JSON-RPC 调用。
@@ -1730,7 +2033,7 @@ export class AUNClient {
     async _resumeOrgRequest(method, params, target) {
         const binding = params.request_binding;
         const now = Math.trunc(Date.now() / 1000);
-        if (!isJsonObject(binding) || now < Number(binding.exp))
+        if (!isJsonObject(binding) || now <= Number(binding.exp) + 300)
             return params;
         const credentials = isJsonObject(params.credentials) ? params.credentials : {};
         const credential = ['member_credential', 'approval_credential', 'audit_credential'].map((field) => credentials[field]).find(isJsonObject) ?? params.credential_template;
@@ -1787,7 +2090,7 @@ export class AUNClient {
             checkpoint = { ...checkpoint, result, phase: 'upload' };
             tokens.saveMetadata(orgAid, { org_identity_creation: checkpoint });
         }
-        await this._uploadOrgAgentMd(store, orgAid, params);
+        await this._uploadOrgAgentMd(store, orgAid, params, checkpoint.result);
         tokens.saveMetadata(orgAid, { org_identity_creation: null });
         return checkpoint.result;
     }
@@ -1829,7 +2132,7 @@ export class AUNClient {
         const now = Math.trunc(Date.now() / 1000);
         if (binding.org_id !== orgAid || nextBinding.org_id !== orgAid || binding.member_aid === ownerAid || nextBinding.member_aid !== ownerAid
             || binding.role !== 'member' || nextBinding.role !== 'owner' || digest(previous.terms) !== binding.terms_hash || digest(next.terms) !== nextBinding.terms_hash
-            || !Number.isSafeInteger(nextBinding.iat) || !Number.isSafeInteger(nextBinding.exp) || Number(nextBinding.iat) > now || Number(nextBinding.exp) <= now
+            || !Number.isSafeInteger(nextBinding.iat) || !Number.isSafeInteger(nextBinding.exp) || Number(nextBinding.iat) > now + 300 || now > Number(nextBinding.exp) + 300
             || credential.iss !== orgAid || credential.sub !== binding.member_aid || credential.parent != null || credential.delegate !== false
             || ext.credential_type !== 'member' || ext.bound_to_membership !== true || ext.org_id !== orgAid || ext.membership_id !== binding.membership_id
             || ext.binding_version !== binding.binding_version || ext.membership_terms_hash !== binding.terms_hash
@@ -1848,7 +2151,7 @@ export class AUNClient {
         const checkedAt = Math.trunc(Date.now() / 1000);
         verifyMembershipBinding(binding, resolve, checkedAt, orgAid);
         verifyCredentialSignature(credential, resolve, checkedAt, orgAid);
-        if (Number(nextBinding.exp) <= checkedAt)
+        if (checkedAt > Number(nextBinding.exp) + 300)
             throw ownershipFailure('invalid', 'Org transfer membership materials do not match');
     }
     async completeOrgTransfer(params = {}, options = {}) {
@@ -1938,7 +2241,7 @@ export class AUNClient {
             tokenStore.saveMetadata(orgAid, { org_identity_transfer: pending });
         }
         const result = await this.call('org.lifecycle.transferAccept', await this._resumeOrgRequest('org.lifecycle.transferAccept', pending.finalize_params, target));
-        await this._uploadOrgAgentMd(store, orgAid, pending.source_params);
+        await this._uploadOrgAgentMd(store, orgAid, pending.source_params, result);
         tokenStore.saveMetadata(orgAid, { org_identity_transfer: { transfer_id: transferId, owner_aid: owner.aid, input_hash: inputHash, phase: 'completed', result } });
         localStore.clearPendingGroupBind(pendingKey);
         return result;
@@ -1976,15 +2279,18 @@ export class AUNClient {
         }
         return result;
     }
-    async _uploadOrgAgentMd(store, orgAid, params) {
+    async _uploadOrgAgentMd(store, orgAid, params, initialResult) {
         const owner = this._currentAid;
         if (!owner)
             throw ownershipFailure('forbidden', 'Org agent.md requires current owner');
-        if (await this._resumeGroupAgentMdUpload(store, orgAid))
+        const organization = isJsonObject(initialResult) && isJsonObject(initialResult.organization) ? initialResult.organization : undefined;
+        const bootstrap = organization?.org_id === orgAid && organization.owner_aid === owner.aid && organization.status === 'active'
+            ? { aid: orgAid, ownerAid: owner.aid, certFingerprint: this._localEntityCertificate(orgAid).certFingerprint, completedTransfer: Boolean(params.transfer_id && isJsonObject(initialResult) && initialResult.transfer_id === params.transfer_id) } : undefined;
+        if (await this._resumeGroupAgentMdUpload(store, orgAid, bootstrap))
             return;
         const identity = this._localEntityCertificate(orgAid);
         const content = String(params.org_agent_md ?? buildDefaultAgentMd(orgAid, { type: 'org', owner: owner.aid, entityCertFingerprint: identity.certFingerprint, name: String(params.name ?? orgAid) }));
-        const uploaded = await store.uploadAgentMd(orgAid, content, { uploaderAid: owner.aid, entityOwnerResolver: (aid, type) => this._resolveEntityAgentMdOwner(aid, type), entityIdentityGetter: (aid) => this._freshEntityCertificate(aid, 'org') });
+        const uploaded = await store.uploadAgentMd(orgAid, content, { uploaderAid: owner.aid, entityOwnerResolver: (aid, type) => this._resolveEntityAgentMdOwner(aid, type, bootstrap), entityIdentityGetter: (aid) => this._freshEntityCertificate(aid, 'org') });
         if (!uploaded.ok) {
             const code = ['invalid', 'unavailable', 'forbidden', 'conflict', 'persistence_unavailable'].includes(uploaded.error.code) ? uploaded.error.code : uploaded.error.code === 'NETWORK_ERROR' ? 'unavailable' : 'invalid';
             throw ownershipFailure(code, uploaded.error.message, code === 'unavailable');
@@ -2100,7 +2406,7 @@ export class AUNClient {
         if (!imported.ok) {
             throw new ValidationError(imported.error.message);
         }
-        await this._uploadGroupAgentMd(store, groupAid, payload, group);
+        await this._uploadGroupAgentMd(store, groupAid, payload, group, certPem);
         if (keystore && typeof keystore.clearPendingGroupBind === 'function') {
             keystore.clearPendingGroupBind(pendingKey);
         }
@@ -2168,7 +2474,7 @@ export class AUNClient {
             '',
         ].join('\n');
     }
-    async _resumeGroupAgentMdUpload(store, groupAid) {
+    async _resumeGroupAgentMdUpload(store, groupAid, bootstrap) {
         const identityStore = store;
         const pendingManager = identityStore._agentMdManager ?? this._agentMdManager;
         const pending = pendingManager.pendingUpload(groupAid);
@@ -2188,7 +2494,7 @@ export class AUNClient {
             uploadViaGatewayHost: true,
             ownerAidGetter: () => identity.aid,
             currentAidGetter: () => identity,
-            entityOwnerResolver: (aid, type) => this._resolveEntityAgentMdOwner(aid, type),
+            entityOwnerResolver: (aid, type) => this._resolveEntityAgentMdOwner(aid, type, bootstrap?.completedTransfer || pending.condition?.if_none_match === '*' ? bootstrap : undefined),
             entityIdentityGetter: (aid, type) => this._freshEntityCertificate(aid, type),
             entitySignerResolver: (aid, fingerprint) => this._freshEntitySigner(aid, fingerprint),
             gatewayResolver: (aid) => identityStore._resolveGateway(aid),
@@ -2203,15 +2509,16 @@ export class AUNClient {
         });
         return await manager.resumePendingUpload(groupAid);
     }
-    async _uploadGroupAgentMd(store, groupAid, params, group) {
+    async _uploadGroupAgentMd(store, groupAid, params, group, initialCertificate) {
         const uploaderAid = String(this._aid ?? '').trim();
         if (!uploaderAid) {
             throw new ValidationError('group agent.md upload requires current owner AID');
         }
         this._aidStore = store;
-        if (await this._resumeGroupAgentMdUpload(store, groupAid))
+        const bootstrap = initialCertificate ? { aid: groupAid, ownerAid: String(group.owner_aid ?? '').trim(), certFingerprint: certFingerprint(initialCertificate), type: 'group' } : undefined;
+        if (await this._resumeGroupAgentMdUpload(store, groupAid, bootstrap))
             return;
-        const uploaded = await store.uploadAgentMd(groupAid, this._groupAgentMdContent(groupAid, params, group), { uploaderAid, entityOwnerResolver: (aid, type) => this._resolveEntityAgentMdOwner(aid, type), entityIdentityGetter: (aid) => this._freshEntityCertificate(aid) });
+        const uploaded = await store.uploadAgentMd(groupAid, this._groupAgentMdContent(groupAid, params, group), { uploaderAid, entityOwnerResolver: (aid, type) => this._resolveEntityAgentMdOwner(aid, type, bootstrap), entityIdentityGetter: (aid) => this._freshEntityCertificate(aid) });
         if (!uploaded.ok) {
             const code = ['invalid', 'unavailable', 'forbidden', 'conflict', 'persistence_unavailable'].includes(uploaded.error.code) ? uploaded.error.code : uploaded.error.code === 'NETWORK_ERROR' ? 'unavailable' : 'invalid';
             throw ownershipFailure(code, `group agent.md upload failed: ${uploaded.error.message}`, code === 'unavailable');
@@ -2232,8 +2539,20 @@ export class AUNClient {
         const material = await this._auth.resolveOwnershipCertificate(await this._resolveOwnershipCertificateGateway(aid), aid, fingerprint, 'signing');
         return AID._create({ aid, aunPath: this._configModel.aunPath, certPem: material.cert_pem, certValid: true, privateKeyPem: null, privateKeyValid: false });
     }
-    async _resolveEntityAgentMdOwner(aid, type) {
-        const authority = await this._agentMdManager.readEntityAuthorityFresh(aid);
+    async _resolveEntityAgentMdOwner(aid, type, bootstrap) {
+        let authority;
+        try {
+            authority = bootstrap?.completedTransfer && type === 'org' && bootstrap.aid === aid && bootstrap.ownerAid === this._currentAid?.aid
+                ? { owner_aid: bootstrap.ownerAid, entity_cert_fingerprint: bootstrap.certFingerprint }
+                : await this._agentMdManager.readEntityAuthorityFresh(aid);
+        }
+        catch (error) {
+            if (!bootstrap || bootstrap.aid !== aid || type !== (bootstrap.type ?? 'org') || !(error instanceof AUNError) || !isJsonObject(error.data) || error.data.http_status !== 404)
+                throw error;
+            if (!bootstrap.ownerAid || bootstrap.ownerAid !== this._currentAid?.aid)
+                throw ownershipFailure('forbidden', 'entity initial owner does not match uploader');
+            authority = { owner_aid: bootstrap.ownerAid, entity_cert_fingerprint: bootstrap.certFingerprint };
+        }
         const identity = await this._freshEntityCertificate(aid, type);
         if (authority.entity_cert_fingerprint !== identity.certFingerprint)
             throw ownershipFailure('conflict', 'entity authority changed during current-certificate verification');
@@ -2301,7 +2620,7 @@ export class AUNClient {
         if (!imported.ok) {
             throw new ValidationError(imported.error.message);
         }
-        await this._uploadGroupAgentMd(store, groupAid, payload, group);
+        await this._uploadGroupAgentMd(store, groupAid, payload, group, certPem);
         // 落盘成功，清除 pending 槽位
         if (groupId && keystore && typeof keystore.clearPendingGroupBind === 'function') {
             keystore.clearPendingGroupBind(pendingKey);
@@ -2600,6 +2919,8 @@ export class AUNClient {
      * 发送轻量在线通知，不走离线存储、seq/pull 或 ack。
      */
     async notify(method, params, options = {}) {
+        if (this._migrationPending)
+            throw new ConnectionError('client is migrating');
         if (params !== undefined && params !== null && !isJsonObject(params)) {
             throw new ValidationError('notify params must be an object');
         }
@@ -2675,6 +2996,10 @@ export class AUNClient {
         const messageEvent = event === 'message.received' || event === 'message.recalled' || event === 'message.batch';
         const hadMessageConsumer = messageEvent && [...this._dispatcher._snapshotApplicationHandlers(['message.received', 'message.recalled', 'message.batch']).values()].some((handlers) => handlers.length > 0);
         const result = this._dispatcher.subscribe(event, handler);
+        if (event === 'agent_md_changed') {
+            this._getAgentMdChanges().schedule();
+            void this._getAgentMdChanges().deliverEvents().catch((error) => this._clientLog.debug(String(error)));
+        }
         if (messageEvent) {
             if (this._p2pPeerPullEnabled && !hadMessageConsumer)
                 this._delivery.refreshPendingPeers();
@@ -2912,6 +3237,8 @@ export class AUNClient {
     // ── 事件自动解密管线 ──────────────────────────────────────
     /** 处理 transport 层推送的原始 P2P 消息 */
     async _onRawMessageReceived(data) {
+        if (this._controlMessages().onPush(data))
+            return;
         return this._delivery.onRawMessageReceived(data);
     }
     async _onRawMessageRecalled(data) {
@@ -2919,6 +3246,8 @@ export class AUNClient {
     }
     /** 处理群组消息推送：自动解密后 re-publish */
     async _onRawGroupMessageCreated(data) {
+        if (this._controlMessages().onPush(data, true))
+            return;
         return this._delivery.onRawGroupMessageCreated(data);
     }
     async _onRawGroupMessageRecalled(data) {
@@ -3006,6 +3335,8 @@ export class AUNClient {
         this._delivery.markPublishedSeq(ns, seq);
     }
     _publishAppEvent(event, payload, source = 'direct', deliveryContext) {
+        if (messageClassOf(payload) === 'sdk_control')
+            return this._controlMessages().consume(payload);
         if (event === 'message.received') {
             return this._handleOwnershipMessage(payload).then((handled) => {
                 if (!handled)
@@ -3488,7 +3819,7 @@ export class AUNClient {
                     throw new ValidationError('gateway url unavailable for e2ee cert fetch');
                 }
                 const peerGatewayUrl = AUNClient._resolvePeerGatewayUrl(gatewayUrl, aid);
-                const certPem = await _httpGetText(AUNClient._buildCertUrl(peerGatewayUrl, aid, certFingerprint), this._configModel.verifySsl, timeoutMs);
+                const certPem = await this._auth._fetchRiskText(AUNClient._buildCertUrl(peerGatewayUrl, aid, certFingerprint));
                 if (auth !== this._auth || pkiEpoch !== auth._strictPkiEpoch)
                     throw new ValidationError('peer certificate fetch context changed');
                 const validated = await this._validateAndCachePeerCert({
@@ -3929,6 +4260,9 @@ export class AUNClient {
     // ── 内部：连接 ────────────────────────────────────────────
     /** 执行一次连接流程 */
     async _connectOnce(params, allowReauth, reconnectOwner, connectionOwner) {
+        await this._restoreRiskState();
+        this._assertRiskReconnect();
+        this._riskNegotiated = false;
         const tStart = Date.now();
         connectionOwner ??= this._connectAbort ?? undefined;
         this._lifecycle.assertConnectionAttemptOwner(connectionOwner);
@@ -3938,8 +4272,15 @@ export class AUNClient {
         this._captureCapabilitiesFromConnect(params);
         this._connectDeliveryMode = { ...(params.delivery_mode ?? this._connectDeliveryMode) };
         const extraInfo = (params.extra_info && typeof params.extra_info === 'object' && !Array.isArray(params.extra_info))
-            ? params.extra_info
-            : undefined;
+            ? { ...params.extra_info }
+            : {};
+        if (typeof this._tokenStore.updateInstanceState === 'function') {
+            extraInfo._capabilities = {
+                ...(isJsonObject(extraInfo._capabilities) ? extraInfo._capabilities : {}),
+                message_classes_v1: { p2p: ['normal', 'control', 'sdk_control'], group: ['normal', 'control', 'sdk_control'] },
+                sdk_control_protocols: { 'aun.agent_md.changed': [1] },
+            };
+        }
         const prevState = this._state;
         this._auth.setInstanceContext({ deviceId: this._deviceId, slotId: this._slotId });
         this._state = 'connecting';
@@ -3953,10 +4294,16 @@ export class AUNClient {
             const challenge = await this._transport.connect(gatewayUrl);
             this._assertReconnectOwner(reconnectOwner);
             this._lifecycle.assertConnectionAttemptOwner(connectionOwner);
+            const authTransport = reconnectOwner ? {
+                call: (...args) => {
+                    this._assertReconnectOwner(reconnectOwner);
+                    return this._transport.call(...args);
+                },
+            } : this._transport;
             this._clientLog.debug(`WebSocket connection established: gateway=${gatewayUrl}`);
             this._state = 'authenticating';
             if (allowReauth) {
-                const authContext = await this._auth.connectSession(this._transport, challenge, gatewayUrl, {
+                const authContext = await this._auth.connectSession(authTransport, challenge, gatewayUrl, {
                     accessToken: String(params.access_token ?? ''),
                     deviceId: this._deviceId,
                     slotId: this._slotId,
@@ -3982,10 +4329,14 @@ export class AUNClient {
                     if (isJsonObject(auth.hello) && 'heartbeat_interval' in auth.hello) {
                         this._applyServerHeartbeatInterval(auth.hello.heartbeat_interval, 'auth');
                     }
+                    this._gatewayConnectionId = isJsonObject(auth.hello) && isJsonObject(auth.hello.connection) ? String(auth.hello.connection.id ?? '') : '';
+                    this._negotiatedCapabilities = isJsonObject(auth.hello) && isJsonObject(auth.hello.negotiated_capabilities) ? auth.hello.negotiated_capabilities : {};
+                    if (isJsonObject(auth.hello))
+                        await this._applyRiskHello(auth.hello);
                 }
             }
             else {
-                const hello = await this._auth.initializeWithToken(this._transport, challenge, String(params.access_token), {
+                const hello = await this._auth.initializeWithToken(authTransport, challenge, String(params.access_token), {
                     deviceId: this._deviceId,
                     slotId: this._slotId,
                     deliveryMode: this._connectDeliveryMode,
@@ -3999,6 +4350,10 @@ export class AUNClient {
                 if (isJsonObject(hello) && 'heartbeat_interval' in hello) {
                     this._applyServerHeartbeatInterval(hello.heartbeat_interval, 'auth');
                 }
+                this._gatewayConnectionId = isJsonObject(hello) && isJsonObject(hello.connection) ? String(hello.connection.id ?? '') : '';
+                this._negotiatedCapabilities = isJsonObject(hello) && isJsonObject(hello.negotiated_capabilities) ? hello.negotiated_capabilities : {};
+                if (isJsonObject(hello))
+                    await this._applyRiskHello(hello);
             }
             this._assertReconnectOwner(reconnectOwner);
             this._lifecycle.assertConnectionAttemptOwner(connectionOwner);
@@ -4006,6 +4361,7 @@ export class AUNClient {
                 throw new ConnectionError('websocket disconnected during authentication');
             }
             this._serverKicked = false;
+            this._migrationPending = false;
             this._lastDisconnectInfo = null;
             this._state = 'ready';
             this._connectedAt = Date.now();
@@ -4061,6 +4417,11 @@ export class AUNClient {
             else {
                 this._clientLog.debug('V2 session init deferred for short connection');
             }
+            this._controlMessages().close();
+            this._safeAsync(this._controlMessages().recover());
+            this._agentMdChanges?.close();
+            this._agentMdChanges = new AgentMdChangeCoordinator(this);
+            this._agentMdChanges.schedule();
             // connect/reconnect 成功后自动触发一次 P2P message.v2.pull，补齐离线期间积压
             // 群消息按惰性触发，不在此处主动 pull
             if (backgroundSyncEnabled) {
@@ -4298,6 +4659,8 @@ export class AUNClient {
             this._clientLog.warn(`V2 decrypt: invalid envelope_json for msg seq=${String(msg.seq)}`);
             return null;
         }
+        if (messageClassOf({ ...msg, envelope }) === 'sdk_control' && source !== 'control_pull')
+            return null;
         const e2eeMeta = this._v2E2eeMeta(envelope);
         if (observeAgentMd) {
             if (deferredEffects)
@@ -4435,8 +4798,10 @@ export class AUNClient {
             return null;
         }
         let plaintext;
+        let payloadBytes;
         try {
             plaintext = decryptMessage(envelope, this._aid ?? '', this._deviceId, ikPriv, spkPriv, senderPubDer);
+            payloadBytes = decryptedMessagePayloadBytes(plaintext);
             if (plaintext === null)
                 throw new Error('recipient_not_found_or_envelope_verification_failed');
         }
@@ -4488,6 +4853,11 @@ export class AUNClient {
             encrypted: true,
             e2ee,
         };
+        if (!this._v2E2EE.isEncryptedEnvelopePayload(msg.payload))
+            result._semantic_evidence = {
+                envelope_bytes_base64: Buffer.from(envelopeJson, 'utf8').toString('base64'), payload_bytes_base64: Buffer.from(payloadBytes).toString('base64'),
+                received_by: this._aid ?? '', received_at: Math.trunc(Date.now() / 1000), source,
+            };
         if (typeof plaintext.type === 'string' && plaintext.type.startsWith('aun.ownership.'))
             result.from_aid = fromAid;
         if (senderDeviceId)
@@ -4684,6 +5054,8 @@ export class AUNClient {
         return this._groupState.autoConfirmPendingProposals();
     }
     async _onV2PushNotification(data, expectedVersion, inlineGeneration) {
+        if (this._controlMessages().onPush(data))
+            return;
         return this._delivery.onV2PushNotification(data, expectedVersion, inlineGeneration);
     }
     async _onV2StateProposed(data) {
@@ -4696,6 +5068,8 @@ export class AUNClient {
         return this._groupState.onV2StateConfirmed(data);
     }
     async _onRawGroupV2MessageCreated(data, expectedVersion, inlineGeneration) {
+        if (this._controlMessages().onPush(data, true))
+            return;
         return this._delivery.onRawGroupV2MessageCreated(data, expectedVersion, inlineGeneration);
     }
     /** Push 通知带 payload 时的就地解密（复用 _decryptV2Message） */
@@ -4719,7 +5093,7 @@ export class AUNClient {
         }
     }
     /** 发现并缓存全部 Gateway 候选，供首连和自动重连故障转移使用。 */
-    async _resolveGatewayCandidatesForAid(aid) {
+    async _resolveGatewayCandidatesForAid(aid, fresh = false, reconnectOwner) {
         const resolvedAid = String(aid ?? this._aid ?? '').trim();
         if (!resolvedAid) {
             throw new StateError('gateway discovery requires a loaded AID');
@@ -4732,14 +5106,15 @@ export class AUNClient {
         const tokenStore = this._tokenStore;
         const discoveryIsCurrent = () => (this._discovery === discovery
             && this._tokenStore === tokenStore
-            && !this._closing);
-        if (sameIssuer && this._gatewayCandidates.length > 0)
+            && !this._closing
+            && (!reconnectOwner || this._ownsReconnect(reconnectOwner)));
+        if (!fresh && sameIssuer && this._gatewayCandidates.length > 0)
             return [...this._gatewayCandidates];
-        if (sameIssuer && this._gatewayUrl) {
+        if (!fresh && sameIssuer && this._gatewayUrl) {
             this._gatewayCandidates = [this._gatewayUrl];
             return [...this._gatewayCandidates];
         }
-        if (!sameIssuer) {
+        if (!fresh && !sameIssuer) {
             const cached = this._peerGatewayCache.get(issuerDomain);
             if (cached)
                 return [...cached];
@@ -4754,7 +5129,7 @@ export class AUNClient {
                 : [];
             const cachedGateway = cachedList[0]
                 ?? (isJsonObject(metadata) ? String(metadata.gateway_url ?? '').trim() : '');
-            if (cachedGateway) {
+            if (!fresh && cachedGateway) {
                 const gatewayUrls = [...new Set([cachedGateway, ...cachedList])];
                 if (sameIssuer) {
                     this._gatewayCandidates = gatewayUrls;
@@ -5135,21 +5510,182 @@ export class AUNClient {
     // ── 内部：断线重连 ────────────────────────────────────────
     /** 不重连 close code 集合：认证失败/权限错误/被踢等，重连无意义 */
     static _NO_RECONNECT_CODES = new Set([4001, 4003, 4008, 4009, 4010, 4011, 4013, 4014, 4015]);
+    _onGatewayMigrate(input) {
+        const data = input;
+        if (!isJsonObject(data) || this._closing || this._disconnecting || this._connectAbort || this._reconnectActive
+            || this._state !== 'ready' || !this._sessionParams || !this._gatewayConnectionId)
+            return;
+        const aid = this._aid ?? '';
+        const issuer = aid.slice(aid.indexOf('.') + 1).toLowerCase().replace(/\.$/, '');
+        const now = Date.now() / 1000;
+        if (typeof data.migration_id !== 'string' || !data.migration_id.trim()
+            || typeof data.revision !== 'number' || !Number.isSafeInteger(data.revision) || data.revision <= 0
+            || typeof data.issuer !== 'string' || data.issuer.trim().toLowerCase().replace(/\.$/, '') !== issuer
+            || data.aid !== aid || data.device_id !== this._deviceId || data.slot_id !== this._slotId
+            || data.connection_id !== this._gatewayConnectionId || typeof data.gateway_url !== 'string'
+            || typeof data.expires_at !== 'number' || !Number.isFinite(data.expires_at)
+            || data.expires_at <= now || data.expires_at > now + 300)
+            return;
+        let target;
+        try {
+            target = new URL(data.gateway_url);
+        }
+        catch {
+            return;
+        }
+        const hostname = target.hostname.toLowerCase();
+        if (target.protocol !== 'wss:' || target.username || target.password || target.hash
+            || /^\w+:\/\/[^/]*@/.test(data.gateway_url) || target.pathname !== '/aun'
+            || !(hostname === issuer || hostname.endsWith(`.${issuer}`))
+            || !hostname.split('.').every((label) => /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(label)))
+            return;
+        const identity = JSON.stringify([this._aid, this._deviceId, this._slotId]);
+        const previous = this._migrationRevision.get(identity);
+        if (previous && (data.revision <= previous.revision || data.migration_id === previous.migrationId))
+            return;
+        this._migrationRevision.set(identity, { revision: data.revision, migrationId: data.migration_id });
+        this._migrationPending = true;
+        this._reconnectActive = true;
+        const owner = new AbortController();
+        this._reconnectAbort = owner;
+        this._state = 'standby';
+        this._stopBackgroundTasks();
+        this._dispatcher.enqueue('gateway.migrate', data);
+        const task = Promise.resolve().then(() => this._runGatewayMigration(data, owner, identity));
+        this._reconnectTask = task;
+        this._safeAsync(task);
+    }
+    async _runGatewayMigration(data, owner, identity) {
+        const expiresAt = Number(data.expires_at) * 1000;
+        const current = () => this._ownsReconnect(owner) && !this._disconnecting && !this._connectAbort
+            && identity === JSON.stringify([this._aid, this._deviceId, this._slotId]);
+        const wait = (operation) => this._lifecycle.waitForAttempt(operation, undefined, owner);
+        const retry = this._sessionOptions.retry;
+        const maxAttempts = Number(retry.max_attempts ?? 0);
+        let delay = clampReconnectDelayMs(Number(retry.initial_delay ?? 1) * 1000, RECONNECT_MIN_BASE_DELAY_MS);
+        const maxDelay = clampReconnectDelayMs(Number(retry.max_delay ?? 64) * 1000, RECONNECT_MAX_BASE_DELAY_MS);
+        const expiryTimer = setTimeout(() => {
+            if (!current())
+                return;
+            owner.abort();
+            this._discovery._cancelPending?.();
+            this._auth._cancelPending?.();
+            void this._transport.close().catch(() => { });
+        }, Math.max(0, expiresAt - Date.now()));
+        let lastError = new ConnectionError('gateway migration expired');
+        try {
+            if (!current())
+                return;
+            await this._transport.waitForPending(Math.min(5000, Math.max(0, expiresAt - Date.now())), owner.signal);
+            if (!current())
+                return;
+            await this._saveSeqTrackerState();
+            await this._transport.close();
+            if (!current())
+                return;
+            this._delivery.resetInlineAckState();
+            for (let attempt = 1; current() && Date.now() < expiresAt; attempt++) {
+                if (maxAttempts > 0 && attempt > maxAttempts)
+                    throw lastError;
+                let candidates = attempt === 1 ? [String(data.gateway_url)] : [];
+                if (attempt > 1) {
+                    try {
+                        candidates = await wait(this._resolveGatewayCandidatesForAid(String(data.aid), true, owner));
+                    }
+                    catch (error) {
+                        lastError = error;
+                    }
+                }
+                for (let index = 0; index < candidates.length; index++) {
+                    const gateway = candidates[index];
+                    if (!current() || Date.now() >= expiresAt)
+                        return;
+                    this._state = 'reconnecting';
+                    this._migrationPending = true;
+                    try {
+                        await wait(this._connectOnce({ ...this._sessionParams, gateway, gateways: candidates }, true, owner));
+                        if (!current())
+                            return;
+                        if (!this._transport.isConnected())
+                            throw new ConnectionError('websocket disconnected while migrating');
+                        this._sessionParams.gateway = gateway;
+                        this._sessionParams.gateways = candidates;
+                        return;
+                    }
+                    catch (error) {
+                        lastError = error;
+                        if (!current())
+                            return;
+                        this._migrationPending = true;
+                        await this._transport.close().catch(() => { });
+                        if (!current())
+                            return;
+                        if (attempt === 1 && index === 0) {
+                            try {
+                                const discovered = await wait(this._resolveGatewayCandidatesForAid(String(data.aid), true, owner));
+                                candidates = [...candidates, ...discovered.filter((item) => !candidates.includes(item))];
+                            }
+                            catch (discoveryError) {
+                                lastError = discoveryError;
+                            }
+                        }
+                    }
+                }
+                if (!AUNClient._shouldRetryReconnect(lastError))
+                    throw lastError;
+                if (maxAttempts > 0 && attempt >= maxAttempts)
+                    throw lastError;
+                await this._sleep(Math.min(delay, Math.max(0, expiresAt - Date.now())), owner.signal);
+                if (!current())
+                    return;
+                delay = Math.min(delay * 2, maxDelay);
+            }
+        }
+        catch (error) {
+            lastError = error;
+        }
+        finally {
+            clearTimeout(expiryTimer);
+            if (this._reconnectAbort === owner) {
+                this._migrationPending = false;
+                this._reconnectActive = false;
+                this._reconnectAbort = null;
+                this._reconnectTask = null;
+                this._nextRetryAt = null;
+                if ((this._state !== 'ready' || owner.signal.aborted) && !this._closing) {
+                    this._stopBackgroundTasks();
+                    this._state = 'standby';
+                    if (!owner.signal.aborted)
+                        this._dispatcher.enqueue('connection.error', { error: formatCaughtError(lastError) });
+                }
+            }
+        }
+    }
     /** 处理服务端主动断开通知 event/gateway.disconnect。
      *
      * 服务端可能附带结构化 detail 字段（如配额超限时含 aid/device_id/slot_id/quota_kind/evicted_by）。
      * 透传到应用层可订阅事件 'gateway.disconnect'，方便业务定位被踢原因。
      */
     async _onGatewayDisconnect(data) {
-        const payload = (data && typeof data === 'object') ? data : {};
+        const payload = (data && typeof data === 'object') ? structuredClone(data) : {};
         const code = payload.code;
         const reason = payload.reason ?? '';
         const detail = (payload.detail && typeof payload.detail === 'object' && !Array.isArray(payload.detail))
             ? payload.detail
             : {};
+        const wrapper = payload.risk_state ?? detail.risk_state;
+        delete payload.risk_state;
+        delete detail.risk_state;
+        if (isJsonObject(wrapper) && Array.isArray(wrapper.states))
+            for (const state of wrapper.states)
+                if (isJsonObject(state))
+                    await this._onRiskControl(state);
+        const retryMs = Number(detail.retry_after_ms ?? payload.retry_after_ms ?? 0);
+        if (Number(code) === 4029 && Number.isSafeInteger(retryMs) && retryMs > 0)
+            this._riskScalarReconnectAt = (typeof performance !== 'undefined' ? performance.now() : Date.now()) + retryMs;
         this._clientLog.warn(`server initiated disconnect: code=${code}, reason=${reason}, detail=${JSON.stringify(detail)}`);
         const reasonText = String(reason ?? '').trim().toLowerCase();
-        const retryable = Number(code) === 4012
+        const retryable = Number(code) === 4012 || Number(code) === 4029
             || reasonText.includes('long_connection_already_exists')
             || reasonText.includes('long connection already exists');
         this._serverKicked = !retryable;
@@ -5362,7 +5898,7 @@ export class AUNClient {
                 break;
             }
             this._retryAttempt = attempt;
-            this._nextRetryAt = Date.now() + reconnectSleepDelayMs(delay, maxBaseDelay);
+            this._nextRetryAt = Date.now() + Math.max(reconnectSleepDelayMs(delay, maxBaseDelay), this._riskReconnectDelay());
             this._state = 'retry_backoff';
             if (!reconnectAbort || !await this._publishReconnectEvent(reconnectAbort, 'state_change', {
                 state: this._publicState(this._state),