pi-web-ui 0.95.0 → 0.96.0

package/dist/server/terminals.js

@@ -24,7 +24,7 @@ import "./patch-node-pty.js";
 import { spawn } from "node-pty";
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import { bilingual, pick } from "./i18n.js";
+import { pick } from "./i18n.js";
 /** Location of the command list for a project: <workspaceRoot>/.pi/commands.json */
 export function commandsFilePath(workspaceRoot) {
     return join(workspaceRoot, ".pi", "commands.json");
@@ -147,8 +147,10 @@ export function terminalIdleNotifyLines() {
 /** 哨兵行：命令执行完后由 shell 打印，携带真实退出码。正则只匹配数字，
  *  因此不会误匹配回显里的 printf 格式串 `[pi-exit:%s]`。 */
 const BASH_SENTINEL_RE = /\[pi-exit:(\d+)\]/g;
+/** bash 阻塞循环 collected 的累积上限：超限丢最旧一半（见 bash 工具执行循环）。 */
+const BASH_COLLECT_MAX = 2 * 1024 * 1024;
 /**
- * 把任意命令（含多行脚本）构造成「一行」交互 shell 命令：执行 + 捕获退出码。
+ * 把任意命令（含多行脚本）构造成一行交互 shell 命令：执行 + 捕获退出码。
  *
  * 单行很关键：整行先被 shell 完整解析再执行，命令中途读 stdin 也不会吃掉
  * 后续哨兵；也避开交互 shell 的 bracketed-paste 对多行输入的特殊处理。
@@ -156,15 +158,6 @@ const BASH_SENTINEL_RE = /\[pi-exit:(\d+)\]/g;
  */
 export function buildTerminalBashLine(command, tailFile) {
     const trimmed = command.replace(/\s+$/, "");
-    let body = trimmed;
-    if (trimmed.includes("\n")) {
-        body = `eval $'${trimmed
-            .replace(/\\/g, "\\\\")
-            .replace(/'/g, "\\'")
-            .replace(/\r/g, "\\r")
-            .replace(/\n/g, "\\n")
-            .replace(/\t/g, "\\t")}'`;
-    }
     // 退出码取【第一个】命令（真正干活的那个）而非管道末尾命令：`head`/`grep`/`tail`
     // 在管道末尾会把退出码吞成自己的（head 恒 0、grep 无命恒 1）。`${PIPESTATUS:-$?}`
     // 在 bash 里取 PIPESTATUS[0]（首命令），busybox ash/dash 无 PIPESTATUS 时退化为 `$?`。
@@ -172,12 +165,84 @@ export function buildTerminalBashLine(command, tailFile) {
     // 留下的 141 不是真失败，而是“按要求截断=成功”。只有恰好 141 才转 0，真失败照报。
     // tailFile：`cmd > log 2>&1 | tail -N`——拆掉 tail 后 stdout 进文件、终端为空；
     // 在哨兵前补一个 `tail -N log` 让模型看到日志尾部，退出码仍是底层命令的。
-    // eslint-disable-next-line no-useless-escape -- \$? must reach the shell literally
-    const rcGuard = `__pi_rc=\${PIPESTATUS:-\$?}; [ "$__pi_rc" -eq 141 ] && __pi_rc=0`;
     const tailPart = tailFile
         ? `; tail -n ${Math.max(1, Math.floor(tailFile.lines))} -- '${tailFile.file.replace(/'/g, `'\\''`)}'`
         : "";
-    return `${body}; ${rcGuard}${tailPart}; printf '\\n[pi-exit:%s]\\n' "$__pi_rc"`;
+    // eslint-disable-next-line no-useless-escape -- \$? must reach the shell literally
+    const sentinel = `__pi_rc=\${PIPESTATUS:-\$?}; [ "$__pi_rc" -eq 141 ] && __pi_rc=0${tailPart}; printf '\\n[pi-exit:%s]\\n' "$__pi_rc"`;
+    if (trimmed.includes("\n")) {
+        // 多行路径（行为保持）：$'...' 转义后是一行物理输入，引号/换行全部字面化，
+        // 以 `'` 收尾——`; ` 同行拼接哨兵不会被尾注释/尾管道/续行吞掉。
+        const body = `eval $'${trimmed
+            .replace(/\\/g, "\\\\")
+            .replace(/'/g, "\\'")
+            .replace(/\r/g, "\\r")
+            .replace(/\n/g, "\\n")
+            .replace(/\t/g, "\\t")}'`;
+        return `${body}; ${sentinel}`;
+    }
+    // 单行路径：哨兵独占一行追加。行内 `; ` 拼接会被常见形态吞掉——
+    // 尾注释（`cmd # note; printf…` 整段进注释）、尾管道（`cmd |; …` 语法错误）。
+    // 独占一行后这两类安全；尾随续行符/未闭合引号仍会把哨兵行并入命令或吞进
+    // 字符串——这类形态无法安全续行，直接拒注入（调用方按无退出码模式执行并注明）。
+    if (sentinelUnsafeReason(trimmed))
+        return trimmed;
+    return `${trimmed}\n${sentinel}`;
+}
+/**
+ * 判定命令能否安全追加「独占一行的退出码哨兵」；返回拒注入原因或 null（可注入）。
+ *
+ * - 尾随续行符 `\`：下一行被并入本命令，哨兵行成为命令的一部分。
+ * - 未闭合引号：哨兵行被吞进字符串字面量，永远不会作为代码执行。
+ * - 多行命令：经 `$'...'` 转义单行化后引号/换行全部字面化，总是安全 → null。
+ *
+ * 扫描按 POSIX 引号语义跟踪 `'`/`"`/`` ` `` 三种引号与转义；`$'...'`（ANSI-C
+ * 引号）内 `\'` 不闭合引号，也一并识别。
+ */
+export function sentinelUnsafeReason(command) {
+    const trimmed = command.replace(/\s+$/, "");
+    if (trimmed.includes("\n"))
+        return null;
+    let quote = null;
+    // 当前单引号是否 $' 开头（ANSI-C 引号，内含转义语义）
+    let ansiC = false;
+    let escaped = false;
+    for (let i = 0; i < trimmed.length; i++) {
+        const ch = trimmed[i];
+        if (quote) {
+            if (escaped) {
+                escaped = false;
+                continue;
+            }
+            // POSIX 单引号内 `\` 是普通字符；ANSI-C/双引号/反引号内 `\` 转义下一字符
+            if (ch === "\\" && (quote !== "'" || ansiC)) {
+                escaped = true;
+                continue;
+            }
+            if (ch === quote)
+                quote = null;
+            continue;
+        }
+        if (escaped) {
+            // 引号外的转义：被转义字符原样跳过（`\"` 不开引号等）
+            escaped = false;
+            continue;
+        }
+        if (ch === "\\") {
+            escaped = true;
+            continue;
+        }
+        if (ch === "'" || ch === '"' || ch === "`") {
+            quote = ch;
+            ansiC = ch === "'" && i > 0 && trimmed[i - 1] === "$";
+        }
+    }
+    if (quote !== null)
+        return "unclosed_quote";
+    // 扫描结束仍在转义态 = 最后一个字符是引号外的 `\`（尾随续行符）
+    if (escaped)
+        return "trailing_backslash";
+    return null;
 }
 /** 顶层（引号/反引号/转义外）按 `|` 拆分的管道元素。 */
 export function splitTopLevelPipes(cmd) {
@@ -230,6 +295,11 @@ function parseTailLines(rest) {
  * - `tail -f` / `tail --follow`（长驻观察）也不拆。
  */
 export function detectTrailingLimiter(command) {
+    // 含命令替换（$() / 反引号）的命令保守跳过拆管：splitTopLevelPipes 只跟踪引号
+    // 与顶层 `|`，不解析括号嵌套——`cmd $(x | y)` 里替换内的管道会被误判为顶层
+    // 管道段，拆掉后直接破坏命令语义。保守正确优先，宁可少优化。
+    if (/\$\(|`/.test(command))
+        return null;
     const parts = splitTopLevelPipes(command);
     if (parts.length < 2)
         return null;
@@ -1368,34 +1438,50 @@ export class TerminalManager {
      * Kill the native PTY (issue #215：Windows ConPTY 关机死锁；issue #269：MSYS2 控制台耗尽死锁）。
      *
      * Windows 下：
-     * 1. 若进程已经退出（entry.exited）：绝不可再调用 Node 的 process.kill(pid)，
-     *    直接调 pty.kill() 释放 HPCON 句柄（子进程已死、管道见 EOF，绝不会死锁）。
-     * 2. 若进程尚未退出（!entry.exited）：
-     *    先尝试优雅关闭（向 PTY 写入 \x03exit\r），让 bash 正常触发清理钩子；
-     *    若仍未退出才以 process.kill(pid)（TerminateProcess）强制兜底。
-     * 3. 关机（shutdown=true）：跳过 pty.kill()，由 OS 回收。
-     * 非 Windows 原样直调 pty.kill()。
+     * 1. 若进程已经退出（entry.exited）：直接调 pty.kill() 释放 HPCON 句柄
+     *    （子进程已死、管道见 EOF，绝不会死锁）；关机路径跳过，由 OS 回收。
+     * 2. 若进程尚未退出（!entry.exited）：先向 PTY 写入 \x03exit\r 优雅关闭（让
+     *    bash 正常触发清理钩子），300ms 后仍活着再调 pty.kill() 兜底——node-pty 在
+     *    Windows 上走 console-process-list 做**全树**清理。不再使用裸
+     *    process.kill(pid)（TerminateProcess）：它只杀 ConPTY 附着的单一进程，
+     *    且从拿到 pid 到调用之间隔着一个 PID 复用误杀窗口。
+     * 3. 关机（shutdown=true）：只做优雅写，跳过 pty.kill() 与 300ms 兜底，由 OS
+     *    回收（保持 50ms 内退出的关机预算）。
+     * 非 Windows 原样直调 pty.kill()（POSIX 下 shell 是直接子进程，pty.kill 足够，
+     * 保持既有行为不做额外延迟）。
      */
     killNative(entry, shutdown = false) {
         if (process.platform === "win32") {
-            if (!entry.exited) {
-                const pid = entry.pty.pid;
-                if (typeof pid === "number") {
-                    try {
-                        // 优雅关闭：先发 Ctrl+C，再发 exit\r
-                        entry.pty.write("\x03exit\r");
-                    }
-                    catch { }
+            if (entry.exited) {
+                if (!shutdown) {
                     try {
-                        process.kill(pid);
+                        entry.pty.kill();
                     }
                     catch {
                         // already dead
                     }
                 }
+                return;
+            }
+            // 优雅关闭：先发 Ctrl+C，再发 exit\r
+            try {
+                entry.pty.write("\x03exit\r");
             }
+            catch { }
             if (shutdown)
                 return;
+            const t = setTimeout(() => {
+                if (entry.exited)
+                    return;
+                try {
+                    entry.pty.kill();
+                }
+                catch {
+                    // already dead
+                }
+            }, 300);
+            t.unref?.();
+            return;
         }
         try {
             entry.pty.kill();
@@ -1530,29 +1616,29 @@ export function makeTerminalBashTool(terminals, opts) {
     return defineTool({
         name: "bash",
         label: "Run bash command",
-        description: bilingual("Run a shell command and return its full output plus exit code. Commands run in a visible terminal.\n" +
-            "persist=false (default, one-shot): a fresh terminal is created per call, run to completion, then the shell exits (the process ends) while its output stays in the terminal list for later review — like a normal bash call, but each command also leaves a viewable terminal record.\n" +
-            "persist=true: commands run in the PERSISTENT visible terminal 'ai-bash' — shell state such as cd, venv activation or ssh sessions is retained across calls; you can use terminal_wait to re-block on a backgrounded command, or terminal_read / terminal_input / terminal_key on 'ai-bash' to observe or interact anytime.\n" +
-            "Run the bare command — do NOT pipe through head/tail/more/less (output is returned complete anyway, and pipes hide live progress in the terminal). Use the head/tail parameters instead to trim the returned output. For interactive commands (REPLs, prompts, installers asking y/n) set persist=true and drive them with terminal_input / terminal_key.", "运行 shell 命令并返回完整输出与退出码。命令在可见终端中运行。\n" +
-            "persist=false（默认，一次性）：每次调用新建一个终端，运行至结束，然后 shell 退出（进程结束），输出保留在终端列表中供稍后查看——如同普通 bash 调用，但每条命令都会留下一条可查看的终端记录。\n" +
-            "persist=true：命令在常驻可见终端 'ai-bash' 中运行——cd、venv 激活、ssh 会话等 shell 状态跨调用保留；可用 terminal_wait 重新阻塞等待后台命令，或随时用 terminal_read / terminal_input / terminal_key 观察或交互。\n" +
-            "直接运行裸命令——不要经 head/tail/more/less 管道（反正会返回完整输出，管道还会挡住终端里的实时进度）。用 head/tail 参数截断返回的输出。交互式命令（REPL、提示符、问 y/n 的安装程序）请设 persist=true 并用 terminal_input / terminal_key 驱动。"),
-        promptSnippet: bilingual("run shell commands (persist=true keeps the terminal alive across calls)", "运行 shell 命令（persist=true 让终端跨调用保持存活）"),
+        description: "Run a shell command in a visible terminal; returns full output and exit code. " +
+            "persist=false (default): a fresh one-shot terminal per call; the shell exits after the command but its output stays viewable. " +
+            "persist=true: runs in the persistent 'ai-bash' terminal — shell state (cd/venv/ssh) is retained across calls; " +
+            "terminal_read/terminal_input/terminal_key observe or interact; terminal_wait blocks on backgrounded commands. " +
+            "Run the bare command — never pipe through head/tail/more/less (output is returned complete; pipes hide live progress); use the head/tail params instead. " +
+            "For interactive commands (REPLs, y/n prompts) set persist=true and drive them with terminal_input / terminal_key.",
+        promptSnippet: "run shell commands (persist=true keeps the terminal alive across calls)",
         parameters: Type.Object({
-            command: Type.String({ description: bilingual("The shell command to run", "要运行的 shell 命令") }),
-            timeout: Type.Optional(Type.Number({ description: bilingual("Optional timeout in seconds", "可选的超时秒数") })),
+            command: Type.String({ description: "The shell command to run" }),
+            timeout: Type.Optional(Type.Number({ description: "Optional timeout in seconds" })),
             persist: Type.Optional(Type.Boolean({
-                description: bilingual("Keep the terminal alive after the command (default: false → a one-shot terminal that exits when the command finishes while its output is retained for review). true runs in the persistent 'ai-bash' terminal so shell state (cd/venv/ssh) is retained across calls and the terminal stays interactive.", "运行后保持终端存活（默认 false → 命令结束时退出的、输出保留供查看的一次性终端）。true 则在常驻 'ai-bash' 终端中运行，shell 状态（cd/venv/ssh）跨调用保留、终端保持可交互。"),
+                description: "true → run in the persistent 'ai-bash' terminal: shell state (cd/venv/ssh) is retained across calls. " +
+                    "false (default) → one-shot terminal that exits when the command finishes; output stays viewable.",
             })),
             head: Type.Optional(Type.Integer({
                 minimum: 1,
                 maximum: 5000,
-                description: bilingual("Only return the FIRST N lines of output (like `| head -N`). Use this for verbose commands instead of piping through head.", "只返回输出的前 N 行（如 `| head -N`）。输出冗长的命令请用它，而不要经 head 管道。"),
+                description: "Only return the FIRST N lines of output (like `| head -N`); prefer this over piping through head.",
             })),
             tail: Type.Optional(Type.Integer({
                 minimum: 1,
                 maximum: 5000,
-                description: bilingual("Only return the LAST N lines of output (like `| tail -N`). Use this for verbose commands instead of piping through tail.", "只返回输出的后 N 行（如 `| tail -N`）。输出冗长的命令请用它，而不要经 tail 管道。"),
+                description: "Only return the LAST N lines of output (like `| tail -N`); prefer this over piping through tail.",
             })),
         }),
         execute: async (_id, p, signal) => {
@@ -1614,8 +1700,16 @@ export function makeTerminalBashTool(terminals, opts) {
                 let collected = "";
                 let cursor = start;
                 let lastDataAt = Date.now();
+                // 尾随续行符/未闭合引号的命令无法安全注入哨兵（哨兵行会被并入命令或
+                // 吞进字符串）：按无退出码模式执行，靠静默/超时/总时长解阻收尾并注明。
+                const sentinelUnsafe = sentinelUnsafeReason(runCommand);
+                const sentinelNote = sentinelUnsafe
+                    ? pick(lang, `\n[注：命令以${sentinelUnsafe === "trailing_backslash" ? "续行符 \\" : "未闭合引号"}结尾，无法注入退出码哨兵——已按无退出码模式执行，拿不到真实 exit code。建议拆分成更简单的单行命令重试。]`, `\n[Note: the command ends with ${sentinelUnsafe === "trailing_backslash" ? "a line-continuation backslash" : "an unclosed quote"}; the exit-code sentinel could not be injected — it ran without exit-code detection. Prefer splitting it into simpler single-line commands.]`, "terminals.bash.nosentinel.note")
+                    : "";
                 // 标记「有哨兵命令在跑」：terminal_wait 据此区分等待与空闲。
-                terminals.setSentinelPending(termId, true);
+                // 无哨兵命令没有可等待的哨兵，标记反而误导 terminal_wait。
+                if (!sentinelUnsafe)
+                    terminals.setSentinelPending(termId, true);
                 const inputErr = terminals.inputChecked(termId, buildTerminalBashLine(runCommand, tailFile) + "\r");
                 if (inputErr)
                     throw new Error(inputErr);
@@ -1633,6 +1727,12 @@ export function makeTerminalBashTool(terminals, opts) {
                         collected += read.data;
                         cursor = read.cursor;
                         lastDataAt = Date.now();
+                        // 长跑/刷屏命令的累积无上限会拖爆服务进程内存。哨兵判定只看尾部
+                        // 8KB（lastSentinel），超限丢最旧一半、保留近期输出即可；
+                        // 命令结束后的 cleanBashOutput 语义不受影响。
+                        if (collected.length > BASH_COLLECT_MAX) {
+                            collected = collected.slice(collected.length - BASH_COLLECT_MAX / 2);
+                        }
                     }
                     const m = lastSentinel(collected);
                     if (m) {
@@ -1654,15 +1754,15 @@ export function makeTerminalBashTool(terminals, opts) {
                         terminals.inputChecked(termId, "\x03");
                         closeOneShot();
                         const timeoutPartial = truncateMiddle(stripAnsi(collected), 4000);
-                        throw new Error(pick(lang, `Command timed out after ${p.timeout}s（已发 Ctrl+C；已有输出：${timeoutPartial}）`, `Command timed out after ${p.timeout}s (sent Ctrl+C; partial output: ${timeoutPartial})`, "terminals.bash.timeout", { "p.timeout": p.timeout, timeoutPartial }));
+                        throw new Error(pick(lang, `Command timed out after ${p.timeout}s（已发 Ctrl+C；已有输出：${timeoutPartial}）${sentinelNote}`, `Command timed out after ${p.timeout}s (sent Ctrl+C; partial output: ${timeoutPartial})${sentinelNote}`, "terminals.bash.timeout", { "p.timeout": p.timeout, timeoutPartial }));
                     }
                     // 静默解阻（仅持久终端）：转后台 + 注册完成观察器，立即把控制权还给模型。
                     if (persist && idleMs > 0 && Date.now() - lastDataAt >= idleMs) {
-                        return backgroundResult(terminals, opts, runCommand, applyHeadTail(cleanBashOutput(collected), p.head, effectiveTail, lang), Math.round((Date.now() - lastDataAt) / 1000), lang, termId, persist, "idle");
+                        return backgroundResult(terminals, opts, runCommand, applyHeadTail(cleanBashOutput(collected), p.head, effectiveTail, lang) + sentinelNote, Math.round((Date.now() - lastDataAt) / 1000), lang, termId, persist, "idle");
                     }
                     // 总时长解阻（持久与一次性终端）：前台运行达到上限，转入后台继续执行，避免卡死。
                     if (maxForegroundMs > 0 && Date.now() - startTime >= maxForegroundMs) {
-                        return backgroundResult(terminals, opts, runCommand, applyHeadTail(cleanBashOutput(collected), p.head, effectiveTail, lang), Math.round((Date.now() - startTime) / 1000), lang, termId, persist, "elapsed");
+                        return backgroundResult(terminals, opts, runCommand, applyHeadTail(cleanBashOutput(collected), p.head, effectiveTail, lang) + sentinelNote, Math.round((Date.now() - startTime) / 1000), lang, termId, persist, "elapsed");
                     }
                 }
             }
@@ -1758,15 +1858,15 @@ export { TERMINAL_TOOL_NAMES } from "./tool-manager.js";
 /** System-prompt guidance teaching the model WHEN to prefer the terminal tools
  *  over one-shot bash. Without it models almost never pick them — bash returns
  *  complete output in a single call, so it always wins on convenience. */
-export const TERMINAL_TOOLS_GUIDANCE = `Persistent interactive terminal tools are available (terminal_create / terminal_list / terminal_close / terminal_input / terminal_key / terminal_read / terminal_wait). The bash tool stays the DEFAULT for ordinary commands - it runs in a visible terminal and returns the full output (persist=false, one-shot terminal that exits when the command finishes). Switch to the bash tool's persist=true, or to the terminal tools, when:
-- The program is interactive or TUI-based (REPLs like python/node, vim/htop, installers asking y/n, anything waiting on stdin). For these, prefer bash({ persist: true }) which runs it in the persistent 'ai-bash' terminal and returns immediately; then drive it with terminal_input / terminal_key (and terminal_read) on terminalId='ai-bash'.
-- You start a long-running server or watcher and want to keep watching its output (terminal_read with waitMs), send keys to it later (e.g. interrupt via terminal_key with Ctrl+c), or block until a backgrounded command finishes without polling (terminal_wait).
-- The user explicitly asks you to work in the visible terminal panel.
-Liveness watchdog: terminals you touched (create/input/key) are monitored - if one goes silent with no new output while you are working (default 15s), an automatic system reminder is injected into the conversation. Treat it as a prompt to check that terminal (terminal_read), respond to an input prompt (terminal_input / terminal_key), or close it (terminal_close) if it is no longer needed.`;
+export const TERMINAL_TOOLS_GUIDANCE = `Persistent interactive terminal tools are available (terminal_create / terminal_list / terminal_close / terminal_input / terminal_key / terminal_read / terminal_wait). The bash tool stays the DEFAULT for ordinary commands. Switch to bash({persist:true}) or the terminal tools when:
+- The program is interactive or TUI-based (REPLs, vim/htop, y/n installers, anything waiting on stdin): prefer bash({persist:true}), which runs it in the persistent 'ai-bash' terminal and returns immediately; then drive it with terminal_input / terminal_key / terminal_read on terminalId='ai-bash'.
+- You start a long-running server or watcher and want to watch its output (terminal_read with waitMs), send keys later (e.g. Ctrl+c via terminal_key), or block until a backgrounded command finishes without polling (terminal_wait).
+- The user asks you to work in the visible terminal panel.
+Liveness watchdog: terminals you touched are monitored — if one goes silent while you are working (default 15s), a system reminder prompts you to check it (terminal_read), answer its input prompt, or close it (terminal_close) if no longer needed.`;
 /** Build the agent-facing persistent terminal tools for one conversation. */
 export function makePersistentTerminalTools(terminals, cwd, 
-/** per-call 返回文本的服务端语言（默认英文）；工具 definition 走 bilingual 内联双语。 */
-lang) {
+/** per-call 返回文本的服务端语言（默认英文）；工具 definition 为纯英文。 */
+lang, options) {
     const getLang = lang ?? (() => "en");
     const result = (text, details = {}) => ({ content: [{ type: "text", text }], details });
     const failIf = (error) => {
@@ -1777,11 +1877,13 @@ lang) {
         defineTool({
             name: "terminal_create",
             label: "Create terminal",
-            description: bilingual("Create a named persistent interactive PTY in the current workspace. Use terminal_input or terminal_key to interact with it and terminal_read to inspect incremental output. Prefer this over bash when the program is interactive/TUI-based (REPLs, vim/htop, y/n prompts), when starting a long-running server you want to keep observing or interrupt, or when the user asks to work in the visible terminal. For simple one-shot commands use bash instead.", "在当前工作区创建具名常驻交互式 PTY。用 terminal_input 或 terminal_key 与之交互，用 terminal_read 查看增量输出。程序是交互式/TUI（REPL、vim/htop、y/n 提示）、要启动长驻服务并持续观察或中断、或用户明确要求在可见终端里操作时，优先用它而非 bash。简单的一次性命令请用 bash。"),
-            promptSnippet: bilingual("run interactive programs or long-running servers in a persistent visible PTY (multi-step: create → input/key → read)", "在常驻可见 PTY 中运行交互式程序或长驻服务（多步：create → input/key → read）"),
+            description: "Create a named persistent interactive PTY. Interact via terminal_input / terminal_key, inspect output via terminal_read. " +
+                "Prefer bash for one-shot commands; use this (or bash persist=true) for interactive/TUI programs (REPLs, vim/htop, y/n prompts) or long-running servers to observe or interrupt.",
+            promptSnippet: "run interactive programs or long-running servers in a persistent visible PTY (multi-step: " +
+                "create → input/key → read)",
             parameters: Type.Object({
-                terminalId: Type.String({ description: bilingual("Stable terminal name", "稳定的终端名称") }),
-                cwd: Type.Optional(Type.String({ description: bilingual("Workspace-relative directory", "工作区相对目录") })),
+                terminalId: Type.String({ description: "Stable terminal name" }),
+                cwd: Type.Optional(Type.String({ description: "Workspace-relative directory" })),
                 cols: Type.Optional(Type.Integer({ minimum: 2, maximum: 500 })),
                 rows: Type.Optional(Type.Integer({ minimum: 2, maximum: 200 })),
             }),
@@ -1799,15 +1901,15 @@ lang) {
         defineTool({
             name: "terminal_list",
             label: "List terminals",
-            description: bilingual("List all persistent PTY terminals owned by this conversation.", "列出本对话拥有的全部常驻 PTY 终端。"),
-            promptSnippet: bilingual("list persistent terminals", "列出常驻终端"),
+            description: "List all persistent PTY terminals owned by this conversation.",
+            promptSnippet: "list persistent terminals",
             parameters: Type.Object({}),
             execute: async () => result(JSON.stringify(terminals.list()), terminals.list()),
         }),
         defineTool({
             name: "terminal_close",
             label: "Close terminal",
-            description: bilingual("Close a persistent PTY and terminate its process tree.", "关闭常驻 PTY 并终止其进程树。"),
+            description: "Close a persistent PTY and terminate its process tree.",
             parameters: Type.Object({ terminalId: Type.String() }),
             execute: async (_id, p) => {
                 const lang = getLang();
@@ -1822,10 +1924,16 @@ lang) {
         defineTool({
             name: "terminal_input",
             label: "Send terminal input",
-            description: bilingual("Send arbitrary text to a persistent PTY. Include newline when a command should be submitted.", "向常驻 PTY 发送任意文本。需要提交命令时带上换行。"),
+            description: "Send arbitrary text to a persistent PTY. Include newline when a command should be submitted.",
             parameters: Type.Object({ terminalId: Type.String(), data: Type.String() }),
             execute: async (_id, p) => {
                 const lang = getLang();
+                if (options?.checkSafety && (p.data.includes("\n") || p.data.includes("\r"))) {
+                    const safety = options.checkSafety(p.data.trim());
+                    if (safety.blocked) {
+                        throw new Error(pick(lang, `【终端输入命令被安全规则阻断】${safety.reason ? ` 原因：${safety.reason}` : ""}`, `[Terminal command blocked by safety rule]${safety.reason ? ` Reason: ${safety.reason}` : ""}`, "terminals.command.blocked", { reason: safety.reason ?? "" }));
+                    }
+                }
                 failIf(terminals.inputChecked(p.terminalId, p.data));
                 // AI 发了输入 = 在等结果，重开一个静默纪元。
                 terminals.noteAgentActivity(p.terminalId);
@@ -1835,11 +1943,11 @@ lang) {
         defineTool({
             name: "terminal_key",
             label: "Send terminal key",
-            description: bilingual("Send Enter, Tab, arrows, function keys, or Ctrl/Alt combinations to a persistent PTY.", "向常驻 PTY 发送 Enter、Tab、方向键、功能键或 Ctrl/Alt 组合键。"),
+            description: "Send Enter, Tab, arrows, function keys, or Ctrl/Alt combinations to a persistent PTY.",
             parameters: Type.Object({
                 terminalId: Type.String(),
                 key: Type.String({
-                    description: bilingual("Enter, Tab, ArrowUp, c, etc.", "按键名，如 Enter、Tab、ArrowUp、c 等"),
+                    description: "Enter, Tab, ArrowUp, c, etc.",
                 }),
                 modifiers: Type.Optional(Type.Object({
                     ctrl: Type.Optional(Type.Boolean()),
@@ -1858,7 +1966,9 @@ lang) {
         defineTool({
             name: "terminal_read",
             label: "Read terminal output",
-            description: bilingual("Read incremental output from a persistent PTY. Keep the returned cursor and pass it on the next read; optionally wait for new output or process exit.", "从常驻 PTY 读取增量输出。保留返回的 cursor，下次读取时传回；可选择等待新输出或进程退出。"),
+            description: "Read incremental output from a persistent PTY. " +
+                "Keep the returned cursor and pass it on the next read; " +
+                "optionally wait for new output or process exit.",
             parameters: Type.Object({
                 terminalId: Type.String(),
                 cursor: Type.Optional(Type.Integer({ minimum: 0 })),
@@ -1879,18 +1989,20 @@ lang) {
         defineTool({
             name: "terminal_wait",
             label: "Wait for terminal command",
-            description: bilingual("Block until a command started THROUGH THE BASH TOOL finishes (its exit marker appears) or the timeout expires — no polling needed. Only applies to terminals with a pending bash-tool command; terminals driven manually via terminal_input (e.g. interactive programs) have no completion marker — use terminal_read(waitMs=…) to observe those instead. Returns {finished, exitCode} plus the output produced while waiting; finished=false means it is STILL running (call again to keep waiting).", "阻塞等待经 BASH 工具启动的命令结束（出现退出标记）或超时——无需轮询。仅适用于有待决 bash 工具命令的终端；经 terminal_input 手动驱动的终端（如交互式程序）没有完成标记——观察它们请用 terminal_read(waitMs=…)。返回 {finished, exitCode} 及等待期间产生的输出；finished=false 表示仍在运行（可再次调用继续等）。"),
-            promptSnippet: bilingual("block until a terminal's current command finishes (no polling)", "阻塞等待终端当前命令结束（无需轮询）"),
+            description: "Block until a command started through the BASH TOOL finishes (exit marker appears) or timeout — no polling. " +
+                "Only applies to bash-tool commands; commands sent via terminal_input have no completion marker — use terminal_read(waitMs=…) for those. " +
+                "Returns {finished, exitCode} plus output produced while waiting; finished=false means still running (call again).",
+            promptSnippet: "block until a terminal's current command finishes (no polling)",
             parameters: Type.Object({
                 terminalId: Type.String(),
                 cursor: Type.Optional(Type.Integer({
                     minimum: 0,
-                    description: bilingual("Ignore exit markers before this absolute offset (default: now)", "忽略该绝对偏移之前的退出标记（默认：现在）"),
+                    description: "Ignore exit markers before this absolute offset (default: now)",
                 })),
                 maxWaitMs: Type.Optional(Type.Integer({
                     minimum: 100,
                     maximum: 600000,
-                    description: bilingual("Max wait in ms (default 300000)", "最长等待毫秒数（默认 300000）"),
+                    description: "Max wait in ms (default 300000)",
                 })),
             }),
             execute: async (_id, p, signal) => {

package/dist/server/tool-manager.js

@@ -77,8 +77,10 @@ export const PATCH_TOOL_NAME = "patch";
 export const LSP_TOOL_NAME = "lsp";
 /** 旧工具名（持久化迁移用；新代码一律用 MARKERS_LIST_TOOL_NAME）。 */
 export const LEGACY_MARKERS_LIST_TOOL_NAME = "markers_list";
-/** 可开关的 Agent 工具总目录（共 27 个；bash 本体与 SDK 内置 edit/read
- *  不进目录——关了 agent 就残了，不给关）。 */
+/** 可开关的 Agent 工具总目录（共 27 个）。核心内置工具 bash/read/edit/write 不进
+ *  目录——目录条目 = OTHER_AGENT_TOOLS 自动渲染的设置行，而这四个在设置页
+ *  「核心工具」区单独开关（见 SettingsModal 的 CORE_BUILTIN_TOOL_NAMES 区块），
+ *  禁用名单同样接受它们（normalizeDisabledAgentTools）。 */
 export const AGENT_TOOL_CATALOG = [
     ...TERMINAL_TOOL_NAMES.map((name) => ({
         name,
@@ -248,13 +250,18 @@ export const AGENT_TOOL_CATALOG = [
         offHintKey: "todoListOffHint",
     },
 ];
+/** SDK 核心内置工具名（可被门控显式禁用或被预设白名单过滤）。 */
+export const CORE_BUILTIN_TOOL_NAMES = ["bash", "read", "edit", "write"];
+export function isCoreBuiltinTool(name) {
+    return CORE_BUILTIN_TOOL_NAMES.includes(name);
+}
 const KNOWN_NAMES = new Set(AGENT_TOOL_CATALOG.map((t) => t.name));
 /** 是否为本表登记的可开关工具（未知名一律 false，不抛错）。 */
 export function isKnownAgentTool(name) {
     return KNOWN_NAMES.has(name);
 }
 /** 归一化禁用名单：非数组回落默认（= 默认关的那些）；数组则只保留已知工具名
- *  （去重；未知名丢弃，防旧文件/手写脏数据污染）。 */
+ *  （去重；未知名丢弃，防旧文件/手写脏数据污染）。支持登记核心内置工具。 */
 export function normalizeDisabledAgentTools(v) {
     if (!Array.isArray(v))
         return defaultDisabledAgentTools();
@@ -262,8 +269,9 @@ export function normalizeDisabledAgentTools(v) {
     for (const x of v) {
         // 旧名迁移：markers_list → todo_list（改名前已关闭的用户保持关闭）。
         const name = x === LEGACY_MARKERS_LIST_TOOL_NAME ? MARKERS_LIST_TOOL_NAME : x;
-        if (typeof name === "string" && KNOWN_NAMES.has(name) && !out.includes(name))
+        if (typeof name === "string" && (KNOWN_NAMES.has(name) || isCoreBuiltinTool(name)) && !out.includes(name)) {
             out.push(name);
+        }
     }
     return out;
 }
@@ -317,21 +325,30 @@ export function setAgentToolsEnabled(session, names, on) {
     }
 }
 /**
- * 全量重放（创建会话 / reload 后 / 设置变更后调）：按禁用名单把目录内工具
- * 逐个加回或剔除；目录外的工具（bash/SDK 内置/插件工具）原样不动。
+ * 全量重放（创建会话 / reload 后 / 设置变更后调）：按禁用名单把目录内工具与
+ * 核心内置工具（bash/read/edit/write，禁用名单接受它们）逐个加回或剔除；
+ * 基线之外的工具（插件工具等）原样不动。
  * 支持传入 preset（预设 id），按预设白名单做二次过滤。
+ * 复原基线取 session.getAllTools()（全集，含被禁用的）——基线里没有的工具不会凭空发明。
  * Session 未就绪时静默跳过（下次创建/reload 会再应用）。
  */
 export function applyAgentToolsGating(session, disabled, preset) {
     try {
         const off = new Set(disabled);
-        const names = new Set(session.getActiveToolNames());
+        const allNames = session.getAllTools().map((t) => t.name);
+        const names = new Set(allNames);
         for (const t of AGENT_TOOL_CATALOG) {
             if (off.has(t.name))
                 names.delete(t.name);
             else
                 names.add(t.name);
         }
+        for (const core of CORE_BUILTIN_TOOL_NAMES) {
+            if (off.has(core))
+                names.delete(core);
+            else if (allNames.includes(core))
+                names.add(core);
+        }
         const filtered = filterToolsByPreset(names, preset);
         session.setActiveToolsByName(filtered);
     }

package/dist/server/tool-overrides.js

@@ -0,0 +1,59 @@
+/**
+ * tool-overrides.ts —— pi-web-ui 对 SDK 内置工具的覆盖（read / write / edit）如何与
+ * **第三方 pi 扩展提供的同名工具共存**。
+ *
+ * 为什么需要这个模块（问题）：SDK 的注册表合并链是
+ * `allCustomTools = [...扩展注册的工具, ...customTools]` 再逐个 `definitionRegistry.set(name, …)`
+ * —— 后写赢 ⇒ **customTools 恒顶掉扩展的同名工具，与加载顺序无关、也没有开关**（见
+ * `dist/core/agent-session.js` 的 `_refreshToolRegistry()`）。而官方
+ * `docs/extensions.md` §Overriding Built-in Tools 明写扩展**可以**覆盖 `read` / `bash` /
+ * `powershell` / `edit` / `write` / `grep` / `find` / `ls` 并逐个列出了 `read`。
+ * pi-web-ui 过去把这三个覆盖直接塞进创建时的 `customTools` ⇒ 那句话在 `read`/`write`/`edit`
+ * 上失效：第三方扩展的同名工具**永远轮不到**，而且症状会伪装（覆盖层转发内置实现 ⇒
+ * 「读文件/图片/目录都正常，只有扩展特有的能力没有」，例如 `pi-better-edit` 的 read 不出锚、
+ * 它的 edit 随后一律 `E_UNKNOWN_ANCHOR`）。
+ *
+ * 做法：这三个覆盖**不再于创建时注册**。会话建好后按名字从**扩展注册表**
+ * （`session.extensionRunner.getAllRegisteredTools()`，不受 customTools 顶替影响）取扩展的同名
+ * 实现当基底，没有则用 pi-web-ui 自己的完整实现，再交给装饰器（`composeWith`）在其上叠加
+ * pi-web-ui 的能力（目录列条目 / 权限沙箱）。装饰器必须把**行为**委托给基底，只加自己那一层；
+ * 基底的 schema、描述、prompt 指引、渲染全部原样保留，扩展独有的参数（如 better-edit 的
+ * `windows`）照旧可用。
+ *
+ * 注入手法与 `plugins.ts` 的 `syncPluginToolsIntoSession` 相同：改 `session._customTools`
+ * 后调 `_refreshToolRegistry()`（SDK 改私有字段名即返回 null，调用方按「覆盖没装上」降级；
+ * `extensionRunner` 缺失时退化成「有扩展也当内置」＝改动前的行为，不会更差）。
+ *
+ * 顺序：注入项排在既有 `_customTools` **之前** ⇒ pi-web-ui 插件注册的同名工具（也是
+ * customTools，比覆盖层后写）仍然是最后赢家，与改动前的相对顺序一致。
+ */
+/** 解析某个工具名在**扩展注册表**里的实现；没有扩展提供时返回 undefined。 */
+export function extensionToolDefinition(session, name) {
+    const tools = session.extensionRunner?.getAllRegisteredTools?.();
+    return tools?.find((tool) => tool.definition?.name === name)?.definition;
+}
+/**
+ * 把覆盖装进已建好的会话：逐个解析基底（扩展同名工具优先）→ 装饰 → 注入 → 刷新注册表。
+ * 返回注入的工具名；会话对象形状不符（SDK 改私有字段名）返回 null，调用方按「覆盖未生效」降级。
+ */
+export function installToolOverrides(session, specs) {
+    if (!Array.isArray(session._customTools) || typeof session._refreshToolRegistry !== "function")
+        return null;
+    const names = new Set(specs.map((s) => s.name));
+    const injected = [];
+    for (const spec of specs) {
+        const extensionTool = extensionToolDefinition(session, spec.name);
+        if (extensionTool) {
+            // 有扩展同名工具：只能叠（composeWith）；没给装饰器就整个让给它 ——
+            // **绝不**用 fallback 顶掉它（那就又是本模块存在要防的那个问题）。
+            if (spec.composeWith)
+                injected.push(spec.composeWith(extensionTool));
+            continue;
+        }
+        injected.push(spec.fallback());
+    }
+    // 同名项先剔除再前置：重复调用幂等（不会层层叠加），且插件工具仍然后写赢。
+    session._customTools = [...injected, ...session._customTools.filter((t) => !names.has(t.name))];
+    session._refreshToolRegistry();
+    return [...names];
+}

package/dist/server/update-check.js

@@ -13,6 +13,7 @@ import { readdirSync, readFileSync, realpathSync, existsSync } from "node:fs";
 import { delimiter, dirname, join } from "node:path";
 import { promisify } from "node:util";
 import { pick } from "./i18n.js";
+import { sdkCopies } from "./sdk-origin.js";
 const PI_CORE_PACKAGE = "@earendil-works/pi-coding-agent";
 /** npm 官方源；用户在 <agentDir>/npm/.npmrc 里配了镜像/私有源时会被覆盖（issue #151）。 */
 export const NPM_DEFAULT_REGISTRY = "https://registry.npmjs.org";
@@ -424,6 +425,32 @@ export function defaultProbePiCore() {
     piCoreProbe = { at: now, version };
     return version;
 }
+/**
+ * issue #321 — detect "a newer pi is installed on this machine than the one
+ * this process actually loaded". The panel's pi-core row probes the GLOBAL pi
+ * CLI (what `npm i -g` updates), but the server loads its own bundled copy
+ * (nested beats ancestor in Node resolution, issue #260) — so after upgrading
+ * the global pi the panel reads "up to date" while conversations still run the
+ * old SDK. That invisible split is exactly what #321 reports; this turns it
+ * into data the UI can explain.
+ *
+ * Two detectors, unioned (newest wins): the CLI probe (standard global
+ * install) and the ancestor-chain copies (fallback when the probe finds
+ * nothing — different npm prefix, bun, …). Pure — tests inject both.
+ * Returns null when nothing newer than `runningVersion` is found.
+ */
+export function detectPiSdkSplit(runningVersion, probePiCore = defaultProbePiCore, copies = sdkCopies()) {
+    let installed = probePiCore();
+    for (const copy of copies) {
+        if (compareVersions(copy.version, runningVersion) > 0 &&
+            (!installed || compareVersions(copy.version, installed) > 0)) {
+            installed = copy.version;
+        }
+    }
+    if (!installed || compareVersions(installed, runningVersion) <= 0)
+        return null;
+    return { running: runningVersion, installed };
+}
 /**
  * Fallback when the CLI probe yields nothing: the version of the vendored pi
  * core copy in <agentDir>/npm/node_modules, or null if that is absent too.
@@ -646,7 +673,7 @@ gitCheck = defaultCheckGitExtension) {
  *  up-to-date ones, errors last. Stable within each bucket (Array.sort is
  *  stable) so registry order survives ties. */
 export function sortUpdateItems(items) {
-    const kindRank = (k) => (k === "webui" ? 0 : k === "pi-core" ? 1 : 2);
+    const kindRank = (k) => (k === "webui" ? 0 : k === "pi-core" ? 1 : k === "plugin" ? 2 : 3);
     return [...items].sort((a, b) => {
         const ka = kindRank(a.kind);
         const kb = kindRank(b.kind);