@hermespilot/link 0.3.8 → 0.3.9

package/dist/{chunk-RJB5VUT4.js → chunk-7OVDWXR7.js}

@@ -3970,7 +3970,7 @@ import os2 from "os";
 import path5 from "path";
 
 // src/constants.ts
-var LINK_VERSION = "0.3.8";
+var LINK_VERSION = "0.3.9";
 var LINK_COMMAND = "hermeslink";
 var LINK_DEFAULT_PORT = 52379;
 var LINK_RUNTIME_DIR_NAME = ".hermeslink";
@@ -4455,6 +4455,9 @@ var DEFAULT_START_TIMEOUT_MS = 12e3;
 var HEALTH_TIMEOUT_MS = 1500;
 var MIN_API_SERVER_VERSION = "0.4.0";
 var PROFILE_NAME_PATTERN = /^[a-zA-Z0-9._-]{1,64}$/u;
+var DASHBOARD_STATUS_URL = "http://127.0.0.1:9119/api/status";
+var DASHBOARD_STATUS_TIMEOUT_MS = 1500;
+var MAX_VERSION_LOG_OUTPUT_LENGTH = 1200;
 var gatewayStartInFlightByProfile = /* @__PURE__ */ new Map();
 async function ensureHermesApiServerAvailable(options = {}) {
   const profileName = normalizeProfileName(options.profileName);
@@ -4571,28 +4574,56 @@ async function reloadHermesGateway(options = {}) {
   }
   return ensureHermesApiServerAvailable({ ...options, forceRestart: true });
 }
-async function readHermesVersion() {
-  const { stdout } = await execHermesVersion();
-  const raw = stdout.trim();
-  const version = parseHermesVersion(raw);
-  return {
-    raw,
-    version,
-    supportsApiServer: version ? compareSemver(version, MIN_API_SERVER_VERSION) >= 0 : null
-  };
-}
-async function execHermesVersion() {
+async function readHermesVersion(options = {}) {
   try {
-    return await execFileAsync2(resolveHermesBin(), ["version"], {
-      timeout: 5e3,
-      windowsHide: true
-    });
-  } catch {
-    return await execFileAsync2(resolveHermesBin(), ["--version"], {
-      timeout: 5e3,
-      windowsHide: true
+    const { stdout } = await execHermesVersion(options.logger);
+    const raw = stdout.trim();
+    const version = parseHermesVersion(raw);
+    return buildHermesVersionInfo(raw, version);
+  } catch (cliError) {
+    const dashboardStatusUrl = options.dashboardStatusUrl ?? DASHBOARD_STATUS_URL;
+    void options.logger?.warn("hermes_version_dashboard_fallback_requested", {
+      dashboard_status_url: dashboardStatusUrl,
+      reason: cliError instanceof Error ? cliError.message : String(cliError)
     });
+    try {
+      const fallback = await readHermesDashboardVersion({
+        fetchImpl: options.fetchImpl,
+        statusUrl: dashboardStatusUrl,
+        timeoutMs: options.dashboardTimeoutMs
+      });
+      void options.logger?.info("hermes_version_dashboard_fallback_succeeded", {
+        dashboard_status_url: dashboardStatusUrl,
+        hermes_version: fallback.version
+      });
+      return fallback;
+    } catch (dashboardError) {
+      void options.logger?.warn("hermes_version_dashboard_fallback_failed", {
+        dashboard_status_url: dashboardStatusUrl,
+        error: dashboardError instanceof Error ? dashboardError.message : String(dashboardError)
+      });
+      throw new Error(
+        `Hermes version detection failed. CLI: ${cliError instanceof Error ? cliError.message : String(cliError)}; dashboard fallback: ${dashboardError instanceof Error ? dashboardError.message : String(dashboardError)}`
+      );
+    }
+  }
+}
+async function execHermesVersion(logger) {
+  const hermesBin = resolveHermesBin();
+  const failures = [];
+  for (const args of [["version"], ["--version"]]) {
+    try {
+      return await execFileAsync2(hermesBin, args, {
+        timeout: 5e3,
+        windowsHide: true
+      });
+    } catch (error) {
+      const failure = describeVersionCommandFailure(hermesBin, args, error);
+      failures.push(failure.summary);
+      void logger?.warn("hermes_version_cli_command_failed", failure.fields);
+    }
   }
+  throw new Error(failures.join("; "));
 }
 function assertHermesRunsApiSupported(version, status) {
   if (status !== 404) {
@@ -4617,7 +4648,7 @@ async function startHermesGatewayOnce(paths, profileName, logger) {
   return await gatewayStartInFlightByProfile.get(profileName);
 }
 async function startHermesGateway(paths, profileName, logger) {
-  const version = await readHermesVersion().catch((error) => {
+  const version = await readHermesVersion({ logger }).catch((error) => {
     void logger?.error("gateway_hermes_cli_unavailable", {
       error: error instanceof Error ? error.message : String(error)
     });
@@ -4729,7 +4760,7 @@ async function restartHermesGatewayServiceIfAvailable(options) {
   return {
     pid: null,
     logPath,
-    version: await readHermesVersion().catch(() => null),
+    version: await readHermesVersion({ logger: options.logger }).catch(() => null),
     ...logHint ? { logHint } : {}
   };
 }
@@ -4972,6 +5003,72 @@ function parseHermesVersion(value) {
   const match = /\bv?(\d+\.\d+\.\d+)\b/u.exec(value);
   return match?.[1] ?? null;
 }
+function buildHermesVersionInfo(raw, version) {
+  return {
+    raw,
+    version,
+    supportsApiServer: version ? compareSemver(version, MIN_API_SERVER_VERSION) >= 0 : null
+  };
+}
+async function readHermesDashboardVersion(options = {}) {
+  const fetcher = options.fetchImpl ?? fetch;
+  const controller = new AbortController();
+  const timer = setTimeout(
+    () => controller.abort(),
+    options.timeoutMs ?? DASHBOARD_STATUS_TIMEOUT_MS
+  );
+  try {
+    const response = await fetcher(options.statusUrl ?? DASHBOARD_STATUS_URL, {
+      method: "GET",
+      headers: { accept: "application/json" },
+      signal: controller.signal
+    });
+    if (!response.ok) {
+      throw new Error(`Hermes dashboard returned HTTP ${response.status}`);
+    }
+    const payload = await response.json().catch(() => null);
+    const record = toRecord2(payload);
+    const versionText = readString4(record, "version");
+    if (!versionText) {
+      throw new Error("Hermes dashboard status did not include a version");
+    }
+    const raw = truncateVersionLogOutput(JSON.stringify(record));
+    const version = parseHermesVersion(versionText) ?? parseHermesVersion(raw);
+    return buildHermesVersionInfo(raw, version);
+  } catch (error) {
+    if (error instanceof Error && error.name === "AbortError") {
+      throw new Error("Hermes dashboard version probe timed out");
+    }
+    throw error;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+function describeVersionCommandFailure(hermesBin, args, error) {
+  const message = error instanceof Error ? error.message : String(error);
+  const output = truncateVersionLogOutput(readExecErrorOutput2(error));
+  return {
+    summary: `${hermesBin} ${args.join(" ")} failed: ${message}`,
+    fields: {
+      hermes_bin: hermesBin,
+      command: args.join(" "),
+      error: message,
+      ...output ? { output } : {}
+    }
+  };
+}
+function readExecErrorOutput2(error) {
+  if (typeof error !== "object" || error === null) {
+    return "";
+  }
+  const stdout = "stdout" in error && error.stdout != null ? String(error.stdout) : "";
+  const stderr = "stderr" in error && error.stderr != null ? String(error.stderr) : "";
+  return `${stdout}
+${stderr}`.trim();
+}
+function truncateVersionLogOutput(value) {
+  return value.length > MAX_VERSION_LOG_OUTPUT_LENGTH ? `${value.slice(0, MAX_VERSION_LOG_OUTPUT_LENGTH)}...` : value;
+}
 function compareSemver(left, right) {
   const leftParts = left.split(".").map((part) => Number.parseInt(part, 10));
   const rightParts = right.split(".").map((part) => Number.parseInt(part, 10));
@@ -10671,7 +10768,7 @@ async function createHermesRun(input, options = {}) {
   );
   if (response.status === 404 || response.status === 503) {
     assertHermesRunsApiSupported(
-      await readHermesVersion().catch(() => null),
+      await readHermesVersion({ logger: options.logger }).catch(() => null),
       response.status
     );
     throw new LinkHttpError(
@@ -10698,7 +10795,7 @@ async function streamHermesRunEvents(runId, options = {}) {
     options
   );
   assertHermesRunsApiSupported(
-    await readHermesVersion().catch(() => null),
+    await readHermesVersion({ logger: options.logger }).catch(() => null),
     response.status
   );
   if (!response.ok || !response.body) {
@@ -10741,7 +10838,7 @@ async function streamHermesResponses(input, options = {}) {
   );
   if (response.status === 404 || response.status === 503) {
     assertHermesRunsApiSupported(
-      await readHermesVersion().catch(() => null),
+      await readHermesVersion({ logger: options.logger }).catch(() => null),
       response.status
     );
     throw new LinkHttpError(
@@ -19376,7 +19473,10 @@ var runningUpdate = null;
 async function readHermesUpdateCheck(options) {
   const now = options.now ?? (() => /* @__PURE__ */ new Date());
   const [local, remoteResult] = await Promise.all([
-    readHermesVersion().catch((error) => ({
+    readHermesVersion({
+      fetchImpl: options.fetchImpl,
+      logger: options.logger
+    }).catch((error) => ({
       raw: error instanceof Error ? error.message : String(error),
       version: null
     })),
@@ -21437,6 +21537,17 @@ import path24 from "path";
 import { rm as rm12 } from "fs/promises";
 
 // src/relay/bootstrap.ts
+var RelayNetworkError = class extends Error {
+  constructor(relayBaseUrl, causeMessage) {
+    super(
+      `Cannot reach Hermes Relay at ${relayBaseUrl}. Please check your network connection, VPN, or proxy settings, then try again.`
+    );
+    this.relayBaseUrl = relayBaseUrl;
+    this.causeMessage = causeMessage;
+  }
+  relayBaseUrl;
+  causeMessage;
+};
 async function bootstrapRelayLink(options) {
   const fetcher = options.fetchImpl ?? fetch;
   const baseUrl = options.relayBaseUrl.replace(/\/+$/u, "");
@@ -21477,14 +21588,23 @@ async function bootstrapRelayLink(options) {
   };
 }
 async function postJson(fetcher, url, token, body) {
-  const response = await fetcher(url, {
-    method: "POST",
-    headers: {
-      authorization: `Bearer ${token}`,
-      "content-type": "application/json"
-    },
-    body: JSON.stringify(body)
-  });
+  let response;
+  try {
+    response = await fetcher(url, {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${token}`,
+        "content-type": "application/json"
+      },
+      body: JSON.stringify(body)
+    });
+  } catch (error) {
+    const baseUrl = new URL(url).origin;
+    throw new RelayNetworkError(
+      baseUrl,
+      error instanceof Error ? error.message : String(error)
+    );
+  }
   const payload = await response.json().catch(() => null);
   if (!response.ok) {
     const message = readErrorMessage4(payload) ?? `Relay request failed with HTTP ${response.status}`;
@@ -21512,14 +21632,22 @@ async function preparePairing(paths = resolveRuntimePaths()) {
   const config = await loadConfig(paths);
   const identity = await ensureIdentity(paths);
   const systemInfo = readLinkSystemInfo();
-  const created = await postServerJson(config.serverBaseUrl, "/api/v1/link-pairings", {
-    install_id: identity.install_id,
-    link_id: identity.link_id ?? void 0,
-    display_name: systemInfo.defaultDisplayName,
-    platform: systemInfo.platform,
-    hostname: systemInfo.hostname ?? void 0,
-    public_key_pem: identity.public_key_pem
-  });
+  const created = await postServerJson(
+    config.serverBaseUrl,
+    "/api/v1/link-pairings",
+    {
+      install_id: identity.install_id,
+      link_id: identity.link_id ?? void 0,
+      display_name: systemInfo.defaultDisplayName,
+      platform: systemInfo.platform,
+      hostname: systemInfo.hostname ?? void 0,
+      public_key_pem: identity.public_key_pem
+    },
+    {
+      target: "server",
+      action: "create pairing session"
+    }
+  );
   const relayBaseUrl = created.relayBaseUrl || config.relayBaseUrl;
   let assigned;
   let updatedIdentity;
@@ -21541,28 +21669,43 @@ async function preparePairing(paths = resolveRuntimePaths()) {
       installId: updatedIdentity.install_id,
       publicKeyPem: updatedIdentity.public_key_pem
     });
-    await patchServerJson(config.serverBaseUrl, `/api/v1/link-pairings/${created.sessionId}/link`, created.pairingToken, {
-      install_id: updatedIdentity.install_id,
-      link_id: assigned.linkId,
-      link_version: LINK_VERSION,
-      display_name: systemInfo.defaultDisplayName,
-      platform: systemInfo.platform,
-      hostname: systemInfo.hostname ?? void 0,
-      lan_ips: routes.lanIps,
-      public_ipv4s: routes.publicIpv4s,
-      public_ipv6s: routes.publicIpv6s,
-      preferred_urls: routes.preferredUrls,
-      environment: routes.environment
-    });
+    await patchServerJson(
+      config.serverBaseUrl,
+      `/api/v1/link-pairings/${created.sessionId}/link`,
+      created.pairingToken,
+      {
+        install_id: updatedIdentity.install_id,
+        link_id: assigned.linkId,
+        link_version: LINK_VERSION,
+        display_name: systemInfo.defaultDisplayName,
+        platform: systemInfo.platform,
+        hostname: systemInfo.hostname ?? void 0,
+        lan_ips: routes.lanIps,
+        public_ipv4s: routes.publicIpv4s,
+        public_ipv6s: routes.publicIpv6s,
+        preferred_urls: routes.preferredUrls,
+        environment: routes.environment
+      },
+      {
+        target: "server",
+        action: "finalize pairing"
+      }
+    );
   } catch (error) {
+    const reportedError = error instanceof RelayNetworkError ? createPairingNetworkError({
+      target: "relay",
+      action: "connect to Relay",
+      baseUrl: error.relayBaseUrl,
+      detail: error.causeMessage
+    }) : error;
     await reportPairingErrorToServer({
       serverBaseUrl: config.serverBaseUrl,
       sessionId: created.sessionId,
       source: "link",
       pairingToken: created.pairingToken,
-      error: pairingErrorSnapshot("prepare_pairing", error)
+      error: pairingErrorSnapshot("prepare_pairing", reportedError)
     });
-    throw error;
+    throw reportedError;
   }
   const qrPayload = {
     kind: "hermes_link_pairing",
@@ -21662,6 +21805,10 @@ async function claimPairing(input) {
       {
         claim_token: input.claimToken,
         app_instance_id: input.appInstanceId ?? void 0
+      },
+      {
+        target: "server",
+        action: "verify pairing claim"
       }
     );
   } catch (error) {
@@ -21709,15 +21856,25 @@ async function loadRequiredIdentity2(paths) {
   }
   return identity;
 }
-async function postServerJson(serverBaseUrl, path25, body) {
-  const response = await fetch(`${serverBaseUrl.replace(/\/+$/u, "")}${path25}`, {
-    method: "POST",
-    headers: {
-      accept: "application/json",
-      "content-type": "application/json"
-    },
-    body: JSON.stringify(body)
-  });
+async function postServerJson(serverBaseUrl, path25, body, options) {
+  let response;
+  try {
+    response = await fetch(`${serverBaseUrl.replace(/\/+$/u, "")}${path25}`, {
+      method: "POST",
+      headers: {
+        accept: "application/json",
+        "content-type": "application/json"
+      },
+      body: JSON.stringify(body)
+    });
+  } catch (error) {
+    throw createPairingNetworkError({
+      target: options.target,
+      action: options.action,
+      baseUrl: serverBaseUrl,
+      detail: error instanceof Error ? error.message : String(error)
+    });
+  }
   return readJsonResponse2(response);
 }
 async function reportPairingErrorToServer(input) {
@@ -21750,16 +21907,26 @@ function pairingErrorSnapshot(stage, error) {
     occurred_at: (/* @__PURE__ */ new Date()).toISOString()
   };
 }
-async function patchServerJson(serverBaseUrl, path25, token, body) {
-  const response = await fetch(`${serverBaseUrl.replace(/\/+$/u, "")}${path25}`, {
-    method: "PATCH",
-    headers: {
-      accept: "application/json",
-      authorization: `Bearer ${token}`,
-      "content-type": "application/json"
-    },
-    body: JSON.stringify(body)
-  });
+async function patchServerJson(serverBaseUrl, path25, token, body, options) {
+  let response;
+  try {
+    response = await fetch(`${serverBaseUrl.replace(/\/+$/u, "")}${path25}`, {
+      method: "PATCH",
+      headers: {
+        accept: "application/json",
+        authorization: `Bearer ${token}`,
+        "content-type": "application/json"
+      },
+      body: JSON.stringify(body)
+    });
+  } catch (error) {
+    throw createPairingNetworkError({
+      target: options.target,
+      action: options.action,
+      baseUrl: serverBaseUrl,
+      detail: error instanceof Error ? error.message : String(error)
+    });
+  }
   return readJsonResponse2(response);
 }
 async function readJsonResponse2(response) {
@@ -21781,6 +21948,15 @@ function readErrorMessage5(payload) {
   const message = error.message;
   return typeof message === "string" ? message : null;
 }
+function createPairingNetworkError(input) {
+  const baseMessage = input.target === "server" ? `HermesPilot Server is unreachable while trying to ${input.action}.` : `Hermes Relay is unreachable while trying to ${input.action}.`;
+  const hint = "If you are using a VPN, proxy, or corporate network, try turning it off and retrying.";
+  return new LinkHttpError(
+    503,
+    input.target === "server" ? "pairing_server_unreachable" : "pairing_relay_unreachable",
+    `${baseMessage} Please check whether ${input.baseUrl} is reachable. ${hint} Detail: ${input.detail}`
+  );
+}
 function pairingClaimPath(sessionId, paths) {
   return path24.join(paths.pairingDir, `${Buffer.from(sessionId).toString("base64url")}.claimed.json`);
 }
@@ -22916,6 +23092,7 @@ export {
   createFileLogger,
   getLinkLogFile,
   ensureHermesApiServerAvailable,
+  readHermesVersion,
   loadConfig,
   saveConfig,
   normalizeLanHost,

package/dist/cli/index.js

@@ -22,6 +22,7 @@ import {
   preparePairing,
   probeLocalLinkService,
   readHermesApiServerConfig,
+  readHermesVersion,
   readPairingClaim,
   reportLinkStatusToServer,
   resolveHermesConfigPath,
@@ -32,7 +33,7 @@ import {
   startDaemonProcess,
   startLinkService,
   stopDaemonProcess
-} from "../chunk-RJB5VUT4.js";
+} from "../chunk-7OVDWXR7.js";
 
 // src/cli/index.ts
 import { Command } from "commander";
@@ -273,16 +274,16 @@ var messages = {
     "autostart.alreadyEnabled": "Boot autostart is already enabled via {method}: {path}",
     "pair.description": "Create a Hermes Link pairing session",
     "pair.preflight": "Checking local Hermes configuration before pairing...",
+    "pair.preflight.hermesFiles": "Checking Hermes data directory, config, and environment files...",
+    "pair.preflight.hermesCli": "Checking whether the Hermes CLI is available...",
+    "pair.preflight.hermesApiServer": "Checking whether the Hermes API Server is ready...",
     "pair.hermesHome": "Hermes home: {path}",
+    "pair.hermesVersion": "Hermes CLI: {value}",
     "pair.apiReady": "Hermes API Server is ready on 127.0.0.1:{port}",
-    "pair.preparing": "Preparing pairing session through HermesPilot Server and Relay...",
-    "pair.server": "Server: {url}",
-    "pair.relay": "Relay: {url}",
-    "pair.linkId": "Hermes Link ID: {value}",
-    "pair.code": "Pairing code: {value}",
-    "pair.localApi": "Local API: http://127.0.0.1:{port}",
-    "pair.scan": "Open this pairing page in the HermesPilot App or scan the QR code below:",
-    "pair.openBrowserFailed": "Could not open the system browser automatically. You can still scan the QR code below or open this URL manually: {url}",
+    "pair.preparing": "Creating the pairing session...",
+    "pair.scan": "Please scan the QR code below in the HermesPilot App:",
+    "pair.openPairingPage": "If the QR code is hard to scan, you can open this page locally: {url}",
+    "pair.manualCode": "You can also use the HermesPilot App manual connection mode and enter this pairing code:",
     "pair.expires": "Pairing expires in 10 minutes. Press Ctrl+C to cancel waiting.",
     "pair.claimed": "Pairing succeeded. Starting Hermes Link in the background...",
     "pair.claimedRunning": "Pairing succeeded. Hermes Link is already running in the background.",
@@ -298,6 +299,8 @@ var messages = {
     "doctor.notAssigned": "not assigned",
     "doctor.lanHost": "Configured LAN host: {value}",
     "doctor.networkWarning": "Network note: {message}",
+    "doctor.hermesCli": "Hermes CLI: {value}",
+    "doctor.hermesCliUnavailable": "Hermes CLI is unavailable. Please make sure the `hermes` command can run in this system.",
     "doctor.apiReady": "Hermes API Server: ready",
     "doctor.apiStarted": "Hermes API Server: started and ready",
     "doctor.apiUnavailable": "Hermes API Server: unavailable. {message}",
@@ -306,6 +309,8 @@ var messages = {
     "error.relayLinkInvalid": "Relay did not return a valid link_id.",
     "error.relayEmpty": "Relay returned an empty response.",
     "error.serverHttp": "HermesPilot Server request failed with HTTP {status}.",
+    "error.pairingServerUnreachable": "Could not reach HermesPilot Server while creating the pairing session. Check whether {url} is reachable, then try again. If you use a proxy network, add hermes-server.clawpilot.me and hermes-relay.clawpilot.me to the proxy exclusion list, or temporarily turn off VPN/proxy and retry.",
+    "error.pairingRelayUnreachable": "Could not reach Hermes Relay while creating the pairing session. Check whether {url} is reachable, then try again. If you use a proxy network, add hermes-server.clawpilot.me and hermes-relay.clawpilot.me to the proxy exclusion list, or temporarily turn off VPN/proxy and retry.",
     "error.portInUse": "Local port {port} is already in use by another process. Stop that process or change the Hermes Link port, then run `hermeslink pair` again.",
     "error.pairingRequires": "Pairing needs HermesPilot Server and Relay, but this command could not start a complete pairing session.",
     "error.pairingRequires.detail": "The deployed services may be healthy, but the installed Link package must call Server for a short-lived relay bootstrap token before it can request a link_id."
@@ -363,16 +368,16 @@ var messages = {
     "autostart.alreadyEnabled": "\u5F00\u673A\u81EA\u542F\u5DF2\u542F\u7528\uFF0C\u65B9\u5F0F\uFF1A{method}\uFF0C\u6587\u4EF6\uFF1A{path}",
     "pair.description": "\u521B\u5EFA Hermes Link \u914D\u5BF9\u4F1A\u8BDD",
     "pair.preflight": "\u6B63\u5728\u914D\u5BF9\u524D\u68C0\u67E5\u672C\u673A Hermes \u914D\u7F6E...",
+    "pair.preflight.hermesFiles": "\u6B63\u5728\u68C0\u67E5 Hermes \u6570\u636E\u76EE\u5F55\u3001\u914D\u7F6E\u6587\u4EF6\u548C\u73AF\u5883\u6587\u4EF6...",
+    "pair.preflight.hermesCli": "\u6B63\u5728\u68C0\u67E5 Hermes CLI \u662F\u5426\u53EF\u7528...",
+    "pair.preflight.hermesApiServer": "\u6B63\u5728\u68C0\u67E5 Hermes API Server \u662F\u5426\u5C31\u7EEA...",
     "pair.hermesHome": "Hermes \u6570\u636E\u76EE\u5F55\uFF1A{path}",
+    "pair.hermesVersion": "Hermes CLI\uFF1A{value}",
     "pair.apiReady": "Hermes API Server \u5DF2\u5C31\u7EEA\uFF1A127.0.0.1:{port}",
-    "pair.preparing": "\u6B63\u5728\u901A\u8FC7 HermesPilot Server \u548C Relay \u521B\u5EFA\u914D\u5BF9\u4F1A\u8BDD...",
-    "pair.server": "Server\uFF1A{url}",
-    "pair.relay": "Relay\uFF1A{url}",
-    "pair.linkId": "Hermes Link ID\uFF1A{value}",
-    "pair.code": "\u914D\u5BF9\u7801\uFF1A{value}",
-    "pair.localApi": "\u672C\u5730 API\uFF1Ahttp://127.0.0.1:{port}",
-    "pair.scan": "\u8BF7\u5728 HermesPilot App \u4E2D\u6253\u5F00\u8FD9\u4E2A\u914D\u5BF9\u9875\uFF0C\u6216\u626B\u63CF\u4E0B\u9762\u7684\u4E8C\u7EF4\u7801\uFF1A",
-    "pair.openBrowserFailed": "\u65E0\u6CD5\u81EA\u52A8\u6253\u5F00\u7CFB\u7EDF\u6D4F\u89C8\u5668\u3002\u4F60\u4ECD\u7136\u53EF\u4EE5\u626B\u63CF\u4E0B\u9762\u7684\u4E8C\u7EF4\u7801\uFF0C\u6216\u624B\u52A8\u6253\u5F00\u8FD9\u4E2A\u94FE\u63A5\uFF1A{url}",
+    "pair.preparing": "\u6B63\u5728\u521B\u5EFA\u914D\u5BF9\u4F1A\u8BDD...",
+    "pair.scan": "\u8BF7\u5728 HermesPilot App \u4E2D\u626B\u7801\u4E0B\u9762\u7684\u4E8C\u7EF4\u7801\uFF1A",
+    "pair.openPairingPage": "\u5982\u679C\u4E8C\u7EF4\u7801\u4E0D\u5BB9\u6613\u626B\u63CF\uFF0C\u4F60\u53EF\u4EE5\u5728\u672C\u673A\u6253\u5F00\u8FD9\u4E2A\u9875\u9762\uFF1A{url}",
+    "pair.manualCode": "\u4F60\u4E5F\u53EF\u4EE5\u5728 HermesPilot App \u4E2D\u4F7F\u7528\u624B\u52A8\u8FDE\u63A5\u6A21\u5F0F\uFF0C\u8F93\u5165\u4EE5\u4E0B\u914D\u5BF9\u7801\u8FDB\u884C\u8FDE\u63A5\uFF1A",
     "pair.expires": "\u914D\u5BF9\u4F1A\u8BDD 10 \u5206\u949F\u540E\u8FC7\u671F\u3002\u6309 Ctrl+C \u9000\u51FA\u7B49\u5F85\u3002",
     "pair.claimed": "\u914D\u5BF9\u5DF2\u6210\u529F\u3002\u6B63\u5728\u628A Hermes Link \u5207\u6362\u5230\u540E\u53F0\u8FD0\u884C...",
     "pair.claimedRunning": "\u914D\u5BF9\u5DF2\u6210\u529F\u3002Hermes Link \u5DF2\u5728\u540E\u53F0\u6301\u7EED\u8FD0\u884C\u3002",
@@ -388,6 +393,8 @@ var messages = {
     "doctor.notAssigned": "\u5C1A\u672A\u5206\u914D",
     "doctor.lanHost": "\u5DF2\u914D\u7F6E\u5C40\u57DF\u7F51\u4E3B\u673A\uFF1A{value}",
     "doctor.networkWarning": "\u7F51\u7EDC\u63D0\u793A\uFF1A{message}",
+    "doctor.hermesCli": "Hermes CLI\uFF1A{value}",
+    "doctor.hermesCliUnavailable": "Hermes CLI\uFF1A\u4E0D\u53EF\u7528\u3002\u8BF7\u786E\u8BA4\u5F53\u524D\u7CFB\u7EDF\u53EF\u4EE5\u76F4\u63A5\u8FD0\u884C `hermes` \u547D\u4EE4\u3002",
     "doctor.apiReady": "Hermes API Server\uFF1A\u5DF2\u5C31\u7EEA",
     "doctor.apiStarted": "Hermes API Server\uFF1A\u5DF2\u81EA\u52A8\u542F\u52A8\u5E76\u5C31\u7EEA",
     "doctor.apiUnavailable": "Hermes API Server\uFF1A\u4E0D\u53EF\u7528\u3002{message}",
@@ -396,6 +403,8 @@ var messages = {
     "error.relayLinkInvalid": "Relay \u6CA1\u6709\u8FD4\u56DE\u6709\u6548\u7684 link_id\u3002",
     "error.relayEmpty": "Relay \u8FD4\u56DE\u4E86\u7A7A\u54CD\u5E94\u3002",
     "error.serverHttp": "HermesPilot Server \u8BF7\u6C42\u5931\u8D25\uFF0CHTTP \u72B6\u6001\u7801\uFF1A{status}\u3002",
+    "error.pairingServerUnreachable": "\u521B\u5EFA\u914D\u5BF9\u4F1A\u8BDD\u65F6\u65E0\u6CD5\u8FDE\u63A5 HermesPilot Server\u3002\u8BF7\u5148\u786E\u8BA4 {url} \u53EF\u4EE5\u8BBF\u95EE\uFF0C\u7136\u540E\u91CD\u8BD5\u3002\u91CD\u70B9\u63D0\u9192\uFF1A\u5982\u679C\u4F60\u4F7F\u7528\u4E86\u4EE3\u7406\u7F51\u7EDC\uFF0C\u53EF\u4EE5\u628A hermes-server.clawpilot.me \u548C hermes-relay.clawpilot.me \u52A0\u5165\u4EE3\u7406\u6392\u9664\u540D\u5355\uFF0C\u6216\u4E34\u65F6\u5173\u95ED VPN/\u4EE3\u7406\u540E\u518D\u8BD5\u3002",
+    "error.pairingRelayUnreachable": "\u521B\u5EFA\u914D\u5BF9\u4F1A\u8BDD\u65F6\u65E0\u6CD5\u8FDE\u63A5 Hermes Relay\u3002\u8BF7\u5148\u786E\u8BA4 {url} \u53EF\u4EE5\u8BBF\u95EE\uFF0C\u7136\u540E\u91CD\u8BD5\u3002\u91CD\u70B9\u63D0\u9192\uFF1A\u5982\u679C\u4F60\u4F7F\u7528\u4E86\u4EE3\u7406\u7F51\u7EDC\uFF0C\u53EF\u4EE5\u628A hermes-server.clawpilot.me \u548C hermes-relay.clawpilot.me \u52A0\u5165\u4EE3\u7406\u6392\u9664\u540D\u5355\uFF0C\u6216\u4E34\u65F6\u5173\u95ED VPN/\u4EE3\u7406\u540E\u518D\u8BD5\u3002",
     "error.portInUse": "\u672C\u5730\u7AEF\u53E3 {port} \u5DF2\u88AB\u5176\u4ED6\u8FDB\u7A0B\u5360\u7528\u3002\u8BF7\u5148\u505C\u6B62\u5360\u7528\u8BE5\u7AEF\u53E3\u7684\u7A0B\u5E8F\uFF0C\u6216\u8C03\u6574 Hermes Link \u7AEF\u53E3\u540E\u91CD\u65B0\u8FD0\u884C `hermeslink pair`\u3002",
     "error.pairingRequires": "\u914D\u5BF9\u9700\u8981 HermesPilot Server \u548C Relay\uFF0C\u4F46\u5F53\u524D\u547D\u4EE4\u6CA1\u6709\u80FD\u542F\u52A8\u5B8C\u6574\u914D\u5BF9\u4F1A\u8BDD\u3002",
     "error.pairingRequires.detail": "\u4E91\u7AEF\u670D\u52A1\u53EF\u4EE5\u662F\u5DF2\u90E8\u7F72\u4E14\u5065\u5EB7\u7684\uFF1B\u672C\u673A Link \u4ECD\u5FC5\u987B\u5148\u5411 Server \u7533\u8BF7\u77ED\u671F relay bootstrap token\uFF0C\u624D\u80FD\u518D\u5411 Relay \u7533\u8BF7 link_id\u3002"
@@ -459,6 +468,18 @@ function translateKnownError(message, language) {
   if (serverHttp?.groups?.status) {
     return translate(language, "error.serverHttp", { status: serverHttp.groups.status });
   }
+  const pairingServerUnreachable = /^HermesPilot Server is unreachable while trying to [^.]+\. Please check whether (?<url>\S+) is reachable\./u.exec(message);
+  if (pairingServerUnreachable?.groups?.url) {
+    return translate(language, "error.pairingServerUnreachable", {
+      url: pairingServerUnreachable.groups.url
+    });
+  }
+  const pairingRelayUnreachable = /^Hermes Relay is unreachable while trying to [^.]+\. Please check whether (?<url>\S+) is reachable\./u.exec(message);
+  if (pairingRelayUnreachable?.groups?.url) {
+    return translate(language, "error.pairingRelayUnreachable", {
+      url: pairingRelayUnreachable.groups.url
+    });
+  }
   if (message.includes("Pairing requires HermesPilot Server and Relay")) {
     return [translate(language, "error.pairingRequires"), translate(language, "error.pairingRequires.detail")].join("\n");
   }
@@ -487,6 +508,7 @@ async function assertPairingPreflightReady(options = {}) {
   const configPath = resolveHermesConfigPath(profileName);
   const envPath = path2.join(hermesHome, ".env");
   const failures = [];
+  options.onProgress?.("hermes_files");
   if (!await isDirectory(hermesHome)) {
     failures.push({
       code: "hermes_home_missing",
@@ -517,6 +539,23 @@ async function assertPairingPreflightReady(options = {}) {
   if (failures.length > 0) {
     throwPairingPreflightError(failures);
   }
+  options.onProgress?.("hermes_cli");
+  let hermesVersion;
+  try {
+    const readVersion = options.readHermesVersion ?? readHermesVersion;
+    hermesVersion = await readVersion();
+  } catch {
+    throwPairingPreflightError([
+      {
+        code: "hermes_cli_unavailable",
+        zh: "\u6682\u65F6\u627E\u4E0D\u5230\u53EF\u7528\u7684 Hermes CLI \u547D\u4EE4\u3002",
+        en: "Hermes CLI is not available right now.",
+        actionZh: "\u8BF7\u786E\u8BA4 Hermes Link \u548C Hermes Agent \u5B89\u88C5\u5728\u540C\u4E00\u4E2A\u7CFB\u7EDF\u73AF\u5883\u4E2D\uFF0C\u5E76\u4E14\u7EC8\u7AEF\u80FD\u76F4\u63A5\u8FD0\u884C `hermes`\u3002\u5982\u679C\u4F60\u4F7F\u7528\u4E86\u81EA\u5B9A\u4E49\u5B89\u88C5\u8DEF\u5F84\uFF0C\u4E5F\u53EF\u4EE5\u8BBE\u7F6E HERMES_BIN\u3002",
+        actionEn: "Make sure Hermes Link and Hermes Agent are installed in the same system environment, and that the terminal can run `hermes` directly. If Hermes is installed in a custom location, set HERMES_BIN."
+      }
+    ]);
+  }
+  options.onProgress?.("hermes_api_server");
   const apiServerConfig = await readHermesApiServerConfig(profileName, configPath);
   if (apiServerConfig.enabled !== true) {
     throwPairingPreflightError([
@@ -548,6 +587,10 @@ async function assertPairingPreflightReady(options = {}) {
         started: availability.started,
         host: availability.configResult.apiServer.host ?? null,
         port: availability.configResult.apiServer.port ?? null
+      },
+      hermesVersion: {
+        raw: hermesVersion.raw,
+        version: hermesVersion.version
       }
     };
   } catch (error) {
@@ -780,16 +823,17 @@ program.command("pair").description(helpText("pair.description")).action(async (
   const language = languageChoice.language;
   const t = translate.bind(null, language);
   console.log(t("pair.preflight"));
-  const preflight = await assertPairingPreflightReady({ paths });
   const environment = detectRuntimeEnvironment();
   if (environment.warning) {
     console.log(t("doctor.networkWarning", { message: environment.warning }));
   }
-  console.log(t("pair.hermesHome", { path: preflight.hermesHome }));
-  console.log(t("pair.apiReady", { port: preflight.apiServer.port ?? "unknown" }));
+  await assertPairingPreflightReady({
+    paths,
+    onProgress: (stage) => {
+      console.log(t(pairingPreflightProgressKey(stage)));
+    }
+  });
   console.log(t("pair.preparing"));
-  console.log(t("pair.server", { url: config.serverBaseUrl }));
-  console.log(t("pair.relay", { url: config.relayBaseUrl }));
   await ensureIdentity(paths);
   const hadActiveDevices = await hasActiveDevices(paths);
   const probeBeforePair = await probeLocalLinkService({ port: config.port });
@@ -806,19 +850,12 @@ program.command("pair").description(helpText("pair.description")).action(async (
   const service = reusedRunningService ? null : await startLinkService({ paths });
   const qrValue = JSON.stringify(prepared.qrPayload);
   const pairingPageUrl = `http://127.0.0.1:${config.port}/pair?session_id=${encodeURIComponent(prepared.sessionId)}`;
-  console.log(t("pair.linkId", { value: prepared.linkId }));
-  console.log(t("pair.code", { value: prepared.code }));
-  console.log(t("pair.localApi", { port: config.port }));
-  if (!reusedRunningService) {
-    console.log(t("start.listening", { port: config.port }));
-  }
   console.log(t("pair.scan"));
-  console.log(`Pairing page: ${pairingPageUrl}`);
-  const browserOpened = await openSystemBrowser(pairingPageUrl);
-  if (!browserOpened) {
-    console.log(t("pair.openBrowserFailed", { url: pairingPageUrl }));
-  }
   qrcode.generate(qrValue, { small: true });
+  await openSystemBrowser(pairingPageUrl);
+  console.log(t("pair.openPairingPage", { url: pairingPageUrl }));
+  console.log(t("pair.manualCode"));
+  console.log(prepared.code);
   console.log(t("pair.expires"));
   const result = await waitForPairingOrShutdown(prepared.sessionId, paths);
   if (service) {
@@ -923,6 +960,12 @@ program.command("doctor").description(helpText("doctor.description")).action(asy
       console.log(`Hermes config backup: ${hermesConfig.backupPath}`);
     }
   }
+  try {
+    const hermesVersion = await readHermesVersion();
+    console.log(t("doctor.hermesCli", { value: formatHermesVersion(hermesVersion) }));
+  } catch {
+    console.log(t("doctor.hermesCliUnavailable"));
+  }
   try {
     const availability = await ensureHermesApiServerAvailable({ timeoutMs: 5e3 });
     console.log(t(availability.started ? "doctor.apiStarted" : "doctor.apiReady"));
@@ -939,6 +982,19 @@ async function loadCliLanguage() {
   const config = await loadConfig();
   return resolveLanguage(config.language);
 }
+function formatHermesVersion(version) {
+  return version.version ?? version.raw;
+}
+function pairingPreflightProgressKey(stage) {
+  switch (stage) {
+    case "hermes_files":
+      return "pair.preflight.hermesFiles";
+    case "hermes_cli":
+      return "pair.preflight.hermesCli";
+    case "hermes_api_server":
+      return "pair.preflight.hermesApiServer";
+  }
+}
 async function deliverStagedFilesFromCli(stagingDir, paths, config) {
   try {
     return await deliverStagedFilesThroughDaemon(stagingDir, config.port);

package/dist/http/app.js

@@ -1,6 +1,6 @@
 import {
   createApp
-} from "../chunk-RJB5VUT4.js";
+} from "../chunk-7OVDWXR7.js";
 export {
   createApp
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hermespilot/link",
-  "version": "0.3.8",
+  "version": "0.3.9",
   "private": false,
   "description": "Hermes Link companion service and CLI for connecting hermes-agent through HermesPilot",
   "license": "MIT",