docs: add JD01 GC retention guidance

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

@@ -0,0 +1,146 @@
+---
+name: unidesk-gc
+description: 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:
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+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.
+
+## 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:
+
+```bash
+df -h /
+df -BG /
+docker system df
+du -sh /root/unidesk/.worktree /root/unidesk/.state /tmp /var/log 2>/dev/null || true
+```
+
+Summarize the starting and final `df` percentage, major successful cleanup classes, protected failures, and remaining high-risk pressure sources.

.agents/skills/unidesk-gc/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "UniDesk GC"
+  short_description: "Controlled disk GC for UniDesk hosts"
+  default_prompt: "Use $unidesk-gc to plan and run controlled disk cleanup for a UniDesk host."