@coclaw/openclaw-coclaw 0.17.1 → 0.17.3

package/package.json

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

package/src/realtime-bridge.js

@@ -22,6 +22,12 @@ const CONNECT_TIMEOUT_MS = 10_000;
 const SERVER_HB_PING_MS = 25_000;
 const SERVER_HB_TIMEOUT_MS = 45_000;
 const SERVER_HB_MAX_MISS = 4; // 连续 4 次无响应才断连（~3 分钟）
+// gateway 握手失败的指数退避表：每个元素是"上一次失败"之后、"下一次尝试"之前的等待时间。
+// 最多 5 次重试（加上首次尝试共 6 次），全部失败后进入 gave-up 终态，不再自动尝试。
+const GATEWAY_RETRY_DELAYS_MS = [5_000, 10_000, 20_000, 20_000, 20_000];
+// v3 握手失败时，只有错误消息匹配此正则才回退到不带 device 的 legacy 握手。
+// 严格限定在"签名/设备/scope/协议"相关错误，避免对网络/内部错误做无意义的降级尝试。
+const GATEWAY_HANDSHAKE_FALLBACK_PATTERN = /signature|device|scope|protocol/i;
 
 function toServerWsUrl(baseUrl, token) {
 	const url = new URL(baseUrl);
@@ -112,6 +118,12 @@ export class RealtimeBridge {
 		this.__fileHandler = null;
 		this.__ndcPreloadResult = null;
 		this.__ndcCleanup = null;
+		// gateway 握手重试状态（刷屏治理 + 兼容性回退）
+		this.__gatewayAttempts = 0;          // 已失败的连续握手次数（握手成功时归零）
+		this.__gatewayRetryTimer = null;     // 下一次尝试的 setTimeout 句柄
+		this.__gatewayGaveUp = false;        // 重试次数耗尽 → 终态，不再自动尝试
+		this.__gatewayLegacyMode = false;    // 学到"本 gateway 不接受带 device 的 v3"
+		this.__gatewayLastReason = null;     // 最近一次失败原因（用于 gave-up 上报）
 	}
 
 	__resolveWebSocket() {
@@ -192,6 +204,14 @@ export class RealtimeBridge {
 	}
 
 	__closeGatewayWs() {
+		// 当 server WS 失效主动关闭 gateway 时，取消任何 pending 重试定时器、把连续失败计数归零：
+		// 新 server 会话应从新预算开始重试 gateway，避免旧会话的零散失败累计吞掉未来的重试机会。
+		// 不清 __gatewayGaveUp / __gatewayLegacyMode —— 那是跨会话的终态/学习，只由 stop() 复位。
+		if (this.__gatewayRetryTimer) {
+			clearTimeout(this.__gatewayRetryTimer);
+			this.__gatewayRetryTimer = null;
+		}
+		this.__gatewayAttempts = 0;
 		if (!this.gatewayWs) {
 			return;
 		}
@@ -558,12 +578,13 @@ export class RealtimeBridge {
 		};
 	}
 
-	__sendGatewayConnectRequest(ws, nonce) {
-		this.gatewayConnectReqId = `coclaw-connect-${Date.now()}`;
-		this.__logDebug(`gateway connect request -> id=${this.gatewayConnectReqId}`);
+	__sendGatewayConnectRequest(ws, nonce, { legacy = false } = {}) {
+		// 用 rpcSeq 保证 ID 唯一，避免 v3→legacy 同毫秒内两次调用产生相同 id
+		this.gatewayRpcSeq += 1;
+		this.gatewayConnectReqId = `coclaw-connect-${Date.now()}-${this.gatewayRpcSeq}`;
+		this.__logDebug(`gateway connect request -> id=${this.gatewayConnectReqId} legacy=${legacy}`);
 		try {
 			const authToken = this.__resolveGatewayAuthToken();
-			const device = this.__buildDeviceField(nonce, authToken);
 			const params = {
 				minProtocol: 3,
 				maxProtocol: 3,
@@ -577,8 +598,12 @@ export class RealtimeBridge {
 				role: 'operator',
 				scopes: ['operator.admin'],
 				auth: authToken ? { token: authToken } : undefined,
-				device,
 			};
+			// legacy 回退仅省略 device 字段；其他字段保持与 v3 一致。
+			// 当 gateway 不支持/不接受 device 字段时，auth.token 足以完成旧版握手。
+			if (!legacy) {
+				params.device = this.__buildDeviceField(nonce, authToken);
+			}
 			ws.send(JSON.stringify({
 				type: 'req',
 				id: this.gatewayConnectReqId,
@@ -592,7 +617,42 @@ export class RealtimeBridge {
 		}
 	}
 
+	/**
+	 * 握手失败一次：累加计数；未耗尽则按退避表调度下次尝试，耗尽则进入 gave-up 终态。
+	 * 调度 / 尝试 / 终态 guard 由 __ensureGatewayConnection 一致执行。
+	 * @param {string} reason - 本次失败原因，用于 gave-up 时汇总上报
+	 */
+	__onGatewayAttemptFailed(reason) {
+		if (!this.started || this.__gatewayGaveUp || this.__gatewayRetryTimer) {
+			return;
+		}
+		this.__gatewayLastReason = reason;
+		this.__gatewayAttempts += 1;
+		if (this.__gatewayAttempts > GATEWAY_RETRY_DELAYS_MS.length) {
+			this.__gatewayGaveUp = true;
+			remoteLog(`gateway.handshake.gave-up attempts=${this.__gatewayAttempts} lastReason=${reason}`);
+			this.logger.warn?.(`[coclaw] gateway handshake gave up after ${this.__gatewayAttempts} attempts (last reason: ${reason})`);
+			return;
+		}
+		const delay = GATEWAY_RETRY_DELAYS_MS[this.__gatewayAttempts - 1];
+		this.__gatewayRetryTimer = setTimeout(() => {
+			this.__gatewayRetryTimer = null;
+			this.__ensureGatewayConnection();
+		}, delay);
+		this.__gatewayRetryTimer.unref?.();
+	}
+
 	__ensureGatewayConnection() {
+		// 停机守卫：防止 stop() 之后某个已进入调度队列的 retry timer callback 再触发新 WS
+		if (!this.started) {
+			return;
+		}
+		// 刷屏治理：已进入终态 / 已调度下次尝试 → 不启动新 WS。
+		// 这两个 guard 保证在 __waitGatewayReady 或 server WS 重连的连续触发下
+		// 只会按退避表节奏新建连接。
+		if (this.__gatewayGaveUp || this.__gatewayRetryTimer) {
+			return;
+		}
 		if (this.gatewayWs || !this.serverWs || this.serverWs.readyState !== 1) {
 			return;
 		}
@@ -606,6 +666,12 @@ export class RealtimeBridge {
 		this.gatewayReady = false;
 		this.gatewayConnectReqId = null;
 
+		// per-WS 闭包状态，只在本条 WS 的生命周期内有效。
+		let connectFailReported = false;   // 已经打过 ws.connect-failed；close 时抑制重复的 ws.disconnected
+		let pendingLegacyAttempted = false; // 本 WS 已尝试过 legacy 握手，避免重复降级
+		let wasReady = false;               // 本 WS 曾经握手成功（区分"握手失败"与"成功后断开"）
+		let lastChallengeNonce = '';        // 最近一次 challenge 的 nonce，legacy 回退时复用
+
 		ws.addEventListener('message', (event) => {
 			let payload = null;
 			try {
@@ -619,13 +685,23 @@ export class RealtimeBridge {
 			}
 			if (payload.type === 'event' && payload.event === 'connect.challenge') {
 				const nonce = payload?.payload?.nonce ?? '';
-				this.__logDebug('gateway event <- connect.challenge');
-				this.__sendGatewayConnectRequest(ws, nonce);
+				lastChallengeNonce = nonce;
+				this.__logDebug(`gateway event <- connect.challenge legacyMode=${this.__gatewayLegacyMode}`);
+				// 已经学到此 gateway 是 legacy（上一条 WS 回退过）→ 直接发 legacy 握手
+				if (this.__gatewayLegacyMode) {
+					pendingLegacyAttempted = true;
+					this.__sendGatewayConnectRequest(ws, nonce, { legacy: true });
+				}
+				else {
+					this.__sendGatewayConnectRequest(ws, nonce);
+				}
 				return;
 			}
 			if (payload.type === 'res' && this.gatewayConnectReqId && payload.id === this.gatewayConnectReqId) {
 				if (payload.ok === true) {
 					this.gatewayReady = true;
+					wasReady = true;
+					this.__gatewayAttempts = 0; // 成功握手 → 重置失败计数，让后续瞬态断开有完整重试预算
 					remoteLog('ws.connected peer=gateway');
 					this.__logDebug(`gateway connect ok <- id=${payload.id}`);
 					this.gatewayConnectReqId = null;
@@ -633,10 +709,28 @@ export class RealtimeBridge {
 					this.__pushInstanceInfo();
 				}
 				else {
+					const reason = payload?.error?.message ?? 'unknown';
+					// v3 → legacy 同 WS 回退：仅在签名/协议相关错误、且本 WS 尚未尝试 legacy 时触发
+					const shouldFallback =
+						!pendingLegacyAttempted
+						&& !this.__gatewayLegacyMode
+						&& GATEWAY_HANDSHAKE_FALLBACK_PATTERN.test(reason);
+					if (shouldFallback) {
+						pendingLegacyAttempted = true;
+						this.__gatewayLegacyMode = true;
+						// v3 的失败原因已由这条 remoteLog 单独上报，不写入 __gatewayLastReason；
+						// 后者保持"最后一次真正失败的原因"语义，供 gave-up 时使用。
+						remoteLog(`gateway.handshake.fallback v3→legacy reason=${reason}`);
+						this.logger.info?.(`[coclaw] gateway v3 handshake failed (${reason}), falling back to legacy`);
+						this.__sendGatewayConnectRequest(ws, lastChallengeNonce, { legacy: true });
+						return;
+					}
 					this.gatewayReady = false;
 					this.gatewayConnectReqId = null;
-					remoteLog(`ws.connect-failed peer=gateway msg=${payload?.error?.message ?? 'unknown'}`);
-					this.logger.warn?.(`[coclaw] gateway connect failed: ${payload?.error?.message ?? 'unknown'}`);
+					connectFailReported = true;
+					this.__gatewayLastReason = reason;
+					remoteLog(`ws.connect-failed peer=gateway msg=${reason}`);
+					this.logger.warn?.(`[coclaw] gateway connect failed: ${reason}`);
 					try { ws.close(1008, 'gateway_connect_failed'); }
 					/* c8 ignore next */
 					catch {}
@@ -675,21 +769,46 @@ export class RealtimeBridge {
 			this.__logDebug('gateway ws open, waiting for connect.challenge');
 		});
 		ws.addEventListener('close', (ev) => {
-			remoteLog(`ws.disconnected peer=gateway code=${ev?.code ?? '?'}`);
+			// 握手失败路径已经打过 ws.connect-failed，这里抑制重复的 disconnected 日志；
+			// 成功后的意外断开、握手途中的异常断开仍按原样上报。
+			if (!connectFailReported) {
+				remoteLog(`ws.disconnected peer=gateway code=${ev?.code ?? '?'}`);
+			}
 			this.logger.info?.(`[coclaw] gateway ws closed (code=${ev?.code ?? '?'} reason=${ev?.reason ?? 'n/a'})`);
-			this.gatewayWs = null;
-			this.gatewayReady = false;
-			this.gatewayConnectReqId = null;
+			if (this.gatewayWs === ws) {
+				this.gatewayWs = null;
+				this.gatewayReady = false;
+				this.gatewayConnectReqId = null;
+			}
 			/* c8 ignore next 3 -- gateway 意外断开时结算未完成 RPC，避免等超时 */
 			for (const [, settle] of this.gatewayPendingRequests) {
 				settle({ ok: false, error: 'gateway_closed' });
 			}
 			this.gatewayPendingRequests.clear();
+			// 调度下一次尝试：仅在 bridge 仍活着、未 gave-up、server WS 健康时；
+			// 其他场景（如 bridge stop、server WS 已断）由上游流程兜底，不参与 gateway 重试。
+			if (this.started && !this.__gatewayGaveUp
+				&& this.serverWs && this.serverWs.readyState === 1
+				&& (wasReady || connectFailReported)) {
+				if (wasReady) {
+					// 之前握成功过，视为瞬态掉线 → 重置计数，让新一轮拿到完整重试预算
+					this.__gatewayAttempts = 0;
+				}
+				this.__onGatewayAttemptFailed(
+					/* c8 ignore next -- connectFailReported 路径必然已设 __gatewayLastReason */
+					wasReady ? 'disconnected' : (this.__gatewayLastReason ?? 'connect-failed')
+				);
+			}
 		});
 		ws.addEventListener('error', (err) => {
 			/* c8 ignore next -- ?./?? fallback */
 			remoteLog(`ws.error peer=gateway msg=${String(err?.message ?? err)}`);
 			this.logger.warn?.(`[coclaw] gateway ws error: ${String(err?.message ?? err)}`);
+			// 防御 ws 库在某些错误下只 emit error 不跟随 close 的情况：主动关闭让 close handler
+			// 接管清理和重试调度，避免 gatewayWs 引用卡在僵尸状态阻塞后续 __ensureGatewayConnection。
+			try { ws.close(1011, 'ws_error'); }
+			/* c8 ignore next */
+			catch {}
 		});
 	}
 
@@ -1049,6 +1168,15 @@ export class RealtimeBridge {
 			clearTimeout(this.reconnectTimer);
 			this.reconnectTimer = null;
 		}
+		// 清理 gateway 重试状态：refresh()（stop+start 同一实例）后应以全新状态启动
+		if (this.__gatewayRetryTimer) {
+			clearTimeout(this.__gatewayRetryTimer);
+			this.__gatewayRetryTimer = null;
+		}
+		this.__gatewayAttempts = 0;
+		this.__gatewayGaveUp = false;
+		this.__gatewayLegacyMode = false;
+		this.__gatewayLastReason = null;
 		this.__closeGatewayWs();
 		if (this.webrtcPeer) {
 			await this.webrtcPeer.closeAll().catch(() => {});

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

@@ -0,0 +1,375 @@
+/**
+ * 文件回退队列：内存优先，超过预算后追加写入 JSONL 文件。
+ * 业务无关纯工具：存储任意字符串（调用方需保证不含裸 `\n`，否则行分隔语义被破坏）。
+ *
+ * 行为约定详见 docs/rpc-dc-file-queue.md。
+ * - FIFO、单一生产者／消费者；多消费者时每条只交付给其中一个。
+ * - 构造时清理目录残留（不跨生命周期复用）。
+ * - 消费侧：`for await (const item of queue) { ... }`；`destroy()` 让迭代结束。
+ */
+
+import fs from 'node:fs/promises';
+import { createReadStream, createWriteStream, rmSync } from 'node:fs';
+import nodePath from 'node:path';
+import readline from 'node:readline';
+
+import { createMutex } from './mutex.js';
+
+const DEFAULT_MEM_BUDGET = 8 * 1024 * 1024;
+const DEFAULT_DISK_CAP = 1024 * 1024 * 1024;
+
+class FileBackedQueue {
+	/**
+	 * @param {object} opts
+	 * @param {string} opts.dir - 队列文件根目录
+	 * @param {string} opts.id - 队列标识（用于子目录命名）
+	 * @param {number} [opts.memBudget=8MB] - 内存持有字节数上限
+	 * @param {number} [opts.diskCap=1GB] - 磁盘+内存总字节数硬上限
+	 * @param {(reason: string, size: number) => void} [opts.onDrop] - 拒入队时的回调
+	 * @param {{ warn?: Function, info?: Function, error?: Function }} [opts.logger=console]
+	 */
+	constructor(opts) {
+		const {
+			dir,
+			id,
+			memBudget = DEFAULT_MEM_BUDGET,
+			diskCap = DEFAULT_DISK_CAP,
+			onDrop,
+			logger = console,
+		} = opts ?? {};
+
+		if (!dir || typeof dir !== 'string') throw new TypeError('dir is required');
+		if (!id || typeof id !== 'string') throw new TypeError('id is required');
+
+		this.dir = dir;
+		this.id = id;
+		this.memBudget = memBudget;
+		this.diskCap = diskCap;
+		this.onDrop = onDrop;
+		this.logger = logger;
+
+		this.subdir = nodePath.join(dir, id);
+		this.filePath = nodePath.join(this.subdir, 'queue.jsonl');
+
+		this.memQueue = [];
+		this.memBytes = 0;
+		this.diskBytes = 0;       // 磁盘上未消费的 payload 字节（不含分隔 \n）
+		this.writtenBytes = 0;    // 已写入文件的累计字节（含 \n）
+		this.readOffset = 0;      // 下次 refill 的起始偏移
+		this.spilled = false;
+		this.destroyed = false;
+		this.writeStream = null;
+		this.writeErr = null;
+		this.waiters = [];
+		this.mutex = createMutex();
+
+		// 防御性清理：不跨生命周期复用旧数据
+		try {
+			rmSync(this.subdir, { recursive: true, force: true });
+		} catch (err) {
+			/* c8 ignore next 2 -- rmSync with force rarely fails on posix */
+			this.logger?.warn?.('fbq.construct cleanup error', err);
+		}
+	}
+
+	/**
+	 * 入队一条字符串。
+	 * @param {string} jsonStr
+	 * @returns {Promise<boolean>} accepted（true）/ dropped（false）
+	 */
+	async enqueue(jsonStr) {
+		return await this.mutex.withLock(async () => {
+			if (this.destroyed) return false;
+			if (typeof jsonStr !== 'string') throw new TypeError('jsonStr must be a string');
+
+			const size = Buffer.byteLength(jsonStr, 'utf8');
+
+			if (this.memBytes + this.diskBytes + size > this.diskCap) {
+				this.__dispatchDrop('disk-cap', size);
+				return false;
+			}
+
+			// 内存路径：未溢出且加上新条目仍在预算内
+			if (!this.spilled && this.memBytes + size <= this.memBudget) {
+				this.memQueue.push(jsonStr);
+				this.memBytes += size;
+				this.__wakeOne();
+				return true;
+			}
+
+			// 溢出路径：lazy 打开写流
+			if (!this.spilled) {
+				await this.__openWriteStream();
+				if (this.writeErr) {
+					this.__dispatchDrop('fs-error', size);
+					return false;
+				}
+				this.spilled = true;
+			}
+
+			try {
+				await this.__writeLine(jsonStr + '\n');
+				this.diskBytes += size;
+				this.writtenBytes += size + 1;
+				this.__wakeOne();
+				return true;
+			} catch (err) {
+				this.logger?.warn?.('fbq.enqueue fs-error', err);
+				this.__dispatchDrop('fs-error', size);
+				return false;
+			}
+		});
+	}
+
+	/**
+	 * @returns {{ memCount: number, memBytes: number, diskBytes: number, spilled: boolean }}
+	 */
+	stats() {
+		return {
+			memCount: this.memQueue.length,
+			memBytes: this.memBytes,
+			diskBytes: this.diskBytes,
+			spilled: this.spilled,
+		};
+	}
+
+	/**
+	 * 清空数据但保留实例可用。
+	 */
+	async clear() {
+		return await this.mutex.withLock(async () => {
+			if (this.destroyed) return;
+			await this.__closeWriteStream();
+			try {
+				await fs.rm(this.filePath, { force: true });
+			} catch (err) {
+				/* c8 ignore next 2 -- rm with force rarely fails */
+				this.logger?.warn?.('fbq.clear rm error', err);
+			}
+			this.memQueue = [];
+			this.memBytes = 0;
+			this.diskBytes = 0;
+			this.writtenBytes = 0;
+			this.readOffset = 0;
+			this.spilled = false;
+			this.writeErr = null;
+		});
+	}
+
+	/**
+	 * 停写、关 FD、删目录、结束所有迭代器。幂等。
+	 */
+	async destroy() {
+		return await this.mutex.withLock(async () => {
+			if (this.destroyed) return;
+			this.destroyed = true;
+
+			// 唤醒所有等待者，让它们在下一轮循环中看到 destroyed 并返回 done
+			const toWake = this.waiters.splice(0);
+			for (const w of toWake) w.resolve();
+
+			await this.__closeWriteStream();
+			try {
+				await fs.rm(this.subdir, { recursive: true, force: true });
+			} catch (err) {
+				/* c8 ignore next 2 -- rm with force rarely fails */
+				this.logger?.warn?.('fbq.destroy rm error', err);
+			}
+
+			this.memQueue = [];
+			this.memBytes = 0;
+			this.diskBytes = 0;
+			this.writtenBytes = 0;
+			this.readOffset = 0;
+			this.spilled = false;
+		});
+	}
+
+	[Symbol.asyncIterator]() {
+		const self = this;
+		return {
+			next() { return self.__nextIter(); },
+			return() { return Promise.resolve({ done: true, value: undefined }); },
+			[Symbol.asyncIterator]() { return this; },
+		};
+	}
+
+	async __nextIter() {
+		while (true) {
+			let waitPromise = null;
+			const result = await this.mutex.withLock(async () => {
+				if (this.memQueue.length === 0 && this.spilled && !this.destroyed) {
+					await this.__refillImpl();
+				}
+				if (this.memQueue.length > 0) {
+					const item = this.memQueue.shift();
+					this.memBytes -= Buffer.byteLength(item, 'utf8');
+					return { value: item, done: false };
+				}
+				if (this.destroyed) return { done: true, value: undefined };
+				waitPromise = new Promise((resolve, reject) => {
+					this.waiters.push({ resolve, reject });
+				});
+				return null;
+			});
+			if (result !== null) return result;
+			await waitPromise;
+		}
+	}
+
+	__wakeOne() {
+		if (this.waiters.length > 0) {
+			const w = this.waiters.shift();
+			w.resolve();
+		}
+	}
+
+	__dispatchDrop(reason, size) {
+		try {
+			this.onDrop?.(reason, size);
+		} catch (err) {
+			/* c8 ignore next 2 -- onDrop throwing is caller's bug */
+			this.logger?.warn?.('fbq.onDrop threw', err);
+		}
+		this.logger?.warn?.('fbq.drop', { reason, size });
+	}
+
+	async __openWriteStream() {
+		this.writeErr = null;
+		try {
+			await fs.mkdir(this.subdir, { recursive: true });
+		} catch (err) {
+			this.writeErr = err;
+			return;
+		}
+		this.writeStream = createWriteStream(this.filePath, { flags: 'a' });
+		this.writeStream.on('error', (err) => {
+			this.writeErr = err;
+			this.logger?.warn?.('fbq.writeStream error', err);
+		});
+	}
+
+	async __writeLine(str) {
+		if (this.writeErr) throw this.writeErr;
+		return await new Promise((resolve, reject) => {
+			this.writeStream.write(str, (err) => {
+				if (err) reject(err);
+				else resolve();
+			});
+		});
+	}
+
+	async __closeWriteStream() {
+		if (!this.writeStream) return;
+		const stream = this.writeStream;
+		this.writeStream = null;
+		if (stream.destroyed || stream.writableEnded) return;
+		// 使用事件而非 end(cb)：errored 流上 end 的回调可能永不触发 → 死锁风险。
+		// 'close' 在正常结束后触发；'error' 在异常流上作为兜底。Promise 幂等。
+		await new Promise((resolve) => {
+			stream.once('close', resolve);
+			stream.once('error', resolve);
+			try {
+				stream.end();
+			/* c8 ignore next 3 -- stream.end 同步抛极少见 */
+			} catch {
+				resolve();
+			}
+		});
+	}
+
+	// 调用方必须已持有 mutex，且已确认 !destroyed
+	async __refillImpl() {
+		if (!this.spilled) return;
+
+		let actualEnd;
+		try {
+			const st = await fs.stat(this.filePath);
+			actualEnd = st.size;
+		} catch (err) {
+			/* c8 ignore next 3 -- stat 在正常持有期间不会失败 */
+			this.logger?.warn?.('fbq.refill stat error', err);
+			return;
+		}
+
+		if (this.readOffset >= actualEnd) {
+			await this.__dropFile();
+			return;
+		}
+
+		const newLines = [];
+		let cumBytes = 0;     // 文件字节：payload + \n
+		let cumPayload = 0;   // 仅 payload
+		let stoppedAtEof = true;
+
+		const stream = createReadStream(this.filePath, {
+			start: this.readOffset,
+			end: actualEnd - 1,
+		});
+		const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
+
+		try {
+			for await (const line of rl) {
+				const sz = Buffer.byteLength(line, 'utf8');
+				if (newLines.length > 0 && this.memBytes + cumPayload + sz > this.memBudget) {
+					stoppedAtEof = false;
+					break;
+				}
+				newLines.push(line);
+				cumBytes += sz + 1;
+				cumPayload += sz;
+			}
+		} catch (err) {
+			/* c8 ignore next 4 -- read 错误罕见，保守退出 */
+			this.logger?.warn?.('fbq.refill read error', err);
+			rl.close();
+			stream.destroy();
+			return;
+		} finally {
+			rl.close();
+			stream.destroy();
+		}
+
+		const availableBytes = actualEnd - this.readOffset;
+
+		if (stoppedAtEof && cumBytes > availableBytes) {
+			// 最后一行未终止（尾部 \n 缺失）：视为半截，丢弃
+			const partial = newLines.pop();
+			cumPayload -= Buffer.byteLength(partial, 'utf8');
+			this.logger?.warn?.('fbq.refill partial tail discarded', {
+				size: Buffer.byteLength(partial, 'utf8'),
+			});
+			// 将 readOffset 推到 writtenBytes，彻底丢弃尾部残片
+			this.readOffset = this.writtenBytes;
+		} else {
+			this.readOffset += cumBytes;
+		}
+
+		for (const line of newLines) {
+			this.memQueue.push(line);
+			this.memBytes += Buffer.byteLength(line, 'utf8');
+		}
+		this.diskBytes -= cumPayload;
+
+		if (this.readOffset >= this.writtenBytes) {
+			await this.__dropFile();
+		}
+	}
+
+	async __dropFile() {
+		await this.__closeWriteStream();
+		try {
+			await fs.rm(this.filePath, { force: true });
+		} catch (err) {
+			/* c8 ignore next 2 -- rm with force rarely fails */
+			this.logger?.warn?.('fbq.dropFile error', err);
+		}
+		this.spilled = false;
+		this.writtenBytes = 0;
+		this.readOffset = 0;
+		this.diskBytes = 0;
+		this.writeErr = null;
+	}
+}
+
+export { FileBackedQueue };

package/src/webrtc/webrtc-peer.js

@@ -252,7 +252,14 @@ export class WebRtcPeer {
 		const turnUrl = iceServers.find((s) => s.urls?.startsWith('turn:'))?.urls ?? 'none';
 		this.__remoteLog(`rtc.ice-config conn=${connId} stun=${stunUrl} turn=${turnUrl}`);
 
-		const pc = new this.__PeerConnection({ iceServers });
+		// settings 仅对 pion 生效：werift 路径不吃 settings 字段（大概率静默忽略，
+		// 但按 __impl 分层更干净）。只收紧 pion 的 SCTP RTO 退避上限到 10s，
+		// 让 APK 后台唤醒后的深度退避窗口能落在 UI 的 15s 超时内。
+		const pcConfig = { iceServers };
+		if (this.__impl === 'pion') {
+			pcConfig.settings = { sctpRtoMax: 10000 };
+		}
+		const pc = new this.__PeerConnection(pcConfig);
 
 		const remoteMaxMessageSize = this.__resolveMaxMessageSize(pc, msg.payload.sdp);
 
@@ -569,16 +576,57 @@ export class WebRtcPeer {
 	 */
 	__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(',');
+		const fileSummary = this.__summarizeFileChannels(session.fileChannels);
 		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}`);
+		// 仅 pion 路径追加 SCTP 采样：cwnd 是否塌回 1×MTU + bytesSent 增量是否 ~0
+		// 是判定"是否陷入深度 RTO 退避"的关键。fire-and-forget + 内部 try/catch
+		// 双保险，不阻塞 dump 主流程；rtc.sctp 独立一行避免污染既有 rtc.dump 格式。
+		if (this.__impl === 'pion' && typeof session.pc.getSctpStats === 'function') {
+			this.__dumpSctpStats(connId, session, state).catch(() => {});
+		}
+	}
+
+	/**
+	 * 按 readyState 聚合 file DC。closed 态只给计数，非 closed 态附带 label —
+	 * 长会话内已关闭的 DC 会累积到 FIFO 上限，全量拼 label 会让 dump 膨胀，
+	 * 而断连时真正有诊断价值的是"还没关干净"的 DC。
+	 */
+	__summarizeFileChannels(fileChannels) {
+		if (fileChannels.size === 0) return 'none';
+		const byState = new Map();
+		for (const dc of fileChannels) {
+			/* c8 ignore next -- ?? fallback for missing readyState */
+			const st = dc.readyState ?? '?';
+			if (!byState.has(st)) byState.set(st, []);
+			byState.get(st).push(dc.label);
+		}
+		const parts = [];
+		for (const [st, labels] of byState) {
+			if (st === 'closed') parts.push(`closed:${labels.length}`);
+			else parts.push(`${st}:${labels.length}(${labels.join(',')})`);
+		}
+		return parts.join(' ');
+	}
+
+	async __dumpSctpStats(connId, session, state) {
+		try {
+			const stats = await session.pc.getSctpStats();
+			if (!stats) {
+				this.__remoteLog(`rtc.sctp conn=${connId} state=${state} sctp=none`);
+				return;
+			}
+			this.__remoteLog(
+				`rtc.sctp conn=${connId} state=${state} cwnd=${stats.congestionWindow} srtt=${Math.round(stats.srttMs)}ms sent=${stats.bytesSent} recv=${stats.bytesReceived} mtu=${stats.mtu}`,
+			);
+		} catch (err) {
+			this.__remoteLog(`rtc.sctp conn=${connId} state=${state} error=${err.message}`);
+			this.logger.warn?.(`${this.__rtcTag} [${connId}] getSctpStats error: ${err.message}`);
+		}
 	}
 
 	/**

package/src/homedir-mock.helper.js

@@ -1,47 +0,0 @@
-/**
- * 跨平台 mock os.homedir()
- *
- * Node.js os.homedir() 在不同平台读取不同环境变量：
- * - POSIX: HOME
- * - Windows: USERPROFILE（优先）、HOMEDRIVE+HOMEPATH
- *
- * 测试中需同时设置两端变量，确保 os.homedir() 返回期望路径。
- */
-
-const HOME_VARS = ['HOME', 'USERPROFILE'];
-
-/**
- * 保存当前 home 相关环境变量
- * @returns {Record<string, string | undefined>}
- */
-export function saveHomedir() {
-	const saved = {};
-	for (const key of HOME_VARS) {
-		saved[key] = process.env[key];
-	}
-	return saved;
-}
-
-/**
- * 将 home 相关环境变量统一设置为指定路径
- * @param {string} dir - 目标路径
- */
-export function setHomedir(dir) {
-	for (const key of HOME_VARS) {
-		process.env[key] = dir;
-	}
-}
-
-/**
- * 恢复之前保存的 home 相关环境变量
- * @param {Record<string, string | undefined>} saved
- */
-export function restoreHomedir(saved) {
-	for (const key of HOME_VARS) {
-		if (saved[key] === undefined) {
-			delete process.env[key];
-		} else {
-			process.env[key] = saved[key];
-		}
-	}
-}