feat: report remote gc target shortfall

docs/reference/gc.md

@@ -10,7 +10,7 @@ UniDesk 的磁盘治理入口是 `bun scripts/cli.ts gc ...`。该入口用于
 - `gc db-trace plan|run --confirm --before-date YYYY-MM-DD --vacuum-full`：显式 trace 遥测留存入口；涉及数据库重写时按维护窗口处理。
 - `gc remote <providerId> plan|run --confirm|status --job-id <id>`：通过 UniDesk SSH 透传在 provider host 上执行受控 GC。远端长任务必须使用异步 job 和 `status` 短查询，不应让单次 SSH 等待完整 registry GC 或其他长清理。
 
-所有成功和失败输出都必须是 JSON。`plan` 必须标记 `dryRun=true`、`mutation=false`；`run` 必须要求 `--confirm` 并报告 `diskBefore`、`diskAfter`、`summary`、`results` 和 `protected`。
+所有成功和失败输出都必须是 JSON。`plan` 必须标记 `dryRun=true`、`mutation=false`；`run` 必须要求 `--confirm` 并报告 `diskBefore`、`diskAfter`、`summary`、`results` 和 `protected`。远端 GC 可用 `--target-use-percent N` 显式表达目标根盘水位；`summary.target` 必须给出目标所需释放量、候选估算、预计水位、缺口和 `safeStop` 决策，避免靠人工心算判断是否应该继续扩大清理范围。
 
 ## Protected Data
 
@@ -74,14 +74,14 @@ Registry 执行必须以远端异步 job 完成，并具备以下维护保护：
 
 ## Safe Stop Line
 
-磁盘目标可以设为 `<70%`，但安全边界优先级高于目标百分比。当执行以下命令后仍高于目标时，应停止自动清理并提交决策表：
+磁盘目标可以设为 `<70%` 或维护窗口临时目标如 `<50%`，但安全边界优先级高于目标百分比。目标必须直接传给 CLI，使输出带有可机读缺口：
 
 ```bash
-bun scripts/cli.ts gc remote G14 plan --limit 20
-bun scripts/cli.ts gc remote G14 plan --include-hwlab-registry --limit 20
+bun scripts/cli.ts gc remote G14 plan --target-use-percent 50 --limit 20
+bun scripts/cli.ts gc remote G14 plan --target-use-percent 50 --include-hwlab-registry --limit 20
 ```
 
-若两个 plan 都没有有意义候选，剩余空间通常位于 registry 保留集、k3s runtime、containerd image cache 或 PVC 数据中。继续下降需要显式选择以下更高风险方案之一：
+当 `summary.target.safeStop=true`、`state` 为 `shortfall` 或 `safe-stop-no-meaningful-candidates` 时，应停止自动清理并提交决策表。若默认 plan 和 registry plan 都无法覆盖目标缺口，剩余空间通常位于 registry 保留集、k3s runtime、containerd image cache 或 PVC 数据中。继续下降需要显式选择以下更高风险方案之一：
 
 | 方案 | 风险 | 需要的前置决策 |
 |---|---|---|
@@ -100,16 +100,16 @@ G14 当前只有一个本机 k3s cluster；空间归因时不要把 `hwlab-dev`
 | k3s namespace/PVC | `kubectl get pv,pvc,pod -A -o json` 结合 local-path PV host path | 把可归属数据映射到 namespace/workload |
 | Registry repo/tag/revision | registry v2 repository/tag link、manifest revision 与 blob manifest 解析 | 判断镜像历史 tag、cache revision 与共享 layer 的贡献 |
 
-当前 G14 高水位的长期基线分布如下，后续诊断出现同类量级时优先按同一顺序处理：
+G14 高水位的长期基线分布如下，后续诊断出现同类量级时优先按同一顺序处理。registry retention 后，空间压力可能从 `/var/lib/hwlab/registry` 转移到 k3s containerd snapshot/content、local-path PVC 和 host containerd；这些都属于受保护运行面，不能为了达到百分比目标直接删除目录。
 
 | 类别 | 路径 | 典型量级 | 归因说明 |
 |---|---|---:|---|
-| HWLAB local registry | `/var/lib/hwlab/registry` | 约 60GiB | 最大头；按 repo/tag retention 管理 |
-| k3s runtime | `/var/lib/rancher/k3s` | 约 24GiB | embedded containerd、local-path PVC 和 k3s server/db |
-| k3s containerd snapshots | `/var/lib/rancher/k3s/agent/containerd/.../snapshots` | 约 14GiB | workload image layer/snapshot cache，共享占用，不能直接按单 pod 删除 |
-| k3s containerd blobs | `/var/lib/rancher/k3s/agent/containerd/.../blobs` | 约 6GiB | k3s image content store，共享占用 |
-| k3s local-path PVC | `/var/lib/rancher/k3s/storage` | 约 3GiB | 可按 namespace/PVC 归因 |
-| host containerd | `/var/lib/containerd` | 约 9GiB | k3s 外的 host/containerd cache，默认不由 remote GC prune |
+| HWLAB local registry | `/var/lib/hwlab/registry` | 高水位约 60GiB；retention 后约十几 GiB | 最大头；按 repo/tag/revision retention 管理，不能直接删 blob |
+| k3s runtime | `/var/lib/rancher/k3s` | 约 45-55GiB | embedded containerd、local-path PVC 和 k3s server/db |
+| k3s containerd snapshots | `/var/lib/rancher/k3s/agent/containerd/.../snapshots` | 约 30-40GiB | workload image layer/snapshot cache，共享占用，不能直接按单 pod 删除 |
+| k3s containerd blobs | `/var/lib/rancher/k3s/agent/containerd/.../blobs` | 约 8-12GiB | k3s image content store，共享占用 |
+| k3s local-path PVC | `/var/lib/rancher/k3s/storage` | 约 8-10GiB | 可按 namespace/PVC 归因，只能通过运行面 retention 入口清理 |
+| host containerd | `/var/lib/containerd` | 约 9-12GiB | k3s 外的 host/containerd cache，默认不由 remote GC prune |
 | root workspaces/cache | `/root` | 约 2GiB | HWLAB/v0.2 worktree、npm/bun/cache 等 |
 | logs | `/var/log` | 约 1GiB | journald 约占一半，pod logs 很小 |