@coclaw/openclaw-coclaw 0.26.5 → 0.27.0

package/README.md

@@ -172,14 +172,11 @@ openclaw gateway call coclaw.upgradeHealth --json
 
 ## WebRTC 实现
 
-插件在运行时按优先级选择 WebRTC 实现：
+WebRTC 唯一实现为 **pion**——通过 `@coclaw/pion-node` SDK 驱动 Go 侧 pion-ipc 进程，实现完整 WebRTC 能力。pion 加载失败时不再兜底（`impl=none`）：所有依赖 WebRTC DataChannel 的远程功能（chat、UI RPC、文件传输）不可用；gateway 进程、本地 RPC 面与自动升级不受影响，可通过发布修复版本自动升级恢复。
 
-1. **pion**（主力）— 通过 `@coclaw/pion-node` SDK 驱动 Go 侧 pion-ipc 进程，实现完整 WebRTC 能力。
-2. **werift**（回退）— 纯 JavaScript 实现，作为 pion 加载失败时的兜底。
+加载结果通过 `coclaw.env impl=...` 日志上报。
 
-选择结果通过 `bridge.started` / `coclaw.env impl=...` 日志上报。
-
-> `ndc-preloader.js`（node-datachannel 路径）的代码仍保留但已摘除 `node-datachannel` 依赖和 vendor 预编译包（2026-04-19）——运行时必然走 fallback 到 werift，待 pion 在全部线上平台稳定观察期结束后与 werift 一并移除。
+> 历史：werift（纯 JS 兜底）与 ndc（node-datachannel）路径已于 2026-07-16 移除。werift 的 DataChannel 不触发 `onbufferedamountlow` 属性回调，而插件的 RPC 背压与文件下载恢复都挂在该回调上——werift 路径实为"能连上但文件/大流量必楔死"的负价值兜底。背景见 `docs/webrtc-impl-strategy.md`。
 
 ## 运行与排障日志
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coclaw/openclaw-coclaw",
-  "version": "0.26.5",
+  "version": "0.27.0",
   "type": "module",
   "license": "Apache-2.0",
   "description": "OpenClaw plugin for remote chat over WebRTC. Run `openclaw coclaw enroll` after install.",
@@ -68,7 +68,6 @@
   },
   "dependencies": {
     "@coclaw/pion-node": "^0.4.0",
-    "werift": "^0.19.0",
     "ws": "^8.19.0"
   },
   "peerDependencies": {

package/src/auto-upgrade/state.js

@@ -7,6 +7,11 @@
  * 2. OPENCLAW_STATE_DIR 环境变量（worker 子进程，由 spawner 传入）
  * 3. ~/.openclaw（兜底默认值）
  *
+ * 注：第 3 档（homedir）实际够不着——gateway 进程内 runtime 必在（full mode 才启
+ * scheduler）、worker 进程 spawner 总会传 OPENCLAW_STATE_DIR，故不存在“worker 写错盘”。
+ * 曾被对抗式 review 当 bug 捞出，核实为不可达防御，记此免再捞。
+ * 同理“runtime 非空但 .state 缺失”的部分注入形态也不可达，勿为对齐 claw-paths.js 改成抛错。
+ *
  * 锁策略：state 文件的 read-modify-write 统一走 stateMutex；纯读不加锁。
  * 锁只能护住同进程内并发（gateway 与 worker 跨进程仍各写各的），但 worker /
  * scheduler 各自内部是串行流，进程内互斥已足够。
@@ -24,8 +29,13 @@ const STATE_FILENAME = 'upgrade-state.json';
 const LOG_FILENAME = 'upgrade-log.jsonl';
 const LOG_MAX_LINES = 200;
 const LOG_KEEP_LINES = 100;
-// lastUpgrade.error 截断上限：远端上报行不宜过长；jsonl 保留完整 error
-const ERROR_MAX_CHARS = 500;
+// lastUpgrade.error 截断上限：远端上报行不宜过长；jsonl 保留完整 error。
+// 取 1600 是为 ≥ worker.js formatCmdFailure 复合串的理论最大长度（≈1547：
+// prefix + message/stdout/stderr 三段各尾截 500 + 标签与 " | " 分隔符开销），
+// 保证 worker 格式化的失败串绝不被 state.js 二次全局截断而切掉中段真因；
+// 这里不解析 worker 的分段格式（保持两者解耦），只保留一道防御性硬上限——
+// state.js 的 error 还来自 'boom'/'timeout'/verify 等其它短串，需防意外超长串无界落盘。
+const ERROR_MAX_CHARS = 1600;
 
 const stateMutex = createMutex();
 const logMutex = createMutex();

package/src/auto-upgrade/updater.js

@@ -582,8 +582,12 @@ export class AutoUpgradeScheduler {
 				);
 			}
 
-			// 来源验明 npm 后才上报 available——否则永不升级的装置每小时刷一条
-			remoteLog(`upgrade.available from=${result.currentVersion} to=${result.latestVersion}`);
+			// 来源验明 npm 后才上报 available——否则永不升级的装置每小时刷一条；
+			// available 同为稳定态（直到升级落地或新版发布），与兄弟信号同模式按 (原因, toVersion) 去重防刷屏
+			this.__gateSignalOnce(
+				`available|${result.latestVersion}`,
+				`upgrade.available from=${result.currentVersion} to=${result.latestVersion}`,
+			);
 			this.__logger.info?.(`[auto-upgrade] Update available: ${result.currentVersion} → ${result.latestVersion}`);
 
 			// installPath 取自权威记录（新鲜）；缺失时回退自推包根，

package/src/file-manager/handler.js

@@ -318,7 +318,7 @@ export function createFileHandler({ resolveWorkspace, logger, deps = {} }) {
 
 	/**
 	 * 处理 file:<transferId> DataChannel
-	 * @param {object} dc - werift DataChannel
+	 * @param {object} dc - DataChannel
 	 * @param {string} [connId] - 所属 PeerConnection 的连接 ID
 	 */
 	function handleFileChannel(dc, connId) {

package/src/realtime-bridge.js

@@ -151,7 +151,6 @@ export class RealtimeBridge {
 		this.__resolveGatewayAuthToken = deps.resolveGatewayAuthToken ?? defaultResolveGatewayAuthToken;
 		this.__loadDeviceIdentity = deps.loadDeviceIdentity ?? loadOrCreateDeviceIdentity;
 		this.__preloadPion = deps.preloadPion ?? null;
-		this.__preloadNdc = deps.preloadNdc ?? null;
 		this.__WebSocket = deps.WebSocket; // undefined=使用 ws 包, null=禁用（测试用）, 其他=自定义实现
 		this.__gatewayReadyTimeoutMs = deps.gatewayReadyTimeoutMs ?? 1500;
 		this.__dcReqTtlMs = deps.dcReqTtlMs ?? DC_REQ_TTL_MS;
@@ -1403,7 +1402,7 @@ export class RealtimeBridge {
 						// 信令消息，与 drain 内的同名日志做区分主要看 msg 文本。
 						const sigType = payload?.type ?? 'unknown';
 						const sigConn = payload?.fromConnId ?? payload?.toConnId ?? 'unknown';
-						this.logger.warn?.(`[coclaw/rtc] signaling error (or werift not found) type=${sigType} conn=${sigConn}: ${err?.message}`);
+						this.logger.warn?.(`[coclaw/rtc] signaling error type=${sigType} conn=${sigConn}: ${err?.message}`);
 						remoteLog(`rtc.signaling-error type=${sigType} conn=${sigConn} msg=${err?.message}`);
 					}
 					return;
@@ -1443,7 +1442,7 @@ export class RealtimeBridge {
 				this.__webrtcPeerReady = null;
 				if (this.webrtcPeer) {
 					try { await this.webrtcPeer.closeAll(); }
-					/* c8 ignore next 3 -- 防御性兜底，werift close 异常时不可崩溃 gateway */
+					/* c8 ignore next 3 -- 防御性兜底，closeAll 异常时不可崩溃 gateway */
 					catch (e) { this.logger.warn?.(`[coclaw/rtc] closeAll failed: ${e?.message}`); }
 					this.webrtcPeer = null;
 				}
@@ -1497,7 +1496,11 @@ export class RealtimeBridge {
 			.then((v) => { this.__pluginVersion = v; })
 			.catch(() => { this.__pluginVersion = 'unknown'; });
 
-		// 1. 尝试 pion（最高优先级）
+		// 唯一实现 pion，失败不再回退（werift 兜底已剔除：其 DataChannel 无
+		// onbufferedamountlow 回调，插件的背压/文件下载恢复挂在该回调上，werift
+		// 路径实为"连上但核心功能楔死"的负价值兜底）。impl='none' 时所有走 DC 的
+		// 远程功能（chat / UI RPC / 文件）不可用；gateway 进程、本地 RPC 面与
+		// 自动升级链路不受影响，可发布修复版把机器捞回。
 		const preloadPionFn = this.__preloadPion
 			?? (await import('./webrtc/pion-preloader.js')).preloadPion;
 		const pionResult = await preloadPionFn({ logger: this.logger }).catch((err) => {
@@ -1509,17 +1512,10 @@ export class RealtimeBridge {
 			return pionResult;
 		}
 
-		// 2. 回退到 ndc/werift
-		const preloadNdcFn = this.__preloadNdc
-			?? (await import('./webrtc/ndc-preloader.js')).preloadNdc;
-		const [ndcResult] = await Promise.all([
-			preloadNdcFn().catch((err) => {
-				this.logger.warn?.(`[coclaw] ndc preload unexpected failure: ${err?.message}`);
-				return { PeerConnection: null, cleanup: null, impl: 'none' };
-			}),
-			versionPromise,
-		]);
-		return ndcResult;
+		// none 结果保持非空对象契约（start/stop 竞态守卫直接读 .impl / .cleanup）；
+		// 返回前须等版本预热完成，保证 __buildEnvLine 的 plugin= 字段就绪
+		await versionPromise;
+		return { PeerConnection: null, cleanup: null, impl: 'none' };
 	}
 	/* c8 ignore stop */
 
@@ -1571,7 +1567,7 @@ export class RealtimeBridge {
 		// preload 后还有一道 started 检查兜底（含 pion cleanup），这里先挡住一次无意义的 preload。
 		if (!this.started) return;
 		// 先完成 WebRTC 实现加载，再建立连接，避免 UI 发来 offer 时 RTC 包未就绪
-		// 优先级：pion → ndc → werift → none
+		// 唯一实现 pion，失败即 none（无兜底）
 		const preloadResult = await this.__preloadWebrtc();
 		// 竞态保护：若 preload 期间 stop() 已执行，不再赋值，直接返回。
 		if (!this.started) {
@@ -1583,10 +1579,9 @@ export class RealtimeBridge {
 		}
 		this.__ndcPreloadResult = preloadResult;
 		this.__ndcCleanup = preloadResult.cleanup;
-		const implLabel = preloadResult.impl === 'ndc' ? 'node-datachannel(ndc)' : preloadResult.impl;
-		this.__implLabel = implLabel; // 缓存供 ws.open 时发送
+		this.__implLabel = preloadResult.impl; // 缓存供 ws.open 时发送
 		// 启动信息只本地 log；远程发送统一由 ws.open 触发，避免重复
-		this.logger.info?.(`[coclaw] WebRTC impl: ${implLabel}`);
+		this.logger.info?.(`[coclaw] WebRTC impl: ${this.__implLabel}`);
 		this.logger.info?.(`[coclaw] ${this.__buildEnvLine()}`);
 		remoteLog('bridge.started');
 		// 启动 UI 转发 RPC 路由表周期扫描：1h 间隔扫描 24h 过期条目，避免长程 RPC 残留。
@@ -1699,8 +1694,7 @@ export class RealtimeBridge {
 			await this.webrtcPeer.closeAll().catch(() => {});
 			this.webrtcPeer = null;
 		}
-		// pion: 关闭 Go 进程（异步，快速）
-		// ndc: 不调用 cleanup()——同步 join native threads 耗时 10s+，进程退出时 OS 回收
+		// pion: 关闭 Go 进程（异步，快速）；none: cleanup 为 null，无事可做
 		const impl = this.__ndcPreloadResult?.impl;
 		if (impl === 'pion' && this.__ndcCleanup) {
 			await this.__ndcCleanup().catch(() => {});
@@ -1768,20 +1762,19 @@ export async function restartRealtimeBridge(opts) {
 
 /**
  * @param {object} [opts]
- * @param {boolean} [opts.forceCleanup] - 调用 ndc cleanup() 释放 native TSFN（仅测试用）。
- *   生产环境不调用：cleanup() 会 join native threads（无活跃 PC 时通常 sub-second，
- *   但 worst-case 阻塞 10s），且 gateway 通过 process.exit() 退出无需依赖事件循环排空。
+ * @param {boolean} [opts.forceCleanup] - ndc 时代释放 native TSFN 的历史参数（仅测试用）。
+ *   现存实现（pion/none）下恒为 no-op：pion 的 cleanup 已在 stop() 内处理（fast async），
+ *   none 无 cleanup。保留签名兼容既有测试调用方。
  */
 export async function stopRealtimeBridge({ forceCleanup = false } = {}) {
 	if (!singleton) {
 		return;
 	}
-	// pion 的 cleanup 已在 stop() 内处理（fast async），此处 forceCleanup 仅用于 ndc
 	const impl = singleton.__ndcPreloadResult?.impl;
 	const cleanupFn = (forceCleanup && impl !== 'pion') ? singleton.__ndcCleanup : null;
 	await singleton.stop();
 	singleton = null; // 置 null 后须通过 restartRealtimeBridge 重建
-	/* c8 ignore next 3 -- forceCleanup 仅 ndc 测试清理 TSFN，pion binary 存在时走 pion 路径不触发 */
+	/* c8 ignore next 3 -- 历史 ndc 分支：现存实现下 cleanupFn 恒 null，不可触发 */
 	if (typeof cleanupFn === 'function') {
 		try { cleanupFn(); } catch { /* cleanup 失败不影响 stop 结果 */ }
 	}

package/src/session-manager/manager.js

@@ -32,7 +32,6 @@ async function safeReaddir(dir) {
 	try { return await fsp.readdir(dir); }
 	catch (err) {
 		if (err.code === 'ENOENT' || err.code === 'ENOTDIR') return [];
-		/* c8 ignore next 2 -- 非 ENOENT/ENOTDIR 的 fs 错误按原样上抛 */
 		throw err;
 	}
 }
@@ -45,7 +44,6 @@ async function safeAccess(filePath) {
 	try { await fsp.access(filePath); return true; }
 	catch (err) {
 		if (err.code === 'ENOENT' || err.code === 'ENOTDIR') return false;
-		/* c8 ignore next 2 -- 非 ENOENT/ENOTDIR 的 fs 错误按原样上抛 */
 		throw err;
 	}
 }
@@ -150,12 +148,10 @@ export function createSessionManager(options = {}) {
 			const full = nodePath.join(dir, file);
 			let stat;
 			try { stat = await fsp.stat(full); }
-			/* c8 ignore start -- readdir→stat race window：文件被并发删除时跳过 */
 			catch (err) {
 				if (err.code === 'ENOENT') continue;
 				throw err;
 			}
-			/* c8 ignore stop */
 			const row = {
 				sessionId: parsed.sessionId,
 				sessionKey: sessionKeyById.get(parsed.sessionId) ?? null,
@@ -224,12 +220,10 @@ export function createSessionManager(options = {}) {
 			const full = nodePath.join(dir, name);
 			let stat;
 			try { stat = await fsp.stat(full); }
-			/* c8 ignore start -- readdir→stat race window */
 			catch (err) {
 				if (err.code === 'ENOENT') continue;
 				throw err;
 			}
-			/* c8 ignore stop */
 			candidates.push({
 				path: full,
 				archiveStamp,
@@ -240,7 +234,6 @@ export function createSessionManager(options = {}) {
 			if (a.archiveStamp !== b.archiveStamp) {
 				return b.archiveStamp.localeCompare(a.archiveStamp);
 			}
-			/* c8 ignore next -- 同 sessionId 同 archiveStamp 的归档实测 0 case */
 			return b.updatedAt - a.updatedAt;
 		});
 		if (candidates.length > 0) {

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

@@ -486,6 +486,7 @@ class FileBackedQueue {
 			/* c8 ignore next 2 -- rm with force rarely fails */
 			this.logger?.warn?.('fbq.handleFsError rm error', rmErr);
 		}
+		// 故意不 __dispatchSpillEnd：webrtc 只 destroy 不 clear + fsBroken 粘性不再 spill，spillActive 卡 true 不可达；即便发生也仅 monitor 观测标志失真，不丢消息
 		this.spilled = false;
 		this.writtenBytes = 0;
 		this.readOffset = 0;

package/src/webrtc/pion-preloader.js

@@ -9,7 +9,7 @@ const SEVERE_LOG_PATTERN = /request timeout|orphan response/;
  * 预加载 Pion WebRTC 实现：启动 pion-ipc Go 进程，返回绑定了 ipc 的 PeerConnection。
  *
  * **此函数永不 throw**——所有异常内部捕获，通过 remoteLog 报告。
- * 失败时返回 null（调用方降级到 ndc/werift）。
+ * 失败时返回 null（调用方按 impl='none' 处理，无兜底实现）。
  *
  * binary 解析由 @coclaw/pion-node 内部处理（env → npm 平台包 → PATH）。
  *

package/src/webrtc/webrtc-peer.js

@@ -729,13 +729,13 @@ export class WebRtcPeer {
 		// 连接状态变更（校验 pc 归属，防止旧 PC 异步回调删除新 session）
 		pc.onconnectionstatechange = () => {
 			const state = pc.connectionState;
-			this.__remoteLog(`rtc.state conn=${connId} ${state}`);
-			this.logger.info?.(`${this.__rtcTag} [${connId}] connectionState: ${state}`);
-
 			// 校验 pc 归属：旧 PC 的异步回调可能在新 session 已建立后触发
 			const cur = this.__sessions.get(connId);
 			if (!cur || cur.pc !== pc) return;
 
+			this.__remoteLog(`rtc.state conn=${connId} ${state}`);
+			this.logger.info?.(`${this.__rtcTag} [${connId}] connectionState: ${state}`);
+
 			// 离开 failed 状态时清理 TTL timer（ICE restart 恢复、自然关闭等）
 			if (state !== 'failed' && cur.__failedTimer) {
 				clearTimeout(cur.__failedTimer);
@@ -829,7 +829,7 @@ export class WebRtcPeer {
 				// 后变 fire-and-forget（WebRTC 实现的 ondatachannel 是 sync 回调，不能 await）
 				session.rpcChannel = channel;
 				this.__setupDataChannel(connId, channel).catch((err) => {
-					/* c8 ignore next 2 -- setup 内部已经 try/catch 所有 await；此处仅防御性兜底 */
+					/* c8 ignore next 2 -- async 装配段（FBQ 构造+init）无内部 try/catch，此 catch 是其抛错的真实吞没点（非"防御兜底"）；生产不可达（仅 server 违反 connId 契约触发）暂未修，详见 TODO「__setupDataChannel 装配抛错 → rpcQueue 半残静默丢消息」 */
 					this.logger.warn?.(`${this.__rtcTag} [${connId}] __setupDataChannel error: ${err?.message}`);
 				});
 			} else if (channel.label.startsWith('file:')) {
@@ -879,6 +879,8 @@ export class WebRtcPeer {
 			// 注入 __onRequest 或 enqueue 到新 rpcQueue。session 已删除时（rpcChannel===null 或
 			// sess undefined）也按 stale 处理，避免向已清空的 session 注入消息。
 			const sess = this.__sessions.get(connId);
+			// 身份守卫故意放在派发处（而非 dc.onmessage 入口）：reassembler 每 dc 独立、陈旧 chunk 派发前
+			// 无害，放此处可挡住所有通向派发的路径（含未来 reassembler 定时刷新等非 onmessage 旁路）。
 			if (!sess || sess.rpcChannel !== dc) {
 				return;
 			}
@@ -924,6 +926,9 @@ export class WebRtcPeer {
 		}, { logger: this.logger });
 
 		dc.onopen = () => {
+			// 陈旧通道早返回：旧 dc 的迟到 onopen 不应对新 session 误报 transport
+			const sess = this.__sessions.get(connId);
+			if (!sess || sess.rpcChannel !== dc) return;
 			this.__remoteLog(`dc.open conn=${connId} label=${dc.label}`);
 			this.logger.info?.(`${this.__rtcTag} [${connId}] DataChannel "${dc.label}" opened`);
 			// rpc DC 建立后，把本端 transport 信息单播给 UI。
@@ -963,6 +968,9 @@ export class WebRtcPeer {
 			}
 		};
 		dc.onerror = (err) => {
+			// 陈旧通道早返回：旧 dc 的迟到 onerror 不打进新 session 上下文
+			const sess = this.__sessions.get(connId);
+			if (!sess || sess.rpcChannel !== dc) return;
 			this.__remoteLog(`dc.error conn=${connId} label=${dc.label}`);
 			/* c8 ignore next -- ?./?? fallback */
 			this.logger.warn?.(`${this.__rtcTag} [${connId}] DataChannel "${dc.label}" error: ${String(err?.message ?? err)}`);

package/src/webrtc/ndc-preloader.js

@@ -1,247 +0,0 @@
-import { createRequire } from 'module';
-import nodePath from 'path';
-import fsSync from 'fs';
-import fsPromises from 'fs/promises';
-import { remoteLog as defaultRemoteLog } from '../remote-log.js';
-
-const SUPPORTED_PLATFORMS = new Set([
-	'linux-x64',
-	'linux-arm64',
-	'darwin-x64',
-	'darwin-arm64',
-	'win32-x64',
-]);
-
-const DEFAULT_IMPORT_TIMEOUT_MS = 10_000;
-
-/**
- * 给 promise 加超时保护。超时后 reject，但原 promise 仍在后台执行——
- * JS 无法取消 pending 的 import()，超时只是让调用方不再等待。
- * @param {Promise} promise
- * @param {number} ms
- * @param {string} label - 用于错误信息
- */
-function withTimeout(promise, ms, label) {
-	// 超时后原 promise 仍在后台执行（JS 无法取消 pending 的 import()）。
-	// 必须 .catch 兜住原 promise 的潜在 rejection，否则超时场景下
-	// 原 promise 最终 reject 会成为 unhandled rejection，导致进程终止。
-	promise.catch(() => {});
-	let timer;
-	const timeout = new Promise((_, reject) => {
-		timer = setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), ms);
-		timer.unref?.();
-	});
-	return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
-}
-
-/**
- * 解析 vendor 源和部署目标路径。
- * @param {string} platformKey - 如 'linux-x64'
- * @param {string} pluginRoot - 插件根目录
- * @returns {{ src: string, dest: string, destDir: string }}
- */
-export function defaultResolvePaths(platformKey, pluginRoot) {
-	const src = nodePath.join(pluginRoot, 'vendor', 'ndc-prebuilds', platformKey, 'node_datachannel.node');
-
-	// 定位 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 {
-			const pkg = JSON.parse(fsSync.readFileSync(nodePath.join(pkgRoot, 'package.json'), 'utf8'));
-			if (pkg.name === 'node-datachannel') break;
-		} catch { /* 继续向上 */ }
-		pkgRoot = nodePath.dirname(pkgRoot);
-	}
-	const destDir = nodePath.join(pkgRoot, 'build', 'Release');
-	const dest = nodePath.join(destDir, 'node_datachannel.node');
-
-	return { src, dest, destDir };
-	/* c8 ignore stop */
-}
-
-/**
- * ndc polyfill 的 RTCPeerConnection 将 iceServers 的 username:credential 直接拼入 URL，
- * 但 TURN REST API 的 username 格式为 `timestamp:identity`（含冒号），
- * 导致 libdatachannel 的 URL parser 截断 username。
- * 此 wrapper 在传入 polyfill 前对 username/credential 做 percent-encoding 规避该问题。
- */
-function wrapNdcCredentials(NativeRTC) {
-	return class extends NativeRTC {
-		constructor(config = {}) {
-			if (config?.iceServers) {
-				config = {
-					...config,
-					iceServers: config.iceServers.map(s => {
-						/* c8 ignore next -- TURN 无凭据时的短路，集成环境下不经过此路径 */
-						if (!s.username && !s.credential) return s;
-						return {
-							...s,
-							username: s.username ? encodeURIComponent(s.username) : s.username,
-							credential: s.credential ? encodeURIComponent(s.credential) : s.credential,
-						};
-					}),
-				};
-			}
-			super(config);
-		}
-	};
-}
-
-/**
- * 预加载 WebRTC 实现：优先 node-datachannel，失败回退 werift，全部失败返回 null。
- *
- * **此函数永不 throw**——所有异常内部捕获，通过 remoteLog 报告。
- * 返回值始终为 { PeerConnection, cleanup, impl } 结构。
- *
- * @param {object} [deps] - 可注入依赖（测试用）
- * @param {object} [deps.fs] - { access, copyFile, mkdir }
- * @param {Function} [deps.dynamicImport] - (specifier) => import(specifier)
- * @param {Function} [deps.remoteLog] - (text) => void
- * @param {string} [deps.platform] - 覆盖 process.platform
- * @param {string} [deps.arch] - 覆盖 process.arch
- * @param {string} [deps.pluginRoot] - 覆盖插件根目录
- * @param {Function} [deps.resolvePaths] - (platformKey, pluginRoot) => { src, dest, destDir }
- * @param {number} [deps.importTimeout] - 动态 import 超时（ms），默认 10s
- * @returns {Promise<{ PeerConnection: Function|null, cleanup: Function|null, impl: string }>}
- */
-export async function preloadNdc(deps = {}) {
-	const fs = deps.fs ?? fsPromises;
-	const dynamicImport = deps.dynamicImport ?? ((spec) => import(spec));
-	const log = deps.remoteLog ?? defaultRemoteLog;
-	const platform = deps.platform ?? process.platform;
-	const arch = deps.arch ?? process.arch;
-	const pluginRoot = deps.pluginRoot ?? nodePath.resolve(import.meta.dirname, '../..');
-	const resolvePaths = deps.resolvePaths ?? defaultResolvePaths;
-	const importTimeout = deps.importTimeout ?? DEFAULT_IMPORT_TIMEOUT_MS;
-
-	const platformKey = `${platform}-${arch}`;
-	log(`ndc.preload platform=${platformKey}`);
-
-	try {
-		// 平台检查
-		if (!SUPPORTED_PLATFORMS.has(platformKey)) {
-			log(`ndc.skip reason=unsupported-platform platform=${platformKey}`);
-			return weriftFallback(dynamicImport, log, importTimeout);
-		}
-		const { src, dest, destDir } = resolvePaths(platformKey, pluginRoot);
-
-		// 检查目标 binary 是否已存在（正常 pnpm install 或已执行过 bootstrap）
-		let needCopy = false;
-		try {
-			await fs.access(dest);
-			log('ndc.binary-exists');
-		} catch {
-			needCopy = true;
-		}
-
-		if (needCopy) {
-			// 检查 vendor 源 binary
-			try {
-				await fs.access(src);
-			} catch {
-				log('ndc.fallback reason=binary-missing');
-				return weriftFallback(dynamicImport, log, importTimeout);
-			}
-
-			// 部署 binary
-			try {
-				await fs.mkdir(destDir, { recursive: true });
-				await fs.copyFile(src, dest);
-				log('ndc.binary-deployed');
-			} catch (err) {
-				log(`ndc.fallback reason=copy-failed error=${err.message}`);
-				return weriftFallback(dynamicImport, log, importTimeout);
-			}
-		}
-
-		// 加载模块（带超时保护，防止 native binding dlopen 卡住）
-		let polyfill, ndc;
-		try {
-			polyfill = await withTimeout(
-				dynamicImport('node-datachannel/polyfill'),
-				importTimeout,
-				'import(node-datachannel/polyfill)',
-			);
-			ndc = await withTimeout(
-				dynamicImport('node-datachannel'),
-				importTimeout,
-				'import(node-datachannel)',
-			);
-		} catch (err) {
-			log(`ndc.fallback reason=import-failed error=${err.message}`);
-			return weriftFallback(dynamicImport, log, importTimeout);
-		}
-
-		const { RTCPeerConnection } = polyfill;
-		const cleanup = ndc.cleanup ?? ndc.default?.cleanup ?? null;
-
-		// 验证 RTCPeerConnection 可用（不创建实例，避免 native thread 阻止进程退出）
-		if (typeof RTCPeerConnection !== 'function') {
-			log('ndc.fallback reason=smoke-failed error=RTCPeerConnection is not a function');
-			return weriftFallback(dynamicImport, log, importTimeout);
-		}
-
-		// 注册 libdatachannel 内部日志回调（Warning 级别），
-		// 用于捕获 ICE/DTLS/SCTP 层断连原因。
-		// initLogger 是进程全局单例，调用一次即可（cleanup 不会被调用，logger 全程有效）。
-		// callback 通过 TSFN 投递到 JS 主线程，Warning 级别正常运行时零输出。
-		/* c8 ignore next -- ??/?. fallback */
-		const initLogger = ndc.initLogger ?? ndc.default?.initLogger;
-		if (typeof initLogger === 'function') {
-			try {
-				initLogger('Warning', (level, message) => {
-					try {
-						const msg = typeof message === 'string' ? message.replace(/\n/g, '\\n') : message;
-						log(`ndc.native level=${level} ${msg}`);
-					} catch { /* 不让任何异常传播到 native 层 */ }
-				});
-				log('ndc.logger-registered level=Warning');
-			} catch (err) {
-				// initLogger 失败不影响 ndc 正常使用
-				log(`ndc.logger-failed error=${err.message}`);
-			}
-		}
-
-		// 重要：调用方在不再需要 node-datachannel 时（如 bridge stop），必须调用 cleanup()。
-		// node-datachannel 内部使用 ThreadSafeCallback 维持 native threads，不调用 cleanup()
-		// 会阻止 Node 进程正常退出（上游 issue #366）。
-		// 当前 RealtimeBridge.stop() 不调用 cleanup()（阻塞 10s+），native threads 保持活跃供复用。
-		// 进程退出时 OS 会回收所有资源。
-		log(`ndc.loaded platform=${platformKey}`);
-		return { PeerConnection: wrapNdcCredentials(RTCPeerConnection), cleanup, impl: 'ndc' };
-	} catch (err) {
-		// node-datachannel 依赖已摘除：require.resolve 抛 MODULE_NOT_FOUND 是过渡期
-		// 预期路径，记为 skip 而非误导性的 unexpected。其余才是真正未预期异常。
-		if (err?.code === 'MODULE_NOT_FOUND') {
-			log('ndc.skip reason=ndc-not-installed');
-		} else {
-			log(`ndc.fallback reason=unexpected error=${err.message}`);
-		}
-		return weriftFallback(dynamicImport, log, importTimeout);
-	}
-}
-
-/**
- * 回退到 werift。加载也带超时保护。
- * werift 也失败时返回 PeerConnection: null（WebRTC 不可用但不影响 gateway）。
- * @param {Function} dynamicImport
- * @param {Function} log
- * @param {number} importTimeout
- */
-async function weriftFallback(dynamicImport, log, importTimeout) {
-	try {
-		const { RTCPeerConnection } = await withTimeout(
-			dynamicImport('werift'),
-			importTimeout,
-			'import(werift)',
-		);
-		log('webrtc.fallback-to-werift');
-		return { PeerConnection: RTCPeerConnection, cleanup: null, impl: 'werift' };
-	} catch (err) {
-		log(`webrtc.all-unavailable error=${err.message}`);
-		return { PeerConnection: null, cleanup: null, impl: 'none' };
-	}
-}