chatccc 0.2.208 → 0.2.209

package/package.json

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

package/src/__tests__/startup-lifecycle.test.ts

@@ -3,6 +3,7 @@ import { describe, expect, it, vi } from "vitest";
 import {
   INTERNAL_RESTART_ENV_VAR,
   buildWebUiUrl,
+  createServiceLifecycleGuard,
   createInternalRestartEnv,
   openWebUiInDefaultBrowser,
   shouldAutoOpenWebUi,
@@ -96,3 +97,135 @@ describe("ChatCCC startup lifecycle", () => {
     expect(onInfo).toHaveBeenCalledWith(expect.stringContaining("http://localhost:18080/"));
   });
 });
+
+describe("ChatCCC service lifecycle guard", () => {
+  function createHarness() {
+    let intervalCallback: (() => void) | undefined;
+    const timer = { ref: vi.fn() };
+    const setIntervalImpl = vi.fn((callback: () => void) => {
+      intervalCallback = callback;
+      return timer;
+    });
+    const clearIntervalImpl = vi.fn();
+    const tracer = vi.fn();
+    const server = {
+      listening: true,
+      address: vi.fn(() => ({ address: "127.0.0.1", port: 18080 })),
+      ref: vi.fn(),
+    };
+    const recoverServer = vi.fn(async () => {
+      server.listening = true;
+    });
+    const guard = createServiceLifecycleGuard({
+      intervalMs: 10_000,
+      setIntervalImpl,
+      clearIntervalImpl,
+      tracer,
+      getActiveResourcesInfo: () => ["TCPServerWrap", "Timeout"],
+    });
+
+    return {
+      clearIntervalImpl,
+      getIntervalCallback: () => intervalCallback,
+      guard,
+      recoverServer,
+      server,
+      setIntervalImpl,
+      timer,
+      tracer,
+    };
+  }
+
+  it("starts exactly one referenced keep-alive timer", () => {
+    const h = createHarness();
+
+    h.guard.start();
+    h.guard.start();
+
+    expect(h.setIntervalImpl).toHaveBeenCalledOnce();
+    expect(h.setIntervalImpl).toHaveBeenCalledWith(expect.any(Function), 10_000);
+    expect(h.timer.ref).toHaveBeenCalledOnce();
+  });
+
+  it("keeps a listening HTTP server referenced", async () => {
+    const h = createHarness();
+    h.guard.attachServer(h.server, h.recoverServer);
+    h.guard.start();
+
+    await h.guard.checkNow();
+
+    expect(h.server.ref).toHaveBeenCalled();
+    expect(h.recoverServer).not.toHaveBeenCalled();
+  });
+
+  it("coalesces concurrent recovery when the HTTP server is not listening", async () => {
+    const h = createHarness();
+    h.server.listening = false;
+    let finishRecovery: (() => void) | undefined;
+    h.recoverServer.mockImplementation(() => new Promise<void>((resolve) => {
+      finishRecovery = () => {
+        h.server.listening = true;
+        resolve();
+      };
+    }));
+    h.guard.attachServer(h.server, h.recoverServer);
+    h.guard.start();
+
+    const first = h.guard.checkNow();
+    const second = h.guard.checkNow();
+    await Promise.resolve();
+    expect(h.recoverServer).toHaveBeenCalledOnce();
+
+    finishRecovery?.();
+    await Promise.all([first, second]);
+    expect(h.tracer).toHaveBeenCalledWith(
+      "service-lifecycle: HTTP server recovered",
+      expect.objectContaining({ serverListening: true }),
+    );
+  });
+
+  it("re-arms on unexpected beforeExit and records public diagnostics", async () => {
+    const h = createHarness();
+    h.guard.attachServer(h.server, h.recoverServer);
+
+    h.guard.handleBeforeExit(0);
+    await h.guard.checkNow();
+
+    expect(h.setIntervalImpl).toHaveBeenCalledOnce();
+    expect(h.server.ref).toHaveBeenCalled();
+    expect(h.tracer).toHaveBeenCalledWith(
+      "service-lifecycle: unexpected beforeExit",
+      expect.objectContaining({
+        code: 0,
+        activeResources: ["TCPServerWrap", "Timeout"],
+        serverListening: true,
+      }),
+    );
+  });
+
+  it("stays stopped after an intentional shutdown", () => {
+    const h = createHarness();
+    h.guard.start();
+
+    h.guard.beginShutdown("SIGTERM");
+    h.guard.handleBeforeExit(0);
+
+    expect(h.clearIntervalImpl).toHaveBeenCalledWith(h.timer);
+    expect(h.setIntervalImpl).toHaveBeenCalledOnce();
+    expect(h.tracer).toHaveBeenCalledWith(
+      "service-lifecycle: shutdown requested",
+      { reason: "SIGTERM" },
+    );
+  });
+
+  it("the timer callback runs a health check", async () => {
+    const h = createHarness();
+    h.guard.attachServer(h.server, h.recoverServer);
+    h.guard.start();
+
+    h.getIntervalCallback()?.();
+    await Promise.resolve();
+
+    expect(h.server.ref).toHaveBeenCalled();
+  });
+});

package/src/index.ts

@@ -31,6 +31,7 @@ import { appendStartupTrace, attachRelayWebSocket, ensureSingleInstance, freeRel
 import { createUiRouter, setExtraApiHandler, setReloadConfigHook, startSetupMode } from "./web-ui.ts";
 import {
   buildWebUiUrl,
+  createServiceLifecycleGuard,
   openWebUiInDefaultBrowser,
   shouldAutoOpenWebUi,
 } from "./startup-lifecycle.ts";
@@ -744,10 +745,19 @@ async function main(): Promise<void> {
     autoOpenWebUi,
   });
 
-  // 黑匣子：所有未捕获异常 / 信号 / beforeExit 都同步写入 startup-trace.log（appendFileSync）。
+  // ChatCCC 是常驻服务，不能把“当前刚好有没有 Agent session”当作进程生命周期。
+  // referenced timer 明确锚定服务进程；HTTP Server 接入后还会定期 ref/健康检查。
+  // `/restart`、`/update` 都使用 process.exit()，不会被 timer 阻止。
+  const serviceLifecycle = createServiceLifecycleGuard({ tracer: appendStartupTrace });
+  serviceLifecycle.start();
+
+  // 黑匣子：所有未捕获异常 / 信号 / beforeExit 都同步写入 startup-trace.log（appendFileSync）。
   // 越早装越好——后续任何一行抛错都有兜底；它独立于 SIGINT 清理（见末尾的
   // server.close）——只负责诊断与默认致命退出，不替代清理逻辑。
-  installCrashLogging({ flush: () => fileLog.flush() });
+  installCrashLogging({
+    flush: () => fileLog.flush(),
+    onBeforeExit: (code) => serviceLifecycle.handleBeforeExit(code),
+  });
 
   // 模拟模式：独立端口 18079，不与 SDK 实例冲突，不走飞书凭证/权限/WSClient
   if (USE_SIMULATE) {
@@ -787,10 +797,14 @@ async function main(): Promise<void> {
       simServer.once("error", onError);
       simServer.once("listening", onListening);
       simServer.listen(SIM_PORT, "127.0.0.1");
-    }).catch((err: NodeJS.ErrnoException) => {
+    }).catch((err: NodeJS.ErrnoException) => {
       console.error(`\n[启动] 监听失败：端口 ${SIM_PORT}（${err.code ?? "?"} — ${err.message}）`);
-      process.exit(1);
-    });
+      process.exit(1);
+    });
+    serviceLifecycle.attachServer(
+      simServer,
+      () => recoverHttpServer(simServer, SIM_PORT),
+    );
 
     console.log(`\n${"=".repeat(60)}`);
     console.log(`  ChatCCC — 模拟飞书环境模式`);
@@ -808,8 +822,8 @@ async function main(): Promise<void> {
       );
     }
 
-    installShutdownHandlers(simServer);
-    return;
+    installShutdownHandlers(simServer, serviceLifecycle);
+    return;
   }
 
   if (Number.isNaN(CHATCCC_PORT) || CHATCCC_PORT < 1 || CHATCCC_PORT > 65535) {
@@ -856,7 +870,7 @@ async function main(): Promise<void> {
     if (!APP_ID.trim() || !APP_SECRET.trim()) {
       // 凭证不全：进 setup 向导。注入 onActivate 回调让用户点"保存并启动"
       // 时，原地（同进程）调用 startBotService，复用 setup HTTP server。
-      startSetupMode(CHATCCC_PORT, {
+      const setupServer = startSetupMode(CHATCCC_PORT, {
         openBrowser: autoOpenWebUi,
         onActivate: async (httpServer: Server) => {
           reloadRuntimeConfig("setup-activate");
@@ -865,17 +879,23 @@ async function main(): Promise<void> {
           });
           try {
             await startConfiguredPlatforms(httpServer, { failOnFeishuError: true });
-            installShutdownHandlers(httpServer);
-            return { ok: true };
+            return { ok: true };
           } catch (err) {
             appendStartupTrace("setup-activate: startConfiguredPlatforms failed", {
               message: (err as Error).message,
             });
             return { ok: false, error: (err as Error).message };
           }
-        },
-      });
-      return;
+        },
+      });
+      setupServer.once("listening", () => {
+        serviceLifecycle.attachServer(
+          setupServer,
+          () => recoverHttpServer(setupServer, CHATCCC_PORT),
+        );
+      });
+      installShutdownHandlers(setupServer, serviceLifecycle);
+      return;
     }
     console.log(`  必填项校验通过（App ID 摘要: ${maskAppId(APP_ID)}）。\n`);
     appendStartupTrace("main: feishu credentials ok", { appIdMask: maskAppId(APP_ID) });
@@ -903,6 +923,13 @@ async function main(): Promise<void> {
     printServiceDidNotStart(`本地中继端口 ${CHATCCC_PORT} 无法监听（${err.code ?? "?"} — ${err.message}）`);
     process.exit(1);
   });
+  serviceLifecycle.attachServer(
+    httpServer,
+    () => recoverHttpServer(httpServer, CHATCCC_PORT),
+  );
+  // 平台鉴权/长连接启动可能耗时；此时也必须允许 Ctrl+C / SIGTERM 正常退出，
+  // 不能只留下更早安装的信号日志 listener 把默认退出行为吞掉。
+  installShutdownHandlers(httpServer, serviceLifecycle);
 
   // 必须等 HTTP server 真正监听后再发起打开请求，避免浏览器先到一步看到
   // ERR_CONNECTION_REFUSED。Chrome CDP 守护仍保持自己原有的独立行为。
@@ -923,9 +950,23 @@ async function main(): Promise<void> {
   }
 
   await startConfiguredPlatforms(httpServer, { failOnFeishuError: false });
-
-  installShutdownHandlers(httpServer);
-}
+}
+
+/**
+ * 生命周期健康检查发现 HTTP Server 已停止监听时，优先原地恢复同一个 Server。
+ * router、WebSocket upgrade listener 都挂在这个对象上，复用它能保留现有服务绑定；
+ * 恢复失败会被 lifecycle guard 记录，并在下一轮检查重试。
+ */
+async function recoverHttpServer(httpServer: Server, port: number): Promise<void> {
+  if (httpServer.listening) {
+    httpServer.ref();
+    return;
+  }
+  appendStartupTrace("service-lifecycle: HTTP recovery begin", { port });
+  await listenWithRetry(httpServer, port, "127.0.0.1");
+  httpServer.ref();
+  appendStartupTrace("service-lifecycle: HTTP recovery listen succeeded", { port });
+}
 
 /**
  * 带重试的 server.listen，Windows 端口释放有延迟时自动重试。
@@ -963,10 +1004,26 @@ async function listenWithRetry(
  * Node EventEmitter 按注册顺序触发，installCrashLogging 装得更早 → 同步 trace
  * 先写盘，再走这里。
  */
-function installShutdownHandlers(httpServer: Server): void {
-  process.on("SIGINT", () => { console.log("\nShutting down..."); wechatSignal.stopped = true; stopChromeDevtoolsGuard(); httpServer.close(); process.exit(0); });
-  process.on("SIGTERM", () => { wechatSignal.stopped = true; stopChromeDevtoolsGuard(); httpServer.close(); process.exit(0); });
-}
+function installShutdownHandlers(
+  httpServer: Server,
+  serviceLifecycle: ReturnType<typeof createServiceLifecycleGuard>,
+): void {
+  process.on("SIGINT", () => {
+    console.log("\nShutting down...");
+    serviceLifecycle.beginShutdown("SIGINT");
+    wechatSignal.stopped = true;
+    stopChromeDevtoolsGuard();
+    httpServer.close();
+    process.exit(0);
+  });
+  process.on("SIGTERM", () => {
+    serviceLifecycle.beginShutdown("SIGTERM");
+    wechatSignal.stopped = true;
+    stopChromeDevtoolsGuard();
+    httpServer.close();
+    process.exit(0);
+  });
+}
 
 main().catch((err: Error) => {
   appendStartupTrace("main: catch fatal", { message: err.message, stack: err.stack?.slice(0, 800) });

package/src/startup-lifecycle.ts

@@ -1,5 +1,159 @@
 import { spawn, type ChildProcess } from "node:child_process";
 
+const DEFAULT_SERVICE_HEALTH_INTERVAL_MS = 10_000;
+
+interface RefTimer {
+  ref?: () => unknown;
+}
+
+export interface ServiceLifecycleServer {
+  listening: boolean;
+  address: () => unknown;
+  ref: () => unknown;
+}
+
+interface ServiceLifecycleGuardOptions {
+  intervalMs?: number;
+  setIntervalImpl?: (callback: () => void, delayMs: number) => RefTimer;
+  clearIntervalImpl?: (timer: RefTimer) => void;
+  tracer?: (message: string, extra?: Record<string, unknown>) => void;
+  getActiveResourcesInfo?: () => string[];
+}
+
+export interface ServiceLifecycleGuard {
+  start: () => void;
+  attachServer: (
+    server: ServiceLifecycleServer,
+    recoverServer?: () => void | Promise<void>,
+  ) => void;
+  checkNow: () => Promise<void>;
+  handleBeforeExit: (code: number) => void;
+  beginShutdown: (reason: string) => void;
+}
+
+/**
+ * 为 ChatCCC 这种常驻服务建立一个明确的进程生命周期锚点。
+ *
+ * 正常情况下，正在 listen 的 HTTP Server 自己就足以维持事件循环；额外的
+ * referenced timer 是最后一道保险，避免某个依赖升级或异常 close/unref 让进程在
+ * 没有信号、异常或退出码的情况下静默消失。定时检查同时会重新 ref Server，并在
+ * Server 确实停止监听时串行触发恢复，避免只把一个失去服务能力的僵尸进程留下来。
+ */
+export function createServiceLifecycleGuard(
+  options: ServiceLifecycleGuardOptions = {},
+): ServiceLifecycleGuard {
+  const intervalMs = options.intervalMs ?? DEFAULT_SERVICE_HEALTH_INTERVAL_MS;
+  const setIntervalImpl = options.setIntervalImpl
+    ?? ((callback, delayMs) => setInterval(callback, delayMs));
+  const clearIntervalImpl = options.clearIntervalImpl
+    ?? ((timer) => clearInterval(timer as NodeJS.Timeout));
+  const tracer = options.tracer ?? (() => {});
+  const getActiveResourcesInfo = options.getActiveResourcesInfo
+    ?? (() => process.getActiveResourcesInfo());
+
+  let timer: RefTimer | null = null;
+  let server: ServiceLifecycleServer | null = null;
+  let recoverServer: (() => void | Promise<void>) | undefined;
+  let recoveryPromise: Promise<void> | null = null;
+  let shuttingDown = false;
+
+  const trace = (message: string, extra?: Record<string, unknown>): void => {
+    try { tracer(message, extra); } catch { /* 诊断路径不能反过来打断服务 */ }
+  };
+
+  const serverAddress = (): unknown => {
+    try { return server?.address() ?? null; } catch { return null; }
+  };
+
+  const activeResources = (): string[] => {
+    try { return getActiveResourcesInfo(); } catch { return []; }
+  };
+
+  const diagnostics = (extra: Record<string, unknown> = {}): Record<string, unknown> => ({
+    ...extra,
+    uptimeSeconds: Math.floor(process.uptime()),
+    activeResources: activeResources(),
+    serverAttached: server !== null,
+    serverListening: server?.listening ?? false,
+    serverAddress: serverAddress(),
+  });
+
+  const start = (): void => {
+    if (shuttingDown || timer) return;
+    timer = setIntervalImpl(() => { void checkNow(); }, intervalMs);
+    // Node 的 Timeout 默认就是 ref 状态；显式 ref 让常驻服务契约不会依赖默认值。
+    try { timer.ref?.(); } catch { /* ignore */ }
+    trace("service-lifecycle: guard started", { intervalMs });
+  };
+
+  const checkNow = async (): Promise<void> => {
+    if (shuttingDown || !server) return;
+    if (server.listening) {
+      try { server.ref(); } catch (err) {
+        trace("service-lifecycle: HTTP server ref failed", diagnostics({
+          error: (err as Error).message,
+        }));
+      }
+      return;
+    }
+
+    if (recoveryPromise) return recoveryPromise;
+    trace("service-lifecycle: HTTP server inactive", diagnostics());
+    if (!recoverServer) return;
+
+    recoveryPromise = Promise.resolve()
+      .then(() => recoverServer?.())
+      .then(() => {
+        if (server?.listening) {
+          try { server.ref(); } catch { /* 下一轮健康检查会再次尝试 */ }
+          trace("service-lifecycle: HTTP server recovered", diagnostics());
+        } else {
+          trace("service-lifecycle: HTTP recovery completed without listening", diagnostics());
+        }
+      })
+      .catch((err: unknown) => {
+        trace("service-lifecycle: HTTP server recovery failed", diagnostics({
+          error: err instanceof Error ? err.message : String(err),
+        }));
+      })
+      .finally(() => {
+        recoveryPromise = null;
+      });
+    return recoveryPromise;
+  };
+
+  const attachServer = (
+    nextServer: ServiceLifecycleServer,
+    nextRecoverServer?: () => void | Promise<void>,
+  ): void => {
+    server = nextServer;
+    recoverServer = nextRecoverServer;
+    if (server.listening) {
+      try { server.ref(); } catch { /* 下一轮健康检查会记录 */ }
+    }
+    trace("service-lifecycle: HTTP server attached", diagnostics());
+  };
+
+  const handleBeforeExit = (code: number): void => {
+    if (shuttingDown) return;
+    trace("service-lifecycle: unexpected beforeExit", diagnostics({ code }));
+    start();
+    void checkNow();
+  };
+
+  const beginShutdown = (reason: string): void => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    if (timer) {
+      try { clearIntervalImpl(timer); } catch { /* process 即将退出 */ }
+      timer = null;
+    }
+    trace("service-lifecycle: shutdown requested", { reason });
+  };
+
+  return { start, attachServer, checkNow, handleBeforeExit, beginShutdown };
+}
+
 /**
  * ChatCCC 自己拉起替代进程时使用的内部标记。
  *

package/src/web-ui.ts

@@ -2131,7 +2131,10 @@ export function setExtraApiHandler(handler: ExtraApiHandler): void {
   extraApiHandler = handler;
 }
 
-export function startSetupMode(port: number, options: StartSetupModeOptions = {}): void {
+export function startSetupMode(
+  port: number,
+  options: StartSetupModeOptions = {},
+): ReturnType<typeof createServer> {
   const router = createUiRouter();
   const server = createServer(router);
   setupHttpServer = server;
@@ -2167,4 +2170,5 @@ export function startSetupMode(port: number, options: StartSetupModeOptions = {}
     console.log("");
     if (options.openBrowser !== false) openWebUiInDefaultBrowser(port);
   });
+  return server;
 }