chatccc 0.2.210 → 0.2.212

package/README.md

@@ -332,9 +332,11 @@ Codex 的默认模型和推理强度可继续由 `~/.codex/config.toml` 管理
 
 **飞书：** 找到机器人后直接发送普通消息，即可在当前私聊中创建并持续使用专属 AI 会话；私聊工作目录固定为运行 ChatCCC 的系统账号用户目录。默认 Agent 发生变化后，下一条私聊普通消息会触发切换并创建新的空会话；若旧 Agent 正在生成，该消息会先排队，待当前回复完成后再切换。命令不会触发自动切换。需要独立任务时，发送 `/new`、`/new claude`、`/new cursor` 或 `/new codex`，机器人会另外创建会话群。
 
-**微信：** 扫码登录后，在机器人私聊里发送 `/new` 或指定 Agent 的 `/new ...` 命令即可开始。功能与飞书基本一致，但展示为纯文本。
-
-## 可用指令
+**微信：** 扫码登录后，在机器人私聊里发送 `/new` 或指定 Agent 的 `/new ...` 命令即可开始。功能与飞书基本一致，但展示为纯文本。
+
+**会话停滞保护：** 当 Agent 连续 3 分钟处于“正在生成回复”且回复字符数没有变化、同时尚未报告权威终态时，ChatCCC 会结束旧 CLI，并优先补发一次“完成了吗？如果没完成继续”；恢复轮再次发生相同停滞时不再递归续跑。Codex 只有 `turn.completed` 才算权威终态，阶段性的 `agent_message` 不算；任一 Agent 报告权威终态后若输出流仍超过 10 秒未关闭，ChatCCC 会强制清理该 CLI 并按正常完成收尾，不会重复询问 Agent。
+
+## 可用指令
 
 | 指令 | 作用 |
 | --- | --- |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chatccc",
-  "version": "0.2.210",
+  "version": "0.2.212",
   "description": "Feishu bot bridge for Claude Code",
   "license": "Apache-2.0",
   "type": "module",

package/src/__tests__/ccc-adapter.test.ts

@@ -73,6 +73,7 @@ describe("createCccAdapter", () => {
     expect(messages).toEqual([
       { type: "assistant", blocks: [{ type: "text", text: "hello" }] },
       { type: "assistant", blocks: [{ type: "text", text: " world" }] },
+      { type: "assistant", blocks: [], isFinalResponse: true },
     ]);
     expect(streamTextMock).toHaveBeenCalledWith(expect.objectContaining({
       model: { modelId: "deepseek-v4-flash" },
@@ -109,6 +110,7 @@ describe("createCccAdapter", () => {
         type: "assistant",
         blocks: [{ type: "tool_result", tool_use_id: "call-1", content: { content: "hello" }, is_error: false }],
       },
+      { type: "assistant", blocks: [], isFinalResponse: true },
     ]);
   });
 });

package/src/__tests__/claude-adapter.test.ts

@@ -52,6 +52,7 @@ describe("normalizeSdkMessage", () => {
     expect(result).not.toBeNull();
     expect(result!.type).toBe("assistant");
     expect(result!.blocks).toEqual([{ type: "text", text: "Hello world" }]);
+    expect(result!.isFinalResponse).toBeUndefined();
   });
 
   it("normalizes assistant message with thinking block", () => {
@@ -269,10 +270,17 @@ describe("normalizeSdkMessage", () => {
     expect(result!.blocks[0]).toEqual({ type: "text", text: "still here" });
   });
 
-  it("returns null for non-assistant/non-user/non-system messages", () => {
+  it("marks a successful result event as an authoritative final response", () => {
     expect(
       normalizeSdkMessage({ type: "result", subtype: "success" }),
-    ).toBeNull();
+    ).toEqual({
+      type: "assistant",
+      blocks: [],
+      isFinalResponse: true,
+    });
+  });
+
+  it("returns null for other non-assistant/non-user/non-system messages", () => {
     expect(
       normalizeSdkMessage({ type: "stream_event" }),
     ).toBeNull();

package/src/__tests__/codex-adapter.test.ts

@@ -56,15 +56,16 @@ function createInMemoryMetaStore(
 // ---------------------------------------------------------------------------
 
 describe("normalizeCodexMessage", () => {
-  it("normalizes agent_message into assistant text block", () => {
-    const result = normalizeCodexMessage({
-      type: "item.completed",
-      item: { id: "item_0", type: "agent_message", text: "hello" },
+  it("normalizes agent_message into assistant text block", () => {
+    const result = normalizeCodexMessage({
+      type: "item.completed",
+      item: { id: "item_0", type: "agent_message", text: "hello" },
     });
-    expect(result).not.toBeNull();
-    expect(result!.type).toBe("assistant");
-    expect(result!.blocks).toEqual([{ type: "text", text: "hello" }]);
-  });
+    expect(result).not.toBeNull();
+    expect(result!.type).toBe("assistant");
+    expect(result!.blocks).toEqual([{ type: "text", text: "hello" }]);
+    expect(result!.isFinalResponse).toBeUndefined();
+  });
 
   it("normalizes command_execution start into tool_use block", () => {
     const result = normalizeCodexMessage({
@@ -142,13 +143,17 @@ describe("normalizeCodexMessage", () => {
     expect(normalizeCodexMessage({ type: "turn.started" })).toBeNull();
   });
 
-  it("returns null for turn.completed events", () => {
-    expect(
-      normalizeCodexMessage({
-        type: "turn.completed",
-        usage: { input_tokens: 100, output_tokens: 50 },
-      }),
-    ).toBeNull();
+  it("marks turn.completed as the authoritative final response", () => {
+    expect(
+      normalizeCodexMessage({
+        type: "turn.completed",
+        usage: { input_tokens: 100, output_tokens: 50 },
+      }),
+    ).toEqual({
+      type: "assistant",
+      blocks: [],
+      isFinalResponse: true,
+    });
   });
 
   it("returns null for unknown event types", () => {
@@ -224,7 +229,7 @@ describe("Codex stream fixtures", () => {
     expect(state.accumulatedContent).toContain("tool_test");
   });
 
-  it("with tool: 只映射 agent_message 和 command_execution，不映射元事件", () => {
+  it("with tool: 普通输出不标终态，只有 turn.completed 标记终态", () => {
     const lines = readFixture("codex_with_tool.jsonl");
     const messages: UnifiedStreamMessage[] = [];
     for (const raw of lines) {
@@ -234,12 +239,18 @@ describe("Codex stream fixtures", () => {
       if (normalized) messages.push(normalized);
     }
 
-    // 应有: tool_use + tool_result + text = 3 条消息
-    expect(messages.length).toBe(3);
-    expect(messages[0].blocks[0].type).toBe("tool_use");
-    expect(messages[1].blocks[0].type).toBe("tool_result");
-    expect(messages[2].blocks[0].type).toBe("text");
-  });
+    // 应有: tool_use + tool_result + text + turn.completed = 4 条消息
+    expect(messages.length).toBe(4);
+    expect(messages[0].blocks[0].type).toBe("tool_use");
+    expect(messages[1].blocks[0].type).toBe("tool_result");
+    expect(messages[2].blocks[0].type).toBe("text");
+    expect(messages[2].isFinalResponse).toBeUndefined();
+    expect(messages[3]).toEqual({
+      type: "assistant",
+      blocks: [],
+      isFinalResponse: true,
+    });
+  });
 });
 
 // ---------------------------------------------------------------------------

package/src/__tests__/codex-raw-stream-log.test.ts

@@ -136,10 +136,17 @@ describe("Codex raw stream logs", () => {
     expect(rawLogWriteLineMock).toHaveBeenNthCalledWith(2, lines[1]);
     expect(rawLogWriteLineMock).toHaveBeenNthCalledWith(3, lines[2]);
     expect(rawLogCloseMock).toHaveBeenCalledWith({ keep: false });
-    expect(events).toContainEqual({
-      type: "assistant",
-      blocks: [{ type: "text", text: "hello" }],
-    });
+    expect(events).toEqual([
+      {
+        type: "assistant",
+        blocks: [{ type: "text", text: "hello" }],
+      },
+      {
+        type: "assistant",
+        blocks: [],
+        isFinalResponse: true,
+      },
+    ]);
   });
 
   it("fails the turn and kills the process tree when bad JSON is followed by idle stdout", async () => {

package/src/__tests__/cursor-adapter.test.ts

@@ -445,9 +445,10 @@ describe("normalizeCursorMessage - 三类 assistant 事件区分", () => {
       type: "assistant",
       message: { role: "assistant", content: [{ type: "text", text: "你" }] },
       timestamp_ms: 1778411927583,
-    });
-    expect(result).not.toBeNull();
-    expect(result!.blocks).toEqual([{ type: "text", text: "你" }]);
+    });
+    expect(result).not.toBeNull();
+    expect(result!.blocks).toEqual([{ type: "text", text: "你" }]);
+    expect(result!.isFinalResponse).toBeUndefined();
   });
 
   it("Buffered flush（has timestamp_ms, has model_call_id）→ text_final（覆盖，避免与 delta 重复累加）", () => {
@@ -461,9 +462,10 @@ describe("normalizeCursorMessage - 三类 assistant 事件区分", () => {
       model_call_id: "mc-1",
     } as Parameters<typeof normalizeCursorMessage>[0]);
     expect(result).not.toBeNull();
-    expect(result!.blocks).toEqual([
-      { type: "text_final", text: "完整快照（与 delta 累计相同）" },
-    ]);
+    expect(result!.blocks).toEqual([
+      { type: "text_final", text: "完整快照（与 delta 累计相同）" },
+    ]);
+    expect(result!.isFinalResponse).toBeUndefined();
   });
 
   it("Final flush（no timestamp_ms）→ text_final（覆盖）", () => {
@@ -475,9 +477,10 @@ describe("normalizeCursorMessage - 三类 assistant 事件区分", () => {
       },
     });
     expect(result).not.toBeNull();
-    expect(result!.blocks).toEqual([
-      { type: "text_final", text: "你上一题问的是 1+2=?" },
-    ]);
+    expect(result!.blocks).toEqual([
+      { type: "text_final", text: "你上一题问的是 1+2=?" },
+    ]);
+    expect(result!.isFinalResponse).toBeUndefined();
   });
 });
 
@@ -490,10 +493,11 @@ describe("normalizeCursorMessage - result 消息（官方权威最终文本）",
     });
     expect(result).not.toBeNull();
     expect(result!.type).toBe("assistant");
-    expect(result!.blocks).toEqual([
-      { type: "text_final", text: "权威最终文本" },
-    ]);
-  });
+    expect(result!.blocks).toEqual([
+      { type: "text_final", text: "权威最终文本" },
+    ]);
+    expect(result!.isFinalResponse).toBe(true);
+  });
 
   it("result 消息没有 result 字段时返回 null（无可用文本）", () => {
     expect(

package/src/__tests__/orchestrator.test.ts

@@ -87,7 +87,12 @@ import {
   resetState,
   sessionInfoMap,
 } from "../session.ts";
-import { activePrompts, dequeueMessage, resetBindingState } from "../session-chat-binding.ts";
+import {
+  activePrompts,
+  dequeueMessage,
+  getChatsForSession,
+  resetBindingState,
+} from "../session-chat-binding.ts";
 import { ABD_APPEND_PROMPT } from "../shared-prefix.ts";
 import { config } from "../config.ts";
 
@@ -802,6 +807,7 @@ describe("handleCommand WeChat processing ack", () => {
     expect(platform.sendRawCard).toHaveBeenCalled();
     const card = JSON.parse(vi.mocked(platform.sendRawCard).mock.calls[0][1]);
     expect(JSON.stringify(card)).toContain("xhigh");
+    expect(getChatsForSession("sid-codex-effort")).toContain("codex-chat");
   });
 
   it("rejects /effort in Cursor sessions", async () => {

package/src/__tests__/session.test.ts

@@ -122,7 +122,11 @@ import {
   _resetResponseStallTimeoutForTest,
   _setResponseStallCheckIntervalForTest,
   _resetResponseStallCheckIntervalForTest,
+  _setFinalResponseCloseTimeoutForTest,
+  _resetFinalResponseCloseTimeoutForTest,
   setSessionEffortOverride,
+  RESPONSE_STALL_RECOVERY_PROMPT,
+  RESPONSE_STALL_RECOVERY_EXHAUSTED_NOTICE,
 } from "../session.ts";
 import {
   activePrompts,
@@ -369,6 +373,7 @@ describe("runAgentSession process monitor", () => {
     _resetProcessMonitorIntervalForTest();
     _resetResponseStallTimeoutForTest();
     _resetResponseStallCheckIntervalForTest();
+    _resetFinalResponseCloseTimeoutForTest();
     resetBindingState();
     vi.useRealTimers();
   });
@@ -670,7 +675,7 @@ describe("runAgentSession process monitor", () => {
 
 describe("runAgentSession response stall watchdog", () => {
   let tempDir = "";
-  const recoveryPrompt = "完成了吗？如果没完成继续";
+  const recoveryPrompt = RESPONSE_STALL_RECOVERY_PROMPT;
 
   beforeEach(async () => {
     vi.useFakeTimers();
@@ -690,6 +695,7 @@ describe("runAgentSession response stall watchdog", () => {
     _resetProcessAliveForTest();
     _resetResponseStallTimeoutForTest();
     _resetResponseStallCheckIntervalForTest();
+    _resetFinalResponseCloseTimeoutForTest();
     resetBindingState();
     vi.useRealTimers();
     if (tempDir) await rm(tempDir, { recursive: true, force: true });
@@ -768,6 +774,290 @@ describe("runAgentSession response stall watchdog", () => {
     });
   });
 
+  it("self-heals a missing trigger-chat binding and gives automatic recovery the normal card lifecycle", async () => {
+    vi.setSystemTime(0);
+    _setResponseStallTimeoutForTest(100);
+    _setResponseStallCheckIntervalForTest(10);
+    _setProcessAliveForTest(() => true);
+
+    const platform = mockPlatform("feishu");
+    setSessionPlatform(platform);
+
+    const receivedPrompts: string[] = [];
+    const adapter: ToolAdapter = {
+      displayName: "Any Agent",
+      sessionDescPrefix: "Agent Session:",
+      createSession: async () => ({ sessionId: "sid-binding-recovery" }),
+      getSessionInfo: async (sid) => ({ sessionId: sid, cwd: "F:\\repo" }),
+      closeSession: async () => {},
+      prompt: async function* (
+        _sid: string,
+        text: string,
+        _cwd: string,
+        signal?: AbortSignal,
+        options?: ToolPromptOptions,
+      ) {
+        receivedPrompts.push(text);
+        options?.onProcessStart?.({ pid: 5000 + receivedPrompts.length });
+        if (receivedPrompts.length === 1) {
+          yield { type: "assistant", blocks: [{ type: "text", text: "" }] };
+          await new Promise<void>((resolve) => {
+            if (signal?.aborted) {
+              resolve();
+              return;
+            }
+            signal?.addEventListener("abort", () => resolve(), { once: true });
+          });
+          return;
+        }
+        yield {
+          type: "assistant",
+          blocks: [{ type: "text", text: "recovery completed" }],
+          isFinalResponse: true,
+        };
+      },
+    };
+    _setAdapterForToolForTest("claude", adapter);
+
+    const firstRun = runAgentSession(
+      "sid-binding-recovery",
+      "first prompt",
+      platform,
+      "chat-binding-recovery",
+      0,
+      "claude",
+    );
+
+    await vi.waitFor(() => {
+      expect(activePrompts.get("sid-binding-recovery")?.responseProgress).toBeDefined();
+    });
+    const progress = activePrompts.get("sid-binding-recovery")!.responseProgress!;
+    await vi.advanceTimersByTimeAsync(progress.unchangedSince + 101 - Date.now());
+    await firstRun;
+    await vi.advanceTimersByTimeAsync(200);
+    await vi.waitFor(() => expect(receivedPrompts).toHaveLength(2));
+    await vi.waitFor(() => expect(isSessionRunning("sid-binding-recovery")).toBe(false));
+
+    expect(getChatsForSession("sid-binding-recovery")).toContain("chat-binding-recovery");
+    expect(platform.cardCreate).toHaveBeenCalledTimes(2);
+    expect(platform.cardSend).toHaveBeenCalledTimes(2);
+    expect(platform.sendText).toHaveBeenCalledWith(
+      "chat-binding-recovery",
+      expect.stringContaining(recoveryPrompt),
+    );
+
+    const registry = JSON.parse(
+      await readFile(join(tempDir, "session-registry.json"), "utf8"),
+    ) as Record<string, { running?: boolean }>;
+    expect(registry["chat-binding-recovery"]?.running).toBe(false);
+  });
+
+  it("treats an authoritative final response that races timeout cleanup as completed", async () => {
+    vi.setSystemTime(0);
+    _setResponseStallTimeoutForTest(100);
+    _setResponseStallCheckIntervalForTest(10);
+    _setProcessAliveForTest(() => true);
+
+    const platform = mockPlatform("feishu");
+    setSessionPlatform(platform);
+    bindChatToSession("sid-final-race", "chat-final-race");
+    recordLastActiveChat("sid-final-race", "chat-final-race");
+
+    const receivedPrompts: string[] = [];
+    const adapter: ToolAdapter = {
+      displayName: "Any Agent",
+      sessionDescPrefix: "Agent Session:",
+      createSession: async () => ({ sessionId: "sid-final-race" }),
+      getSessionInfo: async (sid) => ({ sessionId: sid, cwd: "F:\\repo" }),
+      closeSession: async () => {},
+      prompt: async function* (
+        _sid: string,
+        text: string,
+        _cwd: string,
+        signal?: AbortSignal,
+        options?: ToolPromptOptions,
+      ) {
+        receivedPrompts.push(text);
+        options?.onProcessStart?.({ pid: 5151 });
+        yield { type: "assistant", blocks: [{ type: "text", text: "" }] };
+        await new Promise<void>((resolve) => {
+          if (signal?.aborted) {
+            resolve();
+            return;
+          }
+          signal?.addEventListener("abort", () => resolve(), { once: true });
+        });
+        yield {
+          type: "assistant",
+          blocks: [{ type: "text", text: "completed at the timeout boundary" }],
+          isFinalResponse: true,
+        };
+      },
+    };
+    _setAdapterForToolForTest("claude", adapter);
+
+    const run = runAgentSession(
+      "sid-final-race",
+      "prompt",
+      platform,
+      "chat-final-race",
+      0,
+      "claude",
+    );
+    await vi.waitFor(() => {
+      expect(activePrompts.get("sid-final-race")?.responseProgress).toBeDefined();
+    });
+    const progress = activePrompts.get("sid-final-race")!.responseProgress!;
+    await vi.advanceTimersByTimeAsync(progress.unchangedSince + 101 - Date.now());
+    await run;
+    await vi.advanceTimersByTimeAsync(1_000);
+
+    expect(receivedPrompts).toHaveLength(1);
+    expect(mockStreamStates.get("sid-final-race")).toMatchObject({
+      status: "done",
+      finalReply: "completed at the timeout boundary",
+    });
+    expect(platform.sendText).not.toHaveBeenCalledWith(
+      "chat-final-race",
+      RESPONSE_STALL_RECOVERY_EXHAUSTED_NOTICE,
+    );
+  });
+
+  it("force-closes a stream that stays open after an authoritative final event without auto-recovery", async () => {
+    vi.setSystemTime(0);
+    _setResponseStallTimeoutForTest(100);
+    _setResponseStallCheckIntervalForTest(10);
+    _setFinalResponseCloseTimeoutForTest(1_000);
+    _setProcessAliveForTest(() => true);
+
+    const platform = mockPlatform("feishu");
+    setSessionPlatform(platform);
+    bindChatToSession("sid-final-close", "chat-final-close");
+    recordLastActiveChat("sid-final-close", "chat-final-close");
+
+    const closeSession = vi.fn();
+    const adapter: ToolAdapter = {
+      displayName: "Any Agent",
+      sessionDescPrefix: "Agent Session:",
+      createSession: async () => ({ sessionId: "sid-final-close" }),
+      getSessionInfo: async (sid) => ({ sessionId: sid, cwd: "F:\\repo" }),
+      closeSession: async () => {},
+      prompt: async function* (
+        _sid: string,
+        _text: string,
+        _cwd: string,
+        signal?: AbortSignal,
+        options?: ToolPromptOptions,
+      ) {
+        options?.onSessionCreated?.(closeSession);
+        options?.onProcessStart?.({ pid: 7171 });
+        yield {
+          type: "assistant",
+          blocks: [{ type: "text", text: "authoritative answer" }],
+        };
+        yield {
+          type: "assistant",
+          blocks: [],
+          isFinalResponse: true,
+        };
+        await new Promise<void>((resolve) => {
+          if (signal?.aborted) {
+            resolve();
+            return;
+          }
+          signal?.addEventListener("abort", () => resolve(), { once: true });
+        });
+      },
+    };
+    _setAdapterForToolForTest("claude", adapter);
+
+    const run = runAgentSession(
+      "sid-final-close",
+      "prompt",
+      platform,
+      "chat-final-close",
+      0,
+      "claude",
+    );
+
+    await vi.waitFor(() => {
+      expect(activePrompts.get("sid-final-close")?.finalResponseObserved).toBe(true);
+    });
+    await vi.advanceTimersByTimeAsync(900);
+    expect(activePrompts.has("sid-final-close")).toBe(true);
+
+    await vi.advanceTimersByTimeAsync(100);
+    await run;
+
+    expect(closeSession).toHaveBeenCalledTimes(1);
+    expect(killProcessTreeMock).toHaveBeenCalledWith(7171);
+    expect(mockStreamStates.get("sid-final-close")).toMatchObject({
+      status: "done",
+      finalReply: "authoritative answer",
+    });
+    expect(platform.sendText).not.toHaveBeenCalledWith(
+      "chat-final-close",
+      expect.stringContaining(RESPONSE_STALL_RECOVERY_PROMPT),
+    );
+  });
+
+  it("cancels the final-response close guard when the stream exits normally", async () => {
+    vi.setSystemTime(0);
+    _setFinalResponseCloseTimeoutForTest(1_000);
+    _setProcessAliveForTest(() => true);
+
+    const platform = mockPlatform("feishu");
+    setSessionPlatform(platform);
+    bindChatToSession("sid-final-normal", "chat-final-normal");
+    recordLastActiveChat("sid-final-normal", "chat-final-normal");
+
+    const closeSession = vi.fn();
+    const adapter: ToolAdapter = {
+      displayName: "Any Agent",
+      sessionDescPrefix: "Agent Session:",
+      createSession: async () => ({ sessionId: "sid-final-normal" }),
+      getSessionInfo: async (sid) => ({ sessionId: sid, cwd: "F:\\repo" }),
+      closeSession: async () => {},
+      prompt: async function* (
+        _sid: string,
+        _text: string,
+        _cwd: string,
+        _signal?: AbortSignal,
+        options?: ToolPromptOptions,
+      ) {
+        options?.onSessionCreated?.(closeSession);
+        options?.onProcessStart?.({ pid: 7272 });
+        yield {
+          type: "assistant",
+          blocks: [{ type: "text", text: "normal answer" }],
+        };
+        yield {
+          type: "assistant",
+          blocks: [],
+          isFinalResponse: true,
+        };
+      },
+    };
+    _setAdapterForToolForTest("claude", adapter);
+
+    await runAgentSession(
+      "sid-final-normal",
+      "prompt",
+      platform,
+      "chat-final-normal",
+      0,
+      "claude",
+    );
+    await vi.advanceTimersByTimeAsync(2_000);
+
+    expect(closeSession).not.toHaveBeenCalled();
+    expect(killProcessTreeMock).not.toHaveBeenCalled();
+    expect(mockStreamStates.get("sid-final-normal")).toMatchObject({
+      status: "done",
+      finalReply: "normal answer",
+    });
+  });
+
   it("runs the reserved recovery prompt before an already queued user message", async () => {
     vi.setSystemTime(0);
     _setResponseStallTimeoutForTest(100);
@@ -842,7 +1132,7 @@ describe("runAgentSession response stall watchdog", () => {
     expect(isSessionRunning("sid-recovery-priority")).toBe(true);
     expect(platform.sendText).toHaveBeenCalledWith(
       "chat-recovery-priority",
-      "检测到会话停滞，正在自动确认并继续。",
+      expect.stringContaining(recoveryPrompt),
     );
 
     await vi.advanceTimersByTimeAsync(200);

package/src/adapters/adapter-interface.ts

@@ -87,10 +87,17 @@ export type UnifiedBlock =
 // UnifiedStreamMessage — 一次 SDK/CLI 事件对应的归一化消息
 // ---------------------------------------------------------------------------
 
-export interface UnifiedStreamMessage {
-  type: "assistant" | "user" | "system";
-  blocks: UnifiedBlock[];
-}
+export interface UnifiedStreamMessage {
+  type: "assistant" | "user" | "system";
+  blocks: UnifiedBlock[];
+  /**
+   * 适配器确认本事件代表一条完整、权威的最终回复，而不是流式文本片段。
+   *
+   * response-stall 终止与最终事件可能在同一事件循环边界竞态；只有该标记
+   * 为 true 时，上层才允许把已经触发的超时改判为正常完成。
+   */
+  isFinalResponse?: boolean;
+}
 
 // ---------------------------------------------------------------------------
 // CreateSessionResult
@@ -194,4 +201,4 @@ export function parseUserCommand(userText: string): UserCommand {
   if (original.startsWith("/plan")) return { original, mode: "plan" };
   if (original.startsWith("/ask")) return { original, mode: "ask" };
   return { original, mode: null };
-}
+}

package/src/adapters/ccc-adapter.ts

@@ -96,6 +96,12 @@ export function createCccAdapter(options: CccAdapterOptions = {}): ToolAdapter {
               is_error: event.is_error,
             }],
           };
+        } else if (event.type === "done" && !signal?.aborted) {
+          yield {
+            type: "assistant",
+            blocks: [],
+            isFinalResponse: true,
+          };
         } else if (event.type === "error") {
           throw new Error(event.message);
         }

package/src/adapters/claude-adapter.ts

@@ -57,6 +57,7 @@ interface SdkContentBlock {
 interface SdkMessageLike {
   type?: string;
   subtype?: string;
+  result?: string;
   message?: { content?: SdkContentBlock[] };
   compact_metadata?: {
     trigger?: "manual" | "auto";
@@ -202,6 +203,16 @@ function logMcpConfig(): void {
 }
 
 export function normalizeSdkMessage(msg: SdkMessageLike): UnifiedStreamMessage | null {
+  // SDK result/success 是 Claude 对本轮完整结束的权威确认。文本已经由之前的
+  // assistant 消息累计，因此这里只发送终态信号，避免重复追加 result 文本。
+  if (msg.type === "result" && msg.subtype === "success") {
+    return {
+      type: "assistant",
+      blocks: [],
+      isFinalResponse: true,
+    };
+  }
+
   if (
     (msg.type === "assistant" || msg.type === "user") &&
     msg.message?.content

package/src/adapters/codex-adapter.ts

@@ -130,7 +130,8 @@ interface CodexEvent {
 export function normalizeCodexMessage(
   msg: CodexEvent,
 ): UnifiedStreamMessage | null {
-  // agent_message 文本回复
+  // agent_message 只是 Codex 的一条阶段性文本 item。即使内容看起来像完整答复，
+  // 后面仍可能继续发出工具调用，因此不能用它关闭 response-stall watchdog。
   if (
     msg.type === "item.completed" &&
     msg.item?.type === "agent_message" &&
@@ -142,6 +143,16 @@ export function normalizeCodexMessage(
     };
   }
 
+  // turn.completed 是 Codex 对整轮完成的权威确认。正文已经由之前的
+  // agent_message 累计，这里只发送空终态信号，避免重复追加最终文本。
+  if (msg.type === "turn.completed") {
+    return {
+      type: "assistant",
+      blocks: [],
+      isFinalResponse: true,
+    };
+  }
+
   // command_execution 工具调用开始
   if (
     msg.type === "item.started" &&
@@ -180,7 +191,7 @@ export function normalizeCodexMessage(
     };
   }
 
-  // thread.started / turn.started / turn.completed → 不映射为用户可见消息
+  // thread.started / turn.started → 不映射为用户可见消息
   return null;
 }
 

package/src/adapters/cursor-adapter.ts

@@ -353,6 +353,7 @@ export function normalizeCursorMessage(
     return {
       type: "assistant",
       blocks: [{ type: "text_final", text: msg.result }],
+      isFinalResponse: true,
     };
   }
 

package/src/orchestrator.ts

@@ -1143,11 +1143,47 @@ export async function handleCommand(
       chatInfo = await platform.getChatInfo(chatId);
       description = chatInfo.description;
       const sessionInfo = platform.extractSessionInfo(description);
-      if (sessionInfo) {
-        sessionId = sessionInfo.sessionId;
-        descriptionTool = sessionInfo.tool;
-        toolLabel = toolDisplayName(descriptionTool);
-      }
+      if (sessionInfo) {
+        sessionId = sessionInfo.sessionId;
+        descriptionTool = sessionInfo.tool;
+        toolLabel = toolDisplayName(descriptionTool);
+
+        // 群描述是群聊会话路由的权威来源。历史群可能早于 registry 创建，
+        // 或在冷启动时没有被重建进内存映射；若只解析 sessionId 而不补绑定，
+        // prompt 虽能启动，却找不到生成卡片目标，收尾也无法清除 running。
+        const registry = await loadSessionRegistryForBinding();
+        const record = registry[chatId];
+        if (record?.sessionId && record.sessionId !== sessionId) {
+          unbindChatFromSession(record.sessionId, chatId);
+        }
+        bindChatToSession(sessionId, chatId);
+
+        const memoryInfo = sessionInfoMap.get(chatId);
+        if (!memoryInfo || memoryInfo.sessionId !== sessionId) {
+          sessionInfoMap.set(chatId, {
+            sessionId,
+            tool: descriptionTool,
+            turnCount: record?.sessionId === sessionId ? record.turnCount : 0,
+            lastContextTokens:
+              record?.sessionId === sessionId ? record.lastContextTokens : 0,
+            startTime:
+              record?.sessionId === sessionId
+                ? record.startTime
+                : Date.now(),
+          });
+        }
+
+        // 同步自愈持久化记录，使下一次重启可以直接重建绑定。running 取实际
+        // 内存状态，顺便修复旧故障遗留的 stale running=true。
+        await recordSessionRegistry({
+          chatId,
+          sessionId,
+          tool: descriptionTool,
+          chatType,
+          chatName: chatInfo.name,
+          running: isSessionRunning(sessionId),
+        });
+      }
     } catch (err) {
       logTrace(tid, "BRANCH", {
         reason: "get_chat_info_failed",

package/src/session-chat-binding.ts

@@ -111,6 +111,8 @@ export interface ActivePrompt {
   processPid?: number;
   processMonitor?: ReturnType<typeof setInterval>;
   responseStallMonitor?: ReturnType<typeof setInterval>;
+  /** Grace timer that force-closes a stream which stays open after its authoritative final event. */
+  finalResponseCloseTimer?: ReturnType<typeof setTimeout>;
   /** Character-count progress observed only while the activity is "responding". */
   responseProgress?: ResponseProgressObservation;
   /** Set before a response-stall auto-end begins so competing monitors cannot win the race. */
@@ -123,6 +125,8 @@ export interface ActivePrompt {
   resourceStuck?: boolean;
   /** True only for the single internal continuation turn after a response stall. */
   autoRecovery?: boolean;
+  /** Adapter observed an authoritative completed final-response event. */
+  finalResponseObserved?: boolean;
   /** Adapter-provided callback to close the underlying SDK session / subprocess.
    *  Called by stop-stuck-loop before controller.abort() to terminate the CLI
    *  process immediately, rather than waiting for the async generator to unblock. */
@@ -273,6 +277,7 @@ export function resetBindingState(): void {
   for (const prompt of activePrompts.values()) {
     if (prompt.processMonitor) clearInterval(prompt.processMonitor);
     if (prompt.responseStallMonitor) clearInterval(prompt.responseStallMonitor);
+    if (prompt.finalResponseCloseTimer) clearTimeout(prompt.finalResponseCloseTimer);
   }
   activePrompts.clear();
   finalizingSessions.clear();

package/src/session.ts

@@ -165,14 +165,17 @@ function platformForChat(chatId: string): PlatformAdapter | null {
 const DEFAULT_PROCESS_MONITOR_INTERVAL_MS = 5000;
 const DEFAULT_RESPONSE_STALL_TIMEOUT_MS = 3 * 60 * 1000;
 const DEFAULT_RESPONSE_STALL_CHECK_INTERVAL_MS = 5000;
+const DEFAULT_FINAL_RESPONSE_CLOSE_TIMEOUT_MS = 10_000;
 export const RESPONSE_STALL_RECOVERY_PROMPT = "完成了吗？如果没完成继续";
-export const RESPONSE_STALL_RECOVERY_NOTICE = "检测到会话停滞，正在自动确认并继续。";
+export const RESPONSE_STALL_RECOVERY_NOTICE =
+  `检测到会话停滞，正在自动确认并继续。\n\n${RESPONSE_STALL_RECOVERY_PROMPT}`;
 export const RESPONSE_STALL_RECOVERY_EXHAUSTED_NOTICE =
   "⚠️ 自动续跑仍连续 3 分钟没有新回复，本次不再自动继续。";
 const RESPONSE_STALL_RECOVERY_DELAY_MS = 200;
 let processMonitorIntervalMs = DEFAULT_PROCESS_MONITOR_INTERVAL_MS;
 let responseStallTimeoutMs = DEFAULT_RESPONSE_STALL_TIMEOUT_MS;
 let responseStallCheckIntervalMs = DEFAULT_RESPONSE_STALL_CHECK_INTERVAL_MS;
+let finalResponseCloseTimeoutMs = DEFAULT_FINAL_RESPONSE_CLOSE_TIMEOUT_MS;
 let isProcessAliveImpl = (pid: number): boolean => {
   try {
     process.kill(pid, 0);
@@ -220,7 +223,15 @@ export function _setResponseStallCheckIntervalForTest(ms: number): void {
 export function _resetResponseStallCheckIntervalForTest(): void {
   responseStallCheckIntervalMs = DEFAULT_RESPONSE_STALL_CHECK_INTERVAL_MS;
 }
-
+
+export function _setFinalResponseCloseTimeoutForTest(ms: number): void {
+  finalResponseCloseTimeoutMs = ms;
+}
+
+export function _resetFinalResponseCloseTimeoutForTest(): void {
+  finalResponseCloseTimeoutMs = DEFAULT_FINAL_RESPONSE_CLOSE_TIMEOUT_MS;
+}
+
 function clearPromptProcessMonitor(sessionId: string): void {
   const prompt = activePrompts.get(sessionId);
   if (!prompt?.processMonitor) return;
@@ -235,6 +246,59 @@ function clearPromptResponseStallMonitor(sessionId: string): void {
   prompt.responseStallMonitor = undefined;
 }
 
+function clearPromptFinalResponseCloseTimer(sessionId: string): void {
+  const prompt = activePrompts.get(sessionId);
+  if (!prompt?.finalResponseCloseTimer) return;
+  clearTimeout(prompt.finalResponseCloseTimer);
+  prompt.finalResponseCloseTimer = undefined;
+}
+
+/**
+ * 权威终态只说明 Agent 已完成本轮，不保证 CLI/SDK 的输出流会及时关闭。
+ * 给正常清理保留 10 秒；若流仍悬挂，则关闭底层 session 并杀掉当前 CLI 树，
+ * 让 runAgentSession 以 done 收尾。这里绝不触发自动续跑，因为答案已完整到达。
+ */
+function scheduleFinalResponseCloseGuard(
+  sessionId: string,
+  runningPrompt: NonNullable<ReturnType<typeof activePrompts.get>>,
+): void {
+  if (runningPrompt.finalResponseCloseTimer) return;
+
+  const timeoutMs = finalResponseCloseTimeoutMs;
+  const handle = setTimeout(() => {
+    const current = activePrompts.get(sessionId);
+    if (
+      !current
+      || current !== runningPrompt
+      || !current.finalResponseObserved
+      || current.stopped
+      || current.abnormalExit
+      || current.resourceStuck
+      || current.autoEnded
+    ) {
+      return;
+    }
+
+    current.finalResponseCloseTimer = undefined;
+    clearPromptProcessMonitor(sessionId);
+    clearPromptResponseStallMonitor(sessionId);
+    try {
+      current.closeSession?.();
+    } catch (err) {
+      console.warn(
+        `[${ts()}] [FINAL-RESPONSE] closeSession failed for ${sessionId}: ${(err as Error).message}`,
+      );
+    }
+    current.controller.abort();
+    void killProcessTree(current.processPid);
+    console.warn(
+      `[${ts()}] [FINAL-RESPONSE] Session ${sessionId} stream stayed open for ${timeoutMs}ms after its authoritative final event; forced clean shutdown`,
+    );
+  }, timeoutMs);
+  handle.unref?.();
+  runningPrompt.finalResponseCloseTimer = handle;
+}
+
 function formatTerminalHeader(status: "running" | "done" | "stopped" | "error" | "auto_ended"): {
   title: string;
   template?: string;
@@ -396,6 +460,7 @@ export function resetState(): void {
   for (const prompt of activePrompts.values()) {
     if (prompt.processMonitor) clearInterval(prompt.processMonitor);
     if (prompt.responseStallMonitor) clearInterval(prompt.responseStallMonitor);
+    if (prompt.finalResponseCloseTimer) clearTimeout(prompt.finalResponseCloseTimer);
   }
   activePrompts.clear();
   displayCards.clear();
@@ -997,9 +1062,19 @@ export async function runAgentSession(
   traceId?: string,
   options: RunAgentSessionOptions = {},
 ): Promise<void> {
-  const tid = traceId ?? "";
-
-  // 记录用户最后发送消息的群（display loop 只推送到该群）
+  const tid = traceId ?? "";
+
+  // runAgentSession 是飞书用户消息、队列消息与内部自动恢复共同使用的唯一
+  // prompt 执行入口。即使冷启动后的历史群只靠群描述解析出 sessionId、registry
+  // 尚未重建出内存映射，也必须在任何异步操作前补齐绑定，确保三种来源都有完全
+  // 相同的卡片、状态和收尾行为。
+  const previousSessionId = sessionInfoMap.get(_chatId)?.sessionId;
+  if (previousSessionId && previousSessionId !== sessionId) {
+    unbindChatFromSession(previousSessionId, _chatId);
+  }
+  bindChatToSession(sessionId, _chatId);
+
+  // 记录用户最后发送消息的群（display loop 只推送到该群）
   // 如果是从队列消费且队列消息来自其他群，保留原来的 display chat
   recordChatPlatform(_chatId, platform);
   recordLastActiveChat(sessionId, consumeQueuePreservedChat(sessionId) ?? _chatId);
@@ -1025,6 +1100,7 @@ export async function runAgentSession(
     stopped: false,
     startTime: now,
     autoRecovery: options.autoRecovery === true,
+    finalResponseObserved: false,
   });
 
   // 资源监控僵死检测：CPU + 内存连续 3 分钟无变化 → 强制停止
@@ -1269,6 +1345,7 @@ export async function runAgentSession(
         || current.abnormalExit
         || current.resourceStuck
         || current.autoEnded
+        || current.finalResponseObserved
         || activityTracker.activity.kind !== "responding"
         || !hasResponseStalled(current.responseProgress, Date.now(), responseStallTimeoutMs)
       ) {
@@ -1305,6 +1382,18 @@ export async function runAgentSession(
         autoEndedAt,
       });
 
+      // 最终事件可能在上面的落盘 I/O 期间到达。只有适配器明确标记的完整
+      // final response 才能赢得这场竞态；普通文本片段绝不能取消超时。
+      if (current.finalResponseObserved) {
+        current.autoEnded = false;
+        current.autoEndedAt = undefined;
+        cancelAutoRecoveryReservation(sessionId);
+        console.log(
+          `[${ts()}] [RESPONSE-STALL] Authoritative final response won timeout race for ${sessionId}`,
+        );
+        return;
+      }
+
       try {
         current.closeSession?.();
       } catch (err) {
@@ -1336,11 +1425,23 @@ export async function runAgentSession(
         clearPromptProcessMonitor(sessionId);
         if (exitInfo.pid !== undefined) unregisterProcess(exitInfo.pid);
       },
-      onSessionCreated: (closeSession) => {
-        const prompt = activePrompts.get(sessionId);
-        if (prompt) prompt.closeSession = closeSession;
-      },
-    })) {
+      onSessionCreated: (closeSession) => {
+        const prompt = activePrompts.get(sessionId);
+        if (prompt) prompt.closeSession = closeSession;
+      },
+    })) {
+      if (unifiedMsg.isFinalResponse) {
+        const prompt = activePrompts.get(sessionId);
+        if (prompt && prompt === runningPrompt) {
+          // 同步标记必须发生在任何 await 之前，让 watchdog 无法在已收到完整
+          // 最终事件后仍把本轮判为停滞。
+          if (!prompt.finalResponseObserved) {
+            prompt.finalResponseObserved = true;
+            scheduleFinalResponseCloseGuard(sessionId, prompt);
+          }
+        }
+      }
+
       let activityChanged = false;
       for (const block of unifiedMsg.blocks) {
         if (updateAgentActivity(activityTracker, block)) activityChanged = true;
@@ -1401,27 +1502,47 @@ export async function runAgentSession(
     const wasStopped = prompt?.stopped ?? false;
     const wasAbnormalExit = prompt?.abnormalExit ?? false;
     const wasResourceStuck = prompt?.resourceStuck ?? false;
-    const wasAutoEnded = prompt?.autoEnded ?? false;
+    const timeoutTriggered = prompt?.autoEnded ?? false;
+    const completedAtTimeoutBoundary =
+      timeoutTriggered && (prompt?.finalResponseObserved ?? false);
+    const wasAutoEnded = timeoutTriggered && !completedAtTimeoutBoundary;
     const wasAutoRecovery = prompt?.autoRecovery ?? false;
-    const autoEndedAt = prompt?.autoEndedAt;
+    const autoEndedAt = wasAutoEnded ? prompt?.autoEndedAt : undefined;
     clearPromptResponseStallMonitor(sessionId);
     clearPromptProcessMonitor(sessionId);
+    clearPromptFinalResponseCloseTimer(sessionId);
     markSessionFinalizing(sessionId);
     activePrompts.delete(sessionId);
 
     try {
-    // 先写最终状态（done/stopped），确保 display loop 在下一轮消费前
-    // 读到新状态并终结旧卡片。否则 setImmediate 在 CHECK 阶段先于
-    // writeFile I/O（POLL 阶段）执行，display loop 会误以为旧轮仍在
-    // 运行中并更新旧卡片，而不是新建卡片。
-    const finalStatus = wasAutoEnded
-      ? "auto_ended"
-      : (streamErrored || wasAbnormalExit || wasResourceStuck)
-        ? "error"
-        : wasStopped
-          ? "stopped"
-          : "done";
-    const finalReply = pickFinalReply(state).trim();
+      if (completedAtTimeoutBoundary) {
+        // reservation 可能在 watchdog 开始终止普通轮时已经建立。最终回复若在
+        // abort/kill 清理边界到达，本轮按完成处理，并原子取消尚未启动的恢复轮。
+        cancelAutoRecoveryReservation(sessionId);
+        console.log(
+          `[${ts()}] [RESPONSE-STALL] Session ${sessionId} completed with an authoritative final response during timeout cleanup`,
+        );
+      }
+      // 即使运行期间映射被异常清空，也必须更新本次实际触发 chat，避免 registry
+      // 永久残留 running=true。
+      const finalizationChatIds = [...new Set([
+        ...getChatsForSession(sessionId),
+        _chatId,
+      ])];
+      // 先写最终状态（done/stopped），确保 display loop 在下一轮消费前
+      // 读到新状态并终结旧卡片。否则 setImmediate 在 CHECK 阶段先于
+      // writeFile I/O（POLL 阶段）执行，display loop 会误以为旧轮仍在
+      // 运行中并更新旧卡片，而不是新建卡片。
+      const finalStatus = completedAtTimeoutBoundary
+        ? "done"
+        : wasAutoEnded
+          ? "auto_ended"
+          : (streamErrored || wasAbnormalExit || wasResourceStuck)
+            ? "error"
+            : wasStopped
+              ? "stopped"
+              : "done";
+      const finalReply = pickFinalReply(state).trim();
 
     // stop-stuck-loop 接口可能在 fire-and-forget 中已写入带 final_reply 的
     // stream state，finally 不应覆盖它。同时保留 stuckAt 标记，防止
@@ -1459,7 +1580,7 @@ export async function runAgentSession(
     let autoRecoveryTarget: { chatId: string; platform: PlatformAdapter } | undefined;
 
     if (wasStopped) {
-      for (const cid of getChatsForSession(sessionId)) {
+      for (const cid of finalizationChatIds) {
         const finfo = sessionInfoMap.get(cid);
         await recordSessionRegistry({
           chatId: cid,
@@ -1471,7 +1592,7 @@ export async function runAgentSession(
           running: false,
         });
       }
-      const active1 = getLastActiveChat(sessionId) ?? getChatsForSession(sessionId)[0];
+      const active1 = getLastActiveChat(sessionId) ?? finalizationChatIds[0];
       if (active1) {
         await platform.sendText(active1, "会话已停止。").catch(() => {});
         platform.setChatAvatar(active1, tool, "idle").catch(() => {});
@@ -1479,7 +1600,7 @@ export async function runAgentSession(
       console.log(`[${ts()}] Session ${sessionId} stopped (content chunks: ${state.chunkCount})`);
       if (tid) logTrace(tid, "SESSION_END", { sessionId, outcome: "stopped", chunks: state.chunkCount });
     } else if (wasAutoEnded) {
-      for (const cid of getChatsForSession(sessionId)) {
+      for (const cid of finalizationChatIds) {
         const finfo = sessionInfoMap.get(cid);
         await recordSessionRegistry({
           chatId: cid,
@@ -1491,7 +1612,7 @@ export async function runAgentSession(
           running: false,
         });
       }
-      const activeAutoEnded = getLastActiveChat(sessionId) ?? getChatsForSession(sessionId)[0];
+      const activeAutoEnded = getLastActiveChat(sessionId) ?? finalizationChatIds[0];
       if (activeAutoEnded) {
         const pp = platformForChat(activeAutoEnded) ?? platform;
         const terminalState = await readStreamState(sessionId);
@@ -1526,7 +1647,7 @@ export async function runAgentSession(
       console.warn(`[${ts()}] Session ${sessionId} auto-ended after stalled response output (content chunks: ${state.chunkCount})`);
       if (tid) logTrace(tid, "SESSION_END", { sessionId, outcome: "response_stall", chunks: state.chunkCount });
     } else if (wasAbnormalExit) {
-      for (const cid of getChatsForSession(sessionId)) {
+      for (const cid of finalizationChatIds) {
         const finfo = sessionInfoMap.get(cid);
         await recordSessionRegistry({
           chatId: cid,
@@ -1538,12 +1659,12 @@ export async function runAgentSession(
           running: false,
         });
       }
-      const activeErr = getLastActiveChat(sessionId) ?? getChatsForSession(sessionId)[0];
+      const activeErr = getLastActiveChat(sessionId) ?? finalizationChatIds[0];
       if (activeErr) platform.setChatAvatar(activeErr, tool, "idle").catch(() => {});
       console.log(`[${ts()}] Session ${sessionId} process exited unexpectedly (content chunks: ${state.chunkCount})`);
       if (tid) logTrace(tid, "SESSION_END", { sessionId, outcome: "process_missing", chunks: state.chunkCount });
-    } else {
-      for (const cid of getChatsForSession(sessionId)) {
+    } else {
+      for (const cid of finalizationChatIds) {
         const finfo = sessionInfoMap.get(cid);
         await recordSessionRegistry({
           chatId: cid,
@@ -1555,7 +1676,7 @@ export async function runAgentSession(
           running: false,
         });
       }
-      const active2 = getLastActiveChat(sessionId) ?? getChatsForSession(sessionId)[0];
+      const active2 = getLastActiveChat(sessionId) ?? finalizationChatIds[0];
       if (active2) {
         const terminalState = await readStreamState(sessionId);
         if (finalReply && !displayCards.has(active2) && (!terminalState || !isFinalReplySentForTurn(terminalState))) {
@@ -2027,6 +2148,7 @@ export function stopSession(sessionId: string): boolean {
   prompt.stopped = true;
   clearPromptResponseStallMonitor(sessionId);
   clearPromptProcessMonitor(sessionId);
+  clearPromptFinalResponseCloseTimer(sessionId);
   cancelQueuedMessage(sessionId);
   try {
     prompt.closeSession?.();