Skip to content

fix(run): confine dispatch guidance to the preparing host - #274

Merged
slowdini merged 1 commit into
devfrom
fix/windows-wsl-hybrid-guidance
Aug 15, 2026
Merged

fix(run): confine dispatch guidance to the preparing host#274
slowdini merged 1 commit into
devfrom
fix/windows-wsl-hybrid-guidance

Conversation

@slowdini

Copy link
Copy Markdown
Owner

What this changes

The generated dispatch and judge recipes carry the absolute paths of the host that prepared the workspace, so the shell that eventually runs them has to resolve those same paths. Git Bash shares the Windows filesystem and does. WSL resolves its own namespace, where a C:\... path names nothing — and nothing in the tree translates between the two (no wslpath, no /mnt/c handling anywhere).

Guidance that listed Git Bash and WSL side by side as equivalent Windows options pointed at a split that fails quietly. src/cli/run/orchestrate/shell.rs went further and documented it as supported — "Preparing on Windows and dispatching from WSL is a legitimate split" — while its preflight warning told operators to "prepare here and dispatch them from a POSIX shell."

User-facing change

POSIX_TOOLING_REQUIREMENT (src/core/runtime.rs) states the constraint once and names WSL as where eval-magic runs rather than somewhere to dispatch into. Its four Markdown consumers — RUNBOOK.md, dispatch-manifest.md, and both shell-discovery errors — pick that up automatically. AFTER_HELP mirrors it by hand for clap, per the convention in AGENTS.md.

Preflight warning, before and after:

⚠ no POSIX shell found. ... The workspace and recipes below are still
  correct — prepare here and dispatch them from a POSIX shell.
⚠ no POSIX shell found. ... The workspace and recipes below are still
  correct — dispatch them from a POSIX shell on this host.

Documentation

docs/developer_overview.md gains a Platform support section recording the tiers: Linux and macOS supported, Windows through Git Bash deprecated with removal gated on #256, and the Windows-prepare/WSL-dispatch split unsupported with the reason it cannot work. AGENTS.md points at it; the README carries the user-facing deprecation note.

No schema or CLI-surface changes.

Verification

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-targets      # 1146 passed, 0 failed

Two new tests, both written first and confirmed failing against the old wording:

  • the_declared_requirement_places_wsl_around_eval_magic_not_downstream_of_it (src/core/runtime.rs)
  • a_missing_shell_confines_dispatch_to_the_host_that_prepared_the_workspace (src/cli/run/orchestrate/shell.rs)

Ten golden fixtures re-blessed with GOLDEN_BLESS=1 cargo test golden_; the diff is one line per fixture — the requirement sentence and nothing else. cargo run -- --help checked for the rendered REQUIREMENTS block.

Context

This is the pre-refactor half of a Windows support decision: correct what is claimed now, and defer the code, CI, and distribution removal until after #256 replaces the POSIX recipe surface with a runner-driven eval-magic dispatch.

🤖 Generated with Claude Code

The generated recipes carry the absolute paths of the host that prepared the
workspace, so the shell that dispatches them has to resolve those same paths.
Git Bash shares the Windows filesystem and does; WSL resolves its own namespace,
where a `C:\...` path names nothing, and nothing in the tree translates between
the two. Guidance that listed Git Bash and WSL side by side — and a preflight
warning inviting an operator to "prepare here and dispatch from a POSIX shell" —
pointed at a split that fails quietly.

POSIX_TOOLING_REQUIREMENT now states the constraint once and names WSL as where
eval-magic runs rather than somewhere to dispatch into; its four Markdown
consumers pick that up, and AFTER_HELP mirrors it by hand for clap.

Also records the support tiers under "Platform support" in the developer
overview: Linux and macOS supported, Windows through Git Bash deprecated with
removal gated on #256, and the Windows-prepare/WSL-dispatch split unsupported.

Before:
  ⚠ no POSIX shell found. ... The workspace and recipes below are still
    correct — prepare here and dispatch them from a POSIX shell.
After:
  ⚠ no POSIX shell found. ... The workspace and recipes below are still
    correct — dispatch them from a POSIX shell on this host.

Verification: cargo fmt --check, cargo clippy --all-targets --all-features
-- -D warnings, cargo test --all-targets (1146 passed, 0 failed). Golden
fixtures re-blessed with GOLDEN_BLESS=1; the diff is one line per fixture.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@slowdini
slowdini merged commit 157878f into dev Aug 15, 2026
8 checks passed
@slowdini
slowdini deleted the fix/windows-wsl-hybrid-guidance branch August 15, 2026 22:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant