@agentunion/fastaun 0.5.6 → 0.5.9

package/dist/client/delivery.js

@@ -37,23 +37,235 @@ function isPromiseLike(value) {
 function formatDeliveryError(error) {
     return error instanceof Error ? error : String(error);
 }
+function positiveSafeSequenceHint(value) {
+    if (typeof value === 'number')
+        return Number.isSafeInteger(value) && value > 0 ? value : 0;
+    if (typeof value !== 'string' || !value || value.trim() !== value)
+        return 0;
+    const parsed = Number(value);
+    return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : 0;
+}
+function nonNegativeSafeSequenceHint(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : null;
+}
+function deduplicatePlainForwardPageMessages(value, afterSeq) {
+    if (!Array.isArray(value))
+        return [];
+    const bySeq = new Map();
+    for (const raw of value) {
+        if (!isJsonObject(raw))
+            continue;
+        const seq = positiveSafeSequenceHint(raw.seq);
+        if (seq <= afterSeq || bySeq.has(seq))
+            continue;
+        bySeq.set(seq, { ...raw, seq });
+    }
+    return [...bySeq.entries()].sort(([left], [right]) => left - right).map(([, message]) => message);
+}
 export class MessageDeliveryEngine {
     runtime;
     realtimeTailHeads = null;
     realtimeSyncing = null;
+    pendingGroupPullUpper = null;
+    onlineUnreadHintTargets = null;
+    onlineUnreadHintTasks = null;
     pendingP2PInlineAcks = null;
     pendingGroupInlineAcks = null;
     pendingGroupInlineAckNamespaces = null;
     inlineAckGeneration = 0;
+    // 同一实例的 tracker 写入必须串行，避免旧的延迟 flush 覆盖新的 Forward 提交。
+    seqTrackerWriteChain = Promise.resolve();
     constructor(runtime) {
         this.runtime = runtime;
     }
+    isPullOperationCurrent() {
+        const client = this.runtime.client;
+        const generation = client._pullOperationGeneration;
+        if (generation === undefined)
+            return true;
+        const pipeline = client._rpcPipeline;
+        return typeof pipeline?.isPullGenerationCurrent === 'function'
+            ? pipeline.isPullGenerationCurrent(generation)
+            : true;
+    }
+    ensurePullOperationCurrent() {
+        if (!this.isPullOperationCurrent())
+            throw new Error('pull invalidated');
+    }
+    forwardCoordinator() {
+        const coordinator = this.runtime.client._v2E2EE;
+        if (!coordinator
+            || typeof coordinator.pendingForwardCursor !== 'function'
+            || typeof coordinator.recordForwardCursor !== 'function'
+            || typeof coordinator.clearForwardCursor !== 'function'
+            || typeof coordinator.pendingForwardAck !== 'function'
+            || typeof coordinator.recordForwardAck !== 'function'
+            || typeof coordinator.clearForwardAck !== 'function') {
+            throw new Error('Forward cursor coordinator is unavailable');
+        }
+        return coordinator;
+    }
+    async confirmPlainForwardAck(ns, method, ackSeq, groupId = '') {
+        const client = this.runtime.client;
+        this.ensurePullOperationCurrent();
+        const coordinator = this.forwardCoordinator();
+        const generation = this.captureInlineAckGeneration();
+        coordinator.recordForwardAck(ns, ackSeq);
+        const params = method === 'message.ack'
+            ? {
+                seq: ackSeq,
+                device_id: client._deviceId,
+                slot_id: client._slotId,
+                _rpc_background: true,
+            }
+            : {
+                group_id: groupId,
+                msg_seq: ackSeq,
+                device_id: client._deviceId,
+                slot_id: client._slotId,
+                _rpc_background: true,
+            };
+        const result = await client._rpcPipeline.rawCall(method, params, { background: true });
+        this.ensurePullOperationCurrent();
+        const actualAckSeq = this.resolveForwardAckSeq(result, ackSeq);
+        if (actualAckSeq < ackSeq) {
+            throw new Error(`${method} server ACK watermark ${actualAckSeq} is below requested ${ackSeq}`);
+        }
+        coordinator.clearForwardAck(ns, actualAckSeq);
+        if (method === 'message.ack') {
+            this.onP2PV2AckSucceeded(actualAckSeq, generation);
+        }
+        else {
+            this.onGroupV2AckSucceeded(groupId, actualAckSeq, generation);
+        }
+    }
+    async commitPlainForwardPage(ns, afterSeq, method, result, groupId = '') {
+        if (!isJsonObject(result)) {
+            throw new Error(`${method} response must be an object`);
+        }
+        const client = this.runtime.client;
+        this.ensurePullOperationCurrent();
+        const response = result;
+        const messages = deduplicatePlainForwardPageMessages(response.messages, afterSeq);
+        const coordinator = this.forwardCoordinator();
+        const pageContigBefore = client._seqTracker.getContiguousSeq(ns);
+        const pageInlineGeneration = this.captureInlineAckGeneration();
+        const deferredServerCursor = Number(coordinator.pendingForwardCursor(ns, pageContigBefore) ?? 0);
+        const deferredForwardAck = Number(coordinator.pendingForwardAck(ns, pageContigBefore) ?? 0);
+        const pageTrackerSnapshot = typeof client._seqTracker.snapshotNamespace === 'function'
+            ? client._seqTracker.snapshotNamespace(ns)
+            : null;
+        response._contig_before = pageContigBefore;
+        const cursor = isJsonObject(response.cursor)
+            ? response.cursor
+            : null;
+        const serverAckRaw = method === 'message.pull' ? response.server_ack_seq : cursor?.current_seq;
+        const hasServerAck = method === 'message.pull'
+            ? Object.prototype.hasOwnProperty.call(response, 'server_ack_seq')
+            : Boolean(cursor && Object.prototype.hasOwnProperty.call(cursor, 'current_seq'));
+        const parsedServerAck = hasServerAck ? nonNegativeSafeSequenceHint(serverAckRaw) : null;
+        const serverAckSeq = parsedServerAck ?? 0;
+        const retentionFloor = method === 'message.pull'
+            ? positiveSafeSequenceHint(response.retention_floor_seq)
+            : Math.max(positiveSafeSequenceHint(response.retention_floor_message_seq), positiveSafeSequenceHint(response.retention_floor_seq), positiveSafeSequenceHint(cursor?.retention_floor_seq));
+        const visibilityFloor = method === 'group.pull'
+            ? Math.max(positiveSafeSequenceHint(cursor?.join_seq), Math.max(0, positiveSafeSequenceHint(response.earliest_available_message_seq) - 1))
+            : 0;
+        let publishedCount = 0;
+        let committed = false;
+        try {
+            for (const rawMessage of messages) {
+                this.ensurePullOperationCurrent();
+                const seq = positiveSafeSequenceHint(rawMessage.seq);
+                if (method === 'message.pull') {
+                    const appEvent = this.p2pAppEventForMessage(rawMessage);
+                    if (await this.publishPulledMessage(appEvent.event, ns, seq, appEvent.payload, false)) {
+                        publishedCount += 1;
+                    }
+                    this.ensurePullOperationCurrent();
+                    continue;
+                }
+                const message = normalizeGroupMentionMode(rawMessage);
+                if (this.recallEventFromGroupMessage(message)) {
+                    if (await this.publishGroupRecallTombstone(groupId, seq, message)) {
+                        this.ensurePullOperationCurrent();
+                        this.markPublishedSeq(ns, seq);
+                        publishedCount += 1;
+                    }
+                }
+                else if (await this.publishPulledMessage('group.message_created', ns, seq, message, false)) {
+                    this.ensurePullOperationCurrent();
+                    publishedCount += 1;
+                }
+            }
+            this.ensurePullOperationCurrent();
+            if (messages.length > 0)
+                client._seqTracker.onPullResult(ns, messages, afterSeq);
+            const commitTarget = Math.max(client._seqTracker.getContiguousSeq(ns), retentionFloor, visibilityFloor, deferredServerCursor);
+            if (commitTarget > client._seqTracker.getContiguousSeq(ns)) {
+                client._seqTracker.forceContiguousSeq(ns, commitTarget);
+            }
+            if (client._seqTracker.getContiguousSeq(ns) !== pageContigBefore) {
+                this.ensurePullOperationCurrent();
+                await this.drainOrderedMessages(ns, undefined, false, false);
+                this.ensurePullOperationCurrent();
+                await client._commitSeqTrackerState(ns);
+            }
+            committed = true;
+        }
+        catch (exc) {
+            if (this.isPullOperationCurrent() && !committed && typeof client._seqTracker.restoreNamespaceSnapshot === 'function') {
+                client._seqTracker.restoreNamespaceSnapshot(ns, pageTrackerSnapshot);
+                this.dropSeqTrackerPending(ns);
+            }
+            throw exc;
+        }
+        this.ensurePullOperationCurrent();
+        const committedAck = client._seqTracker.getContiguousSeq(ns);
+        if (deferredServerCursor > 0 && committedAck >= deferredServerCursor) {
+            coordinator.clearForwardCursor(ns, committedAck);
+        }
+        if (hasServerAck && parsedServerAck !== null && serverAckSeq > committedAck) {
+            coordinator.recordForwardCursor(ns, serverAckSeq, committedAck);
+        }
+        if (hasServerAck && parsedServerAck !== null && serverAckSeq >= deferredForwardAck) {
+            coordinator.clearForwardAck(ns, serverAckSeq);
+            if (method === 'message.pull') {
+                this.onP2PV2AckSucceeded(serverAckSeq, pageInlineGeneration);
+            }
+            else {
+                this.onGroupV2AckSucceeded(groupId, serverAckSeq, pageInlineGeneration);
+            }
+        }
+        const contigAdvanced = committedAck > pageContigBefore;
+        const knownServerAck = hasServerAck ? serverAckSeq : deferredServerCursor;
+        if (committedAck > 0
+            && ((hasServerAck && committedAck > serverAckSeq)
+                || (contigAdvanced && committedAck > knownServerAck))) {
+            coordinator.recordForwardAck(ns, committedAck);
+        }
+        const pendingAckSeq = Number(coordinator.pendingForwardAck(ns, committedAck) ?? 0);
+        if (pendingAckSeq > 0) {
+            const ackMethod = method === 'message.pull' ? 'message.ack' : 'group.ack_messages';
+            const clampedAckSeq = this.clampAckSeq(ackMethod, ackMethod === 'message.ack' ? 'seq' : 'msg_seq', ns, pendingAckSeq);
+            if (clampedAckSeq < pendingAckSeq) {
+                throw new Error(`${ackMethod} cannot confirm pending Forward watermark ${pendingAckSeq}`);
+            }
+            this.ensurePullOperationCurrent();
+            await this.confirmPlainForwardAck(ns, ackMethod, pendingAckSeq, groupId);
+        }
+        return { rawCount: messages.length, publishedCount };
+    }
     resetInlineAckState() {
         this.inlineAckGeneration += 1;
+        void this.runtime.client._rpcPipeline?.invalidatePulls?.();
         this.pendingP2PInlineAcks = null;
         this.pendingGroupInlineAcks = null;
         this.pendingGroupInlineAckNamespaces = null;
         this.realtimeSyncing = null;
+        this.pendingGroupPullUpper = null;
+        this.onlineUnreadHintTargets = null;
+        this.onlineUnreadHintTasks = null;
         this.realtimeTailHeads = null;
     }
     inlineGenerationIsCurrent(generation) {
@@ -68,6 +280,15 @@ export class MessageDeliveryEngine {
     captureGroupInlineAckGeneration() {
         return this.pendingGroupInlineAcks?.size ? this.inlineAckGeneration : null;
     }
+    async waitForPendingInlineCommit(ns, seq) {
+        const pending = this.pendingP2PInlineAcks?.get(ns);
+        if (pending && (pending.committed || pending.seq > seq))
+            return;
+        const queues = this.runtime.client._pushProcessQueues;
+        const processing = queues?.get(ns);
+        if (processing)
+            await processing;
+    }
     pendingInlineAckNamespaceCount() {
         return (this.pendingP2PInlineAcks?.size ?? 0) + (this.pendingGroupInlineAcks?.size ?? 0);
     }
@@ -90,6 +311,50 @@ export class MessageDeliveryEngine {
     endRealtimeSync(ns) {
         this.realtimeSyncing?.delete(ns);
     }
+    hasPendingPull(ns) {
+        return (this.pendingGroupPullUpper?.get(ns) ?? 0) > 0;
+    }
+    onPullGateIdle(ns) {
+        if (!ns)
+            return;
+        if (ns.startsWith('p2p:')) {
+            this.runtime.client._schedulePendingP2pPullIfNeeded?.(ns, 'pull-gate-idle');
+            return;
+        }
+        this.schedulePendingGroupPullIfNeeded(ns, 'pull-gate-idle');
+    }
+    recordPendingGroupPull(ns, seq) {
+        if (!ns || !Number.isSafeInteger(seq) || seq <= 0)
+            return;
+        const pending = this.pendingGroupPullUpper ?? new Map();
+        this.pendingGroupPullUpper = pending;
+        pending.set(ns, Math.max(pending.get(ns) ?? 0, seq));
+    }
+    schedulePendingGroupPullIfNeeded(ns, reason) {
+        const pending = this.pendingGroupPullUpper;
+        if (!pending)
+            return false;
+        const upper = pending.get(ns) ?? 0;
+        if (upper <= 0) {
+            pending.delete(ns);
+            return false;
+        }
+        const client = this.runtime.client;
+        const contiguous = client._seqTracker.getContiguousSeq(ns);
+        if (upper <= contiguous) {
+            pending.delete(ns);
+            client._clientLog.debug(`Group pending pull upper already covered: ns=${ns}, upper_seq=${upper}, contiguous=${contiguous}, reason=${reason}`);
+            return false;
+        }
+        if (client.state !== ConnectionState.READY || client._closing
+            || client._rpcPipeline?.hasPullActivity?.(ns, false))
+            return false;
+        pending.delete(ns);
+        const groupId = ns.slice('group:'.length);
+        client._clientLog.debug(`Group pending push follow-up pull scheduled: ns=${ns}, upper_seq=${upper}, reason=${reason}`);
+        client._safeAsync(this.onRawGroupV2MessageCreated({ group_id: groupId, seq: upper }));
+        return true;
+    }
     prunePushedSeqs(ns) {
         const client = this.runtime.client;
         const pushed = client._pushedSeqs.get(ns);
@@ -132,12 +397,15 @@ export class MessageDeliveryEngine {
     }
     async publishOrderedQueueItem(ns, event, seq, payload, source, pullResponse = false) {
         const client = this.runtime.client;
+        this.ensurePullOperationCurrent();
         if (event === 'group.changed' && this.isGroupEventNamespace(ns)) {
             await this.publishOrderedGroupChanged(payload, source);
+            this.ensurePullOperationCurrent();
             return;
         }
         if (event === 'message.recalled') {
             await this.publishMessageRecallTombstone(seq, payload);
+            this.ensurePullOperationCurrent();
             return;
         }
         if (pullResponse) {
@@ -150,6 +418,7 @@ export class MessageDeliveryEngine {
             if (isPromiseLike(published))
                 await published;
         }
+        this.ensurePullOperationCurrent();
     }
     async publishOrderedGroupChanged(payload, source = 'ordered') {
         const client = this.runtime.client;
@@ -925,7 +1194,7 @@ export class MessageDeliveryEngine {
         // 在旧 seq tracking / ordered publish 之前转入前台 Tail 协调器。
         const inlinePresent = Object.prototype.hasOwnProperty.call(msg, 'inline_message');
         const legacyPushSeq = this.realtimeHeadSeq(msg.seq, inlinePresent);
-        if (client._v2Session && client._aid && msg.seq !== undefined && msg.seq !== null) {
+        if (client._v2Session && client._aid && (msg.seq !== undefined && msg.seq !== null || inlinePresent)) {
             if (legacyPushSeq === null) {
                 if (inlinePresent)
                     await this.recoverInvalidP2PRealtimeHead(`p2p:${client._aid}`, msg.seq);
@@ -1025,7 +1294,7 @@ export class MessageDeliveryEngine {
         // 不能让 payload 路径直接推进旧 ordered publish 状态。
         const inlinePresent = Object.prototype.hasOwnProperty.call(msg, 'inline_message');
         const legacyPushSeq = this.realtimeHeadSeq(seq, inlinePresent);
-        if (client._v2Session && groupId && seq !== undefined && seq !== null) {
+        if (client._v2Session && groupId && (seq !== undefined && seq !== null || inlinePresent)) {
             if (legacyPushSeq === null) {
                 if (inlinePresent)
                     await this.recoverInvalidGroupRealtimeHead(groupId, `group:${groupId}`, seq);
@@ -1139,20 +1408,14 @@ export class MessageDeliveryEngine {
         client._clientLog.debug(`P2P message gap fill start: after_seq=${afterSeq}`);
         let filled = 0;
         try {
-            const operation = () => client._pullV2(afterSeq, 50, { skipAutoAck: true, gateLocked: true });
+            // Gap Fill 本身就是 Forward Pull，必须沿用协调器的完整事务：
+            // 原始页提交成功后由协调器负责 Piggyback/终端 ACK。
+            const operation = () => client._pullV2(afterSeq, 50, { gateLocked: true });
             const messages = client._rpcPipeline
                 ? await client._rpcPipeline.runPullSerialized(client._rpcPipeline.pullGateKeyForCall('message.pull', { after_seq: afterSeq, limit: 50 }), operation, true)
                 : await client._withBackgroundRpc(operation);
             filled = messages.length;
             this.prunePushedSeqs(ns);
-            if (client._seqTracker.getContiguousSeq(ns) !== afterSeq) {
-                await this.drainOrderedMessages(ns, undefined, true);
-                this.persistSeq(ns);
-            }
-            const contig = client._seqTracker.getContiguousSeq(ns);
-            if (contig > 0 && contig !== afterSeq) {
-                await client._withBackgroundRpc(() => client._ackV2(contig));
-            }
             client._clientLog.debug(`P2P message gap fill done: after_seq=${afterSeq}, filled=${filled}`);
         }
         catch (exc) {
@@ -1160,6 +1423,7 @@ export class MessageDeliveryEngine {
         }
         finally {
             client._gapFillDone.delete(dedupKey);
+            client._schedulePendingP2pPullIfNeeded?.(ns, 'gap-fill-complete');
         }
     }
     async fillGroupGap(groupId) {
@@ -1184,10 +1448,6 @@ export class MessageDeliveryEngine {
                 : await client._withBackgroundRpc(operation);
             filled = messages.length;
             this.prunePushedSeqs(ns);
-            if (client._seqTracker.getContiguousSeq(ns) !== afterSeq) {
-                await this.drainOrderedMessages(ns, undefined, true);
-                this.persistSeq(ns);
-            }
             client._clientLog.debug(`group message gap fill done: group=${groupId}, after_seq=${afterSeq}, filled=${filled}`);
         }
         catch (exc) {
@@ -1198,9 +1458,41 @@ export class MessageDeliveryEngine {
             if (filled > 0 && client._seqTracker.getContiguousSeq(ns) > afterSeq) {
                 void this.fillGroupGap(groupId);
             }
+            this.schedulePendingGroupPullIfNeeded(ns, 'gap-fill-complete');
         }
     }
-    async fillGroupEventGap(groupId) {
+    scheduleRealtimeWindowForward(ns, groupId = '') {
+        const client = this.runtime.client;
+        const state = this.syncState(ns);
+        if (client._sessionOptions?.background_sync === false
+            || state.ack >= state.tail - 1)
+            return;
+        groupId = String(groupId ?? '').trim();
+        if (!groupId && (!client._aid || ns !== `p2p:${client._aid}`))
+            return;
+        const key = `${groupId ? 'group' : 'p2p'}_realtime_window_forward:${ns}`;
+        if (client._gapFillDone.has(key))
+            return;
+        client._gapFillDone.set(key, Date.now());
+        client._safeAsync(Promise.resolve().then(async () => {
+            try {
+                if (client._sessionOptions?.background_sync === false
+                    || client.state !== ConnectionState.READY || client._closing)
+                    return;
+                const live = this.syncState(ns);
+                if (live.ack >= live.tail - 1)
+                    return;
+                if (groupId)
+                    await this.fillGroupGap(groupId);
+                else
+                    await this.fillP2pGap();
+            }
+            finally {
+                client._gapFillDone.delete(key);
+            }
+        }));
+    }
+    async fillGroupEventGap(groupId, options = {}) {
         const client = this.runtime.client;
         if (client._sessionOptions?.background_sync === false)
             return;
@@ -1208,32 +1500,49 @@ export class MessageDeliveryEngine {
         if (!groupId)
             return;
         const ns = `group_event:${groupId}`;
-        const afterSeq = client._seqTracker.getContiguousSeq(ns);
-        const dedupKey = `group_evt:${groupId}:${afterSeq}`;
+        const requestedAfterSeq = Number(options.afterSeq ?? 0);
+        const afterSeq = Number.isSafeInteger(requestedAfterSeq) && requestedAfterSeq > 0
+            ? requestedAfterSeq
+            : client._seqTracker.getContiguousSeq(ns);
+        const singlePage = options.singlePage === true;
+        const dedupKey = `group_event_pull:${ns}`;
         if (client._gapFillDone.has(dedupKey))
             return;
-        const token = client._tryAcquirePullGate(ns);
-        if (token === null) {
-            client._clientLog.debug(`group event gap fill skipped: pull in-flight group=${groupId}`);
-            return;
+        let legacyGateToken = null;
+        if (!client._rpcPipeline) {
+            const acquire = client._tryAcquirePullGate;
+            if (typeof acquire === 'function') {
+                legacyGateToken = acquire.call(client, ns);
+                if (legacyGateToken === null)
+                    return;
+            }
         }
         client._gapFillDone.set(dedupKey, Date.now());
         let filled = 0;
+        let continuationAfterSeq = 0;
         try {
             let nextAfterSeq = afterSeq;
-            const maxPages = 100;
+            const maxPages = singlePage ? 1 : 100;
             let pageCount = 0;
             while (pageCount < maxPages) {
                 pageCount += 1;
                 client._clientLog.debug(`group event gap fill start: group=${groupId}, after_seq=${nextAfterSeq}`);
-                const result = await client.call('group.pull_events', {
+                const request = {
                     group_id: groupId,
                     after_event_seq: nextAfterSeq,
                     device_id: client._deviceId,
                     limit: 50,
                     _pull_gate_locked: true,
                     _rpc_background: true,
-                });
+                };
+                let result;
+                if (client._rpcPipeline) {
+                    const pullKey = client._rpcPipeline.pullGateKeyForCall('group.pull_events', request);
+                    result = await client._rpcPipeline.runPullSerialized(pullKey, () => client.call('group.pull_events', request), true);
+                }
+                else {
+                    result = await client.call('group.pull_events', request);
+                }
                 if (!isJsonObject(result))
                     return;
                 const events = result.events;
@@ -1293,16 +1602,28 @@ export class MessageDeliveryEngine {
                 }
                 if (eventObjects.length > 0 && ackContig > 0 && ackContig !== pageContigBefore) {
                     const ackSeq = this.clampAckSeq('group.ack_events', 'event_seq', ns, ackContig);
-                    client._transport.call('group.ack_events', {
-                        group_id: groupId,
-                        event_seq: ackSeq,
-                        device_id: client._deviceId,
-                        slot_id: client._slotId,
-                    }, undefined, undefined, true).catch((e) => {
+                    try {
+                        const ackPromise = client._transport.call('group.ack_events', {
+                            group_id: groupId,
+                            event_seq: ackSeq,
+                            device_id: client._deviceId,
+                            slot_id: client._slotId,
+                        }, undefined, undefined, true);
+                        if (singlePage)
+                            await ackPromise;
+                        else
+                            ackPromise.catch((e) => {
+                                client._clientLog.debug(`group event auto-ack failed: group=${groupId} ${formatDeliveryError(e)}`);
+                            });
+                    }
+                    catch (e) {
                         client._clientLog.debug(`group event auto-ack failed: group=${groupId} ${formatDeliveryError(e)}`);
-                    });
+                    }
                 }
                 const nextAfter = Math.max(eventSeqs.length > 0 ? Math.max(...eventSeqs) : nextAfterSeq, nextAfterSeq);
+                if (singlePage && result.has_more === true && nextAfter > nextAfterSeq) {
+                    continuationAfterSeq = nextAfter;
+                }
                 if (eventObjects.length === 0 || nextAfter <= nextAfterSeq || result.has_more === false)
                     break;
                 nextAfterSeq = nextAfter;
@@ -1317,12 +1638,32 @@ export class MessageDeliveryEngine {
         }
         finally {
             client._gapFillDone.delete(dedupKey);
-            client._releasePullGate(ns, token);
-            if (filled > 0 && client._seqTracker.getContiguousSeq(ns) > afterSeq) {
+            if (legacyGateToken !== null && typeof client._releasePullGate === 'function') {
+                client._releasePullGate(ns, legacyGateToken);
+            }
+            if (singlePage && continuationAfterSeq > afterSeq) {
+                this.enqueueOnlineUnreadEventHint({
+                    group_id: groupId,
+                    _online_hint_after_event_seq: continuationAfterSeq,
+                });
+            }
+            else if (!singlePage && filled > 0 && client._seqTracker.getContiguousSeq(ns) > afterSeq) {
                 void this.fillGroupEventGap(groupId);
             }
         }
     }
+    enqueueOnlineUnreadEventHint(data) {
+        const client = this.runtime.client;
+        const groupId = String(data.group_id ?? '').trim();
+        if (!groupId || client._sessionOptions?.background_sync === false)
+            return;
+        const rawAfter = Number(data._online_hint_after_event_seq ?? 0);
+        const afterSeq = Number.isSafeInteger(rawAfter) && rawAfter > 0 ? rawAfter : 0;
+        client._safeAsync(this.fillGroupEventGap(groupId, {
+            afterSeq,
+            singlePage: true,
+        }));
+    }
     async handleGroupChangedEventSeq(data, groupId) {
         const client = this.runtime.client;
         groupId = String(groupId ?? '').trim();
@@ -1339,10 +1680,8 @@ export class MessageDeliveryEngine {
                 client._clientLog.debug(`group.changed online unread hint skipped: group=${groupId} background_sync=false`);
                 return;
             }
-            client._clientLog.debug(`group.changed online unread hint triggering gap fill: group=${groupId}, event_seq=${eventSeq}`);
-            this.fillGroupEventGap(groupId).catch((exc) => {
-                client._clientLog.warn(`background gap fill trigger failed: ${formatDeliveryError(exc)}`);
-            });
+            client._clientLog.debug(`group.changed online unread hint triggering event Forward: group=${groupId}, event_seq=${eventSeq}`);
+            this.enqueueOnlineUnreadEventHint(data);
             return;
         }
         if (this.isSelfJoinGroupChanged(data)) {
@@ -1606,16 +1945,49 @@ export class MessageDeliveryEngine {
         if (!this.pendingGroupInlineAcks?.size || !this.inlineGenerationIsCurrent(generation)
             || !Number.isSafeInteger(requestedSeq) || requestedSeq <= 0)
             return;
-        let actualAckSeq = requestedSeq;
+        const actualAckSeq = this.resolveGroupPullAckSeq(result, requestedSeq);
+        this.onGroupV2AckSucceeded(groupId, actualAckSeq, generation);
+    }
+    resolveGroupPullAckSeq(result, requestedSeq) {
+        if (!Number.isSafeInteger(requestedSeq) || requestedSeq <= 0)
+            return 0;
         const response = isJsonObject(result) ? result : null;
-        const cursor = response && isJsonObject(response.cursor)
-            ? response.cursor
-            : null;
-        if (cursor && Object.prototype.hasOwnProperty.call(cursor, 'current_seq')) {
-            const raw = cursor.current_seq;
-            actualAckSeq = typeof raw === 'number' && Number.isSafeInteger(raw) && raw >= 0 ? raw : 0;
+        if (!response || !Object.prototype.hasOwnProperty.call(response, 'cursor'))
+            return 0;
+        const cursor = response.cursor;
+        const cursorObject = isJsonObject(cursor) ? cursor : null;
+        if (!cursorObject || !Object.prototype.hasOwnProperty.call(cursorObject, 'current_seq'))
+            return 0;
+        const raw = cursorObject.current_seq;
+        return typeof raw === 'number' && Number.isSafeInteger(raw) && raw >= 0 ? raw : 0;
+    }
+    resolveForwardAckSeq(result, requestedSeq) {
+        if (!Number.isSafeInteger(requestedSeq) || requestedSeq <= 0)
+            return 0;
+        const response = isJsonObject(result) ? result : null;
+        // 旧服务端成功响应可能不带累计水位字段；RPC 已成功，兼容按请求水位处理。
+        if (!response)
+            return requestedSeq;
+        let raw;
+        if (Object.prototype.hasOwnProperty.call(response, 'effective_ack_seq'))
+            raw = response.effective_ack_seq;
+        else if (Object.prototype.hasOwnProperty.call(response, 'ack_seq'))
+            raw = response.ack_seq;
+        else if (Object.prototype.hasOwnProperty.call(response, 'cursor')) {
+            const cursor = response.cursor;
+            const cursorObject = isJsonObject(cursor) ? cursor : null;
+            if (cursorObject) {
+                if (!Object.prototype.hasOwnProperty.call(cursorObject, 'current_seq'))
+                    return 0;
+                raw = cursorObject.current_seq;
+            }
+            else {
+                raw = cursor;
+            }
         }
-        this.onGroupV2AckSucceeded(groupId, actualAckSeq, generation);
+        else
+            return requestedSeq;
+        return typeof raw === 'number' && Number.isSafeInteger(raw) && raw >= 0 ? raw : 0;
     }
     resolveActualAckSeq(result, requestedSeq) {
         if (!Number.isSafeInteger(requestedSeq) || requestedSeq <= 0)
@@ -1649,22 +2021,31 @@ export class MessageDeliveryEngine {
         const before = this.syncState(ns);
         const order = forceTail ? ['tail'] : typeof client._seqTracker.planRealtimeSync === 'function'
             ? client._seqTracker.planRealtimeSync(ns, pushSeq, pageLimit)
-            : (pushSeq > before.ack ? ['tail'] : []);
+            : (() => {
+                const gap = pushSeq - before.ack;
+                if (gap <= 0)
+                    return before.ack < before.tail - 1 ? ['forward'] : [];
+                return gap <= pageLimit * 2 ? ['forward'] : ['tail'];
+            })();
+        // Planner 依据 S-A 选路；H 已覆盖 S 也不代表 A 已连续提交，仍需前台 Forward。
+        const headForward = order.length === 1 && order[0] === 'forward' && pushSeq > before.ack;
         let result = { messages: [], raw_count: 0 };
         let tailHead = null;
-        const run = async (request, background) => {
+        const run = async (request, background, forceForward = false) => {
             const invoke = async () => {
                 const live = this.syncState(ns);
                 if (request.window_mode === 'tail' && !forceTail && typeof client._seqTracker.getSyncState === 'function' && pushSeq <= live.head)
                     return { messages: [], raw_count: 0 };
-                if (request.window_mode !== 'tail' && live.ack >= live.tail - 1)
+                if (request.window_mode !== 'tail' && !forceForward && !headForward && live.ack >= live.tail - 1)
+                    return { messages: [], raw_count: 0 };
+                if (request.window_mode !== 'tail' && headForward && live.ack >= pushSeq)
                     return { messages: [], raw_count: 0 };
                 if (request.window_mode === 'tail') {
                     const tailResult = await client._v2E2EE.pullV2TailInternal({
                         window_mode: 'tail',
                         after_seq: live.ack,
                         limit: pageLimit,
-                    });
+                    }, true);
                     tailHead = this.syncState(ns).head;
                     return tailResult;
                 }
@@ -1686,8 +2067,24 @@ export class MessageDeliveryEngine {
         const state = this.syncState(ns);
         const needsForward = state.ack < state.tail - 1;
         const backgroundEnabled = client._sessionOptions?.background_sync !== false;
-        if (backgroundEnabled && (order.length === 1 && order[0] === 'forward' || (order.length === 1 && order[0] === 'tail' && needsForward))) {
-            result = await run({ after_seq: state.ack, limit: pageLimit, ...(order[0] === 'tail' ? { max_pages: 1 } : {}) }, true);
+        // Tail 期间到达的新 Push 可能只更新 maxSeen 而没有扩展 Tail 窗口。
+        const maxSeen = Number(client._seqTracker.getMaxSeenSeq?.(ns) ?? 0);
+        const tailMissedDuringPull = tailHead !== null && maxSeen > state.head;
+        const tailForward = tailHead !== null && (needsForward || tailMissedDuringPull);
+        const backgroundWindowForward = (order.length === 1 && order[0] === 'forward' && !headForward)
+            || (order.length === 1 && order[0] === 'tail' && tailHead === null && needsForward);
+        const foregroundForward = headForward || tailForward;
+        if (foregroundForward || backgroundEnabled && backgroundWindowForward) {
+            const forwardTarget = Math.max(headForward ? pushSeq : 0, tailForward || backgroundWindowForward ? state.tail - 1 : 0, tailMissedDuringPull ? maxSeen : 0);
+            const requiredPages = Math.max(1, Math.ceil(Math.max(0, forwardTarget - state.ack) / pageLimit));
+            result = await run({
+                after_seq: state.ack,
+                limit: pageLimit,
+                ...(headForward ? { max_pages: Math.max(2, requiredPages) } : order[0] === 'tail' ? { max_pages: requiredPages } : {}),
+            }, !foregroundForward, headForward || tailMissedDuringPull);
+        }
+        if (tailHead !== null && this.syncState(ns).ack < this.syncState(ns).tail - 1) {
+            this.scheduleRealtimeWindowForward(ns);
         }
         if (tailHead !== null) {
             this.markRealtimeTailCompleted(result, tailHead);
@@ -1699,15 +2096,24 @@ export class MessageDeliveryEngine {
         const before = this.syncState(ns);
         const order = forceTail ? ['tail'] : typeof client._seqTracker.planRealtimeSync === 'function'
             ? client._seqTracker.planRealtimeSync(ns, pushSeq, pageLimit)
-            : (pushSeq > before.ack ? ['tail'] : []);
+            : (() => {
+                const gap = pushSeq - before.ack;
+                if (gap <= 0)
+                    return before.ack < before.tail - 1 ? ['forward'] : [];
+                return gap <= pageLimit * 2 ? ['forward'] : ['tail'];
+            })();
+        // Planner 依据 S-A 选路；H 已覆盖 S 也不代表 A 已连续提交，仍需前台 Forward。
+        const headForward = order.length === 1 && order[0] === 'forward' && pushSeq > before.ack;
         let result = { messages: [], raw_count: 0 };
         let tailHead = null;
-        const run = async (request, background) => {
+        const run = async (request, background, forceForward = false) => {
             const invoke = async () => {
                 const live = this.syncState(ns);
                 if (request.window_mode === 'tail' && !forceTail && typeof client._seqTracker.getSyncState === 'function' && pushSeq <= live.head)
                     return { messages: [], raw_count: 0 };
-                if (request.window_mode !== 'tail' && live.ack >= live.tail - 1)
+                if (request.window_mode !== 'tail' && !forceForward && !headForward && live.ack >= live.tail - 1)
+                    return { messages: [], raw_count: 0 };
+                if (request.window_mode !== 'tail' && headForward && live.ack >= pushSeq)
                     return { messages: [], raw_count: 0 };
                 if (request.window_mode === 'tail') {
                     const tailResult = await client._v2E2EE.pullGroupV2TailInternal({
@@ -1715,7 +2121,7 @@ export class MessageDeliveryEngine {
                         window_mode: 'tail',
                         after_seq: live.ack,
                         limit: pageLimit,
-                    });
+                    }, true);
                     tailHead = this.syncState(ns).head;
                     return tailResult;
                 }
@@ -1736,15 +2142,30 @@ export class MessageDeliveryEngine {
         const state = this.syncState(ns);
         const needsForward = state.ack < state.tail - 1;
         const backgroundEnabled = client._sessionOptions?.background_sync !== false;
-        if (backgroundEnabled && (order.length === 1 && order[0] === 'forward' || (order.length === 1 && order[0] === 'tail' && needsForward))) {
-            result = await run({ after_seq: state.ack, limit: pageLimit, ...(order[0] === 'tail' ? { max_pages: 1 } : {}) }, true);
+        const maxSeen = Number(client._seqTracker.getMaxSeenSeq?.(ns) ?? 0);
+        const tailMissedDuringPull = tailHead !== null && maxSeen > state.head;
+        const tailForward = tailHead !== null && (needsForward || tailMissedDuringPull);
+        const backgroundWindowForward = (order.length === 1 && order[0] === 'forward' && !headForward)
+            || (order.length === 1 && order[0] === 'tail' && tailHead === null && needsForward);
+        const foregroundForward = headForward || tailForward;
+        if (foregroundForward || backgroundEnabled && backgroundWindowForward) {
+            const forwardTarget = Math.max(headForward ? pushSeq : 0, tailForward || backgroundWindowForward ? state.tail - 1 : 0, tailMissedDuringPull ? maxSeen : 0);
+            const requiredPages = Math.max(1, Math.ceil(Math.max(0, forwardTarget - state.ack) / pageLimit));
+            result = await run({
+                after_seq: state.ack,
+                limit: pageLimit,
+                ...(headForward ? { max_pages: Math.max(2, requiredPages) } : order[0] === 'tail' ? { max_pages: requiredPages } : {}),
+            }, !foregroundForward, headForward || tailMissedDuringPull);
+        }
+        if (tailHead !== null && this.syncState(ns).ack < this.syncState(ns).tail - 1) {
+            this.scheduleRealtimeWindowForward(ns, groupId);
         }
         if (tailHead !== null) {
             this.markRealtimeTailCompleted(result, tailHead);
         }
         return result;
     }
-    async runP2PForwardRecovery(ns, pageLimit) {
+    async runP2PForwardRecovery(ns, pageLimit, background = false) {
         const client = this.runtime.client;
         const request = { after_seq: this.syncState(ns).ack, limit: pageLimit, max_pages: 1 };
         const invoke = async () => {
@@ -1755,20 +2176,22 @@ export class MessageDeliveryEngine {
         if (!client._rpcPipeline)
             return await invoke();
         const key = client._rpcPipeline.pullGateKeyForCall('message.pull', request);
-        return await client._rpcPipeline.runPullSerialized(key, invoke, true);
+        return await client._rpcPipeline.runPullSerialized(key, invoke, background);
     }
-    async runGroupForwardRecovery(groupId, ns, pageLimit) {
+    async runGroupForwardRecovery(groupId, ns, pageLimit, background = false, throughSeq = 0) {
         const client = this.runtime.client;
-        const request = { group_id: groupId, after_seq: this.syncState(ns).ack, limit: pageLimit, max_pages: 1 };
+        const ack = this.syncState(ns).ack;
+        const maxPages = Math.max(1, Math.ceil(Math.max(0, throughSeq - ack) / pageLimit));
+        const request = { group_id: groupId, after_seq: ack, limit: pageLimit, max_pages: maxPages };
         const invoke = async () => {
             const after = this.syncState(ns).ack;
-            const messages = await client._pullGroupV2(groupId, after, pageLimit, { gateLocked: true, maxPages: 1 });
+            const messages = await client._pullGroupV2(groupId, after, pageLimit, { gateLocked: true, maxPages });
             return { messages, raw_count: messages.length };
         };
         if (!client._rpcPipeline)
             return await invoke();
         const key = client._rpcPipeline.pullGateKeyForCall('group.pull', request);
-        return await client._rpcPipeline.runPullSerialized(key, invoke, true);
+        return await client._rpcPipeline.runPullSerialized(key, invoke, background);
     }
     syncState(ns) {
         const tracker = this.runtime.client._seqTracker;
@@ -2131,7 +2554,7 @@ export class MessageDeliveryEngine {
             }
             if (!this.inlineGenerationIsCurrent(generation))
                 return false;
-            client._commitSeqTrackerState(ns);
+            await client._commitSeqTrackerState(ns);
             if (!this.inlineGenerationIsCurrent(generation))
                 return false;
             this.markPublishedSeq(ns, seq);
@@ -2306,13 +2729,18 @@ export class MessageDeliveryEngine {
         if (!this.pendingP2PInlineAcks?.size || !this.inlineGenerationIsCurrent(generation)
             || !Number.isSafeInteger(requestedSeq) || requestedSeq <= 0)
             return;
-        let actualAckSeq = requestedSeq;
+        const actualAckSeq = this.resolveP2PPullAckSeq(result, requestedSeq);
+        this.onP2PV2AckSucceeded(actualAckSeq, generation);
+    }
+    resolveP2PPullAckSeq(result, requestedSeq) {
+        if (!Number.isSafeInteger(requestedSeq) || requestedSeq <= 0)
+            return 0;
         const response = isJsonObject(result) ? result : null;
         if (response && Object.prototype.hasOwnProperty.call(response, 'server_ack_seq')) {
             const raw = response.server_ack_seq;
-            actualAckSeq = typeof raw === 'number' && Number.isSafeInteger(raw) && raw >= 0 ? raw : 0;
+            return typeof raw === 'number' && Number.isSafeInteger(raw) && raw >= 0 ? raw : 0;
         }
-        this.onP2PV2AckSucceeded(actualAckSeq, generation);
+        return 0;
     }
     async onV2PushNotification(data, expectedVersion, inlineGeneration) {
         const client = this.runtime.client;
@@ -2325,10 +2753,16 @@ export class MessageDeliveryEngine {
         const ns = client._aid ? `p2p:${client._aid}` : '';
         if (!pushData || !ns)
             return;
+        if (String(pushData.kind ?? '').trim() === 'message.online_unread_hint') {
+            if (client._sessionOptions?.background_sync === false)
+                return;
+            this.enqueueOnlineUnreadP2pHint(pushData);
+            return;
+        }
         const inlinePresent = Object.prototype.hasOwnProperty.call(pushData, 'inline_message');
         const pushSeq = this.realtimeHeadSeq(rawPushSeq, inlinePresent);
         if (pushSeq === null) {
-            if (inlinePresent && rawPushSeq !== undefined && rawPushSeq !== null) {
+            if (inlinePresent) {
                 await this.recoverInvalidP2PRealtimeHead(ns, rawPushSeq);
             }
             return;
@@ -2350,34 +2784,26 @@ export class MessageDeliveryEngine {
             catch (exc) {
                 if (inlineGeneration !== undefined && !this.inlineGenerationIsCurrent(inlineGeneration))
                     return;
-                client._clientLog.warn(`V2 P2P inline push rejected, falling back to Tail: seq=${pushSeq} err=${formatDeliveryError(exc)}`);
+                client._clientLog.warn(`V2 P2P inline push rejected, falling back to sync planner: seq=${pushSeq} err=${formatDeliveryError(exc)}`);
             }
         const before = this.syncState(ns);
         client._seqTracker.updateMaxSeen(ns, pushSeq);
-        const hasGap = before.ack < before.tail - 1;
-        if (pushSeq <= before.head && !hasGap && !inlinePresent) {
+        if (pushSeq <= before.ack && before.ack >= before.tail - 1) {
             client._clientLog.debug(`V2 P2P duplicate push ignored: seq=${pushSeq} A/T/H=${JSON.stringify(before)}`);
             this.retryPendingP2PInlineAck(ns, pushSeq, 'covered inline push');
             return;
         }
-        if (!this.beginRealtimeSync(ns)) {
-            client._clientLog.debug(`V2 P2P push coalesced into in-flight realtime sync: ns=${ns} seq=${pushSeq}`);
+        const pullActive = client._rpcPipeline?.hasPullActivity?.(ns) === true;
+        if (pullActive || !this.beginRealtimeSync(ns)) {
+            client._recordPendingP2pPull(ns, pushSeq);
+            client._clientLog.debug(`V2 P2P push queued behind in-flight realtime sync: ns=${ns} seq=${pushSeq}`);
             return;
         }
         try {
-            const syncResult = await this.runP2PRealtimeSync(ns, pushSeq, 50, inlinePresent && !inlineConsumed);
+            await this.runP2PRealtimeSync(ns, pushSeq, 50, false);
             if (inlineGeneration !== undefined && !this.inlineGenerationIsCurrent(inlineGeneration))
                 return;
-            const tailHead = this.realtimeTailHead(syncResult);
-            const maxSeen = Number(client._seqTracker.getMaxSeenSeq?.(ns) ?? 0);
-            if (client._sessionOptions?.background_sync !== false
-                && tailHead !== null && Number.isSafeInteger(maxSeen) && maxSeen > tailHead) {
-                await this.runP2PForwardRecovery(ns, 50).catch((exc) => {
-                    client._clientLog.warn(`V2 P2P stale Tail Forward recovery failed: ${formatDeliveryError(exc)}`);
-                });
-                if (inlineGeneration !== undefined && !this.inlineGenerationIsCurrent(inlineGeneration))
-                    return;
-            }
+            // Tail 期间新到达的 Push 已由 realtime sync 在同一周期内补至多一页 Forward。
         }
         catch (exc) {
             client._clientLog.warn(`V2 P2P push auto-sync failed: ${formatDeliveryError(exc)}`);
@@ -2385,6 +2811,7 @@ export class MessageDeliveryEngine {
         finally {
             if (inlineGeneration === undefined || this.inlineGenerationIsCurrent(inlineGeneration)) {
                 this.endRealtimeSync(ns);
+                client._schedulePendingP2pPullIfNeeded?.(ns, 'push-auto-pull-complete');
             }
         }
     }
@@ -2393,50 +2820,35 @@ export class MessageDeliveryEngine {
         const groupId = String(data.group_id ?? '').trim();
         if (!groupId)
             return;
-        client._onlineUnreadHintQueue.set(groupId, { ...data });
-        if (client._onlineUnreadHintTimer || client._onlineUnreadHintDrainActive)
-            return;
-        const delayMs = Math.max(0, Number(client._onlineUnreadHintInitialDelayMs ?? 750) || 0);
-        this.runtime.delivery.setOnlineUnreadHintTimer(setTimeout(() => {
-            this.runtime.delivery.setOnlineUnreadHintTimer(null);
-            client._safeAsync(this.drainOnlineUnreadHints());
-        }, delayMs));
-    }
-    async drainOnlineUnreadHints() {
-        const client = this.runtime.client;
-        if (client._onlineUnreadHintDrainActive)
-            return;
-        this.runtime.delivery.setOnlineUnreadHintDrainActive(true);
-        const attemptedAckByGroup = new Map();
-        try {
-            while (client._onlineUnreadHintQueue.size > 0) {
-                if (client.state !== ConnectionState.READY)
-                    return;
-                const groupId = client._onlineUnreadHintQueue.keys().next().value;
-                if (!groupId)
-                    return;
-                const payload = client._onlineUnreadHintQueue.get(groupId);
-                client._onlineUnreadHintQueue.delete(groupId);
-                if (!payload)
-                    continue;
-                const currentAck = this.syncState(`group:${groupId}`).ack;
-                const attemptedAck = attemptedAckByGroup.get(groupId);
-                if (attemptedAck !== undefined && currentAck <= attemptedAck)
-                    continue;
-                attemptedAckByGroup.set(groupId, currentAck);
-                await this.onRawGroupV2MessageCreated({ ...payload, _online_hint_drained: true });
-                const intervalMs = Math.max(0, Number(client._onlineUnreadHintIntervalMs ?? 50) || 0);
-                if (intervalMs > 0 && client._onlineUnreadHintQueue.size > 0) {
-                    await new Promise((resolve) => setTimeout(resolve, intervalMs));
+        const ns = `group:${groupId}`;
+        const targets = this.onlineUnreadHintTargets ?? new Map();
+        const tasks = this.onlineUnreadHintTasks ?? new Map();
+        this.onlineUnreadHintTargets = targets;
+        this.onlineUnreadHintTasks = tasks;
+        targets.set(ns, Math.max(targets.get(ns) ?? 0, positiveSafeSequenceHint(data.seq)));
+        if (tasks.has(ns))
+            return;
+        const task = Promise.resolve().then(async () => {
+            try {
+                while (true) {
+                    const ackBefore = this.syncState(ns).ack;
+                    await this.runGroupForwardRecovery(groupId, ns, 50, true, targets.get(ns) ?? 0);
+                    const ackAfter = this.syncState(ns).ack;
+                    if (ackAfter >= (targets.get(ns) ?? 0) || ackAfter <= ackBefore)
+                        return;
                 }
             }
-        }
-        catch (exc) {
-            client._clientLog.debug(`online unread hint drain failed: ${formatDeliveryError(exc)}`);
-        }
-        finally {
-            this.runtime.delivery.setOnlineUnreadHintDrainActive(false);
-        }
+            catch (exc) {
+                client._clientLog.debug(`online unread hint background Forward failed: ns=${ns} err=${formatDeliveryError(exc)}`);
+            }
+            finally {
+                targets.delete(ns);
+                if (tasks.get(ns) === task)
+                    tasks.delete(ns);
+            }
+        });
+        tasks.set(ns, task);
+        client._safeAsync(task);
     }
     async onRawGroupV2MessageCreated(data, expectedVersion, inlineGeneration) {
         const client = this.runtime.client;
@@ -2457,29 +2869,16 @@ export class MessageDeliveryEngine {
             return;
         }
         if (seq === null) {
-            if (inlinePresent && rawSeq !== undefined && rawSeq !== null) {
+            if (inlinePresent) {
                 await this.recoverInvalidGroupRealtimeHead(groupId, `group:${groupId}`, rawSeq);
             }
             return;
         }
         const eventKind = String(d.kind ?? '').trim();
         if (eventKind === 'group.online_unread_hint') {
-            if (!d._online_hint_drained) {
-                if (client._sessionOptions.background_sync === false)
-                    return;
-                this.enqueueOnlineUnreadHint(d);
-                return;
-            }
-            // Hint 不是真实消息 Head：不消费 inline、不推进水位、也不直接 ACK。
-            // 只在后台同步开启时，从已提交 Ack 强制做一次普通 Forward，绝不进入 Tail planner。
             if (client._sessionOptions.background_sync === false)
                 return;
-            try {
-                await this.runGroupForwardRecovery(groupId, `group:${groupId}`, 50);
-            }
-            catch (exc) {
-                client._clientLog.warn(`group online unread hint recovery pull failed: group=${groupId} err=${formatDeliveryError(exc)}`);
-            }
+            this.enqueueOnlineUnreadHint(d);
             return;
         }
         const ns = `group:${groupId}`;
@@ -2500,40 +2899,32 @@ export class MessageDeliveryEngine {
             catch (exc) {
                 if (inlineGeneration !== undefined && !this.inlineGenerationIsCurrent(inlineGeneration))
                     return;
-                client._clientLog.warn(`V2 group inline push rejected, falling back to Tail: group=${groupId} seq=${seq} err=${formatDeliveryError(exc)}`);
+                client._clientLog.warn(`V2 group inline push rejected, falling back to sync planner: group=${groupId} seq=${seq} err=${formatDeliveryError(exc)}`);
             }
         }
         const before = this.syncState(ns);
         client._seqTracker.updateMaxSeen(ns, seq);
-        const hasGap = before.ack < before.tail - 1;
-        if (seq <= before.head && !hasGap && !inlinePresent) {
+        if (seq <= before.ack && before.ack >= before.tail - 1) {
             client._clientLog.debug(`V2 group duplicate push ignored: group=${groupId} seq=${seq} A/T/H=${JSON.stringify(before)}`);
             const pending = this.pendingGroupInlineAcks?.get(ns);
             if (pending?.seq === seq) {
                 this.retryPendingGroupInlineAck(ns, seq, 'covered inline push');
             }
-            else {
+            else if (!inlinePresent) {
                 this.fireGroupV2Ack(groupId, seq, 'covered push');
             }
             return;
         }
-        if (!this.beginRealtimeSync(ns)) {
-            client._clientLog.debug(`V2 group push coalesced into in-flight realtime sync: ns=${ns} seq=${seq}`);
+        const pullActive = client._rpcPipeline?.hasPullActivity?.(ns) === true;
+        if (pullActive || !this.beginRealtimeSync(ns)) {
+            this.recordPendingGroupPull(ns, seq);
+            client._clientLog.debug(`V2 group push queued behind in-flight realtime sync: ns=${ns} seq=${seq}`);
             return;
         }
-        const pullTask = this.runGroupRealtimeSync(groupId, ns, seq, 50, inlinePresent && !inlineConsumed).then(async (syncResult) => {
+        void this.runGroupRealtimeSync(groupId, ns, seq, 50, false).then(async () => {
             if (inlineGeneration !== undefined && !this.inlineGenerationIsCurrent(inlineGeneration))
                 return;
-            const tailHead = this.realtimeTailHead(syncResult);
-            const maxSeen = Number(client._seqTracker.getMaxSeenSeq?.(ns) ?? 0);
-            if (client._sessionOptions?.background_sync !== false
-                && tailHead !== null && Number.isSafeInteger(maxSeen) && maxSeen > tailHead) {
-                await this.runGroupForwardRecovery(groupId, ns, 50).catch((exc) => {
-                    client._clientLog.warn(`V2 group stale Tail Forward recovery failed: group=${groupId} err=${formatDeliveryError(exc)}`);
-                });
-                if (inlineGeneration !== undefined && !this.inlineGenerationIsCurrent(inlineGeneration))
-                    return;
-            }
+            // Tail 期间新到达的 Push 已由 realtime sync 在同一周期内补至多一页 Forward。
         }).catch((exc) => {
             if (inlineGeneration !== undefined && !this.inlineGenerationIsCurrent(inlineGeneration))
                 return;
@@ -2541,11 +2932,9 @@ export class MessageDeliveryEngine {
         }).finally(() => {
             if (inlineGeneration === undefined || this.inlineGenerationIsCurrent(inlineGeneration)) {
                 this.endRealtimeSync(ns);
+                this.schedulePendingGroupPullIfNeeded(ns, 'push-auto-pull-complete');
             }
         });
-        if (d._online_hint_drained) {
-            await pullTask;
-        }
     }
     restoreSeqTrackerState() {
         const client = this.runtime.client;
@@ -2598,11 +2987,20 @@ export class MessageDeliveryEngine {
     migrateSeqStateGroupIds(state) {
         return state;
     }
-    saveSeqTrackerState() {
+    enqueueOnlineUnreadP2pHint(data) {
+        const client = this.runtime.client;
+        if (!client._aid || !client._v2Session)
+            return;
+        const ns = `p2p:${client._aid}`;
+        client._safeAsync(this.runP2PForwardRecovery(ns, 50, true).catch((exc) => {
+            client._clientLog.debug(`P2P online unread hint background Forward failed: ns=${ns} err=${formatDeliveryError(exc)}`);
+        }));
+    }
+    async saveSeqTrackerState() {
         const client = this.runtime.client;
         const context = this.currentSeqTrackerContext();
         if (!context) {
-            this.flushSeqTrackerPending();
+            await this.flushSeqTrackerPending();
             return;
         }
         const state = typeof client._seqTracker.exportSyncState === 'function'
@@ -2620,13 +3018,13 @@ export class MessageDeliveryEngine {
         }
         if (Object.keys(state).length > 0)
             this.mergeSeqTrackerPending(context, state);
-        this.flushSeqTrackerPending();
+        await this.flushSeqTrackerPending();
     }
     persistSeq(ns, forceSeq) {
         const client = this.runtime.client;
         const context = this.currentSeqTrackerContext();
         if (!context) {
-            this.flushSeqTrackerPending();
+            void this.flushSeqTrackerPending();
             return;
         }
         const seq = forceSeq ?? client._seqTracker.getContiguousSeq(ns);
@@ -2641,7 +3039,7 @@ export class MessageDeliveryEngine {
         this.mergeSeqTrackerPending(context, { [ns]: state });
         this.scheduleSeqTrackerFlush();
     }
-    commitSeqTrackerState(ns) {
+    async commitSeqTrackerState(ns) {
         const client = this.runtime.client;
         const context = this.currentSeqTrackerContext();
         if (!context || !ns)
@@ -2652,11 +3050,17 @@ export class MessageDeliveryEngine {
         if (![state.ack, state.tail, state.head].some((value) => Number(value) > 0))
             return;
         const [aid, deviceId, slotId] = JSON.parse(context);
-        this.writeSeqTrackerState(aid, deviceId, slotId, { [ns]: state }, true);
-        this.dropSeqTrackerPending(ns);
+        const pendingBeforeCommit = this.takeSeqTrackerPending(context, ns);
+        try {
+            await this.writeSeqTrackerState(aid, deviceId, slotId, { [ns]: state }, true);
+        }
+        catch (exc) {
+            this.restoreSeqTrackerPending(context, ns, pendingBeforeCommit);
+            throw exc;
+        }
         client._clientLog.debug(`seq_tracker atomic commit: ns=${ns} A/T/H=${JSON.stringify(state)} context=${context}`);
     }
-    flushSeqTrackerPending() {
+    async flushSeqTrackerPending() {
         const client = this.runtime.client;
         this.cancelSeqTrackerFlushTimer();
         const context = client._seqTrackerPendingPersistContext;
@@ -2669,7 +3073,7 @@ export class MessageDeliveryEngine {
         const state = Object.fromEntries(pending.entries());
         pending.clear();
         client._seqTrackerPendingPersistContext = null;
-        this.writeSeqTrackerState(aid, deviceId, slotId, state);
+        await this.writeSeqTrackerState(aid, deviceId, slotId, state);
     }
     dropSeqTrackerPending(ns) {
         const client = this.runtime.client;
@@ -2680,6 +3084,34 @@ export class MessageDeliveryEngine {
             this.cancelSeqTrackerFlushTimer();
         }
     }
+    takeSeqTrackerPending(context, ns) {
+        const client = this.runtime.client;
+        if (client._seqTrackerPendingPersistContext !== context)
+            return null;
+        const pending = this.seqTrackerPending();
+        const state = pending.get(ns);
+        if (!state)
+            return null;
+        pending.delete(ns);
+        if (pending.size === 0) {
+            client._seqTrackerPendingPersistContext = null;
+            this.cancelSeqTrackerFlushTimer();
+        }
+        return { ...state };
+    }
+    restoreSeqTrackerPending(context, ns, state) {
+        if (!state || this.currentSeqTrackerContext() !== context)
+            return;
+        const client = this.runtime.client;
+        const pendingContext = client._seqTrackerPendingPersistContext;
+        if (pendingContext && pendingContext !== context)
+            return;
+        const pending = this.seqTrackerPending();
+        if (!pending.has(ns))
+            pending.set(ns, state);
+        client._seqTrackerPendingPersistContext = context;
+        this.scheduleSeqTrackerFlush();
+    }
     currentSeqTrackerContext() {
         const client = this.runtime.client;
         if (!client._aid)
@@ -2698,7 +3130,7 @@ export class MessageDeliveryEngine {
         const pending = this.seqTrackerPending();
         const pendingContext = client._seqTrackerPendingPersistContext;
         if (pendingContext && pendingContext !== context && pending.size > 0) {
-            this.flushSeqTrackerPending();
+            void this.flushSeqTrackerPending();
         }
         client._seqTrackerPendingPersistContext = context;
         for (const [ns, raw] of Object.entries(state)) {
@@ -2719,7 +3151,7 @@ export class MessageDeliveryEngine {
             return;
         client._seqTrackerFlushTimer = setTimeout(() => {
             client._seqTrackerFlushTimer = null;
-            this.flushSeqTrackerPending();
+            void this.flushSeqTrackerPending();
         }, SEQ_TRACKER_PERSIST_FLUSH_DELAY_MS);
     }
     cancelSeqTrackerFlushTimer() {
@@ -2729,26 +3161,34 @@ export class MessageDeliveryEngine {
             client._seqTrackerFlushTimer = null;
         }
     }
-    writeSeqTrackerState(aid, deviceId, slotId, state, throwOnError = false) {
+    async writeSeqTrackerState(aid, deviceId, slotId, state, throwOnError = false) {
+        await this.enqueueSeqTrackerWrite(() => this.writeSeqTrackerStateNow(aid, deviceId, slotId, state, throwOnError));
+    }
+    enqueueSeqTrackerWrite(operation) {
+        const run = this.seqTrackerWriteChain.then(operation, operation);
+        this.seqTrackerWriteChain = run.catch(() => { });
+        return run;
+    }
+    async writeSeqTrackerStateNow(aid, deviceId, slotId, state, throwOnError = false) {
         const client = this.runtime.client;
         if (!aid || Object.keys(state).length === 0)
             return;
         try {
             const saveSync = client._tokenStore.saveSyncStates;
             if (typeof saveSync === 'function') {
-                saveSync.call(client._tokenStore, aid, deviceId, slotId, state);
+                await saveSync.call(client._tokenStore, aid, deviceId, slotId, state);
                 return;
             }
             const saveFn = client._tokenStore.saveSeq;
             if (typeof saveFn === 'function') {
                 for (const [ns, triplet] of Object.entries(state)) {
-                    saveFn.call(client._tokenStore, aid, deviceId, slotId, ns, triplet.ack);
+                    await saveFn.call(client._tokenStore, aid, deviceId, slotId, ns, triplet.ack);
                 }
                 return;
             }
             const updater = client._tokenStore.updateInstanceState;
             if (typeof updater === 'function') {
-                updater.call(client._tokenStore, aid, deviceId, slotId, (metadata) => {
+                await updater.call(client._tokenStore, aid, deviceId, slotId, (metadata) => {
                     const existing = isJsonObject(metadata.seq_tracker_state)
                         ? { ...metadata.seq_tracker_state }
                         : {};
@@ -2775,36 +3215,56 @@ export class MessageDeliveryEngine {
         const client = this.runtime.client;
         if (!client._aid || !ns)
             return;
+        const aid = client._aid;
+        const deviceId = client._deviceId;
+        const slotId = client._slotId;
         const seq = client._seqTracker.getContiguousSeq(ns);
         this.dropSeqTrackerPending(ns);
-        try {
-            if (seq > 0 && typeof client._tokenStore.saveSeq === 'function') {
-                client._tokenStore.saveSeq(client._aid, client._deviceId, client._slotId, ns, seq);
-                return;
-            }
-            const deleteSeq = client._tokenStore.deleteSeq;
-            if (seq <= 0 && typeof deleteSeq === 'function') {
-                deleteSeq.call(client._tokenStore, client._aid, client._deviceId, client._slotId, ns);
-                return;
-            }
-            const updater = client._tokenStore.updateInstanceState;
-            if (seq <= 0 && typeof updater === 'function') {
-                updater.call(client._tokenStore, client._aid, client._deviceId, client._slotId, (metadata) => {
-                    if (isJsonObject(metadata.seq_tracker_state)) {
-                        const next = { ...metadata.seq_tracker_state };
-                        delete next[ns];
-                        metadata.seq_tracker_state = next;
-                    }
-                    return metadata;
-                });
-                return;
-            }
-            if (seq > 0) {
-                this.saveSeqTrackerState();
-            }
+        const saveSeq = client._tokenStore.saveSeq;
+        if (seq > 0 && typeof saveSeq === 'function') {
+            void this.enqueueSeqTrackerWrite(async () => {
+                try {
+                    await saveSeq.call(client._tokenStore, aid, deviceId, slotId, ns, seq);
+                }
+                catch (exc) {
+                    client._clientLog.debug(`persist repaired seq failed: ns=${ns} err=${formatDeliveryError(exc)}`);
+                }
+            });
+            return;
         }
-        catch (exc) {
-            client._clientLog.debug(`persist repaired seq failed: ns=${ns} err=${formatDeliveryError(exc)}`);
+        const deleteSeq = client._tokenStore.deleteSeq;
+        if (seq <= 0 && typeof deleteSeq === 'function') {
+            void this.enqueueSeqTrackerWrite(async () => {
+                try {
+                    await deleteSeq.call(client._tokenStore, aid, deviceId, slotId, ns);
+                }
+                catch (exc) {
+                    client._clientLog.debug(`delete repaired seq failed: ns=${ns} err=${formatDeliveryError(exc)}`);
+                }
+            });
+            return;
+        }
+        const updater = client._tokenStore.updateInstanceState;
+        if (seq <= 0 && typeof updater === 'function') {
+            void this.enqueueSeqTrackerWrite(async () => {
+                try {
+                    await updater.call(client._tokenStore, aid, deviceId, slotId, (metadata) => {
+                        if (isJsonObject(metadata.seq_tracker_state)) {
+                            const next = { ...metadata.seq_tracker_state };
+                            delete next[ns];
+                            metadata.seq_tracker_state = next;
+                        }
+                        return metadata;
+                    });
+                }
+                catch (exc) {
+                    client._clientLog.debug(`delete repaired seq failed: ns=${ns} err=${formatDeliveryError(exc)}`);
+                }
+            });
+            return;
+        }
+        if (seq > 0) {
+            void this.saveSeqTrackerState();
         }
     }
     clampAckSeq(method, field, ns, seq) {
@@ -2864,13 +3324,15 @@ export class MessageDeliveryEngine {
         }
         return params;
     }
-    async drainOrderedMessages(ns, beforeSeq, pullResponse = false) {
+    async drainOrderedMessages(ns, beforeSeq, pullResponse = false, persist = true) {
         const client = this.runtime.client;
+        this.ensurePullOperationCurrent();
         const queue = client._pendingOrderedMsgs.get(ns);
         if (!queue || queue.size === 0)
             return;
         let delivered = false;
         while (true) {
+            this.ensurePullOperationCurrent();
             const contig = client._seqTracker.getContiguousSeq(ns);
             const ready = [...queue.keys()]
                 .filter((seq) => seq <= contig && (beforeSeq === undefined || seq < beforeSeq))
@@ -2896,6 +3358,7 @@ export class MessageDeliveryEngine {
                 continue;
             }
             await this.publishOrderedQueueItem(ns, item.event, seq, item.payload, 'ordered-drain', pullResponse);
+            this.ensurePullOperationCurrent();
             this.markPublishedSeq(ns, seq);
             client._markOrderedSeqDelivered(ns, seq);
             delivered = true;
@@ -2903,16 +3366,20 @@ export class MessageDeliveryEngine {
         }
         if (queue.size === 0) {
             client._pendingOrderedMsgs.delete(ns);
-            if (delivered)
-                this.saveSeqTrackerState();
+            if (delivered && persist) {
+                this.ensurePullOperationCurrent();
+                await this.saveSeqTrackerState();
+            }
         }
     }
     async publishOrderedMessage(event, ns, seq, payload) {
         const client = this.runtime.client;
+        this.ensurePullOperationCurrent();
         const seqNum = Number(seq);
         if (!Number.isFinite(seqNum) || !Number.isInteger(seqNum) || seqNum <= 0) {
             client._clientLog.debug(`publish ordered direct(no-seq): event=${event}, ns=${ns || '<none>'}, seq=${String(seq)}`);
             await this.publishOrderedQueueItem(ns, event, seqNum, payload, 'ordered');
+            this.ensurePullOperationCurrent();
             return true;
         }
         if (client._pushedSeqs.get(ns)?.has(seqNum)) {
@@ -2930,6 +3397,7 @@ export class MessageDeliveryEngine {
             return false;
         }
         await this.drainOrderedMessages(ns, seqNum);
+        this.ensurePullOperationCurrent();
         if (client._pushedSeqs.get(ns)?.has(seqNum)) {
             client._clientLog.debug(`publish ordered skipped after-drain duplicate: event=${event}, ns=${ns}, seq=${seqNum}`);
             return false;
@@ -2939,19 +3407,24 @@ export class MessageDeliveryEngine {
         if (queue && queue.size === 0)
             client._pendingOrderedMsgs.delete(ns);
         await this.publishOrderedQueueItem(ns, event, seqNum, payload, 'ordered');
+        this.ensurePullOperationCurrent();
         this.markPublishedSeq(ns, seqNum);
         client._markOrderedSeqDelivered(ns, seqNum);
         client._clientLog.debug(`publish ordered delivered: event=${event}, ns=${ns}, seq=${seqNum}`);
         await this.drainOrderedMessages(ns);
-        if (!client._pendingOrderedMsgs.get(ns))
-            this.saveSeqTrackerState();
+        if (!client._pendingOrderedMsgs.get(ns)) {
+            this.ensurePullOperationCurrent();
+            await this.saveSeqTrackerState();
+        }
         return true;
     }
     async publishOrderedGroupRecall(ns, seq, message) {
         const client = this.runtime.client;
+        this.ensurePullOperationCurrent();
         const seqNum = Number(seq);
         if (!Number.isFinite(seqNum) || !Number.isInteger(seqNum) || seqNum <= 0) {
             await this.publishGroupRecallTombstone(ns.replace(/^group:/, ''), seq, message);
+            this.ensurePullOperationCurrent();
             return true;
         }
         // 撤回 tombstone 也占 seq：推进 contiguous 并标记已发布，确保 ack 正常推进、不留空洞。
@@ -2961,24 +3434,31 @@ export class MessageDeliveryEngine {
         }
         client._seqTracker.onMessageSeq(ns, seqNum);
         await this.publishGroupRecallTombstone(ns.replace(/^group:/, ''), seq, message);
+        this.ensurePullOperationCurrent();
         this.markPublishedSeq(ns, seqNum);
         client._markOrderedSeqDelivered?.(ns, seqNum);
         await this.drainOrderedMessages(ns);
-        if (!client._pendingOrderedMsgs.get(ns))
-            this.saveSeqTrackerState();
+        if (!client._pendingOrderedMsgs.get(ns)) {
+            this.ensurePullOperationCurrent();
+            await this.saveSeqTrackerState();
+        }
         return true;
     }
-    async publishPulledMessage(event, ns, seq, payload) {
+    async publishPulledMessage(event, ns, seq, payload, persist = true) {
         const client = this.runtime.client;
+        this.ensurePullOperationCurrent();
         const seqNum = Number(seq);
         if (!Number.isFinite(seqNum) || !Number.isInteger(seqNum) || seqNum <= 0 || !ns) {
             client._clientLog.debug(`publish pulled direct(no-seq): event=${event}, ns=${ns || '<none>'}, seq=${String(seq)}`);
             if (event === 'message.recalled') {
-                return this.publishMessageRecallTombstone(seq, payload);
+                const published = await this.publishMessageRecallTombstone(seq, payload);
+                this.ensurePullOperationCurrent();
+                return published;
             }
             const published = client._withPullResponseProcessing(ns, () => client._publishAppEvent(event, payload, 'pull'));
             if (isPromiseLike(published))
                 await published;
+            this.ensurePullOperationCurrent();
             return true;
         }
         const queue = client._pendingOrderedMsgs.get(ns);
@@ -2989,23 +3469,28 @@ export class MessageDeliveryEngine {
                 client._pendingOrderedMsgs.delete(ns);
             return false;
         }
-        await this.drainOrderedMessages(ns, seqNum, true);
+        await this.drainOrderedMessages(ns, seqNum, true, persist);
+        this.ensurePullOperationCurrent();
         queue?.delete(seqNum);
         if (queue && queue.size === 0)
             client._pendingOrderedMsgs.delete(ns);
         if (event === 'message.recalled') {
             const recallPublished = await this.publishMessageRecallTombstone(seqNum, payload);
+            this.ensurePullOperationCurrent();
             this.markPublishedSeq(ns, seqNum);
             client._clientLog.debug(`publish pulled delivered: event=${event}, ns=${ns}, seq=${seqNum}`);
-            await this.drainOrderedMessages(ns, undefined, true);
+            await this.drainOrderedMessages(ns, undefined, true, persist);
+            this.ensurePullOperationCurrent();
             return recallPublished;
         }
         const published = client._withPullResponseProcessing(ns, () => client._publishAppEvent(event, payload, 'pull'));
         if (isPromiseLike(published))
             await published;
+        this.ensurePullOperationCurrent();
         this.markPublishedSeq(ns, seqNum);
         client._clientLog.debug(`publish pulled delivered: event=${event}, ns=${ns}, seq=${seqNum}`);
-        await this.drainOrderedMessages(ns, undefined, true);
+        await this.drainOrderedMessages(ns, undefined, true, persist);
+        this.ensurePullOperationCurrent();
         return true;
     }
 }