Document Windows Git Bash path pitfalls for native Windows automation

What feature would you like to see?

Add a Windows-specific diagnostic or documentation note for commands that fail because Kimi Code executes the Bash tool through Git Bash on Windows.

The specific failure class is: a Windows-native command or script emits Windows paths such as E:\path\file.tar, and a POSIX tool inside Git Bash interprets the drive prefix as remote host:file syntax.

One reproducible example is GNU tar in Git Bash:

tar -cf E:\Zero_Base\sumi_os\.momo\state\kimi-gitbash-tar-repro\sample.tar sample.txt
tar: Cannot connect to E: resolve failed
exit=128

The same operation succeeds if the path is converted to Git Bash POSIX form:

tar -cf /e/Zero_Base/sumi_os/.momo/state/kimi-gitbash-tar-repro/posix.tar sample.txt
exit=0

It also succeeds with tar's local-file escape hatch, although that still leaves an awkward Windows-path artifact in this environment:

tar --force-local -cf E:\Zero_Base\sumi_os\.momo\state\kimi-gitbash-tar-repro\sample.tar sample.txt
exit=0

The confusing part for users is that Kimi Code's Windows install path starts from PowerShell, but the agent shell tool is documented and implemented as Git Bash:

• packages/agent-core/src/tools/builtin/shell/bash.ts: Windows uses Git Bash for the Bash tool.
• packages/kaos/src/environment.ts: Windows resolves KIMI_SHELL_PATH or Git-for-Windows bash.exe.
• docs/en/reference/tools.md: "On Windows, Git Bash is used by default."

This is a reasonable default for POSIX-like agent commands, but it is easy to misdiagnose when the failed command is actually a Windows-native automation flow, especially .ps1 scripts, archive commands, installers, or commands that pass Windows absolute paths to POSIX tools.

Suggested scope:

• Add a troubleshooting note in the Windows / tools documentation explaining that Git Bash is a POSIX compatibility layer, not native PowerShell.
• Mention common symptoms such as tar: Cannot connect to E: resolve failed.
• Recommend converting paths to /e/... or using native PowerShell for complex Windows automation.
• Optionally add a focused diagnostic hint when shell output on Windows matches Cannot connect to [A-Z]: resolve failed.

I am not proposing to change the default Windows shell in this issue. This is about making the existing Git Bash boundary clearer and easier to recover from.

Additional information

Local repro environment:

Windows 11
Git for Windows via Scoop
Git Bash: D:\DevConfig\scoop\apps\git\current\bin\bash.exe
Repository source checked: MoonshotAI/kimi-code main-compatible local checkout

The upstream duplicate scan did not find an existing issue specifically for the tar / Windows-drive-prefix failure. Related Windows Git Bash issues exist, for example Windows update and console-window behavior, but they appear to be different failure modes.

This issue is intended as a small diagnostic/docs improvement, not a broad shell-policy change.

Start with docs/en/reference/tools.md and compare its Windows Git Bash description with packages/agent-core/src/tools/builtin/shell/bash.ts and packages/kaos/src/environment.ts. Document the drive-letter path failure, POSIX path conversion, and native PowerShell option; if the diagnostic hint is included, define its scope from the reported error pattern.