@coclaw/openclaw-coclaw 0.19.2 → 0.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coclaw/openclaw-coclaw",
-  "version": "0.19.2",
+  "version": "0.20.0",
   "type": "module",
   "license": "Apache-2.0",
   "description": "OpenClaw CoClaw channel plugin for remote chat",
@@ -39,7 +39,10 @@
   "openclaw": {
     "extensions": [
       "./index.js"
-    ]
+    ],
+    "install": {
+      "minHostVersion": ">=2026.2.19"
+    }
   },
   "scripts": {
     "build": "echo 'No build step needed (pure ES modules)'",

package/src/auto-upgrade/state.js

@@ -1,10 +1,10 @@
 /**
  * state.js — upgrade-state.json 与 upgrade-log.jsonl 读写
  *
- * 状态文件存储在 OpenClaw state 目录下（~/.openclaw/coclaw/），
- * 与 bindings.json 共享同一目录。路径解析优先级：
+ * 例外：本文件 gateway 主进程与 auto-upgrade worker 子进程共用，worker 没 runtime
+ * 注入，故保留独立的双轨解析（不走 claw-paths.js）：
  * 1. runtime.state.resolveStateDir()（gateway 进程内）
- * 2. OPENCLAW_STATE_DIR 环境变量（worker 进程，由 spawner 传入）
+ * 2. OPENCLAW_STATE_DIR 环境变量（worker 子进程，由 spawner 传入）
  * 3. ~/.openclaw（兜底默认值）
  */
 import fs from 'node:fs/promises';

package/src/chat-history-manager/manager.js

@@ -1,7 +1,7 @@
 import fs from 'node:fs/promises';
-import os from 'node:os';
 import nodePath from 'node:path';
 
+import { agentSessionsDir } from '../claw-paths.js';
 import { atomicWriteJsonFile } from '../utils/atomic-write.js';
 import { createMutex } from '../utils/mutex.js';
 
@@ -28,13 +28,13 @@ function emptyStore() {
 export class ChatHistoryManager {
 	/**
 	 * @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] - 测试注入
 	 */
 	constructor(opts = {}) {
-		this.__rootDir = opts.rootDir ?? nodePath.join(os.homedir(), '.openclaw', 'agents');
+		this.__resolveSessionsDir = opts.resolveSessionsDir ?? agentSessionsDir;
 		this.__logger = opts.logger ?? console;
 		/* c8 ignore next 2 -- ?? fallback：测试始终注入 */
 		this.__readFile = opts.readFile ?? fs.readFile;
@@ -48,7 +48,7 @@ export class ChatHistoryManager {
 	}
 
 	__sessionsDir(agentId) {
-		return nodePath.join(this.__rootDir, agentId, 'sessions');
+		return this.__resolveSessionsDir(agentId);
 	}
 
 	__historyFilePath(agentId) {

package/src/claw-paths.js

@@ -0,0 +1,84 @@
+/**
+ * claw-paths.js — OpenClaw 路径解析的唯一入口（gateway 主进程内）
+ *
+ * 设计原则：
+ * - clawStateDir：高度稳定的 OpenClaw API（自 2026-02-19 起注入 runtime），直接信任
+ * - session 三件套（store / transcript / sessions dir）：自 2026-03-16 起才注入 runtime，
+ *   做防御性 fallback，回退到 OpenClaw 自家长期稳定的固定布局
+ * - 不读 OPENCLAW_STATE_DIR 环境变量；不回退到 ~/.openclaw 家目录
+ * - runtime 缺失或字段缺失（除 session helper 外）即抛错，bug 早暴露
+ *
+ * 例外：auto-upgrade/state.js 是 gateway 与 worker 子进程共用的，worker 没 runtime，
+ * 故那个文件保留独立的 env 兜底，不走本模块。
+ */
+import nodePath from 'node:path';
+
+import { getRuntime } from './runtime.js';
+
+const CHANNEL_ID = 'coclaw';
+
+/**
+ * OpenClaw 真实 state 目录
+ * @returns {string}
+ */
+export function clawStateDir() {
+	const rt = getRuntime();
+	if (!rt?.state?.resolveStateDir) {
+		throw new Error('claw-paths: runtime not injected; cannot resolve state dir');
+	}
+	return rt.state.resolveStateDir();
+}
+
+/**
+ * CoClaw 自管文件根目录（bindings / settings / device-identity / rpc-queues）
+ * @returns {string}
+ */
+export function pluginDir() {
+	return nodePath.join(clawStateDir(), CHANNEL_ID);
+}
+
+/**
+ * sessions.json 全路径（session-manager 读会话索引用）
+ *
+ * 优先 runtime helper（自 2026-03-16 起），允许跟随 OpenClaw 自定义 store 配置；
+ * runtime 没注入 helper 时回退到固定布局。
+ * @param {string} agentId
+ * @returns {string}
+ */
+export function sessionStorePath(agentId) {
+	const rt = getRuntime();
+	const helper = rt?.agent?.session?.resolveStorePath;
+	if (helper) {
+		return helper(undefined, { agentId });
+	}
+	return nodePath.join(clawStateDir(), 'agents', agentId, 'sessions', 'sessions.json');
+}
+
+/**
+ * sessions 所在目录（topic / chat-history 写自己的扩展文件用）
+ *
+ * 通过 sessionStorePath 反推 dirname，使 CoClaw 扩展文件随 OpenClaw 真实存储位置走。
+ * @param {string} agentId
+ * @returns {string}
+ */
+export function agentSessionsDir(agentId) {
+	return nodePath.dirname(sessionStorePath(agentId));
+}
+
+/**
+ * 单条 session 的 JSONL transcript 全路径（session-manager 读单会话用）
+ * @param {string} sessionId
+ * @param {string} agentId
+ * @param {{ sessionFile?: string }} [entry] - sessions.json 索引条目，可能含 sessionFile 覆盖
+ * @returns {string}
+ */
+export function sessionTranscriptPath(sessionId, agentId, entry) {
+	const rt = getRuntime();
+	const helper = rt?.agent?.session?.resolveSessionFilePath;
+	if (helper) {
+		return helper(sessionId, entry, { agentId });
+	}
+	return nodePath.join(agentSessionsDir(agentId), `${sessionId}.jsonl`);
+}
+
+export { CHANNEL_ID };

package/src/config.js

@@ -1,27 +1,16 @@
 import fs from 'node:fs/promises';
-import os from 'node:os';
 import nodePath from 'node:path';
 
-import { getRuntime } from './runtime.js';
+import { CHANNEL_ID, pluginDir } from './claw-paths.js';
 import { atomicWriteJsonFile } from './utils/atomic-write.js';
 import { createMutex } from './utils/mutex.js';
 
 export const DEFAULT_ACCOUNT_ID = 'default';
-export const CHANNEL_ID = 'coclaw';
+export { CHANNEL_ID };
 const BINDINGS_FILENAME = 'bindings.json';
 
-export function resolveStateDir() {
-	const rt = getRuntime();
-	if (rt?.state?.resolveStateDir) {
-		return rt.state.resolveStateDir();
-	}
-	return process.env.OPENCLAW_STATE_DIR
-		? nodePath.resolve(process.env.OPENCLAW_STATE_DIR)
-		: nodePath.join(os.homedir(), '.openclaw');
-}
-
 export function getBindingsPath() {
-	return nodePath.join(resolveStateDir(), CHANNEL_ID, BINDINGS_FILENAME);
+	return nodePath.join(pluginDir(), BINDINGS_FILENAME);
 }
 
 function toRecord(value) {

package/src/device-identity.js

@@ -1,12 +1,10 @@
 import crypto from 'node:crypto';
 import fs from 'node:fs';
-import os from 'node:os';
 import nodePath from 'node:path';
 
-import { getRuntime } from './runtime.js';
+import { pluginDir } from './claw-paths.js';
 import { atomicWriteFileSync } from './utils/atomic-write.js';
 
-const CHANNEL_ID = 'coclaw';
 const IDENTITY_FILENAME = 'device-identity.json';
 
 // Ed25519 SPKI 前缀（固定 12 字节），公钥裸字节从 SPKI DER 中截取
@@ -27,22 +25,12 @@ function normalizeMetadataForAuth(value) {
 	return trimmed ? toLowerAscii(trimmed) : '';
 }
 
-function resolveStateDir() {
-	const rt = getRuntime();
-	if (rt?.state?.resolveStateDir) {
-		return rt.state.resolveStateDir();
-	}
-	return process.env.OPENCLAW_STATE_DIR
-		? nodePath.resolve(process.env.OPENCLAW_STATE_DIR)
-		: nodePath.join(os.homedir(), '.openclaw');
-}
-
 /**
  * 获取身份文件路径
  * @returns {string}
  */
 export function getIdentityPath() {
-	return nodePath.join(resolveStateDir(), CHANNEL_ID, IDENTITY_FILENAME);
+	return nodePath.join(pluginDir(), IDENTITY_FILENAME);
 }
 
 /**
@@ -89,7 +77,7 @@ function generateIdentity() {
  * 加载或创建设备身份（Ed25519 密钥对）
  *
  * 存储格式与 OpenClaw device-identity.ts 保持一致。
- * @param {string} [filePath] - 自定义路径，默认 ~/.openclaw/coclaw/device-identity.json
+ * @param {string} [filePath] - 自定义路径，默认 <state-dir>/coclaw/device-identity.json
  * @returns {{ deviceId: string, publicKeyPem: string, privateKeyPem: string }}
  */
 export function loadOrCreateDeviceIdentity(filePath) {

package/src/realtime-bridge.js

@@ -1,9 +1,9 @@
-import fs from 'node:fs';
-import os from 'node:os';
 import nodePath from 'node:path';
 import { WebSocket as WsWebSocket } from 'ws';
 
+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';
 import { getHostName, readSettings } from './settings.js';
 import {
 	loadOrCreateDeviceIdentity,
@@ -15,6 +15,7 @@ import { getRuntime } from './runtime.js';
 import { setSender as setRemoteLogSender, remoteLog } from './remote-log.js';
 import { getPluginVersion } from './plugin-version.js';
 import { getPlatformInfoLine } from './platform-info.js';
+import { RunEventRoutes, DEFAULT_TTL_MS as RUN_EVENT_DEFAULT_TTL_MS, DEFAULT_SCAN_MS as RUN_EVENT_DEFAULT_SCAN_MS } from './rpc-routing/run-event-routes.js';
 
 const DEFAULT_GATEWAY_WS_URL = `ws://127.0.0.1:${process.env.OPENCLAW_GATEWAY_PORT || '18789'}`;
 const RECONNECT_MS = 10_000;
@@ -87,24 +88,18 @@ function maskUrlToken(url) {
 	return url.replace(/([?&]token=)[^&]+/, '$1***');
 }
 
-/* c8 ignore start -- 仅在未注入 resolveGatewayAuthToken 时使用，依赖 runtime/env/文件系统 */
-function defaultResolveGatewayAuthToken() {
+// 仅在未注入 resolveGatewayAuthToken 时使用，依赖 runtime / 环境变量
+export function defaultResolveGatewayAuthToken() {
 	const envToken = process.env.OPENCLAW_GATEWAY_TOKEN?.trim();
 	if (envToken) {
 		return envToken;
 	}
 	try {
 		const rt = getRuntime();
-		if (rt?.config?.loadConfig) {
-			const cfg = rt.config.loadConfig();
-			const token = cfg?.gateway?.auth?.token;
-			return typeof token === 'string' && token.trim() ? token.trim() : '';
-		}
-		const cfgPath = process.env.OPENCLAW_CONFIG_PATH
-			? nodePath.resolve(process.env.OPENCLAW_CONFIG_PATH)
-			: nodePath.join(os.homedir(), '.openclaw', 'openclaw.json');
-		const raw = fs.readFileSync(cfgPath, 'utf8');
-		const cfg = JSON.parse(raw);
+		if (!rt?.config?.loadConfig) {
+			return '';
+		}
+		const cfg = rt.config.loadConfig();
 		const token = cfg?.gateway?.auth?.token;
 		return typeof token === 'string' && token.trim() ? token.trim() : '';
 	}
@@ -113,7 +108,6 @@ function defaultResolveGatewayAuthToken() {
 		return '';
 	}
 }
-/* c8 ignore stop */
 
 /**
  * WebSocket 桥接器：CoClaw server ↔ OpenClaw gateway
@@ -132,6 +126,8 @@ export class RealtimeBridge {
 	 * @param {number} [deps.gatewayReadyTimeoutMs] - __waitGatewayReady 默认超时（测试可注入短值）
 	 * @param {number} [deps.dcReqTtlMs] - UI 转发 RPC 路由表条目 TTL（测试可注入短值）
 	 * @param {number} [deps.dcReqScanMs] - UI 转发 RPC 路由表周期扫描间隔（测试可注入短值）
+	 * @param {number} [deps.runEventRoutesTtlMs] - runId → connId 路由表条目 TTL（测试可注入短值）
+	 * @param {number} [deps.runEventRoutesScanMs] - runId → connId 路由表周期扫描间隔（测试可注入短值）
 	 */
 	constructor(deps = {}) {
 		this.__readConfig = deps.readConfig ?? readConfig;
@@ -145,6 +141,11 @@ export class RealtimeBridge {
 		this.__gatewayReadyTimeoutMs = deps.gatewayReadyTimeoutMs ?? 1500;
 		this.__dcReqTtlMs = deps.dcReqTtlMs ?? DC_REQ_TTL_MS;
 		this.__dcReqScanMs = deps.dcReqScanMs ?? DC_REQ_SCAN_MS;
+		this.__runEventRoutesTtlMs = deps.runEventRoutesTtlMs ?? RUN_EVENT_DEFAULT_TTL_MS;
+		this.__runEventRoutesScanMs = deps.runEventRoutesScanMs ?? RUN_EVENT_DEFAULT_SCAN_MS;
+		// rpc-queues/ 启动期预热钩子（B-stage1 plan-2）。仅供测试覆盖错误分支注入；生产路径走默认。
+		this.__cleanupRpcQueueResiduals = deps.cleanupRpcQueueResiduals ?? defaultCleanupResiduals;
+		this.__measureRpcQueueDiskCap = deps.measureRpcQueueDiskCap ?? defaultMeasureDiskCap;
 
 		this.serverWs = null;
 		this.gatewayWs = null;
@@ -179,6 +180,11 @@ export class RealtimeBridge {
 		// 用于 res 帧按发起方单播；查不到时回退广播兜底（兼容旧 UI / 撞号 / 上游新增中间态字符串等）
 		this.__dcPendingRequests = new Map();
 		this.__dcPendingScanTimer = null;
+		// runId → connId 路由表：用于 event:agent 帧按发起方单播。
+		// 实例延迟到 start() 真 logger 到位时再 new；stop() destroy 后置 null。
+		this.__runEventRoutes = null;
+		// rpc DC 文件回退队列的磁盘容量（B-stage1 plan-2 探测，B-stage2 才消费）
+		this.__diskCap = null;
 	}
 
 	__resolveWebSocket() {
@@ -287,6 +293,8 @@ export class RealtimeBridge {
 		this.gatewayPendingRequests.clear();
 		// 清空 UI 转发 RPC 路由表：gateway 已断，不会再有响应回来；不主动通知 UI，由 UI 30/60s 超时兜底
 		this.__dcPendingRequests.clear();
+		// 同步清空 runId 路由表（gateway 已断，不会再有 event:agent 推过来）
+		this.__runEventRoutes?.clear();
 	}
 
 	/** 懒加载 WebRtcPeer（promise 锁防并发重复创建） */
@@ -842,10 +850,28 @@ export class RealtimeBridge {
 					if (payload.type === 'res' && typeof payload.id === 'string') {
 						const info = this.__dcPendingRequests.get(payload.id);
 						if (info) {
-						// 终态才清条目；accepted 类中间态保留等下一帧
+							// runId 路由表维护：accepted 时 add（首发优先），非 accepted 时 remove。
+							// 写入要求 reqId 表命中以拿 connId；删除嵌在 reqId 命中分支内——
+							// 因 reqId 表 miss 意味着写入也未发生过（设计上等价 no-op），
+							// 极端错位（reqId 表先 TTL 过期、runId 表条目仍存）由 24h TTL 兜底。
+							const runId = payload.payload?.runId;
+							if (typeof runId === 'string' && runId) {
+								if (payload.payload?.status === 'accepted') {
+									this.__runEventRoutes?.add(runId, info.connId, payload.id);
+									this.logger.debug?.(`[coclaw/run-event-route] add runId=${runId} connId=${info.connId} reqId=${payload.id}`);
+								}
+								else {
+									this.__runEventRoutes?.remove(runId, payload.id);
+									this.logger.debug?.(`[coclaw/run-event-route] remove runId=${runId} reqId=${payload.id}`);
+								}
+							}
+							// 终态才清条目；accepted 类中间态保留等下一帧
 							if (isFinalResMsg(payload)) {
 								this.__dcPendingRequests.delete(payload.id);
+								this.logger.debug?.(`[coclaw/rpc-res-route] remove reqId=${payload.id} reason=final-res`);
 							}
+							/* c8 ignore next -- TODO: 2026-05-20 后删除 */
+							this.logger.debug?.(`[coclaw/rpc-res-route] hit, reqId=${payload.id} → connId=${info.connId}`);
 							// sendTo 阶段 1 改为 async（admission 决策 await）；外层 listener 已是 async
 							const delivered = await this.webrtcPeer?.sendTo(info.connId, payload);
 							if (!delivered) {
@@ -856,6 +882,24 @@ export class RealtimeBridge {
 							}
 							return;
 						}
+						/* c8 ignore next -- TODO: 2026-05-20 后删除 */
+						this.logger.debug?.(`[coclaw/rpc-res-route] miss, broadcast, reqId=${payload.id}`);
+					}
+					// (c2) agent event 按 runId 单播：命中即送达，不退兜底广播；miss 走 (d) 兜底
+					if (payload.type === 'event' && payload.event === 'agent') {
+						const runId = payload.payload?.runId;
+						if (typeof runId === 'string' && runId) {
+							const connId = this.__runEventRoutes?.lookup(runId);
+							if (connId !== undefined) {
+								/* c8 ignore next -- TODO: 2026-05-20 后删除 */
+								this.logger.debug?.(`[coclaw/run-event-route] hit, runId=${runId} → connId=${connId}`);
+								// sendTo 失败不打 log（PC 状态翻转日志已足够，drop 是正确语义）
+								await this.webrtcPeer?.sendTo(connId, payload);
+								return;
+							}
+						}
+						/* c8 ignore next -- TODO: 2026-05-20 后删除 */
+						this.logger.debug?.(`[coclaw/run-event-route] miss, broadcast, runId=${runId ?? '<missing>'}`);
 					}
 					// (d) 兜底广播：覆盖 event 类型 / 映射未命中场景
 					this.webrtcPeer?.broadcast(payload);
@@ -894,6 +938,8 @@ export class RealtimeBridge {
 			this.gatewayPendingRequests.clear();
 			// 同步清空 UI 转发 RPC 路由表（同 __closeGatewayWs 语义）
 			this.__dcPendingRequests.clear();
+			// 同步清空 runId 路由表（gateway 已断，不会再有 event:agent 推过来）
+			this.__runEventRoutes?.clear();
 			// 调度下一次尝试：仅在 bridge 仍活着、未 gave-up、server WS 健康时；
 			// 其他场景（如 bridge stop、server WS 已断）由上游流程兜底，不参与 gateway 重试。
 			if (this.started && !this.__gatewayGaveUp
@@ -1013,6 +1059,7 @@ export class RealtimeBridge {
 				connId,
 				expireAt: Date.now() + this.__dcReqTtlMs,
 			});
+			this.logger.debug?.(`[coclaw/rpc-res-route] add reqId=${id} connId=${connId}`);
 		}
 		try {
 			this.__logDebug(`gateway req -> id=${id} method=${payload.method}`);
@@ -1030,7 +1077,10 @@ export class RealtimeBridge {
 		catch {
 			// SEND_FAILED：撤回映射后广播错误响应
 			if (typeof id === 'string') {
-				this.__dcPendingRequests.delete(id);
+				const removed = this.__dcPendingRequests.delete(id);
+				if (removed) {
+					this.logger.debug?.(`[coclaw/rpc-res-route] remove reqId=${id} reason=send-failed`);
+				}
 			}
 			this.webrtcPeer?.broadcast({
 				type: 'res',
@@ -1336,6 +1386,24 @@ export class RealtimeBridge {
 		this.logger = logger ?? console;
 		this.pluginConfig = pluginConfig ?? {};
 		this.started = true;
+		// rpc DC 文件回退队列的启动期预热（B-stage1 plan-2）：清残留 *.jsonl + 探测磁盘容量。
+		// 远早于第一条 rpc DC 建立（dump 设计）；__diskCap 暂存供 B-stage2 切 FBQ 时取用。
+		// 整块包 try/catch：模块自身不抛，但仍可能进入 catch 的路径——pluginDir() 同步抛
+		// （runtime 未注入 / nodePath.join 参数异常 / 测试注入的 stub 抛错）。任何路径都不能把
+		// bridge.start 卡死。
+		try {
+			const queueDir = nodePath.join(pluginDir(), 'rpc-queues');
+			await this.__cleanupRpcQueueResiduals(queueDir, { logger: this.logger });
+			this.__diskCap = await this.__measureRpcQueueDiskCap(queueDir, { logger: this.logger });
+		}
+		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;
+		}
+		// race 守卫：cleanup/measure 期间若 stop() 已执行，不应再启动 native WebRTC 进程。
+		// preload 后还有一道 started 检查兜底（含 pion cleanup），这里先挡住一次无意义的 preload。
+		if (!this.started) return;
 		// 先完成 WebRTC 实现加载，再建立连接，避免 UI 发来 offer 时 RTC 包未就绪
 		// 优先级：pion → ndc → werift → none
 		const preloadResult = await this.__preloadWebrtc();
@@ -1378,6 +1446,13 @@ export class RealtimeBridge {
 			}
 		}, this.__dcReqScanMs);
 		this.__dcPendingScanTimer.unref?.();
+		// 启动 runId → connId 路由表（agent event 单播）。延迟到 start 才 new，确保拿到真 logger。
+		this.__runEventRoutes = new RunEventRoutes({
+			logger: this.logger,
+			ttlMs: this.__runEventRoutesTtlMs,
+			scanMs: this.__runEventRoutesScanMs,
+		});
+		this.__runEventRoutes.init();
 		await this.__connectIfNeeded();
 	}
 
@@ -1428,6 +1503,11 @@ export class RealtimeBridge {
 			clearInterval(this.__dcPendingScanTimer);
 			this.__dcPendingScanTimer = null;
 		}
+		// 销毁 runId 路由表（停 timer + clear + 标 destroyed）；refresh 时会重建
+		if (this.__runEventRoutes) {
+			this.__runEventRoutes.destroy();
+			this.__runEventRoutes = null;
+		}
 		this.__closeGatewayWs();
 		if (this.webrtcPeer) {
 			await this.webrtcPeer.closeAll().catch(() => {});

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;
+	}
+}