@xyagent/cli 0.0.1

package/src-ext/runtime/hermes/gatewayManager.mjs

@@ -0,0 +1,625 @@
+// hermes-agent gateway 进程管理 —— 给 `agentlink pair -r hermes` 用：
+// 配置改完之后直接 kill + spawn 让 gateway 自动起来，**用户不用再手敲
+// nohup**。
+//
+// 设计要点：
+//   - 不接管常驻管理 —— 用户已经用 launchctl/systemd-user 托管的话，我们
+//     探测到 :8642 通就什么也不做；不通才介入。
+//   - spawnDetached + unref → 子进程脱离 pair 进程的生命周期，pair 退出后
+//     gateway 继续跑。
+//   - 不靠 pkill —— 用 lsof 找端口占用者拿 pid 精准 kill，避免误杀其它叫
+//     "hermes gateway"的进程。
+
+import { execSync, spawn, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import net from "node:net";
+import os from "node:os";
+import path from "node:path";
+
+// gateway 启动后 listen 端口需要时间 —— 热路径 1.5~3s，但冷启动（首次加载
+// skills/记忆/模型路由）实测可 >8s；给到 30s 上限，避免误判超时后回退到默认 profile（错身份）。
+const HEALTH_POLL_INTERVAL_MS = 300;
+const HEALTH_POLL_TIMEOUT_MS = 30000;
+// kill 之后等端口完全释放，避免 spawn 时撞 EADDRINUSE。
+const PORT_RELEASE_TIMEOUT_MS = 5000;
+const PORT_RELEASE_INTERVAL_MS = 200;
+
+// per-profile 端口范围（default profile 固定 8642，不在此范围内）
+const PROFILE_PORT_MIN = 8643;
+const PROFILE_PORT_MAX = 8742;
+
+// 进程级 profile gateway 注册表
+// Map<slug, { port: number, pid: number, baseUrl: string, lastActiveAt: Date }>
+export const profileGatewayRegistry = new Map();
+
+// 最大并发 profile gateway 数（含 default profile）
+export const MAX_PROFILE_GATEWAYS = Number(
+  process.env.HERMES_MAX_PROFILE_GATEWAYS || "5",
+);
+
+// idle 回收阈值（分钟）
+const IDLE_TIMEOUT_MINUTES = Number(
+  process.env.HERMES_GATEWAY_IDLE_TIMEOUT_MINUTES || "30",
+);
+
+// idle 回收 timer（每 5 分钟扫一次）
+let _idleCleanupTimer = null;
+
+/**
+ * 手动触发 idle 回收（也供测试调用）。
+ */
+export async function runIdleCleanup({ log } = {}) {
+  const now = Date.now();
+  const thresholdMs = IDLE_TIMEOUT_MINUTES * 60 * 1000;
+  for (const [slug, info] of profileGatewayRegistry.entries()) {
+    const idleMs = now - info.lastActiveAt.getTime();
+    if (idleMs >= thresholdMs) {
+      log?.info?.("hermes.profile.idle_evict", "evicting idle profile gateway", {
+        slug, idle_minutes: Math.floor(idleMs / 60000), port: info.port,
+      });
+      await stopGatewayOnPort(info.port, { log }).catch(() => {});
+      profileGatewayRegistry.delete(slug);
+    }
+  }
+}
+
+/**
+ * 启动进程级 idle 回收后台 timer（只启动一次）。
+ */
+export function startIdleCleanupTimer({ log } = {}) {
+  if (_idleCleanupTimer) return;
+  _idleCleanupTimer = setInterval(() => {
+    runIdleCleanup({ log }).catch(() => {});
+  }, 5 * 60 * 1000);
+  // 不阻止进程退出
+  if (_idleCleanupTimer.unref) _idleCleanupTimer.unref();
+}
+
+/**
+ * 检查端口是否空闲（返回 Promise<boolean>）。
+ * 通过 net.createServer().listen() 探测，比 lsof 更准确（跨平台）。
+ */
+function isPortFree(port) {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    server.once("error", () => resolve(false));
+    server.once("listening", () => {
+      server.close(() => resolve(true));
+    });
+    server.listen(port, "127.0.0.1");
+  });
+}
+
+/**
+ * 为 per-profile hermesHome 分配/复用端口。
+ *
+ * 规则：
+ *   1. hermesHome == ~/.hermes → 固定返回 8642（向后兼容）
+ *   2. 读 <hermesHome>/gateway-port.json，若端口空闲 → 复用
+ *   3. 否则在 [8643, 8742] 探测空闲端口，写入文件
+ *   4. 全满 → 抛出错误
+ *
+ * @param {string} hermesHome
+ * @returns {Promise<number>}
+ */
+
+/**
+ * 读 `<hermesHome>/.env` 里某个 key 的值（去包裹引号/首尾空白）。
+ * 文件不存在 / 读失败 / 未命中 → 返回 ""。
+ * @param {string} hermesHome
+ * @param {string} key
+ * @returns {string}
+ */
+export function readProfileEnvValue(hermesHome, key) {
+  try {
+    const raw = fs.readFileSync(path.join(hermesHome, ".env"), "utf8");
+    for (const line of raw.split("\n")) {
+      const t = line.trim();
+      if (!t || t.startsWith("#")) continue;
+      const eq = t.indexOf("=");
+      if (eq < 0) continue;
+      if (t.slice(0, eq).trim() !== key) continue;
+      let v = t.slice(eq + 1).trim();
+      if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) {
+        v = v.slice(1, -1);
+      }
+      return v;
+    }
+  } catch { /* .env 不存在或读失败 */ }
+  return "";
+}
+
+export async function resolveProfilePort(hermesHome) {
+  // default profile → 固定 8642
+  const defaultHome = path.join(os.homedir(), ".hermes");
+  if (path.normalize(hermesHome) === path.normalize(defaultHome)) {
+    return 8642;
+  }
+
+  // 优先用 profile 自己 .env 的 API_SERVER_PORT —— hermes gateway 启动时按它绑端口，
+  // bridge 期望端口必须与之一致，否则会路由到别的 profile 的 gateway（跨 profile 串台 bug）。
+  const envPort = Number(readProfileEnvValue(hermesHome, "API_SERVER_PORT"));
+  if (Number.isFinite(envPort) && envPort > 0) {
+    return envPort;
+  }
+
+  const portFile = path.join(hermesHome, "gateway-port.json");
+
+  // 尝试读已持久化的端口
+  try {
+    const raw = fs.readFileSync(portFile, "utf8");
+    const saved = JSON.parse(raw);
+    const savedPort = Number(saved?.port);
+    if (Number.isFinite(savedPort) && savedPort > 0) {
+      const free = await isPortFree(savedPort);
+      if (free) return savedPort;
+      // 端口被占——可能是我们的 gateway，也可能是无关进程。
+      // 按 spec: 端口被占 → 重探新端口（调用侧会在 spawn 前 stop 掉旧 pid）
+    }
+  } catch { /* 文件不存在或解析失败，继续探测 */ }
+
+  // 顺序探测 [8643, 8742]
+  for (let port = PROFILE_PORT_MIN; port <= PROFILE_PORT_MAX; port++) {
+    const free = await isPortFree(port);
+    if (free) {
+      // 持久化
+      try {
+        fs.mkdirSync(hermesHome, { recursive: true });
+        fs.writeFileSync(portFile, JSON.stringify({ port }), "utf8");
+      } catch { /* 写失败不影响返回 */ }
+      return port;
+    }
+  }
+
+  throw new Error(
+    `no available port in range ${PROFILE_PORT_MIN}-${PROFILE_PORT_MAX} for hermes profile gateway`,
+  );
+}
+
+/**
+ * per-profile gateway 生命周期入口。
+ *
+ * @param {string} slug  profile 名（gwId.toLowerCase().slice(0,32)）
+ * @param {string} hermesHome  profile 目录绝对路径
+ * @param {{ mode?: "ensure"|"restart", log?: any, binary?: string }} opts
+ * @returns {Promise<{ ok: boolean, started: boolean, pid?: number, port: number, baseUrl: string, logPath: string, error?: string }>}
+ */
+export async function manageProfileGateway(slug, hermesHome, {
+  mode = "ensure", log, binary,
+} = {}) {
+  const eLog = log?.child ? log.child({ comp: "hermes.profile.gateway", slug }) : log;
+
+  const logPath = path.join(hermesHome, "gateway.log");
+  const pidFile = path.join(hermesHome, "gateway.pid");
+
+  // mode=ensure：先探活已有 gateway（用注册表或 port file 里的端口），健康则 no-op
+  // 这样避免 resolveProfilePort 因 gateway 在运行而错误地重分配端口
+  if (mode === "ensure") {
+    // 先查内存注册表
+    const cached = profileGatewayRegistry.get(slug);
+    if (cached && cached.port) {
+      const cachedBase = `http://127.0.0.1:${cached.port}`;
+      const probe = await probeHealth(cachedBase, { timeoutMs: 1500 });
+      if (probe.ok) {
+        cached.lastActiveAt = new Date();
+        eLog?.info?.("hermes.profile.gateway.ensure.cached_ok", "profile gateway healthy (cached)", { slug, port: cached.port });
+        return { ok: true, started: false, pid: cached.pid, port: cached.port, baseUrl: cachedBase, logPath };
+      }
+    }
+    // 尝试读 port file 里的端口做 health check（gateway 可能在运行但不在注册表里）
+    const portFileRead = (() => {
+      try {
+        const raw = fs.readFileSync(path.join(hermesHome, "gateway-port.json"), "utf8");
+        const saved = JSON.parse(raw);
+        const p = Number(saved?.port);
+        return (Number.isFinite(p) && p > 0) ? p : null;
+      } catch { return null; }
+    })();
+    if (portFileRead) {
+      const savedBase = `http://127.0.0.1:${portFileRead}`;
+      const probe = await probeHealth(savedBase, { timeoutMs: 1500 });
+      if (probe.ok) {
+        eLog?.info?.("hermes.profile.gateway.ensure.portfile_ok", "profile gateway healthy (port file)", { slug, port: portFileRead });
+        profileGatewayRegistry.set(slug, {
+          port: portFileRead, pid: 0, baseUrl: savedBase, lastActiveAt: new Date(),
+        });
+        return { ok: true, started: false, pid: 0, port: portFileRead, baseUrl: savedBase, logPath };
+      }
+    }
+  }
+
+  // 需要 spawn：调 resolveProfilePort 分配（或重新分配）端口
+  let port;
+  try {
+    port = await resolveProfilePort(hermesHome);
+  } catch (err) {
+    return { ok: false, started: false, port: 0, baseUrl: "", logPath,
+      error: err?.message || String(err) };
+  }
+
+  const baseUrl = `http://127.0.0.1:${port}`;
+
+  // 需要 spawn：先检查并发上限，执行 LRU 驱逐
+  await _evictIfNeeded({ eLog });
+
+  const effectiveBinary = binary ?? findHermesBinary();
+  if (!effectiveBinary) {
+    return {
+      ok: false, started: false, port, baseUrl, logPath,
+      error: "hermes 可执行文件没在 PATH 找到（也试了 ~/.local/bin / ~/.hermes/.../venv/bin / /usr/local/bin / /opt/homebrew/bin）。装 hermes-agent 后再 pair。",
+    };
+  }
+
+  // per-profile pid file 路径（不用全局 ~/.hermes/gateway.pid）
+  const readProfilePid = () => {
+    try {
+      const raw = fs.readFileSync(pidFile, "utf8").trim();
+      if (!raw) return null;
+      let pid;
+      if (raw.startsWith("{")) {
+        try { pid = JSON.parse(raw)?.pid; } catch { return null; }
+      } else {
+        pid = parseInt(raw, 10);
+      }
+      if (!Number.isFinite(pid) || pid <= 0) return null;
+      try { process.kill(pid, 0); return pid; } catch { return null; }
+    } catch { return null; }
+  };
+
+  // stop 旧 gateway（用 per-profile pid file 或 lsof）
+  const pidFromFile = readProfilePid();
+  const pidFromPort = findListeningPid(port);
+  const oldPid = pidFromFile ?? pidFromPort;
+  if (oldPid !== null) {
+    eLog?.info?.("hermes.profile.gateway.stop", "stopping old profile gateway", { slug, port, pid: oldPid });
+    try { process.kill(oldPid, "SIGTERM"); } catch {}
+    await waitForPortFree(port, { timeoutMs: 2500 });
+    await waitForPidGone(oldPid, { timeoutMs: 1500 });
+  }
+
+  // spawn 新 gateway
+  eLog?.info?.("hermes.profile.gateway.spawn", "spawning profile gateway", { slug, port, hermesHome });
+  let spawnResult;
+  try {
+    spawnResult = spawnGatewayDetached({
+      binary: effectiveBinary,
+      logPath,
+      log: eLog,
+      env: { HERMES_HOME: hermesHome },
+    });
+  } catch (err) {
+    return {
+      ok: false, started: false, port, baseUrl, logPath,
+      error: `profile gateway spawn 失败: ${err?.message || err}`,
+    };
+  }
+  const { pid, logPath: lp } = spawnResult;
+
+  // 等健康
+  const healthResult = await waitForHealth(baseUrl);
+  if (!healthResult.ok) {
+    return {
+      ok: false, started: true, pid, port, baseUrl, logPath: lp,
+      error: `profile gateway spawn 后 ${HEALTH_POLL_TIMEOUT_MS}ms 内未通过 /health。看日志：${lp}`,
+    };
+  }
+
+  // 更新注册表
+  profileGatewayRegistry.set(slug, {
+    port, pid, baseUrl, lastActiveAt: new Date(),
+  });
+
+  // 启动 idle 回收 timer（第一个 profile gateway spawn 时启动）
+  startIdleCleanupTimer({ log });
+
+  return { ok: true, started: true, pid, port, baseUrl, logPath: lp };
+}
+
+/**
+ * 检查并发上限，必要时 LRU 驱逐最旧 profile。
+ */
+async function _evictIfNeeded({ eLog } = {}) {
+  if (profileGatewayRegistry.size < MAX_PROFILE_GATEWAYS) return;
+
+  // 找 lastActiveAt 最早的
+  let oldestSlug = null;
+  let oldestTime = Infinity;
+  for (const [slug, info] of profileGatewayRegistry.entries()) {
+    const t = info.lastActiveAt.getTime();
+    if (t < oldestTime) {
+      oldestTime = t;
+      oldestSlug = slug;
+    }
+  }
+  if (!oldestSlug) return;
+
+  const info = profileGatewayRegistry.get(oldestSlug);
+  eLog?.info?.("hermes.profile.gateway.lru_evict", "LRU evicting profile gateway", {
+    slug: oldestSlug, port: info.port, last_active: info.lastActiveAt,
+  });
+  await stopGatewayOnPort(info.port, { log: eLog }).catch(() => {});
+  profileGatewayRegistry.delete(oldestSlug);
+}
+
+/**
+ * 找 hermes 可执行文件。优先 PATH，然后常见 venv 位置。
+ * 找不到返回 null（pair 上游打错就行，本模块不退出进程）。
+ */
+export function findHermesBinary() {
+  // 1. which hermes
+  try {
+    const r = spawnSync("which", ["hermes"], { encoding: "utf8" });
+    if (r.status === 0) {
+      const p = String(r.stdout || "").trim().split("\n")[0];
+      if (p && fs.existsSync(p)) return p;
+    }
+  } catch { /* fall through */ }
+  // 2. 用户常见安装位置
+  for (const candidate of [
+    path.join(os.homedir(), ".local", "bin", "hermes"),
+    path.join(os.homedir(), ".hermes", "hermes-agent", "venv", "bin", "hermes"),
+    "/usr/local/bin/hermes",
+    "/opt/homebrew/bin/hermes",
+  ]) {
+    try {
+      if (fs.existsSync(candidate)) return candidate;
+    } catch { /* skip */ }
+  }
+  return null;
+}
+
+/**
+ * lsof 找当前 listen 指定端口的 pid（macOS / Linux 通用）。
+ * 找不到（端口空闲）返回 null。
+ */
+export function findListeningPid(port) {
+  try {
+    const out = execSync(`lsof -nP -iTCP:${port} -sTCP:LISTEN -Fp 2>/dev/null`, {
+      encoding: "utf8", timeout: 3000,
+    });
+    // 输出形如 "p12345\n" — 一行一个 pid 前缀 'p'
+    const m = out.match(/^p(\d+)/m);
+    return m ? Number(m[1]) : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 读 hermes 自家 pid file `~/.hermes/gateway.pid`，覆盖「进程在但 API_SERVER
+ * 没开 → 没监听 :8642 → lsof 找不到」这种场景。
+ *
+ * 文件格式是 JSON：`{"pid": 94014, "kind": "hermes-gateway", "argv": [...]}`，
+ * 早期版本 hermes 写过纯整数，两种都兼容。返回 null = pid 文件不存在 / 解析
+ * 失败 / 进程已死（stale 文件）。
+ */
+export function readHermesGatewayPid() {
+  try {
+    const pidPath = path.join(os.homedir(), ".hermes", "gateway.pid");
+    const raw = fs.readFileSync(pidPath, "utf8").trim();
+    if (!raw) return null;
+    let pid;
+    if (raw.startsWith("{")) {
+      try { pid = JSON.parse(raw)?.pid; } catch { return null; }
+    } else {
+      pid = parseInt(raw, 10);
+    }
+    if (!Number.isFinite(pid) || pid <= 0) return null;
+    // 验证 pid 还活着 —— signal 0 不真发信号，只检查进程
+    try { process.kill(pid, 0); return pid; } catch { return null; }
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 等 pid 真的退出。pid 已经不存在或 process.kill(pid,0) 抛 ESRCH 视为已退。
+ */
+async function waitForPidGone(pid, { timeoutMs = 1500 } = {}) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try { process.kill(pid, 0); } catch { return true; }
+    await new Promise((r) => setTimeout(r, 100));
+  }
+  return false;
+}
+
+/**
+ * GET <baseUrl>/health 一次，timeout 3s。返回 {ok, status, error}。
+ */
+export async function probeHealth(baseUrl, { timeoutMs = 3000 } = {}) {
+  try {
+    const controller = new AbortController();
+    const t = setTimeout(() => controller.abort(), timeoutMs);
+    const res = await fetch(`${baseUrl}/health`, { signal: controller.signal });
+    clearTimeout(t);
+    if (!res.ok) return { ok: false, status: res.status };
+    return { ok: true, status: res.status };
+  } catch (err) {
+    return {
+      ok: false,
+      error: err?.name === "AbortError" ? `timeout ${timeoutMs}ms` : (err?.message || String(err)),
+    };
+  }
+}
+
+/**
+ * 轮询 /health 直到通过或超时。
+ */
+export async function waitForHealth(baseUrl, {
+  timeoutMs = HEALTH_POLL_TIMEOUT_MS,
+  intervalMs = HEALTH_POLL_INTERVAL_MS,
+} = {}) {
+  const deadline = Date.now() + timeoutMs;
+  let last = null;
+  while (Date.now() < deadline) {
+    last = await probeHealth(baseUrl, { timeoutMs: Math.min(2000, intervalMs * 4) });
+    if (last.ok) return last;
+    await new Promise((r) => setTimeout(r, intervalMs));
+  }
+  return last || { ok: false, error: "no probe attempted" };
+}
+
+/**
+ * 等端口完全释放（避免 kill 后立刻 spawn 撞 EADDRINUSE）。
+ */
+export async function waitForPortFree(port, {
+  timeoutMs = PORT_RELEASE_TIMEOUT_MS,
+  intervalMs = PORT_RELEASE_INTERVAL_MS,
+} = {}) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (findListeningPid(port) === null) return true;
+    await new Promise((r) => setTimeout(r, intervalMs));
+  }
+  return false;
+}
+
+/**
+ * 优雅关停 hermes gateway 进程。
+ *
+ * 双源 pid 解析：
+ *   1. `~/.hermes/gateway.pid` —— 覆盖「进程在跑但 API_SERVER 没开 →
+ *      lsof 看不到 :8642」的关键场景。这种 case 下不杀掉旧 pid 直接 spawn
+ *      会撞 hermes 自家的 lock，新进程立刻 "Gateway already running (PID …)"
+ *      退出 → waitForHealth 30s 超时 → bridge 重试 → 用户看到三连"启动失败"。
+ *   2. lsof `:port` —— 兜底，处理 pid file 缺失 / stale 的边缘情况。
+ *
+ * 没找到任何 pid → no-op。
+ */
+export async function stopGatewayOnPort(port, { log } = {}) {
+  const pidFromFile = readHermesGatewayPid();
+  const pidFromPort = findListeningPid(port);
+  // 优先用 pid file —— 它能反映"进程在但没监听端口"这种我们必须处理的状态。
+  // 都有但不一致（极少见）时也用 pid file 的，因为 hermes 自己就靠它判断 lock。
+  const pid = pidFromFile ?? pidFromPort;
+  if (pid === null) {
+    log?.info?.("hermes.gateway.stop.noop", "no gateway pid found", { port });
+    return { stopped: false, alreadyStopped: true };
+  }
+  log?.info?.("hermes.gateway.stop", "sending SIGTERM", {
+    port, pid, source: pidFromFile != null ? "pid_file" : "port_lsof",
+  });
+  try { process.kill(pid, "SIGTERM"); } catch { /* dead already */ }
+  // 双重等待：端口释放 + 进程退出。hermes 进程可能持有 lock 但不 listen 端口
+  // (API_SERVER off 场景)，单靠 waitForPortFree 会立刻成功 → 我们以为 stop
+  // 完成 → spawn 撞 lock。必须等进程真退出。
+  const released = await waitForPortFree(port, { timeoutMs: 2500 });
+  const gone = await waitForPidGone(pid, { timeoutMs: 1500 });
+  if (released && gone) {
+    return { stopped: true, pid, signal: "SIGTERM" };
+  }
+  log?.warn?.("hermes.gateway.stop.force", "SIGTERM 未完成, 升级 SIGKILL", {
+    port, pid, port_released: released, pid_gone: gone,
+  });
+  try { process.kill(pid, "SIGKILL"); } catch { /* dead already */ }
+  await waitForPortFree(port, { timeoutMs: 2500 });
+  await waitForPidGone(pid, { timeoutMs: 1500 });
+  return { stopped: true, pid, signal: "SIGKILL" };
+}
+
+/**
+ * spawn detached `hermes gateway run`，stdout/stderr 重定向到 log 文件。
+ * 子进程被 unref，pair 退出后 gateway 继续跑。
+ *
+ * @param {{ binary: string, logPath: string, env?: NodeJS.ProcessEnv, log?: any }} opts
+ * @returns {{ pid: number, logPath: string }}
+ */
+export function spawnGatewayDetached({ binary, logPath, env, log }) {
+  // 保证 log 目录存在
+  try { fs.mkdirSync(path.dirname(logPath), { recursive: true }); } catch { /* ok */ }
+  // 'a' 追加模式 —— 多次启动日志连续
+  const fd = fs.openSync(logPath, "a");
+  // `--replace`: hermes 自家的"自动替换已存在 gateway"标志（见用户报的错误
+  // 提示："use 'hermes gateway run --replace' to auto-replace"）。我们前面
+  // 已经 stopGatewayOnPort 杀过一遍，--replace 是 TOCTOU 兜底 —— 万一在
+  // kill 和 spawn 之间又被人拉起来（launchd KeepAlive 之类），hermes 自己
+  // 会处理。老版本 hermes 没这个 flag 会报 unknown option 立刻退出，
+  // waitForHealth 30s 后 caller 报错可见。
+  const child = spawn(binary, ["gateway", "run", "--replace"], {
+    detached: true,
+    stdio: ["ignore", fd, fd],
+    env: { ...process.env, ...(env || {}) },
+    cwd: process.env.HOME || "/",
+  });
+  // 让 stdio FD 不阻塞 GC
+  try { fs.closeSync(fd); } catch { /* ok */ }
+  // 监听 error 事件防止 ENOENT 等错误变成 uncaughtException
+  child.on("error", (err) => {
+    log?.warn?.("hermes.gateway.spawn.error", "gateway child process error", {
+      binary, error: err?.message || String(err),
+    });
+  });
+  child.unref();
+  log?.info?.("hermes.gateway.spawn", "spawned detached", {
+    binary, pid: child.pid, log_path: logPath,
+  });
+  return { pid: child.pid, logPath };
+}
+
+/**
+ * 顶层入口 —— 把"配置改了，请重启 gateway"自动化。
+ *
+ * 输入 `mode`：
+ *   - "ensure"   gateway 已通过 /health 就不动；不通就 spawn
+ *   - "restart"  无条件 stop + spawn（配置实际有变化时）
+ *
+ * 返回 { ok, started, restarted, alreadyOk, error, logPath, pid }
+ */
+export async function manageHermesGateway({
+  baseUrl, mode = "ensure", logPath, log, healthTimeoutMs,
+} = {}) {
+  const port = Number(new URL(baseUrl).port || "8642");
+  const eLog = log?.child ? log.child({ comp: "hermes.gateway" }) : log;
+  const effectiveLog = logPath || path.join(os.tmpdir(), "hermes-gateway.log");
+
+  // mode=ensure：先 probe，已经通就返回
+  if (mode === "ensure") {
+    const pre = await probeHealth(baseUrl);
+    if (pre.ok) {
+      eLog?.info?.("hermes.gateway.ensure.already_ok", "gateway healthy", { baseUrl });
+      return { ok: true, alreadyOk: true, started: false, restarted: false };
+    }
+  }
+
+  const binary = findHermesBinary();
+  if (!binary) {
+    return {
+      ok: false, started: false, restarted: false,
+      error: "hermes 可执行文件没在 PATH 找到（也试了 ~/.local/bin / ~/.hermes/.../venv/bin / /usr/local/bin / /opt/homebrew/bin）。装 hermes-agent 后再 pair。",
+    };
+  }
+
+  // 无论 mode 一律先 stop —— mode=ensure 走到这说明 probe 已经失败，gateway
+  // 要么没起、要么进程在但没 listen :8642（典型 API_SERVER_ENABLED=false 状态）。
+  // 后者 stopGatewayOnPort 通过 pid file 也能找到并杀掉；前者就是 no-op。
+  // 不 stop 直接 spawn 会撞 hermes 自家 lock → "Gateway already running" → 死循环。
+  const stopResult = await stopGatewayOnPort(port, { log: eLog });
+
+  // spawn 新进程
+  const { pid, logPath: lp } = spawnGatewayDetached({
+    binary, logPath: effectiveLog, log: eLog,
+  });
+
+  // 轮询 /health。healthTimeoutMs 可由调用方收短（配对场景不该为等 gateway
+  // 健康而阻塞后续步骤 —— gateway 已 detached spawn，会在后台继续起来）。
+  const effectiveHealthTimeout = healthTimeoutMs || HEALTH_POLL_TIMEOUT_MS;
+  const final = await waitForHealth(baseUrl, { timeoutMs: effectiveHealthTimeout });
+  if (final.ok) {
+    return {
+      ok: true, started: true,
+      restarted: !!(stopResult && stopResult.stopped),
+      pid, logPath: lp,
+      stoppedOldPid: stopResult?.pid,
+    };
+  }
+  // 启动了但探活超时 —— 多半是配置错（API key 缺 / venv 损坏），让用户看 log。
+  // started=true 表示进程已 spawn（detached），只是没在窗口内通过 /health；
+  // 调用方据此区分「后台启动中/未配置模型」(软) 与「连进程都没起」(硬)。
+  return {
+    ok: false, started: true, healthTimedOut: true,
+    restarted: !!(stopResult && stopResult.stopped),
+    pid, logPath: lp,
+    error: `gateway 已 spawn 但 ${effectiveHealthTimeout}ms 内未通过 /health。看启动日志：${lp}`,
+  };
+}