fix(crabbox): preflight sparse sync disk space

vincentkoc · vincentkoc · commit e24582d53cbf · 2026-06-02T11:42:14.000+02:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -45,6 +45,7 @@ Docs: https://docs.openclaw.ai
 
 ### Fixes
 
+- Release/CI/E2E: fail early when Crabbox sparse-sync full checkouts do not have enough local disk, with guidance for moving the sync root.
 - Control UI: serve static assets asynchronously after safe-open checks so large UI files do not block Gateway request handling.
 - Scripts/UI: forward direct wrapper SIGHUP shutdown to child processes so terminal hangups do not leave wrapped dev commands running.
 - Gateway: return the post-expiration pending-work revision from node drains so reconnecting nodes do not observe stale queue revisions after expired items are pruned.
diff --git a/scripts/crabbox-wrapper.mjs b/scripts/crabbox-wrapper.mjs
@@ -10,6 +10,7 @@ import {
   readFileSync,
   readdirSync,
   rmSync,
+  statfsSync,
   statSync,
   utimesSync,
   writeFileSync,
@@ -1937,8 +1938,60 @@ function fullCheckoutSyncRoot() {
   return root;
 }
 
+function parsePositiveIntegerEnv(name, fallback) {
+  const raw = process.env[name]?.trim();
+  if (!raw) {
+    return fallback;
+  }
+  if (!/^\d+$/u.test(raw)) {
+    throw new Error(`${name} must be a non-negative integer byte count, got ${JSON.stringify(raw)}`);
+  }
+  const parsed = Number.parseInt(raw, 10);
+  return parsed;
+}
+
+function formatByteCount(bytes) {
+  if (bytes < 1024) {
+    return `${bytes} B`;
+  }
+  const units = ["KiB", "MiB", "GiB", "TiB"];
+  let value = bytes / 1024;
+  let unitIndex = 0;
+  while (value >= 1024 && unitIndex < units.length - 1) {
+    value /= 1024;
+    unitIndex += 1;
+  }
+  return `${value.toFixed(value >= 10 ? 1 : 2)} ${units[unitIndex]}`;
+}
+
+function assertFullCheckoutSyncDisk(root) {
+  const requiredBytes = parsePositiveIntegerEnv(
+    "OPENCLAW_CRABBOX_SYNC_MIN_FREE_BYTES",
+    1024 * 1024 * 1024,
+  );
+  if (requiredBytes === 0) {
+    return;
+  }
+  const stats = statfsSync(root);
+  const freeBytes = stats.bavail * stats.bsize;
+  if (freeBytes >= requiredBytes) {
+    return;
+  }
+  throw new Error(
+    [
+      "insufficient free disk for Crabbox sparse-sync full checkout",
+      `root=${root}`,
+      `free=${formatByteCount(freeBytes)}`,
+      `required=${formatByteCount(requiredBytes)}`,
+      "set OPENCLAW_CRABBOX_SYNC_TMPDIR to a roomier filesystem or lower OPENCLAW_CRABBOX_SYNC_MIN_FREE_BYTES if you know this checkout fits",
+    ].join("; "),
+  );
+}
+
 function prepareFullCheckoutForSync(options = {}) {
-  const dir = mkdtempSync(resolve(fullCheckoutSyncRoot(), "openclaw-crabbox-sync-"));
+  const syncRoot = fullCheckoutSyncRoot();
+  assertFullCheckoutSyncDisk(syncRoot);
+  const dir = mkdtempSync(resolve(syncRoot, "openclaw-crabbox-sync-"));
   let active = false;
 
   function create() {
diff --git a/test/scripts/crabbox-wrapper.test.ts b/test/scripts/crabbox-wrapper.test.ts
@@ -2492,6 +2492,37 @@ describe.concurrent("scripts/crabbox-wrapper", () => {
     }
   });
 
+  it("fails sparse-sync full checkout early when the sync root is too low on disk", () => {
+    const syncRoot = path.join(repoRoot, ".crabbox-test-low-disk-sync-root");
+    rmSync(syncRoot, { recursive: true, force: true });
+    try {
+      const result = runWrapper(
+        "provider: hetzner, aws, local-container, blacksmith-testbox, or cloudflare\n",
+        ["run", "--provider", "aws", "--", "echo ok"],
+        {
+          env: {
+            OPENCLAW_CRABBOX_SYNC_MIN_FREE_BYTES: "999999999999999",
+            OPENCLAW_CRABBOX_SYNC_TMPDIR: syncRoot,
+          },
+          gitResponses: {
+            [GIT_CONFIG_SPARSE_KEY]: { stdout: "true\n" },
+            [GIT_STATUS_PORCELAIN_KEY]: { stdout: "" },
+          },
+        },
+      );
+
+      expect(result.status).toBe(1);
+      expect(result.stderr).toContain(
+        "insufficient free disk for Crabbox sparse-sync full checkout",
+      );
+      expect(result.stderr).toContain("OPENCLAW_CRABBOX_SYNC_TMPDIR");
+      expect(result.stderr).toContain("OPENCLAW_CRABBOX_SYNC_MIN_FREE_BYTES");
+      expect(readdirSync(syncRoot)).toEqual([]);
+    } finally {
+      rmSync(syncRoot, { recursive: true, force: true });
+    }
+  });
+
   (process.platform === "win32" ? it.skip : it)(
     "recreates sparse-sync temporary full checkouts that disappear while Crabbox is running",
     () => {
