@coclaw/openclaw-coclaw 0.18.0 → 0.19.2

package/src/webrtc/webrtc-peer.js

@@ -1,5 +1,7 @@
 import { createReassembler } from './dc-chunking.js';
-import { RpcSendQueue, DC_LOW_WATER_MARK } from './rpc-send-queue.js';
+import { MemoryQueue } from '../utils/memory-queue.js';
+import { RpcDcSender, DC_LOW_WATER_MARK, MAX_SINGLE_MSG_BYTES } from './rpc-dc-sender.js';
+import { isAgentRunResponse } from './agent-run-response.js';
 import { remoteLog } from '../remote-log.js';
 
 // 单个 session 内 file DC 历史快照的容量上限（满后按 FIFO 淘汰最老条目）。
@@ -41,7 +43,7 @@ export class WebRtcPeer {
 		this.__PeerConnection = PeerConnection;
 		this.__impl = impl ?? null;
 		this.__rtcTag = impl ? `[coclaw/rtc:${impl}]` : '[coclaw/rtc]';
-		/** @type {Map<string, { pc: object, rpcChannel: object|null, rpcSendQueue: RpcSendQueue|null, fileChannels: Set, remoteMaxMessageSize: number, nextMsgId: number }>} */
+		/** @type {Map<string, { pc: object, rpcChannel: object|null, rpcQueue: MemoryQueue|null, rpcDcSender: RpcDcSender|null, rpcConsumeLoop: Promise<void>|null, fileChannels: Set, remoteMaxMessageSize: number, nextMsgId: number }>} */
 		this.__sessions = new Map();
 	}
 
@@ -64,6 +66,23 @@ export class WebRtcPeer {
 	async closeByConnId(connId) {
 		const session = this.__sessions.get(connId);
 		if (!session) return;
+		// 先 detach 所有 PC 事件，再做后续 await 链。两个目的：
+		// 1. 防止 pc.close() 异步触发 onconnectionstatechange 误删 connId 复用后的新 session
+		// 2. RPC 清理含 await（queue.destroy + consumeLoop），期间若旧 PC 还有滞后回调
+		//    （某些 WebRTC 实现 close 后仍投递事件），可能通过 Map.get(connId) 拿到新 session 误操作
+		//    特别是 ondatachannel：晚到的 channel 会被 __setupDataChannel 装到新 session
+		session.pc.onconnectionstatechange = null;
+		session.pc.onicecandidate = null;
+		session.pc.ondatachannel = null;
+		if ('onselectedcandidatepairchange' in session.pc) {
+			session.pc.onselectedcandidatepairchange = null;
+		}
+		if ('oniceconnectionstatechange' in session.pc) {
+			session.pc.oniceconnectionstatechange = null;
+		}
+		if ('onicegatheringstatechange' in session.pc) {
+			session.pc.onicegatheringstatechange = null;
+		}
 		// 清理 failed TTL 定时器
 		if (session.__failedTimer) {
 			clearTimeout(session.__failedTimer);
@@ -81,22 +100,17 @@ export class WebRtcPeer {
 			session.__pluginProbeInFlight = null;
 		}
 		this.__sessions.delete(connId);
-		// 显式关闭 rpc 发送队列：dc.onclose 路径中 `sessions.get(connId)` 已返回 undefined 而短路，
-		// 此处不主动 close 会丢失 drop 汇总 remoteLog 诊断
-		if (session.rpcSendQueue) {
-			session.rpcSendQueue.close();
-			session.rpcSendQueue = null;
+		// 显式关闭 rpc 链路：dc.onclose 路径中 `sessions.get(connId)` 已返回 undefined 而短路，
+		// 此处不主动 close 会丢失 drop 汇总 remoteLog 诊断 + consumeLoop 泄漏
+		if (session.rpcDcSender || session.rpcQueue) {
+			session.rpcDcSender?.close();
+			await session.rpcQueue?.destroy();
+			if (session.rpcConsumeLoop) await session.rpcConsumeLoop.catch(() => {});
+			session.rpcDcSender = null;
+			session.rpcQueue = null;
+			session.rpcConsumeLoop = null;
 			session.rpcChannel = null;
 		}
-		// 先 detach 事件，防止 pc.close() 异步触发 onconnectionstatechange 删除新 session
-		session.pc.onconnectionstatechange = null;
-		session.pc.onicecandidate = null;
-		if ('onselectedcandidatepairchange' in session.pc) {
-			session.pc.onselectedcandidatepairchange = null;
-		}
-		if ('oniceconnectionstatechange' in session.pc) {
-			session.pc.oniceconnectionstatechange = null;
-		}
 		await session.pc.close();
 		this.__remoteLog(`rtc.closed conn=${connId}`);
 		this.logger.info?.(`${this.__rtcTag} [${connId}] closed`);
@@ -108,7 +122,7 @@ export class WebRtcPeer {
 		await Promise.all(closing);
 	}
 
-	/** 向所有已打开的 rpcChannel 广播（大消息自动分片，经由 RpcSendQueue 流控） */
+	/** 向所有已打开的 rpcChannel 广播（大消息自动分片，经由 MemoryQueue + RpcDcSender 流控） */
 	broadcast(payload) {
 		let jsonStr;
 		try {
@@ -120,9 +134,14 @@ export class WebRtcPeer {
 		}
 		if (typeof jsonStr !== 'string') return; // payload 是 undefined/symbol 时 stringify 返回 undefined
 		for (const session of this.__sessions.values()) {
-			const q = session.rpcSendQueue;
+			const q = session.rpcQueue;
 			if (q && session.rpcChannel?.readyState === 'open') {
-				q.send(jsonStr);
+				// fire-and-forget：admission 决策返回 boolean Promise，broadcast 不关心结果；
+				// 内部异常（mutex 等极冷路径）catch 防 unhandled rejection
+				q.enqueue(jsonStr).catch((err) => {
+					/* c8 ignore next -- enqueue 仅在 mutex 异常等极冷路径 reject；类型校验已由调用方完成 */
+					this.__logDebug(`broadcast enqueue error: ${err?.message}`);
+				});
 			}
 		}
 	}
@@ -130,14 +149,18 @@ export class WebRtcPeer {
 	/**
 	 * 向指定 connId 的 rpc DC 单播一个 JSON 帧（不走 server 中转）。
 	 * 若 session/DC 未就绪或被发送队列拒收（队列满等）返回 false，由调用方决定是否重试。
+	 *
+	 * 阶段 1 改造：enqueue 是 async（mutex 内 admission 决策），sendTo 也变 async；调用方
+	 * 已在 async 上下文（realtime-bridge.js 的 ws.message handler），增加 `await` 即可。
+	 *
 	 * @param {string} connId
 	 * @param {object} payload - 完整的 JSON 帧（通常是 { type: 'event', event, payload }）
-	 * @returns {boolean} true=已入队发送；false=session 不存在 / DC 未 open / payload 不可序列化 / 发送队列拒收
+	 * @returns {Promise<boolean>} true=已入队发送；false=session 不存在 / DC 未 open / payload 不可序列化 / 发送队列拒收
 	 */
-	sendTo(connId, payload) {
+	async sendTo(connId, payload) {
 		const session = this.__sessions.get(connId);
 		if (!session) return false;
-		const q = session.rpcSendQueue;
+		const q = session.rpcQueue;
 		if (!q || session.rpcChannel?.readyState !== 'open') return false;
 		let jsonStr;
 		try {
@@ -147,7 +170,13 @@ export class WebRtcPeer {
 			return false;
 		}
 		if (typeof jsonStr !== 'string') return false;
-		return q.send(jsonStr);
+		try {
+			return await q.enqueue(jsonStr);
+		} catch (err) {
+			/* c8 ignore next 3 -- enqueue 仅在 mutex 异常等极冷路径 reject；与 broadcast/file sendFn 对称 */
+			this.__logDebug(`[${connId}] sendTo enqueue error: ${err?.message}`);
+			return false;
+		}
 	}
 
 	async __handleOffer(msg) {
@@ -180,12 +209,13 @@ export class WebRtcPeer {
 				this.logger.info?.(`${this.__rtcTag} ICE restart offer from ${connId}, renegotiating`);
 				try {
 					await existing.pc.setRemoteDescription({ type: 'offer', sdp: msg.payload.sdp });
-					// 重协商 SDP 可能变更 a=max-message-size，同步刷新 queue 分片阈值；
-					// queue 中已入队的 chunks 按旧值分片保留，新消息用新值
+					// 重协商 SDP 可能变更 a=max-message-size，同步刷新 sender 分片阈值；
+					// queue 存的是完整字符串（buildChunks 在 sender.send 内同步完成），
+					// 已开始分片的当前消息用旧 size，下一条消息用新 size
 					const newMMS = this.__resolveMaxMessageSize(existing.pc, msg.payload.sdp);
 					if (newMMS !== existing.remoteMaxMessageSize) {
 						existing.remoteMaxMessageSize = newMMS;
-						if (existing.rpcSendQueue) existing.rpcSendQueue.maxMessageSize = newMMS;
+						if (existing.rpcDcSender) existing.rpcDcSender.maxMessageSize = newMMS;
 					}
 					const answer = await existing.pc.createAnswer();
 					await existing.pc.setLocalDescription(answer);
@@ -242,13 +272,20 @@ export class WebRtcPeer {
 		const iceServers = [];
 		if (msg.turnCreds) {
 			const { urls, username, credential } = msg.turnCreds;
-			for (const url of urls) {
-				const server = { urls: url };
-				if (url.startsWith('turn:') || url.startsWith('turns:')) {
-					server.username = username;
-					server.credential = credential;
+			// 防御：urls 必须是 string 数组；非数组（含 undefined / 单 string）跳过，
+			// 避免 for-of undefined 抛错或单 string 被字符级迭代成无效 iceServers
+			if (Array.isArray(urls)) {
+				for (const url of urls) {
+					if (typeof url !== 'string') continue;
+					const server = { urls: url };
+					if (url.startsWith('turn:') || url.startsWith('turns:')) {
+						server.username = username;
+						server.credential = credential;
+					}
+					iceServers.push(server);
 				}
-				iceServers.push(server);
+			} else {
+				this.logger.warn?.(`${this.__rtcTag} ignored malformed turnCreds.urls (expected string[], got ${typeof urls})`);
 			}
 		}
 
@@ -268,7 +305,7 @@ export class WebRtcPeer {
 
 		const remoteMaxMessageSize = this.__resolveMaxMessageSize(pc, msg.payload.sdp);
 
-		const session = { pc, rpcChannel: null, rpcSendQueue: null, fileChannels: new Set(), remoteMaxMessageSize, nextMsgId: 1 };
+		const session = { pc, rpcChannel: null, rpcQueue: null, rpcDcSender: null, rpcConsumeLoop: null, fileChannels: new Set(), remoteMaxMessageSize, nextMsgId: 1 };
 		this.__sessions.set(connId, session);
 
 		// ICE candidate → 发给 UI，并统计各类型 candidate 数量
@@ -287,6 +324,11 @@ export class WebRtcPeer {
 			hostAddrs.length = 0;
 		};
 		pc.onicecandidate = ({ candidate }) => {
+			// pc identity guard：旧 PC 在 closeByConnId 之后微任务里仍可能投递 onicecandidate
+			// （属性置 null 不阻止已 dispatch 的回调）；此时 connId 可能已被新 session 复用，
+			// 旧 candidate 不应转发给 UI，否则 UI 会把旧 PC 的 candidate 加到新 PC 上
+			const cur = this.__sessions.get(connId);
+			if (!cur || cur.pc !== pc) return;
 			if (!candidate) {
 				// 浏览器路径：gathering 完成通过 null candidate 通知
 				flushGatherDiag();
@@ -319,6 +361,9 @@ export class WebRtcPeer {
 		// gathering→ 重置 flag 支持 ICE restart；complete→ flush 汇总
 		if ('onicegatheringstatechange' in pc) {
 			pc.onicegatheringstatechange = () => {
+				// pc identity guard：与其他 handler 对称，旧 PC 微任务迟到不污染新 session 的 gather diag
+				const cur = this.__sessions.get(connId);
+				if (!cur || cur.pc !== pc) return;
 				const state = pc.iceGatheringState;
 				if (state === 'gathering') {
 					gatheringEmitted = false;
@@ -414,23 +459,37 @@ export class WebRtcPeer {
 		// pion: 选中的 candidate pair 通过独立事件上报
 		if ('onselectedcandidatepairchange' in pc) {
 			pc.onselectedcandidatepairchange = () => {
+				// pc identity guard：旧 PC 的迟到回调会用旧 pc.selectedCandidatePair 数据
+				// + 闭包 connId 拼出"旧 pair + 新 connId"的混合日志，并往 UI 转发过时 transport
+				const cur = this.__sessions.get(connId);
+				if (!cur || cur.pc !== pc) return;
 				const pair = pc.selectedCandidatePair;
 				if (pair) {
 					this.__logNominatedPair(connId, pair);
 				}
 				// ICE restart 或初次选中都会触发；让出一次 CPU 后再单播 transport 信息。
 				// 签名去重保证 pair 不变时不会重复发送。
-				queueMicrotask(() => this.__sendPeerTransport(connId));
+				queueMicrotask(() => { this.__sendPeerTransport(connId).catch(() => {}); });
 			};
 		}
 
 		// 监听 UI 创建的 DataChannel
 		pc.ondatachannel = ({ channel }) => {
+			// pc identity guard：旧 PC 在 closeByConnId 之后微任务里仍可能投递 ondatachannel
+			// （属性置 null 不阻止已 dispatch 的回调）；此时 connId 可能已被新 session 复用，
+			// 旧 channel 必须被忽略，否则会进 __setupDataChannel 把旧 dc 装到新 session
+			const cur = this.__sessions.get(connId);
+			if (!cur || cur.pc !== pc) return;
 			this.__remoteLog(`dc.received conn=${connId} label=${channel.label}`);
 			this.logger.info?.(`${this.__rtcTag} [${connId}] DataChannel "${channel.label}" received`);
 			if (channel.label === 'rpc') {
+				// rpcChannel 在 sync 路径赋值，作为 setup 内身份重核的依据；setup 本身改 async
+				// 后变 fire-and-forget（WebRTC 实现的 ondatachannel 是 sync 回调，不能 await）
 				session.rpcChannel = channel;
-				this.__setupDataChannel(connId, channel);
+				this.__setupDataChannel(connId, channel).catch((err) => {
+					/* c8 ignore next 2 -- setup 内部已经 try/catch 所有 await；此处仅防御性兜底 */
+					this.logger.warn?.(`${this.__rtcTag} [${connId}] __setupDataChannel error: ${err?.message}`);
+				});
 			} else if (channel.label.startsWith('file:')) {
 				// 跟踪 file DC 用于诊断 dump：保留全量历史以便排查"传输到一半挂掉"场景，
 				// 但用 FIFO 上限避免长会话内无界增长
@@ -486,29 +545,27 @@ export class WebRtcPeer {
 		}
 	}
 
-	__setupDataChannel(connId, dc) {
-		// rpc DC 发送流控：每条 rpc DC 绑定一个 RpcSendQueue，广播与 files RPC 响应均经此出口
+	async __setupDataChannel(connId, dc) {
+		// rpc DC 发送流控：MemoryQueue（admission + 边沿日志）+ RpcDcSender（分片 + 背压）
+		// 通过消费循环串起来。广播 / sendTo / files sendFn 都向 queue.enqueue，sender 从 queue 拉
 		const session = this.__sessions.get(connId);
-		if (session && dc.label === 'rpc') {
-			if ('bufferedAmountLowThreshold' in dc) {
-				dc.bufferedAmountLowThreshold = DC_LOW_WATER_MARK;
-			}
-			session.rpcSendQueue = new RpcSendQueue({
-				dc,
-				maxMessageSize: session.remoteMaxMessageSize,
-				getNextMsgId: () => session.nextMsgId++,
-				logger: this.logger,
-				tag: `conn=${connId}`,
-			});
-			dc.onbufferedamountlow = () => {
-				session.rpcSendQueue?.onBufferedAmountLow();
-			};
-		}
 
+		// === 同步部分（首个 await 前）：wire dc handlers ===
+		// reassembler / dc.onopen / dc.onclose / dc.onerror / dc.onmessage 必须在 async fn 的
+		// 同步部分 wire 完成；ondatachannel 是 WebRTC 实现的 sync 回调，调方调用后立即可能 dispatch
+		// 消息，handler 不能等 init 完才挂。stale dc 上的事件由 handler 内身份守卫吸收。
 		const reassembler = createReassembler((jsonStr) => {
 			const payload = JSON.parse(jsonStr);
+			// identity guard：与 dc.onclose 的 identity guard 对称。
+			// DC 重建后旧 dc 的 message event 仍可能在 microtask 队列里派发；若不核身份，旧请求会
+			// 注入 __onRequest 或 enqueue 到新 rpcQueue。session 已删除时（rpcChannel===null 或
+			// sess undefined）也按 stale 处理，避免向已清空的 session 注入消息。
+			const sess = this.__sessions.get(connId);
+			if (!sess || sess.rpcChannel !== dc) {
+				return;
+			}
 			// DC 探测：立即回复，不走 gateway
-			// 故意绕过 RpcSendQueue：probe-ack 仅用于测量传输层（SCTP/DTLS）健康，
+			// 故意绕过 MemoryQueue + RpcDcSender：probe-ack 仅用于测量传输层（SCTP/DTLS）健康，
 			// 走 queue 会把应用层积压压力错误地映射到"DC 不通"上。
 			if (payload.type === 'probe') {
 				try { dc.send(JSON.stringify({ type: 'probe-ack' })); }
@@ -523,7 +580,6 @@ export class WebRtcPeer {
 			if (payload.type === 'req') {
 				// coclaw.files.* 方法本地处理，不转发 gateway
 				if (payload.method?.startsWith('coclaw.files.') && this.__onFileRpc) {
-					const sess = this.__sessions.get(connId);
 					const sendFn = (response) => {
 						let jsonStr;
 						try {
@@ -533,7 +589,12 @@ export class WebRtcPeer {
 							return;
 						}
 						if (typeof jsonStr !== 'string') return;
-						sess?.rpcSendQueue?.send(jsonStr);
+						// fire-and-forget：files sendFn 历史是 sync void 接口，保留语义；
+						// admission 决策内部消化，失败由 overflow 状态机/close 汇总统一上报
+						sess?.rpcQueue?.enqueue(jsonStr).catch((err) => {
+							/* c8 ignore next -- enqueue 仅在 mutex 异常等极冷路径 reject */
+							this.__logDebug(`[${connId}] file sendFn enqueue error: ${err?.message}`);
+						});
 					};
 					this.__onFileRpc(payload, sendFn, connId);
 				} else {
@@ -551,7 +612,7 @@ export class WebRtcPeer {
 			// queueMicrotask 让出一次 CPU：确保 pion 侧 selectedCandidatePair setter 已 assign，
 			// 同时避免在 onopen 同步栈里触发可能的重入。
 			if (dc.label === 'rpc') {
-				queueMicrotask(() => this.__sendPeerTransport(connId));
+				queueMicrotask(() => { this.__sendPeerTransport(connId).catch(() => {}); });
 			}
 		};
 		dc.onclose = () => {
@@ -559,9 +620,17 @@ export class WebRtcPeer {
 			this.logger.info?.(`${this.__rtcTag} [${connId}] DataChannel "${dc.label}" closed`);
 			reassembler.reset();
 			const sess = this.__sessions.get(connId);
-			if (sess && dc.label === 'rpc') {
-				sess.rpcSendQueue?.close();
-				sess.rpcSendQueue = null;
+			// identity guard：仅当 sess.rpcChannel 仍是这个 dc 时才清三件套。
+			// 同 session 重建（UI 重建 rpc DC）后，旧 dc 的 onclose 可能滞后到达，此时
+			// session 已挂上新三件套；若不核身份，旧 dc 的 onclose 会瞬间杀死新链路
+			if (sess && dc.label === 'rpc' && sess.rpcChannel === dc) {
+				// dc.onclose 是 sync 回调，不能 await consumeLoop。仅触发 close + destroy；
+				// consumeLoop 通过 sender.close → SENDER_CLOSED → break + queue.destroy → done 自然退出
+				sess.rpcDcSender?.close();
+				sess.rpcQueue?.destroy().catch(() => {});
+				sess.rpcDcSender = null;
+				sess.rpcQueue = null;
+				sess.rpcConsumeLoop = null;
 				sess.rpcChannel = null;
 			}
 		};
@@ -577,6 +646,90 @@ export class WebRtcPeer {
 				this.logger.warn?.(`${this.__rtcTag} [${connId}] DC message error: ${err.message}`);
 			}
 		};
+
+		if (!session || dc.label !== 'rpc') return;
+
+		// === 异步部分：rpc 三件套（队列 / 发送器 / 消费循环）+ 身份守卫 ===
+		// 罕见：session 已有旧三件套（UI 重建 rpc DC 等）。先 await close + destroy 旧实例
+		// 再造新实例，避免新旧 queue/sender 在同一 session 上并存。await 的目的是让旧实例
+		// 完整收尾（FBQ 阶段对应底层 fs 残留清理），MemoryQueue 阶段 destroy 是 sync 完成。
+		if (session.rpcDcSender || session.rpcQueue) {
+			session.rpcDcSender?.close();
+			if (session.rpcQueue) await session.rpcQueue.destroy();
+			if (session.rpcConsumeLoop) await session.rpcConsumeLoop.catch(() => { /* c8 ignore next -- 极冷防御 */ });
+		}
+		// 构造 queue 并 await init。MemoryQueue.init 是 no-op；保留 await 占位，FBQ 阶段
+		// init 承担 fs 残留清理。await 期间可能发生 closeByConnId / 同 connId 二次 ondatachannel，
+		// 因此后面必须身份重核才能赋 session 字段。
+		const queue = new MemoryQueue({
+			id: connId,
+			maxMessageBytes: MAX_SINGLE_MSG_BYTES,
+			bypassAdmission: isAgentRunResponse,
+			logger: this.logger,
+			tag: `conn=${connId}`,
+		});
+		await queue.init();
+		// 身份重核：init 期间 session 可能被 closeByConnId 从 Map 删除，或被同 connId 二次
+		// ondatachannel 把 rpcChannel 替换成新 dc。任一不再成立都视为 stale，destroy queue 后
+		// 直接退出，绝不污染 session 三件套字段。
+		const sessAfter = this.__sessions.get(connId);
+		if (sessAfter !== session || session.rpcChannel !== dc) {
+			await queue.destroy();
+			return;
+		}
+		if ('bufferedAmountLowThreshold' in dc) {
+			dc.bufferedAmountLowThreshold = DC_LOW_WATER_MARK;
+		}
+		const sender = new RpcDcSender({
+			dc,
+			maxMessageSize: session.remoteMaxMessageSize,
+			getNextMsgId: () => session.nextMsgId++,
+			logger: this.logger,
+			tag: `conn=${connId}`,
+		});
+		session.rpcQueue = queue;
+		session.rpcDcSender = sender;
+		// 闭包捕获本次 sender 局部引用，而不是读 session.rpcDcSender 字段。
+		// 同 session rebuild 后字段会指向新 sender，旧 dc 的 BAL 滞后事件若读字段
+		// 会错唤醒新 sender；捕获局部引用后旧 dc 触发 BAL 调的是已 close 的旧 sender，
+		// onBufferedAmountLow 在 splice 空 waiter 数组上无副作用
+		dc.onbufferedamountlow = () => {
+			sender.onBufferedAmountLow();
+		};
+		// 起消费循环：从 queue 拉一条 → await sender.send()。sender close 时循环 break。
+		// finally 兜底关闭：覆盖 dc.send 中途抛错 / 异常退出场景——dc.onclose 不一定会及时
+		// 触发清理（如 readyState 短暂 open 但 send 失败），主动 close+destroy 避免 queue/sender
+		// 残留导致后续 broadcast 入队后无人消费。两个 close/destroy 都幂等。
+		session.rpcConsumeLoop = (async () => {
+			try {
+				for await (const str of queue) {
+					try {
+						await sender.send(str);
+					} catch (err) {
+						if (err.code === 'SENDER_CLOSED') break;
+						// safe-wrap：logger.warn 自身抛不能让消费循环挂掉
+						try { this.logger.warn?.(`${this.__rtcTag} [${connId}] rpc-dc.send-failed code=${err.code} size=${str.length}`); }
+						/* c8 ignore next -- logger 自身抛是极冷防御路径 */
+						catch { /* swallow */ }
+					}
+				}
+			} finally {
+				sender.close();
+				await queue.destroy().catch(() => {});
+				// 防御性清字段：若 loop 因 sender 内部错误自行退出（dc.onclose / closeByConnId
+				// 都不是触发方），三字段会暂留非 null 直到 dc.onclose 最终到达。期间 producer
+				// 看到非 null 会以为通道活着——虽然 enqueue 安全返 false，但减少误导窗口。
+				// 身份比对避免误清"dc.onclose 已先清掉、并被新一轮 setup 装入新实例"的字段。
+				if (session.rpcQueue === queue) {
+					session.rpcQueue = null;
+					session.rpcDcSender = null;
+					session.rpcConsumeLoop = null;
+				}
+			}
+		})();
+		// unhandled rejection 防御：循环 promise 自身极少抛（仅 iterator 实现 bug），但
+		// 一旦逃逸为 unhandled rejection 会让 plugin/gateway 进程退出
+		session.rpcConsumeLoop.catch(() => {});
 	}
 
 	/**
@@ -586,9 +739,15 @@ export class WebRtcPeer {
 	__dumpSessionState(connId, session, state) {
 		const rpcState = session.rpcChannel?.readyState ?? 'none';
 		const fileSummary = this.__summarizeFileChannels(session.fileChannels);
-		const q = session.rpcSendQueue;
+		const q = session.rpcQueue;
 		const queueInfo = q
-			? `queueLen=${q.queue.length} queueBytes=${q.queueBytes} dropped=${q.droppedCount}`
+			? (() => {
+				const s = q.stats();
+				// memCount 沿用历史 token 名 queueLen（不改名）；其余 5 个 stats 字段保持
+				// 与 stats() 内部同名输出。Phase A 阶段 4 个磁盘字段恒为 0/false，是给
+				// Phase B 切 FBQ 留形状的占位。
+				return `queueLen=${s.memCount} queueBytes=${s.memBytes} diskBytes=${s.diskBytes} writtenBytes=${s.writtenBytes} spilled=${s.spilled} fsBroken=${s.fsBroken} dropped=${s.droppedCount} droppedBytes=${s.droppedBytes}`;
+			})()
 			: 'queue=none';
 		this.__remoteLog(`rtc.dump conn=${connId} state=${state} sessions=${this.__sessions.size} rpc=${rpcState} ${queueInfo} fileCount=${session.fileChannels.size} files=[${fileSummary}]`);
 		this.logger.info?.(`${this.__rtcTag} [${connId}] dump state=${state} rpc=${rpcState} ${queueInfo} fileCount=${session.fileChannels.size} files=${fileSummary}`);
@@ -668,7 +827,7 @@ export class WebRtcPeer {
 	 *
 	 * @param {string} connId
 	 */
-	__sendPeerTransport(connId) {
+	async __sendPeerTransport(connId) {
 		const session = this.__sessions.get(connId);
 		if (!session) return;
 		const local = session.pc?.selectedCandidatePair?.local;
@@ -683,13 +842,14 @@ export class WebRtcPeer {
 		const sig = `${payload.candidateType}|${payload.protocol}|${payload.relayProtocol ?? ''}`;
 		if (session.__lastPeerTransportSig === sig) return;
 		session.__lastPeerTransportSig = sig;
-		const ok = this.sendTo(connId, {
+		// sendTo 阶段 1 改 async：await admission 决策结果
+		const ok = await this.sendTo(connId, {
 			type: 'event',
 			event: 'coclaw.rtc.peerTransport',
 			payload,
 		});
 		if (!ok) {
-			// DC 尚未 open，回滚签名以便 dc.onopen 再次触发时重发
+			// DC 尚未 open / 队列拒收：回滚签名以便 dc.onopen 再次触发时重发
 			session.__lastPeerTransportSig = null;
 			return;
 		}
@@ -699,7 +859,7 @@ export class WebRtcPeer {
 	/**
 	 * 主动探针：在 rpc DC 上发一个 plugin-probe，期待 UI 回 plugin-probe-ack。
 	 * 用于区分"pion 报告 connected 但 UI 其实没收到数据"与"UI 真的收到了但没记录事件"。
-	 * 绕过 RpcSendQueue（与 probe-ack 对称），仅测量传输层，不受应用层积压影响。
+	 * 绕过 MemoryQueue + RpcDcSender（与 probe-ack 对称），仅测量传输层，不受应用层积压影响。
 	 * 同一 session 同时只保留一条 in-flight 探针；超时仅打日志，不影响业务恢复。
 	 */
 	__sendPluginProbe(connId) {