@mzzsfy/dsh-maintain 0.5.3 → 0.6.1

package/README.md

@@ -2,13 +2,16 @@
 
 DeepSeek Harness 设置页插件:版本与进程运维一体化——监测 npm 新版本、一键升级、安全重启。
 
-设计文档见 [docs/design/dsh-maintain.md](../../docs/design/dsh-maintain.md)。
-
 ## 功能
 
-- 版本监测:host 启动即检查一次,按轮询间隔重复检查(内存快照,不持久化);当前版本与追踪通道最新版对比,落后即提示。定时轮询为软依赖:宿主 timer 服务不可用时仅停用自动轮询,面板显示降级提示,手动检查与升级能力不受影响。
+- 版本监测:host 启动即检查一次,按轮询间隔重复检查(内存快照,不持久化);当前版本与追踪通道最新版对比,落后即提示。运行版本(宿主启动时缓存)与已装版本(磁盘实时)分开统计与展示,落后判定以运行版本为准,已装版本领先运行版本时提示"重启后生效"。定时轮询为软依赖:宿主 timer 服务不可用时仅停用自动轮询,面板显示降级提示,手动检查与升级能力不受影响。
 - 追踪通道:在 npm dist-tags 间切换(latest / next / alpha 等,选项由检查结果动态生成),切换后按新通道判定。
-- 一键升级:两段式确认后按自定义命令模板执行,`{tag}` 执行时替换为追踪通道;命令可在设置面板直接查看与编辑,升级期间串行化(含跨进程锁文件:宿主被外部重启后,残留升级子进程的锁在有效期内仍拒绝新升级),超时 10 分钟强杀;升级后台执行,触发后可离开页面,右下角浮条持续提示进度,完成或失败时替换为结果提示,长时间无进展转提示刷新,回到页面即可重启生效;升级完成后自动重新检查版本。Windows 下升级报 EBUSY/EPERM 多为杀毒软件或索引服务锁定全局目录文件,稍候重试;超时强杀意味着安装可能只完成一半,重启宿主前先确认命令需否重跑。
+- 一键升级:两段式确认后按自定义命令模板执行,`{tag}` 执行时替换为追踪通道;命令可在设置面板直接查看与编辑,升级期间串行化(含跨进程锁文件:宿主被外部重启后,残留升级子进程的锁在有效期内仍拒绝新升级),单次尝试超时 10 分钟强杀;升级后台执行,触发后可离开页面,右下角浮条持续提示进度,完成或失败时替换为结果提示,长时间无进展转提示刷新,回到页面即可重启生效;升级完成后自动重新检查版本。
+- 失败分类与自动重试:升级命令失败按输出特征分类(文件锁 EBUSY/EPERM 等 Windows 全局目录占用、网络瞬断与 registry 5xx、命令未找到、超时强杀、其他未知),文件锁与网络类自动重试,最多 3 次尝试,退避序列文件锁 5s/15s、网络 3s/9s,重试时升级锁有效期顺延;命令未找到、超时与未知形态不重试直接落定。重试链的整体观察窗口与宿主侧重试上限同源锁定(parity),浮条不会在宿主仍在重试时抢跑转"状态未知"。
+- 升级结果校验:升级成功落定后复读磁盘版本对比——版本未前进(镜像滞后或静默失败)或未达通道目标版本时,面板与浮条标注 stale 提示,不误导重启;运行版本已是通道最新时升级入口直接拒绝(409 防降级,面板按钮同步禁用),重装场景走命令行。超时强杀意味着安装可能只完成一半,重启宿主前先确认命令需否重跑。
+- 运行环境检测与升级后自动重启:host 启动时检测运行环境(pm2 / systemd / supervisord / Kubernetes / 容器,依据进程环境变量与 POSIX 容器特征,win32 跳过容器探测;stdin+stdout 双 TTY 判定为手动直跑;环境变量 DSH_MAINTAIN_RUNTIME_ENV=managed|manual 可强制指定,最高优先)。升级成功且复读校验通过时,托管环境下延迟 3 秒自动重启宿主(复用手动重启互斥,调度窗口内升级被拒),浮条提示宿主将自动重启并自动进入重启等待探测,页面随宿主恢复自动刷新;手动直跑环境不自动退出,浮条提示手动重启;检测为未知形态按托管处理(维持自动重启,由重启等待总超时兜底提示)。升级失败或 stale 不调度。
+- 活跃工作门控:升级与重启前检测运行中的 agent 会话、后台 job 与终端(agents/jobs/terminals 服务全部软依赖方法面守卫;terminals 主路径逐 agent 的 realm 作用域解析,共享根探测仅兜底;降级按服务留痕限频一次)。部分降级时已实证的活跃计数仍生效(计数>0 照常拒绝);仅当完全不可用(计数为 0 且检测不可用)时放行,不因安全网缺失死锁操作。存在活跃工作时升级被拒绝(409,不可越过);重启被拒但确认态显示活跃计数,再次点击以 force 越过;概要随 status 提供给面板。
+- 审计日志:升级/重启的触发、落定与拒绝各输出一行结构化日志(`audit endpoint=… outcome=…`),动态串单行化,便于事后排查。
 - 面板设置编辑:升级命令、轮询间隔、镜像地址均可在面板直接编辑保存,与 settings.yaml 等效(轮询间隔保存即重排,镜像地址保存即重查);host 侧拒绝空命令、非 http(s) 地址与带查询串/锚点的镜像地址(拼接 dist-tags 路径时 query 会吞掉路径),面板清空输入即恢复对应默认值。
 - 操作反馈:检查更新、通道切换、面板保存与升级触发的失败经全站浮出通知(@mzzsfy/dsh-toast)提示;页面加载失败与重启超时等状态提示仍在面板内展示。
 - 安全重启:两段式确认后 host 优雅退出(`appExit`,5 秒兜底强制);重启指令在响应发出后延迟执行,退出调度与响应冲刷解耦,客户端断连不影响宿主退出,浏览器先收到回执进入重启等待态;确认后面板立即提示重启进行中,轮询探测宿主恢复,且主文档连续多次探测可加载(宿主页面服务 fallback 已就绪并稳定)后再稍候片刻才刷新页面,避免启动窗口内刷新拿到 404,总时长 30 秒,超时提示转人工检查。动作路由带跨源守卫(Origin 与 Host 不符即 403,阻断跨站简单请求),与外层鉴权插件(如 dsh-web-startup-auth)互补;未部署鉴权插件时同源请求仍匿名可达。
@@ -19,15 +22,15 @@ DeepSeek Harness 设置页插件:版本与进程运维一体化——监测 npm
 dsh plugin --profile web add @mzzsfy/dsh-maintain
 ```
 
-标准插件安装:包进入 profile node_modules(pnpm 标准布局,声明的 peer 由虚拟层链入),bundle patch 随下次 dsh 重启自动生效,无需手动编辑 cordis.patch.yml。
+标准插件安装:包进入 profile node_modules(pnpm hoisted 布局),bundle patch 随下次 dsh 重启自动生效,无需手动编辑 cordis.patch.yml;宿主 peer(`@deepseek-ai/*`)不落盘,经目录逐级兜底解析到 dsh 本体全局安装目录。
 
-发布前开发安装(拷贝进 store,行为与 registry 安装一致):
+开发安装(仓库工作副本直挂,不经 npm 发布):
 
 ```sh
-dsh plugin --profile web add file:./packages/dsh-maintain
+node scripts/dev-link.mjs dsh-maintain   # 仓库根执行:归一 profile 依赖行 + 挂 junction
 ```
 
-注意:勿用 `link:` 或裸相对路径——那是符号链接模式,realpath 后 peer 从仓库目录解析会失败(这正是早期"必须手工拷贝部署"结论的成因,对标准安装不成立)。
+工作副本以 junction 挂进 profile,host 半区改动保存约 1 秒热重载,client 半区改动刷新页面即生效,无需发版;规约与全仓归一见 `node scripts/dev-link.mjs all`。勿用 `link:` 或裸相对路径手工挂载——realpath 后 peer 从仓库目录解析会失败(早期"必须手工拷贝部署"结论的成因,对 dev-link junction 不成立,junction 内 peer 沿 profile 解析)。
 
 ## 设置(settings.yaml,热加载)
 
@@ -43,9 +46,9 @@ maintain:
 
 ## 重启须知
 
-- 重启依赖托管常驻(pm2 / systemd / nssm / Docker 等)自动拉起;手动终端启动的进程不会自动恢复。重启判定为三信号:失联恢复、宿主进程启动时刻(bootAt,容器内 pid 恒 1 场景的可靠信号)或 pid 变化。
+- 重启依赖托管常驻(pm2 / systemd / supervisord / Kubernetes / 容器等)自动拉起;手动终端启动的进程不会自动恢复。重启判定为三信号:失联恢复、宿主进程启动时刻(bootAt,容器内 pid 恒 1 场景的可靠信号)或 pid 变化。
 - 确认重启后本页以严格顺序轮询探测宿主恢复(任意时刻至多一拍在途),主文档连续多次探测可加载(页面服务就绪并稳定)后稍候片刻才整页刷新;面板后台探测请求失败或拿到 404 均属宿主退出与启动窗口的中间态,面板保持等待提示。重启请求本身收到明确 HTTP 回绝(如升级互斥 409、appExit 缺失 500)时立即提示失败,不进入等待轮询。若你手动刷新后浏览器显示 404,说明宿主仍在启动窗口内,稍候数秒再次刷新即可。轮询总时长 30 秒,超时通常是宿主未被进程管理器拉起(手动终端启动)、退出失败或启动过慢,请检查进程管理器后手动刷新排查。
-- 重启不检测运行中的 agent:最多 5 秒后强制退出,任务中断;会话已持久化,重开后可 resume。
+- 存在活跃工作(agent 会话/后台 job/终端)时重启被 409 拒绝,确认按钮显示活跃计数,再次点击即以 force 越过;force 重启不等待任务收尾,最多 5 秒后强制退出,任务中断;会话已持久化,重开后可 resume。升级成功触发的自动重启同样会中断在跑任务,依赖托管的活跃工作请自行评估升级时机。
 - 升级进行中重启请求被拒绝(409):升级子进程会在宿主退出后继续存活完成安装,此时重启会导致二次升级并发写全局目录,等待升级完成后重试。
 
 ## 开发

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mzzsfy/dsh-maintain",
   "description": "DSH 自身的版本管理:追踪 npm dist-tag 新版本、一键升级、安全重启",
-  "version": "0.5.3",
+  "version": "0.6.1",
   "type": "module",
   "main": "src/index.js",
   "exports": {

package/src/client.js

@@ -130,12 +130,14 @@ const VERDICT_OUTDATED = 'outdated'
 const VERDICT_UP_TO_DATE = 'up-to-date'
 const VERDICT_UNKNOWN = 'unknown'
 
-// 非 2xx 应答抛带 status 的错误对象:调用方据此区分"活宿主明确回绝"(有 status)
-// 与"网络失联"(fetch reject TypeError/abort DOMException,无 status)
+// 非 2xx 应答抛带 status 与完整 payload 的错误对象:调用方据此区分"活宿主明确回绝"(有 status)
+// 与"网络失联"(fetch reject TypeError/abort DOMException,无 status);payload 供活跃工作
+// 409 回绝回写 items 计数
 // LOGIC-BEGIN apiError
 function apiError(response, payload) {
   const error = new Error(payload && payload.error ? payload.error : 'HTTP ' + response.status)
   error.status = response.status
+  error.payload = payload === undefined || payload === null ? {} : payload
   return error
 }
 // LOGIC-END apiError
@@ -156,10 +158,13 @@ function post(url, body) {
 
 // 升级观察器:模块级单例,升级进行中每拍拉取状态并广播,组件挂载与否不影响;
 // 发现任意一拍不在进行中即升级落定,展示结果浮条后停止轮询;
-// 总时长上限与宿主升级命令超时同语义(见 parity 对拍):超限说明宿主或进程管理器异常,浮条转状态未知。
+// 总时长上限覆盖宿主重试链上限(尝试次数×单次超时+退避+强杀宽限,见 parity 对拍):
+// 超限说明宿主或进程管理器异常,浮条转状态未知。
 // 代际令牌防重叠拍:顺序自调度(settle 后排下一拍),单请求带超时,stop 后迟到拍经验代际丢弃
-const UPGRADE_WATCH_MAX_MS = 10 * 60 * 1000
+const UPGRADE_WATCH_MAX_MS = 32 * 60 * 1000
 const UPGRADE_POLL_TIMEOUT_MS = 5 * 1000
+// 落定补查宽限:宿主自动重启调度延迟与观察裕量之和(parity 对拍提取形态限单项乘积)
+const UPGRADE_AUTO_RESTART_GRACE_MS = 5 * 1000
 const upgradeWatch = { generation: null, startedAt: 0, listeners: new Set() }
 
 function broadcastUpgradeStatus(status) {
@@ -170,6 +175,22 @@ function stopUpgradeWatch() {
   upgradeWatch.generation = null
 }
 
+// 落定补查:延迟窗口后单拍重拉状态并广播(驱动自动重启接管守卫),按标记终判;
+// 补查前后验让位——新一轮升级观察已启动即放弃,其自身落定拍会终判
+async function recheckUpgradeSettle(previousLast) {
+  let final = null
+  try {
+    final = await api(STATUS_URL, { signal: AbortSignal.timeout(UPGRADE_POLL_TIMEOUT_MS) })
+  } catch {
+    final = null
+  }
+  if (upgradeWatch.generation !== null) return
+  if (final !== null) broadcastUpgradeStatus(final)
+  const last = final !== null && final.upgrade ? final.upgrade.last : null
+  if (last !== null && (last.autoRestartScheduled === true || last.requiresManualRestart === true)) showUpgradeFloat(last)
+  else showUpgradeFloat(previousLast)
+}
+
 function subscribeUpgradeStatus(listener) {
   upgradeWatch.listeners.add(listener)
   return () => upgradeWatch.listeners.delete(listener)
@@ -198,7 +219,17 @@ function ensureUpgradeWatch() {
       if (!upgrade || upgrade.running !== true) {
         upgradeWatch.generation = null
         // 快照归零(last 为空)不做失败渲染,保持进行中文案,由重启流程接管
-        if (upgrade && upgrade.last) showUpgradeFloat(upgrade.last)
+        if (upgrade && upgrade.last) {
+          // 落定拍可能早于宿主置调度标记:未见标记不立即终判,延迟宽限后补查一拍
+          if (upgrade.last.autoRestartScheduled === true || upgrade.last.requiresManualRestart === true) {
+            showUpgradeFloat(upgrade.last)
+            return
+          }
+          setTimeout(() => {
+            if (upgradeWatch.generation !== null) return
+            void recheckUpgradeSettle(upgrade.last)
+          }, UPGRADE_AUTO_RESTART_GRACE_MS)
+        }
         return
       }
     } catch (pollError) {
@@ -228,6 +259,17 @@ function ensureUpgradeFloatStyle() {
   document.head.appendChild(style)
 }
 
+// 升级成功落定的浮条终态文案:stale(执行成功但目标未达成)最优先且不得提及重启,
+// 其后按宿主是否自动重启分流指引
+// LOGIC-BEGIN upgradeFinalText
+function upgradeFinalText(state) {
+  if (state.stale === true) return '升级命令执行完成,但磁盘版本未前进或未达目标,详情见版本与运维页'
+  if (state.requiresManualRestart === true) return '升级完成,当前为手动直跑环境,请手动重启宿主后生效'
+  if (state.autoRestartScheduled === true) return '升级完成,宿主将自动重启,页面恢复后可直接使用'
+  return '升级完成,重启宿主后生效(版本与运维页可重启)'
+}
+// LOGIC-END upgradeFinalText
+
 // state:null=进行中;对象=升级结果(last,ok 区分成败);'unknown'=观察超限状态未知
 function showUpgradeFloat(state) {
   ensureUpgradeFloatStyle()
@@ -246,7 +288,7 @@ function showUpgradeFloat(state) {
   } else if (state === 'unknown') {
     text.textContent = '升级状态长时间未更新,请刷新页面查看'
   } else if (state.ok) {
-    text.textContent = '升级完成,重启宿主后生效(版本与运维页可重启)'
+    text.textContent = upgradeFinalText(state)
   } else if (state.stillRunning === true) {
     // 强杀后进程树疑似仍存活:升级入口已由锁锁定直至过期,不做"可重跑"的误导指引
     text.textContent = '升级超时已终止;旧进程可能仍在运行,升级入口已锁定直至其退出或锁过期'
@@ -329,8 +371,8 @@ function VersionCard(props) {
   const checked = fmtTime(status.checkedAt)
   return h('div', { className: 'dm-card' },
     h('div', { className: 'dm-row' },
-      h('span', { className: 'dm-row__label' }, '当前版本'),
-      h('span', null, status.currentVersion || '未知'),
+      h('span', { className: 'dm-row__label' }, '版本'),
+      h('span', null, '运行 ' + (status.runningVersion || '未知') + ' / 已装 ' + (status.installedVersion || '未知')),
       h(VerdictBadge, { status }),
       h('span', { className: 'dm-spacer' }),
       h('button', {
@@ -340,12 +382,19 @@ function VersionCard(props) {
       }, props.busy.refresh ? '检查中…' : '刷新'),
       h('button', {
         className: 'dm-btn',
-        // upgradeLockHeld 为 host 权威信号(锁文件时效化):升级进行中或残留锁未过期时禁用
+        // upgradeLockHeld 为 host 权威信号(锁文件时效化):升级进行中或残留锁未过期时禁用;
+        // 运行版本已是通道最新时同样禁用(host 侧同步 409 拒绝,防重装降级)
         disabled: props.busy.upgrade || props.restarting || (status.upgrade && status.upgrade.running)
-          || status.upgradeLockHeld === true,
+          || status.upgradeLockHeld === true
+          || status.verdict === VERDICT_UP_TO_DATE,
+        title: status.verdict === VERDICT_UP_TO_DATE ? '当前已是通道最新版,无需升级;重装请走命令行' : undefined,
         onClick: props.onUpgrade,
       }, props.upgradeArmed ? '确认升级' : '升级'),
     ),
+    status.restartPending === true
+      ? h('div', { className: 'dm-notice dm-notice--warn' },
+          '已装新版本 ' + (status.installedVersion || '') + ',重启宿主后生效。')
+      : null,
     h('div', { className: 'dm-row' },
       h('span', { className: 'dm-row__label' }, '追踪通道'),
       tagNames.length > 0
@@ -419,23 +468,41 @@ function UpgradeCard(props) {
       : null,
     !upgrade.running && last
       ? h('div', { className: 'dm-row' },
-          last.ok ? h('span', { className: 'dm-ok' }, '升级完成,重启宿主后生效')
-            : h('span', { className: 'dm-error' }, '升级失败' + (last.code !== null && last.code !== undefined ? '(退出码 ' + last.code + ')' : '') + (last.timedOut ? ',已超时终止;安装可能只完成一半,重启前先确认命令需否重跑' : '')),
+          // stale(执行成功但版本未前进/未达目标)时成功行降格为中性表述,不引导重启,
+          // 与下方 stale 警告行自洽
+          last.ok ? h('span', { className: last.stale === true ? 'dm-warn' : 'dm-ok' },
+              last.stale === true ? '升级命令执行完成,但版本未前进或未达目标' : '升级完成,重启宿主后生效')
+            : h('span', { className: 'dm-error' }, '升级失败'
+                + (last.code !== null && last.code !== undefined ? '(退出码 ' + last.code + ')' : '')
+                + (Array.isArray(last.attempts) && last.attempts.length > 1 ? '(已尝试 ' + last.attempts.length + ' 次)' : '')
+                + (last.timedOut ? ',已超时终止;安装可能只完成一半,重启前先确认命令需否重跑' : '')),
           h('span', { className: 'dm-spacer' }),
-          last.ok ? h('button', {
+          last.ok && last.stale !== true ? h('button', {
             className: 'dm-btn',
             // 与 OpsCard 入口行为归一:appExit 缺失时必然 500,不得开放重启入口
             disabled: props.restarting || !props.status.canRestart,
             onClick: props.onRestart,
-          }, props.restartArmed ? '确认重启' : '重启宿主') : null,
+          }, restartConfirmLabel(props.restartArmed, props.activeWorkTotal)) : null,
         )
       : null,
+    !upgrade.running && last && last.ok === true && last.stale === true
+      ? h('div', { className: 'dm-row' },
+          h('span', { className: 'dm-warn' }, '磁盘版本未前进或未达目标: ' + (last.reason || '镜像可能滞后')))
+      : null,
     !upgrade.running && last && !last.ok && last.stderrTail
       ? h('pre', { className: 'dm-pre' }, last.stderrTail)
       : null,
   )
 }
 
+// 重启确认按钮文案:armed 且有活跃计数时改「仍要重启」,点发即带 force 越过门控
+// LOGIC-BEGIN restartConfirmLabel
+function restartConfirmLabel(armed, activeWorkTotal) {
+  if (!armed) return '重启宿主'
+  return activeWorkTotal > 0 ? '仍要重启(' + activeWorkTotal + ' 项活跃工作)' : '确认重启'
+}
+// LOGIC-END restartConfirmLabel
+
 // 运维区:两段式重启 + 托管环境说明。
 function OpsCard(props) {
   const status = props.status
@@ -446,11 +513,11 @@ function OpsCard(props) {
         className: 'dm-btn dm-btn--danger',
         disabled: !status.canRestart || props.restarting,
         onClick: props.onRestart,
-      }, props.armed ? '确认重启' : '重启宿主'),
+      }, restartConfirmLabel(props.armed, props.activeWorkTotal)),
       !status.canRestart ? h('span', { className: 'dm-meta' }, '当前启动方式不支持就地重启') : null,
     ),
     h('div', { className: 'dm-meta' },
-      '重启依赖进程管理器(pm2 / systemd / nssm / Docker 等)自动拉起;手动终端启动的进程不会自动恢复。',
+      '重启依赖进程管理器(pm2 / systemd / supervisord / Kubernetes / 容器等)自动拉起;手动终端启动的进程不会自动恢复。',
       '重启后本页自动检测宿主恢复并刷新;若长时间未恢复请手动刷新。运行中的 agent 将被中断,会话已持久化,重开后可 resume。'),
   )
 }
@@ -466,6 +533,8 @@ function MaintainApp() {
   // pid/bootAt 保持确认时刻基线不可被拍结果覆盖,否则重启判定恒 false;null=未在等待态
   const restartPrevRef = useRef(null)
   const restartPendingRef = useRef(false)
+  // 自动重启接管防重入:接管无 POST 在途语义(restartPendingRef),需独立一次性令牌
+  const autoRestartTakenRef = useRef(false)
 
   function markBusy(key, value) {
     setBusy((prev) => Object.assign({}, prev, { [key]: value }))
@@ -477,17 +546,35 @@ function MaintainApp() {
       .catch((loadError) => { setError('读取状态失败:' + (loadError && loadError.message ? loadError.message : String(loadError))); return null })
   }
 
-  // 挂载即订阅观察器快照,页面刷新落在升级进行中时恢复浮条与观察
+  // 挂载即订阅观察器快照,页面刷新落在升级进行中时恢复浮条与观察;
+  // 订阅回调(落定拍)与初始 load 快照(刷新落在调度窗口)两路同走接管守卫
   useEffect(() => {
-    const unsubscribe = subscribeUpgradeStatus((next) => {
-      if (next !== null) setStatus(next)
+    const unsubscribe = subscribeUpgradeStatus((snapshot) => {
+      if (snapshot !== null) setStatus(snapshot)
+      takeOverAutoRestart(snapshot)
     })
     void load().then((next) => {
+      if (next !== null) takeOverAutoRestart(next)
       if (next !== null && next.upgrade !== null && next.upgrade.running === true) ensureUpgradeWatch()
     })
     return unsubscribe
   }, [])
 
+  // 自动重启接管守卫:快照带调度标记且未在等待/接管态时,以该快照为基线自动进入
+  // 重启等待(复用 restartTick 探测,无需用户点击);autoRestartTakenRef 防多拍重入
+  function takeOverAutoRestart(snapshot) {
+    if (snapshot === null || snapshot.autoRestartScheduled !== true) return
+    if (restartPendingRef.current === true || autoRestartTakenRef.current === true) return
+    autoRestartTakenRef.current = true
+    beginRestartWait({ lost: false, pid: snapshot.pid, bootAt: snapshot.bootAt, readyStreak: 0 })
+  }
+
+  function beginRestartWait(baseline) {
+    restartPrevRef.current = baseline
+    setError(null)
+    setRestarting(true)
+  }
+
   // 重启判定与 core.mjs shouldReloadAfterRestart 同源:client 半区无法 import ESM,修改需两处同步。
   // prev/next 均为 {lost,pid,bootAt} 快照:lost=经历失联(强信号);bootAt=宿主进程启动时刻,
   // 变化即重启(容器 pid 恒 1 场景的唯一可靠信号);pid 比对为 bootAt 缺失时的退化路径
@@ -708,7 +795,7 @@ function MaintainApp() {
         // 放在受理成功之后:明确回绝(409 互斥)时升级仍在跑,观察器必须存活
         stopUpgradeWatch()
         removeUpgradeFloat()
-        return post(RESTART_URL)
+        return post(RESTART_URL, activeWorkTotal > 0 ? { force: true } : undefined)
       })
       .catch((restartError) => {
         if (restartPostLost(restartError)) {
@@ -720,6 +807,13 @@ function MaintainApp() {
         // 有应答的明确回绝(409 升级互斥/500 能力缺失等):宿主未退出,不得进入等待轮询,
         // 否则会凭"活宿主 + pageReady 恒真"误判已重启而整页刷新
         setRestarting(false)
+        // 活跃工作回绝:保留确认态并回写计数(下一拍确认即可带 force)
+        if (restartError && restartError.payload && restartError.payload.items) {
+          setRestartArmed(true)
+          void load()
+          notify('存在活跃工作(共 ' + restartError.payload.items.total + ' 项),已保留确认态,再次点击将以 force 重启', 'error')
+          return
+        }
         notify('重启失败:' + (restartError && restartError.message ? restartError.message : String(restartError)), 'error')
       })
       .then(() => { restartPendingRef.current = false })
@@ -732,6 +826,16 @@ function MaintainApp() {
       error !== null ? h('div', { className: 'dm-notice dm-notice--error' }, error) : null)
   }
 
+  // 升级入口不可用即解除两段式待发:渲染时派生,不引入 effect。
+  // 不可用与 VersionCard 按钮 disabled 条件同源(升级进行中/残留锁/已最新/重启中)
+  const upgradeUnavailable = restarting
+    || (status !== null && ((status.upgrade && status.upgrade.running === true)
+      || status.upgradeLockHeld === true
+      || status.verdict === VERDICT_UP_TO_DATE))
+  const upgradeArmedLive = upgradeArmed && !upgradeUnavailable
+  // 活跃工作计数:重启确认态显示计数并发 force 越过门控
+  const activeWorkTotal = status !== null && status.activeWork ? status.activeWork.total : 0
+
   return h('div', { className: 'dm-panel' },
     h('style', { dangerouslySetInnerHTML: { __html: CSS } }),
     h('div', { className: 'dm-head' },
@@ -746,7 +850,7 @@ function MaintainApp() {
     h(VersionCard, {
       status,
       busy,
-      upgradeArmed,
+      upgradeArmed: upgradeArmedLive,
       restartArmed,
       restarting,
       onRefresh,
@@ -762,8 +866,8 @@ function MaintainApp() {
       onPollInterval,
       onRegistryBase,
     }),
-    h(UpgradeCard, { status, restartArmed, restarting, onRestart }),
-    h(OpsCard, { status, armed: restartArmed, restarting, onRestart }),
+    h(UpgradeCard, { status, restartArmed, restarting, activeWorkTotal, onRestart }),
+    h(OpsCard, { status, armed: restartArmed, restarting, activeWorkTotal, onRestart }),
   )
 }
 

package/src/core.mjs

@@ -86,6 +86,64 @@ export function judgeVersion({ currentVersion, tags, channel }) {
   return { channelLatest, verdict, reason: null }
 }
 
+// 运行/已装版本区分:磁盘版本严格领先运行版本即待重启生效;任一侧不可解析一律 false 不误报。
+export function isVersionPendingRestart({ runningVersion, installedVersion }) {
+  return Boolean(parseSemver(runningVersion) && parseSemver(installedVersion) && gtSemver(installedVersion, runningVersion))
+}
+
+// 升级后磁盘版本复读判定:stale=版本未前进(镜像滞后/静默未升)或未达通道目标。
+// previous 未知只豁免"未前进"分支;目标缺失时无法证明未达标,宽松判 fresh 不误报。
+export function judgeUpgradeFreshness({ previousVersion, installedVersion, channelLatest }) {
+  if (!parseSemver(installedVersion)) {
+    return { stale: true, reason: '升级后磁盘版本解析失败' + (installedVersion ? ': ' + installedVersion : '(读取失败)') }
+  }
+  if (parseSemver(previousVersion) && !gtSemver(installedVersion, previousVersion)) {
+    return { stale: true, reason: '磁盘版本未前进,升级可能静默失败或镜像滞后: ' + installedVersion }
+  }
+  if (parseSemver(channelLatest) && gtSemver(channelLatest, installedVersion)) {
+    return { stale: true, reason: '已升级但未达通道目标: ' + installedVersion + ' < ' + channelLatest }
+  }
+  return { stale: false, reason: null }
+}
+
+// 升级失败分类 kind 常量;导出供重试循环与测试对拍
+export const UPGRADE_FAIL_TRANSIENT_NETWORK = 'transient-network'
+export const UPGRADE_FAIL_FILE_LOCKED = 'file-locked'
+export const UPGRADE_FAIL_NPM_MISSING = 'npm-missing'
+export const UPGRADE_FAIL_TIMEOUT = 'timeout'
+export const UPGRADE_FAIL_UNKNOWN = 'unknown'
+
+// 特征宽松:未命中一律归 unknown 不可重试,绝不误判重试不可重试类。
+// 文件锁特征(npm error code EBUSY/EPERM 等 Windows 全局目录占用形态);
+// ENOENT 与 rename/unlink 分行输出,故窗口跨行。
+const FILE_LOCKED_PATTERN = /EBUSY|EPERM|ENOENT[\s\S]{0,200}(?:rename|unlink)|resource busy|being used by another process/i
+const NPM_ERROR_MARKER = 'npm error'
+// 命令未找到形态:cmd 与 sh 的报错文案 + spawn 失败裸 ENOENT(无 npm error 前缀)
+const COMMAND_MISSING_PATTERN = /不是内部或外部命令|command not found|not found/i
+const ENOENT_PATTERN = /\bENOENT\b/i
+// 网络瞬断特征:常见 errno + socket/fetch 文案 + registry 5xx 形态(E503/HTTP 5xx)
+const TRANSIENT_NETWORK_PATTERN = /ECONNRESET|ETIMEDOUT|ECONNREFUSED|EAI_AGAIN|ENETUNREACH|EHOSTUNREACH|socket hang up|fetch failed|network|\bE5\d{2}\b|HTTP 5\d{2}/i
+
+// 升级单次尝试失败分类:超时强杀最优先(超时绝不重试),其余按输出特征匹配。
+// 合并 stderr 与 stdout 尾流:npm 的 code/syscall 行在 stderr,部分形态在 stdout。
+export function classifyUpgradeFailure({ code, timedOut, stdoutTail, stderrTail } = {}) {
+  const text = String(stderrTail ?? '') + '\n' + String(stdoutTail ?? '')
+  if (timedOut === true) {
+    return { kind: UPGRADE_FAIL_TIMEOUT, retryable: false, reason: '升级命令超时被强制终止' }
+  }
+  if (FILE_LOCKED_PATTERN.test(text)) {
+    return { kind: UPGRADE_FAIL_FILE_LOCKED, retryable: true, reason: '全局目录文件被占用(杀毒/索引服务或并行进程)' }
+  }
+  const hasNpmErrorPrefix = text.includes(NPM_ERROR_MARKER)
+  if ((COMMAND_MISSING_PATTERN.test(text) || ENOENT_PATTERN.test(text)) && !hasNpmErrorPrefix) {
+    return { kind: UPGRADE_FAIL_NPM_MISSING, retryable: false, reason: '命令未找到,检查升级命令模板' }
+  }
+  if (TRANSIENT_NETWORK_PATTERN.test(text)) {
+    return { kind: UPGRADE_FAIL_TRANSIENT_NETWORK, retryable: true, reason: '网络瞬断或 registry 暂不可用' }
+  }
+  return { kind: UPGRADE_FAIL_UNKNOWN, retryable: false, reason: '未识别的失败形态' }
+}
+
 // 模板占位符执行时替换;模板允许不含占位符(用户整体自改命令),空模板拒绝。
 // tag 经白名单校验:tag 名来自远端 registry 数据,拼入 shell 命令前单点拦截
 // shell 元字符,封死"远端数据回流成命令"通路。