# Windows Bash Command Mapping (Git Bash vs WSL stub)

## The Issue
On Windows machines (especially when the AI tool runs in PowerShell context), the `bash` command often resolves to the WSL stub at `C:\Users\...\WindowsApps\bash.exe` instead of the required Git for Windows / MSYS bash.

This breaks the entire ClaudeTools harness:
- `.claude/scripts/vault.sh`, `sync.sh`, `check-messages.sh`, etc. expect GNU bash features, `/d/claudetools` style paths, etc.
- Hooks and commands invoke `bash -c '...'`.
- `self-check` expects: `bash present (GNU bash, version 5.2.37(1)-release (x86_64-pc-msys))`

Symptoms: "Windows Subsystem for Linux has no installed distributions." or scripts failing with path/quoting issues.

## The Fix
Prepend Git Bash directories to `$env:Path` so plain `bash` resolves to the correct one:

```powershell
$gitBin = "C:\Program Files\Git\bin"
$gitUsrBin = "C:\Program Files\Git\usr\bin"
if ((Test-Path $gitBin) -and ((Get-Command bash -ErrorAction SilentlyContinue).Source -notlike '*Git*bin*bash.exe')) {
    $env:Path = "$gitBin;$gitUsrBin;" + ($env:Path -replace [regex]::Escape("$gitBin;"), '' -replace [regex]::Escape("$gitUsrBin;"), '')
}
```

After this:
- `Get-Command bash` returns `C:\Program Files\Git\bin\bash.exe`
- `bash --version` shows the MSYS version
- Plain invocations like `bash .claude/scripts/vault.sh list` work.

## Project Helper
Use the reusable script:

```powershell
. .claude/scripts/ensure-git-bash.ps1
```

It contains the logic above (idempotent, with verbose/warning).

## Persistence
The user's PowerShell profile (`$PROFILE`) sources/contains the remap logic so it applies on shell startup.

See: `.claude/scripts/ensure-git-bash.ps1` (the helper) and the profile for the exact code.

## For AI Sessions (Grok or Claude)
- At the start of any command involving bash/harness scripts, ensure the mapping (source the ps1 or run the snippet).
- In Grok: the `.grok/skills/windows-bash/SKILL.md` (if present) and this memory entry will be available.
- Always prefer explicit full path ` "C:\Program Files\Git\bin\bash.exe" .claude/scripts/vault.sh ... ` for critical one-off calls if the env isn't trusted yet.
- Git Bash terminals (launched directly) already have the correct bash.

## Related
- See the backslash hook for another Git Bash gotcha: `.claude/hooks/block-backslash-winpath.sh`
- SSH: always use system OpenSSH (`C:\Windows\System32\OpenSSH\ssh.exe`), never Git's ssh.
- Profile and PATH ordering is the standard way; do not remove the WindowsApps stub.

This was fixed during a session on GURU-5070 to make Grok tool calls reliable with the harness. Add similar entries for other machine-specific env quirks.