mlclaw 0.2.3 → 0.3.1

package/entrypoint.sh

@@ -1,16 +1,138 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-LIVE_DIR="${OPENCLAW_LIVE_DIR:-/tmp/openclaw-live}"
+LIVE_DIR="${OPENCLAW_LIVE_DIR:-/home/node/.local/share/mlclaw/live}"
+OPENCLAW_UID="${MLCLAW_OPENCLAW_UID:-1000}"
+OPENCLAW_GID="${MLCLAW_OPENCLAW_GID:-1000}"
+OPENCLAW_IDENTITY="${OPENCLAW_UID}:${OPENCLAW_GID}"
+export MLCLAW_OPENCLAW_UID="$OPENCLAW_UID"
+export MLCLAW_OPENCLAW_GID="$OPENCLAW_GID"
+HF_BROKER_ENABLED=0
+HF_BROKER_RUN_DIR="/run/mlclaw-hf-broker"
+STATE_HF_TOKEN=""
+RESTORED_PROTECTED_STATE_DIR="$LIVE_DIR/.mlclaw-protected"
+PROTECTED_STATE_DIR="/var/lib/mlclaw-protected"
+HF_BROKER_STATE_DIR="$PROTECTED_STATE_DIR/hf-broker"
+
+prepare_hf_broker() {
+  local broker_token="${MLCLAW_BROKER_HF_TOKEN:-${HF_TOKEN:-${HUGGINGFACE_HUB_TOKEN:-${MLCLAW_ROUTER_TOKEN:-${HF_ROUTER_TOKEN:-}}}}}"
+  if [ -z "$broker_token" ]; then
+    echo "[hf-broker] MLCLAW_BROKER_HF_TOKEN is not configured; broker disabled"
+    return
+  fi
+
+  local token_file="$HF_BROKER_RUN_DIR/hf-token"
+  local agent_secret_file="$HF_BROKER_RUN_DIR/agent-secret"
+  local operator_secret_file="$HF_BROKER_RUN_DIR/operator-secret"
+  local broker_agent_secrets="$HF_BROKER_RUN_DIR/agent-secrets.conf"
+  local broker_operator_secrets="$HF_BROKER_RUN_DIR/operator-secrets.conf"
+  local operator_brokers_file="$HF_BROKER_RUN_DIR/operator-brokers.json"
+  local agent_secret operator_secret
+
+  install -d -m 0750 -o root -g hf-broker "$HF_BROKER_RUN_DIR"
+  agent_secret="$(od -An -N48 -tx1 /dev/urandom | tr -d ' \n')"
+  operator_secret="$(od -An -N48 -tx1 /dev/urandom | tr -d ' \n')"
+  printf '%s\n' "$broker_token" > "$token_file"
+  printf '%s\n' "$agent_secret" > "$agent_secret_file"
+  printf '%s\n' "$operator_secret" > "$operator_secret_file"
+  printf 'default = %s\n' "$agent_secret" > "$broker_agent_secrets"
+  printf 'mlclaw-control = %s\n' "$operator_secret" > "$broker_operator_secrets"
+  printf '{"version":1,"brokers":[{"id":"hf-broker","label":"Hugging Face","url":"http://127.0.0.1:7864","token_file":"%s"}]}\n' "$operator_secret_file" > "$operator_brokers_file"
+  chown hf-broker:hf-broker "$token_file" "$broker_agent_secrets" "$broker_operator_secrets"
+  chmod 0600 "$token_file" "$agent_secret_file" "$operator_secret_file" "$broker_agent_secrets" "$broker_operator_secrets" "$operator_brokers_file"
+
+  if [ -z "${MLCLAW_STATE_MOUNT_DIR:-}" ]; then
+    STATE_HF_TOKEN="${MLCLAW_BROKER_HF_TOKEN:-${HF_TOKEN:-${HUGGINGFACE_HUB_TOKEN:-$broker_token}}}"
+  fi
+
+  export MLCLAW_HF_BROKER_URL="http://127.0.0.1:7863"
+  export MLCLAW_HF_BROKER_AGENT_SECRET_FILE="$agent_secret_file"
+  if [ "${MLCLAW_GATEWAY_LOCATION:-}" = "local" ]; then
+    export MLCLAW_TRUSTED_HF_TOKEN_FILE="$token_file"
+  fi
+  if [ -z "${MLCLAW_OPERATOR_BROKERS_FILE:-}" ]; then
+    export MLCLAW_OPERATOR_BROKERS_FILE="$operator_brokers_file"
+  fi
+  HF_BROKER_ENABLED=1
+}
+
+restore_protected_state() {
+  install -d -m 0710 -o root -g hf-broker "$PROTECTED_STATE_DIR"
+  if [ -d "$RESTORED_PROTECTED_STATE_DIR" ]; then
+    find "$PROTECTED_STATE_DIR" -mindepth 1 -maxdepth 1 -exec rm -rf -- {} +
+    cp -a "$RESTORED_PROTECTED_STATE_DIR/." "$PROTECTED_STATE_DIR/"
+    rm -rf "$RESTORED_PROTECTED_STATE_DIR"
+  fi
+  install -d -m 0700 -o root -g root "$PROTECTED_STATE_DIR/control"
+  install -d -m 0700 -o hf-broker -g hf-broker "$HF_BROKER_STATE_DIR"
+  chown -R root:root "$PROTECTED_STATE_DIR/control"
+  chown -R hf-broker:hf-broker "$HF_BROKER_STATE_DIR"
+  chmod 0710 "$PROTECTED_STATE_DIR"
+  chmod 0700 "$PROTECTED_STATE_DIR/control" "$HF_BROKER_STATE_DIR"
+}
+
+start_hf_broker() {
+  if [ "$HF_BROKER_ENABLED" != "1" ]; then
+    return
+  fi
+
+  install -d -m 0700 -o hf-broker -g hf-broker "$HF_BROKER_STATE_DIR"
+  install -d -m 0700 -o hf-broker -g hf-broker "$HF_BROKER_STATE_DIR/grants"
+  if [ ! -e "$HF_BROKER_STATE_DIR/grants/grants.json" ]; then
+    printf '{"grants":[]}\n' > "$HF_BROKER_STATE_DIR/grants/grants.json"
+    chown hf-broker:hf-broker "$HF_BROKER_STATE_DIR/grants/grants.json"
+    chmod 0600 "$HF_BROKER_STATE_DIR/grants/grants.json"
+  fi
+  chown -R hf-broker:hf-broker "$HF_BROKER_STATE_DIR"
+  chmod 0700 "$HF_BROKER_STATE_DIR"
+
+  HF_BROKER_HF_TOKEN_FILE="$HF_BROKER_RUN_DIR/hf-token" \
+  HF_BROKER_SECRETS_FILE="$HF_BROKER_RUN_DIR/agent-secrets.conf" \
+  HF_BROKER_OPERATOR_SECRETS_FILE="$HF_BROKER_RUN_DIR/operator-secrets.conf" \
+  HF_BROKER_BIND_ADDR=127.0.0.1 \
+  HF_BROKER_PORT=7863 \
+  HF_BROKER_OPERATOR_BIND_ADDR=127.0.0.1 \
+  HF_BROKER_OPERATOR_PORT=7864 \
+  HF_BROKER_SCOPE_FILE=/app/hf-broker.scope.json \
+  HF_BROKER_STATE_DIR="$HF_BROKER_STATE_DIR" \
+  gosu hf-broker:hf-broker /usr/local/bin/hf-broker &
+  HF_BROKER_PID=$!
+
+  for _ in $(seq 1 50); do
+    if ! kill -0 "$HF_BROKER_PID" 2>/dev/null; then
+      echo "[hf-broker] process exited during startup" >&2
+      wait "$HF_BROKER_PID"
+      return 1
+    fi
+    if node -e "fetch('http://127.0.0.1:7863/healthz').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"; then
+      echo "[hf-broker] agent and operator listeners ready"
+      return
+    fi
+    sleep 0.1
+  done
+  echo "[hf-broker] startup timed out" >&2
+  kill "$HF_BROKER_PID" 2>/dev/null || true
+  return 1
+}
+
+chown_openclaw_live() {
+  chown "$OPENCLAW_IDENTITY" "$LIVE_DIR"
+  find "$LIVE_DIR" -mindepth 1 -maxdepth 1 ! -name .mlclaw-protected -exec chown -R "$OPENCLAW_IDENTITY" {} +
+}
 
 if [ "${MLCLAW_GATEWAY_DISABLED:-0}" = "1" ]; then
   echo "[mlclaw] gateway disabled"
   exit 0
 fi
 
-if [ -z "${HUGGINGFACE_HUB_TOKEN:-}" ] && [ -n "${HF_TOKEN:-}" ]; then
-  export HUGGINGFACE_HUB_TOKEN="$HF_TOKEN"
-fi
+prepare_hf_broker
+export MLCLAW_PROTECTED_STATE_DIR="$PROTECTED_STATE_DIR"
+export MLCLAW_OPENAI_CREDENTIAL_STORE_FILE="$PROTECTED_STATE_DIR/control/openai-api-key.enc"
+# The broad token and legacy Router token must not enter the control plane or
+# OpenClaw. The token is already in the broker-owned runtime file before the
+# environment is scrubbed; local bucket state sync receives a dedicated copy
+# only around trusted restore and supervisor execution.
+unset MLCLAW_BROKER_HF_TOKEN MLCLAW_ROUTER_TOKEN HF_ROUTER_TOKEN HF_TOKEN HUGGINGFACE_HUB_TOKEN
 
 # State, workspace, and config paths are ALWAYS derived from the live dir,
 # never inherited: older deployments set OPENCLAW_STATE_DIR=/data/... as Space
@@ -30,15 +152,25 @@ CONFIG_PATH="$OPENCLAW_CONFIG_PATH"
 # silently start fresh then snapshot over a bucket that still holds data).
 echo "[hf-state-sync] starting restore"
 RESTORE_TIMEOUT_SECONDS="${MLCLAW_RESTORE_TIMEOUT_SECONDS:-180}"
+node /app/hf-state-sync.js prepare-restore
 if command -v timeout >/dev/null 2>&1; then
-  timeout "${RESTORE_TIMEOUT_SECONDS}s" node /app/hf-state-sync.js restore
+  env MLCLAW_STATE_HF_TOKEN="$STATE_HF_TOKEN" timeout "${RESTORE_TIMEOUT_SECONDS}s" gosu "$OPENCLAW_IDENTITY" node /app/hf-state-sync.js restore
 else
-  node /app/hf-state-sync.js restore
+  env MLCLAW_STATE_HF_TOKEN="$STATE_HF_TOKEN" gosu "$OPENCLAW_IDENTITY" node /app/hf-state-sync.js restore
 fi
 echo "[hf-state-sync] restore complete"
+restore_protected_state
+
+if [ -n "${MLCLAW_STATE_MOUNT_DIR:-}" ]; then
+  chown root:root "$MLCLAW_STATE_MOUNT_DIR"
+  chmod 0700 "$MLCLAW_STATE_MOUNT_DIR"
+fi
 
 mkdir -p "$LIVE_DIR" "$WORKSPACE_DIR" "$STATE_DIR"
-chown -R node:node "$LIVE_DIR"
+chown_openclaw_live
+install -d -m 0710 -o root -g hf-broker "$PROTECTED_STATE_DIR"
+install -d -m 0700 -o root -g root "$PROTECTED_STATE_DIR/control"
+start_hf_broker
 
 if [ -n "${OPENCLAW_AGENT_NAME:-}" ]; then
   printf "%s\n" "$OPENCLAW_AGENT_NAME" > "$STATE_DIR/agent-name.txt"
@@ -47,17 +179,32 @@ fi
 if [ ! -f "$CONFIG_PATH" ]; then
   cp /app/openclaw.default.json "$CONFIG_PATH"
 fi
-chown -R node:node "$LIVE_DIR"
+chown_openclaw_live
+
+# Let OpenClaw create its native workspace files. The ML Claw runtime waits for
+# native onboarding to finish before adding workspace tooling; OpenClaw treats
+# any preinstalled workspace skills as evidence that onboarding already ran.
+echo "[openclaw-setup] initializing baseline workspace"
+env \
+  -u MLCLAW_CREDENTIAL_KEY \
+  -u MLCLAW_SESSION_SECRET \
+  -u SESSION_SECRET \
+  -u OAUTH_CLIENT_SECRET \
+  -u HF_TOKEN \
+  -u HUGGINGFACE_HUB_TOKEN \
+  HOME=/home/node USER=node LOGNAME=node \
+  gosu "$OPENCLAW_IDENTITY" node /app/openclaw.mjs setup --baseline --workspace "$WORKSPACE_DIR"
+echo "[openclaw-setup] baseline workspace ready"
 
 if [ -n "${OPENCLAW_MODEL:-}" ]; then
   echo "[huggingface-config] configuring selected Hugging Face model"
-  gosu node node /app/scripts/configure-huggingface-model.mjs "$CONFIG_PATH"
+  gosu "$OPENCLAW_IDENTITY" node /app/scripts/configure-huggingface-model.mjs "$CONFIG_PATH"
   echo "[huggingface-config] Hugging Face model configured"
 fi
 
 if [ -n "${TELEGRAM_BOT_TOKEN:-}" ] && [ -n "${TELEGRAM_ALLOWED_USERS:-}" ]; then
   echo "[telegram-config] configuring Telegram channel"
-  gosu node node /app/scripts/configure-telegram.mjs "$CONFIG_PATH" "$TELEGRAM_ALLOWED_USERS"
+  gosu "$OPENCLAW_IDENTITY" node /app/scripts/configure-telegram.mjs "$CONFIG_PATH" "$TELEGRAM_ALLOWED_USERS"
   echo "[telegram-config] Telegram channel configured"
 fi
 
@@ -73,7 +220,7 @@ if [ -n "${TELEGRAM_BOT_TOKEN:-}" ] && [ "${OPENCLAW_TELEGRAM_CONNECTIVITY_PROBE
     if curl -fsS --connect-timeout 20 --max-time 30 "${PROBE_PROXY[@]}" \
       "${PROBE_API_ROOT}/bot${TELEGRAM_BOT_TOKEN}/getMe" \
       -o "$PROBE_OUT"; then
-      gosu node node /app/scripts/report-telegram-probe.mjs "$PROBE_OUT" || true
+      gosu "$OPENCLAW_IDENTITY" node /app/scripts/report-telegram-probe.mjs "$PROBE_OUT" || true
     else
       echo "[telegram-probe] curl getMe failed"
     fi
@@ -83,9 +230,12 @@ if [ -n "${TELEGRAM_BOT_TOKEN:-}" ] && [ "${OPENCLAW_TELEGRAM_CONNECTIVITY_PROBE
   fi
 fi
 
-echo "[hf-tooling] seeding baseline Hugging Face tooling"
-node /app/hf-tooling-seed.js
-echo "[hf-tooling] baseline Hugging Face tooling ready"
-
-chown -R node:node "$LIVE_DIR"
-exec gosu node node /app/hf-state-sync.js supervise -- node /app/mlclaw-space-runtime.js
+chown_openclaw_live
+# The wrapper remains the trusted root supervisor so its OAuth credentials and
+# process environment are not readable by the unprivileged OpenClaw child. The
+# state supervisor stages live files in a separate secret-free node process;
+# only the trusted parent uploads the resulting archive.
+if [ -n "$STATE_HF_TOKEN" ]; then
+  export MLCLAW_STATE_HF_TOKEN="$STATE_HF_TOKEN"
+fi
+exec node /app/hf-state-sync.js supervise -- node /app/mlclaw-space-runtime.js

package/hf-broker.scope.json

@@ -0,0 +1,38 @@
+{
+  "rules": [
+    {
+      "id": "mlclaw-read-repositories",
+      "effect": "allow",
+      "clients": ["default"],
+      "operations": ["repo.list", "repo.metadata.read", "repo.contents.read", "git.fetch"],
+      "targets": [
+        {"kind": "repo", "type": "*", "owner": "*", "name": "*"}
+      ]
+    },
+    {
+      "id": "mlclaw-append-repositories",
+      "effect": "allow",
+      "clients": ["default"],
+      "operations": ["git.push.append"],
+      "targets": [
+        {"kind": "repo", "type": "*", "owner": "*", "name": "*"}
+      ]
+    },
+    {
+      "id": "mlclaw-request-protected-repository-writes",
+      "effect": "request",
+      "clients": ["default"],
+      "operations": ["git.push.force", "git.ref.delete", "git.tag.update"],
+      "targets": [
+        {"kind": "repo", "type": "*", "owner": "*", "name": "*"}
+      ],
+      "grant_policy": {
+        "default_minutes": 5,
+        "max_minutes": 60,
+        "request_ttl_minutes": 15,
+        "default_max_uses": 1,
+        "max_uses": 3
+      }
+    }
+  ]
+}

package/package.json

@@ -1,9 +1,11 @@
 {
   "name": "mlclaw",
-  "version": "0.2.3",
+  "version": "0.3.1",
   "license": "MIT",
   "config": {
-    "openclawVersion": "2026.7.1-beta.2",
+    "openclawVersion": "2026.7.1-beta.5",
+    "brokerkitVersion": "fcfc5f2304436d952b18e7c9583bb378d1952776",
+    "brokerkitPluginVersion": "0.1.0",
     "runtimeImageRepository": "ghcr.io/osolmaz/mlclaw"
   },
   "repository": {
@@ -28,6 +30,7 @@
     "dist/mlclaw-space-runtime.js",
     "Dockerfile",
     "entrypoint.sh",
+    "hf-broker.scope.json",
     "mlclaw.ps1",
     "mlclaw.sh",
     "LICENSE",
@@ -53,6 +56,14 @@
     "pack:check": "node scripts/check-package.mjs",
     "prepack": "npm run build",
     "check:secrets": "node scripts/check-secrets.mjs",
+    "format": "prettier --check eslint.config.mjs vitest.config.ts vitest.stryker.config.ts package.json README.md src/hf-state-sync/archive.ts src/hf-state-sync/cli.ts src/hf-state-sync/paths.ts src/hf-state-sync/prepare.ts src/hf-state-sync/stage-worker.ts src/hf-state-sync/supervise.ts src/mlclaw-space-runtime/delegated-brokerkit.ts src/mlclaw-space-runtime/operator-brokers.ts src/mlclaw-space-runtime/openclaw-config.ts src/mlclaw-space-runtime/app.ts src/mlclaw-space-runtime/config.ts src/mlclaw-space-runtime/openai-credentials.ts src/mlclaw-space-runtime/server.ts src/mlclaw-space-runtime/shell.ts src/mlclaw-control-ui/src/main.tsx src/mlclaw-control-ui/src/styles.css src/mlclaw-control-ui/src/components/ui/utils.ts src/mlclaw/git.ts test/hf-state-sync.archive.test.ts test/hf-state-sync.roundtrip.test.ts test/hf-state-sync.supervise.test.ts test/mlclaw.bundle.test.ts test/mlclaw.delegated-brokerkit.test.ts test/mlclaw.generate-space.test.ts test/mlclaw.operator-brokers.test.ts test/mlclaw.runtime-image.test.ts test/mlclaw.space-runtime.test.ts docs/operator-brokers-config.md",
+    "format:write": "prettier --write eslint.config.mjs vitest.config.ts vitest.stryker.config.ts package.json README.md src/hf-state-sync/archive.ts src/hf-state-sync/cli.ts src/hf-state-sync/paths.ts src/hf-state-sync/prepare.ts src/hf-state-sync/stage-worker.ts src/hf-state-sync/supervise.ts src/mlclaw-space-runtime/delegated-brokerkit.ts src/mlclaw-space-runtime/operator-brokers.ts src/mlclaw-space-runtime/openclaw-config.ts src/mlclaw-space-runtime/app.ts src/mlclaw-space-runtime/config.ts src/mlclaw-space-runtime/openai-credentials.ts src/mlclaw-space-runtime/server.ts src/mlclaw-space-runtime/shell.ts src/mlclaw-control-ui/src/main.tsx src/mlclaw-control-ui/src/styles.css src/mlclaw-control-ui/src/components/ui/utils.ts src/mlclaw/git.ts test/hf-state-sync.archive.test.ts test/hf-state-sync.roundtrip.test.ts test/hf-state-sync.supervise.test.ts test/mlclaw.bundle.test.ts test/mlclaw.delegated-brokerkit.test.ts test/mlclaw.generate-space.test.ts test/mlclaw.operator-brokers.test.ts test/mlclaw.runtime-image.test.ts test/mlclaw.space-runtime.test.ts docs/operator-brokers-config.md",
+    "lint": "eslint --max-warnings 0 src/mlclaw-space-runtime/delegated-brokerkit.ts src/mlclaw-space-runtime/operator-brokers.ts src/mlclaw-space-runtime/openclaw-config.ts",
+    "coverage": "vitest run --coverage",
+    "dry": "slophammer-ts dry .",
+    "mutate": "stryker run --dryRunOnly",
+    "slophammer": "slophammer-ts check .",
+    "check": "npm run format && npm run lint && npm run typecheck && npm test && npm run coverage && npm run build && npm run check:secrets && npm run pack:check && npm run dry && npm run slophammer",
     "test": "vitest run",
     "typecheck": "tsc --noEmit"
   },
@@ -62,18 +73,31 @@
     "@huggingface/xetchunk-wasm": "^0.0.6",
     "commander": "^14.0.3",
     "hono": "^4.12.28",
+    "lucide-react": "^0.468.0",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
     "skillflag": "^0.2.0",
     "zod": "^3.24.0"
   },
   "devDependencies": {
+    "@eslint/js": "^9.39.5",
+    "@stryker-mutator/core": "^9.6.1",
+    "@stryker-mutator/typescript-checker": "^9.6.1",
+    "@stryker-mutator/vitest-runner": "^9.6.1",
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.1",
     "@types/node": "^24.0.0",
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^5.2.0",
+    "@vitest/coverage-v8": "^3.2.7",
     "esbuild": "^0.25.0",
+    "eslint": "^9.39.5",
+    "jsdom": "^29.1.1",
+    "prettier": "^3.9.5",
+    "slophammer-ts": "^0.3.0",
     "typescript": "^5.7.0",
+    "typescript-eslint": "^8.63.0",
     "vite": "^7.3.6",
     "vitest": "^3.0.0"
   }

package/space/README.md

@@ -7,10 +7,19 @@ sdk: docker
 app_port: 7860
 hf_oauth: true
 hf_oauth_expiration_minutes: 43200
+hf_oauth_scopes:
+  - read-mcp
+  - read-repos
+  - contribute-repos
+  - write-repos
+  - manage-repos
+  - inference-api
+  - jobs
 pinned: false
 secrets:
-  - HF_TOKEN
+  - MLCLAW_ROUTER_TOKEN
   - MLCLAW_SESSION_SECRET
+  - MLCLAW_CREDENTIAL_KEY
   - OPENAI_API_KEY
 ---
 
@@ -60,9 +69,10 @@ OpenClaw trusted-proxy auth. The browser never receives an OpenClaw gateway
 token.
 
 Durable state lives in a private Hugging Face Storage Bucket configured by
-`OPENCLAW_HF_STATE_BUCKET`. The bucket is not mounted as a live filesystem;
-`hf-state-sync` restores verified snapshots on boot and uploads new snapshots
-during runtime and shutdown.
+`OPENCLAW_HF_STATE_BUCKET` and mounted at `/data/mlclaw-state`. The mount is
+only the snapshot store; live SQLite and workspace state stay on local
+container disk. `hf-state-sync` restores verified snapshots on boot and uploads
+new snapshots during runtime and shutdown.
 
 Manage an existing deployment from your machine with:
 

package/src/hf-state-sync/archive.ts

@@ -19,6 +19,7 @@ const STATE_EXCLUDED_SUFFIXES = [".log"];
 // are replaced by VACUUM INTO copies during staging.
 const SIDECAR_SUFFIXES = [".sqlite-wal", ".sqlite-shm"];
 const STATE_DIR_NAME = ".openclaw";
+export const PROTECTED_STATE_DIR_NAME = ".mlclaw-protected";
 
 function isExcluded(name: string, inStateDir: boolean): boolean {
   if (SIDECAR_SUFFIXES.some((suffix) => name.endsWith(suffix))) {
@@ -27,10 +28,7 @@ function isExcluded(name: string, inStateDir: boolean): boolean {
   if (!inStateDir) {
     return false;
   }
-  return (
-    STATE_EXCLUDED_NAMES.has(name) ||
-    STATE_EXCLUDED_SUFFIXES.some((suffix) => name.endsWith(suffix))
-  );
+  return STATE_EXCLUDED_NAMES.has(name) || STATE_EXCLUDED_SUFFIXES.some((suffix) => name.endsWith(suffix));
 }
 
 /**
@@ -46,11 +44,15 @@ async function copyTreeFiltered(params: {
   rootDir: string;
   inStateDir: boolean;
   depth: number;
+  excludeProtectedState: boolean;
 }): Promise<void> {
-  const { sourceDir, destDir, databases, rootDir, inStateDir, depth } = params;
+  const { sourceDir, destDir, databases, rootDir, inStateDir, depth, excludeProtectedState } = params;
   await fs.mkdir(destDir, { recursive: true });
   const entries = await fs.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;
     }
@@ -66,6 +68,7 @@ async function copyTreeFiltered(params: {
         // project may legitimately contain its own .openclaw directory.
         inStateDir: inStateDir || (depth === 0 && entry.name === STATE_DIR_NAME),
         depth: depth + 1,
+        excludeProtectedState,
       });
     } else if (entry.isFile()) {
       if (entry.name.endsWith(".sqlite")) {
@@ -82,14 +85,17 @@ async function copyTreeFiltered(params: {
 }
 
 export type StageResult =
-  | { kind: "staged"; databases: string[] }
-  | { kind: "corrupt-database"; database: string; detail: string };
+  { kind: "staged"; databases: string[] } | { kind: "corrupt-database"; database: string; detail: string };
 
 /**
  * Stage a snapshot of the live dir: filtered file copy plus a consistent,
  * integrity-checked VACUUM INTO copy of every live SQLite DB.
  */
-export async function stageLiveDir(liveDir: string, stagingDir: string): Promise<StageResult> {
+export async function stageLiveDir(
+  liveDir: string,
+  stagingDir: string,
+  options: { excludeProtectedState?: boolean } = {},
+): Promise<StageResult> {
   const databases: string[] = [];
   await copyTreeFiltered({
     sourceDir: liveDir,
@@ -98,6 +104,7 @@ export async function stageLiveDir(liveDir: string, stagingDir: string): Promise
     rootDir: liveDir,
     inStateDir: false,
     depth: 0,
+    excludeProtectedState: options.excludeProtectedState ?? false,
   });
   for (const relative of databases) {
     const staged = path.join(stagingDir, relative);

package/src/hf-state-sync/cli.ts

@@ -1,28 +1,49 @@
-import { createHfBucketHub } from "./hub.js";
+import { createHfBucketHub, createMountedBucketHub } from "./hub.js";
 import type { BucketHub } from "./hub.js";
-import { log, logError, resolveSyncConfig } from "./paths.js";
+import { type SyncConfig, log, logError, resolveSyncConfig } from "./paths.js";
 import { runRestore } from "./restore.js";
+import { prepareRestore } from "./prepare.js";
 import { runSnapshot } from "./snapshot.js";
 import { supervise } from "./supervise.js";
+import { runStageWorker, trustedStageArchive } from "./stage-worker.js";
 
 const USAGE = `usage:
   hf-state-sync restore
   hf-state-sync snapshot
   hf-state-sync supervise -- <command> [args...]`;
 
-function makeHub(bucket: string | null): BucketHub | null {
-  return bucket ? createHfBucketHub({ bucket }) : null;
+function makeHub(config: SyncConfig): BucketHub | null {
+  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: string[]): Promise<number> {
+  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;
@@ -48,7 +69,13 @@ async function main(argv: string[]): Promise<number> {
       if (!hub) {
         return 1;
       }
-      const outcome = await runSnapshot({ config, hub, bootTime: new Date().toISOString() });
+      const stageArchive = trustedStageArchive(config, process.argv[1]);
+      const outcome = await runSnapshot({
+        config,
+        hub,
+        bootTime: new Date().toISOString(),
+        ...(stageArchive ? { stageArchive } : {}),
+      });
       if (outcome.kind === "failed") {
         logError(outcome.detail);
         return 1;

package/src/hf-state-sync/hub.ts

@@ -1,4 +1,5 @@
 import fs from "node:fs/promises";
+import path from "node:path";
 import { BucketClient, BucketHttpError } from "../hf-bucket-client/client.js";
 
 /**
@@ -13,7 +14,8 @@ export interface BucketHub {
 
 /**
  * BucketHub backed by the shared TypeScript Storage Bucket client. Auth comes
- * from HF_TOKEN in Space Secrets.
+ * from HF_TOKEN in the local gateway environment or an explicit caller token.
+ * Space gateway mode should prefer createMountedBucketHub instead.
  */
 export function createHfBucketHub(params: { bucket: string; token?: string }): BucketHub {
   const token = params.token ?? process.env.HF_TOKEN;
@@ -79,3 +81,82 @@ export function createHfBucketHub(params: { bucket: string; token?: string }): B
     },
   };
 }
+
+/** BucketHub backed by a read-write Storage Bucket volume mounted in the Space. */
+export function createMountedBucketHub(params: { mountDir: string }): BucketHub {
+  const root = path.resolve(params.mountDir);
+  const assertMountRoot = async (): Promise<void> => {
+    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 = (remotePath: string): string => {
+    const normalized = remotePath.replace(/^\/+/, "");
+    const resolved = path.resolve(root, normalized);
+    if (resolved !== root && !resolved.startsWith(`${root}${path.sep}`)) {
+      throw new Error(`invalid bucket path outside mount: ${remotePath}`);
+    }
+    return resolved;
+  };
+
+  return {
+    async download(remotePath, localPath) {
+      await assertMountRoot();
+      const source = localPathFor(remotePath);
+      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 ${remotePath}: ${message}`);
+      }
+    },
+    async upload(localPath, remotePath) {
+      await assertMountRoot();
+      const target = localPathFor(remotePath);
+      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);
+        // The trusted supervisor uploads as root, while restore runs as the
+        // unprivileged OpenClaw user. State objects contain only snapshots and
+        // runtime metadata, so keep them world-readable but root-writable.
+        await fs.chmod(tmp, 0o644);
+        await fs.rename(tmp, target);
+      } catch (err) {
+        await fs.rm(tmp, { force: true }).catch(() => undefined);
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`mounted bucket upload failed for ${remotePath}: ${message}`);
+      }
+    },
+    async delete(remotePaths) {
+      await assertMountRoot();
+      for (const remotePath of remotePaths) {
+        try {
+          await fs.rm(localPathFor(remotePath), { force: true });
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          console.error(`[hf-state-sync] prune failed for ${remotePath}: ${message}`);
+        }
+      }
+    },
+  };
+}
+
+function isNotFound(err: unknown): boolean {
+  return err instanceof Error && "code" in err && err.code === "ENOENT";
+}