@twinsearth/dsh-master 3.3.3 → 3.3.5

package/src/engine/llm-stream.ts

@@ -0,0 +1,189 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+// @ts-nocheck
+
+/**
+ * 可中断的 LLM 流（3.3.5）。
+ *
+ * 真实宿主 API 是 `ctx.llm.stream(options)`（不是草案里的 `llm.client.chat.completions.create`）：
+ *   * `options.signal` 原生支持取消；
+ *   * 取消后流会以 `{type:'finish', reason:{kind:'aborted'}}` 收尾；
+ *   * `StreamChunk` 里文本增量是 `{type:'text-delta', text}`。
+ *
+ * 本模块负责「谁在跑、怎么停、停完怎么记账」：
+ *   * 每个 key（会话/消息）最多一条在跑的流，新的一轮会先中止旧的；
+ *   * 中止后**保留已产出的半截文本**（`partial`），供 UI 展示与上下文续写；
+ *   * `dispose()` 中止全部（宿主卸载用）；
+ *   * **不声称**能验证服务端计费已停止——我们只能保证自己停止读取并传了 signal。
+ *
+ * 依赖注入：`streamFn(options) => AsyncIterable<StreamChunk>`，便于测试与替换。
+ */
+
+import { createAbortRegistry } from '../channel/abort-registry.ts'
+
+const ABORTED = Symbol('aborted')
+
+function watchAbort(signal) {
+  if (!signal) return { promise: new Promise(() => {}), cancel: () => {} }
+  let listener = null
+  const promise = new Promise((resolve) => {
+    if (signal.aborted) { resolve(ABORTED); return }
+    listener = () => resolve(ABORTED)
+    signal.addEventListener('abort', listener, { once: true })
+  })
+  return {
+    promise,
+    cancel: () => { try { if (listener) signal.removeEventListener('abort', listener) } catch { /* ignore */ } },
+  }
+}
+
+function chunkText(chunk) {
+  if (!chunk || typeof chunk !== 'object') return ''
+  if (chunk.type === 'text-delta') return String(chunk.text ?? '')
+  if (chunk.type === 'reasoning-delta') return ''
+  return ''
+}
+
+/**
+ * @param {{
+ *   streamFn: (options: object) => AsyncIterable<object>,
+ *   registry?: object,
+ *   onDelta?: (delta: string, meta: object) => void,
+ *   logger?: { info?: Function, warn?: Function, error?: Function },
+ * }} deps
+ */
+export function createLlmStreamer(deps = {}) {
+  if (typeof deps.streamFn !== 'function') {
+    return {
+      available: false,
+      reason: 'streamFn-required',
+      run: async () => ({ ok: false, code: 'streamFn-required', error: 'a streamFn(options) => AsyncIterable is required' }),
+      abort: () => false,
+      abortAll: () => [],
+      activeKeys: () => [],
+      dispose: () => ({ aborted: [] }),
+    }
+  }
+
+  const registry = deps.registry ?? createAbortRegistry()
+  const log = (level, message) => { try { deps.logger?.[level]?.(message) } catch { /* ignore */ } }
+  const stallTimeoutMs = Number(deps.stallTimeoutMs) > 0 ? Number(deps.stallTimeoutMs) : 0
+  let disposed = false
+
+  /**
+   * 跑一条流并返回结构化结果（永不抛：错误变成 code）。
+   * @param {{key: string, options?: object, signal?: AbortSignal}} input
+   */
+  async function run(input = {}) {
+    const key = String(input.key ?? '').trim()
+    if (!key) return { ok: false, code: 'key-required', error: 'key is required' }
+    if (disposed) return { ok: false, code: 'streamer-disposed', error: 'streamer was disposed' }
+
+    const entry = registry.begin(key)
+    const signal = entry.signal
+    const onDelta = typeof input.onDelta === 'function' ? input.onDelta : deps.onDelta
+    const external = input.signal
+    const onExternalAbort = () => entry.abort('external-abort')
+    if (external) {
+      if (external.aborted) entry.abort('external-abort')
+      else external.addEventListener('abort', onExternalAbort, { once: true })
+    }
+
+    let text = ''
+    let finish = null
+    let aborted = false
+    let usage = null
+    const watch = watchAbort(signal)
+    const iteratorRef = { current: null }
+
+    try {
+      const iterator = deps.streamFn({ ...(input.options ?? {}), signal })
+      iteratorRef.current = iterator?.[Symbol.asyncIterator]?.() ?? null
+      if (!iteratorRef.current) return { ok: false, code: 'stream-not-async-iterable', error: 'streamFn must return an AsyncIterable', text, aborted: false }
+
+      while (true) {
+        // 卡住兜底：上游长时间不吐字（连接半死/网关静默）时主动中止，避免句柄挂着烧钱
+        const stall = stallTimeoutMs > 0
+          ? new Promise((resolve) => { const timer = setTimeout(() => resolve('stalled'), stallTimeoutMs); if (typeof timer.unref === 'function') timer.unref() })
+          : new Promise(() => {})
+        const step = await Promise.race([iteratorRef.current.next(), watch.promise, stall])
+        if (step === 'stalled') {
+          entry.abort('stalled')
+          log('warn', `[llm-stream] upstream stalled >${stallTimeoutMs}ms key=${key}`)
+          return { ok: false, code: 'stalled', error: `no chunk within ${stallTimeoutMs}ms`, text, aborted: true, finish, usage, savedContent: text }
+        }
+        if (step === ABORTED) { aborted = true; break }
+        if (!step || step.done) break
+        const chunk = step.value
+        if (signal.aborted) { aborted = true; break }
+        if (chunk?.type === 'usage' && chunk.usage) usage = chunk.usage
+        if (chunk?.type === 'finish') {
+          finish = chunk.reason ?? null
+          if (finish?.kind === 'aborted') aborted = true
+          if (finish?.kind === 'error') {
+            return { ok: false, code: 'llm-error', error: finish.failure?.message ?? 'model call failed', failure: finish.failure, text, aborted: false, usage }
+          }
+          continue
+        }
+        const delta = chunkText(chunk)
+        if (delta) {
+          text += delta
+          try { onDelta?.(delta, { key, text }) } catch { /* 消费回调异常不影响流 */ }
+        }
+      }
+
+      if (aborted) {
+        log('info', `[llm-stream] aborted key=${key} after ${text.length} chars`)
+        return { ok: false, code: 'aborted', error: 'generation aborted by caller', text, aborted: true, finish, usage, savedContent: text }
+      }
+      log('info', `[llm-stream] done key=${key} chars=${text.length}`)
+      return { ok: true, code: 'completed', text, aborted: false, finish, usage }
+    } catch (error) {
+      const message = String(error?.message ?? error)
+      const isAbort = signal.aborted || error?.name === 'AbortError' || /abort/iu.test(message)
+      if (isAbort) {
+        log('info', `[llm-stream] abort surfaced as error key=${key}: ${message}`)
+        return { ok: false, code: 'aborted', error: message, text, aborted: true, finish, usage, savedContent: text }
+      }
+      log('error', `[llm-stream] failed key=${key}: ${message}`)
+      return { ok: false, code: 'stream-failed', error: message, text, aborted: false, finish, usage }
+    } finally {
+      watch.cancel()
+      try { external?.removeEventListener?.('abort', onExternalAbort) } catch { /* ignore */ }
+      // 清理上游时**绝不能无限等**：卡死的异步生成器会把 return() 排在未完成的 next() 后面，
+      // await 它会永久挂住（这正是我们要防的僵尸句柄）。这里给一个有界让步。
+      try {
+        const closing = iteratorRef.current?.return?.()
+        if (closing && typeof closing.then === 'function') {
+          await Promise.race([
+            closing,
+            new Promise((resolve) => { const timer = setTimeout(resolve, 50); if (typeof timer.unref === 'function') timer.unref() }),
+          ])
+        }
+      } catch { /* 尽力关闭上游 */ }
+      entry.end()
+    }
+  }
+
+  return {
+    available: true,
+    run,
+    abort: (key, reason = 'user-interrupt') => registry.abort(String(key ?? ''), reason),
+    abortAll: (reason = 'shutdown') => registry.abortAll(reason),
+    activeKeys: () => registry.keys(),
+    dispose: () => {
+      if (disposed) return { aborted: [] }
+      disposed = true
+      return { aborted: registry.abortAll('disposed') }
+    },
+  }
+}
+
+/**
+ * 把真实 `ctx.llm.stream` 适配成 streamFn。
+ * 之所以包一层：只取需要的字段，且把 method 绑定到服务对象上（避免 this 丢失）。
+ */
+export function llmStreamFn(llm) {
+  if (!llm || typeof llm.stream !== 'function') return null
+  return (options) => llm.stream(options)
+}

package/src/engine/plugin-updater.ts

@@ -0,0 +1,359 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+// @ts-nocheck
+
+/**
+ * 插件安全更新流水线（房主版 PluginUpdater · 3.3.5 增强）。
+ *
+ * 语义：快照 → 后台更新（可轮询）→ 冒烟 → 成功清理 / 失败物理回滚。
+ * 不假设存在 VM：执行能力由调用方注入 `executor`。
+ *
+ * 本版新增（相对上一版）：
+ *   1. **生命周期中断**：`dispose()`（宿主侧挂在 ctx.effect 里）会中止所有进行中的更新；
+ *   2. **信号合并**：外部 `signal` + 内部整体超时 + job 超时，三者任一触发都能打断轮询；
+ *   3. **进度节流**：`minProgressIntervalMs` 限制 onProgress 频率，终态与阶段切换必发；
+ *   4. **致命告警钩子**：回滚失败时 `onFatal()` 必被调用（宿主可据此弹全局告警）；
+ *   5. **命令构造辅助**：`shellArgv()` 以 argv 形式传脚本，避免手写引号导致的注入/截断。
+ *
+ * executor 契约：
+ *   snapshot(name) → {ok}
+ *   restore(name) → {ok}
+ *   run(argv, {phase, signal?}) → {ok, jobId?}
+ *   jobStatus(jobId) → {status:'running'|'completed'|'failed', exitCode?, stdout?, stderr?}
+ *   deleteSnapshot?(name)
+ */
+
+export const UPDATE_PHASES = Object.freeze([
+  'idle', 'snapshotting', 'updating', 'smoke-testing', 'rolling-back', 'success', 'failed',
+])
+
+const DEFAULTS = Object.freeze({
+  timeoutMs: 10 * 60 * 1000,
+  smokeTimeoutMs: 60 * 1000,
+  pollIntervalMs: 2_000,
+  minProgressIntervalMs: 0,
+})
+
+const sleepDefault = (ms) => new Promise((resolve) => setTimeout(resolve, Math.max(1, ms)))
+const ABORTED = Symbol('aborted')
+
+/**
+ * 把 AbortSignal 变成可 race 的 promise：即使适配器的某个调用永不 resolve，
+ * 中止也能立刻打断等待（这是“不留僵尸轮询”的关键）。
+ */
+function watchAbort(signal) {
+  if (!signal) return { promise: new Promise(() => {}), cancel: () => {} }
+  let listener = null
+  const promise = new Promise((resolve) => {
+    if (signal.aborted) { resolve(ABORTED); return }
+    listener = () => resolve(ABORTED)
+    signal.addEventListener('abort', listener, { once: true })
+  })
+  return {
+    promise,
+    cancel: () => { try { if (listener) signal.removeEventListener('abort', listener) } catch { /* ignore */ } },
+  }
+}
+
+function requiredExecutor(executor) {
+  if (!executor || typeof executor.snapshot !== 'function' || typeof executor.restore !== 'function' || typeof executor.run !== 'function') {
+    return null
+  }
+  return executor
+}
+
+function positiveInt(value, fallback) {
+  const n = Number(value)
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : fallback
+}
+
+/**
+ * 把一段 shell 脚本包成 argv，**不拼接引号**：脚本始终是单个参数。
+ * 这是避免“引号地狱 / 注入”的正解——不要手写 `'${script.replace(/'/g, ...)}'`。
+ */
+export function shellArgv(script, { shell = 'bash', login = true } = {}) {
+  const text = String(script ?? '')
+  if (!text.trim()) return []
+  return [shell, login ? '-lc' : '-c', text]
+}
+
+/** 默认冒烟脚本：set -e + 有限次健康探测（端口由调用方传入，别硬编码 3000）。 */
+export function buildSmokeScript({ port = 3000, path = '/api/health', attempts = 10, intervalSeconds = 2 } = {}) {
+  const safePath = String(path).startsWith('/') ? String(path) : `/${path}`
+  const tries = Math.max(1, Math.min(60, Number(attempts) || 10))
+  const wait = Math.max(1, Math.min(30, Number(intervalSeconds) || 2))
+  return [
+    'set -eu',
+    'dsh stop >/dev/null 2>&1 || true',
+    'dsh start --daemon',
+    `for i in $(seq 1 ${tries}); do`,
+    `  if curl -fsS "http://127.0.0.1:${Number(port) || 3000}${safePath}" >/dev/null; then exit 0; fi`,
+    `  sleep ${wait}`,
+    'done',
+    'echo "health check timeout" >&2',
+    'exit 1',
+  ].join('\n')
+}
+
+/**
+ * @param {{
+ *   executor?: object,
+ *   logger?: { info?: Function, warn?: Function, error?: Function },
+ *   onProgress?: (progress: {phase:string, message:string, percent:number, at:number}) => void,
+ *   onFatal?: (failure: {code:string, message:string, snapshotId:string, steps:object[]}) => void,
+ *   minProgressIntervalMs?: number,
+ *   now?: () => number,
+ *   sleepImpl?: (ms:number) => Promise<void>,
+ * }} deps
+ */
+export function createPluginUpdater(deps = {}) {
+  const logger = deps.logger ?? {}
+  const now = typeof deps.now === 'function' ? deps.now : () => Date.now()
+  const sleep = typeof deps.sleepImpl === 'function' ? deps.sleepImpl : sleepDefault
+  const progressInterval = Number(deps.minProgressIntervalMs) > 0 ? Number(deps.minProgressIntervalMs) : DEFAULTS.minProgressIntervalMs
+  const running = new Map()
+  const lifecycle = new AbortController()
+  let disposed = false
+
+  const log = (level, message) => { try { logger[level]?.(message) } catch { /* ignore */ } }
+
+  function makeReporter() {
+    let lastEmitAt = -Infinity
+    let lastPhase = null
+    const emit = (progress, force = false) => {
+      if (!force && progress.percent < 100 && progressInterval > 0 && now() - lastEmitAt < progressInterval) return
+      lastEmitAt = now()
+      lastPhase = progress.phase
+      try { deps.onProgress?.(progress) } catch { /* 回调异常不影响事务 */ }
+    }
+    return {
+      report: (phase, message, percent) => {
+        const terminal = percent >= 100 || phase === 'success' || phase === 'failed'
+        const phaseChanged = phase !== lastPhase
+        emit({ phase, message, percent, at: now() }, terminal || phaseChanged)
+      },
+    }
+  }
+
+  /**
+   * 轮询异步作业直到终态；支持外部信号与超时，超时给具名 code。
+   * `jobStatus` 与 `sleep` 都与中止信号 race，因此卡死的适配器也能被打断。
+   */
+  async function waitForJob(executor, jobId, timeoutMs, signal, onPoll) {
+    const startedAt = now()
+    const deadline = startedAt + timeoutMs
+    const watch = watchAbort(signal)
+    let polls = 0
+    try {
+      while (true) {
+        if (signal?.aborted) return { ok: false, code: 'aborted', polls, elapsedMs: Math.max(0, now() - startedAt) }
+        polls += 1
+        const status = await Promise.race([executor.jobStatus(jobId), watch.promise])
+        if (status === ABORTED) return { ok: false, code: 'aborted', polls, elapsedMs: Math.max(0, now() - startedAt) }
+        const state = String(status?.status ?? '')
+        if (state === 'completed' || state === 'failed') {
+          return { ok: state === 'completed' && Number(status?.exitCode ?? 0) === 0, status, polls, elapsedMs: Math.max(0, now() - startedAt) }
+        }
+        try { onPoll?.(polls) } catch { /* ignore */ }
+        if (now() >= deadline) return { ok: false, code: 'job-timeout', status, polls, elapsedMs: Math.max(0, now() - startedAt) }
+        const remaining = deadline - now()
+        const slept = await Promise.race([sleep(Math.min(DEFAULTS.pollIntervalMs, Math.max(1, remaining))), watch.promise])
+        if (slept === ABORTED) return { ok: false, code: 'aborted', polls, elapsedMs: Math.max(0, now() - startedAt) }
+      }
+    } finally {
+      watch.cancel()
+    }
+  }
+
+  async function safeUpdate(input = {}) {
+    if (disposed) {
+      return { success: false, code: 'updater-disposed', message: 'updater was disposed', rolledBack: false, fatal: false, steps: [] }
+    }
+    const executor = requiredExecutor(deps.executor)
+    if (!executor) return { success: false, code: 'executor-required', message: 'an executor with snapshot/restore/run is required; no VM is assumed', rolledBack: false, fatal: false, steps: [] }
+
+    const update = Array.isArray(input.update) && input.update.length > 0 ? input.update : null
+    if (!update) return { success: false, code: 'update-command-required', message: 'update argv is required', rolledBack: false, fatal: false, steps: [] }
+
+    const key = String(input.key ?? input.target ?? 'default')
+    if (running.has(key)) return { success: false, code: 'update-in-progress', message: `another update is already running for ${key}`, rolledBack: false, fatal: false, steps: [] }
+
+    const timeoutMs = positiveInt(input.timeoutMs, DEFAULTS.timeoutMs)
+    const smokeTimeoutMs = positiveInt(input.smokeTimeoutMs, DEFAULTS.smokeTimeoutMs)
+    const snapshotName = String(input.snapshotName ?? '').trim() || `pre-update-${now()}`
+    const steps = []
+    const record = (step, detail = {}) => { steps.push({ step, at: now(), ...detail }) }
+    const { report } = makeReporter()
+
+    // 三个中断源合并成一个内部控制器：外部 signal、整体超时、dispose()
+    const controller = new AbortController()
+    const signal = controller.signal
+    const onExternalAbort = () => controller.abort(String(input.signal?.reason ?? 'external-abort'))
+    if (input.signal) {
+      if (input.signal.aborted) controller.abort('external-abort')
+      else input.signal.addEventListener('abort', onExternalAbort, { once: true })
+    }
+    const onLifecycleAbort = () => controller.abort('disposed')
+    lifecycle.signal.addEventListener('abort', onLifecycleAbort, { once: true })
+    const deadline = now() + timeoutMs
+    const remaining = () => Math.max(1, deadline - now())
+    const timeoutTimer = setTimeout(() => controller.abort('timeout'), timeoutMs)
+    if (typeof timeoutTimer.unref === 'function') timeoutTimer.unref()
+
+    const cleanupSignals = () => {
+      clearTimeout(timeoutTimer)
+      try { input.signal?.removeEventListener?.('abort', onExternalAbort) } catch { /* ignore */ }
+      try { lifecycle.signal.removeEventListener('abort', onLifecycleAbort) } catch { /* ignore */ }
+    }
+
+    const run = async () => {
+      const abortResult = (code, extra = {}) => ({
+        success: false, code, message: `update ${code}`, rolledBack: false, fatal: false, snapshotId: snapshotName, steps, ...extra,
+      })
+
+      if (signal.aborted) return abortResult('aborted', { abortedBeforeSnapshot: true })
+
+      // ── Phase 1: snapshot ────────────────────────────────────────────────
+      report('snapshotting', '正在创建快照…', 5)
+      try {
+        const snapshot = await executor.snapshot(snapshotName)
+        if (snapshot && snapshot.ok === false) {
+          record('snapshot', { ok: false, detail: snapshot })
+          report('failed', '快照失败，已中止更新（环境未改动）', 100)
+          return { success: false, code: 'snapshot-failed', message: 'snapshot failed; update aborted before any change', rolledBack: false, fatal: false, snapshotId: snapshotName, steps }
+        }
+        record('snapshot', { ok: true })
+        log('info', `[plugin-updater] snapshot ready: ${snapshotName}`)
+      } catch (error) {
+        record('snapshot', { ok: false, error: String(error?.message ?? error) })
+        report('failed', '快照异常，已中止更新（环境未改动）', 100)
+        return { success: false, code: 'snapshot-threw', message: String(error?.message ?? error), rolledBack: false, fatal: false, snapshotId: snapshotName, steps }
+      }
+
+      const rollback = async (reason, message) => {
+        report('rolling-back', '更新失败，正在回滚…', 85)
+        let restored = null
+        try { restored = await executor.restore(snapshotName) } catch (error) { restored = { ok: false, error: String(error?.message ?? error) } }
+        const restoredOk = restored?.ok !== false
+        record('restore', { ok: restoredOk, detail: restored })
+        if (!restoredOk) {
+          const failure = { code: 'rollback-failed', message: `${reason}: rollback failed, manual intervention required`, snapshotId: snapshotName, steps }
+          log('error', `[plugin-updater] FATAL rollback failed for ${snapshotName}: ${JSON.stringify(restored)}`)
+          report('failed', '回滚失败，需要人工介入！', 100)
+          try { deps.onFatal?.(failure) } catch { /* 告警钩子异常不改变结论 */ }
+          return { success: false, ...failure, rolledBack: false, fatal: true }
+        }
+        if (Array.isArray(input.restart) && input.restart.length > 0) {
+          try {
+            const restarted = await executor.run(input.restart, { phase: 'restart' })
+            record('restart', { ok: restarted?.ok !== false, detail: restarted })
+          } catch (error) {
+            record('restart', { ok: false, error: String(error?.message ?? error) })
+          }
+        }
+        report('failed', '已回滚到更新前状态', 100)
+        log('warn', `[plugin-updater] rolled back after ${reason}`)
+        return { success: false, code: reason, message, rolledBack: true, fatal: false, snapshotId: snapshotName, steps }
+      }
+
+      if (signal.aborted) return await rollback('aborted', 'update aborted before applying changes; snapshot discarded')
+
+      // ── Phase 2: update ─────────────────────────────────────────────────
+      report('updating', '正在执行更新…', 20)
+      try {
+        const updated = await executor.run(update, { phase: 'update', signal })
+        if (updated && updated.ok === false) {
+          record('update', { ok: false, detail: updated })
+          return await rollback('update-failed', 'update command failed; environment rolled back')
+        }
+        if (signal.aborted) return await rollback('aborted', 'update aborted by caller; environment rolled back')
+        if (updated && typeof updated.jobId === 'string' && updated.jobId) {
+          const job = await waitForJob(executor, updated.jobId, Math.min(remaining(), timeoutMs), signal, (polls) => {
+            report('updating', `等待更新作业…（第 ${polls} 次轮询）`, 20 + Math.min(45, polls * 2))
+          })
+          if (!job.ok) {
+            record('update-job', { ok: false, code: job.code ?? 'job-failed', polls: job.polls, detail: job.status })
+            if (job.code === 'aborted') return await rollback('aborted', 'update job aborted; environment rolled back')
+            return await rollback(job.code === 'job-timeout' ? 'job-timeout' : 'update-job-failed', job.code === 'job-timeout' ? `update job timed out after ${timeoutMs}ms` : 'update job failed; environment rolled back')
+          }
+          record('update-job', { ok: true, polls: job.polls, elapsedMs: job.elapsedMs })
+        }
+        record('update', { ok: true, async: Boolean(updated?.jobId) })
+      } catch (error) {
+        record('update', { ok: false, error: String(error?.message ?? error) })
+        return await rollback('update-threw', String(error?.message ?? error))
+      }
+
+      // ── Phase 3: smoke ──────────────────────────────────────────────────
+      if (Array.isArray(input.smoke) && input.smoke.length > 0) {
+        report('smoke-testing', '正在做冒烟测试…', 70)
+        try {
+          const smoke = await executor.run(input.smoke, { phase: 'smoke', signal })
+          if (smoke && smoke.ok === false) {
+            record('smoke', { ok: false, detail: smoke })
+            return await rollback('smoke-failed', 'smoke test failed after update; environment rolled back')
+          }
+          if (smoke && typeof smoke.jobId === 'string' && smoke.jobId) {
+            const job = await waitForJob(executor, smoke.jobId, Math.min(remaining(), smokeTimeoutMs), signal, (polls) => {
+              report('smoke-testing', `等待冒烟作业…（第 ${polls} 次轮询）`, 70 + Math.min(20, polls))
+            })
+            if (!job.ok) {
+              record('smoke-job', { ok: false, code: job.code ?? 'job-failed', polls: job.polls })
+              if (job.code === 'aborted') return await rollback('aborted', 'smoke test aborted; environment rolled back')
+              return await rollback('smoke-failed', 'smoke test job failed; environment rolled back')
+            }
+            record('smoke-job', { ok: true, polls: job.polls })
+          }
+          record('smoke', { ok: true })
+        } catch (error) {
+          record('smoke', { ok: false, error: String(error?.message ?? error) })
+          return await rollback('smoke-threw', String(error?.message ?? error))
+        }
+        // 冒烟期间被中止：不能把“刚好跑完”当成成功
+        if (signal.aborted) return await rollback('aborted', 'update aborted during smoke test; environment rolled back')
+      }
+
+      // ── Phase 4: success ────────────────────────────────────────────────
+      report('success', '更新完成，系统运行正常', 100)
+      if (input.keepSnapshotOnSuccess !== true && typeof executor.deleteSnapshot === 'function') {
+        try {
+          await executor.deleteSnapshot(snapshotName)
+          record('cleanup', { ok: true })
+        } catch (error) {
+          record('cleanup', { ok: false, error: String(error?.message ?? error) })
+          log('warn', `[plugin-updater] snapshot cleanup failed: ${String(error?.message ?? error)}`)
+        }
+      }
+      log('info', '[plugin-updater] update succeeded')
+      return { success: true, code: 'updated', message: 'all plugins updated and verified', rolledBack: false, fatal: false, snapshotId: snapshotName, steps }
+    }
+
+    running.set(key, true)
+    try {
+      const result = await run()
+      return { ...result, phase: result.success ? 'success' : 'failed' }
+    } finally {
+      running.delete(key)
+      cleanupSignals()
+    }
+  }
+
+  /** 宿主卸载时调用（通常包在 ctx.effect 里）：中止所有在跑的更新。 */
+  function dispose() {
+    if (disposed) return { aborted: 0 }
+    disposed = true
+    let aborted = 0
+    try { lifecycle.abort('disposed') } catch { /* ignore */ }
+    for (const key of running.keys()) { running.delete(key); aborted += 1 }
+    log('info', `[plugin-updater] disposed; ${aborted} update(s) signalled to stop`)
+    return { aborted }
+  }
+
+  return {
+    safeUpdate,
+    isRunning: (key = 'default') => running.has(String(key)),
+    activeCount: () => running.size,
+    phases: UPDATE_PHASES,
+    dispose,
+  }
+}