@co0ontty/wand 1.25.2 → 1.25.5

package/README.md

@@ -31,6 +31,18 @@ wand web
 
 安装完成后打开浏览器访问终端中提示的地址即可。
 
+### 升级
+
+推荐用同一条一键脚本升级（脚本会自动停掉正在运行的 wand 进程、清理 npm 改名残留再装最新版）：
+
+```bash
+bash <(curl -Ls https://raw.githubusercontent.com/co0ontty/wand/master/install.sh)
+```
+
+> 也可以直接在网页设置里点「更新」按钮，或在 TUI 模式按 `u`，wand 自己会调用同样的清理逻辑。Web 端点击更新后会自动重启服务，无需手动操作。
+
+如果以前装过 systemd 自启服务但还是 `Restart=on-failure`（v1.25.x 前的版本），重新进入 TUI 按一次 `i` 重装服务即可换成 `Restart=always`，自动更新后才能正确拉起新进程。
+
 ## 功能
 
 <p align="center">

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

@@ -0,0 +1,51 @@
+/**
+ * npm 全局更新通用辅助。
+ *
+ * 共用于 server.ts 的 /api/update / performAutoUpdate，以及 TUI 的 installUpdate。
+ *
+ * 解决的核心问题：当 wand 进程正在运行（systemd/launchd/nohup/直接前台都算）时，
+ * `npm install -g @co0ontty/wand@latest` 会把旧包目录 rename 成 `.wand-XXXXXX` 备份。
+ * 如果安装中途失败，这个备份目录会留下，之后每次 npm install 都会因为目标 dest 已存在
+ * 报 `ENOTEMPTY: directory not empty, rename ...`。
+ *
+ * 我们的策略：每次 npm install 之前先清掉 `@co0ontty/.wand-*` 残留目录；
+ * 如果第一次安装仍然撞上 ENOTEMPTY，清理后重试；再不行就 uninstall + force install。
+ */
+/**
+ * 解析当前 `npm root -g` 的目录。失败返回 null。
+ */
+export declare function getNpmGlobalRoot(): string | null;
+/**
+ * 清理上一次 npm install 失败留下的 `.wand-XXXXXX` 残留目录。
+ *
+ * 同步执行，best-effort：找不到 npm root、目录不存在、无权限删除等都不会抛错。
+ * 返回被清理的目录列表，方便调用方记录日志。
+ */
+export declare function cleanupNpmLeftovers(): {
+    removed: string[];
+    errors: string[];
+};
+/**
+ * 异步版本的全局安装：
+ * 1. 清理残留
+ * 2. `npm install -g <pkg>`
+ * 3. 撞上 ENOTEMPTY/EEXIST：再清一次 + 重试一次
+ * 4. 再不行：`npm uninstall -g <pkg-no-tag>` + `npm install -g --force <pkg>`
+ *
+ * @param pkg 包名带版本，例如 `@co0ontty/wand@latest`
+ * @param timeoutMs 单次 npm 调用超时
+ * @param log 可选 logger，用来把过程写入控制台或前端日志
+ */
+export declare function installPackageGloballyAsync(pkg: string, timeoutMs: number, log?: (line: string) => void): Promise<void>;
+/**
+ * 同步版本，给 TUI installUpdate 用。
+ *
+ * 返回值兼容 spawnSync：包含最后一次尝试的 stdout/stderr/status。
+ */
+export declare function installPackageGloballySync(pkg: string, timeoutMs: number): {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+    attempts: string[];
+};
+export declare const NPM_UPDATE_PACKAGE_NAME = "@co0ontty/wand";

package/dist/npm-update-utils.js

@@ -0,0 +1,171 @@
+/**
+ * npm 全局更新通用辅助。
+ *
+ * 共用于 server.ts 的 /api/update / performAutoUpdate，以及 TUI 的 installUpdate。
+ *
+ * 解决的核心问题：当 wand 进程正在运行（systemd/launchd/nohup/直接前台都算）时，
+ * `npm install -g @co0ontty/wand@latest` 会把旧包目录 rename 成 `.wand-XXXXXX` 备份。
+ * 如果安装中途失败，这个备份目录会留下，之后每次 npm install 都会因为目标 dest 已存在
+ * 报 `ENOTEMPTY: directory not empty, rename ...`。
+ *
+ * 我们的策略：每次 npm install 之前先清掉 `@co0ontty/.wand-*` 残留目录；
+ * 如果第一次安装仍然撞上 ENOTEMPTY，清理后重试；再不行就 uninstall + force install。
+ */
+import { exec, spawnSync } from "node:child_process";
+import { existsSync, readdirSync, rmSync, statSync } from "node:fs";
+import path from "node:path";
+import { promisify } from "node:util";
+const execAsync = promisify(exec);
+const PACKAGE_NAME = "@co0ontty/wand";
+const PACKAGE_SCOPE = "@co0ontty";
+const PACKAGE_BASENAME = "wand";
+/**
+ * 解析当前 `npm root -g` 的目录。失败返回 null。
+ */
+export function getNpmGlobalRoot() {
+    try {
+        const res = spawnSync("npm", ["root", "-g"], { encoding: "utf8", timeout: 10_000 });
+        if (res.status !== 0)
+            return null;
+        const out = (res.stdout || "").trim();
+        return out.length > 0 ? out : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 清理上一次 npm install 失败留下的 `.wand-XXXXXX` 残留目录。
+ *
+ * 同步执行，best-effort：找不到 npm root、目录不存在、无权限删除等都不会抛错。
+ * 返回被清理的目录列表，方便调用方记录日志。
+ */
+export function cleanupNpmLeftovers() {
+    const removed = [];
+    const errors = [];
+    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}: ${err instanceof Error ? err.message : String(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);
+        try {
+            // 仅清理目录，避免误删同名文件
+            if (!statSync(fullPath).isDirectory())
+                continue;
+            rmSync(fullPath, { recursive: true, force: true });
+            removed.push(fullPath);
+        }
+        catch (err) {
+            errors.push(`rm ${fullPath}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    return { removed, errors };
+}
+/**
+ * 异步版本的全局安装：
+ * 1. 清理残留
+ * 2. `npm install -g <pkg>`
+ * 3. 撞上 ENOTEMPTY/EEXIST：再清一次 + 重试一次
+ * 4. 再不行：`npm uninstall -g <pkg-no-tag>` + `npm install -g --force <pkg>`
+ *
+ * @param pkg 包名带版本，例如 `@co0ontty/wand@latest`
+ * @param timeoutMs 单次 npm 调用超时
+ * @param log 可选 logger，用来把过程写入控制台或前端日志
+ */
+export async function installPackageGloballyAsync(pkg, timeoutMs, log) {
+    const note = (line) => {
+        if (log)
+            log(line);
+    };
+    const cleanup = cleanupNpmLeftovers();
+    if (cleanup.removed.length > 0) {
+        note(`[wand] 清理 npm 残留目录: ${cleanup.removed.join(", ")}`);
+    }
+    try {
+        await execAsync(`npm install -g ${pkg}`, { timeout: timeoutMs });
+        return;
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        if (!/ENOTEMPTY|EEXIST/.test(msg)) {
+            throw error;
+        }
+        note(`[wand] npm install 遇到 ENOTEMPTY/EEXIST，清理后重试一次...`);
+    }
+    cleanupNpmLeftovers();
+    try {
+        await execAsync(`npm install -g ${pkg}`, { timeout: timeoutMs });
+        return;
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        if (!/ENOTEMPTY|EEXIST/.test(msg)) {
+            throw error;
+        }
+        note(`[wand] 重试仍失败，尝试先卸载再强制安装...`);
+    }
+    // 终极兜底：uninstall + force install
+    const baseName = pkg.replace(/@[^@/]*$/, ""); // strip @latest / @1.2.3
+    try {
+        await execAsync(`npm uninstall -g ${baseName}`, { timeout: timeoutMs });
+    }
+    catch {
+        /* 卸载失败也继续，下一步 --force 可能仍然能装上 */
+    }
+    cleanupNpmLeftovers();
+    await execAsync(`npm install -g --force ${pkg}`, { timeout: timeoutMs });
+}
+/**
+ * 同步版本，给 TUI installUpdate 用。
+ *
+ * 返回值兼容 spawnSync：包含最后一次尝试的 stdout/stderr/status。
+ */
+export function installPackageGloballySync(pkg, timeoutMs) {
+    const attempts = [];
+    const tryInstall = (extra) => {
+        const args = ["install", "-g", ...extra, pkg];
+        attempts.push(`npm ${args.join(" ")}`);
+        const r = spawnSync("npm", args, { encoding: "utf8", timeout: timeoutMs });
+        return {
+            status: r.status,
+            stdout: r.stdout || "",
+            stderr: r.stderr || "",
+        };
+    };
+    cleanupNpmLeftovers();
+    let res = tryInstall([]);
+    if (res.status === 0)
+        return { ...res, attempts };
+    const hitENOTEMPTY = (r) => /ENOTEMPTY|EEXIST/.test(r.stdout + r.stderr);
+    if (!hitENOTEMPTY(res))
+        return { ...res, attempts };
+    cleanupNpmLeftovers();
+    res = tryInstall([]);
+    if (res.status === 0)
+        return { ...res, attempts };
+    if (!hitENOTEMPTY(res))
+        return { ...res, attempts };
+    // 终极兜底
+    const baseName = pkg.replace(/@[^@/]*$/, "");
+    attempts.push(`npm uninstall -g ${baseName}`);
+    spawnSync("npm", ["uninstall", "-g", baseName], { encoding: "utf8", timeout: timeoutMs });
+    cleanupNpmLeftovers();
+    res = tryInstall(["--force"]);
+    return { ...res, attempts };
+}
+export const NPM_UPDATE_PACKAGE_NAME = PACKAGE_NAME;

package/dist/server.js

@@ -21,6 +21,7 @@ import { SessionLogger } from "./session-logger.js";
 import { StructuredSessionManager } from "./structured-session-manager.js";
 import { generatePwaManifest, generateServiceWorker } from "./pwa.js";
 import { getErrorMessage, registerClaudeHistoryRoutes, registerSessionRoutes } from "./server-session-routes.js";
+import { installPackageGloballyAsync } from "./npm-update-utils.js";
 import { registerUploadRoutes } from "./upload-routes.js";
 import { optimizePrompt, PromptOptimizeError } from "./prompt-optimizer.js";
 import { resolveDatabasePath, WandStorage } from "./storage.js";
@@ -1063,23 +1064,13 @@ export async function startServer(config, configPath) {
             res.status(500).json({ error: getErrorMessage(error, "保存证书失败。") });
         }
     });
-    // ── Global npm install with ENOTEMPTY fallback ──
+    // ── Global npm install (with leftover cleanup + ENOTEMPTY fallback) ──
+    // 把所有恢复逻辑下沉到 ./npm-update-utils，TUI 和 server 共用，确保自动更新、
+    // /api/update、tui installUpdate 三处行为一致。
     async function npmInstallGlobal(pkg, timeoutMs) {
-        try {
-            await execAsync(`npm install -g ${pkg}`, { timeout: timeoutMs });
-        }
-        catch (error) {
-            const msg = getErrorMessage(error, "");
-            if (msg.includes("ENOTEMPTY")) {
-                // Running process holds files in the install dir; uninstall first, then reinstall with --force.
-                process.stdout.write(`[wand] npm install 遇到 ENOTEMPTY，尝试先卸载再安装...\n`);
-                await execAsync(`npm uninstall -g ${pkg}`, { timeout: timeoutMs });
-                await execAsync(`npm install -g --force ${pkg}`, { timeout: timeoutMs });
-            }
-            else {
-                throw error;
-            }
-        }
+        await installPackageGloballyAsync(pkg, timeoutMs, (line) => {
+            process.stdout.write(`${line}\n`);
+        });
     }
     app.get("/api/check-update", async (_req, res) => {
         try {
@@ -1104,7 +1095,13 @@ export async function startServer(config, configPath) {
                 return;
             }
             await npmInstallGlobal(`${PKG_NAME}@latest`, 120000);
-            res.json({ ok: true, message: `已更新到 ${latest}，请重启 wand 服务以生效。` });
+            // 装包成功后告知前端可以发起重启；前端会随即调用 /api/restart 完成自动重启。
+            res.json({
+                ok: true,
+                message: `已更新到 ${latest}`,
+                restartRequired: true,
+                version: latest,
+            });
         }
         catch (error) {
             res.status(500).json({ error: getErrorMessage(error, "更新失败。") });

package/dist/structured-session-manager.js

@@ -1177,10 +1177,66 @@ export class StructuredSessionManager {
             const blocksByKey = new Map();
             const keyOrder = [];
             let toolResultSeq = 0;
+            // 估算单个 ContentBlock 的"信息体积"——文字 / thinking / tool input 长度之和。
+            // 用于 upsertBlocks 的防御性合并：同一 message.id 重发时，按位置取信息量更大的
+            // 那个版本，保证已经吐出的文字 / tool_use input 不会被一条更短的同 id 事件
+            // 整段覆盖。
+            const blockVolume = (b) => {
+                if (!b)
+                    return 0;
+                const anyB = b;
+                let total = 0;
+                if (typeof anyB.text === "string")
+                    total += anyB.text.length;
+                if (typeof anyB.thinking === "string")
+                    total += anyB.thinking.length;
+                if (typeof anyB.content === "string")
+                    total += anyB.content.length;
+                if (anyB.input) {
+                    try {
+                        total += JSON.stringify(anyB.input).length;
+                    }
+                    catch (_e) { /* ignore */ }
+                }
+                return total;
+            };
             const upsertBlocks = (key, blocks) => {
-                if (!blocksByKey.has(key))
+                const prev = blocksByKey.get(key);
+                if (!prev) {
                     keyOrder.push(key);
-                blocksByKey.set(key, blocks);
+                    blocksByKey.set(key, blocks);
+                    return;
+                }
+                // claude -p 在同一 message.id 的多次 assistant 事件里**应当**每次发出累加内容。
+                // 但偶发会观察到某次重发只带其中一部分 block（典型场景：text 后又开始一段
+                // tool_use，下一帧 text 字段意外为空字符串），导致先前已渲染的文本被覆盖
+                // 为空——刷新页面后从持久化又恢复出来，就是用户反馈的"显示了又消失"。
+                // 这里按 index 逐块取较"重"的版本，类型一致则取信息量大者，否则信任 incoming
+                // 但**绝不**让 incoming 比 prev 的总块数少（短数组拼接 prev 的尾部）。
+                const merged = [];
+                const maxLen = Math.max(prev.length, blocks.length);
+                for (let i = 0; i < maxLen; i++) {
+                    const a = prev[i];
+                    const b = blocks[i];
+                    if (a && !b) {
+                        merged.push(a);
+                        continue;
+                    }
+                    if (!a && b) {
+                        merged.push(b);
+                        continue;
+                    }
+                    if (a && b) {
+                        if (a.type === b.type) {
+                            merged.push(blockVolume(b) >= blockVolume(a) ? b : a);
+                        }
+                        else {
+                            // 类型变了（极少见，多半是上游 bug）——保留信息量大者，不丢字。
+                            merged.push(blockVolume(b) >= blockVolume(a) ? b : a);
+                        }
+                    }
+                }
+                blocksByKey.set(key, merged);
             };
             const rebuildTurnBlocks = () => {
                 const flat = [];

package/dist/tui/commands.d.ts

@@ -26,7 +26,11 @@ export interface UpdateInfo {
 export declare function checkUpdate(currentVersion: string): UpdateInfo;
 /**
  * 执行 `npm install -g @co0ontty/wand@latest`。
+ *
  * 此调用同步阻塞（TUI 上层应在另一线程的 setImmediate 调度，或直接 await）。
+ * 通过 npm-update-utils 自动处理 `.wand-XXXXXX` 残留目录和 ENOTEMPTY 回退，
+ * 行为与 server.ts 的 /api/update / performAutoUpdate 保持一致。
+ *
  * 返回 npm 输出供调试。
  */
 export declare function installUpdate(): CommandResult;

package/dist/tui/commands.js

@@ -9,6 +9,7 @@ import { existsSync, mkdirSync, writeFileSync, unlinkSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import process from "node:process";
+import { installPackageGloballySync } from "../npm-update-utils.js";
 const PACKAGE_NAME = "@co0ontty/wand";
 // ─── 重启 ────────────────────────────────────────────────────────────────
 /**
@@ -52,26 +53,30 @@ export function checkUpdate(currentVersion) {
 }
 /**
  * 执行 `npm install -g @co0ontty/wand@latest`。
+ *
  * 此调用同步阻塞（TUI 上层应在另一线程的 setImmediate 调度，或直接 await）。
+ * 通过 npm-update-utils 自动处理 `.wand-XXXXXX` 残留目录和 ENOTEMPTY 回退，
+ * 行为与 server.ts 的 /api/update / performAutoUpdate 保持一致。
+ *
  * 返回 npm 输出供调试。
  */
 export function installUpdate() {
-    const res = spawnSync("npm", ["install", "-g", `${PACKAGE_NAME}@latest`], {
-        encoding: "utf8",
-        timeout: 180_000,
-    });
+    const res = installPackageGloballySync(`${PACKAGE_NAME}@latest`, 180_000);
     const out = (res.stdout || "") + (res.stderr ? "\n" + res.stderr : "");
+    const trail = res.attempts.length > 1
+        ? `\n\n尝试过的命令：\n  ${res.attempts.join("\n  ")}`
+        : "";
     if (res.status === 0) {
         return {
             ok: true,
             message: "更新已安装。按 [R] 重启以生效。",
-            detail: out.trim(),
+            detail: (out.trim() + trail).trim(),
         };
     }
     return {
         ok: false,
         message: `npm install 失败 (exit ${res.status})`,
-        detail: out.trim(),
+        detail: (out.trim() + trail).trim(),
     };
 }
 // ─── 打开浏览器 ─────────────────────────────────────────────────────────
@@ -358,6 +363,10 @@ function installSystemdUserService(ctx) {
     const unitPath = servicePath();
     const wandBin = resolveWandBin(ctx);
     const nodeBin = process.execPath;
+    // Restart=always 是关键：自动更新 / /api/restart 走的是 "spawn detached + exit 0"，
+    // 在 systemd 用户服务的 cgroup 下，detached 子进程会随父进程一起被清理（默认
+    // KillMode=control-group），只有 Restart=always 能让 systemd 在 exit 0 后拉起
+    // 新进程，把更新真正生效。
     const unit = [
         "[Unit]",
         "Description=wand web console",
@@ -367,7 +376,7 @@ function installSystemdUserService(ctx) {
         "Type=simple",
         `ExecStart=${nodeBin} ${wandBin} web -c ${ctx.configPath}`,
         `Environment=WAND_NO_TUI=1`,
-        "Restart=on-failure",
+        "Restart=always",
         "RestartSec=3",
         "",
         "[Install]",

package/dist/web-ui/content/scripts.js

@@ -1076,6 +1076,49 @@
           scheduleForegroundSync("android-resume", { immediate: true });
           ensureTerminalFitWithRetry("android-resume");
         });
+
+        // Bridge from Android IME animation. State values: "start" / "shown" / "hidden".
+        // 原生层用 setPadding 在 WebView 父容器上 resize WebView, 视觉上键盘
+        // 动画跟系统同步, 但带来一个副作用: window.innerHeight === visualViewport.height,
+        // 导致 setupVisualViewportHandlers 里的 isKeyboardOpen 检测 (基于
+        // offsetBottom) 永远是 false, 不会进 keyboard-open / keyboard-close 分支,
+        // 终端 forceReplay 路径也就不跑了。
+        //
+        // 这里直接听原生层的"键盘动画收尾"事件, 触发 ensureTerminalFit
+        // (forceReplay=true), 把 wterm 的网格按真实视口重排一遍。
+        window.addEventListener("wand-ime-state", function(e) {
+          var which = e && e.detail && e.detail.state;
+          if (which === "shown" || which === "hidden") {
+            try {
+              ensureTerminalFit("native-ime-" + which, { forceReplay: true });
+              maybeScrollTerminalToBottom("native-ime");
+            } catch (_e) {}
+          }
+        });
+
+        // Bridge from Android ConnectivityManager.NetworkCallback. State values:
+        //   "available"  — 默认网络刚刚可用 (启动期没网 → 接上)
+        //   "changed"    — 已有网络切到另一个 (Wi-Fi ↔ 4G), socket 必死
+        //   "validated"  — captive portal / VPN 验证完成, internet 才真正通
+        //   "lost"       — 默认网络断了, 还没有备援网络
+        // 前三种都强制重连; "lost" 不动 socket, 只更新 isOnline 让 UI 提示。
+        // 这条路径比 navigator.online / visibilitychange 早 2-8 秒触发,
+        // 切网后用户基本看不到断线提示。
+        window.addEventListener("wand-android-network", function(e) {
+          var which = e && e.detail && e.detail.state;
+          if (which === "lost") {
+            state.isOnline = false;
+            try { updateOfflineBanner(); } catch (_e) {}
+            return;
+          }
+          if (which === "available" || which === "changed" || which === "validated") {
+            // 以原生信号为权威, 立刻翻 isOnline 给 UI; 有些 ROM 上
+            // navigator.onLine 要等几秒才更新, 否则 banner 会闪一下。
+            state.isOnline = true;
+            try { updateOfflineBanner(); } catch (_e) {}
+            forceReconnectWebSocket("android-network-" + which);
+          }
+        });
       }
 
       function restoreLoginSession() {
@@ -9156,16 +9199,27 @@
         })
         .then(function(res) { return res.json(); })
         .then(function(data) {
+          if (data.error) {
+            if (msgEl) {
+              msgEl.textContent = data.error;
+              msgEl.style.color = "var(--error)";
+              msgEl.classList.remove("hidden");
+            }
+            updateBtn.disabled = false;
+            return;
+          }
+          // \u5b89\u88c5\u6210\u529f\uff1a\u81ea\u52a8\u8c03\u7528 /api/restart\uff0c\u8ba9\u670d\u52a1\u91cd\u542f\u751f\u6548\uff0c
+          // \u9875\u9762\u4f1a\u88ab restart overlay \u63a5\u624b\uff0c\u7b49\u540e\u7aef\u56de\u6765\u540e\u81ea\u52a8\u5237\u65b0\u3002
           if (msgEl) {
-            msgEl.textContent = data.message || data.error || "\u66f4\u65b0\u5b8c\u6210\u3002";
-            msgEl.style.color = data.error ? "var(--error)" : "var(--success)";
+            msgEl.textContent = (data.message || "\u66f4\u65b0\u5b8c\u6210") + "\uff0c\u6b63\u5728\u91cd\u542f\u670d\u52a1\u2026";
+            msgEl.style.color = "var(--success)";
             msgEl.classList.remove("hidden");
           }
-          if (data.error) {
-            updateBtn.disabled = false;
+          updateBtn.classList.add("hidden");
+          if (data.restartRequired !== false) {
+            performRestart(null, msgEl);
           } else {
-            updateBtn.classList.add("hidden");
-            // Show restart button
+            // \u670d\u52a1\u7aef\u660e\u786e\u8868\u793a\u4e0d\u9700\u8981\u91cd\u542f\uff0c\u4fdd\u7559\u624b\u52a8\u91cd\u542f\u6309\u94ae
             var restartBtn = document.getElementById("do-restart-button");
             if (restartBtn) restartBtn.classList.remove("hidden");
           }
@@ -10867,6 +10921,48 @@
         }
       }
 
+      // 计算一条 ConversationTurn 里所有 content block 的"信息体积"——文字 / 思考 /
+      // tool_result 内容长度之和。用于在 lastMessage 增量更新里判断 incoming 是否
+      // 至少和 localLast 一样完整，防止服务端偶发吐出更短的同 message.id 导致
+      // 已显示的文字段被回退覆盖（"显示了又消失"的根因之一）。
+      function turnContentVolume(turn) {
+        if (!turn || !Array.isArray(turn.content)) return 0;
+        var total = 0;
+        for (var i = 0; i < turn.content.length; i++) {
+          var b = turn.content[i];
+          if (!b) continue;
+          if (typeof b.text === "string") total += b.text.length;
+          if (typeof b.thinking === "string") total += b.thinking.length;
+          if (typeof b.content === "string") total += b.content.length;
+          else if (Array.isArray(b.content)) {
+            for (var k = 0; k < b.content.length; k++) {
+              var sub = b.content[k];
+              if (sub && typeof sub.text === "string") total += sub.text.length;
+            }
+          }
+          if (b.input) {
+            try { total += JSON.stringify(b.input).length; } catch (_e) {}
+          }
+        }
+        return total;
+      }
+
+      // 合并同 role 的 last assistant turn：incoming 通常是权威更新（包含完整 usage、
+      // 完整 block 序列），但偶发的服务端回退会让 incoming 比 local 更短。此时
+      // 保留本地内容——下一次正常 emit 会校正。usage 字段以 incoming 优先（因为
+      // 那是 result event 给的最终值）。
+      function mergeAssistantTurn(localLast, incoming) {
+        if (!localLast) return incoming;
+        if (!incoming) return localLast;
+        var localVol = turnContentVolume(localLast);
+        var incVol = turnContentVolume(incoming);
+        if (incVol >= localVol) return incoming;
+        // incoming 更短：保留 local 的 content，但允许 incoming 更新 usage / 元字段。
+        return Object.assign({}, localLast, {
+          usage: incoming.usage || localLast.usage,
+        });
+      }
+
       // Append queued user message placeholders to currentMessages so they
       // remain visible across WS updates and re-renders.
       function buildMessagesForRender(session, messages) {
@@ -12868,20 +12964,31 @@
             // 这里在 visualViewport 检测到键盘收起的瞬间直接强制复位一次，
             // 并把 --app-viewport-height 兜底清掉，确保 .app-container 回到
             // 100dvh、input-panel 重新贴屏幕底部。
+            //
+            // Android APK (window.__wandImeNative=true) 跳过这段 iOS hack —
+            // MainActivity 已经在 IME 动画 callback 里逐帧把 root setPadding,
+            // WebView 直接被原生层 resize 推回到了正确位置, 这里再调
+            // scrollTo(0,0) 反而会跟原生 padding 打架, 偶尔产生一帧抖。
+            // 只保留 refit / 滚底两个纯展示动作。
             var rootEl = document.documentElement;
-            rootEl.style.removeProperty('--app-viewport-height');
-            window.scrollTo(0, 0);
-            if (document.scrollingElement) document.scrollingElement.scrollTop = 0;
-            rootEl.scrollTop = 0;
-            if (document.body) document.body.scrollTop = 0;
-            setTimeout(function() {
-              // 二次复位：等键盘收起动画 + iOS 自身的回滚跑完后再清一次，
-              // 防止 iOS 在动画过程中又把 scrollTop 推上去。
+            var imeIsNative = !!window.__wandImeNative;
+            if (!imeIsNative) {
+              rootEl.style.removeProperty('--app-viewport-height');
               window.scrollTo(0, 0);
               if (document.scrollingElement) document.scrollingElement.scrollTop = 0;
               rootEl.scrollTop = 0;
               if (document.body) document.body.scrollTop = 0;
-              syncAppViewportHeight();
+            }
+            setTimeout(function() {
+              if (!imeIsNative) {
+                // 二次复位：等键盘收起动画 + iOS 自身的回滚跑完后再清一次，
+                // 防止 iOS 在动画过程中又把 scrollTop 推上去。
+                window.scrollTo(0, 0);
+                if (document.scrollingElement) document.scrollingElement.scrollTop = 0;
+                rootEl.scrollTop = 0;
+                if (document.body) document.body.scrollTop = 0;
+                syncAppViewportHeight();
+              }
               ensureTerminalFit("keyboard-close", { forceReplay: true });
               maybeScrollTerminalToBottom("force");
             }, 200);
@@ -13500,23 +13607,30 @@
                 snapshot.sessionKind = msg.data.sessionKind;
               }
 
-              if (isIncremental && msg.data.lastMessage) {
+              // 优先级修正：若同一事件里同时带 messages（全量）和 lastMessage（增量），
+              // 让全量赢。WS 端的 debounce 已经会在跨形状时 flush，但保留这层
+              // 客户端兜底，避免任何上游再合并出双载体事件时再次丢消息。
+              if (msg.data.messages) {
+                // Full mode (authoritative)
+                snapshot.messages = msg.data.messages;
+              } else if (isIncremental && msg.data.lastMessage) {
                 // Incremental mode: merge lastMessage into existing session messages
                 var existingSession = state.sessions.find(function(s) { return s.id === msg.sessionId; });
                 if (existingSession) {
                   var msgs = Array.isArray(existingSession.messages) ? existingSession.messages.slice() : [];
                   var expectedCount = msg.data.messageCount || 0;
-                  // Replace last turn if same role, or append if new turn
-                  if (msgs.length > 0 && msg.data.lastMessage.role && msgs[msgs.length - 1].role === msg.data.lastMessage.role) {
-                    msgs[msgs.length - 1] = msg.data.lastMessage;
+                  // 防御性合并：lastMessage 应当至少和本地最后一条一样长。如果服务端
+                  // 因为上游 bug（如 upsertBlocks 整段覆盖）回退发来一条更短的同 role
+                  // 消息，保留本地版本——文字会被刷新或下一次 emit 修正。
+                  var localLast = msgs.length > 0 ? msgs[msgs.length - 1] : null;
+                  var incoming = msg.data.lastMessage;
+                  if (localLast && incoming.role && localLast.role === incoming.role) {
+                    msgs[msgs.length - 1] = mergeAssistantTurn(localLast, incoming);
                   } else if (msgs.length < expectedCount) {
-                    msgs.push(msg.data.lastMessage);
+                    msgs.push(incoming);
                   }
                   snapshot.messages = msgs;
                 }
-              } else if (!isIncremental && msg.data.messages) {
-                // Full mode (backward compatible)
-                snapshot.messages = msg.data.messages;
               }
 
               // Fast path: chunk-only incremental events skip expensive chat update
@@ -14299,7 +14413,11 @@
         var renderWasAtBottom = isChatNearBottom(chatMessages);
         if (renderWasAtBottom) state.chatStickToBottom = true;
 
-        var existingCount = chatMessages.querySelectorAll(".chat-message").length;
+        // 把 .system-info 卡片从计数里剔除——它由 extractPtySystemInfo 在
+        // fullRenderChat 里穿插注入，不存在于 messages 数组中，混进 existingCount
+        // 会让 msgCount !== existingCount 永远为真，每帧都走 fullRenderChat，从而
+        // 不断 wipe innerHTML，触发"莫名其妙跳到最上面"的视觉错位。
+        var existingCount = chatMessages.querySelectorAll(".chat-message:not(.system-info)").length;
         // Full render when: forced, no existing messages, or message count decreased/changed
         var needsFullRender = forceRender || existingCount === 0 || msgCount !== existingCount;
 
@@ -14347,6 +14465,29 @@
             '</div>';
           }
 
+          // 在 innerHTML 整段重写前，先记下当前视口里"最靠近顶部边缘"的那条消息
+          // 的 data-msg-index 和它到容器顶部的偏移。重写完成后找到同一 data-msg-index
+          // 的新节点，把它放回原来的偏移——这是 column-reverse 下保住用户视线的
+          // 标准锚点法。没有锚点时（首次渲染、空 → 非空）才走 scrollTop=0 兜底。
+          var anchorMsgIndex = -1;
+          var anchorOffset = 0;
+          if (prevMsgCount > 0 && !renderWasAtBottom) {
+            var containerTop = chatMessages.getBoundingClientRect().top;
+            var preEls = chatMessages.querySelectorAll(".chat-message:not(.system-info)");
+            for (var pi = 0; pi < preEls.length; pi++) {
+              var rect = preEls[pi].getBoundingClientRect();
+              // 第一条 top >= containerTop 的就是视口内最靠上的可见消息
+              if (rect.bottom >= containerTop) {
+                var idxAttr = preEls[pi].getAttribute("data-msg-index");
+                if (idxAttr != null) {
+                  anchorMsgIndex = parseInt(idxAttr, 10);
+                  anchorOffset = rect.top - containerTop;
+                }
+                break;
+              }
+            }
+          }
+
           chatMessages.innerHTML = html;
           // 给每条消息打 data-msg-index（用 state.currentMessages 的全局索引），
           // 后面 refreshChatUnreadDivider 用它找未读分割线的位置。
@@ -14371,6 +14512,21 @@
             // 同一会话内的全量重渲染：用户原本贴底就保持贴底，浏览器在 innerHTML
             // 重置后可能把 scrollTop 钳到一个奇怪的值，这里显式拉回 0。
             chatMessages.scrollTop = 0;
+          } else if (anchorMsgIndex >= 0) {
+            // 用户当前不在底部——根据保存的锚点恢复视图位置，避免被"踢到最上面"。
+            var newAnchor = chatMessages.querySelector(
+              '.chat-message[data-msg-index="' + anchorMsgIndex + '"]'
+            );
+            if (newAnchor) {
+              var newContainerTop = chatMessages.getBoundingClientRect().top;
+              var newRect = newAnchor.getBoundingClientRect();
+              var delta = (newRect.top - newContainerTop) - anchorOffset;
+              if (Math.abs(delta) > 0.5) {
+                state.chatIsProgrammaticScroll = true;
+                chatMessages.scrollTop += delta;
+                requestAnimationFrame(function() { state.chatIsProgrammaticScroll = false; });
+              }
+            }
           }
           attachAllCopyHandlers(chatMessages);
           bindChatScrollListener();
@@ -14530,7 +14686,10 @@
           // Optimization: only re-render the newest N messages (column-reverse: first children)
           // that actually differ, starting from the top (newest). Most streaming updates only
           // touch the latest assistant turn, so we can skip scanning all older messages.
-          var existingEls = Array.from(chatMessages.querySelectorAll(".chat-message"));
+          // 同样剔除 system-info 卡片，否则 existingEls 长度对不上 reversedMessages，
+          // top-N 对照会拿 system-info 卡片去比真消息的 HTML，永远 replacedAny=false，
+          // 触发 fullRenderChat 兜底分支——这是滚动跳顶的另一条触发路径。
+          var existingEls = Array.from(chatMessages.querySelectorAll(".chat-message:not(.system-info)"));
           var reversedMessages = messages.slice().reverse();
           var replacedAny = false;
           // Scan from newest (index 0 in reversed) up to MAX_STREAMING_SCAN messages
@@ -17649,29 +17808,29 @@
           })
           .then(function(res) { return res.json(); })
           .then(function(data) {
-            setProgress(false);
-            card.classList.remove("is-busy");
             if (data.error) {
               // Update failed
+              setProgress(false);
+              card.classList.remove("is-busy");
               setSubtitle("\u66f4\u65b0\u672a\u5b8c\u6210");
               setStatus(data.error, "error");
               actionBtn.disabled = false;
               if (actionLabel) actionLabel.textContent = "\u91cd\u8bd5";
               return;
             }
-            // Phase 2: Update succeeded, show restart button
-            setSubtitle(data.message || "\u66f4\u65b0\u5b8c\u6210\uff0c\u91cd\u542f\u540e\u751f\u6548");
-            setStatus("");
+            // Phase 2: \u5b89\u88c5\u6210\u529f\uff0c\u81ea\u52a8\u8c03\u7528 /api/restart\uff0c\u7531 restart overlay \u63a5\u7ba1 UX\u3002
             card.classList.add("is-success");
-            if (actionLabel) actionLabel.textContent = "\u91cd\u542f\u751f\u6548";
-            actionBtn.disabled = false;
-            actionBtn.onclick = function() {
-              actionBtn.disabled = true;
-              if (actionLabel) actionLabel.textContent = "\u6b63\u5728\u91cd\u542f\u2026";
-              setSubtitle("\u670d\u52a1\u6b63\u5728\u91cd\u542f\u2026");
-              setProgress(true);
-              performRestartCard(actionBtn, actionLabel, subtitleEl, statusEl, progressEl);
-            };
+            setSubtitle((data.message || "\u66f4\u65b0\u5b8c\u6210") + "\uff0c\u6b63\u5728\u91cd\u542f\u670d\u52a1\u2026");
+            setStatus("");
+            if (actionLabel) actionLabel.textContent = "\u6b63\u5728\u91cd\u542f\u2026";
+            if (data.restartRequired === false) {
+              setProgress(false);
+              card.classList.remove("is-busy");
+              actionBtn.disabled = false;
+              if (actionLabel) actionLabel.textContent = "\u5df2\u5b8c\u6210";
+              return;
+            }
+            performRestartCard(actionBtn, actionLabel, subtitleEl, statusEl, progressEl);
           })
           .catch(function() {
             setProgress(false);

package/dist/ws-broadcast.js

@@ -78,23 +78,46 @@ export class WsBroadcastManager {
         if (event.type === "output") {
             const existing = this.outputDebounceCache.get(event.sessionId);
             if (existing) {
-                clearTimeout(existing.timer);
-                // Merge prev + cur. Cur takes precedence for identically-named fields,
-                // but fields only present on prev (e.g. chunk while cur carries
-                // messages, or messages while cur carries chunk) survive — the old
-                // implementation silently dropped them.
                 const prevData = existing.event.data ?? {};
                 const curData = event.data ?? {};
-                const merged = { ...prevData, ...curData };
-                const prevChunk = prevData.chunk;
-                const curChunk = curData.chunk;
-                if (prevChunk && curChunk) {
-                    merged.chunk = prevChunk + curChunk;
+                // 跨"事件形状"不能简单 shallow-merge：
+                //   - 全量事件（带 messages）+ 增量事件（带 lastMessage，不带 messages）
+                //     合并后变成 { messages, incremental: true, lastMessage }。客户端
+                //     reducer 看到 incremental 就只读 lastMessage，把权威的 messages 丢掉，
+                //     表现是"刷新页面才出来的消失文字"。
+                //   - 反过来：增量在前，全量在后，cur 覆盖 prev 后 incremental 仍为 true
+                //     而 messages 来自 cur——这种顺序原本是安全的，但风险一致就一起处理。
+                // 形状不一致时 flush 上一条立即广播，新事件单独开窗口。这样客户端永远
+                // 不会在一条 WS 消息里同时看到 messages 和 lastMessage 两种语义。
+                const prevHasMessages = "messages" in prevData && prevData.messages !== undefined;
+                const prevHasLastMsg = "lastMessage" in prevData && prevData.lastMessage !== undefined;
+                const curHasMessages = "messages" in curData && curData.messages !== undefined;
+                const curHasLastMsg = "lastMessage" in curData && curData.lastMessage !== undefined;
+                const shapeMismatch = (prevHasMessages && curHasLastMsg && !curHasMessages) ||
+                    (prevHasLastMsg && curHasMessages && !curHasLastMsg);
+                if (shapeMismatch) {
+                    clearTimeout(existing.timer);
+                    this.outputDebounceCache.delete(event.sessionId);
+                    this.broadcast(existing.event);
+                    // Fall through to schedule cur on a fresh debounce window
                 }
-                else if (prevChunk && !curChunk) {
-                    merged.chunk = prevChunk;
+                else {
+                    clearTimeout(existing.timer);
+                    // Merge prev + cur. Cur takes precedence for identically-named fields,
+                    // but fields only present on prev (e.g. chunk while cur carries
+                    // messages, or messages while cur carries chunk) survive — the old
+                    // implementation silently dropped them.
+                    const merged = { ...prevData, ...curData };
+                    const prevChunk = prevData.chunk;
+                    const curChunk = curData.chunk;
+                    if (prevChunk && curChunk) {
+                        merged.chunk = prevChunk + curChunk;
+                    }
+                    else if (prevChunk && !curChunk) {
+                        merged.chunk = prevChunk;
+                    }
+                    event = { ...event, data: merged };
                 }
-                event = { ...event, data: merged };
             }
             const timer = setTimeout(() => {
                 this.outputDebounceCache.delete(event.sessionId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@co0ontty/wand",
-  "version": "1.25.2",
+  "version": "1.25.5",
   "description": "A web terminal for local CLI tools like Claude.",
   "type": "module",
   "bin": {