chatccc 0.2.242 → 0.2.243

package/src/__tests__/session.test.ts

@@ -9,7 +9,7 @@ vi.mock("../adapters/proc-tree-kill.ts", () => ({
 }));
 
 // mock stream-state 以支持在测试中控制累积长度
-const mockStreamStates = new Map<string, {
+const mockStreamStates = new Map<string, {
   accumulatedContent: string;
   finalReply: string;
   activity?: {
@@ -22,14 +22,14 @@ const mockStreamStates = new Map<string, {
   autoEndedAt?: number;
   turnCount?: number;
   finalReplySentTurn?: number;
-  finalReplySentAt?: number;
-  terminalError?: {
-    kind: "network_timeout" | "network" | "authentication" | "rate_limit" | "provider" | "process" | "resource" | "unknown";
-    title: string;
-    message: string;
-    occurredAt: number;
-  };
-}>();
+  finalReplySentAt?: number;
+  terminalError?: {
+    kind: "network_timeout" | "network" | "authentication" | "rate_limit" | "provider" | "process" | "resource" | "unknown";
+    title: string;
+    message: string;
+    occurredAt: number;
+  };
+}>();
 vi.mock("../stream-state.ts", () => ({
   readStreamState: async (sid: string) => {
     const state = mockStreamStates.get(sid);
@@ -40,8 +40,8 @@ vi.mock("../stream-state.ts", () => ({
       finalReply: state.finalReply,
       activity: state.activity,
       finalReplySentTurn: state.finalReplySentTurn,
-      finalReplySentAt: state.finalReplySentAt,
-      terminalError: state.terminalError,
+      finalReplySentAt: state.finalReplySentAt,
+      terminalError: state.terminalError,
       autoEndedAt: state.autoEndedAt,
       status: state.status ?? "running",
       chunkCount: 0,
@@ -66,14 +66,14 @@ vi.mock("../stream-state.ts", () => ({
     autoEndedAt?: number;
     turnCount?: number;
     finalReplySentTurn?: number;
-    finalReplySentAt?: number;
-    terminalError?: {
-      kind: "network_timeout" | "network" | "authentication" | "rate_limit" | "provider" | "process" | "resource" | "unknown";
-      title: string;
-      message: string;
-      occurredAt: number;
-    };
-  }) => {
+    finalReplySentAt?: number;
+    terminalError?: {
+      kind: "network_timeout" | "network" | "authentication" | "rate_limit" | "provider" | "process" | "resource" | "unknown";
+      title: string;
+      message: string;
+      occurredAt: number;
+    };
+  }) => {
     mockStreamStates.set(state.sessionId, {
       accumulatedContent: state.accumulatedContent,
       finalReply: state.finalReply,
@@ -82,8 +82,8 @@ vi.mock("../stream-state.ts", () => ({
       autoEndedAt: state.autoEndedAt,
       turnCount: state.turnCount,
       finalReplySentTurn: state.finalReplySentTurn,
-      finalReplySentAt: state.finalReplySentAt,
-      terminalError: state.terminalError,
+      finalReplySentAt: state.finalReplySentAt,
+      terminalError: state.terminalError,
     });
   },
   createEmptyStreamState: (sid: string, cwd: string, tool: string, turnCount: number) => ({
@@ -131,11 +131,11 @@ import {
   stopUnifiedDisplayLoop,
   _setProcessAliveForTest,
   _resetProcessAliveForTest,
-  _setProcessMonitorIntervalForTest,
-  _resetProcessMonitorIntervalForTest,
-  _setAvatarRefreshIntervalForTest,
-  _resetAvatarRefreshIntervalForTest,
-  _setResponseStallTimeoutForTest,
+  _setProcessMonitorIntervalForTest,
+  _resetProcessMonitorIntervalForTest,
+  _setAvatarRefreshIntervalForTest,
+  _resetAvatarRefreshIntervalForTest,
+  _setResponseStallTimeoutForTest,
   _resetResponseStallTimeoutForTest,
   _setResponseStallCheckIntervalForTest,
   _resetResponseStallCheckIntervalForTest,
@@ -438,7 +438,7 @@ describe("runAgentSession previous final delivery guard", () => {
   });
 });
 
-describe("runAgentSession process monitor", () => {
+describe("runAgentSession process monitor", () => {
   let registryFile = "";
   let toolsFile = "";
 
@@ -468,7 +468,7 @@ describe("runAgentSession process monitor", () => {
     vi.useRealTimers();
   });
 
-  it("marks the turn as error and sends a separate notice when the CLI process disappears", async () => {
+  it("marks the turn as error and sends a separate notice when the CLI process disappears", async () => {
     const platform = mockPlatform("feishu");
     setSessionPlatform(platform);
     bindChatToSession("sid-process", "chat-process");
@@ -524,52 +524,52 @@ describe("runAgentSession process monitor", () => {
       "chat-process",
       expect.stringContaining("进程异常结束"),
     );
-  });
-
-  it("persists and sends the root cause when the agent stream fails before producing output", async () => {
-    vi.spyOn(console, "error").mockImplementation(() => {});
-    const platform = mockPlatform("feishu");
-    platform.cardCreate = vi.fn(async () => {
-      throw new Error("CardKit unavailable");
-    });
-    setSessionPlatform(platform);
-    bindChatToSession("sid-stream-error", "chat-stream-error");
-    recordLastActiveChat("sid-stream-error", "chat-stream-error");
-
-    const adapter: ToolAdapter = {
-      displayName: "CCC Agent",
-      sessionDescPrefix: "CCC Session:",
-      createSession: async () => ({ sessionId: "sid-stream-error" }),
-      getSessionInfo: async (sid) => ({ sessionId: sid, cwd: "/tmp" }),
-      closeSession: async () => {},
-      prompt: async function* () {
-        throw new Error(
-          "Failed after 3 attempts. Last error: Cannot connect to API: " +
-          "Connect Timeout Error (timeout: 10000ms)",
-        );
-      },
-    };
-    _setAdapterForToolForTest("ccc", adapter);
-
-    const outcome = await runAgentSession(
-      "sid-stream-error",
-      "prompt",
-      platform,
-      "chat-stream-error",
-      Date.now(),
-      "ccc",
-    );
-
-    const state = mockStreamStates.get("sid-stream-error");
-    expect(outcome).toBe("error");
-    expect(state?.status).toBe("error");
-    expect(state?.terminalError?.kind).toBe("network_timeout");
-    expect(state?.terminalError?.message).toContain("已重试 3 次");
-    expect(platform.sendText).toHaveBeenCalledWith(
-      "chat-stream-error",
-      expect.stringContaining("网络连接超时"),
-    );
-  });
+  });
+
+  it("persists and sends the root cause when the agent stream fails before producing output", async () => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    const platform = mockPlatform("feishu");
+    platform.cardCreate = vi.fn(async () => {
+      throw new Error("CardKit unavailable");
+    });
+    setSessionPlatform(platform);
+    bindChatToSession("sid-stream-error", "chat-stream-error");
+    recordLastActiveChat("sid-stream-error", "chat-stream-error");
+
+    const adapter: ToolAdapter = {
+      displayName: "CCC Agent",
+      sessionDescPrefix: "CCC Session:",
+      createSession: async () => ({ sessionId: "sid-stream-error" }),
+      getSessionInfo: async (sid) => ({ sessionId: sid, cwd: "/tmp" }),
+      closeSession: async () => {},
+      prompt: async function* () {
+        throw new Error(
+          "Failed after 3 attempts. Last error: Cannot connect to API: " +
+          "Connect Timeout Error (timeout: 10000ms)",
+        );
+      },
+    };
+    _setAdapterForToolForTest("ccc", adapter);
+
+    const outcome = await runAgentSession(
+      "sid-stream-error",
+      "prompt",
+      platform,
+      "chat-stream-error",
+      Date.now(),
+      "ccc",
+    );
+
+    const state = mockStreamStates.get("sid-stream-error");
+    expect(outcome).toBe("error");
+    expect(state?.status).toBe("error");
+    expect(state?.terminalError?.kind).toBe("network_timeout");
+    expect(state?.terminalError?.message).toContain("已重试 3 次");
+    expect(platform.sendText).toHaveBeenCalledWith(
+      "chat-stream-error",
+      expect.stringContaining("网络连接超时"),
+    );
+  });
 
   it("recreates the progress card when the initial CardKit send fails", async () => {
     vi.spyOn(console, "error").mockImplementation(() => {});
@@ -806,99 +806,99 @@ describe("runAgentSession process monitor", () => {
     expect(sentTexts[0]).toContain("first prompt");
     expect(sentTexts[1]).toContain("second prompt");
   });
-});
-
-describe("runAgentSession periodic avatar refresh", () => {
-  let registryFile = "";
-  let toolsFile = "";
-
-  beforeEach(async () => {
-    vi.useFakeTimers();
-    resetState();
-    resetBindingState();
-    mockStreamStates.clear();
-    const dir = await mkdtemp(join(tmpdir(), "chatccc-avatar-refresh-"));
-    registryFile = join(dir, "session-registry.json");
-    toolsFile = join(dir, "session-tools.json");
-    _setSessionRegistryFileForTest(registryFile);
-    _setSessionToolsFileForTest(toolsFile);
-    _setAvatarRefreshIntervalForTest(50);
-  });
-
-  afterEach(async () => {
-    _resetSessionRegistryFileForTest();
-    _resetSessionToolsFileForTest();
-    _resetAvatarRefreshIntervalForTest();
-    _clearAdapterCacheForTest();
-    resetState();
-    resetBindingState();
-    vi.useRealTimers();
-    if (registryFile) await rm(dirname(registryFile), { recursive: true, force: true });
-  });
-
-  it.each(["codex", "cursor", "claude", "ccc"])(
-    "refreshes the busy avatar for %s every interval and stops after completion",
-    async (tool) => {
-      const sessionId = `sid-avatar-${tool}`;
-      const chatId = `chat-avatar-${tool}`;
-      const platform = mockPlatform("feishu");
-      setSessionPlatform(platform);
-      bindChatToSession(sessionId, chatId);
-      recordLastActiveChat(sessionId, chatId);
-
-      let finishPrompt: (() => void) | undefined;
-      const adapter: ToolAdapter = {
-        displayName: tool,
-        sessionDescPrefix: `${tool} Session:`,
-        createSession: async () => ({ sessionId }),
-        getSessionInfo: async (sid) => ({ sessionId: sid, cwd: "/tmp" }),
-        closeSession: async () => {},
-        prompt: async function* () {
-          yield { type: "assistant", blocks: [{ type: "text", text: "working" }] };
-          await new Promise<void>((resolve) => {
-            finishPrompt = resolve;
-          });
-          yield { type: "assistant", blocks: [{ type: "text", text: "done" }] };
-        },
-      };
-      _setAdapterForToolForTest(tool, adapter);
-
-      const runPromise = runAgentSession(
-        sessionId,
-        "prompt",
-        platform,
-        chatId,
-        Date.now(),
-        tool,
-      );
-
-      await vi.waitFor(() => {
-        expect(vi.mocked(platform.setChatAvatar).mock.calls.some(
-          ([calledChatId, calledTool, status]) =>
-            calledChatId === chatId && calledTool === tool && status === "busy",
-        )).toBe(true);
-        expect(finishPrompt).toBeTypeOf("function");
-      });
-      const initialBusyCalls = vi.mocked(platform.setChatAvatar).mock.calls.filter(
-        ([calledChatId, calledTool, status]) =>
-          calledChatId === chatId && calledTool === tool && status === "busy",
-      ).length;
-
-      await vi.advanceTimersByTimeAsync(51);
-      expect(vi.mocked(platform.setChatAvatar).mock.calls.filter(
-        ([calledChatId, calledTool, status]) =>
-          calledChatId === chatId && calledTool === tool && status === "busy",
-      )).toHaveLength(initialBusyCalls + 1);
-
-      finishPrompt?.();
-      await runPromise;
-      const callsAfterCompletion = vi.mocked(platform.setChatAvatar).mock.calls.length;
-
-      await vi.advanceTimersByTimeAsync(100);
-      expect(platform.setChatAvatar).toHaveBeenCalledTimes(callsAfterCompletion);
-    },
-  );
-});
+});
+
+describe("runAgentSession periodic avatar refresh", () => {
+  let registryFile = "";
+  let toolsFile = "";
+
+  beforeEach(async () => {
+    vi.useFakeTimers();
+    resetState();
+    resetBindingState();
+    mockStreamStates.clear();
+    const dir = await mkdtemp(join(tmpdir(), "chatccc-avatar-refresh-"));
+    registryFile = join(dir, "session-registry.json");
+    toolsFile = join(dir, "session-tools.json");
+    _setSessionRegistryFileForTest(registryFile);
+    _setSessionToolsFileForTest(toolsFile);
+    _setAvatarRefreshIntervalForTest(50);
+  });
+
+  afterEach(async () => {
+    _resetSessionRegistryFileForTest();
+    _resetSessionToolsFileForTest();
+    _resetAvatarRefreshIntervalForTest();
+    _clearAdapterCacheForTest();
+    resetState();
+    resetBindingState();
+    vi.useRealTimers();
+    if (registryFile) await rm(dirname(registryFile), { recursive: true, force: true });
+  });
+
+  it.each(["codex", "cursor", "claude", "ccc"])(
+    "refreshes the busy avatar for %s every interval and stops after completion",
+    async (tool) => {
+      const sessionId = `sid-avatar-${tool}`;
+      const chatId = `chat-avatar-${tool}`;
+      const platform = mockPlatform("feishu");
+      setSessionPlatform(platform);
+      bindChatToSession(sessionId, chatId);
+      recordLastActiveChat(sessionId, chatId);
+
+      let finishPrompt: (() => void) | undefined;
+      const adapter: ToolAdapter = {
+        displayName: tool,
+        sessionDescPrefix: `${tool} Session:`,
+        createSession: async () => ({ sessionId }),
+        getSessionInfo: async (sid) => ({ sessionId: sid, cwd: "/tmp" }),
+        closeSession: async () => {},
+        prompt: async function* () {
+          yield { type: "assistant", blocks: [{ type: "text", text: "working" }] };
+          await new Promise<void>((resolve) => {
+            finishPrompt = resolve;
+          });
+          yield { type: "assistant", blocks: [{ type: "text", text: "done" }] };
+        },
+      };
+      _setAdapterForToolForTest(tool, adapter);
+
+      const runPromise = runAgentSession(
+        sessionId,
+        "prompt",
+        platform,
+        chatId,
+        Date.now(),
+        tool,
+      );
+
+      await vi.waitFor(() => {
+        expect(vi.mocked(platform.setChatAvatar).mock.calls.some(
+          ([calledChatId, calledTool, status]) =>
+            calledChatId === chatId && calledTool === tool && status === "busy",
+        )).toBe(true);
+        expect(finishPrompt).toBeTypeOf("function");
+      });
+      const initialBusyCalls = vi.mocked(platform.setChatAvatar).mock.calls.filter(
+        ([calledChatId, calledTool, status]) =>
+          calledChatId === chatId && calledTool === tool && status === "busy",
+      ).length;
+
+      await vi.advanceTimersByTimeAsync(51);
+      expect(vi.mocked(platform.setChatAvatar).mock.calls.filter(
+        ([calledChatId, calledTool, status]) =>
+          calledChatId === chatId && calledTool === tool && status === "busy",
+      )).toHaveLength(initialBusyCalls + 1);
+
+      finishPrompt?.();
+      await runPromise;
+      const callsAfterCompletion = vi.mocked(platform.setChatAvatar).mock.calls.length;
+
+      await vi.advanceTimersByTimeAsync(100);
+      expect(platform.setChatAvatar).toHaveBeenCalledTimes(callsAfterCompletion);
+    },
+  );
+});
 
 describe("runAgentSession response stall watchdog", () => {
   let tempDir = "";
@@ -1001,7 +1001,7 @@ describe("runAgentSession response stall watchdog", () => {
     });
   });
 
-  it("does not apply the reply-stall timeout while an Agent is compacting context", async () => {
+  it("does not apply the reply-stall timeout while an Agent is compacting context", async () => {
     vi.setSystemTime(0);
     _setResponseStallTimeoutForTest(180_000);
     _setResponseStallCheckIntervalForTest(1_000);
@@ -1026,10 +1026,10 @@ describe("runAgentSession response stall watchdog", () => {
         signal?: AbortSignal,
         options?: ToolPromptOptions,
       ) {
-        options?.onSessionCreated?.(closeSession);
-        options?.onProcessStart?.({ pid: 4343 });
-        yield { type: "assistant", blocks: [{ type: "agent_status", status: "compacting" }] };
-        await new Promise<void>((resolve) => {
+        options?.onSessionCreated?.(closeSession);
+        options?.onProcessStart?.({ pid: 4343 });
+        yield { type: "assistant", blocks: [{ type: "agent_status", status: "compacting" }] };
+        await new Promise<void>((resolve) => {
           if (signal?.aborted) {
             resolve();
             return;
@@ -1051,11 +1051,11 @@ describe("runAgentSession response stall watchdog", () => {
     );
 
     await vi.waitFor(() => {
-      expect(activePrompts.get("sid-starting-stall")).toMatchObject({
-        processPid: 4343,
-      });
-      expect(activePrompts.get("sid-starting-stall")?.responseProgress).toBeUndefined();
-      expect(closeSession).toHaveBeenCalledTimes(0);
+      expect(activePrompts.get("sid-starting-stall")).toMatchObject({
+        processPid: 4343,
+      });
+      expect(activePrompts.get("sid-starting-stall")?.responseProgress).toBeUndefined();
+      expect(closeSession).toHaveBeenCalledTimes(0);
     });
 
     await vi.advanceTimersByTimeAsync(181_001);
@@ -1066,17 +1066,17 @@ describe("runAgentSession response stall watchdog", () => {
       .length;
 
     // 旧实现不会结束真正的零事件启动；先清理测试会话，避免失败用例悬挂。
-    stopSession("sid-starting-stall");
-    await vi.advanceTimersByTimeAsync(1_000);
-    await runPromise;
-
-    expect(stateAfterDeadline).toMatchObject({
-      status: "running",
-      activity: { kind: "compacting" },
-    });
-    expect(closeCountAfterDeadline).toBe(0);
-    expect(treeKillCountAfterDeadline).toBe(0);
-  });
+    stopSession("sid-starting-stall");
+    await vi.advanceTimersByTimeAsync(1_000);
+    await runPromise;
+
+    expect(stateAfterDeadline).toMatchObject({
+      status: "running",
+      activity: { kind: "compacting" },
+    });
+    expect(closeCountAfterDeadline).toBe(0);
+    expect(treeKillCountAfterDeadline).toBe(0);
+  });
 
   it("self-heals a missing trigger-chat binding and gives automatic recovery the normal card lifecycle", async () => {
     vi.setSystemTime(0);
@@ -1519,7 +1519,7 @@ describe("runAgentSession response stall watchdog", () => {
     expect(receivedPrompts[1]).toContain(recoveryPrompt);
     expect(platform.sendText).toHaveBeenCalledWith(
       "chat-recovery-limit",
-      "⚠️ 自动续跑仍连续 3 分钟没有生成新回复，本次不再自动继续。",
+      "⚠️ 自动续跑仍连续 3 分钟没有生成新回复，本次不再自动继续。",
     );
   });
 
@@ -1721,7 +1721,7 @@ describe("unified display loop activity status", () => {
   });
 });
 
-describe("unified display loop terminal card update", () => {
+describe("unified display loop terminal card update", () => {
   beforeEach(() => {
     vi.useFakeTimers();
     resetState();
@@ -1735,7 +1735,7 @@ describe("unified display loop terminal card update", () => {
     vi.useRealTimers();
   });
 
-  it("shows a distinct auto-ended state and sends a warning even with an empty reply", async () => {
+  it("shows a distinct auto-ended state and sends a warning even with an empty reply", async () => {
     const platform = mockPlatform("feishu");
     setSessionPlatform(platform);
 
@@ -1777,115 +1777,115 @@ describe("unified display loop terminal card update", () => {
     expect(card.header.title.content).toBe("已自动结束 · 3分钟无新内容");
     expect(card.header.template).toBe("orange");
     expect(platform.sendText).toHaveBeenCalledWith(
-      "chat-auto-ended",
-      "⚠️ 已自动结束：生成回复阶段连续 3 分钟没有字符变化。本轮没有可发送的回复内容。",
+      "chat-auto-ended",
+      "⚠️ 已自动结束：生成回复阶段连续 3 分钟没有字符变化。本轮没有可发送的回复内容。",
     );
     expect(displayCards.has("chat-auto-ended")).toBe(false);
-  });
-
-  it("shows the stream root cause in the error card without a duplicate text notice", async () => {
-    const platform = mockPlatform("feishu");
-    setSessionPlatform(platform);
-
-    bindChatToSession("sid-network-error", "chat-network-error");
-    recordLastActiveChat("sid-network-error", "chat-network-error");
-    sessionInfoMap.set("chat-network-error", {
-      sessionId: "sid-network-error",
-      turnCount: 1,
-      lastContextTokens: 0,
-      startTime: 0,
-      tool: "ccc",
-    });
-    displayCards.set("chat-network-error", {
-      cardId: "card-network-error",
-      sequence: 1,
-      cardBusy: false,
-      cardCreatedAt: Date.now(),
-      lastSentContent: "",
-      streamErrorNotified: false,
-      sessionId: "sid-network-error",
-      turnCount: 1,
-      dotCount: 0,
-    });
-    mockStreamStates.set("sid-network-error", {
-      accumulatedContent: "",
-      finalReply: "",
-      status: "error",
-      turnCount: 1,
-      terminalError: {
-        kind: "network_timeout",
-        title: "网络连接超时",
-        message: "连接模型服务失败，已重试 3 次，单次连接等待 10 秒。请检查网络、VPN或模型服务状态后重试。",
-        occurredAt: Date.now(),
-      },
-    });
-
-    startUnifiedDisplayLoop();
-    await vi.advanceTimersByTimeAsync(3_000);
-
-    const payload = vi.mocked(platform.cardUpdate).mock.calls[0]?.[1];
-    const card = JSON.parse(payload as string) as {
-      header: { title: { content: string }; template?: string };
-      body: { elements: Array<{ content?: string }> };
-    };
-    expect(card.header.title.content).toBe("异常结束 · 网络连接超时");
-    expect(card.header.template).toBe("red");
-    expect(card.body.elements[0]?.content).toContain("已重试 3 次");
-    expect(platform.sendText).not.toHaveBeenCalled();
-    expect(mockStreamStates.get("sid-network-error")?.finalReplySentTurn).toBe(1);
-    expect(displayCards.has("chat-network-error")).toBe(false);
-  });
-
-  it("falls back to a root-cause text when the error card cannot be updated", async () => {
-    vi.spyOn(console, "error").mockImplementation(() => {});
-    const platform = mockPlatform("feishu");
-    platform.cardUpdate = vi.fn(async () => {
-      throw new Error("CardKit unavailable");
-    });
-    setSessionPlatform(platform);
-
-    bindChatToSession("sid-error-fallback", "chat-error-fallback");
-    recordLastActiveChat("sid-error-fallback", "chat-error-fallback");
-    sessionInfoMap.set("chat-error-fallback", {
-      sessionId: "sid-error-fallback",
-      turnCount: 1,
-      lastContextTokens: 0,
-      startTime: 0,
-      tool: "ccc",
-    });
-    displayCards.set("chat-error-fallback", {
-      cardId: "card-error-fallback",
-      sequence: 1,
-      cardBusy: false,
-      cardCreatedAt: Date.now(),
-      lastSentContent: "",
-      streamErrorNotified: false,
-      sessionId: "sid-error-fallback",
-      turnCount: 1,
-      dotCount: 0,
-    });
-    mockStreamStates.set("sid-error-fallback", {
-      accumulatedContent: "",
-      finalReply: "",
-      status: "error",
-      turnCount: 1,
-      terminalError: {
-        kind: "network_timeout",
-        title: "网络连接超时",
-        message: "连接模型服务失败，已重试 3 次。",
-        occurredAt: Date.now(),
-      },
-    });
-
-    startUnifiedDisplayLoop();
-    await vi.advanceTimersByTimeAsync(3_000);
-
-    expect(platform.sendText).toHaveBeenCalledWith(
-      "chat-error-fallback",
-      expect.stringContaining("异常结束：网络连接超时"),
-    );
-    expect(displayCards.has("chat-error-fallback")).toBe(false);
-  });
+  });
+
+  it("shows the stream root cause in the error card without a duplicate text notice", async () => {
+    const platform = mockPlatform("feishu");
+    setSessionPlatform(platform);
+
+    bindChatToSession("sid-network-error", "chat-network-error");
+    recordLastActiveChat("sid-network-error", "chat-network-error");
+    sessionInfoMap.set("chat-network-error", {
+      sessionId: "sid-network-error",
+      turnCount: 1,
+      lastContextTokens: 0,
+      startTime: 0,
+      tool: "ccc",
+    });
+    displayCards.set("chat-network-error", {
+      cardId: "card-network-error",
+      sequence: 1,
+      cardBusy: false,
+      cardCreatedAt: Date.now(),
+      lastSentContent: "",
+      streamErrorNotified: false,
+      sessionId: "sid-network-error",
+      turnCount: 1,
+      dotCount: 0,
+    });
+    mockStreamStates.set("sid-network-error", {
+      accumulatedContent: "",
+      finalReply: "",
+      status: "error",
+      turnCount: 1,
+      terminalError: {
+        kind: "network_timeout",
+        title: "网络连接超时",
+        message: "连接模型服务失败，已重试 3 次，单次连接等待 10 秒。请检查网络、VPN或模型服务状态后重试。",
+        occurredAt: Date.now(),
+      },
+    });
+
+    startUnifiedDisplayLoop();
+    await vi.advanceTimersByTimeAsync(3_000);
+
+    const payload = vi.mocked(platform.cardUpdate).mock.calls[0]?.[1];
+    const card = JSON.parse(payload as string) as {
+      header: { title: { content: string }; template?: string };
+      body: { elements: Array<{ content?: string }> };
+    };
+    expect(card.header.title.content).toBe("异常结束 · 网络连接超时");
+    expect(card.header.template).toBe("red");
+    expect(card.body.elements[0]?.content).toContain("已重试 3 次");
+    expect(platform.sendText).not.toHaveBeenCalled();
+    expect(mockStreamStates.get("sid-network-error")?.finalReplySentTurn).toBe(1);
+    expect(displayCards.has("chat-network-error")).toBe(false);
+  });
+
+  it("falls back to a root-cause text when the error card cannot be updated", async () => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    const platform = mockPlatform("feishu");
+    platform.cardUpdate = vi.fn(async () => {
+      throw new Error("CardKit unavailable");
+    });
+    setSessionPlatform(platform);
+
+    bindChatToSession("sid-error-fallback", "chat-error-fallback");
+    recordLastActiveChat("sid-error-fallback", "chat-error-fallback");
+    sessionInfoMap.set("chat-error-fallback", {
+      sessionId: "sid-error-fallback",
+      turnCount: 1,
+      lastContextTokens: 0,
+      startTime: 0,
+      tool: "ccc",
+    });
+    displayCards.set("chat-error-fallback", {
+      cardId: "card-error-fallback",
+      sequence: 1,
+      cardBusy: false,
+      cardCreatedAt: Date.now(),
+      lastSentContent: "",
+      streamErrorNotified: false,
+      sessionId: "sid-error-fallback",
+      turnCount: 1,
+      dotCount: 0,
+    });
+    mockStreamStates.set("sid-error-fallback", {
+      accumulatedContent: "",
+      finalReply: "",
+      status: "error",
+      turnCount: 1,
+      terminalError: {
+        kind: "network_timeout",
+        title: "网络连接超时",
+        message: "连接模型服务失败，已重试 3 次。",
+        occurredAt: Date.now(),
+      },
+    });
+
+    startUnifiedDisplayLoop();
+    await vi.advanceTimersByTimeAsync(3_000);
+
+    expect(platform.sendText).toHaveBeenCalledWith(
+      "chat-error-fallback",
+      expect.stringContaining("异常结束：网络连接超时"),
+    );
+    expect(displayCards.has("chat-error-fallback")).toBe(false);
+  });
 
   it("does not repeat the same terminal CardKit sequence while the prompt is still active", async () => {
     const platform = mockPlatform("feishu");