@coclaw/openclaw-coclaw 0.21.4 → 0.22.1

package/README.md

@@ -92,7 +92,7 @@ pnpm run release:versions                  # 显示所有已发布版本
 | `coclaw.files.delete` | 删除工作区文件/目录 |
 | `coclaw.files.mkdir` | 创建工作区目录 |
 | `coclaw.files.create` | 创建空文件 |
-| `nativeui.sessions.listAll` | 列出所有 session（分页 + 标题推导） |
+| `nativeui.sessions.listAll` | 列出所有 session（分页） |
 | `nativeui.sessions.get` | 获取 session 原始 JSONL 行（分页） |
 
 ## Gateway Services

package/index.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）：
@@ -177,32 +179,94 @@ const plugin = {
 			logger.warn?.(`[coclaw] chat history manager load 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 }) {
+			if (!sessionKey || !sessionId) {
+				// 早返值得警惕：上游事件 schema 异常，或 topic（无 sessionKey）误入双源链路。
+				// 打 log + remoteLog 让运维能定位事件源；不影响其他通道。
+				logger.warn?.(
+					`[coclaw] chat history early-return: missing sessionKey/sessionId`,
+				);
+				remoteLog(
+					`chat-history.missing-keys sessionKey=${sessionKey ?? 'null'} sessionId=${sessionId ?? 'null'}`,
+				);
+				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}`);
+				return;
+			}
+			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,
+				});
+			});
+		}
+
+		// 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 +303,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 +340,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 +358,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 +387,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 +401,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;
@@ -363,21 +423,21 @@ const plugin = {
 				// best-effort ensure：失败不阻断 listAll
 				try { await ensureAgentSession(agentId); }
 				catch {}
-				respond(true, manager.listAll(params ?? {}));
+				respond(true, await manager.listAll(params ?? {}));
 			}
 			catch (err) {
 				respondError(respond, err);
 			}
 		});
 
-		api.registerGatewayMethod('nativeui.sessions.get', ({ params, respond }) => {
+		api.registerGatewayMethod('nativeui.sessions.get', async ({ params, respond }) => {
 			try {
 				const sessionId = params?.sessionId;
 				if (typeof sessionId !== 'string' || sessionId.trim().length === 0) {
 					respondInvalid(respond, 'sessionId required');
 					return;
 				}
-				respond(true, manager.get(params ?? {}));
+				respond(true, await manager.get(params ?? {}));
 			}
 			catch (err) {
 				respondError(respond, err);
@@ -474,7 +534,7 @@ const plugin = {
 			}
 		});
 
-		api.registerGatewayMethod('coclaw.topics.getHistory', ({ params, respond }) => {
+		api.registerGatewayMethod('coclaw.topics.getHistory', async ({ params, respond }) => {
 			try {
 				const topicId = params?.topicId?.trim?.();
 				if (!topicId) {
@@ -483,7 +543,7 @@ const plugin = {
 				}
 				const agentId = params?.agentId?.trim?.() || 'main';
 				// 直接复用 session-manager 的 get()，topicId 即 sessionId
-				respond(true, manager.get({ agentId, sessionId: topicId }));
+				respond(true, await manager.get({ agentId, sessionId: topicId }));
 			}
 			catch (err) {
 				respondError(respond, err);
@@ -577,7 +637,7 @@ const plugin = {
 		});
 
 		// TODO: coclaw.topics.getHistory 未来可废弃，UI 改用 coclaw.sessions.getById
-		api.registerGatewayMethod('coclaw.sessions.getById', ({ params, respond }) => {
+		api.registerGatewayMethod('coclaw.sessions.getById', async ({ params, respond }) => {
 			try {
 				const sessionId = params?.sessionId?.trim?.();
 				if (!sessionId) {
@@ -586,7 +646,7 @@ const plugin = {
 				}
 				const agentId = params?.agentId?.trim?.() || 'main';
 				const limit = params?.limit;
-				respond(true, manager.getById({ agentId, sessionId, limit }));
+				respond(true, await manager.getById({ agentId, sessionId, limit }));
 			}
 			catch (err) {
 				respondError(respond, err);
@@ -691,6 +751,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 +817,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.4",
+  "version": "0.22.1",
   "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/auto-upgrade/updater.js

@@ -131,6 +131,14 @@ export async function writeUpgradeLock(pid) {
  * `upgrade.ledger-read-failed` / `upgrade.ledger-parse-failed`），避免运维只
  * 看到 start() 那条 "Skipping: not an npm-installed plugin" 时误判方向。
  *
+ * 注：内部 `readFileSync` 为同步 IO，**有意保留**——只在升级周期决策时读一次
+ * 账本（整个进程生命周期通常一锤子）。改 async 必须沿 `shouldSkipAutoUpgrade`
+ * 等调用链向上传播，收益不抵成本。
+ *
+ * 另：OpenClaw plugin SDK 当前未暴露查询 installRecords 的 API，只能直接读
+ * `<state-dir>/plugins/installs.json`（与上游 `manifest-metadata-scan` 等
+ * 内部模块同源做法）。如果上游后续开放官方接口，可切换并删除直读分支。
+ *
  * @param {string} pluginId
  * @returns {object|null}
  */

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,25 @@ function emptyStore() {
 }
 
 /**
- * Chat History 管理器：追踪 chat（sessionKey）因 reset 产生的孤儿 session。
+ * 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 +95,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`);
 		}
@@ -112,11 +135,32 @@ export class ChatHistoryManager {
 	}
 
 	/**
-	 * 记录一个被抛弃的孤儿 session
-	 * @param {{ agentId: string, sessionKey: string, sessionId: string }} params
+	 * 记录一次 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 recordArchived({ agentId, sessionKey, sessionId }) {
-		if (!sessionKey || !sessionId) return;
+	async recordSessionTransition({ agentId, sessionKey, currentSessionId, archivedSessionId }) {
+		if (!sessionKey || !currentSessionId) return;
+		// 规范化：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 +168,57 @@ 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 列表。
+	 * 获取指定 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 +240,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 };