orca/docs/reference/wsl-runner-verification.md

Verifying the W1–W3 Windows/WSL work

Unit and real-binary tests cover Windows and WSL behavior.

1. Unit — runs everywhere, every PR

Suite	Pins
src/main/wsl/wsl-runner.test.ts	Separator, lane selection, fencing, WSLENV, guest cwd, script interpreter, budget split, refusal on unresolved PATH
src/main/wsl/wsl-guest-environment.test.ts	Burst collapse, per-distro isolation, malformed-payload rejection, transient vs permanent, retry windows, joiner budget
src/main/wsl/wsl-w1-w3-contract.test.ts	The W1→W3 chain end to end: absolute wsl.exe, argv array, bounded call, no --, script byte-identical, WSLENV, no shell on probe, login PATH still applied
src/shared/source-scan/source-tree-scan.test.ts	The guard helpers. A guard that under-reports is worse than none

2. Real-binary — the assertions nothing else can make

Windows CI (package (windows) job in pr.yml) rebuilds node-pty from patched source and runs the win32 suites against a real ConPTY: a real detached grandchild, a real job kill, and the inverse — a clean exit must leave backgrounded work alone.

Real WSL distro — not in CI; WSL isn't available on hosted runners.

ORCA_REAL_WSL_RUNNER_TEST=1 ORCA_WSL_TEST_DISTRO=Ubuntu-24.04 \
  pnpm vitest run src/main/wsl/wsl-runner.wsl.test.ts

It appends sleep 60 to the distro's ~/.profile and asserts the probe lane still answers inside its budget — #14288 reproduced, not simulated — then restores the profile. Also covers banner stripping, a script carrying quotes and $ arriving byte-identical, WSLENV crossing, and guest cwd.

Run this before shipping a change to src/main/wsl/. It is the only evidence that the probe lane does what the workstream claims, and it has already gone stale once against a runner change while passing in CI, because CI skips it.