clawdentity 0.0.17 → 0.0.19

package/dist/index.js

@@ -17084,7 +17084,8 @@ var FILE_MODE = 384;
 var ENV_KEY_MAP = {
   registryUrl: "CLAWDENTITY_REGISTRY_URL",
   proxyUrl: "CLAWDENTITY_PROXY_URL",
-  apiKey: "CLAWDENTITY_API_KEY"
+  apiKey: "CLAWDENTITY_API_KEY",
+  humanName: "CLAWDENTITY_HUMAN_NAME"
 };
 var LEGACY_ENV_KEY_MAP = {
   registryUrl: ["CLAWDENTITY_REGISTRY"]
@@ -17111,6 +17112,9 @@ var normalizeConfig = (raw) => {
   if (typeof raw.apiKey === "string" && raw.apiKey.length > 0) {
     config2.apiKey = raw.apiKey;
   }
+  if (typeof raw.humanName === "string" && raw.humanName.length > 0) {
+    config2.humanName = raw.humanName;
+  }
   return config2;
 };
 var getConfigDir = () => join2(homedir(), CONFIG_DIR);
@@ -18536,7 +18540,8 @@ var logger5 = createLogger({ service: "cli", module: "config" });
 var VALID_KEYS = [
   "registryUrl",
   "proxyUrl",
-  "apiKey"
+  "apiKey",
+  "humanName"
 ];
 var isValidConfigKey = (value) => {
   return VALID_KEYS.includes(value);
@@ -20862,11 +20867,20 @@ function parseInviteRedeemResponse(payload) {
   }
   const apiKeyId = parseNonEmptyString7(apiKeySource.id);
   const apiKeyName = parseNonEmptyString7(apiKeySource.name);
+  const humanSource = isRecord7(payload.human) ? payload.human : void 0;
+  const humanName = parseNonEmptyString7(humanSource?.displayName);
   const proxyUrl = parseNonEmptyString7(payload.proxyUrl);
+  if (humanName.length === 0) {
+    throw createCliError5(
+      "CLI_INVITE_REDEEM_INVALID_RESPONSE",
+      "Invite redeem response is invalid"
+    );
+  }
   return {
     apiKeyToken,
     apiKeyId: apiKeyId.length > 0 ? apiKeyId : void 0,
     apiKeyName: apiKeyName.length > 0 ? apiKeyName : void 0,
+    humanName,
     proxyUrl
   };
 }
@@ -20921,6 +20935,14 @@ async function redeemInvite(code, options, dependencies = {}) {
       "Invite code is required"
     );
   }
+  const displayName = parseNonEmptyString7(options.displayName);
+  if (displayName.length === 0) {
+    throw createCliError5(
+      "CLI_INVITE_REDEEM_DISPLAY_NAME_REQUIRED",
+      "Display name is required. Pass --display-name <name>."
+    );
+  }
+  const apiKeyName = parseNonEmptyString7(options.apiKeyName);
   const runtime = await resolveInviteRuntime(options.registryUrl, dependencies);
   const response = await executeInviteRequest({
     fetchImpl: runtime.fetchImpl,
@@ -20930,7 +20952,11 @@ async function redeemInvite(code, options, dependencies = {}) {
       headers: {
         "content-type": "application/json"
       },
-      body: JSON.stringify({ code: inviteCode })
+      body: JSON.stringify({
+        code: inviteCode,
+        displayName,
+        apiKeyName: apiKeyName.length > 0 ? apiKeyName : void 0
+      })
     }
   });
   const responseBody = await parseJsonResponse5(response);
@@ -20950,12 +20976,13 @@ async function redeemInvite(code, options, dependencies = {}) {
     registryUrl: runtime.registryUrl
   };
 }
-async function persistRedeemConfig(registryUrl, apiKeyToken, proxyUrl, dependencies = {}) {
+async function persistRedeemConfig(registryUrl, apiKeyToken, proxyUrl, humanName, dependencies = {}) {
   const setConfigValueImpl = dependencies.setConfigValueImpl ?? setConfigValue;
   try {
     await setConfigValueImpl("registryUrl", registryUrl);
     await setConfigValueImpl("apiKey", apiKeyToken);
     await setConfigValueImpl("proxyUrl", proxyUrl);
+    await setConfigValueImpl("humanName", humanName);
   } catch (error48) {
     logger7.warn("cli.invite_redeem_config_persist_failed", {
       errorName: error48 instanceof Error ? error48.name : "unknown"
@@ -20989,7 +21016,10 @@ var createInviteCommand = (dependencies = {}) => {
       }
     )
   );
-  inviteCommand.command("redeem <code>").description("Redeem a registry invite code and store PAT locally").option("--registry-url <url>", "Override registry URL").action(
+  inviteCommand.command("redeem <code>").description("Redeem a registry invite code and store PAT locally").requiredOption(
+    "--display-name <name>",
+    "Human display name used for onboarding"
+  ).option("--api-key-name <name>", "Optional API key label").option("--registry-url <url>", "Override registry URL").action(
     withErrorHandling(
       "invite redeem",
       async (code, options) => {
@@ -20997,9 +21027,11 @@ var createInviteCommand = (dependencies = {}) => {
         logger7.info("cli.invite_redeemed", {
           apiKeyId: result.apiKeyId,
           apiKeyName: result.apiKeyName,
+          humanName: result.humanName,
           registryUrl: result.registryUrl
         });
         writeStdoutLine("Invite redeemed");
+        writeStdoutLine(`Human name: ${result.humanName}`);
         if (result.apiKeyName) {
           writeStdoutLine(`API key name: ${result.apiKeyName}`);
         }
@@ -21009,6 +21041,7 @@ var createInviteCommand = (dependencies = {}) => {
           result.registryUrl,
           result.apiKeyToken,
           result.proxyUrl,
+          result.humanName,
           dependencies
         );
         writeStdoutLine("API key saved to local config");
@@ -21057,7 +21090,6 @@ var HOOK_PATH_SEND_TO_PEER = "send-to-peer";
 var OPENCLAW_SEND_TO_PEER_HOOK_PATH = "hooks/send-to-peer";
 var DEFAULT_OPENCLAW_BASE_URL2 = "http://127.0.0.1:18789";
 var DEFAULT_OPENCLAW_MAIN_SESSION_KEY = "main";
-var DEFAULT_OPENCLAW_AGENT_ID = "main";
 var DEFAULT_CONNECTOR_PORT = 19400;
 var DEFAULT_CONNECTOR_OUTBOUND_PATH3 = "/v1/outbound";
 var DEFAULT_CONNECTOR_STATUS_PATH2 = "/v1/status";
@@ -21074,6 +21106,7 @@ var OPENCLAW_SETUP_COMMAND_HINT = "Run: clawdentity openclaw setup <agentName>";
 var OPENCLAW_SETUP_RESTART_COMMAND_HINT = `${OPENCLAW_SETUP_COMMAND_HINT} and restart OpenClaw`;
 var OPENCLAW_SETUP_WITH_BASE_URL_HINT = `${OPENCLAW_SETUP_COMMAND_HINT} --openclaw-base-url <url>`;
 var OPENCLAW_PAIRING_COMMAND_HINT = "Run QR pairing first: clawdentity pair start <agentName> --qr and clawdentity pair confirm <agentName> --qr-file <path>";
+var OPENCLAW_DEVICE_APPROVAL_COMMAND_HINT = "Run: openclaw devices list and openclaw devices approve <requestId>";
 var textEncoder2 = new TextEncoder();
 var textDecoder = new TextDecoder();
 function isRecord8(value) {
@@ -21113,11 +21146,11 @@ function parseNonEmptyString8(value, label) {
   }
   return trimmed;
 }
-function parseOptionalName(value) {
+function parseOptionalProfileName(value, label) {
   if (value === void 0) {
     return void 0;
   }
-  return parseNonEmptyString8(value, "name");
+  return parseNonEmptyString8(value, label);
 }
 function parsePeerAlias(value) {
   const alias = parseNonEmptyString8(value, "peer alias");
@@ -21374,12 +21407,13 @@ async function loadPeersConfig(peersPath) {
     }
     const did = parseAgentDid2(value.did, `Peer ${normalizedAlias} did`);
     const proxyUrl = parseProxyUrl(value.proxyUrl);
-    const name = parseOptionalName(value.name);
-    if (name === void 0) {
+    const agentName = parseOptionalProfileName(value.agentName, "agentName");
+    const humanName = parseOptionalProfileName(value.humanName, "humanName");
+    if (agentName === void 0 && humanName === void 0) {
       peers[normalizedAlias] = { did, proxyUrl };
       continue;
     }
-    peers[normalizedAlias] = { did, proxyUrl, name };
+    peers[normalizedAlias] = { did, proxyUrl, agentName, humanName };
   }
   return { peers };
 }
@@ -21739,9 +21773,11 @@ function parseRelayRuntimeConfig(value, relayRuntimeConfigPath) {
   }
   const updatedAt = typeof value.updatedAt === "string" && value.updatedAt.trim().length > 0 ? value.updatedAt.trim() : void 0;
   const openclawHookToken = typeof value.openclawHookToken === "string" && value.openclawHookToken.trim().length > 0 ? value.openclawHookToken.trim() : void 0;
+  const relayTransformPeersPath = typeof value.relayTransformPeersPath === "string" && value.relayTransformPeersPath.trim().length > 0 ? value.relayTransformPeersPath.trim() : void 0;
   return {
     openclawBaseUrl: parseOpenclawBaseUrl(value.openclawBaseUrl),
     openclawHookToken,
+    relayTransformPeersPath,
     updatedAt
   };
 }
@@ -21757,10 +21793,11 @@ async function loadRelayRuntimeConfig(relayRuntimeConfigPath) {
   }
   return parseRelayRuntimeConfig(parsed, relayRuntimeConfigPath);
 }
-async function saveRelayRuntimeConfig(relayRuntimeConfigPath, openclawBaseUrl, openclawHookToken) {
+async function saveRelayRuntimeConfig(relayRuntimeConfigPath, openclawBaseUrl, openclawHookToken, relayTransformPeersPath) {
   const config2 = {
     openclawBaseUrl,
     ...openclawHookToken ? { openclawHookToken } : {},
+    ...relayTransformPeersPath ? { relayTransformPeersPath } : {},
     updatedAt: nowIso()
   };
   await writeSecureFile3(
@@ -21807,33 +21844,40 @@ function normalizeStringArrayWithValues(value, requiredValues) {
   return Array.from(normalized);
 }
 function resolveHookDefaultSessionKey(config2, hooks) {
-  if (typeof hooks.defaultSessionKey === "string" && hooks.defaultSessionKey.trim().length > 0) {
-    return hooks.defaultSessionKey.trim();
-  }
   const session = isRecord8(config2.session) ? config2.session : {};
   const scope = typeof session.scope === "string" ? session.scope.trim().toLowerCase() : "";
+  const configuredMainSessionKey = resolveConfiguredOpenclawMainSessionKey(session);
+  if (typeof hooks.defaultSessionKey === "string" && hooks.defaultSessionKey.trim().length > 0) {
+    return normalizeLegacyHookDefaultSessionKey(
+      hooks.defaultSessionKey,
+      configuredMainSessionKey
+    );
+  }
   if (scope === "global") {
     return "global";
   }
-  const agents = isRecord8(config2.agents) ? config2.agents : {};
-  const agentList = Array.isArray(agents.list) ? agents.list : [];
-  const defaultAgentId = resolveDefaultOpenclawAgentId(agentList);
-  return `agent:${defaultAgentId}:${DEFAULT_OPENCLAW_MAIN_SESSION_KEY}`;
+  return configuredMainSessionKey;
 }
-function resolveDefaultOpenclawAgentId(agentList) {
-  const preferred = agentList.find(
-    (agent) => isRecord8(agent) && agent.default === true && typeof agent.id === "string" && agent.id.trim().length > 0
-  ) ?? agentList.find(
-    (agent) => isRecord8(agent) && typeof agent.id === "string" && agent.id.trim().length > 0
-  );
-  if (isRecord8(preferred) && typeof preferred.id === "string" && preferred.id.trim().length > 0) {
-    return normalizeOpenclawIdToken(preferred.id, DEFAULT_OPENCLAW_AGENT_ID);
+function resolveConfiguredOpenclawMainSessionKey(session) {
+  if (typeof session.mainKey === "string" && session.mainKey.trim().length > 0) {
+    return session.mainKey.trim();
+  }
+  return DEFAULT_OPENCLAW_MAIN_SESSION_KEY;
+}
+function normalizeLegacyHookDefaultSessionKey(value, fallbackSessionKey) {
+  const trimmed = value.trim();
+  const legacyMatch = /^agent:[^:]+:(.+)$/i.exec(trimmed);
+  if (!legacyMatch) {
+    return trimmed;
+  }
+  const routedSessionKey = legacyMatch[1]?.trim();
+  if (typeof routedSessionKey === "string" && routedSessionKey.length > 0) {
+    return routedSessionKey;
   }
-  return DEFAULT_OPENCLAW_AGENT_ID;
+  return fallbackSessionKey;
 }
-function normalizeOpenclawIdToken(value, fallback) {
-  const normalized = value.trim().toLowerCase().replace(/[^a-z0-9_-]+/g, "-").replace(/^-+/g, "").replace(/-+$/g, "").slice(0, 64);
-  return normalized.length > 0 ? normalized : fallback;
+function isCanonicalAgentSessionKey(value) {
+  return /^agent:[^:]+:.+/i.test(value.trim());
 }
 function generateOpenclawHookToken() {
   return randomBytes3(OPENCLAW_HOOK_TOKEN_BYTES).toString("hex");
@@ -22017,103 +22061,105 @@ async function runOpenclawDoctor(options = {}) {
   const openclawDir = resolveOpenclawDir(options.openclawDir, homeDir);
   const peerAlias = parseDoctorPeerAlias(options.peerAlias);
   const checks = [];
-  const resolveConfigImpl = options.resolveConfigImpl ?? resolveConfig;
-  try {
-    const resolvedConfig = await resolveConfigImpl();
-    const envProxyUrl = typeof process.env.CLAWDENTITY_PROXY_URL === "string" ? process.env.CLAWDENTITY_PROXY_URL.trim() : "";
-    if (typeof resolvedConfig.registryUrl !== "string" || resolvedConfig.registryUrl.trim().length === 0) {
-      checks.push(
-        toDoctorCheck({
-          id: "config.registry",
-          label: "CLI config",
-          status: "fail",
-          message: "registryUrl is missing",
-          remediationHint: "Run: clawdentity config set registryUrl <REGISTRY_URL>"
-        })
-      );
-    } else if (typeof resolvedConfig.apiKey !== "string" || resolvedConfig.apiKey.trim().length === 0) {
-      checks.push(
-        toDoctorCheck({
-          id: "config.registry",
-          label: "CLI config",
-          status: "fail",
-          message: "apiKey is missing",
-          remediationHint: "Run: clawdentity config set apiKey <API_KEY>"
-        })
-      );
-    } else if (envProxyUrl.length > 0) {
-      let hasValidEnvProxyUrl = true;
-      try {
-        parseProxyUrl(envProxyUrl);
-      } catch {
-        hasValidEnvProxyUrl = false;
+  if (options.includeConfigCheck !== false) {
+    const resolveConfigImpl = options.resolveConfigImpl ?? resolveConfig;
+    try {
+      const resolvedConfig = await resolveConfigImpl();
+      const envProxyUrl = typeof process.env.CLAWDENTITY_PROXY_URL === "string" ? process.env.CLAWDENTITY_PROXY_URL.trim() : "";
+      if (typeof resolvedConfig.registryUrl !== "string" || resolvedConfig.registryUrl.trim().length === 0) {
         checks.push(
           toDoctorCheck({
             id: "config.registry",
             label: "CLI config",
             status: "fail",
-            message: "CLAWDENTITY_PROXY_URL is invalid",
-            remediationHint: "Set CLAWDENTITY_PROXY_URL to a valid http(s) URL or unset it"
+            message: "registryUrl is missing",
+            remediationHint: "Run: clawdentity config set registryUrl <REGISTRY_URL>"
           })
         );
-      }
-      if (hasValidEnvProxyUrl) {
+      } else if (typeof resolvedConfig.apiKey !== "string" || resolvedConfig.apiKey.trim().length === 0) {
         checks.push(
           toDoctorCheck({
             id: "config.registry",
             label: "CLI config",
-            status: "pass",
-            message: "registryUrl and apiKey are configured (proxy URL override is active via CLAWDENTITY_PROXY_URL)"
+            status: "fail",
+            message: "apiKey is missing",
+            remediationHint: "Run: clawdentity config set apiKey <API_KEY>"
           })
         );
-      }
-    } else if (typeof resolvedConfig.proxyUrl !== "string" || resolvedConfig.proxyUrl.trim().length === 0) {
-      checks.push(
-        toDoctorCheck({
-          id: "config.registry",
-          label: "CLI config",
-          status: "fail",
-          message: "proxyUrl is missing",
-          remediationHint: "Run: clawdentity invite redeem <clw_inv_...> or clawdentity config init"
-        })
-      );
-    } else {
-      let hasValidConfigProxyUrl = true;
-      try {
-        parseProxyUrl(resolvedConfig.proxyUrl);
-      } catch {
-        hasValidConfigProxyUrl = false;
+      } else if (envProxyUrl.length > 0) {
+        let hasValidEnvProxyUrl = true;
+        try {
+          parseProxyUrl(envProxyUrl);
+        } catch {
+          hasValidEnvProxyUrl = false;
+          checks.push(
+            toDoctorCheck({
+              id: "config.registry",
+              label: "CLI config",
+              status: "fail",
+              message: "CLAWDENTITY_PROXY_URL is invalid",
+              remediationHint: "Set CLAWDENTITY_PROXY_URL to a valid http(s) URL or unset it"
+            })
+          );
+        }
+        if (hasValidEnvProxyUrl) {
+          checks.push(
+            toDoctorCheck({
+              id: "config.registry",
+              label: "CLI config",
+              status: "pass",
+              message: "registryUrl and apiKey are configured (proxy URL override is active via CLAWDENTITY_PROXY_URL)"
+            })
+          );
+        }
+      } else if (typeof resolvedConfig.proxyUrl !== "string" || resolvedConfig.proxyUrl.trim().length === 0) {
         checks.push(
           toDoctorCheck({
             id: "config.registry",
             label: "CLI config",
             status: "fail",
-            message: "proxyUrl is invalid",
+            message: "proxyUrl is missing",
             remediationHint: "Run: clawdentity invite redeem <clw_inv_...> or clawdentity config init"
           })
         );
+      } else {
+        let hasValidConfigProxyUrl = true;
+        try {
+          parseProxyUrl(resolvedConfig.proxyUrl);
+        } catch {
+          hasValidConfigProxyUrl = false;
+          checks.push(
+            toDoctorCheck({
+              id: "config.registry",
+              label: "CLI config",
+              status: "fail",
+              message: "proxyUrl is invalid",
+              remediationHint: "Run: clawdentity invite redeem <clw_inv_...> or clawdentity config init"
+            })
+          );
+        }
+        if (hasValidConfigProxyUrl) {
+          checks.push(
+            toDoctorCheck({
+              id: "config.registry",
+              label: "CLI config",
+              status: "pass",
+              message: "registryUrl, apiKey, and proxyUrl are configured"
+            })
+          );
+        }
       }
-      if (hasValidConfigProxyUrl) {
-        checks.push(
-          toDoctorCheck({
-            id: "config.registry",
-            label: "CLI config",
-            status: "pass",
-            message: "registryUrl, apiKey, and proxyUrl are configured"
-          })
-        );
-      }
+    } catch {
+      checks.push(
+        toDoctorCheck({
+          id: "config.registry",
+          label: "CLI config",
+          status: "fail",
+          message: "unable to resolve CLI config",
+          remediationHint: "Fix ~/.clawdentity/config.json or rerun: clawdentity config init"
+        })
+      );
     }
-  } catch {
-    checks.push(
-      toDoctorCheck({
-        id: "config.registry",
-        label: "CLI config",
-        status: "fail",
-        message: "unable to resolve CLI config",
-        remediationHint: "Fix ~/.clawdentity/config.json or rerun: clawdentity config init"
-      })
-    );
   }
   const selectedAgentPath = resolveOpenclawAgentNamePath(homeDir);
   let selectedAgentName;
@@ -22302,6 +22348,15 @@ async function runOpenclawDoctor(options = {}) {
     const hooks = isRecord8(openclawConfig.hooks) ? openclawConfig.hooks : {};
     const hooksEnabled = hooks.enabled === true;
     const hookToken = typeof hooks.token === "string" && hooks.token.trim().length > 0 ? hooks.token.trim() : void 0;
+    const defaultSessionKey = typeof hooks.defaultSessionKey === "string" && hooks.defaultSessionKey.trim().length > 0 ? hooks.defaultSessionKey.trim() : void 0;
+    const allowRequestSessionKey = hooks.allowRequestSessionKey === false;
+    const allowedSessionKeyPrefixes = normalizeStringArrayWithValues(
+      hooks.allowedSessionKeyPrefixes,
+      []
+    );
+    const missingRequiredSessionPrefixes = defaultSessionKey === void 0 ? ["hook:"] : ["hook:", defaultSessionKey].filter(
+      (prefix) => !allowedSessionKeyPrefixes.includes(prefix)
+    );
     const mappings = Array.isArray(hooks.mappings) ? hooks.mappings.filter(isRecord8) : [];
     const relayMapping = mappings.find(
       (mapping) => isRelayHookMapping(mapping)
@@ -22361,6 +22416,45 @@ async function runOpenclawDoctor(options = {}) {
         })
       );
     }
+    const sessionRoutingIssues = [];
+    if (defaultSessionKey === void 0) {
+      sessionRoutingIssues.push("hooks.defaultSessionKey is missing");
+    }
+    if (!allowRequestSessionKey) {
+      sessionRoutingIssues.push("hooks.allowRequestSessionKey is not false");
+    }
+    if (missingRequiredSessionPrefixes.length > 0) {
+      sessionRoutingIssues.push(
+        `hooks.allowedSessionKeyPrefixes is missing: ${missingRequiredSessionPrefixes.join(", ")}`
+      );
+    }
+    if (defaultSessionKey !== void 0 && isCanonicalAgentSessionKey(defaultSessionKey)) {
+      sessionRoutingIssues.push(
+        "hooks.defaultSessionKey uses canonical agent format (agent:<id>:...); use OpenClaw request session keys like main, global, or subagent:*"
+      );
+    }
+    if (sessionRoutingIssues.length > 0) {
+      checks.push(
+        toDoctorCheck({
+          id: "state.hookSessionRouting",
+          label: "OpenClaw hook session routing",
+          status: "fail",
+          message: sessionRoutingIssues.join("; "),
+          remediationHint: OPENCLAW_SETUP_RESTART_COMMAND_HINT,
+          details: { openclawConfigPath }
+        })
+      );
+    } else {
+      checks.push(
+        toDoctorCheck({
+          id: "state.hookSessionRouting",
+          label: "OpenClaw hook session routing",
+          status: "pass",
+          message: "hooks default session and allowed session prefixes are configured",
+          details: { openclawConfigPath }
+        })
+      );
+    }
   } catch {
     checks.push(
       toDoctorCheck({
@@ -22382,6 +22476,16 @@ async function runOpenclawDoctor(options = {}) {
         details: { openclawConfigPath }
       })
     );
+    checks.push(
+      toDoctorCheck({
+        id: "state.hookSessionRouting",
+        label: "OpenClaw hook session routing",
+        status: "fail",
+        message: `unable to read ${openclawConfigPath}`,
+        remediationHint: "Ensure the OpenClaw config file exists (OPENCLAW_CONFIG_PATH/CLAWDBOT_CONFIG_PATH, or state dir) and rerun openclaw setup",
+        details: { openclawConfigPath }
+      })
+    );
   }
   const relayRuntimeConfigPath = resolveRelayRuntimeConfigPath(homeDir);
   try {
@@ -22407,6 +22511,72 @@ async function runOpenclawDoctor(options = {}) {
       })
     );
   }
+  const gatewayDevicePendingPath = join6(openclawDir, "devices", "pending.json");
+  try {
+    const pendingPayload = await readJsonFile(gatewayDevicePendingPath);
+    if (!isRecord8(pendingPayload)) {
+      checks.push(
+        toDoctorCheck({
+          id: "state.gatewayDevicePairing",
+          label: "OpenClaw gateway device pairing",
+          status: "fail",
+          message: `invalid pending device approvals file: ${gatewayDevicePendingPath}`,
+          remediationHint: OPENCLAW_DEVICE_APPROVAL_COMMAND_HINT,
+          details: { gatewayDevicePendingPath }
+        })
+      );
+    } else {
+      const pendingRequestIds = Object.keys(pendingPayload);
+      if (pendingRequestIds.length === 0) {
+        checks.push(
+          toDoctorCheck({
+            id: "state.gatewayDevicePairing",
+            label: "OpenClaw gateway device pairing",
+            status: "pass",
+            message: "no pending gateway device approvals",
+            details: { gatewayDevicePendingPath }
+          })
+        );
+      } else {
+        checks.push(
+          toDoctorCheck({
+            id: "state.gatewayDevicePairing",
+            label: "OpenClaw gateway device pairing",
+            status: "fail",
+            message: `pending gateway device approvals: ${pendingRequestIds.length}`,
+            remediationHint: OPENCLAW_DEVICE_APPROVAL_COMMAND_HINT,
+            details: {
+              gatewayDevicePendingPath,
+              pendingRequestIds
+            }
+          })
+        );
+      }
+    }
+  } catch (error48) {
+    if (getErrorCode2(error48) === "ENOENT") {
+      checks.push(
+        toDoctorCheck({
+          id: "state.gatewayDevicePairing",
+          label: "OpenClaw gateway device pairing",
+          status: "pass",
+          message: "no pending gateway device approvals file was found",
+          details: { gatewayDevicePendingPath }
+        })
+      );
+    } else {
+      checks.push(
+        toDoctorCheck({
+          id: "state.gatewayDevicePairing",
+          label: "OpenClaw gateway device pairing",
+          status: "fail",
+          message: `unable to read pending device approvals at ${gatewayDevicePendingPath}`,
+          remediationHint: OPENCLAW_DEVICE_APPROVAL_COMMAND_HINT,
+          details: { gatewayDevicePendingPath }
+        })
+      );
+    }
+  }
   if (options.includeConnectorRuntimeCheck !== false) {
     if (selectedAgentName === void 0) {
       checks.push(
@@ -22769,7 +22939,8 @@ async function setupOpenclawRelay(agentName, options) {
   await saveRelayRuntimeConfig(
     relayRuntimeConfigPath,
     openclawBaseUrl,
-    patchedOpenclawConfig.hookToken
+    patchedOpenclawConfig.hookToken,
+    relayTransformPeersPath
   );
   logger8.info("cli.openclaw_setup_completed", {
     agentName: normalizedAgentName,
@@ -22791,9 +22962,45 @@ async function setupOpenclawRelay(agentName, options) {
     relayRuntimeConfigPath
   };
 }
+async function assertSetupChecklistHealthy(input) {
+  const checklist = await runOpenclawDoctor({
+    homeDir: input.homeDir,
+    openclawDir: input.openclawDir,
+    includeConfigCheck: false,
+    includeConnectorRuntimeCheck: input.includeConnectorRuntimeCheck
+  });
+  if (checklist.status === "healthy") {
+    return;
+  }
+  const firstFailure = checklist.checks.find((check2) => check2.status === "fail");
+  throw createCliError6(
+    "CLI_OPENCLAW_SETUP_CHECKLIST_FAILED",
+    "OpenClaw setup checklist failed",
+    {
+      firstFailedCheckId: firstFailure?.id,
+      firstFailedCheckMessage: firstFailure?.message,
+      remediationHint: firstFailure?.remediationHint,
+      checks: checklist.checks
+    }
+  );
+}
 async function setupOpenclawSelfReady(agentName, options) {
-  const setup = await setupOpenclawRelay(agentName, options);
+  const resolvedHomeDir = resolveHomeDir(options.homeDir);
+  const resolvedOpenclawDir = resolveOpenclawDir(
+    options.openclawDir,
+    resolvedHomeDir
+  );
+  const setup = await setupOpenclawRelay(agentName, {
+    ...options,
+    homeDir: resolvedHomeDir,
+    openclawDir: resolvedOpenclawDir
+  });
   if (options.noRuntimeStart === true) {
+    await assertSetupChecklistHealthy({
+      homeDir: resolvedHomeDir,
+      openclawDir: resolvedOpenclawDir,
+      includeConnectorRuntimeCheck: false
+    });
     return {
       ...setup,
       runtimeMode: "none",
@@ -22812,7 +23019,6 @@ async function setupOpenclawSelfReady(agentName, options) {
   const waitTimeoutSeconds = parseWaitTimeoutSeconds(
     options.waitTimeoutSeconds
   );
-  const resolvedHomeDir = resolveHomeDir(options.homeDir);
   const runtime = await startSetupConnectorRuntime({
     agentName: assertValidAgentName(agentName),
     homeDir: resolvedHomeDir,
@@ -22822,6 +23028,11 @@ async function setupOpenclawSelfReady(agentName, options) {
     waitTimeoutSeconds,
     fetchImpl
   });
+  await assertSetupChecklistHealthy({
+    homeDir: resolvedHomeDir,
+    openclawDir: resolvedOpenclawDir,
+    includeConnectorRuntimeCheck: true
+  });
   return {
     ...setup,
     ...runtime
@@ -22967,6 +23178,7 @@ var AIT_FILE_NAME4 = "ait.jwt";
 var SECRET_KEY_FILE_NAME3 = "secret.key";
 var PAIRING_QR_DIR_NAME = "pairing";
 var PEERS_FILE_NAME2 = "peers.json";
+var OPENCLAW_RELAY_RUNTIME_FILE_NAME3 = "openclaw-relay.json";
 var PAIR_START_PATH = "/pair/start";
 var PAIR_CONFIRM_PATH = "/pair/confirm";
 var PAIR_STATUS_PATH = "/pair/status";
@@ -22978,6 +23190,7 @@ var FILE_MODE4 = 384;
 var PEER_ALIAS_PATTERN2 = /^[a-zA-Z0-9._-]+$/;
 var DEFAULT_STATUS_WAIT_SECONDS = 300;
 var DEFAULT_STATUS_POLL_INTERVAL_SECONDS = 3;
+var MAX_PROFILE_NAME_LENGTH = 64;
 var isRecord9 = (value) => {
   return typeof value === "object" && value !== null;
 };
@@ -22994,6 +23207,49 @@ function parseNonEmptyString9(value) {
   }
   return value.trim();
 }
+function hasControlChars2(value) {
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    if (code <= 31 || code === 127) {
+      return true;
+    }
+  }
+  return false;
+}
+function parseProfileName(value, label) {
+  const candidate = parseNonEmptyString9(value);
+  if (candidate.length === 0) {
+    throw createCliError7(
+      "CLI_PAIR_PROFILE_INVALID",
+      `${label} is required for pairing`
+    );
+  }
+  if (candidate.length > MAX_PROFILE_NAME_LENGTH) {
+    throw createCliError7(
+      "CLI_PAIR_PROFILE_INVALID",
+      `${label} must be at most ${MAX_PROFILE_NAME_LENGTH} characters`
+    );
+  }
+  if (hasControlChars2(candidate)) {
+    throw createCliError7(
+      "CLI_PAIR_PROFILE_INVALID",
+      `${label} contains control characters`
+    );
+  }
+  return candidate;
+}
+function parsePeerProfile(payload) {
+  if (!isRecord9(payload)) {
+    throw createCliError7(
+      "CLI_PAIR_PROFILE_INVALID",
+      "Pair profile must be an object"
+    );
+  }
+  return {
+    agentName: parseProfileName(payload.agentName, "agentName"),
+    humanName: parseProfileName(payload.humanName, "humanName")
+  };
+}
 function parsePairingTicket(value) {
   const ticket = parseNonEmptyString9(value);
   if (!ticket.startsWith(PAIRING_TICKET_PREFIX)) {
@@ -23158,10 +23414,19 @@ function parsePeerEntry(value) {
       "Peer entry is invalid"
     );
   }
-  return {
+  const agentNameRaw = parseNonEmptyString9(value.agentName);
+  const humanNameRaw = parseNonEmptyString9(value.humanName);
+  const entry = {
     did,
     proxyUrl
   };
+  if (agentNameRaw.length > 0) {
+    entry.agentName = parseProfileName(agentNameRaw, "agentName");
+  }
+  if (humanNameRaw.length > 0) {
+    entry.humanName = parseProfileName(humanNameRaw, "humanName");
+  }
+  return entry;
 }
 async function loadPeersConfig2(input) {
   const peersPath = resolvePeersConfigPath(input.getConfigDirImpl);
@@ -23216,6 +23481,86 @@ async function savePeersConfig2(input) {
   );
   await input.chmodImpl(peersPath, FILE_MODE4);
 }
+function resolveRelayRuntimeConfigPath2(getConfigDirImpl) {
+  return join7(getConfigDirImpl(), OPENCLAW_RELAY_RUNTIME_FILE_NAME3);
+}
+async function loadRelayTransformPeersPath(input) {
+  const relayRuntimeConfigPath = resolveRelayRuntimeConfigPath2(
+    input.getConfigDirImpl
+  );
+  let raw;
+  try {
+    raw = await input.readFileImpl(relayRuntimeConfigPath, "utf8");
+  } catch (error48) {
+    const nodeError = error48;
+    if (nodeError.code === "ENOENT") {
+      return void 0;
+    }
+    logger9.warn("cli.pair.relay_runtime_read_failed", {
+      relayRuntimeConfigPath,
+      reason: error48 instanceof Error && error48.message.length > 0 ? error48.message : "unknown"
+    });
+    return void 0;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    logger9.warn("cli.pair.relay_runtime_invalid_json", {
+      relayRuntimeConfigPath
+    });
+    return void 0;
+  }
+  if (!isRecord9(parsed)) {
+    return void 0;
+  }
+  const relayTransformPeersPath = parseNonEmptyString9(
+    parsed.relayTransformPeersPath
+  );
+  if (relayTransformPeersPath.length === 0) {
+    return void 0;
+  }
+  return resolve(relayTransformPeersPath);
+}
+async function syncOpenclawRelayPeersSnapshot(input) {
+  const relayTransformPeersPath = await loadRelayTransformPeersPath({
+    getConfigDirImpl: input.getConfigDirImpl,
+    readFileImpl: input.readFileImpl
+  });
+  if (relayTransformPeersPath === void 0) {
+    return;
+  }
+  try {
+    await input.readFileImpl(relayTransformPeersPath, "utf8");
+  } catch (error48) {
+    const nodeError = error48;
+    if (nodeError.code === "ENOENT") {
+      return;
+    }
+    logger9.warn("cli.pair.relay_peers_snapshot_probe_failed", {
+      relayTransformPeersPath,
+      reason: error48 instanceof Error && error48.message.length > 0 ? error48.message : "unknown"
+    });
+    return;
+  }
+  try {
+    await input.mkdirImpl(dirname5(relayTransformPeersPath), {
+      recursive: true
+    });
+    await input.writeFileImpl(
+      relayTransformPeersPath,
+      `${JSON.stringify(input.config, null, 2)}
+`,
+      "utf8"
+    );
+    await input.chmodImpl(relayTransformPeersPath, FILE_MODE4);
+  } catch (error48) {
+    logger9.warn("cli.pair.relay_peers_snapshot_write_failed", {
+      relayTransformPeersPath,
+      reason: error48 instanceof Error && error48.message.length > 0 ? error48.message : "unknown"
+    });
+  }
+}
 function parseTtlSeconds(value) {
   const raw = parseNonEmptyString9(value);
   if (raw.length === 0) {
@@ -23244,6 +23589,19 @@ function parsePositiveIntegerOption(input) {
   }
   return parsed;
 }
+function resolveLocalPairProfile(input) {
+  const humanName = parseNonEmptyString9(input.config.humanName);
+  if (humanName.length === 0) {
+    throw createCliError7(
+      "CLI_PAIR_HUMAN_NAME_MISSING",
+      "Human name is missing. Run `clawdentity invite redeem <clw_inv_...> --display-name <name>` or `clawdentity config set humanName <name>`."
+    );
+  }
+  return {
+    agentName: parseProfileName(input.agentName, "agentName"),
+    humanName: parseProfileName(humanName, "humanName")
+  };
+}
 function parseProxyUrl2(candidate) {
   try {
     const parsed = new URL(candidate);
@@ -23394,15 +23752,25 @@ function parsePairStartResponse(payload) {
   const ticket = parsePairingTicket(payload.ticket);
   const initiatorAgentDid = parseNonEmptyString9(payload.initiatorAgentDid);
   const expiresAt = parseNonEmptyString9(payload.expiresAt);
+  let initiatorProfile;
   if (initiatorAgentDid.length === 0 || expiresAt.length === 0) {
     throw createCliError7(
       "CLI_PAIR_START_INVALID_RESPONSE",
       "Pair start response is invalid"
     );
   }
+  try {
+    initiatorProfile = parsePeerProfile(payload.initiatorProfile);
+  } catch {
+    throw createCliError7(
+      "CLI_PAIR_START_INVALID_RESPONSE",
+      "Pair start response is invalid"
+    );
+  }
   return {
     ticket,
     initiatorAgentDid,
+    initiatorProfile,
     expiresAt
   };
 }
@@ -23416,16 +23784,29 @@ function parsePairConfirmResponse(payload) {
   const paired = payload.paired === true;
   const initiatorAgentDid = parseNonEmptyString9(payload.initiatorAgentDid);
   const responderAgentDid = parseNonEmptyString9(payload.responderAgentDid);
+  let initiatorProfile;
+  let responderProfile;
   if (!paired || initiatorAgentDid.length === 0 || responderAgentDid.length === 0) {
     throw createCliError7(
       "CLI_PAIR_CONFIRM_INVALID_RESPONSE",
       "Pair confirm response is invalid"
     );
   }
+  try {
+    initiatorProfile = parsePeerProfile(payload.initiatorProfile);
+    responderProfile = parsePeerProfile(payload.responderProfile);
+  } catch {
+    throw createCliError7(
+      "CLI_PAIR_CONFIRM_INVALID_RESPONSE",
+      "Pair confirm response is invalid"
+    );
+  }
   return {
     paired,
     initiatorAgentDid,
-    responderAgentDid
+    responderAgentDid,
+    initiatorProfile,
+    responderProfile
   };
 }
 function parsePairStatusResponse(payload) {
@@ -23446,6 +23827,7 @@ function parsePairStatusResponse(payload) {
   const responderAgentDid = parseNonEmptyString9(payload.responderAgentDid);
   const expiresAt = parseNonEmptyString9(payload.expiresAt);
   const confirmedAt = parseNonEmptyString9(payload.confirmedAt);
+  let initiatorProfile;
   if (initiatorAgentDid.length === 0 || expiresAt.length === 0) {
     throw createCliError7(
       "CLI_PAIR_STATUS_INVALID_RESPONSE",
@@ -23458,10 +23840,37 @@ function parsePairStatusResponse(payload) {
       "Pair status response is invalid"
     );
   }
+  try {
+    initiatorProfile = parsePeerProfile(payload.initiatorProfile);
+  } catch {
+    throw createCliError7(
+      "CLI_PAIR_STATUS_INVALID_RESPONSE",
+      "Pair status response is invalid"
+    );
+  }
+  let responderProfile;
+  if (payload.responderProfile !== void 0) {
+    try {
+      responderProfile = parsePeerProfile(payload.responderProfile);
+    } catch {
+      throw createCliError7(
+        "CLI_PAIR_STATUS_INVALID_RESPONSE",
+        "Pair status response is invalid"
+      );
+    }
+  }
+  if (statusRaw === "confirmed" && responderProfile === void 0) {
+    throw createCliError7(
+      "CLI_PAIR_STATUS_INVALID_RESPONSE",
+      "Pair status response is invalid"
+    );
+  }
   return {
     status: statusRaw,
     initiatorAgentDid,
+    initiatorProfile,
     responderAgentDid: responderAgentDid.length > 0 ? responderAgentDid : void 0,
+    responderProfile,
     expiresAt,
     confirmedAt: confirmedAt.length > 0 ? confirmedAt : void 0
   };
@@ -23666,7 +24075,9 @@ async function persistPairedPeer(input) {
   });
   peersConfig.peers[alias] = {
     did: input.peerDid,
-    proxyUrl: peerProxyUrl
+    proxyUrl: peerProxyUrl,
+    agentName: input.peerProfile.agentName,
+    humanName: input.peerProfile.humanName
   };
   await savePeersConfig2({
     config: peersConfig,
@@ -23675,6 +24086,14 @@ async function persistPairedPeer(input) {
     writeFileImpl,
     chmodImpl
   });
+  await syncOpenclawRelayPeersSnapshot({
+    config: peersConfig,
+    getConfigDirImpl,
+    readFileImpl,
+    mkdirImpl,
+    writeFileImpl,
+    chmodImpl
+  });
   return alias;
 }
 async function startPairing(agentName, options, dependencies = {}) {
@@ -23688,13 +24107,19 @@ async function startPairing(agentName, options, dependencies = {}) {
     config: config2,
     fetchImpl
   });
+  const normalizedAgentName = assertValidAgentName(agentName);
+  const initiatorProfile = resolveLocalPairProfile({
+    config: config2,
+    agentName: normalizedAgentName
+  });
   const { ait, secretKey } = await readAgentProofMaterial(
-    agentName,
+    normalizedAgentName,
     dependencies
   );
   const requestUrl = toProxyRequestUrl(proxyUrl, PAIR_START_PATH);
   const requestBody = JSON.stringify({
-    ttlSeconds
+    ttlSeconds,
+    initiatorProfile
   });
   const bodyBytes = new TextEncoder().encode(requestBody);
   const timestampSeconds = nowSecondsImpl();
@@ -23751,6 +24176,11 @@ async function confirmPairing(agentName, options, dependencies = {}) {
   const readFileImpl = dependencies.readFileImpl ?? readFile6;
   const qrDecodeImpl = dependencies.qrDecodeImpl ?? decodeTicketFromPng;
   const config2 = await resolveConfigImpl();
+  const normalizedAgentName = assertValidAgentName(agentName);
+  const responderProfile = resolveLocalPairProfile({
+    config: config2,
+    agentName: normalizedAgentName
+  });
   const ticketSource = resolveConfirmTicketSource(options);
   const proxyUrl = await resolveProxyUrl({
     config: config2,
@@ -23780,11 +24210,14 @@ async function confirmPairing(agentName, options, dependencies = {}) {
     ticket = parsePairingTicket(qrDecodeImpl(new Uint8Array(imageBytes)));
   }
   const { ait, secretKey } = await readAgentProofMaterial(
-    agentName,
+    normalizedAgentName,
     dependencies
   );
   const requestUrl = toProxyRequestUrl(proxyUrl, PAIR_CONFIRM_PATH);
-  const requestBody = JSON.stringify({ ticket });
+  const requestBody = JSON.stringify({
+    ticket,
+    responderProfile
+  });
   const bodyBytes = new TextEncoder().encode(requestBody);
   const timestampSeconds = nowSecondsImpl();
   const nonce = nonceFactoryImpl();
@@ -23820,6 +24253,7 @@ async function confirmPairing(agentName, options, dependencies = {}) {
   const peerAlias = await persistPairedPeer({
     ticket,
     peerDid: parsed.initiatorAgentDid,
+    peerProfile: parsed.initiatorProfile,
     dependencies
   });
   if (ticketSource.source === "qr-file" && ticketSource.qrFilePath) {
@@ -23901,15 +24335,23 @@ async function getPairingStatusOnce(agentName, options, dependencies = {}) {
       );
     }
     const peerDid = callerAgentDid === parsed.initiatorAgentDid ? responderAgentDid : callerAgentDid === responderAgentDid ? parsed.initiatorAgentDid : void 0;
+    const peerProfile = callerAgentDid === parsed.initiatorAgentDid ? parsed.responderProfile : callerAgentDid === responderAgentDid ? parsed.initiatorProfile : void 0;
     if (!peerDid) {
       throw createCliError7(
         "CLI_PAIR_STATUS_FORBIDDEN",
         "Local agent is not a participant in the pairing ticket"
       );
     }
+    if (!peerProfile) {
+      throw createCliError7(
+        "CLI_PAIR_STATUS_INVALID_RESPONSE",
+        "Pair status response is invalid"
+      );
+    }
     peerAlias = await persistPairedPeer({
       ticket,
       peerDid,
+      peerProfile,
       dependencies
     });
   }
@@ -24005,6 +24447,12 @@ var createPairCommand = (dependencies = {}) => {
         writeStdoutLine("Pairing ticket created");
         writeStdoutLine(`Ticket: ${result.ticket}`);
         writeStdoutLine(`Initiator Agent DID: ${result.initiatorAgentDid}`);
+        writeStdoutLine(
+          `Initiator Agent Name: ${result.initiatorProfile.agentName}`
+        );
+        writeStdoutLine(
+          `Initiator Human Name: ${result.initiatorProfile.humanName}`
+        );
         writeStdoutLine(`Expires At: ${result.expiresAt}`);
         if (result.qrPath) {
           writeStdoutLine(`QR File: ${result.qrPath}`);
@@ -24047,6 +24495,14 @@ var createPairCommand = (dependencies = {}) => {
               `Responder Agent DID: ${status.responderAgentDid}`
             );
           }
+          if (status.responderProfile) {
+            writeStdoutLine(
+              `Responder Agent Name: ${status.responderProfile.agentName}`
+            );
+            writeStdoutLine(
+              `Responder Human Name: ${status.responderProfile.humanName}`
+            );
+          }
           if (status.peerAlias) {
             writeStdoutLine(`Peer alias saved: ${status.peerAlias}`);
           }
@@ -24067,7 +24523,19 @@ var createPairCommand = (dependencies = {}) => {
         });
         writeStdoutLine("Pairing confirmed");
         writeStdoutLine(`Initiator Agent DID: ${result.initiatorAgentDid}`);
+        writeStdoutLine(
+          `Initiator Agent Name: ${result.initiatorProfile.agentName}`
+        );
+        writeStdoutLine(
+          `Initiator Human Name: ${result.initiatorProfile.humanName}`
+        );
         writeStdoutLine(`Responder Agent DID: ${result.responderAgentDid}`);
+        writeStdoutLine(
+          `Responder Agent Name: ${result.responderProfile.agentName}`
+        );
+        writeStdoutLine(
+          `Responder Human Name: ${result.responderProfile.humanName}`
+        );
         writeStdoutLine(`Paired: ${result.paired ? "true" : "false"}`);
         if (result.peerAlias) {
           writeStdoutLine(`Peer alias saved: ${result.peerAlias}`);
@@ -24099,9 +24567,23 @@ var createPairCommand = (dependencies = {}) => {
         });
         writeStdoutLine(`Status: ${result.status}`);
         writeStdoutLine(`Initiator Agent DID: ${result.initiatorAgentDid}`);
+        writeStdoutLine(
+          `Initiator Agent Name: ${result.initiatorProfile.agentName}`
+        );
+        writeStdoutLine(
+          `Initiator Human Name: ${result.initiatorProfile.humanName}`
+        );
         if (result.responderAgentDid) {
           writeStdoutLine(`Responder Agent DID: ${result.responderAgentDid}`);
         }
+        if (result.responderProfile) {
+          writeStdoutLine(
+            `Responder Agent Name: ${result.responderProfile.agentName}`
+          );
+          writeStdoutLine(
+            `Responder Human Name: ${result.responderProfile.humanName}`
+          );
+        }
         writeStdoutLine(`Expires At: ${result.expiresAt}`);
         if (result.confirmedAt) {
           writeStdoutLine(`Confirmed At: ${result.confirmedAt}`);