@mzzsfy/dsh-maintain 0.6.1 → 0.7.0

package/README.md

@@ -6,10 +6,10 @@ DeepSeek Harness 设置页插件:版本与进程运维一体化——监测 npm
 
 - 版本监测:host 启动即检查一次,按轮询间隔重复检查(内存快照,不持久化);当前版本与追踪通道最新版对比,落后即提示。运行版本(宿主启动时缓存)与已装版本(磁盘实时)分开统计与展示,落后判定以运行版本为准,已装版本领先运行版本时提示"重启后生效"。定时轮询为软依赖:宿主 timer 服务不可用时仅停用自动轮询,面板显示降级提示,手动检查与升级能力不受影响。
 - 追踪通道:在 npm dist-tags 间切换(latest / next / alpha 等,选项由检查结果动态生成),切换后按新通道判定。
-- 一键升级:两段式确认后按自定义命令模板执行,`{tag}` 执行时替换为追踪通道;命令可在设置面板直接查看与编辑,升级期间串行化(含跨进程锁文件:宿主被外部重启后,残留升级子进程的锁在有效期内仍拒绝新升级),单次尝试超时 10 分钟强杀;升级后台执行,触发后可离开页面,右下角浮条持续提示进度,完成或失败时替换为结果提示,长时间无进展转提示刷新,回到页面即可重启生效;升级完成后自动重新检查版本。
+- 一键升级:点击升级弹出确认窗,窗内展示将执行的实际命令(`{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 不调度。
+- 升级结果校验:升级命令成功且宿主继续运行(手动直跑或本次未勾选自动重启)时复读磁盘版本对比——版本未前进(镜像滞后或静默失败)或未达通道目标版本时,面板与浮条标注 stale 提示;自动重启路径不做复读与 stale 判定(升级落定钩子禁止网络请求与磁盘读取),版本是否前进由重启后的启动检查呈现。运行版本已是通道最新时升级入口直接拒绝(409 防降级,面板按钮同步禁用),重装场景走命令行。超时强杀意味着安装可能只完成一半,重启宿主前先确认命令需否重跑。
+- 运行环境检测与升级后自动重启:host 启动时检测运行环境(pm2 / systemd / supervisord / Kubernetes / 容器,依据进程环境变量与 POSIX 容器特征,win32 跳过容器探测;stdin+stdout 双 TTY 判定为手动直跑;环境变量 DSH_MAINTAIN_RUNTIME_ENV=managed|manual 可强制指定,最高优先)。升级确认弹窗勾选自动重启且命令成功(退出码 0)时,托管环境下延迟 3 秒自动重启宿主——与面板"确认重启"共用同一退出调度入口(同一互斥、同一审计、同一延迟退出,仅审计行不同),落定钩子零网络请求零磁盘读取(npm 刚替换过宿主文件,避免半写状态故障);浮条提示宿主将自动重启并自动进入重启等待探测,页面随宿主恢复自动刷新;手动直跑环境不自动退出,浮条提示手动重启(弹窗内同步提示该环境约束);检测为未知形态按托管处理(维持自动重启,由重启等待总超时兜底提示)。升级失败或未勾选自动重启时不调度,后者升级完成仅提示,需在面板手动重启。
 - 活跃工作门控:升级与重启前检测运行中的 agent 会话、后台 job 与终端(agents/jobs/terminals 服务全部软依赖方法面守卫;terminals 主路径逐 agent 的 realm 作用域解析,共享根探测仅兜底;降级按服务留痕限频一次)。部分降级时已实证的活跃计数仍生效(计数>0 照常拒绝);仅当完全不可用(计数为 0 且检测不可用)时放行,不因安全网缺失死锁操作。存在活跃工作时升级被拒绝(409,不可越过);重启被拒但确认态显示活跃计数,再次点击以 force 越过;概要随 status 提供给面板。
 - 审计日志:升级/重启的触发、落定与拒绝各输出一行结构化日志(`audit endpoint=… outcome=…`),动态串单行化,便于事后排查。
 - 面板设置编辑:升级命令、轮询间隔、镜像地址均可在面板直接编辑保存,与 settings.yaml 等效(轮询间隔保存即重排,镜像地址保存即重查);host 侧拒绝空命令、非 http(s) 地址与带查询串/锚点的镜像地址(拼接 dist-tags 路径时 query 会吞掉路径),面板清空输入即恢复对应默认值。
@@ -42,7 +42,7 @@ maintain:
   registryBase: https://registry.npmjs.org       # 官方源不可达时可改为镜像地址
 ```
 
-升级命令、轮询间隔、镜像地址三项亦可在设置面板"版本与运维"页直接编辑保存(等效 settings.yaml,热生效)。
+升级命令、轮询间隔、镜像地址三项亦可在设置面板"版本与运维"页直接编辑保存(等效 settings.yaml,热生效);升级后自动重启不在设置中,由升级确认弹窗内的勾选项逐次决定。
 
 ## 重启须知
 

package/package.json

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

package/src/client.js

@@ -67,6 +67,29 @@ const CSS = [
   '.dm-notice--ok { color:var(--dsw-alias-state-success-primary, #1a9e55); }',
   '.dm-pre { margin:0; font-family:ui-monospace, Consolas, monospace; font-size:11px; line-height:1.6; white-space:pre-wrap;',
   '  word-break:break-all; color:var(--dsw-alias-label-secondary); max-height:120px; overflow:auto; }',
+  // ---- 布尔开关:规约形态(track 胶囊 + thumb 圆点,状态锚定 input) ----
+  '.dm-switch { display:inline-flex; align-items:center; gap:8px; cursor:pointer; position:relative; }',
+  '.dm-switch input[type="checkbox"] { position:absolute; opacity:0; width:0; height:0; }',
+  '.dm-switch__track { width:30px; height:16px; border-radius:999px; flex:none; position:relative;',
+  '  background:var(--dsw-alias-separator-primary, rgba(128,128,128,0.35)); transition:background 0.15s ease; }',
+  '.dm-switch__thumb { position:absolute; top:2px; left:2px; width:12px; height:12px; border-radius:50%;',
+  '  background:#fff; transition:left 0.15s ease; }',
+  '.dm-switch input[type="checkbox"]:checked + .dm-switch__track { background:var(--dsw-alias-state-success-primary, #1a9e55); }',
+  '.dm-switch input[type="checkbox"]:checked + .dm-switch__track .dm-switch__thumb { left:16px; }',
+  '.dm-switch input[type="checkbox"]:focus-visible + .dm-switch__track { outline:2px solid var(--dsw-alias-brand-primary, #4d6bfe); outline-offset:2px; }',
+  '.dm-switch input[type="checkbox"]:disabled + .dm-switch__track { opacity:0.45; cursor:default; }',
+  '.dm-switch:hover { opacity:0.85; }',
+  // 文字标签在 DOM 中排 track 之后(保 input+track 紧邻兄弟,状态选择器才生效),视觉以 order 提前
+  '.dm-switch .dm-row__label { order:-1; }',
+  // ---- 升级确认弹窗:遮罩 + 居中窗体 ----
+  '.dm-dialog__mask { position:fixed; inset:0; background:rgba(0,0,0,0.45); z-index:9999;',
+  '  display:flex; align-items:center; justify-content:center; padding:16px; }',
+  '.dm-dialog { background:var(--dsw-alias-bg-layer-1, #fff); color:inherit; border-radius:12px; padding:16px;',
+  '  width:480px; max-width:100%; max-height:80vh; overflow:auto; display:flex; flex-direction:column; gap:10px;',
+  '  box-shadow:0 8px 32px rgba(0,0,0,0.25); }',
+  '.dm-dialog__hint { color:var(--dsw-alias-label-secondary); font-size:12px; }',
+  '.dm-dialog__section { display:flex; flex-direction:column; gap:6px; padding:8px 0; border-top:1px solid var(--dsw-alias-separator-primary, rgba(128,128,128,0.35)); }',
+  '.dm-dialog__outcome { color:var(--dsw-alias-label-secondary); font-size:12px; line-height:1.6; }',
 ].join('\n')
 
 const STATUS_URL = '/api/maintain/status'
@@ -128,6 +151,10 @@ function restartPostLost(error) {
 // test/parity.test.mjs 按 const 名正则提取对拍,修改任一侧必须同步。
 const VERDICT_OUTDATED = 'outdated'
 const VERDICT_UP_TO_DATE = 'up-to-date'
+// 与 host runtime.mjs RUNTIME_KINDS.MANUAL_START 镜像(parity 对拍,单侧改名即测试失败)
+const RUNTIME_KIND_MANUAL = 'manual-start-likely'
+// 与 host AUTO_RESTART_DELAY_MS 镜像(parity 对拍):弹窗文案引用,勿手抄数字
+const AUTO_RESTART_DELAY_SEC = 3
 const VERDICT_UNKNOWN = 'unknown'
 
 // 非 2xx 应答抛带 status 与完整 payload 的错误对象:调用方据此区分"活宿主明确回绝"(有 status)
@@ -363,6 +390,21 @@ function EditRow(props) {
   )
 }
 
+// 布尔开关:原生 checkbox 保可访问性,视觉为 track 胶囊 + thumb 圆点(规约形态);
+// input 与 track 必须保持紧邻兄弟(状态选择器为紧邻组合器),文字标签排最后,视觉经 order 提前
+function Switch(props) {
+  return h('label', { className: 'dm-switch', title: props.title },
+    h('input', {
+      type: 'checkbox',
+      checked: props.checked === true,
+      disabled: props.disabled === true,
+      onChange: (e) => props.onChange(e.target.checked),
+    }),
+    h('span', { className: 'dm-switch__track' }, h('span', { className: 'dm-switch__thumb' })),
+    props.label ? h('span', { className: 'dm-row__label' }, props.label) : null,
+  )
+}
+
 // 版本区:当前版本、通道切换、通道最新版、结论、检查时间与错误、刷新与升级、升级命令编辑。
 function VersionCard(props) {
   const status = props.status
@@ -389,7 +431,7 @@ function VersionCard(props) {
           || 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' },
@@ -522,11 +564,51 @@ function OpsCard(props) {
   )
 }
 
+// 升级确认弹窗:展示将执行的命令({tag} 已替换为追踪通道)与自动重启勾选,确认才触发。
+// 自动重启是会话级选择(不持久化),勾/不勾的后果在窗内明示:
+// 勾选=命令成功后宿主延迟 3 秒退出,由进程管理器拉起新版本,页面随宿主恢复自动刷新;
+// 不勾选=宿主继续运行旧版本,面板提示"重启宿主后生效",需手动点重启按钮
+function UpgradeDialog(props) {
+  // 每次打开都重新挂载(MaintainApp 条件渲染),默认勾选随挂载重置
+  const [autoRestart, setAutoRestart] = useState(true)
+  const status = props.status
+  const template = typeof status.upgradeTemplate === 'string' && status.upgradeTemplate.length > 0
+    ? status.upgradeTemplate
+    : DEFAULT_UPGRADE_TEMPLATE
+  const command = template.split('{tag}').join(status.channel)
+  return h('div', { className: 'dm-dialog__mask', onClick: props.onCancel },
+    h('div', { className: 'dm-dialog', role: 'dialog', 'aria-modal': 'true', onClick: (e) => e.stopPropagation() },
+      h('div', { className: 'dm-card__title' }, '确认升级'),
+      h('div', { className: 'dm-dialog__hint' }, '将执行以下命令(升级期间页面可离开,进度由右下角浮条提示):'),
+      h('pre', { className: 'dm-pre' }, command),
+      h('div', { className: 'dm-dialog__section' },
+        h(Switch, {
+          label: '升级完成后自动重启宿主',
+          checked: autoRestart,
+          onChange: setAutoRestart,
+        }),
+        h('div', { className: 'dm-dialog__outcome' },
+          autoRestart
+            ? '已勾选:升级命令执行成功后,宿主将在 ' + AUTO_RESTART_DELAY_SEC + ' 秒后自动退出,由你的进程管理器(docker / pm2 / systemd 等)拉起新版本,本页随宿主恢复自动刷新。升级落定后宿主不再执行任何网络请求与磁盘读取。'
+            : '未勾选:升级完成后宿主继续运行当前版本,面板提示「重启宿主后生效」,需要你手动点击重启按钮才切换到新版本。'),
+        status.runtimeEnv && status.runtimeEnv.kind === RUNTIME_KIND_MANUAL
+          ? h('div', { className: 'dm-dialog__outcome dm-warn' }, '当前为手动终端直跑环境:没有进程管理器拉起宿主,勾选自动重启也不会自动退出,完成后仍需手动重启。')
+          : null,
+      ),
+      h('div', { className: 'dm-row' },
+        h('span', { className: 'dm-spacer' }),
+        h('button', { className: 'dm-btn', onClick: props.onCancel }, '取消'),
+        h('button', { className: 'dm-btn', onClick: () => props.onConfirm(autoRestart) }, '开始升级'),
+      ),
+    ),
+  )
+}
+
 function MaintainApp() {
   const [status, setStatus] = useState(null)
   const [error, setError] = useState(null)
   const [busy, setBusy] = useState({})
-  const [upgradeArmed, setUpgradeArmed] = useState(false)
+  const [upgradeDialogOpen, setUpgradeDialogOpen] = useState(false)
   const [restartArmed, setRestartArmed] = useState(false)
   const [restarting, setRestarting] = useState(false)
   // 重启探测的跨拍状态快照 {lost,pid,bootAt,readyStreak}:lost 与 readyStreak 随拍更新,
@@ -742,15 +824,10 @@ function MaintainApp() {
     submitEdit(REGISTRY_BASE_URL, { base }, 'registryBase', (error) => '保存失败:' + (error && error.message ? error.message : String(error)))
   }
 
-  function onUpgrade() {
-    if (!upgradeArmed) {
-      setUpgradeArmed(true)
-      setRestartArmed(false)
-      return
-    }
-    setUpgradeArmed(false)
+  function onUpgrade(autoRestart) {
+    setUpgradeDialogOpen(false)
     markBusy('upgrade', true)
-    post(UPGRADE_URL)
+    post(UPGRADE_URL, { autoRestart: autoRestart === true })
       .then((next) => {
         setStatus(next); setError(null)
         // 升级转后台执行:观察器接管状态跟踪与完成提示,页面可离开
@@ -764,7 +841,6 @@ function MaintainApp() {
     if (restartPendingRef.current) return
     if (!restartArmed) {
       setRestartArmed(true)
-      setUpgradeArmed(false)
       return
     }
     setRestartArmed(false)
@@ -826,13 +902,13 @@ function MaintainApp() {
       error !== null ? h('div', { className: 'dm-notice dm-notice--error' }, error) : null)
   }
 
-  // 升级入口不可用即解除两段式待发:渲染时派生,不引入 effect。
+  // 升级入口不可用即关闭确认弹窗:渲染时派生,不引入 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
+  const upgradeDialogOpenLive = upgradeDialogOpen && !upgradeUnavailable
   // 活跃工作计数:重启确认态显示计数并发 force 越过门控
   const activeWorkTotal = status !== null && status.activeWork ? status.activeWork.total : 0
 
@@ -850,13 +926,12 @@ function MaintainApp() {
     h(VersionCard, {
       status,
       busy,
-      upgradeArmed: upgradeArmedLive,
       restartArmed,
       restarting,
       onRefresh,
       onChannel,
       onTemplateSave,
-      onUpgrade,
+      onUpgrade: () => { setRestartArmed(false); setUpgradeDialogOpen(true) },
       onRestart,
     }),
     h(SettingsCard, {
@@ -868,6 +943,11 @@ function MaintainApp() {
     }),
     h(UpgradeCard, { status, restartArmed, restarting, activeWorkTotal, onRestart }),
     h(OpsCard, { status, armed: restartArmed, restarting, activeWorkTotal, onRestart }),
+    upgradeDialogOpenLive ? h(UpgradeDialog, {
+      status,
+      onCancel: () => setUpgradeDialogOpen(false),
+      onConfirm: onUpgrade,
+    }) : null,
   )
 }
 

package/src/core.mjs

@@ -241,6 +241,15 @@ export async function fetchDistTags({ registryBase, fetchImpl = fetch, timeoutMs
   return tags
 }
 
+// 运行版本事实源:运行进程 argv[1] 指向运行宿主自己的 bin.js(<包根>/lib/bin.js),
+// dirname 后上一级即包根,其 package.json 就是运行宿主清单。多副本共存时全局布局
+// 候选与 createRequire 解析都会命中其他副本(全局 0.1.5 + 副本跑旧版实测),只有
+// argv[1] 与运行进程绑定,列为最高优先级候选。
+export function runningHostCandidate({ argv1, pathImpl = win32 }) {
+  if (!argv1 || typeof argv1 !== 'string') return null
+  return pathImpl.join(pathImpl.dirname(argv1), '..', 'package.json')
+}
+
 // npm 全局布局下宿主包清单位置的候选序列;win 与 posix 目录结构不同,按声明平台选实现,与宿主 OS 解耦。
 export function hostPackageCandidates({ execPath, platform }) {
   const pathImpl = platform === 'win32' ? win32 : posix
@@ -251,17 +260,20 @@ export function hostPackageCandidates({ execPath, platform }) {
   return [pathImpl.join(globalDir, '@deepseek-ai', 'dsh', 'package.json')]
 }
 
-// 宿主实际安装版本:先按全局布局候选读文件,再退 createRequire 解析(插件可能随宿主树部署)。
-// 全部失败返回 null,面板显示未知,不影响宿主。
-export async function resolveHostVersion({ execPath, platform, readFileImpl = readFile, resolveImpl }) {
+// 宿主实际安装版本:运行宿主候选(argv[1] 推导)优先,再按全局布局候选,最后退
+// createRequire 解析(插件可能随宿主树部署)。全部失败返回 null,面板显示未知,不影响宿主。
+export async function resolveHostVersion({ execPath, platform, argv1, readFileImpl = readFile, resolveImpl }) {
+  const pathImpl = platform === 'win32' ? win32 : posix
+  const running = runningHostCandidate({ argv1, pathImpl })
   const candidates = hostPackageCandidates({ execPath, platform })
+  const ordered = running ? [running].concat(candidates) : candidates
   let requireResolved = null
   try {
     requireResolved = resolveImpl ? resolveImpl(TARGET_PACKAGE + '/package.json') : createRequire(import.meta.url)(TARGET_PACKAGE + '/package.json')
   } catch {
     requireResolved = null
   }
-  for (const candidate of requireResolved ? candidates.concat(requireResolved) : candidates) {
+  for (const candidate of requireResolved ? ordered.concat(requireResolved) : ordered) {
     try {
       const parsed = JSON.parse(await readFileImpl(candidate, 'utf8'))
       if (parsed && typeof parsed.version === 'string' && parsed.version.length > 0) return parsed.version

package/src/index.js

@@ -41,7 +41,7 @@ export const UPGRADE_TIMEOUT_MS = 10 * 60 * 1000
 // 响应发出到执行退出的延迟:保证浏览器收到 200 并进入重启等待态,进程才离场;
 // 导出仅供测试计算延迟窗口等待时长
 export const RESTART_DELAY_MS = 2 * 1000
-// 升级成功后自动重启的延迟:给 runCheck 与浮条终态一拍时间,观察器轮询可赶上;
+// 升级成功后自动重启的延迟:给浮条终态与观察器接管一拍时间,观察器轮询可赶上;
 // 导出仅供测试计算延迟窗口等待时长
 export const AUTO_RESTART_DELAY_MS = 3 * 1000
 // 轮询底层计时粒度;导出仅供 parity 测试与 client 提示文案对拍
@@ -202,12 +202,14 @@ export async function runUpgradeWithRetry({ command, timeoutMs = UPGRADE_TIMEOUT
   return { attempts, ok: false, kind: null, stillRunning: false, stdoutTail: '', stderrTail: '', error: null }
 }
 
-// 升级后自动重启守卫:四条件缺一不可——成功、非 stale、非手动直跑、appExit 可用。
-// 手动直跑(双 TTY)进程退出后无人拉起,只标 requiresManualRestart 交面板指引
-export function judgeAutoRestart({ ok, stale, runtimeKind, hasExit }) {
+// 升级后自动重启守卫:四条件缺一不可——成功、非手动直跑、本次勾选 enabled、appExit 可用。
+// 手动直跑(双 TTY)进程退出后无人拉起,只标 requiresManualRestart 交面板指引,
+// 该指引是环境约束事实,不受勾选影响;enabled 由升级路由严格 boolean 校验保证
+// 无 stale 条件:版本复读属升级后磁盘读取,关机路径禁止;版本是否前进由重启后的启动检查呈现
+export function judgeAutoRestart({ ok, runtimeKind, hasExit, enabled }) {
   if (ok !== true) return { schedule: false, requiresManualRestart: false }
-  if (stale === true) return { schedule: false, requiresManualRestart: false }
   if (runtimeKind === RUNTIME_KINDS.MANUAL_START) return { schedule: false, requiresManualRestart: true }
+  if (enabled !== true) return { schedule: false, requiresManualRestart: false }
   if (hasExit !== true) return { schedule: false, requiresManualRestart: false }
   return { schedule: true, requiresManualRestart: false }
 }
@@ -361,6 +363,7 @@ export function apply(ctx) {
     return resolveHostVersion({
       execPath: process.execPath,
       platform: process.platform,
+      argv1: process.argv[1],
       readFileImpl: readFile,
       resolveImpl: undefined,
     })
@@ -434,7 +437,8 @@ export function apply(ctx) {
       return
     }
     const dispose = timerCtx.interval(() => {
-      if (checkInFlight !== null || nextDueAt === null || Date.now() < nextDueAt) return
+      // restartScheduled 窗口内不再发起检查:关机延迟期间的网络请求与磁盘读取都是半写状态风险
+      if (restartScheduled || checkInFlight !== null || nextDueAt === null || Date.now() < nextDueAt) return
       runCheck().then(scheduleNext, scheduleNext)
     }, TICK_MS)
     ctx.effect(() => dispose, 'dsh-maintain poll interval')
@@ -480,7 +484,7 @@ export function apply(ctx) {
     }
   }
 
-  function triggerUpgrade() {
+  function triggerUpgrade(autoRestart) {
     const config = readSettings(ctx)
     // 模板校验同步失败即同步 throw,由调用方 try/catch 转 400,不走异步通道
     const command = buildUpgradeCommand({ template: config.upgradeCommandTemplate, tag: config.channel })
@@ -505,8 +509,8 @@ export function apply(ctx) {
     // running 即串行化门闩:路由检查与本处置位之间无 await,单线程下无竞态窗口
     upgrade = { running: true, last }
     writeUpgradeLock(last.startedAt)
-    audit('upgrade', 'triggered', 'command=' + singleLine(command))
-    void performUpgrade(command, last, config.channel)
+    audit('upgrade', 'triggered', 'command=' + singleLine(command) + ' autoRestart=' + (autoRestart === true))
+    void performUpgrade(command, last, config.channel, autoRestart === true)
   }
 
   // 升级锁文件只在此写入:首次与每次重试覆写,startedAt 取当前尝试开始时刻,
@@ -517,20 +521,24 @@ export function apply(ctx) {
     } catch { /* 锁不可写仅损失跨进程防护,内存门闩仍生效 */ }
   }
 
-  // 自动重启与手动重启共用 restartScheduled 互斥:调度窗口内到达的升级被 409,
-  // 手动重启端点幂等;autoRestartScheduled 单独给 status/client 分流终态文案
-  function scheduleAutoRestart() {
+  // 宿主退出调度唯一入口:手动重启(HTTP 入口)与升级落定(内部入口)共用,
+  // 置双向互斥标记、留审计、延迟 exit(0)。调度窗口内升级被 409,手动重启幂等
+  function scheduleHostExit({ detail, autoRestart = false, delayMs }) {
     restartScheduled = true
-    autoRestartScheduled = true
-    audit('restart', 'scheduled', 'reason=upgrade-ok delayMs=' + AUTO_RESTART_DELAY_MS)
-    setTimeout(() => exit(0), AUTO_RESTART_DELAY_MS)
+    if (autoRestart === true) autoRestartScheduled = true
+    audit('restart', autoRestart === true ? 'scheduled' : 'triggered', detail + ' delayMs=' + delayMs)
+    // 退出延迟与响应冲刷解耦:客户端在冲刷完成前断连会让 end 回调失效,绑定其上会使重启悬空;
+    // 同步发出响应后延迟退出,延迟本身保证回执先于进程离场送达
+    setTimeout(() => exit(0), delayMs)
   }
 
-  async function performUpgrade(command, last, channel) {
+  async function performUpgrade(command, last, channel, autoRestart) {
+    // settle 声明在 try 外:继续运行路径的版本复读在 finally 中消费它
+    let settle = null
     try {
-      // 触发前快照磁盘版本,成功落定后复读对比,版本未前进或未达目标即标 stale
+      // 触发前快照磁盘版本,继续运行路径复读时以此为对比基线
       last.previousVersion = await resolveCurrentHostVersion()
-      const settle = await runUpgradeWithRetry({
+      settle = await runUpgradeWithRetry({
         command,
         onAttemptStart: () => writeUpgradeLock(Date.now()),
       })
@@ -547,20 +555,11 @@ export function apply(ctx) {
         stdoutTail: settle.stdoutTail,
         stderrTail: settle.stderrTail,
       })
-      if (settle.ok) {
-        last.installedVersion = await resolveCurrentHostVersion()
-        const tags = snapshot.tags
-        const freshness = judgeUpgradeFreshness({
-          previousVersion: last.previousVersion,
-          installedVersion: last.installedVersion,
-          channelLatest: tags !== null && Object.prototype.hasOwnProperty.call(tags, channel) ? tags[channel] : null,
-        })
-        last.stale = freshness.stale
-        last.reason = freshness.reason
-      }
     } catch (error) {
       last.error = error && error.message ? error.message : String(error)
     } finally {
+      // 关机路径经 return 提前离场会吞掉 finally 内新抛异常:本块各消费点已 try/catch
+      // 防御(删锁/复读/runCheck),后续修改必须保持该契约,勿在此块新增可抛调用
       if (last.finishedAt === null) last.finishedAt = Date.now()
       upgrade = { running: false, last }
       // stillRunning(强杀后进程树疑似仍在写全局目录)时保留锁文件,由过期机制收敛,
@@ -580,14 +579,33 @@ export function apply(ctx) {
         + (last.stale === true ? ' stale=' + singleLine(last.reason) : ''))
       audit('upgrade', last.ok === true ? 'ok' : 'failed',
         'durationMs=' + (last.finishedAt - last.startedAt) + ' code=' + last.code + ' kind=' + singleLine(last.kind))
-      // 自动重启守卫:等环境检测落定后按四条件分流(手动直跑只标指引,不退出)
+      // 关机前置判定只取内存输入(启动期缓存的运行环境 + 本次会话勾选):升级命令刚
+      // 替换过宿主磁盘文件,落定钩子发起网络请求或读取磁盘都是半写状态下的故障源
       await runtimeEnvReady
-      const decision = judgeAutoRestart({ ok: last.ok === true, stale: last.stale === true, runtimeKind: runtimeEnv.kind, hasExit: typeof exit === 'function' })
+      const decision = judgeAutoRestart({ ok: last.ok === true, runtimeKind: runtimeEnv.kind, hasExit: typeof exit === 'function', enabled: autoRestart === true })
       if (decision.requiresManualRestart === true) last.requiresManualRestart = true
       if (decision.schedule === true) {
+        // 关机路径零收尾:与确认重启同一内部动作,直接进入延迟退出
         // last 镜像调度标记:浮条终态文案按其分流(与 status.autoRestartScheduled 同值)
         last.autoRestartScheduled = true
-        scheduleAutoRestart()
+        scheduleHostExit({ detail: 'reason=upgrade-ok', autoRestart: true, delayMs: AUTO_RESTART_DELAY_MS })
+        return
+      }
+      // 继续运行路径(失败/手动直跑/本次未勾选自动重启):复读磁盘版本标 stale,版本未前进提示保留
+      if (settle !== null && settle.ok) {
+        // 复读属磁盘消费点,拒绝不得以 unhandledRejection 形式逃逸(void 触发即崩宿主):
+        // 失败时放弃 stale 判定,保留已装版本 null 由启动检查兜底呈现
+        try {
+          last.installedVersion = await resolveCurrentHostVersion()
+          const tags = snapshot.tags
+          const freshness = judgeUpgradeFreshness({
+            previousVersion: last.previousVersion,
+            installedVersion: last.installedVersion,
+            channelLatest: tags !== null && Object.prototype.hasOwnProperty.call(tags, channel) ? tags[channel] : null,
+          })
+          last.stale = freshness.stale
+          last.reason = freshness.reason
+        } catch { /* 复读失败仅损失 stale 提示,不覆盖升级成功结果 */ }
       }
       // 升级结束后自动重新检查版本并重排轮询(命令可能改了本地版本)
       runCheck().then(scheduleNext, scheduleNext)
@@ -606,6 +624,10 @@ export function apply(ctx) {
     {
       path: API_PATHS.REFRESH,
       handler: route('POST', WRITE, async (req, res) => {
+        if (restartScheduled) {
+          sendJson(res, 409, { error: '重启已调度,禁止检查更新' })
+          return
+        }
         await drainInFlightThenCheck()
         scheduleNext()
         sendJson(res, 200, await currentStatus())
@@ -698,6 +720,11 @@ export function apply(ctx) {
           return
         }
         await settings.update(NAMESPACE, { registryBase: base })
+        if (restartScheduled) {
+          // 保存生效但不发起检查:关机窗口内网络请求与磁盘读取都是半写状态风险
+          sendJson(res, 200, await currentStatus())
+          return
+        }
         await drainInFlightThenCheck()
         scheduleNext()
         sendJson(res, 200, await currentStatus())
@@ -706,6 +733,15 @@ export function apply(ctx) {
     {
       path: API_PATHS.UPGRADE,
       handler: route('POST', WRITE, async (req, res) => {
+        // body 校验必须在全部门控之前:门控到 triggerUpgrade 置位之间不得插入 await,
+        // 否则并发请求双双通过 409 门控,两个升级进程并发写全局目录
+        // 自动重启为确认弹窗的会话级勾选,严格 boolean:缺失/宽转一律拒绝,防静默翻转关机行为
+        const rawBody = await readBody(req)
+        const requestBody = rawBody ? (JSON.parse(rawBody) || {}) : {}
+        if (typeof requestBody.autoRestart !== 'boolean') {
+          sendJson(res, 400, { error: 'autoRestart 必须是 boolean' })
+          return
+        }
         // 与重启调度双向互斥:restartScheduled 置位到 exit(0) 执行的窗口内触发升级,
         // detached 孤儿会与新宿主交错
         if (upgrade.running || restartScheduled) {
@@ -737,13 +773,18 @@ export function apply(ctx) {
           })
           return
         }
-        triggerUpgrade()
+        triggerUpgrade(requestBody.autoRestart)
         sendJson(res, 200, await currentStatus())
       }),
     },
     {
       path: API_PATHS.RESTART,
       handler: route('POST', WRITE, async (req, res) => {
+        // body 读取必须在全部门控之前:幂等检查到 scheduleHostExit 置位之间不得插入
+        // await,否则并发请求双双越过幂等门,双重调度 exit
+        const rawBody = await readBody(req)
+        // 'null' 字面量解析为 null:按空体处理,防 null.force 形态的内部错误外泄
+        const requestBody = rawBody ? (JSON.parse(rawBody) || {}) : {}
         // 与升级门闩互斥:升级子进程经 detached+unref 存活于宿主死后,
         // 重启后新宿主门闩归零会放行第二次升级,双 npm install 并发写全局目录
         if (upgrade.running) {
@@ -762,9 +803,6 @@ export function apply(ctx) {
         }
         // 活跃工作门控:重启可被 force 越过(升级后自动重启链路无法等待人工确认,
         // 对齐 dsh-service:升级不可越/重启 force 可越)
-        const rawBody = await readBody(req)
-        // 'null' 字面量解析为 null:按空体处理,防 null.force 形态的内部错误外泄
-        const requestBody = rawBody ? (JSON.parse(rawBody) || {}) : {}
         const activeWork = collectActiveWork(ctx)
         if (activeWork.total > 0 && requestBody.force !== true) {
           audit('restart', 'rejected', 'reason=active-work total=' + activeWork.total)
@@ -775,12 +813,9 @@ export function apply(ctx) {
           })
           return
         }
-        restartScheduled = true
-        audit('restart', 'triggered', requestBody.force === true ? 'forced=true' : 'forced=false')
+        // 响应先发,退出调度经统一入口(与升级落定关机同一条链)
         sendJson(res, 200, { ok: true, restarting: true })
-        // 退出延迟与响应冲刷解耦:客户端在冲刷完成前断连会让 end 回调失效,绑定其上会使重启悬空;
-        // 同步发出响应后延迟退出,延迟本身保证回执先于进程离场送达
-        setTimeout(() => exit(0), RESTART_DELAY_MS)
+        scheduleHostExit({ detail: 'forced=' + (requestBody.force === true), delayMs: RESTART_DELAY_MS })
       }),
     },
   ]

package/test/dist-tags.test.mjs

@@ -191,6 +191,42 @@ test('场景:全部途径失败返回 null 不抛错', async () => {
   assert.equal(version, null)
 })
 
+test('场景:运行宿主候选(argv1 推导)优先于全局布局', async () => {
+  // 多副本共存:全局是 0.1.5,实际运行的是副本树内 0.1.1-rc.2,运行版本必须取 argv1 推导的包根
+  const files = {
+    'C:\\deploy\\.dsh-versions\\0.1.1-rc.2\\node_modules\\@deepseek-ai\\dsh\\package.json': JSON.stringify({ version: '0.1.1-rc.2' }),
+    'C:\\nvm\\v24\\node_modules\\@deepseek-ai\\dsh\\package.json': JSON.stringify({ version: '0.1.5-rc.1' }),
+  }
+  const version = await resolveHostVersion({
+    execPath: 'C:\\nvm\\v24\\node.exe',
+    platform: 'win32',
+    argv1: 'C:\\deploy\\.dsh-versions\\0.1.1-rc.2\\node_modules\\@deepseek-ai\\dsh\\lib\\bin.js',
+    readFileImpl: async (path) => {
+      if (!Object.prototype.hasOwnProperty.call(files, path)) throw new Error('ENOENT')
+      return files[path]
+    },
+    resolveImpl: () => { throw new Error('MODULE_NOT_FOUND') },
+  })
+  assert.equal(version, '0.1.1-rc.2')
+})
+
+test('场景:argv1 缺失或不可读时回退全局布局候选', async () => {
+  const files = {
+    '/prefix/lib/node_modules/@deepseek-ai/dsh/package.json': JSON.stringify({ version: '1.0.0' }),
+  }
+  const readFileFor = (files) => async (path) => {
+    if (!Object.prototype.hasOwnProperty.call(files, path)) throw new Error('ENOENT')
+    return files[path]
+  }
+  const common = { execPath: '/prefix/bin/node', platform: 'linux', resolveImpl: () => { throw new Error('MODULE_NOT_FOUND') } }
+  // argv1 为空
+  const v1 = await resolveHostVersion({ ...common, argv1: undefined, readFileImpl: readFileFor(files) })
+  assert.equal(v1, '1.0.0')
+  // argv1 指向的包根不可读,回退
+  const v2 = await resolveHostVersion({ ...common, argv1: '/nowhere/lib/bin.js', readFileImpl: readFileFor(files) })
+  assert.equal(v2, '1.0.0')
+})
+
 test('场景:候选文件可读但 version 非法时静默换下一候选', async () => {
   const files = {
     '/prefix/lib/node_modules/@deepseek-ai/dsh/package.json': JSON.stringify({ name: 'x' }),

package/test/parity.test.mjs

@@ -92,6 +92,17 @@ test('parity: VERDICT 三常量 client 与 core 一致', () => {
   assert.equal(extractConst('VERDICT_UNKNOWN'), VERDICT_UNKNOWN)
 })
 
+// host 侧锚点直接 import runtime.mjs 实现,防测试内手抄字面量漂移假绿
+import { RUNTIME_KINDS } from '../src/runtime.mjs'
+
+test('parity: 手动直跑运行环境常量 client 与 host 一致', () => {
+  assert.equal(extractConst('RUNTIME_KIND_MANUAL'), RUNTIME_KINDS.MANUAL_START)
+})
+
+test('parity: 弹窗文案自动重启延迟秒与 host AUTO_RESTART_DELAY_MS 换算一致', () => {
+  assert.equal(extractNumberConst('AUTO_RESTART_DELAY_SEC'), AUTO_RESTART_DELAY_MS / 1000)
+})
+
 // host 侧锚点直接 import index.js 实现,防测试内手抄字面量漂移假绿
 import {
   DEFAULT_UPGRADE_TEMPLATE,

package/test/route.test.mjs

@@ -6,7 +6,7 @@ import { test } from 'node:test'
 import assert from 'node:assert/strict'
 import { EventEmitter } from 'node:events'
 
-import { apply, RESTART_DELAY_MS, UPGRADE_LOCK_PATH, collectActiveWork } from '../src/index.js'
+import { apply, RESTART_DELAY_MS, AUTO_RESTART_DELAY_MS, UPGRADE_LOCK_PATH, collectActiveWork } from '../src/index.js'
 import { rmSync, readFileSync } from 'node:fs'
 
 // 锁文件是固定共享路径:测试进程中断可能残留幽灵锁毒化后续运行,用例前预热清理
@@ -128,6 +128,15 @@ async function call(routes, path, req) {
 const post = (routes, path, body, headers) => call(routes, path, makeReq({ method: 'POST', body, headers }))
 const get = (routes, path) => call(routes, path, makeReq({ method: 'GET' }))
 
+// 排空微任务链(setImmediate 为宏任务,先于其执行的全部微任务此后必已完成)
+const drainMicrotasks = () => new Promise((resolve) => setImmediate(resolve))
+// 真实时间等待:mock timers 域内 setTimeout 不再真实计时,以 setImmediate 自旋让出事件循环
+const realSleep = (ms) => new Promise((resolve) => {
+  const start = Date.now()
+  const spin = () => { if (Date.now() - start >= ms) resolve(); else setImmediate(spin) }
+  setImmediate(spin)
+})
+
 test('挂载:8 条路由注册,启动检查后快照就绪', async () => {
   const { ctx, routes } = makeCtx()
   apply(ctx)
@@ -302,7 +311,7 @@ test('upgrade:运行版本已是通道最新 409 拒绝(防降级),unknown 放
     const refreshed = await post(routes, '/api/maintain/refresh')
     assert.equal(refreshed.status, 200)
     assert.equal(refreshed.payload.verdict, 'up-to-date', '前置:注入运行版本应高于 0.0.1 假目标')
-    const denied = await post(routes, '/api/maintain/upgrade')
+    const denied = await post(routes, '/api/maintain/upgrade', { autoRestart: true })
     assert.equal(denied.status, 409)
     assert.match(denied.payload.error, /已是通道最新版/)
     assert.equal(store.upgradeCommandTemplate, 'node -e "process.exit(0)"', '拒绝路径不得触发升级')
@@ -328,7 +337,7 @@ test('upgrade:verdict unknown 放行(tags 未就绪不得 409 误拒)', async ()
     assert.ok(snapshot, '启动检查 5 秒内未完成')
     assert.equal(snapshot.tags, null, '前置:registry 不可达,tags 未就绪')
     assert.equal(snapshot.verdict, 'unknown', '前置:verdict 应为 unknown')
-    const allowed = await post(routes, '/api/maintain/upgrade')
+    const allowed = await post(routes, '/api/maintain/upgrade', { autoRestart: true })
     assert.equal(allowed.status, 200, 'verdict unknown 必须放行,不得 409 误拒')
     assert.equal(allowed.payload.upgrade.running, true)
     // 等假命令落定:防残留升级锁毒化后续用例
@@ -357,11 +366,11 @@ test('upgrade:真实挂起命令触达门闩,二次 409,结束后自动重查',
   const { ctx, routes } = makeCtx({ settingsStore: store })
   apply(ctx)
   const baseline = await get(routes, '/api/maintain/status').then((r) => r.payload)
-  const first = await post(routes, '/api/maintain/upgrade')
+  const first = await post(routes, '/api/maintain/upgrade', { autoRestart: true })
   assert.equal(first.status, 200)
   assert.equal(first.payload.upgrade.running, true)
   assert.equal(first.payload.upgradeLockHeld, true, '升级期间锁文件持有效力')
-  const second = await post(routes, '/api/maintain/upgrade')
+  const second = await post(routes, '/api/maintain/upgrade', { autoRestart: true })
   assert.equal(second.status, 409)
   // 等挂起命令自然退出(轮询而非固定 sleep,兼做落定状态显式断言)
   let settled = null
@@ -377,47 +386,55 @@ test('upgrade:真实挂起命令触达门闩,二次 409,结束后自动重查',
   assert.ok(settled.checkedAt !== null)
 })
 
-test('upgrade:落定后复读磁盘版本,假命令未升级版本时标 stale', async () => {
+test('upgrade:托管+勾选自动重启,命令成功即调度关机且落定钩子零网络零读盘', async (t) => {
   const store = { upgradeCommandTemplate: 'node -e "process.exit(0)"' }
   const exits = []
-  const { ctx, routes } = makeCtx({ settingsStore: store, appExit: (code) => exits.push(code) })
-  apply(ctx)
-  const first = await post(routes, '/api/maintain/upgrade')
-  assert.equal(first.status, 200)
-  let settled = null
-  for (let i = 0; i < 50 && settled === null; i += 1) {
-    await new Promise((resolve) => setTimeout(resolve, 100))
-    const status = await get(routes, '/api/maintain/status').then((r) => r.payload).catch(() => null)
-    if (status && status.upgrade && status.upgrade.running === false && status.upgrade.last !== null) settled = status
+  let fetchCalls = 0
+  const originalFetch = globalThis.fetch
+  globalThis.fetch = async (...args) => {
+    fetchCalls += 1
+    return originalFetch(...args)
   }
-  assert.ok(settled, '升级应在假命令退出后落定')
-  assert.equal(settled.upgrade.last.ok, true)
-  assert.ok('previousVersion' in settled.upgrade.last, '触发前磁盘版本快照必须进 status')
-  assert.equal(settled.upgrade.last.installedVersion, settled.upgrade.last.previousVersion, '假命令不改磁盘,复读版本应与快照一致')
-  assert.equal(settled.upgrade.last.stale, true, '版本未前进必须标 stale(镜像滞后/静默未升)')
-  assert.ok(typeof settled.upgrade.last.reason === 'string' && settled.upgrade.last.reason.length > 0)
-  // stale 抑制自动重启:不调度退出、不标手动指引;重启互斥同步释放
-  assert.equal(settled.autoRestartScheduled, false)
-  assert.equal(settled.upgrade.last.requiresManualRestart, undefined)
-  assert.ok(typeof settled.runtimeEnv === 'object' && typeof settled.runtimeEnv.kind === 'string', 'runtimeEnv 必须进 status')
-  const restart = await post(routes, '/api/maintain/restart')
-  assert.equal(restart.status, 200, 'stale 落定后重启互斥必须已释放')
-})
-
-test('upgrade:stale 落定不调度自动重启(宿主退出零触发)', async () => {
-  const store = { upgradeCommandTemplate: 'node -e "process.exit(0)"' }
-  const exits = []
-  const { ctx, routes } = makeCtx({ settingsStore: store, appExit: (code) => exits.push(code) })
-  apply(ctx)
-  await post(routes, '/api/maintain/upgrade')
-  for (let i = 0; i < 50; i += 1) {
-    await new Promise((resolve) => setTimeout(resolve, 100))
-    const status = await get(routes, '/api/maintain/status').then((r) => r.payload).catch(() => null)
-    if (status && status.upgrade && status.upgrade.running === false && status.upgrade.last !== null) break
+  t.mock.timers.enable({ apis: ['setTimeout'] })
+  try {
+    const { ctx, routes } = makeCtx({ settingsStore: store, appExit: (code) => exits.push(code) })
+    apply(ctx)
+    // 等启动检查落定,固定网络请求基线(mock timers 域内以 realSleep 自旋让出事件循环)
+    let baseline = null
+    for (let waited = 0; waited < 5000 && baseline === null; waited += 25) {
+      const poll = await get(routes, '/api/maintain/status').then((r) => r.payload).catch(() => null)
+      if (poll && poll.checkedAt !== null) baseline = fetchCalls
+      else await realSleep(25)
+    }
+    assert.ok(baseline !== null, '启动检查 5 秒内未完成')
+    const first = await post(routes, '/api/maintain/upgrade', { autoRestart: true })
+    assert.equal(first.status, 200)
+    let settled = null
+    for (let i = 0; i < 50 && settled === null; i += 1) {
+      await realSleep(30)
+      const status = await get(routes, '/api/maintain/status').then((r) => r.payload).catch(() => null)
+      if (status && status.upgrade && status.upgrade.running === false && status.upgrade.last !== null) settled = status
+    }
+    assert.ok(settled, '升级应在假命令退出后落定')
+    assert.equal(settled.upgrade.last.ok, true)
+    // 关机路径零复读:版本复读属升级后磁盘读取,是明确的故障源,砍掉
+    assert.equal(settled.upgrade.last.installedVersion, null, '关机路径禁止复读磁盘版本')
+    assert.equal(settled.upgrade.last.stale, null, '关机路径无 stale 判定')
+    assert.equal(settled.upgrade.last.requiresManualRestart, undefined)
+    assert.equal(settled.autoRestartScheduled, true, '命令成功即调度关机(stale 不再抑制)')
+    assert.equal(settled.upgradeLockHeld, false, '升级结束后锁文件应删除')
+    assert.ok(typeof settled.runtimeEnv === 'object' && typeof settled.runtimeEnv.kind === 'string', 'runtimeEnv 必须进 status')
+    // 落定钩子零网络:观察窗口内 fetch 计数不得增长(runCheck 已随关机路径移除)
+    await realSleep(300)
+    assert.equal(fetchCalls, baseline, '落定钩子禁止网络请求')
+    // 关机动作与确认重启同源:延迟窗口后 exit(0),窗口内不得提前
+    assert.deepEqual(exits, [], '延迟窗口内不得提前退出')
+    t.mock.timers.tick(AUTO_RESTART_DELAY_MS + 1)
+    assert.deepEqual(exits, [0], '延迟窗口过后必须调度宿主退出')
+  } finally {
+    globalThis.fetch = originalFetch
+    rmSync(UPGRADE_LOCK_PATH, { force: true })
   }
-  // 观察窗口覆盖自动重启延迟:若误调度,延迟窗口内 exit 会被调用
-  await new Promise((resolve) => setTimeout(resolve, 200))
-  assert.deepEqual(exits, [], 'stale 时禁止调度任何宿主退出')
 })
 
 test('restart:升级进行中 409 拒绝且不调度退出', async () => {
@@ -425,7 +442,7 @@ test('restart:升级进行中 409 拒绝且不调度退出', async () => {
   const exits = []
   const { ctx, routes } = makeCtx({ settingsStore: store, appExit: (code) => exits.push(code) })
   apply(ctx)
-  const upgrade = await post(routes, '/api/maintain/upgrade')
+  const upgrade = await post(routes, '/api/maintain/upgrade', { autoRestart: true })
   assert.equal(upgrade.status, 200)
   const denied = await post(routes, '/api/maintain/restart')
   assert.equal(denied.status, 409)
@@ -447,13 +464,50 @@ test('upgrade:重启调度后触发升级 409(双向互斥)', async (t) => {
   apply(ctx)
   const restart = await post(routes, '/api/maintain/restart')
   assert.equal(restart.status, 200)
-  const denied = await post(routes, '/api/maintain/upgrade')
+  const denied = await post(routes, '/api/maintain/upgrade', { autoRestart: true })
   assert.equal(denied.status, 409)
   assert.match(denied.payload.error, /重启已调度/)
   t.mock.timers.tick(RESTART_DELAY_MS + 1)
   assert.deepEqual(exits, [0])
 })
 
+test('upgrade:重启调度窗口内 refresh 409,registry-base 保存但不发起检查', async (t) => {
+  // 关机延迟窗口内网络请求与磁盘读取都是半写状态风险:refresh 全拒,registry-base 只落盘
+  t.mock.timers.enable({ apis: ['setTimeout'] })
+  const store = { registryBase: 'https://registry.npmjs.org' }
+  let fetchCalls = 0
+  const originalFetch = globalThis.fetch
+  globalThis.fetch = async (...args) => {
+    fetchCalls += 1
+    return originalFetch(...args)
+  }
+  try {
+    const exits = []
+    const { ctx, routes } = makeCtx({ settingsStore: store, appExit: (code) => exits.push(code) })
+    apply(ctx)
+    let baseline = null
+    for (let waited = 0; waited < 5000 && baseline === null; waited += 25) {
+      const poll = await get(routes, '/api/maintain/status').then((r) => r.payload).catch(() => null)
+      if (poll && poll.checkedAt !== null) baseline = fetchCalls
+      else await realSleep(25)
+    }
+    assert.ok(baseline !== null, '启动检查 5 秒内未完成')
+    const restart = await post(routes, '/api/maintain/restart')
+    assert.equal(restart.status, 200)
+    const refresh = await post(routes, '/api/maintain/refresh')
+    assert.equal(refresh.status, 409, '关机窗口内检查更新必须拒绝')
+    const saved = await post(routes, '/api/maintain/registry-base', { base: 'https://mirror.example.org' })
+    assert.equal(saved.status, 200, '镜像地址保存照常落盘')
+    assert.equal(store.registryBase, 'https://mirror.example.org')
+    assert.equal(saved.payload.registryBase, 'https://mirror.example.org', 'status 回显新地址')
+    assert.equal(fetchCalls, baseline, '关机窗口内不得发起任何网络检查')
+    t.mock.timers.tick(RESTART_DELAY_MS + 1)
+    assert.deepEqual(exits, [0])
+  } finally {
+    globalThis.fetch = originalFetch
+  }
+})
+
 test('status:快照携带 bootAt 实例代际', async () => {
   const { ctx, routes } = makeCtx()
   apply(ctx)
@@ -495,6 +549,103 @@ test('poll-interval:超上界 400(秒转毫秒溢出防护)', async () => {
   assert.equal(store.pollIntervalSec, undefined, '超上界值不得落盘')
 })
 
+test('upgrade:未勾选自动重启,升级成功落定继续运行并标 stale', async (t) => {
+  const store = { upgradeCommandTemplate: 'node -e "process.exit(0)"' }
+  const exits = []
+  const { ctx, routes } = makeCtx({
+    settingsStore: store,
+    appExit: (code) => exits.push(code),
+    // 探针恒读旧版:模拟假命令不改磁盘,复读版本与触发前快照一致即 stale
+    services: { hostVersionProbe: () => Promise.resolve('1.0.0') },
+  })
+  t.mock.timers.enable({ apis: ['setTimeout'] })
+  apply(ctx)
+  // 排空启动期微任务链,探针读序此后稳定
+  await drainMicrotasks()
+  const trigger = await post(routes, '/api/maintain/upgrade', { autoRestart: false })
+  assert.equal(trigger.status, 200)
+  let settled = null
+  try {
+    for (let i = 0; i < 50 && settled === null; i += 1) {
+      await realSleep(30)
+      const status = await get(routes, '/api/maintain/status').then((r) => r.payload).catch(() => null)
+      if (status && status.upgrade && status.upgrade.running === false && status.upgrade.last !== null) settled = status
+    }
+    assert.ok(settled, '升级应在假命令退出后落定')
+    assert.equal(settled.upgrade.last.ok, true)
+    // 假命令不改磁盘,复读版本与触发前快照一致 → stale
+    assert.equal(settled.upgrade.last.stale, true, '继续运行路径必须复读并标注 stale')
+    assert.ok(typeof settled.upgrade.last.reason === 'string' && settled.upgrade.last.reason.length > 0, 'stale 必须带原因')
+    assert.equal(settled.autoRestartScheduled, false, '未勾选不得置调度标记')
+    assert.equal(settled.upgrade.last.requiresManualRestart, undefined, '托管环境未勾选不标手动指引')
+    // 推过完整调度延迟:若误调度,延迟窗口内 exit 必被调用
+    t.mock.timers.tick(AUTO_RESTART_DELAY_MS + 1)
+    assert.deepEqual(exits, [], '未勾选自动重启时禁止调度任何宿主退出')
+  } finally {
+    rmSync(UPGRADE_LOCK_PATH, { force: true })
+  }
+})
+
+test('upgrade:勾选自动重启+落定,延迟窗口后调度宿主退出', async (t) => {
+  const store = { upgradeCommandTemplate: 'node -e "process.exit(0)"' }
+  const exits = []
+  const { ctx, routes } = makeCtx({
+    settingsStore: store,
+    appExit: (code) => exits.push(code),
+    // 关机路径零读盘:探针返回值不影响断言,恒读旧版即可
+    services: { hostVersionProbe: () => Promise.resolve('1.0.0') },
+  })
+  t.mock.timers.enable({ apis: ['setTimeout'] })
+  apply(ctx)
+  await drainMicrotasks()
+  const trigger = await post(routes, '/api/maintain/upgrade', { autoRestart: true })
+  assert.equal(trigger.status, 200)
+  let settled = null
+  try {
+    for (let i = 0; i < 50 && settled === null; i += 1) {
+      await realSleep(30)
+      const status = await get(routes, '/api/maintain/status').then((r) => r.payload).catch(() => null)
+      if (status && status.upgrade && status.upgrade.running === false && status.upgrade.last !== null) settled = status
+    }
+    assert.ok(settled, '升级应在假命令退出后落定')
+    assert.equal(settled.upgrade.last.ok, true)
+    assert.equal(settled.upgrade.last.stale, null, '关机路径零复读,stale 不再判定')
+    // 落定可见与调度置位之间隔 runtimeEnvReady 的 await:await 一次 status 让微任务链走完再断言
+    const scheduled = await get(routes, '/api/maintain/status').then((r) => r.payload)
+    assert.equal(scheduled.autoRestartScheduled, true, '勾选自动重启时升级成功必须调度')
+    assert.deepEqual(exits, [], '调度延迟窗口内不得提前退出')
+    t.mock.timers.tick(AUTO_RESTART_DELAY_MS + 1)
+    assert.deepEqual(exits, [0], '延迟窗口过后必须调度宿主退出')
+  } finally {
+    rmSync(UPGRADE_LOCK_PATH, { force: true })
+  }
+})
+
+test('upgrade:autoRestart 缺失或非 boolean 一律 400', async () => {
+  // 假命令兜底:本用例期待 400,但若校验意外放行,真实默认模板会当场触发 npm install
+  const store = { upgradeCommandTemplate: 'node -e "process.exit(0)"' }
+  const { ctx, routes } = makeCtx({ settingsStore: store })
+  apply(ctx)
+  const missing = await post(routes, '/api/maintain/upgrade')
+  assert.equal(missing.status, 400, '缺失 autoRestart 必须拒绝,防静默翻转关机行为')
+  const stringInput = await post(routes, '/api/maintain/upgrade', { autoRestart: 'true' })
+  assert.equal(stringInput.status, 400, '字符串宽转必须拒绝')
+  const status = await get(routes, '/api/maintain/status').then((r) => r.payload)
+  assert.equal(status.upgrade.running, false, '非法输入不得触发升级')
+  assert.equal(status.upgrade.last, null, '非法输入不得产生升级记录')
+})
+
+test('upgrade:body 校验先于门控,门控命中时非法 body 仍 400', async (t) => {
+  // 锁定 handler 顺序:readBody 在全部门控之前,门控到置位之间零 await
+  t.mock.timers.enable({ apis: ['setTimeout'] })
+  const store = { upgradeCommandTemplate: 'node -e "process.exit(0)"' }
+  const { ctx, routes } = makeCtx({ settingsStore: store, appExit: () => {} })
+  apply(ctx)
+  await post(routes, '/api/maintain/restart')
+  const denied = await post(routes, '/api/maintain/upgrade')
+  assert.equal(denied.status, 400, 'body 非法时即使门控(重启已调度)命中也必须 400')
+})
+
 test('registry-base:带 query 或 hash 的输入 400', async () => {
   const store = {}
   const { ctx, routes } = makeCtx({ settingsStore: store })
@@ -596,7 +747,7 @@ test('upgrade:存在活跃工作 409 拒绝,不可越', async () => {
   const terminals = { list: () => [] }
   const { ctx, routes } = makeCtx({ settingsStore: store, services: { agents, jobs, terminals } })
   apply(ctx)
-  const denied = await post(routes, '/api/maintain/upgrade')
+  const denied = await post(routes, '/api/maintain/upgrade', { autoRestart: true })
   assert.equal(denied.status, 409)
   assert.match(denied.payload.error, /活跃工作/)
   assert.equal(denied.payload.items.agents, 1)
@@ -649,7 +800,7 @@ test('自动重启接线:落定链消费运行环境并分流调度与手动指
   assert.ok(settle, '落定链缺少 judgeAutoRestart 判定')
   assert.match(settle[1], /runtimeKind: runtimeEnv\.kind/, '落定判定必须消费运行环境检测结果')
   assert.match(source, /if \(decision\.requiresManualRestart === true\) last\.requiresManualRestart = true/, '手动直跑指引必须回写 last')
-  assert.match(source, /if \(decision\.schedule === true\) \{[\s\S]*?last\.autoRestartScheduled = true[\s\S]*?scheduleAutoRestart\(\)/, '调度链必须置位标记并调用 scheduleAutoRestart')
+  assert.match(source, /if \(decision\.schedule === true\) \{[\s\S]*?last\.autoRestartScheduled = true[\s\S]*?scheduleHostExit\(\{ detail: 'reason=upgrade-ok', autoRestart: true/, '调度链必须置位标记并经统一退出入口关机')
 })
 
 test('upgrade:env 注入手动直跑环境,落定链保守分流零退出', async () => {
@@ -659,7 +810,7 @@ test('upgrade:env 注入手动直跑环境,落定链保守分流零退出', asyn
     const exits = []
     const { ctx, routes } = makeCtx({ settingsStore: store, appExit: (code) => exits.push(code) })
     apply(ctx)
-    await post(routes, '/api/maintain/upgrade')
+    await post(routes, '/api/maintain/upgrade', { autoRestart: true })
     let settled = null
     for (let i = 0; i < 50 && settled === null; i += 1) {
       await new Promise((resolve) => setTimeout(resolve, 100))
@@ -670,8 +821,8 @@ test('upgrade:env 注入手动直跑环境,落定链保守分流零退出', asyn
     assert.equal(settled.runtimeEnv.kind, 'manual-start-likely', 'env 注入必须经 apply 检测进 status')
     assert.equal(settled.autoRestartScheduled, false, '手动直跑禁止调度自动重启')
     assert.deepEqual(exits, [], '手动直跑禁止任何宿主退出')
-    // stale 优先:版本未前进时不引导手动重启(重启无意义)
-    assert.equal(settled.upgrade.last.requiresManualRestart, undefined)
+    // 手动直跑标环境指引:命令成功即提示手动重启(指引不再被 stale 抑制)
+    assert.equal(settled.upgrade.last.requiresManualRestart, true, '手动直跑必须标手动重启指引')
   } finally {
     delete process.env.DSH_MAINTAIN_RUNTIME_ENV
   }
@@ -687,7 +838,7 @@ test('audit:触发/落定/拒绝各留一行结构化日志', async () => {
     const agents = { list: () => [{ id: 'a1', status: 'running' }] }
     const { ctx, routes } = makeCtx({ services: { agents }, appExit: () => {} })
     apply(ctx)
-    await post(routes, '/api/maintain/upgrade')
+    await post(routes, '/api/maintain/upgrade', { autoRestart: true })
     assert.equal(warns.some((text) => text.includes('audit endpoint=upgrade outcome=rejected reason=active-work')), true, '门控拒绝须留审计行')
     await post(routes, '/api/maintain/restart')
     assert.equal(warns.some((text) => text.includes('audit endpoint=restart outcome=rejected reason=active-work')), true, '重启门控拒绝须留审计行')
@@ -702,7 +853,7 @@ test('audit:触发/落定/拒绝各留一行结构化日志', async () => {
   console.warn = (text) => plainWarns.push(String(text))
   try {
     apply(plainCtx.ctx)
-    await post(plainCtx.routes, '/api/maintain/upgrade')
+    await post(plainCtx.routes, '/api/maintain/upgrade', { autoRestart: true })
     for (let i = 0; i < 50; i += 1) {
       await new Promise((resolve) => setTimeout(resolve, 100))
       const status = await get(plainCtx.routes, '/api/maintain/status').then((r) => r.payload).catch(() => null)

package/test/switch-guard.test.mjs

@@ -0,0 +1,45 @@
+// 开关样式守卫 BDD:状态选择器回退为裸 input 会静默隐藏 label 内其他 input,
+// 属无报错的 UI 损坏,故对源文本做静态断言锁死结构(usage-panel 同款守卫)
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import test from 'node:test'
+import assert from 'node:assert/strict'
+
+const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..')
+const source = readFileSync(join(PKG_ROOT, 'src', 'client.js'), 'utf8')
+
+test('switch 隐藏规则以 input[type="checkbox"] 精确匹配', () => {
+  assert.match(source, /\.dm-switch input\[type="checkbox"\] \{ position:absolute/)
+})
+
+test('switch 状态选择器禁止裸 input 锚定(防误伤 label 内其他 input)', () => {
+  const bare = source.match(/\.dm-switch input:(?!\[type)[a-z-]+/g)
+  assert.equal(bare, null, `裸 input 状态选择器: ${bare}`)
+})
+
+test('switch 文字标签的视觉提前依赖 order 规则,删除即回退到 track 右侧', () => {
+  assert.match(source, /\.dm-switch \.dm-row__label \{ order:-1/)
+})
+
+test('checkbox 仅允许出现在 Switch 组件内,禁止裸 checkbox 直出', () => {
+  const occurrences = [...source.matchAll(/type: 'checkbox'/g)].map((match) => match.index)
+  assert.equal(occurrences.length, 1, `checkbox 字面量出现 ${occurrences.length} 次`)
+  const factoryStart = source.indexOf('function Switch(')
+  const factoryEnd = source.indexOf('dm-switch__thumb', factoryStart)
+  assert.ok(occurrences[0] > factoryStart && occurrences[0] < factoryEnd, 'checkbox 字面量不在 Switch 组件内')
+})
+
+test('Switch 产出顺序为 input 在前 track 在后', () => {
+  const factory = source.slice(source.indexOf('function Switch('))
+  assert.ok(factory.indexOf("h('input'") < factory.indexOf('dm-switch__track'), '组件内 input 必须先于 track')
+})
+
+test('Switch 的 input 与 track 必须紧邻(状态选择器为紧邻组合器,中间插元素即视觉失效)', () => {
+  const factory = source.slice(source.indexOf('function Switch('))
+  const inputAt = factory.indexOf("h('input'")
+  const trackAt = factory.indexOf("h('span', { className: 'dm-switch__track'")
+  assert.ok(inputAt >= 0 && trackAt > inputAt, '前置:input 先于 track')
+  const between = factory.slice(inputAt + 1, trackAt)
+  assert.equal((between.match(/\bh\('/g) || []).length, 0, 'input 与 track 之间不得插入其他元素')
+})

package/test/upgrade.test.mjs

@@ -219,19 +219,29 @@ test('重试:假命令真实进程 文件锁失败后重试成功', async () =>
   }
 })
 
-test('自动重启:四条件守卫(成功/非 stale/非手动直跑/appExit 可用)', () => {
-  // 成功+托管(含 unknown)→ 调度
-  assert.deepEqual(judgeAutoRestart({ ok: true, stale: false, runtimeKind: RUNTIME_KINDS.UNKNOWN, hasExit: true }), { schedule: true, requiresManualRestart: false })
-  assert.deepEqual(judgeAutoRestart({ ok: true, stale: false, runtimeKind: RUNTIME_KINDS.DECLARED_MANAGED, hasExit: true }), { schedule: true, requiresManualRestart: false })
-  assert.deepEqual(judgeAutoRestart({ ok: true, stale: false, runtimeKind: RUNTIME_KINDS.PM2, hasExit: true }), { schedule: true, requiresManualRestart: false })
+test('自动重启:四条件守卫(成功/非手动直跑/enabled/appExit 可用)', () => {
+  // 成功+托管(含 unknown)+enabled=true → 调度
+  assert.deepEqual(judgeAutoRestart({ ok: true, runtimeKind: RUNTIME_KINDS.UNKNOWN, hasExit: true, enabled: true }), { schedule: true, requiresManualRestart: false })
+  assert.deepEqual(judgeAutoRestart({ ok: true, runtimeKind: RUNTIME_KINDS.DECLARED_MANAGED, hasExit: true, enabled: true }), { schedule: true, requiresManualRestart: false })
+  assert.deepEqual(judgeAutoRestart({ ok: true, runtimeKind: RUNTIME_KINDS.PM2, hasExit: true, enabled: true }), { schedule: true, requiresManualRestart: false })
   // 失败不调度
-  assert.deepEqual(judgeAutoRestart({ ok: false, stale: false, runtimeKind: RUNTIME_KINDS.UNKNOWN, hasExit: true }), { schedule: false, requiresManualRestart: false })
-  // stale 不调度
-  assert.deepEqual(judgeAutoRestart({ ok: true, stale: true, runtimeKind: RUNTIME_KINDS.UNKNOWN, hasExit: true }), { schedule: false, requiresManualRestart: false })
+  assert.deepEqual(judgeAutoRestart({ ok: false, runtimeKind: RUNTIME_KINDS.UNKNOWN, hasExit: true, enabled: true }), { schedule: false, requiresManualRestart: false })
   // 手动直跑 → 手动指引,不调度
-  assert.deepEqual(judgeAutoRestart({ ok: true, stale: false, runtimeKind: RUNTIME_KINDS.MANUAL_START, hasExit: true }), { schedule: false, requiresManualRestart: true })
+  assert.deepEqual(judgeAutoRestart({ ok: true, runtimeKind: RUNTIME_KINDS.MANUAL_START, hasExit: true, enabled: true }), { schedule: false, requiresManualRestart: true })
   // appExit 缺失不调度
-  assert.deepEqual(judgeAutoRestart({ ok: true, stale: false, runtimeKind: RUNTIME_KINDS.UNKNOWN, hasExit: false }), { schedule: false, requiresManualRestart: false })
+  assert.deepEqual(judgeAutoRestart({ ok: true, runtimeKind: RUNTIME_KINDS.UNKNOWN, hasExit: false, enabled: true }), { schedule: false, requiresManualRestart: false })
   // 手动直跑与 appExit 缺失并存 → 仍以手动指引标记(指引面板,与退出能力无关)
-  assert.deepEqual(judgeAutoRestart({ ok: true, stale: false, runtimeKind: RUNTIME_KINDS.MANUAL_START, hasExit: false }), { schedule: false, requiresManualRestart: true })
+  assert.deepEqual(judgeAutoRestart({ ok: true, runtimeKind: RUNTIME_KINDS.MANUAL_START, hasExit: false, enabled: true }), { schedule: false, requiresManualRestart: true })
+})
+
+test('自动重启:enabled 严格 boolean,仅 true 调度', () => {
+  // 显式 false:托管(含 unknown)不调度、不标手动指引
+  assert.deepEqual(judgeAutoRestart({ ok: true, runtimeKind: RUNTIME_KINDS.UNKNOWN, hasExit: true, enabled: false }), { schedule: false, requiresManualRestart: false })
+  assert.deepEqual(judgeAutoRestart({ ok: true, runtimeKind: RUNTIME_KINDS.DECLARED_MANAGED, hasExit: true, enabled: false }), { schedule: false, requiresManualRestart: false })
+  // 手动直跑指引是环境约束事实,不受勾选影响
+  assert.deepEqual(judgeAutoRestart({ ok: true, runtimeKind: RUNTIME_KINDS.MANUAL_START, hasExit: true, enabled: false }), { schedule: false, requiresManualRestart: true })
+  // 非 true 一律不调度:调用点经升级路由严格 boolean 校验,此处锁定纯函数自身契约
+  assert.deepEqual(judgeAutoRestart({ ok: true, runtimeKind: RUNTIME_KINDS.UNKNOWN, hasExit: true, enabled: undefined }), { schedule: false, requiresManualRestart: false })
+  assert.deepEqual(judgeAutoRestart({ ok: true, runtimeKind: RUNTIME_KINDS.UNKNOWN, hasExit: true, enabled: null }), { schedule: false, requiresManualRestart: false })
+  assert.deepEqual(judgeAutoRestart({ ok: true, runtimeKind: RUNTIME_KINDS.UNKNOWN, hasExit: true, enabled: 'true' }), { schedule: false, requiresManualRestart: false })
 })