@agentunion/fastaun 0.3.3 → 0.3.5

package/dist/client.js

@@ -36,6 +36,9 @@ import { encryptP2PMessage, encryptGroupMessage, decryptMessage, } from './v2/e2
 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)
@@ -197,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;
@@ -364,15 +420,14 @@ export class AUNClient {
     _defaultConnectDeliveryMode;
     /** peer 证书缓存 */
     _certCache = new Map();
-    // AgentMDs 目录：{agentMdPath}/list.json 保存元数据，{agentMdPath}/{aid}/agent.md 保存正文。
+    // 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 Set();
-    _agentMdLastListRebuilt = false;
+    _agentMdFetchInflight = new Map();
     /** 消息序列号跟踪器（群消息 + P2P 空洞检测） */
     _seqTracker = new SeqTracker();
     _seqTrackerContext = null;
@@ -380,10 +435,17 @@ 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();
+    /** P2P pull 进行中到达的纯通知 push 上界；pull gate 释放后需要补拉一次。 */
+    _pendingP2pPullUpper = new Map();
     /** 缺 sender IK 时暂存原始 V2 消息，后台补齐 IK 后重试解密。 */
     _v2SenderIKPending = new Map();
     /** sender IK 后台补齐任务去重。 */
@@ -409,10 +471,9 @@ 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 PULL_GATE_STALE_MS = 3000;
     static V2_SIG_CACHE_TTL_MS = 60 * 60 * 1000;
     static V2_SIG_CACHE_MAX = 16_384;
     _reconnectActive = false;
@@ -426,7 +487,7 @@ export class AUNClient {
         const rawConfig = { ...(config ?? {}) };
         this._configModel = configFromMap(rawConfig);
         const initAid = String(rawConfig.aid ?? '').trim() || null;
-        this._agentMdPath = path.join(this._configModel.aunPath, 'AgentMDs');
+        this._agentMdPath = path.join(this._configModel.aunPath, 'AIDs');
         this.config = {
             aun_path: this._configModel.aunPath,
             root_ca_path: this._configModel.rootCaPath,
@@ -456,6 +517,19 @@ export class AUNClient {
             secretStoreLogger: this._logger.for('aun_core.secret-store'),
         });
         this._keystore = keystore;
+        // 启动时被动清理 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 };
@@ -547,6 +621,23 @@ export class AUNClient {
         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 ?? '');
@@ -585,11 +676,11 @@ export class AUNClient {
         };
     }
     /**
-     * 设置 agent.md 本地存储根目录；为空时恢复默认 {aun_path}/AgentMDs。
+     * 设置 agent.md 本地存储根目录；为空时恢复默认 {aun_path}/AIDs。
      */
     setAgentMdPath(root) {
         const raw = String(root ?? '').trim();
-        const next = raw || path.join(this._configModel.aunPath, 'AgentMDs');
+        const next = raw || path.join(this._configModel.aunPath, 'AIDs');
         fs.mkdirSync(next, { recursive: true });
         this._agentMdPath = next;
         this._agentMdCache.clear();
@@ -662,15 +753,15 @@ export class AUNClient {
         return target;
     }
     _agentMdRoot() {
-        const root = this._agentMdPath || path.join(this._configModel.aunPath, 'AgentMDs');
+        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');
     }
-    _agentMdListPath() {
-        return path.join(this._agentMdRoot(), 'list.json');
+    _agentMdMetaPath(aid) {
+        return path.join(this._agentMdRoot(), this._agentMdSafeAid(aid), 'agentmd.json');
     }
     _atomicWriteText(filePath, content) {
         fs.mkdirSync(path.dirname(filePath), { recursive: true });
@@ -712,8 +803,9 @@ export class AUNClient {
     _sleepSync(ms) {
         Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
     }
-    _withAgentMdListLock(fn) {
-        const lockPath = path.join(this._agentMdRoot(), 'list.json.lock');
+    _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) {
@@ -749,93 +841,39 @@ export class AUNClient {
             catch { /* ignore */ }
         }
     }
-    _writeAgentMdListUnlocked(records) {
-        const sorted = {};
-        for (const aid of Object.keys(records).sort())
-            sorted[aid] = records[aid];
-        this._atomicWriteText(this._agentMdListPath(), `${JSON.stringify({ version: 1, updated_at: Date.now(), records: sorted }, null, 2)}\n`);
-    }
-    _normalizeAgentMdList(data) {
-        const records = {};
-        let iterable = [];
-        if (isJsonObject(data)) {
-            const rawRecords = data.records;
-            if (Array.isArray(rawRecords))
-                iterable = rawRecords;
-            else if (isJsonObject(rawRecords)) {
-                iterable = Object.values(rawRecords);
-            }
+    _writeAgentMdRecordUnlocked(aid, record) {
+        const payload = {};
+        for (const [key, value] of Object.entries(record)) {
+            if (key !== 'content' && value !== undefined && value !== null)
+                payload[key] = value;
         }
-        else if (Array.isArray(data)) {
-            iterable = data;
-        }
-        for (const item of iterable) {
-            if (!isJsonObject(item))
-                continue;
-            const aid = String(item.aid ?? '').trim();
-            if (!aid)
-                continue;
-            const record = {};
-            for (const [key, value] of Object.entries(item)) {
-                if (key !== 'content')
-                    record[key] = value;
-            }
-            record.aid = aid;
-            for (const key of ['fetched_at', 'observed_at', 'checked_at', 'updated_at']) {
-                record[key] = Number(record[key] ?? 0) || 0;
-            }
-            records[aid] = record;
-        }
-        return records;
+        payload.aid = this._agentMdSafeAid(aid);
+        this._atomicWriteText(this._agentMdMetaPath(aid), `${JSON.stringify(payload, null, 2)}\n`);
     }
-    _rebuildAgentMdListUnlocked() {
-        const records = {};
-        const root = this._agentMdRoot();
-        const now = Date.now();
-        for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
-            if (!entry.isDirectory())
-                continue;
-            const aid = entry.name;
-            const filePath = path.join(root, aid, 'agent.md');
-            if (!fs.existsSync(filePath))
-                continue;
-            try {
-                const content = fs.readFileSync(filePath, 'utf-8');
-                let fetchedAt = now;
-                try {
-                    fetchedAt = Math.trunc(fs.statSync(filePath).mtimeMs);
-                }
-                catch { /* ignore */ }
-                records[aid] = {
-                    aid,
-                    local_etag: this._agentMdContentEtag(content),
-                    fetched_at: fetchedAt,
-                    updated_at: now,
-                };
-            }
-            catch (err) {
-                this._clientLog.warn(`agent.md rebuild skipped unreadable file aid=${aid} err=${err instanceof Error ? err.message : String(err)}`);
-            }
+    _normalizeAgentMdRecord(aid, data) {
+        if (!isJsonObject(data))
+            return {};
+        const record = {};
+        for (const [key, value] of Object.entries(data)) {
+            if (key !== 'content')
+                record[key] = value;
         }
-        this._writeAgentMdListUnlocked(records);
-        this._agentMdCache.clear();
-        return records;
-    }
-    _readAgentMdListUnlocked() {
-        const filePath = this._agentMdListPath();
-        if (!fs.existsSync(filePath)) {
-            this._agentMdLastListRebuilt = true;
-            return this._rebuildAgentMdListUnlocked();
+        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 {
-            const parsed = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
-            this._agentMdLastListRebuilt = false;
-            return this._normalizeAgentMdList(parsed);
+            return this._normalizeAgentMdRecord(aid, JSON.parse(fs.readFileSync(filePath, 'utf-8')));
         }
         catch (err) {
-            this._clientLog.warn(`agent.md list.json damaged, rebuilding: ${err instanceof Error ? err.message : String(err)}`);
-            this._agentMdLastListRebuilt = true;
-            return this._rebuildAgentMdListUnlocked();
+            this._clientLog.warn(`agent.md metadata damaged, ignoring: aid=${aid} err=${err instanceof Error ? err.message : String(err)}`);
+            return {};
         }
     }
     _readAgentMdContent(aid) {
@@ -861,21 +899,25 @@ export class AUNClient {
         if (!target)
             return null;
         try {
-            const records = this._withAgentMdListLock(() => this._readAgentMdListUnlocked());
-            const record = records[target];
-            if (record && typeof record === 'object') {
-                const loaded = { ...record, aid: target };
+            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);
-                    loaded.content = content;
-                    loaded.local_etag = this._agentMdContentEtag(content);
+                    next.content = content;
+                    next.local_etag = this._agentMdContentEtag(content);
                 }
                 catch (err) {
-                    this._clientLog.warn(`agent.md content read failed: aid=${target} err=${err instanceof Error ? err.message : String(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)}`);
+                    }
                 }
-                this._agentMdCache.set(target, { ...loaded });
-                return { ...loaded };
-            }
+                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)}`);
@@ -890,25 +932,23 @@ export class AUNClient {
             const inputFields = { ...fields };
             const hasContent = Object.prototype.hasOwnProperty.call(inputFields, 'content') && inputFields.content !== undefined && inputFields.content !== null;
             let savedTo = '';
-            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 record = this._withAgentMdListLock(() => {
-                const records = this._readAgentMdListUnlocked();
-                const next = { ...(records[target] ?? {}), aid: target };
+            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();
-                records[target] = { ...next };
-                this._writeAgentMdListUnlocked(records);
+                this._writeAgentMdRecordUnlocked(target, next);
                 return next;
             });
             const loaded = { ...record };
@@ -967,15 +1007,12 @@ export class AUNClient {
             return;
         if (this._agentMdFetchInflight.has(target))
             return;
-        this._agentMdFetchInflight.add(target);
         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)}`);
-        }).finally(() => {
-            this._agentMdFetchInflight.delete(target);
         });
     }
     _observeAgentMdMeta(aid, etag = '', lastModified = '', source = '') {
@@ -1026,7 +1063,7 @@ export class AUNClient {
         }
         this._observeAgentMdMeta(senderAid, String(sender.etag ?? '').trim(), String(sender.last_modified ?? sender.lastModified ?? '').trim(), 'envelope');
     }
-    async checkAgentMd(aid, maxUnsyncedDays = 0) {
+    async checkAgentMd(aid, maxUnsyncedDays = 1) {
         const target = String(aid ?? this._aid ?? '').trim();
         if (!target)
             throw new ValidationError('checkAgentMd requires aid (or local AID)');
@@ -1035,7 +1072,9 @@ export class AUNClient {
         const localFound = !!(Object.keys(before).length > 0 && (String(before.content ?? '') || localEtag));
         const remoteEtagCached = String(before.remote_etag ?? '').trim();
         const lastModifiedCached = String(before.last_modified ?? '').trim();
-        const checkedAtCached = Number(before.checked_at ?? 0);
+        const 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)) {
@@ -1053,6 +1092,25 @@ export class AUNClient {
                 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 {
@@ -1244,11 +1302,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') {
@@ -1258,10 +1322,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);
@@ -1270,7 +1336,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) {
@@ -1278,6 +1344,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 调用。
@@ -1297,6 +1397,13 @@ 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);
             }
@@ -1318,17 +1425,33 @@ export class AUNClient {
             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);
@@ -1338,12 +1461,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);
             }
@@ -1355,7 +1478,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') {
@@ -1363,26 +1486,42 @@ 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)) {
@@ -1399,8 +1538,12 @@ export class AUNClient {
                 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);
@@ -1486,6 +1629,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();
@@ -1575,7 +1746,7 @@ export class AUNClient {
                     _decrypt_error: String(exc),
                 };
                 this._attachV2EnvelopeMetadataFromSource(safeEvent, data);
-                this._publishAppEvent('message.undecryptable', safeEvent).catch(() => { });
+                Promise.resolve(this._publishAppEvent('message.undecryptable', safeEvent)).catch(() => { });
             }
         });
         this._clientLog.debug(`_onRawMessageReceived exit: elapsed=${Date.now() - tStart}ms (handler dispatched)`);
@@ -1595,12 +1766,15 @@ export class AUNClient {
         const seq = msg.seq;
         if (seq !== undefined && seq !== null && this._aid) {
             const ns = `p2p:${this._aid}`;
-            // Push 修上界：先更新 maxSeenSeq，让上界反映服务端状态
+            // Push 只先更新 maxSeenSeq；contiguous_seq 是已交付游标，必须等应用层发布返回后再推进。
             if (seq > 0)
                 this._seqTracker.updateMaxSeen(ns, seq);
-            const needPull = this._seqTracker.onMessageSeq(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
@@ -1609,23 +1783,16 @@ export class AUNClient {
                 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._transport.call('message.ack', {
-                    seq: ackSeq,
-                    device_id: this._deviceId,
-                    slot_id: this._slotId,
-                })
+                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 {
+            // V2-only：普通 _raw.message.received 只承载明文；V2 密文由 peer.v2.message_received 通知触发 pull。
             await this._publishAppEvent('message.received', msg, 'push');
         }
     }
@@ -1652,7 +1819,7 @@ export class AUNClient {
                     _decrypt_error: String(exc),
                 };
                 this._attachV2EnvelopeMetadataFromSource(safeEvent, data);
-                this._publishAppEvent('group.message_undecryptable', safeEvent).catch(() => { });
+                Promise.resolve(this._publishAppEvent('group.message_undecryptable', safeEvent)).catch(() => { });
             }
         });
         this._clientLog.debug(`_onRawGroupMessageCreated exit: elapsed=${Date.now() - tStart}ms (handler dispatched)`);
@@ -1678,17 +1845,22 @@ 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}`;
-            // Push 修上界：先更新 maxSeenSeq
+            // Push 只先更新 maxSeenSeq；contiguous_seq 是已交付游标，必须等应用层发布返回后再推进。
             if (seq > 0)
                 this._seqTracker.updateMaxSeen(ns, seq);
-            const needPull = this._seqTracker.onMessageSeq(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);
@@ -1696,118 +1868,65 @@ export class AUNClient {
                 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._transport.call('group.ack_messages', {
-                    group_id: groupId,
-                    msg_seq: ackSeq,
-                    device_id: this._deviceId,
-                    slot_id: this._slotId,
-                })
+                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)}`); });
             }
-            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);
+            if (contigAfter !== contigBefore)
+                this._saveSeqTrackerState();
         }
         else {
+            // 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);
         this._clientLog.debug(`auto pull group messages start: group=${groupId}, after_seq=${afterSeq}, seq=${String(notification.seq ?? '')}`);
-        try {
-            // V2-only 模式：走 group.v2.pull（合并 V1 明文 + V2 密文并自动解密）
-            if (this._v2Session) {
-                await this._pullGroupV2Internal({ group_id: groupId, after_seq: afterSeq, limit: 50 });
-                this._clientLog.debug(`auto pull group messages done(v2): group=${groupId}, after_seq=${afterSeq}`);
-                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)) {
-                                this._clientLog.debug(`auto pull group message skipped duplicate: group=${groupId}, seq=${s}`);
-                                continue; // 已发布到应用层，跳过
-                            }
-                            if (s !== undefined && s !== null) {
-                                await this._publishPulledMessage('group.message_created', ns, s, msg);
-                            }
-                            else {
-                                await this._publishAppEvent('group.message_created', msg, 'pull');
-                            }
-                        }
-                    }
-                    this._prunePushedSeqs(ns);
-                    return;
-                }
-            }
-        }
-        catch (exc) {
-            this._clientLog.debug(`auto pull group messages failed: ${formatCaughtError(exc)}`);
+        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, 'group-push-fallback');
     }
     /** 后台补齐群消息空洞 */
     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}`);
         }
@@ -1816,6 +1935,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 消息空洞 */
@@ -1828,35 +1951,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}`);
         }
@@ -1865,6 +1978,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 清理。 */
@@ -1877,6 +1994,38 @@ export class AUNClient {
             this._pushedSeqs.set(ns, new Set(keep));
         }
     }
+    _recordPendingP2pPull(ns, seq) {
+        if (!ns || seq <= 0)
+            return;
+        const previous = this._pendingP2pPullUpper.get(ns) ?? 0;
+        if (seq > previous) {
+            this._pendingP2pPullUpper.set(ns, seq);
+        }
+        this._clientLog.debug(`P2P pending pull upper recorded: ns=${ns}, seq=${seq}, previous=${previous}, contiguous=${this._seqTracker.getContiguousSeq(ns)}`);
+    }
+    _schedulePendingP2pPullIfNeeded(ns, reason) {
+        if (!ns)
+            return false;
+        const upperSeq = this._pendingP2pPullUpper.get(ns) ?? 0;
+        if (upperSeq <= 0) {
+            this._pendingP2pPullUpper.delete(ns);
+            return false;
+        }
+        const contig = this._seqTracker.getContiguousSeq(ns);
+        if (upperSeq <= contig) {
+            this._pendingP2pPullUpper.delete(ns);
+            this._clientLog.debug(`P2P pending pull upper already covered: ns=${ns}, upper_seq=${upperSeq}, contiguous=${contig}, reason=${reason}`);
+            return false;
+        }
+        if (this._state !== 'connected' || this._closing) {
+            this._clientLog.debug(`P2P pending pull postponed: ns=${ns}, upper_seq=${upperSeq}, contiguous=${contig}, state=${this._state}, closing=${this._closing}, reason=${reason}`);
+            return false;
+        }
+        this._pendingP2pPullUpper.delete(ns);
+        this._clientLog.info(`P2P pending push follow-up pull scheduled: ns=${ns}, upper_seq=${upperSeq}, contiguous=${contig}, reason=${reason}`);
+        void this._fillP2pGap();
+        return true;
+    }
     _markPublishedSeq(ns, seq) {
         let pushed = this._pushedSeqs.get(ns);
         if (!pushed) {
@@ -1925,7 +2074,7 @@ export class AUNClient {
             return payload;
         return this._attachCurrentInstanceContext(payload);
     }
-    async _publishAppEvent(event, payload, source = 'direct') {
+    _publishAppEvent(event, payload, source = 'direct') {
         if ((event === 'message.received' || event === 'group.message_created') && isJsonObject(payload)) {
             this._maybeAppendEchoTraceReceive(payload);
         }
@@ -1949,7 +2098,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();
@@ -2102,25 +2251,280 @@ export class AUNClient {
         }
         return true;
     }
-    async _drainOrderedMessages(ns, beforeSeq) {
+    _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;
+        if (key.startsWith('p2p:')) {
+            this._schedulePendingP2pPullIfNeeded(key, 'pull-gate-release');
+        }
+    }
+    _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();
+        }
+        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, onBusy) {
+        if (key && this._isPullResponseProcessing(key)) {
+            onBusy?.();
+            return false;
+        }
+        const token = this._tryAcquirePullGate(key);
+        if (token === null) {
+            onBusy?.();
+            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, 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)
                 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, 'ordered-drain');
+            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)
@@ -2130,7 +2534,9 @@ export class AUNClient {
         const seqNum = Number(seq);
         if (!Number.isFinite(seqNum) || !Number.isInteger(seqNum) || seqNum <= 0) {
             this._clientLog.debug(`publish ordered direct(no-seq): event=${event}, ns=${ns || '<none>'}, seq=${String(seq)}`);
-            await this._publishAppEvent(event, payload, 'ordered');
+            const published = this._publishAppEvent(event, payload, 'ordered');
+            if (isPromiseLike(published))
+                await published;
             return true;
         }
         if (this._pushedSeqs.get(ns)?.has(seqNum)) {
@@ -2142,7 +2548,15 @@ 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;
@@ -2156,17 +2570,25 @@ export class AUNClient {
         queue?.delete(seqNum);
         if (queue && queue.size === 0)
             this._pendingOrderedMsgs.delete(ns);
-        await this._publishAppEvent(event, payload, 'ordered');
+        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) {
             this._clientLog.debug(`publish pulled direct(no-seq): event=${event}, ns=${ns || '<none>'}, seq=${String(seq)}`);
-            await this._publishAppEvent(event, payload, 'pull');
+            const published = this._withPullResponseProcessing(ns, () => this._publishAppEvent(event, payload, 'pull'));
+            if (isPromiseLike(published))
+                await published;
             return true;
         }
         const queue = this._pendingOrderedMsgs.get(ns);
@@ -2180,22 +2602,51 @@ export class AUNClient {
         queue?.delete(seqNum);
         if (queue && queue.size === 0)
             this._pendingOrderedMsgs.delete(ns);
-        await this._publishAppEvent(event, payload, 'pull');
+        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());
+        let filled = 0;
         try {
-            let filled = 0;
             let nextAfterSeq = afterSeq;
             const maxPages = 100;
             let pageCount = 0;
@@ -2207,6 +2658,7 @@ export class AUNClient {
                     after_event_seq: nextAfterSeq,
                     device_id: this._deviceId,
                     limit: 50,
+                    _pull_gate_locked: true,
                 });
                 if (!isJsonObject(result))
                     return;
@@ -2215,16 +2667,12 @@ export class AUNClient {
                     return;
                 const pageContigBefore = this._seqTracker.getContiguousSeq(ns);
                 const eventObjects = events.filter(isJsonObject);
-                if (eventObjects.length > 0) {
-                    this._seqTracker.onPullResult(ns, eventObjects, nextAfterSeq);
-                }
-                const cursor = isJsonObject(result.cursor) ? result.cursor : null;
-                const serverAck = cursor ? Number(cursor.current_seq ?? 0) : 0;
-                if (serverAck > 0) {
+                const retentionFloor = this._pullRetentionFloor(result, 'retention_floor_event_seq', 'retention_floor_event_seq');
+                if (retentionFloor > 0) {
                     const contigBeforeFloor = this._seqTracker.getContiguousSeq(ns);
-                    if (contigBeforeFloor < serverAck) {
-                        this._clientLog.info(`group.pull_events retention-floor advance: ns=${ns} contiguous=${contigBeforeFloor} -> cursor.current_seq=${serverAck}`);
-                        this._seqTracker.forceContiguousSeq(ns, serverAck);
+                    if (contigBeforeFloor < retentionFloor) {
+                        this._clientLog.info(`group.pull_events retention-floor advance: ns=${ns} contiguous=${contigBeforeFloor} -> retention_floor=${retentionFloor}`);
+                        this._seqTracker.forceContiguousSeq(ns, retentionFloor);
                     }
                 }
                 const eventSeqs = [];
@@ -2235,20 +2683,23 @@ export class AUNClient {
                     evt._from_gap_fill = true;
                     const et = String(evt.event_type ?? '');
                     // 消息事件由 _fillGroupGap 负责，事件补洞不重复投递
-                    if (et === 'group.message_created')
-                        continue;
-                    // 验签：有 client_signature 就验（与实时事件路径对齐）
-                    const cs = evt.client_signature;
-                    if (cs && typeof cs === 'object') {
-                        if (this._shouldSkipEventSignature(evt)) {
-                            delete evt.client_signature;
-                        }
-                        else {
-                            evt._verified = await this._verifyEventSignatureAsync(evt, cs);
+                    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);
+                    }
+                    if (Number.isFinite(eventSeq) && eventSeq > 0) {
+                        this._markPulledSeqDelivered(ns, eventSeq);
                     }
-                    // group.changed 或缺失/其他 → 发布到 group.changed（向后兼容）
-                    await this._dispatcher.publish('group.changed', evt);
                     filled += 1;
                 }
                 const contig = this._seqTracker.getContiguousSeq(ns);
@@ -2263,12 +2714,11 @@ export class AUNClient {
                         event_seq: ackSeq,
                         device_id: this._deviceId,
                         slot_id: this._slotId,
-                    }).catch((e) => { this._clientLog.debug(`group event auto-ack failed: group=${groupId} ${formatCaughtError(e)}`); });
+                    }, undefined, undefined, true).catch((e) => { this._clientLog.debug(`group event auto-ack failed: group=${groupId} ${formatCaughtError(e)}`); });
                 }
-                const nextAfter = Math.max(eventSeqs.length > 0 ? Math.max(...eventSeqs) : nextAfterSeq, nextAfterSeq);
-                if (eventObjects.length === 0 || nextAfter <= nextAfterSeq || result.has_more === false)
-                    break;
-                nextAfterSeq = nextAfter;
+                // 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}`);
@@ -2280,6 +2730,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) {
@@ -2363,7 +2817,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 时才触发补拉（补洞回来的事件不再触发新补洞）
@@ -2569,11 +3023,85 @@ export class AUNClient {
             return false;
         }
     }
-    /**
-     * 获取对方证书（带缓存 + 完整 PKI 验证）。  /**
-     * 获取对方证书（带缓存 + 完整 PKI 验证）。
-     * 跨域时自动路由到 peer 所在域的 Gateway。
-     */
+    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 ?? ''}`);
@@ -2589,67 +3117,107 @@ 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, timeoutMs);
+                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, timeoutMs);
-                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) {
@@ -2893,6 +3461,7 @@ export class AUNClient {
         this._gapFillDone.clear();
         this._pushedSeqs.clear();
         this._pendingOrderedMsgs.clear();
+        this._pendingP2pPullUpper.clear();
         this._v2SenderIKPending.clear();
         this._v2SenderIKFetching.clear();
         this._groupSynced.clear();
@@ -2905,6 +3474,7 @@ export class AUNClient {
         this._gapFillDone.clear();
         this._pushedSeqs.clear();
         this._pendingOrderedMsgs.clear();
+        this._pendingP2pPullUpper.clear();
         this._v2SenderIKPending.clear();
         this._v2SenderIKFetching.clear();
         this._groupSynced.clear();
@@ -3108,7 +3678,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)}`);
@@ -3200,7 +3770,7 @@ 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();
@@ -3379,7 +3949,11 @@ export class AUNClient {
             const session = this._v2Session;
             if (session && fromAid) {
                 try {
-                    const bs = await this.call('message.v2.bootstrap', { peer_aid: fromAid });
+                    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);
@@ -3389,7 +3963,10 @@ export class AUNClient {
                 }
                 if (groupId) {
                     try {
-                        const gbs = await this.call('group.v2.bootstrap', { group_id: groupId });
+                        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)
@@ -3448,14 +4025,21 @@ 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}`);
@@ -3464,6 +4048,7 @@ export class AUNClient {
                     devices: peerDevices,
                     auditRecipients: auditRaw,
                     cachedAt: Date.now(),
+                    wrapPolicy,
                 });
             }
         }
@@ -3504,13 +4089,19 @@ 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,
                         });
                     }
                 }
@@ -3536,7 +4127,10 @@ export class AUNClient {
         if (targets.length === 0) {
             throw new E2EEError(`V2 bootstrap: no usable devices found for ${to}`);
         }
-        const envelope = 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,
@@ -3606,18 +4200,30 @@ 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}` : '';
+        if (ns && !opts?.gateLocked) {
+            return await this._runPullSerialized(ns, async () => this.pullV2(afterSeq, limit, {
+                ...(opts ?? {}),
+                gateLocked: true,
+                scheduleFollowup: true,
+            }));
+        }
         const decrypted = [];
+        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.call('message.v2.pull', { after_seq: nextAfterSeq, limit });
+            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);
@@ -3626,10 +4232,13 @@ export class AUNClient {
                 .map((msg) => Number(msg.seq ?? 0))
                 .filter((seq) => Number.isFinite(seq) && seq > 0);
             const pageContigBefore = ns ? this._seqTracker.getContiguousSeq(ns) : 0;
-            const pageMaxSeq = seqs.length > 0 ? Math.max(...seqs) : nextAfterSeq;
-            if (ns && seqs.length > 0) {
-                this._seqTracker.forceContiguousSeq(ns, pageMaxSeq);
-                this._clientLog.debug(`message.v2.pull force contiguous: ns=${ns}, page_max_seq=${pageMaxSeq}, previous=${pageContigBefore}`);
+            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);
@@ -3653,10 +4262,12 @@ export class AUNClient {
                             payload: legacyPayload,
                             encrypted: false,
                         };
-                        if (ns)
+                        if (ns) {
                             await this._publishPulledMessage('message.received', ns, seq, v1Msg);
-                        else
+                        }
+                        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>'}`);
                     }
@@ -3678,10 +4289,12 @@ export class AUNClient {
                     this._clientLog.debug(`message.v2.pull decrypt returned null: seq=${seq}, ns=${ns || '<none>'}`);
                     continue;
                 }
-                if (ns)
+                if (ns) {
                     await this._publishPulledMessage('message.received', ns, seq, plaintext);
-                else
+                }
+                else {
                     await this._publishAppEvent('message.received', plaintext, 'pull');
+                }
                 decrypted.push(plaintext);
                 this._logMessageDebug('decrypt-ok', 'message.v2.pull', 'message.received', plaintext);
             }
@@ -3697,10 +4310,10 @@ export class AUNClient {
                 const ackSeq = this._seqTracker.getContiguousSeq(ns);
                 const contigAdvanced = ackSeq !== pageContigBefore;
                 if (contigAdvanced) {
-                    await this._drainOrderedMessages(ns);
+                    await this._drainOrderedMessages(ns, undefined, true);
                     this._saveSeqTrackerState();
                 }
-                if (messages.length > 0 && contigAdvanced && ackSeq > 0) {
+                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));
                 }
@@ -3733,7 +4346,7 @@ export class AUNClient {
             }
         }
         this._clientLog.debug(`message.v2.ack send: ns=${ns || '<none>'}, up_to_seq=${seq}`);
-        const raw = await this.call('message.v2.ack', { up_to_seq: seq });
+        const raw = await this._callRawV2Rpc('message.v2.ack', { up_to_seq: seq });
         const result = isJsonObject(raw)
             ? { ...raw }
             : { result: raw };
@@ -3839,19 +4452,25 @@ 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);
@@ -3869,6 +4488,7 @@ export class AUNClient {
                     cachedAt: Date.now(),
                     epoch,
                     stateCommitment,
+                    wrapPolicy,
                 });
             }
             // lazy sync 触发：发现 pending members 时异步发起提案
@@ -3911,7 +4531,7 @@ export class AUNClient {
             if (target)
                 targets.push(target);
         }
-        const envelope = 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,
@@ -3938,28 +4558,37 @@ export class AUNClient {
         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}`;
+        if (!opts?.gateLocked) {
+            return await this._runPullSerialized(ns, async () => this.pullGroupV2(gid, afterSeq, limit, {
+                ...(opts ?? {}),
+                gateLocked: true,
+                scheduleFollowup: true,
+            }));
+        }
         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.call('group.v2.pull', {
+            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) {
@@ -3969,8 +4598,9 @@ export class AUNClient {
                 .map((msg) => Number(msg.seq ?? 0))
                 .filter((seq) => Number.isFinite(seq) && seq > 0);
             const pageContigBefore = this._seqTracker.getContiguousSeq(ns);
-            const pageMaxSeq = seqs.length > 0 ? Math.max(...seqs) : nextAfterSeq;
+            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}`);
             }
@@ -4034,18 +4664,18 @@ export class AUNClient {
                 decrypted.push(plaintext);
                 this._logMessageDebug('decrypt-ok', 'group.v2.pull', 'group.message_created', plaintext);
             }
-            const serverAckSeq = Number(cursor?.current_seq ?? 0);
-            if (Number.isFinite(serverAckSeq) && serverAckSeq > 0) {
+            const retentionFloor = this._pullRetentionFloor(result, 'retention_floor_message_seq', 'retention_floor_message_seq');
+            if (retentionFloor > 0) {
                 const contig = this._seqTracker.getContiguousSeq(ns);
-                if (contig < serverAckSeq) {
-                    this._clientLog.info(`group.v2.pull retention-floor advance: ns=${ns} contiguous=${contig} -> cursor.current_seq=${serverAckSeq}`);
-                    this._seqTracker.forceContiguousSeq(ns, serverAckSeq);
+                if (contig < retentionFloor) {
+                    this._clientLog.info(`group.v2.pull retention-floor advance: ns=${ns} contiguous=${contig} -> retention_floor=${retentionFloor}`);
+                    this._seqTracker.forceContiguousSeq(ns, retentionFloor);
                 }
             }
             const ackSeq = this._seqTracker.getContiguousSeq(ns);
             const contigAdvanced = ackSeq !== pageContigBefore;
             if (contigAdvanced) {
-                await this._drainOrderedMessages(ns);
+                await this._drainOrderedMessages(ns, undefined, true);
                 this._saveSeqTrackerState();
             }
             if (messages.length > 0 && contigAdvanced && ackSeq > 0) {
@@ -4081,7 +4711,7 @@ export class AUNClient {
             seq = maxSeen;
         }
         this._clientLog.debug(`group.v2.ack send: group=${gid}, ns=${ns}, up_to_seq=${seq}`);
-        const result = await this.call('group.v2.ack', { group_id: gid, 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;
     }
@@ -4117,7 +4747,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)
@@ -4465,7 +5095,8 @@ export class AUNClient {
             for (const row of envelope.recipients) {
                 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;
@@ -4749,7 +5380,10 @@ 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)
                 : [];
@@ -4858,7 +5492,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)
                 : [];
@@ -5064,11 +5701,10 @@ export class AUNClient {
             try {
                 const decrypted = await this._decryptV2PushMessage(data);
                 if (decrypted) {
-                    // 解密成功：把 pushSeq 加入 receivedSeqs，让 _tryAdvance 自然推进
-                    // （如果 pushSeq == contiguousSeq + 1 会自动推进到 pushSeq）
-                    const needPull = this._seqTracker.onMessageSeq(ns, pushSeq);
+                    // 解密成功也不能先推进 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();
                     }
@@ -5076,7 +5712,7 @@ export class AUNClient {
                         // 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 })
+                        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}`);
@@ -5096,31 +5732,37 @@ export class AUNClient {
         if (pushSeq > 0 && ns) {
             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)) {
+                this._recordPendingP2pPull(ns, pushSeq);
+                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, () => this._recordPendingP2pPull(ns, pushSeq)).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);
@@ -5134,7 +5776,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);
@@ -5148,7 +5791,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);
@@ -5161,7 +5805,8 @@ export class AUNClient {
             return;
         }
         this._logMessageDebug('server-push', '_raw.group.v2.message_created', 'group.message_created', data);
-        const groupId = String(data.group_id ?? '').trim();
+        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) {
             this._clientLog.debug(`_onRawGroupV2MessageCreated skipped: group=${groupId || '<empty>'}, seq=${String(data.seq ?? '')}`);
@@ -5178,22 +5823,28 @@ export class AUNClient {
         }
         const afterSeq = this._repairPushContiguousBound(ns, seq, false, '_raw.group.v2.message_created');
         const dedupKey = `v2_group_push:${groupId}:${afterSeq}`;
-        if (this._gapFillDone.has(dedupKey)) {
-            this._clientLog.debug(`_onRawGroupV2MessageCreated skipped duplicate in-flight pull: group=${groupId}, dedup=${dedupKey}`);
-            return;
-        }
-        this._gapFillDone.set(dedupKey, Date.now());
-        try {
-            this._clientLog.debug(`_onRawGroupV2MessageCreated auto-pull start: group=${groupId}, after_seq=${afterSeq}, push_seq=${seq}`);
-            await this.pullGroupV2(groupId, afterSeq, 50);
-            this._clientLog.debug(`_onRawGroupV2MessageCreated auto-pull done: group=${groupId}, after_seq=${afterSeq}, push_seq=${seq}, contiguous=${this._seqTracker.getContiguousSeq(ns)}`);
-        }
-        catch (exc) {
+        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) {