@co0ontty/wand 2.9.1 → 2.10.0

package/dist/npm-update-utils.js

@@ -12,8 +12,8 @@
  * `@co0ontty/.wand-*` 残留目录；失败时恢复备份，避免运行中的服务被半成品安装拆掉。
  */
 import { execFile, spawnSync } from "node:child_process";
-import { chmodSync, cpSync, existsSync, mkdtempSync, readdirSync, rmSync, statSync } from "node:fs";
-import os from "node:os";
+import { randomUUID } from "node:crypto";
+import { chmodSync, cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readlinkSync, realpathSync, readdirSync, renameSync, rmSync, statfsSync, statSync, symlinkSync, writeFileSync, } from "node:fs";
 import path from "node:path";
 import process from "node:process";
 import { promisify } from "node:util";
@@ -24,10 +24,14 @@ const execFileAsync = promisify(execFile);
 export const PACKAGE_NAME = "@co0ontty/wand";
 const PACKAGE_SCOPE = "@co0ontty";
 const PACKAGE_BASENAME = "wand";
-const NPM_BIN = process.platform === "win32" ? "npm.cmd" : "npm";
+const DEFAULT_NPM_BIN = process.platform === "win32" ? "npm.cmd" : "npm";
 const COMMON_UNIX_PATHS = ["/usr/local/sbin", "/usr/local/bin", "/usr/sbin", "/usr/bin", "/sbin", "/bin"];
 const INSTALL_MAX_BUFFER = 10 * 1024 * 1024;
 const NPM_VIEW_TIMEOUT_MS = 15_000;
+const UPDATE_DISK_RESERVE_BYTES = 512 * 1024 * 1024;
+function npmBin() {
+    return process.env.WAND_NPM_BIN || DEFAULT_NPM_BIN;
+}
 export function normalizeUpdateChannel(value) {
     return value === "beta" ? "beta" : "stable";
 }
@@ -83,7 +87,7 @@ export function buildPackageUpdateInfo(currentVersion, channel, latestVersion) {
 }
 async function viewPackageVersionAsync(channel, timeoutMs = NPM_VIEW_TIMEOUT_MS) {
     try {
-        const { stdout } = await execFileAsync(NPM_BIN, ["view", getInstallSpecForChannel(channel), "version"], { timeout: timeoutMs, env: getChildEnv(), maxBuffer: INSTALL_MAX_BUFFER });
+        const { stdout } = await execFileAsync(npmBin(), ["view", getInstallSpecForChannel(channel), "version"], { timeout: timeoutMs, env: getChildEnv(), maxBuffer: INSTALL_MAX_BUFFER });
         const version = String(stdout || "").trim();
         return version || null;
     }
@@ -132,7 +136,7 @@ function runNpmSync(args, timeoutMs) {
         env: getChildEnv(),
         maxBuffer: INSTALL_MAX_BUFFER,
     };
-    return spawnSync(NPM_BIN, args, options);
+    return spawnSync(npmBin(), args, options);
 }
 async function runNpmAsync(args, timeoutMs) {
     const options = {
@@ -140,7 +144,7 @@ async function runNpmAsync(args, timeoutMs) {
         env: getChildEnv(),
         maxBuffer: INSTALL_MAX_BUFFER,
     };
-    await execFileAsync(NPM_BIN, args, options);
+    await execFileAsync(npmBin(), args, options);
 }
 /**
  * 解析当前 `npm root -g` 的目录。失败返回 null。
@@ -157,6 +161,40 @@ export function getNpmGlobalRoot() {
         return null;
     }
 }
+function getNpmGlobalPrefix() {
+    try {
+        const res = runNpmSync(["prefix", "-g"], 10_000);
+        if (res.status !== 0)
+            return null;
+        const out = (res.stdout || "").trim();
+        return out.length > 0 ? out : null;
+    }
+    catch {
+        return null;
+    }
+}
+function getGlobalWandBinPaths() {
+    const prefix = getNpmGlobalPrefix();
+    if (!prefix)
+        return [];
+    if (process.platform === "win32") {
+        return [
+            path.join(prefix, PACKAGE_BASENAME),
+            path.join(prefix, `${PACKAGE_BASENAME}.cmd`),
+            path.join(prefix, `${PACKAGE_BASENAME}.ps1`),
+        ];
+    }
+    return [path.join(prefix, "bin", PACKAGE_BASENAME)];
+}
+function pathEntryExists(targetPath) {
+    try {
+        lstatSync(targetPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * 清理上一次 npm install 失败留下的 `.wand-XXXXXX` 残留目录。
  *
@@ -169,34 +207,69 @@ export function cleanupNpmLeftovers() {
     const root = getNpmGlobalRoot();
     if (!root)
         return { removed, errors };
-    const scopeDir = path.join(root, PACKAGE_SCOPE);
-    if (!existsSync(scopeDir))
-        return { removed, errors };
-    let entries;
-    try {
-        entries = readdirSync(scopeDir);
-    }
-    catch (err) {
-        errors.push(`readdir ${scopeDir}: ${getErrorMessage(err)}`);
-        return { removed, errors };
-    }
-    // 残留目录形如 `.wand-PdFXStca`：以点开头 + 包基名 + 短横线 + 随机后缀
-    const leftoverPattern = new RegExp(`^\\.${PACKAGE_BASENAME}-[A-Za-z0-9]+$`);
-    for (const name of entries) {
-        if (!leftoverPattern.test(name))
-            continue;
-        const fullPath = path.join(scopeDir, name);
+    // npm 的 rename 临时项固定为 `.wand-` + 8 位随机字串。不要用宽泛前缀，
+    // 否则会误删用户/运维留下的 `.wand-backup` 等人工备份。
+    const leftoverPattern = new RegExp(`^\\.${PACKAGE_BASENAME}-[A-Za-z0-9]{8}$`);
+    const isWandPackageLeftover = (fullPath) => {
         try {
-            // 仅清理目录，避免误删同名文件
-            if (!statSync(fullPath).isDirectory())
-                continue;
-            rmSync(fullPath, { recursive: true, force: true });
-            removed.push(fullPath);
+            if (!lstatSync(fullPath).isDirectory())
+                return false;
+            const manifest = JSON.parse(readFileSync(path.join(fullPath, "package.json"), "utf8"));
+            return manifest.name === PACKAGE_NAME;
+        }
+        catch {
+            return false;
+        }
+    };
+    const isWandBinLeftover = (fullPath) => {
+        try {
+            const entry = lstatSync(fullPath);
+            if (entry.isDirectory())
+                return false;
+            const marker = entry.isSymbolicLink()
+                ? readlinkSync(fullPath)
+                : readFileSync(fullPath, "utf8").slice(0, 16 * 1024);
+            return marker.includes(`${PACKAGE_SCOPE}/${PACKAGE_BASENAME}`)
+                || marker.includes(`${PACKAGE_SCOPE}${path.sep}${PACKAGE_BASENAME}`);
+        }
+        catch {
+            return false;
+        }
+    };
+    const cleanupDir = (dir, directoriesOnly) => {
+        if (!existsSync(dir))
+            return;
+        let entries;
+        try {
+            entries = readdirSync(dir);
         }
         catch (err) {
-            errors.push(`rm ${fullPath}: ${getErrorMessage(err)}`);
+            errors.push(`readdir ${dir}: ${getErrorMessage(err)}`);
+            return;
         }
-    }
+        for (const name of entries) {
+            if (!leftoverPattern.test(name))
+                continue;
+            const fullPath = path.join(dir, name);
+            try {
+                const belongsToWand = directoriesOnly
+                    ? isWandPackageLeftover(fullPath)
+                    : isWandBinLeftover(fullPath);
+                if (!belongsToWand)
+                    continue;
+                // bin 目录绝不递归删除目录；scope 里只删除已验证 manifest 的 wand 包。
+                rmSync(fullPath, { recursive: directoriesOnly, force: true });
+                removed.push(fullPath);
+            }
+            catch (err) {
+                errors.push(`rm ${fullPath}: ${getErrorMessage(err)}`);
+            }
+        }
+    };
+    cleanupDir(path.join(root, PACKAGE_SCOPE), true);
+    const binPaths = getGlobalWandBinPaths();
+    if (binPaths.length > 0)
+        cleanupDir(path.dirname(binPaths[0]), false);
     return { removed, errors };
 }
 const REQUIRED_RUNTIME_FILES = [
@@ -216,11 +289,59 @@ function getGlobalPackageDir() {
     const root = getNpmGlobalRoot();
     return root ? path.join(root, PACKAGE_SCOPE, PACKAGE_BASENAME) : null;
 }
-function validateGlobalWandInstall() {
-    const packageDir = getGlobalPackageDir();
-    if (!packageDir) {
-        return { ok: false, message: "无法解析 npm 全局安装目录。" };
+function directorySizeSync(targetPath) {
+    const entry = lstatSync(targetPath);
+    if (entry.isSymbolicLink())
+        return 0;
+    if (!entry.isDirectory())
+        return entry.size;
+    let total = 0;
+    for (const name of readdirSync(targetPath)) {
+        total += directorySizeSync(path.join(targetPath, name));
     }
+    return total;
+}
+/**
+ * 更新时同时存在旧包备份、npm 正在解包的新版本和下载/回滚余量。
+ * 旧包大小按三倍计（安全备份、新包、回滚 staging），再保留 512 MiB，
+ * 避免 ENOSPC 把全局 CLI 拆成半包。
+ */
+export function requiredUpdateFreeBytes(currentInstallBytes) {
+    const normalized = Number.isFinite(currentInstallBytes)
+        ? Math.max(0, Math.floor(currentInstallBytes))
+        : 0;
+    return normalized * 3 + UPDATE_DISK_RESERVE_BYTES;
+}
+function formatBytes(bytes) {
+    const gib = bytes / (1024 ** 3);
+    if (gib >= 1)
+        return `${gib.toFixed(2)} GiB`;
+    return `${(bytes / (1024 ** 2)).toFixed(0)} MiB`;
+}
+function nearestExistingAncestor(targetPath) {
+    let current = path.resolve(targetPath);
+    while (!existsSync(current)) {
+        const parent = path.dirname(current);
+        if (parent === current)
+            return current;
+        current = parent;
+    }
+    return current;
+}
+function assertUpdateDiskSpace(packageDir, note) {
+    const currentInstallBytes = existsSync(packageDir) ? directorySizeSync(packageDir) : 0;
+    const probePath = nearestExistingAncestor(packageDir);
+    const stats = statfsSync(probePath, { bigint: true });
+    const availableBytes = Number(stats.bavail * stats.bsize);
+    const requiredBytes = requiredUpdateFreeBytes(currentInstallBytes);
+    if (availableBytes < requiredBytes) {
+        throw new Error(`磁盘空间不足，已取消更新以保护当前安装：可用 ${formatBytes(availableBytes)}，` +
+            `至少需要 ${formatBytes(requiredBytes)}（当前 wand ${formatBytes(currentInstallBytes)}）。`);
+    }
+    note?.(`[wand] 更新磁盘预检通过: 可用 ${formatBytes(availableBytes)}，` +
+        `需要 ${formatBytes(requiredBytes)}`);
+}
+function validateWandPackageDir(packageDir) {
     const missing = [];
     for (const rel of REQUIRED_RUNTIME_FILES) {
         const fullPath = path.join(packageDir, rel);
@@ -254,6 +375,41 @@ function validateGlobalWandInstall() {
             };
         }
     }
+    return { ok: true };
+}
+function validateGlobalWandInstall() {
+    const packageDir = getGlobalPackageDir();
+    if (!packageDir) {
+        return { ok: false, message: "无法解析 npm 全局安装目录。" };
+    }
+    const packageValidation = validateWandPackageDir(packageDir);
+    if (!packageValidation.ok)
+        return packageValidation;
+    const binPaths = getGlobalWandBinPaths();
+    const cliPath = path.join(packageDir, "dist", "cli.js");
+    const hasWorkingBin = process.platform === "win32"
+        ? binPaths.length > 0 && binPaths.every((binPath) => {
+            try {
+                return statSync(binPath).isFile();
+            }
+            catch {
+                return false;
+            }
+        })
+        : binPaths.length === 1 && (() => {
+            try {
+                return realpathSync(binPaths[0]) === realpathSync(cliPath);
+            }
+            catch {
+                return false;
+            }
+        })();
+    if (!hasWorkingBin) {
+        return {
+            ok: false,
+            message: `全局 wand 命令入口缺失: ${binPaths.join(", ") || "无法解析 npm prefix"}`,
+        };
+    }
     return { ok: true, packageDir };
 }
 function assertGlobalWandInstallComplete() {
@@ -265,48 +421,172 @@ function assertGlobalWandInstallComplete() {
 function createGlobalInstallBackup(note) {
     const packageDir = getGlobalPackageDir();
     if (!packageDir) {
-        return { packageDir: "", backupDir: null };
+        throw new Error("无法解析 npm 全局安装目录，已取消更新以保护当前安装。");
     }
     if (!existsSync(packageDir)) {
-        return { packageDir, backupDir: null };
+        assertUpdateDiskSpace(packageDir, note);
+        return { packageDir, backupRoot: null, backupDir: null, binEntries: [] };
+    }
+    // 备份前只要求包体完整；bin shim 本身可能正是待修复对象。
+    const validation = validateWandPackageDir(packageDir);
+    if (!validation.ok) {
+        throw new Error(`${validation.message}；已取消更新，请先修复当前安装。`);
     }
-    const backupRoot = mkdtempSync(path.join(os.tmpdir(), "wand-global-backup-"));
+    assertUpdateDiskSpace(packageDir, note);
+    const scopeDir = path.dirname(packageDir);
+    mkdirSync(scopeDir, { recursive: true });
+    // 与全局包同盘并避开 npm 的 `.wand-XXXXXXXX` 命名，崩溃/重启后仍可作为救援运行时。
+    const backupRoot = mkdtempSync(path.join(scopeDir, ".wand-safe-backup-"));
     const backupDir = path.join(backupRoot, PACKAGE_BASENAME);
+    const binEntries = [];
     try {
         cpSync(packageDir, backupDir, {
             recursive: true,
             dereference: false,
             verbatimSymlinks: true,
         });
+        const binBackupDir = path.join(backupRoot, "bin");
+        for (const [index, originalPath] of getGlobalWandBinPaths().entries()) {
+            if (!pathEntryExists(originalPath))
+                continue;
+            mkdirSync(binBackupDir, { recursive: true });
+            const backupPath = path.join(binBackupDir, `${index}-${path.basename(originalPath)}`);
+            cpSync(originalPath, backupPath, {
+                dereference: false,
+                verbatimSymlinks: true,
+            });
+            binEntries.push({ originalPath, backupPath });
+        }
         note?.(`[wand] 已备份当前全局安装: ${backupDir}`);
-        return { packageDir, backupDir };
+        return { packageDir, backupRoot, backupDir, binEntries };
     }
     catch (err) {
         rmSync(backupRoot, { recursive: true, force: true });
-        note?.(`[wand] 全局安装备份失败，继续尝试更新: ${getErrorMessage(err)}`);
-        return { packageDir, backupDir: null };
+        throw new Error(`全局安装备份失败，已取消更新: ${getErrorMessage(err)}`);
     }
 }
 function cleanupGlobalInstallBackup(backup) {
-    if (!backup.backupDir)
+    if (!backup.backupRoot)
         return;
-    rmSync(path.dirname(backup.backupDir), { recursive: true, force: true });
+    rmSync(backup.backupRoot, { recursive: true, force: true });
+}
+function removeGlobalBinEntry(binPath) {
+    try {
+        if (lstatSync(binPath).isDirectory()) {
+            throw new Error(`拒绝递归删除异常的 wand bin 目录: ${binPath}`);
+        }
+        rmSync(binPath, { force: true });
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+    }
+}
+function pointPosixBinAtRecoveryBackup(backup) {
+    if (process.platform === "win32" || !backup.backupDir)
+        return;
+    const binPaths = getGlobalWandBinPaths();
+    if (binPaths.length !== 1)
+        throw new Error("无法解析 npm 全局 bin 目录。");
+    const binPath = binPaths[0];
+    const recoveryCli = path.join(backup.backupDir, "dist", "cli.js");
+    const recoveryValidation = validateWandPackageDir(backup.backupDir);
+    if (!recoveryValidation.ok)
+        throw new Error(recoveryValidation.message);
+    const binDir = path.dirname(binPath);
+    mkdirSync(binDir, { recursive: true });
+    const pendingLink = path.join(binDir, `.wand-recovery-${randomUUID()}`);
+    try {
+        symlinkSync(path.relative(binDir, recoveryCli), pendingLink);
+        // rename 覆盖文件/符号链接是原子的；若目标异常地是目录则拒绝并保留原状。
+        if (pathEntryExists(binPath) && lstatSync(binPath).isDirectory()) {
+            throw new Error(`拒绝替换异常的 wand bin 目录: ${binPath}`);
+        }
+        renameSync(pendingLink, binPath);
+    }
+    catch (err) {
+        rmSync(pendingLink, { force: true });
+        throw err;
+    }
+}
+function restoreGlobalBinEntries(backup) {
+    const binPaths = getGlobalWandBinPaths();
+    if (process.platform !== "win32") {
+        if (binPaths.length !== 1)
+            throw new Error("无法解析 npm 全局 bin 目录。");
+        const binPath = binPaths[0];
+        const cliPath = path.join(backup.packageDir, "dist", "cli.js");
+        mkdirSync(path.dirname(binPath), { recursive: true });
+        removeGlobalBinEntry(binPath);
+        symlinkSync(path.relative(path.dirname(binPath), cliPath), binPath);
+        return;
+    }
+    for (const entry of backup.binEntries) {
+        removeGlobalBinEntry(entry.originalPath);
+        mkdirSync(path.dirname(entry.originalPath), { recursive: true });
+        cpSync(entry.backupPath, entry.originalPath, {
+            dereference: false,
+            verbatimSymlinks: true,
+        });
+    }
 }
 function restoreGlobalInstallBackup(backup, note) {
     if (!backup.packageDir || !backup.backupDir || !existsSync(backup.backupDir))
         return false;
+    const scopeDir = path.dirname(backup.packageDir);
+    let stageRoot = null;
+    let quarantinePath = null;
     try {
-        rmSync(backup.packageDir, { recursive: true, force: true });
-        cpSync(backup.backupDir, backup.packageDir, {
+        // 回滚复制/目录切换期间，即使进程或机器硬退出，launchd/systemd 仍能从同盘完整备份启动。
+        pointPosixBinAtRecoveryBackup(backup);
+        // 先在 npm root 同盘 staging 复制并校验。复制失败时不碰当前目录，也不消费备份；
+        // staging 完整后才用同盘 rename 原子替换，避免回滚自身再次留下半包。
+        mkdirSync(scopeDir, { recursive: true });
+        stageRoot = mkdtempSync(path.join(scopeDir, ".wand-restore-"));
+        const stagedPackage = path.join(stageRoot, PACKAGE_BASENAME);
+        cpSync(backup.backupDir, stagedPackage, {
             recursive: true,
             dereference: false,
             verbatimSymlinks: true,
         });
+        const stagedValidation = validateWandPackageDir(stagedPackage);
+        if (!stagedValidation.ok)
+            throw new Error(stagedValidation.message);
+        // 不先 rm 当前目录：把它原子挪到同盘 quarantine，再 promote staging。
+        // promote 若失败，立即把原目录原子放回，避免失败路径留下空安装。
+        if (existsSync(backup.packageDir)) {
+            quarantinePath = path.join(scopeDir, `.wand-quarantine-${randomUUID()}`);
+            renameSync(backup.packageDir, quarantinePath);
+        }
+        try {
+            renameSync(stagedPackage, backup.packageDir);
+        }
+        catch (promoteError) {
+            if (quarantinePath && !existsSync(backup.packageDir) && existsSync(quarantinePath)) {
+                renameSync(quarantinePath, backup.packageDir);
+                quarantinePath = null;
+            }
+            throw promoteError;
+        }
+        restoreGlobalBinEntries(backup);
+        const validation = validateGlobalWandInstall();
+        if (!validation.ok)
+            throw new Error(validation.message);
+        if (quarantinePath) {
+            rmSync(quarantinePath, { recursive: true, force: true });
+            quarantinePath = null;
+        }
+        rmSync(stageRoot, { recursive: true, force: true });
+        stageRoot = null;
         note?.(`[wand] 已恢复更新前的全局安装: ${backup.packageDir}`);
         return true;
     }
     catch (err) {
-        note?.(`[wand] 恢复更新前安装失败: ${getErrorMessage(err)}`);
+        if (stageRoot)
+            rmSync(stageRoot, { recursive: true, force: true });
+        note?.(`[wand] 恢复更新前安装失败: ${getErrorMessage(err)}；` +
+            `备份保留在 ${backup.backupRoot ?? backup.backupDir}` +
+            `${quarantinePath ? `；替换前目录保留在 ${quarantinePath}` : ""}`);
         return false;
     }
 }
@@ -314,7 +594,57 @@ async function npmInstallGlobalAsync(pkg, timeoutMs, extra = []) {
     await runNpmAsync(["install", "-g", ...extra, pkg], timeoutMs);
 }
 function isRecoverableInstallError(message) {
-    return /ENOTEMPTY|EEXIST|全局 wand 安装不完整|无法解析 npm 全局安装目录|全局 wand CLI 无法设置执行权限/.test(message);
+    return /ENOTEMPTY|EEXIST|全局 wand 安装不完整|无法解析 npm 全局安装目录|全局 wand CLI 无法设置执行权限|全局 wand 命令入口缺失/.test(message);
+}
+function acquireGlobalUpdateLock() {
+    const root = getNpmGlobalRoot();
+    if (!root)
+        throw new Error("无法解析 npm 全局安装目录，不能建立更新锁。");
+    const scopeDir = path.join(root, PACKAGE_SCOPE);
+    // 放在 npm root，而不是 @scope 内；npm uninstall 可能清理空 scope 目录。
+    const lockPath = path.join(root, ".wand-update-lock");
+    const token = randomUUID();
+    mkdirSync(scopeDir, { recursive: true });
+    try {
+        mkdirSync(lockPath);
+        writeFileSync(path.join(lockPath, "owner.json"), `${JSON.stringify({ pid: process.pid, token, createdAt: Date.now() })}\n`, "utf8");
+        return { lockPath, token };
+    }
+    catch (err) {
+        if (err.code !== "EEXIST") {
+            // 只有本次成功 mkdir 后写 owner 失败时才清；owner token 防止误删别人的锁。
+            try {
+                const owner = JSON.parse(readFileSync(path.join(lockPath, "owner.json"), "utf8"));
+                if (owner.token === token)
+                    rmSync(lockPath, { recursive: true, force: true });
+            }
+            catch {
+                /* 无法证明归属，不删除 */
+            }
+            throw err;
+        }
+    }
+    let ownerPid = 0;
+    try {
+        const owner = JSON.parse(readFileSync(path.join(lockPath, "owner.json"), "utf8"));
+        ownerPid = typeof owner.pid === "number" ? owner.pid : 0;
+    }
+    catch {
+        /* owner may still be writing; the directory itself is the atomic lock */
+    }
+    throw new Error(`另一个 wand 更新正在进行中（锁: ${lockPath}${ownerPid ? `, PID ${ownerPid}` : ""}）。` +
+        "若确认没有更新进程，请手动删除该锁目录。");
+}
+function releaseGlobalUpdateLock(lock) {
+    try {
+        const owner = JSON.parse(readFileSync(path.join(lock.lockPath, "owner.json"), "utf8"));
+        if (owner.token === lock.token) {
+            rmSync(lock.lockPath, { recursive: true, force: true });
+        }
+    }
+    catch {
+        // 无法确认 owner 时宁可留下陈旧锁，也不能删掉另一个更新者的锁。
+    }
 }
 /**
  * 异步版本的全局安装：
@@ -332,9 +662,11 @@ export async function installPackageGloballyAsync(pkg, timeoutMs, log) {
         if (log)
             log(line);
     };
-    const backup = createGlobalInstallBackup(note);
+    const updateLock = acquireGlobalUpdateLock();
+    let backup = null;
     let success = false;
     try {
+        backup = createGlobalInstallBackup(note);
         const cleanup = cleanupNpmLeftovers();
         if (cleanup.removed.length > 0) {
             note(`[wand] 清理 npm 残留目录: ${cleanup.removed.join(", ")}`);
@@ -350,7 +682,7 @@ export async function installPackageGloballyAsync(pkg, timeoutMs, log) {
             if (!isRecoverableInstallError(msg)) {
                 throw error;
             }
-            if (/全局 wand 安装不完整|无法解析 npm 全局安装目录|全局 wand CLI 无法设置执行权限/.test(msg)) {
+            if (/全局 wand 安装不完整|无法解析 npm 全局安装目录|全局 wand CLI 无法设置执行权限|全局 wand 命令入口缺失/.test(msg)) {
                 note(`[wand] npm install 后安装目录不完整，尝试强制重装...`);
             }
             else {
@@ -386,12 +718,21 @@ export async function installPackageGloballyAsync(pkg, timeoutMs, log) {
         success = true;
     }
     finally {
-        if (!success) {
-            if (restoreGlobalInstallBackup(backup, note)) {
-                cleanupNpmLeftovers();
+        try {
+            let restored = false;
+            if (!success && backup) {
+                restored = restoreGlobalInstallBackup(backup, note);
+                if (restored) {
+                    cleanupNpmLeftovers();
+                }
             }
+            // 恢复失败时绝不能再删唯一完整备份，留给人工恢复。
+            if (backup && (success || restored))
+                cleanupGlobalInstallBackup(backup);
+        }
+        finally {
+            releaseGlobalUpdateLock(updateLock);
         }
-        cleanupGlobalInstallBackup(backup);
     }
 }
 /**
@@ -402,7 +743,26 @@ export async function installPackageGloballyAsync(pkg, timeoutMs, log) {
 export function installPackageGloballySync(pkg, timeoutMs) {
     const attempts = [];
     const backupNotes = [];
-    const backup = createGlobalInstallBackup((line) => backupNotes.push(line));
+    let updateLock;
+    try {
+        updateLock = acquireGlobalUpdateLock();
+    }
+    catch (err) {
+        return { status: 1, stdout: "", stderr: getErrorMessage(err), attempts };
+    }
+    let backup;
+    try {
+        backup = createGlobalInstallBackup((line) => backupNotes.push(line));
+    }
+    catch (err) {
+        releaseGlobalUpdateLock(updateLock);
+        return {
+            status: 1,
+            stdout: "",
+            stderr: getErrorMessage(err),
+            attempts,
+        };
+    }
     const withValidation = (res) => {
         if (res.status !== 0)
             return res;
@@ -431,42 +791,58 @@ export function installPackageGloballySync(pkg, timeoutMs) {
         attempts,
     });
     const finishSuccess = (res) => {
-        cleanupGlobalInstallBackup(backup);
-        return withBackupNotes(res);
+        try {
+            cleanupGlobalInstallBackup(backup);
+            return withBackupNotes(res);
+        }
+        finally {
+            releaseGlobalUpdateLock(updateLock);
+        }
     };
     const finishFailure = (res) => {
-        if (restoreGlobalInstallBackup(backup, (line) => backupNotes.push(line))) {
-            cleanupNpmLeftovers();
+        try {
+            const restored = restoreGlobalInstallBackup(backup, (line) => backupNotes.push(line));
+            if (restored) {
+                cleanupNpmLeftovers();
+                cleanupGlobalInstallBackup(backup);
+            }
+            return withBackupNotes(res);
+        }
+        finally {
+            releaseGlobalUpdateLock(updateLock);
         }
-        cleanupGlobalInstallBackup(backup);
-        return withBackupNotes(res);
     };
-    cleanupNpmLeftovers();
-    let res = tryInstall([]);
-    if (res.status === 0) {
-        return finishSuccess(res);
-    }
-    const hitRecoverableInstallError = (r) => isRecoverableInstallError(r.stdout + r.stderr);
-    if (!hitRecoverableInstallError(res)) {
-        return finishFailure(res);
-    }
-    cleanupNpmLeftovers();
-    res = tryInstall([]);
-    if (res.status === 0) {
-        return finishSuccess(res);
-    }
-    if (!hitRecoverableInstallError(res)) {
+    try {
+        cleanupNpmLeftovers();
+        let res = tryInstall([]);
+        if (res.status === 0) {
+            return finishSuccess(res);
+        }
+        const hitRecoverableInstallError = (r) => isRecoverableInstallError(r.stdout + r.stderr);
+        if (!hitRecoverableInstallError(res)) {
+            return finishFailure(res);
+        }
+        cleanupNpmLeftovers();
+        res = tryInstall([]);
+        if (res.status === 0) {
+            return finishSuccess(res);
+        }
+        if (!hitRecoverableInstallError(res)) {
+            return finishFailure(res);
+        }
+        // 终极兜底（卸载用固定包名，兼容 git spec，见 async 版同样注释）
+        attempts.push(`npm uninstall -g ${PACKAGE_NAME}`);
+        runNpmSync(["uninstall", "-g", PACKAGE_NAME], timeoutMs);
+        cleanupNpmLeftovers();
+        res = tryInstall(["--force"]);
+        if (res.status === 0) {
+            return finishSuccess(res);
+        }
         return finishFailure(res);
     }
-    // 终极兜底（卸载用固定包名，兼容 git spec，见 async 版同样注释）
-    attempts.push(`npm uninstall -g ${PACKAGE_NAME}`);
-    runNpmSync(["uninstall", "-g", PACKAGE_NAME], timeoutMs);
-    cleanupNpmLeftovers();
-    res = tryInstall(["--force"]);
-    if (res.status === 0) {
-        return finishSuccess(res);
+    catch (err) {
+        return finishFailure({ status: 1, stdout: "", stderr: getErrorMessage(err) });
     }
-    return finishFailure(res);
 }
 /**
  * 解析「刚装好的全局 wand CLI 入口」(dist/cli.js) 的绝对路径。
@@ -494,3 +870,15 @@ export function resolveGlobalWandCli() {
         return found;
     return null;
 }
+/**
+ * 返回 npm 全局命令 shim 的稳定路径。服务 unit 应固定到这个入口，而不是包目录内的
+ * dist/cli.js；更新回滚期间 shim 会临时指向同盘安全备份，始终保持可启动。
+ */
+export function resolveGlobalWandBin() {
+    const candidates = getGlobalWandBinPaths();
+    for (const candidate of candidates) {
+        if (pathEntryExists(candidate))
+            return candidate;
+    }
+    return null;
+}