@simonyea/holysheep-cli 2.1.9 → 2.1.11

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@simonyea/holysheep-cli",
-  "version": "2.1.9",
+  "version": "2.1.11",
   "description": "Claude Code/Cursor/Cline API relay for China — ¥1=$1, WeChat/Alipay payment, no credit card, no VPN. One command setup for all AI coding tools.",
   "scripts": {
-    "test": "node tests/droid.test.js && node tests/workspace-store.test.js",
+    "test": "node tests/droid.test.js && node tests/workspace-store.test.js && node tests/runtime-stale-upgrade.test.js",
     "prepublishOnly": "node scripts/check-tarball-size.js"
   },
   "keywords": [

package/src/commands/webui.js

@@ -113,34 +113,45 @@ function autoInstallBun(logger) {
 }
 
 // ── Runtime resolution ───────────────────────────────────────────────────────
-// Priority:
-//   1. Local dev checkout at ../aionui-fork/dist-server (developer building locally)
-//   2. Installed runtime at ~/.holysheep/aionui-runtime/dist-server
-//   3. If --setup-runtime + HOLYSHEEP_AIONUI_RUNTIME_URL, download into (2)
-//   4. null → fall back to legacy workspace
-function resolveAionUiRuntimeDir() {
-  // (1) Dev checkout — if holysheep-cli was cloned and `bun run build` ran in aionui-fork
-  const repoRoot = path.resolve(__dirname, '..', '..')
-  const devRuntime = path.join(repoRoot, 'aionui-fork')
-  if (fs.existsSync(path.join(devRuntime, 'dist-server', 'server.mjs'))) {
-    return { dir: devRuntime, source: 'dev-checkout' }
-  }
-  // (2) User-installed runtime
-  const home = process.env.HOME || process.env.USERPROFILE
-  if (home) {
-    const installed = path.join(home, '.holysheep', 'aionui-runtime')
-    if (fs.existsSync(path.join(installed, 'dist-server', 'server.mjs'))) {
-      return { dir: installed, source: 'installed' }
+// This file used to have its own "does `server.mjs` exist?" resolver and
+// short-circuit before the fetcher was ever consulted. That's why earlier
+// releases' version-drift detection (added in `aionui-runtime-fetcher.js`)
+// never kicked in — we never called it. Now the single source of truth is
+// `resolveRuntime()` from the fetcher module, with stale detection + atomic
+// upgrade baked in. We just call it twice:
+//   * Once synchronously-shaped (allowDownload:false) for the "[mode=…]"
+//     status line so we don't incur a network hit just to print a label.
+//   * Once with allowDownload:true inside startAionUiMode, where we're
+//     willing to pay the ~20MB download to get a fresh runtime.
+async function resolveAionUiRuntime({ allowDownload, logger = () => {} } = {}) {
+  const { resolveRuntime } = require('../webui/aionui-runtime-fetcher')
+  return resolveRuntime({ allowDownload: !!allowDownload, logger })
+}
+
+// Cheap probe for the status line. No download, never blocks.
+function probeAionUiRuntimeLabel() {
+  try {
+    const {
+      USER_CACHE_DIR,
+      VENDOR_DIR,
+      isValidRuntimeDir,
+      isVersionCurrent,
+    } = require('../webui/aionui-runtime-fetcher')
+
+    const forkDir = path.resolve(__dirname, '..', '..', 'aionui-fork')
+    if (isValidRuntimeDir(forkDir)) return 'aionui-fork'
+    if (isValidRuntimeDir(VENDOR_DIR)) return 'vendor'
+    if (isValidRuntimeDir(USER_CACHE_DIR)) {
+      return isVersionCurrent(USER_CACHE_DIR) ? 'installed' : 'installed-stale'
     }
-  }
-  return null
+  } catch {}
+  return 'none'
 }
 
 async function downloadAionUiRuntime(logger) {
   // Fetcher has a baked-in default URL + SHA256 — no env var required.
   // HOLYSHEEP_AIONUI_RUNTIME_URL still works as an override.
-  const { resolveRuntime } = require('../webui/aionui-runtime-fetcher')
-  return resolveRuntime({ allowDownload: true, logger })
+  return resolveAionUiRuntime({ allowDownload: true, logger })
 }
 
 // ── HolySheep config → API key ───────────────────────────────────────────────
@@ -345,20 +356,47 @@ function spawnAionUiServer({ bunPath, runtimeDir, port }) {
 async function startAionUiMode(opts) {
   const port = Number(opts.port) || 9876
 
-  // 1. Resolve runtime. First launch after `npm i -g` won't have one locally
-  // — we auto-download from the baked-in URL (verified by SHA256) unless the
-  // user opts out via HOLYSHEEP_WEBUI_NO_AUTOFETCH=1.
-  let runtime = resolveAionUiRuntimeDir()
+  // 1. Resolve runtime. Fetcher returns one of:
+  //   source='user-cache'        → version matches baked-in DEFAULT_RUNTIME_VERSION
+  //   source='user-cache-stale'  → version mismatch AND upgrade was skipped/failed
+  //                                (we can still boot with the old runtime,
+  //                                 but the user sees an explicit warning)
+  //   source='download-upgrade'  → cache was stale, we auto-upgraded in place
+  //   source='download'          → first-ever install, freshly downloaded
+  //   source='aionui-fork'/'vendor' → dev checkout
+  //
+  // We always call with allowDownload:true here (unless the user disabled
+  // auto-fetch) so stale caches get upgraded the same way first-run downloads
+  // happen. Before 2.1.10 the local resolver short-circuited on "file exists"
+  // and stale caches stayed stale forever.
   const autoFetchDisabled = process.env.HOLYSHEEP_WEBUI_NO_AUTOFETCH === '1'
-  if (!runtime && !autoFetchDisabled) {
-    console.log(chalk.cyan('▶ AionUi runtime not installed — downloading automatically (~21 MB, one-time)'))
-    console.log(chalk.gray('  (disable with HOLYSHEEP_WEBUI_NO_AUTOFETCH=1; override URL with HOLYSHEEP_AIONUI_RUNTIME_URL)'))
-    const downloaded = await downloadAionUiRuntime((m) => console.log(chalk.gray(`  ${m}`)))
-    if (downloaded) {
-      runtime = { dir: downloaded.dir, source: downloaded.source }
-      console.log(chalk.gray('  AionUi runtime installed. Next: ensure bun is available to launch it.'))
+  if (!autoFetchDisabled) {
+    // Pre-announce only when we know we're going to hit the network. For
+    // first-ever install we always do. For stale cache we _may_ do, depending
+    // on HOLYSHEEP_AIONUI_SKIP_UPGRADE.
+    const probe = probeAionUiRuntimeLabel()
+    if (probe === 'none') {
+      console.log(chalk.cyan('▶ AionUi runtime not installed — downloading automatically (~21 MB, one-time)'))
+      console.log(chalk.gray('  (disable with HOLYSHEEP_WEBUI_NO_AUTOFETCH=1; override URL with HOLYSHEEP_AIONUI_RUNTIME_URL)'))
+    } else if (probe === 'installed-stale' && process.env.HOLYSHEEP_AIONUI_SKIP_UPGRADE !== '1') {
+      console.log(chalk.cyan('▶ AionUi runtime is out of date — upgrading in place (atomic)'))
+      console.log(chalk.gray('  (set HOLYSHEEP_AIONUI_SKIP_UPGRADE=1 to pin current cache; HOLYSHEEP_AIONUI_PIN_VERSION=<v> to lock a version)'))
     }
   }
+  let runtime = await resolveAionUiRuntime({
+    allowDownload: !autoFetchDisabled,
+    logger: (m) => console.log(chalk.gray(`  ${m}`)),
+  })
+  if (runtime && runtime.source === 'download-upgrade') {
+    console.log(chalk.green(`  ✓ AionUi runtime upgraded to ${runtime.version}`))
+  } else if (runtime && runtime.source === 'user-cache-stale') {
+    console.log(chalk.yellow(
+      `  ⚠ Running stale AionUi runtime (${runtime.version}, expected newer). ` +
+      `Run: rm -rf ~/.holysheep/aionui-runtime && hs web  to force rebuild.`
+    ))
+  } else if (runtime && runtime.source === 'download') {
+    console.log(chalk.gray('  AionUi runtime installed. Next: ensure bun is available to launch it.'))
+  }
   if (!runtime) {
     const home = process.env.HOME || process.env.USERPROFILE || '~'
     console.log(chalk.red('✗ AionUi runtime not found and auto-download did not succeed'))
@@ -538,10 +576,12 @@ async function webui(opts) {
       console.log()
       return await startLegacyMode(opts)
     }
-    // Tri-state mode line: helps user-reports when things go sideways
+    // Tri-state mode line: helps user-reports when things go sideways.
+    // Runtime label now distinguishes `installed` (version matches baked-in
+    // DEFAULT_RUNTIME_VERSION) from `installed-stale` (will auto-upgrade on
+    // next call to resolveAionUiRuntime). `none` means first-ever launch.
     const bunFound = resolveBunPath() ? 'found' : 'missing'
-    const rt = resolveAionUiRuntimeDir()
-    const rtLabel = rt ? rt.source : 'none'
+    const rtLabel = probeAionUiRuntimeLabel()
     console.log(chalk.gray(`[mode=aionui platform=${process.platform} bun=${bunFound} runtime=${rtLabel}]`))
     console.log()
     return await startAionUiMode(opts)

package/src/webui/aionui-runtime-fetcher.js

@@ -2,17 +2,39 @@
  * AionUi runtime resolver
  *
  * Resolution order:
- *   1. ~/.holysheep/aionui-runtime/  (installed / cached)
- *   2. <cli>/src/webui/vendor/aionui/  (dev checkout — not shipped to npm)
- *   3. <cli>/../aionui-fork/  (dev repo checkout — not shipped to npm)
+ *   1. ~/.holysheep/aionui-runtime/  (installed / cached) — ONLY if its
+ *      version string matches DEFAULT_RUNTIME_VERSION (or
+ *      HOLYSHEEP_AIONUI_PIN_VERSION). A mismatch is treated as *stale*: the
+ *      cache is atomically replaced with the current version on next launch.
+ *   2. <cli>/src/webui/vendor/aionui/  (dev checkout — not shipped to npm,
+ *      no version gate)
+ *   3. <cli>/../aionui-fork/  (dev repo checkout — not shipped to npm,
+ *      no version gate; lets local `bun run build` take precedence over
+ *      any cached runtime when you're iterating on the fork)
  *   4. DEFAULT_RUNTIME_URL + DEFAULT_RUNTIME_SHA256 (baked in; auto-download
- *      when --setup-runtime is passed). Users can override via env.
+ *      when --setup-runtime is passed OR when cache is stale). Users can
+ *      override via env.
  *   5. null → caller must show a clear "runtime not installed" error
  *
- * The baked-in default URL is a public mirror of the AionUi v1.9.18 fork
- * with HolySheep API-key login patched in. It's the prebuilt artifact that
- * ships alongside `@simonyea/holysheep-cli` and is used by `hs web` on
- * first launch when no local runtime is present.
+ * ── Why stale detection exists ──────────────────────────────────────────────
+ * Before 2.1.10 the resolver returned the cache as soon as it saw
+ * `dist-server/server.mjs` on disk, regardless of which version it was. That
+ * meant users who installed hs web back when hs0/hs1 was the baked-in default
+ * kept running that exact build forever — every subsequent release (hs2
+ * rebrand, hs3 link fixes, hs5 OpenClaw model selector + HolySheep CLI card)
+ * silently did nothing on their machines, because their ~/.holysheep/…
+ * directory already "looked valid." This file now compares the cached
+ * package.json version against DEFAULT_RUNTIME_VERSION and upgrades in place
+ * via an atomic rename flow (stage → backup old → swap → drop backup).
+ *
+ * ── Atomic upgrade safety ───────────────────────────────────────────────────
+ * 1. Download tarball to `${USER_CACHE_DIR}.staging-${ts}` and verify SHA256.
+ * 2. Rename existing `USER_CACHE_DIR` → `${USER_CACHE_DIR}.bak-${ts}` (fast).
+ * 3. Rename staging dir → `USER_CACHE_DIR` (fast).
+ * 4. rm -rf the backup.
+ * Any failure before step 3 leaves the old cache untouched. A failure between
+ * step 2 and 3 is auto-restored from the backup. The user never ends up with
+ * no runtime at all.
  */
 
 'use strict'
@@ -27,16 +49,16 @@ const http = require('http')
 const USER_CACHE_DIR = path.join(os.homedir(), '.holysheep', 'aionui-runtime')
 const VENDOR_DIR = path.join(__dirname, 'vendor', 'aionui')
 
-// Baked-in defaults — updated with every 2.x.0 release that bumps the bundle.
-// Override via HOLYSHEEP_AIONUI_RUNTIME_URL / HOLYSHEEP_AIONUI_RUNTIME_SHA256.
-// hs3 = fix user-visible iOfficeAI/AionUi links → holysheep.ai (2.1.6, 2026-04-22).
-// Previous revisions still live on the CDN for forensics, but all new installs of
-// @simonyea/holysheep-cli >= 2.1.6 pull this tarball.
+// Baked-in defaults — updated with every release that bumps the runtime bundle.
+// Override at runtime via HOLYSHEEP_AIONUI_RUNTIME_URL / HOLYSHEEP_AIONUI_RUNTIME_SHA256
+// / HOLYSHEEP_AIONUI_PIN_VERSION. When DEFAULT_RUNTIME_VERSION changes in a
+// new CLI release, the next `hs web` invocation on user machines will detect
+// the version drift and upgrade the cache in place.
 const DEFAULT_RUNTIME_URL =
-  'https://mail.holysheep.ai/app/cli/aionui-runtime-v1.9.18-holysheep-hs5.tar.gz'
+  'https://mail.holysheep.ai/app/cli/aionui-runtime-v1.9.18-holysheep-hs7.tar.gz'
 const DEFAULT_RUNTIME_SHA256 =
-  'e398a13bf4b2256b63cc977322ab8c817c09e7d4000235218c3d2838e9dfb85f'
-const DEFAULT_RUNTIME_VERSION = '1.9.18-holysheep-hs5'
+  'abe85be2fa5e682bbfdcfd719f69f0eda296be5ee369173191c1c38e020120ef'
+const DEFAULT_RUNTIME_VERSION = '1.9.18-holysheep-hs7'
 
 function isValidRuntimeDir(dir) {
   if (!dir) return false
@@ -50,7 +72,35 @@ function isValidRuntimeDir(dir) {
   }
 }
 
+/**
+ * Read the version of a runtime directory.
+ *
+ * Order:
+ *   1. `.holysheep-runtime-version` (flat text file we stamp after a
+ *      successful download/upgrade — guaranteed to match what the fetcher
+ *      pulled, regardless of whether the tarball itself shipped a
+ *      package.json). This is the file future `isVersionCurrent` comparisons
+ *      rely on; without it, every subsequent `hs web` would mis-detect the
+ *      fresh cache as stale and re-download forever.
+ *   2. `package.json` `version` field (legacy — the hs0/hs1 tarballs did
+ *      include one with `1.9.18-holysheep`). Kept for backwards compat.
+ *   3. 'unknown' — treated as NOT current, so the fetcher will upgrade.
+ */
 function readVersion(dir) {
+  try {
+    const stamp = path.join(dir, '.holysheep-runtime-version')
+    if (fs.existsSync(stamp)) {
+      // .trim() is REQUIRED. writeVersionStamp() appends '\n', and a human
+      // doing manual recovery might have used `echo foo > file` (writes
+      // 'foo\n') or `echo -n foo > file` (writes 'foo' but on bash `echo`
+      // builtins that don't recognize -n you get '-n foo\n'). Trimming
+      // whitespace makes all these shapes compare equal — without it,
+      // isVersionCurrent() returned false on a freshly-stamped cache and
+      // looped into auto-upgrade. DO NOT remove this .trim().
+      const v = fs.readFileSync(stamp, 'utf8').trim()
+      if (v) return v
+    }
+  } catch {}
   try {
     const pkgPath = path.join(dir, 'package.json')
     if (fs.existsSync(pkgPath)) {
@@ -61,34 +111,109 @@ function readVersion(dir) {
   return 'unknown'
 }
 
+/**
+ * Stamp the runtime directory with the version we just installed so that
+ * readVersion() returns the right answer on subsequent launches. Fails
+ * silently — a missing stamp only means the _next_ launch will re-download,
+ * which is annoying but not dangerous.
+ */
+function writeVersionStamp(dir, version) {
+  try {
+    fs.writeFileSync(path.join(dir, '.holysheep-runtime-version'), version + '\n', 'utf8')
+  } catch {}
+}
+
+/**
+ * Strict string equality against the expected version.
+ *
+ * We intentionally do not parse semver ranges — runtime releases are tagged
+ * explicitly (hs5, hs6, …) and every CLI release pins exactly one expected
+ * string. This keeps the upgrade decision a boolean, not a version-math
+ * guessing game.
+ *
+ * Priority:
+ *   1. HOLYSHEEP_AIONUI_PIN_VERSION   (user opted-in lock)
+ *   2. DEFAULT_RUNTIME_VERSION         (baked into this CLI release)
+ */
+function expectedVersion() {
+  return process.env.HOLYSHEEP_AIONUI_PIN_VERSION || DEFAULT_RUNTIME_VERSION
+}
+
+function isVersionCurrent(dir) {
+  return readVersion(dir) === expectedVersion()
+}
+
 /**
  * Resolve an AionUi runtime directory.
- * @returns {{ dir: string, version: string, source: 'user-cache'|'vendor'|'env-download' } | null}
+ *
+ * @param {object}  opts
+ * @param {boolean} opts.allowDownload - if true, will attempt to download
+ *   the runtime when no local cache exists, OR when the local cache is
+ *   stale (version mismatch). Stale-upgrade is suppressed when the env var
+ *   `HOLYSHEEP_AIONUI_SKIP_UPGRADE=1` is set, in which case the stale cache
+ *   is returned as-is with `source: 'user-cache-stale'`.
+ * @param {(msg:string)=>void} opts.logger
+ *
+ * @returns {{ dir: string, version: string,
+ *             source: 'user-cache'|'user-cache-stale'|'vendor'|'aionui-fork'|'download'|'download-upgrade'
+ *           } | null}
  */
 async function resolveRuntime({ allowDownload = false, logger = () => {} } = {}) {
   // 1. User cache (installed runtime)
   if (isValidRuntimeDir(USER_CACHE_DIR)) {
-    return { dir: USER_CACHE_DIR, version: readVersion(USER_CACHE_DIR), source: 'user-cache' }
+    const ver = readVersion(USER_CACHE_DIR)
+    if (isVersionCurrent(USER_CACHE_DIR)) {
+      return { dir: USER_CACHE_DIR, version: ver, source: 'user-cache' }
+    }
+
+    // Stale. Decide whether to upgrade in place.
+    const skipUpgrade = process.env.HOLYSHEEP_AIONUI_SKIP_UPGRADE === '1'
+    if (allowDownload && !skipUpgrade) {
+      logger(`runtime cache is out of date (found ${ver}, expected ${expectedVersion()}) — upgrading...`)
+      try {
+        await performAtomicUpgrade(USER_CACHE_DIR, logger)
+        return {
+          dir: USER_CACHE_DIR,
+          version: readVersion(USER_CACHE_DIR) || expectedVersion(),
+          source: 'download-upgrade',
+        }
+      } catch (e) {
+        logger(`runtime upgrade failed: ${e.message}`)
+        // Fall through: return stale cache as a degraded-but-usable state
+        // so the user still gets _some_ WebUI rather than a hard error.
+        return { dir: USER_CACHE_DIR, version: ver, source: 'user-cache-stale' }
+      }
+    }
+    // No upgrade allowed/desired → return stale
+    return { dir: USER_CACHE_DIR, version: ver, source: 'user-cache-stale' }
   }
 
-  // 2. Dev vendor checkout (bundled for darwin-arm64 dev rigs — not in npm)
+  // 2. Dev vendor checkout (bundled for darwin-arm64 dev rigs — not in npm).
+  // No version gate: a dev checkout is assumed current by construction.
   if (isValidRuntimeDir(VENDOR_DIR)) {
     return { dir: VENDOR_DIR, version: readVersion(VENDOR_DIR), source: 'vendor' }
   }
 
-  // 3. Dev repo aionui-fork/ (when running from the holysheep-cli source repo)
+  // 3. Dev repo aionui-fork/ (when running from the holysheep-cli source repo).
+  // No version gate: whoever is building the fork locally is on the bleeding
+  // edge by definition; comparing against DEFAULT_RUNTIME_VERSION would just
+  // break local dev every time you bump the version bakeline.
   const forkDir = path.resolve(__dirname, '..', '..', 'aionui-fork')
   if (isValidRuntimeDir(forkDir)) {
     return { dir: forkDir, version: readVersion(forkDir), source: 'aionui-fork' }
   }
 
-  // 4. Download from env override OR baked-in default
+  // 4. Fresh install — download from env override OR baked-in default
   if (allowDownload) {
     const url = process.env.HOLYSHEEP_AIONUI_RUNTIME_URL || DEFAULT_RUNTIME_URL
     const expectedSha = process.env.HOLYSHEEP_AIONUI_RUNTIME_SHA256 || DEFAULT_RUNTIME_SHA256
     try {
+      fs.mkdirSync(USER_CACHE_DIR, { recursive: true })
       await downloadAndExtract(url, USER_CACHE_DIR, expectedSha, logger)
       if (isValidRuntimeDir(USER_CACHE_DIR)) {
+        // Stamp the version so subsequent launches don't re-detect as stale
+        // (hs5+ tarballs ship no root package.json).
+        writeVersionStamp(USER_CACHE_DIR, expectedVersion())
         return {
           dir: USER_CACHE_DIR,
           version: readVersion(USER_CACHE_DIR) || DEFAULT_RUNTIME_VERSION,
@@ -104,6 +229,82 @@ async function resolveRuntime({ allowDownload = false, logger = () => {} } = {})
   return null
 }
 
+/**
+ * Atomically replace the runtime at `targetDir` with a freshly downloaded
+ * copy. Safe against mid-operation failure: the old cache is preserved
+ * either in place (if download/verify fails) or as a `.bak-*` directory
+ * (if we crash between backup and swap).
+ *
+ * Implementation:
+ *   a) Download + extract to `${targetDir}.staging-${ts}`, verify SHA256.
+ *   b) `mv targetDir → ${targetDir}.bak-${ts}`  (atomic, same filesystem)
+ *   c) `mv stagingDir → targetDir`              (atomic, same filesystem)
+ *   d) `rm -rf ${targetDir}.bak-${ts}` on success.
+ *   e) On any failure in (b)→(c), try to restore from the `.bak-*` path.
+ */
+async function performAtomicUpgrade(targetDir, logger) {
+  const url = process.env.HOLYSHEEP_AIONUI_RUNTIME_URL || DEFAULT_RUNTIME_URL
+  const expectedSha = process.env.HOLYSHEEP_AIONUI_RUNTIME_SHA256 || DEFAULT_RUNTIME_SHA256
+  const ts = Date.now()
+  const stagingDir = `${targetDir}.staging-${ts}`
+  const backupDir = `${targetDir}.bak-${ts}`
+
+  // (a) Download + extract + verify into an isolated staging dir.
+  fs.mkdirSync(stagingDir, { recursive: true })
+  try {
+    await downloadAndExtract(url, stagingDir, expectedSha, logger)
+  } catch (e) {
+    try { rmrf(stagingDir) } catch {}
+    throw e
+  }
+  if (!isValidRuntimeDir(stagingDir)) {
+    try { rmrf(stagingDir) } catch {}
+    throw new Error('staged runtime failed structure validation')
+  }
+
+  // (b) Back up the old cache, if any.
+  let backedUp = false
+  if (fs.existsSync(targetDir)) {
+    try {
+      fs.renameSync(targetDir, backupDir)
+      backedUp = true
+    } catch (e) {
+      try { rmrf(stagingDir) } catch {}
+      throw new Error(`failed to back up old runtime: ${e.message}`)
+    }
+  }
+
+  // (c) Move staging into place.
+  try {
+    fs.renameSync(stagingDir, targetDir)
+  } catch (e) {
+    // Try to restore the backup so the user isn't left runtime-less.
+    if (backedUp) {
+      try { fs.renameSync(backupDir, targetDir) } catch {}
+    }
+    try { rmrf(stagingDir) } catch {}
+    throw new Error(`failed to swap in new runtime: ${e.message}`)
+  }
+
+  // (d) Stamp the version. hs5+ tarballs do NOT include a root package.json,
+  // so without this stamp readVersion() would fall back to 'unknown' and the
+  // very next `hs web` would re-enter the stale-upgrade branch and download
+  // again. See readVersion() docstring above.
+  writeVersionStamp(targetDir, expectedVersion())
+
+  // (e) Success — drop the backup.
+  if (backedUp) {
+    try { rmrf(backupDir) } catch (e) {
+      logger(`warning: could not remove old runtime backup at ${backupDir}: ${e.message}`)
+    }
+  }
+}
+
+function rmrf(p) {
+  // fs.rmSync landed in Node 14.14, which is well below our floor.
+  fs.rmSync(p, { recursive: true, force: true })
+}
+
 /**
  * Download a tar.gz from url, verify optional SHA256, extract into destDir.
  * Uses only Node built-ins (https + tar via exec) — zero new deps.
@@ -122,7 +323,7 @@ function downloadAndExtract(url, destDir, expectedSha, logger) {
       // Follow redirects (GitHub Releases → S3 CDN)
       if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
         file.close()
-        fs.unlinkSync(tmpFile)
+        try { fs.unlinkSync(tmpFile) } catch {}
         return resolve(downloadAndExtract(res.headers.location, destDir, expectedSha, logger))
       }
       if (res.statusCode !== 200) {
@@ -147,7 +348,7 @@ function downloadAndExtract(url, destDir, expectedSha, logger) {
             fs.mkdirSync(destDir, { recursive: true })
             const { execSync } = require('child_process')
             execSync(`tar -xzf "${tmpFile}" -C "${destDir}" --strip-components=0`, { stdio: 'ignore' })
-            fs.unlinkSync(tmpFile)
+            try { fs.unlinkSync(tmpFile) } catch {}
             // Post-extract sanity: hs4 once shipped a tarball that only
             // contained dist-server/ — the WebUI launched but every
             // renderer-side feature silently did nothing. Fail loudly here so
@@ -196,11 +397,8 @@ function describeInstallGuidance() {
     `    export HOLYSHEEP_AIONUI_RUNTIME_SHA256=${DEFAULT_RUNTIME_SHA256}`,
     '    hs web --setup-runtime',
     '',
-    '  Build from source (requires bun):',
-    '    git clone https://github.com/iOfficeAI/AionUi.git ~/AionUi',
-    '    cd ~/AionUi && bun install && bun run build:renderer:web && bun run build:server',
-    `    mkdir -p ${USER_CACHE_DIR}`,
-    `    cp -R ~/AionUi/{dist-server,out} ${USER_CACHE_DIR}/`,
+    '  Force a fresh runtime download even if cache exists:',
+    `    rm -rf ${USER_CACHE_DIR} && hs web`,
     '',
     '  Or fall back to the legacy HolySheep Workspace:',
     '    HOLYSHEEP_WEBUI_LEGACY=1 hs web',
@@ -213,8 +411,12 @@ module.exports = {
   DEFAULT_RUNTIME_URL,
   DEFAULT_RUNTIME_SHA256,
   DEFAULT_RUNTIME_VERSION,
+  expectedVersion,
+  isVersionCurrent,
   isValidRuntimeDir,
   readVersion,
+  writeVersionStamp,
   resolveRuntime,
+  performAtomicUpgrade,
   describeInstallGuidance,
 }