pi-web-ui 0.19.2 → 0.20.0

package/dist/server/agent-service.js

@@ -14,7 +14,7 @@ import { spawn } from "node:child_process";
 import { existsSync, readFileSync, statSync, writeFileSync, mkdirSync, watch, } from "node:fs";
 import { dirname, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
-import { createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, defineTool, getAgentDir, ModelRuntime, SessionManager, } from "@earendil-works/pi-coding-agent";
+import { createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, createBashTool, createLocalBashOperations, defineTool, getAgentDir, ModelRuntime, SessionManager, } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { serializeMessage, serializeStreamingMessage, } from "./serialize.js";
 import { loadCommands, saveCommandsFile, TerminalManager, } from "./terminals.js";
@@ -218,10 +218,122 @@ function decodeText(buf) {
         }
     }
 }
-/** Windows persona appendix: legacy Chinese files are often GBK/GB2312 — read
- *  them via the terminal with the right encoding, never paste mojibake into
- *  reasoning/answers. Appended to the SDK system prompt on win32 only. */
-const WINDOWS_GBK_PERSONA = `You are a coding agent running on Windows. Many legacy Chinese text files (.html/.txt/.md/.log, exported documents) are GBK/GB2312 encoded: the read tool decodes UTF-8 only and will show mojibake (乱码) for them. If a file's content looks garbled, read it through the terminal instead: in Git Bash use \`cat file | iconv -f GBK -t UTF-8\` (or \`iconv -f GBK -t UTF-8 file\`); in cmd use \`chcp 65001 && type file\`; in PowerShell use \`Get-Content -Encoding Default file\`. Never paste mojibake into your reasoning or answer — describe the decoded content instead.`;
+/** Windows persona appendix — appended to the SDK system prompt on win32 only.
+ *  Two failure modes it guards against: (1) the SDK bash tool has NO default
+ *  timeout, so a long-running command hangs the whole conversation forever;
+ *  (2) the in-app terminal is an interactive TTY where heredocs / interactive
+ *  programs wait for input that never comes. Legacy Chinese files are often
+ *  GBK/GB2312 — read them with the right encoding, never paste mojibake into
+ *  reasoning/answers. */
+const WINDOWS_PERSONA = `You are a coding agent running on Windows. The bash tool runs Git Bash (bash.exe), not PowerShell. Follow these rules to avoid hanging the session:
+
+
+
+- ALWAYS pass a timeout parameter to the bash tool (in seconds). There is NO default timeout — a command that never finishes (servers, watchers, infinite loops, slow downloads/installs) will hang the entire conversation indefinitely. Pick a generous timeout for long-running work, but never omit it.
+- NEVER run interactive or foreground long-running commands through the bash tool (vi, less, top, python -, node -, npm run dev, sleep 10000). For servers/daemons use background execution with output redirected to a log file, then poll the log; stop them when done.
+- In the interactive terminal (TTY) — which is Git Bash too, not PowerShell — NEVER use heredocs (<<'EOF' ... EOF) or here-strings, and NEVER start interactive programs (vi, less, python -, node -, npm init): they wait for keyboard input that never arrives and hang the terminal forever. Prefer writing a temp script file (e.g. .pi-tmp.sh) and running it non-interactively. ALWAYS pass a timeout to long-running commands (e.g. \`timeout 120 npm run dev\`).
+
+Many legacy Chinese text files (.html/.txt/.md/.log, exported documents) are GBK/GB2312 encoded: the read tool decodes UTF-8 only and will show mojibake (乱码) for them. If a file's content looks garbled, read it through the terminal instead: in Git Bash use \`cat file | iconv -f GBK -t UTF-8\` (or \`iconv -f GBK -t UTF-8 file\`); in cmd use \`chcp 65001 && type file\`; in PowerShell use \`Get-Content -Encoding Default file\`. Never paste mojibake into your reasoning or answer — describe the decoded content instead.`;
+/**
+ * Killable bash tool: wraps the SDK bash tool with operations that register
+ * their own AbortController into a client-level set. abortBash() aborts only
+ * those controllers → the command's process tree is killed while the agent
+ * run and the conversation continue (the tool returns an aborted error and
+ * the model moves on). Injected as a customTool overriding the builtin bash.
+ */
+function makeKillableBashTool(cwd, kills) {
+    const base = createLocalBashOperations();
+    const tool = createBashTool(cwd, {
+        operations: {
+            exec: async (command, c, opts) => {
+                const ac = new AbortController();
+                kills.add(ac);
+                try {
+                    const signals = [opts.signal, ac.signal].filter((s) => s !== undefined);
+                    return await base.exec(command, c, {
+                        ...opts,
+                        signal: signals.length > 1 ? AbortSignal.any(signals) : signals[0],
+                    });
+                }
+                finally {
+                    kills.delete(ac);
+                }
+            },
+        },
+    });
+    // AgentTool → ToolDefinition (same fields; customTools expects definitions).
+    return {
+        name: tool.name,
+        label: tool.label,
+        description: tool.description,
+        parameters: tool.parameters,
+        prepareArguments: tool.prepareArguments,
+        executionMode: tool.executionMode,
+        execute: (toolCallId, params, signal, onUpdate) => tool.execute(toolCallId, params, signal, onUpdate),
+    };
+}
+/**
+ * Snapshot currently LISTENING TCP ports → owning pid. Windows: netstat;
+ * POSIX: lsof. Used to detect servers the agent started in the background
+ * (the bash tool itself exits, leaving e.g. `npm run dev &` listening).
+ */
+async function snapshotListeningPorts() {
+    const m = new Map();
+    try {
+        const { execFile } = await import("node:child_process");
+        if (process.platform === "win32") {
+            const out = await new Promise((resolve, reject) => execFile("netstat", ["-ano", "-p", "tcp"], { windowsHide: true, timeout: 8000 }, (err, stdout) => (err ? reject(err) : resolve(stdout))));
+            for (const line of out.split(/\r?\n/)) {
+                const p = line.trim().split(/\s+/);
+                // TCP 0.0.0.0:5173 0.0.0.0:0 LISTENING 12345
+                if (p.length >= 5 && p[0] === "TCP" && p[3] === "LISTENING") {
+                    const port = Number(p[1].split(":").pop());
+                    const pid = Number(p[4]);
+                    if (Number.isFinite(port) && Number.isFinite(pid))
+                        m.set(port, pid);
+                }
+            }
+        }
+        else {
+            const out = await new Promise((resolve, reject) => execFile("lsof", ["-iTCP", "-sTCP:LISTEN", "-P", "-n"], { timeout: 8000 }, (err, stdout) => (err ? reject(err) : resolve(stdout))));
+            for (const line of out.split(/\r?\n/).slice(1)) {
+                const p = line.trim().split(/\s+/);
+                if (p.length >= 9) {
+                    // NAME column tail: "*:5173 (LISTEN)" or "[::1]:5173 (LISTEN)"
+                    const mm = (p[p.length - 1] ?? "").match(/(\d+)\)?\s*$/);
+                    const port = mm ? Number(mm[1]) : NaN;
+                    const pid = Number(p[1]);
+                    if (Number.isFinite(port) && Number.isFinite(pid))
+                        m.set(port, pid);
+                }
+            }
+        }
+    }
+    catch {
+        // best effort — snapshot failure just means no tracking this round
+    }
+    return m;
+}
+/** Kill a pid and its whole process tree (cross-platform). */
+function killPidTree(pid) {
+    try {
+        if (process.platform === "win32") {
+            void import("node:child_process").then(({ spawn }) => {
+                spawn("taskkill", ["/F", "/T", "/PID", String(pid)], {
+                    stdio: "ignore",
+                    detached: true,
+                    windowsHide: true,
+                }).unref();
+            });
+        }
+        else {
+            process.kill(-pid, "SIGKILL");
+        }
+    }
+    catch {
+        // already dead
+    }
+}
 /**
  * Cheap per-message discriminator for the serialization cache key. Persisted
  * message content never changes, so this is stable across snapshots, while
@@ -709,6 +821,15 @@ class ClientStateStore {
         this.save();
     }
 }
+/** Hard cap on how long ONE tool call may run before the watchdog aborts the
+ *  session. The SDK bash tool has NO default timeout, so a command that never
+ *  finishes (servers, watchers, infinite loops) would otherwise hang the whole
+ *  conversation indefinitely. Override with the PI_WEB_TOOL_TIMEOUT_MS env var
+ *  (milliseconds). */
+const TOOL_WATCHDOG_TIMEOUT_MS = (() => {
+    const v = Number(process.env.PI_WEB_TOOL_TIMEOUT_MS);
+    return Number.isFinite(v) && v > 0 ? v : 20 * 60_000;
+})();
 /** Cap on simultaneously open conversations of ONE project (each keeps a full
  *  runtime alive; conversations of other projects keep their own lists). */
 const MAX_OPEN_CONVERSATIONS = 8;
@@ -808,6 +929,23 @@ export class ClientSession {
     static WIZARD_IDLE_TIMEOUT_MS = 5 * 60_000;
     /** Absolute deadline for the whole wizard session (model latency guard). */
     static WIZARD_MAX_TOTAL_MS = 20 * 60_000;
+    /** How long a hard abort waits for session.abort() to make the run idle
+     *  before force-resetting the conversation (model streams that ignore the
+     *  abort signal would otherwise leave the chat stuck forever). */
+    static HARD_ABORT_TIMEOUT_MS = 15_000;
+    /** Extra settle window after session.abort() returns: the run is only
+     *  considered stopped once its agent_end event arrives. If it doesn't
+     *  (model stream stuck before the run even started), force-reset. */
+    static HARD_ABORT_SETTLE_MS = 8_000;
+    /** Live AbortControllers of THIS client's running bash tool calls — aborting
+     *  them kills only the command (agent run and conversation continue). */
+    bashKills = new Set();
+    /** LISTENING-port snapshot taken when the current bash tool started — the
+     *  end-of-execution diff reveals servers the agent left running in the
+     *  background (e.g. `npm run dev &`). Keyed by port → pid. */
+    bashListenBefore = null;
+    /** Background servers the agent started (port → pid). 「中断」kills them. */
+    bgServers = new Map();
     /** The active conversation (all session operations target it). */
     get conv() {
         const conv = this.convs.get(this.activeId);
@@ -904,17 +1042,26 @@ export class ClientSession {
                 modelRuntime: this.sharedModelRuntime,
                 ...(process.platform === "win32"
                     ? {
-                        // Windows 上很多老中文文件（.html/.txt/.md/.log、导出文档）是
-                        // GBK/GB2312 编码，read 工具按 UTF-8 读会乱码——注入 persona 让模型
-                        // 改用终端按 GBK 读，且绝不把乱码贴进推理/回答。
+                        // Windows 专属 persona：bash 工具跑 Git Bash 且无默认超时、终端是
+                        // 交互式 TTY——注入约束避免 heredoc/交互/长驻命令挂死整个会话；
+                        // GBK 老中文文件让模型改用终端按正确编码读（iconv/chcp/Get-Content）。
                         resourceLoaderOptions: {
-                            systemPromptOverride: (base) => base ? `${base}\n\n${WINDOWS_GBK_PERSONA}` : WINDOWS_GBK_PERSONA,
+                            systemPromptOverride: (base) => base ? `${base}\n\n${WINDOWS_PERSONA}` : WINDOWS_PERSONA,
                         },
                     }
                     : {}),
             });
             return {
-                ...(await createAgentSessionFromServices({ services, sessionManager })),
+                ...(await createAgentSessionFromServices({
+                    services,
+                    sessionManager,
+                    // 可手动停止的 bash 工具：覆盖 SDK 内置 bash（customTools 按 name
+                    // 覆盖），执行时把自己的 AbortController 注册进客户端集合——
+                    // abortBash() 只杀这些命令，agent run 与对话继续。
+                    customTools: [
+                        makeKillableBashTool(effectiveCwd, this.bashKills),
+                    ],
+                })),
                 services,
                 diagnostics: services.diagnostics,
             };
@@ -943,6 +1090,7 @@ export class ClientSession {
             queueSteering: 0,
             queueFollowUp: 0,
             toolStartTimes: new Map(),
+            toolWatchdogs: new Map(),
         };
     }
     /** Add a socket to this client's broadcast set; flushes buffered startup notices. */
@@ -1013,6 +1161,44 @@ export class ClientSession {
                 this.webUi.refresh();
         }, WIDGET_REFRESH_MS);
     }
+    /** Arm the hang-guard for a tool call: if it is still running after
+     *  TOOL_WATCHDOG_TIMEOUT_MS, abort the session instead of letting the
+     *  conversation hang forever (the SDK bash tool has no default timeout). */
+    armToolWatchdog(conv, toolCallId) {
+        const t = setTimeout(() => {
+            conv.toolWatchdogs.delete(toolCallId);
+            // The tool finished before the deadline — nothing to do.
+            if (!conv.toolStartTimes.has(toolCallId))
+                return;
+            this.emit({
+                type: "notice",
+                level: "warning",
+                text: `工具执行超过 ${Math.round(TOOL_WATCHDOG_TIMEOUT_MS / 60_000)} 分钟，已自动终止（防止挂死）。可调整超时：环境变量 PI_WEB_TOOL_TIMEOUT_MS（毫秒）。`,
+            });
+            conv.toolStartTimes.delete(toolCallId);
+            // Abort the run (kills the process tree via the SDK's abort signal);
+            // agent_end will fire with stopReason "aborted" and existing logic
+            // clears any goal / review loop. interruptRun adds a force-reset
+            // fallback in case the model stream ignores the abort signal.
+            void this.interruptRun(conv, "工具执行超时");
+        }, TOOL_WATCHDOG_TIMEOUT_MS);
+        t.unref?.();
+        conv.toolWatchdogs.set(toolCallId, t);
+    }
+    /** Cancel a tool's watchdog — called when the tool finishes normally. */
+    clearToolWatchdog(conv, toolCallId) {
+        const t = conv.toolWatchdogs.get(toolCallId);
+        if (t) {
+            clearTimeout(t);
+            conv.toolWatchdogs.delete(toolCallId);
+        }
+    }
+    /** Cancel every watchdog of a conversation (removeConversation / dispose). */
+    clearAllToolWatchdogs(conv) {
+        for (const t of conv.toolWatchdogs.values())
+            clearTimeout(t);
+        conv.toolWatchdogs.clear();
+    }
     onEvent(conv, event) {
         switch (event.type) {
             case "bash_execution_update": {
@@ -1030,11 +1216,24 @@ export class ClientSession {
                 // Record the moment the tool actually starts so tool_status can
                 // report real execution time (vs. time spent waiting on the model).
                 conv.toolStartTimes.set(event.toolCallId, Date.now());
+                // Snapshot listeners before a bash run — the post-run diff catches
+                // servers the agent started in the background.
+                if (event.toolName === "bash") {
+                    void snapshotListeningPorts().then((m) => {
+                        this.bashListenBefore = m;
+                    });
+                }
+                this.armToolWatchdog(conv, event.toolCallId);
                 break;
             }
             case "tool_execution_end": {
                 const startedAt = conv.toolStartTimes.get(event.toolCallId);
                 conv.toolStartTimes.delete(event.toolCallId);
+                this.clearToolWatchdog(conv, event.toolCallId);
+                // Bash finished — wait briefly for background servers to bind their
+                // ports, then diff against the pre-run snapshot and record them.
+                if (event.toolName === "bash")
+                    void this.trackBackgroundServers();
                 const durationMs = startedAt !== undefined ? Date.now() - startedAt : undefined;
                 // The bash tool does not put its exit code in result.details — on
                 // failure it throws "Command exited with code N" and the agent
@@ -2509,9 +2708,123 @@ export class ClientSession {
         }
         return out;
     }
+    /**
+     * Hard-abort the running agent (Stop button / global 中断). Tries
+     * session.abort() first; if the run is not idle within
+     * HARD_ABORT_TIMEOUT_MS (model stream ignoring the abort signal), the
+     * conversation's runtime is force-disposed and recreated from the last
+     * persisted session so the chat ALWAYS comes back usable — never stuck
+     * overnight. The notice fires only on the forced-reset path.
+     */
     async abort() {
+        await this.interruptRun(this.conv, "已停止");
+        // 中断同时清理 AI 在后台启动的服务（npm run dev & 等）——避免用户
+        // 测试时发现端口被占用而不知道是什么进程。
+        const killed = await this.killBackgroundServers();
+        if (killed.length > 0) {
+            this.emit({
+                type: "notice",
+                level: "info",
+                text: `已停止 AI 后台服务：端口 ${killed.join("、")}（进程已结束）`,
+            });
+        }
+        this.flushSnapshot();
+    }
+    /** After a bash tool run, wait briefly for background servers to bind,
+     *  then diff the listening-port snapshot against the pre-run one and
+     *  remember anything new — those are servers the agent left running. */
+    async trackBackgroundServers() {
+        const before = this.bashListenBefore;
+        this.bashListenBefore = null;
+        if (!before)
+            return;
+        await new Promise((r) => setTimeout(r, 1500));
+        const after = await snapshotListeningPorts();
+        for (const [port, pid] of after) {
+            if (!before.has(port) && !this.bgServers.has(port)) {
+                this.bgServers.set(port, { pid, since: Date.now() });
+                this.emit({
+                    type: "notice",
+                    level: "info",
+                    text: `检测到 AI 启动的后台服务：端口 ${port}（pid ${pid}）——点顶栏「中断」可停止`,
+                });
+            }
+        }
+    }
+    /** Kill every background server the agent started; returns the freed ports. */
+    async killBackgroundServers() {
+        if (this.bgServers.size === 0)
+            return [];
+        const killed = [];
+        for (const [port, { pid }] of [...this.bgServers]) {
+            killPidTree(pid);
+            killed.push(String(port));
+        }
+        this.bgServers.clear();
+        return killed;
+    }
+    /** Kill only the running bash command(s) — the agent run itself continues
+     *  (the bash tool returns an aborted error and the model moves on). Uses
+     *  the per-client AbortController set registered by
+     *  makeKillableBashTool. */
+    async abortBash() {
+        if (this.bashKills.size === 0) {
+            this.emit({
+                type: "notice",
+                level: "info",
+                text: "当前没有正在运行的 bash 命令",
+            });
+            this.flushSnapshot();
+            return;
+        }
+        for (const ac of [...this.bashKills])
+            ac.abort();
+        this.emit({
+            type: "notice",
+            level: "info",
+            text: "已停止 bash 命令（对话继续）",
+        });
+        // 让 AI 明确知道是用户手动停止：sendUserMessage 触发下一轮，agent
+        // 会看到「命令被用户中止」而不是普通失败，并据此继续（不会困惑于
+        // 为什么命令失败了）。
+        try {
+            await this.conv.runtime.session.sendUserMessage("（系统：用户手动停止了刚才的 bash 命令——命令被中止，终止前已输出的内容在对应工具结果里。请据此继续，不要重跑被中止的命令，除非确实必要。）");
+        }
+        catch {
+            // best effort — 消息注入失败不影响命令已停止的事实
+        }
+        this.flushSnapshot();
+    }
+    /** Interrupt a run: abort, with a force-reset fallback on timeout. */
+    async interruptRun(conv, reason) {
+        // The run is only truly stopped when its agent_end event arrives:
+        // session.abort() can return without stopping anything when the run is
+        // stuck before the agent even started (e.g. a model stream that never
+        // begins), so we watch for agent_end and force-reset when it never
+        // comes — abort 卡住（超时）或空转（结算窗口）两条路都覆盖。
+        let ended = false;
+        let forced = false;
+        const off = conv.session.subscribe((e) => {
+            if (e.type === "agent_end") {
+                ended = true;
+            }
+        });
+        const force = () => {
+            if (forced)
+                return;
+            forced = true;
+            void this.forceResetConversation(conv, `${reason}：运行未终止，已强制重置当前对话`);
+        };
+        // 1) abort itself hangs (model stream ignores the signal) → hard kill.
+        const abortTimer = setTimeout(() => {
+            if (!ended)
+                force();
+        }, ClientSession.HARD_ABORT_TIMEOUT_MS);
+        abortTimer.unref?.();
+        // 2) abort itself (Stop semantics: kills the process tree, emits
+        //    agent_end with stopReason "aborted" on the normal path).
         try {
-            await this.session.abort();
+            await conv.runtime.session.abort();
         }
         catch (err) {
             this.emit({
@@ -2520,7 +2833,46 @@ export class ClientSession {
                 text: `中止失败：${err.message}`,
             });
         }
-        this.flushSnapshot();
+        // 3) abort returned but no agent_end within the settle window → the
+        //    run was stuck before it started; force-reset to recover.
+        if (!ended) {
+            await new Promise((r) => setTimeout(r, ClientSession.HARD_ABORT_SETTLE_MS));
+        }
+        clearTimeout(abortTimer);
+        off();
+        if (!ended)
+            force();
+    }
+    /** Force-reset a conversation: dispose the stuck runtime (kills the hung
+     *  model stream / child processes) and rebuild it from the most recent
+     *  persisted session. The conversation record itself is kept (same id,
+     *  same cwd, same serialization caches), so the UI stays attached. */
+    async forceResetConversation(conv, reason) {
+        try {
+            conv.unsubscribe?.();
+            conv.unsubscribe = undefined;
+            this.clearAllToolWatchdogs(conv);
+            conv.toolStartTimes.clear();
+            await conv.runtime.dispose();
+            const runtime = await createAgentSessionRuntime(this.makeRuntimeFactory(), {
+                cwd: conv.cwd,
+                agentDir: this.agentDir,
+                sessionManager: SessionManager.continueRecent(conv.cwd),
+            });
+            conv.runtime = runtime;
+            conv.session = runtime.session;
+            this.emit({ type: "notice", level: "warning", text: reason });
+            await this.bindSession();
+            this.emitConversations();
+            void this.pushSlashCommands();
+        }
+        catch (err) {
+            this.emit({
+                type: "notice",
+                level: "error",
+                text: `强制中断失败：${err.message}`,
+            });
+        }
     }
     async newChat() {
         // Reuse an already-open blank conversation instead of piling up new ones
@@ -2620,6 +2972,7 @@ export class ClientSession {
         if (!conv || id === this.activeId)
             return;
         this.convs.delete(id);
+        this.clearAllToolWatchdogs(conv);
         conv.unsubscribe?.();
         conv.unsubscribe = undefined;
         void conv.runtime.dispose().catch(() => { });
@@ -3975,6 +4328,7 @@ export class ClientSession {
         this.unwatchDir();
         this.webUi.dispose();
         for (const conv of this.convs.values()) {
+            this.clearAllToolWatchdogs(conv);
             conv.unsubscribe?.();
             try {
                 await conv.runtime.dispose();

package/dist/server/ensure-bash.js

@@ -0,0 +1,80 @@
+/**
+ * Lightweight bash fallback for Windows.
+ *
+ * When neither Git Bash nor a bash on PATH exists, download busybox-w32
+ * (single self-contained ~1.5MB exe, no installer) into <home>/.pi-web/bin/
+ * and expose it as bash.exe — busybox dispatches on argv[0], so `bash.exe`
+ * runs its bash (ash) applet. The terminal panel (terminals.ts) and the SDK
+ * bash tool (via PATH) then both resolve to it, so the agent never silently
+ * falls back to cmd/PowerShell syntax on a bare Windows box.
+ *
+ * Download is fire-and-forget at server start and never throws: on failure
+ * the terminal simply falls back to $COMSPEC (cmd.exe) as before.
+ */
+import { copyFileSync, existsSync, mkdirSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+/** Official busybox-w32 64-bit Unicode build (Win10 1903+ / Win11). */
+const BUSYBOX_URL = "https://frippery.org/files/busybox/busybox64u.exe";
+/** busybox.exe is ~660KB; anything far smaller is an error page, not a binary. */
+const MIN_SIZE = 500_000;
+/** Download cap — a stalled connection must not block startup forever. */
+const DOWNLOAD_TIMEOUT_MS = 60_000;
+/** Directory holding the busybox fallback (shared with terminals.ts / PATH). */
+export function windowsBashDir() {
+    return join(homedir(), ".pi-web", "bin");
+}
+/** bash.exe (busybox bash applet) used by the terminal and the SDK bash tool. */
+export function windowsBashPath() {
+    return join(windowsBashDir(), "bash.exe");
+}
+/** True when a standard Git Bash install exists (SDK's preferred shell). */
+export function hasGitBash() {
+    const pf = process.env.ProgramFiles;
+    const pf86 = process.env["ProgramFiles(x86)"];
+    for (const cand of [
+        pf ? join(pf, "Git", "bin", "bash.exe") : "",
+        pf86 ? join(pf86, "Git", "bin", "bash.exe") : "",
+    ]) {
+        if (cand && existsSync(cand))
+            return true;
+    }
+    return false;
+}
+/**
+ * Ensure a bash.exe exists on Windows. No-op when Git Bash is already
+ * installed (it is strictly preferred) or the fallback is already present.
+ * Never throws — failures degrade silently to the previous behaviour.
+ *
+ * @returns the bash.exe path when ready, null otherwise.
+ */
+export async function ensureWindowsBash() {
+    if (process.platform !== "win32")
+        return null;
+    const target = windowsBashPath();
+    if (existsSync(target))
+        return target;
+    if (hasGitBash())
+        return null; // Git Bash preferred — nothing to install.
+    const dir = windowsBashDir();
+    mkdirSync(dir, { recursive: true });
+    const tmp = join(dir, `busybox-${process.pid}.tmp`);
+    try {
+        const res = await fetch(BUSYBOX_URL, {
+            signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS),
+        });
+        if (!res.ok)
+            return null;
+        const buf = Buffer.from(await res.arrayBuffer());
+        if (buf.length < MIN_SIZE)
+            return null; // error/HTML page, not the exe.
+        writeFileSync(tmp, buf);
+        renameSync(tmp, join(dir, "busybox.exe"));
+        copyFileSync(join(dir, "busybox.exe"), target);
+        return target;
+    }
+    catch {
+        rmSync(tmp, { force: true });
+        return null;
+    }
+}

package/dist/server/index.js

@@ -21,7 +21,7 @@ import { stat } from "node:fs/promises";
 import { createServer } from "node:http";
 import { createConnection } from "node:net";
 import { spawn } from "node:child_process";
-import { basename, dirname, join, resolve } from "node:path";
+import { basename, delimiter, dirname, join, resolve } from "node:path";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { randomUUID } from "node:crypto";
@@ -29,6 +29,7 @@ import express from "express";
 import { WebSocket, WebSocketServer } from "ws";
 import { VERSION, getAgentDir } from "@earendil-works/pi-coding-agent";
 import { AgentService, previewKind, workspacePath } from "./agent-service.js";
+import { ensureWindowsBash, windowsBashDir } from "./ensure-bash.js";
 const PORT = Number(process.env.PORT ?? 8787);
 const CWD = resolve(process.env.PI_WEB_CWD ?? process.cwd());
 const DATA_DIR = resolve(process.env.PI_WEB_DATA_DIR ?? join(homedir(), ".pi-web"));
@@ -36,6 +37,13 @@ const DATA_DIR = resolve(process.env.PI_WEB_DATA_DIR ?? join(homedir(), ".pi-web
 // <SESSION_DIR_ROOT>/--<cwd>--/, shared with the pi CLI/TUI (getAgentDir
 // honors PI_CODING_AGENT_DIR).
 const SESSION_DIR_ROOT = join(getAgentDir(), "sessions");
+// Windows 轻量 bash 兜底：把 <home>/.pi-web/bin 前置到 PATH（SDK 的 bash 工具经
+// findBashOnPath 会找到其中的 bash.exe），并在无 Git Bash 时后台下载 busybox-w32。
+// 终端面板的 shell 探测链也已包含该目录（见 terminals.ts resolveShell）。
+if (process.platform === "win32") {
+    process.env.PATH = `${windowsBashDir()}${delimiter}${process.env.PATH ?? ""}`;
+    void ensureWindowsBash();
+}
 const app = express();
 app.use(express.json({ limit: "10mb" }));
 app.get("/api/health", (_req, res) => {
@@ -209,6 +217,9 @@ wss.on("connection", (ws) => {
             case "abort":
                 void cs.abort();
                 break;
+            case "abort_bash":
+                void cs.abortBash();
+                break;
             case "new_chat":
                 void cs.newChat();
                 break;

package/dist/server/terminals.js

@@ -103,16 +103,50 @@ export async function saveCommandsFile(workspaceRoot, commands) {
     }
 }
 const isWindows = process.platform === "win32";
+/** `-i` makes bash interactive; cmd.exe / powershell.exe are interactive on their own. */
+function bashArgs(shell) {
+    return /[\\/]bash(\.exe)?$/i.test(shell) ? ["-i"] : [];
+}
 /**
- * Interactive shell for PTYs. Windows has no $SHELL: use Git Bash if the user
- * has it, otherwise the console host from $COMSPEC (always set → cmd.exe).
- * POSIX uses the user's login shell, falling back to bash.
+ * Interactive shell for PTYs.
+ * - Windows: prefer bash — it matches the SDK's bash tool, so the agent and
+ *   the terminal speak the same shell language (no more PowerShell/bash
+ *   混用 that leaves heredocs / `&&` / `<<` hanging or erroring). Order:
+ *   1. PI_WEB_SHELL (explicit override)
+ *   2. $SHELL when it exists on disk (user launched from a Git Bash session)
+ *   3. Git Bash install paths (ProgramFiles / ProgramFiles(x86))
+ *   4. busybox-w32 fallback in <home>/.pi-web/bin/bash.exe (ensure-bash.ts
+ *      downloads it automatically when 2–3 are absent)
+ *   5. $COMSPEC (cmd.exe — always set)
+ *   6. powershell.exe (last resort)
+ * - POSIX: the user's login shell, falling back to bash.
+ * Resolved per terminal spawn (not at module load) so a busybox download that
+ * finishes after startup is picked up by the next terminal.
  */
-const SHELL = isWindows
-    ? process.env.SHELL || process.env.COMSPEC || "powershell.exe"
-    : process.env.SHELL || "bash";
-/** `-i` is POSIX-only; cmd.exe / powershell.exe start interactively on their own. */
-const SHELL_ARGS = isWindows ? [] : ["-i"];
+function resolveShell() {
+    if (isWindows) {
+        const explicit = process.env.PI_WEB_SHELL;
+        if (explicit)
+            return { shell: explicit, args: bashArgs(explicit) };
+        const she = process.env.SHELL;
+        if (she && existsSync(she))
+            return { shell: she, args: bashArgs(she) };
+        const pf = process.env.ProgramFiles;
+        const pf86 = process.env["ProgramFiles(x86)"];
+        for (const cand of [
+            pf ? join(pf, "Git", "bin", "bash.exe") : "",
+            pf86 ? join(pf86, "Git", "bin", "bash.exe") : "",
+        ]) {
+            if (cand && existsSync(cand))
+                return { shell: cand, args: ["-i"] };
+        }
+        const busybox = join(homedir(), ".pi-web", "bin", "bash.exe");
+        if (existsSync(busybox))
+            return { shell: busybox, args: ["-i"] };
+        return { shell: process.env.COMSPEC || "powershell.exe", args: [] };
+    }
+    return { shell: process.env.SHELL || "bash", args: ["-i"] };
+}
 /**
  * Environment for spawned shells. System services (launchd/systemd) run with
  * no locale variables, which puts the shell in the C locale: its line editor
@@ -302,7 +336,8 @@ export class TerminalManager {
         repairSpawnHelperPermissions();
         let pty;
         try {
-            pty = spawn(SHELL, SHELL_ARGS, {
+            const { shell, args } = resolveShell();
+            pty = spawn(shell, args, {
                 name: "xterm-256color",
                 cols: Math.max(2, Math.floor(cols) || 80),
                 rows: Math.max(2, Math.floor(rows) || 24),