mlclaw 0.4.0 → 0.4.1

package/.agents/skills/mlclaw/SKILL.md

@@ -59,8 +59,9 @@ Collect or confirm:
 
 - Hugging Face token access: `HF_TOKEN`, `HF_TOKEN_PATH`, `$HF_HOME/token`, or
   `hf auth login`.
-- The active Hugging Face token is installed as the broker-owned
-  `MLCLAW_BROKER_HF_TOKEN`; legacy dedicated Router tokens remain supported.
+- A separate fine-grained Hugging Face token is installed as the broker-owned
+  `MLCLAW_BROKER_HF_TOKEN`; the active CLI login is used only to provision
+  resources. Legacy dedicated Router tokens remain supported for inference.
 - Agent name, unless a Telegram bot token is supplied and the user wants the
   name derived from the bot username.
 - Gateway mode:

package/Dockerfile

@@ -1,8 +1,8 @@
 ARG OPENCLAW_VERSION=2026.7.1
 ARG OPENCLAW_BASE_IMAGE=ghcr.io/openclaw/openclaw:${OPENCLAW_VERSION}
 ARG BROKERKIT_PLUGIN_VERSION=0.2.1
-ARG BROKERKIT_VERSION=hf-broker/v0.1.0
-ARG MLCLAW_RUNTIME_IMAGE=ghcr.io/osolmaz/mlclaw:0.4.0-openclaw-2026.7.1
+ARG BROKERKIT_VERSION=hf-broker/v0.2.0
+ARG MLCLAW_RUNTIME_IMAGE=ghcr.io/osolmaz/mlclaw:0.4.1-openclaw-2026.7.1
 
 FROM golang:1.26.5-bookworm AS hf-broker-build
 ARG BROKERKIT_VERSION

package/README.md

@@ -47,12 +47,23 @@ flow, and resumes after sign-in. Non-interactive runs never install software and
 still require a token up front. You never paste that token into someone else's
 app; the bootstrapper runs locally.
 
-ML Claw places the active Hugging Face token behind an in-container HF Broker.
-The broker owns the real token; OpenClaw receives only a separate agent
-credential that can call the broker's typed, policy-checked routes. It cannot
-read the token or use the admin-only operator API. Existing dedicated inference
-tokens remain supported through `MLCLAW_ROUTER_TOKEN`, `HF_ROUTER_TOKEN`, or
-`--router-token-file` during migration.
+The `hf` CLI login is a provisioning credential: ML Claw uses it to create and
+configure resources owned by your account. HF Broker uses a separate, durable
+fine-grained credential whose required permissions are versioned by BrokerKit.
+Interactive bootstrap opens Hugging Face's token form with those fields
+preselected, then accepts the new token through a hidden local prompt. Creating
+or replacing this credential never changes the active `hf` CLI login. For
+automation, pass a `0600` file through `--broker-hf-token-file`; ML Claw does
+not accept the token as a command-line value.
+
+The broker owns the selected credential; OpenClaw receives only a separate
+agent credential that can call the broker's typed, policy-checked routes. It
+cannot read the token or use the admin-only operator API. Rerunning bootstrap
+reuses a healthy saved broker credential without reopening the form. A missing,
+invalid, wrong-account, or under-scoped credential must be repaired before ML
+Claw continues; it never silently substitutes the active CLI login. Existing
+dedicated inference tokens remain supported through `MLCLAW_ROUTER_TOKEN`,
+`HF_ROUTER_TOKEN`, or `--router-token-file` during migration.
 
 ## Default Flow
 
@@ -254,9 +265,25 @@ It never reads secret values and never modifies bucket contents.
 
 `mlclaw update` also refreshes the generated Space Dockerfile and runtime
 metadata, so older Spaces can move to the current implementation without
-recreating their bucket. For legacy deployments, ML Claw installs the active
-local Hugging Face credential as `MLCLAW_BROKER_HF_TOKEN`, removes stale direct
-token secrets, and restarts the Space with the broker boundary enabled.
+recreating their bucket. It does not promote the active Hugging Face CLI login
+into a runtime secret. Recover or repair the dedicated broker credential first
+when updating a deployment that predates this boundary.
+
+Inspect or replace the dedicated credential with:
+
+```bash
+mlclaw credentials status mlclaw
+mlclaw credentials repair mlclaw
+mlclaw credentials repair mlclaw --broker-hf-token-file ~/secrets/mlclaw-broker.env
+```
+
+`status` performs a read-only verification and prints the account, BrokerKit
+profile, verification time, and a short SHA-256 fingerprint, never the token.
+`repair` validates the replacement before changing anything. Local running
+gateways are replaced transactionally and rolled back on failure; stopped local
+gateways stay stopped. Space repair uses the active CLI login only to install
+the already-validated secret and restart the Space, restoring the previous
+secret and local metadata if the operation fails.
 
 ## Browser Settings
 

package/dist/mlclaw-space-runtime.js

@@ -8584,6 +8584,7 @@ function remainingUpstreamTimeout(deadline) {
 // src/mlclaw-space-runtime/openclaw-config.ts
 var BROKER_MCP_CONNECTION_TIMEOUT_MS = 1e4;
 var BROKER_MCP_REQUEST_TIMEOUT_MS = 45e3;
+var AUTOMATIC_SESSION_RESET_DISABLED_MINUTES = 2147483647;
 async function configureOpenClawGateway(config2) {
   const raw2 = await fs.readFile(config2.openclawConfigPath, "utf8");
   const openclawConfig = JSON.parse(raw2);
@@ -8607,6 +8608,7 @@ async function configureOpenClawGateway(config2) {
     embedSandbox: "scripts"
   };
   configureOpenClawModels(openclawConfig, config2);
+  disableAutomaticSessionResets(openclawConfig);
   configureManagedMcpServers(openclawConfig, config2);
   configureBrokerMcpServer(openclawConfig, config2);
   configureBrokerKitPlugin(openclawConfig, config2);
@@ -8618,6 +8620,18 @@ async function configureOpenClawGateway(config2) {
     await fs.chown(config2.openclawConfigPath, config2.openclawUid, config2.openclawGid);
   }
 }
+function disableAutomaticSessionResets(openclawConfig) {
+  const session = object(openclawConfig, "session");
+  session.reset = {
+    mode: "idle",
+    idleMinutes: AUTOMATIC_SESSION_RESET_DISABLED_MINUTES
+  };
+  delete session.idleMinutes;
+  delete session.resetByType;
+  delete session.resetByChannel;
+  const maintenance = object(session, "maintenance");
+  maintenance.resetArchiveRetention = false;
+}
 function configureBrokerMcpServer(openclawConfig, config2) {
   const servers = object(object(openclawConfig, "mcp"), "servers");
   if (!config2.brokerAgentUrl || !config2.brokerAgentSecretFile) {

package/dist/mlclaw.mjs

@@ -8956,7 +8956,7 @@ import fs16 from "node:fs/promises";
 import { realpathSync } from "node:fs";
 import os8 from "node:os";
 import process4 from "node:process";
-import { createHash as createHash3, randomBytes, randomUUID as randomUUID2 } from "node:crypto";
+import { createHash as createHash4, randomBytes, randomUUID as randomUUID2 } from "node:crypto";
 import { pathToFileURL as pathToFileURL2 } from "node:url";
 import { setTimeout as delay2 } from "node:timers/promises";
 
@@ -10056,10 +10056,10 @@ function parsePodmanConnections(raw) {
     if (!value || typeof value !== "object") {
       return [];
     }
-    const record = value;
-    const name = record.Name ?? record.name;
-    const uri = record.URI ?? record.uri;
-    const isDefault = record.Default ?? record.default;
+    const record2 = value;
+    const name = record2.Name ?? record2.name;
+    const uri = record2.URI ?? record2.uri;
+    const isDefault = record2.Default ?? record2.default;
     if (typeof name !== "string" || !name.trim()) {
       return [];
     }
@@ -14900,7 +14900,7 @@ var HubApi = class {
     return new BucketClient({ bucket, accessToken: this.token, hubUrl: this.hubUrl, fetch: this.fetchImpl });
   }
   async whoami() {
-    return await this.requestJson("/api/whoami-v2");
+    return parseHubIdentity(await this.requestJson("/api/whoami-v2"));
   }
   async createBucket(bucketId, privateBucket = true) {
     const [namespace, name] = splitRepoId(bucketId);
@@ -15285,6 +15285,55 @@ var HubApi = class {
     return response;
   }
 };
+function parseHubIdentity(value) {
+  const root = record(value);
+  const name = stringValue(root.name);
+  if (!name) {
+    throw new Error("Hugging Face identity response omitted the account name");
+  }
+  const organizations = Array.isArray(root.orgs) ? root.orgs.map((entry) => stringValue(record(entry).name)).filter((entry) => Boolean(entry)) : [];
+  const auth = record(root.auth);
+  const accessToken = record(auth.accessToken);
+  const fineGrained = record(accessToken.fineGrained);
+  const authType = stringValue(auth.type);
+  const accessTokenRole = stringValue(accessToken.role);
+  const scoped = Array.isArray(fineGrained.scoped) ? fineGrained.scoped.map(parseFineGrainedScope).filter((entry) => Boolean(entry)) : [];
+  const global2 = stringArray(fineGrained.global);
+  const canReadGatedRepos = fineGrained.canReadGatedRepos === true;
+  const parsedAccessToken = {
+    ...accessTokenRole ? { role: accessTokenRole } : {},
+    ...Object.keys(fineGrained).length > 0 ? { fineGrained: { global: global2, scoped, canReadGatedRepos } } : {}
+  };
+  const parsedAuth = {
+    ...authType ? { type: authType } : {},
+    ...Object.keys(parsedAccessToken).length > 0 ? { accessToken: parsedAccessToken } : {}
+  };
+  return {
+    name,
+    organizations: [...new Set(organizations)].sort(),
+    ...Object.keys(parsedAuth).length > 0 ? { auth: parsedAuth } : {}
+  };
+}
+function parseFineGrainedScope(value) {
+  const scope = record(value);
+  const entity = record(scope.entity);
+  const type = stringValue(entity.type);
+  if (!type) return void 0;
+  const name = stringValue(entity.name);
+  return {
+    entity: { type, ...name ? { name } : {} },
+    permissions: stringArray(scope.permissions)
+  };
+}
+function record(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function stringValue(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : void 0;
+}
+function stringArray(value) {
+  return Array.isArray(value) ? [...new Set(value.filter((entry) => typeof entry === "string" && Boolean(entry.trim())))].map((entry) => entry.trim()).sort() : [];
+}
 function splitRepoId(repoId) {
   const parts = repoId.split("/");
   if (parts.length !== 2 || !parts[0] || !parts[1]) {
@@ -15327,7 +15376,7 @@ import path13 from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 var DEFAULT_OPENCLAW_VERSION = "2026.7.1";
 var DEFAULT_BROKERKIT_PLUGIN_VERSION = "0.2.1";
-var DEFAULT_BROKERKIT_VERSION = "hf-broker/v0.1.0";
+var DEFAULT_BROKERKIT_VERSION = "hf-broker/v0.2.0";
 var DEFAULT_RUNTIME_IMAGE_REPOSITORY = "ghcr.io/osolmaz/mlclaw";
 var PACKAGE_METADATA = readPackageMetadata();
 var PACKAGE_VERSION = packageString("version", "unknown");
@@ -16178,15 +16227,15 @@ var makeIssue = (params) => {
       message: issueData.message
     };
   }
-  let errorMessage = "";
+  let errorMessage2 = "";
   const maps = errorMaps.filter((m2) => !!m2).slice().reverse();
   for (const map of maps) {
-    errorMessage = map(fullIssue, { data, defaultError: errorMessage }).message;
+    errorMessage2 = map(fullIssue, { data, defaultError: errorMessage2 }).message;
   }
   return {
     ...issueData,
     path: fullPath,
-    message: errorMessage
+    message: errorMessage2
   };
 };
 var EMPTY_PATH = [];
@@ -19791,6 +19840,12 @@ var manifestFields = {
   gatewayLocation: external_exports.enum(["local", "space"]),
   model: external_exports.string().min(1).max(512),
   runtimeImage: external_exports.string().min(1).max(1024),
+  brokerCredential: external_exports.object({
+    profileId: external_exports.literal("hf-broker-complete-v1"),
+    account: external_exports.string().min(1).max(128),
+    fingerprintSha256: external_exports.string().regex(/^[a-f0-9]{64}$/),
+    verifiedAt: external_exports.string().datetime()
+  }).strict().optional(),
   credentialKeySha256: external_exports.string().regex(/^[a-f0-9]{64}$/).optional(),
   tailscaleMode: external_exports.enum(["off", "direct", "serve"]).optional(),
   spaceVisibility: external_exports.enum(["private", "public"]).optional(),
@@ -20279,6 +20334,165 @@ function delay(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+// src/mlclaw/hf-broker-credential.ts
+import { createHash as createHash3 } from "node:crypto";
+
+// src/mlclaw/hf-broker-credential-requirements.json
+var hf_broker_credential_requirements_default = {
+  version: 1,
+  profile_id: "hf-broker-complete-v1",
+  token_form_url: "https://huggingface.co/settings/tokens/new",
+  token_type: "fineGrained",
+  requires_gated_repositories: true,
+  personal_permissions: [
+    "collection.read",
+    "collection.write",
+    "discussion.write",
+    "inference.endpoints.infer.write",
+    "inference.endpoints.write",
+    "inference.serverless.write",
+    "job.write",
+    "repo.access.read",
+    "repo.content.read",
+    "repo.write",
+    "resourceGroup.write",
+    "sql-console.embed.write",
+    "user.billing.read",
+    "user.mcp.read",
+    "user.notifications.read",
+    "user.notifications.write",
+    "user.papers.write",
+    "user.preferences.write",
+    "user.settings.notifications.write",
+    "user.social.likes.write",
+    "user.webhooks.read",
+    "user.webhooks.write"
+  ],
+  global_permissions: [
+    "discussion.write",
+    "post.write"
+  ],
+  organization_permissions: [
+    "collection.read",
+    "collection.write",
+    "discussion.write",
+    "inference.endpoints.infer.write",
+    "inference.endpoints.write",
+    "inference.serverless.write",
+    "job.write",
+    "org.auditLog.write",
+    "org.billing.read",
+    "org.members.read",
+    "org.members.write",
+    "org.networkSecurity.read",
+    "org.networkSecurity.write",
+    "org.read",
+    "org.repos.read",
+    "org.serviceAccounts.read",
+    "org.serviceAccounts.write",
+    "org.write",
+    "repo.access.read",
+    "repo.content.read",
+    "repo.write",
+    "resourceGroup.write",
+    "sql-console.embed.write"
+  ]
+};
+
+// src/mlclaw/hf-broker-credential.ts
+var permissionListSchema = external_exports.array(external_exports.string().min(1)).min(1).superRefine((permissions, context) => {
+  if (permissions.some((permission) => permission !== permission.trim())) {
+    context.addIssue({ code: external_exports.ZodIssueCode.custom, message: "permissions must not contain outer whitespace" });
+  }
+  if (new Set(permissions).size !== permissions.length) {
+    context.addIssue({ code: external_exports.ZodIssueCode.custom, message: "permissions must be unique" });
+  }
+  if (permissions.some((permission, index) => index > 0 && permission < permissions[index - 1])) {
+    context.addIssue({ code: external_exports.ZodIssueCode.custom, message: "permissions must be sorted" });
+  }
+});
+var profileSchema = external_exports.object({
+  version: external_exports.literal(1),
+  profile_id: external_exports.literal("hf-broker-complete-v1"),
+  token_form_url: external_exports.literal("https://huggingface.co/settings/tokens/new"),
+  token_type: external_exports.literal("fineGrained"),
+  requires_gated_repositories: external_exports.literal(true),
+  personal_permissions: permissionListSchema,
+  global_permissions: permissionListSchema,
+  organization_permissions: permissionListSchema
+}).strict();
+var BROKER_CREDENTIAL_PROFILE = Object.freeze(profileSchema.parse(hf_broker_credential_requirements_default));
+var HF_TOKEN_CREATE_URL = BROKER_CREDENTIAL_PROFILE.token_form_url;
+var BROKER_PERSONAL_PERMISSIONS = BROKER_CREDENTIAL_PROFILE.personal_permissions;
+var BROKER_GLOBAL_PERMISSIONS = BROKER_CREDENTIAL_PROFILE.global_permissions;
+var BROKER_ORGANIZATION_PERMISSIONS = BROKER_CREDENTIAL_PROFILE.organization_permissions;
+function buildBrokerTokenUrl(owner, accountName) {
+  const url = new URL(HF_TOKEN_CREATE_URL);
+  url.searchParams.set("tokenType", BROKER_CREDENTIAL_PROFILE.token_type);
+  for (const permission of BROKER_PERSONAL_PERMISSIONS) {
+    url.searchParams.append("ownUserPermissions", permission);
+  }
+  for (const permission of BROKER_GLOBAL_PERMISSIONS) {
+    url.searchParams.append("globalPermissions", permission);
+  }
+  url.searchParams.set("canReadGatedRepos", String(BROKER_CREDENTIAL_PROFILE.requires_gated_repositories));
+  if (owner !== accountName) {
+    url.searchParams.append("orgs", owner);
+    for (const permission of BROKER_ORGANIZATION_PERMISSIONS) {
+      url.searchParams.append("orgPermissions", permission);
+    }
+  }
+  return url.toString();
+}
+function assessBrokerCredential(identity, owner) {
+  const accessToken = identity.auth?.accessToken;
+  if (accessToken?.role !== BROKER_CREDENTIAL_PROFILE.token_type) {
+    return {
+      status: "unsupported",
+      reason: "HF Broker requires a dedicated fine-grained Hugging Face token"
+    };
+  }
+  if (!accessToken.fineGrained) {
+    return {
+      status: "unsupported",
+      reason: "Hugging Face omitted this fine-grained token's permission details"
+    };
+  }
+  const personalAvailable = new Set(scopedPermissions(accessToken.fineGrained.scoped, "user", identity.name));
+  const globalAvailable = new Set(accessToken.fineGrained.global);
+  const missing = BROKER_PERSONAL_PERMISSIONS.filter((permission) => !personalAvailable.has(permission));
+  missing.push(
+    ...BROKER_GLOBAL_PERMISSIONS.filter((permission) => !globalAvailable.has(permission)).map(
+      (permission) => `global:${permission}`
+    )
+  );
+  if (!accessToken.fineGrained.canReadGatedRepos) {
+    missing.push("canReadGatedRepos");
+  }
+  if (owner !== identity.name) {
+    const organizationAvailable = new Set(scopedPermissions(accessToken.fineGrained.scoped, "org", owner));
+    missing.push(
+      ...BROKER_ORGANIZATION_PERMISSIONS.filter((permission) => !organizationAvailable.has(permission)).map(
+        (permission) => `org:${permission}`
+      )
+    );
+  }
+  missing.sort();
+  return missing.length === 0 ? { status: "sufficient" } : { status: "insufficient", missing };
+}
+function brokerCredentialMetadata(token, identity, verifiedAt) {
+  return {
+    profileId: BROKER_CREDENTIAL_PROFILE.profile_id,
+    account: identity.name,
+    fingerprintSha256: createHash3("sha256").update(token).digest("hex"),
+    verifiedAt: verifiedAt.toISOString()
+  };
+}
+function scopedPermissions(scopes, type, name) {
+  if (!Array.isArray(scopes)) return [];
+  return scopes.filter((scope) => scope.entity.type === type && (!scope.entity.name || scope.entity.name === name)).flatMap((scope) => scope.permissions);
+}
+
 // src/mlclaw/tailscale.ts
 import { execFile as execFile3 } from "node:child_process";
 import { promisify as promisify3 } from "node:util";
@@ -20351,7 +20565,7 @@ function parseTailscaleStatus(value) {
     return { ready: false, reason: "Tailscale returned an invalid status" };
   }
   if (status.BackendState !== "Running") {
-    return { ready: false, reason: `Tailscale is ${stringValue(status.BackendState) ?? "not running"}` };
+    return { ready: false, reason: `Tailscale is ${stringValue2(status.BackendState) ?? "not running"}` };
   }
   const self = recordValue(status.Self);
   if (self?.Online === false) {
@@ -20361,8 +20575,8 @@ function parseTailscaleStatus(value) {
     (candidate) => typeof candidate === "string" && isTailscaleIpv4(candidate)
   );
   if (typeof ipv4 !== "string") return { ready: false, reason: "Tailscale IPv4 address is unavailable" };
-  const dnsName = normalizeTailscaleDnsName(stringValue(self?.DNSName));
-  const tailnet = stringValue(recordValue(status.CurrentTailnet)?.Name);
+  const dnsName = normalizeTailscaleDnsName(stringValue2(self?.DNSName));
+  const tailnet = stringValue2(recordValue(status.CurrentTailnet)?.Name);
   return { ready: true, ipv4, ...dnsName ? { dnsName } : {}, ...tailnet ? { tailnet } : {} };
 }
 var TailscaleApprovalRequiredError = class extends Error {
@@ -20469,7 +20683,7 @@ function commandErrorMessage(error) {
 function recordValue(value) {
   return value && typeof value === "object" && !Array.isArray(value) ? value : void 0;
 }
-function stringValue(value) {
+function stringValue2(value) {
   return typeof value === "string" && value.trim() ? value.trim() : void 0;
 }
 function arrayValue(value) {
@@ -20541,7 +20755,7 @@ function createProgram(runtimeOverrides = {}) {
   program2.command("bootstrap", { isDefault: true }).alias("configure").description("Create or update a Hugging Face OpenClaw deployment").option("--owner <owner>", "Hugging Face user or organization").option("--name <name>", "Agent and runtime resource base name").option("--bucket <owner/bucket>", "State bucket to create or adopt").option("--gateway <local|space>", "Where the live gateway runs").option("--telegram-token <token>", "Optional Telegram bot token").option("--telegram-token-file <path>", "File containing TELEGRAM_BOT_TOKEN=... or a raw token").option("--telegram-user-id <id>", "Allowed Telegram user ID").option("--telegram-api-root <url>", "Telegram API root override").option("--telegram-proxy <url>", "Telegram proxy URL override").option("--hardware <flavor>", "Hugging Face Space hardware flavor").option("--sleep-time <seconds>", "Space sleep timeout in seconds; -1 means never sleep", parseInteger).option("--model <model>", "OpenClaw model identifier").option("--runtime-image <image>", "ML Claw runtime image").option("--bundled-runtime", "Generate a bundled Space runtime instead of using the prebuilt ML Claw image", false).option("--public-space", "Create the Hugging Face Space as public instead of private", false).addOption(new Option("--gateway-token <token>").hideHelp()).option("--router-token <token>", "Hugging Face Router inference token for Space gateway model calls").option(
     "--router-token-file <path>",
     "File containing MLCLAW_ROUTER_TOKEN=..., HF_ROUTER_TOKEN=..., or a raw token"
-  ).option("--docker-context <name>", "Docker context for local gateway mode").option("--container-runtime <auto|docker|podman>", "Local container runtime", "auto").option("--local-port <port>", "Loopback port for a local gateway", parseLocalPort).option("--tailscale <off|direct|serve>", "Tailnet access mode", parseTailscaleMode).option("--tailscale-port <port>", "Tailnet listener or Serve HTTPS port", parseLocalPort).option(
+  ).option("--broker-hf-token-file <path>", "File containing MLCLAW_BROKER_HF_TOKEN=... or a raw Hugging Face token").option("--docker-context <name>", "Docker context for local gateway mode").option("--container-runtime <auto|docker|podman>", "Local container runtime", "auto").option("--local-port <port>", "Loopback port for a local gateway", parseLocalPort).option("--tailscale <off|direct|serve>", "Tailnet access mode", parseTailscaleMode).option("--tailscale-port <port>", "Tailnet listener or Serve HTTPS port", parseLocalPort).option(
     "--allow-local-fallback",
     "Allow non-interactive Space bootstrap to fall back to a ready local runtime",
     false
@@ -20566,6 +20780,13 @@ function createProgram(runtimeOverrides = {}) {
     const hub = runtime.hubFactory(token);
     await settings(repoId, opts, hub, runtime);
   });
+  const credentials = program2.command("credentials").description("Inspect or replace trusted broker credentials");
+  credentials.command("status").description("Verify the dedicated HF Broker credential").argument("[agent]", "Agent name; inferred when exactly one deployment exists").action(async (agent) => {
+    await credentialsStatus(agent, runtime);
+  });
+  credentials.command("repair").description("Replace and apply the dedicated HF Broker credential").argument("[agent]", "Agent name; inferred when exactly one deployment exists").option("--broker-hf-token-file <path>", "File containing MLCLAW_BROKER_HF_TOKEN=... or a raw token").action(async (agent, opts) => {
+    await credentialsRepair(agent, opts, runtime);
+  });
   const gateway = program2.command("gateway").description("Operate a ML Claw gateway");
   gateway.command("start").argument("<agent>", "Agent name").option("--docker-context <name>", "Set Docker context only when the deployment has no pinned context").option("--local-port <port>", "Loopback port for the local gateway", parseLocalPort).option("--tailscale <off|direct|serve>", "Tailnet access mode", parseTailscaleMode).option("--tailscale-port <port>", "Tailnet listener or Serve HTTPS port", parseLocalPort).option("--no-pull", "Do not docker pull before starting a local gateway").option("--takeover", "Start even if another live runtime lease is present", false).action(async (agent, opts) => {
     await gatewayStart(agent, opts, runtime);
@@ -20777,20 +20998,24 @@ async function bootstrap(opts, runtime) {
   const runtimeImage = resolveRuntimeImage(opts.runtimeImage, runtime.env);
   resolveSpaceRuntimeImage(opts, runtime.env);
   let plan;
+  let reviewedBrokerHfToken;
   for (; ; ) {
     plan = await resolveBootstrapPlan({
       opts,
       owner,
       agentName,
       hfToken,
+      hfIdentity: me2,
       model,
       runtimeImage,
       hub,
       runtime,
+      ...reviewedBrokerHfToken ? { providedBrokerHfToken: reviewedBrokerHfToken } : {},
       ...requestedGatewayLocation ? { requestedGatewayLocation } : {},
       ...telegramToken ? { telegramToken } : {},
       ...telegramUserId ? { telegramUserId } : {}
     });
+    reviewedBrokerHfToken = plan.secrets.MLCLAW_BROKER_HF_TOKEN;
     const alternative = await promptAlternativeBootstrapName({
       plan,
       explicitBucket: opts.bucket,
@@ -20866,6 +21091,8 @@ async function bootstrap(opts, runtime) {
         owner,
         agentName,
         hfToken,
+        hfIdentity: me2,
+        brokerHfToken: activePlan.secrets.MLCLAW_BROKER_HF_TOKEN ?? hfToken,
         model,
         runtimeImage,
         hub,
@@ -20923,7 +21150,7 @@ async function bootstrap(opts, runtime) {
           const secretsChanged = JSON.stringify(previousSecrets) !== JSON.stringify(activePlan.secrets);
           if (secretsChanged) {
             await assertLease();
-            await setSpaceGatewaySecrets(hub, activePlan.manifest.space, hfToken, activePlan.secrets, assertLease);
+            await setSpaceGatewaySecrets(hub, activePlan.manifest.space, activePlan.secrets, assertLease);
             if (canDeleteBroadTokenSecrets({
               model: activePlan.manifest.model,
               routerTokenPresent: hasBrokerOrRouterTokenSecretRecord(activePlan.secrets)
@@ -21081,7 +21308,7 @@ function assertBootstrapIdentityMatches(plan, identity) {
 }
 async function reconcileManifest(params) {
   const { hub, runtime } = params;
-  const localLockKey = createHash3("sha256").update(`${params.manifest.owner}\0${params.manifest.agent}`).digest("hex");
+  const localLockKey = deploymentLockKey(params.manifest);
   return await withDeploymentLock(runtime.configRoot, localLockKey, async () => {
     let requestedManifest = params.manifest;
     const client = hub.bucket(requestedManifest.bucket);
@@ -21120,7 +21347,7 @@ async function reconcileManifest(params) {
       const secrets = await ensureDeploymentCredentialKey(runtime, requestedManifest.agent);
       requestedManifest = {
         ...requestedManifest,
-        credentialKeySha256: createHash3("sha256").update(requiredSecret(secrets, "MLCLAW_CREDENTIAL_KEY")).digest("hex")
+        credentialKeySha256: createHash4("sha256").update(requiredSecret(secrets, "MLCLAW_CREDENTIAL_KEY")).digest("hex")
       };
     }
     const currentDesired = await readDesiredState(client);
@@ -21240,6 +21467,8 @@ async function resolveBootstrapPlan(params) {
     agentName,
     requestedGatewayLocation,
     hfToken,
+    hfIdentity,
+    providedBrokerHfToken,
     telegramToken,
     telegramUserId,
     model,
@@ -21251,6 +21480,14 @@ async function resolveBootstrapPlan(params) {
   const now = runtime.now().toISOString();
   const existingManifest = await readManifest(runtime.configRoot, agentName).catch(() => null);
   const existingSecrets = await readSecretEnv(runtime.configRoot, agentName).catch(() => ({}));
+  const brokerCredential = await resolveBrokerHfToken({
+    opts,
+    owner,
+    hfIdentity,
+    ...providedBrokerHfToken ? { preferredToken: providedBrokerHfToken } : {},
+    existingSecrets,
+    runtime
+  });
   const sessionSecret = existingSecrets.MLCLAW_SESSION_SECRET ?? randomBytes(48).toString("base64url");
   const restoredCredentialKey = existingSecrets.MLCLAW_CREDENTIAL_KEY ?? runtime.env.MLCLAW_CREDENTIAL_KEY;
   if (existingManifest?.recoveredWithoutCredentialKey && !restoredCredentialKey) {
@@ -21259,7 +21496,7 @@ async function resolveBootstrapPlan(params) {
     );
   }
   const credentialKey = restoredCredentialKey ?? randomBytes(32).toString("base64url");
-  const credentialKeySha256 = createHash3("sha256").update(credentialKey).digest("hex");
+  const credentialKeySha256 = createHash4("sha256").update(credentialKey).digest("hex");
   if (existingManifest?.credentialKeySha256 && existingManifest.credentialKeySha256 !== credentialKeySha256) {
     throw new Error("MLCLAW_CREDENTIAL_KEY does not match the recovered deployment");
   }
@@ -21325,6 +21562,7 @@ async function resolveBootstrapPlan(params) {
     gatewayLocation,
     model: effectiveModel,
     runtimeImage: effectiveRuntimeImage,
+    brokerCredential: brokerCredentialMetadata(brokerCredential.token, brokerCredential.identity, runtime.now()),
     credentialKeySha256,
     ...existingManifest?.tailscaleMode ? { tailscaleMode: existingManifest.tailscaleMode } : {},
     ...existingManifest?.spaceVisibility ? { spaceVisibility: existingManifest.spaceVisibility } : {},
@@ -21342,7 +21580,7 @@ async function resolveBootstrapPlan(params) {
   const effectiveTelegramProxy = opts.telegramProxy ?? existingSecrets.TELEGRAM_PROXY;
   const effectiveTelegramApiRoot = opts.telegramApiRoot ?? existingSecrets.TELEGRAM_API_ROOT;
   const secrets = deploymentSecrets({
-    hfToken,
+    hfToken: brokerCredential.token,
     ...effectiveTelegramToken ? { telegramToken: effectiveTelegramToken } : {},
     ...effectiveTelegramUserId ? { telegramUserId: effectiveTelegramUserId } : {},
     sessionSecret,
@@ -21601,6 +21839,8 @@ async function resolveHostedBootstrapFallback(params) {
       agentName: params.agentName,
       requestedGatewayLocation: "local",
       hfToken: params.hfToken,
+      hfIdentity: params.hfIdentity,
+      providedBrokerHfToken: params.brokerHfToken,
       model: params.model,
       runtimeImage: params.runtimeImage,
       hub: params.hub,
@@ -21978,35 +22218,43 @@ async function deployLocalBootstrap(plan, opts, runtime, desiredChanged = true,
     }
     try {
       if (networkAccessChanged && plan.manifest.networkAccess) {
+        await assertLease();
         await disableNetworkAccess(plan.manifest, runtime);
       }
       if (previousSecrets) {
+        await assertLease();
         await writeSecretEnv(runtime.configRoot, plan.agentName, previousSecrets);
       } else {
+        await assertLease();
         await fs16.rm(secretEnvPath(runtime.configRoot, plan.agentName), { force: true });
       }
       if (previousContainer?.running && previousManifest) {
-        await startLocalGateway({ manifest: previousManifest, runtime, pull: false, refresh: true });
+        await startLocalGateway({ manifest: previousManifest, runtime, pull: false, refresh: true, assertLease });
         runtime.stdout.log(`Previous local gateway restored: ${containerNameFor(previousManifest.agent)}`);
       } else if (previousContainer && previousManifest && startupAttempted) {
-        await startLocalGateway({ manifest: previousManifest, runtime, pull: false, refresh: true });
+        await startLocalGateway({ manifest: previousManifest, runtime, pull: false, refresh: true, assertLease });
+        await assertLease();
         await localRunnerFor(previousManifest, runtime).stop(
           containerNameFor(previousManifest.agent),
           localConnectionFor(previousManifest)
         );
         if (previousNetworkState !== "owned") {
+          await assertLease();
           await disableNetworkAccess(previousManifest, runtime);
         }
         runtime.stdout.log(`Previous stopped local gateway restored: ${containerNameFor(previousManifest.agent)}`);
       } else {
         if (startupAttempted) {
+          await assertLease();
           await removeFailedBootstrapContainer(plan.manifest, runtime, !previousManifest);
         }
       }
       if (previousNetworkState === "owned" && previousManifest?.networkAccess) {
+        await assertLease();
         await runtime.tailscaleRunner.ensureMapping(networkAccessMapping(previousManifest.networkAccess));
       }
       if (!previousManifest) {
+        await assertLease();
         await fs16.rm(manifestPath(runtime.configRoot, plan.agentName), { force: true });
       }
     } catch (rollbackError) {
@@ -22112,7 +22360,7 @@ async function deploySpaceGateway(params) {
   await assertLease();
   await clearSpaceGatewayDisabled(hub, manifest.space);
   await assertLease();
-  await setSpaceGatewaySecrets(hub, manifest.space, hfToken, secrets, assertLease);
+  await setSpaceGatewaySecrets(hub, manifest.space, secrets, assertLease);
   if (canDeleteBroadTokenSecrets({
     model: manifest.model,
     routerTokenPresent: hasBrokerOrRouterTokenSecretRecord(secrets)
@@ -23219,7 +23467,7 @@ async function restoreMatchingDeploymentCredentialKey(runtime, agent, expectedSh
   const candidates = [suppliedCredentialKey, runtime.env.MLCLAW_CREDENTIAL_KEY, secrets.MLCLAW_CREDENTIAL_KEY].filter(
     (value) => Boolean(value)
   );
-  const credentialKey = candidates.find((value) => createHash3("sha256").update(value).digest("hex") === expectedSha256);
+  const credentialKey = candidates.find((value) => createHash4("sha256").update(value).digest("hex") === expectedSha256);
   if (!credentialKey) {
     throw new Error("local MLCLAW_CREDENTIAL_KEY is missing or does not match the canonical deployment identity");
   }
@@ -23245,7 +23493,7 @@ async function update(repoId, opts, hub, hfToken, runtime) {
   const runtimeImage = resolveSpaceRuntimeImage(opts, runtime.env);
   const agentName = variables.get("OPENCLAW_AGENT_NAME")?.value?.trim() || repoId.split("/")[1] || "openclaw";
   if (!canonicalTemplate) {
-    await ensureUpdateRouterToken({
+    await ensureUpdateCredentials({
       repoId,
       agentName,
       model: variables.get("OPENCLAW_MODEL")?.value ?? DEFAULT_MODEL2,
@@ -23282,39 +23530,39 @@ async function update(repoId, opts, hub, hfToken, runtime) {
   await doctor(repoId, { fix: true }, hub, runtime);
   runtime.stdout.log(`Space deployment triggered: ${repoId}`);
 }
-async function ensureUpdateRouterToken(params) {
-  if (!isHuggingFaceRouterModel(params.model)) {
-    return;
-  }
-  const spaceSecrets = await params.hub.getSpaceSecrets(params.repoId);
+async function ensureUpdateCredentials(params) {
   const hasExplicitOverride = params.opts.routerToken !== void 0 || params.opts.routerTokenFile !== void 0;
-  if (hasBrokerOrRouterTokenSecretMap(spaceSecrets) && !hasExplicitOverride) {
-    return;
-  }
   const hasManifest = await manifestExists(params.runtime.configRoot, params.agentName);
-  const localSecrets = hasManifest ? await readSecretEnv(params.runtime.configRoot, params.agentName).catch(() => ({})) : {};
+  if (!hasManifest) {
+    throw new Error(
+      `cannot verify the dedicated HF Broker credential; recover the deployment and run \`mlclaw credentials repair ${params.agentName}\``
+    );
+  }
+  const localManifest = await readManifest(params.runtime.configRoot, params.agentName);
+  if (localManifest.space !== params.repoId) {
+    throw new Error(
+      `local deployment ${params.agentName} belongs to ${localManifest.space}, not ${params.repoId}; specify the matching deployment before updating`
+    );
+  }
+  const localSecrets = await readSecretEnv(params.runtime.configRoot, params.agentName).catch(
+    () => ({})
+  );
+  const brokerCredential = await verifiedStoredBrokerCredential(localManifest, params.runtime);
   const routerToken = hasExplicitOverride ? await resolveRouterToken({
     opts: params.opts,
     runtime: params.runtime,
     existingSecrets: localSecrets,
     model: params.model
   }) : void 0;
-  const brokerToken = routerToken ? void 0 : await params.runtime.readToken(params.runtime.env);
-  const credential = routerToken ?? brokerToken;
-  if (!credential) {
-    throw new Error("Hugging Face broker credential is unavailable");
-  }
-  await params.hub.addSpaceSecret(
-    params.repoId,
-    routerToken ? "MLCLAW_ROUTER_TOKEN" : "MLCLAW_BROKER_HF_TOKEN",
-    credential
-  );
-  if (hasManifest) {
-    await writeSecretEnv(params.runtime.configRoot, params.agentName, {
-      ...localSecrets,
-      ...routerToken ? { MLCLAW_ROUTER_TOKEN: routerToken } : { MLCLAW_BROKER_HF_TOKEN: brokerToken }
-    });
-  }
+  await params.hub.addSpaceSecret(params.repoId, "MLCLAW_BROKER_HF_TOKEN", brokerCredential.token);
+  if (routerToken) {
+    await params.hub.addSpaceSecret(params.repoId, "MLCLAW_ROUTER_TOKEN", routerToken);
+  }
+  await writeSecretEnv(params.runtime.configRoot, params.agentName, {
+    ...localSecrets,
+    MLCLAW_BROKER_HF_TOKEN: brokerCredential.token,
+    ...routerToken ? { MLCLAW_ROUTER_TOKEN: routerToken } : {}
+  });
 }
 async function doctor(repoId, opts, hub, runtime) {
   if (!repoId.includes("/") && await manifestExists(runtime.configRoot, repoId)) {
@@ -23409,14 +23657,20 @@ async function doctor(repoId, opts, hub, runtime) {
       }
     }
   }
-  if (!secrets.has("MLCLAW_BROKER_HF_TOKEN")) {
-    if (fix) {
-      await hub.addSpaceSecret(repoId, "MLCLAW_BROKER_HF_TOKEN", await runtime.readToken(runtime.env));
-      secrets.set("MLCLAW_BROKER_HF_TOKEN", { key: "MLCLAW_BROKER_HF_TOKEN" });
-      fixed.push("set secret MLCLAW_BROKER_HF_TOKEN");
-    } else {
-      issues.push("secret MLCLAW_BROKER_HF_TOKEN is missing");
+  if (fix) {
+    const manifests = (await listManifests(runtime.configRoot)).filter((manifest) => manifest.space === repoId);
+    if (manifests.length !== 1) {
+      throw new Error(
+        `cannot verify MLCLAW_BROKER_HF_TOKEN without one matching local deployment; recover it with \`mlclaw bootstrap --name ${repoId.split("/")[1] ?? "agent"}\``
+      );
     }
+    const credential = await verifiedStoredBrokerCredential(manifests[0], runtime);
+    const existed = secrets.has("MLCLAW_BROKER_HF_TOKEN");
+    await hub.addSpaceSecret(repoId, "MLCLAW_BROKER_HF_TOKEN", credential.token);
+    secrets.set("MLCLAW_BROKER_HF_TOKEN", { key: "MLCLAW_BROKER_HF_TOKEN" });
+    fixed.push(`${existed ? "refreshed verified" : "set"} secret MLCLAW_BROKER_HF_TOKEN`);
+  } else if (!secrets.has("MLCLAW_BROKER_HF_TOKEN")) {
+    issues.push("secret MLCLAW_BROKER_HF_TOKEN is missing");
   }
   const staleTokenSecrets = ["HF_TOKEN", "HUGGINGFACE_HUB_TOKEN"].filter((key) => secrets.has(key));
   if (staleTokenSecrets.length > 0) {
@@ -23634,14 +23888,14 @@ async function setDeploymentSecrets(hub, repoId, secrets, assertMutation = async
     await hub.addSpaceSecret(repoId, key, value);
   }
 }
-async function setSpaceGatewaySecrets(hub, repoId, hfToken, secrets, assertMutation = async () => void 0) {
+async function setSpaceGatewaySecrets(hub, repoId, secrets, assertMutation = async () => void 0) {
   await setDeploymentSecrets(
     hub,
     repoId,
     {
       MLCLAW_SESSION_SECRET: requiredSecret(secrets, "MLCLAW_SESSION_SECRET"),
       MLCLAW_CREDENTIAL_KEY: requiredSecret(secrets, "MLCLAW_CREDENTIAL_KEY"),
-      MLCLAW_BROKER_HF_TOKEN: hfToken,
+      MLCLAW_BROKER_HF_TOKEN: requiredSecret(secrets, "MLCLAW_BROKER_HF_TOKEN"),
       ...secrets.MLCLAW_ROUTER_TOKEN ? { MLCLAW_ROUTER_TOKEN: secrets.MLCLAW_ROUTER_TOKEN } : {},
       ...secrets.TELEGRAM_BOT_TOKEN ? { TELEGRAM_BOT_TOKEN: secrets.TELEGRAM_BOT_TOKEN } : {},
       ...secrets.TELEGRAM_ALLOWED_USERS ? { TELEGRAM_ALLOWED_USERS: secrets.TELEGRAM_ALLOWED_USERS } : {},
@@ -23768,6 +24022,309 @@ async function readOptionalRouterTokenFile(file) {
   const parsed = parseSecretEnv(raw);
   return nonEmpty(parsed.MLCLAW_ROUTER_TOKEN) ?? nonEmpty(parsed.HF_ROUTER_TOKEN) ?? nonEmpty(raw);
 }
+async function credentialsStatus(requestedAgent, runtime) {
+  const manifest = await credentialManifest(requestedAgent, runtime);
+  await verifiedStoredBrokerCredential(manifest, runtime);
+  const metadata = manifest.brokerCredential;
+  if (!metadata) throw new Error("verified HF Broker credential metadata is missing");
+  runtime.stdout.log(`Agent: ${manifest.agent}`);
+  runtime.stdout.log(`Status: healthy`);
+  runtime.stdout.log(`Profile: ${metadata.profileId}`);
+  runtime.stdout.log(`Account: ${metadata.account}`);
+  runtime.stdout.log(`Fingerprint: ${metadata.fingerprintSha256.slice(0, 12)}`);
+  runtime.stdout.log(`Verified: ${metadata.verifiedAt}`);
+}
+async function verifiedStoredBrokerCredential(manifest, runtime) {
+  const secrets = await readSecretEnv(runtime.configRoot, manifest.agent);
+  const token = nonEmpty(secrets.MLCLAW_BROKER_HF_TOKEN);
+  if (!token) throw new Error(`deployment ${manifest.agent} has no dedicated HF Broker credential`);
+  if (!manifest.brokerCredential) {
+    throw new Error(
+      `HF Broker credential metadata is missing; run \`mlclaw credentials repair ${manifest.agent}\` to complete the cutover`
+    );
+  }
+  const verified = await verifyBrokerHfToken(token, manifest.owner, manifest.brokerCredential.account, runtime);
+  const observed = brokerCredentialMetadata(token, verified.identity, runtime.now());
+  if (observed.fingerprintSha256 !== manifest.brokerCredential.fingerprintSha256) {
+    throw new Error(
+      `HF Broker credential fingerprint changed; run \`mlclaw credentials repair ${manifest.agent}\` to reconcile it`
+    );
+  }
+  return verified;
+}
+async function credentialsRepair(requestedAgent, opts, runtime) {
+  const selectedManifest = await credentialManifest(requestedAgent, runtime);
+  await withDeploymentLock(runtime.configRoot, deploymentLockKey(selectedManifest), async () => {
+    const manifest = await readManifest(runtime.configRoot, selectedManifest.agent);
+    const secrets = await readSecretEnv(runtime.configRoot, manifest.agent).catch(() => ({}));
+    const oldToken = nonEmpty(secrets.MLCLAW_BROKER_HF_TOKEN);
+    const account = await credentialRepairAccount(manifest, oldToken, runtime);
+    const fileToken = await readOptionalBrokerHfTokenFile(opts.brokerHfTokenFile);
+    const suppliedToken = fileToken ?? nonEmpty(runtime.env.MLCLAW_BROKER_HF_TOKEN);
+    let replacement;
+    if (suppliedToken) {
+      replacement = await verifyBrokerHfToken(suppliedToken, manifest.owner, account, runtime);
+    } else {
+      if (!runtime.prompt.isInteractive()) {
+        throw new Error(
+          "credential repair requires --broker-hf-token-file, MLCLAW_BROKER_HF_TOKEN, or an interactive terminal"
+        );
+      }
+      replacement = await promptForBrokerHfToken(manifest.owner, account, runtime);
+    }
+    const updatedManifest = {
+      ...manifest,
+      brokerCredential: brokerCredentialMetadata(replacement.token, replacement.identity, runtime.now()),
+      updatedAt: runtime.now().toISOString()
+    };
+    const updatedSecrets = { ...secrets, MLCLAW_BROKER_HF_TOKEN: replacement.token };
+    const coordinationToken = manifest.gatewayLocation === "space" ? await runtime.readToken(runtime.env) : replacement.token;
+    const coordinationHub = runtime.hubFactory(coordinationToken);
+    const control = await coordinationHub.deploymentControlStore(manifest.owner, manifest.deploymentId);
+    const operation = newOperation(manifest, runtime.now());
+    let lease = await acquireControlLease(control, manifest, operation, runtime.now());
+    let renewalError;
+    let renewal = Promise.resolve();
+    const renewalTimer = setInterval(() => {
+      renewal = renewal.then(async () => {
+        if (renewalError) return;
+        try {
+          lease = await renewControlLease(control, lease, runtime.now());
+        } catch (error) {
+          renewalError = error;
+        }
+      });
+    }, 45e3);
+    const assertLease = async () => {
+      await renewal;
+      if (renewalError) throw renewalError;
+      await assertControlLease(control, lease, runtime.now());
+      if (renewalError) throw renewalError;
+    };
+    try {
+      await assertLease();
+      if (manifest.gatewayLocation === "local") {
+        await applyLocalCredentialRepair(manifest, updatedManifest, secrets, updatedSecrets, runtime, assertLease);
+      } else {
+        await applySpaceCredentialRepair(
+          manifest,
+          updatedManifest,
+          secrets,
+          updatedSecrets,
+          oldToken,
+          coordinationHub,
+          runtime,
+          assertLease
+        );
+      }
+      await assertLease();
+    } finally {
+      clearInterval(renewalTimer);
+      await renewal;
+      await releaseControlLease(control, lease);
+    }
+    runtime.stdout.log(`HF Broker credential repaired: ${manifest.agent}`);
+  });
+}
+async function credentialManifest(requestedAgent, runtime) {
+  if (requestedAgent) return await readManifest(runtime.configRoot, requestedAgent);
+  const manifests = await listManifests(runtime.configRoot);
+  if (manifests.length === 1) return manifests[0];
+  if (manifests.length === 0) throw new Error("no ML Claw deployment found");
+  throw new Error("multiple ML Claw deployments found; specify an agent name");
+}
+async function credentialRepairAccount(manifest, oldToken, runtime) {
+  if (manifest.brokerCredential) return manifest.brokerCredential.account;
+  if (oldToken) {
+    try {
+      return (await runtime.hubFactory(oldToken).whoami()).name;
+    } catch {
+    }
+  }
+  const provisioningToken = await runtime.readToken(runtime.env);
+  return (await runtime.hubFactory(provisioningToken).whoami()).name;
+}
+async function applyLocalCredentialRepair(previousManifest, updatedManifest, previousSecrets, updatedSecrets, runtime, assertLease) {
+  const runner = localRunnerFor(previousManifest, runtime);
+  const existing = await runner.inspect(containerNameFor(previousManifest.agent), localConnectionFor(previousManifest));
+  if (!existing?.running) {
+    await replaceLocalCredentialFiles(
+      previousManifest,
+      updatedManifest,
+      previousSecrets,
+      updatedSecrets,
+      runtime,
+      assertLease
+    );
+    return;
+  }
+  const bucketPrefix = await readDeploymentBucketPrefix(runtime, previousManifest.agent);
+  await deployLocalBootstrap(
+    {
+      agentName: previousManifest.agent,
+      names: namesFor(previousManifest.owner, previousManifest.agent),
+      hasExistingManifest: true,
+      previousManifest,
+      gatewayLocation: "local",
+      ...bucketPrefix ? { bucketPrefix } : {},
+      bucketPlan: { bucket: previousManifest.bucket, exists: true, objectCount: 0 },
+      bucket: previousManifest.bucket,
+      manifest: updatedManifest,
+      secrets: updatedSecrets
+    },
+    { pull: false },
+    runtime,
+    true,
+    assertLease
+  );
+}
+async function replaceLocalCredentialFiles(previousManifest, updatedManifest, previousSecrets, updatedSecrets, runtime, assertLease) {
+  try {
+    await assertLease();
+    await writeSecretEnv(runtime.configRoot, updatedManifest.agent, updatedSecrets);
+    await assertLease();
+    await writeManifest(runtime.configRoot, updatedManifest);
+  } catch (error) {
+    await assertLease();
+    await writeSecretEnv(runtime.configRoot, previousManifest.agent, previousSecrets);
+    await assertLease();
+    await writeManifest(runtime.configRoot, previousManifest);
+    throw error;
+  }
+}
+async function applySpaceCredentialRepair(previousManifest, updatedManifest, previousSecrets, updatedSecrets, oldToken, hub, runtime, assertLease) {
+  try {
+    await assertLease();
+    await hub.addSpaceSecret(
+      previousManifest.space,
+      "MLCLAW_BROKER_HF_TOKEN",
+      requiredSecret(updatedSecrets, "MLCLAW_BROKER_HF_TOKEN")
+    );
+    await assertLease();
+    await hub.restartSpace(previousManifest.space, true);
+    await replaceLocalCredentialFiles(
+      previousManifest,
+      updatedManifest,
+      previousSecrets,
+      updatedSecrets,
+      runtime,
+      assertLease
+    );
+  } catch (error) {
+    try {
+      await assertLease();
+      if (oldToken) {
+        await hub.addSpaceSecret(previousManifest.space, "MLCLAW_BROKER_HF_TOKEN", oldToken);
+      } else {
+        await hub.deleteSpaceSecret(previousManifest.space, "MLCLAW_BROKER_HF_TOKEN");
+      }
+      await assertLease();
+      await hub.restartSpace(previousManifest.space, true);
+      await assertLease();
+      await writeSecretEnv(runtime.configRoot, previousManifest.agent, previousSecrets);
+      await assertLease();
+      await writeManifest(runtime.configRoot, previousManifest);
+    } catch (rollbackError) {
+      throw new Error(
+        `credential repair failed (${errorMessage(error)}) and rollback failed (${errorMessage(rollbackError)})`
+      );
+    }
+    throw error;
+  }
+}
+function deploymentLockKey(manifest) {
+  return createHash4("sha256").update(`${manifest.owner}\0${manifest.agent}`).digest("hex");
+}
+async function resolveBrokerHfToken(params) {
+  const fileToken = await readOptionalBrokerHfTokenFile(params.opts.brokerHfTokenFile);
+  const environmentToken = nonEmpty(params.runtime.env.MLCLAW_BROKER_HF_TOKEN);
+  const configuredToken = fileToken ?? environmentToken ?? nonEmpty(params.preferredToken) ?? nonEmpty(params.existingSecrets.MLCLAW_BROKER_HF_TOKEN);
+  if (configuredToken) {
+    try {
+      return await verifyBrokerHfToken(configuredToken, params.owner, params.hfIdentity.name, params.runtime);
+    } catch (error) {
+      if (fileToken || environmentToken || params.preferredToken) throw error;
+      if (params.runtime.prompt.isInteractive()) {
+        params.runtime.prompt.note(
+          `The saved HF Broker credential could not be used (${errorMessage(error)}). It must be replaced before ML Claw can continue.`,
+          "HF Broker credential"
+        );
+      } else {
+        throw new Error(
+          `the saved HF Broker credential is unusable (${errorMessage(error)}); run \`mlclaw credentials repair\` interactively`
+        );
+      }
+    }
+  }
+  if (!params.runtime.prompt.isInteractive()) {
+    throw new Error(
+      "a dedicated HF Broker credential is required; set MLCLAW_BROKER_HF_TOKEN, pass --broker-hf-token-file, or run bootstrap interactively"
+    );
+  }
+  return await promptForBrokerHfToken(params.owner, params.hfIdentity.name, params.runtime);
+}
+async function promptForBrokerHfToken(owner, account, runtime) {
+  runtime.prompt.note(
+    "ML Claw will open a Hugging Face token form with BrokerKit's permissions preselected. Create a dedicated token and paste it here. Your current HF CLI login will not be changed.",
+    "HF Broker credential"
+  );
+  const url = buildBrokerTokenUrl(owner, account);
+  const opened = await runtime.hfCli.openUrl(url);
+  runtime.prompt.note(
+    `${opened ? "The token form was opened in your browser." : "Open this token form in your browser."}
+
+Name and create the token, then copy it. The URL contains permission names only; it contains no credential. The exact URL is printed below.`,
+    "Create the broker token"
+  );
+  runtime.stdout.log(url);
+  for (; ; ) {
+    const replacement = readPromptValue(
+      await runtime.prompt.password({ message: "Paste the new Hugging Face broker token" }),
+      "Hugging Face broker token"
+    );
+    try {
+      const verified = await verifyBrokerHfToken(replacement, owner, account, runtime);
+      runtime.prompt.note(
+        "The dedicated broker token was verified. It will be stored only in ML Claw's trusted broker configuration.",
+        "HF Broker credential ready"
+      );
+      return verified;
+    } catch (error) {
+      runtime.prompt.note(errorMessage(error), "Broker token was not accepted");
+      if (!await promptConfirm("Try another broker token?", true, runtime)) {
+        throw new Error("a valid dedicated HF Broker credential is required");
+      }
+    }
+  }
+}
+async function verifyBrokerHfToken(token, owner, expectedAccount, runtime) {
+  const identity = await runtime.hubFactory(token).whoami();
+  if (identity.name !== expectedAccount) {
+    throw new Error(`broker token belongs to ${identity.name}, not ${expectedAccount}`);
+  }
+  const assessment = assessBrokerCredential(identity, owner);
+  if (assessment.status !== "sufficient") {
+    throw new Error(brokerCredentialAssessmentDetail(assessment));
+  }
+  return { token, identity };
+}
+async function readOptionalBrokerHfTokenFile(file) {
+  if (!file) return void 0;
+  const raw = await fs16.readFile(file, "utf8");
+  const parsed = parseSecretEnv(raw);
+  const token = nonEmpty(parsed.MLCLAW_BROKER_HF_TOKEN) ?? nonEmpty(raw);
+  if (!token) throw new Error("HF Broker token file is empty");
+  return token;
+}
+function brokerCredentialAssessmentDetail(assessment) {
+  if (assessment.status === "unsupported") return assessment.reason;
+  const shown = assessment.missing.slice(0, 8);
+  const remaining = assessment.missing.length - shown.length;
+  return `The HF Broker credential is missing ${assessment.missing.length} required permission${assessment.missing.length === 1 ? "" : "s"}: ${shown.join(", ")}${remaining > 0 ? `, and ${remaining} more` : ""}`;
+}
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
 function isHuggingFaceRouterModel(model) {
   return model.trim().startsWith("huggingface/");
 }

package/entrypoint.sh

@@ -15,7 +15,7 @@ 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:-}}}}}"
+  local broker_token="${MLCLAW_BROKER_HF_TOKEN:-}"
   if [ -z "$broker_token" ]; then
     echo "[hf-broker] MLCLAW_BROKER_HF_TOKEN is not configured; broker disabled"
     return
@@ -45,7 +45,7 @@ prepare_hf_broker() {
   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}}}"
+    STATE_HF_TOKEN="$broker_token"
   fi
 
   export MLCLAW_HF_BROKER_URL="http://127.0.0.1:7863"
@@ -130,8 +130,8 @@ 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
+# The broker token and legacy token variables must not enter the control plane
+# or OpenClaw. The broker token is already in its 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

package/openclaw.default.json

@@ -57,9 +57,11 @@
   "session": {
     "dmScope": "per-channel-peer",
     "reset": {
-      "mode": "daily",
-      "atHour": 4,
-      "idleMinutes": 1440
+      "mode": "idle",
+      "idleMinutes": 2147483647
+    },
+    "maintenance": {
+      "resetArchiveRetention": false
     }
   },
   "cron": {

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "mlclaw",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "license": "MIT",
   "config": {
     "openclawVersion": "2026.7.1",
-    "brokerkitVersion": "hf-broker/v0.1.0",
+    "brokerkitVersion": "hf-broker/v0.2.0",
     "brokerkitPluginVersion": "0.2.1",
     "runtimeImageRepository": "ghcr.io/osolmaz/mlclaw"
   },
@@ -55,8 +55,8 @@
     "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/auth.ts src/mlclaw/cli.ts src/mlclaw/deployment-state.ts src/mlclaw/docker.ts src/mlclaw/hf-cli.ts src/mlclaw/hub-api.ts src/mlclaw/local-config.ts src/mlclaw/tailscale.ts src/mlclaw-space-runtime/delegated-brokerkit.ts src/mlclaw-space-runtime/delegated-revisions.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/local-access.ts src/mlclaw-space-runtime/openai-credentials.ts src/mlclaw-space-runtime/proxy.ts src/mlclaw-space-runtime/server.ts src/mlclaw-space-runtime/session.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.auth.test.ts test/mlclaw.brokerkit-agent-tools.test.ts test/mlclaw.bundle.test.ts test/mlclaw.cli.test.ts test/mlclaw.delegated-brokerkit.test.ts test/mlclaw.deployment-state.test.ts test/mlclaw.docker.test.ts test/mlclaw.generate-space.test.ts test/mlclaw.hub-api.test.ts test/mlclaw.local-config.test.ts test/mlclaw.operator-brokers.test.ts test/mlclaw.runtime-image.test.ts test/mlclaw.space-runtime.test.ts test/mlclaw.tailscale.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/auth.ts src/mlclaw/cli.ts src/mlclaw/deployment-state.ts src/mlclaw/docker.ts src/mlclaw/hf-cli.ts src/mlclaw/hub-api.ts src/mlclaw/local-config.ts src/mlclaw/tailscale.ts src/mlclaw-space-runtime/delegated-brokerkit.ts src/mlclaw-space-runtime/delegated-revisions.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/local-access.ts src/mlclaw-space-runtime/openai-credentials.ts src/mlclaw-space-runtime/proxy.ts src/mlclaw-space-runtime/server.ts src/mlclaw-space-runtime/session.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.auth.test.ts test/mlclaw.brokerkit-agent-tools.test.ts test/mlclaw.bundle.test.ts test/mlclaw.cli.test.ts test/mlclaw.delegated-brokerkit.test.ts test/mlclaw.deployment-state.test.ts test/mlclaw.docker.test.ts test/mlclaw.generate-space.test.ts test/mlclaw.hub-api.test.ts test/mlclaw.local-config.test.ts test/mlclaw.operator-brokers.test.ts test/mlclaw.runtime-image.test.ts test/mlclaw.space-runtime.test.ts test/mlclaw.tailscale.test.ts docs/operator-brokers-config.md",
+    "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/auth.ts src/mlclaw/cli.ts src/mlclaw/deployment-state.ts src/mlclaw/docker.ts src/mlclaw/hf-broker-credential.ts src/mlclaw/hf-cli.ts src/mlclaw/hub-api.ts src/mlclaw/local-config.ts src/mlclaw/tailscale.ts src/mlclaw-space-runtime/delegated-brokerkit.ts src/mlclaw-space-runtime/delegated-revisions.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/local-access.ts src/mlclaw-space-runtime/openai-credentials.ts src/mlclaw-space-runtime/proxy.ts src/mlclaw-space-runtime/server.ts src/mlclaw-space-runtime/session.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.auth.test.ts test/mlclaw.brokerkit-agent-tools.test.ts test/mlclaw.bundle.test.ts test/mlclaw.cli.test.ts test/mlclaw.delegated-brokerkit.test.ts test/mlclaw.deployment-state.test.ts test/mlclaw.docker.test.ts test/mlclaw.generate-space.test.ts test/mlclaw.hf-broker-credential.test.ts test/mlclaw.hub-api.test.ts test/mlclaw.local-config.test.ts test/mlclaw.operator-brokers.test.ts test/mlclaw.runtime-image.test.ts test/mlclaw.space-runtime.test.ts test/mlclaw.tailscale.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/auth.ts src/mlclaw/cli.ts src/mlclaw/deployment-state.ts src/mlclaw/docker.ts src/mlclaw/hf-broker-credential.ts src/mlclaw/hf-cli.ts src/mlclaw/hub-api.ts src/mlclaw/local-config.ts src/mlclaw/tailscale.ts src/mlclaw-space-runtime/delegated-brokerkit.ts src/mlclaw-space-runtime/delegated-revisions.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/local-access.ts src/mlclaw-space-runtime/openai-credentials.ts src/mlclaw-space-runtime/proxy.ts src/mlclaw-space-runtime/server.ts src/mlclaw-space-runtime/session.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.auth.test.ts test/mlclaw.brokerkit-agent-tools.test.ts test/mlclaw.bundle.test.ts test/mlclaw.cli.test.ts test/mlclaw.delegated-brokerkit.test.ts test/mlclaw.deployment-state.test.ts test/mlclaw.docker.test.ts test/mlclaw.generate-space.test.ts test/mlclaw.hf-broker-credential.test.ts test/mlclaw.hub-api.test.ts test/mlclaw.local-config.test.ts test/mlclaw.operator-brokers.test.ts test/mlclaw.runtime-image.test.ts test/mlclaw.space-runtime.test.ts test/mlclaw.tailscale.test.ts docs/operator-brokers-config.md",
     "lint": "eslint --max-warnings 0 src/mlclaw-space-runtime/delegated-brokerkit.ts src/mlclaw-space-runtime/delegated-revisions.ts src/mlclaw-space-runtime/operator-brokers.ts src/mlclaw-space-runtime/openclaw-config.ts",
     "coverage": "vitest run --coverage",
     "dry": "slophammer-ts dry .",

package/tsconfig.json

@@ -3,6 +3,7 @@
     "target": "ES2023",
     "module": "NodeNext",
     "moduleResolution": "NodeNext",
+    "resolveJsonModule": true,
     "lib": ["ES2023", "DOM"],
     "types": ["node"],
     "jsx": "react-jsx",