@mzzsfy/dsh-maintain 0.5.2 → 0.6.0

package/test/route.test.mjs

@@ -6,8 +6,8 @@ import { test } from 'node:test'
 import assert from 'node:assert/strict'
 import { EventEmitter } from 'node:events'
 
-import { apply, RESTART_DELAY_MS, UPGRADE_LOCK_PATH } from '../src/index.js'
-import { rmSync } from 'node:fs'
+import { apply, RESTART_DELAY_MS, UPGRADE_LOCK_PATH, collectActiveWork } from '../src/index.js'
+import { rmSync, readFileSync } from 'node:fs'
 
 // 锁文件是固定共享路径:测试进程中断可能残留幽灵锁毒化后续运行,用例前预热清理
 rmSync(UPGRADE_LOCK_PATH, { force: true })
@@ -15,21 +15,27 @@ rmSync(UPGRADE_LOCK_PATH, { force: true })
 // 全局 fetch 拦截:core.fetchDistTags 默认绑定全局 fetch,测试期返回与 dist-tags.test
 // 同形的流式响应(tags 就绪),防止启动检查/refresh 触发真实网络请求
 const MOCK_TAGS = { latest: '9.9.9', next: '10.0.0' }
-globalThis.fetch = async () => ({
-  ok: true,
-  status: 200,
-  body: {
-    getReader: () => {
-      const chunks = [new TextEncoder().encode(JSON.stringify(MOCK_TAGS))]
-      return {
-        read: async () => (chunks.length ? { done: false, value: chunks.shift() } : { done: true, value: undefined }),
-        cancel: async () => {},
-      }
+
+// 与文件顶部全局 fetch 拦截同形的流式响应体
+function tagsBody(tags) {
+  return {
+    ok: true,
+    status: 200,
+    body: {
+      getReader: () => {
+        const chunks = [new TextEncoder().encode(JSON.stringify(tags))]
+        return {
+          read: async () => (chunks.length ? { done: false, value: chunks.shift() } : { done: true, value: undefined }),
+          cancel: async () => {},
+        }
+      },
     },
-  },
-})
+  }
+}
+
+globalThis.fetch = async () => tagsBody(MOCK_TAGS)
 
-function makeCtx({ appExit, settingsStore, timerAvailable = true } = {}) {
+function makeCtx({ appExit, settingsStore, timerAvailable = true, services = {} } = {}) {
   const routes = new Map()
   let tick = null
   const store = settingsStore ?? {}
@@ -39,6 +45,7 @@ function makeCtx({ appExit, settingsStore, timerAvailable = true } = {}) {
     get(name) {
       if (name === 'appExit') return appExit
       if (name === 'settings') return settingsService
+      if (Object.prototype.hasOwnProperty.call(services, name)) return services[name]
       return undefined
     },
     // effect 桩:执行装配函数并捕获其返回的 disposer,供测试模拟 fiber 停用
@@ -91,12 +98,11 @@ function makeReq({ method = 'POST', body, headers = {} } = {}) {
   req.destroy = () => {
     req.destroyed = true
   }
-  if (body !== undefined) {
-    queueMicrotask(() => {
-      req.emit('data', Buffer.from(typeof body === 'string' ? body : JSON.stringify(body)))
-      req.emit('end')
-    })
-  }
+  // 无 body 也须发 end:路由侧读体(如 restart 的 force)对空体解析为空对象
+  queueMicrotask(() => {
+    if (body !== undefined) req.emit('data', Buffer.from(typeof body === 'string' ? body : JSON.stringify(body)))
+    req.emit('end')
+  })
   return req
 }
 
@@ -280,8 +286,63 @@ test('registry-base:非法 scheme 400;合法值持久化', async () => {
   assert.equal(store.registryBase, 'https://mirror.example')
 })
 
-test('upgrade:空白模板经 upgrade-template 路由拒绝', async () => {
-  // 默认模板是真实 npm install 命令,POST upgrade 的默认路径禁止在测试中触发;
+test('upgrade:运行版本已是通道最新 409 拒绝(防降级),unknown 放行', async () => {
+  const store = { upgradeCommandTemplate: 'node -e "process.exit(0)"' }
+  // 版本探测注入受控值:CI 无 dsh 本体,真实盘读回 null 会把 verdict 打成 unknown,
+  // 防降级门控(核心断言)在 CI 恒不触发
+  const { ctx, routes } = makeCtx({
+    settingsStore: store,
+    services: { hostVersionProbe: () => Promise.resolve('5.4.3') },
+  })
+  apply(ctx)
+  // 注入运行版本远低于假目标版本:verdict 应转 up-to-date,升级入口拒绝
+  const originalFetch = globalThis.fetch
+  globalThis.fetch = async () => tagsBody({ latest: '0.0.1', next: '0.0.2' })
+  try {
+    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')
+    assert.equal(denied.status, 409)
+    assert.match(denied.payload.error, /已是通道最新版/)
+    assert.equal(store.upgradeCommandTemplate, 'node -e "process.exit(0)"', '拒绝路径不得触发升级')
+  } finally {
+    globalThis.fetch = originalFetch
+  }
+})
+
+test('upgrade:verdict unknown 放行(tags 未就绪不得 409 误拒)', async () => {
+  const store = { upgradeCommandTemplate: 'node -e "process.exit(0)"' }
+  // fetch 在 apply 前替换:启动检查即失败,tags 保持 null,verdict 恒 unknown
+  const originalFetch = globalThis.fetch
+  globalThis.fetch = async () => { throw new Error('ECONNREFUSED') }
+  try {
+    const { ctx, routes } = makeCtx({ settingsStore: store })
+    apply(ctx)
+    let snapshot = null
+    for (let waited = 0; waited < 5000 && snapshot === null; waited += 25) {
+      const poll = await get(routes, '/api/maintain/status').then((r) => r.payload)
+      if (poll.checkedAt !== null) snapshot = poll
+      else await new Promise((resolve) => setTimeout(resolve, 25))
+    }
+    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')
+    assert.equal(allowed.status, 200, 'verdict unknown 必须放行,不得 409 误拒')
+    assert.equal(allowed.payload.upgrade.running, true)
+    // 等假命令落定:防残留升级锁毒化后续用例
+    for (let i = 0; i < 50; i += 1) {
+      await new Promise((resolve) => setTimeout(resolve, 100))
+      const s = await get(routes, '/api/maintain/status').then((r) => r.payload).catch(() => null)
+      if (s && s.upgrade && s.upgrade.running === false && s.upgrade.last !== null) break
+    }
+  } finally {
+    globalThis.fetch = originalFetch
+  }
+})
+
+test('upgrade:空白模板经 upgrade-template 路由拒绝', async () => {  // 默认模板是真实 npm install 命令,POST upgrade 的默认路径禁止在测试中触发;
   // 门闩语义由"真实挂起命令"用例覆盖,此处锁定保存侧空白拒绝
   const store = {}
   const { ctx, routes } = makeCtx({ settingsStore: store })
@@ -316,6 +377,49 @@ test('upgrade:真实挂起命令触达门闩,二次 409,结束后自动重查',
   assert.ok(settled.checkedAt !== null)
 })
 
+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)
+  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
+  }
+  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
+  }
+  // 观察窗口覆盖自动重启延迟:若误调度,延迟窗口内 exit 会被调用
+  await new Promise((resolve) => setTimeout(resolve, 200))
+  assert.deepEqual(exits, [], 'stale 时禁止调度任何宿主退出')
+})
+
 test('restart:升级进行中 409 拒绝且不调度退出', async () => {
   const store = { upgradeCommandTemplate: 'node -e "setTimeout(() => {}, 2000)"' }
   const exits = []
@@ -359,6 +463,29 @@ test('status:快照携带 bootAt 实例代际', async () => {
   assert.ok(Number.isFinite(status.payload.bootAt) && status.payload.bootAt > 0)
 })
 
+test('status:运行版本与已装版本双字段,verdict 以运行版本为准', async () => {
+  const { ctx, routes } = makeCtx()
+  apply(ctx)
+  // 等启动检查落定:installedVersion 由检查快照填充
+  let ready = null
+  for (let waited = 0; waited < 5000 && ready === null; waited += 25) {
+    const poll = await call(routes, '/api/maintain/status', makeReq({ method: 'GET' }))
+    if (poll.payload.checkedAt !== null) ready = poll.payload
+    else await new Promise((resolve) => setTimeout(resolve, 25))
+  }
+  assert.ok(ready, '启动检查 5 秒内未完成')
+  assert.ok('runningVersion' in ready, 'status 必须返回 runningVersion')
+  assert.ok('installedVersion' in ready, 'status 必须返回 installedVersion')
+  assert.equal(ready.currentVersion, undefined, '旧 currentVersion 字段移除,不保留兼容层')
+  // 静态磁盘下两读一致;磁盘领先运行版本(升级后未重启)才置 restartPending
+  assert.equal(ready.installedVersion, ready.runningVersion)
+  assert.equal(ready.restartPending, false)
+  // 运行版本与已装版本来源不同(apply 缓存 vs 检查快照):缺失时 verdict 未知
+  if (ready.runningVersion === null) {
+    assert.equal(ready.verdict, 'unknown')
+  }
+})
+
 test('poll-interval:超上界 400(秒转毫秒溢出防护)', async () => {
   const store = {}
   const { ctx, routes } = makeCtx({ settingsStore: store })
@@ -422,4 +549,168 @@ test('readBody 超限:路由归一 400', async () => {
   await done
   assert.equal(res.status, 400)
   assert.match(res.payload.error, /上限/)
+})
+
+// ---- 活跃工作门控(S10)----
+
+test('collectActiveWork:agents/jobs/terminals 计活与去重', () => {
+  const terminals = {
+    list: (owner) => owner && owner.id === 'a1'
+      ? [{ sessionId: 't1', status: { kind: 'running' } }, { sessionId: 't3', status: { kind: 'exited' } }]
+      : [{ sessionId: 't1', status: { kind: 'running' } }, { sessionId: 't2', status: { kind: 'running' } }],
+  }
+  const agentA = { id: 'a1', status: 'running', ctx: { get: (n) => (n === 'terminals' ? terminals : undefined) } }
+  const agentB = { id: 'a2', status: 'idle' }
+  const agents = { list: () => [agentA, agentB] }
+  const jobs = {
+    list: (caller) => caller === undefined
+      ? [{ id: 'j1', status: 'running' }]
+      : [{ id: 'j1', status: 'running' }, { id: 'j2', status: 'stopping' }, { id: 'j3', status: 'done' }],
+  }
+  const result = collectActiveWork({ get: (n) => (n === 'agents' ? agents : n === 'jobs' ? jobs : n === 'terminals' ? terminals : undefined) })
+  // agents:a1 running;a jobs:j1 双 caller 去重计一,j2 stopping 计活,j3 不计;terminals:t1 去重,t2 计,t3 非运行不计
+  assert.deepEqual({ agents: result.agents, jobs: result.jobs, terminals: result.terminals }, { agents: 1, jobs: 2, terminals: 2 })
+  assert.equal(result.total, 5)
+  assert.equal(result.detectionAvailable, true)
+})
+
+test('collectActiveWork:服务缺失或异常 fail-open 降级', () => {
+  const empty = collectActiveWork({ get: () => undefined })
+  assert.deepEqual([empty.agents, empty.jobs, empty.terminals], [0, 0, 0])
+  assert.equal(empty.detectionAvailable, false)
+  const throwing = { get: () => ({ list: () => { throw new Error('boom') } }) }
+  const degraded = collectActiveWork(throwing)
+  assert.equal(degraded.total, 0)
+  assert.equal(degraded.detectionAvailable, false)
+  // 根作用域 terminals 缺失但 agent realm 有,不算降级(realm 隔离常态)
+  const agent = { id: 'a1', status: 'idle', ctx: { get: (n) => (n === 'terminals' ? { list: () => [{ sessionId: 't1', status: { kind: 'running' } }] } : undefined) } }
+  const realmOnly = collectActiveWork({ get: (n) => (n === 'agents' ? { list: () => [agent] } : n === 'jobs' ? { list: () => [] } : undefined) })
+  assert.equal(realmOnly.terminals, 1)
+  assert.equal(realmOnly.detectionAvailable, true)
+})
+
+test('upgrade:存在活跃工作 409 拒绝,不可越', async () => {
+  const store = { upgradeCommandTemplate: 'node -e "process.exit(0)"' }
+  const agents = { list: () => [{ id: 'a1', status: 'running' }] }
+  const jobs = { list: () => [] }
+  const terminals = { list: () => [] }
+  const { ctx, routes } = makeCtx({ settingsStore: store, services: { agents, jobs, terminals } })
+  apply(ctx)
+  const denied = await post(routes, '/api/maintain/upgrade')
+  assert.equal(denied.status, 409)
+  assert.match(denied.payload.error, /活跃工作/)
+  assert.equal(denied.payload.items.agents, 1)
+  assert.equal(denied.payload.detectionAvailable, true)
+  const status = await get(routes, '/api/maintain/status').then((r) => r.payload)
+  assert.equal(status.upgrade.running, false, '拒绝路径不得触发升级')
+})
+
+test('restart:活跃工作 409,force 越过', async (t) => {
+  t.mock.timers.enable({ apis: ['setTimeout'] })
+  const exits = []
+  const agents = { list: () => [{ id: 'a1', status: 'running' }] }
+  const jobs = { list: () => [] }
+  const { ctx, routes } = makeCtx({ appExit: (code) => exits.push(code), services: { agents, jobs } })
+  apply(ctx)
+  const denied = await post(routes, '/api/maintain/restart')
+  assert.equal(denied.status, 409)
+  assert.match(denied.payload.error, /活跃工作/)
+  assert.deepEqual(exits, [])
+  const forced = await post(routes, '/api/maintain/restart', { force: true })
+  assert.equal(forced.status, 200)
+  t.mock.timers.tick(RESTART_DELAY_MS + 1)
+  assert.deepEqual(exits, [0], 'force 越过后必须正常调度退出')
+})
+
+test('status:activeWork 概要进快照,服务缺失标 detectionAvailable=false', async () => {
+  const { ctx, routes } = makeCtx()
+  apply(ctx)
+  const status = await get(routes, '/api/maintain/status').then((r) => r.payload)
+  assert.equal(status.activeWork.total, 0)
+  assert.equal(status.activeWork.detectionAvailable, false)
+})
+
+// ---- 批 2 审查建议落地 ----
+
+test('restart:null 体按空体处理,内部形态不泄漏', async (t) => {
+  t.mock.timers.enable({ apis: ['setTimeout'] })
+  const exits = []
+  const { ctx, routes } = makeCtx({ appExit: (code) => exits.push(code) })
+  apply(ctx)
+  const ok = await post(routes, '/api/maintain/restart', 'null')
+  assert.equal(ok.status, 200, 'null 体须按空体处理,不得以内部错误形态 400/500 泄漏')
+  t.mock.timers.tick(RESTART_DELAY_MS + 1)
+  assert.deepEqual(exits, [0], 'null 体等价空体:正常调度退出')
+})
+
+test('自动重启接线:落定链消费运行环境并分流调度与手动指引(源码形态锁定)', () => {
+  const source = readFileSync(new URL('../src/index.js', import.meta.url), 'utf8')
+  const settle = source.match(/const decision = judgeAutoRestart\(\{([\s\S]*?)\}\)/)
+  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')
+})
+
+test('upgrade:env 注入手动直跑环境,落定链保守分流零退出', async () => {
+  process.env.DSH_MAINTAIN_RUNTIME_ENV = 'manual'
+  try {
+    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')
+    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
+    }
+    assert.ok(settled, '升级应在假命令退出后落定')
+    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)
+  } finally {
+    delete process.env.DSH_MAINTAIN_RUNTIME_ENV
+  }
+})
+
+// ---- 审计日志(S12)----
+
+test('audit:触发/落定/拒绝各留一行结构化日志', async () => {
+  const warns = []
+  const originalWarn = console.warn
+  console.warn = (text) => warns.push(String(text))
+  try {
+    const agents = { list: () => [{ id: 'a1', status: 'running' }] }
+    const { ctx, routes } = makeCtx({ services: { agents }, appExit: () => {} })
+    apply(ctx)
+    await post(routes, '/api/maintain/upgrade')
+    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, '重启门控拒绝须留审计行')
+    await post(routes, '/api/maintain/restart', { force: true })
+    assert.equal(warns.some((text) => /audit endpoint=restart outcome=triggered\b/.test(text) && text.includes('forced=true')), true, 'force 触发须留审计行')
+  } finally {
+    console.warn = originalWarn
+  }
+  // 升级触发与落定:假命令真实进程,落定行带 durationMs 与 code
+  const plainWarns = []
+  const plainCtx = makeCtx({ settingsStore: { upgradeCommandTemplate: 'node -e "process.exit(0)"' }, appExit: () => {} })
+  console.warn = (text) => plainWarns.push(String(text))
+  try {
+    apply(plainCtx.ctx)
+    await post(plainCtx.routes, '/api/maintain/upgrade')
+    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)
+      if (status && status.upgrade && status.upgrade.running === false && status.upgrade.last !== null) break
+    }
+  } finally {
+    console.warn = originalWarn
+  }
+  assert.equal(plainWarns.some((text) => /audit endpoint=upgrade outcome=triggered/.test(text)), true, '升级触发须留审计行')
+  assert.equal(plainWarns.some((text) => /audit endpoint=upgrade outcome=(ok|failed) durationMs=[0-9]+ code=/.test(text)), true, '升级落定须留审计行')
 })

package/test/runtime.test.mjs

@@ -0,0 +1,67 @@
+import assert from 'node:assert/strict'
+import { test } from 'node:test'
+import { detectRuntimeEnv, RUNTIME_KINDS } from '../src/runtime.mjs'
+
+const POSIX = 'linux'
+const WIN32 = 'win32'
+const BOTH_TTY = { stdin: true, stdout: true }
+const NO_TTY = { stdin: false, stdout: false }
+const noProbes = { existsImpl: async () => false, readFileImpl: async () => { throw new Error('ENOENT') } }
+
+test('环境检测:env 覆盖最高优先', async () => {
+  const managed = await detectRuntimeEnv({ env: { DSH_MAINTAIN_RUNTIME_ENV: 'managed', pm_id: '0' }, platform: POSIX, isTTY: BOTH_TTY, ...noProbes })
+  assert.deepEqual(managed, { kind: RUNTIME_KINDS.DECLARED_MANAGED, declared: true })
+  const manual = await detectRuntimeEnv({ env: { DSH_MAINTAIN_RUNTIME_ENV: 'manual', pm_id: '0' }, platform: POSIX, isTTY: NO_TTY, ...noProbes })
+  assert.deepEqual(manual, { kind: RUNTIME_KINDS.MANUAL_START, declared: false })
+  // 非法覆盖值不生效,继续走常规判定
+  const bogus = await detectRuntimeEnv({ env: { DSH_MAINTAIN_RUNTIME_ENV: 'sideways' }, platform: POSIX, isTTY: NO_TTY, ...noProbes })
+  assert.deepEqual(bogus, { kind: RUNTIME_KINDS.UNKNOWN, declared: false })
+})
+
+test('环境检测:env 表命中各托管形态', async () => {
+  const table = [
+    [{ pm_id: '0' }, RUNTIME_KINDS.PM2],
+    [{ PM2_HOME: 'C:/pm2' }, RUNTIME_KINDS.PM2],
+    [{ pm_uptime: '123' }, RUNTIME_KINDS.PM2],
+    [{ INVOCATION_ID: 'x' }, RUNTIME_KINDS.SYSTEMD],
+    [{ JOURNAL_STREAM: '9' }, RUNTIME_KINDS.SYSTEMD],
+    [{ NOTIFY_SOCKET: '/run/notify' }, RUNTIME_KINDS.SYSTEMD],
+    [{ SUPERVISOR_ENABLED: '1' }, RUNTIME_KINDS.SUPERVISORD],
+    [{ SUPERVISOR_PROCESS_NAME: 'dsh' }, RUNTIME_KINDS.SUPERVISORD],
+    [{ KUBERNETES_SERVICE_HOST: '10.0.0.1' }, RUNTIME_KINDS.KUBERNETES],
+  ]
+  for (const [env, kind] of table) {
+    const result = await detectRuntimeEnv({ env, platform: POSIX, isTTY: NO_TTY, ...noProbes })
+    assert.deepEqual(result, { kind, declared: true }, JSON.stringify(env))
+  }
+  // 空串环境值不构成声明
+  const empty = await detectRuntimeEnv({ env: { pm_id: '' }, platform: POSIX, isTTY: NO_TTY, ...noProbes })
+  assert.deepEqual(empty, { kind: RUNTIME_KINDS.UNKNOWN, declared: false })
+})
+
+test('环境检测:POSIX 容器探测', async () => {
+  const docker = await detectRuntimeEnv({ env: {}, platform: POSIX, isTTY: NO_TTY, existsImpl: async (p) => p === '/.dockerenv', readFileImpl: async () => { throw new Error('ENOENT') } })
+  assert.deepEqual(docker, { kind: RUNTIME_KINDS.DOCKER, declared: true })
+  for (const [marker, kind] of [['/docker/', RUNTIME_KINDS.DOCKER], ['kubepods', RUNTIME_KINDS.KUBERNETES], ['containerd', RUNTIME_KINDS.CONTAINER], ['lxc', RUNTIME_KINDS.CONTAINER], ['podman', RUNTIME_KINDS.CONTAINER]]) {
+    const result = await detectRuntimeEnv({ env: {}, platform: POSIX, isTTY: NO_TTY, existsImpl: async () => false, readFileImpl: async () => '12:pids:/sys/fs/cgroup/' + marker + 'abc' })
+    assert.deepEqual(result, { kind, declared: true }, marker)
+  }
+  // 探测器异常不致命,继续后续判定
+  const broken = await detectRuntimeEnv({ env: {}, platform: POSIX, isTTY: NO_TTY, existsImpl: async () => { throw new Error('EACCES') }, readFileImpl: async () => { throw new Error('EACCES') } })
+  assert.deepEqual(broken, { kind: RUNTIME_KINDS.UNKNOWN, declared: false })
+})
+
+test('环境检测:win32 跳过 POSIX 探测', async () => {
+  const win = await detectRuntimeEnv({ env: {}, platform: WIN32, isTTY: NO_TTY, existsImpl: async () => true, readFileImpl: async () => '/docker/xyz' })
+  assert.deepEqual(win, { kind: RUNTIME_KINDS.UNKNOWN, declared: false })
+})
+
+test('环境检测:双 TTY 判手动直跑,单 TTY 不构成', async () => {
+  const both = await detectRuntimeEnv({ env: {}, platform: POSIX, isTTY: BOTH_TTY, ...noProbes })
+  assert.deepEqual(both, { kind: RUNTIME_KINDS.MANUAL_START, declared: false })
+  const stdinOnly = await detectRuntimeEnv({ env: {}, platform: POSIX, isTTY: { stdin: true, stdout: false }, ...noProbes })
+  assert.deepEqual(stdinOnly, { kind: RUNTIME_KINDS.UNKNOWN, declared: false })
+  // 托管声明优先于 TTY
+  const declaredWithTty = await detectRuntimeEnv({ env: { pm_id: '0' }, platform: POSIX, isTTY: BOTH_TTY, ...noProbes })
+  assert.deepEqual(declaredWithTty, { kind: RUNTIME_KINDS.PM2, declared: true })
+})

package/test/upgrade.test.mjs

@@ -1,7 +1,18 @@
 import { test } from 'node:test'
 import assert from 'node:assert/strict'
+import { rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
 
 import { runUpgrade } from '../src/upgrade.mjs'
+import { runUpgradeWithRetry, judgeAutoRestart, UPGRADE_MAX_ATTEMPTS, UPGRADE_RETRY_BACKOFF_MS } from '../src/index.js'
+import {
+  UPGRADE_FAIL_FILE_LOCKED,
+  UPGRADE_FAIL_TRANSIENT_NETWORK,
+  UPGRADE_FAIL_NPM_MISSING,
+  UPGRADE_FAIL_TIMEOUT,
+} from '../src/core.mjs'
+import { RUNTIME_KINDS } from '../src/runtime.mjs'
 
 // 脚本体一律单引号:Windows shell 化 spawn 经 cmd.exe,双层双引号会被截断。
 const NODE = 'node'
@@ -63,3 +74,164 @@ test('场景:命令不存在失败不抛错', async () => {
   const result = await runUpgrade({ command: 'definitely-not-exist-cmd-xyz --version', timeoutMs: 10 * 1000 })
   assert.equal(result.ok, false)
 })
+
+// ---- S2 限次重试:尝试循环以注入式执行器单测,退避零等待;末尾附真实假命令端到端 ----
+
+const FILE_LOCKED_FAIL = {
+  ok: false,
+  code: 1,
+  timedOut: false,
+  stillRunning: false,
+  stdoutTail: '',
+  stderrTail: 'npm error code EBUSY\nnpm error syscall rename',
+}
+const NETWORK_FAIL = {
+  ok: false,
+  code: 1,
+  timedOut: false,
+  stillRunning: false,
+  stdoutTail: '',
+  stderrTail: 'npm error code ECONNRESET',
+}
+const OK_RESULT = { ok: true, code: 0, timedOut: false, stillRunning: false, stdoutTail: '', stderrTail: '' }
+
+function makeHarness(results) {
+  const queue = results.slice()
+  const sleeps = []
+  let attemptStarts = 0
+  return {
+    sleeps,
+    runImpl: async () => (queue.length > 1 ? queue.shift() : queue[0]),
+    sleepImpl: async (ms) => { sleeps.push(ms) },
+    onAttemptStart: () => { attemptStarts += 1 },
+    get starts() { return attemptStarts },
+  }
+}
+
+const ATTEMPT_KEYS = ['startedAt', 'finishedAt', 'ok', 'code', 'timedOut', 'kind'].sort()
+
+test('重试:可重试失败按退避序列重试至成功', async () => {
+  const harness = makeHarness([FILE_LOCKED_FAIL, NETWORK_FAIL, OK_RESULT])
+  const settle = await runUpgradeWithRetry({ command: 'fake', runImpl: harness.runImpl, sleepImpl: harness.sleepImpl, onAttemptStart: harness.onAttemptStart })
+  assert.equal(settle.ok, true)
+  assert.equal(settle.attempts.length, 3)
+  assert.equal(settle.kind, null)
+  assert.deepEqual(settle.attempts.map((a) => a.kind), [UPGRADE_FAIL_FILE_LOCKED, UPGRADE_FAIL_TRANSIENT_NETWORK, null])
+  // 退避按 kind 取序列对应位:file-locked 首退避、transient-network 次退避
+  assert.deepEqual(harness.sleeps, [UPGRADE_RETRY_BACKOFF_MS[UPGRADE_FAIL_FILE_LOCKED][0], UPGRADE_RETRY_BACKOFF_MS[UPGRADE_FAIL_TRANSIENT_NETWORK][1]])
+  assert.equal(harness.starts, 2, '首次尝试不经 onAttemptStart,每次重试各触发一次(锁覆写点)')
+})
+
+test('重试:尝试条目形态锁定为裁剪后字段集,尾流仅在落定结果上', async () => {
+  const harness = makeHarness([FILE_LOCKED_FAIL, OK_RESULT])
+  const settle = await runUpgradeWithRetry({ command: 'fake', runImpl: harness.runImpl, sleepImpl: harness.sleepImpl })
+  assert.deepEqual(Object.keys(settle.attempts[0]).sort(), ATTEMPT_KEYS)
+  assert.equal(settle.attempts[0].code, 1)
+  assert.equal(settle.attempts[0].timedOut, false)
+  assert.ok(settle.attempts[0].finishedAt >= settle.attempts[0].startedAt)
+  // 末次尝试的尾流上浮到落定结果,供 last 直接消费
+  assert.equal(settle.stdoutTail, '')
+  assert.equal(settle.stderrTail, '')
+})
+
+test('重试:不可重试类立即落定,不睡眠不重试', async () => {
+  for (const [fail, kind] of [
+    [{ ...FILE_LOCKED_FAIL, stderrTail: 'spawn npmm ENOENT' }, UPGRADE_FAIL_NPM_MISSING],
+    [{ ok: false, code: null, timedOut: true, stillRunning: false, stdoutTail: '', stderrTail: '' }, UPGRADE_FAIL_TIMEOUT],
+    [{ ok: false, code: 3, timedOut: false, stillRunning: false, stdoutTail: '', stderrTail: 'boom-fail' }, 'unknown'],
+  ]) {
+    const harness = makeHarness([fail])
+    const settle = await runUpgradeWithRetry({ command: 'fake', runImpl: harness.runImpl, sleepImpl: harness.sleepImpl })
+    assert.equal(settle.ok, false)
+    assert.equal(settle.kind, kind, JSON.stringify(fail))
+    assert.equal(settle.attempts.length, 1, JSON.stringify(fail))
+    assert.deepEqual(harness.sleeps, [], JSON.stringify(fail))
+  }
+})
+
+test('重试:持续可重试失败收敛于次数上限,末次不安排退避', async () => {
+  const harness = makeHarness([NETWORK_FAIL])
+  const settle = await runUpgradeWithRetry({ command: 'fake', runImpl: harness.runImpl, sleepImpl: harness.sleepImpl })
+  assert.equal(settle.ok, false)
+  assert.equal(settle.kind, UPGRADE_FAIL_TRANSIENT_NETWORK)
+  assert.equal(settle.attempts.length, UPGRADE_MAX_ATTEMPTS)
+  assert.equal(harness.sleeps.length, UPGRADE_MAX_ATTEMPTS - 1, '末次尝试后不得再安排退避')
+  assert.equal(settle.attempts.every((a) => a.kind === UPGRADE_FAIL_TRANSIENT_NETWORK), true)
+})
+
+test('重试:退避序列缺失按不可重试落定,不得零间隔轰击', async () => {
+  // 注入空退避表模拟"可重试分类缺少序列"的配置缺口:宁可不重试,不可无间隔重试
+  const warns = []
+  const originalWarn = console.warn
+  console.warn = (text) => { warns.push(String(text)) }
+  try {
+    const harness = makeHarness([FILE_LOCKED_FAIL])
+    const settle = await runUpgradeWithRetry({ command: 'fake', backoff: {}, runImpl: harness.runImpl, sleepImpl: harness.sleepImpl })
+    assert.equal(settle.ok, false)
+    assert.equal(settle.kind, UPGRADE_FAIL_FILE_LOCKED)
+    assert.equal(settle.attempts.length, 1, '序列缺失不得进入下一轮尝试')
+    assert.deepEqual(harness.sleeps, [], '序列缺失不得安排退避')
+    assert.equal(warns.some((text) => text.includes('退避')), true, '序列缺失必须留痕')
+  } finally {
+    console.warn = originalWarn
+  }
+})
+
+test('重试:执行器抛错收敛为失败落定不重试', async () => {
+  const settle = await runUpgradeWithRetry({
+    command: 'fake',
+    runImpl: async () => { throw new Error('spawn exploded') },
+    sleepImpl: async () => {},
+  })
+  assert.equal(settle.ok, false)
+  assert.equal(settle.error, 'spawn exploded')
+  assert.equal(settle.attempts.length, 1)
+})
+
+test('重试:常量形态为计算式导出', () => {
+  assert.equal(UPGRADE_MAX_ATTEMPTS, 3)
+  assert.deepEqual(UPGRADE_RETRY_BACKOFF_MS[UPGRADE_FAIL_FILE_LOCKED], [5 * 1000, 15 * 1000])
+  assert.deepEqual(UPGRADE_RETRY_BACKOFF_MS[UPGRADE_FAIL_TRANSIENT_NETWORK], [3 * 1000, 9 * 1000])
+})
+
+test('重试:假命令真实进程 文件锁失败后重试成功', async () => {
+  const statePath = join(tmpdir(), 'dsh-maintain-retry-test-' + process.pid + '.flag')
+  rmSync(statePath, { force: true })
+  process.env.DSH_MAINTAIN_TEST_RETRY_STATE = statePath
+  try {
+    const script = "const fs=require('fs');const p=process.env.DSH_MAINTAIN_TEST_RETRY_STATE;if(fs.existsSync(p)){process.exit(0)}fs.writeFileSync(p,'1');console.error('npm error code EBUSY');console.error('npm error syscall rename');process.exit(1)"
+    let attemptStarts = 0
+    const settle = await runUpgradeWithRetry({
+      command: NODE + ' -e "' + script + '"',
+      runImpl: (opts) => runUpgrade(opts),
+      sleepImpl: async () => {},
+      onAttemptStart: () => { attemptStarts += 1 },
+    })
+    assert.equal(settle.ok, true)
+    assert.equal(settle.attempts.length, 2)
+    assert.equal(settle.attempts[0].ok, false)
+    assert.equal(settle.attempts[0].kind, UPGRADE_FAIL_FILE_LOCKED, '真实进程 stderr 应命中文件锁特征: ' + settle.attempts[0].stderrTail)
+    assert.equal(settle.attempts[1].ok, true)
+    assert.equal(settle.attempts[1].kind, null)
+    assert.equal(attemptStarts, 1, '仅重试尝试覆写锁')
+  } finally {
+    rmSync(statePath, { force: true })
+  }
+})
+
+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 })
+  // 失败不调度
+  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: true, stale: false, runtimeKind: RUNTIME_KINDS.MANUAL_START, hasExit: true }), { schedule: false, requiresManualRestart: true })
+  // appExit 缺失不调度
+  assert.deepEqual(judgeAutoRestart({ ok: true, stale: false, runtimeKind: RUNTIME_KINDS.UNKNOWN, hasExit: false }), { schedule: false, requiresManualRestart: false })
+  // 手动直跑与 appExit 缺失并存 → 仍以手动指引标记(指引面板,与退出能力无关)
+  assert.deepEqual(judgeAutoRestart({ ok: true, stale: false, runtimeKind: RUNTIME_KINDS.MANUAL_START, hasExit: false }), { schedule: false, requiresManualRestart: true })
+})