Draft: add manual VHDX compaction command for stopped WSL distros

[Guayamose]

Summary of the Pull Request

Related to #40243 and #4699.

This is an exploratory draft PR for a manual-only VHDX compaction path.

It adds a new manual command:

• wsl --manage <Distro> --compact

The command compacts the VHDX backing file for a stopped WSL 2 distro using the Windows Virtual Disk API.

This PR intentionally does not add automatic compaction yet.

PR Checklist

• Closes: Proposal for #4699: opt-in VHDX compaction after WSL shutdown #40243
• Communication: Discussed in Proposal for #4699: opt-in VHDX compaction after WSL shutdown #40243 and related to the long-standing disk reclaim request in WSL 2 should automatically release disk space back to the host OS #4699
• Tests: Added/updated and pass locally where applicable
• Localization: End-user facing strings added/updated
• Dev docs: Not added; this is currently an exploratory draft
• Documentation updated: Not yet; if this direction is accepted, docs can be added in the docs repo

Detailed Description of the Pull Request / Additional comments

Scope

Included:

• Adds an internal VHD compaction helper using OpenVirtualDisk and CompactVirtualDisk.
• Adds service/client plumbing for compacting a distro VHD.
• Adds wsl --manage <Distro> --compact.
• Rejects running distros / in-use VHDs.
• Preserves clear error behavior for ERROR_SHARING_VIOLATION.
• Adds tests for the manual command path.
• Updates help/localization strings.

Not included:

• No automatic compaction.
• No shutdown hook.
• No .wslconfig policy.
• No threshold/cooldown logic.
• No deferred retry/background task.
• No Docker-specific special casing.
• No special handling for Docker-managed VHDs.

Motivation

The broader issue in #4699 is that WSL 2 distro VHDX files can grow significantly and not release space back to the host automatically.

In #40243 I proposed a safer path around shutdown/offline compaction. Before attempting any automatic policy, this PR adds a smaller manual command first, so the Virtual Disk API integration and safety model can be reviewed independently.

Validation

Built successfully on Windows:

• cmake .
• cmake --build . --config Debug --target wsl wslservice wsltests -- /m
• cmake --build . --config Debug --target msixinstallerpackage -- /m

Tested:

• UnitTests::UnitTests::Compact passed.
• Manual compact against a stopped disposable Ubuntu WSL 2 distro succeeded.
• The distro booted successfully after compaction.
• Running distro case rejected as expected with Wsl/Service/WSL_E_DISTRO_NOT_STOPPED.
• wsl --manage Ubuntu --compact --resize 10GB did not compact and failed argument validation/help as expected.

Manual validation result:

• Command: wsl --manage Ubuntu --compact
• Output: La operación se completó correctamente.
• Exit code: 0
• VHD delta: -2,097,152 bytes
• Boot check command: wsl -d Ubuntu -- echo ok
• Boot check output: ok
• Boot check exit code: 0

Running distro validation:

• Command: wsl --manage Ubuntu --compact
• Error: Wsl/Service/WSL_E_DISTRO_NOT_STOPPED
• Exit code: -1
• VHD delta: 0

Notes

This is opened as a draft because the intended first step is design and maintainer feedback on the manual command surface and service/helper integration.

Open questions:

• Is wsl --manage <Distro> --compact the right CLI surface?
• Should this remain manual first before any automatic policy is considered?
• Should the helper report before/after size or keep output minimal?
• Should fixed/non-compactable VHDs get a more specific message?
• Are there preferred telemetry/logging patterns for this operation?

Future work, if this direction is acceptable:

• opt-in shutdown-triggered policy
• threshold/cooldown
• deferred retry/backoff
• richer telemetry/logging
• reclaim estimation

[Copilot]

Pull request overview

Adds a manual-only VHDX compaction path for stopped WSL 2 distributions, exposed via wsl --manage <Distro> --compact, with service plumbing and a Virtual Disk API helper.

Changes:

• Introduces --compact in wsl.exe --manage, routed through SvcComm to the service.
• Implements a service-side CompactDistribution path that rejects non-WSL2 and running/in-use distros and invokes CompactVirtualDisk.
• Updates help/localization text and adds a WSL2 unit test covering the compact flow.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
test/windows/UnitTests.cpp	Adds help text expectation and a new WSL2 test for --manage --compact.
src/windows/service/inc/wslservice.idl	Extends ILxssUserSession with CompactDistribution RPC method.
src/windows/service/exe/LxssUserSession.h	Declares CompactDistribution on the COM class + impl.
src/windows/service/exe/LxssUserSession.cpp	Implements CompactDistribution validation and VHD compaction call path.
src/windows/inc/wsl.h	Adds --compact manage option constant.
src/windows/common/WslCoreFilesystem.h	Declares CompactVhd helper.
src/windows/common/WslCoreFilesystem.cpp	Implements CompactVhd via OpenVirtualDisk + CompactVirtualDisk.
src/windows/common/WslClient.cpp	Adds CLI parsing/dispatch for --manage --compact.
src/windows/common/svccomm.hpp	Adds SvcComm::CompactDistribution declaration.
src/windows/common/svccomm.cpp	Wires SvcComm::CompactDistribution to ILxssUserSession.
localization/strings/en-US/Resources.resw	Adds --compact help text + locked token list update.
localization/strings/es-ES/Resources.resw	Adds Spanish --compact help text + locked token list update.

[Guayamose]

@microsoft-github-policy-service agree

[Copilot]

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 33 out of 33 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 33 out of 33 changed files in this pull request and generated no new comments.