@coclaw/openclaw-coclaw 0.13.1 → 0.14.0

package/index.js

@@ -13,6 +13,7 @@ import { generateTitle } from './src/topic-manager/title-gen.js';
 import { AutoUpgradeScheduler } from './src/auto-upgrade/updater.js';
 import { getPackageInfo } from './src/auto-upgrade/updater-check.js';
 import { createFileHandler } from './src/file-manager/handler.js';
+import { abortAgentRun } from './src/agent-abort.js';
 
 import { getPluginVersion, __resetPluginVersion } from './src/plugin-version.js';
 export { getPluginVersion, __resetPluginVersion };
@@ -457,6 +458,27 @@ const plugin = {
 			}
 		});
 
+		// 取消正在执行的 embedded agent run（通过 OpenClaw 全局 symbol 侧门）
+		// 侧门不存在 / sessionId 未注册 / handle.abort 抛异常时返回 { ok:false, reason } —— UI 静默降级
+		api.registerGatewayMethod('coclaw.agent.abort', ({ params, respond }) => {
+			try {
+				const sessionId = params?.sessionId;
+				if (typeof sessionId !== 'string' || !sessionId) {
+					logger.warn?.(`[coclaw.agent.abort] invalid sessionId: ${JSON.stringify(sessionId)}`);
+					respondInvalid(respond, 'sessionId is required');
+					return;
+				}
+				logger.info?.(`[coclaw.agent.abort] request sessionId=${sessionId}`);
+				const result = abortAgentRun(sessionId, logger);
+				logger.info?.(`[coclaw.agent.abort] result sessionId=${sessionId} ok=${result.ok}${result.reason ? ` reason=${result.reason}` : ''}${result.error ? ` error=${result.error}` : ''}`);
+				respond(true, result);
+			}
+			catch (err) {
+				logger.error?.(`[coclaw.agent.abort] handler threw: ${String(err?.message ?? err)}`);
+				respondError(respond, err);
+			}
+		});
+
 		api.registerGatewayMethod('coclaw.upgradeHealth', async ({ respond }) => {
 			try {
 				const { version } = await getPackageInfo();

package/package.json

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

package/src/agent-abort.js

@@ -0,0 +1,106 @@
+/**
+ * agent-abort：封装 OpenClaw embedded agent run 的侧门取消入口
+ *
+ * OpenClaw 自 v2026.3.12 起通过全局 symbol 注册表暴露 activeRuns 映射，
+ * 允许外部根据 sessionId 调 handle.abort() 真正终止正在执行的 agent run
+ *（LLM + 工具 + compaction 均受影响）。
+ *
+ * 本模块是 CoClaw 插件访问该侧门的唯一入口，未来上游提供正式 API 时集中替换。
+ */
+
+const EMBEDDED_RUN_STATE_KEY = Symbol.for('openclaw.embeddedRunState');
+const REPLY_RUN_STATE_KEY = Symbol.for('openclaw.replyRunRegistry');
+
+/* c8 ignore start */ // 临时诊断代码，定位完问题会删除
+/**
+ * 诊断用：从 reply-run-registry 全局单例中解析 sessionId → sessionKey 映射及概览
+ * @param {string} sessionId
+ * @returns {string}
+ */
+function describeReplyRunRegistry(sessionId) {
+	const state = globalThis[REPLY_RUN_STATE_KEY];
+	if (!state) return 'reply.state=absent';
+	const parts = [];
+	const runs = state.activeRunsByKey;
+	if (runs && typeof runs.size === 'number') {
+		parts.push(`reply.activeRunsByKey.size=${runs.size}`);
+		try {
+			const ks = [];
+			if (typeof runs.keys === 'function') {
+				for (const k of runs.keys()) {
+					ks.push(k);
+					if (ks.length >= 10) break;
+				}
+			}
+			parts.push(`reply.keys=${JSON.stringify(ks)}`);
+		}
+		catch (e) {
+			parts.push(`reply.keysErr=${String(e?.message ?? e)}`);
+		}
+	}
+	else {
+		parts.push('reply.activeRunsByKey=absent');
+	}
+	const byId = state.activeKeysBySessionId;
+	if (byId && typeof byId.get === 'function') {
+		try {
+			const mapped = byId.get(sessionId);
+			parts.push(`reply.keyForSid=${mapped === undefined ? 'null' : JSON.stringify(mapped)}`);
+		}
+		catch (e) {
+			parts.push(`reply.keyForSidErr=${String(e?.message ?? e)}`);
+		}
+	}
+	else {
+		parts.push('reply.activeKeysBySessionId=absent');
+	}
+	return parts.join(' ');
+}
+/* c8 ignore stop */
+
+/**
+ * 尝试取消 sessionId 对应的 embedded agent run
+ * @param {string} sessionId
+ * @param {{ info?: Function }} [logger] - 可选 logger；传入时在 not-found 分支 dump activeRuns 诊断信息
+ * @returns {{ ok: true } | { ok: false, reason: 'not-supported' | 'not-found' | 'abort-threw', error?: string }}
+ */
+export function abortAgentRun(sessionId, logger) {
+	const state = globalThis[EMBEDDED_RUN_STATE_KEY];
+	if (!state || !state.activeRuns || typeof state.activeRuns.get !== 'function') {
+		return { ok: false, reason: 'not-supported' };
+	}
+	try {
+		const handle = state.activeRuns.get(sessionId);
+		if (!handle) {
+			/* c8 ignore start */ // 临时诊断代码，定位完问题会删除
+			if (logger?.info) {
+				let diag = `sessionId=${sessionId} embedded.size=${state.activeRuns.size ?? '?'}`;
+				try {
+					const ks = [];
+					if (typeof state.activeRuns.keys === 'function') {
+						for (const k of state.activeRuns.keys()) {
+							ks.push(k);
+							if (ks.length >= 10) break;
+						}
+					}
+					diag += ` embedded.keys=${JSON.stringify(ks)}`;
+				}
+				catch (e) {
+					diag += ` embedded.keysErr=${String(e?.message ?? e)}`;
+				}
+				diag += ` ${describeReplyRunRegistry(sessionId)}`;
+				logger.info(`[coclaw.agent.abort] not-found diag ${diag}`);
+			}
+			/* c8 ignore stop */
+			return { ok: false, reason: 'not-found' };
+		}
+		// shape 守卫：abort 字段应为函数；若不是说明 OpenClaw handle 契约变化（归入 not-supported 让 UI 提示升级）
+		if (typeof handle.abort !== 'function') return { ok: false, reason: 'not-supported' };
+		handle.abort();
+		return { ok: true };
+	}
+	catch (err) {
+		// activeRuns.get() 或 handle.abort() 抛（非 Map 实现 / OpenClaw 内部错误）
+		return { ok: false, reason: 'abort-threw', error: String(err?.message ?? err) };
+	}
+}

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

@@ -114,7 +114,8 @@ export async function generateTitle({ topicId, topicManager, agentRpc, logger })
 			message: '请为这段对话生成标题',
 			idempotencyKey: randomUUID(),
 		}, {
-			timeoutMs: 60_000,
+			// 题目生成需等待 LLM 完整响应；60s 在复杂对话/慢模型下易超时
+			timeoutMs: 300_000,
 			acceptTimeoutMs: 10_000,
 		});
 

package/src/webrtc/dc-chunking.js

@@ -22,20 +22,15 @@ const encoder = new TextEncoder();
 const decoder = new TextDecoder();
 
 /**
- * 按需分片并发送消息
- * 小于 maxMessageSize 直接发 string；否则切成 binary chunk 逐个发送
- * @param {object} dc - DataChannel（werift 或浏览器）
+ * 按需分片：小于等于 maxMessageSize 返回 null（调用方直发 string），否则返回 chunk 数组
  * @param {string} jsonStr - 已序列化的 JSON 字符串
  * @param {number} maxMessageSize - 对端声明的 maxMessageSize
  * @param {() => number} getNextMsgId - 获取下一个 msgId
+ * @returns {Buffer[]|null} null 表示不需要分片；否则为 chunk Buffer 数组
  */
-export function chunkAndSend(dc, jsonStr, maxMessageSize, getNextMsgId, logger) {
+export function buildChunks(jsonStr, maxMessageSize, getNextMsgId) {
 	const fullBytes = encoder.encode(jsonStr);
-	// 快路径：不需要分片
-	if (fullBytes.byteLength <= maxMessageSize) {
-		dc.send(jsonStr);
-		return;
-	}
+	if (fullBytes.byteLength <= maxMessageSize) return null;
 
 	const chunkPayloadSize = maxMessageSize - HEADER_SIZE;
 	if (chunkPayloadSize <= 0) {
@@ -44,7 +39,7 @@ export function chunkAndSend(dc, jsonStr, maxMessageSize, getNextMsgId, logger)
 
 	const msgId = getNextMsgId();
 	const totalChunks = Math.ceil(fullBytes.byteLength / chunkPayloadSize);
-	logger?.info?.(`[dc-chunking] chunking msgId=${msgId}: ${fullBytes.byteLength} bytes → ${totalChunks} chunks (maxMsgSize=${maxMessageSize})`);
+	const chunks = new Array(totalChunks);
 
 	for (let i = 0; i < totalChunks; i++) {
 		const start = i * chunkPayloadSize;
@@ -55,7 +50,30 @@ export function chunkAndSend(dc, jsonStr, maxMessageSize, getNextMsgId, logger)
 		chunk[0] = flag;
 		chunk.writeUInt32BE(msgId, 1);
 		chunk.set(fullBytes.subarray(start, end), HEADER_SIZE);
+		chunks[i] = chunk;
+	}
+	return chunks;
+}
 
+/**
+ * 按需分片并发送消息（薄包装：buildChunks + dc.send）
+ * 注意：无应用层流控；生产路径请使用 RpcSendQueue
+ * @param {object} dc - DataChannel
+ * @param {string} jsonStr - 已序列化的 JSON 字符串
+ * @param {number} maxMessageSize - 对端声明的 maxMessageSize
+ * @param {() => number} getNextMsgId - 获取下一个 msgId
+ * @param {object} [logger] - 可选 logger
+ */
+export function chunkAndSend(dc, jsonStr, maxMessageSize, getNextMsgId, logger) {
+	const chunks = buildChunks(jsonStr, maxMessageSize, getNextMsgId);
+	if (!chunks) {
+		dc.send(jsonStr);
+		return;
+	}
+	const msgId = chunks[0].readUInt32BE(1);
+	const totalBytes = chunks.reduce((n, c) => n + (c.length - HEADER_SIZE), 0);
+	logger?.info?.(`[dc-chunking] chunking msgId=${msgId}: ${totalBytes} bytes → ${chunks.length} chunks (maxMsgSize=${maxMessageSize})`);
+	for (const chunk of chunks) {
 		dc.send(chunk);
 	}
 }

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

@@ -0,0 +1,182 @@
+/**
+ * rpc DataChannel 发送流控队列
+ *
+ * 针对 plugin 侧 rpc DC 的应用层流控：与 UI 侧 `webrtc-connection.js` 语义对齐，
+ * 但因插件运行在 gateway 进程内，必须对队列大小设硬/软上限，避免 OOM。
+ *
+ * 使用方式：每条 rpc DC 一个实例，绑定到 session.rpcSendQueue。
+ * - send(jsonStr)：同步入口，fire-and-forget；返回 accepted/dropped
+ * - onBufferedAmountLow()：由 DC `bufferedamountlow` 事件转调，触发 drain
+ * - close()：DC 关闭时调用，清空队列并汇总 drop 统计
+ *
+ * 不做：Promise 送达保证；单条消息硬上限内的背压；自动重试。
+ */
+
+import { buildChunks } from './dc-chunking.js';
+import { remoteLog } from '../remote-log.js';
+
+/** 高水位：`dc.bufferedAmount >= HIGH` 时暂停 fast-path / drain */
+export const DC_HIGH_WATER_MARK = 1024 * 1024;       // 1 MB
+/** 低水位：设置 `dc.bufferedAmountLowThreshold`，触发 `bufferedamountlow` 事件 */
+export const DC_LOW_WATER_MARK = 256 * 1024;         // 256 KB
+/** 应用层队列软上限：`queueBytes >= MAX_QUEUE_BYTES` 时新消息被 drop */
+export const MAX_QUEUE_BYTES = 10 * 1024 * 1024;     // 10 MB
+/** 单条消息硬上限（对齐 dc-chunking.js MAX_REASSEMBLY_BYTES，接收端重组不了也无意义） */
+export const MAX_SINGLE_MSG_BYTES = 50 * 1024 * 1024; // 50 MB
+
+export class RpcSendQueue {
+	/**
+	 * @param {object} opts
+	 * @param {object} opts.dc - DataChannel 实例（需支持 send / bufferedAmount / readyState）
+	 * @param {number} opts.maxMessageSize - 对端 SDP 声明的 a=max-message-size
+	 * @param {() => number} opts.getNextMsgId - 分片 msgId 生成器
+	 * @param {object} [opts.logger] - pino 风格 logger
+	 * @param {string} [opts.tag] - 诊断 tag（通常是 connId）
+	 */
+	constructor({ dc, maxMessageSize, getNextMsgId, logger, tag }) {
+		if (!dc) throw new Error('RpcSendQueue: dc is required');
+		this.dc = dc;
+		this.maxMessageSize = maxMessageSize;
+		this.getNextMsgId = getNextMsgId;
+		this.logger = logger ?? console;
+		this.tag = tag ?? '';
+
+		/** @type {Buffer[]} chunks 或 Buffer 化的 string 消息 */
+		this.queue = [];
+		this.queueBytes = 0;
+		this.closed = false;
+
+		// drop 统计（累计到 close 时汇总）
+		this.droppedCount = 0;
+		this.droppedBytes = 0;
+		// 队列"满"状态：仅 queue-full drop 触发 true；drain 下降到 < MAX 翻回 false
+		// single-msg-oversize drop 不影响此状态（它是应用 bug 性质，不代表队列压力）
+		this.queueOverflowActive = false;
+	}
+
+	/**
+	 * 同步发送一条 JSON 字符串。
+	 * @param {string} jsonStr
+	 * @returns {boolean} true=accepted（至少已入队或已直发），false=dropped
+	 */
+	send(jsonStr) {
+		if (this.closed || this.dc.readyState !== 'open') return false;
+
+		const chunks = buildChunks(jsonStr, this.maxMessageSize, this.getNextMsgId);
+		const totalBytes = chunks
+			? chunks.reduce((n, c) => n + c.length, 0)
+			: Buffer.byteLength(jsonStr, 'utf8');
+
+		// 硬上限：单条超限
+		if (totalBytes > MAX_SINGLE_MSG_BYTES) {
+			this.droppedCount += 1;
+			this.droppedBytes += totalBytes;
+			this.logger.warn?.(`[rpc-queue${this.__tagSuffix()}] drop reason=single-msg-oversize size=${totalBytes} cap=${MAX_SINGLE_MSG_BYTES}`);
+			return false;
+		}
+
+		// 软上限：队列已积压到 MAX（允许之前单条溢出，但新消息从此开始拒绝）
+		if (this.queueBytes >= MAX_QUEUE_BYTES) {
+			this.droppedCount += 1;
+			this.droppedBytes += totalBytes;
+			this.logger.warn?.(`[rpc-queue${this.__tagSuffix()}] drop reason=queue-full size=${totalBytes} queueBytes=${this.queueBytes}`);
+			if (!this.queueOverflowActive) {
+				this.queueOverflowActive = true;
+				remoteLog(`rpc-queue.overflow-start${this.__tagSuffix()} queueBytes=${this.queueBytes}`);
+			}
+			return false;
+		}
+
+		// 不分片：单条 string 或 Buffer 直接处理
+		if (!chunks) {
+			if (this.queue.length === 0
+				&& this.dc.readyState === 'open'
+				&& this.dc.bufferedAmount < DC_HIGH_WATER_MARK) {
+				try {
+					this.dc.send(jsonStr);
+					return true;
+				} catch (err) {
+					this.logger.warn?.(`[rpc-queue${this.__tagSuffix()}] fast-path send failed: ${err?.message}`);
+					return false;
+				}
+			}
+			const buf = Buffer.from(jsonStr, 'utf8');
+			this.queue.push(buf);
+			this.queueBytes += buf.length;
+			return true;
+		}
+
+		// 分片：fast-path 尝试同步直发尽可能多的 chunk
+		// 循环条件与 __drain 一致：DC 仍 open 且 bufferedAmount 未顶到 HIGH
+		let i = 0;
+		if (this.queue.length === 0) {
+			while (i < chunks.length
+				&& this.dc.readyState === 'open'
+				&& this.dc.bufferedAmount < DC_HIGH_WATER_MARK) {
+				try {
+					this.dc.send(chunks[i]);
+					i += 1;
+				} catch (err) {
+					this.logger.warn?.(`[rpc-queue${this.__tagSuffix()}] fast-path send failed at chunk ${i}/${chunks.length}: ${err?.message}`);
+					return false;
+				}
+			}
+		}
+		// 剩余 chunk 原子性入队（保证同一消息分片连续，不被其他消息插入）
+		for (; i < chunks.length; i += 1) {
+			this.queue.push(chunks[i]);
+			this.queueBytes += chunks[i].length;
+		}
+		return true;
+	}
+
+	/** 由外部 `dc.onbufferedamountlow` 事件触发 */
+	onBufferedAmountLow() {
+		this.__drain();
+	}
+
+	/**
+	 * 关闭队列：清空待发送 chunks，汇总并 remoteLog drop 统计。幂等。
+	 */
+	close() {
+		if (this.closed) return;
+		this.closed = true;
+		const residual = this.queue.length;
+		const residualBytes = this.queueBytes;
+		this.queue.length = 0;
+		this.queueBytes = 0;
+		this.queueOverflowActive = false;
+		if (this.droppedCount > 0 || residual > 0) {
+			remoteLog(`rpc-queue.close${this.__tagSuffix()} dropped=${this.droppedCount} droppedBytes=${this.droppedBytes} residualChunks=${residual} residualBytes=${residualBytes}`);
+		}
+	}
+
+	/** @private 排队持续发送直至 HIGH 水位或队列空 */
+	__drain() {
+		if (this.closed) return;
+		const dc = this.dc;
+		while (this.queue.length > 0
+			&& dc.readyState === 'open'
+			&& dc.bufferedAmount < DC_HIGH_WATER_MARK) {
+			const chunk = this.queue[0];
+			try {
+				dc.send(chunk);
+			} catch (err) {
+				this.logger.warn?.(`[rpc-queue${this.__tagSuffix()}] drain send failed: ${err?.message}`);
+				return; // 保留队列，等 onclose 统一清理
+			}
+			this.queue.shift();
+			this.queueBytes -= chunk.length;
+			// 满 → 未满 状态转换
+			if (this.queueOverflowActive && this.queueBytes < MAX_QUEUE_BYTES) {
+				this.queueOverflowActive = false;
+				remoteLog(`rpc-queue.overflow-end${this.__tagSuffix()} dropped=${this.droppedCount} droppedBytes=${this.droppedBytes}`);
+			}
+		}
+	}
+
+	/** @private */
+	__tagSuffix() {
+		return this.tag ? ` ${this.tag}` : '';
+	}
+}

package/src/webrtc/webrtc-peer.js

@@ -1,10 +1,19 @@
-import { chunkAndSend, createReassembler } from './dc-chunking.js';
+import { createReassembler } from './dc-chunking.js';
+import { RpcSendQueue, DC_LOW_WATER_MARK } from './rpc-send-queue.js';
 import { remoteLog } from '../remote-log.js';
 
 // 单个 session 内 file DC 历史快照的容量上限（满后按 FIFO 淘汰最老条目）。
 // 用于诊断 dump：过大会撑爆 remoteLog 单帧，20 足以覆盖典型多文件传输会话。
 const FILE_CHANNEL_HISTORY_LIMIT = 20;
 
+// Failed session 保留 24 小时，支持 Capacitor 长时间后台恢复后 ICE restart。
+// 超时后 session 被回收释放 IPC listeners 和 Go 侧资源。
+const FAILED_SESSION_TTL_MS = 24 * 60 * 60 * 1000;
+
+// Session 总数上限（活跃 + failed）。溢出时淘汰最旧的 failed session。
+// 20 足以覆盖多 UI 实例（浏览器多标签 + 移动端）的典型场景。
+const MAX_SESSIONS = 20;
+
 /**
  * 管理多个 WebRTC PeerConnection（以 connId 为粒度）。
  * Plugin 作为被叫方：收到 UI 的 offer → 回复 answer。
@@ -32,7 +41,7 @@ export class WebRtcPeer {
 		this.__PeerConnection = PeerConnection;
 		this.__impl = impl ?? null;
 		this.__rtcTag = impl ? `[coclaw/rtc:${impl}]` : '[coclaw/rtc]';
-		/** @type {Map<string, { pc: object, rpcChannel: object|null, remoteMaxMessageSize: number, nextMsgId: number }>} */
+		/** @type {Map<string, { pc: object, rpcChannel: object|null, rpcSendQueue: RpcSendQueue|null, fileChannels: Set, remoteMaxMessageSize: number, nextMsgId: number }>} */
 		this.__sessions = new Map();
 	}
 
@@ -55,7 +64,19 @@ export class WebRtcPeer {
 	async closeByConnId(connId) {
 		const session = this.__sessions.get(connId);
 		if (!session) return;
+		// 清理 failed TTL 定时器
+		if (session.__failedTimer) {
+			clearTimeout(session.__failedTimer);
+			session.__failedTimer = null;
+		}
 		this.__sessions.delete(connId);
+		// 显式关闭 rpc 发送队列：dc.onclose 路径中 `sessions.get(connId)` 已返回 undefined 而短路，
+		// 此处不主动 close 会丢失 drop 汇总 remoteLog 诊断
+		if (session.rpcSendQueue) {
+			session.rpcSendQueue.close();
+			session.rpcSendQueue = null;
+			session.rpcChannel = null;
+		}
 		// 先 detach 事件，防止 pc.close() 异步触发 onconnectionstatechange 删除新 session
 		session.pc.onconnectionstatechange = null;
 		session.pc.onicecandidate = null;
@@ -73,15 +94,16 @@ export class WebRtcPeer {
 		await Promise.all(closing);
 	}
 
-	/** 向所有已打开的 rpcChannel 广播（大消息自动分片） */
+	/** 向所有已打开的 rpcChannel 广播（大消息自动分片，经由 RpcSendQueue 流控） */
 	broadcast(payload) {
 		const jsonStr = JSON.stringify(payload);
 		for (const [connId, session] of this.__sessions) {
-			const dc = session.rpcChannel;
-			if (dc?.readyState === 'open') {
+			const q = session.rpcSendQueue;
+			if (q && session.rpcChannel?.readyState === 'open') {
 				try {
-					chunkAndSend(dc, jsonStr, session.remoteMaxMessageSize, () => session.nextMsgId++, this.logger);
+					q.send(jsonStr);
 				} catch (err) {
+					// buildChunks 抛（maxMessageSize 配置错）等罕见情况
 					this.__logDebug(`[${connId}] broadcast send failed: ${err.message}`);
 				}
 			}
@@ -105,12 +127,24 @@ export class WebRtcPeer {
 						toConnId: connId,
 						payload: { reason: 'impl_unsupported' },
 					});
-					return;
+					return; // TTL timer 保持不变（reject 是同步的，不影响 timer 正常工作）
+				}
+				// 暂停 failed TTL timer：pion restart 涉及异步协商，期间不应被回收
+				if (existing.__failedTimer) {
+					clearTimeout(existing.__failedTimer);
+					existing.__failedTimer = null;
 				}
 				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 });
+					// 重协商 SDP 可能变更 a=max-message-size，同步刷新 queue 分片阈值；
+					// queue 中已入队的 chunks 按旧值分片保留，新消息用新值
+					const newMMS = this.__resolveMaxMessageSize(existing.pc, msg.payload.sdp);
+					if (newMMS !== existing.remoteMaxMessageSize) {
+						existing.remoteMaxMessageSize = newMMS;
+						if (existing.rpcSendQueue) existing.rpcSendQueue.maxMessageSize = newMMS;
+					}
 					const answer = await existing.pc.createAnswer();
 					await existing.pc.setLocalDescription(answer);
 					this.__onSend({
@@ -155,6 +189,11 @@ export class WebRtcPeer {
 			await this.closeByConnId(connId);
 		}
 
+		// session 总数限制：溢出时淘汰最旧的 failed session
+		if (this.__sessions.size >= MAX_SESSIONS) {
+			this.__evictOldestFailed();
+		}
+
 		// 从 Server 注入的 turnCreds 构建 iceServers
 		// werift 的 urls 必须是单个 string，每个 URL 独立一个对象
 		const iceServers = [];
@@ -177,15 +216,9 @@ export class WebRtcPeer {
 
 		const pc = new this.__PeerConnection({ iceServers });
 
-		// 分片阈值 = 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 remoteMMS = mmsMatch ? parseInt(mmsMatch[1], 10) : 65536;
-		const localMMS = pc.maxMessageSize ?? remoteMMS;
-		const remoteMaxMessageSize = Math.min(remoteMMS, localMMS);
+		const remoteMaxMessageSize = this.__resolveMaxMessageSize(pc, msg.payload.sdp);
 
-		const session = { pc, rpcChannel: null, fileChannels: new Set(), remoteMaxMessageSize, nextMsgId: 1 };
+		const session = { pc, rpcChannel: null, rpcSendQueue: null, fileChannels: new Set(), remoteMaxMessageSize, nextMsgId: 1 };
 		this.__sessions.set(connId, session);
 
 		// ICE candidate → 发给 UI，并统计各类型 candidate 数量
@@ -222,6 +255,12 @@ export class WebRtcPeer {
 			const cur = this.__sessions.get(connId);
 			if (!cur || cur.pc !== pc) return;
 
+			// 离开 failed 状态时清理 TTL timer（ICE restart 恢复、自然关闭等）
+			if (state !== 'failed' && cur.__failedTimer) {
+				clearTimeout(cur.__failedTimer);
+				cur.__failedTimer = null;
+			}
+
 			if (state === 'connected') {
 				// 重置 dump 去重水位（disconnected → connected → disconnected 仍能再 dump）
 				cur.__lastDumpState = null;
@@ -238,16 +277,25 @@ export class WebRtcPeer {
 				// pion: pair 通过独立的 selectedcandidatepairchange 事件上报
 			} else if (state === 'disconnected' || state === 'failed' || state === 'closed') {
 				// 诊断 dump：失败/断连/关闭时输出当前 PC 上 DC 状态，定位"PC 假活/DC 死"现象
-				// - closed 多由本地主动关闭触发，dump 收敛诊断噪声但仍清理 session
+				// - closed 由 closeByConnId 接管清理，dump 收敛诊断噪声
 				// - disconnected 可能反复触发，去重避免噪声
 				if (state !== 'closed' && cur.__lastDumpState !== state) {
 					cur.__lastDumpState = state;
 					this.__dumpSessionState(connId, cur, state);
 				}
-				// 仅 closed 删除 session；failed 保留以支持 ICE restart 恢复
-				// （如 app 后台冻结 → pion ICE failed → 前台恢复后 restart）
-				if (state === 'closed') {
-					this.__sessions.delete(connId);
+				if (state === 'failed') {
+					// 启动 TTL 定时器：超时后回收 session 释放 IPC listeners 和 Go 侧资源。
+					// unref() 确保定时器不阻止进程退出（gateway 由其他连接保活）。
+					if (cur.__failedTimer) clearTimeout(cur.__failedTimer);
+					cur.__failedTimer = setTimeout(() => {
+						this.__remoteLog(`rtc.session-expired conn=${connId} ttl=${FAILED_SESSION_TTL_MS / 1000}s`);
+						this.logger.info?.(`${this.__rtcTag} [${connId}] session TTL expired, closing`);
+						this.closeByConnId(connId).catch(() => {});
+					}, FAILED_SESSION_TTL_MS);
+					cur.__failedTimer.unref?.();
+				} else if (state === 'closed') {
+					// 自然进入 closed 时也需通过 closeByConnId 释放 IPC listeners 和 Go 资源
+					this.closeByConnId(connId).catch(() => {});
 				}
 			}
 		};
@@ -298,6 +346,10 @@ export class WebRtcPeer {
 			// SDP 协商失败 → 清理已入 Map 的 session，避免泄漏
 			const cur = this.__sessions.get(connId);
 			if (cur && cur.pc === pc) {
+				if (cur.__failedTimer) {
+					clearTimeout(cur.__failedTimer);
+					cur.__failedTimer = null;
+				}
 				this.__sessions.delete(connId);
 			}
 			await pc.close().catch(() => {});
@@ -321,9 +373,29 @@ export class WebRtcPeer {
 	}
 
 	__setupDataChannel(connId, dc) {
+		// rpc DC 发送流控：每条 rpc DC 绑定一个 RpcSendQueue，广播与 files RPC 响应均经此出口
+		const session = this.__sessions.get(connId);
+		if (session && dc.label === 'rpc') {
+			if ('bufferedAmountLowThreshold' in dc) {
+				dc.bufferedAmountLowThreshold = DC_LOW_WATER_MARK;
+			}
+			session.rpcSendQueue = new RpcSendQueue({
+				dc,
+				maxMessageSize: session.remoteMaxMessageSize,
+				getNextMsgId: () => session.nextMsgId++,
+				logger: this.logger,
+				tag: `conn=${connId}`,
+			});
+			dc.onbufferedamountlow = () => {
+				session.rpcSendQueue?.onBufferedAmountLow();
+			};
+		}
+
 		const reassembler = createReassembler((jsonStr) => {
 			const payload = JSON.parse(jsonStr);
 			// DC 探测：立即回复，不走 gateway
+			// 故意绕过 RpcSendQueue：probe-ack 仅用于测量传输层（SCTP/DTLS）健康，
+			// 走 queue 会把应用层积压压力错误地映射到"DC 不通"上。
 			if (payload.type === 'probe') {
 				try { dc.send(JSON.stringify({ type: 'probe-ack' })); }
 				catch { /* DC 已关闭，忽略 */ }
@@ -332,15 +404,10 @@ export class WebRtcPeer {
 			if (payload.type === 'req') {
 				// coclaw.files.* 方法本地处理，不转发 gateway
 				if (payload.method?.startsWith('coclaw.files.') && this.__onFileRpc) {
-					const session = this.__sessions.get(connId);
+					const sess = this.__sessions.get(connId);
 					const sendFn = (response) => {
 						try {
-							chunkAndSend(
-								dc, JSON.stringify(response),
-								session?.remoteMaxMessageSize ?? 65536,
-								() => session.nextMsgId++,
-								this.logger,
-							);
+							sess?.rpcSendQueue?.send(JSON.stringify(response));
 						} catch (err) {
 							this.__logDebug(`[${connId}] sendFn failed: ${err.message}`);
 						}
@@ -362,8 +429,12 @@ export class WebRtcPeer {
 			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;
+			const sess = this.__sessions.get(connId);
+			if (sess && dc.label === 'rpc') {
+				sess.rpcSendQueue?.close();
+				sess.rpcSendQueue = null;
+				sess.rpcChannel = null;
+			}
 		};
 		dc.onerror = (err) => {
 			this.__remoteLog(`dc.error conn=${connId} label=${dc.label}`);
@@ -389,8 +460,24 @@ export class WebRtcPeer {
 			? '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}`);
+		const q = session.rpcSendQueue;
+		const queueInfo = q
+			? `queueLen=${q.queue.length} queueBytes=${q.queueBytes} dropped=${q.droppedCount}`
+			: 'queue=none';
+		this.__remoteLog(`rtc.dump conn=${connId} state=${state} sessions=${this.__sessions.size} rpc=${rpcState} ${queueInfo} fileCount=${session.fileChannels.size} files=[${fileSummary}]`);
+		this.logger.info?.(`${this.__rtcTag} [${connId}] dump state=${state} rpc=${rpcState} ${queueInfo} fileCount=${session.fileChannels.size} files=${fileSummary}`);
+	}
+
+	/**
+	 * 分片阈值 = min(远端能接收, 本地能发送)
+	 * 远端：从 SDP 的 a=max-message-size 解析（缺失则 RFC 8841 默认 65536）
+	 * 本地：pc.maxMessageSize（pion 为 65536，ndc/werift 无此属性则不限制）
+	 */
+	__resolveMaxMessageSize(pc, sdp) {
+		const mmsMatch = sdp?.match(/a=max-message-size:(\d+)/);
+		const remoteMMS = mmsMatch ? parseInt(mmsMatch[1], 10) : 65536;
+		const localMMS = pc.maxMessageSize ?? remoteMMS;
+		return Math.min(remoteMMS, localMMS);
 	}
 
 	__logNominatedPair(connId, pair) {
@@ -404,9 +491,25 @@ export class WebRtcPeer {
 		remoteLog(this.__impl ? `${msg} rtc=${this.__impl}` : msg);
 	}
 
+	/** 淘汰最旧的 failed session（Map 迭代序 ≈ 创建时间序），用于 queue length 限制 */
+	__evictOldestFailed() {
+		for (const [connId, session] of this.__sessions) {
+			if (session.pc.connectionState === 'failed') {
+				this.__remoteLog(`rtc.session-evicted conn=${connId} sessions=${this.__sessions.size}`);
+				this.logger.info?.(`${this.__rtcTag} [${connId}] session evicted (limit ${MAX_SESSIONS}), closing`);
+				this.closeByConnId(connId).catch(() => {});
+				return true;
+			}
+		}
+		this.logger.warn?.(`${this.__rtcTag} session limit (${MAX_SESSIONS}) reached, no failed sessions to evict`);
+		return false;
+	}
+
 	__logDebug(message) {
 		if (typeof this.logger?.debug === 'function') {
 			this.logger.debug(`${this.__rtcTag} ${message}`);
 		}
 	}
 }
+
+export { FAILED_SESSION_TTL_MS, MAX_SESSIONS };