@coclaw/openclaw-coclaw 0.16.0 → 0.17.1

package/README.md

@@ -172,22 +172,14 @@ openclaw gateway call coclaw.upgradeHealth --json
 
 ## WebRTC 实现
 
-插件支持两个 WebRTC 实现，运行时自动选择：
+插件在运行时按优先级选择 WebRTC 实现：
 
-1. **node-datachannel**（首选）— 基于 libdatachannel 的工业级实现，通过 vendor 预编译 native binary 部署。
-2. **werift**（回退）— 纯 JavaScript 实现，作为 node-datachannel 加载失败时的兜底。
+1. **pion**（主力）— 通过 `@coclaw/pion-node` SDK 驱动 Go 侧 pion-ipc 进程，实现完整 WebRTC 能力。
+2. **werift**（回退）— 纯 JavaScript 实现，作为 pion 加载失败时的兜底。
 
-选择结果通过 remoteLog 上报（`ndc.loaded` 或 `ndc.using-werift`）。
+选择结果通过 `bridge.started` / `coclaw.env impl=...` 日志上报。
 
-### vendor 预编译包
-
-由于 OpenClaw 使用 `--ignore-scripts` 安装插件，node-datachannel 的 native binary 需通过 vendor 预编译包提供：
-
-```bash
-bash scripts/download-ndc-prebuilds.sh   # 下载 5 平台预编译包到 vendor/ndc-prebuilds/
-```
-
-支持的平台：linux-x64、linux-arm64、darwin-x64、darwin-arm64、win32-x64。vendor 目录不入 git，通过 npm publish 的 `files` 字段包含在发布包中。
+> `ndc-preloader.js`（node-datachannel 路径）的代码仍保留但已摘除 `node-datachannel` 依赖和 vendor 预编译包（2026-04-19）——运行时必然走 fallback 到 werift，待 pion 在全部线上平台稳定观察期结束后与 werift 一并移除。
 
 ## 运行与排障日志
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coclaw/openclaw-coclaw",
-  "version": "0.16.0",
+  "version": "0.17.1",
   "type": "module",
   "license": "Apache-2.0",
   "description": "OpenClaw CoClaw channel plugin for remote chat",
@@ -32,7 +32,6 @@
     "!src/**/*.test.js",
     "!src/mock-server.helper.js",
     "openclaw.plugin.json",
-    "vendor/ndc-prebuilds/**",
     "LICENSE"
   ],
   "main": "index.js",
@@ -59,7 +58,6 @@
     "release:versions": "npm view @coclaw/openclaw-coclaw versions --json --registry=https://registry.npmjs.org/ && npm view @coclaw/openclaw-coclaw versions --json"
   },
   "dependencies": {
-    "node-datachannel": "0.32.2",
     "@coclaw/pion-node": "^0.1.3",
     "werift": "^0.19.0",
     "ws": "^8.19.0"

package/src/auto-upgrade/registry-fallback.js

@@ -0,0 +1,61 @@
+/**
+ * registry-fallback.js — npm registry 反向兜底
+ *
+ * 升级首次失败（timeout/429/网络异常等）后，按当前用户的 registry 选反方向源
+ * 再试一次：用户原本走 npmmirror 卡住时切到 npmjs；走 npmjs 卡住（如 IP 段被
+ * 限流）时切到 npmmirror。两侧任一可用即能脱困。
+ */
+import { execFile as nodeExecFile } from 'node:child_process';
+
+export const NPMJS_REGISTRY = 'https://registry.npmjs.org/';
+export const NPMMIRROR_REGISTRY = 'https://registry.npmmirror.com/';
+
+const DEFAULT_TIMEOUT_MS = 10_000;
+
+/**
+ * 读取当前 npm 默认 registry（继承用户 .npmrc 与 env）
+ *
+ * 失败 / 空字符串均回退到 npmjs URL；上层 pickFallbackRegistry 会据此选 npmmirror。
+ * 即"npm 命令本身坏掉时盲选 npmmirror"——在 worker 这种"反正只重试一次"的场景下
+ * 是合理代价。
+ *
+ * 调用方应优先传入 execFileFn 以避免在测试环境拉起真实 npm 进程。
+ * @param {object} [opts]
+ * @param {Function} [opts.execFileFn]
+ * @param {number} [opts.timeoutMs]
+ * @returns {Promise<string>}
+ */
+export function getCurrentNpmRegistry(opts) {
+	/* c8 ignore next -- ?./?? fallback */
+	const doExecFile = opts?.execFileFn ?? nodeExecFile;
+	/* c8 ignore next -- ?? fallback */
+	const timeout = opts?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	return new Promise((resolve) => {
+		doExecFile('npm', ['config', 'get', 'registry'], {
+			timeout,
+			shell: process.platform === 'win32',
+		}, (err, stdout) => {
+			if (err) { resolve(NPMJS_REGISTRY); return; }
+			const raw = String(stdout).trim();
+			resolve(raw || NPMJS_REGISTRY);
+		});
+	});
+}
+
+/**
+ * 根据当前 registry 选反向兜底：
+ * - 含 `npmmirror.com` → 切到 npmjs
+ * - 其他（含 npmjs / cnpmjs.org / 自建 / 非字符串等异常输入） → 一律切到 npmmirror
+ *
+ * "反向"语义只严格区分 npmmirror，因为它是国内绝对主流；其他国内镜像（cnpmjs 等）
+ * 当前直接切到 npmmirror（同方向但换实例），属于"换源"兜底而非真正反向，是有意为之
+ * 的简化。
+ * @param {string} current
+ * @returns {string}
+ */
+export function pickFallbackRegistry(current) {
+	if (typeof current === 'string' && /npmmirror\.com/i.test(current)) {
+		return NPMJS_REGISTRY;
+	}
+	return NPMMIRROR_REGISTRY;
+}

package/src/auto-upgrade/updater.js

@@ -7,7 +7,10 @@ import { readState, resolveStateDir, writeState } from './state.js';
 import { getRuntime } from '../runtime.js';
 import { remoteLog } from '../remote-log.js';
 
-const INITIAL_DELAY_MS = 5 * 60 * 1000; // 5 分钟
+// 首次检查延迟较长：失败时由 worker 触发 gateway restart，scheduler 重启后会重新计时；
+// 60 分钟基线（实际随机 60-120 分钟）能把"失败→重启→再次检查"的循环周期拉长，
+// 避免连续升级失败时 gateway 在短时间内反复被打扰。
+const INITIAL_DELAY_MS = 60 * 60 * 1000; // 60 分钟
 const CHECK_INTERVAL_MS = 60 * 60 * 1000; // 1 小时
 const CHANNEL_ID = 'coclaw';
 const LOCK_FILENAME = 'upgrade.lock';

package/src/auto-upgrade/worker.js

@@ -17,26 +17,35 @@ import { parseArgs } from 'node:util';
 import { createBackup, restoreFromBackup, removeBackup } from './worker-backup.js';
 import { verifyUpgrade, waitForGateway } from './worker-verify.js';
 import { addSkippedVersion, updateLastUpgrade, appendLog } from './state.js';
+import { getCurrentNpmRegistry, pickFallbackRegistry } from './registry-fallback.js';
 
 const SEMVER_RE = /^\d+\.\d+\.\d+(-[\w.-]+)?$/;
+// 单次 plugins update 上限：包含 npm install 大型 native deps，慢网络 + 弱机器需较长时间
+const UPDATE_TIMEOUT_MS = 10 * 60 * 1000;
 
 /**
  * 执行 openclaw plugins update
+ *
+ * 仅支持 source === "npm" 的安装（updater 已做前置过滤）。
+ * env 由调用方决定：缺省时子进程继承当前 process.env（含用户 .npmrc 自动生效）；
+ * 显式传入时用于覆盖 registry 等 npm 配置以做兜底重试。
  * @param {string} pluginId - 插件 ID
  * @param {object} [opts]
  * @param {Function} [opts.execFileFn]
+ * @param {NodeJS.ProcessEnv} [opts.env]
  * @returns {Promise<void>}
  */
-// openclaw plugins update 内部实现为 staged backup-and-replace，
-// 仅支持 source === "npm" 的安装（updater 已做前置过滤）
 function runPluginUpdate(pluginId, opts) {
 	/* c8 ignore next -- ?./?? fallback */
 	const doExecFile = opts?.execFileFn ?? nodeExecFile;
 	return new Promise((resolve, reject) => {
-		doExecFile('openclaw', ['plugins', 'update', pluginId], {
-			timeout: 120_000,
+		const execOpts = {
+			timeout: UPDATE_TIMEOUT_MS,
 			shell: process.platform === 'win32',
-		}, (err) => {
+		};
+		// 不传 env 时让 Node 默认继承父进程；显式 env 才覆盖
+		if (opts?.env) execOpts.env = opts.env;
+		doExecFile('openclaw', ['plugins', 'update', pluginId], execOpts, (err) => {
 			if (err) reject(new Error(`plugins update failed: ${err.message}`));
 			else resolve();
 		});
@@ -110,21 +119,44 @@ export async function runUpgrade({ pluginDir, fromVersion, toVersion, pluginId,
 	await createBackup(pluginDir);
 	log('[upgrade-worker] Backup created');
 
-	// 2. 执行升级
+	// 2. 执行升级（首次按用户原 env，失败后用反向 mirror 重试一次）
 	log('[upgrade-worker] Running plugins update...');
+	let updateErr = null;
 	try {
 		await runPluginUpdate(pluginId, opts);
+		log('[upgrade-worker] Update command completed');
+	}
+	catch (firstErr) {
+		log(`[upgrade-worker] Update command failed: ${firstErr.message}`);
+		updateErr = firstErr;
+		try {
+			const current = await getCurrentNpmRegistry(opts);
+			const fallback = pickFallbackRegistry(current);
+			log(`[upgrade-worker] Retrying with fallback registry: ${fallback}`);
+			// npm 同时认 npm_config_X 与 NPM_CONFIG_X 两种 env 命名，
+			// 若用户已 export 大写版（国内常见），仅 set 小写不足以覆盖，
+			// 显式 delete 大写避免 retry 仍走原 registry。
+			const retryEnv = { ...process.env };
+			delete retryEnv.NPM_CONFIG_REGISTRY;
+			retryEnv.npm_config_registry = fallback;
+			await runPluginUpdate(pluginId, { ...opts, env: retryEnv });
+			log('[upgrade-worker] Update command completed on retry');
+			updateErr = null;
+		}
+		catch (retryErr) {
+			log(`[upgrade-worker] Retry with fallback registry failed: ${retryErr.message}`);
+			updateErr = retryErr;
+		}
 	}
-	catch (updateErr) {
-		// 升级命令本身失败（可能是瞬态故障），恢复备份但不标记版本为 skipped
-		log(`[upgrade-worker] Update command failed: ${updateErr.message}`);
+
+	if (updateErr) {
+		// 两次都失败仍按瞬态故障处理（保留原 skipVersion: false 设计意图）
 		await handleRollback({
 			pluginDir, fromVersion, toVersion, pluginId, pkgName,
 			error: updateErr.message, skipVersion: false, opts, log,
 		});
 		return;
 	}
-	log('[upgrade-worker] Update command completed');
 
 	// 3. 等待 gateway 重启并验证
 	log('[upgrade-worker] Verifying upgrade...');

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/webrtc/ndc-preloader.js

@@ -46,6 +46,7 @@ export function defaultResolvePaths(platformKey, pluginRoot) {
 	// 定位 node-datachannel 包根：从入口路径向上查找 package.json
 	const require = createRequire(nodePath.join(pluginRoot, 'package.json'));
 	const entryPath = require.resolve('node-datachannel');
+	/* c8 ignore start -- node-datachannel 依赖已于 2026-04-19 摘除，以下路径仅在 ndc 实际安装时命中；代码保留作为过渡期 fallback 自然失败锚点，待 ndc-preloader 整体清理时一并删除 */
 	let pkgRoot = nodePath.dirname(entryPath);
 	while (pkgRoot !== nodePath.dirname(pkgRoot)) {
 		try {
@@ -58,6 +59,7 @@ export function defaultResolvePaths(platformKey, pluginRoot) {
 	const dest = nodePath.join(destDir, 'node_datachannel.node');
 
 	return { src, dest, destDir };
+	/* c8 ignore stop */
 }
 
 /**

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

@@ -6,13 +6,13 @@ import { remoteLog } from '../remote-log.js';
 // 用于诊断 dump：过大会撑爆 remoteLog 单帧，20 足以覆盖典型多文件传输会话。
 const FILE_CHANNEL_HISTORY_LIMIT = 20;
 
-// Failed session 保留 24 小时，支持 Capacitor 长时间后台恢复后 ICE restart。
+// Failed session 保留 12 小时，支持 Capacitor 后台恢复后 ICE restart。
 // 超时后 session 被回收释放 IPC listeners 和 Go 侧资源。
-const FAILED_SESSION_TTL_MS = 24 * 60 * 60 * 1000;
+const FAILED_SESSION_TTL_MS = 12 * 60 * 60 * 1000;
 
 // Session 总数上限（活跃 + failed）。溢出时淘汰最旧的 failed session。
-// 20 足以覆盖多 UI 实例（浏览器多标签 + 移动端）的典型场景。
-const MAX_SESSIONS = 20;
+// 10 足以覆盖多 UI 实例（浏览器多标签 + 移动端）的典型场景。
+const MAX_SESSIONS = 10;
 
 /**
  * 管理多个 WebRTC PeerConnection（以 connId 为粒度）。
@@ -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`);
@@ -134,6 +148,8 @@ export class WebRtcPeer {
 	async __handleOffer(msg) {
 		const connId = msg.fromConnId;
 		const isIceRestart = !!msg.payload?.iceRestart;
+		const credRemain = this.__credRemainSec(msg.turnCreds);
+		const credRemainStr = credRemain ?? 'none';
 
 		// ICE restart：在现有 PC 上重新协商，保持 DTLS session
 		if (isIceRestart) {
@@ -141,7 +157,7 @@ export class WebRtcPeer {
 			if (existing) {
 				// 仅已验证支持 ICE restart 的 impl 放行，其余立即 reject 让 UI 走 rebuild
 				if (this.__impl !== 'pion') {
-					this.__remoteLog(`rtc.ice-restart-unsupported conn=${connId} impl=${this.__impl}`);
+					this.__remoteLog(`rtc.ice-restart-unsupported conn=${connId} impl=${this.__impl} credRemain=${credRemainStr}`);
 					this.logger.info?.(`${this.__rtcTag} ICE restart rejected: impl=${this.__impl} not verified`);
 					this.__onSend({
 						type: 'rtc:restart-rejected',
@@ -155,7 +171,7 @@ export class WebRtcPeer {
 					clearTimeout(existing.__failedTimer);
 					existing.__failedTimer = null;
 				}
-				this.__remoteLog(`rtc.ice-restart conn=${connId}`);
+				this.__remoteLog(`rtc.ice-restart conn=${connId} credRemain=${credRemainStr}`);
 				this.logger.info?.(`${this.__rtcTag} ICE restart offer from ${connId}, renegotiating`);
 				try {
 					await existing.pc.setRemoteDescription({ type: 'offer', sdp: msg.payload.sdp });
@@ -173,11 +189,12 @@ 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) {
 					// ICE restart 协商失败 → reject，不 fall through
-					this.__remoteLog(`rtc.ice-restart-failed conn=${connId}`);
+					this.__remoteLog(`rtc.ice-restart-failed conn=${connId} credRemain=${credRemainStr}`);
 					this.logger.warn?.(`${this.__rtcTag} ICE restart failed for ${connId}: ${err?.message}`);
 					this.__onSend({
 						type: 'rtc:restart-rejected',
@@ -192,7 +209,7 @@ export class WebRtcPeer {
 				}
 			}
 			// 无 session → reject（plugin 可能已重启）
-			this.__remoteLog(`rtc.ice-restart-no-session conn=${connId}`);
+			this.__remoteLog(`rtc.ice-restart-no-session conn=${connId} credRemain=${credRemainStr}`);
 			this.logger.warn?.(`${this.__rtcTag} ICE restart from ${connId} but no session, rejecting`);
 			this.__onSend({
 				type: 'rtc:restart-rejected',
@@ -243,11 +260,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）
@@ -255,6 +285,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,
@@ -265,6 +303,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 = () => {
@@ -283,6 +344,7 @@ export class WebRtcPeer {
 			}
 
 			if (state === 'connected') {
+				const prevDumpState = cur.__lastDumpState;
 				// 重置 dump 去重水位（disconnected → connected → disconnected 仍能再 dump）
 				cur.__lastDumpState = null;
 				// werift: iceTransports[0].connection.nominated
@@ -296,6 +358,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 收敛诊断噪声
@@ -425,6 +503,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) {
@@ -556,10 +639,73 @@ 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);
 	}
 
+	// 解析 HMAC turnCreds 中的剩余秒数（username 形如 "<expireAt>:<userId>"）；
+	// 负值表示已过期；解析失败或 turnCreds 缺失返回 null。仅用于 ICE restart 日志诊断。
+	__credRemainSec(turnCreds) {
+		const username = turnCreds?.username;
+		if (typeof username !== 'string') return null;
+		const expireAt = Number(username.split(':')[0]);
+		if (!Number.isFinite(expireAt)) return null;
+		return expireAt - Math.floor(Date.now() / 1000);
+	}
+
 	/** 淘汰最旧的 failed session（Map 迭代序 ≈ 创建时间序），用于 queue length 限制 */
 	__evictOldestFailed() {
 		for (const [connId, session] of this.__sessions) {