Local workspace disk hygiene

Use this runbook on the Windows development host. It separates online cleanup from maintenance that requires a Docker/WSL outage.

Canonical repository output paths

• Service publish output: <repo>/tmp/build/stella-publish/
• Mirror seed and local mirror E2E output: <repo>/tmp/build/mirror/
• Benchmark work, results, and caches: <repo>/tmp/bench/stella-vs-others/

Do not direct repository builds to C:\temp, %TEMP%, /mnt/c/temp, or /c/temp. These canonical trees are ignored by Git and can be aged out without touching source or durable QA evidence.

Safe online nightly cleanup

With Docker and WSL running, remove only objects that are unused and older than local midnight:

$cutoff = (Get-Date).Date.ToUniversalTime().ToString('o')
docker image prune -a -f --filter "until=$cutoff"
$elapsed = (Get-Date) - (Get-Date).Date
$age = '{0}h{1}m' -f [math]::Floor($elapsed.TotalHours), $elapsed.Minutes
docker builder prune -a -f --filter "until=$age"

Do not age-prune named PostgreSQL volumes, attached WSL VHDX files, tracked or mounted runtime plugin bundles, NuGet caches, or src/**/bin, src/**/obj, and node_modules.

The repo provides tools/scripts/online-disk-cleanup.ps1 for this online-only pass. Register it nightly at 02:00 from an elevated Windows PowerShell prompt:

$script = (Resolve-Path '.\tools\scripts\online-disk-cleanup.ps1').Path
$action = New-ScheduledTaskAction -Execute 'powershell.exe' -Argument "-NoProfile -ExecutionPolicy Bypass -File `"$script`""
$trigger = New-ScheduledTaskTrigger -Daily -At '02:00'
Register-ScheduledTask -TaskName 'Stella Ops online disk cleanup' -Action $action -Trigger $trigger -RunLevel Highest

Windows.old

Use the Windows cleanup UI so servicing metadata is removed correctly:

1. Open Settings > System > Storage > Temporary files.
2. Select Previous Windows installation(s).
3. Select Remove files and confirm.

Equivalent elevated command-line cleanup can be initiated with cleanmgr.exe, but the Settings path is preferred because it shows the exact reclaimable category before deletion.

Docker VHDX compaction maintenance window

Deleting Docker objects frees space inside docker_data.vhdx; it does not shrink the host file while Docker is running. Compaction therefore requires a planned outage:

1. Verify PostgreSQL and other writes are quiesced, then quit Docker Desktop.

2. Run wsl --shutdown and verify no WSL distribution remains running with wsl --list --running.

3. Mark the registered WSL distribution VHD sparse, then compact the Docker data VHDX from an elevated PowerShell prompt:

   wsl --manage docker-desktop --set-sparse true
   Optimize-VHD -Path "$env:LOCALAPPDATA\Docker\wsl\disk\docker_data.vhdx" -Mode Full
   

4. Start Docker Desktop and verify PostgreSQL plus the Stella Ops containers are healthy.

The host already enables sparseVhd=true for newly managed WSL VHDX files. The explicit wsl --manage ... --set-sparse true command converts the existing registered distribution VHD; Optimize-VHD compacts the Docker-managed data file after it is detached. Schedule this offline maintenance weekly or monthly, not as an unattended nightly task.

WSL swap

swap.vhdx is WSL’s configured swap backing store, not disposable temp output. Check current usage with wsl -d docker-desktop -- free -h. Change the swap= value in %USERPROFILE%\.wslconfig only during a maintenance window, then apply it with wsl --shutdown. Do not delete an attached swap VHDX.