@hermespilot/link 0.6.1 → 0.6.3

package/dist/{chunk-RBMFF32Z.js → chunk-PCJGVIKH.js}

@@ -1183,6 +1183,8 @@ import {
   stat
 } from "fs/promises";
 import path2 from "path";
+var TRANSIENT_RENAME_ERROR_CODES = /* @__PURE__ */ new Set(["EPERM", "EACCES", "EBUSY"]);
+var RENAME_RETRY_DELAYS_MS = [25, 50, 100, 200, 400];
 async function atomicWriteFilePreservingMetadata(filePath, value, options = {}) {
   const resolvedPath = path2.resolve(filePath);
   const directory = path2.dirname(resolvedPath);
@@ -1214,7 +1216,7 @@ async function atomicWriteFilePreservingMetadata(filePath, value, options = {})
       await handle.close();
     }
     await applyMetadata(tempPath, metadata);
-    await rename(tempPath, resolvedPath);
+    await renameWithTransientRetry(tempPath, resolvedPath);
   } catch (error) {
     await rm(tempPath, { force: true });
     throw error;
@@ -1321,6 +1323,30 @@ async function applyOwner(filePath, metadata) {
     }
   }
 }
+async function renameWithTransientRetry(from, to) {
+  let lastError;
+  for (let attempt = 0; attempt <= RENAME_RETRY_DELAYS_MS.length; attempt += 1) {
+    try {
+      await rename(from, to);
+      return;
+    } catch (error) {
+      lastError = error;
+      if (attempt >= RENAME_RETRY_DELAYS_MS.length || !isTransientRenameError(error)) {
+        throw error;
+      }
+      await delay(RENAME_RETRY_DELAYS_MS[attempt]);
+    }
+  }
+  throw lastError;
+}
+function isTransientRenameError(error) {
+  return typeof error === "object" && error !== null && "code" in error && typeof error.code === "string" && TRANSIENT_RENAME_ERROR_CODES.has(error.code);
+}
+function delay(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
 function metadataFromStats(statsValue) {
   return {
     uid: statsValue.uid,
@@ -4852,7 +4878,7 @@ import { execFile as execFile2, spawn } from "child_process";
 import { constants as fsConstants } from "fs";
 import { access, readFile as readFile5, realpath, stat as stat4 } from "fs/promises";
 import path7 from "path";
-import { setTimeout as delay } from "timers/promises";
+import { setTimeout as delay2 } from "timers/promises";
 import { promisify as promisify2 } from "util";
 
 // src/runtime/logger.ts
@@ -4865,7 +4891,7 @@ import os2 from "os";
 import path5 from "path";
 
 // src/constants.ts
-var LINK_VERSION = "0.6.1";
+var LINK_VERSION = "0.6.3";
 var LINK_COMMAND = "hermeslink";
 var LINK_DEFAULT_PORT = 52379;
 var LINK_RUNTIME_DIR_NAME = ".hermeslink";
@@ -5396,6 +5422,17 @@ var HERMES_GATEWAY_ENV_BLOCKLIST_PREFIXES = ["API_SERVER_"];
 var gatewayStartInFlightByProfile = /* @__PURE__ */ new Map();
 var hermesVersionCache = /* @__PURE__ */ new Map();
 var hermesVersionInFlight = /* @__PURE__ */ new Map();
+var HermesApiServerUnavailableError = class extends LinkHttpError {
+  constructor(details) {
+    super(
+      503,
+      "hermes_api_server_unavailable",
+      buildUnavailableErrorMessage(details)
+    );
+    this.details = details;
+  }
+  details;
+};
 async function ensureHermesApiServerAvailable(options = {}) {
   const profileName = normalizeProfileName(options.profileName);
   await assertProfileExists(profileName);
@@ -5426,11 +5463,12 @@ async function ensureHermesApiServerAvailable(options = {}) {
       reason: "auto_start_disabled",
       issue: health.issue ?? "unknown"
     });
-    throw new LinkHttpError(
-      503,
-      "hermes_api_server_unavailable",
-      `${unavailableMessage()}${health.issue ? ` ${health.issue}` : ""}`
-    );
+    throw new HermesApiServerUnavailableError({
+      profileName,
+      port: configResult.apiServer.port ?? null,
+      health,
+      attemptedStart: false
+    });
   }
   void options.logger?.info("gateway_auto_start_requested", {
     profile: profileName,
@@ -5504,11 +5542,15 @@ async function ensureHermesApiServerAvailable(options = {}) {
     issue: health.issue ?? "unknown",
     ...logHint ? { log_hint: logHint } : {}
   });
-  throw new LinkHttpError(
-    503,
-    "hermes_api_server_unavailable",
-    `${unavailableMessage()} Link tried to start it with \`${formatHermesGatewayRunCommand(profileName)}\`, but it did not become ready.${health.issue ? ` ${health.issue}` : ""}${logHint ? ` \u6700\u8FD1 Gateway \u65E5\u5FD7\uFF1A${logHint}` : ""} Gateway log: ${start.logPath}`
-  );
+  throw new HermesApiServerUnavailableError({
+    profileName,
+    port: configResult.apiServer.port ?? null,
+    health,
+    attemptedStart: true,
+    startCommand: formatHermesGatewayRunCommand(profileName),
+    gatewayLog: start.logPath,
+    logHint: logHint || void 0
+  });
 }
 async function reloadHermesGateway(options = {}) {
   const profileName = normalizeProfileName(options.profileName);
@@ -5993,7 +6035,7 @@ async function waitForHermesApiHealth(config, fetcher, timeoutMs) {
   const deadline = Date.now() + timeoutMs;
   let health = await readHermesApiServerHealth(config, fetcher);
   while (!health.healthy && !health.terminal && Date.now() < deadline) {
-    await delay(400);
+    await delay2(400);
     health = await readHermesApiServerHealth(config, fetcher);
   }
   return health;
@@ -6012,31 +6054,37 @@ async function readHermesApiServerHealth(config, fetcher = fetch) {
     const payload = await detailed.json().catch(() => null);
     const record = toRecord2(payload);
     if (!isHermesApiServerHealthPayload(record, { allowStatusOnly: false })) {
+      const issue3 = createHealthIssue("not_hermes_response", {
+        probe: "GET /health/detailed"
+      });
       return {
         healthy: false,
         terminal: true,
-        issue: "\u5F53\u524D\u7AEF\u53E3\u8FD4\u56DE\u4E86\u975E Hermes API Server \u7684\u5065\u5EB7\u68C0\u67E5\u54CD\u5E94\uFF0C\u53EF\u80FD\u88AB\u5176\u4ED6\u672C\u673A\u670D\u52A1\u5360\u7528\u3002",
+        ...healthIssueFields(issue3),
         detailed: record
       };
     }
-    const issue = describeDetailedHealthIssue(record);
+    const issue2 = describeDetailedHealthIssue(record);
     const terminal = isTerminalDetailedHealth(record);
-    const authIssue = issue ? null : await probeHermesApiServerAuth(resolvedConfig, fetcher);
+    const authIssue = issue2 ? null : await probeHermesApiServerAuth(resolvedConfig, fetcher);
     if (authIssue) {
       return authIssue;
     }
     return {
-      healthy: !issue,
+      healthy: !issue2,
       terminal,
-      ...issue ? { issue } : {},
+      ...issue2 ? healthIssueFields(issue2) : {},
       detailed: record
     };
   }
   if (detailed?.status === 401) {
+    const issue2 = createHealthIssue("auth_invalid", {
+      probe: "GET /health/detailed"
+    });
     return {
       healthy: false,
       authInvalid: true,
-      issue: "Hermes API Server \u8FD4\u56DE 401\uFF0C\u5F53\u524D\u7AEF\u53E3\u53EF\u80FD\u5C5E\u4E8E\u53E6\u4E00\u4E2A Profile\uFF0C\u6216 API Server key \u5DF2\u53D8\u66F4\u3002"
+      ...healthIssueFields(issue2)
     };
   }
   const basic = await fetchWithTimeout(
@@ -6053,10 +6101,13 @@ async function readHermesApiServerHealth(config, fetcher = fetch) {
     if (!isHermesApiServerHealthPayload(record, {
       allowStatusOnly: true
     })) {
+      const issue2 = createHealthIssue("not_hermes_response", {
+        probe: "GET /health"
+      });
       return {
         healthy: false,
         terminal: true,
-        issue: "\u5F53\u524D\u7AEF\u53E3\u8FD4\u56DE\u4E86\u975E Hermes API Server \u7684\u5065\u5EB7\u68C0\u67E5\u54CD\u5E94\uFF0C\u53EF\u80FD\u88AB\u5176\u4ED6\u672C\u673A\u670D\u52A1\u5360\u7528\u3002",
+        ...healthIssueFields(issue2),
         detailed: record
       };
     }
@@ -6067,15 +6118,22 @@ async function readHermesApiServerHealth(config, fetcher = fetch) {
     return { healthy: true };
   }
   if (basic?.status === 401) {
+    const issue2 = createHealthIssue("auth_invalid", {
+      probe: "GET /health"
+    });
     return {
       healthy: false,
       authInvalid: true,
-      issue: "Hermes API Server \u8FD4\u56DE 401\uFF0C\u5F53\u524D\u7AEF\u53E3\u53EF\u80FD\u5C5E\u4E8E\u53E6\u4E00\u4E2A Profile\uFF0C\u6216 API Server key \u5DF2\u53D8\u66F4\u3002"
+      ...healthIssueFields(issue2)
     };
   }
+  const issue = createHealthIssue("port_unreachable", {
+    port: resolvedConfig.port,
+    probe: "GET /health/detailed, GET /health"
+  });
   return {
     healthy: false,
-    issue: describePortHealthFailure(resolvedConfig.port)
+    ...healthIssueFields(issue)
   };
 }
 async function probeHermesApiServerAuth(config, fetcher) {
@@ -6088,22 +6146,32 @@ async function probeHermesApiServerAuth(config, fetcher) {
     fetcher
   );
   if (!response) {
+    const issue = createHealthIssue("models_probe_timeout", {
+      probe: "GET /v1/models"
+    });
     return {
       healthy: false,
-      issue: "Hermes API Server \u9274\u6743\u63A2\u6D4B\u65E0\u54CD\u5E94\uFF1A/v1/models \u6CA1\u6709\u5728\u8D85\u65F6\u65F6\u95F4\u5185\u8FD4\u56DE\u3002"
+      ...healthIssueFields(issue)
     };
   }
   if (response?.status === 401) {
+    const issue = createHealthIssue("auth_invalid", {
+      probe: "GET /v1/models"
+    });
     return {
       healthy: false,
       authInvalid: true,
-      issue: "Hermes API Server \u8FD4\u56DE 401\uFF0C\u5F53\u524D\u7AEF\u53E3\u53EF\u80FD\u5C5E\u4E8E\u53E6\u4E00\u4E2A Profile\uFF0C\u6216 API Server key \u5DF2\u53D8\u66F4\u3002"
+      ...healthIssueFields(issue)
     };
   }
   if (response && !response.ok) {
+    const issue = createHealthIssue("models_probe_http", {
+      status: response.status,
+      probe: "GET /v1/models"
+    });
     return {
       healthy: false,
-      issue: `Hermes API Server \u9274\u6743\u63A2\u6D4B\u5931\u8D25\uFF1A/v1/models \u8FD4\u56DE HTTP ${response.status}\u3002`
+      ...healthIssueFields(issue)
     };
   }
   return null;
@@ -6129,14 +6197,92 @@ function shouldAutoStart(value) {
   const raw = process.env.HERMESLINK_GATEWAY_AUTOSTART?.trim().toLowerCase();
   return raw !== "0" && raw !== "false" && raw !== "off";
 }
-function unavailableMessage() {
-  return "Hermes API Server \u5F53\u524D\u4E0D\u53EF\u7528\u3002\u8BF7\u786E\u8BA4 Hermes Agent \u5DF2\u5B89\u88C5\uFF0C\u5E76\u53EF\u901A\u8FC7 `hermes gateway run` \u542F\u52A8\uFF1BHermesPilot Link \u9700\u8981 Hermes Agent \u7684\u672C\u673A API Server\u3002";
-}
 function isHermesApiServerHealthPayload(payload, options) {
   return payload.platform === "hermes-agent" || options.allowStatusOnly && (payload.status === "ok" || payload.ok === true);
 }
-function describePortHealthFailure(port) {
-  return port ? `Hermes API Server \u7AEF\u53E3 ${port} \u6CA1\u6709\u54CD\u5E94\uFF1B\u5982\u679C\u8FD9\u662F\u521A\u521B\u5EFA\u7684 Profile\uFF0C\u53EF\u80FD\u662F Gateway \u5C1A\u672A\u542F\u52A8\u3001\u7AEF\u53E3\u88AB\u5176\u4ED6\u8FDB\u7A0B\u5360\u7528\uFF0C\u6216 Profile \u7684 API Server port \u914D\u7F6E\u4E0D\u6B63\u786E\u3002` : "Hermes API Server \u7AEF\u53E3\u6CA1\u6709\u54CD\u5E94\u3002";
+function buildUnavailableErrorMessage(details) {
+  const reason = details.health.issue ?? "unknown reason";
+  return `Hermes API Server is unavailable: ${reason}`;
+}
+function createHealthIssue(code, values = {}) {
+  switch (code) {
+    case "not_hermes_response":
+      return {
+        code,
+        ...values.probe !== void 0 ? { probe: values.probe } : {},
+        message: "The configured port returned a non-Hermes API Server health response. Another local service may be using this port."
+      };
+    case "auth_invalid":
+      return {
+        code,
+        ...values.probe !== void 0 ? { probe: values.probe } : {},
+        message: "Hermes API Server returned 401. The configured API key may be wrong, or this port may belong to another Profile."
+      };
+    case "models_probe_timeout":
+      return {
+        code,
+        ...values.probe !== void 0 ? { probe: values.probe } : {},
+        message: "Hermes API Server did not respond to /v1/models before the timeout."
+      };
+    case "models_probe_http":
+      return {
+        code,
+        ...values.status !== void 0 ? { status: values.status } : {},
+        ...values.probe !== void 0 ? { probe: values.probe } : {},
+        message: `Hermes API Server /v1/models returned HTTP ${values.status ?? "unknown"}.`
+      };
+    case "port_unreachable":
+      return {
+        code,
+        ...values.port !== void 0 ? { port: values.port } : {},
+        ...values.probe !== void 0 ? { probe: values.probe } : {},
+        message: values.port ? `Hermes API Server port ${values.port} did not respond.` : "Hermes API Server port did not respond."
+      };
+    case "gateway_state":
+      return {
+        code,
+        ...values.state !== void 0 ? { state: values.state } : {},
+        ...values.probe !== void 0 ? { probe: values.probe } : {},
+        message: `Hermes Gateway state is ${values.state ?? "unknown"}.`
+      };
+    case "api_server_state":
+      return {
+        code,
+        ...values.state !== void 0 ? { state: values.state } : {},
+        ...values.detail !== void 0 ? { detail: values.detail } : {},
+        ...values.probe !== void 0 ? { probe: values.probe } : {},
+        message: `Hermes API Server state is ${values.state ?? "unknown"}${values.detail ? `: ${values.detail}` : ""}.`
+      };
+    case "exit_reason":
+      return {
+        code,
+        ...values.detail !== void 0 ? { detail: values.detail } : {},
+        ...values.probe !== void 0 ? { probe: values.probe } : {},
+        message: `Hermes Gateway exit reason: ${values.detail ?? "unknown"}.`
+      };
+  }
+}
+function healthIssueFields(issue) {
+  const fields = {
+    issue: issue.message,
+    issueCode: issue.code
+  };
+  if (issue.port !== void 0) {
+    fields.issuePort = issue.port;
+  }
+  if (issue.status !== void 0) {
+    fields.issueStatus = issue.status;
+  }
+  if (issue.state !== void 0) {
+    fields.issueState = issue.state;
+  }
+  if (issue.detail !== void 0) {
+    fields.issueDetail = issue.detail;
+  }
+  if (issue.probe !== void 0) {
+    fields.issueProbe = issue.probe;
+  }
+  return fields;
 }
 function describeDetailedHealthIssue(payload) {
   const gatewayState = readString4(payload, "gateway_state");
@@ -6145,22 +6291,26 @@ function describeDetailedHealthIssue(payload) {
   const apiServer = toRecord2(platforms.api_server);
   const apiServerState = readString4(apiServer, "state");
   const apiServerError = readString4(apiServer, "error_message");
-  const platformIssue = firstFatalPlatformIssue(platforms);
-  const parts = [];
   if (gatewayState && gatewayState !== "running") {
-    parts.push(`Gateway \u72B6\u6001\u662F ${gatewayState}`);
+    return createHealthIssue("gateway_state", {
+      state: gatewayState,
+      probe: "GET /health/detailed"
+    });
   }
   if (apiServerState && !isHealthyPlatformState(apiServerState)) {
-    parts.push(
-      `API Server \u72B6\u6001\u662F ${apiServerState}${apiServerError ? `\uFF1A${apiServerError}` : ""}`
-    );
+    return createHealthIssue("api_server_state", {
+      state: apiServerState,
+      ...apiServerError ? { detail: apiServerError } : {},
+      probe: "GET /health/detailed"
+    });
   }
-  if (exitReason) {
-    parts.push(`\u9000\u51FA\u539F\u56E0\uFF1A${exitReason}`);
-  } else if (platformIssue) {
-    parts.push(platformIssue);
+  if (exitReason && gatewayState !== "running") {
+    return createHealthIssue("exit_reason", {
+      detail: exitReason,
+      probe: "GET /health/detailed"
+    });
   }
-  return parts.length > 0 ? `Hermes Gateway \u672A\u5C31\u7EEA\uFF1A${dedupe(parts).join("\uFF1B")}\u3002` : null;
+  return null;
 }
 function isTerminalDetailedHealth(payload) {
   const gatewayState = readString4(payload, "gateway_state");
@@ -6168,18 +6318,6 @@ function isTerminalDetailedHealth(payload) {
   const apiServerState = readString4(toRecord2(platforms.api_server), "state");
   return gatewayState === "startup_failed" || apiServerState === "fatal" || apiServerState === "failed";
 }
-function firstFatalPlatformIssue(platforms) {
-  for (const [name, value] of Object.entries(platforms)) {
-    const platform = toRecord2(value);
-    const state = readString4(platform, "state");
-    if (state !== "fatal" && state !== "failed") {
-      continue;
-    }
-    const message = readString4(platform, "error_message");
-    return `${name} \u72B6\u6001\u662F ${state}${message ? `\uFF1A${message}` : ""}`;
-  }
-  return null;
-}
 function isHealthyPlatformState(value) {
   return ["connected", "running", "ready", "ok", "healthy"].includes(
     value.toLowerCase()
@@ -9168,12 +9306,12 @@ var ConversationMetadataCoordinator = class {
     return { ...next, last_event_seq: event.seq, updated_at: event.created_at };
   }
   scheduleGeneratedTitleRefresh(conversationId) {
-    for (const delay3 of GENERATED_TITLE_RETRY_DELAYS_MS) {
+    for (const delay4 of GENERATED_TITLE_RETRY_DELAYS_MS) {
       setTimeout(() => {
         void this.generateTitleFromFirstRound(conversationId).catch(
           () => void 0
         );
-      }, delay3);
+      }, delay4);
     }
   }
   async renameConversation(conversationId, title, input) {
@@ -19600,7 +19738,7 @@ function isExpectedClientDisconnectError2(error, options = {}) {
 import { execFile as execFile4 } from "child_process";
 import { readdir as readdir9, readFile as readFile13, rename as rename3, stat as stat13 } from "fs/promises";
 import path20 from "path";
-import { setTimeout as delay2 } from "timers/promises";
+import { setTimeout as delay3 } from "timers/promises";
 import { promisify as promisify4 } from "util";
 import YAML2 from "yaml";
 var DEFAULT_PROFILE = "default";
@@ -19861,7 +19999,7 @@ async function waitForProcessesToExit(pids, timeoutMs) {
   const deadline = Date.now() + timeoutMs;
   let remaining = pids.filter(isProcessRunning);
   while (remaining.length > 0 && Date.now() < deadline) {
-    await delay2(100);
+    await delay3(100);
     remaining = remaining.filter(isProcessRunning);
   }
   return remaining;
@@ -19880,7 +20018,7 @@ async function waitForProfilePathToRemainAbsent(profilePath) {
     if (await pathExists(profilePath)) {
       return false;
     }
-    await delay2(PROFILE_DELETE_VERIFY_INTERVAL_MS);
+    await delay3(PROFILE_DELETE_VERIFY_INTERVAL_MS);
   }
   return !await pathExists(profilePath);
 }
@@ -25352,12 +25490,12 @@ function connectRelayControl(options) {
     onUpdate: options.onStreamBatchPolicy
   };
   const startConnect = () => {
-    void waitForPersistedCooldown().then((delay3) => {
+    void waitForPersistedCooldown().then((delay4) => {
       if (closedByUser) {
         return;
       }
-      if (delay3 > 0) {
-        scheduleTimer(delay3, "cooldown", `Relay reconnect cooldown active for ${delay3}ms`);
+      if (delay4 > 0) {
+        scheduleTimer(delay4, "cooldown", `Relay reconnect cooldown active for ${delay4}ms`);
         return;
       }
       connect();
@@ -25466,8 +25604,8 @@ function connectRelayControl(options) {
     }
     if (recorded.cooldownUntilMs !== null) {
       reconnectAttempts = 0;
-      const delay4 = Math.max(0, recorded.cooldownUntilMs - Date.now());
-      scheduleTimer(delay4, "cooldown", `Relay reconnect storm guard active for ${delay4}ms`);
+      const delay5 = Math.max(0, recorded.cooldownUntilMs - Date.now());
+      scheduleTimer(delay5, "cooldown", `Relay reconnect storm guard active for ${delay5}ms`);
       return;
     }
     reconnectAttempts += 1;
@@ -25475,15 +25613,15 @@ function connectRelayControl(options) {
       baseMs: backoffBaseMs,
       maxMs: backoffMaxMs
     });
-    const delay3 = Math.max(backoffMs, relayRetryAfterMs ?? 0);
-    scheduleTimer(delay3, "retrying", `Retrying in ${delay3}ms`);
+    const delay4 = Math.max(backoffMs, relayRetryAfterMs ?? 0);
+    scheduleTimer(delay4, "retrying", `Retrying in ${delay4}ms`);
   }
   async function waitForPersistedCooldown() {
     return await readRelayCooldownDelayMs(paths).catch(() => 0);
   }
-  function scheduleTimer(delay3, state, message) {
+  function scheduleTimer(delay4, state, message) {
     options.onStatus?.({ state, attempt: reconnectAttempts, message });
-    retryTimer = setTimeout(connect, delay3);
+    retryTimer = setTimeout(connect, delay4);
     retryTimer.unref?.();
   }
   return {
@@ -27723,13 +27861,14 @@ async function buildOfficialInstallCommand(options, targetVersion) {
     HERMESLINK_YES: "1",
     HERMESLINK_NO_PROFILE_EDIT: "1",
     HERMESLINK_NO_PATH_PROMPT: "1",
+    HERMESLINK_SKIP_DOCTOR: "1",
     HERMESLINK_SKIP_RESTART: "1"
   };
   if (process.platform === "win32") {
     const windowsCommand = `& { $ErrorActionPreference = "Stop"; Invoke-RestMethod ${quotePowerShellString(installer.windowsUrl)} | Invoke-Expression }`;
     return {
       command: windowsCommand,
-      displayCommand: `$env:HERMESLINK_VERSION="${targetVersion}"; $env:HERMESLINK_YES="1"; $env:HERMESLINK_NO_PATH_PROMPT="1"; $env:HERMESLINK_SKIP_RESTART="1"; ${windowsCommand}; hermeslink restart`,
+      displayCommand: `$env:HERMESLINK_VERSION="${targetVersion}"; $env:HERMESLINK_YES="1"; $env:HERMESLINK_NO_PATH_PROMPT="1"; $env:HERMESLINK_SKIP_DOCTOR="1"; $env:HERMESLINK_SKIP_RESTART="1"; ${windowsCommand}; hermeslink restart`,
       env,
       source: "official-installer",
       installerUrl: installer.windowsUrl
@@ -27738,7 +27877,7 @@ async function buildOfficialInstallCommand(options, targetVersion) {
   const unixCommand = buildUnixInstallCommand(installer.unixUrl);
   return {
     command: unixCommand,
-    displayCommand: `HERMESLINK_VERSION=${targetVersion} HERMESLINK_YES=1 HERMESLINK_NO_PROFILE_EDIT=1 HERMESLINK_NO_PATH_PROMPT=1 HERMESLINK_SKIP_RESTART=1 sh -c ${quoteShellToken(unixCommand)} && hermeslink restart`,
+    displayCommand: `HERMESLINK_VERSION=${targetVersion} HERMESLINK_YES=1 HERMESLINK_NO_PROFILE_EDIT=1 HERMESLINK_NO_PATH_PROMPT=1 HERMESLINK_SKIP_DOCTOR=1 HERMESLINK_SKIP_RESTART=1 sh -c ${quoteShellToken(unixCommand)} && hermeslink restart`,
     env,
     source: "official-installer",
     installerUrl: installer.unixUrl
@@ -27920,8 +28059,9 @@ function buildWindowsDetachedUpdaterScript(input) {
     "  $env:HERMESLINK_VERSION = $TargetVersion",
     '  $env:HERMESLINK_YES = "1"',
     '  $env:HERMESLINK_NO_PATH_PROMPT = "1"',
+    '  $env:HERMESLINK_SKIP_DOCTOR = "1"',
     '  $env:HERMESLINK_SKIP_RESTART = "1"',
-    '  Invoke-Step "Installing Hermes Link $TargetVersion" { & powershell.exe -NoProfile -ExecutionPolicy Bypass -File $InstallerPath -Version $TargetVersion -NoPathPrompt -SkipRestart } | Out-Null',
+    '  Invoke-Step "Installing Hermes Link $TargetVersion" { & powershell.exe -NoProfile -ExecutionPolicy Bypass -File $InstallerPath -Version $TargetVersion -NoPathPrompt -SkipDoctor -SkipRestart } | Out-Null',
     '  Invoke-Step "Starting Hermes Link after update" { & $NodePath $CliScriptPath start } | Out-Null',
     '  Add-UpdateLog ""',
     '  Add-UpdateLog ("=== link update finished " + (Get-Date).ToUniversalTime().ToString("o") + " exit=0 signal=null ===")',
@@ -29745,7 +29885,6 @@ export {
   LinkHttpError,
   resolveHermesProfileDir,
   resolveHermesConfigPath,
-  readHermesApiServerConfig,
   ensureHermesApiServerConfig,
   resolveRuntimePaths,
   createFileLogger,
@@ -29755,6 +29894,7 @@ export {
   getGatewayLogFiles,
   readRecentGatewayLogEntries,
   flushLogFiles,
+  HermesApiServerUnavailableError,
   ensureHermesApiServerAvailable,
   readHermesVersion,
   defaultLinkConfig,

package/dist/cli/index.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import {
   ConversationService,
+  HermesApiServerUnavailableError,
   LINK_COMMAND,
   LINK_VERSION,
   LinkHttpError,
@@ -28,7 +29,6 @@ import {
   parseLogLevel,
   preparePairing,
   probeLocalLinkService,
-  readHermesApiServerConfig,
   readHermesVersion,
   readPairingClaim,
   readRecentGatewayLogEntries,
@@ -44,7 +44,7 @@ import {
   startDaemonProcess,
   startLinkService,
   stopDaemonProcess
-} from "../chunk-RBMFF32Z.js";
+} from "../chunk-PCJGVIKH.js";
 
 // src/cli/index.ts
 import { Command } from "commander";
@@ -452,6 +452,38 @@ var messages = {
     "doctor.apiReady": "Hermes API Server: ready",
     "doctor.apiStarted": "Hermes API Server: started and ready",
     "doctor.apiUnavailable": "Hermes API Server: unavailable. {message}",
+    "doctor.apiUnavailable.summary": "Hermes API Server: unavailable",
+    "doctor.apiUnavailable.profile": "Profile: {profile}; port: {port}",
+    "doctor.apiUnavailable.diagnosisDivider": "----- API Server diagnosis -----",
+    "doctor.apiUnavailable.check": "Check: {check}",
+    "doctor.apiUnavailable.result": "Result: {result}",
+    "doctor.apiUnavailable.startAttempt": "Link tried to start it with: {command}",
+    "doctor.apiUnavailable.startSkipped": "Auto-start was skipped; Link only checked the existing server.",
+    "doctor.apiUnavailable.recentLog": "Recent Gateway log: {message}",
+    "doctor.apiUnavailable.gatewayLog": "Gateway log: {path}",
+    "doctor.apiUnavailable.fix.port": "Suggestion: check whether another process is using port {port}, or run `hermes gateway run --replace` to view the Hermes startup error directly.",
+    "doctor.apiUnavailable.fix.auth": "Suggestion: check API_SERVER_KEY in the current Profile .env/config.yaml, or make sure this port belongs to the same Hermes Profile.",
+    "doctor.apiUnavailable.fix.notHermes": "Suggestion: change the Hermes API Server port or stop the non-Hermes service using this port.",
+    "doctor.apiUnavailable.fix.models": "Suggestion: the health endpoint responds, but the model API does not. Check Hermes provider/model configuration and Gateway logs.",
+    "doctor.apiUnavailable.fix.gateway": "Suggestion: start Hermes Gateway with `hermes gateway run --replace` and check the printed Hermes error.",
+    "doctor.apiCheck.notHermes": "Read the Hermes health response from {probe}.",
+    "doctor.apiCheck.authInvalid": "Call {probe} with the configured API key.",
+    "doctor.apiCheck.modelsTimeout": "Call {probe} to verify the API key and model API.",
+    "doctor.apiCheck.modelsHttp": "Call {probe} to verify the API key and model API.",
+    "doctor.apiCheck.port": "Connect to the Hermes health endpoints: {probe}.",
+    "doctor.apiCheck.gatewayState": "Read gateway_state from /health/detailed.",
+    "doctor.apiCheck.apiServerState": "Read platforms.api_server.state from /health/detailed.",
+    "doctor.apiCheck.exitReason": "Read exit_reason from /health/detailed.",
+    "doctor.apiCheck.unknown": "Run the Hermes API Server health checks.",
+    "doctor.apiIssue.notHermes": "The configured port returned a non-Hermes health response. Another local service may be using this port.",
+    "doctor.apiIssue.authInvalid": "The API key was rejected (HTTP 401). The key in Profile .env/config.yaml may be stale, or this port may belong to another Profile.",
+    "doctor.apiIssue.modelsTimeout": "/v1/models did not respond before the timeout.",
+    "doctor.apiIssue.modelsHttp": "/v1/models returned HTTP {status}.",
+    "doctor.apiIssue.port": "Port {port} did not respond.",
+    "doctor.apiIssue.gatewayState": "Gateway state is {state}.",
+    "doctor.apiIssue.apiServerState": "API Server state is {state}{detail}.",
+    "doctor.apiIssue.exitReason": "Gateway exit reason: {detail}.",
+    "doctor.apiIssue.unknown": "{message}",
     "error.relayPublicKeyMismatch": "Relay rejected the pairing request because the Server-issued bootstrap token does not match this Link public key. Make sure Server and Relay are deployed with the same bootstrap key configuration, then run `hermeslink pair` again.",
     "error.relayChallengeInvalid": "Relay did not return a valid install challenge.",
     "error.relayLinkInvalid": "Relay did not return a valid link_id.",
@@ -616,6 +648,38 @@ var messages = {
     "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}",
+    "doctor.apiUnavailable.summary": "Hermes API Server\uFF1A\u4E0D\u53EF\u7528",
+    "doctor.apiUnavailable.profile": "Profile\uFF1A{profile}\uFF1B\u7AEF\u53E3\uFF1A{port}",
+    "doctor.apiUnavailable.diagnosisDivider": "----- API Server \u8BCA\u65AD -----",
+    "doctor.apiUnavailable.check": "\u68C0\u6D4B\u73AF\u8282\uFF1A{check}",
+    "doctor.apiUnavailable.result": "\u68C0\u6D4B\u7ED3\u679C\uFF1A{result}",
+    "doctor.apiUnavailable.startAttempt": "Link \u5DF2\u5C1D\u8BD5\u542F\u52A8\uFF1A{command}",
+    "doctor.apiUnavailable.startSkipped": "\u5DF2\u8DF3\u8FC7\u81EA\u52A8\u542F\u52A8\uFF1BLink \u53EA\u68C0\u67E5\u4E86\u5F53\u524D\u5DF2\u6709\u7684 API Server\u3002",
+    "doctor.apiUnavailable.recentLog": "\u6700\u8FD1 Gateway \u65E5\u5FD7\uFF1A{message}",
+    "doctor.apiUnavailable.gatewayLog": "Gateway \u65E5\u5FD7\uFF1A{path}",
+    "doctor.apiUnavailable.fix.port": "\u5EFA\u8BAE\uFF1A\u786E\u8BA4\u7AEF\u53E3 {port} \u662F\u5426\u88AB\u5176\u4ED6\u8FDB\u7A0B\u5360\u7528\uFF0C\u6216\u76F4\u63A5\u8FD0\u884C `hermes gateway run --replace` \u67E5\u770B Hermes \u539F\u59CB\u542F\u52A8\u9519\u8BEF\u3002",
+    "doctor.apiUnavailable.fix.auth": "\u5EFA\u8BAE\uFF1A\u68C0\u67E5\u5F53\u524D Profile \u7684 .env/config.yaml \u4E2D API_SERVER_KEY \u662F\u5426\u4E00\u81F4\uFF0C\u6216\u786E\u8BA4\u8FD9\u4E2A\u7AEF\u53E3\u5C5E\u4E8E\u540C\u4E00\u4E2A Hermes Profile\u3002",
+    "doctor.apiUnavailable.fix.notHermes": "\u5EFA\u8BAE\uFF1A\u8C03\u6574 Hermes API Server \u7AEF\u53E3\uFF0C\u6216\u505C\u6B62\u5360\u7528\u8BE5\u7AEF\u53E3\u7684\u975E Hermes \u670D\u52A1\u3002",
+    "doctor.apiUnavailable.fix.models": "\u5EFA\u8BAE\uFF1A\u5065\u5EB7\u63A5\u53E3\u5DF2\u6709\u54CD\u5E94\uFF0C\u4F46\u6A21\u578B\u63A5\u53E3\u4E0D\u53EF\u7528\uFF1B\u8BF7\u68C0\u67E5 Hermes \u7684\u6A21\u578B/provider \u914D\u7F6E\u548C Gateway \u65E5\u5FD7\u3002",
+    "doctor.apiUnavailable.fix.gateway": "\u5EFA\u8BAE\uFF1A\u76F4\u63A5\u8FD0\u884C `hermes gateway run --replace`\uFF0C\u67E5\u770B Hermes Gateway \u8F93\u51FA\u7684\u539F\u59CB\u9519\u8BEF\u3002",
+    "doctor.apiCheck.notHermes": "\u8BFB\u53D6 Hermes \u5065\u5EB7\u68C0\u67E5\u54CD\u5E94\uFF08{probe}\uFF09\u3002",
+    "doctor.apiCheck.authInvalid": "\u4F7F\u7528\u5F53\u524D\u914D\u7F6E\u7684 API key \u8BF7\u6C42 {probe}\u3002",
+    "doctor.apiCheck.modelsTimeout": "\u8BF7\u6C42 {probe}\uFF0C\u9A8C\u8BC1 API key \u548C\u6A21\u578B\u63A5\u53E3\u662F\u5426\u53EF\u7528\u3002",
+    "doctor.apiCheck.modelsHttp": "\u8BF7\u6C42 {probe}\uFF0C\u9A8C\u8BC1 API key \u548C\u6A21\u578B\u63A5\u53E3\u662F\u5426\u53EF\u7528\u3002",
+    "doctor.apiCheck.port": "\u8FDE\u63A5 Hermes \u5065\u5EB7\u68C0\u67E5\u63A5\u53E3\uFF1A{probe}\u3002",
+    "doctor.apiCheck.gatewayState": "\u8BFB\u53D6 /health/detailed \u91CC\u7684 gateway_state\u3002",
+    "doctor.apiCheck.apiServerState": "\u8BFB\u53D6 /health/detailed \u91CC\u7684 platforms.api_server.state\u3002",
+    "doctor.apiCheck.exitReason": "\u8BFB\u53D6 /health/detailed \u91CC\u7684 exit_reason\u3002",
+    "doctor.apiCheck.unknown": "\u6267\u884C Hermes API Server \u5065\u5EB7\u68C0\u67E5\u3002",
+    "doctor.apiIssue.notHermes": "\u5F53\u524D\u914D\u7F6E\u7AEF\u53E3\u8FD4\u56DE\u7684\u4E0D\u662F Hermes API Server \u5065\u5EB7\u54CD\u5E94\uFF0C\u53EF\u80FD\u88AB\u5176\u4ED6\u672C\u673A\u670D\u52A1\u5360\u7528\u3002",
+    "doctor.apiIssue.authInvalid": "API key \u88AB\u62D2\u7EDD\uFF08HTTP 401\uFF09\u3002\u5F53\u524D Profile .env/config.yaml \u91CC\u7684 key \u53EF\u80FD\u5DF2\u8FC7\u671F\uFF0C\u6216\u8FD9\u4E2A\u7AEF\u53E3\u5C5E\u4E8E\u53E6\u4E00\u4E2A Profile\u3002",
+    "doctor.apiIssue.modelsTimeout": "/v1/models \u5728\u8D85\u65F6\u65F6\u95F4\u5185\u6CA1\u6709\u54CD\u5E94\u3002",
+    "doctor.apiIssue.modelsHttp": "/v1/models \u8FD4\u56DE HTTP {status}\u3002",
+    "doctor.apiIssue.port": "\u7AEF\u53E3 {port} \u6CA1\u6709\u54CD\u5E94\u3002",
+    "doctor.apiIssue.gatewayState": "Gateway \u72B6\u6001\u662F {state}\u3002",
+    "doctor.apiIssue.apiServerState": "API Server \u72B6\u6001\u662F {state}{detail}\u3002",
+    "doctor.apiIssue.exitReason": "Gateway \u9000\u51FA\u539F\u56E0\uFF1A{detail}\u3002",
+    "doctor.apiIssue.unknown": "{message}",
     "error.relayPublicKeyMismatch": "Relay \u62D2\u7EDD\u4E86\u914D\u5BF9\u8BF7\u6C42\uFF1AServer \u7B7E\u53D1\u7684 bootstrap token \u4E0E\u672C\u673A Link \u516C\u94A5\u4E0D\u5339\u914D\u3002\u8BF7\u786E\u8BA4 Server \u548C Relay \u4F7F\u7528\u540C\u4E00\u5957 bootstrap key \u914D\u7F6E\uFF0C\u7136\u540E\u91CD\u65B0\u8FD0\u884C `hermeslink pair`\u3002",
     "error.relayChallengeInvalid": "Relay \u6CA1\u6709\u8FD4\u56DE\u6709\u6548\u7684\u5B89\u88C5\u6311\u6218\u3002",
     "error.relayLinkInvalid": "Relay \u6CA1\u6709\u8FD4\u56DE\u6709\u6548\u7684 link_id\u3002",
@@ -717,6 +781,136 @@ function parseLanguage(value) {
   return null;
 }
 
+// src/hermes/api-server-diagnostics.ts
+function formatHermesApiServerUnavailable(error, language) {
+  if (!(error instanceof HermesApiServerUnavailableError)) {
+    return translate(language, "doctor.apiUnavailable", {
+      message: localizeErrorMessage(error, language)
+    });
+  }
+  const details = error.details;
+  const port = details.port === null ? "unknown" : String(details.port);
+  const lines = [
+    translate(language, "doctor.apiUnavailable.summary"),
+    translate(language, "doctor.apiUnavailable.profile", {
+      profile: details.profileName,
+      port
+    }),
+    translate(language, "doctor.apiUnavailable.diagnosisDivider"),
+    translate(language, "doctor.apiUnavailable.check", {
+      check: formatHealthCheck(details.health, language)
+    }),
+    translate(language, "doctor.apiUnavailable.result", {
+      result: formatHealthIssue(details.health, language)
+    })
+  ];
+  if (details.attemptedStart && details.startCommand) {
+    lines.push(
+      translate(language, "doctor.apiUnavailable.startAttempt", {
+        command: details.startCommand
+      })
+    );
+  } else if (!details.attemptedStart) {
+    lines.push(translate(language, "doctor.apiUnavailable.startSkipped"));
+  }
+  const fix = formatFix(details.health, language, port);
+  if (fix) {
+    lines.push(fix);
+  }
+  if (details.logHint) {
+    lines.push(
+      translate(language, "doctor.apiUnavailable.recentLog", {
+        message: details.logHint
+      })
+    );
+  }
+  if (details.gatewayLog) {
+    lines.push(
+      translate(language, "doctor.apiUnavailable.gatewayLog", {
+        path: details.gatewayLog
+      })
+    );
+  }
+  return lines.join("\n");
+}
+function formatHealthCheck(health, language) {
+  const probe = health.issueProbe ?? "unknown";
+  switch (health.issueCode) {
+    case "not_hermes_response":
+      return translate(language, "doctor.apiCheck.notHermes", { probe });
+    case "auth_invalid":
+      return translate(language, "doctor.apiCheck.authInvalid", { probe });
+    case "models_probe_timeout":
+      return translate(language, "doctor.apiCheck.modelsTimeout", { probe });
+    case "models_probe_http":
+      return translate(language, "doctor.apiCheck.modelsHttp", { probe });
+    case "port_unreachable":
+      return translate(language, "doctor.apiCheck.port", { probe });
+    case "gateway_state":
+      return translate(language, "doctor.apiCheck.gatewayState");
+    case "api_server_state":
+      return translate(language, "doctor.apiCheck.apiServerState");
+    case "exit_reason":
+      return translate(language, "doctor.apiCheck.exitReason");
+    default:
+      return translate(language, "doctor.apiCheck.unknown");
+  }
+}
+function formatHealthIssue(health, language) {
+  switch (health.issueCode) {
+    case "not_hermes_response":
+      return translate(language, "doctor.apiIssue.notHermes");
+    case "auth_invalid":
+      return translate(language, "doctor.apiIssue.authInvalid");
+    case "models_probe_timeout":
+      return translate(language, "doctor.apiIssue.modelsTimeout");
+    case "models_probe_http":
+      return translate(language, "doctor.apiIssue.modelsHttp", {
+        status: health.issueStatus ?? "unknown"
+      });
+    case "port_unreachable":
+      return translate(language, "doctor.apiIssue.port", {
+        port: health.issuePort ?? "unknown"
+      });
+    case "gateway_state":
+      return translate(language, "doctor.apiIssue.gatewayState", {
+        state: health.issueState ?? "unknown"
+      });
+    case "api_server_state":
+      return translate(language, "doctor.apiIssue.apiServerState", {
+        state: health.issueState ?? "unknown",
+        detail: health.issueDetail ? `${language === "zh-CN" ? "\uFF1A" : ": "}${health.issueDetail}` : ""
+      });
+    case "exit_reason":
+      return translate(language, "doctor.apiIssue.exitReason", {
+        detail: health.issueDetail ?? "unknown"
+      });
+    default:
+      return translate(language, "doctor.apiIssue.unknown", {
+        message: health.issue ?? "unknown"
+      });
+  }
+}
+function formatFix(health, language, port) {
+  switch (health.issueCode) {
+    case "port_unreachable":
+      return translate(language, "doctor.apiUnavailable.fix.port", { port });
+    case "auth_invalid":
+      return translate(language, "doctor.apiUnavailable.fix.auth");
+    case "not_hermes_response":
+      return translate(language, "doctor.apiUnavailable.fix.notHermes");
+    case "models_probe_timeout":
+    case "models_probe_http":
+      return translate(language, "doctor.apiUnavailable.fix.models");
+    case "gateway_state":
+    case "api_server_state":
+    case "exit_reason":
+      return translate(language, "doctor.apiUnavailable.fix.gateway");
+    default:
+      return null;
+  }
+}
+
 // src/pairing/preflight.ts
 import { access, stat } from "fs/promises";
 import path2 from "path";
@@ -755,7 +949,7 @@ async function assertPairingPreflightReady(options = {}) {
     });
   }
   if (failures.length > 0) {
-    throwPairingPreflightError(failures);
+    throwPairingPreflightError(failures, options.language);
   }
   options.onProgress?.("hermes_cli");
   let hermesVersion;
@@ -763,29 +957,20 @@ async function assertPairingPreflightReady(options = {}) {
     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."
-      }
-    ]);
+    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.language
+    );
   }
   options.onProgress?.("hermes_api_server");
-  const apiServerConfig = await readHermesApiServerConfig(profileName, configPath);
-  if (apiServerConfig.enabled !== true) {
-    throwPairingPreflightError([
-      {
-        code: "hermes_api_server_disabled",
-        zh: "Hermes API Server \u8FD8\u6CA1\u6709\u5F00\u542F\u3002",
-        en: "Hermes API Server is not enabled.",
-        actionZh: "\u8BF7\u8FD0\u884C `hermeslink doctor` \u8BA9 Link \u81EA\u52A8\u8865\u9F50 API Server \u914D\u7F6E\uFF0C\u6216\u5728 Hermes \u914D\u7F6E\u4E2D\u542F\u7528 platforms.api_server\u3002",
-        actionEn: "Run `hermeslink doctor` so Link can prepare the API Server config, or enable platforms.api_server in Hermes config."
-      }
-    ]);
-  }
   try {
     const ensureAvailable = options.ensureApiServerAvailable ?? ensureHermesApiServerAvailable;
     const availability = await ensureAvailable({
@@ -806,32 +991,40 @@ async function assertPairingPreflightReady(options = {}) {
         host: availability.configResult.apiServer.host ?? null,
         port: availability.configResult.apiServer.port ?? null
       },
+      notice: availability.configResult.notice,
+      backupPath: availability.configResult.backupPath,
       hermesVersion: {
         raw: hermesVersion.raw,
         version: hermesVersion.version
       }
     };
   } catch (error) {
-    throwPairingPreflightError([
-      {
-        code: "hermes_api_server_unavailable",
-        zh: "Hermes API Server \u5F53\u524D\u4E0D\u53EF\u7528\uFF0CLink \u4E0D\u80FD\u786E\u8BA4 App \u914D\u5BF9\u540E\u53EF\u4EE5\u53D1\u9001\u6D88\u606F\u3002",
-        en: "Hermes API Server is not available, so Link cannot confirm that the App will be able to send messages after pairing.",
-        actionZh: "\u8BF7\u5148\u8FD0\u884C `hermes gateway run --replace` \u6216 `hermeslink doctor`\uFF0C\u786E\u8BA4 /health \u53EF\u4EE5\u8BBF\u95EE\u540E\u518D\u91CD\u65B0\u6267\u884C `hermeslink pair`\u3002",
-        actionEn: "Run `hermes gateway run --replace` or `hermeslink doctor` first, then retry `hermeslink pair` after /health is reachable.",
-        detail: error instanceof Error ? error.message : String(error)
-      }
-    ]);
+    throwPairingPreflightError(
+      [
+        {
+          code: "hermes_api_server_unavailable",
+          zh: "Hermes API Server \u9884\u68C0\u5931\u8D25\u3002",
+          en: "Hermes API Server preflight failed.",
+          actionZh: "\u8BF7\u6839\u636E\u4E0B\u9762\u201C\u7EC6\u8282\u201D\u4E2D\u7684\u68C0\u6D4B\u73AF\u8282\u548C\u68C0\u6D4B\u7ED3\u679C\u5904\u7406\u540E\uFF0C\u518D\u91CD\u65B0\u6267\u884C `hermeslink pair`\u3002",
+          actionEn: "Use the check step and result in Detail below, then run `hermeslink pair` again.",
+          detail: options.language === void 0 ? error instanceof Error ? error.message : String(error) : formatHermesApiServerUnavailable(error, options.language)
+        }
+      ],
+      options.language
+    );
   }
 }
-function throwPairingPreflightError(failures) {
+function throwPairingPreflightError(failures, language) {
   throw new LinkHttpError(
     503,
     failures[0]?.code ?? "pairing_preflight_failed",
-    formatPairingPreflightMessage(failures)
+    formatPairingPreflightMessage(failures, language)
   );
 }
-function formatPairingPreflightMessage(failures) {
+function formatPairingPreflightMessage(failures, language) {
+  if (language) {
+    return formatLocalizedPairingPreflightMessage(failures, language);
+  }
   const lines = [
     "\u914D\u5BF9\u524D\u68C0\u67E5\u6CA1\u6709\u901A\u8FC7\uFF0C\u6682\u65F6\u4E0D\u4F1A\u5411 HermesPilot Server \u6216 Relay \u7533\u8BF7\u914D\u5BF9\u4E8C\u7EF4\u7801/\u914D\u5BF9\u7801\u3002",
     "Pairing preflight failed. Link did not request a pairing QR code or pairing code from HermesPilot Server or Relay.",
@@ -849,6 +1042,25 @@ function formatPairingPreflightMessage(failures) {
   });
   return lines.join("\n");
 }
+function formatLocalizedPairingPreflightMessage(failures, language) {
+  const lines = language === "zh-CN" ? ["\u914D\u5BF9\u524D\u68C0\u67E5\u6CA1\u6709\u901A\u8FC7\uFF0C\u6682\u65F6\u4E0D\u4F1A\u7533\u8BF7\u914D\u5BF9\u4E8C\u7EF4\u7801/\u914D\u5BF9\u7801\u3002", ""] : [
+    "Pairing preflight failed. Link did not request a pairing QR code or pairing code.",
+    ""
+  ];
+  failures.forEach((failure, index) => {
+    const prefix = failures.length > 1 ? `${index + 1}. ` : "";
+    lines.push(`${prefix}${language === "zh-CN" ? failure.zh : failure.en}`);
+    lines.push(
+      language === "zh-CN" ? `   \u5904\u7406\u5EFA\u8BAE\uFF1A${failure.actionZh}` : `   Suggested fix: ${failure.actionEn}`
+    );
+    if (failure.detail) {
+      lines.push(
+        language === "zh-CN" ? `   \u7EC6\u8282\uFF1A${failure.detail}` : `   Detail: ${failure.detail}`
+      );
+    }
+  });
+  return lines.join("\n");
+}
 async function isDirectory(filePath) {
   return stat(filePath).then((value) => value.isDirectory()).catch(() => false);
 }
@@ -1242,12 +1454,19 @@ program.command("pair").description(helpText("pair.description")).action(async (
   if (environment.warning) {
     console.log(t("doctor.networkWarning", { message: environment.warning }));
   }
-  await assertPairingPreflightReady({
+  const preflight = await assertPairingPreflightReady({
     paths,
+    language,
     onProgress: (stage) => {
       console.log(t(pairingPreflightProgressKey(stage)));
     }
   });
+  if (preflight.notice) {
+    console.log(preflight.notice);
+    if (preflight.backupPath) {
+      console.log(`Hermes config backup: ${preflight.backupPath}`);
+    }
+  }
   console.log(t("pair.preparing"));
   await ensureIdentity(paths);
   const hadActiveDevices = await hasActiveDevices(paths);
@@ -1455,7 +1674,7 @@ program.command("doctor").option("--install", helpText("doctor.installOnly")).de
     const availability = await ensureHermesApiServerAvailable({ timeoutMs: 5e3 });
     console.log(t(availability.started ? "doctor.apiStarted" : "doctor.apiReady"));
   } catch (error) {
-    console.log(t("doctor.apiUnavailable", { message: error instanceof Error ? error.message : String(error) }));
+    console.log(formatHermesApiServerUnavailable(error, language));
   }
 });
 if (isCliEntrypoint()) {

package/dist/http/app.js

@@ -1,6 +1,6 @@
 import {
   createApp
-} from "../chunk-RBMFF32Z.js";
+} from "../chunk-PCJGVIKH.js";
 export {
   createApp
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hermespilot/link",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "private": false,
   "description": "Hermes Link companion service and CLI for connecting hermes-agent through HermesPilot",
   "license": "MIT",
@@ -40,27 +40,27 @@
     "publish:npm": "npm publish --access public"
   },
   "dependencies": {
-    "@koa/router": "^15.4.0",
-    "better-sqlite3": "^12.9.0",
-    "commander": "^12.1.0",
-    "koa": "^2.15.3",
-    "qrcode": "^1.5.4",
-    "qrcode-terminal": "^0.12.0",
-    "ws": "^8.18.0",
-    "yaml": "^2.6.1",
-    "zod": "^3.24.1"
+    "@koa/router": "15.4.0",
+    "better-sqlite3": "12.9.0",
+    "commander": "12.1.0",
+    "koa": "2.15.3",
+    "qrcode": "1.5.4",
+    "qrcode-terminal": "0.12.0",
+    "ws": "8.18.0",
+    "yaml": "2.6.1",
+    "zod": "3.24.1"
   },
   "devDependencies": {
-    "@types/better-sqlite3": "^7.6.13",
-    "@types/koa": "^2.15.0",
-    "@types/node": "^20.19.39",
-    "@types/qrcode": "^1.5.6",
-    "@types/qrcode-terminal": "^0.12.2",
-    "@types/ws": "^8.5.13",
-    "tsup": "^8.3.5",
-    "tsx": "^4.19.2",
-    "typescript": "^5.7.2",
-    "vitest": "^2.1.8"
+    "@types/better-sqlite3": "7.6.13",
+    "@types/koa": "2.15.0",
+    "@types/node": "20.19.39",
+    "@types/qrcode": "1.5.6",
+    "@types/qrcode-terminal": "0.12.2",
+    "@types/ws": "8.5.13",
+    "tsup": "8.3.5",
+    "tsx": "4.19.2",
+    "typescript": "5.7.2",
+    "vitest": "2.1.8"
   },
   "engines": {
     "node": ">=20.0.0"