@coclaw/openclaw-coclaw 0.22.2 → 0.22.4

package/index.js

@@ -19,10 +19,29 @@ import { decideCancelResponse } from './src/agent-cancel-heuristic.js';
 import { remoteLog } from './src/remote-log.js';
 import { registerProviderAuthHandlers } from './src/provider-auth/index.js';
 import { registerModelDefaultHandlers } from './src/model-default/index.js';
+import { getClawConfig } from './src/claw-config.js';
 
 import { getPluginVersion, __resetPluginVersion } from './src/plugin-version.js';
 export { getPluginVersion, __resetPluginVersion };
 
+// 收纳 register() 在 full 模式启动的 fire-and-forget 初始化任务（topic / chat-history
+// load + reconcile）的完成信号。默认 Promise.resolve() 让 awaitPluginInit() 在 register
+// 未跑或非 full 模式时立即返回。每次 full register 都重置——多次 register 互不串扰。
+let __pluginInitDone = Promise.resolve();
+
+export function awaitPluginInit() {
+	return __pluginInitDone;
+}
+
+// abort-threw 远端日志节流：gateway 进程活动期间最多上报一次，避免上游 handle.abort
+// 持续抛错时 500ms tick 重试把 remote-log 刷爆。logger.info 已对 abort-threw 静默
+// （见 coclaw.agent.abort handler 注释），但完全失去诊断信号会让运维瞎子，故保留首条。
+let __abortThrewReported = false;
+
+export function __resetAbortThrewReported() {
+	__abortThrewReported = false;
+}
+
 // 侧门注册表观测：patch OpenClaw embeddedRunState.activeRuns 的 set/delete，
 // 用于跟踪 sessionId 何时注册/注销（agent 取消流程实际读取的就是这张表）。
 // OpenClaw 侧门形状变化时（缺失 / 抛异常），通过 remoteLog 上报为升级契约变更的早期信号。
@@ -61,8 +80,9 @@ function patchMapLogging(map, label, logger) {
 	}
 	const origSet = map.set.bind(map);
 	const origDel = map.delete.bind(map);
-	// log 行包 try/catch 兜底：上游若把 Map 换成有 throwing getter（如 Proxy）的对象，
-	// 不能让本插件的诊断 log 把 OpenClaw 内部 set/delete 流程带崩
+	// AGENTS.md §"日志器"一般规则是"调用点不要再包 try/catch"，此处特例：safeLog/safeSize
+	// 是绑到 OpenClaw 内部 Map.set/delete 路径上的诊断仪器，上游若把 Map 换成 throwing-getter
+	// Proxy 或 logger 自身异常都不能把宿主的 set/delete 流程带崩，故保留 swallow 兜底
 	const safeLog = (msg) => {
 		try { logger?.info?.(msg); } catch { /* swallow — diag log 不得影响主流程 */ }
 	};
@@ -171,16 +191,19 @@ const plugin = {
 		const topicManager = new TopicManager({ logger });
 		const chatHistoryManager = new ChatHistoryManager({ logger });
 
-		// 懒加载 topic / chat history 数据（best-effort，不阻断注册）
-		topicManager.load('main').catch((err) => {
+		// 懒加载 topic / chat history 数据（best-effort，不阻断注册）。
+		// 两条 promise 收成一个 bundle 挂到 __pluginInitDone，让测试 / 关心 done 时机的
+		// caller 通过 awaitPluginInit() 显式等待——生产 gateway 不调即原 fire-and-forget 语义
+		const topicLoadP = topicManager.load('main').catch((err) => {
 			logger.warn?.(`[coclaw] topic manager load failed: ${String(err?.message ?? err)}`);
 		});
-		chatHistoryManager.load('main')
+		const chatHistoryLoadP = chatHistoryManager.load('main')
 			.then(() => manager.listAllEntries('main'))
 			.then((entries) => chatHistoryManager.reconcileAll('main', entries))
 			.catch((err) => {
 				logger.warn?.(`[coclaw] chat history manager load/reconcile failed: ${String(err?.message ?? err)}`);
 			});
+		__pluginInitDone = Promise.all([topicLoadP, chatHistoryLoadP]);
 
 		// 追踪 chat 因 reset 产生的 session 流水。双源回调（hook + sessions.changed）共用 helper。
 		// recordSessionTransition 内部已 __reloadFromDisk + mutex，外层无需再 cache.has + load。
@@ -680,8 +703,8 @@ const plugin = {
 				const runDuration = typeof params?.runDuration === 'number' ? params.runDuration : undefined;
 				const abortDuration = typeof params?.abortDuration === 'number' ? params.abortDuration : undefined;
 				const result = decideCancelResponse(abortResult, { runDuration, abortDuration });
-				// not-found 是 UI 重试期常态（注册空窗），不打日志避免噪音；其余分支保留 info
-				if (result.reason !== 'not-found') {
+				// not-found（注册空窗）与 abort-threw（上游 handle.abort 持续抛）都是 UI 500ms tick 重试期常态，跳过 info 日志避免洪水；其余分支保留 info
+				if (result.reason !== 'not-found' && result.reason !== 'abort-threw') {
 					logger.info?.(`[coclaw.agent.abort] result sessionId=${sessionId} ok=${result.ok}${result.reason ? ` reason=${result.reason}` : ''}${result.error ? ` error=${result.error}` : ''}`);
 				}
 				if (result.ok) {
@@ -695,6 +718,12 @@ const plugin = {
 					// 启发升格：双闸均达阈值，把 not-found 升格为 gone，让 UI 主动 settleByCancel
 					remoteLog(`abort.gone sid=${sessionId} runDur=${runDuration} abortDur=${abortDuration}`);
 				}
+				else if (result.reason === 'abort-threw' && !__abortThrewReported) {
+					// 一次性：上游 handle.abort 首次抛错时上报，让运维知道这个 gateway 实例发生过；
+					// 后续 tick 重试不再上报，避免被 UI 500ms 拍频刷爆远端日志
+					__abortThrewReported = true;
+					remoteLog(`abort.threw sid=${sessionId} error=${result.error || ''}`);
+				}
 				respond(true, result);
 			}
 			catch (err) {
@@ -717,7 +746,7 @@ const plugin = {
 
 		const fileHandler = createFileHandler({
 			resolveWorkspace: (agentId) => {
-				const cfg = api.runtime?.config?.loadConfig();
+				const cfg = getClawConfig();
 				const dir = api.runtime?.agent?.resolveAgentWorkspaceDir(cfg, agentId);
 				if (!dir) {
 					const err = new Error('Cannot resolve workspace: runtime not available');
@@ -799,8 +828,13 @@ const plugin = {
 
 				try {
 					if (action === 'bind') {
+						// 先校验非空 code，避免无效输入触发 doBind 内的 cancelActiveEnroll 副作用
+						const code = positionals[0];
+						if (typeof code !== 'string' || code.length === 0) {
+							return { text: 'Error: binding code is required' };
+						}
 						const result = await doBind({
-							code: positionals[0],
+							code,
 							serverUrl: options.server,
 						});
 						return { text: bindOk(result) };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coclaw/openclaw-coclaw",
-  "version": "0.22.2",
+  "version": "0.22.4",
   "type": "module",
   "license": "Apache-2.0",
   "description": "OpenClaw plugin for remote chat over WebRTC. Run `openclaw coclaw enroll` after install.",
@@ -50,7 +50,7 @@
     "typecheck": "echo \"No typecheck configured yet (coclaw openclaw plugin)\"",
     "check": "pnpm lint && pnpm typecheck",
     "test:plugin": "node --test src/plugin-mode.test.js",
-    "test": "c8 --check-coverage --lines 100 --functions 100 --branches 95 --statements 100 --reporter=text --reporter=lcov bash -c 'for f in src/**/*.test.js src/*.test.js index.test.js; do node --test \"$f\" || exit 1; done'",
+    "test": "c8 --check-coverage --lines 100 --functions 100 --branches 95 --statements 100 --reporter=text --reporter=lcov bash -c 'node --test src/**/*.test.js src/*.test.js index.test.js'",
     "e2e": "node --test --test-concurrency=1 e2e/*.e2e.spec.js",
     "verify": "pnpm check && pnpm test",
     "link": "bash ./scripts/link.sh",

package/src/auto-upgrade/updater.js

@@ -191,7 +191,11 @@ function loadInstallRecordFromLegacyConfig(pluginId) {
 		const config = getClawConfig();
 		return config?.plugins?.installs?.[pluginId] ?? null;
 	}
-	catch {
+	catch (err) {
+		// 与同函数其他 catch 风格对齐：旧版账本读取异常也外推诊断信号，
+		// 否则下游只能看到笼统的 "Skipping: not an npm-installed plugin"，无定位线索
+		/* c8 ignore next -- ?? fallback：err 字段缺省的兜底分支不强制覆盖 */
+		remoteLog(`upgrade.legacy-config-read-failed msg=${err?.message ?? String(err)}`);
 		return null;
 	}
 }

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

@@ -39,6 +39,8 @@ export function classifyChatHistorySessionKey(sessionKey) {
 	//   由 cron 守卫挡住即可，避免与 IM per-account DM accountId="cron"/"subagent" 形态冲突
 	//   （accountId 仅按 [a-z0-9_-]{1,64} 校验，"cron"/"subagent" 都是合法账户名）。
 	if (parts[2] === 'explicit') return { ok: false, reason: 'explicit' };
+	// agent:<id>:cron:<jobId>:subagent:<uuid> 形态命中 cron 守卫返回 reason='cron'，
+	// 丢一层嵌套语义；上报信号目前无下游按 reason 细分计数/告警，留作识别到才说
 	if (parts[2] === 'cron') return { ok: false, reason: 'cron' };
 	if (parts[2] === 'subagent') return { ok: false, reason: 'subagent' };
 	return { ok: true, reason: null };
@@ -76,7 +78,8 @@ export class ChatHistoryManager {
 	constructor(opts = {}) {
 		this.__resolveSessionsDir = opts.resolveSessionsDir ?? agentSessionsDir;
 		this.__logger = opts.logger ?? console;
-		/* c8 ignore next 2 -- ?? fallback：测试始终注入 */
+		// readFile / writeJsonFile DI 注入点用于精细 mock；不注入时默认走 fs.readFile + atomicWriteJsonFile。
+		// 默认构造路径由"通过 setRuntime 端到端落盘"测试覆盖。
 		this.__readFile = opts.readFile ?? fs.readFile;
 		this.__writeJsonFile = opts.writeJsonFile ?? atomicWriteJsonFile;
 		// 内存缓存：agentId -> { version, [sessionKey]: [...] }
@@ -192,6 +195,7 @@ export class ChatHistoryManager {
 			for (let i = 1; i < list.length; i++) {
 				const item = list[i];
 				if (!item || typeof item !== 'object' || item.archivedAt) continue;
+				// 复用 archivedAt 写补登时间；事后与正常归档无法区分，线下分析靠下方 chat-history.sanitize-coerce 上报信号
 				item.archivedAt = now;
 				this.__logger.warn?.(
 					`[coclaw] chat-history sanitize: non-head unarchived entry coerced sessionKey=${sessionKey} sid=${item.sessionId}`,
@@ -351,6 +355,8 @@ export class ChatHistoryManager {
 		} catch (err) {
 			this.__reportLoadError(filePath, err, '__reloadFromDisk');
 		}
+		// 读盘失败 + cache 已热身 → 保留旧 cache（best-effort 容忍）。下次写盘会把旧数据回灌磁盘自愈；
+		// 但若长期无新写入，磁盘上的损坏内容不会被主动修复
 		if (!this.__cache.has(agentId)) {
 			this.__cache.set(agentId, emptyStore());
 		}

package/src/file-manager/handler.js

@@ -643,6 +643,17 @@ export function createFileHandler({ resolveWorkspace, logger, deps = {} }) {
 		let wsBackpressureCount = 0;
 		let wsError = false;
 		let finishing = false;
+		// 一次性 cleanup attach 守卫：dc.onerror 后 pion 通常紧跟 dc.onclose，
+		// 两条 cleanup 路径若都向 ws 挂 'close' 监听会重复 safeUnlink。
+		// 用 flag 而不是 wsError 守卫，是为了不破坏 SIZE_EXCEEDED 等"先同步 unlink、
+		// 再触发 dc.close → dc.onclose"路径：那条路径同样设 wsError=true 但**没**
+		// attach 过，仍需 dc.onclose 兜底 attach（fopen 完成后才删到真文件）
+		let cleanupAttached = false;
+		function attachTmpCleanupOnce() {
+			if (cleanupAttached) return;
+			cleanupAttached = true;
+			ws.on('close', () => safeUnlink(tmpPath));
+		}
 
 		// --- 受控写入：中间缓冲 + drain 循环 ---
 		const pendingQueue = [];
@@ -672,9 +683,11 @@ export function createFileHandler({ resolveWorkspace, logger, deps = {} }) {
 				draining = false;
 				pendingQueue.length = 0;
 				log.warn?.(`[coclaw/file] drainLoop write error: ${err.message}`);
+				// 走安全网而非同步 safeUnlink：fopen 未完成时 sync unlink 扑空被吞，
+				// fopen 后留孤儿。attach 在 destroy 之前确保 'close' emit 时 listener 已就位
+				attachTmpCleanupOnce();
 				ws.destroy();
 				if (!dcClosed) sendError(dc, 'WRITE_FAILED', err.message);
-				safeUnlink(tmpPath);
 				const elapsed = Date.now() - startTime;
 				remoteLog(`file.up.fail ${logTag}id=${transferId} reason=drain-write-error err=${err.message} received=${receivedBytes}/${declaredSize} elapsed=${elapsed}ms`);
 				return;
@@ -692,8 +705,17 @@ export function createFileHandler({ resolveWorkspace, logger, deps = {} }) {
 		function finishUpload() {
 			if (finishing) return;
 			finishing = true;
-			ws.end(async () => {
+			ws.end(async (err) => {
 				const elapsed = Date.now() - startTime;
+				// ws 在 'finish' 之前被 destroy 时，Node Writable 会用 err 调 pending end cb
+				//（destroy(e) 用 e；destroy() 用 ERR_STREAM_DESTROYED）。任何 ws 中途夭折的
+				// 产线路径都已经在 ws.on('error') / dc.onclose / dc.onerror / drainLoop catch
+				// 里 attach 过清理 + 打过更具体的 fail log；这里只需兜底 attach 一次（idempotent）
+				// 防御未来路径漏挂，并跳过 rename / size 校验 / 成功响应
+				if (err) {
+					attachTmpCleanupOnce();
+					return;
+				}
 				if (dcClosed) {
 					safeUnlink(tmpPath);
 					remoteLog(`file.up.fail ${logTag}id=${transferId} reason=dc-closed-before-flush received=${receivedBytes}/${declaredSize} elapsed=${elapsed}ms bp=${wsBackpressureCount}`);
@@ -795,13 +817,20 @@ export function createFileHandler({ resolveWorkspace, logger, deps = {} }) {
 			if (doneReceived) {
 				// done 已收到但 drain 未完成 — finishUpload 中会检测 dcClosed 并清理 tmp
 				if (!finishing) finishUpload();
-			} else {
-				ws.destroy();
-				safeUnlink(tmpPath);
-				const elapsed = Date.now() - startTime;
-				remoteLog(`file.up.fail ${logTag}id=${transferId} reason=dc-closed received=${receivedBytes}/${declaredSize} elapsed=${elapsed}ms bp=${wsBackpressureCount}`);
-				log.warn?.(`[coclaw/file] [${connId ?? '?'}] up.fail id=${transferId} reason=dc-closed received=${receivedBytes}/${declaredSize} elapsed=${elapsed}ms bp=${wsBackpressureCount}`);
+				return;
 			}
+			// 等 ws 关闭后再 unlink——fopen 未完成时直接 safeUnlink 会扑空被吞，
+			// 随后 fopen 完成创建文件却没人清，留下孤儿 tmp。flag 守卫保证 dc.onerror
+			// 已 attach 过时不会重挂第二个 listener
+			attachTmpCleanupOnce();
+			ws.destroy();
+			// dc.onerror 已打过 reason=dc-error fail 日志 → 跳过 reason=dc-closed
+			// 避免双触发时 fail 日志重复（SIZE_EXCEEDED 路径打的是 reason=size-exceeded
+			// 的 reject 日志，不在此 fail 命名空间，不受影响）
+			if (wsError) return;
+			const elapsed = Date.now() - startTime;
+			remoteLog(`file.up.fail ${logTag}id=${transferId} reason=dc-closed received=${receivedBytes}/${declaredSize} elapsed=${elapsed}ms bp=${wsBackpressureCount}`);
+			log.warn?.(`[coclaw/file] [${connId ?? '?'}] up.fail id=${transferId} reason=dc-closed received=${receivedBytes}/${declaredSize} elapsed=${elapsed}ms bp=${wsBackpressureCount}`);
 		};
 
 		// pion 异步 send 错误经此回调上报；触发已有清理路径
@@ -810,8 +839,9 @@ export function createFileHandler({ resolveWorkspace, logger, deps = {} }) {
 			wsError = true;
 			draining = false;
 			pendingQueue.length = 0;
+			// 同上：等 ws 关闭后再 unlink，避开 fopen-vs-unlink race
+			attachTmpCleanupOnce();
 			ws.destroy();
-			safeUnlink(tmpPath);
 			const elapsed = Date.now() - startTime;
 			/* c8 ignore next -- ?? fallback for non-Error throw */
 			const errMsg = err?.message ?? String(err);
@@ -829,11 +859,16 @@ export function createFileHandler({ resolveWorkspace, logger, deps = {} }) {
 			draining = false;
 			pendingQueue.length = 0;
 			log.warn?.(`[coclaw/file] write stream error: ${err.message}`);
+			// 安全网先装：sendError 会同步 dc.close → dc.onclose，doneReceived=true 且
+			// !finishing 时会同步重入 finishUpload → ws.end，整条 sync 链全跑完才回到这里。
+			// 与 drainLoop catch 顺序对齐。显式 ws.destroy() 不依赖 Node autoDestroy
+			// （注入的非标准 stream 可能不触发）触发 ws 关闭流程；listener 在 'close' emit 时 fire
+			attachTmpCleanupOnce();
+			ws.destroy();
 			if (!dcClosed) {
 				const code = err.code === 'ENOSPC' ? 'DISK_FULL' : 'WRITE_FAILED';
 				sendError(dc, code, err.message);
 			}
-			safeUnlink(tmpPath);
 			const elapsed = Date.now() - startTime;
 			remoteLog(`file.up.fail ${logTag}id=${transferId} reason=write-error err=${err.code || err.message} received=${receivedBytes}/${declaredSize} elapsed=${elapsed}ms`);
 			log.warn?.(`[coclaw/file] [${connId ?? '?'}] up.fail id=${transferId} reason=write-error received=${receivedBytes}/${declaredSize} elapsed=${elapsed}ms err=${err.code || err.message}`);
@@ -901,7 +936,13 @@ export function createFileHandler({ resolveWorkspace, logger, deps = {} }) {
 	}
 
 	function safeUnlink(filePath) {
-		_unlink(filePath).catch(() => {});
+		// ENOENT 静默：tmp 可能尚未创建（fopen 未完成）或已被另一路径删过，均属预期。
+		// 其余错（EACCES / EBUSY / EIO）若完全无声会让孤儿 tmp 悄悄积累——warn 一下，
+		// 仍保留 fire-and-forget 语义；scheduleTmpCleanup 仍是最终兜底
+		_unlink(filePath).catch((err) => {
+			if (err?.code === 'ENOENT') return;
+			log.warn?.(`[coclaw/file] safeUnlink failed: ${filePath} ${err?.code || err?.message}`);
+		});
 	}
 
 	return {

package/src/model-default/handlers.js

@@ -105,11 +105,13 @@ export function buildModelDefaultHandlers({ sdk, loadConfig, resolveAgentDir })
 				respondInvalid(respond, 'primary is required');
 				return;
 			}
-			const primary = params.primary;
-			if (primary !== null && typeof primary !== 'string') {
+			const rawPrimary = params.primary;
+			if (rawPrimary !== null && typeof rawPrimary !== 'string') {
 				respondInvalid(respond, 'primary must be a string or null');
 				return;
 			}
+			// 复制粘贴常带前后空白；trim 后再做形态/凭据/catalog 校验，并按 trim 后的值落盘
+			const primary = rawPrimary === null ? null : rawPrimary.trim();
 			if (primary !== null && primary.length === 0) {
 				respondInvalid(respond, 'primary must be a non-empty string or null');
 				return;

package/src/model-default/index.js

@@ -17,6 +17,9 @@ import { buildModelDefaultHandlers } from './handlers.js';
 import { mainAgentDir } from '../claw-paths.js';
 import { getClawConfig } from '../claw-config.js';
 
+// link-UNSAFE：模块级 dedup 缓存。`--link` 模式下两实例各自 lazy-load 一次
+// SDK（结果一致、运行无伤但去重失效）。当前仅 RPC handler 走该路径——
+// 不要在 hook 回调里访问本模块的 export。详见 docs/module-boundaries.md。
 let _configMutationP;
 let _modelsP;
 let _providerAuthP;

package/src/provider-auth/index.js

@@ -10,6 +10,9 @@
 import { buildProviderAuthHandlers } from './handlers.js';
 import { mainAgentDir } from '../claw-paths.js';
 
+// link-UNSAFE：模块级 dedup 缓存。`--link` 模式下两实例各自 lazy-load 一次
+// SDK（结果一致、运行无伤但去重失效）。当前仅 RPC handler 走该路径——
+// 不要在 hook 回调里访问本模块的 export。详见 docs/module-boundaries.md。
 let _sdkPromise;
 
 // 默认 loader 仅作 fallback：生产路径必须由入口（plugins/openclaw/index.js）注入 loadSdk，

package/src/realtime-bridge.js

@@ -112,6 +112,7 @@ export function defaultResolveGatewayAuthToken() {
 		}
 	}
 	catch (err) {
+		// register 早期 / runtime 未注入完成时也可能被触达，注入 logger 此时未必可用，用 console.warn 兜底
 		console.warn?.(`[coclaw] resolve gateway auth token failed: ${String(err?.message ?? err)}`);
 	}
 	const envToken = process.env.OPENCLAW_GATEWAY_TOKEN?.trim();
@@ -584,12 +585,11 @@ export class RealtimeBridge {
 			const hostName = getHostName();
 			const pluginVersion = await getPluginVersion();
 			const agentModels = await this.__collectAgentModels();
-			broadcastPluginEvent('coclaw.info.updated', {
-				name,
-				hostName,
-				pluginVersion,
-				agentModels,
-			});
+			// 采集失败时漏报 agentModels（而非显式 null）：server / UI 走 patch 语义
+			// 保留旧值，避免 admin 仪表盘瞬时清空（OpenClaw manifest cache 偶发卡顿时易触发）
+			const payload = { name, hostName, pluginVersion };
+			if (agentModels !== null) payload.agentModels = agentModels;
+			broadcastPluginEvent('coclaw.info.updated', payload);
 		}
 		catch (err) {
 			/* c8 ignore next 2 -- 防御性兜底 */
@@ -603,7 +603,9 @@ export class RealtimeBridge {
 	 */
 	async __collectAgentModels() {
 		try {
-			const result = await this.__gatewayRpc('agents.list', {}, { timeoutMs: 3000 });
+			// OpenClaw agents.list 走 manifest cache 加载链路，偶发 cache mismatch 时 ~10s 才回
+			// （issue #80697）；timeout 给到 30s 让本地 cache miss 有恢复窗口
+			const result = await this.__gatewayRpc('agents.list', {}, { timeoutMs: 30000 });
 			if (result?.ok !== true) return null;
 			const agents = result?.response?.payload?.agents;
 			if (!Array.isArray(agents)) return null;
@@ -1128,9 +1130,11 @@ export class RealtimeBridge {
 			this.logger.warn?.(
 				`[coclaw] dc gateway req invalid: id=${typeof payload?.id} method=${typeof payload?.method}`,
 			);
-			// 有合法 id 时回 INVALID_REQUEST 让发起方尽快放弃等待；id 不合法时只能 drop
+			// 有合法 id 时回 INVALID_REQUEST 让发起方尽快放弃等待；id 不合法时只能 drop。
+			// 单播：connId 来自每条连接的闭包必非空，只发给发出乱码请求的连接，
+			// 不打扰其他客户端（旁边 OFFLINE / SEND_FAILED 分支属系统级公告保留广播语义）
 			if (hasValidId) {
-				this.webrtcPeer?.broadcast({
+				await this.webrtcPeer?.sendTo(connId, {
 					type: 'res',
 					id: payload.id,
 					ok: false,
@@ -1604,6 +1608,8 @@ export class RealtimeBridge {
 		});
 		this.__runEventRoutes.init();
 		// 外线（plugin↔远端 server）先发起 connectIfNeeded：仅创建 WebSocket 即返回，不阻塞内线。
+		// 不包 try/catch：__connectIfNeeded → getBindingsPath → pluginDir 链路依赖 runtime 已注入，
+		// register full 模式下 setRuntime 必然先于 service.start 完成，pluginDir 不会抛
 		await this.__connectIfNeeded();
 		// 三条线各自独立启动：内线（plugin↔本机 gateway）由 start() 主动触发，
 		// 不再依附于外线 open。即便外线建连失败/未配置 token，内线仍能起来支撑 DC RPC。
@@ -1717,6 +1723,13 @@ export class RealtimeBridge {
 //   restart(opts) — 无论当前状态，确保 bridge 以给定 opts 运行（幂等）
 //   stop()        — 停止并销毁 singleton
 // 调用方无需感知 singleton 是否为 null，选"要运行"或"要停止"即可。
+//
+// link-UNSAFE 警告：以下 singleton 状态与所有读 singleton 的 export（restart /
+// stop / waitForSessionsReady / ensureAgentSession / gatewayAgentRpc /
+// broadcastPluginEvent）在 `--link` 安装模式下，hook 路径与 RPC 路径可能拿
+// 到不同 ESM 模块实例 → 两份独立 singleton。**不要在 api.on(...) hook 回调内
+// 调用本文件的任何 export**。hook 内若需触发 bridge 副作用，请走 RPC
+// （api.callGatewayMethod('coclaw.xxx', ...)）。详见 docs/module-boundaries.md。
 
 let singleton = null;
 

package/src/remote-log.js

@@ -3,6 +3,11 @@
  *
  * 将诊断日志缓冲并通过 WS 通道推送到 CoClaw server。
  * 单例模式——各模块直接 import { remoteLog } 使用。
+ *
+ * link-UNSAFE：buffer / sender / flushing 都是模块级状态。`--link` 模式下
+ * hook 实例可能从未被 setSender 注入 → hook 路径调 remoteLog 会落到没装
+ * sender 的实例 → 静默丢日志。**不要在 hook 回调内调用 remoteLog**；
+ * 要发就用 hook 入参里的 logger。详见 docs/module-boundaries.md。
  */
 
 const MAX_BUFFER = 1000;

package/src/runtime.js

@@ -1,4 +1,8 @@
-// runtime 单例：在 plugin 模式下由 register() 注入
+// runtime 单例：在 plugin 模式下由 register() 注入。
+// link-UNSAFE：`--link` 安装模式下 hook 与 RPC handler 可能跑在不同 ESM 实例 →
+// 两份独立 runtime；hook 实例从未被 setRuntime → getRuntime() 返回 null。
+// **不要在 hook 回调内调用 getRuntime()**——hook 入参 `api` 已带 runtime。
+// 详见 docs/module-boundaries.md。
 let runtime = null;
 
 export function setRuntime(rt) {

package/src/session-manager/manager.js

@@ -83,24 +83,22 @@ function shouldReplaceByPriority(current, next) {
 }
 
 export function createSessionManager(options = {}) {
-	/* 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 resolveSessionsDir(aid);
 	}
 
 	async function readIndex(agentId = 'main') {
-		/* c8 ignore next */
 		const aid = typeof agentId === 'string' && agentId.trim() ? agentId.trim() : 'main';
 		const file = resolveStorePath(aid);
 		const data = await readJsonSafe(file, {});
-		/* c8 ignore next */
+		// readJsonSafe 抛错时返回 {}（已是 object），此处兜底 sessions.json 内容是合法 JSON
+		// 但非 object（number / string / boolean / null / array 由下游 listAllEntries 单独处理）
 		if (!data || typeof data !== 'object') return {};
 		return data;
 	}
@@ -176,7 +174,6 @@ export function createSessionManager(options = {}) {
 		// 补充 sessions.json 中有索引但无 transcript 文件的 session（如 reset 后未对话、新建 session）
 		for (const [sessionKey, entry] of Object.entries(index)) {
 			const sid = entry?.sessionId;
-			/* c8 ignore next -- !sid 防御性检查 */
 			if (!sid || grouped.has(sid)) continue;
 			grouped.set(sid, {
 				sessionId: sid,
@@ -184,7 +181,7 @@ export function createSessionManager(options = {}) {
 				indexed: true,
 				archiveType: 'live',
 				fileName: null,
-				/* c8 ignore next -- ?? fallback */
+				// entry.updatedAt 缺失或非数字时回落 0；UI 端按 updatedAt 排序时无 transcript 项排到末位
 				updatedAt: entry.updatedAt ?? 0,
 				size: 0,
 			});
@@ -284,12 +281,10 @@ export function createSessionManager(options = {}) {
 				all.push(JSON.parse(line));
 			}
 			catch (err) {
-				/* c8 ignore next -- ?./?? fallback */
 				logger.warn?.(`[session-manager] bad json line skipped: ${String(err?.message ?? err)}`);
 			}
 		}
 		const messages = all.slice(cursor, cursor + limit);
-		/* c8 ignore next */
 		const nextCursor = cursor + limit < all.length ? String(cursor + limit) : null;
 		return {
 			agentId,
@@ -332,7 +327,6 @@ export function createSessionManager(options = {}) {
 				messages.push(row);
 			}
 			catch (err) {
-				/* c8 ignore next -- ?./?? fallback */
 				logger.warn?.(`[session-manager] bad json line skipped: ${String(err?.message ?? err)}`);
 			}
 		}

package/src/topic-manager/manager.js

@@ -229,6 +229,7 @@ export class TopicManager {
 		const srcPath = nodePath.join(this.__sessionsDir(agentId), `${topicId}.jsonl`);
 		const tempId = randomUUID();
 		const tempPath = nodePath.join(this.__sessionsDir(agentId), `${tempId}.jsonl`);
+		// fs.copyFile 非 atomic；崩在半路的临时 *.jsonl 可能被 session-manager 扫到列为幽灵会话，用户重试导出即恢复
 		await this.__copyFile(srcPath, tempPath);
 		return { tempId, tempPath };
 	}

package/src/utils/memory-queue.js

@@ -282,8 +282,11 @@ class MemoryQueue {
 		return this.tag ? ` ${this.tag}` : '';
 	}
 
+	// AGENTS.md §"日志器" 一般规则是"调用点不要再包 try/catch"，此处特例：
+	// __safeWarn 是 enqueue 同步入口的兜底，enqueue 对外承诺不抛业务无关错误，
+	// 哪怕 logger 自身坏了也不能传染到 RPC 数据通路，故保留 swallow
 	__safeWarn(msg) {
-		try { this.logger.warn?.(`[rpc-queue${this.__tagSuffix()}] ${msg}`); } catch { /* logger 自身坏了也不能让 enqueue 抛 */ }
+		try { this.logger.warn?.(`[rpc-queue${this.__tagSuffix()}] ${msg}`); } catch { /* swallow */ }
 	}
 }
 

package/src/webrtc/dc-chunking.js

@@ -60,29 +60,6 @@ export function buildChunks(jsonStr, maxMessageSize, getNextMsgId) {
 	return chunks;
 }
 
-/**
- * 按需分片并发送消息（薄包装：buildChunks + dc.send）
- * 注意：无应用层流控；生产路径请使用 MemoryQueue + RpcDcSender
- * @param {object} dc - DataChannel
- * @param {string} jsonStr - 已序列化的 JSON 字符串
- * @param {number} maxMessageSize - 对端声明的 maxMessageSize
- * @param {() => number} getNextMsgId - 获取下一个 msgId
- * @param {object} [logger] - 可选 logger
- */
-export function chunkAndSend(dc, jsonStr, maxMessageSize, getNextMsgId, logger) {
-	const chunks = buildChunks(jsonStr, maxMessageSize, getNextMsgId);
-	if (!chunks) {
-		dc.send(jsonStr);
-		return;
-	}
-	const msgId = chunks[0].readUInt32BE(1);
-	const totalBytes = chunks.reduce((n, c) => n + (c.length - HEADER_SIZE), 0);
-	logger?.info?.(`[dc-chunking] chunking msgId=${msgId}: ${totalBytes} bytes → ${chunks.length} chunks (maxMsgSize=${maxMessageSize})`);
-	for (const chunk of chunks) {
-		dc.send(chunk);
-	}
-}
-
 /**
  * 创建分片重组器
  * @param {(jsonStr: string) => void} onComplete - 完整消息回调

package/src/webrtc/rpc-dc-sender.js

@@ -160,8 +160,11 @@ class RpcDcSender {
 		return this.tag ? ` ${this.tag}` : '';
 	}
 
+	// AGENTS.md §"日志器" 一般规则是"调用点不要再包 try/catch"，此处特例：
+	// __safeWarn 在 send/BAL 热路径里调，logger 异常不能升级为协议错（caller 只
+	// 等 RPC 应答，不该收到 logger 自身的 stack），故保留 swallow
 	__safeWarn(msg) {
-		try { this.logger.warn?.(`[rpc-dc-sender${this.__tagSuffix()}] ${msg}`); } catch { /* logger 自身坏了不能让 send 抛非协议错 */ }
+		try { this.logger.warn?.(`[rpc-dc-sender${this.__tagSuffix()}] ${msg}`); } catch { /* swallow */ }
 	}
 
 	__safeRemoteLog(text) {

package/src/webrtc/webrtc-peer.js

@@ -996,9 +996,10 @@ export class WebRtcPeer {
 		// 'fbq' 模式下若 queueDir 不可用则降级到 mem，避免阻塞装配。
 		// 同 connId race 隔离（决策 4）：FBQ id 加唯一后缀 ${connId}-${ts}-${nonce}，
 		// 让新旧实例文件名物理不同，destroy/init 期间互不踩踏。MemoryQueue 不碰 fs，无此需求。
-		// connId 字符集（PRE-EXISTING 契约）：上游 server 分配 connId 形如 `c_<digits>`；
-		// FBQ / MemoryQueue 共用 `^[A-Za-z0-9._-]+$` 校验。若 server 将来引入特殊字符，
-		// queue 构造会抛 TypeError，由 __setupDataChannel 的 .catch 兜底 warn——非 B9b 引入。
+		// connId 字符集契约：FBQ / MemoryQueue 共用 `^[A-Za-z0-9._-]+$` 校验。
+		// 上游 server 分配 connId 形如 `c_<digits>` 符合契约；若 server 引入特殊字符，
+		// queue 构造抛 TypeError，由 __setupDataChannel 的 .catch 兜底 warn。
+		// 完整契约 / 违反后果 / 修复方向见 docs/connid-contract.md
 		const useFbq = this.__rpcQueueImpl === 'fbq' && !!this.__queueDir;
 		const fbqFallback = !useFbq && this.__rpcQueueImpl === 'fbq';
 		const queue = useFbq