sintbot 1.4.1 → 1.4.2

package/CHANGELOG.en.json

@@ -1,4 +1,23 @@
 [
+  {
+    "version": "1.4.2",
+    "date": "2026-11-09",
+    "name": "Check and install new versions from the console",
+    "items": [
+      {
+        "t": "Version checks in the console",
+        "d": "Software updates in Settings checks for stable releases at startup and daily and shows release notes when a new version is available."
+      },
+      {
+        "t": "One-click upgrade for background runs",
+        "d": "When a launchd agent runs SintBot, Upgrade now waits until every group is idle and settled, installs the new version into its own folder and switches to it; if it does not connect every group within 90 seconds, the previous version is restored. New messages wait about a minute during the switch and are asked to be resent."
+      },
+      {
+        "t": "Steps for foreground runs",
+        "d": "A foreground run shows how to stop, reinstall and start. Upgrades are not announced in groups."
+      }
+    ]
+  },
   {
     "version": "1.4.1",
     "date": "2026-11-09",

package/CHANGELOG.json

@@ -1,4 +1,23 @@
 [
+  {
+    "version": "1.4.2",
+    "date": "2026-11-09",
+    "name": "在控制台查看和安装新版本",
+    "items": [
+      {
+        "t": "控制台检查新版本",
+        "d": "设置页的软件更新启动时和每天各检查一次正式版，有新版本时提示并附发布说明。"
+      },
+      {
+        "t": "后台运行时一键升级",
+        "d": "由 launchd 后台任务运行时，点「现在升级」会等所有群空闲、记录结清后，把新版本装到单独的目录再切换；新版本 90 秒内没连上全部群会自动换回旧版。切换期间约一分钟不处理新消息，会提示稍后重发。"
+      },
+      {
+        "t": "前台运行给出升级步骤",
+        "d": "前台运行时卡片说明如何停止、重新安装并启动。升级不在群里播报。"
+      }
+    ]
+  },
   {
     "version": "1.4.1",
     "date": "2026-11-09",

package/bin/sintbot-v2.js

@@ -112,6 +112,7 @@ async function startMultiGroupService({ installation, preflightOnly, uiEnabled =
   let service
   let ui
   let configControl
+  let updater
   let liveTransport
   let onSigint, onSigterm
   try {
@@ -157,6 +158,7 @@ async function startMultiGroupService({ installation, preflightOnly, uiEnabled =
       if (finishing) return
       finishing = true
       ui?.close()
+      updater?.close()
       lock.release()
       process.stderr.write(`C2 multi-group · ${result.reason}; platform stopped=${result.platformStopped}; runner drained=${result.drained}\n`,
         () => process.exit(result.code))
@@ -255,8 +257,24 @@ async function startMultiGroupService({ installation, preflightOnly, uiEnabled =
     configControl = require('../src/c2configcontrol').createC2ConfigControl({
       installation, getBindings: () => service.bindings, getHeld: () => service.held,
       assertWriterLock, store,
-      activateRoute: route => service.addRoute(route),
+      activateRoute: route => service.addRoute(route), isFrozen: () => service.inMaintenance,
       log: message => process.stderr.write(`C2 multi-group · ${message}\n`) })
+    if (!preflightOnly) {
+      // Console software updates. Only a launchd job that starts this exact
+      // entry may upgrade, and only while every group is idle and settled.
+      const c2updates = require('../src/c2updater')
+      const pkg = require('../package.json')
+      const upgradeGate = c2updates.createC2UpgradeGate({ isRunning: () => running,
+        service: () => service, capacity, assertJournalScope })
+      updater = c2updates.createC2Updater({ currentVersion: pkg.version,
+        runMode: c2updates.detectRunMode({ privateBuild: pkg.private === true, entry: __filename }),
+        stateFile: path.join(stateDir, 'update.json'), dataDir: stateDir, configPath: cfg._path,
+        gate: upgradeGate, beginMaintenance: () => service.beginMaintenance(),
+        endMaintenance: () => service.endMaintenance(), expectedGroups: () => service.bindings.size,
+        registries: c2updates.registriesFromEnv(),
+        fetchImpl: require('../src/core/proxy').getProxyFetch() || globalThis.fetch,
+        autoCheck: uiEnabled, log: message => process.stderr.write(`C2 update · ${message}\n`) })
+    }
     const stop = reason => { void service.stop(reason, 0).then(finish) }
     onSigint = () => stop('SIGINT')
     onSigterm = () => stop('SIGTERM')
@@ -268,7 +286,7 @@ async function startMultiGroupService({ installation, preflightOnly, uiEnabled =
         getConfig: () => cfg, getBindings: () => service.bindings,
         getHeld: () => service.held, getCapacity: () => capacity.snapshot(),
         getConnHealth: () => liveTransport?.platform.connHealth?.() || {},
-        assertWriterLock, ...configControl,
+        assertWriterLock, ...configControl, updater,
         log: message => process.stderr.write(`Console · ${message}\n`) })
       await new Promise((resolve, reject) => {
         ui.server.once('error', reject)
@@ -287,6 +305,10 @@ async function startMultiGroupService({ installation, preflightOnly, uiEnabled =
     for (const item of started.held || []) {
       process.stderr.write(`SintBot group ${item.chatId} is held: ${item.reason}\n`)
     }
+    // A console upgrade that switched to this version is done once every
+    // group is connected; then the daily version check starts.
+    if (!started.held?.length) updater?.confirmStarted()
+    void updater?.start()
   } catch (error) {
     ui?.close()
     const stopped = await service?.stop('startup-failed', 1)
@@ -297,6 +319,7 @@ async function startMultiGroupService({ installation, preflightOnly, uiEnabled =
     throw error
   } finally {
     if (!running) {
+      updater?.close()
       if (onSigint) process.off('SIGINT', onSigint)
       if (onSigterm) process.off('SIGTERM', onSigterm)
       capacity.close(); lock.release()
@@ -356,6 +379,14 @@ async function main(argv = process.argv.slice(2)) {
     process.stdout.write(HELP)
     return
   }
+  if (sub === 'upgrade-switch') {
+    // Internal: started detached by a console upgrade; never run it by hand.
+    const { values } = parseArgs({ args: rest, allowPositionals: false, options: { state: { type: 'string' } } })
+    if (!values.state || !path.isAbsolute(values.state)) throw new Error('upgrade-switch needs --state <absolute path>')
+    const outcome = await require('../src/c2upgradeswitch').runUpgradeSwitch({ stateFile: values.state })
+    process.exitCode = outcome === 'done' ? 0 : 1
+    return
+  }
   if (!['init', 'start', 'incident'].includes(sub)) {
     throw new Error(`${sub} is unavailable in this release; use sintbot help`)
   }

package/docs/AI-ASSISTED-INSTALL.md

@@ -1,4 +1,4 @@
-# Install SintBot 1.4.1 with an AI assistant
+# Install SintBot 1.4.2 with an AI assistant
 
 English · [简体中文](./zh-CN/AI-ASSISTED-INSTALL.md)
 
@@ -15,5 +15,5 @@ Use the terminal on the Mac that will run SintBot. A cloud shell cannot install
 ## Copyable request
 
 ```text
-Install SintBot 1.4.1 on this Mac using the one-line installation guide. Preserve existing services, configuration, state and Codex or Claude Code account data. Do not expose credentials. Verify the actual installed executable and binary core, configure the Feishu groups with their runners, and initialize only clean new state. Run the foreground preflight and an authorized read-only group test, check the result, then verify clean stop/restart. Stop temporary processes when finished, and distinguish package installation from successful group acceptance.
+Install SintBot 1.4.2 on this Mac using the one-line installation guide. Preserve existing services, configuration, state and Codex or Claude Code account data. Do not expose credentials. Verify the actual installed executable and binary core, configure the Feishu groups with their runners, and initialize only clean new state. Run the foreground preflight and an authorized read-only group test, check the result, then verify clean stop/restart. Stop temporary processes when finished, and distinguish package installation from successful group acceptance.
 ```

package/docs/install.md

@@ -1,4 +1,4 @@
-# Install SintBot 1.4.1
+# Install SintBot 1.4.2
 
 English · [简体中文](./zh-CN/install.md)
 
@@ -10,7 +10,7 @@ You need a Mac, Node.js 22 or newer, and projects stored on that Mac. Install an
 curl -fsSL https://sintbot.com/install.sh | bash
 ```
 
-The installer checks the environment, installs `sintbot@1.4.1` into `~/.local/share/sintbot`, and verifies the entry, built-in core and Feishu module. Continue when you see `Installed and verified SintBot 1.4.1`. No sudo is needed.
+The installer checks the environment, installs `sintbot@1.4.2` into `~/.local/share/sintbot`, and verifies the entry, built-in core and Feishu module. Continue when you see `Installed and verified SintBot 1.4.2`. No sudo is needed.
 
 To preview, append `-s -- --dry-run`. To choose another location, set `SINTBOT_INSTALL_DIR` and adjust the executable paths below.
 
@@ -104,6 +104,8 @@ Messages sent while a task runs are added to that task in Codex groups (`codexSt
 
 With `--ui`, open `http://127.0.0.1:4600` on this Mac. The console shows each group (a paused group shows Needs attention), stops tasks, binds new groups, and switches the model or project folder of an idle group. For LAN access, set a console password in its settings first, then enable LAN access.
 
+Settings → Software updates checks for new releases. In the foreground setup above it shows the upgrade steps: press Ctrl-C and wait for exit, rerun the one-line installer, then start again with the same command. If your own launchd agent starts SintBot, Upgrade now waits until every group is idle and settled, installs the new version into `~/.local/share/sintbot/releases/<version>` and switches the agent to it; if the new version does not connect every group within 90 seconds, the previous one is restored. Upgrades are not announced in groups.
+
 You can also add a group without the console: add it to the configuration, stop the service and run `start` again; the new group is registered automatically. Bound groups cannot be removed or renamed by editing the configuration.
 
 ## Stop and restart

package/docs/zh-CN/AI-ASSISTED-INSTALL.md

@@ -1,4 +1,4 @@
-# 用 AI 助手安装 SintBot 1.4.1
+# 用 AI 助手安装 SintBot 1.4.2
 
 [English](../AI-ASSISTED-INSTALL.md) · 简体中文
 
@@ -15,5 +15,5 @@
 ## 可复制的请求
 
 ```text
-按一行安装指南，在这台 Mac 安装 SintBot 1.4.1。保留已有服务、配置、状态和 Codex 或 Claude Code 账号数据，不输出凭据。验证实际入口与二进制核心，配置飞书群及各群的执行器，只对全新状态初始化。运行前台预检和已授权的只读群测试，对照结果，再验证正常停止与重启。完成后停止临时进程，并区分程序包安装与群验收结果。
+按一行安装指南，在这台 Mac 安装 SintBot 1.4.2。保留已有服务、配置、状态和 Codex 或 Claude Code 账号数据，不输出凭据。验证实际入口与二进制核心，配置飞书群及各群的执行器，只对全新状态初始化。运行前台预检和已授权的只读群测试，对照结果，再验证正常停止与重启。完成后停止临时进程，并区分程序包安装与群验收结果。
 ```

package/docs/zh-CN/install.md

@@ -1,4 +1,4 @@
-# 安装 SintBot 1.4.1
+# 安装 SintBot 1.4.2
 
 [English](../install.md) · 简体中文
 
@@ -10,7 +10,7 @@
 curl -fsSL https://sintbot.com/install.sh | bash
 ```
 
-安装器会自动检查环境，把 `sintbot@1.4.1` 装到 `~/.local/share/sintbot`，并验证程序入口、内置核心和飞书模块。看到 `Installed and verified SintBot 1.4.1` 就可以继续。不需要 sudo。
+安装器会自动检查环境，把 `sintbot@1.4.2` 装到 `~/.local/share/sintbot`，并验证程序入口、内置核心和飞书模块。看到 `Installed and verified SintBot 1.4.2` 就可以继续。不需要 sudo。
 
 可选预览：在命令末尾加 `-s -- --dry-run`。要自定义安装位置，设置 `SINTBOT_INSTALL_DIR` 环境变量，并同步修改后面的可执行文件路径。
 
@@ -104,6 +104,8 @@ SINTBOT="$HOME/.local/share/sintbot/bin/sintbot"
 
 带 `--ui` 启动后，在本机浏览器打开 `http://127.0.0.1:4600`。控制台可以查看各群状态（暂停的群显示「需要处理」）、停止任务、绑定新群、给空闲的群切换模型或项目目录。要从局域网访问，先在控制台的设置里设访问密码，再开启局域网访问。
 
+「设置 → 软件更新」会检查新版本。按上面前台方式运行时，卡片给出升级步骤：按 Ctrl-C 等待退出，重新运行一行安装命令，再用原来的命令启动。如果用你自己的 launchd 后台任务启动 SintBot，「现在升级」会等所有群空闲、记录结清后，把新版本装到 `~/.local/share/sintbot/releases/<版本>` 并切换过去；新版本 90 秒内没连上全部群会自动换回旧版。升级不在群里播报。
+
 不用控制台也能加群：在配置里加上新群，停止后重新 `start` 即可，新群会自动登记。已绑定的群不能通过改配置删除或改名。
 
 ## 停止与重启

package/install.sh

@@ -2,7 +2,7 @@
 # The function is parsed in full before installation starts, including when piped.
 sintbot_install() (
   set -eu
-  version=1.4.1
+  version=1.4.2
   prefix="${SINTBOT_INSTALL_DIR:-$HOME/.local/share/sintbot}"
   fail() { printf 'SintBot: %s\n' "$*" >&2; exit 1; }
   case "${1:-}" in

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sintbot",
-  "version": "1.4.1",
+  "version": "1.4.2",
   "private": false,
   "description": "Drive your Mac projects from Feishu groups with Codex or Claude Code, using a built-in agent core.",
   "bin": {
@@ -63,6 +63,8 @@
     "src/c2migration.js",
     "src/c2multigroupcapacity.js",
     "src/c2multigroupservice.js",
+    "src/c2updater.js",
+    "src/c2upgradeswitch.js",
     "src/cdp.js",
     "src/config.js",
     "src/core/c2cardeffectbridge.js",
@@ -129,6 +131,7 @@
     "src/ui/serverbase.js",
     "src/ui/sessions.js",
     "src/ui/takeover.js",
+    "src/updater.js",
     "src/usage.js"
   ],
   "scripts": {

package/src/c2configcontrol.js

@@ -19,9 +19,9 @@ const RESET_KEYS = ['provider', 'model', 'workdir', 'codexApp']
 // It never moves a journal, settles a receipt or reconnects the platform.
 function createC2ConfigControl({ installation, getBindings, getHeld = () => new Map(),
   assertWriterLock, store = null, activateRoute = null, probeRunner = assertRunnerExecutable,
-  log = () => {} } = {}) {
+  isFrozen = () => false, log = () => {} } = {}) {
   if (!installation?.cfg?._path || typeof getBindings !== 'function' ||
-      typeof getHeld !== 'function' ||
+      typeof getHeld !== 'function' || typeof isFrozen !== 'function' ||
       typeof assertWriterLock !== 'function' ||
       store !== null && typeof store.resetGroupSession !== 'function' ||
       activateRoute !== null && typeof activateRoute !== 'function' ||
@@ -47,6 +47,7 @@ function createC2ConfigControl({ installation, getBindings, getHeld = () => new
   function validateConfig(raw) {
     prepared = null
     held()
+    if (isFrozen()) throw new Error('SintBot is upgrading; settings cannot change until it restarts')
     const next = loadInstallationFromRaw(raw, cfg._path, { dataDir: stateDir,
       allowAddedGroups: !!activateRoute && !!store })
     const bindings = getBindings()

package/src/c2console.js

@@ -17,7 +17,10 @@ const WRITE_PATHS = ['/api/login', '/api/logout', '/api/logout/all',
   '/api/groups/order', '/api/groups/policy', '/api/groups/redact',
   '/api/groups/codex-steer', '/api/groups/pause', '/api/groups/stop',
   '/api/agent', '/api/provider-settings', '/api/codex/verify', '/api/usage/refresh',
-  '/api/inbox/dismiss', '/api/issues/status']
+  '/api/inbox/dismiss', '/api/issues/status',
+  // Software updates: check and ignore anywhere; install only when launchd
+  // manages this exact entry (the updater refuses every other run mode).
+  '/api/update/check', '/api/update/start', '/api/update/ignore']
 const SUPPORTED_RUNNERS = ['claude', 'codex']
 
 function createC2ConsoleFacade({ getBindings, getCapacity, getConfig, getHeld = () => new Map(),
@@ -32,7 +35,7 @@ function createC2ConsoleFacade({ getBindings, getCapacity, getConfig, getHeld =
   const startedAt = now()
   const capabilities = Object.freeze({ mode: 'durable-v2',
     reason: '此操作尚未接入当前版本的持久处理流程，未执行。',
-    summary: '实时状态、认证管理、停止任务、绑定新群，以及空闲群的模型切换（Codex / Claude Code）和项目目录修改已接入；该群有任务或未结记录时不能修改。开新会话、解除绑定、控制台插话、定时任务、画布和升级暂不可用。',
+    summary: '实时状态、认证管理、停止任务、绑定新群、空闲群的模型切换（Codex / Claude Code）和项目目录修改，以及后台运行时的软件升级已接入；该群有任务或未结记录时不能修改。开新会话、解除绑定、控制台插话、定时任务和画布暂不可用。',
     allowed: { GET: READ_PATHS, POST: WRITE_PATHS } })
   function held() {
     if (assertWriterLock() !== true) throw new Error('服务写入权限已失效，操作未执行')
@@ -133,7 +136,7 @@ function createC2Console(options = {}) {
     throw new TypeError('C2 console requires explicit installation paths')
   }
   const facade = createC2ConsoleFacade(options)
-  const ui = createUiServer({ configPath, host, log, getConnHealth,
+  const ui = createUiServer({ configPath, host, log, getConnHealth, updater: options.updater || null,
     onHostChange: options.onHostChange,
     getLiveState: facade.getLiveState, control: facade.control, runtimePolicy: facade,
     issuesPath: path.join(stateDir, 'issues.jsonl'),

package/src/c2multigroupservice.js

@@ -5,6 +5,7 @@ const { coordinateC2GlobalFault } = require('./core/c2globalfault')
 
 const RECOVERING_NOTICE = '上一个任务出错，正在收尾，这条消息没有处理，请稍后重发。'
 const HELD_NOTICE = '本群上一个任务结果不明，已暂停处理，等待人工确认；其他群不受影响。'
+const UPGRADING_NOTICE = 'SintBot 正在升级，这条消息没有处理，请一分钟后重发。'
 const reasonOf = error => String(error?.message || error || 'unknown').slice(0, 300)
 
 // Turns a group binding still holds: a running turn, a non-idle handoff or a
@@ -58,6 +59,8 @@ function createC2MultiGroupService({ routes, assertWriterLock,
   const bindings = new Map()
   // chatId -> { reason, source: 'startup' | 'runtime', since, binding }
   const suspended = new Map()
+  // Set while a console upgrade switches the service: no message is admitted.
+  let maintenance = false
   let transport = null
   let started = false
   let starting = false
@@ -227,7 +230,7 @@ function createC2MultiGroupService({ routes, assertWriterLock,
     if (bindings.has(route.chatId)) return Promise.resolve(bindings.get(route.chatId))
     if (activating.has(route.chatId)) return activating.get(route.chatId)
     const opening = (async () => {
-      if (!started || starting || stopPromise) throw new Error('C2 service is not serving')
+      if (!started || starting || stopPromise || maintenance) throw new Error('C2 service is not serving')
       held()
       const binding = await createBinding({ route, transport })
       if (!started || stopPromise || !writerHeld() || suspended.has(route.chatId) ||
@@ -255,6 +258,10 @@ function createC2MultiGroupService({ routes, assertWriterLock,
     // Foreign/paused group events are not faults and never get a receipt.
     if (!allowed(msg?.chatId)) return { ignored: true, reason: 'unconfigured-or-paused' }
     if (quarantine?.rejects(msg)) return { quarantined: true }
+    if (maintenance && started && !stopPromise) {
+      return answerC2InputRejection({ error: rejectC2Input('C2 service upgrading',
+        { reason: 'upgrading', notice: UPGRADING_NOTICE }), msg, platform: sourceAdapter, log })
+    }
     if (recovering.has(msg.chatId) && started && !stopPromise) {
       // The group's failed turn is being closed; nothing is admitted meanwhile.
       return answerC2InputRejection({ error: rejectC2Input('C2 group recovering',
@@ -319,6 +326,7 @@ function createC2MultiGroupService({ routes, assertWriterLock,
   }
   function recall(event) {
     if (suspended.has(event?.chatId)) return { ignored: true, reason: 'group-held' }
+    if (maintenance) return { ignored: true, reason: 'upgrading' }
     if (!allowed(event?.chatId)) return { ignored: true }
     let binding
     try {
@@ -409,7 +417,16 @@ function createC2MultiGroupService({ routes, assertWriterLock,
     return [...suspended].map(([chatId, entry]) => Object.freeze({ chatId,
       reason: entry.reason, source: entry.source, since: entry.since }))
   }
-  return { start, stop, routeMessage, addRoute, heldGroups,
+  function beginMaintenance() {
+    if (!maintenance) log('upgrade: admission closed for the service switch')
+    maintenance = true
+  }
+  function endMaintenance() {
+    if (maintenance) log('upgrade: admission reopened')
+    maintenance = false
+  }
+  return { start, stop, routeMessage, addRoute, heldGroups, beginMaintenance, endMaintenance,
+    get inMaintenance() { return maintenance },
     get bindings() { return new Map(bindings) },
     get held() { return new Map([...suspended].map(([chatId, entry]) =>
       [chatId, { reason: entry.reason, source: entry.source, since: entry.since }])) } }

package/src/c2updater.js

@@ -0,0 +1,361 @@
+'use strict'
+
+// Software updates for the multi-group service. Checking is read-only. Only a
+// launchd-managed installation upgrades from the console, and only while every
+// group is idle and settled: the exact stable version is installed side by
+// side under the releases directory, then a detached switch process replaces
+// the service entry with the same steps as the deploy scripts and rolls back
+// on any failure. Foreground and development installations get instructions.
+const fs = require('node:fs')
+const os = require('node:os')
+const path = require('node:path')
+const { execFile, execFileSync, spawn } = require('node:child_process')
+const { promisify } = require('node:util')
+const { createHash } = require('node:crypto')
+const { stableVersion, compareVersion, fetchVersion, CHECK_INTERVAL_MS } = require('./updater')
+const { atomicWriteJSON } = require('./core/store')
+
+const PACKAGE = 'sintbot'
+const REGISTRIES = Object.freeze([
+  { registry: 'https://registry.npmjs.org', source: 'npm' },
+  { registry: 'https://registry.npmmirror.com', source: 'mirror' },
+])
+const QUEUE_TIMEOUT_MS = 24 * 60 * 60 * 1000
+const ACTIVE = Object.freeze(['queued', 'installing', 'switching'])
+const LABEL = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/
+const execFileAsync = promisify(execFile)
+
+function readJSON(file) {
+  try {
+    const value = JSON.parse(fs.readFileSync(file, 'utf8'))
+    return value && typeof value === 'object' ? value : {}
+  } catch { return {} }
+}
+
+function readPlist(file, { exec = execFileSync } = {}) {
+  return JSON.parse(exec('/usr/bin/plutil', ['-convert', 'json', '-o', '-', file],
+    { encoding: 'utf8', timeout: 10_000 }))
+}
+
+const real = file => { try { return fs.realpathSync(file) } catch { return null } }
+
+// launchd names its job in XPC_SERVICE_NAME. The job counts as managing this
+// process only when its plist starts this exact entry and launchd reports this
+// exact PID; anything else is a foreground run.
+function detectRunMode({ privateBuild, entry, env = process.env, pid = process.pid,
+  uid = process.getuid?.(), home = os.homedir(), exec = execFileSync } = {}) {
+  if (privateBuild === true) return Object.freeze({ mode: 'dev' })
+  const label = env.XPC_SERVICE_NAME
+  if (typeof label !== 'string' || !LABEL.test(label) || label === '0') {
+    return Object.freeze({ mode: 'foreground' })
+  }
+  const plist = path.join(home, 'Library', 'LaunchAgents', `${label}.plist`)
+  try {
+    const spec = readPlist(plist, { exec })
+    const args = spec.ProgramArguments
+    if (spec.Label !== label || !Array.isArray(args) || args.length < 3 ||
+        !args.every(arg => typeof arg === 'string') ||
+        real(args[1]) === null || real(args[1]) !== real(entry)) {
+      return Object.freeze({ mode: 'foreground', reason: 'launchd entry differs' })
+    }
+    const printed = exec('/bin/launchctl', ['print', `gui/${uid}/${label}`],
+      { encoding: 'utf8', timeout: 10_000 })
+    if (!new RegExp(`^\\s*pid = ${pid}\\s*$`, 'm').test(printed)) {
+      return Object.freeze({ mode: 'foreground', reason: 'launchd pid differs' })
+    }
+    return Object.freeze({ mode: 'managed', label, plist, entry: args[1],
+      logFile: typeof spec.StandardErrorPath === 'string' ? spec.StandardErrorPath : null })
+  } catch {
+    return Object.freeze({ mode: 'foreground', reason: 'launchd job unreadable' })
+  }
+}
+
+function registriesFromEnv(env = process.env) {
+  const custom = env.SINTBOT_UPDATE_REGISTRY
+  if (custom === undefined || custom === '') return REGISTRIES
+  const url = new URL(custom)
+  if (!['http:', 'https:'].includes(url.protocol)) throw new Error('SINTBOT_UPDATE_REGISTRY must be an http(s) URL')
+  return Object.freeze([{ registry: url.href.replace(/\/$/, ''), source: 'custom' }])
+}
+
+function defaultReleasesRoot(env = process.env, home = os.homedir()) {
+  const dir = env.SINTBOT_RELEASES_DIR
+  if (dir !== undefined && dir !== '') {
+    if (!path.isAbsolute(dir) || path.resolve(dir) !== dir) throw new Error('SINTBOT_RELEASES_DIR must be a normalized absolute path')
+    return dir
+  }
+  return path.join(home, '.local', 'share', 'sintbot', 'releases')
+}
+
+const entryOf = prefix => path.join(prefix, 'lib', 'node_modules', PACKAGE, 'bin', 'sintbot-v2.js')
+
+function npmBin() {
+  const sibling = path.join(path.dirname(process.execPath), 'npm')
+  return fs.existsSync(sibling) ? sibling : 'npm'
+}
+
+async function defaultInstallVersion({ version, prefix, registry }) {
+  const env = {}
+  for (const key of ['PATH', 'HOME', 'USER', 'TMPDIR', 'HTTP_PROXY', 'HTTPS_PROXY', 'NO_PROXY',
+    'http_proxy', 'https_proxy', 'no_proxy', 'LANG', 'LC_ALL']) {
+    if (process.env[key] !== undefined) env[key] = process.env[key]
+  }
+  try {
+    await execFileAsync(npmBin(), ['install', '--global', '--prefix', prefix, `--registry=${registry}`,
+      '--omit=dev', '--ignore-scripts', '--no-audit', '--no-fund', `${PACKAGE}@${version}`],
+    { timeout: 10 * 60_000, maxBuffer: 4 * 1024 * 1024, env })
+  } catch (error) {
+    throw new Error(`安装 v${version} 失败（退出码 ${error?.code ?? '未知'}）；没有提权，也没有改用其他版本`)
+  }
+}
+
+// The same verification as the public installer, in a child process so the
+// service never loads modules of another version.
+function defaultVerifyInstall({ version, prefix }) {
+  const root = path.join(prefix, 'lib', 'node_modules', PACKAGE)
+  // Only literal requires in this file: the package builder rejects computed ones.
+  const script = `
+const fs = require('node:fs');
+const path = require('node:path');
+const { pathToFileURL } = require('node:url');
+(async () => {
+  const root = process.argv[1];
+  const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+  if (pkg.name !== 'sintbot' || pkg.version !== process.argv[2] || pkg.private === true ||
+      pkg.bin?.sintbot !== 'bin/sintbot-v2.js') throw new Error('package identity differs');
+  await import(pathToFileURL(path.join(root, 'src/agent/privatecore.js')).href);
+  await import(pathToFileURL(path.join(root, 'src/platform/feishu.js')).href);
+})().catch(() => process.exit(1));`
+  try {
+    execFileSync(process.execPath, ['-e', script, root, version], { timeout: 60_000, stdio: 'ignore', cwd: '/' })
+    const reported = execFileSync(process.execPath, [entryOf(prefix), 'version'],
+      { encoding: 'utf8', timeout: 30_000, cwd: '/' }).trim()
+    if (reported !== version) throw new Error('version differs')
+  } catch {
+    throw new Error(`v${version} 安装后的核对没有通过；新目录保留在 ${prefix}，服务没有切换`)
+  }
+}
+
+function defaultSpawnSwitch({ entry, stateFile }) {
+  const child = spawn(process.execPath, [entry, 'upgrade-switch', '--state', stateFile],
+    { detached: true, stdio: 'ignore', cwd: '/', env: process.env })
+  child.unref()
+  return child.pid
+}
+
+function journalHashes(dataDir) {
+  const out = {}
+  for (const name of fs.readdirSync(dataDir).filter(name => /^c2-v2.*\.log$/.test(name)).sort()) {
+    out[name] = createHash('sha256').update(fs.readFileSync(path.join(dataDir, name))).digest('hex')
+  }
+  return out
+}
+
+function alive(pid) {
+  if (!Number.isSafeInteger(pid) || pid <= 0) return false
+  try { process.kill(pid, 0); return true } catch (error) { return error.code === 'EPERM' }
+}
+
+function createC2Updater({ currentVersion, runMode, stateFile, dataDir, configPath,
+  gate, beginMaintenance = () => {}, endMaintenance = () => {}, expectedGroups = () => 0,
+  registries = REGISTRIES, fetchImpl = globalThis.fetch, releasesRoot = defaultReleasesRoot(),
+  installVersion = defaultInstallVersion, verifyInstall = defaultVerifyInstall,
+  spawnSwitch = defaultSpawnSwitch, hashJournals = journalHashes, isAlive = alive,
+  now = Date.now, waitMs = 5_000, queueTimeoutMs = QUEUE_TIMEOUT_MS,
+  checkIntervalMs = CHECK_INTERVAL_MS, autoCheck = true, log = () => {} } = {}) {
+  if (typeof currentVersion !== 'string' || !runMode || typeof runMode.mode !== 'string' ||
+      typeof stateFile !== 'string' || !path.isAbsolute(stateFile) || typeof gate !== 'function') {
+    throw new TypeError('C2 updater needs the version, run mode, state file and idle gate')
+  }
+  const current = stableVersion(currentVersion)
+  let data = readJSON(stateFile)
+  let timer = null
+  let checking = null
+  let closed = false
+
+  function persist() {
+    try { atomicWriteJSON(stateFile, data, { mode: 0o600 }) } catch (error) { log(`update state: ${error.message}`) }
+  }
+  function setJob(patch, message) {
+    data.job = { ...data.job, ...patch, ...(message ? { message } : {}), updatedAt: now() }
+    persist()
+    return data.job
+  }
+  function fail(message) {
+    setJob({ state: 'failed' }, String(message).slice(0, 300))
+    return status()
+  }
+
+  // A switch that this process did not finish is settled from the evidence:
+  // the new version reached here, the switch process is still working, or it
+  // stopped without writing a result.
+  if (data.job?.state === 'switching' && data.job.to !== current && !isAlive(data.job.helperPid)) {
+    fail('切换过程中断，现场已保留；请检查后重新发起')
+  } else if (data.job?.state === 'installing') {
+    fail('安装被中断，可重新发起升级')
+  }
+
+  // The switch process writes this file too; always act on its latest bytes.
+  function refresh() { data = readJSON(stateFile) }
+  function status() {
+    refresh()
+    const latest = stableVersion(data.latestVersion)
+    const upgradeSupported = runMode.mode === 'managed'
+    return {
+      currentVersion, latestVersion: latest, checkedAt: Number(data.checkedAt) || null,
+      source: data.source || '', ignoredVersion: data.ignoredVersion || '',
+      available: !!current && !!latest && compareVersion(latest, current) > 0 && data.ignoredVersion !== latest,
+      mode: runMode.mode, upgradeSupported, announceSupported: false,
+      job: data.job ? { ...data.job } : null,
+    }
+  }
+
+  async function check() {
+    if (closed) return status()
+    if (checking) return checking
+    checking = (async () => {
+      let lastError = null
+      for (const item of registries) {
+        try {
+          const version = await fetchVersion({ fetchImpl, url: `${item.registry}/${PACKAGE}/latest` })
+          refresh()
+          data.latestVersion = version
+          data.checkedAt = now()
+          data.source = item.source
+          data.registry = item.registry
+          if (data.ignoredVersion && data.ignoredVersion !== version) data.ignoredVersion = ''
+          persist()
+          return status()
+        } catch (error) { lastError = error }
+      }
+      if (lastError) log(`update check unavailable: ${lastError.message || 'network error'}`)
+      return status()
+    })().finally(() => { checking = null })
+    return checking
+  }
+
+  function ignore(version) {
+    refresh()
+    const v = stableVersion(version)
+    if (!v || v !== stableVersion(data.latestVersion)) throw new Error('只能忽略当前检测到的版本')
+    data.ignoredVersion = v
+    persist()
+    return status()
+  }
+
+  function startUpgrade({ version } = {}) {
+    refresh()
+    if (runMode.mode !== 'managed') {
+      throw new Error(runMode.mode === 'dev' ? '开发版请用部署脚本升级' : '前台运行请按卡片上的步骤升级')
+    }
+    const v = stableVersion(version)
+    if (!current || !v || v !== stableVersion(data.latestVersion) || compareVersion(v, current) <= 0) {
+      throw new Error('版本信息已变化，请先重新检查')
+    }
+    if (data.job && ACTIVE.includes(data.job.state)) throw new Error('已有升级正在进行')
+    if (gate().includes('held')) throw new Error('有暂停的群，先处理后再升级')
+    data.job = { id: `${now()}-${Math.random().toString(36).slice(2, 8)}`, state: 'queued',
+      from: current, to: v, registry: data.registry || registries[0].registry,
+      createdAt: now(), updatedAt: now(), message: '等所有群空闲、记录结清后升级' }
+    persist()
+    schedule(0)
+    return status()
+  }
+
+  function schedule(ms = waitMs) {
+    if (closed || timer || data.job?.state !== 'queued') return
+    timer = setTimeout(() => { timer = null; void processQueue() }, ms)
+    timer.unref?.()
+  }
+
+  async function processQueue() {
+    const job = data.job
+    if (closed || job?.state !== 'queued') return status()
+    if (now() - job.createdAt > queueTimeoutMs) return fail('等待群空闲超时；可在空闲后重新发起')
+    const blocked = gate()
+    if (blocked.includes('held')) return fail('有暂停的群，升级已取消；先处理暂停的群')
+    if (blocked.length) { schedule(); return status() }
+    const prefix = path.join(releasesRoot, job.to)
+    if (!job.installed) {
+      setJob({ state: 'installing', prefix }, `正在安装 v${job.to}`)
+      try {
+        if (fs.existsSync(prefix)) {
+          // A directory left by an earlier attempt or a manual install is reused
+          // only when it verifies as exactly this version.
+          await verifyInstall({ version: job.to, prefix })
+        } else {
+          fs.mkdirSync(releasesRoot, { recursive: true, mode: 0o700 })
+          await installVersion({ version: job.to, prefix, registry: job.registry })
+          await verifyInstall({ version: job.to, prefix })
+        }
+      } catch (error) { return fail(error.message) }
+      if (closed) return status()
+      setJob({ state: 'queued', installed: true }, `v${job.to} 已安装，等所有群空闲后切换`)
+    }
+    // Close admission first, then prove idleness once more: nothing can start
+    // between this check and the switch process stopping the service.
+    if (gate().length) { schedule(); return status() }
+    beginMaintenance()
+    const settled = gate()
+    if (settled.length) { endMaintenance(); schedule(); return status() }
+    let hashes
+    try { hashes = hashJournals(dataDir) } catch (error) { endMaintenance(); return fail(`无法读取群记录：${error.message}`) }
+    setJob({ state: 'switching', oldEntry: runMode.entry, newEntry: entryOf(prefix), label: runMode.label,
+      plist: runMode.plist, logFile: runMode.logFile, dataDir, configPath,
+      expectedGroups: expectedGroups(), journals: hashes, servicePid: process.pid,
+      backupDir: path.join(dataDir, 'upgrades', new Date(now()).toISOString().replace(/[:.]/g, '-')),
+      steps: [] }, `正在切换到 v${job.to}；期间的消息会提示稍后重发`)
+    try {
+      const pid = spawnSwitch({ entry: runMode.entry, stateFile })
+      setJob({ helperPid: pid })
+    } catch (error) {
+      endMaintenance()
+      return fail(`切换进程没有启动：${error.message}`)
+    }
+    return status()
+  }
+
+  // The new version marks the switch done only after every group connected.
+  function confirmStarted() {
+    refresh()
+    if (data.job?.state === 'switching' && data.job.to === current) {
+      setJob({ state: 'done', finishedAt: now() }, `已升级到 v${current}`)
+    }
+    return status()
+  }
+
+  if (data.job?.state === 'queued') schedule(0)
+  const checkTimer = autoCheck ? setInterval(() => { void check() }, checkIntervalMs) : null
+  checkTimer?.unref?.()
+  return { status, check, ignore, startUpgrade, processQueue, confirmStarted,
+    start() { return autoCheck ? check() : Promise.resolve(status()) },
+    close() { closed = true; if (checkTimer) clearInterval(checkTimer); if (timer) clearTimeout(timer); timer = null } }
+}
+
+// What keeps a console upgrade from starting: 'not-serving', 'held', 'busy'
+// or 'unsettled'. The updater's own maintenance flag never blocks it, so the
+// final check after admission closes can pass.
+function createC2UpgradeGate({ isRunning, service, capacity, assertJournalScope }) {
+  return () => {
+    const reasons = new Set()
+    const live = service()
+    if (!isRunning() || !live) return ['not-serving']
+    if (live.held.size) reasons.add('held')
+    const shared = capacity.snapshot()
+    if (shared.closed) reasons.add('not-serving')
+    if (shared.active || shared.waiting) reasons.add('busy')
+    for (const [chatId, binding] of live.bindings) {
+      if (binding.gate.blocked) reasons.add('not-serving')
+      for (const rt of binding.engine.rts.values()) {
+        if (rt.v2NormalRouteActive || rt.v2AdmissionPending || rt.v2Controller ||
+            rt.v2QueueReceiptIds?.length) reasons.add('busy')
+      }
+      try { assertJournalScope(binding.journal, chatId, { requireSettled: true }) }
+      catch { reasons.add('unsettled') }
+    }
+    return [...reasons]
+  }
+}
+
+module.exports = { createC2Updater, createC2UpgradeGate, detectRunMode, registriesFromEnv, defaultReleasesRoot,
+  entryOf, journalHashes, readPlist, defaultVerifyInstall, REGISTRIES, PACKAGE }

package/src/c2upgradeswitch.js

@@ -0,0 +1,169 @@
+'use strict'
+
+// Detached switch process started by the console upgrade. It runs outside the
+// service's process group, so stopping the launchd job does not stop it. The
+// steps are those of the deploy scripts: stop the job, wait for the writer
+// lock, prove the journals unchanged, back up data and plist, preflight the
+// new entry with the job's environment, replace only the entry in the plist,
+// start the job and wait for every group to connect. Any failure restores the
+// original plist bytes and restarts the previous version.
+const fs = require('node:fs')
+const path = require('node:path')
+const { execFileSync, spawnSync } = require('node:child_process')
+const { isDeepStrictEqual } = require('node:util')
+const { atomicWriteJSON } = require('./core/store')
+const { journalHashes, readPlist } = require('./c2updater')
+
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms))
+
+function defaultSystem() {
+  const uid = process.getuid()
+  const run = (file, args, options = {}) => spawnSync(file, args, { encoding: 'utf8', timeout: 60_000, ...options })
+  return {
+    bootout: label => run('/bin/launchctl', ['bootout', `gui/${uid}/${label}`]),
+    bootstrap: plist => run('/bin/launchctl', ['bootstrap', `gui/${uid}`, plist]),
+    jobPid: label => {
+      const out = run('/bin/launchctl', ['print', `gui/${uid}/${label}`])
+      if (out.status !== 0) return null
+      const match = /^\s*pid = (\d+)\s*$/m.exec(out.stdout || '')
+      return match ? Number(match[1]) : 0
+    },
+    alive: pid => { try { process.kill(pid, 0); return true } catch (error) { return error.code === 'EPERM' } },
+    readPlist: file => readPlist(file),
+    writePlist: (file, value) => {
+      const json = `${file}.upgrade.json`, tmp = `${file}.upgrade.tmp`
+      fs.writeFileSync(json, JSON.stringify(value), { mode: 0o600 })
+      try {
+        execFileSync('/usr/bin/plutil', ['-convert', 'xml1', '-o', tmp, json], { timeout: 10_000 })
+        fs.chmodSync(tmp, 0o600)
+        execFileSync('/usr/bin/plutil', ['-lint', tmp], { timeout: 10_000, stdio: 'ignore' })
+        fs.renameSync(tmp, file)
+      } finally { fs.rmSync(json, { force: true }); fs.rmSync(tmp, { force: true }) }
+    },
+    backupData: (dataDir, file) => {
+      const base = path.basename(dataDir)
+      const out = run('/usr/bin/tar', ['-czf', file, '--exclude', `${base}/upgrades`, '-C', path.dirname(dataDir), base])
+      if (out.status !== 0) throw new Error(`data backup failed: ${(out.stderr || '').trim().slice(0, 200)}`)
+      fs.chmodSync(file, 0o600)
+    },
+    preflight: (spec, entry) => {
+      const env = { HOME: process.env.HOME, USER: process.env.USER, ...(spec.EnvironmentVariables || {}) }
+      const args = [entry, ...spec.ProgramArguments.slice(2), '--preflight']
+      return run(spec.ProgramArguments[0], args, { env, cwd: '/', timeout: 180_000 })
+    },
+    logSize: file => { try { return fs.statSync(file).size } catch { return 0 } },
+    logSince: (file, offset) => {
+      try {
+        const fd = fs.openSync(file, 'r')
+        try {
+          const size = fs.fstatSync(fd).size
+          if (size <= offset) return ''
+          const buffer = Buffer.alloc(Math.min(size - offset, 4 * 1024 * 1024))
+          fs.readSync(fd, buffer, 0, buffer.length, offset)
+          return buffer.toString('utf8')
+        } finally { fs.closeSync(fd) }
+      } catch { return '' }
+    },
+  }
+}
+
+async function runUpgradeSwitch({ stateFile, system = defaultSystem(), hashJournals = journalHashes,
+  now = Date.now, wait = sleep, stopTimeoutMs = 60_000, connectTimeoutMs = 90_000, pollMs = 500 } = {}) {
+  const read = () => JSON.parse(fs.readFileSync(stateFile, 'utf8'))
+  const state = read()
+  const job = state.job
+  if (job?.state !== 'switching' || typeof job.label !== 'string' || typeof job.plist !== 'string' ||
+      typeof job.oldEntry !== 'string' || typeof job.newEntry !== 'string' ||
+      typeof job.dataDir !== 'string' || typeof job.backupDir !== 'string') {
+    throw new Error('No switching upgrade job to run')
+  }
+  const steps = []
+  const write = (patch, message) => {
+    const latest = read()
+    if (latest.job?.id !== job.id) throw new Error('The upgrade job changed during the switch')
+    latest.job = { ...latest.job, ...patch, ...(message ? { message } : {}), steps: [...steps], updatedAt: now() }
+    atomicWriteJSON(stateFile, latest, { mode: 0o600 })
+    return latest.job
+  }
+  const step = (name, ok = true, detail = '') => {
+    steps.push({ at: now(), step: name, ok, ...(detail ? { detail: String(detail).slice(0, 300) } : {}) })
+    try { write({}) } catch {}
+  }
+  const lockFile = path.join(job.dataDir, 'daemon.lock')
+  const until = async (predicate, ms) => {
+    const end = now() + ms
+    while (now() < end) { if (await predicate()) return true; await wait(pollMs) }
+    return !!(await predicate())
+  }
+  const stopped = () => until(() => {
+    const pid = system.jobPid(job.label)
+    return (pid === null || pid === 0) && !system.alive(job.servicePid) && !fs.existsSync(lockFile)
+  }, stopTimeoutMs)
+  const connected = (offset, expectDone) => until(() => {
+    const text = system.logSince(job.logFile, offset)
+    if (/ held \(|multi-group failure|startup cleanup was not confirmed/.test(text)) return false
+    if (job.expectedGroups > 0 &&
+        text.includes(`SintBot Feishu ingress connected for ${job.expectedGroups} groups`)) return true
+    try { return expectDone && read().job?.state === 'done' } catch { return false }
+  }, connectTimeoutMs)
+
+  fs.mkdirSync(job.backupDir, { recursive: true, mode: 0o700 })
+  const original = fs.readFileSync(job.plist)
+  fs.writeFileSync(path.join(job.backupDir, 'service.plist'), original, { mode: 0o600 })
+  const spec = system.readPlist(job.plist)
+  if (spec.Label !== job.label || spec.ProgramArguments?.[1] !== job.oldEntry) {
+    write({ state: 'failed' }, '服务配置和发起升级时不一致，没有切换')
+    return 'failed'
+  }
+
+  // Restore the exact original plist and start the previous version.
+  async function rollback(reason) {
+    step('rollback', true, reason)
+    system.bootout(job.label)
+    await stopped()
+    fs.writeFileSync(job.plist, original, { mode: 0o600 })
+    const offset = system.logSize(job.logFile)
+    const started = system.bootstrap(job.plist)
+    const back = started.status === 0 && await connected(offset, false)
+    step('previous version started', back)
+    write({ state: back ? 'rolled-back' : 'failed', finishedAt: now() }, back
+      ? `没有切换到 v${job.to}：${reason}；已换回 v${job.from}`
+      : `没有切换到 v${job.to}：${reason}；换回 v${job.from} 后服务没有连上，请手动检查`)
+    return back ? 'rolled-back' : 'failed'
+  }
+
+  const out = system.bootout(job.label)
+  step('stop service', out.status === 0, out.stderr)
+  if (!await stopped()) return rollback('旧服务没有在规定时间内停止')
+  if (!isDeepStrictEqual(hashJournals(job.dataDir), job.journals)) {
+    // A journal changed after the idle check: never switch on top of it.
+    return rollback('停止过程中群记录发生了变化')
+  }
+  step('journals unchanged')
+  try { system.backupData(job.dataDir, path.join(job.backupDir, 'data.tgz')); step('data backed up') }
+  catch (error) { return rollback(error.message) }
+  const check = system.preflight(spec, job.newEntry)
+  step('new version preflight', check.status === 0, (check.stderr || '').trim().split('\n').pop())
+  if (check.status !== 0) return rollback('新版本预检没有通过')
+  const next = { ...spec, ProgramArguments: [...spec.ProgramArguments] }
+  next.ProgramArguments[1] = job.newEntry
+  try {
+    system.writePlist(job.plist, next)
+    const written = system.readPlist(job.plist)
+    const expected = { ...spec, ProgramArguments: next.ProgramArguments }
+    if (!isDeepStrictEqual(written, expected)) throw new Error('rewritten service configuration differs')
+    step('service entry replaced')
+  } catch (error) { return rollback(error.message) }
+  const offset = system.logSize(job.logFile)
+  const started = system.bootstrap(job.plist)
+  step('start new version', started.status === 0, started.stderr)
+  if (started.status !== 0 || !await connected(offset, true)) {
+    return rollback(`新版本启动后没有在 ${Math.round(connectTimeoutMs / 1000)} 秒内连上全部群`)
+  }
+  const latest = read().job
+  if (latest?.state !== 'done') write({ state: 'done', finishedAt: now() }, `已升级到 v${job.to}`)
+  else write({})
+  return 'done'
+}
+
+module.exports = { runUpgradeSwitch, defaultSystem }

package/src/ui/console.html

@@ -2580,7 +2580,7 @@ function cronFullHtml(text){
   }).join('');
 }
 const RUNTIME_UI_TEXT={
-  "summary": "当前支持多群消息、流式卡片回复、忙时跟进、停止任务、状态查看、认证管理、绑定新群，以及空闲群的模型（Codex / Claude Code）和项目目录切换。新会话、解除绑定、控制台插话、定时任务、生图、画布、预览与升级暂不可用。",
+  "summary": "当前支持多群消息、流式卡片回复、忙时跟进、停止任务、状态查看、认证管理、绑定新群、空闲群的模型（Codex / Claude Code）和项目目录切换，以及后台运行时的软件升级。新会话、解除绑定、控制台插话、定时任务、生图、画布与预览暂不可用。",
   "groups": "可绑定新群，修改模型、项目目录、权限、数据输出和忙时跟进；该群须没有进行中的任务和未结记录。切模型或项目会开始新的一段对话。停止任务在「概览」。群里发 /model 也能切换模型。",
   "skills": "当前支持飞书文字消息、忙时跟进、任务回复和停止。定时任务、生图、群消息管理、画布与预览暂未接入。",
   "cron": "当前不执行定时任务；已有定义仅供查看。",
@@ -3485,21 +3485,27 @@ function renderSettings(){
       <div class="hint">代理第一次填,新的对话轮次就生效;改已有的地址要重启后台服务(sintbot service restart)。</div></div>
   </div>`;
   const updateJob=upd&&upd.job;
-  const updateBusy=!!(updateJob&&['queued','installing','restarting','restart-needed'].includes(updateJob.state));
-  const updateText=!upd?'后台版本检查不可用':updateJob?esc(updateJob.message||updateJob.state):upd.available?`检测到新版本 v${esc(upd.latestVersion)} · 当前 v${esc(upd.currentVersion)}`:upd.checkedAt?`当前为最新版本 v${esc(upd.currentVersion)}`:'尚未检查新版';
+  // 1.4.x 多群服务的升级器带 mode:后台托管才能一键升级,前台与开发版只给说明;不在群里播报。
+  const updMode=upd&&upd.mode||'';
+  const updateBusy=!!(updateJob&&['queued','installing','switching','restarting','restart-needed'].includes(updateJob.state));
+  const updCanInstall=!!(upd&&(updMode?upd.upgradeSupported:true));
+  const updateText=!upd?'后台版本检查不可用':updateJob&&updateJob.state!=='done'||updateJob&&!upd.available&&updMode?esc(updateJob.message||updateJob.state):upd.available?`检测到新版本 v${esc(upd.latestVersion)} · 当前 v${esc(upd.currentVersion)}`:updMode==='dev'&&upd.latestVersion?`最新正式版 v${esc(upd.latestVersion)} · 当前开发版 v${esc(upd.currentVersion)}`:upd.checkedAt&&upd.latestVersion?`当前为最新版本 v${esc(upd.currentVersion)}`:upd.checkedAt?'暂时无法确认最新版本':'尚未检查新版';
+  const updHint=updMode==='managed'?'只安装检测到的稳定版本：等所有群空闲、记录结清后装到单独的目录，再切换后台服务；新版本没在 90 秒内连上全部群会自动换回。旧版本保留用于回滚，不提权，不在群里播报。'
+    :updMode==='foreground'?'前台运行不能在控制台升级：在运行 SintBot 的终端按 Ctrl-C 等待退出，重新运行一行安装命令 curl -fsSL https://sintbot.com/install.sh | bash，再用原来的启动命令启动。'
+    :updMode==='dev'?'开发版不在控制台升级，请用部署脚本。':'只安装检测到的稳定版本;所有群任务与队列清空后才会安装。需要可写的全局安装目录,不会提权;后台服务会自动重启,前台运行需手动重启。';
   const updateCard=`<div class="card" style="grid-column:1/-1" id="updateCard"><div class="lbl">软件更新</div>
     <div id="updateStatus" class="hint" style="margin:0 0 12px;color:var(--ink)">${updateText}</div>
     ${upd&&upd.available?`<div class="hint" style="margin:-4px 0 12px">版本差异与发布说明：<a href="https://github.com/sintlab/sintbot/releases/tag/v${encodeURIComponent(upd.latestVersion)}" target="_blank" rel="noopener" style="color:var(--ember-soft)">查看 v${esc(upd.latestVersion)} 发布说明</a></div>`:''}
     <div class="inline" style="gap:14px;flex-wrap:wrap;margin-bottom:12px">
       <span class="dim">自动检查稳定版(启动时及每天)</span>
-      <label class="inline" style="gap:6px;cursor:pointer"><input type="checkbox" id="updAnnounce" ${upd&&upd.announce!==false?'checked':''} style="width:auto"/> <span class="dim">升级后向群里播报(记住选择)</span></label>
+      ${upd&&upd.announceSupported===false?'':`<label class="inline" style="gap:6px;cursor:pointer"><input type="checkbox" id="updAnnounce" ${upd&&upd.announce!==false?'checked':''} style="width:auto"/> <span class="dim">升级后向群里播报(记住选择)</span></label>`}
     </div>
     <div class="inline" style="gap:8px;flex-wrap:wrap">
       <button class="btn" id="updCheck" ${!upd?'disabled':''}>检查新版</button>
-      <button class="btn primary" id="updInstall" ${!upd||!upd.available||updateBusy?'disabled':''}>现在升级</button>
+      ${updCanInstall?`<button class="btn primary" id="updInstall" ${!upd||!upd.available||updateBusy?'disabled':''}>现在升级</button>`:''}
       <button class="btn" id="updIgnore" ${!upd||!upd.available?'disabled':''}>忽略此版本</button>
     </div>
-    <div class="hint" style="margin-top:10px">只安装检测到的稳定版本;所有群任务与队列清空后才会安装。需要可写的全局安装目录,不会提权;后台服务会自动重启,前台运行需手动重启。</div>
+    <div class="hint" style="margin-top:10px">${updHint}</div>
     <div class="update-history"><div class="subhead">版本历史</div>
       <div id="verhistBox"><div class="empty">加载中…</div></div></div>
   </div>`;
@@ -3547,18 +3553,19 @@ function renderSettings(){
     }catch(e){toast(e.message,'err');b.disabled=false;}
   };
   const saveUpdatePrefs=async(patch)=>{try{S=await api('/api/ui/update-settings','POST',patch);renderSettings();}catch(e){toast(e.message,'err');}};
-  $('#updAnnounce').onchange=()=>saveUpdatePrefs({announce:$('#updAnnounce').checked});
+  if($('#updAnnounce'))$('#updAnnounce').onchange=()=>saveUpdatePrefs({announce:$('#updAnnounce').checked});
   $('#updCheck').onclick=async()=>{const b=$('#updCheck');b.disabled=true;b.textContent='检查中…';
     try{await api('/api/update/check','POST',{});S=await api('/api/state');await refreshInbox();renderSettings();renderOverview();toast('版本检查完成','ok');}
     catch(e){toast(e.message,'err');b.disabled=false;b.textContent='检查新版';}};
-  $('#updInstall').onclick=async()=>{const u=S.update||{},version=u.latestVersion;if(!version)return;
-    const announce=$('#updAnnounce').checked;
-    if(!confirm(`将从 v${u.currentVersion} 升级到 v${version}。${announce?'安装完成后会向未暂停的群播报；':'本次不向群播报。'}所有群任务结束后才开始安装，后台服务会重启。继续?`))return;
+  if($('#updInstall'))$('#updInstall').onclick=async()=>{const u=S.update||{},version=u.latestVersion;if(!version)return;
+    const announce=$('#updAnnounce')?$('#updAnnounce').checked:false;
+    const what=u.mode==='managed'?'等所有群空闲、记录结清后装到单独的目录，再切换后台服务；切换期间约一分钟不处理新消息，新版本没连上全部群会自动换回。':`${announce?'安装完成后会向未暂停的群播报；':'本次不向群播报。'}所有群任务结束后才开始安装，后台服务会重启。`;
+    if(!confirm(`将从 v${u.currentVersion} 升级到 v${version}。${what}继续?`))return;
     const b=$('#updInstall');b.disabled=true;
-    try{const r=await api('/api/update/start','POST',{version,announce});S.update={...r,announce};await refreshInbox();renderSettings();renderOverview();toast('更新已排队，群任务空闲后开始','ok');}
+    try{const r=await api('/api/update/start','POST',{version,announce});S.update={...r,announce};await refreshInbox();renderSettings();renderOverview();toast(u.mode==='managed'?'升级已排队，所有群空闲后开始':'更新已排队，群任务空闲后开始','ok');}
     catch(e){toast(e.message,'err');b.disabled=false;}};
   $('#updIgnore').onclick=async()=>{const version=(S.update||{}).latestVersion;if(!version)return;
-    try{const r=await api('/api/update/ignore','POST',{version});S.update={...r,announce:$('#updAnnounce').checked};await refreshInbox();renderSettings();renderOverview();toast('已忽略此版本','ok');}
+    try{const r=await api('/api/update/ignore','POST',{version});S.update={...r,announce:$('#updAnnounce')?$('#updAnnounce').checked:false};await refreshInbox();renderSettings();renderOverview();toast('已忽略此版本','ok');}
     catch(e){toast(e.message,'err');}};
   // 只开着控制台的守护进程(还没接平台):第一次接上平台时说一句接下来会发生什么(服务托管的会自己重启连上)
   {const pl=S.platforms||{};if(S.setupMode&&(pl.feishu||pl.slack||pl.wecom)&&!window._sbRestartToast){window._sbRestartToast=1;toast(S.setupMode.supervised?'已接上聊天平台 —— 后台服务几秒后自动重启并连上':'已接上聊天平台 —— 在终端里重启 sintbot start --ui 连上','ok');}}
@@ -4032,7 +4039,7 @@ updateThemeBtn();
 const I18N_EN=[
   ["需要处理", "Needs attention"],
   ["当前可用操作", "Available controls"],
-  ["当前支持多群消息、流式卡片回复、忙时跟进、停止任务、状态查看、认证管理、绑定新群，以及空闲群的模型（Codex / Claude Code）和项目目录切换。新会话、解除绑定、控制台插话、定时任务、生图、画布、预览与升级暂不可用。", "Available: group messages, streaming reply cards, busy-turn followups, stopping tasks, live status, authentication, binding new groups, and switching the model (Codex / Claude Code) or project of an idle group. New sessions, unbinding, console messages, schedules, image generation, canvas, previews and upgrades are unavailable."],
+  ["当前支持多群消息、流式卡片回复、忙时跟进、停止任务、状态查看、认证管理、绑定新群、空闲群的模型（Codex / Claude Code）和项目目录切换，以及后台运行时的软件升级。新会话、解除绑定、控制台插话、定时任务、生图、画布与预览暂不可用。", "Available: group messages, streaming reply cards, busy-turn followups, stopping tasks, live status, authentication, binding new groups, switching the model (Codex / Claude Code) or project of an idle group, and software upgrades in a background run. New sessions, unbinding, console messages, schedules, image generation, canvas and previews are unavailable."],
   ["可绑定新群，修改模型、项目目录、权限、数据输出和忙时跟进；该群须没有进行中的任务和未结记录。切模型或项目会开始新的一段对话。停止任务在「概览」。群里发 /model 也能切换模型。", "Bind new groups and change the model, project folder, permissions, data display and busy-turn followups of a group with no running task or unsettled record. Changing the model or project starts a new conversation. Stop tasks in Overview. Members can also switch models with /model in the group."],
   ["当前支持飞书文字消息、忙时跟进、任务回复和停止。定时任务、生图、群消息管理、画布与预览暂未接入。", "Feishu text messages, busy-turn followups, task replies and stopping are supported. Schedules, image generation, group message management, canvas and previews are unavailable."],
   ["当前不执行定时任务；已有定义仅供查看。", "Schedules are not executed. Existing definitions are shown for reference only."],
@@ -4765,6 +4772,11 @@ const I18N_EN=[
   ["更新已排队，群任务空闲后开始","Update queued; installation will start when all group tasks are idle"],
   ["已忽略此版本","This version was ignored"],
   ["版本检查完成","Version check complete"],
+  ["暂时无法确认最新版本","The latest version could not be confirmed yet"],
+  ["升级已排队，所有群空闲后开始","Upgrade queued; it starts when every group is idle"],
+  ["只安装检测到的稳定版本：等所有群空闲、记录结清后装到单独的目录，再切换后台服务；新版本没在 90 秒内连上全部群会自动换回。旧版本保留用于回滚，不提权，不在群里播报。","Installs only the detected stable version: once every group is idle and settled, it goes into its own folder and the background service switches to it; if the new version does not connect every group within 90 seconds, the previous one is restored. The previous version is kept for rollback. No elevated privileges and no group announcements."],
+  ["前台运行不能在控制台升级：在运行 SintBot 的终端按 Ctrl-C 等待退出，重新运行一行安装命令 curl -fsSL https://sintbot.com/install.sh | bash，再用原来的启动命令启动。","A foreground run cannot upgrade from the console: press Ctrl-C in the terminal running SintBot and wait for it to exit, rerun the one-line installer curl -fsSL https://sintbot.com/install.sh | bash, then start with your usual command."],
+  ["开发版不在控制台升级，请用部署脚本。","Development builds are not upgraded from the console; use the deployment scripts."],
   ["访问地址正在切换;页面即将重载","Changing the access address; this page will reload"],
   ["访问设置已保存","Access settings saved"],
   ["开启局域网访问前要设置至少 6 位访问密码","Set an access password of at least 6 characters before enabling LAN access"],
@@ -5380,16 +5392,25 @@ const I18N_EN_RX=[
   [/^登录失败 \(HTTP (\d+)\)$/,"Sign-in failed (HTTP $1)"],
   [/^检测到新版本 v([\d.]+) · 当前 v([\d.]+)$/,"New version v$1 · current v$2"],
   [/^当前为最新版本 v([\d.]+)$/,"v$1 is the latest version"],
+  [/^最新正式版 v([\d.]+) · 当前开发版 v(\S+)$/,"Latest release v$1 · this development build v$2"],
   [/^等待所有群任务结束后更新$/,"Waiting for all group tasks to finish"],
   [/^正在检查安装位置并安装指定版本$/,"Checking the install location and installing the selected version"],
   [/^已安装，正在重启后台服务$/,"Installed; restarting the background service"],
   [/^已安装新版；后台服务未能自动重启，请手动重启$/,"The new version is installed, but the background service did not restart; restart it manually"],
   [/^已安装新版；当前不是受托管服务，请手动重启 SintBot$/,"The new version is installed; restart SintBot manually"],
   [/^更新完成并已重启$/,"Update completed and restarted"],
+  [/^等所有群空闲、记录结清后升级$/,"Waiting until every group is idle and settled"],
+  [/^正在安装 v([\d.]+)$/,"Installing v$1"],
+  [/^v([\d.]+) 已安装，等所有群空闲后切换$/,"v$1 is installed; switching when every group is idle"],
+  [/^正在切换到 v([\d.]+)；期间的消息会提示稍后重发$/,"Switching to v$1; messages meanwhile are asked to be resent later"],
+  [/^已升级到 v([\d.]+)$/,"Upgraded to v$1"],
+  [/^没有切换到 v([\d.]+)：([\s\S]*)；已换回 v([\d.]+)$/,"Did not switch to v$1 ($2); v$3 was restored"],
+  [/^等待群空闲超时；可在空闲后重新发起$/,"Timed out waiting for idle groups; retry when they are idle"],
+  [/^有暂停的群，升级已取消；先处理暂停的群$/,"A group is paused, so the upgrade was cancelled; handle the paused group first"],
   [/^更新后未能自动重启，请手动重启服务$/,"The update could not restart automatically; restart the service manually"],
   [/^等待群任务结束超时；可在任务空闲后重新发起$/,"Timed out waiting for group tasks; retry when they are idle"],
   [/^当前运行的是开发目录或非全局副本；请在终端手动更新$/,"This is a development or non-global install; update it from a terminal"],
-  [/^将从 v([\d.]+) 升级到 v([\d.]+)。([\s\S]*)$/,(a,from,to,what)=>`Upgrade from v${from} to v${to}. ${what.replace('所有群任务结束后才开始安装，后台服务会重启。','Installation waits until all group tasks finish, then restarts the background service.').replace('本次不向群播报。','This update will not be announced in groups.').replace('安装完成后会向未暂停的群播报；','After installation, it will be announced in active groups;')}`],
+  [/^将从 v([\d.]+) 升级到 v([\d.]+)。([\s\S]*)$/,(a,from,to,what)=>`Upgrade from v${from} to v${to}. ${what.replace('等所有群空闲、记录结清后装到单独的目录，再切换后台服务；切换期间约一分钟不处理新消息，新版本没连上全部群会自动换回。','Once every group is idle and settled, it installs into its own folder and switches the background service; new messages wait about a minute during the switch, and the previous version is restored if the new one does not connect every group. ').replace('所有群任务结束后才开始安装，后台服务会重启。','Installation waits until all group tasks finish, then restarts the background service.').replace('本次不向群播报。','This update will not be announced in groups.').replace('安装完成后会向未暂停的群播报；','After installation, it will be announced in active groups;')}`],
 ];
 /* I18N_DICT_END */
 
@@ -5590,7 +5611,7 @@ async function fetchCodexModels(){if(CX_MODELS)return CX_MODELS;try{CX_MODELS=aw
 function cxDefEffortLabel(model){const m=CX_MODELS&&(CX_MODELS.models||[]).find(x=>x.model===model);return '默认'+(m&&m.defEffort?'('+m.defEffort+')':'');}
 /* 有 codex provider 时启动即预热模型列表(server 缓存 10min)→ 卡片默认档标注补齐 + 面板秒开 */
 function warmCodexModels(){if(!CX_MODELS&&S&&(S.providers||[]).some(x=>x.runner==='codex'&&!x.hidden))fetchCodexModels().then(()=>renderProviders());}
-const RUNTIME_DISABLED_SELECTORS='[data-osay],[data-onew],.gpv,[data-rm],[data-gcfg],[data-cronnew],[data-cronadd],[data-crontgl],[data-cronrm],[data-reposave],[data-repotest],[data-iconuse],[data-iconsys],[data-iconstyle],[data-stylecollect],#mNewChat,#addModel,.pcard [data-act="edit"],.pcard [data-act="test"],#amSave,#amDel,#mNewGo,#pgSend,#pgNew,#fSave,#slSave,#wSave,#bSave,#styleNew,[data-styleedit],[data-styledup],[data-styledel],#nsSave,#nsExtract,#clSave,#updCheck,#updInstall,#updIgnore,[data-pvstop],[data-lvkill],[data-lvkillall]';
+const RUNTIME_DISABLED_SELECTORS='[data-osay],[data-onew],.gpv,[data-rm],[data-gcfg],[data-cronnew],[data-cronadd],[data-crontgl],[data-cronrm],[data-reposave],[data-repotest],[data-iconuse],[data-iconsys],[data-iconstyle],[data-stylecollect],#mNewChat,#addModel,.pcard [data-act="edit"],.pcard [data-act="test"],#amSave,#amDel,#mNewGo,#pgSend,#pgNew,#fSave,#slSave,#wSave,#bSave,#styleNew,[data-styleedit],[data-styledup],[data-styledel],#nsSave,#nsExtract,#clSave,[data-pvstop],[data-lvkill],[data-lvkillall]';
 function disableRuntimeControl(el,reason){
   el.disabled=true;el.title=trText(reason);el.dataset.runtimeDisabled='1';
   el.setAttribute('aria-disabled','true');

package/src/updater.js

@@ -0,0 +1,243 @@
+// Stable-version checks and guarded in-place upgrades for the global package.
+// Checking is read-only. Installation is explicit, exact-version only, waits for
+// every group queue to drain, and never escalates privileges.
+
+const fs = require('node:fs')
+const path = require('node:path')
+const { execFile } = require('node:child_process')
+const { promisify } = require('node:util')
+const { atomicWriteJSON } = require('./core/store')
+
+const execFileAsync = promisify(execFile)
+const PACKAGE = 'sintbot'
+const REGISTRIES = [
+  { url: 'https://registry.npmjs.org/sintbot/latest', source: 'npm' },
+  { url: 'https://registry.npmmirror.com/sintbot/latest', source: 'mirror' },
+]
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000
+const CHECK_TIMEOUT_MS = 10_000
+const QUEUE_TIMEOUT_MS = 24 * 60 * 60 * 1000
+
+function stableVersion(value) {
+  const s = String(value || '').trim().replace(/^v/, '')
+  return /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/.test(s) ? s : null
+}
+
+function compareVersion(a, b) {
+  const av = stableVersion(a); const bv = stableVersion(b)
+  if (!av || !bv) return 0
+  const aa = av.split('.').map(BigInt); const bb = bv.split('.').map(BigInt)
+  for (let i = 0; i < 3; i++) if (aa[i] !== bb[i]) return aa[i] > bb[i] ? 1 : -1
+  return 0
+}
+
+function hasPendingWork(live) {
+  // Updating while the engine is missing or its snapshot is incomplete is unsafe:
+  // a busy group could be hidden by a failed state read. Treat unknown as busy.
+  if (!live || live.running !== true || !Number.isFinite(Number(live.queue)) || !live.groups || typeof live.groups !== 'object') return true
+  if (Number(live.queue) > 0) return true
+  return Object.values(live.groups).some((g) => !g || g.busy || !Number.isFinite(Number(g.queue)) || Number(g.queue) > 0)
+}
+
+async function fetchVersion({ fetchImpl = globalThis.fetch, url, timeoutMs = CHECK_TIMEOUT_MS } = {}) {
+  const ac = new AbortController()
+  const timer = setTimeout(() => ac.abort(), timeoutMs)
+  try {
+    const res = await fetchImpl(url, { headers: { accept: 'application/json' }, signal: ac.signal, redirect: 'error' })
+    if (!res || !res.ok) throw new Error(`HTTP ${res && res.status || 'error'}`)
+    const data = await res.json()
+    const version = stableVersion(data && (data.version || (data['dist-tags'] && data['dist-tags'].latest)))
+    if (!version) throw new Error('registry returned no stable version')
+    return version
+  } finally { clearTimeout(timer) }
+}
+
+function readState(file) {
+  try {
+    const v = JSON.parse(fs.readFileSync(file, 'utf8'))
+    return v && typeof v === 'object' ? v : {}
+  } catch { return {} }
+}
+
+function createUpdater({
+  currentVersion,
+  stateFile,
+  getLiveState = () => null,
+  fetchImpl = globalThis.fetch,
+  registries = REGISTRIES,
+  now = Date.now,
+  waitMs = 5000,
+  queueTimeoutMs = QUEUE_TIMEOUT_MS,
+  checkIntervalMs = CHECK_INTERVAL_MS,
+  isGlobalInstall = defaultGlobalInstall,
+  installExact = defaultInstallExact,
+  readInstalledVersion = defaultReadInstalledVersion,
+  getManagedService = () => false,
+  restartManagedService = async () => ({ ok: false }),
+  setAnnouncementBaseline = () => {},
+  log = () => {},
+} = {}) {
+  const file = stateFile || path.join(require('node:os').homedir(), '.sbot', 'update.json')
+  const current = stableVersion(currentVersion) || '0.0.0'
+  let data = readState(file)
+  let queueTimer = null
+  let checking = null
+  let closed = false
+
+  // If a previous daemon was replaced during the restart step, the new package
+  // version is the evidence that installation and restart both completed.
+  if (data.job && data.job.state === 'restarting') {
+    data.job = data.job.to === current
+      ? { ...data.job, state: 'done', message: '更新完成并已重启', updatedAt: now() }
+      : { ...data.job, state: 'failed', message: '更新后未能自动重启，请手动重启服务', updatedAt: now() }
+    persist()
+  }
+
+  function persist() { try { atomicWriteJSON(file, data, { mode: 0o600 }) } catch (e) { log('update state: ' + (e && e.message)) } }
+  function status() {
+    const latest = stableVersion(data.latestVersion)
+    return {
+      currentVersion: current,
+      latestVersion: latest,
+      checkedAt: Number(data.checkedAt) || null,
+      source: data.source || '',
+      ignoredVersion: data.ignoredVersion || '',
+      available: !!latest && compareVersion(latest, current) > 0 && data.ignoredVersion !== latest,
+      job: data.job ? { ...data.job } : null,
+    }
+  }
+
+  async function check() {
+    if (closed) return status()
+    if (checking) return checking
+    checking = (async () => {
+      let lastError = null
+      for (const r of registries) {
+        try {
+          const version = await fetchVersion({ fetchImpl, url: r.url })
+          data.latestVersion = version
+          data.checkedAt = now()
+          data.source = r.source || ''
+          if (data.ignoredVersion && data.ignoredVersion !== version) data.ignoredVersion = ''
+          persist()
+          return status()
+        } catch (e) { lastError = e }
+      }
+      // Network errors are deliberately quiet and never erase the last success.
+      if (lastError) log('update check unavailable: ' + (lastError && lastError.message || 'network error'))
+      return status()
+    })().finally(() => { checking = null })
+    return checking
+  }
+
+  function ignore(version) {
+    const v = stableVersion(version)
+    if (!v || v !== stableVersion(data.latestVersion)) throw new Error('只能忽略当前检测到的版本')
+    data.ignoredVersion = v
+    persist()
+    return status()
+  }
+
+  function startUpgrade({ version, announce = true } = {}) {
+    const v = stableVersion(version)
+    if (!v || v !== stableVersion(data.latestVersion) || compareVersion(v, current) <= 0) throw new Error('版本信息已变化，请先重新检查')
+    if (data.job && ['queued', 'installing', 'restarting', 'restart-needed'].includes(data.job.state)) throw new Error('已有更新需要完成或重启后再试')
+    data.job = { id: `${now()}-${Math.random().toString(36).slice(2, 8)}`, state: 'queued', from: current, to: v,
+      announce: announce !== false, createdAt: now(), updatedAt: now(), message: '等待所有群任务结束后更新' }
+    persist()
+    void processQueue()
+    return status()
+  }
+
+  function scheduleQueueCheck() {
+    if (closed || queueTimer || !data.job || data.job.state !== 'queued') return
+    queueTimer = setTimeout(() => { queueTimer = null; void processQueue() }, waitMs)
+    if (queueTimer.unref) queueTimer.unref()
+  }
+
+  async function processQueue() {
+    const job = data.job
+    if (closed || !job || job.state !== 'queued') return
+    if (now() - job.createdAt > queueTimeoutMs) {
+      data.job = { ...job, state: 'failed', message: '等待群任务结束超时；可在任务空闲后重新发起', updatedAt: now() }
+      persist(); return
+    }
+    let live
+    try { live = getLiveState() }
+    catch (e) { log('update queue: live state unavailable: ' + (e && e.message)); return scheduleQueueCheck() }
+    if (hasPendingWork(live)) return scheduleQueueCheck()
+    if (queueTimer) { clearInterval(queueTimer); queueTimer = null }
+    data.job = { ...job, state: 'installing', message: '正在检查安装位置并安装指定版本', updatedAt: now() }
+    persist()
+    try {
+      const checkResult = await isGlobalInstall()
+      if (!checkResult || !checkResult.ok) throw new Error((checkResult && checkResult.reason) || '当前运行位置不是可写的全局安装')
+      const result = await installExact(PACKAGE, job.to, checkResult)
+      if (!result || result.ok === false) throw new Error((result && result.reason) || '安装失败；检查包管理器日志后可手动重试')
+      const installed = await readInstalledVersion(checkResult)
+      if (stableVersion(installed) !== job.to) throw new Error('安装完成后的版本核对不符；请手动检查后重启')
+      if (!job.announce) { try { setAnnouncementBaseline(job.to) } catch (e) { log('update announcement baseline: ' + (e && e.message)) } }
+      const managed = await getManagedService()
+      if (managed) {
+        data.job = { ...job, state: 'restarting', message: '已安装，正在重启后台服务', updatedAt: now() }
+        persist()
+        const restarted = await restartManagedService()
+        if (restarted && restarted.ok) return status()
+        data.job = { ...job, state: 'restart-needed', message: '已安装新版；后台服务未能自动重启，请手动重启', updatedAt: now() }
+      } else {
+        data.job = { ...job, state: 'restart-needed', message: '已安装新版；当前不是受托管服务，请手动重启 SintBot', updatedAt: now() }
+      }
+      persist()
+    } catch (e) {
+      data.job = { ...job, state: 'failed', message: String(e && e.message || e).slice(0, 300), updatedAt: now() }
+      persist()
+    }
+    return status()
+  }
+
+  if (data.job && data.job.state === 'queued') void processQueue()
+  const checkTimer = setInterval(() => { void check() }, checkIntervalMs)
+  if (checkTimer.unref) checkTimer.unref()
+
+  return {
+    status,
+    check,
+    ignore,
+    startUpgrade,
+    start() { return check() },
+    close() { closed = true; clearInterval(checkTimer); if (queueTimer) clearTimeout(queueTimer); queueTimer = null },
+  }
+}
+
+function defaultGlobalInstall() {
+  const { execFileSync } = require('node:child_process')
+  const rootOut = execFileSync('npm', ['root', '-g'], { encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'pipe'] }).trim()
+  const globalRoot = fs.realpathSync(rootOut)
+  const globalPackage = path.join(globalRoot, PACKAGE)
+  const runningPackage = fs.realpathSync(path.resolve(__dirname, '..'))
+  if (runningPackage !== fs.realpathSync(globalPackage)) return { ok: false, reason: '当前运行的是开发目录或非全局副本；请在终端手动更新' }
+  fs.accessSync(globalRoot, fs.constants.W_OK | fs.constants.X_OK)
+  fs.accessSync(path.dirname(globalPackage), fs.constants.W_OK | fs.constants.X_OK)
+  return { ok: true, globalRoot, globalPackage }
+}
+
+async function defaultInstallExact(name, version) {
+  const env = {}
+  const allowed = ['PATH', 'HOME', 'USERPROFILE', 'APPDATA', 'LOCALAPPDATA', 'TEMP', 'TMP', 'SystemRoot', 'PATHEXT',
+    'HTTP_PROXY', 'HTTPS_PROXY', 'NO_PROXY', 'http_proxy', 'https_proxy', 'no_proxy', 'LANG', 'LC_ALL']
+  for (const k of allowed) if (process.env[k] !== undefined) env[k] = process.env[k]
+  const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm'
+  try {
+    await execFileAsync(npm, ['install', '--global', `${name}@${version}`, '--omit=dev', '--no-audit', '--no-fund'],
+      { timeout: 10 * 60 * 1000, maxBuffer: 2 * 1024 * 1024, windowsHide: true, env })
+    return { ok: true }
+  } catch (e) {
+    return { ok: false, reason: `安装失败(退出码 ${e && e.code != null ? e.code : '未知'})；未提权，也未改用其他版本` }
+  }
+}
+
+function defaultReadInstalledVersion(info) {
+  try { return JSON.parse(fs.readFileSync(path.join(info.globalPackage, 'package.json'), 'utf8')).version || null } catch { return null }
+}
+
+module.exports = { PACKAGE, REGISTRIES, CHECK_INTERVAL_MS, stableVersion, compareVersion, hasPendingWork, fetchVersion, createUpdater, defaultGlobalInstall, defaultInstallExact, defaultReadInstalledVersion }