@hermespilot/link 0.3.7 → 0.3.9

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

@@ -1099,58 +1099,200 @@ function readProfileAvatarType(row) {
 }
 
 // src/hermes/cron-link-delivery.ts
-import { mkdir as mkdir4, readdir as readdir2, readFile as readFile3, stat } from "fs/promises";
+import { mkdir as mkdir3, readdir as readdir3, readFile as readFile3, stat as stat2 } from "fs/promises";
 import path4 from "path";
 
 // src/storage/atomic-json.ts
-import { mkdir as mkdir2, open, readFile, rename, rm } from "fs/promises";
+import { readFile } from "fs/promises";
+
+// src/storage/atomic-file.ts
 import { randomUUID as randomUUID2 } from "crypto";
+import {
+  chmod,
+  chown,
+  lstat,
+  mkdir as mkdir2,
+  open,
+  readdir,
+  rename,
+  rm,
+  stat
+} from "fs/promises";
 import path2 from "path";
-async function readJsonFile(filePath) {
+async function atomicWriteFilePreservingMetadata(filePath, value, options = {}) {
+  const resolvedPath = path2.resolve(filePath);
+  const directory = path2.dirname(resolvedPath);
+  await ensureDirectoryWithInheritedMetadata(
+    directory,
+    options.directoryMode ?? 448
+  );
+  const existingMetadata = await readExistingFileMetadata(resolvedPath) ?? (options.metadataSourcePath ? await readExistingFileMetadata(path2.resolve(options.metadataSourcePath)) : null);
+  const directoryMetadata = await readPathMetadata(directory);
+  const metadata = {
+    uid: existingMetadata?.uid ?? directoryMetadata.uid,
+    gid: existingMetadata?.gid ?? directoryMetadata.gid,
+    mode: existingMetadata?.mode ?? options.mode ?? 384
+  };
+  const tempPath = path2.join(
+    directory,
+    `.${path2.basename(resolvedPath)}.${process.pid}.${Date.now()}.${randomUUID2()}.tmp`
+  );
   try {
-    const raw = await readFile(filePath, "utf8");
-    return JSON.parse(raw);
+    const handle = await open(tempPath, "wx", metadata.mode);
+    try {
+      if (typeof value === "string") {
+        await handle.writeFile(value, options.encoding ?? "utf8");
+      } else {
+        await handle.writeFile(value);
+      }
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    await applyMetadata(tempPath, metadata);
+    await rename(tempPath, resolvedPath);
   } catch (error) {
+    await rm(tempPath, { force: true });
+    throw error;
+  }
+}
+async function ensureDirectoryWithInheritedMetadata(directory, mode) {
+  const { source, missing } = await findExistingAncestor(directory);
+  await mkdir2(directory, { recursive: true, mode });
+  for (const missingDirectory of missing) {
+    await applyMetadata(missingDirectory, {
+      uid: source.uid,
+      gid: source.gid,
+      mode
+    });
+  }
+}
+async function inheritOwnerRecursively(targetPath, sourcePath) {
+  if (process.platform === "win32") {
+    return;
+  }
+  const source = await readPathMetadata(sourcePath);
+  await applyOwnerRecursively(targetPath, source);
+}
+async function findExistingAncestor(directory) {
+  const missing = [];
+  let current = path2.resolve(directory);
+  while (true) {
+    const currentStat = await stat(current).catch((error) => {
+      if (isNodeError(error, "ENOENT")) {
+        return null;
+      }
+      throw error;
+    });
+    if (currentStat) {
+      if (!currentStat.isDirectory()) {
+        throw new Error(`${current} is not a directory`);
+      }
+      return {
+        source: metadataFromStats(currentStat),
+        missing: missing.reverse()
+      };
+    }
+    missing.push(current);
+    const parent = path2.dirname(current);
+    if (parent === current) {
+      throw new Error(`No existing parent directory for ${directory}`);
+    }
+    current = parent;
+  }
+}
+async function readExistingFileMetadata(filePath) {
+  const fileStat = await stat(filePath).catch((error) => {
     if (isNodeError(error, "ENOENT")) {
       return null;
     }
     throw error;
+  });
+  if (!fileStat) {
+    return null;
+  }
+  if (!fileStat.isFile()) {
+    throw new Error(`${filePath} is not a file`);
   }
+  return metadataFromStats(fileStat);
 }
-async function writeJsonFile(filePath, value, mode = 384) {
-  await mkdir2(path2.dirname(filePath), { recursive: true, mode: 448 });
-  const tmpPath = `${filePath}.${process.pid}.${Date.now()}.${randomUUID2()}.tmp`;
-  const payload = `${JSON.stringify(value, null, 2)}
-`;
-  const handle = await open(tmpPath, "w", mode);
+async function readPathMetadata(filePath) {
+  return metadataFromStats(await stat(filePath));
+}
+async function applyMetadata(filePath, metadata) {
+  await applyOwner(filePath, metadata);
+  await chmod(filePath, metadata.mode);
+}
+async function applyOwnerRecursively(filePath, metadata) {
+  const current = await lstat(filePath);
+  if (current.isSymbolicLink()) {
+    return;
+  }
+  await applyOwner(filePath, metadata);
+  if (!current.isDirectory()) {
+    return;
+  }
+  const entries = await readdir(filePath, { withFileTypes: true });
+  await Promise.all(
+    entries.map(
+      (entry) => applyOwnerRecursively(path2.join(filePath, entry.name), metadata)
+    )
+  );
+}
+async function applyOwner(filePath, metadata) {
+  if (process.platform === "win32") {
+    return;
+  }
+  const currentUid = typeof process.getuid === "function" ? process.getuid() : void 0;
+  const currentGid = typeof process.getgid === "function" ? process.getgid() : void 0;
+  if (metadata.uid === currentUid && metadata.gid === currentGid) {
+    return;
+  }
   try {
-    await handle.writeFile(payload, "utf8");
-    await handle.sync();
-  } finally {
-    await handle.close();
+    await chown(filePath, metadata.uid, metadata.gid);
+  } catch (error) {
+    const current = await stat(filePath);
+    if (current.uid !== metadata.uid || current.gid !== metadata.gid) {
+      throw error;
+    }
   }
+}
+function metadataFromStats(statsValue) {
+  return {
+    uid: statsValue.uid,
+    gid: statsValue.gid,
+    mode: statsValue.mode & 511
+  };
+}
+function isNodeError(error, code) {
+  return typeof error === "object" && error !== null && "code" in error && error.code === code;
+}
+
+// src/storage/atomic-json.ts
+async function readJsonFile(filePath) {
   try {
-    await rename(tmpPath, filePath);
+    const raw = await readFile(filePath, "utf8");
+    return JSON.parse(raw);
   } catch (error) {
-    await rm(tmpPath, { force: true });
+    if (isNodeError2(error, "ENOENT")) {
+      return null;
+    }
     throw error;
   }
 }
-function isNodeError(error, code) {
+async function writeJsonFile(filePath, value, mode = 384) {
+  const payload = `${JSON.stringify(value, null, 2)}
+`;
+  await atomicWriteFilePreservingMetadata(filePath, payload, { mode });
+}
+function isNodeError2(error, code) {
   return typeof error === "object" && error !== null && "code" in error && error.code === code;
 }
 
 // src/hermes/config.ts
 import { randomBytes } from "crypto";
 import net from "net";
-import {
-  copyFile,
-  mkdir as mkdir3,
-  readFile as readFile2,
-  readdir,
-  rename as rename2,
-  writeFile
-} from "fs/promises";
+import { readFile as readFile2, readdir as readdir2 } from "fs/promises";
 import os from "os";
 import path3 from "path";
 import YAML from "yaml";
@@ -1374,7 +1516,7 @@ async function readHermesSessionsDir(profileName = "default", configPath = resol
 async function readHermesApiServerConfig(profileName = "default", configPath = resolveHermesConfigPath(profileName)) {
   const existingRaw = await readFile2(configPath, "utf8").catch(
     (error) => {
-      if (isNodeError2(error, "ENOENT")) {
+      if (isNodeError3(error, "ENOENT")) {
         return null;
       }
       throw error;
@@ -1399,7 +1541,7 @@ async function readHermesApiServerConfig(profileName = "default", configPath = r
 async function readHermesModelConfig(profileName = "default", configPath = resolveHermesConfigPath(profileName)) {
   const existingRaw = await readFile2(configPath, "utf8").catch(
     (error) => {
-      if (isNodeError2(error, "ENOENT")) {
+      if (isNodeError3(error, "ENOENT")) {
         return null;
       }
       throw error;
@@ -1920,7 +2062,7 @@ async function ensureHermesApiServerConfig(profileName = "default", configPath =
 async function ensureHermesApiServerConfigUnlocked(profileName = "default", configPath = resolveHermesConfigPath(profileName)) {
   const existingRaw = await readFile2(configPath, "utf8").catch(
     (error) => {
-      if (isNodeError2(error, "ENOENT")) {
+      if (isNodeError3(error, "ENOENT")) {
         return null;
       }
       throw error;
@@ -1986,12 +2128,13 @@ async function ensureHermesApiServerConfigUnlocked(profileName = "default", conf
     };
   }
   const backupPath = existingRaw ? `${configPath}.bak.${Date.now()}` : null;
-  await mkdir3(path3.dirname(configPath), { recursive: true, mode: 448 });
-  if (backupPath) {
-    await copyFile(configPath, backupPath);
+  if (backupPath && existingRaw !== null) {
+    await atomicWriteFilePreservingMetadata(backupPath, existingRaw, {
+      metadataSourcePath: configPath
+    });
   }
   document.contents = document.createNode(config);
-  await writeFile(configPath, document.toString(), { mode: 384 });
+  await atomicWriteFilePreservingMetadata(configPath, document.toString());
   return {
     configPath,
     apiServer: applyEnvOverrides(
@@ -2017,7 +2160,7 @@ async function ensureHermesApiServerConfigUnlocked(profileName = "default", conf
 async function readHermesConfigDocument(configPath) {
   const existingRaw = await readFile2(configPath, "utf8").catch(
     (error) => {
-      if (isNodeError2(error, "ENOENT")) {
+      if (isNodeError3(error, "ENOENT")) {
         return null;
       }
       throw error;
@@ -2032,14 +2175,16 @@ async function readHermesConfigDocument(configPath) {
 }
 async function writeHermesConfigDocument(input) {
   const backupPath = input.existingRaw ? `${input.configPath}.bak.${Date.now()}` : null;
-  await mkdir3(path3.dirname(input.configPath), { recursive: true, mode: 448 });
   if (backupPath) {
-    await copyFile(input.configPath, backupPath);
+    await atomicWriteFilePreservingMetadata(backupPath, input.existingRaw, {
+      metadataSourcePath: input.configPath
+    });
   }
   input.document.contents = input.document.createNode(input.config);
-  const tempPath = `${input.configPath}.tmp.${process.pid}.${Date.now()}`;
-  await writeFile(tempPath, input.document.toString(), { mode: 384 });
-  await rename2(tempPath, input.configPath);
+  await atomicWriteFilePreservingMetadata(
+    input.configPath,
+    input.document.toString()
+  );
   return backupPath;
 }
 function readManagedModelConfigs(config, env, defaultModel, defaultReasoningEffort) {
@@ -3361,9 +3506,9 @@ async function readConfiguredApiServerPorts(excludedProfileName) {
     resolveDefaultHermesRoot(resolveHermesProfileDir("default")),
     "profiles"
   );
-  const entries = await readdir(profilesRoot, { withFileTypes: true }).catch(
+  const entries = await readdir2(profilesRoot, { withFileTypes: true }).catch(
     (error) => {
-      if (isNodeError2(error, "ENOENT")) {
+      if (isNodeError3(error, "ENOENT")) {
         return [];
       }
       throw error;
@@ -3385,7 +3530,7 @@ async function addConfiguredApiServerPort(ports, profileName, excludedProfileNam
     resolveHermesConfigPath(profileName),
     "utf8"
   ).catch((error) => {
-    if (isNodeError2(error, "ENOENT")) {
+    if (isNodeError3(error, "ENOENT")) {
       return "";
     }
     throw error;
@@ -3458,7 +3603,7 @@ async function readHermesApiServerEnvOverrides(profileName) {
 async function readHermesEnvFile(profileName) {
   const envPath = path3.join(resolveHermesProfileDir(profileName), ".env");
   const raw = await readFile2(envPath, "utf8").catch((error) => {
-    if (isNodeError2(error, "ENOENT")) {
+    if (isNodeError3(error, "ENOENT")) {
       return "";
     }
     throw error;
@@ -3483,7 +3628,7 @@ async function writeHermesEnvValue(profileName, key, value) {
   const envPath = path3.join(resolveHermesProfileDir(profileName), ".env");
   const existingRaw = await readFile2(envPath, "utf8").catch(
     (error) => {
-      if (isNodeError2(error, "ENOENT")) {
+      if (isNodeError3(error, "ENOENT")) {
         return "";
       }
       throw error;
@@ -3506,13 +3651,14 @@ async function writeHermesEnvValue(profileName, key, value) {
     nextLines.push(`${key}=${formatEnvValue(value)}`);
   }
   const nextRaw = nextLines.join("\n").replace(/\n*$/u, "\n");
-  await mkdir3(path3.dirname(envPath), { recursive: true, mode: 448 });
   if (existingRaw) {
-    await copyFile(envPath, `${envPath}.bak.${Date.now()}`);
+    await atomicWriteFilePreservingMetadata(
+      `${envPath}.bak.${Date.now()}`,
+      existingRaw,
+      { metadataSourcePath: envPath }
+    );
   }
-  const tempPath = `${envPath}.tmp.${process.pid}.${Date.now()}`;
-  await writeFile(tempPath, nextRaw, { mode: 384 });
-  await rename2(tempPath, envPath);
+  await atomicWriteFilePreservingMetadata(envPath, nextRaw);
 }
 function applyEnvOverrides(config, env, withDefaults) {
   const host = config.host ?? env.host;
@@ -3591,7 +3737,7 @@ function ensureRecord(parent, key) {
 function resolveHermesConfiguredPath(value, baseDir) {
   return path3.isAbsolute(value) ? path3.normalize(value) : path3.resolve(baseDir, value);
 }
-function isNodeError2(error, code) {
+function isNodeError3(error, code) {
   return typeof error === "object" && error !== null && "code" in error && error.code === code;
 }
 function resolveDefaultHermesRoot(hermesHome) {
@@ -3716,9 +3862,9 @@ async function listCronOutputFiles(profileName, jobId) {
     "output",
     jobId
   );
-  const entries = await readdir2(outputDir, { withFileTypes: true }).catch(
+  const entries = await readdir3(outputDir, { withFileTypes: true }).catch(
     (error) => {
-      if (isNodeError3(error, "ENOENT")) {
+      if (isNodeError4(error, "ENOENT")) {
         return [];
       }
       throw error;
@@ -3730,7 +3876,7 @@ async function listCronOutputFiles(profileName, jobId) {
       continue;
     }
     const outputPath = path4.join(outputDir, entry.name);
-    const fileStat = await stat(outputPath);
+    const fileStat = await stat2(outputPath);
     files.push({
       path: outputPath,
       mtime: fileStat.mtime.toISOString(),
@@ -3763,7 +3909,7 @@ async function readRegistry(paths) {
   return { version: REGISTRY_VERSION, bindings: [] };
 }
 async function writeRegistry(paths, registry) {
-  await mkdir4(paths.indexesDir, { recursive: true, mode: 448 });
+  await mkdir3(paths.indexesDir, { recursive: true, mode: 448 });
   await writeJsonFile(registryPath(paths), registry);
 }
 function registryPath(paths) {
@@ -3789,13 +3935,13 @@ function readString3(record, ...keys) {
   }
   return void 0;
 }
-function isNodeError3(error, code) {
+function isNodeError4(error, code) {
   return error instanceof Error && error.code === code;
 }
 
 // src/hermes/gateway.ts
 import { execFile as execFile2, spawn } from "child_process";
-import { access, readFile as readFile5, stat as stat3 } from "fs/promises";
+import { access, readFile as readFile5, stat as stat4 } from "fs/promises";
 import path7 from "path";
 import { setTimeout as delay } from "timers/promises";
 import { promisify as promisify2 } from "util";
@@ -3815,7 +3961,7 @@ function isLinkHttpError(error) {
 }
 
 // src/runtime/logger.ts
-import { appendFile, mkdir as mkdir5, open as open2, readFile as readFile4, rename as rename3, rm as rm2, stat as stat2 } from "fs/promises";
+import { appendFile, mkdir as mkdir4, open as open2, readFile as readFile4, rename as rename2, rm as rm2, stat as stat3 } from "fs/promises";
 import os3 from "os";
 import path6 from "path";
 
@@ -3824,7 +3970,7 @@ import os2 from "os";
 import path5 from "path";
 
 // src/constants.ts
-var LINK_VERSION = "0.3.7";
+var LINK_VERSION = "0.3.9";
 var LINK_COMMAND = "hermeslink";
 var LINK_DEFAULT_PORT = 52379;
 var LINK_RUNTIME_DIR_NAME = ".hermeslink";
@@ -3900,7 +4046,7 @@ var FileLogger = class {
     return this.queue;
   }
   async appendEntry(entry) {
-    await mkdir5(this.paths.logsDir, { recursive: true, mode: 448 });
+    await mkdir4(this.paths.logsDir, { recursive: true, mode: 448 });
     const line = `${JSON.stringify(entry)}
 `;
     await this.rotateIfNeeded(Buffer.byteLength(line, "utf8"));
@@ -3936,7 +4082,7 @@ function createRotatingTextLogWriter(options) {
         return queue;
       }
       const next = queue.then(async () => {
-        await mkdir5(paths.logsDir, { recursive: true, mode: 448 });
+        await mkdir4(paths.logsDir, { recursive: true, mode: 448 });
         await rotateLogFileIfNeeded(filePath, buffer.length, maxFileBytes, maxFiles);
         await appendFile(filePath, buffer, { mode: 384 });
       }).catch(() => void 0);
@@ -4037,7 +4183,7 @@ function clampLimit(value) {
   return Math.min(MAX_READ_LIMIT, Math.max(1, Math.floor(value)));
 }
 async function rotateLogFileIfNeeded(filePath, nextBytes, maxFileBytes, maxFiles) {
-  const current = await stat2(filePath).catch(() => null);
+  const current = await stat3(filePath).catch(() => null);
   if (!current || current.size === 0 || current.size + nextBytes <= maxFileBytes) {
     return;
   }
@@ -4152,7 +4298,7 @@ async function readTail(filePath, maxBytes) {
   return tail?.content ?? null;
 }
 async function readTailWithMetadata(filePath, maxBytes) {
-  const info = await stat2(filePath).catch(() => null);
+  const info = await stat3(filePath).catch(() => null);
   if (!info || info.size <= 0) {
     return null;
   }
@@ -4176,7 +4322,7 @@ async function readTailWithMetadata(filePath, maxBytes) {
 }
 async function moveIfExists(from, to) {
   await rm2(to, { force: true }).catch(() => void 0);
-  await rename3(from, to).catch((error) => {
+  await rename2(from, to).catch((error) => {
     if (error.code !== "ENOENT") {
       throw error;
     }
@@ -4309,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);
@@ -4425,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) {
@@ -4471,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)
     });
@@ -4583,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 } : {}
   };
 }
@@ -4599,8 +4776,8 @@ async function assertProfileExists(profileName) {
   if (profileName === "default") {
     return;
   }
-  const exists = await stat3(resolveHermesProfileDir(profileName)).then((value) => value.isDirectory()).catch((error) => {
-    if (isNodeError4(error, "ENOENT")) {
+  const exists = await stat4(resolveHermesProfileDir(profileName)).then((value) => value.isDirectory()).catch((error) => {
+    if (isNodeError5(error, "ENOENT")) {
       return false;
     }
     throw error;
@@ -4800,7 +4977,7 @@ function isHealthyPlatformState(value) {
 function toRecord2(value) {
   return typeof value === "object" && value !== null ? value : {};
 }
-function isNodeError4(error, code) {
+function isNodeError5(error, code) {
   return typeof error === "object" && error !== null && "code" in error && error.code === code;
 }
 function readString4(payload, key) {
@@ -4826,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));
@@ -5168,7 +5411,7 @@ function firstRecord(...values) {
 
 // src/conversations/blob-store.ts
 import { randomUUID as randomUUID3 } from "crypto";
-import { mkdir as mkdir6, readFile as readFile6, readdir as readdir3, rm as rm3, stat as stat4, writeFile as writeFile2 } from "fs/promises";
+import { mkdir as mkdir5, readFile as readFile6, readdir as readdir4, rm as rm3, stat as stat5, writeFile } from "fs/promises";
 import path9 from "path";
 
 // src/conversations/media.ts
@@ -5623,8 +5866,8 @@ async function writeConversationBlob(paths, conversationId, input, options) {
   }
   const id = `blob_${randomUUID3().replaceAll("-", "")}`;
   const filePath = blobPath(paths, id);
-  await mkdir6(path9.dirname(filePath), { recursive: true, mode: 448 });
-  await writeFile2(filePath, input.bytes, { mode: 384 });
+  await mkdir5(path9.dirname(filePath), { recursive: true, mode: 448 });
+  await writeFile(filePath, input.bytes, { mode: 384 });
   const blob = {
     id,
     size: input.bytes.byteLength,
@@ -5651,7 +5894,7 @@ async function readConversationBlob(paths, conversationId, blobId) {
   const filePath = blobPath(paths, blobId);
   const manifest = await readConversationBlobManifest(paths, conversationId, blobId);
   const bytes = await readFile6(filePath).catch((error) => {
-    if (isNodeError5(error, "ENOENT")) {
+    if (isNodeError6(error, "ENOENT")) {
       throw new LinkHttpError(404, "blob_not_found", "Blob was not found");
     }
     throw error;
@@ -5693,7 +5936,7 @@ async function deleteConversationBlobIfUnreferenced(paths, conversationId, blobI
 async function materializeConversationBlob(paths, conversationId, blobId, manifest) {
   const existingPath = manifest.materialized_path;
   if (existingPath) {
-    const exists = await stat4(existingPath).then((value) => value.isFile()).catch(() => false);
+    const exists = await stat5(existingPath).then((value) => value.isFile()).catch(() => false);
     if (exists) {
       return existingPath;
     }
@@ -5703,8 +5946,8 @@ async function materializeConversationBlob(paths, conversationId, blobId, manife
     targetDir,
     materializedAttachmentFilename(blobId, manifest.filename ?? blobId)
   );
-  await mkdir6(targetDir, { recursive: true, mode: 448 });
-  await writeFile2(targetPath, await readFile6(blobPath(paths, blobId)), {
+  await mkdir5(targetDir, { recursive: true, mode: 448 });
+  await writeFile(targetPath, await readFile6(blobPath(paths, blobId)), {
     mode: 384
   });
   await writeJsonFile(`${blobPath(paths, blobId)}.json`, {
@@ -5733,11 +5976,11 @@ async function pruneConversationBlobReference(paths, conversationId, blobId) {
 }
 async function listConversationBlobIds(paths, conversationId) {
   assertValidConversationId(conversationId);
-  await mkdir6(paths.blobsDir, { recursive: true, mode: 448 });
-  const entries = await readdir3(paths.blobsDir, {
+  await mkdir5(paths.blobsDir, { recursive: true, mode: 448 });
+  const entries = await readdir4(paths.blobsDir, {
     withFileTypes: true
   }).catch((error) => {
-    if (isNodeError5(error, "ENOENT")) {
+    if (isNodeError6(error, "ENOENT")) {
       return [];
     }
     throw error;
@@ -5771,12 +6014,12 @@ function conversationAttachmentsDir(paths, conversationId) {
   assertValidConversationId(conversationId);
   return path9.join(paths.conversationsDir, conversationId, "attachments");
 }
-function isNodeError5(error, code) {
+function isNodeError6(error, code) {
   return typeof error === "object" && error !== null && "code" in error && error.code === code;
 }
 
 // src/conversations/profile-runtime.ts
-import { stat as stat5 } from "fs/promises";
+import { stat as stat6 } from "fs/promises";
 var PROFILE_NAME_PATTERN2 = /^[a-zA-Z0-9._-]{1,64}$/u;
 function normalizeProfileName2(profileName) {
   const value = profileName?.trim() || "default";
@@ -5917,8 +6160,8 @@ async function buildConversationRuntimeMetadata(paths, manifest, snapshot) {
 async function ensureProfileIdentityForRuntime(paths, profileName) {
   const profilePath = resolveHermesProfileDir(profileName);
   if (profileName !== "default") {
-    const exists = await stat5(profilePath).then((value) => value.isDirectory()).catch((error) => {
-      if (isNodeError6(error, "ENOENT")) {
+    const exists = await stat6(profilePath).then((value) => value.isDirectory()).catch((error) => {
+      if (isNodeError7(error, "ENOENT")) {
         return false;
       }
       throw error;
@@ -5944,7 +6187,7 @@ function displayNameForProfile(profile) {
   const custom = profile.displayName?.trim();
   return custom || fallbackProfileDisplayName(profile.profileName);
 }
-function isNodeError6(error, code) {
+function isNodeError7(error, code) {
   return typeof error === "object" && error !== null && "code" in error && error.code === code;
 }
 
@@ -6489,11 +6732,11 @@ function formatContextUsageLines(runtime) {
 }
 
 // src/conversations/delivery-staging.ts
-import { mkdir as mkdir7, rm as rm4 } from "fs/promises";
+import { mkdir as mkdir6, rm as rm4 } from "fs/promises";
 import path10 from "path";
 async function prepareDeliveryStagingRunDir(paths, conversationId, runId) {
   const directory = deliveryStagingRunDir(paths, conversationId, runId);
-  await mkdir7(directory, { recursive: true, mode: 448 });
+  await mkdir6(directory, { recursive: true, mode: 448 });
   return directory;
 }
 async function removeConversationDeliveryStaging(paths, conversationId) {
@@ -6852,7 +7095,7 @@ function isUsableLanIpv4(value) {
 }
 
 // src/hermes/session-title.ts
-import { stat as stat6 } from "fs/promises";
+import { stat as stat7 } from "fs/promises";
 import path11 from "path";
 async function readHermesSessionTitle(sessionId, paths, profileName) {
   const trimmedSessionId = sessionId.trim();
@@ -6864,8 +7107,8 @@ async function readHermesSessionTitle(sessionId, paths, profileName) {
     resolveHermesProfileDir(resolvedProfileName),
     "state.db"
   );
-  const exists = await stat6(dbPath).then((value) => value.isFile()).catch((error) => {
-    if (isNodeError7(error, "ENOENT")) {
+  const exists = await stat7(dbPath).then((value) => value.isFile()).catch((error) => {
+    if (isNodeError8(error, "ENOENT")) {
       return false;
     }
     throw error;
@@ -6885,8 +7128,8 @@ async function readHermesCompressionTip(sessionId, paths, profileName) {
     resolveHermesProfileDir(resolvedProfileName),
     "state.db"
   );
-  const exists = await stat6(dbPath).then((value) => value.isFile()).catch((error) => {
-    if (isNodeError7(error, "ENOENT")) {
+  const exists = await stat7(dbPath).then((value) => value.isFile()).catch((error) => {
+    if (isNodeError8(error, "ENOENT")) {
       return false;
     }
     throw error;
@@ -6949,7 +7192,7 @@ function readCompressionTipFromStateDb(dbPath, sessionId) {
     db?.close();
   }
 }
-function isNodeError7(error, code) {
+function isNodeError8(error, code) {
   return typeof error === "object" && error !== null && "code" in error && error.code === code;
 }
 function isValidProfileName(value) {
@@ -8648,11 +8891,11 @@ function hydrateAgentEventBlocks(blocks, agentEvents) {
 // src/conversations/conversation-store.ts
 import {
   appendFile as appendFile2,
-  mkdir as mkdir8,
-  readdir as readdir4,
+  mkdir as mkdir7,
+  readdir as readdir5,
   readFile as readFile7,
   rm as rm5,
-  writeFile as writeFile3
+  writeFile as writeFile2
 } from "fs/promises";
 import path12 from "path";
 var ConversationStore = class {
@@ -8661,14 +8904,14 @@ var ConversationStore = class {
   }
   paths;
   async ensureConversationsDir() {
-    await mkdir8(this.paths.conversationsDir, { recursive: true, mode: 448 });
+    await mkdir7(this.paths.conversationsDir, { recursive: true, mode: 448 });
   }
   async listConversationIds() {
     await this.ensureConversationsDir();
-    const entries = await readdir4(this.paths.conversationsDir, {
+    const entries = await readdir5(this.paths.conversationsDir, {
       withFileTypes: true
     }).catch((error) => {
-      if (isNodeError8(error, "ENOENT")) {
+      if (isNodeError9(error, "ENOENT")) {
         return [];
       }
       throw error;
@@ -8676,7 +8919,7 @@ var ConversationStore = class {
     return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
   }
   async createConversation(manifest, snapshot = createEmptySnapshot2()) {
-    await mkdir8(this.conversationDir(manifest.id), {
+    await mkdir7(this.conversationDir(manifest.id), {
       recursive: true,
       mode: 448
     });
@@ -8716,7 +8959,7 @@ var ConversationStore = class {
       conversation_id: conversationId,
       created_at: now
     };
-    await mkdir8(this.conversationDir(conversationId), {
+    await mkdir7(this.conversationDir(conversationId), {
       recursive: true,
       mode: 448
     });
@@ -8737,7 +8980,7 @@ var ConversationStore = class {
     await this.readManifest(conversationId);
     const raw = await readFile7(this.eventsPath(conversationId), "utf8").catch(
       (error) => {
-        if (isNodeError8(error, "ENOENT")) {
+        if (isNodeError9(error, "ENOENT")) {
           return "";
         }
         throw error;
@@ -8747,7 +8990,7 @@ var ConversationStore = class {
   }
   overwriteEvents(conversationId, events) {
     const content = events.map((event) => JSON.stringify(event)).join("\n");
-    return writeFile3(
+    return writeFile2(
       this.eventsPath(conversationId),
       content ? `${content}
 ` : "",
@@ -8792,18 +9035,18 @@ var ConversationStore = class {
 function createEmptySnapshot2() {
   return { schema_version: 1, messages: [], runs: [] };
 }
-function isNodeError8(error, code) {
+function isNodeError9(error, code) {
   return typeof error === "object" && error !== null && "code" in error && error.code === code;
 }
 
 // src/conversations/hermes-session-sync.ts
 import { randomUUID as randomUUID6 } from "crypto";
-import { readdir as readdir6, readFile as readFile9, stat as stat8 } from "fs/promises";
+import { readdir as readdir7, readFile as readFile9, stat as stat9 } from "fs/promises";
 import os4 from "os";
 import path14 from "path";
 
 // src/conversations/delivery-import.ts
-import { lstat, readFile as readFile8, readdir as readdir5, stat as stat7 } from "fs/promises";
+import { lstat as lstat2, readFile as readFile8, readdir as readdir6, stat as stat8 } from "fs/promises";
 import path13 from "path";
 var MAX_IMPORTED_BLOB_BYTES = 100 * 1024 * 1024;
 var MAX_MEDIA_IMPORT_FAILURES = 20;
@@ -8899,8 +9142,8 @@ function resolveDeliveryStagingTarget(paths, stagingDir) {
   };
 }
 async function collectStagedDeliveryReferences(stagingDir) {
-  const directoryStat = await lstat(stagingDir).catch((error) => {
-    if (isNodeError9(error, "ENOENT")) {
+  const directoryStat = await lstat2(stagingDir).catch((error) => {
+    if (isNodeError10(error, "ENOENT")) {
       throw new LinkHttpError(
         404,
         "delivery_staging_not_found",
@@ -8916,7 +9159,7 @@ async function collectStagedDeliveryReferences(stagingDir) {
       "delivery staging path is not a directory"
     );
   }
-  const entries = await readdir5(stagingDir, { withFileTypes: true });
+  const entries = await readdir6(stagingDir, { withFileTypes: true });
   return entries.filter((entry) => entry.isFile() && !entry.name.startsWith(".")).filter((entry) => isSupportedDeliveryFilename(entry.name)).sort(
     (left, right) => left.name.localeCompare(right.name, "en", { numeric: true })
   ).slice(0, MAX_DELIVERY_FILES).map((entry) => {
@@ -9080,8 +9323,8 @@ function emptyImportResult(input) {
 }
 async function writeBlobFromFile(deps, conversationId, source) {
   const sourcePath = resolveMediaSourcePath(source.path);
-  const fileStat = await stat7(sourcePath).catch((error) => {
-    if (isNodeError9(error, "ENOENT")) {
+  const fileStat = await stat8(sourcePath).catch((error) => {
+    if (isNodeError10(error, "ENOENT")) {
       throw new LinkHttpError(
         404,
         "media_source_not_found",
@@ -9115,7 +9358,7 @@ function describeMediaImportFailure(reference, sourceKey, error) {
     key: sourceKey,
     filename: sanitizeFilename(reference.path, "attachment"),
     reason: error instanceof Error ? error.message : String(error),
-    ...isNodeError9(error) && error.code ? { code: error.code } : {}
+    ...isNodeError10(error) && error.code ? { code: error.code } : {}
   };
 }
 function isSupportedDeliveryFilename(filename) {
@@ -9128,7 +9371,7 @@ function readString8(payload, key) {
 function toRecord7(value) {
   return typeof value === "object" && value !== null ? value : {};
 }
-function isNodeError9(error, code) {
+function isNodeError10(error, code) {
   return typeof error === "object" && error !== null && "code" in error && (code === void 0 || error.code === code);
 }
 
@@ -9895,9 +10138,9 @@ function rememberKnownHermesConversation(map, sessionId, conversationId) {
 async function discoverHermesProfileNames() {
   const names = /* @__PURE__ */ new Set([DEFAULT_PROFILE_NAME]);
   const profilesDir = path14.join(os4.homedir(), ".hermes", "profiles");
-  const entries = await readdir6(profilesDir, { withFileTypes: true }).catch(
+  const entries = await readdir7(profilesDir, { withFileTypes: true }).catch(
     (error) => {
-      if (isNodeError10(error, "ENOENT")) {
+      if (isNodeError11(error, "ENOENT")) {
         return [];
       }
       throw error;
@@ -10098,7 +10341,7 @@ async function readJsonlMessages(profileName, sessionId) {
   const sessionsDir = await readHermesSessionsDir(profileName).then((value) => value.sessionsDir).catch(() => path14.join(profileDir, "sessions"));
   const transcriptPath = path14.join(sessionsDir, `${sessionId}.jsonl`);
   const raw = await readFile9(transcriptPath, "utf8").catch((error) => {
-    if (isNodeError10(error, "ENOENT")) {
+    if (isNodeError11(error, "ENOENT")) {
       return "";
     }
     throw error;
@@ -10373,8 +10616,8 @@ function quoteIdentifier(value) {
   return `"${value.replaceAll('"', '""')}"`;
 }
 async function isFile(filePath) {
-  return stat8(filePath).then((value) => value.isFile()).catch((error) => {
-    if (isNodeError10(error, "ENOENT")) {
+  return stat9(filePath).then((value) => value.isFile()).catch((error) => {
+    if (isNodeError11(error, "ENOENT")) {
       return false;
     }
     throw error;
@@ -10407,12 +10650,12 @@ function readBoolean(value) {
   }
   return false;
 }
-function isNodeError10(error, code) {
+function isNodeError11(error, code) {
   return typeof error === "object" && error !== null && "code" in error && error.code === code;
 }
 
 // src/conversations/run-lifecycle.ts
-import { readdir as readdir7 } from "fs/promises";
+import { readdir as readdir8 } from "fs/promises";
 
 // src/hermes/api-server.ts
 async function listHermesModels(options = {}) {
@@ -10525,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(
@@ -10552,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) {
@@ -10595,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(
@@ -10806,7 +11049,7 @@ function readString10(payload, key) {
 }
 
 // src/conversations/history-builder.ts
-import { readFile as readFile10, stat as stat9 } from "fs/promises";
+import { readFile as readFile10, stat as stat10 } from "fs/promises";
 import path15 from "path";
 var HISTORY_ROLES = /* @__PURE__ */ new Set(["user", "assistant"]);
 var HERMES_HISTORY_COLUMNS = [
@@ -10914,8 +11157,8 @@ async function readHermesTranscriptHistory(sessionId, profileName) {
   };
 }
 async function readHermesStateDbHistory(dbPath, sessionId) {
-  const exists = await stat9(dbPath).then((value) => value.isFile()).catch((error) => {
-    if (isNodeError11(error, "ENOENT")) {
+  const exists = await stat10(dbPath).then((value) => value.isFile()).catch((error) => {
+    if (isNodeError12(error, "ENOENT")) {
       return false;
     }
     throw error;
@@ -10934,7 +11177,7 @@ async function readHermesJsonlHistory(sessionsDir, sessionId) {
   }
   const transcriptPath = path15.join(sessionsDir, `${sessionId}.jsonl`);
   const raw = await readFile10(transcriptPath, "utf8").catch((error) => {
-    if (isNodeError11(error, "ENOENT")) {
+    if (isNodeError12(error, "ENOENT")) {
       return "";
     }
     throw error;
@@ -11156,7 +11399,7 @@ function readTableColumns2(db, table) {
     db.prepare(`PRAGMA table_info(${table})`).all().map((row) => row.name).filter((name) => typeof name === "string")
   );
 }
-function isNodeError11(error, code) {
+function isNodeError12(error, code) {
   return typeof error === "object" && error !== null && "code" in error && error.code === code;
 }
 function isValidProfileName2(value) {
@@ -11174,7 +11417,7 @@ function normalizeProfileForCompare(value) {
 
 // src/hermes/stt.ts
 import { execFile as execFile3 } from "child_process";
-import { access as access2, readFile as readFile11, stat as stat10 } from "fs/promises";
+import { access as access2, readFile as readFile11, stat as stat11 } from "fs/promises";
 import path16 from "path";
 import { promisify as promisify3 } from "util";
 var execFileAsync3 = promisify3(execFile3);
@@ -11334,7 +11577,7 @@ async function resolveExecutablePath(command) {
 }
 async function isExecutableFile(filePath) {
   try {
-    const info = await stat10(filePath);
+    const info = await stat11(filePath);
     if (!info.isFile()) {
       return false;
     }
@@ -11375,7 +11618,7 @@ async function findDevHermesAgentSource() {
   return null;
 }
 async function isDirectory(candidate) {
-  return stat10(candidate).then((info) => info.isDirectory()).catch(() => false);
+  return stat11(candidate).then((info) => info.isDirectory()).catch(() => false);
 }
 function compactProcessOutput(value) {
   const compact = value.trim().replace(/\s+/gu, " ").slice(0, 500);
@@ -12619,8 +12862,8 @@ function formatFilenameList(filenames) {
   return remaining > 0 ? `${preview.join("\u3001")} \u7B49 ${filenames.length} \u4E2A` : preview.join("\u3001");
 }
 async function readdirWithDirs(directory) {
-  return readdir7(directory, { withFileTypes: true }).catch((error) => {
-    if (isNodeError12(error, "ENOENT")) {
+  return readdir8(directory, { withFileTypes: true }).catch((error) => {
+    if (isNodeError13(error, "ENOENT")) {
       return [];
     }
     throw error;
@@ -12850,7 +13093,7 @@ function readResponseId(payload) {
   const response = toRecord11(payload.response);
   return readString13(payload, "response_id") ?? readString13(response, "id");
 }
-function isNodeError12(error, code) {
+function isNodeError13(error, code) {
   if (typeof error !== "object" || error === null || !("code" in error)) {
     return false;
   }
@@ -13686,7 +13929,7 @@ function findApproval(snapshot, approvalId) {
 
 // src/identity/identity.ts
 import { generateKeyPairSync, randomUUID as randomUUID8, sign } from "crypto";
-import { mkdir as mkdir9, chmod } from "fs/promises";
+import { mkdir as mkdir8, chmod as chmod2 } from "fs/promises";
 import { z } from "zod";
 var linkIdentitySchema = z.object({
   install_id: z.string().min(1),
@@ -13708,8 +13951,8 @@ async function ensureIdentity(paths = resolveRuntimePaths()) {
   if (existing) {
     return existing;
   }
-  await mkdir9(paths.homeDir, { recursive: true, mode: 448 });
-  await chmod(paths.homeDir, 448).catch(() => void 0);
+  await mkdir8(paths.homeDir, { recursive: true, mode: 448 });
+  await chmod2(paths.homeDir, 448).catch(() => void 0);
   const { publicKey, privateKey } = generateKeyPairSync("ed25519");
   const now = (/* @__PURE__ */ new Date()).toISOString();
   const identity = {
@@ -14903,7 +15146,7 @@ function createHttpErrorMiddleware(logger) {
 }
 
 // src/hermes/profiles.ts
-import { mkdir as mkdir10, readdir as readdir8, readFile as readFile12, rename as rename4, rm as rm6, stat as stat11 } from "fs/promises";
+import { readdir as readdir9, readFile as readFile12, rename as rename3, rm as rm6, stat as stat12 } from "fs/promises";
 import os5 from "os";
 import path17 from "path";
 import YAML2 from "yaml";
@@ -14913,9 +15156,9 @@ async function listHermesProfiles(paths = resolveRuntimePaths()) {
   const profiles = /* @__PURE__ */ new Map();
   profiles.set(DEFAULT_PROFILE, await profileInfo(DEFAULT_PROFILE, paths));
   const profilesDir = path17.join(os5.homedir(), ".hermes", "profiles");
-  const entries = await readdir8(profilesDir, { withFileTypes: true }).catch(
+  const entries = await readdir9(profilesDir, { withFileTypes: true }).catch(
     (error) => {
-      if (isNodeError13(error, "ENOENT")) {
+      if (isNodeError14(error, "ENOENT")) {
         return [];
       }
       throw error;
@@ -14939,8 +15182,8 @@ async function listHermesProfiles(paths = resolveRuntimePaths()) {
 async function getHermesProfileStatus(name, paths = resolveRuntimePaths()) {
   assertProfileName(name);
   const profile = await profileInfo(name, paths);
-  const exists = await stat11(profile.path).then((value) => value.isDirectory()).catch((error) => {
-    if (isNodeError13(error, "ENOENT")) {
+  const exists = await stat12(profile.path).then((value) => value.isDirectory()).catch((error) => {
+    if (isNodeError14(error, "ENOENT")) {
       return false;
     }
     throw error;
@@ -14957,7 +15200,7 @@ async function renameHermesProfile(oldName, newName, paths = resolveRuntimePaths
   assertMutableProfile(newName);
   const oldProfile = await profileInfo(oldName, paths);
   const newProfilePath = resolveHermesProfileDir(newName);
-  await rename4(oldProfile.path, newProfilePath);
+  await rename3(oldProfile.path, newProfilePath);
   const identity = await renameProfileIdentity(paths, {
     oldProfileName: oldName,
     newProfileName: newName,
@@ -14980,8 +15223,8 @@ async function updateHermesProfileMetadata(name, metadata, paths = resolveRuntim
 async function deleteHermesProfile(name, paths = resolveRuntimePaths()) {
   assertMutableProfile(name);
   const profile = await profileInfo(name, paths);
-  const exists = await stat11(profile.path).then((value) => value.isDirectory()).catch((error) => {
-    if (isNodeError13(error, "ENOENT")) {
+  const exists = await stat12(profile.path).then((value) => value.isDirectory()).catch((error) => {
+    if (isNodeError14(error, "ENOENT")) {
       return false;
     }
     throw error;
@@ -15049,13 +15292,13 @@ function assertProfileName(name) {
     throw new LinkHttpError(400, "invalid_profile_name", "invalid profile name");
   }
 }
-function isNodeError13(error, code) {
+function isNodeError14(error, code) {
   return typeof error === "object" && error !== null && "code" in error && error.code === code;
 }
 async function countSkills(root) {
-  const entries = await readdir8(root, { withFileTypes: true }).catch(
+  const entries = await readdir9(root, { withFileTypes: true }).catch(
     (error) => {
-      if (isNodeError13(error, "ENOENT")) {
+      if (isNodeError14(error, "ENOENT")) {
         return [];
       }
       throw error;
@@ -15082,7 +15325,7 @@ async function countConfiguredTools(profileName) {
     resolveHermesConfigPath(profileName),
     "utf8"
   ).catch((error) => {
-    if (isNodeError13(error, "ENOENT")) {
+    if (isNodeError14(error, "ENOENT")) {
       return "";
     }
     throw error;
@@ -15759,14 +16002,11 @@ function errorMessage(error) {
 import { spawn as spawn2 } from "child_process";
 import { EventEmitter as EventEmitter2 } from "events";
 import {
-  copyFile as copyFile2,
   cp,
-  mkdir as mkdir11,
+  mkdir as mkdir9,
   readFile as readFile13,
   rm as rm7,
-  stat as stat12,
-  writeFile as writeFile4,
-  rename as rename5
+  stat as stat13
 } from "fs/promises";
 import path18 from "path";
 import YAML3 from "yaml";
@@ -15816,7 +16056,7 @@ async function startHermesProfileCreation(input, options) {
     signal: null,
     error: null
   };
-  await mkdir11(options.paths.runDir, { recursive: true, mode: 448 });
+  await mkdir9(options.paths.runDir, { recursive: true, mode: 448 });
   await writeProfileCreationState(options.paths, started);
   await writer.write(`
 === profile creation started ${startedAt} ===
@@ -16093,7 +16333,7 @@ function randomSuffix(attempt) {
 async function applyProfileCreationPostSteps(input) {
   const profilePath = resolveHermesProfileDir(input.profileName);
   if (!await pathExists(profilePath)) {
-    await mkdir11(profilePath, { recursive: true, mode: 448 });
+    await ensureDirectoryWithInheritedMetadata(profilePath, 448);
   }
   if (input.sourceProfile && input.copyScopes.length > 0) {
     await copyProfileScopes({
@@ -16221,7 +16461,7 @@ function collectEnvKeys(value, keys = /* @__PURE__ */ new Set()) {
 async function writeEnvValues(profileName, values) {
   const envPath = path18.join(resolveHermesProfileDir(profileName), ".env");
   const existingRaw = await readFile13(envPath, "utf8").catch((error) => {
-    if (isNodeError14(error, "ENOENT")) {
+    if (isNodeError15(error, "ENOENT")) {
       return "";
     }
     throw error;
@@ -16246,13 +16486,14 @@ async function writeEnvValues(profileName, values) {
     nextLines.push(`${key}=${formatEnvValue2(value)}`);
   }
   const nextRaw = nextLines.join("\n").replace(/\n*$/u, "\n");
-  await mkdir11(path18.dirname(envPath), { recursive: true, mode: 448 });
   if (existingRaw) {
-    await copyFile2(envPath, `${envPath}.bak.${Date.now()}`);
+    await atomicWriteFilePreservingMetadata(
+      `${envPath}.bak.${Date.now()}`,
+      existingRaw,
+      { metadataSourcePath: envPath }
+    );
   }
-  const tempPath = `${envPath}.tmp.${process.pid}.${Date.now()}`;
-  await writeFile4(tempPath, nextRaw, { mode: 384 });
-  await rename5(tempPath, envPath);
+  await atomicWriteFilePreservingMetadata(envPath, nextRaw);
 }
 async function copySkills(sourceProfile, targetProfile) {
   const sourceSkills = path18.join(resolveHermesProfileDir(sourceProfile), "skills");
@@ -16266,6 +16507,10 @@ async function copySkills(sourceProfile, targetProfile) {
     force: true,
     errorOnExist: false
   });
+  await inheritOwnerRecursively(
+    targetSkills,
+    resolveHermesProfileDir(targetProfile)
+  );
 }
 function copyProperty(source, target, key) {
   if (Object.prototype.hasOwnProperty.call(source, key)) {
@@ -16277,7 +16522,7 @@ function copyProperty(source, target, key) {
 async function readYamlConfig(configPath) {
   const existingRaw = await readFile13(configPath, "utf8").catch(
     (error) => {
-      if (isNodeError14(error, "ENOENT")) {
+      if (isNodeError15(error, "ENOENT")) {
         return null;
       }
       throw error;
@@ -16289,14 +16534,15 @@ async function readYamlConfig(configPath) {
   };
 }
 async function writeYamlConfig(configPath, input) {
-  await mkdir11(path18.dirname(configPath), { recursive: true, mode: 448 });
   if (input.existingRaw) {
-    await copyFile2(configPath, `${configPath}.bak.${Date.now()}`);
+    await atomicWriteFilePreservingMetadata(
+      `${configPath}.bak.${Date.now()}`,
+      input.existingRaw,
+      { metadataSourcePath: configPath }
+    );
   }
   const document = new YAML3.Document(input.config);
-  const tempPath = `${configPath}.tmp.${process.pid}.${Date.now()}`;
-  await writeFile4(tempPath, document.toString(), { mode: 384 });
-  await rename5(tempPath, configPath);
+  await atomicWriteFilePreservingMetadata(configPath, document.toString());
 }
 async function failProfileCreation(input) {
   if (input.rollbackProfileName) {
@@ -16362,8 +16608,8 @@ async function clearProfileCreationLogFiles(paths) {
   ]);
 }
 async function pathExists(targetPath) {
-  return await stat12(targetPath).then(() => true).catch((error) => {
-    if (isNodeError14(error, "ENOENT")) {
+  return await stat13(targetPath).then(() => true).catch((error) => {
+    if (isNodeError15(error, "ENOENT")) {
       return false;
     }
     throw error;
@@ -16410,7 +16656,7 @@ function formatEnvValue2(value) {
 function escapeRegExp2(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
 }
-function isNodeError14(error, code) {
+function isNodeError15(error, code) {
   return typeof error === "object" && error !== null && "code" in error && error.code === code;
 }
 
@@ -16619,13 +16865,9 @@ function toProfileToolConfigHttpError(error) {
 // src/hermes/memory.ts
 import {
   access as access3,
-  copyFile as copyFile3,
-  mkdir as mkdir12,
-  readdir as readdir9,
+  readdir as readdir10,
   readFile as readFile14,
-  rename as rename6,
-  stat as stat13,
-  writeFile as writeFile5
+  stat as stat14
 } from "fs/promises";
 import path19 from "path";
 import YAML4 from "yaml";
@@ -16938,12 +17180,11 @@ function isSensitiveConfigKey(key) {
 }
 async function writeCustomProviderConfig(profileName, provider, config) {
   const configPath = customProviderConfigPath(profileName, provider);
-  await mkdir12(path19.dirname(configPath), { recursive: true, mode: 448 });
-  await writeFile5(configPath, `${JSON.stringify(config, null, 2)}
-`, {
-    encoding: "utf8",
-    mode: 384
-  });
+  await atomicWriteFilePreservingMetadata(
+    configPath,
+    `${JSON.stringify(config, null, 2)}
+`
+  );
 }
 function normalizeConfigurableProvider(provider, patch) {
   if (provider === CUSTOM_PROVIDER_CARD_ID) {
@@ -16991,7 +17232,7 @@ async function patchHermesMemoryProvider(profileName, provider) {
   const configPath = resolveHermesConfigPath(profileName);
   const existingRaw = await readFile14(configPath, "utf8").catch(
     (error) => {
-      if (isNodeError15(error, "ENOENT")) {
+      if (isNodeError16(error, "ENOENT")) {
         return null;
       }
       throw error;
@@ -17003,17 +17244,13 @@ async function patchHermesMemoryProvider(profileName, provider) {
   memory.provider = provider === "built-in" ? "" : provider;
   config.memory = memory;
   const backupPath = existingRaw ? `${configPath}.bak.${Date.now()}` : null;
-  await mkdir12(path19.dirname(configPath), { recursive: true, mode: 448 });
-  if (backupPath) {
-    await copyFile3(configPath, backupPath);
+  if (backupPath && existingRaw !== null) {
+    await atomicWriteFilePreservingMetadata(backupPath, existingRaw, {
+      metadataSourcePath: configPath
+    });
   }
   document.contents = document.createNode(config);
-  const tempPath = `${configPath}.tmp.${process.pid}.${Date.now()}`;
-  await writeFile5(tempPath, document.toString(), {
-    encoding: "utf8",
-    mode: 384
-  });
-  await rename6(tempPath, configPath);
+  await atomicWriteFilePreservingMetadata(configPath, document.toString());
 }
 function resolveMemoryDir(profileName) {
   return path19.join(resolveHermesProfileDir(profileName), "memories");
@@ -17021,8 +17258,8 @@ function resolveMemoryDir(profileName) {
 async function readMemoryStore(profileName, target, limits) {
   const filePath = memoryFilePath(profileName, target);
   const entries = await readMemoryEntries(filePath);
-  const fileStat = await stat13(filePath).catch((error) => {
-    if (isNodeError15(error, "ENOENT")) {
+  const fileStat = await stat14(filePath).catch((error) => {
+    if (isNodeError16(error, "ENOENT")) {
       return null;
     }
     throw error;
@@ -17051,7 +17288,7 @@ async function readMemoryStore(profileName, target, limits) {
 }
 async function readMemoryEntries(filePath) {
   const raw = await readFile14(filePath, "utf8").catch((error) => {
-    if (isNodeError15(error, "ENOENT")) {
+    if (isNodeError16(error, "ENOENT")) {
       return "";
     }
     throw error;
@@ -17071,17 +17308,10 @@ async function mutateMemoryEntries(profileName, target, mutate) {
 async function writeMemoryEntries(profileName, target, entries) {
   assertWithinLimit(target, entries, await readMemoryLimits(profileName));
   const filePath = memoryFilePath(profileName, target);
-  const dir = path19.dirname(filePath);
-  await mkdir12(dir, { recursive: true, mode: 448 });
-  const tempPath = path19.join(
-    dir,
-    `.mem_${process.pid}_${Date.now()}_${target}.tmp`
+  await atomicWriteFilePreservingMetadata(
+    filePath,
+    entries.join(ENTRY_DELIMITER)
   );
-  await writeFile5(tempPath, entries.join(ENTRY_DELIMITER), {
-    encoding: "utf8",
-    mode: 384
-  });
-  await rename6(tempPath, filePath);
 }
 function memoryFilePath(profileName, target) {
   return path19.join(
@@ -17562,7 +17792,7 @@ function customProviderRegistryPath(profileName) {
 async function readCustomProviderRegistry(profileName) {
   const raw = await readFile14(customProviderRegistryPath(profileName), "utf8").catch(
     (error) => {
-      if (isNodeError15(error, "ENOENT")) {
+      if (isNodeError16(error, "ENOENT")) {
         return "";
       }
       throw error;
@@ -17599,19 +17829,17 @@ async function saveCustomProviderRegistryEntry(profileName, provider) {
     { id: providerId, label: providerId, description: "\u81EA\u5B9A\u4E49 memory provider\u3002" }
   ].sort((left, right) => left.id.localeCompare(right.id));
   const registryPath2 = customProviderRegistryPath(profileName);
-  await mkdir12(path19.dirname(registryPath2), { recursive: true, mode: 448 });
-  await writeFile5(
+  await atomicWriteFilePreservingMetadata(
     registryPath2,
     `${JSON.stringify({ providers }, null, 2)}
-`,
-    { encoding: "utf8", mode: 384 }
+`
   );
 }
 async function discoverUserMemoryProviderDescriptors(profileName) {
   const pluginsDir = path19.join(resolveHermesProfileDir(profileName), "plugins");
-  const entries = await readdir9(pluginsDir, { withFileTypes: true }).catch(
+  const entries = await readdir10(pluginsDir, { withFileTypes: true }).catch(
     (error) => {
-      if (isNodeError15(error, "ENOENT")) {
+      if (isNodeError16(error, "ENOENT")) {
         return [];
       }
       throw error;
@@ -17652,7 +17880,7 @@ async function isUserMemoryProviderInstalled(profileName, provider) {
 async function isMemoryProviderPluginDir(providerDir) {
   const source = await readFile14(path19.join(providerDir, "__init__.py"), "utf8").catch(
     (error) => {
-      if (isNodeError15(error, "ENOENT")) {
+      if (isNodeError16(error, "ENOENT")) {
         return "";
       }
       throw error;
@@ -17664,7 +17892,7 @@ async function isMemoryProviderPluginDir(providerDir) {
 async function readPluginMetadata(providerDir) {
   const raw = await readFile14(path19.join(providerDir, "plugin.yaml"), "utf8").catch(
     (error) => {
-      if (isNodeError15(error, "ENOENT")) {
+      if (isNodeError16(error, "ENOENT")) {
         return "";
       }
       throw error;
@@ -17690,7 +17918,7 @@ async function resolveByteRoverCli() {
 async function readHolographicProviderConfig(profileName) {
   const raw = await readFile14(resolveHermesConfigPath(profileName), "utf8").catch(
     (error) => {
-      if (isNodeError15(error, "ENOENT")) {
+      if (isNodeError16(error, "ENOENT")) {
         return "";
       }
       throw error;
@@ -17704,7 +17932,7 @@ async function patchHolographicProviderConfig(profileName, patch) {
   const configPath = resolveHermesConfigPath(profileName);
   const existingRaw = await readFile14(configPath, "utf8").catch(
     (error) => {
-      if (isNodeError15(error, "ENOENT")) {
+      if (isNodeError16(error, "ENOENT")) {
         return null;
       }
       throw error;
@@ -17721,17 +17949,15 @@ async function patchHolographicProviderConfig(profileName, patch) {
   }
   plugins["hermes-memory-store"] = memoryStore;
   config.plugins = plugins;
-  await mkdir12(path19.dirname(configPath), { recursive: true, mode: 448 });
   if (existingRaw) {
-    await copyFile3(configPath, `${configPath}.bak.${Date.now()}`);
+    await atomicWriteFilePreservingMetadata(
+      `${configPath}.bak.${Date.now()}`,
+      existingRaw,
+      { metadataSourcePath: configPath }
+    );
   }
   document.contents = document.createNode(config);
-  const tempPath = `${configPath}.tmp.${process.pid}.${Date.now()}`;
-  await writeFile5(tempPath, document.toString(), {
-    encoding: "utf8",
-    mode: 384
-  });
-  await rename6(tempPath, configPath);
+  await atomicWriteFilePreservingMetadata(configPath, document.toString());
 }
 async function patchHermesMemoryEnv(profileName, patch) {
   const entries = Object.entries(patch).filter(
@@ -17742,7 +17968,7 @@ async function patchHermesMemoryEnv(profileName, patch) {
   }
   const envPath = path19.join(resolveHermesProfileDir(profileName), ".env");
   const existingRaw = await readFile14(envPath, "utf8").catch((error) => {
-    if (isNodeError15(error, "ENOENT")) {
+    if (isNodeError16(error, "ENOENT")) {
       return "";
     }
     throw error;
@@ -17772,13 +17998,14 @@ async function patchHermesMemoryEnv(profileName, patch) {
     }
   }
   const nextRaw = nextLines.join("\n").replace(/\n*$/u, "\n");
-  await mkdir12(path19.dirname(envPath), { recursive: true, mode: 448 });
   if (existingRaw) {
-    await copyFile3(envPath, `${envPath}.bak.${Date.now()}`);
+    await atomicWriteFilePreservingMetadata(
+      `${envPath}.bak.${Date.now()}`,
+      existingRaw,
+      { metadataSourcePath: envPath }
+    );
   }
-  const tempPath = `${envPath}.tmp.${process.pid}.${Date.now()}`;
-  await writeFile5(tempPath, nextRaw, { encoding: "utf8", mode: 384 });
-  await rename6(tempPath, envPath);
+  await atomicWriteFilePreservingMetadata(envPath, nextRaw);
 }
 function isMemoryEnvKeyWritable(key) {
   return [
@@ -17799,7 +18026,7 @@ async function readActiveMemoryProvider(profileName) {
     resolveHermesConfigPath(profileName),
     "utf8"
   ).catch((error) => {
-    if (isNodeError15(error, "ENOENT")) {
+    if (isNodeError16(error, "ENOENT")) {
       return "";
     }
     throw error;
@@ -17824,16 +18051,15 @@ async function patchJsonProviderConfig(profileName, relativePath, patch) {
       next[key] = value;
     }
   }
-  await mkdir12(path19.dirname(configPath), { recursive: true, mode: 448 });
-  await writeFile5(configPath, `${JSON.stringify(next, null, 2)}
-`, {
-    encoding: "utf8",
-    mode: 384
-  });
+  await atomicWriteFilePreservingMetadata(
+    configPath,
+    `${JSON.stringify(next, null, 2)}
+`
+  );
 }
 async function readJsonObject(filePath) {
   const raw = await readFile14(filePath, "utf8").catch((error) => {
-    if (isNodeError15(error, "ENOENT")) {
+    if (isNodeError16(error, "ENOENT")) {
       return "{}";
     }
     throw error;
@@ -17887,7 +18113,7 @@ async function readMemoryLimits(profileName) {
     resolveHermesConfigPath(profileName),
     "utf8"
   ).catch((error) => {
-    if (isNodeError15(error, "ENOENT")) {
+    if (isNodeError16(error, "ENOENT")) {
       return "";
     }
     throw error;
@@ -17980,7 +18206,7 @@ function formatEnvValue3(value) {
 function escapeRegExp3(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
 }
-function isNodeError15(error, code) {
+function isNodeError16(error, code) {
   return error instanceof Error && "code" in error && error.code === code;
 }
 
@@ -18388,14 +18614,7 @@ function toMemoryHttpError(error) {
 }
 
 // src/hermes/skills.ts
-import {
-  copyFile as copyFile4,
-  mkdir as mkdir13,
-  readFile as readFile15,
-  readdir as readdir10,
-  rename as rename7,
-  writeFile as writeFile6
-} from "fs/promises";
+import { readFile as readFile15, readdir as readdir11 } from "fs/promises";
 import path20 from "path";
 import YAML5 from "yaml";
 var HermesSkillNotFoundError = class extends Error {
@@ -18487,9 +18706,9 @@ async function findSkillFiles(root) {
   return results.sort((left, right) => left.localeCompare(right));
 }
 async function collectSkillFiles(directory, results) {
-  const entries = await readdir10(directory, { withFileTypes: true }).catch(
+  const entries = await readdir11(directory, { withFileTypes: true }).catch(
     (error) => {
-      if (isNodeError16(error, "ENOENT")) {
+      if (isNodeError17(error, "ENOENT")) {
         return [];
       }
       throw error;
@@ -18514,7 +18733,7 @@ async function collectSkillFiles(directory, results) {
 async function readSkillMetadata(input) {
   const raw = await readFile15(input.skillFile, "utf8").catch(
     (error) => {
-      if (isNodeError16(error, "ENOENT") || isNodeError16(error, "EACCES")) {
+      if (isNodeError17(error, "ENOENT") || isNodeError17(error, "EACCES")) {
         return null;
       }
       throw error;
@@ -18591,7 +18810,7 @@ function normalizeDescription(value) {
 }
 async function readDisabledSkillNames(configPath) {
   const raw = await readFile15(configPath, "utf8").catch((error) => {
-    if (isNodeError16(error, "ENOENT")) {
+    if (isNodeError17(error, "ENOENT")) {
       return "";
     }
     throw error;
@@ -18616,7 +18835,7 @@ async function readSkillProvenance(root) {
 async function readBundledSkillNames(root) {
   const raw = await readFile15(path20.join(root, ".bundled_manifest"), "utf8").catch(
     (error) => {
-      if (isNodeError16(error, "ENOENT")) {
+      if (isNodeError17(error, "ENOENT")) {
         return "";
       }
       throw error;
@@ -18639,7 +18858,7 @@ async function readBundledSkillNames(root) {
 async function readHubInstalledSkills(root) {
   const raw = await readFile15(path20.join(root, ".hub", "lock.json"), "utf8").catch(
     (error) => {
-      if (isNodeError16(error, "ENOENT")) {
+      if (isNodeError17(error, "ENOENT")) {
         return "";
       }
       throw error;
@@ -18711,7 +18930,7 @@ function compareCategoryNames(left, right) {
 async function readHermesConfigDocument2(configPath) {
   const existingRaw = await readFile15(configPath, "utf8").catch(
     (error) => {
-      if (isNodeError16(error, "ENOENT")) {
+      if (isNodeError17(error, "ENOENT")) {
         return null;
       }
       throw error;
@@ -18726,14 +18945,16 @@ async function readHermesConfigDocument2(configPath) {
 }
 async function writeHermesConfigDocument2(input) {
   const backupPath = input.existingRaw ? `${input.configPath}.bak.${Date.now()}` : null;
-  await mkdir13(path20.dirname(input.configPath), { recursive: true, mode: 448 });
   if (backupPath) {
-    await copyFile4(input.configPath, backupPath);
+    await atomicWriteFilePreservingMetadata(backupPath, input.existingRaw, {
+      metadataSourcePath: input.configPath
+    });
   }
   input.document.contents = input.document.createNode(input.config);
-  const tempPath = `${input.configPath}.tmp.${process.pid}.${Date.now()}`;
-  await writeFile6(tempPath, input.document.toString(), { mode: 384 });
-  await rename7(tempPath, input.configPath);
+  await atomicWriteFilePreservingMetadata(
+    input.configPath,
+    input.document.toString()
+  );
   return backupPath;
 }
 function readStringList3(value) {
@@ -18756,7 +18977,7 @@ function ensureRecord3(target, key) {
   target[key] = current;
   return current;
 }
-function isNodeError16(error, code) {
+function isNodeError17(error, code) {
   return typeof error === "object" && error !== null && "code" in error && error.code === code;
 }
 
@@ -19238,7 +19459,7 @@ function readModelList(payload) {
 // src/hermes/updates.ts
 import { EventEmitter as EventEmitter3 } from "events";
 import { spawn as spawn3 } from "child_process";
-import { mkdir as mkdir14, readFile as readFile16, rm as rm8 } from "fs/promises";
+import { mkdir as mkdir10, readFile as readFile16, rm as rm8 } from "fs/promises";
 import path21 from "path";
 var SERVER_HERMES_RELEASES_LATEST_PATH = "/api/v1/hermes-agent/releases/latest";
 var RELEASE_CACHE_TTL_MS = 6 * 60 * 60 * 1e3;
@@ -19252,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
     })),
@@ -19299,7 +19523,7 @@ async function startHermesUpdate(options) {
     signal: null,
     error: null
   };
-  await mkdir14(options.paths.runDir, { recursive: true, mode: 448 });
+  await mkdir10(options.paths.runDir, { recursive: true, mode: 448 });
   await writer.write(`
 === hermes update started ${startedAt} ===
 `);
@@ -19603,17 +19827,17 @@ function readString17(payload, key) {
 // src/link/updates.ts
 import { spawn as spawn5 } from "child_process";
 import { EventEmitter as EventEmitter4 } from "events";
-import { mkdir as mkdir17, readFile as readFile18, rm as rm11 } from "fs/promises";
+import { mkdir as mkdir13, readFile as readFile18, rm as rm11 } from "fs/promises";
 import path23 from "path";
 
 // src/daemon/process.ts
 import { spawn as spawn4 } from "child_process";
-import { mkdir as mkdir16, readFile as readFile17, rm as rm10 } from "fs/promises";
+import { mkdir as mkdir12, readFile as readFile17, rm as rm10 } from "fs/promises";
 import path22 from "path";
 
 // src/daemon/service.ts
 import { createServer } from "http";
-import { mkdir as mkdir15, rm as rm9, writeFile as writeFile7 } from "fs/promises";
+import { mkdir as mkdir11, rm as rm9, writeFile as writeFile3 } from "fs/promises";
 
 // src/relay/control-client.ts
 import WebSocket from "ws";
@@ -20606,8 +20830,8 @@ function pidFilePath(paths = resolveRuntimePaths()) {
   return `${paths.runDir}/hermeslink.pid`;
 }
 async function writePidFile(paths) {
-  await mkdir15(paths.runDir, { recursive: true, mode: 448 });
-  await writeFile7(pidFilePath(paths), `${process.pid}
+  await mkdir11(paths.runDir, { recursive: true, mode: 448 });
+  await writeFile3(pidFilePath(paths), `${process.pid}
 `, { mode: 384 });
 }
 async function closeServer(server) {
@@ -20681,8 +20905,8 @@ async function startDaemonProcess(paths = resolveRuntimePaths()) {
       return status;
     }
   }
-  await mkdir16(paths.logsDir, { recursive: true, mode: 448 });
-  await mkdir16(paths.runDir, { recursive: true, mode: 448 });
+  await mkdir12(paths.logsDir, { recursive: true, mode: 448 });
+  await mkdir12(paths.runDir, { recursive: true, mode: 448 });
   const scriptPath = currentCliScriptPath();
   const child = spawn4(process.execPath, [scriptPath, "daemon-supervisor"], {
     detached: true,
@@ -20700,7 +20924,7 @@ async function startDaemonProcess(paths = resolveRuntimePaths()) {
   return await getDaemonStatus(paths);
 }
 async function runDaemonSupervisor(paths = resolveRuntimePaths()) {
-  await mkdir16(paths.logsDir, { recursive: true, mode: 448 });
+  await mkdir12(paths.logsDir, { recursive: true, mode: 448 });
   const log = createRotatingTextLogWriter({
     paths,
     fileName: path22.basename(daemonLogFile(paths))
@@ -20944,7 +21168,7 @@ async function startLinkUpdate(options) {
     error: null,
     manual_command: manualCommand
   };
-  await mkdir17(options.paths.runDir, { recursive: true, mode: 448 });
+  await mkdir13(options.paths.runDir, { recursive: true, mode: 448 });
   await writer.write(
     `
 === link update started ${startedAt} target=${targetVersion} ===
@@ -21313,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, "");
@@ -21353,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}`;
@@ -21388,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;
@@ -21417,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",
@@ -21538,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) {
@@ -21585,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) {
@@ -21626,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) {
@@ -21657,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`);
 }
@@ -22792,6 +23092,7 @@ export {
   createFileLogger,
   getLinkLogFile,
   ensureHermesApiServerAvailable,
+  readHermesVersion,
   loadConfig,
   saveConfig,
   normalizeLanHost,