@agentunion/fastaun-browser 0.3.2 → 0.3.4

package/dist/client.js

@@ -18,6 +18,7 @@ import { CryptoProvider, uint8ToBase64, base64ToUint8, pemToArrayBuffer, p1363To
 import { IndexedDBKeyStore } from './keystore/indexeddb.js';
 import { V2Session, V2KeyStore } from './v2/session/index.js';
 import { encryptP2PMessage, encryptGroupMessage, decryptMessage, } from './v2/e2ee/index.js';
+import { ecdsaVerifyRaw } from './v2/crypto/ecdsa.js';
 import { computeStateCommitment } from './v2/state/index.js';
 import { AUNLogger } from './logger.js';
 import { AUNError, AuthError, ConnectionError, E2EEError, PermissionError, StateError, ValidationError, } from './errors.js';
@@ -44,6 +45,15 @@ function stableStringify(obj) {
     }
     return JSON.stringify(obj);
 }
+function getV2DeviceId(dev) {
+    if (Object.prototype.hasOwnProperty.call(dev, 'device_id')) {
+        return { present: true, value: String(dev.device_id ?? '').trim() };
+    }
+    if (Object.prototype.hasOwnProperty.call(dev, 'owner_device_id')) {
+        return { present: true, value: String(dev.owner_device_id ?? '').trim() };
+    }
+    return { present: false, value: '' };
+}
 function sortObjectKeys(obj) {
     if (obj === null || obj === undefined || typeof obj !== 'object')
         return obj;
@@ -118,7 +128,16 @@ const REMOVED_E2EE_METHODS = new Set([
 ]);
 /** 需要客户端签名的关键方法 */
 const SIGNED_METHODS = new Set([
-    'group.send', 'group.kick', 'group.add_member',
+    'message.send',
+    'message.v2.put_peer_pk', 'message.v2.bootstrap',
+    'message.v2.group_bootstrap', 'message.v2.pull',
+    'message.v2.ack',
+    'group.send',
+    'group.v2.put_group_pk', 'group.v2.bootstrap',
+    'group.v2.send', 'group.v2.pull', 'group.v2.ack',
+    'group.v2.propose_state', 'group.v2.confirm_state',
+    'group.v2.get_proposal',
+    'group.kick', 'group.add_member',
     'group.leave', 'group.remove_member', 'group.update_rules',
     'group.update', 'group.update_announcement',
     'group.update_join_requirements', 'group.set_role',
@@ -251,6 +270,63 @@ function isGroupServiceAid(value) {
     const [name, ...issuerParts] = text.split('.');
     return name === 'group' && issuerParts.join('.').length > 0;
 }
+function normalizeV2WrapPolicy(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return undefined;
+    const obj = raw;
+    let protocol = String(obj.protocol ?? '').trim().toUpperCase();
+    let scope = String(obj.scope ?? '').trim().toLowerCase();
+    if (scope !== 'aid' && scope !== 'device') {
+        if (obj.per_aid_wrap === true)
+            scope = 'aid';
+        else if (obj.per_device_wrap === true)
+            scope = 'device';
+        else
+            scope = '';
+    }
+    if (protocol !== '1DH' && protocol !== '3DH')
+        protocol = '';
+    if (scope === 'aid')
+        protocol = '1DH';
+    if (!protocol && !scope)
+        return undefined;
+    return {
+        protocol: protocol ? protocol : undefined,
+        scope: scope ? scope : undefined,
+    };
+}
+function v2WrapCapabilities() {
+    return {
+        version: 'v2.1',
+        protocols: ['1DH', '3DH'],
+        scopes: ['aid', 'device'],
+        per_aid_wrap: true,
+        per_device_wrap: true,
+    };
+}
+function applyV2WrapPolicyToTargets(targets, policy) {
+    if (!policy)
+        return targets;
+    const normalized = targets.map((target) => {
+        const row = { ...target };
+        if (policy.protocol === '1DH') {
+            row.keySource = 'aid_master';
+            row.spkPkDer = undefined;
+            row.spkId = '';
+        }
+        return row;
+    });
+    if (policy.scope !== 'aid')
+        return normalized;
+    const collapsed = new Map();
+    for (const target of normalized) {
+        const key = `${target.aid}\u0000${target.role}`;
+        if (!collapsed.has(key)) {
+            collapsed.set(key, { ...target, deviceId: '' });
+        }
+    }
+    return Array.from(collapsed.values());
+}
 /** 32 字节左侧零填充（用于 P-256 私钥 scalar 规范化） */
 function _v2LeftPad32(b) {
     if (b.length === 32)
@@ -269,6 +345,43 @@ function _v2B64ToBytes(s) {
         out[i] = bin.charCodeAt(i);
     return out;
 }
+function _v2B64ToBytesStrict(s) {
+    const text = String(s ?? '').trim();
+    if (!text || text.length % 4 === 1 || !/^[A-Za-z0-9+/]*={0,2}$/.test(text)) {
+        throw new Error('invalid base64');
+    }
+    return _v2B64ToBytes(text);
+}
+function _v2BytesEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a[i] ^ b[i];
+    return diff === 0;
+}
+function _v2ConcatBytes(...parts) {
+    const total = parts.reduce((sum, part) => sum + part.length, 0);
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const part of parts) {
+        out.set(part, offset);
+        offset += part.length;
+    }
+    return out;
+}
+function _v2LengthPrefixedTextKey(...parts) {
+    const enc = new TextEncoder();
+    return parts.map((part) => `${enc.encode(part).length}:${part};`).join('');
+}
+function _v2LengthPrefixedBytes(...parts) {
+    const enc = new TextEncoder();
+    const framed = [];
+    for (const part of parts) {
+        framed.push(enc.encode(`${part.length}:`), part, enc.encode(';'));
+    }
+    return _v2ConcatBytes(...framed);
+}
 /** Base64URL → Uint8Array（兼容缺失 padding） */
 function _v2B64uToBytes(s) {
     const std = s.replace(/-/g, '+').replace(/_/g, '/');
@@ -281,12 +394,74 @@ function formatCaughtError(error) {
 function v2E2eeMeta(envelope) {
     const suite = String(envelope.suite ?? '');
     const modeSuite = String(envelope.suite ?? 'unknown');
-    return {
+    const meta = {
         version: 'v2',
         suite,
         encryption_mode: `v2_${modeSuite}`,
         forward_secrecy: true,
     };
+    const protectedHeaders = metadataWithoutAuth(envelope.protected_headers);
+    if (protectedHeaders && Object.keys(protectedHeaders).length > 0) {
+        meta.protected_headers = protectedHeaders;
+    }
+    const payloadType = String(envelope.payload_type ?? protectedHeaders?.payload_type ?? '').trim();
+    if (payloadType) {
+        meta.payload_type = payloadType;
+    }
+    const context = metadataWithoutAuth(envelope.context);
+    if (context && Object.keys(context).length > 0) {
+        meta.context = context;
+    }
+    const agentMd = metadataWithoutAuth(envelope.agent_md);
+    if (agentMd && Object.keys(agentMd).length > 0) {
+        meta.agent_md = agentMd;
+    }
+    return meta;
+}
+function attachV2EnvelopeMetadata(message, meta) {
+    if (!meta)
+        return;
+    const payloadType = typeof meta.payload_type === 'string' ? meta.payload_type.trim() : '';
+    if (payloadType)
+        message.payload_type = payloadType;
+    if (isJsonObject(meta.protected_headers)) {
+        message.protected_headers = { ...meta.protected_headers };
+    }
+    if (isJsonObject(meta.agent_md)) {
+        message.agent_md = { ...meta.agent_md };
+    }
+}
+function attachV2EnvelopeMetadataFromSource(message, source) {
+    const envelope = extractV2EnvelopeFromSource(source);
+    if (envelope)
+        attachV2EnvelopeMetadata(message, v2E2eeMeta(envelope));
+}
+function extractV2EnvelopeFromSource(source) {
+    if (!isJsonObject(source))
+        return null;
+    if (isJsonObject(source.payload))
+        return source.payload;
+    if (typeof source.envelope_json === 'string' && source.envelope_json) {
+        try {
+            const parsed = JSON.parse(source.envelope_json);
+            if (isJsonObject(parsed))
+                return parsed;
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+function metadataWithoutAuth(value) {
+    if (!isJsonObject(value))
+        return null;
+    const body = {};
+    for (const [key, item] of Object.entries(value)) {
+        if (key !== '_auth')
+            body[key] = item;
+    }
+    return body;
 }
 function normalizeDeliveryModeConfig(raw, opts = {}) {
     const defaultMode = String(opts.defaultMode ?? 'fanout').trim().toLowerCase() || 'fanout';
@@ -379,11 +554,13 @@ export class AUNClient {
     _v2Session;
     _v2KeyStore;
     _v2BootstrapCache = new Map();
+    _v2SenderIKPending = new Map();
+    _v2SenderIKFetching = new Set();
     static V2_BOOTSTRAP_TTL_MS = 60 * 60 * 1000;
     static V2_RETRYABLE_CODES = new Set([-33011, -33012, -33050, -33052, -33054]);
     /** V2 state 签名验证缓存：cacheKey(hex) → expiry_unix_ms */
     _v2SigCache = new Map();
-    static _V2_SIG_CACHE_TTL = 600_000; // 10 min
+    static _V2_SIG_CACHE_TTL = 60 * 60 * 1000;
     static _V2_SIG_CACHE_MAX = 16384;
     /** V2 state chain 本地记录：group_id → [state_version, chain_hash] */
     _v2StateChains = new Map();
@@ -405,6 +582,11 @@ export class AUNClient {
     _localAgentMdEtag = '';
     /** gateway 在 RPC envelope._meta.agent_md_etag 注入的服务端 etag；纯观察，无下游依赖。 */
     _remoteAgentMdEtag = '';
+    /** 浏览器侧 AgentMDs 逻辑根目录，正文映射到 IndexedDB 里的 {aid}/agent.md。 */
+    _agentMdPath = '';
+    _agentMdCache = new Map();
+    _agentMdFetchInflight = new Set();
+    _agentMdLock = Promise.resolve();
     /** 消息序列号跟踪器（群消息 + P2P 空洞检测） */
     _seqTracker = new SeqTracker();
     _seqTrackerContext = null;
@@ -418,6 +600,9 @@ export class AUNClient {
     _groupSynced = new Set();
     /** gap fill 来源标记：true 表示当前正在补洞（pull 触发），false 表示非补洞 */
     _gapFillActive = false;
+    // Pull Gate：序列化同一 key 的并发 pull 操作，防止重复拉取
+    _pullGates = new Map();
+    static _PULL_GATE_STALE_MS = 30000;
     // 重连相关
     _reconnectActive = false;
     _reconnectAbort = null;
@@ -444,8 +629,11 @@ export class AUNClient {
             root_ca_path: this.configModel.rootCaPem,
             seed_password: this.configModel.seedPassword,
         };
+        this._agentMdPath = this._agentMdDefaultRoot();
+        this._deviceId = getDeviceId();
         // Logger 必须最早初始化（其他子模块构造时通过 logger 输出）
-        this._logger = new AUNLogger({ debug: _debug });
+        this._logger = new AUNLogger({ debug: _debug, aunPath: this.configModel.aunPath });
+        this._logger.bindDeviceId(this._deviceId);
         this._clientLog = this._logger.for('aun_core.client');
         this._logAuth = this._logger.for('aun_core.auth');
         this._logTransport = this._logger.for('aun_core.transport');
@@ -455,8 +643,7 @@ export class AUNClient {
         this._clientLog.info(`AUNClient initialized: debug=${_debug} aunPath=${this.configModel.aunPath} aid=${initAid ?? '-'}`);
         this._dispatcher = new EventDispatcher();
         this._discovery = new GatewayDiscovery();
-        this._keystore = new IndexedDBKeyStore();
-        this._deviceId = getDeviceId();
+        this._keystore = new IndexedDBKeyStore({ encryptionSeed: this.configModel.seedPassword ?? undefined });
         this._slotId = '';
         this._connectDeliveryMode = normalizeDeliveryModeConfig({ mode: 'fanout' });
         this._defaultConnectDeliveryMode = { ...this._connectDeliveryMode };
@@ -475,7 +662,11 @@ export class AUNClient {
             timeout: DEFAULT_SESSION_OPTIONS.timeouts.call,
             onDisconnect: (error, closeCode) => this._handleTransportDisconnect(error, closeCode),
         });
-        this._transport.setMetaObserver((meta) => this._observeRpcMeta(meta));
+        this._transport.setMetaObserver((meta) => {
+            void this._observeRpcMeta(meta).catch((exc) => {
+                this._clientLog.debug(`agent.md meta observer skipped: ${String(exc)}`);
+            });
+        });
         this.auth = new AuthNamespace(this);
         this.custody = new CustodyNamespace(this);
         this.meta = new MetaNamespace(this);
@@ -548,30 +739,64 @@ export class AUNClient {
     get aid() {
         return this._aid;
     }
+    setAgentMdPath(root) {
+        const next = String(root ?? '').trim() || this._agentMdDefaultRoot();
+        this._agentMdPath = next;
+        this._agentMdCache.clear();
+        return next;
+    }
+    setAgentMDPath(root) {
+        return this.setAgentMdPath(root);
+    }
+    SetAgentMDPath(root) {
+        return this.setAgentMdPath(root);
+    }
     /**
-     * 浏览器版本 publishAgentMd。接收 agent.md 文本（应用层用 `<input type=file>` 等读出文本传入），
-     * 内部签名 → 上传 → 更新 _localAgentMdEtag（quoted sha256，与服务端一致）。
+     * 浏览器版本 publishAgentMd。默认从 {agentMdPath}/{self_aid}/agent.md 的等价 IndexedDB 正文读取，
+     * 然后签名、上传，并刷新 agentmd.json 元数据。
      *
-     * @throws ValidationError content 为空
+     * 兼容旧浏览器调用：传入 content 时会先写入等价正文，再从该正文发布。
      */
     async publishAgentMd(content) {
-        const text = String(content ?? '');
-        if (text.length === 0) {
-            throw new ValidationError('publishAgentMd requires non-empty content');
+        const target = this._agentMdOwnerAid();
+        if (!target) {
+            throw new ValidationError('publishAgentMd requires local AID');
+        }
+        if (content !== undefined && content !== null) {
+            const text = String(content ?? '');
+            if (text.length === 0) {
+                throw new ValidationError('publishAgentMd requires non-empty content');
+            }
+            await this._saveAgentMdRecord(target, {
+                content: text,
+                local_etag: await this._agentMdContentEtag(text),
+                fetched_at: Date.now(),
+            });
         }
-        const signed = await this.auth.signAgentMd(text);
+        const localContent = await this._readAgentMdContent(target);
+        if (localContent === null || localContent.length === 0) {
+            throw new ValidationError('publishAgentMd requires local agent.md content');
+        }
+        const signed = await this.auth.signAgentMd(localContent);
         const result = await this.auth.uploadAgentMd(signed);
-        const buf = new TextEncoder().encode(signed);
-        const digest = await crypto.subtle.digest('SHA-256', buf);
-        const hex = Array.from(new Uint8Array(digest))
-            .map((b) => b.toString(16).padStart(2, '0'))
-            .join('');
-        this._localAgentMdEtag = `"${hex}"`;
+        this._localAgentMdEtag = await this._agentMdContentEtag(signed);
+        const remoteEtag = isJsonObject(result) ? String(result.etag ?? '').trim() : '';
+        if (remoteEtag)
+            this._remoteAgentMdEtag = remoteEtag;
+        await this._saveAgentMdRecord(target, {
+            content: signed,
+            local_etag: this._localAgentMdEtag,
+            remote_etag: remoteEtag || undefined,
+            last_modified: isJsonObject(result) ? String(result.last_modified ?? '').trim() : '',
+            fetched_at: Date.now(),
+            remote_status: remoteEtag ? 'found' : 'unknown',
+            last_error: '',
+        });
         return result;
     }
     /**
-     * 浏览器版本 fetchAgentMd。aid 缺省时取自身；不接受 savePath（浏览器无文件系统）；
-     * 若 aid 是自己则同步刷新 _localAgentMdEtag 与 in_sync。
+     * 浏览器版本 fetchAgentMd。aid 缺省时取自身；下载后的正文固定写入
+     * {agentMdPath}/{aid}/agent.md 的等价 IndexedDB 正文，agentmd.json 只保存元数据。
      */
     async fetchAgentMd(aid) {
         const target = String(aid ?? this._aid ?? '').trim();
@@ -581,17 +806,30 @@ export class AUNClient {
         const content = await this.auth.downloadAgentMd(target);
         const signature = await this.auth.verifyAgentMd(content, { aid: target });
         const isSelf = target === (this._aid ?? '');
+        const localEtag = await this._agentMdContentEtag(content);
+        const cacheMeta = this._agentMdAuthCacheMeta(target);
+        const remoteEtag = String(cacheMeta.etag ?? '').trim();
+        const lastModified = String(cacheMeta.lastModified ?? cacheMeta.last_modified ?? '').trim();
+        if (isSelf) {
+            this._localAgentMdEtag = localEtag;
+            if (remoteEtag)
+                this._remoteAgentMdEtag = remoteEtag;
+        }
+        await this._saveAgentMdRecord(target, {
+            content,
+            local_etag: localEtag,
+            remote_etag: remoteEtag || undefined,
+            last_modified: lastModified || undefined,
+            fetched_at: Date.now(),
+            remote_status: 'found',
+            verify_status: isJsonObject(signature) ? String(signature.status ?? '') : '',
+            verify_error: isJsonObject(signature) ? String(signature.reason ?? '') : '',
+            last_error: '',
+        });
         let in_sync = null;
         if (isSelf) {
-            const buf = new TextEncoder().encode(content);
-            const digest = await crypto.subtle.digest('SHA-256', buf);
-            const hex = Array.from(new Uint8Array(digest))
-                .map((b) => b.toString(16).padStart(2, '0'))
-                .join('');
-            this._localAgentMdEtag = `"${hex}"`;
-            const local = this._localAgentMdEtag || '';
-            const remote = this._remoteAgentMdEtag || '';
-            in_sync = local && remote ? local === remote : false;
+            const remote = remoteEtag || this._remoteAgentMdEtag || '';
+            in_sync = localEtag && remote ? localEtag === remote : false;
         }
         return {
             aid: target,
@@ -600,13 +838,396 @@ export class AUNClient {
             in_sync,
         };
     }
+    getLocalAgentMdEtag() {
+        return this._localAgentMdEtag;
+    }
+    getRemoteAgentMdEtag() {
+        return this._remoteAgentMdEtag;
+    }
+    async _agentMdContentEtag(content) {
+        const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(String(content ?? '')));
+        const hex = Array.from(new Uint8Array(digest)).map((b) => b.toString(16).padStart(2, '0')).join('');
+        return `"${hex}"`;
+    }
+    _agentMdOwnerAid() {
+        return String(this._aid ?? '').trim();
+    }
+    _agentMdDefaultRoot() {
+        return this._joinAgentMdPath(this.configModel.aunPath || '.', 'AgentMDs');
+    }
+    _joinAgentMdPath(base, name) {
+        const left = String(base ?? '').trim().replace(/[\\/]+$/g, '');
+        return left ? `${left}/${name}` : name;
+    }
+    _agentMdRoot() {
+        return this._agentMdPath || this._agentMdDefaultRoot();
+    }
+    _agentMdSafeAid(aid) {
+        const target = String(aid ?? '').trim();
+        if (!target || target.includes('/') || target.includes('\\') || target.includes('\0')) {
+            throw new ValidationError('agent.md aid is empty or contains path separators');
+        }
+        return target;
+    }
+    _agentMdMetaKey(aid) {
+        return `${this._agentMdSafeAid(aid)}/agentmd.json`;
+    }
+    _agentMdContentKey(aid) {
+        return `${this._agentMdSafeAid(aid)}/agent.md`;
+    }
+    async _readAgentMdStorage(logicalKey) {
+        const key = String(logicalKey ?? '').trim();
+        if (!key)
+            return null;
+        const load = this._keystore.loadAgentMdCache;
+        if (typeof load !== 'function') {
+            throw new Error('IndexedDB agent.md storage unavailable');
+        }
+        const record = await load.call(this._keystore, this._agentMdRoot(), key);
+        if (record && Object.prototype.hasOwnProperty.call(record, 'content')) {
+            return String(record.content ?? '');
+        }
+        return null;
+    }
+    async _writeAgentMdStorage(logicalKey, content) {
+        const key = String(logicalKey ?? '').trim();
+        if (!key)
+            return;
+        const save = this._keystore.upsertAgentMdCache;
+        if (typeof save !== 'function') {
+            throw new Error('IndexedDB agent.md storage unavailable');
+        }
+        const text = String(content ?? '');
+        await save.call(this._keystore, this._agentMdRoot(), key, {
+            content: text,
+            local_etag: await this._agentMdContentEtag(text),
+            fetched_at: Date.now(),
+        });
+    }
+    async _withAgentMdLock(fn) {
+        const previous = this._agentMdLock.catch(() => undefined);
+        let release;
+        const current = new Promise((resolve) => { release = resolve; });
+        this._agentMdLock = previous.then(() => current);
+        await previous;
+        try {
+            return await fn();
+        }
+        finally {
+            release();
+        }
+    }
+    _normalizeAgentMdRecord(aid, data) {
+        if (!isJsonObject(data))
+            return {};
+        const record = {};
+        for (const [key, value] of Object.entries(data)) {
+            if (key !== 'content')
+                record[key] = value;
+        }
+        record.aid = this._agentMdSafeAid(String(record.aid ?? aid));
+        for (const key of ['fetched_at', 'observed_at', 'checked_at', 'updated_at']) {
+            record[key] = Number(record[key] ?? 0) || 0;
+        }
+        return record;
+    }
+    async _writeAgentMdRecordUnlocked(aid, record) {
+        const payload = {};
+        for (const [key, value] of Object.entries(record)) {
+            if (key !== 'content' && value !== undefined && value !== null)
+                payload[key] = value;
+        }
+        payload.aid = this._agentMdSafeAid(aid);
+        await this._writeAgentMdStorage(this._agentMdMetaKey(aid), `${JSON.stringify(payload, null, 2)}\n`);
+    }
+    async _readAgentMdRecordUnlocked(aid) {
+        const raw = await this._readAgentMdStorage(this._agentMdMetaKey(aid));
+        if (raw === null)
+            return {};
+        try {
+            return this._normalizeAgentMdRecord(aid, JSON.parse(raw));
+        }
+        catch (err) {
+            this._clientLog.warn(`agent.md metadata damaged, ignoring: aid=${aid} err=${err instanceof Error ? err.message : String(err)}`);
+            return {};
+        }
+    }
+    async _readAgentMdContent(aid) {
+        return await this._readAgentMdStorage(this._agentMdContentKey(aid));
+    }
+    async _writeAgentMdContent(aid, content) {
+        await this._writeAgentMdStorage(this._agentMdContentKey(aid), String(content ?? ''));
+    }
+    _agentMdAuthCacheMeta(aid) {
+        try {
+            const store = this.auth._agentMdCache;
+            const record = store?.get(String(aid ?? '').trim());
+            return record && typeof record === 'object' ? { ...record } : {};
+        }
+        catch {
+            return {};
+        }
+    }
+    async _loadAgentMdRecord(aid) {
+        const target = String(aid ?? '').trim();
+        if (!target)
+            return null;
+        try {
+            const loaded = await this._withAgentMdLock(async () => {
+                const record = await this._readAgentMdRecordUnlocked(target);
+                const next = Object.keys(record).length > 0 ? { ...record, aid: target } : { aid: target };
+                try {
+                    const content = await this._readAgentMdContent(target);
+                    if (content !== null) {
+                        next.content = content;
+                        next.local_etag = await this._agentMdContentEtag(content);
+                    }
+                    else {
+                        // 元数据存在但正文缺失
+                        const metaRaw = await this._readAgentMdStorage(this._agentMdMetaKey(target));
+                        if (metaRaw !== null) {
+                            this._clientLog.warn(`agent.md content read failed: aid=${target}`);
+                        }
+                    }
+                }
+                catch (err) {
+                    this._clientLog.warn(`agent.md content read failed: aid=${target} err=${err instanceof Error ? err.message : String(err)}`);
+                }
+                return next;
+            });
+            if (Object.keys(loaded).length <= 1)
+                return null;
+            this._agentMdCache.set(target, { ...loaded });
+            return { ...loaded };
+        }
+        catch (err) {
+            this._clientLog.debug(`agent.md cache load skipped: aid=${target} err=${err instanceof Error ? err.message : String(err)}`);
+        }
+        return null;
+    }
+    async _saveAgentMdRecord(aid, fields) {
+        const target = String(aid ?? '').trim();
+        if (!target)
+            return {};
+        try {
+            const inputFields = { ...fields };
+            const hasContent = Object.prototype.hasOwnProperty.call(inputFields, 'content') && inputFields.content !== undefined && inputFields.content !== null;
+            if (hasContent) {
+                const text = String(inputFields.content ?? '');
+                await this._writeAgentMdContent(target, text);
+                if (!inputFields.local_etag)
+                    inputFields.local_etag = await this._agentMdContentEtag(text);
+                if (!inputFields.fetched_at)
+                    inputFields.fetched_at = Date.now();
+            }
+            delete inputFields.content;
+            const record = await this._withAgentMdLock(async () => {
+                const next = { ...(await this._readAgentMdRecordUnlocked(target)), aid: target };
+                for (const [key, value] of Object.entries(inputFields)) {
+                    if (value !== undefined && value !== null)
+                        next[key] = value;
+                }
+                next.updated_at = Date.now();
+                await this._writeAgentMdRecordUnlocked(target, next);
+                return next;
+            });
+            const loaded = { ...record };
+            if (hasContent)
+                loaded.content = String(fields.content ?? '');
+            this._agentMdCache.set(target, { ...loaded });
+            const owner = this._agentMdOwnerAid();
+            if (target === owner) {
+                const localEtag = String(loaded.local_etag ?? '').trim();
+                const remoteEtag = String(loaded.remote_etag ?? '').trim();
+                if (localEtag)
+                    this._localAgentMdEtag = localEtag;
+                if (remoteEtag)
+                    this._remoteAgentMdEtag = remoteEtag;
+            }
+            return { ...loaded };
+        }
+        catch (err) {
+            this._clientLog.debug(`agent.md cache save skipped: aid=${target} err=${err instanceof Error ? err.message : String(err)}`);
+        }
+        return {};
+    }
+    async _agentMdHasLocalContent(aid, record) {
+        if (record && typeof record.content === 'string' && record.content.length > 0)
+            return true;
+        try {
+            return (await this._readAgentMdContent(aid)) !== null;
+        }
+        catch {
+            return false;
+        }
+    }
+    _agentMdCheckedAtFresh(checkedAtMs, maxUnsyncedDays) {
+        const days = Number(maxUnsyncedDays || 0);
+        if (!Number.isFinite(days) || days <= 0)
+            return false;
+        if (!Number.isFinite(checkedAtMs) || checkedAtMs <= 0)
+            return false;
+        return Date.now() - checkedAtMs <= days * 86400000;
+    }
+    _agentMdLastModifiedFresh(lastModified, maxUnsyncedDays) {
+        const days = Number(maxUnsyncedDays || 0);
+        if (!Number.isFinite(days) || days <= 0)
+            return false;
+        const ts = Date.parse(String(lastModified ?? '').trim());
+        if (!Number.isFinite(ts))
+            return false;
+        return Date.now() <= ts + days * 86400000;
+    }
+    async _scheduleAgentMdFetchIfMissing(aid, record, source = '') {
+        const target = String(aid ?? '').trim();
+        if (!target || await this._agentMdHasLocalContent(target, record))
+            return;
+        if (this._agentMdFetchInflight.has(target))
+            return;
+        this._agentMdFetchInflight.add(target);
+        try {
+            await this.fetchAgentMd(target);
+        }
+        catch (err) {
+            await this._saveAgentMdRecord(target, {
+                last_error: err instanceof Error ? err.message : String(err),
+                remote_status: 'found',
+            });
+            this._clientLog.debug(`agent.md auto fetch failed: aid=${target} source=${source || '-'} err=${err instanceof Error ? err.message : String(err)}`);
+        }
+        finally {
+            this._agentMdFetchInflight.delete(target);
+        }
+    }
+    async _observeAgentMdMeta(aid, etag = '', lastModified = '', source = '') {
+        const target = String(aid ?? '').trim();
+        const remoteEtag = String(etag ?? '').trim();
+        const remoteLastModified = String(lastModified ?? '').trim();
+        if (!target || (!remoteEtag && !remoteLastModified))
+            return;
+        let before = this._agentMdCache.get(target);
+        if (!before || typeof before !== 'object')
+            before = await this._loadAgentMdRecord(target) ?? {};
+        const same = (!remoteEtag || String(before.remote_etag ?? '').trim() === remoteEtag) &&
+            (!remoteLastModified || String(before.last_modified ?? '').trim() === remoteLastModified);
+        let record = { ...before };
+        if (!same || Object.keys(before).length === 0) {
+            const fields = {
+                observed_at: Date.now(),
+                remote_status: 'found',
+            };
+            if (remoteEtag)
+                fields.remote_etag = remoteEtag;
+            if (remoteLastModified)
+                fields.last_modified = remoteLastModified;
+            record = await this._saveAgentMdRecord(target, fields) || record;
+        }
+        if (target === this._agentMdOwnerAid() && remoteEtag)
+            this._remoteAgentMdEtag = remoteEtag;
+        await this._scheduleAgentMdFetchIfMissing(target, record, source);
+        this._clientLog.debug(`agent.md meta observed: aid=${target} etag=${remoteEtag || '-'} last_modified=${remoteLastModified || '-'} source=${source || '-'}`);
+    }
+    async _observeAgentMdEtag(aid, etag, source = '') {
+        await this._observeAgentMdMeta(aid, etag, '', source);
+    }
+    async _observeAgentMdFromEnvelope(envelope) {
+        if (!isJsonObject(envelope))
+            return;
+        const env = envelope;
+        if (!isJsonObject(env.agent_md))
+            return;
+        const agentMd = env.agent_md;
+        if (!isJsonObject(agentMd.sender))
+            return;
+        const sender = agentMd.sender;
+        let senderAid = String(sender.aid ?? '').trim();
+        if (!senderAid) {
+            const aad = isJsonObject(env.aad) ? env.aad : {};
+            senderAid = String(aad.from ?? env.from ?? '').trim();
+        }
+        await this._observeAgentMdMeta(senderAid, String(sender.etag ?? '').trim(), String(sender.last_modified ?? sender.lastModified ?? '').trim(), 'envelope');
+    }
+    async checkAgentMd(aid, maxUnsyncedDays = 0) {
+        const target = String(aid ?? this._aid ?? '').trim();
+        if (!target)
+            throw new ValidationError('checkAgentMd requires aid (or local AID)');
+        const before = await this._loadAgentMdRecord(target) ?? {};
+        const localEtag = String(before.local_etag ?? '').trim();
+        const localFound = !!(Object.keys(before).length > 0 && (String(before.content ?? '') || localEtag));
+        const remoteEtagCached = String(before.remote_etag ?? '').trim();
+        const lastModifiedCached = String(before.last_modified ?? '').trim();
+        const checkedAtCached = Number(before.checked_at ?? 0);
+        const cachedInSync = !!(localFound && localEtag && remoteEtagCached && localEtag === remoteEtagCached);
+        // max_unsynced_days > 0 且距上次 HEAD 在窗口内 → 直接返回缓存；否则强制 HEAD。
+        if (cachedInSync && this._agentMdCheckedAtFresh(checkedAtCached, maxUnsyncedDays)) {
+            return {
+                aid: target,
+                local_found: true,
+                remote_found: true,
+                local_etag: localEtag,
+                remote_etag: remoteEtagCached,
+                in_sync: true,
+                last_modified: lastModifiedCached,
+                status: 200,
+                cached: true,
+                verify_status: String(before.verify_status ?? ''),
+                verify_error: String(before.verify_error ?? ''),
+            };
+        }
+        const now = Date.now();
+        let remote;
+        try {
+            remote = await this.auth.headAgentMd(target);
+        }
+        catch (err) {
+            await this._saveAgentMdRecord(target, { checked_at: now, remote_status: 'error', last_error: err instanceof Error ? err.message : String(err) });
+            throw err;
+        }
+        const remoteFound = !!remote.found;
+        const remoteEtag = String(remote.etag ?? '').trim();
+        const lastModified = String(remote.last_modified ?? remote.lastModified ?? '').trim();
+        const saved = await this._saveAgentMdRecord(target, {
+            remote_etag: remoteFound ? remoteEtag : '',
+            last_modified: lastModified,
+            checked_at: now,
+            remote_status: remoteFound ? 'found' : 'missing',
+            last_error: '',
+        });
+        if (target === this._agentMdOwnerAid() && remoteEtag)
+            this._remoteAgentMdEtag = remoteEtag;
+        const inSync = !!(localFound && remoteFound && localEtag && remoteEtag && localEtag === remoteEtag);
+        return {
+            aid: target,
+            local_found: localFound,
+            remote_found: remoteFound,
+            local_etag: localEtag,
+            remote_etag: remoteEtag,
+            in_sync: inSync,
+            last_modified: lastModified,
+            status: Number(remote.status ?? (remoteFound ? 200 : 404)),
+            cached: false,
+            verify_status: String(saved.verify_status ?? before.verify_status ?? ''),
+            verify_error: String(saved.verify_error ?? before.verify_error ?? ''),
+        };
+    }
     /** transport 的 meta observer：吸收 gateway 注入的 _meta 字段。失败不影响业务。 */
-    _observeRpcMeta(meta) {
+    async _observeRpcMeta(meta) {
         if (!isJsonObject(meta))
             return;
         const etag = String(meta.agent_md_etag ?? '').trim();
         if (etag) {
             this._remoteAgentMdEtag = etag;
+            await this._observeAgentMdMeta(this._aid ?? '', etag, '', 'rpc.self');
+        }
+        const etags = meta.agent_md_etags;
+        if (isJsonObject(etags)) {
+            // role key 优先级：requester / peer 是新规范，其余是兼容旧 SDK 的别名。
+            for (const key of ['requester', 'peer', 'receiver', 'target', 'to', 'sender', 'from']) {
+                const item = etags[key];
+                if (!isJsonObject(item))
+                    continue;
+                await this._observeAgentMdMeta(String(item.aid ?? ''), String(item.etag ?? ''), String(item.last_modified ?? item.lastModified ?? ''), `rpc.${key}`);
+            }
         }
     }
     get state() {
@@ -660,18 +1281,30 @@ export class AUNClient {
         this._sessionOptions = this._buildSessionOptions(normalized);
         this._transport.setTimeout(this._sessionOptions.timeouts.call);
         this._closing = false;
-        try {
-            await this._connectOnce(normalized, false);
-            this._clientLog.debug(`connect exit: elapsed=${Date.now() - tStart}ms state=${this._state}`);
-        }
-        catch (err) {
-            // 连接失败时回退状态，允许重试
-            if (this._state === 'connecting' || this._state === 'authenticating') {
-                this._state = 'disconnected';
+        const gateways = this._resolveGateways(normalized);
+        let lastErr = null;
+        for (const gw of gateways) {
+            try {
+                const gwParams = { ...normalized, gateway: gw };
+                await this._connectOnce(gwParams, false);
+                this._clientLog.debug(`connect exit: elapsed=${Date.now() - tStart}ms state=${this._state}`);
+                return;
             }
-            this._clientLog.debug(`connect exit (error): elapsed=${Date.now() - tStart}ms err=${err instanceof Error ? err.message : String(err)}`);
-            throw err;
+            catch (err) {
+                lastErr = err;
+                if (gateways.length > 1) {
+                    this._clientLog.warn(`connect: gateway ${gw} failed, trying next: ${err instanceof Error ? err.message : String(err)}`);
+                }
+                if (this._state === 'connecting' || this._state === 'authenticating') {
+                    this._state = 'connecting';
+                }
+            }
+        }
+        if (this._state === 'connecting' || this._state === 'authenticating') {
+            this._state = 'disconnected';
         }
+        this._clientLog.debug(`connect exit (error): elapsed=${Date.now() - tStart}ms err=${lastErr instanceof Error ? lastErr.message : String(lastErr)}`);
+        throw lastErr;
     }
     /** 断开连接但保留本地状态，可再次 connect */
     async disconnect() {
@@ -803,6 +1436,9 @@ export class AUNClient {
             throw new PermissionError(`legacy E2EE method is removed in this SDK: ${method}`);
         }
         const p = { ...(params ?? {}) };
+        if (method === 'message.send' || method === 'group.send') {
+            this._normalizeOutboundMessagePayload(p, method);
+        }
         this._validateOutboundCall(method, p);
         this._injectMessageCursorContext(method, p);
         // group.* 方法的 group_id 归一化为 canonical 格式（兼容老/污染数据）
@@ -815,7 +1451,7 @@ export class AUNClient {
             p.group_id = normalizedGroupId;
         }
         // group.* 方法注入 device_id（服务端用于多设备消息路由）
-        if (method.startsWith('group.') && this._deviceId && p.device_id === undefined) {
+        if (method.startsWith('group.') && p.device_id === undefined) {
             p.device_id = this._deviceId;
         }
         if (method.startsWith('group.') && p.slot_id === undefined) {
@@ -880,6 +1516,20 @@ export class AUNClient {
                 return this._putMessageThoughtEncryptedV2(p);
             }
         }
+        // Pull Gate：序列化同一 key 的 pull 操作，防止并发重复拉取
+        const pullGateKey = this._pullGateKeyForCall(method, p);
+        if (pullGateKey) {
+            return await this._runPullSerialized(pullGateKey, async () => {
+                return await this._callImplInner(method, p);
+            });
+        }
+        return await this._callImplInner(method, p);
+    }
+    /**
+     * _callImpl 的内层：pull gate 之后的实际 RPC 分发逻辑。
+     * 拆分出来以便 pull gate 包裹整个操作。
+     */
+    async _callImplInner(method, p) {
         // message.pull：V2 就绪时走 V2 pull
         if (method === 'message.pull' && this._v2Session) {
             this._clientLog.debug('call route: message.pull → V2 pull');
@@ -904,7 +1554,12 @@ export class AUNClient {
         }
         // 关键操作自动附加客户端签名
         if (SIGNED_METHODS.has(method)) {
-            await this._signClientOperation(method, p);
+            if (this._shouldSkipClientSignature(method, p)) {
+                delete p.client_signature;
+            }
+            else {
+                await this._signClientOperation(method, p);
+            }
         }
         // P1-23: 非幂等方法使用更长超时
         const callTimeout = NON_IDEMPOTENT_METHODS.has(method) ? NON_IDEMPOTENT_TIMEOUT : undefined;
@@ -1042,6 +1697,9 @@ export class AUNClient {
             const seq = msg.seq;
             if (seq !== undefined && seq !== null && this._aid) {
                 const ns = `p2p:${this._aid}`;
+                // Push 修上界：先更新 maxSeenSeq
+                if (seq > 0)
+                    this._seqTracker.updateMaxSeen(ns, seq);
                 const needPull = this._seqTracker.onMessageSeq(ns, seq);
                 if (needPull) {
                     this._safeAsync(this._fillP2pGap());
@@ -1049,8 +1707,10 @@ export class AUNClient {
                 // auto-ack contiguous_seq
                 const contig = this._seqTracker.getContiguousSeq(ns);
                 if (contig > 0) {
+                    const maxSeen = this._seqTracker.getMaxSeenSeq(ns);
+                    const ackSeq = maxSeen > 0 ? Math.min(contig, maxSeen) : contig;
                     this._transport.call('message.ack', {
-                        seq: contig,
+                        seq: ackSeq,
                         device_id: this._deviceId,
                         slot_id: this._slotId,
                     }).catch((e) => { this._clientLog.warn(`P2P auto-ack failed:${String(e)}`); });
@@ -1079,6 +1739,7 @@ export class AUNClient {
                     timestamp: (src.timestamp ?? null),
                     _decrypt_error: String(exc),
                 };
+                attachV2EnvelopeMetadataFromSource(safeEvent, data);
                 await this._publishAppEvent('message.undecryptable', safeEvent);
             }
         }
@@ -1111,6 +1772,14 @@ export class AUNClient {
         }
         try {
             const ns = `group:${groupId}`;
+            // Push 修上界：先更新 maxSeenSeq
+            this._seqTracker.updateMaxSeen(ns, seq);
+            const contigBefore = this._seqTracker.getContiguousSeq(ns);
+            if (contigBefore === seq) {
+                this._clientLog.debug(`_onRawGroupV2MessageCreated duplicate push already covered: group=${groupId} seq=${seq}`);
+                return;
+            }
+            const afterSeq = this._repairPushContiguousBound(ns, seq, false, '_raw.group.v2.message_created');
             // per-namespace 去重：同一 group namespace 只允许 1 个 in-flight pull
             const dedupKey = `group_pull:${ns}`;
             if (this._gapFillDone.has(dedupKey)) {
@@ -1119,7 +1788,6 @@ export class AUNClient {
             }
             this._gapFillDone.add(dedupKey);
             try {
-                const afterSeq = Math.max(0, this._seqTracker.getContiguousSeq(ns));
                 this._clientLog.debug(`_onRawGroupV2MessageCreated -> group.v2.pull group=${groupId} after_seq=${afterSeq}`);
                 const messages = await this.pullGroupV2(groupId, afterSeq, 50);
                 this._clientLog.debug(`_onRawGroupV2MessageCreated pulled ${messages.length} msgs for group=${groupId}`);
@@ -1164,15 +1832,20 @@ export class AUNClient {
             // seq 跟踪 + auto-ack
             if (groupId && seq !== undefined && seq !== null) {
                 const ns = `group:${groupId}`;
+                // Push 修上界：先更新 maxSeenSeq
+                if (seq > 0)
+                    this._seqTracker.updateMaxSeen(ns, seq);
                 const needPull = this._seqTracker.onMessageSeq(ns, seq);
                 if (needPull) {
                     this._safeAsync(this._fillGroupGap(groupId));
                 }
                 const contig = this._seqTracker.getContiguousSeq(ns);
                 if (contig > 0) {
+                    const maxSeen = this._seqTracker.getMaxSeenSeq(ns);
+                    const ackSeq = maxSeen > 0 ? Math.min(contig, maxSeen) : contig;
                     this._transport.call('group.ack_messages', {
                         group_id: groupId,
-                        msg_seq: contig,
+                        msg_seq: ackSeq,
                         device_id: this._deviceId,
                         slot_id: this._slotId,
                     }).catch((e) => { this._clientLog.warn('group message auto-ack failed: group=' + groupId, e); });
@@ -1200,6 +1873,7 @@ export class AUNClient {
                     timestamp: (src.timestamp ?? null),
                     _decrypt_error: String(exc),
                 };
+                attachV2EnvelopeMetadataFromSource(safeEvent, data);
                 await this._publishAppEvent('group.message_undecryptable', safeEvent);
             }
         }
@@ -1331,53 +2005,80 @@ export class AUNClient {
         this._gapFillDone.add(dedupKey);
         this._gapFillActive = true;
         try {
-            const result = await this.call('group.pull_events', {
-                group_id: groupId,
-                after_event_seq: afterSeq,
-                device_id: this._deviceId,
-                limit: 50,
-            });
-            if (isJsonObject(result)) {
+            let nextAfterSeq = afterSeq;
+            const maxPages = 100;
+            let pageCount = 0;
+            while (pageCount < maxPages) {
+                pageCount += 1;
+                const result = await this.call('group.pull_events', {
+                    group_id: groupId,
+                    after_event_seq: nextAfterSeq,
+                    device_id: this._deviceId,
+                    limit: 50,
+                });
+                if (!isJsonObject(result))
+                    return;
                 const events = result.events;
-                if (Array.isArray(events)) {
-                    this._seqTracker.onPullResult(ns, events.filter(isJsonObject), afterSeq);
-                    const cursor = isJsonObject(result.cursor) ? result.cursor : null;
-                    const serverAck = cursor ? Number(cursor.current_seq ?? 0) : 0;
-                    if (serverAck > 0) {
-                        const contigBefore = this._seqTracker.getContiguousSeq(ns);
-                        if (contigBefore < serverAck) {
-                            this._clientLog.info('group.pull_events retention-floor advance: ns=' + ns + ' contiguous=' + contigBefore + ' -> cursor.current_seq=' + serverAck);
-                            this._seqTracker.forceContiguousSeq(ns, serverAck);
-                        }
-                    }
-                    // 持久化 cursor + ack_events（与 Python 对齐）
-                    this._saveSeqTrackerState();
-                    const contig = this._seqTracker.getContiguousSeq(ns);
-                    if (contig > 0 && (events.length > 0 || serverAck > 0)) {
-                        this._transport.call('group.ack_events', {
-                            group_id: groupId,
-                            event_seq: contig,
-                            device_id: this._deviceId,
-                            slot_id: this._slotId,
-                        }).catch((e) => { this._clientLog.warn('group event auto-ack failed: group=' + groupId, e); });
+                if (!Array.isArray(events))
+                    return;
+                const pageContigBefore = this._seqTracker.getContiguousSeq(ns);
+                const eventObjects = events.filter(isJsonObject);
+                if (eventObjects.length > 0) {
+                    this._seqTracker.onPullResult(ns, eventObjects, nextAfterSeq);
+                }
+                const cursor = isJsonObject(result.cursor) ? result.cursor : null;
+                const serverAck = cursor ? Number(cursor.current_seq ?? 0) : 0;
+                if (serverAck > 0) {
+                    const contigBeforeFloor = this._seqTracker.getContiguousSeq(ns);
+                    if (contigBeforeFloor < serverAck) {
+                        this._clientLog.info('group.pull_events retention-floor advance: ns=' + ns + ' contiguous=' + contigBeforeFloor + ' -> cursor.current_seq=' + serverAck);
+                        this._seqTracker.forceContiguousSeq(ns, serverAck);
                     }
-                    for (const evt of events) {
-                        if (isJsonObject(evt)) {
-                            evt._from_gap_fill = true;
-                            const et = String(evt.event_type ?? '');
-                            // 消息事件由 _fillGroupGap 负责，事件补洞不重复投递
-                            if (et === 'group.message_created')
-                                continue;
-                            // 验签：有 client_signature 就验（与实时事件路径对齐）
-                            const cs = evt.client_signature;
-                            if (cs && typeof cs === 'object') {
-                                evt._verified = await this._verifyEventSignature(evt, cs);
-                            }
-                            // group.changed 或缺失/其他 → 发布到 group.changed（向后兼容）
-                            await this._dispatcher.publish('group.changed', evt);
+                }
+                const eventSeqs = [];
+                for (const evt of eventObjects) {
+                    const eventSeq = Number(evt.event_seq ?? 0);
+                    if (Number.isFinite(eventSeq) && eventSeq > 0)
+                        eventSeqs.push(eventSeq);
+                    evt._from_gap_fill = true;
+                    const et = String(evt.event_type ?? '');
+                    // 消息事件由 _fillGroupGap 负责，事件补洞不重复投递
+                    if (et === 'group.message_created')
+                        continue;
+                    // 验签：有 client_signature 就验（与实时事件路径对齐）
+                    const cs = evt.client_signature;
+                    if (cs && typeof cs === 'object') {
+                        if (this._shouldSkipEventSignature(evt)) {
+                            delete evt.client_signature;
+                        }
+                        else {
+                            evt._verified = await this._verifyEventSignature(evt, cs);
                         }
                     }
+                    // group.changed 或缺失/其他 → 发布到 group.changed（向后兼容）
+                    await this._dispatcher.publish('group.changed', evt);
+                }
+                const contig = this._seqTracker.getContiguousSeq(ns);
+                if (contig !== pageContigBefore) {
+                    this._saveSeqTrackerState();
+                }
+                if (eventObjects.length > 0 && contig > 0 && contig !== pageContigBefore) {
+                    const maxSeen = this._seqTracker.getMaxSeenSeq(ns);
+                    const ackSeq = maxSeen > 0 ? Math.min(contig, maxSeen) : contig;
+                    this._transport.call('group.ack_events', {
+                        group_id: groupId,
+                        event_seq: ackSeq,
+                        device_id: this._deviceId,
+                        slot_id: this._slotId,
+                    }).catch((e) => { this._clientLog.warn('group event auto-ack failed: group=' + groupId, e); });
                 }
+                const nextAfter = Math.max(eventSeqs.length > 0 ? Math.max(...eventSeqs) : nextAfterSeq, nextAfterSeq);
+                if (eventObjects.length === 0 || nextAfter <= nextAfterSeq || result.has_more === false)
+                    break;
+                nextAfterSeq = nextAfter;
+            }
+            if (pageCount >= maxPages) {
+                this._clientLog.warn(`group event gap fill reached max_pages=${maxPages} group=${groupId} after_seq=${nextAfterSeq}`);
             }
         }
         catch (exc) {
@@ -1495,10 +2196,10 @@ export class AUNClient {
         if (!isJsonObject(payload))
             return payload;
         const result = { ...payload };
-        if (this._deviceId && !String(result.device_id ?? '').trim()) {
+        if (!('device_id' in result)) {
             result.device_id = this._deviceId;
         }
-        if (this._slotId && !String(result.slot_id ?? '').trim()) {
+        if (!('slot_id' in result)) {
             result.slot_id = this._slotId;
         }
         return result;
@@ -1554,6 +2255,18 @@ export class AUNClient {
         const trace = `${this._echoTimestamp()} [AUN-SDK.send] aid=${this._aid ?? '-'} conn_uptime=${uptime}s`;
         params.payload = { ...payload, text: payload.text + '\n' + trace };
     }
+    _shouldSkipClientSignature(method, params) {
+        if (method !== 'message.send' && method !== 'group.send')
+            return false;
+        if (params.encrypted || params.encrypt)
+            return false;
+        return this._isEchoPayload(params.payload);
+    }
+    _shouldSkipEventSignature(event) {
+        if (event.encrypted || event.encrypt)
+            return false;
+        return this._isEchoPayload(event.payload);
+    }
     _maybeAppendEchoTraceReceive(msg) {
         if (msg.encrypted)
             return;
@@ -1567,13 +2280,17 @@ export class AUNClient {
     _messageTargetsCurrentInstance(message) {
         if (!isJsonObject(message))
             return true;
-        const targetDeviceId = String(message.device_id ?? '').trim();
-        if (targetDeviceId && this._deviceId && targetDeviceId !== this._deviceId) {
-            return false;
+        if ('device_id' in message) {
+            const targetDeviceId = String(message.device_id ?? '').trim();
+            if (targetDeviceId !== this._deviceId) {
+                return false;
+            }
         }
-        const targetSlotId = String(message.slot_id ?? '').trim();
-        if (targetSlotId && this._slotId && targetSlotId !== this._slotId) {
-            return false;
+        if ('slot_id' in message) {
+            const targetSlotId = String(message.slot_id ?? '').trim();
+            if (targetSlotId !== this._slotId) {
+                return false;
+            }
         }
         return true;
     }
@@ -1668,7 +2385,12 @@ export class AUNClient {
                 // 验签：有 client_signature 就验，没有默认安全
                 const cs = d.client_signature;
                 if (cs && isJsonObject(cs)) {
-                    d._verified = await this._verifyEventSignature(d, cs);
+                    if (this._shouldSkipEventSignature(d)) {
+                        delete d.client_signature;
+                    }
+                    else {
+                        d._verified = await this._verifyEventSignature(d, cs);
+                    }
                 }
                 await this._dispatcher.publish('group.changed', d);
                 const groupId = (d.group_id ?? '');
@@ -1677,14 +2399,20 @@ export class AUNClient {
                     this._v2BootstrapCache.delete(`group:${groupId}`);
                 }
                 // Group SPK 编排：成员变更触发注册/轮换
+                const membershipActions = new Set([
+                    'member_added', 'member_left', 'member_removed', 'role_changed',
+                    'owner_transferred', 'joined', 'join_approved', 'invite_code_used',
+                ]);
                 if (this._v2Session && groupId) {
-                    const membershipActions = new Set([
-                        'member_added', 'member_left', 'member_removed', 'role_changed',
-                        'owner_transferred', 'joined', 'join_approved',
-                    ]);
                     if (membershipActions.has(action)) {
                         const callFn = async (method, params) => this.call(method, params);
-                        if (action === 'joined' || action === 'join_approved') {
+                        const joinedAid = String(d.joined_aid ?? d.member_aid ?? d.aid ?? '').trim();
+                        const actorAid = String(d.actor_aid ?? '').trim();
+                        const selfAid = String(this._aid ?? '').trim();
+                        const joinActions = new Set(['member_added', 'joined', 'join_approved', 'invite_code_used']);
+                        const isSelfJoin = joinActions.has(action) && !!selfAid && (joinedAid === selfAid ||
+                            (!joinedAid && (action === 'joined' || action === 'invite_code_used') && actorAid === selfAid));
+                        if (isSelfJoin) {
                             this._v2Session.ensureGroupRegistered?.(groupId, callFn)?.catch(exc => {
                                 this._clientLog.debug(`group SPK registration failed (non-fatal): group=${groupId} action=${action} err=${exc}`);
                             });
@@ -1696,7 +2424,7 @@ export class AUNClient {
                         }
                     }
                 }
-                if (groupId && action === 'upsert' && this._v2Session) {
+                if (groupId && this._v2Session && (action === 'upsert' || membershipActions.has(action))) {
                     this._safeAsync(this._v2AutoProposeState(groupId, { leaderDelay: true }));
                 }
                 // event_seq 空洞检测：持久化后的 group.changed 会携带 event_seq。
@@ -1761,12 +2489,17 @@ export class AUNClient {
         // 提交者签名验证
         const cs = d.client_signature;
         if (cs && isJsonObject(cs)) {
-            const verified = await this._verifyEventSignature(d, cs);
-            if (verified === false) {
-                this._clientLog.warn(`state_committed committer signature verify failed group=%s${String(groupId)}`);
-                return;
+            if (this._shouldSkipEventSignature(d)) {
+                delete d.client_signature;
+            }
+            else {
+                const verified = await this._verifyEventSignature(d, cs);
+                if (verified === false) {
+                    this._clientLog.warn(`state_committed committer signature verify failed group=%s${String(groupId)}`);
+                    return;
+                }
+                d._verified = verified;
             }
-            d._verified = verified;
         }
         const stateVersion = Number(d.state_version ?? 0);
         const stateHash = String(d.state_hash ?? '').trim();
@@ -2036,6 +2769,7 @@ export class AUNClient {
             let e2eeMeta = null;
             let decryptFailed = false;
             if (isV2Envelope) {
+                e2eeMeta = v2E2eeMeta(payload);
                 const plaintext = await this._decryptV2EnvelopeForThought({
                     envelope: payload,
                     fromAid: senderAid,
@@ -2047,7 +2781,7 @@ export class AUNClient {
                 }
                 else {
                     decryptedPayload = plaintext;
-                    const e2eeObj = v2E2eeMeta(payload);
+                    const e2eeObj = e2eeMeta;
                     // 暴露 protected_headers（去 _auth）
                     const ph = payload.protected_headers;
                     if (isJsonObject(ph)) {
@@ -2084,6 +2818,8 @@ export class AUNClient {
                 created_at: item.created_at,
                 e2ee: e2eeMeta,
             };
+            if (isJsonObject(e2eeMeta))
+                attachV2EnvelopeMetadata(thought, e2eeMeta);
             if (decryptFailed)
                 thought.decrypt_failed = true;
             if ('context' in item)
@@ -2122,6 +2858,8 @@ export class AUNClient {
             let decryptFailed = false;
             // V2 P2P thought envelope：per-device wrap，本设备解密自己的 row
             if (payload?.type === 'e2ee.p2p_encrypted') {
+                const e2eeObj = v2E2eeMeta(payload);
+                message.e2ee = e2eeObj;
                 const plaintext = await this._decryptV2EnvelopeForThought({
                     envelope: payload,
                     fromAid,
@@ -2133,7 +2871,6 @@ export class AUNClient {
                 else {
                     decrypted = { ...message };
                     decrypted.payload = plaintext;
-                    const e2eeObj = v2E2eeMeta(payload);
                     // 暴露 protected_headers（去 _auth）
                     const ph = payload.protected_headers;
                     if (isJsonObject(ph)) {
@@ -2162,6 +2899,7 @@ export class AUNClient {
             else if (payload?.type === 'e2ee.encrypted') {
                 decryptFailed = true;
             }
+            const exposedE2ee = (decrypted ?? message).e2ee;
             const thought = {
                 thought_id: thoughtId,
                 message_id: thoughtId,
@@ -2169,8 +2907,10 @@ export class AUNClient {
                 to: toAid,
                 payload: (decrypted ?? message).payload,
                 created_at: item.created_at,
-                e2ee: (decrypted ?? message).e2ee,
+                e2ee: exposedE2ee,
             };
+            if (isJsonObject(exposedE2ee))
+                attachV2EnvelopeMetadata(thought, exposedE2ee);
             if (decryptFailed)
                 thought.decrypt_failed = true;
             if ('context' in item)
@@ -2184,7 +2924,7 @@ export class AUNClient {
      * 获取对方证书（带缓存 + 完整 PKI 验证：链 + CRL + OCSP + AID 绑定）。
      * 跨域时自动将请求路由到 peer 所在域的 Gateway。
      */
-    async _fetchPeerCert(aid, certFingerprint) {
+    async _fetchPeerCert(aid, certFingerprint, timeoutMs = 5000) {
         const tStart = Date.now();
         this._clientLog.debug(`_fetchPeerCert enter: aid=${aid} fingerprint=${certFingerprint ?? '<none>'}`);
         try {
@@ -2206,7 +2946,7 @@ export class AUNClient {
                 const certUrl = buildCertUrl(peerGatewayUrl, aid, certFingerprint);
                 // 兼容旧浏览器，不使用 AbortSignal.timeout（Chrome 103+ 才支持）
                 const controller = new AbortController();
-                const timeoutId = setTimeout(() => controller.abort(), 5000);
+                const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
                 try {
                     const resp = await fetch(certUrl, { signal: controller.signal });
                     if (!resp.ok)
@@ -2223,7 +2963,7 @@ export class AUNClient {
                 }
                 // 兼容旧浏览器，不使用 AbortSignal.timeout（Chrome 103+ 才支持）
                 const fallbackController = new AbortController();
-                const fallbackTimeoutId = setTimeout(() => fallbackController.abort(), 5000);
+                const fallbackTimeoutId = setTimeout(() => fallbackController.abort(), timeoutMs);
                 try {
                     const fallbackResp = await fetch(buildCertUrl(peerGatewayUrl, aid), { signal: fallbackController.signal });
                     if (!fallbackResp.ok) {
@@ -2485,6 +3225,10 @@ export class AUNClient {
         }
     }
     _resolveGateway(params) {
+        const gateways = this._resolveGateways(params);
+        return gateways[0];
+    }
+    _resolveGateways(params) {
         const topology = isJsonObject(params.topology) ? params.topology : null;
         if (topology) {
             const mode = String(topology.mode ?? 'gateway');
@@ -2495,10 +3239,16 @@ export class AUNClient {
                 throw new ValidationError('relay topology is not implemented in the Browser SDK');
             }
         }
-        const gateway = String(params.gateway ?? this._gatewayUrl ?? '');
+        const gw = params.gateway ?? params.gateways;
+        if (Array.isArray(gw)) {
+            const urls = gw.map((g) => String(g ?? '')).filter((u) => u.length > 0);
+            if (urls.length > 0)
+                return urls;
+        }
+        const gateway = String(gw ?? this._gatewayUrl ?? '');
         if (!gateway)
             throw new StateError('missing gateway in connect params');
-        return gateway;
+        return [gateway];
     }
     async _syncIdentityAfterConnect(accessToken) {
         let identity = null;
@@ -2787,6 +3537,16 @@ export class AUNClient {
         };
         scheduleRefresh(0);
     }
+    _normalizeOutboundMessagePayload(params, method = '') {
+        if (!Object.prototype.hasOwnProperty.call(params, 'payload') && Object.prototype.hasOwnProperty.call(params, 'content')) {
+            params.payload = params.content;
+            delete params.content;
+        }
+        const payload = params.payload;
+        if (isJsonObject(payload) && !Object.prototype.hasOwnProperty.call(payload, 'type') && typeof payload.text === 'string') {
+            params.payload = { type: 'text', ...payload };
+        }
+    }
     _validateMessageRecipient(toAid) {
         if (isGroupServiceAid(toAid)) {
             throw new ValidationError('message.send receiver cannot be group.{issuer}; use group.send instead');
@@ -3210,6 +3970,8 @@ export class AUNClient {
         this._gapFillDone.clear();
         this._pushedSeqs.clear();
         this._pendingOrderedMsgs.clear();
+        this._v2SenderIKPending.clear();
+        this._v2SenderIKFetching.clear();
         this._groupSynced.clear();
     }
     _refreshSeqTrackerContext() {
@@ -3220,6 +3982,8 @@ export class AUNClient {
         this._gapFillDone.clear();
         this._pushedSeqs.clear();
         this._pendingOrderedMsgs.clear();
+        this._v2SenderIKPending.clear();
+        this._v2SenderIKFetching.clear();
         this._groupSynced.clear();
         this._seqTrackerContext = nextContext;
     }
@@ -3273,13 +4037,54 @@ export class AUNClient {
             }).catch(() => { });
         }
     }
-    // ── V2 E2EE API（async，与 Python `client.py` `_init_v2_session` / `send_v2` / `pull_v2` / `ack_v2` 对齐） ──
-    /**
-     * 初始化 V2 session：从 AID PEM 私钥提取 raw scalar + DER 公钥，
-     * 打开 V2 KeyStore（IndexedDB），构造 V2Session 并注册当前设备 SPK。
-     *
-     * connect 成功后自动调用，可幂等手动调用。
-     */
+    _persistRepairedSeq(ns) {
+        if (!this._aid || !ns)
+            return;
+        const seq = this._seqTracker.getContiguousSeq(ns);
+        try {
+            if (seq > 0 && typeof this._keystore.saveSeq === 'function') {
+                this._keystore.saveSeq(this._aid, this._deviceId, this._slotId, ns, seq).catch((exc) => {
+                    this._clientLog.debug(`persist repaired seq failed: ns=${ns} err=${formatCaughtError(exc)}`);
+                });
+                return;
+            }
+            const deleteSeq = this._keystore.deleteSeq;
+            if (seq <= 0 && typeof deleteSeq === 'function') {
+                deleteSeq.call(this._keystore, this._aid, this._deviceId, this._slotId, ns).catch((exc) => {
+                    this._clientLog.debug(`delete repaired seq failed: ns=${ns} err=${formatCaughtError(exc)}`);
+                });
+                return;
+            }
+            if (seq > 0) {
+                this._saveSeqTrackerState();
+            }
+        }
+        catch (exc) {
+            this._clientLog.debug(`persist repaired seq failed: ns=${ns} err=${formatCaughtError(exc)}`);
+        }
+    }
+    _repairPushContiguousBound(ns, pushSeq, hasPayload, label) {
+        if (!ns || !Number.isFinite(pushSeq) || pushSeq <= 0) {
+            return ns ? this._seqTracker.getContiguousSeq(ns) : 0;
+        }
+        const contig = this._seqTracker.getContiguousSeq(ns);
+        const shouldRepair = contig > pushSeq;
+        if (!shouldRepair)
+            return contig;
+        const repairedTo = Math.max(0, pushSeq - 1);
+        this._seqTracker.repairContiguousSeq(ns, repairedTo);
+        const repaired = this._seqTracker.getContiguousSeq(ns);
+        this._persistRepairedSeq(ns);
+        this._clientLog.warn(`${label} push repaired contiguous_seq: ns=${ns} payload=${hasPayload} push_seq=${pushSeq} contiguous=${contig}->${repaired}`);
+        return repaired;
+    }
+    // ── V2 E2EE API（async，与 Python `client.py` `_init_v2_session` / `send_v2` / `pull_v2` / `ack_v2` 对齐） ──
+    /**
+     * 初始化 V2 session：从 AID PEM 私钥提取 raw scalar + DER 公钥，
+     * 打开 V2 KeyStore（IndexedDB），构造 V2Session 并注册当前设备 SPK。
+     *
+     * connect 成功后自动调用，可幂等手动调用。
+     */
     async initV2Session() {
         if (!this._aid)
             return;
@@ -3323,6 +4128,104 @@ export class AUNClient {
         // 上线时自动确认 pending state proposals
         this._safeAsync(this._v2AutoConfirmPendingProposals());
     }
+    async _v2TrustedIKPubDer(aid) {
+        const normalizedAid = String(aid ?? '').trim();
+        if (!normalizedAid)
+            throw new E2EEError('spk_aid_missing');
+        if (this._aid && normalizedAid === this._aid) {
+            if (!this._v2Session)
+                throw new E2EEError('V2 session not initialized');
+            return this._v2Session.currentIkPubDer;
+        }
+        const certPem = await this._fetchPeerCert(normalizedAid);
+        const pubKey = await importCertPublicKeyEcdsa(certPem);
+        return new Uint8Array(await crypto.subtle.exportKey('spki', pubKey));
+    }
+    _v2SPKTimestampText(value, aid, deviceId, spkId) {
+        if (value === null || value === undefined || value === '') {
+            throw new E2EEError(`spk_timestamp_missing: aid=${aid} device_id=${deviceId} spk_id=${spkId}`);
+        }
+        if (typeof value === 'boolean') {
+            throw new E2EEError(`spk_timestamp_invalid: aid=${aid} device_id=${deviceId} spk_id=${spkId}`);
+        }
+        if (typeof value === 'number') {
+            if (!Number.isSafeInteger(value)) {
+                throw new E2EEError(`spk_timestamp_invalid: aid=${aid} device_id=${deviceId} spk_id=${spkId}`);
+            }
+            return String(value);
+        }
+        const text = String(value).trim();
+        if (!/^\d+$/.test(text)) {
+            throw new E2EEError(`spk_timestamp_invalid: aid=${aid} device_id=${deviceId} spk_id=${spkId}`);
+        }
+        return BigInt(text).toString();
+    }
+    async _v2VerifySPKDevice(args) {
+        if (!this._v2Session)
+            throw new E2EEError('V2 session not initialized');
+        const spkId = String(args.dev.spk_id ?? '').trim();
+        if (!spkId)
+            return;
+        if (args.keySource !== 'peer_device_prekey' && args.keySource !== 'group_device_prekey') {
+            throw new E2EEError(`spk_key_source_invalid: aid=${args.aid} device_id=${args.deviceId} spk_id=${spkId} key_source=${args.keySource}`);
+        }
+        if (!args.spkPkDer || args.spkPkDer.length === 0) {
+            throw new E2EEError(`spk_public_key_missing: aid=${args.aid} device_id=${args.deviceId} spk_id=${spkId}`);
+        }
+        const spkHash = bytesToHex(new Uint8Array(await crypto.subtle.digest('SHA-256', args.spkPkDer.slice().buffer)));
+        const expectedSpkId = `sha256:${spkHash.substring(0, 16)}`;
+        if (spkId !== expectedSpkId) {
+            throw new E2EEError(`spk_id_mismatch: aid=${args.aid} device_id=${args.deviceId} spk_id=${spkId} expected=${expectedSpkId}`);
+        }
+        const trustedIK = await this._v2TrustedIKPubDer(args.aid);
+        if (!_v2BytesEqual(trustedIK, args.ikPkDer)) {
+            throw new E2EEError(`spk_ik_mismatch: aid=${args.aid} device_id=${args.deviceId} spk_id=${spkId}`);
+        }
+        if (_v2BytesEqual(args.spkPkDer, trustedIK)) {
+            this._v2Session.markPeerSPKVerified(args.aid, args.deviceId, spkId);
+            return;
+        }
+        const sigB64 = String(args.dev.spk_signature ?? '').trim();
+        if (!sigB64) {
+            throw new E2EEError(`spk_signature_missing: aid=${args.aid} device_id=${args.deviceId} spk_id=${spkId}`);
+        }
+        let signature;
+        try {
+            signature = _v2B64ToBytesStrict(sigB64);
+        }
+        catch {
+            throw new E2EEError(`spk_signature_invalid_base64: aid=${args.aid} device_id=${args.deviceId} spk_id=${spkId}`);
+        }
+        const encoder = new TextEncoder();
+        const tsText = this._v2SPKTimestampText(args.dev.spk_timestamp, args.aid, args.deviceId, spkId);
+        const signData = _v2ConcatBytes(args.spkPkDer, encoder.encode(spkId), encoder.encode(tsText));
+        if (!(await ecdsaVerifyRaw(trustedIK, signature, signData))) {
+            throw new E2EEError(`spk_signature_invalid: aid=${args.aid} device_id=${args.deviceId} spk_id=${spkId}`);
+        }
+        this._v2Session.markPeerSPKVerified(args.aid, args.deviceId, spkId);
+    }
+    async _v2BuildTargetFromDevice(args) {
+        const aid = String(args.aid ?? '').trim();
+        const devId = getV2DeviceId(args.dev);
+        const deviceId = devId.present ? devId.value : String(args.deviceId ?? '').trim();
+        const ikPk = String(args.dev.ik_pk ?? '').trim();
+        if (!aid || !devId.present || !ikPk)
+            return null;
+        const ikPkDer = _v2B64ToBytes(ikPk);
+        const spkPkDer = args.dev.spk_pk ? _v2B64ToBytes(String(args.dev.spk_pk)) : undefined;
+        const keySource = String(args.dev.key_source ?? args.defaultKeySource).trim() || args.defaultKeySource;
+        await this._v2VerifySPKDevice({ dev: args.dev, aid, deviceId, ikPkDer, spkPkDer, keySource });
+        this._v2Session?.cachePeerIK(aid, deviceId, ikPkDer);
+        return {
+            aid,
+            deviceId,
+            role: args.role,
+            keySource,
+            ikPkDer,
+            spkPkDer,
+            spkId: String(args.dev.spk_id ?? '').trim(),
+        };
+    }
     async _getV2SenderPubDer(fromAid, senderDeviceId) {
         const session = this._v2Session;
         if (!session || !fromAid)
@@ -3331,37 +4234,134 @@ export class AUNClient {
         if (senderPubDer)
             return senderPubDer;
         try {
-            const bs = await this.call('message.v2.bootstrap', { peer_aid: fromAid });
-            const peers = (Array.isArray(bs?.peer_devices) ? bs.peer_devices : []);
-            for (const dev of peers) {
-                const devId = String(dev.device_id ?? dev.owner_device_id ?? '');
-                const ikPk = String(dev.ik_pk ?? '');
-                if (!devId || !ikPk)
-                    continue;
-                session.cachePeerIK(fromAid, devId, _v2B64ToBytes(ikPk));
-            }
-            senderPubDer = session.getPeerIK(fromAid, senderDeviceId);
-            if (senderPubDer)
-                return senderPubDer;
-        }
-        catch (exc) {
-            this._clientLog.warn(`V2 decrypt: bootstrap for sender ${fromAid} failed: ${String(formatCaughtError(exc))}`);
-        }
-        try {
-            const certPem = await this._fetchPeerCert(fromAid);
+            const certPem = await this._fetchPeerCert(fromAid, undefined, 3000);
             const pubKey = await importCertPublicKeyEcdsa(certPem);
             senderPubDer = new Uint8Array(await crypto.subtle.exportKey('spki', pubKey));
-            if (senderDeviceId) {
-                session.cachePeerIK(fromAid, senderDeviceId, senderPubDer);
-            }
-            this._clientLog.debug(`V2 decrypt: sender IK fallback from CA cert for ${fromAid}`);
+            session.cachePeerIK(fromAid, senderDeviceId, senderPubDer);
+            this._clientLog.debug(`V2 decrypt: sender IK fallback from PKI cert for ${fromAid}`);
             return senderPubDer;
         }
         catch (exc) {
-            this._clientLog.warn(`V2 decrypt: CA fallback for ${fromAid} failed: ${String(formatCaughtError(exc))}`);
+            this._clientLog.warn(`V2 decrypt: PKI cert sender IK fallback failed for ${fromAid}: ${String(formatCaughtError(exc))}`);
             return null;
         }
     }
+    _v2PendingSenderIKMessageKey(msg, groupId) {
+        const messageId = String(msg.message_id ?? '').trim();
+        const seq = String(msg.seq ?? '').trim();
+        const prefix = groupId ? `group:${groupId}` : `p2p:${this._aid ?? ''}`;
+        return `${prefix}:${messageId || seq || Math.random().toString(36).slice(2)}`;
+    }
+    _v2PendingSenderIKFetchKey(fromAid, senderDeviceId, groupId) {
+        return `${fromAid}#${senderDeviceId}#${groupId || ''}`;
+    }
+    _cacheV2PeerIKFromDevice(dev, fallbackAid = '') {
+        const session = this._v2Session;
+        if (!session || !isJsonObject(dev))
+            return;
+        const device = dev;
+        const devId = getV2DeviceId(device);
+        const aid = String(device.aid ?? fallbackAid ?? '').trim();
+        const ikPk = String(device.ik_pk ?? '').trim();
+        if (!devId.present || !aid || !ikPk)
+            return;
+        try {
+            session.cachePeerIK(aid, devId.value, _v2B64ToBytes(ikPk));
+        }
+        catch (exc) {
+            this._clientLog.debug(`V2 sender IK cache from bootstrap skipped aid=${aid} dev=${devId.value}: ${String(formatCaughtError(exc))}`);
+        }
+    }
+    _scheduleV2SenderIKPending(args) {
+        const fromAid = String(args.fromAid ?? '').trim();
+        if (!fromAid)
+            return;
+        const senderDeviceId = String(args.senderDeviceId ?? '');
+        const groupId = String(args.groupId ?? '').trim();
+        const messageKey = this._v2PendingSenderIKMessageKey(args.msg, groupId);
+        this._v2SenderIKPending.set(messageKey, {
+            msg: { ...args.msg },
+            fromAid,
+            senderDeviceId,
+            groupId,
+            createdAt: Date.now(),
+        });
+        this._clientLog.debug(`V2 decrypt pending sender IK: key=${messageKey} from=${fromAid} device=${senderDeviceId || '-'} group=${groupId || '<p2p>'} pending=${this._v2SenderIKPending.size}`);
+        this._scheduleV2SenderIKFetch(fromAid, senderDeviceId, groupId);
+    }
+    _scheduleV2SenderIKFetch(fromAid, senderDeviceId, groupId) {
+        const fetchKey = this._v2PendingSenderIKFetchKey(fromAid, senderDeviceId, groupId);
+        if (!fromAid || this._v2SenderIKFetching.has(fetchKey))
+            return;
+        this._v2SenderIKFetching.add(fetchKey);
+        this._safeAsync(this._resolveV2SenderIKPending(fromAid, senderDeviceId, groupId, fetchKey));
+    }
+    async _resolveV2SenderIKPending(fromAid, senderDeviceId, groupId, fetchKey) {
+        try {
+            const session = this._v2Session;
+            if (session && fromAid) {
+                try {
+                    const bs = await this.call('message.v2.bootstrap', {
+                        peer_aid: fromAid,
+                        e2ee_wrap_capabilities: v2WrapCapabilities(),
+                    });
+                    const peers = (Array.isArray(bs?.peer_devices) ? bs.peer_devices : []);
+                    for (const dev of peers)
+                        this._cacheV2PeerIKFromDevice(dev, fromAid);
+                }
+                catch (exc) {
+                    this._clientLog.warn(`V2 sender IK pending bootstrap failed peer=${fromAid}: ${String(formatCaughtError(exc))}`);
+                }
+                if (groupId) {
+                    try {
+                        const gbs = await this.call('group.v2.bootstrap', {
+                            group_id: groupId,
+                            e2ee_wrap_capabilities: v2WrapCapabilities(),
+                        });
+                        const devices = (Array.isArray(gbs?.devices) ? gbs.devices : []);
+                        const audit = (Array.isArray(gbs?.audit_recipients) ? gbs.audit_recipients : []);
+                        for (const dev of devices)
+                            this._cacheV2PeerIKFromDevice(dev);
+                        for (const dev of audit)
+                            this._cacheV2PeerIKFromDevice(dev);
+                    }
+                    catch (exc) {
+                        this._clientLog.warn(`V2 sender IK pending group bootstrap failed group=${groupId}: ${String(formatCaughtError(exc))}`);
+                    }
+                }
+                if (!session.getPeerIK(fromAid, senderDeviceId)) {
+                    await this._getV2SenderPubDer(fromAid, senderDeviceId);
+                }
+            }
+            const pendingItems = [...this._v2SenderIKPending.entries()].filter(([, entry]) => entry.fromAid === fromAid && entry.senderDeviceId === senderDeviceId && entry.groupId === groupId);
+            for (const [key, entry] of pendingItems) {
+                let plaintext = null;
+                try {
+                    plaintext = await this._decryptV2Message(entry.msg, false);
+                }
+                catch (exc) {
+                    this._clientLog.warn(`V2 sender IK pending retry raised: key=${key} err=${String(formatCaughtError(exc))}`);
+                }
+                this._v2SenderIKPending.delete(key);
+                if (plaintext === null) {
+                    this._clientLog.debug(`V2 sender IK pending retry failed: key=${key}`);
+                    continue;
+                }
+                const seq = Number(entry.msg.seq ?? 0);
+                if (entry.groupId) {
+                    plaintext.group_id = entry.groupId;
+                    await this._publishPulledMessage('group.message_created', `group:${entry.groupId}`, seq, plaintext);
+                }
+                else {
+                    await this._publishPulledMessage('message.received', `p2p:${this._aid ?? ''}`, seq, plaintext);
+                }
+                this._clientLog.debug(`V2 sender IK pending retry delivered: key=${key}`);
+            }
+        }
+        finally {
+            this._v2SenderIKFetching.delete(fetchKey);
+        }
+    }
     /**
      * V2 P2P 加密发送（推测性：用缓存 bootstrap 直接发，失败刷新重试一次）。
      *
@@ -3374,108 +4374,21 @@ export class AUNClient {
         if (!this._v2Session) {
             throw new StateError('V2 session not initialized (not connected?)');
         }
-        const session = this._v2Session;
         const toAid = String(to ?? '').trim();
         if (!toAid)
             throw new ValidationError("message.send requires 'to'");
         if (!isJsonObject(payload))
             throw new ValidationError('message.send payload must be a dict for V2 encryption');
         const attempt = async (useCache) => {
-            let peerDevices = [];
-            let auditRaw = [];
-            const cached = useCache ? this._v2BootstrapCache.get(toAid) : undefined;
-            if (cached && (Date.now() - cached.cachedAt) < AUNClient.V2_BOOTSTRAP_TTL_MS) {
-                peerDevices = cached.devices;
-                auditRaw = cached.auditRecipients;
-            }
-            else {
-                const bs = await this.call('message.v2.bootstrap', { peer_aid: toAid });
-                peerDevices = (Array.isArray(bs?.peer_devices) ? bs.peer_devices : []);
-                auditRaw = (Array.isArray(bs?.audit_recipients) ? bs.audit_recipients : []);
-                if (peerDevices.length > 0) {
-                    this._v2BootstrapCache.set(toAid, {
-                        devices: peerDevices,
-                        auditRecipients: auditRaw,
-                        cachedAt: Date.now(),
-                    });
-                }
-            }
-            if (peerDevices.length === 0) {
-                throw new E2EEError(`V2 bootstrap: no devices found for ${toAid}`);
-            }
-            const targets = [];
-            for (const dev of peerDevices) {
-                const ikDer = _v2B64ToBytes(String(dev.ik_pk ?? ''));
-                const spkDer = dev.spk_pk ? _v2B64ToBytes(String(dev.spk_pk)) : undefined;
-                session.cachePeerIK(toAid, String(dev.device_id ?? ''), ikDer);
-                targets.push({
-                    aid: toAid,
-                    deviceId: String(dev.device_id ?? ''),
-                    role: 'peer',
-                    keySource: String(dev.key_source ?? 'peer_device_prekey'),
-                    ikPkDer: ikDer,
-                    spkPkDer: spkDer,
-                    spkId: String(dev.spk_id ?? ''),
-                });
-            }
-            const auditTargets = [];
-            for (const dev of auditRaw) {
-                if (!dev.ik_pk)
-                    continue;
-                const ikDer = _v2B64ToBytes(String(dev.ik_pk));
-                const spkDer = dev.spk_pk ? _v2B64ToBytes(String(dev.spk_pk)) : undefined;
-                auditTargets.push({
-                    aid: String(dev.aid ?? ''),
-                    deviceId: String(dev.device_id ?? ''),
-                    role: 'audit',
-                    keySource: String(dev.key_source ?? 'peer_device_prekey'),
-                    ikPkDer: ikDer,
-                    spkPkDer: spkDer,
-                    spkId: String(dev.spk_id ?? ''),
-                });
-            }
-            // self-sync：当前 AID 的其它设备
-            if (this._aid && this._aid !== toAid) {
-                try {
-                    const selfCached = this._v2BootstrapCache.get(this._aid);
-                    let selfDevices = [];
-                    if (selfCached && (Date.now() - selfCached.cachedAt) < AUNClient.V2_BOOTSTRAP_TTL_MS) {
-                        selfDevices = selfCached.devices;
-                    }
-                    else {
-                        const selfBs = await this.call('message.v2.bootstrap', { peer_aid: this._aid });
-                        selfDevices = (Array.isArray(selfBs?.peer_devices) ? selfBs.peer_devices : []);
-                        if (selfDevices.length > 0) {
-                            this._v2BootstrapCache.set(this._aid, {
-                                devices: selfDevices,
-                                auditRecipients: [],
-                                cachedAt: Date.now(),
-                            });
-                        }
-                    }
-                    for (const dev of selfDevices) {
-                        const devId = String(dev.owner_device_id ?? dev.device_id ?? '');
-                        if (devId === this._deviceId)
-                            continue;
-                        const ikDer = _v2B64ToBytes(String(dev.ik_pk ?? ''));
-                        const spkDer = dev.spk_pk ? _v2B64ToBytes(String(dev.spk_pk)) : undefined;
-                        targets.push({
-                            aid: this._aid,
-                            deviceId: devId,
-                            role: 'self_sync',
-                            keySource: String(dev.key_source ?? 'peer_device_prekey'),
-                            ikPkDer: ikDer,
-                            spkPkDer: spkDer,
-                            spkId: String(dev.spk_id ?? ''),
-                        });
-                    }
-                }
-                catch (exc) {
-                    this._clientLog.debug(`V2 self-sync bootstrap failed (non-fatal): ${String(exc)}`);
-                }
-            }
-            const sender = await session.getSenderIdentity();
-            const envelope = await encryptP2PMessage(sender, { targets, auditRecipients: auditTargets }, payload, opts ?? {});
+            const envelope = await this._buildV2P2PEnvelope({
+                to: toAid,
+                payload,
+                messageId: opts?.messageId,
+                timestamp: opts?.timestamp,
+                protectedHeaders: opts?.protectedHeaders,
+                context: opts?.context,
+                useCache,
+            });
             return this.call('message.send', {
                 to: toAid,
                 payload: envelope,
@@ -3506,91 +4419,106 @@ export class AUNClient {
             throw new StateError('V2 session not initialized (not connected?)');
         }
         const ns = this._aid ? `p2p:${this._aid}` : '';
-        const effective = afterSeq || (ns ? this._seqTracker.getContiguousSeq(ns) : 0);
-        const result = await this.call('message.v2.pull', {
-            after_seq: effective,
-            limit,
-        });
-        const messages = (Array.isArray(result?.messages) ? result.messages : []);
         const decrypted = [];
-        const seqs = messages
-            .map((msg) => Number(msg.seq ?? 0))
-            .filter((seq) => Number.isFinite(seq) && seq > 0);
-        const contigBefore = ns ? this._seqTracker.getContiguousSeq(ns) : 0;
-        if (ns && seqs.length > 0 && seqs[0] > contigBefore) {
-            this._seqTracker.forceContiguousSeq(ns, seqs[0]);
-        }
-        for (const msg of messages) {
-            const seq = Number(msg.seq ?? 0);
-            if (!Number.isFinite(seq) || seq <= 0)
-                continue;
-            const version = String(msg.version ?? 'v2');
-            if (version === 'v1') {
-                const legacy = isJsonObject(msg.legacy_v1) ? msg.legacy_v1 : {};
-                const legacyPayload = legacy.payload;
-                const payloadType = isJsonObject(legacyPayload)
-                    ? String(legacyPayload.type ?? '').trim()
-                    : '';
-                if (legacyPayload !== undefined && legacyPayload !== null
-                    && payloadType !== 'e2ee.encrypted' && payloadType !== 'e2ee.group_encrypted') {
-                    const v1Msg = {
-                        message_id: String(msg.message_id ?? ''),
-                        from: String(msg.from_aid ?? ''),
-                        to: String(legacy.to ?? this._aid ?? ''),
-                        seq: msg.seq,
-                        type: String(msg.type ?? ''),
-                        timestamp: msg.t_server,
-                        payload: legacyPayload,
-                        encrypted: false,
-                    };
-                    if (ns)
-                        await this._publishPulledMessage('message.received', ns, seq, v1Msg);
-                    else
-                        await this._publishAppEvent('message.received', v1Msg);
-                    decrypted.push(v1Msg);
+        let nextAfterSeq = afterSeq || (ns ? this._seqTracker.getContiguousSeq(ns) : 0);
+        let pageCount = 0;
+        const maxPages = 100;
+        while (pageCount < maxPages) {
+            pageCount += 1;
+            const result = await this.call('message.v2.pull', {
+                after_seq: nextAfterSeq,
+                limit,
+            });
+            const messages = (Array.isArray(result?.messages) ? result.messages : []);
+            const seqs = messages
+                .map((msg) => Number(msg.seq ?? 0))
+                .filter((seq) => Number.isFinite(seq) && seq > 0);
+            const pageContigBefore = ns ? this._seqTracker.getContiguousSeq(ns) : 0;
+            const pageMaxSeq = seqs.length > 0 ? Math.max(...seqs) : nextAfterSeq;
+            if (ns && seqs.length > 0) {
+                this._seqTracker.forceContiguousSeq(ns, pageMaxSeq);
+            }
+            for (const msg of messages) {
+                const seq = Number(msg.seq ?? 0);
+                if (!Number.isFinite(seq) || seq <= 0)
+                    continue;
+                const version = String(msg.version ?? 'v2');
+                if (version === 'v1') {
+                    const legacy = isJsonObject(msg.legacy_v1) ? msg.legacy_v1 : {};
+                    const legacyPayload = legacy.payload;
+                    const payloadType = isJsonObject(legacyPayload)
+                        ? String(legacyPayload.type ?? '').trim()
+                        : '';
+                    if (legacyPayload !== undefined && legacyPayload !== null
+                        && payloadType !== 'e2ee.encrypted' && payloadType !== 'e2ee.group_encrypted') {
+                        const v1Msg = {
+                            message_id: String(msg.message_id ?? ''),
+                            from: String(msg.from_aid ?? ''),
+                            to: String(legacy.to ?? this._aid ?? ''),
+                            seq: msg.seq,
+                            type: String(msg.type ?? ''),
+                            timestamp: msg.t_server,
+                            payload: legacyPayload,
+                            encrypted: false,
+                        };
+                        if (ns)
+                            await this._publishPulledMessage('message.received', ns, seq, v1Msg);
+                        else
+                            await this._publishAppEvent('message.received', v1Msg);
+                        decrypted.push(v1Msg);
+                    }
+                    else {
+                        this._clientLog.debug(`message.v2.pull skipping V1 envelope seq=${seq} payload_type=${payloadType || '<none>'} (V1 E2EE removed)`);
+                    }
+                    continue;
+                }
+                if (version !== 'v2') {
+                    this._clientLog.debug(`message.v2.pull skipping non-V2 row seq=${seq} version=${String(msg.version ?? '')}`);
+                    continue;
+                }
+                // 跟踪每个旧 SPK 引用的最大 seq（用于消费后销毁）
+                const msgSpkId = String(msg.spk_id ?? '');
+                if (msgSpkId && this._v2Session && !this._v2Session.isCurrentSPK(msgSpkId)) {
+                    this._v2Session.trackOldSPKMaxSeq(msgSpkId, seq);
+                }
+                const plaintext = await this._decryptV2Message(msg);
+                if (plaintext === null)
+                    continue;
+                if (ns) {
+                    await this._publishPulledMessage('message.received', ns, seq, plaintext);
+                    decrypted.push(plaintext);
                 }
                 else {
-                    this._clientLog.debug(`message.v2.pull skipping V1 envelope seq=${seq} payload_type=${payloadType || '<none>'} (V1 E2EE removed)`);
+                    await this._publishAppEvent('message.received', plaintext);
+                    decrypted.push(plaintext);
                 }
-                continue;
             }
-            if (version !== 'v2') {
-                this._clientLog.debug(`message.v2.pull skipping non-V2 row seq=${seq} version=${String(msg.version ?? '')}`);
-                continue;
-            }
-            // 跟踪每个旧 SPK 引用的最大 seq（用于消费后销毁）
-            const msgSpkId = String(msg.spk_id ?? '');
-            if (msgSpkId && this._v2Session && !this._v2Session.isCurrentSPK(msgSpkId)) {
-                this._v2Session.trackOldSPKMaxSeq(msgSpkId, seq);
+            const serverAckSeq = Number(result.server_ack_seq ?? 0);
+            if (ns && Number.isFinite(serverAckSeq) && serverAckSeq > 0) {
+                const contig = this._seqTracker.getContiguousSeq(ns);
+                if (contig < serverAckSeq) {
+                    this._clientLog.info(`message.v2.pull retention-floor advance: ns=${ns} contiguous=${contig} -> server_ack_seq=${serverAckSeq}`);
+                    this._seqTracker.forceContiguousSeq(ns, serverAckSeq);
+                }
             }
-            // 解密
-            const plaintext = await this._decryptV2Message(msg);
-            if (plaintext === null)
-                continue;
-            // 有序 publish + 去重（与 V1 push 路径对齐）
             if (ns) {
-                await this._publishPulledMessage('message.received', ns, seq, plaintext);
-                decrypted.push(plaintext);
-            }
-            else {
-                await this._publishAppEvent('message.received', plaintext);
-                decrypted.push(plaintext);
-            }
-        }
-        if (ns && seqs.length > 0) {
-            const maxSeq = Math.max(...seqs);
-            const contig = this._seqTracker.getContiguousSeq(ns);
-            if (maxSeq > contig) {
-                this._seqTracker.forceContiguousSeq(ns, maxSeq);
-                await this._drainOrderedMessages(ns);
-            }
-            const ackSeq = this._seqTracker.getContiguousSeq(ns);
-            if (ackSeq !== contigBefore) {
-                this._saveSeqTrackerState();
-                if (ackSeq > 0) {
+                const ackSeq = this._seqTracker.getContiguousSeq(ns);
+                const contigAdvanced = ackSeq !== pageContigBefore;
+                if (contigAdvanced) {
+                    await this._drainOrderedMessages(ns);
+                    this._saveSeqTrackerState();
+                }
+                if (messages.length > 0 && contigAdvanced && ackSeq > 0) {
                     this._safeAsync(this.ackV2(ackSeq).then(() => undefined));
                 }
             }
+            const nextAfter = Math.max(pageMaxSeq, nextAfterSeq);
+            if (messages.length === 0 || nextAfter <= nextAfterSeq || result.has_more === false)
+                break;
+            nextAfterSeq = nextAfter;
+        }
+        if (pageCount >= maxPages) {
+            this._clientLog.warn(`message.v2.pull reached max_pages=${maxPages} after_seq=${nextAfterSeq}`);
         }
         return decrypted;
     }
@@ -3601,9 +4529,17 @@ export class AUNClient {
      */
     async ackV2(upToSeq) {
         const ns = this._aid ? `p2p:${this._aid}` : '';
-        const seq = upToSeq ?? (ns ? this._seqTracker.getContiguousSeq(ns) : 0);
+        let seq = upToSeq ?? (ns ? this._seqTracker.getContiguousSeq(ns) : 0);
         if (seq <= 0)
             return { acked: 0 };
+        // ack clamp：永远不发送超过 maxSeenSeq 的 up_to_seq
+        if (ns) {
+            const maxSeen = this._seqTracker.getMaxSeenSeq(ns);
+            if (maxSeen > 0 && seq > maxSeen) {
+                this._clientLog.warn(`ackV2 clamp: up_to_seq=${seq} > max_seen=${maxSeen}, clamp`);
+                seq = maxSeen;
+            }
+        }
         const raw = await this.call('message.v2.ack', { up_to_seq: seq });
         const result = isJsonObject(raw)
             ? { ...raw }
@@ -3634,8 +4570,8 @@ export class AUNClient {
         }
         return result;
     }
-    /** 解密单条 V2 消息（与 Python `_decrypt_v2_message` 对齐） */
-    async _decryptV2Message(msg) {
+    /** 解密单条 V2 消息（与 Python `_decrypt_v2_message` 对齐）。缺 sender IK 时先入 pending，后台补齐后重试。 */
+    async _decryptV2Message(msg, allowPending = true) {
         const session = this._v2Session;
         if (!session)
             return null;
@@ -3650,6 +4586,8 @@ export class AUNClient {
             this._clientLog.warn(`V2 decrypt: invalid envelope_json for msg seq=${String(msg.seq)}`);
             return null;
         }
+        const e2eeMeta = v2E2eeMeta(envelope);
+        await this._observeAgentMdFromEnvelope(envelope);
         // 确定 spk_id 和 recipient_key_source
         let spkId = '';
         let recipientKeySource = '';
@@ -3663,7 +4601,7 @@ export class AUNClient {
             // 从 recipients 数组中查找本设备的 row 以获取 key_source
             if (!spkId) {
                 for (const row of envelope.recipients) {
-                    if (Array.isArray(row) && row.length >= 6 && row[0] === this._aid && row[1] === this._deviceId) {
+                    if (Array.isArray(row) && row.length >= 6 && row[0] === this._aid && (row[1] === this._deviceId || row[1] === '')) {
                         spkId = String(row[5] ?? '');
                         recipientKeySource = row.length > 3 ? String(row[3] ?? '') : '';
                         break;
@@ -3672,40 +4610,80 @@ export class AUNClient {
             }
             else {
                 for (const row of envelope.recipients) {
-                    if (Array.isArray(row) && row.length >= 6 && row[0] === this._aid && row[1] === this._deviceId) {
+                    if (Array.isArray(row) && row.length >= 6 && row[0] === this._aid && (row[1] === this._deviceId || row[1] === '')) {
                         recipientKeySource = row.length > 3 ? String(row[3] ?? '') : '';
                         break;
                     }
                 }
             }
         }
-        // 根据 aad.group_id 判断使用 group SPK 还是 P2P SPK
+        // group_id 只表示群上下文；getGroupDecryptKeys 内部必须按 group SPK -> P2P device SPK -> IK fallback 查找。
         const aad = isJsonObject(envelope.aad) ? envelope.aad : {};
         const groupIdForKeys = String(msg.group_id ?? aad.group_id ?? envelope.group_id ?? '').trim();
+        const undecryptableEvent = groupIdForKeys ? 'group.message_undecryptable' : 'message.undecryptable';
         let ikPriv;
         let spkPriv;
-        if (groupIdForKeys) {
-            const keys = await session.getGroupDecryptKeys(groupIdForKeys, spkId);
-            ikPriv = keys.ikPriv;
-            spkPriv = keys.spkPriv;
+        try {
+            if (groupIdForKeys) {
+                const keys = await session.getGroupDecryptKeys(groupIdForKeys, spkId);
+                ikPriv = keys.ikPriv;
+                spkPriv = keys.spkPriv;
+            }
+            else {
+                const keys = await session.getDecryptKeys(spkId);
+                ikPriv = keys.ikPriv;
+                spkPriv = keys.spkPriv;
+            }
         }
-        else {
-            const keys = await session.getDecryptKeys(spkId);
-            ikPriv = keys.ikPriv;
-            spkPriv = keys.spkPriv;
+        catch (exc) {
+            this._clientLog.warn(`V2 decrypt: SPK lookup failed seq=${String(msg.seq)} spk_id=${spkId}: ${String(exc)}`);
+            try {
+                const event = {
+                    message_id: String(msg.message_id ?? ''),
+                    from: String(msg.from_aid ?? ''),
+                    to: String(msg.to ?? ''),
+                    seq: msg.seq,
+                    timestamp: (msg.t_server ?? msg.timestamp),
+                    device_id: String(msg.device_id ?? ''),
+                    slot_id: String(msg.slot_id ?? ''),
+                    _decrypt_error: String(exc),
+                    _decrypt_stage: 'spk_lookup',
+                    _envelope_type: String(envelope.type ?? ''),
+                    _suite: String(envelope.suite ?? ''),
+                    _spk_id: spkId,
+                };
+                attachV2EnvelopeMetadata(event, e2eeMeta);
+                await this._dispatcher.publish(undecryptableEvent, event);
+            }
+            catch { /* publish 异常不影响主流程 */ }
+            return null;
         }
         const fromAid = String(msg.from_aid ?? '');
         const senderDeviceId = String(aad.from_device ?? '');
         const senderPubDer = await this._getV2SenderPubDer(fromAid, senderDeviceId);
         if (!senderPubDer) {
-            this._clientLog.warn(`V2 decrypt: no sender IK for ${fromAid}, cannot verify signature`);
+            this._clientLog.warn(`V2 decrypt: no sender IK for ${fromAid} device=${senderDeviceId}`);
+            if (allowPending) {
+                this._scheduleV2SenderIKPending({ msg, fromAid, senderDeviceId, groupId: groupIdForKeys });
+                return null;
+            }
             try {
-                await this._dispatcher.publish('message.undecryptable', {
+                const event = {
                     message_id: String(msg.message_id ?? ''),
                     from: fromAid,
+                    to: String(msg.to ?? ''),
                     seq: msg.seq,
+                    timestamp: (msg.t_server ?? msg.timestamp),
+                    device_id: String(msg.device_id ?? ''),
+                    slot_id: String(msg.slot_id ?? ''),
                     _decrypt_error: 'sender_ik_not_found',
-                });
+                    _decrypt_stage: 'sender_ik',
+                    _envelope_type: String(envelope.type ?? ''),
+                    _suite: String(envelope.suite ?? ''),
+                    _sender_device_id: String(aad.from_device ?? ''),
+                };
+                attachV2EnvelopeMetadata(event, e2eeMeta);
+                await this._dispatcher.publish(undecryptableEvent, event);
             }
             catch { /* publish 异常不影响主流程 */ }
             return null;
@@ -3717,12 +4695,22 @@ export class AUNClient {
         catch (exc) {
             this._clientLog.warn(`V2 decrypt failed for msg seq=${String(msg.seq)}: ${String(exc)}`);
             try {
-                await this._dispatcher.publish('message.undecryptable', {
+                const event = {
                     message_id: String(msg.message_id ?? ''),
                     from: fromAid,
+                    to: String(msg.to ?? ''),
                     seq: msg.seq,
+                    timestamp: (msg.t_server ?? msg.timestamp),
+                    device_id: String(msg.device_id ?? ''),
+                    slot_id: String(msg.slot_id ?? ''),
                     _decrypt_error: String(exc),
-                });
+                    _decrypt_stage: 'decrypt',
+                    _envelope_type: String(envelope.type ?? ''),
+                    _suite: String(envelope.suite ?? ''),
+                    _sender_device_id: String(aad.from_device ?? ''),
+                };
+                attachV2EnvelopeMetadata(event, e2eeMeta);
+                await this._dispatcher.publish(undecryptableEvent, event);
             }
             catch { /* publish 异常不影响主流程 */ }
             return null;
@@ -3748,7 +4736,8 @@ export class AUNClient {
                 this._clientLog.debug(`V2 SPK rotation failed (non-fatal): ${exc}`);
             });
         }
-        return {
+        const e2ee = v2E2eeMeta(envelope);
+        const result = {
             message_id: String(msg.message_id ?? ''),
             from: fromAid,
             to: this._aid ?? '',
@@ -3756,8 +4745,10 @@ export class AUNClient {
             t_server: msg.t_server,
             payload: plaintext,
             encrypted: true,
-            e2ee: v2E2eeMeta(envelope),
+            e2ee: e2ee,
         };
+        attachV2EnvelopeMetadata(result, e2ee);
+        return result;
     }
     /**
      * V2 Group 加密发送（推测性：用缓存 bootstrap 直接发，失败刷新重试一次）。
@@ -3843,32 +4834,53 @@ export class AUNClient {
         if (!gid)
             throw new ValidationError('group.pull requires group_id');
         const ns = `group:${gid}`;
-        const effective = afterSeq || this._seqTracker.getContiguousSeq(ns);
-        const result = await this.call('group.v2.pull', {
-            group_id: gid,
-            after_seq: effective,
-            limit,
-        });
-        const messages = (Array.isArray(result?.messages) ? result.messages : []);
         const decrypted = [];
-        const seqs = messages
-            .map((msg) => Number(msg.seq ?? 0))
-            .filter((seq) => Number.isFinite(seq) && seq > 0);
-        const contigBefore = this._seqTracker.getContiguousSeq(ns);
-        if (seqs.length > 0 && seqs[0] > contigBefore) {
-            this._seqTracker.forceContiguousSeq(ns, seqs[0]);
-        }
-        for (const msg of messages) {
-            const seq = Number(msg.seq ?? 0);
-            if (!Number.isFinite(seq) || seq <= 0)
-                continue;
-            const version = String(msg.version ?? 'v2');
-            if (version === 'v1') {
-                const payload = msg.payload;
-                const payloadObj = isJsonObject(payload) ? payload : null;
-                if (payloadObj) {
-                    const payloadType = String(payloadObj.type ?? '').trim();
-                    if (payloadType !== 'e2ee.encrypted' && payloadType !== 'e2ee.group_encrypted') {
+        let nextAfterSeq = afterSeq || this._seqTracker.getContiguousSeq(ns);
+        let pageCount = 0;
+        const maxPages = 100;
+        while (pageCount < maxPages) {
+            pageCount += 1;
+            const result = await this.call('group.v2.pull', {
+                group_id: gid,
+                after_seq: nextAfterSeq,
+                limit,
+            });
+            const messages = (Array.isArray(result?.messages) ? result.messages : []);
+            const seqs = messages
+                .map((msg) => Number(msg.seq ?? 0))
+                .filter((seq) => Number.isFinite(seq) && seq > 0);
+            const pageContigBefore = this._seqTracker.getContiguousSeq(ns);
+            const pageMaxSeq = seqs.length > 0 ? Math.max(...seqs) : nextAfterSeq;
+            if (seqs.length > 0) {
+                this._seqTracker.forceContiguousSeq(ns, pageMaxSeq);
+            }
+            for (const msg of messages) {
+                const seq = Number(msg.seq ?? 0);
+                if (!Number.isFinite(seq) || seq <= 0)
+                    continue;
+                const version = String(msg.version ?? 'v2');
+                if (version === 'v1') {
+                    const payload = msg.payload;
+                    const payloadObj = isJsonObject(payload) ? payload : null;
+                    if (payloadObj) {
+                        const payloadType = String(payloadObj.type ?? '').trim();
+                        if (payloadType !== 'e2ee.encrypted' && payloadType !== 'e2ee.group_encrypted') {
+                            const v1Msg = {
+                                message_id: String(msg.message_id ?? ''),
+                                from: String(msg.from_aid ?? ''),
+                                group_id: gid,
+                                seq: msg.seq,
+                                type: String(msg.type ?? ''),
+                                timestamp: msg.t_server,
+                                payload,
+                                encrypted: false,
+                            };
+                            await this._publishPulledMessage('group.message_created', ns, seq, v1Msg);
+                            decrypted.push(v1Msg);
+                            continue;
+                        }
+                    }
+                    else if (payload !== undefined && payload !== null) {
                         const v1Msg = {
                             message_id: String(msg.message_id ?? ''),
                             from: String(msg.from_aid ?? ''),
@@ -3883,51 +4895,45 @@ export class AUNClient {
                         decrypted.push(v1Msg);
                         continue;
                     }
+                    this._clientLog.debug(`group.v2.pull skipping V1 envelope group=${gid} seq=${seq} payload_type=${payloadObj ? String(payloadObj.type ?? '') : '<none>'} (V1 E2EE removed)`);
+                    continue;
                 }
-                else if (payload !== undefined && payload !== null) {
-                    const v1Msg = {
-                        message_id: String(msg.message_id ?? ''),
-                        from: String(msg.from_aid ?? ''),
-                        group_id: gid,
-                        seq: msg.seq,
-                        type: String(msg.type ?? ''),
-                        timestamp: msg.t_server,
-                        payload,
-                        encrypted: false,
-                    };
-                    await this._publishPulledMessage('group.message_created', ns, seq, v1Msg);
-                    decrypted.push(v1Msg);
+                if (version !== 'v2') {
+                    this._clientLog.debug(`group.v2.pull skipping non-V2 row group=${gid} seq=${seq} version=${String(msg.version ?? '')}`);
                     continue;
                 }
-                this._clientLog.debug(`group.v2.pull skipping V1 envelope group=${gid} seq=${seq} payload_type=${payloadObj ? String(payloadObj.type ?? '') : '<none>'} (V1 E2EE removed)`);
-                continue;
-            }
-            if (version !== 'v2') {
-                this._clientLog.debug(`group.v2.pull skipping non-V2 row group=${gid} seq=${seq} version=${String(msg.version ?? '')}`);
-                continue;
+                const plaintext = await this._decryptV2Message(msg);
+                if (plaintext === null)
+                    continue;
+                plaintext.group_id = gid;
+                await this._publishPulledMessage('group.message_created', ns, seq, plaintext);
+                decrypted.push(plaintext);
             }
-            const plaintext = await this._decryptV2Message(msg);
-            if (plaintext === null)
-                continue;
-            plaintext.group_id = gid;
-            // 有序 publish + 去重（与 V1 group push 路径对齐）
-            await this._publishPulledMessage('group.message_created', ns, seq, plaintext);
-            decrypted.push(plaintext);
-        }
-        if (seqs.length > 0) {
-            const maxSeq = Math.max(...seqs);
-            const contig = this._seqTracker.getContiguousSeq(ns);
-            if (maxSeq > contig) {
-                this._seqTracker.forceContiguousSeq(ns, maxSeq);
-                await this._drainOrderedMessages(ns);
+            const cursor = isJsonObject(result.cursor) ? result.cursor : null;
+            const serverAckSeq = Number(cursor?.current_seq ?? 0);
+            if (Number.isFinite(serverAckSeq) && serverAckSeq > 0) {
+                const contig = this._seqTracker.getContiguousSeq(ns);
+                if (contig < serverAckSeq) {
+                    this._clientLog.info(`group.v2.pull retention-floor advance: ns=${ns} contiguous=${contig} -> cursor.current_seq=${serverAckSeq}`);
+                    this._seqTracker.forceContiguousSeq(ns, serverAckSeq);
+                }
             }
             const ackSeq = this._seqTracker.getContiguousSeq(ns);
-            if (ackSeq !== contigBefore) {
+            const contigAdvanced = ackSeq !== pageContigBefore;
+            if (contigAdvanced) {
+                await this._drainOrderedMessages(ns);
                 this._saveSeqTrackerState();
-                if (ackSeq > 0) {
-                    this._safeAsync(this.ackGroupV2(gid, ackSeq).then(() => undefined));
-                }
             }
+            if (messages.length > 0 && contigAdvanced && ackSeq > 0) {
+                this._safeAsync(this.ackGroupV2(gid, ackSeq).then(() => undefined));
+            }
+            const nextAfter = Math.max(pageMaxSeq, nextAfterSeq);
+            if (messages.length === 0 || nextAfter <= nextAfterSeq || result.has_more === false)
+                break;
+            nextAfterSeq = nextAfter;
+        }
+        if (pageCount >= maxPages) {
+            this._clientLog.warn(`group.v2.pull reached max_pages=${maxPages} group=${gid} after_seq=${nextAfterSeq}`);
         }
         return decrypted;
     }
@@ -3942,9 +4948,15 @@ export class AUNClient {
         if (!gid)
             throw new ValidationError('group.ack_messages requires group_id');
         const ns = `group:${gid}`;
-        const seq = upToSeq ?? this._seqTracker.getContiguousSeq(ns);
+        let seq = upToSeq ?? this._seqTracker.getContiguousSeq(ns);
         if (seq <= 0)
             return { acked: 0 };
+        // ack clamp：永远不发送超过 maxSeenSeq 的 up_to_seq
+        const maxSeen = this._seqTracker.getMaxSeenSeq(ns);
+        if (maxSeen > 0 && seq > maxSeen) {
+            this._clientLog.warn(`ackGroupV2 clamp: group=${gid} up_to_seq=${seq} > max_seen=${maxSeen}, clamp`);
+            seq = maxSeen;
+        }
         return this.call('group.v2.ack', { group_id: gid, up_to_seq: seq });
     }
     // ── V2 thought（per-device wrap，服务端透传，不持久化）──────────
@@ -3962,20 +4974,27 @@ export class AUNClient {
         const useCache = opts.useCache !== false;
         let peerDevices = [];
         let auditRaw = [];
+        let wrapPolicy;
         const cached = useCache ? this._v2BootstrapCache.get(to) : undefined;
         if (cached && (Date.now() - cached.cachedAt) < AUNClient.V2_BOOTSTRAP_TTL_MS) {
             peerDevices = cached.devices;
             auditRaw = cached.auditRecipients;
+            wrapPolicy = cached.wrapPolicy;
         }
         else {
-            const bs = await this.call('message.v2.bootstrap', { peer_aid: to });
+            const bs = await this.call('message.v2.bootstrap', {
+                peer_aid: to,
+                e2ee_wrap_capabilities: v2WrapCapabilities(),
+            });
             peerDevices = (Array.isArray(bs?.peer_devices) ? bs.peer_devices : []);
             auditRaw = (Array.isArray(bs?.audit_recipients) ? bs.audit_recipients : []);
+            wrapPolicy = normalizeV2WrapPolicy(bs?.e2ee_wrap_policy);
             if (peerDevices.length > 0) {
                 this._v2BootstrapCache.set(to, {
                     devices: peerDevices,
                     auditRecipients: auditRaw,
                     cachedAt: Date.now(),
+                    wrapPolicy,
                 });
             }
         }
@@ -3984,33 +5003,27 @@ export class AUNClient {
         }
         const targets = [];
         for (const dev of peerDevices) {
-            const ikDer = _v2B64ToBytes(String(dev.ik_pk ?? ''));
-            const spkDer = dev.spk_pk ? _v2B64ToBytes(String(dev.spk_pk)) : undefined;
-            session.cachePeerIK(to, String(dev.device_id ?? ''), ikDer);
-            targets.push({
+            const devId = getV2DeviceId(dev);
+            const target = await this._v2BuildTargetFromDevice({
+                dev,
                 aid: to,
-                deviceId: String(dev.device_id ?? ''),
+                deviceId: devId.value,
                 role: 'peer',
-                keySource: String(dev.key_source ?? 'peer_device_prekey'),
-                ikPkDer: ikDer,
-                spkPkDer: spkDer,
-                spkId: String(dev.spk_id ?? ''),
+                defaultKeySource: 'peer_device_prekey',
             });
+            if (target)
+                targets.push(target);
         }
         for (const dev of auditRaw) {
-            if (!dev.ik_pk)
-                continue;
-            const ikDer = _v2B64ToBytes(String(dev.ik_pk));
-            const spkDer = dev.spk_pk ? _v2B64ToBytes(String(dev.spk_pk)) : undefined;
-            targets.push({
+            const target = await this._v2BuildTargetFromDevice({
+                dev,
                 aid: String(dev.aid ?? ''),
                 deviceId: String(dev.device_id ?? ''),
                 role: 'audit',
-                keySource: String(dev.key_source ?? 'peer_device_prekey'),
-                ikPkDer: ikDer,
-                spkPkDer: spkDer,
-                spkId: String(dev.spk_id ?? ''),
+                defaultKeySource: 'peer_device_prekey',
             });
+            if (target)
+                targets.push(target);
         }
         // self-sync：自己其它设备
         if (this._aid && this._aid !== to) {
@@ -4021,7 +5034,10 @@ export class AUNClient {
                     selfDevices = selfCached.devices;
                 }
                 else {
-                    const selfBs = await this.call('message.v2.bootstrap', { peer_aid: this._aid });
+                    const selfBs = await this.call('message.v2.bootstrap', {
+                        peer_aid: this._aid,
+                        e2ee_wrap_capabilities: v2WrapCapabilities(),
+                    });
                     selfDevices = (Array.isArray(selfBs?.peer_devices) ? selfBs.peer_devices : []);
                     if (selfDevices.length > 0) {
                         this._v2BootstrapCache.set(this._aid, {
@@ -4032,20 +5048,18 @@ export class AUNClient {
                     }
                 }
                 for (const dev of selfDevices) {
-                    const devId = String(dev.owner_device_id ?? dev.device_id ?? '');
-                    if (devId === this._deviceId)
+                    const devId = getV2DeviceId(dev);
+                    if (!devId.present || devId.value === this._deviceId)
                         continue;
-                    const ikDer = _v2B64ToBytes(String(dev.ik_pk ?? ''));
-                    const spkDer = dev.spk_pk ? _v2B64ToBytes(String(dev.spk_pk)) : undefined;
-                    targets.push({
+                    const target = await this._v2BuildTargetFromDevice({
+                        dev,
                         aid: this._aid,
-                        deviceId: devId,
+                        deviceId: devId.value,
                         role: 'self_sync',
-                        keySource: String(dev.key_source ?? 'peer_device_prekey'),
-                        ikPkDer: ikDer,
-                        spkPkDer: spkDer,
-                        spkId: String(dev.spk_id ?? ''),
+                        defaultKeySource: 'peer_device_prekey',
                     });
+                    if (target)
+                        targets.push(target);
                 }
             }
             catch (exc) {
@@ -4053,7 +5067,8 @@ export class AUNClient {
             }
         }
         const sender = await session.getSenderIdentity();
-        const envelope = await encryptP2PMessage(sender, { targets, auditRecipients: [] }, opts.payload, { messageId: opts.messageId, timestamp: opts.timestamp, protectedHeaders: opts.protectedHeaders, context: opts.context });
+        const sendTargets = applyV2WrapPolicyToTargets(targets, wrapPolicy);
+        const envelope = await encryptP2PMessage(sender, { targets: sendTargets, auditRecipients: [] }, opts.payload, { messageId: opts.messageId, timestamp: opts.timestamp, protectedHeaders: opts.protectedHeaders, context: opts.context });
         return envelope;
     }
     /**
@@ -4127,18 +5142,27 @@ export class AUNClient {
         let epoch = 0;
         let stateCommitment = { state_version: 0, state_hash: '', state_chain: '' };
         let auditRecipientsRaw = [];
+        let wrapPolicy;
         const cached = useCache ? this._v2BootstrapCache.get(cacheKey) : undefined;
         if (cached && (Date.now() - cached.cachedAt) < AUNClient.V2_BOOTSTRAP_TTL_MS) {
             allDevices = cached.devices;
             epoch = cached.epoch ?? 0;
             stateCommitment = cached.stateCommitment ?? { state_version: 0, state_hash: '', state_chain: '' };
             auditRecipientsRaw = cached.auditRecipients;
+            wrapPolicy = cached.wrapPolicy;
         }
         else {
-            const bs = await this.call('group.v2.bootstrap', { group_id: groupId });
+            const bs = await this.call('group.v2.bootstrap', {
+                group_id: groupId,
+                e2ee_wrap_capabilities: v2WrapCapabilities(),
+            });
             allDevices = (Array.isArray(bs?.devices) ? bs.devices : []);
             epoch = Number(bs?.epoch ?? 0);
             auditRecipientsRaw = (Array.isArray(bs?.audit_recipients) ? bs.audit_recipients : []);
+            wrapPolicy = normalizeV2WrapPolicy(bs?.e2ee_wrap_policy);
+            await this._v2CheckFork(groupId, String(bs?.state_chain ?? ''));
+            await this._v2VerifyStateSignature(groupId, bs);
+            await this._publishV2GroupSecurityLevel(groupId, bs);
             stateCommitment = {
                 state_version: Number(bs?.state_version ?? 0) || 0,
                 state_hash: String(bs?.state_hash_signed ?? bs?.state_hash ?? ''),
@@ -4151,11 +5175,9 @@ export class AUNClient {
                     cachedAt: Date.now(),
                     epoch,
                     stateCommitment: stateCommitment,
+                    wrapPolicy,
                 });
             }
-            await this._v2CheckFork(groupId, String(bs?.state_chain ?? ''));
-            await this._v2VerifyStateSignature(groupId, bs);
-            await this._publishV2GroupSecurityLevel(groupId, bs);
             // lazy sync 触发：发现 pending members 时异步发起提案
             const pendingAdds = Array.isArray(bs?.pending_adds) ? bs.pending_adds : [];
             if (pendingAdds.length > 0 && this._v2Session) {
@@ -4168,42 +5190,37 @@ export class AUNClient {
         const targets = [];
         for (const dev of allDevices) {
             const devAid = String(dev.aid ?? '');
-            const devId = String(dev.device_id ?? '');
-            if (devAid === this._aid && devId === this._deviceId)
+            const devId = getV2DeviceId(dev);
+            if (devAid === this._aid && devId.present && devId.value === this._deviceId)
                 continue;
-            const ikDer = _v2B64ToBytes(String(dev.ik_pk ?? ''));
-            const spkDer = dev.spk_pk ? _v2B64ToBytes(String(dev.spk_pk)) : undefined;
             const role = devAid === this._aid ? 'self_sync' : 'member';
-            targets.push({
+            const target = await this._v2BuildTargetFromDevice({
+                dev,
                 aid: devAid,
-                deviceId: devId,
+                deviceId: devId.value,
                 role,
-                keySource: String(dev.key_source ?? 'peer_device_prekey'),
-                ikPkDer: ikDer,
-                spkPkDer: spkDer,
-                spkId: String(dev.spk_id ?? ''),
+                defaultKeySource: 'peer_device_prekey',
             });
+            if (target)
+                targets.push(target);
         }
         for (const dev of auditRecipientsRaw) {
-            if (!dev.ik_pk)
-                continue;
-            const ikDer = _v2B64ToBytes(String(dev.ik_pk));
-            const spkDer = dev.spk_pk ? _v2B64ToBytes(String(dev.spk_pk)) : undefined;
-            targets.push({
+            const target = await this._v2BuildTargetFromDevice({
+                dev,
                 aid: String(dev.aid ?? ''),
                 deviceId: String(dev.device_id ?? ''),
                 role: 'audit',
-                keySource: String(dev.key_source ?? 'peer_device_prekey'),
-                ikPkDer: ikDer,
-                spkPkDer: spkDer,
-                spkId: String(dev.spk_id ?? ''),
+                defaultKeySource: 'peer_device_prekey',
             });
+            if (target)
+                targets.push(target);
         }
         if (targets.length === 0) {
             throw new E2EEError(`V2 group: no target devices for ${groupId}`);
         }
         const sender = await session.getSenderIdentity();
-        const envelope = await encryptGroupMessage(sender, groupId, epoch, targets, opts.payload, { messageId: opts.messageId, timestamp: opts.timestamp, protectedHeaders: opts.protectedHeaders, context: opts.context }, stateCommitment);
+        const sendTargets = applyV2WrapPolicyToTargets(targets, wrapPolicy);
+        const envelope = await encryptGroupMessage(sender, groupId, epoch, sendTargets, opts.payload, { messageId: opts.messageId, timestamp: opts.timestamp, protectedHeaders: opts.protectedHeaders, context: opts.context }, stateCommitment);
         return envelope;
     }
     async _publishV2GroupSecurityLevel(groupId, bootstrap) {
@@ -4286,7 +5303,7 @@ export class AUNClient {
         if (Array.isArray(recipients)) {
             for (const row of recipients) {
                 if (Array.isArray(row) && row.length >= 6) {
-                    if (row[0] === this._aid && row[1] === this._deviceId) {
+                    if (row[0] === this._aid && (row[1] === this._deviceId || row[1] === '')) {
                         spkId = String(row[5] ?? '');
                         recipientKeySource = row.length > 3 ? String(row[3] ?? '') : '';
                         break;
@@ -4294,26 +5311,33 @@ export class AUNClient {
                 }
             }
         }
-        // 根据 aad.group_id 判断使用 group SPK 还是 P2P SPK
         const aad = opts.envelope.aad ?? {};
         const groupIdForKeys = String(aad.group_id ?? opts.envelope.group_id ?? '').trim();
         let ikPriv;
         let spkPriv;
-        if (groupIdForKeys) {
-            const keys = await session.getGroupDecryptKeys(groupIdForKeys, spkId);
-            ikPriv = keys.ikPriv;
-            spkPriv = keys.spkPriv;
+        // group_id 只表示群上下文；group lookup 内部按 group SPK -> P2P device SPK -> IK fallback。
+        try {
+            if (groupIdForKeys) {
+                const keys = await session.getGroupDecryptKeys(groupIdForKeys, spkId);
+                ikPriv = keys.ikPriv;
+                spkPriv = keys.spkPriv;
+            }
+            else {
+                const keys = await session.getDecryptKeys(spkId);
+                ikPriv = keys.ikPriv;
+                spkPriv = keys.spkPriv;
+            }
         }
-        else {
-            const keys = await session.getDecryptKeys(spkId);
-            ikPriv = keys.ikPriv;
-            spkPriv = keys.spkPriv;
+        catch (exc) {
+            this._clientLog.warn(`V2 thought decrypt: SPK lookup failed from=${opts.fromAid}, group=${groupIdForKeys || '<p2p>'}, spk_id=${spkId || '<empty>'}: ${exc}`);
+            return null;
         }
         const fromAid = String(opts.fromAid || aad.from || '').trim();
         const senderDeviceId = String(aad.from_device ?? '');
         const senderPubDer = await this._getV2SenderPubDer(fromAid, senderDeviceId);
         if (!senderPubDer) {
             this._clientLog.warn(`V2 thought decrypt: no sender IK for ${fromAid} device=${senderDeviceId}`);
+            this._scheduleV2SenderIKFetch(fromAid, senderDeviceId, groupIdForKeys);
             return null;
         }
         try {
@@ -4367,11 +5391,8 @@ export class AUNClient {
             const signPayloadBytes = new TextEncoder().encode(signPayload);
             const sigBytes = base64ToUint8(stateSignature);
             // 验签缓存检查
-            const cacheInput = new TextEncoder().encode(actorAid + '\x00' + signPayload + '\x00');
-            const cacheData = new Uint8Array(cacheInput.length + sigBytes.length);
-            cacheData.set(cacheInput, 0);
-            cacheData.set(sigBytes, cacheInput.length);
-            const cacheHashBuf = await crypto.subtle.digest('SHA-256', cacheData.buffer);
+            const cacheData = _v2LengthPrefixedBytes(new TextEncoder().encode(actorAid), signPayloadBytes, sigBytes);
+            const cacheHashBuf = await crypto.subtle.digest('SHA-256', cacheData.slice().buffer);
             const cacheHashArr = new Uint8Array(cacheHashBuf);
             let cacheKey = '';
             for (let i = 0; i < cacheHashArr.length; i++)
@@ -4594,13 +5615,17 @@ export class AUNClient {
             }
             if (myRole !== 'owner' && myRole !== 'admin')
                 return false;
-            const bootstrapResp = await this.call('group.v2.bootstrap', { group_id: groupId });
+            const bootstrapResp = await this.call('group.v2.bootstrap', {
+                group_id: groupId,
+                e2ee_wrap_capabilities: v2WrapCapabilities(),
+            });
             const devices = (Array.isArray(bootstrapResp?.devices) ? bootstrapResp.devices : []);
             const candidates = [];
             for (const dev of devices) {
                 const aid = String(dev.aid ?? '').trim();
+                const hasDeviceId = 'device_id' in dev;
                 const deviceId = String(dev.device_id ?? '').trim();
-                if (aid && deviceId && onlineAdminAids.has(aid)) {
+                if (aid && hasDeviceId && onlineAdminAids.has(aid)) {
                     candidates.push(`${aid}\x1f${deviceId}`);
                 }
             }
@@ -4616,7 +5641,7 @@ export class AUNClient {
                 this._clientLog.debug(`V2 auto propose leader elected: group=${groupId} leader=${leader}`);
                 return true;
             }
-            const delayMs = await this._v2LeaderDelayMs(`${groupId}\x00${myKey}`);
+            const delayMs = await this._v2LeaderDelayMs(_v2LengthPrefixedTextKey(groupId, myKey));
             this._clientLog.debug(`V2 auto propose non-leader delay: group=${groupId} leader=${leader} self=${myKey} delay_ms=${delayMs}`);
             await this._sleep(delayMs);
             return true;
@@ -4695,7 +5720,10 @@ export class AUNClient {
                 }
             }
             // 获取群所有成员的设备列表（V2 bootstrap）
-            const bootstrapResp = await this.call('group.v2.bootstrap', { group_id: groupId });
+            const bootstrapResp = await this.call('group.v2.bootstrap', {
+                group_id: groupId,
+                e2ee_wrap_capabilities: v2WrapCapabilities(),
+            });
             const allDevices = (Array.isArray(bootstrapResp?.devices) ? bootstrapResp.devices : []);
             const auditRecipients = (Array.isArray(bootstrapResp?.audit_recipients) ? bootstrapResp.audit_recipients : []);
             const auditAidsList = [...new Set(auditRecipients.map(r => String(r.aid ?? '').trim()).filter(Boolean))].sort();
@@ -4929,30 +5957,42 @@ export class AUNClient {
         const pushFrom = isJsonObject(data) ? String(data.from_aid ?? '') : '';
         const pushMsgId = isJsonObject(data) ? String(data.message_id ?? '') : '';
         const envelopeJson = isJsonObject(data) ? data.envelope_json : undefined;
+        const hasPayload = !!envelopeJson;
         const ns = this._aid ? `p2p:${this._aid}` : '';
         let contigBefore = ns ? this._seqTracker.getContiguousSeq(ns) : 0;
-        this._clientLog.debug(`_onV2PushNotification: push_seq=${pushSeq || 'null'} push_from=${pushFrom} push_msg_id=${pushMsgId} has_payload=${!!envelopeJson} contiguous_seq=${contigBefore}`);
+        this._clientLog.debug(`_onV2PushNotification: push_seq=${pushSeq || 'null'} push_from=${pushFrom} push_msg_id=${pushMsgId} has_payload=${hasPayload} contiguous_seq=${contigBefore}`);
+        // ── Push 修上界：只更新 maxSeenSeq，不动 contiguousSeq ──
+        if (pushSeq > 0 && ns) {
+            this._seqTracker.updateMaxSeen(ns, pushSeq);
+            if (contigBefore === pushSeq) {
+                this._clientLog.debug(`_onV2PushNotification: push seq=${pushSeq} already covered by contiguous_seq=${contigBefore}, ignore duplicate push`);
+                return;
+            }
+            contigBefore = this._repairPushContiguousBound(ns, pushSeq, hasPayload, '_raw.peer.v2.message_received');
+        }
         // ── 带 payload 的 push：尝试就地解密 ──
-        if (envelopeJson && pushSeq > 0 && ns) {
+        if (hasPayload && pushSeq > 0 && ns) {
             try {
                 const decrypted = await this._decryptV2Message(data);
                 if (decrypted) {
-                    // 解密成功：contiguous_seq 上界 = push_seq
-                    this._seqTracker.onMessageSeq(ns, pushSeq);
-                    if (pushSeq === contigBefore + 1) {
-                        this._seqTracker.forceContiguousSeq(ns, pushSeq);
-                    }
-                    await this._publishOrderedMessage('message.received', ns, pushSeq, decrypted);
+                    // 解密成功：把 pushSeq 加入 receivedSeqs，让 _tryAdvance 自然推进
+                    const needPull = this._seqTracker.onMessageSeq(ns, pushSeq);
+                    const published = await this._publishOrderedMessage('message.received', ns, pushSeq, decrypted);
                     const newContig = this._seqTracker.getContiguousSeq(ns);
                     if (newContig !== contigBefore) {
                         this._saveSeqTrackerState();
                     }
                     if (newContig > 0 && newContig !== contigBefore) {
-                        this._transport.call('message.v2.ack', { up_to_seq: newContig })
+                        const maxSeen = this._seqTracker.getMaxSeenSeq(ns);
+                        const ackSeq = maxSeen > 0 ? Math.min(newContig, maxSeen) : newContig;
+                        this.call('message.v2.ack', { up_to_seq: ackSeq })
                             .catch(e => this._clientLog.debug(`V2 P2P push-ack failed: ${e}`));
                     }
                     this._clientLog.debug(`_onV2PushNotification: push 带 payload 解密成功, contiguous_seq=${contigBefore}->${newContig} push_seq=${pushSeq}`);
-                    return;
+                    if (!needPull && (published || newContig >= pushSeq || pushSeq <= contigBefore)) {
+                        return;
+                    }
+                    this._clientLog.debug(`_onV2PushNotification: payload push seq=${pushSeq} 因空洞挂起，继续 pull 补齐 after_seq=${newContig}`);
                 }
             }
             catch (exc) {
@@ -4966,14 +6006,6 @@ export class AUNClient {
         // 正确做法：保持 contiguousSeq 不变，用它作为 pull 的 after_seq；
         // pull 成功 + 解密成功后再由 pull 路径推进 contiguousSeq。
         if (pushSeq > 0 && ns) {
-            // 越界修复：如果 contiguousSeq >= pushSeq（被之前的异常 push 污染，或恰好等于），
-            // 强制拉回到 pushSeq - 1，确保能拉到 pushSeq 这条消息
-            if (contigBefore >= pushSeq) {
-                this._clientLog.warn(`_onV2PushNotification: contiguous_seq=${contigBefore} 越界（>= push_seq=${pushSeq}），强制修复为 ${pushSeq - 1}`);
-                this._seqTracker.forceContiguousSeq(ns, pushSeq - 1);
-                this._saveSeqTrackerState(); // 持久化修复后的状态
-                contigBefore = pushSeq - 1;
-            }
             // 纯通知：不更新 contiguousSeq，由 pull 结果驱动推进
             this._clientLog.debug(`_onV2PushNotification: 纯通知 push_seq=${pushSeq} > contiguous_seq=${contigBefore}, 触发 pull(after_seq=${contigBefore})`);
         }
@@ -5035,6 +6067,66 @@ export class AUNClient {
             this._clientLog.warn(`background task exception:${String(exc)}`);
         });
     }
+    // ── Pull Gate（序列化同一 key 的并发 pull）──────────────────
+    _pullGateKeyForCall(method, params) {
+        if (method === 'message.pull' || method === 'message.v2.pull') {
+            return this._aid ? `p2p:${this._aid}` : '';
+        }
+        if (method === 'group.pull' || method === 'group.v2.pull') {
+            const gid = String(params.group_id ?? '').trim();
+            return gid ? `group:${gid}` : '';
+        }
+        if (method === 'group.pull_events') {
+            const gid = String(params.group_id ?? '').trim();
+            return gid ? `group_event:${gid}` : '';
+        }
+        return '';
+    }
+    _tryAcquirePullGate(key) {
+        if (!key)
+            return 0;
+        const now = Date.now();
+        const gate = this._pullGates.get(key) ?? { inflight: false, startedAt: 0, token: 0 };
+        if (gate.inflight && now - gate.startedAt <= AUNClient._PULL_GATE_STALE_MS) {
+            return null;
+        }
+        if (gate.inflight) {
+            this._clientLog.warn(`pull in-flight stale reset: key=${key} age=${now - gate.startedAt}ms`);
+        }
+        gate.token += 1;
+        gate.inflight = true;
+        gate.startedAt = now;
+        this._pullGates.set(key, gate);
+        return gate.token;
+    }
+    _releasePullGate(key, token) {
+        if (!key || token == null)
+            return;
+        const gate = this._pullGates.get(key);
+        if (!gate || gate.token !== token)
+            return;
+        gate.inflight = false;
+        gate.startedAt = 0;
+    }
+    async _runPullSerialized(key, operation) {
+        let token = this._tryAcquirePullGate(key);
+        if (token === null) {
+            const deadline = Date.now() + AUNClient._PULL_GATE_STALE_MS + 100;
+            while (token === null && Date.now() <= deadline) {
+                await this._sleep(25);
+                token = this._tryAcquirePullGate(key);
+            }
+            if (token === null) {
+                throw new StateError(`pull already in-flight for ${key}`);
+            }
+        }
+        try {
+            return await operation();
+        }
+        finally {
+            this._releasePullGate(key, token);
+        }
+    }
     /** 可取消的 sleep */
     _sleep(ms) {
         return new Promise((resolve) => {