@co0ontty/wand 1.32.2 → 1.33.0

package/dist/path-repair.d.ts

@@ -0,0 +1,78 @@
+/**
+ * 运行时 PATH 自修复。
+ *
+ * 背景：用户把 wand 装成 systemd / launchd 服务时，service unit 文件里的 PATH
+ * 是"安装那一刻"的快照（见 src/tui/commands.ts:buildServicePath）。之后：
+ *   - 用户切 node 版本（nvm/fnm/volta），claude 装到新的 bin 目录；
+ *   - 或 `npm install -g @co0ontty/wand` 重装，但没重新跑 `wand service:install`，
+ *     install.sh 只 `systemctl start`，unit 里的 PATH 一直是老的；
+ *   - 或 claude 装到 `~/.bun/bin`、`~/.local/bin` 等当时不在 PATH 里的位置。
+ *
+ * 服务进程的 process.env.PATH 就是这份陈旧快照。process-manager 给 PTY 子进程
+ * 用 buildChildEnv(inheritEnv=true) 时把这份 PATH 直接透传，于是 spawn 出来的
+ * shell 里 `claude` 找不到 → "command not found"。
+ *
+ * 修复分两层（都在 startServer() 开头跑）：
+ *   1. repairRuntimePath()（同步、cheap）：扫常见工具链 bin 目录，把存在但 PATH
+ *      里缺的"追加"到 process.env.PATH 末尾。
+ *   2. deepRepairRuntimePath()（异步、贵一点）：起一个 login shell 拉用户实际的
+ *      PATH（覆盖 ~/.bashrc、~/.zshrc、nvm/fnm/volta 的 shell-init 等所有动态
+ *      逻辑），把里面 PATH 里我们还没的目录"前插"到 process.env.PATH 前面。这
+ *      是真正能修好"unit 里 PATH 太旧、用户 shell 里却好好的"这种场景的关键。
+ *
+ * 设计决策：
+ *   - 同步那层只追加不前插：尊重用户已有顺序；异步那层愿意前插，因为它拿到的是
+ *     用户实际"会用的"PATH，比 unit 里的更可信。
+ *   - 只加 existsSync 真实存在的：避免 PATH 里塞一堆死路径。
+ *   - 用 path.delimiter：Windows 用 `;`，POSIX 用 `:`，跨平台安全。
+ *   - 不重写 service unit：那需要 sudo，且语义太重；只在 install.sh 主动调
+ *     `wand service:install` 时才重新烧 PATH。
+ *   - login shell 用 -lc 跑，4 秒超时；失败就静默走同步路径，不阻塞启动。
+ *
+ * WAND_PATH_REPAIR_DISABLE=1 可以彻底关掉同步那层（极端情况下用户想完全控制 PATH 时用）。
+ * WAND_PATH_REPAIR_DEEP_DISABLE=1 只关掉 login shell 探测，但保留同步追加。
+ */
+export interface PathRepairResult {
+    /** 实际新追加进 PATH 的目录（按追加顺序）。 */
+    added: string[];
+    /** 关键命令的解析结果（PATH 修复后 `which` 出来的）。null = 没找到。 */
+    resolved: Record<string, string | null>;
+    /** 修复后的 PATH 整体；调试用。 */
+    finalPath: string;
+    /** login shell 探测阶段的状态：success / disabled / failed / skipped。 */
+    deepProbe: "success" | "disabled" | "failed" | "skipped";
+    /** 异步阶段产生的告警信息（login shell 超时、解析失败等）。 */
+    warnings: string[];
+}
+/**
+ * 把候选目录中"存在 + 未在 PATH 中"的追加到 process.env.PATH。
+ *
+ * 不会去重已经在 PATH 里的项（即使顺序不理想也保持原样），只往末尾补。
+ */
+export declare function repairRuntimePath(): PathRepairResult;
+/**
+ * 在 repairRuntimePath() 同步追加完之后，再用 login shell 拉一份用户实际的 PATH
+ * 合并进来。这是真正能修好"unit 里 PATH 太旧、用户 shell 里 claude 好好的"那种
+ * 升级回归的关键——同步阶段只能扫已知路径，login shell 才能拿到 nvm/fnm/volta
+ * 这种动态注入的 PATH。
+ *
+ * 行为：
+ *   - 跑 `${shell} -l -c '...'` 拉 $PATH 和 command -v claude/codex（4s 超时）
+ *   - 把 login shell PATH 里我们还没收录的目录 **前插** 到 process.env.PATH（注意
+ *     是前插，不是追加 —— 它比 unit 里的更可信）
+ *   - 失败时静默走同步那一版结果
+ *
+ * 接受一个已经跑过同步阶段的 result，在上面 mutate。
+ */
+export declare function deepRepairRuntimePath(result: PathRepairResult, opts?: {
+    shell?: string;
+    timeoutMs?: number;
+}): Promise<PathRepairResult>;
+/**
+ * 把修复结果格式化为一行可读摘要（startServer 启动日志用）。
+ *
+ * 例：
+ *   `[wand] PATH augmented (+3 dirs); claude=/usr/local/bin/claude, codex=<missing>`
+ *   `[wand] PATH already complete; claude=/Users/foo/.bun/bin/claude`
+ */
+export declare function formatPathRepairSummary(result: PathRepairResult): string;

package/dist/path-repair.js

@@ -0,0 +1,374 @@
+import { existsSync, readdirSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+import { spawn, spawnSync } from "node:child_process";
+/** 关键的 CLI 工具，会被诊断输出。 */
+const PROBE_COMMANDS = ["claude", "codex"];
+const DEEP_PROBE_TIMEOUT_MS = 4000;
+/**
+ * 构造候选 bin 目录列表（按优先级，前面的更可信）。
+ *
+ * 顺序原则：
+ *   1. 当前 node 的 bin 目录（claude 大概率就装这里：`npm install -g claude` 把 bin
+ *      放在与 node 同 prefix 的 bin 目录）；
+ *   2. 用户级常见 npm-global / 语言工具链路径；
+ *   3. Homebrew（macOS）；
+ *   4. /usr/local/... 等系统标准路径兜底。
+ */
+function candidateBinDirs() {
+    const home = os.homedir();
+    const nodeBinDir = path.dirname(process.execPath);
+    const candidates = [
+        nodeBinDir,
+        path.join(home, ".npm-global", "bin"),
+        path.join(home, ".local", "bin"),
+        path.join(home, "bin"),
+        path.join(home, ".bun", "bin"),
+        path.join(home, ".volta", "bin"),
+        path.join(home, ".cargo", "bin"),
+        path.join(home, ".deno", "bin"),
+        path.join(home, ".pnpm"),
+        path.join(home, "Library", "pnpm"), // pnpm 在 macOS 默认这里
+    ];
+    // nvm / fnm / n 这种多版本管理器：扫最新几个 node 版本的 bin 目录加进去。
+    // 不会拿单一"激活"版本（service 进程拿不到 shell init），所以宁可多塞几个；
+    // 重复目录会在 repairRuntimePath() 的 Set 里被去重。
+    for (const dir of scanNodeVersionManagerBins(home))
+        candidates.push(dir);
+    if (process.platform === "darwin") {
+        candidates.push("/opt/homebrew/bin", "/opt/homebrew/sbin");
+    }
+    candidates.push("/usr/local/sbin", "/usr/local/bin", "/usr/sbin", "/usr/bin", "/sbin", "/bin");
+    return candidates;
+}
+/**
+ * 扫各种 node 版本管理器的 bin 目录。返回的路径都不带 versions/<v>/bin 检查——
+ * 调用方负责 existsSync 过滤。
+ *
+ * 覆盖：
+ *   - nvm:        ~/.nvm/versions/node/<v>/bin
+ *   - fnm:        ~/.local/share/fnm/node-versions/<v>/installation/bin 或
+ *                 ~/Library/Application Support/fnm/node-versions/<v>/installation/bin
+ *   - n（tj/n）:  /usr/local/n/versions/node/<v>/bin
+ */
+function scanNodeVersionManagerBins(home) {
+    const results = [];
+    // nvm
+    const nvmBase = path.join(home, ".nvm", "versions", "node");
+    for (const v of listLatestVersions(nvmBase, 4)) {
+        results.push(path.join(nvmBase, v, "bin"));
+    }
+    // fnm（Linux 默认 / macOS 默认）
+    const fnmCandidates = [
+        path.join(home, ".local", "share", "fnm", "node-versions"),
+        path.join(home, "Library", "Application Support", "fnm", "node-versions"),
+    ];
+    for (const fnmBase of fnmCandidates) {
+        for (const v of listLatestVersions(fnmBase, 4)) {
+            results.push(path.join(fnmBase, v, "installation", "bin"));
+        }
+    }
+    // tj/n
+    const nBase = "/usr/local/n/versions/node";
+    for (const v of listLatestVersions(nBase, 4)) {
+        results.push(path.join(nBase, v, "bin"));
+    }
+    return results;
+}
+/** 列出 base 下"看起来像 node 版本号"的目录，按 semver 降序取前 N 个。 */
+function listLatestVersions(base, limit) {
+    if (!existsSync(base))
+        return [];
+    try {
+        const entries = readdirSync(base);
+        return entries
+            .filter((e) => /^v?\d+\.\d+\.\d+/.test(e))
+            .sort((a, b) => semverCompare(b, a))
+            .slice(0, limit);
+    }
+    catch {
+        return [];
+    }
+}
+function semverCompare(a, b) {
+    const pa = a.replace(/^v/, "").split(/[.\-+]/).map((x) => Number(x) || 0);
+    const pb = b.replace(/^v/, "").split(/[.\-+]/).map((x) => Number(x) || 0);
+    for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+        const da = pa[i] ?? 0;
+        const db = pb[i] ?? 0;
+        if (da !== db)
+            return da - db;
+    }
+    return 0;
+}
+/**
+ * 把候选目录中"存在 + 未在 PATH 中"的追加到 process.env.PATH。
+ *
+ * 不会去重已经在 PATH 里的项（即使顺序不理想也保持原样），只往末尾补。
+ */
+export function repairRuntimePath() {
+    if (process.env.WAND_PATH_REPAIR_DISABLE === "1") {
+        return {
+            added: [],
+            resolved: probeCommands(),
+            finalPath: process.env.PATH ?? "",
+            deepProbe: "disabled",
+            warnings: [],
+        };
+    }
+    const delim = path.delimiter;
+    const currentPath = process.env.PATH ?? "";
+    const existing = new Set(currentPath
+        .split(delim)
+        .map((seg) => seg.trim())
+        .filter((seg) => seg.length > 0));
+    const added = [];
+    for (const dir of candidateBinDirs()) {
+        if (!dir || existing.has(dir))
+            continue;
+        // existsSync 不抛错，权限不够 / 路径里有 EACCES 都返回 false，安全。
+        let ok = false;
+        try {
+            ok = existsSync(dir);
+        }
+        catch {
+            ok = false;
+        }
+        if (!ok)
+            continue;
+        existing.add(dir);
+        added.push(dir);
+    }
+    if (added.length > 0) {
+        const suffix = added.join(delim);
+        process.env.PATH = currentPath
+            ? `${currentPath}${delim}${suffix}`
+            : suffix;
+    }
+    return {
+        added,
+        resolved: probeCommands(),
+        finalPath: process.env.PATH ?? "",
+        deepProbe: "skipped",
+        warnings: [],
+    };
+}
+/**
+ * 在 repairRuntimePath() 同步追加完之后，再用 login shell 拉一份用户实际的 PATH
+ * 合并进来。这是真正能修好"unit 里 PATH 太旧、用户 shell 里 claude 好好的"那种
+ * 升级回归的关键——同步阶段只能扫已知路径，login shell 才能拿到 nvm/fnm/volta
+ * 这种动态注入的 PATH。
+ *
+ * 行为：
+ *   - 跑 `${shell} -l -c '...'` 拉 $PATH 和 command -v claude/codex（4s 超时）
+ *   - 把 login shell PATH 里我们还没收录的目录 **前插** 到 process.env.PATH（注意
+ *     是前插，不是追加 —— 它比 unit 里的更可信）
+ *   - 失败时静默走同步那一版结果
+ *
+ * 接受一个已经跑过同步阶段的 result，在上面 mutate。
+ */
+export async function deepRepairRuntimePath(result, opts = {}) {
+    if (process.env.WAND_PATH_REPAIR_DISABLE === "1") {
+        result.deepProbe = "disabled";
+        return result;
+    }
+    if (process.env.WAND_PATH_REPAIR_DEEP_DISABLE === "1") {
+        result.deepProbe = "disabled";
+        return result;
+    }
+    const shell = pickProbeShell(opts.shell);
+    if (!shell) {
+        result.warnings.push("跳过 login shell 探测：未找到可用 shell");
+        result.deepProbe = "skipped";
+        return result;
+    }
+    let probe;
+    try {
+        probe = await probeLoginShell(shell, opts.timeoutMs ?? DEEP_PROBE_TIMEOUT_MS);
+    }
+    catch (err) {
+        result.warnings.push(`login shell 探测失败 (${shell}): ${err instanceof Error ? err.message : String(err)}`);
+        result.deepProbe = "failed";
+        return result;
+    }
+    const delim = path.delimiter;
+    const existing = new Set((process.env.PATH ?? "")
+        .split(delim)
+        .map((seg) => seg.trim())
+        .filter((seg) => seg.length > 0));
+    // login shell 报告的所有 PATH 段 + claude/codex 解析出的目录都纳入候选。
+    const fromShell = [];
+    for (const seg of probe.path.split(delim).map((s) => s.trim()).filter(Boolean)) {
+        fromShell.push(seg);
+    }
+    if (probe.claude)
+        fromShell.push(path.dirname(probe.claude));
+    if (probe.codex)
+        fromShell.push(path.dirname(probe.codex));
+    const additions = [];
+    for (const dir of fromShell) {
+        if (!dir || existing.has(dir))
+            continue;
+        let ok = false;
+        try {
+            ok = existsSync(dir);
+        }
+        catch {
+            ok = false;
+        }
+        if (!ok)
+            continue;
+        existing.add(dir);
+        additions.push(dir);
+    }
+    if (additions.length > 0) {
+        // 前插：login shell 的 PATH 优先级比 unit 写死的高，让 claude 解析到用户期望的版本。
+        const prefix = additions.join(delim);
+        const currentPath = process.env.PATH ?? "";
+        process.env.PATH = currentPath ? `${prefix}${delim}${currentPath}` : prefix;
+        result.added.push(...additions);
+    }
+    result.finalPath = process.env.PATH ?? "";
+    // 修复完再 probe 一次，让 resolved 字段反映最终能找到的位置（之前 sync 阶段
+    // 可能 claude 还是 missing，login shell 注入 nvm 目录后这次能命中）。
+    result.resolved = probeCommands();
+    result.deepProbe = "success";
+    return result;
+}
+function pickProbeShell(configured) {
+    const candidates = [
+        configured,
+        process.env.SHELL,
+        "/bin/bash",
+        "/usr/bin/bash",
+        "/bin/zsh",
+        "/usr/bin/zsh",
+        "/bin/sh",
+    ].filter((s) => typeof s === "string" && s.length > 0);
+    for (const c of candidates) {
+        if (existsSync(c))
+            return c;
+    }
+    return null;
+}
+/**
+ * 用 login shell 跑一段最小脚本，拿到用户实际的 PATH 和 claude/codex 解析路径。
+ * 用 \x1f（ASCII Unit Separator）作字段分隔符避免和路径里的字符冲突。
+ */
+function probeLoginShell(shell, timeoutMs) {
+    const script = `printf 'PATH\\x1f%s\\n' "$PATH"; ` +
+        `printf 'CLAUDE\\x1f%s\\n' "$(command -v claude 2>/dev/null)"; ` +
+        `printf 'CODEX\\x1f%s\\n' "$(command -v codex 2>/dev/null)"`;
+    return new Promise((resolve, reject) => {
+        const child = spawn(shell, ["-l", "-c", script], {
+            env: {
+                ...process.env,
+                // 防止 PROMPT_COMMAND / PS1 等钩子往 stdout 喷东西干扰解析
+                PS1: "",
+                PROMPT_COMMAND: "",
+            },
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        let settled = false;
+        const finalize = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            fn();
+        };
+        const timer = setTimeout(() => {
+            try {
+                child.kill("SIGTERM");
+            }
+            catch { /* noop */ }
+            finalize(() => reject(new Error(`login shell probe timed out after ${timeoutMs}ms`)));
+        }, timeoutMs);
+        child.stdout?.on("data", (b) => { stdout += b.toString(); });
+        child.stderr?.on("data", (b) => { stderr += b.toString(); });
+        child.on("error", (err) => {
+            clearTimeout(timer);
+            finalize(() => reject(err));
+        });
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            finalize(() => {
+                if (!stdout && code !== 0) {
+                    reject(new Error(`login shell exited ${code}: ${stderr.trim().slice(0, 200)}`));
+                    return;
+                }
+                const out = { path: "", claude: null, codex: null };
+                for (const line of stdout.split("\n")) {
+                    const idx = line.indexOf("\x1f");
+                    if (idx < 0)
+                        continue;
+                    const key = line.slice(0, idx);
+                    const val = line.slice(idx + 1).trim();
+                    if (!val)
+                        continue;
+                    if (key === "PATH")
+                        out.path = val;
+                    else if (key === "CLAUDE")
+                        out.claude = val;
+                    else if (key === "CODEX")
+                        out.codex = val;
+                }
+                resolve(out);
+            });
+        });
+    });
+}
+/** 用系统 `which` / `where` 查询关键命令。失败/没找到统一返回 null。 */
+function probeCommands() {
+    const out = {};
+    for (const name of PROBE_COMMANDS) {
+        out[name] = whichSync(name);
+    }
+    return out;
+}
+function whichSync(cmd) {
+    // Windows 用 `where`，POSIX 用 `which`；都走 process.env.PATH，因此一定要在
+    // repairRuntimePath() 追加完 PATH 之后再调。
+    const tool = process.platform === "win32" ? "where" : "which";
+    try {
+        const res = spawnSync(tool, [cmd], { encoding: "utf8" });
+        if (res.status !== 0)
+            return null;
+        const first = (res.stdout || "").split(/\r?\n/).find((line) => line.trim().length > 0);
+        return first ? first.trim() : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 把修复结果格式化为一行可读摘要（startServer 启动日志用）。
+ *
+ * 例：
+ *   `[wand] PATH augmented (+3 dirs); claude=/usr/local/bin/claude, codex=<missing>`
+ *   `[wand] PATH already complete; claude=/Users/foo/.bun/bin/claude`
+ */
+export function formatPathRepairSummary(result) {
+    const parts = [];
+    if (result.added.length > 0) {
+        parts.push(`PATH augmented (+${result.added.length} dirs: ${result.added.join(", ")})`);
+    }
+    else {
+        parts.push("PATH already complete");
+    }
+    const probes = [];
+    for (const [name, resolved] of Object.entries(result.resolved)) {
+        probes.push(`${name}=${resolved ?? "<missing>"}`);
+    }
+    if (probes.length > 0)
+        parts.push(probes.join(", "));
+    if (result.deepProbe === "failed" && result.warnings.length > 0) {
+        parts.push(`deep-probe: ${result.warnings[0]}`);
+    }
+    else if (result.deepProbe === "success") {
+        parts.push("deep-probe: ok");
+    }
+    return parts.join("; ");
+}

package/dist/server.d.ts

@@ -1,6 +1,7 @@
 import { ProcessManager } from "./process-manager.js";
 import { StructuredSessionManager } from "./structured-session-manager.js";
 import { WandStorage } from "./storage.js";
+import { type PathRepairResult } from "./path-repair.js";
 import { WandConfig } from "./types.js";
 /** Persist a cwd to recent paths. Used by both REST and session creation hooks. */
 export declare function recordRecentPath(storage: WandStorage, cwd: string | undefined | null): void;
@@ -18,6 +19,7 @@ export interface ServerHandle {
     httpsEnabled: boolean;
     version: string;
     orphanRecoveredCount: number;
+    pathRepair: PathRepairResult;
     close(): Promise<void>;
 }
 export declare function startServer(config: WandConfig, configPath: string): Promise<ServerHandle>;

package/dist/server.js

@@ -25,6 +25,7 @@ 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";
+import { deepRepairRuntimePath, formatPathRepairSummary, repairRuntimePath } from "./path-repair.js";
 import { isLogBusActive, wandTuiLog } from "./tui/log-bus.js";
 import { renderApp } from "./web-ui/index.js";
 import { WsBroadcastManager } from "./ws-broadcast.js";
@@ -734,6 +735,27 @@ function mimeForExt(ext) {
     return MIME_BY_EXT[ext.toLowerCase()] || "application/octet-stream";
 }
 export async function startServer(config, configPath) {
+    // 关键：在创建 ProcessManager / 任何 spawn 之前先修 PATH。
+    // 服务被注册为 systemd / launchd 时，unit 文件里的 PATH 是安装那一刻烧死的，
+    // 之后用户切 node 版本 / 重装 wand / 把 claude 装到新位置都不会更新 unit，
+    // 服务进程的 process.env.PATH 就长期 stale。这里追加常见工具链 bin 目录，
+    // 让 spawn 出的 PTY 子进程能找到 claude / codex。详见 src/path-repair.ts。
+    const pathRepair = repairRuntimePath();
+    // 同步追加完后还有一层兜底：起 login shell 拉用户实际 $PATH，把 nvm / fnm /
+    // volta 这类动态注入的目录也合并进来。失败会静默走 sync 结果，不阻塞启动。
+    try {
+        await deepRepairRuntimePath(pathRepair, { shell: config.shell });
+    }
+    catch {
+        // deepRepairRuntimePath 内部已经 catch 了所有异常并写到 result.warnings；
+        // 这里只是兜底，避免任何意外 throw 阻断启动。
+    }
+    if (pathRepair.added.length > 0
+        || Object.values(pathRepair.resolved).some((v) => v === null)
+        || pathRepair.warnings.length > 0) {
+        // 有改动 / 有命令没解析到 / 有告警时才打 log，避免正常启动刷屏。
+        process.stdout.write(`[wand] ${formatPathRepairSummary(pathRepair)}\n`);
+    }
     const app = express();
     const storage = new WandStorage(resolveDatabasePath(configPath));
     setAuthStorage(storage);
@@ -2031,6 +2053,7 @@ export async function startServer(config, configPath) {
         httpsEnabled: useHttps,
         version: PKG_VERSION,
         orphanRecoveredCount: processes.getOrphanRecoveredCount(),
+        pathRepair,
         close,
     };
 }

package/dist/structured-session-manager.d.ts

@@ -152,6 +152,17 @@ export declare class StructuredSessionManager {
     private extractCodexText;
     private extractCodexItemBlock;
     private upsertCodexBlock;
+    /**
+     * 组装结构化 runner 退出失败时的可读错误字符串。
+     *
+     * 痛点：之前 claude -p / codex exec 异常退出只把"stderr.trim() || `... exited
+     * with code N`"塞给 UI。如果 stderr 是空的，用户在前端只能看到 "EXIT 1" 这种
+     * 没有任何上下文的串，根本不知道是网络错误、参数错误还是 binary 找不着。
+     *
+     * 这里固定把"provider + 退出码 / 信号"放在最前面，再把 stderr / NDJSON 错误
+     * 事件 / 最后一段 stdout 之类的上下文跟在后面，方便定位。
+     */
+    private formatStructuredExitError;
     private finishStructuredFailure;
     private extractModelName;
     private extractUsage;

package/dist/structured-session-manager.js

@@ -1297,9 +1297,17 @@ export class StructuredSessionManager {
                     closedAt: new Date().toISOString(),
                     spawnError: error.message,
                 });
-                reject(error);
+                // spawn 直接失败（最常见是 ENOENT —— PATH 里找不到 codex 可执行文件）。
+                // 之前只 reject(error)，外层 catch 会把 error.message 直接当 lastError，
+                // 用户看到的就是裸的 "spawn codex ENOENT"，没法快速反应。这里加一层
+                // 包装把上下文（runner 名 + 常见排查建议）拼好。
+                const nodeErr = error;
+                const hint = nodeErr.code === "ENOENT"
+                    ? "（PATH 中找不到 codex 可执行文件；请确认 codex 已安装，或重跑 `wand service:install` 刷新服务的 PATH）"
+                    : "";
+                reject(new Error(`codex exec 启动失败：${error.message}${hint}`));
             });
-            child.on("close", (code) => {
+            child.on("close", (code, signal) => {
                 this.pendingChildren.delete(sessionId);
                 this.lastStreamSaveAt.delete(sessionId);
                 if (lineBuf.trim()) {
@@ -1329,11 +1337,12 @@ export class StructuredSessionManager {
                 // codex 把模型/网络/沙箱等错误写到 stdout 的 NDJSON 流（type: error / turn.failed），
                 // 而不是 stderr。我们以 turn.failed 的 message 为准，其次是最后一个 error 事件。
                 const codexFailed = codexTurnFailed !== null;
-                if ((codexFailed || (code !== 0 && code !== null)) && !interruptedByUser) {
-                    const errorText = (codexTurnFailed && codexTurnFailed.trim())
-                        || (codexErrors.length > 0 ? codexErrors[codexErrors.length - 1] : "")
-                        || stderr.trim()
-                        || `codex exec exited with code ${code}`;
+                if ((codexFailed || (code !== 0 && code !== null) || signal) && !interruptedByUser) {
+                    const errorText = this.formatStructuredExitError("codex exec", code, signal, {
+                        stderr,
+                        primary: codexTurnFailed,
+                        extras: codexErrors,
+                    });
                     const exitForSnapshot = typeof code === "number" ? code : 1;
                     const failed = this.finishStructuredFailure(current, exitForSnapshot, errorText, turnState);
                     this.sessions.set(sessionId, failed);
@@ -1754,9 +1763,16 @@ export class StructuredSessionManager {
                 }
             };
             let stderr = "";
+            // 兜底：当 stderr 是空、JSON 也没解析到任何错误事件时，把最后一段非空
+            // stdout 文本作为上下文塞给错误信息。claude -p 偶尔会把 fatal error 以
+            // 纯文本（非 JSON）打到 stdout 然后非零退出，之前的实现会丢掉这部分。
+            let lastRawStdoutChunk = "";
             child.stdout?.on("data", (chunk) => {
                 const text = chunk.toString();
                 this.logger?.appendStructuredStdout(sessionId, text);
+                const trimmed = text.trim();
+                if (trimmed)
+                    lastRawStdoutChunk = trimmed.slice(-1024);
                 lineBuf += text;
                 const lines = lineBuf.split("\n");
                 // Keep the last (possibly incomplete) segment in the buffer.
@@ -1782,9 +1798,14 @@ export class StructuredSessionManager {
                     closedAt: new Date().toISOString(),
                     spawnError: error.message,
                 });
-                reject(error);
+                // 同 codex 那边：spawn ENOENT 最常见，提示用户去 service:install 刷 PATH。
+                const nodeErr = error;
+                const hint = nodeErr.code === "ENOENT"
+                    ? "（PATH 中找不到 claude 可执行文件；请确认 claude 已安装，或重跑 `wand service:install` 刷新服务的 PATH）"
+                    : "";
+                reject(new Error(`claude -p 启动失败：${error.message}${hint}`));
             });
-            child.on("close", (code) => {
+            child.on("close", (code, signal) => {
                 this.pendingChildren.delete(sessionId);
                 this.lastStreamSaveAt.delete(sessionId);
                 this.logger?.appendStructuredSpawn(sessionId, {
@@ -1812,8 +1833,14 @@ export class StructuredSessionManager {
                 // 可能以非零 exit code 退出（内部 handler 调了 exit(1)）。这种情况属于正常
                 // 中断流程，不应走失败路径——后续 interruptedWith 逻辑会发送新消息。
                 const interruptedByUser = this.interruptedWith.has(sessionId);
-                if (code !== 0 && code !== null && !interruptedByUser) {
-                    const errorText = stderr.trim() || `claude -p exited with code ${code}`;
+                const failedExit = (code !== null && code !== 0) || signal !== null;
+                if (failedExit && !interruptedByUser) {
+                    const errorText = this.formatStructuredExitError("claude -p", code, signal, {
+                        stderr,
+                        // claude -p 没有 codex 那种独立的 turn.failed 事件，所以 primary 留空；
+                        // 退路是 stderr / stdoutTail。
+                        stdoutTail: lastRawStdoutChunk,
+                    });
                     const failureTurn = {
                         role: "assistant",
                         content: [{ type: "text", text: `结构化会话执行失败：${errorText}` }],
@@ -1826,10 +1853,12 @@ export class StructuredSessionManager {
                     else {
                         msgs.push(failureTurn);
                     }
+                    // 仅 signal 终止时 code 为 null；用 1 占位，让 UI 的"exitCode !== 0"判定也能命中。
+                    const exitForSnapshot = typeof code === "number" ? code : 1;
                     const failed = {
                         ...current,
                         status: "failed",
-                        exitCode: code,
+                        exitCode: exitForSnapshot,
                         endedAt: new Date().toISOString(),
                         output: errorText,
                         claudeSessionId: turnState.sessionId ?? current.claudeSessionId,
@@ -2587,6 +2616,36 @@ export class StructuredSessionManager {
         }
         blocks.push(block);
     }
+    /**
+     * 组装结构化 runner 退出失败时的可读错误字符串。
+     *
+     * 痛点：之前 claude -p / codex exec 异常退出只把"stderr.trim() || `... exited
+     * with code N`"塞给 UI。如果 stderr 是空的，用户在前端只能看到 "EXIT 1" 这种
+     * 没有任何上下文的串，根本不知道是网络错误、参数错误还是 binary 找不着。
+     *
+     * 这里固定把"provider + 退出码 / 信号"放在最前面，再把 stderr / NDJSON 错误
+     * 事件 / 最后一段 stdout 之类的上下文跟在后面，方便定位。
+     */
+    formatStructuredExitError(provider, code, signal, options = {}) {
+        const head = signal
+            ? `${provider} terminated by signal ${signal}${code !== null ? ` (code ${code})` : ""}`
+            : code !== null
+                ? `${provider} exited with code ${code}`
+                : `${provider} exited (unknown status)`;
+        const primary = options.primary?.trim();
+        const stderrTrim = options.stderr?.trim() ?? "";
+        const lastExtra = options.extras && options.extras.length > 0
+            ? options.extras[options.extras.length - 1].trim()
+            : "";
+        const stdoutTail = options.stdoutTail?.trim() ?? "";
+        // 选第一个非空的"详情"作为正文展示，剩下的不再追加避免太长。
+        const detail = primary || lastExtra || stderrTrim || stdoutTail;
+        if (!detail)
+            return head;
+        // 控制长度，避免大段 stderr 撑爆 UI；保留尾部信息（最近的更相关）。
+        const trimmed = detail.length > 2048 ? `...${detail.slice(-2048)}` : detail;
+        return `${head}\n${trimmed}`;
+    }
     finishStructuredFailure(current, code, errorText, turnState) {
         const failureTurn = {
             role: "assistant",

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

@@ -135,6 +135,7 @@
         // askuserquestion 菜单多份叠加的最强候选根因。
         syncOutputBuffer: null,
         syncOutputDeadline: 0,
+        syncFramingResidue: false,
         lastChunkAt: 0,
         terminalHealthTimer: null,
         lastTerminalResyncAt: 0,
@@ -147,12 +148,14 @@
         // scroll 动画），多次调用用 Math.max 合并、不会被短窗口缩短。
         terminalProgrammaticScrollUntil: 0,
         terminalScrollIdleTimer: null,
-        terminalScrollIdleMs: 1800,
         terminalScrollThreshold: 12,
         showTerminalJumpToBottom: false,
         terminalViewportEl: null,
         terminalViewportScrollHandler: null,
         terminalViewportTouchHandler: null,
+        terminalViewportTouchStartHandler: null,
+        terminalTouchStartY: 0,
+        terminalComposing: false,
         resizeObserver: null,
         resizeHandler: null,
         resizeTimer: null,
@@ -1916,9 +1919,14 @@
                         if (selectedSession.provider === "claude" && selectedSession.claudeSessionId) {
                           bits += '<span id="claude-session-id-badge" class="claude-session-id-badge" data-claude-id="' + escapeHtml(selectedSession.claudeSessionId) + '" title="点击复制 Claude 会话 ID">' + iconSvg("cloud", { size: 11, strokeWidth: 1.7, cls: "claude-session-id-icon" }) + '<span class="claude-session-id-text">' + escapeHtml(selectedSession.claudeSessionId.slice(0, 8)) + '</span></span>';
                         }
-                        if (!isStructuredSession(selectedSession) && selectedSession.exitCode !== undefined && selectedSession.exitCode !== null) {
-                          if (bits) bits += '<span class="session-info-separator">|</span>';
-                          bits += '<span id="session-exit-display" class="session-exit-display">退出码=' + selectedSession.exitCode + '</span>';
+                        // 非结构化会话：进程退出后展示退出码（哪怕 0，告诉用户已正常结束）。
+                        // 结构化会话：只在退出码非 0（即真有失败）时展示，避免成功的多轮对话也挂个 "退出码=0" 误导。
+                        if (selectedSession.exitCode !== undefined && selectedSession.exitCode !== null) {
+                          var showExit = !isStructuredSession(selectedSession) || selectedSession.exitCode !== 0;
+                          if (showExit) {
+                            if (bits) bits += '<span class="session-info-separator">|</span>';
+                            bits += '<span id="session-exit-display" class="session-exit-display">退出码=' + selectedSession.exitCode + '</span>';
+                          }
                         }
                         return bits ? '<div class="input-session-info-bar">' + bits + '</div>' : '';
                       })()
@@ -6174,12 +6182,25 @@
           inputBox.addEventListener("keydown", handleInputBoxKeydown);
           inputBox.addEventListener("paste", handleInputPaste);
           inputBox.addEventListener("input", function() {
+            // INPUT-3: IME 组字期间不把半成品发给 PTY，等 compositionend 再统一发。
+            if (state.terminalComposing) return;
             if (handleInteractiveTextInput(inputBox)) {
               return;
             }
             refreshInputBoxState(inputBox);
             setDraftValue(inputBox.value, true);
           });
+          // INPUT-3: 交互模式 IME 组字承接。compositionstart 起置位标志让 input
+          // handler 静默；compositionend 取最终组字结果发 PTY 并清空。非交互模式不
+          // 介入，正常的中文聊天输入不受影响。
+          inputBox.addEventListener("compositionstart", function() {
+            if (state.terminalInteractive) state.terminalComposing = true;
+          });
+          inputBox.addEventListener("compositionend", function() {
+            if (!state.terminalComposing) return;
+            state.terminalComposing = false;
+            if (state.terminalInteractive) handleInteractiveTextInput(inputBox);
+          });
           inputBox.addEventListener("focus", function() {
             // Close drawer when user focuses input to avoid backdrop blocking clicks
             closeSessionsDrawer();
@@ -7127,7 +7148,10 @@
         var shouldShow = !!state.selectedId
           && state.currentView === "terminal"
           && !state.terminalAutoFollow
-          && !isTerminalNearBottom();
+          // SCROLL-2: 隐藏判据用严格 2px(isTerminalAtBottom) 而非 12px。否则距底
+          // 3–12px 区间 autoFollow 恒 false(scroll handler 只在 ≤2px 才恢复)却又
+          // 因 isTerminalNearBottom()=true 隐藏按钮 → 既不跟随又无回底入口的死区。
+          && !isTerminalAtBottom();
         state.showTerminalJumpToBottom = shouldShow;
         if (button) {
           button.classList.toggle("visible", shouldShow);
@@ -7175,22 +7199,19 @@
         }
       }
 
-      function scheduleTerminalResumeFollow() {
-        clearTerminalScrollIdleTimer();
-        updateTerminalJumpToBottomButton();
-        state.terminalScrollIdleTimer = setTimeout(function() {
-          state.terminalScrollIdleTimer = null;
-          state.terminalAutoFollow = true;
-          if (!isTerminalNearBottom()) {
-            scrollTerminalToBottom(true);
-          }
-          updateTerminalJumpToBottomButton();
-        }, state.terminalScrollIdleMs);
-      }
-
       function setTerminalManualScrollActive() {
         state.terminalAutoFollow = false;
         clearTerminalScrollIdleTimer();
+        // SCROLL-1: 用户一旦表达"看历史"意图，立刻作废任何在途的程序性拽底。
+        // 否则一个已排队、尚未 fire 的 wterm rAF _doRender 仍读着旧的
+        // _shouldScrollToBottom=true 把视口拽回底，而那次拽底触发的 scroll 事件正好
+        // 落在 120ms 程序窗口内被 scroll handler early-return 吞掉——上滚意图被悄悄
+        // 撤回。这里同步按掉 wterm 的跟随意图、并清零程序窗口，让紧随的真实 scroll
+        // 事件能被 handler 正常复判。
+        state.terminalProgrammaticScrollUntil = 0;
+        if (state.terminal && "_shouldScrollToBottom" in state.terminal) {
+          state.terminal._shouldScrollToBottom = false;
+        }
         updateTerminalJumpToBottomButton();
       }
 
@@ -7441,9 +7462,17 @@
 
       function createWideParserState() { return { mode: "normal" }; }
 
+      // PERF-1: 整块纯 ASCII 且无 ESC ⇒ 无宽字符、无 ANSI 序列，可跳过逐字符扫描。
+      function isAsciiNonEscape(s) {
+        return !/[^\x00-\x7f]/.test(s) && s.indexOf("\x1b") === -1;
+      }
+
       function widePadAnsi(data, st) {
         if (!data) return "";
         var s = String(data);
+        // PERF-1: 不在 ANSI 解析中间态、且整块纯 ASCII 无转义时原样返回，省下逐字符
+        // 拼接与 U+2060 注入。Claude 流式输出与全量重放大量命中此快路径。
+        if (st.mode === "normal" && isAsciiNonEscape(s)) return s;
         var out = "";
         for (var i = 0; i < s.length; i++) {
           var code = s.charCodeAt(i);
@@ -7530,6 +7559,9 @@
                 // 护栏：超长/超时强制 flush，避免永久卡死
                 out += state.syncOutputBuffer;
                 state.syncOutputBuffer = null;
+                // FLICKER: 这是 NEW-A 唯一"失手"路径——半个 ?2026 帧被透传给 wterm，
+                // 可能渲染错位。打标记让 R6 chunk 兜底 resync 一次（且仅此时触发）。
+                state.syncFramingResidue = true;
               }
               return out;
             }
@@ -7629,10 +7661,17 @@
           var node = anchor && anchor.nodeType === 3 ? anchor.parentNode : anchor;
           var output = document.getElementById("output");
           if (!output || !node || !output.contains(node)) return;
+          // COPY-1: 终端每行被 wterm 补齐到整列宽（空 cell 输出真实空格 + white-space:pre），
+          // 选中复制会带一长串行尾空格；同时宽字符后插了零宽填充符 U+2060。两者一起清：
+          // 逐行剥 filler + trimEnd。只要选区落在 #output 内就处理（不再要求"含 filler
+          // 才改写"，否则纯 ASCII 行的尾随空格漏网）。
           var text = sel.toString();
-          if (text.indexOf(WAND_WIDE_FILLER) === -1) return;
+          var cleaned = text.split("\n").map(function(line) {
+            return line.split(WAND_WIDE_FILLER).join("").replace(/[ \t]+$/, "");
+          }).join("\n");
+          if (cleaned === text) return; // 无可清理内容，交回浏览器默认复制
           if (e.clipboardData) {
-            e.clipboardData.setData("text/plain", text.split(WAND_WIDE_FILLER).join(""));
+            e.clipboardData.setData("text/plain", cleaned);
             e.preventDefault();
           }
         });
@@ -7755,6 +7794,11 @@
       var RESYNC_BUDGET_WINDOW_MS = 5000;
       var RESYNC_BUDGET_MAX = 12;
       var RESYNC_WARN_COOLDOWN_MS = 30000;
+      // RENDER-1: softResync 自身的重放（wandTerminalWrite 末尾会调 maybeScheduleResyncForChunk）
+      // 不应再触发新一轮 resync，否则从 health-check/onResize/刷新/重连等路径进来时，
+      // 整段含 CSI 的 replaySource 会让单次 resync 被放大成 2~3 次全量重放。重放期间置位
+      // 此标志，maybeScheduleResyncForChunk 开头据此短路。
+      var _resyncInProgress = false;
       function softResyncTerminal(options) {
         if (!state.terminal || !state.terminalOutput) return false;
         var opts = options || {};
@@ -7767,8 +7811,13 @@
         var replaySource = marker > 0 ? state.terminalOutput.slice(marker) : state.terminalOutput;
         var bufLen = replaySource.length;
         var startedAt = (typeof performance !== "undefined" && performance.now) ? performance.now() : Date.now();
-        resetTerminal();
-        wandTerminalWrite(state.terminal, replaySource);
+        _resyncInProgress = true;
+        try {
+          resetTerminal();
+          wandTerminalWrite(state.terminal, replaySource);
+        } finally {
+          _resyncInProgress = false;
+        }
         state.lastTerminalResyncAt = Date.now();
         maybeScrollTerminalToBottom("output");
         if (!opts.skipFit) ensureTerminalFit("refresh");
@@ -7819,6 +7868,14 @@
       var _resyncChunkLastAt = 0;
       var _resyncChunkTailTimer = null;
       function maybeScheduleResyncForChunk(chunk) {
+        if (_resyncInProgress) return; // RENDER-1: 屏蔽 softResync 自身重放触发的递归
+        // FLICKER: R6 chunk 热路径 resync 仅在 NEW-A 失手时兜底——即 ?2026 残帧被
+        // processSyncOutputFraming 超时/超长强制 flush 透传给 wterm 之后。正常完整包帧
+        // 的重绘（菜单/todo/thinking spinner）已被 NEW-A 原子化、wterm 渲染正确，无需
+        // resync。旧实现对每个含 CSI 的 chunk 都触发，使 thinking 期间每 ~1.5s 一次
+        // resetTerminal→空白帧→重画，终端区持续闪烁。残帧标记在此消费一次（仅此触发）。
+        if (!state.syncFramingResidue) return;
+        state.syncFramingResidue = false;
         if (!chunk || typeof chunk !== "string") return;
         if (chunk.indexOf("\x1b[") === -1) return;
         if (!IN_PLACE_REDRAW_RE.test(chunk)) return;
@@ -8048,15 +8105,32 @@
               }
               setTerminalManualScrollActive();
             };
-            state.terminalViewportTouchHandler = function() {
-              setTerminalManualScrollActive();
+            // SCROLL-3: 触摸只在"看历史"方向（手指下拉、clientY 增大）才下台跟随；
+            // 手指上滑（朝新内容/底部）不关跟随，交给 scroll handler 在到底时恢复。
+            // 终端非 column-reverse：手指下拉=内容下移=看上方历史=上滚意图，与 wheel
+            // 的 deltaY<0 对称。原实现任何 touchmove 都关跟随，移动端在底部轻微回弹
+            // 就丢跟随。
+            state.terminalViewportTouchStartHandler = function(e) {
+              if (e.touches && e.touches.length === 1) {
+                state.terminalTouchStartY = e.touches[0].clientY;
+              }
+            };
+            state.terminalViewportTouchHandler = function(e) {
+              if (!e.touches || e.touches.length !== 1) return;
+              if (typeof state.terminalTouchStartY !== "number") return;
+              if (e.touches[0].clientY - state.terminalTouchStartY > 4) {
+                setTerminalManualScrollActive();
+              }
             };
             viewport.addEventListener("scroll", state.terminalViewportScrollHandler, { passive: true });
+            viewport.addEventListener("touchstart", state.terminalViewportTouchStartHandler, { passive: true });
             viewport.addEventListener("touchmove", state.terminalViewportTouchHandler, { passive: true });
           }
 
+          // SCROLL-5: 只在上滚（朝历史，deltaY<0）时下台跟随；向下滚（想回去）交给
+          // scroll handler 在真正到底时恢复，避免"远离底部时向下滚也被一直按住不跟随"。
           state.terminalWheelHandler = function(e) {
-            if (!isTerminalNearBottom() || e.deltaY < 0) {
+            if (e.deltaY < 0) {
               setTerminalManualScrollActive();
             }
             e.stopPropagation();
@@ -8074,7 +8148,13 @@
             wandTerminalWrite(term, "点击上方「新对话」开始你的第一次对话。\r\n");
           }
 
-          state.terminalClickHandler = focusInputBox;
+          // COPY-4: 有终端选区时不抢焦点到输入框，否则打断双击选词/三击选行后的复制
+          // （焦点与后续 Ctrl+C 目标被夺走）。wterm 自带 _onClickFocus 有同款护栏。
+          // 透传 event 给 focusInputBox(skipMobile)，保留"移动端点终端不自动弹键盘"。
+          state.terminalClickHandler = function(e) {
+            if (hasActiveTerminalSelection()) return;
+            focusInputBox(e);
+          };
           container.addEventListener("click", state.terminalClickHandler);
           updateTerminalJumpToBottomButton();
           initTerminalResizeHandle();
@@ -11426,29 +11506,57 @@
 
         if (event.key === "Escape") {
           event.preventDefault();
-          queueDirectInput(getControlInput("escape"), "escape");
+          var escSess = getSelectedSession();
+          if (isStructuredSession(escSess)) {
+            // INPUT-2: 结构化会话没有 PTY，Esc 不能把 \x1b 当消息发给 Claude。
+            // 用户语义 Esc=中断：正在生成时等同点"停止"按钮，否则无操作。
+            if (escSess && escSess.structuredState && escSess.structuredState.inFlight) {
+              stopSession();
+            }
+          } else {
+            queueDirectInput(getControlInput("escape"), "escape");
+          }
           return;
         }
 
         if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === "c") {
-          // Allow copy when text is selected; otherwise send SIGINT to terminal
-          var inputBox = document.getElementById("input-box");
-          var hasSelection = inputBox && (inputBox.selectionStart !== inputBox.selectionEnd);
-          if (hasSelection) {
+          // COPY-2: 有选区（输入框内或终端输出区）时放行浏览器原生复制，而不是发
+          // SIGINT。原实现只看输入框选区，漏了文档级终端选区。
+          var inputBoxC = document.getElementById("input-box");
+          var hasSelectionC = (inputBoxC && inputBoxC.selectionStart !== inputBoxC.selectionEnd)
+            || hasActiveTerminalSelection();
+          if (hasSelectionC) {
             return; // Let browser handle copy
           }
+          var ccSess = getSelectedSession();
+          if (isStructuredSession(ccSess)) {
+            // INPUT-2: 结构化会话不把 SIGINT(\x03) 当消息发给 Claude。Ctrl+C 视为
+            // 中断当前生成（等同停止按钮），非生成态则无操作。
+            event.preventDefault();
+            if (ccSess && ccSess.structuredState && ccSess.structuredState.inFlight) {
+              stopSession();
+            }
+            return;
+          }
           event.preventDefault();
           queueDirectInput(getControlInput("ctrl_c"), "ctrl_c");
           return;
         }
 
         if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === "d") {
-          // Allow copy when text is selected; otherwise send EOF to terminal
+          // COPY-2: 有选区（输入框内或终端输出区）时放行浏览器复制。
           var inputBox2 = document.getElementById("input-box");
-          var hasSelection2 = inputBox2 && (inputBox2.selectionStart !== inputBox2.selectionEnd);
+          var hasSelection2 = (inputBox2 && (inputBox2.selectionStart !== inputBox2.selectionEnd))
+            || hasActiveTerminalSelection();
           if (hasSelection2) {
             return; // Let browser handle copy
           }
+          var cdSess = getSelectedSession();
+          if (isStructuredSession(cdSess)) {
+            // INPUT-2: 结构化会话吞掉 Ctrl+D（EOF 对 Claude 对话无意义，别当消息发）
+            event.preventDefault();
+            return;
+          }
           event.preventDefault();
           queueDirectInput(getControlInput("ctrl_d"), "ctrl_d");
           return;
@@ -11456,6 +11564,11 @@
 
         if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === "l") {
           event.preventDefault();
+          var clSess = getSelectedSession();
+          if (isStructuredSession(clSess)) {
+            // INPUT-2: 结构化会话吞掉 Ctrl+L（清屏对 Claude 对话无意义）
+            return;
+          }
           queueDirectInput(getControlInput("ctrl_l"), "ctrl_l");
           return;
         }
@@ -13542,10 +13655,12 @@
           composer.placeholder = getComposerPlaceholder(selectedSession, state.terminalInteractive);
           composer.disabled = !structured && !!selectedSession && !isRunning && !canResumeOnSend;
           composer.setAttribute("aria-disabled", composer.disabled ? "true" : "false");
-          // 终端交互模式下按键由 document capture phase 透传到 PTY；用
-          // readOnly 而非 disabled 防止 IME 组合输入等边界场景下字符同时
-          // 落到 textarea，又保留 focus 能力。
-          composer.readOnly = !!state.terminalInteractive;
+          // INPUT-3: 交互模式不再设 readOnly。readOnly 的 textarea 上 IME 根本不会
+          // 激活（compositionstart 不触发），导致中文/日文等组字输入彻底打不出。普通
+          // 字符 keydown 已由 capture 阶段的 captureTerminalInput preventDefault 拦截、
+          // 不会落进 textarea；唯独 IME 组字期间 capture 放行(isComposing)，字符临时
+          // 落入 textarea，由 compositionend 取最终文本发 PTY 后清空。
+          composer.readOnly = false;
           composer.classList.toggle("is-terminal-passthrough", !!state.terminalInteractive);
         }
         var sendBtn = document.getElementById("send-input-button");
@@ -13561,15 +13676,40 @@
         if (container) container.classList.toggle("interactive", !structured && state.terminalInteractive);
       }
 
+      // COPY-2/COPY-4: 是否存在落在终端输出区(#output)内的活动文本选区。用于：
+      // 有选区时 Ctrl+C 放行浏览器原生复制而非发 SIGINT；click 不抢焦点以免打断
+      // 双击选词/三击选行后的复制。
+      function hasActiveTerminalSelection() {
+        var sel = window.getSelection && window.getSelection();
+        if (!sel || sel.isCollapsed) return false;
+        var output = document.getElementById("output");
+        if (!output) return false;
+        var node = sel.anchorNode;
+        if (node && node.nodeType === 3) node = node.parentNode;
+        return !!(node && output.contains(node));
+      }
+
       function captureTerminalInput(event) {
         if (!shouldCaptureTerminalEvent(event)) return;
+        // INPUT-1: 放行 Cmd/Meta 组合键给浏览器（复制/粘贴/刷新/切标签）。PTY 用
+        // Ctrl 不用 Cmd，拦下来既破坏 macOS 原生快捷键，又会把裸字母(Cmd+X→'x')
+        // 误塞进 PTY。
+        if (event.metaKey) return;
         var key = keyFromKeyboardEvent(event);
         if (!key) return;
-        event.preventDefault();
         var mods = getModifierStateFromEvent(event, key);
         if (isModifierKey(key)) return;
+        // COPY-2: 有选区时 Ctrl+C 放行浏览器原生复制，而不是发 SIGINT(0x03) 把进程
+        // 杀了还复制不到。无选区的 Ctrl+C 仍透传给 PTY。
+        if (mods.ctrl && key.length === 1 && key.toLowerCase() === "c" && hasActiveTerminalSelection()) {
+          return;
+        }
         var sequence = buildPtySequence(key, mods);
-        if (sequence) sendTerminalSequence(sequence, key);
+        // INPUT-4: 只有真正要发给 PTY 的键才 preventDefault；空序列(F5/F12/死键等)
+        // 放行给浏览器，避免"既没发 PTY 又吞掉浏览器默认行为"。
+        if (!sequence) return;
+        event.preventDefault();
+        sendTerminalSequence(sequence, key);
       }
 
       function handleMiniKeyboardClick(event) {
@@ -15250,7 +15390,11 @@
           var now = Date.now();
           var chunkPause = state.lastChunkAt > 0 && (now - state.lastChunkAt > 300);
           var resyncDue = (now - state.lastTerminalResyncAt) > 30000;
-          if (resyncDue && (chunkPause || selectedSession.status !== "running") && state.terminalOutput) {
+          // RENDER-2: 仅在"自上次 resync 以来确有新输出"时才重放。静止/已结束会话
+          // buffer 不再变化，30s 周期 resync 是纯无用功，还会把 cursor-home 中间帧
+          // 重堆进 scrollback、扰动滚动位置。lastChunkAt>lastTerminalResyncAt 即脏。
+          var dirtySinceResync = state.lastChunkAt > state.lastTerminalResyncAt;
+          if (resyncDue && dirtySinceResync && (chunkPause || selectedSession.status !== "running") && state.terminalOutput) {
             softResyncTerminal();
           }
         }, 5000);
@@ -15306,6 +15450,9 @@
           if (state.terminalViewportTouchHandler) {
             state.terminalViewportEl.removeEventListener("touchmove", state.terminalViewportTouchHandler);
           }
+          if (state.terminalViewportTouchStartHandler) {
+            state.terminalViewportEl.removeEventListener("touchstart", state.terminalViewportTouchStartHandler);
+          }
         }
         if (output) {
           if (state.terminalWheelHandler) {
@@ -15318,13 +15465,24 @@
         state.terminalViewportEl = null;
         state.terminalViewportScrollHandler = null;
         state.terminalViewportTouchHandler = null;
+        state.terminalViewportTouchStartHandler = null;
         state.terminalWheelHandler = null;
         state.terminalClickHandler = null;
+        // LIFE-1: 清理 initTerminalScrollbar 注册的 hide-timer 与拖拽状态。否则
+        // hide-timer 闭包引用游离节点（置 El=null 拦不住它），且若拖拽中途 teardown，
+        // 残留 dragging=true 会让新会话 scrollbar 的 scheduleHideScrollbar 被永久抑制
+        // （开头 if(dragging)return）→ 滚动条出现后再也不自动消失。
+        if (state.terminalScrollbarHideTimer) {
+          clearTimeout(state.terminalScrollbarHideTimer);
+          state.terminalScrollbarHideTimer = null;
+        }
         if (state.terminalScrollbarEl && state.terminalScrollbarEl.parentNode) {
           state.terminalScrollbarEl.parentNode.removeChild(state.terminalScrollbarEl);
         }
         state.terminalScrollbarEl = null;
         state.terminalScrollbarThumbEl = null;
+        state.terminalScrollbarDragging = false;
+        state.terminalScrollbarRafPending = false;
         if (state.terminal) {
           state.terminal.destroy();
           state.terminal = null;
@@ -15349,6 +15507,7 @@
         // 会让新会话的首批 PTY 字节全部被吞进 buffer 等永远不会来的 end。
         state.syncOutputBuffer = null;
         state.syncOutputDeadline = 0;
+        state.syncFramingResidue = false;
         state.terminalSessionId = null;
         state.terminalOutput = "";
         state.terminalOutputMarker = 0; // R8: teardown 时重置 /clear marker
@@ -15371,6 +15530,11 @@
         _resyncStatsWindowStart = 0;
         _resyncStatsCount = 0;
         _resyncLastWarnAt = 0;
+        _resyncInProgress = false;
+        // SIZE-2: lastResize 是全局去重缓存，记"上次 POST 的尺寸"。切到另一个在不同
+        // 尺寸下创建的会话时，若新算出的 cols/rows 恰好等于上次值会被去重跳过，导致
+        // 后端该会话列宽停在旧值、整段折行。teardown 重置后新会话首次 resize 必发出。
+        state.lastResize = { cols: 0, rows: 0 };
       }
 
       function sendTerminalResize(cols, rows) {
@@ -15383,6 +15547,10 @@
         // wterm WASM grid 的 maxCols 硬编码 256。POST 给服务端的 cols 也同步
         // clamp，避免服务端 pty.resize 给 Claude 一个 wterm 实际渲不下的列宽。
         if (cols > 256) cols = 256;
+        // SIZE-1: rows 也 clamp 到后端上限 160（process-manager clampDimension 10..160）。
+        // 否则高分屏+小字号客户端算出 rows>160 时，后端压到 160，客户端网格底部多出的
+        // 行对应的 PTY 内容永不写入 → 底部大片空白 / 光标错位 / 全屏菜单画到不存在的行。
+        if (rows > 160) rows = 160;
         var nextSize = { cols: cols, rows: rows };
         if (state.lastResize.cols !== nextSize.cols || state.lastResize.rows !== nextSize.rows) {
           state.lastResize = nextSize;

package/package.json

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