mlclaw 0.2.3 → 0.3.1

package/dist/hf-state-sync.js

@@ -7,6 +7,7 @@ var __export = (target, all) => {
 
 // src/hf-state-sync/hub.ts
 import fs from "node:fs/promises";
+import path from "node:path";
 
 // src/vendor/hfjs-xet/error.ts
 async function createApiError(response, opts) {
@@ -3828,10 +3829,10 @@ var CurrentXorbInfo = class {
       hash: computeXorbHash(xorbChunksCleaned),
       chunks: xorbChunksCleaned,
       id: this.id,
-      files: Object.entries(this.fileProcessedBytes).map(([path6, processedBytes]) => ({
-        path: path6,
-        progress: processedBytes / this.fileSize[path6],
-        lastSentProgress: ((this.fileUploadedBytes[path6] ?? 0) + (processedBytes - (this.fileUploadedBytes[path6] ?? 0)) * PROCESSING_PROGRESS_RATIO) / this.fileSize[path6]
+      files: Object.entries(this.fileProcessedBytes).map(([path9, processedBytes]) => ({
+        path: path9,
+        progress: processedBytes / this.fileSize[path9],
+        lastSentProgress: ((this.fileUploadedBytes[path9] ?? 0) + (processedBytes - (this.fileUploadedBytes[path9] ?? 0)) * PROCESSING_PROGRESS_RATIO) / this.fileSize[path9]
       }))
     };
   }
@@ -4704,7 +4705,7 @@ var BucketClient = class {
     if (paths.length === 0) {
       return;
     }
-    await this.batch(paths.map((path6) => ({ type: "deleteFile", path: path6 })));
+    await this.batch(paths.map((path9) => ({ type: "deleteFile", path: path9 })));
   }
   async batch(operations) {
     const body = `${operations.map((op) => JSON.stringify(op)).join("\n")}
@@ -4720,8 +4721,8 @@ var BucketClient = class {
    * any other failure (including bucket/auth errors), so a missing object is
    * never conflated with an unreachable bucket.
    */
-  async downloadFile(path6) {
-    const url = `${this.hubUrl}/buckets/${this.bucket}/resolve/${encodeURIComponent(path6)}`;
+  async downloadFile(path9) {
+    const url = `${this.hubUrl}/buckets/${this.bucket}/resolve/${encodeURIComponent(path9)}`;
     const response = await this.fetchWithRetry(url);
     if (response.status === 404) {
       await this.assertBucketAccessible();
@@ -4813,10 +4814,82 @@ function createHfBucketHub(params) {
     }
   };
 }
+function createMountedBucketHub(params) {
+  const root = path.resolve(params.mountDir);
+  const assertMountRoot = async () => {
+    let stat;
+    try {
+      stat = await fs.stat(root);
+    } catch (err) {
+      if (isNotFound(err)) {
+        throw new Error(`mounted bucket root is missing: ${root}`);
+      }
+      const message = err instanceof Error ? err.message : String(err);
+      throw new Error(`mounted bucket root is not accessible: ${root}: ${message}`);
+    }
+    if (!stat.isDirectory()) {
+      throw new Error(`mounted bucket root is not a directory: ${root}`);
+    }
+  };
+  const localPathFor = (remotePath2) => {
+    const normalized = remotePath2.replace(/^\/+/, "");
+    const resolved = path.resolve(root, normalized);
+    if (resolved !== root && !resolved.startsWith(`${root}${path.sep}`)) {
+      throw new Error(`invalid bucket path outside mount: ${remotePath2}`);
+    }
+    return resolved;
+  };
+  return {
+    async download(remotePath2, localPath) {
+      await assertMountRoot();
+      const source = localPathFor(remotePath2);
+      try {
+        await fs.copyFile(source, localPath);
+        return "downloaded";
+      } catch (err) {
+        if (isNotFound(err)) {
+          return "not-found";
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`mounted bucket download failed for ${remotePath2}: ${message}`);
+      }
+    },
+    async upload(localPath, remotePath2) {
+      await assertMountRoot();
+      const target = localPathFor(remotePath2);
+      const dir = path.dirname(target);
+      const tmp = path.join(dir, `.tmp-${path.basename(target)}-${process.pid}-${Date.now()}`);
+      try {
+        await fs.mkdir(dir, { recursive: true });
+        await fs.copyFile(localPath, tmp);
+        await fs.chmod(tmp, 420);
+        await fs.rename(tmp, target);
+      } catch (err) {
+        await fs.rm(tmp, { force: true }).catch(() => void 0);
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`mounted bucket upload failed for ${remotePath2}: ${message}`);
+      }
+    },
+    async delete(remotePaths) {
+      await assertMountRoot();
+      for (const remotePath2 of remotePaths) {
+        try {
+          await fs.rm(localPathFor(remotePath2), { force: true });
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          console.error(`[hf-state-sync] prune failed for ${remotePath2}: ${message}`);
+        }
+      }
+    }
+  };
+}
+function isNotFound(err) {
+  return err instanceof Error && "code" in err && err.code === "ENOENT";
+}
 
 // src/hf-state-sync/paths.ts
 import { randomUUID } from "node:crypto";
-var DEFAULT_LIVE_DIR = "/tmp/openclaw-live";
+var DEFAULT_LIVE_DIR = "/home/node/.local/share/mlclaw/live";
 var DEFAULT_BUCKET_PREFIX = "openclaw-state";
 var DEFAULT_INTERVAL_SECONDS = 60;
 var DEFAULT_HANDOFF_POLL_SECONDS = 5;
@@ -4827,9 +4900,12 @@ function positiveIntFromEnv(value, fallback) {
 }
 function resolveSyncConfig(env = process.env) {
   const runId = env.MLCLAW_RUN_ID?.trim() || randomUUID();
+  const snapshotUid = nonNegativeIntFromEnv(env.MLCLAW_OPENCLAW_UID);
+  const snapshotGid = nonNegativeIntFromEnv(env.MLCLAW_OPENCLAW_GID);
   return {
     liveDir: env.OPENCLAW_LIVE_DIR?.trim() || DEFAULT_LIVE_DIR,
     bucket: env.OPENCLAW_HF_STATE_BUCKET?.trim() || null,
+    stateMountDir: env.MLCLAW_STATE_MOUNT_DIR?.trim() || null,
     bucketPrefix: normalizeBucketPrefix(env.OPENCLAW_HF_STATE_PREFIX),
     intervalSeconds: positiveIntFromEnv(env.HF_STATE_SYNC_INTERVAL_SECONDS, DEFAULT_INTERVAL_SECONDS),
     handoffPollSeconds: positiveIntFromEnv(env.HF_STATE_SYNC_HANDOFF_POLL_SECONDS, DEFAULT_HANDOFF_POLL_SECONDS),
@@ -4838,9 +4914,16 @@ function resolveSyncConfig(env = process.env) {
     runtimeId: env.MLCLAW_RUNTIME_ID?.trim() || runId,
     agentName: env.OPENCLAW_AGENT_NAME?.trim() || "openclaw",
     gatewayLocation: env.MLCLAW_GATEWAY_LOCATION === "local" || env.MLCLAW_GATEWAY_LOCATION === "space" ? env.MLCLAW_GATEWAY_LOCATION : "unknown",
-    runtimeImage: env.MLCLAW_RUNTIME_IMAGE?.trim() || "unknown"
+    runtimeImage: env.MLCLAW_RUNTIME_IMAGE?.trim() || "unknown",
+    ...snapshotUid !== void 0 ? { snapshotUid } : {},
+    ...snapshotGid !== void 0 ? { snapshotGid } : {},
+    ...env.MLCLAW_PROTECTED_STATE_DIR?.trim() ? { protectedStateDir: env.MLCLAW_PROTECTED_STATE_DIR.trim() } : {}
   };
 }
+function nonNegativeIntFromEnv(value) {
+  const parsed = Number(value);
+  return Number.isInteger(parsed) && parsed >= 0 ? parsed : void 0;
+}
 function remotePath(config, name) {
   return `${normalizeBucketPrefix(config.bucketPrefix)}/${name.replace(/^\/+/, "")}`;
 }
@@ -4858,20 +4941,20 @@ function logError(message) {
 // src/hf-state-sync/restore.ts
 import fs4 from "node:fs/promises";
 import os from "node:os";
-import path3 from "node:path";
+import path4 from "node:path";
 
 // src/hf-state-sync/archive.ts
 import { execFile } from "node:child_process";
 import { createHash } from "node:crypto";
 import { createReadStream } from "node:fs";
 import fs3 from "node:fs/promises";
-import path2 from "node:path";
+import path3 from "node:path";
 import { pipeline } from "node:stream/promises";
 import { promisify } from "node:util";
 
 // src/hf-state-sync/sqlite.ts
 import fs2 from "node:fs/promises";
-import path from "node:path";
+import path2 from "node:path";
 import { DatabaseSync } from "node:sqlite";
 async function findSqliteFiles(root) {
   const found = [];
@@ -4883,7 +4966,7 @@ async function findSqliteFiles(root) {
   }
   for (const entry of entries) {
     if (entry.isFile() && entry.name.endsWith(".sqlite")) {
-      found.push(path.join(entry.parentPath, entry.name));
+      found.push(path2.join(entry.parentPath, entry.name));
     }
   }
   return found.sort();
@@ -4919,6 +5002,7 @@ var STATE_EXCLUDED_NAMES = /* @__PURE__ */ new Set([".env", "credentials", "tmp"
 var STATE_EXCLUDED_SUFFIXES = [".log"];
 var SIDECAR_SUFFIXES = [".sqlite-wal", ".sqlite-shm"];
 var STATE_DIR_NAME = ".openclaw";
+var PROTECTED_STATE_DIR_NAME = ".mlclaw-protected";
 function isExcluded(name, inStateDir) {
   if (SIDECAR_SUFFIXES.some((suffix) => name.endsWith(suffix))) {
     return true;
@@ -4929,15 +5013,18 @@ function isExcluded(name, inStateDir) {
   return STATE_EXCLUDED_NAMES.has(name) || STATE_EXCLUDED_SUFFIXES.some((suffix) => name.endsWith(suffix));
 }
 async function copyTreeFiltered(params) {
-  const { sourceDir, destDir, databases, rootDir, inStateDir, depth } = params;
+  const { sourceDir, destDir, databases, rootDir, inStateDir, depth, excludeProtectedState } = params;
   await fs3.mkdir(destDir, { recursive: true });
   const entries = await fs3.readdir(sourceDir, { withFileTypes: true });
   for (const entry of entries) {
+    if (excludeProtectedState && depth === 0 && entry.name === PROTECTED_STATE_DIR_NAME) {
+      continue;
+    }
     if (isExcluded(entry.name, inStateDir)) {
       continue;
     }
-    const source = path2.join(sourceDir, entry.name);
-    const dest = path2.join(destDir, entry.name);
+    const source = path3.join(sourceDir, entry.name);
+    const dest = path3.join(destDir, entry.name);
     if (entry.isDirectory()) {
       await copyTreeFiltered({
         sourceDir: source,
@@ -4947,11 +5034,12 @@ async function copyTreeFiltered(params) {
         // Only the top-level .openclaw dir is OpenClaw state; a workspace
         // project may legitimately contain its own .openclaw directory.
         inStateDir: inStateDir || depth === 0 && entry.name === STATE_DIR_NAME,
-        depth: depth + 1
+        depth: depth + 1,
+        excludeProtectedState
       });
     } else if (entry.isFile()) {
       if (entry.name.endsWith(".sqlite")) {
-        databases.push(path2.relative(rootDir, source));
+        databases.push(path3.relative(rootDir, source));
       } else {
         await fs3.copyFile(source, dest);
       }
@@ -4960,7 +5048,7 @@ async function copyTreeFiltered(params) {
     }
   }
 }
-async function stageLiveDir(liveDir, stagingDir) {
+async function stageLiveDir(liveDir, stagingDir, options = {}) {
   const databases = [];
   await copyTreeFiltered({
     sourceDir: liveDir,
@@ -4968,12 +5056,13 @@ async function stageLiveDir(liveDir, stagingDir) {
     databases,
     rootDir: liveDir,
     inStateDir: false,
-    depth: 0
+    depth: 0,
+    excludeProtectedState: options.excludeProtectedState ?? false
   });
   for (const relative of databases) {
-    const staged = path2.join(stagingDir, relative);
-    await fs3.mkdir(path2.dirname(staged), { recursive: true });
-    vacuumInto(path2.join(liveDir, relative), staged);
+    const staged = path3.join(stagingDir, relative);
+    await fs3.mkdir(path3.dirname(staged), { recursive: true });
+    vacuumInto(path3.join(liveDir, relative), staged);
     const integrity = checkIntegrity(staged);
     if (integrity.kind === "corrupt") {
       return { kind: "corrupt-database", database: relative, detail: integrity.detail };
@@ -5480,8 +5569,8 @@ function getErrorMap() {
 
 // node_modules/zod/v3/helpers/parseUtil.js
 var makeIssue = (params) => {
-  const { data, path: path6, errorMaps, issueData } = params;
-  const fullPath = [...path6, ...issueData.path || []];
+  const { data, path: path9, errorMaps, issueData } = params;
+  const fullPath = [...path9, ...issueData.path || []];
   const fullIssue = {
     ...issueData,
     path: fullPath
@@ -5597,11 +5686,11 @@ var errorUtil;
 
 // node_modules/zod/v3/types.js
 var ParseInputLazyPath = class {
-  constructor(parent, value, path6, key) {
+  constructor(parent, value, path9, key) {
     this._cachedPath = [];
     this.parent = parent;
     this.data = value;
-    this._path = path6;
+    this._path = path9;
     this._key = key;
   }
   get path() {
@@ -9086,7 +9175,7 @@ function promoteSnapshot(params) {
 // src/hf-state-sync/restore.ts
 async function tryRestoreEntry(params) {
   const { hub, entry, workDir, liveDir } = params;
-  const archivePath = path3.join(workDir, `candidate-${entry.id}.tar.zst`);
+  const archivePath = path4.join(workDir, `candidate-${entry.id}.tar.zst`);
   const downloaded = await hub.download(entry.path, archivePath);
   if (downloaded === "not-found") {
     logError(`snapshot ${entry.id} missing from bucket`);
@@ -9110,11 +9199,11 @@ async function tryRestoreEntry(params) {
     for (const database of await findSqliteFiles(extractDir)) {
       const integrity = checkIntegrity(database);
       if (integrity.kind === "corrupt") {
-        logError(`snapshot ${entry.id} db ${path3.basename(database)} corrupt: ${integrity.detail}`);
+        logError(`snapshot ${entry.id} db ${path4.basename(database)} corrupt: ${integrity.detail}`);
         return "failed";
       }
     }
-    await fs4.mkdir(path3.dirname(liveDir), { recursive: true });
+    await fs4.mkdir(path4.dirname(liveDir), { recursive: true });
     await fs4.rename(extractDir, liveDir);
     return "restored";
   } finally {
@@ -9131,9 +9220,9 @@ async function runRestore(params) {
     return { kind: "fresh-start", reason: "live-dir-exists" };
   } catch {
   }
-  const workDir = await fs4.mkdtemp(path3.join(os.tmpdir(), "hf-state-restore-"));
+  const workDir = await fs4.mkdtemp(path4.join(os.tmpdir(), "hf-state-restore-"));
   try {
-    const manifestPath = path3.join(workDir, "manifest.json");
+    const manifestPath = path4.join(workDir, "manifest.json");
     const downloaded = await hub.download(remotePath(config, MANIFEST_REMOTE_NAME), manifestPath);
     if (downloaded === "not-found") {
       return { kind: "fresh-start", reason: "no-manifest" };
@@ -9157,10 +9246,84 @@ async function runRestore(params) {
   }
 }
 
-// src/hf-state-sync/snapshot.ts
+// src/hf-state-sync/prepare.ts
 import fs5 from "node:fs/promises";
+import path5 from "node:path";
+async function prepareRestore(config) {
+  if (config.snapshotUid === void 0 || config.snapshotGid === void 0) {
+    throw new Error("restore preparation requires MLCLAW_OPENCLAW_UID and MLCLAW_OPENCLAW_GID");
+  }
+  const liveParent = path5.dirname(config.liveDir);
+  await fs5.mkdir(liveParent, { recursive: true });
+  await fs5.chown(liveParent, config.snapshotUid, config.snapshotGid);
+  if (!config.stateMountDir) {
+    return;
+  }
+  await makeTraversableDirectory(config.stateMountDir);
+  const prefixRoot = confinedPath(config.stateMountDir, config.bucketPrefix);
+  let prefixPart = config.stateMountDir;
+  for (const part of config.bucketPrefix.split("/").filter(Boolean)) {
+    prefixPart = path5.join(prefixPart, part);
+    await makeTraversableDirectory(prefixPart);
+  }
+  await makeReadableIfFile(path5.join(prefixRoot, "manifest.json"));
+  const snapshotsDir = path5.join(prefixRoot, "snapshots");
+  await makeTraversableDirectory(snapshotsDir);
+  let entries;
+  try {
+    entries = await fs5.readdir(snapshotsDir, { withFileTypes: true });
+  } catch (err) {
+    if (isNotFound2(err)) {
+      return;
+    }
+    throw err;
+  }
+  for (const entry of entries) {
+    if (entry.isFile()) {
+      await fs5.chmod(path5.join(snapshotsDir, entry.name), 420);
+    }
+  }
+}
+async function makeTraversableDirectory(directory) {
+  try {
+    const stat = await fs5.lstat(directory);
+    if (stat.isDirectory()) {
+      await fs5.chmod(directory, 457);
+    }
+  } catch (err) {
+    if (!isNotFound2(err)) {
+      throw err;
+    }
+  }
+}
+function confinedPath(root, relative) {
+  const resolvedRoot = path5.resolve(root);
+  const resolved = path5.resolve(resolvedRoot, relative);
+  if (resolved !== resolvedRoot && !resolved.startsWith(`${resolvedRoot}${path5.sep}`)) {
+    throw new Error(`invalid state prefix outside mounted bucket: ${relative}`);
+  }
+  return resolved;
+}
+async function makeReadableIfFile(file) {
+  try {
+    const stat = await fs5.lstat(file);
+    if (stat.isFile()) {
+      await fs5.chmod(file, 420);
+    }
+  } catch (err) {
+    if (!isNotFound2(err)) {
+      throw err;
+    }
+  }
+}
+function isNotFound2(err) {
+  return err instanceof Error && "code" in err && err.code === "ENOENT";
+}
+
+// src/hf-state-sync/snapshot.ts
+import fs6 from "node:fs/promises";
 import os2 from "node:os";
-import path4 from "node:path";
+import path6 from "node:path";
 var snapshotCounter = 0;
 function snapshotId(now, runId) {
   snapshotCounter += 1;
@@ -9168,12 +9331,12 @@ function snapshotId(now, runId) {
   return `${stamp}-${runId.slice(0, 8)}-${snapshotCounter}`;
 }
 async function fetchManifest(config, hub, workDir) {
-  const localPath = path4.join(workDir, "manifest.remote.json");
+  const localPath = path6.join(workDir, "manifest.remote.json");
   const result = await hub.download(remotePath(config, MANIFEST_REMOTE_NAME), localPath);
   if (result === "not-found") {
     return { kind: "none" };
   }
-  const parsed = parseManifest(await fs5.readFile(localPath, "utf8"));
+  const parsed = parseManifest(await fs6.readFile(localPath, "utf8"));
   return parsed.kind === "ok" ? { kind: "ok", manifest: parsed.manifest } : { kind: "invalid", reason: parsed.reason };
 }
 async function runSnapshot(params) {
@@ -9182,31 +9345,29 @@ async function runSnapshot(params) {
     return { kind: "skipped", reason: "no-bucket" };
   }
   try {
-    await fs5.access(config.liveDir);
+    await fs6.access(config.liveDir);
   } catch {
     return { kind: "skipped", reason: "empty-state" };
   }
-  const workDir = await fs5.mkdtemp(path4.join(os2.tmpdir(), "hf-state-snapshot-"));
+  const workDir = await fs6.mkdtemp(path6.join(os2.tmpdir(), "hf-state-snapshot-"));
   try {
-    const stagingDir = path4.join(workDir, "stage");
-    const staged = await stageLiveDir(config.liveDir, stagingDir);
+    const now = (params.now ?? (() => /* @__PURE__ */ new Date()))();
+    const id = snapshotId(now, config.runId);
+    const archiveName = `state-${id}.tar.zst`;
+    const archivePath = path6.join(workDir, archiveName);
+    const staged = params.stageArchive ? await params.stageArchive({ liveDir: config.liveDir, archivePath }) : await stageArchiveInProcess(config.liveDir, path6.join(workDir, "stage"), archivePath);
     if (staged.kind === "corrupt-database") {
       return {
         kind: "failed",
         detail: `live database ${staged.database} failed integrity check: ${staged.detail}`
       };
     }
-    const now = (params.now ?? (() => /* @__PURE__ */ new Date()))();
-    const id = snapshotId(now, config.runId);
-    const archiveName = `state-${id}.tar.zst`;
-    const archivePath = path4.join(workDir, archiveName);
-    await createTarZst(stagingDir, archivePath);
     const entry = {
       id,
       path: remotePath(config, `snapshots/${archiveName}`),
       createdAt: now.toISOString(),
       sha256: await sha256File(archivePath),
-      sizeBytes: (await fs5.stat(archivePath)).size,
+      sizeBytes: (await fs6.stat(archivePath)).size,
       runId: config.runId,
       bootTime: params.bootTime
     };
@@ -9223,27 +9384,182 @@ async function runSnapshot(params) {
       entry,
       keep: config.keepSnapshots
     });
-    const manifestPath = path4.join(workDir, "manifest.json");
-    await fs5.writeFile(manifestPath, serializeManifest(manifest));
+    const manifestPath = path6.join(workDir, "manifest.json");
+    await fs6.writeFile(manifestPath, serializeManifest(manifest));
     await hub.upload(manifestPath, remotePath(config, MANIFEST_REMOTE_NAME));
     if (expired.length > 0) {
       await hub.delete(expired.map((e) => e.path));
     }
-    log(`snapshot ${entry.id} uploaded (${entry.sizeBytes} bytes, ${staged.databases.length} dbs)`);
+    log(`snapshot ${entry.id} uploaded (${entry.sizeBytes} bytes, ${staged.databaseCount} dbs)`);
     return { kind: "uploaded", entry };
   } catch (err) {
     return { kind: "failed", detail: err instanceof Error ? err.message : String(err) };
   } finally {
-    await fs5.rm(workDir, { recursive: true, force: true });
+    await fs6.rm(workDir, { recursive: true, force: true });
+  }
+}
+async function stageArchiveInProcess(liveDir, stagingDir, archivePath) {
+  const staged = await stageLiveDir(liveDir, stagingDir);
+  if (staged.kind === "corrupt-database") {
+    return staged;
   }
+  await createTarZst(stagingDir, archivePath);
+  return { kind: "staged", databaseCount: staged.databases.length };
 }
 
 // src/hf-state-sync/supervise.ts
+import { spawn as spawn2 } from "node:child_process";
+import fs8 from "node:fs/promises";
+import os4 from "node:os";
+import path8 from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+
+// src/hf-state-sync/stage-worker.ts
 import { spawn } from "node:child_process";
-import fs6 from "node:fs/promises";
+import { createReadStream as createReadStream2, createWriteStream, writeFileSync } from "node:fs";
+import fs7 from "node:fs/promises";
 import os3 from "node:os";
-import path5 from "node:path";
-import { setTimeout as delay } from "node:timers/promises";
+import path7 from "node:path";
+import { pipeline as pipeline2 } from "node:stream/promises";
+function unprivilegedStageArchive(params) {
+  return async ({ liveDir, archivePath }) => {
+    const child = spawn(process.execPath, [params.scriptPath, "stage-worker", liveDir], {
+      uid: params.uid,
+      gid: params.gid,
+      env: snapshotWorkerEnvironment(process.env),
+      stdio: ["ignore", "pipe", "inherit", "pipe"]
+    });
+    if (!child.stdout || !child.stdio[3]) {
+      child.kill("SIGKILL");
+      throw new Error("snapshot staging worker pipes are unavailable");
+    }
+    const archiveOutput = createWriteStream(archivePath, { flags: "wx", mode: 384 });
+    const metadata = collect(child.stdio[3]);
+    const archive = pipeline2(child.stdout, archiveOutput);
+    const exitCode = await new Promise((resolve, reject) => {
+      child.once("error", reject);
+      child.once("exit", (code, signal) => resolve(code ?? (signal ? 128 : 1)));
+    });
+    await archive;
+    const message = parseWorkerMessage(await metadata);
+    if (exitCode !== 0 || message.kind === "failed") {
+      throw new Error(
+        message.kind === "failed" ? message.detail : `snapshot staging worker exited with code ${exitCode}`
+      );
+    }
+    return message;
+  };
+}
+function protectedStageArchive(params) {
+  return async (request) => {
+    const outcome = await params.base(request);
+    if (outcome.kind !== "staged") {
+      return outcome;
+    }
+    const workDir = await fs7.mkdtemp(path7.join(os3.tmpdir(), "hf-state-protected-stage-"));
+    try {
+      const stagingDir = path7.join(workDir, "stage");
+      await extractTarZst(request.archivePath, stagingDir);
+      const destination = path7.join(stagingDir, params.archiveName);
+      await fs7.cp(params.sourceDir, destination, {
+        recursive: true,
+        force: false,
+        preserveTimestamps: true,
+        filter: (source) => includeProtectedSnapshotPath(params.sourceDir, source)
+      });
+      await fs7.chmod(destination, 448);
+      await fs7.rm(request.archivePath, { force: true });
+      await createTarZst(stagingDir, request.archivePath);
+      await fs7.chmod(request.archivePath, 384);
+      return outcome;
+    } finally {
+      await fs7.rm(workDir, { recursive: true, force: true });
+    }
+  };
+}
+function includeProtectedSnapshotPath(sourceDir, source) {
+  const relative = path7.relative(sourceDir, source);
+  return relative !== "hf-broker/mirrors" && !relative.startsWith(`hf-broker/mirrors${path7.sep}`);
+}
+function trustedStageArchive(config, scriptPath) {
+  const canStageAsOpenClaw = process.getuid?.() === 0 && Boolean(scriptPath) && config.snapshotUid !== void 0 && config.snapshotGid !== void 0;
+  if (!canStageAsOpenClaw) {
+    if (config.protectedStateDir) {
+      throw new Error("protected runtime state requires root snapshot staging with an OpenClaw UID and GID");
+    }
+    return void 0;
+  }
+  let stageArchive = unprivilegedStageArchive({
+    uid: config.snapshotUid,
+    gid: config.snapshotGid,
+    scriptPath
+  });
+  if (config.protectedStateDir) {
+    stageArchive = protectedStageArchive({
+      base: stageArchive,
+      sourceDir: config.protectedStateDir,
+      archiveName: PROTECTED_STATE_DIR_NAME
+    });
+  }
+  return stageArchive;
+}
+async function runStageWorker(liveDir) {
+  const workDir = await fs7.mkdtemp(path7.join(os3.tmpdir(), "hf-state-stage-worker-"));
+  try {
+    const stagingDir = path7.join(workDir, "stage");
+    const archivePath = path7.join(workDir, "snapshot.tar.zst");
+    const staged = await stageLiveDir(liveDir, stagingDir, { excludeProtectedState: true });
+    if (staged.kind === "corrupt-database") {
+      writeWorkerMessage(staged);
+      return 0;
+    }
+    await createTarZst(stagingDir, archivePath);
+    writeWorkerMessage({ kind: "staged", databaseCount: staged.databases.length });
+    await pipeline2(createReadStream2(archivePath), process.stdout);
+    return 0;
+  } catch (err) {
+    writeWorkerMessage({ kind: "failed", detail: err instanceof Error ? err.message : String(err) });
+    return 1;
+  } finally {
+    await fs7.rm(workDir, { recursive: true, force: true });
+  }
+}
+function snapshotWorkerEnvironment(env) {
+  return {
+    HOME: "/home/node",
+    PATH: env.PATH,
+    TMPDIR: env.TMPDIR
+  };
+}
+function writeWorkerMessage(message) {
+  writeFileSync(3, `${JSON.stringify(message)}
+`);
+}
+async function collect(stream) {
+  if (!stream) {
+    throw new Error("snapshot staging worker metadata pipe is unavailable");
+  }
+  const chunks = [];
+  for await (const chunk of stream) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+function parseWorkerMessage(raw) {
+  const parsed = JSON.parse(raw);
+  if (parsed.kind === "staged" && Number.isInteger(parsed.databaseCount) && parsed.databaseCount >= 0) {
+    return parsed;
+  }
+  if (parsed.kind === "corrupt-database" && parsed.database && parsed.detail) {
+    return parsed;
+  }
+  if (parsed.kind === "failed" && parsed.detail) {
+    return parsed;
+  }
+  throw new Error("snapshot staging worker returned invalid metadata");
+}
+
+// src/hf-state-sync/supervise.ts
 var LEASE_HEARTBEAT_MS = 6e4;
 var HANDOFF_REQUEST_TTL_MS = 10 * 60 * 1e3;
 async function supervise(params) {
@@ -9253,6 +9569,8 @@ async function supervise(params) {
     throw new Error("supervise: missing child command");
   }
   const bootTime = (/* @__PURE__ */ new Date()).toISOString();
+  const scriptPath = process.argv[1];
+  const stageArchive = trustedStageArchive(config, scriptPath);
   let lastSnapshotId;
   const handoffState = { request: null };
   const writeLease = async () => {
@@ -9266,24 +9584,24 @@ async function supervise(params) {
       lastHeartbeatAt: (/* @__PURE__ */ new Date()).toISOString(),
       ...lastSnapshotId ? { lastSnapshotId } : {}
     };
-    const tmpDir = await fs6.mkdtemp(path5.join(os3.tmpdir(), "hf-state-lease-"));
+    const tmpDir = await fs8.mkdtemp(path8.join(os4.tmpdir(), "hf-state-lease-"));
     try {
-      const file = path5.join(tmpDir, "status.json");
-      await fs6.writeFile(file, JSON.stringify(status, null, 2) + "\n");
+      const file = path8.join(tmpDir, "status.json");
+      await fs8.writeFile(file, JSON.stringify(status, null, 2) + "\n");
       await hub.upload(file, remotePath(config, "runtime/status.json"));
     } finally {
-      await fs6.rm(tmpDir, { recursive: true, force: true });
+      await fs8.rm(tmpDir, { recursive: true, force: true });
     }
   };
   const readHandoffRequest = async () => {
-    const tmpDir = await fs6.mkdtemp(path5.join(os3.tmpdir(), "hf-state-handoff-"));
+    const tmpDir = await fs8.mkdtemp(path8.join(os4.tmpdir(), "hf-state-handoff-"));
     try {
-      const file = path5.join(tmpDir, "request.json");
+      const file = path8.join(tmpDir, "request.json");
       const result = await hub.download(remotePath(config, "runtime/handoff-request.json"), file);
       if (result === "not-found") {
         return null;
       }
-      const parsed = JSON.parse(await fs6.readFile(file, "utf8"));
+      const parsed = JSON.parse(await fs8.readFile(file, "utf8"));
       if (parsed?.schemaVersion !== 1 || parsed.agent !== config.agentName || parsed.runtimeId !== config.runtimeId || typeof parsed.requestedAt !== "string" || typeof parsed.requestId !== "string" || !parsed.requestId) {
         return null;
       }
@@ -9297,7 +9615,7 @@ async function supervise(params) {
       }
       return parsed;
     } finally {
-      await fs6.rm(tmpDir, { recursive: true, force: true });
+      await fs8.rm(tmpDir, { recursive: true, force: true });
     }
   };
   const writeHandoffAck = async (request) => {
@@ -9310,17 +9628,20 @@ async function supervise(params) {
       completedAt: (/* @__PURE__ */ new Date()).toISOString(),
       ...lastSnapshotId ? { lastSnapshotId } : {}
     };
-    const tmpDir = await fs6.mkdtemp(path5.join(os3.tmpdir(), "hf-state-handoff-ack-"));
+    const tmpDir = await fs8.mkdtemp(path8.join(os4.tmpdir(), "hf-state-handoff-ack-"));
     try {
-      const file = path5.join(tmpDir, "ack.json");
-      await fs6.writeFile(file, JSON.stringify(ack, null, 2) + "\n");
+      const file = path8.join(tmpDir, "ack.json");
+      await fs8.writeFile(file, JSON.stringify(ack, null, 2) + "\n");
       await hub.upload(file, remotePath(config, "runtime/handoff-ack.json"));
       await hub.delete([remotePath(config, "runtime/handoff-request.json")]);
     } finally {
-      await fs6.rm(tmpDir, { recursive: true, force: true });
+      await fs8.rm(tmpDir, { recursive: true, force: true });
     }
   };
-  const child = spawn(binary, args, { stdio: "inherit" });
+  const child = spawn2(binary, args, {
+    stdio: "inherit",
+    env: supervisedChildEnvironment(process.env)
+  });
   const childExit = new Promise((resolve) => {
     child.on("exit", (code, signal) => resolve(code ?? (signal ? 128 : 1)));
     child.on("error", (err) => {
@@ -9332,7 +9653,12 @@ async function supervise(params) {
   let inFlight = null;
   const runOnce = async (label) => {
     try {
-      const outcome = await runSnapshot({ config, hub, bootTime });
+      const outcome = await runSnapshot({
+        config,
+        hub,
+        bootTime,
+        ...stageArchive ? { stageArchive } : {}
+      });
       if (outcome.kind === "failed") {
         logError(`${label}: snapshot failed: ${outcome.detail}`);
       } else if (outcome.kind === "uploaded") {
@@ -9372,7 +9698,9 @@ async function supervise(params) {
   })();
   void snapshotLoop;
   const heartbeatLoop = (async () => {
-    await writeLease().catch((err) => logError(`initial lease failed: ${err instanceof Error ? err.message : String(err)}`));
+    await writeLease().catch(
+      (err) => logError(`initial lease failed: ${err instanceof Error ? err.message : String(err)}`)
+    );
     while (!stopping) {
       await delay(LEASE_HEARTBEAT_MS);
       if (stopping) {
@@ -9430,16 +9758,25 @@ async function supervise(params) {
   if (handoffState.request) {
     const request = handoffState.request;
     if (finalOutcome.kind !== "uploaded") {
-      throw new Error(`handoff ${request.requestId} final snapshot did not upload: ${snapshotFailureDetail(finalOutcome)}`);
+      throw new Error(
+        `handoff ${request.requestId} final snapshot did not upload: ${snapshotFailureDetail(finalOutcome)}`
+      );
     }
     await writeHandoffAck(request).catch((err) => {
-      throw new Error(`handoff ${request.requestId} snapshot completed but ack failed: ${err instanceof Error ? err.message : String(err)}`);
+      throw new Error(
+        `handoff ${request.requestId} snapshot completed but ack failed: ${err instanceof Error ? err.message : String(err)}`
+      );
     });
     log(`handoff ${request.requestId} acknowledged`);
     return 0;
   }
   return exitCode;
 }
+function supervisedChildEnvironment(source) {
+  const env = { ...source };
+  delete env.MLCLAW_STATE_HF_TOKEN;
+  return env;
+}
 function snapshotFailureDetail(outcome) {
   switch (outcome.kind) {
     case "uploaded":
@@ -9456,17 +9793,36 @@ var USAGE = `usage:
   hf-state-sync restore
   hf-state-sync snapshot
   hf-state-sync supervise -- <command> [args...]`;
-function makeHub(bucket) {
-  return bucket ? createHfBucketHub({ bucket }) : null;
+function makeHub(config) {
+  if (!config.bucket) {
+    return null;
+  }
+  if (config.stateMountDir) {
+    log(`using mounted state bucket at ${config.stateMountDir}`);
+    return createMountedBucketHub({ mountDir: config.stateMountDir });
+  }
+  const token = process.env.MLCLAW_STATE_HF_TOKEN ?? process.env.HF_TOKEN;
+  return createHfBucketHub({ bucket: config.bucket, ...token ? { token } : {} });
 }
 async function main(argv) {
+  if (argv[0] === "stage-worker") {
+    const liveDir = argv[1];
+    if (!liveDir) {
+      logError("stage-worker: missing live directory");
+      return 2;
+    }
+    return runStageWorker(liveDir);
+  }
   const config = resolveSyncConfig();
-  const hub = makeHub(config.bucket);
+  const hub = makeHub(config);
   if (!hub) {
     logError("OPENCLAW_HF_STATE_BUCKET is not set; state will NOT survive restarts");
   }
   const mode = argv[0];
   switch (mode) {
+    case "prepare-restore":
+      await prepareRestore(config);
+      return 0;
     case "restore": {
       if (!hub) {
         return 0;
@@ -9491,7 +9847,13 @@ async function main(argv) {
       if (!hub) {
         return 1;
       }
-      const outcome = await runSnapshot({ config, hub, bootTime: (/* @__PURE__ */ new Date()).toISOString() });
+      const stageArchive = trustedStageArchive(config, process.argv[1]);
+      const outcome = await runSnapshot({
+        config,
+        hub,
+        bootTime: (/* @__PURE__ */ new Date()).toISOString(),
+        ...stageArchive ? { stageArchive } : {}
+      });
       if (outcome.kind === "failed") {
         logError(outcome.detail);
         return 1;
@@ -9507,8 +9869,8 @@ async function main(argv) {
         return 2;
       }
       if (!hub) {
-        const { spawn: spawn2 } = await import("node:child_process");
-        const child = spawn2(command[0], command.slice(1), { stdio: "inherit" });
+        const { spawn: spawn3 } = await import("node:child_process");
+        const child = spawn3(command[0], command.slice(1), { stdio: "inherit" });
         return await new Promise((resolve) => {
           process.on("SIGTERM", () => child.kill("SIGTERM"));
           process.on("SIGINT", () => child.kill("SIGINT"));