@agentunion/fastaun-browser 0.5.4 → 0.5.8

package/dist/client/v2-e2ee.js

@@ -1,15 +1,133 @@
 import { importCertPublicKeyEcdsa } from '../crypto.js';
 import { E2EEError, StateError, ValidationError } from '../errors.js';
-import { normalizeGroupId } from '../group-id.js';
 import { decryptMessage, encryptGroupMessage, encryptP2PMessage, } from '../v2/e2ee/index.js';
 import { V2Session, V2KeyStore } from '../v2/session/index.js';
 import { ConnectionState, isJsonObject } from '../types.js';
+import { normalizeGroupMentionMode } from './mention-mode.js';
 const V2_BOOTSTRAP_TTL_MS = 60 * 60 * 1000;
 const V2_RETRYABLE_CODES = new Set([-33011, -33012, -33050, -33052, -33054]);
 const V2_GROUP_STALE_BOOTSTRAP_CODE = -33054;
+const V2_PULL_DEFAULT_PAGE_LIMIT = 50;
+const V2_PULL_MAX_PAGE_LIMIT = 50;
+const V2_SENDER_IK_SYNC_FETCH_TIMEOUT_MS = 3_000;
 const V2_SESSION_INIT_RETRY_LIMIT = 12;
 const V2_SESSION_INIT_RETRY_BASE_MS = 1000;
 const V2_SESSION_INIT_RETRY_MAX_MS = 5000;
+function strictWindowSeq(value, field, positive = false) {
+    if (!Number.isSafeInteger(value))
+        throw new ValidationError(`${field} must be an integer`);
+    const minimum = positive ? 1 : 0;
+    if (value < minimum)
+        throw new ValidationError(`${field} must be >= ${minimum}`);
+    return value;
+}
+function safeNonNegativeSeq(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : null;
+}
+function strictWindowLimit(value) {
+    const limit = strictWindowSeq(value, 'limit', true);
+    if (limit > V2_PULL_MAX_PAGE_LIMIT)
+        throw new ValidationError(`limit must be <= ${V2_PULL_MAX_PAGE_LIMIT}`);
+    return limit;
+}
+function deduplicateWindowMessages(value, lowerSeq, upperSeq, boundary) {
+    if (!Array.isArray(value))
+        throw new ValidationError('messages must be an array');
+    const bySeq = new Map();
+    for (const raw of value) {
+        if (!isJsonObject(raw))
+            throw new ValidationError('messages entries must be objects');
+        const row = raw;
+        const seq = strictWindowSeq(row.seq, 'messages[].seq', true);
+        if (seq < lowerSeq || seq > upperSeq)
+            throw new ValidationError(`messages[].seq is outside ${boundary}`);
+        const previous = bySeq.get(seq);
+        if (previous && JSON.stringify(previous) !== JSON.stringify(row))
+            throw new ValidationError('messages contains conflicting duplicate seq');
+        bySeq.set(seq, row);
+    }
+    return [...bySeq.entries()].sort(([a], [b]) => a - b).map(([, row]) => row);
+}
+function deduplicateForwardPageMessages(value, afterSeq) {
+    if (!Array.isArray(value))
+        return [];
+    const bySeq = new Map();
+    for (const raw of value) {
+        if (!isJsonObject(raw))
+            continue;
+        const row = raw;
+        const seq = safeNonNegativeSeq(row.seq);
+        if (seq === null || seq <= 0 || seq <= afterSeq || bySeq.has(seq))
+            continue;
+        bySeq.set(seq, row);
+    }
+    return [...bySeq.entries()].sort(([a], [b]) => a - b).map(([, row]) => row);
+}
+function shouldContinueForwardPage({ rawCount, nextAfterSeq, nextAfter, limit, hasMoreField, hasMore, serverHead, pendingAckSeq, }) {
+    // 无新 seq 或游标未前进时必须停止，避免错误元数据造成循环。
+    if (rawCount <= 0 || nextAfter <= nextAfterSeq)
+        return false;
+    if (hasMore || serverHead > nextAfter || pendingAckSeq > 0)
+        return true;
+    // 仅旧服务缺失 has_more 时，以满页保留兼容续拉。
+    return !hasMoreField && limit > 0 && rawCount >= limit;
+}
+function validateTailPage(result, afterSeq, pageLimit) {
+    if (!isJsonObject(result))
+        throw new ValidationError('tail response must be an object');
+    const row = result;
+    if (row.window_mode !== 'tail')
+        throw new ValidationError('tail response window_mode must equal tail');
+    strictWindowSeq(afterSeq, 'after_seq');
+    const windowStart = strictWindowSeq(row.window_start_seq, 'window_start_seq');
+    const head = strictWindowSeq(row.head_seq, 'head_seq');
+    const covered = strictWindowSeq(row.covered_through_seq, 'covered_through_seq');
+    if (windowStart > head || covered !== head || head - windowStart + 1 > pageLimit) {
+        throw new ValidationError('tail response proof is invalid');
+    }
+    let lowerSeq = windowStart;
+    if (head <= afterSeq) {
+        if (windowStart !== head)
+            throw new ValidationError('empty tail window must end at head_seq');
+        lowerSeq = head + 1;
+    }
+    else {
+        if (windowStart < afterSeq + 1)
+            throw new ValidationError('tail window_start_seq is below after_seq');
+        lowerSeq = Math.max(windowStart, afterSeq + 1);
+    }
+    const messages = deduplicateWindowMessages(row.messages, lowerSeq, head, 'the proven tail window');
+    if (head <= afterSeq && messages.length > 0)
+        throw new ValidationError('tail response must not include messages at or below after_seq');
+    return { windowStart, head, messages };
+}
+function validateHistoryPage(result, beforeSeq) {
+    if (!isJsonObject(result))
+        throw new ValidationError('history response must be an object');
+    const row = result;
+    const rawStart = row.window_start_seq;
+    const rawNext = row.next_before_seq;
+    if ((rawStart === undefined) !== (rawNext === undefined))
+        throw new ValidationError('history pagination boundaries must both be present or absent');
+    let lowerSeq = 1;
+    let windowStart;
+    if (rawStart !== undefined) {
+        windowStart = strictWindowSeq(rawStart, 'window_start_seq', true);
+        const nextBefore = strictWindowSeq(rawNext, 'next_before_seq', true);
+        if (windowStart !== nextBefore || windowStart >= beforeSeq)
+            throw new ValidationError('history boundary is invalid');
+        lowerSeq = windowStart;
+    }
+    const messages = deduplicateWindowMessages(row.messages, lowerSeq, beforeSeq - 1, 'the history page');
+    if (messages.length > 0 && (windowStart === undefined || Number(messages[0].seq) !== windowStart)) {
+        throw new ValidationError('history messages require exact pagination boundaries');
+    }
+    if (messages.length === 0 && windowStart !== undefined)
+        throw new ValidationError('empty history page must not include pagination boundaries');
+    if (typeof row.has_older !== 'boolean' || (messages.length === 0 && row.has_older))
+        throw new ValidationError('has_older is invalid');
+    return messages;
+}
 const MEMBERSHIP_ACTIONS = new Set([
     'member_added',
     'member_left',
@@ -205,6 +323,12 @@ function v2WrapCapabilities() {
         per_device_wrap: true,
     };
 }
+function withExplicitGroupAid(params, groupAid) {
+    const aid = String(groupAid ?? '').trim();
+    if (aid)
+        params.group_aid = aid;
+    return params;
+}
 function applyV2WrapPolicyToTargets(targets, policy) {
     if (!policy)
         return targets;
@@ -231,6 +355,10 @@ function applyV2WrapPolicyToTargets(targets, policy) {
 export class V2E2EECoordinator {
     runtime;
     targetSetCache = new Map();
+    senderIKSyncFetches = new Map();
+    /** 服务端 ACK cursor 高于本地 A 时，延迟到下一次 Forward Pull 再恢复。 */
+    pendingForwardCursors = new Map();
+    pendingForwardAcks = new Map();
     v2SessionInitRetryTimer = null;
     v2SessionInitRetryBackgroundSync = false;
     v2SessionInitRetryIdentityKey = null;
@@ -240,6 +368,51 @@ export class V2E2EECoordinator {
     get client() {
         return this.runtime.client;
     }
+    resetForwardCursorState() {
+        this.pendingForwardCursors.clear();
+        this.pendingForwardAcks.clear();
+    }
+    pendingForwardCursor(ns, localAck) {
+        if (!ns)
+            return 0;
+        const pending = this.pendingForwardCursors.get(ns) ?? 0;
+        if (pending <= localAck) {
+            if (pending > 0)
+                this.pendingForwardCursors.delete(ns);
+            return 0;
+        }
+        return pending;
+    }
+    recordForwardCursor(ns, cursor, localAck) {
+        if (!ns || !Number.isSafeInteger(cursor) || cursor <= localAck)
+            return;
+        this.pendingForwardCursors.set(ns, Math.max(this.pendingForwardCursors.get(ns) ?? 0, cursor));
+    }
+    clearForwardCursor(ns, committedAck) {
+        const pending = this.pendingForwardCursors.get(ns) ?? 0;
+        if (pending > 0 && committedAck >= pending)
+            this.pendingForwardCursors.delete(ns);
+    }
+    pendingForwardAck(ns, localAck) {
+        if (!ns)
+            return 0;
+        const pending = this.pendingForwardAcks.get(ns) ?? 0;
+        if (!Number.isSafeInteger(pending) || pending <= 0 || localAck <= 0 || pending > localAck) {
+            this.pendingForwardAcks.delete(ns);
+            return 0;
+        }
+        return pending;
+    }
+    recordForwardAck(ns, ackSeq) {
+        if (!ns || !Number.isSafeInteger(ackSeq) || ackSeq <= 0)
+            return;
+        this.pendingForwardAcks.set(ns, Math.max(this.pendingForwardAcks.get(ns) ?? 0, ackSeq));
+    }
+    clearForwardAck(ns, confirmedSeq) {
+        const pending = this.pendingForwardAcks.get(ns) ?? 0;
+        if (pending > 0 && confirmedSeq >= pending)
+            this.pendingForwardAcks.delete(ns);
+    }
     get bootstrapCache() {
         const client = this.client;
         if (!(client._v2BootstrapCache instanceof Map)) {
@@ -253,6 +426,18 @@ export class V2E2EECoordinator {
     setBootstrapCacheEntry(key, entry) {
         this.bootstrapCache.set(key, entry);
     }
+    cacheBundledSelfDevices(bootstrap, wrapPolicy) {
+        const client = this.client;
+        if (!client._aid || !Object.prototype.hasOwnProperty.call(bootstrap, 'self_devices'))
+            return;
+        const selfDevices = (Array.isArray(bootstrap.self_devices) ? bootstrap.self_devices : []);
+        this.setBootstrapCacheEntry(client._aid, {
+            devices: selfDevices,
+            auditRecipients: [],
+            cachedAt: Date.now(),
+            wrapPolicy,
+        });
+    }
     deleteBootstrapCacheEntry(key) {
         this.bootstrapCache.delete(key);
         this.targetSetCache.delete(key);
@@ -555,6 +740,84 @@ export class V2E2EECoordinator {
     pendingSenderIKFetchKey(fromAid, senderDeviceId, groupId) {
         return `${fromAid}#${senderDeviceId}#${groupId || ''}`;
     }
+    async fetchSenderIKOnce(fromAid, senderDeviceId, groupId, certFingerprint = '') {
+        const client = this.client;
+        const peerAid = String(fromAid ?? '').trim();
+        const deviceId = String(senderDeviceId ?? '').trim();
+        const gid = String(groupId ?? '').trim();
+        const fingerprint = String(certFingerprint ?? '').trim().toLowerCase();
+        if (!peerAid)
+            return null;
+        const fetchKey = [peerAid, deviceId, gid, fingerprint].join('#');
+        const existing = this.senderIKSyncFetches.get(fetchKey);
+        if (existing)
+            return await existing;
+        const task = (async () => {
+            const started = Date.now();
+            let timer;
+            const timedOut = Symbol('sender-ik-timeout');
+            const fetch = async () => {
+                try {
+                    const bootstrap = await client.call('message.v2.bootstrap', {
+                        peer_aid: peerAid,
+                        e2ee_wrap_capabilities: v2WrapCapabilities(),
+                    });
+                    const peers = (Array.isArray(bootstrap?.peer_devices) ? bootstrap.peer_devices : []);
+                    for (const dev of peers)
+                        client._cacheV2PeerIKFromDevice(dev, peerAid);
+                }
+                catch (exc) {
+                    client._clientLog.warn(`V2 sender IK 同步 bootstrap 失败: peer=${peerAid} device=${deviceId || '-'} err=${String(formatE2EEError(exc))}`);
+                }
+                let senderPubDer = await this.getV2SenderPubDer(peerAid, deviceId, fingerprint);
+                if (senderPubDer || !gid)
+                    return senderPubDer;
+                try {
+                    const bootstrap = await client.call('group.v2.bootstrap', {
+                        group_id: gid,
+                        e2ee_wrap_capabilities: v2WrapCapabilities(),
+                    });
+                    const devices = (Array.isArray(bootstrap?.devices) ? bootstrap.devices : []);
+                    const audit = (Array.isArray(bootstrap?.audit_recipients) ? bootstrap.audit_recipients : []);
+                    for (const dev of devices)
+                        client._cacheV2PeerIKFromDevice(dev);
+                    for (const dev of audit)
+                        client._cacheV2PeerIKFromDevice(dev);
+                }
+                catch (exc) {
+                    client._clientLog.warn(`V2 sender IK 同步 group bootstrap 失败: group=${gid} peer=${peerAid} err=${String(formatE2EEError(exc))}`);
+                }
+                senderPubDer = await this.getV2SenderPubDer(peerAid, deviceId, fingerprint);
+                return senderPubDer;
+            };
+            try {
+                const result = await Promise.race([
+                    fetch(),
+                    new Promise((resolve) => {
+                        timer = setTimeout(() => resolve(timedOut), V2_SENDER_IK_SYNC_FETCH_TIMEOUT_MS);
+                    }),
+                ]);
+                if (result === timedOut) {
+                    client._clientLog.warn(`V2 sender IK 同步获取超时: peer=${peerAid} device=${deviceId || '-'} group=${gid || '<p2p>'} timeout_ms=${V2_SENDER_IK_SYNC_FETCH_TIMEOUT_MS}`);
+                    return null;
+                }
+                return result;
+            }
+            finally {
+                if (timer !== undefined)
+                    clearTimeout(timer);
+                client._clientLog.debug(`V2 sender IK 同步获取完成: peer=${peerAid} device=${deviceId || '-'} group=${gid || '<p2p>'} elapsed_ms=${Date.now() - started}`);
+            }
+        })();
+        this.senderIKSyncFetches.set(fetchKey, task);
+        try {
+            return await task;
+        }
+        finally {
+            if (this.senderIKSyncFetches.get(fetchKey) === task)
+                this.senderIKSyncFetches.delete(fetchKey);
+        }
+    }
     scheduleSenderIKPending(args) {
         const client = this.client;
         const fromAid = String(args.fromAid ?? '').trim();
@@ -571,7 +834,8 @@ export class V2E2EECoordinator {
             createdAt: Date.now(),
         });
         client._clientLog.debug(`V2 decrypt pending sender IK: key=${messageKey} from=${fromAid} device=${senderDeviceId || '-'} group=${groupId || '<p2p>'} pending=${client._v2SenderIKPending.size}`);
-        this.scheduleSenderIKFetch(fromAid, senderDeviceId, groupId);
+        if (args.startFetch !== false)
+            this.scheduleSenderIKFetch(fromAid, senderDeviceId, groupId);
     }
     scheduleSenderIKFetch(fromAid, senderDeviceId, groupId) {
         const client = this.client;
@@ -622,26 +886,33 @@ export class V2E2EECoordinator {
             const pendingItems = [...client._v2SenderIKPending.entries()].filter(([, entry]) => entry.fromAid === fromAid && entry.senderDeviceId === senderDeviceId && entry.groupId === groupId);
             for (const [key, entry] of pendingItems) {
                 let plaintext = null;
+                const retryStatus = {};
                 try {
-                    plaintext = await client._decryptV2Message(entry.msg, false);
+                    plaintext = await client._decryptV2Message(entry.msg, false, true, true, true, retryStatus);
                 }
                 catch (exc) {
                     client._clientLog.warn(`V2 sender IK pending retry raised: key=${key} err=${String(formatE2EEError(exc))}`);
+                    client._v2SenderIKPending.delete(key);
+                    continue;
                 }
-                client._v2SenderIKPending.delete(key);
                 if (plaintext === null) {
-                    client._clientLog.debug(`V2 sender IK pending retry failed: key=${key}`);
-                    client.emit('message.undecryptable', {
-                        from: entry.fromAid,
-                        sender_device_id: entry.senderDeviceId,
-                        group_id: entry.groupId || undefined,
-                        seq: Number(entry.msg.seq ?? 0),
-                        reason: 'sender_ik_retry_failed',
-                    });
+                    if (retryStatus.deferred) {
+                        client._clientLog.warn(`V2 pending retry still missing key material: key=${key}`);
+                        continue;
+                    }
+                    client._clientLog.warn(`V2 sender IK pending retry still undecryptable: key=${key}`);
+                    const isGroup = Boolean(entry.groupId);
+                    const eventName = isGroup ? 'group.message_undecryptable' : 'message.undecryptable';
+                    const safeEvent = this.safeUndecryptablePushEvent(entry.msg, isGroup);
+                    safeEvent._decrypt_error = 'sender IK pending retry failed';
+                    safeEvent._decrypt_stage = 'sender_ik_pending_retry';
+                    await client._publishAppEvent(eventName, safeEvent, 'pending_retry');
                     continue;
                 }
+                client._v2SenderIKPending.delete(key);
                 const seq = Number(entry.msg.seq ?? 0);
                 if (entry.groupId) {
+                    plaintext = normalizeGroupMentionMode(plaintext, entry.msg, entry.msg.envelope_json);
                     plaintext.group_id = entry.groupId;
                     await client._publishPulledMessage('group.message_created', `group:${entry.groupId}`, seq, plaintext);
                 }
@@ -709,19 +980,211 @@ export class V2E2EECoordinator {
             throw exc;
         }
     }
+    historyDecryptFailure(msg, reason) {
+        return {
+            message_id: String(msg.message_id ?? ''),
+            seq: Number(msg.seq ?? 0),
+            encrypted: true,
+            history_error: { code: 'decrypt_failed', message: reason },
+        };
+    }
+    async decodeP2PWindowMessage(msg, publish, history, source, orderedPublish = false) {
+        const client = this.client;
+        const seq = strictWindowSeq(msg.seq, 'messages[].seq', true);
+        let plaintext = null;
+        if (String(msg.version ?? '') === 'v1') {
+            const legacy = isJsonObject(msg.legacy_v1)
+                ? msg.legacy_v1 : {};
+            const payload = legacy.payload;
+            const payloadType = isJsonObject(payload)
+                ? String(payload.type ?? '').trim() : '';
+            if (payload !== undefined && payload !== null && !['e2ee.encrypted', 'e2ee.group_encrypted'].includes(payloadType)) {
+                plaintext = {
+                    message_id: String(msg.message_id ?? ''), from: String(msg.from_aid ?? ''),
+                    to: String(legacy.to ?? client._aid ?? ''), seq, type: String(msg.type ?? ''),
+                    timestamp: msg.t_server, payload: payload, encrypted: false,
+                };
+                attachGatewayProximity(plaintext, msg);
+            }
+        }
+        else {
+            plaintext = source === 'inline_push'
+                ? await client._decryptV2Message(msg, false, false, false, false)
+                : await client._decryptV2Message(msg, false);
+        }
+        if (!plaintext) {
+            if (history)
+                return this.historyDecryptFailure(msg, 'message could not be decrypted');
+            client._clientLog.warn(`P2P Tail 单条消息解密失败，连续性证明仍保留: seq=${seq}`);
+            return null;
+        }
+        if (publish) {
+            const event = client._delivery.p2pAppEventForMessage(plaintext);
+            if (orderedPublish) {
+                await client._delivery.publishOrderedMessage(event.event, client._aid ? `p2p:${client._aid}` : '', seq, event.payload);
+            }
+            else {
+                await client._publishAppEvent(event.event, event.payload, source);
+            }
+        }
+        return plaintext;
+    }
+    async decodeGroupWindowMessage(msg, groupId, groupAid, publish, history, source, orderedPublish = false) {
+        const client = this.client;
+        const seq = strictWindowSeq(msg.seq, 'messages[].seq', true);
+        let plaintext = null;
+        if (String(msg.version ?? '') === 'v1') {
+            const payload = msg.payload;
+            if (payload === undefined || payload === null) {
+                if (history)
+                    return this.historyDecryptFailure(msg, 'legacy payload is missing');
+                client._clientLog.warn(`Group Tail 缺少 payload 的 V1 行已跳过，连续性证明仍保留: group=${groupId}, seq=${seq}`);
+                return null;
+            }
+            if (isJsonObject(payload)
+                && ['e2ee.encrypted', 'e2ee.group_encrypted'].includes(String(payload.type ?? ''))) {
+                if (history)
+                    return this.historyDecryptFailure(msg, 'unsupported legacy encrypted envelope');
+                client._clientLog.warn(`Group Tail 不支持的旧加密消息已跳过，连续性证明仍保留: group=${groupId}, seq=${seq}`);
+                return null;
+            }
+            plaintext = {
+                message_id: String(msg.message_id ?? ''), from: String(msg.from_aid ?? ''),
+                group_id: groupId, group_aid: groupAid, seq, type: String(msg.type ?? ''),
+                timestamp: msg.t_server, payload: payload, encrypted: false,
+            };
+            plaintext = normalizeGroupMentionMode(plaintext, msg, msg.envelope_json);
+            attachGatewayProximity(plaintext, msg);
+        }
+        else {
+            plaintext = source === 'inline_push'
+                ? await client._decryptV2Message(msg, false, false, false, false)
+                : await client._decryptV2Message(msg, false);
+            if (plaintext) {
+                // Inline Head 已绑定群身份；解密结果若声称群身份，必须与其严格一致。
+                if (source === 'inline_push' && Object.prototype.hasOwnProperty.call(plaintext, 'group_id')
+                    && (typeof plaintext.group_id !== 'string' || !plaintext.group_id || plaintext.group_id !== groupId)) {
+                    return null;
+                }
+                plaintext.group_id = groupId;
+                plaintext.group_aid = groupAid;
+                plaintext = normalizeGroupMentionMode(plaintext, msg, msg.envelope_json);
+            }
+        }
+        if (!plaintext) {
+            if (history)
+                return this.historyDecryptFailure(msg, 'message could not be decrypted');
+            client._clientLog.warn(`Group Tail 单条消息解密失败，连续性证明仍保留: group=${groupId}, seq=${seq}`);
+            return null;
+        }
+        if (publish) {
+            if (orderedPublish) {
+                await client._delivery.publishOrderedMessage('group.message_created', `group:${groupId}`, seq, plaintext);
+            }
+            else {
+                await client._publishAppEvent('group.message_created', plaintext, source);
+            }
+        }
+        return plaintext;
+    }
+    async decodeInlineP2PMessage(msg) {
+        return await this.decodeP2PWindowMessage(msg, false, false, 'inline_push');
+    }
+    async decodeInlineGroupMessage(msg, groupId, groupAid) {
+        return await this.decodeGroupWindowMessage(msg, groupId, groupAid, false, false, 'inline_push');
+    }
+    async applyTailFloor(ns, floor) {
+        const client = this.client;
+        if (!ns || floor <= 0 || client._seqTracker.getContiguousSeq(ns) >= floor)
+            return;
+        client._seqTracker.forceContiguousSeq(ns, floor);
+        client._persistSeq(ns);
+        await client._saveSeqTrackerState?.();
+    }
+    async pullV2TailInternal(params, deferPublish = false) {
+        const client = this.client;
+        if (params.window_mode !== 'tail')
+            throw new ValidationError('window_mode must equal tail');
+        if ('ack_up_to_seq' in params || params.force === true)
+            throw new ValidationError('Tail does not accept ack_up_to_seq or force');
+        const afterSeq = strictWindowSeq(params.after_seq ?? 0, 'after_seq');
+        const limit = strictWindowLimit(params.limit ?? V2_PULL_DEFAULT_PAGE_LIMIT);
+        const ns = client._aid ? `p2p:${client._aid}` : '';
+        const result = await client._callRawV2Rpc('message.v2.pull', { window_mode: 'tail', after_seq: afterSeq, limit, _rpc_foreground: true });
+        const floor = Number(result.retention_floor_seq ?? 0);
+        const previous = ns ? client._seqTracker.getSyncState(ns) : null;
+        await this.applyTailFloor(ns, Number.isSafeInteger(floor) ? floor : 0);
+        const page = validateTailPage(result, afterSeq, limit);
+        if (ns) {
+            client._seqTracker.commitTailWindow(ns, {
+                windowStartSeq: page.windowStart, headSeq: page.head, coveredThroughSeq: page.head, pageLimit: limit,
+            });
+            client._persistSeq(ns);
+            await client._saveSeqTrackerState?.();
+        }
+        const decoded = [];
+        for (const msg of page.messages) {
+            const plaintext = await this.decodeP2PWindowMessage(msg, true, false, 'tail', deferPublish);
+            if (plaintext)
+                decoded.push(plaintext);
+        }
+        const ack = ns ? client._seqTracker.getContiguousSeq(ns) : 0;
+        if (previous && ack > previous.ack)
+            await this.ackV2(ack);
+        return { ...result, messages: decoded, raw_count: page.messages.length };
+    }
+    async historyV2Internal(params) {
+        const beforeSeq = strictWindowSeq(params.before_seq, 'before_seq', true);
+        const limit = strictWindowLimit(params.limit ?? V2_PULL_DEFAULT_PAGE_LIMIT);
+        const result = await this.client._callRawV2Rpc('message.history', { before_seq: beforeSeq, limit, _rpc_foreground: true });
+        const messages = validateHistoryPage(result, beforeSeq);
+        const decoded = [];
+        for (const msg of messages) {
+            const plaintext = await this.decodeP2PWindowMessage(msg, false, true, 'history');
+            if (plaintext)
+                decoded.push(plaintext);
+        }
+        return { ...result, messages: decoded };
+    }
     async pullV2(afterSeq = 0, limit = 50, opts) {
         const client = this.client;
         await client._ensureV2SessionReady('message.pull');
         const ns = client._aid ? `p2p:${client._aid}` : '';
+        if (opts?.windowMode === 'tail') {
+            if (!opts.gateLocked) {
+                const key = `${ns}|tail|after=${afterSeq}|limit=${limit}`;
+                return await client._runPullSerialized(key, () => this.pullV2(afterSeq, limit, {
+                    ...(opts ?? {}),
+                    gateLocked: true,
+                }), false);
+            }
+            const result = await this.pullV2TailInternal({ window_mode: 'tail', after_seq: afterSeq, limit });
+            return Array.isArray(result.messages) ? result.messages : [];
+        }
+        if (ns && !opts?.gateLocked) {
+            const key = `${ns}|forward|after=${afterSeq}|force=${String(Boolean(opts?.force))}|limit=${limit}`;
+            return await client._runPullSerialized(key, () => this.pullV2(afterSeq, limit, {
+                ...(opts ?? {}),
+                gateLocked: true,
+            }), true);
+        }
         const decrypted = [];
         let nextAfterSeq = opts?.force ? afterSeq : (afterSeq || (ns ? client._seqTracker.getContiguousSeq(ns) : 0));
+        let pullGateKey = ns
+            ? `${ns}|forward|after=${afterSeq}|force=${String(Boolean(opts?.force))}|limit=${limit}`
+            : '';
+        const deferredServerCursor = ns ? this.pendingForwardCursor(ns, client._seqTracker.getContiguousSeq(ns)) : 0;
+        const deferredForwardAck = ns ? this.pendingForwardAck(ns, client._seqTracker.getContiguousSeq(ns)) : 0;
         let pageCount = 0;
         let lastAutoAckSeq = 0;
-        let pendingAckSeq = 0;
-        const maxPages = 100;
+        let pendingAckSeq = deferredForwardAck;
+        const maxPages = Math.max(1, Math.min(100, Math.trunc(Number(opts?.maxPages ?? 100) || 100)));
         while (pageCount < maxPages) {
             pageCount += 1;
             const ackUpToSeq = pendingAckSeq;
+            const pendingInlineGeneration = ackUpToSeq > 0
+                ? client._delivery?.pendingP2PInlineAckGeneration?.(ns) ?? null
+                : null;
             const result = await client._callRawV2Rpc('message.v2.pull', {
                 after_seq: nextAfterSeq,
                 limit,
@@ -729,23 +1192,38 @@ export class V2E2EECoordinator {
                 ...(ackUpToSeq > 0 ? { ack_up_to_seq: ackUpToSeq } : {}),
             });
             if (ackUpToSeq > 0) {
-                pendingAckSeq = 0;
-                lastAutoAckSeq = Math.max(lastAutoAckSeq, ackUpToSeq);
+                const actualAckSeq = client._delivery?.resolveP2PPullAckSeq?.(result, ackUpToSeq) ?? 0;
+                if (actualAckSeq >= ackUpToSeq) {
+                    if (pendingInlineGeneration !== null) {
+                        client._delivery?.completePendingP2PInlineAckUpTo?.(ns, actualAckSeq, pendingInlineGeneration);
+                    }
+                    pendingAckSeq = 0;
+                    lastAutoAckSeq = Math.max(lastAutoAckSeq, ackUpToSeq);
+                    this.clearForwardAck(ns, ackUpToSeq);
+                }
+                else {
+                    client._clientLog.warn(`message.v2.pull piggyback ACK below target: requested=${ackUpToSeq}, actual=${actualAckSeq}; fallback terminal ACK`);
+                    await this.confirmForwardP2PAck(ackUpToSeq, pendingInlineGeneration ?? undefined);
+                    pendingAckSeq = 0;
+                    lastAutoAckSeq = Math.max(lastAutoAckSeq, ackUpToSeq);
+                }
             }
             const pageMessages = (Array.isArray(result?.messages) ? result.messages : []);
-            const messages = pageMessages.filter((msg) => {
-                const seq = Number(msg.seq ?? 0);
-                return Number.isFinite(seq) && seq > nextAfterSeq;
-            }).sort((a, b) => Number(a.seq ?? 0) - Number(b.seq ?? 0));
-            client._clientLog.debug(`message.v2.pull page response: page=${pageCount}, raw_count=${messages.length}, stale_count=${Math.max(0, pageMessages.length - messages.length)}, has_more=${String(result.has_more ?? '')}, server_ack_seq=${String(result.server_ack_seq ?? '')}`);
+            const messages = deduplicateForwardPageMessages(pageMessages, nextAfterSeq);
+            const cursor = isJsonObject(result.cursor) ? result.cursor : null;
+            const hasMoreField = Object.prototype.hasOwnProperty.call(result, 'has_more');
+            const hasMore = result.has_more === true;
+            const serverHead = safeNonNegativeSeq(cursor?.latest_seq) ?? 0;
+            client._clientLog.debug(`message.v2.pull page response: page=${pageCount}, raw_count=${messages.length}, stale_count=${Math.max(0, pageMessages.length - messages.length)}, has_more=${String(result.has_more ?? '')}, server_head=${serverHead}, server_ack_seq=${String(result.server_ack_seq ?? '')}`);
             const seqs = messages
                 .map((msg) => Number(msg.seq ?? 0))
                 .filter((seq) => Number.isFinite(seq) && seq > 0);
             const pageContigBefore = ns ? client._seqTracker.getContiguousSeq(ns) : 0;
+            const pageTrackerSnapshot = ns && typeof client._seqTracker.snapshotNamespace === 'function'
+                ? client._seqTracker.snapshotNamespace(ns)
+                : null;
             const pageMaxSeq = seqs.length > 0 ? Math.max(...seqs) : nextAfterSeq;
-            if (ns && seqs.length > 0) {
-                client._seqTracker.forceContiguousSeq(ns, pageMaxSeq);
-            }
+            const deferredKeyFetches = new Map();
             for (const msg of messages) {
                 const seq = Number(msg.seq ?? 0);
                 if (!Number.isFinite(seq) || seq <= 0)
@@ -772,7 +1250,7 @@ export class V2E2EECoordinator {
                         attachGatewayProximity(v1Msg, msg);
                         const appEvent = client._delivery.p2pAppEventForMessage(v1Msg);
                         if (ns)
-                            await client._publishPulledMessage(appEvent.event, ns, seq, appEvent.payload);
+                            await client._publishPulledMessage(appEvent.event, ns, seq, appEvent.payload, false);
                         else
                             await client._publishAppEvent(appEvent.event, appEvent.payload);
                         decrypted.push(v1Msg);
@@ -790,11 +1268,20 @@ export class V2E2EECoordinator {
                 if (msgSpkId && client._v2Session && !client._v2Session.isCurrentSPK(msgSpkId)) {
                     client._v2Session.trackOldSPKMaxSeq(msgSpkId, seq);
                 }
-                const plaintext = await client._decryptV2Message(msg);
+                const deferStatus = {};
+                const plaintext = await client._decryptV2Message(msg, true, true, true, true, deferStatus, true);
+                if (deferStatus.deferred && deferStatus.fromAid) {
+                    const key = `${deferStatus.fromAid}\u0000${deferStatus.senderDeviceId ?? ''}\u0000${deferStatus.groupId ?? ''}`;
+                    deferredKeyFetches.set(key, {
+                        fromAid: deferStatus.fromAid,
+                        senderDeviceId: deferStatus.senderDeviceId ?? '',
+                        groupId: deferStatus.groupId ?? '',
+                    });
+                }
                 if (plaintext === null)
                     continue;
                 if (ns) {
-                    await client._publishPulledMessage('message.received', ns, seq, plaintext);
+                    await client._publishPulledMessage('message.received', ns, seq, plaintext, false);
                     decrypted.push(plaintext);
                 }
                 else {
@@ -803,26 +1290,60 @@ export class V2E2EECoordinator {
                 }
             }
             const hasServerAckSeq = Object.prototype.hasOwnProperty.call(result, 'server_ack_seq');
-            const serverAckSeq = Number(result.server_ack_seq ?? 0);
-            if (ns && Number.isFinite(serverAckSeq) && serverAckSeq > 0) {
-                const contig = client._seqTracker.getContiguousSeq(ns);
-                if (contig < serverAckSeq) {
-                    client._clientLog.info(`message.v2.pull retention-floor advance: ns=${ns} contiguous=${contig} -> server_ack_seq=${serverAckSeq}`);
-                    client._seqTracker.forceContiguousSeq(ns, serverAckSeq);
-                }
-            }
+            const parsedServerAckSeq = hasServerAckSeq ? safeNonNegativeSeq(result.server_ack_seq) : null;
+            const serverAckSeq = parsedServerAckSeq ?? 0;
+            const retentionFloor = Math.max(0, Number(result.retention_floor_seq ?? 0));
             if (ns) {
-                const ackSeq = client._seqTracker.getContiguousSeq(ns);
-                const contigAdvanced = ackSeq !== pageContigBefore;
-                if (contigAdvanced) {
-                    await client._drainOrderedMessages(ns);
-                    client._persistSeq(ns);
+                const commitTarget = Math.max(pageContigBefore, Number.isFinite(retentionFloor) ? retentionFloor : 0, pageCount === 1 ? deferredServerCursor : 0, seqs.length > 0 ? pageMaxSeq : pageContigBefore);
+                let ackSeq = pageContigBefore;
+                let contigAdvanced = false;
+                try {
+                    if (commitTarget > pageContigBefore) {
+                        client._seqTracker.forceContiguousSeq(ns, commitTarget);
+                        if (retentionFloor > pageContigBefore) {
+                            client._clientLog.info(`message.v2.pull retention-floor advance: ns=${ns} contiguous=${pageContigBefore} -> retention_floor_seq=${retentionFloor}`);
+                        }
+                        if (deferredServerCursor > pageContigBefore && pageCount === 1) {
+                            client._clientLog.info(`message.v2.pull restore local A from deferred server ACK cursor: ns=${ns}, contiguous=${pageContigBefore} -> server_ack_seq=${deferredServerCursor}`);
+                        }
+                        if (seqs.length > 0) {
+                            client._clientLog.debug(`message.v2.pull force contiguous: ns=${ns}, page_max_seq=${pageMaxSeq}, previous=${pageContigBefore}`);
+                        }
+                    }
+                    ackSeq = client._seqTracker.getContiguousSeq(ns);
+                    contigAdvanced = ackSeq !== pageContigBefore;
+                    if (contigAdvanced) {
+                        await client._commitSeqTrackerState(ns);
+                        if (pageCount === 1 && deferredServerCursor > 0)
+                            this.clearForwardCursor(ns, ackSeq);
+                    }
                 }
-                const ackNeeded = pageMessages.length > 0
-                    && ackSeq > 0
+                catch (exc) {
+                    if (typeof client._seqTracker.restoreNamespaceSnapshot === 'function') {
+                        client._seqTracker.restoreNamespaceSnapshot(ns, pageTrackerSnapshot);
+                    }
+                    client._clientLog.error?.(`message.v2.pull Forward commit rolled back: ns=${ns} target=${commitTarget} error=${formatE2EEError(exc)}`);
+                    throw exc;
+                }
+                if (contigAdvanced)
+                    await client._drainOrderedMessages(ns, undefined, false, false);
+                for (const fetch of deferredKeyFetches.values()) {
+                    this.scheduleSenderIKFetch(fetch.fromAid, fetch.senderDeviceId, fetch.groupId);
+                }
+                if (parsedServerAckSeq !== null && serverAckSeq > ackSeq) {
+                    this.recordForwardCursor(ns, serverAckSeq, ackSeq);
+                }
+                // 无本页服务端水位时，只有本页成功提交了比已知服务端更高的 A
+                // 才新增 ACK 义务。空页不能仅因本地已有 A 而重复 ACK。
+                const knownServerAckSeq = hasServerAckSeq
+                    ? serverAckSeq
+                    : (pageCount === 1 ? deferredServerCursor : 0);
+                const ackNeeded = ackSeq > 0
                     && ackSeq > lastAutoAckSeq
-                    && (contigAdvanced || (hasServerAckSeq && ackSeq > serverAckSeq));
+                    && ((hasServerAckSeq && ackSeq > serverAckSeq)
+                        || (contigAdvanced && ackSeq > knownServerAckSeq));
                 if (ackNeeded) {
+                    this.recordForwardAck(ns, ackSeq);
                     const nextAfter = Math.max(pageMaxSeq, nextAfterSeq);
                     const canContinuePage = messages.length > 0 && nextAfter > nextAfterSeq;
                     if (canContinuePage) {
@@ -830,18 +1351,30 @@ export class V2E2EECoordinator {
                         lastAutoAckSeq = Math.max(lastAutoAckSeq, ackSeq);
                     }
                     else {
-                        await this.ackV2(ackSeq);
+                        await this.confirmForwardP2PAck(ackSeq);
                         lastAutoAckSeq = Math.max(lastAutoAckSeq, ackSeq);
                     }
                 }
             }
             const nextAfter = Math.max(pageMaxSeq, nextAfterSeq);
             const rawCount = messages.length;
-            const canContinuePage = rawCount > 0 && nextAfter > nextAfterSeq;
-            const fullPage = canContinuePage && limit > 0 && rawCount >= limit;
-            const shouldContinue = canContinuePage && (fullPage || pendingAckSeq > 0);
+            const shouldContinue = shouldContinueForwardPage({
+                rawCount,
+                nextAfterSeq,
+                nextAfter,
+                limit,
+                hasMoreField,
+                hasMore,
+                serverHead,
+                pendingAckSeq,
+            });
             if (!shouldContinue)
                 break;
+            if (pullGateKey && opts?.gateLocked && client._rpcPipeline?.yieldPullGate) {
+                const nextKey = `${ns}|forward|after=${nextAfter}|force=${String(Boolean(opts?.force))}|limit=${limit}`;
+                await client._rpcPipeline.yieldPullGate(pullGateKey, nextKey, true);
+                pullGateKey = nextKey;
+            }
             const tailDelayMs = v2PullTailDelayMs(rawCount, limit);
             if (tailDelayMs > 0)
                 await v2Sleep(tailDelayMs);
@@ -850,40 +1383,69 @@ export class V2E2EECoordinator {
         if (pageCount >= maxPages) {
             client._clientLog.warn(`message.v2.pull reached max_pages=${maxPages} after_seq=${nextAfterSeq}`);
             if (pendingAckSeq > 0) {
-                await this.ackV2(pendingAckSeq);
+                await this.confirmForwardP2PAck(pendingAckSeq);
                 pendingAckSeq = 0;
             }
         }
         return decrypted;
     }
-    async ackV2(upToSeq) {
+    async confirmForwardP2PAck(upToSeq, inlineGeneration) {
+        const ns = this.client._aid ? `p2p:${this.client._aid}` : '';
+        try {
+            const result = await this.ackV2ForForward(upToSeq, inlineGeneration);
+            const actualAckSeq = this.client._delivery?.resolveForwardAckSeq?.(result, upToSeq) ?? 0;
+            if (actualAckSeq < upToSeq) {
+                throw new E2EEError(`message.v2.ack server ACK watermark ${actualAckSeq} is below requested ${upToSeq}`);
+            }
+            this.clearForwardAck(ns, upToSeq);
+        }
+        catch (exc) {
+            this.recordForwardAck(ns, upToSeq);
+            throw exc;
+        }
+    }
+    async ackV2(upToSeq, inlineGeneration) {
+        return this.ackV2WithConfirmation(upToSeq, inlineGeneration, false);
+    }
+    async ackV2ForForward(upToSeq, inlineGeneration) {
+        return this.ackV2WithConfirmation(upToSeq, inlineGeneration, true);
+    }
+    async ackV2WithConfirmation(upToSeq, inlineGeneration, requireServerWatermark) {
         const client = this.client;
         const ns = client._aid ? `p2p:${client._aid}` : '';
         let seq = upToSeq ?? (ns ? client._seqTracker.getContiguousSeq(ns) : 0);
-        if (seq <= 0)
+        if (typeof seq !== 'number' || !Number.isSafeInteger(seq) || seq <= 0)
             return { acked: 0 };
         seq = client._clampAckSeq('message.v2.ack', 'up_to_seq', ns, seq);
+        if (!Number.isSafeInteger(seq) || seq <= 0)
+            return { acked: 0 };
+        // ACK 发出前绑定当时的 inline pending；迟到响应不得结算重置后新建的 pending。
+        const ackGeneration = inlineGeneration ?? client._delivery?.pendingP2PInlineAckGeneration?.(ns) ?? null;
+        const v2SessionAtStart = client._v2Session;
+        const v2RuntimeGenerationAtStart = Number(client._v2RuntimeGeneration ?? 0);
         const raw = await client._callRawV2Rpc('message.v2.ack', { up_to_seq: seq });
         const result = isJsonObject(raw)
             ? { ...raw }
             : { result: raw };
-        let actualAckSeq = seq;
-        if ('effective_ack_seq' in result)
-            actualAckSeq = Number(result.effective_ack_seq ?? 0);
-        else if ('ack_seq' in result)
-            actualAckSeq = Number(result.ack_seq ?? 0);
-        else if ('cursor' in result)
-            actualAckSeq = Number(result.cursor ?? 0);
-        if (!Number.isFinite(actualAckSeq))
-            actualAckSeq = seq;
+        const actualAckSeq = requireServerWatermark
+            ? (client._delivery?.resolveForwardAckSeq?.(result, seq) ?? 0)
+            : (client._delivery?.resolveActualAckSeq?.(result, seq) ?? seq);
+        if (requireServerWatermark && actualAckSeq < seq) {
+            throw new E2EEError(`message.v2.ack server ACK watermark ${actualAckSeq} is below requested ${seq}`);
+        }
         result.ack_seq = actualAckSeq;
         result.success = true;
-        if (Number(result.acked ?? 0) === 0)
-            result.acked = actualAckSeq;
-        if (client._v2Session) {
+        if (ackGeneration !== null) {
+            client._delivery?.completePendingP2PInlineAckUpTo?.(ns, actualAckSeq, ackGeneration);
+        }
+        if (v2SessionAtStart
+            && client._v2Session === v2SessionAtStart
+            && Number(client._v2RuntimeGeneration ?? 0) === v2RuntimeGenerationAtStart) {
             try {
-                const destroyed = await client._v2Session.maybeDestroyOldSPKs(actualAckSeq);
-                if (destroyed.length > 0) {
+                const destroyed = await v2SessionAtStart.maybeDestroyOldSPKs(actualAckSeq);
+                if (client._v2Session === v2SessionAtStart
+                    && Number(client._v2RuntimeGeneration ?? 0) === v2RuntimeGenerationAtStart
+                    && destroyed.length > 0) {
                     client._clientLog.info(`V2 destroyed old SPKs after ack: ${destroyed.slice(0, 3)} (PFS)`);
                 }
             }
@@ -896,9 +1458,10 @@ export class V2E2EECoordinator {
     async sendGroupV2(groupId, payload, opts) {
         const client = this.client;
         await client._ensureV2SessionReady('group.send', 'V2 session not initialized; encrypted group.send requires V2 (V1 E2EE removed)');
-        const gid = normalizeGroupId(groupId) || String(groupId ?? '').trim();
+        const gid = String(groupId ?? '').trim();
         if (!gid)
             throw new ValidationError("group.send requires 'group_id'");
+        const groupAid = String(opts?.groupAid ?? '').trim();
         if (!isJsonObject(payload))
             throw new ValidationError('group.send payload must be a dict for V2 encryption');
         const attempt = async (useCache) => {
@@ -911,10 +1474,10 @@ export class V2E2EECoordinator {
                 context: opts?.context,
                 useCache,
             });
-            return client.call('group.v2.send', {
+            return client.call('group.v2.send', withExplicitGroupAid({
                 group_id: gid,
                 envelope,
-            });
+            }, groupAid));
         };
         try {
             const result = await attempt(true);
@@ -927,14 +1490,14 @@ export class V2E2EECoordinator {
                     await client._saveSeqTrackerState();
                 }
             }
-            return client._delivery.attachSendResultEnvelope('group.send', {
+            return client._delivery.attachSendResultEnvelope('group.send', withExplicitGroupAid({
                 group_id: gid,
                 payload,
                 message_id: opts?.messageId,
                 timestamp: opts?.timestamp,
                 protected_headers: opts?.protectedHeaders,
                 context: opts?.context,
-            }, result, true);
+            }, groupAid), result, true);
         }
         catch (exc) {
             const excCode = exc?.code;
@@ -951,65 +1514,184 @@ export class V2E2EECoordinator {
                         await client._saveSeqTrackerState();
                     }
                 }
-                return client._delivery.attachSendResultEnvelope('group.send', {
+                return client._delivery.attachSendResultEnvelope('group.send', withExplicitGroupAid({
                     group_id: gid,
                     payload,
                     message_id: opts?.messageId,
                     timestamp: opts?.timestamp,
                     protected_headers: opts?.protectedHeaders,
                     context: opts?.context,
-                }, result, true);
+                }, groupAid), result, true);
             }
             throw exc;
         }
     }
+    async pullGroupV2TailInternal(params, deferPublish = false) {
+        const client = this.client;
+        if (params.window_mode !== 'tail')
+            throw new ValidationError('window_mode must equal tail');
+        if ('ack_up_to_seq' in params || params.force === true)
+            throw new ValidationError('Tail does not accept ack_up_to_seq or force');
+        const groupId = String(params.group_id ?? params.group_aid ?? '').trim();
+        if (!groupId)
+            throw new ValidationError('group_id is required');
+        let groupAid = String(params.group_aid ?? '').trim();
+        const afterSeq = strictWindowSeq(params.after_seq ?? 0, 'after_seq');
+        const limit = strictWindowLimit(params.limit ?? V2_PULL_DEFAULT_PAGE_LIMIT);
+        const ns = `group:${groupId}`;
+        const result = await client._callRawV2Rpc('group.v2.pull', withExplicitGroupAid({
+            group_id: groupId, window_mode: 'tail', after_seq: afterSeq, limit, _rpc_foreground: true,
+        }, groupAid));
+        const resultAid = String(result.group_aid ?? result.groupAid ?? '').trim();
+        if (resultAid)
+            groupAid = resultAid;
+        const floor = Number(result.retention_floor_message_seq ?? result.retention_floor_seq ?? 0);
+        const previous = client._seqTracker.getSyncState(ns);
+        await this.applyTailFloor(ns, Number.isSafeInteger(floor) ? floor : 0);
+        const page = validateTailPage(result, afterSeq, limit);
+        client._seqTracker.commitTailWindow(ns, {
+            windowStartSeq: page.windowStart, headSeq: page.head, coveredThroughSeq: page.head, pageLimit: limit,
+        });
+        client._persistSeq(ns);
+        await client._saveSeqTrackerState?.();
+        const decoded = [];
+        for (const msg of page.messages) {
+            client._logMessageDebug?.('tail-raw', 'group.v2.pull', 'group.message_created', msg);
+            const plaintext = await this.decodeGroupWindowMessage(msg, groupId, groupAid, true, false, 'tail', deferPublish);
+            if (plaintext)
+                decoded.push(plaintext);
+        }
+        const ack = client._seqTracker.getContiguousSeq(ns);
+        if (ack > previous.ack)
+            await this.ackGroupV2(groupId, ack, groupAid);
+        return { ...result, messages: decoded, raw_count: page.messages.length };
+    }
+    async historyGroupV2Internal(params) {
+        const groupId = String(params.group_id ?? params.group_aid ?? '').trim();
+        if (!groupId)
+            throw new ValidationError('group_id is required');
+        let groupAid = String(params.group_aid ?? '').trim();
+        const beforeSeq = strictWindowSeq(params.before_seq, 'before_seq', true);
+        const limit = strictWindowLimit(params.limit ?? V2_PULL_DEFAULT_PAGE_LIMIT);
+        const result = await this.client._callRawV2Rpc('group.history', withExplicitGroupAid({
+            group_id: groupId, before_seq: beforeSeq, limit, _rpc_foreground: true,
+        }, groupAid));
+        const resultAid = String(result.group_aid ?? result.groupAid ?? '').trim();
+        if (resultAid)
+            groupAid = resultAid;
+        const messages = validateHistoryPage(result, beforeSeq);
+        const decoded = [];
+        for (const msg of messages) {
+            const plaintext = await this.decodeGroupWindowMessage(msg, groupId, groupAid, false, true, 'history');
+            if (plaintext)
+                decoded.push(plaintext);
+        }
+        return { ...result, messages: decoded };
+    }
     async pullGroupV2Internal(params) {
-        await this.pullGroupV2(params.group_id, params.after_seq, params.limit);
+        await this.pullGroupV2(params.group_id, params.after_seq, params.limit, {
+            gateLocked: true,
+            explicitAfterSeq: true,
+            force: params.force === true,
+        });
     }
     async pullGroupV2(groupId, afterSeq = 0, limit = 50, opts) {
         const client = this.client;
         await client._ensureV2SessionReady('group.pull');
-        const gid = normalizeGroupId(groupId) || String(groupId ?? '').trim();
+        const gid = String(groupId ?? '').trim();
         if (!gid)
             throw new ValidationError('group.pull requires group_id');
+        let groupAid = String(opts?.groupAid ?? '').trim();
         const ns = `group:${gid}`;
+        if (opts?.windowMode === 'tail') {
+            if (!opts.gateLocked) {
+                const key = `${ns}|tail|after=${afterSeq}|limit=${limit}`;
+                return await client._runPullSerialized(key, () => this.pullGroupV2(gid, afterSeq, limit, {
+                    ...(opts ?? {}),
+                    gateLocked: true,
+                }), false);
+            }
+            const result = await this.pullGroupV2TailInternal({
+                group_id: String(opts.wireGroupId ?? gid), group_aid: groupAid || undefined,
+                window_mode: 'tail', after_seq: afterSeq, limit,
+            });
+            return Array.isArray(result.messages) ? result.messages : [];
+        }
+        if (!opts?.gateLocked) {
+            const key = `${ns}|forward|after=${afterSeq}|force=${String(Boolean(opts?.force))}|limit=${limit}`;
+            return await client._runPullSerialized(key, () => this.pullGroupV2(gid, afterSeq, limit, {
+                ...(opts ?? {}),
+                gateLocked: true,
+            }), true);
+        }
         const decrypted = [];
         const wireGroupId = String(opts?.wireGroupId ?? groupId ?? '').trim() || gid;
         const cursorParams = opts?.cursorParams ?? {};
         const ownsCursor = opts?.ownsCursor !== false;
-        let nextAfterSeq = opts?.explicitAfterSeq ? afterSeq : (afterSeq || client._seqTracker.getContiguousSeq(ns));
+        let pullGateKey = ownsCursor
+            ? `${ns}|forward|after=${afterSeq}|force=${String(Boolean(opts?.force))}|limit=${limit}`
+            : '';
+        let nextAfterSeq = (opts?.explicitAfterSeq || opts?.force)
+            ? afterSeq
+            : (afterSeq || client._seqTracker.getContiguousSeq(ns));
+        const deferredServerCursor = ownsCursor
+            ? this.pendingForwardCursor(ns, client._seqTracker.getContiguousSeq(ns))
+            : 0;
+        const deferredForwardAck = ownsCursor ? this.pendingForwardAck(ns, client._seqTracker.getContiguousSeq(ns)) : 0;
         let pageCount = 0;
         let lastAutoAckSeq = 0;
-        let pendingAckSeq = 0;
-        const maxPages = 100;
+        let pendingAckSeq = deferredForwardAck;
+        const maxPages = Math.max(1, Math.min(100, Math.trunc(Number(opts?.maxPages ?? 100) || 100)));
         while (pageCount < maxPages) {
             pageCount += 1;
             const ackUpToSeq = ownsCursor ? pendingAckSeq : 0;
-            const result = await client._callRawV2Rpc('group.v2.pull', {
+            const pendingInlineGeneration = ackUpToSeq > 0
+                ? client._delivery?.pendingGroupInlineAckGeneration?.(ns) ?? null
+                : null;
+            const result = await client._callRawV2Rpc('group.v2.pull', withExplicitGroupAid({
                 group_id: wireGroupId,
-                group_aid: gid,
                 after_seq: nextAfterSeq,
                 limit,
                 ...cursorParams,
+                ...(opts?.force ? { force: true } : {}),
                 ...(ackUpToSeq > 0 ? { ack_up_to_seq: ackUpToSeq } : {}),
-            });
+            }, groupAid));
             if (ackUpToSeq > 0) {
-                pendingAckSeq = 0;
-                lastAutoAckSeq = Math.max(lastAutoAckSeq, ackUpToSeq);
+                const actualAckSeq = client._delivery?.resolveGroupPullAckSeq?.(result, ackUpToSeq) ?? 0;
+                if (actualAckSeq >= ackUpToSeq) {
+                    if (pendingInlineGeneration !== null) {
+                        client._delivery?.completePendingGroupInlineAckUpTo?.(ns, actualAckSeq, pendingInlineGeneration);
+                    }
+                    pendingAckSeq = 0;
+                    lastAutoAckSeq = Math.max(lastAutoAckSeq, ackUpToSeq);
+                    this.clearForwardAck(ns, ackUpToSeq);
+                }
+                else {
+                    client._clientLog.warn(`group.v2.pull piggyback ACK below target: group=${gid}, requested=${ackUpToSeq}, actual=${actualAckSeq}; fallback terminal ACK`);
+                    await this.confirmForwardGroupAck(gid, ackUpToSeq, groupAid);
+                    pendingAckSeq = 0;
+                    lastAutoAckSeq = Math.max(lastAutoAckSeq, ackUpToSeq);
+                }
             }
+            const resultGroupAid = String(result.group_aid ?? result.groupAid ?? '').trim();
+            if (resultGroupAid)
+                groupAid = resultGroupAid;
+            const eventGroupAid = resultGroupAid || groupAid || gid;
             const pageMessages = (Array.isArray(result?.messages) ? result.messages : []);
-            const messages = pageMessages.filter((msg) => {
-                const seq = Number(msg.seq ?? 0);
-                return Number.isFinite(seq) && seq > nextAfterSeq;
-            }).sort((a, b) => Number(a.seq ?? 0) - Number(b.seq ?? 0));
+            const messages = deduplicateForwardPageMessages(pageMessages, nextAfterSeq);
+            const cursor = isJsonObject(result.cursor) ? result.cursor : null;
+            const hasMoreField = Object.prototype.hasOwnProperty.call(result, 'has_more');
+            const hasMore = result.has_more === true;
+            const serverHead = Math.max(safeNonNegativeSeq(result.latest_message_seq) ?? 0, safeNonNegativeSeq(cursor?.latest_seq) ?? 0);
             const seqs = messages
                 .map((msg) => Number(msg.seq ?? 0))
                 .filter((seq) => Number.isFinite(seq) && seq > 0);
             const pageContigBefore = client._seqTracker.getContiguousSeq(ns);
+            const pageTrackerSnapshot = typeof client._seqTracker.snapshotNamespace === 'function'
+                ? client._seqTracker.snapshotNamespace(ns)
+                : null;
             const pageMaxSeq = seqs.length > 0 ? Math.max(...seqs) : nextAfterSeq;
-            if (seqs.length > 0) {
-                client._seqTracker.forceContiguousSeq(ns, pageMaxSeq);
-            }
+            const deferredKeyFetches = new Map();
             for (const msg of messages) {
                 const seq = Number(msg.seq ?? 0);
                 if (!Number.isFinite(seq) || seq <= 0)
@@ -1020,7 +1702,11 @@ export class V2E2EECoordinator {
                     const payloadObj = isJsonObject(payload) ? payload : null;
                     // 群撤回 tombstone（占位 / 通知）：归一化为 group.message_recalled 事件，仍占 seq。
                     if (client._delivery.recallEventFromGroupMessage(msg)) {
-                        await client._delivery.publishGroupRecallTombstone(gid, seq, msg);
+                        await client._delivery.publishGroupRecallTombstone(gid, seq, {
+                            ...msg,
+                            group_id: gid,
+                            group_aid: eventGroupAid,
+                        });
                         client._markPublishedSeq(ns, seq);
                         client._clientLog.debug(`group.v2.pull recall tombstone delivered: group=${gid}, seq=${seq}`);
                         continue;
@@ -1028,35 +1714,39 @@ export class V2E2EECoordinator {
                     if (payloadObj) {
                         const payloadType = String(payloadObj.type ?? '').trim();
                         if (payloadType !== 'e2ee.encrypted' && payloadType !== 'e2ee.group_encrypted') {
-                            const v1Msg = {
+                            let v1Msg = {
                                 message_id: String(msg.message_id ?? ''),
                                 from: String(msg.from_aid ?? ''),
                                 group_id: gid,
+                                group_aid: eventGroupAid,
                                 seq: msg.seq,
                                 type: String(msg.type ?? ''),
                                 timestamp: msg.t_server,
                                 payload,
                                 encrypted: false,
                             };
+                            v1Msg = normalizeGroupMentionMode(v1Msg, msg, msg.envelope_json);
                             attachGatewayProximity(v1Msg, msg);
-                            await client._publishPulledMessage('group.message_created', ns, seq, v1Msg);
+                            await client._publishPulledMessage('group.message_created', ns, seq, v1Msg, false);
                             decrypted.push(v1Msg);
                             continue;
                         }
                     }
                     else if (payload !== undefined && payload !== null) {
-                        const v1Msg = {
+                        let v1Msg = {
                             message_id: String(msg.message_id ?? ''),
                             from: String(msg.from_aid ?? ''),
                             group_id: gid,
+                            group_aid: eventGroupAid,
                             seq: msg.seq,
                             type: String(msg.type ?? ''),
                             timestamp: msg.t_server,
                             payload,
                             encrypted: false,
                         };
+                        v1Msg = normalizeGroupMentionMode(v1Msg, msg, msg.envelope_json);
                         attachGatewayProximity(v1Msg, msg);
-                        await client._publishPulledMessage('group.message_created', ns, seq, v1Msg);
+                        await client._publishPulledMessage('group.message_created', ns, seq, v1Msg, false);
                         decrypted.push(v1Msg);
                         continue;
                     }
@@ -1067,35 +1757,83 @@ export class V2E2EECoordinator {
                     client._clientLog.debug(`group.v2.pull skipping non-V2 row group=${gid} seq=${seq} version=${String(msg.version ?? '')}`);
                     continue;
                 }
-                const plaintext = await client._decryptV2Message(msg);
+                const deferStatus = {};
+                let plaintext = await client._decryptV2Message(msg, true, true, true, true, deferStatus, true);
+                if (deferStatus.deferred && deferStatus.fromAid) {
+                    const key = `${deferStatus.fromAid}\u0000${deferStatus.senderDeviceId ?? ''}\u0000${deferStatus.groupId ?? ''}`;
+                    deferredKeyFetches.set(key, {
+                        fromAid: deferStatus.fromAid,
+                        senderDeviceId: deferStatus.senderDeviceId ?? '',
+                        groupId: deferStatus.groupId ?? '',
+                    });
+                }
                 if (plaintext === null)
                     continue;
+                plaintext = normalizeGroupMentionMode(plaintext, msg, msg.envelope_json);
                 plaintext.group_id = gid;
-                await client._publishPulledMessage('group.message_created', ns, seq, plaintext);
+                plaintext.group_aid = eventGroupAid;
+                await client._publishPulledMessage('group.message_created', ns, seq, plaintext, false);
                 decrypted.push(plaintext);
             }
-            const cursor = isJsonObject(result.cursor) ? result.cursor : null;
-            const cursorCurrentSeq = Number(cursor?.current_seq ?? 0);
-            if (Number.isFinite(cursorCurrentSeq) && cursorCurrentSeq > 0) {
-                const contig = client._seqTracker.getContiguousSeq(ns);
-                if (contig < cursorCurrentSeq) {
-                    client._clientLog.info(`group.v2.pull retention-floor advance: ns=${ns} contiguous=${contig} -> cursor.current_seq=${cursorCurrentSeq}`);
-                    client._seqTracker.forceContiguousSeq(ns, cursorCurrentSeq);
+            const hasServerCursor = cursor !== null && Object.prototype.hasOwnProperty.call(cursor, 'current_seq');
+            const parsedCursorCurrentSeq = hasServerCursor ? safeNonNegativeSeq(cursor?.current_seq) : null;
+            const cursorCurrentSeq = parsedCursorCurrentSeq ?? 0;
+            const retentionFloor = Math.max(Number(result.retention_floor_message_seq ?? result.retention_floor_seq ?? 0), Number(cursor?.retention_floor_seq ?? 0));
+            const visibilityFloor = Math.max(0, Math.max(0, Number(result.earliest_available_message_seq ?? 1) - 1), Number(cursor?.join_seq ?? 0));
+            const effectiveFloor = Math.max(retentionFloor, visibilityFloor);
+            const commitTarget = Math.max(pageContigBefore, Number.isFinite(effectiveFloor) ? effectiveFloor : 0, ownsCursor && pageCount === 1 ? deferredServerCursor : 0, seqs.length > 0 ? pageMaxSeq : pageContigBefore);
+            let ackSeq = pageContigBefore;
+            let contigAdvanced = false;
+            if (ownsCursor) {
+                try {
+                    if (commitTarget > pageContigBefore) {
+                        client._seqTracker.forceContiguousSeq(ns, commitTarget);
+                        if (effectiveFloor > pageContigBefore) {
+                            client._clientLog.info(`group.v2.pull floor advance: ns=${ns} contiguous=${pageContigBefore} -> effective_floor=${effectiveFloor} retention_floor=${retentionFloor} visibility_floor=${visibilityFloor}`);
+                        }
+                        if (deferredServerCursor > pageContigBefore && pageCount === 1) {
+                            client._clientLog.info(`group.v2.pull restore local A from deferred server ACK cursor: group=${gid}, ns=${ns}, contiguous=${pageContigBefore} -> current_seq=${deferredServerCursor}`);
+                        }
+                        if (seqs.length > 0) {
+                            client._clientLog.debug(`group.v2.pull force contiguous: group=${gid}, ns=${ns}, page_max_seq=${pageMaxSeq}, previous=${pageContigBefore}`);
+                        }
+                    }
+                    ackSeq = client._seqTracker.getContiguousSeq(ns);
+                    contigAdvanced = ackSeq !== pageContigBefore;
+                    if (contigAdvanced) {
+                        await client._commitSeqTrackerState(ns);
+                        if (pageCount === 1 && deferredServerCursor > 0)
+                            this.clearForwardCursor(ns, ackSeq);
+                    }
+                }
+                catch (exc) {
+                    if (typeof client._seqTracker.restoreNamespaceSnapshot === 'function') {
+                        client._seqTracker.restoreNamespaceSnapshot(ns, pageTrackerSnapshot);
+                    }
+                    client._clientLog.error?.(`group.v2.pull Forward commit rolled back: group=${gid} ns=${ns} target=${commitTarget} error=${formatE2EEError(exc)}`);
+                    throw exc;
                 }
+                if (contigAdvanced)
+                    await client._drainOrderedMessages(ns, undefined, false, false);
             }
-            const ackSeq = client._seqTracker.getContiguousSeq(ns);
-            const contigAdvanced = ackSeq !== pageContigBefore;
-            if (contigAdvanced) {
-                await client._drainOrderedMessages(ns);
-                client._persistSeq(ns);
+            for (const fetch of deferredKeyFetches.values()) {
+                this.scheduleSenderIKFetch(fetch.fromAid, fetch.senderDeviceId, fetch.groupId);
             }
-            const hasServerCursor = cursor !== null && Object.prototype.hasOwnProperty.call(cursor, 'current_seq');
-            const ackNeeded = pageMessages.length > 0
-                && ackSeq > 0
+            if (ownsCursor && parsedCursorCurrentSeq !== null && cursorCurrentSeq > ackSeq) {
+                this.recordForwardCursor(ns, cursorCurrentSeq, ackSeq);
+            }
+            // 无本页 cursor.current_seq 时，只有本页成功提交了比已知 cursor
+            // 更高的 A 才新增 ACK 义务；空页不得因已有本地 A 重复确认。
+            const knownServerCursorSeq = hasServerCursor
+                ? cursorCurrentSeq
+                : (ownsCursor && pageCount === 1 ? deferredServerCursor : 0);
+            const ackNeeded = ackSeq > 0
                 && ackSeq > lastAutoAckSeq
                 && ownsCursor
-                && (contigAdvanced || (hasServerCursor && ackSeq > cursorCurrentSeq));
+                && ((hasServerCursor && ackSeq > cursorCurrentSeq)
+                    || (contigAdvanced && ackSeq > knownServerCursorSeq));
             if (ackNeeded) {
+                this.recordForwardAck(ns, ackSeq);
                 const nextAfter = Math.max(pageMaxSeq, nextAfterSeq);
                 const canContinuePage = messages.length > 0 && nextAfter > nextAfterSeq && ownsCursor;
                 if (canContinuePage) {
@@ -1103,7 +1841,7 @@ export class V2E2EECoordinator {
                     lastAutoAckSeq = Math.max(lastAutoAckSeq, ackSeq);
                 }
                 else {
-                    await this.ackGroupV2(gid, ackSeq);
+                    await this.confirmForwardGroupAck(gid, ackSeq, groupAid);
                     lastAutoAckSeq = Math.max(lastAutoAckSeq, ackSeq);
                 }
             }
@@ -1111,11 +1849,23 @@ export class V2E2EECoordinator {
             if (!ownsCursor)
                 break;
             const rawCount = messages.length;
-            const canContinuePage = rawCount > 0 && nextAfter > nextAfterSeq;
-            const fullPage = canContinuePage && limit > 0 && rawCount >= limit;
-            const shouldContinue = canContinuePage && (fullPage || pendingAckSeq > 0);
+            const shouldContinue = shouldContinueForwardPage({
+                rawCount,
+                nextAfterSeq,
+                nextAfter,
+                limit,
+                hasMoreField,
+                hasMore,
+                serverHead,
+                pendingAckSeq,
+            });
             if (!shouldContinue)
                 break;
+            if (pullGateKey && opts?.gateLocked && client._rpcPipeline?.yieldPullGate) {
+                const nextKey = `${ns}|forward|after=${nextAfter}|force=${String(Boolean(opts?.force))}|limit=${limit}`;
+                await client._rpcPipeline.yieldPullGate(pullGateKey, nextKey, true);
+                pullGateKey = nextKey;
+            }
             const tailDelayMs = v2PullTailDelayMs(rawCount, limit);
             if (tailDelayMs > 0)
                 await v2Sleep(tailDelayMs);
@@ -1124,23 +1874,66 @@ export class V2E2EECoordinator {
         if (pageCount >= maxPages) {
             client._clientLog.warn(`group.v2.pull reached max_pages=${maxPages} group=${gid} after_seq=${nextAfterSeq}`);
             if (pendingAckSeq > 0) {
-                await this.ackGroupV2(gid, pendingAckSeq);
+                await this.confirmForwardGroupAck(gid, pendingAckSeq, groupAid);
                 pendingAckSeq = 0;
             }
         }
         return decrypted;
     }
-    async ackGroupV2(groupId, upToSeq) {
+    async confirmForwardGroupAck(groupId, upToSeq, groupAid) {
+        const ns = `group:${String(groupId ?? '').trim()}`;
+        try {
+            const result = await this.ackGroupV2ForForward(groupId, upToSeq, groupAid);
+            const actualAckSeq = this.client._delivery?.resolveForwardAckSeq?.(result, upToSeq) ?? 0;
+            if (actualAckSeq < upToSeq) {
+                throw new E2EEError(`group.v2.ack server ACK watermark ${actualAckSeq} is below requested ${upToSeq}`);
+            }
+            this.clearForwardAck(ns, upToSeq);
+        }
+        catch (exc) {
+            this.recordForwardAck(ns, upToSeq);
+            throw exc;
+        }
+    }
+    async ackGroupV2(groupId, upToSeq, groupAid, inlineGeneration) {
+        return this.ackGroupV2WithConfirmation(groupId, upToSeq, groupAid, inlineGeneration, false);
+    }
+    async ackGroupV2ForForward(groupId, upToSeq, groupAid) {
+        return this.ackGroupV2WithConfirmation(groupId, upToSeq, groupAid, undefined, true);
+    }
+    async ackGroupV2WithConfirmation(groupId, upToSeq, groupAid, inlineGeneration, requireServerWatermark) {
         const client = this.client;
-        const gid = normalizeGroupId(groupId) || String(groupId ?? '').trim();
+        const gid = typeof groupId === 'string' ? groupId.trim() : '';
         if (!gid)
             throw new ValidationError('group.ack_messages requires group_id');
-        const ns = `group:${gid}`;
-        let seq = Number(upToSeq ?? client._seqTracker.getContiguousSeq(ns));
-        if (!Number.isFinite(seq) || seq <= 0)
+        if (groupAid !== undefined && typeof groupAid !== 'string') {
+            throw new ValidationError('group.ack_messages group_aid must be a string');
+        }
+        const explicitGroupAid = groupAid?.trim() ?? '';
+        const wireNs = `group:${gid}`;
+        const ns = client._delivery?.resolvePendingGroupInlineAckNamespace?.(wireNs) ?? wireNs;
+        let seq = upToSeq ?? client._seqTracker.getContiguousSeq(ns);
+        if (typeof upToSeq !== 'undefined' && (typeof upToSeq !== 'number' || !Number.isSafeInteger(upToSeq))) {
+            return { acked: 0 };
+        }
+        if (!Number.isSafeInteger(seq) || seq <= 0)
             return { acked: 0 };
         seq = client._clampAckSeq('group.v2.ack', 'up_to_seq', ns, seq);
-        return client._callRawV2Rpc('group.v2.ack', { group_id: gid, group_aid: gid, up_to_seq: seq });
+        if (!Number.isSafeInteger(seq) || seq <= 0)
+            return { acked: 0 };
+        // 与 P2P 一致，必须将 ACK 响应限定到请求开始时对应的 inline generation。
+        const ackGeneration = inlineGeneration ?? client._delivery?.pendingGroupInlineAckGeneration?.(ns) ?? null;
+        const raw = await client._callRawV2Rpc('group.v2.ack', withExplicitGroupAid({ group_id: gid, up_to_seq: seq }, explicitGroupAid));
+        const actualAckSeq = requireServerWatermark
+            ? (client._delivery?.resolveForwardAckSeq?.(raw, seq) ?? 0)
+            : (client._delivery?.resolveActualAckSeq?.(raw, seq) ?? seq);
+        if (requireServerWatermark && actualAckSeq < seq) {
+            throw new E2EEError(`group.v2.ack server ACK watermark ${actualAckSeq} is below requested ${seq}`);
+        }
+        if (ackGeneration !== null) {
+            client._delivery?.completePendingGroupInlineAckUpTo?.(ns, actualAckSeq, ackGeneration);
+        }
+        return raw;
     }
     async putMessageThoughtEncryptedV2(params) {
         const client = this.client;
@@ -1318,7 +2111,7 @@ export class V2E2EECoordinator {
             let e2ee;
             if (payload?.type === 'e2ee.group_encrypted' && String(payload.version ?? '') === 'v2') {
                 e2ee = v2E2eeMeta(payload);
-                const plain = await client._decryptV2EnvelopeForThought({ envelope: payload, fromAid });
+                const plain = await client._decryptV2EnvelopeForThought({ envelope: payload, fromAid, fetchSenderIK: true });
                 if (plain === null) {
                     decryptFailed = true;
                     client._clientLog.debug(`group.thought.get decrypt returned null: group=${groupId}, thought_id=${thoughtId}, from=${fromAid}`);
@@ -1388,7 +2181,7 @@ export class V2E2EECoordinator {
             let e2ee;
             if (payload?.type === 'e2ee.p2p_encrypted' && String(payload.version ?? '') === 'v2') {
                 e2ee = v2E2eeMeta(payload);
-                const plain = await client._decryptV2EnvelopeForThought({ envelope: payload, fromAid });
+                const plain = await client._decryptV2EnvelopeForThought({ envelope: payload, fromAid, fetchSenderIK: true });
                 if (plain === null) {
                     decryptFailed = true;
                     client._clientLog.debug(`message.thought.get decrypt returned null: thought_id=${thoughtId}, from=${fromAid}, to=${toAid}`);
@@ -1475,7 +2268,10 @@ export class V2E2EECoordinator {
         const fromAid = String(opts.fromAid || aad.from || '').trim();
         const senderDeviceId = String(aad.from_device ?? '');
         const senderCertFingerprint = String(envelope.sender_cert_fingerprint ?? '').trim().toLowerCase();
-        const senderPubDer = await this.getV2SenderPubDer(fromAid, senderDeviceId, senderCertFingerprint);
+        let senderPubDer = await this.getV2SenderPubDer(fromAid, senderDeviceId, senderCertFingerprint);
+        if (!senderPubDer && opts.fetchSenderIK) {
+            senderPubDer = await this.fetchSenderIKOnce(fromAid, senderDeviceId, groupIdForKeys, senderCertFingerprint);
+        }
         if (!senderPubDer) {
             client._clientLog.warn(`V2 thought decrypt: no sender IK for ${fromAid} device=${senderDeviceId}`);
             this.scheduleSenderIKFetch(fromAid, senderDeviceId, groupIdForKeys);
@@ -1543,7 +2339,7 @@ export class V2E2EECoordinator {
         return String(envelope.version ?? '').trim().toLowerCase() === 'v2' && payloadType.startsWith('e2ee.');
     }
     safeUndecryptablePushEvent(msg, group) {
-        const event = {
+        let event = {
             message_id: msg.message_id ?? null,
             from: msg.from ?? null,
             seq: msg.seq ?? null,
@@ -1567,6 +2363,10 @@ export class V2E2EECoordinator {
                 attachV2EnvelopeMetadata(event, v2E2eeMeta(envelope));
             }
         }
+        if (group) {
+            const modeSource = envelope ? { ...msg, envelope } : msg;
+            event = normalizeGroupMentionMode(event, modeSource);
+        }
         return event;
     }
     async decryptEncryptedPushPayload(msg, group) {
@@ -1580,7 +2380,7 @@ export class V2E2EECoordinator {
         if (!plaintext)
             return null;
         const e2eeMeta = v2E2eeMeta(envelope);
-        const result = {
+        let result = {
             message_id: String(msg.message_id ?? ''),
             from: fromAid,
             seq: msg.seq ?? null,
@@ -1599,6 +2399,7 @@ export class V2E2EECoordinator {
         attachGatewayProximity(result, msg);
         if (group) {
             result.group_id = msg.group_id ?? aad.group_id ?? envelope.group_id ?? null;
+            result = normalizeGroupMentionMode(result, msg, envelope);
         }
         else {
             result.to = msg.to ?? client._aid ?? '';
@@ -1659,6 +2460,7 @@ export class V2E2EECoordinator {
             peerDevices = (Array.isArray(bs?.peer_devices) ? bs.peer_devices : []);
             auditRaw = (Array.isArray(bs?.audit_recipients) ? bs.audit_recipients : []);
             wrapPolicy = normalizeV2WrapPolicy(bs?.e2ee_wrap_policy);
+            this.cacheBundledSelfDevices(bs, wrapPolicy);
             if (peerDevices.length > 0) {
                 this.setBootstrapCacheEntry(to, {
                     devices: peerDevices,
@@ -1758,8 +2560,7 @@ export class V2E2EECoordinator {
             throw new StateError('V2 session not initialized');
         }
         const session = client._v2Session;
-        const rawGroupId = String(opts.groupId ?? '').trim();
-        const groupId = normalizeGroupId(rawGroupId) || rawGroupId;
+        const groupId = String(opts.groupId ?? '').trim();
         if (!groupId)
             throw new ValidationError("group.send requires 'group_id'");
         const useCache = opts.useCache !== false;
@@ -1770,15 +2571,7 @@ export class V2E2EECoordinator {
         let auditRecipientsRaw = [];
         let wrapPolicy;
         let usedCachedBootstrap = false;
-        let cached = useCache ? this.getBootstrapCacheEntry(cacheKey) : undefined;
-        if (!cached && useCache && rawGroupId && rawGroupId !== groupId) {
-            const legacyCacheKey = `group:${rawGroupId}`;
-            cached = this.getBootstrapCacheEntry(legacyCacheKey);
-            if (cached) {
-                this.setBootstrapCacheEntry(cacheKey, cached);
-                this.deleteBootstrapCacheEntry(legacyCacheKey);
-            }
-        }
+        const cached = useCache ? this.getBootstrapCacheEntry(cacheKey) : undefined;
         if (cached && (Date.now() - Number(cached.cachedAt ?? 0)) < V2_BOOTSTRAP_TTL_MS) {
             allDevices = (cached.devices ?? []);
             epoch = Number(cached.epoch ?? 0) || 0;