@mzzsfy/dsh-maintain 0.5.3 → 0.6.0

package/src/index.js

@@ -12,13 +12,20 @@ import {
   TARGET_PACKAGE,
   TAG_PLACEHOLDER,
   buildUpgradeCommand,
+  classifyUpgradeFailure,
   fetchDistTags,
   isValidChannelName,
   isValidRegistryBase,
+  isVersionPendingRestart,
+  judgeUpgradeFreshness,
   judgeVersion,
   resolveHostVersion,
+  UPGRADE_FAIL_FILE_LOCKED,
+  UPGRADE_FAIL_TRANSIENT_NETWORK,
+  VERDICT_UP_TO_DATE,
 } from './core.mjs'
 import { runUpgrade } from './upgrade.mjs'
+import { detectRuntimeEnv, RUNTIME_KINDS } from './runtime.mjs'
 
 export const name = 'dsh-maintain'
 
@@ -34,11 +41,177 @@ 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 提示文案对拍
 export const TICK_MS = 60 * 1000
 // 轮询间隔上界:超大值会让到期时间戳溢出为 Infinity,轮询静默失效
 export const POLL_INTERVAL_MAX_SEC = 30 * 24 * 60 * 60
 
+// 升级尝试次数上限(含首次):npm 文件锁重试收益递减,收敛防长期占锁;导出仅供测试与 parity 对拍
+export const UPGRADE_MAX_ATTEMPTS = 3
+// 可重试失败的退避序列,按重试序号取值,越界取末位;导出仅供测试与 parity 对拍
+export const UPGRADE_RETRY_BACKOFF_MS = Object.freeze({
+  [UPGRADE_FAIL_FILE_LOCKED]: Object.freeze([5 * 1000, 15 * 1000]),
+  [UPGRADE_FAIL_TRANSIENT_NETWORK]: Object.freeze([3 * 1000, 9 * 1000]),
+})
+
+// 退避序列缺失返回 null,由调用方判不可重试:宁可不重试,不可零间隔轰击上游
+function upgradeRetryBackoffMs(backoff, kind, retryIndex) {
+  const seq = backoff[kind]
+  if (!seq || seq.length === 0) return null
+  return seq[Math.min(retryIndex, seq.length - 1)]
+}
+
+// 日志单行化:拼入 console.warn 的动态串不得携带换行,防日志结构被打散
+const singleLine = (text) => String(text ?? '').replace(/[\r\n]+/g, ' ')
+
+// 审计日志:升级/重启的触发、落定、拒绝各一行结构化输出,不引日志框架
+const audit = (endpoint, outcome, extra) => {
+  console.warn('[dsh-maintain] audit endpoint=' + endpoint + ' outcome=' + outcome + (extra ? ' ' + extra : ''))
+}
+
+// 活跃工作检测:agents/jobs/terminals 全软依赖方法面守卫,缺失或异常即降级放行(fail-open,
+// 不因安全网缺失死锁重启)。terminals 主路径逐 agent 的 realm 作用域解析(PTY 注册表随
+// agent 挂载且 isolate,共享根作用域因 realm 隔离恒缺,仅兜底);sessions 不作活跃指标;
+// 禁止顶层 inject(阻塞装载)。导出仅供测试
+// 降级留痕按服务键进程首见一次:status 每拍重检,不限频会刷屏
+const degradedWarned = new Set()
+
+export function collectActiveWork(ctx) {
+  const counts = { agents: 0, jobs: 0, terminals: 0 }
+  let detectionAvailable = true
+  const degrade = (key, detail) => {
+    detectionAvailable = false
+    if (degradedWarned.has(key)) return
+    degradedWarned.add(key)
+    console.warn('[dsh-maintain] 活跃工作检测降级,门控放行(' + key + '): ' + singleLine(detail))
+  }
+
+  let agentList = []
+  try {
+    const agents = ctx.get('agents')
+    if (!agents || typeof agents.list !== 'function') throw new Error('agents 服务方法面不可用')
+    const rows = agents.list()
+    agentList = Array.isArray(rows) ? rows : []
+    counts.agents = agentList.filter((agent) => agent && agent.status === 'running').length
+  } catch (error) {
+    degrade('agents', error && error.message ? error.message : String(error))
+  }
+
+  try {
+    const jobs = ctx.get('jobs')
+    if (!jobs || typeof jobs.list !== 'function') throw new Error('jobs 服务方法面不可用')
+    const seen = new Set()
+    for (const caller of [undefined, ...agentList]) {
+      const rows = jobs.list(caller)
+      for (const job of Array.isArray(rows) ? rows : []) {
+        const key = String(job && job.id)
+        if (seen.has(key)) continue
+        seen.add(key)
+        // stopping 必须计活:kill 置 stopping 后未落定,进程仍在
+        if (job && (job.status === 'running' || job.status === 'stopping')) counts.jobs += 1
+      }
+    }
+  } catch (error) {
+    degrade('jobs', error && error.message ? error.message : String(error))
+  }
+
+  try {
+    const seen = new Set()
+    let sawTerminalsService = false
+    const scan = (terminals, owner) => {
+      if (!terminals || typeof terminals.list !== 'function') return
+      sawTerminalsService = true
+      const rows = terminals.list(owner)
+      for (const terminal of Array.isArray(rows) ? rows : []) {
+        const key = String(terminal && terminal.sessionId)
+        if (seen.has(key)) continue
+        seen.add(key)
+        if (terminal && terminal.status && terminal.status.kind === 'running') counts.terminals += 1
+      }
+    }
+    for (const agent of agentList) {
+      try {
+        const agentCtx = agent && agent.ctx
+        if (agentCtx && typeof agentCtx.get === 'function') scan(agentCtx.get('terminals'), agent)
+      } catch (error) {
+        degrade('terminals', 'realm 探测异常: ' + (error && error.message ? error.message : String(error)))
+      }
+    }
+    try {
+      scan(ctx.get('terminals'), undefined)
+    } catch (error) {
+      degrade('terminals', '根探测异常: ' + (error && error.message ? error.message : String(error)))
+    }
+    if (!sawTerminalsService) degrade('terminals', 'terminals 服务面不可用')
+  } catch (error) {
+    degrade('terminals', error && error.message ? error.message : String(error))
+  }
+
+  return {
+    agents: counts.agents,
+    jobs: counts.jobs,
+    terminals: counts.terminals,
+    total: counts.agents + counts.jobs + counts.terminals,
+    detectionAvailable,
+  }
+}
+
+const sleepMs = (ms) => new Promise((resolve) => { setTimeout(resolve, ms) })
+
+// 升级尝试循环:单次执行语义与超时不变,失败经分类,可重试类按退避重试,
+// 直至成功/不可重试/次数上限;尾流只在落定结果上,attempts 条目只留判定字段。
+// runImpl/sleepImpl/backoff 注入仅供测试,默认真实执行器、定时睡眠与导出退避表
+export async function runUpgradeWithRetry({ command, timeoutMs = UPGRADE_TIMEOUT_MS, maxAttempts = UPGRADE_MAX_ATTEMPTS, backoff = UPGRADE_RETRY_BACKOFF_MS, runImpl = runUpgrade, sleepImpl = sleepMs, onAttemptStart }) {
+  const attempts = []
+  for (let index = 0; index < maxAttempts; index += 1) {
+    if (index > 0 && typeof onAttemptStart === 'function') onAttemptStart()
+    const startedAt = Date.now()
+    let result = null
+    let thrownMessage = null
+    try {
+      result = await runImpl({ command, timeoutMs })
+    } catch (error) {
+      thrownMessage = error && error.message ? error.message : String(error)
+    }
+    if (thrownMessage !== null) {
+      attempts.push({ startedAt, finishedAt: Date.now(), ok: false, code: null, timedOut: false, kind: null })
+      return { attempts, ok: false, kind: null, stillRunning: false, stdoutTail: '', stderrTail: '', error: thrownMessage }
+    }
+    const failure = result.ok ? null : classifyUpgradeFailure(result)
+    attempts.push({
+      startedAt,
+      finishedAt: Date.now(),
+      ok: result.ok === true,
+      code: typeof result.code === 'number' ? result.code : null,
+      timedOut: result.timedOut === true,
+      kind: failure === null ? null : failure.kind,
+    })
+    const settle = { attempts, ok: result.ok === true, kind: failure === null ? null : failure.kind, stillRunning: result.stillRunning === true, stdoutTail: result.stdoutTail ?? '', stderrTail: result.stderrTail ?? '', error: null }
+    if (result.ok) return settle
+    if (failure.retryable !== true || index >= maxAttempts - 1) return settle
+    const backoffMs = upgradeRetryBackoffMs(backoff, failure.kind, index)
+    if (backoffMs === null) {
+      console.warn('[dsh-maintain] 可重试分类缺少退避序列,按不可重试落定: kind=' + singleLine(failure.kind))
+      return settle
+    }
+    await sleepImpl(backoffMs)
+  }
+  return { attempts, ok: false, kind: null, stillRunning: false, stdoutTail: '', stderrTail: '', error: null }
+}
+
+// 升级后自动重启守卫:四条件缺一不可——成功、非 stale、非手动直跑、appExit 可用。
+// 手动直跑(双 TTY)进程退出后无人拉起,只标 requiresManualRestart 交面板指引
+export function judgeAutoRestart({ ok, stale, runtimeKind, hasExit }) {
+  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 (hasExit !== true) return { schedule: false, requiresManualRestart: false }
+  return { schedule: true, requiresManualRestart: false }
+}
+
 // 浏览器半区调用的 API 路径清单:client.js 同名常量与之对拍(parity),防单侧改路径生产 404
 export const API_PATHS = Object.freeze({
   STATUS: '/api/maintain/status',
@@ -167,15 +340,6 @@ function readSettings(ctx) {
   }
 }
 
-async function resolveCurrentHostVersion() {
-  return resolveHostVersion({
-    execPath: process.execPath,
-    platform: process.platform,
-    readFileImpl: readFile,
-    resolveImpl: undefined,
-  })
-}
-
 /** @param {import('@deepseek-ai/cordis').Context} ctx */
 export function apply(ctx) {
   // 启动器在挂载前提供 appExit(有界退出,5 秒兜底强制);缺失时重启能力关闭
@@ -189,12 +353,44 @@ export function apply(ctx) {
     console.warn('[dsh-maintain] 检测到未过期的升级锁(可能存在残留升级子进程),升级端点保持拒绝直至锁过期: ' + UPGRADE_LOCK_PATH)
   }
 
-  // 内存快照:仅存当前态,进程重启后从启动检查重新开始(设计约束:不持久化)
-  const snapshot = { currentVersion: null, tags: null, checkedAt: null, error: null }
+  // 运行版本探测:服务面可注入受控实现(测试面),缺省走真实盘读;
+  // 约定恒 resolve 不 reject,真实实现全失败回 null,注入侧经 then 同步抛错同折进 rejection
+  function resolveCurrentHostVersion() {
+    const probe = ctx.get('hostVersionProbe')
+    if (typeof probe === 'function') return Promise.resolve().then(probe)
+    return resolveHostVersion({
+      execPath: process.execPath,
+      platform: process.platform,
+      readFileImpl: readFile,
+      resolveImpl: undefined,
+    })
+  }
+
+  // 内存快照:仅存当前态,进程重启后从启动检查重新开始(设计约束:不持久化)。
+  // installedVersion 为磁盘实时版本(每次检查读取),与运行版本区分
+  const snapshot = { installedVersion: null, tags: null, checkedAt: null, error: null }
+  // 运行版本:apply 时读一次缓存,即宿主启动时的版本;verdict 以它判定。
+  // resolveCurrentHostVersion 约定恒 resolve 不 reject,此处 catch 锁定该约束,
+  // 防读盘异常以未处理拒绝形式逃逸
+  let runningVersion = null
+  const runningVersionReady = resolveCurrentHostVersion()
+    .then((version) => { runningVersion = version })
+    .catch(() => {})
+
+  // 运行环境:apply 时一次检测;探测异步,以 ready 链收口,异常回退 unknown(维持自动重启)
+  let runtimeEnv = { kind: RUNTIME_KINDS.UNKNOWN, declared: false }
+  const runtimeEnvReady = detectRuntimeEnv({
+    env: process.env,
+    platform: process.platform,
+    isTTY: { stdin: process.stdin.isTTY === true, stdout: process.stdout.isTTY === true },
+  })
+    .then((env) => { runtimeEnv = env })
+    .catch(() => {})
   let upgrade = { running: false, last: null }
   let checkInFlight = null
   let nextDueAt = null
   let restartScheduled = false
+  let autoRestartScheduled = false
 
   function runCheck() {
     if (checkInFlight) return checkInFlight
@@ -207,7 +403,7 @@ export function apply(ctx) {
         // registry 不可达:保留上次 tags,仅记录错误
         snapshot.error = error && error.message ? error.message : String(error)
       }
-      snapshot.currentVersion = await resolveCurrentHostVersion()
+      snapshot.installedVersion = await resolveCurrentHostVersion()
       snapshot.checkedAt = Date.now()
       return snapshot
     })()
@@ -245,9 +441,16 @@ export function apply(ctx) {
     pollRunning = true
   })
 
-  function currentStatus() {
+  function judgeNow() {
+    // verdict 以运行版本判定:用户关心"跑的是不是最新";已装版本供升级复读校验
+    return judgeVersion({ currentVersion: runningVersion, tags: snapshot.tags, channel: readSettings(ctx).channel })
+  }
+
+  async function currentStatus() {
+    // 等运行版本首读与运行环境检测落定:apply 即发起,此处仅吸收启动窗口的微小延迟
+    await Promise.all([runningVersionReady, runtimeEnvReady])
     const config = readSettings(ctx)
-    const judged = judgeVersion({ currentVersion: snapshot.currentVersion, tags: snapshot.tags, channel: config.channel })
+    const judged = judgeNow()
     // running 即视为持锁:省一次盘读,且窗口期语义与 upgrade 路由的门闩一致
     const lock = upgrade.running === true ? { startedAt: Date.now() } : readUpgradeLock()
     return {
@@ -256,7 +459,9 @@ export function apply(ctx) {
       bootAt: BOOT_AT,
       pollRunning,
       upgradeLockHeld: lock !== null && !upgradeLockStale(lock),
-      currentVersion: snapshot.currentVersion,
+      runningVersion,
+      installedVersion: snapshot.installedVersion,
+      restartPending: isVersionPendingRestart({ runningVersion, installedVersion: snapshot.installedVersion }),
       channel: config.channel,
       upgradeTemplate: config.upgradeCommandTemplate,
       pollIntervalSec: config.pollIntervalSec,
@@ -268,6 +473,9 @@ export function apply(ctx) {
       checkedAt: snapshot.checkedAt,
       checkError: snapshot.error,
       upgrade,
+      runtimeEnv,
+      autoRestartScheduled,
+      activeWork: collectActiveWork(ctx),
       canRestart: typeof exit === 'function',
     }
   }
@@ -276,40 +484,114 @@ export function apply(ctx) {
     const config = readSettings(ctx)
     // 模板校验同步失败即同步 throw,由调用方 try/catch 转 400,不走异步通道
     const command = buildUpgradeCommand({ template: config.upgradeCommandTemplate, tag: config.channel })
-    const last = { command, startedAt: Date.now(), ok: false, finishedAt: null, timedOut: false, stillRunning: false, code: null, stdoutTail: '', stderrTail: '', error: null }
+    const last = {
+      command,
+      startedAt: Date.now(),
+      ok: false,
+      finishedAt: null,
+      timedOut: false,
+      stillRunning: false,
+      code: null,
+      stdoutTail: '',
+      stderrTail: '',
+      error: null,
+      kind: null,
+      attempts: [],
+      previousVersion: null,
+      installedVersion: null,
+      stale: null,
+      reason: null,
+    }
     // running 即串行化门闩:路由检查与本处置位之间无 await,单线程下无竞态窗口
     upgrade = { running: true, last }
+    writeUpgradeLock(last.startedAt)
+    audit('upgrade', 'triggered', 'command=' + singleLine(command))
+    void performUpgrade(command, last, config.channel)
+  }
+
+  // 升级锁文件只在此写入:首次与每次重试覆写,startedAt 取当前尝试开始时刻,
+  // 过期阈值覆盖单次尝试的完整时长(超时 + 强杀宽限)
+  function writeUpgradeLock(startedAt) {
     try {
-      writeFileSync(UPGRADE_LOCK_PATH, JSON.stringify({ startedAt: last.startedAt, pid: process.pid }), 'utf8')
+      writeFileSync(UPGRADE_LOCK_PATH, JSON.stringify({ startedAt, pid: process.pid }), 'utf8')
     } catch { /* 锁不可写仅损失跨进程防护,内存门闩仍生效 */ }
-    console.warn('[dsh-maintain] 升级开始: ' + command)
-    runUpgrade({ command, timeoutMs: UPGRADE_TIMEOUT_MS })
-      .then((result) => {
-        upgrade = {
-          running: false,
-          last: { ...last, ok: result.ok, finishedAt: Date.now(), timedOut: result.timedOut, stillRunning: result.stillRunning === true, code: result.code, stdoutTail: result.stdoutTail, stderrTail: result.stderrTail },
-        }
+  }
+
+  // 自动重启与手动重启共用 restartScheduled 互斥:调度窗口内到达的升级被 409,
+  // 手动重启端点幂等;autoRestartScheduled 单独给 status/client 分流终态文案
+  function scheduleAutoRestart() {
+    restartScheduled = true
+    autoRestartScheduled = true
+    audit('restart', 'scheduled', 'reason=upgrade-ok delayMs=' + AUTO_RESTART_DELAY_MS)
+    setTimeout(() => exit(0), AUTO_RESTART_DELAY_MS)
+  }
+
+  async function performUpgrade(command, last, channel) {
+    try {
+      // 触发前快照磁盘版本,成功落定后复读对比,版本未前进或未达目标即标 stale
+      last.previousVersion = await resolveCurrentHostVersion()
+      const settle = await runUpgradeWithRetry({
+        command,
+        onAttemptStart: () => writeUpgradeLock(Date.now()),
       })
-      .catch((error) => {
-        upgrade = { running: false, last: { ...last, finishedAt: Date.now(), error: error && error.message ? error.message : String(error) } }
+      const final = settle.attempts[settle.attempts.length - 1] ?? null
+      Object.assign(last, {
+        attempts: settle.attempts,
+        ok: settle.ok,
+        kind: settle.kind,
+        error: settle.error,
+        finishedAt: Date.now(),
+        timedOut: final !== null ? final.timedOut : false,
+        stillRunning: settle.stillRunning,
+        code: final !== null ? final.code : null,
+        stdoutTail: settle.stdoutTail,
+        stderrTail: settle.stderrTail,
       })
-      .then(() => {
-        // stillRunning(强杀后进程树疑似仍在写全局目录)时保留锁文件,由过期机制收敛,
-        // 与"宿主死后幽灵锁"防线对称;正常落定即删
-        if (upgrade.last.stillRunning === true) {
-          console.warn('[dsh-maintain] 升级超时强杀且进程疑似仍存活,升级锁保留至过期: ' + UPGRADE_LOCK_PATH)
-        } else {
-          try {
-            rmSync(UPGRADE_LOCK_PATH, { force: true })
-          } catch (lockError) {
-            console.warn('[dsh-maintain] 升级锁删除失败(将由过期机制收敛): ' + (lockError?.message ?? lockError))
-          }
+      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 {
+      if (last.finishedAt === null) last.finishedAt = Date.now()
+      upgrade = { running: false, last }
+      // stillRunning(强杀后进程树疑似仍在写全局目录)时保留锁文件,由过期机制收敛,
+      // 与"宿主死后幽灵锁"防线对称;正常落定即删
+      if (last.stillRunning === true) {
+        console.warn('[dsh-maintain] 升级超时强杀且进程疑似仍存活,升级锁保留至过期: ' + UPGRADE_LOCK_PATH)
+      } else {
+        try {
+          rmSync(UPGRADE_LOCK_PATH, { force: true })
+        } catch (lockError) {
+          console.warn('[dsh-maintain] 升级锁删除失败(将由过期机制收敛): ' + (lockError?.message ?? lockError))
         }
-        console.warn('[dsh-maintain] 升级结束: ok=' + upgrade.last.ok + (upgrade.last.code !== null ? ' 退出码=' + upgrade.last.code : '') + (upgrade.last.error ? ' ' + upgrade.last.error : ''))
-      })
+      }
+      console.warn('[dsh-maintain] 升级结束: ok=' + last.ok + ' kind=' + singleLine(last.kind)
+        + (last.code !== null ? ' 退出码=' + last.code : '')
+        + (last.error ? ' ' + singleLine(last.error) : '')
+        + (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' })
+      if (decision.requiresManualRestart === true) last.requiresManualRestart = true
+      if (decision.schedule === true) {
+        // last 镜像调度标记:浮条终态文案按其分流(与 status.autoRestartScheduled 同值)
+        last.autoRestartScheduled = true
+        scheduleAutoRestart()
+      }
       // 升级结束后自动重新检查版本并重排轮询(命令可能改了本地版本)
-      .then(runCheck, runCheck)
-      .then(scheduleNext, scheduleNext)
+      runCheck().then(scheduleNext, scheduleNext)
+    }
   }
 
   const WRITE = { crossOrigin: true }
@@ -318,7 +600,7 @@ export function apply(ctx) {
     {
       path: API_PATHS.STATUS,
       handler: route('GET', {}, async (req, res) => {
-        sendJson(res, 200, currentStatus())
+        sendJson(res, 200, await currentStatus())
       }),
     },
     {
@@ -326,7 +608,7 @@ export function apply(ctx) {
       handler: route('POST', WRITE, async (req, res) => {
         await drainInFlightThenCheck()
         scheduleNext()
-        sendJson(res, 200, currentStatus())
+        sendJson(res, 200, await currentStatus())
       }),
     },
     {
@@ -355,7 +637,7 @@ export function apply(ctx) {
         await settings.update(NAMESPACE, { channel })
         // 切通道无需重查:dist-tags 与 channel 无关,白名单已用现有 snapshot 校验
         scheduleNext()
-        sendJson(res, 200, currentStatus())
+        sendJson(res, 200, await currentStatus())
       }),
     },
     {
@@ -373,7 +655,7 @@ export function apply(ctx) {
           return
         }
         await settings.update(NAMESPACE, { upgradeCommandTemplate: template })
-        sendJson(res, 200, currentStatus())
+        sendJson(res, 200, await currentStatus())
       }),
     },
     {
@@ -398,7 +680,7 @@ export function apply(ctx) {
         }
         await settings.update(NAMESPACE, { pollIntervalSec: seconds })
         scheduleNext()
-        sendJson(res, 200, currentStatus())
+        sendJson(res, 200, await currentStatus())
       }),
     },
     {
@@ -418,7 +700,7 @@ export function apply(ctx) {
         await settings.update(NAMESPACE, { registryBase: base })
         await drainInFlightThenCheck()
         scheduleNext()
-        sendJson(res, 200, currentStatus())
+        sendJson(res, 200, await currentStatus())
       }),
     },
     {
@@ -427,15 +709,36 @@ export function apply(ctx) {
         // 与重启调度双向互斥:restartScheduled 置位到 exit(0) 执行的窗口内触发升级,
         // detached 孤儿会与新宿主交错
         if (upgrade.running || restartScheduled) {
+          audit('upgrade', 'rejected', restartScheduled ? 'reason=restart-scheduled' : 'reason=running')
           sendJson(res, 409, { error: restartScheduled ? '重启已调度,禁止触发升级' : '升级进行中' })
           return
         }
         if (upgradeLockStale(readUpgradeLock()) === false) {
+          audit('upgrade', 'rejected', 'reason=lock')
           sendJson(res, 409, { error: '存在未过期的升级锁(可能有残留升级子进程),等待锁过期或删除 ' + UPGRADE_LOCK_PATH })
           return
         }
+        // 防降级:运行版本已达通道最新时拒绝(重装旧版即降级,对齐 no-newer-version);
+        // 信息不足(verdict unknown)放行,宽松不误拒
+        const judged = judgeNow()
+        if (judged.verdict === VERDICT_UP_TO_DATE) {
+          audit('upgrade', 'rejected', 'reason=up-to-date')
+          sendJson(res, 409, { error: '当前已是通道最新版,无需升级;重装请走命令行' })
+          return
+        }
+        // 活跃工作门控:升级不可越(agent 会话/job 在跑时强行升级会被中断)
+        const activeWork = collectActiveWork(ctx)
+        if (activeWork.total > 0) {
+          audit('upgrade', 'rejected', 'reason=active-work total=' + activeWork.total)
+          sendJson(res, 409, {
+            error: '存在活跃工作(共 ' + activeWork.total + ' 项:agents ' + activeWork.agents + '/jobs ' + activeWork.jobs + '/terminals ' + activeWork.terminals + '),升级会中断它们,请等待完成',
+            items: activeWork,
+            detectionAvailable: activeWork.detectionAvailable,
+          })
+          return
+        }
         triggerUpgrade()
-        sendJson(res, 200, currentStatus())
+        sendJson(res, 200, await currentStatus())
       }),
     },
     {
@@ -444,10 +747,12 @@ export function apply(ctx) {
         // 与升级门闩互斥:升级子进程经 detached+unref 存活于宿主死后,
         // 重启后新宿主门闩归零会放行第二次升级,双 npm install 并发写全局目录
         if (upgrade.running) {
+          audit('restart', 'rejected', 'reason=upgrade-running')
           sendJson(res, 409, { error: '升级进行中,禁止重启;等待升级完成后重试' })
           return
         }
         if (typeof exit !== 'function') {
+          audit('restart', 'rejected', 'reason=no-appExit')
           sendJson(res, 500, { error: '启动器未提供 appExit,无法重启' })
           return
         }
@@ -455,7 +760,23 @@ export function apply(ctx) {
           sendJson(res, 200, { ok: true, restarting: true })
           return
         }
+        // 活跃工作门控:重启可被 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)
+          sendJson(res, 409, {
+            error: '存在活跃工作(共 ' + activeWork.total + ' 项:agents ' + activeWork.agents + '/jobs ' + activeWork.jobs + '/terminals ' + activeWork.terminals + '),重启会中断它们;确认无误请带 force 重试',
+            items: activeWork,
+            detectionAvailable: activeWork.detectionAvailable,
+          })
+          return
+        }
         restartScheduled = true
+        audit('restart', 'triggered', requestBody.force === true ? 'forced=true' : 'forced=false')
         sendJson(res, 200, { ok: true, restarting: true })
         // 退出延迟与响应冲刷解耦:客户端在冲刷完成前断连会让 end 回调失效,绑定其上会使重启悬空;
         // 同步发出响应后延迟退出,延迟本身保证回执先于进程离场送达

package/src/runtime.mjs

@@ -0,0 +1,69 @@
+// 运行环境检测:判定宿主进程是否处于托管启动形态,决定升级后可否自动重启。
+// 纯函数,探测点经参数注入;顺序:env 显式覆盖 > 进程环境表 > POSIX 容器探测 > 双 TTY > unknown。
+import { stat, readFile } from 'node:fs/promises'
+
+export const RUNTIME_KINDS = Object.freeze({
+  DECLARED_MANAGED: 'declared-managed',
+  PM2: 'pm2',
+  SYSTEMD: 'systemd',
+  SUPERVISORD: 'supervisord',
+  KUBERNETES: 'kubernetes',
+  DOCKER: 'docker',
+  CONTAINER: 'container',
+  MANUAL_START: 'manual-start-likely',
+  UNKNOWN: 'unknown',
+})
+
+// 环境覆盖键:managed|manual,测试与用户显式纠偏用
+const RUNTIME_ENV_OVERRIDE = 'DSH_MAINTAIN_RUNTIME_ENV'
+const OVERRIDE_MANAGED = 'managed'
+const OVERRIDE_MANUAL = 'manual'
+
+// 各托管形态的特征环境变量表:命中任一即声明
+const MANAGED_ENV_KEYS = Object.freeze([
+  [RUNTIME_KINDS.PM2, Object.freeze(['pm_id', 'PM2_HOME', 'pm_uptime'])],
+  [RUNTIME_KINDS.SYSTEMD, Object.freeze(['INVOCATION_ID', 'JOURNAL_STREAM', 'NOTIFY_SOCKET'])],
+  [RUNTIME_KINDS.SUPERVISORD, Object.freeze(['SUPERVISOR_ENABLED', 'SUPERVISOR_PROCESS_NAME'])],
+  [RUNTIME_KINDS.KUBERNETES, Object.freeze(['KUBERNETES_SERVICE_HOST'])],
+])
+
+const DOCKERENV_PATH = '/.dockerenv'
+const CGROUP_PATH = '/proc/1/cgroup'
+// cgroup 归类:/docker/ 与 dockerenv 同为 docker;kubepods 即 k8s;其余容器运行时归 container
+const CGROUP_DOCKER_PATTERN = /\/docker\//
+const CGROUP_K8S_PATTERN = /kubepods/
+const CGROUP_CONTAINER_PATTERN = /containerd|lxc|podman/
+
+const fallbackExists = async (path) => {
+  try {
+    await stat(path)
+    return true
+  } catch {
+    return false
+  }
+}
+
+const fallbackRead = async (path) => readFile(path, 'utf8')
+
+export async function detectRuntimeEnv({ env, platform, isTTY, existsImpl = fallbackExists, readFileImpl = fallbackRead }) {
+  const override = env[RUNTIME_ENV_OVERRIDE]
+  if (override === OVERRIDE_MANAGED) return { kind: RUNTIME_KINDS.DECLARED_MANAGED, declared: true }
+  if (override === OVERRIDE_MANUAL) return { kind: RUNTIME_KINDS.MANUAL_START, declared: false }
+
+  for (const [kind, keys] of MANAGED_ENV_KEYS) {
+    if (keys.some((key) => env[key])) return { kind, declared: true }
+  }
+
+  if (platform !== 'win32') {
+    try {
+      if (await existsImpl(DOCKERENV_PATH)) return { kind: RUNTIME_KINDS.DOCKER, declared: true }
+      const cgroup = await readFileImpl(CGROUP_PATH)
+      if (CGROUP_DOCKER_PATTERN.test(cgroup)) return { kind: RUNTIME_KINDS.DOCKER, declared: true }
+      if (CGROUP_K8S_PATTERN.test(cgroup)) return { kind: RUNTIME_KINDS.KUBERNETES, declared: true }
+      if (CGROUP_CONTAINER_PATTERN.test(cgroup)) return { kind: RUNTIME_KINDS.CONTAINER, declared: true }
+    } catch { /* 探测失败按未声明继续 */ }
+  }
+
+  if (isTTY.stdin === true && isTTY.stdout === true) return { kind: RUNTIME_KINDS.MANUAL_START, declared: false }
+  return { kind: RUNTIME_KINDS.UNKNOWN, declared: false }
+}

package/src/upgrade.mjs

@@ -9,8 +9,9 @@ import { spawn } from 'node:child_process'
 
 const OUTPUT_TAIL_BYTES = 2000
 const SPAWN_ERROR_CODE = 127
-// 树终止后的宽限期:子进程树拒死(权限/管道悬挂)时强制收敛,防升级门闩永久卡死
-const KILL_GRACE_MS = 5 * 1000
+// 树终止后的宽限期:子进程树拒死(权限/管道悬挂)时强制收敛,防升级门闩永久卡死;
+// 导出仅供 parity 测试作观察窗口上界的构成项对拍
+export const KILL_GRACE_MS = 5 * 1000
 
 function collectTail(stream) {
   let text = ''