@coclaw/openclaw-coclaw 0.19.2 → 0.20.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coclaw/openclaw-coclaw",
-  "version": "0.19.2",
+  "version": "0.20.1",
   "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/auto-upgrade/updater.js

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

package/src/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-config.js

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

package/src/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,10 @@
-import fs from 'node:fs';
-import os from 'node:os';
 import nodePath from 'node:path';
 import { WebSocket as WsWebSocket } from 'ws';
 
+import { getClawConfig } from './claw-config.js';
+import { pluginDir } from './claw-paths.js';
 import { clearConfig, getBindingsPath, readConfig } from './config.js';
+import { cleanupResiduals as defaultCleanupResiduals, measureDiskCap as defaultMeasureDiskCap } from './rpc-queue-startup.js';
 import { getHostName, readSettings } from './settings.js';
 import {
 	loadOrCreateDeviceIdentity,
@@ -15,6 +16,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 +89,14 @@ 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);
+		const cfg = getClawConfig();
 		const token = cfg?.gateway?.auth?.token;
 		return typeof token === 'string' && token.trim() ? token.trim() : '';
 	}
@@ -113,7 +105,6 @@ function defaultResolveGatewayAuthToken() {
 		return '';
 	}
 }
-/* c8 ignore stop */
 
 /**
  * WebSocket 桥接器：CoClaw server ↔ OpenClaw gateway
@@ -132,6 +123,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 +138,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 +177,14 @@ 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 探测，B9b 在装配 FBQ 时取）
+		this.__diskCap = null;
+		// rpc DC 文件回退队列根目录（B-stage1 plan-2 已 cleanupResiduals 过；B9b 装配 FBQ 时取）。
+		// prep 失败时 null → webrtc-peer 装配点自动降级到 MemoryQueue
+		this.__queueDir = 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 锁防并发重复创建） */
@@ -321,6 +329,10 @@ export class RealtimeBridge {
 			PeerConnection,
 			impl: this.__ndcPreloadResult?.impl,
 			logger: this.logger,
+			// B9b：webrtc-peer 装配 FBQ 时取 disk 容量 + 队列根目录；
+			// __queueDir 为 null 时（plan-2 prep 失败）自动降级到 MemoryQueue
+			getDiskCap: () => this.__diskCap,
+			queueDir: this.__queueDir,
 		});
 	}
 	/* c8 ignore stop */
@@ -842,10 +854,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 +886,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 +942,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 +1063,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 +1081,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 +1390,28 @@ 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 });
+			// 只有 cleanupResiduals 成功 + measureDiskCap 完成后才暴露 queueDir 给 webrtc 装配；
+			// 任一抛错都让 __queueDir 留 null，下游自动降级到 MemoryQueue
+			this.__queueDir = queueDir;
+		}
+		catch (err) {
+			/* c8 ignore next -- ?./?? fallback：err 总是 Error，logger.warn 总存在 */
+			this.logger.warn?.(`[coclaw] rpc-queues startup prep failed (skipped): ${err?.message ?? err}`);
+			this.__diskCap = null;
+			this.__queueDir = null;
+		}
+		// race 守卫：cleanup/measure 期间若 stop() 已执行，不应再启动 native WebRTC 进程。
+		// preload 后还有一道 started 检查兜底（含 pion cleanup），这里先挡住一次无意义的 preload。
+		if (!this.started) return;
 		// 先完成 WebRTC 实现加载，再建立连接，避免 UI 发来 offer 时 RTC 包未就绪
 		// 优先级：pion → ndc → werift → none
 		const preloadResult = await this.__preloadWebrtc();
@@ -1378,6 +1454,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 +1511,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(() => {});