@coclaw/openclaw-coclaw 0.12.2 → 0.13.0

package/README.md

@@ -1,10 +1,17 @@
 # @coclaw/openclaw-coclaw
 
-CoClaw 的 OpenClaw 插件（npm: `@coclaw/openclaw-coclaw`，plugin id: `openclaw-coclaw`），包含：
+CoClaw 的 OpenClaw 插件（npm: `@coclaw/openclaw-coclaw`，plugin id: `openclaw-coclaw`），运行在 OpenClaw gateway 进程中，是 CoClaw 与 OpenClaw 之间的核心连接层。
 
-- **transport bridge** — CoClaw server 与 OpenClaw gateway 之间的实时消息桥接
-- **session-manager** — 会话列表/读取能力（`nativeui.sessions.listAll` / `nativeui.sessions.get`）
+主要模块：
+
+- **realtime bridge** — CoClaw server 与 OpenClaw gateway 之间的 WebSocket 实时消息桥接，支持 RPC 转发和事件广播
+- **WebRTC peer** — 与 CoClaw UI 建立 WebRTC DataChannel 直连，提供 RPC 和文件传输两类通道
+- **session manager** — 会话列表/读取能力（`nativeui.sessions.listAll` / `nativeui.sessions.get`）
+- **chat history manager** — 跟踪和管理 chat reset 产生的孤儿 session（`coclaw.chatHistory.list`）
+- **topic manager** — 独立话题的创建、列表、标题生成与删除（`coclaw.topics.*`）
+- **file manager** — 工作区文件管理，支持通过 WebRTC DataChannel 流式传输和 gateway RPC 回退（`coclaw.files.*`）
 - **auto-upgrade** — 从 npm 安装的插件自动检查并升级到最新版本
+- **device identity** — Ed25519 密钥对管理，用于 gateway WebSocket 连接的设备认证
 
 ## 安装与模式切换
 
@@ -60,6 +67,41 @@ WAIT=1 pnpm run release:check -- 0.1.7     # 轮询直到版本生效
 pnpm run release:versions                  # 显示所有已发布版本
 ```
 
+## Gateway RPC 方法
+
+插件注册的所有 gateway method（通过 `openclaw gateway call <method>` 或 WebRTC DC 调用）：
+
+| 方法 | 说明 |
+|------|------|
+| `coclaw.bind` | 绑定 Claw 到 CoClaw server |
+| `coclaw.unbind` | 解绑并停止 bridge |
+| `coclaw.enroll` | 生成认领码，等待用户完成绑定 |
+| `coclaw.info` / `coclaw.info.get` | 获取插件版本、claw 版本、capabilities、名称、主机名 |
+| `coclaw.info.patch` | 修改 claw 显示名称，广播 `coclaw.info.updated` 事件 |
+| `coclaw.topics.create` | 创建话题 |
+| `coclaw.topics.list` | 列出指定 agent 的话题 |
+| `coclaw.topics.get` | 获取单个话题 |
+| `coclaw.topics.getHistory` | 获取话题对话记录 |
+| `coclaw.topics.update` | 更新话题标题 |
+| `coclaw.topics.generateTitle` | 通过 agent RPC 自动生成话题标题 |
+| `coclaw.topics.delete` | 删除话题及其 `.jsonl` 文件 |
+| `coclaw.chatHistory.list` | 列出 chat 的历史（孤儿）session |
+| `coclaw.sessions.getById` | 按 sessionId 获取消息记录 |
+| `coclaw.upgradeHealth` | 返回当前插件版本（升级健康检查） |
+| `coclaw.files.list` | 列出工作区文件（RPC 回退） |
+| `coclaw.files.delete` | 删除工作区文件/目录 |
+| `coclaw.files.mkdir` | 创建工作区目录 |
+| `coclaw.files.create` | 创建空文件 |
+| `nativeui.sessions.listAll` | 列出所有 session（分页 + 标题推导） |
+| `nativeui.sessions.get` | 获取 session 原始 JSONL 行（分页） |
+
+## Gateway Services
+
+| Service ID | 说明 |
+|------------|------|
+| `coclaw-realtime-bridge` | CoClaw server WebSocket 桥接 + WebRTC peer 管理 |
+| `coclaw-auto-upgrade` | npm 安装模式下的自动升级调度器 |
+
 ## 绑定 / 解绑
 
 绑定码从 CoClaw Web 端生成，有效期有限。
@@ -183,6 +225,19 @@ openclaw logs --limit 300 --plain | rg -n "gateway connect failed|protocol misma
 openclaw logs --limit 300 --plain | rg -n "ui->server req|bot->server res|bot->server event|gateway req" -i
 ```
 
+## 设置
+
+插件设置存储在 `~/.openclaw/coclaw/settings.json`，独立于绑定信息，解绑后重新绑定不会丢失。
+
+当前支持的设置项：
+- `name` — Claw 显示名称（可选，最长 63 字符），通过 `coclaw.info.patch` RPC 修改
+
+`settings.js` 是读写设置的唯一入口。
+
+## 设备身份
+
+插件在首次运行时自动生成 Ed25519 密钥对，存储在 `~/.openclaw/coclaw/device-identity.json`（mode 0o600）。`deviceId` 为公钥的 SHA-256 摘要，用于 gateway WebSocket 连接的设备认证（v3 auth payload）。
+
 ## 测试门禁
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coclaw/openclaw-coclaw",
-  "version": "0.12.2",
+  "version": "0.13.0",
   "type": "module",
   "license": "Apache-2.0",
   "description": "OpenClaw CoClaw channel plugin for remote chat",
@@ -60,7 +60,9 @@
   },
   "dependencies": {
     "node-datachannel": "0.32.2",
-    "werift": "^0.19.0"
+    "@coclaw/pion-node": "^0.1.1",
+    "werift": "^0.19.0",
+    "ws": "^8.19.0"
   },
   "devDependencies": {
     "c8": "^10.1.3",

package/src/auto-upgrade/updater-check.js

@@ -33,11 +33,12 @@ export async function getPackageInfo(pluginDir) {
  * @returns {Promise<string>}
  */
 export async function getLatestVersion(pkgName, opts) {
+	/* c8 ignore next -- ?./?? fallback */
 	const doExecFile = opts?.execFileFn ?? nodeExecFile;
 	return new Promise((resolve, reject) => {
 		doExecFile('npm', ['view', pkgName, 'version'], {
 			timeout: 30_000,
-			shell: true,
+			shell: process.platform === 'win32',
 		}, (err, stdout) => {
 			if (err) {
 				reject(new Error(`npm view failed: ${err.message}`));
@@ -65,6 +66,7 @@ export function isNewerVersion(a, b) {
 	const pa = parse(a);
 	const pb = parse(b);
 	for (let i = 0; i < 3; i++) {
+		/* c8 ignore next 2 -- ?? fallback：正常 semver 不会有缺失段 */
 		if ((pa[i] ?? 0) > (pb[i] ?? 0)) return true;
 		if ((pa[i] ?? 0) < (pb[i] ?? 0)) return false;
 	}

package/src/auto-upgrade/updater-spawn.js

@@ -31,6 +31,7 @@ export function getWorkerPath() {
  * @returns {{ child: object }}
  */
 export function spawnUpgradeWorker({ pluginDir, fromVersion, toVersion, pluginId, pkgName, opts, logger }) {
+	/* c8 ignore next -- ?./?? fallback */
 	const doSpawn = opts?.spawnFn ?? nodeSpawn;
 	const workerPath = getWorkerPath();
 
@@ -52,6 +53,7 @@ export function spawnUpgradeWorker({ pluginDir, fromVersion, toVersion, pluginId
 		detached: true,
 		stdio: 'ignore',
 		env,
+		windowsHide: true,
 	});
 
 	// spawn 失败时 Node.js 会异步 emit 'error'；若无监听器则变为未捕获异常导致 gateway 崩溃

package/src/auto-upgrade/updater.js

@@ -166,6 +166,7 @@ export class AutoUpgradeScheduler {
 		}
 
 		// 默认 5~10 分钟随机延迟，避免多实例同时发起检查
+		/* c8 ignore next 2 -- ?? fallback：测试始终注入 initialDelayMs */
 		const initialDelay = this.__opts.initialDelayMs
 			?? (INITIAL_DELAY_MS + Math.floor(Math.random() * INITIAL_DELAY_MS));
 		this.__logger.info?.(`[auto-upgrade] Scheduler started. First check in ${Math.round(initialDelay / 1000)}s`);
@@ -173,6 +174,7 @@ export class AutoUpgradeScheduler {
 		this.__initialTimer = setTimeout(() => {
 			this.__initialTimer = null;
 			this.__check().catch(() => {});
+			/* c8 ignore next -- ?? fallback */
 			const interval = this.__opts.checkIntervalMs ?? CHECK_INTERVAL_MS;
 			this.__intervalTimer = setInterval(() => this.__check().catch(() => {}), interval);
 		}, initialDelay);
@@ -274,6 +276,7 @@ export class AutoUpgradeScheduler {
 			});
 
 			// 记录 worker PID，下次 check 时据此判断 worker 是否仍在运行
+			/* c8 ignore next -- ?? fallback */
 			const writeLock = this.__opts.writeUpgradeLockFn ?? writeUpgradeLock;
 			await writeLock(child.pid);
 		}

package/src/auto-upgrade/worker-verify.js

@@ -24,9 +24,10 @@ const CMD_TIMEOUT_MS = 30_000;
  * @returns {Promise<string>}
  */
 function runCmd(cmd, args, opts) {
+	/* c8 ignore next -- ?./?? fallback */
 	const doExecFile = opts?.execFileFn ?? nodeExecFile;
 	return new Promise((resolve, reject) => {
-		doExecFile(cmd, args, { timeout: CMD_TIMEOUT_MS, shell: true }, (err, stdout) => {
+		doExecFile(cmd, args, { timeout: CMD_TIMEOUT_MS, shell: process.platform === 'win32' }, (err, stdout) => {
 			if (err) reject(err);
 			else resolve(String(stdout).trim());
 		});
@@ -50,6 +51,7 @@ export async function waitForGateway(opts) {
 		// restart 命令失败不阻断流程，仍尝试等待
 	}
 
+	/* c8 ignore next 2 -- ?./?? fallback */
 	const timeout = opts?.timeoutMs ?? GATEWAY_READY_TIMEOUT_MS;
 	const interval = opts?.pollIntervalMs ?? POLL_INTERVAL_MS;
 	const start = Date.now();
@@ -124,6 +126,7 @@ export async function verifyUpgrade(pluginId, opts) {
 		return { ok: true, version };
 	}
 	catch (err) {
+		/* c8 ignore next -- ?./?? fallback */
 		return { ok: false, error: String(err?.message ?? err) };
 	}
 }

package/src/auto-upgrade/worker.js

@@ -9,7 +9,7 @@
  * 注意：
  * - 本模块作为独立 node 进程运行，与 gateway 进程隔离
  * - state dir 通过 OPENCLAW_STATE_DIR 环境变量由 spawner 传入
- * - shell: true 为 Windows 兼容性所需（openclaw 全局安装生成 .cmd 包装器）
+ * - shell 仅在 Windows 启用（openclaw 全局安装生成 .cmd 包装器，需 shell 解析）
  */
 
 import { execFile as nodeExecFile } from 'node:child_process';
@@ -30,11 +30,12 @@ const SEMVER_RE = /^\d+\.\d+\.\d+(-[\w.-]+)?$/;
 // 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,
-			shell: true,
+			shell: process.platform === 'win32',
 		}, (err) => {
 			if (err) reject(new Error(`plugins update failed: ${err.message}`));
 			else resolve();
@@ -61,9 +62,10 @@ async function fallbackInstallOldVersion(pkgName, version, pluginId, opts) {
 	if (!SEMVER_RE.test(version)) {
 		throw new Error(`invalid version format: ${version}`);
 	}
+	/* c8 ignore next -- ?./?? fallback */
 	const doExecFile = opts?.execFileFn ?? nodeExecFile;
 	const run = (args, timeout = 120_000) => new Promise((resolve, reject) => {
-		doExecFile('openclaw', args, { timeout, shell: true }, (err) => {
+		doExecFile('openclaw', args, { timeout, shell: process.platform === 'win32' }, (err) => {
 			if (err) reject(err);
 			else resolve();
 		});
@@ -193,11 +195,14 @@ async function handleRollback({ pluginDir, fromVersion, toVersion, pluginId, pkg
 	// update 命令失败可能是瞬态故障（网络、磁盘等），不应永久跳过该版本
 	if (skipVersion) {
 		try { await addSkippedVersion(toVersion); }
+		/* c8 ignore next -- 状态写入 catch：测试中 stub 不会失败 */
 		catch (e) { log(`[upgrade-worker] Failed to record skipped version (non-fatal): ${e.message}`); }
 	}
 	try { await updateLastUpgrade({ from: fromVersion, to: toVersion, result: 'rollback' }); }
+	/* c8 ignore next -- 状态写入 catch */
 	catch (e) { log(`[upgrade-worker] Failed to update lastUpgrade (non-fatal): ${e.message}`); }
 	try { await appendLog({ from: fromVersion, to: toVersion, result: 'rollback', error }); }
+	/* c8 ignore next -- 状态写入 catch */
 	catch (e) { log(`[upgrade-worker] Failed to append log (non-fatal): ${e.message}`); }
 	if (skipVersion) {
 		log(`[upgrade-worker] Rollback complete. Version ${toVersion} added to skipped list`);

package/src/chat-history-manager/manager.js

@@ -36,6 +36,7 @@ export class ChatHistoryManager {
 	constructor(opts = {}) {
 		this.__rootDir = opts.rootDir ?? nodePath.join(os.homedir(), '.openclaw', 'agents');
 		this.__logger = opts.logger ?? console;
+		/* c8 ignore next 2 -- ?? fallback：测试始终注入 */
 		this.__readFile = opts.readFile ?? fs.readFile;
 		this.__writeJsonFile = opts.writeJsonFile ?? atomicWriteJsonFile;
 		// 内存缓存：agentId -> { version, [sessionKey]: [...] }

package/src/cli-registrar.js

@@ -54,6 +54,7 @@ async function callWithRetry(method, deps, rpcOpts) {
 	let result = await callRpc();
 
 	if (isGatewayUnavailable(result)) {
+		/* c8 ignore next -- ?? fallback：测试始终注入 deps.restartGateway */
 		const restartFn = deps.restartGateway ?? restartGatewayProcess;
 		try {
 			await restartFn(deps.spawn);
@@ -87,7 +88,7 @@ function handleRpcError(result, fallbackMsg) {
  * @param {object} ctx.logger - 日志实例
  * @param {object} [deps] - 可注入依赖（测试用）
  */
-export function registerCoclawCli({ program, logger }, deps = {}) {
+export function registerCoclawCli({ program, logger: _logger }, deps = {}) {
 	const coclaw = program
 		.command('coclaw')
 		.description('CoClaw bind/unbind commands');
@@ -144,6 +145,7 @@ export function registerCoclawCli({ program, logger }, deps = {}) {
 					console.log(claimCodeCreated({
 						code: data.code,
 						appUrl: data.appUrl,
+						/* c8 ignore next -- ?? fallback */
 						expiresMinutes: data.expiresMinutes ?? 30,
 					}));
 				} else {

package/src/common/gateway-notify.js

@@ -49,6 +49,7 @@ export function escapeJsonForCmd(json) {
  * @returns {Promise<{ ok: boolean, status?: string, error?: string }>}
  */
 export function callGatewayMethod(method, spawnFn, opts) {
+	/* c8 ignore next -- ?? fallback */
 	const doSpawn = spawnFn ?? nodeSpawn;
 
 	return new Promise((resolve) => {

package/src/device-identity.js

@@ -108,6 +108,7 @@ export function loadOrCreateDeviceIdentity(filePath) {
 				if (derivedId && derivedId !== parsed.deviceId) {
 					const updated = { ...parsed, deviceId: derivedId };
 					fs.writeFileSync(fp, `${JSON.stringify(updated, null, 2)}\n`, { mode: 0o600 });
+					/* c8 ignore next -- best-effort chmod */
 					try { fs.chmodSync(fp, 0o600); } catch { /* best-effort */ }
 					return { deviceId: derivedId, publicKeyPem: parsed.publicKeyPem, privateKeyPem: parsed.privateKeyPem };
 				}
@@ -131,6 +132,7 @@ export function loadOrCreateDeviceIdentity(filePath) {
 		createdAtMs: Date.now(),
 	};
 	fs.writeFileSync(fp, `${JSON.stringify(stored, null, 2)}\n`, { mode: 0o600 });
+	/* c8 ignore next -- best-effort chmod */
 	try { fs.chmodSync(fp, 0o600); } catch { /* best-effort */ }
 	return identity;
 }

package/src/file-manager/handler.js

@@ -11,7 +11,7 @@ const HIGH_WATER_MARK = 262_144; // 256KB
 const LOW_WATER_MARK = 65_536; // 64KB
 const MAX_UPLOAD_SIZE = 1_073_741_824; // 1GB
 const FILE_DC_TIMEOUT_MS = 30_000; // DC 打开后 30s 内需收到请求
-const TMP_CLEANUP_DELAY_MS = 60_000; // 启动后 60s 延迟清理
+const TMP_CLEANUP_DELAY_MS = 2_000; // 启动后 2s 延迟清理
 const TMP_FILE_PATTERN = /\.tmp\.[0-9a-f-]{36}$/;
 
 // --- 路径安全校验 ---
@@ -70,6 +70,7 @@ export async function validatePath(workspaceDir, userPath, deps = {}) {
 	}
 
 	// 仅允许普通文件和目录
+	/* c8 ignore next 4 -- 特殊文件类型（socket/FIFO/device）在测试环境无法可靠构造 */
 	if (!stat.isFile() && !stat.isDirectory() && !stat.isSymbolicLink()) {
 		const err = new Error(`Special file type denied: ${userPath}`);
 		err.code = 'PATH_DENIED';
@@ -329,6 +330,13 @@ export function createFileHandler({ resolveWorkspace, logger, deps = {} }) {
 		}, FILE_DC_TIMEOUT_MS);
 		requestTimer.unref?.();
 
+		// 早期 error 上报：保护 GET/PUT/POST 接管前的窗口期
+		// 内部 handler 接管后会用更具上下文的 onerror 替换此处
+		dc.onerror = (err) => {
+			/* c8 ignore next -- ?? fallback for missing label/err.message */
+			remoteLog(`file.dc.error conn=${connId} label=${dc.label ?? 'unknown'} stage=pre-request err=${err?.message ?? err}`);
+		};
+
 		let requestReceived = false;
 
 		dc.onmessage = (event) => {
@@ -348,9 +356,13 @@ export function createFileHandler({ resolveWorkspace, logger, deps = {} }) {
 				return;
 			}
 
+			// 本地 logger.info：让 gateway 本地 log 直接看到 file 操作的开始
+			// （远端诊断走 remoteLog，但本地能看到对排查 WSL2 假活/重连场景至关重要）
+			log.info?.(`[coclaw/file] [${connId}] ${req.method} label=${dc.label ?? '?'} path=${req.path ?? '?'}${req.size != null ? ` size=${req.size}` : ''}`);
+
 			if (req.method === 'GET') {
 				/* c8 ignore next 3 -- handleGet 内部已完整处理异常，此 catch 纯防御 */
-				handleGet(dc, req).catch((err) => {
+				handleGet(dc, req, connId).catch((err) => {
 					log.warn?.(`[coclaw/file] GET error: ${err.message}`);
 				});
 			} else if (req.method === 'PUT') {
@@ -369,7 +381,12 @@ export function createFileHandler({ resolveWorkspace, logger, deps = {} }) {
 		};
 	}
 
-	async function handleGet(dc, req) {
+	async function handleGet(dc, req, connId) {
+		/* c8 ignore next -- ?./?? fallback for non-file: label */
+		const transferId = dc.label?.split(':')?.[1] ?? randomUUID();
+		const logTag = connId ? `conn=${connId} ` : '';
+		const startTime = Date.now();
+
 		let workspaceDir, resolved;
 		try {
 			const agentId = req.agentId?.trim?.() || 'main'; /* c8 ignore next -- ?./?? fallback */
@@ -410,18 +427,50 @@ export function createFileHandler({ resolveWorkspace, logger, deps = {} }) {
 		} catch {
 			return; // DC 已关闭
 		}
+		remoteLog(`file.dl.start ${logTag}id=${transferId} size=${stat.size}`);
+		/* c8 ignore next -- 空文件分支：进度日志条件下永远不触发，无需 25% 阈值 */
+		let nextLogAt = stat.size > 0 ? Math.floor(stat.size * 0.25) : Infinity;
+		let logStep = 1;
 
 		// 流式发送文件内容
 		const stream = _createReadStream(resolved, { highWaterMark: CHUNK_SIZE });
 		let sentBytes = 0;
 		let dcClosed = false;
 
-		dc.onclose = () => { dcClosed = true; stream.destroy(); };
+		// flow control 状态
+		let bufferedAmountLowCount = 0;
+		let pauseCount = 0;
+		let resumeCount = 0;
+		let pausedNow = false;
+
+		dc.onclose = () => {
+			dcClosed = true;
+			stream.destroy();
+		};
+
+		// pion 异步 send 错误经此回调上报；ndc 同步抛错由 stream.on('data') 的 try/catch 接住
+		dc.onerror = (err) => {
+			if (dcClosed) return;
+			dcClosed = true;
+			stream.destroy();
+			const elapsed = Date.now() - startTime;
+			/* c8 ignore next -- ?? fallback for non-Error throw */
+			const errMsg = err?.message ?? String(err);
+			remoteLog(`file.dl.fail ${logTag}id=${transferId} reason=dc-error err=${errMsg} sent=${sentBytes}/${stat.size} elapsed=${elapsed}ms`);
+			log.warn?.(`[coclaw/file] [${connId ?? '?'}] dl.fail id=${transferId} reason=dc-error sent=${sentBytes}/${stat.size} err=${errMsg}`);
+		};
 
 		if (dc.bufferedAmountLowThreshold !== undefined) {
 			dc.bufferedAmountLowThreshold = LOW_WATER_MARK;
 		}
-		dc.onbufferedamountlow = () => stream.resume();
+		dc.onbufferedamountlow = () => {
+			bufferedAmountLowCount++;
+			if (pausedNow) {
+				resumeCount++;
+				pausedNow = false;
+				stream.resume();
+			}
+		};
 
 		await new Promise((resolve, reject) => {
 			stream.on('data', (chunk) => {
@@ -430,8 +479,17 @@ export function createFileHandler({ resolveWorkspace, logger, deps = {} }) {
 					dc.send(chunk);
 					sentBytes += chunk.length;
 					if (dc.bufferedAmount > HIGH_WATER_MARK) {
+						pauseCount++;
+						pausedNow = true;
 						stream.pause();
 					}
+					// 进度日志（25% / 50% / 75%）
+					if (sentBytes >= nextLogAt && logStep <= 3) {
+						remoteLog(`file.dl.progress ${logTag}id=${transferId} ${logStep * 25}% sent=${sentBytes}/${stat.size}`);
+						logStep++;
+						/* c8 ignore next -- 空文件分支：进入此循环时 stat.size 必然 > 0 */
+						nextLogAt = stat.size > 0 ? Math.floor(stat.size * logStep * 0.25) : Infinity;
+					}
 				/* c8 ignore start -- dc.send 抛异常属罕见竞态 */
 				} catch {
 					dcClosed = true;
@@ -439,18 +497,27 @@ export function createFileHandler({ resolveWorkspace, logger, deps = {} }) {
 				}
 				/* c8 ignore stop */
 			});
-			stream.on('end', () => {
+			stream.on('end', async () => {
 				if (dcClosed) { resolve(); return; }
 				try {
 					dc.send(JSON.stringify({ ok: true, bytes: sentBytes }));
-					dc.close();
+					// 必须 await close()：pion-node 等价 W3C graceful close，
+					// 否则在不支持 graceful 的实现上最后一条 ok JSON 会被丢弃
+					await dc.close();
 				} catch { /* ignore */ }
+				const elapsed = Date.now() - startTime;
+				// 完成时也 dump 一次最终统计，便于事后审计 backpressure 行为
+				remoteLog(`file.dl.ok ${logTag}id=${transferId} bytes=${sentBytes} elapsed=${elapsed}ms balCount=${bufferedAmountLowCount} pauseCount=${pauseCount} resumeCount=${resumeCount}`);
+				log.info?.(`[coclaw/file] [${connId ?? '?'}] dl.ok id=${transferId} bytes=${sentBytes} elapsed=${elapsed}ms balCount=${bufferedAmountLowCount} pauseCount=${pauseCount}`);
 				resolve();
 			});
 			stream.on('error', (err) => {
 				if (!dcClosed) {
 					sendError(dc, 'READ_FAILED', err.message);
 				}
+				const elapsed = Date.now() - startTime;
+				remoteLog(`file.dl.fail ${logTag}id=${transferId} reason=read-error err=${err.message} sent=${sentBytes}/${stat.size} elapsed=${elapsed}ms`);
+				log.warn?.(`[coclaw/file] [${connId ?? '?'}] dl.fail id=${transferId} reason=read-error sent=${sentBytes}/${stat.size} err=${err.message}`);
 				reject(err);
 			});
 		}).catch((err) => {
@@ -630,6 +697,7 @@ export function createFileHandler({ resolveWorkspace, logger, deps = {} }) {
 				if (dcClosed) {
 					safeUnlink(tmpPath);
 					remoteLog(`file.up.fail ${logTag}id=${transferId} reason=dc-closed-before-flush received=${receivedBytes}/${declaredSize} elapsed=${elapsed}ms bp=${wsBackpressureCount}`);
+					log.warn?.(`[coclaw/file] [${connId ?? '?'}] up.fail id=${transferId} reason=dc-closed-before-flush received=${receivedBytes}/${declaredSize} elapsed=${elapsed}ms bp=${wsBackpressureCount}`);
 					return;
 				}
 				const valid = receivedBytes === declaredSize;
@@ -639,9 +707,10 @@ export function createFileHandler({ resolveWorkspace, logger, deps = {} }) {
 					/* c8 ignore next */
 					} catch { /* ignore */ }
 					safeUnlink(tmpPath);
-					/* c8 ignore next */
-					try { dc.close(); } catch { /* ignore */ }
+					// graceful close：必须 await，否则 send 入队的 error JSON 会被 close 丢弃
+					try { await dc.close(); } catch { /* ignore */ }
 					remoteLog(`file.up.fail ${logTag}id=${transferId} reason=size-mismatch expected=${declaredSize} got=${receivedBytes} elapsed=${elapsed}ms`);
+					log.warn?.(`[coclaw/file] [${connId ?? '?'}] up.fail id=${transferId} reason=size-mismatch expected=${declaredSize} got=${receivedBytes} elapsed=${elapsed}ms`);
 					return;
 				}
 				// 先 rename，再发成功响应（避免 rename 失败时 UI 误认为成功）
@@ -654,9 +723,9 @@ export function createFileHandler({ resolveWorkspace, logger, deps = {} }) {
 						dc.send(JSON.stringify({ ok: false, error: { code: 'WRITE_FAILED', message: `rename failed: ${renameErr.message}` } }));
 					} catch { /* ignore */ }
 					safeUnlink(tmpPath);
-					/* c8 ignore next */
-					try { dc.close(); } catch { /* ignore */ }
-					remoteLog(`file.up.fail ${logTag}id=${transferId} reason=rename-failed elapsed=${elapsed}ms`);
+					try { await dc.close(); } catch { /* ignore */ }
+					remoteLog(`file.up.fail ${logTag}id=${transferId} reason=rename-failed received=${receivedBytes} elapsed=${elapsed}ms`);
+					log.warn?.(`[coclaw/file] [${connId ?? '?'}] up.fail id=${transferId} reason=rename-failed received=${receivedBytes} elapsed=${elapsed}ms`);
 					return;
 				}
 				const result = { ok: true, bytes: receivedBytes };
@@ -665,9 +734,10 @@ export function createFileHandler({ resolveWorkspace, logger, deps = {} }) {
 					dc.send(JSON.stringify(result));
 				/* c8 ignore next */
 				} catch { /* ignore */ }
-				/* c8 ignore next */
-				try { dc.close(); } catch { /* ignore */ }
+				// graceful close：上传成功路径同样必须 await，否则 result JSON 会丢
+				try { await dc.close(); } catch { /* ignore */ }
 				remoteLog(`file.up.ok ${logTag}id=${transferId} bytes=${receivedBytes} elapsed=${elapsed}ms bp=${wsBackpressureCount}`);
+				log.info?.(`[coclaw/file] [${connId ?? '?'}] up.ok id=${transferId} bytes=${receivedBytes} elapsed=${elapsed}ms bp=${wsBackpressureCount}`);
 			});
 		}
 
@@ -701,6 +771,7 @@ export function createFileHandler({ resolveWorkspace, logger, deps = {} }) {
 					} catch { /* ignore */ }
 					try { dc.close(); } catch { /* ignore */ }
 					remoteLog(`file.up.reject ${logTag}id=${transferId} reason=size-exceeded received=${receivedBytes}`);
+					log.warn?.(`[coclaw/file] [${connId ?? '?'}] up.reject id=${transferId} reason=size-exceeded received=${receivedBytes}`);
 					return;
 				}
 
@@ -711,6 +782,7 @@ export function createFileHandler({ resolveWorkspace, logger, deps = {} }) {
 				if (receivedBytes >= nextLogAt && logStep <= 3) {
 					remoteLog(`file.up.progress ${logTag}id=${transferId} ${logStep * 25}% received=${receivedBytes}/${declaredSize} bp=${wsBackpressureCount}`);
 					logStep++;
+					/* c8 ignore next -- declaredSize=0 的上传不会达到进度日志阈值 */
 					nextLogAt = declaredSize > 0 ? Math.floor(declaredSize * logStep * 0.25) : Infinity;
 				}
 			}
@@ -728,11 +800,31 @@ export function createFileHandler({ resolveWorkspace, logger, deps = {} }) {
 				safeUnlink(tmpPath);
 				const elapsed = Date.now() - startTime;
 				remoteLog(`file.up.fail ${logTag}id=${transferId} reason=dc-closed received=${receivedBytes}/${declaredSize} elapsed=${elapsed}ms bp=${wsBackpressureCount}`);
+				log.warn?.(`[coclaw/file] [${connId ?? '?'}] up.fail id=${transferId} reason=dc-closed received=${receivedBytes}/${declaredSize} elapsed=${elapsed}ms bp=${wsBackpressureCount}`);
 			}
 		};
 
+		// pion 异步 send 错误经此回调上报；触发已有清理路径
+		dc.onerror = (err) => {
+			if (dcClosed || wsError) return;
+			wsError = true;
+			draining = false;
+			pendingQueue.length = 0;
+			ws.destroy();
+			safeUnlink(tmpPath);
+			const elapsed = Date.now() - startTime;
+			/* c8 ignore next -- ?? fallback for non-Error throw */
+			const errMsg = err?.message ?? String(err);
+			remoteLog(`file.up.fail ${logTag}id=${transferId} reason=dc-error err=${errMsg} received=${receivedBytes}/${declaredSize} elapsed=${elapsed}ms bp=${wsBackpressureCount}`);
+			/* c8 ignore next -- ?./?? fallback */
+			log.warn?.(`[coclaw/file] [${connId ?? '?'}] up.fail id=${transferId} reason=dc-error received=${receivedBytes}/${declaredSize} err=${errMsg}`);
+		};
+
 		// WriteStream 错误处理
 		ws.on('error', (err) => {
+			// 幂等：dc.onerror 路径会先 ws.destroy()，destroy 可能再触发一次 'error'，
+			// 已设 wsError 后直接返回，避免产生第二条 fail 日志
+			if (wsError) return;
 			wsError = true;
 			draining = false;
 			pendingQueue.length = 0;
@@ -744,6 +836,7 @@ export function createFileHandler({ resolveWorkspace, logger, deps = {} }) {
 			safeUnlink(tmpPath);
 			const elapsed = Date.now() - startTime;
 			remoteLog(`file.up.fail ${logTag}id=${transferId} reason=write-error err=${err.code || err.message} received=${receivedBytes}/${declaredSize} elapsed=${elapsed}ms`);
+			log.warn?.(`[coclaw/file] [${connId ?? '?'}] up.fail id=${transferId} reason=write-error received=${receivedBytes}/${declaredSize} elapsed=${elapsed}ms err=${err.code || err.message}`);
 		});
 	}
 
@@ -799,9 +892,11 @@ export function createFileHandler({ resolveWorkspace, logger, deps = {} }) {
 	// --- 工具函数 ---
 
 	function sendError(dc, code, message) {
+		/* c8 ignore next 2 -- DC 可能已关闭，catch 纯防御 */
 		try {
 			dc.send(JSON.stringify({ ok: false, error: { code, message } }));
 		} catch { /* DC 可能已关闭 */ }
+		/* c8 ignore next */
 		try { dc.close(); } catch { /* ignore */ }
 	}
 

package/src/plugin-version.js

@@ -8,6 +8,7 @@ export async function getPluginVersion() {
 	try {
 		const pkgPath = nodePath.resolve(import.meta.dirname, '..', 'package.json');
 		const raw = await fs.readFile(pkgPath, 'utf8');
+		/* c8 ignore next -- ?? fallback */
 		__pluginVersion = JSON.parse(raw).version ?? 'unknown';
 	} catch {
 		return 'unknown';

package/src/realtime-bridge.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import nodePath from 'node:path';
+import { WebSocket as WsWebSocket } from 'ws';
 
 import { clearConfig, getBindingsPath, readConfig } from './config.js';
 import { getHostName, readSettings } from './settings.js';
@@ -84,8 +85,9 @@ export class RealtimeBridge {
 		this.__getBindingsPath = deps.getBindingsPath ?? getBindingsPath;
 		this.__resolveGatewayAuthToken = deps.resolveGatewayAuthToken ?? defaultResolveGatewayAuthToken;
 		this.__loadDeviceIdentity = deps.loadDeviceIdentity ?? loadOrCreateDeviceIdentity;
+		this.__preloadPion = deps.preloadPion ?? null;
 		this.__preloadNdc = deps.preloadNdc ?? null;
-		this.__WebSocket = deps.WebSocket ?? null;
+		this.__WebSocket = deps.WebSocket; // undefined=使用 ws 包, null=禁用（测试用）, 其他=自定义实现
 		this.__gatewayReadyTimeoutMs = deps.gatewayReadyTimeoutMs ?? 1500;
 
 		this.serverWs = null;
@@ -112,7 +114,7 @@ export class RealtimeBridge {
 	}
 
 	__resolveWebSocket() {
-		return this.__WebSocket ?? globalThis.WebSocket;
+		return this.__WebSocket === undefined ? WsWebSocket : this.__WebSocket;
 	}
 
 	__logDebug(message) {
@@ -226,7 +228,8 @@ export class RealtimeBridge {
 		this.webrtcPeer = new WebRtcPeer({
 			onSend: (msg) => this.__forwardToServer(msg),
 			onRequest: (dcPayload) => {
-				void this.__handleGatewayRequestFromServer(dcPayload);
+				this.__handleGatewayRequestFromDc(dcPayload)
+					.catch((err) => this.logger.warn?.(`[coclaw] dc request handler error: ${err?.message}`));
 			},
 			onFileRpc: (payload, sendFn) => {
 				this.__fileHandler.handleRpcRequest(payload, sendFn)
@@ -236,6 +239,7 @@ export class RealtimeBridge {
 				this.__fileHandler.handleFileChannel(dc, connId);
 			},
 			PeerConnection,
+			impl: this.__ndcPreloadResult?.impl,
 			logger: this.logger,
 		});
 	}
@@ -625,8 +629,6 @@ export class RealtimeBridge {
 				return;
 			}
 			if (payload.type === 'res' || payload.type === 'event') {
-				// TODO: UI 已通过 DataChannel 接收业务消息，待旧版 UI 全部更新后移除此转发
-				this.__forwardToServer(payload);
 				this.webrtcPeer?.broadcast(payload);
 			}
 		});
@@ -698,11 +700,11 @@ export class RealtimeBridge {
 		});
 	}
 
-	async __handleGatewayRequestFromServer(payload) {
+	async __handleGatewayRequestFromDc(payload) {
 		const ready = await this.__waitGatewayReady();
 		if (!ready || !this.gatewayWs || this.gatewayWs.readyState !== 1) {
 			this.__logDebug(`gateway req drop (offline): id=${payload.id} method=${payload.method}`);
-			const errorRes = {
+			this.webrtcPeer?.broadcast({
 				type: 'res',
 				id: payload.id,
 				ok: false,
@@ -710,9 +712,7 @@ export class RealtimeBridge {
 					code: 'GATEWAY_OFFLINE',
 					message: 'Gateway is offline',
 				},
-			};
-			this.__forwardToServer(errorRes);
-			this.webrtcPeer?.broadcast(errorRes);
+			});
 			return;
 		}
 		try {
@@ -725,7 +725,7 @@ export class RealtimeBridge {
 			}));
 		}
 		catch {
-			const errorRes = {
+			this.webrtcPeer?.broadcast({
 				type: 'res',
 				id: payload.id,
 				ok: false,
@@ -733,9 +733,7 @@ export class RealtimeBridge {
 					code: 'GATEWAY_SEND_FAILED',
 					message: 'Failed to send request to gateway',
 				},
-			};
-			this.__forwardToServer(errorRes);
-			this.webrtcPeer?.broadcast(errorRes);
+			});
 		}
 	}
 
@@ -848,13 +846,6 @@ export class RealtimeBridge {
 					}
 					return;
 				}
-				if (payload?.type === 'req' || payload?.type === 'rpc.req') {
-					void this.__handleGatewayRequestFromServer({
-						id: payload.id,
-						method: payload.method,
-						params: payload.params ?? {},
-					});
-				}
 			}
 			catch (err) {
 				this.logger.warn?.(`[coclaw] realtime message parse failed: ${String(err?.message ?? err)}`);
@@ -913,6 +904,7 @@ export class RealtimeBridge {
 			this.__clearConnectTimer();
 			setRemoteLogSender(null);
 			remoteLog(`ws.error peer=server msg=${String(err?.message ?? err)}`);
+			/* c8 ignore next -- ?./?? fallback */
 			this.logger.warn?.(`[coclaw] realtime bridge error, will retry in ${RECONNECT_MS}ms: ${String(err?.message ?? err)}`);
 			this.serverWs = null;
 			this.__closeGatewayWs();
@@ -923,27 +915,53 @@ export class RealtimeBridge {
 		});
 	}
 
-	async start({ logger, pluginConfig } = {}) {
-		this.logger = logger ?? console;
-		this.pluginConfig = pluginConfig ?? {};
-		this.started = true;
-		// 先完成 WebRTC 实现加载，再建立连接，避免 UI 发来 offer 时 RTC 包未就绪
-		const preloadFn = this.__preloadNdc
+	/* c8 ignore start -- WebRTC preload 涉及 native/Go 进程，集成测试覆盖 */
+	async __preloadWebrtc() {
+		// 版本预热并行启动
+		const versionPromise = getPluginVersion()
+			.then((v) => { this.__pluginVersion = v; })
+			.catch(() => { this.__pluginVersion = 'unknown'; });
+
+		// 1. 尝试 pion（最高优先级）
+		const preloadPionFn = this.__preloadPion
+			?? (await import('./webrtc/pion-preloader.js')).preloadPion;
+		const pionResult = await preloadPionFn().catch((err) => {
+			this.logger.warn?.(`[coclaw] pion preload unexpected failure: ${err?.message}`);
+			return null;
+		});
+		if (pionResult?.PeerConnection) {
+			await versionPromise;
+			return pionResult;
+		}
+
+		// 2. 回退到 ndc/werift
+		const preloadNdcFn = this.__preloadNdc
 			?? (await import('./webrtc/ndc-preloader.js')).preloadNdc;
-		// 版本预热与 preload 并行，供 gateway connect 请求同步使用
-		const [preloadResult] = await Promise.all([
-			preloadFn().catch((err) => {
-				// preloadNdc 设计上永不 throw，此 catch 为纯防御性兜底
+		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' };
 			}),
-			getPluginVersion()
-				.then((v) => { this.__pluginVersion = v; })
-				.catch(() => { this.__pluginVersion = 'unknown'; }),
+			versionPromise,
 		]);
+		return ndcResult;
+	}
+	/* c8 ignore stop */
+
+	async start({ logger, pluginConfig } = {}) {
+		/* c8 ignore next 2 -- ?? fallback：测试始终注入 logger/pluginConfig */
+		this.logger = logger ?? console;
+		this.pluginConfig = pluginConfig ?? {};
+		this.started = true;
+		// 先完成 WebRTC 实现加载，再建立连接，避免 UI 发来 offer 时 RTC 包未就绪
+		// 优先级：pion → ndc → werift → none
+		const preloadResult = await this.__preloadWebrtc();
 		// 竞态保护：若 preload 期间 stop() 已执行，不再赋值，直接返回。
-		// 不调 cleanup()——与 stop() 策略一致，native threads 保持活跃供后续复用。
 		if (!this.started) {
+			// pion 进程需要关闭
+			if (preloadResult.impl === 'pion' && preloadResult.cleanup) {
+				preloadResult.cleanup().catch(() => {});
+			}
 			return;
 		}
 		this.__ndcPreloadResult = preloadResult;
@@ -978,12 +996,12 @@ export class RealtimeBridge {
 			this.webrtcPeer = null;
 			this.__webrtcPeerReady = null;
 		}
-		// 不在 stop() 中调用 ndc.cleanup()：
-		// cleanup() 是同步 native 调用，需 join native threads，耗时 10s+，
-		// 会阻塞事件循环导致 RPC handler 超时。
-		// gateway 是长驻进程，native threads 保持活跃即可；
-		// 下次 start() 重新 import（ESM 缓存命中）可直接复用。
-		// 进程退出时 OS 会回收所有资源。
+		// pion: 关闭 Go 进程（异步，快速）
+		// ndc: 不调用 cleanup()——同步 join native threads 耗时 10s+，进程退出时 OS 回收
+		const impl = this.__ndcPreloadResult?.impl;
+		if (impl === 'pion' && this.__ndcCleanup) {
+			await this.__ndcCleanup().catch(() => {});
+		}
 		this.__ndcCleanup = null;
 		this.__ndcPreloadResult = null;
 		if (this.__fileHandler) {
@@ -1029,7 +1047,8 @@ export async function restartRealtimeBridge(opts) {
 		await singleton.stop();
 		singleton = null;
 	}
-	singleton = new RealtimeBridge();
+	const deps = opts?.__deps; // 仅测试用
+	singleton = new RealtimeBridge(deps);
 	await singleton.start(opts);
 }
 
@@ -1043,11 +1062,14 @@ export async function stopRealtimeBridge({ forceCleanup = false } = {}) {
 	if (!singleton) {
 		return;
 	}
-	const cleanupFn = forceCleanup ? singleton.__ndcCleanup : null;
+	// 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 路径不触发 */
 	if (typeof cleanupFn === 'function') {
-		try { cleanupFn(); } catch { /* c8 ignore next -- cleanup 失败不影响 stop 结果 */ }
+		try { cleanupFn(); } catch { /* cleanup 失败不影响 stop 结果 */ }
 	}
 }
 
@@ -1086,5 +1108,5 @@ export function broadcastPluginEvent(event, payload) {
 	if (!singleton) return;
 	const frame = { type: 'event', event, payload };
 	singleton.__forwardToServer(frame);
-	singleton.webrtcPeer?.broadcast(frame);
+	singleton.webrtcPeer?.broadcast(frame); /* c8 ignore -- ?. fallback */
 }

package/src/session-manager/manager.js

@@ -242,6 +242,7 @@ export function createSessionManager(options = {}) {
 				indexed: true,
 				archiveType: 'live',
 				fileName: null,
+				/* c8 ignore next -- ?? fallback */
 				updatedAt: entry.updatedAt ?? 0,
 				size: 0,
 			});

package/src/settings.js

@@ -75,5 +75,6 @@ export async function writeName(name) {
  */
 export function getHostName() {
 	const raw = os.hostname().trim();
+	/* c8 ignore next -- || fallback：hostname 恰好等于 ".local" 的情况极罕见 */
 	return raw.replace(/\.local$/i, '') || 'openclaw';
 }

package/src/topic-manager/manager.js

@@ -29,6 +29,7 @@ export class TopicManager {
 	 * @param {Function} [opts.copyFile] - 测试注入
 	 */
 	constructor(opts = {}) {
+		/* c8 ignore next 6 -- ?? fallback：测试始终注入 */
 		this.__rootDir = opts.rootDir ?? nodePath.join(os.homedir(), '.openclaw', 'agents');
 		this.__logger = opts.logger ?? console;
 		this.__readFile = opts.readFile ?? fs.readFile;

package/src/topic-manager/title-gen.js

@@ -136,10 +136,12 @@ export async function generateTitle({ topicId, topicManager, agentRpc, logger })
 		await topicManager.updateTitle({ topicId, title });
 		return { title };
 	} catch (err) {
+		/* c8 ignore next -- ?./?? fallback */
 		log.warn?.(`[coclaw] generateTitle failed for topic ${topicId}: ${String(err?.message ?? err)}`);
 		throw err;
 	} finally {
 		// 清理临时文件
+		/* c8 ignore next -- .catch() 防御 */
 		await topicManager.cleanupTempFile(tempPath).catch(() => {});
 	}
 }

package/src/webrtc/dc-chunking.js

@@ -82,7 +82,7 @@ export function createReassembler(onComplete, opts = {}) {
 		// binary = 分片 chunk
 		const buf = Buffer.isBuffer(data) ? data : Buffer.from(data);
 		if (buf.length < HEADER_SIZE) {
-			logger?.warn?.('[dc-chunking] chunk too short, discarding');
+			logger?.warn?.('[dc-chunking] chunk too short, discarding'); /* c8 ignore -- ?./?. fallback */
 			return;
 		}
 

package/src/webrtc/ndc-preloader.js

@@ -73,6 +73,7 @@ function wrapNdcCredentials(NativeRTC) {
 				config = {
 					...config,
 					iceServers: config.iceServers.map(s => {
+						/* c8 ignore next -- TURN 无凭据时的短路，集成环境下不经过此路径 */
 						if (!s.username && !s.credential) return s;
 						return {
 							...s,
@@ -185,6 +186,7 @@ export async function preloadNdc(deps = {}) {
 		// 用于捕获 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 {

package/src/webrtc/pion-preloader.js

@@ -0,0 +1,83 @@
+import { remoteLog as defaultRemoteLog } from '../remote-log.js';
+
+const DEFAULT_START_TIMEOUT_MS = 10_000;
+
+/**
+ * 预加载 Pion WebRTC 实现：启动 pion-ipc Go 进程，返回绑定了 ipc 的 PeerConnection。
+ *
+ * **此函数永不 throw**——所有异常内部捕获，通过 remoteLog 报告。
+ * 失败时返回 null（调用方降级到 ndc/werift）。
+ *
+ * binary 解析由 @coclaw/pion-node 内部处理（env → npm 平台包 → PATH）。
+ *
+ * @param {object} [deps] - 可注入依赖（测试用）
+ * @param {Function} [deps.dynamicImport] - (specifier) => import(specifier)
+ * @param {Function} [deps.remoteLog] - (text) => void
+ * @param {number} [deps.startTimeout] - 启动超时（ms），默认 10s
+ * @returns {Promise<{ PeerConnection: Function, cleanup: Function, impl: string, ipc: object }|null>}
+ */
+export async function preloadPion(deps = {}) {
+	const log = deps.remoteLog ?? defaultRemoteLog;
+	const dynamicImport = deps.dynamicImport ?? ((spec) => import(spec));
+	const startTimeout = deps.startTimeout ?? DEFAULT_START_TIMEOUT_MS;
+
+	log('pion.preload');
+
+	let ipc = null;
+	try {
+		// 加载 pion-node SDK
+		let PionIpc, RTCPeerConnection;
+		try {
+			const mod = await dynamicImport('@coclaw/pion-node');
+			PionIpc = mod.PionIpc;
+			RTCPeerConnection = mod.RTCPeerConnection;
+		} catch (err) {
+			log(`pion.skip reason=import-failed error=${err.message}`);
+			return null;
+		}
+
+		if (typeof PionIpc !== 'function' || typeof RTCPeerConnection !== 'function') {
+			log('pion.skip reason=invalid-exports');
+			return null;
+		}
+
+		// 启动 IPC 进程（内部会 ping 验证就绪，binary 由 pion-node 自动解析）
+		ipc = new PionIpc({
+			logger: (msg) => log(`pion.ipc ${msg}`),
+			timeout: startTimeout,
+			autoRestart: true,
+		});
+
+		try {
+			await ipc.start();
+		} catch (err) {
+			log(`pion.skip reason=start-failed error=${err.message}`);
+			return null;
+		}
+
+		// 创建绑定了 ipc 的 PeerConnection 子类
+		class BoundPeerConnection extends RTCPeerConnection {
+			constructor(config = {}) {
+				super({ ...config, _ipc: ipc });
+			}
+		}
+
+		const cleanup = async () => {
+			try {
+				await ipc.stop();
+			} catch {
+				// 静默忽略，stop 失败不影响后续
+			}
+		};
+
+		log('pion.loaded');
+		return { PeerConnection: BoundPeerConnection, cleanup, impl: 'pion', ipc };
+	} catch (err) {
+		// ipc 已启动但后续步骤意外失败 → 关闭 Go 进程，防止泄漏
+		if (ipc) {
+			ipc.stop().catch(() => {});
+		}
+		log(`pion.skip reason=unexpected error=${err.message}`);
+		return null;
+	}
+}

package/src/webrtc/webrtc-peer.js

@@ -1,6 +1,10 @@
 import { chunkAndSend, createReassembler } from './dc-chunking.js';
 import { remoteLog } from '../remote-log.js';
 
+// 单个 session 内 file DC 历史快照的容量上限（满后按 FIFO 淘汰最老条目）。
+// 用于诊断 dump：过大会撑爆 remoteLog 单帧，20 足以覆盖典型多文件传输会话。
+const FILE_CHANNEL_HISTORY_LIMIT = 20;
+
 /**
  * 管理多个 WebRTC PeerConnection（以 connId 为粒度）。
  * Plugin 作为被叫方：收到 UI 的 offer → 回复 answer。
@@ -14,8 +18,9 @@ export class WebRtcPeer {
 	 * @param {function} [opts.onFileChannel] - file:<transferId> DataChannel 的回调 (dc, connId) => void
 	 * @param {object} [opts.logger] - pino 风格 logger
 	 * @param {function} opts.PeerConnection - RTCPeerConnection 构造函数（由 ndc-preloader 提供）
+	 * @param {string} [opts.impl] - WebRTC 实现标识（pion / ndc / werift）
 	 */
-	constructor({ onSend, onRequest, onFileRpc, onFileChannel, logger, PeerConnection }) {
+	constructor({ onSend, onRequest, onFileRpc, onFileChannel, logger, PeerConnection, impl }) {
 		if (!PeerConnection) {
 			throw new Error('PeerConnection constructor is required');
 		}
@@ -25,6 +30,8 @@ export class WebRtcPeer {
 		this.__onFileChannel = onFileChannel;
 		this.logger = logger ?? console;
 		this.__PeerConnection = PeerConnection;
+		this.__impl = impl ?? null;
+		this.__rtcTag = impl ? `[coclaw/rtc:${impl}]` : '[coclaw/rtc]';
 		/** @type {Map<string, { pc: object, rpcChannel: object|null, remoteMaxMessageSize: number, nextMsgId: number }>} */
 		this.__sessions = new Map();
 	}
@@ -52,9 +59,12 @@ export class WebRtcPeer {
 		// 先 detach 事件，防止 pc.close() 异步触发 onconnectionstatechange 删除新 session
 		session.pc.onconnectionstatechange = null;
 		session.pc.onicecandidate = null;
+		if ('onselectedcandidatepairchange' in session.pc) {
+			session.pc.onselectedcandidatepairchange = null;
+		}
 		await session.pc.close();
-		remoteLog(`rtc.closed conn=${connId}`);
-		this.logger.info?.(`[coclaw/rtc] [${connId}] closed`);
+		this.__remoteLog(`rtc.closed conn=${connId}`);
+		this.logger.info?.(`${this.__rtcTag} [${connId}] closed`);
 	}
 
 	/** 关闭所有 PeerConnection */
@@ -86,8 +96,8 @@ export class WebRtcPeer {
 		if (isIceRestart) {
 			const existing = this.__sessions.get(connId);
 			if (existing) {
-				remoteLog(`rtc.ice-restart conn=${connId}`);
-				this.logger.info?.(`[coclaw/rtc] ICE restart offer from ${connId}, renegotiating`);
+				this.__remoteLog(`rtc.ice-restart conn=${connId}`);
+				this.logger.info?.(`${this.__rtcTag} ICE restart offer from ${connId}, renegotiating`);
 				try {
 					await existing.pc.setRemoteDescription({ type: 'offer', sdp: msg.payload.sdp });
 					const answer = await existing.pc.createAnswer();
@@ -97,20 +107,37 @@ export class WebRtcPeer {
 						toConnId: connId,
 						payload: { sdp: answer.sdp },
 					});
-					this.logger.info?.(`[coclaw/rtc] ICE restart answer sent to ${connId}`);
+					this.logger.info?.(`${this.__rtcTag} ICE restart answer sent to ${connId}`);
 					return;
 				} catch (err) {
-					// ICE restart 协商失败 → 回退到 full rebuild
-					remoteLog(`rtc.ice-restart-failed conn=${connId}`);
-					this.logger.warn?.(`[coclaw/rtc] ICE restart failed for ${connId}, falling back to rebuild: ${err?.message}`);
-					await this.closeByConnId(connId);
+					// ICE restart 协商失败 → reject，不 fall through
+					this.__remoteLog(`rtc.ice-restart-failed conn=${connId}`);
+					this.logger.warn?.(`${this.__rtcTag} ICE restart failed for ${connId}: ${err?.message}`);
+					this.__onSend({
+						type: 'rtc:restart-rejected',
+						toConnId: connId,
+						payload: { reason: 'restart_failed' },
+					});
+					await this.closeByConnId(connId).catch((closeErr) => {
+						/* c8 ignore next -- closeByConnId 内部已 try/catch，此路径极难触发 */
+						this.logger.warn?.(`${this.__rtcTag} closeByConnId failed after restart rejection for ${connId}: ${closeErr?.message}`);
+					});
+					return;
 				}
 			}
-			// 无现有 session 或 ICE restart 失败 → 按 full rebuild 继续
+			// 无 session → reject（plugin 可能已重启）
+			this.__remoteLog(`rtc.ice-restart-no-session conn=${connId}`);
+			this.logger.warn?.(`${this.__rtcTag} ICE restart from ${connId} but no session, rejecting`);
+			this.__onSend({
+				type: 'rtc:restart-rejected',
+				toConnId: connId,
+				payload: { reason: 'no_session' },
+			});
+			return;
 		}
 
-		remoteLog(`rtc.offer conn=${connId}`);
-		this.logger.info?.(`[coclaw/rtc] offer received from ${connId}, creating answer`);
+		this.__remoteLog(`rtc.offer conn=${connId}`);
+		this.logger.info?.(`${this.__rtcTag} offer received from ${connId}, creating answer`);
 
 		// 同一 connId 重复 offer → 先关闭旧连接
 		if (this.__sessions.has(connId)) {
@@ -135,15 +162,19 @@ export class WebRtcPeer {
 		// 记录 ICE 服务器配置（脱敏，不含 credential）
 		const stunUrl = iceServers.find((s) => s.urls?.startsWith('stun:'))?.urls ?? 'none';
 		const turnUrl = iceServers.find((s) => s.urls?.startsWith('turn:'))?.urls ?? 'none';
-		remoteLog(`rtc.ice-config conn=${connId} stun=${stunUrl} turn=${turnUrl}`);
+		this.__remoteLog(`rtc.ice-config conn=${connId} stun=${stunUrl} turn=${turnUrl}`);
 
 		const pc = new this.__PeerConnection({ iceServers });
 
-		// 从 SDP 解析对端 maxMessageSize（用于分片决策）
+		// 分片阈值 = min(远端能接收, 本地能发送)
+		// 远端：从 offer SDP 的 a=max-message-size 解析（缺失则 RFC 8841 默认 65536）
+		// 本地：pc.maxMessageSize（pion 为 65536，ndc/werift 无此属性则不限制）
 		const mmsMatch = msg.payload.sdp?.match(/a=max-message-size:(\d+)/);
-		const remoteMaxMessageSize = mmsMatch ? parseInt(mmsMatch[1], 10) : 65536;
+		const remoteMMS = mmsMatch ? parseInt(mmsMatch[1], 10) : 65536;
+		const localMMS = pc.maxMessageSize ?? remoteMMS;
+		const remoteMaxMessageSize = Math.min(remoteMMS, localMMS);
 
-		const session = { pc, rpcChannel: null, remoteMaxMessageSize, nextMsgId: 1 };
+		const session = { pc, rpcChannel: null, fileChannels: new Set(), remoteMaxMessageSize, nextMsgId: 1 };
 		this.__sessions.set(connId, session);
 
 		// ICE candidate → 发给 UI，并统计各类型 candidate 数量
@@ -151,7 +182,7 @@ export class WebRtcPeer {
 		pc.onicecandidate = ({ candidate }) => {
 			if (!candidate) {
 				// gathering 完成，输出汇总
-				remoteLog(`rtc.ice-gathered conn=${connId} host=${candidateCounts.host} srflx=${candidateCounts.srflx} relay=${candidateCounts.relay}`);
+				this.__remoteLog(`rtc.ice-gathered conn=${connId} host=${candidateCounts.host} srflx=${candidateCounts.srflx} relay=${candidateCounts.relay}`);
 				return;
 			}
 			// 从 candidate 字符串中提取类型（typ host / typ srflx / typ relay）
@@ -173,34 +204,68 @@ export class WebRtcPeer {
 		// 连接状态变更（校验 pc 归属，防止旧 PC 异步回调删除新 session）
 		pc.onconnectionstatechange = () => {
 			const state = pc.connectionState;
-			remoteLog(`rtc.state conn=${connId} ${state}`);
-			this.logger.info?.(`[coclaw/rtc] [${connId}] connectionState: ${state}`);
+			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;
+
 			if (state === 'connected') {
+				// 重置 dump 去重水位（disconnected → connected → disconnected 仍能再 dump）
+				cur.__lastDumpState = null;
+				// werift: iceTransports[0].connection.nominated
 				const nominated = pc.iceTransports?.[0]?.connection?.nominated;
 				if (nominated) {
 					const localC = nominated.localCandidate;
 					const remoteC = nominated.remoteCandidate;
 					const localInfo = `${localC?.type ?? '?'} ${localC?.host ?? '?'}:${localC?.port ?? '?'}`;
 					const remoteInfo = `${remoteC?.type ?? '?'} ${remoteC?.host ?? '?'}:${remoteC?.port ?? '?'}`;
-					remoteLog(`rtc.ice-nominated conn=${connId} local=${localInfo} remote=${remoteInfo}`);
-					this.logger.info?.(`[coclaw/rtc] [${connId}] ICE nominated: local=${localInfo} remote=${remoteInfo}`);
+					this.__remoteLog(`rtc.ice-nominated conn=${connId} local=${localInfo} remote=${remoteInfo}`);
+					this.logger.info?.(`${this.__rtcTag} [${connId}] ICE nominated: local=${localInfo} remote=${remoteInfo}`);
+				}
+				// pion: pair 通过独立的 selectedcandidatepairchange 事件上报
+			} else if (state === 'disconnected' || state === 'failed' || state === 'closed') {
+				// 诊断 dump：失败/断连/关闭时输出当前 PC 上 DC 状态，定位"PC 假活/DC 死"现象
+				// - closed 多由本地主动关闭触发，dump 收敛诊断噪声但仍清理 session
+				// - disconnected 可能反复触发，去重避免噪声
+				if (state !== 'closed' && cur.__lastDumpState !== state) {
+					cur.__lastDumpState = state;
+					this.__dumpSessionState(connId, cur, state);
 				}
-			} else if (state === 'failed' || state === 'closed') {
-				const cur = this.__sessions.get(connId);
-				if (cur && cur.pc === pc) {
+				// 仅 closed 删除 session；failed 保留以支持 ICE restart 恢复
+				// （如 app 后台冻结 → pion ICE failed → 前台恢复后 restart）
+				if (state === 'closed') {
 					this.__sessions.delete(connId);
 				}
 			}
 		};
 
+		// pion: 选中的 candidate pair 通过独立事件上报
+		if ('onselectedcandidatepairchange' in pc) {
+			pc.onselectedcandidatepairchange = () => {
+				const pair = pc.selectedCandidatePair;
+				if (pair) {
+					this.__logNominatedPair(connId, pair);
+				}
+			};
+		}
+
 		// 监听 UI 创建的 DataChannel
 		pc.ondatachannel = ({ channel }) => {
-			remoteLog(`dc.received conn=${connId} label=${channel.label}`);
-			this.logger.info?.(`[coclaw/rtc] [${connId}] DataChannel "${channel.label}" received`);
+			this.__remoteLog(`dc.received conn=${connId} label=${channel.label}`);
+			this.logger.info?.(`${this.__rtcTag} [${connId}] DataChannel "${channel.label}" received`);
 			if (channel.label === 'rpc') {
 				session.rpcChannel = channel;
 				this.__setupDataChannel(connId, channel);
 			} else if (channel.label.startsWith('file:')) {
+				// 跟踪 file DC 用于诊断 dump：保留全量历史以便排查"传输到一半挂掉"场景，
+				// 但用 FIFO 上限避免长会话内无界增长
+				if (session.fileChannels.size >= FILE_CHANNEL_HISTORY_LIMIT) {
+					const oldest = session.fileChannels.values().next().value;
+					session.fileChannels.delete(oldest);
+				}
+				session.fileChannels.add(channel);
 				this.__onFileChannel?.(channel, connId);
 			}
 		};
@@ -216,8 +281,8 @@ export class WebRtcPeer {
 				toConnId: connId,
 				payload: { sdp: answer.sdp },
 			});
-			remoteLog(`rtc.answer conn=${connId}`);
-			this.logger.info?.(`[coclaw/rtc] answer sent to ${connId}`);
+			this.__remoteLog(`rtc.answer conn=${connId}`);
+			this.logger.info?.(`${this.__rtcTag} answer sent to ${connId}`);
 		} catch (err) {
 			// SDP 协商失败 → 清理已入 Map 的 session，避免泄漏
 			const cur = this.__sessions.get(connId);
@@ -236,8 +301,12 @@ export class WebRtcPeer {
 			this.__logDebug(`ICE candidate from ${connId} but no session`);
 			return;
 		}
-		await session.pc.addIceCandidate(msg.payload);
-		this.__logDebug(`[${connId}] ICE candidate added`);
+		try {
+			await session.pc.addIceCandidate(msg.payload);
+			this.__logDebug(`[${connId}] ICE candidate added`);
+		} catch (err) {
+			this.__logDebug(`[${connId}] addIceCandidate failed: ${err?.message}`);
+		}
 	}
 
 	__setupDataChannel(connId, dc) {
@@ -275,33 +344,58 @@ export class WebRtcPeer {
 		}, { logger: this.logger });
 
 		dc.onopen = () => {
-			remoteLog(`dc.open conn=${connId} label=${dc.label}`);
-			this.logger.info?.(`[coclaw/rtc] [${connId}] DataChannel "${dc.label}" opened`);
+			this.__remoteLog(`dc.open conn=${connId} label=${dc.label}`);
+			this.logger.info?.(`${this.__rtcTag} [${connId}] DataChannel "${dc.label}" opened`);
 		};
 		dc.onclose = () => {
-			remoteLog(`dc.closed conn=${connId} label=${dc.label}`);
-			this.logger.info?.(`[coclaw/rtc] [${connId}] DataChannel "${dc.label}" closed`);
+			this.__remoteLog(`dc.closed conn=${connId} label=${dc.label}`);
+			this.logger.info?.(`${this.__rtcTag} [${connId}] DataChannel "${dc.label}" closed`);
 			reassembler.reset();
 			const session = this.__sessions.get(connId);
 			if (session && dc.label === 'rpc') session.rpcChannel = null;
 		};
 		dc.onerror = (err) => {
-			remoteLog(`dc.error conn=${connId} label=${dc.label}`);
+			this.__remoteLog(`dc.error conn=${connId} label=${dc.label}`);
 			/* c8 ignore next -- ?./?? fallback */
-			this.logger.warn?.(`[coclaw/rtc] [${connId}] DataChannel "${dc.label}" error: ${String(err?.message ?? err)}`);
+			this.logger.warn?.(`${this.__rtcTag} [${connId}] DataChannel "${dc.label}" error: ${String(err?.message ?? err)}`);
 		};
 		dc.onmessage = (event) => {
 			try {
 				reassembler.feed(event.data);
 			} catch (err) {
-				this.logger.warn?.(`[coclaw/rtc] [${connId}] DC message error: ${err.message}`);
+				this.logger.warn?.(`${this.__rtcTag} [${connId}] DC message error: ${err.message}`);
 			}
 		};
 	}
 
+	/**
+	 * 失败/断连时输出 session 诊断快照：rpc/file DC readyState、session 总数。
+	 * 用于定位"PC 假活但 DC 已死"或"PC 已断但 DC 仍在传"的异常现象。
+	 */
+	__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(',');
+		this.__remoteLog(`rtc.dump conn=${connId} state=${state} sessions=${this.__sessions.size} rpc=${rpcState} fileCount=${session.fileChannels.size} files=[${fileSummary}]`);
+		this.logger.info?.(`${this.__rtcTag} [${connId}] dump state=${state} rpc=${rpcState} fileCount=${session.fileChannels.size} files=${fileSummary}`);
+	}
+
+	__logNominatedPair(connId, pair) {
+		const localInfo = `${pair.local?.type ?? '?'} ${pair.local?.address ?? pair.local?.host ?? '?'}:${pair.local?.port ?? '?'}`;
+		const remoteInfo = `${pair.remote?.type ?? '?'} ${pair.remote?.address ?? pair.remote?.host ?? '?'}:${pair.remote?.port ?? '?'}`;
+		this.__remoteLog(`rtc.ice-nominated conn=${connId} local=${localInfo} remote=${remoteInfo}`);
+		this.logger.info?.(`${this.__rtcTag} [${connId}] ICE nominated: local=${localInfo} remote=${remoteInfo}`);
+	}
+
+	__remoteLog(msg) {
+		remoteLog(this.__impl ? `${msg} rtc=${this.__impl}` : msg);
+	}
+
 	__logDebug(message) {
 		if (typeof this.logger?.debug === 'function') {
-			this.logger.debug(`[coclaw/rtc] ${message}`);
+			this.logger.debug(`${this.__rtcTag} ${message}`);
 		}
 	}
 }