@co0ontty/wand 4.91.1-beta.357.1.g3bfbf35 → 4.92.0

package/README.md

@@ -68,6 +68,13 @@ wand config:password
 - **Update channels** — built-in stable/beta update checks and upgrade prompts
 - **CLI updates** — check and quickly update Claude Code, Codex, OpenCode, Qoder CLI, Pi, and Gemini CLI from server settings, with optional automatic updates
 
+Stable subscribers receive npm `latest`; Beta subscribers receive the newer of `latest`
+and `beta`, including a stable release that supersedes its prerelease. Installing stable
+keeps the Beta subscription enabled. Updates pin the checked version, wait for Core turns,
+and restart only the Web service. If an old updater cannot run, rerun `install.sh` for a
+staged recovery that preserves the previous installation and service scope. Node.js must
+meet the new package's requirement. See [Web update and recovery](docs/web-updates.md).
+
 ### Configuration
 
 The default config file is `~/.wand/config.json`; it is created by `wand init`.
@@ -251,16 +258,30 @@ npm install -g @google/gemini-cli@latest
 - **HTTPS** — 可选自签证书，适合远程或移动端访问
 - **版本管理** — 内置更新检查与升级提示，支持 stable/beta 双通道
 
-Web 设置中的「Beta 通道」决定服务端 npm 更新来源：关闭时仅检查
-`@co0ontty/wand@latest`，开启时检查 `@co0ontty/wand@beta`；「自动更新 Web 服务」
-独立决定是否自动安装。检查后安装锁定具体版本，避免 dist-tag 在安装期间移动。
-关闭 Beta 不会自动降级；需要立即返回较旧正式版时，点击「更新或重新安装」。
+Web 设置中的「Beta 通道」决定服务端 npm 更新候选：关闭时仅检查
+`@co0ontty/wand@latest`，开启时同时检查 `latest` 与 `beta`，选择版本较新的一个；
+同号正式版高于其 beta。「自动更新 Web 服务」独立决定是否自动安装。
+检查后安装锁定具体版本，避免 dist-tag 在安装期间移动。Beta 用户安装正式版后
+仍保留 Beta 订阅，下一次有更新的 beta 时继续收到更新。关闭 Beta 不会自动降级；
+需要立即返回较旧正式版时，点击「更新或重新安装」。
+
+手动与自动更新共用独立 helper：等待 Core 回合完成后安装，失败保留旧服务；
+成功后只重启 Web 服务，Render/terminald 的会话继续运行。Web 更新不能升级 Node.js；
+Node 版本不足会在改动安装前拒绝。页面同时核对新服务实例和目标版本后才刷新。
+旧版本无法自更新时，重新执行本文的 `install.sh`：恢复流程先下载验证完整包，
+保留旧安装，等待 Core 排空，再修复全局入口与原 service scope，支持残缺安装。
+默认保留已保存的 Beta 订阅；切换 Node 后已有配置/数据库仍进入升级流程。
+入口会复用兼容的已有 Node，必要时使用已配置 nvm 安装；npm 目录不可写时迁入用户可写的运行时目录，
+后续更新始终绑定这份实际安装。新版也附带 `wand update:repair` 恢复命令，避免依赖 GitHub 可达。
+可用 `WAND_UPDATE_CHANNEL=stable` 或 `beta` 指定本次恢复目标，
+`WAND_CONFIG_PATH` 指定自定义配置路径。详细流程、失败原因与补救见 [Web 更新说明](docs/web-updates.md)。
 
 正式 npm 发布由 `vX.Y.Z` Git tag 触发，只写入 `latest`，拒绝预发布版本。
 master 的 Beta 发布只写入 `beta`，版本为下一补丁号加
 `-beta.<构建序号>.<重试序号>.g<提交>`，例如 `4.89.5-beta.100.1.gabcdef0`。
 版本基数同时检查正式 Git tags 和 npm latest，兼容未推送 Git 的本地正式发布。
-Beta 尚未发布、通道版本无效或 npm 暂不可达时，不自动安装其他通道。
+Beta 标签缺失或无效时，Beta 订阅仍可接收有效正式版；正式通道始终不选择 beta。
+两个候选都无效或 npm 不可达时不安装。
 - **CLI 更新** — 在服务端设置中检查并快速更新 Claude Code、Codex、OpenCode、Qoder CLI、Pi 和 Gemini CLI，也可开启自动更新
 
 ### 配置

package/dist/build-info.json

@@ -1,6 +1,6 @@
 {
-  "commit": "3bfbf35960418829557a3ceebd4651536c75158d",
-  "builtAt": "2026-10-14T00:02:21.131Z",
-  "version": "4.91.1-beta.357.1.g3bfbf35",
-  "channel": "beta"
+  "commit": "f9fff36feba5836645f1eff3c7605c2d3c794755",
+  "builtAt": "2026-10-14T02:19:26.662Z",
+  "version": "4.92.0",
+  "channel": "stable"
 }

package/dist/cli.js

@@ -180,6 +180,11 @@ async function main() {
             await runAgentCliCommand(command, args, configPath);
             break;
         }
+        case "update:repair": {
+            const { repairInstalledUpdate } = await import("./update-repair-cli.js");
+            process.exitCode = await repairInstalledUpdate(configPath);
+            break;
+        }
         case "core:status": {
             const { checkCoreStatus } = await import("./core-status-cli.js");
             await checkCoreStatus(configPath);
@@ -297,6 +302,7 @@ Agent runtime:
 
 System service (default = system-wide; pass --user for user-level):
   wand service:install      Register and start the background service (needs sudo for system)
+  wand update:repair        Recover an old/broken installation while retaining data and update channel
   wand service:uninstall    Stop and remove the service
   wand service:start        Start the service
   wand service:stop         Stop the service

package/dist/core-runner.js

@@ -632,13 +632,6 @@ export function compactionSettings(config, defaults) {
         keepRecentTokens: override?.keepRecentTokens ?? defaults.keepRecentTokens,
     };
 }
-/** 一条只含文本的用户消息才算“真正的用户输入”：只在该边界切，保证 tool_use / tool_result 不被切开。 */
-function currentUserTurnIndex(session, prompt) {
-    const turns = session.messages ?? [];
-    const last = turns.at(-1);
-    const text = last?.content?.filter((block) => block.type === "text").map((block) => block.text).join("\n");
-    return last?.role === "user" && text === prompt ? turns.length - 1 : turns.length;
-}
 function isUserTextTurn(turn) {
     if (turn.role !== "user")
         return false;

package/dist/core-status-cli.d.ts

@@ -4,6 +4,8 @@ export interface CoreStatus {
     activeTurnCount: number;
     activeTurnIds?: string[];
 }
+/** A single request spends only the original overall deadline, never a fresh timeout. */
+export declare function remainingCoreRequestBudget(deadline: number): number;
 export declare function checkCoreStatus(configPath: string): Promise<void>;
 /** Zero means wait indefinitely. A timeout/error NEVER runs the stop command. */
 export declare function waitForCoreTurnsComplete(configPath: string, timeoutSeconds?: number, stopCommand?: string[], allowStopped?: boolean): Promise<number>;

package/dist/core-status-cli.js

@@ -141,17 +141,18 @@ async function readLegacyStatus(configPath, timeoutMs = 5000) {
     });
     return parseStatus(result);
 }
+/** A single request spends only the original overall deadline, never a fresh timeout. */
+export function remainingCoreRequestBudget(deadline) {
+    const remaining = deadline - Date.now();
+    if (remaining <= 0)
+        throw new Error("等待 Core 回合超时，服务未停止，已取消重启。");
+    return Math.min(5000, remaining);
+}
 async function openControl(configPath, deadline = Infinity) {
     const control = new CoreControl(configPath);
-    const budget = () => {
-        const remaining = deadline - Date.now();
-        if (remaining <= 0)
-            throw new Error("等待 Core 回合超时，服务未停止，已取消重启。");
-        return Math.min(5000, remaining);
-    };
     try {
-        await control.connect(budget());
-        await control.request("core-status", budget());
+        await control.connect(remainingCoreRequestBudget(deadline));
+        await control.request("core-status", remainingCoreRequestBudget(deadline));
         return control;
     }
     catch (error) {
@@ -183,12 +184,6 @@ export async function waitForCoreTurnsComplete(configPath, timeoutSeconds = 0, s
     if (stopCommand && !stopCommand.length)
         throw new Error("缺少等待完成后要执行的停止命令。");
     const deadline = timeoutSeconds > 0 ? Date.now() + timeoutSeconds * 1000 : Infinity;
-    const budget = () => {
-        const remaining = deadline - Date.now();
-        if (remaining <= 0)
-            throw new Error("等待 Core 回合超时，服务未停止，已取消重启。");
-        return Math.min(5000, remaining);
-    };
     const control = await openControl(configPath, deadline);
     try {
         const readStatus = async (budget = 5000) => {
@@ -222,7 +217,9 @@ export async function waitForCoreTurnsComplete(configPath, timeoutSeconds = 0, s
                 return { hasActiveTurns: false, activeTurnCount: 0 };
             }
         };
-        let status = control && stopCommand ? await control.request("core-drain", budget()) : await readStatus(budget());
+        let status = control && stopCommand
+            ? await control.request("core-drain", remainingCoreRequestBudget(deadline))
+            : await readStatus(remainingCoreRequestBudget(deadline));
         if (!control && stopCommand)
             console.error("[wand] 旧服务尚不支持重启排空；正在读取真实服务状态。首次升级等待期间请勿启动新任务。");
         let lastCount = -1;
@@ -235,7 +232,7 @@ export async function waitForCoreTurnsComplete(configPath, timeoutSeconds = 0, s
             if (remaining <= 0)
                 throw new Error("等待 Core 回合超时，服务未停止，已取消重启。");
             await new Promise((resolve) => setTimeout(resolve, Math.min(1000, remaining)));
-            status = await readStatus(budget());
+            status = await readStatus(remainingCoreRequestBudget(deadline));
         }
         // The draining connection stays open until the stop command finishes.
         // New Pi inputs are persisted in the queue, not started in the check/stop gap.

package/dist/daemon-connection.d.ts

@@ -1,4 +1,9 @@
 import type net from "node:net";
+/** Reject this client's pending generation without changing its connection lifecycle. */
+export declare function rejectPendingRequests<T extends {
+    timer: NodeJS.Timeout;
+    reject(error: Error): void;
+}>(pending: Map<number, T>, error: Error): void;
 /** Bound connect attempts, including sockets that close before the handshake. */
 export declare function waitForDaemonSocket(socket: net.Socket): Promise<void>;
 /** Probe the application, not just the fd: a half-open socket may still be writable. */

package/dist/daemon-connection.js

@@ -2,6 +2,14 @@ import { lstatSync, utimesSync } from "node:fs";
 const CONNECT_TIMEOUT_MS = 10_000;
 const HEARTBEAT_INTERVAL_MS = 15_000;
 const HEARTBEAT_TIMEOUT_MS = 5_000;
+/** Reject this client's pending generation without changing its connection lifecycle. */
+export function rejectPendingRequests(pending, error) {
+    for (const request of pending.values()) {
+        clearTimeout(request.timer);
+        request.reject(error);
+    }
+    pending.clear();
+}
 /** Bound connect attempts, including sockets that close before the handshake. */
 export function waitForDaemonSocket(socket) {
     return new Promise((resolve, reject) => {

package/dist/decision-tool.js

@@ -1,3 +1,5 @@
+import { isRecord } from "./object-utils.js";
+import { collapseWhitespaceAndClip as collapse } from "./text-utils.js";
 /** core 会话里决策是进程内工具（`src/core-runner.ts`）；CLI 会话是命令行调用。 */
 export const DECISION_TOOL_NAME = "decision_evaluate";
 /** Small shell lexer: quoted examples are one argument, not executable commands; heredoc bodies are data. */
@@ -116,14 +118,6 @@ const MODE_HINTS = {
     choice: "选择", score: "评分", noul: "是非判断", mixed: "混合判断",
 };
 const GENERIC_HINT = "选择 / 评分 / 是非判断";
-function isRecord(value) {
-    return !!value && typeof value === "object" && !Array.isArray(value);
-}
-/** 折叠空白并截断：摘要永远单行、有界。 */
-function collapse(text, max) {
-    const flat = text.replace(/\s+/g, " ").trim();
-    return flat.length > max ? `${flat.slice(0, Math.max(1, max - 1))}…` : flat;
-}
 function modeOf(types) {
     const unique = new Set(types);
     if (!unique.size)

package/dist/middleware/api-scope.js

@@ -18,6 +18,7 @@ export const API_ROUTE_RULES = [
     { prefix: "/api/connectors", scope: "admin" },
     { prefix: "/api/github", scope: "admin" },
     { prefix: "/api/update", scope: "admin" },
+    { prefix: "/api/update-status", scope: "admin" },
     { prefix: "/api/update-channel", scope: "admin" },
     { prefix: "/api/check-update", scope: "admin" },
     { prefix: "/api/auto-update", scope: "admin" },

package/dist/models/shared.d.ts

@@ -15,4 +15,4 @@ export declare const PI_FALLBACK_MODELS: ClaudeModelInfo[];
  */
 export declare const GEMINI_FALLBACK_MODELS: ClaudeModelInfo[];
 export declare function cloneModels(models: readonly ClaudeModelInfo[]): ClaudeModelInfo[];
-export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export { isRecord } from "../object-utils.js";

package/dist/models/shared.js

@@ -58,6 +58,4 @@ export function cloneModels(models) {
             : {}),
     }));
 }
-export function isRecord(value) {
-    return !!value && typeof value === "object" && !Array.isArray(value);
-}
+export { isRecord } from "../object-utils.js";

package/dist/npm-update-utils.d.ts

@@ -20,18 +20,31 @@ export interface PackageUpdateInfo {
     updateAvailable: boolean;
     distTag: "latest" | "beta";
     installSpec: string;
+    /** Candidate metadata is distinct from the user's persistent subscription. */
+    stableVersion?: string | null;
+    betaVersion?: string | null;
 }
 export declare function normalizeUpdateChannel(value: unknown): UpdateChannel;
 export declare function getInstallSpecForChannel(channel: UpdateChannel): string;
 export declare function buildPackageUpdateInfo(currentVersion: string, channel: UpdateChannel, latestVersion: string | null): PackageUpdateInfo;
+export declare function selectPackageUpdateInfo(currentVersion: string, channel: UpdateChannel, stableVersion: string | null, betaVersion?: string | null): PackageUpdateInfo;
 export declare function checkPackageUpdateAsync(currentVersion: string, channel: UpdateChannel, timeoutMs?: number): Promise<PackageUpdateInfo>;
 export declare function checkPackageUpdateSync(currentVersion: string, channel: UpdateChannel, timeoutMs?: number): PackageUpdateInfo;
+export declare function resolveInstalledNpmPrefix(moduleUrl?: string, platform?: NodeJS.Platform): {
+    root: string;
+    prefix: string;
+} | null;
 /**
  * 更新时同时存在旧包备份、npm 正在解包的新版本和下载/回滚余量。
  * 旧包大小按三倍计（安全备份、新包、回滚 staging），再保留 512 MiB，
  * 避免 ENOSPC 把全局 CLI 拆成半包。
  */
 export declare function requiredUpdateFreeBytes(currentInstallBytes: number): number;
+export declare function assertNodeVersionForUpdate(range: string, current?: string): void;
+export declare function checkGlobalUpdateAccess(): boolean;
+export declare function isGlobalUpdateLocked(): boolean;
+/** Only used in the independent helper process; holds the install lock through handoff. */
+export declare function withGlobalUpdateLock<T>(action: () => Promise<T>): Promise<T>;
 /**
  * 异步版本的全局安装：
  * 1. 清理残留
@@ -44,7 +57,11 @@ export declare function requiredUpdateFreeBytes(currentInstallBytes: number): nu
  * @param log 可选 logger，用来把过程写入控制台或前端日志
  * @returns 与本次安装使用同一个 npm root 校验出的 dist/cli.js 绝对路径
  */
-export declare function installPackageGloballyAsync(pkg: string, timeoutMs: number, log?: (line: string) => void): Promise<string>;
+export declare function installPackageGloballyAsync(pkg: string, timeoutMs: number, log?: (line: string) => void, options?: {
+    backupReceiptPath?: string;
+}): Promise<string>;
+/** Keep the old runtime until the new instance actually responds. */
+export declare function finalizeDeferredGlobalUpdate(receiptPath: string, rollback?: boolean, log?: (line: string) => void): boolean;
 /**
  * 同步版本，给 TUI installUpdate 用。
  *

package/dist/npm-update-utils.js

@@ -13,14 +13,15 @@
  */
 import { execFile, spawnSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
-import { chmodSync, cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readlinkSync, realpathSync, readdirSync, renameSync, rmSync, statfsSync, statSync, symlinkSync, } from "node:fs";
+import { accessSync, constants as fsConstants, 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";
+import { fileURLToPath } from "node:url";
 import { buildChildEnv } from "./env-utils.js";
 import { whichSync } from "./path-repair.js";
 import { getErrorMessage } from "./error-utils.js";
-import { compareWandInstallOrder, extractSemver } from "./version-utils.js";
+import { compareSemver, compareWandInstallOrder, extractSemver } from "./version-utils.js";
 import { acquireDeploymentLock, releaseDeploymentLock } from "./deployment-lock.js";
 const execFileAsync = promisify(execFile);
 export const PACKAGE_NAME = "@co0ontty/wand";
@@ -95,14 +96,48 @@ function viewPackageVersionSync(channel, timeoutMs = NPM_VIEW_TIMEOUT_MS) {
     const version = res.stdout.trim();
     return version || null;
 }
+export function selectPackageUpdateInfo(currentVersion, channel, stableVersion, betaVersion = null) {
+    const stable = acceptedVersion(stableVersion, "stable");
+    const beta = channel === "beta" ? acceptedVersion(betaVersion, "beta") : null;
+    const useBeta = beta !== null && (stable === null || compareWandInstallOrder(beta, stable) > 0);
+    const info = buildPackageUpdateInfo(currentVersion, useBeta ? "beta" : "stable", useBeta ? beta : stable);
+    return { ...info, channel, stableVersion: stable, betaVersion: beta };
+}
 export async function checkPackageUpdateAsync(currentVersion, channel, timeoutMs = NPM_VIEW_TIMEOUT_MS) {
-    const latest = await viewPackageVersionAsync(channel, timeoutMs);
-    return buildPackageUpdateInfo(currentVersion, channel, latest);
+    const [stable, beta] = await Promise.all([
+        viewPackageVersionAsync("stable", timeoutMs),
+        channel === "beta" ? viewPackageVersionAsync("beta", timeoutMs) : null,
+    ]);
+    return selectPackageUpdateInfo(currentVersion, channel, stable, beta);
 }
 export function checkPackageUpdateSync(currentVersion, channel, timeoutMs = NPM_VIEW_TIMEOUT_MS) {
-    const latest = viewPackageVersionSync(channel, timeoutMs);
-    return buildPackageUpdateInfo(currentVersion, channel, latest);
+    const stable = viewPackageVersionSync("stable", timeoutMs);
+    const beta = channel === "beta" ? viewPackageVersionSync("beta", timeoutMs) : null;
+    return selectPackageUpdateInfo(currentVersion, channel, stable, beta);
+}
+export function resolveInstalledNpmPrefix(moduleUrl = import.meta.url, platform = process.platform) {
+    try {
+        const packageDir = path.dirname(path.dirname(fileURLToPath(moduleUrl)));
+        let scope = path.dirname(packageDir);
+        // Rollback may briefly boot through the recovery shim. Its retained backup
+        // still belongs to the original npm prefix, not the shell's default prefix.
+        if (/^\.wand-safe-backup-[A-Za-z0-9]+$/.test(path.basename(scope)))
+            scope = path.dirname(scope);
+        const root = path.dirname(scope);
+        if (path.basename(packageDir) !== PACKAGE_BASENAME || path.basename(scope) !== PACKAGE_SCOPE
+            || path.basename(root) !== "node_modules"
+            || JSON.parse(readFileSync(path.join(packageDir, "package.json"), "utf8")).name !== PACKAGE_NAME)
+            return null;
+        const parent = path.dirname(root);
+        if (platform !== "win32" && path.basename(parent) !== "lib")
+            return null;
+        return { root, prefix: platform === "win32" ? parent : path.dirname(parent) };
+    }
+    catch {
+        return null;
+    }
 }
+const INSTALLED_NPM_BINDING = resolveInstalledNpmPrefix();
 function getChildEnv() {
     const entries = [
         path.dirname(process.execPath),
@@ -120,6 +155,7 @@ function getChildEnv() {
     return {
         ...buildChildEnv(true),
         PATH: pathEntries.join(path.delimiter),
+        ...(INSTALLED_NPM_BINDING ? { npm_config_prefix: INSTALLED_NPM_BINDING.prefix } : {}),
     };
 }
 function runNpmSync(args, timeoutMs) {
@@ -143,6 +179,8 @@ async function runNpmAsync(args, timeoutMs) {
  * 解析当前 `npm root -g` 的目录。失败返回 null。
  */
 function getNpmGlobalRoot() {
+    if (INSTALLED_NPM_BINDING)
+        return INSTALLED_NPM_BINDING.root;
     try {
         const res = runNpmSync(["root", "-g"], 10_000);
         if (res.status !== 0)
@@ -155,6 +193,8 @@ function getNpmGlobalRoot() {
     }
 }
 function getNpmGlobalPrefix() {
+    if (INSTALLED_NPM_BINDING)
+        return INSTALLED_NPM_BINDING.prefix;
     try {
         const res = runNpmSync(["prefix", "-g"], 10_000);
         if (res.status !== 0)
@@ -584,18 +624,71 @@ function restoreGlobalInstallBackup(backup, note) {
         return false;
     }
 }
+export function assertNodeVersionForUpdate(range, current = process.versions.node) {
+    const minimum = range.trim().match(/^>=(\d+\.\d+\.\d+)$/)?.[1];
+    if (minimum && compareSemver(current, minimum) < 0) {
+        throw new Error(`新版本要求 Node.js >= ${minimum}（当前 ${current}）。请先升级 Node.js，再执行 README 的 install.sh 恢复更新；旧安装未修改。`);
+    }
+}
+async function checkUpdateNodeVersion(pkg, timeoutMs) {
+    // Registry metadata is checked before creating a backup or replacing any files.
+    // npm --engine-strict remains the authority for other engine range formats.
+    const { stdout } = await execFileAsync(npmBin(), ["view", pkg, "engines.node"], {
+        timeout: Math.min(timeoutMs, NPM_VIEW_TIMEOUT_MS), env: getChildEnv(), maxBuffer: INSTALL_MAX_BUFFER,
+    });
+    assertNodeVersionForUpdate(String(stdout));
+}
 async function npmInstallGlobalAsync(pkg, timeoutMs, extra = []) {
-    await runNpmAsync(["install", "-g", ...extra, pkg], timeoutMs);
+    await runNpmAsync(["install", "-g", "--engine-strict", ...extra, pkg], timeoutMs);
 }
 function isRecoverableInstallError(message) {
     return /ENOTEMPTY|EEXIST|全局 wand 安装不完整|无法解析 npm 全局安装目录|全局 wand CLI 无法设置执行权限|全局 wand 命令入口缺失/.test(message);
 }
+export function checkGlobalUpdateAccess() {
+    const root = getNpmGlobalRoot();
+    const prefix = getNpmGlobalPrefix();
+    if (!root || !prefix)
+        return false;
+    try {
+        for (const dir of [root, path.join(root, PACKAGE_SCOPE), path.join(prefix, "bin")]) {
+            accessSync(nearestExistingAncestor(dir), fsConstants.W_OK);
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function isGlobalUpdateLocked() {
+    const root = getNpmGlobalRoot();
+    return !!root && existsSync(path.join(root, ".wand-update-lock"));
+}
 function acquireGlobalUpdateLock() {
     const root = getNpmGlobalRoot();
     if (!root)
         throw new Error("无法解析 npm 全局安装目录，不能建立更新锁。");
     mkdirSync(path.join(root, PACKAGE_SCOPE), { recursive: true });
-    return acquireDeploymentLock(path.join(root, ".wand-update-lock"));
+    const inherited = process.env.WAND_DEPLOYMENT_LOCKS
+        ? JSON.parse(process.env.WAND_DEPLOYMENT_LOCKS) : [];
+    if (!Array.isArray(inherited))
+        throw new Error("无效的部署锁回执。");
+    return acquireDeploymentLock(path.join(root, ".wand-update-lock"), { inherited });
+}
+/** Only used in the independent helper process; holds the install lock through handoff. */
+export async function withGlobalUpdateLock(action) {
+    const lock = acquireGlobalUpdateLock();
+    const previous = process.env.WAND_DEPLOYMENT_LOCKS;
+    try {
+        process.env.WAND_DEPLOYMENT_LOCKS = JSON.stringify([lock]);
+        return await action();
+    }
+    finally {
+        if (previous === undefined)
+            delete process.env.WAND_DEPLOYMENT_LOCKS;
+        else
+            process.env.WAND_DEPLOYMENT_LOCKS = previous;
+        releaseGlobalUpdateLock(lock);
+    }
 }
 function releaseGlobalUpdateLock(lock) {
     releaseDeploymentLock(lock);
@@ -612,11 +705,12 @@ function releaseGlobalUpdateLock(lock) {
  * @param log 可选 logger，用来把过程写入控制台或前端日志
  * @returns 与本次安装使用同一个 npm root 校验出的 dist/cli.js 绝对路径
  */
-export async function installPackageGloballyAsync(pkg, timeoutMs, log) {
+export async function installPackageGloballyAsync(pkg, timeoutMs, log, options = {}) {
     const note = (line) => {
         if (log)
             log(line);
     };
+    await checkUpdateNodeVersion(pkg, timeoutMs);
     const updateLock = acquireGlobalUpdateLock();
     let backup = null;
     let success = false;
@@ -683,7 +777,11 @@ export async function installPackageGloballyAsync(pkg, timeoutMs, log) {
                 }
             }
             // 恢复失败时绝不能再删唯一完整备份，留给人工恢复。
-            if (backup && (success || restored))
+            if (backup && success && options.backupReceiptPath) {
+                writeFileSync(options.backupReceiptPath, JSON.stringify(backup), { mode: 0o600 });
+                note(`[wand] 旧安装备份保留到启动验证完成: ${backup.backupDir ?? "首次安装"}`);
+            }
+            else if (backup && (success || restored))
                 cleanupGlobalInstallBackup(backup);
         }
         finally {
@@ -691,6 +789,46 @@ export async function installPackageGloballyAsync(pkg, timeoutMs, log) {
         }
     }
 }
+function readDeferredGlobalInstallBackup(receiptPath) {
+    const value = JSON.parse(readFileSync(receiptPath, "utf8"));
+    const packageDir = getGlobalPackageDir();
+    if (!packageDir || value.packageDir !== packageDir || !Array.isArray(value.binEntries)) {
+        throw new Error("更新备份回执与当前安装不一致。");
+    }
+    if (value.backupRoot === null && value.backupDir === null && value.binEntries.length === 0)
+        return value;
+    if (typeof value.backupRoot !== "string" || path.dirname(value.backupRoot) !== path.dirname(packageDir)
+        || !/^\.wand-safe-backup-[A-Za-z0-9]+$/.test(path.basename(value.backupRoot))
+        || value.backupDir !== path.join(value.backupRoot, PACKAGE_BASENAME)
+        || !lstatSync(value.backupRoot).isDirectory() || lstatSync(value.backupRoot).isSymbolicLink()) {
+        throw new Error("更新备份回执无效。");
+    }
+    const expectedBins = new Set(getGlobalWandBinPaths());
+    for (const entry of value.binEntries) {
+        if (!expectedBins.has(entry.originalPath) || path.dirname(entry.backupPath) !== path.join(value.backupRoot, "bin")) {
+            throw new Error("更新入口备份回执无效。");
+        }
+    }
+    return value;
+}
+/** Keep the old runtime until the new instance actually responds. */
+export function finalizeDeferredGlobalUpdate(receiptPath, rollback = false, log) {
+    const lock = acquireGlobalUpdateLock();
+    try {
+        const backup = readDeferredGlobalInstallBackup(receiptPath);
+        if (rollback && !restoreGlobalInstallBackup(backup, log))
+            return false;
+        // A manager may already be starting the old runtime through the recovery
+        // shim. Retain that backup so its late imports remain available.
+        if (!rollback)
+            cleanupGlobalInstallBackup(backup);
+        rmSync(receiptPath, { force: true });
+        return true;
+    }
+    finally {
+        releaseGlobalUpdateLock(lock);
+    }
+}
 /**
  * 同步版本，给 TUI installUpdate 用。
  *
@@ -701,6 +839,10 @@ export function installPackageGloballySync(pkg, timeoutMs) {
     const backupNotes = [];
     let updateLock;
     try {
+        const metadata = runNpmSync(["view", pkg, "engines.node"], Math.min(timeoutMs, NPM_VIEW_TIMEOUT_MS));
+        if (metadata.status === 0)
+            assertNodeVersionForUpdate(metadata.stdout);
+        // Fixtures/old registries may not expose engines; --engine-strict still checks installation.
         updateLock = acquireGlobalUpdateLock();
     }
     catch (err) {
@@ -732,7 +874,7 @@ export function installPackageGloballySync(pkg, timeoutMs) {
         };
     };
     const tryInstall = (extra) => {
-        const args = ["install", "-g", ...extra, pkg];
+        const args = ["install", "-g", "--engine-strict", ...extra, pkg];
         attempts.push(`npm ${args.join(" ")}`);
         const r = runNpmSync(args, timeoutMs);
         return withValidation({

package/dist/object-utils.d.ts

@@ -0,0 +1,2 @@
+/** Non-null objects excluding arrays; retains the existing Date/class-instance behavior. */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;

package/dist/object-utils.js

@@ -0,0 +1,4 @@
+/** Non-null objects excluding arrays; retains the existing Date/class-instance behavior. */
+export function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/pi-event-projection.d.ts

@@ -0,0 +1,8 @@
+/** Fields consumed by Wand's Pi reducer. Context/entries are CLI-owned history,
+ * not new output. Never journal repeated copies of that history in native mode. */
+export declare const PI_PROTOCOL_FIELDS: Set<string>;
+/** agent_end is a reconciliation snapshot, not a second replay of every turn.
+ * The latest assistant owns the final answer, usage and stop/error facts. This
+ * also supports CLIs that emit only the final snapshot (without deltas). */
+export declare function lastPiAssistantMessage(event: Record<string, unknown>): Record<string, unknown> | undefined;
+export declare function projectPiProtocolEvent(event: Record<string, unknown>): Record<string, unknown>;

package/dist/pi-event-projection.js

@@ -0,0 +1,28 @@
+/** Fields consumed by Wand's Pi reducer. Context/entries are CLI-owned history,
+ * not new output. Never journal repeated copies of that history in native mode. */
+export const PI_PROTOCOL_FIELDS = new Set([
+    "type", "id", "message", "assistantMessageEvent", "toolCallId", "toolName",
+    "args", "result", "partialResult", "isError", "messages",
+]);
+/** agent_end is a reconciliation snapshot, not a second replay of every turn.
+ * The latest assistant owns the final answer, usage and stop/error facts. This
+ * also supports CLIs that emit only the final snapshot (without deltas). */
+export function lastPiAssistantMessage(event) {
+    const messages = event.type === "agent_end" && Array.isArray(event.messages) ? event.messages
+        : event.type === "message_end" || event.type === "turn_end" ? [event.message] : [];
+    for (let index = messages.length - 1; index >= 0; index--) {
+        const message = messages[index];
+        if (message && typeof message === "object" && !Array.isArray(message)
+            && message.role === "assistant")
+            return message;
+    }
+    return undefined;
+}
+export function projectPiProtocolEvent(event) {
+    const projected = Object.fromEntries(Object.entries(event).filter(([key]) => PI_PROTOCOL_FIELDS.has(key)));
+    if (event.type === "agent_end" && Array.isArray(event.messages)) {
+        const last = lastPiAssistantMessage(event);
+        projected.messages = last ? [last] : [];
+    }
+    return projected;
+}

package/dist/pi-model-discovery.js

@@ -1,6 +1,7 @@
 import { readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import path from "node:path";
+import { isRecord } from "./object-utils.js";
 const MODEL_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:@/-]{0,127}$/;
 const SUPPORTED_APIS = new Set([
     "anthropic-messages",
@@ -12,9 +13,6 @@ const MAX_PAGES_PER_ENDPOINT = 40;
 const MAX_MODELS_PER_ENDPOINT = 2000;
 const MAX_RESPONSE_BYTES = 2 * 1024 * 1024;
 const REQUEST_TIMEOUT_MS = 10_000;
-function isRecord(value) {
-    return !!value && typeof value === "object" && !Array.isArray(value);
-}
 function resolveConfigValue(value, env) {
     if (typeof value !== "string")
         return null;

package/dist/pi-native-event-bridge.d.ts

@@ -0,0 +1,2 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+export default function wandNativeEvents(pi: ExtensionAPI): void;