Cleanup — local machine only

The reason this exists is not docker system prune — that is one command. It is that the popular cleanup commands delete the wrong things: docker system prune -a --volumes takes the local dev database with it, and kill $(lsof -ti:8777) kills a LaunchAgent that restarts 15 seconds later, so the port looks cleaned and is not.

Remote resources are out of scope: SkyPilot clusters, k8s pods and anything that costs money belong to the cluster-job workflow (e.g. a sky-job skill), which has its own gates. Never sky down --all, never kubectl delete from here.

Always: report first

bash scripts/report.sh

Prints listening ports with the process holding each one, processes still attached to a terminal (the reliable tell for "a shell left this behind" — daemons and app helpers have no controlling terminal), tmux sessions, and the Docker table with containers, volumes and reclaimable sizes. It deletes nothing.

Then present a table: what · how much it frees · tier · the exact command, and wait. Even the safe tier is proposed, not executed, unless the user already said go.

Tiers

Safe — rebuildable from a command, no state inside

Ask — cheap to delete, expensive or impossible to get back

• Running containers. Something may be mid-write. Name it, say what it belongs to, ask.
• Images that are slow to rebuild: GPU/ML bases, anything multi-GB or built from a private registry. Freeing 700 MB to spend 10 minutes rebuilding is a bad trade — say the trade out loud.
• Terminal processes: a dev server (npm run dev, uvicorn --reload), an SSH tunnel, a training run. Show PID, elapsed time and the full command; the user decides. SIGTERM first (kill <pid>), SIGKILL (kill -9) only after it refuses.
• tmux sessions: tmux attach -t <name> and look before tmux kill-session. A session holding a half-finished run is not junk.

Never automatically

• Docker volumes. They are the only place local state lives — dev databases, MinIO buckets, Redis dumps. LINKS=0 means no container references it right now, not that it is junk: a compose down leaves its data volume at 0 links and compose up expects it back. Never docker system prune --volumes, never docker volume prune. List them with owner and size; delete only a volume the user names, one at a time.
• Anything this session did not start, unless the user says whose it is. Another terminal, another person's tunnel, an editor's language server.
• Processes under launchd. A port that keeps reopening after you kill its PID is usually held by a LaunchAgent with KeepAlive — find its label (launchctl list | grep -i <name>) and launchctl bootout gui/$(id -u)/<label>; killing the bare PID achieves nothing. Same shape for anything else in ~/Library/LaunchAgents.
• /tmp artifacts that were never persisted. Check the project's durable-storage rule first — an expensive result living only there gets copied out before anything is removed.

Port already in use

lsof -nP -iTCP:<port> -sTCP:LISTEN       # who holds it — read the command, do not kill blind

Then decide by owner: your own dev server → stop it in its terminal; a container → docker stop; a LaunchAgent → launchctl bootout; something you do not recognise → report it, do not kill it. Never kill -9 $(lsof -ti:<port>) as a reflex: it skips the question of what that process was doing, and on a supervised process it is a no-op with extra steps.

Output

The table, the reclaimable total, then the commands actually run and what they freed. Report the real numbers (docker system df before and after), not "cleaned up".