@coclaw/openclaw-coclaw 0.17.3 → 0.17.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coclaw/openclaw-coclaw",
-  "version": "0.17.3",
+  "version": "0.17.5",
   "type": "module",
   "license": "Apache-2.0",
   "description": "OpenClaw CoClaw channel plugin for remote chat",

package/src/auto-upgrade/updater.js

@@ -14,6 +14,15 @@ const INITIAL_DELAY_MS = 60 * 60 * 1000; // 60 分钟
 const CHECK_INTERVAL_MS = 60 * 60 * 1000; // 1 小时
 const CHANNEL_ID = 'coclaw';
 const LOCK_FILENAME = 'upgrade.lock';
+// 锁年龄兜底：worker 最坏耗时约 36 分钟，TTL 给到约 3 倍余量。
+// 超龄一律视为过期清理，兜住 worker 被强杀未清锁 / PID 被 OS 复用给长命进程的场景，
+// 避免自动升级被永久卡住。
+// 刻意取 110 分钟而非 120 分钟：巡检间隔 60min，锁写入与巡检有秒级抖动；
+// 若 TTL 正好等于巡检间隔的整数倍，锁年龄会在第 N 次巡检时刚好 "未过期"，
+// 要等到第 N+1 次巡检才清，白白多浪费一轮。110min 保证第 2 次巡检即过期。
+// 代价是 worker 真卡超 110 分钟会多起一个并行 worker，此概率在当前超时矩阵下极低，
+// 且底层升级命令失败会走回滚，不会破坏插件。
+const LOCK_TTL_MS = 110 * 60 * 1000; // 110 分钟
 
 // ── upgrade.lock：保证同时最多一个 worker 进程 ──
 
@@ -21,10 +30,34 @@ export function getLockPath() {
 	return nodePath.join(resolveStateDir(), CHANNEL_ID, LOCK_FILENAME);
 }
 
+/**
+ * 清理过期锁文件。
+ *
+ * 成功才打 "Stale lock removed" 的 info；失败意味着系统性异常（权限/只读 FS/
+ * 路径被替换为目录等），打 warn 并上报 server，避免运维无感——这类失败若与
+ * writeUpgradeLock 同源故障叠加，会让锁陷入"每轮都判过期但写不进新 pid"的循环。
+ * { force: true } 对文件不存在本身不会抛，所以这里 catch 到的一定是真故障。
+ * 函数本身不抛——调用方无需额外 catch。
+ * @param {string} lockPath
+ * @param {'missing-pid'|'ttl-exceeded'|'pid-dead'} reason - 清理原因 token，
+ *   同时用作 remoteLog 的 key=value 字段
+ * @param {object} [logger]
+ */
+async function removeStaleLock(lockPath, reason, logger) {
+	try {
+		await fs.rm(lockPath, { force: true });
+		logger?.info?.(`[auto-upgrade] Stale lock removed (${reason})`);
+	}
+	catch (err) {
+		logger?.warn?.(`[auto-upgrade] Stale lock removal failed (${reason}): ${err?.message}`);
+		remoteLog(`upgrade.lock-cleanup-failed reason=${reason} msg=${err?.message}`);
+	}
+}
+
 /**
  * 检查升级锁是否被持有（worker 进程是否存活）
  *
- * 若锁文件存在但 PID 已死（过期锁），顺手清理残留文件。
+ * 若锁文件存在但判定为过期（PID 已死 / JSON 无效 / 超龄），顺手清理残留文件。
  * @param {object} [opts]
  * @param {object} [opts.logger]
  * @returns {Promise<boolean>}
@@ -42,8 +75,14 @@ export async function isUpgradeLocked(opts) {
 	try {
 		const lock = JSON.parse(raw);
 		if (!lock.pid) {
-			logger?.info?.('[auto-upgrade] Stale lock removed (missing pid)');
-			await fs.rm(lockPath, { force: true }).catch(() => {});
+			await removeStaleLock(lockPath, 'missing-pid', logger);
+			return false;
+		}
+		// 超龄兜底：PID 复用误判、worker 被强杀未清锁等场景下一律视为过期。
+		// ts 不可解析也当过期（writeUpgradeLock 必写 ISO 时间戳，缺字段即异常状态）。
+		const lockTs = Date.parse(lock.ts);
+		if (!Number.isFinite(lockTs) || Date.now() - lockTs > LOCK_TTL_MS) {
+			await removeStaleLock(lockPath, 'ttl-exceeded', logger);
 			return false;
 		}
 		// signal 0 不发信号，仅检查进程存活性；进程不存在时抛异常
@@ -52,8 +91,7 @@ export async function isUpgradeLocked(opts) {
 	}
 	catch {
 		// JSON 无效 / PID 已死 → 清理过期锁
-		logger?.info?.('[auto-upgrade] Stale lock removed (worker pid no longer alive)');
-		await fs.rm(lockPath, { force: true }).catch(() => {});
+		await removeStaleLock(lockPath, 'pid-dead', logger);
 		return false;
 	}
 }

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

@@ -1,134 +1,221 @@
 /**
  * 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 注册链路正常，
- * 确保插件仍具备自我升级能力。
+ * 允许 > toVersion 的原因：scheduler 观察到 latest=x 并发起升级后，到实际
+ * 执行 `plugins update` 之间 npm dist-tag 可能已指向 x+1；严格等 x 会把
+ * 这种"升级到了更新版本"误判为失败并回滚。
+ *
+ * 磁盘 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';
+
+// 与 updater-check.js 同逻辑，worker 运行在独立子进程，不跨进程复用 gateway 模块
+function isNewerVersion(a, b) {
+	const parse = (v) => v.replace(/-.*$/, '').split('.').map(Number);
+	const pa = parse(a);
+	const pb = parse(b);
+	for (let i = 0; i < 3; i++) {
+		/* c8 ignore next 2 -- ?? fallback：正常 semver 不会有缺失段 */
+		if ((pa[i] ?? 0) > (pb[i] ?? 0)) return true;
+		if ((pa[i] ?? 0) < (pb[i] ?? 0)) return false;
+	}
+	// x.y.z 相同时：release > pre-release（semver 规则）
+	const aHasPre = a.includes('-');
+	const bHasPre = b.includes('-');
+	if (bHasPre && !aHasPre) return true;
+	return false;
+}
 
-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);
+		}
+		catch {
+			return { ok: false, reason: `invalid-json: ${output.slice(0, 120)}` };
 		}
-		return result.version;
+		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) {
+			// 等于或更新均视为成功，覆盖"升级窗口期 dist-tag 前移"的情形
+			if (result.version === toVersion || isNewerVersion(result.version, toVersion)) {
+				return {
+					ok: true,
+					version: result.version,
+					attempts,
+					elapsedMs: Date.now() - start,
+				};
+			}
+			lastVersion = result.version;
+			lastReason = `version-too-old 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,13 +15,17 @@
 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';
 
 const SEMVER_RE = /^\d+\.\d+\.\d+(-[\w.-]+)?$/;
 // 单次 plugins update 上限：包含 npm install 大型 native deps，慢网络 + 弱机器需较长时间
 const UPDATE_TIMEOUT_MS = 10 * 60 * 1000;
+// 回滚兜底重装旧版本走的是同一条 npm 下载链路，且触发前置本身是"备份已丢"的异常态，
+// 此时尽量兜住比快速失败更重要，与 UPDATE_TIMEOUT_MS 对齐
+const FALLBACK_INSTALL_TIMEOUT_MS = 10 * 60 * 1000;
+const FALLBACK_UNINSTALL_TIMEOUT_MS = 60 * 1000;
 
 /**
  * 执行 openclaw plugins update
@@ -73,7 +77,7 @@ async function fallbackInstallOldVersion(pkgName, version, pluginId, opts) {
 	}
 	/* c8 ignore next -- ?./?? fallback */
 	const doExecFile = opts?.execFileFn ?? nodeExecFile;
-	const run = (args, timeout = 120_000) => new Promise((resolve, reject) => {
+	const run = (args, timeout) => new Promise((resolve, reject) => {
 		doExecFile('openclaw', args, { timeout, shell: process.platform === 'win32' }, (err) => {
 			if (err) reject(err);
 			else resolve();
@@ -82,13 +86,13 @@ async function fallbackInstallOldVersion(pkgName, version, pluginId, opts) {
 
 	// 先卸载：install 不支持覆盖已安装插件
 	try {
-		await run(['plugins', 'uninstall', pluginId], 60_000);
+		await run(['plugins', 'uninstall', pluginId], FALLBACK_UNINSTALL_TIMEOUT_MS);
 	} catch {
 		// uninstall 失败不阻断，继续尝试 install
 	}
 
 	try {
-		await run(['plugins', 'install', `${pkgName}@${version}`]);
+		await run(['plugins', 'install', `${pkgName}@${version}`], FALLBACK_INSTALL_TIMEOUT_MS);
 	} catch (err) {
 		throw new Error(`fallback install failed: ${err.message}`);
 	}
@@ -160,7 +164,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. 成功
@@ -171,8 +175,11 @@ export async function runUpgrade({ pluginDir, fromVersion, toVersion, pluginId,
 		catch (e) {
 			log(`[upgrade-worker] Backup cleanup failed (non-fatal): ${e.message}`);
 		}
-		await updateLastUpgrade({ from: fromVersion, to: toVersion, result: 'ok' });
-		await appendLog({ from: fromVersion, to: toVersion, result: 'ok' });
+		// 记录真实装上的版本而非目标版本——dist-tag 前移窗口下两者可能不同。
+		// 不加 fallback：若 result.ok 时 version 缺失，说明上游契约被破坏，
+		// 宁可让状态里直接暴露 undefined 便于排障，也不要用 toVersion 糊过去
+		await updateLastUpgrade({ from: fromVersion, to: result.version, result: 'ok' });
+		await appendLog({ from: fromVersion, to: result.version, result: 'ok' });
 		log('[upgrade-worker] Upgrade complete');
 	} else {
 		// 4b. 失败，回滚
@@ -212,15 +219,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

@@ -1087,7 +1087,7 @@ export class RealtimeBridge {
 		// 1. 尝试 pion（最高优先级）
 		const preloadPionFn = this.__preloadPion
 			?? (await import('./webrtc/pion-preloader.js')).preloadPion;
-		const pionResult = await preloadPionFn().catch((err) => {
+		const pionResult = await preloadPionFn({ logger: this.logger }).catch((err) => {
 			this.logger.warn?.(`[coclaw] pion preload unexpected failure: ${err?.message}`);
 			return null;
 		});

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/webrtc/pion-preloader.js

@@ -1,6 +1,9 @@
 import { remoteLog as defaultRemoteLog } from '../remote-log.js';
 
-const DEFAULT_START_TIMEOUT_MS = 10_000;
+const DEFAULT_IPC_REQUEST_TIMEOUT_MS = 20_000;
+
+// 匹配 pion-node 内部视为严重的 log：IPC 请求超时、以及 Go 侧迟到的响应（主请求已 reject，响应变孤儿）
+const SEVERE_LOG_PATTERN = /request timeout|orphan response/;
 
 /**
  * 预加载 Pion WebRTC 实现：启动 pion-ipc Go 进程，返回绑定了 ipc 的 PeerConnection。
@@ -13,13 +16,15 @@ const DEFAULT_START_TIMEOUT_MS = 10_000;
  * @param {object} [deps] - 可注入依赖（测试用）
  * @param {Function} [deps.dynamicImport] - (specifier) => import(specifier)
  * @param {Function} [deps.remoteLog] - (text) => void
- * @param {number} [deps.startTimeout] - 启动超时（ms），默认 10s
+ * @param {object} [deps.logger] - plugin 本地 pino-style logger（.info/.warn/.error），用于本地调试可见性
+ * @param {number} [deps.ipcRequestTimeout] - 每次 IPC 请求的超时（ms，也用于启动 ping），默认 20s
  * @returns {Promise<{ PeerConnection: Function, cleanup: Function, impl: string, ipc: object }|null>}
  */
 export async function preloadPion(deps = {}) {
 	const log = deps.remoteLog ?? defaultRemoteLog;
+	const localLogger = deps.logger ?? null;
 	const dynamicImport = deps.dynamicImport ?? ((spec) => import(spec));
-	const startTimeout = deps.startTimeout ?? DEFAULT_START_TIMEOUT_MS;
+	const ipcRequestTimeout = deps.ipcRequestTimeout ?? DEFAULT_IPC_REQUEST_TIMEOUT_MS;
 
 	log('pion.preload');
 
@@ -42,9 +47,18 @@ export async function preloadPion(deps = {}) {
 		}
 
 		// 启动 IPC 进程（内部会 ping 验证就绪，binary 由 pion-node 自动解析）
+		// logger 回调双打：始终走 remoteLog；同时送本地 logger，严重事件（IPC 超时、orphan 响应）
+		// 升级到 error 级别，便于本地调试时一眼可见；其他运维类消息走 info。
 		ipc = new PionIpc({
-			logger: (msg) => log(`pion.ipc ${msg}`),
-			timeout: startTimeout,
+			logger: (msg) => {
+				log(`pion.ipc ${msg}`);
+				if (SEVERE_LOG_PATTERN.test(msg)) {
+					localLogger?.error?.(`[pion-ipc] ${msg}`);
+				} else {
+					localLogger?.info?.(`[pion-ipc] ${msg}`);
+				}
+			},
+			timeout: ipcRequestTimeout,
 			autoRestart: true,
 		});