@coclaw/openclaw-coclaw 0.21.5 → 0.22.2

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';
@@ -17,6 +17,8 @@ import { createFileHandler } from './src/file-manager/handler.js';
 import { abortAgentRun } from './src/agent-abort.js';
 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 { getPluginVersion, __resetPluginVersion } from './src/plugin-version.js';
 export { getPluginVersion, __resetPluginVersion };
@@ -132,7 +134,7 @@ function respondInvalid(respond, message) {
 const plugin = {
 	id: 'openclaw-coclaw',
 	name: 'CoClaw',
-	description: 'OpenClaw CoClaw channel plugin for remote chat',
+	description: 'OpenClaw plugin for remote chat over WebRTC',
 	register(api) {
 		// 按 OpenClaw SDK 入口模式分叉（参照 defineChannelPluginEntry，见上游 plugin-sdk/core.ts 的
 		// defineChannelPluginEntry 实现 与 docs/plugins/sdk-entrypoints.md）：
@@ -173,36 +175,108 @@ const plugin = {
 		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)}`);
-		});
+		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)}`);
+			});
 
-		// 追踪 chat 因 reset 产生的孤儿 session
+		// 追踪 chat 因 reset 产生的 session 流水。双源回调（hook + sessions.changed）共用 helper。
+		// recordSessionTransition 内部已 __reloadFromDisk + mutex，外层无需再 cache.has + load。
+		//
+		// agentId 解析：hook 路径有 ctx.agentId（显式契约，优先用）；sessions.changed 路径
+		// gateway broadcast payload 不含 agentId（见 openclaw-repo emitSessionsChanged），
+		// 只能 fallback 切 sessionKey（`agent:<agentId>:*` → parts[1]）。当前 sessionKey schema
+		// 下两路径解析结果等价；多 agent topic 启用后若上游 sessionKey schema 加前缀会需复评。
+		//
+		// archivedSessionId 解析：hook 路径来自 event.resumedFrom；sessions.changed payload
+		// 不带（无 previousSessionId 字段）→ 进 manager 时为 undefined。manager 不会去
+		// "推断字段值"，而是把文件首位未归档头直接翻为归档（补 archivedAt）后再 unshift
+		// 新头——等价于"以文件首位 sessionId 作为前任"。
+		//
+		// 该 helper 可直接作为 bridge.onSessionCreated 回调（签名兼容；缺失字段走兜底：
+		// agentId 走 parts[1] fallback、archivedSessionId 走 manager 翻 head 路径）。
+		async function handleSessionCreated({ agentId, sessionKey, sessionId, archivedSessionId }) {
+			// 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/invalid sessionKey/sessionId`,
+				);
+				remoteLog(
+					`chat-history.missing-keys sessionKey=${formatField(sessionKey)} sessionId=${formatField(sessionId)}`,
+				);
+				return;
+			}
+			// 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';
+			}
+			try {
+				await chatHistoryManager.recordSessionTransition({
+					agentId: resolvedAgentId,
+					sessionKey,
+					currentSessionId: sessionId,
+					archivedSessionId,
+				});
+			} catch (err) {
+				logger.warn?.(`[coclaw] chat history record failed: ${String(err?.message ?? err)}`);
+			}
+		}
 		if (typeof api.on === 'function') {
 			api.on('session_start', async (event, ctx) => {
-				if (!event.resumedFrom) return; // 首次创建，无前任
-				const agentId = ctx?.agentId ?? 'main';
-				const sessionKey = event.sessionKey;
-				if (!sessionKey) return;
-				try {
-					if (!chatHistoryManager.__cache.has(agentId)) {
-						await chatHistoryManager.load(agentId);
-					}
-					await chatHistoryManager.recordArchived({
-						agentId,
-						sessionKey,
-						sessionId: event.resumedFrom,
-					});
-				} catch (err) {
-					logger.warn?.(`[coclaw] chat history record failed: ${String(err?.message ?? err)}`);
-				}
+				// event.sessionId 是新 sid（必填），event.resumedFrom 是旧 sid（可选），ctx.agentId 可信
+				await handleSessionCreated({
+					agentId: ctx?.agentId,
+					sessionKey: event?.sessionKey,
+					sessionId: event?.sessionId,
+					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。
+		// 所有 restartRealtimeBridge 调用必须走这个 helper，避免漏接回调。
+		async function restartBridge() {
+			await restartRealtimeBridge({
+				logger,
+				pluginConfig: api.pluginConfig,
+				onSessionCreated: handleSessionCreated,
 			});
 		}
 
 		api.registerService({
 			id: 'coclaw-realtime-bridge',
 			async start() {
-				await restartRealtimeBridge({ logger, pluginConfig: api.pluginConfig });
+				await restartBridge();
 			},
 			async stop() {
 				await stopRealtimeBridge();
@@ -239,11 +313,11 @@ const plugin = {
 				});
 			} catch (err) {
 				// bind 失败时恢复 bridge（best-effort，不覆盖原始错误）
-				await restartRealtimeBridge({ logger, pluginConfig: api.pluginConfig }).catch(() => {});
+				await restartBridge().catch(() => {});
 				throw err;
 			}
 			// bind 已持久化，restart 失败不影响结果
-			await restartRealtimeBridge({ logger, pluginConfig: api.pluginConfig }).catch((err) => {
+			await restartBridge().catch((err) => {
 				logger.warn?.(`[coclaw] bridge restart failed after bind: ${err?.message ?? err}`);
 			});
 			return result;
@@ -276,11 +350,9 @@ const plugin = {
 					serverUrl: params?.serverUrl,
 				});
 				respond(true, {
-					status: {
-						clawId: result.clawId,
-						rebound: result.rebound,
-						previousClawId: result.previousClawId,
-					},
+					clawId: result.clawId,
+					rebound: result.rebound,
+					previousClawId: result.previousClawId,
 				});
 			}
 			catch (err) {
@@ -296,7 +368,7 @@ const plugin = {
 					return;
 				}
 				const result = await doUnbind({ serverUrl: params?.serverUrl });
-				respond(true, { status: { clawId: result.clawId } });
+				respond(true, { clawId: result.clawId });
 			}
 			catch (err) {
 				respondError(respond, err);
@@ -325,12 +397,10 @@ const plugin = {
 
 				// 立即返回认领码给 CLI
 				respond(true, {
-					status: {
-						code: result.code,
-						appUrl: result.appUrl,
-						expiresAt: result.expiresAt,
-						expiresMinutes,
-					},
+					code: result.code,
+					appUrl: result.appUrl,
+					expiresAt: result.expiresAt,
+					expiresMinutes,
 				});
 
 				// 后台 fire-and-forget：等待认领并保存 config + 启 bridge
@@ -341,7 +411,7 @@ const plugin = {
 					signal: abortController.signal,
 				}).then(async () => {
 					if (abortController.signal.aborted) return;
-					await restartRealtimeBridge({ logger, pluginConfig: api.pluginConfig });
+					await restartBridge();
 					logger.info?.('[coclaw] enroll completed, bridge restarted');
 				}).catch((err) => {
 					if (abortController.signal.aborted) return;
@@ -691,6 +761,25 @@ const plugin = {
 			}
 		});
 
+		// provider 认证管理 RPC（API key 写入 / 列表 / 撤销）。SDK 走懒加载 dynamic import，
+		// 不增加本插件 cold-load 开销，也让测试环境无需 openclaw 包就能加载 index.js。
+		// loadSdk 字面量必须留在本入口源码里：OpenClaw plugin loader 只扫入口文件识别
+		// `openclaw/plugin-sdk/*` 字符串字面量、命中后才把整张依赖图过 jiti 改写到自家 dist；
+		// 字面量留在子模块里 loader 看不到 → 整张图走原生 Node 解析必败（plugin 部署目录不带 openclaw 包）
+		registerProviderAuthHandlers(api, {
+			loadSdk: () => import('openclaw/plugin-sdk/provider-auth'),
+		});
+
+		// 模型默认配置 RPC（coclaw.model.set / list）。三个 SDK 子入口的字面量
+		// dynamic import 必须留在本入口源码——OpenClaw plugin loader 只扫入口源码
+		// 命中 `openclaw/plugin-sdk/*` 字面量并触发 jiti 重写；藏在子模块的字面量
+		// loader 看不到 → 原生 Node 解析必败。
+		registerModelDefaultHandlers(api, {
+			loadConfigMutation: () => import('openclaw/plugin-sdk/config-mutation'),
+			loadModelsProviderRuntime: () => import('openclaw/plugin-sdk/models-provider-runtime'),
+			loadProviderAuth: () => import('openclaw/plugin-sdk/provider-auth'),
+		});
+
 		const scheduler = new AutoUpgradeScheduler({ pluginId: api.id, logger });
 		api.registerService({
 			id: 'coclaw-auto-upgrade',
@@ -738,7 +827,7 @@ const plugin = {
 							signal: abortController.signal,
 						}).then(async () => {
 							if (abortController.signal.aborted) return;
-							await restartRealtimeBridge({ logger, pluginConfig: api.pluginConfig });
+							await restartBridge();
 							logger.info?.('[coclaw] enroll completed via slash command, bridge restarted');
 						}).catch((err) => {
 							if (abortController.signal.aborted) return;

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "openclaw-coclaw",
   "name": "CoClaw",
-  "description": "OpenClaw CoClaw channel plugin for remote chat. Run `openclaw coclaw enroll` after install to connect to CoClaw.",
+  "description": "OpenClaw plugin for remote chat over WebRTC. Run `openclaw coclaw enroll` after install.",
   "activation": {
     "onStartup": true
   },

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@coclaw/openclaw-coclaw",
-  "version": "0.21.5",
+  "version": "0.22.2",
   "type": "module",
   "license": "Apache-2.0",
-  "description": "OpenClaw CoClaw channel plugin for remote chat. Run `openclaw coclaw enroll` after install to connect to CoClaw.",
+  "description": "OpenClaw plugin for remote chat over WebRTC. Run `openclaw coclaw enroll` after install.",
   "repository": {
     "type": "git",
     "url": "https://github.com/coclaw/coclaw.git",
@@ -41,7 +41,7 @@
       "./index.js"
     ],
     "install": {
-      "minHostVersion": ">=2026.2.19"
+      "minHostVersion": ">=2026.3.22"
     }
   },
   "scripts": {
@@ -51,6 +51,7 @@
     "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'",
+    "e2e": "node --test --test-concurrency=1 e2e/*.e2e.spec.js",
     "verify": "pnpm check && pnpm test",
     "link": "bash ./scripts/link.sh",
     "unlink": "bash ./scripts/unlink.sh",
@@ -62,7 +63,7 @@
     "release:versions": "npm view @coclaw/openclaw-coclaw versions --json --registry=https://registry.npmjs.org/ && npm view @coclaw/openclaw-coclaw versions --json"
   },
   "dependencies": {
-    "@coclaw/pion-node": "^0.3.0",
+    "@coclaw/pion-node": "^0.4.0",
     "werift": "^0.19.0",
     "ws": "^8.19.0"
   },

package/src/channel-plugin.js

@@ -17,7 +17,7 @@ export const coclawChannelPlugin = {
 		label: 'CoClaw',
 		selectionLabel: 'CoClaw',
 		docsPath: 'https://docs.coclaw.net',
-		blurb: 'CoClaw channel plugin for remote chat',
+		blurb: 'CoClaw channel plugin for remote chat over WebRTC',
 	},
 	capabilities: {
 		chatTypes: ['direct'],

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

@@ -4,6 +4,7 @@ import nodePath from 'node:path';
 import { agentSessionsDir } from '../claw-paths.js';
 import { atomicWriteJsonFile } from '../utils/atomic-write.js';
 import { createMutex } from '../utils/mutex.js';
+import { remoteLog } from '../remote-log.js';
 
 const HISTORY_FILE = 'coclaw-chat-history.json';
 
@@ -12,18 +13,57 @@ function emptyStore() {
 }
 
 /**
- * Chat History 管理器：追踪 chat（sessionKey）因 reset 产生的孤儿 session。
+ * 判定 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 流水。
  *
  * 每个 agentId 对应一份 coclaw-chat-history.json，按需懒加载到内存。
  * 写操作通过 mutex + atomicWriteJsonFile 保证一致性。
  *
- * 文件结构示例：
+ * 文件结构示例（archivedAt 是 Date.now() 落的 13 位毫秒时间戳）：
  * {
  *   "version": 1,
  *   "agent:main:main": [
- *     { "sessionId": "xxx", "archivedAt": 1742003000000 }
+ *     { "sessionId": "current-sid" },                          // 首位：未归档头 = 当前活跃 session
+ *     { "sessionId": "older",    "archivedAt": 1742003000000 } // 第二位起：已归档（新→旧）
  *   ]
  * }
+ *
+ * 详见 plugins/openclaw/docs/architecture.md
+ *
+ * 双源事件供给：
+ * - session_start hook：event 同时含新 sid (currentSessionId) + 旧 sid (archivedSessionId)
+ * - sessions.changed reason=create：payload 含 sessionKey + 新 sid，旧 sid 从文件首位推断
  */
 export class ChatHistoryManager {
 	/**
@@ -87,14 +127,29 @@ export class ChatHistoryManager {
 				this.__cache.set(agentId, data);
 				return;
 			}
-		} catch {
-			// 文件不存在或解析失败，初始化空数据
+		} catch (err) {
+			this.__reportLoadError(filePath, err, '__doLoad');
 		}
 		this.__cache.set(agentId, emptyStore());
 	}
 
+	/**
+	 * 读盘失败分流：ENOENT 是正常情况（首次启动文件不存在）静默；
+	 * 其他错误（权限、磁盘损坏、JSON 破损）有诊断价值，打 warn + remoteLog 标识可疑。
+	 */
+	__reportLoadError(filePath, err, callsite) {
+		if (err?.code === 'ENOENT') return;
+		const fname = nodePath.basename(filePath);
+		this.__logger.warn?.(
+			`[coclaw] chat-history ${callsite} read failed for ${fname}: ${String(err?.message ?? err)}`,
+		);
+		remoteLog(
+			`chat-history.reload-error site=${callsite} file=${fname} msg=${String(err?.message ?? err)}`,
+		);
+	}
+
 	__ensureLoaded(agentId) {
-		/* c8 ignore start -- recordArchived/list 均先 __reloadFromDisk，此分支为防御性守卫 */
+		/* c8 ignore start -- recordSessionTransition/list 均先 __reloadFromDisk，此分支为防御性守卫 */
 		if (!this.__cache.has(agentId)) {
 			throw new Error(`ChatHistoryManager: agent "${agentId}" not loaded, call load() first`);
 		}
@@ -108,15 +163,76 @@ 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;
+		}
 	}
 
 	/**
-	 * 记录一个被抛弃的孤儿 session
-	 * @param {{ agentId: string, sessionKey: string, sessionId: string }} params
+	 * 遍历 store 内每个 sessionKey 的 list，把 `list[1..]` 中 `!archivedAt` 的项强制
+	 * 写上 `archivedAt = Date.now()`。每修一条同时打本地 warn + remoteLog 暴露信号。
+	 * @param {object} store
+	 * @param {string} agentId
 	 */
-	async recordArchived({ agentId, sessionKey, sessionId }) {
-		if (!sessionKey || !sessionId) return;
+	__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}`,
+				);
+			}
+		}
+	}
+
+	/**
+	 * 记录一次 session 转换。双源事件共用：
+	 * - session_start hook：
+	 *     currentSessionId = event.sessionId，
+	 *     archivedSessionId = event.resumedFrom
+	 * - sessions.changed reason=create：
+	 *     currentSessionId = payload.sessionId，
+	 *     archivedSessionId 不提供（从文件首位推断）
+	 *
+	 * 文件首位（list[0]）维护当前活跃 session（未归档），其后是已归档 item（新→旧）。
+	 *
+	 * 幂等：head 已是 currentSessionId 且
+	 *   - 无 archivedSessionId，或
+	 *   - archivedSessionId 已存在于 list 中
+	 * 时整体 no-op（不写盘）。
+	 *
+	 * @param {{ agentId: string, sessionKey: string, currentSessionId: string, archivedSessionId?: string }} params
+	 */
+	async recordSessionTransition({ agentId, sessionKey, currentSessionId, archivedSessionId }) {
+		// 严格类型校验：上游 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 暴露信号
+		// 让运维捕捉到上游可能的回归——只在真触发时打一次，正常路径噪声为零。
+		if (archivedSessionId === currentSessionId) {
+			remoteLog(`chat-history.archived-equals-current sessionKey=${sessionKey} sid=${currentSessionId}`);
+			archivedSessionId = undefined;
+		}
 		await this.__mutex(agentId).withLock(async () => {
 			// 从磁盘重载确保最新状态：list() 无锁覆写 __cache 可能导致缓存过期
 			await this.__reloadFromDisk(agentId);
@@ -124,23 +240,93 @@ export class ChatHistoryManager {
 			if (!Array.isArray(store[sessionKey])) {
 				store[sessionKey] = [];
 			}
-			// 去重：同一 sessionId 不重复记录
-			if (store[sessionKey].some((r) => r.sessionId === sessionId)) return;
-			// 头部插入（最近的在前）
-			store[sessionKey].unshift({
-				sessionId,
-				archivedAt: Date.now(),
-			});
+			const list = store[sessionKey];
+			const head = list[0];
+			const headIsCurrent = head && !head.archivedAt && head.sessionId === currentSessionId;
+			const archivedAlreadyInList = archivedSessionId
+				&& list.some((it) => it.sessionId === archivedSessionId);
+			// 完全 no-op：head 已是 current 且无新 archived 要追加
+			if (headIsCurrent && (!archivedSessionId || archivedAlreadyInList)) return;
+
+			// head 已是 current（双源到达：第二个事件提供了之前未带的 archivedSessionId）
+			// → 不动 head，仅在第二位插入 archivedSessionId
+			if (headIsCurrent) {
+				list.splice(1, 0, { sessionId: archivedSessionId, archivedAt: Date.now() });
+				await this.__persist(agentId);
+				return;
+			}
+
+			// stale 事件防御：currentSessionId 已存在于 list 其他位置（即已被归档）。
+			// 此时若继续走"翻 head"会把真正活跃的头错翻成归档，并让该 sid 在 list 中重复出现。
+			// 触发场景：A→B→C 快速连续 reset 时，hook 与 sessions.changed 跨通道乱序到达，
+			//   旧 transition 的事件晚于新 transition 的事件被处理。
+			if (list.some((it) => it.sessionId === currentSessionId)) return;
+
+			// 一般路径：翻 head 为归档（若未归档），然后处理 archivedSessionId，最后头插新 head
+			// head 已归档（老格式磁盘数据 / 已正常归档的 list）→ 跳过翻动直接 unshift
+			if (head && !head.archivedAt) {
+				head.archivedAt = Date.now();
+			}
+			// archivedSessionId 与 head 不同且不在 list → 在第二位追加（保证不丢前任记录）
+			if (archivedSessionId
+				&& archivedSessionId !== head?.sessionId
+				&& !list.some((it) => it.sessionId === archivedSessionId)) {
+				list.splice(1, 0, { sessionId: archivedSessionId, archivedAt: Date.now() });
+			}
+			list.unshift({ sessionId: currentSessionId });
 			await this.__persist(agentId);
 		});
 	}
 
 	/**
-	 * 获取指定 chat 的孤儿 session 列表。
+	 * 启动期对账：把 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）。
 	 * 每次调用从磁盘重载，确保跨模块实例一致性
 	 * （OpenClaw 的 hook 和 gateway method 可能在不同 ESM 模块实例中运行）。
+	 *
+	 * RPC 契约：`coclaw.chatHistory.list` 直接透传本返回值，不做服务端过滤；调用方
+	 * （UI / 其它消费者）按 `archivedAt != null` 自行过滤未归档头与孤儿历史段。
+	 *
+	 * **返回值是 cache 引用，调用方禁止 mutate**（不要 splice / sort / 改 item 字段）；
+	 * RPC handler 立刻 JSON 序列化所以无副作用，进程内消费者若需要修改请先 deep copy。
+	 *
 	 * @param {{ agentId: string, sessionKey: string }} params
-	 * @returns {Promise<{ history: { sessionId: string, archivedAt: number }[] }>}
+	 * @returns {Promise<{ history: { sessionId: string, archivedAt?: number }[] }>}
 	 */
 	async list({ agentId, sessionKey }) {
 		await this.__reloadFromDisk(agentId);
@@ -162,8 +348,8 @@ export class ChatHistoryManager {
 				this.__cache.set(agentId, data);
 				return;
 			}
-		} catch {
-			// 文件不存在或解析失败
+		} catch (err) {
+			this.__reportLoadError(filePath, err, '__reloadFromDisk');
 		}
 		if (!this.__cache.has(agentId)) {
 			this.__cache.set(agentId, emptyStore());

package/src/claw-paths.js

@@ -16,6 +16,7 @@ import nodePath from 'node:path';
 import { getRuntime } from './runtime.js';
 
 const CHANNEL_ID = 'coclaw';
+const MAIN_AGENT_ID = 'main';
 
 /**
  * OpenClaw 真实 state 目录
@@ -81,4 +82,17 @@ export function sessionTranscriptPath(sessionId, agentId, entry) {
 	return nodePath.join(agentSessionsDir(agentId), `${sessionId}.jsonl`);
 }
 
+/**
+ * main agent 的 agentDir（auth-profiles.json / auth-state.json 等凭据文件所在目录）
+ *
+ * OpenClaw provider-auth helper 的 `agentDir` 入参约定**含 `/agent` 子目录**
+ * （上游 `resolveOpenClawAgentDir` 内部就是拼到这一层），见 mental-model 陷阱 #14。
+ * 凭据相关 RPC（provider-auth setApiKey / list / remove）一律走 main agent
+ * 一份就够——所有 agent 通过 OpenClaw 的层叠合并自动可见（mental-model § 4.2-4.3）。
+ * @returns {string}
+ */
+export function mainAgentDir() {
+	return nodePath.join(clawStateDir(), 'agents', MAIN_AGENT_ID, 'agent');
+}
+
 export { CHANNEL_ID };