sync: auto-sync from GURU-5070 at 2026-06-02 20:40:54

Author: Mike Swanson
Machine: GURU-5070
Timestamp: 2026-06-02 20:40:54

.claude/memory/feedback_windows_bash_mapping.md

@@ -0,0 +1,54 @@
+# 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.