Disk Pressure Proactive

Disk Pressure Proactive

In a constrained-disk environment, installs fail mid-flight and leave broken state. Pruning before the failure is cheaper than recovering after. And the prune runs in parallel with foreground work — disk-headroom work doesn't block feature work.

The trigger

Check free space at session start (see session-orient) and before any heavy install/build:

Get-PSDrive C | Select-Object Used,Free

If free space is under ~2-3 GB, or a heavy install/build is incoming and space is under ~5 GB, prune proactively. Don't wait for the ENOSPC failure.

The prune cascade (priority order)

Hit the cheap wins first, measure before deleting, bound the recursion:

1. Recycle Bin — Clear-RecycleBin -Force -ErrorAction SilentlyContinue. Always safe; often a few hundred MB.
2. Build output dirs — bounded recursion, measure, delete:

   $dirs = Get-ChildItem apps -Recurse -Directory -Filter ".next" -Depth 3 -ErrorAction SilentlyContinue
   $dirs | ForEach-Object { "{0:N0} MB {1}" -f ((Get-ChildItem $_.FullName -Recurse -File -EA SilentlyContinue | Measure-Object Length -Sum).Sum / 1MB), $_.FullName }
   # then delete the confirmed ones
   

   -Depth 3 bounds the scan so it doesn't cost more than the reclaim. Targets: .next/, dist/, build/, .output/, .turbo/, .vercel/.
3. Package store (unreferenced only) — pnpm store prune, uv cache clean. Safe — removes only unreferenced packages.
4. Temp — Remove-Item $env:TEMP\* -Recurse -Force -EA SilentlyContinue (selective; don't nuke files in use).

State the safety property before each prune

A prune sounds destructive. Name its safety property so the user trusts it without a confirm round-trip:

"Pruning the pnpm store (safe, removes only unreferenced packages)." "Clearing the Recycle Bin (no project files there)."

If a prune is not safe by default (e.g. deleting .next/ while a dev server is running), say so and either skip it or stop the server first (see shell-confirm-hygiene).

Run the prune in parallel with foreground work

The prune is disk-headroom work; it doesn't block feature work. While it runs, continue the foreground task ("pruning the uv cache for headroom while I build agentkit"). This is fill-the-wait applied to maintenance.

When NOT to prune

• Free space is healthy (> ~5 GB and no heavy install incoming). Pruning then is churn.
• The prune target is in active use (a dev server writing to .next/). Stop the server or skip that target.
• The reclaim is smaller than the scan cost. Measure first; skip targets under ~50 MB.

Anti-patterns

• Waiting for ENOSPC. Recovery from a half-installed package is harder than a prune.
• docker system prune -a as the first move. Nukes everything including images you wanted; targeted prunes first.
• Unbounded recursion. Scanning the whole tree costs more than the reclaim; use -Depth.
• Pruning without stating safety. Forces a confirm or a user "wait, is this safe?" — name the property.
• Blocking feature work on the prune. Run them in parallel.

Pair with

• session-orient — the disk check at session start is the trigger source.
• fill-the-wait — the prune runs alongside the foreground task.
• shell-confirm-hygiene — a non-safe prune gets a confirm; a safe one says so and runs.
• background-failure-triage — if a prune fails, it doesn't abort the foreground build.