Windows: bash tool in OpenPI derived sessions (subagent / Web) incorrectly invokes WSL stub; shellPath setting is ignored

[zhujiangbo]

Description

On Windows systems without WSL installed, the bash tool in OpenPI-created subagent / Web sessions fails with the same error (exit code 1) for any command, even something as simple as echo hi:

??? Linux ? Windows ?????????????
?????? Microsoft Store ??????:
https://aka.ms/wslstore

(The message above is in Chinese and originates from C:\Windows\System32\bash.exe, the WSL launcher stub, not a real bash shell.)

This indicates the tool is invoking the WSL stub (System32\bash.exe) rather than the user-configured shell (e.g., Git Bash).

---

Environment

• OS: Windows (Chinese edition), WSL not installed
• Git for Windows: installed at D:\Git (non‑default path)
• Pi version: 0.85.1
• OpenPI version: 0.5.0
• Global setting: ~/.pi/agent/settings.json contains "shellPath": "D:/Git/bin/bash.exe" (the file exists and is executable)

---

Steps to Reproduce

1. Configure "shellPath": "D:/Git/bin/bash.exe" in settings.json.
2. In the interactive Pi session, run !echo hi → works as expected (hi is printed), confirming the main flow respects shellPath.
3. Enter an OpenPI subagent or Web session and use the bash tool to execute any command (e.g., echo hi) → the above WSL stub error appears.

---

Root Cause (Hypothesis)

• The main interactive flow follows the Pi documentation and respects settings.shellPath.
• However, the bash tool in OpenPI‑derived sessions hard‑codes a bare bash call and does not propagate the user‑configured shellPath.
• On Windows, CreateProcess searches System32 before PATH, so it finds System32\bash.exe—the WSL stub—first. Changing PATH alone cannot override this because the system directory takes precedence.
• Code‑level confirmation needed: The host registration for the bash tool in subagent / Web sessions should be checked to see whether it reads shellPath.

---

Suggested Fixes

1. Align the bash tool in derived sessions with the main flow’s shell resolution logic:
   shellPath → Git Bash discovery → fallback to bash—but never use the System32 stub.
2. If resolution results in System32\bash.exe (the WSL stub), pre‑check whether WSL is actually available. If not, fail fast with a clear, actionable error message.
3. On Windows, affected sessions could fall back to or switch to a powershell tool as an alternative.
4. Minor: Ensure tool output is decoded correctly (e.g., GBK for legacy console code pages) to avoid garbled messages that obscure the real error.

---

Workaround

• Perform shell operations inside the main interactive Pi session where shellPath is respected.
• After modifying the configuration, restart the host process that serves OpenPI sessions.

---

[seekskyworld]

已定位根因并认领：extensions/file-mutation-display 在所有 Session 模式的 session_start 中重新注册 createBashToolDefinition(ctx.cwd)，覆盖 Pi 已按 SettingsManager.getShellPath() 构造的原生 bash 定义。子 Session 通过 print 模式绑定扩展后会落回裸 bash，Windows 可能命中 System32\\bash.exe WSL stub。

实施方案：该扩展只负责 TUI 展示，因此仅在 ctx.mode === "tui" 时注册展示包装；headless/RPC/print Session 保留 Pi 原生工具。补充自定义 shell 的子 Session 回归测试，覆盖绑定扩展后的实际 executeBash 路径。

[seekskyworld]

实现已提交 PR #423：#423

中文技术复盘已登记到仓库 Research index：docs/research/ISSUE_419_SHELL_PATH_RETROSPECTIVE_2026-09-07.md。记录包含 Pi 原生 shellPath 解析、展示扩展覆盖边界、最小复现和验证限制。