Skip to content

fork fleet: Windows starter for a desk pool (D9) - #229

Draft
scuttletoby wants to merge 7 commits into
fork/desk-d8-setup-packfrom
fork/desk-d9-windows-starter
Draft

scuttletoby wants to merge 7 commits into
fork/desk-d8-setup-packfrom
fork/desk-d9-windows-starter

Conversation

@scuttletoby

@scuttletoby scuttletoby commented Nov 15, 2026 •

Copy link
Copy Markdown
Owner

Row D9 of the desktop pool plan: a Windows starter that turns a Windows PC into a desk pool desktop through one WSL2 distro, and runs the D8 setup pack inside it. Stacked on #225 (D8).

Why

A Windows desktop needs a few steps on the Windows side before the desk kit can run: a WSL2 distro, a memory cap so CI never takes the whole PC, NAT, and the distro settings the WSL2 walls require. Without a script these steps are easy to get wrong, and the walls then refuse the machine.

fork-kit/desk/windows/start-desk.ps1 runs in a normal (not administrator) Windows PowerShell 5.1 window. It:

  • prints the PC's facts and asks before it changes anything; before the question it checks the machine file and
    -FleetConfig exist and refuses a WSL 1 distro of that name (wsl -l -v); a distro of that name it did not make is
    named in the prompt, and its name must be typed to take it over (its wsl.conf is replaced)
  • makes the distro (-Distro, default fork-desk, Ubuntu 24.04, wsl --install ... --version 2, checked after)
  • sets the [wsl2] memory cap in .wslconfig (-MemoryGB; the default is three quarters of the RAM, at most the
    RAM less 6 GB, never under 4 GB; a value that leaves Windows under 2 GB is refused), plus swap, NAT and DNS
    tunnelling. It reads and writes the file as UTF-8 without a BOM (never ASCII), through a temp file and a rename,
    keeps a dated copy of the old file, and keys it does not set stay as they were.
  • writes the distro settings that the WSL2 walls check: systemd on, no Windows drives, programs or PATH, a resolv.conf of its own, and WSL's binfmt handler masked
  • runs one wsl --shutdown, and only when the live state differs: PID 1 is not systemd, Windows interop is still
    there, Windows drives are mounted, wsl.conf or .wslconfig is newer than the distro's boot, the memory cap or
    networking mode in force is not the one asked for, or a .wslconfig change still owes its shutdown (a mark in
    %LOCALAPPDATA%\fork-desk, written before the change and removed after the shutdown: WSL's uptime skips sleep)
  • installs the packages, copies in the machine file (and -FleetConfig), and runs the desk kit's bootstrap from one release commit
  • adds a logon task that keeps the distro running while the owner is logged in
  • ends with desk-install check and its own PASS/FAIL lines, and exits 1 when any fails

-Uninstall (no -Repo/-Sha needed) runs desk-install uninstall in the distro, stops and removes the logon task, and names the first .wslconfig.bak-*. It leaves the distro and .wslconfig in place.

What happens when this runs again, stops half-way, or meets existing, old or empty state?

Case What happens
Runs again Every step checks first and skips what is already right. .wslconfig and the distro settings are rewritten only on a change. WSL is shut down only when the live state is not yet right. D8's installer is idempotent. A test runs the in-distro part twice and the second run changes nothing.
Stops half-way wsl.conf and the copied-in files are written to X.new and then renamed, so a stop never leaves a half file. A stop between removing WSL's resolv.conf link and writing the new file leaves no resolv.conf, and the next run writes it. A new run redoes whatever is not yet right. A stop before wsl --shutdown is seen by the next run from the live state (interop still there, wsl.conf newer than the boot) or from the owed-restart mark, so that run shuts WSL down. A stop inside wsl --install leaves a mark, so the next run asks no takeover question; a broken registration fails its first start with a wsl --unregister hint.
Existing / old state A WSL 1 distro of that name is refused before anything changes. An existing .wslconfig keeps its other keys, and a dated copy is kept. An existing distro of the same name that the starter did not make is named and taken over only when its name is typed. A resolv.conf the distro already owns is kept (tested). A foreign desk install inside the distro is refused by D8.
Empty state An empty distro gets every setting (tested). -Uninstall runs desk-install uninstall only when the distro exists and the installer is there, and removing a logon task that is not there is not an error.

General vs project

General. No project, person or machine is named. The repo, release sha, machine file and fleet config are all arguments.

Upstream fit

Only the fork-only fork-kit/desk/ folder and the fork CI test list change. Nothing in upstream T3 changes.

Tests

fork-kit/desk/tests/windows.test.py (listed in .github/fork-ci-tests.txt) runs without Windows:

  • the in-distro part runs on a fake root, and the real WSL2 walls (fork-fleet-walls/wsl2) then pass. A second run changes nothing.

  • an empty distro

  • a resolv.conf of its own is kept

  • Windows PowerShell 5.1 can read the script: ASCII only, no tabs, brackets balanced. With pwsh on PATH, it is also parsed for real.

  • it asks before any change

  • text piped into the distro ends in a comment line, so the CR that PowerShell adds is harmless, and there are no quotes inside native arguments

  • the kit it runs is this repository's fork-kit/desk/bootstrap.sh

  • round 1: the .wslconfig merge keeps every other key and non-ASCII letter (run under pwsh when it is on PATH,
    skipped otherwise), a text check that no ASCII encoding is left, the live-state restart decision (its shell part
    run on fake /proc states), and a distro it did not make is named and must be typed

  • round 2: WSL 1 refused before the question and any restart and a new distro installed as WSL 2 (text order), the
    inputs checked before the question and -Sha case-sensitive, the restart and install marks (text order), a mounted
    Windows drive restarts (shell part on a fake /proc/mounts), and the wsl -l -v parser (under pwsh, skipped
    otherwise). The live tests put a wslinfo that answers nat first on PATH.

Local run (Python 3.12, no pwsh here, so the pwsh steps were skipped): python3 -I -B -W error::ResourceWarning fork-kit/desk/tests/windows.test.py: 16 tests, OK (2 skipped: the pwsh runs); install.test.py 33 OK after D8's round 2 merged in.

Not covered by a test: nothing fakes wsl.exe for the PowerShell flow itself (no pwsh here), so the order of the
takeover, the marks and the shutdown is checked as text only.

Red-checks

Each rule was broken in a copy, one at a time, and the named test failed (all 4 red):

  • systemd turned on in wsl.conf -> test_the_wsl2_walls_pass_after_it_and_a_second_run_changes_nothing
  • the Windows PATH not turned off -> the same test
  • a resolv.conf of the owner's own overwritten -> test_a_resolv_conf_of_its_own_is_kept
  • a second run that rewrites files -> test_the_wsl2_walls_pass_after_it_and_a_second_run_changes_nothing

Round 1: the new test file run against the round-0 starter: the three MUST tests fail (.wslconfig encoding, the
live-state restart decision, the takeover prompt), plus test_it_asks_before_it_changes_anything (it now looks for
the merge call). The pwsh merge test was skipped here and runs in CI.

Round 2: the new test file run against the round-1 starter: 4 fail (WSL 1 / --version 2, inputs before the
question, the marks and uninstall order, a mounted Windows drive).

🤖 Generated with Claude Code

start-desk.ps1 sets up a WSL2 distro for the desk kit from Windows
PowerShell 5.1: a memory and swap cap in .wslconfig, NAT, the WSL2
walls' settings inside the distro, the packages, the machine file, then
the desk kit's bootstrap from one release commit, a logon task that
keeps the distro running, and a PASS/FAIL check. -Uninstall removes it.
Every step skips what is already right; WSL restarts only on a change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@scuttletoby

Copy link
Copy Markdown
Owner Author

Review round 1 at 3a91ca2 (lens229, correctness and safety): SAFE WITH NITS. Fix round to follow.

Holds: asks before changing anything; Repo/Sha/Distro pattern-checked; .wslconfig merge keeps other keys; .new + rename for written files; HTTPS-only pinned download. 7/7 tests pass, but none run the .wslconfig merge or the shutdown decision.

  1. Proven: start-desk.ps1:110,124: on Windows PowerShell 5.1 Get-Content reads a BOM-less file as ANSI and Set-Content -Encoding ascii turns non-ASCII into ?. [wsl2] kernel=D:\kernels\José\bzImage becomes Jos??, and WSL no longer boots any distro. Read and write UTF-8 without BOM ([IO.File]::ReadAllLines/WriteAllLines with UTF8Encoding($false)), and add a test that runs the merge.
  2. :121,128,131: the restart decision uses only "changed during this run" or PID 1 not systemd. Stopped after wsl.conf is written but before wsl --shutdown, a re-run sees no change and PID 1 = systemd, so the old interop stays live, check FAILs and re-running never clears it; same for .wslconfig (the Windows check at :160 reads only the file). Decide on live state (WSLInterop present, networking mode not nat, /etc/wsl.conf newer than /proc/1).
  3. :83,96,128: an existing distro with the same name (e.g. Ubuntu) has its whole wsl.conf replaced (drops [user] default=, turns off /mnt/c and Windows PATH). Say so in the prompt, or refuse a distro the script did not create unless confirmed.
  4. :79: the 4 GB floor beats the README's "at least 6 GB left to Windows" on an 8 GB PC; -MemoryGB above RAM is accepted silently.
  5. Nits: exits 0 after catch/FAIL lines (:164-170); -Uninstall still needs -Repo/-Sha; the :160 check accepts the key in any section; Into breaks on UNC paths (:38).

scuttletoby and others added 4 commits November 15, 2026 20:45
- .wslconfig is read and written as UTF-8 without a BOM (never ASCII), by a
  temp file and a rename, with a dated backup; only [wsl2] keys are judged
- the restart decision reads the live state (PID 1, interop, wsl.conf newer
  than boot, memory, networking mode, .wslconfig newer than the boot)
- a distro the starter did not make is named and must be typed to take over
- MemoryGB above the PC's RAM less 2 GB is refused
- exit 1 on a failed check; -Uninstall needs no -Repo/-Sha; UNC paths work

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… flag (D9)

The text check that no ASCII encoding is left matched the comment that
explains the bug.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@scuttletoby

Copy link
Copy Markdown
Owner Author

Fix round 1 (commits 3e3e314, a884923; D8's round 1 merged in; head a884923). Tests: windows.test.py 11 OK (1 skipped: no pwsh here; CI has it), install.test.py 27 OK.

  1. .wslconfig as ASCII: fixed (3e3e314). Read and written as UTF-8 without a BOM ([IO.File] with UTF8Encoding($false)), through a temp file and a rename. Tests: test_wslconfig_merge_keeps_every_other_letter_and_key (runs the merge under pwsh; skipped when pwsh is absent, CI has it) and test_wslconfig_is_utf8_without_a_bom_never_ascii (no -Encoding ascii left).
  2. Restart decision on "changed this run": fixed (3e3e314). Decided on live state: PID 1 not systemd, WSLInterop present, /etc/wsl.conf newer than PID 1, the memory cap or networking mode in force, .wslconfig newer than the boot. Test: test_the_restart_decision_reads_the_live_state (the shell part on fake /proc states).
  3. Existing distro taken over silently: fixed (3e3e314). A distro the starter did not make is named in the prompt and its name must be typed. Test: test_a_distro_it_did_not_make_is_named_and_must_be_typed.
  4. -MemoryGB: fixed (3e3e314). A value leaving Windows under 2 GB is refused; README states the default (3/4 of RAM, at most RAM less 6 GB, never under 4 GB).
  5. Nits: fixed (3e3e314): exit 1 on a failed check; -Uninstall needs no -Repo/-Sha; only [wsl2] keys are judged; UNC paths work in Into.

Fails before the fix: the new test file against the round-0 starter: the three MUST tests above fail (1 failure, 2 errors), and the asks-first test. a884923 rewords a comment that the no-ASCII text check matched.

PR body updated. Still draft.

@scuttletoby

Copy link
Copy Markdown
Owner Author

Re-check lens 229 r1 at a884923: SAFE WITH NITS

Earlier findings: 1 ASCII .wslconfig FIXED (start-desk.ps1:94-122, UTF-8 no BOM via .new + rename; merge proven under real Windows PowerShell 5.1 on scratch files: non-ASCII kept, UTF-16 read, [WSL2] case, duplicate section, empty/comment-only file, one .bak- per change, second run again=False); 2 restart from live state FIXED (:77-89, :180-186); 3 silent distro takeover FIXED (marker :140, typed name :156-160; the test only checks text); 4 memory default FIXED (:131-132); 5 nits FIXED. The 4 new tests fail on round-0. windows.test.py 11 OK, 1 skipped (no pwsh).

New:

  1. WSL1 not ruled out (:166, :140): wsl --install has no --version 2 and a taken-over distro is not checked. With --set-default-version 1 or a typed WSL1 name, PID 1 is never systemd, so every run says restart, does wsl --shutdown (stops every distro and Docker Desktop) and check FAILs forever. Fix: --version 2 and refuse a WSL1 distro (wsl -l -v).
  2. -MachineFile/-FleetConfig checked late (:37 via :193): a path typo is found only after .wslconfig/wsl.conf changed, a shutdown and apt. Test-Path both before the prompt.
  3. Restart blind spots (:84, :181-183): a run that changes only swap/dnsTunneling/guiApplications and stops before :188, then sleep (VM uptime does not count sleep) -> no restart, :213 PASSes. automount has no live check. Sturdier: the vmmemWSL process start time.
  4. Stopped inside wsl --install or before the marker (:166, :73): next run asks the owner to type the name of its own distro; a broken registration fails at :169 with no wsl --unregister hint.
  5. -Uninstall (:145-146): Unregister-ScheduledTask likely leaves the running sleep infinity alive (unverified); Stop-ScheduledTask first. Closing message could name the .wslconfig.bak-*.
  6. Nits: the ownership check boots an existing distro before asking; on a <=6 GB PC the refusal names -MemoryGB 4, which the owner never passed; ValidatePattern is case-insensitive, so an uppercase -Sha passes (:12). No injection path found.
  7. Tests (windows.test.py:99-128): the Live part uses PATH=/usr/bin:/bin, so inside a mirrored-networking WSL the real wslinfo answers and :116 fails; nothing fakes wsl.exe for the PowerShell flow (takeover and shutdown order checked as text only).

scuttletoby and others added 2 commits November 15, 2026 22:38
… marks) (D9)

- wsl --install with --version 2; a WSL 1 distro (wsl -l -v) is refused
  before the question and before any restart, a new one is checked after
  the install.
- -MachineFile and -FleetConfig are tested before the first question; -Sha
  is matched case-sensitively; a PC too small for the default cap gets its
  own message.
- A Windows-side mark for an owed wsl --shutdown (written before .wslconfig
  changes, removed after the shutdown: uptime skips sleep) and for a distro
  this script is installing (no takeover question after a stop); a failed
  first start names wsl --unregister.
- A live check for Windows drives mounted under /mnt.
- -Uninstall stops the logon task before removing it and names the first
  .wslconfig.bak-*.
- The live tests put a wslinfo that answers nat first on PATH.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@scuttletoby

Copy link
Copy Markdown
Owner Author

Fix round 2 at e88ff71 (merge of D8 round 2, then one commit)

Lens 229 r1:

  1. WSL 1 not ruled out (MUST) -> fixed (e88ff71): wsl --install ... --version 2; the distro list is read with wsl -l -v (no distro is started) and a WSL 1 distro of that name is refused before the question, the marks and any wsl --shutdown, with wsl --set-version DISTRO 2 as the fix; a newly installed one is checked again before its first start. Tests: test_wsl1_is_refused_before_anything_changes_and_a_new_distro_is_wsl2 (text order), test_wsl_version_is_read_from_the_list (pwsh only, skipped here).
  2. -MachineFile/-FleetConfig checked late (MUST) -> fixed (e88ff71): Test-Path -PathType Leaf for both before the first question. Test: test_inputs_are_checked_before_the_question.
  3. Restart blind spots -> fixed (e88ff71): a Windows-side mark (%LOCALAPPDATA%\fork-desk\DISTRO.restart) written by Merge-WslConfig just before it writes .wslconfig and removed only after wsl --shutdown worked; while it is there the next run restarts (sleep does not matter). automount gets a live check (a drive under /mnt/X in /proc/mounts). I did not use the vmmemWSL start time: unverified whether a normal user may read it. Tests: test_a_stopped_run_keeps_its_marks, test_a_mounted_windows_drive_restarts.
  4. Stopped inside wsl --install -> fixed (e88ff71): a DISTRO.made mark before the install (no takeover question next time; removed once the in-distro mark is written); a failed first start names wsl --unregister DISTRO. Test: test_a_stopped_run_keeps_its_marks.
  5. -Uninstall -> fixed (e88ff71): Stop-ScheduledTask before Unregister-ScheduledTask; the closing message names the first .wslconfig.bak-*. Test: same.
  6. Nits: uppercase -Sha -> fixed (ValidateScript with -cmatch); -MemoryGB 4 message -> fixed (a PC too small for the default gets its own message); the ownership check starts an existing distro before asking -> documented (it runs only test -e, changes nothing in it, and now comes after the WSL 1 refusal and the input checks).
  7. Tests: mirrored wslinfo -> fixed (the live tests put a wslinfo that answers nat first on PATH); no fake wsl.exe for the PowerShell flow -> not fixed, documented in the PR body: there is no pwsh here, so the flow order stays a text check.

State question: runs again (marks absent after a full run; WSL 2 check reads only), stops half-way (owed-restart mark before the write, install mark before wsl --install), old state (WSL 1 distro refused; a foreign distro still needs its name typed), empty (no distros: wsl -l -v exits non-zero, read as "not there").

Red-check: the new test file against the round-1 starter: 4 fail (WSL 1, inputs first, marks and uninstall order, mounted drive). Head: windows.test.py 16 OK (2 skipped, no pwsh); install.test.py 33 OK.

This branch has not been deployed

No deployments
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