@coclaw/openclaw-coclaw 0.19.2 → 0.20.0

package/src/rpc-routing/run-event-routes.js

@@ -0,0 +1,138 @@
+/**
+ * runId → connId 路由表（已集成于 realtime-bridge）
+ *
+ * 用途：把 OpenClaw gateway 推来的 `event:agent` 帧按 runId 单播给真正发起这个 run 的 DC，
+ * 避免多 PC 场景下"广播给所有连过来的 rpc DC"导致死 PC 也收到的问题。
+ *
+ * 设计要点：
+ * - 构造函数纯组装，无副作用；起 timer 走 init()，停 timer 走 destroy()
+ * - destroy 后 add / remove / lookup / clear / init 全是 no-op
+ * - add 写入策略：runId 不在表写入；同 reqId 刷新 expireAt；不同 reqId 跳过覆盖（首发优先）
+ * - remove 删除策略：runId 在表 + entry.reqId === 入参 reqId 才删（防跨 RPC 巧合 runId 误删）
+ * - lookup hot path：不顺手清过期，TTL 由 scan timer 负责
+ * - scan 整段 try/catch 兜底，logger 抛错也不能击穿 gateway 进程
+ * - timer 必须 unref()——避免 hold 进程退出
+ *
+ * 与 reqId 路由表（realtime-bridge.js __dcPendingRequests）保持行为对齐：
+ * 对 PC 关闭不做联动清理，TTL 兜底；网关 WS 断开走 clear()。
+ */
+
+/** 路由条目最大存活时间（24h），与 reqId 表对齐 */
+export const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000;
+/** 整表周期扫描间隔（1h），与 reqId 表对齐 */
+export const DEFAULT_SCAN_MS = 60 * 60 * 1000;
+
+export class RunEventRoutes {
+	/**
+	 * @param {object} [opts]
+	 * @param {{ info?: Function, warn?: Function, error?: Function, debug?: Function }} [opts.logger=console]
+	 * @param {number} [opts.ttlMs=DEFAULT_TTL_MS]
+	 * @param {number} [opts.scanMs=DEFAULT_SCAN_MS]
+	 */
+	constructor({ logger, ttlMs, scanMs } = {}) {
+		this.logger = logger ?? console;
+		this.ttlMs = ttlMs ?? DEFAULT_TTL_MS;
+		this.scanMs = scanMs ?? DEFAULT_SCAN_MS;
+		/** @type {Map<string, { connId: string, reqId: string, expireAt: number }>} */
+		this.__entries = new Map();
+		this.__scanTimer = null;
+		this.__destroyed = false;
+	}
+
+	/** 起周期扫描 timer。重入安全：已 init / 已 destroy 均 no-op */
+	init() {
+		if (this.__destroyed) return;
+		if (this.__scanTimer) return;
+		this.__scanTimer = setInterval(() => this.__scanExpired(), this.scanMs);
+		this.__scanTimer.unref?.();
+	}
+
+	/**
+	 * 添加路由条目。任一参数 falsy 静默返回（防御性）。
+	 * @param {string} runId
+	 * @param {string} connId
+	 * @param {string} reqId
+	 */
+	add(runId, connId, reqId) {
+		if (this.__destroyed) return;
+		if (!runId || !connId || !reqId) return;
+		const existing = this.__entries.get(runId);
+		const expireAt = Date.now() + this.ttlMs;
+		if (existing && existing.reqId !== reqId) {
+			// 已被首发占用，跳过覆盖（防 attach 抢路由）。debug 日志便于观察。
+			// logger.debug 自身抛错也不能让 add 失败（与 __scanExpired 内的 try/catch 风格一致）
+			try { this.logger.debug?.(`[run-event-routes] add skipped: runId already routed by reqId=${existing.reqId} new reqId=${reqId}`); }
+			catch { /* logger 自身坏了不能让 add 抛 */ }
+			return;
+		}
+		// 同 reqId 重发：仅刷新 expireAt，connId 锁死在首发值（首发优先的彻底化）
+		if (existing) {
+			existing.expireAt = expireAt;
+			return;
+		}
+		this.__entries.set(runId, { connId, reqId, expireAt });
+	}
+
+	/**
+	 * 移除路由条目。runId 在表且 entry.reqId === 入参 reqId 才删。
+	 * @param {string} runId
+	 * @param {string} reqId
+	 */
+	remove(runId, reqId) {
+		if (this.__destroyed) return;
+		if (!runId || !reqId) return;
+		const entry = this.__entries.get(runId);
+		if (!entry) return;
+		if (entry.reqId !== reqId) return;
+		this.__entries.delete(runId);
+	}
+
+	/**
+	 * 查路由 → connId 或 undefined。不顺手清过期。
+	 * @param {string} runId
+	 * @returns {string | undefined}
+	 */
+	lookup(runId) {
+		if (this.__destroyed) return undefined;
+		if (!runId) return undefined;
+		const entry = this.__entries.get(runId);
+		return entry?.connId;
+	}
+
+	/** 整表清空。不动 timer（语义=网关 WS 断开后清表，保留 scan 给后续 init 用）*/
+	clear() {
+		if (this.__destroyed) return;
+		this.__entries.clear();
+	}
+
+	/** 停 timer + clear + 标 destroyed。幂等。*/
+	destroy() {
+		if (this.__destroyed) return;
+		this.__destroyed = true;
+		if (this.__scanTimer) {
+			clearInterval(this.__scanTimer);
+			this.__scanTimer = null;
+		}
+		this.__entries.clear();
+	}
+
+	/** 内部扫描过期条目；try/catch 兜底，避免 timer 回调异常击穿 gateway 进程 */
+	__scanExpired() {
+		try {
+			const now = Date.now();
+			let cleaned = 0;
+			for (const [runId, entry] of this.__entries) {
+				if (entry.expireAt <= now) {
+					this.__entries.delete(runId);
+					cleaned += 1;
+				}
+			}
+			if (cleaned > 0) {
+				this.logger.warn?.(`[run-event-routes] expired entries cleaned: count=${cleaned}`);
+			}
+		}
+		catch {
+			// 扫描器自身异常静默吞掉，避免拖垮 gateway（如 logger.warn 抛错）
+		}
+	}
+}

package/src/session-manager/manager.js

@@ -1,7 +1,8 @@
 import fs from 'node:fs';
-import os from 'node:os';
 import nodePath from 'node:path';
 
+import { agentSessionsDir, sessionStorePath, sessionTranscriptPath } from '../claw-paths.js';
+
 const DERIVED_TITLE_MAX_LEN = 60;
 
 // OC 注入的 inbound metadata 头部（Conversation info / Sender / Thread starter 等）
@@ -172,18 +173,22 @@ function deriveTitle(filePath, logger) {
 }
 
 export function createSessionManager(options = {}) {
-	const rootDir = options.rootDir ?? nodePath.join(os.homedir(), '.openclaw', 'agents');
 	/* c8 ignore next */
 	const logger = options.logger ?? console;
+	const resolveSessionsDir = options.resolveSessionsDir ?? agentSessionsDir;
+	const resolveStorePath = options.resolveStorePath ?? sessionStorePath;
+	const resolveTranscriptPath = options.resolveTranscriptPath ?? sessionTranscriptPath;
 
 	function sessionsDir(agentId = 'main') {
 		/* c8 ignore next */
 		const aid = typeof agentId === 'string' && agentId.trim() ? agentId.trim() : 'main';
-		return nodePath.join(rootDir, aid, 'sessions');
+		return resolveSessionsDir(aid);
 	}
 
 	function readIndex(agentId = 'main') {
-		const file = nodePath.join(sessionsDir(agentId), 'sessions.json');
+		/* c8 ignore next */
+		const aid = typeof agentId === 'string' && agentId.trim() ? agentId.trim() : 'main';
+		const file = resolveStorePath(aid);
 		const data = readJsonSafe(file, {});
 		/* c8 ignore next */
 		if (!data || typeof data !== 'object') return {};
@@ -279,7 +284,7 @@ export function createSessionManager(options = {}) {
 		const dir = sessionsDir(agentId);
 		// live 文件优先：同一 sessionId 可能同时存在 live 和 reset 文件
 		// （OpenClaw reset 后复用 sessionId），live 代表当前活跃 transcript
-		const livePath = nodePath.join(dir, `${sessionId}.jsonl`);
+		const livePath = resolveTranscriptPath(sessionId, agentId);
 		if (fs.existsSync(livePath)) {
 			return livePath;
 		}

package/src/settings.js

@@ -2,7 +2,7 @@ import fs from 'node:fs/promises';
 import os from 'node:os';
 import nodePath from 'node:path';
 
-import { resolveStateDir, CHANNEL_ID } from './config.js';
+import { pluginDir } from './claw-paths.js';
 import { atomicWriteJsonFile } from './utils/atomic-write.js';
 import { createMutex } from './utils/mutex.js';
 
@@ -12,7 +12,7 @@ export const MAX_NAME_LENGTH = 63;
 const settingsMutex = createMutex();
 
 function getSettingsPath() {
-	return nodePath.join(resolveStateDir(), CHANNEL_ID, SETTINGS_FILENAME);
+	return nodePath.join(pluginDir(), SETTINGS_FILENAME);
 }
 
 async function readJsonSafe(filePath) {

package/src/topic-manager/manager.js

@@ -1,8 +1,8 @@
 import fs from 'node:fs/promises';
-import os from 'node:os';
 import nodePath from 'node:path';
 import { randomUUID } from 'node:crypto';
 
+import { agentSessionsDir } from '../claw-paths.js';
 import { atomicWriteJsonFile } from '../utils/atomic-write.js';
 import { createMutex } from '../utils/mutex.js';
 
@@ -21,16 +21,15 @@ function emptyStore() {
 export class TopicManager {
 	/**
 	 * @param {object} [opts]
-	 * @param {string} [opts.rootDir] - agents 根目录，默认 ~/.openclaw/agents
 	 * @param {object} [opts.logger]
+	 * @param {Function} [opts.resolveSessionsDir] - 测试注入：自定义 sessions 目录解析
 	 * @param {Function} [opts.readFile] - 测试注入
 	 * @param {Function} [opts.writeJsonFile] - 测试注入
 	 * @param {Function} [opts.unlinkFile] - 测试注入
 	 * @param {Function} [opts.copyFile] - 测试注入
 	 */
 	constructor(opts = {}) {
-		/* c8 ignore next 6 -- ?? fallback：测试始终注入 */
-		this.__rootDir = opts.rootDir ?? nodePath.join(os.homedir(), '.openclaw', 'agents');
+		this.__resolveSessionsDir = opts.resolveSessionsDir ?? agentSessionsDir;
 		this.__logger = opts.logger ?? console;
 		this.__readFile = opts.readFile ?? fs.readFile;
 		this.__writeJsonFile = opts.writeJsonFile ?? atomicWriteJsonFile;
@@ -45,7 +44,7 @@ export class TopicManager {
 	}
 
 	__sessionsDir(agentId) {
-		return nodePath.join(this.__rootDir, agentId, 'sessions');
+		return this.__resolveSessionsDir(agentId);
 	}
 
 	__topicsFilePath(agentId) {

package/src/utils/memory-queue.js

@@ -1,18 +1,19 @@
 /**
  * 纯内存版 FBQ-API 兼容容器
  *
- * 阶段 1 用作 RpcDcSender 的前置缓冲，替换原 `RpcSendQueue` 中的"容器层"职责（admission +
- * overflow 边沿状态机 + close 汇总）。阶段 2 再把本模块替换为 `FileBackedQueue`，因接口对齐，
- * 替换近乎一行 import 改动。
+ * 阶段 1 用作 RpcDcSender 的前置缓冲，与 `FileBackedQueue` 接口对齐。阶段 2 单点平替，
+ * webrtc-peer 仅一行 `new` 改写。
  *
  * 与 FBQ 的差异：
  * - 不引入 fs；`diskBytes / writtenBytes` 永为 0，`spilled / fsBroken` 永为 false
- * - admission 仅基于 `memBudget`；命中 `bypassAdmission(jsonStr)` 时即使队列满也接收（保留
- *   `RpcSendQueue` 的 agent run 白名单豁免行为）
- * - 内部携带 overflow-start/-end 边沿状态机和 close 汇总日志（搬自原 `RpcSendQueue`）
+ * - admission 仅基于 `memBudget`；命中 `bypassAdmission(jsonStr)` 时即使队列满也接收
  *
- * 契约：`enqueue / __nextIter / destroy / clear` 内部任何分支都不得因 logger / remoteLog / onDrop /
- * bypassAdmission 自身抛而传染调用方——所有外部调用均经过 safe wrapper（try/catch）。
+ * 容器纯净化（B-stage1）：本模块不承担诊断职责（边沿日志、累计、汇总），仅通过
+ * `onDrop(reason, size)` 回调把丢弃事件外抛，由调用方（rpc-drop-monitor 等）统一
+ * 处理日志输出。容器与诊断解耦后 MemoryQueue ≡ FBQ minus 磁盘语义。
+ *
+ * 契约：`enqueue / __nextIter / destroy / clear` 内部任何分支都不得因 onDrop /
+ * bypassAdmission 自身抛而传染调用方——所有外部回调均经过 try/catch 包裹。
  *
  * 使用方式（消费侧）：
  * ```js
@@ -21,7 +22,6 @@
  * 调用 `queue.destroy()` 后 iterator 在下一轮返回 `{ done: true }`。
  */
 
-import { remoteLog } from '../remote-log.js';
 import { createMutex } from './mutex.js';
 
 /** 默认内存预算：与原 RpcSendQueue 的 MAX_QUEUE_BYTES 对齐 */
@@ -85,11 +85,6 @@ class MemoryQueue {
 		this.destroyed = false;
 		this.waiters = [];
 		this.mutex = createMutex();
-
-		// drop 统计 + overflow 边沿状态机
-		this.droppedCount = 0;
-		this.droppedBytes = 0;
-		this.queueOverflowActive = false;
 	}
 
 	/**
@@ -107,15 +102,21 @@ class MemoryQueue {
 
 	/**
 	 * 入队一条字符串。
-	 * - 队列满（memBytes >= memBudget）且未命中 bypassAdmission → onDrop + 返回 false
-	 *   首次进入溢出态打 overflow-start（warn + remoteLog），持续期间静默累加
+	 * - destroyed → 直接返回 false（**silent 短路**，**不触发 onDrop**）。设计意图：destroyed
+	 *   意味着对应连接已死/正在清理，丢弃是正确清理副作用，不需要 noisy 日志。loud-on-loss
+	 *   红线只对"连接活着但拒收"场景生效（oversize / queue-full）。
+	 * - 单条 size > maxMessageBytes（bypass 也不豁免）→ onDrop('oversize', size) + 返回 false
+	 * - 队列满（memBytes >= memBudget）且未命中 bypassAdmission → onDrop('queue-full', size) + 返回 false
 	 * - 否则入队 + 返回 true（包括"单条 overshoot"：当前 memBytes < memBudget，但本条很大）
 	 *
+	 * 不输出任何日志/累计：诊断职责由调用方注入的 onDrop 处理。
+	 *
 	 * @param {string} jsonStr
 	 * @returns {Promise<boolean>}
 	 */
 	async enqueue(jsonStr) {
 		return await this.mutex.withLock(async () => {
+			// destroyed 短路：silent，不调 onDrop。详见上方 JSDoc。
 			if (this.destroyed) return false;
 			if (typeof jsonStr !== 'string') throw new TypeError('jsonStr must be a string');
 
@@ -124,10 +125,7 @@ class MemoryQueue {
 			// per-message 硬上限：bypass 也不豁免。对齐 sender 端 MAX_SINGLE_MSG_BYTES 检查，
 			// 避免大帧先入队再被 sender 拒，导致 memBytes 异常膨胀（特别是 sender 阻塞期间）。
 			if (size > this.maxMessageBytes) {
-				this.droppedCount += 1;
-				this.droppedBytes += size;
 				this.__dispatchDrop('oversize', size);
-				this.__safeWarn(`drop reason=oversize size=${size} cap=${this.maxMessageBytes}`);
 				return false;
 			}
 
@@ -135,15 +133,7 @@ class MemoryQueue {
 			// 允许"单条 overshoot"：上一条消息把 queueBytes 顶到 < MAX 但 >= MAX 之间任一值时
 			// 仍能入队；下一次再有非白名单消息才会被 drop。
 			if (this.memBytes >= this.memBudget && !this.__isBypass(jsonStr)) {
-				this.droppedCount += 1;
-				this.droppedBytes += size;
 				this.__dispatchDrop('queue-full', size);
-				// 仅状态翻转点打 log，避免 DC 卡死时刷屏
-				if (!this.queueOverflowActive) {
-					this.queueOverflowActive = true;
-					this.__safeWarn(`overflow-start queueBytes=${this.memBytes}`);
-					this.__safeRemoteLog(`rpc-queue.overflow-start${this.__tagSuffix()} queueBytes=${this.memBytes}`);
-				}
 				return false;
 			}
 
@@ -155,11 +145,10 @@ class MemoryQueue {
 	}
 
 	/**
-	 * 当前快照，用于诊断 dump。形态与 FBQ 对齐 + 阶段 1 私有诊断字段。
+	 * 当前快照，用于诊断 dump。形态与 FBQ 完全对齐（6 字段）。
 	 * @returns {{
 	 *   memCount: number, memBytes: number, diskBytes: number, writtenBytes: number,
-	 *   spilled: boolean, fsBroken: boolean,
-	 *   droppedCount: number, droppedBytes: number, queueOverflowActive: boolean
+	 *   spilled: boolean, fsBroken: boolean
 	 * }}
 	 */
 	stats() {
@@ -170,14 +159,11 @@ class MemoryQueue {
 			writtenBytes: 0,
 			spilled: false,
 			fsBroken: false,
-			droppedCount: this.droppedCount,
-			droppedBytes: this.droppedBytes,
-			queueOverflowActive: this.queueOverflowActive,
 		};
 	}
 
 	/**
-	 * 清空数据但保留实例可用，重置 drop 统计与 overflow 状态。
+	 * 清空数据但保留实例可用。
 	 */
 	async clear() {
 		return await this.mutex.withLock(async () => {
@@ -185,22 +171,38 @@ class MemoryQueue {
 			this.memQueue = [];
 			this.head = 0;
 			this.memBytes = 0;
-			this.droppedCount = 0;
-			this.droppedBytes = 0;
-			this.queueOverflowActive = false;
 		});
 	}
 
 	/**
-	 * 关闭队列：唤醒所有 waiter（让 iterator 返回 done）、汇总 drop/residual log。幂等。
+	 * 关闭队列：唤醒所有 waiter（让 iterator 返回 done）。幂等。
+	 * 不输出汇总日志：close 汇总职责由调用方注入的 monitor.summarize 处理。
+	 *
+	 * @param {(residual: { memCount: number, memBytes: number, diskBytes: number, writtenBytes: number, spilled: boolean, fsBroken: boolean }) => void} [onBeforeClear]
+	 *   可选回调（**必须为同步函数**）：在 mutex 内、清空 memQueue **之前**触发，参数是销毁时刻的残留快照。
+	 *   存在意义：mutex 保证 in-flight enqueue 已落地（broadcast 是 fire-and-forget），调用方
+	 *   sync 调 `queue.stats()` 读不到 in-flight 入队的消息；改用此回调可拿到原子准确的残留快照。
+	 *   回调同步抛错被 swallow，不影响 destroy 完成。
+	 *   **注意**：返回 Promise 的异步回调其 rejection 不会被捕获——仅设计为 sync 钩子。
 	 */
-	async destroy() {
+	async destroy(onBeforeClear) {
 		return await this.mutex.withLock(async () => {
 			if (this.destroyed) return;
 			this.destroyed = true;
 
-			const residual = this.memQueue.length - this.head;
-			const residualBytes = this.memBytes;
+			// 在 mutex 内、清空之前快照残留：保证看到所有已入队的消息（含 in-flight）
+			if (typeof onBeforeClear === 'function') {
+				const residual = {
+					memCount: this.memQueue.length - this.head,
+					memBytes: this.memBytes,
+					diskBytes: 0,
+					writtenBytes: 0,
+					spilled: false,
+					fsBroken: false,
+				};
+				try { onBeforeClear(residual); }
+				catch { /* 回调自身抛是调用方的 bug；不能传染给 destroy 契约 */ }
+			}
 
 			// 唤醒所有等待者，让它们在下一轮循环看到 destroyed 并返回 done
 			const toWake = this.waiters.splice(0);
@@ -209,12 +211,6 @@ class MemoryQueue {
 			this.memQueue = [];
 			this.head = 0;
 			this.memBytes = 0;
-
-			if (this.droppedCount > 0 || residual > 0) {
-				this.__safeRemoteLog(
-					`rpc-queue.close${this.__tagSuffix()} dropped=${this.droppedCount} droppedBytes=${this.droppedBytes} residualChunks=${residual} residualBytes=${residualBytes}`,
-				);
-			}
 		});
 	}
 
@@ -243,14 +239,6 @@ class MemoryQueue {
 						this.head = 0;
 					}
 
-					// 满 → 未满 状态翻转：与 overflow-start 对称，含累计 dropped
-					if (this.queueOverflowActive && this.memBytes < this.memBudget) {
-						this.queueOverflowActive = false;
-						this.__safeInfo(`overflow-end dropped=${this.droppedCount} droppedBytes=${this.droppedBytes}`);
-						this.__safeRemoteLog(
-							`rpc-queue.overflow-end${this.__tagSuffix()} dropped=${this.droppedCount} droppedBytes=${this.droppedBytes}`,
-						);
-					}
 					return { value: item, done: false };
 				}
 				if (this.destroyed) return { done: true, value: undefined };
@@ -297,14 +285,6 @@ class MemoryQueue {
 	__safeWarn(msg) {
 		try { this.logger.warn?.(`[rpc-queue${this.__tagSuffix()}] ${msg}`); } catch { /* logger 自身坏了也不能让 enqueue 抛 */ }
 	}
-
-	__safeInfo(msg) {
-		try { this.logger.info?.(`[rpc-queue${this.__tagSuffix()}] ${msg}`); } catch { /* logger 自身坏了也不能让 enqueue/__nextIter 抛 */ }
-	}
-
-	__safeRemoteLog(text) {
-		try { remoteLog(text); } catch { /* 防御性：remoteLog 当前同步路径不抛，未来若变化此 wrapper 兜底 */ }
-	}
 }
 
 export { MemoryQueue };

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

@@ -0,0 +1,154 @@
+/**
+ * rpc DC 发送链路的"丢弃监视器"——独立模块，与队列容器解耦。
+ *
+ * 职责：承接 MemoryQueue / FileBackedQueue 的 onDrop 事件，做边沿状态机日志、
+ * 累计计数、关闭汇总。容器（队列）只负责数据缓冲，不知道日志策略；监视器只
+ * 知道事件，不知道队列内部结构。两者通过 onDrop(reason, size, err?) 契约对接。
+ *
+ * 设计要点：
+ * - 工厂函数 + 闭包，不是 class（与项目其它工具模块一致）
+ * - 5 个内部标量 + 1 个 idempotent flag 跟踪状态
+ * - logger / remoteLog 调用一律 try/catch 包裹，自身抛不传染调用方
+ * - maybeEmitOverflowEnd 反抖动（候选 A）：仅当 memCount===0 && writtenBytes===0 才翻转
+ *   B-stage1 阶段 writtenBytes 恒 0（MemoryQueue），等价 memCount===0
+ *   B-stage2 切 FBQ 时同一行代码自然抗"刚出列又写盘"的抖动
+ *
+ * 日志格式约定（与现行 MemoryQueue 内嵌日志保持一致；唯一漂移点是
+ * 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             (每条独立)
+ *   info / remoteLog: rpc-queue.overflow-end    conn=X dropped=N droppedBytes=M
+ *   remoteLog:        rpc-queue.close           conn=X dropped=N droppedBytes=M
+ *                                               residualChunks=K residualBytes=L
+ *                                               residualDiskBytes=X residualWrittenBytes=Y
+ *                                               fsBroken=bool lastReason=str
+ *
+ * close 日志含两组 disk token（residualDiskBytes/residualWrittenBytes）是为 FBQ 阶段
+ * 诊断完整性预留——B-stage1 阶段它们恒 0；B-stage2 切到 FileBackedQueue 时承载磁盘残留信息。
+ */
+
+import { remoteLog } from '../remote-log.js';
+
+/**
+ * @param {object} opts
+ * @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,
+ *   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 },
+ * }}
+ */
+export function createRpcDropMonitor({ connId, logger }) {
+	let dropCount = 0;
+	let dropBytes = 0;
+	let overflowActive = false;
+	let fsBroken = false; // sticky：一旦 true 不复位
+	let lastReason = null;
+	let summarized = false; // summarize 幂等 flag
+
+	const tag = `[rpc-queue conn=${connId}]`;
+
+	function safeWarn(msg) {
+		try { logger?.warn?.(`${tag} ${msg}`); }
+		catch { /* logger 自身坏了也不能让 onDrop 抛 */ }
+	}
+
+	function safeInfo(msg) {
+		try { logger?.info?.(`${tag} ${msg}`); }
+		catch { /* 同上 */ }
+	}
+
+	function safeRemoteLog(text) {
+		try { remoteLog(text); }
+		catch { /* remoteLog 当前同步路径不抛；防御性兜底 */ }
+	}
+
+	function onDrop(reason, size, err) {
+		dropCount += 1;
+		dropBytes += size;
+		lastReason = reason;
+
+		if (reason === 'queue-full') {
+			if (!overflowActive) {
+				overflowActive = true;
+				safeWarn(`overflow-start queueBytes=${size}`);
+				safeRemoteLog(`rpc-queue.overflow-start conn=${connId} queueBytes=${size}`);
+			}
+			// 持续期间静默
+			return;
+		}
+		if (reason === 'disk-cap') {
+			if (!overflowActive) {
+				overflowActive = true;
+				safeWarn(`disk-cap-start size=${size}`);
+				safeRemoteLog(`rpc-queue.disk-cap-start conn=${connId} size=${size}`);
+			}
+			return;
+		}
+		if (reason === 'fs-error') {
+			if (!fsBroken) {
+				fsBroken = true;
+				const errno = err?.code ?? 'UNKNOWN';
+				const errMsg = err?.message ?? '';
+				safeWarn(`fs-broken errno=${errno} msg=${errMsg}`);
+				safeRemoteLog(`rpc-queue.fs-broken conn=${connId} errno=${errno} msg=${errMsg}`);
+			}
+			return;
+		}
+		if (reason === 'oversize') {
+			// 每次独立 warn，不改 overflowActive
+			safeWarn(`oversize size=${size}`);
+			return;
+		}
+		// 未知 reason：仅累加，无 log（防御性）
+	}
+
+	function maybeEmitOverflowEnd(stats) {
+		if (!overflowActive) return;
+		if (!stats) return; // 防御：调用方应传 queue.stats()，但 stats 为 null/undefined 时安全跳过
+		if (stats.memCount === 0 && stats.writtenBytes === 0) {
+			overflowActive = false;
+			safeInfo(`overflow-end dropped=${dropCount} droppedBytes=${dropBytes}`);
+			safeRemoteLog(`rpc-queue.overflow-end conn=${connId} dropped=${dropCount} droppedBytes=${dropBytes}`);
+		}
+	}
+
+	function summarize(residualStats) {
+		if (summarized) return;
+		summarized = true;
+
+		const residualChunks = residualStats?.memCount ?? 0;
+		const residualBytes = residualStats?.memBytes ?? 0;
+		const residualDiskBytes = residualStats?.diskBytes ?? 0;
+		const residualWrittenBytes = residualStats?.writtenBytes ?? 0;
+		const hasAnomaly = overflowActive || fsBroken || dropCount > 0
+			|| residualChunks > 0 || residualDiskBytes > 0 || residualWrittenBytes > 0;
+		if (hasAnomaly) {
+			safeRemoteLog(
+				`rpc-queue.close conn=${connId} dropped=${dropCount} droppedBytes=${dropBytes}`
+				+ ` residualChunks=${residualChunks} residualBytes=${residualBytes}`
+				+ ` residualDiskBytes=${residualDiskBytes} residualWrittenBytes=${residualWrittenBytes}`
+				+ ` fsBroken=${fsBroken} lastReason=${lastReason ?? 'none'}`,
+			);
+		}
+		overflowActive = false;
+	}
+
+	function getStats() {
+		return {
+			dropCount,
+			dropBytes,
+			overflowActive,
+			fsBroken,
+			lastReason,
+		};
+	}
+
+	return { onDrop, maybeEmitOverflowEnd, summarize, getStats };
+}