@coclaw/openclaw-coclaw 0.21.3 → 0.21.5

package/README.md

@@ -92,7 +92,7 @@ pnpm run release:versions                  # 显示所有已发布版本
 | `coclaw.files.delete` | 删除工作区文件/目录 |
 | `coclaw.files.mkdir` | 创建工作区目录 |
 | `coclaw.files.create` | 创建空文件 |
-| `nativeui.sessions.listAll` | 列出所有 session（分页 + 标题推导） |
+| `nativeui.sessions.listAll` | 列出所有 session（分页） |
 | `nativeui.sessions.get` | 获取 session 原始 JSONL 行（分页） |
 
 ## Gateway Services

package/index.js

@@ -363,21 +363,21 @@ const plugin = {
 				// best-effort ensure：失败不阻断 listAll
 				try { await ensureAgentSession(agentId); }
 				catch {}
-				respond(true, manager.listAll(params ?? {}));
+				respond(true, await manager.listAll(params ?? {}));
 			}
 			catch (err) {
 				respondError(respond, err);
 			}
 		});
 
-		api.registerGatewayMethod('nativeui.sessions.get', ({ params, respond }) => {
+		api.registerGatewayMethod('nativeui.sessions.get', async ({ params, respond }) => {
 			try {
 				const sessionId = params?.sessionId;
 				if (typeof sessionId !== 'string' || sessionId.trim().length === 0) {
 					respondInvalid(respond, 'sessionId required');
 					return;
 				}
-				respond(true, manager.get(params ?? {}));
+				respond(true, await manager.get(params ?? {}));
 			}
 			catch (err) {
 				respondError(respond, err);
@@ -474,7 +474,7 @@ const plugin = {
 			}
 		});
 
-		api.registerGatewayMethod('coclaw.topics.getHistory', ({ params, respond }) => {
+		api.registerGatewayMethod('coclaw.topics.getHistory', async ({ params, respond }) => {
 			try {
 				const topicId = params?.topicId?.trim?.();
 				if (!topicId) {
@@ -483,7 +483,7 @@ const plugin = {
 				}
 				const agentId = params?.agentId?.trim?.() || 'main';
 				// 直接复用 session-manager 的 get()，topicId 即 sessionId
-				respond(true, manager.get({ agentId, sessionId: topicId }));
+				respond(true, await manager.get({ agentId, sessionId: topicId }));
 			}
 			catch (err) {
 				respondError(respond, err);
@@ -577,7 +577,7 @@ const plugin = {
 		});
 
 		// TODO: coclaw.topics.getHistory 未来可废弃，UI 改用 coclaw.sessions.getById
-		api.registerGatewayMethod('coclaw.sessions.getById', ({ params, respond }) => {
+		api.registerGatewayMethod('coclaw.sessions.getById', async ({ params, respond }) => {
 			try {
 				const sessionId = params?.sessionId?.trim?.();
 				if (!sessionId) {
@@ -586,7 +586,7 @@ const plugin = {
 				}
 				const agentId = params?.agentId?.trim?.() || 'main';
 				const limit = params?.limit;
-				respond(true, manager.getById({ agentId, sessionId, limit }));
+				respond(true, await manager.getById({ agentId, sessionId, limit }));
 			}
 			catch (err) {
 				respondError(respond, err);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coclaw/openclaw-coclaw",
-  "version": "0.21.3",
+  "version": "0.21.5",
   "type": "module",
   "license": "Apache-2.0",
   "description": "OpenClaw CoClaw channel plugin for remote chat. Run `openclaw coclaw enroll` after install to connect to CoClaw.",

package/src/auto-upgrade/updater.js

@@ -131,6 +131,14 @@ export async function writeUpgradeLock(pid) {
  * `upgrade.ledger-read-failed` / `upgrade.ledger-parse-failed`），避免运维只
  * 看到 start() 那条 "Skipping: not an npm-installed plugin" 时误判方向。
  *
+ * 注：内部 `readFileSync` 为同步 IO，**有意保留**——只在升级周期决策时读一次
+ * 账本（整个进程生命周期通常一锤子）。改 async 必须沿 `shouldSkipAutoUpgrade`
+ * 等调用链向上传播，收益不抵成本。
+ *
+ * 另：OpenClaw plugin SDK 当前未暴露查询 installRecords 的 API，只能直接读
+ * `<state-dir>/plugins/installs.json`（与上游 `manifest-metadata-scan` 等
+ * 内部模块同源做法）。如果上游后续开放官方接口，可切换并删除直读分支。
+ *
  * @param {string} pluginId
  * @returns {object|null}
  */

package/src/device-identity.js

@@ -77,6 +77,13 @@ function generateIdentity() {
  * 加载或创建设备身份（Ed25519 密钥对）
  *
  * 存储格式与 OpenClaw device-identity.ts 保持一致。
+ *
+ * 注：本函数及内部 `fs.existsSync` / `readFileSync` / `generateKeyPairSync` /
+ * `atomicWriteFileSync` 均为同步 IO，**有意保留**——本路径只在 plugin↔本机
+ * gateway 首次握手时命中一次（后续走 realtime-bridge 的内存缓存），属于"启动期
+ * 一锤子"。改 async 必须把握手链路也 async 化，复杂度全长在握手那条线上，收益
+ * 不抵成本。重新评估前请先确认调用频率确实发生了变化。
+ *
  * @param {string} [filePath] - 自定义路径，默认 <state-dir>/coclaw/device-identity.json
  * @returns {{ deviceId: string, publicKeyPem: string, privateKeyPem: string }}
  */

package/src/realtime-bridge.js

@@ -768,9 +768,13 @@ export class RealtimeBridge {
 				if (this.gatewayWs !== ws) {
 					return;
 				}
+				// rawData 保留供转发链路（res 单播 / agent event 单播 / 兜底广播）透传：
+				// 跳过 webrtcPeer.broadcast/sendTo 内部的重新 stringify，省掉对大 payload
+				// （如 agent.run.event 含大 tool_result）的重复序列化主线程阻塞。
+				const rawData = String(event.data ?? '{}');
 				let payload = null;
 				try {
-					payload = JSON.parse(String(event.data ?? '{}'));
+					payload = JSON.parse(rawData);
 				}
 				catch {
 					return;
@@ -892,7 +896,9 @@ export class RealtimeBridge {
 							/* c8 ignore next -- TODO: 2026-05-20 后删除 */
 							this.logger.debug?.(`[coclaw/rpc-res-route] hit, reqId=${payload.id} → connId=${info.connId}`);
 							// sendTo 阶段 1 改为 async（admission 决策 await）；外层 listener 已是 async
-							const delivered = await this.webrtcPeer?.sendTo(info.connId, payload);
+							// 透传 rawData 跳过重新 stringify：gateway → plugin → DC 转发链路上的大 payload
+							// （如 agent.run.event 含大 tool_result）省掉一次主线程序列化阻塞。
+							const delivered = await this.webrtcPeer?.sendTo(info.connId, payload, rawData);
 							if (!delivered) {
 							// PC 已断 / DC 未 open / 队列拒收：本地 log 丢弃，不退回广播
 								this.__logDebug(
@@ -913,7 +919,8 @@ export class RealtimeBridge {
 								/* c8 ignore next -- TODO: 2026-05-20 后删除 */
 								this.logger.debug?.(`[coclaw/run-event-route] hit, runId=${runId} → connId=${connId}`);
 								// sendTo 失败不打 log（PC 状态翻转日志已足够，drop 是正确语义）
-								await this.webrtcPeer?.sendTo(connId, payload);
+								// 透传 rawData 跳过重新 stringify：agent event payload 可能很大（如 tool_result）
+								await this.webrtcPeer?.sendTo(connId, payload, rawData);
 								return;
 							}
 						}
@@ -921,7 +928,8 @@ export class RealtimeBridge {
 						this.logger.debug?.(`[coclaw/run-event-route] miss, broadcast, runId=${runId ?? '<missing>'}`);
 					}
 					// (d) 兜底广播：覆盖 event 类型 / 映射未命中场景
-					this.webrtcPeer?.broadcast(payload);
+					// 透传 rawData 跳过重新 stringify：agent event 兜底广播同样可能很大
+					this.webrtcPeer?.broadcast(payload, rawData);
 				}
 			})().catch((err) => {
 				this.logger.warn?.(`[coclaw] gateway ws message handler error: ${err?.message ?? err}`);
@@ -1310,8 +1318,14 @@ export class RealtimeBridge {
 						await this.__webrtcPeerReady;
 						await this.webrtcPeer.handleSignaling(payload);
 					} catch (err) {
-						this.logger.warn?.(`[coclaw/rtc] signaling error (or werift not found): ${err?.message}`);
-						remoteLog(`rtc.signaling-error msg=${err?.message}`);
+						// 现在 handleSignaling 内 drain 自己 catch + 转 rtc.signaling-error remoteLog 不
+						// 抛出，这层 catch 只会兜到 __initWebrtcPeer() 失败（peer 未就绪）。type/conn
+						// 字段保留是为了 server 端日志区分发生位置——init 路径下 type/conn 仍来自当前
+						// 信令消息，与 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}`);
+						remoteLog(`rtc.signaling-error type=${sigType} conn=${sigConn} msg=${err?.message}`);
 					}
 					return;
 				}

package/src/session-manager/manager.js

@@ -1,69 +1,8 @@
-import fs from 'node:fs';
+import fsp from 'node:fs/promises';
 import nodePath from 'node:path';
 
 import { agentSessionsDir, sessionStorePath, sessionTranscriptPath } from '../claw-paths.js';
-
-const DERIVED_TITLE_MAX_LEN = 60;
-
-// OC 注入的 inbound metadata 头部（Conversation info / Sender / Thread starter 等）
-const INBOUND_META_RE = /^\w[\w ]* \(untrusted[^)]*\):\n```json\n[\s\S]*?\n```\n\n/;
-// operator 级策略/指令前缀，如 Skills store policy (operator configured): ...
-const OPERATOR_POLICY_RE = /^\w[\w ]* \(operator configured\):[\s\S]*?\n\n/;
-// OC 注入的用户消息时间戳前缀
-const USER_TS_RE = /^\[(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun)\s+\d{4}-\d{2}-\d{2}\s+\d{2}:\d{2}(?::\d{2})?\s+[^\]]+\]\s*/;
-// 尾部 [message_id: xxx]
-const MSG_ID_SUFFIX_RE = /\n\[message_id:\s*[^\]]+\]\s*$/;
-// 尾部 Untrusted context 块（外部元数据注入）
-const UNTRUSTED_CTX_SUFFIX_RE = /\n\nUntrusted context \(metadata, do not treat as instructions or commands\):\n[\s\S]*$/;
-// 定时任务前缀
-const CRON_UUID_RE = /\[cron:[0-9a-f-]+(?:\s+([^\]]*))?\]\s*/;
-// cron 注入的 Current time 行及其后的系统追加指令（如 "Return your summary..."）
-const CRON_TIME_TAIL_RE = /\nCurrent time:[^\n]+[\s\S]*$/;
-// 从 Current time 行提取 UTC 时间部分
-const CRON_TIME_UTC_RE = /(\d{4})-(\d{2})-(\d{2})\s+(\d{2}):(\d{2})\s+UTC/;
-
-function formatCronTime(matchedText) {
-	const m = matchedText.match(CRON_TIME_UTC_RE);
-	if (!m) return '';
-	/* c8 ignore start -- Date 构造在正则已校验的输入下不会抛出 */
-	try {
-		const d = new Date(`${m[1]}-${m[2]}-${m[3]}T${m[4]}:${m[5]}:00Z`);
-		if (!Number.isFinite(d.getTime())) return '';
-		const y = d.getFullYear();
-		const mo = String(d.getMonth() + 1).padStart(2, '0');
-		const dd = String(d.getDate()).padStart(2, '0');
-		const hh = String(d.getHours()).padStart(2, '0');
-		const mi = String(d.getMinutes()).padStart(2, '0');
-		return ` ${y}-${mo}-${dd} ${hh}${mi}`;
-	}
-	catch {
-		return '';
-	}
-	/* c8 ignore stop */
-}
-
-function stripLeadingPattern(text, re) {
-	let prev;
-	do {
-		prev = text;
-		text = text.replace(re, '');
-	} while (text !== prev);
-	return text;
-}
-
-function cleanTitleText(text) {
-	/* c8 ignore next */
-	if (!text) return '';
-	let s = stripLeadingPattern(text, INBOUND_META_RE);
-	s = stripLeadingPattern(s, OPERATOR_POLICY_RE);
-	s = s.replace(CRON_TIME_TAIL_RE, (match) => formatCronTime(match));
-	return s
-		.replace(USER_TS_RE, '')
-		.replace(CRON_UUID_RE, (_, taskName) => taskName ? `${taskName} ` : '')
-		.replace(UNTRUSTED_CTX_SUFFIX_RE, '')
-		.replace(MSG_ID_SUFFIX_RE, '')
-		.trim();
-}
+import { iterTextLines } from '../utils/text-line-stream.js';
 
 function toNum(value, fallback) {
 	const n = Number(value);
@@ -77,15 +16,36 @@ function clamp(value, min, max, fallback) {
 	return n;
 }
 
-function readJsonSafe(filePath, fallback) {
+async function readJsonSafe(filePath, fallback) {
 	try {
-		return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+		const text = await fsp.readFile(filePath, 'utf8');
+		return JSON.parse(text);
 	}
 	catch {
 		return fallback;
 	}
 }
 
+// readdir 与后续 stat 之间存在天然 race window（文件被并发删除/reset 归档）。
+// 统一把 ENOENT/ENOTDIR 视为"目录消失即空目录"，其它错误（如 EACCES）按原样上抛。
+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;
+	}
+}
+
+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;
+	}
+}
+
 function parseSessionFileName(fileName) {
 	if (typeof fileName !== 'string' || !fileName.includes('.jsonl')) return null;
 	if (fileName.includes('.jsonl.delete.') || fileName.includes('.jsonl.deleted.')) return null;
@@ -118,60 +78,6 @@ function shouldReplaceByPriority(current, next) {
 	return next.updatedAt > current.updatedAt;
 }
 
-function truncateTitle(text, maxLen = DERIVED_TITLE_MAX_LEN) {
-	if (text.length <= maxLen) return text;
-	const cut = text.slice(0, maxLen - 1);
-	const lastSpace = cut.lastIndexOf(' ');
-	if (lastSpace > maxLen * 0.6) {
-		return `${cut.slice(0, lastSpace)}…`;
-	}
-	return `${cut}…`;
-}
-
-function extractRawTextFromContent(content) {
-	if (typeof content === 'string') return content;
-	/* c8 ignore next */
-	if (!Array.isArray(content)) return undefined;
-	for (const part of content) {
-		if (!part || typeof part !== 'object') continue;
-		if (part.type !== 'text') continue;
-		/* c8 ignore next */
-		if (typeof part.text !== 'string') continue;
-		if (part.text.trim()) return part.text;
-	}
-	return undefined;
-}
-
-function findFirstUserRawText(filePath, logger) {
-	const lines = fs.readFileSync(filePath, 'utf8').split(/\r?\n/);
-	for (const line of lines) {
-		if (!line) continue;
-		try {
-			const row = JSON.parse(line);
-			if (row?.type !== 'message') continue;
-			if (row?.message?.role !== 'user') continue;
-			const raw = extractRawTextFromContent(row?.message?.content);
-			if (raw && raw.trim()) return raw;
-		}
-		catch (err) {
-			/* c8 ignore next -- ?./?? fallback */
-			logger.warn?.(`[session-manager] bad json line skipped when deriving title: ${String(err?.message ?? err)}`);
-		}
-	}
-	return undefined;
-}
-
-function deriveTitle(filePath, logger) {
-	const rawText = findFirstUserRawText(filePath, logger);
-	if (!rawText) return undefined;
-	const cleaned = cleanTitleText(rawText);
-	if (!cleaned) return undefined;
-	const normalized = cleaned.replace(/\s+/g, ' ').trim();
-	/* c8 ignore next */
-	if (!normalized) return undefined;
-	return truncateTitle(normalized, DERIVED_TITLE_MAX_LEN);
-}
-
 export function createSessionManager(options = {}) {
 	/* c8 ignore next */
 	const logger = options.logger ?? console;
@@ -185,22 +91,22 @@ export function createSessionManager(options = {}) {
 		return resolveSessionsDir(aid);
 	}
 
-	function readIndex(agentId = 'main') {
+	async function readIndex(agentId = 'main') {
 		/* c8 ignore next */
 		const aid = typeof agentId === 'string' && agentId.trim() ? agentId.trim() : 'main';
 		const file = resolveStorePath(aid);
-		const data = readJsonSafe(file, {});
+		const data = await readJsonSafe(file, {});
 		/* c8 ignore next */
 		if (!data || typeof data !== 'object') return {};
 		return data;
 	}
 
-	function listAll(params = {}) {
+	async function listAll(params = {}) {
 		const agentId = typeof params.agentId === 'string' && params.agentId.trim() ? params.agentId.trim() : 'main';
 		const limit = clamp(params.limit, 1, 200, 50);
 		const cursor = clamp(params.cursor, 0, Number.MAX_SAFE_INTEGER, 0);
 		const dir = sessionsDir(agentId);
-		const index = readIndex(agentId);
+		const index = await readIndex(agentId);
 		const indexed = new Set(
 			Object.values(index)
 				.map((item) => item?.sessionId)
@@ -214,13 +120,20 @@ export function createSessionManager(options = {}) {
 			}
 		}
 
-		const files = fs.existsSync(dir) ? fs.readdirSync(dir) : [];
+		const files = await safeReaddir(dir);
 		const grouped = new Map();
 		for (const file of files) {
 			const parsed = parseSessionFileName(file);
 			if (!parsed?.sessionId) continue;
 			const full = nodePath.join(dir, file);
-			const stat = fs.statSync(full);
+			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,
@@ -256,20 +169,7 @@ export function createSessionManager(options = {}) {
 		const rows = Array.from(grouped.values());
 		rows.sort((a, b) => b.updatedAt - a.updatedAt);
 
-		const items = rows.slice(cursor, cursor + limit).map((row) => {
-			if (!row.fileName) {
-				return { ...row };
-			}
-			const transcriptPath = nodePath.join(dir, row.fileName);
-			const derivedTitle = deriveTitle(transcriptPath, logger);
-			if (!derivedTitle) {
-				return { ...row };
-			}
-			return {
-				...row,
-				derivedTitle,
-			};
-		});
+		const items = rows.slice(cursor, cursor + limit).map((row) => ({ ...row }));
 		const nextCursor = cursor + limit < rows.length ? String(cursor + limit) : null;
 		return {
 			agentId,
@@ -280,53 +180,74 @@ export function createSessionManager(options = {}) {
 		};
 	}
 
-	function resolveTranscriptFile(agentId, sessionId) {
+	async function resolveTranscriptFile(agentId, sessionId) {
 		const dir = sessionsDir(agentId);
 		// live 文件优先：同一 sessionId 可能同时存在 live 和 reset 文件
 		// （OpenClaw reset 后复用 sessionId），live 代表当前活跃 transcript
 		const livePath = resolveTranscriptPath(sessionId, agentId);
-		if (fs.existsSync(livePath)) {
-			return livePath;
-		}
-		const files = fs.existsSync(dir) ? fs.readdirSync(dir) : [];
+		if (await safeAccess(livePath)) return livePath;
+
+		const files = await safeReaddir(dir);
 		const resetPrefix = `${sessionId}.jsonl.reset.`;
-		const resetCandidates = files
-			.filter((name) => name.startsWith(resetPrefix))
-			.map((name) => {
-				const full = nodePath.join(dir, name);
-				const stat = fs.statSync(full);
-				return {
-					path: full,
-					archiveStamp: name.slice(resetPrefix.length),
-					updatedAt: stat.mtimeMs,
-				};
-			})
-			.sort((a, b) => {
-				if (a.archiveStamp !== b.archiveStamp) {
-					return b.archiveStamp.localeCompare(a.archiveStamp);
-				}
-				/* c8 ignore next -- 同一 sessionId 的 reset 文件不会有相同 archiveStamp */
-				return b.updatedAt - a.updatedAt;
+		const resetCandidates = [];
+		for (const name of files) {
+			if (!name.startsWith(resetPrefix)) continue;
+			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 */
+			resetCandidates.push({
+				path: full,
+				archiveStamp: name.slice(resetPrefix.length),
+				updatedAt: stat.mtimeMs,
 			});
+		}
+		resetCandidates.sort((a, b) => {
+			if (a.archiveStamp !== b.archiveStamp) {
+				return b.archiveStamp.localeCompare(a.archiveStamp);
+			}
+			/* c8 ignore next -- 同一 sessionId 的 reset 文件不会有相同 archiveStamp */
+			return b.updatedAt - a.updatedAt;
+		});
 		if (resetCandidates.length > 0) {
 			return resetCandidates[0].path;
 		}
 		return null;
 	}
 
-	function get(params = {}) {
+	// 读 transcript 全文；不存在视为空字符串。返回原始文本，由调用方走 iterTextLines
+	// 流式扫描 + 解析，避免大文件 split 一次性卡 event loop。
+	async function readTranscriptText(file) {
+		try {
+			return await fsp.readFile(file, 'utf8');
+		}
+		/* c8 ignore start -- resolveTranscriptFile→readFile race window */
+		catch (err) {
+			if (err.code === 'ENOENT') return '';
+			throw err;
+		}
+		/* c8 ignore stop */
+	}
+
+	async function get(params = {}) {
 		const agentId = typeof params.agentId === 'string' && params.agentId.trim() ? params.agentId.trim() : 'main';
 		const sessionId = typeof params.sessionId === 'string' ? params.sessionId.trim() : '';
 		if (!sessionId) throw new Error('sessionId required');
 		const limit = clamp(params.limit, 1, 500, 100);
 		const cursor = clamp(params.cursor, 0, Number.MAX_SAFE_INTEGER, 0);
-		const file = resolveTranscriptFile(agentId, sessionId);
+		const file = await resolveTranscriptFile(agentId, sessionId);
 		if (!file) {
 			return { agentId, sessionId, total: 0, cursor: String(cursor), nextCursor: null, messages: [] };
 		}
 
+		const text = await readTranscriptText(file);
 		const all = [];
-		for (const line of fs.readFileSync(file, 'utf8').split(/\r?\n/).filter(Boolean)) {
+		for await (const line of iterTextLines(text)) {
 			try {
 				all.push(JSON.parse(line));
 			}
@@ -352,20 +273,21 @@ export function createSessionManager(options = {}) {
 	 * 按 sessionId 获取消息，返回完整 JSONL 行级结构。
 	 * 只返回 type==="message" 且有合法 message.role 的行。
 	 * @param {{ sessionId: string, agentId?: string, limit?: number }} params
-	 * @returns {{ messages: object[] }}
+	 * @returns {Promise<{ messages: object[] }>}
 	 */
-	function getById(params = {}) {
+	async function getById(params = {}) {
 		const agentId = typeof params.agentId === 'string' && params.agentId.trim() ? params.agentId.trim() : 'main';
 		const sessionId = typeof params.sessionId === 'string' ? params.sessionId.trim() : '';
 		if (!sessionId) throw new Error('sessionId required');
 		const limit = clamp(params.limit, 1, 500, 500);
-		const file = resolveTranscriptFile(agentId, sessionId);
+		const file = await resolveTranscriptFile(agentId, sessionId);
 		if (!file) {
 			return { messages: [] };
 		}
 
+		const text = await readTranscriptText(file);
 		const messages = [];
-		for (const line of fs.readFileSync(file, 'utf8').split(/\r?\n/).filter(Boolean)) {
+		for await (const line of iterTextLines(text)) {
 			try {
 				const row = JSON.parse(line);
 				if (row?.type !== 'message') continue;

package/src/utils/text-line-stream.js

@@ -0,0 +1,60 @@
+export const DEFAULT_YIELD_EVERY = 100;
+
+/**
+ * 流式扫描大字符串的行，分批让出 event loop。
+ *
+ * 不预先 split——按 \n 游标推进，避免大字符串一次性 split 卡主线程。
+ *
+ * 行终止与 split(/\r?\n/) 的语义差异：
+ * - 把 \n 视为"行终止符"而非"分隔符"。末尾 \n 之后**不产生**额外空段，即
+ *   `'foo\n'` 仅产 `['foo']`（split 会得 `['foo','']`）。`skipEmpty: false`
+ *   下亦如此——空段是"两个分隔符之间没字符"，末尾 \n 之后没有内容也没有下
+ *   一个分隔符，所以本来就不应该产空段。
+ * - 仅剥紧贴 \n 之前的 \r（CRLF 折行）。**孤立的 \r**（行内或末尾段无 \n）
+ *   按字面保留，与 split(/\r?\n/) 一致。
+ *
+ * 空行（连续 \n\n 之间的空段）按 skipEmpty 选项过滤，默认跳过。
+ *
+ * 让出策略：每处理 yieldEvery 行 await 一次 setImmediate，让 I/O 回调（如 RTC
+ * 数据通道帧、其它 RPC handler）有机会插入。Node 中首选 setImmediate 而非
+ * setTimeout(0)：后者最小延迟被钳制到 1ms，让出净开销显著更大。
+ *
+ * @param {string} text - 待扫描文本
+ * @param {{ yieldEvery?: number, skipEmpty?: boolean }} [opts]
+ * @returns {AsyncGenerator<string>}
+ */
+export async function* iterTextLines(text, opts = {}) {
+	if (typeof text !== 'string' || text.length === 0) return;
+	const yieldEvery = Number.isFinite(opts.yieldEvery) && opts.yieldEvery > 0
+		? Math.trunc(opts.yieldEvery)
+		: DEFAULT_YIELD_EVERY;
+	const skipEmpty = opts.skipEmpty !== false;
+
+	const len = text.length;
+	let start = 0;
+	let count = 0;
+
+	while (start < len) {
+		const lfIdx = text.indexOf('\n', start);
+		const terminatedByLf = lfIdx !== -1;
+		const end = terminatedByLf ? lfIdx : len;
+
+		// 仅当本段确实由 LF 终止时才剥末尾 \r（CRLF）。
+		// 末尾段（无 LF）保留原文，与 split(/\r?\n/) 行为一致——
+		// 否则 'a\r' 会被剥成 'a' 静默丢失，违反"行为等价"约定。
+		let lineEnd = end;
+		if (terminatedByLf && lineEnd > start && text.charCodeAt(lineEnd - 1) === 13) {
+			lineEnd--;
+		}
+
+		if (!skipEmpty || lineEnd > start) {
+			yield text.slice(start, lineEnd);
+		}
+
+		start = end + 1;
+
+		if (++count % yieldEvery === 0) {
+			await new Promise((resolve) => setImmediate(resolve));
+		}
+	}
+}

package/src/webrtc/webrtc-peer.js

@@ -69,12 +69,121 @@ export class WebRtcPeer {
 		// 队列实现选择：测试可显式覆盖；非 'fbq'/'mem' 一律收编为模块默认，避免误用
 		this.__rpcQueueImpl = (rpcQueueImpl === 'fbq' || rpcQueueImpl === 'mem') ? rpcQueueImpl : RPC_QUEUE_IMPL;
 		this.__rtcTag = impl ? `[coclaw/rtc:${impl}]` : '[coclaw/rtc]';
-		/** @type {Map<string, { pc: object, rpcChannel: object|null, rpcQueue: MemoryQueue|null, rpcDcSender: RpcDcSender|null, rpcConsumeLoop: Promise<void>|null, rpcDropMonitor: object|null, fileChannels: Set, remoteMaxMessageSize: number, nextMsgId: number }>} */
+		/** @type {Map<string, { pc: object, connId: string, rpcChannel: object|null, rpcQueue: MemoryQueue|null, rpcDcSender: RpcDcSender|null, rpcConsumeLoop: Promise<void>|null, rpcDropMonitor: object|null, fileChannels: Set, remoteMaxMessageSize: number, nextMsgId: number }>} */
 		this.__sessions = new Map();
+		// per-connId 信令串行化队列：把外线 ws 信令处理改成"按 connId 维护 FIFO 队列"，
+		// 消息按到达顺序串行处理。替换原 offerMutex 方案——后者的 await prev 微任务跳板
+		// 会让 setRemoteDescription 的 IPC 字节序被推到紧随而至的 ICE 候选之后，导致冷
+		// 启动时部分 ICE 候选撞"remote description is not set"被 pion 丢弃。
+		//
+		// 队列与 sessions 生命周期完全解耦：closeByConnId / closeAll / failed-TTL 等 session
+		// 清理路径不动 __signalingQueues；唯一删除路径是 drain 跑空后自删 entry，下条同
+		// connId 消息进来再按需重建。
+		/** @type {Map<string, { queue: Array<{ msg: object, doneCb: () => void }>, running: boolean }>} */
+		this.__signalingQueues = new Map();
+		// 关停门禁：closeAll 入口立即置 true，后续 drain / __handleOffer 在 await 边界看到
+		// __stopping 即放弃后续动作，避免在 plugin 关停期间继续新建/响应 PC。
+		this.__stopping = false;
 	}
 
-	/** 处理来自 Server 转发的信令消息 */
+	/**
+	 * 处理来自 Server 转发的信令消息。
+	 *
+	 * 入队即调度，每条消息附带 doneCb；caller `await handleSignaling(msg)` 会等本条 msg
+	 * 真正 drain 完毕（含错误被 drain 内 catch 转 remoteLog 的情形）才回。错误不再冒到
+	 * 调用方——`rtc.signaling-error` remoteLog 是单一来源，由 drain 的 per-item catch 输出。
+	 *
+	 * 同 connId 的多条消息严格 FIFO；不同 connId 互不阻塞（每个 connId 自己一条 drain
+	 * 微任务链）。冷启动 1 offer + 5 ICE 并发投递时，drain 保证 SRD 完整跑完后再发 ICE
+	 * 的 addIceCandidate，避免 pion 端"remote description is not set"丢候选。
+	 */
 	async handleSignaling(msg) {
+		const connId = msg?.fromConnId ?? msg?.toConnId;
+		if (!connId) return;
+		return new Promise((resolve) => {
+			this.__enqueueSignaling(connId, msg, resolve);
+		});
+	}
+
+	__enqueueSignaling(connId, msg, doneCb) {
+		let state = this.__signalingQueues.get(connId);
+		if (!state) {
+			state = { queue: [], running: false };
+			this.__signalingQueues.set(connId, state);
+		}
+		state.queue.push({ msg, doneCb });
+		// fire-and-forget 触发 drain；running flag 保证只有第一条入队的 caller 启动真实 drain，
+		// 后续入队的 caller 走 push + 由当前 drain 顺序消化。drain 自身用 try/finally 兜底，
+		// per-item 诊断调用也都包了 try/catch；这里再加一层 .catch() 兜 unhandled rejection
+		// 的极冷防御——CoClaw plugin 强约束要求"不许带垮 gateway"。
+		this.__drainSignaling(connId, state).catch((err) => {
+			/* c8 ignore start -- drain 内部 try/finally + per-item try/catch 已覆盖；此 catch 仅极冷防御 */
+			try {
+				this.logger.error?.(`${this.__rtcTag} __drainSignaling unhandled error conn=${connId}: ${err?.message ?? err}`);
+			} catch {
+				/* swallow */
+			}
+			/* c8 ignore stop */
+		});
+	}
+
+	async __drainSignaling(connId, state) {
+		if (state.running) return;
+		// 同步置位：入口到首次 await 之间不能让步，否则同 tick 内多次 enqueue 会双开 drain。
+		state.running = true;
+		try {
+			while (state.queue.length > 0) {
+				// 关停门禁：closeAll 已置位时，剩余信令全部丢弃但仍 fire 每条 doneCb，
+				// 防止 caller `await handleSignaling` 悬挂（队列在 finally 内删除 entry）。
+				if (this.__stopping) {
+					for (const item of state.queue) {
+						/* c8 ignore next 2 -- doneCb 是构造时塞入的 Promise resolver，理论上不抛；try 仅极冷防御 */
+						try { item.doneCb?.(); } catch { /* swallow */ }
+					}
+					state.queue.length = 0;
+					break;
+				}
+				const item = state.queue.shift();
+				try {
+					await this.__handleSignalingMsg(item.msg);
+				} catch (err) {
+					// 单条信令出错不打断 drain；与 realtime-bridge 原 outer catch 的诊断格式对齐。
+					// 诊断调用各自 try/catch：若 logger / remoteLog 自身抛错（极冷），不能让异常
+					// 冒出 per-item catch 阻断后续 doneCb fire（CoClaw plugin "不许带垮 gateway"
+					// 强约束 + 防止 caller `await handleSignaling` 永挂）。
+					const t = item.msg?.type ?? 'unknown';
+					/* c8 ignore next 2 -- 诊断 wrap 是极冷防御，注入的 logger 不抛 */
+					try { this.logger.warn?.(`${this.__rtcTag} signaling error type=${t} conn=${connId}: ${err?.message}`); } catch { /* swallow */ }
+					/* c8 ignore next 2 -- 同上 */
+					try { this.__remoteLog(`rtc.signaling-error type=${t} conn=${connId} msg=${err?.message}`); } catch { /* swallow */ }
+				} finally {
+					// 始终 fire doneCb（即便 await 抛错或 logger 自身抛错），caller 不悬挂。
+					/* c8 ignore next 2 -- 同上，doneCb 是 Promise resolver；try 仅极冷防御 */
+					try { item.doneCb?.(); } catch { /* swallow */ }
+				}
+			}
+		} finally {
+			state.running = false;
+			if (state.queue.length === 0) {
+				// 同 connId 旧 entry 可能在 drain 期间被替换；仅当 map 仍指向本 state 时才删，
+				// 避免误删新 entry。
+				if (this.__signalingQueues.get(connId) === state) {
+					this.__signalingQueues.delete(connId);
+				}
+				/* c8 ignore start -- 防御性兜底；正常控制流 while 退出时 queue.length 必为 0 */
+			} else {
+				// 契约违反：while 条件按 length>0 进，__stopping 分支 break 前会 length=0，
+				// 正常退出意味着 queue 已空——理论不可达。不主动重启 drain（running 已落 false，
+				// 下条 enqueue 自然 kick off 消化残留），保留 entry 以便后续 drain 继续处理。
+				this.logger.error?.(`${this.__rtcTag} __drainSignaling exited with non-empty queue conn=${connId} len=${state.queue.length}`);
+				this.__remoteLog(`drain.contract-violation conn=${connId} len=${state.queue.length}`);
+			}
+			/* c8 ignore stop */
+		}
+	}
+
+	/** 单条信令的 type→handler 分发（drain 内部调用，外部测试可直接复用 handleSignaling） */
+	async __handleSignalingMsg(msg) {
 		const connId = msg.fromConnId ?? msg.toConnId;
 		if (msg.type === 'rtc:offer') {
 			await this.__handleOffer(msg);
@@ -83,20 +192,60 @@ export class WebRtcPeer {
 		} else if (msg.type === 'rtc:ready' || msg.type === 'rtc:closed') {
 			this.__logDebug(`${msg.type} from ${connId}`);
 			if (msg.type === 'rtc:closed') {
-				await this.closeByConnId(connId);
+				const session = this.__sessions.get(connId);
+				if (session) await this.closeByConnId(connId, session);
 			}
 		}
 	}
 
-	/** 关闭指定 connId 的 PeerConnection */
-	async closeByConnId(connId) {
-		const session = this.__sessions.get(connId);
-		if (!session) return;
-		// 先 detach 所有 PC 事件，再做后续 await 链。两个目的：
-		// 1. 防止 pc.close() 异步触发 onconnectionstatechange 误删 connId 复用后的新 session
-		// 2. RPC 清理含 await（queue.destroy + consumeLoop），期间若旧 PC 还有滞后回调
-		//    （某些 WebRTC 实现 close 后仍投递事件），可能通过 Map.get(connId) 拿到新 session 误操作
-		//    特别是 ondatachannel：晚到的 channel 会被 __setupDataChannel 装到新 session
+	/**
+	 * 关闭指定 session：身份守卫确保 connId 仍指向 expectedSession 时才动手，
+	 * 否则 no-op（session 已被同步段五件事原子替换 / 旧 close 已完成 / 等）。
+	 * @param {string} connId
+	 * @param {object} expectedSession - 调用方持有的 session 引用；nullish 视为 no-op。
+	 */
+	async closeByConnId(connId, expectedSession) {
+		if (!expectedSession) return;
+		if (this.__sessions.get(connId) !== expectedSession) return;
+		const session = expectedSession;
+		// 同步先 detach handler + clear timer，再 delete map，最后才进入 fire-and-forget 兼容的
+		// 异步收尾（sender/queue/pc.close）。这个顺序保证：(1) pc.close 期间的滞后回调不会
+		// 误改新 session；(2) sessions.get(connId) 在删表后立即返回 undefined，并发 offer 走
+		// 同步段五件事路径而非误以为"close 还在跑"。
+		this.__detachPcHandlers(session);
+		this.__clearSessionSyncState(session);
+		this.__sessions.delete(connId);
+		await this.__finalizeSessionAsync(session);
+		this.__remoteLog(`rtc.closed conn=${connId}`);
+		this.logger.info?.(`${this.__rtcTag} [${connId}] closed`);
+	}
+
+	/**
+	 * 关闭所有 PeerConnection。每轮快照表内当前所有 session 并发关闭，
+	 * 表非空就继续 drain——若 closeAll await Promise.all 期间另一条 message handler
+	 * 已过 sock guard 并落地新 session（auth-close / stop 窄缝），下一轮把它收掉，
+	 * 结构性消除"快照漏掉新 session"的 race，不必依赖 12h failed-TTL 兜底。
+	 *
+	 * 终止条件：调用方（realtime-bridge auth-close / stop）已先关 server WS，
+	 * 不会再有新 rtc:offer 涌入，drain 至多一两轮就达表空。
+	 */
+	async closeAll() {
+		// 关停门禁：drain 与 __handleOffer 看到 __stopping 后立刻放弃后续动作，
+		// 配合 while-drain 兜底"snapshot 漏掉新 session"竞态。__stopping 一旦置 true
+		// 不再重置——本插件 closeAll 调用方（auth-close / 析构）均紧跟 webrtcPeer = null，
+		// 下次复用会建新实例从 false 起。
+		this.__stopping = true;
+		while (this.__sessions.size > 0) {
+			const closing = [...this.__sessions.values()].map((s) => this.closeByConnId(s.connId, s));
+			await Promise.all(closing);
+		}
+	}
+
+	/**
+	 * 同步 detach PC 上 6 个 handler。防止 pc.close 异步触发的滞后回调
+	 * 通过 sessions.get(connId) 误访问已被替换/正在替换的新 session。
+	 */
+	__detachPcHandlers(session) {
 		session.pc.onconnectionstatechange = null;
 		session.pc.onicecandidate = null;
 		session.pc.ondatachannel = null;
@@ -109,13 +258,14 @@ export class WebRtcPeer {
 		if ('onicegatheringstatechange' in session.pc) {
 			session.pc.onicegatheringstatechange = null;
 		}
-		// 清理 failed TTL 定时器
+	}
+
+	/** 同步清 session 上的 timer 与 in-flight 标志，避免 close 后还在 fire 副作用。 */
+	__clearSessionSyncState(session) {
 		if (session.__failedTimer) {
 			clearTimeout(session.__failedTimer);
 			session.__failedTimer = null;
 		}
-		// 清理 plugin-probe 定时器（避免 session 已关闭仍触发 timeout 日志，
-		// 或 500ms 调度窗口内 session 被替换时对着新 session 误发探针）
 		if (session.__pluginProbeSchedTimer) {
 			clearTimeout(session.__pluginProbeSchedTimer);
 			session.__pluginProbeSchedTimer = null;
@@ -125,11 +275,15 @@ export class WebRtcPeer {
 			session.__pluginProbeTimer = null;
 			session.__pluginProbeInFlight = null;
 		}
-		this.__sessions.delete(connId);
-		// 显式关闭 rpc 链路：dc.onclose 路径中 `sessions.get(connId)` 已返回 undefined 而短路，
-		// 此处不主动 close 会丢失 drop 汇总 remoteLog 诊断 + consumeLoop 泄漏。
-		// summarize 走 destroy 的 onBeforeClear 钩子在 mutex 内拿原子快照——同步读 stats 看不到
-		// 还在 mutex 队列里的 in-flight enqueue（broadcast 是 fire-and-forget，会与 close 并发）。
+	}
+
+	/**
+	 * 异步收尾：rpc 链路 destroy + monitor summarize + pc.close。可作为 fire-and-forget 跑
+	 * （同步段非 ICE 重发替换旧 session 时），也作为 closeByConnId 的 await 末段。
+	 * 调用前必须已完成 __detachPcHandlers + __clearSessionSyncState + sessions.delete，否则
+	 * 滞后回调可能踩新 session。
+	 */
+	async __finalizeSessionAsync(session) {
 		if (session.rpcDcSender || session.rpcQueue) {
 			session.rpcDcSender?.close();
 			const monRef = session.rpcDropMonitor;
@@ -142,27 +296,19 @@ export class WebRtcPeer {
 			session.rpcChannel = null;
 		}
 		await session.pc.close();
-		this.__remoteLog(`rtc.closed conn=${connId}`);
-		this.logger.info?.(`${this.__rtcTag} [${connId}] closed`);
-	}
-
-	/** 关闭所有 PeerConnection */
-	async closeAll() {
-		const closing = [...this.__sessions.keys()].map((id) => this.closeByConnId(id));
-		await Promise.all(closing);
 	}
 
-	/** 向所有已打开的 rpcChannel 广播（大消息自动分片，经由 FBQ/MemoryQueue + RpcDcSender 流控） */
-	broadcast(payload) {
-		let jsonStr;
-		try {
-			jsonStr = JSON.stringify(payload);
-		} catch (err) {
-			// 循环引用 / BigInt 等导致 stringify 抛——记日志后整条丢弃，不冒到 gateway
-			this.__logDebug(`broadcast stringify failed: ${err?.message}`);
-			return;
-		}
-		if (typeof jsonStr !== 'string') return; // payload 是 undefined/symbol 时 stringify 返回 undefined
+	/**
+	 * 向所有已打开的 rpcChannel 广播（大消息自动分片，经由 FBQ/MemoryQueue + RpcDcSender 流控）。
+	 * @param {object} payload - 完整的 JSON 帧
+	 * @param {string} [rawStr] - 已序列化字符串旁路：非空字符串且不含字面 \n/\r 时直接透传，
+	 *                            跳过 stringify；含换行或类型不符时回退到 JSON.stringify(payload)。
+	 *                            用于 gateway WS → DC 转发链路，省掉对大 payload（如 agent.run.event
+	 *                            含大 tool_result / compaction summary）的主线程重复序列化阻塞。
+	 */
+	broadcast(payload, rawStr) {
+		const jsonStr = this.__resolveJsonStr(payload, rawStr, 'broadcast');
+		if (jsonStr === null) return;
 		for (const session of this.__sessions.values()) {
 			const q = session.rpcQueue;
 			if (q && session.rpcChannel?.readyState === 'open') {
@@ -185,21 +331,16 @@ export class WebRtcPeer {
 	 *
 	 * @param {string} connId
 	 * @param {object} payload - 完整的 JSON 帧（通常是 { type: 'event', event, payload }）
+	 * @param {string} [rawStr] - 已序列化字符串旁路：语义同 broadcast 的 rawStr 参数
 	 * @returns {Promise<boolean>} true=已入队发送；false=session 不存在 / DC 未 open / payload 不可序列化 / 发送队列拒收
 	 */
-	async sendTo(connId, payload) {
+	async sendTo(connId, payload, rawStr) {
 		const session = this.__sessions.get(connId);
 		if (!session) return false;
 		const q = session.rpcQueue;
 		if (!q || session.rpcChannel?.readyState !== 'open') return false;
-		let jsonStr;
-		try {
-			jsonStr = JSON.stringify(payload);
-		} catch (err) {
-			this.__logDebug(`[${connId}] sendTo stringify failed: ${err?.message}`);
-			return false;
-		}
-		if (typeof jsonStr !== 'string') return false;
+		const jsonStr = this.__resolveJsonStr(payload, rawStr, `[${connId}] sendTo`);
+		if (jsonStr === null) return false;
 		try {
 			return await q.enqueue(jsonStr);
 		} catch (err) {
@@ -209,71 +350,53 @@ export class WebRtcPeer {
 		}
 	}
 
+	/**
+	 * 把 (payload, rawStr) 归一为可入队的 JSON 字符串。
+	 * 直通条件：rawStr 为非空字符串且不含字面 \n/\r。
+	 * 回退路径：含换行或类型不符时走 JSON.stringify(payload)；并对 stringify 抛 / 返非字符串做防御。
+	 *
+	 * 为何排除字面换行：rpcQueue 的 FBQ 实现在溢出到磁盘时按 JSONL 格式（rec + '\n'）追加，
+	 * 用 readline 回填——若入队字符串内含字面 \n/\r 会切坏 spill 文件。旧 stringify 路径输出
+	 * 紧凑无换行天然满足；新 raw 直通必须保持同等强度的入队不变量。
+	 *
+	 * @param {object} payload
+	 * @param {string} [rawStr]
+	 * @param {string} tag - 日志前缀（broadcast / [connId] sendTo）
+	 * @returns {string | null} 可入队的 JSON 字符串；null 表示丢弃（stringify 抛 / 返非字符串）
+	 */
+	__resolveJsonStr(payload, rawStr, tag) {
+		if (typeof rawStr === 'string' && rawStr.length > 0) {
+			if (!rawStr.includes('\n') && !rawStr.includes('\r')) {
+				return rawStr;
+			}
+			// 含换行 → 走 stringify 重做归一化（保 FBQ JSONL 行约束）
+			this.__logDebug(`${tag} rawStr fallback: contains newline`);
+		}
+		try {
+			const jsonStr = JSON.stringify(payload);
+			// payload 是 undefined/symbol 时 stringify 返回 undefined
+			if (typeof jsonStr !== 'string') return null;
+			return jsonStr;
+		} catch (err) {
+			// 循环引用 / BigInt 等导致 stringify 抛——记日志后整条丢弃，不冒到 gateway
+			this.__logDebug(`${tag} stringify failed: ${err?.message}`);
+			return null;
+		}
+	}
+
 	async __handleOffer(msg) {
+		// 关停门禁：closeAll 已置 __stopping 后任何 offer 都不再创建 session 或回 answer，
+		// 与 drain 顶端的 __stopping 检查互为冗余（drain 抢先一步，但 __handleOffer 入口
+		// 这条是"今天每条无害不代表明天加副作用还无害"的稳健补丁）。
+		if (this.__stopping) return;
+
 		const connId = msg.fromConnId;
 		const isIceRestart = !!msg.payload?.iceRestart;
-		const credRemain = this.__credRemainSec(msg.turnCreds);
-		const credRemainStr = credRemain ?? 'none';
 
-		// ICE restart：在现有 PC 上重新协商，保持 DTLS session
-		if (isIceRestart) {
-			const existing = this.__sessions.get(connId);
-			if (existing) {
-				// 仅已验证支持 ICE restart 的 impl 放行，其余立即 reject 让 UI 走 rebuild
-				if (this.__impl !== 'pion') {
-					this.__remoteLog(`rtc.ice-restart-unsupported conn=${connId} impl=${this.__impl} credRemain=${credRemainStr}`);
-					this.logger.info?.(`${this.__rtcTag} ICE restart rejected: impl=${this.__impl} not verified`);
-					this.__onSend({
-						type: 'rtc:restart-rejected',
-						toConnId: connId,
-						payload: { reason: 'impl_unsupported' },
-					});
-					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} credRemain=${credRemainStr}`);
-				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，同步刷新 sender 分片阈值；
-					// queue 存的是完整字符串（buildChunks 在 sender.send 内同步完成），
-					// 已开始分片的当前消息用旧 size，下一条消息用新 size
-					const newMMS = this.__resolveMaxMessageSize(existing.pc, msg.payload.sdp);
-					if (newMMS !== existing.remoteMaxMessageSize) {
-						existing.remoteMaxMessageSize = newMMS;
-						if (existing.rpcDcSender) existing.rpcDcSender.maxMessageSize = newMMS;
-					}
-					const answer = await existing.pc.createAnswer();
-					await existing.pc.setLocalDescription(answer);
-					this.__onSend({
-						type: 'rtc:answer',
-						toConnId: connId,
-						payload: { sdp: answer.sdp },
-					});
-					this.__remoteLog(`rtc.restart-answer-sent conn=${connId}`);
-					this.logger.info?.(`${this.__rtcTag} ICE restart answer sent to ${connId}`);
-					return;
-				} catch (err) {
-					// ICE restart 协商失败 → reject，不 fall through
-					this.__remoteLog(`rtc.ice-restart-failed conn=${connId} credRemain=${credRemainStr}`);
-					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 → reject（plugin 可能已重启）
+		// no-session ICE restart：立即 reject，不建 session。
+		if (isIceRestart && !this.__sessions.has(connId)) {
+			const credRemain = this.__credRemainSec(msg.turnCreds);
+			const credRemainStr = credRemain ?? 'none';
 			this.__remoteLog(`rtc.ice-restart-no-session conn=${connId} credRemain=${credRemainStr}`);
 			this.logger.warn?.(`${this.__rtcTag} ICE restart from ${connId} but no session, rejecting`);
 			this.__onSend({
@@ -284,19 +407,175 @@ export class WebRtcPeer {
 			return;
 		}
 
-		this.__remoteLog(`rtc.offer conn=${connId}`);
-		this.logger.info?.(`${this.__rtcTag} offer received from ${connId}, creating answer`);
+		let session;
+		if (isIceRestart) {
+			// ICE restart：复用现有 session
+			session = this.__sessions.get(connId);
+		} else {
+			// 非 ICE：必要时同步替换旧 session。五件事原子（JS 单线程保证不与并发 offer 交错）：
+			// (a) detach 旧 PC handler  (b) clear 旧 session 同步状态  (c) sessions.delete
+			// (d) 触发 fire-and-forget 异步收尾（闭包持旧 session 引用，不按 connId 查表）
+			// (e) 建新 session + wire handler + sessions.set —— 由 __createSession 完成
+			const oldSession = this.__sessions.get(connId);
+			if (oldSession) {
+				this.__detachPcHandlers(oldSession);
+				this.__clearSessionSyncState(oldSession);
+				this.__sessions.delete(connId);
+				this.__finalizeSessionAsync(oldSession).catch((err) => {
+					/* c8 ignore next 2 -- finalize 内 pc.close 在生产路径稳定；防 unhandled rejection */
+					this.logger.warn?.(`${this.__rtcTag} [${connId}] background finalize failed: ${err?.message ?? err}`);
+				});
+				this.__remoteLog(`rtc.closed conn=${connId}`);
+				this.logger.info?.(`${this.__rtcTag} [${connId}] closed`);
+			}
+			if (this.__sessions.size >= MAX_SESSIONS) {
+				this.__evictOldestFailed();
+			}
+			session = this.__createSession(msg, connId);
+		}
+
+		// SDP 协商：原 __handleOfferLocked 主体直接嵌入，删除 offerMutex.withLock 包裹。
+		// per-connId FIFO drain 已保证同 connId 信令串行；mutex.withLock 的 await prev
+		// microtask 让步即是冷启动 ICE 候选撞 SRD 未设的根因，移除后顺序恢复："offer→ICE→ICE..."
+		// 的 ws 到达顺序在 pion-ipc 端被原样保留。
+		//
+		// 三段 await 间的身份重核仍保留：可在 await 中途删 session 的路径只剩"不走信令
+		// 队列"那几条——connectionState=closed/failed-TTL 同步触发 closeByConnId、
+		// closeAll 外线调用、闭包别处直接调 closeByConnId。rtc:closed 现在走 FIFO drain，
+		// 不会在同 connId 三段 await 间插入；最多排在 offer 后面、offer 完成发出 answer
+		// 后才被处理（UI 端 setRemoteDescription 已 try/catch，stale answer 无回归）。
+		// 命中身份重核即丢弃后续动作，不发 stale rtc:answer。
+		const credRemain = this.__credRemainSec(msg.turnCreds);
+		const credRemainStr = credRemain ?? 'none';
 
-		// 同一 connId 重复 offer → 先关闭旧连接
-		if (this.__sessions.has(connId)) {
-			await this.closeByConnId(connId);
+		if (isIceRestart) {
+			// 仅已验证支持 ICE restart 的 impl 放行，其余立即 reject 让 UI 走 rebuild
+			if (this.__impl !== 'pion') {
+				this.__remoteLog(`rtc.ice-restart-unsupported conn=${connId} impl=${this.__impl} credRemain=${credRemainStr}`);
+				this.logger.info?.(`${this.__rtcTag} ICE restart rejected: impl=${this.__impl} not verified`);
+				this.__onSend({
+					type: 'rtc:restart-rejected',
+					toConnId: connId,
+					payload: { reason: 'impl_unsupported' },
+				});
+				return; // TTL timer 保持不变（reject 是同步的，不影响 timer 正常工作）
+			}
+			// 暂停 failed TTL timer：pion restart 涉及异步协商，期间不应被回收
+			if (session.__failedTimer) {
+				clearTimeout(session.__failedTimer);
+				session.__failedTimer = null;
+			}
+			this.__remoteLog(`rtc.ice-restart conn=${connId} credRemain=${credRemainStr}`);
+			this.logger.info?.(`${this.__rtcTag} ICE restart offer from ${connId}, renegotiating`);
+			try {
+				await session.pc.setRemoteDescription({ type: 'offer', sdp: msg.payload.sdp });
+				// 身份重核：能在三连 await 中间删 session 的路径都不走信令队列——
+				// connectionState=closed/failed-TTL 同步触发 closeByConnId、closeAll 外线调用、
+				// 闭包别处直调 closeByConnId。命中即丢弃后续动作，不发 stale rtc:answer。
+				// logger.info 仅本地诊断，不上 remoteLog（closeByConnId 触发方自带 rtc.closed /
+				// rtc.state 等远程日志，server 端能从那侧还原"PC 哪一刻死了"）。
+				if (this.__sessions.get(connId) !== session) {
+					this.logger.info?.(`${this.__rtcTag} [${connId}] ICE restart aborted: session changed after setRemoteDescription`);
+					return;
+				}
+				// 重协商 SDP 可能变更 a=max-message-size，同步刷新 sender 分片阈值；
+				// queue 存的是完整字符串（buildChunks 在 sender.send 内同步完成），
+				// 已开始分片的当前消息用旧 size，下一条消息用新 size
+				const newMMS = this.__resolveMaxMessageSize(session.pc, msg.payload.sdp);
+				if (newMMS !== session.remoteMaxMessageSize) {
+					session.remoteMaxMessageSize = newMMS;
+					if (session.rpcDcSender) session.rpcDcSender.maxMessageSize = newMMS;
+				}
+				const answer = await session.pc.createAnswer();
+				if (this.__sessions.get(connId) !== session) {
+					this.logger.info?.(`${this.__rtcTag} [${connId}] ICE restart aborted: session changed after createAnswer`);
+					return;
+				}
+				await session.pc.setLocalDescription(answer);
+				if (this.__sessions.get(connId) !== session) {
+					this.logger.info?.(`${this.__rtcTag} [${connId}] ICE restart aborted: session changed after setLocalDescription`);
+					return;
+				}
+				this.__onSend({
+					type: 'rtc:answer',
+					toConnId: connId,
+					payload: { sdp: answer.sdp },
+				});
+				this.__remoteLog(`rtc.restart-answer-sent conn=${connId}`);
+				this.logger.info?.(`${this.__rtcTag} ICE restart answer sent to ${connId}`);
+				return;
+			} catch (err) {
+				// 身份重核：session 已被中途关掉时 catch 收到的 err 是"PC 已 close"残响，
+				// 不应再发 stale restart-rejected（用户会看到误报失败），也不重复调 closeByConnId
+				// （session 已删，再调是 no-op 但徒增 rtc.closed 日志噪声）。
+				if (this.__sessions.get(connId) !== session) {
+					this.logger.info?.(`${this.__rtcTag} [${connId}] ICE restart error after session change (suppressed): ${err?.message}`);
+					return;
+				}
+				// ICE restart 协商失败 → reject，不 fall through
+				this.__remoteLog(`rtc.ice-restart-failed conn=${connId} credRemain=${credRemainStr}`);
+				this.logger.warn?.(`${this.__rtcTag} ICE restart failed for ${connId}: ${err?.message}`);
+				this.__onSend({
+					type: 'rtc:restart-rejected',
+					toConnId: connId,
+					payload: { reason: 'restart_failed' },
+				});
+				await this.closeByConnId(connId, session).catch((closeErr) => {
+					/* c8 ignore next -- closeByConnId 内部已 try/catch，此路径极难触发 */
+					this.logger.warn?.(`${this.__rtcTag} closeByConnId failed after restart rejection for ${connId}: ${closeErr?.message}`);
+				});
+				return;
+			}
 		}
 
-		// session 总数限制：溢出时淘汰最旧的 failed session
-		if (this.__sessions.size >= MAX_SESSIONS) {
-			this.__evictOldestFailed();
+		// 首次 offer：session 已由 sync gate 建好（含 wire 全部 PC handler 与 sessions.set），
+		// 锁内只跑 SDP 协商三段 await。每段后做身份重核：pion-ipc 不在 pc.close 时 reject
+		// in-flight 请求，过期 setRemoteDescription / createAnswer / setLocalDescription 可能
+		// 正常 resolve，身份重核拦截"已被替换的 session 发出 stale answer"。
+		this.__remoteLog(`rtc.offer conn=${connId}`);
+		this.logger.info?.(`${this.__rtcTag} offer received from ${connId}, creating answer`);
+		try {
+			await session.pc.setRemoteDescription({ type: 'offer', sdp: msg.payload.sdp });
+			if (this.__sessions.get(connId) !== session) {
+				this.logger.info?.(`${this.__rtcTag} [${connId}] first offer aborted: session changed after setRemoteDescription`);
+				return;
+			}
+			const answer = await session.pc.createAnswer();
+			if (this.__sessions.get(connId) !== session) {
+				this.logger.info?.(`${this.__rtcTag} [${connId}] first offer aborted: session changed after createAnswer`);
+				return;
+			}
+			await session.pc.setLocalDescription(answer);
+			if (this.__sessions.get(connId) !== session) {
+				this.logger.info?.(`${this.__rtcTag} [${connId}] first offer aborted: session changed after setLocalDescription`);
+				return;
+			}
+			this.__onSend({
+				type: 'rtc:answer',
+				toConnId: connId,
+				payload: { sdp: answer.sdp },
+			});
+			this.__remoteLog(`rtc.answer conn=${connId}`);
+			this.logger.info?.(`${this.__rtcTag} answer sent to ${connId}`);
+		} catch (err) {
+			// 身份重核：session 已被替换/外部 close 时 err 是 PC 残响，suppress；
+			// 由替换方 / close 方负责清理，不重复抛错到上游（避免误报"首次连接失败"）。
+			if (this.__sessions.get(connId) !== session) {
+				this.logger.info?.(`${this.__rtcTag} [${connId}] first offer error after session change (suppressed): ${err?.message}`);
+				return;
+			}
+			// 自家 session 仍在表里：走 closeByConnId 集中清理（detach + timer 清理 + pc.close + 日志）
+			await this.closeByConnId(connId, session).catch(() => { /* c8 ignore next -- 极冷防御 */ });
+			throw err;
 		}
+	}
 
+	/**
+	 * 同步建新 session：构造 PC、wire 全部 PC handler、sessions.set。
+	 * 在 sync gate 内调用，调用前应已完成对旧 session 的同步替换（如有）。
+	 * 异常会传播到 __handleOffer，由 handleSignaling 调用方处理。
+	 */
+	__createSession(msg, connId) {
 		// 从 Server 注入的 turnCreds 构建 iceServers
 		// werift 的 urls 必须是单个 string，每个 URL 独立一个对象
 		const iceServers = [];
@@ -335,7 +614,18 @@ export class WebRtcPeer {
 
 		const remoteMaxMessageSize = this.__resolveMaxMessageSize(pc, msg.payload.sdp);
 
-		const session = { pc, rpcChannel: null, rpcQueue: null, rpcDcSender: null, rpcConsumeLoop: null, rpcDropMonitor: null, fileChannels: new Set(), remoteMaxMessageSize, nextMsgId: 1 };
+		const session = {
+			pc,
+			connId,
+			rpcChannel: null,
+			rpcQueue: null,
+			rpcDcSender: null,
+			rpcConsumeLoop: null,
+			rpcDropMonitor: null,
+			fileChannels: new Set(),
+			remoteMaxMessageSize,
+			nextMsgId: 1,
+		};
 		this.__sessions.set(connId, session);
 
 		// ICE candidate → 发给 UI，并统计各类型 candidate 数量
@@ -476,12 +766,12 @@ export class WebRtcPeer {
 					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(() => {});
+						this.closeByConnId(connId, cur).catch(() => {});
 					}, FAILED_SESSION_TTL_MS);
 					cur.__failedTimer.unref?.();
 				} else if (state === 'closed') {
 					// 自然进入 closed 时也需通过 closeByConnId 释放 IPC listeners 和 Go 资源
-					this.closeByConnId(connId).catch(() => {});
+					this.closeByConnId(connId, cur).catch(() => {});
 				}
 			}
 		};
@@ -532,32 +822,7 @@ export class WebRtcPeer {
 			}
 		};
 
-		// offer → answer
-		try {
-			await pc.setRemoteDescription({ type: 'offer', sdp: msg.payload.sdp });
-			const answer = await pc.createAnswer();
-			await pc.setLocalDescription(answer);
-
-			this.__onSend({
-				type: 'rtc:answer',
-				toConnId: connId,
-				payload: { sdp: answer.sdp },
-			});
-			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);
-			if (cur && cur.pc === pc) {
-				if (cur.__failedTimer) {
-					clearTimeout(cur.__failedTimer);
-					cur.__failedTimer = null;
-				}
-				this.__sessions.delete(connId);
-			}
-			await pc.close().catch(() => {});
-			throw err;
-		}
+		return session;
 	}
 
 	async __handleIce(msg) {
@@ -1030,7 +1295,7 @@ export class WebRtcPeer {
 			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(() => {});
+				this.closeByConnId(connId, session).catch(() => {});
 				return true;
 			}
 		}