@coclaw/openclaw-coclaw 0.17.2 → 0.17.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coclaw/openclaw-coclaw",
-  "version": "0.17.2",
+  "version": "0.17.4",
   "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"
   ],

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

@@ -1,134 +1,199 @@
 /**
  * worker-verify.js — 升级后验证
  *
- * 三步验证策略（任一失败即判定升级失败）：
- * 1. Gateway 存活：轮询 `openclaw gateway status`，超时 60s
- * 2. 插件已加载：`openclaw plugins list` 包含指定插件
- * 3. 升级模块健康：`openclaw gateway call coclaw.upgradeHealth` 返回版本号
+ * 策略：触发 gateway restart → 轮询 coclaw.upgradeHealth RPC 直到返回版本
+ * 严格等于 toVersion。单次调用失败（gateway 未就绪 / plugin 未注册 / JSON 非法 /
+ * 版本不对）一律按"稍后重试"处理，在总超时窗口内持续尝试。
  *
- * 第 3 步同时验证了插件代码能正常执行、gateway method 注册链路正常，
- * 确保插件仍具备自我升级能力。
+ * 磁盘 package.json 的版本仅作为诊断写入本地日志，不参与判定——openclaw 侧
+ * `plugins.installs[id].installPath` 可能在 id-migration 等极端场景发生漂移，
+ * 而 upgradeHealth 是 gateway 进程内"新代码真的被加载"的权威信号。
+ *
+ * worker 运行在独立子进程中，禁止使用 remoteLog；诊断信息全部通过 logger
+ * （本地日志）输出，由 updater 记录到 upgrade-log.jsonl。
  */
 import { execFile as nodeExecFile } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import nodePath from 'node:path';
 
-const GATEWAY_READY_TIMEOUT_MS = 60_000;
-const POLL_INTERVAL_MS = 2000;
 const CMD_TIMEOUT_MS = 30_000;
+const HEALTH_POLL_INTERVAL_MS = 3_000;
+// 本机 openclaw 冷启动可能需访问外部资源（AWS 诊断、ollama 探测等）
+// 及插件 bootstrap，合计 30~60s 常见；5 分钟给足余量
+const HEALTH_TOTAL_TIMEOUT_MS = 5 * 60 * 1000;
 
 /**
- * 执行命令并返回 stdout
+ * 执行命令并返回 stdout；错误对象附带 stderr 以便诊断
  * @param {string} cmd
  * @param {string[]} args
  * @param {object} [opts]
  * @param {Function} [opts.execFileFn]
+ * @param {number} [opts.cmdTimeoutMs]
  * @returns {Promise<string>}
  */
 function runCmd(cmd, args, opts) {
 	/* c8 ignore next -- ?./?? fallback */
 	const doExecFile = opts?.execFileFn ?? nodeExecFile;
+	/* c8 ignore next -- ?./?? fallback */
+	const timeout = opts?.cmdTimeoutMs ?? CMD_TIMEOUT_MS;
 	return new Promise((resolve, reject) => {
-		doExecFile(cmd, args, { timeout: CMD_TIMEOUT_MS, shell: process.platform === 'win32' }, (err, stdout) => {
-			if (err) reject(err);
+		doExecFile(cmd, args, { timeout, shell: process.platform === 'win32' }, (err, stdout, stderr) => {
+			if (err) {
+				/* c8 ignore next -- ?? fallback：execFile 实现不保证 stderr 一定字符串化 */
+				err.stderr = String(stderr ?? '');
+				reject(err);
+			}
 			else resolve(String(stdout).trim());
 		});
 	});
 }
 
 /**
- * 步骤 1：等待 gateway 恢复运行
+ * 触发一次 gateway 重启；失败不抛（后续轮询 RPC 会兜底验证 gateway 是否就绪）
  * @param {object} [opts]
  * @param {Function} [opts.execFileFn]
- * @param {number} [opts.timeoutMs]
- * @param {number} [opts.pollIntervalMs]
  * @returns {Promise<void>}
  */
-export async function waitForGateway(opts) {
-	// 主动触发重启，不依赖 OpenClaw 的文件变更自动重启策略
+export async function triggerGatewayRestart(opts) {
 	try {
 		await runCmd('openclaw', ['gateway', 'restart'], opts);
 	}
 	catch {
-		// restart 命令失败不阻断流程，仍尝试等待
-	}
-
-	/* c8 ignore next 2 -- ?./?? fallback */
-	const timeout = opts?.timeoutMs ?? GATEWAY_READY_TIMEOUT_MS;
-	const interval = opts?.pollIntervalMs ?? POLL_INTERVAL_MS;
-	const start = Date.now();
-
-	while (Date.now() - start < timeout) {
-		try {
-			const output = await runCmd('openclaw', ['gateway', 'status'], opts);
-			if (output.includes('running')) return;
-		}
-		catch {
-			// gateway 未就绪，继续轮询
-		}
-		await sleep(interval);
+		// restart 命令本身失败不阻断：openclaw 可能已在重启/daemon 自恢复；
+		// 无论如何都进入后续 upgradeHealth 轮询，由它判定 gateway 最终是否可用
 	}
-
-	throw new Error('Gateway did not become ready within timeout');
 }
 
 /**
- * 步骤 2：验证插件已加载
- * @param {string} pluginId - 插件 ID
- * @param {object} [opts]
- * @param {Function} [opts.execFileFn]
- * @returns {Promise<void>}
+ * 读取磁盘 package.json 的版本号（诊断用途，不参与判定）
+ * @param {string} pluginDir
+ * @returns {Promise<string | null>}
  */
-export async function verifyPluginLoaded(pluginId, opts) {
-	const output = await runCmd('openclaw', ['plugins', 'list'], opts);
-	if (!output.includes(pluginId)) {
-		throw new Error(`Plugin ${pluginId} not found in plugins list`);
+export async function readDiskPackageVersion(pluginDir) {
+	try {
+		const pkgPath = nodePath.join(pluginDir, 'package.json');
+		const raw = await readFile(pkgPath, 'utf8');
+		const pkg = JSON.parse(raw);
+		return typeof pkg?.version === 'string' ? pkg.version : null;
+	}
+	catch {
+		return null;
 	}
 }
 
 /**
- * 步骤 3：验证升级模块健康
+ * 单次调用 coclaw.upgradeHealth；永不抛异常，失败归一化为 { ok: false, reason }
  * @param {object} [opts]
- * @param {Function} [opts.execFileFn]
- * @returns {Promise<string>} 返回版本号
+ * @returns {Promise<{ ok: true, version: string } | { ok: false, reason: string }>}
  */
-export async function verifyUpgradeHealth(opts) {
-	const output = await runCmd(
-		'openclaw',
-		['gateway', 'call', 'coclaw.upgradeHealth', '--json'],
-		opts,
-	);
+async function callUpgradeHealthOnce(opts) {
 	try {
-		const result = JSON.parse(output);
-		if (!result.version) {
-			throw new Error('upgradeHealth response missing version');
+		const output = await runCmd(
+			'openclaw',
+			['gateway', 'call', 'coclaw.upgradeHealth', '--json'],
+			opts,
+		);
+		let payload;
+		try {
+			payload = JSON.parse(output);
 		}
-		return result.version;
+		catch {
+			return { ok: false, reason: `invalid-json: ${output.slice(0, 120)}` };
+		}
+		if (!payload?.version) return { ok: false, reason: 'missing-version' };
+		return { ok: true, version: String(payload.version) };
 	}
 	catch (err) {
-		if (err.message?.includes('upgradeHealth')) throw err;
-		throw new Error(`Failed to parse upgradeHealth response: ${output}`);
+		const stderr = typeof err?.stderr === 'string' ? err.stderr.trim() : '';
+		/* c8 ignore next -- ?? fallback */
+		const msg = err?.message ?? String(err);
+		const reason = (stderr || msg || 'unknown').slice(0, 200);
+		return { ok: false, reason };
 	}
 }
 
 /**
- * 执行完整验证流程
- * @param {string} pluginId - 插件 ID
+ * 轮询 upgradeHealth 直到版本严格等于 toVersion，或总超时
+ * @param {string} toVersion
  * @param {object} [opts]
  * @param {Function} [opts.execFileFn]
- * @param {number} [opts.timeoutMs]
+ * @param {number} [opts.totalTimeoutMs]
  * @param {number} [opts.pollIntervalMs]
- * @returns {Promise<{ ok: boolean, version?: string, error?: string }>}
+ * @param {number} [opts.cmdTimeoutMs]
+ * @returns {Promise<{ ok: true, version: string, attempts: number, elapsedMs: number }
+ *   | { ok: false, attempts: number, elapsedMs: number, lastReason: string, lastVersion: string }>}
  */
-export async function verifyUpgrade(pluginId, opts) {
-	try {
-		await waitForGateway(opts);
-		await verifyPluginLoaded(pluginId, opts);
-		const version = await verifyUpgradeHealth(opts);
-		return { ok: true, version };
+export async function pollUpgradeHealth(toVersion, opts) {
+	/* c8 ignore next -- ?? fallback */
+	const totalTimeout = opts?.totalTimeoutMs ?? HEALTH_TOTAL_TIMEOUT_MS;
+	/* c8 ignore next -- ?? fallback */
+	const pollInterval = opts?.pollIntervalMs ?? HEALTH_POLL_INTERVAL_MS;
+	const start = Date.now();
+	let attempts = 0;
+	let lastReason = '';
+	let lastVersion = '';
+
+	while (Date.now() - start < totalTimeout) {
+		attempts += 1;
+		const result = await callUpgradeHealthOnce(opts);
+		if (result.ok) {
+			if (result.version === toVersion) {
+				return {
+					ok: true,
+					version: result.version,
+					attempts,
+					elapsedMs: Date.now() - start,
+				};
+			}
+			lastVersion = result.version;
+			lastReason = `version-mismatch got=${result.version} want=${toVersion}`;
+		}
+		else {
+			lastReason = result.reason;
+		}
+		// 剩余时间不足以再等一个 interval 就直接退出，避免最后一次毫无意义的 sleep
+		if (Date.now() - start + pollInterval >= totalTimeout) break;
+		await sleep(pollInterval);
 	}
-	catch (err) {
-		/* c8 ignore next -- ?./?? fallback */
-		return { ok: false, error: String(err?.message ?? err) };
+
+	return {
+		ok: false,
+		attempts,
+		elapsedMs: Date.now() - start,
+		lastReason,
+		lastVersion,
+	};
+}
+
+/**
+ * 完整验证流程：触发 gateway restart → 读磁盘版本（诊断）→ 轮询 upgradeHealth
+ * @param {string} pluginDir - 插件安装目录（来自 openclaw.json 的权威 installPath）
+ * @param {string} toVersion - 目标版本
+ * @param {object} [opts]
+ * @param {Function} [opts.execFileFn]
+ * @param {number} [opts.totalTimeoutMs]
+ * @param {number} [opts.pollIntervalMs]
+ * @param {number} [opts.cmdTimeoutMs]
+ * @param {Function} [log] - 本地日志函数
+ * @returns {Promise<{ ok: true, version: string } | { ok: false, error: string }>}
+ */
+export async function verifyUpgrade(pluginDir, toVersion, opts, log) {
+	const logFn = typeof log === 'function' ? log : () => {};
+
+	await triggerGatewayRestart(opts);
+
+	const onDiskVersion = await readDiskPackageVersion(pluginDir);
+	logFn(`[upgrade-worker] On-disk package.json version: ${onDiskVersion ?? '(unreadable)'} (expected ${toVersion})`);
+
+	const result = await pollUpgradeHealth(toVersion, opts);
+	if (result.ok) {
+		logFn(`[upgrade-worker] upgradeHealth verified: version=${result.version} attempts=${result.attempts} elapsed=${result.elapsedMs}ms`);
+		return { ok: true, version: result.version };
 	}
+
+	const error = `verify timeout: attempts=${result.attempts} elapsed=${result.elapsedMs}ms lastVersion=${result.lastVersion || '(none)'} lastReason=${result.lastReason || '(none)'}`;
+	logFn(`[upgrade-worker] ${error}`);
+	return { ok: false, error };
 }
 
 function sleep(ms) {

package/src/auto-upgrade/worker.js

@@ -15,7 +15,7 @@
 import { execFile as nodeExecFile } from 'node:child_process';
 import { parseArgs } from 'node:util';
 import { createBackup, restoreFromBackup, removeBackup } from './worker-backup.js';
-import { verifyUpgrade, waitForGateway } from './worker-verify.js';
+import { verifyUpgrade, triggerGatewayRestart } from './worker-verify.js';
 import { addSkippedVersion, updateLastUpgrade, appendLog } from './state.js';
 import { getCurrentNpmRegistry, pickFallbackRegistry } from './registry-fallback.js';
 
@@ -160,7 +160,7 @@ export async function runUpgrade({ pluginDir, fromVersion, toVersion, pluginId,
 
 	// 3. 等待 gateway 重启并验证
 	log('[upgrade-worker] Verifying upgrade...');
-	const result = await verifyUpgrade(pluginId, opts);
+	const result = await verifyUpgrade(pluginDir, toVersion, opts, log);
 
 	if (result.ok) {
 		// 4a. 成功
@@ -212,15 +212,9 @@ async function handleRollback({ pluginDir, fromVersion, toVersion, pluginId, pkg
 		}
 	}
 
-	// 等待 gateway 重启
-	log('[upgrade-worker] Waiting for gateway to restart after rollback...');
-	try {
-		await waitForGateway(opts);
-		log('[upgrade-worker] Gateway restarted after rollback');
-	}
-	catch {
-		log('[upgrade-worker] Gateway did not restart after rollback');
-	}
+	// 触发 gateway 重启让老版本回到运行态（尽力而为，不验证结果）
+	log('[upgrade-worker] Triggering gateway restart after rollback...');
+	await triggerGatewayRestart(opts);
 
 	// 记录状态（顺序执行因共享 state 文件，但各自 try/catch 避免单个失败阻断其余）
 	// 仅验证失败（新版本确实被加载并发现有问题）才标记为 skipped；

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

@@ -4,12 +4,13 @@
  *
  * 行为约定详见 docs/rpc-dc-file-queue.md。
  * - FIFO、单一生产者／消费者；多消费者时每条只交付给其中一个。
- * - 构造时清理目录残留（不跨生命周期复用）。
+ * - 构造纯字段初始化，不碰 FS；使用前需 `await q.init()`。
  * - 消费侧：`for await (const item of queue) { ... }`；`destroy()` 让迭代结束。
+ * - FS 异常下进入 `fsBroken` 粘性降级：mem 路径继续工作，溢出消息 drop。
  */
 
 import fs from 'node:fs/promises';
-import { createReadStream, createWriteStream, rmSync } from 'node:fs';
+import { createReadStream, createWriteStream } from 'node:fs';
 import nodePath from 'node:path';
 import readline from 'node:readline';
 
@@ -18,13 +19,22 @@ import { createMutex } from './mutex.js';
 const DEFAULT_MEM_BUDGET = 8 * 1024 * 1024;
 const DEFAULT_DISK_CAP = 1024 * 1024 * 1024;
 
+// JS 对象开销估算（string header + array slot 等），仅用于 admission 决策不影响 memBytes 报告
+const ENTRY_OVERHEAD = 64;
+
+// id 字符集：UUID / 字母数字 / 点 / 下划线 / 减号，且不能是 "." 或 ".."
+const ID_RE = /^[A-Za-z0-9._-]+$/;
+
+// 压缩阈值：head 越过 64 且占 memQueue 一半以上时切片回收
+const COMPACT_HEAD_THRESHOLD = 64;
+
 class FileBackedQueue {
 	/**
 	 * @param {object} opts
 	 * @param {string} opts.dir - 队列文件根目录
-	 * @param {string} opts.id - 队列标识（用于子目录命名）
+	 * @param {string} opts.id - 队列标识，字符集受限，防路径穿越
 	 * @param {number} [opts.memBudget=8MB] - 内存持有字节数上限
-	 * @param {number} [opts.diskCap=1GB] - 磁盘+内存总字节数硬上限
+	 * @param {number} [opts.diskCap=1GB] - 磁盘+内存总字节数硬上限（含 `\n`）
 	 * @param {(reason: string, size: number) => void} [opts.onDrop] - 拒入队时的回调
 	 * @param {{ warn?: Function, info?: Function, error?: Function }} [opts.logger=console]
 	 */
@@ -40,6 +50,17 @@ class FileBackedQueue {
 
 		if (!dir || typeof dir !== 'string') throw new TypeError('dir is required');
 		if (!id || typeof id !== 'string') throw new TypeError('id is required');
+		if (id === '.' || id === '..' || !ID_RE.test(id)) {
+			throw new TypeError('id contains invalid characters');
+		}
+		// 基础设施 fail-fast：容量参数必须是有限正数，避免 NaN/Infinity/非数字绕过 admission。
+		// NaN 与任何数比较皆为 false → admission 永远通过 → diskCap 变相失效。
+		if (!Number.isFinite(memBudget) || memBudget <= 0) {
+			throw new TypeError('memBudget must be a finite positive number');
+		}
+		if (!Number.isFinite(diskCap) || diskCap <= 0) {
+			throw new TypeError('diskCap must be a finite positive number');
+		}
 
 		this.dir = dir;
 		this.id = id;
@@ -48,28 +69,52 @@ class FileBackedQueue {
 		this.onDrop = onDrop;
 		this.logger = logger;
 
-		this.subdir = nodePath.join(dir, id);
-		this.filePath = nodePath.join(this.subdir, 'queue.jsonl');
+		this.filePath = nodePath.join(dir, `${id}.jsonl`);
 
+		// 单文件 ring-ish 结构：head 指针 + 数组；shift 为 O(1) 摊销
 		this.memQueue = [];
+		this.head = 0;
 		this.memBytes = 0;
-		this.diskBytes = 0;       // 磁盘上未消费的 payload 字节（不含分隔 \n）
 		this.writtenBytes = 0;    // 已写入文件的累计字节（含 \n）
 		this.readOffset = 0;      // 下次 refill 的起始偏移
 		this.spilled = false;
+		this.initialized = false;
 		this.destroyed = false;
+		this.fsBroken = false;    // 粘性：一旦 FS 出错，不再尝试 reopen
 		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);
-		}
+	/**
+	 * 派生的未消费磁盘字节数（含 \n），用于 admission 与 stats。
+	 */
+	get diskBytes() {
+		return this.writtenBytes - this.readOffset;
+	}
+
+	/**
+	 * 异步初始化：清理残留文件，标记可用。幂等。
+	 */
+	async init() {
+		return await this.mutex.withLock(async () => {
+			if (this.destroyed) return;
+			if (this.initialized) return;
+			try {
+				await fs.rm(this.filePath, { force: true });
+			} catch (err) {
+				// best-effort：init 的 rm 可能因 ENOTDIR / EACCES 等失败。
+				// 权威残留清理在 __openWriteStream 中（首次 spill 前）再做一次，
+				// 确保不会用 'a' flag 追加到旧数据上污染 FIFO。
+				this.logger?.warn?.('fbq.init rm warning', err);
+			}
+			this.initialized = true;
+		});
+	}
+
+	async [Symbol.asyncDispose]() {
+		await this.destroy();
 	}
 
 	/**
@@ -80,28 +125,45 @@ class FileBackedQueue {
 	async enqueue(jsonStr) {
 		return await this.mutex.withLock(async () => {
 			if (this.destroyed) return false;
+			if (!this.initialized) throw new TypeError('queue not initialized');
 			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) {
+			// admission：按物理占用（mem + 已写文件总字节，含 \n）判定，保证 diskCap 是真正的硬上限。
+			// 用 writtenBytes（不减 readOffset）的含义：文件前缀已读但未被 __dropFile 回收前仍算占用。
+			// 代价：持续背压下消费者还没追到写端时新消息可能被 drop，直到完全 drain 触发 __dropFile 重置。
+			if (this.memBytes + this.writtenBytes + size + 1 > 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;
+			// 内存路径：未溢出且 admission 通过（考虑 overhead；首条无论多大都收）
+			if (!this.spilled) {
+				const pendingCount = this.memQueue.length - this.head;
+				const cost = this.memBytes + pendingCount * ENTRY_OVERHEAD + size + ENTRY_OVERHEAD;
+				if (pendingCount === 0 || cost <= this.memBudget) {
+					this.memQueue.push(jsonStr);
+					this.memBytes += size;
+					this.__wakeOne();
+					return true;
+				}
+			}
+
+			// 溢出路径：FS 已破直接 drop，不再尝试 reopen
+			if (this.fsBroken) {
+				this.__dispatchDrop('fs-error', size);
+				return false;
 			}
 
-			// 溢出路径：lazy 打开写流
 			if (!this.spilled) {
 				await this.__openWriteStream();
 				if (this.writeErr) {
+					const err = this.writeErr;
 					this.__dispatchDrop('fs-error', size);
+					// 前置 mkdir/rm 失败也进入粘性降级：与 stream 'error' 路径语义一致，
+					// 避免后续每次 overflow 都重试同一个持续性 FS 故障。
+					await this.__handleFsError(err);
 					return false;
 				}
 				this.spilled = true;
@@ -109,32 +171,39 @@ class FileBackedQueue {
 
 			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);
+				// 直接在当前锁内触发粘性降级：真实 Node stream 下 cb err 通常也会 emit 'error'
+				// （监听器会另外排一次 handleFsError，但 fsBroken 已置 → no-op）；测试里的 monkey-patch
+				// 只触发 cb、不发 'error'，这里主动降级保证行为一致。
+				await this.__handleFsError(err);
 				return false;
 			}
 		});
 	}
 
 	/**
-	 * @returns {{ memCount: number, memBytes: number, diskBytes: number, spilled: boolean }}
+	 * @returns {{ memCount: number, memBytes: number, diskBytes: number, writtenBytes: number, spilled: boolean, fsBroken: boolean }}
+	 *   - diskBytes：未消费 backlog（writtenBytes - readOffset）
+	 *   - writtenBytes：本次生命周期累计已写字节（admission 依据的物理占用），drain 或 FS 降级后重置为 0
 	 */
 	stats() {
 		return {
-			memCount: this.memQueue.length,
+			memCount: this.memQueue.length - this.head,
 			memBytes: this.memBytes,
 			diskBytes: this.diskBytes,
+			writtenBytes: this.writtenBytes,
 			spilled: this.spilled,
+			fsBroken: this.fsBroken,
 		};
 	}
 
 	/**
-	 * 清空数据但保留实例可用。
+	 * 清空数据但保留实例可用；显式清 fsBroken，允许再次尝试落盘。
 	 */
 	async clear() {
 		return await this.mutex.withLock(async () => {
@@ -147,17 +216,18 @@ class FileBackedQueue {
 				this.logger?.warn?.('fbq.clear rm error', err);
 			}
 			this.memQueue = [];
+			this.head = 0;
 			this.memBytes = 0;
-			this.diskBytes = 0;
 			this.writtenBytes = 0;
 			this.readOffset = 0;
 			this.spilled = false;
+			this.fsBroken = false;
 			this.writeErr = null;
 		});
 	}
 
 	/**
-	 * 停写、关 FD、删目录、结束所有迭代器。幂等。
+	 * 停写、关 FD、删文件、结束所有迭代器。幂等。
 	 */
 	async destroy() {
 		return await this.mutex.withLock(async () => {
@@ -170,15 +240,15 @@ class FileBackedQueue {
 
 			await this.__closeWriteStream();
 			try {
-				await fs.rm(this.subdir, { recursive: true, force: true });
+				await fs.rm(this.filePath, { force: true });
 			} catch (err) {
 				/* c8 ignore next 2 -- rm with force rarely fails */
 				this.logger?.warn?.('fbq.destroy rm error', err);
 			}
 
 			this.memQueue = [];
+			this.head = 0;
 			this.memBytes = 0;
-			this.diskBytes = 0;
 			this.writtenBytes = 0;
 			this.readOffset = 0;
 			this.spilled = false;
@@ -198,12 +268,20 @@ class FileBackedQueue {
 		while (true) {
 			let waitPromise = null;
 			const result = await this.mutex.withLock(async () => {
-				if (this.memQueue.length === 0 && this.spilled && !this.destroyed) {
+				const pendingCount = this.memQueue.length - this.head;
+				if (pendingCount === 0 && this.spilled && !this.destroyed) {
 					await this.__refillImpl();
 				}
-				if (this.memQueue.length > 0) {
-					const item = this.memQueue.shift();
+				if (this.memQueue.length - this.head > 0) {
+					const item = this.memQueue[this.head];
+					this.memQueue[this.head] = undefined;
+					this.head += 1;
 					this.memBytes -= Buffer.byteLength(item, 'utf8');
+					// 惰性压缩：避免 head 一直向前、数组永不回收
+					if (this.head > COMPACT_HEAD_THRESHOLD && this.head * 2 >= this.memQueue.length) {
+						this.memQueue = this.memQueue.slice(this.head);
+						this.head = 0;
+					}
 					return { value: item, done: false };
 				}
 				if (this.destroyed) return { done: true, value: undefined };
@@ -224,6 +302,11 @@ class FileBackedQueue {
 		}
 	}
 
+	__wakeAll() {
+		const toWake = this.waiters.splice(0);
+		for (const w of toWake) w.resolve();
+	}
+
 	__dispatchDrop(reason, size) {
 		try {
 			this.onDrop?.(reason, size);
@@ -237,20 +320,32 @@ class FileBackedQueue {
 	async __openWriteStream() {
 		this.writeErr = null;
 		try {
-			await fs.mkdir(this.subdir, { recursive: true });
+			// 目录 0o700 / 文件 0o600：POSIX best-effort。
+			// - 新建目录/文件会按此 mode（再经 umask）创建
+			// - 已存在的目录 mkdir(recursive) 不会被 chmod 收紧，以该目录原权限为准
+			// - Windows 下 mode 参数语义很弱（无 owner/group/other 概念），实际访问控制依赖父目录 NTFS ACL
+			// 仍比默认 0o644 更保守；atomic-write.js 也是同一策略。
+			await fs.mkdir(nodePath.dirname(this.filePath), { recursive: true, mode: 0o700 });
+			// 权威残留清理：即便 init 的 rm 被吞掉，这里开流前再 rm 一次，
+			// 避免 'a' flag 追加到旧数据上污染 FIFO。
+			await fs.rm(this.filePath, { force: true });
 		} catch (err) {
 			this.writeErr = err;
 			return;
 		}
-		this.writeStream = createWriteStream(this.filePath, { flags: 'a' });
+		this.writeStream = createWriteStream(this.filePath, { flags: 'a', mode: 0o600 });
 		this.writeStream.on('error', (err) => {
 			this.writeErr = err;
 			this.logger?.warn?.('fbq.writeStream error', err);
+			// 异步错误：排队到 mutex 做粘性降级清理，避免状态半截卡死
+			this.mutex.withLock(() => this.__handleFsError(err)).catch(() => {});
 		});
 	}
 
 	async __writeLine(str) {
-		if (this.writeErr) throw this.writeErr;
+		// 不再前置 writeErr 检查：一旦 writeErr 被异步设置，__handleFsError 会立即排队清理并
+		// 把 fsBroken 置粘性；spill 路径入口已判 fsBroken，到这里 writeErr 必为 null。
+		// 写失败通过 write 回调的 err 反映，catch 块处理。
 		return await new Promise((resolve, reject) => {
 			this.writeStream.write(str, (err) => {
 				if (err) reject(err);
@@ -278,6 +373,25 @@ class FileBackedQueue {
 		});
 	}
 
+	// mutex 内调用：FS 错误粘性降级
+	async __handleFsError(_err) {
+		if (this.destroyed || this.fsBroken) return;
+		this.fsBroken = true;
+		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.handleFsError rm error', err);
+		}
+		this.spilled = false;
+		this.writtenBytes = 0;
+		this.readOffset = 0;
+		this.writeErr = null;
+		// 唤醒全部消费者，让它们重新观察状态
+		this.__wakeAll();
+	}
+
 	// 调用方必须已持有 mutex，且已确认 !destroyed
 	async __refillImpl() {
 		if (!this.spilled) return;
@@ -287,8 +401,10 @@ class FileBackedQueue {
 			const st = await fs.stat(this.filePath);
 			actualEnd = st.size;
 		} catch (err) {
-			/* c8 ignore next 3 -- stat 在正常持有期间不会失败 */
+			// 读侧 FS 错误（外部删文件、权限丢失等）走粘性降级，
+			// 避免 spilled=true / fsBroken=false 的悬空态让消费者永远挂 waiter。
 			this.logger?.warn?.('fbq.refill stat error', err);
+			await this.__handleFsError(err);
 			return;
 		}
 
@@ -302,6 +418,9 @@ class FileBackedQueue {
 		let cumPayload = 0;   // 仅 payload
 		let stoppedAtEof = true;
 
+		const pendingCount = this.memQueue.length - this.head;
+		const baseCost = this.memBytes + pendingCount * ENTRY_OVERHEAD;
+
 		const stream = createReadStream(this.filePath, {
 			start: this.readOffset,
 			end: actualEnd - 1,
@@ -311,7 +430,9 @@ class FileBackedQueue {
 		try {
 			for await (const line of rl) {
 				const sz = Buffer.byteLength(line, 'utf8');
-				if (newLines.length > 0 && this.memBytes + cumPayload + sz > this.memBudget) {
+				// overhead 一致性：admission 侧已用 overhead，refill 侧同步考虑
+				const newLinesCost = newLines.length * ENTRY_OVERHEAD;
+				if (newLines.length > 0 && baseCost + cumPayload + newLinesCost + sz + ENTRY_OVERHEAD > this.memBudget) {
 					stoppedAtEof = false;
 					break;
 				}
@@ -320,10 +441,12 @@ class FileBackedQueue {
 				cumPayload += sz;
 			}
 		} catch (err) {
-			/* c8 ignore next 4 -- read 错误罕见，保守退出 */
+			/* c8 ignore next 6 -- read 错误极罕见（stat 已通过、fd 已打开），路径保留用于粘性降级 */
+			// read 错误同 stat：统一走粘性降级而非静默 return
 			this.logger?.warn?.('fbq.refill read error', err);
 			rl.close();
 			stream.destroy();
+			await this.__handleFsError(err);
 			return;
 		} finally {
 			rl.close();
@@ -349,7 +472,6 @@ class FileBackedQueue {
 			this.memQueue.push(line);
 			this.memBytes += Buffer.byteLength(line, 'utf8');
 		}
-		this.diskBytes -= cumPayload;
 
 		if (this.readOffset >= this.writtenBytes) {
 			await this.__dropFile();
@@ -367,7 +489,6 @@ class FileBackedQueue {
 		this.spilled = false;
 		this.writtenBytes = 0;
 		this.readOffset = 0;
-		this.diskBytes = 0;
 		this.writeErr = null;
 	}
 }

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];
-		}
-	}
-}