@agentunion/fastaun 0.5.6 → 0.5.9

package/dist/client/rpc-pipeline.js

@@ -1,6 +1,6 @@
 import * as crypto from 'node:crypto';
 import { normalizeSlotId, slotIsolationKey } from '../config.js';
-import { ClientSignatureError, ConnectionError, PermissionError, ValidationError } from '../errors.js';
+import { ClientSignatureError, ConnectionError, PermissionError, TimeoutError, ValidationError } from '../errors.js';
 import { ConnectionState, isJsonObject, } from '../types.js';
 import { validateAIDFormat, validateGroupIDFormat } from '../validators.js';
 import { normalizeGroupMentionMode, normalizeGroupSettingsResponse } from './mention-mode.js';
@@ -71,6 +71,7 @@ const SIGNED_METHODS = new Set([
     'group.dissolve', 'group.suspend', 'group.resume',
 ]);
 const SIGNING_KEY_CACHE_MAX = 32;
+const IDENTITY_ADMISSION_RETRY_DELAYS_MS = [0, 50, 100, 200];
 const signingKeyCache = new Map();
 const certFingerprintCache = new Map();
 function cacheGet(cache, key) {
@@ -108,9 +109,17 @@ function getCertFingerprint(certPem) {
 }
 /** 旧式 tryAcquirePullGate 的防并发窗口。 */
 const PULL_GATE_STALE_MS = 30000;
+const PULL_GATE_OPERATION_TIMEOUT_MS = 3000;
+function sameIdentityAdmissionRejection(error, original) {
+    const errorCode = Number(error?.code);
+    const originalCode = Number(original?.code);
+    const errorMessage = String(error instanceof Error ? error.message : error?.message ?? '').trim().toLowerCase();
+    const originalMessage = String(original instanceof Error ? original.message : original?.message ?? '').trim().toLowerCase();
+    return errorCode === -32003 && originalCode === -32003 && errorMessage === originalMessage;
+}
 const NON_IDEMPOTENT_TIMEOUT_MS = 35_000;
 const NON_IDEMPOTENT_METHODS = new Set([
-    'message.send', 'group.send', 'group.create', 'group.invite',
+    'message.send', 'mail.send', 'group.send', 'group.create', 'group.invite',
     'group.kick', 'group.remove_member', 'group.leave', 'group.dissolve',
     'group.set_settings',
     'group.update_announcement', 'group.update_rules',
@@ -145,13 +154,19 @@ export class RpcPipeline {
     runtime;
     pullGateStates = new Map();
     inlineRealtimeScopes = new Set();
-    bypassedPullScopes = new Map();
+    pullGeneration = 0;
+    pullInvalidationWait = null;
     constructor(runtime) {
         this.runtime = runtime;
     }
     async call(method, params) {
         const client = this.runtime.client;
         const tStart = Date.now();
+        const requestedAckSeq = method === 'message.ack' || method === 'message.v2.ack'
+            ? Number(params?.seq
+                ?? params?.up_to_seq
+                ?? 0) || 0
+            : 0;
         client._clientLog.debug(`call enter: method=${method}`);
         try {
             const preflight = this.preflight(method, params);
@@ -166,6 +181,8 @@ export class RpcPipeline {
             delete p._pull_gate_locked;
             const skipSendResultEnvelope = Boolean(p._skip_send_result_envelope);
             delete p._skip_send_result_envelope;
+            const deferGroupReadyPostprocess = Boolean(p._defer_group_ready_postprocess);
+            delete p._defer_group_ready_postprocess;
             const pullGateKey = this.pullGateKeyForCall(method, p);
             const runWithPullResponseScope = async (operation) => {
                 const scope = pullGateKey ? this.pullScopeKey(pullGateKey) : '';
@@ -174,12 +191,8 @@ export class RpcPipeline {
                     return await operation();
                 return await wrapper.call(client, scope, operation);
             };
-            if (pullGateKey && this.isPullResponseProcessing(pullGateKey)) {
-                client._clientLog.debug(`pull skipped while processing pull response: method=${method} key=${pullGateKey}`);
-                return client._emptyPullResultForCall(method);
-            }
             if (pullGateKey && !pullGateLocked) {
-                const pullBackground = this.pullGateBackgroundForCall(method, p);
+                const pullBackground = rpcBackground && this.pullGateBackgroundForCall(method, p);
                 const lockedParams = { ...p, _pull_gate_locked: true };
                 if (pullBackground)
                     lockedParams._rpc_background = true;
@@ -238,13 +251,10 @@ export class RpcPipeline {
                 if (p.window_mode === 'tail') {
                     return await runWithPullResponseScope(() => client._v2E2EE.pullV2TailInternal(p));
                 }
-                const skipAutoAck = p._skip_auto_ack === true || p.skip_auto_ack === true;
                 const force = p.force === true;
                 const afterSeq = Number(p.after_seq ?? 0) || 0;
                 const limit = Number(p.limit ?? 50) || 50;
-                const messages = await runWithPullResponseScope(() => (skipAutoAck
-                    ? runWithRpcPriority(() => client._pullV2(afterSeq, limit, { skipAutoAck: true, gateLocked: true, force }))
-                    : runWithRpcPriority(() => client._pullV2(afterSeq, limit, { gateLocked: true, force }))));
+                const messages = await runWithPullResponseScope(() => runWithRpcPriority(() => client._pullV2(afterSeq, limit, { gateLocked: true, force })));
                 return { messages };
             }
             if (method === 'message.history') {
@@ -253,7 +263,11 @@ export class RpcPipeline {
             }
             if (method === 'message.ack' || method === 'message.v2.ack') {
                 await client._ensureV2SessionReady('message.ack');
-                return await runWithRpcPriority(() => client._ackV2(Number(p.seq ?? p.up_to_seq ?? 0) || undefined));
+                const ackSeq = requestedAckSeq || Number(p.seq ?? p.up_to_seq ?? 0) || 0;
+                if (ackSeq > 0 && client._aid) {
+                    await client._delivery.waitForPendingInlineCommit(`p2p:${client._aid}`, ackSeq);
+                }
+                return await runWithRpcPriority(() => client._ackV2(ackSeq || undefined));
             }
             if (method === 'group.pull' || method === 'group.v2.pull') {
                 if (!String(p.group_id ?? '').trim()) {
@@ -264,8 +278,8 @@ export class RpcPipeline {
                     return await runWithPullResponseScope(() => client._v2E2EE.pullGroupV2TailInternal(p));
                 }
                 const hasExplicitAfterSeq = 'after_seq' in p || 'after_message_seq' in p;
-                const cursorParams = client._explicitGroupCursorParams(p);
-                const ownsCursor = Object.keys(cursorParams).length === 0 || client._groupCursorTargetsCurrentInstance(cursorParams);
+                const cursorParams = this.explicitGroupCursorParams(p);
+                const ownsCursor = Object.keys(cursorParams).length === 0 || this.groupCursorTargetsCurrentInstance(cursorParams);
                 const pullOpts = { gateLocked: true };
                 if (hasExplicitAfterSeq)
                     pullOpts.explicitAfterSeq = true;
@@ -294,8 +308,8 @@ export class RpcPipeline {
                     throw new ValidationError('group.ack_messages requires group_id');
                 }
                 await client._ensureV2SessionReady('group.ack_messages');
-                const cursorParams = client._explicitGroupCursorParams(p);
-                const ownsCursor = Object.keys(cursorParams).length === 0 || client._groupCursorTargetsCurrentInstance(cursorParams);
+                const cursorParams = this.explicitGroupCursorParams(p);
+                const ownsCursor = Object.keys(cursorParams).length === 0 || this.groupCursorTargetsCurrentInstance(cursorParams);
                 if (method === 'group.ack_messages' && !ownsCursor) {
                     return await runWithRpcPriority(() => client._rawGroupAckMessages(p));
                 }
@@ -311,15 +325,19 @@ export class RpcPipeline {
             if (method === 'group.thought.get' || method === 'message.thought.get') {
                 client._clientLog.debug(`thought.get transport call start: method=${method}, params=${client._debugJson(client._messageEnvelopeFieldsForDebug(p))}`);
             }
-            let result = callTimeout
-                ? (rpcBackground
-                    ? await client._transport.call(method, p, callTimeout, undefined, true)
-                    : await client._transport.call(method, p, callTimeout))
-                : (rpcBackground
-                    ? await client._transport.call(method, p, undefined, undefined, true)
-                    : await client._transport.call(method, p));
+            const invokeTransport = () => {
+                const request = callTimeout
+                    ? (rpcBackground
+                        ? client._transport.call(method, p, callTimeout, undefined, true)
+                        : client._transport.call(method, p, callTimeout))
+                    : (rpcBackground
+                        ? client._transport.call(method, p, undefined, undefined, true)
+                        : client._transport.call(method, p));
+                return this.bindActivePullCancellation(method, p, request);
+            };
+            let result = await this.transportCallWithIdentityRecovery(invokeTransport, method, p);
             const sendResultModeSource = result;
-            result = await this.postprocessResult(method, p, result);
+            result = await this.postprocessResult(method, p, result, { skipGroupState: deferGroupReadyPostprocess });
             if (!skipSendResultEnvelope) {
                 result = client._delivery.attachSendResultEnvelope(method, p, result, Boolean(p.encrypted), sendResultModeSource);
             }
@@ -531,9 +549,9 @@ export class RpcPipeline {
             }
             else {
                 mode = 'forward';
-                cursor = `after=${String(params.after_seq ?? 0)}|force=${String(Boolean(params.force))}`;
+                cursor = `after=${String(params.after_seq ?? 0)}`;
             }
-            return `p2p:${client._aid}|${mode}|${cursor}|limit=${String(params.limit)}`;
+            return `p2p:${client._aid}|mode=${mode}|cursor=${cursor}|force=${String(Boolean(params.force))}|limit=${String(params.limit)}`;
         }
         if (method === 'group.pull' || method === 'group.v2.pull' || method === 'group.history') {
             const groupId = String(params.group_id ?? params.group_aid ?? '').trim();
@@ -551,13 +569,17 @@ export class RpcPipeline {
             }
             else {
                 mode = 'forward';
-                cursor = `after=${String(params.after_seq ?? params.after_message_seq ?? 0)}|force=${String(Boolean(params.force))}`;
+                cursor = `after=${String(params.after_seq ?? params.after_message_seq ?? 0)}`;
             }
-            return `group:${groupId}|${mode}|${cursor}|limit=${String(params.limit)}`;
+            const explicitCursor = this.explicitGroupCursorParams(params);
+            const cursorSuffix = Object.keys(explicitCursor).length > 0
+                ? `|cursor_params=${stableStringify(explicitCursor)}`
+                : '';
+            return `group:${groupId}|mode=${mode}|cursor=${cursor}${cursorSuffix}|force=${String(Boolean(params.force))}|limit=${String(params.limit)}`;
         }
         if (method === 'group.pull_events' && String(params.group_id ?? params.group_aid ?? '').trim()) {
             const groupId = String(params.group_id ?? params.group_aid ?? '').trim();
-            return `group_event:${groupId}|forward|after=${String(params.after_event_seq ?? 0)}|limit=${String(params.limit)}`;
+            return `group_event:${groupId}|mode=forward|cursor=after=${String(params.after_event_seq ?? 0)}|force=${String(Boolean(params.force))}|limit=${String(params.limit)}`;
         }
         return '';
     }
@@ -570,23 +592,63 @@ export class RpcPipeline {
         return true;
     }
     pullGateName(key) {
-        if (key.startsWith('p2p:'))
-            return 'p2p_message';
-        if (key.startsWith('group:'))
-            return 'group_message';
-        if (key.startsWith('group_event:'))
-            return 'group_event';
-        return `other:${key}`;
+        void key;
+        return 'pull';
     }
     pullGateState(key) {
         const name = this.pullGateName(key);
         let state = this.pullGateStates.get(name);
         if (!state) {
-            state = { active: null, foreground: [], background: [], byKey: new Map() };
+            state = { active: null, foreground: [], background: [], byKey: new Map(), lifecycle: new Map(), watchdog: null };
             this.pullGateStates.set(name, state);
         }
+        this.startPullGateWatchdog(state, name);
         return state;
     }
+    pullGateOperationTimeoutMs() {
+        const client = this.runtime.client;
+        const configured = Number(client._PULL_GATE_OPERATION_TIMEOUT_MS
+            ?? client._PULL_GATE_TIMEOUT_MS
+            ?? client._PULL_GATE_QUEUE_TIMEOUT_MS);
+        return Number.isFinite(configured) && configured > 0 ? configured : PULL_GATE_OPERATION_TIMEOUT_MS;
+    }
+    startPullGateWatchdog(state, name) {
+        if (state.watchdog)
+            return;
+        const interval = Math.min(50, Math.max(1, Math.floor(this.pullGateOperationTimeoutMs() / 4)));
+        const timer = setInterval(() => this.checkPullGate(state, name), interval);
+        state.watchdog = timer;
+        const unref = timer.unref;
+        unref?.call(timer);
+    }
+    stopPullGateWatchdogs() {
+        for (const state of this.pullGateStates.values()) {
+            if (state.watchdog === null)
+                continue;
+            clearInterval(state.watchdog);
+            state.watchdog = null;
+        }
+    }
+    checkPullGate(state, name) {
+        const active = state.active;
+        if (!active) {
+            this.drainPullGate(state);
+            return;
+        }
+        if (!active.pullingStartedAt || Date.now() - active.pullingStartedAt < this.pullGateOperationTimeoutMs())
+            return;
+        if (active.timedOut)
+            return;
+        active.timedOut = true;
+        active.invalidated = true;
+        this.pullGeneration += 1;
+        active.cancel?.();
+        const timeout = new TimeoutError(`pull gate timeout: ${active.namespace}`, { retryable: true });
+        this.runtime.client._clientLog.warn(`pull gate watchdog timeout: gate=${name} key=${active.key} elapsed=${Date.now() - active.pullingStartedAt}ms`);
+        // 仅拒绝当前调用方；取消不敏感的 operation 仍可能运行，必须等其
+        // 真正 settle 后才释放 active，避免与后续 Pull 并发修改游标。
+        active.reject(timeout);
+    }
     pullScopeKey(key) {
         return key.split('|', 1)[0] ?? key;
     }
@@ -594,37 +656,37 @@ export class RpcPipeline {
         const ns = String(namespace ?? '').trim();
         return Boolean(ns) && this.inlineRealtimeScopes.has(ns);
     }
-    async executeBypassedPull(key, operation, background) {
-        const scope = this.pullScopeKey(key);
-        this.bypassedPullScopes.set(scope, (this.bypassedPullScopes.get(scope) ?? 0) + 1);
-        try {
-            return await this.executePullOperation(operation, background);
-        }
-        finally {
-            const remaining = (this.bypassedPullScopes.get(scope) ?? 1) - 1;
-            if (remaining <= 0) {
-                this.bypassedPullScopes.delete(scope);
-            }
-            else {
-                this.bypassedPullScopes.set(scope, remaining);
-            }
-        }
+    bindActivePullCancellation(method, params, request) {
+        const cancel = request.cancel;
+        const key = this.pullGateKeyForCall(method, params);
+        if (typeof cancel !== 'function' || !key)
+            return request;
+        const state = this.pullGateStates.get(this.pullGateName(key));
+        const active = state?.active;
+        if (!active || active.key !== key || active.timedOut || active.invalidated)
+            return request;
+        const boundCancel = () => cancel.call(request);
+        active.cancel = boundCancel;
+        return request.finally(() => {
+            if (active.cancel === boundCancel)
+                active.cancel = null;
+        });
     }
     isPullResponseProcessing(key) {
         if (!key)
             return false;
         return (this.runtime.client._pullResponseKeys.get(this.pullScopeKey(key)) ?? 0) > 0;
     }
-    hasPullActivity(namespace) {
+    hasPullActivity(namespace, includePending = true) {
         const ns = String(namespace ?? '').trim();
         if ((!ns.startsWith('p2p:') && !ns.startsWith('group:')) || this.hasInlineRealtimeGuard(ns))
             return true;
         const client = this.runtime.client;
         if ((client._pullResponseKeys.get(ns) ?? 0) > 0)
             return true;
-        if (Number(client._pendingP2pPullUpper?.get?.(ns) ?? 0) > 0)
+        if (includePending && Number(client._pendingP2pPullUpper?.get?.(ns) ?? 0) > 0)
             return true;
-        if ((this.bypassedPullScopes.get(ns) ?? 0) > 0)
+        if (includePending && client._delivery?.hasPendingPull?.(ns))
             return true;
         for (const key of client._gapFillDone?.keys?.() ?? []) {
             const marker = String(key ?? '').trim();
@@ -660,6 +722,7 @@ export class RpcPipeline {
             const state = this.pullGateStates.get(this.pullGateName(ns));
             if (state) {
                 this.drainPullGate(state);
+                this.runtime.client._delivery?.onPullGateIdle?.(ns);
                 this.armQueuedPullTimers(state);
             }
         }
@@ -694,94 +757,188 @@ export class RpcPipeline {
         gate.inflight = false;
         gate.startedAt = 0;
         if (key.startsWith('p2p:')) {
-            client._schedulePendingP2pPullIfNeeded(key, 'pull-gate-release');
+            client._schedulePendingP2pPullIfNeeded?.(key, 'pull-gate-release');
+        }
+    }
+    isPullGenerationCurrent(generation) {
+        return generation === this.pullGeneration;
+    }
+    invalidatePulls() {
+        if (this.pullInvalidationWait)
+            return this.pullInvalidationWait;
+        this.pullGeneration += 1;
+        const error = new Error('pull invalidated');
+        const waits = [];
+        for (const state of this.pullGateStates.values()) {
+            const jobs = new Set();
+            if (state.active)
+                jobs.add(state.active);
+            for (const job of state.foreground)
+                jobs.add(job);
+            for (const job of state.background)
+                jobs.add(job);
+            for (const job of jobs) {
+                job.invalidated = true;
+                if (!job.timedOut)
+                    job.reject(error);
+                job.cancel?.();
+                job.resumeResolve?.();
+                job.resumeResolve = null;
+                if (job.running) {
+                    waits.push(job.settled);
+                }
+                else {
+                    job.settledResolve?.();
+                    job.settledResolve = null;
+                }
+            }
+            state.foreground = state.foreground.filter((job) => !jobs.has(job));
+            state.background = state.background.filter((job) => !jobs.has(job));
+            for (const [key, job] of state.byKey.entries()) {
+                if (jobs.has(job) && !job.running)
+                    state.byKey.delete(key);
+            }
+            this.drainPullGate(state);
         }
+        const wait = Promise.all(waits).then(() => undefined);
+        let tracked;
+        tracked = wait.finally(() => {
+            if (this.pullInvalidationWait === tracked)
+                this.pullInvalidationWait = null;
+        });
+        this.pullInvalidationWait = tracked;
+        return tracked;
+    }
+    pullInvalidationInProgress() {
+        return this.pullInvalidationWait !== null;
     }
     async runPullSerialized(key, operation, background = false) {
-        if (key && this.isPullResponseProcessing(key)) {
-            this.runtime.client._clientLog.debug(`pull skipped while processing pull response: key=${key}`);
-            return [];
+        if (this.pullInvalidationInProgress()) {
+            throw new Error('pull invalidated');
         }
         if (!key)
             return await this.executePullOperation(operation, background);
         const state = this.pullGateState(key);
-        const timeoutMs = Math.max(0, Number(this.runtime.client._PULL_GATE_QUEUE_TIMEOUT_MS ?? 3_000) || 0);
-        const existing = state.byKey.get(key);
+        const namespace = this.pullScopeKey(key);
+        const active = state.active?.key === key && !state.active.timedOut && !state.active.invalidated ? state.active : null;
+        const queuedForeground = state.foreground.find((job) => job.key === key && !job.timedOut && !job.invalidated);
+        const queuedBackground = state.background.find((job) => job.key === key && !job.timedOut && !job.invalidated);
+        const existing = background
+            ? (active ?? queuedForeground ?? queuedBackground)
+            : (queuedForeground ?? (active && !active.background ? active : null) ?? queuedBackground);
         if (existing) {
+            if (!background && existing.background && existing !== state.active) {
+                const index = state.background.indexOf(existing);
+                if (index >= 0)
+                    state.background.splice(index, 1);
+                existing.background = false;
+                state.foreground.push(existing);
+            }
+            const shared = existing.promise;
             this.runtime.client._clientLog.debug(`pull gate coalesced: gate=${this.pullGateName(key)} key=${key} background=${String(background)}`);
-            if (this.hasInlineRealtimeGuard(this.pullScopeKey(key)))
-                return await existing.promise;
-            return await this.waitForCoalesced(existing.promise, timeoutMs, operation, background, key);
+            return await shared;
         }
         let resolve;
         let reject;
         const promise = new Promise((res, rej) => { resolve = res; reject = rej; });
+        let settledResolve;
+        const settled = new Promise((resolveSettled) => { settledResolve = resolveSettled; });
+        void promise.catch(() => { });
         const job = {
             key,
+            namespace,
             background,
+            running: false,
+            suspended: false,
             enqueuedAt: Date.now(),
             operation,
             promise,
             resolve,
             reject,
             timer: null,
+            resume: null,
+            resumeResolve: null,
+            pullingStartedAt: 0,
+            timedOut: false,
+            invalidated: false,
+            cancel: null,
+            settled,
+            settledResolve,
         };
         const queue = background ? state.background : state.foreground;
         queue.push(job);
         state.byKey.set(key, job);
         this.drainPullGate(state);
-        if (state.active !== job && !this.hasInlineRealtimeGuard(this.pullScopeKey(job.key))) {
-            job.timer = setTimeout(() => this.bypassQueuedPull(state, job), timeoutMs);
-        }
+        this.checkPullGate(state, this.pullGateName(key));
         return await promise;
     }
     async executePullOperation(operation, background) {
-        if (background)
-            return await this.runtime.client._withBackgroundRpc(operation);
-        return await operation();
-    }
-    waitForCoalesced(shared, timeoutMs, operation, background, key) {
-        return new Promise((resolve, reject) => {
-            let settled = false;
-            const timer = setTimeout(() => {
-                if (settled)
-                    return;
-                settled = true;
-                this.runtime.client._clientLog.warn(`pull gate coalesced wait timeout, bypass: gate=${this.pullGateName(key)} key=${key} timeout=${timeoutMs}ms`);
-                void this.executeBypassedPull(key, operation, background).then(resolve, reject);
-            }, timeoutMs);
-            shared.then((value) => {
-                if (settled)
-                    return;
-                settled = true;
-                clearTimeout(timer);
-                resolve(value);
-            }, (error) => {
-                if (settled)
-                    return;
-                settled = true;
-                clearTimeout(timer);
-                reject(error);
-            });
-        });
+        const client = this.runtime.client;
+        const hadPrevious = Object.prototype.hasOwnProperty.call(client, '_pullOperationGeneration');
+        const previous = client._pullOperationGeneration;
+        client._pullOperationGeneration = this.pullGeneration;
+        try {
+            if (background)
+                return await client._withBackgroundRpc(operation);
+            return await operation();
+        }
+        finally {
+            if (hadPrevious)
+                client._pullOperationGeneration = previous;
+            else
+                delete client._pullOperationGeneration;
+        }
     }
-    bypassQueuedPull(state, job) {
-        if (state.active === job)
-            return;
-        if (this.hasInlineRealtimeGuard(this.pullScopeKey(job.key))) {
-            job.timer = null;
+    pullOperationIsCurrent() {
+        const generation = this.runtime.client._pullOperationGeneration;
+        return generation === undefined || this.isPullGenerationCurrent(generation);
+    }
+    throwIfPullInvalidated() {
+        if (!this.pullOperationIsCurrent())
+            throw new Error('pull invalidated');
+    }
+    async yieldPullGate(key, nextKey, background) {
+        if (!key)
             return;
-        }
-        const queue = job.background ? state.background : state.foreground;
-        const index = queue.indexOf(job);
-        if (index < 0)
+        const state = this.pullGateState(key);
+        const namespace = this.pullScopeKey(key);
+        const job = state.active?.key === key ? state.active : null;
+        if (!job || state.active !== job || job.timedOut || job.invalidated)
             return;
-        queue.splice(index, 1);
+        const replacementKey = String(nextKey || key);
         if (state.byKey.get(job.key) === job)
             state.byKey.delete(job.key);
-        job.timer = null;
-        this.runtime.client._clientLog.warn(`pull gate queue timeout, bypass: gate=${this.pullGateName(job.key)} key=${job.key} background=${String(job.background)}`);
-        void this.executeBypassedPull(job.key, job.operation, job.background).then(job.resolve, job.reject);
+        job.key = replacementKey;
+        job.namespace = this.pullScopeKey(replacementKey);
+        if (background !== undefined)
+            job.background = background;
+        state.byKey.set(job.key, job);
+        state.lifecycle.set(namespace, 'pulled');
+        job.suspended = true;
+        job.resume = new Promise((resolve) => { job.resumeResolve = resolve; });
+        state.active = null;
+        (job.background ? state.background : state.foreground).push(job);
+        this.drainPullGate(state);
+        if (job.resume) {
+            await job.resume;
+            if (job.invalidated)
+                throw new Error('pull invalidated');
+        }
+    }
+    getPullLifecycle(namespace) {
+        const ns = this.pullScopeKey(namespace);
+        if (!ns)
+            return 'idle';
+        return this.pullGateStates.get(this.pullGateName(ns))?.lifecycle.get(ns) ?? 'idle';
+    }
+    setPullLifecycle(namespace, lifecycle) {
+        const ns = this.pullScopeKey(namespace);
+        if (!ns)
+            return;
+        const state = this.pullGateStates.get(this.pullGateName(ns));
+        if (!state || state.active?.namespace !== ns)
+            return;
+        state.lifecycle.set(ns, lifecycle);
     }
     drainPullGate(state) {
         if (state.active)
@@ -798,24 +955,37 @@ export class RpcPipeline {
             clearTimeout(job.timer);
             job.timer = null;
         }
-        void this.executePullOperation(job.operation, job.background)
-            .then(job.resolve, job.reject)
+        job.pullingStartedAt = Date.now();
+        job.timedOut = false;
+        state.lifecycle.set(job.namespace, 'pulling');
+        const resumeResolve = job.resumeResolve;
+        job.resume = null;
+        job.resumeResolve = null;
+        if (job.suspended) {
+            job.suspended = false;
+            resumeResolve?.();
+            return;
+        }
+        job.running = true;
+        const operationPromise = this.executePullOperation(job.operation, job.background);
+        void operationPromise
+            .then((value) => { if (!job.timedOut && !job.invalidated)
+            job.resolve(value); }, (error) => { if (!job.timedOut && !job.invalidated)
+            job.reject(error); })
             .finally(() => {
+            state.lifecycle.set(job.namespace, 'idle');
             if (state.active === job)
                 state.active = null;
             if (state.byKey.get(job.key) === job)
                 state.byKey.delete(job.key);
             this.drainPullGate(state);
+            job.settledResolve?.();
+            job.settledResolve = null;
+            if (!job.invalidated)
+                this.runtime.client._delivery?.onPullGateIdle?.(job.namespace);
         });
     }
-    armQueuedPullTimers(state) {
-        const timeoutMs = Math.max(0, Number(this.runtime.client._PULL_GATE_QUEUE_TIMEOUT_MS ?? 3_000) || 0);
-        for (const job of [...state.foreground, ...state.background]) {
-            if (!job.timer && !this.hasInlineRealtimeGuard(this.pullScopeKey(job.key))) {
-                job.timer = setTimeout(() => this.bypassQueuedPull(state, job), timeoutMs);
-            }
-        }
-    }
+    armQueuedPullTimers(_state) { }
     // ── raw-call ───────────────────────────────────────────────────────────────
     async rawCall(method, params, opts = {}) {
         const { timeout, trace, signed = true, background = false } = opts;
@@ -824,20 +994,50 @@ export class RpcPipeline {
         if (signed) {
             this.applyClientSignature(method, payload);
         }
-        if (background) {
-            return await client._transport.call(method, payload, timeout, trace, true);
-        }
-        if (trace !== undefined) {
-            return await client._transport.call(method, payload, timeout, trace);
+        const invokeTransport = () => {
+            let request;
+            if (background)
+                request = client._transport.call(method, payload, timeout, trace, true);
+            else if (trace !== undefined)
+                request = client._transport.call(method, payload, timeout, trace);
+            else if (timeout !== undefined)
+                request = client._transport.call(method, payload, timeout);
+            else
+                request = client._transport.call(method, payload);
+            return this.bindActivePullCancellation(method, payload, request);
+        };
+        const result = await this.transportCallWithIdentityRecovery(invokeTransport, method, payload);
+        this.throwIfPullInvalidated();
+        return result;
+    }
+    async transportCallWithIdentityRecovery(operation, method, params) {
+        try {
+            return await operation();
         }
-        if (timeout !== undefined) {
-            return await client._transport.call(method, payload, timeout);
+        catch (err) {
+            const recover = this.runtime.client._recoverIdentityAdmission;
+            if (typeof recover !== 'function' || !await recover.call(this.runtime.client, err, method, params))
+                throw err;
+            let lastError = err;
+            for (const delay of IDENTITY_ADMISSION_RETRY_DELAYS_MS) {
+                if (delay > 0)
+                    await new Promise((resolve) => setTimeout(resolve, delay));
+                try {
+                    return await operation();
+                }
+                catch (retryError) {
+                    if (!sameIdentityAdmissionRejection(retryError, err))
+                        throw retryError;
+                    lastError = retryError;
+                }
+            }
+            throw lastError;
         }
-        return await client._transport.call(method, payload);
     }
     // ── postprocess ────────────────────────────────────────────────────────────
-    async postprocessResult(method, params, result) {
+    async postprocessResult(method, params, result, options = {}) {
         const client = this.runtime.client;
+        this.throwIfPullInvalidated();
         let next = result;
         if ((method === 'group.send' || method === 'group.v2.send') && isUnknownJsonObject(next)) {
             next = normalizeGroupMentionMode(next);
@@ -854,12 +1054,40 @@ export class RpcPipeline {
             next = await client._decryptMessageThoughts(next);
         }
         if (method === 'message.pull' && isUnknownJsonObject(next)) {
-            this.postprocessMessagePull(params, next);
+            const isTail = String(next.window_mode ?? params.window_mode ?? '').trim().toLowerCase() === 'tail';
+            if (!isTail && client._aid && client._seqTracker) {
+                const ns = `p2p:${client._aid}`;
+                const afterSeq = Math.max(0, Number(params.after_seq ?? 0) || 0);
+                await client._delivery.commitPlainForwardPage(ns, afterSeq, 'message.pull', next);
+            }
+            else {
+                this.postprocessMessagePull(params, next);
+            }
         }
         if (method === 'group.pull' && isUnknownJsonObject(next)) {
-            this.postprocessGroupPull(params, next);
+            if (Array.isArray(next.messages)) {
+                next.messages = next.messages.map((message) => normalizeGroupMentionMode(message));
+            }
+            const gid = String(params.group_id ?? params.group_aid ?? '').trim();
+            const explicitCursorParams = this.explicitGroupCursorParams(params);
+            const ownsCursor = Object.keys(explicitCursorParams).length === 0
+                || this.groupCursorTargetsCurrentInstance(explicitCursorParams);
+            const isTail = String(next.window_mode ?? params.window_mode ?? '').trim().toLowerCase() === 'tail';
+            if (!ownsCursor) {
+                client._clientLog.debug(`group.pull external cursor skips local Forward commit: group=${gid}`);
+            }
+            else if (!isTail && gid && client._seqTracker) {
+                const ns = `group:${gid}`;
+                const afterSeq = Math.max(0, Number(params.after_message_seq ?? params.after_seq ?? 0) || 0);
+                await client._delivery.commitPlainForwardPage(ns, afterSeq, 'group.pull', next, gid);
+            }
+            else {
+                this.postprocessGroupPull(params, next);
+            }
+        }
+        if (!options.skipGroupState) {
+            next = await client._groupState.postprocessResult(method, params, next);
         }
-        next = await client._groupState.postprocessResult(method, params, next);
         return next;
     }
     // ── private helpers ────────────────────────────────────────────────────────
@@ -973,6 +1201,19 @@ export class RpcPipeline {
         }
         return cursorParams;
     }
+    explicitGroupCursorParams(params) {
+        const value = params._group_cursor_params;
+        if (!isJsonObject(value))
+            return {};
+        return { ...value };
+    }
+    groupCursorTargetsCurrentInstance(params) {
+        const client = this.runtime.client;
+        const deviceId = String(params.device_id ?? '').trim();
+        const slotId = String(params.slot_id ?? '').trim();
+        return (!deviceId || deviceId === (client._deviceId ?? ''))
+            && (!slotId || slotId === (client._slotId ?? ''));
+    }
     validateMessageRecipient(toAid) {
         if (!String(toAid ?? '').trim()) {
             throw new ValidationError("message.send requires 'to' (recipient AID)");