Summary

• Problem: On Windows, spawn('bash', ...) resolves to C:\Windows\System32\bash.exe (the WSL launcher) via CreateProcess's System32-first lookup. WSL bash has broken ${VAR} expansion in -c mode and uses /mnt/c/ paths — both break workflow bash nodes and loop until_bash deterministically.
• Why it matters: Issue bug(workflows): bash nodes silently fail on Windows when bash resolves to WSL launcher (System32\bash.exe) — $VAR expansion broken in -c mode #1326. Affects every Windows user who runs Archon workflows with bash nodes. Symptoms range from silent variable-substitution failures to loop nodes silently re-iterating forever (because bashErr.code === 'ENOENT' was logged but bashComplete = false kept the loop alive until iteration limit).
• What changed: Added resolveBashPath() in @archon/git that defaults to Git Bash on Windows, supports ARCHON_BASH_PATH override (eagerly validated via existsSync), and is wired into both bash node + loop until_bash execution paths. Error handling switches from err.message?.includes('ENOENT') to err.code === 'ENOENT' | 'EACCES' | 'ENOTDIR' (consistent, type-safe). Loop until_bash now throws on bash-binary failures instead of silently re-iterating.
• What did NOT change (scope boundary): Zero changes to homebrew/archon.rb, package.json versions, CHANGELOG outside the single [Unreleased] → Fixed entry, marketplace workflows, provider validation, mutates_checkout, executor-shared.ts, loader.ts, or any other unrelated subsystems. This is the slim version of fix(workflows): resolve bash via absolute path on Windows (#1326) #1470 per @Wirasm's 2026-05-27 request.

UX Journey

Before

Windows User → archon workflow run → bash node → spawn('bash', ...) →
                                                   ↓ (CreateProcess)
                                                  C:\Windows\System32\bash.exe (WSL)
                                                   ↓
                                                  ${VAR} expansion BROKEN
                                                  /c/path → /mnt/c/path mismatch
                                                   ↓
                                                  silent failure OR loop forever

After

Windows User → archon workflow run → bash node → [resolveBashPath()] →
                                                   ↓
                                                  C:\Program Files\Git\bin\bash.exe
                                                  (or *ARCHON_BASH_PATH* if set)
                                                   ↓
                                                  Git Bash with working ${VAR} + POSIX paths
                                                   ↓
                                                  works as documented

Architecture Diagram

Before

@archon/git/exec.ts ──── execFileAsync('bash', ...) ──→ dag-executor.ts (bash + loop_until_bash)

After

@archon/git/exec.ts ─── [+] resolveBashPath() ──→ dag-executor.ts (bash + loop_until_bash)
                    ─── execFileAsync(...)

Connection inventory:

Label Snapshot

• Risk: risk: low (additive resolver, fall-through default is 'bash' on non-Windows = current behavior)
• Size: size: S (6 files, +116 / -18)
• Scope: workflows, git, docs
• Module: workflows:dag-executor, git:exec

Change Metadata

• Change type: bug
• Primary scope: workflows

Linked Issue

• Closes bug(workflows): bash nodes silently fail on Windows when bash resolves to WSL launcher (System32\bash.exe) — $VAR expansion broken in -c mode #1326
• Supersedes fix(workflows): resolve bash via absolute path on Windows (#1326) #1470 (per @Wirasm's 2026-05-27 close-comment requesting unrelated changes be stripped)

Validation Evidence (required)

# Test suite — full dag-executor.test.ts:
$ bun test packages/workflows/src/dag-executor.test.ts
 249 pass
 0 fail
 467 expect() calls
Ran 249 tests across 1 file. [2.58s]

# New resolveBashPath tests (4 cases):
$ bun test packages/workflows/src/dag-executor.test.ts --test-name-pattern "resolveBashPath"
 4 pass
 245 filtered out
 0 fail
 5 expect() calls

Wirasm 2026-04-29 review fixes — all addressed

• ✅ ARCHON_BASH_PATH documented in configuration.md
• ✅ err.code === 'ENOENT' (no longer err.message?.includes)
• ✅ ENOTDIR added to error condition (catches directory override path)
• ✅ loopBashPath reused in error message (not re-resolved via fresh call)
• ✅ coleam00/Archon#1326 issue refs removed from exec.ts docstring + test comments
• ✅ resolveBashPath docstring condensed (4 detail layers → 2)
• ✅ EACCES/ENOENT loop test coverage via resolveBashPath unit tests + Wirasm-spec'd throw-on-failure
• ✅ CHANGELOG [Unreleased] → Fixed entry added
• ✅ CodeRabbit nitpick: loop_node.until_bash_exec_error → loop.until_bash_failed ({domain}.{action}_{state} convention)

Smoke notes

This PR has been smoked on a Windows machine where the WSL-launcher bug is reproducible. The resolveBashPath() default of C:\Program Files\Git\bin\bash.exe is verified to correctly invoke Git Bash with working ${VAR} expansion and /c/ POSIX paths.

🤖 Slim rework of #1470 done by Claude Code (atlas-architect/Archon) per maintainer 2026-05-27 request.

Summary by CodeRabbit

• Bug Fixes

  • Fixed bash node and until_bash loop execution on Windows, preventing silent hangs.
  • Windows now defaults to Git Bash instead of WSL launcher for bash operations.
  • Added ability to override bash executable path via environment variable configuration.
  • Enhanced error messages when bash binary is missing or unreachable.

• Documentation

  • Added reference documentation for bash executable path configuration variable.