chatccc 0.2.49 → 0.2.51

package/src/index.ts

@@ -30,7 +30,7 @@ import { resolve, dirname } from "node:path";
 import { WSClient, EventDispatcher } from "@larksuiteoapi/node-sdk";
 import WebSocket from "ws";
 
-import { appendStartupTrace, attachRelayWebSocket, ensureSingleInstance, freeRelayListenPort, installCrashLogging } from "./shared.ts";
+import { appendStartupTrace, attachRelayWebSocket, ensureSingleInstance, freeRelayListenPort, installCrashLogging, waitForPortFree } from "./shared.ts";
 import { createUiRouter, setExtraApiHandler, setReloadConfigHook, startSetupMode } from "./web-ui.ts";
 import { makeTraceId, logTrace } from "./trace.ts";
 import {
@@ -97,14 +97,17 @@ import {
   initClaudeSession,
   lastMsgTimestamps,
   processedMessages,
+  rebuildBindingsFromRegistry,
   resetState,
   resumeAndPrompt,
   sessionInfoMap,
+  switchChatBinding,
   recordSessionRegistry,
   getAdapterForTool,
   stopSession,
   loadSessionRegistryForBinding,
   removeSessionRegistryRecord,
+  saveSessionTool,
 } from "./session.ts";
 import {
   bindChatToSession,
@@ -493,6 +496,7 @@ async function handleCommand(text: string, chatId: string, openId: string, msgTi
         startTime: Date.now(),
         running: false,
       });
+      await saveSessionTool(sessionId, tool, initialName);
       await sendCardReply(
         freshToken, chatId, `${toolLabel} Session Ready`,
         `这是你的 **${toolLabel}** 私聊会话。\n\n` +
@@ -542,6 +546,7 @@ async function handleCommand(text: string, chatId: string, openId: string, msgTi
       startTime: Date.now(),
       running: false,
     });
+    await saveSessionTool(sessionId, tool, initialName);
 
     const adapter = getAdapterForTool(tool);
     await sendCardReply(
@@ -628,6 +633,7 @@ async function handleCommand(text: string, chatId: string, openId: string, msgTi
           await updateChatInfo(freshToken, chatId, newName, description!);
           console.log(`[${ts()}] [RENAME] First message → group renamed to "${newName}"`);
           await recordSessionRegistry({ chatId, sessionId, tool: descriptionTool, chatName: newName }).catch(() => {});
+          await saveSessionTool(sessionId, descriptionTool, newName).catch(() => {});
         } catch (err) {
           console.error(`[${ts()}] [RENAME] Failed: ${(err as Error).message}`);
         }
@@ -713,11 +719,10 @@ async function handleCommand(text: string, chatId: string, openId: string, msgTi
           cwd = await getDefaultCwd(chatId);
         }
 
-        // 不 abort 旧 session，只解绑当前 chat
-        // 旧 session 如果正在跑，display loop 继续服务其他群
-        unbindChatFromSession(sessionId, chatId);
-        displayCards.delete(chatId);
-
+        // 第一步:创建新 session(此时尚未碰任何内存绑定,失败可直接返回,
+        // 旧 session 状态完全保留)。
+        // 注意不 abort 旧 session：旧 session 若仍在跑,display loop 会继续
+        // 把卡片推到原群直到 prompt 自然结束(或被 /stop)。
         let newSessionId: string;
         try {
           const init = await initClaudeSession(descriptionTool, cwd);
@@ -728,36 +733,46 @@ async function handleCommand(text: string, chatId: string, openId: string, msgTi
           return;
         }
 
-        // 绑定新 session
-        bindChatToSession(newSessionId, chatId);
-        recordLastActiveChat(newSessionId, chatId);
-
+        // 第二步:事务式切换 chat 绑定 —— 把 chat 从 oldSessionId 改嫁到
+        // newSessionId。switchChatBinding 内部保证:
+        //   - 群聊先调 updateChatInfo 改群描述,失败则内存绑定完全不动
+        //   - 私聊跳过 updateChatInfo(私聊 chatId 调群 API 必然失败)
+        //   - API 成功后统一切换内存:unbind 旧 / clear displayCards / bind 新 /
+        //     recordLastActiveChat / sessionInfoMap.set + 持久化 registry/sessions
+        // 详见 session.ts::switchChatBinding 注释。
         const descPrefix = sessionPrefixForTool(descriptionTool);
         const newName = sessionChatName("新会话", cwd);
-        await updateChatInfo(freshToken, chatId, newName, `${descPrefix} ${newSessionId}`);
-        console.log(`[${ts()}] [NEWH] Group updated: name="${newName}" desc="${descPrefix} ${newSessionId}"`);
-
-        sessionInfoMap.set(chatId, {
-          sessionId: newSessionId,
-          turnCount: 0,
-          lastContextTokens: 0,
-          startTime: Date.now(),
-          tool: descriptionTool,
-        });
-        await recordSessionRegistry({
+        const switchResult = await switchChatBinding({
           chatId,
-          sessionId: newSessionId,
+          chatType,
+          oldSessionId: sessionId,
+          newSessionId,
           tool: descriptionTool,
           chatName: newName,
-          turnCount: 0,
-          lastContextTokens: 0,
-          startTime: Date.now(),
-          running: false,
+          newDescription: `${descPrefix} ${newSessionId}`,
+          updateChatInfoFn: (cid, name, desc) => updateChatInfo(freshToken, cid, name, desc),
         });
+        if (!switchResult.ok) {
+          // 飞书 API 失败:内存仍指向旧 session,新 session 已创建但无人使用,
+          // 留在 sessions.json(loadSessionTools)成为 orphan,可由 /sessions
+          // 列表展示供人工清理或下次 /newh 覆盖。代价小于让群 description
+          // 与内存绑定不一致。
+          logTrace(tid, "DONE", { outcome: "newh_update_chat_fail", error: switchResult.error?.message });
+          await sendCardReply(
+            freshToken, chatId, "Error",
+            `更新群描述失败,会话未切换(新 session 已创建但未启用):\n${switchResult.error?.message}`,
+            "red"
+          );
+          return;
+        }
+        if (chatType !== "p2p") {
+          console.log(`[${ts()}] [NEWH] Group updated: name="${newName}" desc="${descPrefix} ${newSessionId}"`);
+        }
 
         setChatAvatar(freshToken, chatId, descriptionTool, "new").catch(() => {});
 
-        // 如果新 session 有活跃 prompt，启动 display loop 让本群也能看到
+        // 如果新 session 有活跃 prompt,启动 display loop 让本群也能看到。
+        // /newh 后通常是空 session,这里几乎走不到,但留作防御。
         if (isSessionRunning(newSessionId)) {
           const { ensureDisplayLoop } = await import("./session.ts");
           ensureDisplayLoop(newSessionId);
@@ -829,12 +844,8 @@ async function handleCommand(text: string, chatId: string, openId: string, msgTi
         }
         const target = ordered[index];
 
-        // 不 abort 当前 chat 的旧 session，只解绑再重新绑定
-        if (sessionId) {
-          unbindChatFromSession(sessionId, chatId);
-          displayCards.delete(chatId);
-        }
-
+        // 第一步:解析目标 session 的 cwd(adapter.getSessionInfo 失败则 fallback,
+        // 这一步不动任何内存绑定,失败也不脏)。
         const targetAdapter = getAdapterForTool(target.tool);
         let cwd2: string;
         try {
@@ -844,33 +855,43 @@ async function handleCommand(text: string, chatId: string, openId: string, msgTi
           cwd2 = await getDefaultCwd(chatId);
         }
 
-        // 绑定到新 session
-        bindChatToSession(target.sessionId, chatId);
-        recordLastActiveChat(target.sessionId, chatId);
-
+        // 第二步:事务式切换 chat 绑定到 target.sessionId。
+        // switchChatBinding 内部行为同 /newh,详见 session.ts::switchChatBinding。
+        // 注意:这里把 turnCount 沿用 target.turnCount(从 registry 读到的目标 chat
+        // 历史轮数),而不是从 0 开始,这样 /status 显示的轮数延续历史。
         const descPrefix2 = sessionPrefixForTool(target.tool);
         const newName2 = target.chatName || sessionChatName("新会话", cwd2);
-        await updateChatInfo(freshToken, chatId, newName2, `${descPrefix2} ${target.sessionId}`);
-        console.log(`[${ts()}] [SESSION] Switched to session ${target.sessionId} (#${index + 1}), name="${newName2}"`);
-
-        sessionInfoMap.set(chatId, {
-          sessionId: target.sessionId,
-          turnCount: target.turnCount,
-          lastContextTokens: 0,
-          startTime: Date.now(),
-          tool: target.tool,
-        });
-        await recordSessionRegistry({
+        const switchResult = await switchChatBinding({
           chatId,
-          sessionId: target.sessionId,
+          chatType,
+          oldSessionId: sessionId,
+          newSessionId: target.sessionId,
           tool: target.tool,
           chatName: newName2,
-          running: false,
+          newDescription: `${descPrefix2} ${target.sessionId}`,
+          initialTurnCount: target.turnCount,
+          initialContextTokens: 0,
+          updateChatInfoFn: (cid, name, desc) => updateChatInfo(freshToken, cid, name, desc),
         });
+        if (!switchResult.ok) {
+          logTrace(tid, "DONE", { outcome: "session_update_chat_fail", error: switchResult.error?.message });
+          await sendCardReply(
+            freshToken, chatId, "Error",
+            `更新群描述失败,会话未切换:\n${switchResult.error?.message}`,
+            "red"
+          );
+          return;
+        }
+        if (chatType !== "p2p") {
+          console.log(`[${ts()}] [SESSION] Switched to session ${target.sessionId} (#${index + 1}), name="${newName2}"`);
+        }
 
         setChatAvatar(freshToken, chatId, target.tool, "new").catch(() => {});
 
-        // 如果新 session 有活跃 prompt，加上 display loop
+        // 如果新 session 有活跃 prompt,加上 display loop。注意:此时
+        // recordLastActiveChat 已经把 lastActive 改成当前 chat,会"抢走"
+        // 原有群的 display 推送(见 review 中 corner case 5)。这是已知
+        // 设计权衡:用户主动切换就是想"接管"该 session 的显示。
         if (isSessionRunning(target.sessionId)) {
           const { ensureDisplayLoop } = await import("./session.ts");
           ensureDisplayLoop(target.sessionId);
@@ -1225,25 +1246,34 @@ async function startBotServiceCore(): Promise<void> {
       console.error(`[WS] Local relay error: ${err.message}`);
     });
   } else {
+    // 进程首次启动:此时所有 Map 都是空的,resetState 主要是打个 LOG 标识"开始
+    // 干净状态"。修正残留的 running stream-state 并重建 session→chat 映射。
     resetState();
-    // 启动时修正残留的 running 状态并重建 session→chat 映射
     fixStaleStreamStates().then(async () => {
       const registry = await loadSessionRegistryForBinding();
       rebuildSessionChatsFromRegistry(registry);
     }).catch((err) => console.error(`[${ts()}] Init bindings failed: ${(err as Error).message}`));
 
+    // ⚠️ 关键设计:onReady / onReconnected 只重建只读映射,**绝不**清空运行时
+    // 状态(activePrompts、displayLoops、sessionInfoMap、processedMessages)。
+    // SDK 重连只是底层 WebSocket 抖动,业务层不受影响:
+    //   - 后台 generator 仍在跑、stream-state 仍在被写
+    //   - display loop 仍在向群推送
+    //   - 已处理消息的去重 set 必须保留,避免 SDK 重推老消息时 prompt 跑两遍
+    // 历史 bug:此处曾误调 resetState() 导致重连即让所有后台任务变孤儿,
+    // 同一 session 还可能双开 prompt(详见 session.ts::resetState 注释)。
     const wsClient = new WSClient({
       appId: APP_ID,
       appSecret: APP_SECRET,
       onReady: async () => {
-        resetState();
-        const registry = await loadSessionRegistryForBinding();
-        rebuildSessionChatsFromRegistry(registry);
+        await rebuildBindingsFromRegistry().catch((err) =>
+          console.error(`[${ts()}] [SDK READY] rebuild bindings failed: ${(err as Error).message}`)
+        );
       },
       onReconnected: async () => {
-        resetState();
-        const registry = await loadSessionRegistryForBinding();
-        rebuildSessionChatsFromRegistry(registry);
+        await rebuildBindingsFromRegistry().catch((err) =>
+          console.error(`[${ts()}] [SDK RECONNECT] rebuild bindings failed: ${(err as Error).message}`)
+        );
       },
     });
 
@@ -1405,22 +1435,14 @@ async function main(): Promise<void> {
   // 凭证齐全：自己起 HTTP server（同时挂 UI router），再调 startBotService
   // 把 WS 中继和飞书 SDK 挂上去。
   appendStartupTrace("main: before freeRelayListenPort", { CHATCCC_PORT });
-  freeRelayListenPort(CHATCCC_PORT);
-  appendStartupTrace("main: after freeRelayListenPort", { CHATCCC_PORT });
+  const killed = freeRelayListenPort(CHATCCC_PORT);
+  appendStartupTrace("main: after freeRelayListenPort", { CHATCCC_PORT, killed });
+  if (killed > 0) {
+    await waitForPortFree(CHATCCC_PORT);
+    appendStartupTrace("main: port free confirmed", { CHATCCC_PORT });
+  }
   const httpServer = createServer(createUiRouter());
-  await new Promise<void>((resolveListen, rejectListen) => {
-    const onError = (err: NodeJS.ErrnoException): void => {
-      httpServer.removeListener("listening", onListening);
-      rejectListen(err);
-    };
-    const onListening = (): void => {
-      httpServer.removeListener("error", onError);
-      resolveListen();
-    };
-    httpServer.once("error", onError);
-    httpServer.once("listening", onListening);
-    httpServer.listen(CHATCCC_PORT, "127.0.0.1");
-  }).catch((err: NodeJS.ErrnoException) => {
+  await listenWithRetry(httpServer, CHATCCC_PORT, "127.0.0.1").catch((err: NodeJS.ErrnoException) => {
     console.error(`\n[启动] 本地中继 WebSocket 监听失败：端口 ${CHATCCC_PORT}（${err.code ?? "?"} — ${err.message}）`);
     console.error(
       "  处理建议: 关闭占用该端口的其它程序，或在 config.json 的 port 字段里改成其它未占用端口（如 18081）。"
@@ -1439,6 +1461,36 @@ async function main(): Promise<void> {
   installShutdownHandlers(httpServer);
 }
 
+/**
+ * 带重试的 server.listen，Windows 端口释放有延迟时自动重试。
+ */
+async function listenWithRetry(
+  server: ReturnType<typeof createServer>,
+  port: number,
+  host: string,
+  maxRetries = 3,
+): Promise<void> {
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      await new Promise<void>((resolve, reject) => {
+        server.once("error", reject);
+        server.once("listening", resolve);
+        server.listen(port, host);
+      });
+      return;
+    } catch (err: unknown) {
+      const e = err as NodeJS.ErrnoException;
+      server.removeAllListeners("listening");
+      server.removeAllListeners("error");
+      if (e.code === "EADDRINUSE" && i < maxRetries - 1) {
+        await new Promise((r) => setTimeout(r, 500 * (i + 1)));
+        continue;
+      }
+      throw err;
+    }
+  }
+}
+
 /**
  * 注册 SIGINT / SIGTERM 清理：把 relay/setup 共用的 httpServer 关掉再退出。
  *

package/src/session-chat-binding.ts

@@ -31,6 +31,13 @@ export function unbindChatFromSession(sessionId: string, chatId: string): void {
     chats.delete(chatId);
     if (chats.size === 0) sessionChatsMap.delete(sessionId);
   }
+  // 双保险：lastActiveChatMap 是 sessionId → 最后活跃 chatId 的快照，
+  // 若被解绑的 chatId 正好是该 session 的 lastActive（典型场景：/newh
+  // 把当前群从旧 session 改嫁到新 session），不清理会让旧 session 的
+  // display loop 继续向已离开的群推送卡片。
+  if (lastActiveChatMap.get(sessionId)?.chatId === chatId) {
+    lastActiveChatMap.delete(sessionId);
+  }
 }
 
 export function getChatsForSession(sessionId: string): string[] {
@@ -75,6 +82,22 @@ export function getLastActiveChat(sessionId: string): string | undefined {
   return lastActiveChatMap.get(sessionId)?.chatId;
 }
 
+/**
+ * display loop 决定推送目标 chat 的纯函数：
+ * 仅当 lastActiveChat 仍然绑定到该 session 时才返回，否则返回 undefined。
+ *
+ * 修复 bug：用户 `/newh` 把当前群从旧 session 改嫁到新 session 后，旧
+ * session 的 lastActiveChatMap 残留旧 chatId 快照，display loop 会继续
+ * 在该群创建/更新卡片。这里通过交叉验证 sessionChatsMap 把这种悬挂记录
+ * 排除掉——loop 拿到 undefined 就走"无活跃群"分支自然停推。
+ */
+export function pickDisplayChat(sessionId: string): string | undefined {
+  const candidate = lastActiveChatMap.get(sessionId)?.chatId;
+  if (!candidate) return undefined;
+  const chats = sessionChatsMap.get(sessionId);
+  return chats?.has(candidate) ? candidate : undefined;
+}
+
 // ---------------------------------------------------------------------------
 // displayCards: chatId → 展示卡片状态（display loop 用）
 // ---------------------------------------------------------------------------

package/src/session.ts

@@ -45,6 +45,7 @@ import {
   rebuildSessionChatsFromRegistry,
   recordLastActiveChat,
   getLastActiveChat,
+  pickDisplayChat,
 } from "./session-chat-binding.ts";
 
 // ---------------------------------------------------------------------------
@@ -84,6 +85,29 @@ export const sessionInfoMap = new Map<string, {
   tool: string;
 }>();
 
+/**
+ * 清空所有进程内运行时状态。
+ *
+ * ⚠️ 红线：**绝对不要**在飞书 SDK 的 onReady / onReconnected 回调里调用本函数。
+ * SDK 的 WebSocket 重连只是底层连接抖动，业务层（活跃 prompt、display loop、
+ * stream-state 文件、轮数计数）完全不受影响。在重连里调 resetState 会：
+ *   1) `activePrompts.clear()` 只是删 Map，**不会** abort 后台 generator。
+ *      generator 继续跑、继续写 stream-state.json，但 display loop 已被
+ *      stop，用户群里再也看不到任何更新；最终回复永远不发到群。
+ *   2) 该 sessionId 在内存里"看似空闲"，下一条用户消息进来会**第二次进入**
+ *      `runAgentSession`，同一个 cursor/claude session 同时跑两条 prompt，
+ *      输出互相串扰、token 计费翻倍。
+ *   3) `processedMessages` / `lastMsgTimestamps` 被清，SDK 重连后若服务端
+ *      重推已 ack 的消息，去重失效会让同一 prompt 被处理两次。
+ *   4) `sessionInfoMap` 清空后，群再发消息时 nextTurnCount 从 1 重新计数。
+ *
+ * 合法调用点：
+ *   - 单元测试 setup（清测试间状态）
+ *   - 进程首次启动（此时 Map 都是空的，调用纯粹是为了打 LOG）
+ *
+ * SDK 重连场景请改用 `rebuildBindingsFromRegistry()`，它只重建 sessionId →
+ * chatId 映射，不动任何运行时状态。
+ */
 export function resetState(): void {
   for (const entry of chatSessionMap.values()) {
     if (entry.spinnerTimer) clearInterval(entry.spinnerTimer);
@@ -93,7 +117,6 @@ export function resetState(): void {
   sessionInfoMap.clear();
   processedMessages.clear();
   lastMsgTimestamps.clear();
-  // 清理新的全局状态
   activePrompts.clear();
   displayCards.clear();
   for (const stop of displayLoops.values()) stop();
@@ -101,6 +124,9 @@ export function resetState(): void {
   console.log(`[${ts()}] [RESET] State cleared (dedup + active sessions + bindings)`);
 }
 
+// 注:`rebuildBindingsFromRegistry` 定义在下方与 loadSessionRegistry 同区域,
+// 是 onReady/onReconnected 取代 resetState 的正确入口。
+
 // ---------------------------------------------------------------------------
 // Adapter: 按 tool 创建并缓存
 // ---------------------------------------------------------------------------
@@ -136,11 +162,14 @@ export function getAdapterForTool(tool: string): ToolAdapter {
 interface SessionToolRecord {
   tool: string;
   createdAt: number;
+  chatName?: string;
 }
 
+let sessionToolsFile = SESSIONS_FILE;
+
 async function loadSessionTools(): Promise<Record<string, SessionToolRecord>> {
   try {
-    const raw = await readFile(SESSIONS_FILE, "utf-8");
+    const raw = await readFile(sessionToolsFile, "utf-8");
     return JSON.parse(raw);
   } catch {
     return {};
@@ -149,17 +178,23 @@ async function loadSessionTools(): Promise<Record<string, SessionToolRecord>> {
 
 async function saveSessionTools(data: Record<string, SessionToolRecord>): Promise<void> {
   try {
-    await mkdir(dirname(SESSIONS_FILE), { recursive: true });
-    await writeFile(SESSIONS_FILE, JSON.stringify(data, null, 2), "utf-8");
+    await mkdir(dirname(sessionToolsFile), { recursive: true });
+    await writeFile(sessionToolsFile, JSON.stringify(data, null, 2), "utf-8");
   } catch (err) {
     console.error(`[${ts()}] Failed to save sessions.json: ${(err as Error).message}`);
     fileLog.flush();
   }
 }
 
-export async function saveSessionTool(sessionId: string, tool: string): Promise<void> {
+export async function saveSessionTool(sessionId: string, tool: string, chatName?: string): Promise<void> {
   const data = await loadSessionTools();
-  data[sessionId] = { tool, createdAt: Date.now() };
+  const existing = data[sessionId];
+  const mergedChatName = chatName ?? existing?.chatName;
+  data[sessionId] = {
+    tool,
+    createdAt: existing?.createdAt ?? Date.now(),
+    ...(mergedChatName ? { chatName: mergedChatName } : {}),
+  };
   await saveSessionTools(data);
 }
 
@@ -169,6 +204,14 @@ export async function getSessionTool(sessionId: string): Promise<string | null>
   return record?.tool ?? null;
 }
 
+export function _setSessionToolsFileForTest(filePath: string): void {
+  sessionToolsFile = filePath;
+}
+
+export function _resetSessionToolsFileForTest(): void {
+  sessionToolsFile = SESSIONS_FILE;
+}
+
 // ---------------------------------------------------------------------------
 // Conversation session registry for /sessions
 // ---------------------------------------------------------------------------
@@ -217,6 +260,26 @@ export async function loadSessionRegistryForBinding(): Promise<SessionRegistryDa
   return loadSessionRegistry();
 }
 
+/**
+ * 从持久化的 registry 重建 sessionId → chatId 映射。
+ *
+ * 设计契约（替代之前 onReady/onReconnected 误用的 resetState）：
+ *   - **不动** activePrompts：后台 prompt 在 SDK 重连后必须继续被识别为活跃,
+ *     否则下条用户消息会绕过 isSessionRunning 检查再开一条 prompt,
+ *     导致同一 sessionId 双开 generator
+ *   - **不动** sessionInfoMap：内存里的轮数/contextTokens 比 registry 更新
+ *   - **不动** displayCards / displayLoops：正在跑的 prompt 还需要它们继续推卡片
+ *   - **不动** processedMessages / lastMsgTimestamps：SDK 重连若重推已 ack 消息,
+ *     去重 set 还在才能避免同一 prompt 跑两遍
+ *
+ * 唯一被重建的是 sessionChatsMap（通过调用 rebuildSessionChatsFromRegistry）——
+ * 该 Map 是从 registry 派生的纯只读映射,重建是幂等且廉价的。
+ */
+export async function rebuildBindingsFromRegistry(): Promise<void> {
+  const registry = await loadSessionRegistry();
+  rebuildSessionChatsFromRegistry(registry);
+}
+
 async function saveSessionRegistry(data: SessionRegistryData): Promise<void> {
   try {
     await mkdir(dirname(sessionRegistryFile), { recursive: true });
@@ -361,6 +424,118 @@ export function accumulateBlockContent(
   }
 }
 
+// ---------------------------------------------------------------------------
+// switchChatBinding — /newh、/session N 共用的事务式"切换 chat 绑定"
+// ---------------------------------------------------------------------------
+//
+// 设计契约（解决三类历史 bug）：
+//
+//   1. 私聊不能调 updateChatInfo（飞书 API 在 p2p chatId 上会返回非 0 → throw）。
+//      之前的实现没判断 chatType,私聊 /newh、/session N 走到 updateChatInfo
+//      就直接抛错,留下"内存已切换、registry 没更新"的脏状态。
+//
+//   2. updateChatInfo 群聊也可能因为网络/频控失败。之前的代码顺序是
+//        先 unbind 旧 → bind 新 → 再调 updateChatInfo
+//      API 失败后内存绑定已经切走,但群 description 还是旧 sessionId。
+//      下次用户在群里发消息时,extractSessionInfo 拿到旧 sessionId,而内存绑定
+//      指向新 sessionId,路由完全错乱（参考 /newh 的 corner case 7）。
+//
+//   3. 改成"先 API 后内存"的顺序后,API 失败就完全不切换内存,下次消息按
+//      旧 description 正常路由到旧 session,新创建的 session 留在 sessions.json
+//      里成为可清理的 orphan。
+//
+// 调用方约定：
+//   - newSessionId 必须是已经 createSession 完成的真实 session（本函数不创建）
+//   - oldSessionId 为 null 表示当前 chat 没有任何旧绑定（比如私聊首次绑）
+//   - 私聊跳过 updateChatInfo,直接做内存切换 + registry 持久化
+//   - API 失败时：
+//       * 不动内存绑定 / sessionInfoMap / displayCards
+//       * 返回 { ok: false, error }
+//       * 调用方负责把错误反馈给用户
+// ---------------------------------------------------------------------------
+
+export interface SwitchChatBindingArgs {
+  chatId: string;
+  chatType: string;
+  oldSessionId: string | null;
+  newSessionId: string;
+  tool: string;
+  /** 群名（私聊忽略） */
+  chatName: string;
+  /** 群描述（私聊忽略），通常为 `${sessionPrefixForTool(tool)} ${newSessionId}` */
+  newDescription: string;
+  /** 切换后 sessionInfoMap 的初始 turnCount/lastContextTokens（如沿用历史） */
+  initialTurnCount?: number;
+  initialContextTokens?: number;
+  /** 飞书 updateChatInfo 实现，依赖注入便于测试 mock */
+  updateChatInfoFn: (chatId: string, name: string, description: string) => Promise<void>;
+}
+
+export interface SwitchChatBindingResult {
+  ok: boolean;
+  error?: Error;
+}
+
+export async function switchChatBinding(args: SwitchChatBindingArgs): Promise<SwitchChatBindingResult> {
+  const {
+    chatId,
+    chatType,
+    oldSessionId,
+    newSessionId,
+    tool,
+    chatName,
+    newDescription,
+    initialTurnCount = 0,
+    initialContextTokens = 0,
+    updateChatInfoFn,
+  } = args;
+
+  // Step 1: 群聊场景先调用飞书 API（不可逆操作放最前）。
+  // 私聊跳过——p2p chatId 调 updateChatInfo 必然失败。
+  if (chatType !== "p2p") {
+    try {
+      await updateChatInfoFn(chatId, chatName, newDescription);
+    } catch (err) {
+      // API 失败：完全不动内存,调用方负责回报用户。
+      return { ok: false, error: err as Error };
+    }
+  }
+
+  // Step 2: API 成功（或私聊跳过）后,原子地切换内存绑定。
+  // 这一段全是同步 Map 操作,不会失败。
+  if (oldSessionId) {
+    unbindChatFromSession(oldSessionId, chatId);
+    displayCards.delete(chatId);
+  }
+  bindChatToSession(newSessionId, chatId);
+  recordLastActiveChat(newSessionId, chatId);
+
+  const now = Date.now();
+  sessionInfoMap.set(chatId, {
+    sessionId: newSessionId,
+    turnCount: initialTurnCount,
+    lastContextTokens: initialContextTokens,
+    startTime: now,
+    tool,
+  });
+
+  // Step 3: 持久化（registry + sessions.json）。
+  // 这两步即使失败也不影响内存正确性,下次 prompt 会再写一次。
+  await recordSessionRegistry({
+    chatId,
+    sessionId: newSessionId,
+    tool,
+    chatName,
+    turnCount: initialTurnCount,
+    lastContextTokens: initialContextTokens,
+    startTime: now,
+    running: false,
+  });
+  await saveSessionTool(newSessionId, tool, chatName);
+
+  return { ok: true };
+}
+
 // ---------------------------------------------------------------------------
 // AI tool session management
 // ---------------------------------------------------------------------------
@@ -658,7 +833,9 @@ export function ensureDisplayLoop(sessionId: string): void {
       const state = await readStreamState(sessionId);
       if (!state) return;
 
-      const chatId = getLastActiveChat(sessionId);
+      // pickDisplayChat 在 lastActiveChat 已与本 session 解绑时返回 undefined，
+      // 避免 /newh 等改嫁场景下旧 session 仍向已离开群推卡片。
+      const chatId = pickDisplayChat(sessionId);
       if (!chatId) {
         // 无活跃群，若 session 已结束则停止 loop
         if (state.status !== "running") {
@@ -901,9 +1078,31 @@ export interface SessionsListEntry {
 
 export async function getAllSessionsStatus(): Promise<SessionsListEntry[]> {
   const registry = await loadSessionRegistry();
-  const entries = Object.values(registry)
+  const registryEntries = Object.values(registry)
     .filter((record) => record.chatId && record.sessionId && record.tool)
-    .sort((a, b) => b.updatedAt - a.updatedAt)
+    .map((record) => ({ ...record, sortTime: record.updatedAt }));
+  const registeredSessionIds = new Set(registryEntries.map((record) => record.sessionId));
+  const sessionTools = await loadSessionTools();
+  const orphanEntries = Object.entries(sessionTools)
+    .filter(([sessionId, record]) => sessionId && record?.tool && !registeredSessionIds.has(sessionId))
+    .map(([sessionId, record]) => {
+      const createdAt = Number.isFinite(record.createdAt) ? record.createdAt : 0;
+      const active = activePrompts.get(sessionId);
+      return {
+        chatId: "",
+        sessionId,
+        tool: record.tool,
+        chatName: record.chatName ?? "",
+        turnCount: 0,
+        lastContextTokens: 0,
+        startTime: active?.startTime ?? createdAt,
+        updatedAt: createdAt,
+        running: false,
+        sortTime: active?.startTime ?? createdAt,
+      };
+    });
+  const entries = [...registryEntries, ...orphanEntries]
+    .sort((a, b) => b.sortTime - a.sortTime)
     .slice(0, 20);
   // 并行解析每个 session 的 model/effort（cursor 涉及异步 store IO）
   return Promise.all(