chatccc 0.2.207 → 0.2.209

package/package.json

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

package/src/__tests__/card-action-routing.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, it } from "vitest";
+
+import { resolveFeishuCardActionChatType } from "../card-action-routing.ts";
+
+describe("resolveFeishuCardActionChatType", () => {
+  it("keeps card commands in a persisted private chat on the p2p route", () => {
+    expect(resolveFeishuCardActionChatType("private-chat", {
+      "private-chat": { chatType: "p2p" },
+    })).toBe("p2p");
+  });
+
+  it("defaults unknown and group chats to the group route", () => {
+    expect(resolveFeishuCardActionChatType("group-chat", {
+      "group-chat": { chatType: "group" },
+    })).toBe("group");
+    expect(resolveFeishuCardActionChatType("unknown-chat", {})).toBe("group");
+  });
+});

package/src/__tests__/orchestrator.test.ts

@@ -342,6 +342,43 @@ describe("handleCommand WeChat processing ack", () => {
     expect(registry["feishu-p2p"]?.sessionId).toBe("sid-feishu-private");
   });
 
+  it("sends the normal session state card in an established Feishu p2p chat", async () => {
+    const platform = mockPlatform("feishu");
+    _setAdapterForToolForTest("claude", mockAdapter("sid-feishu-state"));
+    await recordSessionRegistry({
+      chatId: "feishu-p2p-state",
+      sessionId: "sid-feishu-state",
+      tool: "claude",
+      chatType: "p2p",
+      chatName: "飞书私聊",
+      turnCount: 2,
+      running: false,
+    });
+
+    await handleCommand(platform, "/state", "feishu-p2p-state", "ou-user", Date.now(), "p2p");
+
+    expect(platform.getChatInfo).not.toHaveBeenCalled();
+    expect(platform.sendRawCard).toHaveBeenCalledTimes(1);
+    const cardText = vi.mocked(platform.sendRawCard).mock.calls[0][1];
+    expect(cardText).toContain("sid-feishu-state");
+    expect(cardText).toContain("Claude Code");
+    expect(cardText).toContain("2");
+  });
+
+  it("shows an explicit state card without creating an Agent when a Feishu p2p chat is not bound yet", async () => {
+    const platform = mockPlatform("feishu");
+    const adapter = mockAdapter("should-not-be-created");
+    _setAdapterForToolForTest("claude", adapter);
+
+    await handleCommand(platform, "/state", "feishu-p2p-empty", "ou-user", Date.now(), "p2p");
+
+    expect(adapter.createSession).not.toHaveBeenCalled();
+    expect(platform.sendRawCard).toHaveBeenCalledTimes(1);
+    const cardText = vi.mocked(platform.sendRawCard).mock.calls[0][1];
+    expect(cardText).toContain("未建立会话");
+    expect(cardText).toContain("Claude Code");
+  });
+
   it("switches an idle Feishu p2p chat to a fresh session when the default Agent changes", async () => {
     const platform = mockPlatform("feishu");
     const oldPrompt = vi.fn(async function* () {

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/card-action-routing.ts

@@ -0,0 +1,14 @@
+export type FeishuCommandChatType = "p2p" | "group";
+
+type SessionRegistryForRouting = Record<string, { chatType?: string }>;
+
+/**
+ * Feishu card action callbacks do not include the chat type. Recover it from
+ * the persisted binding so buttons clicked in a private chat stay in p2p.
+ */
+export function resolveFeishuCardActionChatType(
+  chatId: string,
+  registry: SessionRegistryForRouting,
+): FeishuCommandChatType {
+  return registry[chatId]?.chatType === "p2p" ? "p2p" : "group";
+}

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";
@@ -112,7 +113,8 @@ import {
 import { fixStaleStreamStates } from "./stream-state.ts";
 import { handleCommand, type PlatformAdapter } from "./orchestrator.ts";
 import { createWechatAdapter, startWechatPlatform } from "./wechat-platform.ts";
-import { handleCodexResetCardAction } from "./codex-reset-actions.ts";
+import { handleCodexResetCardAction } from "./codex-reset-actions.ts";
+import { resolveFeishuCardActionChatType } from "./card-action-routing.ts";
 import { reloadRuntimeConfig } from "./runtime-reload.ts";
 
 // ---------------------------------------------------------------------------
@@ -507,16 +509,18 @@ async function startBotServiceCore(): Promise<void> {
       });
       if (handledCodexReset) return;
 
-      const result = parseCardAction(data);
-      if (!result) return;
-      console.log(`[BTN] chat=${result.chatId} text="${result.text}"`);
+      const result = parseCardAction(data);
+      if (!result) return;
+      const registry = await loadSessionRegistryForBinding();
+      const chatType = resolveFeishuCardActionChatType(result.chatId, registry);
+      console.log(`[BTN] chat=${result.chatId} chatType=${chatType} text="${result.text}"`);
       handleCommand(
         feishuPlatform,
         result.text,
         result.chatId,
         result.openId,
         Date.now(),
-        "group",
+        chatType,
         undefined,
         result.commandId,
       ).catch((err) =>
@@ -542,15 +546,17 @@ async function startBotServiceCore(): Promise<void> {
     ws.on("message", async (raw: Buffer) => {
       try {
         const data = JSON.parse(raw.toString()) as Evt;
-        const action = parseCardAction(data);
-        if (action) {
+        const action = parseCardAction(data);
+        if (action) {
+          const registry = await loadSessionRegistryForBinding();
+          const chatType = resolveFeishuCardActionChatType(action.chatId, registry);
           handleCommand(
             feishuPlatform,
             action.text,
             action.chatId,
             action.openId,
             Date.now(),
-            "group",
+            chatType,
             undefined,
             action.commandId,
           ).catch((err) =>
@@ -739,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) {
@@ -782,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 — 模拟飞书环境模式`);
@@ -803,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) {
@@ -851,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");
@@ -860,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) });
@@ -898,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 守护仍保持自己原有的独立行为。
@@ -918,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 端口释放有延迟时自动重试。
@@ -958,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/orchestrator.ts

@@ -416,6 +416,48 @@ function isFeishuP2p(platform: PlatformAdapter, chatType: string): boolean {
   return chatType === "p2p" && platform.kind === "feishu";
 }
 
+async function sendStateCard(
+  platform: PlatformAdapter,
+  chatId: string,
+  sessionId: string | null,
+  toolLabel: string,
+  traceId: string,
+): Promise<void> {
+  const status = sessionId ? await getSessionStatus(chatId) : null;
+  const isActive = sessionId ? isSessionRunning(sessionId) : false;
+  const stateLabel = sessionId
+    ? (isActive ? "🟢 运行中" : "⚪ 空闲")
+    : "⚪ 未建立会话";
+  const statusText = [
+    `**群名:** ${status?.chatName || "—"}`,
+    `**Session ID:** ${sessionId ? `\`${status?.sessionId ?? sessionId}\`` : "—"}`,
+    `**工具:** ${toolLabel}`,
+    `**状态:** ${stateLabel}`,
+    `**已对话轮数:** ${status?.turnCount ?? 0}`,
+    `**模型:** ${sessionId ? (status?.model ?? anthropicConfigDisplay(CLAUDE_MODEL)) : "—"}`,
+  ];
+  if (status?.effort != null) {
+    statusText.push(`**Effort:** ${status.effort}`);
+  }
+  if (isActive && status) {
+    const elapsed = Math.floor((Date.now() - status.startTime) / 1000);
+    const mins = Math.floor(elapsed / 60);
+    const secs = elapsed % 60;
+    statusText.push(`**本轮已运行:** ${mins}分${secs}秒`);
+    statusText.push(`**已产出总字符:** ${status.accumulatedLength.toLocaleString()}`);
+  }
+  if (status?.lastContextTokens) {
+    statusText.push(`**上下文 Token 数:** ~${status.lastContextTokens.toLocaleString()}`);
+  }
+  const card = buildStatusCard(statusText.join("\n"), isActive ? "blue" : "green");
+  const ok = await platform.sendRawCard(chatId, card);
+  console.log(`[${ts()}] [STATUS] card sent, ok=${ok}`);
+  logTrace(traceId, "DONE", {
+    outcome: sessionId ? "status" : "status_no_session",
+    ok,
+  });
+}
+
 interface FeishuP2pRegistryRecord {
   sessionId: string;
   tool: string;
@@ -1336,44 +1378,11 @@ export async function handleCommand(
       return;
     }
 
-    if (isCommandText && textLower === "/state") {
-      logTrace(tid, "BRANCH", { cmd: "/state" });
-      const status = await getSessionStatus(chatId);
-      const isActive = isSessionRunning(sessionId);
-      const statusText = [
-        `**群名:** ${status?.chatName || "—"}`,
-        `**Session ID:** \`${status?.sessionId ?? sessionId}\``,
-        `**工具:** ${toolLabel}`,
-        `**状态:** ${isActive ? "🟢 运行中" : "⚪ 空闲"}`,
-        `**已对话轮数:** ${status?.turnCount ?? 0}`,
-        `**模型:** ${status?.model ?? anthropicConfigDisplay(CLAUDE_MODEL)}`,
-      ];
-      if (status?.effort != null) {
-        statusText.push(`**Effort:** ${status.effort}`);
-      }
-      if (isActive) {
-        const elapsed = Math.floor((Date.now() - status!.startTime) / 1000);
-        const mins = Math.floor(elapsed / 60);
-        const secs = elapsed % 60;
-        statusText.push(`**本轮已运行:** ${mins}分${secs}秒`);
-        statusText.push(
-          `**已产出总字符:** ${status!.accumulatedLength.toLocaleString()}`,
-        );
-      }
-      if (status?.lastContextTokens) {
-        statusText.push(
-          `**上下文 Token 数:** ~${status.lastContextTokens.toLocaleString()}`,
-        );
-      }
-      const card = buildStatusCard(
-        statusText.join("\n"),
-        isActive ? "blue" : "green",
-      );
-      const ok = await platform.sendRawCard(chatId, card);
-      console.log(`[${ts()}] [STATUS] card sent, ok=${ok}`);
-      logTrace(tid, "DONE", { outcome: "status", ok });
-      return;
-    }
+    if (isCommandText && textLower === "/state") {
+      logTrace(tid, "BRANCH", { cmd: "/state" });
+      await sendStateCard(platform, chatId, sessionId, toolLabel, tid);
+      return;
+    }
 
     if (isCommandText && textLower === "/sessions") {
       logTrace(tid, "BRANCH", { cmd: "/sessions" });
@@ -2000,9 +2009,23 @@ export async function handleCommand(
       const card = buildModelCard(currentModel, models, defaultTool);
       await platform.sendRawCard(chatId, card);
     }
-    logTrace(tid, "DONE", { outcome: "model_query", defaultTool });
-    return;
-  }
+    logTrace(tid, "DONE", { outcome: "model_query", defaultTool });
+    return;
+  }
+
+  // A private /state query is useful even before the first Agent session exists.
+  // Keep it read-only and render the same status-card shape as established chats.
+  if (isCommandText && textLower === "/state" && isFeishuP2p(platform, chatType)) {
+    logTrace(tid, "BRANCH", { cmd: "/state", scope: "unbound_p2p" });
+    await sendStateCard(
+      platform,
+      chatId,
+      null,
+      toolDisplayName(resolveDefaultAgentTool()),
+      tid,
+    );
+    return;
+  }
 
   // 无会话上下文 → /sessions 仍是有效指令，不触发飞书私聊自动建群。
   if (isCommandText && textLower === "/effort") {

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;
 }