@coclaw/openclaw-coclaw 0.19.2 → 0.20.1

package/src/rpc-queue-startup.js

@@ -0,0 +1,103 @@
+/**
+ * rpc-queues/ 启动期预热（B-stage1 plan-2）。
+ *
+ * 提供两个 async 函数，均**永不抛**——bridge.start 不能被启动期 fs 操作阻断：
+ *
+ * - `cleanupResiduals(dir, opts)`：mkdir { recursive: true } → readdir →
+ *   按 `*.jsonl` 白名单逐个 unlink。任何子步失败均 warn 并跳过。
+ *   白名单确保不会误删邻近文件（dump 设计：保留账本类小文件的扩展位）。
+ *
+ * - `measureDiskCap(dir, opts)`：fs.statfs → 公式
+ *   `min(1GB, max(64MB, floor(free × 0.5)))`；statfs 抛错或缺失（Node <18.15）
+ *   走 catch 路径回退固定 1GB。返回值由 bridge 暂存到 `__diskCap`，
+ *   B-stage2 切 FBQ 时再消费（路径 TBD）。
+ *
+ * `fsOps` 注入仅供测试覆盖错误分支；生产路径默认 `fs.promises`，调用方不传。
+ *
+ * 行为契约（红线）：
+ * - 不抛错，只 warn
+ * - 不递归删——白名单仅 `*.jsonl`
+ * - statfs 失败/缺失统一回退 1GB
+ */
+
+import fs from 'node:fs/promises';
+import nodePath from 'node:path';
+
+export const ONE_GB = 1024 * 1024 * 1024;
+export const SIXTY_FOUR_MB = 64 * 1024 * 1024;
+
+/**
+ * @param {string} dir - 队列目录绝对路径
+ * @param {object} [opts]
+ * @param {object} [opts.logger] - pino 风格 logger（warn? / info? / error?）
+ * @param {object} [opts.fsOps] - fs.promises 兼容子集（mkdir/readdir/unlink），仅供测试
+ */
+export async function cleanupResiduals(dir, { logger, fsOps = fs } = {}) {
+	try {
+		await fsOps.mkdir(dir, { recursive: true });
+	}
+	catch (err) {
+		/* c8 ignore next -- ?./?? fallback：err 总是 Error，.message 总存在 */
+		logger?.warn?.(`[coclaw] rpc-queues cleanup mkdir failed: ${err?.message ?? err}`);
+		return;
+	}
+
+	let names;
+	try {
+		names = await fsOps.readdir(dir);
+	}
+	catch (err) {
+		/* c8 ignore next -- ?./?? fallback：err 总是 Error，.message 总存在 */
+		logger?.warn?.(`[coclaw] rpc-queues cleanup readdir failed: ${err?.message ?? err}`);
+		return;
+	}
+
+	for (const name of names) {
+		// readdir 默认返回 string[]，但若调用方注入 Buffer/Dirent 风格 mock，name.endsWith
+		// 会抛出冲过"模块永不抛"红线。生产路径不会触发——纯防御。
+		if (typeof name !== 'string') {
+			logger?.warn?.(`[coclaw] rpc-queues unexpected non-string entry: ${typeof name}`);
+			continue;
+		}
+		if (!name.endsWith('.jsonl')) continue;
+		// nodePath.join 与 unlink 共享同一 try/catch：dir 若误传非 string（生产路径不会，
+		// 但 typeof readdir 防御已挡 name 那一头），nodePath.join(dir, name) 会抛 TypeError，
+		// 必须落在同一个 catch 里兜住才不破"模块永不抛"红线。
+		try {
+			const p = nodePath.join(dir, name);
+			await fsOps.unlink(p);
+		}
+		catch (err) {
+			/* c8 ignore next -- ?./?? fallback：err 总是 Error，.message 总存在 */
+			logger?.warn?.(`[coclaw] rpc-queues unlink failed file=${name} err=${err?.message ?? err}`);
+		}
+	}
+}
+
+/**
+ * @param {string} dir - 队列目录绝对路径（statfs 自动定位所在文件系统）
+ * @param {object} [opts]
+ * @param {object} [opts.logger]
+ * @param {object} [opts.fsOps] - fs.promises 兼容子集（statfs），仅供测试
+ * @returns {Promise<number>} diskCap 字节数；statfs 失败回退 1GB
+ */
+export async function measureDiskCap(dir, { logger, fsOps = fs } = {}) {
+	try {
+		const st = await fsOps.statfs(dir);
+		const free = Number(st.bavail) * Number(st.bsize);
+		// 真实生产环境（容器、网络挂载、ENOSYS 走 catch 之外的怪环境）下 statfs 偶有
+		// 返回非 number / NaN / 负数字段的情况；Number(NaN/undefined) 乘任何东西都是 NaN，
+		// floor(NaN * 0.5) = NaN，max/min 链路也会冒泡 NaN——不防御会让 __diskCap 为 NaN。
+		if (!Number.isFinite(free) || free < 0) {
+			/* c8 ignore next -- ?./?? fallback */
+			logger?.warn?.(`[coclaw] rpc-queues statfs failed (non-finite, fallback 1GB): bavail=${st?.bavail} bsize=${st?.bsize}`);
+			return ONE_GB;
+		}
+		return Math.min(ONE_GB, Math.max(SIXTY_FOUR_MB, Math.floor(free * 0.5)));
+	}
+	catch (err) {
+		/* c8 ignore next -- ?./?? fallback：err 总是 Error 或 TypeError，.message 总存在 */
+		logger?.warn?.(`[coclaw] rpc-queues statfs failed (fallback 1GB): ${err?.message ?? err}`);
+		return ONE_GB;
+	}
+}

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/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;