feat: add gc disk relief command

scripts/src/help.ts

@@ -18,6 +18,7 @@ export function rootHelp(): unknown {
       { command: "server swap status|ensure [--path /swapfile] [--size 2GiB] [--dry-run]", description: "Inspect or idempotently create host swap for low-memory main-server operation." },
       { command: "server logs [--tail-bytes N]", description: "Return bounded tails from file logs and docker logs." },
       { command: "server cleanup plan [--min-age-hours N] [--limit N]", description: "Dry-run Docker image cleanup plan only: list active/protected images, stale candidates older than the default 24h threshold, risk, estimated reclaim, and manual review commands without deleting anything." },
+      { command: "gc plan|run|db-trace --confirm [--logs-keep-days N] [--include-browser-cache]", description: "One-time main-server disk relief for logs, journald, Docker build cache, allowlisted /tmp artifacts and explicit trace telemetry retention; plan is read-only and run requires --confirm." },
       { command: "server rebuild <backend-core|frontend|dev-frontend-proxy|provider-gateway|todo-note|code-queue-mgr|project-manager|baidu-netdisk|oa-event-flow>", description: "Maintenance-only local Compose rebuild for reviewed main-server services; frontend standard release must use CI artifact plus deploy apply dev/prod artifact consumers." },
       { command: "provider attach <providerId> [--master-server URL] [--up] [--force] | provider triage <providerId> [--observed-error text] [--observed-scope scope] [--microservice id ...] [--full|--raw]", description: "Generate the minimal external provider-gateway env/compose bundle or run the low-noise read-only provider health triage contract." },
       { command: "ssh <route> [operation args...]", description: "Open a Host SSH / WSL SSH maintenance session through the provider-gateway bridge; route syntax such as `G14:k3s` or `D601:win/c/test` only locates distributed targets." },
@@ -260,6 +261,47 @@ function providerHelp(): unknown {
   };
 }
 
+function gcHelp(): unknown {
+  return {
+    command: "gc plan|run|db-trace",
+    output: "json",
+    usage: [
+      "bun scripts/cli.ts gc plan",
+      "bun scripts/cli.ts gc run --confirm",
+      "bun scripts/cli.ts gc plan --logs-keep-days 7 --docker-log-max-bytes 50M --journal-target-size 512M",
+      "bun scripts/cli.ts gc run --confirm --build-cache-all --include-browser-cache",
+      "bun scripts/cli.ts gc run --confirm --include-browser-cache",
+      "bun scripts/cli.ts gc db-trace plan --before-date 2026-05-25",
+      "bun scripts/cli.ts gc db-trace run --confirm --before-date 2026-05-25 --vacuum-full",
+      "bun scripts/cli.ts gc plan --full",
+    ],
+    description: "Plan or execute bounded one-time main-server disk relief for file logs, Docker json logs, systemd journal, Docker BuildKit cache, allowlisted /tmp artifacts and explicitly scoped database trace telemetry retention.",
+    safety: {
+      default: "plan is read-only and mutation=false",
+      runGuard: "run requires --confirm",
+      protected: ["PostgreSQL PGDATA", "Docker volumes", "Docker images", "Baidu Netdisk staging/backups", "D601 registry storage"],
+      database: "default gc run is database diagnostic-only; gc db-trace is the explicit trace telemetry retention path and requires --confirm plus --vacuum-full",
+    },
+    options: {
+      "--logs-keep-days N": "delete UniDesk file logs older than N days; default 7",
+      "--file-log-max-bytes SIZE": "compact newer large file logs above SIZE; default 50M",
+      "--file-log-tail-bytes SIZE": "tail bytes kept when compacting file logs; default 20M",
+      "--docker-log-max-bytes SIZE": "truncate Docker json-file logs above SIZE; default 50M",
+      "--journal-target-size SIZE": "vacuum systemd journal to SIZE; default 512M",
+      "--build-cache-until DURATION": "prune Docker builder cache unused for duration; default 24h",
+      "--build-cache-all": "prune all Docker builder cache without an until filter",
+      "--tmp-min-age-hours N": "delete allowlisted /tmp artifacts older than N hours; default 24",
+      "--limit N": "number of candidates returned and executed by run when --full is not set; default 50",
+      "--full|--raw": "return and run against all candidates rather than the default bounded page",
+      "--include-browser-cache": "also remove repo-local .state/playwright-browsers cache",
+      "db-trace --before-date YYYY-MM-DD": "plan or delete default trace telemetry event types before the date",
+      "db-trace run --vacuum-full": "rewrite public.oa_events after deletion so df can reclaim disk; requires maintenance window",
+      "--no-file-logs|--no-docker-logs|--no-journal|--no-build-cache|--no-tmp|--no-db-summary": "disable one collector",
+    },
+    reference: "docs/reference/cli.md",
+  };
+}
+
 function commanderHelp(): unknown {
   return {
     command: "commander contract|plan|smoke|approval|prompt-lint",
@@ -530,6 +572,7 @@ export function staticNamespaceHelp(args: string[]): unknown | null {
   if (top === "microservice") return microserviceHelp();
   if (top === "decision" || top === "decision-center") return decisionHelp();
   if (top === "provider") return providerHelp();
+  if (top === "gc") return gcHelp();
   if (top === "commander") return commanderHelp();
   if (top === "schedule") return scheduleHelp();
   if (top === "codex") return codexHelp();