@coclaw/openclaw-coclaw 0.17.0 → 0.17.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coclaw/openclaw-coclaw",
-  "version": "0.17.0",
+  "version": "0.17.2",
   "type": "module",
   "license": "Apache-2.0",
   "description": "OpenClaw CoClaw channel plugin for remote chat",
@@ -58,7 +58,7 @@
     "release:versions": "npm view @coclaw/openclaw-coclaw versions --json --registry=https://registry.npmjs.org/ && npm view @coclaw/openclaw-coclaw versions --json"
   },
   "dependencies": {
-    "@coclaw/pion-node": "^0.1.3",
+    "@coclaw/pion-node": "^0.3.0",
     "werift": "^0.19.0",
     "ws": "^8.19.0"
   },

package/src/realtime-bridge.js

@@ -659,6 +659,14 @@ export class RealtimeBridge {
 				return;
 			}
 			if (payload.type === 'res' || payload.type === 'event') {
+				// 过滤 gateway 的管理层广播事件，这些对 WebChat / plugin 客户端无意义：
+				// - health: 全量状态快照（~3KB, ~60s 一次 + RPC 触发），给 Admin UI 的监控仪表盘用
+				// - tick: gateway WS 保活心跳（30s 一次），UI 隔着 DC 不需要，DC 自己有 probe 机制
+				// 不转发可避免后台时 rpc DC 队列被灌满。上游支持按需订阅前先在插件侧拦截。
+				if (payload.type === 'event'
+					&& (payload.event === 'health' || payload.event === 'tick')) {
+					return;
+				}
 				this.webrtcPeer?.broadcast(payload);
 			}
 		});

package/src/utils/file-backed-queue.js

@@ -0,0 +1,375 @@
+/**
+ * 文件回退队列：内存优先，超过预算后追加写入 JSONL 文件。
+ * 业务无关纯工具：存储任意字符串（调用方需保证不含裸 `\n`，否则行分隔语义被破坏）。
+ *
+ * 行为约定详见 docs/rpc-dc-file-queue.md。
+ * - FIFO、单一生产者／消费者；多消费者时每条只交付给其中一个。
+ * - 构造时清理目录残留（不跨生命周期复用）。
+ * - 消费侧：`for await (const item of queue) { ... }`；`destroy()` 让迭代结束。
+ */
+
+import fs from 'node:fs/promises';
+import { createReadStream, createWriteStream, rmSync } from 'node:fs';
+import nodePath from 'node:path';
+import readline from 'node:readline';
+
+import { createMutex } from './mutex.js';
+
+const DEFAULT_MEM_BUDGET = 8 * 1024 * 1024;
+const DEFAULT_DISK_CAP = 1024 * 1024 * 1024;
+
+class FileBackedQueue {
+	/**
+	 * @param {object} opts
+	 * @param {string} opts.dir - 队列文件根目录
+	 * @param {string} opts.id - 队列标识（用于子目录命名）
+	 * @param {number} [opts.memBudget=8MB] - 内存持有字节数上限
+	 * @param {number} [opts.diskCap=1GB] - 磁盘+内存总字节数硬上限
+	 * @param {(reason: string, size: number) => void} [opts.onDrop] - 拒入队时的回调
+	 * @param {{ warn?: Function, info?: Function, error?: Function }} [opts.logger=console]
+	 */
+	constructor(opts) {
+		const {
+			dir,
+			id,
+			memBudget = DEFAULT_MEM_BUDGET,
+			diskCap = DEFAULT_DISK_CAP,
+			onDrop,
+			logger = console,
+		} = opts ?? {};
+
+		if (!dir || typeof dir !== 'string') throw new TypeError('dir is required');
+		if (!id || typeof id !== 'string') throw new TypeError('id is required');
+
+		this.dir = dir;
+		this.id = id;
+		this.memBudget = memBudget;
+		this.diskCap = diskCap;
+		this.onDrop = onDrop;
+		this.logger = logger;
+
+		this.subdir = nodePath.join(dir, id);
+		this.filePath = nodePath.join(this.subdir, 'queue.jsonl');
+
+		this.memQueue = [];
+		this.memBytes = 0;
+		this.diskBytes = 0;       // 磁盘上未消费的 payload 字节（不含分隔 \n）
+		this.writtenBytes = 0;    // 已写入文件的累计字节（含 \n）
+		this.readOffset = 0;      // 下次 refill 的起始偏移
+		this.spilled = false;
+		this.destroyed = false;
+		this.writeStream = null;
+		this.writeErr = null;
+		this.waiters = [];
+		this.mutex = createMutex();
+
+		// 防御性清理：不跨生命周期复用旧数据
+		try {
+			rmSync(this.subdir, { recursive: true, force: true });
+		} catch (err) {
+			/* c8 ignore next 2 -- rmSync with force rarely fails on posix */
+			this.logger?.warn?.('fbq.construct cleanup error', err);
+		}
+	}
+
+	/**
+	 * 入队一条字符串。
+	 * @param {string} jsonStr
+	 * @returns {Promise<boolean>} accepted（true）/ dropped（false）
+	 */
+	async enqueue(jsonStr) {
+		return await this.mutex.withLock(async () => {
+			if (this.destroyed) return false;
+			if (typeof jsonStr !== 'string') throw new TypeError('jsonStr must be a string');
+
+			const size = Buffer.byteLength(jsonStr, 'utf8');
+
+			if (this.memBytes + this.diskBytes + size > this.diskCap) {
+				this.__dispatchDrop('disk-cap', size);
+				return false;
+			}
+
+			// 内存路径：未溢出且加上新条目仍在预算内
+			if (!this.spilled && this.memBytes + size <= this.memBudget) {
+				this.memQueue.push(jsonStr);
+				this.memBytes += size;
+				this.__wakeOne();
+				return true;
+			}
+
+			// 溢出路径：lazy 打开写流
+			if (!this.spilled) {
+				await this.__openWriteStream();
+				if (this.writeErr) {
+					this.__dispatchDrop('fs-error', size);
+					return false;
+				}
+				this.spilled = true;
+			}
+
+			try {
+				await this.__writeLine(jsonStr + '\n');
+				this.diskBytes += size;
+				this.writtenBytes += size + 1;
+				this.__wakeOne();
+				return true;
+			} catch (err) {
+				this.logger?.warn?.('fbq.enqueue fs-error', err);
+				this.__dispatchDrop('fs-error', size);
+				return false;
+			}
+		});
+	}
+
+	/**
+	 * @returns {{ memCount: number, memBytes: number, diskBytes: number, spilled: boolean }}
+	 */
+	stats() {
+		return {
+			memCount: this.memQueue.length,
+			memBytes: this.memBytes,
+			diskBytes: this.diskBytes,
+			spilled: this.spilled,
+		};
+	}
+
+	/**
+	 * 清空数据但保留实例可用。
+	 */
+	async clear() {
+		return await this.mutex.withLock(async () => {
+			if (this.destroyed) return;
+			await this.__closeWriteStream();
+			try {
+				await fs.rm(this.filePath, { force: true });
+			} catch (err) {
+				/* c8 ignore next 2 -- rm with force rarely fails */
+				this.logger?.warn?.('fbq.clear rm error', err);
+			}
+			this.memQueue = [];
+			this.memBytes = 0;
+			this.diskBytes = 0;
+			this.writtenBytes = 0;
+			this.readOffset = 0;
+			this.spilled = false;
+			this.writeErr = null;
+		});
+	}
+
+	/**
+	 * 停写、关 FD、删目录、结束所有迭代器。幂等。
+	 */
+	async destroy() {
+		return await this.mutex.withLock(async () => {
+			if (this.destroyed) return;
+			this.destroyed = true;
+
+			// 唤醒所有等待者，让它们在下一轮循环中看到 destroyed 并返回 done
+			const toWake = this.waiters.splice(0);
+			for (const w of toWake) w.resolve();
+
+			await this.__closeWriteStream();
+			try {
+				await fs.rm(this.subdir, { recursive: true, force: true });
+			} catch (err) {
+				/* c8 ignore next 2 -- rm with force rarely fails */
+				this.logger?.warn?.('fbq.destroy rm error', err);
+			}
+
+			this.memQueue = [];
+			this.memBytes = 0;
+			this.diskBytes = 0;
+			this.writtenBytes = 0;
+			this.readOffset = 0;
+			this.spilled = false;
+		});
+	}
+
+	[Symbol.asyncIterator]() {
+		const self = this;
+		return {
+			next() { return self.__nextIter(); },
+			return() { return Promise.resolve({ done: true, value: undefined }); },
+			[Symbol.asyncIterator]() { return this; },
+		};
+	}
+
+	async __nextIter() {
+		while (true) {
+			let waitPromise = null;
+			const result = await this.mutex.withLock(async () => {
+				if (this.memQueue.length === 0 && this.spilled && !this.destroyed) {
+					await this.__refillImpl();
+				}
+				if (this.memQueue.length > 0) {
+					const item = this.memQueue.shift();
+					this.memBytes -= Buffer.byteLength(item, 'utf8');
+					return { value: item, done: false };
+				}
+				if (this.destroyed) return { done: true, value: undefined };
+				waitPromise = new Promise((resolve, reject) => {
+					this.waiters.push({ resolve, reject });
+				});
+				return null;
+			});
+			if (result !== null) return result;
+			await waitPromise;
+		}
+	}
+
+	__wakeOne() {
+		if (this.waiters.length > 0) {
+			const w = this.waiters.shift();
+			w.resolve();
+		}
+	}
+
+	__dispatchDrop(reason, size) {
+		try {
+			this.onDrop?.(reason, size);
+		} catch (err) {
+			/* c8 ignore next 2 -- onDrop throwing is caller's bug */
+			this.logger?.warn?.('fbq.onDrop threw', err);
+		}
+		this.logger?.warn?.('fbq.drop', { reason, size });
+	}
+
+	async __openWriteStream() {
+		this.writeErr = null;
+		try {
+			await fs.mkdir(this.subdir, { recursive: true });
+		} catch (err) {
+			this.writeErr = err;
+			return;
+		}
+		this.writeStream = createWriteStream(this.filePath, { flags: 'a' });
+		this.writeStream.on('error', (err) => {
+			this.writeErr = err;
+			this.logger?.warn?.('fbq.writeStream error', err);
+		});
+	}
+
+	async __writeLine(str) {
+		if (this.writeErr) throw this.writeErr;
+		return await new Promise((resolve, reject) => {
+			this.writeStream.write(str, (err) => {
+				if (err) reject(err);
+				else resolve();
+			});
+		});
+	}
+
+	async __closeWriteStream() {
+		if (!this.writeStream) return;
+		const stream = this.writeStream;
+		this.writeStream = null;
+		if (stream.destroyed || stream.writableEnded) return;
+		// 使用事件而非 end(cb)：errored 流上 end 的回调可能永不触发 → 死锁风险。
+		// 'close' 在正常结束后触发；'error' 在异常流上作为兜底。Promise 幂等。
+		await new Promise((resolve) => {
+			stream.once('close', resolve);
+			stream.once('error', resolve);
+			try {
+				stream.end();
+			/* c8 ignore next 3 -- stream.end 同步抛极少见 */
+			} catch {
+				resolve();
+			}
+		});
+	}
+
+	// 调用方必须已持有 mutex，且已确认 !destroyed
+	async __refillImpl() {
+		if (!this.spilled) return;
+
+		let actualEnd;
+		try {
+			const st = await fs.stat(this.filePath);
+			actualEnd = st.size;
+		} catch (err) {
+			/* c8 ignore next 3 -- stat 在正常持有期间不会失败 */
+			this.logger?.warn?.('fbq.refill stat error', err);
+			return;
+		}
+
+		if (this.readOffset >= actualEnd) {
+			await this.__dropFile();
+			return;
+		}
+
+		const newLines = [];
+		let cumBytes = 0;     // 文件字节：payload + \n
+		let cumPayload = 0;   // 仅 payload
+		let stoppedAtEof = true;
+
+		const stream = createReadStream(this.filePath, {
+			start: this.readOffset,
+			end: actualEnd - 1,
+		});
+		const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
+
+		try {
+			for await (const line of rl) {
+				const sz = Buffer.byteLength(line, 'utf8');
+				if (newLines.length > 0 && this.memBytes + cumPayload + sz > this.memBudget) {
+					stoppedAtEof = false;
+					break;
+				}
+				newLines.push(line);
+				cumBytes += sz + 1;
+				cumPayload += sz;
+			}
+		} catch (err) {
+			/* c8 ignore next 4 -- read 错误罕见，保守退出 */
+			this.logger?.warn?.('fbq.refill read error', err);
+			rl.close();
+			stream.destroy();
+			return;
+		} finally {
+			rl.close();
+			stream.destroy();
+		}
+
+		const availableBytes = actualEnd - this.readOffset;
+
+		if (stoppedAtEof && cumBytes > availableBytes) {
+			// 最后一行未终止（尾部 \n 缺失）：视为半截，丢弃
+			const partial = newLines.pop();
+			cumPayload -= Buffer.byteLength(partial, 'utf8');
+			this.logger?.warn?.('fbq.refill partial tail discarded', {
+				size: Buffer.byteLength(partial, 'utf8'),
+			});
+			// 将 readOffset 推到 writtenBytes，彻底丢弃尾部残片
+			this.readOffset = this.writtenBytes;
+		} else {
+			this.readOffset += cumBytes;
+		}
+
+		for (const line of newLines) {
+			this.memQueue.push(line);
+			this.memBytes += Buffer.byteLength(line, 'utf8');
+		}
+		this.diskBytes -= cumPayload;
+
+		if (this.readOffset >= this.writtenBytes) {
+			await this.__dropFile();
+		}
+	}
+
+	async __dropFile() {
+		await this.__closeWriteStream();
+		try {
+			await fs.rm(this.filePath, { force: true });
+		} catch (err) {
+			/* c8 ignore next 2 -- rm with force rarely fails */
+			this.logger?.warn?.('fbq.dropFile error', err);
+		}
+		this.spilled = false;
+		this.writtenBytes = 0;
+		this.readOffset = 0;
+		this.diskBytes = 0;
+		this.writeErr = null;
+	}
+}
+
+export { FileBackedQueue };

package/src/webrtc/rpc-send-queue.js

@@ -62,6 +62,10 @@ export class RpcSendQueue {
 	send(jsonStr) {
 		if (this.closed || this.dc.readyState !== 'open') return false;
 
+		// 诊断日志：打印每次入队的事件，跟踪 gateway 还会推哪些事件
+		// 需要时临时打开，平时保持注释避免日志噪音
+		// this.logger.info?.(`[rpc-queue${this.__tagSuffix()}] send-payload ${jsonStr}`);
+
 		const chunks = buildChunks(jsonStr, this.maxMessageSize, this.getNextMsgId);
 		const totalBytes = chunks
 			? chunks.reduce((n, c) => n + c.length, 0)
@@ -80,6 +84,8 @@ export class RpcSendQueue {
 			this.droppedCount += 1;
 			this.droppedBytes += totalBytes;
 			this.logger.warn?.(`[rpc-queue${this.__tagSuffix()}] drop reason=queue-full size=${totalBytes} queueBytes=${this.queueBytes}`);
+			// 诊断日志：定位后台长时间占队的事件来源。需要时临时打开
+			// this.logger.info?.(`[rpc-queue${this.__tagSuffix()}] dropped-payload ${jsonStr}`);
 			if (!this.queueOverflowActive) {
 				this.queueOverflowActive = true;
 				remoteLog(`rpc-queue.overflow-start${this.__tagSuffix()} queueBytes=${this.queueBytes}`);

package/src/webrtc/webrtc-peer.js

@@ -69,6 +69,17 @@ export class WebRtcPeer {
 			clearTimeout(session.__failedTimer);
 			session.__failedTimer = null;
 		}
+		// 清理 plugin-probe 定时器（避免 session 已关闭仍触发 timeout 日志，
+		// 或 500ms 调度窗口内 session 被替换时对着新 session 误发探针）
+		if (session.__pluginProbeSchedTimer) {
+			clearTimeout(session.__pluginProbeSchedTimer);
+			session.__pluginProbeSchedTimer = null;
+		}
+		if (session.__pluginProbeTimer) {
+			clearTimeout(session.__pluginProbeTimer);
+			session.__pluginProbeTimer = null;
+			session.__pluginProbeInFlight = null;
+		}
 		this.__sessions.delete(connId);
 		// 显式关闭 rpc 发送队列：dc.onclose 路径中 `sessions.get(connId)` 已返回 undefined 而短路，
 		// 此处不主动 close 会丢失 drop 汇总 remoteLog 诊断
@@ -83,6 +94,9 @@ export class WebRtcPeer {
 		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`);
@@ -175,6 +189,7 @@ export class WebRtcPeer {
 						toConnId: connId,
 						payload: { sdp: answer.sdp },
 					});
+					this.__remoteLog(`rtc.restart-answer-sent conn=${connId}`);
 					this.logger.info?.(`${this.__rtcTag} ICE restart answer sent to ${connId}`);
 					return;
 				} catch (err) {
@@ -237,7 +252,14 @@ export class WebRtcPeer {
 		const turnUrl = iceServers.find((s) => s.urls?.startsWith('turn:'))?.urls ?? 'none';
 		this.__remoteLog(`rtc.ice-config conn=${connId} stun=${stunUrl} turn=${turnUrl}`);
 
-		const pc = new this.__PeerConnection({ iceServers });
+		// settings 仅对 pion 生效：werift 路径不吃 settings 字段（大概率静默忽略，
+		// 但按 __impl 分层更干净）。只收紧 pion 的 SCTP RTO 退避上限到 10s，
+		// 让 APK 后台唤醒后的深度退避窗口能落在 UI 的 15s 超时内。
+		const pcConfig = { iceServers };
+		if (this.__impl === 'pion') {
+			pcConfig.settings = { sctpRtoMax: 10000 };
+		}
+		const pc = new this.__PeerConnection(pcConfig);
 
 		const remoteMaxMessageSize = this.__resolveMaxMessageSize(pc, msg.payload.sdp);
 
@@ -245,11 +267,24 @@ export class WebRtcPeer {
 		this.__sessions.set(connId, session);
 
 		// ICE candidate → 发给 UI，并统计各类型 candidate 数量
+		// gather complete 时一并输出 host 候选的 IP:port 列表（诊断 docker/vbridge 误 gather）
 		const candidateCounts = { host: 0, srflx: 0, relay: 0 };
+		const hostAddrs = [];
+		let gatheringEmitted = false;
+		const flushGatherDiag = () => {
+			if (gatheringEmitted) return;
+			gatheringEmitted = true;
+			const hostInfo = hostAddrs.length ? ` hosts=${hostAddrs.join(',')}` : '';
+			this.__remoteLog(`rtc.ice-gathered conn=${connId} host=${candidateCounts.host} srflx=${candidateCounts.srflx} relay=${candidateCounts.relay}${hostInfo}`);
+			candidateCounts.host = 0;
+			candidateCounts.srflx = 0;
+			candidateCounts.relay = 0;
+			hostAddrs.length = 0;
+		};
 		pc.onicecandidate = ({ candidate }) => {
 			if (!candidate) {
-				// gathering 完成，输出汇总
-				this.__remoteLog(`rtc.ice-gathered conn=${connId} host=${candidateCounts.host} srflx=${candidateCounts.srflx} relay=${candidateCounts.relay}`);
+				// 浏览器路径：gathering 完成通过 null candidate 通知
+				flushGatherDiag();
 				return;
 			}
 			// 从 candidate 字符串中提取类型（typ host / typ srflx / typ relay）
@@ -257,6 +292,14 @@ export class WebRtcPeer {
 			if (typMatch && candidateCounts[typMatch[1]] !== undefined) {
 				candidateCounts[typMatch[1]]++;
 			}
+			// host 候选记录 addr:port，用于观察 pion 是否把 docker0 / br-* / loopback 等接口当成 host
+			// candidate 格式: "candidate:<foundation> <comp> <proto> <prio> <ADDR> <PORT> typ host ..."
+			if (typMatch?.[1] === 'host') {
+				const parts = candidate.candidate.split(' ');
+				if (parts.length >= 6) {
+					hostAddrs.push(`${parts[4]}:${parts[5]}`);
+				}
+			}
 			this.__onSend({
 				type: 'rtc:ice',
 				toConnId: connId,
@@ -267,6 +310,29 @@ export class WebRtcPeer {
 				},
 			});
 		};
+		// pion-node 不会在 gather complete 时 fire onicecandidate(null)，用 icegatheringstatechange 兜底。
+		// gathering→ 重置 flag 支持 ICE restart；complete→ flush 汇总
+		if ('onicegatheringstatechange' in pc) {
+			pc.onicegatheringstatechange = () => {
+				const state = pc.iceGatheringState;
+				if (state === 'gathering') {
+					gatheringEmitted = false;
+				} else if (state === 'complete') {
+					flushGatherDiag();
+				}
+			};
+		}
+
+		// ICE agent 状态（pion 暴露的独立事件）：能看到 checking / connected / failed 等纯 ICE 侧跳转，
+		// 与复合 connectionState 互补。对诊断"pion 说 connected 但 UI 看不到数据"非常关键。
+		// 仅在 pion-node 实现中可用；其他实现赋值是 no-op。
+		if ('oniceconnectionstatechange' in pc) {
+			pc.oniceconnectionstatechange = () => {
+				const cur = this.__sessions.get(connId);
+				if (!cur || cur.pc !== pc) return;
+				this.__remoteLog(`rtc.iceState conn=${connId} ${pc.iceConnectionState ?? '?'}`);
+			};
+		}
 
 		// 连接状态变更（校验 pc 归属，防止旧 PC 异步回调删除新 session）
 		pc.onconnectionstatechange = () => {
@@ -285,6 +351,7 @@ export class WebRtcPeer {
 			}
 
 			if (state === 'connected') {
+				const prevDumpState = cur.__lastDumpState;
 				// 重置 dump 去重水位（disconnected → connected → disconnected 仍能再 dump）
 				cur.__lastDumpState = null;
 				// werift: iceTransports[0].connection.nominated
@@ -298,6 +365,22 @@ export class WebRtcPeer {
 					this.logger.info?.(`${this.__rtcTag} [${connId}] ICE nominated: local=${localInfo} remote=${remoteInfo}`);
 				}
 				// pion: pair 通过独立的 selectedcandidatepairchange 事件上报
+				// ICE restart 恢复（disconnected/failed → connected）时做诊断动作：
+				// - dump 当前 session DC 状态，对照"UI 看不到 connected 时 plugin 侧看到什么"
+				// - 发一次 plugin-probe，实测 DC 是否双向可用
+				// 只对 pion 生效：werift/ndc 为兼容路径，不涉及本次调查的病态场景。
+				if (this.__impl === 'pion' && (prevDumpState === 'disconnected' || prevDumpState === 'failed')) {
+					this.__dumpSessionState(connId, cur, 'connected');
+					// 挂到 session 上，使 closeByConnId 能在 500ms 窗口内取消；
+					// 否则 session 被替换（同 connId 新 offer）时会对着新 session 误发探针。
+					if (cur.__pluginProbeSchedTimer) clearTimeout(cur.__pluginProbeSchedTimer);
+					cur.__pluginProbeSchedTimer = setTimeout(() => {
+						cur.__pluginProbeSchedTimer = null;
+						this.__sendPluginProbe(connId);
+					}, 500);
+					// unref() 避免定时器阻塞 gateway 进程退出（gateway 由其他连接保活）。
+					cur.__pluginProbeSchedTimer.unref?.();
+				}
 			} else if (state === 'disconnected' || state === 'failed' || state === 'closed') {
 				// 诊断 dump：失败/断连/关闭时输出当前 PC 上 DC 状态，定位"PC 假活/DC 死"现象
 				// - closed 由 closeByConnId 接管清理，dump 收敛诊断噪声
@@ -427,6 +510,11 @@ export class WebRtcPeer {
 				catch { /* DC 已关闭，忽略 */ }
 				return;
 			}
+			// 来自 UI 的 plugin-probe 回复：验证 plugin → UI 方向确实传达并被回传
+			if (payload.type === 'plugin-probe-ack') {
+				this.__handlePluginProbeAck(connId, payload.id);
+				return;
+			}
 			if (payload.type === 'req') {
 				// coclaw.files.* 方法本地处理，不转发 gateway
 				if (payload.method?.startsWith('coclaw.files.') && this.__onFileRpc) {
@@ -488,16 +576,57 @@ export class WebRtcPeer {
 	 */
 	__dumpSessionState(connId, session, state) {
 		const rpcState = session.rpcChannel?.readyState ?? 'none';
-		const fileSummary = session.fileChannels.size === 0
-			? 'none'
-			/* c8 ignore next -- ?? fallback for missing readyState */
-			: [...session.fileChannels].map((dc) => `${dc.label}=${dc.readyState ?? '?'}`).join(',');
+		const fileSummary = this.__summarizeFileChannels(session.fileChannels);
 		const q = session.rpcSendQueue;
 		const queueInfo = q
 			? `queueLen=${q.queue.length} queueBytes=${q.queueBytes} dropped=${q.droppedCount}`
 			: '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}`);
+		// 仅 pion 路径追加 SCTP 采样：cwnd 是否塌回 1×MTU + bytesSent 增量是否 ~0
+		// 是判定"是否陷入深度 RTO 退避"的关键。fire-and-forget + 内部 try/catch
+		// 双保险，不阻塞 dump 主流程；rtc.sctp 独立一行避免污染既有 rtc.dump 格式。
+		if (this.__impl === 'pion' && typeof session.pc.getSctpStats === 'function') {
+			this.__dumpSctpStats(connId, session, state).catch(() => {});
+		}
+	}
+
+	/**
+	 * 按 readyState 聚合 file DC。closed 态只给计数，非 closed 态附带 label —
+	 * 长会话内已关闭的 DC 会累积到 FIFO 上限，全量拼 label 会让 dump 膨胀，
+	 * 而断连时真正有诊断价值的是"还没关干净"的 DC。
+	 */
+	__summarizeFileChannels(fileChannels) {
+		if (fileChannels.size === 0) return 'none';
+		const byState = new Map();
+		for (const dc of fileChannels) {
+			/* c8 ignore next -- ?? fallback for missing readyState */
+			const st = dc.readyState ?? '?';
+			if (!byState.has(st)) byState.set(st, []);
+			byState.get(st).push(dc.label);
+		}
+		const parts = [];
+		for (const [st, labels] of byState) {
+			if (st === 'closed') parts.push(`closed:${labels.length}`);
+			else parts.push(`${st}:${labels.length}(${labels.join(',')})`);
+		}
+		return parts.join(' ');
+	}
+
+	async __dumpSctpStats(connId, session, state) {
+		try {
+			const stats = await session.pc.getSctpStats();
+			if (!stats) {
+				this.__remoteLog(`rtc.sctp conn=${connId} state=${state} sctp=none`);
+				return;
+			}
+			this.__remoteLog(
+				`rtc.sctp conn=${connId} state=${state} cwnd=${stats.congestionWindow} srtt=${Math.round(stats.srttMs)}ms sent=${stats.bytesSent} recv=${stats.bytesReceived} mtu=${stats.mtu}`,
+			);
+		} catch (err) {
+			this.__remoteLog(`rtc.sctp conn=${connId} state=${state} error=${err.message}`);
+			this.logger.warn?.(`${this.__rtcTag} [${connId}] getSctpStats error: ${err.message}`);
+		}
 	}
 
 	/**
@@ -558,6 +687,59 @@ export class WebRtcPeer {
 		this.__remoteLog(`rtc.peer-transport conn=${connId} type=${payload.candidateType} proto=${payload.protocol} relay=${payload.relayProtocol ?? '-'}`);
 	}
 
+	/**
+	 * 主动探针：在 rpc DC 上发一个 plugin-probe，期待 UI 回 plugin-probe-ack。
+	 * 用于区分"pion 报告 connected 但 UI 其实没收到数据"与"UI 真的收到了但没记录事件"。
+	 * 绕过 RpcSendQueue（与 probe-ack 对称），仅测量传输层，不受应用层积压影响。
+	 * 同一 session 同时只保留一条 in-flight 探针；超时仅打日志，不影响业务恢复。
+	 */
+	__sendPluginProbe(connId) {
+		const session = this.__sessions.get(connId);
+		if (!session) return;
+		const dc = session.rpcChannel;
+		if (!dc || dc.readyState !== 'open') return;
+		// 已有 in-flight 则跳过（避免重复）
+		if (session.__pluginProbeInFlight) return;
+
+		const id = (session.__pluginProbeIdSeq = (session.__pluginProbeIdSeq ?? 0) + 1);
+		const startMs = Date.now();
+		const timer = setTimeout(() => {
+			if (session.__pluginProbeInFlight?.id === id) {
+				session.__pluginProbeInFlight = null;
+				session.__pluginProbeTimer = null;
+				this.__remoteLog(`rtc.plugin-probe conn=${connId} id=${id} timeout`);
+			}
+		}, 5000);
+		timer.unref?.();
+		session.__pluginProbeInFlight = { id, startMs };
+		session.__pluginProbeTimer = timer;
+
+		try {
+			dc.send(JSON.stringify({ type: 'plugin-probe', id }));
+			this.__remoteLog(`rtc.plugin-probe conn=${connId} id=${id} sent`);
+		} catch (err) {
+			clearTimeout(timer);
+			session.__pluginProbeInFlight = null;
+			session.__pluginProbeTimer = null;
+			this.__remoteLog(`rtc.plugin-probe conn=${connId} id=${id} send-failed msg=${err?.message ?? err}`);
+		}
+	}
+
+	/** 收到 UI 的 plugin-probe-ack：计算 RTT 并释放 in-flight 槽位 */
+	__handlePluginProbeAck(connId, id) {
+		const session = this.__sessions.get(connId);
+		if (!session) return;
+		const inFlight = session.__pluginProbeInFlight;
+		if (!inFlight || inFlight.id !== id) return; // 过期 ack，忽略
+		const rtt = Date.now() - inFlight.startMs;
+		if (session.__pluginProbeTimer) {
+			clearTimeout(session.__pluginProbeTimer);
+			session.__pluginProbeTimer = null;
+		}
+		session.__pluginProbeInFlight = null;
+		this.__remoteLog(`rtc.plugin-probe conn=${connId} id=${id} acked rtt=${rtt}`);
+	}
+
 	__remoteLog(msg) {
 		remoteLog(this.__impl ? `${msg} rtc=${this.__impl}` : msg);
 	}