Handoff: D: WSL data VHDX with XFS and VDO decision gate

Continuation target

Suggested target: D:\WSL-data\xfs-data.vhdx, 512 GiB logical capacity, dynamically expanding. The D: drive had approximately 1,279.8 GiB free when checked on 2026-08-13. The directory did not yet exist. Dynamic does not reserve 512 GiB immediately, but the next agent must still confirm available space before creating anything.

Current state and facts already verified

Research artifact: /home/miro/zettelkasten/Literature notes/2026-08-13 WSL VHDX filesystem support and compression options.md.

Procedure: create and mount the XFS baseline

1. Use an elevated Windows PowerShell. Do not use the current WSL shell to create the Windows VHDX. The agent may use the local Windows CUA wrapper if needed; this task must run on this machine, not Battlebox.
2. Create the directory only if it does not exist; refuse if the VHDX already exists.
3. Create a dynamic 512 GiB VHDX using DiskPart. DiskPart is used rather than assuming that the Hyper-V PowerShell module is installed.
4. Attach the VHDX to WSL as a bare disk. In WSL, identify the new device by size/model; never assume a fixed /dev/sdX name.
5. Create a GPT partition table and one full-size Linux partition, format it as XFS, mount it at /mnt/wsl-data, and validate a write/read test.
6. Record the UUID and add an /etc/fstab entry with nofail. Test a WSL restart and then detach/re-attach only as needed.

PowerShell: preflight and VHDX creation

$vhdDir = 'D:\WSL-data'
$vhd = Join-Path $vhdDir 'xfs-data.vhdx'
$sizeGiB = 512

Get-PSDrive D | Select-Object Name,
  @{N='FreeGiB';E={[math]::Round($_.Free / 1GB, 1)}}
if (Test-Path -LiteralPath $vhd) { throw "Refusing to overwrite existing $vhd" }
New-Item -ItemType Directory -Path $vhdDir -Force | Out-Null

$diskpart = @"
create vdisk file="$vhd" maximum=$($sizeGiB * 1024) type=expandable
select vdisk file="$vhd"
attach vdisk
detach vdisk
exit
"@
$diskpart | diskpart
if (-not (Test-Path -LiteralPath $vhd)) { throw "VHDX was not created: $vhd" }
Get-Item -LiteralPath $vhd | Select-Object FullName, Length, LastWriteTime

Do not initialize or format the disk in Windows: Windows does not create XFS. The VHDX must be detached from Windows before WSL owns it.

PowerShell then WSL: attach, identify, partition, XFS

# Elevated PowerShell
wsl --mount --vhd D:\WSL-data\xfs-data.vhdx --bare

# Inside the intended WSL distribution, as root/sudo.
lsblk -o NAME,SIZE,TYPE,FSTYPE,MODEL,MOUNTPOINTS
# Identify the new 512G disk from the output, then substitute its exact path below.
disk=/dev/sdX
sudo parted --script "$disk" mklabel gpt mkpart primary xfs 1MiB 100%
sudo partprobe "$disk"
lsblk -f "$disk"

# Re-check the partition name, then substitute it exactly. This destroys its contents.
part=/dev/sdX1
sudo mkfs.xfs -f "$part"
sudo mkdir -p /mnt/wsl-data
sudo mount -t xfs "$part" /mnt/wsl-data
sudo chown "$USER:$USER" /mnt/wsl-data
uuid=$(sudo blkid -s UUID -o value "$part")
printf 'UUID=%s /mnt/wsl-data xfs defaults,nofail 0 2\n' "$uuid" | sudo tee -a /etc/fstab

If parted, mkfs.xfs, or blkid are missing, install only the relevant packages for the current distro (parted and xfsprogs) after reporting the exact package action. Do not silently substitute ext4.

VDO decision gate

# Read-only proof required before any VDO work
uname -r
sudo dmsetup targets | grep -w vdo || true
zgrep -E 'CONFIG_(DM_VDO|XFS_FS)=' /proc/config.gz 2>/dev/null || true
grep -w xfs /proc/filesystems

• If no VDO target is shown, complete only the XFS baseline, report VDO as blocked, and ask Miro whether to authorize a custom WSL kernel.
• If Miro explicitly authorizes the custom-kernel route, plan it separately: build Microsoft’s WSL kernel with CONFIG_DM_VDO, build/install its matching modules VHD, configure global %UserProfile%\.wslconfig kernel= and kernelModules=, restart WSL, and re-run the proof command. This affects every WSL 2 distro and is not an incidental storage-step change.
• Only after proof and approval should the agent create LVM/VDO metadata. It must use a disposable VHDX first and measure CPU, physical VHDX growth, and workload time. Do not say it will make WSL faster by default.

Required verification and handoff report

findmnt /mnt/wsl-data
df -hT /mnt/wsl-data
sudo xfs_info /mnt/wsl-data
touch /mnt/wsl-data/.wsl-vhdx-smoke && stat /mnt/wsl-data/.wsl-vhdx-smoke
sudo mount -a

# From elevated PowerShell after the Linux-side checks
wsl --shutdown
wsl -d <target-distro> -- findmnt /mnt/wsl-data

The next agent’s final report must state: exact VHDX path; requested and actual VHDX file size; disk/partition/UUID; mountpoint; the output of findmnt and df -T; whether the restart persistence test passed; VDO status and exact evidence; all files changed (especially /etc/fstab and any .wslconfig); and any packages installed.

Risks, sources, and suggested skills

• Destructive target confusion: never run parted or mkfs.xfs until lsblk identifies the newly attached VHDX by its size and empty state.
• Windows lock: VHDX must not be attached/mounted by Windows while WSL uses it. Use wsl --unmount D:\WSL-data\xfs-data.vhdx only after unmounting it in Linux.
• VDO changes are global: a custom WSL kernel is a separate authorization and maintenance commitment.
• Performance claim: VDO can reduce physical writes but adds hashing/compression and metadata overhead; benchmark real workload inputs.

Primary sources: Microsoft: Mount a Linux disk in WSL 2 · Microsoft: import-in-place ext4 requirement · Microsoft WSL 6.18 kernel config · Linux kernel dm-vdo documentation · Microsoft: .wslconfig custom kernel settings.

Suggested skills: battlebox-ssh only if the agent needs the remote host (not for this task); otherwise Windows CUA for elevated PowerShell, and zettelkasten-vault only if it records results in the vault.