Module wsl 

Managing a named WSL2 distribution as a first-class host: discovery, invocation, preflight, artifact install, the Windows lifecycle task, and the non-secret provider record.

What this module is, and what it deliberately is not

It is the platform half of the managed WSL host feature — the part that knows about wsl.exe, schtasks.exe, ext4 renames and UTF-16 console output. The orchestration above it (the wsl command surface, the credential broker, the device flow) lives in the CLI, because none of that is platform-specific.

02-target-architecture.md draws the line in one sentence: “No PowerShell script, registry mutation, .wslconfig rewrite or distribution installation is hidden behind this adapter.” Nothing here writes the registry, edits .wslconfig, installs or unregisters a distribution, or runs a shell. The complete list of programs this module can start is wsl.exe and schtasks.exe, and everything either of them is asked to do is an argument vector built in one place.

Module	What it owns
exec	Literal-argv invocation, bounded capture, deadline, cancellation, and the anonymous stdin pipe a credential crosses on
discovery	Decoding wsl.exe’s UTF-16/UTF-8 output, and reading --list --verbose into exact names
probe	Selecting a distribution and the five preflight questions
artifact	Exact-version release selection, SHA-256 verification, and the atomic install inside the distribution
task	The per-distribution Windows login task: render, register, query, detach
record	The non-secret provider record under the config directory

Every build has this module; only Windows has a host to run it on

02-target-architecture.md requires that on a non-Windows build wsl and --host wsl:… “fail with an actionable unsupported-platform error rather than disappearing from help”. A #[cfg(windows)] module would give the opposite: a command that exists on one platform and is a compile error to mention on the others.

So the model is compiled everywhere and only WslHost::on_this_host refuses, with WslError::UnsupportedPlatform. That has a second benefit that is worth as much: the parsing, the rendering, the record and the argument vectors are all exercised by cargo test on the Linux and macOS CI legs, rather than by the one leg that has WSL.

Where the credential is, and is not

03-security-and-lifecycle.md item 3 requires the stored credential document to cross the boundary only through an anonymous stdin pipe, and to be absent from argv, environment, provider records, logs, errors, status JSON, temporary files and scheduled-task XML. This module’s part of that:

• exec::PipedInput is the only way to give a child bytes, its Debug prints a length, and exec::CommandRequest has no environment API at all;
• exec::CommandRequest::refuse_payload_in_argv refuses the launch when the payload is also in the command line;
• task::LifecycleTask has no field that could hold one, and the only temporary file this module writes is that task’s document;
• record::WslProviderRecord has five non-secret fields and deny_unknown_fields.

crates/platform/tests/no_wsl_credential_outside_child_stdin.rs is the test that puts a canary through the whole path and looks everywhere else.

Modules

artifact

Choosing the one published Linux archive that matches, proving it is the one that was published, and putting the binary inside it at /usr/local/bin/runner-manager without a moment in which that path holds half a file.

discovery

Reading wsl.exe --list --verbose, and deciding that a name an operator typed is exactly one distribution that is really installed.

exec

Running a program with a literal argument vector, bounded output, a deadline, a cancellation flag, and an optional anonymous stdin pipe.

probe

Selecting a distribution and asking it the five questions that decide whether the product may manage it.

record

The one non-secret file this feature writes on the Windows side: a record per managed WSL distribution.

task

The one Windows login task that keeps a managed WSL distribution alive, and the four operations on it: render, register, query, remove.

Structs

WslHost

The WSL adapter bound to a command runner.

Enums

WslError

Anything that can go wrong managing a WSL distribution.

Functions

require_windows

Whether this build can manage a WSL distribution at all.