From 065b3fab2433dfd552c8808ff719128709585da6 Mon Sep 17 00:00:00 2001 From: Neil Date: Thu, 10 Sep 2026 17:42:54 -0700 Subject: [PATCH] docs(wsl): record the two traps the real-WSL run surfaced MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Both were found running the four `*.wsl.test.ts` suites against a live Ubuntu-24.04 distro — the first time any of them had executed. Lane ratchet header, next to the existing "does a registered suite EXECUTE" prose, because that is where someone will look: - nothing in `.github/` or `config/` sets any `ORCA_REAL_WSL_*` variable, so all four suites ran on no machine until exported by hand. They pass; that was not knowable from a green board. - these gates are compared with `===`, and `set VAR=1 && cmd` in cmd.exe stores `"1 "`. Trailing space, gate shut, and the suite reports "skipped" exactly as it does when the variable was never set. I filed that as a repo defect for several minutes before checking my own shell. A gate whose closed state is indistinguishable from its unset state is a gate nobody is running. - registered, triggered, and unable to fail are three separate ways to be invisible. The banner suite was all three at once. Runner suite header: it appends `sleep 60` to the shared distro user's `~/.profile` and backs up to a fixed path with `|| true`, whose teardown fallback is `rm -f "$HOME/.profile"`. The teardown works — it has no margin. An aborted run leaves every new login stalling a minute, or deletes the profile. The note says not to run it against a shared distro, and gives the check to repeat if you must: hash `$HOME/.profile` either side, never assume the restore. Comments only; no assertion or behaviour changes. Both lane ratchets stay green. --- .../win32-test-lane-registration.test.mjs | 17 +++++++++++++++-- src/main/wsl/wsl-runner.wsl.test.ts | 12 ++++++++++++ 2 files changed, 27 insertions(+), 2 deletions(-) diff --git a/config/scripts/win32-test-lane-registration.test.mjs b/config/scripts/win32-test-lane-registration.test.mjs index a1566c55c31..dcfd41fc941 100644 --- a/config/scripts/win32-test-lane-registration.test.mjs +++ b/config/scripts/win32-test-lane-registration.test.mjs @@ -59,9 +59,22 @@ import { classifyPrJobs } from './pr-code-change-scope.mjs' * - whether a registered suite EXECUTES. Registration is what is asserted. A * suite gated on win32 plus an env var stays skipped on the CI runner even * when registered -- see MANUAL_OPT_IN -- and a path registered but gated - * for another platform is not caught either. + * for another platform is not caught either. Measured 2026-09: nothing in + * `.github/` or `config/` sets any `ORCA_REAL_WSL_*` variable, so all four + * `*.wsl.test.ts` suites ran on no machine until someone exported them by + * hand. They pass; that was not knowable from the board. + * - that an env-var gate can be OPENED. These are compared with `===`, and + * `set VAR=1 && cmd` in cmd.exe stores `"1 "` -- trailing space, gate shut, + * suite reports "skipped" exactly as it does when you never set it. Prefer + * `set "VAR=1"`, and prefer a gate whose closed state is distinguishable + * from its unset state. A gate nobody can open is a gate nobody is running. * - whether the `package_windows` job is triggered for a given diff, or - * whether the registered test asserts anything worth running. + * whether the registered test asserts anything worth running. The second + * half is not hypothetical: `local-worktree-filesystem-wsl-banner.wsl.test.ts` + * was registered, opt-in, green -- and could not fail, because its contrast + * row used `endsWith` and the banner it contrasts against is conditional on + * distro user state. Registered, triggered and unable to fail are three + * separate ways to be invisible. * * Growth of the two grandfathered lists is capped by literals, but only review * stops someone raising a cap. The caps make that an explicit, visible edit. diff --git a/src/main/wsl/wsl-runner.wsl.test.ts b/src/main/wsl/wsl-runner.wsl.test.ts index c31ac669140..49faa19d813 100644 --- a/src/main/wsl/wsl-runner.wsl.test.ts +++ b/src/main/wsl/wsl-runner.wsl.test.ts @@ -11,6 +11,18 @@ import { resolveWslExecutablePath } from './wsl-executable-path' * Gated behind an env var and win32 because it mutates the distro's `~/.profile` * to reproduce #14288. Run with: * ORCA_REAL_WSL_RUNNER_TEST=1 pnpm vitest run src/main/wsl/wsl-runner.wsl.test.ts + * + * DO NOT run this against a distro you share. The teardown below works, but it + * has no margin, and all three of its failure modes land on a real user: + * - the appended `sleep 60` is in `$HOME/.profile` for the duration, so any + * login shell started in that window stalls a minute; + * - an aborted run (crash, timeout, Ctrl-C) never reaches `afterAll`, and the + * stall becomes permanent; + * - the backup is `cp … || true` to a FIXED path, so if it fails, or a stale + * copy from an earlier abort is present, teardown's `|| rm -f "$HOME/.profile"` + * deletes or reverts the user's profile. + * Verified by hashing `$HOME/.profile` either side of a run, which is the check + * to repeat if you must run it somewhere shared -- do not assume the restore. */ const DISTRO = process.env.ORCA_WSL_TEST_DISTRO ?? 'Ubuntu-24.04' const enabled = process.platform === 'win32' && process.env.ORCA_REAL_WSL_RUNNER_TEST === '1'