pikasTech-unidesk/.agents/skills/unidesk-gc/SKILL.md

name, description

name

description

unidesk-gc

UniDesk disk GC and host pressure relief workflow. Use when Codex needs to diagnose or reduce UniDesk host/root filesystem usage, run `bun scripts/cli.ts gc ...`, handle `/tmp/unidesk-cli-output` growth, clean merged UniDesk worktrees, prune controlled BuildKit/tool caches, tune journald caps, investigate Web observe/Chrome growth, or decide safe-stop boundaries for local host or `gc remote` operations. Trigger on gc, disk cleanup, disk full, root filesystem high water, host disk pressure, worktree cleanup, BuildKit cache cleanup, Web observe artifact growth, Chrome memory pressure, or UniDesk GC retention tasks.

UniDesk GC

Use this skill for UniDesk disk pressure work. Prefer the controlled UniDesk CLI and stop at protected boundaries instead of expanding into ad hoc rm -rf, Docker prune, database cleanup, raw Kubernetes deletion, or runtime state deletion.

Long-term policy lives in docs/reference/gc.md. Read that reference before remote GC, k3s/PVC attribution, JD01 Web observe/Chrome growth, G14 registry retention, CI workspace retention, or any safe-stop decision.

Local Host Workflow

Start with read-only attribution:

df -h /
df -BG /
bun scripts/cli.ts gc plan --target-use-percent 69 --limit 50

If the default plan has a shortfall, use explicit opt-in candidates:

bun scripts/cli.ts gc plan --target-use-percent 69 --limit 2000 \
  --include-tool-caches \
  --include-stale-tmp \
  --include-vscode-stale-servers \
  --include-vscode-stale-extensions \
  --include-vscode-cached-vsix \
  --include-baidu-staging \
  --include-state-artifacts \
  --include-state-stale-scratch \
  --include-codex-sessions \
  --include-merged-worktrees \
  --include-vpn-diagnostic-logs

Run the same candidate surface only after reviewing the plan:

bun scripts/cli.ts gc run --confirm --target-use-percent 69 --limit 2000 \
  --include-tool-caches \
  --include-stale-tmp \
  --include-vscode-stale-servers \
  --include-vscode-stale-extensions \
  --include-vscode-cached-vsix \
  --include-baidu-staging \
  --include-state-artifacts \
  --include-state-stale-scratch \
  --include-codex-sessions \
  --include-merged-worktrees \
  --include-vpn-diagnostic-logs

When worktree candidates are protected by merge/cherry timeout, rerun only the worktree surface with higher temporary budgets:

bun scripts/cli.ts gc plan --target-use-percent 69 --limit 2000 \
  --include-merged-worktrees \
  --worktree-scan-budget-ms 120000 \
  --worktree-cherry-check-timeout-ms 10000 \
  --no-file-logs --no-docker-logs --no-journal --no-build-cache --no-tmp --no-db-summary

Use the matching run --confirm only for candidates still shown by that plan. Dirty, recent, active, unmerged, and timeout-protected worktrees must remain protected.

Cache And Logs

Check Docker image cleanup separately:

bun scripts/cli.ts server cleanup plan --min-age-hours 24 --limit 80

If it returns zero stale image candidates, do not use docker image prune or docker system prune; protected images may be current or rollback/runtime truth.

Default BuildKit cleanup can estimate reclaim but actually release 0B if all cache is recent. Use --build-cache-all only as an explicit pressure-relief step:

bun scripts/cli.ts gc plan --target-use-percent 69 --build-cache-all --limit 50 \
  --no-file-logs --no-docker-logs --no-journal --no-tmp --no-db-summary
bun scripts/cli.ts gc run --confirm --target-use-percent 69 --build-cache-all --limit 50 \
  --no-file-logs --no-docker-logs --no-journal --no-tmp --no-db-summary

Journald can be capped through the same CLI:

bun scripts/cli.ts gc plan --target-use-percent 69 --journal-target-size 128M --limit 50 \
  --no-file-logs --no-docker-logs --no-build-cache --no-tmp --no-db-summary

Use the matching run --confirm if the plan is acceptable.

Temporary Dumps

/tmp/unidesk-cli-output is a CLI dump directory for oversized JSON/stdout. It can grow close to GiB scale during GC diagnosis because each truncated plan/run writes another dump. After extracting needed evidence and confirming no active writers, it is acceptable to remove the dump directory:

fuser -v /tmp/unidesk-cli-output 2>&1 || true
rm -rf -- /tmp/unidesk-cli-output

Prefer turning repeated dump cleanup into a controlled CLI retention policy instead of making manual removal the normal interface.

For other /tmp directories, check size, mtime, and active fds first. Avoid deleting same-day source/workspace scratch that may belong to parallel tasks unless its owner and recreatability are clear.

Remote Hosts

Use bun scripts/cli.ts gc remote <providerId> ... for provider hosts. Remote long work must be asynchronous and queried with status --job-id; do not keep a long SSH session open.

Read docs/reference/gc.md before these remote cases:

• G14 registry retention, CI workspace retention, k3s/PVC attribution, and safe-stop decisions.
• PK01 pikanode temp retention and Docker-provider safe boundaries.
• JD01 k3s/PVC attribution, Web observe artifact retention, Chrome/observer memory growth, and YAML-first source-of-truth checks.

For JD01, Chrome memory growth should first be treated as an observer lifecycle problem: sentinel/quick-verify terminal paths must stop their observer, and runner TTL/maxSamples/artifact caps must come from YAML. Do not solve it by raw killing Chrome or deleting web-observe directories; use controlled observe stop and GC plan candidates.

JD01 and other remote hosts may use rebuildable tool caches only through explicit opt-in:

bun scripts/cli.ts gc remote JD01 plan --target-use-percent 49 --include-tool-caches --limit 100
bun scripts/cli.ts gc remote JD01 run --confirm --target-use-percent 49 --include-tool-caches --limit 100

Review the plan first. The remote tool-cache candidate is limited to fixed allowlisted npm/npx/Bun cache directories; do not replace it with ad hoc rm -rf ~/.npm ~/.bun, and do not touch node_modules, auth/config, k3s/containerd, PVCs, or Docker volumes.

Protected Boundaries

Never use these as generic disk relief:

• docker system prune, docker image prune, Docker volume removal, or Compose volume deletion.
• PostgreSQL PGDATA or database trace cleanup without the dedicated gc db-trace flow, backup, and maintenance window.
• /var/lib/containerd, /var/lib/rancher/k3s, /var/lib/kubelet, PVC paths, registry blobs, runtime snapshots, or k3s/container runtime state.
• Codex auth/config/profile state. Codex session cleanup must use --include-codex-sessions; large active Codex SQLite log files require fuser checks and a dedicated retention decision.
• Active Web observe runs, live observer runners, live Chrome process trees, or web-observe state roots without manifest/heartbeat/pid/open-fd based stale classification.
• Dirty, active, unmerged, recent, or timeout-protected worktrees.
• backend-core rebuild/restart/replacement while solving disk pressure unless the user explicitly asks.

If summary.target.safeStop=true remains after all low-risk candidates, stop and report the remaining protected pressure sources and decision options. Do not bypass the CLI to hit a percentage target.

Verification

Close with concise evidence:

df -h /
df -BG /
docker system df
du -sh /root/unidesk/.worktree /root/unidesk/.state /tmp /var/log 2>/dev/null || true

For remote memory/Chrome pressure, also include free -h, Chrome/observer process summary, and web-observe state size. Summarize the starting and final df percentage, major successful cleanup classes, protected failures, and remaining high-risk pressure sources.