chatccc 0.2.49 → 0.2.50

package/package.json

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

package/src/__tests__/cards.test.ts

@@ -380,6 +380,14 @@ describe("buildSessionsCard", () => {
     expect(afterPrivateChat).not.toContain("(群聊)");
   });
 
+  it("shows chat id missing for sessions without a chat binding", () => {
+    const card = buildSessionsCard([
+      { sessionId: "orphan", chatName: "", chatId: "", active: true, turnCount: 0, elapsedSeconds: 3, model: "Claude Opus 4.7", tool: "claude" },
+    ]);
+    const content: string = JSON.parse(card).elements[0].text.content;
+    expect(content).toContain("chat id缺失");
+  });
+
   it("includes /session help text in non-empty card", () => {
     const card = buildSessionsCard([
       { sessionId: "abc123", chatName: "", chatId: "oc_abc123", active: false, turnCount: 2, elapsedSeconds: null, model: "Claude Opus 4.7", tool: "claude" },
@@ -446,4 +454,4 @@ describe("buildButtons", () => {
     const obj = result as any;
     expect(obj.actions[0].type).toBe("primary");
   });
-});
+});

package/src/__tests__/session.test.ts

@@ -26,15 +26,26 @@ import {
   getSessionStatus,
   getAllSessionsStatus,
   recordSessionRegistry,
+  saveSessionTool,
   accumulateBlockContent,
   pickFinalReply,
   UNKNOWN_MODEL_PLACEHOLDER,
   _setSessionRegistryFileForTest,
   _resetSessionRegistryFileForTest,
+  _setSessionToolsFileForTest,
+  _resetSessionToolsFileForTest,
   _setAdapterForToolForTest,
   _clearAdapterCacheForTest,
 } from "../session.ts";
-import { activePrompts } from "../session-chat-binding.ts";
+import {
+  activePrompts,
+  bindChatToSession,
+  unbindChatFromSession,
+  recordLastActiveChat,
+  getLastActiveChat,
+  pickDisplayChat,
+  resetBindingState,
+} from "../session-chat-binding.ts";
 import type { AccumulatorState } from "../session.ts";
 import type { ToolAdapter, UnifiedBlock, SessionInfo } from "../adapters/adapter-interface.ts";
 
@@ -233,6 +244,7 @@ describe("getSessionStatus", () => {
 
 describe("getAllSessionsStatus", () => {
   let registryFile = "";
+  let sessionsFile = "";
 
   beforeEach(async () => {
     chatSessionMap.clear();
@@ -240,12 +252,15 @@ describe("getAllSessionsStatus", () => {
     activePrompts.clear();
     const dir = await mkdtemp(join(tmpdir(), "chatccc-session-registry-"));
     registryFile = join(dir, "session-registry.json");
+    sessionsFile = join(dir, "sessions.json");
     _setSessionRegistryFileForTest(registryFile);
+    _setSessionToolsFileForTest(sessionsFile);
   });
 
   afterEach(async () => {
     _clearAdapterCacheForTest();
     _resetSessionRegistryFileForTest();
+    _resetSessionToolsFileForTest();
     if (registryFile) {
       await rm(dirname(registryFile), { recursive: true, force: true });
     }
@@ -298,6 +313,32 @@ describe("getAllSessionsStatus", () => {
     expect(result[1].chatName).toBe("test-chat-2");
   });
 
+  it("includes recent sessions without a registry chat binding", async () => {
+    await saveSessionTool("orphan-session", "claude");
+    activePrompts.set("orphan-session", {
+      controller: new AbortController(),
+      stopped: false,
+      startTime: 3000,
+    });
+
+    const result = await getAllSessionsStatus();
+    expect(result).toHaveLength(1);
+    expect(result[0].sessionId).toBe("orphan-session");
+    expect(result[0].chatId).toBe("");
+    expect(result[0].active).toBe(true);
+    expect(result[0].turnCount).toBe(0);
+  });
+
+  it("orphan sessions preserve chatName from sessions.json", async () => {
+    await saveSessionTool("orphan-with-name", "claude", "帮我写代码-src");
+    const result = await getAllSessionsStatus();
+    expect(result).toHaveLength(1);
+    expect(result[0].sessionId).toBe("orphan-with-name");
+    expect(result[0].chatId).toBe("");
+    expect(result[0].chatName).toBe("帮我写代码-src");
+    expect(result[0].active).toBe(false);
+  });
+
   it("returns recent disk sessions by updatedAt desc, limited to 20", async () => {
     for (let i = 0; i < 25; i++) {
       await recordSessionRegistry({
@@ -635,3 +676,79 @@ describe("pickFinalReply", () => {
     ).toBe("");
   });
 });
+
+// ---------------------------------------------------------------------------
+// pickDisplayChat — display loop 选择推送目标 chat 的纯函数
+// 关键不变量：仅当某 chatId 既是 session 的"最后活跃 chat"且仍然绑定到该
+// session 时才返回。否则返回 undefined（loop 当作"无活跃群"，不推送）。
+// 这是为了修复 /newh 后旧 session 仍向已解绑群推卡片的 bug。
+// ---------------------------------------------------------------------------
+
+describe("pickDisplayChat", () => {
+  beforeEach(() => {
+    resetBindingState();
+  });
+
+  it("绑定 + 记录活跃后，返回该 chatId", () => {
+    bindChatToSession("sid-A", "chat_X");
+    recordLastActiveChat("sid-A", "chat_X");
+    expect(pickDisplayChat("sid-A")).toBe("chat_X");
+  });
+
+  it("从未记录过活跃 chat 时返回 undefined", () => {
+    bindChatToSession("sid-A", "chat_X");
+    expect(pickDisplayChat("sid-A")).toBeUndefined();
+  });
+
+  it("最后活跃 chat 已被解绑（如 /newh 场景）时返回 undefined，避免向已离开本 session 的群推送", () => {
+    bindChatToSession("sid-A", "chat_X");
+    recordLastActiveChat("sid-A", "chat_X");
+    // 模拟 /newh：chat_X 被解绑，转给新 session
+    unbindChatFromSession("sid-A", "chat_X");
+    expect(pickDisplayChat("sid-A")).toBeUndefined();
+  });
+
+  it("session 仍绑定其他 chat 但 lastActive 是已解绑 chat 时返回 undefined（不应回退到任意绑定）", () => {
+    // 多群共享 session 的极端情况：lastActive 指向 chat_X，但 chat_X 已解绑
+    bindChatToSession("sid-A", "chat_X");
+    bindChatToSession("sid-A", "chat_Y");
+    recordLastActiveChat("sid-A", "chat_X");
+    unbindChatFromSession("sid-A", "chat_X");
+    expect(pickDisplayChat("sid-A")).toBeUndefined();
+  });
+
+  it("session 绑定多个 chat 且 lastActive 是仍绑定的 chat 时正确返回", () => {
+    bindChatToSession("sid-A", "chat_X");
+    bindChatToSession("sid-A", "chat_Y");
+    recordLastActiveChat("sid-A", "chat_Y");
+    expect(pickDisplayChat("sid-A")).toBe("chat_Y");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// unbindChatFromSession — 双保险：清理 lastActiveChatMap[sessionId]
+// 若该 sessionId 的 lastActive 正好指向被解绑的 chatId，则一并清掉，
+// 防止后续逻辑（不仅 display loop）读到悬挂的旧记录。
+// ---------------------------------------------------------------------------
+
+describe("unbindChatFromSession 同步清理 lastActiveChatMap", () => {
+  beforeEach(() => {
+    resetBindingState();
+  });
+
+  it("解绑的 chat 正是 lastActive 时清掉记录", () => {
+    bindChatToSession("sid-A", "chat_X");
+    recordLastActiveChat("sid-A", "chat_X");
+    unbindChatFromSession("sid-A", "chat_X");
+    expect(getLastActiveChat("sid-A")).toBeUndefined();
+  });
+
+  it("解绑的 chat 不是 lastActive 时保留 lastActive", () => {
+    // chat_X 是 lastActive，解绑 chat_Y 不应影响
+    bindChatToSession("sid-A", "chat_X");
+    bindChatToSession("sid-A", "chat_Y");
+    recordLastActiveChat("sid-A", "chat_X");
+    unbindChatFromSession("sid-A", "chat_Y");
+    expect(getLastActiveChat("sid-A")).toBe("chat_X");
+  });
+});

package/src/cards.ts

@@ -294,8 +294,8 @@ export function buildSessionsCard(sessions: Array<{
     }
     const toolLabel = s.tool === "cursor" ? "Cursor" : s.tool === "codex" ? "Codex" : "Claude Code";
     const namePart = s.chatName ? `**${s.chatName}** ` : "";
-    const groupTag = s.chatId && s.chatId.startsWith("oc_") ? " (群聊)" : "";
-    return `**${i + 1}.** ${namePart}${groupTag} \`${shortId}\` ${status} | 工具: ${toolLabel} | 轮数: ${s.turnCount} | ${s.model}${extra}`;
+    const chatTag = !s.chatId ? " (chat id缺失)" : s.chatId.startsWith("oc_") ? " (群聊)" : "";
+    return `**${i + 1}.** ${namePart}${chatTag} \`${shortId}\` ${status} | 工具: ${toolLabel} | 轮数: ${s.turnCount} | ${s.model}${extra}`;
   };
 
   const lines: string[] = [`共 **${sessions.length}** 个会话:`, ""];

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 {
@@ -105,6 +105,7 @@ import {
   stopSession,
   loadSessionRegistryForBinding,
   removeSessionRegistryRecord,
+  saveSessionTool,
 } from "./session.ts";
 import {
   bindChatToSession,
@@ -493,6 +494,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 +544,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 +631,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}`);
         }
@@ -754,6 +758,7 @@ async function handleCommand(text: string, chatId: string, openId: string, msgTi
           startTime: Date.now(),
           running: false,
         });
+        await saveSessionTool(newSessionId, descriptionTool, newName);
 
         setChatAvatar(freshToken, chatId, descriptionTool, "new").catch(() => {});
 
@@ -867,6 +872,7 @@ async function handleCommand(text: string, chatId: string, openId: string, msgTi
           chatName: newName2,
           running: false,
         });
+        await saveSessionTool(target.sessionId, target.tool, newName2);
 
         setChatAvatar(freshToken, chatId, target.tool, "new").catch(() => {});
 
@@ -1405,22 +1411,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 +1437,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";
 
 // ---------------------------------------------------------------------------
@@ -136,11 +137,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 +153,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 +179,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
 // ---------------------------------------------------------------------------
@@ -658,7 +676,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 +921,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(

package/src/shared.ts

@@ -1,17 +1,17 @@
 import { execSync } from "node:child_process";
-import {
-  appendFileSync,
-  existsSync,
-  mkdirSync,
-  readFileSync,
-  unlinkSync,
-  writeFileSync,
-} from "node:fs";
-import { createServer } from "node:http";
-import { homedir } from "node:os";
-import { join } from "node:path";
-import { inspect } from "node:util";
-import { WebSocketServer, WebSocket } from "ws";
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { createServer } from "node:http";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { inspect } from "node:util";
+import { WebSocketServer, WebSocket } from "ws";
 
 import { printServiceDidNotStart } from "./exit-banner.ts";
 
@@ -42,8 +42,11 @@ export function appendStartupTrace(message: string, extra?: Record<string, unkno
 // 进程树：当前进程及其所有祖先（用于避免 taskkill /T 误杀启动链）
 // ---------------------------------------------------------------------------
 
-/** 自当前 PID 沿父链上溯直到系统进程，包含自身 */
+let _cachedAncestorSet: Set<number> | undefined;
+
+/** 自当前 PID 沿父链上溯直到系统进程，包含自身。结果会被缓存，同一进程内多次调用复用。 */
 export function getProcessAncestorPidSet(): Set<number> {
+  if (_cachedAncestorSet) return _cachedAncestorSet;
   const ancestors = new Set<number>();
   let cur: number = process.pid;
   const maxHops = 48;
@@ -74,6 +77,7 @@ export function getProcessAncestorPidSet(): Set<number> {
     if (parent === undefined || Number.isNaN(parent) || parent === cur) break;
     cur = parent;
   }
+  _cachedAncestorSet = ancestors;
   return ancestors;
 }
 
@@ -137,8 +141,9 @@ function collectListeningPidsOnPortWindows(port: number, netstatOut: string): nu
   return out;
 }
 
-/** 在 createRelayServer 之前调用：清掉本机该端口上仍在监听的旧进程（不杀当前进程树祖先） */
-export function freeRelayListenPort(port: number): void {
+/** 在 createRelayServer 之前调用：清掉本机该端口上仍在监听的旧进程（不杀当前进程树祖先）。
+ *  返回实际 kill 的进程数。 */
+export function freeRelayListenPort(port: number): number {
   const ancestors = getProcessAncestorPidSet();
   appendStartupTrace("freeRelayListenPort: begin", {
     port,
@@ -147,9 +152,10 @@ export function freeRelayListenPort(port: number): void {
 
   if (process.platform !== "win32") {
     appendStartupTrace("freeRelayListenPort: skip (non-Windows)", { port });
-    return;
+    return 0;
   }
 
+  let killed = 0;
   try {
     const portOut = execSync(`netstat -ano | findstr :${port}`, { encoding: "utf8", windowsHide: true });
     const pids = collectListeningPidsOnPortWindows(port, portOut);
@@ -159,11 +165,32 @@ export function freeRelayListenPort(port: number): void {
       console.log(`[KILL] Free port ${port}: killing LISTENING/UDP holder PID ${pidNum}...`);
       appendStartupTrace("freeRelayListenPort: killByPid", { port, pid: pidNum });
       killByPid(pidNum);
+      killed++;
     }
   } catch {
     appendStartupTrace("freeRelayListenPort: netstat/findstr (no rows or error)", { port });
   }
-  appendStartupTrace("freeRelayListenPort: end", { port });
+  appendStartupTrace("freeRelayListenPort: end", { port, killed });
+  return killed;
+}
+
+/**
+ * 轮询等待端口释放（Windows 下 taskkill 后端口可能不会立即释放）。
+ * 在 freeRelayListenPort kill 了进程后调用，确认端口真正空闲再 listen。
+ */
+export async function waitForPortFree(port: number, timeoutMs = 3000): Promise<void> {
+  if (process.platform !== "win32") return;
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      const out = execSync(`netstat -ano | findstr :${port}`, { encoding: "utf8", windowsHide: true });
+      const pids = collectListeningPidsOnPortWindows(port, out);
+      if (pids.length === 0) return;
+    } catch {
+      return;
+    }
+    await new Promise((r) => setTimeout(r, 200));
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -355,56 +382,56 @@ export function installCrashLogging(opts: CrashHandlersOptions = {}): InstallCra
 // 文件日志：同时输出到控制台和日志文件
 // ---------------------------------------------------------------------------
 
-export function setupFileLogging(logDir: string, prefix: string): { logPath: string; flush: () => void } {
-  mkdirSync(logDir, { recursive: true });
-  const ts = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
-  const logPath = join(logDir, `${prefix}-${ts}.log`);
-  writeFileSync(logPath, "", { flag: "a", encoding: "utf8" });
-  const origConsoleLog = console.log.bind(console);
-  const origConsoleError = console.error.bind(console);
-  const formatArg = (arg: unknown): string => {
-    if (typeof arg === "string") return arg;
-    if (arg instanceof Error) return arg.stack ?? arg.message;
-    return inspect(arg, { depth: 6, breakLength: Infinity, maxArrayLength: 200 });
-  };
-  const writeLine = (level: string, args: unknown[]) => {
-    try {
-      const line = args.map(formatArg).join(" ");
-      appendFileSync(logPath, `[${new Date().toISOString()}] [${level}] ${line}\n`, "utf8");
-    } catch (err) {
-      try {
-        appendStartupTrace("fileLog write failed", { level, error: err instanceof Error ? err.message : String(err) });
-      } catch {
-        // 日志系统自身不能影响主流程
-      }
-    }
-  };
-  console.log = (...args: unknown[]) => {
-    writeLine("LOG", args);
-    try {
-      origConsoleLog(...args);
-    } catch {
-      // 控制台输出失败也不能拖垮服务
-    }
-  };
-  console.error = (...args: unknown[]) => {
-    writeLine("ERR", args);
-    try {
-      origConsoleError(...args);
-    } catch {
-      // 控制台输出失败也不能拖垮服务
-    }
-  };
-  const flush = () => {
-    try {
-      appendFileSync(logPath, "", "utf8");
-    } catch (err) {
-      appendStartupTrace("fileLog flush failed", { error: err instanceof Error ? err.message : String(err) });
-    }
-  };
-  origConsoleLog(`Log file: ${logPath}`);
-  return { logPath, flush };
-}
+export function setupFileLogging(logDir: string, prefix: string): { logPath: string; flush: () => void } {
+  mkdirSync(logDir, { recursive: true });
+  const ts = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
+  const logPath = join(logDir, `${prefix}-${ts}.log`);
+  writeFileSync(logPath, "", { flag: "a", encoding: "utf8" });
+  const origConsoleLog = console.log.bind(console);
+  const origConsoleError = console.error.bind(console);
+  const formatArg = (arg: unknown): string => {
+    if (typeof arg === "string") return arg;
+    if (arg instanceof Error) return arg.stack ?? arg.message;
+    return inspect(arg, { depth: 6, breakLength: Infinity, maxArrayLength: 200 });
+  };
+  const writeLine = (level: string, args: unknown[]) => {
+    try {
+      const line = args.map(formatArg).join(" ");
+      appendFileSync(logPath, `[${new Date().toISOString()}] [${level}] ${line}\n`, "utf8");
+    } catch (err) {
+      try {
+        appendStartupTrace("fileLog write failed", { level, error: err instanceof Error ? err.message : String(err) });
+      } catch {
+        // 日志系统自身不能影响主流程
+      }
+    }
+  };
+  console.log = (...args: unknown[]) => {
+    writeLine("LOG", args);
+    try {
+      origConsoleLog(...args);
+    } catch {
+      // 控制台输出失败也不能拖垮服务
+    }
+  };
+  console.error = (...args: unknown[]) => {
+    writeLine("ERR", args);
+    try {
+      origConsoleError(...args);
+    } catch {
+      // 控制台输出失败也不能拖垮服务
+    }
+  };
+  const flush = () => {
+    try {
+      appendFileSync(logPath, "", "utf8");
+    } catch (err) {
+      appendStartupTrace("fileLog flush failed", { error: err instanceof Error ? err.message : String(err) });
+    }
+  };
+  origConsoleLog(`Log file: ${logPath}`);
+  return { logPath, flush };
+}
 
 // ---------------------------------------------------------------------------
 // 本地 WebSocket 中继服务器（同一端口、多客户端广播）