chatccc 0.2.81 → 0.2.83

package/package.json

@@ -1,63 +1,63 @@
-{
-  "name": "chatccc",
-  "version": "0.2.81",
-  "description": "Feishu bot bridge for Claude Code",
-  "license": "Apache-2.0",
-  "type": "module",
-  "main": "./src/index.ts",
-  "bin": {
-    "chatccc": "bin/chatccc.mjs"
-  },
-  "files": [
-    "src/",
-    "bin/",
-    "scripts/postinstall-sharp-check.mjs",
-    "demo/ilink_echo_probe.ts",
-    "im-skills/",
-    "images/img_readme_*.jpg",
-    "images/img_readme_*.png",
-    "images/avatars/status_*.png",
-    "images/avatars/badges/",
-    "package.json",
-    "README.md",
-    "config.sample.json"
-  ],
-  "scripts": {
-    "dev": "tsx src/index.ts",
-    "chatccc": "tsx src/index.ts",
-    "start": "tsx src/index.ts",
-    "demo:bot-test": "tsx demo/bot_test.ts",
-    "demo:bot-test:local": "tsx demo/bot_test.ts --local",
-    "demo:create-group": "tsx src/index.ts",
-    "demo:create-group:local": "tsx src/index.ts --local",
-    "demo:permission-check": "tsx demo/permission_check.ts",
-    "demo:claude-hi": "tsx demo/claude_say_hi.ts",
-    "demo:codex-hi": "tsx demo/codex_say_hi.ts",
-    "demo:ilink-echo": "tsx demo/ilink_echo_probe.ts",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "postinstall": "node scripts/postinstall-sharp-check.mjs"
-  },
-  "dependencies": {
-    "@ai-sdk/openai-compatible": "^2.0.47",
-    "@anthropic-ai/claude-agent-sdk": "0.2.133",
-    "@larksuiteoapi/node-sdk": "^1.59.0",
-    "@openilink/openilink-sdk-node": "^0.6.0",
-    "ai": "^6.0.184",
-    "nodemailer": "^8.0.7",
-    "qrcode-terminal": "^0.12.0",
-    "sharp": "^0.34.5",
-    "tsx": "^4.0.0",
-    "ws": "^8.18.0"
-  },
-  "devDependencies": {
-    "@types/node": "^20.0.0",
-    "@types/qrcode-terminal": "^0.12.2",
-    "@types/ws": "^8.18.1",
-    "typescript": "^5.0.0",
-    "vitest": "^3.2.4"
-  },
-  "engines": {
-    "node": ">=20"
-  }
-}
+{
+  "name": "chatccc",
+  "version": "0.2.83",
+  "description": "Feishu bot bridge for Claude Code",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./src/index.ts",
+  "bin": {
+    "chatccc": "bin/chatccc.mjs"
+  },
+  "files": [
+    "src/",
+    "bin/",
+    "scripts/postinstall-sharp-check.mjs",
+    "demo/ilink_echo_probe.ts",
+    "im-skills/",
+    "images/img_readme_*.jpg",
+    "images/img_readme_*.png",
+    "images/avatars/status_*.png",
+    "images/avatars/badges/",
+    "package.json",
+    "README.md",
+    "config.sample.json"
+  ],
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "chatccc": "tsx src/index.ts",
+    "start": "tsx src/index.ts",
+    "demo:bot-test": "tsx demo/bot_test.ts",
+    "demo:bot-test:local": "tsx demo/bot_test.ts --local",
+    "demo:create-group": "tsx src/index.ts",
+    "demo:create-group:local": "tsx src/index.ts --local",
+    "demo:permission-check": "tsx demo/permission_check.ts",
+    "demo:claude-hi": "tsx demo/claude_say_hi.ts",
+    "demo:codex-hi": "tsx demo/codex_say_hi.ts",
+    "demo:ilink-echo": "tsx demo/ilink_echo_probe.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "postinstall": "node scripts/postinstall-sharp-check.mjs"
+  },
+  "dependencies": {
+    "@ai-sdk/openai-compatible": "^2.0.47",
+    "@anthropic-ai/claude-agent-sdk": "0.2.133",
+    "@larksuiteoapi/node-sdk": "^1.59.0",
+    "@openilink/openilink-sdk-node": "^0.6.0",
+    "ai": "^6.0.184",
+    "nodemailer": "^8.0.7",
+    "qrcode-terminal": "^0.12.0",
+    "sharp": "^0.34.5",
+    "tsx": "^4.0.0",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/qrcode-terminal": "^0.12.2",
+    "@types/ws": "^8.18.1",
+    "typescript": "^5.0.0",
+    "vitest": "^3.2.4"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/src/__tests__/proc-tree-kill.test.ts

@@ -0,0 +1,108 @@
+// =============================================================================
+// proc-tree-kill.test.ts — 进程树强杀工具单测护栏
+// =============================================================================
+// 目的：覆盖 codex/cursor adapter 之前 proc.kill() 在 Windows + shell:true 下
+//      只杀第一层 cmd.exe 壳、留下 node + 真二进制成"幽灵"的 bug。
+// 测试构造一棵三层进程树（祖父 cmd/sh → 父 node → 子 sleep 进程），
+// 用 killProcessTree 杀掉祖父 PID，断言整棵树都不存在了。
+// =============================================================================
+
+import { describe, it, expect } from "vitest";
+import { spawn } from "node:child_process";
+import { join } from "node:path";
+import { writeFileSync, unlinkSync, existsSync, mkdtempSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { killProcessTree } from "../adapters/proc-tree-kill.ts";
+
+function isAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function sleep(ms: number): Promise<void> {
+  await new Promise((r) => setTimeout(r, ms));
+}
+
+describe("killProcessTree", () => {
+  it("kills a 3-level process tree (shell wrapper + node child + node grandchild)", async () => {
+    // 用临时脚本模拟 codex CLI 的真实拓扑：
+    //   layer-1: shell (cmd.exe / sh) — 因为 spawn 用了 shell:true
+    //     layer-2: node 进程 — 模拟 `node codex.js` 入口
+    //       layer-3: 又一个 node 进程 — 模拟真正干活的 codex.exe 子进程
+    const tmp = mkdtempSync(join(tmpdir(), "chatccc-proctree-"));
+    const childScript = join(tmp, "child.mjs");
+    const pidFile = join(tmp, "grand.pid");
+    const isWin = process.platform === "win32";
+
+    writeFileSync(
+      childScript,
+      [
+        `import { spawn } from "node:child_process";`,
+        `import { writeFileSync } from "node:fs";`,
+        // 启动孙进程：再开一个 node，跑一个 10 分钟的 setTimeout 占位
+        `const grand = spawn(process.execPath, ["-e", "setTimeout(()=>{},600000)"], { stdio: "ignore", detached: false });`,
+        `writeFileSync(${JSON.stringify(pidFile)}, String(grand.pid));`,
+        // 父进程自己也挂住别退出
+        `setTimeout(()=>{}, 600000);`,
+      ].join("\n"),
+      "utf8",
+    );
+
+    // 启动祖父：复现 codex-adapter 用 shell:true 的方式
+    // 路径必须加引号，否则 cmd.exe 把空格当分隔符
+    const proc = spawn(`"${process.execPath}" "${childScript}"`, {
+      stdio: "ignore",
+      shell: true,
+      windowsHide: true,
+      detached: !isWin,
+    });
+
+    expect(proc.pid).toBeGreaterThan(0);
+
+    // 等待孙进程 pid 被写出来（pidFile 出现表示中间 node 已成功 spawn 孙子）
+    let grandPid = 0;
+    for (let i = 0; i < 100; i++) {
+      if (existsSync(pidFile)) {
+        const s = readFileSync(pidFile, "utf8").trim();
+        if (s && /^\d+$/.test(s)) {
+          grandPid = parseInt(s, 10);
+          break;
+        }
+      }
+      await sleep(100);
+    }
+    expect(grandPid).toBeGreaterThan(0);
+    expect(isAlive(grandPid)).toBe(true);
+
+    // 杀祖父（在 shell:true 时 proc.pid 就是 cmd.exe / sh 那一层）。
+    // 关键断言：如果 killProcessTree 没有 /T 递归，grandPid 会留下来。
+    await killProcessTree(proc.pid!);
+
+    for (let i = 0; i < 50; i++) {
+      if (!isAlive(grandPid)) break;
+      await sleep(100);
+    }
+
+    expect(isAlive(grandPid)).toBe(false);
+    expect(isAlive(proc.pid!)).toBe(false);
+
+    try {
+      unlinkSync(childScript);
+      if (existsSync(pidFile)) unlinkSync(pidFile);
+    } catch {
+      // 忽略清理失败
+    }
+  }, 30000);
+
+  it("does not throw when pid does not exist", async () => {
+    await expect(killProcessTree(999999)).resolves.toBeUndefined();
+  });
+
+  it("does not throw when pid is undefined", async () => {
+    await expect(killProcessTree(undefined)).resolves.toBeUndefined();
+  });
+});

package/src/__tests__/stop-session.test.ts

@@ -0,0 +1,126 @@
+// =============================================================================
+// stop-session.test.ts — stopSession 单测护栏
+// =============================================================================
+// 覆盖修复"幽灵 codex 会话"的两条关键行为：
+// 1) controller.abort() 必须被触发（让 adapter finally 走 killProcessTree）
+// 2) 立刻把 stream-state.status 改成 stopped，不依赖 runAgentSession 的 finally
+//    （那个 finally 要等 generator 自然结束，子进程没死透就一直停在 running）
+// =============================================================================
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import type { StreamState } from "../stream-state.ts";
+
+// mock stream-state，使用模块内可观测的 Map 记录读写
+const stateStore = new Map<string, StreamState>();
+const writeCalls: StreamState[] = [];
+
+vi.mock("../stream-state.ts", () => ({
+  readStreamState: async (sid: string): Promise<StreamState | null> => {
+    return stateStore.get(sid) ?? null;
+  },
+  writeStreamState: async (state: StreamState): Promise<void> => {
+    writeCalls.push(structuredClone(state));
+    stateStore.set(state.sessionId, state);
+  },
+  createEmptyStreamState: (sid: string, cwd: string, tool: string, turnCount: number) => ({
+    sessionId: sid,
+    status: "running" as const,
+    accumulatedContent: "",
+    finalReply: "",
+    chunkCount: 0,
+    turnCount,
+    contextTokens: 0,
+    updatedAt: Date.now(),
+    cwd,
+    tool,
+  }),
+  fixStaleStreamStates: async () => {},
+  STREAMS_DIR: "/tmp/streams-mock",
+}));
+
+import { stopSession } from "../session.ts";
+import { activePrompts } from "../session-chat-binding.ts";
+
+function seedRunningSession(sid: string, accumulated = "partial output"): AbortController {
+  const controller = new AbortController();
+  activePrompts.set(sid, { controller, stopped: false, startTime: Date.now() });
+  stateStore.set(sid, {
+    sessionId: sid,
+    status: "running",
+    accumulatedContent: accumulated,
+    finalReply: "",
+    chunkCount: 1,
+    turnCount: 1,
+    contextTokens: 0,
+    updatedAt: Date.now(),
+    cwd: "F:/repo",
+    tool: "codex",
+  });
+  return controller;
+}
+
+async function flush(): Promise<void> {
+  // 让 stopSession 内 fire-and-forget 的 microtask 跑完
+  for (let i = 0; i < 5; i++) {
+    await Promise.resolve();
+  }
+  await new Promise((r) => setTimeout(r, 10));
+}
+
+beforeEach(() => {
+  activePrompts.clear();
+  stateStore.clear();
+  writeCalls.length = 0;
+});
+
+describe("stopSession 行为护栏", () => {
+  it("没有活跃 session 时返回 false，不做任何事", async () => {
+    const ok = stopSession("nonexistent");
+    expect(ok).toBe(false);
+    await flush();
+    expect(writeCalls).toHaveLength(0);
+  });
+
+  it("abort controller + 立刻把 stream-state.status 写成 stopped", async () => {
+    const controller = seedRunningSession("sid-A", "hello world");
+    let aborted = false;
+    controller.signal.addEventListener("abort", () => { aborted = true; });
+
+    const ok = stopSession("sid-A");
+    expect(ok).toBe(true);
+    expect(aborted).toBe(true);
+
+    await flush();
+
+    // 关键护栏：必须有一次 writeStreamState 把 status 改成 stopped
+    expect(writeCalls.length).toBeGreaterThanOrEqual(1);
+    const lastWrite = writeCalls[writeCalls.length - 1];
+    expect(lastWrite.sessionId).toBe("sid-A");
+    expect(lastWrite.status).toBe("stopped");
+    // 累积内容不丢
+    expect(lastWrite.accumulatedContent).toBe("hello world");
+  });
+
+  it("已经是终态(done/stopped/error)的 stream-state 不会被覆盖", async () => {
+    seedRunningSession("sid-B");
+    // 模拟 generator finally 已经先写了 done
+    stateStore.set("sid-B", {
+      ...stateStore.get("sid-B")!,
+      status: "done",
+    });
+
+    const ok = stopSession("sid-B");
+    expect(ok).toBe(true);
+    await flush();
+
+    // 不应再有 stopped 覆盖 done 的写入
+    const stoppedWrites = writeCalls.filter((w) => w.status === "stopped");
+    expect(stoppedWrites).toHaveLength(0);
+  });
+
+  it("activePrompts 标记 stopped=true", async () => {
+    seedRunningSession("sid-C");
+    stopSession("sid-C");
+    expect(activePrompts.get("sid-C")?.stopped).toBe(true);
+  });
+});

package/src/adapters/codex-adapter.ts

@@ -22,6 +22,7 @@ import {
   defaultCodexSessionMetaStore,
   type CodexSessionMetaStore,
 } from "./codex-session-meta-store.ts";
+import { killProcessTree } from "./proc-tree-kill.ts";
 import { config } from "../config.ts";
 
 // ---------------------------------------------------------------------------
@@ -192,15 +193,23 @@ async function* readJsonLines(
   signal?: AbortSignal,
 ): AsyncGenerator<CodexEvent> {
   const rl = createInterface({ input: proc.stdout!, crlfDelay: Infinity });
-  for await (const line of rl) {
-    if (signal?.aborted) break;
-    const trimmed = line.trim();
-    if (!trimmed) continue;
-    try {
-      yield JSON.parse(trimmed) as CodexEvent;
-    } catch {
-      // 非 JSON 行静默跳过（如 "Reading prompt from stdin..."）
+  // abort 时主动 close readline，避免等待 Windows 管道自然关闭（可能延迟数分钟）
+  const onAbort = () => { rl.close(); };
+  signal?.addEventListener("abort", onAbort, { once: true });
+  try {
+    for await (const line of rl) {
+      if (signal?.aborted) break;
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      try {
+        yield JSON.parse(trimmed) as CodexEvent;
+      } catch {
+        // 非 JSON 行静默跳过（如 "Reading prompt from stdin..."）
+      }
     }
+  } finally {
+    signal?.removeEventListener("abort", onAbort);
+    rl.close();
   }
 }
 
@@ -242,14 +251,17 @@ class CodexAdapter implements ToolAdapter {
 
     const proc = spawnCodex(args, cwd, userText);
 
-    const onAbort = () => { proc.kill(); };
+    // 关键：spawn 用了 shell:true，proc.pid 指向的是壳进程（cmd.exe / sh）。
+    // 真正干活的是壳的孙子 codex.exe。普通 proc.kill() 在 Windows 上只杀第一层，
+    // 会留下幽灵 node + codex.exe 继续烧 token、stream-state 永远停在 running。
+    // 因此 abort 与 finally 都必须用 killProcessTree 整棵进程树一起收尸。
+    const onAbort = () => { void killProcessTree(proc.pid); };
     signal?.addEventListener("abort", onAbort, { once: true });
 
     try {
       for await (const raw of readJsonLines(proc, signal)) {
         if (signal?.aborted) break;
 
-        // 首次 prompt 时从 thread.started 事件学习 threadId
         if (
           isFirstPrompt &&
           raw.type === "thread.started" &&
@@ -265,7 +277,7 @@ class CodexAdapter implements ToolAdapter {
       }
     } finally {
       signal?.removeEventListener("abort", onAbort);
-      proc.kill();
+      await killProcessTree(proc.pid);
     }
   }
 

package/src/adapters/cursor-adapter.ts

@@ -20,6 +20,7 @@ import {
   defaultCursorSessionMetaStore,
   type CursorSessionMetaStore,
 } from "./cursor-session-meta-store.ts";
+import { killProcessTree } from "./proc-tree-kill.ts";
 
 // ---------------------------------------------------------------------------
 // 类型：Cursor JSONL 消息行
@@ -288,13 +289,21 @@ async function* readJsonLines(
   signal?: AbortSignal,
 ): AsyncGenerator<CursorMessageLine> {
   const rl = createInterface({ input: proc.stdout!, crlfDelay: Infinity });
-  for await (const line of rl) {
-    if (signal?.aborted) break;
-    const trimmed = line.trim();
-    if (!trimmed) continue;
-    try {
-      yield JSON.parse(trimmed) as CursorMessageLine;
-    } catch { /* 非 JSON 行静默跳过 */ }
+  // abort 时主动 close readline，避免等待 Windows 管道自然关闭（可能延迟数分钟）
+  const onAbort = () => { rl.close(); };
+  signal?.addEventListener("abort", onAbort, { once: true });
+  try {
+    for await (const line of rl) {
+      if (signal?.aborted) break;
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      try {
+        yield JSON.parse(trimmed) as CursorMessageLine;
+      } catch { /* 非 JSON 行静默跳过 */ }
+    }
+  } finally {
+    signal?.removeEventListener("abort", onAbort);
+    rl.close();
   }
 }
 
@@ -319,20 +328,16 @@ class CursorAdapter implements ToolAdapter {
     for await (const msg of readJsonLines(proc)) {
       if (msg.type === "system" && msg.subtype === "init" && msg.session_id) {
         const sessionId = msg.session_id;
-        // 持久化 sessionId → { cwd, model }：getSessionInfo 后续依赖此映射，
-        // 否则 Cursor 会话上的 /git、/status、/sessions 等命令将无法显示
-        // 真实工作目录与真实模型。优先用 init 事件自报字段（cursor-agent
-        // 内部权威），cwd 没有时退回调用方传入的 cwd 兜底。
         await this.metaStore
           .set(sessionId, { cwd: msg.cwd ?? cwd, model: msg.model })
           .catch(() => {});
         this.activeProcs.delete(proc);
-        proc.kill();
+        await killProcessTree(proc.pid);
         return { sessionId };
       }
     }
 
-    proc.kill();
+    await killProcessTree(proc.pid);
     this.activeProcs.delete(proc);
     throw new Error("No session ID in Cursor init event");
   }
@@ -346,16 +351,14 @@ class CursorAdapter implements ToolAdapter {
     const proc = spawnAgent(["--resume", sessionId], cwd, userText);
     this.activeProcs.add(proc);
 
-    const onAbort = () => { proc.kill(); };
+    // 见 codex-adapter.ts 同位置注释：spawn 用了 shell:true，必须杀整棵树，
+    // 否则 abort 后真正在跑的孙进程 cursor-agent 还会继续输出 & 占用资源。
+    const onAbort = () => { void killProcessTree(proc.pid); };
     signal?.addEventListener("abort", onAbort, { once: true });
 
     try {
       for await (const raw of readJsonLines(proc, signal)) {
         if (signal?.aborted) break;
-        // 自动学习：resume 流首条 init 事件若带 cwd / model，更新映射。
-        // 这是为升级前创建的旧会话或映射文件意外丢失的情况兜底——
-        // 用户向旧会话发一次消息后，/git、/status 等即可正常显示。
-        // fire-and-forget：写失败不影响流式输出。
         if (
           raw.type === "system" &&
           raw.subtype === "init" &&
@@ -371,7 +374,7 @@ class CursorAdapter implements ToolAdapter {
       }
     } finally {
       signal?.removeEventListener("abort", onAbort);
-      proc.kill();
+      await killProcessTree(proc.pid);
       this.activeProcs.delete(proc);
     }
   }

package/src/adapters/proc-tree-kill.ts

@@ -0,0 +1,97 @@
+// =============================================================================
+// proc-tree-kill.ts — 跨平台进程树强杀工具
+// =============================================================================
+// 背景：codex / cursor adapter 通过 `spawn(cmd, args, { shell: true })` 启动 CLI
+// 时，Node 拿到的 proc.pid 是最外层 cmd.exe（Windows）或 /bin/sh（其它）的
+// PID。真正干活的是它再 spawn 出来的：
+//
+//     cmd.exe              ← proc.kill() 只能杀到这一层
+//       └─ node codex.js   ← Codex CLI 入口
+//            └─ codex.exe  ← 实际 Rust 二进制（继续烧 token）
+//
+// 单纯 proc.kill() 在 Windows 上等价于 TerminateProcess 顶层壳，孙子进程不会
+// 收到任何信号、继续运行，导致用户 /stop 看似生效（adapter 标记 stopped）但
+// 实际 codex 仍在后台跑、stream-state 一直停在 "running"。
+//
+// 解决方案：abort 时不要走 proc.kill()，而是用本工具按 pid 杀掉整棵进程树。
+//   - Windows: `taskkill /pid <pid> /T /F`（/T = 递归子进程, /F = 强制）
+//   - 其它：`process.kill(-pgid, "SIGTERM")` + 兜底 SIGKILL（adapter spawn 时
+//           需配合 detached:true 让子进程拥有独立 process group）
+// =============================================================================
+
+import { spawn } from "node:child_process";
+
+/** 异步杀掉以 pid 为根的整棵进程树。
+ *
+ * 设计目标：永不抛错、永不阻塞调用者。
+ * - pid 不存在、参数缺失 → 静默返回
+ * - 子进程 spawn 失败 → console.warn 但不 reject
+ * - Windows 上 taskkill 异步执行，不阻塞 event loop
+ *
+ * 调用方约定：返回的 Promise 在 kill 命令发出后立即 resolve。
+ * 真正的进程退出由 OS 异步完成，调用方如果需要确认"已死透"，应自己再轮询
+ * `process.kill(pid, 0)`。
+ */
+export async function killProcessTree(pid: number | undefined): Promise<void> {
+  if (pid == null || !Number.isFinite(pid) || pid <= 0) return;
+  if (process.platform === "win32") {
+    await killWindowsTree(pid);
+    return;
+  }
+  await killPosixTree(pid);
+}
+
+// ---------------------------------------------------------------------------
+// Windows: taskkill /T /F
+// ---------------------------------------------------------------------------
+
+function killWindowsTree(pid: number): Promise<void> {
+  return new Promise<void>((resolve) => {
+    let resolved = false;
+    const done = () => {
+      if (resolved) return;
+      resolved = true;
+      resolve();
+    };
+    try {
+      const proc = spawn("taskkill", ["/pid", String(pid), "/T", "/F"], {
+        stdio: "ignore",
+        windowsHide: true,
+        // taskkill 本身很快（<200ms），不需要 detached
+      });
+      proc.once("error", (err) => {
+        console.warn(`[killProcessTree] taskkill spawn error for pid=${pid}: ${(err as Error).message}`);
+        done();
+      });
+      proc.once("close", () => { done(); });
+      // 兜底超时：3 秒后强制 resolve，避免极端情况下 hang 住调用方
+      setTimeout(done, 3000).unref();
+    } catch (err) {
+      console.warn(`[killProcessTree] taskkill failed for pid=${pid}: ${(err as Error).message}`);
+      done();
+    }
+  });
+}
+
+// ---------------------------------------------------------------------------
+// POSIX: 优先按 process group 杀，回退到按 pid 杀
+// ---------------------------------------------------------------------------
+
+async function killPosixTree(pid: number): Promise<void> {
+  // 第一次尝试：按 process group 发 SIGTERM。要求 spawn 时 detached:true。
+  trySignal(-pid, "SIGTERM");
+  trySignal(pid, "SIGTERM");
+  // 给进程 1 秒优雅退出机会
+  await new Promise((r) => setTimeout(r, 1000));
+  // 兜底：SIGKILL
+  trySignal(-pid, "SIGKILL");
+  trySignal(pid, "SIGKILL");
+}
+
+function trySignal(target: number, signal: NodeJS.Signals): void {
+  try {
+    process.kill(target, signal);
+  } catch {
+    // 进程已不存在或权限不足，忽略
+  }
+}

package/src/session.ts

@@ -1250,7 +1250,18 @@ export function ensureDisplayLoop(sessionId: string): void {
 // ---------------------------------------------------------------------------
 // stopSession — 停止指定 session 的活跃 prompt
 // ---------------------------------------------------------------------------
-
+//
+// 设计要点：
+// 1) controller.abort() 触发 adapter finally 里的 killProcessTree(proc.pid)，
+//    后者负责把整棵 CLI 进程树（cmd.exe 壳 + node CLI 入口 + 真二进制）一起
+//    收尸；之前用 proc.kill() 在 Windows + shell:true 下只能杀第一层 cmd.exe，
+//    会留下"幽灵 CLI 子进程"继续跑、stream-state 永远停在 running。
+//
+// 2) 立刻 fire-and-forget 把 stream-state 标 stopped，不依赖 runAgentSession
+//    的 finally。原因：generator 自然结束依赖子进程 stdout 关闭，killProcessTree
+//    虽然很快但仍是异步，期间 display loop 可能多读到 1–2 帧 "running"，
+//    用户体验上"按下停止后还要等几秒卡片才变成已停止"。先把状态标好，
+//    finally 后续再写一次也不冲突——status 最终值仍然是 stopped。
 export function stopSession(sessionId: string): boolean {
   const prompt = activePrompts.get(sessionId);
   if (!prompt) return false;
@@ -1258,6 +1269,27 @@ export function stopSession(sessionId: string): boolean {
   cancelQueuedMessage(sessionId);
   prompt.controller.abort();
   console.log(`[${ts()}] [STOP] Session ${sessionId} aborted`);
+
+  // fire-and-forget：立刻把 stream-state.status 改成 stopped，
+  // 让 display loop 下一次扫到立刻渲染"已停止"卡片，不必再等几秒。
+  void (async () => {
+    try {
+      const current = await readStreamState(sessionId);
+      if (!current) return;
+      // 已经是终态就别再覆盖，避免把 done/error 误改成 stopped
+      if (current.status !== "running") return;
+      await writeStreamState({
+        ...current,
+        status: "stopped",
+        updatedAt: Date.now(),
+      });
+    } catch (err) {
+      console.warn(
+        `[${ts()}] [STOP] writeStreamState(stopped) failed for ${sessionId}: ${(err as Error).message}`,
+      );
+    }
+  })();
+
   return true;
 }