@coclaw/openclaw-coclaw 0.20.0 → 0.20.2

package/package.json

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

package/src/auto-upgrade/updater.js

@@ -1,13 +1,18 @@
 import fs from 'node:fs/promises';
+import nodeFs from 'node:fs';
 import nodePath from 'node:path';
 
 import { checkForUpdate } from './updater-check.js';
 import { spawnUpgradeWorker } from './updater-spawn.js';
 import { readState, resolveStateDir, writeState } from './state.js';
-import { getRuntime } from '../runtime.js';
+import { getClawConfig } from '../claw-config.js';
 import { remoteLog } from '../remote-log.js';
 import { atomicWriteFile } from '../utils/atomic-write.js';
 
+// OpenClaw ≥ 2026.4.25 起把插件安装记录从 openclaw.json 的 plugins.installs
+// 迁移到独立账本文件，并在 loadConfig() 返回前剥掉 plugins.installs。
+const INSTALLS_LEDGER_RELATIVE_PATH = nodePath.join('plugins', 'installs.json');
+
 // 首次检查延迟较长：失败时由 worker 触发 gateway restart，scheduler 重启后会重新计时；
 // 60 分钟基线（实际随机 60-120 分钟）能把"失败→重启→再次检查"的循环周期拉长，
 // 避免连续升级失败时 gateway 在短时间内反复被打扰。
@@ -109,6 +114,80 @@ export async function writeUpgradeLock(pid) {
 	);
 }
 
+/**
+ * 读取本插件的安装记录（兼容新旧 OpenClaw 契约）
+ *
+ * - 新版（OpenClaw ≥ 2026.4.25）：账本文件 `<state-dir>/plugins/installs.json`
+ *   下的 `installRecords[pluginId]` 是来源真相；`loadConfig()` 返回的对象里
+ *   `plugins.installs` 已被剥离。
+ * - 旧版（OpenClaw ≤ 2026.4.24）：账本文件不存在，
+ *   `loadConfig().plugins.installs[pluginId]` 是来源真相。
+ *
+ * 兼容策略：先尝试账本文件；ENOENT（文件不存在）→ 回落到旧字段；
+ * 其它失败（权限/JSON 损坏/缺记录）→ 视为账本不可用，按"无来源信息"处理，不回落。
+ * 这两条互斥（新 gateway 必有账本、旧 gateway 必无）能让两个分支天然分流。
+ *
+ * 失败路径会通过 `remoteLog` 外推诊断信号（`upgrade.state-dir-failed` /
+ * `upgrade.ledger-read-failed` / `upgrade.ledger-parse-failed`），避免运维只
+ * 看到 start() 那条 "Skipping: not an npm-installed plugin" 时误判方向。
+ *
+ * @param {string} pluginId
+ * @returns {object|null}
+ */
+function loadInstallRecord(pluginId) {
+	let ledgerPath;
+	try {
+		ledgerPath = nodePath.join(resolveStateDir(), INSTALLS_LEDGER_RELATIVE_PATH);
+	}
+	catch (err) {
+		// 极少触发：host runtime 的 state resolver 自身异常
+		/* c8 ignore next -- ?? fallback：err 字段缺省的兜底分支不强制覆盖 */
+		remoteLog(`upgrade.state-dir-failed msg=${err?.message ?? String(err)}`);
+		return null;
+	}
+	let raw;
+	try {
+		raw = nodeFs.readFileSync(ledgerPath, 'utf8');
+	}
+	catch (err) {
+		if (err?.code === 'ENOENT') {
+			return loadInstallRecordFromLegacyConfig(pluginId);
+		}
+		// 账本应该可读但读不到（权限/EISDIR/IO 错误）：不回落到旧字段，避免误判老路径
+		// 静默返回 null 会让 start() 打 "Skipping: not an npm-installed plugin"，对运维毫无指向；
+		// 把诊断信号外推到 server，便于定位
+		/* c8 ignore next -- ?? fallback：err 字段缺省的兜底分支不强制覆盖 */
+		remoteLog(`upgrade.ledger-read-failed code=${err?.code ?? 'unknown'} msg=${err?.message ?? String(err)}`);
+		return null;
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	}
+	catch (err) {
+		// 账本损坏：同样不回落，并外推诊断信号
+		/* c8 ignore next -- ?? fallback：err 字段缺省的兜底分支不强制覆盖 */
+		remoteLog(`upgrade.ledger-parse-failed msg=${err?.message ?? String(err)}`);
+		return null;
+	}
+	return parsed?.installRecords?.[pluginId] ?? null;
+}
+
+/**
+ * 旧版 OpenClaw（≤ 2026.4.24）账本路径：openclaw.json 的 plugins.installs。
+ * @param {string} pluginId
+ * @returns {object|null}
+ */
+function loadInstallRecordFromLegacyConfig(pluginId) {
+	try {
+		const config = getClawConfig();
+		return config?.plugins?.installs?.[pluginId] ?? null;
+	}
+	catch {
+		return null;
+	}
+}
+
 /**
  * 判断是否应跳过自动升级
  *
@@ -122,16 +201,7 @@ export async function writeUpgradeLock(pid) {
  * @returns {boolean} true 表示应跳过自动升级
  */
 export function shouldSkipAutoUpgrade(pluginId) {
-	const rt = getRuntime();
-	if (!rt?.config?.loadConfig) return true;
-	try {
-		const config = rt.config.loadConfig();
-		const installInfo = config?.plugins?.installs?.[pluginId];
-		return installInfo?.source !== 'npm';
-	}
-	catch {
-		return true;
-	}
+	return loadInstallRecord(pluginId)?.source !== 'npm';
 }
 
 /**
@@ -140,15 +210,7 @@ export function shouldSkipAutoUpgrade(pluginId) {
  * @returns {string|null}
  */
 export function getPluginInstallPath(pluginId) {
-	const rt = getRuntime();
-	if (!rt?.config?.loadConfig) return null;
-	try {
-		const config = rt.config.loadConfig();
-		return config?.plugins?.installs?.[pluginId]?.installPath ?? null;
-	}
-	catch {
-		return null;
-	}
+	return loadInstallRecord(pluginId)?.installPath ?? null;
 }
 
 /**

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

@@ -43,6 +43,13 @@ const HEALTH_POLL_INTERVAL_MS = 3_000;
 // 及插件 bootstrap，合计 30~60s 常见；5 分钟给足余量
 const HEALTH_TOTAL_TIMEOUT_MS = 5 * 60 * 1000;
 
+// 单调时钟（毫秒，整数）。轮询超时只关心"流逝"，必须避开 Date.now() 的墙钟
+// 跳变（NTP 同步、host suspend/resume、WSL2 vmtime sync）—— 这些跳变会让
+// loop 误以为已经超时而提前退出
+function monoNowMs() {
+	return Number(process.hrtime.bigint() / 1_000_000n);
+}
+
 /**
  * 执行命令并返回 stdout；错误对象附带 stderr 以便诊断
  * @param {string} cmd
@@ -149,12 +156,12 @@ export async function pollUpgradeHealth(toVersion, opts) {
 	const totalTimeout = opts?.totalTimeoutMs ?? HEALTH_TOTAL_TIMEOUT_MS;
 	/* c8 ignore next -- ?? fallback */
 	const pollInterval = opts?.pollIntervalMs ?? HEALTH_POLL_INTERVAL_MS;
-	const start = Date.now();
+	const start = monoNowMs();
 	let attempts = 0;
 	let lastReason = '';
 	let lastVersion = '';
 
-	while (Date.now() - start < totalTimeout) {
+	while (monoNowMs() - start < totalTimeout) {
 		attempts += 1;
 		const result = await callUpgradeHealthOnce(opts);
 		if (result.ok) {
@@ -164,7 +171,7 @@ export async function pollUpgradeHealth(toVersion, opts) {
 					ok: true,
 					version: result.version,
 					attempts,
-					elapsedMs: Date.now() - start,
+					elapsedMs: monoNowMs() - start,
 				};
 			}
 			lastVersion = result.version;
@@ -174,14 +181,14 @@ export async function pollUpgradeHealth(toVersion, opts) {
 			lastReason = result.reason;
 		}
 		// 剩余时间不足以再等一个 interval 就直接退出，避免最后一次毫无意义的 sleep
-		if (Date.now() - start + pollInterval >= totalTimeout) break;
+		if (monoNowMs() - start + pollInterval >= totalTimeout) break;
 		await sleep(pollInterval);
 	}
 
 	return {
 		ok: false,
 		attempts,
-		elapsedMs: Date.now() - start,
+		elapsedMs: monoNowMs() - start,
 		lastReason,
 		lastVersion,
 	};

package/src/claw-config.js

@@ -0,0 +1,27 @@
+/**
+ * claw-config.js — OpenClaw runtime config 的统一访问入口
+ *
+ * 设计原则：
+ * - 业务代码只调 getClawConfig()，不直接摸 rt.config，新旧 API 切换全在此处兜底
+ * - OpenClaw v2026.4.27+ 新 API `config.current()`；老 API `config.loadConfig()` 仍可用但触发 deprecation 警告
+ * - 两个 API 内部都返回同一个 getRuntimeConfig() 快照，字段语义一致
+ * - 异常不在此处吞，让调用方按需处理（取 token 与读账本兜底策略不同）
+ *
+ * 拆分触发：本文件超约 200 行，或某一类 host 适配独立成块且 ≥ 100 行时再拆出去；
+ * 否则 path 之外的 host 适配优先往本文件加（必要时改名 claw-host.js）
+ */
+import { getRuntime } from './runtime.js';
+
+/**
+ * 读取当前 OpenClaw 运行时配置快照
+ *
+ * 优先 `config.current()`（v2026.4.27+），缺失时回落到 `config.loadConfig()`。
+ *
+ * @returns {object|null} runtime 未注入或缺 config 访问 API 时返回 null
+ */
+export function getClawConfig() {
+	const rt = getRuntime();
+	const reader = rt?.config?.current ?? rt?.config?.loadConfig;
+	if (!reader) return null;
+	return reader();
+}

package/src/realtime-bridge.js

@@ -1,6 +1,7 @@
 import nodePath from 'node:path';
 import { WebSocket as WsWebSocket } from 'ws';
 
+import { getClawConfig } from './claw-config.js';
 import { pluginDir } from './claw-paths.js';
 import { clearConfig, getBindingsPath, readConfig } from './config.js';
 import { cleanupResiduals as defaultCleanupResiduals, measureDiskCap as defaultMeasureDiskCap } from './rpc-queue-startup.js';
@@ -95,11 +96,7 @@ export function defaultResolveGatewayAuthToken() {
 		return envToken;
 	}
 	try {
-		const rt = getRuntime();
-		if (!rt?.config?.loadConfig) {
-			return '';
-		}
-		const cfg = rt.config.loadConfig();
+		const cfg = getClawConfig();
 		const token = cfg?.gateway?.auth?.token;
 		return typeof token === 'string' && token.trim() ? token.trim() : '';
 	}
@@ -183,8 +180,11 @@ export class RealtimeBridge {
 		// runId → connId 路由表：用于 event:agent 帧按发起方单播。
 		// 实例延迟到 start() 真 logger 到位时再 new；stop() destroy 后置 null。
 		this.__runEventRoutes = null;
-		// rpc DC 文件回退队列的磁盘容量（B-stage1 plan-2 探测，B-stage2 才消费）
+		// rpc DC 文件回退队列的磁盘容量（B-stage1 plan-2 探测，B9b 在装配 FBQ 时取）
 		this.__diskCap = null;
+		// rpc DC 文件回退队列根目录（B-stage1 plan-2 已 cleanupResiduals 过；B9b 装配 FBQ 时取）。
+		// prep 失败时 null → webrtc-peer 装配点自动降级到 MemoryQueue
+		this.__queueDir = null;
 	}
 
 	__resolveWebSocket() {
@@ -329,6 +329,10 @@ export class RealtimeBridge {
 			PeerConnection,
 			impl: this.__ndcPreloadResult?.impl,
 			logger: this.logger,
+			// B9b：webrtc-peer 装配 FBQ 时取 disk 容量 + 队列根目录；
+			// __queueDir 为 null 时（plan-2 prep 失败）自动降级到 MemoryQueue
+			getDiskCap: () => this.__diskCap,
+			queueDir: this.__queueDir,
 		});
 	}
 	/* c8 ignore stop */
@@ -1395,11 +1399,15 @@ export class RealtimeBridge {
 			const queueDir = nodePath.join(pluginDir(), 'rpc-queues');
 			await this.__cleanupRpcQueueResiduals(queueDir, { logger: this.logger });
 			this.__diskCap = await this.__measureRpcQueueDiskCap(queueDir, { logger: this.logger });
+			// 只有 cleanupResiduals 成功 + measureDiskCap 完成后才暴露 queueDir 给 webrtc 装配；
+			// 任一抛错都让 __queueDir 留 null，下游自动降级到 MemoryQueue
+			this.__queueDir = queueDir;
 		}
 		catch (err) {
 			/* c8 ignore next -- ?./?? fallback：err 总是 Error，logger.warn 总存在 */
 			this.logger.warn?.(`[coclaw] rpc-queues startup prep failed (skipped): ${err?.message ?? err}`);
 			this.__diskCap = null;
+			this.__queueDir = null;
 		}
 		// race 守卫：cleanup/measure 期间若 stop() 已执行，不应再启动 native WebRTC 进程。
 		// preload 后还有一道 started 检查兜底（含 pion cleanup），这里先挡住一次无意义的 preload。

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

@@ -35,8 +35,10 @@ class FileBackedQueue {
 	 * @param {string} opts.id - 队列标识，字符集受限，防路径穿越
 	 * @param {number} [opts.memBudget=8MB] - 内存持有字节数上限
 	 * @param {number} [opts.diskCap=1GB] - 磁盘+内存总字节数硬上限（含 `\n`）
-	 * @param {(reason: string, size: number) => void} [opts.onDrop] - 拒入队时的回调
+	 * @param {number} [opts.maxMessageBytes=Infinity] - 单条硬上限；超过即 drop（bypass 也不豁免）
+	 * @param {(reason: string, size: number, err?: Error) => void} [opts.onDrop] - 拒入队时的回调；'fs-error' 传底层 err，其它 reason 第三参为 undefined
 	 * @param {{ warn?: Function, info?: Function, error?: Function }} [opts.logger=console]
+	 * @param {(jsonStr: string) => boolean} [opts.bypassAdmission] - 白名单谓词，命中则容量层 admission 豁免（与 MemoryQueue 同义）
 	 */
 	constructor(opts) {
 		const {
@@ -44,8 +46,10 @@ class FileBackedQueue {
 			id,
 			memBudget = DEFAULT_MEM_BUDGET,
 			diskCap = DEFAULT_DISK_CAP,
+			maxMessageBytes = Infinity,
 			onDrop,
 			logger = console,
+			bypassAdmission,
 		} = opts ?? {};
 
 		if (!dir || typeof dir !== 'string') throw new TypeError('dir is required');
@@ -61,13 +65,19 @@ class FileBackedQueue {
 		if (!Number.isFinite(diskCap) || diskCap <= 0) {
 			throw new TypeError('diskCap must be a finite positive number');
 		}
+		if (maxMessageBytes !== Infinity && (!Number.isFinite(maxMessageBytes) || maxMessageBytes <= 0)) {
+			throw new TypeError('maxMessageBytes must be Infinity or a finite positive number');
+		}
 
 		this.dir = dir;
 		this.id = id;
 		this.memBudget = memBudget;
 		this.diskCap = diskCap;
+		this.maxMessageBytes = maxMessageBytes;
 		this.onDrop = onDrop;
 		this.logger = logger;
+		// 非函数（含 undefined / null / 字符串等）一律收编为 null，保持向后兼容
+		this.bypassAdmission = typeof bypassAdmission === 'function' ? bypassAdmission : null;
 
 		this.filePath = nodePath.join(dir, `${id}.jsonl`);
 
@@ -83,6 +93,9 @@ class FileBackedQueue {
 		this.fsBroken = false;    // 粘性：一旦 FS 出错，不再尝试 reopen
 		this.writeStream = null;
 		this.writeErr = null;
+		// 粘性最新 fs 错误：__handleFsError 在 mutex 内缓存；后续走 fsBroken 短路的 enqueue 通过
+		// __dispatchDrop 第三参把 err 透传给 onDrop，让 monitor / 运维拿到具体 errno
+		this.lastFsErr = null;
 		this.waiters = [];
 		this.mutex = createMutex();
 	}
@@ -130,10 +143,20 @@ class FileBackedQueue {
 
 			const size = Buffer.byteLength(jsonStr, 'utf8');
 
+			// per-message 硬上限：bypass 也不豁免（红线 3：bypass 仅豁免容量层 admission）。
+			// 与 sender 端 MAX_SINGLE_MSG_BYTES 检查对齐——避免大帧先入队再被 sender 拒，
+			// 导致 backlog 异常膨胀且 oversize 不进 monitor 账（loud-on-loss）。
+			if (size > this.maxMessageBytes) {
+				this.__dispatchDrop('oversize', size);
+				return false;
+			}
+
 			// admission：按物理占用（mem + 已写文件总字节，含 \n）判定，保证 diskCap 是真正的硬上限。
 			// 用 writtenBytes（不减 readOffset）的含义：文件前缀已读但未被 __dropFile 回收前仍算占用。
 			// 代价：持续背压下消费者还没追到写端时新消息可能被 drop，直到完全 drain 触发 __dropFile 重置。
-			if (this.memBytes + this.writtenBytes + size + 1 > this.diskCap) {
+			// bypassAdmission 命中时容量层豁免（与 MemoryQueue 一致）：白名单消息可越过 diskCap 入队，
+			// 实际占用可能短暂超 diskCap——这是红线 3 的明确预期。物理 IO 失败仍会按 fs-error drop。
+			if (this.memBytes + this.writtenBytes + size + 1 > this.diskCap && !this.__isBypass(jsonStr)) {
 				this.__dispatchDrop('disk-cap', size);
 				return false;
 			}
@@ -150,9 +173,10 @@ class FileBackedQueue {
 				}
 			}
 
-			// 溢出路径：FS 已破直接 drop，不再尝试 reopen
+			// 溢出路径：FS 已破直接 drop，不再尝试 reopen。lastFsErr 由 __handleFsError 已粘性置好，
+			// 把它透传给 onDrop 第三参——红线 2 "丢失/延迟必须 loud 可观测" 要求把 errno 抬出去
 			if (this.fsBroken) {
-				this.__dispatchDrop('fs-error', size);
+				this.__dispatchDrop('fs-error', size, this.lastFsErr);
 				return false;
 			}
 
@@ -160,7 +184,7 @@ class FileBackedQueue {
 				await this.__openWriteStream();
 				if (this.writeErr) {
 					const err = this.writeErr;
-					this.__dispatchDrop('fs-error', size);
+					this.__dispatchDrop('fs-error', size, err);
 					// 前置 mkdir/rm 失败也进入粘性降级：与 stream 'error' 路径语义一致，
 					// 避免后续每次 overflow 都重试同一个持续性 FS 故障。
 					await this.__handleFsError(err);
@@ -176,7 +200,7 @@ class FileBackedQueue {
 				return true;
 			} catch (err) {
 				this.logger?.warn?.('fbq.enqueue fs-error', err);
-				this.__dispatchDrop('fs-error', size);
+				this.__dispatchDrop('fs-error', size, err);
 				// 直接在当前锁内触发粘性降级：真实 Node stream 下 cb err 通常也会 emit 'error'
 				// （监听器会另外排一次 handleFsError，但 fsBroken 已置 → no-op）；测试里的 monkey-patch
 				// 只触发 cb、不发 'error'，这里主动降级保证行为一致。
@@ -223,17 +247,33 @@ class FileBackedQueue {
 			this.spilled = false;
 			this.fsBroken = false;
 			this.writeErr = null;
+			this.lastFsErr = null;
 		});
 	}
 
 	/**
 	 * 停写、关 FD、删文件、结束所有迭代器。幂等。
+	 *
+	 * @param {(residual: { memCount: number, memBytes: number, diskBytes: number, writtenBytes: number, spilled: boolean, fsBroken: boolean }) => void} [onBeforeClear]
+	 *   可选回调（**必须为同步函数**）：在 mutex 内、清空字段 / 关流 / 删文件**之前**触发，
+	 *   参数是销毁时刻的 6 字段残留快照。存在意义：mutex 保证 in-flight enqueue 已落地；调用方
+	 *   sync 调 `queue.stats()` 看不到 in-flight 入队的消息，改用此回调可拿原子准确的残留快照。
+	 *   回调同步抛错被 swallow，不影响 destroy 完成。
+	 *   **注意**：返回 Promise 的异步回调其 rejection 不会被捕获——仅设计为 sync 钩子（与 MemoryQueue 一致）。
 	 */
-	async destroy() {
+	async destroy(onBeforeClear) {
 		return await this.mutex.withLock(async () => {
 			if (this.destroyed) return;
 			this.destroyed = true;
 
+			// 在 mutex 内、清空 / 关流 / 删文件之前快照 6 字段残留：mutex 保证看到所有已入队的消息（含 in-flight）；
+			// 异步 IO 清理（__closeWriteStream / fs.rm）会改 spilled/writtenBytes，所以快照必须先抓
+			if (typeof onBeforeClear === 'function') {
+				const residual = this.stats();
+				try { onBeforeClear(residual); }
+				catch { /* 回调自身抛是调用方的 bug；不能传染给 destroy 契约（与 MemoryQueue silent gotcha 镜像）*/ }
+			}
+
 			// 唤醒所有等待者，让它们在下一轮循环中看到 destroyed 并返回 done
 			const toWake = this.waiters.splice(0);
 			for (const w of toWake) w.resolve();
@@ -252,6 +292,7 @@ class FileBackedQueue {
 			this.writtenBytes = 0;
 			this.readOffset = 0;
 			this.spilled = false;
+			this.lastFsErr = null;
 		});
 	}
 
@@ -307,14 +348,24 @@ class FileBackedQueue {
 		for (const w of toWake) w.resolve();
 	}
 
-	__dispatchDrop(reason, size) {
+	__dispatchDrop(reason, size, err) {
 		try {
-			this.onDrop?.(reason, size);
-		} catch (err) {
+			this.onDrop?.(reason, size, err);
+		} catch (cbErr) {
 			/* c8 ignore next 2 -- onDrop throwing is caller's bug */
-			this.logger?.warn?.('fbq.onDrop threw', err);
+			this.logger?.warn?.('fbq.onDrop threw', cbErr);
+		}
+		this.logger?.warn?.('fbq.drop', { reason, size, err: err?.message });
+	}
+
+	__isBypass(jsonStr) {
+		if (!this.bypassAdmission) return false;
+		try {
+			return Boolean(this.bypassAdmission(jsonStr));
+		} catch {
+			// 谓词自身抛 → 视为非白名单（最安全的回退；保守 drop 而非误入队）
+			return false;
 		}
-		this.logger?.warn?.('fbq.drop', { reason, size });
 	}
 
 	async __openWriteStream() {
@@ -373,16 +424,17 @@ class FileBackedQueue {
 		});
 	}
 
-	// mutex 内调用：FS 错误粘性降级
-	async __handleFsError(_err) {
+	// mutex 内调用：FS 错误粘性降级。err 缓存到 lastFsErr 供后续 fsBroken 短路 enqueue 透传给 onDrop
+	async __handleFsError(err) {
 		if (this.destroyed || this.fsBroken) return;
 		this.fsBroken = true;
+		this.lastFsErr = err;
 		await this.__closeWriteStream();
 		try {
 			await fs.rm(this.filePath, { force: true });
-		} catch (err) {
+		} catch (rmErr) {
 			/* c8 ignore next 2 -- rm with force rarely fails */
-			this.logger?.warn?.('fbq.handleFsError rm error', err);
+			this.logger?.warn?.('fbq.handleFsError rm error', rmErr);
 		}
 		this.spilled = false;
 		this.writtenBytes = 0;

package/src/webrtc/webrtc-peer.js

@@ -1,10 +1,24 @@
+import { randomUUID } from 'node:crypto';
+
 import { createReassembler } from './dc-chunking.js';
 import { MemoryQueue } from '../utils/memory-queue.js';
+import { FileBackedQueue } from '../utils/file-backed-queue.js';
 import { RpcDcSender, DC_LOW_WATER_MARK, MAX_SINGLE_MSG_BYTES } from './rpc-dc-sender.js';
 import { createRpcDropMonitor } from './rpc-drop-monitor.js';
 import { isAgentRunResponse } from './agent-run-response.js';
 import { remoteLog } from '../remote-log.js';
 
+// rpc DC 发送队列实现选择（B-stage2 B9b）。
+// - 'mem'：MemoryQueue（当前生产默认）—— 不碰 fs，溢出即 drop；FBQ 未充分本地验证前先用此模式发布
+// - 'fbq'：FileBackedQueue —— 长时间后台 / ICE 恢复等慢消化场景溢出到磁盘
+// 当 'fbq' 但 queueDir 不可用（bridge 启动期 plan-2 prep 失败）时自动降级到 'mem'，避免阻塞 webrtc 装配。
+// 单点常量；构造时可通过 `rpcQueueImpl` opt 覆盖（测试用）。生产侧改回 'fbq' 只需翻这一行。
+const RPC_QUEUE_IMPL = 'mem';
+
+// FBQ 装配兜底：bridge 启动期 measureDiskCap 失败 → __diskCap=null → 这里兜底 1GB
+const ONE_GB = 1024 * 1024 * 1024;
+const RPC_QUEUE_MEM_BUDGET = 10 * 1024 * 1024;
+
 // 单个 session 内 file DC 历史快照的容量上限（满后按 FIFO 淘汰最老条目）。
 // 用于诊断 dump：过大会撑爆 remoteLog 单帧，20 足以覆盖典型多文件传输会话。
 const FILE_CHANNEL_HISTORY_LIMIT = 20;
@@ -31,8 +45,13 @@ export class WebRtcPeer {
 	 * @param {object} [opts.logger] - pino 风格 logger
 	 * @param {function} opts.PeerConnection - RTCPeerConnection 构造函数（由 ndc-preloader 提供）
 	 * @param {string} [opts.impl] - WebRTC 实现标识（pion / ndc / werift）
+	 * @param {() => (number|null)} [opts.getDiskCap] - 启动期测得的 diskCap 字节数；prep 失败返 null。
+	 *   FBQ 装配时取（兜底 1GB）；MemoryQueue 装配不消费。
+	 * @param {string} [opts.queueDir] - rpc DC 队列文件目录（FBQ 模式所需）；空 / 非字符串时降级到 MemoryQueue
+	 * @param {'fbq'|'mem'} [opts.rpcQueueImpl] - rpc 队列实现选择，默认取模块级 RPC_QUEUE_IMPL；
+	 *   测试用——生产路径走默认即可
 	 */
-	constructor({ onSend, onRequest, onFileRpc, onFileChannel, logger, PeerConnection, impl }) {
+	constructor({ onSend, onRequest, onFileRpc, onFileChannel, logger, PeerConnection, impl, getDiskCap, queueDir, rpcQueueImpl }) {
 		if (!PeerConnection) {
 			throw new Error('PeerConnection constructor is required');
 		}
@@ -43,6 +62,12 @@ export class WebRtcPeer {
 		this.logger = logger ?? console;
 		this.__PeerConnection = PeerConnection;
 		this.__impl = impl ?? null;
+		// 非函数（含 undefined / null / 字符串等）一律收编为 null，调用时再做 null 兜底
+		this.__getDiskCap = typeof getDiskCap === 'function' ? getDiskCap : null;
+		// FBQ 文件根目录；非字符串 / 空字符串 → null → 装配时自动降级到 MemoryQueue
+		this.__queueDir = typeof queueDir === 'string' && queueDir.length > 0 ? queueDir : null;
+		// 队列实现选择：测试可显式覆盖；非 'fbq'/'mem' 一律收编为模块默认，避免误用
+		this.__rpcQueueImpl = (rpcQueueImpl === 'fbq' || rpcQueueImpl === 'mem') ? rpcQueueImpl : RPC_QUEUE_IMPL;
 		this.__rtcTag = impl ? `[coclaw/rtc:${impl}]` : '[coclaw/rtc]';
 		/** @type {Map<string, { pc: object, rpcChannel: object|null, rpcQueue: MemoryQueue|null, rpcDcSender: RpcDcSender|null, rpcConsumeLoop: Promise<void>|null, rpcDropMonitor: object|null, fileChannels: Set, remoteMaxMessageSize: number, nextMsgId: number }>} */
 		this.__sessions = new Map();
@@ -551,8 +576,8 @@ export class WebRtcPeer {
 	}
 
 	async __setupDataChannel(connId, dc) {
-		// rpc DC 发送流控：MemoryQueue（admission + bypass 白名单）+ rpc-drop-monitor
-		// （边沿日志 / 累计 / 汇总）+ RpcDcSender（分片 + 背压），通过消费循环串起来。
+		// rpc DC 发送流控：Queue（FileBackedQueue 默认 / MemoryQueue 降级；admission + bypass 白名单）
+		// + rpc-drop-monitor（边沿日志 / 累计 / 汇总）+ RpcDcSender（分片 + 背压），通过消费循环串起来。
 		// 广播 / sendTo / files sendFn 都向 queue.enqueue，sender 从 queue 拉。
 		const session = this.__sessions.get(connId);
 
@@ -673,20 +698,40 @@ export class WebRtcPeer {
 			if (session.rpcConsumeLoop) await session.rpcConsumeLoop.catch(() => { /* c8 ignore next -- 极冷防御 */ });
 			session.rpcDropMonitor = null;
 		}
-		// 创建 monitor。必须在 new MemoryQueue 之前——MemoryQueue 的 onDrop 接 monitor.onDrop。
+		// 创建 monitor。必须在 new Queue 之前——Queue 的 onDrop 接 monitor.onDrop。
 		// monitor 是局部变量，stale 路径下函数返回后自然 GC，不挂 session 字段（无 drop 可汇总）。
 		const monitor = createRpcDropMonitor({ connId, logger: this.logger });
-		// 构造 queue 并 await init。MemoryQueue.init 是 no-op；保留 await 占位，FBQ 阶段
-		// init 承担 fs 残留清理。await 期间可能发生 closeByConnId / 同 connId 二次 ondatachannel，
-		// 因此后面必须身份重核才能赋 session 字段。
-		const queue = new MemoryQueue({
-			id: connId,
-			maxMessageBytes: MAX_SINGLE_MSG_BYTES,
-			bypassAdmission: isAgentRunResponse,
-			onDrop: monitor.onDrop,
-			logger: this.logger,
-			tag: `conn=${connId}`,
-		});
+
+		// queue 实例选择（B-stage2 B9b）：默认取模块级 RPC_QUEUE_IMPL（当前 'mem'）；
+		// 'fbq' 模式下若 queueDir 不可用则降级到 mem，避免阻塞装配。
+		// 同 connId race 隔离（决策 4）：FBQ id 加唯一后缀 ${connId}-${ts}-${nonce}，
+		// 让新旧实例文件名物理不同，destroy/init 期间互不踩踏。MemoryQueue 不碰 fs，无此需求。
+		// connId 字符集（PRE-EXISTING 契约）：上游 server 分配 connId 形如 `c_<digits>`；
+		// FBQ / MemoryQueue 共用 `^[A-Za-z0-9._-]+$` 校验。若 server 将来引入特殊字符，
+		// queue 构造会抛 TypeError，由 __setupDataChannel 的 .catch 兜底 warn——非 B9b 引入。
+		const useFbq = this.__rpcQueueImpl === 'fbq' && !!this.__queueDir;
+		const fbqFallback = !useFbq && this.__rpcQueueImpl === 'fbq';
+		const queue = useFbq
+			? new FileBackedQueue({
+				id: `${connId}-${Date.now()}-${randomUUID().slice(0, 8)}`,
+				dir: this.__queueDir,
+				memBudget: RPC_QUEUE_MEM_BUDGET,
+				diskCap: this.__getDiskCap?.() ?? ONE_GB,
+				maxMessageBytes: MAX_SINGLE_MSG_BYTES,
+				bypassAdmission: isAgentRunResponse,
+				onDrop: monitor.onDrop,
+				logger: this.logger,
+			})
+			: new MemoryQueue({
+				id: connId,
+				maxMessageBytes: MAX_SINGLE_MSG_BYTES,
+				bypassAdmission: isAgentRunResponse,
+				onDrop: monitor.onDrop,
+				logger: this.logger,
+				tag: `conn=${connId}`,
+			});
+		// FBQ.init 承担 fs 残留清理（含同 connId 唯一后缀文件，不会撞旧实例）；MemoryQueue.init 是 no-op。
+		// await 期间可能发生 closeByConnId / 同 connId 二次 ondatachannel，因此后面必须身份重核才能赋字段。
 		await queue.init();
 		// 身份重核：init 期间 session 可能被 closeByConnId 从 Map 删除，或被同 connId 二次
 		// ondatachannel 把 rpcChannel 替换成新 dc。任一不再成立都视为 stale，destroy queue 后
@@ -696,6 +741,12 @@ export class WebRtcPeer {
 			await queue.destroy();
 			return;
 		}
+		// 装配成功后日志：让运维侧看到该 session 实际跑哪种 queue（特别是 fbq 降级到 mem 的场景）。
+		// 放在 stale 守卫之后——只对真正生效的 session 打 log，避免 stale 装配虚报一次。
+		// 单 session 只打一次，频率与连接频率挂钩——符合 remoteLog 红线（不高频）。
+		const queueImpl = useFbq ? 'fbq' : 'mem';
+		this.logger.info?.(`${this.__rtcTag} [${connId}] rpc queue impl=${queueImpl}${fbqFallback ? ' (fallback: queueDir unavailable)' : ''}`);
+		this.__remoteLog(`rtc.queue-impl conn=${connId} impl=${queueImpl}${fbqFallback ? ' fallback=queue-dir-null' : ''}`);
 		if ('bufferedAmountLowThreshold' in dc) {
 			dc.bufferedAmountLowThreshold = DC_LOW_WATER_MARK;
 		}