chatccc 0.2.298 → 0.2.299

package/README.md

@@ -455,7 +455,7 @@ ChatCCC 通过 Codex 的 **app-server 模式**（一个常驻进程 + WebSocket
 
 `/restart safe`（短别名 `/restartsf`）与 `/update safe`（短别名 `/updatesf`）会先建立全局准入门禁：指令到达前已经运行或进入单会话缓存队列的工作会继续完成，之后到达的新普通任务会被提示在维护完成后重发。维护任务持久化到 `~/.chatccc/state/safe-maintenance.json`，进程意外退出后可继续排空；依赖安装、会话收尾、自动恢复和 Agent Teams 执行也计入等待条件。内存缓存随重启自然重建，磁盘会话、看板、图片等持久数据不会被清理。
 
-ChatCCC 的内部重启和更新使用跨平台父子进程握手：替代进程完成启动预检后通知父进程退出，再等待旧监听端口实际释放并接管 PID；替代进程未就绪或握手超时时，父进程会保留并继续服务。
+ChatCCC 的普通内部重启使用跨平台父子进程握手：替代进程完成启动预检后通知父进程退出，再等待旧监听端口实际释放并接管 PID；替代进程未就绪或握手超时时，父进程会保留并继续服务。自更新则先把仅依赖 Node.js 的更新器复制到 `~/.chatccc/update/`，确认更新器就绪后退出旧进程，再由安装目录外的更新器执行 npm 安装并启动新版，从而避免 Windows 因运行中进程或原生模块占用全局包目录而报 `EBUSY`。更新失败时会尝试恢复并重启原版本，详细记录写入 `~/.chatccc/logs/update-watcher.log`。
 
 Codex 和 Cursor 在 Linux/macOS 下使用独立进程组。停止时先显示“正在停止”，待进程组内后代退出后再显示“已停止”；仅外层 shell 退出不算清理完成。重复停止请求合并处理，清理失败会保留会话进程占用保护并报告“Agent 停止未完成”，后续请求必须先完成清理才能启动新 Agent。Windows 继续使用 `taskkill /T /F`，命令失败或超时不会当作成功。
 

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, mkdirSync, openSync } from "node:fs";
+import { 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";
@@ -27,6 +27,7 @@ import { reloadRuntimeConfig } from "./runtime-reload.js";
 import { acquireUpdateCommandGuard } from "./update-command-guard.js";
 import { createInternalRestartEnv, INTERNAL_RESTART_ENV_VAR, INTERNAL_RESTART_READY_MESSAGE, } from "./startup-lifecycle.js";
 import { resolveChatCccRuntimeSpawnSpec } from "./runtime-entry.js";
+import { SELF_UPDATE_ERROR_ENV_VAR, SELF_UPDATE_RESULT_ENV_VAR, spawnSelfUpdateHelper, waitForSelfUpdateHelperReady, } from "./self-update.js";
 import { engineManager } from "./engines/engine-specs.js";
 import { beginSafeMaintenanceTrackedWork, isSafeMaintenanceAdmissionClosed, safeMaintenanceCoordinator, } from "./safe-maintenance.js";
 import { feishuP2pContactStore, isValidFeishuOpenId, } from "./agent-team/repositories/feishu-p2p-contact-store.js";
@@ -625,80 +626,28 @@ function isRunningFromGlobalNpm() {
         return false;
     }
 }
-const UPDATE_LOG = join(homedir(), ".chatccc", "logs", "update-watcher.log");
-function updLog(msg) {
-    const ts = new Date().toISOString();
-    try {
-        appendFileSync(UPDATE_LOG, `${ts} [UPDATE-SYNC] ${msg}\n`, "utf-8");
-    }
-    catch { }
-}
-/** 同步更新 npm 全局包并 spawn 新进程重启。不依赖 systemd 或任何服务管理器。 */
-function syncUpdateAndRestart(options = {}) {
-    updLog(`sync update start, pid=${process.pid}`);
-    appendStartupTrace("update: sync update start", { pid: process.pid });
-    const npmCmd = process.platform === "win32" ? "npm.cmd" : "npm";
-    let updateSucceeded = false;
-    // 1. npm update
-    updLog(`running: ${npmCmd} update -g chatccc`);
-    appendStartupTrace("update: npm update begin", { npmCmd });
-    const t0 = Date.now();
+/**
+ * 将真正的 npm 更新交给安装目录外的独立进程。父进程只在更新器确认读入任务后
+ * 退出；更新器随后等待本进程和 npm bin 包装器释放目录，再安装并启动新版。
+ */
+async function exitForExternalSelfUpdate() {
+    let child;
     try {
-        const out = execSync(`${npmCmd} update -g chatccc 2>&1`, { encoding: "utf8", timeout: 120000, windowsHide: true });
-        const elapsed = Date.now() - t0;
-        updLog(`npm update OK (${elapsed}ms): ${out.slice(0, 500)}`);
-        appendStartupTrace("update: npm update OK", { elapsedMs: elapsed, outputLen: out.length });
-        updateSucceeded = true;
-    }
-    catch (e) {
-        const elapsed = Date.now() - t0;
-        const err = e;
-        updLog(`npm update failed (${elapsed}ms): message=${err.message}, stderr=${(err.stderr || "").slice(0, 500)}, stdout=${(err.stdout || "").slice(0, 200)}`);
-        appendStartupTrace("update: npm update failed", { elapsedMs: elapsed, message: err.message, stderrLen: (err.stderr || "").length });
-        // fallback
-        updLog(`fallback: ${npmCmd} install -g chatccc@latest`);
-        appendStartupTrace("update: npm install fallback begin", { npmCmd });
-        const t1 = Date.now();
-        try {
-            const out2 = execSync(`${npmCmd} install -g chatccc@latest 2>&1`, { encoding: "utf8", timeout: 120000, windowsHide: true });
-            const elapsed2 = Date.now() - t1;
-            updLog(`npm install fallback OK (${elapsed2}ms): ${out2.slice(0, 500)}`);
-            appendStartupTrace("update: npm install fallback OK", { elapsedMs: elapsed2, outputLen: out2.length });
-            updateSucceeded = true;
-        }
-        catch (e2) {
-            const elapsed2 = Date.now() - t1;
-            const err2 = e2;
-            updLog(`npm install fallback also failed (${elapsed2}ms): message=${err2.message}, stderr=${(err2.stderr || "").slice(0, 500)}`);
-            appendStartupTrace("update: npm install fallback failed", { elapsedMs: elapsed2, message: err2.message });
-        }
-    }
-    if (!updateSucceeded && options.spawnOnUpdateFailure === false) {
-        updLog("safe update aborted: both npm update and fallback install failed");
-        appendStartupTrace("update: safe update aborted before restart", {});
-        return undefined;
+        child = spawnSelfUpdateHelper();
     }
-    // 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 {
-        const child = spawnRestartChild({ projectRoot: PROJECT_ROOT });
-        child.unref();
-        updLog(`spawn new chatccc OK, childPid=${child.pid}, bin=${spawnSpec.command} ${spawnSpec.args.join(" ")}`);
-        appendStartupTrace("update: spawn OK", {
-            childPid: child.pid,
-            binPath: spawnSpec.args[0],
+    catch (error) {
+        appendStartupTrace("update: external helper spawn failed", {
+            error: error.message,
         });
-        return child;
-    }
-    catch (e) {
-        const errMsg = e.message;
-        updLog(`spawn new chatccc failed: ${errMsg}`);
-        appendStartupTrace("update: spawn failed", { error: errMsg });
-        return undefined;
+        return false;
     }
+    const ready = await waitForSelfUpdateHelperReady(child);
+    if (!ready)
+        return false;
+    child.unref();
+    fileLog.flush();
+    appendStartupTrace("update: parent exit for external helper", { childPid: child.pid });
+    process.exit(0);
 }
 // ---------------------------------------------------------------------------
 // /restart — 自重启子进程（不经过 npx/npm，避免 PATH 注入秒退；防空窗兜底）
@@ -933,7 +882,14 @@ export function configureSafeMaintenanceRuntime(platforms) {
     });
 }
 export function recoverSafeMaintenanceAfterStartup() {
-    return safeMaintenanceCoordinator.recoverAfterStartup(process.env[INTERNAL_RESTART_ENV_VAR] === "1");
+    const updateResult = process.env[SELF_UPDATE_RESULT_ENV_VAR];
+    return safeMaintenanceCoordinator.recoverAfterStartup(process.env[INTERNAL_RESTART_ENV_VAR] === "1", updateResult === "failed"
+        ? {
+            succeeded: false,
+            error: process.env[SELF_UPDATE_ERROR_ENV_VAR]
+                || "ChatCCC 更新失败，已恢复更新前版本。",
+        }
+        : undefined);
 }
 async function executeSafeRestart() {
     fileLog.flush();
@@ -949,15 +905,7 @@ async function executeSafeRestart() {
 async function executeSafeUpdate() {
     fileLog.flush();
     appendStartupTrace("safe-maintenance: update begin", { fromPid: process.pid });
-    const child = syncUpdateAndRestart({ spawnOnUpdateFailure: false });
-    if (!child)
-        return false;
-    child.unref();
-    const shouldExit = await decideRestartParentExit(child, RESTART_CHILD_READY_MS);
-    if (!shouldExit)
-        return false;
-    appendStartupTrace("safe-maintenance: update parent exit", { childPid: child.pid });
-    process.exit(0);
+    return exitForExternalSelfUpdate();
 }
 function safeMaintenanceRequester(platform, chatId, openId) {
     return { platform: platform.kind ?? "feishu", chatId, openId };
@@ -1168,19 +1116,11 @@ async function handleCommandInternal(platform, text, chatId, openId, msgTimestam
             await safeMaintenanceCoordinator.cancel(false);
         await platform.sendText(chatId, "正在更新并重启，请稍候...").catch(() => { });
         logTrace(tid, "DONE", { outcome: "update" });
-        appendStartupTrace("update: sync update begin", { fromPid: process.pid });
-        const child = syncUpdateAndRestart({ spawnOnUpdateFailure: false });
-        if (child) {
-            // 只有替代进程通过 IPC 明确完成预检才退出父进程；否则父进程继续服务。
-            void decideRestartParentExit(child, RESTART_CHILD_READY_MS).then((shouldExit) => {
-                if (!shouldExit)
-                    return;
-                appendStartupTrace("update: parent exit", { childPid: child.pid });
-                process.exit(0);
-            });
-        }
-        else {
-            appendStartupTrace("update: replacement unavailable, parent stays alive", {});
+        appendStartupTrace("update: external helper begin", { fromPid: process.pid });
+        const started = await exitForExternalSelfUpdate();
+        if (!started) {
+            appendStartupTrace("update: external helper unavailable, parent stays alive", {});
+            await platform.sendText(chatId, "更新器启动失败，ChatCCC 将继续运行。请查看 ~/.chatccc/logs/update-watcher.log。").catch(() => { });
         }
         return;
     }

package/dist/src/safe-maintenance.js

@@ -134,7 +134,7 @@ export class SafeMaintenanceCoordinator {
             this.tickRunning = false;
         }
     }
-    async recoverAfterStartup(internalRestart) {
+    async recoverAfterStartup(internalRestart, maintenanceResult) {
         if (!this.job || !this.runtime)
             return;
         if (this.job.phase === "draining") {
@@ -142,9 +142,29 @@ export class SafeMaintenanceCoordinator {
             await this.notifyAll(this.job.requesters, "ChatCCC 已恢复未完成的安全维护预约，继续等待现有任务结束。");
             return;
         }
+        if (this.job.phase === "failed"
+            && this.job.kind === "update"
+            && internalRestart
+            && maintenanceResult?.succeeded === false) {
+            await this.notifyAll(this.job.requesters, this.job.lastError || maintenanceResult.error || "ChatCCC 更新失败，已恢复更新前版本。");
+            return;
+        }
         if (this.job.phase !== "executing")
             return;
         if (internalRestart) {
+            if (this.job.kind === "update" && maintenanceResult?.succeeded === false) {
+                const message = maintenanceResult.error || "ChatCCC 更新失败，已恢复更新前版本。";
+                const failed = {
+                    ...this.job,
+                    phase: "failed",
+                    updatedAt: this.now().toISOString(),
+                    lastError: message,
+                };
+                writeJob(this.filePath, failed);
+                this.job = failed;
+                await this.notifyAll(this.job.requesters, message);
+                return;
+            }
             const completed = { ...this.job, phase: "completed", updatedAt: this.now().toISOString() };
             writeJob(this.filePath, completed);
             this.job = completed;

package/dist/src/self-update.js

@@ -0,0 +1,170 @@
+import { spawn } from "node:child_process";
+import { closeSync, copyFileSync, mkdirSync, openSync, readFileSync, writeFileSync, } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { PROJECT_ROOT, USER_DATA_DIR } from "./config.js";
+import { resolveNpmInvocation } from "./engines/engine-manager.js";
+import { appendStartupTrace } from "./shared.js";
+export const SELF_UPDATE_HELPER_READY_MESSAGE = "chatccc:self-update-helper-ready";
+export const SELF_UPDATE_RESULT_ENV_VAR = "CHATCCC_SELF_UPDATE_RESULT";
+export const SELF_UPDATE_ERROR_ENV_VAR = "CHATCCC_SELF_UPDATE_ERROR";
+const helperMonitors = new WeakMap();
+function monitorSelfUpdateHelper(child, expectedParentPid) {
+    const existing = helperMonitors.get(child);
+    if (existing)
+        return existing;
+    if (typeof child.on !== "function") {
+        const unavailable = {
+            promise: Promise.resolve({ kind: "exit" }),
+            cancel() { },
+        };
+        helperMonitors.set(child, unavailable);
+        return unavailable;
+    }
+    const addListener = child.on.bind(child);
+    const removeListener = typeof child.off === "function"
+        ? child.off.bind(child)
+        : undefined;
+    let settlePromise = () => { };
+    let settled = false;
+    const cleanup = () => {
+        removeListener?.("message", onMessage);
+        removeListener?.("exit", onExit);
+        removeListener?.("error", onError);
+    };
+    const settle = (outcome) => {
+        if (settled)
+            return;
+        settled = true;
+        cleanup();
+        settlePromise(outcome);
+    };
+    const onMessage = (message) => {
+        const ready = message;
+        if (!ready || ready.type !== SELF_UPDATE_HELPER_READY_MESSAGE)
+            return;
+        if (ready.parentPid !== expectedParentPid)
+            return;
+        if (typeof ready.pid === "number" && child.pid !== undefined && ready.pid !== child.pid)
+            return;
+        settle({ kind: "ready" });
+    };
+    const onExit = () => settle({ kind: "exit" });
+    const onError = (error) => settle({ kind: "error", error });
+    const promise = new Promise((resolvePromise) => {
+        settlePromise = resolvePromise;
+    });
+    const monitor = { promise, cancel: cleanup };
+    helperMonitors.set(child, monitor);
+    addListener("message", onMessage);
+    addListener("exit", onExit);
+    addListener("error", onError);
+    if (child.exitCode !== null || child.signalCode !== null)
+        settle({ kind: "exit" });
+    return monitor;
+}
+/**
+ * 将更新器复制到 ~/.chatccc 后再启动。更新器本身和 cwd 都不位于 npm 包目录，
+ * 因而主进程退出后 npm 可以在 Windows 上重命名或替换全局安装目录。
+ */
+export function spawnSelfUpdateHelper(options = {}) {
+    const projectRoot = options.projectRoot ?? PROJECT_ROOT;
+    const userDataDir = options.userDataDir ?? USER_DATA_DIR;
+    const helperSourcePath = options.helperSourcePath
+        ?? join(projectRoot, "scripts", "self-update-helper.mjs");
+    const parentPid = options.parentPid ?? process.pid;
+    const npmInvocation = options.npmInvocation ?? resolveNpmInvocation();
+    const spawnImpl = options.spawnImpl ?? spawn;
+    const trace = options.trace ?? appendStartupTrace;
+    const packageJson = JSON.parse(readFileSync(join(projectRoot, "package.json"), "utf8"));
+    if (packageJson.name !== "chatccc" || typeof packageJson.version !== "string") {
+        throw new Error("当前安装目录缺少有效的 chatccc package.json。");
+    }
+    const updateDir = join(userDataDir, "update");
+    const logDir = join(userDataDir, "logs");
+    mkdirSync(updateDir, { recursive: true });
+    mkdirSync(logDir, { recursive: true });
+    const id = `${Date.now()}-${randomUUID()}`;
+    const helperPath = join(updateDir, `self-update-helper-${id}.mjs`);
+    const jobPath = join(updateDir, `self-update-job-${id}.json`);
+    const resultFile = join(updateDir, `self-update-result-${id}.json`);
+    copyFileSync(helperSourcePath, helperPath);
+    const job = {
+        schemaVersion: 1,
+        parentPid,
+        packageRoot: projectRoot,
+        previousVersion: packageJson.version,
+        restartCwd: userDataDir || homedir(),
+        npmCommand: npmInvocation.command,
+        npmArgsPrefix: [...npmInvocation.argsPrefix],
+        runtimeCommand: process.execPath,
+        runtimeEntry: join(projectRoot, "dist", "src", "index.js"),
+        resultFile,
+        safeMaintenanceFile: join(userDataDir, "state", "safe-maintenance.json"),
+        cleanupPaths: [jobPath, helperPath],
+    };
+    writeFileSync(jobPath, JSON.stringify(job, null, 2), "utf8");
+    const logPath = join(logDir, "update-watcher.log");
+    const logFd = openSync(logPath, "a");
+    const stdio = ["ignore", logFd, logFd, "ipc"];
+    trace("update: external helper spawn", {
+        helperPath,
+        jobPath,
+        packageRoot: projectRoot,
+        cwd: userDataDir,
+    });
+    try {
+        const child = spawnImpl(process.execPath, [helperPath, jobPath], {
+            cwd: userDataDir,
+            detached: true,
+            stdio,
+            shell: false,
+            windowsHide: true,
+            env: process.env,
+        });
+        monitorSelfUpdateHelper(child, parentPid);
+        return child;
+    }
+    finally {
+        closeSync(logFd);
+    }
+}
+/**
+ * 只有外置更新器确认已读入任务后，主进程才可退出。若更新器早退或超时，
+ * 保留当前服务并终止更新器，避免服务空窗。
+ */
+export async function waitForSelfUpdateHelperReady(child, timeoutMs = 5_000, trace = appendStartupTrace) {
+    const monitor = helperMonitors.get(child) ?? monitorSelfUpdateHelper(child, process.pid);
+    let timer;
+    const timeout = new Promise((resolvePromise) => {
+        timer = setTimeout(() => resolvePromise({ kind: "exit" }), timeoutMs);
+        timer.unref?.();
+    });
+    const outcome = await Promise.race([monitor.promise, timeout]);
+    if (timer)
+        clearTimeout(timer);
+    monitor.cancel();
+    if (outcome.kind === "ready") {
+        if (child.connected && typeof child.disconnect === "function") {
+            try {
+                child.disconnect();
+            }
+            catch { /* helper may disconnect first */ }
+        }
+        trace("update: external helper ready", { childPid: child.pid });
+        return true;
+    }
+    if (typeof child.kill === "function") {
+        try {
+            child.kill();
+        }
+        catch { /* best effort */ }
+    }
+    trace("update: external helper unavailable", {
+        childPid: child.pid,
+        outcome: outcome.kind,
+        error: outcome.kind === "error" ? outcome.error.message : undefined,
+    });
+    return false;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chatccc",
-  "version": "0.2.298",
+  "version": "0.2.299",
   "description": "Feishu bot bridge for Claude Code",
   "license": "Apache-2.0",
   "type": "module",
@@ -14,6 +14,7 @@
     "deepccc-agent/os-prompts/",
     "bin/",
     "scripts/postinstall-sharp-check.mjs",
+    "scripts/self-update-helper.mjs",
     "demo/ilink_echo_probe.ts",
     "agent-prompts/",
     "im-skills/",

package/scripts/self-update-helper.mjs

@@ -0,0 +1,301 @@
+import { spawn, spawnSync } from "node:child_process";
+import {
+  existsSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+const READY_MESSAGE = "chatccc:self-update-helper-ready";
+const INTERNAL_RESTART_ENV = "CHATCCC_INTERNAL_RESTART";
+const RESTART_PARENT_PID_ENV = "CHATCCC_RESTART_PARENT_PID";
+const UPDATE_RESULT_ENV = "CHATCCC_SELF_UPDATE_RESULT";
+const UPDATE_ERROR_ENV = "CHATCCC_SELF_UPDATE_ERROR";
+
+function log(message, details) {
+  const suffix = details === undefined
+    ? ""
+    : ` ${typeof details === "string" ? details : JSON.stringify(details)}`;
+  console.log(`${new Date().toISOString()} [UPDATE-HELPER] ${message}${suffix}`);
+}
+
+function sleep(ms) {
+  return new Promise((resolvePromise) => setTimeout(resolvePromise, ms));
+}
+
+function pidIsAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code === "EPERM";
+  }
+}
+
+async function waitForParentExit(parentPid, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (pidIsAlive(parentPid)) {
+    if (Date.now() >= deadline) return false;
+    await sleep(100);
+  }
+  // npm 的 bin 包装器会在主进程结束后才从 spawnSync 返回；留出短暂时间，
+  // 让包装器也退出并释放它继承的 Windows 当前目录句柄。
+  await sleep(300);
+  return true;
+}
+
+function readInstalledPackage(job) {
+  const packageJsonPath = resolve(job.packageRoot, "package.json");
+  const parsed = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+  if (parsed?.name !== "chatccc" || typeof parsed.version !== "string") {
+    throw new Error("安装后的 package.json 无效。");
+  }
+  if (!existsSync(job.runtimeEntry)) {
+    throw new Error(`安装后的运行入口不存在：${job.runtimeEntry}`);
+  }
+  return parsed;
+}
+
+function runNpmInstall(job, packageSpec) {
+  const args = [
+    ...job.npmArgsPrefix,
+    "install",
+    "-g",
+    packageSpec,
+    "--no-audit",
+    "--no-fund",
+  ];
+  log("npm install begin", {
+    command: job.npmCommand,
+    args,
+    cwd: job.restartCwd,
+  });
+  const result = spawnSync(job.npmCommand, args, {
+    cwd: job.restartCwd,
+    env: process.env,
+    encoding: "utf8",
+    maxBuffer: 8 * 1024 * 1024,
+    timeout: 180_000,
+    windowsHide: true,
+    shell: false,
+  });
+  const output = `${result.stdout ?? ""}\n${result.stderr ?? ""}`.trim();
+  log("npm install end", {
+    packageSpec,
+    status: result.status,
+    signal: result.signal,
+    error: result.error?.message,
+    output: output.slice(-4_000),
+  });
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    throw new Error(`npm install ${packageSpec} 失败（退出码 ${result.status ?? "unknown"}）：${output.slice(-1_000)}`);
+  }
+}
+
+async function installWithRetry(job, packageSpec) {
+  const attempts = Number.isInteger(job.maxInstallAttempts) && job.maxInstallAttempts > 0
+    ? job.maxInstallAttempts
+    : 3;
+  let lastError;
+  for (let attempt = 1; attempt <= attempts; attempt += 1) {
+    try {
+      runNpmInstall(job, packageSpec);
+      return;
+    } catch (error) {
+      lastError = error;
+      log("npm install attempt failed", {
+        packageSpec,
+        attempt,
+        attempts,
+        error: error instanceof Error ? error.message : String(error),
+      });
+      if (attempt < attempts) await sleep(500 * attempt);
+    }
+  }
+  throw lastError ?? new Error(`npm install ${packageSpec} 失败。`);
+}
+
+function persistResult(job, result) {
+  const temporary = `${job.resultFile}.${process.pid}.tmp`;
+  writeFileSync(temporary, JSON.stringify({
+    schemaVersion: 1,
+    completedAt: new Date().toISOString(),
+    ...result,
+  }, null, 2), "utf8");
+  renameSync(temporary, job.resultFile);
+}
+
+function markSafeUpdateFailed(job, message) {
+  if (!job.safeMaintenanceFile || !existsSync(job.safeMaintenanceFile)) return;
+  try {
+    const current = JSON.parse(readFileSync(job.safeMaintenanceFile, "utf8"));
+    if (current?.kind !== "update" || current.phase !== "executing") return;
+    const failed = {
+      ...current,
+      phase: "failed",
+      updatedAt: new Date().toISOString(),
+      lastError: message,
+    };
+    const temporary = `${job.safeMaintenanceFile}.${process.pid}.tmp`;
+    writeFileSync(temporary, JSON.stringify(failed, null, 2), "utf8");
+    renameSync(temporary, job.safeMaintenanceFile);
+    log("safe update state marked failed");
+  } catch (error) {
+    log("failed to persist safe update failure", error instanceof Error ? error.message : String(error));
+  }
+}
+
+function launchRuntime(job, status, errorMessage) {
+  const env = {
+    ...process.env,
+    [INTERNAL_RESTART_ENV]: "1",
+    [RESTART_PARENT_PID_ENV]: String(process.pid),
+    [UPDATE_RESULT_ENV]: status,
+  };
+  if (errorMessage) env[UPDATE_ERROR_ENV] = errorMessage.slice(0, 2_000);
+  const child = spawn(job.runtimeCommand, [job.runtimeEntry], {
+    cwd: job.restartCwd,
+    detached: true,
+    stdio: ["ignore", "ignore", "inherit"],
+    shell: false,
+    windowsHide: true,
+    env,
+  });
+  child.unref();
+  log("runtime launched", {
+    pid: child.pid,
+    status,
+    command: job.runtimeCommand,
+    entry: job.runtimeEntry,
+    cwd: job.restartCwd,
+  });
+}
+
+function validateJob(job) {
+  if (
+    job?.schemaVersion !== 1
+    || !Number.isInteger(job.parentPid)
+    || job.parentPid <= 0
+    || typeof job.packageRoot !== "string"
+    || typeof job.previousVersion !== "string"
+    || typeof job.restartCwd !== "string"
+    || typeof job.npmCommand !== "string"
+    || !Array.isArray(job.npmArgsPrefix)
+    || !job.npmArgsPrefix.every((arg) => typeof arg === "string")
+    || typeof job.runtimeCommand !== "string"
+    || typeof job.runtimeEntry !== "string"
+    || typeof job.resultFile !== "string"
+    || (job.safeMaintenanceFile !== undefined && typeof job.safeMaintenanceFile !== "string")
+    || (job.cleanupPaths !== undefined && (
+      !Array.isArray(job.cleanupPaths)
+      || !job.cleanupPaths.every((path) => typeof path === "string")
+    ))
+  ) {
+    throw new Error("自更新任务文件无效。");
+  }
+  return job;
+}
+
+async function announceReady(job) {
+  if (typeof process.send !== "function") return;
+  await new Promise((resolvePromise) => {
+    try {
+      process.send({
+        type: READY_MESSAGE,
+        pid: process.pid,
+        parentPid: job.parentPid,
+      }, () => resolvePromise());
+    } catch {
+      resolvePromise();
+    }
+  });
+  try { process.disconnect?.(); } catch { /* parent may disconnect first */ }
+}
+
+export async function runSelfUpdateJob(job) {
+  const parentExited = await waitForParentExit(
+    job.parentPid,
+    job.parentExitTimeoutMs ?? 30_000,
+  );
+  if (!parentExited) {
+    throw new Error(`旧 ChatCCC 进程 ${job.parentPid} 未在限定时间内退出，已取消更新。`);
+  }
+
+  try {
+    await installWithRetry(job, "chatccc@latest");
+    const installed = readInstalledPackage(job);
+    persistResult(job, {
+      status: "success",
+      previousVersion: job.previousVersion,
+      installedVersion: installed.version,
+      rollbackSucceeded: false,
+    });
+    launchRuntime(job, "success");
+  } catch (updateError) {
+    const message = updateError instanceof Error ? updateError.message : String(updateError);
+    log("latest installation failed; rollback begin", {
+      previousVersion: job.previousVersion,
+      error: message,
+    });
+    let rollbackSucceeded = false;
+    try {
+      await installWithRetry(job, `chatccc@${job.previousVersion}`);
+      readInstalledPackage(job);
+      rollbackSucceeded = true;
+    } catch (rollbackError) {
+      log("rollback failed", rollbackError instanceof Error ? rollbackError.message : String(rollbackError));
+      // npm 可能只在 postinstall 等末尾步骤失败；若入口仍完整，则优先恢复服务。
+      try {
+        readInstalledPackage(job);
+        rollbackSucceeded = true;
+        log("existing runtime remains usable after rollback failure");
+      } catch {
+        // 包目录确实不可用，只能保留结果和日志供人工恢复。
+      }
+    }
+    persistResult(job, {
+      status: "failed",
+      previousVersion: job.previousVersion,
+      rollbackSucceeded,
+      error: message,
+    });
+    markSafeUpdateFailed(job, message);
+    if (!rollbackSucceeded) {
+      throw new Error(`更新失败且无法恢复旧版本：${message}`);
+    }
+    launchRuntime(job, "failed", message);
+  }
+}
+
+async function main() {
+  const jobPath = process.argv[2];
+  if (!jobPath) throw new Error("缺少自更新任务文件路径。");
+  const job = validateJob(JSON.parse(readFileSync(jobPath, "utf8")));
+  log("helper started", {
+    pid: process.pid,
+    parentPid: job.parentPid,
+    packageRoot: job.packageRoot,
+    helper: basename(process.argv[1]),
+  });
+  await announceReady(job);
+  try {
+    await runSelfUpdateJob(job);
+  } finally {
+    for (const path of job.cleanupPaths ?? []) {
+      try { rmSync(path, { force: true }); } catch { /* best effort */ }
+    }
+  }
+}
+
+const invokedDirectly = process.argv[1]
+  && import.meta.url === pathToFileURL(resolve(process.argv[1])).href;
+if (invokedDirectly) {
+  main().catch((error) => {
+    log("fatal", error instanceof Error ? error.stack ?? error.message : String(error));
+    process.exitCode = 1;
+  });
+}