@agentunion/fastaun 0.3.2 → 0.3.4

package/dist/client.js

@@ -14,10 +14,12 @@ import * as crypto from 'node:crypto';
 import * as fs from 'node:fs';
 import * as http from 'node:http';
 import * as https from 'node:https';
+import * as path from 'node:path';
 import { URL } from 'node:url';
 import { configFromMap, getDeviceId, normalizeInstanceId } from './config.js';
 import { CryptoProvider } from './crypto.js';
 import { GatewayDiscovery } from './discovery.js';
+import { DnsResilientNet } from './net.js';
 import { AUNError, AuthError, ConnectionError, E2EEError, PermissionError, StateError, TimeoutError, ValidationError, } from './errors.js';
 import { EventDispatcher } from './events.js';
 import { FileKeyStore } from './keystore/file.js';
@@ -31,8 +33,12 @@ import { AuthFlow } from './auth.js';
 import { SeqTracker } from './seq-tracker.js';
 import { V2Session } 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 { isJsonObject, } from './types.js';
+function isPromiseLike(value) {
+    return Boolean(value && typeof value.then === 'function');
+}
 /**
  * 递归排序键的 JSON 序列化（Canonical JSON for AUN）
  * 等价于 Python json.dumps(sort_keys=True, separators=(",",":"), ensure_ascii=False)
@@ -58,6 +64,15 @@ export 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 computeStateHash(params) {
     const sortedMembers = [...params.members].sort((a, b) => a.aid.localeCompare(b.aid));
     const membershipBlock = sortedMembers.map(m => `${m.aid}:${m.role}`).join('|');
@@ -156,7 +171,16 @@ function reconnectSleepDelayMs(baseDelay, maxBaseDelay) {
 }
 /** 需要客户端签名的关键方法 */
 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',
@@ -176,6 +200,59 @@ const SIGNED_METHODS = new Set([
 ]);
 /** peer 证书缓存 TTL（1 小时） */
 const PEER_CERT_CACHE_TTL = 3600;
+function normalizeV2WrapPolicy(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        return { explicit: false, version: '', protocol: '', scope: 'device' };
+    }
+    const obj = raw;
+    let protocol = String(obj.protocol ?? '').trim().toUpperCase();
+    if (protocol !== '1DH' && protocol !== '3DH')
+        protocol = '';
+    let scope = String(obj.scope ?? '').trim().toLowerCase();
+    if (scope !== 'aid' && scope !== 'device') {
+        scope = obj.per_aid_wrap === true ? 'aid' : 'device';
+    }
+    if (scope === 'aid')
+        protocol = '1DH';
+    return {
+        explicit: true,
+        version: String(obj.version ?? ''),
+        protocol,
+        scope: scope,
+    };
+}
+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.explicit)
+        return targets;
+    const out = [];
+    const seen = new Set();
+    for (const target of targets) {
+        const row = { ...target };
+        if (policy.protocol === '1DH') {
+            row.keySource = 'aid_master';
+            row.spkPkDer = undefined;
+            row.spkId = '';
+        }
+        if (policy.scope === 'aid') {
+            const key = `${row.aid}\x1f${row.role}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            row.deviceId = '';
+        }
+        out.push(row);
+    }
+    return out;
+}
 function _v2LeftPad32(b) {
     if (b.length === 32)
         return b;
@@ -189,6 +266,21 @@ function _v2B64ToBytes(s) {
     const buf = Buffer.from(String(s ?? '').trim(), 'base64');
     return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
 }
+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 _v2B64uToBytes(s) {
     const std = String(s ?? '').replace(/-/g, '+').replace(/_/g, '/');
     const pad = std.length % 4 === 0 ? '' : '='.repeat(4 - (std.length % 4));
@@ -245,11 +337,11 @@ function normalizeDeliveryModeConfig(raw, opts = {}) {
 }
 // ── HTTP 辅助 ─────────────────────────────────────────────────
 /** 发起 HTTP GET 请求，返回文本内容 */
-function _httpGetText(url, verifySsl) {
+function _httpGetText(url, verifySsl, timeoutMs = 30_000) {
     return new Promise((resolve, reject) => {
         const parsed = new URL(url);
         const mod = parsed.protocol === 'https:' ? https : http;
-        const options = { timeout: 30_000 };
+        const options = { timeout: timeoutMs };
         if (!verifySsl) {
             options.rejectUnauthorized = false;
         }
@@ -274,6 +366,17 @@ function _httpGetText(url, verifySsl) {
 /**
  * AUN Core SDK 主客户端
  */
+function lengthPrefixedTextKey(...parts) {
+    return parts.map((part) => `${Buffer.byteLength(part, 'utf8')}:${part};`).join('');
+}
+function lengthPrefixedBytesKey(...parts) {
+    const chunks = [];
+    for (const part of parts) {
+        const bytes = Buffer.from(part.buffer, part.byteOffset, part.byteLength);
+        chunks.push(Buffer.from(`${bytes.length}:`, 'ascii'), bytes, Buffer.from(';', 'ascii'));
+    }
+    return Buffer.concat(chunks);
+}
 export class AUNClient {
     /** 原始配置 */
     config;
@@ -317,13 +420,14 @@ export class AUNClient {
     _defaultConnectDeliveryMode;
     /** peer 证书缓存 */
     _certCache = new Map();
-    // 本地 agent.md 文件路径与对应 etag（quoted sha256 hex，与服务端 _agent_md_etag 一致）。
-    // 由 setLocalAgentMdPath() 设置；用于跟服务端 RPC 注入的 _meta.agent_md_etag 比对，
-    // 触发"本地未发布到服务端"或"服务端版本更新"的 UI 提示。
+    // AIDs 目录：{agentMdPath}/{aid}/agentmd.json 保存元数据，{agentMdPath}/{aid}/agent.md 保存正文。
+    _agentMdPath = '';
     _localAgentMdPath = '';
     _localAgentMdEtag = '';
     // gateway 在 RPC envelope._meta.agent_md_etag 注入的服务端 etag；纯观察，无下游依赖。
     _remoteAgentMdEtag = '';
+    _agentMdCache = new Map();
+    _agentMdFetchInflight = new Map();
     /** 消息序列号跟踪器（群消息 + P2P 空洞检测） */
     _seqTracker = new SeqTracker();
     _seqTrackerContext = null;
@@ -331,10 +435,19 @@ export class AUNClient {
     _groupSynced = new Set();
     /** 补洞去重：已完成/进行中的 key -> 开始时间戳，防止重复 pull 同一区间 */
     _gapFillDone = new Map();
+    /** pull gate：按消费单元串行化 public pull / gap fill / push auto-pull。 */
+    _pullGates = new Map();
+    _pullResponseKeys = new Map();
+    /** 当前异步调用栈是否属于通知触发的后台 RPC。 */
+    _backgroundRpcDepth = 0;
     /** 已发布到应用层的 seq 集合（按命名空间），补洞路径 publish 前检查以避免重复分发 */
     _pushedSeqs = new Map();
     /** 已解密但因 seq 空洞暂缓发布的应用层消息（按 namespace -> seq） */
     _pendingOrderedMsgs = new Map();
+    /** 缺 sender IK 时暂存原始 V2 消息，后台补齐 IK 后重试解密。 */
+    _v2SenderIKPending = new Map();
+    /** sender IK 后台补齐任务去重。 */
+    _v2SenderIKFetching = new Set();
     // ── 后台任务定时器 ──────────────────────────────────────────
     _heartbeatTimer = null;
     _tokenRefreshTimer = null;
@@ -356,11 +469,10 @@ export class AUNClient {
     /** 最近一次已成功提交的 membership_snapshot；相同快照直接跳过。 */
     _v2AutoProposeLastSnapshot = new Map();
     _v2LazyProposeTriggered = new Map();
-    _v2PullInflight = false;
-    _v2PullPending = false;
     static V2_BOOTSTRAP_TTL_MS = 60 * 60 * 1000;
     static V2_RETRYABLE_CODES = new Set([-33011, -33012, -33050, -33052, -33054]);
-    static V2_SIG_CACHE_TTL_MS = 600_000;
+    static PULL_GATE_STALE_MS = 3000;
+    static V2_SIG_CACHE_TTL_MS = 60 * 60 * 1000;
     static V2_SIG_CACHE_MAX = 16_384;
     _reconnectActive = false;
     _reconnectAbort = null;
@@ -373,30 +485,49 @@ export class AUNClient {
         const rawConfig = { ...(config ?? {}) };
         this._configModel = configFromMap(rawConfig);
         const initAid = String(rawConfig.aid ?? '').trim() || null;
+        this._agentMdPath = path.join(this._configModel.aunPath, 'AIDs');
         this.config = {
             aun_path: this._configModel.aunPath,
             root_ca_path: this._configModel.rootCaPath,
             seed_password: this._configModel.seedPassword,
         };
+        this._deviceId = getDeviceId(this._configModel.aunPath);
         // 初始化 Logger（per-client 单例，必须最早创建）
         const debugFlag = this._configModel.debug || debug;
         this._logger = new AUNLogger({
             debug: debugFlag,
             aunPath: this._configModel.aunPath,
         });
+        this._logger.bindDeviceId(this._deviceId);
         this._clientLog = this._logger.for('aun_core.client');
         if (debugFlag) {
             this._clientLog.info(`AUNClient initialized (debug=true, aunPath=${this._configModel.aunPath})`);
         }
         this._dispatcher = new EventDispatcher(this._logger.for('aun_core.events'));
-        this._discovery = new GatewayDiscovery({ verifySsl: this._configModel.verifySsl });
+        const dnsNet = new DnsResilientNet({
+            verifySsl: this._configModel.verifySsl,
+            logger: this._clientLog,
+        });
+        this._discovery = new GatewayDiscovery({ verifySsl: this._configModel.verifySsl, logger: this._clientLog, net: dnsNet });
         const keystore = new FileKeyStore(this._configModel.aunPath, {
             encryptionSeed: this._configModel.seedPassword ?? undefined,
             logger: this._logger.for('aun_core.keystore'),
             secretStoreLogger: this._logger.for('aun_core.secret-store'),
         });
         this._keystore = keystore;
-        this._deviceId = getDeviceId(this._configModel.aunPath);
+        // 启动时被动清理 registerAid 留下的孤儿临时目录（>10 分钟）
+        try {
+            const cleanup = keystore.cleanupPendingDirs;
+            if (typeof cleanup === 'function') {
+                const removed = cleanup.call(keystore, 600_000);
+                if (removed > 0) {
+                    this._clientLog.info(`_pending cleanup removed=${removed}`);
+                }
+            }
+        }
+        catch (err) {
+            this._clientLog.warn(`_pending cleanup failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
         this._slotId = '';
         this._connectDeliveryMode = normalizeDeliveryModeConfig({ mode: 'fanout' });
         this._defaultConnectDeliveryMode = { ...this._connectDeliveryMode };
@@ -409,6 +540,7 @@ export class AUNClient {
             rootCaPath: this._configModel.rootCaPath ?? undefined,
             verifySsl: this._configModel.verifySsl,
             logger: this._logger.for('aun_core.auth'),
+            net: dnsNet,
         });
         this._aid = initAid;
         this._transport = new RPCTransport({
@@ -417,6 +549,7 @@ export class AUNClient {
             onDisconnect: (err, closeCode) => this._handleTransportDisconnect(err, closeCode),
             verifySsl: this._configModel.verifySsl,
             logger: this._logger.for('aun_core.transport'),
+            dnsNet,
         });
         this._transport.setMetaObserver((meta) => this._observeRpcMeta(meta));
         this.auth = new AuthNamespace(this);
@@ -453,61 +586,107 @@ export class AUNClient {
         return this._aid;
     }
     /**
-     * 读取本地 agent.md，签名后上传，并刷新本地 etag。
+     * 读取 {agentMdPath}/{self_aid}/agent.md，签名后上传，并把签名结果原子写回本地。
      */
-    async publishAgentMd(path) {
-        const rawPath = String(path ?? '').trim();
-        if (!rawPath) {
-            throw new ValidationError('publishAgentMd requires non-empty path');
+    async publishAgentMd() {
+        const target = this._agentMdOwnerAid();
+        if (!target) {
+            throw new ValidationError('publishAgentMd requires local AID');
         }
-        const content = fs.readFileSync(rawPath).toString('utf-8');
+        const content = this._readAgentMdContent(target);
         const signed = await this.auth.signAgentMd(content);
         const result = await this.auth.uploadAgentMd(signed);
-        const digest = crypto.createHash('sha256').update(signed, 'utf-8').digest('hex');
-        this._localAgentMdEtag = `"${digest}"`;
-        this._localAgentMdPath = rawPath;
+        this._localAgentMdEtag = this._agentMdContentEtag(signed);
+        const remoteEtag = isJsonObject(result) ? String(result.etag ?? '').trim() : '';
+        if (remoteEtag)
+            this._remoteAgentMdEtag = remoteEtag;
+        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;
     }
     /**
-     * 下载 agent.md 并自动验签；可选写盘；目标是自身 AID 时刷新本地 etag。
+     * 下载 agent.md 并自动验签；内容固定保存到 {agentMdPath}/{aid}/agent.md。
      */
-    async fetchAgentMd(aid, savePath) {
+    async fetchAgentMd(aid) {
         const target = String(aid ?? this._aid ?? '').trim();
         if (!target) {
             throw new ValidationError('fetchAgentMd requires aid (or local AID)');
         }
+        return await this._startAgentMdFetchTask(target);
+    }
+    async _startAgentMdFetchTask(target) {
+        const existing = this._agentMdFetchInflight.get(target);
+        if (existing) {
+            return await existing;
+        }
+        const task = this._fetchAgentMdOnce(target);
+        this._agentMdFetchInflight.set(target, task);
+        task.finally(() => {
+            if (this._agentMdFetchInflight.get(target) === task) {
+                this._agentMdFetchInflight.delete(target);
+            }
+        }).catch(() => undefined);
+        return await task;
+    }
+    async _fetchAgentMdOnce(target) {
         const content = await this.auth.downloadAgentMd(target);
         const signature = await this.auth.verifyAgentMd(content, { aid: target });
         const isSelf = target === (this._aid ?? '');
+        const localEtag = 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;
+        }
+        const saved = 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 inSync = null;
         if (isSelf) {
-            const digest = crypto.createHash('sha256').update(content, 'utf-8').digest('hex');
-            this._localAgentMdEtag = `"${digest}"`;
-            const local = this._localAgentMdEtag || '';
-            const remote = this._remoteAgentMdEtag || '';
-            inSync = local && remote ? local === remote : false;
-        }
-        let savedTo = null;
-        let saveError = null;
-        const rawSavePath = String(savePath ?? '').trim();
-        if (rawSavePath) {
-            try {
-                fs.writeFileSync(rawSavePath, content, 'utf-8');
-                savedTo = rawSavePath;
-            }
-            catch (exc) {
-                saveError = exc instanceof Error ? exc.message : String(exc);
-            }
+            const remote = remoteEtag || this._remoteAgentMdEtag || '';
+            inSync = localEtag && remote ? localEtag === remote : false;
         }
         return {
             aid: target,
             content,
             signature: signature,
             in_sync: inSync,
-            saved_to: savedTo,
-            save_error: saveError,
+            saved_to: String(saved.saved_to ?? this._agentMdFilePath(target)),
+            save_error: null,
         };
     }
+    /**
+     * 设置 agent.md 本地存储根目录；为空时恢复默认 {aun_path}/AIDs。
+     */
+    setAgentMdPath(root) {
+        const raw = String(root ?? '').trim();
+        const next = raw || path.join(this._configModel.aunPath, 'AIDs');
+        fs.mkdirSync(next, { recursive: true });
+        this._agentMdPath = next;
+        this._agentMdCache.clear();
+        return this._agentMdPath;
+    }
+    SetAgentMDPath(root) {
+        return this.setAgentMdPath(root);
+    }
     /**
      * 记录本地 agent.md 文件路径并一次性计算 etag（quoted sha256，与服务端一致）。
      *
@@ -558,6 +737,414 @@ export class AUNClient {
     getRemoteAgentMdEtag() {
         return this._remoteAgentMdEtag;
     }
+    _agentMdContentEtag(content) {
+        return `"${crypto.createHash('sha256').update(String(content ?? ''), 'utf-8').digest('hex')}"`;
+    }
+    _agentMdOwnerAid() {
+        return String(this._aid ?? '').trim();
+    }
+    _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;
+    }
+    _agentMdRoot() {
+        const root = this._agentMdPath || path.join(this._configModel.aunPath, 'AIDs');
+        fs.mkdirSync(root, { recursive: true });
+        return root;
+    }
+    _agentMdFilePath(aid) {
+        return path.join(this._agentMdRoot(), this._agentMdSafeAid(aid), 'agent.md');
+    }
+    _agentMdMetaPath(aid) {
+        return path.join(this._agentMdRoot(), this._agentMdSafeAid(aid), 'agentmd.json');
+    }
+    _atomicWriteText(filePath, content) {
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        const tmp = path.join(path.dirname(filePath), `.${path.basename(filePath)}.${process.pid}.${crypto.randomUUID()}.tmp`);
+        let fd = null;
+        try {
+            fd = fs.openSync(tmp, 'w');
+            fs.writeFileSync(fd, content, 'utf-8');
+            fs.fsyncSync(fd);
+            fs.closeSync(fd);
+            fd = null;
+            fs.renameSync(tmp, filePath);
+            try {
+                const dirFd = fs.openSync(path.dirname(filePath), 'r');
+                try {
+                    fs.fsyncSync(dirFd);
+                }
+                finally {
+                    fs.closeSync(dirFd);
+                }
+            }
+            catch { /* best effort */ }
+        }
+        finally {
+            if (fd !== null) {
+                try {
+                    fs.closeSync(fd);
+                }
+                catch { /* ignore */ }
+            }
+            if (fs.existsSync(tmp)) {
+                try {
+                    fs.unlinkSync(tmp);
+                }
+                catch { /* ignore */ }
+            }
+        }
+    }
+    _sleepSync(ms) {
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+    }
+    _withAgentMdRecordLock(aid, fn) {
+        const lockPath = path.join(path.dirname(this._agentMdMetaPath(aid)), 'agentmd.json.lock');
+        fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+        const deadline = Date.now() + 5000;
+        let fd = null;
+        while (fd === null) {
+            try {
+                fd = fs.openSync(lockPath, 'wx');
+                fs.writeFileSync(fd, `${process.pid}\n`, 'utf-8');
+            }
+            catch (err) {
+                if (err?.code !== 'EEXIST' || Date.now() >= deadline)
+                    throw err;
+                try {
+                    const st = fs.statSync(lockPath);
+                    if (Date.now() - st.mtimeMs > 30000)
+                        fs.unlinkSync(lockPath);
+                }
+                catch { /* ignore */ }
+                this._sleepSync(25);
+            }
+        }
+        try {
+            return fn();
+        }
+        finally {
+            if (fd !== null) {
+                try {
+                    fs.closeSync(fd);
+                }
+                catch { /* ignore */ }
+            }
+            try {
+                fs.unlinkSync(lockPath);
+            }
+            catch { /* ignore */ }
+        }
+    }
+    _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);
+        this._atomicWriteText(this._agentMdMetaPath(aid), `${JSON.stringify(payload, null, 2)}\n`);
+    }
+    _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;
+    }
+    _readAgentMdRecordUnlocked(aid) {
+        const filePath = this._agentMdMetaPath(aid);
+        if (!fs.existsSync(filePath))
+            return {};
+        try {
+            return this._normalizeAgentMdRecord(aid, JSON.parse(fs.readFileSync(filePath, 'utf-8')));
+        }
+        catch (err) {
+            this._clientLog.warn(`agent.md metadata damaged, ignoring: aid=${aid} err=${err instanceof Error ? err.message : String(err)}`);
+            return {};
+        }
+    }
+    _readAgentMdContent(aid) {
+        return fs.readFileSync(this._agentMdFilePath(aid), 'utf-8');
+    }
+    _writeAgentMdContent(aid, content) {
+        const filePath = this._agentMdFilePath(aid);
+        this._atomicWriteText(filePath, String(content ?? ''));
+        return filePath;
+    }
+    _agentMdAuthCacheMeta(aid) {
+        try {
+            const store = this.auth._agentMdCache;
+            const record = store?.get(String(aid ?? '').trim());
+            return record && typeof record === 'object' ? { ...record } : {};
+        }
+        catch {
+            return {};
+        }
+    }
+    _loadAgentMdRecord(aid) {
+        const target = String(aid ?? '').trim();
+        if (!target)
+            return null;
+        try {
+            const loaded = this._withAgentMdRecordLock(target, () => {
+                const record = this._readAgentMdRecordUnlocked(target);
+                const next = Object.keys(record).length > 0 ? { ...record, aid: target } : { aid: target };
+                try {
+                    const content = this._readAgentMdContent(target);
+                    next.content = content;
+                    next.local_etag = this._agentMdContentEtag(content);
+                }
+                catch (err) {
+                    if (fs.existsSync(this._agentMdMetaPath(target))) {
+                        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;
+    }
+    _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;
+            let savedTo = '';
+            const record = this._withAgentMdRecordLock(target, () => {
+                if (hasContent) {
+                    const content = String(inputFields.content ?? '');
+                    savedTo = this._writeAgentMdContent(target, content);
+                    if (!inputFields.local_etag)
+                        inputFields.local_etag = this._agentMdContentEtag(content);
+                    if (!inputFields.fetched_at)
+                        inputFields.fetched_at = Date.now();
+                }
+                delete inputFields.content;
+                const next = { ...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();
+                this._writeAgentMdRecordUnlocked(target, next);
+                return next;
+            });
+            const loaded = { ...record };
+            if (hasContent) {
+                loaded.content = String(fields.content ?? '');
+                if (savedTo)
+                    loaded.saved_to = savedTo;
+            }
+            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 {};
+    }
+    _agentMdHasLocalContent(aid, record) {
+        if (record && typeof record.content === 'string' && record.content.length > 0)
+            return true;
+        try {
+            return fs.existsSync(this._agentMdFilePath(aid));
+        }
+        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;
+    }
+    _scheduleAgentMdFetchIfMissing(aid, record, source = '') {
+        const target = String(aid ?? '').trim();
+        if (!target || this._agentMdHasLocalContent(target, record))
+            return;
+        if (this._agentMdFetchInflight.has(target))
+            return;
+        void this.fetchAgentMd(target).catch((err) => {
+            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)}`);
+        });
+    }
+    _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 = 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 = this._saveAgentMdRecord(target, fields) || record;
+        }
+        if (target === this._agentMdOwnerAid() && remoteEtag)
+            this._remoteAgentMdEtag = remoteEtag;
+        this._scheduleAgentMdFetchIfMissing(target, record, source);
+        this._clientLog.debug(`agent.md meta observed: aid=${target} etag=${remoteEtag || '-'} last_modified=${remoteLastModified || '-'} source=${source || '-'}`);
+    }
+    _observeAgentMdEtag(aid, etag, source = '') {
+        this._observeAgentMdMeta(aid, etag, '', source);
+    }
+    _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();
+        }
+        this._observeAgentMdMeta(senderAid, String(sender.etag ?? '').trim(), String(sender.last_modified ?? sender.lastModified ?? '').trim(), 'envelope');
+    }
+    async checkAgentMd(aid, maxUnsyncedDays = 1) {
+        const target = String(aid ?? this._aid ?? '').trim();
+        if (!target)
+            throw new ValidationError('checkAgentMd requires aid (or local AID)');
+        const before = 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 checkedAt = Number(before.checked_at ?? 0);
+        const fetchedAt = Number(before.fetched_at ?? 0);
+        const checkedAtCached = checkedAt > 0 ? checkedAt : fetchedAt;
+        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 remoteFoundCached = !!(remoteEtagCached || String(before.remote_status ?? '') === 'found');
+        if (!localFound &&
+            !remoteFoundCached &&
+            String(before.remote_status ?? '') === 'missing' &&
+            this._agentMdCheckedAtFresh(checkedAtCached, maxUnsyncedDays)) {
+            return {
+                aid: target,
+                local_found: false,
+                remote_found: false,
+                local_etag: '',
+                remote_etag: '',
+                in_sync: false,
+                last_modified: '',
+                status: 404,
+                cached: true,
+                verify_status: '',
+                verify_error: '',
+            };
+        }
+        const now = Date.now();
+        let remote;
+        try {
+            remote = await this.auth.headAgentMd(target);
+        }
+        catch (err) {
+            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 = 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) {
         if (!meta || typeof meta !== 'object')
@@ -565,6 +1152,17 @@ export class AUNClient {
         const etag = String(meta.agent_md_etag ?? '').trim();
         if (etag) {
             this._remoteAgentMdEtag = etag;
+            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;
+                this._observeAgentMdMeta(String(item.aid ?? ''), String(item.etag ?? ''), String(item.last_modified ?? item.lastModified ?? ''), `rpc.${key}`);
+            }
         }
     }
     /** 连接状态 */
@@ -613,19 +1211,31 @@ export class AUNClient {
         this._transport.setTimeout(callTimeoutSec != null ? callTimeoutSec * 1000 : 35_000);
         this._closing = false;
         this._clientLog.debug(`connect enter: gateway=${String(normalized.gateway ?? '')}, device_id=${this._deviceId}`);
-        try {
-            await this._connectOnce(normalized, false);
-            this._clientLog.debug(`connect exit: elapsed=${Date.now() - tStart}ms aid=${this._aid ?? ''}, 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 aid=${this._aid ?? ''}, state=${this._state}`);
+                return;
             }
-            this._clientLog.error(`connect failed: ${formatCaughtError(err)}`, err instanceof Error ? err : undefined);
-            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: ${formatCaughtError(err)}`);
+                }
+                if (this._state === 'connecting' || this._state === 'authenticating') {
+                    this._state = 'connecting';
+                }
+            }
+        }
+        if (this._state === 'connecting' || this._state === 'authenticating') {
+            this._state = 'disconnected';
         }
+        this._clientLog.error(`connect failed: ${formatCaughtError(lastErr)}`, lastErr instanceof Error ? lastErr : undefined);
+        this._clientLog.debug(`connect exit (error): elapsed=${Date.now() - tStart}ms err=${lastErr instanceof Error ? lastErr.message : String(lastErr)}`);
+        throw lastErr;
     }
     /** 关闭连接 */
     async close() {
@@ -690,11 +1300,17 @@ export class AUNClient {
         }
     }
     /**
-     * 列出本地所有已存储的身份摘要（仅返回有有效私钥的 AID）。
+     * 列出本地身份摘要。
+     *
+     * @param opts.all=false（默认）：仅返回严格校验通过的可用身份——
+     *   keypair 完整 + cert 公钥 == keypair 公钥 + cert 时间窗口有效
+     * @param opts.all=true：返回所有 AIDs/ 子目录（不含 _pending/）；
+     *   每项含 valid=bool 和 reason=string 字段
      */
-    listIdentities() {
+    listIdentities(opts) {
         const tStart = Date.now();
-        this._clientLog.debug(`listIdentities enter`);
+        const includeAll = !!opts?.all;
+        this._clientLog.debug(`listIdentities enter all=${includeAll}`);
         try {
             const listFn = this._keystore.listIdentities;
             if (typeof listFn !== 'function') {
@@ -704,10 +1320,12 @@ export class AUNClient {
             const aids = listFn.call(this._keystore);
             const summaries = [];
             for (const aid of [...aids].sort()) {
-                const identity = this._keystore.loadIdentity(aid);
-                if (!identity || !identity.private_key_pem)
+                const { valid, reason } = this._validateLocalIdentity(aid);
+                if (!includeAll && !valid)
                     continue;
-                const summary = { aid };
+                const summary = { aid, valid };
+                if (reason)
+                    summary.reason = reason;
                 const loadMetadata = this._keystore.loadMetadata;
                 if (typeof loadMetadata === 'function') {
                     const md = loadMetadata.call(this._keystore, aid);
@@ -716,7 +1334,7 @@ export class AUNClient {
                 }
                 summaries.push(summary);
             }
-            this._clientLog.debug(`listIdentities exit: elapsed=${Date.now() - tStart}ms count=${summaries.length}`);
+            this._clientLog.debug(`listIdentities exit: elapsed=${Date.now() - tStart}ms all=${includeAll} count=${summaries.length}`);
             return summaries;
         }
         catch (err) {
@@ -724,6 +1342,40 @@ export class AUNClient {
             throw err;
         }
     }
+    /**
+     * 严格校验本地身份的可用性。返回 {valid, reason}。
+     * 4 项校验：keypair 完整 + cert 存在 + cert 公钥 == keypair 公钥 + cert 时间窗口有效。
+     */
+    _validateLocalIdentity(aid) {
+        const identity = this._keystore.loadIdentity(aid);
+        if (!identity)
+            return { valid: false, reason: 'no identity record' };
+        const priv = String(identity.private_key_pem ?? '');
+        const pubB64 = String(identity.public_key_der_b64 ?? '');
+        const certPem = String(identity.cert ?? '');
+        if (!priv || !pubB64)
+            return { valid: false, reason: 'missing keypair' };
+        if (!certPem)
+            return { valid: false, reason: 'missing certificate' };
+        try {
+            const crypto = require('node:crypto');
+            const cert = new crypto.X509Certificate(certPem);
+            const certPubDer = cert.publicKey.export({ type: 'spki', format: 'der' });
+            const localPubDer = Buffer.from(pubB64, 'base64');
+            if (!certPubDer.equals(localPubDer)) {
+                return { valid: false, reason: 'cert public key does not match keypair' };
+            }
+            const now = Date.now();
+            if (now < new Date(cert.validFrom).getTime())
+                return { valid: false, reason: 'cert not yet valid' };
+            if (now > new Date(cert.validTo).getTime())
+                return { valid: false, reason: 'cert expired' };
+            return { valid: true, reason: '' };
+        }
+        catch (e) {
+            return { valid: false, reason: `cert parse error: ${e instanceof Error ? e.message : String(e)}` };
+        }
+    }
     // ── RPC ───────────────────────────────────────────────────
     /**
      * 发送 JSON-RPC 调用。
@@ -743,6 +1395,16 @@ export class AUNClient {
                 throw new PermissionError(`legacy E2EE method is removed in this SDK: ${method}`);
             }
             const p = { ...(params ?? {}) };
+            const rpcBackground = Boolean(p._rpc_background) || this._backgroundRpcDepth > 0;
+            delete p._rpc_background;
+            const runWithRpcPriority = async (operation) => {
+                if (!rpcBackground)
+                    return await operation();
+                return await this._withBackgroundRpc(operation);
+            };
+            if (method === 'message.send' || method === 'group.send') {
+                this._normalizeOutboundMessagePayload(p, method);
+            }
             this._validateOutboundCall(method, p);
             this._injectMessageCursorContext(method, p);
             // group.* 方法的 group_id 归一化为 canonical 格式（兼容老/污染数据）
@@ -755,23 +1417,39 @@ 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) {
                 p.slot_id = this._slotId;
             }
+            const pullGateLocked = Boolean(p._pull_gate_locked);
+            if ('_pull_gate_locked' in p) {
+                delete p._pull_gate_locked;
+            }
+            const pullGateKey = this._pullGateKeyForCall(method, p);
+            if (pullGateKey && this._isPullResponseProcessing(pullGateKey)) {
+                this._clientLog.debug(`pull skipped while processing pull response: method=${method} key=${pullGateKey}`);
+                return this._emptyPullResultForCall(method);
+            }
+            if (pullGateKey && !pullGateLocked) {
+                const lockedParams = { ...p, _pull_gate_locked: true };
+                if (rpcBackground)
+                    lockedParams._rpc_background = true;
+                const result = await this._runPullSerialized(pullGateKey, async () => this.call(method, lockedParams));
+                return result;
+            }
             // 自动加密：message.send 默认加密（encrypt 默认 true）— V2-only
             if (method === 'message.send') {
                 const encrypt = p.encrypt ?? true;
                 delete p.encrypt;
                 if (encrypt) {
-                    return await this.sendV2(String(p.to ?? ''), p.payload, {
+                    return await runWithRpcPriority(() => this.sendV2(String(p.to ?? ''), p.payload, {
                         messageId: String(p.message_id ?? '') || undefined,
                         timestamp: p.timestamp,
                         protectedHeaders: this._protectedHeadersFromParams(p),
                         context: isJsonObject(p.context) ? p.context : undefined,
-                    });
+                    }));
                 }
                 // encrypt=false：明文走通用 RPC 路径；protected_headers/headers 是信封元数据，加密与否都保留
                 this._maybeAppendEchoTraceSend(p);
@@ -781,12 +1459,12 @@ export class AUNClient {
                 const encrypt = p.encrypt ?? true;
                 delete p.encrypt;
                 if (encrypt) {
-                    return await this.sendGroupV2(String(p.group_id ?? ''), p.payload, {
+                    return await runWithRpcPriority(() => this.sendGroupV2(String(p.group_id ?? ''), p.payload, {
                         messageId: String(p.message_id ?? '') || undefined,
                         timestamp: p.timestamp,
                         protectedHeaders: this._protectedHeadersFromParams(p),
                         context: isJsonObject(p.context) ? p.context : undefined,
-                    });
+                    }));
                 }
                 this._maybeAppendEchoTraceSend(p);
             }
@@ -798,7 +1476,7 @@ export class AUNClient {
                     if (!this._v2Session || !String(p.group_id ?? '').trim()) {
                         throw new StateError(v2Error);
                     }
-                    return await this._putGroupThoughtEncryptedV2(p);
+                    return await runWithRpcPriority(() => this._putGroupThoughtEncryptedV2(p));
                 }
             }
             if (method === 'message.thought.put') {
@@ -806,40 +1484,70 @@ export class AUNClient {
                 delete p.encrypt;
                 if (encrypt) {
                     await this._ensureV2SessionReady('message.thought.put', 'V2 session not initialized; encrypted message.thought.put requires V2 (V1 E2EE removed)');
-                    return await this._putMessageThoughtEncryptedV2(p);
+                    return await runWithRpcPriority(() => this._putMessageThoughtEncryptedV2(p));
                 }
             }
-            if (method === 'message.pull' && this._clientUsesV2P2P()) {
+            // V2-only：兼容入口名只作为 SDK 内部适配层存在，底层绝不能降级发 legacy RPC。
+            if (method === 'message.pull' || method === 'message.v2.pull') {
                 await this._ensureV2SessionReady('message.pull');
-                const messages = await this.pullV2(Number(p.after_seq ?? 0) || 0, Number(p.limit ?? 50) || 50);
+                const skipAutoAck = p._skip_auto_ack === true || p.skip_auto_ack === true;
+                const afterSeq = Number(p.after_seq ?? 0) || 0;
+                const limit = Number(p.limit ?? 50) || 50;
+                const messages = skipAutoAck
+                    ? await runWithRpcPriority(() => this.pullV2(afterSeq, limit, { skipAutoAck: true, gateLocked: true }))
+                    : await runWithRpcPriority(() => this.pullV2(afterSeq, limit, { gateLocked: true }));
                 return { messages };
             }
-            if (method === 'message.ack' && this._clientUsesV2P2P()) {
+            if (method === 'message.ack' || method === 'message.v2.ack') {
                 await this._ensureV2SessionReady('message.ack');
-                return await this.ackV2(Number(p.seq ?? p.up_to_seq ?? 0) || undefined);
+                return await runWithRpcPriority(() => this.ackV2(Number(p.seq ?? p.up_to_seq ?? 0) || undefined));
             }
-            if (method === 'group.pull' && this._clientUsesV2Group() && p.group_id) {
+            if (method === 'group.pull' || method === 'group.v2.pull') {
+                if (!String(p.group_id ?? '').trim()) {
+                    throw new ValidationError('group.pull requires group_id');
+                }
                 await this._ensureV2SessionReady('group.pull');
-                const messages = await this.pullGroupV2(String(p.group_id), Number(p.after_seq ?? p.after_message_seq ?? 0) || 0, Number(p.limit ?? 50) || 50);
+                const messages = await runWithRpcPriority(() => this.pullGroupV2(String(p.group_id), Number(p.after_seq ?? p.after_message_seq ?? 0) || 0, Number(p.limit ?? 50) || 50, { gateLocked: true }));
                 return { messages };
             }
-            if (method === 'group.ack_messages' && this._clientUsesV2Group() && p.group_id) {
+            if (method === 'group.ack_messages' || method === 'group.v2.ack') {
+                if (!String(p.group_id ?? '').trim()) {
+                    throw new ValidationError('group.ack_messages requires group_id');
+                }
                 await this._ensureV2SessionReady('group.ack_messages');
-                return await this.ackGroupV2(String(p.group_id), Number(p.seq ?? p.msg_seq ?? p.up_to_seq ?? 0) || undefined);
+                return await runWithRpcPriority(() => this.ackGroupV2(String(p.group_id), Number(p.seq ?? p.msg_seq ?? p.up_to_seq ?? 0) || undefined));
+            }
+            if (method === 'message.pull') {
+                delete p._skip_auto_ack;
+                delete p.skip_auto_ack;
             }
             // 关键操作自动附加客户端签名
             if (SIGNED_METHODS.has(method)) {
-                this._signClientOperation(method, p);
+                if (this._shouldSkipClientSignature(method, p)) {
+                    delete p.client_signature;
+                }
+                else {
+                    this._signClientOperation(method, p);
+                }
             }
             // P1-23: 非幂等方法使用更长超时
             const callTimeout = NON_IDEMPOTENT_METHODS.has(method) ? NON_IDEMPOTENT_TIMEOUT_MS : undefined;
+            if (method === 'group.thought.get' || method === 'message.thought.get') {
+                this._clientLog.debug(`thought.get transport call start: method=${method}, params=${this._debugJson(this._messageEnvelopeFieldsForDebug(p))}`);
+            }
             let result = callTimeout
-                ? await this._transport.call(method, p, callTimeout)
-                : await this._transport.call(method, p);
+                ? (rpcBackground
+                    ? await this._transport.call(method, p, callTimeout, undefined, true)
+                    : await this._transport.call(method, p, callTimeout))
+                : (rpcBackground
+                    ? await this._transport.call(method, p, undefined, undefined, true)
+                    : await this._transport.call(method, p));
             if (method === 'group.thought.get' && isJsonObject(result)) {
+                this._clientLog.debug(`group.thought.get transport result: found=${String(result.found ?? '')}, raw_count=${Array.isArray(result.thoughts) ? result.thoughts.length : 0}`);
                 result = await this._decryptGroupThoughts(result);
             }
             if (method === 'message.thought.get' && isJsonObject(result)) {
+                this._clientLog.debug(`message.thought.get transport result: found=${String(result.found ?? '')}, raw_count=${Array.isArray(result.thoughts) ? result.thoughts.length : 0}`);
                 result = await this._decryptMessageThoughts(result);
             }
             // ── V2-only 群状态编排：成员变更后 propose+confirm state。
@@ -919,6 +1627,34 @@ export class AUNClient {
         this._clientLog.debug(`on exit: elapsed=${Date.now() - tStart}ms event=${event}`);
         return result;
     }
+    async _callRawV2Rpc(method, params) {
+        const p = { ...(params ?? {}) };
+        const rpcBackground = Boolean(p._rpc_background) || this._backgroundRpcDepth > 0;
+        delete p._rpc_background;
+        delete p._pull_gate_locked;
+        delete p._skip_auto_ack;
+        delete p.skip_auto_ack;
+        if (method.startsWith('group.') && p.group_id !== undefined && p.group_id !== null) {
+            p.group_id = normalizeGroupId(String(p.group_id)) || String(p.group_id);
+        }
+        if (method.startsWith('group.') && p.device_id === undefined) {
+            p.device_id = this._deviceId;
+        }
+        if (method.startsWith('group.') && p.slot_id === undefined) {
+            p.slot_id = this._slotId;
+        }
+        if (SIGNED_METHODS.has(method)) {
+            if (this._shouldSkipClientSignature(method, p)) {
+                delete p.client_signature;
+            }
+            else {
+                this._signClientOperation(method, p);
+            }
+        }
+        return rpcBackground
+            ? await this._transport.call(method, p, undefined, undefined, true)
+            : await this._transport.call(method, p);
+    }
     /** P2-13: 取消订阅事件（对齐 Python/JS off 方法） */
     off(event, handler) {
         const tStart = Date.now();
@@ -988,6 +1724,7 @@ export class AUNClient {
     async _onRawMessageReceived(data) {
         const tStart = Date.now();
         if (isJsonObject(data)) {
+            this._logMessageDebug('server-push', '_raw.message.received', 'message.received', data);
             this._clientLog.debug(`_onRawMessageReceived enter: from=${String(data.from ?? '')}, message_id=${String(data.message_id ?? '')}, seq=${String(data.seq ?? '')}`);
         }
         else {
@@ -1006,7 +1743,8 @@ export class AUNClient {
                     timestamp: data.timestamp,
                     _decrypt_error: String(exc),
                 };
-                this._publishAppEvent('message.undecryptable', safeEvent).catch(() => { });
+                this._attachV2EnvelopeMetadataFromSource(safeEvent, data);
+                Promise.resolve(this._publishAppEvent('message.undecryptable', safeEvent)).catch(() => { });
             }
         });
         this._clientLog.debug(`_onRawMessageReceived exit: elapsed=${Date.now() - tStart}ms (handler dispatched)`);
@@ -1014,47 +1752,53 @@ export class AUNClient {
     /** 实际处理推送消息的异步任务 */
     async _processAndPublishMessage(data) {
         if (!isJsonObject(data)) {
-            await this._publishAppEvent('message.received', data);
+            await this._publishAppEvent('message.received', data, 'push');
             return;
         }
         const msg = { ...data };
         if (!this._messageTargetsCurrentInstance(msg)) {
+            this._clientLog.debug(`P2P push filtered by instance: message_id=${String(msg.message_id ?? '')}, seq=${String(msg.seq ?? '')}, target_device=${String(msg.device_id ?? '')}, target_slot=${String(msg.slot_id ?? '')}, local_device=${this._deviceId}, local_slot=${this._slotId}`);
             return;
         }
         // P2P 空洞检测
         const seq = msg.seq;
         if (seq !== undefined && seq !== null && this._aid) {
             const ns = `p2p:${this._aid}`;
-            const needPull = this._seqTracker.onMessageSeq(ns, seq);
+            // Push 只先更新 maxSeenSeq；contiguous_seq 是已交付游标，必须等应用层发布返回后再推进。
+            if (seq > 0)
+                this._seqTracker.updateMaxSeen(ns, seq);
+            const contigBefore = this._seqTracker.getContiguousSeq(ns);
+            const published = await this._publishOrderedMessage('message.received', ns, seq, msg);
+            const contigAfter = this._seqTracker.getContiguousSeq(ns);
+            const needPull = Number(seq) > contigAfter && !published;
             if (needPull) {
-                this._clientLog.debug(`P2P seq gap detected: ns=${ns}, seq=${seq}, contiguous=${this._seqTracker.getContiguousSeq(ns)}`);
+                this._clientLog.debug(`P2P seq gap detected: ns=${ns}, seq=${seq}, contiguous=${contigAfter}`);
                 this._fillP2pGap().catch(exc => this._clientLog.warn(`background gap fill trigger failed: ${formatCaughtError(exc)}`));
             }
             // auto-ack contiguous_seq
             const contig = this._seqTracker.getContiguousSeq(ns);
             if (contig > 0) {
-                this._transport.call('message.ack', {
-                    seq: contig,
-                    device_id: this._deviceId,
-                    slot_id: this._slotId,
-                }).catch((e) => { this._clientLog.debug(`P2P auto-ack failed: ${formatCaughtError(e)}`); });
+                const maxSeen = this._seqTracker.getMaxSeenSeq(ns);
+                const ackSeq = maxSeen > 0 ? Math.min(contig, maxSeen) : contig;
+                this._clientLog.debug(`P2P push auto-ack send: ns=${ns}, seq=${ackSeq}, contiguous=${contig}, max_seen=${maxSeen}`);
+                this._withBackgroundRpc(() => this.ackV2(ackSeq))
+                    .then(() => { this._clientLog.debug(`P2P push auto-ack ok: ns=${ns}, seq=${ackSeq}`); })
+                    .catch((e) => { this._clientLog.debug(`P2P auto-ack failed: ${formatCaughtError(e)}`); });
             }
             // 即时持久化 cursor，异常断连后不回退
-            this._saveSeqTrackerState();
-        }
-        // V2-only：普通 _raw.message.received 只承载明文；V2 密文由 peer.v2.message_received 通知触发 pull。
-        if (seq !== undefined && seq !== null && this._aid) {
-            const ns = `p2p:${this._aid}`;
-            await this._publishOrderedMessage('message.received', ns, seq, msg);
+            if (contigAfter !== contigBefore)
+                this._saveSeqTrackerState();
         }
         else {
-            await this._publishAppEvent('message.received', msg);
+            // V2-only：普通 _raw.message.received 只承载明文；V2 密文由 peer.v2.message_received 通知触发 pull。
+            await this._publishAppEvent('message.received', msg, 'push');
         }
     }
     /** 处理群组消息推送：自动解密后 re-publish */
     async _onRawGroupMessageCreated(data) {
         const tStart = Date.now();
         if (isJsonObject(data)) {
+            this._logMessageDebug('server-push', '_raw.group.message_created', 'group.message_created', data);
             this._clientLog.debug(`_onRawGroupMessageCreated enter: group_id=${String(data.group_id ?? '')}, message_id=${String(data.message_id ?? '')}, seq=${String(data.seq ?? '')}`);
         }
         else {
@@ -1072,7 +1816,8 @@ export class AUNClient {
                     timestamp: data.timestamp,
                     _decrypt_error: String(exc),
                 };
-                this._publishAppEvent('group.message_undecryptable', safeEvent).catch(() => { });
+                this._attachV2EnvelopeMetadataFromSource(safeEvent, data);
+                Promise.resolve(this._publishAppEvent('group.message_undecryptable', safeEvent)).catch(() => { });
             }
         });
         this._clientLog.debug(`_onRawGroupMessageCreated exit: elapsed=${Date.now() - tStart}ms (handler dispatched)`);
@@ -1085,7 +1830,7 @@ export class AUNClient {
      */
     async _processAndPublishGroupMessage(data) {
         if (!isJsonObject(data)) {
-            await this._publishAppEvent('group.message_created', data);
+            await this._publishAppEvent('group.message_created', data, 'group-push');
             return;
         }
         const msg = { ...data };
@@ -1098,125 +1843,88 @@ export class AUNClient {
         if (payload === undefined || payload === null
             || (typeof payload === 'object' && Object.keys(payload).length === 0)) {
             // 不带 payload 的通知不能先推进 seq，否则 auto-pull 会用推进后的 cursor 跳过该消息。
-            await this._autoPullGroupMessages(msg);
+            void this._autoPullGroupMessages(msg).catch((exc) => {
+                this._clientLog.warn(`auto pull group message task failed: ${formatCaughtError(exc)}`);
+            });
             return;
         }
         if (groupId && seq !== undefined && seq !== null) {
             const ns = `group:${groupId}`;
-            const needPull = this._seqTracker.onMessageSeq(ns, seq);
+            // Push 只先更新 maxSeenSeq；contiguous_seq 是已交付游标，必须等应用层发布返回后再推进。
+            if (seq > 0)
+                this._seqTracker.updateMaxSeen(ns, seq);
+            const contigBefore = this._seqTracker.getContiguousSeq(ns);
+            const published = await this._publishOrderedMessage('group.message_created', ns, seq, msg);
+            const contigAfter = this._seqTracker.getContiguousSeq(ns);
+            const needPull = Number(seq) > contigAfter && !published;
             if (needPull) {
-                this._clientLog.debug(`group message seq gap detected: group=${groupId}, seq=${seq}, contiguous=${this._seqTracker.getContiguousSeq(ns)}`);
+                this._clientLog.debug(`group message seq gap detected: group=${groupId}, seq=${seq}, contiguous=${contigAfter}`);
                 this._fillGroupGap(groupId).catch(exc => this._clientLog.warn(`background gap fill trigger failed: ${formatCaughtError(exc)}`));
             }
             const contig = this._seqTracker.getContiguousSeq(ns);
             if (contig > 0) {
-                this._transport.call('group.ack_messages', {
-                    group_id: groupId,
-                    msg_seq: contig,
-                    device_id: this._deviceId,
-                    slot_id: this._slotId,
-                }).catch((e) => { this._clientLog.debug(`group message auto-ack failed: group=${groupId} ${formatCaughtError(e)}`); });
-            }
-            this._saveSeqTrackerState();
-        }
-        // V2-only：普通 group.message_created 只承载明文；V2 密文由 group.v2.message_created 通知触发 pull。
-        if (groupId && seq !== undefined && seq !== null) {
-            const nsKey = `group:${groupId}`;
-            await this._publishOrderedMessage('group.message_created', nsKey, seq, msg);
+                const maxSeen = this._seqTracker.getMaxSeenSeq(ns);
+                const ackSeq = maxSeen > 0 ? Math.min(contig, maxSeen) : contig;
+                this._clientLog.debug(`group push auto-ack send: group=${groupId}, ns=${ns}, seq=${ackSeq}, contiguous=${contig}, max_seen=${maxSeen}`);
+                this._withBackgroundRpc(() => this.ackGroupV2(groupId, ackSeq))
+                    .then(() => { this._clientLog.debug(`group push auto-ack ok: group=${groupId}, seq=${ackSeq}`); })
+                    .catch((e) => { this._clientLog.debug(`group message auto-ack failed: group=${groupId} ${formatCaughtError(e)}`); });
+            }
+            if (contigAfter !== contigBefore)
+                this._saveSeqTrackerState();
         }
         else {
-            await this._publishAppEvent('group.message_created', msg);
+            // V2-only：普通 group.message_created 只承载明文；V2 密文由 group.v2.message_created 通知触发 pull。
+            await this._publishAppEvent('group.message_created', msg, 'group-push');
         }
     }
     /** 收到不带 payload 的 group.message_created 通知后，自动 pull 最新消息 */
     async _autoPullGroupMessages(notification) {
-        const groupId = (notification.group_id ?? '');
+        let groupId = String(notification.group_id ?? '').trim();
         if (!groupId) {
             await this._publishAppEvent('group.message_created', notification);
             return;
         }
+        groupId = normalizeGroupId(groupId) || groupId;
         const ns = `group:${groupId}`;
         const afterSeq = this._seqTracker.getContiguousSeq(ns);
-        try {
-            // V2-only 模式：走 group.v2.pull（合并 V1 明文 + V2 密文并自动解密）
-            if (this._v2Session) {
-                await this._pullGroupV2Internal({ group_id: groupId, after_seq: afterSeq, limit: 50 });
-                return;
-            }
-            const result = await this.call('group.pull', {
-                group_id: groupId,
-                after_message_seq: afterSeq,
-                device_id: this._deviceId,
-                limit: 50,
-            });
-            if (isJsonObject(result)) {
-                const messages = result.messages;
-                if (Array.isArray(messages)) {
-                    // onPullResult 已在 call() 拦截器中调用，此处不再重复
-                    const pushed = this._pushedSeqs.get(ns);
-                    for (const msg of messages) {
-                        if (isJsonObject(msg)) {
-                            const s = msg.seq;
-                            if (pushed && s !== undefined && s !== null && pushed.has(s)) {
-                                continue; // 已发布到应用层，跳过
-                            }
-                            if (s !== undefined && s !== null) {
-                                await this._publishPulledMessage('group.message_created', ns, s, msg);
-                            }
-                            else {
-                                await this._publishAppEvent('group.message_created', msg);
-                            }
-                        }
-                    }
-                    this._prunePushedSeqs(ns);
-                    return;
-                }
-            }
-        }
-        catch (exc) {
-            this._clientLog.debug(`auto pull group messages failed: ${formatCaughtError(exc)}`);
+        this._clientLog.debug(`auto pull group messages start: group=${groupId}, after_seq=${afterSeq}, seq=${String(notification.seq ?? '')}`);
+        const started = await this._tryRunBackgroundPull(ns, async () => {
+            const pullAfterSeq = this._seqTracker.getContiguousSeq(ns);
+            const messages = await this.pullGroupV2(groupId, pullAfterSeq, 50, { gateLocked: true });
+            this._prunePushedSeqs(ns);
+            return messages.length;
+        }, true);
+        if (!started) {
+            this._clientLog.debug(`auto pull group messages skipped: pull in-flight group=${groupId}`);
         }
-        await this._publishAppEvent('group.message_created', notification);
     }
     /** 后台补齐群消息空洞 */
     async _fillGroupGap(groupId) {
+        groupId = normalizeGroupId(groupId) || String(groupId ?? '').trim();
+        if (!groupId)
+            return;
         const ns = `group:${groupId}`;
         const afterSeq = this._seqTracker.getContiguousSeq(ns);
         // 去重：同一 (group:id:after_seq) 只补一次
         const dedupKey = `group_msg:${groupId}:${afterSeq}`;
         if (this._gapFillDone.has(dedupKey))
             return;
+        const token = this._tryAcquirePullGate(ns);
+        if (token === null) {
+            this._clientLog.debug(`group message gap fill skipped: pull in-flight group=${groupId}`);
+            return;
+        }
         this._gapFillDone.set(dedupKey, Date.now());
         this._clientLog.debug(`group message gap fill start: group=${groupId}, after_seq=${afterSeq}`);
+        let filled = 0;
         try {
-            const result = await this.call('group.pull', {
-                group_id: groupId,
-                after_message_seq: afterSeq,
-                device_id: this._deviceId,
-                limit: 50,
-            });
-            let filled = 0;
-            if (isJsonObject(result)) {
-                const messages = result.messages;
-                if (Array.isArray(messages)) {
-                    // onPullResult 已在 call() 拦截器中调用，此处不再重复
-                    const pushed = this._pushedSeqs.get(ns);
-                    for (const msg of messages) {
-                        if (isJsonObject(msg)) {
-                            const s = msg.seq;
-                            if (pushed && s !== undefined && s !== null && pushed.has(s))
-                                continue;
-                            if (s !== undefined && s !== null) {
-                                await this._publishPulledMessage('group.message_created', ns, s, msg);
-                            }
-                            else {
-                                await this._publishAppEvent('group.message_created', msg);
-                            }
-                            filled += 1;
-                        }
-                    }
-                    this._prunePushedSeqs(ns);
-                }
+            const messages = await this._withBackgroundRpc(() => this.pullGroupV2(groupId, afterSeq, 50, { gateLocked: true }));
+            filled = messages.length;
+            this._prunePushedSeqs(ns);
+            if (this._seqTracker.getContiguousSeq(ns) !== afterSeq) {
+                await this._drainOrderedMessages(ns, undefined, true);
+                this._saveSeqTrackerState();
             }
             this._clientLog.debug(`group message gap fill done: group=${groupId}, after_seq=${afterSeq}, filled=${filled}`);
         }
@@ -1225,6 +1933,10 @@ export class AUNClient {
         }
         finally {
             this._gapFillDone.delete(dedupKey);
+            this._releasePullGate(ns, token);
+            if (filled > 0 && this._seqTracker.getContiguousSeq(ns) > afterSeq) {
+                void this._fillGroupGap(groupId);
+            }
         }
     }
     /** 后台补齐 P2P 消息空洞 */
@@ -1237,35 +1949,25 @@ export class AUNClient {
         const dedupKey = `p2p:${afterSeq}`;
         if (this._gapFillDone.has(dedupKey))
             return;
+        const token = this._tryAcquirePullGate(ns);
+        if (token === null) {
+            this._clientLog.debug(`P2P message gap fill skipped: pull in-flight ns=${ns}`);
+            return;
+        }
         this._gapFillDone.set(dedupKey, Date.now());
         this._clientLog.debug(`P2P message gap fill start: after_seq=${afterSeq}`);
+        let filled = 0;
         try {
-            const result = await this.call('message.pull', {
-                after_seq: afterSeq,
-                limit: 50,
-            });
-            let filled = 0;
-            if (isJsonObject(result)) {
-                const messages = result.messages;
-                if (Array.isArray(messages)) {
-                    // onPullResult 已在 call() 拦截器中调用，此处不再重复
-                    const pushed = this._pushedSeqs.get(ns);
-                    for (const msg of messages) {
-                        if (isJsonObject(msg)) {
-                            const s = msg.seq;
-                            if (pushed && s !== undefined && s !== null && pushed.has(s))
-                                continue;
-                            if (s !== undefined && s !== null) {
-                                await this._publishPulledMessage('message.received', ns, s, msg);
-                            }
-                            else {
-                                await this._publishAppEvent('message.received', msg);
-                            }
-                            filled += 1;
-                        }
-                    }
-                    this._prunePushedSeqs(ns);
-                }
+            const messages = await this._withBackgroundRpc(() => this.pullV2(afterSeq, 50, { skipAutoAck: true, gateLocked: true }));
+            filled = messages.length;
+            this._prunePushedSeqs(ns);
+            if (this._seqTracker.getContiguousSeq(ns) !== afterSeq) {
+                await this._drainOrderedMessages(ns, undefined, true);
+                this._saveSeqTrackerState();
+            }
+            const contig = this._seqTracker.getContiguousSeq(ns);
+            if (contig > 0 && contig !== afterSeq) {
+                await this._withBackgroundRpc(() => this.ackV2(contig));
             }
             this._clientLog.debug(`P2P message gap fill done: after_seq=${afterSeq}, filled=${filled}`);
         }
@@ -1274,6 +1976,10 @@ export class AUNClient {
         }
         finally {
             this._gapFillDone.delete(dedupKey);
+            this._releasePullGate(ns, token);
+            if (filled > 0 && this._seqTracker.getContiguousSeq(ns) > afterSeq) {
+                void this._fillP2pGap();
+            }
         }
     }
     /** 只按硬上限裁剪 published guard，不能按 contiguousSeq 清理。 */
@@ -1321,10 +2027,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;
@@ -1334,10 +2040,11 @@ export class AUNClient {
             return payload;
         return this._attachCurrentInstanceContext(payload);
     }
-    async _publishAppEvent(event, payload) {
+    _publishAppEvent(event, payload, source = 'direct') {
         if ((event === 'message.received' || event === 'group.message_created') && isJsonObject(payload)) {
             this._maybeAppendEchoTraceReceive(payload);
         }
+        this._logAppMessagePublish(event, payload, source);
         // 注入本地/远端 agent.md etag，让应用层判断版本一致性；失败不影响业务。
         if (isJsonObject(payload)) {
             try {
@@ -1357,7 +2064,7 @@ export class AUNClient {
                 this._clientLog.debug(`agent_md etag inject skipped: ${err instanceof Error ? err.message : String(err)}`);
             }
         }
-        await this._dispatcher.publish(event, this._normalizePublishedMessagePayload(event, payload));
+        return this._dispatcher.publishSyncAware(event, this._normalizePublishedMessagePayload(event, payload));
     }
     _echoTimestamp() {
         const now = new Date();
@@ -1383,6 +2090,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;
@@ -1393,34 +2112,379 @@ export class AUNClient {
         const trace = `${this._echoTimestamp()} [AUN-SDK.receive] aid=${this._aid ?? '-'} conn_uptime=${uptime}s`;
         msg.payload = { ...payload, text: payload.text + '\n' + trace };
     }
+    _debugJson(value) {
+        const seen = new WeakSet();
+        try {
+            return JSON.stringify(value, (_key, item) => {
+                if (typeof item === 'bigint')
+                    return item.toString();
+                if (item instanceof Uint8Array) {
+                    return {
+                        _type: item.constructor.name,
+                        len: item.byteLength,
+                        base64: Buffer.from(item).toString('base64'),
+                    };
+                }
+                if (item && typeof item === 'object') {
+                    if (seen.has(item))
+                        return '[Circular]';
+                    seen.add(item);
+                }
+                return item;
+            });
+        }
+        catch {
+            return String(value);
+        }
+    }
+    _messagePayloadForDebug(message) {
+        if (!isJsonObject(message))
+            return message;
+        const msg = message;
+        if ('payload' in msg)
+            return msg.payload;
+        if ('content' in msg)
+            return msg.content;
+        if (typeof msg.envelope_json === 'string' && msg.envelope_json) {
+            try {
+                return JSON.parse(msg.envelope_json);
+            }
+            catch {
+                return msg.envelope_json;
+            }
+        }
+        if (isJsonObject(msg.legacy_v1)) {
+            const legacy = msg.legacy_v1;
+            if ('payload' in legacy)
+                return legacy.payload;
+            if ('content' in legacy)
+                return legacy.content;
+        }
+        return null;
+    }
+    _messageEnvelopeFieldsForDebug(message) {
+        if (!isJsonObject(message)) {
+            return { value_type: typeof message };
+        }
+        const msg = message;
+        const keys = [
+            'message_id', 'id', 'from', 'from_aid', 'sender_aid', 'to', 'to_aid',
+            'group_id', 'seq', 'msg_seq', 'type', 'version', 'timestamp', 't_server',
+            'device_id', 'slot_id', 'encrypted', 'dispatch_mode', 'dispatch',
+            'e2ee', 'headers', 'protected_headers', 'context', 'status',
+            '_decrypt_error', '_decrypt_stage',
+        ];
+        const out = {};
+        for (const key of keys) {
+            if (Object.prototype.hasOwnProperty.call(msg, key))
+                out[key] = msg[key];
+        }
+        return out;
+    }
+    _logMessageDebug(stage, source, event, message, opts = {}) {
+        // 关键消息链路诊断日志长期保留在代码中；是否输出由 logger 的 debug/level 控制。
+        const record = {
+            stage,
+            source,
+            event,
+            envelope: this._messageEnvelopeFieldsForDebug(message),
+            payload: opts.payloadOverride !== undefined ? opts.payloadOverride : this._messagePayloadForDebug(message),
+        };
+        if (opts.extra)
+            record.extra = opts.extra;
+        this._clientLog.debug(`message.debug ${this._debugJson(record)}`);
+    }
+    _logAppMessagePublish(event, payload, source) {
+        if (!['message.received', 'message.undecryptable', 'group.message_created', 'group.message_undecryptable'].includes(event)) {
+            return;
+        }
+        this._logMessageDebug('publish', source, event, payload);
+    }
     _messageTargetsCurrentInstance(message) {
         if (!isJsonObject(message))
             return true;
-        const targetDeviceId = String(message.device_id ?? '').trim();
-        if (targetDeviceId && this._deviceId && targetDeviceId !== this._deviceId) {
+        if ('device_id' in message) {
+            const targetDeviceId = String(message.device_id ?? '').trim();
+            if (targetDeviceId !== this._deviceId) {
+                return false;
+            }
+        }
+        if ('slot_id' in message) {
+            const targetSlotId = String(message.slot_id ?? '').trim();
+            if (targetSlotId !== this._slotId) {
+                return false;
+            }
+        }
+        return true;
+    }
+    _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;
+    }
+    _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') && String(params.group_id ?? '').trim()) {
+            return `group:${String(params.group_id ?? '').trim()}`;
+        }
+        if (method === 'group.pull_events' && String(params.group_id ?? '').trim()) {
+            return `group_event:${String(params.group_id ?? '').trim()}`;
+        }
+        return '';
+    }
+    _isPullResponseProcessing(key) {
+        if (!key)
             return false;
+        return (this._pullResponseKeys.get(key) ?? 0) > 0;
+    }
+    _emptyPullResultForCall(method) {
+        if (method === 'group.pull_events')
+            return { events: [], count: 0 };
+        if (method === 'message.pull' || method === 'message.v2.pull' || method === 'group.pull' || method === 'group.v2.pull') {
+            return { messages: [], count: 0 };
+        }
+        return {};
+    }
+    _withPullResponseProcessing(key, fn) {
+        if (!key)
+            return fn();
+        this._pullResponseKeys.set(key, (this._pullResponseKeys.get(key) ?? 0) + 1);
+        const release = () => {
+            const next = (this._pullResponseKeys.get(key) ?? 1) - 1;
+            if (next <= 0) {
+                this._pullResponseKeys.delete(key);
+            }
+            else {
+                this._pullResponseKeys.set(key, next);
+            }
+        };
+        try {
+            const result = fn();
+            if (isPromiseLike(result)) {
+                return Promise.resolve(result).finally(release);
+            }
+            release();
+            return result;
+        }
+        catch (exc) {
+            release();
+            throw exc;
+        }
+    }
+    _pullResultCount(result) {
+        if (Array.isArray(result))
+            return result.length;
+        if (!isJsonObject(result))
+            return 0;
+        const obj = result;
+        const rawCount = Number(obj.raw_count ?? 0);
+        if (Number.isFinite(rawCount) && rawCount > 0)
+            return rawCount;
+        if (Array.isArray(obj.messages))
+            return obj.messages.length;
+        if (Array.isArray(obj.events))
+            return obj.events.length;
+        return 0;
+    }
+    _nextPullParams(method, params) {
+        const next = { ...params };
+        delete next._pull_gate_locked;
+        if (method === 'message.pull' || method === 'message.v2.pull') {
+            if (!this._aid)
+                return null;
+            next.after_seq = this._seqTracker.getContiguousSeq(`p2p:${this._aid}`);
+            return next;
+        }
+        if (method === 'group.pull' || method === 'group.v2.pull') {
+            const groupId = normalizeGroupId(String(next.group_id ?? '').trim()) || String(next.group_id ?? '').trim();
+            if (!groupId)
+                return null;
+            next.group_id = groupId;
+            next.after_seq = this._seqTracker.getContiguousSeq(`group:${groupId}`);
+            delete next.after_message_seq;
+            return next;
+        }
+        if (method === 'group.pull_events') {
+            const groupId = normalizeGroupId(String(next.group_id ?? '').trim()) || String(next.group_id ?? '').trim();
+            if (!groupId)
+                return null;
+            next.group_id = groupId;
+            next.after_event_seq = this._seqTracker.getContiguousSeq(`group_event:${groupId}`);
+            return next;
+        }
+        return null;
+    }
+    _pullRequestAfter(method, params) {
+        if (method === 'message.pull' || method === 'message.v2.pull')
+            return Number(params.after_seq ?? 0) || 0;
+        if (method === 'group.pull' || method === 'group.v2.pull')
+            return Number(params.after_seq ?? params.after_message_seq ?? 0) || 0;
+        if (method === 'group.pull_events')
+            return Number(params.after_event_seq ?? 0) || 0;
+        return 0;
+    }
+    _pullRetentionFloor(result, topLevelKey, cursorKey) {
+        const values = [Number(result[topLevelKey] ?? 0)];
+        const cursor = isJsonObject(result.cursor) ? result.cursor : null;
+        if (cursor) {
+            values.push(Number(cursor[cursorKey] ?? 0));
+            values.push(Number(cursor.retention_floor_seq ?? 0));
+        }
+        return Math.max(0, ...values.filter((value) => Number.isFinite(value)));
+    }
+    _schedulePullFollowup(method, params, result) {
+        if (method === 'message.pull')
+            method = 'message.v2.pull';
+        else if (method === 'group.pull')
+            method = 'group.v2.pull';
+        if (this._pullResultCount(result) <= 0)
+            return;
+        const next = this._nextPullParams(method, params);
+        if (!next)
+            return;
+        if (this._pullRequestAfter(method, next) <= this._pullRequestAfter(method, params))
+            return;
+        void (async () => {
+            try {
+                await this._withBackgroundRpc(async () => {
+                    if (method === 'message.pull' || method === 'message.v2.pull') {
+                        await this.pullV2(Number(next.after_seq ?? 0) || 0, Number(next.limit ?? 50) || 50);
+                        return;
+                    }
+                    if (method === 'group.pull' || method === 'group.v2.pull') {
+                        const groupId = String(next.group_id ?? '').trim();
+                        if (!groupId)
+                            return;
+                        await this.pullGroupV2(groupId, Number(next.after_seq ?? next.after_message_seq ?? 0) || 0, Number(next.limit ?? 50) || 50);
+                        return;
+                    }
+                    await this.call(method, next);
+                });
+            }
+            catch (exc) {
+                this._clientLog.debug(`pull follow-up skipped/failed: method=${method} err=${formatCaughtError(exc)}`);
+            }
+        })();
+    }
+    async _withBackgroundRpc(operation) {
+        this._backgroundRpcDepth += 1;
+        try {
+            return await operation();
         }
-        const targetSlotId = String(message.slot_id ?? '').trim();
-        if (targetSlotId && this._slotId && targetSlotId !== this._slotId) {
+        finally {
+            this._backgroundRpcDepth = Math.max(0, this._backgroundRpcDepth - 1);
+        }
+    }
+    async _runPullSerialized(key, operation) {
+        if (key && this._isPullResponseProcessing(key)) {
+            this._clientLog.debug(`pull skipped while processing pull response: key=${key}`);
+            return [];
+        }
+        let token = this._tryAcquirePullGate(key);
+        if (token === null) {
+            // 显式 pull 可能撞上 push/gap-fill 的后台 pull。这里不并行发第二个 pull，
+            // 也不把后台 in-flight 暴露成业务错误；短等待 gate 释放后再进入连接级 RPC queue。
+            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 this._withBackgroundRpc(operation);
+        }
+        finally {
+            this._releasePullGate(key, token);
+        }
+    }
+    async _tryRunBackgroundPull(key, operation, followupOnMessages = false) {
+        if (key && this._isPullResponseProcessing(key))
+            return false;
+        const token = this._tryAcquirePullGate(key);
+        if (token === null)
             return false;
+        let count = 0;
+        try {
+            count = await this._withBackgroundRpc(operation);
+        }
+        finally {
+            this._releasePullGate(key, token);
+        }
+        if (followupOnMessages && count > 0) {
+            // 后台续拉是 fire-and-forget；关闭连接时 transport 会拒绝排队 RPC，
+            // 这里必须本地收口，避免测试/宿主进程看到未处理的 Promise rejection。
+            void this._tryRunBackgroundPull(key, operation, true).catch((exc) => {
+                this._clientLog.debug(`background pull follow-up skipped/failed: key=${key} err=${formatCaughtError(exc)}`);
+            });
         }
         return true;
     }
-    async _drainOrderedMessages(ns, beforeSeq) {
+    async _drainOrderedMessages(ns, beforeSeq, pullResponse = false) {
         const queue = this._pendingOrderedMsgs.get(ns);
         if (!queue || queue.size === 0)
             return;
-        const contig = this._seqTracker.getContiguousSeq(ns);
-        const ready = [...queue.keys()]
-            .filter((seq) => seq <= contig && (beforeSeq === undefined || seq < beforeSeq))
-            .sort((a, b) => a - b);
-        for (const seq of ready) {
+        while (true) {
+            const contig = this._seqTracker.getContiguousSeq(ns);
+            const ready = [...queue.keys()]
+                .filter((seq) => seq <= contig && (beforeSeq === undefined || seq < beforeSeq))
+                .sort((a, b) => a - b);
+            let seq = ready[0];
+            if (seq === undefined) {
+                const nextSeq = contig + 1;
+                if (beforeSeq !== undefined && nextSeq >= beforeSeq)
+                    break;
+                if (!queue.has(nextSeq))
+                    break;
+                seq = nextSeq;
+            }
             const item = queue.get(seq);
             queue.delete(seq);
-            if (!item || this._pushedSeqs.get(ns)?.has(seq))
+            if (!item)
+                continue;
+            if (this._pushedSeqs.get(ns)?.has(seq)) {
+                this._clientLog.debug(`publish ordered drain skipped duplicate: ns=${ns}, seq=${seq}, event=${item.event}`);
+                this._markOrderedSeqDelivered(ns, seq);
                 continue;
-            await this._publishAppEvent(item.event, item.payload);
+            }
+            if (pullResponse) {
+                const published = this._withPullResponseProcessing(ns, () => this._publishAppEvent(item.event, item.payload, 'ordered-drain'));
+                if (isPromiseLike(published))
+                    await published;
+            }
+            else {
+                const published = this._publishAppEvent(item.event, item.payload, 'ordered-drain');
+                if (isPromiseLike(published))
+                    await published;
+            }
             this._markPublishedSeq(ns, seq);
+            this._markOrderedSeqDelivered(ns, seq);
+            this._clientLog.debug(`publish ordered drain delivered: ns=${ns}, seq=${seq}, event=${item.event}`);
         }
         if (queue.size === 0)
             this._pendingOrderedMsgs.delete(ns);
@@ -1428,10 +2492,14 @@ export class AUNClient {
     async _publishOrderedMessage(event, ns, seq, payload) {
         const seqNum = Number(seq);
         if (!Number.isFinite(seqNum) || !Number.isInteger(seqNum) || seqNum <= 0) {
-            await this._publishAppEvent(event, payload);
+            this._clientLog.debug(`publish ordered direct(no-seq): event=${event}, ns=${ns || '<none>'}, seq=${String(seq)}`);
+            const published = this._publishAppEvent(event, payload, 'ordered');
+            if (isPromiseLike(published))
+                await published;
             return true;
         }
         if (this._pushedSeqs.get(ns)?.has(seqNum)) {
+            this._clientLog.debug(`publish ordered skipped duplicate: event=${event}, ns=${ns}, seq=${seqNum}`);
             const queue = this._pendingOrderedMsgs.get(ns);
             queue?.delete(seqNum);
             if (queue && queue.size === 0)
@@ -1439,30 +2507,52 @@ export class AUNClient {
             return false;
         }
         const contig = this._seqTracker.getContiguousSeq(ns);
-        if (seqNum > contig) {
+        if (seqNum <= contig) {
+            this._clientLog.debug(`publish ordered stale covered: event=${event}, ns=${ns}, seq=${seqNum}, contiguous=${contig}`);
+            const queue = this._pendingOrderedMsgs.get(ns);
+            queue?.delete(seqNum);
+            if (queue && queue.size === 0)
+                this._pendingOrderedMsgs.delete(ns);
+            return false;
+        }
+        if (seqNum !== contig + 1) {
+            this._clientLog.debug(`publish ordered enqueue(gap): event=${event}, ns=${ns}, seq=${seqNum}, contiguous=${contig}`);
             this._enqueueOrderedMessage(ns, event, seqNum, payload);
             return false;
         }
         await this._drainOrderedMessages(ns, seqNum);
-        if (this._pushedSeqs.get(ns)?.has(seqNum))
+        if (this._pushedSeqs.get(ns)?.has(seqNum)) {
+            this._clientLog.debug(`publish ordered skipped after-drain duplicate: event=${event}, ns=${ns}, seq=${seqNum}`);
             return false;
+        }
         const queue = this._pendingOrderedMsgs.get(ns);
         queue?.delete(seqNum);
         if (queue && queue.size === 0)
             this._pendingOrderedMsgs.delete(ns);
-        await this._publishAppEvent(event, payload);
+        const published = this._publishAppEvent(event, payload, 'ordered');
+        if (isPromiseLike(published))
+            await published;
         this._markPublishedSeq(ns, seqNum);
+        this._markOrderedSeqDelivered(ns, seqNum);
+        this._clientLog.debug(`publish ordered delivered: event=${event}, ns=${ns}, seq=${seqNum}`);
         await this._drainOrderedMessages(ns);
         return true;
     }
     async _publishPulledMessage(event, ns, seq, payload) {
+        // Pull/gap-fill 批次是服务端对 after_seq 的可用结果集，可能跨过永久空洞。
+        // 这里只能做 namespace+seq 去重并按返回顺序发布，不能套用 push 路径的
+        // seq == contiguous_seq + 1 门控，否则会把空洞后的可用消息错误卡住。
         const seqNum = Number(seq);
         if (!Number.isFinite(seqNum) || !Number.isInteger(seqNum) || seqNum <= 0 || !ns) {
-            await this._publishAppEvent(event, payload);
+            this._clientLog.debug(`publish pulled direct(no-seq): event=${event}, ns=${ns || '<none>'}, seq=${String(seq)}`);
+            const published = this._withPullResponseProcessing(ns, () => this._publishAppEvent(event, payload, 'pull'));
+            if (isPromiseLike(published))
+                await published;
             return true;
         }
         const queue = this._pendingOrderedMsgs.get(ns);
         if (this._pushedSeqs.get(ns)?.has(seqNum)) {
+            this._clientLog.debug(`publish pulled skipped duplicate: event=${event}, ns=${ns}, seq=${seqNum}`);
             queue?.delete(seqNum);
             if (queue && queue.size === 0)
                 this._pendingOrderedMsgs.delete(ns);
@@ -1471,70 +2561,126 @@ export class AUNClient {
         queue?.delete(seqNum);
         if (queue && queue.size === 0)
             this._pendingOrderedMsgs.delete(ns);
-        await this._publishAppEvent(event, payload);
+        const published = this._withPullResponseProcessing(ns, () => this._publishAppEvent(event, payload, 'pull'));
+        if (isPromiseLike(published))
+            await published;
         this._markPublishedSeq(ns, seqNum);
+        this._markPulledSeqDelivered(ns, seqNum);
+        await this._drainOrderedMessages(ns, undefined, true);
+        this._clientLog.debug(`publish pulled delivered: event=${event}, ns=${ns}, seq=${seqNum}`);
         return true;
     }
+    _markPulledSeqDelivered(ns, seq) {
+        // Pull 批次是 after_seq 之后服务端当前可用的结果集，可能跨过永久空洞。
+        // 这里仅在应用层发布返回后推进已交付游标，不能改成 push 的相邻 seq 门控。
+        const seqNum = Number(seq);
+        if (!ns || !Number.isFinite(seqNum) || !Number.isInteger(seqNum) || seqNum <= 0)
+            return false;
+        const before = this._seqTracker.getContiguousSeq(ns);
+        this._seqTracker.forceContiguousSeq(ns, seqNum);
+        return this._seqTracker.getContiguousSeq(ns) !== before;
+    }
+    _markOrderedSeqDelivered(ns, seq) {
+        if (!ns || !Number.isFinite(seq) || !Number.isInteger(seq) || seq <= 0)
+            return false;
+        const before = this._seqTracker.getContiguousSeq(ns);
+        this._seqTracker.onMessageSeq(ns, seq);
+        return this._seqTracker.getContiguousSeq(ns) !== before;
+    }
     /** 后台补齐群事件空洞 */
     async _fillGroupEventGap(groupId) {
+        groupId = normalizeGroupId(groupId) || String(groupId ?? '').trim();
+        if (!groupId)
+            return;
         const ns = `group_event:${groupId}`;
         const afterSeq = this._seqTracker.getContiguousSeq(ns);
         // 去重：同一 (group_evt:id:after_seq) 只补一次
         const dedupKey = `group_evt:${groupId}:${afterSeq}`;
         if (this._gapFillDone.has(dedupKey))
             return;
+        const token = this._tryAcquirePullGate(ns);
+        if (token === null) {
+            this._clientLog.debug(`group event gap fill skipped: pull in-flight group=${groupId}`);
+            return;
+        }
         this._gapFillDone.set(dedupKey, Date.now());
-        this._clientLog.debug(`group event gap fill start: group=${groupId}, after_seq=${afterSeq}`);
+        let filled = 0;
         try {
-            const result = await this.call('group.pull_events', {
-                group_id: groupId,
-                after_event_seq: afterSeq,
-                device_id: this._deviceId,
-                limit: 50,
-            });
-            let filled = 0;
-            if (isJsonObject(result)) {
+            let nextAfterSeq = afterSeq;
+            const maxPages = 100;
+            let pageCount = 0;
+            while (pageCount < maxPages) {
+                pageCount += 1;
+                this._clientLog.debug(`group event gap fill start: group=${groupId}, after_seq=${nextAfterSeq}`);
+                const result = await this.call('group.pull_events', {
+                    group_id: groupId,
+                    after_event_seq: nextAfterSeq,
+                    device_id: this._deviceId,
+                    limit: 50,
+                    _pull_gate_locked: true,
+                });
+                if (!isJsonObject(result))
+                    return;
                 const events = result.events;
-                if (Array.isArray(events)) {
-                    this._seqTracker.onPullResult(ns, events.filter(isJsonObject));
-                    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.debug(`group event auto-ack failed: group=${groupId} ${formatCaughtError(e)}`); });
+                if (!Array.isArray(events))
+                    return;
+                const pageContigBefore = this._seqTracker.getContiguousSeq(ns);
+                const eventObjects = events.filter(isJsonObject);
+                const retentionFloor = this._pullRetentionFloor(result, 'retention_floor_event_seq', 'retention_floor_event_seq');
+                if (retentionFloor > 0) {
+                    const contigBeforeFloor = this._seqTracker.getContiguousSeq(ns);
+                    if (contigBeforeFloor < retentionFloor) {
+                        this._clientLog.info(`group.pull_events retention-floor advance: ns=${ns} contiguous=${contigBeforeFloor} -> retention_floor=${retentionFloor}`);
+                        this._seqTracker.forceContiguousSeq(ns, retentionFloor);
                     }
-                    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') {
+                }
+                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') {
+                        // 验签：有 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._verifyEventSignatureAsync(evt, cs);
                             }
-                            // group.changed 或缺失/其他 → 发布到 group.changed（向后兼容）
-                            await this._dispatcher.publish('group.changed', evt);
-                            filled += 1;
                         }
+                        // group.changed 或缺失/其他 → 发布到 group.changed（向后兼容）
+                        await this._dispatcher.publish('group.changed', evt);
+                    }
+                    if (Number.isFinite(eventSeq) && eventSeq > 0) {
+                        this._markPulledSeqDelivered(ns, eventSeq);
                     }
+                    filled += 1;
+                }
+                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,
+                    }, undefined, undefined, true).catch((e) => { this._clientLog.debug(`group event auto-ack failed: group=${groupId} ${formatCaughtError(e)}`); });
+                }
+                // pull_events 与其它 pull 一样：一次后台任务只消费一个批次。
+                // 非空批次返回后由 pull gate 的 fire-and-forget follow-up 重新排队，直到空批停止。
+                break;
+            }
+            if (pageCount >= maxPages) {
+                this._clientLog.warn(`group event gap fill reached max_pages=${maxPages} group=${groupId} after_seq=${nextAfterSeq}`);
             }
             this._clientLog.debug(`group event gap fill done: group=${groupId}, after_seq=${afterSeq}, filled=${filled}`);
         }
@@ -1543,6 +2689,10 @@ export class AUNClient {
         }
         finally {
             this._gapFillDone.delete(dedupKey);
+            this._releasePullGate(ns, token);
+            if (filled > 0 && this._seqTracker.getContiguousSeq(ns) > afterSeq) {
+                void this._fillGroupEventGap(groupId);
+            }
         }
     }
     _extractGroupIdFromResult(result) {
@@ -1567,28 +2717,45 @@ export class AUNClient {
                 // 验签：有 client_signature 就验，没有默认安全（H20: 严格 boolean）
                 const cs = d.client_signature;
                 if (cs && isJsonObject(cs)) {
-                    d._verified = await this._verifyEventSignatureAsync(d, cs);
+                    if (this._shouldSkipEventSignature(d)) {
+                        delete d.client_signature;
+                    }
+                    else {
+                        d._verified = await this._verifyEventSignatureAsync(d, cs);
+                    }
                 }
                 await this._dispatcher.publish('group.changed', d);
                 // V2-only：成员/设备变化会影响 group.v2.bootstrap 的设备集与 state commitment。
                 if (groupId) {
                     this._v2BootstrapCache.delete(`group:${groupId}`);
                 }
-                if (groupId && action === 'upsert' && this._v2Session) {
+                const membershipActions = new Set([
+                    'member_added', 'member_left', 'member_removed', 'role_changed',
+                    'owner_transferred', 'joined', 'join_approved', 'invite_code_used',
+                ]);
+                if (groupId && this._v2Session && (action === 'upsert' || membershipActions.has(action))) {
                     this._safeAsync(this._v2AutoProposeState(groupId, { leaderDelay: true }));
                 }
                 // Group SPK 编排：成员变更触发注册/轮换
                 if (this._v2Session && groupId) {
-                    const callFn = async (method, params) => this.call(method, params);
-                    if (action === 'joined' || action === 'join_approved') {
-                        this._v2Session.ensureGroupRegistered?.(groupId, callFn)?.catch(exc => {
-                            this._clientLog.debug(`group SPK registration failed (non-fatal): group=${groupId} action=${action} err=${formatCaughtError(exc)}`);
-                        });
-                    }
-                    else if (['member_added', 'member_left', 'member_removed', 'role_changed', 'owner_transferred'].includes(action)) {
-                        this._v2Session.rotateGroupSPK?.(groupId, callFn)?.catch(exc => {
-                            this._clientLog.debug(`group SPK rotation failed (non-fatal): group=${groupId} action=${action} err=${formatCaughtError(exc)}`);
-                        });
+                    if (membershipActions.has(action)) {
+                        const callFn = async (method, params) => this.call(method, params);
+                        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=${formatCaughtError(exc)}`);
+                            });
+                        }
+                        else {
+                            this._v2Session.rotateGroupSPK?.(groupId, callFn)?.catch(exc => {
+                                this._clientLog.debug(`group SPK rotation failed (non-fatal): group=${groupId} action=${action} err=${formatCaughtError(exc)}`);
+                            });
+                        }
                     }
                 }
                 // event_seq 空洞检测：持久化后的 group.changed 会携带 event_seq。
@@ -1609,7 +2776,7 @@ export class AUNClient {
                             event_seq: contig,
                             device_id: this._deviceId,
                             slot_id: this._slotId,
-                        }).catch((e) => { this._clientLog.debug(`group event push auto-ack failed: group=${groupId} ${formatCaughtError(e)}`); });
+                        }, undefined, undefined, true).catch((e) => { this._clientLog.debug(`group event push auto-ack failed: group=${groupId} ${formatCaughtError(e)}`); });
                     }
                 }
                 // 仅在真实 event gap 时才触发补拉（补洞回来的事件不再触发新补洞）
@@ -1655,12 +2822,17 @@ export class AUNClient {
             // 提交者签名验证（兼容旧版：无签名时继续）
             const cs = d.client_signature;
             if (cs && isJsonObject(cs)) {
-                const verified = await this._verifyEventSignatureAsync(d, cs);
-                if (verified === false) {
-                    this._clientLog.warn(`state_committed committer signature verification failed group=${groupId}`);
-                    return;
+                if (this._shouldSkipEventSignature(d)) {
+                    delete d.client_signature;
+                }
+                else {
+                    const verified = await this._verifyEventSignatureAsync(d, cs);
+                    if (verified === false) {
+                        this._clientLog.warn(`state_committed committer signature verification failed group=${groupId}`);
+                        return;
+                    }
+                    d._verified = verified;
                 }
-                d._verified = verified;
             }
             const stateVersion = Number(d.state_version ?? 0);
             const stateHash = String(d.state_hash ?? '').trim();
@@ -1810,12 +2982,86 @@ export class AUNClient {
             return false;
         }
     }
-    /**
-     * 获取对方证书（带缓存 + 完整 PKI 验证）。  /**
-     * 获取对方证书（带缓存 + 完整 PKI 验证）。
-     * 跨域时自动路由到 peer 所在域的 Gateway。
-     */
-    async _fetchPeerCert(aid, certFingerprint) {
+    async _validateAndCachePeerCert(opts) {
+        const aid = String(opts.aid ?? '').trim();
+        const certPem = String(opts.certPem ?? '').trim();
+        const certFingerprint = String(opts.certFingerprint ?? '').trim() || undefined;
+        if (!aid)
+            throw new ValidationError('peer aid is required for cert validation');
+        if (!certPem)
+            throw new ValidationError(`peer cert is empty for ${aid}`);
+        const gatewayUrl = this._gatewayUrl;
+        if (!gatewayUrl) {
+            throw new ValidationError('gateway url unavailable for e2ee cert validation');
+        }
+        const peerGatewayUrl = AUNClient._resolvePeerGatewayUrl(gatewayUrl, aid);
+        const x509Cert = new crypto.X509Certificate(certPem);
+        // H7: 严格校验指纹（DER SHA-256 或 SPKI SHA-256 任一匹配即可）
+        if (certFingerprint) {
+            const expectedFP = certFingerprint.toLowerCase();
+            if (!expectedFP.startsWith('sha256:')) {
+                throw new ValidationError(`unsupported cert_fingerprint format for ${aid}: ${expectedFP.slice(0, 24)}`);
+            }
+            const expectedHex = expectedFP.slice('sha256:'.length);
+            const derHex = x509Cert.fingerprint256.replace(/:/g, '').toLowerCase();
+            let spkiHex = '';
+            try {
+                const spkiDer = x509Cert.publicKey.export({ type: 'spki', format: 'der' });
+                spkiHex = crypto.createHash('sha256').update(spkiDer).digest('hex');
+            }
+            catch {
+                spkiHex = '';
+            }
+            if (expectedHex !== derHex && (!spkiHex || expectedHex !== spkiHex)) {
+                throw new ValidationError(`peer cert fingerprint mismatch for ${aid}: expected=${expectedFP.slice(0, 24)}...`);
+            }
+        }
+        let cachedBootstrapChain = false;
+        const caChainPems = opts.caChainPems ?? [];
+        if (caChainPems.length > 0) {
+            try {
+                this._auth.cacheGatewayCaChain(peerGatewayUrl, caChainPems, aid);
+                cachedBootstrapChain = true;
+            }
+            catch (exc) {
+                this._clientLog.debug(`bootstrap CA chain cache skipped: peer=${aid}, source=${opts.source ?? 'unknown'}, err=${formatCaughtError(exc)}`);
+            }
+        }
+        try {
+            await this._auth.verifyPeerCertificate(peerGatewayUrl, certPem, aid);
+        }
+        catch (exc) {
+            if (cachedBootstrapChain) {
+                this._auth.discardGatewayCaChain(peerGatewayUrl, aid);
+            }
+            throw new ValidationError(`peer cert verification failed for ${aid}: ${exc instanceof Error ? exc.message : String(exc)}`);
+        }
+        const nowSec = Date.now() / 1000;
+        const entry = {
+            certPem,
+            validatedAt: nowSec,
+            refreshAfter: nowSec + PEER_CERT_CACHE_TTL,
+        };
+        const cacheKey = AUNClient._certCacheKey(aid, certFingerprint);
+        this._certCache.set(cacheKey, entry);
+        const bareKey = AUNClient._certCacheKey(aid);
+        if (bareKey !== cacheKey)
+            this._certCache.set(bareKey, entry);
+        if (!certFingerprint) {
+            const actualFp = `sha256:${x509Cert.fingerprint256.replace(/:/g, '').toLowerCase()}`;
+            this._certCache.set(AUNClient._certCacheKey(aid, actualFp), entry);
+        }
+        try {
+            // peer 证书只存版本目录，不覆盖 cert.pem
+            this._keystore.saveCert(aid, certPem, certFingerprint, { makeActive: false });
+        }
+        catch (exc) {
+            this._clientLog.error(`failed to write cert to keystore (aid=${aid}, fp=${certFingerprint ?? ''}): ${formatCaughtError(exc)}`, exc instanceof Error ? exc : undefined);
+        }
+        return certPem;
+    }
+    /** 获取对方证书（带缓存 + 完整 PKI 验证），跨域时自动路由到 peer 所在域。 */
+    async _fetchPeerCert(aid, certFingerprint, timeoutMs = 30_000) {
         const tStart = Date.now();
         this._clientLog.debug(`_fetchPeerCert enter: aid=${aid}, fp=${certFingerprint ?? ''}`);
         try {
@@ -1830,75 +3076,118 @@ export class AUNClient {
             if (!gatewayUrl) {
                 throw new ValidationError('gateway url unavailable for e2ee cert fetch');
             }
-            // 跨域时用 peer 所在域的 Gateway URL
             const peerGatewayUrl = AUNClient._resolvePeerGatewayUrl(gatewayUrl, aid);
             let certPem;
             try {
-                const certUrl = AUNClient._buildCertUrl(peerGatewayUrl, aid, certFingerprint);
-                certPem = await _httpGetText(certUrl, this._configModel.verifySsl);
+                certPem = await _httpGetText(AUNClient._buildCertUrl(peerGatewayUrl, aid, certFingerprint), this._configModel.verifySsl, timeoutMs);
             }
             catch (exc) {
-                if (!certFingerprint) {
+                if (!certFingerprint)
                     throw exc;
-                }
-                const fallbackCert = await _httpGetText(AUNClient._buildCertUrl(peerGatewayUrl, aid), this._configModel.verifySsl);
-                certPem = fallbackCert;
-            }
-            // H7: 严格校验指纹（DER SHA-256 或 SPKI SHA-256 任一匹配即可）
-            if (certFingerprint) {
-                const expectedFP = String(certFingerprint).trim().toLowerCase();
-                if (!expectedFP.startsWith('sha256:')) {
-                    throw new ValidationError(`unsupported cert_fingerprint format for ${aid}: ${expectedFP.slice(0, 24)}`);
-                }
-                const expectedHex = expectedFP.slice('sha256:'.length);
-                const x509Cert = new crypto.X509Certificate(certPem);
-                const derHex = x509Cert.fingerprint256.replace(/:/g, '').toLowerCase();
-                let spkiHex = '';
+                certPem = await _httpGetText(AUNClient._buildCertUrl(peerGatewayUrl, aid), this._configModel.verifySsl, timeoutMs);
+            }
+            const validated = await this._validateAndCachePeerCert({
+                aid,
+                certPem,
+                certFingerprint,
+                source: 'fetch',
+            });
+            this._clientLog.debug(`_fetchPeerCert exit: elapsed=${Date.now() - tStart}ms aid=${aid} (fetched)`);
+            return validated;
+        }
+        catch (err) {
+            this._clientLog.debug(`_fetchPeerCert exit (error): elapsed=${Date.now() - tStart}ms aid=${aid} err=${err instanceof Error ? err.message : String(err)}`);
+            throw err;
+        }
+    }
+    _bootstrapCaChain(material) {
+        let raw;
+        for (const key of ['ca_chain', 'ca_chain_pems', 'cert_chain', 'chain']) {
+            if (material[key] !== undefined && material[key] !== null) {
+                raw = material[key];
+                break;
+            }
+        }
+        if (!Array.isArray(raw))
+            return [];
+        const result = [];
+        for (const item of raw) {
+            let certType = '';
+            let certPem = '';
+            if (isJsonObject(item)) {
+                certType = String(item.cert_type ?? '').trim().toLowerCase();
+                if (certType === 'agent')
+                    continue;
+                certPem = String(item.cert_pem ?? item.cert ?? '').trim();
+            }
+            else {
+                certPem = String(item ?? '').trim();
+            }
+            if (!certPem)
+                continue;
+            if (!certType) {
                 try {
-                    const spkiDer = x509Cert.publicKey.export({ type: 'spki', format: 'der' });
-                    spkiHex = crypto.createHash('sha256').update(spkiDer).digest('hex');
+                    if (!new crypto.X509Certificate(certPem).ca)
+                        continue;
                 }
                 catch {
-                    spkiHex = '';
-                }
-                if (expectedHex !== derHex && (!spkiHex || expectedHex !== spkiHex)) {
-                    throw new ValidationError(`peer cert fingerprint mismatch for ${aid}: expected=${expectedFP.slice(0, 24)}...`);
+                    continue;
                 }
             }
-            // 完整 PKI 验证
-            try {
-                await this._auth.verifyPeerCertificate(peerGatewayUrl, certPem, aid);
-            }
-            catch (exc) {
-                throw new ValidationError(`peer cert verification failed for ${aid}: ${exc instanceof Error ? exc.message : String(exc)}`);
-            }
-            const nowSec = Date.now() / 1000;
-            this._certCache.set(cacheKey, {
-                certPem,
-                validatedAt: nowSec,
-                refreshAfter: nowSec + PEER_CERT_CACHE_TTL,
-            });
+            result.push(certPem);
+        }
+        return result;
+    }
+    async _primeBootstrapPeerCerts(bootstrap, peerAid) {
+        const certsRaw = bootstrap.certs;
+        if (!isJsonObject(certsRaw))
+            return;
+        const materials = certsRaw;
+        const expected = new Set();
+        const normalizedPeer = String(peerAid ?? '').trim();
+        if (normalizedPeer)
+            expected.add(normalizedPeer);
+        const audit = Array.isArray(bootstrap.audit_recipients) ? bootstrap.audit_recipients : [];
+        for (const dev of audit) {
+            if (!isJsonObject(dev))
+                continue;
+            const aid = String(dev.aid ?? '').trim();
+            if (aid)
+                expected.add(aid);
+        }
+        for (const aid of expected) {
+            if (aid === this._aid)
+                continue;
+            const material = materials[aid];
+            if (!isJsonObject(material))
+                continue;
+            const certPem = String(material.cert_pem ?? material.cert ?? '').trim();
+            if (!certPem)
+                continue;
+            const certFingerprint = String(material.cert_fingerprint ?? material.fingerprint ?? material.fp ?? '').trim() || undefined;
             try {
-                // peer 证书只存版本目录，不覆盖 cert.pem
-                this._keystore.saveCert(aid, certPem, certFingerprint, { makeActive: false });
+                await this._validateAndCachePeerCert({
+                    aid,
+                    certPem,
+                    certFingerprint,
+                    caChainPems: this._bootstrapCaChain(material),
+                    source: 'bootstrap',
+                });
             }
             catch (exc) {
-                this._clientLog.error(`failed to write cert to keystore (aid=${aid}, fp=${certFingerprint ?? ''}): ${formatCaughtError(exc)}`, exc instanceof Error ? exc : undefined);
+                this._clientLog.debug(`bootstrap peer cert material ignored: peer=${aid}, err=${formatCaughtError(exc)}`);
             }
-            this._clientLog.debug(`_fetchPeerCert exit: elapsed=${Date.now() - tStart}ms aid=${aid} (fetched)`);
-            return certPem;
-        }
-        catch (err) {
-            this._clientLog.debug(`_fetchPeerCert exit (error): elapsed=${Date.now() - tStart}ms aid=${aid} err=${err instanceof Error ? err.message : String(err)}`);
-            throw err;
         }
     }
     async _decryptGroupThoughts(result) {
+        this._clientLog.debug(`group.thought.get decrypt enter: found=${String(result.found ?? '')}, group=${String(result.group_id ?? '')}, sender=${String(result.sender_aid ?? '')}`);
         if (!result.found) {
+            this._clientLog.debug('group.thought.get decrypt exit: not found');
             return { ...result, thoughts: [] };
         }
         const items = Array.isArray(result.thoughts) ? result.thoughts.filter(isJsonObject) : [];
         if (items.length === 0) {
+            this._clientLog.debug('group.thought.get decrypt exit: empty thoughts');
             return { ...result, thoughts: [] };
         }
         const groupId = String(result.group_id ?? '');
@@ -1908,26 +3197,32 @@ export class AUNClient {
             const payload = isJsonObject(item.payload) ? item.payload : null;
             const thoughtId = String(item.thought_id ?? item.message_id ?? '');
             const fromAid = String(item.from ?? item.sender_aid ?? senderAid);
+            this._logMessageDebug('thought-get-raw', 'group.thought.get', 'group.thought.get', item, {
+                extra: { group_id: groupId, thought_id: thoughtId, from: fromAid },
+            });
             let decryptFailed = false;
             let decryptedPayload = payload ?? {};
             let e2ee;
             if (payload?.type === 'e2ee.group_encrypted' && String(payload.version ?? '') === 'v2') {
+                e2ee = this._v2E2eeMeta(payload);
                 const plain = await this._decryptV2EnvelopeForThought({ envelope: payload, fromAid });
                 if (plain === null) {
                     decryptFailed = true;
+                    this._clientLog.debug(`group.thought.get decrypt returned null: group=${groupId}, thought_id=${thoughtId}, from=${fromAid}`);
                 }
                 else {
                     decryptedPayload = plain;
-                    e2ee = {
-                        version: 'v2',
-                        suite: String(payload.suite ?? ''),
-                        encryption_mode: `v2_${String(payload.suite ?? 'unknown')}`,
-                        forward_secrecy: true,
-                    };
+                    this._logMessageDebug('thought-decrypt-ok', 'group.thought.get', 'group.thought.get', {
+                        group_id: groupId,
+                        thought_id: thoughtId,
+                        from: fromAid,
+                        payload: plain,
+                    });
                 }
             }
             else if (payload?.type === 'e2ee.group_encrypted') {
                 decryptFailed = true;
+                this._clientLog.debug(`group.thought.get unsupported encrypted payload: group=${groupId}, thought_id=${thoughtId}, type=${String(payload.type ?? '')}, version=${String(payload.version ?? '')}`);
             }
             const thought = {
                 thought_id: thoughtId,
@@ -1935,22 +3230,32 @@ export class AUNClient {
                 payload: decryptFailed ? (payload ?? {}) : decryptedPayload,
                 created_at: item.created_at,
             };
-            if (e2ee !== undefined)
+            if (e2ee !== undefined) {
                 thought.e2ee = e2ee;
+                if (isJsonObject(e2ee))
+                    this._attachV2EnvelopeMetadata(thought, e2ee);
+            }
             if (decryptFailed)
                 thought.decrypt_failed = true;
             if ('context' in item)
                 thought.context = item.context;
+            this._logMessageDebug(decryptFailed ? 'thought-decrypt-fail' : 'thought-result', 'group.thought.get', 'group.thought.get', thought, {
+                extra: { group_id: groupId, thought_id: thoughtId },
+            });
             thoughts.push(thought);
         }
+        this._clientLog.debug(`group.thought.get decrypt exit: group=${groupId}, total=${items.length}, returned=${thoughts.length}`);
         return { ...result, thoughts };
     }
     async _decryptMessageThoughts(result) {
+        this._clientLog.debug(`message.thought.get decrypt enter: found=${String(result.found ?? '')}, peer=${String(result.peer_aid ?? '')}, sender=${String(result.sender_aid ?? '')}`);
         if (!result.found) {
+            this._clientLog.debug('message.thought.get decrypt exit: not found');
             return { ...result, thoughts: [] };
         }
         const items = Array.isArray(result.thoughts) ? result.thoughts.filter(isJsonObject) : [];
         if (items.length === 0) {
+            this._clientLog.debug('message.thought.get decrypt exit: empty thoughts');
             return { ...result, thoughts: [] };
         }
         const senderAid = String(result.sender_aid ?? '');
@@ -1961,26 +3266,32 @@ export class AUNClient {
             const thoughtId = String(item.thought_id ?? item.message_id ?? '');
             const fromAid = String(item.from ?? senderAid);
             const toAid = String(item.to ?? peerAid);
+            this._logMessageDebug('thought-get-raw', 'message.thought.get', 'message.thought.get', item, {
+                extra: { thought_id: thoughtId, from: fromAid, to: toAid },
+            });
             let decryptFailed = false;
             let decryptedPayload = payload ?? {};
             let e2ee;
             if (payload?.type === 'e2ee.p2p_encrypted' && String(payload.version ?? '') === 'v2') {
+                e2ee = this._v2E2eeMeta(payload);
                 const plain = await this._decryptV2EnvelopeForThought({ envelope: payload, fromAid });
                 if (plain === null) {
                     decryptFailed = true;
+                    this._clientLog.debug(`message.thought.get decrypt returned null: thought_id=${thoughtId}, from=${fromAid}, to=${toAid}`);
                 }
                 else {
                     decryptedPayload = plain;
-                    e2ee = {
-                        version: 'v2',
-                        suite: String(payload.suite ?? ''),
-                        encryption_mode: `v2_${String(payload.suite ?? 'unknown')}`,
-                        forward_secrecy: true,
-                    };
+                    this._logMessageDebug('thought-decrypt-ok', 'message.thought.get', 'message.thought.get', {
+                        thought_id: thoughtId,
+                        from: fromAid,
+                        to: toAid,
+                        payload: plain,
+                    });
                 }
             }
             else if (payload?.type === 'e2ee.encrypted' || payload?.type === 'e2ee.p2p_encrypted') {
                 decryptFailed = true;
+                this._clientLog.debug(`message.thought.get unsupported encrypted payload: thought_id=${thoughtId}, type=${String(payload.type ?? '')}, version=${String(payload.version ?? '')}`);
             }
             const thought = {
                 thought_id: thoughtId,
@@ -1990,14 +3301,21 @@ export class AUNClient {
                 payload: decryptFailed ? (payload ?? {}) : decryptedPayload,
                 created_at: item.created_at,
             };
-            if (e2ee !== undefined)
+            if (e2ee !== undefined) {
                 thought.e2ee = e2ee;
+                if (isJsonObject(e2ee))
+                    this._attachV2EnvelopeMetadata(thought, e2ee);
+            }
             if (decryptFailed)
                 thought.decrypt_failed = true;
             if ('context' in item)
                 thought.context = item.context;
+            this._logMessageDebug(decryptFailed ? 'thought-decrypt-fail' : 'thought-result', 'message.thought.get', 'message.thought.get', thought, {
+                extra: { thought_id: thoughtId },
+            });
             thoughts.push(thought);
         }
+        this._clientLog.debug(`message.thought.get decrypt exit: total=${items.length}, returned=${thoughts.length}`);
         return { ...result, thoughts };
     }
     /** 从 keystore 恢复 SeqTracker 状态 */ /** 从 keystore 恢复 SeqTracker 状态 */
@@ -2102,6 +3420,8 @@ export class AUNClient {
         this._gapFillDone.clear();
         this._pushedSeqs.clear();
         this._pendingOrderedMsgs.clear();
+        this._v2SenderIKPending.clear();
+        this._v2SenderIKFetching.clear();
         this._groupSynced.clear();
     }
     _refreshSeqTrackerContext() {
@@ -2112,6 +3432,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;
     }
@@ -2152,6 +3474,43 @@ export class AUNClient {
             }).catch(() => { });
         }
     }
+    _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);
+                return;
+            }
+            const deleteSeq = this._keystore.deleteSeq;
+            if (seq <= 0 && typeof deleteSeq === 'function') {
+                deleteSeq.call(this._keystore, this._aid, this._deviceId, this._slotId, ns);
+                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;
+    }
     /** 记录 E2EE 自动编排错误 */
     _logE2eeError(stage, groupId, aid, exc) {
         try {
@@ -2276,7 +3635,7 @@ export class AUNClient {
             catch (exc) {
                 this._clientLog.warn(`V2 session init failed (non-fatal): ${formatCaughtError(exc)}`);
             }
-            // connect/reconnect 成功后自动触发一次 P2P message.pull，补齐离线期间积压
+            // connect/reconnect 成功后自动触发一次 P2P message.v2.pull，补齐离线期间积压
             // 群消息按惰性触发，不在此处主动 pull
             void this._fillP2pGap().catch((exc) => {
                 this._clientLog.warn(`schedule post-connect P2P gap fill failed: ${formatCaughtError(exc)}`);
@@ -2368,45 +3727,245 @@ export class AUNClient {
         this._v2Session = new V2Session(v2Store, this._deviceId, this._aid, aidPriv, aidPubDer);
         await this._v2Session.ensureRegistered(this._v2CallFn());
         this._clientLog.debug(`V2 session initialized aid=${this._aid} device=${this._deviceId}`);
-        this._safeAsync(this._v2AutoConfirmPendingProposals());
+        // 群 state proposal 由服务端在 client.online 时定向通知。
+    }
+    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 cert = new crypto.X509Certificate(certPem);
+        const certPubDer = cert.publicKey.export({ type: 'spki', format: 'der' });
+        return new Uint8Array(certPubDer);
+    }
+    _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 expectedSpkId = `sha256:${crypto.createHash('sha256').update(Buffer.from(args.spkPkDer)).digest('hex').slice(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 tsText = this._v2SPKTimestampText(args.dev.spk_timestamp, args.aid, args.deviceId, spkId);
+        const signData = Buffer.concat([
+            Buffer.from(args.spkPkDer),
+            Buffer.from(spkId, 'utf8'),
+            Buffer.from(tsText, 'utf8'),
+        ]);
+        if (!ecdsaVerifyRaw(trustedIK, signature, new Uint8Array(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)
             return null;
-        let senderPubDer = session.getPeerIK(fromAid, senderDeviceId);
+        const senderPubDer = session.getPeerIK(fromAid, senderDeviceId);
         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;
+            const certPem = await this._fetchPeerCert(fromAid, undefined, 3000);
+            const cert = new crypto.X509Certificate(certPem);
+            const certPubDer = cert.publicKey.export({ type: 'spki', format: 'der' });
+            const certPub = new Uint8Array(certPubDer);
+            session.cachePeerIK(fromAid, senderDeviceId, certPub);
+            this._clientLog.debug(`V2 decrypt: sender IK fallback from PKI cert for ${fromAid}`);
+            return certPub;
+        }
+        catch (exc) {
+            this._clientLog.warn(`V2 decrypt: PKI cert sender IK fallback failed for ${fromAid}: ${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.warn(`V2 decrypt: bootstrap for sender ${fromAid} failed: ${formatCaughtError(exc)}`);
+            this._clientLog.debug(`V2 sender IK cache from bootstrap skipped aid=${aid} dev=${devId.value}: ${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 certPem = await this._fetchPeerCert(fromAid);
-            const cert = new crypto.X509Certificate(certPem);
-            const certPubDer = cert.publicKey.export({ type: 'spki', format: 'der' });
-            senderPubDer = new Uint8Array(certPubDer);
-            if (senderDeviceId) {
-                session.cachePeerIK(fromAid, senderDeviceId, senderPubDer);
+            const session = this._v2Session;
+            if (session && fromAid) {
+                try {
+                    const bs = await this.call('message.v2.bootstrap', {
+                        peer_aid: fromAid,
+                        e2ee_wrap_capabilities: v2WrapCapabilities(),
+                    });
+                    await this._primeBootstrapPeerCerts(bs, fromAid);
+                    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}: ${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}: ${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=${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}`);
             }
-            return senderPubDer;
         }
-        catch (exc) {
-            this._clientLog.warn(`V2 decrypt: CA fallback for ${fromAid} failed: ${formatCaughtError(exc)}`);
-            return null;
+        finally {
+            this._v2SenderIKFetching.delete(fetchKey);
         }
     }
     /**
@@ -2423,20 +3982,30 @@ export class AUNClient {
         const useCache = opts.useCache !== false;
         let peerDevices = [];
         let auditRaw = [];
+        let wrapPolicy = normalizeV2WrapPolicy(undefined);
         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 ?? wrapPolicy;
+            this._clientLog.debug(`message.v2.bootstrap cache hit: to=${to}, devices=${peerDevices.length}, audit=${auditRaw.length}`);
         }
         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(),
+            });
+            await this._primeBootstrapPeerCerts(bs, to);
+            wrapPolicy = normalizeV2WrapPolicy(bs.e2ee_wrap_policy);
             peerDevices = (Array.isArray(bs?.peer_devices) ? bs.peer_devices : []);
             auditRaw = (Array.isArray(bs?.audit_recipients) ? bs.audit_recipients : []);
+            this._clientLog.debug(`message.v2.bootstrap fetched: to=${to}, devices=${peerDevices.length}, audit=${auditRaw.length}`);
             if (peerDevices.length > 0) {
                 this._v2BootstrapCache.set(to, {
                     devices: peerDevices,
                     auditRecipients: auditRaw,
                     cachedAt: Date.now(),
+                    wrapPolicy,
                 });
             }
         }
@@ -2445,37 +4014,28 @@ export class AUNClient {
         }
         const targets = [];
         for (const dev of peerDevices) {
-            const ikPk = String(dev.ik_pk ?? '');
-            if (!ikPk)
-                continue;
-            const devId = String(dev.device_id ?? dev.owner_device_id ?? '');
-            const ikDer = _v2B64ToBytes(ikPk);
-            const spkDer = dev.spk_pk ? _v2B64ToBytes(String(dev.spk_pk)) : undefined;
-            session.cachePeerIK(to, devId, ikDer);
-            targets.push({
+            const devId = getV2DeviceId(dev);
+            const target = await this._v2BuildTargetFromDevice({
+                dev,
                 aid: to,
-                deviceId: devId,
+                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);
         }
         const auditTargets = [];
         for (const dev of auditRaw) {
-            const ikPk = String(dev.ik_pk ?? '');
-            if (!ikPk)
-                continue;
-            auditTargets.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: _v2B64ToBytes(ikPk),
-                spkPkDer: dev.spk_pk ? _v2B64ToBytes(String(dev.spk_pk)) : undefined,
-                spkId: String(dev.spk_id ?? ''),
+                defaultKeySource: 'peer_device_prekey',
             });
+            if (target)
+                auditTargets.push(target);
         }
         // self-sync：给同 AID 其它在线/注册设备也 wrap 一份。
         if (this._aid && this._aid !== to) {
@@ -2486,30 +4046,35 @@ 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(),
+                    });
+                    await this._primeBootstrapPeerCerts(selfBs, this._aid);
                     selfDevices = (Array.isArray(selfBs?.peer_devices) ? selfBs.peer_devices : []);
+                    const selfWrapPolicy = normalizeV2WrapPolicy(selfBs.e2ee_wrap_policy);
                     if (selfDevices.length > 0) {
                         this._v2BootstrapCache.set(this._aid, {
                             devices: selfDevices,
                             auditRecipients: [],
                             cachedAt: Date.now(),
+                            wrapPolicy: selfWrapPolicy,
                         });
                     }
                 }
                 for (const dev of selfDevices) {
-                    const devId = String(dev.owner_device_id ?? dev.device_id ?? '');
-                    const ikPk = String(dev.ik_pk ?? '');
-                    if (!devId || devId === this._deviceId || !ikPk)
+                    const devId = getV2DeviceId(dev);
+                    if (!devId.present || devId.value === this._deviceId)
                         continue;
-                    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: _v2B64ToBytes(ikPk),
-                        spkPkDer: dev.spk_pk ? _v2B64ToBytes(String(dev.spk_pk)) : undefined,
-                        spkId: String(dev.spk_id ?? ''),
+                        defaultKeySource: 'peer_device_prekey',
                     });
+                    if (target)
+                        targets.push(target);
                 }
             }
             catch (exc) {
@@ -2519,12 +4084,32 @@ export class AUNClient {
         if (targets.length === 0) {
             throw new E2EEError(`V2 bootstrap: no usable devices found for ${to}`);
         }
-        return encryptP2PMessage(session.getSenderIdentity(), { targets, auditRecipients: auditTargets }, opts.payload, {
+        const envelope = encryptP2PMessage(session.getSenderIdentity(), {
+            targets: applyV2WrapPolicyToTargets(targets, wrapPolicy),
+            auditRecipients: applyV2WrapPolicyToTargets(auditTargets, wrapPolicy),
+        }, opts.payload, {
             messageId: opts.messageId,
             timestamp: opts.timestamp,
             protectedHeaders: opts.protectedHeaders,
             context: opts.context,
         });
+        this._logMessageDebug('send-envelope', 'message.send.v2', 'message.send', {
+            message_id: envelope.message_id,
+            to,
+            type: envelope.type,
+            version: envelope.version,
+            protected_headers: envelope.protected_headers,
+            context: envelope.context,
+        }, {
+            payloadOverride: envelope,
+            extra: {
+                plaintext_payload: opts.payload,
+                target_count: targets.length,
+                audit_count: auditTargets.length,
+                use_cache: useCache,
+            },
+        });
+        return envelope;
     }
     /** V2 P2P 加密发送，推测性缓存失败后刷新 bootstrap 重试一次。 */
     async sendV2(to, payload, opts) {
@@ -2534,7 +4119,13 @@ export class AUNClient {
             throw new ValidationError("message.send requires 'to'");
         if (!isJsonObject(payload))
             throw new ValidationError('message.send payload must be a dict for V2 encryption');
+        this._logMessageDebug('send-plaintext', 'message.send.v2', 'message.send', {
+            to: toAid,
+            message_id: opts?.messageId ?? '',
+            payload,
+        }, { payloadOverride: payload });
         const attempt = async (useCache) => {
+            this._clientLog.debug(`message.v2.send attempt: to=${toAid}, use_cache=${useCache}`);
             const envelope = await this._buildV2P2PEnvelope({
                 to: toAid,
                 payload,
@@ -2544,11 +4135,13 @@ export class AUNClient {
                 context: opts?.context,
                 useCache,
             });
-            return await this.call('message.send', {
+            const result = await this.call('message.send', {
                 to: toAid,
                 payload: envelope,
                 encrypt: false,
             });
+            this._clientLog.debug(`message.v2.send ok: to=${toAid}, use_cache=${useCache}, seq=${String((isJsonObject(result) ? result.seq : '') ?? '')}`);
+            return result;
         };
         try {
             return await attempt(true);
@@ -2564,94 +4157,153 @@ export class AUNClient {
         }
     }
     /** V2 P2P 拉取并解密；直接方法返回消息数组，call("message.pull") 会包装为 {messages}. */
-    async pullV2(afterSeq = 0, limit = 50) {
+    async pullV2(afterSeq = 0, limit = 50, opts) {
         await this._ensureV2SessionReady('message.pull');
         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 : []);
+        if (ns && !opts?.gateLocked) {
+            return await this._runPullSerialized(ns, async () => this.pullV2(afterSeq, limit, {
+                ...(opts ?? {}),
+                gateLocked: true,
+                scheduleFollowup: true,
+            }));
+        }
         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 totalRawCount = 0;
+        let nextAfterSeq = afterSeq || (ns ? this._seqTracker.getContiguousSeq(ns) : 0);
+        let pageCount = 0;
+        const maxPages = 100;
+        while (pageCount < maxPages) {
+            pageCount += 1;
+            this._clientLog.debug(`message.v2.pull page request: page=${pageCount}, after_seq=${nextAfterSeq}, limit=${limit}, ns=${ns || '<none>'}`);
+            const result = await this._callRawV2Rpc('message.v2.pull', {
+                after_seq: nextAfterSeq,
+                limit,
+            });
+            const messages = (Array.isArray(result?.messages) ? result.messages : []);
+            totalRawCount += messages.length;
+            this._clientLog.debug(`message.v2.pull page response: page=${pageCount}, raw_count=${messages.length}, has_more=${String(result.has_more ?? '')}, server_ack_seq=${String(result.server_ack_seq ?? '')}`);
+            for (const msg of messages) {
+                this._logMessageDebug('pull-raw', 'message.v2.pull', 'message.received', msg);
+            }
+            const seqs = messages
+                .map((msg) => Number(msg.seq ?? 0))
+                .filter((seq) => Number.isFinite(seq) && seq > 0);
+            const pageContigBefore = ns ? this._seqTracker.getContiguousSeq(ns) : 0;
+            let pageMaxSeq = nextAfterSeq;
+            if (seqs.length > 0) {
+                pageMaxSeq = Math.max(...seqs);
+                if (ns) {
+                    this._seqTracker.forceContiguousSeq(ns, pageMaxSeq);
+                    this._clientLog.debug(`message.v2.pull force contiguous: ns=${ns}, page_max_seq=${pageMaxSeq}, previous=${pageContigBefore}`);
+                }
+            }
+            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, 'pull');
+                        }
+                        decrypted.push(v1Msg);
+                        this._clientLog.debug(`message.v2.pull plaintext V1 delivered: seq=${seq}, ns=${ns || '<none>'}`);
+                    }
+                    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;
+                }
+                const spkId = String(msg.spk_id ?? '');
+                if (spkId && this._v2Session && !this._v2Session.isCurrentSPK(spkId)) {
+                    this._v2Session.trackOldSPKMaxSeq(spkId, seq);
+                }
+                const plaintext = await this._decryptV2Message(msg);
+                if (plaintext === null) {
+                    this._clientLog.debug(`message.v2.pull decrypt returned null: seq=${seq}, ns=${ns || '<none>'}`);
+                    continue;
+                }
+                if (ns) {
+                    await this._publishPulledMessage('message.received', ns, seq, 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, 'pull');
+                }
+                decrypted.push(plaintext);
+                this._logMessageDebug('decrypt-ok', 'message.v2.pull', 'message.received', plaintext);
+            }
+            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);
                 }
-                continue;
-            }
-            if (version !== 'v2') {
-                this._clientLog.debug(`message.v2.pull skipping non-V2 row seq=${seq} version=${String(msg.version ?? '')}`);
-                continue;
-            }
-            const spkId = String(msg.spk_id ?? '');
-            if (spkId && this._v2Session && !this._v2Session.isCurrentSPK(spkId)) {
-                this._v2Session.trackOldSPKMaxSeq(spkId, seq);
-            }
-            const plaintext = await this._decryptV2Message(msg);
-            if (plaintext === null)
-                continue;
-            if (ns)
-                await this._publishPulledMessage('message.received', ns, seq, 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 && ackSeq !== contigBefore) {
-                this._safeAsync(this.ackV2(ackSeq).then(() => undefined));
+            if (ns) {
+                const ackSeq = this._seqTracker.getContiguousSeq(ns);
+                const contigAdvanced = ackSeq !== pageContigBefore;
+                if (contigAdvanced) {
+                    await this._drainOrderedMessages(ns, undefined, true);
+                    this._saveSeqTrackerState();
+                }
+                if (messages.length > 0 && contigAdvanced && ackSeq > 0 && !opts?.skipAutoAck) {
+                    this._clientLog.debug(`message.v2.pull scheduling auto-ack: ns=${ns}, ack_seq=${ackSeq}, raw_count=${messages.length}`);
+                    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}`);
         }
+        this._clientLog.debug(`message.v2.pull done: requested_after_seq=${afterSeq}, pages=${pageCount}, decrypted=${decrypted.length}, ns=${ns || '<none>'}`);
         return decrypted;
     }
     /** V2 P2P ack，并触发旧 SPK 销毁自检。 */
     async ackV2(upToSeq) {
         const ns = this._aid ? `p2p:${this._aid}` : '';
-        const seq = Number(upToSeq ?? (ns ? this._seqTracker.getContiguousSeq(ns) : 0));
-        if (!Number.isFinite(seq) || seq <= 0)
+        let seq = Number(upToSeq ?? (ns ? this._seqTracker.getContiguousSeq(ns) : 0));
+        if (!Number.isFinite(seq) || seq <= 0) {
+            this._clientLog.debug(`message.v2.ack skipped: ns=${ns || '<none>'}, up_to_seq=${String(upToSeq ?? '')}`);
             return { acked: 0 };
-        const raw = await this.call('message.v2.ack', { up_to_seq: seq });
+        }
+        // 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;
+            }
+        }
+        this._clientLog.debug(`message.v2.ack send: ns=${ns || '<none>'}, up_to_seq=${seq}`);
+        const raw = await this._callRawV2Rpc('message.v2.ack', { up_to_seq: seq });
         const result = isJsonObject(raw)
             ? { ...raw }
             : { result: raw };
@@ -2679,6 +4331,7 @@ export class AUNClient {
                 this._clientLog.debug(`V2 SPK destroy failed (non-fatal): ${formatCaughtError(exc)}`);
             }
         }
+        this._clientLog.debug(`message.v2.ack ok: ns=${ns || '<none>'}, requested=${seq}, effective=${actualAckSeq}, acked=${String(result.acked ?? '')}`);
         return result;
     }
     /** V2 Group 加密发送，推测性缓存失败后刷新 bootstrap 重试一次。 */
@@ -2689,7 +4342,13 @@ export class AUNClient {
             throw new ValidationError("group.send requires 'group_id'");
         if (!isJsonObject(payload))
             throw new ValidationError('group.send payload must be a dict for V2 encryption');
+        this._logMessageDebug('send-plaintext', 'group.send.v2', 'group.send', {
+            group_id: gid,
+            message_id: opts?.messageId ?? '',
+            payload,
+        }, { payloadOverride: payload });
         const attempt = async (useCache) => {
+            this._clientLog.debug(`group.v2.send attempt: group=${gid}, use_cache=${useCache}`);
             const envelope = await this._buildV2GroupEnvelope({
                 groupId: gid,
                 payload,
@@ -2699,10 +4358,12 @@ export class AUNClient {
                 context: opts?.context,
                 useCache,
             });
-            return await this.call('group.v2.send', {
+            const result = await this.call('group.v2.send', {
                 group_id: gid,
                 envelope: envelope,
             });
+            this._clientLog.debug(`group.v2.send ok: group=${gid}, use_cache=${useCache}, seq=${String((isJsonObject(result) ? result.seq : '') ?? '')}`);
+            return result;
         };
         const markSentSeq = (result) => {
             if (!isJsonObject(result))
@@ -2715,6 +4376,7 @@ export class AUNClient {
             this._seqTracker.onMessageSeq(ns, seq);
             this._markPublishedSeq(ns, seq);
             this._saveSeqTrackerState();
+            this._clientLog.debug(`group.v2.send marked own seq: group=${gid}, ns=${ns}, seq=${seq}`);
         };
         try {
             const result = await attempt(true);
@@ -2747,18 +4409,26 @@ export class AUNClient {
         let auditRecipientsRaw = [];
         let epoch = 0;
         let stateCommitment = { state_version: 0, state_hash: '', state_chain: '' };
+        let wrapPolicy = normalizeV2WrapPolicy(undefined);
         const cached = useCache ? this._v2BootstrapCache.get(cacheKey) : undefined;
         if (cached && Date.now() - cached.cachedAt < AUNClient.V2_BOOTSTRAP_TTL_MS) {
             allDevices = cached.devices;
             auditRecipientsRaw = cached.auditRecipients;
             epoch = cached.epoch ?? 0;
             stateCommitment = cached.stateCommitment ?? stateCommitment;
+            wrapPolicy = cached.wrapPolicy ?? wrapPolicy;
+            this._clientLog.debug(`group.v2.bootstrap cache hit: group=${groupId}, devices=${allDevices.length}, audit=${auditRecipientsRaw.length}, epoch=${epoch}, state_version=${stateCommitment.state_version}`);
         }
         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 : []);
             auditRecipientsRaw = (Array.isArray(bs.audit_recipients) ? bs.audit_recipients : []);
             epoch = Number(bs.epoch ?? 0) || 0;
+            wrapPolicy = normalizeV2WrapPolicy(bs.e2ee_wrap_policy);
+            this._clientLog.debug(`group.v2.bootstrap fetched: group=${groupId}, devices=${allDevices.length}, audit=${auditRecipientsRaw.length}, epoch=${epoch}, members=${Array.isArray(bs.member_aids) ? bs.member_aids.length : 0}`);
             const stateChain = String(bs.state_chain ?? '');
             await this._v2CheckFork(groupId, stateChain);
             await this._v2VerifyStateSignature(groupId, bs);
@@ -2775,6 +4445,7 @@ export class AUNClient {
                     cachedAt: Date.now(),
                     epoch,
                     stateCommitment,
+                    wrapPolicy,
                 });
             }
             // lazy sync 触发：发现 pending members 时异步发起提案
@@ -2789,83 +4460,135 @@ export class AUNClient {
         const targets = [];
         for (const dev of allDevices) {
             const devAid = String(dev.aid ?? '').trim();
-            const devId = String(dev.device_id ?? '').trim();
-            const ikPk = String(dev.ik_pk ?? '').trim();
-            if (!devAid || !devId || !ikPk)
-                continue;
-            if (devAid === this._aid && devId === this._deviceId)
+            const devId = getV2DeviceId(dev);
+            if (devAid === this._aid && devId.present && devId.value === this._deviceId)
                 continue;
             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: _v2B64ToBytes(ikPk),
-                spkPkDer: dev.spk_pk ? _v2B64ToBytes(String(dev.spk_pk)) : undefined,
-                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 group ${groupId}`);
         }
         for (const dev of auditRecipientsRaw) {
-            const ikPk = String(dev.ik_pk ?? '').trim();
-            if (!ikPk)
-                continue;
-            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: _v2B64ToBytes(ikPk),
-                spkPkDer: dev.spk_pk ? _v2B64ToBytes(String(dev.spk_pk)) : undefined,
-                spkId: String(dev.spk_id ?? ''),
+                defaultKeySource: 'peer_device_prekey',
             });
+            if (target)
+                targets.push(target);
         }
-        return encryptGroupMessage(session.getSenderIdentity(), groupId, epoch, targets, opts.payload, {
+        const envelope = encryptGroupMessage(session.getSenderIdentity(), groupId, epoch, applyV2WrapPolicyToTargets(targets, wrapPolicy), opts.payload, {
             messageId: opts.messageId,
             timestamp: opts.timestamp,
             protectedHeaders: opts.protectedHeaders,
             context: opts.context,
         }, stateCommitment);
+        this._logMessageDebug('send-envelope', 'group.send.v2', 'group.send', {
+            group_id: groupId,
+            message_id: envelope.message_id,
+            type: envelope.type,
+            version: envelope.version,
+            protected_headers: envelope.protected_headers,
+            context: envelope.context,
+        }, {
+            payloadOverride: envelope,
+            extra: {
+                plaintext_payload: opts.payload,
+                epoch,
+                target_count: targets.length,
+                audit_count: auditRecipientsRaw.length,
+                state_version: stateCommitment.state_version,
+                use_cache: useCache,
+            },
+        });
+        return envelope;
     }
     async _pullGroupV2Internal(params) {
-        await this.pullGroupV2(params.group_id, params.after_seq, params.limit);
+        await this.pullGroupV2(params.group_id, params.after_seq, params.limit, { gateLocked: true });
     }
     /** V2 Group 拉取并解密；直接方法返回消息数组，call("group.pull") 会包装为 {messages}. */
-    async pullGroupV2(groupId, afterSeq = 0, limit = 50) {
+    async pullGroupV2(groupId, afterSeq = 0, limit = 50, opts) {
         await this._ensureV2SessionReady('group.pull');
         const gid = normalizeGroupId(groupId) || String(groupId ?? '').trim();
         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]);
+        if (!opts?.gateLocked) {
+            return await this._runPullSerialized(ns, async () => this.pullGroupV2(gid, afterSeq, limit, {
+                ...(opts ?? {}),
+                gateLocked: true,
+                scheduleFollowup: true,
+            }));
         }
-        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 decrypted = [];
+        let totalRawCount = 0;
+        let nextAfterSeq = afterSeq || this._seqTracker.getContiguousSeq(ns);
+        let pageCount = 0;
+        const maxPages = 100;
+        while (pageCount < maxPages) {
+            pageCount += 1;
+            this._clientLog.debug(`group.v2.pull page request: group=${gid}, page=${pageCount}, after_seq=${nextAfterSeq}, limit=${limit}, ns=${ns}`);
+            const result = await this._callRawV2Rpc('group.v2.pull', {
+                group_id: gid,
+                after_seq: nextAfterSeq,
+                limit,
+            });
+            const messages = (Array.isArray(result.messages) ? result.messages : []);
+            totalRawCount += messages.length;
+            const cursor = isJsonObject(result.cursor) ? result.cursor : null;
+            this._clientLog.debug(`group.v2.pull page response: group=${gid}, page=${pageCount}, raw_count=${messages.length}, has_more=${String(result.has_more ?? '')}, cursor_current=${String(cursor?.current_seq ?? '')}`);
+            for (const msg of messages) {
+                this._logMessageDebug('pull-raw', 'group.v2.pull', 'group.message_created', msg);
+            }
+            const seqs = messages
+                .map((msg) => Number(msg.seq ?? 0))
+                .filter((seq) => Number.isFinite(seq) && seq > 0);
+            const pageContigBefore = this._seqTracker.getContiguousSeq(ns);
+            let pageMaxSeq = nextAfterSeq;
+            if (seqs.length > 0) {
+                pageMaxSeq = Math.max(...seqs);
+                this._seqTracker.forceContiguousSeq(ns, pageMaxSeq);
+                this._clientLog.debug(`group.v2.pull force contiguous: group=${gid}, ns=${ns}, page_max_seq=${pageMaxSeq}, previous=${pageContigBefore}`);
+            }
+            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);
+                            this._clientLog.debug(`group.v2.pull plaintext V1 delivered: group=${gid}, seq=${seq}`);
+                            continue;
+                        }
+                    }
+                    else if (payload !== undefined && payload !== null) {
                         const v1Msg = {
                             message_id: String(msg.message_id ?? ''),
                             from: String(msg.from_aid ?? ''),
@@ -2878,53 +4601,53 @@ export class AUNClient {
                         };
                         await this._publishPulledMessage('group.message_created', ns, seq, v1Msg);
                         decrypted.push(v1Msg);
+                        this._clientLog.debug(`group.v2.pull plaintext V1 delivered: group=${gid}, seq=${seq}`);
                         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;
+                const plaintext = await this._decryptV2Message(msg);
+                if (plaintext === null) {
+                    this._clientLog.debug(`group.v2.pull decrypt returned null: group=${gid}, seq=${seq}`);
+                    continue;
+                }
+                plaintext.group_id = gid;
+                await this._publishPulledMessage('group.message_created', ns, seq, plaintext);
+                decrypted.push(plaintext);
+                this._logMessageDebug('decrypt-ok', 'group.v2.pull', 'group.message_created', plaintext);
+            }
+            const retentionFloor = this._pullRetentionFloor(result, 'retention_floor_message_seq', 'retention_floor_message_seq');
+            if (retentionFloor > 0) {
+                const contig = this._seqTracker.getContiguousSeq(ns);
+                if (contig < retentionFloor) {
+                    this._clientLog.info(`group.v2.pull retention-floor advance: ns=${ns} contiguous=${contig} -> retention_floor=${retentionFloor}`);
+                    this._seqTracker.forceContiguousSeq(ns, retentionFloor);
+                }
             }
-            if (version !== 'v2') {
-                this._clientLog.debug(`group.v2.pull skipping non-V2 row group=${gid} seq=${seq} version=${String(msg.version ?? '')}`);
-                continue;
+            const ackSeq = this._seqTracker.getContiguousSeq(ns);
+            const contigAdvanced = ackSeq !== pageContigBefore;
+            if (contigAdvanced) {
+                await this._drainOrderedMessages(ns, undefined, true);
+                this._saveSeqTrackerState();
             }
-            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);
-        }
-        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);
+            if (messages.length > 0 && contigAdvanced && ackSeq > 0) {
+                this._clientLog.debug(`group.v2.pull scheduling auto-ack: group=${gid}, ns=${ns}, ack_seq=${ackSeq}, raw_count=${messages.length}`);
+                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;
         }
-        const ackSeq = this._seqTracker.getContiguousSeq(ns);
-        if (ackSeq !== contigBefore) {
-            this._saveSeqTrackerState();
-        }
-        if (ackSeq > 0 && ackSeq !== contigBefore) {
-            this._safeAsync(this.ackGroupV2(gid, ackSeq).then(() => undefined));
+        if (pageCount >= maxPages) {
+            this._clientLog.warn(`group.v2.pull reached max_pages=${maxPages} group=${gid} after_seq=${nextAfterSeq}`);
         }
+        this._clientLog.debug(`group.v2.pull done: group=${gid}, requested_after_seq=${afterSeq}, pages=${pageCount}, decrypted=${decrypted.length}, ns=${ns}`);
         return decrypted;
     }
     /** V2 Group ack。 */
@@ -2933,13 +4656,24 @@ export class AUNClient {
         if (!gid)
             throw new ValidationError('group.ack_messages requires group_id');
         const ns = `group:${gid}`;
-        const seq = Number(upToSeq ?? this._seqTracker.getContiguousSeq(ns));
-        if (!Number.isFinite(seq) || seq <= 0)
+        let seq = Number(upToSeq ?? this._seqTracker.getContiguousSeq(ns));
+        if (!Number.isFinite(seq) || seq <= 0) {
+            this._clientLog.debug(`group.v2.ack skipped: group=${gid}, ns=${ns}, up_to_seq=${String(upToSeq ?? '')}`);
             return { acked: 0 };
-        return await this.call('group.v2.ack', { group_id: gid, up_to_seq: seq });
+        }
+        // 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;
+        }
+        this._clientLog.debug(`group.v2.ack send: group=${gid}, ns=${ns}, up_to_seq=${seq}`);
+        const result = await this._callRawV2Rpc('group.v2.ack', { group_id: gid, up_to_seq: seq });
+        this._clientLog.debug(`group.v2.ack ok: group=${gid}, ns=${ns}, requested=${seq}, result=${this._debugJson(result)}`);
+        return result;
     }
-    /** 解密单条 V2 pull 消息。失败返回 null 并发布 undecryptable。 */
-    async _decryptV2Message(msg) {
+    /** 解密单条 V2 pull 消息。缺 sender IK 时先入 pending，后台补齐后重试。 */
+    async _decryptV2Message(msg, allowPending = true) {
         const session = this._v2Session;
         if (!session)
             return null;
@@ -2954,6 +4688,8 @@ export class AUNClient {
             this._clientLog.warn(`V2 decrypt: invalid envelope_json for msg seq=${String(msg.seq)}`);
             return null;
         }
+        const e2eeMeta = this._v2E2eeMeta(envelope);
+        this._observeAgentMdFromEnvelope(envelope);
         let spkId = '';
         let recipientKeySource = '';
         if (isJsonObject(envelope.recipient)) {
@@ -2968,7 +4704,7 @@ export class AUNClient {
             for (const row of recipients) {
                 if (Array.isArray(row) && row.length >= 6
                     && String(row[0] ?? '') === this._aid
-                    && String(row[1] ?? '') === this._deviceId) {
+                    && (String(row[1] ?? '') === this._deviceId || String(row[1] ?? '') === '')) {
                     if (!spkId)
                         spkId = String(row[5] ?? '');
                     if (row.length > 3)
@@ -2977,31 +4713,73 @@ export class AUNClient {
                 }
             }
         }
-        // 根据 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(aad.group_id ?? msg.group_id ?? '').trim();
+        const undecryptableEvent = groupIdForKeys ? 'group.message_undecryptable' : 'message.undecryptable';
+        this._clientLog.debug(`V2 decrypt start: seq=${String(msg.seq ?? '')}, message_id=${String(msg.message_id ?? '')}, group=${groupIdForKeys || '<p2p>'}, from=${String(msg.from_aid ?? '')}, spk_id=${spkId || '<empty>'}, key_source=${recipientKeySource || '<empty>'}, has_recipient=${String(isJsonObject(envelope.recipient))}, has_recipients=${String(Array.isArray(envelope.recipients))}`);
         let ikPriv;
         let spkPriv;
-        if (groupIdForKeys) {
-            const keys = session.getGroupDecryptKeys(groupIdForKeys, spkId);
-            ikPriv = keys.ikPriv;
-            spkPriv = keys.spkPriv ?? undefined;
+        try {
+            if (groupIdForKeys) {
+                const keys = session.getGroupDecryptKeys(groupIdForKeys, spkId);
+                ikPriv = keys.ikPriv;
+                spkPriv = keys.spkPriv ?? undefined;
+            }
+            else {
+                const keys = session.getDecryptKeys(spkId);
+                ikPriv = keys.ikPriv;
+                spkPriv = keys.spkPriv;
+            }
         }
-        else {
-            const keys = 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}: ${formatCaughtError(exc)}`);
+            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(formatCaughtError(exc)),
+                _decrypt_stage: 'spk_lookup',
+                _envelope_type: String(envelope.type ?? ''),
+                _suite: String(envelope.suite ?? ''),
+                _spk_id: spkId,
+            };
+            this._attachV2EnvelopeMetadata(event, e2eeMeta);
+            this._logMessageDebug('decrypt-fail', 'v2.decrypt', undecryptableEvent, event);
+            await this._dispatcher.publish(undecryptableEvent, event);
+            return null;
         }
+        this._clientLog.debug(`V2 decrypt key lookup ok: seq=${String(msg.seq ?? '')}, group=${groupIdForKeys || '<p2p>'}, ik_len=${ikPriv.byteLength}, spk_len=${spkPriv?.byteLength ?? 0}`);
         const fromAid = String(msg.from_aid ?? '');
         const senderDeviceId = String(aad.from_device ?? '');
         const senderPubDer = await this._getV2SenderPubDer(fromAid, senderDeviceId);
         if (!senderPubDer) {
-            await this._dispatcher.publish('message.undecryptable', {
+            this._clientLog.warn(`V2 decrypt: no sender IK for ${fromAid} device=${senderDeviceId}`);
+            if (allowPending) {
+                this._scheduleV2SenderIKPending({ msg, fromAid, senderDeviceId, groupId: groupIdForKeys });
+                return null;
+            }
+            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 ?? ''),
+            };
+            this._attachV2EnvelopeMetadata(event, e2eeMeta);
+            this._logMessageDebug('decrypt-fail', 'v2.decrypt', undecryptableEvent, event);
+            await this._dispatcher.publish(undecryptableEvent, event);
             return null;
         }
         let plaintext;
@@ -3010,16 +4788,29 @@ export class AUNClient {
         }
         catch (exc) {
             this._clientLog.warn(`V2 decrypt failed for msg seq=${String(msg.seq)}: ${formatCaughtError(exc)}`);
-            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(formatCaughtError(exc)),
-            });
+                _decrypt_stage: 'decrypt',
+                _envelope_type: String(envelope.type ?? ''),
+                _suite: String(envelope.suite ?? ''),
+                _sender_device_id: String(aad.from_device ?? ''),
+            };
+            this._attachV2EnvelopeMetadata(event, e2eeMeta);
+            this._logMessageDebug('decrypt-fail', 'v2.decrypt', undecryptableEvent, event);
+            await this._dispatcher.publish(undecryptableEvent, event);
             return null;
         }
-        if (plaintext === null)
+        if (plaintext === null) {
+            this._clientLog.debug(`V2 decrypt returned null plaintext: seq=${String(msg.seq ?? '')}, group=${groupIdForKeys || '<p2p>'}`);
             return null;
+        }
         // 消费触发 SPK 轮换
         if (groupIdForKeys && recipientKeySource === 'group_device_prekey' && session.isLastUploadedGroupSPK(groupIdForKeys, spkId)) {
             // Group SPK 消费触发轮换
@@ -3042,8 +4833,8 @@ export class AUNClient {
                 this._clientLog.debug(`V2 SPK rotation failed (non-fatal): ${formatCaughtError(exc)}`);
             });
         }
-        const suite = String(envelope.suite ?? '');
-        return {
+        const e2ee = this._v2E2eeMeta(envelope);
+        const result = {
             message_id: String(msg.message_id ?? ''),
             from: fromAid,
             to: this._aid ?? '',
@@ -3051,13 +4842,84 @@ export class AUNClient {
             t_server: msg.t_server,
             payload: plaintext,
             encrypted: true,
-            e2ee: {
-                version: 'v2',
-                suite,
-                encryption_mode: `v2_${suite || 'unknown'}`,
-                forward_secrecy: true,
-            },
+            e2ee,
+        };
+        this._attachV2EnvelopeMetadata(result, e2ee);
+        this._logMessageDebug('decrypt-ok', 'v2.decrypt', groupIdForKeys ? 'group.message_created' : 'message.received', result);
+        return result;
+    }
+    _v2E2eeMeta(envelope) {
+        const suite = String(envelope.suite ?? '');
+        const meta = {
+            version: 'v2',
+            suite,
+            encryption_mode: `v2_${suite || 'unknown'}`,
+            forward_secrecy: true,
         };
+        const protectedHeaders = this._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 = this._metadataWithoutAuth(envelope.context);
+        if (context && Object.keys(context).length > 0) {
+            meta.context = context;
+        }
+        const agentMd = this._metadataWithoutAuth(envelope.agent_md);
+        if (agentMd && Object.keys(agentMd).length > 0) {
+            meta.agent_md = agentMd;
+        }
+        return meta;
+    }
+    _attachV2EnvelopeMetadata(message, meta) {
+        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 };
+        }
+    }
+    _attachV2EnvelopeMetadataFromSource(message, source) {
+        const envelope = this._extractV2EnvelopeFromSource(source);
+        if (envelope) {
+            this._observeAgentMdFromEnvelope(envelope);
+            this._attachV2EnvelopeMetadata(message, this._v2E2eeMeta(envelope));
+        }
+    }
+    _extractV2EnvelopeFromSource(source) {
+        const candidate = source;
+        if (!isJsonObject(candidate))
+            return null;
+        if (isJsonObject(candidate.payload))
+            return candidate.payload;
+        if (typeof candidate.envelope_json === 'string' && candidate.envelope_json) {
+            try {
+                const parsed = JSON.parse(candidate.envelope_json);
+                if (isJsonObject(parsed))
+                    return parsed;
+            }
+            catch {
+                return null;
+            }
+        }
+        return null;
+    }
+    _metadataWithoutAuth(value) {
+        const candidate = value;
+        if (!isJsonObject(candidate))
+            return null;
+        const body = {};
+        for (const [key, item] of Object.entries(candidate)) {
+            if (key !== '_auth')
+                body[key] = item;
+        }
+        return body;
     }
     async _putMessageThoughtEncryptedV2(params) {
         const toAid = String(params.to ?? '').trim();
@@ -3070,7 +4932,14 @@ export class AUNClient {
         const thoughtId = String(params.thought_id ?? '').trim() || `mt-${crypto.randomUUID()}`;
         const timestamp = Number(params.timestamp ?? Date.now());
         const protectedHeaders = this._protectedHeadersFromParams(params);
+        this._logMessageDebug('thought-send-plaintext', 'message.thought.put.v2', 'message.thought.put', {
+            to: toAid,
+            thought_id: thoughtId,
+            timestamp,
+            payload,
+        }, { payloadOverride: payload });
         const attempt = async (useCache) => {
+            this._clientLog.debug(`message.thought.put attempt: to=${toAid}, thought_id=${thoughtId}, use_cache=${useCache}`);
             const context = isJsonObject(params.context) ? params.context : undefined;
             const envelope = await this._buildV2P2PEnvelope({
                 to: toAid,
@@ -3091,7 +4960,13 @@ export class AUNClient {
             if ('context' in params)
                 sendParams.context = params.context;
             this._signClientOperation('message.thought.put', sendParams);
-            return await this._transport.call('message.thought.put', sendParams);
+            this._logMessageDebug('thought-send-envelope', 'message.thought.put.v2', 'message.thought.put', sendParams, {
+                payloadOverride: envelope,
+                extra: { to: toAid, thought_id: thoughtId, use_cache: useCache },
+            });
+            const result = await this._transport.call('message.thought.put', sendParams);
+            this._clientLog.debug(`message.thought.put ok: to=${toAid}, thought_id=${thoughtId}, use_cache=${useCache}`);
+            return result;
         };
         try {
             return await attempt(true);
@@ -3116,7 +4991,14 @@ export class AUNClient {
         const thoughtId = String(params.thought_id ?? '').trim() || `gt-${crypto.randomUUID()}`;
         const timestamp = Number(params.timestamp ?? Date.now());
         const protectedHeaders = this._protectedHeadersFromParams(params);
+        this._logMessageDebug('thought-send-plaintext', 'group.thought.put.v2', 'group.thought.put', {
+            group_id: groupId,
+            thought_id: thoughtId,
+            timestamp,
+            payload,
+        }, { payloadOverride: payload });
         const attempt = async (useCache) => {
+            this._clientLog.debug(`group.thought.put attempt: group=${groupId}, thought_id=${thoughtId}, use_cache=${useCache}`);
             const context = isJsonObject(params.context) ? params.context : undefined;
             const envelope = await this._buildV2GroupEnvelope({
                 groupId,
@@ -3137,7 +5019,13 @@ export class AUNClient {
             if ('context' in params)
                 sendParams.context = params.context;
             this._signClientOperation('group.thought.put', sendParams);
-            return await this._transport.call('group.thought.put', sendParams);
+            this._logMessageDebug('thought-send-envelope', 'group.thought.put.v2', 'group.thought.put', sendParams, {
+                payloadOverride: envelope,
+                extra: { group_id: groupId, thought_id: thoughtId, use_cache: useCache },
+            });
+            const result = await this._transport.call('group.thought.put', sendParams);
+            this._clientLog.debug(`group.thought.put ok: group=${groupId}, thought_id=${thoughtId}, use_cache=${useCache}`);
+            return result;
         };
         try {
             return await attempt(true);
@@ -3159,30 +5047,58 @@ export class AUNClient {
             return null;
         const envelope = opts.envelope;
         let spkId = '';
+        let recipientKeySource = '';
         if (Array.isArray(envelope.recipients)) {
             for (const row of envelope.recipients) {
-                if (!Array.isArray(row) || row.length < 8)
+                if (!Array.isArray(row) || row.length < 6)
                     continue;
-                if (String(row[0] ?? '') === this._aid && String(row[1] ?? '') === this._deviceId) {
+                if (String(row[0] ?? '') === this._aid
+                    && (String(row[1] ?? '') === this._deviceId || String(row[1] ?? '') === '')) {
                     spkId = String(row[5] ?? '');
+                    recipientKeySource = String(row[3] ?? '');
                     break;
                 }
             }
         }
         else if (isJsonObject(envelope.recipient)) {
-            spkId = String(envelope.recipient.spk_id ?? '');
+            const recipient = envelope.recipient;
+            spkId = String(recipient.spk_id ?? '');
+            recipientKeySource = String(recipient.key_source ?? '');
         }
-        const { ikPriv, spkPriv } = session.getDecryptKeys(spkId);
         const aad = isJsonObject(envelope.aad) ? envelope.aad : {};
+        const groupIdForKeys = String(aad.group_id ?? envelope.group_id ?? '').trim();
         const fromAid = String(opts.fromAid || aad.from || '').trim();
         const senderDeviceId = String(aad.from_device ?? '');
+        this._clientLog.debug(`V2 thought decrypt start: from=${fromAid}, sender_device=${senderDeviceId}, group=${groupIdForKeys || '<p2p>'}, spk_id=${spkId || '<empty>'}, key_source=${recipientKeySource || '<empty>'}, type=${String(envelope.type ?? '')}`);
+        // group_id 只表示群上下文；group lookup 内部按 group SPK -> P2P device SPK -> IK fallback。
+        let ikPriv;
+        let spkPriv;
+        try {
+            if (groupIdForKeys) {
+                const keys = session.getGroupDecryptKeys(groupIdForKeys, spkId);
+                ikPriv = keys.ikPriv;
+                spkPriv = keys.spkPriv ?? undefined;
+            }
+            else {
+                const keys = session.getDecryptKeys(spkId);
+                ikPriv = keys.ikPriv;
+                spkPriv = keys.spkPriv;
+            }
+        }
+        catch (exc) {
+            this._clientLog.warn(`V2 thought decrypt: SPK lookup failed from=${fromAid}, group=${groupIdForKeys || '<p2p>'}, spk_id=${spkId || '<empty>'}: ${formatCaughtError(exc)}`);
+            return null;
+        }
         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 {
-            return decryptMessage(envelope, this._aid ?? '', this._deviceId, ikPriv, spkPriv, senderPubDer);
+            const plain = decryptMessage(envelope, this._aid ?? '', this._deviceId, ikPriv, spkPriv, senderPubDer);
+            this._clientLog.debug(`V2 thought decrypt ok: from=${fromAid}, sender_device=${senderDeviceId}, group=${groupIdForKeys || '<p2p>'}`);
+            return plain;
         }
         catch (exc) {
             this._clientLog.warn(`V2 thought decrypt failed from=${fromAid}: ${formatCaughtError(exc)}`);
@@ -3219,11 +5135,7 @@ export class AUNClient {
             });
             const sigBytes = Buffer.from(stateSignature, 'base64');
             const cacheKey = crypto.createHash('sha256')
-                .update(actorAid, 'utf-8')
-                .update(Buffer.from([0]))
-                .update(signPayload, 'utf-8')
-                .update(Buffer.from([0]))
-                .update(sigBytes)
+                .update(lengthPrefixedBytesKey(Buffer.from(actorAid, 'utf-8'), Buffer.from(signPayload, 'utf-8'), sigBytes))
                 .digest('hex');
             const now = Date.now();
             const cachedExp = this._v2SigCache.get(cacheKey);
@@ -3425,15 +5337,19 @@ 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 = isJsonObject(bootstrapResp) && Array.isArray(bootstrapResp.devices)
                 ? bootstrapResp.devices.filter(isJsonObject)
                 : [];
             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}`);
                 }
             }
@@ -3449,7 +5365,7 @@ export class AUNClient {
                 this._clientLog.debug(`V2 auto propose leader elected: group=${groupId} leader=${leader}`);
                 return true;
             }
-            const delayMs = this._v2LeaderDelayMs(`${groupId}\x00${myKey}`);
+            const delayMs = this._v2LeaderDelayMs(lengthPrefixedTextKey(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;
@@ -3533,7 +5449,10 @@ export class AUNClient {
                     }
                 }
             }
-            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 = isJsonObject(bootstrapResp) && Array.isArray(bootstrapResp.devices)
                 ? bootstrapResp.devices.filter(isJsonObject)
                 : [];
@@ -3719,30 +5638,45 @@ 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 ──
+        // 即使 pushSeq 是脏数据（如服务端 bug 导致的 99999），也只影响"已知上界"，
+        // 不会污染下界 contiguousSeq，更不会导致 SDK 把脏数据 ack 回服务端。
+        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._decryptV2PushMessage(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);
+                    // 解密成功也不能先推进 contiguousSeq；必须等应用层发布返回后再推进和 ACK。
+                    const published = await this._publishOrderedMessage('message.received', ns, pushSeq, decrypted);
                     const newContig = this._seqTracker.getContiguousSeq(ns);
+                    const needPull = pushSeq > newContig && !published;
                     if (newContig !== contigBefore) {
                         this._saveSeqTrackerState();
                     }
                     if (newContig > 0 && newContig !== contigBefore) {
-                        this._transport.call('message.v2.ack', { up_to_seq: newContig })
+                        // ack clamp：永远不发送超过 maxSeenSeq 的 up_to_seq
+                        const maxSeen = this._seqTracker.getMaxSeenSeq(ns);
+                        const ackSeq = maxSeen > 0 ? Math.min(newContig, maxSeen) : newContig;
+                        this.call('message.v2.ack', { up_to_seq: ackSeq, _rpc_background: true })
                             .catch(e => this._clientLog.debug(`V2 P2P push-ack failed: ${formatCaughtError(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) {
@@ -3753,38 +5687,37 @@ export class AUNClient {
         // 纯通知只表示服务端已有 pushSeq 这条消息，内容还没有进入本地，不能先推进 contiguousSeq。
         // 后续 pull 必须从当前 contiguousSeq 开始，否则会跳过 pushSeq 本身。
         if (pushSeq > 0 && ns) {
-            if (contigBefore >= pushSeq) {
-                this._clientLog.warn(`_onV2PushNotification: contiguous_seq=${contigBefore} 越界（>= push_seq=${pushSeq}），强制修复为 ${pushSeq - 1}`);
-                this._seqTracker.forceContiguousSeq(ns, pushSeq - 1);
-                contigBefore = pushSeq - 1;
-            }
             this._clientLog.debug(`_onV2PushNotification: 纯通知 push_seq=${pushSeq} > contiguous_seq=${contigBefore}, 触发 pull(after_seq=${contigBefore})`);
         }
-        if (this._v2PullInflight) {
-            this._v2PullPending = true;
+        if (!ns)
             return;
-        }
-        this._v2PullInflight = true;
-        try {
-            do {
-                this._v2PullPending = false;
-                await this.pullV2();
-                const newContig = ns ? this._seqTracker.getContiguousSeq(ns) : -1;
+        void this._tryRunBackgroundPull(ns, async () => {
+            const operationBefore = this._seqTracker.getContiguousSeq(ns);
+            const dedupKey = `p2p_pull:${ns}`;
+            if (this._gapFillDone.has(dedupKey))
+                return 0;
+            this._gapFillDone.set(dedupKey, Date.now());
+            try {
+                const pulled = await this.pullV2(0, 50, { gateLocked: true });
+                const newContig = this._seqTracker.getContiguousSeq(ns);
                 this._clientLog.debug(`_onV2PushNotification pull done: contiguous_seq=${contigBefore}->${newContig} (push_seq=${pushSeq || 'null'})`);
-            } while (this._v2PullPending);
-        }
-        catch (exc) {
-            const newContig = ns ? this._seqTracker.getContiguousSeq(ns) : -1;
+                if (newContig <= operationBefore)
+                    return 0;
+                return pulled.length;
+            }
+            finally {
+                this._gapFillDone.delete(dedupKey);
+            }
+        }, true).catch((exc) => {
+            const newContig = this._seqTracker.getContiguousSeq(ns);
             this._clientLog.warn(`V2 push auto-pull failed: contiguous_seq=${contigBefore}->${newContig} err=${formatCaughtError(exc)}`);
-        }
-        finally {
-            this._v2PullInflight = false;
-        }
+        });
     }
     async _onV2StateProposed(data) {
         if (!isJsonObject(data) || !this._v2Session)
             return;
-        const groupId = String(data.group_id ?? '').trim();
+        const rawGroupId = String(data.group_id ?? '').trim();
+        const groupId = normalizeGroupId(rawGroupId) || rawGroupId;
         if (!groupId)
             return;
         await this._dispatcher.publish('group.v2.state_proposed', data);
@@ -3798,7 +5731,8 @@ export class AUNClient {
     async _onV2StateRetryNeeded(data) {
         if (!isJsonObject(data) || !this._v2Session)
             return;
-        const groupId = String(data.group_id ?? '').trim();
+        const rawGroupId = String(data.group_id ?? '').trim();
+        const groupId = normalizeGroupId(rawGroupId) || rawGroupId;
         if (!groupId)
             return;
         await this._dispatcher.publish('group.v2.state_retry_needed', data);
@@ -3812,7 +5746,8 @@ export class AUNClient {
     async _onV2StateConfirmed(data) {
         if (!isJsonObject(data))
             return;
-        const groupId = String(data.group_id ?? '').trim();
+        const rawGroupId = String(data.group_id ?? '').trim();
+        const groupId = normalizeGroupId(rawGroupId) || rawGroupId;
         if (groupId) {
             this._v2BootstrapCache.delete(`group:${groupId}`);
             this._v2AutoProposeLastSnapshot.delete(groupId);
@@ -3820,29 +5755,51 @@ export class AUNClient {
         await this._dispatcher.publish('group.v2.state_confirmed', data);
     }
     async _onRawGroupV2MessageCreated(data) {
-        if (!isJsonObject(data) || !this._v2Session)
+        if (!isJsonObject(data) || !this._v2Session) {
+            this._clientLog.debug(`_onRawGroupV2MessageCreated skipped: is_object=${String(isJsonObject(data))}, has_v2_session=${String(!!this._v2Session)}`);
             return;
-        const groupId = String(data.group_id ?? '').trim();
+        }
+        this._logMessageDebug('server-push', '_raw.group.v2.message_created', 'group.message_created', data);
+        const rawGroupId = String(data.group_id ?? '').trim();
+        const groupId = normalizeGroupId(rawGroupId) || rawGroupId;
         const seq = Number(data.seq ?? 0);
-        if (!groupId || !Number.isFinite(seq) || seq <= 0)
+        if (!groupId || !Number.isFinite(seq) || seq <= 0) {
+            this._clientLog.debug(`_onRawGroupV2MessageCreated skipped: group=${groupId || '<empty>'}, seq=${String(data.seq ?? '')}`);
             return;
+        }
         const ns = `group:${groupId}`;
-        if (this._pushedSeqs.get(ns)?.has(seq))
-            return;
-        const afterSeq = this._seqTracker.getContiguousSeq(ns);
-        const dedupKey = `v2_group_push:${groupId}:${afterSeq}`;
-        if (this._gapFillDone.has(dedupKey))
+        // Push 修上界：先更新 maxSeenSeq
+        this._seqTracker.updateMaxSeen(ns, seq);
+        const contigBefore = this._seqTracker.getContiguousSeq(ns);
+        this._clientLog.debug(`_onRawGroupV2MessageCreated enter: group=${groupId}, seq=${seq}, contiguous=${contigBefore}, max_seen=${this._seqTracker.getMaxSeenSeq(ns)}`);
+        if (contigBefore === seq) {
+            this._clientLog.debug(`_onRawGroupV2MessageCreated duplicate push already covered: group=${groupId} seq=${seq}`);
             return;
-        this._gapFillDone.set(dedupKey, Date.now());
-        try {
-            await this.pullGroupV2(groupId, afterSeq, 50);
         }
-        catch (exc) {
+        const afterSeq = this._repairPushContiguousBound(ns, seq, false, '_raw.group.v2.message_created');
+        const dedupKey = `v2_group_push:${groupId}:${afterSeq}`;
+        void this._tryRunBackgroundPull(ns, async () => {
+            const pullAfterSeq = this._seqTracker.getContiguousSeq(ns);
+            if (this._gapFillDone.has(dedupKey)) {
+                this._clientLog.debug(`_onRawGroupV2MessageCreated skipped duplicate in-flight pull: group=${groupId}, dedup=${dedupKey}`);
+                return 0;
+            }
+            this._gapFillDone.set(dedupKey, Date.now());
+            try {
+                this._clientLog.debug(`_onRawGroupV2MessageCreated auto-pull start: group=${groupId}, after_seq=${pullAfterSeq}, push_seq=${seq}`);
+                const pulled = await this.pullGroupV2(groupId, pullAfterSeq, 50, { gateLocked: true });
+                const newContig = this._seqTracker.getContiguousSeq(ns);
+                this._clientLog.debug(`_onRawGroupV2MessageCreated auto-pull done: group=${groupId}, after_seq=${pullAfterSeq}, push_seq=${seq}, contiguous=${newContig}`);
+                if (newContig <= pullAfterSeq)
+                    return 0;
+                return pulled.length;
+            }
+            finally {
+                this._gapFillDone.delete(dedupKey);
+            }
+        }, true).catch((exc) => {
             this._clientLog.warn(`V2 group push auto-pull failed: group=${groupId} err=${formatCaughtError(exc)}`);
-        }
-        finally {
-            this._gapFillDone.delete(dedupKey);
-        }
+        });
     }
     /** Push 通知带 payload 时的就地解密（复用 _decryptV2Message） */
     async _decryptV2PushMessage(data) {
@@ -3869,6 +5826,11 @@ export class AUNClient {
     }
     /** 从参数中解析 Gateway URL */
     _resolveGateway(params) {
+        const gateways = this._resolveGateways(params);
+        return gateways[0];
+    }
+    /** 从参数中解析所有 Gateway URL（支持 string 或 string[]） */
+    _resolveGateways(params) {
         const topology = params.topology;
         if (isJsonObject(topology)) {
             const topo = topology;
@@ -3880,11 +5842,16 @@ export class AUNClient {
                 throw new ValidationError('relay topology is not implemented in the TypeScript SDK');
             }
         }
-        const gateway = String(params.gateway ?? '');
-        if (!gateway) {
-            throw new StateError('missing gateway in connect params');
+        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;
+        }
+        if (typeof gw === 'string' && gw) {
+            return [gw];
         }
-        return gateway;
+        throw new StateError('missing gateway in connect params');
     }
     /** 连接后同步身份信息 */
     _syncIdentityAfterConnect(accessToken) {
@@ -4138,6 +6105,16 @@ export class AUNClient {
         };
         scheduleNext(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');