[Windows/Desktop] 内置更新在“停止 Host”阶段失败：旧版 Host 退出慢被 SIGTERM，Shell 判定非干净退出而拒绝安装

[Megumyii]

[Windows/Desktop] 内置更新在“停止 Host”阶段失败：旧版 Host 退出慢被 SIGTERM，Shell 判定非干净退出而拒绝安装

这是准备提交到 GitHub Discussions 的反馈草稿（该仓库 has_issues: false，README 指定 Discussions 为反馈渠道）。
提交位置：https://github.com/deepseek-ai/deepseek-harness/discussions

TL;DR（English）

On Windows, the in-app desktop update fails at the "stop the Host" step. The Shell gives the Host process 10 s to exit after the Host acknowledges shutdown, then sends SIGTERM and refuses to install because the exit was not graceful (exit null, signal SIGTERM, shutdown acknowledged true, graceful deadline exceeded true). Older nightly builds (0.2.1-rc.2 and 0.2.1-rc.5) do not force process.exit() after shutdown-complete, so a leaked handle can keep the Host alive past the deadline. Result: those builds can never self-update from the GUI — a one-way door — and users must quit the app and run the already-downloaded installer manually. 0.2.2-rc.1 and current master already force process.exit() in apps/desktop-host/src/index.ts, but the Shell-side refusal is unchanged, so the dead end remains for anyone still on an older build.

环境

项目	值
OS	Windows 11 24H2，10.0.26100.4652（注册表 ProductName 显示 "Windows 10 Home China"）
桌面端	DeepSeek Harness，nightly 通道（app-update.yml: provider generic, https://download.deepseek.com/dsh-desk/feeds/win-x64/）
安装位置	D:\software\DSH（非默认安装目录）
观察到的版本对	① 0.2.1-rc.2 → 待装 0.2.1-rc.3（2026-10-27） ② 0.2.1-rc.5 → 待装 0.2.2-rc.1（2026-11-13）

现象

点击“安装并重启更新”后弹出：

未能安全停止任务，更新尚未安装，请稍后重试。

“查看技术详情”展开为：

desktop update: Host did not complete graceful task teardown
(exit null, signal SIGTERM, shutdown acknowledged true, graceful deadline exceeded true)

• 应用本身继续运行（Shell 会重新拉起 Host），更新没有安装；
• 已下载的安装包留在更新器缓存里；
• 点“重试更新”会再次走同一条路径，仍然失败；
• 安装包本身完好：sha512 与 update-info.json 记录一致，Authenticode 签名有效（Hangzhou DeepSeek Artificial Intelligence Co., Ltd.），FileVersion 与目标版本一致。

复现步骤

1. 在 nightly 通道检测到新版本并完成下载，点“安装并重启”。
2. 应用刚启动不久、没有任务在运行、会话为空（两次都发生在启动后约 1–2 分钟：15:11:51 启动 / 15:12:48 尝试；14:38:37 启动 / 14:40:19 尝试）。
3. Shell 通过 update-tasks 确认没有活动任务后进入停止阶段：向 Host 发 shutdown。
4. Host 完成应用层收尾并回 shutdown-complete（所以 shutdown acknowledged true），但进程本身在 10 秒内没有退出。
5. Shell 到点后发 SIGTERM 强杀，进程以 exit null / signal SIGTERM 结束。
6. Shell 判定“非干净退出”，抛 DesktopHostUncleanExitError → stop-failed → 拒绝安装并弹窗。

同一台机器、两个不同版本对上各复现一次（2/2）。

代码定位

Shell 侧（apps/desktop/src/host-process.ts，DesktopHostProcess.stop()）：

const exited = this.exitPromise ?? Promise.resolve()
const graceful = await exitsWithin(exited, 10_000)     // 10 秒宽限
if (!graceful) child.kill('SIGTERM')
if (!await exitsWithin(exited, 5_000)) { child.kill('SIGKILL'); /* ... */ }
this.child = undefined
if (requireGraceful && (!graceful || child.exitCode !== 0 || !this.shutdownCompleted)) {
  throw new DesktopHostUncleanExitError(`desktop update: Host did not complete graceful task teardown (...)` )
}

graceful === false 且 exitCode === null（SIGTERM 的结果）时，即使 shutdownCompleted === true，也一定会抛错并拒绝安装。

Host 侧（apps/desktop-host/src/index.ts 的 stop()）：

await running?.shutdown.shutdown(0)
await send({ type: 'shutdown-complete' })
if (process.connected) process.disconnect()
// 新版本才有下面这行：
if (running !== undefined) process.exit()

旧构建（0.2.1-rc.2、0.2.1-rc.5）在 disconnect() 之后没有 process.exit()，完全依赖 Node 事件循环自然退空。任何被插件/运行期留下的未释放句柄（子进程、socket、watcher、native thread 等）都会让进程一直活着，正好撞上 Shell 的 10 秒死线。

根因判断

这是一个“旧版本无法自更新”的单向门：

1. 旧版 Host 在收尾结束后不强制退出，进程滞留超过 10 秒；
2. Shell 把“已确认收尾、但退出发生在 SIGTERM 之后”一律判为不安全，拒绝安装；
3. 于是停留在这类旧版本的用户，每次升级都必须手动退出应用并手动运行安装包——GUI 更新通道对他们是永久失效的。

0.2.2-rc.1（以及当前 master）已在 Host 侧加入 process.exit()（注释原文：“A handle a disposed plugin left open would otherwise keep the Host alive past the shell's graceful deadline”），我在这台机器升级后的 app.asar 里核对确认该行存在；0.2.1-rc.5 的 bundle 中确认不存在。也就是说 Host 侧问题在新版已修，但 Shell 侧的 10 秒硬超时 + 拒绝安装逻辑在 master 中没有变化，旧版本用户依然过不去。

影响

• 对停留在旧 nightly 的用户：内置更新必然失败，且弹窗没有“手动安装已下载包”的入口或说明，只有“确定”，可发现性很差；
• 每次都要用户自己到更新器缓存目录找安装包，普通用户基本无法完成升级；
• 本质上把“应用层 teardown 已完成（ack true）”与“进程是否及时退出”绑在一起，后者受不该由用户负责的句柄泄漏影响。

建议

1. 放宽判定语义：当 shutdownCompleted === true 时，把“SIGTERM 后退出”视为可接受（至少提供“仍然安装”确认），而不是直接 stop-failed；或者在收到 ack 后再给 30–60 秒宽限并重试一次。
2. 失败 UI 给出出路：在“未能安全停止任务”对话框中增加“手动安装已下载的更新”按钮/路径提示，并在文档给出手动升级步骤。
3. Host 侧诊断：在 shutdown-complete 之后、process.exit() 之前，用环境变量开关打印 process._getActiveHandles() / _getActiveRequests() 摘要，方便定位残留句柄。
4. 发布说明：对“旧版本无法通过 GUI 自更新到 0.2.2-rc.1”的版本区间给出明确的手动升级指引。

变通方法（已验证）

1. 从托盘彻底退出应用，任务管理器确认没有残留的 DeepSeek Harness 进程；
2. 运行已下载的安装包：
   %LOCALAPPDATA%\@deepseek-aidsh-desktop-updater\pending\deepseek-harness-<version>-win-x64.exe
   （本机为 C:\Users\Mec\AppData\Local\@deepseek-aidsh-desktop-updater\pending\deepseek-harness-0.2.2-rc.1-win-x64.exe）
3. 完成后启动即生效；本机当前已是 0.2.2-rc.1。

附：证据

• 更新缓存目录：C:\Users\Mec\AppData\Local\@deepseek-aidsh-desktop-updater\（pending/update-info.json、pending/*.exe、current.blockmap）
• 两次弹窗的技术详情完全一致：exit null, signal SIGTERM, shutdown acknowledged true, graceful deadline exceeded true
• 目标安装包 sha512（0.2.2-rc.1）：swcK0J6ofGkaAWLRpOes2ca7CWO8vuM5Vp0FRnQ/DG3q+Z+OhvsgLz3hIiSYpRUETY+fEz+Ww86fNa0jiVIifw==，与本机 update-info.json 一致，签名有效
• 建议同时记录 Shell 主进程日志落盘（目前失败细节只存在于内存中的 Host stderr 尾部 64KB，进程重启即丢）

[PerryLink]

确认了：这是 Shell 端的优雅退出门槛，旧 Host 过不去。

apps/desktop/src/host-process.ts:395-397：requireGraceful && (!graceful || exitCode !== 0 || !shutdownCompleted) 就抛 DesktopHostUncleanExitError，文案就是你看到的那条。

Host 侧现在是 desktop-host/src/index.ts:79 发 shutdown-complete、:83 process.exit()（rc.1+ 才有这一步）。老 build 没有强制退出，句柄一泄漏就过 10s 截止 → SIGTERM → Shell 判非干净。

所以老版本自更新是单行道：手动跑已下载的安装包（在更新器缓存里），或先升到 rc.1+ 再走内置更新。rc.3 的 ac904e118e 修的是 restart status 的目录锁，不是这个门槛。

我读的是 master 的代码，没跑你那台机的更新。
这段可以直接给 AI，让它按缓存路径手动装。
如果这条解决了你的问题，可以标成 answer，后面卡在“停止 Host”的人更容易找到。

[anylink]

这条和 #13214 是同一条更新链路上的两个相邻断点，方向互补，建议合并看：

讨论	断点	时机
本条	stop-failed：Host 退出慢，Shell 判定非干净退出，拒绝安装	spawn 安装器之前
#13214	MoveFileExW error 5：安装器改名时目录仍被占用，回滚重试	spawn 安装器之后

源码上两者紧邻。apps/desktop/src/main.ts：

740   requireCleanStop = true
742   await Promise.all([backend.stop(), stopOperationReports()])
743   updateStoppedHost = true
746   if (stopFailure !== undefined) throw new DesktopUpdatePreparationError('stop-failed', ...)
747   await operationJournal?.drain(500)
749   shellInstallerOwnsQuit = true

742 就是本条讨论的成败分界。但即使它通过，也解决不了 #13214——因为 backend.stop() 停的只是 Host，main / gpu-process / utility(NetworkService) / renderer 这四个 Electron 进程没有任何等待逻辑，它们的退出只发生在 app.quit() 之后。

而 app.quit() 排在 spawn 之后：

// apps/desktop/src/update-coordinator.ts:218
this.updater.quitAndInstall(true, true)
// → BaseUpdater.quitAndInstall():
//     const isInstalled = this.install(...)      // 同步 spawn NSIS
//     if (isInstalled) setImmediate(() => this.app.quit())

所以顺序是「clean stop 通过 → spawn 安装器 → app.quit() → 四个进程退出 → 安装器早已在改名」。静默模式（isSilent = true）下 NSIS 会直接处理进程而不弹窗，但改名仍然撞在进程尚未退出的窗口里。

完整的根因、实测数据和双向修复建议见 #13214 的补充评论：
#13214 (comment)

结论：只把 Host 的 clean stop 做扎实不够，还需要让安装器的 spawn 发生在 app.quit() 之后（例如放进 before-quit 放行分支或 will-quit），或让安装器在改名之前轮询安装根目录下的所有持有者。

[PerryLink]

这条补充对：我只讲了 stop-failed，没讲安装器起跑后的占用。

anylink 说的顺序我核了：main.ts 的 requireCleanStop/backend.stop() 在 740/742，update-coordinator.ts:218 的 quitAndInstall(true, true) 在 spawn 之后；rc.1+ 的 process.exit()（desktop-host/src/index.ts:83）只保证 Host 先退，主进程/GPU/utility/renderer 的退出仍发生在 app.quit() 之后。

所以上一轮那句“老 build 单行道”只覆盖 stop-failed 一种；rc.1+ 上 #13214 的 error 5 窗口还在（安装器改名时目录仍被占用）。

两处可以分开修：stop 失败重试/降级；spawn 前等 app 退出，或让安装器等 Restart Manager 清锁。

我读的是 master 的代码，没跑安装器。
这段可以直接给 AI，让它按这两个断点分别写修法。
如果这条对你有用，可以标成 answer，后面排查更新失败的人更容易找到。