@agentunion/fastaun 0.3.2 → 0.3.3

package/dist/client.js

@@ -14,10 +14,12 @@ import * as crypto from 'node:crypto';
 import * as fs from 'node:fs';
 import * as http from 'node:http';
 import * as https from 'node:https';
+import * as path from 'node:path';
 import { URL } from 'node:url';
 import { configFromMap, getDeviceId, normalizeInstanceId } from './config.js';
 import { CryptoProvider } from './crypto.js';
 import { GatewayDiscovery } from './discovery.js';
+import { DnsResilientNet } from './net.js';
 import { AUNError, AuthError, ConnectionError, E2EEError, PermissionError, StateError, TimeoutError, ValidationError, } from './errors.js';
 import { EventDispatcher } from './events.js';
 import { FileKeyStore } from './keystore/file.js';
@@ -31,6 +33,7 @@ import { AuthFlow } from './auth.js';
 import { SeqTracker } from './seq-tracker.js';
 import { V2Session } from './v2/session/index.js';
 import { encryptP2PMessage, encryptGroupMessage, decryptMessage, } from './v2/e2ee/index.js';
+import { ecdsaVerifyRaw } from './v2/crypto/ecdsa.js';
 import { computeStateCommitment } from './v2/state/index.js';
 import { isJsonObject, } from './types.js';
 /**
@@ -58,6 +61,15 @@ export function stableStringify(obj) {
     }
     return JSON.stringify(obj);
 }
+function getV2DeviceId(dev) {
+    if (Object.prototype.hasOwnProperty.call(dev, 'device_id')) {
+        return { present: true, value: String(dev.device_id ?? '').trim() };
+    }
+    if (Object.prototype.hasOwnProperty.call(dev, 'owner_device_id')) {
+        return { present: true, value: String(dev.owner_device_id ?? '').trim() };
+    }
+    return { present: false, value: '' };
+}
 function computeStateHash(params) {
     const sortedMembers = [...params.members].sort((a, b) => a.aid.localeCompare(b.aid));
     const membershipBlock = sortedMembers.map(m => `${m.aid}:${m.role}`).join('|');
@@ -156,7 +168,16 @@ function reconnectSleepDelayMs(baseDelay, maxBaseDelay) {
 }
 /** 需要客户端签名的关键方法 */
 const SIGNED_METHODS = new Set([
-    'group.send', 'group.kick', 'group.add_member',
+    'message.send',
+    'message.v2.put_peer_pk', 'message.v2.bootstrap',
+    'message.v2.group_bootstrap', 'message.v2.pull',
+    'message.v2.ack',
+    'group.send',
+    'group.v2.put_group_pk', 'group.v2.bootstrap',
+    'group.v2.send', 'group.v2.pull', 'group.v2.ack',
+    'group.v2.propose_state', 'group.v2.confirm_state',
+    'group.v2.get_proposal',
+    'group.kick', 'group.add_member',
     'group.leave', 'group.remove_member', 'group.update_rules',
     'group.update', 'group.update_announcement',
     'group.update_join_requirements', 'group.set_role',
@@ -189,6 +210,21 @@ function _v2B64ToBytes(s) {
     const buf = Buffer.from(String(s ?? '').trim(), 'base64');
     return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
 }
+function _v2B64ToBytesStrict(s) {
+    const text = String(s ?? '').trim();
+    if (!text || text.length % 4 === 1 || !/^[A-Za-z0-9+/]*={0,2}$/.test(text)) {
+        throw new Error('invalid base64');
+    }
+    return _v2B64ToBytes(text);
+}
+function _v2BytesEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a[i] ^ b[i];
+    return diff === 0;
+}
 function _v2B64uToBytes(s) {
     const std = String(s ?? '').replace(/-/g, '+').replace(/_/g, '/');
     const pad = std.length % 4 === 0 ? '' : '='.repeat(4 - (std.length % 4));
@@ -245,11 +281,11 @@ function normalizeDeliveryModeConfig(raw, opts = {}) {
 }
 // ── HTTP 辅助 ─────────────────────────────────────────────────
 /** 发起 HTTP GET 请求，返回文本内容 */
-function _httpGetText(url, verifySsl) {
+function _httpGetText(url, verifySsl, timeoutMs = 30_000) {
     return new Promise((resolve, reject) => {
         const parsed = new URL(url);
         const mod = parsed.protocol === 'https:' ? https : http;
-        const options = { timeout: 30_000 };
+        const options = { timeout: timeoutMs };
         if (!verifySsl) {
             options.rejectUnauthorized = false;
         }
@@ -274,6 +310,17 @@ function _httpGetText(url, verifySsl) {
 /**
  * AUN Core SDK 主客户端
  */
+function lengthPrefixedTextKey(...parts) {
+    return parts.map((part) => `${Buffer.byteLength(part, 'utf8')}:${part};`).join('');
+}
+function lengthPrefixedBytesKey(...parts) {
+    const chunks = [];
+    for (const part of parts) {
+        const bytes = Buffer.from(part.buffer, part.byteOffset, part.byteLength);
+        chunks.push(Buffer.from(`${bytes.length}:`, 'ascii'), bytes, Buffer.from(';', 'ascii'));
+    }
+    return Buffer.concat(chunks);
+}
 export class AUNClient {
     /** 原始配置 */
     config;
@@ -317,13 +364,15 @@ export class AUNClient {
     _defaultConnectDeliveryMode;
     /** peer 证书缓存 */
     _certCache = new Map();
-    // 本地 agent.md 文件路径与对应 etag（quoted sha256 hex，与服务端 _agent_md_etag 一致）。
-    // 由 setLocalAgentMdPath() 设置；用于跟服务端 RPC 注入的 _meta.agent_md_etag 比对，
-    // 触发"本地未发布到服务端"或"服务端版本更新"的 UI 提示。
+    // AgentMDs 目录：{agentMdPath}/list.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;
     /** 消息序列号跟踪器（群消息 + P2P 空洞检测） */
     _seqTracker = new SeqTracker();
     _seqTrackerContext = null;
@@ -335,6 +384,10 @@ export class AUNClient {
     _pushedSeqs = new Map();
     /** 已解密但因 seq 空洞暂缓发布的应用层消息（按 namespace -> seq） */
     _pendingOrderedMsgs = new Map();
+    /** 缺 sender IK 时暂存原始 V2 消息，后台补齐 IK 后重试解密。 */
+    _v2SenderIKPending = new Map();
+    /** sender IK 后台补齐任务去重。 */
+    _v2SenderIKFetching = new Set();
     // ── 后台任务定时器 ──────────────────────────────────────────
     _heartbeatTimer = null;
     _tokenRefreshTimer = null;
@@ -360,7 +413,7 @@ export class AUNClient {
     _v2PullPending = false;
     static V2_BOOTSTRAP_TTL_MS = 60 * 60 * 1000;
     static V2_RETRYABLE_CODES = new Set([-33011, -33012, -33050, -33052, -33054]);
-    static V2_SIG_CACHE_TTL_MS = 600_000;
+    static V2_SIG_CACHE_TTL_MS = 60 * 60 * 1000;
     static V2_SIG_CACHE_MAX = 16_384;
     _reconnectActive = false;
     _reconnectAbort = null;
@@ -373,30 +426,36 @@ 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.config = {
             aun_path: this._configModel.aunPath,
             root_ca_path: this._configModel.rootCaPath,
             seed_password: this._configModel.seedPassword,
         };
+        this._deviceId = getDeviceId(this._configModel.aunPath);
         // 初始化 Logger（per-client 单例，必须最早创建）
         const debugFlag = this._configModel.debug || debug;
         this._logger = new AUNLogger({
             debug: debugFlag,
             aunPath: this._configModel.aunPath,
         });
+        this._logger.bindDeviceId(this._deviceId);
         this._clientLog = this._logger.for('aun_core.client');
         if (debugFlag) {
             this._clientLog.info(`AUNClient initialized (debug=true, aunPath=${this._configModel.aunPath})`);
         }
         this._dispatcher = new EventDispatcher(this._logger.for('aun_core.events'));
-        this._discovery = new GatewayDiscovery({ verifySsl: this._configModel.verifySsl });
+        const dnsNet = new DnsResilientNet({
+            verifySsl: this._configModel.verifySsl,
+            logger: this._clientLog,
+        });
+        this._discovery = new GatewayDiscovery({ verifySsl: this._configModel.verifySsl, logger: this._clientLog, net: dnsNet });
         const keystore = new FileKeyStore(this._configModel.aunPath, {
             encryptionSeed: this._configModel.seedPassword ?? undefined,
             logger: this._logger.for('aun_core.keystore'),
             secretStoreLogger: this._logger.for('aun_core.secret-store'),
         });
         this._keystore = keystore;
-        this._deviceId = getDeviceId(this._configModel.aunPath);
         this._slotId = '';
         this._connectDeliveryMode = normalizeDeliveryModeConfig({ mode: 'fanout' });
         this._defaultConnectDeliveryMode = { ...this._connectDeliveryMode };
@@ -409,6 +468,7 @@ export class AUNClient {
             rootCaPath: this._configModel.rootCaPath ?? undefined,
             verifySsl: this._configModel.verifySsl,
             logger: this._logger.for('aun_core.auth'),
+            net: dnsNet,
         });
         this._aid = initAid;
         this._transport = new RPCTransport({
@@ -417,6 +477,7 @@ export class AUNClient {
             onDisconnect: (err, closeCode) => this._handleTransportDisconnect(err, closeCode),
             verifySsl: this._configModel.verifySsl,
             logger: this._logger.for('aun_core.transport'),
+            dnsNet,
         });
         this._transport.setMetaObserver((meta) => this._observeRpcMeta(meta));
         this.auth = new AuthNamespace(this);
@@ -453,25 +514,35 @@ export class AUNClient {
         return this._aid;
     }
     /**
-     * 读取本地 agent.md，签名后上传，并刷新本地 etag。
+     * 读取 {agentMdPath}/{self_aid}/agent.md，签名后上传，并把签名结果原子写回本地。
      */
-    async publishAgentMd(path) {
-        const rawPath = String(path ?? '').trim();
-        if (!rawPath) {
-            throw new ValidationError('publishAgentMd requires non-empty path');
+    async publishAgentMd() {
+        const target = this._agentMdOwnerAid();
+        if (!target) {
+            throw new ValidationError('publishAgentMd requires local AID');
         }
-        const content = fs.readFileSync(rawPath).toString('utf-8');
+        const content = this._readAgentMdContent(target);
         const signed = await this.auth.signAgentMd(content);
         const result = await this.auth.uploadAgentMd(signed);
-        const digest = crypto.createHash('sha256').update(signed, 'utf-8').digest('hex');
-        this._localAgentMdEtag = `"${digest}"`;
-        this._localAgentMdPath = rawPath;
+        this._localAgentMdEtag = this._agentMdContentEtag(signed);
+        const remoteEtag = isJsonObject(result) ? String(result.etag ?? '').trim() : '';
+        if (remoteEtag)
+            this._remoteAgentMdEtag = remoteEtag;
+        this._saveAgentMdRecord(target, {
+            content: signed,
+            local_etag: this._localAgentMdEtag,
+            remote_etag: remoteEtag || undefined,
+            last_modified: isJsonObject(result) ? String(result.last_modified ?? '').trim() : '',
+            fetched_at: Date.now(),
+            remote_status: remoteEtag ? 'found' : 'unknown',
+            last_error: '',
+        });
         return result;
     }
     /**
-     * 下载 agent.md 并自动验签；可选写盘；目标是自身 AID 时刷新本地 etag。
+     * 下载 agent.md 并自动验签；内容固定保存到 {agentMdPath}/{aid}/agent.md。
      */
-    async fetchAgentMd(aid, savePath) {
+    async fetchAgentMd(aid) {
         const target = String(aid ?? this._aid ?? '').trim();
         if (!target) {
             throw new ValidationError('fetchAgentMd requires aid (or local AID)');
@@ -479,35 +550,54 @@ export class AUNClient {
         const content = await this.auth.downloadAgentMd(target);
         const signature = await this.auth.verifyAgentMd(content, { aid: target });
         const isSelf = target === (this._aid ?? '');
+        const localEtag = this._agentMdContentEtag(content);
+        const cacheMeta = this._agentMdAuthCacheMeta(target);
+        const remoteEtag = String(cacheMeta.etag ?? '').trim();
+        const lastModified = String(cacheMeta.lastModified ?? cacheMeta.last_modified ?? '').trim();
+        if (isSelf) {
+            this._localAgentMdEtag = localEtag;
+            if (remoteEtag)
+                this._remoteAgentMdEtag = remoteEtag;
+        }
+        const saved = this._saveAgentMdRecord(target, {
+            content,
+            local_etag: localEtag,
+            remote_etag: remoteEtag || undefined,
+            last_modified: lastModified || undefined,
+            fetched_at: Date.now(),
+            remote_status: 'found',
+            verify_status: isJsonObject(signature) ? String(signature.status ?? '') : '',
+            verify_error: isJsonObject(signature) ? String(signature.reason ?? '') : '',
+            last_error: '',
+        });
         let inSync = null;
         if (isSelf) {
-            const digest = crypto.createHash('sha256').update(content, 'utf-8').digest('hex');
-            this._localAgentMdEtag = `"${digest}"`;
-            const local = this._localAgentMdEtag || '';
-            const remote = this._remoteAgentMdEtag || '';
-            inSync = local && remote ? local === remote : false;
-        }
-        let savedTo = null;
-        let saveError = null;
-        const rawSavePath = String(savePath ?? '').trim();
-        if (rawSavePath) {
-            try {
-                fs.writeFileSync(rawSavePath, content, 'utf-8');
-                savedTo = rawSavePath;
-            }
-            catch (exc) {
-                saveError = exc instanceof Error ? exc.message : String(exc);
-            }
+            const remote = remoteEtag || this._remoteAgentMdEtag || '';
+            inSync = localEtag && remote ? localEtag === remote : false;
         }
         return {
             aid: target,
             content,
             signature: signature,
             in_sync: inSync,
-            saved_to: savedTo,
-            save_error: saveError,
+            saved_to: String(saved.saved_to ?? this._agentMdFilePath(target)),
+            save_error: null,
         };
     }
+    /**
+     * 设置 agent.md 本地存储根目录；为空时恢复默认 {aun_path}/AgentMDs。
+     */
+    setAgentMdPath(root) {
+        const raw = String(root ?? '').trim();
+        const next = raw || path.join(this._configModel.aunPath, 'AgentMDs');
+        fs.mkdirSync(next, { recursive: true });
+        this._agentMdPath = next;
+        this._agentMdCache.clear();
+        return this._agentMdPath;
+    }
+    SetAgentMDPath(root) {
+        return this.setAgentMdPath(root);
+    }
     /**
      * 记录本地 agent.md 文件路径并一次性计算 etag（quoted sha256，与服务端一致）。
      *
@@ -558,6 +648,447 @@ export class AUNClient {
     getRemoteAgentMdEtag() {
         return this._remoteAgentMdEtag;
     }
+    _agentMdContentEtag(content) {
+        return `"${crypto.createHash('sha256').update(String(content ?? ''), 'utf-8').digest('hex')}"`;
+    }
+    _agentMdOwnerAid() {
+        return String(this._aid ?? '').trim();
+    }
+    _agentMdSafeAid(aid) {
+        const target = String(aid ?? '').trim();
+        if (!target || target.includes('/') || target.includes('\\') || target.includes('\0')) {
+            throw new ValidationError('agent.md aid is empty or contains path separators');
+        }
+        return target;
+    }
+    _agentMdRoot() {
+        const root = this._agentMdPath || path.join(this._configModel.aunPath, 'AgentMDs');
+        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');
+    }
+    _atomicWriteText(filePath, content) {
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        const tmp = path.join(path.dirname(filePath), `.${path.basename(filePath)}.${process.pid}.${crypto.randomUUID()}.tmp`);
+        let fd = null;
+        try {
+            fd = fs.openSync(tmp, 'w');
+            fs.writeFileSync(fd, content, 'utf-8');
+            fs.fsyncSync(fd);
+            fs.closeSync(fd);
+            fd = null;
+            fs.renameSync(tmp, filePath);
+            try {
+                const dirFd = fs.openSync(path.dirname(filePath), 'r');
+                try {
+                    fs.fsyncSync(dirFd);
+                }
+                finally {
+                    fs.closeSync(dirFd);
+                }
+            }
+            catch { /* best effort */ }
+        }
+        finally {
+            if (fd !== null) {
+                try {
+                    fs.closeSync(fd);
+                }
+                catch { /* ignore */ }
+            }
+            if (fs.existsSync(tmp)) {
+                try {
+                    fs.unlinkSync(tmp);
+                }
+                catch { /* ignore */ }
+            }
+        }
+    }
+    _sleepSync(ms) {
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+    }
+    _withAgentMdListLock(fn) {
+        const lockPath = path.join(this._agentMdRoot(), 'list.json.lock');
+        const deadline = Date.now() + 5000;
+        let fd = null;
+        while (fd === null) {
+            try {
+                fd = fs.openSync(lockPath, 'wx');
+                fs.writeFileSync(fd, `${process.pid}\n`, 'utf-8');
+            }
+            catch (err) {
+                if (err?.code !== 'EEXIST' || Date.now() >= deadline)
+                    throw err;
+                try {
+                    const st = fs.statSync(lockPath);
+                    if (Date.now() - st.mtimeMs > 30000)
+                        fs.unlinkSync(lockPath);
+                }
+                catch { /* ignore */ }
+                this._sleepSync(25);
+            }
+        }
+        try {
+            return fn();
+        }
+        finally {
+            if (fd !== null) {
+                try {
+                    fs.closeSync(fd);
+                }
+                catch { /* ignore */ }
+            }
+            try {
+                fs.unlinkSync(lockPath);
+            }
+            catch { /* ignore */ }
+        }
+    }
+    _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);
+            }
+        }
+        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;
+    }
+    _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)}`);
+            }
+        }
+        this._writeAgentMdListUnlocked(records);
+        this._agentMdCache.clear();
+        return records;
+    }
+    _readAgentMdListUnlocked() {
+        const filePath = this._agentMdListPath();
+        if (!fs.existsSync(filePath)) {
+            this._agentMdLastListRebuilt = true;
+            return this._rebuildAgentMdListUnlocked();
+        }
+        try {
+            const parsed = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+            this._agentMdLastListRebuilt = false;
+            return this._normalizeAgentMdList(parsed);
+        }
+        catch (err) {
+            this._clientLog.warn(`agent.md list.json damaged, rebuilding: ${err instanceof Error ? err.message : String(err)}`);
+            this._agentMdLastListRebuilt = true;
+            return this._rebuildAgentMdListUnlocked();
+        }
+    }
+    _readAgentMdContent(aid) {
+        return fs.readFileSync(this._agentMdFilePath(aid), 'utf-8');
+    }
+    _writeAgentMdContent(aid, content) {
+        const filePath = this._agentMdFilePath(aid);
+        this._atomicWriteText(filePath, String(content ?? ''));
+        return filePath;
+    }
+    _agentMdAuthCacheMeta(aid) {
+        try {
+            const store = this.auth._agentMdCache;
+            const record = store?.get(String(aid ?? '').trim());
+            return record && typeof record === 'object' ? { ...record } : {};
+        }
+        catch {
+            return {};
+        }
+    }
+    _loadAgentMdRecord(aid) {
+        const target = String(aid ?? '').trim();
+        if (!target)
+            return null;
+        try {
+            const records = this._withAgentMdListLock(() => this._readAgentMdListUnlocked());
+            const record = records[target];
+            if (record && typeof record === 'object') {
+                const loaded = { ...record, aid: target };
+                try {
+                    const content = this._readAgentMdContent(target);
+                    loaded.content = content;
+                    loaded.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)}`);
+                }
+                this._agentMdCache.set(target, { ...loaded });
+                return { ...loaded };
+            }
+        }
+        catch (err) {
+            this._clientLog.debug(`agent.md cache load skipped: aid=${target} err=${err instanceof Error ? err.message : String(err)}`);
+        }
+        return null;
+    }
+    _saveAgentMdRecord(aid, fields) {
+        const target = String(aid ?? '').trim();
+        if (!target)
+            return {};
+        try {
+            const inputFields = { ...fields };
+            const hasContent = Object.prototype.hasOwnProperty.call(inputFields, 'content') && inputFields.content !== undefined && inputFields.content !== null;
+            let savedTo = '';
+            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 };
+                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);
+                return next;
+            });
+            const loaded = { ...record };
+            if (hasContent) {
+                loaded.content = String(fields.content ?? '');
+                if (savedTo)
+                    loaded.saved_to = savedTo;
+            }
+            this._agentMdCache.set(target, { ...loaded });
+            const owner = this._agentMdOwnerAid();
+            if (target === owner) {
+                const localEtag = String(loaded.local_etag ?? '').trim();
+                const remoteEtag = String(loaded.remote_etag ?? '').trim();
+                if (localEtag)
+                    this._localAgentMdEtag = localEtag;
+                if (remoteEtag)
+                    this._remoteAgentMdEtag = remoteEtag;
+            }
+            return { ...loaded };
+        }
+        catch (err) {
+            this._clientLog.debug(`agent.md cache save skipped: aid=${target} err=${err instanceof Error ? err.message : String(err)}`);
+        }
+        return {};
+    }
+    _agentMdHasLocalContent(aid, record) {
+        if (record && typeof record.content === 'string' && record.content.length > 0)
+            return true;
+        try {
+            return fs.existsSync(this._agentMdFilePath(aid));
+        }
+        catch {
+            return false;
+        }
+    }
+    _agentMdCheckedAtFresh(checkedAtMs, maxUnsyncedDays) {
+        const days = Number(maxUnsyncedDays || 0);
+        if (!Number.isFinite(days) || days <= 0)
+            return false;
+        if (!Number.isFinite(checkedAtMs) || checkedAtMs <= 0)
+            return false;
+        return Date.now() - checkedAtMs <= days * 86400000;
+    }
+    _agentMdLastModifiedFresh(lastModified, maxUnsyncedDays) {
+        const days = Number(maxUnsyncedDays || 0);
+        if (!Number.isFinite(days) || days <= 0)
+            return false;
+        const ts = Date.parse(String(lastModified ?? '').trim());
+        if (!Number.isFinite(ts))
+            return false;
+        return Date.now() <= ts + days * 86400000;
+    }
+    _scheduleAgentMdFetchIfMissing(aid, record, source = '') {
+        const target = String(aid ?? '').trim();
+        if (!target || this._agentMdHasLocalContent(target, record))
+            return;
+        if (this._agentMdFetchInflight.has(target))
+            return;
+        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 = '') {
+        const target = String(aid ?? '').trim();
+        const remoteEtag = String(etag ?? '').trim();
+        const remoteLastModified = String(lastModified ?? '').trim();
+        if (!target || (!remoteEtag && !remoteLastModified))
+            return;
+        let before = this._agentMdCache.get(target);
+        if (!before || typeof before !== 'object')
+            before = this._loadAgentMdRecord(target) ?? {};
+        const same = (!remoteEtag || String(before.remote_etag ?? '').trim() === remoteEtag) &&
+            (!remoteLastModified || String(before.last_modified ?? '').trim() === remoteLastModified);
+        let record = { ...before };
+        if (!same || Object.keys(before).length === 0) {
+            const fields = {
+                observed_at: Date.now(),
+                remote_status: 'found',
+            };
+            if (remoteEtag)
+                fields.remote_etag = remoteEtag;
+            if (remoteLastModified)
+                fields.last_modified = remoteLastModified;
+            record = this._saveAgentMdRecord(target, fields) || record;
+        }
+        if (target === this._agentMdOwnerAid() && remoteEtag)
+            this._remoteAgentMdEtag = remoteEtag;
+        this._scheduleAgentMdFetchIfMissing(target, record, source);
+        this._clientLog.debug(`agent.md meta observed: aid=${target} etag=${remoteEtag || '-'} last_modified=${remoteLastModified || '-'} source=${source || '-'}`);
+    }
+    _observeAgentMdEtag(aid, etag, source = '') {
+        this._observeAgentMdMeta(aid, etag, '', source);
+    }
+    _observeAgentMdFromEnvelope(envelope) {
+        if (!isJsonObject(envelope))
+            return;
+        const env = envelope;
+        if (!isJsonObject(env.agent_md))
+            return;
+        const agentMd = env.agent_md;
+        if (!isJsonObject(agentMd.sender))
+            return;
+        const sender = agentMd.sender;
+        let senderAid = String(sender.aid ?? '').trim();
+        if (!senderAid) {
+            const aad = isJsonObject(env.aad) ? env.aad : {};
+            senderAid = String(aad.from ?? env.from ?? '').trim();
+        }
+        this._observeAgentMdMeta(senderAid, String(sender.etag ?? '').trim(), String(sender.last_modified ?? sender.lastModified ?? '').trim(), 'envelope');
+    }
+    async checkAgentMd(aid, maxUnsyncedDays = 0) {
+        const target = String(aid ?? this._aid ?? '').trim();
+        if (!target)
+            throw new ValidationError('checkAgentMd requires aid (or local AID)');
+        const before = this._loadAgentMdRecord(target) ?? {};
+        const localEtag = String(before.local_etag ?? '').trim();
+        const localFound = !!(Object.keys(before).length > 0 && (String(before.content ?? '') || localEtag));
+        const remoteEtagCached = String(before.remote_etag ?? '').trim();
+        const lastModifiedCached = String(before.last_modified ?? '').trim();
+        const checkedAtCached = Number(before.checked_at ?? 0);
+        const cachedInSync = !!(localFound && localEtag && remoteEtagCached && localEtag === remoteEtagCached);
+        // max_unsynced_days > 0 且距上次 HEAD 在窗口内 → 直接返回缓存；否则强制 HEAD。
+        if (cachedInSync && this._agentMdCheckedAtFresh(checkedAtCached, maxUnsyncedDays)) {
+            return {
+                aid: target,
+                local_found: true,
+                remote_found: true,
+                local_etag: localEtag,
+                remote_etag: remoteEtagCached,
+                in_sync: true,
+                last_modified: lastModifiedCached,
+                status: 200,
+                cached: true,
+                verify_status: String(before.verify_status ?? ''),
+                verify_error: String(before.verify_error ?? ''),
+            };
+        }
+        const now = Date.now();
+        let remote;
+        try {
+            remote = await this.auth.headAgentMd(target);
+        }
+        catch (err) {
+            this._saveAgentMdRecord(target, { checked_at: now, remote_status: 'error', last_error: err instanceof Error ? err.message : String(err) });
+            throw err;
+        }
+        const remoteFound = !!remote.found;
+        const remoteEtag = String(remote.etag ?? '').trim();
+        const lastModified = String(remote.last_modified ?? remote.lastModified ?? '').trim();
+        const saved = this._saveAgentMdRecord(target, {
+            remote_etag: remoteFound ? remoteEtag : '',
+            last_modified: lastModified,
+            checked_at: now,
+            remote_status: remoteFound ? 'found' : 'missing',
+            last_error: '',
+        });
+        if (target === this._agentMdOwnerAid() && remoteEtag)
+            this._remoteAgentMdEtag = remoteEtag;
+        const inSync = !!(localFound && remoteFound && localEtag && remoteEtag && localEtag === remoteEtag);
+        return {
+            aid: target,
+            local_found: localFound,
+            remote_found: remoteFound,
+            local_etag: localEtag,
+            remote_etag: remoteEtag,
+            in_sync: inSync,
+            last_modified: lastModified,
+            status: Number(remote.status ?? (remoteFound ? 200 : 404)),
+            cached: false,
+            verify_status: String(saved.verify_status ?? before.verify_status ?? ''),
+            verify_error: String(saved.verify_error ?? before.verify_error ?? ''),
+        };
+    }
     /** transport 的 meta observer：吸收 gateway 注入的 _meta 字段。失败不影响业务。 */
     _observeRpcMeta(meta) {
         if (!meta || typeof meta !== 'object')
@@ -565,6 +1096,17 @@ export class AUNClient {
         const etag = String(meta.agent_md_etag ?? '').trim();
         if (etag) {
             this._remoteAgentMdEtag = etag;
+            this._observeAgentMdMeta(this._aid ?? '', etag, '', 'rpc.self');
+        }
+        const etags = meta.agent_md_etags;
+        if (isJsonObject(etags)) {
+            // role key 优先级：requester / peer 是新规范，其余是兼容旧 SDK 的别名。
+            for (const key of ['requester', 'peer', 'receiver', 'target', 'to', 'sender', 'from']) {
+                const item = etags[key];
+                if (!isJsonObject(item))
+                    continue;
+                this._observeAgentMdMeta(String(item.aid ?? ''), String(item.etag ?? ''), String(item.last_modified ?? item.lastModified ?? ''), `rpc.${key}`);
+            }
         }
     }
     /** 连接状态 */
@@ -613,19 +1155,31 @@ export class AUNClient {
         this._transport.setTimeout(callTimeoutSec != null ? callTimeoutSec * 1000 : 35_000);
         this._closing = false;
         this._clientLog.debug(`connect enter: gateway=${String(normalized.gateway ?? '')}, device_id=${this._deviceId}`);
-        try {
-            await this._connectOnce(normalized, false);
-            this._clientLog.debug(`connect exit: elapsed=${Date.now() - tStart}ms aid=${this._aid ?? ''}, state=${this._state}`);
-        }
-        catch (err) {
-            // 连接失败时回退状态，允许重试
-            if (this._state === 'connecting' || this._state === 'authenticating') {
-                this._state = 'disconnected';
+        const gateways = this._resolveGateways(normalized);
+        let lastErr = null;
+        for (const gw of gateways) {
+            try {
+                const gwParams = { ...normalized, gateway: gw };
+                await this._connectOnce(gwParams, false);
+                this._clientLog.debug(`connect exit: elapsed=${Date.now() - tStart}ms aid=${this._aid ?? ''}, state=${this._state}`);
+                return;
+            }
+            catch (err) {
+                lastErr = err;
+                if (gateways.length > 1) {
+                    this._clientLog.warn(`connect: gateway ${gw} failed, trying next: ${formatCaughtError(err)}`);
+                }
+                if (this._state === 'connecting' || this._state === 'authenticating') {
+                    this._state = 'connecting';
+                }
             }
-            this._clientLog.error(`connect failed: ${formatCaughtError(err)}`, err instanceof Error ? err : undefined);
-            this._clientLog.debug(`connect exit (error): elapsed=${Date.now() - tStart}ms err=${err instanceof Error ? err.message : String(err)}`);
-            throw err;
         }
+        if (this._state === 'connecting' || this._state === 'authenticating') {
+            this._state = 'disconnected';
+        }
+        this._clientLog.error(`connect failed: ${formatCaughtError(lastErr)}`, lastErr instanceof Error ? lastErr : undefined);
+        this._clientLog.debug(`connect exit (error): elapsed=${Date.now() - tStart}ms err=${lastErr instanceof Error ? lastErr.message : String(lastErr)}`);
+        throw lastErr;
     }
     /** 关闭连接 */
     async close() {
@@ -743,6 +1297,9 @@ export class AUNClient {
                 throw new PermissionError(`legacy E2EE method is removed in this SDK: ${method}`);
             }
             const p = { ...(params ?? {}) };
+            if (method === 'message.send' || method === 'group.send') {
+                this._normalizeOutboundMessagePayload(p, method);
+            }
             this._validateOutboundCall(method, p);
             this._injectMessageCursorContext(method, p);
             // group.* 方法的 group_id 归一化为 canonical 格式（兼容老/污染数据）
@@ -755,7 +1312,7 @@ export class AUNClient {
                 p.group_id = normalizedGroupId;
             }
             // group.* 方法注入 device_id（服务端用于多设备消息路由）
-            if (method.startsWith('group.') && this._deviceId && p.device_id === undefined) {
+            if (method.startsWith('group.') && p.device_id === undefined) {
                 p.device_id = this._deviceId;
             }
             if (method.startsWith('group.') && p.slot_id === undefined) {
@@ -829,17 +1386,27 @@ export class AUNClient {
             }
             // 关键操作自动附加客户端签名
             if (SIGNED_METHODS.has(method)) {
-                this._signClientOperation(method, p);
+                if (this._shouldSkipClientSignature(method, p)) {
+                    delete p.client_signature;
+                }
+                else {
+                    this._signClientOperation(method, p);
+                }
             }
             // P1-23: 非幂等方法使用更长超时
             const callTimeout = NON_IDEMPOTENT_METHODS.has(method) ? NON_IDEMPOTENT_TIMEOUT_MS : undefined;
+            if (method === 'group.thought.get' || method === 'message.thought.get') {
+                this._clientLog.debug(`thought.get transport call start: method=${method}, params=${this._debugJson(this._messageEnvelopeFieldsForDebug(p))}`);
+            }
             let result = callTimeout
                 ? await this._transport.call(method, p, callTimeout)
                 : await this._transport.call(method, p);
             if (method === 'group.thought.get' && isJsonObject(result)) {
+                this._clientLog.debug(`group.thought.get transport result: found=${String(result.found ?? '')}, raw_count=${Array.isArray(result.thoughts) ? result.thoughts.length : 0}`);
                 result = await this._decryptGroupThoughts(result);
             }
             if (method === 'message.thought.get' && isJsonObject(result)) {
+                this._clientLog.debug(`message.thought.get transport result: found=${String(result.found ?? '')}, raw_count=${Array.isArray(result.thoughts) ? result.thoughts.length : 0}`);
                 result = await this._decryptMessageThoughts(result);
             }
             // ── V2-only 群状态编排：成员变更后 propose+confirm state。
@@ -988,6 +1555,7 @@ export class AUNClient {
     async _onRawMessageReceived(data) {
         const tStart = Date.now();
         if (isJsonObject(data)) {
+            this._logMessageDebug('server-push', '_raw.message.received', 'message.received', data);
             this._clientLog.debug(`_onRawMessageReceived enter: from=${String(data.from ?? '')}, message_id=${String(data.message_id ?? '')}, seq=${String(data.seq ?? '')}`);
         }
         else {
@@ -1006,6 +1574,7 @@ export class AUNClient {
                     timestamp: data.timestamp,
                     _decrypt_error: String(exc),
                 };
+                this._attachV2EnvelopeMetadataFromSource(safeEvent, data);
                 this._publishAppEvent('message.undecryptable', safeEvent).catch(() => { });
             }
         });
@@ -1014,17 +1583,21 @@ export class AUNClient {
     /** 实际处理推送消息的异步任务 */
     async _processAndPublishMessage(data) {
         if (!isJsonObject(data)) {
-            await this._publishAppEvent('message.received', data);
+            await this._publishAppEvent('message.received', data, 'push');
             return;
         }
         const msg = { ...data };
         if (!this._messageTargetsCurrentInstance(msg)) {
+            this._clientLog.debug(`P2P push filtered by instance: message_id=${String(msg.message_id ?? '')}, seq=${String(msg.seq ?? '')}, target_device=${String(msg.device_id ?? '')}, target_slot=${String(msg.slot_id ?? '')}, local_device=${this._deviceId}, local_slot=${this._slotId}`);
             return;
         }
         // P2P 空洞检测
         const seq = msg.seq;
         if (seq !== undefined && seq !== null && this._aid) {
             const ns = `p2p:${this._aid}`;
+            // Push 修上界：先更新 maxSeenSeq，让上界反映服务端状态
+            if (seq > 0)
+                this._seqTracker.updateMaxSeen(ns, seq);
             const needPull = this._seqTracker.onMessageSeq(ns, seq);
             if (needPull) {
                 this._clientLog.debug(`P2P seq gap detected: ns=${ns}, seq=${seq}, contiguous=${this._seqTracker.getContiguousSeq(ns)}`);
@@ -1033,11 +1606,16 @@ export class AUNClient {
             // auto-ack contiguous_seq
             const contig = this._seqTracker.getContiguousSeq(ns);
             if (contig > 0) {
+                const maxSeen = this._seqTracker.getMaxSeenSeq(ns);
+                const ackSeq = maxSeen > 0 ? Math.min(contig, maxSeen) : contig;
+                this._clientLog.debug(`P2P push auto-ack send: ns=${ns}, seq=${ackSeq}, contiguous=${contig}, max_seen=${maxSeen}`);
                 this._transport.call('message.ack', {
-                    seq: contig,
+                    seq: ackSeq,
                     device_id: this._deviceId,
                     slot_id: this._slotId,
-                }).catch((e) => { this._clientLog.debug(`P2P auto-ack failed: ${formatCaughtError(e)}`); });
+                })
+                    .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();
@@ -1048,13 +1626,14 @@ export class AUNClient {
             await this._publishOrderedMessage('message.received', ns, seq, msg);
         }
         else {
-            await this._publishAppEvent('message.received', msg);
+            await this._publishAppEvent('message.received', msg, 'push');
         }
     }
     /** 处理群组消息推送：自动解密后 re-publish */
     async _onRawGroupMessageCreated(data) {
         const tStart = Date.now();
         if (isJsonObject(data)) {
+            this._logMessageDebug('server-push', '_raw.group.message_created', 'group.message_created', data);
             this._clientLog.debug(`_onRawGroupMessageCreated enter: group_id=${String(data.group_id ?? '')}, message_id=${String(data.message_id ?? '')}, seq=${String(data.seq ?? '')}`);
         }
         else {
@@ -1072,6 +1651,7 @@ export class AUNClient {
                     timestamp: data.timestamp,
                     _decrypt_error: String(exc),
                 };
+                this._attachV2EnvelopeMetadataFromSource(safeEvent, data);
                 this._publishAppEvent('group.message_undecryptable', safeEvent).catch(() => { });
             }
         });
@@ -1085,7 +1665,7 @@ export class AUNClient {
      */
     async _processAndPublishGroupMessage(data) {
         if (!isJsonObject(data)) {
-            await this._publishAppEvent('group.message_created', data);
+            await this._publishAppEvent('group.message_created', data, 'group-push');
             return;
         }
         const msg = { ...data };
@@ -1103,6 +1683,9 @@ export class AUNClient {
         }
         if (groupId && seq !== undefined && seq !== null) {
             const ns = `group:${groupId}`;
+            // Push 修上界：先更新 maxSeenSeq
+            if (seq > 0)
+                this._seqTracker.updateMaxSeen(ns, seq);
             const needPull = this._seqTracker.onMessageSeq(ns, seq);
             if (needPull) {
                 this._clientLog.debug(`group message seq gap detected: group=${groupId}, seq=${seq}, contiguous=${this._seqTracker.getContiguousSeq(ns)}`);
@@ -1110,12 +1693,17 @@ export class AUNClient {
             }
             const contig = this._seqTracker.getContiguousSeq(ns);
             if (contig > 0) {
+                const maxSeen = this._seqTracker.getMaxSeenSeq(ns);
+                const ackSeq = maxSeen > 0 ? Math.min(contig, maxSeen) : contig;
+                this._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: contig,
+                    msg_seq: ackSeq,
                     device_id: this._deviceId,
                     slot_id: this._slotId,
-                }).catch((e) => { this._clientLog.debug(`group message auto-ack failed: group=${groupId} ${formatCaughtError(e)}`); });
+                })
+                    .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();
         }
@@ -1125,7 +1713,7 @@ export class AUNClient {
             await this._publishOrderedMessage('group.message_created', nsKey, seq, msg);
         }
         else {
-            await this._publishAppEvent('group.message_created', msg);
+            await this._publishAppEvent('group.message_created', msg, 'group-push');
         }
     }
     /** 收到不带 payload 的 group.message_created 通知后，自动 pull 最新消息 */
@@ -1137,10 +1725,12 @@ export class AUNClient {
         }
         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', {
@@ -1158,13 +1748,14 @@ export class AUNClient {
                         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);
+                                await this._publishAppEvent('group.message_created', msg, 'pull');
                             }
                         }
                     }
@@ -1176,7 +1767,7 @@ export class AUNClient {
         catch (exc) {
             this._clientLog.debug(`auto pull group messages failed: ${formatCaughtError(exc)}`);
         }
-        await this._publishAppEvent('group.message_created', notification);
+        await this._publishAppEvent('group.message_created', notification, 'group-push-fallback');
     }
     /** 后台补齐群消息空洞 */
     async _fillGroupGap(groupId) {
@@ -1321,10 +1912,10 @@ export class AUNClient {
         if (!isJsonObject(payload))
             return payload;
         const result = { ...payload };
-        if (this._deviceId && !String(result.device_id ?? '').trim()) {
+        if (!('device_id' in result)) {
             result.device_id = this._deviceId;
         }
-        if (this._slotId && !String(result.slot_id ?? '').trim()) {
+        if (!('slot_id' in result)) {
             result.slot_id = this._slotId;
         }
         return result;
@@ -1334,10 +1925,11 @@ export class AUNClient {
             return payload;
         return this._attachCurrentInstanceContext(payload);
     }
-    async _publishAppEvent(event, payload) {
+    async _publishAppEvent(event, payload, source = 'direct') {
         if ((event === 'message.received' || event === 'group.message_created') && isJsonObject(payload)) {
             this._maybeAppendEchoTraceReceive(payload);
         }
+        this._logAppMessagePublish(event, payload, source);
         // 注入本地/远端 agent.md etag，让应用层判断版本一致性；失败不影响业务。
         if (isJsonObject(payload)) {
             try {
@@ -1383,6 +1975,18 @@ export class AUNClient {
         const trace = `${this._echoTimestamp()} [AUN-SDK.send] aid=${this._aid ?? '-'} conn_uptime=${uptime}s`;
         params.payload = { ...payload, text: payload.text + '\n' + trace };
     }
+    _shouldSkipClientSignature(method, params) {
+        if (method !== 'message.send' && method !== 'group.send')
+            return false;
+        if (params.encrypted || params.encrypt)
+            return false;
+        return this._isEchoPayload(params.payload);
+    }
+    _shouldSkipEventSignature(event) {
+        if (event.encrypted || event.encrypt)
+            return false;
+        return this._isEchoPayload(event.payload);
+    }
     _maybeAppendEchoTraceReceive(msg) {
         if (msg.encrypted)
             return;
@@ -1393,16 +1997,108 @@ export class AUNClient {
         const trace = `${this._echoTimestamp()} [AUN-SDK.receive] aid=${this._aid ?? '-'} conn_uptime=${uptime}s`;
         msg.payload = { ...payload, text: payload.text + '\n' + trace };
     }
+    _debugJson(value) {
+        const seen = new WeakSet();
+        try {
+            return JSON.stringify(value, (_key, item) => {
+                if (typeof item === 'bigint')
+                    return item.toString();
+                if (item instanceof Uint8Array) {
+                    return {
+                        _type: item.constructor.name,
+                        len: item.byteLength,
+                        base64: Buffer.from(item).toString('base64'),
+                    };
+                }
+                if (item && typeof item === 'object') {
+                    if (seen.has(item))
+                        return '[Circular]';
+                    seen.add(item);
+                }
+                return item;
+            });
+        }
+        catch {
+            return String(value);
+        }
+    }
+    _messagePayloadForDebug(message) {
+        if (!isJsonObject(message))
+            return message;
+        const msg = message;
+        if ('payload' in msg)
+            return msg.payload;
+        if ('content' in msg)
+            return msg.content;
+        if (typeof msg.envelope_json === 'string' && msg.envelope_json) {
+            try {
+                return JSON.parse(msg.envelope_json);
+            }
+            catch {
+                return msg.envelope_json;
+            }
+        }
+        if (isJsonObject(msg.legacy_v1)) {
+            const legacy = msg.legacy_v1;
+            if ('payload' in legacy)
+                return legacy.payload;
+            if ('content' in legacy)
+                return legacy.content;
+        }
+        return null;
+    }
+    _messageEnvelopeFieldsForDebug(message) {
+        if (!isJsonObject(message)) {
+            return { value_type: typeof message };
+        }
+        const msg = message;
+        const keys = [
+            'message_id', 'id', 'from', 'from_aid', 'sender_aid', 'to', 'to_aid',
+            'group_id', 'seq', 'msg_seq', 'type', 'version', 'timestamp', 't_server',
+            'device_id', 'slot_id', 'encrypted', 'dispatch_mode', 'dispatch',
+            'e2ee', 'headers', 'protected_headers', 'context', 'status',
+            '_decrypt_error', '_decrypt_stage',
+        ];
+        const out = {};
+        for (const key of keys) {
+            if (Object.prototype.hasOwnProperty.call(msg, key))
+                out[key] = msg[key];
+        }
+        return out;
+    }
+    _logMessageDebug(stage, source, event, message, opts = {}) {
+        // 关键消息链路诊断日志长期保留在代码中；是否输出由 logger 的 debug/level 控制。
+        const record = {
+            stage,
+            source,
+            event,
+            envelope: this._messageEnvelopeFieldsForDebug(message),
+            payload: opts.payloadOverride !== undefined ? opts.payloadOverride : this._messagePayloadForDebug(message),
+        };
+        if (opts.extra)
+            record.extra = opts.extra;
+        this._clientLog.debug(`message.debug ${this._debugJson(record)}`);
+    }
+    _logAppMessagePublish(event, payload, source) {
+        if (!['message.received', 'message.undecryptable', 'group.message_created', 'group.message_undecryptable'].includes(event)) {
+            return;
+        }
+        this._logMessageDebug('publish', source, event, payload);
+    }
     _messageTargetsCurrentInstance(message) {
         if (!isJsonObject(message))
             return true;
-        const targetDeviceId = String(message.device_id ?? '').trim();
-        if (targetDeviceId && this._deviceId && targetDeviceId !== this._deviceId) {
-            return false;
+        if ('device_id' in message) {
+            const targetDeviceId = String(message.device_id ?? '').trim();
+            if (targetDeviceId !== this._deviceId) {
+                return false;
+            }
         }
-        const targetSlotId = String(message.slot_id ?? '').trim();
-        if (targetSlotId && this._slotId && targetSlotId !== this._slotId) {
-            return false;
+        if ('slot_id' in message) {
+            const targetSlotId = String(message.slot_id ?? '').trim();
+            if (targetSlotId !== this._slotId) {
+                return false;
+            }
         }
         return true;
     }
@@ -1417,10 +2113,15 @@ export class AUNClient {
         for (const seq of ready) {
             const item = queue.get(seq);
             queue.delete(seq);
-            if (!item || this._pushedSeqs.get(ns)?.has(seq))
+            if (!item)
+                continue;
+            if (this._pushedSeqs.get(ns)?.has(seq)) {
+                this._clientLog.debug(`publish ordered drain skipped duplicate: ns=${ns}, seq=${seq}, event=${item.event}`);
                 continue;
-            await this._publishAppEvent(item.event, item.payload);
+            }
+            await this._publishAppEvent(item.event, item.payload, 'ordered-drain');
             this._markPublishedSeq(ns, seq);
+            this._clientLog.debug(`publish ordered drain delivered: ns=${ns}, seq=${seq}, event=${item.event}`);
         }
         if (queue.size === 0)
             this._pendingOrderedMsgs.delete(ns);
@@ -1428,10 +2129,12 @@ export class AUNClient {
     async _publishOrderedMessage(event, ns, seq, payload) {
         const seqNum = Number(seq);
         if (!Number.isFinite(seqNum) || !Number.isInteger(seqNum) || seqNum <= 0) {
-            await this._publishAppEvent(event, payload);
+            this._clientLog.debug(`publish ordered direct(no-seq): event=${event}, ns=${ns || '<none>'}, seq=${String(seq)}`);
+            await this._publishAppEvent(event, payload, 'ordered');
             return true;
         }
         if (this._pushedSeqs.get(ns)?.has(seqNum)) {
+            this._clientLog.debug(`publish ordered skipped duplicate: event=${event}, ns=${ns}, seq=${seqNum}`);
             const queue = this._pendingOrderedMsgs.get(ns);
             queue?.delete(seqNum);
             if (queue && queue.size === 0)
@@ -1440,29 +2143,35 @@ export class AUNClient {
         }
         const contig = this._seqTracker.getContiguousSeq(ns);
         if (seqNum > contig) {
+            this._clientLog.debug(`publish ordered enqueue(gap): event=${event}, ns=${ns}, seq=${seqNum}, contiguous=${contig}`);
             this._enqueueOrderedMessage(ns, event, seqNum, payload);
             return false;
         }
         await this._drainOrderedMessages(ns, seqNum);
-        if (this._pushedSeqs.get(ns)?.has(seqNum))
+        if (this._pushedSeqs.get(ns)?.has(seqNum)) {
+            this._clientLog.debug(`publish ordered skipped after-drain duplicate: event=${event}, ns=${ns}, seq=${seqNum}`);
             return false;
+        }
         const queue = this._pendingOrderedMsgs.get(ns);
         queue?.delete(seqNum);
         if (queue && queue.size === 0)
             this._pendingOrderedMsgs.delete(ns);
-        await this._publishAppEvent(event, payload);
+        await this._publishAppEvent(event, payload, 'ordered');
         this._markPublishedSeq(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) {
         const seqNum = Number(seq);
         if (!Number.isFinite(seqNum) || !Number.isInteger(seqNum) || seqNum <= 0 || !ns) {
-            await this._publishAppEvent(event, payload);
+            this._clientLog.debug(`publish pulled direct(no-seq): event=${event}, ns=${ns || '<none>'}, seq=${String(seq)}`);
+            await this._publishAppEvent(event, payload, 'pull');
             return true;
         }
         const queue = this._pendingOrderedMsgs.get(ns);
         if (this._pushedSeqs.get(ns)?.has(seqNum)) {
+            this._clientLog.debug(`publish pulled skipped duplicate: event=${event}, ns=${ns}, seq=${seqNum}`);
             queue?.delete(seqNum);
             if (queue && queue.size === 0)
                 this._pendingOrderedMsgs.delete(ns);
@@ -1471,8 +2180,9 @@ export class AUNClient {
         queue?.delete(seqNum);
         if (queue && queue.size === 0)
             this._pendingOrderedMsgs.delete(ns);
-        await this._publishAppEvent(event, payload);
+        await this._publishAppEvent(event, payload, 'pull');
         this._markPublishedSeq(ns, seqNum);
+        this._clientLog.debug(`publish pulled delivered: event=${event}, ns=${ns}, seq=${seqNum}`);
         return true;
     }
     /** 后台补齐群事件空洞 */
@@ -1484,57 +2194,84 @@ export class AUNClient {
         if (this._gapFillDone.has(dedupKey))
             return;
         this._gapFillDone.set(dedupKey, Date.now());
-        this._clientLog.debug(`group event gap fill start: group=${groupId}, after_seq=${afterSeq}`);
         try {
-            const result = await this.call('group.pull_events', {
-                group_id: groupId,
-                after_event_seq: afterSeq,
-                device_id: this._deviceId,
-                limit: 50,
-            });
             let filled = 0;
-            if (isJsonObject(result)) {
+            let nextAfterSeq = afterSeq;
+            const maxPages = 100;
+            let pageCount = 0;
+            while (pageCount < maxPages) {
+                pageCount += 1;
+                this._clientLog.debug(`group event gap fill start: group=${groupId}, after_seq=${nextAfterSeq}`);
+                const result = await this.call('group.pull_events', {
+                    group_id: groupId,
+                    after_event_seq: nextAfterSeq,
+                    device_id: this._deviceId,
+                    limit: 50,
+                });
+                if (!isJsonObject(result))
+                    return;
                 const events = result.events;
-                if (Array.isArray(events)) {
-                    this._seqTracker.onPullResult(ns, events.filter(isJsonObject));
-                    const cursor = isJsonObject(result.cursor) ? result.cursor : null;
-                    const serverAck = cursor ? Number(cursor.current_seq ?? 0) : 0;
-                    if (serverAck > 0) {
-                        const contigBefore = this._seqTracker.getContiguousSeq(ns);
-                        if (contigBefore < serverAck) {
-                            this._clientLog.info(`group.pull_events retention-floor advance: ns=${ns} contiguous=${contigBefore} -> cursor.current_seq=${serverAck}`);
-                            this._seqTracker.forceContiguousSeq(ns, serverAck);
-                        }
-                    }
-                    // 持久化 cursor + ack_events（与 Python 对齐）
-                    this._saveSeqTrackerState();
-                    const contig = this._seqTracker.getContiguousSeq(ns);
-                    if (contig > 0 && (events.length > 0 || serverAck > 0)) {
-                        this._transport.call('group.ack_events', {
-                            group_id: groupId,
-                            event_seq: contig,
-                            device_id: this._deviceId,
-                            slot_id: this._slotId,
-                        }).catch((e) => { this._clientLog.debug(`group event auto-ack failed: group=${groupId} ${formatCaughtError(e)}`); });
+                if (!Array.isArray(events))
+                    return;
+                const pageContigBefore = this._seqTracker.getContiguousSeq(ns);
+                const eventObjects = events.filter(isJsonObject);
+                if (eventObjects.length > 0) {
+                    this._seqTracker.onPullResult(ns, eventObjects, nextAfterSeq);
+                }
+                const cursor = isJsonObject(result.cursor) ? result.cursor : null;
+                const serverAck = cursor ? Number(cursor.current_seq ?? 0) : 0;
+                if (serverAck > 0) {
+                    const contigBeforeFloor = this._seqTracker.getContiguousSeq(ns);
+                    if (contigBeforeFloor < serverAck) {
+                        this._clientLog.info(`group.pull_events retention-floor advance: ns=${ns} contiguous=${contigBeforeFloor} -> cursor.current_seq=${serverAck}`);
+                        this._seqTracker.forceContiguousSeq(ns, serverAck);
                     }
-                    for (const evt of events) {
-                        if (isJsonObject(evt)) {
-                            evt._from_gap_fill = true;
-                            const et = String(evt.event_type ?? '');
-                            // 消息事件由 _fillGroupGap 负责，事件补洞不重复投递
-                            if (et === 'group.message_created')
-                                continue;
-                            // 验签：有 client_signature 就验（与实时事件路径对齐）
-                            const cs = evt.client_signature;
-                            if (cs && typeof cs === 'object') {
-                                evt._verified = await this._verifyEventSignatureAsync(evt, cs);
-                            }
-                            // group.changed 或缺失/其他 → 发布到 group.changed（向后兼容）
-                            await this._dispatcher.publish('group.changed', evt);
-                            filled += 1;
+                }
+                const eventSeqs = [];
+                for (const evt of eventObjects) {
+                    const eventSeq = Number(evt.event_seq ?? 0);
+                    if (Number.isFinite(eventSeq) && eventSeq > 0)
+                        eventSeqs.push(eventSeq);
+                    evt._from_gap_fill = true;
+                    const et = String(evt.event_type ?? '');
+                    // 消息事件由 _fillGroupGap 负责，事件补洞不重复投递
+                    if (et === 'group.message_created')
+                        continue;
+                    // 验签：有 client_signature 就验（与实时事件路径对齐）
+                    const cs = evt.client_signature;
+                    if (cs && typeof cs === 'object') {
+                        if (this._shouldSkipEventSignature(evt)) {
+                            delete evt.client_signature;
+                        }
+                        else {
+                            evt._verified = await this._verifyEventSignatureAsync(evt, cs);
                         }
                     }
+                    // group.changed 或缺失/其他 → 发布到 group.changed（向后兼容）
+                    await this._dispatcher.publish('group.changed', evt);
+                    filled += 1;
                 }
+                const contig = this._seqTracker.getContiguousSeq(ns);
+                if (contig !== pageContigBefore) {
+                    this._saveSeqTrackerState();
+                }
+                if (eventObjects.length > 0 && contig > 0 && contig !== pageContigBefore) {
+                    const maxSeen = this._seqTracker.getMaxSeenSeq(ns);
+                    const ackSeq = maxSeen > 0 ? Math.min(contig, maxSeen) : contig;
+                    this._transport.call('group.ack_events', {
+                        group_id: groupId,
+                        event_seq: ackSeq,
+                        device_id: this._deviceId,
+                        slot_id: this._slotId,
+                    }).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;
+            }
+            if (pageCount >= maxPages) {
+                this._clientLog.warn(`group event gap fill reached max_pages=${maxPages} group=${groupId} after_seq=${nextAfterSeq}`);
             }
             this._clientLog.debug(`group event gap fill done: group=${groupId}, after_seq=${afterSeq}, filled=${filled}`);
         }
@@ -1567,28 +2304,45 @@ export class AUNClient {
                 // 验签：有 client_signature 就验，没有默认安全（H20: 严格 boolean）
                 const cs = d.client_signature;
                 if (cs && isJsonObject(cs)) {
-                    d._verified = await this._verifyEventSignatureAsync(d, cs);
+                    if (this._shouldSkipEventSignature(d)) {
+                        delete d.client_signature;
+                    }
+                    else {
+                        d._verified = await this._verifyEventSignatureAsync(d, cs);
+                    }
                 }
                 await this._dispatcher.publish('group.changed', d);
                 // V2-only：成员/设备变化会影响 group.v2.bootstrap 的设备集与 state commitment。
                 if (groupId) {
                     this._v2BootstrapCache.delete(`group:${groupId}`);
                 }
-                if (groupId && action === 'upsert' && this._v2Session) {
+                const membershipActions = new Set([
+                    'member_added', 'member_left', 'member_removed', 'role_changed',
+                    'owner_transferred', 'joined', 'join_approved', 'invite_code_used',
+                ]);
+                if (groupId && this._v2Session && (action === 'upsert' || membershipActions.has(action))) {
                     this._safeAsync(this._v2AutoProposeState(groupId, { leaderDelay: true }));
                 }
                 // Group SPK 编排：成员变更触发注册/轮换
                 if (this._v2Session && groupId) {
-                    const callFn = async (method, params) => this.call(method, params);
-                    if (action === 'joined' || action === 'join_approved') {
-                        this._v2Session.ensureGroupRegistered?.(groupId, callFn)?.catch(exc => {
-                            this._clientLog.debug(`group SPK registration failed (non-fatal): group=${groupId} action=${action} err=${formatCaughtError(exc)}`);
-                        });
-                    }
-                    else if (['member_added', 'member_left', 'member_removed', 'role_changed', 'owner_transferred'].includes(action)) {
-                        this._v2Session.rotateGroupSPK?.(groupId, callFn)?.catch(exc => {
-                            this._clientLog.debug(`group SPK rotation failed (non-fatal): group=${groupId} action=${action} err=${formatCaughtError(exc)}`);
-                        });
+                    if (membershipActions.has(action)) {
+                        const callFn = async (method, params) => this.call(method, params);
+                        const joinedAid = String(d.joined_aid ?? d.member_aid ?? d.aid ?? '').trim();
+                        const actorAid = String(d.actor_aid ?? '').trim();
+                        const selfAid = String(this._aid ?? '').trim();
+                        const joinActions = new Set(['member_added', 'joined', 'join_approved', 'invite_code_used']);
+                        const isSelfJoin = joinActions.has(action) && !!selfAid && (joinedAid === selfAid ||
+                            (!joinedAid && (action === 'joined' || action === 'invite_code_used') && actorAid === selfAid));
+                        if (isSelfJoin) {
+                            this._v2Session.ensureGroupRegistered?.(groupId, callFn)?.catch(exc => {
+                                this._clientLog.debug(`group SPK registration failed (non-fatal): group=${groupId} action=${action} err=${formatCaughtError(exc)}`);
+                            });
+                        }
+                        else {
+                            this._v2Session.rotateGroupSPK?.(groupId, callFn)?.catch(exc => {
+                                this._clientLog.debug(`group SPK rotation failed (non-fatal): group=${groupId} action=${action} err=${formatCaughtError(exc)}`);
+                            });
+                        }
                     }
                 }
                 // event_seq 空洞检测：持久化后的 group.changed 会携带 event_seq。
@@ -1655,12 +2409,17 @@ export class AUNClient {
             // 提交者签名验证（兼容旧版：无签名时继续）
             const cs = d.client_signature;
             if (cs && isJsonObject(cs)) {
-                const verified = await this._verifyEventSignatureAsync(d, cs);
-                if (verified === false) {
-                    this._clientLog.warn(`state_committed committer signature verification failed group=${groupId}`);
-                    return;
+                if (this._shouldSkipEventSignature(d)) {
+                    delete d.client_signature;
+                }
+                else {
+                    const verified = await this._verifyEventSignatureAsync(d, cs);
+                    if (verified === false) {
+                        this._clientLog.warn(`state_committed committer signature verification failed group=${groupId}`);
+                        return;
+                    }
+                    d._verified = verified;
                 }
-                d._verified = verified;
             }
             const stateVersion = Number(d.state_version ?? 0);
             const stateHash = String(d.state_hash ?? '').trim();
@@ -1815,7 +2574,7 @@ export class AUNClient {
      * 获取对方证书（带缓存 + 完整 PKI 验证）。
      * 跨域时自动路由到 peer 所在域的 Gateway。
      */
-    async _fetchPeerCert(aid, certFingerprint) {
+    async _fetchPeerCert(aid, certFingerprint, timeoutMs = 30_000) {
         const tStart = Date.now();
         this._clientLog.debug(`_fetchPeerCert enter: aid=${aid}, fp=${certFingerprint ?? ''}`);
         try {
@@ -1835,13 +2594,13 @@ export class AUNClient {
             let certPem;
             try {
                 const certUrl = AUNClient._buildCertUrl(peerGatewayUrl, aid, certFingerprint);
-                certPem = await _httpGetText(certUrl, this._configModel.verifySsl);
+                certPem = await _httpGetText(certUrl, this._configModel.verifySsl, timeoutMs);
             }
             catch (exc) {
                 if (!certFingerprint) {
                     throw exc;
                 }
-                const fallbackCert = await _httpGetText(AUNClient._buildCertUrl(peerGatewayUrl, aid), this._configModel.verifySsl);
+                const fallbackCert = await _httpGetText(AUNClient._buildCertUrl(peerGatewayUrl, aid), this._configModel.verifySsl, timeoutMs);
                 certPem = fallbackCert;
             }
             // H7: 严格校验指纹（DER SHA-256 或 SPKI SHA-256 任一匹配即可）
@@ -1894,11 +2653,14 @@ export class AUNClient {
         }
     }
     async _decryptGroupThoughts(result) {
+        this._clientLog.debug(`group.thought.get decrypt enter: found=${String(result.found ?? '')}, group=${String(result.group_id ?? '')}, sender=${String(result.sender_aid ?? '')}`);
         if (!result.found) {
+            this._clientLog.debug('group.thought.get decrypt exit: not found');
             return { ...result, thoughts: [] };
         }
         const items = Array.isArray(result.thoughts) ? result.thoughts.filter(isJsonObject) : [];
         if (items.length === 0) {
+            this._clientLog.debug('group.thought.get decrypt exit: empty thoughts');
             return { ...result, thoughts: [] };
         }
         const groupId = String(result.group_id ?? '');
@@ -1908,26 +2670,32 @@ export class AUNClient {
             const payload = isJsonObject(item.payload) ? item.payload : null;
             const thoughtId = String(item.thought_id ?? item.message_id ?? '');
             const fromAid = String(item.from ?? item.sender_aid ?? senderAid);
+            this._logMessageDebug('thought-get-raw', 'group.thought.get', 'group.thought.get', item, {
+                extra: { group_id: groupId, thought_id: thoughtId, from: fromAid },
+            });
             let decryptFailed = false;
             let decryptedPayload = payload ?? {};
             let e2ee;
             if (payload?.type === 'e2ee.group_encrypted' && String(payload.version ?? '') === 'v2') {
+                e2ee = this._v2E2eeMeta(payload);
                 const plain = await this._decryptV2EnvelopeForThought({ envelope: payload, fromAid });
                 if (plain === null) {
                     decryptFailed = true;
+                    this._clientLog.debug(`group.thought.get decrypt returned null: group=${groupId}, thought_id=${thoughtId}, from=${fromAid}`);
                 }
                 else {
                     decryptedPayload = plain;
-                    e2ee = {
-                        version: 'v2',
-                        suite: String(payload.suite ?? ''),
-                        encryption_mode: `v2_${String(payload.suite ?? 'unknown')}`,
-                        forward_secrecy: true,
-                    };
+                    this._logMessageDebug('thought-decrypt-ok', 'group.thought.get', 'group.thought.get', {
+                        group_id: groupId,
+                        thought_id: thoughtId,
+                        from: fromAid,
+                        payload: plain,
+                    });
                 }
             }
             else if (payload?.type === 'e2ee.group_encrypted') {
                 decryptFailed = true;
+                this._clientLog.debug(`group.thought.get unsupported encrypted payload: group=${groupId}, thought_id=${thoughtId}, type=${String(payload.type ?? '')}, version=${String(payload.version ?? '')}`);
             }
             const thought = {
                 thought_id: thoughtId,
@@ -1935,22 +2703,32 @@ export class AUNClient {
                 payload: decryptFailed ? (payload ?? {}) : decryptedPayload,
                 created_at: item.created_at,
             };
-            if (e2ee !== undefined)
+            if (e2ee !== undefined) {
                 thought.e2ee = e2ee;
+                if (isJsonObject(e2ee))
+                    this._attachV2EnvelopeMetadata(thought, e2ee);
+            }
             if (decryptFailed)
                 thought.decrypt_failed = true;
             if ('context' in item)
                 thought.context = item.context;
+            this._logMessageDebug(decryptFailed ? 'thought-decrypt-fail' : 'thought-result', 'group.thought.get', 'group.thought.get', thought, {
+                extra: { group_id: groupId, thought_id: thoughtId },
+            });
             thoughts.push(thought);
         }
+        this._clientLog.debug(`group.thought.get decrypt exit: group=${groupId}, total=${items.length}, returned=${thoughts.length}`);
         return { ...result, thoughts };
     }
     async _decryptMessageThoughts(result) {
+        this._clientLog.debug(`message.thought.get decrypt enter: found=${String(result.found ?? '')}, peer=${String(result.peer_aid ?? '')}, sender=${String(result.sender_aid ?? '')}`);
         if (!result.found) {
+            this._clientLog.debug('message.thought.get decrypt exit: not found');
             return { ...result, thoughts: [] };
         }
         const items = Array.isArray(result.thoughts) ? result.thoughts.filter(isJsonObject) : [];
         if (items.length === 0) {
+            this._clientLog.debug('message.thought.get decrypt exit: empty thoughts');
             return { ...result, thoughts: [] };
         }
         const senderAid = String(result.sender_aid ?? '');
@@ -1961,26 +2739,32 @@ export class AUNClient {
             const thoughtId = String(item.thought_id ?? item.message_id ?? '');
             const fromAid = String(item.from ?? senderAid);
             const toAid = String(item.to ?? peerAid);
+            this._logMessageDebug('thought-get-raw', 'message.thought.get', 'message.thought.get', item, {
+                extra: { thought_id: thoughtId, from: fromAid, to: toAid },
+            });
             let decryptFailed = false;
             let decryptedPayload = payload ?? {};
             let e2ee;
             if (payload?.type === 'e2ee.p2p_encrypted' && String(payload.version ?? '') === 'v2') {
+                e2ee = this._v2E2eeMeta(payload);
                 const plain = await this._decryptV2EnvelopeForThought({ envelope: payload, fromAid });
                 if (plain === null) {
                     decryptFailed = true;
+                    this._clientLog.debug(`message.thought.get decrypt returned null: thought_id=${thoughtId}, from=${fromAid}, to=${toAid}`);
                 }
                 else {
                     decryptedPayload = plain;
-                    e2ee = {
-                        version: 'v2',
-                        suite: String(payload.suite ?? ''),
-                        encryption_mode: `v2_${String(payload.suite ?? 'unknown')}`,
-                        forward_secrecy: true,
-                    };
+                    this._logMessageDebug('thought-decrypt-ok', 'message.thought.get', 'message.thought.get', {
+                        thought_id: thoughtId,
+                        from: fromAid,
+                        to: toAid,
+                        payload: plain,
+                    });
                 }
             }
             else if (payload?.type === 'e2ee.encrypted' || payload?.type === 'e2ee.p2p_encrypted') {
                 decryptFailed = true;
+                this._clientLog.debug(`message.thought.get unsupported encrypted payload: thought_id=${thoughtId}, type=${String(payload.type ?? '')}, version=${String(payload.version ?? '')}`);
             }
             const thought = {
                 thought_id: thoughtId,
@@ -1990,14 +2774,21 @@ export class AUNClient {
                 payload: decryptFailed ? (payload ?? {}) : decryptedPayload,
                 created_at: item.created_at,
             };
-            if (e2ee !== undefined)
+            if (e2ee !== undefined) {
                 thought.e2ee = e2ee;
+                if (isJsonObject(e2ee))
+                    this._attachV2EnvelopeMetadata(thought, e2ee);
+            }
             if (decryptFailed)
                 thought.decrypt_failed = true;
             if ('context' in item)
                 thought.context = item.context;
+            this._logMessageDebug(decryptFailed ? 'thought-decrypt-fail' : 'thought-result', 'message.thought.get', 'message.thought.get', thought, {
+                extra: { thought_id: thoughtId },
+            });
             thoughts.push(thought);
         }
+        this._clientLog.debug(`message.thought.get decrypt exit: total=${items.length}, returned=${thoughts.length}`);
         return { ...result, thoughts };
     }
     /** 从 keystore 恢复 SeqTracker 状态 */ /** 从 keystore 恢复 SeqTracker 状态 */
@@ -2102,6 +2893,8 @@ export class AUNClient {
         this._gapFillDone.clear();
         this._pushedSeqs.clear();
         this._pendingOrderedMsgs.clear();
+        this._v2SenderIKPending.clear();
+        this._v2SenderIKFetching.clear();
         this._groupSynced.clear();
     }
     _refreshSeqTrackerContext() {
@@ -2112,6 +2905,8 @@ export class AUNClient {
         this._gapFillDone.clear();
         this._pushedSeqs.clear();
         this._pendingOrderedMsgs.clear();
+        this._v2SenderIKPending.clear();
+        this._v2SenderIKFetching.clear();
         this._groupSynced.clear();
         this._seqTrackerContext = nextContext;
     }
@@ -2141,16 +2936,53 @@ export class AUNClient {
             }
         }
         catch (exc) {
-            this._clientLog.warn(`save SeqTracker state failed: ${formatCaughtError(exc)}`);
-            // 通过内部 dispatcher 发布可观测事件，便于上层监控
-            this._dispatcher.publish('seq_tracker.persist_error', {
-                phase: 'save',
-                aid: this._aid,
-                device_id: this._deviceId,
-                slot_id: this._slotId,
-                error: String(formatCaughtError(exc)),
-            }).catch(() => { });
+            this._clientLog.warn(`save SeqTracker state failed: ${formatCaughtError(exc)}`);
+            // 通过内部 dispatcher 发布可观测事件，便于上层监控
+            this._dispatcher.publish('seq_tracker.persist_error', {
+                phase: 'save',
+                aid: this._aid,
+                device_id: this._deviceId,
+                slot_id: this._slotId,
+                error: String(formatCaughtError(exc)),
+            }).catch(() => { });
+        }
+    }
+    _persistRepairedSeq(ns) {
+        if (!this._aid || !ns)
+            return;
+        const seq = this._seqTracker.getContiguousSeq(ns);
+        try {
+            if (seq > 0 && typeof this._keystore.saveSeq === 'function') {
+                this._keystore.saveSeq(this._aid, this._deviceId, this._slotId, ns, seq);
+                return;
+            }
+            const deleteSeq = this._keystore.deleteSeq;
+            if (seq <= 0 && typeof deleteSeq === 'function') {
+                deleteSeq.call(this._keystore, this._aid, this._deviceId, this._slotId, ns);
+                return;
+            }
+            if (seq > 0) {
+                this._saveSeqTrackerState();
+            }
+        }
+        catch (exc) {
+            this._clientLog.debug(`persist repaired seq failed: ns=${ns} err=${formatCaughtError(exc)}`);
+        }
+    }
+    _repairPushContiguousBound(ns, pushSeq, hasPayload, label) {
+        if (!ns || !Number.isFinite(pushSeq) || pushSeq <= 0) {
+            return ns ? this._seqTracker.getContiguousSeq(ns) : 0;
         }
+        const contig = this._seqTracker.getContiguousSeq(ns);
+        const shouldRepair = contig > pushSeq;
+        if (!shouldRepair)
+            return contig;
+        const repairedTo = Math.max(0, pushSeq - 1);
+        this._seqTracker.repairContiguousSeq(ns, repairedTo);
+        const repaired = this._seqTracker.getContiguousSeq(ns);
+        this._persistRepairedSeq(ns);
+        this._clientLog.warn(`${label} push repaired contiguous_seq: ns=${ns} payload=${hasPayload} push_seq=${pushSeq} contiguous=${contig}->${repaired}`);
+        return repaired;
     }
     /** 记录 E2EE 自动编排错误 */
     _logE2eeError(stage, groupId, aid, exc) {
@@ -2370,43 +3202,236 @@ export class AUNClient {
         this._clientLog.debug(`V2 session initialized aid=${this._aid} device=${this._deviceId}`);
         this._safeAsync(this._v2AutoConfirmPendingProposals());
     }
+    async _v2TrustedIKPubDer(aid) {
+        const normalizedAid = String(aid ?? '').trim();
+        if (!normalizedAid)
+            throw new E2EEError('spk_aid_missing');
+        if (this._aid && normalizedAid === this._aid) {
+            if (!this._v2Session)
+                throw new E2EEError('V2 session not initialized');
+            return this._v2Session.currentIkPubDer;
+        }
+        const certPem = await this._fetchPeerCert(normalizedAid);
+        const cert = new crypto.X509Certificate(certPem);
+        const certPubDer = cert.publicKey.export({ type: 'spki', format: 'der' });
+        return new Uint8Array(certPubDer);
+    }
+    _v2SPKTimestampText(value, aid, deviceId, spkId) {
+        if (value === null || value === undefined || value === '') {
+            throw new E2EEError(`spk_timestamp_missing: aid=${aid} device_id=${deviceId} spk_id=${spkId}`);
+        }
+        if (typeof value === 'boolean') {
+            throw new E2EEError(`spk_timestamp_invalid: aid=${aid} device_id=${deviceId} spk_id=${spkId}`);
+        }
+        if (typeof value === 'number') {
+            if (!Number.isSafeInteger(value)) {
+                throw new E2EEError(`spk_timestamp_invalid: aid=${aid} device_id=${deviceId} spk_id=${spkId}`);
+            }
+            return String(value);
+        }
+        const text = String(value).trim();
+        if (!/^\d+$/.test(text)) {
+            throw new E2EEError(`spk_timestamp_invalid: aid=${aid} device_id=${deviceId} spk_id=${spkId}`);
+        }
+        return BigInt(text).toString();
+    }
+    async _v2VerifySPKDevice(args) {
+        if (!this._v2Session)
+            throw new E2EEError('V2 session not initialized');
+        const spkId = String(args.dev.spk_id ?? '').trim();
+        if (!spkId)
+            return;
+        if (args.keySource !== 'peer_device_prekey' && args.keySource !== 'group_device_prekey') {
+            throw new E2EEError(`spk_key_source_invalid: aid=${args.aid} device_id=${args.deviceId} spk_id=${spkId} key_source=${args.keySource}`);
+        }
+        if (!args.spkPkDer || args.spkPkDer.length === 0) {
+            throw new E2EEError(`spk_public_key_missing: aid=${args.aid} device_id=${args.deviceId} spk_id=${spkId}`);
+        }
+        const expectedSpkId = `sha256:${crypto.createHash('sha256').update(Buffer.from(args.spkPkDer)).digest('hex').slice(0, 16)}`;
+        if (spkId !== expectedSpkId) {
+            throw new E2EEError(`spk_id_mismatch: aid=${args.aid} device_id=${args.deviceId} spk_id=${spkId} expected=${expectedSpkId}`);
+        }
+        const trustedIK = await this._v2TrustedIKPubDer(args.aid);
+        if (!_v2BytesEqual(trustedIK, args.ikPkDer)) {
+            throw new E2EEError(`spk_ik_mismatch: aid=${args.aid} device_id=${args.deviceId} spk_id=${spkId}`);
+        }
+        if (_v2BytesEqual(args.spkPkDer, trustedIK)) {
+            this._v2Session.markPeerSPKVerified(args.aid, args.deviceId, spkId);
+            return;
+        }
+        const sigB64 = String(args.dev.spk_signature ?? '').trim();
+        if (!sigB64) {
+            throw new E2EEError(`spk_signature_missing: aid=${args.aid} device_id=${args.deviceId} spk_id=${spkId}`);
+        }
+        let signature;
+        try {
+            signature = _v2B64ToBytesStrict(sigB64);
+        }
+        catch {
+            throw new E2EEError(`spk_signature_invalid_base64: aid=${args.aid} device_id=${args.deviceId} spk_id=${spkId}`);
+        }
+        const tsText = this._v2SPKTimestampText(args.dev.spk_timestamp, args.aid, args.deviceId, spkId);
+        const signData = Buffer.concat([
+            Buffer.from(args.spkPkDer),
+            Buffer.from(spkId, 'utf8'),
+            Buffer.from(tsText, 'utf8'),
+        ]);
+        if (!ecdsaVerifyRaw(trustedIK, signature, new Uint8Array(signData))) {
+            throw new E2EEError(`spk_signature_invalid: aid=${args.aid} device_id=${args.deviceId} spk_id=${spkId}`);
+        }
+        this._v2Session.markPeerSPKVerified(args.aid, args.deviceId, spkId);
+    }
+    async _v2BuildTargetFromDevice(args) {
+        const aid = String(args.aid ?? '').trim();
+        const devId = getV2DeviceId(args.dev);
+        const deviceId = devId.present ? devId.value : String(args.deviceId ?? '').trim();
+        const ikPk = String(args.dev.ik_pk ?? '').trim();
+        if (!aid || !devId.present || !ikPk)
+            return null;
+        const ikPkDer = _v2B64ToBytes(ikPk);
+        const spkPkDer = args.dev.spk_pk ? _v2B64ToBytes(String(args.dev.spk_pk)) : undefined;
+        const keySource = String(args.dev.key_source ?? args.defaultKeySource).trim() || args.defaultKeySource;
+        await this._v2VerifySPKDevice({ dev: args.dev, aid, deviceId, ikPkDer, spkPkDer, keySource });
+        this._v2Session?.cachePeerIK(aid, deviceId, ikPkDer);
+        return {
+            aid,
+            deviceId,
+            role: args.role,
+            keySource,
+            ikPkDer,
+            spkPkDer,
+            spkId: String(args.dev.spk_id ?? '').trim(),
+        };
+    }
     async _getV2SenderPubDer(fromAid, senderDeviceId) {
         const session = this._v2Session;
         if (!session || !fromAid)
             return null;
-        let senderPubDer = session.getPeerIK(fromAid, senderDeviceId);
+        const senderPubDer = session.getPeerIK(fromAid, senderDeviceId);
         if (senderPubDer)
             return senderPubDer;
         try {
-            const bs = await this.call('message.v2.bootstrap', { peer_aid: fromAid });
-            const peers = (Array.isArray(bs?.peer_devices) ? bs.peer_devices : []);
-            for (const dev of peers) {
-                const devId = String(dev.device_id ?? dev.owner_device_id ?? '');
-                const ikPk = String(dev.ik_pk ?? '');
-                if (!devId || !ikPk)
-                    continue;
-                session.cachePeerIK(fromAid, devId, _v2B64ToBytes(ikPk));
-            }
-            senderPubDer = session.getPeerIK(fromAid, senderDeviceId);
-            if (senderPubDer)
-                return senderPubDer;
+            const certPem = await this._fetchPeerCert(fromAid, undefined, 3000);
+            const cert = new crypto.X509Certificate(certPem);
+            const certPubDer = cert.publicKey.export({ type: 'spki', format: 'der' });
+            const certPub = new Uint8Array(certPubDer);
+            session.cachePeerIK(fromAid, senderDeviceId, certPub);
+            this._clientLog.debug(`V2 decrypt: sender IK fallback from PKI cert for ${fromAid}`);
+            return certPub;
         }
         catch (exc) {
-            this._clientLog.warn(`V2 decrypt: bootstrap for sender ${fromAid} failed: ${formatCaughtError(exc)}`);
+            this._clientLog.warn(`V2 decrypt: PKI cert sender IK fallback failed for ${fromAid}: ${formatCaughtError(exc)}`);
+            return null;
         }
+    }
+    _v2PendingSenderIKMessageKey(msg, groupId) {
+        const messageId = String(msg.message_id ?? '').trim();
+        const seq = String(msg.seq ?? '').trim();
+        const prefix = groupId ? `group:${groupId}` : `p2p:${this._aid ?? ''}`;
+        return `${prefix}:${messageId || seq || Math.random().toString(36).slice(2)}`;
+    }
+    _v2PendingSenderIKFetchKey(fromAid, senderDeviceId, groupId) {
+        return `${fromAid}#${senderDeviceId}#${groupId || ''}`;
+    }
+    _cacheV2PeerIKFromDevice(dev, fallbackAid = '') {
+        const session = this._v2Session;
+        if (!session || !isJsonObject(dev))
+            return;
+        const device = dev;
+        const devId = getV2DeviceId(device);
+        const aid = String(device.aid ?? fallbackAid ?? '').trim();
+        const ikPk = String(device.ik_pk ?? '').trim();
+        if (!devId.present || !aid || !ikPk)
+            return;
         try {
-            const certPem = await this._fetchPeerCert(fromAid);
-            const cert = new crypto.X509Certificate(certPem);
-            const certPubDer = cert.publicKey.export({ type: 'spki', format: 'der' });
-            senderPubDer = new Uint8Array(certPubDer);
-            if (senderDeviceId) {
-                session.cachePeerIK(fromAid, senderDeviceId, senderPubDer);
-            }
-            return senderPubDer;
+            session.cachePeerIK(aid, devId.value, _v2B64ToBytes(ikPk));
         }
         catch (exc) {
-            this._clientLog.warn(`V2 decrypt: CA fallback for ${fromAid} failed: ${formatCaughtError(exc)}`);
-            return null;
+            this._clientLog.debug(`V2 sender IK cache from bootstrap skipped aid=${aid} dev=${devId.value}: ${formatCaughtError(exc)}`);
+        }
+    }
+    _scheduleV2SenderIKPending(args) {
+        const fromAid = String(args.fromAid ?? '').trim();
+        if (!fromAid)
+            return;
+        const senderDeviceId = String(args.senderDeviceId ?? '');
+        const groupId = String(args.groupId ?? '').trim();
+        const messageKey = this._v2PendingSenderIKMessageKey(args.msg, groupId);
+        this._v2SenderIKPending.set(messageKey, {
+            msg: { ...args.msg },
+            fromAid,
+            senderDeviceId,
+            groupId,
+            createdAt: Date.now(),
+        });
+        this._clientLog.debug(`V2 decrypt pending sender IK: key=${messageKey} from=${fromAid} device=${senderDeviceId || '-'} group=${groupId || '<p2p>'} pending=${this._v2SenderIKPending.size}`);
+        this._scheduleV2SenderIKFetch(fromAid, senderDeviceId, groupId);
+    }
+    _scheduleV2SenderIKFetch(fromAid, senderDeviceId, groupId) {
+        const fetchKey = this._v2PendingSenderIKFetchKey(fromAid, senderDeviceId, groupId);
+        if (!fromAid || this._v2SenderIKFetching.has(fetchKey))
+            return;
+        this._v2SenderIKFetching.add(fetchKey);
+        this._safeAsync(this._resolveV2SenderIKPending(fromAid, senderDeviceId, groupId, fetchKey));
+    }
+    async _resolveV2SenderIKPending(fromAid, senderDeviceId, groupId, fetchKey) {
+        try {
+            const session = this._v2Session;
+            if (session && fromAid) {
+                try {
+                    const bs = await this.call('message.v2.bootstrap', { peer_aid: fromAid });
+                    const peers = (Array.isArray(bs?.peer_devices) ? bs.peer_devices : []);
+                    for (const dev of peers)
+                        this._cacheV2PeerIKFromDevice(dev, fromAid);
+                }
+                catch (exc) {
+                    this._clientLog.warn(`V2 sender IK pending bootstrap failed peer=${fromAid}: ${formatCaughtError(exc)}`);
+                }
+                if (groupId) {
+                    try {
+                        const gbs = await this.call('group.v2.bootstrap', { group_id: groupId });
+                        const devices = (Array.isArray(gbs?.devices) ? gbs.devices : []);
+                        const audit = (Array.isArray(gbs?.audit_recipients) ? gbs.audit_recipients : []);
+                        for (const dev of devices)
+                            this._cacheV2PeerIKFromDevice(dev);
+                        for (const dev of audit)
+                            this._cacheV2PeerIKFromDevice(dev);
+                    }
+                    catch (exc) {
+                        this._clientLog.warn(`V2 sender IK pending group bootstrap failed group=${groupId}: ${formatCaughtError(exc)}`);
+                    }
+                }
+                if (!session.getPeerIK(fromAid, senderDeviceId)) {
+                    await this._getV2SenderPubDer(fromAid, senderDeviceId);
+                }
+            }
+            const pendingItems = [...this._v2SenderIKPending.entries()].filter(([, entry]) => entry.fromAid === fromAid && entry.senderDeviceId === senderDeviceId && entry.groupId === groupId);
+            for (const [key, entry] of pendingItems) {
+                let plaintext = null;
+                try {
+                    plaintext = await this._decryptV2Message(entry.msg, false);
+                }
+                catch (exc) {
+                    this._clientLog.warn(`V2 sender IK pending retry raised: key=${key} err=${formatCaughtError(exc)}`);
+                }
+                this._v2SenderIKPending.delete(key);
+                if (plaintext === null) {
+                    this._clientLog.debug(`V2 sender IK pending retry failed: key=${key}`);
+                    continue;
+                }
+                const seq = Number(entry.msg.seq ?? 0);
+                if (entry.groupId) {
+                    plaintext.group_id = entry.groupId;
+                    await this._publishPulledMessage('group.message_created', `group:${entry.groupId}`, seq, plaintext);
+                }
+                else {
+                    await this._publishPulledMessage('message.received', `p2p:${this._aid ?? ''}`, seq, plaintext);
+                }
+                this._clientLog.debug(`V2 sender IK pending retry delivered: key=${key}`);
+            }
+        }
+        finally {
+            this._v2SenderIKFetching.delete(fetchKey);
         }
     }
     /**
@@ -2427,11 +3452,13 @@ export class AUNClient {
         if (cached && Date.now() - cached.cachedAt < AUNClient.V2_BOOTSTRAP_TTL_MS) {
             peerDevices = cached.devices;
             auditRaw = cached.auditRecipients;
+            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 });
             peerDevices = (Array.isArray(bs?.peer_devices) ? bs.peer_devices : []);
             auditRaw = (Array.isArray(bs?.audit_recipients) ? bs.audit_recipients : []);
+            this._clientLog.debug(`message.v2.bootstrap fetched: to=${to}, devices=${peerDevices.length}, audit=${auditRaw.length}`);
             if (peerDevices.length > 0) {
                 this._v2BootstrapCache.set(to, {
                     devices: peerDevices,
@@ -2445,37 +3472,28 @@ export class AUNClient {
         }
         const targets = [];
         for (const dev of peerDevices) {
-            const ikPk = String(dev.ik_pk ?? '');
-            if (!ikPk)
-                continue;
-            const devId = String(dev.device_id ?? dev.owner_device_id ?? '');
-            const ikDer = _v2B64ToBytes(ikPk);
-            const spkDer = dev.spk_pk ? _v2B64ToBytes(String(dev.spk_pk)) : undefined;
-            session.cachePeerIK(to, devId, ikDer);
-            targets.push({
+            const devId = getV2DeviceId(dev);
+            const target = await this._v2BuildTargetFromDevice({
+                dev,
                 aid: to,
-                deviceId: devId,
+                deviceId: devId.value,
                 role: 'peer',
-                keySource: String(dev.key_source ?? 'peer_device_prekey'),
-                ikPkDer: ikDer,
-                spkPkDer: spkDer,
-                spkId: String(dev.spk_id ?? ''),
+                defaultKeySource: 'peer_device_prekey',
             });
+            if (target)
+                targets.push(target);
         }
         const auditTargets = [];
         for (const dev of auditRaw) {
-            const ikPk = String(dev.ik_pk ?? '');
-            if (!ikPk)
-                continue;
-            auditTargets.push({
+            const target = await this._v2BuildTargetFromDevice({
+                dev,
                 aid: String(dev.aid ?? ''),
                 deviceId: String(dev.device_id ?? ''),
                 role: 'audit',
-                keySource: String(dev.key_source ?? 'peer_device_prekey'),
-                ikPkDer: _v2B64ToBytes(ikPk),
-                spkPkDer: dev.spk_pk ? _v2B64ToBytes(String(dev.spk_pk)) : undefined,
-                spkId: String(dev.spk_id ?? ''),
+                defaultKeySource: 'peer_device_prekey',
             });
+            if (target)
+                auditTargets.push(target);
         }
         // self-sync：给同 AID 其它在线/注册设备也 wrap 一份。
         if (this._aid && this._aid !== to) {
@@ -2497,19 +3515,18 @@ export class AUNClient {
                     }
                 }
                 for (const dev of selfDevices) {
-                    const devId = String(dev.owner_device_id ?? dev.device_id ?? '');
-                    const ikPk = String(dev.ik_pk ?? '');
-                    if (!devId || devId === this._deviceId || !ikPk)
+                    const devId = getV2DeviceId(dev);
+                    if (!devId.present || devId.value === this._deviceId)
                         continue;
-                    targets.push({
+                    const target = await this._v2BuildTargetFromDevice({
+                        dev,
                         aid: this._aid,
-                        deviceId: devId,
+                        deviceId: devId.value,
                         role: 'self_sync',
-                        keySource: String(dev.key_source ?? 'peer_device_prekey'),
-                        ikPkDer: _v2B64ToBytes(ikPk),
-                        spkPkDer: dev.spk_pk ? _v2B64ToBytes(String(dev.spk_pk)) : undefined,
-                        spkId: String(dev.spk_id ?? ''),
+                        defaultKeySource: 'peer_device_prekey',
                     });
+                    if (target)
+                        targets.push(target);
                 }
             }
             catch (exc) {
@@ -2519,12 +3536,29 @@ export class AUNClient {
         if (targets.length === 0) {
             throw new E2EEError(`V2 bootstrap: no usable devices found for ${to}`);
         }
-        return encryptP2PMessage(session.getSenderIdentity(), { targets, auditRecipients: auditTargets }, opts.payload, {
+        const envelope = encryptP2PMessage(session.getSenderIdentity(), { targets, auditRecipients: auditTargets }, opts.payload, {
             messageId: opts.messageId,
             timestamp: opts.timestamp,
             protectedHeaders: opts.protectedHeaders,
             context: opts.context,
         });
+        this._logMessageDebug('send-envelope', 'message.send.v2', 'message.send', {
+            message_id: envelope.message_id,
+            to,
+            type: envelope.type,
+            version: envelope.version,
+            protected_headers: envelope.protected_headers,
+            context: envelope.context,
+        }, {
+            payloadOverride: envelope,
+            extra: {
+                plaintext_payload: opts.payload,
+                target_count: targets.length,
+                audit_count: auditTargets.length,
+                use_cache: useCache,
+            },
+        });
+        return envelope;
     }
     /** V2 P2P 加密发送，推测性缓存失败后刷新 bootstrap 重试一次。 */
     async sendV2(to, payload, opts) {
@@ -2534,7 +3568,13 @@ export class AUNClient {
             throw new ValidationError("message.send requires 'to'");
         if (!isJsonObject(payload))
             throw new ValidationError('message.send payload must be a dict for V2 encryption');
+        this._logMessageDebug('send-plaintext', 'message.send.v2', 'message.send', {
+            to: toAid,
+            message_id: opts?.messageId ?? '',
+            payload,
+        }, { payloadOverride: payload });
         const attempt = async (useCache) => {
+            this._clientLog.debug(`message.v2.send attempt: to=${toAid}, use_cache=${useCache}`);
             const envelope = await this._buildV2P2PEnvelope({
                 to: toAid,
                 payload,
@@ -2544,11 +3584,13 @@ export class AUNClient {
                 context: opts?.context,
                 useCache,
             });
-            return await this.call('message.send', {
+            const result = await this.call('message.send', {
                 to: toAid,
                 payload: envelope,
                 encrypt: false,
             });
+            this._clientLog.debug(`message.v2.send ok: to=${toAid}, use_cache=${useCache}, seq=${String((isJsonObject(result) ? result.seq : '') ?? '')}`);
+            return result;
         };
         try {
             return await attempt(true);
@@ -2567,90 +3609,130 @@ export class AUNClient {
     async pullV2(afterSeq = 0, limit = 50) {
         await this._ensureV2SessionReady('message.pull');
         const ns = this._aid ? `p2p:${this._aid}` : '';
-        const effective = afterSeq || (ns ? this._seqTracker.getContiguousSeq(ns) : 0);
-        const result = await this.call('message.v2.pull', { after_seq: effective, limit });
-        const messages = (Array.isArray(result?.messages) ? result.messages : []);
         const decrypted = [];
-        const seqs = messages
-            .map((msg) => Number(msg.seq ?? 0))
-            .filter((seq) => Number.isFinite(seq) && seq > 0);
-        const contigBefore = ns ? this._seqTracker.getContiguousSeq(ns) : 0;
-        if (ns && seqs.length > 0 && seqs[0] > contigBefore) {
-            this._seqTracker.forceContiguousSeq(ns, seqs[0]);
-        }
-        for (const msg of messages) {
-            const seq = Number(msg.seq ?? 0);
-            if (!Number.isFinite(seq) || seq <= 0)
-                continue;
-            const version = String(msg.version ?? 'v2');
-            if (version === 'v1') {
-                const legacy = isJsonObject(msg.legacy_v1) ? msg.legacy_v1 : {};
-                const legacyPayload = legacy.payload;
-                const payloadType = isJsonObject(legacyPayload)
-                    ? String(legacyPayload.type ?? '').trim()
-                    : '';
-                if (legacyPayload !== undefined && legacyPayload !== null && payloadType !== 'e2ee.encrypted' && payloadType !== 'e2ee.group_encrypted') {
-                    const v1Msg = {
-                        message_id: String(msg.message_id ?? ''),
-                        from: String(msg.from_aid ?? ''),
-                        to: String(legacy.to ?? this._aid ?? ''),
-                        seq: msg.seq,
-                        type: String(msg.type ?? ''),
-                        timestamp: msg.t_server,
-                        payload: legacyPayload,
-                        encrypted: false,
-                    };
-                    if (ns)
-                        await this._publishPulledMessage('message.received', ns, seq, v1Msg);
-                    else
-                        await this._publishAppEvent('message.received', v1Msg);
-                    decrypted.push(v1Msg);
+        let nextAfterSeq = afterSeq || (ns ? this._seqTracker.getContiguousSeq(ns) : 0);
+        let pageCount = 0;
+        const maxPages = 100;
+        while (pageCount < maxPages) {
+            pageCount += 1;
+            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 messages = (Array.isArray(result?.messages) ? result.messages : []);
+            this._clientLog.debug(`message.v2.pull page response: page=${pageCount}, raw_count=${messages.length}, has_more=${String(result.has_more ?? '')}, server_ack_seq=${String(result.server_ack_seq ?? '')}`);
+            for (const msg of messages) {
+                this._logMessageDebug('pull-raw', 'message.v2.pull', 'message.received', msg);
+            }
+            const seqs = messages
+                .map((msg) => Number(msg.seq ?? 0))
+                .filter((seq) => Number.isFinite(seq) && seq > 0);
+            const pageContigBefore = ns ? this._seqTracker.getContiguousSeq(ns) : 0;
+            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}`);
+            }
+            for (const msg of messages) {
+                const seq = Number(msg.seq ?? 0);
+                if (!Number.isFinite(seq) || seq <= 0)
+                    continue;
+                const version = String(msg.version ?? 'v2');
+                if (version === 'v1') {
+                    const legacy = isJsonObject(msg.legacy_v1) ? msg.legacy_v1 : {};
+                    const legacyPayload = legacy.payload;
+                    const payloadType = isJsonObject(legacyPayload)
+                        ? String(legacyPayload.type ?? '').trim()
+                        : '';
+                    if (legacyPayload !== undefined && legacyPayload !== null && payloadType !== 'e2ee.encrypted' && payloadType !== 'e2ee.group_encrypted') {
+                        const v1Msg = {
+                            message_id: String(msg.message_id ?? ''),
+                            from: String(msg.from_aid ?? ''),
+                            to: String(legacy.to ?? this._aid ?? ''),
+                            seq: msg.seq,
+                            type: String(msg.type ?? ''),
+                            timestamp: msg.t_server,
+                            payload: legacyPayload,
+                            encrypted: false,
+                        };
+                        if (ns)
+                            await this._publishPulledMessage('message.received', ns, seq, v1Msg);
+                        else
+                            await this._publishAppEvent('message.received', v1Msg, 'pull');
+                        decrypted.push(v1Msg);
+                        this._clientLog.debug(`message.v2.pull plaintext V1 delivered: seq=${seq}, ns=${ns || '<none>'}`);
+                    }
+                    else {
+                        this._clientLog.debug(`message.v2.pull skipping V1 envelope seq=${seq} payload_type=${payloadType || '<none>'} (V1 E2EE removed)`);
+                    }
+                    continue;
                 }
-                else {
-                    this._clientLog.debug(`message.v2.pull skipping V1 envelope seq=${seq} payload_type=${payloadType || '<none>'} (V1 E2EE removed)`);
+                if (version !== 'v2') {
+                    this._clientLog.debug(`message.v2.pull skipping non-V2 row seq=${seq} version=${String(msg.version ?? '')}`);
+                    continue;
+                }
+                const spkId = String(msg.spk_id ?? '');
+                if (spkId && this._v2Session && !this._v2Session.isCurrentSPK(spkId)) {
+                    this._v2Session.trackOldSPKMaxSeq(spkId, seq);
+                }
+                const plaintext = await this._decryptV2Message(msg);
+                if (plaintext === null) {
+                    this._clientLog.debug(`message.v2.pull decrypt returned null: seq=${seq}, ns=${ns || '<none>'}`);
+                    continue;
+                }
+                if (ns)
+                    await this._publishPulledMessage('message.received', ns, seq, plaintext);
+                else
+                    await this._publishAppEvent('message.received', plaintext, 'pull');
+                decrypted.push(plaintext);
+                this._logMessageDebug('decrypt-ok', 'message.v2.pull', 'message.received', plaintext);
+            }
+            const serverAckSeq = Number(result.server_ack_seq ?? 0);
+            if (ns && Number.isFinite(serverAckSeq) && serverAckSeq > 0) {
+                const contig = this._seqTracker.getContiguousSeq(ns);
+                if (contig < serverAckSeq) {
+                    this._clientLog.info(`message.v2.pull retention-floor advance: ns=${ns} contiguous=${contig} -> server_ack_seq=${serverAckSeq}`);
+                    this._seqTracker.forceContiguousSeq(ns, serverAckSeq);
                 }
-                continue;
-            }
-            if (version !== 'v2') {
-                this._clientLog.debug(`message.v2.pull skipping non-V2 row seq=${seq} version=${String(msg.version ?? '')}`);
-                continue;
-            }
-            const spkId = String(msg.spk_id ?? '');
-            if (spkId && this._v2Session && !this._v2Session.isCurrentSPK(spkId)) {
-                this._v2Session.trackOldSPKMaxSeq(spkId, seq);
-            }
-            const plaintext = await this._decryptV2Message(msg);
-            if (plaintext === null)
-                continue;
-            if (ns)
-                await this._publishPulledMessage('message.received', ns, seq, plaintext);
-            else
-                await this._publishAppEvent('message.received', plaintext);
-            decrypted.push(plaintext);
-        }
-        if (ns && seqs.length > 0) {
-            const maxSeq = Math.max(...seqs);
-            const contig = this._seqTracker.getContiguousSeq(ns);
-            if (maxSeq > contig) {
-                this._seqTracker.forceContiguousSeq(ns, maxSeq);
-                await this._drainOrderedMessages(ns);
-            }
-            const ackSeq = this._seqTracker.getContiguousSeq(ns);
-            if (ackSeq !== contigBefore) {
-                this._saveSeqTrackerState();
             }
-            if (ackSeq > 0 && ackSeq !== contigBefore) {
-                this._safeAsync(this.ackV2(ackSeq).then(() => undefined));
+            if (ns) {
+                const ackSeq = this._seqTracker.getContiguousSeq(ns);
+                const contigAdvanced = ackSeq !== pageContigBefore;
+                if (contigAdvanced) {
+                    await this._drainOrderedMessages(ns);
+                    this._saveSeqTrackerState();
+                }
+                if (messages.length > 0 && contigAdvanced && ackSeq > 0) {
+                    this._clientLog.debug(`message.v2.pull scheduling auto-ack: ns=${ns}, ack_seq=${ackSeq}, raw_count=${messages.length}`);
+                    this._safeAsync(this.ackV2(ackSeq).then(() => undefined));
+                }
             }
+            const nextAfter = Math.max(pageMaxSeq, nextAfterSeq);
+            if (messages.length === 0 || nextAfter <= nextAfterSeq || result.has_more === false)
+                break;
+            nextAfterSeq = nextAfter;
         }
+        if (pageCount >= maxPages) {
+            this._clientLog.warn(`message.v2.pull reached max_pages=${maxPages} after_seq=${nextAfterSeq}`);
+        }
+        this._clientLog.debug(`message.v2.pull done: requested_after_seq=${afterSeq}, pages=${pageCount}, decrypted=${decrypted.length}, ns=${ns || '<none>'}`);
         return decrypted;
     }
     /** V2 P2P ack，并触发旧 SPK 销毁自检。 */
     async ackV2(upToSeq) {
         const ns = this._aid ? `p2p:${this._aid}` : '';
-        const seq = Number(upToSeq ?? (ns ? this._seqTracker.getContiguousSeq(ns) : 0));
-        if (!Number.isFinite(seq) || seq <= 0)
+        let seq = Number(upToSeq ?? (ns ? this._seqTracker.getContiguousSeq(ns) : 0));
+        if (!Number.isFinite(seq) || seq <= 0) {
+            this._clientLog.debug(`message.v2.ack skipped: ns=${ns || '<none>'}, up_to_seq=${String(upToSeq ?? '')}`);
             return { acked: 0 };
+        }
+        // ack clamp：永远不发送超过 maxSeenSeq 的 up_to_seq
+        if (ns) {
+            const maxSeen = this._seqTracker.getMaxSeenSeq(ns);
+            if (maxSeen > 0 && seq > maxSeen) {
+                this._clientLog.warn(`ackV2 clamp: up_to_seq=${seq} > max_seen=${maxSeen}, clamp`);
+                seq = maxSeen;
+            }
+        }
+        this._clientLog.debug(`message.v2.ack send: ns=${ns || '<none>'}, up_to_seq=${seq}`);
         const raw = await this.call('message.v2.ack', { up_to_seq: seq });
         const result = isJsonObject(raw)
             ? { ...raw }
@@ -2679,6 +3761,7 @@ export class AUNClient {
                 this._clientLog.debug(`V2 SPK destroy failed (non-fatal): ${formatCaughtError(exc)}`);
             }
         }
+        this._clientLog.debug(`message.v2.ack ok: ns=${ns || '<none>'}, requested=${seq}, effective=${actualAckSeq}, acked=${String(result.acked ?? '')}`);
         return result;
     }
     /** V2 Group 加密发送，推测性缓存失败后刷新 bootstrap 重试一次。 */
@@ -2689,7 +3772,13 @@ export class AUNClient {
             throw new ValidationError("group.send requires 'group_id'");
         if (!isJsonObject(payload))
             throw new ValidationError('group.send payload must be a dict for V2 encryption');
+        this._logMessageDebug('send-plaintext', 'group.send.v2', 'group.send', {
+            group_id: gid,
+            message_id: opts?.messageId ?? '',
+            payload,
+        }, { payloadOverride: payload });
         const attempt = async (useCache) => {
+            this._clientLog.debug(`group.v2.send attempt: group=${gid}, use_cache=${useCache}`);
             const envelope = await this._buildV2GroupEnvelope({
                 groupId: gid,
                 payload,
@@ -2699,10 +3788,12 @@ export class AUNClient {
                 context: opts?.context,
                 useCache,
             });
-            return await this.call('group.v2.send', {
+            const result = await this.call('group.v2.send', {
                 group_id: gid,
                 envelope: envelope,
             });
+            this._clientLog.debug(`group.v2.send ok: group=${gid}, use_cache=${useCache}, seq=${String((isJsonObject(result) ? result.seq : '') ?? '')}`);
+            return result;
         };
         const markSentSeq = (result) => {
             if (!isJsonObject(result))
@@ -2715,6 +3806,7 @@ export class AUNClient {
             this._seqTracker.onMessageSeq(ns, seq);
             this._markPublishedSeq(ns, seq);
             this._saveSeqTrackerState();
+            this._clientLog.debug(`group.v2.send marked own seq: group=${gid}, ns=${ns}, seq=${seq}`);
         };
         try {
             const result = await attempt(true);
@@ -2753,12 +3845,14 @@ export class AUNClient {
             auditRecipientsRaw = cached.auditRecipients;
             epoch = cached.epoch ?? 0;
             stateCommitment = cached.stateCommitment ?? stateCommitment;
+            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 });
             allDevices = (Array.isArray(bs.devices) ? bs.devices : []);
             auditRecipientsRaw = (Array.isArray(bs.audit_recipients) ? bs.audit_recipients : []);
             epoch = Number(bs.epoch ?? 0) || 0;
+            this._clientLog.debug(`group.v2.bootstrap fetched: group=${groupId}, devices=${allDevices.length}, audit=${auditRecipientsRaw.length}, epoch=${epoch}, members=${Array.isArray(bs.member_aids) ? bs.member_aids.length : 0}`);
             const stateChain = String(bs.state_chain ?? '');
             await this._v2CheckFork(groupId, stateChain);
             await this._v2VerifyStateSignature(groupId, bs);
@@ -2789,46 +3883,59 @@ export class AUNClient {
         const targets = [];
         for (const dev of allDevices) {
             const devAid = String(dev.aid ?? '').trim();
-            const devId = String(dev.device_id ?? '').trim();
-            const ikPk = String(dev.ik_pk ?? '').trim();
-            if (!devAid || !devId || !ikPk)
-                continue;
-            if (devAid === this._aid && devId === this._deviceId)
+            const devId = getV2DeviceId(dev);
+            if (devAid === this._aid && devId.present && devId.value === this._deviceId)
                 continue;
             const role = devAid === this._aid ? 'self_sync' : 'member';
-            targets.push({
+            const target = await this._v2BuildTargetFromDevice({
+                dev,
                 aid: devAid,
-                deviceId: devId,
+                deviceId: devId.value,
                 role,
-                keySource: String(dev.key_source ?? 'peer_device_prekey'),
-                ikPkDer: _v2B64ToBytes(ikPk),
-                spkPkDer: dev.spk_pk ? _v2B64ToBytes(String(dev.spk_pk)) : undefined,
-                spkId: String(dev.spk_id ?? ''),
+                defaultKeySource: 'peer_device_prekey',
             });
+            if (target)
+                targets.push(target);
         }
         if (targets.length === 0) {
             throw new E2EEError(`V2 group: no target devices for group ${groupId}`);
         }
         for (const dev of auditRecipientsRaw) {
-            const ikPk = String(dev.ik_pk ?? '').trim();
-            if (!ikPk)
-                continue;
-            targets.push({
+            const target = await this._v2BuildTargetFromDevice({
+                dev,
                 aid: String(dev.aid ?? ''),
                 deviceId: String(dev.device_id ?? ''),
                 role: 'audit',
-                keySource: String(dev.key_source ?? 'peer_device_prekey'),
-                ikPkDer: _v2B64ToBytes(ikPk),
-                spkPkDer: dev.spk_pk ? _v2B64ToBytes(String(dev.spk_pk)) : undefined,
-                spkId: String(dev.spk_id ?? ''),
+                defaultKeySource: 'peer_device_prekey',
             });
+            if (target)
+                targets.push(target);
         }
-        return encryptGroupMessage(session.getSenderIdentity(), groupId, epoch, targets, opts.payload, {
+        const envelope = encryptGroupMessage(session.getSenderIdentity(), groupId, epoch, targets, opts.payload, {
             messageId: opts.messageId,
             timestamp: opts.timestamp,
             protectedHeaders: opts.protectedHeaders,
             context: opts.context,
         }, stateCommitment);
+        this._logMessageDebug('send-envelope', 'group.send.v2', 'group.send', {
+            group_id: groupId,
+            message_id: envelope.message_id,
+            type: envelope.type,
+            version: envelope.version,
+            protected_headers: envelope.protected_headers,
+            context: envelope.context,
+        }, {
+            payloadOverride: envelope,
+            extra: {
+                plaintext_payload: opts.payload,
+                epoch,
+                target_count: targets.length,
+                audit_count: auditRecipientsRaw.length,
+                state_version: stateCommitment.state_version,
+                use_cache: useCache,
+            },
+        });
+        return envelope;
     }
     async _pullGroupV2Internal(params) {
         await this.pullGroupV2(params.group_id, params.after_seq, params.limit);
@@ -2840,32 +3947,61 @@ export class AUNClient {
         if (!gid)
             throw new ValidationError('group.pull requires group_id');
         const ns = `group:${gid}`;
-        const effective = afterSeq || this._seqTracker.getContiguousSeq(ns);
-        const result = await this.call('group.v2.pull', {
-            group_id: gid,
-            after_seq: effective,
-            limit,
-        });
-        const messages = (Array.isArray(result.messages) ? result.messages : []);
         const decrypted = [];
-        const seqs = messages
-            .map((msg) => Number(msg.seq ?? 0))
-            .filter((seq) => Number.isFinite(seq) && seq > 0);
-        const contigBefore = this._seqTracker.getContiguousSeq(ns);
-        if (seqs.length > 0 && seqs[0] > contigBefore) {
-            this._seqTracker.forceContiguousSeq(ns, seqs[0]);
-        }
-        for (const msg of messages) {
-            const seq = Number(msg.seq ?? 0);
-            if (!Number.isFinite(seq) || seq <= 0)
-                continue;
-            const version = String(msg.version ?? 'v2');
-            if (version === 'v1') {
-                const payload = msg.payload;
-                const payloadObj = isJsonObject(payload) ? payload : null;
-                if (payloadObj) {
-                    const payloadType = String(payloadObj.type ?? '').trim();
-                    if (payloadType !== 'e2ee.encrypted' && payloadType !== 'e2ee.group_encrypted') {
+        let nextAfterSeq = afterSeq || this._seqTracker.getContiguousSeq(ns);
+        let pageCount = 0;
+        const maxPages = 100;
+        while (pageCount < maxPages) {
+            pageCount += 1;
+            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', {
+                group_id: gid,
+                after_seq: nextAfterSeq,
+                limit,
+            });
+            const messages = (Array.isArray(result.messages) ? result.messages : []);
+            const cursor = isJsonObject(result.cursor) ? result.cursor : null;
+            this._clientLog.debug(`group.v2.pull page response: group=${gid}, page=${pageCount}, raw_count=${messages.length}, has_more=${String(result.has_more ?? '')}, cursor_current=${String(cursor?.current_seq ?? '')}`);
+            for (const msg of messages) {
+                this._logMessageDebug('pull-raw', 'group.v2.pull', 'group.message_created', msg);
+            }
+            const seqs = messages
+                .map((msg) => Number(msg.seq ?? 0))
+                .filter((seq) => Number.isFinite(seq) && seq > 0);
+            const pageContigBefore = this._seqTracker.getContiguousSeq(ns);
+            const pageMaxSeq = seqs.length > 0 ? Math.max(...seqs) : nextAfterSeq;
+            if (seqs.length > 0) {
+                this._seqTracker.forceContiguousSeq(ns, pageMaxSeq);
+                this._clientLog.debug(`group.v2.pull force contiguous: group=${gid}, ns=${ns}, page_max_seq=${pageMaxSeq}, previous=${pageContigBefore}`);
+            }
+            for (const msg of messages) {
+                const seq = Number(msg.seq ?? 0);
+                if (!Number.isFinite(seq) || seq <= 0)
+                    continue;
+                const version = String(msg.version ?? 'v2');
+                if (version === 'v1') {
+                    const payload = msg.payload;
+                    const payloadObj = isJsonObject(payload) ? payload : null;
+                    if (payloadObj) {
+                        const payloadType = String(payloadObj.type ?? '').trim();
+                        if (payloadType !== 'e2ee.encrypted' && payloadType !== 'e2ee.group_encrypted') {
+                            const v1Msg = {
+                                message_id: String(msg.message_id ?? ''),
+                                from: String(msg.from_aid ?? ''),
+                                group_id: gid,
+                                seq: msg.seq,
+                                type: String(msg.type ?? ''),
+                                timestamp: msg.t_server,
+                                payload,
+                                encrypted: false,
+                            };
+                            await this._publishPulledMessage('group.message_created', ns, seq, v1Msg);
+                            decrypted.push(v1Msg);
+                            this._clientLog.debug(`group.v2.pull plaintext V1 delivered: group=${gid}, seq=${seq}`);
+                            continue;
+                        }
+                    }
+                    else if (payload !== undefined && payload !== null) {
                         const v1Msg = {
                             message_id: String(msg.message_id ?? ''),
                             from: String(msg.from_aid ?? ''),
@@ -2878,53 +4014,53 @@ export class AUNClient {
                         };
                         await this._publishPulledMessage('group.message_created', ns, seq, v1Msg);
                         decrypted.push(v1Msg);
+                        this._clientLog.debug(`group.v2.pull plaintext V1 delivered: group=${gid}, seq=${seq}`);
                         continue;
                     }
+                    this._clientLog.debug(`group.v2.pull skipping V1 envelope group=${gid} seq=${seq} payload_type=${payloadObj ? String(payloadObj.type ?? '') : '<none>'} (V1 E2EE removed)`);
+                    continue;
                 }
-                else if (payload !== undefined && payload !== null) {
-                    const v1Msg = {
-                        message_id: String(msg.message_id ?? ''),
-                        from: String(msg.from_aid ?? ''),
-                        group_id: gid,
-                        seq: msg.seq,
-                        type: String(msg.type ?? ''),
-                        timestamp: msg.t_server,
-                        payload,
-                        encrypted: false,
-                    };
-                    await this._publishPulledMessage('group.message_created', ns, seq, v1Msg);
-                    decrypted.push(v1Msg);
+                if (version !== 'v2') {
+                    this._clientLog.debug(`group.v2.pull skipping non-V2 row group=${gid} seq=${seq} version=${String(msg.version ?? '')}`);
                     continue;
                 }
-                this._clientLog.debug(`group.v2.pull skipping V1 envelope group=${gid} seq=${seq} payload_type=${payloadObj ? String(payloadObj.type ?? '') : '<none>'} (V1 E2EE removed)`);
-                continue;
-            }
-            if (version !== 'v2') {
-                this._clientLog.debug(`group.v2.pull skipping non-V2 row group=${gid} seq=${seq} version=${String(msg.version ?? '')}`);
-                continue;
+                const plaintext = await this._decryptV2Message(msg);
+                if (plaintext === null) {
+                    this._clientLog.debug(`group.v2.pull decrypt returned null: group=${gid}, seq=${seq}`);
+                    continue;
+                }
+                plaintext.group_id = gid;
+                await this._publishPulledMessage('group.message_created', ns, seq, plaintext);
+                decrypted.push(plaintext);
+                this._logMessageDebug('decrypt-ok', 'group.v2.pull', 'group.message_created', plaintext);
+            }
+            const serverAckSeq = Number(cursor?.current_seq ?? 0);
+            if (Number.isFinite(serverAckSeq) && serverAckSeq > 0) {
+                const contig = this._seqTracker.getContiguousSeq(ns);
+                if (contig < serverAckSeq) {
+                    this._clientLog.info(`group.v2.pull retention-floor advance: ns=${ns} contiguous=${contig} -> cursor.current_seq=${serverAckSeq}`);
+                    this._seqTracker.forceContiguousSeq(ns, serverAckSeq);
+                }
             }
-            const plaintext = await this._decryptV2Message(msg);
-            if (plaintext === null)
-                continue;
-            plaintext.group_id = gid;
-            await this._publishPulledMessage('group.message_created', ns, seq, plaintext);
-            decrypted.push(plaintext);
-        }
-        if (seqs.length > 0) {
-            const maxSeq = Math.max(...seqs);
-            const contig = this._seqTracker.getContiguousSeq(ns);
-            if (maxSeq > contig) {
-                this._seqTracker.forceContiguousSeq(ns, maxSeq);
+            const ackSeq = this._seqTracker.getContiguousSeq(ns);
+            const contigAdvanced = ackSeq !== pageContigBefore;
+            if (contigAdvanced) {
                 await this._drainOrderedMessages(ns);
+                this._saveSeqTrackerState();
             }
+            if (messages.length > 0 && contigAdvanced && ackSeq > 0) {
+                this._clientLog.debug(`group.v2.pull scheduling auto-ack: group=${gid}, ns=${ns}, ack_seq=${ackSeq}, raw_count=${messages.length}`);
+                this._safeAsync(this.ackGroupV2(gid, ackSeq).then(() => undefined));
+            }
+            const nextAfter = Math.max(pageMaxSeq, nextAfterSeq);
+            if (messages.length === 0 || nextAfter <= nextAfterSeq || result.has_more === false)
+                break;
+            nextAfterSeq = nextAfter;
         }
-        const ackSeq = this._seqTracker.getContiguousSeq(ns);
-        if (ackSeq !== contigBefore) {
-            this._saveSeqTrackerState();
-        }
-        if (ackSeq > 0 && ackSeq !== contigBefore) {
-            this._safeAsync(this.ackGroupV2(gid, ackSeq).then(() => undefined));
+        if (pageCount >= maxPages) {
+            this._clientLog.warn(`group.v2.pull reached max_pages=${maxPages} group=${gid} after_seq=${nextAfterSeq}`);
         }
+        this._clientLog.debug(`group.v2.pull done: group=${gid}, requested_after_seq=${afterSeq}, pages=${pageCount}, decrypted=${decrypted.length}, ns=${ns}`);
         return decrypted;
     }
     /** V2 Group ack。 */
@@ -2933,13 +4069,24 @@ export class AUNClient {
         if (!gid)
             throw new ValidationError('group.ack_messages requires group_id');
         const ns = `group:${gid}`;
-        const seq = Number(upToSeq ?? this._seqTracker.getContiguousSeq(ns));
-        if (!Number.isFinite(seq) || seq <= 0)
+        let seq = Number(upToSeq ?? this._seqTracker.getContiguousSeq(ns));
+        if (!Number.isFinite(seq) || seq <= 0) {
+            this._clientLog.debug(`group.v2.ack skipped: group=${gid}, ns=${ns}, up_to_seq=${String(upToSeq ?? '')}`);
             return { acked: 0 };
-        return await this.call('group.v2.ack', { group_id: gid, up_to_seq: seq });
+        }
+        // ack clamp：永远不发送超过 maxSeenSeq 的 up_to_seq
+        const maxSeen = this._seqTracker.getMaxSeenSeq(ns);
+        if (maxSeen > 0 && seq > maxSeen) {
+            this._clientLog.warn(`ackGroupV2 clamp: group=${gid} up_to_seq=${seq} > max_seen=${maxSeen}, clamp`);
+            seq = maxSeen;
+        }
+        this._clientLog.debug(`group.v2.ack send: group=${gid}, ns=${ns}, up_to_seq=${seq}`);
+        const result = await this.call('group.v2.ack', { group_id: gid, up_to_seq: seq });
+        this._clientLog.debug(`group.v2.ack ok: group=${gid}, ns=${ns}, requested=${seq}, result=${this._debugJson(result)}`);
+        return result;
     }
-    /** 解密单条 V2 pull 消息。失败返回 null 并发布 undecryptable。 */
-    async _decryptV2Message(msg) {
+    /** 解密单条 V2 pull 消息。缺 sender IK 时先入 pending，后台补齐后重试。 */
+    async _decryptV2Message(msg, allowPending = true) {
         const session = this._v2Session;
         if (!session)
             return null;
@@ -2954,6 +4101,8 @@ export class AUNClient {
             this._clientLog.warn(`V2 decrypt: invalid envelope_json for msg seq=${String(msg.seq)}`);
             return null;
         }
+        const e2eeMeta = this._v2E2eeMeta(envelope);
+        this._observeAgentMdFromEnvelope(envelope);
         let spkId = '';
         let recipientKeySource = '';
         if (isJsonObject(envelope.recipient)) {
@@ -2977,31 +4126,73 @@ export class AUNClient {
                 }
             }
         }
-        // 根据 aad.group_id 判断使用 group SPK 还是 P2P SPK
+        // group_id 只表示群上下文；getGroupDecryptKeys 内部必须按 group SPK -> P2P device SPK -> IK fallback 查找。
         const aad = isJsonObject(envelope.aad) ? envelope.aad : {};
         const groupIdForKeys = String(aad.group_id ?? msg.group_id ?? '').trim();
+        const undecryptableEvent = groupIdForKeys ? 'group.message_undecryptable' : 'message.undecryptable';
+        this._clientLog.debug(`V2 decrypt start: seq=${String(msg.seq ?? '')}, message_id=${String(msg.message_id ?? '')}, group=${groupIdForKeys || '<p2p>'}, from=${String(msg.from_aid ?? '')}, spk_id=${spkId || '<empty>'}, key_source=${recipientKeySource || '<empty>'}, has_recipient=${String(isJsonObject(envelope.recipient))}, has_recipients=${String(Array.isArray(envelope.recipients))}`);
         let ikPriv;
         let spkPriv;
-        if (groupIdForKeys) {
-            const keys = session.getGroupDecryptKeys(groupIdForKeys, spkId);
-            ikPriv = keys.ikPriv;
-            spkPriv = keys.spkPriv ?? undefined;
+        try {
+            if (groupIdForKeys) {
+                const keys = session.getGroupDecryptKeys(groupIdForKeys, spkId);
+                ikPriv = keys.ikPriv;
+                spkPriv = keys.spkPriv ?? undefined;
+            }
+            else {
+                const keys = session.getDecryptKeys(spkId);
+                ikPriv = keys.ikPriv;
+                spkPriv = keys.spkPriv;
+            }
         }
-        else {
-            const keys = session.getDecryptKeys(spkId);
-            ikPriv = keys.ikPriv;
-            spkPriv = keys.spkPriv;
+        catch (exc) {
+            this._clientLog.warn(`V2 decrypt: SPK lookup failed seq=${String(msg.seq)} spk_id=${spkId}: ${formatCaughtError(exc)}`);
+            const event = {
+                message_id: String(msg.message_id ?? ''),
+                from: String(msg.from_aid ?? ''),
+                to: String(msg.to ?? ''),
+                seq: msg.seq,
+                timestamp: (msg.t_server ?? msg.timestamp),
+                device_id: String(msg.device_id ?? ''),
+                slot_id: String(msg.slot_id ?? ''),
+                _decrypt_error: String(formatCaughtError(exc)),
+                _decrypt_stage: 'spk_lookup',
+                _envelope_type: String(envelope.type ?? ''),
+                _suite: String(envelope.suite ?? ''),
+                _spk_id: spkId,
+            };
+            this._attachV2EnvelopeMetadata(event, e2eeMeta);
+            this._logMessageDebug('decrypt-fail', 'v2.decrypt', undecryptableEvent, event);
+            await this._dispatcher.publish(undecryptableEvent, event);
+            return null;
         }
+        this._clientLog.debug(`V2 decrypt key lookup ok: seq=${String(msg.seq ?? '')}, group=${groupIdForKeys || '<p2p>'}, ik_len=${ikPriv.byteLength}, spk_len=${spkPriv?.byteLength ?? 0}`);
         const fromAid = String(msg.from_aid ?? '');
         const senderDeviceId = String(aad.from_device ?? '');
         const senderPubDer = await this._getV2SenderPubDer(fromAid, senderDeviceId);
         if (!senderPubDer) {
-            await this._dispatcher.publish('message.undecryptable', {
+            this._clientLog.warn(`V2 decrypt: no sender IK for ${fromAid} device=${senderDeviceId}`);
+            if (allowPending) {
+                this._scheduleV2SenderIKPending({ msg, fromAid, senderDeviceId, groupId: groupIdForKeys });
+                return null;
+            }
+            const event = {
                 message_id: String(msg.message_id ?? ''),
                 from: fromAid,
+                to: String(msg.to ?? ''),
                 seq: msg.seq,
+                timestamp: (msg.t_server ?? msg.timestamp),
+                device_id: String(msg.device_id ?? ''),
+                slot_id: String(msg.slot_id ?? ''),
                 _decrypt_error: 'sender_ik_not_found',
-            });
+                _decrypt_stage: 'sender_ik',
+                _envelope_type: String(envelope.type ?? ''),
+                _suite: String(envelope.suite ?? ''),
+                _sender_device_id: String(aad.from_device ?? ''),
+            };
+            this._attachV2EnvelopeMetadata(event, e2eeMeta);
+            this._logMessageDebug('decrypt-fail', 'v2.decrypt', undecryptableEvent, event);
+            await this._dispatcher.publish(undecryptableEvent, event);
             return null;
         }
         let plaintext;
@@ -3010,16 +4201,29 @@ export class AUNClient {
         }
         catch (exc) {
             this._clientLog.warn(`V2 decrypt failed for msg seq=${String(msg.seq)}: ${formatCaughtError(exc)}`);
-            await this._dispatcher.publish('message.undecryptable', {
+            const event = {
                 message_id: String(msg.message_id ?? ''),
                 from: fromAid,
+                to: String(msg.to ?? ''),
                 seq: msg.seq,
+                timestamp: (msg.t_server ?? msg.timestamp),
+                device_id: String(msg.device_id ?? ''),
+                slot_id: String(msg.slot_id ?? ''),
                 _decrypt_error: String(formatCaughtError(exc)),
-            });
+                _decrypt_stage: 'decrypt',
+                _envelope_type: String(envelope.type ?? ''),
+                _suite: String(envelope.suite ?? ''),
+                _sender_device_id: String(aad.from_device ?? ''),
+            };
+            this._attachV2EnvelopeMetadata(event, e2eeMeta);
+            this._logMessageDebug('decrypt-fail', 'v2.decrypt', undecryptableEvent, event);
+            await this._dispatcher.publish(undecryptableEvent, event);
             return null;
         }
-        if (plaintext === null)
+        if (plaintext === null) {
+            this._clientLog.debug(`V2 decrypt returned null plaintext: seq=${String(msg.seq ?? '')}, group=${groupIdForKeys || '<p2p>'}`);
             return null;
+        }
         // 消费触发 SPK 轮换
         if (groupIdForKeys && recipientKeySource === 'group_device_prekey' && session.isLastUploadedGroupSPK(groupIdForKeys, spkId)) {
             // Group SPK 消费触发轮换
@@ -3042,8 +4246,8 @@ export class AUNClient {
                 this._clientLog.debug(`V2 SPK rotation failed (non-fatal): ${formatCaughtError(exc)}`);
             });
         }
-        const suite = String(envelope.suite ?? '');
-        return {
+        const e2ee = this._v2E2eeMeta(envelope);
+        const result = {
             message_id: String(msg.message_id ?? ''),
             from: fromAid,
             to: this._aid ?? '',
@@ -3051,13 +4255,84 @@ export class AUNClient {
             t_server: msg.t_server,
             payload: plaintext,
             encrypted: true,
-            e2ee: {
-                version: 'v2',
-                suite,
-                encryption_mode: `v2_${suite || 'unknown'}`,
-                forward_secrecy: true,
-            },
+            e2ee,
+        };
+        this._attachV2EnvelopeMetadata(result, e2ee);
+        this._logMessageDebug('decrypt-ok', 'v2.decrypt', groupIdForKeys ? 'group.message_created' : 'message.received', result);
+        return result;
+    }
+    _v2E2eeMeta(envelope) {
+        const suite = String(envelope.suite ?? '');
+        const meta = {
+            version: 'v2',
+            suite,
+            encryption_mode: `v2_${suite || 'unknown'}`,
+            forward_secrecy: true,
         };
+        const protectedHeaders = this._metadataWithoutAuth(envelope.protected_headers);
+        if (protectedHeaders && Object.keys(protectedHeaders).length > 0) {
+            meta.protected_headers = protectedHeaders;
+        }
+        const payloadType = String(envelope.payload_type ?? protectedHeaders?.payload_type ?? '').trim();
+        if (payloadType) {
+            meta.payload_type = payloadType;
+        }
+        const context = this._metadataWithoutAuth(envelope.context);
+        if (context && Object.keys(context).length > 0) {
+            meta.context = context;
+        }
+        const agentMd = this._metadataWithoutAuth(envelope.agent_md);
+        if (agentMd && Object.keys(agentMd).length > 0) {
+            meta.agent_md = agentMd;
+        }
+        return meta;
+    }
+    _attachV2EnvelopeMetadata(message, meta) {
+        const payloadType = typeof meta.payload_type === 'string' ? meta.payload_type.trim() : '';
+        if (payloadType)
+            message.payload_type = payloadType;
+        if (isJsonObject(meta.protected_headers)) {
+            message.protected_headers = { ...meta.protected_headers };
+        }
+        if (isJsonObject(meta.agent_md)) {
+            message.agent_md = { ...meta.agent_md };
+        }
+    }
+    _attachV2EnvelopeMetadataFromSource(message, source) {
+        const envelope = this._extractV2EnvelopeFromSource(source);
+        if (envelope) {
+            this._observeAgentMdFromEnvelope(envelope);
+            this._attachV2EnvelopeMetadata(message, this._v2E2eeMeta(envelope));
+        }
+    }
+    _extractV2EnvelopeFromSource(source) {
+        const candidate = source;
+        if (!isJsonObject(candidate))
+            return null;
+        if (isJsonObject(candidate.payload))
+            return candidate.payload;
+        if (typeof candidate.envelope_json === 'string' && candidate.envelope_json) {
+            try {
+                const parsed = JSON.parse(candidate.envelope_json);
+                if (isJsonObject(parsed))
+                    return parsed;
+            }
+            catch {
+                return null;
+            }
+        }
+        return null;
+    }
+    _metadataWithoutAuth(value) {
+        const candidate = value;
+        if (!isJsonObject(candidate))
+            return null;
+        const body = {};
+        for (const [key, item] of Object.entries(candidate)) {
+            if (key !== '_auth')
+                body[key] = item;
+        }
+        return body;
     }
     async _putMessageThoughtEncryptedV2(params) {
         const toAid = String(params.to ?? '').trim();
@@ -3070,7 +4345,14 @@ export class AUNClient {
         const thoughtId = String(params.thought_id ?? '').trim() || `mt-${crypto.randomUUID()}`;
         const timestamp = Number(params.timestamp ?? Date.now());
         const protectedHeaders = this._protectedHeadersFromParams(params);
+        this._logMessageDebug('thought-send-plaintext', 'message.thought.put.v2', 'message.thought.put', {
+            to: toAid,
+            thought_id: thoughtId,
+            timestamp,
+            payload,
+        }, { payloadOverride: payload });
         const attempt = async (useCache) => {
+            this._clientLog.debug(`message.thought.put attempt: to=${toAid}, thought_id=${thoughtId}, use_cache=${useCache}`);
             const context = isJsonObject(params.context) ? params.context : undefined;
             const envelope = await this._buildV2P2PEnvelope({
                 to: toAid,
@@ -3091,7 +4373,13 @@ export class AUNClient {
             if ('context' in params)
                 sendParams.context = params.context;
             this._signClientOperation('message.thought.put', sendParams);
-            return await this._transport.call('message.thought.put', sendParams);
+            this._logMessageDebug('thought-send-envelope', 'message.thought.put.v2', 'message.thought.put', sendParams, {
+                payloadOverride: envelope,
+                extra: { to: toAid, thought_id: thoughtId, use_cache: useCache },
+            });
+            const result = await this._transport.call('message.thought.put', sendParams);
+            this._clientLog.debug(`message.thought.put ok: to=${toAid}, thought_id=${thoughtId}, use_cache=${useCache}`);
+            return result;
         };
         try {
             return await attempt(true);
@@ -3116,7 +4404,14 @@ export class AUNClient {
         const thoughtId = String(params.thought_id ?? '').trim() || `gt-${crypto.randomUUID()}`;
         const timestamp = Number(params.timestamp ?? Date.now());
         const protectedHeaders = this._protectedHeadersFromParams(params);
+        this._logMessageDebug('thought-send-plaintext', 'group.thought.put.v2', 'group.thought.put', {
+            group_id: groupId,
+            thought_id: thoughtId,
+            timestamp,
+            payload,
+        }, { payloadOverride: payload });
         const attempt = async (useCache) => {
+            this._clientLog.debug(`group.thought.put attempt: group=${groupId}, thought_id=${thoughtId}, use_cache=${useCache}`);
             const context = isJsonObject(params.context) ? params.context : undefined;
             const envelope = await this._buildV2GroupEnvelope({
                 groupId,
@@ -3137,7 +4432,13 @@ export class AUNClient {
             if ('context' in params)
                 sendParams.context = params.context;
             this._signClientOperation('group.thought.put', sendParams);
-            return await this._transport.call('group.thought.put', sendParams);
+            this._logMessageDebug('thought-send-envelope', 'group.thought.put.v2', 'group.thought.put', sendParams, {
+                payloadOverride: envelope,
+                extra: { group_id: groupId, thought_id: thoughtId, use_cache: useCache },
+            });
+            const result = await this._transport.call('group.thought.put', sendParams);
+            this._clientLog.debug(`group.thought.put ok: group=${groupId}, thought_id=${thoughtId}, use_cache=${useCache}`);
+            return result;
         };
         try {
             return await attempt(true);
@@ -3159,30 +4460,57 @@ export class AUNClient {
             return null;
         const envelope = opts.envelope;
         let spkId = '';
+        let recipientKeySource = '';
         if (Array.isArray(envelope.recipients)) {
             for (const row of envelope.recipients) {
-                if (!Array.isArray(row) || row.length < 8)
+                if (!Array.isArray(row) || row.length < 6)
                     continue;
                 if (String(row[0] ?? '') === this._aid && String(row[1] ?? '') === this._deviceId) {
                     spkId = String(row[5] ?? '');
+                    recipientKeySource = String(row[3] ?? '');
                     break;
                 }
             }
         }
         else if (isJsonObject(envelope.recipient)) {
-            spkId = String(envelope.recipient.spk_id ?? '');
+            const recipient = envelope.recipient;
+            spkId = String(recipient.spk_id ?? '');
+            recipientKeySource = String(recipient.key_source ?? '');
         }
-        const { ikPriv, spkPriv } = session.getDecryptKeys(spkId);
         const aad = isJsonObject(envelope.aad) ? envelope.aad : {};
+        const groupIdForKeys = String(aad.group_id ?? envelope.group_id ?? '').trim();
         const fromAid = String(opts.fromAid || aad.from || '').trim();
         const senderDeviceId = String(aad.from_device ?? '');
+        this._clientLog.debug(`V2 thought decrypt start: from=${fromAid}, sender_device=${senderDeviceId}, group=${groupIdForKeys || '<p2p>'}, spk_id=${spkId || '<empty>'}, key_source=${recipientKeySource || '<empty>'}, type=${String(envelope.type ?? '')}`);
+        // group_id 只表示群上下文；group lookup 内部按 group SPK -> P2P device SPK -> IK fallback。
+        let ikPriv;
+        let spkPriv;
+        try {
+            if (groupIdForKeys) {
+                const keys = session.getGroupDecryptKeys(groupIdForKeys, spkId);
+                ikPriv = keys.ikPriv;
+                spkPriv = keys.spkPriv ?? undefined;
+            }
+            else {
+                const keys = session.getDecryptKeys(spkId);
+                ikPriv = keys.ikPriv;
+                spkPriv = keys.spkPriv;
+            }
+        }
+        catch (exc) {
+            this._clientLog.warn(`V2 thought decrypt: SPK lookup failed from=${fromAid}, group=${groupIdForKeys || '<p2p>'}, spk_id=${spkId || '<empty>'}: ${formatCaughtError(exc)}`);
+            return null;
+        }
         const senderPubDer = await this._getV2SenderPubDer(fromAid, senderDeviceId);
         if (!senderPubDer) {
             this._clientLog.warn(`V2 thought decrypt: no sender IK for ${fromAid} device=${senderDeviceId}`);
+            this._scheduleV2SenderIKFetch(fromAid, senderDeviceId, groupIdForKeys);
             return null;
         }
         try {
-            return decryptMessage(envelope, this._aid ?? '', this._deviceId, ikPriv, spkPriv, senderPubDer);
+            const plain = decryptMessage(envelope, this._aid ?? '', this._deviceId, ikPriv, spkPriv, senderPubDer);
+            this._clientLog.debug(`V2 thought decrypt ok: from=${fromAid}, sender_device=${senderDeviceId}, group=${groupIdForKeys || '<p2p>'}`);
+            return plain;
         }
         catch (exc) {
             this._clientLog.warn(`V2 thought decrypt failed from=${fromAid}: ${formatCaughtError(exc)}`);
@@ -3219,11 +4547,7 @@ export class AUNClient {
             });
             const sigBytes = Buffer.from(stateSignature, 'base64');
             const cacheKey = crypto.createHash('sha256')
-                .update(actorAid, 'utf-8')
-                .update(Buffer.from([0]))
-                .update(signPayload, 'utf-8')
-                .update(Buffer.from([0]))
-                .update(sigBytes)
+                .update(lengthPrefixedBytesKey(Buffer.from(actorAid, 'utf-8'), Buffer.from(signPayload, 'utf-8'), sigBytes))
                 .digest('hex');
             const now = Date.now();
             const cachedExp = this._v2SigCache.get(cacheKey);
@@ -3432,8 +4756,9 @@ export class AUNClient {
             const candidates = [];
             for (const dev of devices) {
                 const aid = String(dev.aid ?? '').trim();
+                const hasDeviceId = 'device_id' in dev;
                 const deviceId = String(dev.device_id ?? '').trim();
-                if (aid && deviceId && onlineAdminAids.has(aid)) {
+                if (aid && hasDeviceId && onlineAdminAids.has(aid)) {
                     candidates.push(`${aid}\x1f${deviceId}`);
                 }
             }
@@ -3449,7 +4774,7 @@ export class AUNClient {
                 this._clientLog.debug(`V2 auto propose leader elected: group=${groupId} leader=${leader}`);
                 return true;
             }
-            const delayMs = this._v2LeaderDelayMs(`${groupId}\x00${myKey}`);
+            const delayMs = this._v2LeaderDelayMs(lengthPrefixedTextKey(groupId, myKey));
             this._clientLog.debug(`V2 auto propose non-leader delay: group=${groupId} leader=${leader} self=${myKey} delay_ms=${delayMs}`);
             await this._sleep(delayMs);
             return true;
@@ -3719,30 +5044,46 @@ export class AUNClient {
         const pushFrom = isJsonObject(data) ? String(data.from_aid ?? '') : '';
         const pushMsgId = isJsonObject(data) ? String(data.message_id ?? '') : '';
         const envelopeJson = isJsonObject(data) ? data.envelope_json : undefined;
+        const hasPayload = !!envelopeJson;
         const ns = this._aid ? `p2p:${this._aid}` : '';
         let contigBefore = ns ? this._seqTracker.getContiguousSeq(ns) : 0;
-        this._clientLog.debug(`_onV2PushNotification: push_seq=${pushSeq || 'null'} push_from=${pushFrom} push_msg_id=${pushMsgId} has_payload=${!!envelopeJson} contiguous_seq=${contigBefore}`);
+        this._clientLog.debug(`_onV2PushNotification: push_seq=${pushSeq || 'null'} push_from=${pushFrom} push_msg_id=${pushMsgId} has_payload=${hasPayload} contiguous_seq=${contigBefore}`);
+        // ── Push 修上界：只更新 maxSeenSeq，不动 contiguousSeq ──
+        // 即使 pushSeq 是脏数据（如服务端 bug 导致的 99999），也只影响"已知上界"，
+        // 不会污染下界 contiguousSeq，更不会导致 SDK 把脏数据 ack 回服务端。
+        if (pushSeq > 0 && ns) {
+            this._seqTracker.updateMaxSeen(ns, pushSeq);
+            if (contigBefore === pushSeq) {
+                this._clientLog.debug(`_onV2PushNotification: push seq=${pushSeq} already covered by contiguous_seq=${contigBefore}, ignore duplicate push`);
+                return;
+            }
+            contigBefore = this._repairPushContiguousBound(ns, pushSeq, hasPayload, '_raw.peer.v2.message_received');
+        }
         // ── 带 payload 的 push：尝试就地解密 ──
-        if (envelopeJson && pushSeq > 0 && ns) {
+        if (hasPayload && pushSeq > 0 && ns) {
             try {
                 const decrypted = await this._decryptV2PushMessage(data);
                 if (decrypted) {
-                    // 解密成功：contiguous_seq 上界 = push_seq
-                    this._seqTracker.onMessageSeq(ns, pushSeq);
-                    if (pushSeq === contigBefore + 1) {
-                        this._seqTracker.forceContiguousSeq(ns, pushSeq);
-                    }
-                    await this._publishOrderedMessage('message.received', ns, pushSeq, decrypted);
+                    // 解密成功：把 pushSeq 加入 receivedSeqs，让 _tryAdvance 自然推进
+                    // （如果 pushSeq == contiguousSeq + 1 会自动推进到 pushSeq）
+                    const needPull = this._seqTracker.onMessageSeq(ns, pushSeq);
+                    const published = await this._publishOrderedMessage('message.received', ns, pushSeq, decrypted);
                     const newContig = this._seqTracker.getContiguousSeq(ns);
                     if (newContig !== contigBefore) {
                         this._saveSeqTrackerState();
                     }
                     if (newContig > 0 && newContig !== contigBefore) {
-                        this._transport.call('message.v2.ack', { up_to_seq: newContig })
+                        // 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 })
                             .catch(e => this._clientLog.debug(`V2 P2P push-ack failed: ${formatCaughtError(e)}`));
                     }
                     this._clientLog.debug(`_onV2PushNotification: push 带 payload 解密成功, contiguous_seq=${contigBefore}->${newContig} push_seq=${pushSeq}`);
-                    return;
+                    if (!needPull && (published || newContig >= pushSeq || pushSeq <= contigBefore)) {
+                        return;
+                    }
+                    this._clientLog.debug(`_onV2PushNotification: payload push seq=${pushSeq} 因空洞挂起，继续 pull 补齐 after_seq=${newContig}`);
                 }
             }
             catch (exc) {
@@ -3753,11 +5094,6 @@ export class AUNClient {
         // 纯通知只表示服务端已有 pushSeq 这条消息，内容还没有进入本地，不能先推进 contiguousSeq。
         // 后续 pull 必须从当前 contiguousSeq 开始，否则会跳过 pushSeq 本身。
         if (pushSeq > 0 && ns) {
-            if (contigBefore >= pushSeq) {
-                this._clientLog.warn(`_onV2PushNotification: contiguous_seq=${contigBefore} 越界（>= push_seq=${pushSeq}），强制修复为 ${pushSeq - 1}`);
-                this._seqTracker.forceContiguousSeq(ns, pushSeq - 1);
-                contigBefore = pushSeq - 1;
-            }
             this._clientLog.debug(`_onV2PushNotification: 纯通知 push_seq=${pushSeq} > contiguous_seq=${contigBefore}, 触发 pull(after_seq=${contigBefore})`);
         }
         if (this._v2PullInflight) {
@@ -3820,22 +5156,37 @@ export class AUNClient {
         await this._dispatcher.publish('group.v2.state_confirmed', data);
     }
     async _onRawGroupV2MessageCreated(data) {
-        if (!isJsonObject(data) || !this._v2Session)
+        if (!isJsonObject(data) || !this._v2Session) {
+            this._clientLog.debug(`_onRawGroupV2MessageCreated skipped: is_object=${String(isJsonObject(data))}, has_v2_session=${String(!!this._v2Session)}`);
             return;
+        }
+        this._logMessageDebug('server-push', '_raw.group.v2.message_created', 'group.message_created', data);
         const groupId = String(data.group_id ?? '').trim();
         const seq = Number(data.seq ?? 0);
-        if (!groupId || !Number.isFinite(seq) || seq <= 0)
+        if (!groupId || !Number.isFinite(seq) || seq <= 0) {
+            this._clientLog.debug(`_onRawGroupV2MessageCreated skipped: group=${groupId || '<empty>'}, seq=${String(data.seq ?? '')}`);
             return;
+        }
         const ns = `group:${groupId}`;
-        if (this._pushedSeqs.get(ns)?.has(seq))
+        // Push 修上界：先更新 maxSeenSeq
+        this._seqTracker.updateMaxSeen(ns, seq);
+        const contigBefore = this._seqTracker.getContiguousSeq(ns);
+        this._clientLog.debug(`_onRawGroupV2MessageCreated enter: group=${groupId}, seq=${seq}, contiguous=${contigBefore}, max_seen=${this._seqTracker.getMaxSeenSeq(ns)}`);
+        if (contigBefore === seq) {
+            this._clientLog.debug(`_onRawGroupV2MessageCreated duplicate push already covered: group=${groupId} seq=${seq}`);
             return;
-        const afterSeq = this._seqTracker.getContiguousSeq(ns);
+        }
+        const afterSeq = this._repairPushContiguousBound(ns, seq, false, '_raw.group.v2.message_created');
         const dedupKey = `v2_group_push:${groupId}:${afterSeq}`;
-        if (this._gapFillDone.has(dedupKey))
+        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) {
             this._clientLog.warn(`V2 group push auto-pull failed: group=${groupId} err=${formatCaughtError(exc)}`);
@@ -3869,6 +5220,11 @@ export class AUNClient {
     }
     /** 从参数中解析 Gateway URL */
     _resolveGateway(params) {
+        const gateways = this._resolveGateways(params);
+        return gateways[0];
+    }
+    /** 从参数中解析所有 Gateway URL（支持 string 或 string[]） */
+    _resolveGateways(params) {
         const topology = params.topology;
         if (isJsonObject(topology)) {
             const topo = topology;
@@ -3880,11 +5236,16 @@ export class AUNClient {
                 throw new ValidationError('relay topology is not implemented in the TypeScript SDK');
             }
         }
-        const gateway = String(params.gateway ?? '');
-        if (!gateway) {
-            throw new StateError('missing gateway in connect params');
+        const gw = params.gateway ?? params.gateways;
+        if (Array.isArray(gw)) {
+            const urls = gw.map(g => String(g ?? '')).filter(u => u.length > 0);
+            if (urls.length > 0)
+                return urls;
+        }
+        if (typeof gw === 'string' && gw) {
+            return [gw];
         }
-        return gateway;
+        throw new StateError('missing gateway in connect params');
     }
     /** 连接后同步身份信息 */
     _syncIdentityAfterConnect(accessToken) {
@@ -4138,6 +5499,16 @@ export class AUNClient {
         };
         scheduleNext(0);
     }
+    _normalizeOutboundMessagePayload(params, method = '') {
+        if (!Object.prototype.hasOwnProperty.call(params, 'payload') && Object.prototype.hasOwnProperty.call(params, 'content')) {
+            params.payload = params.content;
+            delete params.content;
+        }
+        const payload = params.payload;
+        if (isJsonObject(payload) && !Object.prototype.hasOwnProperty.call(payload, 'type') && typeof payload.text === 'string') {
+            params.payload = { type: 'text', ...payload };
+        }
+    }
     _validateMessageRecipient(toAid) {
         if (isGroupServiceAid(toAid)) {
             throw new ValidationError('message.send receiver cannot be group.{issuer}; use group.send instead');