@coclaw/openclaw-coclaw 0.22.1 → 0.22.3

package/index.js

@@ -9,7 +9,7 @@ import { readConfig } from './src/config.js';
 import { setRuntime } from './src/runtime.js';
 import { createSessionManager } from './src/session-manager/manager.js';
 import { TopicManager } from './src/topic-manager/manager.js';
-import { ChatHistoryManager } from './src/chat-history-manager/manager.js';
+import { ChatHistoryManager, classifyChatHistorySessionKey } from './src/chat-history-manager/manager.js';
 import { generateTitle } from './src/topic-manager/title-gen.js';
 import { AutoUpgradeScheduler } from './src/auto-upgrade/updater.js';
 import { getPackageInfo } from './src/auto-upgrade/updater-check.js';
@@ -23,6 +23,15 @@ import { registerModelDefaultHandlers } from './src/model-default/index.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;
+}
+
 // 侧门注册表观测：patch OpenClaw embeddedRunState.activeRuns 的 set/delete，
 // 用于跟踪 sessionId 何时注册/注销（agent 取消流程实际读取的就是这张表）。
 // OpenClaw 侧门形状变化时（缺失 / 抛异常），通过 remoteLog 上报为升级契约变更的早期信号。
@@ -171,13 +180,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').catch((err) => {
-			logger.warn?.(`[coclaw] chat history manager load failed: ${String(err?.message ?? err)}`);
-		});
+		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。
@@ -195,37 +210,32 @@ const plugin = {
 		// 该 helper 可直接作为 bridge.onSessionCreated 回调（签名兼容；缺失字段走兜底：
 		// agentId 走 parts[1] fallback、archivedSessionId 走 manager 翻 head 路径）。
 		async function handleSessionCreated({ agentId, sessionKey, sessionId, archivedSessionId }) {
-			if (!sessionKey || !sessionId) {
+			// sessionKey / sessionId 非字符串时（上游 schema 异常）直接当 missing 处理，避免 split 抛 TypeError
+			// 或脏值落盘。manager 内部入口同样会校验（深度防御）。
+			if (typeof sessionKey !== 'string' || !sessionKey
+				|| typeof sessionId !== 'string' || !sessionId) {
 				// 早返值得警惕：上游事件 schema 异常，或 topic（无 sessionKey）误入双源链路。
 				// 打 log + remoteLog 让运维能定位事件源；不影响其他通道。
+				// 日志兼容性：缺失（null/undefined）→ 'null'；其它非字符串类型 → 'invalid'。
+				const formatField = (v) => v == null
+					? 'null'
+					: (typeof v === 'string' ? v : 'invalid');
 				logger.warn?.(
-					`[coclaw] chat history early-return: missing sessionKey/sessionId`,
+					`[coclaw] chat history early-return: missing/invalid sessionKey/sessionId`,
 				);
 				remoteLog(
-					`chat-history.missing-keys sessionKey=${sessionKey ?? 'null'} sessionId=${sessionId ?? 'null'}`,
+					`chat-history.missing-keys sessionKey=${formatField(sessionKey)} sessionId=${formatField(sessionId)}`,
 				);
 				return;
 			}
-			// topic 上游伪造的 explicit fake sessionKey（形态 `agent:<agentId>:explicit:<sid>`）
-			// 不属于 chat 流水范畴：CoClaw 自管 topic 元信息，不应进 chat-history 桶。
-			// 当前 F1 实验已证明该路径不触发本回调，此守卫属防御性兜底。
-			// 前提假设：(a) sessionKey 首段是 `agent`；(b) `explicit` 占第 3 段（即 parts[2]，
-			// 0-indexed 数）。两条同时成立才命中本守卫；若上游 schema 演进（如挪位置 / 增前缀 /
-			// 改首段名），需复评本守卫。
-			const parts = sessionKey.split(':');
-			if (parts[0] === 'agent' && parts[2] === 'explicit') {
-				remoteLog(`chat-history.skip-explicit sessionKey=${sessionKey}`);
-				return;
-			}
-			// subagent 是 OpenClaw 程序自起的子任务 run（mode=run 一次性 / mode=session 持久绑定），
-			// 形态 `agent:<id>:subagent:<uuid>`，嵌套子代理为 `agent:<id>:subagent:<uuid>:subagent:<uuid2>`。
-			// 它不是人机对话流；父 agent 的 transcript 里已含子代理最终输出（作为 user message 回流），
-			// 因此不入 chat-history。
-			// 判定从 parts[2] 起找 'subagent' 段，避免 agentId 恰好叫 'subagent' 时误伤。
-			if (parts[0] === 'agent' && parts.indexOf('subagent', 2) >= 0) {
-				remoteLog(`chat-history.skip-subagent sessionKey=${sessionKey}`);
+			// sessionKey 路由分类（explicit / subagent / cron 跳过，详见 classifyChatHistorySessionKey）。
+			// 守卫必须与启动期对账 reconcileAll 内的守卫一致——共用同一 helper 避免侧门。
+			const cls = classifyChatHistorySessionKey(sessionKey);
+			if (!cls.ok) {
+				remoteLog(`chat-history.skip-${cls.reason} sessionKey=${sessionKey}`);
 				return;
 			}
+			const parts = sessionKey.split(':');
 			let resolvedAgentId = agentId;
 			if (!resolvedAgentId) {
 				resolvedAgentId = (parts[0] === 'agent' && parts[1]) ? parts[1] : 'main';
@@ -251,6 +261,18 @@ const plugin = {
 					archivedSessionId: event?.resumedFrom,
 				});
 			});
+			// cron 顶替主会话 sid 时不走 session_start hook、不广播 sessions.changed reason=create。
+			// cron_changed action=finished 是 cron 完成的可感知通道（v2026.4.29+ 支持，见
+			// openclaw-repo/src/plugins/hook-types.ts）。main 模式 cron 不带 sessionId → 早返天然过滤；
+			// 真触发顶替的"显式 session:<sk>"/"current" 路径 event.sessionId/sessionKey 都齐。
+			api.on('cron_changed', async (event) => {
+				if (event?.action !== 'finished') return;
+				if (!event?.sessionId || !event?.sessionKey) return;
+				await handleSessionCreated({
+					sessionKey: event.sessionKey,
+					sessionId: event.sessionId,
+				});
+			});
 		}
 
 		// bridge 启动/重启的闭包 helper：把 onSessionCreated 接到 handleSessionCreated。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coclaw/openclaw-coclaw",
-  "version": "0.22.1",
+  "version": "0.22.3",
   "type": "module",
   "license": "Apache-2.0",
   "description": "OpenClaw plugin for remote chat over WebRTC. Run `openclaw coclaw enroll` after install.",

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

@@ -12,6 +12,38 @@ function emptyStore() {
 	return { version: 1 };
 }
 
+/**
+ * 判定 sessionKey 是否应纳入 chat-history 流水。
+ * 不纳入的三类，命中即返回对应 reason：
+ *   - explicit：topic 用的伪 sessionKey，CoClaw 自管不入 chat-history
+ *   - subagent：OpenClaw 程序自起的子任务（含嵌套）
+ *   - cron：isolated cron 跑出的伪 sessionKey（含上游证实主 sessions.json 也会承载此类条目）
+ *
+ * 必须被所有写 chat-history 的入口（事件路径 / 启动对账等）共用，否则启动对账等绕过事件路径
+ * 的入口会把伪 sessionKey 写进 chat-history。
+ *
+ * 非字符串 / 空串 sessionKey 视为非法输入（ok=false reason=null），由 caller 自行决定怎么处理。
+ *
+ * @param {string} sessionKey
+ * @returns {{ ok: boolean, reason: 'explicit' | 'subagent' | 'cron' | null }}
+ */
+export function classifyChatHistorySessionKey(sessionKey) {
+	if (typeof sessionKey !== 'string' || !sessionKey) {
+		return { ok: false, reason: null };
+	}
+	const parts = sessionKey.split(':');
+	if (parts[0] !== 'agent') return { ok: true, reason: null };
+	// 三个跳过类别都用"parts[2] 严格相等"，与上游 routing 一致：
+	// - isCronSessionKey / isSubagentSessionKey 都只在 rest 起始处（即 parts[2]）匹配；
+	// - cron 跑出的子代理（agent:<id>:cron:<jobId>:subagent:<uuid>）上游不视作 subagent，
+	//   由 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' };
+	if (parts[2] === 'cron') return { ok: false, reason: 'cron' };
+	if (parts[2] === 'subagent') return { ok: false, reason: 'subagent' };
+	return { ok: true, reason: null };
+}
+
 /**
  * Chat History 管理器：追踪 chat（sessionKey）下的 session 流水。
  *
@@ -44,7 +76,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]: [...] }
@@ -131,7 +164,44 @@ export class ChatHistoryManager {
 
 	async __persist(agentId) {
 		const store = this.__getStore(agentId);
-		await this.__writeJsonFile(this.__historyFilePath(agentId), store);
+		// 自愈守卫：list[1..]（非头位）若仍有未归档项视为脏数据（cron 顶替 / 旧版本写入 / 异常 race
+		// 残留），强制补 archivedAt。放在 __persist 内是为了覆盖所有写盘路径——新增写入点自动受护。
+		this.__sanitizeAllSessionKeys(store, agentId);
+		try {
+			await this.__writeJsonFile(this.__historyFilePath(agentId), store);
+		} catch (err) {
+			// 写盘失败时清除该 agent 的内存 cache：caller 此前在 mutex 内已对 in-place list 做过
+			// unshift / splice / sanitize，这些修改不能随后被下一次"reload 命中 cache 不读盘"
+			// 的路径误持久化。删 cache 让下次操作的 __reloadFromDisk 必须重读磁盘（或 ENOENT 降级
+			// 为 empty store），保证内存与磁盘最终一致。
+			this.__cache.delete(agentId);
+			throw err;
+		}
+	}
+
+	/**
+	 * 遍历 store 内每个 sessionKey 的 list，把 `list[1..]` 中 `!archivedAt` 的项强制
+	 * 写上 `archivedAt = Date.now()`。每修一条同时打本地 warn + remoteLog 暴露信号。
+	 * @param {object} store
+	 * @param {string} agentId
+	 */
+	__sanitizeAllSessionKeys(store, agentId) {
+		if (!store || typeof store !== 'object') return;
+		const now = Date.now();
+		for (const [sessionKey, list] of Object.entries(store)) {
+			if (!Array.isArray(list) || list.length <= 1) continue;
+			for (let i = 1; i < list.length; i++) {
+				const item = list[i];
+				if (!item || typeof item !== 'object' || item.archivedAt) continue;
+				item.archivedAt = now;
+				this.__logger.warn?.(
+					`[coclaw] chat-history sanitize: non-head unarchived entry coerced sessionKey=${sessionKey} sid=${item.sessionId}`,
+				);
+				remoteLog(
+					`chat-history.sanitize-coerce sessionKey=${sessionKey} sid=${item.sessionId} agentId=${agentId}`,
+				);
+			}
+		}
 	}
 
 	/**
@@ -153,7 +223,10 @@ export class ChatHistoryManager {
 	 * @param {{ agentId: string, sessionKey: string, currentSessionId: string, archivedSessionId?: string }} params
 	 */
 	async recordSessionTransition({ agentId, sessionKey, currentSessionId, archivedSessionId }) {
-		if (!sessionKey || !currentSessionId) return;
+		// 严格类型校验：上游 hook payload 异常时（非字符串 sessionId / sessionKey）静默拒绝，避免把脏值落盘。
+		if (typeof sessionKey !== 'string' || !sessionKey) return;
+		if (typeof currentSessionId !== 'string' || !currentSessionId) return;
+		if (typeof archivedSessionId !== 'string' || !archivedSessionId) archivedSessionId = undefined;
 		// 规范化：archivedSessionId 与 currentSessionId 相同属上游契约异常（resumedFrom 不应等于 sessionId），
 		// 丢弃避免在空 list 起手时写出"同 sid 既是头又是归档"的双份记录。打 remoteLog 暴露信号
 		// 让运维捕捉到上游可能的回归——只在真触发时打一次，正常路径噪声为零。
@@ -206,6 +279,42 @@ export class ChatHistoryManager {
 		});
 	}
 
+	/**
+	 * 启动期对账：把 sessions.json 当前 entries 喂进来，对每条调
+	 * recordSessionTransition；现有幂等 + sanitize 自动吞重复。用于覆盖 plugin/gateway
+	 * 重启窗口期 cron 顶替导致的漏归档（cron_changed hook 是主通道，但 gateway 重启不回放
+	 * 已完成的 cron event，靠启动对账兜底当前 sessions.json 的 head sid）。
+	 *
+	 * sessions.json 里可能含 isolated cron / subagent / explicit 形态的 sessionKey
+	 * 条目（上游 run-session-state.ts:57-60 证实 isolated cron 写主 sessions.json），
+	 * 用 classifyChatHistorySessionKey 守卫滤掉避免污染 chat-history。
+	 *
+	 * 单条 entry 抛错 try/catch 隔离，不阻塞后续；caller 已在外层 .catch 兜底。
+	 *
+	 * @param {string} agentId
+	 * @param {{ sessionKey: string, sessionId: string }[]} entries
+	 */
+	async reconcileAll(agentId, entries) {
+		if (!Array.isArray(entries)) return;
+		for (const entry of entries) {
+			if (!entry || typeof entry !== 'object') continue;
+			const { ok } = classifyChatHistorySessionKey(entry.sessionKey);
+			if (!ok) continue;
+			try {
+				await this.recordSessionTransition({
+					agentId,
+					sessionKey: entry.sessionKey,
+					currentSessionId: entry.sessionId,
+				});
+			}
+			catch (err) {
+				this.__logger.warn?.(
+					`[coclaw] chat-history reconcile entry failed sessionKey=${entry.sessionKey}: ${String(err?.message ?? err)}`,
+				);
+			}
+		}
+	}
+
 	/**
 	 * 获取指定 chat 的 session 列表（原始数组：首位可能是未归档的当前活跃 session）。
 	 * 每次调用从磁盘重载，确保跨模块实例一致性

package/src/file-manager/handler.js

@@ -796,8 +796,10 @@ export function createFileHandler({ resolveWorkspace, logger, deps = {} }) {
 				// done 已收到但 drain 未完成 — finishUpload 中会检测 dcClosed 并清理 tmp
 				if (!finishing) finishUpload();
 			} else {
+				// 等 ws 关闭后再 unlink——fopen 未完成时直接 safeUnlink 会扑空被吞，
+				// 随后 fopen 完成创建文件却没人清，留下孤儿 tmp
+				ws.on('close', () => safeUnlink(tmpPath));
 				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}`);
@@ -810,8 +812,9 @@ export function createFileHandler({ resolveWorkspace, logger, deps = {} }) {
 			wsError = true;
 			draining = false;
 			pendingQueue.length = 0;
+			// 同上：等 ws 关闭后再 unlink，避开 fopen-vs-unlink race
+			ws.on('close', () => safeUnlink(tmpPath));
 			ws.destroy();
-			safeUnlink(tmpPath);
 			const elapsed = Date.now() - startTime;
 			/* c8 ignore next -- ?? fallback for non-Error throw */
 			const errMsg = err?.message ?? String(err);

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

@@ -1717,6 +1717,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

@@ -37,6 +37,10 @@ async function safeReaddir(dir) {
 	}
 }
 
+// OpenClaw ISO 时间戳：YYYY-MM-DDTHH-MM-SS[.sss]Z（与 artifacts.ts ARCHIVE_TIMESTAMP_RE 对齐：毫秒可选）
+// 用于过滤 rsync/备份等场景带入的非法后缀（如 .jsonl.reset.<ts>.bak）
+const ARCHIVE_TS_RE = /^\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}(?:\.\d{3})?Z$/;
+
 async function safeAccess(filePath) {
 	try { await fsp.access(filePath); return true; }
 	catch (err) {
@@ -79,28 +83,46 @@ 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;
 	}
 
+	// 启动期对账用：直接读 sessions.json 把当前所有 sessionKey -> sessionId 摘出来。
+	// 不扫 transcript 文件 / 不做 stat，因此远比 listAll 轻量；缺/坏文件返回空数组。
+	async function listAllEntries(agentId = 'main') {
+		const idx = await readIndex(agentId);
+		// sessions.json 异常被写成数组时，Object.entries 会生成 "0"/"1" 假键，
+		// 把它们当 sessionKey 喂下游会污染。直接拒绝数组形态，同时打 warn 暴露异常。
+		if (Array.isArray(idx)) {
+			logger.warn?.(`[session-manager] sessions.json for agent=${agentId} is an array, expected object — returning empty entries`);
+			return [];
+		}
+		const out = [];
+		for (const [sessionKey, item] of Object.entries(idx)) {
+			const sid = item?.sessionId;
+			if (typeof sessionKey !== 'string' || !sessionKey) continue;
+			if (typeof sid !== 'string' || !sid) continue;
+			out.push({ sessionKey, sessionId: sid });
+		}
+		return out;
+	}
+
 	async function listAll(params = {}) {
 		const agentId = typeof params.agentId === 'string' && params.agentId.trim() ? params.agentId.trim() : 'main';
 		const limit = clamp(params.limit, 1, 200, 50);
@@ -152,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,
@@ -160,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,
 			});
@@ -182,16 +203,24 @@ export function createSessionManager(options = {}) {
 
 	async function resolveTranscriptFile(agentId, sessionId) {
 		const dir = sessionsDir(agentId);
-		// live 文件优先：同一 sessionId 可能同时存在 live 和 reset 文件
+		// live 文件优先：同一 sessionId 可能同时存在 live 和 reset/deleted 归档
 		// （OpenClaw reset 后复用 sessionId），live 代表当前活跃 transcript
 		const livePath = resolveTranscriptPath(sessionId, agentId);
 		if (await safeAccess(livePath)) return livePath;
 
-		const files = await safeReaddir(dir);
+		// .reset.<ts> 与 .deleted.<ts> 都代表 session 的最终态，合并扫描按时间戳取最新
+		// 时间戳是 OpenClaw ISO YYYY-MM-DDTHH-MM-SS[.sss]Z（artifacts.ts 锁住毫秒可选），字典序 = 时间序
 		const resetPrefix = `${sessionId}.jsonl.reset.`;
-		const resetCandidates = [];
+		const deletedPrefix = `${sessionId}.jsonl.deleted.`;
+		const files = await safeReaddir(dir);
+		const candidates = [];
 		for (const name of files) {
-			if (!name.startsWith(resetPrefix)) continue;
+			let archiveStamp;
+			if (name.startsWith(resetPrefix)) archiveStamp = name.slice(resetPrefix.length);
+			else if (name.startsWith(deletedPrefix)) archiveStamp = name.slice(deletedPrefix.length);
+			else continue;
+			// 严格 ISO 时间戳校验，过滤 .jsonl.reset.<ts>.bak 等带尾巴的备份/同步残留
+			if (!ARCHIVE_TS_RE.test(archiveStamp)) continue;
 			const full = nodePath.join(dir, name);
 			let stat;
 			try { stat = await fsp.stat(full); }
@@ -201,21 +230,21 @@ export function createSessionManager(options = {}) {
 				throw err;
 			}
 			/* c8 ignore stop */
-			resetCandidates.push({
+			candidates.push({
 				path: full,
-				archiveStamp: name.slice(resetPrefix.length),
+				archiveStamp,
 				updatedAt: stat.mtimeMs,
 			});
 		}
-		resetCandidates.sort((a, b) => {
+		candidates.sort((a, b) => {
 			if (a.archiveStamp !== b.archiveStamp) {
 				return b.archiveStamp.localeCompare(a.archiveStamp);
 			}
-			/* c8 ignore next -- 同一 sessionId 的 reset 文件不会有相同 archiveStamp */
+			/* c8 ignore next -- 同 sessionId 同 archiveStamp 的归档实测 0 case */
 			return b.updatedAt - a.updatedAt;
 		});
-		if (resetCandidates.length > 0) {
-			return resetCandidates[0].path;
+		if (candidates.length > 0) {
+			return candidates[0].path;
 		}
 		return null;
 	}
@@ -252,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,
@@ -272,6 +299,7 @@ export function createSessionManager(options = {}) {
 	/**
 	 * 按 sessionId 获取消息，返回完整 JSONL 行级结构。
 	 * 只返回 type==="message" 且有合法 message.role 的行。
+	 * limit 语义：不传/null/非 number/NaN/Infinity/<1 → 返回全部；>=1 的有限 number → 取最后 Math.trunc(limit) 条。无默认/最大值。
 	 * @param {{ sessionId: string, agentId?: string, limit?: number }} params
 	 * @returns {Promise<{ messages: object[] }>}
 	 */
@@ -279,7 +307,10 @@ export function createSessionManager(options = {}) {
 		const agentId = typeof params.agentId === 'string' && params.agentId.trim() ? params.agentId.trim() : 'main';
 		const sessionId = typeof params.sessionId === 'string' ? params.sessionId.trim() : '';
 		if (!sessionId) throw new Error('sessionId required');
-		const limit = clamp(params.limit, 1, 500, 500);
+		// limit 类型严格：只接受 number 且 >= 1。string/bool/array 走非 number 分支被拒，
+		// 0 / 负数 / NaN / Infinity / (0,1) 区间也都视为"不限"——(0,1) 不视为不限的话 Math.trunc 后会变 0、slice(-0) 退化为全部
+		const useLimit = typeof params.limit === 'number' && Number.isFinite(params.limit) && params.limit >= 1;
+		const limitNum = useLimit ? Math.trunc(params.limit) : 0;
 		const file = await resolveTranscriptFile(agentId, sessionId);
 		if (!file) {
 			return { messages: [] };
@@ -296,14 +327,12 @@ 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)}`);
 			}
 		}
-		// 取最后 limit 条
-		const sliced = messages.length > limit ? messages.slice(-limit) : messages;
+		const sliced = (useLimit && messages.length > limitNum) ? messages.slice(-limitNum) : messages;
 		return { messages: sliced };
 	}
 
-	return { listAll, get, getById };
+	return { listAll, listAllEntries, get, getById };
 }

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