@coclaw/openclaw-coclaw 0.20.1 → 0.21.0

package/package.json

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

package/src/auto-upgrade/updater.js

@@ -204,6 +204,21 @@ export function shouldSkipAutoUpgrade(pluginId) {
 	return loadInstallRecord(pluginId)?.source !== 'npm';
 }
 
+/**
+ * 判断 host 是否运行在 Nix mode。
+ *
+ * OpenClaw ≥ 2026.5 在 `openclaw plugins {update,install,uninstall,...}` 入口加了
+ * `assertConfigWriteAllowedInCurrentMode()` 守门：当 `OPENCLAW_NIX_MODE=1` 时直接抛
+ * `NixModeConfigMutationError`（code `OPENCLAW_NIX_MODE_CONFIG_IMMUTABLE`），因为
+ * 这类用户的 openclaw.json 由 Nix 当 immutable 资产管，运行时改了下次 Nix 重建会被刷回。
+ * 自动升级在这种环境下毫无意义且会污染日志，scheduler 启动前直接退出即可。
+ *
+ * @returns {boolean}
+ */
+export function isNixMode() {
+	return process.env.OPENCLAW_NIX_MODE === '1';
+}
+
 /**
  * 获取插件安装路径
  * @param {string} pluginId
@@ -239,6 +254,7 @@ export class AutoUpgradeScheduler {
 	 * @param {Function} [params.opts.execFileFn]
 	 * @param {Function} [params.opts.spawnFn]
 	 * @param {Function} [params.opts.shouldSkipFn]
+	 * @param {Function} [params.opts.isNixModeFn]
 	 * @param {Function} [params.opts.getPluginInstallPathFn]
 	 */
 	constructor(params) {
@@ -260,6 +276,17 @@ export class AutoUpgradeScheduler {
 			return;
 		}
 
+		const isNix = this.__opts.isNixModeFn ?? isNixMode;
+		if (isNix()) {
+			// 上推到 server：用户向我们反馈"自动升级没动"时，可凭 server 端 remote log
+			// 直接定位到 Nix mode 跳过路径，不必再回滚问"你是不是 nix-openclaw 装的"。
+			// scheduler.start() 每次 gateway 启动只调一次，量级低、不会刷屏。
+			remoteLog('upgrade.nix-mode-skip');
+			this.__logger.info?.('[auto-upgrade] Skipping: host is in Nix mode (config is immutable)');
+			this.__running = false;
+			return;
+		}
+
 		const shouldSkip = this.__opts.shouldSkipFn ?? shouldSkipAutoUpgrade;
 		if (shouldSkip(this.__pluginId)) {
 			this.__logger.info?.('[auto-upgrade] Skipping: not an npm-installed plugin');

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/realtime-bridge.js

@@ -279,7 +279,8 @@ export class RealtimeBridge {
 			return;
 		}
 		try {
-			this.gatewayWs.close(1000, 'server-disconnect');
+			this.gatewayWs.__closedByPlugin = true;
+			this.gatewayWs.close(1000, 'local-close');
 		}
 		/* c8 ignore next */
 		catch {}
@@ -814,7 +815,10 @@ export class RealtimeBridge {
 						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'); }
+						try {
+							ws.__closedByPlugin = true;
+							ws.close(1008, 'gateway_connect_failed');
+						}
 						/* c8 ignore next */
 						catch {}
 					}
@@ -917,13 +921,27 @@ export class RealtimeBridge {
 			this.__logDebug('gateway ws open, waiting for connect.challenge');
 		});
 		ws.addEventListener('close', (ev) => {
-			// 握手失败路径已经打过 ws.connect-failed，这里抑制重复的 disconnected 日志；
-			// 成功后的意外断开、握手途中的异常断开仍按原样上报。per-WS log 用闭包局部
-			// connectFailReported，无需身份校验
+			// 区分本端 plugin 主动关闭与对端 OpenClaw gateway 关闭：日志/远程上报用不同事件名，
+			// 避免读 log 时把"plugin 自己关"误读成"对端断开"（reason 字段全在我们自定义）；
+			// server 仍可从 remoteLog 频次发现 local-close 循环异常。
+			const closedByPlugin = ws.__closedByPlugin === true;
+			// 握手失败路径已经打过 ws.connect-failed，这里抑制重复的远程上报；
+			// 其它分支（成功后掉线 / 握手中异常断开 / plugin 主动关闭）按原样上报。per-WS log 用
+			// 闭包局部 connectFailReported，无需身份校验
 			if (!connectFailReported) {
-				remoteLog(`ws.disconnected peer=gateway code=${ev?.code ?? '?'}`);
+				if (closedByPlugin) {
+					remoteLog(`ws.local-close peer=gateway reason=${ev?.reason ?? 'n/a'}`);
+				}
+				else {
+					remoteLog(`ws.disconnected peer=gateway code=${ev?.code ?? '?'} reason=${ev?.reason ?? 'n/a'}`);
+				}
+			}
+			if (closedByPlugin) {
+				this.logger.info?.(`[coclaw] gateway ws closed by plugin (reason=${ev?.reason ?? 'n/a'})`);
+			}
+			else {
+				this.logger.info?.(`[coclaw] gateway ws closed by peer (code=${ev?.code ?? '?'} reason=${ev?.reason ?? 'n/a'})`);
 			}
-			this.logger.info?.(`[coclaw] gateway ws closed (code=${ev?.code ?? '?'} reason=${ev?.reason ?? 'n/a'})`);
 			// stale guard：旧 ws 的迟到 close 不应清新 ws 的 lag probes / pending requests / DC 路由 /
 			// 也不应触发新一轮重试调度。非当前 ws → 直接早返，仅留 per-WS 日志。
 			if (this.gatewayWs !== ws) {
@@ -965,7 +983,10 @@ export class RealtimeBridge {
 			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'); }
+			try {
+				ws.__closedByPlugin = true;
+				ws.close(1011, 'ws_error');
+			}
 			/* c8 ignore next */
 			catch {}
 		});
@@ -1395,13 +1416,33 @@ export class RealtimeBridge {
 		// 整块包 try/catch：模块自身不抛，但仍可能进入 catch 的路径——pluginDir() 同步抛
 		// （runtime 未注入 / nodePath.join 参数异常 / 测试注入的 stub 抛错）。任何路径都不能把
 		// bridge.start 卡死。
+		// 10s timeout 兜底：cleanup/measure 内部已永不抛（仅 warn + fallback），但 fs hang
+		// 场景（NFS / 网络挂载 / 磁盘卡）下 fs.promises 调用不返回，整段会卡死；超时让 catch
+		// 兜底降级到 MemoryQueue，bridge 至少能起来。
+		// race 闭合：prep 改成纯返回值，timeout 赢时 catch 显式赋 null；不在 IIFE 内部 mutate
+		// `this.__diskCap`，避免后台 prep 晚到把降级状态又覆盖回非 null。
 		try {
 			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;
+			const prepPromise = (async () => {
+				await this.__cleanupRpcQueueResiduals(queueDir, { logger: this.logger });
+				const diskCap = await this.__measureRpcQueueDiskCap(queueDir, { logger: this.logger });
+				return { queueDir, diskCap };
+			})();
+			let timeoutId;
+			const timeoutPromise = new Promise((_, reject) => {
+				timeoutId = setTimeout(() => reject(new Error('rpc-queues startup prep timeout (10s)')), 10000);
+				timeoutId.unref?.();
+			});
+			let result;
+			try {
+				result = await Promise.race([prepPromise, timeoutPromise]);
+			}
+			finally {
+				clearTimeout(timeoutId);
+			}
+			// race 赢后才赋字段：保证 __diskCap / __queueDir 同时一致
+			this.__diskCap = result.diskCap;
+			this.__queueDir = result.queueDir;
 		}
 		catch (err) {
 			/* c8 ignore next -- ?./?? fallback：err 总是 Error，logger.warn 总存在 */

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

@@ -6,7 +6,8 @@
  * - FIFO、单一生产者／消费者；多消费者时每条只交付给其中一个。
  * - 构造纯字段初始化，不碰 FS；使用前需 `await q.init()`。
  * - 消费侧：`for await (const item of queue) { ... }`；`destroy()` 让迭代结束。
- * - FS 异常下进入 `fsBroken` 粘性降级：mem 路径继续工作，溢出消息 drop。
+ * - FS 异常下进入 `fsBroken` 粘性降级：mem 路径继续工作，溢出消息 drop；
+ *   命中 bypassAdmission 的白名单消息允许 mem 桶 overshoot（与 MemoryQueue 镜像，保白名单不被误报 fs-error）。
  */
 
 import fs from 'node:fs/promises';
@@ -19,9 +20,6 @@ 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._-]+$/;
 
@@ -33,10 +31,12 @@ class FileBackedQueue {
 	 * @param {object} opts
 	 * @param {string} opts.dir - 队列文件根目录
 	 * @param {string} opts.id - 队列标识，字符集受限，防路径穿越
-	 * @param {number} [opts.memBudget=8MB] - 内存持有字节数上限
-	 * @param {number} [opts.diskCap=1GB] - 磁盘+内存总字节数硬上限（含 `\n`）
+	 * @param {number} [opts.memBudget=8MB] - mem 桶阈值（按 current ≥ threshold 判定，允许 single overshoot）
+	 * @param {number} [opts.diskCap=1GB] - mem + 已写文件累计字节总占用阈值（含 `\n`）；按 current ≥ threshold + single overshoot；非文件 size 硬上限
 	 * @param {number} [opts.maxMessageBytes=Infinity] - 单条硬上限；超过即 drop（bypass 也不豁免）
-	 * @param {(reason: string, size: number, err?: Error) => void} [opts.onDrop] - 拒入队时的回调；'fs-error' 传底层 err，其它 reason 第三参为 undefined
+	 * @param {(reason: string, size: number, err?: Error|object) => void} [opts.onDrop] - 拒入队时的回调；'fs-error' 第三参传底层 err；'disk-cap' 第三参传 { memBytes, writtenBytes, diskCap } 分量；其它 reason 第三参为 undefined
+	 * @param {() => void} [opts.onSpillStart] - 文件创建（spilled false→true）回调，边沿触发
+	 * @param {(drainedBytes: number) => void} [opts.onSpillEnd] - 文件 drain 删除（spilled true→false）回调，边沿触发；故障删档不触发
 	 * @param {{ warn?: Function, info?: Function, error?: Function }} [opts.logger=console]
 	 * @param {(jsonStr: string) => boolean} [opts.bypassAdmission] - 白名单谓词，命中则容量层 admission 豁免（与 MemoryQueue 同义）
 	 */
@@ -48,6 +48,8 @@ class FileBackedQueue {
 			diskCap = DEFAULT_DISK_CAP,
 			maxMessageBytes = Infinity,
 			onDrop,
+			onSpillStart,
+			onSpillEnd,
 			logger = console,
 			bypassAdmission,
 		} = opts ?? {};
@@ -75,6 +77,8 @@ class FileBackedQueue {
 		this.diskCap = diskCap;
 		this.maxMessageBytes = maxMessageBytes;
 		this.onDrop = onDrop;
+		this.onSpillStart = onSpillStart;
+		this.onSpillEnd = onSpillEnd;
 		this.logger = logger;
 		// 非函数（含 undefined / null / 字符串等）一律收编为 null，保持向后兼容
 		this.bypassAdmission = typeof bypassAdmission === 'function' ? bypassAdmission : null;
@@ -151,21 +155,44 @@ class FileBackedQueue {
 				return false;
 			}
 
-			// admission：按物理占用（mem + 已写文件总字节，含 \n）判定，保证 diskCap 是真正的硬上限。
-			// 用 writtenBytes（不减 readOffset）的含义：文件前缀已读但未被 __dropFile 回收前仍算占用。
-			// 代价：持续背压下消费者还没追到写端时新消息可能被 drop，直到完全 drain 触发 __dropFile 重置。
-			// 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);
+			// bypass 谓词懒求值缓存：仅 admission / fsBroken overshoot 路径需要时才调用，整次 enqueue 内最多一次。
+			// 容量充裕路径（不超 diskCap 且 mem 装得下）完全不调谓词——保留原短路语义、避免每条消息都解析 JSON。
+			let isBypass; // undefined = 未求值；?= 后变 true / false 即缓存命中
+			const getIsBypass = () => isBypass ??= this.__isBypass(jsonStr);
+
+			// admission：与 MemoryQueue 一致——按 current ≥ threshold 判定，允许 single overshoot。
+			// diskCap 语义：mem + 已写文件累计字节（writtenBytes 不减 readOffset，文件前缀已读但未
+			// __dropFile 回收前仍计入）的总占用阈值；不是单纯文件 size 上限，所以文件实际峰值约为
+			// diskCap - memBudget。允许 single overshoot：当前总占用 < diskCap 时再大的一条都收，
+			// 下一条才会 drop——与 MemoryQueue 单条 overshoot 行为对齐，简化两实现的语义分叉。
+			// bypass 命中时容量层豁免（红线 3）：白名单消息越过 diskCap 入队，物理 IO 失败仍按 fs-error drop。
+			// fsBroken 守卫：粘性降级后 spill 永远不可用、writtenBytes 已重置为 0；mem 桶可能因
+			// 持续 bypass overshoot 推过 diskCap，但此时再来的非 bypass 消息根因是 fs 已坏（而非"容量"），
+			// 必须让下面的 fsBroken 短路赢、报 fs-error 带 lastFsErr，运维才能看到正确的诊断信号。
+			if (!this.fsBroken && this.memBytes + this.writtenBytes >= this.diskCap && !getIsBypass()) {
+				// 第三参传分量，让监视器在 disk-cap-start log 里把 mem / written / cap 都展开
+				this.__dispatchDrop('disk-cap', size, {
+					memBytes: this.memBytes,
+					writtenBytes: this.writtenBytes,
+					diskCap: this.diskCap,
+				});
 				return false;
 			}
 
-			// 内存路径：未溢出且 admission 通过（考虑 overhead；首条无论多大都收）
+			// 内存路径：与 MemoryQueue 一致——memBytes < memBudget 即接受（含 single overshoot）
 			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) {
+				const memFits = this.memBytes < this.memBudget;
+				// fsBroken 降级模式：spill 不可用 → mem 桶就是事实上的容量层。
+				// 此时 bypass 命中允许 overshoot（与 MemoryQueue 镜像），保白名单消息不被误报 fs-error。
+				// 健康路径下 mem 满仍走 spill（不在此处豁免），避免 mem 无界增长违背 spill 设计目标。
+				//
+				// 设计取舍：fsBroken + bypass 路径下 mem 桶**不再**有显式硬上限——bypass 已豁免 diskCap admission，
+				// 这里也豁免 memBudget。理论上同时持续 fsBroken + 高密度 bypass 命中可堆到 OOM，仅靠 maxMessageBytes
+				// 单条 50 MB 兜底。**有意识的接受**：业务侧 agent 响应流量由用户活动自然封顶（与"不做 OOM 防御性
+				// 检测"项目原则一致）；后续诊断完整性由 monitor.summarize 在 close 时透传 residualStats.fsBroken
+				// 让运维侧拿到降级信号即可。请勿在 review 中把"无硬上限"当 P1 误报。
+				const bypassOvershoot = !memFits && this.fsBroken && getIsBypass();
+				if (memFits || bypassOvershoot) {
 					this.memQueue.push(jsonStr);
 					this.memBytes += size;
 					this.__wakeOne();
@@ -191,6 +218,8 @@ class FileBackedQueue {
 					return false;
 				}
 				this.spilled = true;
+				// 文件层翻转 false→true：边沿信号，让监视器记录"开始用磁盘"
+				this.__dispatchSpillStart();
 			}
 
 			try {
@@ -232,6 +261,10 @@ class FileBackedQueue {
 	async clear() {
 		return await this.mutex.withLock(async () => {
 			if (this.destroyed) return;
+			// 与 __dropFile 对称：在重置 spilled 前抓快照，wasSpilled 时配对调 onSpillEnd，
+			// 让监视器 spillActive 复位；否则下一轮真实 spill-start 会被监视器幂等吞掉
+			const drainedBytes = this.writtenBytes;
+			const wasSpilled = this.spilled;
 			await this.__closeWriteStream();
 			try {
 				await fs.rm(this.filePath, { force: true });
@@ -248,6 +281,7 @@ class FileBackedQueue {
 			this.fsBroken = false;
 			this.writeErr = null;
 			this.lastFsErr = null;
+			if (wasSpilled) this.__dispatchSpillEnd(drainedBytes);
 		});
 	}
 
@@ -348,6 +382,7 @@ class FileBackedQueue {
 		for (const w of toWake) w.resolve();
 	}
 
+	// 与 MemoryQueue 一致：诊断职责完全交给注入的 onDrop（监视器做边沿去抖 + 状态翻转 log）
 	__dispatchDrop(reason, size, err) {
 		try {
 			this.onDrop?.(reason, size, err);
@@ -355,7 +390,22 @@ class FileBackedQueue {
 			/* c8 ignore next 2 -- onDrop throwing is caller's bug */
 			this.logger?.warn?.('fbq.onDrop threw', cbErr);
 		}
-		this.logger?.warn?.('fbq.drop', { reason, size, err: err?.message });
+	}
+
+	__dispatchSpillStart() {
+		try { this.onSpillStart?.(); }
+		catch (cbErr) {
+			/* c8 ignore next 2 -- onSpillStart throwing is caller's bug */
+			this.logger?.warn?.('fbq.onSpillStart threw', cbErr);
+		}
+	}
+
+	__dispatchSpillEnd(drainedBytes) {
+		try { this.onSpillEnd?.(drainedBytes); }
+		catch (cbErr) {
+			/* c8 ignore next 2 -- onSpillEnd throwing is caller's bug */
+			this.logger?.warn?.('fbq.onSpillEnd threw', cbErr);
+		}
 	}
 
 	__isBypass(jsonStr) {
@@ -470,8 +520,7 @@ class FileBackedQueue {
 		let cumPayload = 0;   // 仅 payload
 		let stoppedAtEof = true;
 
-		const pendingCount = this.memQueue.length - this.head;
-		const baseCost = this.memBytes + pendingCount * ENTRY_OVERHEAD;
+		const baseBytes = this.memBytes;
 
 		const stream = createReadStream(this.filePath, {
 			start: this.readOffset,
@@ -482,9 +531,9 @@ class FileBackedQueue {
 		try {
 			for await (const line of rl) {
 				const sz = Buffer.byteLength(line, 'utf8');
-				// overhead 一致性：admission 侧已用 overhead，refill 侧同步考虑
-				const newLinesCost = newLines.length * ENTRY_OVERHEAD;
-				if (newLines.length > 0 && baseCost + cumPayload + newLinesCost + sz + ENTRY_OVERHEAD > this.memBudget) {
+				// 与 admission 一致（current ≥ threshold）：当前 mem 总字节 ≥ memBudget 时停止，
+				// 允许首条 single overshoot；后续若仍超阈值再停。
+				if (newLines.length > 0 && baseBytes + cumPayload >= this.memBudget) {
 					stoppedAtEof = false;
 					break;
 				}
@@ -531,6 +580,9 @@ class FileBackedQueue {
 	}
 
 	async __dropFile() {
+		// 抓 drainedBytes 在重置前——让监视器拿到"删除时这文件累计写入了多少字节"
+		const drainedBytes = this.writtenBytes;
+		const wasSpilled = this.spilled;
 		await this.__closeWriteStream();
 		try {
 			await fs.rm(this.filePath, { force: true });
@@ -542,6 +594,9 @@ class FileBackedQueue {
 		this.writtenBytes = 0;
 		this.readOffset = 0;
 		this.writeErr = null;
+		// 文件层翻转 true→false：仅 drain 路径调 spill-end；故障删档（__handleFsError）/
+		// 清理离场（destroy）不调，由 fs-broken / close 信号各自承载，避免语义混淆
+		if (wasSpilled) this.__dispatchSpillEnd(drainedBytes);
 	}
 }
 

package/src/webrtc/rpc-drop-monitor.js

@@ -7,7 +7,8 @@
  *
  * 设计要点：
  * - 工厂函数 + 闭包，不是 class（与项目其它工具模块一致）
- * - 5 个内部标量 + 1 个 idempotent flag 跟踪状态
+ * - 6 个内部状态标量（dropCount / dropBytes / overflowActive / spillActive / fsBroken / lastReason）
+ *   + 1 个 idempotent flag（summarized）跟踪状态
  * - logger / remoteLog 调用一律 try/catch 包裹，自身抛不传染调用方
  * - maybeEmitOverflowEnd 反抖动（候选 A）：仅当 memCount===0 && writtenBytes===0 才翻转
  *   B-stage1 阶段 writtenBytes 恒 0（MemoryQueue），等价 memCount===0
@@ -17,18 +18,27 @@
  * overflow-start 的 queueBytes token：现行取 memBytes，本模块取被拒消息 size，
  * 因为监视器不持队列深度——属可接受漂移）：
  *
- *   warn / remoteLog: rpc-queue.overflow-start conn=X queueBytes=N  (queue-full)
- *   warn / remoteLog: rpc-queue.disk-cap-start  conn=X size=N        (disk-cap)
- *   warn / remoteLog: rpc-queue.fs-broken       conn=X errno=X msg=  (fs-error，sticky)
- *   warn:             [rpc-queue conn=X] oversize size=N             (每条独立)
+ *   warn / remoteLog: rpc-queue.overflow-start conn=X queueBytes=N            (queue-full)
+ *   warn / remoteLog: rpc-queue.disk-cap-start  conn=X size=N memBytes=M
+ *                                               writtenBytes=W diskCap=D     (disk-cap)
+ *   warn / remoteLog: rpc-queue.fs-broken       conn=X errno=X msg=          (fs-error，sticky)
+ *   warn:             [rpc-queue conn=X] oversize size=N                     (每条独立)
  *   info / remoteLog: rpc-queue.overflow-end    conn=X dropped=N droppedBytes=M
- *   remoteLog:        rpc-queue.close           conn=X dropped=N droppedBytes=M
+ *   info / remoteLog: rpc-queue.spill-start     conn=X                       (FBQ 文件创建)
+ *   info / remoteLog: rpc-queue.spill-end       conn=X drainedBytes=N        (FBQ 文件 drain 删除)
+ *   warn / remoteLog: rpc-queue.close           conn=X dropped=N droppedBytes=M
  *                                               residualChunks=K residualBytes=L
  *                                               residualDiskBytes=X residualWrittenBytes=Y
- *                                               fsBroken=bool lastReason=str
+ *                                               fsBroken=bool spillActive=bool lastReason=str
+ *                                                                            (anomaly-only；本地 log 与 remoteLog 同字段)
+ *
+ * spill-start / spill-end 是文件级状态翻转信号：边沿触发，FBQ 在 spilled false→true / true→false
+ * 时通过 onSpillStart / onSpillEnd 钩子回调。与 disk-cap-start 是不同维度的事件——
+ * disk-cap-start 表示 admission 拒收（队列总占用顶到阈值），spill-start 表示物理文件被创建。
+ * MemoryQueue 不调这两个钩子，纯内存路径下不会有 spill 信号。
  *
  * close 日志含两组 disk token（residualDiskBytes/residualWrittenBytes）是为 FBQ 阶段
- * 诊断完整性预留——B-stage1 阶段它们恒 0；B-stage2 切到 FileBackedQueue 时承载磁盘残留信息。
+ * 诊断完整性预留——MemoryQueue 路径下它们恒 0；FBQ 路径下承载磁盘残留信息。
  */
 
 import { remoteLog } from '../remote-log.js';
@@ -38,16 +48,19 @@ import { remoteLog } from '../remote-log.js';
  * @param {string} opts.connId - 连接 ID，用于日志 conn=${connId} token
  * @param {{ warn?: Function, info?: Function, error?: Function }} opts.logger
  * @returns {{
- *   onDrop: (reason: string, size: number, err?: { code?: string, message?: string }) => void,
+ *   onDrop: (reason: string, size: number, err?: { code?: string, message?: string, memBytes?: number, writtenBytes?: number, diskCap?: number }) => void,
+ *   onSpillStart: () => void,
+ *   onSpillEnd: (drainedBytes: number) => void,
  *   maybeEmitOverflowEnd: (stats: { memCount: number, writtenBytes: number }) => void,
- *   summarize: (residualStats?: { memCount?: number, memBytes?: number, diskBytes?: number, writtenBytes?: number }) => void,
- *   getStats: () => { dropCount: number, dropBytes: number, overflowActive: boolean, fsBroken: boolean, lastReason: string|null },
+ *   summarize: (residualStats?: { memCount?: number, memBytes?: number, diskBytes?: number, writtenBytes?: number, fsBroken?: boolean }) => void,
+ *   getStats: () => { dropCount: number, dropBytes: number, overflowActive: boolean, fsBroken: boolean, lastReason: string|null, spillActive: boolean },
  * }}
  */
 export function createRpcDropMonitor({ connId, logger }) {
 	let dropCount = 0;
 	let dropBytes = 0;
 	let overflowActive = false;
+	let spillActive = false; // 文件层翻转标志：FBQ 物理文件存在时 true，drain 删除时 false
 	let fsBroken = false; // sticky：一旦 true 不复位
 	let lastReason = null;
 	let summarized = false; // summarize 幂等 flag
@@ -86,8 +99,13 @@ export function createRpcDropMonitor({ connId, logger }) {
 		if (reason === 'disk-cap') {
 			if (!overflowActive) {
 				overflowActive = true;
-				safeWarn(`disk-cap-start size=${size}`);
-				safeRemoteLog(`rpc-queue.disk-cap-start conn=${connId} size=${size}`);
+				// 把 mem/written/cap 三个分量都带上：disk-cap 不是"文件满了"语义，
+				// 是 mem+writtenBytes 总占用顶到 diskCap 阈值，分量让运维能直接看到谁顶到 cap。
+				const memBytes = err?.memBytes ?? 0;
+				const writtenBytes = err?.writtenBytes ?? 0;
+				const diskCap = err?.diskCap ?? 0;
+				safeWarn(`disk-cap-start size=${size} memBytes=${memBytes} writtenBytes=${writtenBytes} diskCap=${diskCap}`);
+				safeRemoteLog(`rpc-queue.disk-cap-start conn=${connId} size=${size} memBytes=${memBytes} writtenBytes=${writtenBytes} diskCap=${diskCap}`);
 			}
 			return;
 		}
@@ -109,6 +127,23 @@ export function createRpcDropMonitor({ connId, logger }) {
 		// 未知 reason：仅累加，无 log（防御性）
 	}
 
+	// 文件创建：FBQ spilled 翻转 false→true 时调一次。边沿触发，幂等（重复 active 不重 emit）。
+	function onSpillStart() {
+		if (spillActive) return;
+		spillActive = true;
+		safeInfo('spill-start');
+		safeRemoteLog(`rpc-queue.spill-start conn=${connId}`);
+	}
+
+	// 文件删除（drain 完成）：FBQ spilled 翻转 true→false 时调一次。drainedBytes = __dropFile 前的 writtenBytes。
+	// 故障删档（__handleFsError 内的 fs.rm）由 fs-broken 信号承载，不复用此钩子。
+	function onSpillEnd(drainedBytes) {
+		if (!spillActive) return;
+		spillActive = false;
+		safeInfo(`spill-end drainedBytes=${drainedBytes}`);
+		safeRemoteLog(`rpc-queue.spill-end conn=${connId} drainedBytes=${drainedBytes}`);
+	}
+
 	function maybeEmitOverflowEnd(stats) {
 		if (!overflowActive) return;
 		if (!stats) return; // 防御：调用方应传 queue.stats()，但 stats 为 null/undefined 时安全跳过
@@ -127,15 +162,26 @@ export function createRpcDropMonitor({ connId, logger }) {
 		const residualBytes = residualStats?.memBytes ?? 0;
 		const residualDiskBytes = residualStats?.diskBytes ?? 0;
 		const residualWrittenBytes = residualStats?.writtenBytes ?? 0;
-		const hasAnomaly = overflowActive || fsBroken || dropCount > 0
+		// 队列实际 fsBroken 状态：FBQ 经异步路径（writeStream emit error / refill stat err / bypass overshoot 全程仅 mem）可让 fsBroken=true 而 monitor 从未收到 onDrop('fs-error')。
+		// 这里用 residualStats.fsBroken 兜住，让 close 日志反映队列真实降级状态，避免运维侧只能从内部 fsBroken 标量看到"没坏"的假象。
+		const residualFsBroken = residualStats?.fsBroken === true;
+		const effectiveFsBroken = fsBroken || residualFsBroken;
+		// spillActive 也作为 anomaly 信号：destroy 时 spill 文件没 drain 完（onSpillEnd 没触发）
+		// 通常会让 residualWrittenBytes/residualDiskBytes>0 间接触发 close 日志，但显式纳入
+		// spillActive 避免日后 stats 路径漂移（如延迟清空）让"以 spill 状态结束"静默
+		const hasAnomaly = overflowActive || spillActive || effectiveFsBroken || dropCount > 0
 			|| residualChunks > 0 || residualDiskBytes > 0 || residualWrittenBytes > 0;
 		if (hasAnomaly) {
-			safeRemoteLog(
-				`rpc-queue.close conn=${connId} dropped=${dropCount} droppedBytes=${dropBytes}`
+			// 字段表（顺序与 remoteLog 完全一致，便于 server / 本地 log 对齐 grep）
+			const fields = `dropped=${dropCount} droppedBytes=${dropBytes}`
 				+ ` residualChunks=${residualChunks} residualBytes=${residualBytes}`
 				+ ` residualDiskBytes=${residualDiskBytes} residualWrittenBytes=${residualWrittenBytes}`
-				+ ` fsBroken=${fsBroken} lastReason=${lastReason ?? 'none'}`,
-			);
+				+ ` fsBroken=${effectiveFsBroken} spillActive=${spillActive}`
+				+ ` lastReason=${lastReason ?? 'none'}`;
+			// 本地 log 镜像：close 是 session 收尾的异常汇总，开发者主要看本地 log 排查。
+			// 与 overflow-start/disk-cap-start/fs-broken 同级别用 warn——只有 anomaly 时才发。
+			safeWarn(`close ${fields}`);
+			safeRemoteLog(`rpc-queue.close conn=${connId} ${fields}`);
 		}
 		overflowActive = false;
 	}
@@ -145,10 +191,11 @@ export function createRpcDropMonitor({ connId, logger }) {
 			dropCount,
 			dropBytes,
 			overflowActive,
+			spillActive,
 			fsBroken,
 			lastReason,
 		};
 	}
 
-	return { onDrop, maybeEmitOverflowEnd, summarize, getStats };
+	return { onDrop, onSpillStart, onSpillEnd, maybeEmitOverflowEnd, summarize, getStats };
 }

package/src/webrtc/webrtc-peer.js

@@ -9,11 +9,11 @@ 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'：FileBackedQueue（当前生产默认）—— 长时间后台 / ICE 恢复等慢消化场景溢出到磁盘
+// - 'mem'：MemoryQueue —— 不碰 fs，溢出即 drop（紧急回退用，0.20.1~0.20.2 期间临时启用）
 // 当 'fbq' 但 queueDir 不可用（bridge 启动期 plan-2 prep 失败）时自动降级到 'mem'，避免阻塞 webrtc 装配。
-// 单点常量；构造时可通过 `rpcQueueImpl` opt 覆盖（测试用）。生产侧改回 'fbq' 只需翻这一行。
-const RPC_QUEUE_IMPL = 'mem';
+// 单点常量；构造时可通过 `rpcQueueImpl` opt 覆盖（测试用）。紧急回退到 'mem' 只需翻这一行。
+const RPC_QUEUE_IMPL = 'fbq';
 
 // FBQ 装配兜底：bridge 启动期 measureDiskCap 失败 → __diskCap=null → 这里兜底 1GB
 const ONE_GB = 1024 * 1024 * 1024;
@@ -152,7 +152,7 @@ export class WebRtcPeer {
 		await Promise.all(closing);
 	}
 
-	/** 向所有已打开的 rpcChannel 广播（大消息自动分片，经由 MemoryQueue + RpcDcSender 流控） */
+	/** 向所有已打开的 rpcChannel 广播（大消息自动分片，经由 FBQ/MemoryQueue + RpcDcSender 流控） */
 	broadcast(payload) {
 		let jsonStr;
 		try {
@@ -664,7 +664,10 @@ export class WebRtcPeer {
 				// 但 destroy 是 fire-and-forget，回调在 mutex 异步内才 fire 时字段已 null。
 				sess.rpcDcSender?.close();
 				const monRef = sess.rpcDropMonitor;
-				sess.rpcQueue?.destroy((residual) => { monRef?.summarize(residual); }).catch(() => {});
+				sess.rpcQueue?.destroy((residual) => { monRef?.summarize(residual); }).catch((err) => {
+					/* c8 ignore next 2 -- destroy 在生产路径稳定（mutex 内异常极冷），仅诊断兜底 */
+					this.logger.warn?.(`${this.__rtcTag} [${connId}] rpc queue destroy failed in dc.onclose: ${err?.message ?? err}`);
+				});
 				sess.rpcDcSender = null;
 				sess.rpcQueue = null;
 				sess.rpcConsumeLoop = null;
@@ -691,18 +694,30 @@ export class WebRtcPeer {
 		// 罕见：session 已有旧三件套（UI 重建 rpc DC 等）。先 await close + destroy 旧实例
 		// 再造新实例，避免新旧 queue/sender 在同一 session 上并存。summarize 走 destroy 的
 		// onBeforeClear 钩子，确保拿到原子残留快照（in-flight enqueue 已落地）。
+		//
+		// race 闭合：先**同步**捕获旧引用 + 把四个字段置 null，再 await 旧实例 destroy。
+		// 否则 sync ondatachannel 已把 rpcChannel 切到新 dc（readyState='open'），但 rpcQueue
+		// 等字段保留到 await destroy 完成；这窗口里 broadcast / sendTo 看到 "rpcQueue=旧 +
+		// rpcChannel=新 dc open" 会把消息塞进即将销毁的旧 queue。sync nullify 后窗口里 broadcast
+		// 看到 rpcQueue=null 跳过（与"通道未就绪"等价）。
 		if (session.rpcDcSender || session.rpcQueue) {
-			session.rpcDcSender?.close();
+			const oldSender = session.rpcDcSender;
+			const oldQueue = session.rpcQueue;
+			const oldLoop = session.rpcConsumeLoop;
 			const oldMonitor = session.rpcDropMonitor;
-			if (session.rpcQueue) await session.rpcQueue.destroy((residual) => { oldMonitor?.summarize(residual); });
-			if (session.rpcConsumeLoop) await session.rpcConsumeLoop.catch(() => { /* c8 ignore next -- 极冷防御 */ });
+			session.rpcDcSender = null;
+			session.rpcQueue = null;
+			session.rpcConsumeLoop = null;
 			session.rpcDropMonitor = null;
+			oldSender?.close();
+			if (oldQueue) await oldQueue.destroy((residual) => { oldMonitor?.summarize(residual); });
+			if (oldLoop) await oldLoop.catch(() => { /* c8 ignore next -- 极冷防御 */ });
 		}
 		// 创建 monitor。必须在 new Queue 之前——Queue 的 onDrop 接 monitor.onDrop。
 		// monitor 是局部变量，stale 路径下函数返回后自然 GC，不挂 session 字段（无 drop 可汇总）。
 		const monitor = createRpcDropMonitor({ connId, logger: this.logger });
 
-		// queue 实例选择（B-stage2 B9b）：默认取模块级 RPC_QUEUE_IMPL（当前 'mem'）；
+		// queue 实例选择（B-stage2 B9b）：默认取模块级 RPC_QUEUE_IMPL（当前 'fbq'）；
 		// 'fbq' 模式下若 queueDir 不可用则降级到 mem，避免阻塞装配。
 		// 同 connId race 隔离（决策 4）：FBQ id 加唯一后缀 ${connId}-${ts}-${nonce}，
 		// 让新旧实例文件名物理不同，destroy/init 期间互不踩踏。MemoryQueue 不碰 fs，无此需求。
@@ -716,10 +731,14 @@ export class WebRtcPeer {
 				id: `${connId}-${Date.now()}-${randomUUID().slice(0, 8)}`,
 				dir: this.__queueDir,
 				memBudget: RPC_QUEUE_MEM_BUDGET,
+				// diskCap 是 mem + 已写文件累计字节（writtenBytes）的总占用阈值，不是单纯文件 size
+				// 上限——因此文件实际峰值约为 diskCap - memBudget；详见 docs/rpc-dc-file-queue.md
 				diskCap: this.__getDiskCap?.() ?? ONE_GB,
 				maxMessageBytes: MAX_SINGLE_MSG_BYTES,
 				bypassAdmission: isAgentRunResponse,
 				onDrop: monitor.onDrop,
+				onSpillStart: monitor.onSpillStart,
+				onSpillEnd: monitor.onSpillEnd,
 				logger: this.logger,
 			})
 			: new MemoryQueue({
@@ -822,7 +841,7 @@ export class WebRtcPeer {
 			? (() => {
 				const s = q.stats();
 				// memCount 沿用历史 token 名 queueLen（不改名）；queue.stats() 6 个字段（含 4 个
-				// 磁盘字段，MemoryQueue 阶段恒 0/false）+ monitor.getStats() 提供 dropCount/dropBytes。
+				// 磁盘字段，MemoryQueue 路径下恒 0/false）+ monitor.getStats() 提供 dropCount/dropBytes。
 				// 输出文本 8 token 字节级保持与现行格式一致。
 				// monitor 与 queue 在 setupDataChannel 末尾同 tick 装载，q 真值时 monitor 必定也存在；
 				// `?? { ... }` 是防御性兜底，结构上不可达。