punkshell/goals/G-059-wsl-test-driving.md

G-059 WSL detection and suitability probing for driving unix-side tests from Windows

Status: achieved 2026-07-11 Scope: src/tests/ (capability probe helpers + constraint-gated cases in existing suites, e.g the unix sh-payload execution test in modules/punk/mix/testsuites/scriptwrap/multishell.test and a runtime.bash behaviour test), src/tests/AGENTS.md (enablement notes) Acceptance: see GOALS.md index entry (canonical).

Context

Development happens primarily on Windows, but punkshell carries genuinely unix-side behaviour that currently goes unexercised there: the MULTISHELL polyglot's sh/bash payload path (execution-tested only behind an isunix constraint - on Windows the shell layer deliberately re-dispatches to the win32 nextshell), runtime.bash's fetch/use/run logic (checksum parity added 2026-07-11, verified only by bash/zsh syntax check on Windows), and eventually suite runs against linux punkbin runtimes. WSL can close part of that gap without leaving the dev machine.

Approach

Native-filesystem execution is a design constraint, not an optimization

User experience (recorded 2026-07-11): operating on the same repo checkout through the WSL shared path (/mnt/c, DrvFs) is slow, and cross-boundary stat differences cause VCS recalculation - git re-hashes its index (mtime/inode/dev mismatch between Windows and WSL git; git status on /mnt/c is very slow generally) and fossil's mtime scan slows and can see phantom exec-bit changes from DrvFs permission mapping. Two VCS clients with incompatible stat caches must never share one working tree.

Therefore:

• Tier 1 (this goal's test cases): NO repo checkout inside WSL at all. The inputs are small (generated polyglot, runtime.bash, fixture runtime folders) - the harness stages per-test artifacts into a WSL-native tempdir (mktemp -d on ext4) with a single one-way copy-in over the shared path (bulk copy-in is fine; per-file stat traffic during runs is what hurts), executes natively, and collects results back the same way.
• Tier 2 (future full-suite mode, out of scope here beyond being designed-for): a SEPARATE native clone inside the distro (from gitea, or git fetch using the Windows repo as a file:// remote for committed state). Working-tree-uncommitted testing would be an explicit diff-overlay step, never shared-path operation.
• The Windows checkout's git and fossil state must be untouched by a WSL-gated run - acceptance makes this verifiable (git status / fossil changes identical before/after).

Suitability probing

The constraint (e.g wsl_linux_available) is capability-probed in the same spirit as G-058's statickitavailable - wsl.exe existence proves nothing (installs can be distro-less, WSL1-limited, or interop-broken). Probe: launch the default distro, answer uname/tool probes (bash, coreutils sha1 tooling), create a native tempdir and round-trip a staged file. Any probe failure -> skip cleanly (never fail the suite).

Consumers

• multishell.test scriptwrap_multishell_exec_unix_sh (currently isunix-gated) gains a WSL-driven sibling (or the constraint ORs in) running the generated polyglot under the distro's sh/bash from a native staging dir.
• runtime.bash behaviour test: active/use/run resolution against a fixture runtime folder inside WSL (network-dependent fetch cases separately env-gated - corp gitea reachability from WSL2 varies with network setup).

Notes

• Related: G-060 adopts the same push-based staging/collection contract for QEMU guests (which have no shared path to be tempted by); WSL is effectively the first, cheapest provider of that guest-driving contract.
• WSL itself is a Windows feature (no licensing entanglement); distro choice is the user's - the probe should not assume a specific distro, only capabilities.

Outcome (achieved 2026-07-11)

• src/tests/testsupport/wslprobe.tcl (::punktest::wsl): memoized capability probe (wsl.exe present -> default distro launches and unames as Linux -> tools present: bash/mktemp/wslpath + a sha1 tool -> native tempdir file round trip; any failure yields available=0 with a reason and consumers skip) plus staging helpers (staging_create/staging_copy_in/run_in/staging_cleanup - cleanup refuses paths it didn't create). Probe uses wsl -e <cmd> invocations only: management commands (wsl --status, -l) emit UTF-16 - discovered during implementation.
• Consumers: scriptwrap_multishell_exec_wsl_sh in multishell.test (the polyglot's sh payload produces its marker under the distro's bash from native staging - the direct isunix twin still skips on windows) and the new src/tests/shell/testsuites/binscripts/runtimebash_wsl.test (8 tests): runtime.bash's first-ever execution on real unix - multi-candidate run errors with candidates, use/list/run round trip with argument passing, PUNK_ACTIVE_RUNTIME override, unknown/unselectable use errors, stale-active guidance, single-candidate fallback, offline list -remote (crafted cached sha1sums.txt + PUNKBIN_URL forced-failure), and the checkout-untouched guard (git status --porcelain identical before/after the WSL-gated run - the native-staging design made verifiable).
• All green on Tcl 9.0.3 and 8.7 against Ubuntu-24.04/WSL2; suites skip cleanly when the probe fails (constraint gating; helper absence also degrades to skip).
• Enablement/limitations recorded in src/tests/AGENTS.md (incl the known limitation: a present-but-hanging WSL can stall the probe - erroring installs are handled).
• Bonus finding: the WSL list -remote test work triggered the polyglot's first real 512-byte label regression (payload growth pushed the template's :exit_multishell across a boundary); fixed via a documented spacer comment in runtime.bash - the G-05x guardrail suite caught it exactly as designed.