chatccc 0.2.208 → 0.2.210

package/package.json

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

package/src/__tests__/session.test.ts

@@ -670,6 +670,7 @@ describe("runAgentSession process monitor", () => {
 
 describe("runAgentSession response stall watchdog", () => {
   let tempDir = "";
+  const recoveryPrompt = "完成了吗？如果没完成继续";
 
   beforeEach(async () => {
     vi.useFakeTimers();
@@ -766,6 +767,227 @@ describe("runAgentSession response stall watchdog", () => {
       autoEndedAt: expect.any(Number),
     });
   });
+
+  it("runs the reserved recovery prompt before an already queued user message", async () => {
+    vi.setSystemTime(0);
+    _setResponseStallTimeoutForTest(100);
+    _setResponseStallCheckIntervalForTest(10);
+    _setProcessAliveForTest(() => true);
+
+    const platform = mockPlatform("feishu");
+    setSessionPlatform(platform);
+    bindChatToSession("sid-recovery-priority", "chat-recovery-priority");
+    recordLastActiveChat("sid-recovery-priority", "chat-recovery-priority");
+
+    const receivedPrompts: string[] = [];
+    const adapter: ToolAdapter = {
+      displayName: "Any Agent",
+      sessionDescPrefix: "Agent Session:",
+      createSession: async () => ({ sessionId: "sid-recovery-priority" }),
+      getSessionInfo: async (sid) => ({ sessionId: sid, cwd: "F:\\repo" }),
+      closeSession: async () => {},
+      prompt: async function* (
+        _sid: string,
+        text: string,
+        _cwd: string,
+        signal?: AbortSignal,
+        options?: ToolPromptOptions,
+      ) {
+        receivedPrompts.push(text);
+        options?.onProcessStart?.({ pid: 5252 + receivedPrompts.length });
+        if (receivedPrompts.length === 1) {
+          yield { type: "assistant", blocks: [{ type: "text", text: "" }] };
+          await new Promise<void>((resolve) => {
+            if (signal?.aborted) {
+              resolve();
+              return;
+            }
+            signal?.addEventListener("abort", () => resolve(), { once: true });
+          });
+          return;
+        }
+        yield { type: "assistant", blocks: [{ type: "text", text: "recovery completed" }] };
+      },
+    };
+    _setAdapterForToolForTest("claude", adapter);
+
+    enqueueMessage("sid-recovery-priority", {
+      text: "queued user prompt",
+      chatId: "chat-recovery-priority",
+      openId: "open-user",
+      msgTimestamp: 1,
+      chatType: "p2p",
+    });
+    const consumeQueued = vi.fn();
+    setQueueConsumer(consumeQueued);
+
+    const firstRun = runAgentSession(
+      "sid-recovery-priority",
+      "first prompt",
+      platform,
+      "chat-recovery-priority",
+      0,
+      "claude",
+    );
+
+    await vi.waitFor(() => {
+      expect(activePrompts.get("sid-recovery-priority")?.responseProgress).toBeDefined();
+    });
+    const firstProgress = activePrompts.get("sid-recovery-priority")!.responseProgress!;
+    await vi.advanceTimersByTimeAsync(firstProgress.unchangedSince + 101 - Date.now());
+    await firstRun;
+
+    expect(receivedPrompts).toHaveLength(1);
+    expect(consumeQueued).not.toHaveBeenCalled();
+    expect(isSessionRunning("sid-recovery-priority")).toBe(true);
+    expect(platform.sendText).toHaveBeenCalledWith(
+      "chat-recovery-priority",
+      "检测到会话停滞，正在自动确认并继续。",
+    );
+
+    await vi.advanceTimersByTimeAsync(200);
+    await vi.waitFor(() => expect(receivedPrompts).toHaveLength(2));
+    expect(receivedPrompts[1]).toContain(recoveryPrompt);
+    expect(receivedPrompts[1]).not.toContain("queued user prompt");
+    expect(consumeQueued).not.toHaveBeenCalled();
+
+    await vi.advanceTimersByTimeAsync(200);
+    expect(consumeQueued).toHaveBeenCalledTimes(1);
+    expect(consumeQueued).toHaveBeenCalledWith(
+      platform,
+      expect.objectContaining({ text: "queued user prompt" }),
+    );
+    setQueueConsumer(() => {});
+  });
+
+  it("does not auto-recover a second consecutive response stall", async () => {
+    vi.setSystemTime(0);
+    _setResponseStallTimeoutForTest(100);
+    _setResponseStallCheckIntervalForTest(10);
+    _setProcessAliveForTest(() => true);
+
+    const platform = mockPlatform("feishu");
+    setSessionPlatform(platform);
+    bindChatToSession("sid-recovery-limit", "chat-recovery-limit");
+    recordLastActiveChat("sid-recovery-limit", "chat-recovery-limit");
+
+    const receivedPrompts: string[] = [];
+    const adapter: ToolAdapter = {
+      displayName: "Any Agent",
+      sessionDescPrefix: "Agent Session:",
+      createSession: async () => ({ sessionId: "sid-recovery-limit" }),
+      getSessionInfo: async (sid) => ({ sessionId: sid, cwd: "F:\\repo" }),
+      closeSession: async () => {},
+      prompt: async function* (
+        _sid: string,
+        text: string,
+        _cwd: string,
+        signal?: AbortSignal,
+        options?: ToolPromptOptions,
+      ) {
+        receivedPrompts.push(text);
+        options?.onProcessStart?.({ pid: 6262 + receivedPrompts.length });
+        yield { type: "assistant", blocks: [{ type: "text", text: "" }] };
+        await new Promise<void>((resolve) => {
+          if (signal?.aborted) {
+            resolve();
+            return;
+          }
+          signal?.addEventListener("abort", () => resolve(), { once: true });
+        });
+      },
+    };
+    _setAdapterForToolForTest("claude", adapter);
+
+    const firstRun = runAgentSession(
+      "sid-recovery-limit",
+      "first prompt",
+      platform,
+      "chat-recovery-limit",
+      0,
+      "claude",
+    );
+    await vi.waitFor(() => {
+      expect(activePrompts.get("sid-recovery-limit")?.responseProgress).toBeDefined();
+    });
+    const firstProgress = activePrompts.get("sid-recovery-limit")!.responseProgress!;
+    await vi.advanceTimersByTimeAsync(firstProgress.unchangedSince + 101 - Date.now());
+    await firstRun;
+
+    await vi.advanceTimersByTimeAsync(200);
+    await vi.waitFor(() => expect(receivedPrompts).toHaveLength(2));
+    const recoveryProgress = activePrompts.get("sid-recovery-limit")!.responseProgress!;
+    await vi.advanceTimersByTimeAsync(recoveryProgress.unchangedSince + 101 - Date.now());
+    await vi.waitFor(() => expect(isSessionRunning("sid-recovery-limit")).toBe(false));
+
+    await vi.advanceTimersByTimeAsync(1_000);
+    expect(receivedPrompts).toHaveLength(2);
+    expect(receivedPrompts[1]).toContain(recoveryPrompt);
+    expect(platform.sendText).toHaveBeenCalledWith(
+      "chat-recovery-limit",
+      "⚠️ 自动续跑仍连续 3 分钟没有新回复，本次不再自动继续。",
+    );
+  });
+
+  it("lets /stop cancel a reserved recovery before it starts", async () => {
+    vi.setSystemTime(0);
+    _setResponseStallTimeoutForTest(100);
+    _setResponseStallCheckIntervalForTest(10);
+    _setProcessAliveForTest(() => true);
+
+    const platform = mockPlatform("feishu");
+    setSessionPlatform(platform);
+    bindChatToSession("sid-recovery-stop", "chat-recovery-stop");
+    recordLastActiveChat("sid-recovery-stop", "chat-recovery-stop");
+
+    const receivedPrompts: string[] = [];
+    const adapter: ToolAdapter = {
+      displayName: "Any Agent",
+      sessionDescPrefix: "Agent Session:",
+      createSession: async () => ({ sessionId: "sid-recovery-stop" }),
+      getSessionInfo: async (sid) => ({ sessionId: sid, cwd: "F:\\repo" }),
+      closeSession: async () => {},
+      prompt: async function* (
+        _sid: string,
+        text: string,
+        _cwd: string,
+        signal?: AbortSignal,
+      ) {
+        receivedPrompts.push(text);
+        yield { type: "assistant", blocks: [{ type: "text", text: "" }] };
+        await new Promise<void>((resolve) => {
+          if (signal?.aborted) {
+            resolve();
+            return;
+          }
+          signal?.addEventListener("abort", () => resolve(), { once: true });
+        });
+      },
+    };
+    _setAdapterForToolForTest("claude", adapter);
+
+    const firstRun = runAgentSession(
+      "sid-recovery-stop",
+      "first prompt",
+      platform,
+      "chat-recovery-stop",
+      0,
+      "claude",
+    );
+    await vi.waitFor(() => {
+      expect(activePrompts.get("sid-recovery-stop")?.responseProgress).toBeDefined();
+    });
+    const progress = activePrompts.get("sid-recovery-stop")!.responseProgress!;
+    await vi.advanceTimersByTimeAsync(progress.unchangedSince + 101 - Date.now());
+    await firstRun;
+
+    expect(isSessionRunning("sid-recovery-stop")).toBe(true);
+    expect(stopSession("sid-recovery-stop")).toBe(true);
+    await vi.advanceTimersByTimeAsync(500);
+
+    expect(receivedPrompts).toHaveLength(1);
+    expect(isSessionRunning("sid-recovery-stop")).toBe(false);
+  });
 });
 
 describe("unified display loop WeChat delta", () => {

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/session-chat-binding.ts

@@ -57,9 +57,17 @@ export function hasChatsForSession(sessionId: string): boolean {
 // 也必须阻止下一轮提前进入，否则旧会话的落盘可能覆盖新会话绑定。
 const finalizingSessions = new Set<string>();
 
-/** 检查 sessionId 是否有活跃 prompt 或正在完成本轮异步收尾。 */
+// response-stall 自动恢复预约只存在于当前进程内：用户已明确 ChatCCC 重启后
+// 不需要补发恢复 prompt。预约从检测到第一次停滞起一直持有到恢复轮同步进入
+// runAgentSession，填补旧轮收尾和新轮 activePrompts.set 之间的空窗，保证此时
+// 到达的普通用户消息只能进入缓存队列，不能抢在恢复 prompt 前执行。
+const autoRecoveryReservations = new Set<string>();
+
+/** 检查 sessionId 是否有活跃 prompt、正在收尾或已预约自动恢复。 */
 export function isSessionRunning(sessionId: string): boolean {
-  return activePrompts.has(sessionId) || finalizingSessions.has(sessionId);
+  return activePrompts.has(sessionId)
+    || finalizingSessions.has(sessionId)
+    || autoRecoveryReservations.has(sessionId);
 }
 
 export function markSessionFinalizing(sessionId: string): void {
@@ -69,6 +77,27 @@ export function markSessionFinalizing(sessionId: string): void {
 export function clearSessionFinalizing(sessionId: string): void {
   finalizingSessions.delete(sessionId);
 }
+
+/** 为 response-stall 后的内部恢复轮预留下一次执行权。 */
+export function reserveAutoRecovery(sessionId: string): boolean {
+  if (autoRecoveryReservations.has(sessionId)) return false;
+  autoRecoveryReservations.add(sessionId);
+  return true;
+}
+
+/** 恢复轮启动前原子消费预约；返回 false 表示已被 /stop 取消。 */
+export function consumeAutoRecoveryReservation(sessionId: string): boolean {
+  return autoRecoveryReservations.delete(sessionId);
+}
+
+/** 取消尚未启动的恢复轮。 */
+export function cancelAutoRecoveryReservation(sessionId: string): boolean {
+  return autoRecoveryReservations.delete(sessionId);
+}
+
+export function hasAutoRecoveryReservation(sessionId: string): boolean {
+  return autoRecoveryReservations.has(sessionId);
+}
 
 // ---------------------------------------------------------------------------
 // activePrompts: sessionId → 活跃 prompt 控制
@@ -92,6 +121,8 @@ export interface ActivePrompt {
   abnormalExitNotified?: boolean;
   /** Set when the resource monitor detects CPU + memory unchanged for 3 minutes. */
   resourceStuck?: boolean;
+  /** True only for the single internal continuation turn after a response stall. */
+  autoRecovery?: boolean;
   /** Adapter-provided callback to close the underlying SDK session / subprocess.
    *  Called by stop-stuck-loop before controller.abort() to terminate the CLI
    *  process immediately, rather than waiting for the async generator to unblock. */
@@ -245,6 +276,7 @@ export function resetBindingState(): void {
   }
   activePrompts.clear();
   finalizingSessions.clear();
+  autoRecoveryReservations.clear();
   queuedMessages.clear();
   displayCards.clear();
   if (unifiedDisplayLoopHandle !== null) {

package/src/session.ts

@@ -77,6 +77,10 @@ import {
   consumeQueuePreservedChat,
   markSessionFinalizing,
   clearSessionFinalizing,
+  reserveAutoRecovery,
+  consumeAutoRecoveryReservation,
+  cancelAutoRecoveryReservation,
+  hasAutoRecoveryReservation,
 } from "./session-chat-binding.ts";
 
 async function sendFinalReplyTextOnce(
@@ -161,6 +165,11 @@ function platformForChat(chatId: string): PlatformAdapter | null {
 const DEFAULT_PROCESS_MONITOR_INTERVAL_MS = 5000;
 const DEFAULT_RESPONSE_STALL_TIMEOUT_MS = 3 * 60 * 1000;
 const DEFAULT_RESPONSE_STALL_CHECK_INTERVAL_MS = 5000;
+export const RESPONSE_STALL_RECOVERY_PROMPT = "完成了吗？如果没完成继续";
+export const RESPONSE_STALL_RECOVERY_NOTICE = "检测到会话停滞，正在自动确认并继续。";
+export const RESPONSE_STALL_RECOVERY_EXHAUSTED_NOTICE =
+  "⚠️ 自动续跑仍连续 3 分钟没有新回复，本次不再自动继续。";
+const RESPONSE_STALL_RECOVERY_DELAY_MS = 200;
 let processMonitorIntervalMs = DEFAULT_PROCESS_MONITOR_INTERVAL_MS;
 let responseStallTimeoutMs = DEFAULT_RESPONSE_STALL_TIMEOUT_MS;
 let responseStallCheckIntervalMs = DEFAULT_RESPONSE_STALL_CHECK_INTERVAL_MS;
@@ -966,19 +975,28 @@ export async function resumeAndPrompt(
   return runAgentSession(sessionId, userText, platform, chatId, msgTimestamp, tool, traceId);
 }
 
-// ---------------------------------------------------------------------------
-// runAgentSession — session 中心的 agent prompt（文件持久化 + display 解耦）
-// ---------------------------------------------------------------------------
-
-export async function runAgentSession(
-  sessionId: string,
-  userText: string,
-  platform: PlatformAdapter,
-  _chatId: string,
-  msgTimestamp: number,
-  tool: string,
-  traceId?: string,
-): Promise<void> {
+// ---------------------------------------------------------------------------
+// runAgentSession — session 中心的 agent prompt（文件持久化 + display 解耦）
+// ---------------------------------------------------------------------------
+
+interface RunAgentSessionOptions {
+  /**
+   * 标记本轮是 response-stall 后的唯一一次内部续跑。若本轮再次因相同原因
+   * 停滞，不再递归创建第三轮，避免服务异常期间无限消耗 token。
+   */
+  autoRecovery?: boolean;
+}
+
+export async function runAgentSession(
+  sessionId: string,
+  userText: string,
+  platform: PlatformAdapter,
+  _chatId: string,
+  msgTimestamp: number,
+  tool: string,
+  traceId?: string,
+  options: RunAgentSessionOptions = {},
+): Promise<void> {
   const tid = traceId ?? "";
 
   // 记录用户最后发送消息的群（display loop 只推送到该群）
@@ -1002,11 +1020,12 @@ export async function runAgentSession(
   // 注意：下面的 try/catch 在准备失败时会清理 activePrompts。
   const controller = new AbortController();
   const now = Date.now();
-  activePrompts.set(sessionId, {
-    controller,
-    stopped: false,
-    startTime: now,
-  });
+  activePrompts.set(sessionId, {
+    controller,
+    stopped: false,
+    startTime: now,
+    autoRecovery: options.autoRecovery === true,
+  });
 
   // 资源监控僵死检测：CPU + 内存连续 3 分钟无变化 → 强制停止
   const onResourceStuck = (data: { pid: number; sessionId: string; idleMinutes: number }) => {
@@ -1257,6 +1276,13 @@ export async function runAgentSession(
       }
 
       const autoEndedAt = Date.now();
+      // 普通轮第一次因回复停滞结束时，立即预约同 session 的内部续跑。
+      // 预约先于 abort/收尾建立，isSessionRunning 会在整个交接窗口保持 true，
+      // 因此恰好到达的用户消息只能排队，绝不可能抢在恢复 prompt 前。
+      // 若当前已经是恢复轮，则不再预约第三轮。
+      if (!current.autoRecovery) {
+        reserveAutoRecovery(sessionId);
+      }
       current.autoEnded = true;
       current.autoEndedAt = autoEndedAt;
       clearPromptResponseStallMonitor(sessionId);
@@ -1376,6 +1402,7 @@ export async function runAgentSession(
     const wasAbnormalExit = prompt?.abnormalExit ?? false;
     const wasResourceStuck = prompt?.resourceStuck ?? false;
     const wasAutoEnded = prompt?.autoEnded ?? false;
+    const wasAutoRecovery = prompt?.autoRecovery ?? false;
     const autoEndedAt = prompt?.autoEndedAt;
     clearPromptResponseStallMonitor(sessionId);
     clearPromptProcessMonitor(sessionId);
@@ -1426,10 +1453,12 @@ export async function runAgentSession(
       ...(preserveStuckAt ? { stuckAt: preserveStuckAt } : {}),
       ...(autoEndedAt !== undefined ? { autoEndedAt } : {}),
     });
-
+
     // display loop 下一轮会读到最终状态并发送消息
-
-    if (wasStopped) {
+
+    let autoRecoveryTarget: { chatId: string; platform: PlatformAdapter } | undefined;
+
+    if (wasStopped) {
       for (const cid of getChatsForSession(sessionId)) {
         const finfo = sessionInfoMap.get(cid);
         await recordSessionRegistry({
@@ -1464,9 +1493,9 @@ export async function runAgentSession(
       }
       const activeAutoEnded = getLastActiveChat(sessionId) ?? getChatsForSession(sessionId)[0];
       if (activeAutoEnded) {
+        const pp = platformForChat(activeAutoEnded) ?? platform;
         const terminalState = await readStreamState(sessionId);
         if (!displayCards.has(activeAutoEnded) && (!terminalState || !isFinalReplySentForTurn(terminalState))) {
-          const pp = platformForChat(activeAutoEnded) ?? platform;
           await sendFinalReplyTextOnce(
             pp,
             activeAutoEnded,
@@ -1475,7 +1504,24 @@ export async function runAgentSession(
             formatAutoEndedReply(finalReplyToWrite),
           );
         }
-        platform.setChatAvatar(activeAutoEnded, tool, "idle").catch(() => {});
+        pp.setChatAvatar(activeAutoEnded, tool, "idle").catch(() => {});
+
+        if (wasAutoRecovery) {
+          // 这是紧接第一次停滞而启动的恢复轮；再次发生相同停滞即终止
+          // 自动链，避免第三轮及之后的无限续跑。
+          await pp.sendText(
+            activeAutoEnded,
+            RESPONSE_STALL_RECOVERY_EXHAUSTED_NOTICE,
+          ).catch(() => {});
+        } else if (hasAutoRecoveryReservation(sessionId)) {
+          // 用户可见提示与内部恢复 prompt 分离：提示发送失败不影响恢复，
+          // 内部恢复仍由 reservation 保证先于普通缓存消息。
+          await pp.sendText(
+            activeAutoEnded,
+            RESPONSE_STALL_RECOVERY_NOTICE,
+          ).catch(() => {});
+          autoRecoveryTarget = { chatId: activeAutoEnded, platform: pp };
+        }
       }
       console.warn(`[${ts()}] Session ${sessionId} auto-ended after stalled response output (content chunks: ${state.chunkCount})`);
       if (tid) logTrace(tid, "SESSION_END", { sessionId, outcome: "response_stall", chunks: state.chunkCount });
@@ -1522,6 +1568,18 @@ export async function runAgentSession(
       if (tid) logTrace(tid, "SESSION_END", { sessionId, chunks: state.chunkCount, finalTextLen: finalReply.length });
     }
 
+    // 失去聊天绑定时无法安全选择恢复轮的展示目标，取消本次进程内预约。
+    if (
+      wasAutoEnded
+      && hasAutoRecoveryReservation(sessionId)
+      && !autoRecoveryTarget
+    ) {
+      cancelAutoRecoveryReservation(sessionId);
+    }
+    const shouldScheduleAutoRecovery =
+      autoRecoveryTarget !== undefined
+      && hasAutoRecoveryReservation(sessionId);
+
     // 必须等本轮最终卡片、registry 和头像全部收尾后再取出并调度队列消息。
     // 在收尾期间新到达的消息也会因 finalizingSessions 被正确排入这里。
     let queuedForConsumption: ReturnType<typeof dequeueMessage> = undefined;
@@ -1530,7 +1588,9 @@ export async function runAgentSession(
       if (discarded) {
         console.log(`[${ts()}] [QUEUE] Discarding queued message for stopped session ${sessionId}`);
       }
-    } else {
+    } else if (!shouldScheduleAutoRecovery) {
+      // 第一次 response-stall 后保留普通缓存；恢复轮结束后由恢复轮的
+      // finally 再消费，顺序固定为“自动恢复 → 用户缓存”。
       queuedForConsumption = dequeueMessage(sessionId);
     }
 
@@ -1548,7 +1608,48 @@ export async function runAgentSession(
       // 足够时间读到最终状态并终结旧卡片，避免新轮更新旧卡片。
       setTimeout(() => {
         consumeQueuedMessage(platform, queued);
-      }, 200);
+      }, RESPONSE_STALL_RECOVERY_DELAY_MS);
+    }
+
+    if (shouldScheduleAutoRecovery && autoRecoveryTarget) {
+      const target = autoRecoveryTarget;
+      console.log(
+        `[${ts()}] [RESPONSE-STALL] Reserved automatic recovery for session ${sessionId}`,
+      );
+      // 延迟与普通队列原有策略一致，让上一轮终态先完成展示。reservation
+      // 在定时器等待期间仍令 isSessionRunning=true；调用 runAgentSession
+      // 时会在首次 await 前同步写入 activePrompts，然后才消费 reservation，
+      // 因而不存在普通用户消息可插入的事件循环空窗。
+      setTimeout(() => {
+        if (!hasAutoRecoveryReservation(sessionId)) return;
+        const recoveryRun = runAgentSession(
+          sessionId,
+          RESPONSE_STALL_RECOVERY_PROMPT,
+          target.platform,
+          target.chatId,
+          Date.now(),
+          tool,
+          undefined,
+          { autoRecovery: true },
+        );
+        consumeAutoRecoveryReservation(sessionId);
+        void recoveryRun.catch((err) => {
+          console.error(
+            `[${ts()}] [RESPONSE-STALL] Automatic recovery failed for ${sessionId}: ${(err as Error).message}`,
+          );
+          target.platform.sendText(
+            target.chatId,
+            `⚠️ 自动续跑启动失败：${(err as Error).message}`,
+          ).catch(() => {});
+
+          // 若恢复轮在进入主 stream try/finally 前即准备失败，它不会自然
+          // 消费此前保留的用户缓存；在错误回调中补做一次，避免队列悬挂。
+          const queued = dequeueMessage(sessionId);
+          if (queued) {
+            consumeQueuedMessage(target.platform, queued);
+          }
+        });
+      }, RESPONSE_STALL_RECOVERY_DELAY_MS);
     }
     } finally {
       clearSessionFinalizing(sessionId);
@@ -1910,9 +2011,19 @@ export function stopUnifiedDisplayLoop(): void {
 //    虽然很快但仍是异步，期间 display loop 可能多读到 1–2 帧 "running"，
 //    用户体验上"按下停止后还要等几秒卡片才变成已停止"。先把状态标好，
 //    finally 后续再写一次也不冲突——status 最终值仍然是 stopped。
-export function stopSession(sessionId: string): boolean {
-  const prompt = activePrompts.get(sessionId);
-  if (!prompt) return false;
+export function stopSession(sessionId: string): boolean {
+  // /stop 拥有高于内部自动恢复的优先级。旧轮已经完成、恢复轮尚在 200ms
+  // 预约窗口时 activePrompts 为空，因此必须单独取消 reservation。
+  const cancelledRecovery = cancelAutoRecoveryReservation(sessionId);
+  const prompt = activePrompts.get(sessionId);
+  if (!prompt) {
+    if (cancelledRecovery) {
+      cancelQueuedMessage(sessionId);
+      console.log(`[${ts()}] [STOP] Reserved automatic recovery for ${sessionId} cancelled`);
+      return true;
+    }
+    return false;
+  }
   prompt.stopped = true;
   clearPromptResponseStallMonitor(sessionId);
   clearPromptProcessMonitor(sessionId);

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