chatccc 0.2.280 → 0.2.282

package/README.md

@@ -446,6 +446,10 @@ Codex 的默认模型和推理强度可继续由 `~/.codex/config.toml` 管理
 `/update`、`/update safe` 与短别名 `/updatesf` 会把飞书消息或按钮事件 ID 原子写入 `~/.chatccc/state/update-command-guard.json`。同一 ID 跨重启重投时会静默忽略；用户主动发送的新更新指令因事件 ID 不同，仍可执行。该保护不改变普通消息与重启指令的处理方式。
 
 `/restart safe`（短别名 `/restartsf`）与 `/update safe`（短别名 `/updatesf`）会先建立全局准入门禁：指令到达前已经运行或进入单会话缓存队列的工作会继续完成，之后到达的新普通任务会被提示在维护完成后重发。维护任务持久化到 `~/.chatccc/state/safe-maintenance.json`，进程意外退出后可继续排空；依赖安装、会话收尾、自动恢复和 Agent Teams 执行也计入等待条件。内存缓存随重启自然重建，磁盘会话、看板、图片等持久数据不会被清理。
+
+ChatCCC 的内部重启和更新使用跨平台父子进程握手：替代进程完成启动预检后通知父进程退出，再等待旧监听端口实际释放并接管 PID；替代进程未就绪或握手超时时，父进程会保留并继续服务。
+
+飞书接收长连接启用 15 秒握手超时和 30 秒心跳应答超时；首次启动最多等待 45 秒真实连接确认后才提示就绪。运行期间连接持续异常 90 秒时，会关闭并重新建立接收连接，保留会话、消息去重和正在执行的任务。没有用户消息不会触发重连。连接状态与恢复记录写入运行日志和 `startup-trace.log`（`FEISHU-CONNECTION` / `feishu-connection`）。卡片更新遇到网络失败或序号冲突时不会当成送达成功，错误通知保留文本兜底；TLS 断线会明确显示为网络连接失败，已中断的 Agent 任务不会因此自动重放。
 
 > **模型切换**：`/model` 查看当前会话 Agent 的可选模型清单，`/model <名称>` 模糊匹配切换，`/model clear` 恢复默认。可选模型来自当前 Agent 的配置：Claude 使用 `claude.model` / `claude.subagentModel`；Cursor、Codex、CCC Agent 和 DSH 使用各自的 `model` / `alternativeModel`。
 

package/dist/src/cardkit.js

@@ -103,7 +103,31 @@ export async function streamCardKitElement(token, cardId, elementId, content, se
     // success log is intentionally sparse — uncomment to debug streaming throughput
     // console.log(`[${ts()}] [CARDIKT] streamElement OK cardId=${cardId} seq=${sequence}`);
 }
-export async function updateCardKitCard(token, cardId, cardJson, sequence) {
+// Keep bounded per-card sequence history; never reuse an attempted sequence
+// because a failed fetch can mean the response (not the update) was lost.
+const cardUpdateQueues = new Map();
+export function updateCardKitCard(token, cardId, cardJson, sequence) {
+    let state = cardUpdateQueues.get(cardId);
+    if (!state) {
+        for (const [key, candidate] of cardUpdateQueues) {
+            if (cardUpdateQueues.size < 512)
+                break;
+            if (candidate.pending === 0)
+                cardUpdateQueues.delete(key);
+        }
+        state = { sequence: 0, tail: Promise.resolve(), pending: 0 };
+        cardUpdateQueues.set(cardId, state);
+    }
+    const queue = state;
+    queue.pending++;
+    const result = queue.tail.then(async () => {
+        queue.sequence = Math.max(sequence, queue.sequence + 1);
+        await performCardKitUpdate(token, cardId, cardJson, queue.sequence);
+    });
+    queue.tail = result.catch(() => { }).finally(() => { queue.pending--; });
+    return result;
+}
+async function performCardKitUpdate(token, cardId, cardJson, sequence) {
     const { resp, respText } = await fetchCardKit(`${BASE_URL}/cardkit/v1/cards/${cardId}`, {
         method: "PUT",
         headers: {

package/dist/src/feishu-connection.js

@@ -0,0 +1,144 @@
+import { sanitizeTerminalErrorDetail } from "./terminal-error.js";
+/** Owns only the receiving transport. It never resets sessions or replays tasks. */
+export function createFeishuConnectionSupervisor(options) {
+    const stalledAfterMs = options.stalledAfterMs ?? 90_000;
+    let stopped = false;
+    let client;
+    let timer;
+    let startupTimer;
+    let startup;
+    let resolveStartup;
+    let rejectStartup;
+    let unhealthySince;
+    let lastState = "idle";
+    let connected = false;
+    let launching = false;
+    let lastAttempt = 0;
+    const log = (event, detail) => {
+        try {
+            options.log(event, detail);
+        }
+        catch { /* diagnostics cannot break recovery */ }
+    };
+    const reportError = (error) => {
+        if (stopped)
+            return;
+        connected = false;
+        unhealthySince ??= Date.now();
+        log("connection error", { reason: sanitizeTerminalErrorDetail(error instanceof Error ? error.message : String(error)) });
+    };
+    const becameConnected = () => {
+        if (stopped) {
+            // A handshake already in flight can finish after close(); never resurrect
+            // a transport belonging to a stopped setup attempt or shutting-down app.
+            try {
+                client?.close({ force: true });
+            }
+            catch { /* best effort */ }
+            return;
+        }
+        if (connected)
+            return;
+        connected = true;
+        unhealthySince = undefined;
+        lastState = "connected";
+        log("connected");
+        if (startupTimer)
+            clearTimeout(startupTimer);
+        resolveStartup?.();
+        resolveStartup = undefined;
+        rejectStartup = undefined;
+        void Promise.resolve().then(() => stopped ? undefined : options.onConnected()).catch((error) => {
+            log("binding recovery failed", { reason: sanitizeTerminalErrorDetail(String(error)) });
+        });
+    };
+    const stop = () => {
+        if (stopped)
+            return;
+        stopped = true;
+        if (timer)
+            clearInterval(timer);
+        if (startupTimer)
+            clearTimeout(startupTimer);
+        try {
+            client?.close({ force: true });
+        }
+        catch { /* best effort shutdown */ }
+        rejectStartup?.(new Error("飞书长连接在就绪前已停止"));
+        resolveStartup = undefined;
+        rejectStartup = undefined;
+        log("stopped");
+    };
+    const launch = () => {
+        if (stopped || launching || !client)
+            return;
+        launching = true;
+        lastAttempt = Date.now();
+        unhealthySince = lastAttempt;
+        void Promise.resolve().then(() => stopped ? undefined : client.start())
+            .catch(reportError).finally(() => { launching = false; });
+    };
+    const check = () => {
+        if (stopped || !client)
+            return;
+        try {
+            const status = client.getConnectionStatus();
+            if (status.state !== lastState) {
+                lastState = status.state;
+                log("state", { ...status });
+            }
+            if (status.state === "connected") {
+                becameConnected();
+                return;
+            }
+            connected = false;
+            unhealthySince ??= Date.now();
+            // SDK gets a bounded chance to recover. Silence from users is irrelevant.
+            if (launching || Date.now() - unhealthySince < stalledAfterMs
+                || Date.now() - lastAttempt < stalledAfterMs)
+                return;
+            log("restarting receiving connection", { ...status, disconnectedForMs: Date.now() - unhealthySince });
+            client.close({ force: true });
+            launch();
+        }
+        catch (error) {
+            reportError(error);
+        }
+    };
+    const start = () => {
+        if (startup)
+            return startup;
+        if (stopped)
+            return Promise.reject(new Error("飞书长连接已停止"));
+        startup = new Promise((resolve, reject) => { resolveStartup = resolve; rejectStartup = reject; });
+        startupTimer = setTimeout(() => {
+            rejectStartup?.(new Error("飞书长连接握手超时，尚未收到连接成功确认"));
+            rejectStartup = undefined;
+            stop();
+        }, options.startupTimeoutMs ?? 45_000);
+        try {
+            client = options.createClient({
+                onReady: becameConnected,
+                onReconnected: becameConnected,
+                onReconnecting() {
+                    if (stopped)
+                        return;
+                    connected = false;
+                    unhealthySince ??= Date.now();
+                    log("reconnecting");
+                },
+                onError: reportError,
+            });
+            timer = setInterval(check, options.checkIntervalMs ?? 10_000);
+            timer.unref();
+            launch();
+        }
+        catch (error) {
+            rejectStartup?.(error instanceof Error ? error : new Error(String(error)));
+            rejectStartup = undefined;
+            stop();
+        }
+        return startup;
+    };
+    return { start, stop };
+}

package/dist/src/index.js

@@ -23,11 +23,12 @@
  */
 import { createServer } from "node:http";
 import { WSClient, EventDispatcher, Domain } from "@larksuiteoapi/node-sdk";
+import { createFeishuConnectionSupervisor } from "./feishu-connection.js";
 import WebSocket from "ws";
 import { appendStartupTrace, attachRelayWebSocket, ensureSingleInstance, freeRelayListenPort, installCrashLogging, installEpipeGuard, waitForPortFree } from "./shared.js";
 import { createUiRouter, setExtraApiHandler, setReloadConfigHook, startSetupMode } from "./web-ui.js";
 import { configureAgentTeamMainAgent } from "./agent-team/main-agent-bootstrap.js";
-import { buildWebUiUrl, createServiceLifecycleGuard, INTERNAL_RESTART_ENV_VAR, openWebUiInDefaultBrowser, shouldAutoOpenWebUi, } from "./startup-lifecycle.js";
+import { buildWebUiUrl, createServiceLifecycleGuard, announceInternalRestartReady, INTERNAL_RESTART_ENV_VAR, openWebUiInDefaultBrowser, shouldAutoOpenWebUi, } from "./startup-lifecycle.js";
 import { buildPlatformStartupPlan } from "./platform-startup.js";
 import { makeTraceId, logTrace } from "./trace.js";
 import { CHATCCC_PORT, config, APP_ID, APP_SECRET, FEISHU_ENABLED, FEISHU_PLATFORM_TYPE, ILINK_ENABLED, ILINK_REUSE_TOKEN_ON_START, BASE_URL, LOCAL_RELAY_URL, PID_FILE, PROJECT_ROOT, USE_LOCAL, USE_SIMULATE, appendChatLog, fileLog, reportEnvironmentVariableReadout, maskAppId, resolveDefaultAgentTool, toolDisplayName, ts, } from "./config.js";
@@ -256,6 +257,7 @@ async function startBotService(opts) {
         throw err;
     }
 }
+let feishuConnection;
 async function startBotServiceCore() {
     const modeTag = USE_LOCAL ? " (local relay mode)" : "";
     console.log(`${"=".repeat(60)}`);
@@ -420,20 +422,33 @@ async function startBotServiceCore() {
         //   - 已处理消息的去重 set 必须保留,避免 SDK 重推老消息时 prompt 跑两遍
         // 历史 bug:此处曾误调 resetState() 导致重连即让所有后台任务变孤儿,
         // 同一 session 还可能双开 prompt(详见 session.ts::resetState 注释)。
-        const wsClient = new WSClient({
-            appId: APP_ID,
-            appSecret: APP_SECRET,
-            domain: FEISHU_PLATFORM_TYPE === "lark" ? Domain.Lark : Domain.Feishu,
-            onReady: async () => {
-                await rebuildBindingsFromRegistry().catch((err) => console.error(`[${ts()}] [SDK READY] rebuild bindings failed: ${err.message}`));
+        feishuConnection?.stop();
+        feishuConnection = createFeishuConnectionSupervisor({
+            createClient(callbacks) {
+                const client = new WSClient({
+                    appId: APP_ID,
+                    appSecret: APP_SECRET,
+                    domain: FEISHU_PLATFORM_TYPE === "lark" ? Domain.Lark : Domain.Feishu,
+                    autoReconnect: true,
+                    handshakeTimeoutMs: 15_000,
+                    wsConfig: { pingTimeout: 30 },
+                    ...callbacks,
+                });
+                return {
+                    start: () => client.start({ eventDispatcher }),
+                    close: (options) => client.close(options),
+                    getConnectionStatus: () => client.getConnectionStatus(),
+                };
             },
-            onReconnected: async () => {
-                await rebuildBindingsFromRegistry().catch((err) => console.error(`[${ts()}] [SDK RECONNECT] rebuild bindings failed: ${err.message}`));
+            onConnected: rebuildBindingsFromRegistry,
+            log(event, detail) {
+                appendStartupTrace(`feishu-connection: ${event}`, detail);
+                console.log(`[${ts()}] [FEISHU-CONNECTION] ${event}${detail ? ` ${JSON.stringify(detail)}` : ""}`);
             },
         });
         console.log(`\n[启动 6/7] 飞书长连接：正在通过 SDK 建立 WebSocket …`);
         try {
-            await wsClient.start({ eventDispatcher });
+            await feishuConnection.start();
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
@@ -609,6 +624,23 @@ async function main() {
         printServiceDidNotStart("config.json 的 port 字段配置无效（须为 1–65535 的整数）");
         process.exit(1);
     }
+    const isInternalRestart = process.env[INTERNAL_RESTART_ENV_VAR] === "1";
+    if (isInternalRestart) {
+        const announced = await announceInternalRestartReady();
+        appendStartupTrace("restart-handoff: replacement preflight ready", {
+            announced,
+            port: CHATCCC_PORT,
+        });
+        const portReleased = await waitForPortFree(CHATCCC_PORT, 30_000);
+        appendStartupTrace("restart-handoff: parent port wait finished", {
+            port: CHATCCC_PORT,
+            portReleased,
+        });
+        if (!portReleased) {
+            printServiceDidNotStart(`内部重启交接超时：端口 ${CHATCCC_PORT} 在 30 秒内未释放`);
+            process.exit(1);
+        }
+    }
     console.log(`\n[启动 1/7] 单实例：按 PID 文件清理旧 ChatCCC 进程`);
     console.log(`  PID 文件: ${PID_FILE}`);
     appendStartupTrace("main: before ensureSingleInstance", { PID_FILE, CHATCCC_PORT });
@@ -680,14 +712,15 @@ async function main() {
     // 启动 HTTP server（同时挂 UI router，供 dashboard / setup / agent image/file 使用）
     appendStartupTrace("main: before freeRelayListenPort", { CHATCCC_PORT });
     const killed = freeRelayListenPort(CHATCCC_PORT);
-    const isInternalRestart = process.env[INTERNAL_RESTART_ENV_VAR] === "1";
     appendStartupTrace("main: after freeRelayListenPort", { CHATCCC_PORT, killed, isInternalRestart });
-    // 内部自重启（/restart、/update）时父进程还占着端口（祖先链 PID 不会被杀）：
-    // 无条件等待端口释放再 listen，避免子进程一上来就 EADDRINUSE 秒退
-    // （Windows 端口释放有额外延迟，重试窗口容易不够）。
-    if (killed > 0 || isInternalRestart) {
-        await waitForPortFree(CHATCCC_PORT, isInternalRestart ? 5000 : undefined);
-        appendStartupTrace("main: port free confirmed", { CHATCCC_PORT, isInternalRestart });
+    // 普通启动清理过旧实例后，也必须确认端口真正释放再继续监听。
+    if (killed > 0) {
+        const portReleased = await waitForPortFree(CHATCCC_PORT, 5_000);
+        appendStartupTrace("main: post-kill port wait finished", { CHATCCC_PORT, portReleased });
+        if (!portReleased) {
+            printServiceDidNotStart(`旧进程退出后端口 ${CHATCCC_PORT} 在 5 秒内仍未释放`);
+            process.exit(1);
+        }
     }
     const httpServer = createServer(createUiRouter());
     await listenWithRetry(httpServer, CHATCCC_PORT, "127.0.0.1").catch((err) => {
@@ -772,6 +805,7 @@ function installShutdownHandlers(httpServer, serviceLifecycle) {
     process.on("SIGINT", () => {
         console.log("\nShutting down...");
         serviceLifecycle.beginShutdown("SIGINT");
+        feishuConnection?.stop();
         wechatSignal.stopped = true;
         stopChromeDevtoolsGuard();
         httpServer.close();
@@ -779,6 +813,7 @@ function installShutdownHandlers(httpServer, serviceLifecycle) {
     });
     process.on("SIGTERM", () => {
         serviceLifecycle.beginShutdown("SIGTERM");
+        feishuConnection?.stop();
         wechatSignal.stopped = true;
         stopChromeDevtoolsGuard();
         httpServer.close();

package/dist/src/orchestrator.js

@@ -6,7 +6,7 @@
  */
 import { execSync, spawn } from "node:child_process";
 import { readdir, stat } from "node:fs/promises";
-import { appendFileSync, closeSync, existsSync, mkdirSync, openSync } from "node:fs";
+import { appendFileSync, closeSync, mkdirSync, openSync } from "node:fs";
 import { join, resolve, dirname } from "node:path";
 import { homedir } from "node:os";
 import { config as deepCccConfig } from "../deepccc-agent/src/config.js";
@@ -25,7 +25,7 @@ import { applySharedPrefix } from "./shared-prefix.js";
 import { normalizeSessionDisplayTitle, sessionChatName, sessionDisplayTitleFromPrompt, } from "./session-name.js";
 import { reloadRuntimeConfig } from "./runtime-reload.js";
 import { acquireUpdateCommandGuard } from "./update-command-guard.js";
-import { createInternalRestartEnv, INTERNAL_RESTART_ENV_VAR } from "./startup-lifecycle.js";
+import { createInternalRestartEnv, INTERNAL_RESTART_ENV_VAR, INTERNAL_RESTART_READY_MESSAGE, } from "./startup-lifecycle.js";
 import { resolveChatCccRuntimeSpawnSpec } from "./runtime-entry.js";
 import { engineManager } from "./engines/engine-specs.js";
 import { beginSafeMaintenanceTrackedWork, isSafeMaintenanceAdmissionClosed, safeMaintenanceCoordinator, } from "./safe-maintenance.js";
@@ -678,41 +678,18 @@ function syncUpdateAndRestart(options = {}) {
         appendStartupTrace("update: safe update aborted before restart", {});
         return undefined;
     }
-    // 2. resolve bin path
-    const npmPrefix = process.env.NPM_PREFIX || "";
-    const binName = process.platform === "win32" ? "chatccc.cmd" : "chatccc";
-    const binPath = npmPrefix ? join(npmPrefix, binName) : "chatccc";
-    updLog(`bin path: npmPrefix=${npmPrefix || "(empty)"}, binPath=${binPath}`);
-    appendStartupTrace("update: spawn begin", { npmPrefix: npmPrefix || "(empty)", binPath });
-    // 3. spawn new chatccc：优先 node + 全局包入口绝对路径（不依赖 PATH/shell），
-    //    避免继承环境 PATH 异常时秒退；失败时回退到 binPath（走 shell）。
+    // 2. Spawn the updated runtime directly through Node. Reusing the restart
+    // launcher guarantees an IPC handoff channel and avoids shell/PATH variance.
+    const spawnSpec = buildRestartSpawnSpec(PROJECT_ROOT);
+    updLog(`runtime path: ${spawnSpec.command} ${spawnSpec.args.join(" ")}`);
+    appendStartupTrace("update: spawn begin", { runtimeEntry: spawnSpec.args[0] });
     try {
-        let spawnSpec = null;
-        if (npmPrefix) {
-            const entry = join(npmPrefix, "node_modules", "chatccc", "bin", "chatccc.mjs");
-            if (existsSync(entry)) {
-                spawnSpec = { command: process.execPath, args: [entry] };
-            }
-        }
-        const child = spawnSpec
-            ? spawn(spawnSpec.command, spawnSpec.args, {
-                detached: true,
-                stdio: "ignore",
-                shell: false,
-                env: createInternalRestartEnv(),
-            })
-            : spawn(binPath, [], {
-                detached: true,
-                stdio: "ignore",
-                shell: true,
-                env: createInternalRestartEnv(),
-            });
+        const child = spawnRestartChild({ projectRoot: PROJECT_ROOT });
         child.unref();
-        const spawnedAs = spawnSpec ? `${spawnSpec.command} ${spawnSpec.args.join(" ")}` : binPath;
-        updLog(`spawn new chatccc OK, childPid=${child.pid}, bin=${spawnedAs}`);
+        updLog(`spawn new chatccc OK, childPid=${child.pid}, bin=${spawnSpec.command} ${spawnSpec.args.join(" ")}`);
         appendStartupTrace("update: spawn OK", {
             childPid: child.pid,
-            binPath: spawnSpec ? spawnSpec.args[0] : binPath,
+            binPath: spawnSpec.args[0],
         });
         return child;
     }
@@ -726,8 +703,8 @@ function syncUpdateAndRestart(options = {}) {
 // ---------------------------------------------------------------------------
 // /restart — 自重启子进程（不经过 npx/npm，避免 PATH 注入秒退；防空窗兜底）
 // ---------------------------------------------------------------------------
-/** 父进程等待子进程稳定启动的时间窗口（毫秒）。 */
-export const RESTART_CHILD_READY_MS = 3000;
+/** 父进程等待替代进程通过 IPC 完成启动预检的最长时间（毫秒）。 */
+export const RESTART_CHILD_READY_MS = 15_000;
 /**
  * 构建自重启的 spawn 参数：发布包直接运行编译后的 JavaScript；只有尚未
  * build 的开发工作区才使用本地 tsx CLI。两种情况都不经过 npx/npm。
@@ -735,12 +712,64 @@ export const RESTART_CHILD_READY_MS = 3000;
 export function buildRestartSpawnSpec(projectRoot = PROJECT_ROOT) {
     return resolveChatCccRuntimeSpawnSpec(projectRoot);
 }
+const restartHandoffMonitors = new WeakMap();
+function getOrCreateRestartHandoffMonitor(child) {
+    const existing = restartHandoffMonitors.get(child);
+    if (existing)
+        return existing;
+    if (typeof child.on !== "function") {
+        const unavailable = { promise: Promise.resolve({ kind: "no_ipc" }), cancel() { } };
+        restartHandoffMonitors.set(child, unavailable);
+        return unavailable;
+    }
+    const addListener = child.on.bind(child);
+    const removeListener = typeof child.off === "function"
+        ? child.off.bind(child)
+        : undefined;
+    let resolveOutcome = () => { };
+    let settled = false;
+    const cleanup = () => {
+        removeListener?.("message", onMessage);
+        removeListener?.("exit", onExit);
+        removeListener?.("error", onError);
+    };
+    const settle = (outcome) => {
+        if (settled)
+            return;
+        settled = true;
+        cleanup();
+        resolveOutcome(outcome);
+    };
+    const onMessage = (message) => {
+        const ready = message;
+        if (!ready || ready.type !== INTERNAL_RESTART_READY_MESSAGE)
+            return;
+        if (typeof ready.pid === "number" && child.pid !== undefined && ready.pid !== child.pid)
+            return;
+        if (ready.parentPid !== process.pid)
+            return;
+        settle({ kind: "ready" });
+    };
+    const onExit = () => settle({ kind: "exit" });
+    const onError = (error) => settle({ kind: "error", error });
+    const promise = new Promise((resolve) => {
+        resolveOutcome = resolve;
+    });
+    const monitor = { promise, cancel: cleanup };
+    restartHandoffMonitors.set(child, monitor);
+    addListener("message", onMessage);
+    addListener("exit", onExit);
+    addListener("error", onError);
+    if (child.exitCode !== null || child.signalCode !== null)
+        settle({ kind: "exit" });
+    return monitor;
+}
 /**
  * spawn 自重启子进程。
  *
  * stdout/stderr 按启动方式分流：
  * - **终端（TTY）场景**（用户从 cmd/PowerShell/node.exe 窗口启动）：stdio 用
- *   ["ignore", "inherit", "inherit"] 直接继承终端句柄，restart 后窗口日志不中断。
+ *   前三个 stdio 直接继承终端句柄，第四个通道保留给 IPC 握手；restart 后窗口日志不中断。
  *   终端句柄的生命周期不随父进程退出而关闭，因此不存在 EPIPE 风险。
  * - **非终端场景**（守护进程/黑匣子等管道或文件启动）：stderr 重定向到磁盘日志
  *   文件（restart-*.log），子进程继承文件句柄，父进程退出不影响写入。
@@ -756,7 +785,7 @@ export function spawnRestartChild(deps = {}) {
     const isTty = deps.isTty ?? (() => process.stdout.isTTY === true || process.stderr.isTTY === true);
     const { command, args } = buildRestartSpawnSpec(projectRoot);
     let stderrFd;
-    const stdio = ["ignore", "ignore", "pipe"];
+    const stdio = ["ignore", "ignore", "pipe", "ipc"];
     const tty = isTty();
     if (tty) {
         // 终端场景：全部 inherit（含 stdin）。注意 stdin 不能是 "ignore"：
@@ -793,8 +822,11 @@ export function spawnRestartChild(deps = {}) {
         detached: true,
         stdio,
         shell: false,
-        env: createInternalRestartEnv(),
+        env: createInternalRestartEnv(process.env, process.pid),
     });
+    // Attach before returning so an extremely fast replacement cannot emit its
+    // IPC readiness message between spawnRestartChild() and the caller's wait.
+    getOrCreateRestartHandoffMonitor(child);
     // 子进程已继承 stderr 文件句柄；父进程关闭自己的副本，避免"子进程早退、
     // 父进程留下继续服务"时 fd 泄漏。
     if (stderrFd !== undefined) {
@@ -817,24 +849,61 @@ export function spawnRestartChild(deps = {}) {
 }
 /**
  * 决定父进程是否应退出（防空窗兜底）：
- * - 窗口内子进程已退出（死亡或信号终止）→ 返回 false，父进程留下继续服务；
- * - 子进程存活满整个窗口 → 返回 true，父进程退出并把端口让给新进程。
+ * - 替代进程通过 IPC 明确完成预检 → 返回 true，父进程退出并交出端口；
+ * - 替代进程退出、报错或握手超时 → 返回 false，父进程继续服务。
  */
-export async function decideRestartParentExit(child, timeoutMs, pollMs = 500, trace = appendStartupTrace) {
-    const deadline = Date.now() + timeoutMs;
-    while (Date.now() < deadline) {
-        if (child.exitCode !== null || child.signalCode !== null) {
-            trace("restart: child died during window, keeping parent", {
-                childPid: child.pid,
-                exitCode: child.exitCode,
-                signalCode: child.signalCode,
-            });
-            return false;
+export async function decideRestartParentExit(child, timeoutMs, _pollMs = 500, trace = appendStartupTrace) {
+    if (child.exitCode !== null || child.signalCode !== null) {
+        trace("restart: child died during window, keeping parent", {
+            childPid: child.pid,
+            exitCode: child.exitCode,
+            signalCode: child.signalCode,
+        });
+        return false;
+    }
+    const monitor = getOrCreateRestartHandoffMonitor(child);
+    let timeout;
+    const timeoutOutcome = new Promise((resolve) => {
+        timeout = setTimeout(() => resolve({ kind: "no_ipc" }), timeoutMs);
+        timeout.unref?.();
+    });
+    const outcome = await Promise.race([monitor.promise, timeoutOutcome]);
+    if (timeout)
+        clearTimeout(timeout);
+    monitor.cancel();
+    if (outcome.kind === "ready") {
+        if (child.connected && typeof child.disconnect === "function") {
+            try {
+                child.disconnect();
+            }
+            catch { /* child may disconnect first */ }
+        }
+        trace("restart: child handoff ready, parent exiting", { childPid: child.pid });
+        return true;
+    }
+    if (outcome.kind === "exit") {
+        trace("restart: child died during window, keeping parent", {
+            childPid: child.pid,
+            exitCode: child.exitCode,
+            signalCode: child.signalCode,
+        });
+        return false;
+    }
+    if (outcome.kind === "error") {
+        trace("restart: child handoff error, keeping parent", {
+            childPid: child.pid,
+            error: outcome.error.message,
+        });
+        return false;
+    }
+    if (typeof child.kill === "function") {
+        try {
+            child.kill();
         }
-        await new Promise((resolve) => setTimeout(resolve, pollMs));
+        catch { /* best effort */ }
     }
-    trace("restart: child alive after window, parent exiting", { childPid: child.pid });
-    return true;
+    trace("restart: child handoff timeout, keeping parent", { childPid: child.pid });
+    return false;
 }
 const safeMaintenancePlatforms = new Map();
 export function configureSafeMaintenanceRuntime(platforms) {
@@ -1051,8 +1120,8 @@ async function handleCommandInternal(platform, text, chatId, openId, msgTimestam
         appendStartupTrace("restart: spawn begin", { fromPid: process.pid });
         const child = spawnRestartChild();
         child.unref();
-        // 子进程存活满窗口才退出父进程；若子进程在窗口内死亡，父进程留下继续
-        // 服务（防空窗），并已把子进程 stderr 写入 startup-trace 供排查。
+        // 只有替代进程通过 IPC 明确完成预检才退出父进程；超时或早退时父进程
+        // 继续服务，并保留替代进程 stderr 日志供排查。
         void decideRestartParentExit(child, RESTART_CHILD_READY_MS).then((shouldExit) => {
             if (!shouldExit)
                 return;
@@ -1100,10 +1169,9 @@ async function handleCommandInternal(platform, text, chatId, openId, msgTimestam
         await platform.sendText(chatId, "正在更新并重启，请稍候...").catch(() => { });
         logTrace(tid, "DONE", { outcome: "update" });
         appendStartupTrace("update: sync update begin", { fromPid: process.pid });
-        const child = syncUpdateAndRestart();
+        const child = syncUpdateAndRestart({ spawnOnUpdateFailure: false });
         if (child) {
-            // 子进程存活满窗口才退出父进程；若子进程在窗口内死亡，父进程留下继续
-            // 服务（防空窗）。
+            // 只有替代进程通过 IPC 明确完成预检才退出父进程；否则父进程继续服务。
             void decideRestartParentExit(child, RESTART_CHILD_READY_MS).then((shouldExit) => {
                 if (!shouldExit)
                     return;
@@ -1112,8 +1180,7 @@ async function handleCommandInternal(platform, text, chatId, openId, msgTimestam
             });
         }
         else {
-            // spawn 失败：没有子进程可等，给残留日志写入时间后退出
-            setTimeout(() => process.exit(0), 2000);
+            appendStartupTrace("update: replacement unavailable, parent stays alive", {});
         }
         return;
     }

package/dist/src/session.js

@@ -1785,7 +1785,6 @@ export function startUnifiedDisplayLoop() {
                                         console.error(`[${ts()}] [DISPLAY] terminal cardUpdate failed: ${err.message}`);
                                         if (isCardKitSequenceConflict(err)) {
                                             display.sequence = nextSeq;
-                                            terminalCardUpdateAccepted = true;
                                         }
                                     });
                                     if (terminalCardUpdateAccepted) {
@@ -1943,6 +1942,8 @@ export function startUnifiedDisplayLoop() {
                                     catch (err) {
                                         const errMsg = err.message;
                                         console.error(`[${ts()}] CardKit update error: chatId=${chatId} ${errMsg}`);
+                                        display.lastSentContent = "";
+                                        display.lastSentHeaderTitle = "";
                                         if (errMsg.includes("300317")) {
                                             display.sequence = mySeq;
                                         }
@@ -1977,6 +1978,8 @@ export function startUnifiedDisplayLoop() {
                                 catch (err) {
                                     const errMsg = err.message;
                                     console.error(`[${ts()}] CardKit update error: chatId=${chatId} ${errMsg}`);
+                                    display.lastSentContent = "";
+                                    display.lastSentHeaderTitle = "";
                                     if (errMsg.includes("300317")) {
                                         display.sequence = mySeq;
                                     }

package/dist/src/shared.js

@@ -164,25 +164,42 @@ export function freeRelayListenPort(port) {
     return killed;
 }
 /**
- * 轮询等待端口释放（Windows 下 taskkill 后端口可能不会立即释放）。
- * 在 freeRelayListenPort kill 了进程后调用，确认端口真正空闲再 listen。
+ * 跨平台轮询等待端口释放。既用于 Windows taskkill 后的延迟释放，也用于
+ * Linux/macOS 内部重启时等待父进程交出监听端口。
  */
-export async function waitForPortFree(port, timeoutMs = 3000) {
-    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)
+async function canBindLoopbackPort(port) {
+    const probe = createServer();
+    probe.unref();
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = (available) => {
+            if (settled)
                 return;
-        }
-        catch {
-            return;
-        }
-        await new Promise((r) => setTimeout(r, 200));
-    }
+            settled = true;
+            probe.removeAllListeners();
+            if (probe.listening) {
+                probe.close(() => resolve(available));
+            }
+            else {
+                resolve(available);
+            }
+        };
+        probe.once("error", () => finish(false));
+        probe.once("listening", () => finish(true));
+        probe.listen(port, "127.0.0.1");
+    });
+}
+/** Wait until the loopback port can actually be bound on every supported OS. */
+export async function waitForPortFree(port, timeoutMs = 3000, pollMs = 200) {
+    const deadline = Date.now() + timeoutMs;
+    do {
+        if (await canBindLoopbackPort(port))
+            return true;
+        if (Date.now() >= deadline)
+            break;
+        await new Promise((resolve) => setTimeout(resolve, pollMs));
+    } while (Date.now() <= deadline);
+    return false;
 }
 // ---------------------------------------------------------------------------
 // 单实例保证：PID 文件互斥（端口占用在 freeRelayListenPort + 监听前处理）

package/dist/src/startup-lifecycle.js

@@ -147,12 +147,54 @@ export function createServiceLifecycleGuard(options = {}) {
  * 会自然穿过 cmd/bash/npx 这几层启动器，因此也适用于 Windows 与 Linux。
  */
 export const INTERNAL_RESTART_ENV_VAR = "CHATCCC_INTERNAL_RESTART";
-export function createInternalRestartEnv(inherited = process.env) {
+export const INTERNAL_RESTART_PARENT_PID_ENV_VAR = "CHATCCC_RESTART_PARENT_PID";
+export const INTERNAL_RESTART_READY_MESSAGE = "chatccc:restart-handoff-ready";
+export function createInternalRestartEnv(inherited = process.env, parentPid = process.pid) {
     return {
         ...inherited,
         [INTERNAL_RESTART_ENV_VAR]: "1",
+        [INTERNAL_RESTART_PARENT_PID_ENV_VAR]: String(parentPid),
     };
 }
+/**
+ * Tell the current parent that the replacement runtime loaded successfully and
+ * is ready to wait for the listening port. Older parents do not provide IPC;
+ * returning false preserves the port-wait fallback used during an upgrade from
+ * a pre-handoff ChatCCC version.
+ */
+export async function announceInternalRestartReady(options = {}) {
+    const env = options.env ?? process.env;
+    if (env[INTERNAL_RESTART_ENV_VAR] !== "1")
+        return false;
+    const send = options.send ?? (typeof process.send === "function"
+        ? process.send.bind(process)
+        : undefined);
+    if (!send)
+        return false;
+    const pid = options.pid ?? process.pid;
+    const parentPid = Number(env[INTERNAL_RESTART_PARENT_PID_ENV_VAR]);
+    if (!Number.isInteger(parentPid) || parentPid <= 0)
+        return false;
+    const timeoutMs = options.timeoutMs ?? 2_000;
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = (ok) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(ok);
+        };
+        const timer = setTimeout(() => finish(false), timeoutMs);
+        timer.unref?.();
+        try {
+            send({ type: INTERNAL_RESTART_READY_MESSAGE, pid, parentPid }, (error) => finish(!error));
+        }
+        catch {
+            finish(false);
+        }
+    });
+}
 export function shouldAutoOpenWebUi(options = {}) {
     const env = options.env ?? process.env;
     return options.openOnStart !== false && env[INTERNAL_RESTART_ENV_VAR] !== "1";

package/dist/src/terminal-error.js

@@ -64,7 +64,7 @@ export function classifyTerminalError(error, occurredAt = Date.now()) {
             occurredAt,
         };
     }
-    if (/econnrefused|econnreset|enotfound|eai_again|socket hang up|network error|cannot connect/.test(lower)) {
+    if (/econnrefused|econnreset|enotfound|eai_again|socket hang up|network error|cannot connect|tls handshake|before secure tls connection|stream disconnected before completion|websocket closed/.test(lower)) {
         return {
             kind: "network",
             title: "无法连接模型服务",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chatccc",
-  "version": "0.2.280",
+  "version": "0.2.282",
   "description": "Feishu bot bridge for Claude Code",
   "license": "Apache-2.0",
   "type": "module",
@@ -53,7 +53,7 @@
   "dependencies": {
     "@ai-sdk/anthropic": "^3.0.105",
     "@ai-sdk/openai-compatible": "^2.0.47",
-    "@larksuiteoapi/node-sdk": "^1.59.0",
+    "@larksuiteoapi/node-sdk": "^1.66.1",
     "@openilink/openilink-sdk-node": "^0.6.0",
     "@vscode/ripgrep": "^1.18.0",
     "ai": "^6.0.184",